diff options
Diffstat (limited to 'doc/guide.dbk')
| -rw-r--r-- | doc/guide.dbk | 560 |
1 files changed, 560 insertions, 0 deletions
diff --git a/doc/guide.dbk b/doc/guide.dbk new file mode 100644 index 000000000..e8a8ae274 --- /dev/null +++ b/doc/guide.dbk @@ -0,0 +1,560 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- -*- DocBook -*- --> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment; +]> + +<book lang="en"> + +<title>APT User's Guide</title> + +<bookinfo> + +<authorgroup> + <author> + <personname>Jason Gunthorpe</personname><email>jgg@debian.org</email> + </author> +</authorgroup> + +<releaseinfo>Version &apt-product-version;</releaseinfo> + +<abstract> +<para> +This document provides an overview of how to use the the APT package manager. +</para> +</abstract> + +<copyright><year>1998</year><holder>Jason Gunthorpe</holder></copyright> + +<legalnotice> +<title>License Notice</title> +<para> +"APT" and this document are free software; you can redistribute them and/or +modify them under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or (at your +option) any later version. +</para> +</legalnotice> + +<legalnotice> +<para> +For more details, on Debian systems, see the file +/usr/share/common-licenses/GPL for the full license. +</para> +</legalnotice> + +</bookinfo> + +<chapter id="ch1"><title>General</title> +<para> +The APT package currently contains two sections, the APT +<command>dselect</command> method and the <command>apt-get</command> command +line user interface. Both provide a way to install and remove packages as well +as download new packages from the Internet. +</para> + +<section id="s1.1"><title>Anatomy of the Package System</title> +<para> +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 its features is the dependency system. +</para> +<para> +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 for choices in mail +transport agents, X servers and so on. +</para> +<para> +The first step to understanding the dependency system is to grasp the concept +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. +</para> +<para> +For instance, mailcrypt is an emacs extension that aids in encrypting email +with GPG. Without GPGP installed mailcrypt 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. +</para> +<para> +The other important dependency to understand is a conflicting dependency. It +means that a package, when installed with another package, will not work and +may possibly be extremely harmful to the system. As an example consider a mail +transport agent such as sendmail, exim or qmail. It is not possible to have +two mail transport agents installed because both need to listen to the network +to receive mail. Attempting to install two will seriously damage the system so +all mail transport agents have a conflicting dependency with all other mail +transport agents. +</para> +<para> +As an added complication there is the possibility for a package to pretend to +be another package. Consider that exim and sendmail for many intents are +identical, they both deliver mail and understand a common interface. Hence, +the package system has a way for them to declare that they are both +mail-transport-agents. So, exim and sendmail both declare that they provide a +mail-transport-agent and other packages that need a mail transport agent depend +on mail-transport-agent. This can add a great deal of confusion when trying to +manually fix packages. +</para> +<para> +At any given time a single dependency may be met by packages that are already +installed or it may not be. APT attempts to help resolve dependency issues by +providing a number of automatic algorithms that help in selecting packages for +installation. +</para> +</section> + +</chapter> + +<chapter id="ch2"><title>apt-get</title> +<para> +<command>apt-get</command> provides a simple way to install packages from the +command line. Unlike <command>dpkg</command>, <command>apt-get</command> does +not understand .deb files, it works with the package's proper name and can only +install .deb archives from a <emphasis>Source</emphasis>. +</para> +<para> +The first <footnote><para> If you are using an http proxy server you must set +the http_proxy environment variable first, see sources.list(5) </para> +</footnote> thing that should be done before using <command>apt-get</command> +is to fetch the package lists from the <emphasis>Sources</emphasis> so that it +knows what packages are available. This is done with <literal>apt-get +update</literal>. For instance, +</para> +<screen> +# apt-get update +Get http://ftp.de.debian.org/debian-non-US/ stable/binary-i386/ Packages +Get http://llug.sep.bnl.gov/debian/ testing/contrib Packages +Reading Package Lists... Done +Building Dependency Tree... Done +</screen> +<para> +Once updated there are several commands that can be used: +</para> +<variablelist> +<varlistentry> +<term>upgrade</term> +<listitem> +<para> +Upgrade will attempt to gently upgrade the whole system. Upgrade will never +install a new package or remove an existing package, nor will it 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. <command>dselect</command> or +<literal>apt-get install</literal> can be used to force these packages to +install. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>install</term> +<listitem> +<para> +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 its +arguments are changed. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>dist-upgrade</term> +<listitem> +<para> +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 +rather than spend the time manually resolving dependencies in +<command>dselect</command>. Once dist-upgrade has completed then +<command>dselect</command> can be used to install any packages that may have +been left out. +</para> +<para> +It is important to closely look at what dist-upgrade is going to do, its +decisions may sometimes be quite surprising. +</para> +</listitem> +</varlistentry> +</variablelist> +<para> +<command>apt-get</command> has several command line options that are detailed +in its man page, +<citerefentry><refentrytitle>apt-get</refentrytitle><manvolnum>8</manvolnum></citerefentry>. The +most useful option is <literal>-d</literal> 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 them in case something goes wrong. When +<literal>-d</literal> is used the downloaded archives can be installed by +simply running the command that caused them to be downloaded again without +<literal>-d</literal>. +</para> +</chapter> + +<chapter id="ch3"><title>DSelect</title> +<para> +The APT <command>dselect</command> method provides the complete +APT system with the <command>dselect</command> package selection +GUI. <command>dselect</command> is used to select the packages to be +installed or removed and APT actually installs them. +</para> +<para> +To enable the APT method you need to select [A]ccess in +<command>dselect</command> and then choose the APT method. You will be +prompted for a set of <emphasis>Sources</emphasis> which are places to fetch +archives from. These can be remote Internet sites, local Debian mirrors or +CD-ROMs. Each source can provide a fragment of the total Debian archive, APT +will automatically combine them to form a complete set of packages. If you +have a CD-ROM then it is a good idea to specify it first and then specify a +mirror so that you have access to the latest bug fixes. APT will automatically +use packages on your CD-ROM before downloading from the Internet. +</para> +<screen> + Set up a list of distribution source locations + + Please give the base URL of the debian distribution. + The access schemes I know about are: http file + + For example: + file:/mnt/debian, + ftp://ftp.debian.org/debian, + http://ftp.de.debian.org/debian, + + + URL [http://llug.sep.bnl.gov/debian]: +</screen> +<para> +The <emphasis>Sources</emphasis> setup starts by asking for the base of the +Debian archive, defaulting to a HTTP mirror. Next it asks for the distribution +to get. +</para> +<screen> + 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 testing non-US + + Distribution [stable]: +</screen> +<para> +The distribution refers to the Debian version in the archive, +<emphasis>stable</emphasis> refers to the latest released version +and <emphasis>unstable</emphasis> refers to the developmental +version. <emphasis>non-US</emphasis> 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. +</para> +<screen> + Please give the components to get + The components are typically something like: main contrib non-free + + Components [main contrib non-free]: +</screen> +<para> +The components list refers to the list of sub distributions to fetch. The +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. +</para> +<para> +Any number of sources can be added, the setup script will continue to prompt +until you have specified all that you want. +</para> +<para> +Before starting to use <command>dselect</command> it is necessary to update +the available list by selecting [U]pdate from the menu. This is a superset of +<literal>apt-get update</literal> that makes the fetched information available +to <command>dselect</command>. [U]pdate must be performed even if +<literal>apt-get update</literal> has been run before. +</para> +<para> +You can then go on and make your selections using [S]elect and then 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. +</para> +<para> +By default APT will automatically remove the package (.deb) files once they +have been successfully installed. To change this behavior place +<literal>Dselect::clean "prompt";</literal> in /etc/apt/apt.conf. +</para> +</chapter> + +<chapter id="ch4"><title>The Interface</title> +<para> +Both that APT <command>dselect</command> method and <command>apt-get</command> +share the same interface. It is a simple system that generally tells you what +it will do and then goes and does it. <footnote><para> The +<command>dselect</command> method actually is a set of wrapper scripts to +<command>apt-get</command>. The method actually provides more functionality +than is present in <command>apt-get</command> alone. </para> </footnote> After +printing out a summary of what will happen APT then will print out some +informative status messages so that you can estimate how far along it is and +how much is left to do. +</para> + +<section id="s4.1"><title>Startup</title> +<para> +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 +<literal>apt-get check</literal>. +</para> +<screen> +# apt-get check +Reading Package Lists... Done +Building Dependency Tree... Done +</screen> +<para> +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. +</para> +<para> +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 <command>apt-get</command> will refuse to run. +</para> +<screen> +# apt-get check +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 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) +</screen> +<para> +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. A short explanation of why the package has a dependency problem is also +included. +</para> +<para> +There are two ways a system can get into a broken state like this. The +first is caused by <command>dpkg</command> missing some subtle relationships +between packages when performing upgrades. <footnote><para> APT however +considers all known dependencies and attempts to prevent broken +packages </para> </footnote>. The second is if a package installation +fails during an operation. In this situation a package may have been +unpacked without its dependents being installed. +</para> +<para> +The second situation is much less serious than the first because APT places +certain constraints on the order that packages are installed. In both cases +supplying the <literal>-f</literal> option to <command>apt-get</command> +will cause APT to deduce a possible solution to the problem and then +continue on. The APT <command>dselect</command> method always supplies +the <literal>-f</literal> option to allow for easy continuation of failed +maintainer scripts. +</para> +<para> +However, if the <literal>-f</literal> option is used to correct a seriously +broken system caused by the first case then it is possible that it will either +fail immediately or the installation sequence will fail. In either case it is +necessary to manually use dpkg (possibly with forcing options) to correct the +situation enough to allow APT to proceed. +</para> +</section> + +<section id="s4.2"><title>The Status Report</title> +<para> +Before proceeding <command>apt-get</command> will present a report on what will +happen. Generally the report reflects the type of operation being performed +but there are several common elements. In all cases the lists reflect the +final state of things, taking into account the <literal>-f</literal> option +and any other relevant activities to the command being executed. +</para> + +<section id="s4.2.1"><title>The Extra Package list</title> +<screen> +The following extra packages will be installed: + libdbd-mysql-perl xlib6 zlib1 xzx libreadline2 libdbd-msql-perl + mailpgp xdpkg fileutils pinepgp zlib1g xlib6g perl-base + bin86 libgdbm1 libgdbmg1 quake-lib gmp2 bcc xbuffy + squake pgp-i python-base debmake ldso perl libreadlineg2 + ssh +</screen> +<para> +The Extra Package list shows all of the packages that will be installed or +upgraded in excess of the ones mentioned on the command line. It is only +generated for an <literal>install</literal> command. The listed packages are +often the result of an Auto Install. +</para> +</section> + +<section id="s4.2.2"><title>The Packages to Remove</title> +<screen> +The following packages will be REMOVED: + xlib6-dev xpat2 tk40-dev xkeycaps xbattle xonix + xdaliclock tk40 tk41 xforms0.86 ghostview xloadimage xcolorsel + xadmin xboard perl-debug tkined xtetris libreadline2-dev perl-suid + nas xpilot xfig +</screen> +<para> +The Packages to Remove list shows all of the packages that will be removed +from the system. It can be shown for any of the operations and should be given +a careful inspection to ensure nothing important is to be taken off. The +<literal>-f</literal> 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 +installed, possibly due to an aborted installation. +</para> +</section> + +<section id="s4.2.3"><title>The New Packages list</title> +<screen> +The following NEW packages will installed: + zlib1g xlib6g perl-base libgdbmg1 quake-lib gmp2 pgp-i python-base +</screen> +<para> +The New Packages list is simply a reminder of what will happen. The packages +listed are not presently installed in the system but will be when APT is done. +</para> +</section> + +<section id="s4.2.4"><title>The Kept Back list</title> +<screen> +The following packages have been kept back + compface man-db tetex-base msql libpaper svgalib1 + gs snmp arena lynx xpat2 groff xscreensaver +</screen> +<para> +Whenever the whole system is being upgraded there is the possibility that new +versions of packages cannot be installed because they require new things or +conflict with already installed things. In this case the package will appear +in the Kept Back list. The best way to convince packages listed there to +install is with <literal>apt-get install</literal> or by using +<command>dselect</command> to resolve their problems. +</para> +</section> + +<section id="s4.2.5"><title>Held Packages warning</title> +<screen> +The following held packages will be changed: + cvs +</screen> +<para> +Sometimes you can ask APT to install a package that is on hold, in such a case +it prints out a warning that the held package is going to be changed. This +should only happen during dist-upgrade or install. +</para> +</section> + +<section id="s4.2.6"><title>Final summary</title> +<para> +Finally, APT will print out a summary of all the changes that will occur. +</para> +<screen> +206 packages upgraded, 8 newly installed, 23 to remove and 51 not upgraded. +12 packages not fully installed or removed. +Need to get 65.7M/66.7M of archives. After unpacking 26.5M will be used. +</screen> +<para> +The first line of the summary simply is a reduced version of all of the lists +and includes the number of upgrades - that is packages already installed that +have new versions available. The second line indicates the number of poorly +configured packages, possibly the result of an aborted installation. The final +line shows the space requirements that the installation needs. The first pair +of numbers refer to the size of the archive files. The first number indicates +the number of bytes that must be fetched from remote locations and the second +indicates the total size of all the archives required. The next number +indicates the size difference between the presently installed packages and the +newly installed packages. It is roughly equivalent to the space required in +/usr after everything is done. If a large number of packages are being removed +then the value may indicate the amount of space that will be freed. +</para> +<para> +Some other reports can be generated by using the -u option to show packages to +upgrade, they are similar to the previous examples. +</para> +</section> + +</section> + +<section id="s4.3"><title>The Status Display</title> +<para> +During the download of archives and package files APT prints out a series of +status messages. +</para> +<screen> +# apt-get update +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 +</screen> +<para> +The lines starting with <emphasis>Get</emphasis> are printed out when APT +begins to fetch a file while the last line indicates the progress of the +download. The first percent value on the progress line indicates the total +percent done of all files. Unfortunately since the size of the Package files +is unknown <literal>apt-get update</literal> estimates the percent done which +causes some inaccuracies. +</para> +<para> +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 <emphasis>Forking</emphasis> 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. +</para> +<para> +Inside of the single quote is an informative string indicating the progress of +the negotiation phase of the download. Typically it progresses from +<emphasis>Connecting</emphasis> to <emphasis>Waiting for file</emphasis> to +<emphasis>Downloading</emphasis> or <emphasis>Resuming</emphasis>. The final +value is the number of bytes downloaded from the remote site. Once the +download begins this is represented as <literal>102/10.2k</literal> 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 +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 transfer rate. +</para> +<para> +The status display updates every half second to provide a constant feedback on +the download progress while the Get lines scroll back whenever a new file is +started. Since the status display is constantly updated it is unsuitable for +logging to a file, use the <literal>-q</literal> option to remove the status +display. +</para> +</section> + +<section id="s4.4"><title>Dpkg</title> +<para> +APT uses <command>dpkg</command> for installing the archives and will +switch over to the <command>dpkg</command> interface once downloading is +completed. <command>dpkg</command> 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. +</para> +</section> + +</chapter> + +</book> |