X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=developers-reference.sgml;h=ba2a9b7f74a1b285a483d96f87f4808708672af1;hb=f50002db4dc538c97c05759dafb3c0a6cdfffaa2;hp=26d0bcb2f0386a5a8a75cc970f3afbd8b04c745f;hpb=97280efef384958fc536b35568c60ac3a6824f38;p=developers-reference.git diff --git a/developers-reference.sgml b/developers-reference.sgml index 26d0bcb..ba2a9b7 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -6,7 +6,7 @@ %commondata; - + + Configuration management with debconf @@ -3085,7 +3207,7 @@ name="po-debconf" section="7"> manual page for details. - Internationalized Documentation + 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 @@ -3106,7 +3228,7 @@ 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-independant information and define those as entities in a +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. @@ -3132,7 +3254,8 @@ Keeping autoconf's config.sub and especially on more volatile architectures. Some very good packaging practices for any package using autoconf and/or automake have been synthesized in -&file-bpp-autotools;. You're strongly encouraged to read this file and +&file-bpp-autotools; from the autotools-dev +package. You're strongly encouraged to read this file and to follow the given recommendations. @@ -3147,6 +3270,29 @@ breaking. Good practices for library packaging have been grouped in . + + Documentation +

+Be sure to follow the .

+

+If your package contains documentation built from XML or SGML, we +recommend you not ship the XML or SGML source in the binary +package(s). If users want the source of the documentation, they +should retrieve the source package.

+

+Policy specifies that documentation should be shipped in HTML format. +We also recommend shipping documentation in PDF and ASCII format if +convenient and quality output is possible. However, it is generally +not appropriate to ship ASCII versions of documentation whose source +format is HTML.

+

+Major shipped manuals should register themselves with +doc-base on installation. See the +doc-base package documentation for more +information.

+ + Specific types of packages

Several specific types of packages have special sub-policies and @@ -3197,36 +3343,6 @@ Lisp packages should register themselves with sympa may be an example package --> - - Miscellaneous advice - - - 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 example, apart from the usual description that you might 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 aesthetics, you should capitalize the first letter -of the description. Don't put a full stop (period) at the end. -

-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;. @@ -3243,7 +3359,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 @@ -3305,7 +3421,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; @@ -3472,10 +3588,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 @@ -3484,11 +3604,49 @@ 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. + + debconf +

+debconf provides a consistent interface to +configuring packages interactively. It is user interface +independent, allowing end-users to configure packages with a +text-only interface, an HTML interface, or a dialog interface. New +interfaces can be added modularly. +

+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; see . +debconf is not currently required by Debian Policy, +but that may change in the future. + - - lintian + + fakeroot

-Lintian dissects Debian packages and reports bugs +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.

@@ -3504,29 +3662,26 @@ 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.

+ + - - debconf -

-debconf provides a consistent interface to -configuring packages interactively. It is user interface -independent, allowing end-users to configure packages with a -text-only interface, an HTML interface, or a dialog interface. New -interfaces can be added modularly. -

-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. -

- + + 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 @@ -3542,10 +3697,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 @@ -3559,10 +3714,10 @@ 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 + + dh-make

The - - - yada + + yada

yada is another packaging helper tool. It uses a debian/packages file to auto-generate @@ -3587,20 +3742,30 @@ and make the package entirely functional and Policy-compliant. 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.

+ + + + + + 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

cvs-buildpackage provides the capability to inject or import Debian source packages into a CVS repository, build a Debian @@ -3612,103 +3777,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-dev-el -

+ + 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 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.

+ + + + + 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.

+ + - +