X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=dgit-user.7.pod;h=5713064b86a781cc116d41370df1661d5c32c54f;hp=d27cd936059aa86486e0dde29d9cb2e3b4164ce9;hb=fabaa10f37c0cea45e0fcb08d3bcaa6ad07191bd;hpb=c4dea463ddc76cf7e39612dbdce3b18a5a0db957 diff --git a/dgit-user.7.pod b/dgit-user.7.pod index d27cd936..5713064b 100644 --- a/dgit-user.7.pod +++ b/dgit-user.7.pod @@ -9,7 +9,7 @@ system 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. @@ -30,12 +30,12 @@ or L and L. =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 @@ -55,7 +55,7 @@ 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 @@ -66,13 +66,14 @@ Later: =over 4 - % dgit clone glibc jessie + % 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) +(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"). @@ -124,15 +125,23 @@ If you don't know what you're running, try this: =back +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 like -C. +and arrange for you to be on a branch named like +C (yes, with a comma in the branch name). -There is a tracking branch for the contents of the archive, called +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. @@ -140,6 +149,12 @@ This, the I, is synthesized by your local copy of dgit. It is fast forwarding. +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.) @@ -169,7 +184,8 @@ from dgitish git branches. (For Debian afficionados: the git trees that come out of dgit are -"patches-applied packaging branches".) +"patches-applied packaging branches +without a .pc directory".) =head2 What kind of history you get @@ -181,12 +197,15 @@ 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 +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. If the package maintainer is using git then after dgit clone @@ -213,9 +232,9 @@ that are in debian/patches before you do anything else! 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>. +or leave outputs and temporary files not covered by C<.gitignore>. -Kf you always commit, +If you always commit, you can use =over 4 @@ -269,23 +288,41 @@ a complete treatment is beyond the scope of this tutorial. =over 4 - % sudo apt-get build-dep glibc + % mk-build-deps --root-cmd=sudo --install % 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. +=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 @@ -299,6 +336,14 @@ 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 @@ -320,10 +365,11 @@ 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, +This is somewhat tiresome, even though Debian has excellent tools for managing chroots. -C from the sbuild package is a -good starting point. +C from the package of the same name +and C from the C package are +good starting points. Otherwise you could deinstall the packages of interest for those other architectures @@ -333,9 +379,9 @@ 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,) +(The version 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. +and because it will mislead and confuse apt. With the "same number" approach you may still get errors like @@ -350,11 +396,11 @@ but passing C<--force-overwrite> to dpkg will help =head1 SHARING YOUR WORK -The C branch (or whatever) is a normal git branch. +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 +will be able to build binary packages (.deb) just as you did. If you want to contribute your changes back to Debian, @@ -379,15 +425,15 @@ 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" +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 - % git rm debian/source/version - % git commit -m 'switch to 1.0 source format' - % dgit -wgf --dpkg-buildpackage:-sn build-source + % echo '3.0 (native)' >debian/source/format + % git commit -m 'switch to native source format' debian/source/format + % dgit -wgf build-source =back