X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=policy.sgml;h=ae7149ff130ac8c9b8bc39ccbe62db152ed9a82f;hb=6e1b2d9c86e05355da2081276decbf3ae3fce4c2;hp=682e55149f83098f5363cfc472c984d398c0231e;hpb=d649a91f80a6d0b033e9499d27f5da48e2dff1cd;p=debian%2Fdebian-policy.git diff --git a/policy.sgml b/policy.sgml index 682e551..ae7149f 100644 --- a/policy.sgml +++ b/policy.sgml @@ -8,7 +8,7 @@ Debian Policy Manual - + The Debian Policy Mailing List version &version;, &date; @@ -46,7 +46,7 @@ . You can also obtain it by writing to the Free Software Foundation, Inc., - 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. + 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.

@@ -66,7 +66,6 @@ distribution.

-

This manual also describes Debian policy as it relates to creating Debian packages. It is not a tutorial on how to build @@ -74,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 @@ -91,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. -

@@ -116,7 +109,13 @@

- In this manual, the words must, should and + The appendices to this manual are not necessarily normative, + either. Please see for more information. +

+ +

+ In the normative part of this manual, + the words must, should and may, and the adjectives required, recommended and optional, are used to distinguish the significance of the various guidelines in @@ -130,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 @@ -137,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 @@ -152,25 +154,35 @@ New versions of this document +

- The current version of this document is always accessible - from the Debian FTP server ftp.debian.org - as - /debian/doc/package-developer/policy.txt.gz - (also available from the same directory are several other - formats: policy.html.tar.gz, policy.pdf.gz - and policy.ps.gz) or from the webpage.

+ This manual is distributed via the Debian package + + (packages.debian.org + /debian-policy). +

- In addition, 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 + . + ( + www.debian.org + /doc/debian-policy/) + Also available from the same directory are several other + formats: policy.html.tar.gz + (/doc/debian-policy/policy.html.tar.gz), + policy.pdf.gz + (/doc/debian-policy/policy.pdf.gz) + and policy.ps.gz + (/doc/debian-policy/policy.ps.gz).

- The debian-policy package also includes the file - upgrading-checklist.txt which indicates policy + The debian-policy package also includes the file + upgrading-checklist.txt.gz which indicates policy changes between versions of this document.

@@ -190,7 +202,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. @@ -220,101 +233,128 @@ 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 in 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 - them (currently well over 6000), they are split into + them (currently well over 15000), they are split into 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. + restrictions. Thus, the archive is split into the distribution + areas or categories 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. +

- The main and the non-US/main sections - together form the Debian GNU/Linux distribution. + The main category forms the + Debian GNU/Linux distribution.

- Packages in the other sections are not considered to be part - 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.

+ Packages in the other distribution areas (contrib, + non-free) are not considered to be part 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. +

- - 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" @@ -326,41 +366,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 @@ -369,372 +401,299 @@ 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. -

-

- - - The main section +

+ + + + Categories + + + The main category +

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

