doc/apt-ftparchive.1

   1 .\"     Title: apt\-ftparchive
   2 .\"    Author: Jason Gunthorpe
   3 .\" Generator: DocBook XSL Stylesheets v1.71.0 <http://docbook.sf.net/>
   4 .\"      Date: 29 February 2004
   5 .\"    Manual:
   6 .\"    Source: Linux
   7 .\"
   8 .TH "APT\-FTPARCHIVE" "1" "29 February 2004" "Linux" ""
   9 .\" disable hyphenation
  10 .nh
  11 .\" disable justification (adjust text to left margin only)
  12 .ad l
  13 .SH "NAME"
  14 apt\-ftparchive \- Utility to generate index files
  15 .SH "SYNOPSIS"
  16 .HP 15
  17 \fBapt\-ftparchive\fR [\fB\-hvdsq\fR] [\fB\-\-md5\fR] [\fB\-\-delink\fR] [\fB\-\-readonly\fR] [\fB\-\-contents\fR] [\fB\-o=\fR\fB\fIconfig\ string\fR\fR] [\fB\-c=\fR\fB\fIfile\fR\fR] {[packages\ \fIpath\fR...\ [\fIoverride\fR\ [\fIpathprefix\fR]]] | [sources\ \fIpath\fR...\ [\fIoverride\fR\ [\fIpathprefix\fR]]] | [contents\ \fIpath\fR] | [release\ \fIpath\fR] | [generate\ \fIconfig\-file\fR\ \fIsection\fR...] | [clean\ \fIconfig\-file\fR]}
  18 .SH "DESCRIPTION"
  19 .PP
  20 \fBapt\-ftparchive\fR
  21 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.
  22 .PP
  23 \fBapt\-ftparchive\fR
  24 is a superset of the
  25 \fBdpkg\-scanpackages\fR(8)
  26 program, incorporating its entire functionality via the
  27 packages
  28 command. It also contains a contents file generator,
  29 contents, and an elaborate means to 'script' the generation process for a complete archive.
  30 .PP
  31 Internally
  32 \fBapt\-ftparchive\fR
  33 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
  34 \fBgzip\fR(1). When doing a full generate it automatically performs file\-change checks and builds the desired compressed output files.
  35 .PP
  36 Unless the
  37 \fB\-h\fR, or
  38 \fB\-\-help\fR
  39 option is given one of the commands below must be present.
  40 .PP
  41 packages
  42 .RS 3n
  43 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
  44 \fBdpkg\-scanpackages\fR(8).
  45 .sp
  46 The option
  47 \fB\-\-db\fR
  48 can be used to specify a binary caching DB.
  49 .RE
  50 .PP
  51 sources
  52 .RS 3n
  53 The
  54 sources
  55 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
  56 \fBdpkg\-scansources\fR(8).
  57 .sp
  58 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.
  59 .RE
  60 .PP
  61 contents
  62 .RS 3n
  63 The
  64 contents
  65 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.
  66 .sp
  67 The option
  68 \fB\-\-db\fR
  69 can be used to specify a binary caching DB.
  70 .RE
  71 .PP
  72 release
  73 .RS 3n
  74 The
  75 release
  76 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.
  77 .sp
  78 Values for the additional metadata fields in the Release file are taken from the corresponding variables under
  79 APT::FTPArchive::Release, e.g.
  80 APT::FTPArchive::Release::Origin. The supported fields are:
  81 Origin,
  82 Label,
  83 Suite,
  84 Version,
  85 Codename,
  86 Date,
  87 Architectures,
  88 Components,
  89 Description.
  90 .RE
  91 .PP
  92 generate
  93 .RS 3n
  94 The
  95 generate
  96 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.
  97 .RE
  98 .PP
  99 clean
 100 .RS 3n
 101 The
 102 clean
 103 command tidies the databases used by the given configuration file by removing any records that are no longer necessary.
 104 .RE
 105 .SH "THE GENERATE CONFIGURATION"
 106 .PP
 107 The
 108 generate
 109 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.
 110 \fBapt.conf\fR(5)
 111 contains a description of the syntax. Note that the generate configuration is parsed in sectional manner, but
 112 \fBapt.conf\fR(5)
 113 is parsed in a tree manner. This only effects how the scope tag is handled.
 114 .PP
 115 The generate configuration has 4 separate sections, each described below.
 116 .SS "Dir Section"
 117 .PP
 118 The
 119 Dir
 120 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.
 121 .PP
 122 ArchiveDir
 123 .RS 3n
 124 Specifies the root of the FTP archive, in a standard Debian configuration this is the directory that contains the
 125 \fIls\-LR\fR
 126 and dist nodes.
 127 .RE
 128 .PP
 129 OverrideDir
 130 .RS 3n
 131 Specifies the location of the override files.
 132 .RE
 133 .PP
 134 CacheDir
 135 .RS 3n
 136 Specifies the location of the cache files
 137 .RE
 138 .PP
 139 FileListDir
 140 .RS 3n
 141 Specifies the location of the file list files, if the
 142 FileList
 143 setting is used below.
 144 .RE
 145 .SS "Default Section"
 146 .PP
 147 The
 148 Default
 149 section specifies default values, and settings that control the operation of the generator. Other sections may override these defaults with a per\-section setting.
 150 .PP
 151 Packages::Compress
 152 .RS 3n
 153 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'.
 154 .RE
 155 .PP
 156 Packages::Extensions
 157 .RS 3n
 158 Sets the default list of file extensions that are package files. This defaults to '.deb'.
 159 .RE
 160 .PP
 161 Sources::Compress
 162 .RS 3n
 163 This is similar to
 164 Packages::Compress
 165 except that it controls the compression for the Sources files.
 166 .RE
 167 .PP
 168 Sources::Extensions
 169 .RS 3n
 170 Sets the default list of file extensions that are source files. This defaults to '.dsc'.
 171 .RE
 172 .PP
 173 Contents::Compress
 174 .RS 3n
 175 This is similar to
 176 Packages::Compress
 177 except that it controls the compression for the Contents files.
 178 .RE
 179 .PP
 180 DeLinkLimit
 181 .RS 3n
 182 Specifies the number of kilobytes to delink (and replace with hard links) per run. This is used in conjunction with the per\-section
 183 External\-Links
 184 setting.
 185 .RE
 186 .PP
 187 FileMode
 188 .RS 3n
 189 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.
 190 .RE
 191 .SS "TreeDefault Section"
 192 .PP
 193 Sets defaults specific to
 194 Tree
 195 sections. All of these variables are substitution variables and have the strings $(DIST), $(SECTION) and $(ARCH) replaced with their respective values.
 196 .PP
 197 MaxContentsChange
 198 .RS 3n
 199 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.
 200 .RE
 201 .PP
 202 ContentsAge
 203 .RS 3n
 204 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.
 205 .RE
 206 .PP
 207 Directory
 208 .RS 3n
 209 Sets the top of the .deb directory tree. Defaults to
 210 \fI$(DIST)/$(SECTION)/binary\-$(ARCH)/\fR
 211 .RE
 212 .PP
 213 SrcDirectory
 214 .RS 3n
 215 Sets the top of the source package directory tree. Defaults to
 216 \fI$(DIST)/$(SECTION)/source/\fR
 217 .RE
 218 .PP
 219 Packages
 220 .RS 3n
 221 Sets the output Packages file. Defaults to
 222 \fI$(DIST)/$(SECTION)/binary\-$(ARCH)/Packages\fR
 223 .RE
 224 .PP
 225 Sources
 226 .RS 3n
 227 Sets the output Packages file. Defaults to
 228 \fI$(DIST)/$(SECTION)/source/Sources\fR
 229 .RE
 230 .PP
 231 InternalPrefix
 232 .RS 3n
 233 Sets the path prefix that causes a symlink to be considered an internal link instead of an external link. Defaults to
 234 \fI$(DIST)/$(SECTION)/\fR
 235 .RE
 236 .PP
 237 Contents
 238 .RS 3n
 239 Sets the output Contents file. Defaults to
 240 \fI$(DIST)/Contents\-$(ARCH)\fR. If this setting causes multiple Packages files to map onto a single Contents file (such as the default) then
 241 \fBapt\-ftparchive\fR
 242 will integrate those package files together automatically.
 243 .RE
 244 .PP
 245 Contents::Header
 246 .RS 3n
 247 Sets header file to prepend to the contents output.
 248 .RE
 249 .PP
 250 BinCacheDB
 251 .RS 3n
 252 Sets the binary cache database to use for this section. Multiple sections can share the same database.
 253 .RE
 254 .PP
 255 FileList
 256 .RS 3n
 257 Specifies that instead of walking the directory tree,
 258 \fBapt\-ftparchive\fR
 259 should read the list of files from the given file. Relative files names are prefixed with the archive directory.
 260 .RE
 261 .PP
 262 SourceFileList
 263 .RS 3n
 264 Specifies that instead of walking the directory tree,
 265 \fBapt\-ftparchive\fR
 266 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.
 267 .RE
 268 .SS "Tree Section"
 269 .PP
 270 The
 271 Tree
 272 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
 273 Directory
 274 substitution variable.
 275 .PP
 276 The
 277 Tree
 278 section takes a scope tag which sets the
 279 $(DIST)
 280 variable and defines the root of the tree (the path is prefixed by
 281 ArchiveDir). Typically this is a setting such as
 282 \fIdists/woody\fR.
 283 .PP
 284 All of the settings defined in the
 285 TreeDefault
 286 section can be use in a
 287 Tree
 288 section as well as three new variables.
 289 .PP
 290 When processing a
 291 Tree
 292 section
 293 \fBapt\-ftparchive\fR
 294 performs an operation similar to:
 295 .sp .RS 3n .nf for i in Sections do for j in Architectures do Generate for DIST=scope SECTION=i ARCH=j .fi .RE
 296 .PP
 297 Sections
 298 .RS 3n
 299 This is a space separated list of sections which appear under the distribution, typically this is something like
 300 main contrib non\-free
 301 .RE
 302 .PP
 303 Architectures
 304 .RS 3n
 305 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.
 306 .RE
 307 .PP
 308 BinOverride
 309 .RS 3n
 310 Sets the binary override file. The override file contains section, priority and maintainer address information.
 311 .RE
 312 .PP
 313 SrcOverride
 314 .RS 3n
 315 Sets the source override file. The override file contains section information.
 316 .RE
 317 .PP
 318 ExtraOverride
 319 .RS 3n
 320 Sets the binary extra override file.
 321 .RE
 322 .PP
 323 SrcExtraOverride
 324 .RS 3n
 325 Sets the source extra override file.
 326 .RE
 327 .SS "BinDirectory Section"
 328 .PP
 329 The
 330 bindirectory
 331 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
 332 Tree
 333 section with no substitution variables or
 334 SectionArchitecture
 335 settings.
 336 .PP
 337 Packages
 338 .RS 3n
 339 Sets the Packages file output.
 340 .RE
 341 .PP
 342 Sources
 343 .RS 3n
 344 Sets the Sources file output. At least one of
 345 Packages
 346 or
 347 Sources
 348 is required.
 349 .RE
 350 .PP
 351 Contents
 352 .RS 3n
 353 Sets the Contents file output. (optional)
 354 .RE
 355 .PP
 356 BinOverride
 357 .RS 3n
 358 Sets the binary override file.
 359 .RE
 360 .PP
 361 SrcOverride
 362 .RS 3n
 363 Sets the source override file.
 364 .RE
 365 .PP
 366 ExtraOverride
 367 .RS 3n
 368 Sets the binary extra override file.
 369 .RE
 370 .PP
 371 SrcExtraOverride
 372 .RS 3n
 373 Sets the source extra override file.
 374 .RE
 375 .PP
 376 BinCacheDB
 377 .RS 3n
 378 Sets the cache DB.
 379 .RE
 380 .PP
 381 PathPrefix
 382 .RS 3n
 383 Appends a path to all the output paths.
 384 .RE
 385 .PP
 386 FileList, SourceFileList
 387 .RS 3n
 388 Specifies the file list file.
 389 .RE
 390 .SH "THE BINARY OVERRIDE FILE"
 391 .PP
 392 The binary override file is fully compatible with
 393 \fBdpkg\-scanpackages\fR(8). 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.
 394 .PP
 395 The general form of the maintainer field is:
 396 .sp
 397 .RS 3n
 398 .nf
 399 old [// oldn]* => new
 400 .fi
 401 .RE
 402 .sp
 403 or simply,
 404 .sp
 405 .RS 3n
 406 .nf
 407 new
 408 .fi
 409 .RE
 410 .sp
 411 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.
 412 .SH "THE SOURCE OVERRIDE FILE"
 413 .PP
 414 The source override file is fully compatible with
 415 \fBdpkg\-scansources\fR(8). It contains 2 fields separated by spaces. The first fields is the source package name, the second is the section to assign it.
 416 .SH "THE EXTRA OVERRIDE FILE"
 417 .PP
 418 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.
 419 .SH "OPTIONS"
 420 .PP
 421 All command line options may be set using the configuration file, the descriptions indicate the configuration option to set. For boolean options you can override the config file by using something like
 422 \fB\-f\-\fR,\fB\-\-no\-f\fR,
 423 \fB\-f=no\fR
 424 or several other variations.
 425 .PP
 426 \fB\-\-md5\fR
 427 .RS 3n
 428 Generate MD5 sums. This defaults to on, when turned off the generated index files will not have MD5Sum fields where possible. Configuration Item:
 429 APT::FTPArchive::MD5
 430 .RE
 431 .PP
 432 \fB\-d\fR, \fB\-\-db\fR
 433 .RS 3n
 434 Use a binary caching DB. This has no effect on the generate command. Configuration Item:
 435 APT::FTPArchive::DB.
 436 .RE
 437 .PP
 438 \fB\-q\fR, \fB\-\-quiet\fR
 439 .RS 3n
 440 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
 441 \fB\-q=#\fR
 442 to set the quiet level, overriding the configuration file. Configuration Item:
 443 quiet.
 444 .RE
 445 .PP
 446 \fB\-\-delink\fR
 447 .RS 3n
 448 Perform Delinking. If the
 449 External\-Links
 450 setting is used then this option actually enables delinking of the files. It defaults to on and can be turned off with
 451 \fB\-\-no\-delink\fR. Configuration Item:
 452 APT::FTPArchive::DeLinkAct.
 453 .RE
 454 .PP
 455 \fB\-\-contents\fR
 456 .RS 3n
 457 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:
 458 APT::FTPArchive::Contents.
 459 .RE
 460 .PP
 461 \fB\-s\fR, \fB\-\-source\-override\fR
 462 .RS 3n
 463 Select the source override file to use with the
 464 sources
 465 command. Configuration Item:
 466 APT::FTPArchive::SourceOverride.
 467 .RE
 468 .PP
 469 \fB\-\-readonly\fR
 470 .RS 3n
 471 Make the caching databases read only. Configuration Item:
 472 APT::FTPArchive::ReadOnlyDB.
 473 .RE
 474 .PP
 475 \fB\-h\fR, \fB\-\-help\fR
 476 .RS 3n
 477 Show a short usage summary.
 478 .RE
 479 .PP
 480 \fB\-v\fR, \fB\-\-version\fR
 481 .RS 3n
 482 Show the program version.
 483 .RE
 484 .PP
 485 \fB\-c\fR, \fB\-\-config\-file\fR
 486 .RS 3n
 487 Configuration File; Specify a configuration file to use. The program will read the default configuration file and then this configuration file. See
 488 \fBapt.conf\fR(5)
 489 for syntax information.
 490 .RE
 491 .PP
 492 \fB\-o\fR, \fB\-\-option\fR
 493 .RS 3n
 494 Set a Configuration Option; This will set an arbitary configuration option. The syntax is
 495 \fB\-o Foo::Bar=bar\fR.
 496 .RE
 497 .SH "EXAMPLES"
 498 .PP
 499 To create a compressed Packages file for a directory containing binary packages (.deb):
 500 .sp
 501 .RS 3n
 502 .nf
 503 \fBapt\-ftparchive\fR packages \fIdirectory\fR | \fBgzip\fR > \fIPackages.gz\fR
 504 .fi
 505 .RE
 506 .SH "SEE ALSO"
 507 .PP
 508 \fBapt.conf\fR(5)
 509 .SH "DIAGNOSTICS"
 510 .PP
 511 \fBapt\-ftparchive\fR
 512 returns zero on normal operation, decimal 100 on error.
 513 .SH "BUGS"
 514 .PP
 515 [1]\&\fIAPT bug page\fR. If you wish to report a bug in APT, please see
 516 \fI/usr/share/doc/debian/bug\-reporting.txt\fR
 517 or the
 518 \fBreportbug\fR(1)
 519 command.
 520 .SH "AUTHORS"
 521 .PP
 522 \fBJason Gunthorpe\fR
 523 .sp -1n
 524 .IP "" 3n
 525 Author.
 526 .PP
 527 \fBAPT team\fR
 528 .sp -1n
 529 .IP "" 3n
 530 Author.
 531 .SH "REFERENCES"
 532 .TP 3
 533 1.\ APT bug page
 534 \%http://bugs.debian.org/src:apt