From 851b6a097165af4d51c0db01b5e05256e5006896 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 11:00:48 +0200 Subject: Adding upstream version 2.6.1. Signed-off-by: Daniel Baumann --- doc/apt-ftparchive.1.xml | 627 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 627 insertions(+) create mode 100644 doc/apt-ftparchive.1.xml (limited to 'doc/apt-ftparchive.1.xml') diff --git a/doc/apt-ftparchive.1.xml b/doc/apt-ftparchive.1.xml new file mode 100644 index 0000000..871b986 --- /dev/null +++ b/doc/apt-ftparchive.1.xml @@ -0,0 +1,627 @@ + + %aptent; + %aptverbatiment; + %aptvendor; +]> + + + + + &apt-author.jgunthorpe; + &apt-author.team; + &apt-email; + &apt-product; + + 2023-01-29T00:00:00Z + + + + apt-ftparchive + 1 + APT + + + + + apt-ftparchive + Utility to generate index files + + + &synopsis-command-apt-ftparchive; + + 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. + + + + + 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. + + + + + 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. + + + + + 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. + + + + + The release command generates a Release file from a + directory tree. It recursively searches the given directory for + uncompressed and compressed Packages, + Sources, Contents, + Components and icons files as + well as Release, Index and + md5sum.txt files by default + (APT::FTPArchive::Release::Default-Patterns). + Additional filename patterns can be added by listing them in + APT::FTPArchive::Release::Patterns. It then writes to + stdout a Release file containing (by default) an MD5, + SHA1, SHA256 and SHA512 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, + NotAutomatic, ButAutomaticUpgrades, + Acquire-By-Hash, Valid-Until, + Signed-By, Architectures, + Components and Description. + + + + + + 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. + + + + + 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 four separate sections, each described below. + + <literal>Dir</literal> Section + + The Dir section defines the standard directories needed to + locate the files required during the generation process. These + directories are prepended certain relative paths defined in later + sections to produce a complete an absolute path. + + + + Specifies the root of the FTP archive, in a standard + Debian configuration this is the directory that contains the + ls-LR and dist nodes. + + + + + Specifies the location of the override files. + + + + + Specifies the location of the cache files. + + + + + Specifies the location of the file list files, + if the FileList setting is used below. + + + + + <literal>Default</literal> 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. + + + + 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 the compressors configured via the + configuration scope. + The default for all compression schemes is '. gzip'. + + + + + Sets the default list of file extensions that are package files. + This defaults to '.deb'. + + + + + This is similar to Packages::Compress + except that it controls the compression for the Sources files. + + + + + Sets the default list of file extensions that are source files. + This defaults to '.dsc'. + + + + + This is similar to Packages::Compress + except that it controls the compression for the Contents files. + + + + + This is similar to Packages::Compress + except that it controls the compression for the Translation-en master file. + + + + + 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. + + + + + 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. + + + + + Specifies whether long descriptions should be included in the Packages file or split + out into a master Translation-en file. + + + + + <literal>TreeDefault</literal> 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. + + + + + 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. + + + + + 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. + + + + + Sets the top of the .deb directory tree. Defaults to + $(DIST)/$(SECTION)/binary-$(ARCH)/ + + + + + Sets the top of the source package directory tree. Defaults to + $(DIST)/$(SECTION)/source/ + + + + + Sets the output Packages file. Defaults to + $(DIST)/$(SECTION)/binary-$(ARCH)/Packages + + + + + Sets the output Sources file. Defaults to + $(DIST)/$(SECTION)/source/Sources + + + + + Sets the output Translation-en master file with the long descriptions if they + should be not included in the Packages file. Defaults to + $(DIST)/$(SECTION)/i18n/Translation-en + + + + + Sets the path prefix that causes a symlink to be + considered an internal link instead of an external link. Defaults to + $(DIST)/$(SECTION)/ + + + + + Sets the output Contents file. Defaults to + $(DIST)/$(SECTION)/Contents-$(ARCH). If this setting causes multiple + Packages files to map onto a single Contents file (as is the default) + then apt-ftparchive will integrate those package files + together automatically. + + + + + Sets header file to prepend to the contents output. + + + + + Sets the binary cache database to use for this + section. Multiple sections can share the same database. + + + + + 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. + + + + + 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 indexes. + + + + + <literal>Tree</literal> 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/&debian-stable-codename;. + + All of the settings defined in the TreeDefault section can be + used 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 + + + + + + This is a space separated list of sections which appear + under the distribution; typically this is something like + main contrib non-free non-free-firmware + + + + + 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. The architecture 'all' signals that + architecture specific files like Packages should not + include information about architecture all packages in + all files as they will be available in a dedicated file. + + + + + + Specifies whether long descriptions should be included in the Packages file or split + out into a master Translation-en file. + + + + + Sets the binary override file. The override file + contains section, priority and maintainer address information. + + + + + Sets the source override file. The override file + contains section information. + + + + + Sets the binary extra override file. + + + + + Sets the source extra override file. + + + + + <literal>BinDirectory</literal> 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. + + + + Sets the Packages file output. + + + + + Sets the Sources file output. At least one of + Packages or Sources is required. + + + + + Sets the Contents file output (optional). + + + + + Sets the binary override file. + + + + + Sets the source override file. + + + + + Sets the binary extra override file. + + + + + Sets the source extra override file. + + + + + Sets the cache DB. + + + + + Appends a path to all the output paths. + + + + + Specifies the file list file. + + + + + + + The Binary Override File + The binary override file is fully compatible with &dpkg-scanpackages;. It + contains four 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 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 two fields separated by spaces. The first field 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 three 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 the given checksum. These options default to on, when turned off the generated + index files will not have the checksum fields where possible. + Configuration Items: APT::FTPArchive::Checksum and + APT::FTPArchive::Index::Checksum where + Index can be Packages, Sources or + Release and Checksum can be MD5, + SHA1, SHA256 or SHA512. + + + + + 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. + + + + Accept in the packages and contents + commands only package files matching *_arch.deb or + *_all.deb instead of all package files in the given path. + Configuration Item: APT::FTPArchive::Architecture. + + + + + &apt-ftparchive; caches as much as possible of metadata in a cachedb. If packages + are recompiled and/or republished with the same version again, this will lead to problems + as the now outdated cached metadata like size and checksums will be used. With this option + enabled this will no longer happen as it will be checked if the file was changed. + Note that this option is set to "false" by default as it is not recommend + to upload multiple versions/builds of a package with the same version number, so in theory + nobody will have these problems and therefore all these extra checks are useless. + + + + + + This configuration option defaults to "true" and should only be set to + "false" if the Archive generated with &apt-ftparchive; also provides + Translation files. Note that the Translation-en + master file can only be created in the generate command. + + + + &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; + + -- cgit v1.2.3