+ Every package in main must comply with the DFSG + (Debian Free Software 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 + + + The contrib category +

- Every package in contrib and - non-US/contrib must comply with the DFSG. + Every package in contrib must comply with the DFSG.

- In addition, the packages in contrib and - non-US/contrib + In addition, the packages in contrib -

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

-

must meet all policy requirements presented in this manual. -

-

- Furthermore, packages in contrib must not require - a package in a non-US section for compilation or - execution. -

Examples of packages which would be included in - contrib or non-US/contrib are: + 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 + + + The non-free category +

- 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. + Packages must be placed in 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 + In addition, the packages in 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", - 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. -

+ + Sections -

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

- 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 packages in the categories main, + contrib and non-free are grouped further + into sections to simplify handling. +

-

- 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 category and section 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: + + + section if the package is in the + main category, + + + segment/section if the package is in + the contrib or non-free + distribution areas. + + +

+ +

+ The Debian archive maintainers provide the authoritative + list of sections. At present, they are: + admin, comm, + devel, doc, + editors, electronics, embedded, + games, gnome, graphics, + hamradio, interpreters, kde, + libs, libdevel, mail, + math, misc, net, news, + 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 + The following priority levels are recognized by the Debian package management tools. 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 - you may not even be able to use dpkg to - 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.

+ functioning of the system (usually, this means that + dpkg functionality depends on these packages). + Removing a required package may cause your + system to become totally broken and you may not even + be able to use dpkg to put things back, + so only do so if you know what you are doing. 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. 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 @@ -742,19 +701,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 @@ -763,19 +720,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 + already know what they are or have specialized requirements. -

-

+ +

Packages must not depend on packages with lower priority @@ -785,542 +740,638 @@

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

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

-

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

+ + The package name -

- Package names must consist 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. +

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

+ + + Version numbers based on dates + +

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

- The package name is part of the file name of the - .deb file and is included in the control field - information. + 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 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. +

+ 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 + they want to bother the upstream maintainer to change + the version numbers upstream, too.

- 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. + Note that other version formats based on dates which are + parsed correctly by the package management system should + not be changed.

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

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

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

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

+

+ 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, they 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 + maintainer-ship 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, + see . + +

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

+ +

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

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

- - Virtual packages +

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

-

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

+

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

+ Essential is defined as the minimal set of functionality + that must be available and usable on the system even + when packages are in an unconfigured (but unpacked) + state. This is needed to avoid unresolvable dependency + loops on upgrade. If packages add unnecessary + dependencies on packages in this set, the chances that + there will be an unresolvable + dependency loop caused by forcing these Essential + packages to be configured first before they need to be + is greatly increased. It also increases the chances + that frontends will be unable to + calculate an upgrade path, even if one + exists. +

+

+ Also, it's pretty unlikely that functionality from + Essential shall ever be removed (which is one reason why + care must be taken before adding to the Essential + packages set), but packages have been removed + from the Essential set when the functionality moved to a + different package. So depending on these packages + just in case they stop being essential does way + more harm than good. +

+ +

-

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

+

+ 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 latest version of the authoritative list of virtual - package names can be found on - ftp.debian.org in - /debian/doc/package-developer/virtual-package-names-list.txt - or your local mirror. In addition, it is included in the - debian-policy package. The procedure for updating - the list is described at the top of the file.

 +

+ 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. Only very few packages are allowed to form + part of the base system, in order 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. -

+

+ The base system consists of all those packages with priority + required or important. 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 +

-

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

+ -

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

+ + Maintainer Scripts -

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

+

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

-

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

- +

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

- - Maintainer Scripts +

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

-

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

+

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

-

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

+

+ 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

- Note that in general applies to package - maintainer scripts, too. + 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.

- You should not use dpkg-divert on a file - belonging to another package without consulting the - maintainer of that package first. + 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 + .

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

- Package maintainer scripts may prompt the user if - necessary. Prompting may be accomplished by hand, or by - communicating with a program, such as - debconf, which conforms to the Debian - Configuration management specification, version 2 or - higher. These are 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. -

- 4% 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-dependencies 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;. + Packages which use the Debian Configuration management + specification must allow for translation of their messages + by using a gettext-based system such as the one provided by + the po-debconf package.

- 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: + + 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 + 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 @@ -1332,552 +1383,321 @@ 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. +

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

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

+

+ +

-

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

- 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 date -R. + ; 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.) + +

+ + + Copyright: debian/copyright +

+ 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). Also see + for further considerations relayed + to copyrights for packages. +

+ + + Error trapping in makefiles - Version - +

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

-

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

+

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

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

+ - Standards-Version - + + Restrictions on objects in source packages -

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

- +

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

+ + + Main building script: debian/rules - 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 - -

- This file must be an executable makefile, and contains the - package-specific recipes for compiling the package and - building binary package(s) from the source. -

+

+ This file must be an executable makefile, and contains the + package-specific recipes for compiling the package and + building binary package(s) from the source. +

It must start with the line #!/usr/bin/make -f, @@ -1899,15 +1719,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 @@ -1950,7 +1769,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 @@ -1963,11 +1781,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 @@ -1975,8 +1832,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 @@ -2011,11 +1867,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. -

@@ -2027,7 +1881,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.

@@ -2072,6 +1926,19 @@ Package: libc6 possible is a good idea.

+ + patch (optional) + +

+ This target performs whatever additional actions are + required to make the source ready for editing (unpacking + additional upstream archives, applying patches, etc.). + It is recommended to be implemented for any package where + dpkg-source -x does not result in source ready + for additional modification. See + . +

+

@@ -2090,7 +1957,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 @@ -2098,19 +1966,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 @@ -2131,331 +1999,967 @@ Package: libc6 or system information; the GNU style variables should be used for that.

+ + + debian/rules and + DEB_BUILD_OPTIONS + +

