diff options
Diffstat (limited to 'doc/guide.sgml')
| -rw-r--r-- | doc/guide.sgml | 547 |
1 files changed, 0 insertions, 547 deletions
diff --git a/doc/guide.sgml b/doc/guide.sgml deleted file mode 100644 index 747c5718c..000000000 --- a/doc/guide.sgml +++ /dev/null @@ -1,547 +0,0 @@ -<!-- -*- mode: sgml; mode: fold -*- --> -<!doctype debiandoc PUBLIC "-//DebianDoc//DTD DebianDoc//EN"> -<book> -<title>APT User's Guide</title> - -<author>Jason Gunthorpe <email>jgg@debian.org</email></author> -<version>$Id: guide.sgml,v 1.7 2003/04/26 23:26:13 doogie 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 systems, see the file -/usr/share/common-licenses/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 its 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 -for choices in 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, 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. - -<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 package's 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/ testing/contrib Packages -Reading Package Lists... Done -Building Dependency Tree... Done -</example> - -<p> -Once updated there are several 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 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. - -<tag>dist-upgrade<item> -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 <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 its -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 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 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. - -<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 testing 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. - -<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 licenses, 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 superset 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. - -<p> -By default APT will automatically remove the package (.deb) files once they have been -successfully installed. To change this behavior place <tt>Dselect::clean -"prompt";</> in /etc/apt/apt.conf. - -</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>Startup - -<p> -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 <tt>apt-get check</>. -<p> -<example> -# apt-get check -Reading Package Lists... Done -Building Dependency Tree... Done -</example> - -<p> -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. - -<p> -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 -<prgn>apt-get</> will refuse to run. - -<p> -<example> -# 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) -</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. A short explanation of why the package has a dependency -problem is also included. - -<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 constraints on the order that packages are installed. In both cases -supplying the <tt>-f</> option to <prgn>apt-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 installed, 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. - -<p> -Some other reports can be generated by using the -u option to show packages -to upgrade, they are similar to the previous examples. -</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: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 -</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 download thread -and indicates the operation being performed and some useful 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 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. - -<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 begins 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 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. - -<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 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. -</sect> - -</chapt> - <!-- }}} --> - -</book> |