X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=policy.sgml;h=733e1f0c6f39c9c025a9f5cf8f1e10b75d1e2816;hb=8005797abdddb3b4762ed13d88ef22bc15ad8c75;hp=f2de5bad9ab21639475d0f24128956c44ea866cd;hpb=5206184ae5d8b8e9352172576bf07305c9e3fe56;p=debian%2Fdebian-policy.git diff --git a/policy.sgml b/policy.sgml index f2de5ba..733e1f0 100644 --- a/policy.sgml +++ b/policy.sgml @@ -8,7 +8,7 @@ Debian Policy Manual - + The Debian Policy Mailing List version &version;, &date; @@ -73,13 +73,11 @@ the behavior of the packaging system. Instead, this manual attempts to define the interface to the package management system that the developers have to be conversant with. -

Informally, the criteria used for inclusion is that the material meet one of the following requirements: Standard interfaces -

The material presented represents an interface to the packaging system that is mandated for use, and is used by, a significant number of packages, and @@ -90,22 +88,18 @@ compatibility with these interface definitions. (Control file and changelog file formats are examples.) -

Chosen Convention -

If there are a number of technically viable choices that can be made, but one needs to select one of these options for inter-operability. The version number format is one example. -

Please note that these are not mutually exclusive; selected conventions often become parts of standard interfaces. -

@@ -135,6 +129,7 @@ may (or optional) are truly optional and adherence is left to the maintainer's discretion.

+

These classifications are roughly equivalent to the bug severities serious (for must or @@ -142,11 +137,13 @@ normal or important (for should or recommended directive violations) and wishlist (for optional - items). -

Compare RFC 2119. Note, however, that these words are - used in a different way in this document.

+ items). + + Compare RFC 2119. Note, however, that these words are + used in a different way in this document.

+

Much of the information presented in this manual will be useful even when building a package which is to be @@ -160,17 +157,14 @@

This manual is distributed via the Debian package - debian-policy. + .

The current version of this document is also available from the Debian web mirrors at - and from the Debian archive mirrors at - . + id="http://www.debian.org/doc/debian-policy/">. Also available from the same directory are several other formats: policy.html.tar.gz, policy.pdf.gz and policy.ps.gz. @@ -198,7 +192,8 @@

Since September 1998, the responsibility for the contents of - this document lies on the debian-policy mailing list. Proposals + this document lies on the . Proposals are discussed there and inserted into policy after a certain consensus is established. @@ -228,10 +223,52 @@ of the Policy Manual regarding changes to the Policy.

+ + + Related documents + +

+ There are several other documents other than this Policy Manual + that are necessary to fully understand some Debian policies and + procedures. +

+ +

+ The external "sub-policy" documents are referred to in: + + + + + + + + + +

+ +

+ In addition to those, which carry the weight of policy, there + is the Debian Developer's Reference. This document describes + procedures and resources for Debian developers, but it is + not normative; rather, it includes things that don't + belong into the Policy, such as best practices for developers. +

+ +

+ The Developer's Reference is available in the + developers-reference package. + It's also available from the Debian web mirrors at + . +

+ + + The Debian Archive +

The Debian GNU/Linux system is maintained and distributed as a collection of packages. Since there are so many of @@ -239,16 +276,27 @@ sections and given priorities to simplify the handling of them.

+

The effort of the Debian project is to build a free operating system, but not every package we want to make accessible is free in our sense (see the Debian Free Software Guidelines, below), or may be imported/exported without restrictions. Thus, the archive is split into the sections - main, non-free, contrib, - non-US/main, non-US/non-free, and - non-US/contrib. The sections are explained in detail - below. + based on their licenses and other restrictions. +

+ +

+ The aims of this are: + + + to allow us to make as much software available as we can + to allow us to encourage everyone to write free software, + and + to allow us to make it easy for people to produce + CD-ROMs of our system without violating any licenses, + import/export restrictions, or any other laws. +

@@ -261,68 +309,41 @@ of the Debian distribution, although we support their use and provide infrastructure for them (such as our bug-tracking system and mailing lists). This Debian Policy Manual applies - to these packages as well.

+ to these packages as well. +

- - Package copyright and sections + + The Debian Free Software Guidelines

- The aims of this section are: - - - -

to allow us to make as much software available as we - can,

- - -

to allow us to encourage everyone to write free - software, and

- - -

to allow us to make it easy for people to produce - CD-ROMs of our system without violating any licenses, - import/export restrictions, or any other laws.

- - -

- - The Debian Free Software Guidelines -

- The Debian Free Software Guidelines (DFSG) form our - definition of "free software". These are: + The Debian Free Software Guidelines (DFSG) form our + definition of "free software". These are: Free Redistribution -

The license of a Debian component may not restrict any party from selling or giving away the software as a component of an aggregate software distribution containing programs from several different sources. The license may not require a royalty or other fee for such sale. -

Source Code -

The program must include source code, and must allow distribution in source code as well as compiled form. -

Derived Works -

The license must allow modifications and derived works, and must allow them to be distributed under the same terms as the license of the original software. -

Integrity of The Author's Source Code -

The license may restrict source-code from being distributed in modified form only if the license allows the distribution of "patch files" @@ -334,41 +355,33 @@ original software. (This is a compromise. The Debian Project encourages all authors to not restrict any files, source or binary, from being modified.) -

No Discrimination Against Persons or Groups -

The license must not discriminate against any person or group of persons. -

No Discrimination Against Fields of Endeavor -

The license must not restrict anyone from making use of the program in a specific field of endeavor. For example, it may not restrict the program from being used in a business, or from being used for genetic research. -

Distribution of License -

The rights attached to the program must apply to all to whom the program is redistributed without the need for execution of an additional license by those parties. -

License Must Not Be Specific to Debian -

The rights attached to the program must not depend on the program's being part of a Debian system. If the program is extracted from Debian and used or @@ -377,89 +390,82 @@ the program is redistributed must have the same rights as those that are granted in conjunction with the Debian system. -

License Must Not Contaminate Other Software -

The license must not place restrictions on other software that is distributed along with the licensed software. For example, the license must not insist that all other programs distributed on the same medium must be free software. -

Example Licenses -

The "GPL," "BSD," and "Artistic" licenses are examples of licenses that we consider free. -

-

- - +

+ + + + Sections + + The main section +

Every package in main and non-US/main must comply with the DFSG (Debian Free Software - Guidelines).

+ Guidelines). +

In addition, the packages in main -

must not require a package outside of main for compilation or execution (thus, the package must not declare a "Depends", "Recommends", or "Build-Depends" relationship on a non-main package), -

-

must not be so buggy that we refuse to support them, and -

-

must meet all policy requirements presented in this manual. -

+

Similarly, the packages in non-US/main -

must not require a package outside of main or non-US/main for compilation or execution, -

-

must not be so buggy that we refuse to support them, -

-

must meet all policy requirements presented in this manual. -

+ - + + The contrib section +

Every package in contrib and non-US/contrib must comply with the DFSG. @@ -470,16 +476,12 @@ non-US/contrib -

must not be so buggy that we refuse to support them, and -

-

must meet all policy requirements presented in this manual. -

@@ -495,223 +497,219 @@ contrib or non-US/contrib are: -

free packages which require contrib, non-free packages or packages which are not in our archive at all for compilation or execution, and -

-

wrapper packages or other sorts of free accessories for non-free programs. -

- + + The non-free section +

Packages must be placed in non-free or non-US/non-free if they are not compliant with the DFSG or are encumbered by patents or other legal issues that make their distribution problematic.

+

In addition, the packages in non-free and non-US/non-free -

must not be so buggy that we refuse to support them, and -

-

must meet all policy requirements presented in this - manual that it is possible for them to meet. -

+ manual that it is possible for them to meet. + It is possible that there are policy requirements which the package is unable to meet, for example, if the source is unavailable. These situations will need to be handled on a case-by-case basis. -

-

- + The non-US sections +

Non-free programs with cryptographic program code need to be stored on the non-us server because of export restrictions of the U.S.

+

Programs which use patented algorithms that have a - restrictied license also need to be stored on "non-us", + restricted license also need to be stored on "non-us", since that is located in a country where it is not allowed to patent algorithms.

+

A package depends on another package which is distributed via the non-us server has to be stored on the non-us server as well.

- - Further copyright considerations -

- Every package must be accompanied by a verbatim copy of - its copyright and distribution license in the file - /usr/share/doc/package/copyright - (see for further details). -

-

- We reserve the right to restrict files from being included - anywhere in our archives if - - -

+ + + + Copyright considerations + +

+ Every package must be accompanied by a verbatim copy of + its copyright and distribution license in the file + /usr/share/doc/package/copyright + (see for further details). +

+ +

+ We reserve the right to restrict files from being included + anywhere in our archives if + + their use or distribution would break a law, -

- - -

+ + there is an ethical conflict in their distribution or use, -

- - -

+ + we would have to sign a license for them, or -

- - -

+ + their distribution would conflict with other project policies. -

- - -

+ + +

-

- Programs whose authors encourage the user to make - donations are fine for the main distribution, provided - that the authors do not claim that not donating is - immoral, unethical, illegal or something similar; in such - a case they must go in non-free.

+

+ Programs whose authors encourage the user to make + donations are fine for the main distribution, provided + that the authors do not claim that not donating is + immoral, unethical, illegal or something similar; in such + a case they must go in non-free. +

-

- Packages whose copyright permission notices (or patent - problems) do not even allow redistribution of binaries - only, and where no special permission has been obtained, - must not be placed on the Debian FTP site and its mirrors - at all.

+

+ Packages whose copyright permission notices (or patent + problems) do not even allow redistribution of binaries + only, and where no special permission has been obtained, + must not be placed on the Debian FTP site and its mirrors + at all. +

-

- Note that under international copyright law (this applies - in the United States, too), no distribution or - modification of a work is allowed without an explicit - notice saying so. Therefore a program without a copyright - notice is copyrighted and you may not do anything - to it without risking being sued! Likewise if a program - has a copyright notice but no statement saying what is - permitted then nothing is permitted.

+

+ Note that under international copyright law (this applies + in the United States, too), no distribution or + modification of a work is allowed without an explicit + notice saying so. Therefore a program without a copyright + notice is copyrighted and you may not do anything + to it without risking being sued! Likewise if a program + has a copyright notice but no statement saying what is + permitted then nothing is permitted. +

-

- Many authors are unaware of the problems that restrictive - copyrights (or lack of copyright notices) can cause for - the users of their supposedly-free software. It is often - worthwhile contacting such authors diplomatically to ask - them to modify their license terms. However, this can be a - politically difficult thing to do and you should ask for - advice on the debian-legal mailing list first, as - explained below. -

+

+ Many authors are unaware of the problems that restrictive + copyrights (or lack of copyright notices) can cause for + the users of their supposedly-free software. It is often + worthwhile contacting such authors diplomatically to ask + them to modify their license terms. However, this can be a + politically difficult thing to do and you should ask for + advice on the debian-legal mailing list first, as + explained below. +

-

- When in doubt about a copyright, send mail to - debian-legal@lists.debian.org. Be prepared - to provide us with the copyright statement. Software - covered by the GPL, public domain software and BSD-like - copyrights are safe; be wary of the phrases "commercial - use prohibited" and "distribution restricted". -

- - - Subsections +

+ When in doubt about a copyright, send mail to + debian-legal@lists.debian.org. Be prepared + to provide us with the copyright statement. Software + covered by the GPL, public domain software and BSD-like + copyrights are safe; be wary of the phrases "commercial + use prohibited" and "distribution restricted". +

+ -

- The packages in the sections main, - contrib and non-free are grouped further - into subsections to simplify handling. -

+ + Subsections -

- The section and subsection for each package should be - specified in the package's Section control - record. However, the maintainer of the Debian archive - may override this selection to ensure the consistency of - the Debian distribution. The Section field - should be of the form: - - -

+

+ The packages in the sections main, + contrib and non-free are grouped further + into subsections to simplify handling. +

+ +

+ The section and subsection for each package should be + specified in the package's Section control + record (see ). + However, the maintainer of the Debian archive + may override this selection to ensure the consistency of + the Debian distribution. The Section field + should be of the form: + + subsection if the package is in the main section, -

- - -

+ + section/subsection if the package is in the contrib or non-free section, and -

- - -

+ + non-US, non-US/contrib or non-US/non-free if the package is in non-US/main, non-US/contrib or non-US/non-free respectively. -

- - -

+ + +

-

- The Debian archive maintainers provide the authoritative - list of subsections. At present, they are: - admin, base, comm, - contrib, devel, doc, - editors, electronics, games, - graphics, hamradio, - interpreters, libs, mail, - math, misc, net, news, - non-US, non-free, oldlibs, - otherosfs, science, shells, - sound, tex, text, - utils, web, x11. -

- - +

+ The Debian archive maintainers provide the authoritative + list of subsections. At present, they are: + admin, base, comm, + contrib, devel, doc, + editors, electronics, embedded, + games, gnome, graphics, + hamradio, interpreters, kde, + libs, libdevel, mail, + math, misc, net, news, + non-US, non-free, oldlibs, + otherosfs, perl, python, + science, shells, + sound, tex, text, + utils, web, x11. +

+ + + Priorities

Each package should have a priority value, which is - included in the package's control record. This - information is used by the Debian package management tools - to separate high-priority packages from less-important - packages.

+ included in the package's control record + (see ). + This information is used by the Debian package management tools to + separate high-priority packages from less-important packages. +

The following priority levels are recognised by the @@ -719,7 +717,6 @@ required -

Packages which are necessary for the proper functioning of the system. You must not remove these packages or your system may become totally broken and @@ -727,22 +724,19 @@ put things back. Systems with only the required packages are probably unusable, but they do have enough functionality to allow the - sysadmin to boot and install more software.

+ sysadmin to boot and install more software. important -

Important programs, including those which one would expect to find on any Unix-like system. If the expectation is that an experienced Unix person who found it missing would say "What on earth is going on, where is foo?", it must be an important package. -

This is an important criterion because we are trying to produce, amongst other things, a free Unix. -

Other packages without which the system will not run well or be usable must also have priority @@ -750,19 +744,17 @@ not include Emacs, the X Window System, TeX or any other large applications. The important packages are just a bare minimum of - commonly-expected and necessary tools.

+ commonly-expected and necessary tools. standard -

These packages provide a reasonably small but not too limited character-mode system. This is what will be installed by default if the user doesn't select anything - else. It doesn't include many large applications.

+ else. It doesn't include many large applications. optional -

(In a sense everything that isn't required is optional, but that's not what is meant here.) This is all the software that you might reasonably want to @@ -771,19 +763,17 @@ and includes the X Window System, a full TeX distribution, and many applications. Note that optional packages should not conflict with each other. -

extra -

This contains all packages that conflict with others with required, important, standard or optional priorities, or are only likely to be useful if you already know what they are or have specialised requirements. -

-

+ +

Packages must not depend on packages with lower priority @@ -793,557 +783,639 @@

+ + + + + Binary packages + +

+ The Debian GNU/Linux distribution is based on the Debian + package management system, called dpkg. Thus, + all packages in the Debian distribution must be provided + in the .deb file format. +

+ - Binary packages + The package name + +

+ Every package must have a name that's unique within the Debian + archive. +

+ +

+ The package name is included in the control field + Package, the format of which is described + in . + The package name is also included as a part of the file name + of the .deb file. +

+ + + + The version of a package + +

+ Every package has a version number recorded in its + Version control file field, described in + . +

- The Debian GNU/Linux distribution is based on the Debian - package management system, called dpkg. Thus, - all packages in the Debian distribution must be provided - in the .deb file format.

+ The package management system imposes an ordering on version + numbers, so that it can tell whether packages are being up- or + downgraded and so that package system front end applications + can tell whether a package it finds available is newer than + the one installed on the system. The version number format + has the most significant parts (as far as comparison is + concerned) at the beginning. +

+

+ If an upstream package has problematic version numbers they + should be converted to a sane form for use in the + Version field. +

- The package name + Version numbers based on dates

