1Haiku Git Repositories
2======================
3
4Haiku uses Git for source control, combined with Gerrit for review of code changes.
5
6Most of the operating system sources are stored in a single repository at http://cgit.haiku-os.org/haiku .
7
8Another repository at http://cgit.haiku-os.org/buildtools contains the build tools, that is, gcc,
9binutils, and Jam, which are maintained by Haiku developers.
10
11`Additional repositories <https://github.com/orgs/haiku/repositories>`_ are hosed on GitHub.
12
13Finally, some pre-compiled packages are downloaded during the build, these are built using
14Haikuporter from `recipes available here <https://github.com/orgs/haikuports/repositories>`_.
15
16Getting the sourcecode
17----------------------
18
19 * https://www.haiku-os.org/guides/building/get-source-git
20
21Sending change reviews
22----------------------
23
24 * https://dev.haiku-os.org/wiki/CodingGuidelines/SubmittingPatches
25 * https://review.haiku-os.org/Documentation/user-upload.html
26
27Source tree organization
28------------------------
29
30The source tree is organized so you can easily find what you look for. If you're already familiar
31with Haiku, you will notice that the source directory generally mirrors the way the filesystem in
32Haiku is organized.
33
34At the top level, things that need to be "built" in some way are put in the ``src`` directory.
35For example, the "data" folder at the root contains files that are used as-is in the disk image,
36while "src/data" contain files that need to be compild or converted to different formats, such as
37the MIME database.
38
39* src - All files that have to be built
40
41  * add-ons - Everything that will be installed to /boot/system/add-ons: kernel drivers, media codecs, translators, ���
42  * apps - GUI applications that are not preferences
43  * bin - Command-line applications
44  * build - Files to allow using the Haiku buildtools on non-Haiku platforms
45  * data - Data files of any type: icons, MIME database, ���
46  * kits - The public C++ API of Haiku: libbe, libmedia, libgame, ���
47  * libs - Static and shared libraries used by Haiku applications
48  * preferences - The preference applications
49  * servers - The system servers: app_server, input_server, net_server, ���
50  * system - The low-level system that makes Haiku tick
51
52    * boot - The bootloaders for all supported platforms
53    * glue - The "glue code" that makes shared libraries execute their constructors and destructors, and programs start their execution at ``main()``
54    * kernel - The kernel and all of its core services
55    * ldscripts - Linker scripts for building various parts of Haiku
56    * libnetwork - Files for building libnetwork.so, including the POSIX/BSD socket implementation and some extensions to it, as well as the DNS resolver
57    * libroot - Files for building libroot.so, including the standard C and POSIX library implementation
58    * runtime_loader: The special application that knows how to load and run other applications from ELF executable files
59
60  * tests - This more or less mirrors the main source tree layout, and contains tests and debugging tools for each component. Some of the tests are run using cppunit, other can be run manually.
61  * tools - Tools that can be built on non-Haiku platforms. Either needed for compiling Haiku itself, or otherwise useful outside of Haiku
62
63* headers - All shared, private and public headers
64
65  * build - Compatibility headers for building Haiku code on non-Haiku systems
66  * compatibility - Compatbility layers allowing to build BSD and GNU code to run on Haiku
67  * config - Platform-specific configuration, definition of standard types that can be used in other places
68  * cpp - The C++ standard library headers (only for gcc2, for later gcc versions this is provided by the gcc package)
69  * glibc - Headers from glibc, for configuration and definition of some glibc specific functions
70  * libs - Headers for the libraries found in src/libs
71  * os - The public headers that define the Haiku API
72  * posix - The POSIX APIs supported by Haiku
73  * private - Private headers that are shared between haiku components, including work-in-progress APIs that may become public in the future
74  * tools - Headers for various tools and utilities
75
76* docs - Documentation
77
78  * develop - Internal documentation for developers working on Haiku itself (this is what you are reading now)
79  * user - `API reference <https://api.haiku-os.org>`
80  * Some other miscellaneous documentation
81
82* build - Build files
83
84  * jam - Jam rules used by the Haiku build, defining how to build an application, a library, a disk image, ���
85  * config_headers - Configurable headers for enabling various debug features
86  * scripts - Various scripts used by the Haiku build process
87
88* 3rd_party - Developers custom files. Used for various side projects from Haiku developers, useful personal scripts, and integration with other tools and projects such as virtualization software
89
90Managing GCC and binutils updates using vendor branches
91-------------------------------------------------------
92
93The buidtools repository uses vendor branches. This concept originates from `the SVN Book <https://svnbook.red-bean.com/en/1.8/svn.advanced.vendorbr.html>`_
94but applies just as well to Git. This organization allows to clearly separate the imported code
95from upstream, and the changes we have made to it.
96
97The idea is to import all upstream changes in a dedicated branch (there are currently two, called
98vendor-gcc and vendor-binutils). These branches contains the sources of gcc and binutils as
99distributed by the GNU project, without any Haiku changes.
100
101The master branch can then merge new versions from the vendor branches. This allows to use Git
102conflict resolution to make sure our patches are correctly ported from one version to the next.
103
104It also makes it easy to compare the current state of our sourcecode with the upstream code, for
105example to extract patches that could be upstreamed.
106
107How to import upstream binutils changes
108.......................................
109
110Here is an example of the process used to update to a new version of binutils:
111
112.. code-block:: bash
113
114    git checkout vendor-binutils          # Move to the branch containing binutils
115    git rm -rf binutils ; rm -rf binutils # Delete the existing version of binutils
116    wget http://.../binutils-2.36.tar.xz  # Download the latest version
117    tar xf binutils-2.36.tar.xz           # Extract the new binutils version
118    mv binutils-2.36 binutils             # Move the extracted files to the right place
119    git add -f binutils                   # Add the new files to git
120    git commit -m "import binutils 2.36"  # Commit the files in the vendor branch
121    git push origin vendor-binutils       # You can push this directly to the branch
122
123Now this can easily be merged into the master branch:
124
125.. code-block:: bash
126
127    git checkout master
128    git merge vendor-binutils
129
130Review and fix the conflicts, if any, then push the changes for review on Gerrit.
131
132How to import upstream gcc changes
133..................................
134
135Here is an example of the process used to update to a new version of binutils:
136
137.. code-block:: bash
138
139    git checkout vendor-gcc               # Move to the branch containing binutils
140    git rm -rf gcc ; rm -rf gcc           # Delete the existing version of binutils
141    wget http://.../gcc-13.2.0.tar.xz     # Download the latest version
142    tar xf gcc-13.2.0.tar.xz              # Extract the new binutils version
143    mv gcc-13.2.0 gcc                     # Move the extracted files to the right place
144    pushd gcc
145    ./contrib/download_prerequisites      # Download the required gmp, isl, mpfr and mpc dependencies
146    rm gmp gmp-6.2.1.tar.bz2              # Remove gmp download and symbolic link
147    mv gmp-6.2.1 gmp                      # Move the downloaded gmp dependency in place
148    rm isl isl-0.24.tar.bz2
149    mv isl-0.24 isl
150    rm mpc mpc-1.2.1.tar.gz
151    mv mpc-1.2.1 mpc
152    rm mpfr mpfr-4.1.0.tar.bz2
153    mv mpfr-4.1.0 mpfr
154    popd
155    git add -f gcc                        # Add the new files to git
156    git commit -m "import gcc 13.2.0"     # Commit the files in the vendor branch
157    git push origin vendor-binutils       # You can push this directly to the branch
158
159Now this can easily be merged into the master branch:
160
161.. code-block:: bash
162
163    git checkout master
164    git merge vendor-binutils
165
166Review and fix the conflicts, if any, then push the changes for review on Gerrit.
167
168Comparing our code with upstream
169................................
170
171Comparing the two versions is easy because you can refer to them by branch names:
172
173.. code-block:: bash
174
175    git diff vendor-binutils master -- binutils
176