X-Git-Url: https://git.saurik.com/apt.git/blobdiff_plain/578bfd0aed2ec993f4ad85fa6a7094a852261422..c5d8878d1ffe7484e049f52189a07f3847e4fda9:/doc/guide.sgml?ds=sidebyside diff --git a/doc/guide.sgml b/doc/guide.sgml index bbc01b78b..1b7e1d8f3 100644 --- a/doc/guide.sgml +++ b/doc/guide.sgml @@ -1,10 +1,10 @@ - + APT User's Guide Jason Gunthorpe jgg@debian.org -$Id: guide.sgml,v 1.1 1998/07/02 02:58:12 jgg Exp $ +$Id: guide.sgml,v 1.7 2003/04/26 23:26:13 doogie Exp $ This document provides an overview of how to use the the APT package manager. @@ -20,7 +20,7 @@ option) any later version.

For more details, on Debian GNU/Linux systems, see the file -/usr/doc/copyright/GPL for the full license. +/usr/share/common-licenses/GPL for the full license. @@ -39,14 +39,14 @@ the Internet.

The Debian packaging system has a large amount of information associated with each package to help assure that it integrates cleanly and easily into -the system. The most prominent of features is the dependency system. +the system. The most prominent of its features is the dependency system.

The dependency system allows individual programs to make use of shared elements in the system such as libraries. It simplifies placing infrequently used portions of a program in separate packages to reduce the number of things the average user is required to install. Also, it allows -a choices in for such things as mail transport agents, X servers and +for choices in mail transport agents, X servers and so on.

@@ -55,9 +55,9 @@ of a simple dependency. The meaning of a simple dependency is that a package requires another package to be installed at the same time to work properly.

-For instance, mail-crypt is an emacs extension that aids in encrypting email -with PGP. Without PGP installed mail-crypt is useless, so mail-crypt has a -simple dependency on PGP. Also, because it is an emacs extension it has a +For instance, mailcrypt is an emacs extension that aids in encrypting email +with GPG. Without GPGP installed mail-crypt is useless, so mailcrypt has a +simple dependency on GPG. Also, because it is an emacs extension it has a simple dependency on emacs, without emacs it is completely useless.

@@ -96,7 +96,7 @@ for installation.

apt-get provides a simple way to install packages from the command line. Unlike dpkg, apt-get does not understand .deb files, -it works with the packages proper name and can only install .deb archives from +it works with the package's proper name and can only install .deb archives from a Source.

@@ -110,14 +110,13 @@ available. This is done with apt-get update. For instance, # apt-get update Get http://ftp.de.debian.org/debian-non-US/ stable/binary-i386/ Packages -Get http://llug.sep.bnl.gov/debian/ frozen/contrib Packages -Updating package file cache...done -Updating package status cache...done -Checking system integrity...ok +Get http://llug.sep.bnl.gov/debian/ testing/contrib Packages +Reading Package Lists... Done +Building Dependency Tree... Done

-Once updated there are several useful commands that can be used, +Once updated there are several commands that can be used: upgrade Upgrade will attempt to gently upgrade the whole system. Upgrade will @@ -126,20 +125,20 @@ ever upgrade a package that might cause some other package to break. This can be used daily to relatively safely upgrade the system. Upgrade will list all of the packages that it could not upgrade, this usually means that they depend on new packages or conflict with some other package. -Dselect or apt-get install can be used to force these +dselect or apt-get install can be used to force these packages to install. install -Install is used to install single packages by name. The package is +Install is used to install packages by name. The package is automatically fetched and installed. This can be useful if you already know the name of the package to install and do not want to go into a GUI to select it. Any number of packages may be passed to install, they will all be fetched. Install automatically attempts to resolve dependency problems with the listed packages and will print a summary and ask for confirmation -if anything other than it's arguments are changed +if anything other than its arguments are changed. dist-upgrade -Dist-upgrade is a complete upgrader designed to make simple upgrading between +Dist-upgrade is a complete upgrader designed to simplify upgrading between releases of Debian. It uses a sophisticated algorithm to determine the best set of packages to install, upgrade and remove to get as much of the system to the newest release. In some situations it may be desired to use dist-upgrade @@ -153,7 +152,7 @@ decisions may sometimes be quite surprising.

