]>
Commit | Line | Data |
---|---|---|
1 | <!-- -*- mode: sgml; mode: fold -*- --> | |
2 | <!doctype refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [ | |
3 | ||
4 | <!ENTITY % aptent SYSTEM "apt.ent"> | |
5 | %aptent; | |
6 | ||
7 | ]> | |
8 | ||
9 | <refentry> | |
10 | &apt-docinfo; | |
11 | ||
12 | <refmeta> | |
13 | <refentrytitle>apt-ftparchive</> | |
14 | <manvolnum>1</> | |
15 | </refmeta> | |
16 | ||
17 | <!-- Man page title --> | |
18 | <refnamediv> | |
19 | <refname>apt-ftparchive</> | |
20 | <refpurpose>Utility to generate index files</> | |
21 | </refnamediv> | |
22 | ||
23 | <!-- Arguments --> | |
24 | <refsynopsisdiv> | |
25 | <cmdsynopsis> | |
26 | <command>apt-ftparchive</> | |
27 | <arg><option>-hvdsq</></arg> | |
28 | <arg><option>--md5</></arg> | |
29 | <arg><option>--delink</></arg> | |
30 | <arg><option>--readonly</></arg> | |
31 | <arg><option>--contents</></arg> | |
32 | <arg><option>-o=<replaceable/config string/</></arg> | |
33 | <arg><option>-c=<replaceable/file/</></arg> | |
34 | <group choice=req> | |
35 | <arg>packages<arg choice="plain" rep="repeat"><replaceable>path</replaceable></arg><arg><replaceable>override</replaceable><arg><replaceable>pathprefix</replaceable></arg></arg></arg> | |
36 | <arg>sources<arg choice="plain" rep="repeat"><replaceable>path</replaceable></arg><arg><replaceable>override</replaceable><arg><replaceable>pathprefix</replaceable></arg></arg></arg> | |
37 | <arg>contents <arg choice="plain"><replaceable>path</replaceable></arg></arg> | |
38 | <arg>generate <arg choice="plain"><replaceable>config-file</replaceable></arg> <arg choice="plain" rep="repeat"><replaceable>section</replaceable></arg></arg> | |
39 | <arg>clean <arg choice="plain"><replaceable>config-file</replaceable></arg></arg> | |
40 | </group> | |
41 | </cmdsynopsis> | |
42 | </refsynopsisdiv> | |
43 | ||
44 | <RefSect1><Title>Description</> | |
45 | <para> | |
46 | <command/apt-ftparchive/ is the command line tool that generates the index | |
47 | files that APT uses to access a distribution source. The index files should | |
48 | be generated on the origin site based on the content of that site. | |
49 | ||
50 | <para> | |
51 | <command/apt-ftparchive/ is a superset of the &dpkg-scanpackages; program, | |
52 | incorporating its entire functionality via the <literal/packages/ command. | |
53 | It also contains a contents file generator, <literal/contents/, and an | |
54 | elaborate means to 'script' the generation process for a complete | |
55 | archive. | |
56 | ||
57 | <para> | |
58 | Internally <command/apt-ftparchive/ can make use of binary databases to | |
59 | cache the contents of a .deb file and it does not rely on any external | |
60 | programs aside from &gzip;. When doing a full generate it automatically | |
61 | performs file-change checks and builds the desired compressed output files. | |
62 | ||
63 | <para> | |
64 | Unless the <option/-h/, or <option/--help/ option is given one of the | |
65 | commands below must be present. | |
66 | ||
67 | <VariableList> | |
68 | <VarListEntry><term>packages</term> | |
69 | <ListItem><Para> | |
70 | The packages command generates a package file from a directory tree. It | |
71 | takes the given directory and recursively searches it for .deb files, | |
72 | emitting a package record to stdout for each. This command is | |
73 | approximately equivalent to &dpkg-scanpackages;. | |
74 | <para> | |
75 | The option <option/--db/ can be used to specify a binary caching DB. | |
76 | </VarListEntry> | |
77 | ||
78 | <VarListEntry><term>sources</term> | |
79 | <ListItem><Para> | |
80 | The <literal/sources/ command generates a source index file from a directory tree. | |
81 | It takes the given directory and recursively searches it for .dsc files, | |
82 | emitting a source record to stdout for each. This command is approximately | |
83 | equivalent to &dpkg-scansources;. | |
84 | <para> | |
85 | If an override file is specified then a source override file will be | |
86 | looked for with an extension of .src. The --source-override option can be | |
87 | used to change the source override file that will be used. | |
88 | </VarListEntry> | |
89 | ||
90 | <VarListEntry><term>contents</term> | |
91 | <ListItem><Para> | |
92 | The <literal/contents/ command generates a contents file from a directory tree. It | |
93 | takes the given directory and recursively searches it for .deb files, | |
94 | and reads the file list from each file. It then sorts and writes to stdout | |
95 | the list of files matched to packages. Directories are not written to | |
96 | the output. If multiple packages own the same file then each package is | |
97 | separated by a comma in the output. | |
98 | <para> | |
99 | The option <option/--db/ can be used to specify a binary caching DB. | |
100 | </VarListEntry> | |
101 | ||
102 | <VarListEntry><term>generate</term> | |
103 | <ListItem><Para> | |
104 | The <literal/generate/ command is designed to be runnable from a cron script and | |
105 | builds indexes according to the given config file. The config language | |
106 | provides a flexible means of specifying which index files are built from | |
107 | which directories, as well as providing a simple means of maintaining the | |
108 | required settings. | |
109 | </VarListEntry> | |
110 | ||
111 | <VarListEntry><term>clean</term> | |
112 | <ListItem><Para> | |
113 | The <literal/clean/ command tidies the databases used by the given | |
114 | configuration file by removing any records that are no longer necessary. | |
115 | </VarListEntry> | |
116 | </VariableList> | |
117 | ||
118 | </RefSect1> | |
119 | ||
120 | <RefSect1><Title>The Generate Configuration</> | |
121 | <para> | |
122 | The <literal/generate/ command uses a configuration file to describe the | |
123 | archives that are going to be generated. It follows the typical ISC | |
124 | configuration format as seen in ISC tools like bind 8 and dhcpd. | |
125 | &apt-conf; contains a description of the syntax. Note that the generate | |
126 | configuration is parsed in sectional manner, but &apt-conf; is parsed in a | |
127 | tree manner. This only effects how the scope tag is handled. | |
128 | ||
129 | <para> | |
130 | The generate configuration has 4 separate sections, each described below. | |
131 | ||
132 | <refsect2><title>Dir Section</> | |
133 | <Para> | |
134 | The <literal/Dir/ section defines the standard directories needed to | |
135 | locate the files required during the generation process. These | |
136 | directories are prepended to certain relative paths defined in later | |
137 | sections to produce a complete an absolute path. | |
138 | <VariableList> | |
139 | <VarListEntry><term>ArchiveDir</term> | |
140 | <ListItem><Para> | |
141 | Specifies the root of the FTP archive, in a standard | |
142 | Debian configuration this is the directory that contains the | |
143 | <filename/ls-LR/, and dist nodes. | |
144 | </VarListEntry> | |
145 | ||
146 | <VarListEntry><term>OverrideDir</term> | |
147 | <ListItem><Para> | |
148 | Specifies the location of the override files. | |
149 | </VarListEntry> | |
150 | ||
151 | <VarListEntry><term>CacheDir</term> | |
152 | <ListItem><Para> | |
153 | Specifies the location of the cache files | |
154 | </VarListEntry> | |
155 | ||
156 | <VarListEntry><term>FileListDir</term> | |
157 | <ListItem><Para> | |
158 | Specifies the location of the file list files, | |
159 | if the <literal/FileList/ setting is used below. | |
160 | </VarListEntry> | |
161 | </VariableList> | |
162 | </refsect2> | |
163 | ||
164 | <refsect2><title>Default Section</> | |
165 | <para> | |
166 | The <literal/Default/ section specifies default values, and settings | |
167 | that control the operation of the generator. Other sections may override | |
168 | these defaults with a per-section setting. | |
169 | <VariableList> | |
170 | <VarListEntry><term>Packages::Compress</term> | |
171 | <ListItem><Para> | |
172 | Sets the default compression schemes to use | |
173 | for the Package index files. It is a string that contains a space | |
174 | separated list of at least one of: '.' (no compression), 'gzip' and | |
175 | 'bzip2'. The default for all compression schemes is '. gzip'. | |
176 | </VarListEntry> | |
177 | ||
178 | <VarListEntry><term>Packages::Extensions</term> | |
179 | <ListItem><Para> | |
180 | Sets the default list of file extensions that are package files. | |
181 | This defaults to '.deb'. | |
182 | </VarListEntry> | |
183 | ||
184 | <VarListEntry><term>Sources::Compress</term> | |
185 | <ListItem><Para> | |
186 | This is similar to <literal/Packages::Compress/ | |
187 | except that it controls the compression for the Sources files. | |
188 | </VarListEntry> | |
189 | ||
190 | <VarListEntry><term>Sources::Extensions</term> | |
191 | <ListItem><Para> | |
192 | Sets the default list of file extensions that are source files. | |
193 | This defaults to '.dsc'. | |
194 | </VarListEntry> | |
195 | ||
196 | <VarListEntry><term>Contents::Compress</term> | |
197 | <ListItem><Para> | |
198 | This is similar to <literal/Packages::Compress/ | |
199 | except that it controls the compression for the Contents files. | |
200 | </VarListEntry> | |
201 | ||
202 | <VarListEntry><term>DeLinkLimit</term> | |
203 | <ListItem><Para> | |
204 | Specifies the number of kilobytes to delink (and | |
205 | replace with hard links) per run. This is used in conjunction with the | |
206 | per-section <literal/External-Links/ setting. | |
207 | </VarListEntry> | |
208 | ||
209 | <VarListEntry><term>FileMode</term> | |
210 | <ListItem><Para> | |
211 | Specifies the mode of all created index files. It | |
212 | defaults to 0644. All index files are set to this mode with no regard | |
213 | to the umask. | |
214 | </VarListEntry> | |
215 | </VariableList> | |
216 | </refsect2> | |
217 | ||
218 | <refsect2><title>TreeDefault Section</> | |
219 | <para> | |
220 | Sets defaults specific to <literal/Tree/ sections. All of these | |
221 | variables are substitution variables and have the strings $(DIST), | |
222 | $(SECTION) and $(ARCH) replaced with their respective values. | |
223 | ||
224 | <VariableList> | |
225 | <VarListEntry><term>MaxContentsChange</term> | |
226 | <ListItem><Para> | |
227 | Sets the number of kilobytes of contents | |
228 | files that are generated each day. The contents files are round-robined | |
229 | so that over several days they will all be rebuilt. | |
230 | </VarListEntry> | |
231 | ||
232 | <VarListEntry><term>ContentsAge</term> | |
233 | <ListItem><Para> | |
234 | Controls the number of days a contents file is allowed | |
235 | to be checked without changing. If this limit is passed the mtime of the | |
236 | contents file is updated. This case can occur if the package file is | |
237 | changed in such a way that does not result in a new contents file | |
238 | [override edit for instance]. A hold off is allowed in hopes that new | |
239 | .debs will be installed, requiring a new file anyhow. The default is 10, | |
240 | the units are in days. | |
241 | </VarListEntry> | |
242 | ||
243 | <VarListEntry><term>Directory</term> | |
244 | <ListItem><Para> | |
245 | Sets the top of the .deb directory tree. Defaults to | |
246 | <filename>$(DIST)/$(SECTION)/binary-$(ARCH)/</> | |
247 | </VarListEntry> | |
248 | ||
249 | <VarListEntry><term>SrcDirectory</term> | |
250 | <ListItem><Para> | |
251 | Sets the top of the source package directory tree. Defaults to | |
252 | <filename>$(DIST)/$(SECTION)/source/</> | |
253 | </VarListEntry> | |
254 | ||
255 | <VarListEntry><term>Packages</term> | |
256 | <ListItem><Para> | |
257 | Sets the output Packages file. Defaults to | |
258 | <filename>$(DIST)/$(SECTION)/binary-$(ARCH)/Packages</> | |
259 | </VarListEntry> | |
260 | ||
261 | <VarListEntry><term>Sources</term> | |
262 | <ListItem><Para> | |
263 | Sets the output Packages file. Defaults to | |
264 | <filename>$(DIST)/$(SECTION)/source/Sources</> | |
265 | </VarListEntry> | |
266 | ||
267 | <VarListEntry><term>InternalPrefix</term> | |
268 | <ListItem><Para> | |
269 | Sets the path prefix that causes a symlink to be | |
270 | considered an internal link instead of an external link. Defaults to | |
271 | <filename>$(DIST)/$(SECTION)/</> | |
272 | </VarListEntry> | |
273 | ||
274 | <VarListEntry><term>Contents</term> | |
275 | <ListItem><Para> | |
276 | Sets the output Contents file. Defaults to | |
277 | <filename>$(DIST)/Contents-$(ARCH)</>. If this setting causes multiple | |
278 | Packages files to map onto a single Contents file (such as the default) | |
279 | then <command/apt-ftparchive/ will integrate those package files | |
280 | together automatically. | |
281 | </VarListEntry> | |
282 | ||
283 | <VarListEntry><term>Contents::Header</term> | |
284 | <ListItem><Para> | |
285 | Sets header file to prepend to the contents output. | |
286 | </VarListEntry> | |
287 | ||
288 | <VarListEntry><term>BinCacheDB</term> | |
289 | <ListItem><Para> | |
290 | Sets the binary cache database to use for this | |
291 | section. Multiple sections can share the same database. | |
292 | </VarListEntry> | |
293 | ||
294 | <VarListEntry><term>FileList</term> | |
295 | <ListItem><Para> | |
296 | Specifies that instead of walking the directory tree, | |
297 | <command/apt-ftparchive/ should read the list of files from the given | |
298 | file. Relative files names are prefixed with the archive directory. | |
299 | </VarListEntry> | |
300 | ||
301 | <VarListEntry><term>SourceFileList</term> | |
302 | <ListItem><Para> | |
303 | Specifies that instead of walking the directory tree, | |
304 | <command/apt-ftparchive/ should read the list of files from the given | |
305 | file. Relative files names are prefixed with the archive directory. | |
306 | This is used when processing source indexs. | |
307 | </VarListEntry> | |
308 | </VariableList> | |
309 | </refsect2> | |
310 | ||
311 | <refsect2><title>Tree Section</> | |
312 | <para> | |
313 | The <literal/Tree/ section defines a standard Debian file tree which | |
314 | consists of a base directory, then multiple sections in that base | |
315 | directory and finally multiple Architectures in each section. The exact | |
316 | pathing used is defined by the <literal/Directory/ substitution variable. | |
317 | <para> | |
318 | The <literal/Tree/ section takes a scope tag which sets the | |
319 | <literal/$(DIST)/ variable and defines the root of the tree | |
320 | (the path is prefixed by <literal/ArchiveDir/). | |
321 | Typically this is a setting such as <filename>dists/woody</>. | |
322 | <para> | |
323 | All of the settings defined in the <literal/TreeDefault/ section can be | |
324 | use in a <literal/Tree/ section as well as three new variables. | |
325 | <para> | |
326 | When processing a <literal/Tree/ section <command/apt-ftparchive/ | |
327 | performs an operation similar to: | |
328 | <informalexample><programlisting> | |
329 | for i in Sections do | |
330 | for j in Architectures do | |
331 | Generate for DIST=scope SECTION=i ARCH=j | |
332 | </programlisting></informalexample> | |
333 | ||
334 | <VariableList> | |
335 | <VarListEntry><term>Sections</term> | |
336 | <ListItem><Para> | |
337 | This is a space separated list of sections which appear | |
338 | under the distribution, typically this is something like | |
339 | <literal/main contrib non-free/. | |
340 | </VarListEntry> | |
341 | ||
342 | <VarListEntry><term>Architectures</term> | |
343 | <ListItem><Para> | |
344 | This is a space separated list of all the | |
345 | architectures that appear under search section. The special architecture | |
346 | 'source' is used to indicate that this tree has a source archive. | |
347 | </VarListEntry> | |
348 | ||
349 | <VarListEntry><term>BinOverride</term> | |
350 | <ListItem><Para> | |
351 | Sets the binary override file. The override file | |
352 | contains section, priority and maintainer address information. | |
353 | </VarListEntry> | |
354 | ||
355 | <VarListEntry><term>SrcOverride</term> | |
356 | <ListItem><Para> | |
357 | Sets the source override file. The override file | |
358 | contains section information. | |
359 | </VarListEntry> | |
360 | ||
361 | <VarListEntry><term>ExtraOverride</term> | |
362 | <ListItem><Para> | |
363 | Sets the binary extra override file. | |
364 | </VarListEntry> | |
365 | ||
366 | <VarListEntry><term>SrcExtraOverride</term> | |
367 | <ListItem><Para> | |
368 | Sets the source extra override file. | |
369 | </VarListEntry> | |
370 | </VariableList> | |
371 | </refsect2> | |
372 | ||
373 | <refsect2><title>BinDirectory Section</> | |
374 | <para> | |
375 | The <literal/bindirectory/ section defines a binary directory tree | |
376 | with no special structure. The scope tag specifies the location of | |
377 | the binary directory and the settings are similar to the <literal/Tree/ | |
378 | section with no substitution variables or | |
379 | <literal>Section</><literal>Architecture</> settings. | |
380 | <VariableList> | |
381 | <VarListEntry><term>Packages</term> | |
382 | <ListItem><Para> | |
383 | Sets the Packages file output. | |
384 | </VarListEntry> | |
385 | ||
386 | <VarListEntry><term>SrcPackages</term> | |
387 | <ListItem><Para> | |
388 | Sets the Sources file output. At least one of | |
389 | <literal/Packages/ or <literal/SrcPackages/ is required. | |
390 | </VarListEntry> | |
391 | ||
392 | <VarListEntry><term>Contents</term> | |
393 | <ListItem><Para> | |
394 | Sets the Contents file output. (Optional) | |
395 | </VarListEntry> | |
396 | ||
397 | <VarListEntry><term>BinOverride</term> | |
398 | <ListItem><Para> | |
399 | Sets the binary override file. | |
400 | </VarListEntry> | |
401 | ||
402 | <VarListEntry><term>SrcOverride</term> | |
403 | <ListItem><Para> | |
404 | Sets the source override file. | |
405 | </VarListEntry> | |
406 | ||
407 | <VarListEntry><term>ExtraOverride</term> | |
408 | <ListItem><Para> | |
409 | Sets the binary extra override file. | |
410 | </VarListEntry> | |
411 | ||
412 | <VarListEntry><term>SrcExtraOverride</term> | |
413 | <ListItem><Para> | |
414 | Sets the source extra override file. | |
415 | </VarListEntry> | |
416 | ||
417 | <VarListEntry><term>BinCacheDB</term> | |
418 | <ListItem><Para> | |
419 | Sets the cache DB. | |
420 | </VarListEntry> | |
421 | ||
422 | <VarListEntry><term>PathPrefix</term> | |
423 | <ListItem><Para> | |
424 | Appends a path to all the output paths. | |
425 | </VarListEntry> | |
426 | ||
427 | <VarListEntry><term>FileList, SourceFileList</term> | |
428 | <ListItem><Para> | |
429 | Specifies the file list file. | |
430 | </VarListEntry> | |
431 | </VariableList> | |
432 | </refsect2> | |
433 | </RefSect1> | |
434 | ||
435 | <RefSect1><Title>The Binary Override File</> | |
436 | <para> | |
437 | The binary override file is fully compatible with &dpkg-scanpackages;. It | |
438 | contains 4 fields separated by spaces. The first field is the package name, | |
439 | the second is the priority to force that package to, the third is the | |
440 | the section to force that package to and the final field is the maintainer | |
441 | permutation field. | |
442 | <para> | |
443 | The general form of the maintainer field is: | |
444 | <literallayout>old [// oldn]* => new</literallayout> | |
445 | or simply, | |
446 | <literallayout>new</literallayout> | |
447 | The first form allows a double-slash separated list of old email addresses | |
448 | to be specified. If any of those are found then new is substituted for the | |
449 | maintainer field. The second form unconditionally substitutes the | |
450 | maintainer field. | |
451 | </RefSect1> | |
452 | ||
453 | <RefSect1><title>The Source Override File</> | |
454 | <para> | |
455 | The source override file is fully compatible with &dpkg-scansources;. It | |
456 | contains 2 fields separated by spaces. The first fields is the source | |
457 | package name, the second is the section to assign it. | |
458 | </RefSect1> | |
459 | ||
460 | <RefSect1><title>The Extra Override File</> | |
461 | <para> | |
462 | The extra override file allows any arbitrary tag to be added or replaced | |
463 | in the output. It has 3 columns, the first is the package, the second is | |
464 | the tag and the remainder of the line is the new value. | |
465 | </RefSect1> | |
466 | ||
467 | <RefSect1><Title>Options</> | |
468 | &apt-cmdblurb; | |
469 | ||
470 | <VariableList> | |
471 | <VarListEntry><term><option/--md5/</> | |
472 | <ListItem><Para> | |
473 | Generate MD5 sums. This defaults to on, when turned off the generated | |
474 | index files will not have MD5Sum fields where possible. | |
475 | Configuration Item: <literal/APT::FTPArchive::MD5/. | |
476 | </VarListEntry> | |
477 | ||
478 | <VarListEntry><term><option/-d/</><term><option/--db/</> | |
479 | <ListItem><Para> | |
480 | Use a binary caching DB. This has no effect on the generate command. | |
481 | Configuration Item: <literal/APT::FTPArchive::DB/. | |
482 | </VarListEntry> | |
483 | ||
484 | <VarListEntry><term><option/-q/</><term><option/--quiet/</> | |
485 | <ListItem><Para> | |
486 | Quiet; produces output suitable for logging, omitting progress indicators. | |
487 | More q's will produce more quiet up to a maximum of 2. You can also use | |
488 | <option/-q=#/ to set the quiet level, overriding the configuration file. | |
489 | Configuration Item: <literal/quiet/. | |
490 | </VarListEntry> | |
491 | ||
492 | <VarListEntry><term><option/--delink/</> | |
493 | <ListItem><Para> | |
494 | Perform Delinking. If the <literal/External-Links/ setting is used then | |
495 | this option actually enables delinking of the files. It defaults to on and | |
496 | can be turned off with <option/--no-delink/. | |
497 | Configuration Item: <literal/APT::FTPArchive::DeLinkAct/. | |
498 | </VarListEntry> | |
499 | ||
500 | <VarListEntry><term><option/--contents/</> | |
501 | <ListItem><Para> | |
502 | Perform contents generation. When this option is set and package indexes | |
503 | are being generated with a cache DB then the file listing will also be | |
504 | extracted and stored in the DB for later use. When using the generate | |
505 | command this option also allows the creation of any Contents files. The | |
506 | default is on. | |
507 | Configuration Item: <literal/APT::FTPArchive::Contents/. | |
508 | </VarListEntry> | |
509 | ||
510 | <VarListEntry><term><option/-s/</><term><option/--source-override/</> | |
511 | <ListItem><Para> | |
512 | Select the source override file to use with the <literal/sources/ command. | |
513 | Configuration Item: <literal/APT::FTPArchive::SourceOverride/. | |
514 | </VarListEntry> | |
515 | ||
516 | <VarListEntry><term><option/--readonly/</> | |
517 | <ListItem><Para> | |
518 | Make the caching databases read only. | |
519 | Configuration Item: <literal/APT::FTPArchive::ReadOnlyDB/. | |
520 | </VarListEntry> | |
521 | ||
522 | &apt-commonoptions; | |
523 | ||
524 | </VariableList> | |
525 | </RefSect1> | |
526 | ||
527 | <RefSect1><Title>Examples</> | |
528 | ||
529 | <para>To create a compressed Packages file for a directory containing | |
530 | binary packages (.deb): | |
531 | ||
532 | <programlisting | |
533 | <command/apt-ftparchive/ packages <replaceable/directory/ | <command/gzip/ > <filename/Packages.gz/ | |
534 | </programlisting> | |
535 | ||
536 | </RefSect1> | |
537 | ||
538 | <RefSect1><Title>See Also</> | |
539 | <para> | |
540 | &apt-conf; | |
541 | </RefSect1> | |
542 | ||
543 | <RefSect1><Title>Diagnostics</> | |
544 | <para> | |
545 | <command/apt-ftparchive/ returns zero on normal operation, decimal 100 on error. | |
546 | </RefSect1> | |
547 | ||
548 | &manbugs; | |
549 | &manauthor; | |
550 | ||
551 | </refentry> |