</sect>
- <sect>
+ <sect id="maintainer">
<heading>The maintainer of a package</heading>
<p>
- 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.
- </p>
-
- <p>
- The maintainer must be specified in the
- <tt>Maintainer</tt> 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
+ Every package must have a maintainer, except for orphaned
+ packages as described below. 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
+ maintaining the Debian packaging files, evaluating and
+ responding appropriately to reported bugs, uploading new
+ versions of the package (either directly or through a sponsor),
+ ensuring that the package is placed in the appropriate archive
+ area and included in Debian releases as appropriate for the
+ stability and utility of the package, and requesting removal of
+ the package from the Debian distribution if it is no longer
+ useful or maintainable.
+ </p>
+
+ <p>
+ The maintainer must be specified in the <tt>Maintainer</tt>
+ control field with their correct name and a working email
+ address. The email address given in the <tt>Maintainer</tt>
+ control field must accept mail from those role accounts in
+ Debian used to send automated mails regarding the package. This
+ includes non-spam mail from the bug-tracking system, all mail
+ from the Debian archive maintenance software, and other role
+ accounts or automated processes that are commonly agreed on by
+ the project.<footnote>
+ A sample implementation of such a whitelist written for the
+ Mailman mailing list management software is used for mailing
+ lists hosted by alioth.debian.org.
+ </footnote>
+ If one person or team maintains several packages, they should
+ use the same form of their name and email address in
the <tt>Maintainer</tt> fields of those packages.
</p>
</p>
<p>
- If the maintainer of a package quits from the Debian
- project, "Debian QA Group"
- <email>packages@qa.debian.org</email> takes over the
- maintainer-ship of the package until someone else
- volunteers for that task. These packages are called
- <em>orphaned packages</em>.<footnote>
- The detailed procedure for doing this gracefully can
- be found in the Debian Developer's Reference,
- see <ref id="related">.
+ If the maintainer of the package is a team of people with a
+ shared email address, the <tt>Uploaders</tt> control field must
+ be present and must contain at least one human with their
+ personal email address. See <ref id="f-Uploaders"> for the
+ syntax of that field.
+ </p>
+
+ <p>
+ An orphaned package is one with no current maintainer. Orphaned
+ packages should have their <tt>Maintainer</tt> control field set
+ to <tt>Debian QA Group <packages@qa.debian.org></tt>.
+ These packages are considered maintained by the Debian project
+ as a whole until someone else volunteers to take over
+ maintenance.<footnote>
+ The detailed procedure for gracefully orphaning a package can
+ be found in the Debian Developer's Reference
+ (see <ref id="related">).
</footnote>
</p>
</sect>
The maintainer name and email address used in the changelog
should be the details of the person uploading <em>this</em>
version. They are <em>not</em> necessarily those of the
- usual package maintainer. The information here will be
- copied to the <tt>Changed-By</tt> field in the
- <tt>.changes</tt> file (see <ref id="f-Changed-By">),
- and then later used to send an acknowledgement when the
- upload has been installed.
+ usual package maintainer.<footnote>
+ If the developer uploading the package is not one of the usual
+ maintainers of the package (as listed in
+ the <qref id="f-Maintainer"><tt>Maintainer</tt></qref>
+ or <qref id="f-Uploaders"><tt>Uploaders</tt></qref> control
+ fields of the package), the first line of the changelog is
+ conventionally used to explain why a non-maintainer is
+ uploading the package. The Debian Developer's Reference
+ (see <ref id="related">) documents the conventions
+ used.</footnote>
+ The information here will be copied to the <tt>Changed-By</tt>
+ field in the <tt>.changes</tt> file
+ (see <ref id="f-Changed-By">), and then later used to send an
+ acknowledgement when the upload has been installed.
</p>
<p>
<p>
The architectures we build on and build for are determined
- by <prgn>make</prgn> variables using the utility
- <qref id="pkg-dpkg-architecture"><prgn>dpkg-architecture</prgn></qref>.
- 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
- machine type we are building for). Here is a list of
- supported <prgn>make</prgn> variables:
+ by <prgn>make</prgn> variables using the
+ utility <qref id="pkg-dpkg-architecture"><prgn>dpkg-architecture</prgn></qref>.
+ You can determine the Debian architecture and the GNU style
+ architecture specification string for the build architecture as
+ well as for the host architecture. The build architecture is
+ the architecture on which <file>debian/rules</file> is run and
+ the package build is performed. The host architecture is the
+ architecture on which the resulting package will be installed
+ and run. These are normally the same, but may be different in
+ the case of cross-compilation (building packages for one
+ architecture on machines of a different architecture).
+ </p>
+
+ <p>
+ Here is a list of supported <prgn>make</prgn> variables:
<list compact="compact">
<item>
<tt>DEB_*_ARCH</tt> (the Debian architecture)
<tt>DEB_*_GNU_TYPE</tt>)
</list>
where <tt>*</tt> is either <tt>BUILD</tt> for specification of
- the build machine or <tt>HOST</tt> for specification of the
- host machine.
+ the build architecture or <tt>HOST</tt> for specification of the
+ host architecture.
</p>
<p>
<heading>Variable substitutions: <file>debian/substvars</file></heading>
<p>
- When <prgn>dpkg-gencontrol</prgn>,
- <prgn>dpkg-genchanges</prgn> and <prgn>dpkg-source</prgn>
- generate control files, they perform variable substitutions
- on their output just before writing it. Variable
+ When <prgn>dpkg-gencontrol</prgn>
+ generates <qref id="binarycontrolfiles">binary package control
+ files</qref> (<file>DEBIAN/control</file>), it performs variable
+ substitutions on its output just before writing it. Variable
substitutions have the form <tt>${<var>variable</var>}</tt>.
The optional file <file>debian/substvars</file> contains
variable substitutions to be used; variables can also be set
directly from <file>debian/rules</file> using the <tt>-V</tt>
- option to the source packaging commands, and certain
- predefined variables are also available.
+ option to the source packaging commands, and certain predefined
+ variables are also available.
</p>
<p>
putting the name in round brackets and moving it to the
end, and bringing the email address forward).
</p>
+
+ <p>
+ See <ref id="maintainer"> for additional requirements and
+ information about package maintainers.
+ </p>
</sect1>
<sect1 id="f-Uploaders">
<heading><tt>Uploaders</tt></heading>
<p>
- 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
- <qref id="f-Maintainer">Maintainer field</qref>, their names
- and email addresses should be listed here. The format of each
- entry is the same as that of the Maintainer field, and
- multiple entries must be comma separated. This is an optional
- field.
+ List of the names and email addresses of co-maintainers of the
+ package, if any. If the package has other maintainers besides
+ the one named in the <qref id="f-Maintainer">Maintainer
+ field</qref>, their names and email addresses should be listed
+ here. The format of each entry is the same as that of the
+ Maintainer field, and multiple entries must be comma
+ separated.
+ </p>
+
+ <p>
+ This is normally an optional field, but if
+ the <tt>Maintainer</tt> control field names a group of people
+ and a shared email address, the <tt>Uploaders</tt> field must
+ be present and must contain at least one human with their
+ personal email address.
</p>
<p>
</p>
<p>
- 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.
+ This section deals only with public shared libraries: shared
+ libraries that are placed in directories searched by the dynamic
+ linker by default or which are intended to be linked against
+ normally and possibly used by other, independent packages. Shared
+ libraries that are internal to a particular package or that are
+ only loaded as dynamic modules are not covered by this section and
+ are not subject to its requirements.
</p>
- <sect id="sharedlibs-runtime">
- <heading>Run-time shared libraries</heading>
+ <p>
+ A shared library is identified by the <tt>SONAME</tt> attribute
+ stored in its dynamic section. When a binary is linked against a
+ shared library, the <tt>SONAME</tt> of the shared library is
+ recorded in the binary's <tt>NEEDED</tt> section so that the
+ dynamic linker knows that library must be loaded at runtime. The
+ shared library file's full name (which usually contains additional
+ version information not needed in the <tt>SONAME</tt>) is
+ therefore normally not referenced directly. Instead, the shared
+ library is loaded by its <tt>SONAME</tt>, which exists on the file
+ system as a symlink pointing to the full name of the shared
+ library. This symlink must be provided by the
+ package. <ref id="sharedlibs-runtime"> describes how to do this.
+ <footnote>
+ This is a convention of shared library versioning, but not a
+ requirement. Some libraries use the <tt>SONAME</tt> as the full
+ library file name instead and therefore do not need a symlink.
+ Most, however, encode additional information about
+ backwards-compatible revisions as a minor version number in the
+ file name. The <tt>SONAME</tt> itself only changes when
+ binaries linked with the earlier version of the shared library
+ may no longer work, but the filename may change with each
+ release of the library. See <ref id="sharedlibs-runtime"> for
+ more information.
+ </footnote>
+ </p>
<p>
- The run-time shared library needs to be placed in a package
- whose name changes whenever the shared object version
- changes.<footnote>
- <p>
- Since it is common place to install several versions of a
- package that just provides shared libraries, it is a
- good idea that the library package should not
- contain any extraneous non-versioned files, unless they
- happen to be in versioned directories.</p>
- </footnote>
- The most common mechanism is to place it 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>
- 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>.
- </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.
+ When linking a binary or another shared library against a shared
+ library, the <tt>SONAME</tt> for that shared library is not yet
+ known. Instead, the shared library is found by looking for a file
+ matching the library name with <tt>.so</tt> appended. This file
+ exists on the file system as a symlink pointing to the shared
+ library.
+ </p>
+
+ <p>
+ Shared libraries are normally split into several binary packages.
+ The <tt>SONAME</tt> symlink is installed by the runtime shared
+ library package, and the bare <tt>.so</tt> symlink is installed in
+ the development package since it's only used when linking binaries
+ or shared libraries. However, there are some exceptions for
+ unusual shared libraries or for shared libraries that are also
+ loaded as dynamic modules by other programs.
</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).
+ This section is primarily concerned with how the separation of
+ shared libraries into multiple packages should be done and how
+ dependencies on and between shared library binary packages are
+ managed in Debian. <ref id="libraries"> should be read in
+ conjunction with this section and contains additional rules for
+ the files contained in the shared library packages.
</p>
+ <sect id="sharedlibs-runtime">
+ <heading>Run-time shared libraries</heading>
+
+ <p>
+ The run-time shared library must be placed in a package
+ whose name changes whenever the <tt>SONAME</tt> of the shared
+ library changes. This allows several versions of the shared
+ library to be installed at the same time, allowing installation
+ of the new version of the shared library without immediately
+ breaking binaries that depend on the old version. Normally, the
+ run-time shared library and its <tt>SONAME</tt> symlink should
+ be placed in a package named
+ <package><var>libraryname</var><var>soversion</var></package>,
+ where <var>soversion</var> is the version number in
+ the <tt>SONAME</tt> of the shared library.
+ See <ref id="shlibs"> for detailed information on how to
+ determine this version. Alternatively, if it would be confusing
+ to directly append <var>soversion</var>
+ to <var>libraryname</var> (if, for example, <var>libraryname</var>
+ itself ends in a number), you should use
+ <package><var>libraryname</var>-<var>soversion</var></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 all of their <tt>SONAME</tt>s will
+ always change together. Be aware that this is not normally the
+ case, and if the <tt>SONAME</tt>s do not change together,
+ upgrading such a merged shared library package will be
+ unnecessarily difficult because of file conflicts with the old
+ version of the package. When in doubt, always split shared
+ library packages so that each binary package installs a single
+ shared library.
+ </p>
+
+ <p>
+ Every time the shared library ABI changes in a way that may
+ break binaries linked against older versions of the shared
+ library, the <tt>SONAME</tt> of the library and the
+ corresponding name for the binary package containing the runtime
+ shared library should change. Normally, this means
+ the <tt>SONAME</tt> should change any time an interface is
+ removed from the shared library or the signature of an interface
+ (the number of parameters or the types of parameters that it
+ takes, for example) is changed. This practice is vital to
+ allowing clean upgrades from older versions of the package and
+ clean transitions between the old ABI and new ABI without having
+ to upgrade every affected package simultaneously.
+ </p>
+
+ <p>
+ The <tt>SONAME</tt> and binary package name need not, and indeed
+ normally should not, change if new interfaces are added but none
+ are removed or changed, since this will not break binaries
+ linked against the old shared library. Correct versioning of
+ dependencies on the newer shared library by binaries that use
+ the new interfaces is handled via
+ the <qref id="sharedlibs-shlibdeps"><tt>shlibs</tt>
+ system</qref> or via symbols files (see
+ <manref name="deb-symbols" section="5">).
+ </p>
+
<p>
The package should install the shared libraries under
their normal names. For example, the <package>libgdbm3</package>
</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 <package>libgdbm3</package> package should include
- a symbolic link from <file>/usr/lib/libgdbm.so.3</file> to
+ The run-time library package should include the symbolic link for
+ the <tt>SONAME</tt> that <prgn>ldconfig</prgn> would create for
+ the shared libraries. For example,
+ the <package>libgdbm3</package> package should include a symbolic
+ link from <file>/usr/lib/libgdbm.so.3</file> to
<file>libgdbm.so.3.0.0</file>. This is needed so that the dynamic
linker (for example <prgn>ld.so</prgn> or
<prgn>ld-linux.so.*</prgn>) can find the library between the
(<prgn>ld</prgn>) when compiling packages, as it will only look for
<file>libgdbm.so</file> when compiling dynamically.
</p>
+
+ <p>
+ If the package provides Ada Library Information
+ (<file>*.ali</file>) files for use with GNAT, these files must be
+ installed read-only (mode 0444) so that GNAT will not attempt to
+ recompile them. This overrides the normal file mode requirements
+ given in <ref id="permissions-owners">.
+ </p>
</sect>
<sect id="sharedlibs-intradeps">
</example>
must be supported and must set the value of <tt>c</tt> to
<tt>delta</tt>.
- </item>
+ </item>
+ <item>The XSI extension to <prgn>kill</prgn> allowing <tt>kill
+ -<var>signal</var></tt>, where <var>signal</var> is either
+ the name of a signal or one of the numeric signals listed in
+ the XSI extension (0, 1, 2, 3, 6, 9, 14, and 15), must be
+ supported if <prgn>kill</prgn> is implemented as a shell
+ built-in.
+ </item>
+ <item>The XSI extension to <prgn>trap</prgn> allowing numeric
+ signals must be supported. In addition to the signal
+ numbers listed in the extension, which are the same as for
+ <prgn>kill</prgn> above, 13 (SIGPIPE) must be allowed.
+ </item>
</list>
If a shell script requires non-SUSv3 features from the shell
interpreter other than those listed above, the appropriate shell
</p>
<p>
- Log files must be rotated occasionally so that they don't
- grow indefinitely; the best way to do this is to drop a log
- rotation configuration file into the directory
- <file>/etc/logrotate.d</file> and use the facilities provided by
- logrotate.<footnote>
+ Log files must be rotated occasionally so that they don't grow
+ indefinitely. The best way to do this is to install a log
+ rotation configuration file in the
+ directory <file>/etc/logrotate.d</file>, normally
+ named <file>/etc/logrotate.d/<var>package</var></file>, and use
+ the facilities provided by <prgn>logrotate</prgn>.
+ <footnote>
<p>
The traditional approach to log files has been to set up
<em>ad hoc</em> log rotation schemes using simple shell
section="8">):
<example compact="compact">
/var/log/foo/*.log {
-rotate 12
-weekly
-compress
-postrotate
-/etc/init.d/foo force-reload
-endscript
+ rotate 12
+ weekly
+ compress
+ missingok
+ postrotate
+ start-stop-daemon -K -p /var/run/foo.pid -s HUP -x /usr/sbin/foo -q
+ endscript
}
</example>
This rotates all files under <file>/var/log/foo</file>, saves 12
- compressed generations, and forces the daemon to reload its
- configuration information after the log rotation.
+ compressed generations, and tells the daemon to reopen its log
+ files after the log rotation. It skips this log rotation
+ (via <tt>missingok</tt>) if no such log file is present, which
+ avoids errors if the package is removed but not purged.
</p>
<p>
</p>
</sect>
- <sect>
+ <sect id="permissions-owners">
<heading>Permissions and owners</heading>
<p>
</footnote>
</p>
+ <p>
+ Control information files should be owned by <tt>root:root</tt>
+ and either mode 644 (for most files) or mode 755 (for
+ executables such as <qref id="maintscripts">maintainer
+ scripts</qref>).
+ </p>
<p>
Setuid and setgid executables should be mode 4755 or 2755
projects / debian / debian-policy.git / blobdiff