From: Russ Allbery <rra@debian.org>
Date: Mon, 31 May 2010 16:34:44 +0000 (-0700)
Subject: Merge branch 'master' into bug530687-rra
X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=baea58c43486488c3c9bd0b4e52957ce88ddd94c;hp=-c;p=debian%2Fdebian-policy.git

Merge branch 'master' into bug530687-rra
---

baea58c43486488c3c9bd0b4e52957ce88ddd94c
diff --combined policy.sgml
index 45d6643,ab8fedf..1de2494
--- a/policy.sgml
+++ b/policy.sgml
@@@ -90,11 -90,10 +90,10 @@@
  		    is used by, a significant number of packages, and
  		    therefore should not be changed without peer
  		    review. Package maintainers can then rely on this
- 		    interfaces not changing, and the package
- 		    management software authors need to ensure
- 		    compatibility with these interface
- 		    definitions. (Control file and changelog file
- 		    formats are examples.)
+ 		    interface not changing, and the package management
+ 		    software authors need to ensure compatibility with
+ 		    this interface definition. (Control file and
+ 		    changelog file formats are examples.)
  		</item>
  		<tag>Chosen Convention</tag>
  		<item>
@@@ -366,7 -365,7 +365,7 @@@
  	  The Debian Free Software Guidelines (DFSG) form our
  	  definition of "free software".  These are:
  	    <taglist>
- 	      <tag>Free Redistribution
+ 	      <tag>1. Free Redistribution
  	      </tag>
  	      <item>
  		  The license of a Debian component may not restrict any
@@@ -376,20 -375,20 +375,20 @@@
  		  sources. The license may not require a royalty or
  		  other fee for such sale.
  	      </item>
- 	      <tag>Source Code
+ 	      <tag>2. Source Code
  	      </tag>
  	      <item>
  		  The program must include source code, and must allow
  		  distribution in source code as well as compiled form.
  	      </item>
- 	      <tag>Derived Works
+ 	      <tag>3. Derived Works
  	      </tag>
  	      <item>
  		  The license must allow modifications and derived
  		  works, and must allow them to be distributed under the
  		  same terms as the license of the original software.
  	      </item>
- 	      <tag>Integrity of The Author's Source Code
+ 	      <tag>4. Integrity of The Author's Source Code
  	      </tag>
  	      <item>
  		  The license may restrict source-code from being
@@@ -404,13 -403,13 +403,13 @@@
  		  Project encourages all authors to not restrict any
  		  files, source or binary, from being modified.)
  	      </item>
- 	      <tag>No Discrimination Against Persons or Groups
+ 	      <tag>5. No Discrimination Against Persons or Groups
  	      </tag>
  	      <item>
  		  The license must not discriminate against any person
  		  or group of persons.
  	      </item>
- 	      <tag>No Discrimination Against Fields of Endeavor
+ 	      <tag>6. No Discrimination Against Fields of Endeavor
  	      </tag>
  	      <item>
  		  The license must not restrict anyone from making use
@@@ -419,7 -418,7 +418,7 @@@
  		  used in a business, or from being used for genetic
  		  research.
  	      </item>
- 	      <tag>Distribution of License
+ 	      <tag>7. Distribution of License
  	      </tag>
  	      <item>
  		  The rights attached to the program must apply to all
@@@ -427,7 -426,7 +426,7 @@@
  		  for execution of an additional license by those
  		  parties.
  	      </item>
- 	      <tag>License Must Not Be Specific to Debian
+ 	      <tag>8. License Must Not Be Specific to Debian
  	      </tag>
  	      <item>
  		  The rights attached to the program must not depend on
@@@ -439,7 -438,7 +438,7 @@@
  		  rights as those that are granted in conjunction with
  		  the Debian system.
  	      </item>
- 	      <tag>License Must Not Contaminate Other Software
+ 	      <tag>9. License Must Not Contaminate Other Software
  	      </tag>
  	      <item>
  		  The license must not place restrictions on other
