diff options
Diffstat (limited to 'dgit-user.7.pod')
| -rw-r--r-- | dgit-user.7.pod | 415 |
1 files changed, 415 insertions, 0 deletions
diff --git a/dgit-user.7.pod b/dgit-user.7.pod new file mode 100644 index 0000000..e730052 --- /dev/null +++ b/dgit-user.7.pod @@ -0,0 +1,415 @@ +=head1 NAME + +dgit-user - making and sharing changes to Debian packages, with git + +=head1 INTRODUCTION + +dgit lets you fetch the source code to every package on your +system +as if your distro used git to maintain all of it. + +You can then edit it, +build updated binary packages (.debs) +and install and run them. +You can also share your work with others. + +This tutorial gives some recipes and hints for this. +It assumes you have basic familiarity with git. +It does not assume any initial familiarity with +Debian's packaging processes. + +If you are a package maintainer within Debian; a DM or DD; +and/or a sponsee: +this tutorial is not for you. +Try L<dgit-nmu-simple(7)>, L<dgit-maint-*(7)>, +or L<dgit(1)> and L<dgit(7)>. + +=head1 SUMMARY + +(These runes will be discussed later.) + +=over 4 + + % dgit clone glibc jessie + % cd glibc + % wget 'https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=28250;mbox=yes;msg=89' | patch -p1 -u + % git commit -a -m 'Fix libc lost output bug' + % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit + % sudo apt-get build-dep glibc + % dpkg-buildpackage -uc -b + % sudo dpkg -i ../libc6_*.deb + +=back + +Occasionally: + +=over 4 + + % git clean -xdf + % git reset --hard + +=back + +Later: + +=over 4 + + % cd glibc + % dgit pull jessie + % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit + % dpkg-buildpackage -uc -b + % sudo dpkg -i ../libc6_*.deb + +=back + +=head1 FINDING THE RIGHT SOURCE CODE - DGIT CLONE + +=over 4 + + % dgit clone glibc jessie + % cd glibc + +=back + +dgit clone needs to be told the source package name +(which might be different to the binary package name, +which was the name you passed to "apt-get install") +and the codename or alias of the Debian release +(this is called the "suite"). + +=head2 Finding the source package name + +For many packages, the source package name is obvious. +Otherwise, if you know a file that's in the package, +you can look it up with dpkg: + +=over 4 + + % dpkg -S /lib/i386-linux-gnu/libc.so.6 + libc6:i386: /lib/i386-linux-gnu/libc.so.6 + % dpkg -s libc6:i386 + Package: libc6 + Status: install ok installed + ... + Source: glibc + +=back + +(In this example, +libc6 is a "multi-arch: allowed" package, + which means that it exists in several different builds + for different architectures. +That's where C<:i386> comes from.) + +=head2 Finding the Debian release (the "suite") + +Internally, +Debian (and derived) distros normally refer to their releases by codenames. +Debian also has aliases which refer to the current stable release etc. +So for example, at the time of writing +Debian C<jessie> (Debian 8) is Debian C<stable>; and +the current version of Ubuntu is C<yakkety> (Yakkety Yak, 16.10). +You can specify either +the codename C<jessie> or the alias C<stable>. +If you don't say, you get C<sid>, +which is Debian C<unstable> - the main work-in progress branch. + +If you don't know what you're running, try this: + +=over 4 + + % grep '^deb' /etc/apt/sources.list + deb http://the.earth.li/debian/ jessie main non-free contrib + ... + % + +=back + +=head1 WHAT DGIT CLONE PRODUCES + +=head2 What branches are there + +dgit clone will give you a new working tree, +and arrange for you to be on a branch like +C<dgit/jessie>. + +There is a tracking branch for the contents of the archive, called +C<remotes/dgit/dgit/jessie> +(and similarly for other suites). This can be updated with +C<dgit fetch jessie>. +This, the I<remote suite branch>, +is synthesized by your local copy of dgit. +It is fast forwarding. + +(You can also dgit fetch in a tree that wasn't made by dgit clone. +If there's no C<debian/changelog> +you'll have to supply a C<-p>I<package> option to dgit fetch.) + +=head2 What kind of source tree do you get + +If the Debian package is based on some upstream release, +the code layout should be like the upstream version. +You should find C<git grep> helpful to find where to edit. + +The package's Debian metadata and the scripts for building binary +packages are under C<debian/>. +C<debian/control>, C<debian/changelog> and C<debian/rules> are the +starting points. +The Debian Policy Manual has most of the in-depth +technical details. + +For many Debian packages, +there will also be some things in C<debian/patches/>. +It is best to ignore these. +Insofar as they are relevant +the changes there will have been applied to the actual files, +probably by means of actual comments in the git history. +The contents of debian/patches are ignored +when building binaries +from dgitish git branches. + +(For Debian afficionados: +the git trees that come out of dgit are +"patches-applied packaging branches +without a .pc directory".) + +=head2 What kind of history you get + +If you're lucky, the history will be a version of, +or based on, +the Debian maintainer's own git history, +or upstream's git history. + +But for many packages the real git history +does not exist, +or has not been published in a dgitish form. +So yuu may find that the history is a rather short +history invented by dgit. + +dgit histories often contain automatically-generated commits, +including commits which make no changes but just serve +to make a rebasing branch fast-forward. + +If the package maintainer is using git then +after dgit clone +you may find that there is a useful C<vcs-git> remote +referring to the Debian package maintainer's repository +for the package. +You can see what's there with C<git fetch vcs-git>. +But use what you find there with care: +Debian maintainers' git repositories often have +contents which are very confusing and idiosyncratic. +In particular, you may need to manually apply the patches +that are in debian/patches before you do anything else! + +=head1 BUILDING + +=head2 Always commit before building + +=over 4 + + % wget 'https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=28250;mbox=yes;msg=89' | patch -p1 -u + % git commit -a -m 'Fix libc lost output bug' + +=back + +Debian package builds are often quite messy: +they may modify files which are also committed to git, +or leave outputs and teporary files not covered by C<.gitignore>. + +Kf you always commit, +you can use + +=over 4 + + % git clean -xdf + % git reset --hard + +=back + +to tidy up after a build. +(If you forgot to commit, don't use those commands; +instead, you may find that you can use C<git add -p> +to help commit what you actually wanted to keep.) + +These are destructive commands which delete all new files +(so you B<must> remember to say C<git add>) +and throw away edits to every file +(so you B<must> remember to commit). + +=head2 Update the changelog (at least once) before building + +=over 4 + + % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit + +=back + +The binaries you build will have a version number which ultimately +comes from the C<debian/changelog>. +You want to be able to tell your +binaries apart from your distro's. + +So you should update C<debian/changelog> +to add a new stanza at the top, +for your build. + +This rune provides an easy way to do this. +It adds a new changelog +entry with an uninformative message and a plausible version number +(containing a bit of your git commit id). + +If you want to be more sophisticated, +the package C<dpkg-dev-el> has a good Emacs mode +for editing changelogs. +Alternatively, you could edit the changelog with another text editor, +or run C<dch> or C<gbp dch> with different options. +Choosing a good version number is slightly tricky and +a complete treatment is beyond the scope of this tutorial. + +=head2 Actually building + +=over 4 + + % sudo apt-get build-dep glibc + % dpkg-buildpackage -uc -b + +=back + +apt-get build-dep installs the build dependencies according to the +official package, not your modified one. So if you've changed the +build dependencies you might have to install some of them by hand. + +dpkg-buildpackage is the primary tool for building a Debian source +package. +C<-uc> means not to pgp-sign the results. +C<-b> means build all binary packages, +but not to build a source package. + +=head1 INSTALLING + +=head2 Debian Jessie or older + +=over 4 + + % sudo dpkg -i ../libc6_*.deb + +=back + +You can use C<dpkg -i> to install the +.debs that came out of your package. + +If the dependencies aren't installed, +you will get an error, which can usually be fixed with +C<apt-get -f install>. + +=head2 Debian Stretch or newer + +=over 4 + + % sudo apt install ../libc6_*.deb + +=back + +=head1 Multiarch + +If you're working on a library package and your system has multiple +architectures enabled, +you may see something like this: + +=over 4 + + dpkg: error processing package libpcre3-dev:amd64 (--configure): + 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) + +=back + +The multiarch system used by Debian requires each package which is +present for multiple architectures to be exactly the same across +all the architectures for which it is installed. + +The proper solution +is to build the package for all the architectures you +have enabled. +You'll need a chroot for each of the secondary architectures. +This iw somewhat tiresome, +even though Debian has excellent tools for managing chroots. +C<sbuild-createchroot> from the sbuild package is a +good starting point. + +Otherwise you could deinstall the packages of interest +for those other architectures +with something like C<dpkg --remove libpcre3:i386>. + +If neither of those are an option, +your desperate last resort is to try +using the same version number +as the official package for your own package. +(The verseion is controlled by C<debian/changelog> - see above,) +This is not ideal because it makes it hard to tell what is installed, +because it will mislead and confuse apt. + +With the "same number" approach you may still get errors like + +=over 4 + +trying to overwrite shared '/usr/include/pcreposix.h', which is different from other instances of package libpcre3-dev + +=back + +but passing C<--force-overwrite> to dpkg will help +- assuming you know what you're doing. + +=head1 SHARING YOUR WORK + +The C<dgit/jessie> branch (or whatever) is a normal git branch. +You can use C<git push> to publish it on any suitable git server. + +Anyone who gets that git branch from you +will be able to build binary packages (.deb) +just as you did. + +If you want to contribute your changes back to Debian, +you should probably send them as attachments to +an email to the +L<Debian Bug System|https://bugs.debian.org/> +(either a followup to an existing bug, or a new bug). +Patches in C<git-format-patch> format are usually very welcome. + +=head2 Source packages + +The +git branch is not sufficient to build a source package +the way Debian does. +Source packages are somewhat awkward to work with. +Indeed many plausible git histories or git trees +cannot be converted into a suitable source package. +So I recommend you share your git branch instead. + +If a git branch is not enough, and +you need to provide a source package +but don't care about its format/layout +(for example because some software you have consumes source packages, +not git histories) +you can use this recipe to generate a C<1.0> "native" +source package, which is just a tarball +with accompanying .dsc metadata file: + +=over 4 + + % git rm debian/source/version + % git commit -m 'switch to 1.0 source format' + % dgit -wgf --dpkg-buildpackage:-sn build-source + +=back + +If you need to provide a good-looking source package, +be prepared for a lot more work. +You will need to read much more, perhaps starting with +L<dgit-nmu-simple(7)>, +L<dgit-sponsorship(7)> or +L<dgit-maint-*(7)> + +=head1 SEE ALSO + +dgit(1), dgit(7) |