+ Supporting the standardized environment variable + DEB_BUILD_OPTIONS is recommended. This variable can + contain several flags to change how a package is compiled and + built. Each flag must be in the form flag or + flag=options. If multiple flags are + given, they must be separated by whitespace. + Some packages support any delimiter, but whitespace is the + easiest to parse inside a makefile and avoids ambiguity with + flag values that contain commas. + + flag must start with a lowercase letter + (a-z) and consist only of lowercase letters, + numbers (0-9), and the characters + - and _ (hyphen and underscore). + options must not contain whitespace. The same + tag should not be given multiple times with conflicting + values. Package maintainers may assume that + DEB_BUILD_OPTIONS will not contain conflicting tags. +

+ +

+ The meaning of the following tags has been standardized: + + noopt + + The presence of this tag means that the package should + be compiled with a minimum of optimization. For C + programs, it is best to add -O0 to + CFLAGS (although this is usually the default). + Some programs might fail to build or run at this level + of optimization; it may be necessary to use + -O1, for example. + + nostrip + + This tag means that the debugging symbols should not be + stripped from the binary during installation, so that + debugging information may be included in the package. + + parallel=n + + This tag means that the package should be built using up + to n parallel processes if the package build + system supports this. + Packages built with make can often implement + this by passing the -jn option to + make. + + If the package build system does not support parallel + builds, this string must be ignored. If the package + build system only supports a lower level of concurrency + than n, the package should be built using as + many parallel processes as the package build system + supports. It is up to the package maintainer to decide + whether the package build times are long enough and the + package build system is robust enough to make supporting + parallel builds worthwhile. + + +

+ +

+ Unknown flags must be ignored by debian/rules. +

+ +

+ The following makefile snippet is an example of how one may + implement the build options; you will probably have to + massage this example in order to make it work for your + package. + +CFLAGS = -Wall -g +INSTALL = install +INSTALL_FILE = $(INSTALL) -p -o root -g root -m 644 +INSTALL_PROGRAM = $(INSTALL) -p -o root -g root -m 755 +INSTALL_SCRIPT = $(INSTALL) -p -o root -g root -m 755 +INSTALL_DIR = $(INSTALL) -p -d -o root -g root -m 755 + +ifneq (,$(filter noopt,$(DEB_BUILD_OPTIONS))) + CFLAGS += -O0 +else + CFLAGS += -O2 +endif +ifeq (,$(filter nostrip,$(DEB_BUILD_OPTIONS))) + INSTALL_PROGRAM += -s +endif +ifneq (,$(filter parallel=%,$(DEB_BUILD_OPTIONS))) + NUMJOBS = $(patsubst parallel=%,%,$(filter parallel=%,$(DEB_BUILD_OPTIONS))) + MAKEFLAGS += -j$(NUMJOBS) +endif + +

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

+ + + + Optional upstream source location: debian/watch + +

+ This is an optional, recommended control file for the + uscan utility which defines how to automatically + scan ftp or http sites for newly available updates of the + package. This is used by and other Debian QA tools + to help with quality control and maintenance of the + distribution as a whole. +

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

+ + + + Convenience copies of code

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

+ Some software packages include in their distribution convenience + copies of code from other software packages, generally so that + users compiling from source don't have to download multiple + packages. Debian packages should not make use of these + convenience copies unless the included package is explicitly + intended to be used in this way. + For example, parts of the GNU build system work like this. + + If the included code is already in the Debian archive in the + form of a library, the Debian packaging should ensure that + binary packages reference the libraries already in Debian and + the convenience copy is not used. If the included code is not + already in Debian, it should be packaged separately as a + prerequisite if possible. + + Having multiple copies of the same code in Debian is + inefficient, often creates either static linking or shared + library conflicts, and, most importantly, increases the + difficulty of handling security vulnerabilities in the + duplicated code.

+ + + + Source package handling: + debian/README.source

- 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. + If running dpkg-source -x on a source package + doesn't produce the source of the package, ready for editing, + and allow one to make changes and run + dpkg-buildpackage to produce a modified package + without taking any additional steps, creating a + debian/README.source documentation file is + recommended. This file should explain how to do all of the + following: + + Generate the fully patched source, in a form ready for + editing, that would be built to create Debian + packages. Doing this with a patch target in + debian/rules is recommended; see + . + Modify the source and save those modifications so that + they will be applied when building the package. + Remove source modifications that are currently being + applied when building the package. + Optionally, document what steps are necessary to + upgrade the Debian source package to a new upstream version, + if applicable. + + This explanation should include specific commands and mention + any additional required Debian packages. It should not assume + familiarity with any specific Debian packaging system or patch + management tools.