@@@ -448,7 -447,7 +447,7 @@@
  		  that all other programs distributed on the same medium
  		  must be free software.
  	      </item>
- 	      <tag>Example Licenses
+ 	      <tag>10. Example Licenses
  	      </tag>
  	      <item>
                    The "GPL," "BSD," and "Artistic" licenses are examples of
@@@ -1726,14 -1725,17 +1725,17 @@@
  	<p>
  	  It must start with the line <tt>#!/usr/bin/make -f</tt>,
  	  so that it can be invoked by saying its name rather than
- 	  invoking <prgn>make</prgn> explicitly.
+ 	  invoking <prgn>make</prgn> explicitly. That is, invoking
+           either of <tt>make -f debian/rules <em>args...</em></tt>
+           or <tt>./debian/rules <em>args...</em></tt> must result in
+           identical behavior.
  	</p>
  
  	<p>
  	  Since an interactive <file>debian/rules</file> script makes it
  	  impossible to auto-compile that package and also makes it
  	  hard for other people to reproduce the same binary
- 	  package, all <em>required targets</em> MUST be
+ 	  package, all <em>required targets</em> must be
  	  non-interactive. At a minimum, required targets are the
  	  ones called by <prgn>dpkg-buildpackage</prgn>, namely,
  	  <em>clean</em>, <em>binary</em>, <em>binary-arch</em>,
@@@ -2690,7 -2692,7 +2692,7 @@@ Package: libc
  	  <heading><tt>Priority</tt></heading>
  
  	  <p>
- 	    This field represents how important that it is that the user
+ 	    This field represents how important it is that the user
  	    have the package installed. See <ref id="priorities">.
  	  </p>
  
@@@ -2726,12 -2728,7 +2728,12 @@@
  	    values:
  	    <list>
  		<item>A unique single word identifying a Debian machine
 -		      architecture as described in <ref id="arch-spec">.
 +                architecture as described in <ref id="arch-spec">.
 +                </item>
 +                <item>
 +                  An architecture wildcard identifying a set of Debian
 +                  machine architectures, see <ref id="arch-wildcard-spec">.
 +                </item>
  		<item><tt>all</tt>, which indicates an
  		      architecture-independent package.
  		<item><tt>any</tt>, which indicates a package available
@@@ -2744,14 -2741,13 +2746,14 @@@
  	    In the main <file>debian/control</file> file in the source
  	    package, this field may contain the special value
  	    <tt>any</tt>, the special value <tt>all</tt>, or a list of
 -	    architectures separated by spaces.	If <tt>any</tt> or
 -	    <tt>all</tt> appear, they must be the entire contents of the
 -	    field.  Most packages will use either <tt>any</tt> or
 -	    <tt>all</tt>.  Specifying a specific list of architectures is
 -	    for the minority of cases where a program is not portable or
 -	    is not useful on some architectures, and where possible the
 -	    program should be made portable instead.
 +	    specific and wildcard architectures separated by
 +	    spaces. If the special value <tt>any</tt> appears, it must
 +	    be the entire contents of the field.  Most packages will
 +	    use either <tt>any</tt> or <tt>all</tt>.  Specifying a
 +	    specific list of architectures is for the minority of
 +	    cases where a program is not portable or is not useful on
 +	    some architectures, and where possible the program should
 +	    be made portable instead.
  	  </p>
  
  	  <p>