-apt-get has several command line options that are detailed in it's +apt-get has several command line options that are detailed in its man page, . The most useful option is -d which does not install the fetched files. If the system has to download a large number of package it would be undesired to start installing @@ -207,7 +206,7 @@ get. Please give the distribution tag to get or a path to the package file ending in a /. The distribution - tags are typically something like: stable unstable frozen non-US + tags are typically something like: stable unstable testing non-US Distribution [stable]: @@ -219,10 +218,6 @@ developmental version. non-US is only available on some mirrors and refers to packages that contain encryption technology or other things that cannot be exported from the United States. Importing these packages into the US is legal however. -As of this writing the non-US distribution has -not been created, the only way to access it is by specifying -stable/binary-i386/ at this prompt and by specifying a URL ending in -debian-non-US

@@ -234,7 +229,7 @@ debian-non-US

The components list refers to the list of sub distributions to fetch. The -distribution is split up based on software copyright, main being DFSG free +distribution is split up based on software licenses, main being DFSG free packages while contrib and non-free contain things that have various restrictions placed on their use and distribution. @@ -255,6 +250,11 @@ perform the installation using [I]nstall. When using the APT method the [C]onfig and [R]emove commands have no meaning, the [I]nstall command performs both of them together. +

+By default APT will automatically remove the package (.deb) files once they have been +successfully installed. To change this behavior place Dselect::clean +"prompt"; in /etc/apt/apt.conf. + @@ -275,65 +275,60 @@ informative status messages so that you can estimate how far along it is and how much is left to do. -The Pre-Checks +Startup

-Before all operations, except update, APT performs a number of checks on the -systems. These are designed to safe guard the operations it is about to -undertake. At any time the full set of checks may be run by performing -apt-get check. +Before all operations except update, APT performs a number of actions to +prepare its internal state. It also does some checks of the system's state. +At any time these operations can be performed by running apt-get check.

# apt-get check -Updating package file cache...done -Updating package status cache...done -Checking system integrity...ok +Reading Package Lists... Done +Building Dependency Tree... Done

-The first check is to ensure that the archive package lists are matched to -the pre-generated data cache, if they are not then the cache is automatically -refreshed. This may fail if apt-get update has not been run to -synchronize with the Sources. The next check verifies that the state of -the system matches the cached state and automatically rebuilds the cached -state if they are not synchronized. This check should never fail and it -indicates a serious error if it ever does. +The first thing it does is read all the package files into memory. APT +uses a caching scheme so this operation will be faster the second time it +is run. If some of the package files are not found then they will be ignored +and a warning will be printed when apt-get exits.

-The final check performs a detailed analysis of the system integrity. It -checks every dependency of every installed or unpacked package and considers -if it is ok. Should this find a problem then a report will be printed out and +The final operation performs a detailed analysis of the system's dependencies. +It checks every dependency of every installed or unpacked package and considers +if it is OK. Should this find a problem then a report will be printed out and apt-get will refuse to run.

# apt-get check -Updating package file cache...done -Updating package status cache...done -Checking system integrity...dependency error +Reading Package Lists... Done +Building Dependency Tree... Done You might want to run apt-get -f install' to correct these. -Sorry, but the following packages are broken - this means they have unmet -dependencies: - libdbd-mysql-perl: Depends:perl - xzx: Depends:xlib6 - libdbd-msql-perl: Depends:perl - mailpgp: Depends:pgp-i Depends:pgp-us - xdpkg: Depends:python - squake: Depends:quake-lib Depends:quake-lib-stub - debmake: Depends:fileutils - libreadlineg2: Conflicts:libreadline2 - ssh: Depends:gmp2 Depends:xlib6g Depends:zlib1g +Sorry, but the following packages have unmet dependencies: + 9fonts: Depends: xlib6g but it is not installed + uucp: Depends: mailx but it is not installed + blast: Depends: xlib6g (>= 3.3-5) but it is not installed + adduser: Depends: perl-base but it is not installed + aumix: Depends: libgpmg1 but it is not installed + debiandoc-sgml: Depends: sgml-base but it is not installed + bash-builtins: Depends: bash (>= 2.01) but 2.0-3 is installed + cthugha: Depends: svgalibg1 but it is not installed + Depends: xlib6g (>= 3.3-5) but it is not installed + libreadlineg2: Conflicts:libreadline2 (<< 2.1-2.1)

