From: Arch Librarian Date: Mon, 20 Sep 2004 17:01:59 +0000 (+0000) Subject: - Updated apt_preferences(5) man page with many correct... X-Git-Tag: 0.7.24ubuntu1~727 X-Git-Url: https://git.saurik.com/apt.git/commitdiff_plain/5b9d504e6bec12446e7f7a7e2acf6fd1a7185a13?ds=inline - Updated apt_preferences(5) man page with many correct... Author: mdz Date: 2003-07-18 16:17:35 GMT - Updated apt_preferences(5) man page with many corrections and clarifications from Thomas Hood (Closes: #193336) --- diff --git a/debian/changelog b/debian/changelog index 05d5af03d..d00cefbd6 100644 --- a/debian/changelog +++ b/debian/changelog @@ -27,6 +27,9 @@ apt (0.5.6) unstable; urgency=low (Closes: #192933) - Fixes to pt_BR translation from Andre Luis Lopes (Closes: #196669) + - Updated apt_preferences(5) man page with many corrections and + clarifications from Thomas Hood + (Closes: #193336) -- diff --git a/doc/apt_preferences.5.sgml b/doc/apt_preferences.5.sgml index 2d9c9a052..7fa2afdf2 100644 --- a/doc/apt_preferences.5.sgml +++ b/doc/apt_preferences.5.sgml @@ -20,138 +20,138 @@ Preference control file for APT -Description</> +<RefSect1> +<Title>Description The APT preferences file /etc/apt/preferences -can be used to control which version of a package will be selected +can be used to control which versions of packages will be selected for installation. -Several versions of a package may be available for installation when + +Several versions of a package may be available for installation when the &sources-list; file contains references to more than one distribution -(for example, stable and testing); -furthermore, several instances of the same version of a package may be -available when the file contains references to more than one download site -for a particular distribution. APT assigns a "priority" to each instance -that is available. (In what follows, an "instance" will be an instance of -a package that is available according to &sources-list;.) -Subject to dependency constraints, apt-get installs the -instance with the highest priority. If two instances have the same -priority then it installs the more recent one, that is, the one with the -higher version number. - - -The APT preferences file overrides the priorities that APT assigns -to package instances by default, thus giving the user control over which +(for example, stable and testing). +APT assigns a priority to each version that is available. +Subject to dependency constraints, apt-get selects the +version with the highest priority for installation. +The APT preferences file overrides the priorities that APT assigns to +package versions by default, thus giving the user control over which one is selected for installation. + +Several instances of the same version of a package may be available when +the &sources-list; file contains references to more than one source. +In this case apt-get downloads the instance listed +earliest in the &sources-list; file. +The APT preferences file does not affect the choice of instance. + APT's Default Priority Assignments</> -<para>If there is no preferences file, or if there is no entry in the file -that applies to a particular instance, then the priority assigned to that -instance is the priority of the distribution to which that instance -belongs. It is possible to single out a distribution, called the -"target release", which receives a higher priority than other distributions. +<para> +If there is no preferences file or if there is no entry in the file +that applies to a particular version then the priority assigned to that +version is the priority of the distribution to which that version +belongs. It is possible to single out a distribution, "the target release", +which receives a higher priority than other distributions do by default. The target release can be set on the <command>apt-get</command> command line or in the APT configuration file <filename>/etc/apt/apt.conf</filename>. For example, - <programlisting> -# Command to install the <literal/testing/ version of <replaceable>some-package</replaceable> <command>apt-get install -t testing <replaceable>some-package</replaceable></command> </programlisting> - <programlisting> -# Configuration setting to make <literal/stable/ the target release APT::Default-Release "stable"; </programlisting> </para> -<para>If a target release has been specified then APT uses the following -algorithm to set the priorities of the instances of a package. Assign: - +<para> +If the target release has been specified then APT uses the following +algorithm to set the priorities of the versions of a package. Assign: <variablelist> <varlistentry> <term>priority 100</term> -<listitem><simpara>to the instance that is already installed (if any). -</simpara></listitem> +<listitem><simpara>to the version that is already installed (if any).</simpara></listitem> </varlistentry> <varlistentry> <term>priority 500</term> -<listitem><simpara>to the instances that are not installed -and do not belong to the target release. -</simpara></listitem> +<listitem><simpara>to the versions that are not installed and do not belong to the target release.</simpara></listitem> </varlistentry> <varlistentry> <term>priority 990</term> -<listitem><simpara>to the instances that are not installed -and belong to the target release. -</simpara></listitem> +<listitem><simpara>to the versions that are not installed and belong to the target release.</simpara></listitem> </varlistentry> </variablelist> </para> -<para>If no target release has been specified then APT simply assigns -priority 100 to all installed package instances and priority 500 to all -uninstalled package instances. +<para> +If the target release has not been specified then APT simply assigns +priority 100 to all installed package versions and priority 500 to all +uninstalled package versions. </para> -<para>APT then applies the following rules, listed in order of precedence, -to determine which instance of a package to install. - +<para> +APT then applies the following rules, listed in order of precedence, +to determine which version of a package to install. <itemizedlist> -<listitem><simpara>Never downgrade unless the priority of an available instance -exceeds 1000. ("Downgrading" is installing a less recent version of a package -in place of a more recent version. Note that none of APT's default priorities -exceeds 1000; such high priorities can only be set in the preferences file.) -</simpara></listitem> -<listitem><simpara>Install the highest priority instance. -</simpara></listitem> -<listitem><simpara>If two or more instances have the same priority, -install the most recent one. -</simpara></listitem> -<listitem><simpara>If two or more instances have the same version number, -install the one whose source is listed earliest in &sources-list;. -(The installed instance, if there is one, is always preferred in such a -comparison unless <command>apt-get --reinstall</command> is used.) -</simpara></listitem> +<listitem><simpara>Never downgrade unless the priority of an available +version exceeds 1000. ("Downgrading" is installing a less recent version +of a package in place of a more recent version. Note that none of APT's +default priorities exceeds 1000; such high priorities can only be set in +the preferences file. Note also that downgrading a package +can be risky.)</simpara></listitem> +<listitem><simpara>Install the highest priority version.</simpara></listitem> +<listitem><simpara>If two or more versions have the same priority, +install the most recent one (that is, the one with the higher version +number).</simpara></listitem> +<listitem><simpara>If two or more versions have the same priority and +version number but either the packages differ in some of their metadata or the +<literal/--reinstall/ option is given, install the uninstalled one.</simpara></listitem> </itemizedlist> </para> -<para>In a typical situation, the installed instance of a package (priority 100) -is not as recent as one of the instances available from the sources listed in -the &sources-list; file (priority 500 or 990). Then the package will be -upgraded with the command: -<command>apt-get install</command> or <command>apt-get dist-upgrade</command>. +<para> +In a typical situation, the installed version of a package (priority 100) +is not as recent as one of the versions available from the sources listed in +the &sources-list; file (priority 500 or 990). Then the package will be upgraded +when <command>apt-get install <replaceable>some-package</replaceable></command> +or <command>apt-get upgrade</command> is executed. </para> -<para>Rarely, the installed instance of a package is <emphasis/more/ recent -than any of the other available instances. The package will not be downgraded. +<para> +More rarely, the installed version of a package is <emphasis/more/ recent +than any of the other available versions. The package will not be downgraded +when <command>apt-get install <replaceable>some-package</replaceable></command> +or <command>apt-get upgrade</command> is executed. </para> -<para>Sometimes the installed instance of a package is more recent than the +<para> +Sometimes the installed version of a package is more recent than the version belonging to the target release, but not as recent as a version -belonging to some other distribution. Such a package will indeed be upgraded, -because at least <emphasis/one/ of the available instances has a higher -priority than the installed instance. +belonging to some other distribution. Such a package will indeed be upgraded +when <command>apt-get install <replaceable>some-package</replaceable></command> +or <command>apt-get upgrade</command> is executed, +because at least <emphasis/one/ of the available versions has a higher +priority than the installed version. </para> </RefSect2> <RefSect2><Title>The Effect of APT Preferences</> -<para>The APT preferences file allows the system administrator to customize -priorities. The file consists of one or more multi-line records separated -by blank lines. Records can have one of two forms, a specific form and a -general form. +<para> +The APT preferences file allows the system administrator to control the +assignment of priorities. The file consists of one or more multi-line records +separated by blank lines. Records can have one of two forms, a specific form +and a general form. <itemizedlist> <listitem> -<simpara>The "specific" form pins a priority (a "Pin-Priority") to a -specified package and specified version or version range. For -example, the following record pins a high priority to all versions of -the <filename/perl/ package whose version number begins with -"<literal/5.8/". +<simpara> +The specific form assigns a priority (a "Pin-Priority") to a +specified package and specified version or version range. For example, +the following record assigns a high priority to all versions of +the <filename/perl/ package whose version number begins with "<literal/5.8/". </simpara> <programlisting> @@ -162,17 +162,17 @@ Pin-Priority: 1001 </listitem> <listitem><simpara> -The "general" form pins a priority to all of the package versions in a +The general form assigns a priority to all of the package versions in a given distribution (that is, to all the versions of packages that are -listed in a certain <filename/Release/ file), or to all of the package -instances coming from a particular Internet site, as identified by its -fully qualified domain name. +listed in a certain <filename/Release/ file) or to all of the package +versions coming from a particular Internet site, as identified by the +site's fully qualified domain name. </simpara> -<simpara>This general-form entry in the APT preferences file applies only -to groups of packages. For example, the following record causes APT to -assign a high priority to all package instances available from the local -site. +<simpara> +This general-form entry in the APT preferences file applies only +to groups of packages. For example, the following record assigns a high +priority to all package versions available from the local site. </simpara> <programlisting> @@ -181,16 +181,17 @@ Pin: origin "" Pin-Priority: 999 </programlisting> -<simpara>A note of caution: the keyword used here is "<literal/origin/". -This should not be confused with the "Origin:" of a distribution as +<simpara> +A note of caution: the keyword used here is "<literal/origin/". +This should not be confused with the Origin of a distribution as specified in a <filename/Release/ file. What follows the "Origin:" tag -in a <filename/Release/ file is usually not an Internet site address +in a <filename/Release/ file is not an Internet address but an author or vendor name, such as "Debian" or "Ximian". </simpara> -<simpara>The following record causes APT to assign a low priority to all -package versions belonging to any distribution whose "Archive" -(<literal/a/) name is "<literal/unstable/". +<simpara> +The following record assigns a low priority to all package versions +belonging to any distribution whose Archive name is "<literal/unstable/". </simpara> <programlisting> @@ -199,10 +200,10 @@ Pin: release a=unstable Pin-Priority: 50 </programlisting> -<simpara>The following record causes APT to assign a high priority to all -package versions belonging to any release whose "Archive" (<literal/a/) -name is "<literal/stable/" and whose release "Version" (<literal/v/) -number is "<literal/3.0/". +<simpara> +The following record assigns a high priority to all package versions +belonging to any release whose Archive name is "<literal/stable/" +and whose release Version number is "<literal/3.0/". </simpara> <programlisting> @@ -216,55 +217,58 @@ Pin-Priority: 50 </RefSect2> -<RefSect2><Title>How APT Interprets Priorities + +How APT Interprets Priorities -Priorities (P) assigned in the APT preferences file must be positive + +Priorities (P) assigned in the APT preferences file must be positive or negative integers. They are interpreted as follows (roughly speaking): -P > 1000 -causes an instance to be installed -even if this constitutes a downgrade of the package - + +P > 1000 +causes a version to be installed even if this +constitutes a downgrade of the package -990 < P <=1000 -causes an instance to be installed + +990 < P <=1000 +causes a version to be installed even if it does not come from the target release, -unless the installed instance is more recent - +unless the installed version is more recent -500 < P <=990 -causes an instance to be installed -unless there is an instance available belonging to the target release -or the installed version is more recent - + +500 < P <=990 +causes a version to be installed +unless there is a version available belonging to the target release +or the installed version is more recent -100 < P <=500 -causes an instance to be installed -unless there is an instance available belonging to some other -distribution or the installed version is more recent - -0 <= P <=100 -causes an instance to be installed -only if there is no installed instance of the package - + +100 < P <=500 +causes a version to be installed +unless there is a version available belonging to some other +distribution or the installed version is more recent + +0 <= P <=100 +causes a version to be installed +only if there is no installed version of the package -P < 0 -prevents the instance from being installed - + +P < 0 +prevents the version from being installed -If one of the specific-form records described above matches an -available package instance, then that record determines the priority of -the instance. If two specific-form records match an available instance, -then the first record encountered determines the priority. If two -general-form records match an available instance, then the first record -encountered determines the priority. + +If any specific-form records match an available package version then the +first such record determines the priority of the package version. +Failing that, +if any general-form records match an available package version then the +first such record determines the priority of the package version. -For example, suppose the APT preferences file contains the three + +For example, suppose the APT preferences file contains the three records presented earlier: @@ -289,27 +293,30 @@ package will be installed, so long as that version's version number begins with " -An instance of any package other than A version of any package other than -An instance of a package whose origin is not the local -system but some other site listed in &sources-list;, and which belongs to -an "A version of a package whose origin is not the local +system but some other site listed in &sources-list; and which belongs to +an -Determination of Package Version and Distribution Properties + +Determination of Package Version and Distribution Properties -The locations listed in a system's &sources-list; file should provide + +The locations listed in the &sources-list; file should provide Packages and Release files -to describe the package instances available at that location. +to describe the packages available at that location. -The Packages file is normally found in the directory + +The Packages file is normally found in the directory .../dists/dist-name/component/arch: for example, .../dists/stable/main/binary-i386/Packages. It consists of a series of multi-line records, one for each package available @@ -327,26 +334,27 @@ APT priorities: -The Release file is normally found in the directory + +The Release file is normally found in the directory .../dists/dist-name: for example, .../dists/stable/Release, or .../dists/woody/Release. It consists of a single multi-line record which applies to the -names the archive to which all the package instances +names the archive to which all the packages in the directory tree belong. For example, the line - - Pin: release a=stable @@ -356,11 +364,11 @@ Pin: release a=stable the names the release version. For example, the -package instances in the tree might belong to Debian GNU/Linux release -version 3.0. There is normally no version number for the "testing" and -"unstable" distributions because they have not yet been released. -Specifying this in the APT preferences file would require one of the -following lines. +packages in the tree might belong to Debian GNU/Linux release +version 3.0. Note that there is normally no version number for the + @@ -375,14 +383,13 @@ Pin: release 3.0 the names the licensing component associated with the -package instances in the directory tree of the - Pin: release c=main @@ -391,12 +398,11 @@ Pin: release c=main the -names the producer of the package instances in the +names the originator of the packages in the directory tree of the - Pin: release o=Debian @@ -405,11 +411,11 @@ Pin: release o=Debian the -seems redundant. Most commonly, this is +names the label of the packages in the directory tree +of the - Pin: release l=Debian @@ -418,8 +424,9 @@ Pin: release l=Debian -All of the Packages and Release -files retrieved from locations listed in the &sources-list; file are kept + +All of the Packages and Release +files retrieved from locations listed in the &sources-list; file are stored in the directory /var/lib/apt/lists, or in the file named by the variable -Optional Lines in an APT Preferences Record + +Optional Lines in an APT Preferences Record -Each record in the APT preferences file can optionally begin with + +Each record in the APT preferences file can optionally begin with one or more lines beginning with the word -The +The -Examples</> -<RefSect2><Title>Tracking Stable + +Examples + +Tracking Stable -The following APT preferences file will cause APT to assign a + +The following APT preferences file will cause APT to assign a priority higher than the default (500) to all package versions belonging to a +Explanation: Uninstall or do not install any Debian-originated +Explanation: package versions other than those in the stable distro Package: * Pin: release a=stable Pin-Priority: 900 -Explanation: Uninstall or do not install any Debian-originated -Explanation: instances other than those in the stable distro Package: * Pin: release o=Debian Pin-Priority: -10 @@ -479,20 +492,24 @@ apt-get dist-upgrade -The following command will cause APT to upgrade the specified + +The following command will cause APT to upgrade the specified package to the latest version from the apt-get install package/testing - Tracking Testing + + Tracking Testing or Unstable -The following APT preferences file will cause APT to assign + +The following APT preferences file will cause APT to assign a high priority to package versions from the -With the above APT preferences file, any of the -following commands will cause APT to upgrade to the latest +With a suitable &sources-list; file and the above preferences file, +any of the following commands will cause APT to upgrade to the latest @@ -525,9 +542,11 @@ apt-get dist-upgrade The following command will cause APT to upgrade the specified package to the latest version from the apt-get dist-upgrade and the others -apt-get upgrade will upgrade +the package to the most recent apt-get install package/unstable @@ -537,10 +556,12 @@ apt-get install package/unstable - See Also</> +<RefSect1> +<Title>See Also &apt-get; &apt-cache; &apt-conf; &sources-list; - + + &manbugs; &manauthor;