]> git.donarmstrong.com Git - debian/debian-policy.git/blobdiff - policy.sgml
Changelog entry for the previous commit.
[debian/debian-policy.git] / policy.sgml
index 9479fc9d5ef3269fcdcbfdbae965a9d8b59217b8..50c0289fa7f2d682cbc40d7e5bb50c85a937323a 100644 (file)
          distributed in some other way or is intended for local use
          only.
        </p>
          distributed in some other way or is intended for local use
          only.
        </p>
+
+       <p>
+         udebs (stripped-down binary packages used by the Debian Installer) do
+         not comply with all of the requirements discussed here.  See the
+         <url name="Debian Installer internals manual"
+         id="http://d-i.alioth.debian.org/doc/internals/ch03.html"> for more
+         information about them.
+       </p>
       </sect>
 
       <sect>
       </sect>
 
       <sect>
@@ -1729,7 +1737,7 @@ zope.
 /closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i
              </example>
              Then all of the bug numbers listed will be closed by the
 /closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i
              </example>
              Then all of the bug numbers listed will be closed by the
-             archive maintenance script (<prgn>katie</prgn>) using the
+             archive maintenance software (<prgn>dak</prgn>) using the
              <var>version</var> of the changelog entry.
          </footnote>
          This information is conveyed via the <tt>Closes</tt> field
              <var>version</var> of the changelog entry.
          </footnote>
          This information is conveyed via the <tt>Closes</tt> field
@@ -2153,7 +2161,7 @@ zope.
        <p>
          The architectures we build on and build for are determined
          by <prgn>make</prgn> variables using the
        <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>.
+         utility <prgn>dpkg-architecture</prgn>.
          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
          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
@@ -2649,7 +2657,6 @@ Package: libc6
            <item><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</item>
            <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
            <item><qref id="f-Uploaders"><tt>Uploaders</tt></qref></item>
            <item><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</item>
            <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
            <item><qref id="f-Uploaders"><tt>Uploaders</tt></qref></item>
-           <item><qref id="f-DM-Upload-Allowed"><tt>DM-Upload-Allowed</tt></qref></item>
            <item><qref id="f-Section"><tt>Section</tt></qref> (recommended)</item>
            <item><qref id="f-Priority"><tt>Priority</tt></qref> (recommended)</item>
            <item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
            <item><qref id="f-Section"><tt>Section</tt></qref> (recommended)</item>
            <item><qref id="f-Priority"><tt>Priority</tt></qref> (recommended)</item>
            <item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
@@ -2672,6 +2679,7 @@ Package: libc6
            <item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
            <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
            <item><qref id="built-using"><tt>Built-Using</tt></qref></item>
            <item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
            <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
            <item><qref id="built-using"><tt>Built-Using</tt></qref></item>
+           <item><qref id="f-Package-Type"><tt>Package-Type</tt></qref></item>
          </list>
        </p>
 
          </list>
        </p>
 
@@ -2748,13 +2756,13 @@ Package: libc6
          <item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
          <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
          <item><qref id="f-Uploaders"><tt>Uploaders</tt></qref></item>
          <item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
          <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
          <item><qref id="f-Uploaders"><tt>Uploaders</tt></qref></item>
-         <item><qref id="f-DM-Upload-Allowed"><tt>DM-Upload-Allowed</tt></qref></item>
          <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
          <item><qref id="f-VCS-fields"><tt>Vcs-Browser</tt>, <tt>Vcs-Git</tt>, et al.</qref></item>
          <item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (recommended)</item>
          <item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
          <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
          <item><qref id="f-VCS-fields"><tt>Vcs-Browser</tt>, <tt>Vcs-Git</tt>, et al.</qref></item>
          <item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (recommended)</item>
          <item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
+         <item><qref id="f-Package-List"><tt>Package-List</tt></qref> (recommended)</item>
          <item><qref id="f-Checksums"><tt>Checksums-Sha1</tt>
          <item><qref id="f-Checksums"><tt>Checksums-Sha1</tt>
-             and <tt>Checksums-Sha256</tt></qref> (recommended)</item>
+             and <tt>Checksums-Sha256</tt></qref> (mandatory)</item>
          <item><qref id="f-Files"><tt>Files</tt></qref> (mandatory)</item>
        </list>
        </p>
          <item><qref id="f-Files"><tt>Files</tt></qref> (mandatory)</item>
        </list>
        </p>
@@ -2807,7 +2815,7 @@ Package: libc6
            <item><qref id="f-Closes"><tt>Closes</tt></qref></item>
            <item><qref id="f-Changes"><tt>Changes</tt></qref> (mandatory)</item>
            <item><qref id="f-Checksums"><tt>Checksums-Sha1</tt>
            <item><qref id="f-Closes"><tt>Closes</tt></qref></item>
            <item><qref id="f-Changes"><tt>Changes</tt></qref> (mandatory)</item>
            <item><qref id="f-Checksums"><tt>Checksums-Sha1</tt>
