From 24f6490f4ba3572069619d88e053db5cb07e846c Mon Sep 17 00:00:00 2001 From: Arch Librarian Date: Mon, 20 Sep 2004 17:05:19 +0000 Subject: [PATCH] * Replace SGML manpages with XML man pages from richard... Author: mdz Date: 2004-02-07 21:48:14 GMT * Replace SGML manpages with XML man pages from richard.bos@xs4all.nl (Closes: #230687) --- buildlib/defaults.mak | 1 + buildlib/environment.mak.in | 3 + configure.in | 3 + debian/changelog | 2 + doc/apt-cache.8.sgml | 412 ------------- doc/apt-cache.8.xml | 371 ++++++++++++ doc/apt-cdrom.8.sgml | 147 ----- doc/apt-cdrom.8.xml | 162 +++++ doc/apt-config.8.sgml | 105 ---- doc/apt-config.8.xml | 109 ++++ doc/apt-extracttemplates.1.sgml | 80 --- doc/apt-extracttemplates.1.xml | 77 +++ doc/apt-ftparchive.1.sgml | 571 ------------------ doc/apt-ftparchive.1.xml | 565 +++++++++++++++++ doc/apt-get.8.sgml | 512 ---------------- doc/apt-get.8.xml | 466 ++++++++++++++ doc/apt-sortpkgs.1.sgml | 73 --- doc/apt-sortpkgs.1.xml | 71 +++ doc/apt.conf.5.sgml | 415 ------------- doc/apt.conf.5.xml | 389 ++++++++++++ doc/apt.ent | 252 ++++---- ...eferences.5.sgml => apt_preferences.5.xml} | 314 +++++----- doc/makefile | 8 +- doc/sources.list.5.sgml | 199 ------ doc/sources.list.5.xml | 211 +++++++ doc/vendors.list.5.sgml | 104 ---- doc/vendors.list.5.xml | 109 ++++ 27 files changed, 2824 insertions(+), 2907 deletions(-) delete mode 100644 doc/apt-cache.8.sgml create mode 100644 doc/apt-cache.8.xml delete mode 100644 doc/apt-cdrom.8.sgml create mode 100644 doc/apt-cdrom.8.xml delete mode 100644 doc/apt-config.8.sgml create mode 100644 doc/apt-config.8.xml delete mode 100644 doc/apt-extracttemplates.1.sgml create mode 100644 doc/apt-extracttemplates.1.xml delete mode 100644 doc/apt-ftparchive.1.sgml create mode 100644 doc/apt-ftparchive.1.xml delete mode 100644 doc/apt-get.8.sgml create mode 100644 doc/apt-get.8.xml delete mode 100644 doc/apt-sortpkgs.1.sgml create mode 100644 doc/apt-sortpkgs.1.xml delete mode 100644 doc/apt.conf.5.sgml create mode 100644 doc/apt.conf.5.xml rename doc/{apt_preferences.5.sgml => apt_preferences.5.xml} (61%) delete mode 100644 doc/sources.list.5.sgml create mode 100644 doc/sources.list.5.xml delete mode 100644 doc/vendors.list.5.sgml create mode 100644 doc/vendors.list.5.xml diff --git a/buildlib/defaults.mak b/buildlib/defaults.mak index 4d05e5eaf..c3d08d9d4 100644 --- a/buildlib/defaults.mak +++ b/buildlib/defaults.mak @@ -83,6 +83,7 @@ PYTHON_H = $(BASE)/buildlib/python.mak COPY_H = $(BASE)/buildlib/copy.mak YODL_MANPAGE_H = $(BASE)/buildlib/yodl_manpage.mak SGML_MANPAGE_H = $(BASE)/buildlib/sgml_manpage.mak +XML_MANPAGE_H = $(BASE)/buildlib/xml_manpage.mak FAIL_H = $(BASE)/buildlib/fail.mak PODOMAIN_H = $(BASE)/buildlib/podomain.mak diff --git a/buildlib/environment.mak.in b/buildlib/environment.mak.in index f680d8b30..1b0e0b268 100644 --- a/buildlib/environment.mak.in +++ b/buildlib/environment.mak.in @@ -31,6 +31,9 @@ DEBIANDOC_TEXT = @DEBIANDOC_TEXT@ # SGML for the man pages DOCBOOK2MAN := @DOCBOOK2MAN@ +# XML for the man pages +XMLTO := @XMLTO@ + # Gettext settings GMSGFMT = @GMSGFMT@ XGETTEXT = @XGETTEXT@ diff --git a/configure.in b/configure.in index e35f5450f..8375564cb 100644 --- a/configure.in +++ b/configure.in @@ -160,6 +160,9 @@ AC_PATH_PROG(DEBIANDOC_TEXT,debiandoc2text) dnl Check for the SGML tools needed to build man pages AC_PATH_PROG(DOCBOOK2MAN,docbook2man) +dnl Check for the XML tools needed to build man pages +AC_PATH_PROG(XMLTO,xmlto) + dnl Check for YODL dnl AC_CHECK_PROG(YODL_MAN,yodl2man,"yes","") diff --git a/debian/changelog b/debian/changelog index 0ad0a8852..432c4c0a2 100644 --- a/debian/changelog +++ b/debian/changelog @@ -14,6 +14,8 @@ apt (0.5.22) unstable; urgency=low (Closes: #230102) * Simplified Chinese translation of message catalog from "Carlos Z.F. Liu" (Closes: #230960) + * Replace SGML manpages with XML man pages from richard.bos@xs4all.nl + (Closes: #230687) -- diff --git a/doc/apt-cache.8.sgml b/doc/apt-cache.8.sgml deleted file mode 100644 index af347ea8c..000000000 --- a/doc/apt-cache.8.sgml +++ /dev/null @@ -1,412 +0,0 @@ - - -%aptent; - -]> - - - &apt-docinfo; - - - apt-cache - 8 - - - - - apt-cache - APT package handling utility -- cache manipulator - - - - - - apt-cache - - - - - add file - gencaches - showpkg pkg - showsrc pkg - stats - dump - dumpavail - unmet - search regex - show pkg - depends pkg - rdepends pkg - pkgnames prefix - dotty pkg - policy pkgs - madison pkgs - - - - - Description</> - <para> - <command/apt-cache/ performs a variety of operations on APT's package - cache. <command/apt-cache/ does not manipulate the state of the system - but does provide operations to search and generate interesting output - from the package metadata. - - <para> - Unless the <option/-h/, or <option/--help/ option is given, one of the - commands below must be present. - - <VariableList> - <VarListEntry><Term>add <replaceable/file(s)/</Term> - <ListItem><Para> - <literal/add/ adds the named package index files to the package cache. - This is for debugging only. - </VarListEntry> - - <VarListEntry><Term>gencaches</Term> - <ListItem><Para> - <literal/gencaches/ performs the same operation as - <command/apt-get check/. It builds the source and package caches from - the sources in &sources-list; and from <filename>/var/lib/dpkg/status</>. - </VarListEntry> - - <VarListEntry><Term>showpkg <replaceable/pkg(s)/</Term> - <ListItem><Para> - <literal/showpkg/ displays information about the packages listed on the - command line. Remaining arguments are package names. The available - versions and reverse dependencies of each package listed are listed, as - well as forward dependencies for each version. Forward (normal) - dependencies are those packages upon which the package in question - depends; reverse dependencies are those packages that depend upon the - package in question. Thus, forward dependencies must be satisfied for a - package, but reverse dependencies need not be. - For instance, <command>apt-cache showpkg libreadline2</> would produce - output similar to the following: - -<informalexample><programlisting> -Package: libreadline2 -Versions: 2.1-12(/var/state/apt/lists/foo_Packages), -Reverse Depends: - libreadlineg2,libreadline2 - libreadline2-altdev,libreadline2 -Dependencies: -2.1-12 - libc5 (2 5.4.0-0) ncurses3.0 (0 (null)) -Provides: -2.1-12 - -Reverse Provides: -</programlisting></informalexample> - - <para> - Thus it may be seen that libreadline2, version 2.1-12, depends on libc5 and - ncurses3.0 which must be installed for libreadline2 to work. - In turn, libreadlineg2 and libreadline2-altdev depend on libreadline2. If - libreadline2 is installed, libc5 and ncurses3.0 (and ldso) must also be - installed; libreadlineg2 and libreadline2-altdev do not have to be - installed. For the specific meaning of the remainder of the output it - is best to consult the apt source code. - </VarListEntry> - - <VarListEntry><Term>stats</Term> - <ListItem><Para> - <literal/stats/ displays some statistics about the cache. - No further arguments are expected. Statistics reported are: - <itemizedlist> - <listitem><para> - <literal/Total package names/ is the number of package names found - in the cache. - </listitem> - - <listitem><para> - <literal/Normal packages/ is the number of regular, ordinary package - names; these are packages that bear a one-to-one correspondence between - their names and the names used by other packages for them in - dependencies. The majority of packages fall into this category. - </listitem> - - <listitem><para> - <literal/Pure virtual packages/ is the number of packages that exist - only as a virtual package name; that is, packages only "provide" the - virtual package name, and no package actually uses the name. For - instance, "mail-transport-agent" in the Debian GNU/Linux system is a - pure virtual package; several packages provide "mail-transport-agent", - but there is no package named "mail-transport-agent". - </listitem> - - <listitem><para> - <literal/Single virtual packages/ is the number of packages with only - one package providing a particular virtual package. For example, in the - Debian GNU/Linux system, "X11-text-viewer" is a virtual package, but - only one package, xless, provides "X11-text-viewer". - </listitem> - - <listitem><para> - <literal/Mixed virtual packages/ is the number of packages that either - provide a particular virtual package or have the virtual package name - as the package name. For instance, in the Debian GNU/Linux system, - "debconf" is both an actual package, and provided by the debconf-tiny - package. - </listitem> - - <listitem><para> - <literal/Missing/ is the number of package names that were referenced in - a dependency but were not provided by any package. Missing packages may - be in evidence if a full distribution is not accessed, or if a package - (real or virtual) has been dropped from the distribution. Usually they - are referenced from Conflicts statements. - </listitem> - - <listitem><para> - <literal/Total distinct/ versions is the number of package versions - found in the cache; this value is therefore at least equal to the - number of total package names. If more than one distribution (both - "stable" and "unstable", for instance), is being accessed, this value - can be considerably larger than the number of total package names. - </listitem> - - <listitem><para> - <literal/Total dependencies/ is the number of dependency relationships - claimed by all of the packages in the cache. - </listitem> - </itemizedlist> - </VarListEntry> - - <VarListEntry><Term>showsrc <replaceable/pkg(s)/</Term> - <ListItem><Para> - <literal/showsrc/ displays all the source package records that match - the given package names. All versions are shown, as well as all - records that declare the name to be a Binary. - </VarListEntry> - - <VarListEntry><Term>dump</Term> - <ListItem><Para> - <literal/dump/ shows a short listing of every package in the cache. It is - primarily for debugging. - </VarListEntry> - - <VarListEntry><Term>dumpavail</Term> - <ListItem><Para> - <literal/dumpavail/ prints out an available list to stdout. This is - suitable for use with &dpkg; and is used by the &dselect; method. - </VarListEntry> - - <VarListEntry><Term>unmet</Term> - <ListItem><Para> - <literal/unmet/ displays a summary of all unmet dependencies in the - package cache. - </VarListEntry> - - <VarListEntry><Term>show <replaceable/pkg(s)/</Term> - <ListItem><Para> - <literal/show/ performs a function similar to - <command>dpkg --print-avail</>i; it displays the package records for the - named packages. - </VarListEntry> - - <VarListEntry><Term>search <replaceable/regex [ regex ... ]/</Term> - <ListItem><Para> - <literal/search/ performs a full text search on all available package - lists for the regex pattern given. It searches the package names and the - descriptions for an occurrence of the regular expression and prints out - the package name and the short description. If <option/--full/ is given - then output identical to <literal/show/ is produced for each matched - package, and if <option/--names-only/ is given then the long description - is not searched, only the package name is. - <para> - Separate arguments can be used to specify multiple search patterns that - are and'ed together. - </VarListEntry> - - <VarListEntry><Term>depends <replaceable/pkg(s)/</Term> - <ListItem><Para> - <literal/depends/ shows a listing of each dependency a package has - and all the possible other packages that can fulfill that dependency. - </VarListEntry> - - <VarListEntry><Term>rdepends <replaceable/pkg(s)/</Term> - <ListItem><Para> - <literal/rdepends/ shows a listing of each reverse dependency a package - has. - </VarListEntry> - - <VarListEntry><Term>pkgnames <replaceable/[ prefix ]/</Term> - <ListItem><Para> - This command prints the name of each package in the system. The optional - argument is a prefix match to filter the name list. The output is suitable - for use in a shell tab complete function and the output is generated - extremely quickly. This command is best used with the - <option/--generate/ option. - </VarListEntry> - - <VarListEntry><Term>dotty <replaceable/pkg(s)/</Term> - <ListItem><Para> - <literal/dotty/ takes a list of packages on the command line and - generates output suitable for use by dotty from the - <ulink url="http://www.research.att.com/sw/tools/graphviz/">GraphViz</> - package. The result will be a set of nodes and edges representing the - relationships between the packages. By default the given packages will - trace out all dependent packages; this can produce a very large graph. - To limit the output to only the packages listed on the command line, - set the <literal>APT::Cache::GivenOnly</> option. - - <para> - The resulting nodes will have several shapes; normal packages are boxes, - pure provides are triangles, mixed provides are diamonds, - missing packages are hexagons. Orange boxes mean recursion was stopped - [leaf packages], blue lines are pre-depends, green lines are conflicts. - - <para> - Caution, dotty cannot graph larger sets of packages. - - <VarListEntry><Term>policy <replaceable/[ pkg(s) ]/</Term> - <ListItem><Para> - <literal/policy/ is ment to help debug issues relating to the - preferences file. With no arguments it will print out the - priorities of each source. Otherwise it prints out detailed information - about the priority selection of the named package. - </VarListEntry> - - <VarListEntry><Term>madison <replaceable/[ pkg(s) ]/</Term> - <ListItem><Para> - - <literal/apt-cache/'s <literal/madison/ command attempts to mimic - the output format and a subset of the functionality of the Debian - archive management tool, <literal/madison/. It displays - available versions of a package in a tabular format. Unlike the - original <literal/madison/, it can only display information for - the architecture for which APT has retrieved package lists - (<literal/APT::Architecture/). - - </VarListEntry> - </VariableList> - </RefSect1> - - <RefSect1><Title>Options</> - &apt-cmdblurb; - - <VariableList> - <VarListEntry><term><option/-p/</><term><option/--pkg-cache/</> - <ListItem><Para> - Select the file to store the package cache. The package cache is the - primary cache used by all operations. - Configuration Item: <literal/Dir::Cache::pkgcache/. - </VarListEntry> - - <VarListEntry><term><option/-s/</><term><option/--src-cache/</> - <ListItem><Para> - Select the file to store the source cache. The source is used only by - <literal/gencaches/ and it stores a parsed version of the package - information from remote sources. When building the package cache the - source cache is used to advoid reparsing all of the package files. - Configuration Item: <literal/Dir::Cache::srcpkgcache/. - </VarListEntry> - - <VarListEntry><term><option/-q/</><term><option/--quiet/</> - <ListItem><Para> - Quiet; produces output suitable for logging, omitting progress indicators. - More q's will produce more quietness up to a maximum of 2. You can also use - <option/-q=#/ to set the quietness level, overriding the configuration file. - Configuration Item: <literal/quiet/. - </VarListEntry> - - <VarListEntry><term><option/-i/</><term><option/--important/</> - <ListItem><Para> - Print only important dependencies; for use with unmet. Causes only Depends and - Pre-Depends relations to be printed. - Configuration Item: <literal/APT::Cache::Important/. - </VarListEntry> - - <VarListEntry><term><option/-f/</><term><option/--full/</> - <ListItem><Para> - Print full package records when searching. - Configuration Item: <literal/APT::Cache::ShowFull/. - </VarListEntry> - - <VarListEntry><term><option/-a/</><term><option/--all-versions/</> - <ListItem><Para> - Print full records for all available versions. This is the - default; to turn it off, use <option/--no-all-versions/. - If <option/--no-all-versions/ is specified, only the candidate version - will displayed (the one which would be selected for installation). - This option is only applicable to the <literal/show/ command. - Configuration Item: <literal/APT::Cache::AllVersions/. - </VarListEntry> - - <VarListEntry><term><option/-g/</><term><option/--generate/</> - <ListItem><Para> - Perform automatic package cache regeneration, rather than use the cache - as it is. This is the default; to turn it off, use <option/--no-generate/. - Configuration Item: <literal/APT::Cache::Generate/. - </VarListEntry> - - <VarListEntry><term><option/--names-only/</><term><option/-n/</> - <ListItem><Para> - Only search on the package names, not the long descriptions. - Configuration Item: <literal/APT::Cache::NamesOnly/. - </VarListEntry> - - <VarListEntry><term><option/--all-names/</> - <ListItem><Para> - Make <literal/pkgnames/ print all names, including virtual packages - and missing dependencies. - Configuration Item: <literal/APT::Cache::AllNames/. - </VarListEntry> - - <VarListEntry><term><option/--recurse/</> - <ListItem><Para> - Make <literal/depends/ and <literal/rdepends/ recursive so that - all packages mentioned are printed once. - Configuration Item: <literal/APT::Cache::RecurseDepends/. - </VarListEntry> - - <VarListEntry><term><option/--installed/</> - <ListItem><Para> - Limit the output of <literal/depends/ and <literal/rdepends/ to - packages which are currently installed. - Configuration Item: <literal/APT::Cache::Installed/. - </VarListEntry> - - &apt-commonoptions; - - </VariableList> - </RefSect1> - - <RefSect1><Title>Files</> - <variablelist> - <VarListEntry><term><filename>/etc/apt/sources.list</></term> - <ListItem><Para> - Locations to fetch packages from. - Configuration Item: <literal/Dir::Etc::SourceList/. - </VarListEntry> - - <VarListEntry><term><filename>&statedir;/lists/</></term> - <ListItem><Para> - Storage area for state information for each package resource specified in - &sources-list; - Configuration Item: <literal/Dir::State::Lists/. - </VarListEntry> - - <VarListEntry><term><filename>&statedir;/lists/partial/</></term> - <ListItem><Para> - Storage area for state information in transit. - Configuration Item: <literal/Dir::State::Lists/ (implicit partial). - </VarListEntry> - </variablelist> - </RefSect1> - - <RefSect1><Title>See Also</> - <para> - &apt-conf;, &sources-list;, &apt-get; - </RefSect1> - - <RefSect1><Title>Diagnostics</> - <para> - <command/apt-cache/ returns zero on normal operation, decimal 100 on error. - </RefSect1> - - &manbugs; - &manauthor; - -</refentry> diff --git a/doc/apt-cache.8.xml b/doc/apt-cache.8.xml new file mode 100644 index 000000000..f2a49f3fa --- /dev/null +++ b/doc/apt-cache.8.xml @@ -0,0 +1,371 @@ +<?xml version="1.0" encoding="utf-8" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ + +<!ENTITY % aptent SYSTEM "apt.ent"> +%aptent; + +]> + +<refentry> + &apt-docinfo; + + <refmeta> + <refentrytitle>apt-cache</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <!-- Man page title --> + <refnamediv> + <refname>apt-cache</refname> + <refpurpose>APT package handling utility -- cache manipulator</refpurpose> + </refnamediv> + + <!-- Arguments --> + <refsynopsisdiv> + <cmdsynopsis> + <command>apt-cache</command> + <arg><option>-hvsn</option></arg> + <arg><option>-o=<replaceable>config string</replaceable></option></arg> + <arg><option>-c=<replaceable>file</replaceable></option></arg> + <group choice="req"> + <arg>add <arg choice="plain" rep="repeat"><replaceable>file</replaceable></arg></arg> + <arg>gencaches</arg> + <arg>showpkg <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg> + <arg>showsrc <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg> + <arg>stats</arg> + <arg>dump</arg> + <arg>dumpavail</arg> + <arg>unmet</arg> + <arg>search <arg choice="plain"><replaceable>regex</replaceable></arg></arg> + <arg>show <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg> + <arg>depends <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg> + <arg>rdepends <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg> + <arg>pkgnames <arg choice="plain"><replaceable>prefix</replaceable></arg></arg> + <arg>dotty <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg> + <arg>policy <arg choice="plain" rep="repeat"><replaceable>pkgs</replaceable></arg></arg> + <arg>madison <arg choice="plain" rep="repeat"><replaceable>pkgs</replaceable></arg></arg> + </group> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1><title>Description + apt-cache performs a variety of operations on APT's package + cache. apt-cache does not manipulate the state of the system + but does provide operations to search and generate interesting output + from the package metadata. + + Unless the , or option is given, one of the + commands below must be present. + + + add file(s) + add adds the named package index files to the package cache. + This is for debugging only. + + + gencaches + gencaches performs the same operation as + apt-get check. It builds the source and package caches from + the sources in &sources-list; and from + /var/lib/dpkg/status. + + + showpkg pkg(s) + showpkg displays information about the packages listed on the + command line. Remaining arguments are package names. The available + versions and reverse dependencies of each package listed are listed, as + well as forward dependencies for each version. Forward (normal) + dependencies are those packages upon which the package in question + depends; reverse dependencies are those packages that depend upon the + package in question. Thus, forward dependencies must be satisfied for a + package, but reverse dependencies need not be. + For instance, apt-cache showpkg libreadline2 would produce + output similar to the following: + + +Package: libreadline2 +Versions: 2.1-12(/var/state/apt/lists/foo_Packages), +Reverse Depends: + libreadlineg2,libreadline2 + libreadline2-altdev,libreadline2 +Dependencies: +2.1-12 - libc5 (2 5.4.0-0) ncurses3.0 (0 (null)) +Provides: +2.1-12 - +Reverse Provides: + + + Thus it may be seen that libreadline2, version 2.1-12, depends on + libc5 and ncurses3.0 which must be installed for libreadline2 to work. + In turn, libreadlineg2 and libreadline2-altdev depend on libreadline2. If + libreadline2 is installed, libc5 and ncurses3.0 (and ldso) must also be + installed; libreadlineg2 and libreadline2-altdev do not have to be + installed. For the specific meaning of the remainder of the output it + is best to consult the apt source code. + + + statsstats displays some statistics about the cache. + No further arguments are expected. Statistics reported are: + + Total package names is the number of package names found + in the cache. + + + Normal packages is the number of regular, ordinary package + names; these are packages that bear a one-to-one correspondence between + their names and the names used by other packages for them in + dependencies. The majority of packages fall into this category. + + + Pure virtual packages is the number of packages that exist + only as a virtual package name; that is, packages only "provide" the + virtual package name, and no package actually uses the name. For + instance, "mail-transport-agent" in the Debian GNU/Linux system is a + pure virtual package; several packages provide "mail-transport-agent", + but there is no package named "mail-transport-agent". + + + Single virtual packages is the number of packages with only + one package providing a particular virtual package. For example, in the + Debian GNU/Linux system, "X11-text-viewer" is a virtual package, but + only one package, xless, provides "X11-text-viewer". + + + Mixed virtual packages is the number of packages that either + provide a particular virtual package or have the virtual package name + as the package name. For instance, in the Debian GNU/Linux system, + "debconf" is both an actual package, and provided by the debconf-tiny + package. + + + Missing is the number of package names that were referenced in + a dependency but were not provided by any package. Missing packages may + be in evidence if a full distribution is not accessed, or if a package + (real or virtual) has been dropped from the distribution. Usually they + are referenced from Conflicts statements. + + + Total distinct versions is the number of package versions + found in the cache; this value is therefore at least equal to the + number of total package names. If more than one distribution (both + "stable" and "unstable", for instance), is being accessed, this value + can be considerably larger than the number of total package names. + + + Total dependencies is the number of dependency relationships + claimed by all of the packages in the cache. + + + + + + showsrc pkg(s) + showsrc displays all the source package records that match + the given package names. All versions are shown, as well as all + records that declare the name to be a Binary. + + + dump + dump shows a short listing of every package in the cache. It is + primarily for debugging. + + + dumpavail + dumpavail prints out an available list to stdout. This is + suitable for use with &dpkg; and is used by the &dselect; method. + + + unmet + unmet displays a summary of all unmet dependencies in the + package cache. + + + show pkg(s) + show performs a function similar to + dpkg --print-availi; it displays the package records for the + named packages. + + + search regex [ regex ... ] + search performs a full text search on all available package + lists for the regex pattern given. It searches the package names and the + descriptions for an occurrence of the regular expression and prints out + the package name and the short description. If is given + then output identical to show is produced for each matched + package, and if is given then the long description + is not searched, only the package name is. + + Separate arguments can be used to specify multiple search patterns that + are and'ed together. + + + depends pkg(s) + depends shows a listing of each dependency a package has + and all the possible other packages that can fulfill that dependency. + + + rdepends pkg(s) + rdependsshows a listing of each reverse dependency a + package has. + + + pkgnames [ prefix ] + This command prints the name of each package in the system. The optional + argument is a prefix match to filter the name list. The output is suitable + for use in a shell tab complete function and the output is generated + extremely quickly. This command is best used with the + option. + + + dotty pkg(s) + dotty takes a list of packages on the command line and + generates output suitable for use by dotty from the + GraphViz + package. The result will be a set of nodes and edges representing the + relationships between the packages. By default the given packages will + trace out all dependent packages; this can produce a very large graph. + To limit the output to only the packages listed on the command line, + set the APT::Cache::GivenOnly option. + + The resulting nodes will have several shapes; normal packages are boxes, + pure provides are triangles, mixed provides are diamonds, + missing packages are hexagons. Orange boxes mean recursion was stopped + [leaf packages], blue lines are pre-depends, green lines are conflicts. + + Caution, dotty cannot graph larger sets of packages. + + + policy [ pkg(s) ] + policy is ment to help debug issues relating to the + preferences file. With no arguments it will print out the + priorities of each source. Otherwise it prints out detailed information + about the priority selection of the named package. + + + madison /[ pkg(s) ] + apt-cache's madison command attempts to mimic + the output format and a subset of the functionality of the Debian + archive management tool, madison. It displays + available versions of a package in a tabular format. Unlike the + original madison, it can only display information for + the architecture for which APT has retrieved package lists + (APT::Architecture). + + + + + options + &apt-cmdblurb; + + + + Select the file to store the package cache. The package cache is the + primary cache used by all operations. + Configuration Item: Dir::Cache::pkgcache. + + + + Select the file to store the source cache. The source is used only by + gencaches and it stores a parsed version of the package + information from remote sources. When building the package cache the + source cache is used to advoid reparsing all of the package files. + Configuration Item: Dir::Cache::srcpkgcache. + + + + Quiet; produces output suitable for logging, omitting progress indicators. + More q's will produce more quietness up to a maximum of 2. You can also use + to set the quietness level, overriding the configuration file. + Configuration Item: quiet. + + + + Print only important dependencies; for use with unmet. Causes only Depends and + Pre-Depends relations to be printed. + Configuration Item: APT::Cache::Important. + + + + Print full package records when searching. + Configuration Item: APT::Cache::ShowFull. + + + + Print full records for all available versions. This is the + default; to turn it off, use . + If is specified, only the candidate version + will displayed (the one which would be selected for installation). + This option is only applicable to the show command. + Configuration Item: APT::Cache::AllVersions. + + + + Perform automatic package cache regeneration, rather than use the cache + as it is. This is the default; to turn it off, use . + Configuration Item: APT::Cache::Generate. + + + + Only search on the package names, not the long descriptions. + Configuration Item: APT::Cache::NamesOnly. + + + + Make pkgnames print all names, including virtual packages + and missing dependencies. + Configuration Item: APT::Cache::AllNames. + + + + Make depends and rdepends recursive so + that all packages mentioned are printed once. + Configuration Item: APT::Cache::RecurseDepends. + + + + + Limit the output of depends and rdepends to + packages which are currently installed. + Configuration Item: APT::Cache::Installed. + + + &apt-commonoptions; + + + + + Files + + /etc/apt/sources.list + Locations to fetch packages from. + Configuration Item: Dir::Etc::SourceList. + + + &statedir;/lists/ + Storage area for state information for each package resource specified in + &sources-list; + Configuration Item: Dir::State::Lists. + + + &statedir;/lists/partial/ + Storage area for state information in transit. + Configuration Item: Dir::State::Lists (implicit partial). + + + + + See Also + &apt-conf;, &sources-list;, &apt-get; + + + + Diagnostics + apt-cache returns zero on normal operation, decimal 100 on error. + + + + &manbugs; + &manauthor; + + diff --git a/doc/apt-cdrom.8.sgml b/doc/apt-cdrom.8.sgml deleted file mode 100644 index 468146ca7..000000000 --- a/doc/apt-cdrom.8.sgml +++ /dev/null @@ -1,147 +0,0 @@ - - -%aptent; - -]> - - - &apt-docinfo; - - - apt-cdrom - 8 - - - - - apt-cdrom - APT CDROM management utility - - - - - - apt-cdrom - - - - - - add - ident - - - - - Description</> - <para> - <command/apt-cdrom/ is used to add a new CDROM to APTs list of available - sources. <command/apt-cdrom/ takes care of determining the structure of - the disc as well as correcting for several possible mis-burns and - verifying the index files. - <para> - It is necessary to use <command/apt-cdrom/ to add CDs to the APT system, - it cannot be done by hand. Furthermore each disk in a multi-cd set must be - inserted and scanned separately to account for possible mis-burns. - - <para> - Unless the <option/-h/, or <option/--help/ option is given one of the - commands below must be present. - - <VariableList> - <VarListEntry><Term>add</Term> - <ListItem><Para> - <literal/add/ is used to add a new disc to the source list. It will unmount the - CDROM device, prompt for a disk to be inserted and then procceed to - scan it and copy the index files. If the disc does not have a proper - <filename>.disk/</> directory you will be prompted for a descriptive - title. - - <para> - APT uses a CDROM ID to track which disc is currently in the drive and - maintains a database of these IDs in - <filename>&statedir;/cdroms.list</> - </VarListEntry> - - <VarListEntry><Term>ident</Term> - <ListItem><Para> - A debugging tool to report the identity of the current disc as well - as the stored file name - </VarListEntry> - </VariableList> - </RefSect1> - - <RefSect1><Title>Options</> - &apt-cmdblurb; - - <VariableList> - <VarListEntry><term><option/-d/</><term><option/--cdrom/</> - <ListItem><Para> - Mount point; specify the location to mount the cdrom. This mount - point must be listed in <filename>/etc/fstab</> and properly configured. - Configuration Item: <literal/Acquire::cdrom::mount/. - </VarListEntry> - - <VarListEntry><term><option/-r/</><term><option/--rename/</> - <ListItem><Para> - Rename a disc; change the label of a disk or override the disks - given label. This option will cause <command/apt-cdrom/ to prompt for - a new label. - Configuration Item: <literal/APT::CDROM::Rename/. - </VarListEntry> - - <VarListEntry><term><option/-m/</><term><option/--no-mount/</> - <ListItem><Para> - No mounting; prevent <command/apt-cdrom/ from mounting and unmounting - the mount point. - Configuration Item: <literal/APT::CDROM::NoMount/. - </VarListEntry> - - <VarListEntry><term><option/-f/</><term><option/--fast/</> - <ListItem><Para> - Fast Copy; Assume the package files are valid and do not check - every package. This option should be used only if - <command/apt-cdrom/ has been run on this disc before and did not detect - any errors. - Configuration Item: <literal/APT::CDROM::Fast/. - </VarListEntry> - - <VarListEntry><term><option/-a/</><term><option/--thorough/</> - <ListItem><Para> - Thorough Package Scan; This option may be needed with some old - Debian 1.1/1.2 discs that have Package files in strange places. It - takes much longer to scan the CD but will pick them all up. - </VarListEntry> - - <VarListEntry><term><option/-n/</> - <term><option/--just-print/</> - <term><option/--recon/</> - <term><option/--no-act/</> - <ListItem><Para> - No Changes; Do not change the &sources-list; file and do not - write index files. Everything is still checked however. - Configuration Item: <literal/APT::CDROM::NoAct/. - </VarListEntry> - - &apt-commonoptions; - - </VariableList> - </RefSect1> - - <RefSect1><Title>See Also</> - <para> - &apt-conf;, &apt-get;, &sources-list; - </RefSect1> - - <RefSect1><Title>Diagnostics</> - <para> - <command/apt-cdrom/ returns zero on normal operation, decimal 100 on error. - </RefSect1> - - &manbugs; - &manauthor; - -</refentry> - diff --git a/doc/apt-cdrom.8.xml b/doc/apt-cdrom.8.xml new file mode 100644 index 000000000..c8392712f --- /dev/null +++ b/doc/apt-cdrom.8.xml @@ -0,0 +1,162 @@ +<?xml version="1.0" encoding="utf-8" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ + +<!ENTITY % aptent SYSTEM "apt.ent"> +%aptent; + +]> + +<refentry> + + &apt-docinfo; + + <refmeta> + <refentrytitle>apt-cdrom</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <!-- Man page title --> + <refnamediv> + <refname>apt-cdrom</refname> + <refpurpose>APT CDROM management utility</refpurpose> + </refnamediv> + + <!-- Arguments --> + <refsynopsisdiv> + <cmdsynopsis> + <command>apt-cdrom</command> + <arg><option>-hvrmfan</option></arg> + <arg><option>-d=<replaceable>cdrom mount point</replaceable></option></arg> + <arg><option>-o=<replaceable>config string</replaceable></option></arg> + <arg><option>-c=<replaceable>file</replaceable></option></arg> + <group> + <arg>add</arg> + <arg>ident</arg> + </group> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1><title>Description + apt-cdrom is used to add a new CDROM to APTs list + of available sources. apt-cdrom takes care of + determining the structure of + the disc as well as correcting for several possible mis-burns and + verifying the index files. + + + It is necessary to use apt-cdrom to add CDs to the + APT system, + it cannot be done by hand. Furthermore each disk in a multi-cd set must be + inserted and scanned separately to account for possible mis-burns. + + + Unless the , or option is + given one of the commands below must be present. + + + add + add is used to add a new disc to the + source list. It will unmount the + CDROM device, prompt for a disk to be inserted and then procceed to + scan it and copy the index files. If the disc does not have a proper + disk directory you will be prompted for a descriptive + title. + + + APT uses a CDROM ID to track which disc is currently in the drive and + maintains a database of these IDs in + &statedir;/cdroms.list + + + + + ident + A debugging tool to report the identity of the current + disc as well as the stored file name + + + + + + + + Options + &apt-cmdblurb; + + + + Mount point; specify the location to mount the cdrom. This + mount point must be listed in /etc/fstab and + properly configured. + Configuration Item: Acquire::cdrom::mount. + + + + + + Rename a disc; change the label of a disk or override the + disks given label. This option will cause apt-cdrom to + prompt for a new label. + Configuration Item: APT::CDROM::Rename. + + + + + + No mounting; prevent apt-cdrom from + mounting and unmounting the mount point. + Configuration Item: APT::CDROM::NoMount. + + + + + + Fast Copy; Assume the package files are valid and do not + check every package. This option should be used only if + apt-cdrom has been run on this disc before and did not + detect any errors. + Configuration Item: APT::CDROM::Fast. + + + + + + Thorough Package Scan; This option may be needed with some + old Debian 1.1/1.2 discs that have Package files in strange places. It + takes much longer to scan the CD but will pick them all up. + + + + + + + + + No Changes; Do not change the &sources-list; file and do + not write index files. Everything is still checked however. + Configuration Item: APT::CDROM::NoAct. + + + + + &apt-commonoptions; + + + + + See Also + &apt-conf;, &apt-get;, &sources-list; + + + + Diagnostics + apt-cdrom returns zero on normal operation, decimal 100 on error. + + + + &manbugs; + &manauthor; + + + diff --git a/doc/apt-config.8.sgml b/doc/apt-config.8.sgml deleted file mode 100644 index 9ed16b141..000000000 --- a/doc/apt-config.8.sgml +++ /dev/null @@ -1,105 +0,0 @@ - - -%aptent; - -]> - - - &apt-docinfo; - - - apt-config - 8 - - - - - apt-config - APT Configuration Query program - - - - - - apt-config - - - - - shell - dump - - - - - Description</> - <para> - <command/apt-config/ is an internal program used by various portions of - the APT suite to provide consistent configurability. It accesses the main - configuration file <filename>/etc/apt/apt.conf</> in a manner that is - easy to use by scripted applications. - <para> - Unless the <option/-h/, or <option/--help/ option is given one of the - commands below must be present. - </para> - - <VariableList> - <VarListEntry><Term>shell</Term> - <ListItem><Para> - shell is used to access the configuration information from a shell - script. It is given pairs of arguments, the first being a shell - variable and the second the configuration value to query. As output - it lists a series of shell assignments commands for each present value. - In a shell script it should be used like: - </para> - -<informalexample><programlisting> -OPTS="-f" -RES=`apt-config shell OPTS MyApp::Options` -eval $RES -</programlisting></informalexample> - - <para> - This will set the shell environment variable $OPTS to the value of - MyApp::Options with a default of <option/-f/. - - <para> - The configuration item may be postfixed with a /[fdbi]. f returns file - names, d returns directories, b returns true or false and i returns an - integer. Each of the returns is normalized and verified internally. - </VarListEntry> - - <VarListEntry><Term>dump</Term> - <ListItem><Para> - Just show the contents of the configuration space. - </VarListEntry> - - </VariableList> - </RefSect1> - - <RefSect1><Title>Options</> - &apt-cmdblurb; - - <VariableList> - - &apt-commonoptions; - - </VariableList> - </RefSect1> - - <RefSect1><Title>See Also</> - <para> - &apt-conf; - </RefSect1> - - <RefSect1><Title>Diagnostics</> - <para> - <command/apt-config/ returns zero on normal operation, decimal 100 on error. - </RefSect1> - - &manbugs; - &manauthor; - -</refentry> diff --git a/doc/apt-config.8.xml b/doc/apt-config.8.xml new file mode 100644 index 000000000..ae29ddb66 --- /dev/null +++ b/doc/apt-config.8.xml @@ -0,0 +1,109 @@ +<?xml version="1.0" encoding="utf-8" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ + +<!ENTITY % aptent SYSTEM "apt.ent"> +%aptent; + +]> + +<refentry> + &apt-docinfo; + + <refmeta> + <refentrytitle>apt-config</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <!-- Man page title --> + <refnamediv> + <refname>apt-config</refname> + <refpurpose>APT Configuration Query program</refpurpose> + </refnamediv> + + <!-- Arguments --> + <refsynopsisdiv> + <cmdsynopsis> + <command>apt-config</command> + <arg><option>-hv</option></arg> + <arg><option>-o=<replaceable>config string</replaceable></option></arg> + <arg><option>-c=<replaceable>file</replaceable></option></arg> + <group choice="req"> + <arg>shell</arg> + <arg>dump</arg> + </group> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1><title>Description + apt-config is an internal program used by various + portions of the APT suite to provide consistent configurability. It accesses + the main configuration file /etc/apt/apt.conf in a + manner that is easy to use by scripted applications. + + Unless the , or option is + given one of the commands below must be present. + + + + shell + + shell is used to access the configuration information from a shell + script. It is given pairs of arguments, the first being a shell + variable and the second the configuration value to query. As output + it lists a series of shell assignments commands for each present value. + In a shell script it should be used like: + + + +OPTS="-f" +RES=`apt-config shell OPTS MyApp::options` +eval $RES + + + This will set the shell environment variable $OPTS to the value of + MyApp::options with a default of . + + + The configuration item may be postfixed with a /[fdbi]. f returns + file names, d returns directories, b returns true or false and i returns + an integer. Each of the returns is normalized and verified + internally. + + + + dump + + Just show the contents of the configuration space. + + + + + + + options + &apt-cmdblurb; + + + + &apt-commonoptions; + + + + + See Also + + &apt-conf; + + + + Diagnostics + apt-config returns zero on normal operation, decimal 100 on error. + + + + &manbugs; + &manauthor; + + + diff --git a/doc/apt-extracttemplates.1.sgml b/doc/apt-extracttemplates.1.sgml deleted file mode 100644 index d566d9611..000000000 --- a/doc/apt-extracttemplates.1.sgml +++ /dev/null @@ -1,80 +0,0 @@ - - -%aptent; - -]> - - - &apt-docinfo; - - - apt-extracttemplates - 1 - - - - - apt-extracttemplates - Utility to extract DebConf config and templates from Debian packages - - - - - - apt-extracttemplates - - - file - - - - Description</> - <para> - <command/apt-extracttemplates/ will take one or more Debian package files - as input and write out (to a temporary directory) all associated config - scripts and template files. For each passed in package that contains - config scripts and templates, one line of output will be generated - in the format: - <para> - package version template-file config-script - <para> - template-file and config-script are written to the temporary directory - specified by the -t or --tempdir (<literal>APT::ExtractTemplates::TempDir</>) - directory, with filenames of the form <filename>package.template.XXXX</> and - <filename>package.config.XXXX</> - </RefSect1> - - <RefSect1><Title>Options</> - &apt-cmdblurb; - - <VariableList> - <VarListEntry><term><option/-t/</><term><option/--tempdir/</> - <ListItem><Para> - Temporary directory in which to write extracted debconf template files - and config scripts - Configuration Item: <literal/APT::ExtractTemplates::TempDir/. - </VarListEntry> - - &apt-commonoptions; - - </VariableList> - - - </RefSect1> - - <RefSect1><Title>See Also</> - <para> - &apt-conf; - </RefSect1> - - <RefSect1><Title>Diagnostics</> - <para> - <command/apt-extracttemplates/ returns zero on normal operation, decimal 100 on error. - </RefSect1> - - &manbugs; - &manauthor; - -</refentry> diff --git a/doc/apt-extracttemplates.1.xml b/doc/apt-extracttemplates.1.xml new file mode 100644 index 000000000..e0af9cf46 --- /dev/null +++ b/doc/apt-extracttemplates.1.xml @@ -0,0 +1,77 @@ +<?xml version="1.0" encoding="utf-8" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ + +<!ENTITY % aptent SYSTEM "apt.ent"> +%aptent; + +]> + +<refentry> + &apt-docinfo; + + <refmeta> + <refentrytitle>apt-extracttemplates</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <!-- Man page title --> + <refnamediv> + <refname>apt-extracttemplates</refname> + <refpurpose>Utility to extract DebConf config and templates from Debian packages</refpurpose> + </refnamediv> + + <!-- Arguments --> + <refsynopsisdiv> + <cmdsynopsis> + <command>apt-extracttemplates</command> + <arg><option>-hv</option></arg> + <arg><option>-t=<replaceable>temporary directory</replaceable></option></arg> + <arg choice="plain" rep="repeat"><replaceable>file</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1><title>Description + apt-extracttemplates will take one or more Debian package files + as input and write out (to a temporary directory) all associated config + scripts and template files. For each passed in package that contains + config scripts and templates, one line of output will be generated + in the format: + package version template-file config-script + template-file and config-script are written to the temporary directory + specified by the -t or --tempdir (APT::ExtractTemplates::TempDir) + directory, with filenames of the form package.template.XXXX and + package.config.XXXX + + + options + &apt-cmdblurb; + + + + + Temporary directory in which to write extracted debconf template files + and config scripts + Configuration Item: APT::ExtractTemplates::TempDir + + + &apt-commonoptions; + + + + + + + See Also + &apt-conf; + + + Diagnostics + + apt-extracttemplates returns zero on normal operation, decimal 100 on error. + + + &manbugs; + &manauthor; + + diff --git a/doc/apt-ftparchive.1.sgml b/doc/apt-ftparchive.1.sgml deleted file mode 100644 index 220c4a96c..000000000 --- a/doc/apt-ftparchive.1.sgml +++ /dev/null @@ -1,571 +0,0 @@ - - -%aptent; - -]> - - - &apt-docinfo; - - - apt-ftparchive - 1 - - - - - apt-ftparchive - Utility to generate index files - - - - - - apt-ftparchive - - - - - - - - - packagespathoverridepathprefix - sourcespathoverridepathprefix - contents path - release path - generate config-file section - clean config-file - - - - - Description</> - <para> - <command/apt-ftparchive/ is the command line tool that generates the index - files that APT uses to access a distribution source. The index files should - be generated on the origin site based on the content of that site. - - <para> - <command/apt-ftparchive/ is a superset of the &dpkg-scanpackages; program, - incorporating its entire functionality via the <literal/packages/ command. - It also contains a contents file generator, <literal/contents/, and an - elaborate means to 'script' the generation process for a complete - archive. - - <para> - Internally <command/apt-ftparchive/ can make use of binary databases to - cache the contents of a .deb file and it does not rely on any external - programs aside from &gzip;. When doing a full generate it automatically - performs file-change checks and builds the desired compressed output files. - - <para> - Unless the <option/-h/, or <option/--help/ option is given one of the - commands below must be present. - - <VariableList> - <VarListEntry><term>packages</term> - <ListItem><Para> - The packages command generates a package file from a directory tree. It - takes the given directory and recursively searches it for .deb files, - emitting a package record to stdout for each. This command is - approximately equivalent to &dpkg-scanpackages;. - <para> - The option <option/--db/ can be used to specify a binary caching DB. - </VarListEntry> - - <VarListEntry><term>sources</term> - <ListItem><Para> - The <literal/sources/ command generates a source index file from a directory tree. - It takes the given directory and recursively searches it for .dsc files, - emitting a source record to stdout for each. This command is approximately - equivalent to &dpkg-scansources;. - <para> - If an override file is specified then a source override file will be - looked for with an extension of .src. The --source-override option can be - used to change the source override file that will be used. - </VarListEntry> - - <VarListEntry><term>contents</term> - <ListItem><Para> - The <literal/contents/ command generates a contents file from a directory tree. It - takes the given directory and recursively searches it for .deb files, - and reads the file list from each file. It then sorts and writes to stdout - the list of files matched to packages. Directories are not written to - the output. If multiple packages own the same file then each package is - separated by a comma in the output. - <para> - The option <option/--db/ can be used to specify a binary caching DB. - </VarListEntry> - - <VarListEntry><term>release</term> - <ListItem><Para> - The <literal/release/ command generates a Release file from a - directory tree. It recursively searches the given directory for - Packages, Packages.gz, Packages.bz2, Sources, Sources.gz, - Sources.bz2, Release and md5sum.txt files. It then writes to - stdout a Release file containing an MD5 digest and SHA1 digest - for each file. - <para> - Values for the additional metadata fields in the Release file are - taken from the corresponding variables under - <literal/APT::FTPArchive::Release/, - e.g. <literal/APT::FTPArchive::Release::Origin/. The supported fields - are: <literal/Origin/, <literal/Label/, <literal/Suite/, - <literal/Version/, <literal/Codename/, <literal/Date/, - <literal/Architectures/, <literal/Components/, <literal/Description/. - - </VarListEntry> - - <VarListEntry><term>generate</term> - <ListItem><Para> - The <literal/generate/ command is designed to be runnable from a cron script and - builds indexes according to the given config file. The config language - provides a flexible means of specifying which index files are built from - which directories, as well as providing a simple means of maintaining the - required settings. - </VarListEntry> - - <VarListEntry><term>clean</term> - <ListItem><Para> - The <literal/clean/ command tidies the databases used by the given - configuration file by removing any records that are no longer necessary. - </VarListEntry> - </VariableList> - - </RefSect1> - - <RefSect1><Title>The Generate Configuration</> - <para> - The <literal/generate/ command uses a configuration file to describe the - archives that are going to be generated. It follows the typical ISC - configuration format as seen in ISC tools like bind 8 and dhcpd. - &apt-conf; contains a description of the syntax. Note that the generate - configuration is parsed in sectional manner, but &apt-conf; is parsed in a - tree manner. This only effects how the scope tag is handled. - - <para> - The generate configuration has 4 separate sections, each described below. - - <refsect2><title>Dir Section</> - <Para> - The <literal/Dir/ section defines the standard directories needed to - locate the files required during the generation process. These - directories are prepended to certain relative paths defined in later - sections to produce a complete an absolute path. - <VariableList> - <VarListEntry><term>ArchiveDir</term> - <ListItem><Para> - Specifies the root of the FTP archive, in a standard - Debian configuration this is the directory that contains the - <filename/ls-LR/, and dist nodes. - </VarListEntry> - - <VarListEntry><term>OverrideDir</term> - <ListItem><Para> - Specifies the location of the override files. - </VarListEntry> - - <VarListEntry><term>CacheDir</term> - <ListItem><Para> - Specifies the location of the cache files - </VarListEntry> - - <VarListEntry><term>FileListDir</term> - <ListItem><Para> - Specifies the location of the file list files, - if the <literal/FileList/ setting is used below. - </VarListEntry> - </VariableList> - </refsect2> - - <refsect2><title>Default Section</> - <para> - The <literal/Default/ section specifies default values, and settings - that control the operation of the generator. Other sections may override - these defaults with a per-section setting. - <VariableList> - <VarListEntry><term>Packages::Compress</term> - <ListItem><Para> - Sets the default compression schemes to use - for the Package index files. It is a string that contains a space - separated list of at least one of: '.' (no compression), 'gzip' and - 'bzip2'. The default for all compression schemes is '. gzip'. - </VarListEntry> - - <VarListEntry><term>Packages::Extensions</term> - <ListItem><Para> - Sets the default list of file extensions that are package files. - This defaults to '.deb'. - </VarListEntry> - - <VarListEntry><term>Sources::Compress</term> - <ListItem><Para> - This is similar to <literal/Packages::Compress/ - except that it controls the compression for the Sources files. - </VarListEntry> - - <VarListEntry><term>Sources::Extensions</term> - <ListItem><Para> - Sets the default list of file extensions that are source files. - This defaults to '.dsc'. - </VarListEntry> - - <VarListEntry><term>Contents::Compress</term> - <ListItem><Para> - This is similar to <literal/Packages::Compress/ - except that it controls the compression for the Contents files. - </VarListEntry> - - <VarListEntry><term>DeLinkLimit</term> - <ListItem><Para> - Specifies the number of kilobytes to delink (and - replace with hard links) per run. This is used in conjunction with the - per-section <literal/External-Links/ setting. - </VarListEntry> - - <VarListEntry><term>FileMode</term> - <ListItem><Para> - Specifies the mode of all created index files. It - defaults to 0644. All index files are set to this mode with no regard - to the umask. - </VarListEntry> - </VariableList> - </refsect2> - - <refsect2><title>TreeDefault Section</> - <para> - Sets defaults specific to <literal/Tree/ sections. All of these - variables are substitution variables and have the strings $(DIST), - $(SECTION) and $(ARCH) replaced with their respective values. - - <VariableList> - <VarListEntry><term>MaxContentsChange</term> - <ListItem><Para> - Sets the number of kilobytes of contents - files that are generated each day. The contents files are round-robined - so that over several days they will all be rebuilt. - </VarListEntry> - - <VarListEntry><term>ContentsAge</term> - <ListItem><Para> - Controls the number of days a contents file is allowed - to be checked without changing. If this limit is passed the mtime of the - contents file is updated. This case can occur if the package file is - changed in such a way that does not result in a new contents file - [override edit for instance]. A hold off is allowed in hopes that new - .debs will be installed, requiring a new file anyhow. The default is 10, - the units are in days. - </VarListEntry> - - <VarListEntry><term>Directory</term> - <ListItem><Para> - Sets the top of the .deb directory tree. Defaults to - <filename>$(DIST)/$(SECTION)/binary-$(ARCH)/</> - </VarListEntry> - - <VarListEntry><term>SrcDirectory</term> - <ListItem><Para> - Sets the top of the source package directory tree. Defaults to - <filename>$(DIST)/$(SECTION)/source/</> - </VarListEntry> - - <VarListEntry><term>Packages</term> - <ListItem><Para> - Sets the output Packages file. Defaults to - <filename>$(DIST)/$(SECTION)/binary-$(ARCH)/Packages</> - </VarListEntry> - - <VarListEntry><term>Sources</term> - <ListItem><Para> - Sets the output Packages file. Defaults to - <filename>$(DIST)/$(SECTION)/source/Sources</> - </VarListEntry> - - <VarListEntry><term>InternalPrefix</term> - <ListItem><Para> - Sets the path prefix that causes a symlink to be - considered an internal link instead of an external link. Defaults to - <filename>$(DIST)/$(SECTION)/</> - </VarListEntry> - - <VarListEntry><term>Contents</term> - <ListItem><Para> - Sets the output Contents file. Defaults to - <filename>$(DIST)/Contents-$(ARCH)</>. If this setting causes multiple - Packages files to map onto a single Contents file (such as the default) - then <command/apt-ftparchive/ will integrate those package files - together automatically. - </VarListEntry> - - <VarListEntry><term>Contents::Header</term> - <ListItem><Para> - Sets header file to prepend to the contents output. - </VarListEntry> - - <VarListEntry><term>BinCacheDB</term> - <ListItem><Para> - Sets the binary cache database to use for this - section. Multiple sections can share the same database. - </VarListEntry> - - <VarListEntry><term>FileList</term> - <ListItem><Para> - Specifies that instead of walking the directory tree, - <command/apt-ftparchive/ should read the list of files from the given - file. Relative files names are prefixed with the archive directory. - </VarListEntry> - - <VarListEntry><term>SourceFileList</term> - <ListItem><Para> - Specifies that instead of walking the directory tree, - <command/apt-ftparchive/ should read the list of files from the given - file. Relative files names are prefixed with the archive directory. - This is used when processing source indexs. - </VarListEntry> - </VariableList> - </refsect2> - - <refsect2><title>Tree Section</> - <para> - The <literal/Tree/ section defines a standard Debian file tree which - consists of a base directory, then multiple sections in that base - directory and finally multiple Architectures in each section. The exact - pathing used is defined by the <literal/Directory/ substitution variable. - <para> - The <literal/Tree/ section takes a scope tag which sets the - <literal/$(DIST)/ variable and defines the root of the tree - (the path is prefixed by <literal/ArchiveDir/). - Typically this is a setting such as <filename>dists/woody</>. - <para> - All of the settings defined in the <literal/TreeDefault/ section can be - use in a <literal/Tree/ section as well as three new variables. - <para> - When processing a <literal/Tree/ section <command/apt-ftparchive/ - performs an operation similar to: -<informalexample><programlisting> -for i in Sections do - for j in Architectures do - Generate for DIST=scope SECTION=i ARCH=j -</programlisting></informalexample> - - <VariableList> - <VarListEntry><term>Sections</term> - <ListItem><Para> - This is a space separated list of sections which appear - under the distribution, typically this is something like - <literal/main contrib non-free/. - </VarListEntry> - - <VarListEntry><term>Architectures</term> - <ListItem><Para> - This is a space separated list of all the - architectures that appear under search section. The special architecture - 'source' is used to indicate that this tree has a source archive. - </VarListEntry> - - <VarListEntry><term>BinOverride</term> - <ListItem><Para> - Sets the binary override file. The override file - contains section, priority and maintainer address information. - </VarListEntry> - - <VarListEntry><term>SrcOverride</term> - <ListItem><Para> - Sets the source override file. The override file - contains section information. - </VarListEntry> - - <VarListEntry><term>ExtraOverride</term> - <ListItem><Para> - Sets the binary extra override file. - </VarListEntry> - - <VarListEntry><term>SrcExtraOverride</term> - <ListItem><Para> - Sets the source extra override file. - </VarListEntry> - </VariableList> - </refsect2> - - <refsect2><title>BinDirectory Section</> - <para> - The <literal/bindirectory/ section defines a binary directory tree - with no special structure. The scope tag specifies the location of - the binary directory and the settings are similar to the <literal/Tree/ - section with no substitution variables or - <literal>Section</><literal>Architecture</> settings. - <VariableList> - <VarListEntry><term>Packages</term> - <ListItem><Para> - Sets the Packages file output. - </VarListEntry> - - <VarListEntry><term>SrcPackages</term> - <ListItem><Para> - Sets the Sources file output. At least one of - <literal/Packages/ or <literal/SrcPackages/ is required. - </VarListEntry> - - <VarListEntry><term>Contents</term> - <ListItem><Para> - Sets the Contents file output. (Optional) - </VarListEntry> - - <VarListEntry><term>BinOverride</term> - <ListItem><Para> - Sets the binary override file. - </VarListEntry> - - <VarListEntry><term>SrcOverride</term> - <ListItem><Para> - Sets the source override file. - </VarListEntry> - - <VarListEntry><term>ExtraOverride</term> - <ListItem><Para> - Sets the binary extra override file. - </VarListEntry> - - <VarListEntry><term>SrcExtraOverride</term> - <ListItem><Para> - Sets the source extra override file. - </VarListEntry> - - <VarListEntry><term>BinCacheDB</term> - <ListItem><Para> - Sets the cache DB. - </VarListEntry> - - <VarListEntry><term>PathPrefix</term> - <ListItem><Para> - Appends a path to all the output paths. - </VarListEntry> - - <VarListEntry><term>FileList, SourceFileList</term> - <ListItem><Para> - Specifies the file list file. - </VarListEntry> - </VariableList> - </refsect2> - </RefSect1> - - <RefSect1><Title>The Binary Override File</> - <para> - The binary override file is fully compatible with &dpkg-scanpackages;. It - contains 4 fields separated by spaces. The first field is the package name, - the second is the priority to force that package to, the third is the - the section to force that package to and the final field is the maintainer - permutation field. - <para> - The general form of the maintainer field is: - <literallayout>old [// oldn]* => new</literallayout> - or simply, - <literallayout>new</literallayout> - The first form allows a double-slash separated list of old email addresses - to be specified. If any of those are found then new is substituted for the - maintainer field. The second form unconditionally substitutes the - maintainer field. - </RefSect1> - - <RefSect1><title>The Source Override File</> - <para> - The source override file is fully compatible with &dpkg-scansources;. It - contains 2 fields separated by spaces. The first fields is the source - package name, the second is the section to assign it. - </RefSect1> - - <RefSect1><title>The Extra Override File</> - <para> - The extra override file allows any arbitrary tag to be added or replaced - in the output. It has 3 columns, the first is the package, the second is - the tag and the remainder of the line is the new value. - </RefSect1> - - <RefSect1><Title>Options</> - &apt-cmdblurb; - - <VariableList> - <VarListEntry><term><option/--md5/</> - <ListItem><Para> - Generate MD5 sums. This defaults to on, when turned off the generated - index files will not have MD5Sum fields where possible. - Configuration Item: <literal/APT::FTPArchive::MD5/. - </VarListEntry> - - <VarListEntry><term><option/-d/</><term><option/--db/</> - <ListItem><Para> - Use a binary caching DB. This has no effect on the generate command. - Configuration Item: <literal/APT::FTPArchive::DB/. - </VarListEntry> - - <VarListEntry><term><option/-q/</><term><option/--quiet/</> - <ListItem><Para> - Quiet; produces output suitable for logging, omitting progress indicators. - More q's will produce more quiet up to a maximum of 2. You can also use - <option/-q=#/ to set the quiet level, overriding the configuration file. - Configuration Item: <literal/quiet/. - </VarListEntry> - - <VarListEntry><term><option/--delink/</> - <ListItem><Para> - Perform Delinking. If the <literal/External-Links/ setting is used then - this option actually enables delinking of the files. It defaults to on and - can be turned off with <option/--no-delink/. - Configuration Item: <literal/APT::FTPArchive::DeLinkAct/. - </VarListEntry> - - <VarListEntry><term><option/--contents/</> - <ListItem><Para> - Perform contents generation. When this option is set and package indexes - are being generated with a cache DB then the file listing will also be - extracted and stored in the DB for later use. When using the generate - command this option also allows the creation of any Contents files. The - default is on. - Configuration Item: <literal/APT::FTPArchive::Contents/. - </VarListEntry> - - <VarListEntry><term><option/-s/</><term><option/--source-override/</> - <ListItem><Para> - Select the source override file to use with the <literal/sources/ command. - Configuration Item: <literal/APT::FTPArchive::SourceOverride/. - </VarListEntry> - - <VarListEntry><term><option/--readonly/</> - <ListItem><Para> - Make the caching databases read only. - Configuration Item: <literal/APT::FTPArchive::ReadOnlyDB/. - </VarListEntry> - - &apt-commonoptions; - - </VariableList> - </RefSect1> - -<RefSect1><Title>Examples</> - -<para>To create a compressed Packages file for a directory containing -binary packages (.deb): - -<programlisting -<command/apt-ftparchive/ packages <replaceable/directory/ | <command/gzip/ > <filename/Packages.gz/ -</programlisting> - -</RefSect1> - - <RefSect1><Title>See Also</> - <para> - &apt-conf; - </RefSect1> - - <RefSect1><Title>Diagnostics</> - <para> - <command/apt-ftparchive/ returns zero on normal operation, decimal 100 on error. - </RefSect1> - - &manbugs; - &manauthor; - -</refentry> diff --git a/doc/apt-ftparchive.1.xml b/doc/apt-ftparchive.1.xml new file mode 100644 index 000000000..e08444fc6 --- /dev/null +++ b/doc/apt-ftparchive.1.xml @@ -0,0 +1,565 @@ +<?xml version="1.0" encoding="utf-8" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ + +<!ENTITY % aptent SYSTEM "apt.ent"> +%aptent; + +]> + +<refentry> + &apt-docinfo; + + <refmeta> + <refentrytitle>apt-ftparchive</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <!-- Man page title --> + <refnamediv> + <refname>apt-ftparchive</refname> + <refpurpose>Utility to generate index files</refpurpose> + </refnamediv> + + <!-- Arguments --> + <refsynopsisdiv> + <cmdsynopsis> + <command>apt-ftparchive</command> + <arg><option>-hvdsq</option></arg> + <arg><option>--md5</option></arg> + <arg><option>--delink</option></arg> + <arg><option>--readonly</option></arg> + <arg><option>--contents</option></arg> + <arg><option>-o=<replaceable>config string</replaceable></option></arg> + <arg><option>-c=<replaceable>file</replaceable></option></arg> + <group choice="req"> + <arg>packages<arg choice="plain" rep="repeat"><replaceable>path</replaceable></arg><arg><replaceable>override</replaceable><arg><replaceable>pathprefix</replaceable></arg></arg></arg> + <arg>sources<arg choice="plain" rep="repeat"><replaceable>path</replaceable></arg><arg><replaceable>override</replaceable><arg><replaceable>pathprefix</replaceable></arg></arg></arg> + <arg>contents <arg choice="plain"><replaceable>path</replaceable></arg></arg> + <arg>release <arg choice="plain"><replaceable>path</replaceable></arg></arg> + <arg>generate <arg choice="plain"><replaceable>config-file</replaceable></arg> <arg choice="plain" rep="repeat"><replaceable>section</replaceable></arg></arg> + <arg>clean <arg choice="plain"><replaceable>config-file</replaceable></arg></arg> + </group> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1><title>Description + apt-ftparchive is the command line tool that generates the index + files that APT uses to access a distribution source. The index files should + be generated on the origin site based on the content of that site. + + apt-ftparchive is a superset of the &dpkg-scanpackages; program, + incorporating its entire functionality via the packages command. + It also contains a contents file generator, contents, and an + elaborate means to 'script' the generation process for a complete + archive. + + Internally apt-ftparchive can make use of binary databases to + cache the contents of a .deb file and it does not rely on any external + programs aside from &gzip;. When doing a full generate it automatically + performs file-change checks and builds the desired compressed output files. + + Unless the , or option is given one of the + commands below must be present. + + + packages + + The packages command generates a package file from a directory tree. It + takes the given directory and recursively searches it for .deb files, + emitting a package record to stdout for each. This command is + approximately equivalent to &dpkg-scanpackages;. + + The option can be used to specify a binary caching DB. + + + sources + + The sources command generates a source index file from a directory tree. + It takes the given directory and recursively searches it for .dsc files, + emitting a source record to stdout for each. This command is approximately + equivalent to &dpkg-scansources;. + + If an override file is specified then a source override file will be + looked for with an extension of .src. The --source-override option can be + used to change the source override file that will be used. + + + contents + + The contents command generates a contents file from a directory tree. It + takes the given directory and recursively searches it for .deb files, + and reads the file list from each file. It then sorts and writes to stdout + the list of files matched to packages. Directories are not written to + the output. If multiple packages own the same file then each package is + separated by a comma in the output. + + The option can be used to specify a binary caching DB. + + + release + + The release command generates a Release file from a + directory tree. It recursively searches the given directory for + Packages, Packages.gz, Packages.bz2, Sources, Sources.gz, + Sources.bz2, Release and md5sum.txt files. It then writes to + stdout a Release file containing an MD5 digest and SHA1 digest + for each file. + + Values for the additional metadata fields in the Release file are + taken from the corresponding variables under + APT::FTPArchive::Release, + e.g. APT::FTPArchive::Release::Origin. The supported fields + are: Origin, Label, Suite, + Version, Codename, Date, + Architectures, Components, Description. + + + + generate + + The generate command is designed to be runnable from a cron script and + builds indexes according to the given config file. The config language + provides a flexible means of specifying which index files are built from + which directories, as well as providing a simple means of maintaining the + required settings. + + + clean + + The clean command tidies the databases used by the given + configuration file by removing any records that are no longer necessary. + + + + + The Generate Configuration + + The generate command uses a configuration file to describe the + archives that are going to be generated. It follows the typical ISC + configuration format as seen in ISC tools like bind 8 and dhcpd. + &apt-conf; contains a description of the syntax. Note that the generate + configuration is parsed in sectional manner, but &apt-conf; is parsed in a + tree manner. This only effects how the scope tag is handled. + + + The generate configuration has 4 separate sections, each described below. + + Dir Section + + The Dir section defines the standard directories needed to + locate the files required during the generation process. These + directories are prepended to certain relative paths defined in later + sections to produce a complete an absolute path. + + ArchiveDir + + Specifies the root of the FTP archive, in a standard + Debian configuration this is the directory that contains the + ls-LR and dist nodes. + + + OverrideDir + + Specifies the location of the override files. + + + CacheDir + + Specifies the location of the cache files + + + FileListDir + + Specifies the location of the file list files, + if the FileList setting is used below. + + + + + Default Section + + The Default section specifies default values, and settings + that control the operation of the generator. Other sections may override + these defaults with a per-section setting. + + Packages::Compress + + Sets the default compression schemes to use + for the Package index files. It is a string that contains a space + separated list of at least one of: '.' (no compression), 'gzip' and + 'bzip2'. The default for all compression schemes is '. gzip'. + + + Packages::Extensions + + Sets the default list of file extensions that are package files. + This defaults to '.deb'. + + + Sources::Compress + + This is similar to Packages::Compress + except that it controls the compression for the Sources files. + + + Sources::Extensions + + Sets the default list of file extensions that are source files. + This defaults to '.dsc'. + + + Contents::Compress + + This is similar to Packages::Compress + except that it controls the compression for the Contents files. + + + DeLinkLimit + + Specifies the number of kilobytes to delink (and + replace with hard links) per run. This is used in conjunction with the + per-section External-Links setting. + + + FileMode + + Specifies the mode of all created index files. It + defaults to 0644. All index files are set to this mode with no regard + to the umask. + + + + + TreeDefault Section + + Sets defaults specific to Tree sections. All of these + variables are substitution variables and have the strings $(DIST), + $(SECTION) and $(ARCH) replaced with their respective values. + + + MaxContentsChange + + Sets the number of kilobytes of contents + files that are generated each day. The contents files are round-robined + so that over several days they will all be rebuilt. + + + ContentsAge + + Controls the number of days a contents file is allowed + to be checked without changing. If this limit is passed the mtime of the + contents file is updated. This case can occur if the package file is + changed in such a way that does not result in a new contents file + [override edit for instance]. A hold off is allowed in hopes that new + .debs will be installed, requiring a new file anyhow. The default is 10, + the units are in days. + + + Directory + + Sets the top of the .deb directory tree. Defaults to + $(DIST)/$(SECTION)/binary-$(ARCH)/ + + + SrcDirectory + + Sets the top of the source package directory tree. Defaults to + $(DIST)/$(SECTION)/source/ + + + Packages + + Sets the output Packages file. Defaults to + $(DIST)/$(SECTION)/binary-$(ARCH)/Packages + + + Sources + + Sets the output Packages file. Defaults to + $(DIST)/$(SECTION)/source/Sources + + + InternalPrefix + + Sets the path prefix that causes a symlink to be + considered an internal link instead of an external link. Defaults to + $(DIST)/$(SECTION)/ + + + Contents + + Sets the output Contents file. Defaults to + $(DIST)/Contents-$(ARCH). If this setting causes multiple + Packages files to map onto a single Contents file (such as the default) + then apt-ftparchive will integrate those package files + together automatically. + + + Contents::Header + + Sets header file to prepend to the contents output. + + + BinCacheDB + + Sets the binary cache database to use for this + section. Multiple sections can share the same database. + + + FileList + + Specifies that instead of walking the directory tree, + apt-ftparchive should read the list of files from the given + file. Relative files names are prefixed with the archive directory. + + + SourceFileList + + Specifies that instead of walking the directory tree, + apt-ftparchive should read the list of files from the given + file. Relative files names are prefixed with the archive directory. + This is used when processing source indexs. + + + + + Tree Section + + The Tree section defines a standard Debian file tree which + consists of a base directory, then multiple sections in that base + directory and finally multiple Architectures in each section. The exact + pathing used is defined by the Directory substitution variable. + + The Tree section takes a scope tag which sets the + $(DIST) variable and defines the root of the tree + (the path is prefixed by ArchiveDir). + Typically this is a setting such as dists/woody. + + All of the settings defined in the TreeDefault section can be + use in a Tree section as well as three new variables. + + When processing a Tree section apt-ftparchive + performs an operation similar to: + +for i in Sections do + for j in Architectures do + Generate for DIST=scope SECTION=i ARCH=j + + + + Sections + + This is a space separated list of sections which appear + under the distribution, typically this is something like + main contrib non-free + + + Architectures + + This is a space separated list of all the + architectures that appear under search section. The special architecture + 'source' is used to indicate that this tree has a source archive. + + + BinOverride + + Sets the binary override file. The override file + contains section, priority and maintainer address information. + + + SrcOverride + + Sets the source override file. The override file + contains section information. + + + ExtraOverride + + Sets the binary extra override file. + + + SrcExtraOverride + + Sets the source extra override file. + + + + + BinDirectory Section + + The bindirectory section defines a binary directory tree + with no special structure. The scope tag specifies the location of + the binary directory and the settings are similar to the Tree + section with no substitution variables or + SectionArchitecture settings. + + Packages + + Sets the Packages file output. + + + SrcPackages + + Sets the Sources file output. At least one of + Packages or SrcPackages is required. + + + Contents + + Sets the Contents file output. (optional) + + + BinOverride + + Sets the binary override file. + + + SrcOverride + + Sets the source override file. + + + ExtraOverride + + Sets the binary extra override file. + + + SrcExtraOverride + + Sets the source extra override file. + + + BinCacheDB + + Sets the cache DB. + + + PathPrefix + + Appends a path to all the output paths. + + + FileList, SourceFileList + + Specifies the file list file. + + + + + + + The Binary Override File + The binary override file is fully compatible with &dpkg-scanpackages;. It + contains 4 fields separated by spaces. The first field is the package name, + the second is the priority to force that package to, the third is the + the section to force that package to and the final field is the maintainer + permutation field. + The general form of the maintainer field is: + old [// oldn]* => new + or simply, + new + The first form allows a double-slash separated list of old email addresses + to be specified. If any of those are found then new is substituted for the + maintainer field. The second form unconditionally substitutes the + maintainer field. + + + + The Source Override File + + The source override file is fully compatible with &dpkg-scansources;. It + contains 2 fields separated by spaces. The first fields is the source + package name, the second is the section to assign it. + + + The Extra Override File + + The extra override file allows any arbitrary tag to be added or replaced + in the output. It has 3 columns, the first is the package, the second is + the tag and the remainder of the line is the new value. + + + options + &apt-cmdblurb; + + + + + Generate MD5 sums. This defaults to on, when turned off the generated + index files will not have MD5Sum fields where possible. + Configuration Item: APT::FTPArchive::MD5 + + + + + Use a binary caching DB. This has no effect on the generate command. + Configuration Item: APT::FTPArchive::DB. + + + + + Quiet; produces output suitable for logging, omitting progress indicators. + More q's will produce more quiet up to a maximum of 2. You can also use + to set the quiet level, overriding the configuration file. + Configuration Item: quiet. + + + + + Perform Delinking. If the External-Links setting is used then + this option actually enables delinking of the files. It defaults to on and + can be turned off with . + Configuration Item: APT::FTPArchive::DeLinkAct. + + + + + Perform contents generation. When this option is set and package indexes + are being generated with a cache DB then the file listing will also be + extracted and stored in the DB for later use. When using the generate + command this option also allows the creation of any Contents files. The + default is on. + Configuration Item: APT::FTPArchive::Contents. + + + + + Select the source override file to use with the sources command. + Configuration Item: APT::FTPArchive::SourceOverride. + + + + + Make the caching databases read only. + Configuration Item: APT::FTPArchive::ReadOnlyDB. + + + &apt-commonoptions; + + + + +Examples + +To create a compressed Packages file for a directory containing +binary packages (.deb): + + +apt-ftparchive packages directory | gzip > Packages.gz + + + + + See Also + &apt-conf; + + + Diagnostics + apt-ftparchive returns zero on normal operation, decimal 100 on error. + + + &manbugs; + &manauthor; + + diff --git a/doc/apt-get.8.sgml b/doc/apt-get.8.sgml deleted file mode 100644 index 0d6be65d7..000000000 --- a/doc/apt-get.8.sgml +++ /dev/null @@ -1,512 +0,0 @@ - - -%aptent; - -]> - - - &apt-docinfo; - - - apt-get - 8 - - - - - apt-get - APT package handling utility -- command-line interface - - - - - - apt-get - - - - - update - upgrade - dselect-upgrade - install pkg - remove pkg - source pkg - build-dep pkg - check - clean - autoclean - - - - - Description</> - <para> - <command/apt-get/ is the command-line tool for handling packages, and may be - considered the user's "back-end" to other tools using the APT - library. Several "front-end" interfaces exist, such as dselect(8), - aptitude, synaptic, gnome-apt and wajig. - <para> - Unless the <option/-h/, or <option/--help/ option is given, one of the - commands below must be present. - - <VariableList> - <VarListEntry><Term>update</Term> - <ListItem><Para> - <literal/update/ is used to resynchronize the package index files from - their sources. The indexes of available packages are fetched from the - location(s) specified in <filename>/etc/apt/sources.list</>. - For example, when using a Debian archive, this command retrieves and - scans the <filename>Packages.gz</> files, so that information about new - and updated packages is available. An <literal/update/ should always be - performed before an <literal/upgrade/ or <literal/dist-upgrade/. Please - be aware that the overall progress meter will be incorrect as the size - of the package files cannot be known in advance. - </VarListEntry> - - <VarListEntry><Term>upgrade</Term> - <ListItem><Para> - <literal/upgrade/ is used to install the newest versions of all packages - currently installed on the system from the sources enumerated in - <filename>/etc/apt/sources.list</>. Packages currently installed with - new versions available are retrieved and upgraded; under no circumstances - are currently installed packages removed, or packages not already installed - retrieved and installed. New versions of currently installed packages that - cannot be upgraded without changing the install status of another package - will be left at their current version. An <literal/update/ must be - performed first so that <command/apt-get/ knows that new versions of packages are - available. - </VarListEntry> - - <VarListEntry><Term>dselect-upgrade</Term> - <ListItem><Para> - <literal/dselect-upgrade/ - is used in conjunction with the traditional Debian packaging - front-end, &dselect;. <literal/dselect-upgrade/ - follows the changes made by &dselect; to the <literal/Status/ - field of available packages, and performs the actions necessary to realize - that state (for instance, the removal of old and the installation of new - packages). - </VarListEntry> - - <VarListEntry><Term>dist-upgrade</Term> - <ListItem><Para> - <literal/dist-upgrade/, in addition to performing the function of - <literal/upgrade/, also intelligently handles changing dependencies - with new versions of packages; <command/apt-get/ has a "smart" conflict - resolution system, and it will attempt to upgrade the most important - packages at the expense of less important ones if necessary. - The <filename>/etc/apt/sources.list</> file contains a list of locations - from which to retrieve desired package files. - See also &apt-preferences; for a mechanism for - overriding the general settings for individual packages. - </VarListEntry> - - <VarListEntry><Term>install</Term> - <ListItem><Para> - <literal/install/ is followed by one or more packages desired for - installation. Each package is a package name, not a fully qualified - filename (for instance, in a Debian GNU/Linux system, libc6 would be the - argument provided, not <literal/libc6_1.9.6-2.deb/). All packages required - by the package(s) specified for installation will also be retrieved and - installed. The <filename>/etc/apt/sources.list</> file is used to locate - the desired packages. If a hyphen is appended to the package name (with - no intervening space), the identified package will be removed if it is - installed. Similarly a plus sign can be used to designate a package to - install. These latter features may be used to override decisions made by - apt-get's conflict resolution system. - <para> - A specific version of a package can be selected for installation by - following the package name with an equals and the version of the package - to select. This will cause that version to be located and selected for - install. Alternatively a specific distribution can be selected by - following the package name with a slash and the version of the - distribution or the Archive name (stable, testing, unstable). - <para> - Both of the version selection mechanisms can downgrade packages and must - be used with care. - <para> - Finally, the &apt-preferences; mechanism allows you to - create an alternative installation policy for - individual packages. - <para> - If no package matches the given expression and the expression contains one - of '.', '?' or '*' then it is assumed to be a POSIX regular expression, - and it is applied - to all package names in the database. Any matches are then installed (or - removed). Note that matching is done by substring so 'lo.*' matches 'how-lo' - and 'lowest'. If this is undesired, anchor the regular expression - with a '^' or '$' character, or create a more specific regular expression. - </VarListEntry> - - <VarListEntry><Term>remove</Term> - <ListItem><Para> - <literal/remove/ is identical to <literal/install/ except that packages are - removed instead of installed. If a plus sign is appended to the package - name (with no intervening space), the identified package will be - installed instead of removed. - </VarListEntry> - - <VarListEntry><Term>source</Term> - <ListItem><Para> - <literal/source/ causes <command/apt-get/ to fetch source packages. APT - will examine the available packages to decide which source package to - fetch. It will then find and download into the current directory the - newest available version of that source package. Source packages are - tracked separately from binary packages via <literal/deb-src/ type lines - in the &sources-list; file. This probably will mean that you will not - get the same source as the package you have installed or as you could - install. If the --compile options is specified then the package will be - compiled to a binary .deb using dpkg-buildpackage, if --download-only is - specified then the source package will not be unpacked. - <para> - A specific source version can be retrieved by postfixing the source name - with an equals and then the version to fetch, similar to the mechanism - used for the package files. This enables exact matching of the source - package name and version, implicitly enabling the - <literal/APT::Get::Only-Source/ option. - - <para> - Note that source packages are not tracked like binary packages, they - exist only in the current directory and are similar to downloading source - tar balls. - </VarListEntry> - - <VarListEntry><Term>build-dep</Term> - <ListItem><Para> - <literal/build-dep/ causes apt-get to install/remove packages in an - attempt to satisfy the build dependencies for a source package. - </VarListEntry> - - <VarListEntry><Term>check</Term> - <ListItem><Para> - <literal/check/ is a diagnostic tool; it updates the package cache and checks - for broken dependencies. - </VarListEntry> - - <VarListEntry><Term>clean</Term> - <ListItem><Para> - <literal/clean/ clears out the local repository of retrieved package - files. It removes everything but the lock file from - <filename>&cachedir;/archives/</> and - <filename>&cachedir;/archives/partial/</>. When APT is used as a - &dselect; method, <literal/clean/ is run automatically. - Those who do not use dselect will likely want to run <literal/apt-get clean/ - from time to time to free up disk space. - </VarListEntry> - - <VarListEntry><Term>autoclean</Term> - <ListItem><Para> - Like <literal/clean/, <literal/autoclean/ clears out the local - repository of retrieved package files. The difference is that it only - removes package files that can no longer be downloaded, and are largely - useless. This allows a cache to be maintained over a long period without - it growing out of control. The configuration option - <literal/APT::Clean-Installed/ will prevent installed packages from being - erased if it is set to off. - </VarListEntry> - </VariableList> - </RefSect1> - - <RefSect1><Title>Options</> - &apt-cmdblurb; - - <VariableList> - <VarListEntry><term><option/-d/</><term><option/--download-only/</> - <ListItem><Para> - Download only; package files are only retrieved, not unpacked or installed. - Configuration Item: <literal/APT::Get::Download-Only/. - </VarListEntry> - - <VarListEntry><term><option/-f/</><term><option/--fix-broken/</> - <ListItem><Para> - Fix; attempt to correct a system with broken dependencies in - place. This option, when used with install/remove, can omit any packages - to permit APT to deduce a likely solution. Any Package that are specified - must completely correct the problem. The option is sometimes necessary when - running APT for the first time; APT itself does not allow broken package - dependencies to exist on a system. It is possible that a system's - dependency structure can be so corrupt as to require manual intervention - (which usually means using &dselect; or <command/dpkg --remove/ to eliminate some of - the offending packages). Use of this option together with <option/-m/ may produce an - error in some situations. - Configuration Item: <literal/APT::Get::Fix-Broken/. - </VarListEntry> - - <VarListEntry><term><option/-m/</><term><option/--ignore-missing/</> - <term><option/--fix-missing/</> - <ListItem><Para> - Ignore missing packages; If packages cannot be retrieved or fail the - integrity check after retrieval (corrupted package files), hold back - those packages and handle the result. Use of this option together with - <option/-f/ may produce an error in some situations. If a package is - selected for installation (particularly if it is mentioned on the - command line) and it could not be downloaded then it will be silently - held back. - Configuration Item: <literal/APT::Get::Fix-Missing/. - </VarListEntry> - - <VarListEntry><term><option/--no-download/</> - <ListItem><Para> - Disables downloading of packages. This is best used with - <option/--ignore-missing/ to force APT to use only the .debs it has - already downloaded. - Configuration Item: <literal/APT::Get::Download/. - </VarListEntry> - - <VarListEntry><term><option/-q/</><term><option/--quiet/</> - <ListItem><Para> - Quiet; produces output suitable for logging, omitting progress indicators. - More q's will produce more quiet up to a maximum of 2. You can also use - <option/-q=#/ to set the quiet level, overriding the configuration file. - Note that quiet level 2 implies <option/-y/, you should never use -qq - without a no-action modifier such as -d, --print-uris or -s as APT may - decided to do something you did not expect. - Configuration Item: <literal/quiet/. - </VarListEntry> - - <VarListEntry><term><option/-s/</> - <term><option/--simulate/</> - <term><option/--just-print/</> - <term><option/--dry-run/</> - <term><option/--recon/</> - <term><option/--no-act/</> - <ListItem><Para> - No action; perform a simulation of events that would occur but do not - actually change the system. - Configuration Item: <literal/APT::Get::Simulate/. - <para> - Simulate prints out - a series of lines each one representing a dpkg operation, Configure (Conf), - Remove (Remv), Unpack (Inst). Square brackets indicate broken packages with - and empty set of square brackets meaning breaks that are of no consequence - (rare). - </VarListEntry> - - <VarListEntry><term><option/-y/</><term><option/--yes/</> - <term><option/--assume-yes/</> - <ListItem><Para> - Automatic yes to prompts; assume "yes" as answer to all prompts and run - non-interactively. If an undesirable situation, such as changing a held - package or removing an essential package occurs then <literal/apt-get/ - will abort. - Configuration Item: <literal/APT::Get::Assume-Yes/. - </VarListEntry> - - <VarListEntry><term><option/-u/</><term><option/--show-upgraded/</> - <ListItem><Para> - Show upgraded packages; Print out a list of all packages that are to be - upgraded. - Configuration Item: <literal/APT::Get::Show-Upgraded/. - </VarListEntry> - - <VarListEntry><term><option/-V/</><term><option/--verbose-versions/</> - <ListItem><Para> - Show full versions for upgraded and installed packages. - Configuration Item: <literal/APT::Get::Show-Versions/. - </VarListEntry> - - <VarListEntry><term><option/-b/</><term><option/--compile/</> - <term><option/--build/</> - <ListItem><Para> - Compile source packages after downloading them. - Configuration Item: <literal/APT::Get::Compile/. - </VarListEntry> - - <VarListEntry><term><option/--ignore-hold/</> - <ListItem><Para> - Ignore package Holds; This causes <command/apt-get/ to ignore a hold - placed on a package. This may be useful in conjunction with - <literal/dist-upgrade/ to override a large number of undesired holds. - Configuration Item: <literal/APT::Ignore-Hold/. - </VarListEntry> - - <VarListEntry><term><option/--no-upgrade/</> - <ListItem><Para> - - Do not upgrade packages; When used in conjunction with - <literal/install/, <literal/no-upgrade/ will prevent packages - listed on the command linefrom being upgraded if they are already - installed. - - Configuration Item: <literal/APT::Get::Upgrade/. - </VarListEntry> - - <VarListEntry><term><option/--force-yes/</> - <ListItem><Para> - Force yes; This is a dangerous option that will cause apt to continue - without prompting if it is doing something potentially harmful. It - should not be used except in very special situations. Using - <literal/force-yes/ can potentially destroy your system! - Configuration Item: <literal/APT::Get::force-yes/. - </VarListEntry> - - <VarListEntry><term><option/--print-uris/</> - <ListItem><Para> - Instead of fetching the files to install their URIs are printed. Each - URI will have the path, the destination file name, the size and the expected - md5 hash. Note that the file name to write to will not always match - the file name on the remote site! This also works with the - <literal/source/ and <literal/update/ commands. When used with the - <literal/update/ command the MD5 and size are not included, and it is - up to the user to decompress any compressed files. - Configuration Item: <literal/APT::Get::Print-URIs/. - </VarListEntry> - - <VarListEntry><term><option/--purge/</> - <ListItem><Para> - Use purge instead of remove for anything that would be removed. - An asterisk ("*") will be displayed next to packages which are - scheduled to be purged. - Configuration Item: <literal/APT::Get::Purge/. - </VarListEntry> - - <VarListEntry><term><option/--reinstall/</> - <ListItem><Para> - Re-Install packages that are already installed and at the newest version. - Configuration Item: <literal/APT::Get::ReInstall/. - </VarListEntry> - - <VarListEntry><term><option/--list-cleanup/</> - <ListItem><Para> - This option defaults to on, use <literal/--no-list-cleanup/ to turn it - off. When on <command/apt-get/ will automatically manage the contents of - <filename>&statedir;/lists</> to ensure that obsolete files are erased. - The only reason to turn it off is if you frequently change your source - list. - Configuration Item: <literal/APT::Get::List-Cleanup/. - </VarListEntry> - - <VarListEntry><term><option/-t/</> - <term><option/--target-release/</> - <term><option/--default-release/</> - <ListItem><Para> - This option controls the default input to the policy engine, it creates - a default pin at priority 990 using the specified release string. The - preferences file may further override this setting. In short, this option - lets you have simple control over which distribution packages will be - retrieved from. Some common examples might be - <option>-t '2.1*'</> or <option>-t unstable</>. - Configuration Item: <literal/APT::Default-Release/; - see also the &apt-preferences; manual page. - </VarListEntry> - - <VarListEntry><term><option/--trivial-only/</> - <ListItem><Para> - Only perform operations that are 'trivial'. Logically this can be considered - related to <option/--assume-yes/, where <option/--assume-yes/ will answer - yes to any prompt, <option/--trivial-only/ will answer no. - Configuration Item: <literal/APT::Get::Trivial-Only/. - </VarListEntry> - - <VarListEntry><term><option/--no-remove/</> - <ListItem><Para> - If any packages are to be removed apt-get immediately aborts without - prompting. - Configuration Item: <literal/APT::Get::Remove/ - </VarListEntry> - - <VarListEntry><term><option/--only-source/</> - <ListItem><Para> - Only has meaning for the <literal/source/ command. Indicates that the - given source names are not to be mapped through the binary - table. This means that if this option is specified, the - <literal/source/ command will only accept source package names as - arguments, rather than accepting binary package names and looking - up the corresponding source package. - Configuration Item: <literal/APT::Get::Only-Source/ - </VarListEntry> - - <VarListEntry><term><option/--diff-only/</><term><option/--tar-only/</> - <ListItem><Para> - Download only the diff or tar file of a source archive. - Configuration Item: <literal/APT::Get::Diff-Only/ and - <literal/APT::Get::Tar-Only/ - </VarListEntry> - - <VarListEntry><term><option/--arch-only/</> - <ListItem><Para> - Only process architecture-dependent build-dependencies. - Configuration Item: <literal/APT::Get::Arch-Only/ - </VarListEntry> - - &apt-commonoptions; - - </VariableList> - </RefSect1> - - <RefSect1><Title>Files</> - <variablelist> - <VarListEntry><term><filename>/etc/apt/sources.list</></term> - <ListItem><Para> - Locations to fetch packages from. - Configuration Item: <literal/Dir::Etc::SourceList/. - </VarListEntry> - - <VarListEntry><term><filename>/etc/apt/apt.conf</></term> - <ListItem><Para> - APT configuration file. - Configuration Item: <literal/Dir::Etc::Main/. - </VarListEntry> - - <VarListEntry><term><filename>/etc/apt/apt.conf.d/</></term> - <ListItem><Para> - APT configuration file fragments - Configuration Item: <literal/Dir::Etc::Parts/. - </VarListEntry> - - <VarListEntry><term><filename>/etc/apt/preferences</></term> - <ListItem><Para> - Version preferences file. - This is where you would specify "pinning", - i.e. a preference to get certain packages - from a separate source - or from a different version of a distribution. - Configuration Item: <literal/Dir::Etc::Preferences/. - </VarListEntry> - - <VarListEntry><term><filename>&cachedir;/archives/</></term> - <ListItem><Para> - Storage area for retrieved package files. - Configuration Item: <literal/Dir::Cache::Archives/. - </VarListEntry> - - <VarListEntry><term><filename>&cachedir;/archives/partial/</></term> - <ListItem><Para> - Storage area for package files in transit. - Configuration Item: <literal/Dir::Cache::Archives/ (implicit partial). - </VarListEntry> - - <VarListEntry><term><filename>&statedir;/lists/</></term> - <ListItem><Para> - Storage area for state information for each package resource specified in - &sources-list; - Configuration Item: <literal/Dir::State::Lists/. - </VarListEntry> - - <VarListEntry><term><filename>&statedir;/lists/partial/</></term> - <ListItem><Para> - Storage area for state information in transit. - Configuration Item: <literal/Dir::State::Lists/ (implicit partial). - </VarListEntry> - </variablelist> - </RefSect1> - - <RefSect1><Title>See Also</> - <para> - &apt-cache;, &apt-cdrom;, &dpkg;, &dselect;, &sources-list;, - &apt-conf;, &apt-config;, - The APT User's guide in &docdir;, &apt-preferences;, the APT Howto. - </RefSect1> - - <RefSect1><Title>Diagnostics</> - <para> - <command/apt-get/ returns zero on normal operation, decimal 100 on error. - </RefSect1> - - &manbugs; - &manauthor; - -</refentry> diff --git a/doc/apt-get.8.xml b/doc/apt-get.8.xml new file mode 100644 index 000000000..9c819c4c4 --- /dev/null +++ b/doc/apt-get.8.xml @@ -0,0 +1,466 @@ +<?xml version="1.0" encoding="utf-8" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ + +<!ENTITY % aptent SYSTEM "apt.ent"> +%aptent; + +]> + +<refentry> + &apt-docinfo; + <!--<date>14 December 2003</date> --> + + <refmeta> + <refentrytitle>apt-get</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <!-- Man page title --> + <refnamediv> + <refname>apt-get</refname> + <refpurpose>APT package handling utility -- command-line interface</refpurpose> + </refnamediv> + + <!-- Arguments --> + <refsynopsisdiv> + <cmdsynopsis> + <command>apt-get</command> + <arg><option>-hvs</option></arg> + <arg><option>-o=<replaceable>config string</replaceable></option></arg> + <arg><option>-c=<replaceable>file</replaceable></option></arg> + <group choice="req"> + <arg>update</arg> + <arg>upgrade</arg> + <arg>dselect-upgrade</arg> + <arg>install <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg> + <arg>remove <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg> + <arg>source <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg> + <arg>build-dep <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg> + <arg>check</arg> + <arg>clean</arg> + <arg>autoclean</arg> + </group> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1><title>Description + apt-get is the command-line tool for handling packages, and may be + considered the user's "back-end" to other tools using the APT + library. Several "front-end" interfaces exist, such as dselect(8), + aptitude, synaptic, gnome-apt and wajig. + + Unless the , or option is given, one of the + commands below must be present. + + + update + update is used to resynchronize the package index files from + their sources. The indexes of available packages are fetched from the + location(s) specified in /etc/apt/sources.list. + For example, when using a Debian archive, this command retrieves and + scans the Packages.gz files, so that information about new + and updated packages is available. An update should always be + performed before an upgrade or dist-upgrade. Please + be aware that the overall progress meter will be incorrect as the size + of the package files cannot be known in advance. + + + upgrade + upgrade is used to install the newest versions of all packages + currently installed on the system from the sources enumerated in + /etc/apt/sources.list. Packages currently installed with + new versions available are retrieved and upgraded; under no circumstances + are currently installed packages removed, or packages not already installed + retrieved and installed. New versions of currently installed packages that + cannot be upgraded without changing the install status of another package + will be left at their current version. An update must be + performed first so that apt-get knows that new versions of packages are + available. + + + dselect-upgrade + dselect-upgrade + is used in conjunction with the traditional Debian packaging + front-end, &dselect;. dselect-upgrade + follows the changes made by &dselect; to the Status + field of available packages, and performs the actions necessary to realize + that state (for instance, the removal of old and the installation of new + packages). + + + dist-upgrade + dist-upgrade in addition to performing the function of + upgrade, also intelligently handles changing dependencies + with new versions of packages; apt-get has a "smart" conflict + resolution system, and it will attempt to upgrade the most important + packages at the expense of less important ones if necessary. + The /etc/apt/sources.list file contains a list of locations + from which to retrieve desired package files. + See also &apt-preferences; for a mechanism for + overriding the general settings for individual packages. + + + install + install is followed by one or more packages desired for + installation. Each package is a package name, not a fully qualified + filename (for instance, in a Debian GNU/Linux system, libc6 would be the + argument provided, not libc6_1.9.6-2.deb) All packages required + by the package(s) specified for installation will also be retrieved and + installed. The /etc/apt/sources.list file is used to locate + the desired packages. If a hyphen is appended to the package name (with + no intervening space), the identified package will be removed if it is + installed. Similarly a plus sign can be used to designate a package to + install. These latter features may be used to override decisions made by + apt-get's conflict resolution system. + + A specific version of a package can be selected for installation by + following the package name with an equals and the version of the package + to select. This will cause that version to be located and selected for + install. Alternatively a specific distribution can be selected by + following the package name with a slash and the version of the + distribution or the Archive name (stable, testing, unstable). + + Both of the version selection mechanisms can downgrade packages and must + be used with care. + + Finally, the &apt-preferences; mechanism allows you to + create an alternative installation policy for + individual packages. + + If no package matches the given expression and the expression contains one + of '.', '?' or '*' then it is assumed to be a POSIX regular expression, + and it is applied + to all package names in the database. Any matches are then installed (or + removed). Note that matching is done by substring so 'lo.*' matches 'how-lo' + and 'lowest'. If this is undesired, anchor the regular expression + with a '^' or '$' character, or create a more specific regular expression. + + + remove + remove is identical to install except that packages are + removed instead of installed. If a plus sign is appended to the package + name (with no intervening space), the identified package will be + installed instead of removed. + + + source + source causes apt-get to fetch source packages. APT + will examine the available packages to decide which source package to + fetch. It will then find and download into the current directory the + newest available version of that source package. Source packages are + tracked separately from binary packages via deb-src type lines + in the &sources-list; file. This probably will mean that you will not + get the same source as the package you have installed or as you could + install. If the --compile options is specified then the package will be + compiled to a binary .deb using dpkg-buildpackage, if --download-only is + specified then the source package will not be unpacked. + + A specific source version can be retrieved by postfixing the source name + with an equals and then the version to fetch, similar to the mechanism + used for the package files. This enables exact matching of the source + package name and version, implicitly enabling the + APT::Get::Only-Source option. + + Note that source packages are not tracked like binary packages, they + exist only in the current directory and are similar to downloading source + tar balls. + + + build-dep + build-dep causes apt-get to install/remove packages in an + attempt to satisfy the build dependencies for a source package. + + + check + check is a diagnostic tool; it updates the package cache and checks + for broken dependencies. + + + clean + clean clears out the local repository of retrieved package + files. It removes everything but the lock file from + &cachedir;/archives/ and + &cachedir;/archives/partial/. When APT is used as a + &dselect; method, clean is run automatically. + Those who do not use dselect will likely want to run apt-get clean + from time to time to free up disk space. + + + autoclean + Like clean, autoclean clears out the local + repository of retrieved package files. The difference is that it only + removes package files that can no longer be downloaded, and are largely + useless. This allows a cache to be maintained over a long period without + it growing out of control. The configuration option + APT::Clean-Installed will prevent installed packages from being + erased if it is set to off. + + + + + options + &apt-cmdblurb; + + + + Download only; package files are only retrieved, not unpacked or installed. + Configuration Item: APT::Get::Download-Only. + + + + Fix; attempt to correct a system with broken dependencies in + place. This option, when used with install/remove, can omit any packages + to permit APT to deduce a likely solution. Any Package that are specified + must completely correct the problem. The option is sometimes necessary when + running APT for the first time; APT itself does not allow broken package + dependencies to exist on a system. It is possible that a system's + dependency structure can be so corrupt as to require manual intervention + (which usually means using &dselect; or dpkg --remove to eliminate some of + the offending packages). Use of this option together with may produce an + error in some situations. + Configuration Item: APT::Get::Fix-Broken. + + + + + Ignore missing packages; If packages cannot be retrieved or fail the + integrity check after retrieval (corrupted package files), hold back + those packages and handle the result. Use of this option together with + may produce an error in some situations. If a package is + selected for installation (particularly if it is mentioned on the + command line) and it could not be downloaded then it will be silently + held back. + Configuration Item: APT::Get::Fix-Missing. + + + + Disables downloading of packages. This is best used with + to force APT to use only the .debs it has + already downloaded. + Configuration Item: APT::Get::Download. + + + + Quiet; produces output suitable for logging, omitting progress indicators. + More q's will produce more quiet up to a maximum of 2. You can also use + to set the quiet level, overriding the configuration file. + Note that quiet level 2 implies , you should never use -qq + without a no-action modifier such as -d, --print-uris or -s as APT may + decided to do something you did not expect. + Configuration Item: quiet. + + + + + + + + + No action; perform a simulation of events that would occur but do not + actually change the system. + Configuration Item: APT::Get::Simulate. + + Simulate prints out + a series of lines each one representing a dpkg operation, Configure (Conf), + Remove (Remv), Unpack (Inst). Square brackets indicate broken packages with + and empty set of square brackets meaning breaks that are of no consequence + (rare). + + + + + Automatic yes to prompts; assume "yes" as answer to all prompts and run + non-interactively. If an undesirable situation, such as changing a held + package or removing an essential package occurs then apt-get + will abort. + Configuration Item: APT::Get::Assume-Yes. + + + + Show upgraded packages; Print out a list of all packages that are to be + upgraded. + Configuration Item: APT::Get::Show-Upgraded. + + + + Show full versions for upgraded and installed packages. + Configuration Item: APT::Get::Show-Versions. + + + + + Compile source packages after downloading them. + Configuration Item: APT::Get::Compile. + + + + Ignore package Holds; This causes apt-get to ignore a hold + placed on a package. This may be useful in conjunction with + dist-upgrade to override a large number of undesired holds. + Configuration Item: APT::Ignore-Hold. + + + + Do not upgrade packages; When used in conjunction with install, + no-upgrade will prevent packages on the command line + from being upgraded if they are already installed. + Configuration Item: APT::Get::Upgrade. + + + + Force yes; This is a dangerous option that will cause apt to continue + without prompting if it is doing something potentially harmful. It + should not be used except in very special situations. Using + force-yes can potentially destroy your system! + Configuration Item: APT::Get::force-yes. + + + + Instead of fetching the files to install their URIs are printed. Each + URI will have the path, the destination file name, the size and the expected + md5 hash. Note that the file name to write to will not always match + the file name on the remote site! This also works with the + source and update commands. When used with the + update command the MD5 and size are not included, and it is + up to the user to decompress any compressed files. + Configuration Item: APT::Get::Print-URIs. + + + + Use purge instead of remove for anything that would be removed. + An asterisk ("*") will be displayed next to packages which are + scheduled to be purged. + Configuration Item: APT::Get::Purge. + + + + Re-Install packages that are already installed and at the newest version. + Configuration Item: APT::Get::ReInstall. + + + + This option defaults to on, use --no-list-cleanup to turn it + off. When on apt-get will automatically manage the contents of + &statedir;/lists to ensure that obsolete files are erased. + The only reason to turn it off is if you frequently change your source + list. + Configuration Item: APT::Get::List-Cleanup. + + + + + + This option controls the default input to the policy engine, it creates + a default pin at priority 990 using the specified release string. The + preferences file may further override this setting. In short, this option + lets you have simple control over which distribution packages will be + retrieved from. Some common examples might be + or . + Configuration Item: APT::Default-Release; + see also the &apt-preferences; manual page. + + + + + Only perform operations that are 'trivial'. Logically this can be considered + related to , where will answer + yes to any prompt, will answer no. + Configuration Item: APT::Get::Trivial-Only. + + + + If any packages are to be removed apt-get immediately aborts without + prompting. + Configuration Item: APT::Get::Remove. + + + + Only has meaning for the source command. Indicates that the + given source names are not to be mapped through the binary + table. This means that if this option is specified, the + source command will only accept source package names as + arguments, rather than accepting binary package names and looking + up the corresponding source package. + Configuration Item: APT::Get::Only-Source. + + + + Download only the diff or tar file of a source archive. + Configuration Item: APT::Get::Diff-Only and + APT::Get::Tar-Only. + + + + Only process architecture-dependent build-dependencies. + Configuration Item: APT::Get::Arch-Only. + + + &apt-commonoptions; + + + + + Files + + /etc/apt/sources.list + Locations to fetch packages from. + Configuration Item: Dir::Etc::SourceList. + + + /etc/apt/apt.conf + APT configuration file. + Configuration Item: Dir::Etc::Main. + + + /etc/apt/apt.conf.d/ + APT configuration file fragments + Configuration Item: Dir::Etc::Parts. + + + /etc/apt/preferences + Version preferences file. + This is where you would specify "pinning", + i.e. a preference to get certain packages + from a separate source + or from a different version of a distribution. + Configuration Item: Dir::Etc::Preferences. + + + &cachedir;/archives/ + Storage area for retrieved package files. + Configuration Item: Dir::Cache::Archives. + + + &cachedir;/archives/partial/ + Storage area for package files in transit. + Configuration Item: Dir::Cache::Archives (implicit partial). + + + &statedir;/lists/ + Storage area for state information for each package resource specified in + &sources-list; + Configuration Item: Dir::State::Lists. + + + &statedir;/lists/partial/ + Storage area for state information in transit. + Configuration Item: Dir::State::Lists (implicit partial). + + + + + See Also + &apt-cache;, &apt-cdrom;, &dpkg;, &dselect;, &sources-list;, + &apt-conf;, &apt-config;, + The APT User's guide in &docdir;, &apt-preferences;, the APT Howto. + + + Diagnostics + apt-get returns zero on normal operation, decimal 100 on error. + + + &manbugs; + &manauthor; + + diff --git a/doc/apt-sortpkgs.1.sgml b/doc/apt-sortpkgs.1.sgml deleted file mode 100644 index e0af29d2d..000000000 --- a/doc/apt-sortpkgs.1.sgml +++ /dev/null @@ -1,73 +0,0 @@ - - -%aptent; - -]> - - - &apt-docinfo; - - - apt-sortpkgs - 1 - - - - - apt-sortpkgs - Utility to sort package index files - - - - - - apt-sortpkgs - - - - file - - - - Description</> - <para> - <command/apt-sortpkgs/ will take an index file (Source index or Package - index) and sort the records so that they are ordered by the package name. - It will also sort the internal fields of each record according to the - internal sorting rules. - - <para> - All output is sent to stdout, the input must be a seekable file. - </RefSect1> - - <RefSect1><Title>Options</> - &apt-cmdblurb; - - <VariableList> - <VarListEntry><term><option/-s/</><term><option/--source/</> - <ListItem><Para> - Use Source index field ordering. - Configuration Item: <literal/APT::SortPkgs::Source/. - </VarListEntry> - - &apt-commonoptions; - - </VariableList> - </RefSect1> - - <RefSect1><Title>See Also</> - <para> - &apt-conf; - </RefSect1> - - <RefSect1><Title>Diagnostics</> - <para> - <command/apt-sortpkgs/ returns zero on normal operation, decimal 100 on error. - </RefSect1> - - &manbugs; - &manauthor; - -</refentry> diff --git a/doc/apt-sortpkgs.1.xml b/doc/apt-sortpkgs.1.xml new file mode 100644 index 000000000..86058e605 --- /dev/null +++ b/doc/apt-sortpkgs.1.xml @@ -0,0 +1,71 @@ +<?xml version="1.0" encoding="utf-8" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ + +<!ENTITY % aptent SYSTEM "apt.ent"> +%aptent; + +]> + +<refentry> + &apt-docinfo; + + <refmeta> + <refentrytitle>apt-sortpkgs</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <!-- Man page title --> + <refnamediv> + <refname>apt-sortpkgs</refname> + <refpurpose>Utility to sort package index files</refpurpose> + </refnamediv> + + <!-- Arguments --> + <refsynopsisdiv> + <cmdsynopsis> + <command>apt-sortpkgs</command> + <arg><option>-hvs</option></arg> + <arg><option>-o=<replaceable>config string</replaceable></option></arg> + <arg><option>-c=<replaceable>file</replaceable></option></arg> + <arg choice="plain" rep="repeat"><replaceable>file</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1><title>Description + apt-sortpkgs will take an index file (Source index or Package + index) and sort the records so that they are ordered by the package name. + It will also sort the internal fields of each record according to the + internal sorting rules. + + + All output is sent to stdout, the input must be a seekable file. + + + options + &apt-cmdblurb; + + + + + Use Source index field ordering. + Configuration Item: APT::SortPkgs::Source. + + + &apt-commonoptions; + + + + + See Also + &apt-conf; + + + Diagnostics + apt-sortpkgs returns zero on normal operation, decimal 100 on error. + + + &manbugs; + &manauthor; + + diff --git a/doc/apt.conf.5.sgml b/doc/apt.conf.5.sgml deleted file mode 100644 index 2f04c892c..000000000 --- a/doc/apt.conf.5.sgml +++ /dev/null @@ -1,415 +0,0 @@ - - -%aptent; - -]> - - - &apt-docinfo; - - - apt.conf - 5 - - - - - apt.conf - Configuration file for APT - - - Description</> - <para> - <filename/apt.conf/ is the main configuration file for the APT suite of - tools, all tools make use of the configuration file and a common command line - parser to provide a uniform environment. When an APT tool starts up it will - read the configuration specified by the <envar/APT_CONFIG/ environment - variable (if any) and then read the files in <literal/Dir::Etc::Parts/ - then read the main configuration file specified by - <literal/Dir::Etc::main/ then finally apply the - command line options to override the configuration directives, possibly - loading even more config files. - <para> - The configuration file is organized in a tree with options organized into - functional groups. Option specification is given with a double colon - notation, for instance <literal/APT::Get::Assume-Yes/ is an option within - the APT tool group, for the Get tool. Options do not inherit from their - parent groups. - <para> - Syntacticly the configuration language is modeled after what the ISC tools - such as bind and dhcp use. Lines starting with - <literal>//</literal> are treated as comments (ignored). Each line is of the form - <literallayout>APT::Get::Assume-Yes "true";</literallayout> The trailing - semicolon is required and the quotes are optional. A new scope can be - opened with curly braces, like: -<informalexample><programlisting> -APT { - Get { - Assume-Yes "true"; - Fix-Broken "true"; - }; -}; -</programlisting></informalexample> - with newlines placed to make it more readable. Lists can be created by - opening a scope and including a single word enclosed in quotes followed by a - semicolon. Multiple entries can be included, each separated by a semicolon. -<informalexample><programlisting> -DPkg::Pre-Install-Pkgs {"/usr/sbin/dpkg-preconfigure --apt";}; -</programlisting></informalexample> - <para> - In general the sample configuration file in - <filename>&docdir;examples/apt.conf</> &configureindex; - is a good guide for how it should look. - <para> - Two specials are allowed, <literal/#include/ and <literal/#clear/. - <literal/#include/ will include the given file, unless the filename - ends in a slash, then the whole directory is included. - <literal/#clear/ is used to erase a list of names. - <para> - All of the APT tools take a -o option which allows an arbitrary configuration - directive to be specified on the command line. The syntax is a full option - name (<literal/APT::Get::Assume-Yes/ for instance) followed by an equals - sign then the new value of the option. Lists can be appended too by adding - a trailing :: to the list name. - </RefSect1> - - <RefSect1><Title>The APT Group</> - <para> - This group of options controls general APT behavior as well as holding the - options for all of the tools. - - <VariableList> - <VarListEntry><Term>Architecture</Term> - <ListItem><Para> - System Architecture; sets the architecture to use when fetching files and - parsing package lists. The internal default is the architecture apt was - compiled for. - </VarListEntry> - - <VarListEntry><Term>Ignore-Hold</Term> - <ListItem><Para> - Ignore Held packages; This global option causes the problem resolver to - ignore held packages in its decision making. - </VarListEntry> - - <VarListEntry><Term>Clean-Installed</Term> - <ListItem><Para> - Defaults to on. When turned on the autoclean feature will remove any packages - which can no longer be downloaded from the cache. If turned off then - packages that are locally installed are also excluded from cleaning - but - note that APT provides no direct means to reinstall them. - </VarListEntry> - - <VarListEntry><Term>Immediate-Configure</Term> - <ListItem><Para> - Disable Immediate Configuration; This dangerous option disables some - of APT's ordering code to cause it to make fewer dpkg calls. Doing - so may be necessary on some extremely slow single user systems but - is very dangerous and may cause package install scripts to fail or worse. - Use at your own risk. - </VarListEntry> - - <VarListEntry><Term>Force-LoopBreak</Term> - <ListItem><Para> - Never Enable this option unless you -really- know what you are doing. It - permits APT to temporarily remove an essential package to break a - Conflicts/Conflicts or Conflicts/Pre-Depend loop between two essential - packages. SUCH A LOOP SHOULD NEVER EXIST AND IS A GRAVE BUG. This option - will work if the essential packages are not tar, gzip, libc, dpkg, bash or - anything that those packages depend on. - </VarListEntry> - - <VarListEntry><Term>Cache-Limit</Term> - <ListItem><Para> - APT uses a fixed size memory mapped cache file to store the 'available' - information. This sets the size of that cache. - </VarListEntry> - - <VarListEntry><Term>Build-Essential</Term> - <ListItem><Para> - Defines which package(s) are considered essential build dependencies. - </VarListEntry> - - <VarListEntry><Term>Get</Term> - <ListItem><Para> - The Get subsection controls the &apt-get; tool, please see its - documentation for more information about the options here. - </VarListEntry> - - <VarListEntry><Term>Cache</Term> - <ListItem><Para> - The Cache subsection controls the &apt-cache; tool, please see its - documentation for more information about the options here. - </VarListEntry> - - <VarListEntry><Term>CDROM</Term> - <ListItem><Para> - The CDROM subsection controls the &apt-cdrom; tool, please see its - documentation for more information about the options here. - </VarListEntry> - </VariableList> - </RefSect1> - - <RefSect1><Title>The Acquire Group</> - <para> - The <literal/Acquire/ group of options controls the download of packages - and the URI handlers. - - <VariableList> - <VarListEntry><Term>Queue-Mode</Term> - <ListItem><Para> - Queuing mode; <literal/Queue-Mode/ can be one of <literal/host/ or - <literal/access/ which determines how APT parallelizes outgoing - connections. <literal/host/ means that one connection per target host - will be opened, <literal/access/ means that one connection per URI type - will be opened. - </VarListEntry> - - <VarListEntry><Term>Retries</Term> - <ListItem><Para> - Number of retries to perform. If this is non-zero APT will retry failed - files the given number of times. - </VarListEntry> - - <VarListEntry><Term>Source-Symlinks</Term> - <ListItem><Para> - Use symlinks for source archives. If set to true then source archives will - be symlinked when possible instead of copying. True is the default - </VarListEntry> - - <VarListEntry><Term>http</Term> - <ListItem><Para> - HTTP URIs; http::Proxy is the default http proxy to use. It is in the - standard form of <literal>http://[[user][:pass]@]host[:port]/</>. Per - host proxies can also be specified by using the form - <literal/http::Proxy::<host>/ with the special keyword <literal/DIRECT/ - meaning to use no proxies. The <envar/http_proxy/ environment variable - will override all settings. - <para> - Three settings are provided for cache control with HTTP/1.1 compliant - proxy caches. <literal/No-Cache/ tells the proxy to not use its cached - response under any circumstances, <literal/Max-Age/ is sent only for - index files and tells the cache to refresh its object if it is older than - the given number of seconds. Debian updates its index files daily so the - default is 1 day. <literal/No-Store/ specifies that the cache should never - store this request, it is only set for archive files. This may be useful - to prevent polluting a proxy cache with very large .deb files. Note: - Squid 2.0.2 does not support any of these options. - <para> - The option <literal/timeout/ sets the timeout timer used by the method, - this applies to all things including connection timeout and data timeout. - <para> - One setting is provided to control the pipeline depth in cases where the - remote server is not RFC conforming or buggy (such as Squid 2.0.2) - <literal/Acquire::http::Pipeline-Depth/ can be a value from 0 to 5 - indicating how many outstanding requests APT should send. A value of - zero MUST be specified if the remote host does not properly linger - on TCP connections - otherwise data corruption will occur. Hosts which - require this are in violation of RFC 2068. - </VarListEntry> - - <VarListEntry><Term>ftp</Term> - <ListItem><Para> - FTP URIs; ftp::Proxy is the default proxy server to use. It is in the - standard form of <literal>ftp://[[user][:pass]@]host[:port]/</> and is - overridden by the <envar/ftp_proxy/ environment variable. To use a ftp - proxy you will have to set the <literal/ftp::ProxyLogin/ script in the - configuration file. This entry specifies the commands to send to tell - the proxy server what to connect to. Please see - &configureindex; for an example of - how to do this. The subsitution variables available are - <literal/$(PROXY_USER)/, <literal/$(PROXY_PASS)/, <literal/$(SITE_USER)/, - <literal/$(SITE_PASS)/, <literal/$(SITE)/, and <literal/$(SITE_PORT)/. - Each is taken from it's respective URI component. - <para> - The option <literal/timeout/ sets the timeout timer used by the method, - this applies to all things including connection timeout and data timeout. - <para> - Several settings are provided to control passive mode. Generally it is - safe to leave passive mode on, it works in nearly every environment. - However some situations require that passive mode be disabled and port - mode ftp used instead. This can be done globally, for connections that - go through a proxy or for a specific host (See the sample config file - for examples) - <para> - It is possible to proxy FTP over HTTP by setting the <envar/ftp_proxy/ - environment variable to a http url - see the discussion of the http method - above for syntax. You cannot set this in the configuration file and it is - not recommended to use FTP over HTTP due to its low efficiency. - <para> - The setting <literal/ForceExtended/ controls the use of RFC2428 - <literal/EPSV/ and <literal/EPRT/ commands. The defaut is false, which means - these commands are only used if the control connection is IPv6. Setting this - to true forces their use even on IPv4 connections. Note that most FTP servers - do not support RFC2428. - </VarListEntry> - - <VarListEntry><Term>cdrom</Term> - <ListItem><Para> - CDROM URIs; the only setting for CDROM URIs is the mount point, - <literal/cdrom::Mount/ which must be the mount point for the CDROM drive - as specified in <filename>/etc/fstab</>. It is possible to provide - alternate mount and unmount commands if your mount point cannot be listed - in the fstab (such as an SMB mount and old mount packages). The syntax - is to put <literallayout>"/cdrom/"::Mount "foo";</literallayout> within - the cdrom block. It is important to have the trailing slash. Unmount - commands can be specified using UMount. - </VarListEntry> - </VariableList> - </RefSect1> - - <RefSect1><Title>Directories</> - <para> - The <literal/Dir::State/ section has directories that pertain to local - state information. <literal/lists/ is the directory to place downloaded - package lists in and <literal/status/ is the name of the dpkg status file. - <literal/preferences/ is the name of the APT preferences file. - <literal/Dir::State/ contains the default directory to prefix on all sub - items if they do not start with <filename>/</> or <filename>./</>. - <para> - <literal/Dir::Cache/ contains locations pertaining to local cache - information, such as the two package caches <literal/srcpkgcache/ and - <literal/pkgcache/ as well as the location to place downloaded archives, - <literal/Dir::Cache::archives/. Generation of caches can be turned off - by setting their names to be blank. This will slow down startup but - save disk space. It is probably prefered to turn off the pkgcache rather - than the srcpkgcache. Like <literal/Dir::State/ the default - directory is contained in <literal/Dir::Cache/ - <para> - <literal/Dir::Etc/ contains the location of configuration files, - <literal/sourcelist/ gives the location of the sourcelist and - <literal/main/ is the default configuration file (setting has no effect, - unless it is done from the config file specified by - <envar/APT_CONFIG/). - <para> - The <literal/Dir::Parts/ setting reads in all the config fragments in - lexical order from the directory specified. After this is done then the - main config file is loaded. - <para> - Binary programs are pointed to by <literal/Dir::Bin/. <literal/Dir::Bin::Methods/ - specifies the location of the method handlers and <literal/gzip/, - <literal/dpkg/, <literal/apt-get/, <literal/dpkg-source/, - <literal/dpkg-buildpackage/ and <literal/apt-cache/ specify the location - of the respective programs. - </RefSect1> - - <RefSect1><Title>APT in DSelect</> - <para> - When APT is used as a &dselect; method several configuration directives - control the default behaviour. These are in the <literal/DSelect/ section. - - <VariableList> - <VarListEntry><Term>Clean</Term> - <ListItem><Para> - Cache Clean mode; this value may be one of always, prompt, auto, - pre-auto and never. always and prompt will remove all packages from - the cache after upgrading, prompt (the default) does so conditionally. - auto removes only those packages which are no longer downloadable - (replaced with a new version for instance). pre-auto performs this - action before downloading new packages. - </VarListEntry> - - <VarListEntry><Term>Options</Term> - <ListItem><Para> - The contents of this variable is passed to &apt-get; as command line - options when it is run for the install phase. - </VarListEntry> - - <VarListEntry><Term>UpdateOptions</Term> - <ListItem><Para> - The contents of this variable is passed to &apt-get; as command line - options when it is run for the update phase. - </VarListEntry> - - <VarListEntry><Term>PromptAfterUpdate</Term> - <ListItem><Para> - If true the [U]pdate operation in &dselect; will always prompt to continue. - The default is to prompt only on error. - </VarListEntry> - </VariableList> - </RefSect1> - - <RefSect1><Title>How APT calls dpkg</> - <para> - Several configuration directives control how APT invokes &dpkg;. These are - in the <literal/DPkg/ section. - - <VariableList> - <VarListEntry><Term>Options</Term> - <ListItem><Para> - This is a list of options to pass to dpkg. The options must be specified - using the list notation and each list item is passed as a single argument - to &dpkg;. - </VarListEntry> - - <VarListEntry><Term>Pre-Invoke</Term><Term>Post-Invoke</Term> - <ListItem><Para> - This is a list of shell commands to run before/after invoking &dpkg;. - Like <literal/Options/ this must be specified in list notation. The - commands are invoked in order using <filename>/bin/sh</>, should any - fail APT will abort. - </VarListEntry> - - <VarListEntry><Term>Pre-Install-Pkgs</Term> - <ListItem><Para> - This is a list of shell commands to run before invoking dpkg. Like - <literal/Options/ this must be specified in list notation. The commands - are invoked in order using <filename>/bin/sh</>, should any fail APT - will abort. APT will pass to the commands on standard input the - filenames of all .deb files it is going to install, one per line. - <para> - Version 2 of this protocol dumps more information, including the - protocol version, the APT configuration space and the packages, files - and versions being changed. Version 2 is enabled by setting - <literal/DPkg::Tools::Options::cmd::Version/ to 2. <literal/cmd/ is a - command given to <literal/Pre-Install-Pkgs/. - </VarListEntry> - - <VarListEntry><Term>Run-Directory</Term> - <ListItem><Para> - APT chdirs to this directory before invoking dpkg, the default is - <filename>/</>. - </VarListEntry> - - <VarListEntry><Term>Build-Options</Term> - <ListItem><Para> - These options are passed to &dpkg-buildpackage; when compiling packages, - the default is to disable signing and produce all binaries. - </VarListEntry> - </VariableList> - </RefSect1> - - <RefSect1><Title>Debug Options</> - <para> - Most of the options in the <literal/debug/ section are not interesting to - the normal user, however <literal/Debug::pkgProblemResolver/ shows - interesting output about the decisions dist-upgrade makes. - <literal/Debug::NoLocking/ disables file locking so APT can do some - operations as non-root and <literal/Debug::pkgDPkgPM/ will print out the - command line for each dpkg invokation. <literal/Debug::IdentCdrom/ will - disable the inclusion of statfs data in CDROM IDs. - </RefSect1> - - <RefSect1><Title>Examples</> - <para> - &configureindex; contains a - sample configuration file showing the default values for all possible - options. - </RefSect1> - - <RefSect1><Title>Files</> - <para> - <filename>/etc/apt/apt.conf</> - </RefSect1> - - <RefSect1><Title>See Also</> - <para> - &apt-cache;, &apt-config;<!-- ? reading apt.conf -->, &apt-preferences;. - </RefSect1> - - &manbugs; - &manauthor; - -</refentry> diff --git a/doc/apt.conf.5.xml b/doc/apt.conf.5.xml new file mode 100644 index 000000000..33269a2f6 --- /dev/null +++ b/doc/apt.conf.5.xml @@ -0,0 +1,389 @@ +<?xml version="1.0" encoding="utf-8" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ + +<!ENTITY % aptent SYSTEM "apt.ent"> +%aptent; + +]> + +<refentry> + &apt-docinfo; + + <refmeta> + <refentrytitle>apt.conf</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <!-- Man page title --> + <refnamediv> + <refname>apt.conf</refname> + <refpurpose>Configuration file for APT</refpurpose> + </refnamediv> + + <refsect1><title>Description + apt.conf is the main configuration file for the APT suite of + tools, all tools make use of the configuration file and a common command line + parser to provide a uniform environment. When an APT tool starts up it will + read the configuration specified by the APT_CONFIG environment + variable (if any) and then read the files in Dir::Etc::Parts + then read the main configuration file specified by + Dir::Etc::main then finally apply the + command line options to override the configuration directives, possibly + loading even more config files. + + The configuration file is organized in a tree with options organized into + functional groups. option specification is given with a double colon + notation, for instance APT::Get::Assume-Yes is an option within + the APT tool group, for the Get tool. options do not inherit from their + parent groups. + + Syntacticly the configuration language is modeled after what the ISC tools + such as bind and dhcp use. Lines starting with + // are treated as comments (ignored). + Each line is of the form + APT::Get::Assume-Yes "true"; The trailing + semicolon is required and the quotes are optional. A new scope can be + opened with curly braces, like: + + +APT { + Get { + Assume-Yes "true"; + Fix-Broken "true"; + }; +}; + + + with newlines placed to make it more readable. Lists can be created by + opening a scope and including a single word enclosed in quotes followed by a + semicolon. Multiple entries can be included, each separated by a semicolon. + + +DPkg::Pre-Install-Pkgs {"/usr/sbin/dpkg-preconfigure --apt";}; + + + In general the sample configuration file in + &docdir;examples/apt.conf &configureindex; + is a good guide for how it should look. + + Two specials are allowed, #include and #clear + #include will include the given file, unless the filename + ends in a slash, then the whole directory is included. + #clear is used to erase a list of names. + + All of the APT tools take a -o option which allows an arbitrary configuration + directive to be specified on the command line. The syntax is a full option + name (APT::Get::Assume-Yes for instance) followed by an equals + sign then the new value of the option. Lists can be appended too by adding + a trailing :: to the list name. + + + The APT Group + This group of options controls general APT behavior as well as holding the + options for all of the tools. + + + Architecture + System Architecture; sets the architecture to use when fetching files and + parsing package lists. The internal default is the architecture apt was + compiled for. + + + Ignore-Hold + Ignore Held packages; This global option causes the problem resolver to + ignore held packages in its decision making. + + + Clean-Installed + Defaults to on. When turned on the autoclean feature will remove any packages + which can no longer be downloaded from the cache. If turned off then + packages that are locally installed are also excluded from cleaning - but + note that APT provides no direct means to reinstall them. + + + Immediate-Configure + Disable Immediate Configuration; This dangerous option disables some + of APT's ordering code to cause it to make fewer dpkg calls. Doing + so may be necessary on some extremely slow single user systems but + is very dangerous and may cause package install scripts to fail or worse. + Use at your own risk. + + + Force-LoopBreak + Never Enable this option unless you -really- know what you are doing. It + permits APT to temporarily remove an essential package to break a + Conflicts/Conflicts or Conflicts/Pre-Depend loop between two essential + packages. SUCH A LOOP SHOULD NEVER EXIST AND IS A GRAVE BUG. This option + will work if the essential packages are not tar, gzip, libc, dpkg, bash or + anything that those packages depend on. + + + Cache-Limit + APT uses a fixed size memory mapped cache file to store the 'available' + information. This sets the size of that cache. + + + Build-Essential + Defines which package(s) are considered essential build dependencies. + + + Get + The Get subsection controls the &apt-get; tool, please see its + documentation for more information about the options here. + + + Cache + The Cache subsection controls the &apt-cache; tool, please see its + documentation for more information about the options here. + + + CDROM + The CDROM subsection controls the &apt-cdrom; tool, please see its + documentation for more information about the options here. + + + + + The Acquire Group + The Acquire group of options controls the download of packages + and the URI handlers. + + + Queue-Mode + Queuing mode; Queue-Mode can be one of host or + access which determines how APT parallelizes outgoing + connections. host means that one connection per target host + will be opened, access means that one connection per URI type + will be opened. + + + Retries + Number of retries to perform. If this is non-zero APT will retry failed + files the given number of times. + + + Source-Symlinks + Use symlinks for source archives. If set to true then source archives will + be symlinked when possible instead of copying. True is the default. + + + http + HTTP URIs; http::Proxy is the default http proxy to use. It is in the + standard form of http://[[user][:pass]@]host[:port]/. Per + host proxies can also be specified by using the form + http::Proxy::<host> with the special keyword DIRECT + meaning to use no proxies. The http_proxy environment variable + will override all settings. + + Three settings are provided for cache control with HTTP/1.1 compliant + proxy caches. No-Cache tells the proxy to not use its cached + response under any circumstances, Max-Age is sent only for + index files and tells the cache to refresh its object if it is older than + the given number of seconds. Debian updates its index files daily so the + default is 1 day. No-Store specifies that the cache should never + store this request, it is only set for archive files. This may be useful + to prevent polluting a proxy cache with very large .deb files. Note: + Squid 2.0.2 does not support any of these options. + + The option timeout sets the timeout timer used by the method, + this applies to all things including connection timeout and data timeout. + + One setting is provided to control the pipeline depth in cases where the + remote server is not RFC conforming or buggy (such as Squid 2.0.2) + Acquire::http::Pipeline-Depth can be a value from 0 to 5 + indicating how many outstanding requests APT should send. A value of + zero MUST be specified if the remote host does not properly linger + on TCP connections - otherwise data corruption will occur. Hosts which + require this are in violation of RFC 2068. + + + ftp + FTP URIs; ftp::Proxy is the default proxy server to use. It is in the + standard form of ftp://[[user][:pass]@]host[:port]/ and is + overridden by the ftp_proxy environment variable. To use a ftp + proxy you will have to set the ftp::ProxyLogin script in the + configuration file. This entry specifies the commands to send to tell + the proxy server what to connect to. Please see + &configureindex; for an example of + how to do this. The subsitution variables available are + $(PROXY_USER) $(PROXY_PASS) $(SITE_USER) + $(SITE_PASS) $(SITE) and $(SITE_PORT) + Each is taken from it's respective URI component. + + The option timeout sets the timeout timer used by the method, + this applies to all things including connection timeout and data timeout. + + Several settings are provided to control passive mode. Generally it is + safe to leave passive mode on, it works in nearly every environment. + However some situations require that passive mode be disabled and port + mode ftp used instead. This can be done globally, for connections that + go through a proxy or for a specific host (See the sample config file + for examples). + + It is possible to proxy FTP over HTTP by setting the ftp_proxy + environment variable to a http url - see the discussion of the http method + above for syntax. You cannot set this in the configuration file and it is + not recommended to use FTP over HTTP due to its low efficiency. + + The setting ForceExtended controls the use of RFC2428 + EPSV and EPRT commands. The defaut is false, which means + these commands are only used if the control connection is IPv6. Setting this + to true forces their use even on IPv4 connections. Note that most FTP servers + do not support RFC2428. + + + cdrom + CDROM URIs; the only setting for CDROM URIs is the mount point, + cdrom::Mount which must be the mount point for the CDROM drive + as specified in /etc/fstab. It is possible to provide + alternate mount and unmount commands if your mount point cannot be listed + in the fstab (such as an SMB mount and old mount packages). The syntax + is to put "/cdrom/"::Mount "foo"; within + the cdrom block. It is important to have the trailing slash. Unmount + commands can be specified using UMount. + + + + + + Directories + + The Dir::State section has directories that pertain to local + state information. lists is the directory to place downloaded + package lists in and status is the name of the dpkg status file. + preferences is the name of the APT preferences file. + Dir::State contains the default directory to prefix on all sub + items if they do not start with / or ./. + + Dir::Cache contains locations pertaining to local cache + information, such as the two package caches srcpkgcache and + pkgcache as well as the location to place downloaded archives, + Dir::Cache::archives. Generation of caches can be turned off + by setting their names to be blank. This will slow down startup but + save disk space. It is probably prefered to turn off the pkgcache rather + than the srcpkgcache. Like Dir::State the default + directory is contained in Dir::Cache + + Dir::Etc contains the location of configuration files, + sourcelist gives the location of the sourcelist and + main is the default configuration file (setting has no effect, + unless it is done from the config file specified by + APT_CONFIG. + + The Dir::Parts setting reads in all the config fragments in + lexical order from the directory specified. After this is done then the + main config file is loaded. + + Binary programs are pointed to by Dir::Bin. Dir::Bin::Methods + specifies the location of the method handlers and gzip, + dpkg, apt-get dpkg-source + dpkg-buildpackage and apt-cache specify the location + of the respective programs. + + + APT in DSelect + + When APT is used as a &dselect; method several configuration directives + control the default behaviour. These are in the DSelect section. + + + Clean + Cache Clean mode; this value may be one of always, prompt, auto, + pre-auto and never. always and prompt will remove all packages from + the cache after upgrading, prompt (the default) does so conditionally. + auto removes only those packages which are no longer downloadable + (replaced with a new version for instance). pre-auto performs this + action before downloading new packages. + + + options + The contents of this variable is passed to &apt-get; as command line + options when it is run for the install phase. + + + Updateoptions + The contents of this variable is passed to &apt-get; as command line + options when it is run for the update phase. + + + PromptAfterUpdate + If true the [U]pdate operation in &dselect; will always prompt to continue. + The default is to prompt only on error. + + + + + How APT calls dpkg + Several configuration directives control how APT invokes &dpkg;. These are + in the DPkg section. + + + options + This is a list of options to pass to dpkg. The options must be specified + using the list notation and each list item is passed as a single argument + to &dpkg;. + + + Pre-InvokePost-Invoke + This is a list of shell commands to run before/after invoking &dpkg;. + Like options this must be specified in list notation. The + commands are invoked in order using /bin/sh, should any + fail APT will abort. + + + Pre-Install-Pkgs + This is a list of shell commands to run before invoking dpkg. Like + options this must be specified in list notation. The commands + are invoked in order using /bin/sh, should any fail APT + will abort. APT will pass to the commands on standard input the + filenames of all .deb files it is going to install, one per line. + + Version 2 of this protocol dumps more information, including the + protocol version, the APT configuration space and the packages, files + and versions being changed. Version 2 is enabled by setting + DPkg::Tools::options::cmd::Version to 2. cmd is a + command given to Pre-Install-Pkgs. + + + Run-Directory + APT chdirs to this directory before invoking dpkg, the default is + /. + + + Build-options + These options are passed to &dpkg-buildpackage; when compiling packages, + the default is to disable signing and produce all binaries. + + + + + Debug options + Most of the options in the debug section are not interesting to + the normal user, however Debug::pkgProblemResolver shows + interesting output about the decisions dist-upgrade makes. + Debug::NoLocking disables file locking so APT can do some + operations as non-root and Debug::pkgDPkgPM will print out the + command line for each dpkg invokation. Debug::IdentCdrom will + disable the inclusion of statfs data in CDROM IDs. + + + Examples + &configureindex; contains a + sample configuration file showing the default values for all possible + options. + + + Files + /etc/apt/apt.conf + + + See Also + &apt-cache;, &apt-config;, &apt-preferences;. + + + &manbugs; + &manauthor; + + + diff --git a/doc/apt.ent b/doc/apt.ent index f8080762d..be90a3d77 100644 --- a/doc/apt.ent +++ b/doc/apt.ent @@ -2,144 +2,182 @@ -&docdir;examples/configure-index.gz"> -/etc/apt.conf"> +&docdir;examples/configure-index.gz"> +/etc/apt.conf"> - - - "> - - - - "> - - - - "> - - - - "> - - - - "> - - - - "> - - - - "> - - - - "> - - - - "> - - - - "> - - - - "> - - - - "> - - - - "> - - - - "> + + apt.conf + 5 + " +> + + + apt-get + 8 + " +> + + + apt-config + 8 + " +> + + + apt-cdrom + 8 + " +> + + + apt-cache + 8 + " +> + + + apt_preferences + 5 + " +> + + + sources.list + 5 + " +> + + + reportbug + 1 + " +> + + + dpkg + 8 + " +> + + + dpkg-buildpackage + 1 + " +> + + + gzip + 1 + " +> + + + dpkg-scanpackages + 8 + " +> + + + dpkg-scansources + 8 + " +> + + + dselect + 8 + " +> -
apt@packages.debian.org
- Jason Gunthorpe - 1998-2001 Jason Gunthorpe - 12 March 2001 - + +
apt@packages.debian.org
+ Jason Gunthorpe + 1998-2001 Jason Gunthorpe + 14 December 2003 + Linux + + "> Bugs</> - <para> - See the <ulink url='http://bugs.debian.org/src:apt'>APT bug page</>. + <refsect1><title>Bugs + APT bug page. If you wish to report a bug in APT, please see - /usr/share/doc/debian/bug-reporting.txt or the &reportbug; command. - + /usr/share/doc/debian/bug-reporting.txt or the + &reportbug; command. + + "> Author</> - <para> - APT was written by the APT team <email>apt@packages.debian.org</>. - </RefSect1> + <refsect1><title>Author + APT was written by the APT team apt@packages.debian.org. + + +"> + + + + 14 December 2003 + Linux + ">