Contact me sending an e-mail (antispam defense activated)
Collected notes from debian-mentors
1. Introduction
Approching the Art of debian packaging, you cannot but stumble into debian-mentors mailing list. This list collects experienced Debian Developers (also referred as DD) willing to help and novice guys in search for answers to their question.
Reading emails on that lists, I've found something worth note, and I'd like to put that notes in this page. I know there are manuals to read (Debian Policy and New Maintainers' Guide for sure) and there is a FAQ from this mailing list, but not everything is listed there.
2. Notes
Here follow the notes. In italic my comments.
From message http://lists.debian.org/debian-mentors/2005/12/msg00391.html:
Consider adding
copyright notices to ./debian/rules and
./debian/copyright with your name and years of the names of previous
maintainers and contributors who have worked on the Debian packaging.
[cut]
Consider using
dh_makeshibs rather than a custom shlibs file:
+ install -m644 debian/shlibs
debian/sim/DEBIAN/shlibs
For that matter,
sim-0.9.3.svn133.orig/debian/shlibs
Do you actually want to provide shared libraries, anyway? Are
there
multiple binaries linked to said libraries, and is there a space
savings? Or, do you intend to provide a stable ABI against which
other packages are allowed to depend? If not, then I would
suggest to
link statically, without -fPIC flags.a
From message http://lists.debian.org/debian-mentors/2005/12/msg00378.html:
The idea is to
save the maintainer, developer, or user, from sitting
through a 5 minute recursive run of ./configure if they build the
package multiple times back to back.
So,
configure-stamp:
./configure
touch $@
build: configure-stamp
or whatever. Then the build target depends on a successful run of
configure, but a second run of 'build' will not cause ./configure to
be run a second time, because 'configure-stamp' file already exists.
It isn't required.
Actually, for a typical ./configure script which creates a ./Makefile,
it should probably be something to the effect of
Makefile:
./configure
build: Makefile
$(MAKE)
which has the same effect.
From message http://lists.debian.org/debian-mentors/2005/12/msg00390.html:
What do you mean
"provides"? Do you mean, if the ./debian/control
file says "Provides:", or if the two packages include common files?
If they include common files, then you could either make the packages
"Conflict:", or make your package "Replaces:" the other one, or ...
From message http://lists.debian.org/debian-mentors/2005/12/msg00361.html:
- please close
your ITP from debian/changelog;
- debian/README contains your changes to upstream source, but not
debian/changelog;
- debian/rules is OK, but why don't you use debhelper and its dh_*
commands?
This means: Open an ITP bug ($ reportbug wnpp) when you want to package a software.
From message http://lists.debian.org/debian-mentors/2005/12/msg00288.html:
>
I'm having some (for any Debian Developer surely) trivial problems
> with the dependencies: Shishi's configure finds gnutls13 on my
local
> machine, but Debian doesn't have gnutls13 yet. So when I
install the
> packages on another machine, the binaries cannot find gnutls13 and
> they won't work. Can I build my package in a "mini-Debian
> environment" that has the build-depends that I specified?
Check out pbuilder.
From message http://lists.debian.org/debian-mentors/2005/12/msg00293.html:
>
W: shishi source: native-package-with-dash
> N:
> N: Native packaging should only be used if a piece of
software was
> N: written specifically to be turned into a Debian package.
In this case,
> N: the version number should not contain a debian revision
part.
> N:
> N: Native source packages are sometimes created by
accident. In most
> N: cases the reason is the location of the original source
tarball.
> N: dpkg-source searches for this in
> N: ../package_upstream-version.orig.tar.gz.
> N:
>
> What's causing that?
into ../ before running the build (this should contain the upstream
release of shishi, from which the changes you've made can be deduced).
From message http://lists.debian.org/debian-mentors/2005/12/msg00428.html:
>
I renamed the upstream release to shishi_0.0.23.orig.tar.gz and placed
> it in ../. That seem to have done the trick, thanks!
> (Couldn't it have used shishi-0.0.23.tar.gz? I'm not sure if
I
> understand the significance of my step.)
The
packaging tools require that the upstream source have a very specific
name, namely <source-package>_<version>.orig.tar.gz where
<version> is the
package
version without the Debian revision (the bit after the last -).
[cut]
* The shishi manual is covered under the GNU Free Documentation License,which is not a DFSG-free license. The shishi-doc package therefore
must go into non-free rather than main, unless I can convince you, as
upstream, to change the license or dual-license it under a DFSG-free
license such as the GPL.
Furthermore, since the manual is not DFSG-free, the original upstream
source must be repackaged to remove it and anything else that isn't
DFSG-free from the .orig.tar.gz file. This is because everything in
Debian main, including everything contained in the upstream source
tarball even if it doesn't make it into a Debian package, must be
DFSG-free. The manual would have to be a separate source package.
[cut]
* Unless the intention is to have multiple development environments for
the library packages installed at the same time (in other words, both
a libshishi0-dev and a libshishi1-dev, with both co-existing
peacefully), most (myself included) recommend not including the SONAME
version in the -dev package. It makes life much easier for Debian
release management in general. If you version the dev package and
other packages in Debian depend on the library, then when libshishi1
comes along, all of those packages will require updates to their
Build-Depends and new uploads. If, on the other hand, the dev package
is still just called libshishi-dev, those packages only need binary
rebuilds, which can be handled automatically by the Debian release
managers.
My recommendation would therefore be to build libshishi-dev and
libshisa-dev, without the versioning. (The library package names are
fine.)
[cut]
* The -dev packages go into section libdevel, not devel. devel is for
development tools like compilers, revision control systems, and the
like.
* Given that this is alpha software, the third implementation of
Kerberos in Debian, and not necessarily recommended for production use
yet, it should be priority extra rather than priority optional. This
can always be changed later when it's had a 1.0 release and other
packages start depending on it. (The -dev packages should always be
priority extra, though.)
From message http://lists.debian.org/debian-mentors/2005/12/msg00447.html:
> The packaging tools require that the upstream source
have a very specific
> name, namely <source-package>_<version>
the original archive
shishi-0.0.23.tar.gz, instead of renaming it.
From message http://lists.debian.org/debian-mentors/2005/12/msg00369.html:
>>
* debian/watch: delete or (preferably) fix it
> I'm not sure if this file is generally used.
I
really like it when packages use watch files since it's very useful in
the qa.debian.org/developer.php
summary.
> I could probably remove it, but just for the future reference, how
would
> one fix it? Removing the commented lines, or...?
See the man page for uscan; it explains the format.
From message http://lists.debian.org/debian-mentors/2005/12/msg00472.html:
>
Homepage: http://wald.intevation.org
> This is a bit a problem, i'm also not sure because everybody makes
it a
> bit different, i thought it has to be like that (no warranty):
> Homepage: <http://.....>
http://www.us.debian.org/doc
There are *2* spaces in that line, one of which is
foo
.
Homepage: bar
^^
From message http://lists.debian.org/debian-mentors/2005/12/msg00477.html:
> -Depends: ${shlibs:Depends}, ${misc:Depends}
> +Depends: ${shlibs:Depends}
> (You don't need the second variable, it isn't defined anywhere...)
Automatic generation of miscellaneous dependencies.
Some debhelper commands may make the generated package need to depend
on some other packages. For example, if you use dh_installdebconf(1),
your package will generally need to depend on debconf. Or if you use
dh_installxfonts(1), your package will generally need to depend on a
particular version of xutils. Keeping track of these miscellaneous
dependencies can be annoying since they are dependant on how debhelper
does things, so debhelper offers a way to automate it.
All commands of this type, besides documenting what dependencies may be
needed on their man pages, will automatically generate a substvar
called ${misc:Depends}. If you put that token into your debian/control
file, it will be expanded to the dependencies debhelper figures you
need.
-- debhelper(7)
If you don't care about debhelper commands needing to add new dependencies
later then you can remove it if you want to, but it is a better idea to leave
it in. It's unfortunate that dpkg generates an ugly build message if it's
empty, but it does do the right thing.
From message http://lists.debian.org/debian-mentors/2005/12/msg00492.html:
> - you call debhelper scripts like dh_link but you don't set links.
> Drop those calls.
But not too many of them :)
dh_link fixes existing links, so I usually keep this one
unconditionally. I also keep the following, minimally:
dh_installchangelogs # Installs changelog.Debian
dh_installdocs # Installs copyright
dh_link # Fixes existing things
dh_strip # Fixes existing things
dh_compress # Fixes existing things
dh_fixperms # Fixes existing things
dh_installdeb # Does necessary things
dh_shlibdeps # Does things that shouldn't ever hurt, and
# fills in the ${misc:shlibsdepends} variable
# or whatever so I don't see noise from dpkg
dh_gencontrol # Does necessary things
dh_md5sums # Does best-practice things
dh_builddeb # The thing itself
From message http://lists.debian.org/debian-mentors/2005/12/msg00495.html:
> - the architecture is i386. Does it really not run on anything else?
Changed to "any".
From message http://lists.debian.org/debian-mentors/2005/12/msg00503.html:
I already added a NEWS file. But
not every user installed apt-listchanges, so I should also inform him
during update.
So, if you install apt-listchanges you'll notify the user of relevant news. In the man page apt-listchanges(1) I read the files to use are NEWS.Debian and changelog[.Debian] .
From message http://lists.debian.org/debian-mentors/2005/12/msg00505.html:
> Are there special things I need to care of? Does anyone know a package,
> where the configuration files moved? I already added a NEWS file. But
> not every user installed apt-listchanges, so I should also inform him
> during update. Is it enough, do this on command-line or should I better
> use a debconf-dialog? Is it enough to only inform the user or should I
> better ask him [1], if his configuration files should be moved? What
> would you do?
Leafnode has this situation. It copies the file using cat in preinst
and then removes the original. It doesn't ask the user so that things
keep on working after the upgrade without the user having to go and
manually fix their system.
From message http://lists.debian.org/debian-mentors/2005/12/msg00506.html:
> I'm currently preparing an update for a package. Until now, the
> configuration file(s) was/were located in /etc. Now there are changes,
> which make it more useful to have the configuration files
> inside /etc/foobar. The configuration files look like foobar.conf*.
>
> Are there special things I need to care of?
As a newbie maintainer myself, I find the examples and explanations in
http://www.dpkg.org/ConffileHandling very useful for dealing with
conffiles. If your configuration file didn't change format (i.e., the
user just need to copy the old /etc/foobar.conf* to
/etc/foobar/foobar.conf* without any changes), I believe the section
about "Moving a conffile" is exactly what you need.
Also, if the file format didn't change, I don't see any reason the user
should be asked if he/she wants to move the conffile, the package should
just move for him/her.
From message http://lists.debian.org/debian-mentors/2005/12/msg00501.html:
it's very common to leave off the last '.1', since increments in policy
on that level only contain textual changes. Hence your package will
comply with any 3.6.2.x policy, so listing 3.6.2 would be best.
From message http://lists.debian.org/debian-mentors/2006/01/msg00014.html:
> I updated the package to 1.0.0. The version compare algorithm doesn't
> like it ... it thinks that 1.0.0 is less than 1.0.0rc5 ... but that's not
> how release candidates work :)
That's indeed a caveat on the Debian version compare algorithm. When
you're packaging a release candidate, you normally should watch out for
adding 'rcN' to the version to avoid being able to update it to the real
version later.
What's done commonly is something like this: 0.9.9+1.0.0rc5, or for a
higher version: 2.4.3+2.4.4rc1. So you take the version number one lower,
you concatenate the real version with a plus in between. The algorithm
will handle this correctly and the archive will accept a subsequent upload
of 1.0.0 or 2.4.4 proper.
From message http://lists.debian.org/debian-mentors/2006/01/msg00017.html:
> What's done commonly is something like this: 0.9.9+1.0.0rc5, or for a
> higher version: 2.4.3+2.4.4rc1.
I believe this practice has been obsolete since the release of sarge.
dpkg now considers "~" to sort before anything, even a null string, so
you can use e.g. "1.0.0~rc5".
From message http://lists.debian.org/debian-mentors/2006/01/msg00060.html:
> I tried something like:
>
> configure/foo::
> ./configure bla bla bla
>
> but this leads to ./configure being executed twice, one time before
> the actual building, another before the installation.
configure/foo:: configure-foo-stamp
configure-foo-stamp:
./configure bla bla bla
touch configure-foo-stamp
The second time the configure/foo rule is called, it will notice that
the configure-foo-stamp is already present, and not run configure.
From message http://lists.debian.org/debian-mentors/2006/01/msg00076.html:
I recommend switching from the current manually-implemented patch system
to using dpatch, although you're certainly not required to do this and
I'll sponsor the package anyway. The advantage to using dpatch, even
though it may not gain you any additional functionality over what you have
now, is that more other people use it and it's one less thing about the
package for someone else who wants to work on it to figure out.
From message http://lists.debian.org/debian-mentors/2004/12/msg00073.html:
> dh_make genererated control files which usually include something
> like this:
> Depends: ${shlibs:Depends},${misc:Depends}
> Can someone explain me how these variables get substituted?
> Because i get this message if i build the package:
> dpkg-gencontrol: warning: unknown substitution variable ${shlibs:Depends}
> dpkg-gencontrol: warning: unknown substitution variable ${misc:Depends}
During the package generation process, it may be advantageous for the
package generation process to generate or append to the list of substitution
variables. There's stock code within Debhelper to do it, for instance, so
any debhelper script can manipulate a substvar if it wants to.
The generated substitution variables are stored in a file called
<package>.substvars in the debian/ directory of your source tree. This file
is typically cleaned up in the clean target; dh_clean does the job rather
nicely. The program dpkg-gencontrol is responsible for taking the control
file and the <package>.substvars file and making the appropriate
substitutions. To try and minimise problems due to typos and bodgy code,
any substvar mentioned in the control file but not present in substvars
produces a warning from dpkg-gencontrol. If these truly aren't needed by
your application, it is best to remove the relevant substvar from control
for cleanliness.
From message http://lists.debian.org/debian
In that message (and following replies) you can find how to upgrade a package to a newer version of Debian Policy.
From message :