1 <!-- -*- mode: sgml; mode: fold -*- -->
2 <!-- translation of version 1.4 -->
3 <!doctype refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
5 <!ENTITY % aptent SYSTEM "apt.ent.fr">
14 <refentrytitle>apt-ftparchive</>
18 <!-- Man page title -->
20 <refname>apt-ftparchive</>
21 <refpurpose>Un outil pour créer des index
27 <command>apt-ftparchive</>
28 <arg><option>-hvdsq</></arg>
29 <arg><option>--md5</></arg>
30 <arg><option>--delink</></arg>
31 <arg><option>--readonly</></arg>
32 <arg><option>--contents</></arg>
33 <arg><option>-o=<replaceable/option de configuration/</></arg>
34 <arg><option>-c=<replaceable/fichier/</></arg>
36 <arg>packages<arg choice="plain" rep="repeat"><replaceable>chemin</replaceable></arg><arg><replaceable>override</replaceable><arg><replaceable>préfixe-de-chemin</replaceable></arg></arg></arg>
37 <arg>sources<arg choice="plain" rep="repeat"><replaceable>chemin</replaceable></arg><arg><replaceable>override</replaceable><arg><replaceable>préfixe-de-chemin</replaceable></arg></arg></arg>
38 <arg>contents <arg choice="plain"><replaceable>chemin</replaceable></arg></arg>
39 <arg>generate <arg choice="plain"><replaceable>fichier-de-configuration</replaceable></arg> <arg choice="plain" rep="repeat"><replaceable>section</replaceable></arg></arg>
40 <arg>clean <arg choice="plain"><replaceable>fichier-de-configuration</replaceable></arg></arg>
45 <RefSect1><Title>Description</>
47 <command/apt-ftparchive/ est l'outil en ligne de commande qui crée les index
48 dont APT se sert pour accéder aux sources des distributions. Un index doit
49 être créé pour un site et basé sur le contenu de ce site.
52 <command/apt-ftparchive/ est un ensemble comprenant le programme
53 &dpkg-scanpackages; et toutes ses fonctionnalités via la commande
54 <literal/directory/ ; il comprend aussi un générateur de fichier « Contents »,
55 la commande <literal/contents/, et une technique élaborée pour « scripter »
56 le processus de création d'une archive complète.
59 <command/apt-ftparchive/ peut utiliser lui-même des bases de données binaires
60 pour « cacher » le contenu d'un fichier .deb ; il n'a pas besoin de programmes
61 extérieurs, sauf &gzip;. Lors d'une exécution, il vérifie les changements dans
62 les fichiers et crée les fichiers compressés voulus.
65 À moins que l'option <option/-h/ ou <option/--help/ ne soit donnée, l'une des
66 commandes suivantes doit être présente :
69 <VarListEntry><term>packages</term>
71 La commande <literal/packages/ crée un fichier « Packages » à partir d'une
72 arborescence. Elle recherche récursivement à travers le répertoire donné
73 les fichiers .deb et, pour chaque fichier trouvé, envoie l'enregistrement
74 du paquet sur la sortie standard. Cette commande est approximativement
75 équivalente à &dpkg-scanpackages;.
77 On peut se servir de l'option <option/--db/ pour demander un cache binaire.
80 <VarListEntry><term>sources</term>
82 La commande <literal/sources/ crée un index des sources à partir d'une
83 arborescence. Elle recherche récursivement à travers le répertoire donné
84 les fichiers .dsc et, pour chaque fichier trouvé, envoie l'enregistrement
85 du paquet sur la sortie standard. Cette commande est approximativement
86 équivalente à &dpkg-scansources;.
88 Quand on précise un fichier « override », c'est un fichier source avec une
89 extension .src qui est recherché. On peut se servir de l'option
90 <option/--source-override/ pour changer de fichier source d'« override ».
93 <VarListEntry><term>contents</term>
95 La commande <literal/contents/ crée un fichier « Contents » à partir d'une
96 arborescence. Elle recherche récursivement à travers le répertoire donné
97 les fichiers .deb et, pour chaque fichier trouvé, lit la liste des
98 fichiers. Elle trie la liste des fichiers correspondant à des paquets et
99 l'envoie sur la sortie standard. Les répertoires ne font pas partie du
100 résultat. Quand un fichier appartient à plusieurs paquets, une virgule
103 On peut se servir de l'option <option/--db/ pour demander un cache binaire.
106 <VarListEntry><term>generate</term>
108 La commande <literal/generate/ est conçue pour être exécutable par le
109 programme cron et elle crée un index en suivant le fichier de configuration
110 donné. Le langage de configuration fournit un moyen souple de préciser
111 index et répertoires aussi bien que les paramètres requis.
114 <VarListEntry><term>clean</term>
116 La commande <literal/clean/ range les bases de données utilisées par le
117 fichier de configuration en supprimant les enregistrements qui ne sont
124 <RefSect1><Title>Configuration de la commande generate</>
126 La commande <literal/generate/ utilise un fichier de configuration pour
127 décrire l'archive qui va être créée. Le format de ce fichier est le format
128 ISC classique utilisé par des outils ISC comme bind 8 et dhcpd. &apt-conf;
129 décrit ce format. Il faut noter que l'analyse de ce fichier se fait
130 par section tandis que celle d'&apt-conf; se fait par arborescence. Cela
131 n'affecte que l'usage de l'étiquette de visée (scope tag).
134 Ce fichier de configuration possède quatre sections, décrites ci-dessous.
136 <refsect2><title>La section Dir</>
138 La section <literal/Dir/ définit les répertoires standards où situer les
139 fichiers nécessaires au processus de création. Ces répertoires sont
140 précédés de chemins relatifs définis dans les sections suivantes de manière
141 à produire un chemin absolu et complet.
143 <VarListEntry><term>ArchiveDir</term>
145 Indique la racine de l'archive FTP ; Pour une configuration Debian classique,
146 c'est le répertoire qui contient le fichier <filename/ls-LR/, et les noeuds
150 <VarListEntry><term>OverrideDir</term>
152 Indique l'emplacement des fichiers d'« override ».
155 <VarListEntry><term>CacheDir</term>
157 Indique l'emplacement des fichiers de cache.
160 <VarListEntry><term>FileListDir</term>
162 Indique l'emplacement des fichiers contenant la liste des fichiers (si on se
163 sert de la valeur <literal/FileList/ définie plus bas).
168 <refsect2><title>La section Default</>
170 La section <literal/Default/ précise les valeurs par défaut et les paramètres
171 qui contrôlent la marche du générateur. Ces valeurs peuvent être annulées dans
172 d'autres sections (paramètrage par section).
174 <VarListEntry><term>Packages::Compress</term>
176 Indique comment sont compressés les fichiers d'index. C'est une chaîne qui
177 contient des valeurs séparées par des espaces ; elle contient au moins l'une
178 des valeurs suivantes : « . » (pas de compression), « gzip », « bzip2 ».
179 Par défaut, c'est la chaîne « . gzip ».
182 <VarListEntry><term>Packages::Extensions</term>
184 Indique la liste par défaut des extensions de fichier qui constituent des
185 fichiers-paquets. Par défaut, c'est « .deb ».
188 <VarListEntry><term>Sources::Compress</term>
190 Identique à <literal/Packages::Compress/ mais précise comment sont compressés
191 les fichiers sources.
194 <VarListEntry><term>Sources::Extensions</term>
196 Indique la liste par défaut des extensions de fichier qui constituent des
197 fichiers sources. Par défaut, c'est « .dsc ».
200 <VarListEntry><term>Contents::Compress</term>
202 Identique à <literal/Packages::Compress/ mais précise comment sont compressés
203 les fichiers « Contents ».
206 <VarListEntry><term>DeLinkLimit</term>
208 Indique le nombre de kilooctets à délier (et à remplacer par des liens en dur)
209 pour chaque exécution. On s'en sert, pour chaque section, avec le paramètre
210 <literal/External-Links/.
213 <VarListEntry><term>FileMode</term>
215 Indique le système de permissions des fichiers d'index créés. Par défaut,
216 c'est le mode 0644. Tous les fichiers d'index ont ce mode et le masque
217 utilisateur (umasq) est ignoré.
222 <refsect2><title>La section TreeDefault</>
224 On indique les valeurs par défaut particulières à la section « Tree ». Toutes
225 ces variables sont des variables de substitution ; les chaînes $(DIST),
226 $(SECTION) et $(ARCH) sont remplacées par leur valeur respective.
229 <VarListEntry><term>MaxContentsChange</term>
231 Indique le nombre de kilooctets de fichiers « Contents » qui sont
232 crées chaque jour. Les fichiers « Contents » sont tirés au sort
233 selon le système <emphasis>round-robin</emphasis> de manière que, sur
234 plusieurs jours, tous soient reconstruits.
237 <VarListEntry><term>ContentsAge</term>
239 Contrôle le nombre de jours pendant lequel un fichier « Contents » peut être
240 utilisé sans actualisation. Quand cette limite est franchie, le « mtime »
241 du fichier « Contents » est mis à jour. Cela peut arriver quand un fichier
242 est modifié sans que cela modifie le fichier « Contents » (modification
243 par « override » par exemple). Un délai est permis dans l'espoir que de
244 nouveaux « .deb » seront installés, exigeant un nouveau « Contents ». Par
245 défaut ce nombre vaut 10, l'unité étant le jour.
248 <VarListEntry><term>Directory</term>
250 Indique la racine de l'arborescence des « .deb ». Par défaut, c'est
251 <filename>$(DIST)/$(SECTION)/binary-$(ARCH)/</>.
254 <VarListEntry><term>Packages</term>
256 Indique le fichier « Packages » crée. Par défaut, c'est
257 <filename>$(DIST)/$(SECTION)/binary-$(ARCH)/Packages</>.
260 <VarListEntry><term>Sources</term>
262 Indique le fichier « Packages » crée. Par défaut, c'est
263 <filename>$(DIST)/$(SECTION)/source/Sources</>.
266 <VarListEntry><term>InternalPrefix</term>
268 Indique un préfixe de chemin ; ce préfixe fait qu'un lien symbolique sera
269 considéré comme un lien interne plutôt que comme un lien externe. Par défaut,
270 c'est <filename>$(DIST)/$(SECTION)/</>.
273 <VarListEntry><term>Contents</term>
275 Indique le fichier « Contents » crée. Par défaut, c'est
276 <filename>$(DIST)/Contents-$(ARCH)</>. Quand le paramètrage fait que
277 différents fichiers « Packages » se réfèrent à un seul fichier « Contents »,
278 <command/apt-ftparchive/ les intègre automatiquement.
281 <VarListEntry><term>Contents::Header</term>
283 Indique l'en-tête à préfixer au fichier « Contents » crée.
286 <VarListEntry><term>BinCacheDB</term>
288 Indique la base de donnée binaire servant de cache pour cette section.
289 Différentes sections peuvent partager cette base de données.
292 <VarListEntry><term>FileList</term>
294 Indique qu'au lieu de lire l'arborescence, <command/apt-ftparchive/ doit lire
295 la liste de fichiers dans le fichier donné en argument. Les noms relatifs
296 sont préfixés par le répertoire de l'archive.
299 <VarListEntry><term>SourceFileList</term>
301 Indique qu'au lieu de lire l'arborescence, <command/apt-ftparchive/ doit lire
302 la liste de fichiers dans le fichier donné en argument. Les noms relatifs
303 sont préfixés par le répertoire de l'archive. On s'en sert pour créer des
309 <refsect2><title>La section Tree</>
311 La section <literal/Tree/ définit une arborescence debian classique avec
312 un répertoire de base, différentes sections dans ce répertoire et
313 différentes architectures dans chaque section. Le chemin exact est défini
314 par la variable de substitution <literal/Directory/.
316 La section <literal/Tree/ accepte une étiquette de visée (scope tag) qui
317 détermine la variable <literal/$(DIST)/ et la racine de l'arborescence
318 (le chemin est préfixé par <literal/ArchiveDir/). C'est par exemple :
319 <filename>dists/woody</>.
321 Tous les paramètres définis dans la section <literal/TreeDefault/ peuvent
322 s'utiliser dans la section <literal/Tree/ ainsi que les trois nouvelles
325 Quand il exécute la section <literal/Tree/, <command/apt-ftparchive/
327 <informalexample><programlisting>
329 for j in Architectures do
330 Generate for DIST=scope SECTION=i ARCH=j
331 </programlisting></informalexample>
334 <VarListEntry><term>Sections</term>
336 C'est une liste de sections séparées par des espaces qui appartiennent à une
337 distribution ; classiquement, on trouve <literal/main contrib non-free/.
340 <VarListEntry><term>Architectures</term>
342 C'est une liste de toutes les architectures qui appartiennent à chaque
343 section. L'architecture spéciale « source » indique que l'arborescence
344 est une arborescence de sources.
347 <VarListEntry><term>BinOverride</term>
349 Indique le fichier binaire d'« override ». le fichier d'« override » contient
350 des informations sur la section, la priorité et le responsable de paquet.
353 <VarListEntry><term>SrcOverride</term>
355 Indique le fichier source d'« override ». Le fichier d'« override » contient
356 des informations sur la section.
361 <refsect2><title>La section BinDirectory</>
363 La section <literal/bindirectory/ définit une arborescence binaire sans
364 structure particulière. L'étiquette de visée (scope tag) indique l'emplacement
365 du répertoire binaire et le paramètrage est identique à celui pour la
366 section <literal/Tree/ sans substitution de variables ou au paramètrage de
367 <literal>Section</><literal>Architecture</>.
369 <VarListEntry><term>Packages</term>
371 Indique le fichier « Packages » crée.
374 <VarListEntry><term>SrcPackages</term>
376 Indique le fichier « Sources » crée. L'un des deux fichiers,
377 <literal/Packages/ ou <literal/SrcPackages/ est nécessaire.
380 <VarListEntry><term>Contents</term>
382 Indique le fichier « Contents » crée.
385 <VarListEntry><term>Binoverride</term>
387 Indique le fichier binaire d'« override ».
390 <VarListEntry><term>SrcOverride</term>
392 Indique le fichier source d'« override ».
395 <VarListEntry><term>BinCacheDB</term>
397 Indique une base de données cache.
400 <VarListEntry><term>PathPrefix</term>
402 Ajoute un chemin à tous les chemins créés.
405 <VarListEntry><term>FileList, SourceFileList</term>
407 Indique le fichier contenant la liste des fichiers.
413 <RefSect1><Title>Le fichier binaire « Override »</>
415 Le fichier binaire « Override » est pleinement compatible avec
416 &dpkg-scanpackages;. Il contient quatre champs séparés par des espaces. Le
417 premier est le nom du paquet ; le deuxième est la priorité à donner à ce
418 paquet ; le troisième est sa section et le dernier champ est un champ pour
419 une permutation du responsable du paquet.
421 Le champ du responsable est de cette forme :
422 <literallayout>old [// oldn]* => new</literallayout>
424 <literallayout>new</literallayout>
425 La première forme permet de spécifier de vieilles adresses dans une liste (le
426 séparateur est la double barre oblique). Si l'une de ces deux formes est
427 rencontrée, la valeur de new remplace la valeur du champ. La deuxième forme
428 remplace inconditionnellement le champ.
431 <RefSect1><title>Le fichier Source « Override »</>
433 Le fichier Source « Override » est pleinement compatible avec
434 &dpkg-scansources;. Il contient deux champs. Le premier est le nom du paquet
435 source; le second, sa section.
438 <RefSect1><Title>Les options</>
442 <VarListEntry><term><option/--md5/</>
444 Créer la somme de contrôle MD5. Cette option est activée par défaut. Quand
445 elle est désactivée, les fichiers d'index n'ont pas les champs MD5Sum là où
447 Élément de configuration : <literal/APT::FTPArchive::MD5/.
450 <VarListEntry><term><option/-d/</><term><option/--db/</>
452 Utiliser une base de données binaire pour cache. Cela n'a aucun effet sur la
454 Élément de configuration : <literal/APT::FTPArchive::DB/.
457 <VarListEntry><term><option/-q/</><term><option/--quiet/</>
459 Mode silencieux ; cette commande produit une sortie destinée à l'enregistrement
460 dans un fichier journal en omettant les indicateurs de progression.
461 Un plus grand nombre de « q » (2 au plus) produit un plus grand silence.
462 On peut aussi utiliser <option/-q=#/ pour positionner le niveau de silence,
463 et annuler le fichier de configuration.
464 Élément de configuration : <literal/quiet/.
467 <VarListEntry><term><option/--delink/</>
469 Faire une déliaison. Si <literal/External-Links/ est activé, cette option
470 permet réellement la déliaison des fichiers. Par défaut, elle est activée mais
471 elle peut être désactivée avec l'option <option/--no-delink/.
472 Élément de configuration : <literal/APT::FTPArchive::DeLinkAct/.
475 <VarListEntry><term><option/--contents/</>
477 Permettre la création d'un fichier « Contents ». Quand cette option est
478 activée et que les index sont créés sous forme de base de données binaire,
479 la liste des fichiers est aussi extraite et conservée dans la base de données
480 pour un usage futur. Avec la commande generate, cette option permet la
481 création de fichiers « Contents ». Par défaut, elle est activée.
482 Élément de configuration : <literal/APT::FTPArchive::Contents/.
485 <VarListEntry><term><option/-s/</><term><option/--source-override/</>
487 Indique le fichier source d'« override » à utiliser avec la commande
489 Élément de configuration : <literal/APT::FTPArchive::SourceOverride/.
492 <VarListEntry><term><option/--readonly/</>
494 N'autoriser que la lecture pour les bases de données de cache.
495 Élément de configuration : <literal/APT::FTPArchive::ReadOnlyDB/.
503 <RefSect1><Title>Voir aussi</>
508 <RefSect1><Title>Diagnostics</>
510 <command/apt-ftparchive/ retourne zéro si tout se passe bien, le nombre
511 décimal 100 en cas d'erreur.