Merge branch 'preferences_package_field' into 'main'

Improve documentation and tests for the Package pinning field

See merge request apt-team/apt!207

2 files changed, 80 insertions, 9 deletions

diff --git a/doc/apt_preferences.5.xml b/doc/apt_preferences.5.xml
index 8a517ee62..de8cb0664 100644
--- a/doc/apt_preferences.5.xml
+++ b/doc/apt_preferences.5.xml
@@ -282,11 +282,24 @@ condition is checked.
 
 </refsect2>
 
-<refsect2><title>Regular expressions and &glob; syntax</title>
+<refsect2><title>Matching packages in the Package field</title>
+
+<para>The <literal>Package</literal> field specifies the package that a pinning
+priority is applied to. The field can either contain a binary package name, a
+source package name (prefixed with "src:"), a &glob; expression or a regular
+expression (surrounded by slashes). Multiple package names, &glob; expressions
+and regular expressions can be listed separated by whitespace in which case
+the record will match any of the matched packages.</para>
+
+<para>By default, only packages of the native architecture are matched. To
+match binary packages of any architecture, add the <literal>:any</literal>
+suffix to the package name. You can also limit matching to a specific
+architecture by appending the architecture name to the package name,
+separated by a colon character.</para>
+
 <para>
-APT also supports pinning by &glob; expressions, and regular
-expressions surrounded by slashes. For example, the following
-example assigns the priority 500 to all packages from
+For example, the following example uses a glob expression and a regular
+expression to assign the priority 500 to all packages from
 experimental where the name starts with gnome (as a &glob;-like
 expression) or contains the word kde (as a POSIX extended regular
 expression surrounded by slashes).
@@ -320,12 +333,8 @@ pins first, so later specific pins override it.
 The pattern "<literal>*</literal>" in a Package field is not considered
 a &glob; expression in itself.
 </para>
-</refsect2>
 
-<refsect2><title>Pinning by source package</title>
-<para>APT supports pinning by source packages. To pin by a source package,
-prepend "src:" to the package name.</para>
-<para>For example, to pin all binaries produced by the apt source package
+<para>To pin all binaries produced by the apt source package
 of this APT's version to 990, you can do:</para>
 
 <programlisting>
@@ -343,6 +352,12 @@ Package: src:*apt*:any
 Pin: version *
 Pin-Priority: 990
 </programlisting>
+
+<para>The <literal>:any</literal> suffix makes sure to select binary packages
+from any architecture. Without that suffix, apt implicitly assumes the
+<literal>:native</literal> suffix which would only select packages from
+the native architecture.</para>
+
 </refsect2>
 
 
diff --git a/test/integration/test-policy-pinning b/test/integration/test-policy-pinning
index b871f724b..23e90bab6 100755
--- a/test/integration/test-policy-pinning
+++ b/test/integration/test-policy-pinning
@@ -144,6 +144,16 @@ Pin: release n=backports
 Pin-Priority: 600" > rootdir/etc/apt/preferences
 testequalpolicycoolstuff "" "2.0~bpo1" 600 500 600 "" -o Test=GlobalPin
 testequalpolicycoolstuff "" "1.0" 600 990 600 "" -o Test=GlobalPin -t stable
+echo "Package: cool*
+Pin: release n=backports
+Pin-Priority: 600" > rootdir/etc/apt/preferences
+testequalpolicycoolstuff "" "2.0~bpo1" 500 500 600 "" -o Test=GlobPin
+testequalpolicycoolstuff "" "1.0" 500 990 600 "" -o Test=GlobPin -t stable
+echo "Package: /cool.*/
+Pin: release n=backports
+Pin-Priority: 600" > rootdir/etc/apt/preferences
+testequalpolicycoolstuff "" "2.0~bpo1" 500 500 600 "" -o Test=RegexPin
+testequalpolicycoolstuff "" "1.0" 500 990 600 "" -o Test=RegexPin -t stable
 echo "Package: coolstuff
 Pin: release n=backports
 Pin-Priority: 200" > rootdir/etc/apt/preferences
@@ -238,6 +248,7 @@ testequalpolicycoolstuff "2.0~bpo1" "2.0~bpo1" 990 500 990 "" -o Test=ButAutomat
 
 rm incoming/backports.main.pkglist incoming/backports.main.srclist
 buildsimplenativepackage "coolstuff" "all" "2.0~bpo2" "backports"
+buildsimplenativepackage "hotstuff" "all" "1.0" "backports"
 setupaptarchive --no-update
 
 sed -i aptarchive/dists/backports/Release -e 1i"NotAutomatic: yes"
@@ -431,3 +442,48 @@ Pin-Priority: never
 testfailureequal "Reading package lists...
 E: ${tmppath}/rootdir/etc/apt/preferences: The special 'Pin-Priority: never' can only be used for 'Package: *' records" \
  aptget install -s coolstuff -o PinPriority=0
+
+# Test multiple packages
+echo "Package: coolstuff hotstuff
+Pin: release n=backports
+Pin-Priority: 600
+" > rootdir/etc/apt/preferences
+
+testsuccessequal "coolstuff:
+  Installed: 2.0~bpo1
+  Candidate: 2.0~bpo2
+  Version table:
+     2.0~bpo2 600
+        100 file:${tmppath}/aptarchive backports/main all Packages
+ *** 2.0~bpo1 100
+        100 ${tmppath}/rootdir/var/lib/dpkg/status
+     1.0 500
+        500 file:${tmppath}/aptarchive stable/main all Packages
+hotstuff:
+  Installed: (none)
+  Candidate: 1.0
+  Version table:
+     1.0 600
+        100 file:${tmppath}/aptarchive backports/main all Packages" aptcache policy coolstuff hotstuff
+
+echo "Package: c?ol*ff /hot[st]+uff/
+Pin: release n=backports
+Pin-Priority: 600
+" > rootdir/etc/apt/preferences
+
+testsuccessequal "coolstuff:
+  Installed: 2.0~bpo1
+  Candidate: 2.0~bpo2
+  Version table:
+     2.0~bpo2 600
+        100 file:${tmppath}/aptarchive backports/main all Packages
+ *** 2.0~bpo1 100
+        100 ${tmppath}/rootdir/var/lib/dpkg/status
+     1.0 500
+        500 file:${tmppath}/aptarchive stable/main all Packages
+hotstuff:
+  Installed: (none)
+  Candidate: 1.0
+  Version table:
+     1.0 600
+        100 file:${tmppath}/aptarchive backports/main all Packages" aptcache policy coolstuff hotstuff