X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=developers-reference.git;a=blobdiff_plain;f=developers-reference.sgml;h=7adb92514e9fde259d8b3e876de5d3ffdbbae8a8;hp=a7251ba95e79ba971daaf67343a0afce7b9394d1;hb=a575c4eb7334f4cb6c624fc8057bf2d92186fb59;hpb=7c92e2597554ae940af8e950f000ee476a64ddb2 diff --git a/developers-reference.sgml b/developers-reference.sgml index a7251ba..7adb925 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -6,7 +6,7 @@ %commondata; - + + + + + + Best practices for maintainer scripts +

+Maintainer scripts include the files debian/postinst, +debian/preinst, debian/prerm and +debian/postrm. These scripts take care of any package +installation or deinstallation setup which isn't handled merely by the +creation or removal of files and directories. The following +instructions supplement the . +

+Maintainer scripts must be idempotent. That means that you need to +make sure nothing bad will happen if the script is called twice where +it would usually be called once. +

+Standard input and output may be redirected (e.g. into pipes) for +logging purposes, so don't rely on them being a tty. +

+All prompting or interactive configuration should be kept to a +minimum. When it is necessary, you should use the +debconf package for the interface. Remember that +prompting in any case can only be in the configure stage of +the postinst script. +

+Keep the maintainer scripts as simple as possible. We suggest you use +pure POSIX shell scripts. Remember, if you do need any bash features, +the maintainer script must have a bash sh-bang line. POSIX shell or +Bash are preferred to Perl, since they enable +debhelper to easily add bits to the scripts. +

+If you change your maintainer scripts, be sure to test package +removal, double installation, and purging. Be sure that a purged +package is completely gone, that is, it must remove any files created, +directly or indirectly, in any maintainer script. +

+If you need to check for the existence of a command, you should use +something like +if [ -x /usr/sbin/install-docs ]; then ... + +If you don't wish to hard-code the path of the command in your +maintainer script, the following POSIX-compliant shell function may +help: + +&example-pathfind; + +You can use this function to search $PATH for a command name, +passed as an argument. It returns true (zero) if the command was +found, and false if not. This is really the most portable way, since +command -v, type, and which are not +POSIX. While which is an acceptable alternative, since +it is from the required debianutils package, it's +not on the root partition, although that is probably not something +that will cause a problem. + + + + Best practices for debian/control +

+The following practices supplement the .

+ + + Writing useful descriptions +

+The description of the package (as defined by the corresponding field +in the control file) is the primary information available +to the user about a package before they install it. It should provide +all the required information to let the user decide whether to install +the package. +

+For consistency and aesthetics, you should capitalize the first letter +of the Synopsis. Don't put a full stop (period) at the end. The +description itself should consist of full sentences. +

+Since the first user impression is based on the description, be +careful to avoid spelling and grammar mistakes. Ensure that you +spell-check it. ispell has a special -g option +for debian/control files: + +ispell -d american -g debian/control + +If you want someone to proofread the description that you +intend to use you may ask on &email-debian-l10n-english;. + + + + Upstream home page +

+We recommend that you add the URL for the package's home page to the +package description in debian/control. This information +should be added at the +end of description, using the following format: + + . + Homepage: http://some-project.some-place.org/ + +Note the spaces prepending the line, which serves to break the lines +correctly. To see an example of how this displays, see . +

+If there is no home page for the software, this should naturally be +left empty. +

+Note that we expect this field will eventually be replaced by a proper +debian/control field understood by dpkg and +&packages-host;. If you don't want to bother migrating the +home page from the description to this field, you should probably wait +until that is available.

+ + - Package with multiple patches -

-Big packages tend to have many upstream bugs that you want to fix within -the Debian package. If you just correct the bug in the source, all the -fixes are directly integrated in the .diff.gz file and you -can't easily differentiate the various patches that you applied. It gets -very messy when you have to update the package to a new upstream version -which integrates some of the fixes (but not all). -

