Base revisions

Author: jgg
Date: 1998-07-02 02:58:12 GMT
Base revisions

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 &copy; 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>