- Every package must have a name that's unique within the Debian - archive.

+ In general, Debian packages should use the same version + numbers as the upstream sources. +

- Package names must consist only of lower case letters - (a-z), digits (0-9), plus (+) - and minus (-) signs, and periods (.). - They must be at least two characters long and must start - with an alphanumeric character. + However, in some cases where the upstream version number is + based on a date (e.g., a development "snapshot" release) the + package management system cannot handle these version + numbers without epochs. For example, dpkg will consider + "96May01" to be greater than "96Dec24".

- The package name is part of the file name of the - .deb file and is included in the control field - information. + To prevent having to use epochs for every new upstream + version, the date based portion of the version number + should be changed to the following format in such cases: + "19960501", "19961224". It is up to the maintainer whether + he/she wants to bother the upstream maintainer to change + the version numbers upstream, too.

- - - The maintainer of a package -

- Every package must have a Debian maintainer (the - maintainer may be one person or a group of people - reachable from a common email address, such as a mailing - list). The maintainer is responsible for ensuring that - the package is placed in the appropriate distributions. +

+ Note that other version formats based on dates which are + parsed correctly by the package management system should + not be changed.

- The maintainer must be specified in the - Maintainer control field with their correct name - and a working email address. If one person maintains - several packages, he/she should try to avoid having - different forms of their name and email address in - the Maintainer fields of those packages. + Native Debian packages (i.e., packages which have been + written especially for Debian) whose version numbers include + dates should always use the "YYYYMMDD" format.

+ -

- If the maintainer of a package quits from the Debian - project, "Debian QA Group" - packages@qa.debian.org takes over the - maintainership of the package until someone else - volunteers for that task. These packages are called - orphaned packages. -

+ + + + The maintainer of a package + +

+ Every package must have a Debian maintainer (the + maintainer may be one person or a group of people + reachable from a common email address, such as a mailing + list). The maintainer is responsible for ensuring that + the package is placed in the appropriate distributions. +

+ +

+ The maintainer must be specified in the + Maintainer control field with their correct name + and a working email address. If one person maintains + several packages, he/she should try to avoid having + different forms of their name and email address in + the Maintainer fields of those packages. +

+ +

+ The format of the Maintainer control field is + described in . +

+ +

+ If the maintainer of a package quits from the Debian + project, "Debian QA Group" + packages@qa.debian.org takes over the + maintainership of the package until someone else + volunteers for that task. These packages are called + orphaned packages. The detailed procedure for doing this gracefully can - be found in the Debian Developer's Reference, either - in the developers-reference package, or on - the Debian FTP server - ftp.debian.org as - /debian/doc/package-developer/developers-reference.txt.gz - or from the webpage. -

- -

- + be found in the Debian Developer's Reference, + see . + +

+ + + The description of a package - - The description of a package +

+ Every Debian package must have an extended description + stored in the appropriate field of the control record. + The technical information about the format of the + Description field is in . +

-

- Every Debian package must have an extended description - stored in the appropriate field of the control record.

+

+ The description should describe the package (the program) to a + user (system administrator) who has never met it before so that + they have enough information to decide whether they want to + install it. This description should not just be copied verbatim + from the program's documentation. +

+ +

+ Put important information first, both in the synopsis and + extended description. Sometimes only the first part of the + synopsis or of the description will be displayed. You can + assume that there will usually be a way to see the whole + extended description. +

+ +

+ The description should also give information about the + significant dependencies and conflicts between this package + and others, so that the user knows why these dependencies and + conflicts have been declared. +

+ +

+ Instructions for configuring or using the package should + not be included (that is what installation scripts, + manual pages, info files, etc., are for). Copyright + statements and other administrivia should not be included + either (that is what the copyright file is for). +

+ + The single line synopsis

- The description should be written so that it gives the - system administrator enough information to decide whether - to install the package. This description should not just - be copied verbatim from the program's documentation. - Instructions for configuring or using the package should - not be included (that is what installation scripts, - manual pages, info files, etc., are for). Copyright - statements and other administrivia should not be included - either (that is what the copyright file is for). + The single line synopsis should be kept brief - certainly + under 80 characters.

- Please refer to for more information. + Do not include the package name in the synopsis line. The + display software knows how to display this already, and you + do not need to state it. Remember that in many situations + the user may only see the synopsis line - make it as + informative as you can.

- - - Dependencies + The extended description

- Every package must specify the dependency information - about other packages that are required for the first to - work correctly.

+ Do not try to continue the single line synopsis into the + extended description. This will not work correctly when + the full description is displayed, and makes no sense + where only the summary (the single line synopsis) is + available. +

- For example, a dependency entry must be provided for any - shared libraries required by a dynamically-linked executable - binary in a package.

+ The extended description should describe what the package + does and how it relates to the rest of the system (in terms + of, for example, which subsystem it is which part of). +

- Packages are not required to declare any dependencies they - have on other packages which are marked Essential - (see below), and should not do so unless they depend on a - particular version of that package.

+ The description field needs to make sense to anyone, even + people who have no idea about any of the things the + package deals with. + The blurb that comes with a program in its + announcements and/or README files is + rarely suitable for use in a description. It is + usually aimed at people who are already in the + community where the package is used. + +

-

- Sometimes, a package requires another package to be installed - and configured before it can be installed. In this - case, you must specify a Pre-Depends entry for - the package.

+ -

- You should not specify a Pre-Depends entry for a - package before this has been discussed on the - debian-devel mailing list and a consensus about - doing that has been reached.

 + + + Dependencies - - Virtual packages +

+ Every package must specify the dependency information + about other packages that are required for the first to + work correctly. +

-

- Sometimes, there are several packages which offer - more-or-less the same functionality. In this case, it's - useful to define a virtual package whose name - describes that common functionality. (The virtual - packages only exist logically, not physically; that's why - they are called virtual.) The packages with this - particular function will then provide the virtual - package. Thus, any other package requiring that function - can simply depend on the virtual package without having to - specify all possible packages individually.

+

+ For example, a dependency entry must be provided for any + shared libraries required by a dynamically-linked executable + binary in a package. +

-

- All packages should use virtual package names where - appropriate, and arrange to create new ones if necessary. - They should not use virtual package names (except privately, - amongst a cooperating group of packages) unless they have - been agreed upon and appear in the list of virtual package - names. (See also )

+

+ Packages are not required to declare any dependencies they + have on other packages which are marked Essential + (see below), and should not do so unless they depend on a + particular version of that package. +

-

- The latest version of the authoritative list of virtual - package names can be found in the debian-policy package. - It's also available from the Debian web mirrors at - - and from the Debian archive mirrors at - . -

+

+ Sometimes, a package requires another package to be installed + and configured before it can be installed. In this + case, you must specify a Pre-Depends entry for + the package. +

-

- The procedure for updating the list is described in the preface - to the list. -

+

+ You should not specify a Pre-Depends entry for a + package before this has been discussed on the + debian-devel mailing list and a consensus about + doing that has been reached. +

- +

+ The format of the package interrelationship control fields is + described in . +

+ - - Base system + + Virtual packages -

- The base system is a minimum subset of the Debian - GNU/Linux system that is installed before everything else - on a new system. Thus, only very few packages are allowed - to go into the base section to keep the required - disk usage very small.

+

+ Sometimes, there are several packages which offer + more-or-less the same functionality. In this case, it's + useful to define a virtual package whose name + describes that common functionality. (The virtual + packages only exist logically, not physically; that's why + they are called virtual.) The packages with this + particular function will then provide the virtual + package. Thus, any other package requiring that function + can simply depend on the virtual package without having to + specify all possible packages individually. +

-

- Most of these packages will have the priority value - required or at least important, and many - of them will be tagged essential (see below).

+

+ All packages should use virtual package names where + appropriate, and arrange to create new ones if necessary. + They should not use virtual package names (except privately, + amongst a cooperating group of packages) unless they have + been agreed upon and appear in the list of virtual package + names. (See also ) +

+

+ The latest version of the authoritative list of virtual + package names can be found in the debian-policy package. + It is also available from the Debian web mirrors at + . +

- +

+ The procedure for updating the list is described in the preface + to the list. +

+ - - Essential packages + + Base system -

- Some packages are tagged essential. (They have - Essential: yes in their package control record.) - This flag is used for packages that are essential - for a system.

+

+ The base system is a minimum subset of the Debian + GNU/Linux system that is installed before everything else + on a new system. Thus, only very few packages are allowed + to go into the base section to keep the required + disk usage very small. +

-

- Since these packages cannot be easily removed (one has to - specify an extra force option to - dpkg to do so), this flag must not be used - unless absolutely necessary. A shared library package - must not be tagged essential; dependencies will - prevent its premature removal, and we need to be able to - remove it when it has been superseded. -

+

+ Most of these packages will have the priority value + required or at least important, and many + of them will be tagged essential (see below). +

+ -

- Since dpkg will not prevent upgrading of other packages - while an essential package is in an unconfigured + + Essential packages + +

+ Some packages are tagged essential for a system + using the Essential control file field. + The format of the Essential control field is + described in . +

+ +

+ Since these packages cannot be easily removed (one has to + specify an extra force option to + dpkg to do so), this flag must not be used + unless absolutely necessary. A shared library package + must not be tagged essential; dependencies will + prevent its premature removal, and we need to be able to + remove it when it has been superseded. +

+ +

+ Since dpkg will not prevent upgrading of other packages + while an essential package is in an unconfigured state, all essential packages must supply all of their core functionality even when unconfigured. If the package cannot satisfy this requirement it must not be tagged as essential, and any packages depending on this package must instead have explicit dependency fields as appropriate. -

+

-

- You must not tag any packages essential before - this has been discussed on the debian-devel - mailing list and a consensus about doing that has been - reached. -

- - - Tasks +

+ You must not tag any packages essential before + this has been discussed on the debian-devel + mailing list and a consensus about doing that has been + reached. +

+ -

- The Debian install process allows the user to choose from - a number of common tasks which a Debian system can be used to - perform. Selecting a task with tasksel causes - a set of packages that are useful in performing that task to be - installed. -

+ + Tasks -

- This set of packages is all available packages which have the - name of the selected task in the Task field of their - control file. The format of this field is a list of tasks, - separated by commas. -

+

+ The Debian install process allows the user to choose from + a number of common tasks which a Debian system can be used to + perform. Selecting a task with tasksel causes + a set of packages that are useful in performing that task to be + installed. +

-

- You should not tag any packages as belonging to a task - before this has been discussed on the - debian-devel mailing list and a consensus about - doing that has been reached. -

+

+ This set of packages is all available packages which have the + name of the selected task in the Task field of their + control file. The format of this field is a list of tasks, + separated by commas. +

-

- For third parties (and historical reasons), tasksel also - supports constructing tasks based on task - packages. These are packages whose names begin with - task-. Task packages should not be included in the - Debian archive. -

- +

+ You should not tag any packages as belonging to a task + before this has been discussed on the + debian-devel mailing list and a consensus about + doing that has been reached. +

- - Maintainer Scripts +

+ For third parties (and historical reasons), tasksel also + supports constructing tasks based on task + packages. These are packages whose names begin with + task-. Task packages should not be included in the + Debian archive. +

+ -

- The package installation scripts should avoid producing - output which it is unnecessary for the user to see and - should rely on dpkg to stave off boredom on - the part of a user installing many packages. This means, - amongst other things, using the --quiet option on - install-info.

+ + Maintainer Scripts -

- Errors which occur during the execution of an installation - script must be checked and the installation must not - continue after an error. -

+

+ The package installation scripts should avoid producing + output which is unnecessary for the user to see and + should rely on dpkg to stave off boredom on + the part of a user installing many packages. This means, + amongst other things, using the --quiet option on + install-info. +

-

- Note that in general applies to package - maintainer scripts, too. -

+

+ Errors which occur during the execution of an installation + script must be checked and the installation must not + continue after an error. +

+ +

+ Note that in general applies to package + maintainer scripts, too. +

+

+ You should not use dpkg-divert on a file + belonging to another package without consulting the + maintainer of that package first. +

+ +

+ All packages which supply an instance of a common command + name (or, in general, filename) should generally use + update-alternatives, so that they may be + installed together. If update-alternatives + is not used, then each package must use + Conflicts to ensure that other packages are + de-installed. (In this case, it may be appropriate to + specify a conflict against earlier versions of something + that previously did not use + update-alternatives; this is an exception to + the usual rule that versioned conflicts should be + avoided.) +

+ + + Prompting in maintainer scripts

- You should not use dpkg-divert on a file - belonging to another package without consulting the - maintainer of that package first. + Package maintainer scripts may prompt the user if + necessary. Prompting should be done by communicating + through a program, such as debconf, which + conforms to the Debian Configuration management + specification, version 2 or higher. Prompting the user by + other means, such as by hand + From the Jargon file: by hand 2. By extension, + writing code which does something in an explicit or + low-level way for which a presupplied library + (debconf, in this instance) routine ought + to have been available. + , is now deprecated.

- All packages which supply an instance of a common command - name (or, in general, filename) should generally use - update-alternatives, so that they may be - installed together. If update-alternatives - is not used, then each package must use - Conflicts to ensure that other packages are - de-installed. (In this case, it may be appropriate to - specify a conflict against earlier versions of something - that previously did not use - update-alternatives; this is an exception to - the usual rule that versioned conflicts should be - avoided.) + The Debian Configuration management specification is included + in the debconf_specification files in the + debian-policy package. + It is also available from the Debian web mirrors at + .

- - - Prompting in maintainer scripts -

- Package maintainer scripts may prompt the user if - necessary. Prompting may be accomplished by - hand -

From the Jasrgon file: by hand 2. By extension, - writing code which does something in an explicit or - low-level way for which a presupplied library - (debconf, in this instance) routine ought - to have been available.

- (but this is deprecated), or by - communicating though a program, which conforms to the - Debian Configuration management specification, version 2 - or higher (such as debconf). Thiss - specification is included in the - debconf_specification files in the - debian-policy package. You may also - find this file on the FTP site - ftp.debian.org in - /debian/doc/package-developer/debconf_specification.txt.gz - or on your local mirror. -

- 6% of Debian packages [see ] currently use - debconf to prompt the user at - install time, and this number is growing daily. The - benefits of using debconf are briefly explained at - ; they include - preconfiguration, (mostly) noninteractive - installation, elimination of redundant prompting, - consistency of user interface, etc. -

-

- With this increasing number of packages using - debconf, plus the existance of a - nascent second implementation of the Debian - configuration management system - (cdebconf), and the stabilization - of the protocol these things use, the time has - finally come to reflect the use of these things in - policy. - -

- -

-

- Packages which use the Debian Configuration management - specification may contain an additional - config script and a templates - file in their control archive. The config - script might be run before the preinst - script, and before the package is unpacked or any of its - dependencies or pre-dependancies are satisfied. - Therefore it must work using only the tools present in - essential packages. -

+

+ Packages which use the Debian Configuration management + specification may contain an additional + config script and a templates + file in their control archive + The control.tar.gz inside the .deb. + See . + . + The config script might be run before the + preinst script, and before the package is unpacked + or any of its dependencies or pre-dependancies are satisfied. + Therefore it must work using only the tools present in + essential packages. Debconf or another tool that implements the Debian Configuration management specification will also be installed, and any versioned dependencies on it will be satisfied before preconfiguration begins. -

- -

- -

- Packages should try to minimize the amount of prompting - they need to do, and they should ensure that the user - will only ever be asked each question once. This means - that packages should try to use appropriate shared - configuration files (such as /etc/papersize and - /etc/news/server), and shared - debconf variables rather than each - prompting for their own list of required pieces of - information. -

- -

- It also means that an upgrade should not ask the same - questions again, unless the user has used dpkg - --purge to remove the package's configuration. The - answers to configuration questions should be stored in an - appropriate place in /etc so that the user can - modify them, and how this has been done should be - documented.

- -