-The good solution is to keep separate patches within the -debian/patches directory and to apply them on the fly at -build time. The package dbs provides an -implementation of such a system, you just have to build-depend on dbs to -be able to use its functionalities. The package -hello-dbs is a simple example that demonstrates how to -use dbs. -

-Additionally, dbs provides facilities to create the patches and to keep -track of what they are for. - Multiple binary packages -

-A single source package will often build several binary packages, either -to provide several flavors of the same software (examples are the -vim-* packages) or to make several small packages instead of a big one -(it's interesting if the user doesn't need all the packages and can thus -save some disk space). + + Configuration management with debconf +

-The second case can be easily managed by dh_install (from -debhelper) to move files from the build directory to -the package's temporary trees. +Debconf is a configuration management system which +can be used by all the various packaging scripts +(postinst mainly) to request feedback from the user +concerning how to configure the package. Direct user interactions must +now be avoided in favor of debconf +interaction. This will enable non-interactive installations in the +future.

-The first case is a bit more difficult since it involves multiple recompiles -of the same software but with different configure options. The -vim is an example of how to manage this with an -hand crafted rules file. - +Debconf is a great tool but it is often poorly used. Many common mistakes +are listed in the man page. +It is something that you must read if you decide to use debconf. + - Handling debconf translations -

-Like porters, translators have a difficult task. Since they work on many -packages, they cannot keep track of every change in packages in order to -be informed when a translated string is outdated. Fortunately -debconf can automatically report outdated translations, -if package maintainers follow some basic guidelines described below. -

-Translators can use debconf-getlang (package -debconf-utils) to write a templates.xx -file containing both English and localized fields (where xx is -the language code, may be followed by a country code). This file can be -put into the debian subdirectory without any change. -

-When building a binary package, debian/templates.xx files are -merged along with debian/templates to generate the -templates file contained in the binary package. This is -automatically done by dh_installdebconf (package -debhelper). If you do not use debhelper, you can -do the same with debconf-mergetemplate -(package debconf-utils). -

-When the package maintainer needs to update the templates file, they only -change debian/templates. When English strings in this file -and in debian/templates.xx differ, translators do know that -their translation is outdated. -

-Please see the page about - -at the Debian web site, it contains more detailed instructions, including a -full example. + + Internationalization + + + Handling debconf translations +

+Like porters, translators have a difficult task. They work on many +packages and must collaborate with many different +maintainers. Moreover, most of the time, they are not native English +speakers, so you may need to be particularly patient with them. +

+The goal of debconf was to make packages +configuration easier for maintainers and for users. Originally, +translation of debconf templates was handled with +debconf-mergetemplate. However, that technique is now +deprecated; the best way to accomplish debconf +internationalization is by using the po-debconf +package. This method is easier both for maintainer and translators; +transition scripts are provided. +

+Using po-debconf, the translation is stored in +po files (drawing from gettext translation +techniques). Special template files contain the original messages and +mark which fields are translatable. When you change the value of a +translatable field, by calling debconf-updatepo, the +translation is marked as needing attention from the translators. Then, +at build time, the dh_installdebconf program takes care +of all the needed magic to add the template along with the up-to-date +translations into the binary packages. Refer to the manual page for details. + + + + Internationalized documentation +

+Internationalizing documentation is crucial for users, but a lot of +labor. There's no way to eliminate all that work, but you can make things +easier for translators. +

+If you maintain documentation of any size, its easier for translators +if they have access to a source control system. That lets translators +see the differences between two versions of the documentation, so, for +instance, they can see what needs to be retranslated. It is +recommended that the translated documentation maintain a note about +what source control revision the translation is based on. An +interesting system is provided by in the boot-floppies package, +which shows an overview of the translation status for any given +language, using structured comments for the current revision of the +file to be translated and, for a translated file, the revision of the +original file the translation is based on. You might wish to adapt +and provide that in your CVS area. +

+If you maintain XML or SGML documentation, we suggest that you isolate +any language-independent information and define those as entities in a +separate file which is included by all the different +translations. This makes it much easier, for instance, to keep URLs +up-to-date across multiple files. + + - - Specific packaging practices + + Common packaging situations - - Miscellaneous advice - - - Writing useful descriptions -

