Debian Codegraph @

debian/README.maintainers

raw
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.