1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465
|
=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,-security
% cd glibc
% 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 .
% 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,-security
% 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,-security
% 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
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).
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.
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 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 commits 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 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 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 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) 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 .
% dpkg-buildpackage -uc -b
=back
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 Stretch or newer
=over 4
% sudo apt install ../libc6_*.deb
=back
=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>.
=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,-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.
=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<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
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 INSTALLING NEWER DGIT ON OLDER DISTROS
If dgit breaks with the source package you are working with,
this might be due to a bug which would be fixed by upgrading.
You can probably directly
C<apt install>
the latest version of dgit.deb from Debian stable,
or Debian testing.
Versions of dgit from Debian 13 (trixie) onwards document
their installability on old releases in the manpage.
For example, for current Debian testing, see
L<https://manpages.debian.org/testing/dgit/dgit.1.en.html>,
and look in the section SUPPORT ON OLD DISTRIBUTIONS.
=head1 SEE ALSO
dgit(1), dgit(7)
|