-The description of the package (as defined by the corresponding field -in the control file) is usually the first information -available to the user before they install it. As such, it should -provide all the required information to let him decide whether -to install the package. -

-For example, apart from the usual description that you adapt from the -upstream README, you should include the URL of the -web site if there's any. If the package is not yet considered stable -by the author, you may also want to warn the user that the -package is not ready for production use. -

-For consistency and for an aesthetic concern, you should capitalize the -first letter of the description. -

-Last but not least, since the first user impression is based on -that description, you should be careful to avoid English -mistakes. Ensure that you spell check it. -ispell has a special option (-g) for that: -ispell -d american -g debian/control. -If you want someone to proofread the description that you -intend to use you may ask on &email-debian-l10n-english;. @@ -3137,7 +3364,7 @@ members in choosing what they want to work on and in choosing the most critical thing to spend their time on. - Bug Reporting + Bug reporting

We encourage you to file bugs as you find them in Debian packages. In fact, Debian developers are often the first line testers. Finding and @@ -3191,7 +3418,7 @@ list. Even though there is a dedicated group of people for Quality Assurance, QA duties are not reserved solely for them. You can participate in this effort by keeping your packages as bug-free as -possible, and as lintian-clean (see ) as +possible, and as lintian-clean (see ) as possible. If you do not find that possible, then you should consider orphaning some of your packages (see ). Alternatively, you may ask the help of other people @@ -3199,7 +3426,7 @@ in order to catch up the backlog of bugs that you have (you can ask for help on &email-debian-qa; or &email-debian-devel;). At the same time, you can look for co-maintainers (see ). - Bug Squashing Parties + Bug squashing parties

From time to time the QA group organizes bug squashing parties to get rid of as many problems as possible. They are announced on &email-debian-devel-announce; @@ -3227,21 +3454,6 @@ also respect the maintainer's wishes if he expressed some. If someone doesn't feel confident with an NMU, he should just send a patch to the BTS. It's far better than a broken NMU. - Dealing with unreachable maintainers -

-If you notice that a package is lacking maintenance, you should -make sure the maintainer is active and will continue to work on -his packages. Try contacting him yourself. -

-If you do not get a reply after a few weeks you should collect all -useful information about this maintainer. Start by logging into -the -and doing a full search to check whether the maintainer is on vacation -and when they were last seen. Collect any important package names -they maintain and any Release Critical bugs filed against them. -

-Send all this information to &email-debian-qa;, in order to let the -QA people do whatever is needed. Contacting other maintainers

@@ -3264,6 +3476,75 @@ You can do so by using the <package-name>@&pts-host; email address. + Dealing with inactive and/or unreachable maintainers +

+If you notice that a package is lacking maintenance, you should +make sure that the maintainer is active and will continue to work on +their packages. It is possible that they are not active any more, but +haven't registered out of the system, so to speak. On the other hand, +it is also possible that they just need a reminder. +

+The first step is to politely contact the maintainer, and wait for a +response, for a reasonable time. It is quite hard to define "reasonable +time", but it is important to take into account that real life is sometimes +very hectic. One way to handle this would be send a reminder after two +weeks. +

+If the maintainer doesn't reply within four weeks (a month), one can +assume that a response will probably not happen. If that happens, you +should investigate further, and try to gather as much useful information +about the maintainer in question as possible. This includes: +

+ + The "echelon" information available through the + , + which indicates when's the last time a developer has posted to + a Debian mailing list. (This includes uploads via + debian-*-changes lists.) Also, remember to check whether the + maintainer is marked as "on vacation" in the database. + + The number of packages this maintainer is responsible for, + and the condition of those packages. In particular, are there + any RC bugs that have been open for ages? Furthermore, how + many bugs are there in general? Another important piece of + information is whether the packages have been NMUed, and if + so, by whom? + + Is there any activity of the maintainer outside of Debian? + For example, they might have posted something recently to + non-Debian mailing lists or news groups. + +