- If a package has a vitally important piece of - information to pass to the user (such as "don't run me - as I am, you must edit the following configuration files - first or you risk your system emitting badly-formatted - messages"), it should display this in the - config or postinst script and - prompt the user to hit return to acknowledge the - message. Copyright messages do not count as vitally - important (they belong in - /usr/share/doc/package/copyright); - neither do instructions on how to use a program (these - should be in on-line documentation, where all the users - can see them).

- -

- Any necessary prompting should almost always be confined - to the config or postinst - script. If it is done in the postinst, it - should be protected with a conditional so that - unnecessary prompting doesn't happen if a package's - installation fails and the postinst is - called with abort-upgrade, - abort-remove or abort-deconfigure.

- - - - - Source packages - - - Standards conformance - -

- In the source package's Standards-Version control - field, you should specify the most recent version number - of this policy document with which your package complied - when it was last updated. The current version number is - &version;. +

- This information may be used to file bug reports - automatically if your package becomes too much out of - date. + Packages should try to minimize the amount of prompting + they need to do, and they should ensure that the user + will only ever be asked each question once. This means + that packages should try to use appropriate shared + configuration files (such as /etc/papersize and + /etc/news/server), and shared + debconf variables rather than each + prompting for their own list of required pieces of + information.

- The version number has four components: major and minor - version number and major and minor patch level. When the - standards change in a way that requires every package to - change the major number will be changed. Significant - changes that will require work in many packages will be - signaled by a change to the minor number. The major patch - level will be changed for any change to the meaning of the - standards, however small; the minor patch level will be - changed when only cosmetic, typographical or other edits - are made which neither change the meaning of the document - nor affect the contents of packages.

+ It also means that an upgrade should not ask the same + questions again, unless the user has used + dpkg --purge to remove the package's configuration. + The answers to configuration questions should be stored in an + appropriate place in /etc so that the user can + modify them, and how this has been done should be + documented. +

- Thus only the first three components of the policy version - are significant in the Standards-Version control - field, and so either these three components or the all - four components may be specified. -

- In the past, people specified the full version number - in the Standards-Version field, for example "2.3.0.0". - Since minor patch-level changes don't introduce new - policy, it was thought it would be better to relax - policy and only require the first 3 components to be - specified, in this example "2.3.0". All four - components may still be used if someone wishes to do - so. -

- + If a package has a vitally important piece of + information to pass to the user (such as "don't run me + as I am, you must edit the following configuration files + first or you risk your system emitting badly-formatted + messages"), it should display this in the + config or postinst script and + prompt the user to hit return to acknowledge the + message. Copyright messages do not count as vitally + important (they belong in + /usr/share/doc/package/copyright); + neither do instructions on how to use a program (these + should be in on-line documentation, where all the users + can see them).

- You should regularly, and especially if your package has - become out of date, check for the newest Policy Manual - available and update your package, if necessary. When your - package complies with the new standards you should update the - Standards-Version source package field and - release it. -

- See the file upgrading-checklist for - information about policy which has changed between - different versions of this document. -

- + Any necessary prompting should almost always be confined + to the config or postinst + script. If it is done in the postinst, it + should be protected with a conditional so that + unnecessary prompting doesn't happen if a package's + installation fails and the postinst is + called with abort-upgrade, + abort-remove or abort-deconfigure.

+ - - Package relationships + -

- Source packages should specify which binary packages they - require to be installed or not to be installed in order to - build correctly. For example, if building a package - requires a certain compiler, then the compiler should be - specified as a build-time dependency. -

-

- It is not necessary to explicitly specify build-time - relationships on a minimal set of packages that are always - needed to compile, link and put in a Debian package a - standard "Hello World!" program written in C or C++. The - required packages are called build-essential, and - an informational list can be found in - /usr/share/doc/build-essential/list (which is - contained in the build-essential - package). -

Rationale: - - -

This allows maintaining the list separately - from the policy documents (the list does not - need the kind of control that the policy - documents do). -

- - -

- Having a separate package allows one to install - the build-essential packages on a machine, as - well as allowing other packages such as tasks to - require installation of the build-essential - packages using the depends relation. -

+ + Source packages + + + Standards conformance + +

+ Source packages should specify the most recent version number + of this policy document with which your package complied + when it was last updated. +

+ +

+ This information may be used to file bug reports + automatically if your package becomes too much out of date. +

+ +

+ The version is specified in the Standards-Version + control field. + The format of the Standards-Version field is + described in . +

+ +

+ You should regularly, and especially if your package has + become out of date, check for the newest Policy Manual + available and update your package, if necessary. When your + package complies with the new standards you should update the + Standards-Version source package field and + release it. + See the file upgrading-checklist for + information about policy which has changed between + different versions of this document. + +

+ + + + + Package relationships + +

+ Source packages should specify which binary packages they + require to be installed or not to be installed in order to + build correctly. For example, if building a package + requires a certain compiler, then the compiler should be + specified as a build-time dependency. +

+ +

+ It is not necessary to explicitly specify build-time + relationships on a minimal set of packages that are always + needed to compile, link and put in a Debian package a + standard "Hello World!" program written in C or C++. The + required packages are called build-essential, and + an informational list can be found in + /usr/share/doc/build-essential/list (which is + contained in the build-essential + package). + Rationale: + + + This allows maintaining the list separately + from the policy documents (the list does not + need the kind of control that the policy + documents do). + + + Having a separate package allows one to install + the build-essential packages on a machine, as + well as allowing other packages such as tasks to + require installation of the build-essential + packages using the depends relation. -

The separate package allows bug reports against the list to be categorized separately from the policy management process in the BTS. -

-

- - -

+ +

-

- When specifying the set of build-time dependencies, one - should list only those packages explicitly required by the - build. It is not necessary to list packages which are - required merely because some other package in the list of - build-time dependencies depends on them. -

+

+ When specifying the set of build-time dependencies, one + should list only those packages explicitly required by the + build. It is not necessary to list packages which are + required merely because some other package in the list of + build-time dependencies depends on them. The reason for this is that dependencies change, and you should list all those packages, and only those packages that you need directly. What @@ -1355,546 +1427,308 @@ them: installation of libimlib2-dev will automatically ensure that all of its run-time dependencies are satisfied. -

- -

- -

- If build-time dependencies are specified, it must be - possible to build the package and produce working binaries - on a system with only essential and build-essential - packages installed and also those required to satisfy the - build-time relationships (including any implied - relationships). In particular, this means that version - clauses should be used rigorously in build-time - relationships so that one cannot produce bad or - inconsistently configured packages when the relationships - are properly satisfied. -

- -

- explains the technical details. -

- - - Changes to the upstream sources - -

- If changes to the source code are made that are not - specific to the needs of the Debian system, they should be - sent to the upstream authors in whatever form they prefer - so as to be included in the upstream version of the - package.

+ +

-

- If you need to configure the package differently for - Debian or for Linux, and the upstream source doesn't - provide a way to do so, you should add such configuration - facilities (for example, a new autoconf test - or #define) and send the patch to the upstream - authors, with the default set to the way they originally - had it. You can then easily override the default in your - debian/rules or wherever is appropriate.

+

+ If build-time dependencies are specified, it must be + possible to build the package and produce working binaries + on a system with only essential and build-essential + packages installed and also those required to satisfy the + build-time relationships (including any implied + relationships). In particular, this means that version + clauses should be used rigorously in build-time + relationships so that one cannot produce bad or + inconsistently configured packages when the relationships + are properly satisfied. +

-

- You should make sure that the configure utility - detects the correct architecture specification string - (refer to for details).

+

+ explains the technical details. +

+ -

- If you need to edit a Makefile where - GNU-style configure scripts are used, you - should edit the .in files rather than editing the - Makefile directly. This allows the user to - reconfigure the package if necessary. You should - not configure the package and edit the generated - Makefile! This makes it impossible for - someone else to later reconfigure the package.

+ + Changes to the upstream sources -

- You should document your changes and updates to the source - package properly in the debian/changelog file. - For more information, please see . -

- +

+ If changes to the source code are made that are not + specific to the needs of the Debian system, they should be + sent to the upstream authors in whatever form they prefer + so as to be included in the upstream version of the + package. +

+

+ If you need to configure the package differently for + Debian or for Linux, and the upstream source doesn't + provide a way to do so, you should add such configuration + facilities (for example, a new autoconf test + or #define) and send the patch to the upstream + authors, with the default set to the way they originally + had it. You can then easily override the default in your + debian/rules or wherever is appropriate. +

- - Error trapping in makefiles +

+ You should make sure that the configure utility + detects the correct architecture specification string + (refer to for details). +

-