In this example the system has many problems, including a serious problem with libreadlineg2. For each package that has unmet dependencies a line is printed out indicating the package with the problem and the dependencies -that are unmet. For brevity the version inter-relationships are omitted. +that are unmet. A short explanation of why the package has a dependency +problem is also included.

There are two ways a system can get into a broken state like this. The -first is caused by dpkg missing some subtle relationships between +first is caused by dpkg missing some subtle relationships between packages when performing upgrades. APT however considers all known dependencies and attempts to prevent broken packages. The second is if a package installation fails during an operation. In this situation a @@ -341,8 +336,8 @@ package may have been unpacked without its dependents being installed.

The second situation is much less serious than the first because APT places -certain assurances on the order that packages are installed. In both cases -supplying the -f option to atp-get will cause APT to deduce a +certain constraints on the order that packages are installed. In both cases +supplying the -f option to apt-get will cause APT to deduce a possible solution to the problem and then continue on. The APT dselect method always supplies the -f option to allow for easy continuation of failed maintainer scripts. @@ -400,7 +395,7 @@ should be given a careful inspection to ensure nothing important is to be taken off. The -f option is especially good at generating packages to remove so extreme care should be used in that case. The list may contain packages that are going to be removed because they are only -partially removed, possibly due to an aborted installation. +partially installed, possibly due to an aborted installation. The New Packages list @@ -472,23 +467,26 @@ installed packages. It is roughly equivalent to the space required in removed then the value may indicate the amount of space that will be freed. +

+Some other reports can be generated by using the -u option to show packages +to upgrade, they are similar to the previous examples. The Status Display

During the download of archives and package files APT prints out a series of -status messages, +status messages.

# apt-get update -Get http://ftp.de.debian.org/debian-non-US/ stable/binary-i386/ Packages -Get http://llug.sep.bnl.gov/debian/ frozen/contrib Packages -Get http://llug.sep.bnl.gov/debian/ frozen/main Packages -Get http://ftp.de.debian.org/debian-non-US/ unstable/binary-i386/ Packages -Get http://llug.sep.bnl.gov/debian/ frozen/non-free Packages -11% [Packages `Waiting for file' 0/32.1k 0%] 2203b/s 1m52s +Get:1 http://ftp.de.debian.org/debian-non-US/ stable/non-US/ Packages +Get:2 http://llug.sep.bnl.gov/debian/ testing/contrib Packages +Hit http://llug.sep.bnl.gov/debian/ testing/main Packages +Get:4 http://ftp.de.debian.org/debian-non-US/ unstable/binary-i386/ Packages +Get:5 http://llug.sep.bnl.gov/debian/ testing/non-free Packages +11% [5 testing/non-free `Waiting for file' 0/32.1k 0%] 2203b/s 1m52s

@@ -500,10 +498,11 @@ files. Unfortunately since the size of the Package files is unknown inaccuracies.

-The next section of the status line is repeated once for each dowload thread -and indicates the operation being performed and some usefull information +The next section of the status line is repeated once for each download thread +and indicates the operation being performed and some useful information about what is happening. Sometimes this section will simply read Forking -which means the OS is loading the download module. The first word after the [ +which means the OS is loading the download module. The first word after the [ +is the fetch number as shown on the history lines. The next word is the short form name of the object being downloaded. For archives it will contain the name of the package that is being fetched. @@ -512,11 +511,11 @@ Inside of the single quote is an informative string indicating the progress of the negotiation phase of the download. Typically it progresses from Connecting to Waiting for file to Downloading or Resuming. The final value is the number of bytes downloaded from the -remote site. Once the download beings this is represented as 102/10.2k +remote site. Once the download begins this is represented as 102/10.2k indicating that 102 bytes have been fetched and 10.2 kilobytes is expected. The total size is always shown in 4 figure notation to preserve space. After the size display is a percent meter for the file itself. -The second last element is the instantenous average speed. This values is +The second last element is the instantaneous average speed. This values is updated every 5 seconds and reflects the rate of data transfer for that period. Finally is shown the estimated transfer time. This is updated regularly and reflects the time to complete everything at the shown @@ -536,7 +535,7 @@ status display.

APT uses dpkg for installing the archives and will switch over to the dpkg interface once downloading is completed. -dpkg will also as a number of questions as it processes the packages +dpkg will also ask a number of questions as it processes the packages and the packages themselves may also ask several questions. Before each question there is usually a description of what it is asking and the questions are too varied to discuss completely here.