- 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. + This explanation may refer to a documentation file installed by + one of the package's build dependencies provided that the + referenced documentation clearly explains these tasks and is not + a general reference manual.

- 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. + debian/README.source may also include any other + information that would be helpful to someone modifying the + source package. Even if the package doesn't fit the above + description, maintainers are encouraged to document in a + debian/README.source file any source package with a + particularly complex or unintuitive source layout or build + system (for example, a package that builds the same source + multiple times to generate different binary packages).

+ + - Defining alternative changelog formats -

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

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

- debian/substvars - and variable substitutions + + Syntax of control files

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

- 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. + 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 (logical) 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.

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

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

+ +

+ In fields where it is specified that lines may not wrap, + 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. +

+ +

+ Field names are not case-sensitive, but it is usual to + capitalize the field names using mixed case as shown below. +

+ +

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

+ - debian/files - + + Source package control files -- debian/control

- 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 debian/control file contains the most vital + (and version-independent) information about the source package + and about the binary packages it creates.

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

- 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 fields in the general paragraph (the first one, for the source + package) are: + + + Source (mandatory) + Maintainer (mandatory) + Uploaders + Section (recommended) + Priority (recommended) + Build-Depends et al + Standards-Version (recommended) + Homepage +

- 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 in the binary package paragraphs are: + + + Package (mandatory) + Architecture (mandatory) + Section (recommended) + Priority (recommended) + Essential + Depends et al + Description (mandatory) + Homepage + +

+ +

+ The syntax and semantics of the fields are described below. +

+ + + +

+ 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. Many fields are permitted to span multiple lines in + debian/control but not in any other control + file. These tools are responsible for removing the line + breaks from such fields when using fields from + debian/control to generate other control 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) + Homepage +

- 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 (mandatory) + Source (mandatory) + Version (mandatory) + Maintainer (mandatory) + Uploaders + Binary + Architecture + Build-Depends et al + Standards-Version (recommended) + Files (mandatory) + Homepage + +

- 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 debian/control or a .dsc file, + this field must contain only the name of the source package.

+

+ In a binary package control file or a .changes + file, the source package name 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).

+ + + Uploaders + +

+ List of the names and email addresses of co-maintainers of + the package, if any. If the package has other maintainers + beside the one named in the + Maintainer field, their + names and email addresses should be listed here. The + format is the same as that of the Maintainer tag, and + multiple entries should be comma separated. Currently, + this field is restricted to a single line of data. This + is an optional field. +

- 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. + Any parser that interprets the Uploaders field in + debian/control must permit it to span multiple + lines. Line breaks in an Uploaders field that spans multiple + lines are not significant and the semantics of the field are + the same as if the line breaks had not been present. +

+ + + + Changed-By + +

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

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

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

+ + + + 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, + Breaks, 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, + tilde) 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 + + . ~ (plus, full stop, + tilde) 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 "debianisation" + 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 and so that a tilde + sorts before anything, even the end of a part. For example, + the following parts are in sorted order from earliest to + latest: ~~, ~~a, ~, the empty part, + a. + One common use of ~ is for upstream pre-releases. + For example, 1.0~beta1~svn1245 sorts earlier than + 1.0~beta1, which sorts earlier than 1.0.

+

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

@@ -2471,7 +2975,7 @@ Package: libc6 Those starting with two or more spaces. These will be displayed verbatim. If the display cannot be panned - horizontally, the displaying program will linewrap them "hard" + horizontally, the displaying program will line wrap them "hard" (i.e., without taking account of word breaks). If it can they will be allowed to trail off to the right. None, one or two initial spaces may be deleted, but the number of spaces @@ -2483,7 +2987,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. @@ -2501,49 +3005,421 @@ 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 - + + Distribution - Introduction to package maintainer scripts - +

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

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

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

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

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

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

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

