chiark / gitweb /
i18n: dgit: mark some messages (2)
[dgit.git] / dgit-user.7.pod
1 =head1 NAME
2
3 dgit-user - making and sharing changes to Debian packages, with git
4
5 =head1 INTRODUCTION
6
7 dgit lets you fetch the source code to every package on your
8 system
9 as if your distro used git to maintain all of it.
10
11 You can then edit it,
12 build updated binary packages (.debs)
13 and install and run them.
14 You can also share your work with others.
15
16 This tutorial gives some recipes and hints for this.
17 It assumes you have basic familiarity with git.
18 It does not assume any initial familiarity with
19 Debian's packaging processes.
20
21 If you are a package maintainer within Debian; a DM or DD;
22 and/or a sponsee:
23 this tutorial is not for you.
24 Try L<dgit-nmu-simple(7)>, L<dgit-maint-*(7)>,
25 or L<dgit(1)> and L<dgit(7)>.
26
27 =head1 SUMMARY
28
29 (These runes will be discussed later.)
30
31 =over 4
32
33     % dgit clone glibc jessie,-security
34     % cd glibc
35     % curl 'https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=28250;mbox=yes;msg=89' | patch -p1 -u
36     % git commit -a -m 'Fix libc lost output bug'
37     % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit
38     % mk-build-deps --root-cmd=sudo --install
39     % dpkg-buildpackage -uc -b
40     % sudo dpkg -i ../libc6_*.deb
41
42 =back
43
44 Occasionally:
45
46 =over 4
47
48     % git clean -xdf
49     % git reset --hard
50
51 =back
52
53 Later:
54
55 =over 4
56
57     % cd glibc
58     % dgit pull jessie,-security
59     % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit
60     % dpkg-buildpackage -uc -b
61     % sudo dpkg -i ../libc6_*.deb
62
63 =back
64
65 =head1 FINDING THE RIGHT SOURCE CODE - DGIT CLONE
66
67 =over 4
68
69     % dgit clone glibc jessie,-security
70     % cd glibc
71
72 =back
73
74 dgit clone needs to be told the source package name
75 (which might be different to the binary package name,
76 which was the name you passed to "apt-get install")
77 and the codename or alias of the Debian release
78 (this is called the "suite").
79
80 =head2 Finding the source package name
81
82 For many packages, the source package name is obvious.
83 Otherwise, if you know a file that's in the package,
84 you can look it up with dpkg:
85
86 =over 4
87
88     % dpkg -S /lib/i386-linux-gnu/libc.so.6 
89     libc6:i386: /lib/i386-linux-gnu/libc.so.6
90     % dpkg -s libc6:i386
91     Package: libc6
92     Status: install ok installed
93     ...
94     Source: glibc
95
96 =back
97
98 (In this example,
99 libc6 is a "multi-arch: allowed" package,
100  which means that it exists in several different builds
101  for different architectures.
102 That's where C<:i386> comes from.)
103
104 =head2 Finding the Debian release (the "suite")
105
106 Internally,
107 Debian (and derived) distros normally refer to their releases by codenames.
108 Debian also has aliases which refer to the current stable release etc.
109 So for example, at the time of writing
110 Debian C<jessie> (Debian 8) is Debian C<stable>; and
111 the current version of Ubuntu is C<yakkety> (Yakkety Yak, 16.10).
112 You can specify either
113 the codename C<jessie> or the alias C<stable>.
114 If you don't say, you get C<sid>,
115 which is Debian C<unstable> - the main work-in progress branch.
116
117 If you don't know what you're running, try this:
118
119 =over 4
120
121     % grep '^deb' /etc/apt/sources.list
122     deb http://the.earth.li/debian/ jessie main non-free contrib
123     ...
124     %
125
126 =back
127
128 For Debian, you should add C<,-security>
129 to the end of the suite name,
130 unless you're on unstable or testing.
131 Hence, in our example
132 C<jessie> becomes C<jessie,-security>.
133 (Yes, with a comma.)
134
135 =head1 WHAT DGIT CLONE PRODUCES
136
137 =head2 What branches are there
138
139 dgit clone will give you a new working tree,
140 and arrange for you to be on a branch named like
141 C<dgit/jessie,-security> (yes, with a comma in the branch name).
142
143 For each release (like C<jessie>)
144 there is a tracking branch for the contents of the archive, called
145 C<remotes/dgit/dgit/jessie>
146 (and similarly for other suites).  This can be updated with
147 C<dgit fetch jessie>.
148 This, the I<remote suite branch>,
149 is synthesized by your local copy of dgit.
150 It is fast forwarding.
151
152 Debian separates out the security updates, into C<*-security>.
153 Telling dgit C<jessie,-security> means that it should include 
154 any updates available in C<jessie-security>.
155 The comma notation is a request to dgit to track jessie,
156 or jessie-security if there is an update for the package there.
157
158 (You can also dgit fetch in a tree that wasn't made by dgit clone.
159 If there's no C<debian/changelog>
160 you'll have to supply a C<-p>I<package> option to dgit fetch.)
161
162 =head2 What kind of source tree do you get
163
164 If the Debian package is based on some upstream release,
165 the code layout should be like the upstream version.
166 You should find C<git grep> helpful to find where to edit.
167
168 The package's Debian metadata and the scripts for building binary
169 packages are under C<debian/>.
170 C<debian/control>, C<debian/changelog> and C<debian/rules> are the
171 starting points.
172 The Debian Policy Manual has most of the in-depth
173 technical details.
174
175 For many Debian packages,
176 there will also be some things in C<debian/patches/>.
177 It is best to ignore these.
178 Insofar as they are relevant
179 the changes there will have been applied to the actual files,
180 probably by means of actual comments in the git history.
181 The contents of debian/patches are ignored
182 when building binaries
183 from dgitish git branches.
184
185 (For Debian afficionados:
186 the git trees that come out of dgit are
187 "patches-applied packaging branches
188 without a .pc directory".)
189
190 =head2 What kind of history you get
191
192 If you're lucky, the history will be a version of,
193 or based on,
194 the Debian maintainer's own git history,
195 or upstream's git history.
196
197 But for many packages the real git history
198 does not exist,
199 or has not been published in a dgitish form.
200 So you may find that the history is a rather short
201 history invented by dgit.
202
203 dgit histories often contain automatically-generated commits,
204 including commits which make no changes but just serve
205 to make a rebasing branch fast-forward.
206 This is particularly true of
207 combining branches like
208 C<jessie,-security>.
209
210 If the package maintainer is using git then
211 after dgit clone
212 you may find that there is a useful C<vcs-git> remote
213 referring to the Debian package maintainer's repository
214 for the package.
215 You can see what's there with C<git fetch vcs-git>.
216 But use what you find there with care:
217 Debian maintainers' git repositories often have
218 contents which are very confusing and idiosyncratic.
219 In particular, you may need to manually apply the patches
220 that are in debian/patches before you do anything else!
221
222 =head1 BUILDING
223
224 =head2 Always commit before building
225
226 =over 4
227
228     % wget 'https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=28250;mbox=yes;msg=89' | patch -p1 -u
229     % git commit -a -m 'Fix libc lost output bug'
230
231 =back
232
233 Debian package builds are often quite messy:
234 they may modify files which are also committed to git,
235 or leave outputs and temporary files not covered by C<.gitignore>.
236
237 If you always commit,
238 you can use
239
240 =over 4
241
242     % git clean -xdf
243     % git reset --hard
244
245 =back
246
247 to tidy up after a build.
248 (If you forgot to commit, don't use those commands;
249 instead, you may find that you can use C<git add -p>
250 to help commit what you actually wanted to keep.)
251
252 These are destructive commands which delete all new files
253 (so you B<must> remember to say C<git add>)
254 and throw away edits to every file
255 (so you B<must> remember to commit).
256
257 =head2 Update the changelog (at least once) before building
258
259 =over 4
260
261     % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit
262
263 =back
264
265 The binaries you build will have a version number which ultimately
266 comes from the C<debian/changelog>.
267 You want to be able to tell your
268 binaries apart from your distro's.
269
270 So you should update C<debian/changelog>
271 to add a new stanza at the top,
272 for your build.
273
274 This rune provides an easy way to do this.
275 It adds a new changelog
276 entry with an uninformative message and a plausible version number
277 (containing a bit of your git commit id).
278
279 If you want to be more sophisticated,
280 the package C<dpkg-dev-el> has a good Emacs mode
281 for editing changelogs.
282 Alternatively, you could edit the changelog with another text editor,
283 or run C<dch> or C<gbp dch> with different options.
284 Choosing a good version number is slightly tricky and
285 a complete treatment is beyond the scope of this tutorial.
286
287 =head2 Actually building
288
289 =over 4
290
291     % mk-build-deps --root-cmd=sudo --install
292     % dpkg-buildpackage -uc -b
293
294 =back
295
296 dpkg-buildpackage is the primary tool for building a Debian source
297 package.
298 C<-uc> means not to pgp-sign the results.
299 C<-b> means build all binary packages,
300 but not to build a source package.
301
302 =head2 Using sbuild
303
304 You can build in an schroot chroot, with sbuild, instead of in your
305 main environment.  (sbuild is used by the Debian build daemons.)
306
307 =over 4
308
309     % git clean -xdf
310     % sbuild -c jessie -A --no-clean-source \
311              --dpkg-source-opts='-Zgzip -z1 --format=1.0 -sn'
312
313 =back
314
315 Note that this will seem to leave a "source package"
316 (.dsc and .tar.gz)
317 in the parent directory,
318 but that source package should not be used.
319 It is likely to be broken.
320 For more information see Debian bug #868527.
321
322 =head1 INSTALLING
323
324 =head2 Debian Jessie or older
325
326 =over 4
327
328     % sudo dpkg -i ../libc6_*.deb
329
330 =back
331
332 You can use C<dpkg -i> to install the
333 .debs that came out of your package.
334
335 If the dependencies aren't installed,
336 you will get an error, which can usually be fixed with
337 C<apt-get -f install>.
338
339 =head2 Debian Stretch or newer
340
341 =over 4
342
343     % sudo apt install ../libc6_*.deb
344
345 =back
346
347 =head1 Multiarch
348
349 If you're working on a library package and your system has multiple
350 architectures enabled,
351 you may see something like this:
352
353 =over 4
354
355     dpkg: error processing package libpcre3-dev:amd64 (--configure):
356      package libpcre3-dev:amd64 2:8.39-3~3.gbp8f25f5 cannot be configured because libpcre3-dev:i386 is at a different version (2:8.39-2)
357
358 =back
359
360 The multiarch system used by Debian requires each package which is
361 present for multiple architectures to be exactly the same across
362 all the architectures for which it is installed.
363
364 The proper solution
365 is to build the package for all the architectures you
366 have enabled.
367 You'll need a chroot for each of the secondary architectures.
368 This is somewhat tiresome,
369 even though Debian has excellent tools for managing chroots.
370 C<sbuild-debian-developer-setup> from the package of the same name
371 and C<sbuild-createchroot> from the C<sbuild> package are
372 good starting points.
373
374 Otherwise you could deinstall the packages of interest
375 for those other architectures
376 with something like C<dpkg --remove libpcre3:i386>.
377
378 If neither of those are an option,
379 your desperate last resort is to try
380 using the same version number
381 as the official package for your own package.
382 (The version is controlled by C<debian/changelog> - see above).
383 This is not ideal because it makes it hard to tell what is installed,
384 and because it will mislead and confuse apt.
385
386 With the "same number" approach you may still get errors like
387
388 =over 4
389
390 trying to overwrite shared '/usr/include/pcreposix.h', which is different from other instances of package libpcre3-dev
391
392 =back
393
394 but passing C<--force-overwrite> to dpkg will help
395 - assuming you know what you're doing.
396
397 =head1 SHARING YOUR WORK
398
399 The C<dgit/jessie,-security> branch (or whatever) is a normal git branch.
400 You can use C<git push> to publish it on any suitable git server.
401
402 Anyone who gets that git branch from you
403 will be able to build binary packages (.deb)
404 just as you did.
405
406 If you want to contribute your changes back to Debian,
407 you should probably send them as attachments to 
408 an email to the
409 L<Debian Bug System|https://bugs.debian.org/>
410 (either a followup to an existing bug, or a new bug).
411 Patches in C<git-format-patch> format are usually very welcome.
412
413 =head2 Source packages
414
415 The
416 git branch is not sufficient to build a source package
417 the way Debian does.
418 Source packages are somewhat awkward to work with.
419 Indeed many plausible git histories or git trees
420 cannot be converted into a suitable source package.
421 So I recommend you share your git branch instead.
422
423 If a git branch is not enough, and
424 you need to provide a source package
425 but don't care about its format/layout
426 (for example because some software you have consumes source packages,
427 not git histories)
428 you can use this recipe to generate a C<3.0 (native)>
429 source package, which is just a tarball
430 with accompanying .dsc metadata file:
431
432 =over 4
433
434     % echo '3.0 (native)' >debian/source/format
435     % git commit -m 'switch to native source format' debian/source/format
436     % dgit -wgf build-source
437
438 =back
439
440 If you need to provide a good-looking source package,
441 be prepared for a lot more work.
442 You will need to read much more, perhaps starting with
443 L<dgit-nmu-simple(7)>,
444 L<dgit-sponsorship(7)> or
445 L<dgit-maint-*(7)>
446
447 =head1 SEE ALSO
448
449 dgit(1), dgit(7)