+One big problem are packages which were sponsored -- the maintainer is not +an official Debian developer. The echelon information is not available for +sponsored people, for example, so you need to find and contact the Debian +developer who has actually uploaded the package. Given that they signed the +package, they're responsible for the upload anyhow, and should know what +happened to the person they sponsored. +

+It is also allowed to post a query to &email-debian-devel;, asking if anyone +is aware of the whereabouts of the missing maintainer. +

+Once you have gathered all of this, you can contact &email-debian-qa;. +People on this alias will use the information you provided in order to +decide how to proceed. For example, they might orphan one or all of the +packages of the maintainer. If a packages has been NMUed, they might prefer +to contact the NMUer before orphaning the package -- perhaps the person who +has done the NMU is interested in the package. +

+One last word: please remember to be polite. We are all volunteers and +cannot dedicate all of our time to Debian. Also, you are not aware of the +circumstances of the person who is involved. Perhaps they might be +seriously ill or might even had died -- you do not know who may be on the +receiving side -- imagine how a relative will feel if they read the e-mail +of the deceased and find a very impolite, angry and accusing message!) +

+On the other hand, although we are volunteers, we do have a responsibility. +So you can stress the importance of the greater good -- if a maintainer does +not have the time or interest anymore, they should "let go" and give the +package to someone with more time. + + Interacting with prospective Debian developers

@@ -3306,7 +3587,7 @@ the package meets minimum Debian standards. That implies that you must build and test the package on your own system before uploading.

You can not simply upload a binary .deb from the sponsoree. In -theory, you should only ask only for the diff file and the location of the +theory, you should only ask for the diff file and the location of the original source tarball, and then you should download the source and apply the diff yourself. In practice, you may want to use the source package built by your sponsoree. In that case, you have to check that they haven't @@ -3320,7 +3601,7 @@ means being a mentor.

Once the package meets Debian standards, build the package with dpkg-buildpackage -us -uc and sign it -with debsign -m <your-email-addr> <changes-file> +with debsign -m"FULLNAME email-addr" changes-file before uploading it to the incoming directory.

The Maintainer field of the control file and the @@ -3366,10 +3647,14 @@ endorse any particular tool to the exclusion of a competing tool. Most of the descriptions of these packages come from the actual package descriptions themselves. Further information can be found in the package documentation itself. You can also see more info with the -command apt-cache show <package-name>. +command apt-cache show <package-name>.

+ + Core tools +

+The following tools are pretty much required for any maintainer.

- + dpkg-dev

