X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=dgit-user.7.pod;h=ad0cca1da867e3bd19623f0e942723170136627d;hp=54bfa1d0c815d7960d277ad0d87cb705c3229660;hb=ec7cf6aaf2fce8af943ccdd866e98f805f8a98fe;hpb=a940f4daeaac4af029412a8836e8153b67044a94 diff --git a/dgit-user.7.pod b/dgit-user.7.pod index 54bfa1d0..ad0cca1d 100644 --- a/dgit-user.7.pod +++ b/dgit-user.7.pod @@ -1,27 +1,36 @@ =head1 NAME -dgit - tutorial for users of Debian-derived distros supported by dgit +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. +as if your distro used git to maintain all of it. You can then edit it, -build updated binary packages +build updated binary packages (.debs) and install and run them. You can also share your work with others. -This tutorial assumes you have basic familiarity with git. +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. +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, L, +or L and L. =head1 SUMMARY +(These runes will be discussed later.) + =over 4 - % dgit clone glibc jessie + % dgit clone glibc jessie,-security % 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' @@ -32,12 +41,21 @@ It does not assume any initial familiarity with =back +Occasionally: + +=over 4 + + % git clean -xdf + % git reset --hard + +=back + Later: =over 4 % cd glibc - % dgit pull jessie + % dgit pull jessie,-security % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit % dpkg-buildpackage -uc -b % sudo dpkg -i ../libc6_*.deb @@ -46,9 +64,17 @@ Later: =head1 FINDING THE RIGHT SOURCE CODE - DGIT CLONE +=over 4 + + % dgit clone glibc jessie,-security + % cd glibc + +=back + dgit clone needs to be told the source package name -(which might be different to the binary package name) -and the codename of the Debian release +(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 @@ -79,9 +105,14 @@ That's where C<:i386> comes from.) 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 (Debian 8) is Debian stable and +Debian C (Debian 8) is Debian C; and the current version of Ubuntu is C (Yakkety Yak, 16.10). +You can specify either +the codename C or the alias C. +If you don't say, you get C, +which is Debian C - the main work-in progress branch. If you don't know what you're running, try this: @@ -94,15 +125,47 @@ If you don't know what you're running, try this: =back -=head1 EDITING THE SOURCE CODE +For Debian, you should add C<,-security> +to the end of the suite name, +unless you're on unstable or testing. +Hence, in our example +C becomes C. +(Yes, with a comma.) + +=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 named like +C (yes, with a comma in the branch name). -=head2 What kind of source tree you get when you dgit clone +For each release (like C) +there is a tracking branch for the contents of the archive, called +C +(and similarly for other suites). This can be updated with +C. +This, the I, +is synthesized by your local copy of dgit. +It is fast forwarding. -If the Debian package is actually a version of an upstream release, +Debian separates out the security updates, into C<*-security>. +Telling dgit C means that it should include +any updates available in C. +The comma notation is a request to dgit to track jessie, +or jessie-security if there is an update for the package there. + +(You can also dgit fetch in a tree that wasn't made by dgit clone. +If there's no C +you'll have to supply a C<-p>I 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 that git commands C work properly. +You should find C helpful to find where to edit. -The package's Debian metadata and the script for building binary +The package's Debian metadata and the scripts for building binary packages are under C. C, C and C are the starting points. @@ -111,11 +174,18 @@ technical details. For many Debian packages, there will also be some things in C. -These will probably be in your git history -(one way or another), -and they are not used when building a package -based on a git histroy obtained with dgit. -It is best to ignore them. +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 @@ -125,65 +195,124 @@ the Debian maintainer's own git history, or upstream's git history. But for many packages the real git history -does not exist or -cannot be obtained in a standard form +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. +This is particularly true of +combining branches like +C. If the package maintainer is using git then after dgit clone you may find that there is a useful C remote -referring to the Debian package maintainers repository -for the pacakge. +referring to the Debian package maintainer's repository +for the package. You can see what's there with C. But use what you find there with care: -Debian maintainers' git histories are often in -formats which are very confusing and idiosyncratic -from the point of view of those new to Debian git packaging. +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 first +=head2 Always commit before building -When using git with some arbitrary Debian package -you should normally commit before building. +=over 4 -This is because Debian package builds are often quite messy: + % 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 C and C -to put things back. -But if you create a new file -B to say C, and commit, -as otherwise C will delete your new file. +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 +to help commit what you actually wanted to keep.) -=head2 Update the changelog (at least once) +These are destructive commands which delete all new files +(so you B remember to say C) +and throw away edits to every file +(so you B 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. You want to be able to tell your +comes from the C. +You want to be able to tell your binaries apart from your distro's. So you should update C to add a new stanza at the top, for your build. -An easy way to do this is this rune: + +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 has a good Emacs mode +for editing changelogs. +Alternatively, you could edit the changelog with another text editor, +or run C or C 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 - % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit + % sudo apt-get build-dep glibc + % dpkg-buildpackage -uc -b =back -which adds a new entry with a new version number chosen in a -reasonably sensible way, and commits the result to your git branch. +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 to install the .debs that came out of your package. @@ -191,42 +320,113 @@ If the dependencies aren't installed, you will get an error, which can usually be fixed with C. +=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 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. + +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 - 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 branch (or whatever) is a normal git branch. -You can use C to any suitable git server. +The C branch (or whatever) is a normal git branch. +You can use C 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 (either a followup to an existing bug, or a new bug). -Patches in C< format are usually very welcome. +Patches in C format are usually very welcome. -Anyone who gets that git branch from you -will be able to build binary packages -just as you did. +=head2 Source packages -However, the -git branch is not sufficient to build a I. +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 you need to provide a source package, -you will probably want to read one of the other tutorials, -such as L, L or - L -multi-arch clash problem +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<3.0 (native)> +source package, which is just a tarball +with accompanying .dsc metadata file: + +=over 4 + + % echo '3.0 (native)' >debian/source/format + % git commit -m 'switch to native source format' debian/source/format + % dgit -wgf build-source +=back -xxx +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, +L or +L =head1 SEE ALSO dgit(1), dgit(7) - -=head1 AUTHOR - -This tutorial was written and is maintained by Sean Whitton . It contains contributions from other dgit contributors too - see the dgit copyright file.