-               and <tt>Checksums-Sha256</tt></qref> (recommended)</item>
+               and <tt>Checksums-Sha256</tt></qref> (mandatory)</item>
            <item><qref id="f-Files"><tt>Files</tt></qref> (mandatory)</item>
          </list>
        </p>
            <item><qref id="f-Files"><tt>Files</tt></qref> (mandatory)</item>
          </list>
        </p>
@@ -3741,28 +3749,19 @@ Checksums-Sha256:
          </p>
 
          <p>
          </p>
 
          <p>
-           In the <file>.dsc</file> file, these fields should list all
+           In the <file>.dsc</file> file, these fields list all
            files that make up the source package.  In
            files that make up the source package.  In
-           the <file>.changes</file> file, these fields should list all
+           the <file>.changes</file> file, these fields list all
            files being uploaded.  The list of files in these fields
            must match the list of files in the <tt>Files</tt> field.
          </p>
        </sect1>
 
            files being uploaded.  The list of files in these fields
            must match the list of files in the <tt>Files</tt> field.
          </p>
        </sect1>
 
-       <sect1 id="f-DM-Upload-Allowed">
+       <sect1>
          <heading><tt>DM-Upload-Allowed</tt></heading>
 
          <p>
          <heading><tt>DM-Upload-Allowed</tt></heading>
 
          <p>
-           Indicates that Debian Maintainers may upload this package to
-           the Debian archive.  The only valid value is <tt>yes</tt>.  If
-           the field <tt>DM-Upload-Allowed: yes</tt> is present in the
-           source section of the source control file of the most recent
-           version of a package in unstable or experimental, the Debian
-           archive will accept uploads of this package signed with a key
-           in the Debian Maintainer keyring.  See the General
-           Resolution <url id="http://www.debian.org/vote/2007/vote_003"
-           name="Endorse the concept of Debian Maintainers"> for more
-           details.
+           Obsolete, see <qref id="f-DM-Upload-Allowed">below</qref>.
          </p>
        </sect1>
 
          </p>
        </sect1>
 
@@ -3812,6 +3811,34 @@ Checksums-Sha256:
            </taglist>
          </p>
        </sect1>
            </taglist>
          </p>
        </sect1>
+
+       <sect1 id="f-Package-List">
+         <heading><tt>Package-List</tt></heading>
+
+         <p>
+           Multiline field listing all the packages that can be built from
+           the source package, considering every architecture.  The first line
+           of the field value is empty.  Each one of the next lines describes
+           one binary package, by listing its name, type, section and priority
+           separated by spaces.  Fifth and subsequent space-separated items
+           may be present and parsers must allow them.  See the
+           <qref id="f-Package-Type">Package-Type</qref> field for a list of
+           package types.
+         </p>
+       </sect1>
+
+       <sect1 id="f-Package-Type">
+         <heading><tt>Package-Type</tt></heading>
+
+         <p>
+           Simple field containing a word indicating the type of package:
+           <tt>deb</tt> for binary packages and <tt>udeb</tt> for micro binary
+           packages.  Other types not defined here may be indicated.  In
+           source package control files, the <tt>Package-Type</tt> field
+           should be omitted instead of giving it a value of <tt>deb</tt>, as
+           this value is assumed for paragraphs lacking this field.
+         </p>
+       </sect1>
       </sect>
 
       <sect>
       </sect>
 
       <sect>
@@ -3858,6 +3885,28 @@ Checksums-Sha256:
 
       </sect>
 
 
       </sect>
 
+      <sect id="obsolete-control-data-fields">
+       <heading>Obsolete fields</heading>
+
+       <p>
+         The following fields have been obsoleted and may be found in packages
+         conforming with previous versions of the Policy.
+       </p>
+
+       <sect1 id="f-DM-Upload-Allowed">
+         <heading><tt>DM-Upload-Allowed</tt></heading>
+
+         <p>
+           Indicates that Debian Maintainers may upload this package to
+           the Debian archive.  The only valid value is <tt>yes</tt>.  This
+           field was used to regulate uploads by Debian Maintainers, See the
+           General Resolution <url id="http://www.debian.org/vote/2007/vote_003"
+           name="Endorse the concept of Debian Maintainers"> for more details.
+         </p>
+       </sect1>
+
+      </sect>
+
     </chapt>
 
 
     </chapt>
 
 
@@ -6623,7 +6672,7 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1)
          <heading>The <tt>shlibs</tt> system</heading>
 
          <p>
          <heading>The <tt>shlibs</tt> system</heading>
 
          <p>
