diff options
author | Arch Librarian <arch@canonical.com> | 2004-09-20 16:50:36 +0000 |
---|---|---|
committer | Arch Librarian <arch@canonical.com> | 2004-09-20 16:50:36 +0000 |
commit | 578bfd0aed2ec993f4ad85fa6a7094a852261422 (patch) | |
tree | 737f52267f6468a4b6754f8c6665824767352746 /doc/guide.sgml |
Base revisions
Author: jgg
Date: 1998-07-02 02:58:12 GMT
Base revisions
Diffstat (limited to 'doc/guide.sgml')
-rw-r--r-- | doc/guide.sgml | 548 |
1 files changed, 548 insertions, 0 deletions
diff --git a/doc/guide.sgml b/doc/guide.sgml new file mode 100644 index 000000000..bbc01b78b --- /dev/null +++ b/doc/guide.sgml @@ -0,0 +1,548 @@ +<!doctype debiandoc system> +<!-- -*- mode: sgml; mode: fold -*- --> +<book> +<title>APT User's Guide</title> + +<author>Jason Gunthorpe <email>jgg@debian.org</email></author> +<version>$Id: guide.sgml,v 1.1 1998/07/02 02:58:12 jgg Exp $</version> + +<abstract> +This document provides an overview of how to use the the APT package manager. +</abstract> + +<copyright> +Copyright © Jason Gunthorpe, 1998. +<p> +"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. + +<p> +For more details, on Debian GNU/Linux systems, see the file +/usr/doc/copyright/GPL for the full license. +</copyright> + +<toc sect> + +<!-- General {{{ --> +<!-- ===================================================================== --> +<chapt>General + +<p> +The APT package currently contains two sections, the APT <prgn>dselect</> +method and the <prgn>apt-get</> command line user interface. Both provide +a way to install and remove packages as well as download new packages from +the Internet. + +<sect>Anatomy of the Package System +<p> +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. + +<p> +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 +so on. + +<p> +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. + +<p> +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 +simple dependency on emacs, without emacs it is completely useless. + +<p> +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. + +<p> +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. + +<p> +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. +</sect> + +</chapt> + <!-- }}} --> +<!-- apt-get {{{ --> +<!-- ===================================================================== --> +<chapt>apt-get + +<p> +<prgn>apt-get</> provides a simple way to install packages from the command +line. Unlike <prgn>dpkg</>, <prgn>apt-get</> does not understand .deb files, +it works with the packages proper name and can only install .deb archives from +a <em>Source</>. + +<p> +The first <footnote>If you are using an http proxy server you must set the +http_proxy environment variable first, see sources.list(5)</footnote> thing that +should be done before using <prgn>apt-get</> is to fetch the package lists +from the <em>Sources</> so that it knows what packages are +available. This is done with <tt>apt-get update</>. For instance, + +<p> +<example> +# 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 +</example> + +<p> +Once updated there are several useful commands that can be used, +<taglist> +<tag>upgrade<item> +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. +<prgn>Dselect</> or <tt>apt-get install</> can be used to force these +packages to install. + +<tag>install<item> +Install is used to install single 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 + +<tag>dist-upgrade<item> +Dist-upgrade is a complete upgrader designed to make simple 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 <prgn>dselect</>. +Once dist-upgrade has completed then <prgn>dselect</> can be used to install +any packages that may have been left out. + +<p> +It is important to closely look at what dist-upgrade is going to do, its +decisions may sometimes be quite surprising. +</taglist> + +<p> +<prgn>apt-get</> has several command line options that are detailed in it's +man page, <manref name="apt-get" section="8">. The most useful option is +<tt>-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 +them in case something goes wrong. When <tt>-d</> is used the downloaded +archives can be installed by simply running the command that caused them to +be downloaded again without <tt>-d</>. + +</chapt> + <!-- }}} --> +<!-- DSelect {{{ --> +<!-- ===================================================================== --> +<chapt>DSelect +<p> +The APT <prgn>dselect</> method provides the complete APT system with +the <prgn>dselect</> package selection GUI. <prgn>dselect</> is used to +select the packages to be installed or removed and APT actually installs them. + +<p> +To enable the APT method you need to to select [A]ccess in <prgn>dselect</> +and then choose the APT method. You will be prompted for a set of +<em>Sources</> which are places to fetch archives from. These can be remote +Internet sites, local Debian mirrors or CDROMs. 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 CDROM 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 CDROM before +downloading from the Internet. + +<p> +<example> + 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]: +</example> + +<p> +The <em>Sources</> setup starts by asking for the base of the Debian +archive, defaulting to a HTTP mirror. Next it asks for the distribution to +get. + +<p> +<example> + 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 + + Distribution [stable]: +</example> + +<p> +The distribution refers to the Debian version in the archive, <em>stable</> +refers to the latest released version and <em>unstable</> refers to the +developmental version. <em>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. +<footnote>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 </footnote> + +<p> +<example> + Please give the components to get + The components are typically something like: main contrib non-free + + Components [main contrib non-free]: +</example> + +<p> +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 +packages while contrib and non-free contain things that have various +restrictions placed on their use and distribution. + +<p> +Any number of sources can be added, the setup script will continue to +prompt until you have specified all that you want. + +<p> +Before starting to use <prgn>dselect</> it is necessary to update the +available list by selecting [U]pdate from the menu. This is a super-set of +<tt>apt-get update</> that makes the fetched information available to +<prgn>dselect</>. [U]pdate must be performed even if <tt>apt-get update</> +has been run before. + +<p> +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. + +</chapt> + <!-- }}} --> +<!-- The Interfaces {{{ --> +<!-- ===================================================================== --> +<chapt>The Interface + +<p> +Both that APT <prgn>dselect</> method and <prgn>apt-get</> share the same +interface. It is a simple system that generally tells you what it will do +and then goes and does it. +<footnote> +The <prgn>dselect</> method actually is a set of wrapper scripts +to <prgn>apt-get</>. The method actually provides more functionality than +is present in <prgn>apt-get</> alone. +</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. + +<!-- ===================================================================== --> +<sect>The Pre-Checks + +<p> +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 +<tt>apt-get check</>. +<p> +<example> +# apt-get check +Updating package file cache...done +Updating package status cache...done +Checking system integrity...ok +</example> + +<p> +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 <tt>apt-get update</> has not been run to +synchronize with the <em>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. + +<p> +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 +<prgn>apt-get</> will refuse to run. + +<p> +<example> +# apt-get check +Updating package file cache...done +Updating package status cache...done +Checking system integrity...dependency error +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 +</example> + +<p> +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. + +<p> +There are two ways a system can get into a broken state like this. The +first is caused by <prgn>dpkg missing</> some subtle relationships between +packages when performing upgrades. <footnote>APT however considers all known +dependencies and attempts to prevent broken packages</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. + +<p> +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 <tt>-f</> option to <prgn>atp-get</> will cause APT to deduce a +possible solution to the problem and then continue on. The APT <prgn>dselect</> +method always supplies the <tt>-f</> option to allow for easy continuation +of failed maintainer scripts. + +<p> +However, if the <tt>-f</> 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. +</sect> + +<!-- ===================================================================== --> +<sect>The Status Report + +<p> +Before proceeding <prgn>apt-get</> 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 <tt>-f</> option and any other relevant +activities to the command being executed. + +<sect1>The Extra Package list +<p> +<example> +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 +</example> + +<p> +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 <tt>install</> command. The listed packages are +often the result of an Auto Install. +</sect1> + +<sect1>The Packages to Remove +<p> +<example> +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 +</example> + +<p> +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 <tt>-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. +</sect1> + +<sect1>The New Packages list +<p> +<example> +The following NEW packages will installed: + zlib1g xlib6g perl-base libgdbmg1 quake-lib gmp2 pgp-i python-base +</example> + +<p> +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. +</sect1> + +<sect1>The Kept Back list +<p> +<example> +The following packages have been kept back + compface man-db tetex-base msql libpaper svgalib1 + gs snmp arena lynx xpat2 groff xscreensaver +</example> + +<p> +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 <tt>apt-get install</> or by using <prgn>dselect</> +to resolve their problems. +</sect1> + +<sect1>Held Packages warning +<p> +<example> +The following held packages will be changed: + cvs +</example> + +<p> +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. +</sect1> + +<sect1>Final summary +<p> +Finally, APT will print out a summary of all the changes that will occur. + +<p> +<example> +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. +</example> + +<p> +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. + +</sect> + +<!-- ===================================================================== --> +<sect>The Status Display +<p> +During the download of archives and package files APT prints out a series of +status messages, + +<p> +<example> +# 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 +</example> + +<p> +The lines starting with <em>Get</> 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 +<tt>apt-get update</> estimates the percent done which causes some +inaccuracies. + +<p> +The next section of the status line is repeated once for each dowload thread +and indicates the operation being performed and some usefull information +about what is happening. Sometimes this section will simply read <em>Forking</> +which means the OS is loading the download module. The first word after the [ +is the short form name of the object being downloaded. For archives it will +contain the name of the package that is being fetched. + +<p> +Inside of the single quote is an informative string indicating the progress +of the negotiation phase of the download. Typically it progresses from +<em>Connecting</> to <em>Waiting for file</> to <em>Downloading</> or +<em>Resuming</>. The final value is the number of bytes downloaded from the +remote site. Once the download beings this is represented as <tt>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 +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. + +<p> +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 <tt>-q</> option to remove the +status display. +</sect> + +<!-- ===================================================================== --> +<sect>Dpkg + +<p> +APT uses <prgn>dpkg</> for installing the archives and will switch +over to the <prgn>dpkg</> interface once downloading is completed. +<prgn>dpkg</> will also as 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. +</sect> + +</chapt> + <!-- }}} --> + +</book> |