dpkg-dev contains the tools (including @@ -3378,18 +3663,7 @@ source packages. These utilities contain the fundamental, low-level functionality required to create and manipulated packages; as such, they are required for any Debian maintainer. - - - lintian -

-Lintian dissects Debian packages and reports bugs -and policy violations. It contains automated checks for many aspects -of Debian policy as well as some checks for common errors. The use of -lintian has already been discussed in and . - - - + debconf

debconf provides a consistent interface to @@ -3402,14 +3676,71 @@ You can find documentation for this package in the debconf-doc package.

Many feel that this system should be used for all packages requiring -interactive configuration. debconf is not -currently required by Debian Policy, however, that may change in the -future. +interactive configuration; see . +debconf is not currently required by Debian Policy, +but that may change in the future. + + + + fakeroot +

+fakeroot simulates root privileges. This enables +you to build packages without being root (packages usually want to +install files with root ownership). If you have +fakeroot installed, you can build packages as a +user: dpkg-buildpackage -rfakeroot. + + + + + Package lint tools

+According to the Free On-line Dictionary of Computing (FOLDOC), `lint' +is "a Unix C language processor which carries out more thorough checks +on the code than is usual with C compilers." Package lint tools help +package maintainers by automatically finding common problems and +policy violations with their packages.

+ + + lintian +

+lintian dissects Debian packages and emits +information on bugs +and policy violations. It contains automated checks for many aspects +of Debian policy as well as some checks for common errors. +

+You should periodically get the newest lintian from +`unstable' and check over all your packages. Notice that the -i +option provides detailed explanations of what each error or warning means, +what is its basis in Policy, and commonly how you can fix the problem. +

+Refer to for more information on how and when +to use Lintian. +

+You can also see a summary of all problems reported by Lintian on your +packages at . Those reports contain the latest +lintian output on the whole development distribution +("unstable"). + + + linda +

+linda is another package linter. It is similar to +lintian but has a different set of checks. Its +written in Python rather than Perl.

+ + + + + Helpers for debian/rules +

+Package building tools make the process of writing +debian/rules files easier. See +for more information on why these might or might not be desired. - - debhelper + + debhelper

debhelper is a collection of programs that can be used in debian/rules to automate common tasks related to @@ -3425,10 +3756,10 @@ other "debian/rules tools". There are a number of little debhelper add-on packages, too transient to document. You can see the list of most of them by doing apt-cache search ^dh-. + - - - debmake + + debmake

debmake, a pre-cursor to debhelper, is a less granular @@ -3442,10 +3773,25 @@ sort of automated functions that one finds in The consensus is that debmake is now deprecated in favor of debhelper. However, it's not a bug to use debmake. + + + dh-make +

+The +While the rules files generated by - - yada + + yada

yada is another packaging helper tool. It uses a debian/packages file to auto-generate @@ -3455,20 +3801,30 @@ favor of debhelper. However, it's not a bug to use Note that yada is called "essentially unmaintained" by it's own maintainer, Charles Briscoe-Smith. As such, it can be considered deprecated. + - - - equivs + + equivs

equivs is another package for making packages. It is often suggested for local use if you need to make a package simply to fulfill dependencies. It is also sometimes used when making ``meta-packages'', which are packages whose only purpose is to depend -on other packages. +on other packages.

+ + + - - cvs-buildpackage + + Package builders +

+The following packages help with the package building process, general +driving dpkg-buildpackage as well as handling supporting +tasks.

+ + + cvs-buildpackage

cvs-buildpackage provides the capability to inject or import Debian source packages into a CVS repository, build a Debian @@ -3480,105 +3836,234 @@ by Debian maintainers. This allows one to keep separate CVS branches of a package for stable, unstable and possibly experimental distributions, along with the other benefits of a version control system. + - - - dupload + + debootstrap +

+The debootstrap package and script allows you to +"bootstrap" a Debian base system into any part of your file-system. +By "base system", we mean the bare minimum of packages required to +operate and install the rest of the system.

+Having a system like this can be useful in many ways. For instance, +you can chroot into it if you want to test your build +depends. Or, you can test how your package behaves when installed +into a bare base system. Chroot builders use this package, see below. + + + + pbuilder +

+pbuilder constructs a chrooted system, and builds a +package inside the chroot. It is very useful to check that a package's +build-dependencies are correct, and to be sure that unnecessary and +wrong build dependencies will not exist in the resulting package.

+

+A related package is pbuilder-uml, which goes even +further build doing the build within User-mode-linux.

+ + + + sbuild +

+sbuild is another automated builder. It can use +chrooted environments as well. It can be used stand-alone, or as part +of a networked, distributed build environment. As the latter, it is +part of the system used by porters to build binary packages for all +the available architectures. See for more +information, and to see the system in +action.

+ + + + + Package uploaders +

+The following packages help automate or simplify the process of +uploading packages into the official archive.

+ + + dupload +

dupload is a package and a script to automatically upload Debian packages to the Debian archive, to log the upload, and to send mail about the upload of a package. You can configure it for new upload locations or methods. + - - - dput -

+ + dput +

The dput package and script does much the same thing as dupload, but in a different way. It has some features over dupload, such as the ability to check the GnuPG signature and checksums before uploading, and the possibility of running dinstall in dry-run mode after the upload. + + - - - fakeroot -

-fakeroot simulates root privileges. This enables -you to build packages without being root (packages usually want to -install files with root ownership). If you have -fakeroot installed, you can build packages as a -user: dpkg-buildpackage -rfakeroot. - - - - debootstrap -

-The debootstrap package and script allows you to -"bootstrap" a Debian base system into any part of your file-system. -By "base system", we mean the bare minimum of packages required to -operate and install the rest of the system. -

-Having a system like this can be useful in many ways. For instance, -you can chroot into it if you want to test your build -depends. Or, you can test how your package behaves when installed -into a bare base system. - - - - pbuilder + + Maintenance automation

-pbuilder constructs a chrooted system, and builds -a package inside the chroot. It is very useful to check that -a package's build-dependencies are correct, and to be sure that -unnecessary and wrong build dependencies will not exist in the -resulting package. +The following tools help automate different maintenance tasks, from +adding changelog entries or signature lines, looking up bugs in Emacs, +to making use of the newest and official use of +config.sub.

- - - devscripts -

-devscripts is a package containing a few wrappers + + devscripts +

+devscripts is a package containing wrappers and tools which are very helpful for maintaining your Debian packages. Example scripts include debchange and dch, which manipulate your debian/changelog file from the command-line, and debuild, which is a wrapper around dpkg-buildpackage. The bts utility is also very helpful to update the state of bug reports on the -command line, as is uscan to watch for new upstream -versions of your packages. Check the devscripts(1) manual -page for a complete list of available scripts. +command line. uscan can be used to watch for new upstream +versions of your packages. The debrsign can be used to +remotely sign a package prior to upload, which is nice when the +machine you build the package on is different from where your GPG keys +are.

+

+See the manual page for a +complete list of available scripts.

+ + + + autotools-dev +

+Contains best practices for people maintaining packages that use +autoconf and/or automake. Also contains +canonical config.sub and config.guess files +which are known to work on all Debian ports.

+ + + + dpkg-repack +

+dpkg-repack creates Debian package file out of a package +that has already been installed. If any changes have been made to the +package while it was unpacked (e.g., files in /etc were +modified), the new package will inherit the changes.

+

+This utility can make it easy to copy packages from one computer to +another, or to recreate packages that are installed on your system +but no longer available elsewhere, or to store the current state of a +package before you upgrade it.

+ + + + alien +

+alien converts binary packages between various packaging +formats, including Debian, RPM (RedHat), LSB (Linux Standard Base), +Solaris and Slackware packages.

+ + + debsums +

+debsums checks installed packages against their MD5 sums. +Note that not all packages have MD5 sums, since they aren't required +by Policy.

+ - - dpkg-dev-el -

+ + dpkg-dev-el +

dpkg-dev-el is an Emacs lisp package which provides assistance when editing some of the files in the debian directory of your package. For instance, when editing debian/changelog, there are handy functions for -finalizing a version and listing the package's current bugs. +finalizing a version and listing the package's current bugs.

+ + - - debget -

-debget is a package containing a convenient script -which can be helpful in downloading files from the Debian archive. -You can use it to download source packages, for instance (although -apt-get source <package-name> does pretty much the same -thing). + + Porting tools +

+The following tools are helpful for porters and for +cross-compilation.

+ + + quinn-diff +

+quinn-diff is used to locate the differences from +one architecture to another. For instance, it could tell you which +packages need to be ported for architecture Y, based on +architecture X. + + + dpkg-cross +

+dpkg-cross is a tool for installing libraries and +headers for cross-compiling in a way similar to +dpkg. Furthermore, the functionality of +dpkg-buildpackage and dpkg-shlibdeps is +enhanced to support cross-compiling. + + + + + Documentation and information +

+The following packages provide information for maintainers or help +with building documentation. + + debiandoc-sgml +

+debiandoc-sgml provides the DebianDoc SGML DTD, +which is commonly used for Debian documentation. This manual, for +instance, is written in DebianDoc. It also provides scripts for +building and styling the source to various output formats.

+

+Documentation for the DTD can be found in the +debiandoc-sgml-doc package.

+ + + + debian-keyring +

+Contains the public GPG and PGP keys of Debian developers. See and the package documentation for more +information.

+ + + + debview +

+debview provides an Emacs mode for viewing Debian +binary packages. This lets you examine a package without unpacking +it.

+ + - +