@@@ -2792,24 -2788,6 +2794,24 @@@
  	    package, <tt>all</tt> will also be included in the list.
  	  </p>
  
 + 	  <p>
 +	    Specifying a list of architecture wildcards indicates that
 +            the source will build an architecture-dependent package on
 +            the union of the lists of architectures from the expansion
 +            of each specified architecture wildcard, and will only
 +            work correctly on the architectures in the union of the
 +            lists.<footnote> As mentioned in the footnote for
 +            specifying a list of architectures, this is for a minority
 +            of cases where the program is not portable. Generally, it
 +            should not be used for new packages.  Wildcards are not
 +            expanded into a list of known architectures before
 +            comparing to the build architecutre.  Instead, the build
 +            architecture is matched against wildcards and this package
 +            is built if the wildcard matches.</footnote> If the source
 +            package also builds at least one architecture-independent
 +            package, <tt>all</tt> will also be included in the list.
 +	  </p>
 +
  	  <p>
  	    In a <file>.changes</file> file, the <tt>Architecture</tt>
  	    field lists the architecture(s) of the package(s)
@@@ -2823,8 -2801,8 +2825,8 @@@
  	  </p>
  
  	  <p>
- 	    See <ref id="debianrules"> for information how to get the
- 	    architecture for the build process.
+ 	    See <ref id="debianrules"> for information on how to get
+ 	    the architecture for the build process.
  	  </p>
  	</sect1>
  
@@@ -2885,8 -2863,8 +2887,8 @@@
  	  <p>
  	    Thus only the first three components of the policy version
  	    are significant in the <em>Standards-Version</em> control
- 	    field, and so either these three components or the all
- 	    four components may be specified.<footnote>
+ 	    field, and so either these three components or all four
+ 	    components may be specified.<footnote>
  	  	In the past, people specified the full version number
  	  	in the Standards-Version field, for example "2.3.0.0".
  	  	Since minor patch-level changes don't introduce new
@@@ -3278,7 -3256,7 +3280,7 @@@
  	    for the most recent version should be returned first, and
  	    entries should be separated by the representation of a
  	    blank line (the "title" line may also be followed by the
- 	    representation of blank line).
+ 	    representation of a blank line).
  	  </p>
  	</sect1>
  
@@@ -3394,7 -3372,7 +3396,7 @@@ Files
  	    no new original source archive is being distributed the
  	    <tt>.dsc</tt> must still contain the <tt>Files</tt> field
  	    entry for the original source archive
- 	    <file><var>package</var>-<var>upstream-version</var>.orig.tar.gz</file>,
+ 	    <file><var>package</var>_<var>upstream-version</var>.orig.tar.gz</file>,
  	    but the <file>.changes</file> file should leave it out.  In
  	    this case the original source archive on the distribution
  	    site must match exactly, byte-for-byte, the original
@@@ -3737,7 -3715,7 +3739,7 @@@
  		      </example>
                        If this works, then the old-version is
                        "Installed", if not, the old version is in a
-                       "Failed-Config" state.
+                       "Half-Configured" state.
  		  </item>
  		</enumlist>
  	    </item>
@@@ -3845,7 -3823,7 +3847,7 @@@
                        If this fails, the package is left in a
                        "Half-Installed" state, which requires a
                        reinstall. If it works, the packages is left in
-                       a "Config Files" state.
+                       a "Config-Files" state.
  		  </item>
  		  <item>
  		      Otherwise (i.e., the package was completely purged):
@@@ -3857,7 -3835,7 +3859,7 @@@
  <var>new-postrm</var> abort-install
                        </example>
                        If the error-unwind fails, the package is in a
-                       "Half Installed" phase, and requires a
+                       "Half-Installed" phase, and requires a
                        reinstall. If the error unwind works, the
                        package is in a not installed state.
  		  </item>
@@@ -3937,14 -3915,14 +3939,14 @@@
  		      <example compact="compact">
  <var>old-preinst</var> abort-upgrade <var>new-version</var>
  		      </example>
-                       If this fails, the old version is left in an
-                       "Half Installed" state. If it works, dpkg now
+                       If this fails, the old version is left in a
+                       "Half-Installed" state. If it works, dpkg now
                        calls:
  		      <example compact="compact">
  <var>new-postrm</var> abort-upgrade <var>old-version</var>
  		      </example>
