Merge branch 'master' into bug530687-rra

diff --git a/policy.sgml b/policy.sgml
index 91ae7b08a3ce85334f845a6ca9250ab3d7f65281..ba901bc092dc60d882d16f6fef6e9323dc0ca4d3 100644 (file)
--- a/policy.sgml
+++ b/policy.sgml
@@ -2735,27 +2735,52 @@ Package: libc6
            <tt>Architecture</tt> field can include the following sets of
            values:
            <list>
-               <item>A unique single word identifying a Debian machine
-                     architecture as described in <ref id="arch-spec">.
-               <item><tt>all</tt>, which indicates an
-                     architecture-independent package.
-               <item><tt>any</tt>, which indicates a package available
-                     for building on any architecture.
-               <item><tt>source</tt>, which indicates a source package.
+               <item>
+                 A unique single word identifying a Debian machine
+                 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>
+               <item>
+                 <tt>source</tt>, which indicates a source package.
+               </item>
            </list>
          </p>
 
          <p>
            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.
+           package, this field may contain the special value <tt>all</tt>
+           or a list of specific and wildcard architectures separated by
+           spaces.  If <tt>all</tt> appears, that value 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>
+           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>
+             Use of architecture wildcards other than <tt>all</tt> is for
+             a minority of cases where the program is not portable and
+             should not be used for most packages.  Wildcards are not
+             expanded into a list of known architectures before comparing
+             to the build architecutre.  Instead, the build architecture
+             is matched against any wildcards and this package is built
+             if any wildcard matches.
+           </footnote>
          </p>
 
          <p>
@@ -2789,23 +2814,24 @@ Package: libc6
          </p>
 
          <p>
-           Specifying a list of architectures indicates that the source
-           will build an architecture-dependent package, and will only
-           work correctly on the listed architectures.  If the source
-           package also builds at least one architecture-independent
-           package, <tt>all</tt> will also be included in the list.
+           Specifying a list of architectures or architecture wildcards
+           indicates that the source will build an architecture-dependent
+           package, and will only work correctly on the listed or
+           matching architectures.  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)
-           currently being uploaded.  This will be a list; if the
-           source for the package is also being uploaded, the special
+           field lists the architecture(s) of the package(s) currently
+           being uploaded.  This will be a list; if the source for the
+           package is also being uploaded, the special
            entry <tt>source</tt> is also present.  <tt>all</tt> will be
            present if any architecture-independent packages are being
-           uploaded.  <tt>any</tt> may never occur in the
-           <tt>Architecture</tt> field in the <file>.changes</file>
-           file.
+           uploaded.  Architecture wildcards such as <tt>any</tt> may
+           never occur in the <tt>Architecture</tt> field in
+           the <file>.changes</file> file.
          </p>
 
          <p>
@@ -4259,6 +4285,21 @@ Build-Depends: foo [!i386] | bar [!amd64]
          bar</tt> on all other architectures.
        </p>
 
+        <p>
+         All fields that specify build-time relationships 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 any architecture
+         using a kernel other than Linux.
+        </p>
+
        <p>
          Note that the binary package relationship fields such as
          <tt>Depends</tt> appear in one of the binary package
@@ -7956,6 +7997,30 @@ done
        </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>any</tt> (which matches every
+         architecture), <tt><var>os</var></tt>-any, or
+         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), with the first component of the
+           triplet representing the libc and ABI in use.  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>