distribution.
</p>
-
<p>
This manual also describes Debian policy as it relates to
creating Debian packages. It is not a tutorial on how to build
</p>
<p>
- In this manual, the words <em>must</em>, <em>should</em> and
+ The appendices to this manual are not necessarily normative,
+ either. Please see <ref id="pkg-scope"> for more information.
+ </p>
+
+ <p>
+ In the normative part of this manual,
+ the words <em>must</em>, <em>should</em> and
<em>may</em>, and the adjectives <em>required</em>,
<em>recommended</em> and <em>optional</em>, are used to
distinguish the significance of the various guidelines in
<sect>
<heading>New versions of this document</heading>
+
<p>
- The current version of this document is always accessible
- from the Debian FTP server <ftpsite>ftp.debian.org</ftpsite>
- as
- <ftppath>/debian/doc/package-developer/policy.txt.gz</ftppath>
- (also available from the same directory are several other
- formats: <file>policy.html.tar.gz</file>, <file>policy.pdf.gz</file>
- and <file>policy.ps.gz</file>) or from the <url
- id="http://www.debian.org/doc/debian-policy/" name="Debian
- Policy Manual"> webpage.</p>
+ This manual is distributed via the Debian package
+ <package>debian-policy</package>.
+ </p>
<p>
- In addition, this manual is distributed via the Debian package
- <file>debian-policy</file>.
+ The current version of this document is also available from
+ the Debian web mirrors at
+ <tt><url name="/doc/debian-policy/"
+ id="http://www.debian.org/doc/debian-policy/"></tt>
+ and from the Debian archive mirrors at
+ <tt><url name="/doc/package-developer/policy.txt.gz"
+ id="http://ftp.debian.org/debian/doc/package-developer/policy.txt.gz"></tt>.
+ Also available from the same directory are several other
+ formats: <file>policy.html.tar.gz</file>, <file>policy.pdf.gz</file>
+ and <file>policy.ps.gz</file>.
</p>
<p>
- The <tt>debian-policy</tt> package also includes the file
+ The <package>debian-policy</package> package also includes the file
<file>upgrading-checklist.txt</file> which indicates policy
changes between versions of this document.
</p>
statements and other administrivia should not be included
either (that is what the copyright file is for).
</p>
+
+ <p>
+ Please refer to <ref id="descriptions"> for more information.
+ </p>
+
</sect1>
doing that has been reached.</p></sect1>
- <sect1 id="virtual_pkg_sect">
+ <sect1 id="virtual_pkg">
<heading>Virtual packages</heading>
<p>
<p>
The latest version of the authoritative list of virtual
- package names can be found on
- <ftpsite>ftp.debian.org</ftpsite> in
- <ftppath>/debian/doc/package-developer/virtual-package-names-list.txt</ftppath>
- or your local mirror. In addition, it is included in the
- <tt>debian-policy</tt> package. The procedure for updating
- the list is described at the top of the file.</p></sect1>
+ package names can be found in the <tt>debian-policy</tt> package.
+ It's also available from the Debian web mirrors at
+ <tt><url name="/doc/packaging-manuals/virtual-package-names-list.txt"
+ id="http://www.debian.org/doc/packaging-manuals/virtual-package-names-list.txt"></tt>
+ and from the Debian archive mirrors at
+ <tt><url name="/doc/package-developer/virtual-package-names-list.txt"
+ id="http://ftp.debian.org/debian/doc/package-developer/virtual-package-names-list.txt"></tt>.
+ </p>
+ <p>
+ The procedure for updating the list is described in the preface
+ to the list.
+ </p>
+
+ </sect1>
<sect1>
<heading>Base system</heading>
<p>
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
+ 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
</sect1>
- <sect1>
+ <sect1 id="pkg-relations">
<heading>Package relationships</heading>
<p>
are properly satisfied.
</p>
+ <p>
+ <ref id="relationships"> explains the technical details.
+ </p>
+
<sect1>
<heading>Changes to the upstream sources</heading>
<p>
The version number format is:
- [<var>epoch</var><tt>:</tt>]<var>upstream_version</var>[<tt>-</tt><var>debian_revision</var>]
+ [<var>epoch</var><tt>:</tt>]<var>upstream_version</var>[<tt>-</tt><var>debian_revision</var>]
</p>
<p>
</sect1>
</sect>
+<!-- FIXME: section pkg-srcsubstvars is the same as srcsubstvars -->
+
<sect id="srcsubstvars"><heading><file>debian/substvars</file>
and variable substitutions </heading>
<p>
The <file>debian/substvars</file> file is usually generated and
- modified dynamically by <file>debian/rules</file> targets; in
- this case it must be removed by the <tt>clean</tt>
- target.
+ modified dynamically by <file>debian/rules</file> targets, in
+ which case it must be removed by the <tt>clean</tt> target.
</p>
<p>
</footnote>
</p>
</sect>
+
<sect id="descriptions"><heading>Descriptions of packages - the
- <tt>Description</tt> field </heading>
+ <tt>Description</tt> field</heading>
+
+ <p>
+ 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:
+ </p>
+
+ <p><example>
+ Description: <single line synopsis>
+ <extended description over several lines>
+</example></p>
<p>
The description is intended to describe the program to a user
conflicts have been declared.
</p>
- <sect1><heading>Notes about writing descriptions
- </heading>
+ <p>
+ 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.
+ </p>
+
+ <sect1 id="synopsis"><heading>The single line synopsis</heading>
<p>
The single line synopsis should be kept brief - certainly
informative as you can.
</p>
+ </sect1>
+
+ <sect1 id="extendeddesc"><heading>The extended description</heading>
+
<p>
Do not try to continue the single line synopsis into the
extended description. This will not work correctly when
The description field needs to make sense to anyone, even
people who have no idea about any of the things the
package deals with.<footnote>
- <p>
The blurb that comes with a program in its
announcements and/or <prgn>README</prgn> 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.
- </p>
</footnote>
</p>
<p>
- 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 lines in the extended description can have these formats:
</p>
- <p>
- You may include information about dependencies and so forth
- in the extended description, if you wish.
- </p>
+ <p><list>
+
+ <item>
+ Those starting with a single space are part of a paragraph.
+ Successive lines of this form will be word-wrapped when
+ displayed. The leading space will usually be stripped off.
+ </item>
+
+ <item>
+ 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"
+ (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
+ deleted from each line will be the same (so that you can have
+ indenting work correctly, for example).
+ </item>
+
+ <item>
+ Those containing a single space followed by a single full stop
+ character. These are rendered as blank lines. This is the
+ <em>only</em> way to get a blank line<footnote>
+ 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.
+ </footnote>.
+ </item>
+
+ <item>
+ Those containing a space, a full stop and some more characters.
+ These are for future expansion. Do not use them.
+ </item>
+
+ </list></p>
<p>
Do not use tab characters. Their effect is not predictable.
</p>
</sect1>
+
</sect>
+
</chapt>
<chapt id="relationships"><heading>Declaring relationships between
packages</heading>
- <p>
- Packages can declare in their control file that they have
- certain relationships to other packages - for example, that
- they may not be installed at the same time as certain other
- packages, and/or that they depend on the presence of others,
- or that they should overwrite files in certain other packages
- if present.
- </p>
-
- <p>
- This is done using the <tt>Depends</tt>, <tt>Pre-Depends</tt>,
- <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
- <tt>Conflicts</tt>, <tt>Provides</tt> and <tt>Replaces</tt>
- control file fields.
- </p>
-
- <p>
- Source packages may declare relationships to binary packages,
- saying that they require certain binary packages to be
- installed or absent at the time of building the package.
- </p>
-
- <p>
- This is done using the <tt>Build-Depends</tt>,
- <tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts</tt> and
- <tt>Build-Conflicts-Indep</tt> control file fields.
- </p>
-
<sect id="depsyntax"><heading>Syntax of relationship fields
</heading>
<tt>Pre-Depends</tt>
</heading>
+ <p>
+ Packages can declare in their control file that they have
+ certain relationships to other packages - for example, that
+ they may not be installed at the same time as certain other
+ packages, and/or that they depend on the presence of others.
+ </p>
+
+ <p>
+ This is done using the <tt>Depends</tt>, <tt>Pre-Depends</tt>,
+ <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt> and
+ <tt>Conflicts</tt> control file fields.
+ </p>
+
<p>
- These five fields are used to declare a dependency
+ These six fields are used to declare a dependency
relationship by one package on another. Except for
<tt>Enhances</tt>, they appear in the depending (binary)
package's control file. (<tt>Enhances</tt> appears in the
The effect is as if the package(s) which provide a
particular virtual package name had been listed by name
everywhere the virtual package name appears. (See also <ref
- id="virtual_pkg_sect">)
+ id="virtual_pkg">)
</p>
<p>
packages - <tt>Replaces</tt></heading>
<p>
- The <tt>Replaces</tt> control file field has two distinct
- purposes, which come into play in different situations.
+ Packages can declare in their control file that they should
+ overwrite files in certain other packages, or completely
+ replace other packages. The <tt>Replaces</tt> control file
+ field has these two distinct purposes.
</p>
<sect1><heading>Overwriting files in other packages</heading>
<tt>Build-Conflicts</tt>, <tt>Build-Conflicts-Indep</tt>
</heading>
+ <p>
+ Source packages that require certain binary packages to be
+ installed or absent at the time of building the package
+ can declare relationships to those binary packages.
+ </p>
+
<p>
- A source package may declare a dependency or a conflict on a
- binary package, indicating which packages are required to be
- present on the system in order to build the binary packages
- from the source package. This is done with the control file
- fields <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
- <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>.
+ This is done using the <tt>Build-Depends</tt>,
+ <tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts</tt> and
+ <tt>Build-Conflicts-Indep</tt> control file fields.
+ </p>
+
+ <p>
+ Build-dependencies on "build-essential" binary packages can be
+ omitted. Please see <ref id="pkg-relations"> for more information.
+ </p>
+
+ <p>
The dependencies and conflicts they define must be satisfied
(as defined earlier for binary packages) in order to invoke
the targets in <tt>debian/rules</tt>, as follows:<footnote>
</p>
<p>
- Firstly, the package should install the shared libraries under
- their normal names. For example, the <tt>libgdbmg1</tt>
- package should install <tt>libgdbm.so.1.7.3</tt> as
+ Packages involving shared libraries should be split up into
+ several binary packages. This section mostly deals with how
+ this separation is to be accomplished; rules for files within
+ the shared library packages are in <ref id="libraries"> instead.
+ </p>
+
+ <sect id="sharedlibs-runtime">
+ <heading>Run-time shared libraries</heading>
+
+ <p>
+ The run-time shared library needs to be placed in a package called
+ <package><var>libraryname</var><var>soversion</var></package>, where
+ <file><var>soversion</var></file> is the version number in the
+ soname of the shared library<footnote>
+ <p>
+ The soname is the shared object name: it's the thing
+ that has to match exactly between building an executable
+ and running it for the dynamic linker to be able run the
+ program. For example, if the soname of the library is
+ <file>libfoo.so.6</file>, the library package would be
+ called <file>libfoo6</file>.
+ </p>
+ </footnote>.
+ Alternatively, if it would be confusing to directly append
+ <var>soversion</var> to <var>libraryname</var> (e.g. because
+ <var>libraryname</var> itself ends in a number), you may use
+ <package><var>libraryname</var>-<var>soversion</var></package> and
+ <package><var>libraryname</var>-<var>soversion</var>-dev</package>
+ instead.
+ </p>
+
+ <p>
+ If you have several shared libraries built from the same
+ source tree you may lump them all together into a single
+ shared library package, provided that you change all of
+ their sonames at once (so that you don't get filename
+ clashes if you try to install different versions of the
+ combined shared libraries package).
+ </p>
+
+ <p>
+ The package should install the shared libraries under
+ their normal names. For example, the <package>libgdbmg1</package>
+ package should install <file>libgdbm.so.1.7.3</file> as
<file>/usr/lib/libgdbm.so.1.7.3</file>. The files should not be
renamed or re-linked by any <prgn>prerm</prgn> or
<prgn>postrm</prgn> scripts; <prgn>dpkg</prgn> will take care
</p>
<p>
- Secondly, the package should include the symbolic link that
+ Shared libraries should not be installed executable, since
+ the dynamic linker does not require this and trying to
+ execute a shared library usually results in a core dump.
+ </p>
+
+ <p>
+ The run-time library package should include the symbolic link that
<prgn>ldconfig</prgn> would create for the shared libraries.
- For example, the <prgn>libgdbmg1</prgn> package should include
+ For example, the <package>libgdbmg1</package> package should include
a symbolic link from <file>/usr/lib/libgdbm.so.1</file> to
<file>libgdbm.so.1.7.3</file>. This is needed so that the dynamic
linker (for example <prgn>ld.so</prgn> or
<file>.deb</file> depended on the behavior of the underlying
file system. Some file systems (such as reiserfs) reorder
the files so that the order of creation is forgotten.
- S
tarting with release <tt>1.7.0</tt>, <prgn>dpkg</prgn>
- will reorder the files itself as necessary when building a
+ S
ince version 1.7.0, <prgn>dpkg</prgn>
+ reorders the files itself as necessary when building a
package. Thus it is no longer important to concern
oneself with the order of file creation.
</p>
</footnote>
</p>
- <p>
- Thirdly, the associated development package should contain a
- symlink for the shared library without a version number. For
- example, the <tt>libgdbmg1-dev</tt> package should include a
- symlink from <tt>/usr/lib/libgdbm.so</tt> to
- <file>libgdbm.so.1.7.3</file>. This symlink is needed by the
- linker (<prgn>ld</prgn>) when compiling packages, as it will
- only look for <file>libgdbm.so</file> when compiling dynamically.
- </p>
+ <sect1 id="ldconfig">
+ <heading><tt>ldconfig</tt></heading>
<p>
Any package installing shared libraries in one of the default
</p>
</footnote>
must use <prgn>ldconfig</prgn> to update the shared library
- system. The package must call <prgn>ldconfig</prgn> in the
+ system.
+ </p>
+
+ <p>
+ The package must call <prgn>ldconfig</prgn> in the
<prgn>postinst</prgn> script if the first argument is
<tt>configure</tt>; the <prgn>postinst</prgn> script may
optionally invoke <prgn>ldconfig</prgn> at other times. The
</p>
</footnote>
</p>
+ </sect1>
- <sect>
- <heading>Handling shared library dependencies - the
- <tt>shlibs</tt> system</heading>
+ </sect>
+
+ <sect id="sharedlibs-runtime-progs">
+ <heading>Run-time support programs</heading>
+
+ <p>
+ If your package has some run-time support programs which use
+ the shared library you must not put them in the shared
+ library package. If you do that then you won't be able to
+ install several versions of the shared library without
+ getting filename clashes.
+ </p>
+
+ <p>
+ Instead, either create another package for the runtime binaries
+ (this package might typically be named
+ <package><var>libraryname</var>-runtime</package>; note the absence
+ of the <var>soversion</var> in the package name), or if the
+ development package is small, include them in there.
+ </p>
+ </sect>
+
+ <sect id="sharedlibs-static">
+ <heading>Static libraries</heading>
+
+ <p>
+ The static library (<file><var>libraryname.a</var></file>)
+ is usually provided in addition to the shared version.
+ It is placed into the development package (see below).
+ </p>
+
+ <p>
+ In some cases, it is acceptable for a library to be
+ available in static form only; these cases include:
+ <list>
+ <item>libraries for languages whose shared library support
+ is immature or unstable</item>
+ <item>libraries whose interfaces are in flux or under
+ development (commonly the case when the library's
+ major version number is zero, or where the ABI breaks
+ across patchlevels)</item>
+ <item>libraries which are explicitly intended to be
+ available only in static form by their upstream
+ author(s)</item>
+ </list>
+ </p>
+
+ <sect id="sharedlibs-dev">
+ <heading>Development files</heading>
+
+ <p>
+ The development files associated to a shared library need to be
+ placed in a package called
+ <package><var>libraryname</var><var>soversion</var>-dev</package>,
+ or if you prefer only to support one development version at a
+ time, <package><var>libraryname</var>-dev</package>.
+ </p>
+
+ <p>
+ In case several development versions of a library exist, you may
+ need to use <prgn>dpkg</prgn>'s Conflicts mechanism (see
+ <ref id="conflicts">) to ensure that the user only installs one
+ development version at a time (as different development versions are
+ likely to have the same header files in them, which would cause a
+ filename clash if both were installed).
+ </p>
+
+ <p>
+ The development package should contain a symlink for the associated
+ shared library without a version number. For example, the
+ <package>libgdbmg1-dev</package> package should include a symlink
+ from <file>/usr/lib/libgdbm.so</file> to
+ <file>libgdbm.so.1.7.3</file>. This symlink is needed by the linker
+ (<prgn>ld</prgn>) when compiling packages, as it will only look for
+ <file>libgdbm.so</file> when compiling dynamically.
+ </p>
+ </sect>
+
+ <sect id="sharedlibs-intradeps">
+ <heading>Dependencies between the packages of the same library</heading>
+
+ <p>
+ Typically the development version should have an exact
+ version dependency on the runtime library, to make sure that
+ compilation and linking happens correctly. The
+ <tt>${Source-Version}</tt> substitution variable can be
+ useful for this purpose.
+ </p>
+ </sect>
+
+ <sect id="sharedlibs-shlibdeps">
+ <heading>Dependencies between the library and other packages -
+ the <tt>shlibs</tt> system</heading>
<p>
If a package contains a binary or library which links to a
<tt>shlibs</tt> file format and how to create them if your
package contains a shared library.
</p>
- </sect>
- <sect><heading>The <tt>shlibs</tt> files present on the system
- </heading>
+ <sect1>
+ <heading>The <tt>shlibs</tt> files present on the system</heading>
<p>
There are several places where <tt>shlibs</tt> files are
</item>
</list>
</p>
- </sect>
+ </sect1>
- <sect>
+ <sect1>
<heading>How to use <prgn>dpkg-shlibdeps</prgn> and the
<file>shlibs</file> files</heading>
For more details on this and other options, see <manref
name="dpkg-shlibdeps" section="1">.
</p>
- </sect>
+ </sect1>
- <sect id="shlibs"><heading>The <file>shlibs</file> File Format
- </heading>
+ <sect1 id="shlibs">
+ <heading>The <file>shlibs</file> File Format</heading>
<p>
Each <file>shlibs</file> file has the same format. Lines
the dynamic linker about using older shared libraries with
newer binaries.
</p>
- </sect>
+ </sect1>
- <sect>
+ <sect1>
<heading>Providing a <file>shlibs</file> file</heading>
<p>
<prgn>dpkg-shlibdeps</prgn> is called on any of the binary
packages.
</p>
- </sect>
+ </sect1>
- <sect id="shlibslocal">
+ <sect1 id="shlibslocal">
<heading>Writing the <file>debian/shlibs.local</file> file</heading>
<p>
on <tt>bar1</tt> to help ensure that others do not have the
same problem building your package.)
</p>
+ </sect1>
+
</sect>
+
</chapt>
<chapt id="opersys"><heading>The Operating System</heading>
<item><p>stop the service,</p></item>
<tag><tt>restart</tt></tag>
- <item><p>stop and restart the service,</p></item>
+ <item><p>stop and restart the service if it's already
+ running, otherwise start the service</p></item>
<tag><tt>reload</tt></tag>
<item><p>cause the configuration of the service to be
interprets the argument <tt>reload</tt> to send the
nameserver a <tt>HUP</tt> signal (causing it to reload its
configuration); this way the system administrator can say
- <file>/etc/init.d/bind reload</file> to reload the name
+ <tt>/etc/init.d/bind reload</tt> to reload the name
server. The script has one configurable value, which can
be used to pass parameters to the named program at
startup; this value is read from
<sect>
<heading>Menus</heading>
- <p>
- Menu entries should follow the current menu policy found in
- the <tt>menu-policy</tt> files in the <tt>debian-policy</tt>
- package. It may also be found on the Debian FTP site
- <ftpsite>ftp.debian.org</ftpsite> as the file
- <ftppath>/debian/doc/package-developer/menu-policy.txt.gz</ftppath>,
- or in the equivalent location on your local mirror.
- </p>
-
<p>
The Debian <tt>menu</tt> package provides a standard
interface between packages providing applications and
operation should register a menu entry for those
applications, so that users of the <tt>menu</tt> package
will automatically get menu entries in their window
- managers, as well in shells like <tt>pdmenu</tt>.</p>
+ managers, as well in shells like <tt>pdmenu</tt>.
+ </p>
+
+ <p>
+ Menu entries should follow the current menu policy.
+ </p>
+
+ <p>
+ The menu policy can be found in the <tt>menu-policy</tt>
+ files in the <tt>debian-policy</tt> package.
+ They are also available from the Debian web mirrors at
+ <tt><url name="/doc/packaging-manuals/menu-policy/"
+ id="http://www.debian.org/doc/packaging-manuals/menu-policy/"></tt>
+ and from the Debian archive mirrors at
+ <tt><url name="/doc/package-developer/menu-policy.txt.gz"
+ id="http://ftp.debian.org/debian/doc/package-developer/menu-policy.txt.gz"></tt>.
+ </p>
<p>
Please also refer to the <em>Debian Menu System</em>
<sect>
<heading>Multimedia handlers</heading>
- <p>
- Packages which provide the ability to view/show/play,
- compose, edit or print MIME types should register themselves
- as such following the current MIME support policy found in
- the <tt>mime-policy</tt> files in the <tt>debian-policy</tt>
- package. It may also be found on the Debian FTP site
- <ftpsite>ftp.debian.org</ftpsite> as the file
- <ftppath>/debian/doc/package-developer/mime-policy.txt.gz</ftppath>,
- or in the equivalent location on your local mirror.
- </p>
-
<p>
MIME (Multipurpose Internet Mail Extensions, RFCs 2045-2049)
is a mechanism for encoding files and data streams and
view, edit or display MIME types they don't support
directly.
</p>
+
+ <p>
+ Packages which provide the ability to view/show/play,
+ compose, edit or print MIME types should register themselves
+ as such following the current MIME support policy.
+ </p>
+
+ <p>
+ The MIME support policy can be found in the <tt>mime-policy</tt>
+ files in the <tt>debian-policy</tt> package.
+ They are also available from the Debian web mirrors at
+ <tt><url name="/doc/packaging-manuals/mime-policy/"
+ id="http://www.debian.org/doc/packaging-manuals/mime-policy/"></tt>
+ and from the Debian archive mirrors at
+ <tt><url name="/doc/package-developer/mime-policy.txt.gz"
+ id="http://ftp.debian.org/debian/doc/package-developer/mime-policy.txt.gz"></tt>.
+ </p>
+
</sect>
<sect>
</sect>
- <sect>
+ <sect id="libraries">
<heading>Libraries</heading>
+
<p>
- In general, libraries must have a shared version in the
- library package and a static version in the development
- package. The shared version must be compiled with
- <tt>-fPIC</tt>, and the static version must not be. In
- other words, each source unit ( <tt>*.c</tt>, for example,
- for C files) will need to be compiled twice.
- </p>
- <p>
- In some cases, it is acceptable for a library to be
- available in static form only; these cases include:
- <list>
- <item>
- <p>libraries for languages whose shared library support
- is immature or unstable</p>
- </item>
- <item>
- <p>
- libraries whose interfaces are in flux or under
- development (commonly the case when the library's
- major version number is zero, or where the ABI breaks
- across patchlevels)
- </p>
- </item>
- <item>
- <p>
- libraries which are explicitly intended to be
- available only in static form by their upstream
- author(s)</p>
- </item>
- </list>
- If a library is available only in static form, then it must follow
- the conventions for a development package.
+ The shared version of a library must be compiled with
+ <tt>-fPIC</tt>, and the static version must not be. In other
+ words, each source unit (<tt>*.c</tt>, for example, for C files)
+ will need to be compiled twice.
</p>
- <p>
- All libraries must have a shared version in the
- <tt>lib*</tt> package and a static version in the
- <tt>lib*-dev</tt> package. The shared version must be
- compiled with <tt>-fPIC</tt>, and the static version must
- not be. In other words, each <tt>*.c</tt> file will need to
- be compiled twice.</p>
+
<p>
You must specify the gcc option <tt>-D_REENTRANT</tt>
when building a library (either static or shared) to make
- the library compatible with LinuxThreads.</p>
+ the library compatible with LinuxThreads.
+ </p>
<p>
- Note that all installed shared libraries should be
- stripped with
+ All installed shared libraries should be stripped with
<example compact="compact">
strip --strip-unneeded <var>your-lib</var>
</example>
</p>
</sect>
+
<sect>
<heading>Shared libraries</heading>
-
- <p>
- Packages involving shared libraries should be split up
- into several binary packages.</p>
-
- <p>
- For a straightforward library which has a development
- environment and a runtime kit including just shared
- libraries you need to create two packages:
- <file><var>libraryname</var><var>soversion</var></file>, where
- <file><var>soversion</var></file> is the version number in the
- soname of the shared library<footnote>
- <p>
- The soname is the shared object name: it's the thing
- that has to match exactly between building an executable
- and running it for the dynamic linker to be able run the
- program. For example, if the soname of the library is
- <file>libfoo.so.6</file>, the library package would be
- called <file>libfoo6</file>.
- </p>
- </footnote>
- and <tt><var>libraryname</var><var>soversion</var>-dev</tt>.
- Alternatively, if it would be confusing to directly append
- <var>soversion</var> to <var>libraryname</var> (e.g. because
- <var>libraryname</var> itself ends in a number), you may use
- <tt><var>libraryname</var>-<var>soversion</var></tt> and
- <tt><var>libraryname</var>-<var>soversion</var>-dev</tt>
- instead.
- </p>
-
- <p>
- If you prefer only to support one development version at a
- time you may name the development package
- <file><var>libraryname</var>-dev</file>; otherwise you may need
- to use <prgn>dpkg</prgn>'s Conflicts mechanism (see <ref
- id="conflicts">) to ensure that the user only installs one
- development version at a time (as different development
- versions are likely to have the same header files in them,
- which would cause a filename clash if both were installed).
- Typically the development version should also have an exact
- version dependency on the runtime library, to make sure that
- compilation and linking happens correctly. The
- <tt>${Source-Version}</tt> substitution variable can be
- useful for this purpose.
- </p>
-
- <p>
- Packages which use the shared library should have a
- dependency on the name of the shared library package,
- <file><var>libraryname</var><var>soversion</var></file>. When
- the soname changes you can have both versions of the library
- installed while migrating from the old library to the new.
- </p>
-
<p>
- If your package has some run-time support programs which use
- the shared library you must not put them in the shared
- library package. If you do that then you won't be able to
- install several versions of the shared library without
- getting filename clashes. Instead, either create a third
- package for the runtime binaries (this package might
- typically be named <tt><var>libraryname</var>-runtime</tt>;
- note the absence of the <var>soversion</var> in the package
- name), or if the development package is small you may
- include them in there.
- </p>
-
- <p>
- If you have several shared libraries built from the same
- source tree you may lump them all together into a single
- shared library package, provided that you change all of
- their sonames at once (so that you don't get filename
- clashes if you try to install different versions of the
- combined shared libraries package).
- </p>
-
- <p>
- Shared libraries should not be installed executable, since
- the dynamic linker does not require this and trying to
- execute a shared library usually results in a core dump.
+ This section has moved to <ref id="sharedlibs">.
</p>
</sect>
+
<sect id="scripts">
<heading>Scripts</heading>
<heading>Location</heading>
<p>
Any configuration files created or used by your package
- must reside in <file>/etc</file>. If there are several you
- should consider creating a subdirectory of <file>/etc</file>
+ must reside in <file>/etc</file>. If there are several,
+ consider creating a subdirectory of <file>/etc</file>
named after your package.</p>
<p>
If your package creates or uses configuration files
outside of <file>/etc</file>, and it is not feasible to modify
- the package to use the <file>/etc</file>, you should still put
- the files in <file>/etc</file> and create symbolic links to
- those files from the location that the package
- requires.</p>
+ the package to use <file>/etc</file> directly, put the files
+ in <file>/etc</file> and create symbolic links to those files
+ from the location that the package requires.</p>
</sect1>
<sect1>
<p>
However, programs that require dotfiles in order to
- operate sensibly (dotfiles that they do not create
- themselves automatically, that is) are a bad thing.
+ operate sensibly are a bad thing, unless they do create
+ the dotfiles themselves automatically.
+ </p>
+
+ <p>
Furthermore, programs should be configured by the Debian
default installation to behave as closely to the upstream
default behaviour as possible.
file (for more information see <manref name="logrotate"
section="8">):
<example compact="compact">
-/var/log/foo/* {
+/var/log/foo/*.log {
rotate 12
weekly
compress
that a dynamically allocated id can be used. In this case
you should choose an appropriate user or group name,
discussing this on <prgn>debian-devel</prgn> and checking
- with the base system maintainer that it is unique and that
+ with the <package/base-passwd/ maintainer that it is unique and that
they do not wish you to use a statically allocated id
instead. When this has been checked you must arrange for
your package to create the user or group if necessary using
<sect>
<heading>Perl programs and modules</heading>
+
+ <p>
+ Perl programs and modules should follow the current Perl policy.
+ </p>
+
<p>
- Perl programs and modules should follow the current Perl
- policy as defined in the file found on
- <ftpsite>ftp.debian.org</ftpsite> in
- <ftppath>/debian/doc/package-developer/perl-policy.txt.gz</ftppath>
- or your local mirror. In addition, it is included in the
- <tt>debian-policy</tt> package.
+ The Perl policy can be found in the <tt>perl-policy</tt>
+ files in the <tt>debian-policy</tt> package.
+ They are also available from the Debian web mirrors at
+ <tt><url name="/doc/packaging-manuals/perl-policy/"
+ id="http://www.debian.org/doc/packaging-manuals/perl-policy/"></tt>
+ and from the Debian archive mirrors at
+ <tt><url name="/doc/package-developer/perl-policy.txt.gz"
+ id="http://ftp.debian.org/debian/doc/package-developer/perl-policy.txt.gz"></tt>.
</p>
</sect>
<heading>Emacs lisp programs</heading>
<p>
- Please refer to the "Debian Emacs Policy" (documented in
- <file>debian-emacs-policy.gz</file> of the
- <prgn>emacsen-common</prgn> package) for details of how to
+ Please refer to the "Debian Emacs Policy" for details of how to
package emacs lisp programs.
</p>
+
+ <p>
+ The Emacs policy is available in
+ <file>debian-emacs-policy.gz</file> of the
+ <package>emacsen-common</package> package.
+ It is also available from the Debian web mirrors at
+ <tt><url name="/doc/packaging-manuals/debian-emacs-policy"
+ id="http://www.debian.org/doc/packaging-manuals/debian-emacs-policy"></tt>.
+ </p>
</sect>
<sect>
<p>
You should install manual pages in <prgn>nroff</prgn> source
- form, in appropriate places under <file>/usr/share/man</file>. You
- should only use sections 1 to 9 (see the FHS for more
- details). You must not install a preformatted "cat
- page".</p>
+ form, in appropriate places under <file>/usr/share/man</file>.
+ You should only use sections 1 to 9 (see the FHS for more
+ details). You must not install a preformatted "cat page".
+ </p>
<p>
Each program, utility, and function should have an
- associated manpage included in the same package. It is
+ associated manual page included in the same package. It is
suggested that all configuration files also have a manual
- page included as well.
+ page included as well. Manual pages for protocols and other
+ auxiliary things are optional.
</p>
<p>
- There should be a manual page at for every program at the
- very least, and possibly one for every configuration file,
- protocol, utility, and function. If no manual page is
- available, this is considered as a bug and should be
- reported to the Debian Bug Tracking System (the maintainer
- of the package is allowed to write this bug report
+ If no manual page is available, this is considered as a bug
+ and should be reported to the Debian Bug Tracking System (the
+ maintainer of the package is allowed to write this bug report
themselves, if they so desire). Do not close the bug report
until a proper manpage is available.<footnote>
<p>
</footnote>.
Any files that are referenced by programs but are also
useful as standalone documentation should be installed under
- <file>/usr/share/doc/</file> with symbolic links from
+ <file>/usr/share/<var>package</var>/</file> with symbolic links from
<file>/usr/share/doc/<var>package</var></file>.
</p>
latter directory itself may be a symbolic link to the
former.
</p>
+
+ <p>
+ If the purpose of a package is to provide examples, then the
+ example files may be installed into
+ <file>/usr/share/doc/<var>package</var></file>.
+ </p>
</sect>
<sect id="changelogs">
please see their manpages.
</p>
- <p>
- It does <em>not</em> describe the policy requirements imposed
- on Debian packages, such as the permissions on files and
- directories, documentation requirements, upload procedure, and
- so on. You should see the Debian packaging policy manual for
- these details. (Many of them will probably turn out to be
- helpful even if you don't plan to upload your package and make
- it available as part of the distribution.)
- </p>
-
<p>
It is assumed that the reader is reasonably familiar with the
<prgn>dpkg</prgn> System Administrators' manual.
the easy and automatic building of binaries.
</p>
- <p>
- There was a previous version of the Debian source format,
- which is now being phased out. Instructions for converting an
- old-style package are given in the Debian policy manual.
- </p>
-
<sect id="pkg-sourcetools">
<heading>Tools for processing source packages</heading>
all.</p></sect2>
</sect1>
+<!-- FIXME: section pkg-srcsubstvars is the same as srcsubstvars -->
+
<sect1 id="pkg-srcsubstvars"><heading><file>debian/substvars</file>
and variable substitutions
</heading>
</p>
<p>
- The is usually generated and modified dynamically by
- <file>debian/rules</file> targets; in this case it must be
+ This file is usually generated and modified dynamically by
+ <file>debian/rules</file> targets, in which case it must be
removed by the <tt>clean</tt> target.
</p>
It is important to note that there are several fields which
are optional as far as <prgn>dpkg</prgn> 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 <em>must</em> read
- the Debian policy manual in conjuction with the details
- below and the list of fields for the particular file.</p>
+ package, or whose omission may cause problems.
+ </p>
</sect>
<sect><heading>List of fields
<p>
These fields are not used by by <prgn>dpkg</prgn> proper,
but by <prgn>dselect</prgn> 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.
+ selects defaults.
</p>
<p>
- These fields may appear in binary package control files,
+ These fields can appear in binary package control files,
in which case they provide a default value in case the
<file>Packages</file> files are missing the information.
<prgn>dpkg</prgn> and <prgn>dselect</prgn> will only use
<p>
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 the part of the field
+ 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
</heading>
<p>
- The most recent version of the standards (the
- <prgn>dpkg</prgn> programmers' and policy manuals and
- associated texts) with which the package complies. This
+ The most recent version of the standards (the Debian Policy
+ and associated texts) with which the package complies. This
is updated manually when editing the source package to
conform to newer standards; it can sometimes be used to
tell when a package needs attention.
projects / debian / debian-policy.git / blobdiff