-                       If this fails, the old version is left in an
-                       "Half Installed" state. If it works, dpkg now
+                       If this fails, the old version is left in a
+                       "Half-Installed" state. If it works, dpkg now
                        calls:
  		      <example compact="compact">
  <var>old-postinst</var> abort-upgrade <var>new-version</var>
@@@ -4103,7 -4081,7 +4105,7 @@@
                  </example>
                </p>
                <p>
-                 If this fails, the package is in a "Failed-Config"
+                 If this fails, the package is in a "Half-Configured"
                  state, or else it remains "Installed".
                </p>
  	    </item>
@@@ -4281,23 -4259,6 +4283,23 @@@ Build-Depends: foo [!i386] | bar [!amd6
  	  source package section of the control file (which is the
  	  first section).
  	</p>
 +        <p>
 +          All fields that specify build-time relationships
 +          (<tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
 +          <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>) may also
 +          be restricted to a certain set of architectures using architecture
 +          wildcards. The syntax for declaring such restrictions is the same as
 +          declaring restrictions using a certain set of architectures without
 +          architecture wildcards.
 +          For example:
 +          <example compact="compact">
 +Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]
 +          </example>
 +          is equivalent to <tt>foo</tt> on architectures using the
 +          Linux kernel and any cpu, <tt>bar</tt> on architectures
 +          using any kernel and an i386 cpu, and <tt>baz</tt> on
 +          on any architecture using a kernel other than Linux.
 +        </p>
        </sect>
  
        <sect id="binarydeps">
@@@ -4456,12 -4417,12 +4458,12 @@@
  		be <em>unpacked</em> the pre-dependency can be
  		satisfied if the depended-on package is either fully
  		configured, <em>or even if</em> the depended-on
- 		package(s) are only unpacked or half-configured,
- 		provided that they have been configured correctly at
- 		some point in the past (and not removed or partially
- 		removed since).  In this case, both the
+ 		package(s) are only unpacked or in the "Half-Configured"
+ 		state, provided that they have been configured
+ 		correctly at some point in the past (and not removed
+ 		or partially removed since).  In this case, both the
  		previously-configured and currently unpacked or
- 		half-configured versions must satisfy any version
+ 		"Half-Configured" versions must satisfy any version
  		clause in the <tt>Pre-Depends</tt> field.
  	      </p>
  
@@@ -4518,7 -4479,7 +4520,7 @@@
  	<p>
  	  A package will not be regarded as causing breakage merely
  	  because its configuration files are still installed; it must
- 	  be at least half-installed.
+ 	  be at least "Half-Installed".
  	</p>
  
  	<p>
@@@ -4572,7 -4533,7 +4574,7 @@@
  	<p>
  	  A package will not cause a conflict merely because its
  	  configuration files are still installed; it must be at least
- 	  half-installed.
+ 	  "Half-Installed".
  	</p>
  
  	<p>
