]> git.donarmstrong.com Git - debian/debian-policy.git/blobdiff - policy.sgml
Mention optional special role for the first changelog line
[debian/debian-policy.git] / policy.sgml
index dc4553cfd04d0af89d238c44e93e950ae6c0f710..83d42a9f38b15210852ace0932ec427480d4dc3f 100644 (file)
 
          <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.
-         </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.
+           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>
-           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>
 
          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
+         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
@@ -2224,16 +2226,16 @@ endif
        <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>
@@ -5081,7 +5083,7 @@ Replaces: mail-transport-agent
            <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>
@@ -5130,55 +5132,134 @@ Replaces: mail-transport-agent
       </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>
@@ -5198,10 +5279,11 @@ Replaces: mail-transport-agent
       </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
@@ -5421,6 +5503,14 @@ Replaces: mail-transport-agent
        (<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">
@@ -7487,7 +7577,19 @@ fname () {
 </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
@@ -7928,11 +8030,13 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
        </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
@@ -7957,17 +8061,20 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
            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>
@@ -7979,7 +8086,7 @@ endscript
        </p>
       </sect>
 
-      <sect>
+      <sect id="permissions-owners">
        <heading>Permissions and owners</heading>
 
        <p>
@@ -8020,6 +8127,12 @@ endscript
           </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
@@ -8306,10 +8419,14 @@ done
 
        <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>
@@ -8358,11 +8475,13 @@ done
                <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>
@@ -8652,7 +8771,9 @@ name ["<var>syshostname</var>"]:
            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>
@@ -8729,6 +8850,9 @@ name ["<var>syshostname</var>"]:
                  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>