apt-helper: Check that we can open stdout
[apt.git] / doc / apt-ftparchive.1.xml
CommitLineData
24f6490f 1<?xml version="1.0" encoding="utf-8" standalone="no"?>
81cf16a2
DK
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
5abbf5bb
DK
4<!ENTITY % aptent SYSTEM "apt.ent"> %aptent;
5<!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment;
6<!ENTITY % aptvendor SYSTEM "apt-vendor.ent"> %aptvendor;
24f6490f
AL
7]>
8
9<refentry>
5e80de29
AL
10
11 <refentryinfo>
12 &apt-author.jgunthorpe;
13 &apt-author.team;
14 &apt-email;
15 &apt-product;
16 <!-- The last update date -->
6257bfdb 17 <date>2015-09-13T00:00:00Z</date>
5e80de29 18 </refentryinfo>
24f6490f
AL
19
20 <refmeta>
21 <refentrytitle>apt-ftparchive</refentrytitle>
22 <manvolnum>1</manvolnum>
f0599b9c 23 <refmiscinfo class="manual">APT</refmiscinfo>
24f6490f
AL
24 </refmeta>
25
26 <!-- Man page title -->
27 <refnamediv>
28 <refname>apt-ftparchive</refname>
29 <refpurpose>Utility to generate index files</refpurpose>
30 </refnamediv>
31
6e8b4572
DK
32 &synopsis-command-apt-ftparchive;
33
24f6490f
AL
34 <refsect1><title>Description</title>
35 <para><command>apt-ftparchive</command> is the command line tool that generates the index
36 files that APT uses to access a distribution source. The index files should
37 be generated on the origin site based on the content of that site.</para>
38
39 <para><command>apt-ftparchive</command> is a superset of the &dpkg-scanpackages; program,
40 incorporating its entire functionality via the <literal>packages</literal> command.
41 It also contains a contents file generator, <literal>contents</literal>, and an
42 elaborate means to 'script' the generation process for a complete
43 archive.</para>
44
45 <para>Internally <command>apt-ftparchive</command> can make use of binary databases to
46 cache the contents of a .deb file and it does not rely on any external
47 programs aside from &gzip;. When doing a full generate it automatically
48 performs file-change checks and builds the desired compressed output files.</para>
49
aec22160
DK
50 <para>Unless the <option>-h</option>, or <option>--help</option> option is given,
51 one of the commands below must be present.</para>
24f6490f
AL
52
53 <variablelist>
2b9b27c3 54 <varlistentry><term><option>packages</option></term>
24f6490f
AL
55 <listitem><para>
56 The packages command generates a package file from a directory tree. It
57 takes the given directory and recursively searches it for .deb files,
58 emitting a package record to stdout for each. This command is
59 approximately equivalent to &dpkg-scanpackages;.</para>
60
61 <para>The option <option>--db</option> can be used to specify a binary caching DB.</para></listitem>
62 </varlistentry>
63
2b9b27c3 64 <varlistentry><term><option>sources</option></term>
24f6490f
AL
65 <listitem><para>
66 The <literal>sources</literal> command generates a source index file from a directory tree.
67 It takes the given directory and recursively searches it for .dsc files,
68 emitting a source record to stdout for each. This command is approximately
69 equivalent to &dpkg-scansources;.</para>
70 <para>
71 If an override file is specified then a source override file will be
72 looked for with an extension of .src. The --source-override option can be
73 used to change the source override file that will be used.</para></listitem>
74 </varlistentry>
75
2b9b27c3 76 <varlistentry><term><option>contents</option></term>
24f6490f
AL
77 <listitem><para>
78 The <literal>contents</literal> command generates a contents file from a directory tree. It
79 takes the given directory and recursively searches it for .deb files,
80 and reads the file list from each file. It then sorts and writes to stdout
81 the list of files matched to packages. Directories are not written to
82 the output. If multiple packages own the same file then each package is
83 separated by a comma in the output.</para>
84 <para>
85 The option <option>--db</option> can be used to specify a binary caching DB.</para></listitem>
86 </varlistentry>
87
2b9b27c3 88 <varlistentry><term><option>release</option></term>
24f6490f
AL
89 <listitem><para>
90 The <literal>release</literal> command generates a Release file from a
3cb3fe76 91 directory tree. It recursively searches the given directory for uncompressed
a4396982 92 <filename>Packages</filename> and <filename>Sources</filename> files and ones
3cb3fe76
DK
93 compressed with <command>gzip</command>, <command>bzip2</command> or <command>lzma</command>
94 as well as <filename>Release</filename> and <filename>md5sum.txt</filename> files by default
95 (<literal>APT::FTPArchive::Release::Default-Patterns</literal>). Additional filename patterns
96 can be added by listing them in <literal>APT::FTPArchive::Release::Patterns</literal>.
9e446491
DK
97 It then writes to stdout a <filename>Release</filename> file containing (by default) an MD5,
98 SHA1, SHA256 and SHA512 digest for each file.</para>
24f6490f
AL
99 <para>
100 Values for the additional metadata fields in the Release file are
101 taken from the corresponding variables under
102 <literal>APT::FTPArchive::Release</literal>,
103 e.g. <literal>APT::FTPArchive::Release::Origin</literal>. The supported fields
104 are: <literal>Origin</literal>, <literal>Label</literal>, <literal>Suite</literal>,
105 <literal>Version</literal>, <literal>Codename</literal>, <literal>Date</literal>,
c99e48ec
DK
106 <literal>Valid-Until</literal>, <literal>Architectures</literal>,
107 <literal>Components</literal>, <literal>Description</literal>.</para></listitem>
24f6490f
AL
108
109 </varlistentry>
110
2b9b27c3 111 <varlistentry><term><option>generate</option></term>
24f6490f
AL
112 <listitem><para>
113 The <literal>generate</literal> command is designed to be runnable from a cron script and
114 builds indexes according to the given config file. The config language
115 provides a flexible means of specifying which index files are built from
116 which directories, as well as providing a simple means of maintaining the
117 required settings.</para></listitem>
118 </varlistentry>
119
2b9b27c3 120 <varlistentry><term><option>clean</option></term>
24f6490f
AL
121 <listitem><para>
122 The <literal>clean</literal> command tidies the databases used by the given
123 configuration file by removing any records that are no longer necessary.</para></listitem>
124 </varlistentry>
125 </variablelist>
126 </refsect1>
127
128 <refsect1><title>The Generate Configuration</title>
129 <para>
130 The <literal>generate</literal> command uses a configuration file to describe the
131 archives that are going to be generated. It follows the typical ISC
132 configuration format as seen in ISC tools like bind 8 and dhcpd.
133 &apt-conf; contains a description of the syntax. Note that the generate
134 configuration is parsed in sectional manner, but &apt-conf; is parsed in a
135 tree manner. This only effects how the scope tag is handled.</para>
136
137 <para>
a4396982 138 The generate configuration has four separate sections, each described below.</para>
24f6490f 139
aec22160 140 <refsect2><title><literal>Dir</literal> Section</title>
24f6490f
AL
141 <para>
142 The <literal>Dir</literal> section defines the standard directories needed to
143 locate the files required during the generation process. These
5f4331c4 144 directories are prepended certain relative paths defined in later
24f6490f
AL
145 sections to produce a complete an absolute path.</para>
146 <variablelist>
2b9b27c3 147 <varlistentry><term><option>ArchiveDir</option></term>
24f6490f
AL
148 <listitem><para>
149 Specifies the root of the FTP archive, in a standard
150 Debian configuration this is the directory that contains the
151 <filename>ls-LR</filename> and dist nodes.</para></listitem>
152 </varlistentry>
153
2b9b27c3 154 <varlistentry><term><option>OverrideDir</option></term>
24f6490f
AL
155 <listitem><para>
156 Specifies the location of the override files.</para></listitem>
157 </varlistentry>
158
2b9b27c3 159 <varlistentry><term><option>CacheDir</option></term>
24f6490f 160 <listitem><para>
a4396982 161 Specifies the location of the cache files.</para></listitem>
24f6490f
AL
162 </varlistentry>
163
2b9b27c3 164 <varlistentry><term><option>FileListDir</option></term>
24f6490f
AL
165 <listitem><para>
166 Specifies the location of the file list files,
167 if the <literal>FileList</literal> setting is used below.</para></listitem>
168 </varlistentry>
169 </variablelist>
170 </refsect2>
171
aec22160 172 <refsect2><title><literal>Default</literal> Section</title>
24f6490f
AL
173 <para>
174 The <literal>Default</literal> section specifies default values, and settings
175 that control the operation of the generator. Other sections may override
176 these defaults with a per-section setting.</para>
177 <variablelist>
2b9b27c3 178 <varlistentry><term><option>Packages::Compress</option></term>
24f6490f
AL
179 <listitem><para>
180 Sets the default compression schemes to use
14301cf3 181 for the package index files. It is a string that contains a space
24f6490f
AL
182 separated list of at least one of: '.' (no compression), 'gzip' and
183 'bzip2'. The default for all compression schemes is '. gzip'.</para></listitem>
184 </varlistentry>
185
2b9b27c3 186 <varlistentry><term><option>Packages::Extensions</option></term>
24f6490f
AL
187 <listitem><para>
188 Sets the default list of file extensions that are package files.
189 This defaults to '.deb'.</para></listitem>
190 </varlistentry>
191
2b9b27c3 192 <varlistentry><term><option>Sources::Compress</option></term>
24f6490f
AL
193 <listitem><para>
194 This is similar to <literal>Packages::Compress</literal>
195 except that it controls the compression for the Sources files.</para></listitem>
196 </varlistentry>
197
2b9b27c3 198 <varlistentry><term><option>Sources::Extensions</option></term>
24f6490f
AL
199 <listitem><para>
200 Sets the default list of file extensions that are source files.
201 This defaults to '.dsc'.</para></listitem>
202 </varlistentry>
203
2b9b27c3 204 <varlistentry><term><option>Contents::Compress</option></term>
24f6490f
AL
205 <listitem><para>
206 This is similar to <literal>Packages::Compress</literal>
207 except that it controls the compression for the Contents files.</para></listitem>
208 </varlistentry>
34f1d96c 209
2b9b27c3 210 <varlistentry><term><option>Translation::Compress</option></term>
34f1d96c
DK
211 <listitem><para>
212 This is similar to <literal>Packages::Compress</literal>
213 except that it controls the compression for the Translation-en master file.</para></listitem>
214 </varlistentry>
215
2b9b27c3 216 <varlistentry><term><option>DeLinkLimit</option></term>
24f6490f
AL
217 <listitem><para>
218 Specifies the number of kilobytes to delink (and
219 replace with hard links) per run. This is used in conjunction with the
220 per-section <literal>External-Links</literal> setting.</para></listitem>
221 </varlistentry>
222
2b9b27c3 223 <varlistentry><term><option>FileMode</option></term>
24f6490f
AL
224 <listitem><para>
225 Specifies the mode of all created index files. It
226 defaults to 0644. All index files are set to this mode with no regard
227 to the umask.</para></listitem>
228 </varlistentry>
34f1d96c 229
2b9b27c3 230 <varlistentry><term><option>LongDescription</option></term>
34f1d96c 231 <listitem><para>
a4396982
JR
232 Specifies whether long descriptions should be included in the <filename>Packages</filename> file or split
233 out into a master <filename>Translation-en</filename> file.</para></listitem>
34f1d96c 234 </varlistentry>
24f6490f
AL
235 </variablelist>
236 </refsect2>
237
aec22160 238 <refsect2><title><literal>TreeDefault</literal> Section</title>
24f6490f
AL
239 <para>
240 Sets defaults specific to <literal>Tree</literal> sections. All of these
241 variables are substitution variables and have the strings $(DIST),
242 $(SECTION) and $(ARCH) replaced with their respective values.</para>
243
244 <variablelist>
2b9b27c3 245 <varlistentry><term><option>MaxContentsChange</option></term>
24f6490f
AL
246 <listitem><para>
247 Sets the number of kilobytes of contents
248 files that are generated each day. The contents files are round-robined
249 so that over several days they will all be rebuilt.</para></listitem>
250 </varlistentry>
251
2b9b27c3 252 <varlistentry><term><option>ContentsAge</option></term>
24f6490f
AL
253 <listitem><para>
254 Controls the number of days a contents file is allowed
255 to be checked without changing. If this limit is passed the mtime of the
256 contents file is updated. This case can occur if the package file is
257 changed in such a way that does not result in a new contents file
258 [override edit for instance]. A hold off is allowed in hopes that new
259 .debs will be installed, requiring a new file anyhow. The default is 10,
260 the units are in days.</para></listitem>
261 </varlistentry>
262
2b9b27c3 263 <varlistentry><term><option>Directory</option></term>
24f6490f
AL
264 <listitem><para>
265 Sets the top of the .deb directory tree. Defaults to
266 <filename>$(DIST)/$(SECTION)/binary-$(ARCH)/</filename></para></listitem>
267 </varlistentry>
268
2b9b27c3 269 <varlistentry><term><option>SrcDirectory</option></term>
24f6490f
AL
270 <listitem><para>
271 Sets the top of the source package directory tree. Defaults to
272 <filename>$(DIST)/$(SECTION)/source/</filename></para></listitem>
273 </varlistentry>
274
2b9b27c3 275 <varlistentry><term><option>Packages</option></term>
24f6490f
AL
276 <listitem><para>
277 Sets the output Packages file. Defaults to
278 <filename>$(DIST)/$(SECTION)/binary-$(ARCH)/Packages</filename></para></listitem>
279 </varlistentry>
280
2b9b27c3 281 <varlistentry><term><option>Sources</option></term>
24f6490f 282 <listitem><para>
c6474fb6 283 Sets the output Sources file. Defaults to
24f6490f
AL
284 <filename>$(DIST)/$(SECTION)/source/Sources</filename></para></listitem>
285 </varlistentry>
4e794c50 286
2b9b27c3 287 <varlistentry><term><option>Translation</option></term>
4e794c50 288 <listitem><para>
a4396982 289 Sets the output Translation-en master file with the long descriptions if they
4e794c50
DK
290 should be not included in the Packages file. Defaults to
291 <filename>$(DIST)/$(SECTION)/i18n/Translation-en</filename></para></listitem>
4e794c50
DK
292 </varlistentry>
293
2b9b27c3 294 <varlistentry><term><option>InternalPrefix</option></term>
24f6490f
AL
295 <listitem><para>
296 Sets the path prefix that causes a symlink to be
297 considered an internal link instead of an external link. Defaults to
298 <filename>$(DIST)/$(SECTION)/</filename></para></listitem>
299 </varlistentry>
300
2b9b27c3 301 <varlistentry><term><option>Contents</option></term>
24f6490f
AL
302 <listitem><para>
303 Sets the output Contents file. Defaults to
3adddfa8 304 <filename>$(DIST)/$(SECTION)/Contents-$(ARCH)</filename>. If this setting causes multiple
a4396982 305 Packages files to map onto a single Contents file (as is the default)
24f6490f
AL
306 then <command>apt-ftparchive</command> will integrate those package files
307 together automatically.</para></listitem>
308 </varlistentry>
309
2b9b27c3 310 <varlistentry><term><option>Contents::Header</option></term>
24f6490f
AL
311 <listitem><para>
312 Sets header file to prepend to the contents output.</para></listitem>
313 </varlistentry>
314
2b9b27c3 315 <varlistentry><term><option>BinCacheDB</option></term>
24f6490f
AL
316 <listitem><para>
317 Sets the binary cache database to use for this
318 section. Multiple sections can share the same database.</para></listitem>
319 </varlistentry>
320
2b9b27c3 321 <varlistentry><term><option>FileList</option></term>
24f6490f
AL
322 <listitem><para>
323 Specifies that instead of walking the directory tree,
324 <command>apt-ftparchive</command> should read the list of files from the given
325 file. Relative files names are prefixed with the archive directory.</para></listitem>
326 </varlistentry>
327
2b9b27c3 328 <varlistentry><term><option>SourceFileList</option></term>
24f6490f
AL
329 <listitem><para>
330 Specifies that instead of walking the directory tree,
331 <command>apt-ftparchive</command> should read the list of files from the given
332 file. Relative files names are prefixed with the archive directory.
e3a1f08d 333 This is used when processing source indexes.</para></listitem>
24f6490f
AL
334 </varlistentry>
335 </variablelist>
336 </refsect2>
337
aec22160 338 <refsect2><title><literal>Tree</literal> Section</title>
24f6490f
AL
339 <para>
340 The <literal>Tree</literal> section defines a standard Debian file tree which
341 consists of a base directory, then multiple sections in that base
342 directory and finally multiple Architectures in each section. The exact
343 pathing used is defined by the <literal>Directory</literal> substitution variable.</para>
344 <para>
345 The <literal>Tree</literal> section takes a scope tag which sets the
346 <literal>$(DIST)</literal> variable and defines the root of the tree
347 (the path is prefixed by <literal>ArchiveDir</literal>).
e1dd65c9 348 Typically this is a setting such as <filename>dists/&stable-codename;</filename>.</para>
24f6490f
AL
349 <para>
350 All of the settings defined in the <literal>TreeDefault</literal> section can be
a4396982 351 used in a <literal>Tree</literal> section as well as three new variables.</para>
24f6490f
AL
352 <para>
353 When processing a <literal>Tree</literal> section <command>apt-ftparchive</command>
354 performs an operation similar to:
f8b832bd 355 <programlisting>
24f6490f
AL
356for i in Sections do
357 for j in Architectures do
358 Generate for DIST=scope SECTION=i ARCH=j
f8b832bd 359 </programlisting></para>
24f6490f
AL
360
361 <variablelist>
2b9b27c3 362 <varlistentry><term><option>Sections</option></term>
24f6490f
AL
363 <listitem><para>
364 This is a space separated list of sections which appear
a4396982 365 under the distribution; typically this is something like
24f6490f
AL
366 <literal>main contrib non-free</literal></para></listitem>
367 </varlistentry>
368
2b9b27c3 369 <varlistentry><term><option>Architectures</option></term>
24f6490f 370 <listitem><para>
1dd20368
DK
371 This is a space separated list of all the architectures that appear under
372 search section. The special architecture 'source' is used to indicate
373 that this tree has a source archive. The architecture 'all' signals that
374 architecture specific files like <filename>Packages</filename> should not
375 include information about architecture <literal>all</literal> packages in
376 all files as they will be available in a dedicated file.
377 </para></listitem>
24f6490f 378 </varlistentry>
4e794c50 379
2b9b27c3 380 <varlistentry><term><option>LongDescription</option></term>
4e794c50 381 <listitem><para>
a4396982
JR
382 Specifies whether long descriptions should be included in the <filename>Packages</filename> file or split
383 out into a master <filename>Translation-en</filename> file.</para></listitem>
4e794c50
DK
384 </varlistentry>
385
2b9b27c3 386 <varlistentry><term><option>BinOverride</option></term>
24f6490f
AL
387 <listitem><para>
388 Sets the binary override file. The override file
389 contains section, priority and maintainer address information.</para></listitem>
390 </varlistentry>
391
2b9b27c3 392 <varlistentry><term><option>SrcOverride</option></term>
24f6490f
AL
393 <listitem><para>
394 Sets the source override file. The override file
395 contains section information.</para></listitem>
396 </varlistentry>
397
2b9b27c3 398 <varlistentry><term><option>ExtraOverride</option></term>
24f6490f
AL
399 <listitem><para>
400 Sets the binary extra override file.</para></listitem>
401 </varlistentry>
402
2b9b27c3 403 <varlistentry><term><option>SrcExtraOverride</option></term>
24f6490f
AL
404 <listitem><para>
405 Sets the source extra override file.</para></listitem>
406 </varlistentry>
407 </variablelist>
408 </refsect2>
409
aec22160 410 <refsect2><title><literal>BinDirectory</literal> Section</title>
24f6490f
AL
411 <para>
412 The <literal>bindirectory</literal> section defines a binary directory tree
413 with no special structure. The scope tag specifies the location of
414 the binary directory and the settings are similar to the <literal>Tree</literal>
415 section with no substitution variables or
416 <literal>Section</literal><literal>Architecture</literal> settings.</para>
417 <variablelist>
2b9b27c3 418 <varlistentry><term><option>Packages</option></term>
24f6490f
AL
419 <listitem><para>
420 Sets the Packages file output.</para></listitem>
421 </varlistentry>
422
2b9b27c3 423 <varlistentry><term><option>Sources</option></term>
24f6490f
AL
424 <listitem><para>
425 Sets the Sources file output. At least one of
168e1e4e 426 <literal>Packages</literal> or <literal>Sources</literal> is required.</para></listitem>
24f6490f
AL
427 </varlistentry>
428
2b9b27c3 429 <varlistentry><term><option>Contents</option></term>
24f6490f 430 <listitem><para>
a4396982 431 Sets the Contents file output (optional).</para></listitem>
24f6490f
AL
432 </varlistentry>
433
2b9b27c3 434 <varlistentry><term><option>BinOverride</option></term>
24f6490f
AL
435 <listitem><para>
436 Sets the binary override file.</para></listitem>
437 </varlistentry>
438
2b9b27c3 439 <varlistentry><term><option>SrcOverride</option></term>
24f6490f
AL
440 <listitem><para>
441 Sets the source override file.</para></listitem>
442 </varlistentry>
443
2b9b27c3 444 <varlistentry><term><option>ExtraOverride</option></term>
24f6490f
AL
445 <listitem><para>
446 Sets the binary extra override file.</para></listitem>
447 </varlistentry>
448
2b9b27c3 449 <varlistentry><term><option>SrcExtraOverride</option></term>
24f6490f
AL
450 <listitem><para>
451 Sets the source extra override file.</para></listitem>
452 </varlistentry>
453
2b9b27c3 454 <varlistentry><term><option>BinCacheDB</option></term>
24f6490f
AL
455 <listitem><para>
456 Sets the cache DB.</para></listitem>
457 </varlistentry>
458
2b9b27c3 459 <varlistentry><term><option>PathPrefix</option></term>
24f6490f
AL
460 <listitem><para>
461 Appends a path to all the output paths.</para></listitem>
462 </varlistentry>
463
2b9b27c3 464 <varlistentry><term><option>FileList</option></term><term><option>SourceFileList</option></term>
24f6490f
AL
465 <listitem><para>
466 Specifies the file list file.</para></listitem>
467 </varlistentry>
468 </variablelist>
469 </refsect2>
470 </refsect1>
471
472
473 <refsect1><title>The Binary Override File</title>
474 <para>The binary override file is fully compatible with &dpkg-scanpackages;. It
a4396982
JR
475 contains four fields separated by spaces. The first field is the package name,
476 the second is the priority to force that package to, the third is
24f6490f
AL
477 the section to force that package to and the final field is the maintainer
478 permutation field.</para>
479 <para>The general form of the maintainer field is:
480 <literallayout>old [// oldn]* => new</literallayout>
481 or simply,
482 <literallayout>new</literallayout>
483 The first form allows a double-slash separated list of old email addresses
484 to be specified. If any of those are found then new is substituted for the
485 maintainer field. The second form unconditionally substitutes the
486 maintainer field.</para>
487 </refsect1>
488
489
490 <refsect1><title>The Source Override File</title>
491 <para>
492 The source override file is fully compatible with &dpkg-scansources;. It
a4396982 493 contains two fields separated by spaces. The first field is the source
24f6490f
AL
494 package name, the second is the section to assign it.</para>
495 </refsect1>
496
497 <refsect1><title>The Extra Override File</title>
498 <para>
499 The extra override file allows any arbitrary tag to be added or replaced
a4396982 500 in the output. It has three columns, the first is the package, the second is
24f6490f
AL
501 the tag and the remainder of the line is the new value.</para>
502 </refsect1>
503
504 <refsect1><title>options</title>
505 &apt-cmdblurb;
506
507 <variablelist>
9e446491
DK
508 <varlistentry>
509 <term><option>--md5</option></term>
510 <term><option>--sha1</option></term>
511 <term><option>--sha256</option></term>
512 <term><option>--sha512</option></term>
24f6490f 513 <listitem><para>
3c54407f
DK
514 Generate the given checksum. These options default to on, when turned off the generated
515 index files will not have the checksum fields where possible.
516 Configuration Items: <literal>APT::FTPArchive::<replaceable>Checksum</replaceable></literal> and
517 <literal>APT::FTPArchive::<replaceable>Index</replaceable>::<replaceable>Checksum</replaceable></literal> where
1fc8c922
MV
518 <literal><replaceable>Index</replaceable></literal> can be <literal>Packages</literal>, <literal>Sources</literal> or
519 <literal>Release</literal> and <literal><replaceable>Checksum</replaceable></literal> can be <literal>MD5</literal>,
9e446491 520 <literal>SHA1</literal>, <literal>SHA256</literal> or <literal>SHA512</literal>.</para></listitem>
24f6490f
AL
521 </varlistentry>
522
523 <varlistentry><term><option>-d</option></term><term><option>--db</option></term>
524 <listitem><para>
525 Use a binary caching DB. This has no effect on the generate command.
526 Configuration Item: <literal>APT::FTPArchive::DB</literal>.</para></listitem>
527 </varlistentry>
528
529 <varlistentry><term><option>-q</option></term><term><option>--quiet</option></term>
530 <listitem><para>
531 Quiet; produces output suitable for logging, omitting progress indicators.
532 More q's will produce more quiet up to a maximum of 2. You can also use
533 <option>-q=#</option> to set the quiet level, overriding the configuration file.
534 Configuration Item: <literal>quiet</literal>.</para></listitem>
535 </varlistentry>
536
537 <varlistentry><term><option>--delink</option></term>
538 <listitem><para>
539 Perform Delinking. If the <literal>External-Links</literal> setting is used then
540 this option actually enables delinking of the files. It defaults to on and
541 can be turned off with <option>--no-delink</option>.
542 Configuration Item: <literal>APT::FTPArchive::DeLinkAct</literal>.</para></listitem>
543 </varlistentry>
544
545 <varlistentry><term><option>--contents</option></term>
546 <listitem><para>
547 Perform contents generation. When this option is set and package indexes
548 are being generated with a cache DB then the file listing will also be
549 extracted and stored in the DB for later use. When using the generate
550 command this option also allows the creation of any Contents files. The
551 default is on.
552 Configuration Item: <literal>APT::FTPArchive::Contents</literal>.</para></listitem>
553 </varlistentry>
554
555 <varlistentry><term><option>-s</option></term><term><option>--source-override</option></term>
556 <listitem><para>
557 Select the source override file to use with the <literal>sources</literal> command.
558 Configuration Item: <literal>APT::FTPArchive::SourceOverride</literal>.</para></listitem>
559 </varlistentry>
560
561 <varlistentry><term><option>--readonly</option></term>
562 <listitem><para>
563 Make the caching databases read only.
564 Configuration Item: <literal>APT::FTPArchive::ReadOnlyDB</literal>.</para></listitem>
31981076
DK
565 </varlistentry>
566
567 <varlistentry><term><option>-a</option></term><term><option>--arch</option></term>
568 <listitem><para>Accept in the <literal>packages</literal> and <literal>contents</literal>
569 commands only package files matching <literal>*_arch.deb</literal> or
570 <literal>*_all.deb</literal> instead of all package files in the given path.
571 Configuration Item: <literal>APT::FTPArchive::Architecture</literal>.</para></listitem>
572 </varlistentry>
9c24493f 573
ff574e76
DK
574 <varlistentry><term><option>APT::FTPArchive::AlwaysStat</option></term>
575 <listitem><para>
31981076 576 &apt-ftparchive; caches as much as possible of metadata in a cachedb. If packages
ff574e76
DK
577 are recompiled and/or republished with the same version again, this will lead to problems
578 as the now outdated cached metadata like size and checksums will be used. With this option
579 enabled this will no longer happen as it will be checked if the file was changed.
580 Note that this option is set to "<literal>false</literal>" by default as it is not recommend
581 to upload multiply versions/builds of a package with the same versionnumber, so in theory
582 nobody will have these problems and therefore all these extra checks are useless.
583 </para></listitem>
584 </varlistentry>
585
9c24493f
DK
586 <varlistentry><term><option>APT::FTPArchive::LongDescription</option></term>
587 <listitem><para>
588 This configuration option defaults to "<literal>true</literal>" and should only be set to
589 <literal>"false"</literal> if the Archive generated with &apt-ftparchive; also provides
4e794c50
DK
590 <filename>Translation</filename> files. Note that the <filename>Translation-en</filename>
591 master file can only be created in the generate command.
9c24493f
DK
592 </para></listitem>
593 </varlistentry>
594
24f6490f 595 &apt-commonoptions;
1dd20368 596
24f6490f
AL
597 </variablelist>
598 </refsect1>
599
600<refsect1><title>Examples</title>
601
602<para>To create a compressed Packages file for a directory containing
603binary packages (.deb):
604
605<programlisting>
606<command>apt-ftparchive</command> packages <replaceable>directory</replaceable> | <command>gzip</command> > <filename>Packages.gz</filename>
607</programlisting></para>
608
609</refsect1>
610
611 <refsect1><title>See Also</title>
612 <para>&apt-conf;</para>
613 </refsect1>
614
615 <refsect1><title>Diagnostics</title>
616 <para><command>apt-ftparchive</command> returns zero on normal operation, decimal 100 on error.</para>
617 </refsect1>
618
619 &manbugs;
24f6490f
AL
620
621</refentry>