@@@ -5378,10 -5339,10 +5380,10 @@@ dpkg-shlibdeps debian/tmp/usr/bin/* deb
  	</p>
  
  	<p>
- 	  If you are creating a udeb for use in the Debian Installer, you
- 	  will need to specify that <prgn>dpkg-shlibdeps</prgn> should use
- 	  the dependency line of type <tt>udeb</tt> by adding
- 	  <tt>-tudeb</tt> as option<footnote>
+ 	  If you are creating a udeb for use in the Debian Installer,
+ 	  you will need to specify that <prgn>dpkg-shlibdeps</prgn>
+ 	  should use the dependency line of type <tt>udeb</tt> by
+ 	  adding the <tt>-tudeb</tt> option<footnote>
  	      <prgn>dh_shlibdeps</prgn> from the <tt>debhelper</tt> suite
  	      will automatically add this option if it knows it is
  	      processing a udeb.
@@@ -5680,6 -5641,15 +5682,15 @@@ libbar 1 bar1 (>= 1.0-1
                    symlinked there, is relaxed to a recommendation.
                  </p>
                </item>
+               <item>
+                 <p>
+                   The following directories in the root filesystem are
+                   additionally allowed: <file>/sys</file> and
+                   <file>/selinux</file>. <footnote>These directories
+                   are used as mount points to mount virtual filesystems
+                   to get access to kernel information.</footnote>
+                 </p>
+               </item>
              </enumlist>
  
            </p>
@@@ -5725,13 -5695,15 +5736,15 @@@
  	  </p>
  
  	  <p>
- 	    Note, that this applies only to directories <em>below</em>
- 	    <file>/usr/local</file>, not <em>in</em> <file>/usr/local</file>.
- 	    Packages must not create sub-directories in the directory
- 	    <file>/usr/local</file> itself, except those listed in FHS,
- 	    section 4.5.  However, you may create directories below
- 	    them as you wish. You must not remove any of the
- 	    directories listed in 4.5, even if you created them.
+ 	    Note that this applies only to
+ 	    directories <em>below</em> <file>/usr/local</file>,
+ 	    not <em>in</em> <file>/usr/local</file>.  Packages must
+ 	    not create sub-directories in the
+ 	    directory <file>/usr/local</file> itself, except those
+ 	    listed in FHS, section 4.5.  However, you may create
+ 	    directories below them as you wish. You must not remove
+ 	    any of the directories listed in 4.5, even if you created
+ 	    them.
  	  </p>
  
  	  <p>
@@@ -5792,9 -5764,10 +5805,10 @@@ rmdir /usr/local/share/emacs 2>/dev/nul
  	<sect1>
  	  <heading>The system-wide mail directory</heading>
  	  <p>
- 	    The system-wide mail directory is <file>/var/mail</file>. This
- 	    directory is part of the base system and should not owned
- 	    by any particular mail agents.  The use of the old
+ 	    The system-wide mail directory
+ 	    is <file>/var/mail</file>. This directory is part of the
+ 	    base system and should not be owned by any particular mail
+ 	    agents.  The use of the old
  	    location <file>/var/spool/mail</file> is deprecated, even
  	    though the spool may still be physically located there.
  	  </p>
@@@ -6579,13 -6552,48 +6593,48 @@@ Reloading <var>description</var> config
  	  <prgn>anacron</prgn>. Thus, you should only use this
  	  directory for jobs which may be skipped if the system is not
  	  running.)</p>
+ 	<p>
+           Unlike <file>crontab</file> files described in the IEEE Std
+           1003.1-2008 (POSIX.1) available from
+           <url id="http://www.opengroup.org/onlinepubs/9699919799/"
+                name="The Open Group">, the files in
+           <file>/etc/cron.d</file> and the file
+           <file>/etc/crontab</file> have seven fields; namely:
+           <enumlist>
+             <item>Minute [0,59]</item>
+             <item>Hour [0,23]</item>
+             <item>Day of the month [1,31]</item>
+             <item>Month of the year [1,12]</item>
+             <item>Day of the week ([0,6] with 0=Sunday)</item>
+             <item>Username</item>
+             <item>Command to be run</item>
+           </enumlist>
+           Ranges of numbers are allowed.  Ranges are two numbers
+           separated with a hyphen.  The specified range is inclusive.
+           Lists are allowed.  A list is a set of numbers (or ranges)
+           separated by commas. Step values can be used in conjunction
+           with ranges.
+         </p>
  
  	<p>
- 	  The scripts or crontab entries in these directories should
+ 	  The scripts or <tt>crontab</tt> entries in these directories should
  	  check if all necessary programs are installed before they
  	  try to execute them. Otherwise, problems will arise when a
  	  package was removed but not purged since configuration files
- 	  are kept on the system in this situation.</p>
+ 	  are kept on the system in this situation.
+         </p>
+ 
+         <p>
+           Any <tt>cron</tt> daemon must provide
+           <file>/usr/bin/crontab</file> and support normal
+           <tt>crontab</tt> entries as specified in POSIX. The daemon
+           must also support names for days and months, ranges, and
+           step values. It has to support <file>/etc/crontab</file>,
+           and correctly execute the scripts in
+           <file>/etc/cron.d</file>. The daemon must also correctly
+           execute scripts in
+           <file>/etc/cron.{hourly,daily,weekly,monthly}</file>.
+         </p>
        </sect>
  
        <sect id="menus">
@@@ -7295,8 -7303,8 +7344,8 @@@ ln -fs ../sbin/sendmail debian/tmp/usr/
  	<heading>Device files</heading>
  
  	<p>
- 	  Packages must not include device files in the package file
- 	  tree.
+ 	  Packages must not include device files or named pipes in the
+ 	  package file tree.
  	</p>
  
  	<p>
@@@ -7321,6 -7329,18 +7370,18 @@@
  	  <file>/dev/cu*</file> devices should be changed to use
  	  <file>/dev/ttyS*</file>.
  	</p>
+ 
+ 	<p>
+ 	  Named pipes needed by the package must be created in
+ 	  the <prgn>postinst</prgn> script<footnote>
+ 	    It's better to use <prgn>mkfifo</prgn> rather
+ 	    than <prgn>mknod</prgn> to create named pipes so that
+ 	    automated checks for packages incorrectly creating device
+ 	    files with <prgn>mknod</prgn> won't have false positives.
+ 	  </footnote> and removed in
+ 	  the <prgn>prerm</prgn> or <prgn>postrm</prgn> script as
+ 	  appropriate.
+ 	</p>
        </sect>
  
        <sect id="config-files">
@@@ -7936,27 -7956,6 +7997,27 @@@ don
  	</p>
        </sect>
  
 +      <sect id="arch-wildcard-spec">
 +        <heading>Architecture Wildcards</heading>
 +
 +        <p>
 +          A package may specify an architecture wildcard. Architecture
 +          wildcards are in the format <tt><var>os</var></tt>-any and
 +          any-<tt><var>cpu</var></tt>. <footnote>Internally, the package
 +          system normalizes the GNU triplets and the Debian
 +          arches into Debian arch triplets (which are kind of inverted GNU
 +          triplets). So when matching two Debian arch triplets, whenever an
 +          <var>any</var> is found it matches with anything on the other side,
 +          like in:
 +          <example>
 +  gnu-linux-i386     is matched by gnu-linux-any
 +  gnu-kfreebsd-amd64 is matched by any-any-amd64
 +          </example>
 +          And for example <var>any</var> is normalized to <var>any-any-any</var>.
 +        </footnote>
 +        </p>
 +      </sect>
 +
        <sect>
  	<heading>Daemons</heading>
  
@@@ -8669,9 -8668,9 +8730,9 @@@ name ["<var>syshostname</var>"]
  	  <p>
  	    Customization of programs' X resources may also be
  	    supported with the provision of a file with the same name
- 	    as that of the package placed in the
- 	    <file>/etc/X11/Xresources/</file> directory, which must
- 	    registered as a <tt>conffile</tt> or handled as a
+ 	    as that of the package placed in
+ 	    the <file>/etc/X11/Xresources/</file> directory, which
+ 	    must be registered as a <tt>conffile</tt> or handled as a
  	    configuration file.<footnote>
  		Note that this mechanism is not the same as using
  		app-defaults; app-defaults are tied to the client
@@@ -9055,7 -9054,7 +9116,7 @@@ END-INFO-DIR-ENTR
              <p>
                Please note that this does not override the section on
                changelog files below, so the file 
-               <file>/usr/share/<var>package</var>/changelog.Debian.gz</file>
+               <file>/usr/share/doc/<var>package</var>/changelog.Debian.gz</file>
                must refer to the changelog for the current version of
                <var>package</var> in question. In practice, this means
                that the sources of the target and the destination of the