| 1 |
-*- Outline -*- |
| 2 |
|
| 3 |
Read this file if you are a Debian Developer or would like to become |
| 4 |
one, or if you would like to create your own binary packages of GCC. |
| 5 |
|
| 6 |
* Overview |
| 7 |
|
| 8 |
From the GCC sources, Debian currently builds 3 source packages and |
| 9 |
almost 100 binary packages, using a single set of build scripts. The |
| 10 |
3 source packages are: |
| 11 |
|
| 12 |
gcc-x.y: C, C++, Fortran, Objective-C and Objective-C++, plus many |
| 13 |
common libraries like libssp and libgcc. |
| 14 |
gnat-x.y: Ada. |
| 15 |
|
| 16 |
The way we do this is quite peculiar, so listen up :) |
| 17 |
|
| 18 |
When we build from the gcc-x.y source package, we produce, among many |
| 19 |
others, a gcc-x.y-source binary package that contains the pristine |
| 20 |
upstream tarball and some Debian-specific patches. Any user can then |
| 21 |
install this package on their Debian system, and will have the full |
| 22 |
souces in /usr/src/gcc-x.y/gcc-<timestamp>.tar.bz2, along with the |
| 23 |
Makefile snippets that unpack and patch them. |
| 24 |
|
| 25 |
The intended use for this package is twofold: (a) allow users to build |
| 26 |
their own cross-compilers, and (b) build the other packages like |
| 27 |
gnat-x.y. |
| 28 |
|
| 29 |
- gcc-x.y requires only a C compiler to build and produces C, C++, |
| 30 |
Fortran, Go and Objective-C compilers and libraries. It also |
| 31 |
produces the binary package gcc-x.y-source containing all the |
| 32 |
sources and patches in a tarball. |
| 33 |
|
| 34 |
- gnat-x.y build-depends on gcc-x.y-source and an Ada compiler. It |
| 35 |
does not even have an .orig.tar.bz2 package; it is a Debian native |
| 36 |
package. |
| 37 |
|
| 38 |
The benefits of this split are many: |
| 39 |
|
| 40 |
- bootstrapping a subset of languages is much faster than |
| 41 |
bootstrapping all languages and libraries (which can take a full |
| 42 |
week on slow architectures like mips or arm) |
| 43 |
|
| 44 |
- the language maintainers don't have to wait for each other |
| 45 |
|
| 46 |
- for new ports, the absence of a port of, say, gnat-x.y does not |
| 47 |
block the porting of gcc-x.y. |
| 48 |
|
| 49 |
gcc-x.y-source is also intended for interested users to build |
| 50 |
cross-compiler packages. Debian cannot provide all possible |
| 51 |
cross-compiler packages (i.e. all possible host, target, language and |
| 52 |
library combinations), so instead tries to facilitate building them. |
| 53 |
|
| 54 |
* The build sequence |
| 55 |
|
| 56 |
As for all other Debian packages, you build GCC by calling |
| 57 |
debian/rules. |
| 58 |
|
| 59 |
The first thing debian/rules does it to look at the top-most entry in |
| 60 |
debian/changelog: this tells it which source package it is building. |
| 61 |
For example, if the first entry in debian/changelog reads: |
| 62 |
|
| 63 |
gnat-6 (6.2.0-1) unstable; urgency=low |
| 64 |
|
| 65 |
* Upload as gnat-6. |
| 66 |
|
| 67 |
-- Ludovic Brenta <[email protected]> Tue, 26 Jun 2007 00:26:42 +0200 |
| 68 |
|
| 69 |
then, debian/rules will build only the gnat binary packages. |
| 70 |
|
| 71 |
The second step is to build debian/control from debian/control.m4 and |
| 72 |
a complex set of rules specified in debian/rules.conf. The resulting |
| 73 |
control file contains only the binary packages to be built. |
| 74 |
|
| 75 |
The third step is to select which patches to apply (this is done in |
| 76 |
debian/rules.defs), and then to apply the selected patches (see |
| 77 |
debian/rules.patch). The result of this step is a generated |
| 78 |
debian/patches/series file for use by quilt. |
| 79 |
|
| 80 |
The fourth step is to unpack the GCC source tarball. This tarball is |
| 81 |
either in the build directory (when building gcc-x.y), or in |
| 82 |
/usr/src/gcc-x.y/gcc-x.y.z.tar.xz (when building the other source |
| 83 |
packages). |
| 84 |
|
| 85 |
The fifth step is to apply all patches to the unpacked sources with |
| 86 |
quilt. |
| 87 |
|
| 88 |
The sixth step is to create a "build" directory, cd into it, call |
| 89 |
../src/configure, and bootstrap the compiler and libraries selected. |
| 90 |
This is in debian/rules2. |
| 91 |
|
| 92 |
The seventh step is to call "make install" in the build directory: |
| 93 |
this installs the compiler and libraries into debian/tmp |
| 94 |
(i.e. debian/tmp/usr/bin/gcc, etc.) |
| 95 |
|
| 96 |
The eighth step is to run the GCC test suite. This actually takes at |
| 97 |
least as much time as bootstrapping, and you can disable it by setting |
| 98 |
WITHOUT_CHECK to "yes" in the environment. |
| 99 |
|
| 100 |
The ninth step is to build the binary packages, i.e. the .debs. This |
| 101 |
is done by a set of language- and architecture-dependent Makefile |
| 102 |
snippets in the debian/rules.d/ directory, which move files from the |
| 103 |
debian/tmp tree to the debian/<package> trees. |
| 104 |
|
| 105 |
* Making your own packages |
| 106 |
|
| 107 |
In this example, we will build our own gnat-x.y package. |
| 108 |
|
| 109 |
1) Install gcc-x.y-source, which contains the real sources: |
| 110 |
|
| 111 |
# aptitude install gcc-x.y-source |
| 112 |
|
| 113 |
2) Create a build directory: |
| 114 |
|
| 115 |
$ mkdir gnat-x.y-x.y.z; cd gnat-x.y-x.y.z |
| 116 |
|
| 117 |
3) Checkout from Subversion: |
| 118 |
|
| 119 |
$ svn checkout svn://svn.debian.org/gcccvs/branches/sid/gcc-x.y/debian |
| 120 |
|
| 121 |
4) Edit the debian/changelog file, adding a new entry at the top that |
| 122 |
starts with "gnat-x.y". |
| 123 |
|
| 124 |
5) Generate the debian/control file, adjusted for gnat: |
| 125 |
|
| 126 |
$ debian/rules control |
| 127 |
|
| 128 |
8) Build: |
| 129 |
|
| 130 |
$ dpkg-buildpackage |
| 131 |
|
| 132 |
* Hints |
| 133 |
|
| 134 |
You need a powerful machine to build GCC. The larger, the better. |
| 135 |
The build scripts take advantage of as many CPU threads as are |
| 136 |
available in your box (for example: 2 threads on a dual-core amd64; 4 |
| 137 |
threads on a dual-core POWER5; 32 threads on an 8-core UltraSPARC T1, |
| 138 |
etc.). |
| 139 |
|
| 140 |
If you have 2 GB or more of physical RAM, you can achieve maximum |
| 141 |
performance by building in a tmpfs, like this: |
| 142 |
|
| 143 |
1) as root, create the new tmpfs: |
| 144 |
|
| 145 |
# mount -t tmpfs -o size=1280m none /home/lbrenta/src/debian/ram |
| 146 |
|
| 147 |
By default, the tmpfs will be limited to half your physical RAM. The |
| 148 |
beauty of it is that it only consumes as much physical RAM as |
| 149 |
necessary to hold the files in it; deleting files frees up RAM. |
| 150 |
|
| 151 |
2) As your regular user, create the working directory in the tmpfs |
| 152 |
|
| 153 |
$ cp --archive ~/src/debian/gcc-x.y-x.y.z ~/src/debian/ram |
| 154 |
|
| 155 |
3) Build in there. On my dual-core, 2 GHz amd64, it takes 34 minutes |
| 156 |
to build gnat, and the tmpfs takes 992 MiB of physical RAM but |
| 157 |
exceeds 1 GiB during the build. |
| 158 |
|
| 159 |
Note that the build process uses a lot of temporary files. Your $TEMP |
| 160 |
directory should therefore also be in a ram disk. You can achieve |
| 161 |
that either by mounting it as tmpfs, or by setting TEMP to point to |
| 162 |
~/src/debian/ram. |
| 163 |
|
| 164 |
Also note that each thread in your processor(s) will run a compiler in |
| 165 |
it and use up RAM. Therefore your physical memory should be: |
| 166 |
|
| 167 |
Physical_RAM >= 1.2 + 0.4 * Threads (in GiB) |
| 168 |
|
| 169 |
(this is an estimate; your mileage may vary). If you have less |
| 170 |
physical RAM than recommended, reduce the number of threads allocated |
| 171 |
to the build process, or do not use a tmpfs to build. |
| 172 |
|
| 173 |
* Patching GCC |
| 174 |
|
| 175 |
Debian applies a large number of patches to GCC as part of the build |
| 176 |
process. It uses quilt but the necessary debian/patches/series is not |
| 177 |
part of the packaging scripts; instead, "debian/rules patch" generates |
| 178 |
this file by looking at debian/control (which is itself generated!), |
| 179 |
debian/changelog and other files. Then it applies all the patches. |
| 180 |
At this point, you can use quilt as usual: |
| 181 |
|
| 182 |
$ cd ~/src/debian/gcc-x.y |
| 183 |
$ export QUILT_PATCHES=$PWD/debian/patches |
| 184 |
$ quilt series |
| 185 |
|
| 186 |
If you add new patches, remember to add them to the version control |
| 187 |
system too. |
| 188 |
|
| 189 |
-- |
| 190 |
Ludovic Brenta, 2012-04-02. |