chiark / gitweb /
dgit-nmu-simple(7): Cannot yet use DELAYED
[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
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
34     % cd glibc
35     % wget '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     % sudo apt-get build-dep glibc
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
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
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 and the codename or alias of the Debian release
77 (this is called the "suite").
78
79 =head2 Finding the source package name
80
81 For many packages, the source package name is obvious.
82 Otherwise, if you know a file that's in the package,
83 you can look it up with dpkg:
84
85 =over 4
86
87     % dpkg -S /lib/i386-linux-gnu/libc.so.6 
88     libc6:i386: /lib/i386-linux-gnu/libc.so.6
89     % dpkg -s libc6:i386
90     Package: libc6
91     Status: install ok installed
92     ...
93     Source: glibc
94
95 =back
96
97 (In this example,
98 libc6 is a "multi-arch: allowed" package,
99  which means that it exists in several different builds
100  for different architectures.
101 That's where C<:i386> comes from.)
102
103 =head2 Finding the Debian release (the "suite")
104
105 Internally,
106 Debian (and derived) distros normally refer to their releases by codenames.
107 Debian also has aliases which refer to the current stable release etc.
108 So for example, at the time of writing
109 Debian C<jessie> (Debian 8) is Debian C<stable>; and
110 the current version of Ubuntu is C<yakkety> (Yakkety Yak, 16.10).
111 You can specify either
112 the codename C<jessie> or the alias C<stable>.
113 If you don't say, you get C<sid>,
114 which is Debian C<unstable> - the main work-in progress branch.
115
116 If you don't know what you're running, try this:
117
118 =over 4
119
120     % grep '^deb' /etc/apt/sources.list
121     deb http://the.earth.li/debian/ jessie main non-free contrib
122     ...
123     %
124
125 =back
126
127 =head1 WHAT DGIT CLONE PRODUCES
128
129 =head2 What branches are there
130
131 dgit clone will give you a new working tree,
132 and arrange for you to be on a branch like
133 C<dgit/jessie>.
134
135 There is a tracking branch for the contents of the archive, called
136 C<remotes/dgit/dgit/jessie>
137 (and similarly for other suites).  This can be updated with
138 C<dgit fetch jessie>.
139 This, the I<remote suite branch>,
140 is synthesized by your local copy of dgit.
141 It is fast forwarding.
142
143 (You can also dgit fetch in a tree that wasn't made by dgit clone.
144 If there's no C<debian/changelog>
145 you'll have to supply a C<-p>I<package> option to dgit fetch.)
146
147 =head2 What kind of source tree do you get
148
149 If the Debian package is based on some upstream release,
150 the code layout should be like the upstream version.
151 You should find C<git grep> helpful to find where to edit.
152
153 The package's Debian metadata and the scripts for building binary
154 packages are under C<debian/>.
155 C<debian/control>, C<debian/changelog> and C<debian/rules> are the
156 starting points.
157 The Debian Policy Manual has most of the in-depth
158 technical details.
159
160 For many Debian packages,
161 there will also be some things in C<debian/patches/>.
162 It is best to ignore these.
163 Insofar as they are relevant
164 the changes there will have been applied to the actual files,
165 probably by means of actual comments in the git history.
166 The contents of debian/patches are ignored
167 when building binaries
168 from dgitish git branches.
169
170 (For Debian afficionados:
171 the git trees that come out of dgit are
172 "patches-applied packaging branches".)
173
174 =head2 What kind of history you get
175
176 If you're lucky, the history will be a version of,
177 or based on,
178 the Debian maintainer's own git history,
179 or upstream's git history.
180
181 But for many packages the real git history
182 does not exist,
183 or has not been published in a dgitish form.
184 So yuu may find that the history is a rather short
185 history invented by dgit.
186
187 dgit histories often contain automatically-generated commits,
188 including commits which make no changes but just serve
189 to make a rebasing branch fast-forward.
190
191 If the package maintainer is using git then
192 after dgit clone
193 you may find that there is a useful C<vcs-git> remote
194 referring to the Debian package maintainer's repository
195 for the package.
196 You can see what's there with C<git fetch vcs-git>.
197 But use what you find there with care:
198 Debian maintainers' git repositories often have
199 contents which are very confusing and idiosyncratic.
200 In particular, you may need to manually apply the patches
201 that are in debian/patches before you do anything else!
202
203 =head1 BUILDING
204
205 =head2 Always commit before building
206
207 =over 4
208
209     % wget 'https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=28250;mbox=yes;msg=89' | patch -p1 -u
210     % git commit -a -m 'Fix libc lost output bug'
211
212 =back
213
214 Debian package builds are often quite messy:
215 they may modify files which are also committed to git,
216 or leave outputs and teporary files not covered by C<.gitignore>.
217
218 Kf you always commit,
219 you can use
220
221 =over 4
222
223     % git clean -xdf
224     % git reset --hard
225
226 =back
227
228 to tidy up after a build.
229 (If you forgot to commit, don't use those commands;
230 instead, you may find that you can use C<git add -p>
231 to help commit what you actually wanted to keep.)
232
233 These are destructive commands which delete all new files
234 (so you B<must> remember to say C<git add>)
235 and throw away edits to every file
236 (so you B<must> remember to commit).
237
238 =head2 Update the changelog (at least once) before building
239
240 =over 4
241
242     % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit
243
244 =back
245
246 The binaries you build will have a version number which ultimately
247 comes from the C<debian/changelog>.
248 You want to be able to tell your
249 binaries apart from your distro's.
250
251 So you should update C<debian/changelog>
252 to add a new stanza at the top,
253 for your build.
254
255 This rune provides an easy way to do this.
256 It adds a new changelog
257 entry with an uninformative message and a plausible version number
258 (containing a bit of your git commit id).
259
260 If you want to be more sophisticated,
261 the package C<dpkg-dev-el> has a good Emacs mode
262 for editing changelogs.
263 Alternatively, you could edit the changelog with another text editor,
264 or run C<dch> or C<gbp dch> with different options.
265 Choosing a good version number is slightly tricky and
266 a complete treatment is beyond the scope of this tutorial.
267
268 =head2 Actually building
269
270 =over 4
271
272     % sudo apt-get build-dep glibc
273     % dpkg-buildpackage -uc -b
274
275 =back
276
277 apt-get build-dep installs the build dependencies according to the
278 official package, not your modified one.  So if you've changed the
279 build dependencies you might have to install some of them by hand.
280
281 dpkg-buildpackage is the primary tool for building a Debian source
282 package.
283 C<-uc> means not to pgp-sign the results.
284 C<-b> means build all binary packages,
285 but not to build a source package.
286
287 =head1 INSTALLING
288
289 =over 4
290
291     % sudo dpkg -i ../libc6_*.deb
292
293 =back
294
295 You can use C<dpkg -i> to install the
296 .debs that came out of your package.
297
298 If the dependencies aren't installed,
299 you will get an error, which can usually be fixed with
300 C<apt-get -f install>.
301
302 =head1 Multiarch
303
304 If you're working on a library package and your system has multiple
305 architectures enabled,
306 you may see something like this:
307
308 =over 4
309
310     dpkg: error processing package libpcre3-dev:amd64 (--configure):
311      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)
312
313 =back
314
315 The multiarch system used by Debian requires each package which is
316 present for multiple architectures to be exactly the same across
317 all the architectures for which it is installed.
318
319 The proper solution
320 is to build the package for all the architectures you
321 have enabled.
322 You'll need a chroot for each of the secondary architectures.
323 This iw somewhat tiresome,
324 even though Debian has excellent tools for managing chroots.
325 C<sbuild-createchroot> from the sbuild package is a
326 good starting point.
327
328 Otherwise you could deinstall the packages of interest
329 for those other architectures
330 with something like C<dpkg --remove libpcre3:i386>.
331
332 If neither of those are an option,
333 your desperate last resort is to try
334 using the same version number
335 as the official package for your own package.
336 (The verseion is controlled by C<debian/changelog> - see above,)
337 This is not ideal because it makes it hard to tell what is installed,
338 because it will mislead and confuse apt.
339
340 With the "same number" approach you may still get errors like
341
342 =over 4
343
344 trying to overwrite shared '/usr/include/pcreposix.h', which is different from other instances of package libpcre3-dev
345
346 =back
347
348 but passing C<--force-overwrite> to dpkg will help
349 - assuming you know what you're doing.
350
351 =head1 SHARING YOUR WORK
352
353 The C<dgit/jessie> branch (or whatever) is a normal git branch.
354 You can use C<git push> to publish it on any suitable git server.
355
356 Anyone who gets that git branch from you
357 will be able to build binary packages
358 just as you did.
359
360 If you want to contribute your changes back to Debian,
361 you should probably send them as attachments to 
362 an email to the
363 L<Debian Bug System|https://bugs.debian.org/>
364 (either a followup to an existing bug, or a new bug).
365 Patches in C<git-format-patch> format are usually very welcome.
366
367 =head2 Source packages
368
369 The
370 git branch is not sufficient to build a source package
371 the way Debian does.
372 Source packages are somewhat awkward to work with.
373 Indeed many plausible git histories or git trees
374 cannot be converted into a suitable source package.
375 So I recommend you share your git branch instead.
376
377 If a git branch is not enough, and
378 you need to provide a source package
379 but don't care about its format/layout
380 (for example because some software you have consumes source packages,
381 not git histories)
382 you can use this recipe to generate a C<1.0> "native"
383 source package, which is just a tarball
384 with accompanying .dsc metadata file:
385
386 =over 4
387
388     % git rm debian/source/version
389     % git commit -m 'switch to 1.0 source format'
390     % dgit -wgf --dpkg-buildpackage:-sn build-source
391
392 =back
393
394 If you need to provide a good-looking source package,
395 be prepared for a lot more work.
396 You will need to read much more, perhaps starting with
397 L<dgit-nmu-simple(7)>,
398 L<dgit-sponsorship(7)> or
399 L<dgit-maint-*(7)>
400
401 =head1 SEE ALSO
402
403 dgit(1), dgit(7)