diff options
Diffstat (limited to 'doc/apt-ftparchive.1.sgml')
| -rw-r--r-- | doc/apt-ftparchive.1.sgml | 571 |
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> |