chiark / gitweb /
i18n: Provide `i18n-update' target in toplevel Makefile
[dgit.git] / dgit-user.7.pod
index 54bfa1d..5713064 100644 (file)
@@ -1,43 +1,61 @@
 =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<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
+    % 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
+    % curl '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
+    % mk-build-deps --root-cmd=sudo --install
     % 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
+    % 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<jessie> (Debian 8) is Debian stable and
+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:
 
@@ -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<jessie> becomes C<jessie,-security>.
+(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<dgit/jessie,-security> (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<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.
 
-If the Debian package is actually a version of an upstream release,
+Debian separates out the security updates, into C<*-security>.
+Telling dgit C<jessie,-security> means that it should include 
+any updates available in C<jessie-security>.
+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<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 that git commands C<git grep> work properly.
+You should find C<git grep> 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<debian/>.
 C<debian/control>, C<debian/changelog> and C<debian/rules> are the
 starting points.
@@ -111,11 +174,18 @@ technical details.
 
 For many Debian packages,
 there will also be some things in C<debian/patches/>.
-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,140 @@ 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
-So yuu may find that the history is a rather short
+does not exist,
+or has not been published in a dgitish form.
+So you 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<jessie,-security>.
 
 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 maintainers repository
-for the pacakge.
+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 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
+
+=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'
 
-When using git with some arbitrary Debian package
-you should normally commit before building.
+=back
 
-This is because Debian package builds are often quite messy:
+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<git reset --hard> and C<git clean -xdf>
-to put things back.
-But if you create a new file
-B<don't forget> to say C<git add>, and commit,
-as otherwise C<git clean> will delete your new file.
+or leave outputs and temporary files not covered by C<.gitignore>.
+
+If 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)
+=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
+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.
-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<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
 
-    % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit
+    % mk-build-deps --root-cmd=sudo --install
+    % 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.
+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.
+
+=head2 Using sbuild
+
+You can build in an schroot chroot, with sbuild, instead of in your
+main environment.  (sbuild is used by the Debian build daemons.)
+
+=over 4
+
+    % git clean -xdf
+    % sbuild -c jessie -A --no-clean-source \
+             --dpkg-source-opts='-Zgzip -z1 --format=1.0 -sn'
+
+=back
+
+Note that this will seem to leave a "source package"
+(.dsc and .tar.gz)
+in the parent directory,
+but that source package should not be used.
+It is likely to be broken.
+For more information see Debian bug #868527.
 
 =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.
 
@@ -191,42 +336,114 @@ 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 is somewhat tiresome,
+even though Debian has excellent tools for managing chroots.
+C<sbuild-debian-developer-setup> from the package of the same name
+and C<sbuild-createchroot> from the C<sbuild> package are
+good starting points.
+
+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 version is controlled by C<debian/changelog> - see above).
+This is not ideal because it makes it hard to tell what is installed,
+and 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 any suitable git server.
+The C<dgit/jessie,-security> 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.
+Patches in C<git-format-patch> 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<source package>.
+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<dgit-nmu-simple(7)>, L<dgit-sponsorship(7)> or
- L<dgit-maint-*(7)>
 
-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
 
-xxx
+    % echo '3.0 (native)' >debian/source/format
+    % git commit -m 'switch to native source format' debian/source/format
+    % dgit -wgf build-source
 
-=head1 SEE ALSO
+=back
 
-dgit(1), dgit(7)
+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 AUTHOR
+=head1 SEE ALSO
 
-This tutorial was written and is maintained by Sean Whitton <spwhitton@spwhitton.name>.  It contains contributions from other dgit contributors too - see the dgit copyright file.
+dgit(1), dgit(7)