From 271733ee8eb9a673747bdef320af5ca8e8f18273 Mon Sep 17 00:00:00 2001 From: Guillem Jover Date: Wed, 2 Jul 2014 02:22:32 +0200 Subject: doc: Convert from DebianDoc SGML to DocBook XML --- doc/guide.sgml | 547 --------------------------------------------------------- 1 file changed, 547 deletions(-) delete mode 100644 doc/guide.sgml (limited to 'doc/guide.sgml') 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 @@ - - - -APT User's Guide - -Jason Gunthorpe jgg@debian.org -$Id: guide.sgml,v 1.7 2003/04/26 23:26:13 doogie Exp $ - - -This document provides an overview of how to use the the APT package manager. - - - -Copyright © Jason Gunthorpe, 1998. -

-"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. - -

-For more details, on Debian systems, see the file -/usr/share/common-licenses/GPL for the full license. - - - - - - -General - -

-The APT package currently contains two sections, the APT dselect -method and the apt-get command line user interface. Both provide -a way to install and remove packages as well as download new packages from -the Internet. - -Anatomy of the Package System -

-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. - -

-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. - -

-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. - -

-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. - -

-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. - -

-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. - -

-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. - - - - - - -apt-get - -

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

-The first If you are using an http proxy server you must set the -http_proxy environment variable first, see sources.list(5) thing that -should be done before using apt-get is to fetch the package lists -from the Sources so that it knows what packages are -available. This is done with apt-get update. For instance, - -

- -# apt-get update -Get http://ftp.de.debian.org/debian-non-US/ stable/binary-i386/ Packages -Get http://llug.sep.bnl.gov/debian/ testing/contrib Packages -Reading Package Lists... Done -Building Dependency Tree... Done - - -

-Once updated there are several commands that can be used: - -upgrade -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. -dselect or apt-get install can be used to force these -packages to install. - -install -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. - -dist-upgrade -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 dselect. -Once dist-upgrade has completed then dselect can be used to install -any packages that may have been left out. - -

-It is important to closely look at what dist-upgrade is going to do, its -decisions may sometimes be quite surprising. - - -

-apt-get has several command line options that are detailed in its -man page, . The most useful option is --d which does not install the fetched files. If the system has to -download a large number of package it would be undesired to start installing -them in case something goes wrong. When -d is used the downloaded -archives can be installed by simply running the command that caused them to -be downloaded again without -d. - - - - - -DSelect -

-The APT dselect method provides the complete APT system with -the dselect package selection GUI. dselect is used to -select the packages to be installed or removed and APT actually installs them. - -

-To enable the APT method you need to select [A]ccess in dselect -and then choose the APT method. You will be prompted for a set of -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. - -

- - 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]: - - -

-The 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. - -

- - 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]: - - -

-The distribution refers to the Debian version in the archive, stable -refers to the latest released version and unstable refers to the -developmental version. non-US is only available on some mirrors and -refers to packages that contain encryption technology or other things that -cannot be exported from the United States. Importing these packages into the -US is legal however. - -

- - Please give the components to get - The components are typically something like: main contrib non-free - - Components [main contrib non-free]: - - -

-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. - -

-Any number of sources can be added, the setup script will continue to -prompt until you have specified all that you want. - -

-Before starting to use dselect it is necessary to update the -available list by selecting [U]pdate from the menu. This is a superset of -apt-get update that makes the fetched information available to -dselect. [U]pdate must be performed even if apt-get update -has been run before. - -

-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. - -

-By default APT will automatically remove the package (.deb) files once they have been -successfully installed. To change this behavior place Dselect::clean -"prompt"; in /etc/apt/apt.conf. - - - - - -The Interface - -

-Both that APT dselect method and 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. - -The dselect method actually is a set of wrapper scripts -to apt-get. The method actually provides more functionality than -is present in apt-get alone. - -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. - - -Startup - -

-Before all operations except update, APT performs a number of actions to -prepare its internal state. It also does some checks of the system's state. -At any time these operations can be performed by running apt-get check. -

- -# apt-get check -Reading Package Lists... Done -Building Dependency Tree... Done - - -

-The first thing it does is read all the package files into memory. APT -uses a caching scheme so this operation will be faster the second time it -is run. If some of the package files are not found then they will be ignored -and a warning will be printed when apt-get exits. - -

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

- -# apt-get check -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) - - -

-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. - -

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

-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 -f option to apt-get will cause APT to deduce a -possible solution to the problem and then continue on. The APT dselect -method always supplies the -f option to allow for easy continuation -of failed maintainer scripts. - -

-However, if the -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. - - - -The Status Report - -

-Before proceeding 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 -f option and any other relevant -activities to the command being executed. - -The Extra Package list -

- -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 - - -

-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 install command. The listed packages are -often the result of an Auto Install. - - -The Packages to Remove -

- -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 - - -

-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 -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. - - -The New Packages list -

- -The following NEW packages will installed: - zlib1g xlib6g perl-base libgdbmg1 quake-lib gmp2 pgp-i python-base - - -

-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. - - -The Kept Back list -

- -The following packages have been kept back - compface man-db tetex-base msql libpaper svgalib1 - gs snmp arena lynx xpat2 groff xscreensaver - - -

-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 apt-get install or by using dselect -to resolve their problems. - - -Held Packages warning -

- -The following held packages will be changed: - cvs - - -

-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. - - -Final summary -

-Finally, APT will print out a summary of all the changes that will occur. - -

- -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. - - -

-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. - -

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

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

- -# 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 - - -

-The lines starting with 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 -apt-get update estimates the percent done which causes some -inaccuracies. - -

-The next section of the status line is repeated once for each download thread -and indicates the operation being performed and some useful information -about what is happening. Sometimes this section will simply read Forking -which means the OS is loading the download module. The first word after the [ -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. - -

-Inside of the single quote is an informative string indicating the progress -of the negotiation phase of the download. Typically it progresses from -Connecting to Waiting for file to Downloading or -Resuming. The final value is the number of bytes downloaded from the -remote site. Once the download begins this is represented as 102/10.2k -indicating that 102 bytes have been fetched and 10.2 kilobytes is expected. -The total size is always shown in 4 figure notation to preserve space. After -the size display is a percent meter for the file itself. -The second last element is the 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. - -

-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 -q option to remove the -status display. - - - -Dpkg - -

-APT uses dpkg for installing the archives and will switch -over to the dpkg interface once downloading is completed. -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. - - - - - - -- cgit v1.2.3-70-g09d2