summaryrefslogtreecommitdiff
path: root/doc/apt-ftparchive.1.sgml
diff options
context:
space:
mode:
authorArch Librarian <arch@canonical.com>2004-09-20 17:05:19 +0000
committerArch Librarian <arch@canonical.com>2004-09-20 17:05:19 +0000
commit24f6490f4ba3572069619d88e053db5cb07e846c (patch)
tree2c4774b6233e12f552dc9bde4e62e1f7fa6f9b6f /doc/apt-ftparchive.1.sgml
parent16633d164ed17530dca1d016db26176e99a02557 (diff)
* 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)
Diffstat (limited to 'doc/apt-ftparchive.1.sgml')
-rw-r--r--doc/apt-ftparchive.1.sgml571
1 files changed, 0 insertions, 571 deletions
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 @@
-<!-- -*- mode: sgml; mode: fold -*- -->
-<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
-
-<!ENTITY % aptent SYSTEM "apt.ent">
-%aptent;
-
-]>
-
-<refentry>
- &apt-docinfo;
-
- <refmeta>
- <refentrytitle>apt-ftparchive</>
- <manvolnum>1</>
- </refmeta>
-
- <!-- Man page title -->
- <refnamediv>
- <refname>apt-ftparchive</>
- <refpurpose>Utility to generate index files</>
- </refnamediv>
-
- <!-- Arguments -->
- <refsynopsisdiv>
- <cmdsynopsis>
- <command>apt-ftparchive</>
- <arg><option>-hvdsq</></arg>
- <arg><option>--md5</></arg>
- <arg><option>--delink</></arg>
- <arg><option>--readonly</></arg>
- <arg><option>--contents</></arg>
- <arg><option>-o=<replaceable/config string/</></arg>
- <arg><option>-c=<replaceable/file/</></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</>
- <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>