-           The <tt>shlibs</tt> system is an simpler alternative to
+           The <tt>shlibs</tt> system is a simpler alternative to
            the <tt>symbols</tt> system for declaring dependencies for
            shared libraries.  It may be more appropriate for C++
            libraries and other cases where tracking individual symbols is
            the <tt>symbols</tt> system for declaring dependencies for
            shared libraries.  It may be more appropriate for C++
            libraries and other cases where tracking individual symbols is
@@ -6694,7 +6743,7 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1)
                    The <file>shlibs</file> control files for all the
                    packages currently installed on the system.  These are
                    normally found
                    The <file>shlibs</file> control files for all the
                    packages currently installed on the system.  These are
                    normally found
-                   in <file>/var/lib/dpkg/info/*.symbols</file>, but
+                   in <file>/var/lib/dpkg/info/*.shlibs</file>, but
                    packages should not rely on this and instead should
                    use <tt>dpkg-query --control-path <var>package</var>
                    shlibs</tt> if for some reason these files need to be
                    packages should not rely on this and instead should
                    use <tt>dpkg-query --control-path <var>package</var>
                    shlibs</tt> if for some reason these files need to be
@@ -8048,13 +8097,14 @@ Reloading <var>description</var> configuration...done.
        <p>
          The <package>mime-support</package> package provides the
          <prgn>update-mime</prgn> program, which integrates these
        <p>
          The <package>mime-support</package> package provides the
          <prgn>update-mime</prgn> program, which integrates these
-         registrations in the <file>/etc/mailcap</file> file, using Dpkg
+         registrations in the <file>/etc/mailcap</file> file, using dpkg
          triggers<footnote>
            Creating, modifying or removing a file in
            <file>/usr/lib/mime/packages/</file> using maintainer scripts will
            not activate the trigger.  In that case, it can be done by calling
          triggers<footnote>
            Creating, modifying or removing a file in
            <file>/usr/lib/mime/packages/</file> using maintainer scripts will
            not activate the trigger.  In that case, it can be done by calling
-           <tt>dpkg-trigger --no-await --by-package=&lt;me&gt; /usr/lib/mime/packages</tt>,
-           where <tt>&lt;me&gt;</tt> is the name of the package.
+           <tt>dpkg-trigger --no-await /usr/lib/mime/packages</tt> from
+           the maintainer script after creating, modifying, or removing
+           the file.
          </footnote>.
          Packages using this facility <em>should not</em> depend on,
          recommend, or suggest <prgn>mime-support</prgn>.
          </footnote>.
          Packages using this facility <em>should not</em> depend on,
          recommend, or suggest <prgn>mime-support</prgn>.
@@ -10825,12 +10875,6 @@ END-INFO-DIR-ENTRY
        <prgn>dpkg</prgn>, <prgn>dselect</prgn> et al. and the way
        they interact with packages.</p>
 
        <prgn>dpkg</prgn>, <prgn>dselect</prgn> et al. and the way
        they interact with packages.</p>
 
-      <p>
-       It also documents the interaction between
-       <prgn>dselect</prgn>'s core and the access method scripts it
-       uses to actually install the selected packages, and describes
-       how to create a new access method.</p>
-
       <p>
        This manual does not go into detail about the options and
        usage of the package building and installation tools.  It
       <p>
        This manual does not go into detail about the options and
        usage of the package building and installation tools.  It
@@ -10840,10 +10884,7 @@ END-INFO-DIR-ENTRY
 
       <p>
        The utility programs which are provided with <prgn>dpkg</prgn>
 
       <p>
        The utility programs which are provided with <prgn>dpkg</prgn>
-       for managing various system configuration and similar issues,
-       such as <prgn>update-rc.d</prgn> and
-       <prgn>install-info</prgn>, are not described in detail here -
-       please see their man pages.
+       not described in detail here, are documented in their man pages.
       </p>
 
       <p>
       </p>
 
       <p>
@@ -10863,25 +10904,9 @@ END-INFO-DIR-ENTRY
       <heading>Binary packages (from old Packaging Manual)</heading>
 
       <p>
       <heading>Binary packages (from old Packaging Manual)</heading>
 
       <p>
-       The binary package has two main sections.  The first part
-       consists of various control information files and scripts used
-       by <prgn>dpkg</prgn> when installing and removing.  See <ref
-       id="pkg-controlarea">.
-      </p>
-
-      <p>
-       The second part is an archive containing the files and
-       directories to be installed.
-      </p>
-
-      <p>
-       In the future binary packages may also contain other
-       components, such as checksums and digital signatures. The
-       format for the archive is described in full in the
-       <file>deb(5)</file> man page.
+       See <manref name="deb" section="5"> and <ref id="pkg-controlarea">.
       </p>
 
       </p>
 
-
       <sect id="pkg-bincreating"><heading>Creating package files -
       <prgn>dpkg-deb</prgn>
        </heading>
       <sect id="pkg-bincreating"><heading>Creating package files -
       <prgn>dpkg-deb</prgn>
        </heading>
@@ -11183,55 +11208,7 @@ END-INFO-DIR-ENTRY
          </heading>
 
          <p>
          </heading>
 
          <p>
-           <prgn>dpkg-buildpackage</prgn> is a script which invokes
-           <prgn>dpkg-source</prgn>, the <file>debian/rules</file>
-           targets <tt>clean</tt>, <tt>build</tt> and
-           <tt>binary</tt>, <prgn>dpkg-genchanges</prgn> and
-           <prgn>gpg</prgn> (or <prgn>pgp</prgn>) to build a signed
-           source and binary package upload.
-         </p>
-
-         <p>
-           It is usually invoked by hand from the top level of the
-           built or unbuilt source directory.  It may be invoked with
-           no arguments; useful arguments include:
-           <taglist compact="compact">
-             <tag><tt>-uc</tt>, <tt>-us</tt></tag>
-             <item>
-               <p>
-                 Do not sign the <tt>.changes</tt> file or the
-                 source package <tt>.dsc</tt> file, respectively.</p>
-             </item>
-             <tag><tt>-p<var>sign-command</var></tt></tag>
-             <item>
-               <p>
-                 Invoke <var>sign-command</var> instead of finding
-                 <tt>gpg</tt> or <tt>pgp</tt> on the <prgn>PATH</prgn>.
-                 <var>sign-command</var> must behave just like
-                 <prgn>gpg</prgn> or <tt>pgp</tt>.</p>
-             </item>
-             <tag><tt>-r<var>root-command</var></tt></tag>
-             <item>
-               <p>
-                 When root privilege is required, invoke the command
-                 <var>root-command</var>.  <var>root-command</var>
-                 should invoke its first argument as a command, from
-                 the <prgn>PATH</prgn> if necessary, and pass its
-                 second and subsequent arguments to the command it
-                 calls.  If no <var>root-command</var> is supplied
-                 then <var>dpkg-buildpackage</var> will use
-                 the <prgn>fakeroot</prgn> command, which is sufficient
-                 to build most packages without actually requiring root
-                 privileges.</p>
-             </item>
-             <tag><tt>-b</tt>, <tt>-B</tt></tag>
-             <item>
-               <p>
-                 Two types of binary-only build and upload - see
-                 <manref name="dpkg-source" section="1">.
-               </p>
-             </item>
-           </taglist>
+           See <manref name="dpkg-buildpackage" section="1">.
          </p>
        </sect1>
 
          </p>
        </sect1>
 
@@ -11355,23 +11332,10 @@ END-INFO-DIR-ENTRY
          </heading>
 
          <p>
          </heading>
 
          <p>
-           This program is usually called by package-independent
-           automatic building scripts such as
-           <prgn>dpkg-buildpackage</prgn>, but it may also be called
-           by hand.
-         </p>
-
-         <p>
-           It is usually called in the top level of a built source
-           tree, and when invoked with no arguments will print out a
-           straightforward <file>.changes</file> file based on the
-           information in the source package's changelog and control
-           file and the binary and source packages which should have
-           been built.
+           See <manref name="dpkg-genchanges" section="1">.
          </p>
        </sect1>
 
          </p>
        </sect1>
 
-
        <sect1 id="pkg-dpkg-parsechangelog">
           <heading>
             <prgn>dpkg-parsechangelog</prgn> - produces parsed
        <sect1 id="pkg-dpkg-parsechangelog">
           <heading>
             <prgn>dpkg-parsechangelog</prgn> - produces parsed
@@ -11379,12 +11343,7 @@ END-INFO-DIR-ENTRY
          </heading>
 
          <p>
          </heading>
 
          <p>
-           This program is used internally by
-           <prgn>dpkg-source</prgn> et al.  It may also occasionally
-           be useful in <file>debian/rules</file> and elsewhere.  It
-           parses a changelog, <file>debian/changelog</file> by default,
-           and prints a control-file format representation of the
-           information in it to standard output.
+           See <manref name="dpkg-parsechangelog" section="1">.
          </p>
        </sect1>
 
          </p>
        </sect1>
 
@@ -11395,10 +11354,7 @@ END-INFO-DIR-ENTRY
           </heading>
 
           <p>
           </heading>
 
           <p>
-            This program can be used manually, but is also invoked by
-            <tt>dpkg-buildpackage</tt> or <file>debian/rules</file> to set
-            environment or make variables which specify the build and host
-            architecture for the package building process.
+           See <manref name="dpkg-architecture" section="1">.
           </p>
         </sect1>
       </sect>
           </p>
         </sect1>
       </sect>