diff options
Diffstat (limited to 'doc/apt-ftparchive.1.sgml')
| -rw-r--r-- | doc/apt-ftparchive.1.sgml | 507 |
1 files changed, 507 insertions, 0 deletions
diff --git a/doc/apt-ftparchive.1.sgml b/doc/apt-ftparchive.1.sgml new file mode 100644 index 000000000..f05765650 --- /dev/null +++ b/doc/apt-ftparchive.1.sgml @@ -0,0 +1,507 @@ +<!-- -*- 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>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 it's entire functionality via the <literal/directory/ 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 above + commands 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>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 decsription 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 decribed 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 + [overried 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>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 + that <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 + that <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 seach 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> + </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>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 sperated 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>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>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> |