- When make invokes a command in a makefile - (including your package's upstream makefiles and - debian/rules), it does so using sh. This - means that sh's usual bad error handling - properties apply: if you include a miniature script as one - of the commands in your makefile you'll find that if you - don't do anything about it then errors are not detected - and make will blithely continue after - problems.

+

+ If you need to edit a Makefile where GNU-style + configure scripts are used, you should edit the + .in files rather than editing the + Makefile directly. This allows the user to + reconfigure the package if necessary. You should + not configure the package and edit the generated + Makefile! This makes it impossible for someone + else to later reconfigure the package without losing the + changes you made. +

-

- Every time you put more than one shell command (this - includes using a loop) in a makefile command you - must make sure that errors are trapped. For - simple compound commands, such as changing directory and - then running a program, using && rather - than semicolon as a command separator is sufficient. For - more complex commands including most loops and - conditionals you should include a separate set -e - command at the start of every makefile command that's - actually one of these miniature shell scripts.

 + + + Debian changelog: debian/changelog - - Obsolete constructs and libraries +

+ Changes in the Debian version of the package should be + briefly explained in the Debian changelog file + debian/changelog. This includes modifications + made in the Debian package compared to the upstream one + as well as other changes and updates to the package. + + Although there is nothing stopping an author who is also + the Debian maintainer from using this changelog for all + their changes, it will have to be renamed if the Debian + and upstream maintainers become different people. In such + a case, however, it might be better to maintain the package + as a non-native package. + +

-

- The include file <varargs.h> is - provided to support end-users compiling very old software; - the library libtermcap is provided to support the - execution of software which has been linked against it - (either old programs or those such as Netscape which are - only available in binary form).

+

+ Mistakes in changelogs are usually best rectified by making + a new changelog entry rather than "rewriting history" by + editing old changelog entries. +

-

- Debian packages should be patched to use - <stdarg.h> and ncurses - instead. -

- - - +

+ The format of the debian/changelog allows the + package building tools to discover which version of the package + is being built and find out other release-specific information. +

- Control files and their fields +

+ That format is a series of entries like this: -

- Many of the tools in the package management suite manipulate - data represented in a common format, known as control - data. The data is often stored in control - files. Binary and source packages have control files, - and the .changes files which control the installation - of uploaded files are also in control file format. - dpkg's internal databases are in a similar - format. -

+ +package (version) distribution(s); urgency=urgency + + [optional blank line(s), stripped] + + * change details + more change details + + [blank line(s), included in output of dpkg-parsechangelog] + + * even more change details + + [optional blank line(s), stripped] + + -- maintainer name <email address>[two spaces] date + +

- Syntax of control files +

+ package and version are the source + package name and version number. +

- A control file consists of one or more paragraphs of fields. - The paragraphs are separated by blank lines. Some control - files allow only one paragraph; others allow several, in - which case each paragraph usually refers to a different - package. (For example, in source packages, the first - paragraph refers to the source package, and later paragraphs - refer to binary packages generated from the source.) + distribution(s) lists the distributions where + this version should be installed when it is uploaded - it + is copied to the Distribution field in the + .changes file. See .

- Each paragraph consists of a series of data fields; each - field consists of the field name, followed by a colon and - then the data/value associated with that field. It ends at - the end of the line. Horizontal whitespace (spaces and - tabs) may occur immediately before or after the value and is - ignored there; it is conventional to put a single space - after the colon. For example, a field might be: - -Package: libc6 - - the field name is Package and the field value - libc6. + urgency is the value for the Urgency + field in the .changes file for the upload + (see ). It is not possible to specify + an urgency containing commas; commas are used to separate + keyword=value settings in the + dpkg changelog format (though there is + currently only one useful keyword, + urgency). + Recognised urgency values are low, + medium, high and emergency. + They have an effect on how quickly a package will be + considered for inclusion into the testing + distribution, and give an indication of the importance + of any fixes included in this upload. +

- Some fields' values may span several lines; in this case - each continuation line must start with a space or - tab. Any trailing spaces or tabs at the end of individual - lines of a field value are ignored. + The change details may in fact be any series of lines + starting with at least two spaces, but conventionally each + change starts with an asterisk and a separating space and + continuation lines are indented so as to bring them in + line with the start of the text above. Blank lines may be + used here to separate groups of changes, if desired.

- Except where otherwise stated only a single line of data is - allowed and whitespace is not significant in a field body. - Whitespace must not appear inside names (of packages, - architectures, files or anything else) or version numbers, - or between the characters of multi-character version - relationships. + If this upload resolves bugs recorded in the Bug Tracking + System (BTS), they may be automatically closed on the + inclusion of this package into the Debian archive by + including the string: closes: Bug#nnnnn + in the change details. + To be precise, the string should match the following + Perl regular expression: + +/closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i + + Then all of the bug numbers listed will be closed by the + archive maintenance script (katie), or in + the case of an NMU, marked as fixed. + + This information is conveyed via the Closes field + in the .changes file (see ).

- Field names are not case-sensitive, but it is usual to - capitalize the field names using mixed case as shown below. + The maintainer name and email address used in the changelog + should be the details of the person uploading this + version. They are not necessarily those of the + usual package maintainer. The information here will be + copied to the Changed-By field in the + .changes file (see ), + and then later used to send an acknowledgement when the + upload has been installed.

- Blank lines, or lines consisting only of spaces and tabs, - are not allowed within field values or between fields - that - would mean a new paragraph. + The date should be in RFC822 format + This is generated by the 822-date + program. + ; it should include the time zone specified + numerically, with the time zone name or abbreviation + optionally present as a comment in parentheses.

- +

+ The first "title" line with the package name should start + at the left hand margin; the "trailer" line with the + maintainer and date details should be preceded by exactly + one space. The maintainer details and the date must be + separated by exactly two spaces. +

- List of fields

- This list here is not supposed to be exhaustive. Most fields - are dealt with elsewhere in this document. + For more information on placement of the changelog files + within binary packages, please see .

- Package - + + Alternative changelog formats

- The name of the binary package. Package names consist of - lower case letters (a-z), digits (0-9), - plus (+) and minus (-) signs, and - periods (.). + In non-experimental packages you must use a format for + debian/changelog which is supported by the most + recent released version of dpkg.

- They must be at least two characters long and must start - with an alphanumeric character. The use of lowercase - package names is required unless the package you're - building (or referring to, in other fields) is already - using uppercase characters.

+ It is possible to use a format different from the standard + one by providing a changelog parser for the format you wish + to use. The parser must have an API compatible with that + expected by dpkg-genchanges and + dpkg-gencontrol, and it must not interact with + the user at all. + + If there is general interest in the new format, you should + contact the dpkg maintainer to have the + parser script for it included in the dpkg + package. (You will need to agree that the parser and its + man page may be distributed under the GNU GPL, just as the rest + of dpkg is.) + +

+ - Version - + + Error trapping in makefiles -

- This lists the source or binary package's version number - - see . -

+

+ When make invokes a command in a makefile + (including your package's upstream makefiles and + debian/rules), it does so using sh. This + means that sh's usual bad error handling + properties apply: if you include a miniature script as one + of the commands in your makefile you'll find that if you + don't do anything about it then errors are not detected + and make will blithely continue after + problems. +

- +

+ Every time you put more than one shell command (this + includes using a loop) in a makefile command you + must make sure that errors are trapped. For + simple compound commands, such as changing directory and + then running a program, using && rather + than semicolon as a command separator is sufficient. For + more complex commands including most loops and + conditionals you should include a separate set -e + command at the start of every makefile command that's + actually one of these miniature shell scripts. +

+ - Standards-Version - + + Time Stamps +

+ Maintainers should preserve the modification times of the + upstream source files in a package, as far as is reasonably + possible. + The rationale is that there is some information conveyed + by knowing the age of the file, for example, you could + recognize that some documentation is very old by looking + at the modification time, so it would be nice if the + modification time of the upstream source would be + preserved. + +

+ -

- The most recent version of the standards (the policy - manual and associated texts) with which the package - complies. This is updated manually when editing the - source package to conform to newer standards; it can - sometimes be used to tell when a package needs attention. - Its format is described above; see - . -

- + + Restrictions on objects in source packages +

+ The source package may not contain any hard links +

+ This is not currently detected when building source + packages, but only when extracting + them. +

+

+ Hard links may be permitted at some point in the + future, but would require a fair amount of + work. +

+ , device special files, sockets or setuid or + setgid files. + Setgid directories are allowed. + +

+ - Distribution - - -

- In a .changes file or parsed changelog output - this contains the (space-separated) name(s) of the - distribution(s) where this version of the package should - be installed. Valid distributions are determined by the - archive maintainers. - Current distribution names are: - - stable - -

- This is the current "released" version of Debian - GNU/Linux. Once the distribution is - stable only security fixes and other - major bug fixes are allowed. When changes are - made to this distribution, the release number is - increased (for example: 2.2r1 becomes 2.2r2 then - 2.2r3, etc). -

- - - unstable - -

- This distribution value refers to the - developmental part of the Debian - distribution tree. New packages, new upstream - versions of packages and bug fixes go into the - unstable directory tree. Download from - this distribution at your own risk. -

- - - testing - -

- This distribution value refers to the - testing part of the Debian distribution - tree. It receives its packages from the - unstable distribution after a short time lag to - ensure that there are no major issues with the - unstable packages. It is less prone to breakage - than unstable, but still risky. It is not - possible to upload packages directly to - testing. -

- - - frozen - -

- From time to time, the testing - distribution enters a state of "code-freeze" in - anticipation of release as a stable - version. During this period of testing only - fixes for existing or newly-discovered bugs will - be allowed. The exact details of this stage are - determined by the Release Manager. -

- - - experimental - -

- The packages with this distribution value are - deemed by their maintainers to be high - risk. Oftentimes they represent early beta or - developmental packages from various sources that - the maintainers want people to try, but are not - ready to be a part of the other parts of the - Debian distribution tree. Download at your own - risk. -

- - - - You should list all distributions that the - package should be installed into. - -

- - - - - - - Version numbering - -

- Every package has a version number recorded in its - Version control file field. -

- -

- The package management system imposes an ordering on version - numbers, so that it can tell whether packages are being up- or - downgraded and so that package system front end applications - can tell whether a package it finds available is newer than - the one installed on the system. The version number format - has the most significant parts (as far as comparison is - concerned) at the beginning. -

- -

- The version number format is: - [epoch:]upstream_version[-debian_revision] -

- -

- The three components here are: - - epoch - -

- This is a single (generally small) unsigned integer. It - may be omitted, in which case zero is assumed. If it is - omitted then the upstream_version may not - contain any colons. -

- -

- It is provided to allow mistakes in the version numbers - of older versions of a package, and also a package's - previous version numbering schemes, to be left behind. -

- - - upstream_version - -

- This is the main part of the version number. It is - usually the version number of the original ("upstream") - package from which the .deb file has been made, - if this is applicable. Usually this will be in the same - format as that specified by the upstream author(s); - however, it may need to be reformatted to fit into the - package management system's format and comparison - scheme. -

- -

- The comparison behavior of the package management system - with respect to the upstream_version is - described below. The upstream_version - portion of the version number is mandatory. -

- -

- The upstream_version may contain only - alphanumerics -

Alphanumerics are A-Za-z0-9 only.

- - and the characters . + - - : (full stop, plus, hyphen, colon) and should - start with a digit. If there is no - debian_revision then hyphens are not allowed; - if there is no epoch then colons are not - allowed.

- - - debian_revision - -

- This part of the version number specifies the version of - the Debian package based on the upstream version. It - may contain only alphanumerics and the characters - + and . (plus and full stop) and is - compared in the same way as the - upstream_version is. -

- -

- It is optional; if it isn't present then the - upstream_version may not contain a hyphen. - This format represents the case where a piece of - software was written specifically to be turned into a - Debian package, and so there is only one "debianization" - of it and therefore no revision indication is required. -

- -

- It is conventional to restart the - debian_revision at 1 each time the - upstream_version is increased. -

- -

- The package management system will break the version - number apart at the last hyphen in the string (if there - is one) to determine the upstream_version and - debian_revision. The absence of a - debian_revision compares earlier than the - presence of one (but note that the - debian_revision is the least significant part - of the version number). -

- - -

- -

- The upstream_version and debian_revision - parts are compared by the package management system using the - same algorithm: -

- -

- The strings are compared from left to right. -

- -

- First the initial part of each string consisting entirely of - non-digit characters is determined. These two parts (one of - which may be empty) are compared lexically. If a difference - is found it is returned. The lexical comparison is a - comparison of ASCII values modified so that all the letters - sort earlier than all the non-letters. -

- -

- Then the initial part of the remainder of each string which - consists entirely of digit characters is determined. The - numerical values of these two parts are compared, and any - difference found is returned as the result of the comparison. - For these purposes an empty string (which can only occur at - the end of one or both version strings being compared) counts - as zero. -

- -

- These two steps (comparing and removing initial non-digit - strings and initial digit strings) are repeated until a - difference is found or both strings are exhausted. -

- -

- Note that the purpose of epochs is to allow us to leave behind - mistakes in version numbering, and to cope with situations - where the version numbering scheme changes. It is - not intended to cope with version numbers containing - strings of letters which the package management system cannot - interpret (such as ALPHA or pre-), or with - silly orderings (the author of this manual has heard of a - package whose versions went 1.1, 1.2, - 1.3, 1, 2.1, 2.2, - 2 and so forth). -

- -

- If an upstream package has problematic version numbers they - should be converted to a sane form for use in the - Version field. -

- - - Version numbers based on dates -

- In general, Debian packages should use the same version - numbers as the upstream sources.

- -

- However, in some cases where the upstream version number is - based on a date (e.g., a development "snapshot" release) the - package management system cannot handle these version - numbers without epochs. For example, dpkg will consider - "96May01" to be greater than "96Dec24".

- -

- To prevent having to use epochs for every new upstream - version, the version number should be changed to the - following format in such cases: "19960501", "19961224". It - is up to the maintainer whether he/she wants to bother the - upstream maintainer to change the version numbers upstream, - too.

- -

- Note that other version formats based on dates which are - parsed correctly by the package management system should - not be changed.

- -

- Native Debian packages (i.e., packages which have been - written especially for Debian) whose version numbers include - dates should always use the "YYYYMMDD" format.

- - - - Packaging Considerations - - Time Stamps -

- Maintainers should preserve the modification times of the - upstream source files in a package, as far as is reasonably - possible. -

- The rationale is that there is some information conveyed - by knowing the age of the file, for example, you could - recognize that some documentation is very old by looking - at the modification time, so it would be nice if the - modification time of the upstream source would be - preserved. -

- -

- - - debian/rules - the - main building script + + Main building script: debian/rules

This file must be an executable makefile, and contains the @@ -1922,15 +1756,14 @@ Package: libc6

- The required and optional targets are as follows: + The targets are as follows (required unless stated otherwise): - build, build-arch (optional), - build-indep (optional) + build

- The build target should perform all - non-interactive configuration and compilation of the - package. If a package has an interactive pre-build + The build target should perform all the + configuration and compilation of the package. + If a package has an interactive pre-build configuration routine, the Debianized source package must either be built after this has taken place (so that the binary package can be built without rerunning @@ -1973,7 +1806,6 @@ Package: libc6 complete. This will ensure that if debian/rules build is run again it will not rebuild the whole program. -

Another common way to do this is for build to depend on build-stamp and to do nothing else, and for the build-stamp @@ -1986,11 +1818,50 @@ Package: libc6 .PHONY target). See the documentation of make for more information on phony targets. -

+ build-arch (optional), + build-indep (optional) + + +

+ A package may also provide both of the targets + build-arch and build-indep. + The build-arch target, if provided, should + perform all the configuration and compilation required + for producing all architecture-dependant binary packages + (those packages for which the body of the + Architecture field in debian/control + is not all). + Similarly, the build-indep target, if + provided, should perform all the configuration and + compilation required for producing all + architecture-independent binary packages + (those packages for which the body of the + Architecture field in debian/control + is all). + The build target should depend on those of the + targets build-arch and build-indep that + are provided in the rules file. +

+ +

+ If one or both of the targets build-arch and + build-indep are not provided, then invoking + debian/rules with one of the not-provided + targets as arguments should produce a exit status code + of 2. Usually this is provided automatically by make + if the target is missing. +

+ +

+ The build-arch and build-indep targets + must not do anything that might require root privilege. +

+ + binary, binary-arch, binary-indep @@ -1998,8 +1869,7 @@ Package: libc6

The binary target must be all that is necessary for the user to build the binary package(s) - produced from this source package. All of these - targets are required to be non-interactive. It is + produced from this source package. It is split into two parts: binary-arch builds the binary packages which are specific to a particular architecture, and binary-indep builds @@ -2034,11 +1904,9 @@ Package: libc6

The binary targets must be invoked as root. -

The fakeroot package often allows one to build a package correctly even without being root. -

@@ -2050,7 +1918,7 @@ Package: libc6 and binary targets may have had, except that it should leave alone any output files created in the parent directory by a run of a binary - target. This target must be non-interactive. + target.

@@ -2113,7 +1981,8 @@ Package: libc6

The architectures we build on and build for are determined by make variables using the utility - dpkg-architecture. You can determine the + dpkg-architecture. + You can determine the Debian architecture and the GNU style architecture specification string for the build machine (the machine type we are building on) as well as for the host machine (the @@ -2121,19 +1990,19 @@ Package: libc6 supported make variables: -

DEB_*_ARCH (the Debian architecture)

+ DEB_*_ARCH (the Debian architecture) -

DEB_*_GNU_TYPE (the GNU style architecture - specification string)

+ DEB_*_GNU_TYPE (the GNU style architecture + specification string) -

DEB_*_GNU_CPU (the CPU part of - DEB_*_GNU_TYPE)

+ DEB_*_GNU_CPU (the CPU part of + DEB_*_GNU_TYPE) -

DEB_*_GNU_SYSTEM (the System part of - DEB_*_GNU_TYPE)

+ DEB_*_GNU_SYSTEM (the System part of + DEB_*_GNU_TYPE) where * is either BUILD for specification of the build machine or HOST for specification of the @@ -2156,340 +2025,751 @@ Package: libc6

- debian/changelog - + + + Variable substitutions: debian/substvars

- This file records the changes to the Debian-specific parts of the - package -

- Though there is nothing stopping an author who is also - the Debian maintainer from using it for all their - changes, it will have to be renamed if the Debian and - upstream maintainers become different people. In such a - case, however, it might be better to maintain the - package as a non-native package. -

- . + When dpkg-gencontrol, + dpkg-genchanges and dpkg-source + generate control files they perform variable substitutions + on their output just before writing it. Variable + substitutions have the form ${variable}. + The optional file debian/substvars contains + variable substitutions to be used; variables can also be set + directly from debian/rules using the -V + option to the source packaging commands, and certain + predefined variables are also available.

- It has a special format which allows the package building - tools to discover which version of the package is being - built and find out other release-specific information. + The debian/substvars file is usually generated and + modified dynamically by debian/rules targets, in + which case it must be removed by the clean target.

- That format is a series of entries like this: - -package (version) distribution(s); urgency=urgency - -

[optional blank line(s), stripped]

- - * change details - more change details - -

[blank line(s), included in output of dpkg-parsechangelog]

- - * even more change details - -

[optional blank line(s), stripped]

- - -- maintainer name <email - address>[two spaces] date - -

+ See for full + details about source variable substitutions, including the + format of debian/substvars.

+ + + + Generated files list: debian/files

- package and version are the source - package name and version number. + This file is not a permanent part of the source tree; it + is used while building packages to record which files are + being generated. dpkg-genchanges uses it + when it generates a .changes file.

- distribution(s) lists the distributions where - this version should be installed when it is uploaded - it - is copied to the Distribution field in the - .changes file. See . + It should not exist in a shipped source package, and so it + (and any backup files or temporary files such as + files.new + files.new is used as a temporary file by + dpkg-gencontrol and + dpkg-distaddfile - they write a new + version of files here before renaming it, + to avoid leaving a corrupted copy if an error + occurs. + ) should be removed by the + clean target. It may also be wise to + ensure a fresh start by emptying or removing it at the + start of the binary target.

- urgency is the value for the Urgency - field in the .changes file for the upload. It is - not possible to specify an urgency containing commas; commas - are used to separate - keyword=value settings in the - dpkg changelog format (though there is - currently only one useful keyword, - urgency). -

- Recognised urgency values are low, - medium, high and emergency. - They have an effect on how quickly a package will be - considered for inclusion into the testing - distribution, and give an indication of the importance - of any fixes included in this upload. -

- + When dpkg-gencontrol is run for a binary + package, it adds an entry to debian/files for the + .deb file that will be created when dpkg-deb + --build is run for that binary package. So for most + packages all that needs to be done with this file is to + delete it in the clean target.

- The change details may in fact be any series of lines - starting with at least two spaces, but conventionally each - change starts with an asterisk and a separating space and - continuation lines are indented so as to bring them in - line with the start of the text above. Blank lines may be - used here to separate groups of changes, if desired. + If a package upload includes files besides the source + package and any binary packages whose control files were + made with dpkg-gencontrol then they should be + placed in the parent of the package's top-level directory + and dpkg-distaddfile should be called to add + the file to the list in debian/files.

+ + + + + + + Control files and their fields + +

+ The package management system manipulates data represented in + a common format, known as control data, stored in + control files. + Control files are used for source packages, binary packages and + the .changes files which control the installation + of uploaded files + dpkg's internal databases are in a similar + format. + . +

+ + + Syntax of control files + +

+ A control file consists of one or more paragraphs of + fields + The paragraphs are also sometimes referred to as stanzas. + . + The paragraphs are separated by blank lines. Some control + files allow only one paragraph; others allow several, in + which case each paragraph usually refers to a different + package. (For example, in source packages, the first + paragraph refers to the source package, and later paragraphs + refer to binary packages generated from the source.)

- If this upload resolves bugs recorded in the Bug Tracking - System (BTS), they may be automatically closed on the - inclusion of this package into the Debian archive by - including the string: closes: Bug#nnnnn - in the change details. -

- To be precise, the string should match the following - Perl regular expression: - -/closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i - - Then all of the bug numbers listed will be closed by the - archive maintenance script (katie), or in - the case of an NMU, marked as fixed. -

- + Each paragraph consists of a series of data fields; each + field consists of the field name, followed by a colon and + then the data/value associated with that field. It ends at + the end of the line. Horizontal whitespace (spaces and + tabs) may occur immediately before or after the value and is + ignored there; it is conventional to put a single space + after the colon. For example, a field might be: + +Package: libc6 + + the field name is Package and the field value + libc6.

- The maintainer name and email address used in the changelog - should be the details of the person uploading this - version. They are not necessarily those of the - usual package maintainer. The information here will be - copied to the Changed-By field in the - .changes file, and then later used to send an - acknowledgement when the upload has been installed. + Some fields' values may span several lines; in this case + each continuation line must start with a space or a tab. + Any trailing spaces or tabs at the end of individual + lines of a field value are ignored.

- The date should be in RFC822 format -

- This is generated by the 822-date - program. -

- ; it should include the time zone specified - numerically, with the time zone name or abbreviation - optionally present as a comment in parentheses. + Except where otherwise stated, only a single line of data is + allowed and whitespace is not significant in a field body. + Whitespace must not appear inside names (of packages, + architectures, files or anything else) or version numbers, + or between the characters of multi-character version + relationships.

- The first "title" line with the package name should start - at the left hand margin; the "trailer" line with the - maintainer and date details should be preceded by exactly - one space. The maintainer details and the date must be - separated by exactly two spaces. + Field names are not case-sensitive, but it is usual to + capitalize the field names using mixed case as shown below.

- Defining alternative changelog formats +

+ Blank lines, or lines consisting only of spaces and tabs, + are not allowed within field values or between fields - that + would mean a new paragraph. +

-

- It is possible to use a different format to the standard - one, by providing a parser for the format you wish to - use. -

-

- A changelog parser must not interact with the user at - all. -

- - - - debian/substvars - and variable substitutions + + Source package control files -- debian/control

- When dpkg-gencontrol, - dpkg-genchanges and dpkg-source - generate control files they perform variable substitutions - on their output just before writing it. Variable - substitutions have the form ${variable}. - The optional file debian/substvars contains - variable substitutions to be used; variables can also be set - directly from debian/rules using the -V - option to the source packaging commands, and certain - predefined variables are also available. + The debian/control file contains the most vital + (and version-independent) information about the source package + and about the binary packages it creates.

- The debian/substvars file is usually generated and - modified dynamically by debian/rules targets, in - which case it must be removed by the clean target. + The first paragraph of the control file contains information about + the source package in general. The subsequent sets each describe a + binary package that the source tree builds.

- See for full - details about source variable substitutions, including the - format of debian/substvars.

- + The fields in the general paragraph (the first one, for the source + package) are: - debian/files - + + Source (mandatory) + Maintainer (mandatory) + Section (recommended) + Priority (recommended) + Build-Depends et al + Standards-Version (recommended) + +

- This file is not a permanent part of the source tree; it - is used while building packages to record which files are - being generated. dpkg-genchanges uses it - when it generates a .changes file. + The fields in the binary package paragraphs are: + + + Package (mandatory) + Architecture (mandatory) + Section (recommended) + Priority (recommended) + Essential + Depends et al + Description (mandatory) +

- It should not exist in a shipped source package, and so it - (and any backup files or temporary files such as - files.new -

- files.new is used as a temporary file by - dpkg-gencontrol and - dpkg-distaddfile - they write a new - version of files here before renaming it, - to avoid leaving a corrupted copy if an error - occurs -

- ) should be removed by the - clean target. It may also be wise to - ensure a fresh start by emptying or removing it at the - start of the binary target. + The syntax and semantics of the fields are described below.

+ +

- When dpkg-gencontrol is run for a binary - package, it adds an entry to debian/files for the - .deb file that will be created when dpkg-deb - --build is run for that binary package. So for most - packages all that needs to be done with this file is to - delete it in the clean target. + These fields are used by dpkg-gencontrol to + generate control files for binary packages (see below), by + dpkg-genchanges to generate the + .changes file to accompany the upload, and by + dpkg-source when it creates the .dsc + source control file as part of a source archive.

- If a package upload includes files besides the source - package and any binary packages whose control files were - made with dpkg-gencontrol then they should be - placed in the parent of the package's top-level directory - and dpkg-distaddfile should be called to add - the file to the list in debian/files.

+ The fields here may contain variable references - their + values will be substituted by dpkg-gencontrol, + dpkg-genchanges or dpkg-source + when they generate output control files. + See for details. +

+ - Restrictions on objects in source packages - + + Binary package control files -- DEBIAN/control

- The source package may not contain any hard links -

- This is not currently detected when building source - packages, but only when extracting - them. -

-

- Hard links may be permitted at some point in the - future, but would require a fair amount of - work. -

- , device special files, sockets or setuid or - setgid files. -

- Setgid directories are allowed. -

- + The DEBIAN/control file contains the most vital + (and version-dependent) information about a binary package. +

+ +

+ The fields in this file are: + + + Package (mandatory) + Source + Version (mandatory) + Section (recommended) + Priority (recommended) + Architecture (mandatory) + Essential + Depends et al + Installed-Size + Maintainer (mandatory) + Description (mandatory) +

- Descriptions of packages - the - Description field + + Debian source control files -- .dsc + +

+ This file contains a series of fields, identified and + separated just like the fields in the control file of + a binary package. The fields are listed below; their + syntax is described above, in . + + + Format + Source (mandatory) + Version (mandatory) + Maintainer (mandatory) + Binary + Architecture + Build-Depends et al + Standards-Version (recommended) + Files (mandatory) + +

- The "Description" control file field consists of two parts, - the synopsis or the short description, and the long description. - The field's format is as follows: + The source package control file is generated by + dpkg-source when it builds the source + archive, from other files in the source package, + described above. When unpacking, it is checked against + the files and directories in the other parts of the + source package.

-

- Description: <single line synopsis> - <extended description over several lines> -

+ + + + Debian changes files -- .changes

- The description is intended to describe the program to a user - who has never met it before so that they know whether they - want to install it. It should also give information about the - significant dependencies and conflicts between this package - and others, so that the user knows why these dependencies and - conflicts have been declared. + The .changes files are used by the Debian archive maintenance + software to process updates to packages. They contain one + paragraph which contains information from the + debian/control file and other data about the + source package gathered via debian/changelog + and debian/rules.

- Put important information first, both in the synopsis and - extended description. Sometimes only the first part of the - synopsis or of the description will be displayed. You can - assume that there will usually be a way to see the whole - extended description. + The fields in this file are: + + + Format (mandatory) + Date (mandatory) + Source (mandatory) + Binary (mandatory) + Architecture (mandatory) + Version (mandatory) + Distribution (mandatory) + Urgency (recommended) + Maintainer (mandatory) + Changed-By + Description (mandatory) + Closes + Changes (mandatory) + Files (mandatory) +

+ - The single line synopsis + + List of fields + + + Source

- The single line synopsis should be kept brief - certainly - under 80 characters. + This field identifies the source package name.

- Do not include the package name in the synopsis line. The - display software knows how to display this already, and you - do not need to state it. Remember that in many situations - the user may only see the synopsis line - make it as - informative as you can. + In a main source control information, a .changes + or a .dsc file this may contain only the name + of the source package.

+

+ In the control file of a binary package it may be followed + by a version number in parentheses + It is customary to leave a space after the package name + if a version number is specified. + . + This version number may be omitted (and is, by + dpkg-gencontrol) if it has the same value as + the Version field of the binary package in + question. The field itself may be omitted from a binary + package control file when the source package has the same + name and version as the binary package. +

- The extended description + + Maintainer

- Do not try to continue the single line synopsis into the - extended description. This will not work correctly when - the full description is displayed, and makes no sense - where only the summary (the single line synopsis) is - available. + The package maintainer's name and email address. The name + should come first, then the email address inside angle + brackets <> (in RFC822 format).

- The extended description should describe what the package - does and how it relates to the rest of the system (in terms - of, for example, which subsystem it is which part of). + If the maintainer's name contains a full stop then the + whole field will not work directly as an email address due + to a misfeature in the syntax specified in RFC822; a + program using this field as an address must check for this + and correct the problem if necessary (for example by + putting the name in round brackets and moving it to the + end, and bringing the email address forward).

+ + + + Changed-By

- The description field needs to make sense to anyone, even - people who have no idea about any of the things the - package deals with. - The blurb that comes with a program in its - announcements and/or README files is - rarely suitable for use in a description. It is - usually aimed at people who are already in the - community where the package is used. - + The name and email address of the person who changed the + said package. Usually the name of the maintainer. + All the rules for the Maintainer field apply here, too.

+ + + + Section

- The lines in the extended description can have these formats: + This field specifies an application area into which the package + has been classified. See .

-

+

+ When it appears in the debian/control file, + it gives the value for the subfield of the same name in + the Files field of the .changes file. + It also gives the default for the same field in the binary + packages. +

- - Those starting with a single space are part of a paragraph. - Successive lines of this form will be word-wrapped when - displayed. The leading space will usually be stripped off. - +

+ By default, dpkg-gencontrol does not include this + field in the control file of a binary package - use the + -is (or -isp) options to achieve this effect. +

+ + + + Priority + +

+ This field represents how important that it is that the user + have the package installed. See . +

+ +

+ When it appears in the debian/control file, + it gives the value for the subfield of the same name in + the Files field of the .changes file. + It also gives the default for the same field in the binary + packages. +

+ +

+ By default, dpkg-gencontrol does not include this + field in the control file of a binary package - use the + -ip (or -isp) options to achieve this effect. +

+ + + + Package + +

+ The name of the binary package. +

+ +

+ Package names must consist only of lower case letters + (a-z), digits (0-9), plus (+) + and minus (-) signs, and periods (.). + They must be at least two characters long and must start + with an alphanumeric character. +

+ + + + Architecture + +

+ Depending on context and the control file used, the + Architecture field can include the following sets of + values: + + A unique single word identifying a Debian machine + architecture, see . + all, which indicates an + architecture-independent package. + any, which indicates a package available + for building on any architecture. + source, which indicates a source package. + +

+ +

+ In the main debian/control file in the source + package, or in the source package control file + .dsc, one may specify a list of architectures + separated by spaces, or the special values any or + all. +

+ +

+ Specifying any indicates that the source package + isn't dependent on any particular architecture and should + compile fine on any one. The produced binary package(s) + will be specific to whatever the current build architecture + is. + This is the most often used setting, and is recommended + for new packages that aren't Architecture: all. + +

+ +

+ Specifying a list of architectures indicates that the source + will build an architecture-dependent package, and will only + work correctly on the listed architectures. + This is a setting used for a minority of cases where the + program is not portable. Generally, it should not be used + for new packages. + +

+ +

+ In a .changes file, the Architecture + field lists the architecture(s) of the package(s) + currently being uploaded. This will be a list; if the + source for the package is also being uploaded, the special + entry source is also present. +

+ +

+ See for information how to get the + architecture for the build process. +

+ + + + Essential + +

+ This is a boolean field which may occur only in the + control file of a binary package or in a per-package fields + paragraph of a main source control data file. +

+ +

+ If set to yes then the package management system + will refuse to remove the package (upgrading and replacing + it is still possible). The other possible value is no, + which is the same as not having the field at all. +

+ + + + Package interrelationship fields: + Depends, Pre-Depends, + Recommends, Suggests, Conflicts, + Provides, Replaces, Enhances + + +

+ These fields describe the package's relationships with + other packages. Their syntax and semantics are described + in .

+ + + + Standards-Version + +

+ The most recent version of the standards (the policy + manual and associated texts) with which the package + complies. +

+ +

+ The version number has four components: major and minor + version number and major and minor patch level. When the + standards change in a way that requires every package to + change the major number will be changed. Significant + changes that will require work in many packages will be + signaled by a change to the minor number. The major patch + level will be changed for any change to the meaning of the + standards, however small; the minor patch level will be + changed when only cosmetic, typographical or other edits + are made which neither change the meaning of the document + nor affect the contents of packages. +

+ +

+ Thus only the first three components of the policy version + are significant in the Standards-Version control + field, and so either these three components or the all + four components may be specified. + In the past, people specified the full version number + in the Standards-Version field, for example "2.3.0.0". + Since minor patch-level changes don't introduce new + policy, it was thought it would be better to relax + policy and only require the first 3 components to be + specified, in this example "2.3.0". All four + components may still be used if someone wishes to do so. + +

+ + + + + Version + +

+ The version number of a package. The format is: + [epoch:]upstream_version[-debian_revision] +

+ +

+ The three components here are: + + epoch + +

+ This is a single (generally small) unsigned integer. It + may be omitted, in which case zero is assumed. If it is + omitted then the upstream_version may not + contain any colons. +

+ +

+ It is provided to allow mistakes in the version numbers + of older versions of a package, and also a package's + previous version numbering schemes, to be left behind. +

+ + + upstream_version + +

+ This is the main part of the version number. It is + usually the version number of the original ("upstream") + package from which the .deb file has been made, + if this is applicable. Usually this will be in the same + format as that specified by the upstream author(s); + however, it may need to be reformatted to fit into the + package management system's format and comparison + scheme. +

+ +

+ The comparison behavior of the package management system + with respect to the upstream_version is + described below. The upstream_version + portion of the version number is mandatory. +

+ +

+ The upstream_version may contain only + alphanumerics + Alphanumerics are A-Za-z0-9 only. + + and the characters . + - + : (full stop, plus, hyphen, colon) and should + start with a digit. If there is no + debian_revision then hyphens are not allowed; + if there is no epoch then colons are not + allowed. +

+ + + debian_revision + +

+ This part of the version number specifies the version of + the Debian package based on the upstream version. It + may contain only alphanumerics and the characters + + and . (plus and full stop) and is + compared in the same way as the + upstream_version is. +

+ +

+ It is optional; if it isn't present then the + upstream_version may not contain a hyphen. + This format represents the case where a piece of + software was written specifically to be turned into a + Debian package, and so there is only one "debianization" + of it and therefore no revision indication is required. +

+ +

+ It is conventional to restart the + debian_revision at 1 each time the + upstream_version is increased. +

+ +

+ The package management system will break the version + number apart at the last hyphen in the string (if there + is one) to determine the upstream_version and + debian_revision. The absence of a + debian_revision compares earlier than the + presence of one (but note that the + debian_revision is the least significant part + of the version number). +

+ + +

+ +

+ The upstream_version and debian_revision + parts are compared by the package management system using the + same algorithm: +

+ +

+ The strings are compared from left to right. +

+ +

+ First the initial part of each string consisting entirely of + non-digit characters is determined. These two parts (one of + which may be empty) are compared lexically. If a difference + is found it is returned. The lexical comparison is a + comparison of ASCII values modified so that all the letters + sort earlier than all the non-letters. +

+ +

+ Then the initial part of the remainder of each string which + consists entirely of digit characters is determined. The + numerical values of these two parts are compared, and any + difference found is returned as the result of the comparison. + For these purposes an empty string (which can only occur at + the end of one or both version strings being compared) counts + as zero. +

+ +

+ These two steps (comparing and removing initial non-digit + strings and initial digit strings) are repeated until a + difference is found or both strings are exhausted. +

+ +

+ Note that the purpose of epochs is to allow us to leave behind + mistakes in version numbering, and to cope with situations + where the version numbering scheme changes. It is + not intended to cope with version numbers containing + strings of letters which the package management system cannot + interpret (such as ALPHA or pre-), or with + silly orderings (the author of this manual has heard of a + package whose versions went 1.1, 1.2, + 1.3, 1, 2.1, 2.2, + 2 and so forth). +

+ + + + Description + +

+ In a source or binary control file, the Description + field contains a description of the binary package, consisting + of two parts, the synopsis or the short description, and the + long description. The field's format is as follows: +

+ +

+ + Description: <single line synopsis> + <extended description over several lines> + +

+ +

+ The lines in the extended description can have these formats: +

+ +

+ + + Those starting with a single space are part of a paragraph. + Successive lines of this form will be word-wrapped when + displayed. The leading space will usually be stripped off. + Those starting with two or more spaces. These will be @@ -2506,7 +2786,7 @@ Package: libc6 Those containing a single space followed by a single full stop character. These are rendered as blank lines. This is the only way to get a blank line - Completely empty lines will not be rendered as blank lines. + Completely empty lines will not be rendered as blank lines. Instead, they will cause the parser to think you're starting a whole new record in the control file, and will therefore likely abort with an error. @@ -2524,60 +2804,402 @@ Package: libc6 Do not use tab characters. Their effect is not predictable.

- - - +

+ See for further information on this. +

- +

+ In a .changes file, the Description field + contains a summary of the descriptions for the packages being + uploaded. +

+

+ The part of the field before the first newline is empty; + thereafter each line has the name of a binary package and + the summary description line from that binary package. + Each line is indented by one space. +

- Package maintainer scripts - and installation procedure - + - Introduction to package maintainer scripts - + + Distribution -

- It is possible to supply scripts as part of a package which - the package management system will run for you when your - package is installed, upgraded or removed. -

+

+ In a .changes file or parsed changelog output + this contains the (space-separated) name(s) of the + distribution(s) where this version of the package should + be installed. Valid distributions are determined by the + archive maintainers. + Current distribution names are: + + stable + + This is the current "released" version of Debian + GNU/Linux. Once the distribution is + stable only security fixes and other + major bug fixes are allowed. When changes are + made to this distribution, the release number is + increased (for example: 2.2r1 becomes 2.2r2 then + 2.2r3, etc). + -

- These scripts are the files preinst, - postinst, prerm and postrm in the - control area of the package. They must be proper executable - files; if they are scripts (which is recommended), they must - start with the usual #! convention. They should be - readable and executable by anyone, and not world-writable. -

+ unstable + + This distribution value refers to the + developmental part of the Debian + distribution tree. New packages, new upstream + versions of packages and bug fixes go into the + unstable directory tree. Download from + this distribution at your own risk. + -

- The package management system looks at the exit status from - these scripts. It is important that they exit with a - non-zero status if there is an error, so that the package - management system can stop its processing. For shell - scripts this means that you almost always need to - use set -e (this is usually true when writing shell - scripts, in fact). It is also important, of course, that - they don't exit with a non-zero status if everything went - well. -

+ testing + + This distribution value refers to the + testing part of the Debian distribution + tree. It receives its packages from the + unstable distribution after a short time lag to + ensure that there are no major issues with the + unstable packages. It is less prone to breakage + than unstable, but still risky. It is not + possible to upload packages directly to + testing. + -

- When a package is upgraded a combination of the scripts from - the old and new packages is called during the upgrade - procedure. If your scripts are going to be at all - complicated you need to be aware of this, and may need to - check the arguments to your scripts. -

+ frozen + + From time to time, the testing + distribution enters a state of "code-freeze" in + anticipation of release as a stable + version. During this period of testing only + fixes for existing or newly-discovered bugs will + be allowed. The exact details of this stage are + determined by the Release Manager. + -

- Broadly speaking the preinst is called before - (a particular version of) a package is installed, and the - postinst afterwards; the prerm - before (a version of) a package is removed and the + experimental + + The packages with this distribution value are + deemed by their maintainers to be high + risk. Oftentimes they represent early beta or + developmental packages from various sources that + the maintainers want people to try, but are not + ready to be a part of the other parts of the + Debian distribution tree. Download at your own + risk. + + + +

+ You should list all distributions that the + package should be installed into. +

+ +

+ More information is available in the Debian Developer's + Reference, section "The Debian archive". +

+ +

+ + + + Date + +

+ This field includes the date the package was built or last edited. +

+ +

+ The value of this field is usually extracted from the + debian/changelog file - see + ). +

+ + + + Format + +

+ This field specifies a format revision for the file. + The most current format described in the Policy Manual + is version 1.5. The syntax of the + format value is the same as that of a package version + number except that no epoch or Debian revision is allowed + - see . +

+ + + + Urgency + +

+ This is a description of how important it is to upgrade to + this version from previous ones. It consists of a single + keyword usually taking one of the values low, + medium or high (not case-sensitive) + followed by an optional commentary (separated by a space) + which is usually in parentheses. For example: + + + Urgency: low (HIGH for users of diversions) + + +

+ +

+ The value of this field is usually extracted from the + debian/changelog file - see + . +

+ + + + Changes + +

+ This field contains the human-readable changes data, describing + the differences between the last version and the current one. +

+ +

+ There should be nothing in this field before the first + newline; all the subsequent lines must be indented by at + least one space; blank lines must be represented by a line + consiting only of a space and a full stop. +

+ +

+ The value of this field is usually extracted from the + debian/changelog file - see + ). +

+ +

+ Each version's change information should be preceded by a + "title" line giving at least the version, distribution(s) + and urgency, in a human-readable way. +

+ +

+ If data from several versions is being returned the entry + for the most recent version should be returned first, and + entries should be separated by the representation of a + blank line (the "title" line may also be followed by the + representation of blank line). +

+ + + + Binary + +

+ This field is a list of binary packages. +

+ +

+ When it appears in the .dsc file it is the list + of binary packages which a source package can produce. It + does not necessarily produce all of these binary packages + for every architecture. The source control file doesn't + contain details of which architectures are appropriate for + which of the binary packages. +

+ +

+ When it appears in a .changes file it lists the + names of the binary packages actually being uploaded. +

+ +

+ The syntax is a list of binary packages separated by + commas + A space after each comma is conventional. + . Currently the packages must be separated using + only spaces in the .changes file. +

+ + + + Installed-Size + +

+ This field appears in the control files of binary + packages, and in the Packages files. It gives + the total amount of disk space required to install the + named package. +

+ +

+ The disk space is represented in kilobytes as a simple + decimal number. +

+ + + + Files + +

+ This field contains a list of files with information about + each one. The exact information and syntax varies with + the context. In all cases the part of the field + contents on the same line as the field name is empty. The + remainder of the field is one line per file, each line + being indented by one space and containing a number of + sub-fields separated by spaces. +

+ +

+ In the .dsc file, each line contains the MD5 + checksum, size and filename of the tar file and (if applicable) + diff file which make up the remainder of the source + package + That is, the parts which are not the .dsc. + . + The exact forms of the filenames are described + in . +

+ +

+ In the .changes file this contains one line per + file being uploaded. Each line contains the MD5 checksum, + size, section and priority and the filename. + The section + and priority + are the values of the corresponding fields in + the main source control file. If no section or priority is + specified then - should be used, though section + and priority values must be specified for new packages to + be installed properly. +

+ +

+ The special value byhand for the section in a + .changes file indicates that the file in question + is not an ordinary package file and must by installed by + hand by the distribution maintainers. If the section is + byhand the priority should be -. +

+ +

+ If a new Debian revision of a package is being shipped and + no new original source archive is being distributed the + .dsc must still contain the Files field + entry for the original source archive + package-upstream-version.orig.tar.gz, + but the .changes file should leave it out. In + this case the original source archive on the distribution + site must match exactly, byte-for-byte, the original + source archive which was used to generate the + .dsc file and diff which are being uploaded.

+ + + + Closes + +

+ A space-separated list of bug report numbers that the upload + governed by the .changes file closes. +

+ + + + + + User-defined fields + +

+ Additional user-defined fields may be added to the + source package control file. Such fields will be + ignored, and not copied to (for example) binary or + source package control files or upload control files. +

+ +

+ If you wish to add additional unsupported fields to + these output files you should use the mechanism + described here. +

+ +

+ Fields in the main source control information file with + names starting X, followed by one or more of + the letters BCS and a hyphen -, will + be copied to the output files. Only the part of the + field name after the hyphen will be used in the output + file. Where the letter B is used the field + will appear in binary package control files, where the + letter S is used in source package control + files and where C is used in upload control + (.changes) files. +

+ +

+ For example, if the main source information control file + contains the field + + XBS-Comment: I stand between the candle and the star. + + then the binary and source package control files will contain the + field + + Comment: I stand between the candle and the star. + +

+ + + + + + + + Package maintainer scripts and installation procedure + + + Introduction to package maintainer scripts + +

+ It is possible to supply scripts as part of a package which + the package management system will run for you when your + package is installed, upgraded or removed. +

+ +

+ These scripts are the files preinst, + postinst, prerm and postrm in the + control area of the package. They must be proper executable + files; if they are scripts (which is recommended), they must + start with the usual #! convention. They should be + readable and executable by anyone, and not world-writable. +

+ +

+ The package management system looks at the exit status from + these scripts. It is important that they exit with a + non-zero status if there is an error, so that the package + management system can stop its processing. For shell + scripts this means that you almost always need to + use set -e (this is usually true when writing shell + scripts, in fact). It is also important, of course, that + they don't exit with a non-zero status if everything went + well. +

+ +

+ When a package is upgraded a combination of the scripts from + the old and new packages is called during the upgrade + procedure. If your scripts are going to be at all + complicated you need to be aware of this, and may need to + check the arguments to your scripts. +

+ +

+ Broadly speaking the preinst is called before + (a particular version of) a package is installed, and the + postinst afterwards; the prerm + before (a version of) a package is removed and the postrm afterwards.

@@ -2597,7 +3219,7 @@ Package: libc6 considerations really apply to all shell scripts.

 - + Maintainer scripts Idempotency

@@ -2610,18 +3232,16 @@ Package: libc6 should merely do the things that were left undone the first time, if any, and exit with a success status if everything is OK. -

This is so that if an error occurs, the user interrupts dpkg or some other unforeseen circumstance happens you don't leave the user with a badly-broken package when dpkg attempts to repeat the action. -

- + Controlling terminal for maintainer scripts

@@ -2653,118 +3273,109 @@ Package: libc6

-

new-preinst install

+ new-preinst install -

new-preinst install - old-version

+ new-preinst install old-version -

new-preinst upgrade - old-version

+ new-preinst upgrade old-version -

old-preinst abort-upgrade + old-preinst abort-upgrade new-version -

-

postinst configure - most-recently-configured-version

+ postinst configure + most-recently-configured-version -

old-postinst abort-upgrade - new-version

+ old-postinst abort-upgrade + new-version -

conflictor's-postinst abort-remove + conflictor's-postinst abort-remove in-favour package - new-version

+ new-version -

deconfigured's-postinst abort-deconfigure in-favour failed-install-package version removing conflicting-package version -

-

prerm remove

+ prerm remove -

old-prerm upgrade - new-version

+ old-prerm upgrade + new-version -

new-prerm failed-upgrade - old-version

+ new-prerm failed-upgrade + old-version -

conflictor's-prerm remove + conflictor's-prerm remove in-favour package - new-version

+ new-version -

deconfigured's-prerm deconfigure in-favour package-being-installed version removing conflicting-package version -

-

postrm remove

+ postrm remove -

postrm purge

+ postrm purge -

old-postrm upgrade - new-version

+ new-version -

new-postrm failed-upgrade - old-version

+ new-postrm failed-upgrade + old-version -

new-postrm abort-install

+ new-postrm abort-install -

new-postrm abort-install - old-version

+ new-postrm abort-install + old-version -

new-postrm abort-upgrade - old-version

+ new-postrm abort-upgrade + old-version -

disappearer's-postrm disappear overwriter - overwriter-version

 + overwriter-version +

- Details of unpack phase of - installation or upgrade - + + Details of unpack phase of installation or upgrade

The procedure on installation/upgrade/overwrite/disappear @@ -2778,17 +3389,14 @@ Package: libc6 -

-

If a version of the package is already - installed, call + If a version of the package is already installed, call old-prerm upgrade new-version -

+ -

If the script runs but exits with a non-zero exit status, dpkg will attempt: @@ -2798,16 +3406,14 @@ Package: libc6 old-postinst abort-upgrade new-version -

-

+ -

If a "conflicting" package is being removed at the same time: + If a "conflicting" package is being removed at the same time: -

If any packages depended on that conflicting package and --auto-deconfigure is specified, call, for each such package: @@ -2825,10 +3431,10 @@ Package: libc6 The deconfigured packages are marked as requiring configuration, so that if --install is used they will be - configured again if possible.

+ configured again if possible. -

To prepare for removal of the conflicting package, call: + To prepare for removal of the conflicting package, call: conflictor's-prerm remove \ in-favour package new-version @@ -2838,31 +3444,28 @@ Package: libc6 conflictor's-postinst abort-remove \ in-favour package new-version -

-

+ -

-

If the package is being upgraded, call: + If the package is being upgraded, call: new-preinst upgrade old-version -

+ -

Otherwise, if the package had some configuration files from a previous version installed (i.e., it is in the "configuration files only" state): new-preinst install old-version -

- + + -

Otherwise (i.e., the package was completely purged): + Otherwise (i.e., the package was completely purged): new-preinst install @@ -2872,11 +3475,10 @@ Package: libc6 new-postrm abort-install old-version new-postrm abort-install -

-

+

The new package's files are unpacked, overwriting any @@ -2889,7 +3491,7 @@ Package: libc6

- It is an error for a package to contains files which + It is an error for a package to contain files which are on the system in another package, unless Replaces is used (see ). - - debian/substvars - and variable substitutions - - -

- When dpkg-gencontrol, - dpkg-genchanges and dpkg-source - generate control files they do variable substitutions on - their output just before writing it. Variable - substitutions have the form - ${variable-name}. The optional file - debian/substvars contains variable substitutions - to be used; variables can also be set directly from - debian/rules using the -V option to the - source packaging commands, and certain predefined - variables are available. -

- -

- This file is usually generated and modified dynamically by - debian/rules targets, in which case it must be - removed by the clean target. -

- -

- See for full - details about source variable substitutions, including the - format of debian/substvars.

- - - debian/files - - -

- This file is not a permanent part of the source tree; it - is used while building packages to record which files are - being generated. dpkg-genchanges uses it - when it generates a .changes file. -

- -

- It should not exist in a shipped source package, and so it - (and any backup files or temporary files such as - files.new - -

- files.new is used as a temporary file by - dpkg-gencontrol and - dpkg-distaddfile - they write a new - version of files here before renaming it, - to avoid leaving a corrupted copy if an error - occurs -

- ) should be removed by the - clean target. It may also be wise to - ensure a fresh start by emptying or removing it at the - start of the binary target. -

- -

- dpkg-gencontrol adds an entry to this file - for the .deb file that will be created by - dpkg-deb from the control file that it - generates, so for most packages all that needs to be done - with this file is to delete it in clean. -

- -

- If a package upload includes files besides the source - package and any binary packages whose control files were - made with dpkg-gencontrol then they should be - placed in the parent of the package's top-level directory - and dpkg-distaddfile should be called to add - the file to the list in debian/files.

- - - debian/tmp - - -

- This is the canonical temporary location for the - construction of binary packages by the binary - target. The directory tmp serves as the root of - the filesystem tree as it is being constructed (for - example, by using the package's upstream makefiles install - targets and redirecting the output there), and it also - contains the DEBIAN subdirectory. See . -

- -

- If several binary packages are generated from the same - source tree it is usual to use several - debian/tmpsomething directories, for - example tmp-a or tmp-doc. -

- -

- Whatever tmp directories are created and used by - binary must of course be removed by the - clean target.

 - - - - Source packages as archives - + It is possible to put other files in the package control + area, but this is not generally a good idea (though they + will largely be ignored). +

- As it exists on the FTP site, a Debian source package - consists of three related files. You must have the right - versions of all three to be able to use them. + Here is a brief list of the control info files supported by + dpkg and a summary of what they're used for.

- Debian source control file - .dsc + control -

- This file contains a series of fields, identified and - separated just like the fields in the control file of - a binary package. The fields are listed below; their - syntax is described above, in . - - -

Source

- - -

Version

- - -

Maintainer

- - -

Binary

- - -

Architecture

- - -

- Build-Depends et - al. (source package interrelationships) -

- - -

- Standards-Version

- - -

Files

- - + This is the key description file used by + dpkg. It specifies the package's name + and version, gives its description for the user, + states its relationships with other packages, and so + forth. See and + . +

- The source package control file is generated by - dpkg-source when it builds the source - archive, from other files in the source package, - described above. When unpacking it is checked against - the files and directories in the other parts of the - source package, as described below.

+ It is usually generated automatically from information + in the source package by the + dpkg-gencontrol program, and with + assistance from dpkg-shlibdeps. + See . +

- - Original source archive - - - package_upstream-version.orig.tar.gz - + postinst, preinst, postrm, + prerm - -

- This is a compressed (with gzip -9) - tar file containing the source code from - the upstream authors of the program. The tarfile - unpacks into a directory - package-upstream-version.orig, - and does not contain files anywhere other than in - there or in its subdirectories.

- - - - Debianisation diff - - - package_upstream_version-revision.diff.gz - - - + These are exectuable files (usually scripts) which + dpkg runs during installation, upgrade + and removal of packages. They allow the package to + deal with matters which are particular to that package + or require more complicated processing than that + provided by dpkg. Details of when and + how they are called are in . +

- This is a unified context diff (diff -u) - giving the changes which are required to turn the - original source into the Debian source. These changes - may only include editing and creating plain files. - The permissions of files, the targets of symbolic - links and the characteristics of special files or - pipes may not be changed and no files may be removed - or renamed. + It is very important to make these scripts idempotent. + See .

- All the directories in the diff must exist, except the - debian subdirectory of the top of the source - tree, which will be created by - dpkg-source if necessary when unpacking. + The maintainer scripts are guaranteed to run with a + controlling terminal and can interact with the user. + See .

+ -

- The dpkg-source program will - automatically make the debian/rules file - executable (see below).

+ conffiles + + + This file contains a list of configuration files which + are to be handled automatically by dpkg + (see ). Note that not necessarily + every configuration file should be listed here. + + + shlibs + + + This file contains a list of the shared libraries + supplied by the package, with dependency details for + each. This is used by dpkg-shlibdeps + when it determines what dependencies are required in a + package control file. The shlibs file format + is described on . + +

+ + The main control information file: control

- If there is no original source code - for example, if the - package is specially prepared for Debian or the Debian - maintainer is the same as the upstream maintainer - the - format is slightly different: then there is no diff, and the - tarfile is named - package_version.tar.gz and - contains a directory - package-version. + The most important control information file used by + dpkg when it installs a package is + control. It contains all the package's "vital + statistics".

- - - Unpacking a Debian source package without - dpkg-source -

- dpkg-source -x is the recommended way to unpack a - Debian source package. However, if it is not available it - is possible to unpack a Debian source archive as follows: - - -

- Untar the tarfile, which will create a .orig - directory.

- - -

Rename the .orig directory to - package-version.

- - -

- Create the subdirectory debian at the top of - the source tree.

- -

Apply the diff using patch -p0.

- -

Untar the tarfile again if you want a copy of the original - source code alongside the Debianised version.

- - + The binary package control files of packages built from + Debian sources are made by a special tool, + dpkg-gencontrol, which reads + debian/control and debian/changelog to + find the information it needs. See for + more details. +

- It is not possible to generate a valid Debian source archive - without using dpkg-source. In particular, - attempting to use diff directly to generate the - .diff.gz file will not work. + The fields in binary package control files are listed in + .

- Restrictions on objects in source packages - - -

- The source package may not contain any hard links - -

- This is not currently detected when building source - packages, but only when extracting - them. -

- - -

- Hard links may be permitted at some point in the - future, but would require a fair amount of - work. -

- , device special files, sockets or setuid or - setgid files. - -

- Setgid directories are allowed. -

- -

+

+ A description of the syntax of control files and the purpose + of the fields is available in . +

+ -

- The source packaging tools manage the changes between the - original and Debianised source using diff and - patch. Turning the original source tree as - included in the .orig.tar.gz into the debianised - source must not involve any changes which cannot be - handled by these tools. Problematic changes which cause - dpkg-source to halt with an error when - building the source package are: - -

Adding or removing symbolic links, sockets or pipes.

- -

Changing the targets of symbolic links.

- -

Creating directories, other than debian.

- -

Changes to the contents of binary files.

 - Changes which cause dpkg-source to - print a warning but continue anyway are: - - -

- Removing files, directories or symlinks. - -

- Renaming a file is not treated specially - it is - seen as the removal of the old file (which - generates a warning, but is otherwise ignored), - and the creation of the new - one.

- -

- - -

- Changed text files which are missing the usual final - newline (either in the original or the modified - source tree). -

- - - Changes which are not represented, but which are not detected by - dpkg-source, are: - -

Changing the permissions of files (other than - debian/rules) and directories.

 - -

+ + Time Stamps -

- The debian directory and debian/rules - are handled specially by dpkg-source - before - applying the changes it will create the debian - directory, and afterwards it will make - debian/rules world-exectuable. -

- +

+ See . +

- Control files and their - fields (from old Packaging Manual) - + + Source packages (from old Packaging Manual)

- Many of the tools in the dpkg suite manipulate - data in a common format, known as control files. Binary and - source packages have control data as do the .changes - files which control the installation of uploaded files, and - dpkg's internal databases are in a similar - format. + The Debian binary packages in the distribution are generated + from Debian sources, which are in a special format to assist + the easy and automatic building of binaries.

- Syntax of control files - - -

- A file consists of one or more paragraphs of fields. The - paragraphs are separated by blank lines. Some control files - only allow one paragraph; others allow several, in which - case each paragraph often refers to a different package. -

- -

- Each paragraph is a series of fields and values; each field - consists of a name, followed by a colon and the value. It - ends at the end of the line. Horizontal whitespace (spaces - and tabs) may occur before or after the value and is ignored - there; it is conventional to put a single space after the - colon. -

+ + Tools for processing source packages

- Some fields' values may span several lines; in this case - each continuation line must start with a space or - tab. Any trailing spaces or tabs at the end of individual - lines of a field value are ignored. + Various tools are provided for manipulating source packages; + they pack and unpack sources and help build of binary + packages and help manage the distribution of new versions.

- Except where otherwise stated only a single line of data is - allowed and whitespace is not significant in a field body. - Whitespace may never appear inside names (of packages, - architectures, files or anything else), version numbers or - in between the characters of multi-character version - relationships. + They are introduced and typical uses described here; see + for full + documentation about their arguments and operation.

- Field names are not case-sensitive, but it is usual to - capitalise the field names using mixed case as shown below. + For examples of how to construct a Debian source package, + and how to use those utilities that are used by Debian + source packages, please see the hello example + package.

-

- Blank lines, or lines consisting only of spaces and tabs, - are not allowed within field values or between fields - that - would mean a new paragraph. -

+ + + dpkg-source - packs and unpacks Debian source + packages + -

- It is important to note that there are several fields which - are optional as far as dpkg and the related - tools are concerned, but which must appear in every Debian - package, or whose omission may cause problems. -

- +

+ This program is frequently used by hand, and is also + called from package-independent automated building scripts + such as dpkg-buildpackage. +

- List of fields - +

+ To unpack a package it is typically invoked with + + dpkg-source -x .../path/to/filename.dsc + +

- Package - +

+ with the filename.tar.gz and + filename.diff.gz (if applicable) in + the same directory. It unpacks into + package-version, and if + applicable + package-version.orig, in + the current directory. +

- The name of the binary package. Package names consist of - the alphanumerics and + - . - (plus, minus and full stop). - -

- The characters @ : = - % _ (at, colon, equals, percent - and underscore) used to be legal and are still - accepted when found in a package file, but may not be - used in new packages -

- + To create a packed source archive it is typically invoked: + + dpkg-source -b package-version + +

+ +

+ This will create the .dsc, .tar.gz and + .diff.gz (if appropriate) in the current + directory. dpkg-source does not clean the + source tree first - this must be done separately if it is + required.

- They must be at least two characters and must start with - an alphanumeric. In current versions of dpkg they are - sort of case-sensitive

This is a - bug.

; use lowercase package names unless - the package you're building (or referring to, in other - fields) is already using uppercase.

+ See also .

 - Version + + + + dpkg-buildpackage - overall package-building + control script

- This lists the source or binary package's version number - - see . + dpkg-buildpackage is a script which invokes + dpkg-source, the debian/rules + targets clean, build and + binary, dpkg-genchanges and + gpg (or pgp) to build a signed + source and binary package upload.

+

+ It is usually invoked by hand from the top level of the + built or unbuilt source directory. It may be invoked with + no arguments; useful arguments include: + + -uc, -us + +

+ Do not sign the .changes file or the + source package .dsc file, respectively.

+ + -psign-command + +

+ Invoke sign-command instead of finding + gpg or pgp on the PATH. + sign-command must behave just like + gpg or pgp.

+ + -rroot-command + +

+ When root privilege is required, invoke the command + root-command. root-command + should invoke its first argument as a command, from + the PATH if necessary, and pass its + second and subsequent arguments to the command it + calls. If no root-command is supplied + then dpkg-buildpackage will take no + special action to gain root privilege, so that for + most packages it will have to be invoked as root to + start with.

+ + -b, -B + +

+ Two types of binary-only build and upload - see + . +

+ + +

- Architecture + + + dpkg-gencontrol - generates binary package + control files

- This is the architecture string; it is a single word for - the Debian architecture. + This program is usually called from debian/rules + (see ) in the top level of the source + tree.

- dpkg will check the declared architecture of - a binary package against its own compiled-in value before - it installs it. + This is usually done just before the files and directories in the + temporary directory tree where the package is being built have their + permissions and ownerships set and the package is constructed using + dpkg-deb/ + + This is so that the control file which is produced has + the right permissions + .

- The special value all indicates that the package - is architecture-independent. + dpkg-gencontrol must be called after all the + files which are to go into the package have been placed in + the temporary build directory, so that its calculation of + the installed size of a package is correct.

- In the main debian/control file in the source - package, or in the source package control file - .dsc, a list of architectures (separated by - spaces) is also allowed, as is the special value - any. A list indicates that the source will build - an architecture-dependent package, and will only work - correctly on the listed architectures. any - indicates that though the source package isn't dependent - on any particular architecture and should compile fine on - any one, the binary package(s) produced are not - architecture-independent but will instead be specific to - whatever the current build architecture is. + It is also necessary for dpkg-gencontrol to + be run after dpkg-shlibdeps so that the + variable substitutions created by + dpkg-shlibdeps in debian/substvars + are available.

- In a .changes file the Architecture - field lists the architecture(s) of the package(s) - currently being uploaded. This will be a list; if the - source for the package is being uploaded too the special - entry source is also present. + For a package which generates only one binary package, and + which builds it in debian/tmp relative to the top + of the source package, it is usually sufficient to call + dpkg-gencontrol.

- See for information how to get the - architecture for the build process. + Sources which build several binaries will typically need + something like: + + dpkg-gencontrol -Pdebian/tmp-pkg -ppackage + The -P tells + dpkg-gencontrol that the package is being + built in a non-default directory, and the -p + tells it which package's control file should be generated.

+ +

+ dpkg-gencontrol also adds information to the + list of files in debian/files, for the benefit of + (for example) a future invocation of + dpkg-genchanges.

 - Maintainer + + + dpkg-shlibdeps - calculates shared library + dependencies

- The package maintainer's name and email address. The name - should come first, then the email address inside angle - brackets <> (in RFC822 format). + This program is usually called from debian/rules + just before dpkg-gencontrol (see ), in the top level of the source tree.

- If the maintainer's name contains a full stop then the - whole field will not work directly as an email address due - to a misfeature in the syntax specified in RFC822; a - program using this field as an address must check for this - and correct the problem if necessary (for example by - putting the name in round brackets and moving it to the - end, and bringing the email address forward). + Its arguments are executables. + +

+ In a forthcoming dpkg version, + dpkg-shlibdeps would be required to be + called on shared libraries as well. +

+

+ They may be specified either in the locations in the + source tree where they are created or in the locations + in the temporary build tree where they are installed + prior to binary package creation. +

+ for which shared library dependencies should + be included in the binary package's control file.

- In a .changes file or parsed changelog data this - contains the name and email address of the person - responsible for the particular version in question - this - may not be the package's usual maintainer. + If some of the found shared libraries should only + warrant a Recommends or Suggests, or if + some warrant a Pre-Depends, this can be achieved + by using the -ddependency-field option + before those executable(s). (Each -d option + takes effect until the next -d.) +

+ +

+ dpkg-shlibdeps does not directly cause the + output control file to be modified. Instead by default it + adds to the debian/substvars file variable + settings like shlibs:Depends. These variable + settings must be referenced in dependency fields in the + appropriate per-binary-package sections of the source + control file.

- This field is usually optional in as far as the - dpkg are concerned, but its absence when - building packages usually generates a warning.

+ For example, a package that generates an essential part + which requires dependencies, and optional parts that + which only require a recommendation, would separate those + two sets of dependencies into two different fields. + At the time of writing, an example for this was the + + It can say in its debian/rules: + + dpkg-shlibdeps -dDepends program anotherprogram ... \ + -dRecommends optionalpart anotheroptionalpart + + and then in its main control file debian/control: + + ... + Depends: ${shlibs:Pre-Depends} + Recommends: ${shlibs:Recommends} + ... + +

+ +

+ Sources which produce several binary packages with + different shared library dependency requirements can use + the -pvarnameprefix option to override + the default shlibs: prefix (one invocation of + dpkg-shlibdeps per setting of this option). + They can thus produce several sets of dependency + variables, each of the form + varnameprefix:dependencyfield, + which can be referred to in the appropriate parts of the + binary package control files. +

- Source + + + + dpkg-distaddfile - adds a file to + debian/files

- This field identifies the source package name. + Some packages' uploads need to include files other than + the source and binary package files. +

+ +

+ dpkg-distaddfile adds a file to the + debian/files file so that it will be included in + the .changes file when + dpkg-genchanges is run.

- In a main source control information or a - .changes or .dsc file or parsed - changelog data this may contain only the name of the - source package. + It is usually invoked from the binary target of + debian/rules: + + dpkg-distaddfile filename section priority + + The filename is relative to the directory where + dpkg-genchanges will expect to find it - this + is usually the directory above the top level of the source + tree. The debian/rules target should put the + file there just before or just after calling + dpkg-distaddfile.

- In the control file of a binary package (or in a - Packages file) it may be followed by a version - number in parentheses. - -

- It is usual to leave a space after the package name if - a version number is specified. -

- This version number may be omitted (and is, by - dpkg-gencontrol) if it has the same value as - the Version field of the binary package in - question. The field itself may be omitted from a binary - package control file when the source package has the same - name and version as the binary package. + The section and priority are passed + unchanged into the resulting .changes file.

- Package interrelationship fields: - Depends, Pre-Depends, - Recommends Suggests, Conflicts, - Provides, Replaces - - -

- These fields describe the package's relationships with - other packages. Their syntax and semantics are described - in .

- - Description + + + dpkg-genchanges - generates a .changes + upload control file

- In a binary package Packages file or main source - control file this field contains a description of the - binary package, in a special format. See for details. + This program is usually called by package-independent + automatic building scripts such as + dpkg-buildpackage, but it may also be called + by hand.

- In a .changes file it contains a summary of the - descriptions for the packages being uploaded. The part of - the field before the first newline is empty; thereafter - each line has the name of a binary package and the summary - description line from that binary package. Each line is - indented by one space.

+ It is usually called in the top level of a built source + tree, and when invoked with no arguments will print out a + straightforward .changes file based on the + information in the source package's changelog and control + file and the binary and source packages which should have + been built. +

- Essential + + + + dpkg-parsechangelog - produces parsed + representation of a changelog

- This is a boolean field which may occur only in the - control file of a binary package (or in the - Packages file) or in a per-package fields - paragraph of a main source control data file. + This program is used internally by + dpkg-source et al. It may also occasionally + be useful in debian/rules and elsewhere. It + parses a changelog, debian/changelog by default, + and prints a control-file format representation of the + information in it to standard output.

- -

- If set to yes then dpkg and - dselect will refuse to remove the package - (though it can be upgraded and/or replaced). The other - possible value is no, which is the same as not - having the field at all.

 - Section and - Priority - - -

- These two fields classify the package. The - Priority represents how important that it is that - the user have it installed; the Section - represents an application area into which the package has - been classified. -

+ + + dpkg-architecture - information about the build and + host system + -

- When they appear in the debian/control file these - fields give values for the section and priority subfields - of the Files field of the .changes file, - and give defaults for the section and priority of the - binary packages. -

+

+ This program can be used manually, but is also invoked by + dpkg-buildpackage or debian/rules to set + to set environment or make variables which specify the build and + host architecture for the package building process. +

+ + -

- The section and priority are represented, though not as - separate fields, in the information for each file in the - -Filefield of a - .changes file. The section value in a - .changes file is used to decide where to install - a package in the FTP archive. -

+ + The Debianised source tree -

- These fields are not used by by dpkg proper, - but by dselect when it sorts packages and - selects defaults. -

+

+ The source archive scheme described later is intended to + allow a Debianised source tree with some associated control + information to be reproduced and transported easily. The + Debianised source tree is a version of the original program + with certain files added for the benefit of the + Debianisation process, and with any other changes required + made to the rest of the source code and installation + scripts. +

-

- These fields can appear in binary package control files, - in which case they provide a default value in case the - Packages files are missing the information. - dpkg and dselect will only use - the value from a .deb file if they have no other - information; a value listed in a Packages file - will always take precedence. By default - dpkg-gencontrol does not include the section - and priority in the control file of a binary package - use - the -isp, -is or -ip options to - achieve this effect.

- +

+ The extra files created for Debian are in the subdirectory + debian of the top level of the Debianised source + tree. They are described below. +

- Binary - + + debian/rules - the main building script

- This field is a list of binary packages. + See .

+ -

- When it appears in the .dsc file it is the list - of binary packages which a source package can produce. It - does not necessarily produce all of these binary packages - for every architecture. The source control file doesn't - contain details of which architectures are appropriate for - which of the binary packages. -

+ + + debian/changelog

- When it appears in a .changes file it lists the - names of the binary packages actually being uploaded. + See .

- The syntax is a list of binary packages separated by - commas. - + It is recommended that the entire changelog be encoded in the + + encoding of + .

- A space after each comma is conventional. + Support for Unicode, and specifically UTF-8, is + steadily increasing among popular applications in + Debian. For example, in unstable, GNOME 2 has + excellent support (almost level 2) in almost all its + applications; the big remaining one is gnome-terminal, + of which one requires development versions in order to + support UTF-8 (available in Debian experimental now if + you want to play). I think that by the time sarge is + released, UTF-8 support will start to hit critical + mass.

+

+ I think it is fairly obvious that we need to + eventually transition to UTF-8 for our package + infrastructure; it is really the only sane charset in + an international environment. Now, we can't switch to + using UTF-8 for package control fields and the like + until dpkg has better support, but one thing we can + start doing today is requesting that Debian changelogs + are UTF-8 encoded. At some point in time, we can start + requiring them to do so.

- Currently the packages must be separated using - only spaces in the .changes file.

- +

+ Checking for non-UTF8 characters in a changelog is + trivial. Dump the file through + iconv -f utf-8 -t ucs-4 + discard the output, and check the return + value. If there are any characters in the stream + which are invalid UTF-8 sequences, iconv will exit + with an error code; and this will be the case for the + vast majority of other character sets. +

+ +

- Installed-Size - + Defining alternative changelog formats + -

- This field appears in the control files of binary - packages, and in the Packages files. It gives - the total amount of disk space required to install the - named package. -

+

+ It is possible to use a different format to the standard + one, by providing a parser for the format you wish to + use. +

-

- The disk space is represented in kilobytes as a simple - decimal number.

+

+ In order to have dpkg-parsechangelog run your + parser, you must include a line within the last 40 lines + of your file matching the Perl regular expression: + \schangelog-format:\s+([0-9a-z]+)\W The part in + parentheses should be the name of the format. For + example, you might say: + + @@@ changelog-format: joebloggs @@@ + + Changelog format names are non-empty strings of alphanumerics. +

+ +

+ If such a line exists then dpkg-parsechangelog + will look for the parser as + /usr/lib/dpkg/parsechangelog/format-name + or + /usr/local/lib/dpkg/parsechangelog/format-name; + it is an error for it not to find it, or for it not to + be an executable program. The default changelog format + is dpkg, and a parser for it is provided with + the dpkg package. +

+ +

+ The parser will be invoked with the changelog open on + standard input at the start of the file. It should read + the file (it may seek if it wishes) to determine the + information required and return the parsed information + to standard output in the form of a series of control + fields in the standard format. By default it should + return information about only the most recent version in + the changelog; it should accept a + -vversion option to return changes + information from all versions present strictly + after version, and it should then be an + error for version not to be present in the + changelog. +

+ +

+ The fields are: + + Source + Version (mandatory) + Distribution (mandatory) + Urgency (mandatory) + Maintainer (mandatory) + Date + Changes (mandatory) + +

+ +

+ If several versions are being returned (due to the use + of -v), the urgency value should be of the + highest urgency code listed at the start of any of the + versions requested followed by the concatenated + (space-separated) comments from all the versions + requested; the maintainer, version, distribution and + date should always be from the most recent version. +

+ +

+ For the format of the Changes field see + . +

+ +

+ If the changelog format which is being parsed always or + almost always leaves a blank line between individual + change notes these blank lines should be stripped out, + so as to make the resulting output compact. +

+ +

+ If the changelog format does not contain date or package + name information this information should be omitted from + the output. The parser should not attempt to synthesise + it or find it from other sources. +

+ +

+ If the changelog does not have the expected format the + parser should exit with a nonzero exit status, rather + than trying to muddle through and possibly generating + incorrect output. +

+ +

+ A changelog parser may not interact with the user at + all. +

+ - Files - + + debian/substvars and variable substitutions

- This field contains a list of files with information about - each one. The exact information and syntax varies with - the context. In all cases the part of the field - contents on the same line as the field name is empty. The - remainder of the field is one line per file, each line - being indented by one space and containing a number of - sub-fields separated by spaces. + See .

-

- In the .dsc (Debian source control) file each - line contains the MD5 checksum, size and filename of the - tarfile and (if applicable) diff file which make up the - remainder of the source package. - -

- That is, the parts which are not the - .dsc. -

- The exact forms of the filenames are described - in . -

+ -

- In the .changes file this contains one line per - file being uploaded. Each line contains the MD5 checksum, - size, section and priority and the filename. The section - and priority are the values of the corresponding fields in - the main source control file - see . If no section or priority is - specified then - should be used, though section - and priority values must be specified for new packages to - be installed properly. -

+ + debian/files

- The special value byhand for the section in a - .changes file indicates that the file in question - is not an ordinary package file and must by installed by - hand by the distribution maintainers. If the section is - byhand the priority should be -. + See .

- -

- If a new Debian revision of a package is being shipped and - no new original source archive is being distributed the - .dsc must still contain the Files field - entry for the original source archive - package-upstream-version.orig.tar.gz, - but the .changes file should leave it out. In - this case the original source archive on the distribution - site must match exactly, byte-for-byte, the original - source archive which was used to generate the - .dsc file and diff which are being uploaded.

 - - Standards-Version + debian/tmp

- The most recent version of the standards (the Debian Policy - and associated texts) with which the package complies. This - is updated manually when editing the source package to - conform to newer standards; it can sometimes be used to - tell when a package needs attention. + This is the canonical temporary location for the + construction of binary packages by the binary + target. The directory tmp serves as the root of + the filesystem tree as it is being constructed (for + example, by using the package's upstream makefiles install + targets and redirecting the output there), and it also + contains the DEBIAN subdirectory. See . +

+ +

+ If several binary packages are generated from the same + source tree it is usual to use several + debian/tmpsomething directories, for + example tmp-a or tmp-doc.

- Its format is the same as that of a version number except - that no epoch or Debian revision is allowed - see .

- + Whatever tmp directories are created and used by + binary must of course be removed by the + clean target.

 + - Distribution - + Source packages as archives + -

- In a .changes file or parsed changelog output - this contains the (space-separated) name(s) of the - distribution(s) where this version of the package should - be or was installed. Distribution names follow the rules - for package names. (See ). -

+

+ As it exists on the FTP site, a Debian source package + consists of three related files. You must have the right + versions of all three to be able to use them. +

-

- Current distribution values are: +

- stable + Debian source control file - .dsc -

- This is the current "released" version of Debian - GNU/Linux. A new version is released approximately - every 3 months after the development code has - been frozen for a month of testing. Once the - distribution is stable only major bug fixes - are allowed. When changes are made to this - distribution, the release number is increased - (for example: 1.2r1 becomes 1.2r2 then 1.2r3, etc). -

+ This file is a control file used by dpkg-source + to extract a source package. + See . - unstable + + Original source archive - + + package_upstream-version.orig.tar.gz + + +

- This distribution value refers to the - developmental part of the Debian distribution - tree. New packages, new upstream versions of packages - and bug fixes go into the unstable directory - tree. Download from this distribution at your own - risk.

+ This is a compressed (with gzip -9) + tar file containing the source code from + the upstream authors of the program. +

- contrib + + Debianisation diff - + + package_upstream_version-revision.diff.gz + + +

- The packages with this distribution value do not meet - the criteria for inclusion in the main Debian - distribution as defined by the Policy Manual, but meet - the criteria for the contrib - Distribution. There is currently no distinction - between stable and unstable packages in the - contrib or non-free - distributions. Use your best judgement in downloading - from this Distribution.

- + This is a unified context diff (diff -u) + giving the changes which are required to turn the + original source into the Debian source. These changes + may only include editing and creating plain files. + The permissions of files, the targets of symbolic + links and the characteristics of special files or + pipes may not be changed and no files may be removed + or renamed. +

- non-free -

- Like the packages in the contrib seciton, - the packages in non-free do not meet the - criteria for inclusion in the main Debian distribution - as defined by the Policy Manual. Again, use your best - judgement in downloading from this Distribution.

+ All the directories in the diff must exist, except the + debian subdirectory of the top of the source + tree, which will be created by + dpkg-source if necessary when unpacking. +

- experimental -

- The packages with this distribution value are deemed - by their maintainers to be high risk. Oftentimes they - represent early beta or developmental packages from - various sources that the maintainers want people to - try, but are not ready to be a part of the other parts - of the Debian distribution tree. Download at your own - risk.

- + The dpkg-source program will + automatically make the debian/rules file + executable (see below).

 + +

- frozen +

+ If there is no original source code - for example, if the + package is specially prepared for Debian or the Debian + maintainer is the same as the upstream maintainer - the + format is slightly different: then there is no diff, and the + tarfile is named + package_version.tar.gz, + and preferably contains a directory named + package-version. +

+ + + + Unpacking a Debian source package without dpkg-source + +

+ dpkg-source -x is the recommended way to unpack a + Debian source package. However, if it is not available it + is possible to unpack a Debian source archive as follows: + + +

+ Untar the tarfile, which will create a .orig + directory.

+ + +

Rename the .orig directory to + package-version.

+ -

- From time to time, (currently, every 3 months) the - unstable distribution enters a state of - "code-freeze" in anticipation of release as a - stable version. During this period of testing - (usually 4 weeks) only fixes for existing or - newly-discovered bugs will be allowed. -

- - You should list all distributions that - the package should be installed into. Except in unusual - circumstances, installations to stable should also - go into frozen (if it exists) and - unstable. Likewise, installations into - frozen should also go into unstable.

- +

+ Create the subdirectory debian at the top of + the source tree.

+ +

Apply the diff using patch -p0.

+ +

Untar the tarfile again if you want a copy of the original + source code alongside the Debianised version.

+ + - Urgency - +

+ It is not possible to generate a valid Debian source archive + without using dpkg-source. In particular, + attempting to use diff directly to generate the + .diff.gz file will not work. +

+ + + Restrictions on objects in source packages

- This is a description of how important it is to upgrade to - this version from previous ones. It consists of a single - keyword usually taking one of the values LOW, - MEDIUM or HIGH) followed by an optional - commentary (separated by a space) which is usually in - parentheses. For example: - - Urgency: LOW (HIGH for diversions users) - + The source package may not contain any hard links + + This is not currently detected when building source + packages, but only when extracting + them. + + + Hard links may be permitted at some point in the + future, but would require a fair amount of + work. + , device special files, sockets or setuid or + setgid files. + + Setgid directories are allowed. +

- This field appears in the .changes file and in - parsed changelogs; its value appears as the value of the - urgency attribute in a dpkg-style - changelog (see ). + The source packaging tools manage the changes between the + original and Debianised source using diff and + patch. Turning the original source tree as + included in the .orig.tar.gz into the debianised + source must not involve any changes which cannot be + handled by these tools. Problematic changes which cause + dpkg-source to halt with an error when + building the source package are: + +

Adding or removing symbolic links, sockets or pipes.

+ +

Changing the targets of symbolic links.

+ +

Creating directories, other than debian.

+ +

Changes to the contents of binary files.

 + Changes which cause dpkg-source to + print a warning but continue anyway are: + + +

+ Removing files, directories or symlinks. + + Renaming a file is not treated specially - it is + seen as the removal of the old file (which + generates a warning, but is otherwise ignored), + and the creation of the new one. + +

+ + +

+ Changed text files which are missing the usual final + newline (either in the original or the modified + source tree). +

+ + + Changes which are not represented, but which are not detected by + dpkg-source, are: + +

Changing the permissions of files (other than + debian/rules) and directories.

 +

- Urgency keywords are not case-sensitive.

+ The debian directory and debian/rules + are handled specially by dpkg-source - before + applying the changes it will create the debian + directory, and afterwards it will make + debian/rules world-exectuable. +

+ + - Date - - -

- In .changes files and parsed changelogs, this - gives the date the package was built or last edited.

- + + Control files and their fields (from old Packaging Manual) - Format - +

+ Many of the tools in the dpkg suite manipulate + data in a common format, known as control files. Binary and + source packages have control data as do the .changes + files which control the installation of uploaded files, and + dpkg's internal databases are in a similar + format. +

-

- This field occurs in .changes files, and - specifies a format revision for the file. The format - described here is version 1.5. The syntax of the - format value is the same as that of a package version - number except that no epoch or Debian revision is allowed - - see .

- + + Syntax of control files - Changes - +

+ See . +

-

- In a .changes file or parsed changelog this field - contains the human-readable changes data, describing the - differences between the last version and the current one. -

+

+ It is important to note that there are several fields which + are optional as far as dpkg and the related + tools are concerned, but which must appear in every Debian + package, or whose omission may cause problems. +

+ -

- There should be nothing in this field before the first - newline; all the subsequent lines must be indented by at - least one space; blank lines must be represented by a line - consiting only of a space and a full stop. -

+ + List of fields -

- Each version's change information should be preceded by a - "title" line giving at least the version, distribution(s) - and urgency, in a human-readable way. -

+

+ See . +

-

- If data from several versions is being returned the entry - for the most recent version should be returned first, and - entries should be separated by the representation of a - blank line (the "title" line may also be followed by the - representation of blank line).

- +

+ This section now contains only the fields that didn't belong + to the Policy manual. +

- Filename and - MSDOS-Filename - + + Filename and MSDOS-Filename

These fields in Packages files give the @@ -10384,11 +9650,12 @@ install-info --quiet --remove /usr/share/info/foobar.info distribution directories, relative to the root of the Debian hierarchy. If the package has been split into several parts the parts are all listed in order, separated - by spaces.

+ by spaces. +

- Size and MD5sum - + + Size and MD5sum

These fields in Packages files give the size (in @@ -10396,11 +9663,12 @@ install-info --quiet --remove /usr/share/info/foobar.info file(s) which make(s) up a binary package in the distribution. If the package is split into several parts the values for the parts are listed in order, separated by - spaces.

+ spaces. +

- Status - + + Status

This field in dpkg's status file records @@ -10408,66 +9676,68 @@ install-info --quiet --remove /usr/share/info/foobar.info left alone, whether it is broken (requiring reinstallation) or not and what its current state on the system is. Each of these pieces of information is a - single word.

+ single word. +

- Config-Version - + + Config-Version

If a package is not installed or not configured, this field in dpkg's status file records the last version of the package which was successfully - configured.

+ configured. +

- Conffiles - + + Conffiles

This field in dpkg's status file contains information about the automatically-managed configuration files held by a package. This field should not - appear anywhere in a package!

+ appear anywhere in a package! +

- Obsolete fields - + + Obsolete fields

These are still recognised by dpkg but should not appear anywhere any more. + Revision Package-Revision Package_Revision -

The Debian revision part of the package version was at one point in a separate control file field. This - field went through several names.

+ field went through several names. Recommended -

Old name for Recommends

- + Old name for Recommends. Optional -

Old name for Suggests.

- + Old name for Suggests. + Class -

Old name for Priority.

- + Old name for Priority. +

+ - Configuration file handling - (from old Packaging Manual) - + + Configuration file handling (from old Packaging Manual)

dpkg can do a certain amount of automatic @@ -10655,7 +9925,7 @@ install-info --quiet --remove /usr/share/info/foobar.info

- See the manpage for details.