@@ -5792,361 +5793,789 @@ Replaces: mail-transport-agent
-
If a package contains a binary or library which links to a
- shared library, we must ensure that when the package is
- installed on the system, all of the libraries needed are
- also installed. This requirement led to the creation of the
- shlibs system, which is very simple in its design:
- any package which provides a shared library also
- provides information on the package dependencies required to
- ensure the presence of this library, and any package which
- uses a shared library uses this information to
- determine the dependencies it requires. The files which
- contain the mapping from shared libraries to the necessary
- dependency information are called
- When a package is built which contains any shared libraries, it
- must provide a
-
- We say that a binary foo directly uses
- a library libbar if it is explicitly linked
- with that library (that is, the library is listed in the ELF
- NEEDED attribute, caused by adding -lbar
- to the link line when the binary is created). Other
- libraries that are needed by libbar are linked
- indirectly to foo, and the dynamic
- linker will load them automatically when it loads
- libbar. A package should depend on the libraries
- it directly uses, but not the libraries it indirectly uses.
- The dependencies for those libraries will automatically pull
- in the other libraries.
-
+
+ When a package that contains any shared libraries or compiled
+ binaries is built, it must run
- A good example of where this helps is the following. We
- could update libimlib with a new version that
- supports a new graphics format called dgf (but retaining the
- same major version number) and depends on libdgf.
- If we used
+ We say that a binary foo directly uses a
+ library libbar if it is explicitly linked with that
+ library (that is, the library is listed in the
+ ELF NEEDED attribute, caused by adding -lbar
+ to the link line when the binary is created). Other libraries
+ that are needed by libbar are
+ linked indirectly to foo, and the dynamic
+ linker will load them automatically when it
+ loads libbar. A package should depend on the libraries
+ it directly uses, but not the libraries it indirectly uses. The
+ dependencies for those libraries will automatically pull in the
+ other libraries.
In the following sections, we will first describe where the
- various shlibs files are to be found, then how to
- use
- There are several places where shlibs files are
- found. The following list gives them in the order in which
- they are read by
-
+
-
+ During the package build, if the package itself contains
+ shared libraries with
- This lists overrides for this package. This file should
- normally not be used, but may be needed temporarily in
- unusual situations to work around bugs in other packages,
- or in unusual cases where the normally declared dependency
- information in the installed
+ These files must exist
+ before
+
- This lists global overrides. This list is normally
- empty. It is maintained by the local system
- administrator.
-
+ Per-system overrides of shared library dependencies.
+ These files normally do not exist. They are maintained
+ by the local system administrator and must not be
+ created by any Debian package.
+
- When packages are being built,
- any
+ The
+
+
-
+ Be aware that if a
- These are the
+ If your package contains any compiled binaries or shared
+ libraries, put a call to
+ This command puts the dependency information into
+ the
- This file lists any shared libraries whose packages
- have failed to provide correct
+ For more details on
- Put a call to
-
+ The following documents the format of the
- This command puts the dependency information into the
-
+ A
- If you have multiple binary packages, you will need to call
-
+
- If you are creating a udeb for use in the Debian Installer,
- you will need to specify that
+ To explain this format, we'll use the the zlib1g
+ package as an example, which (at the time of writing) installs
+ the shared library
- For more details on
+ library-soname must contain exactly the value of
+ the ELF SONAME attribute of the shared library. In
+ our example, this is libz.so.1.
+ main-dependency-template has the same syntax as a + dependency field in a binary package control file, except that + the string #MINVER# is replaced by a version + restriction like (>= version) or by + nothing if an unversioned dependency is deemed sufficient. + The version restriction will be based on which symbols from + the shared library are referenced and the version at which + they were introduced (see below). In nearly all + cases, main-dependency-template will + be package #MINVER#, + where package is the name of the binary package + containing the shared library. This adds a simple, + possibly-versioned dependency on the shared library package. + In some rare cases, such as when multiple packages provide the + same shared library ABI, the dependency template may need to + be more complex. +
-
- Each
+ In our example, the first line of
+ the zlib1g
+ Each public symbol exported by the shared library must have a + corresponding symbol line, indented by one + space. symbol is the exported symbol (which, for + C++, means the mangled symbol) followed by @ and the + symbol version, or the string Base if there is no + symbol version. minimal-version is the most recent + version of the shared library that changed the behavior of + that symbol, whether by adding it, changing its function + signature (the parameters, their types, or the return type), + or its behavior in a way that is visible to a + caller. id-of-dependency-template is an optional + field that references + an alternative-dependency-template; see below for a + full description. +
+ +
+ For example, libz.so.1 contains the
+ symbols compress
+ and compressBound. compress has no symbol
+ version and last changed its behavior in upstream
+ version 1:1.1.4. compressBound has the
+ symbol version ZLIB_1.2.0, was introduced in upstream
+ version 1:1.2.0, and has not changed its behavior.
+ Its
+ One or more alternative-dependency-template lines
+ may be provided. These are used in cases where some symbols
+ in the shared library should use one dependency template while
+ others should use a different template. The alternative
+ dependency templates are used only if a symbol line contains
+ the id-of-dependency-template field. The first
+ alternative dependency template is numbered 1, the second 2,
+ and so forth.
+ Finally, the entry for the library may contain one or more
+ metadata fields. Currently, the only
+ supported field-name
+ is Build-Depends-Package, whose value lists
+ the
+ Also see
+ If your package provides a shared library, you should arrange
+ to include a
+ Normally, this is done by creating a
+ Packages that provide
+ Special care should be taken in updating + the minimal-version field when the behavior of a + public symbol changes. This is easy to neglect, since there + is no automated method of determining such changes, but + failing to update minimal-version in this case may + result in binary packages with too-weak dependencies that will + fail at runtime, possibly in ways that can cause security + vulnerabilities. If the package maintainer believes that a + symbol behavior change may have occurred but isn't sure, it's + safer to update the minimal-version of all possibly + affected symbols to the current upstream version rather than + leave them unmodified. This may result in unnecessarily + strict dependencies, but it ensures that packages whose + dependencies are satisfied will work properly. +
+ +
+ A common example of when a change
+ to minimal-version is required is a function that
+ takes an enum or struct argument that controls what the
+ function does. For example:
+
+ The minimal-version field normally should not + contain the Debian revision of the package, since the library + behavior is normally fixed for a particular upstream version + and any Debian packaging of that upstream version will have + the same behavior. In the rare case that the library behavior + was changed in a particular Debian revision, + appending ~ to the end of + the minimal-version that includes the Debian + revision is recommended, since this allows backports of the + shared library package using the normal backport versioning + convention to satisfy the dependency. +
+
- We will explain this by reference to the example of the
- zlib1g package, which (at the time of writing)
- installs the shared library
- type is an optional element that indicates the type
- of package for which the line is valid. The only type currently
- in use is udeb. The colon and space after the type are
- required.
+
- library-name is the name of the shared library,
- in this case libz. (This must match the name part
- of the soname, see below.)
+ In the following sections, we will first describe where the
+ various
- soname-version is the version part of the soname of
- the library. The soname is the thing that must exactly match
- for the library to be recognized by the dynamic linker, and is
- usually of the form
- name.so.major-version, in our
- example, libz.so.1.
+ There are several places where shlibs files are
+ found. The following list gives them in the order in which
+ they are read by
+ This lists overrides for this package. This file should
+ normally not be used, but may be needed temporarily in
+ unusual situations to work around bugs in other
+ packages, or in unusual cases where the normally
+ declared dependency information in the
+ installed
+ This lists global overrides. This list is normally
+ empty. It is maintained by the local system
+ administrator.
+
+ These files are generated as part of the package build
+ process and staged for inclusion as control files in the
+ binary packages being built. They provide details of
+ any shared libraries included in the same package.
+
+ The
+ This file lists any shared libraries whose packages have
+ failed to provide correct
+ If a
+ Use of
+ If you are creating a udeb for use in the Debian Installer,
+ you will need to specify that
+ Each
+
+
- dependencies has the same syntax as a dependency - field in a binary package control file. It should give - details of which packages are required to satisfy a binary - built against the version of the library contained in the - package. See for details. -
+
+ We will explain this by reference to the example of the
+ zlib1g package, which (at the time of writing)
+ installs the shared
+ library
- In our example, if the first version of the zlib1g
- package which contained a minor number of at least
- 1.3 was 1:1.1.3-1, then the
- shlibs entry for this library could say:
-
+ type is an optional element that indicates the type + of package for which the line is valid. The only type + currently in use is udeb. The colon and space after + the type are required. +
-
- As zlib1g also provides a udeb containing the shared library,
- there would also be a second line:
-
+ library-name is the name of the shared library, in + this case libz. (This must match the name part of + the soname, see below.) +
-+ soname-version is the version part of the + ELF SONAME attribute of the library. + The SONAME is the thing that must exactly match for + the library to be recognized by the dynamic linker, and is + usually of the + form name.so.major-version, in + our example, libz.so.1. + The version part is the part which comes after + .so., so in our case, it is 1. The soname + may instead be of the + form name-major-version.so, + such as libdb-5.1.so, in which case the name would + be libdb and the version would be 5.1. +
-
- If your package provides a shared library, you need to create
- a
+ dependencies has the same syntax as a dependency + field in a binary package control file. It should give + details of which packages are required to satisfy a binary + built against the version of the library contained in the + package. See for details. +
-
- As
+ In our example, if the last change to the zlib1g
+ package that could change behavior for a client of that
+ library was in version 1:1.2.3.3.dfsg-1, then
+ the shlibs entry for this library could say:
+
+ As zlib1g also provides a udeb containing the shared library,
+ there would also be a second line:
+
+ To provide a
+ Since
+ The additional directory
The following directories in the root filesystem are @@ -6388,6 +6836,29 @@ rmdir /usr/local/share/emacs 2>/dev/null || true though the spool may still be physically located there.
+ +
+ The directory
+ Packages must not include files or directories
+ under
-
Packages must not modify the configuration file
- If a package wants to install a job that has to be executed
- via cron, it should place a file with the name of the
- package in one or more of the following directories:
+ If a package wants to install a job that has to be executed via
+ cron, it should place a file named as specified
+ in into one or more of the following
+ directories:
All files installed in any of these directories must be @@ -7171,15 +7644,18 @@ Reloading description configuration...done.
If a certain job has to be executed at some other frequency or
- at a specific time, the package should install a file
-
Unlike
+ The file name of a cron job file should normally match the + name of the package from which it comes. +
+ ++ If a package supplies multiple cron job files files in the + same directory, the file names should all start with the name + of the package (possibly modified as described below) followed + by a hyphen (-) and a suitable suffix. +
+ ++ A cron job file name must not include any period or plus + characters (. or +) characters as this will + cause cron to ignore the file. Underscores (_) + should be used instead of . and + + characters. +
+
- The MIME support policy can be found in the mime-policy
- files in the debian-policy package.
- It is also available from the Debian web mirrors at
-
+ Packages containing such programs must register them
+ with
- Packages which specify the same file as a
- conffile must be tagged as conflicting
- with each other. (This is an instance of the general rule
- about not sharing files. Note that neither alternatives
- nor diversions are likely to be appropriate in this case;
- in particular,
- The maintainer scripts must not alter a conffile - of any package, including the one the scripts - belong to. -
-If two or more packages use the same configuration file and it is reasonable for both to be installed at the same @@ -8251,6 +8750,34 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq and which manages the shared configuration files. (The sgml-base package is a good example.)
+ +
+ If the configuration file cannot be shared as described above,
+ the packages must be marked as conflicting with each other.
+ Two packages that specify the same file as
+ a conffile must conflict. This is an instance of the
+ general rule about not sharing files. Neither alternatives
+ nor diversions are likely to be appropriate in this case; in
+ particular,
+ When two packages both declare the same conffile, they + may see left-over configuration files from each other even + though they conflict with each other. If a user removes + (without purging) one of the packages and installs the other, + the new package will take over the conffile from the + old package. If the file was modified by the user, it will be + treated the same as any other locally + modified conffile during an upgrade. +
+ ++ The maintainer scripts must not alter a conffile + of any package, including the one the scripts + belong to. +
In addition, the copyright file must say where the upstream - sources (if any) were obtained. It should name the original - authors of the package and the Debian maintainer(s) who were - involved with its creation. + sources (if any) were obtained, and should name the original + authors.
@@ -10426,89 +10952,6 @@ END-INFO-DIR-ENTRY
- This program is usually called from
- Its arguments are executables and shared libraries
-
- 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.
-
- 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.) -
- -
-
- 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.
- 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
-