<p>
In general, Debian packages should use the same version
- numbers as the upstream sources.
- </p>
-
- <p>
- 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".
+ numbers as the upstream sources. However, upstream version
+ numbers based on some date formats (sometimes used for
+ development or "snapshot" releases) will not be ordered
+ correctly by the package management software. For
+ example, <prgn>dpkg</prgn> will consider "96May01" to be
+ greater than "96Dec24".
</p>
<p>
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.
+ version, the date-based portion of any upstream version number
+ should be given in a way that sorts correctly: four-digit year
+ first, followed by a two-digit numeric month, followed by a
+ two-digit numeric date, possibly with punctuation between the
+ components.
</p>
<p>
- Note that other version formats based on dates which are
- parsed correctly by the package management system should
- <em>not</em> be changed.
- </p>
-
- <p>
- Native Debian packages (i.e., packages which have been
- written especially for Debian) whose version numbers include
- dates should always use the "YYYYMMDD" format.
+ Native Debian packages (i.e., packages which have been written
+ especially for Debian) whose version numbers include dates
+ should also follow these rules. If punctuation is desired
+ between the date components, remember that hyphen (<tt>-</tt>)
+ cannot be used in native package versions. Period
+ (<tt>.</tt>) is normally a good choice.
</p>
</sect1>
<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>
<p>
There is no Build-Depends-Arch; this role is essentially
met with Build-Depends. Anyone building the
- <tt>build-indep</tt> and binary-indep<tt></tt> targets is
+ <tt>build-indep</tt> and <tt>binary-indep</tt> targets is
assumed to be building the whole package, and therefore
installation of all build dependencies is required.
</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>
- 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).
+ 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>
+ 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
</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
<p>
These two files are managed through the <prgn>dpkg</prgn>
- "alternatives" mechanism. Thus every package providing an
- editor or pager must call the
- <prgn>update-alternatives</prgn> script to register these
- programs.
+ "alternatives" mechanism. Every package providing an editor or
+ pager must call the <prgn>update-alternatives</prgn> script to
+ register as an alternative for <file>/usr/bin/editor</file>
+ or <file>/usr/bin/pager</file> as appropriate. The alternative
+ should have a slave alternative
+ for <file>/usr/share/man/man1/editor.1.gz</file>
+ or <file>/usr/share/man/man1/pager.1.gz</file> pointing to the
+ corresponding manual page.
</p>
<p>
<example compact="compact">
/usr/lib/cgi-bin/<var>cgi-bin-name</var>
</example>
- and should be referred to as
+ or a subdirectory of that directory, and should be
+ referred to as
<example compact="compact">
http://localhost/cgi-bin/<var>cgi-bin-name</var>
</example>
-
+ (possibly with a subdirectory name
+ before <var>cgi-bin-name</var>).
</item>
<item>
virtual package <tt>x-terminal-emulator</tt>. They should
also register themselves as an alternative for
<file>/usr/bin/x-terminal-emulator</file>, with a priority of
- 20.
+ 20. That alternative should have a slave alternative
+ for <file>/usr/share/man/man1/x-terminal-emulator.1.gz</file>
+ pointing to the corresponding manual page.
</p>
<p>
configuration, add 10 points; otherwise add none.
</item>
</list>
+ That alternative should have a slave alternative
+ for <file>/usr/share/man/man1/x-window-manager.1.gz</file>
+ pointing to the corresponding manual page.
</p>
</sect1>
projects / debian / debian-policy.git / blobdiff