- When a package is upgraded a combination of the scripts from + 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 taking one of the values low, + medium, high, emergency, or + critical + Other urgency values are supported with configuration + changes in the archive software but are not used in Debian. + The urgency affects how quickly a package will be considered + for inclusion into the testing distribution and + gives an indication of the importance of any fixes included + in the upload. Emergency and critical are + treated as synonymous. + (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 + consisting 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. +

+ + + + Homepage + +

+ The URL of the web site for this package, preferably (when + applicable) the site from which the original source can be + obtained and any additional upstream documentation or + information may be found. The content of this field is a + simple URL without any surrounding characters such as + <>. +

+ + + + + + 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 must not be 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. +

+ +

+ Additionally, packages interacting with users using + debconf in the postinst script should + install a config script in the control area, + see for details. +

+ +

+ 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 @@ -2566,7 +3442,7 @@ Package: libc6 start-stop-daemon, install-info, and update-rc.d can be found via the PATH environment variable. Those programs, and any - other program that one would expect to be on the + other program that one would expect to be in the PATH, should thus be invoked without an absolute pathname. Maintainer scripts should also not reset the PATH, though they might choose to modify it by @@ -2574,8 +3450,8 @@ Package: libc6 considerations really apply to all shell scripts.

 - - Maintainer scripts Idempotency + + Maintainer scripts idempotency

It is necessary for the error recovery procedures that the @@ -2587,39 +3463,36 @@ 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

The maintainer scripts are guaranteed to run with a controlling terminal and can interact with the user. - If they need to prompt for passwords, do full-screen - interaction or something similar you should do these - things to and from /dev/tty, since - dpkg will at some point redirect scripts' - standard input and output so that it can log the - installation process. Likewise, because these scripts - may be executed with standard output redirected into a - pipe for logging purposes, Perl scripts should set - unbuffered output by setting $|=1 so that the - output is printed immediately rather than being + Because these scripts may be executed with standard output + redirected into a pipe for logging purposes, Perl scripts + should set unbuffered output by setting $|=1 so + that the output is printed immediately rather than being buffered.

+ + + Exit status

- Each script should return a zero exit status for - success, or a nonzero one for failure. + Each script must return a zero exit status for + success, or a nonzero one for failure, since the package + management system looks for the exit status of these scripts + and determines what action to take next based on that datum.

@@ -2630,118 +3503,112 @@ 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 + + + postinst abort-remove -

deconfigured's-postinst abort-deconfigure in-favour failed-install-package version - removing conflicting-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 + version [removing conflicting-package - version -

+ 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 @@ -2755,39 +3622,57 @@ 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: new-prerm failed-upgrade old-version - Error unwind, for both the above cases: + If this works, the upgrade continues. If this + does not work, the error unwind: old-postinst abort-upgrade new-version -

+ If this works, then the old-version is + "Installed", if not, the old version is in a + "Failed-Config" state. -

+ -

If a "conflicting" package is being removed at the same time: + If a "conflicting" package is being removed at the same time, + or if any package will be broken (due to Breaks): -

- If any packages depended on that conflicting - package and --auto-deconfigure is - specified, call, for each such package: + If --auto-deconfigure is + specified, call, for each package to be deconfigured + due to Breaks: + +deconfigured's-prerm deconfigure \ + in-favour package-being-installed version + + Error unwind: + +deconfigured's-postinst abort-deconfigure \ + in-favour package-being-installed-but-failed version + + The deconfigured packages are marked as + requiring configuration, so that if + --install is used they will be + configured again if possible. + + + If any packages depended on a conflicting + package being removed and --auto-deconfigure is + specified, call, for each such package: deconfigured's-prerm deconfigure \ in-favour package-being-installed version \ @@ -2802,10 +3687,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 each conflicting package, call: conflictor's-prerm remove \ in-favour package new-version @@ -2815,45 +3700,75 @@ 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 -

+ + If this fails, we call: + +new-postrm abort-upgrade old-version + + + +

+ If that works, then + +old-postinst abort-upgrade new-version + + is called. If this works, then the old version + is in an "Installed" state, or else it is left + in an "Unpacked" state. +

+ + +

+ If it fails, then the old version is left + in an "Half-Installed" state. +

+ + + -

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 -

- + + Error unwind: + +new-postrm abort-install old-version + + If this fails, the package is left in a + "Half-Installed" state, which requires a + reinstall. If it works, the packages is left in + a "Config Files" state. + -

Otherwise (i.e., the package was completely purged): + Otherwise (i.e., the package was completely purged): new-preinst install - - Error unwind actions, respectively: - -new-postrm abort-upgrade old-version -new-postrm abort-install old-version + + Error unwind: + new-postrm abort-install - -

+ + If the error-unwind fails, the package is in a + "Half Installed" phase, and requires a + reinstall. If the error unwind works, the + package is in a not installed state. - -

+ +

The new package's files are unpacked, overwriting any @@ -2866,7 +3781,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 - - -

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

- -

- - Debian source control file - .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 . - - -

Source

- - -

Version

- - -

Maintainer

- - -

Binary

- - -

Architecture

- - -

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

- - -

- Standards-Version

- - -

Files

- - - -

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

- - - - Original source archive - - - package_upstream-version.orig.tar.gz - - - - - -

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

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

- -

- 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 dpkg-source program will - automatically make the debian/rules file - executable (see below).

 - - - -

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

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

- - - -

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

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

- + targets clean, build and + binary, dpkg-genchanges and + gpg (or pgp) to build a signed + source and binary package upload.

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

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

 -

Creating directories, other than debian.

+ -psign-command + +

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

 -

Changes to the contents of binary files.

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

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

- -

+ 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

- Changed text files which are missing the usual final - newline (either in the original or the modified - source tree). + Two types of binary-only build and upload - see + .

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

 - -

- -

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

- - - - Control files and their - fields (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. -

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

- -

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

- -

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

- -

- Field names are not case-sensitive, but it is usual to - capitalise the field names using mixed case as shown below. -

- -

- 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 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. When writing - the control files for Debian packages you must read - the Debian policy manual in conjuction with the details - below and the list of fields for the particular file.

- + + + dpkg-gencontrol - generates binary package + control files + - List of fields - +

+ This program is usually called from debian/rules + (see ) in the top level of the source + tree. +

- Package - +

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

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

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

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

- Version - +

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

- This lists the source or binary package's version number - - see . + 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.

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

- This is the architecture string; it is a single word for - the Debian architecture. + This program is usually called from debian/rules + just before dpkg-gencontrol (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. + 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.

- The special value all indicates that the package - is architecture-independent. + 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.)

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

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

- See for information how to get the - architecture for the build process. + 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.

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

- The package maintainer's name and email address. The name - should come first, then the email address inside angle - brackets <> (in RFC822 format). + Some packages' uploads need to include files other than + the source and binary package files.

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

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

+ The section and priority are passed + unchanged into the resulting .changes file. +

- Source - -

- This field identifies the source package name. -

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

- 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. + This program is usually called by package-independent + automatic building scripts such as + dpkg-buildpackage, but it may also be called + by hand.

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

- Package interrelationship fields: - Depends, Pre-Depends, - Recommends Suggests, Conflicts, - Provides, Replaces + + + + dpkg-parsechangelog - produces parsed + representation of a changelog

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

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

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

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

+ + -

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

- + + The Debianised source tree - Essential - +

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

-

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

+

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

+ + + debian/rules - the main building script

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

+ See . +

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

+ + debian/changelog

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

- 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. + It is recommended that the entire changelog be encoded in the + + encoding of + . +

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

+

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

+

-

- These fields are not used by by dpkg proper, - but by dselect when it sorts packages and - selects defaults. See the Debian policy manual for the - priorities in use and the criteria for selecting the - priority for a Debian package, and look at the Debian FTP - archive for a list of currently in-use priorities. -

+ Defining alternative changelog formats + -

- These fields may 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.

- +

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

- Binary - +

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

-

- This field is a list of binary packages. -

+

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

-

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

+

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

-

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

+

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

-

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

- +

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

- Installed-Size - +

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

-

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

+

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

-

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

+

+ 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 synthesize + 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 - dpkg programmers' and policy manuals 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 file system 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).

 + +

+ +

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

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

+ + - 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 @@ -10360,11 +10240,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 @@ -10372,78 +10253,81 @@ 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 whether the user wants a package installed, removed or left alone, whether it is broken (requiring - reinstallation) or not and what its current state on the + re-installation) 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 + These are still recognized 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 @@ -10526,7 +10410,7 @@ install-info --quiet --remove /usr/share/info/foobar.info When a package is installed for the first time dpkg will install the file that comes with it, unless that would mean overwriting a file already on the - filesystem. + file system.

@@ -10631,7 +10515,7 @@ install-info --quiet --remove /usr/share/info/foobar.info

- See the manpage for details.

@@ -10708,4 +10592,7 @@ install-info --quiet --remove /usr/share/info/foobar.info + + +