Ce chapitre décrit les conventions à suivre pour écrire les Makefiles destinés aux programmes GNU. Utiliser Automake vous aidera à écrire un Makefile conforme à ces conventions. Pour en savoir plus sur les Makefiles portables, consultez la norme POSIX ainsi que la section Portable Make Programming du manuel Autoconf.
DESTDIR : prise en charge des installations par étapesTout Makefile devrait contenir la ligne suivante :
SHELL = /bin/sh
afin d'éviter les ennuis sur les systèmes où la variable SHELL risque d'être héritée de l'environnement. (Avec GNU make, ce problème ne se pose jamais.)
Certains programmes make ont des listes de suffixes et des règles implicites incompatibles entre elles, ce qui crée parfois de la confusion ou des dysfonctionnements. Il est donc judicieux de définir explicitement la liste des suffixes en n'utilisant que ceux dont vous avez besoin dans le Makefile concerné, comme ceci :
.SUFFIXES: .SUFFIXES: .c .o
La première ligne vide la liste des suffixes, la seconde introduit tous les suffixes susceptibles d'être soumis à des règles implicites dans ce Makefile.
Ne supposez pas que . (le répertoire courant) figure dans le chemin de recherche pour l'exécution des commandes. Lorsque, pendant le make, vous devez exécuter des programmes faisant partie de votre paquet, veillez à préfixer par ./ si le programme est construit dans le cadre du make, ou par $(srcdir)/ s'il s'agit d'un fichier invariable du code source. Sans l'un de ces préfixes, c'est le chemin de recherche du moment qui est utilisé.
La distinction entre ./ (le répertoire de construction) et $(srcdir)/ (le répertoire source) est importante, car l'utilisateur peut construire dans un répertoire distinct grâce à l'option « --srcdir » de configure. Une règle de la forme :
foo.1 : foo.man sedscript
sed -f sedscript foo.man > foo.1
échouera lorsque le répertoire de construction n'est pas le répertoire source, car foo.man et sedscript se trouvent dans le répertoire source.
Avec GNU make, se reposer sur « VPATH » pour trouver le fichier source fonctionne dans le cas où il n'y a qu'un seul fichier prérequis (prerequisite), puisque la variable automatique « $< » de make représente le fichier source où qu'il se trouve. (Beaucoup de versions de make ne définissent « $< » que dans les règles implicites.) Autrement dit, une cible de Makefile telle que
foo.o : bar.c
$(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
devrait plutôt s'écrire ainsi :
foo.o : bar.c
$(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@
afin que « VPATH » fonctionne correctement. Lorsque la cible a plusieurs prérequis, employer explicitement « $(srcdir) » est le moyen le plus simple de faire fonctionner correctement la règle. Par exemple, la cible foo.1 vue plus haut est mieux écrite ainsi :
foo.1 : foo.man sedscript
sed -f $(srcdir)/sedscript $(srcdir)/foo.man > $@
Les distributions GNU contiennent habituellement des fichiers qui ne sont pas des fichiers source : par exemple des fichiers Info, ainsi que la sortie d'Autoconf, Automake, Bison ou Flex. Comme ces fichiers se trouvent normalement dans le répertoire source, ils devraient toujours s'y trouver, et non dans le répertoire de construction. Par conséquent, les règles de Makefile qui les mettent à jour devraient placer les fichiers mis à jour dans le répertoire source.
En revanche, pour un fichier qui ne figure pas dans la distribution, le Makefile ne devrait pas le placer dans le répertoire source, car construire un programme dans des circonstances ordinaires ne devrait modifier le répertoire source d'aucune façon.
Efforcez-vous de faire en sorte qu'au moins les cibles de construction et d'installation (et toutes leurs sous-cibles) fonctionnent correctement avec un make parallèle.
Écrivez les commandes des Makefiles (et tout script shell, tel que configure) pour qu'elles s'exécutent sous sh (à la fois le shell Bourne traditionnel et le shell POSIX), et non sous csh. N'utilisez aucune fonctionnalité particulière de ksh ou bash, ni de fonctionnalité POSIX qui ne soit pas largement prise en charge par le sh Bourne traditionnel.
Le script configure et les règles de Makefile pour la construction et l'installation ne devraient utiliser directement aucun autre utilitaire que ceux-ci :
awk cat cmp cp diff echo expr false grep install-info ln ls mkdir mv printf pwd rm rmdir sed sleep sort tar test touch tr true
Les programmes de compression tels que gzip peuvent être utilisés dans la règle dist.
De manière générale, tenez-vous-en aux options et fonctionnalités largement prises en charge (généralement spécifiées par POSIX) de ces programmes. Par exemple, n'utilisez pas « mkdir -p », si pratique soit-il, car quelques systèmes ne le prennent pas du tout en charge et, sur d'autres, il n'est pas sûr en exécution parallèle. Pour une liste des incompatibilités connues, consultez la section Portable Shell Programming du manuel Autoconf.
Il est prudent d'éviter de créer des liens symboliques dans les makefiles, car quelques systèmes de fichiers ne les prennent pas en charge.
Les règles de Makefile pour la construction et l'installation peuvent aussi utiliser des compilateurs et des programmes apparentés, mais elles devraient le faire au travers de variables make, afin que l'utilisateur puisse les remplacer par d'autres. Voici quelques-uns des programmes auxquels nous pensons :
ar bison cc flex install ld ldconfig lex make makeinfo ranlib texi2dvi yacc
Utilisez les variables make suivantes pour exécuter ces programmes :
$(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX) $(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
Lorsque vous utilisez ranlib ou ldconfig, vous devriez vous assurer que rien de fâcheux ne se produit si le système ne dispose pas du programme en question. Faites en sorte d'ignorer une erreur de cette commande, et affichez un message avant la commande pour indiquer à l'utilisateur que l'échec de cette commande ne signifie pas qu'il y a un problème. (La macro « AC_PROG_RANLIB » d'Autoconf peut vous y aider.)
Si vous utilisez des liens symboliques, vous devriez prévoir une solution de repli pour les systèmes qui n'en disposent pas.
Les autres utilitaires utilisables au travers de variables Make sont les suivants :
chgrp chmod chown mknod
Dans les portions de Makefile (ou les scripts) destinées uniquement à des systèmes particuliers où vous savez que d'autres utilitaires existent, il est permis de les utiliser.
Les Makefiles devraient fournir des variables permettant de redéfinir certaines commandes, options, etc.
En particulier, vous devriez exécuter la plupart des programmes utilitaires au travers de variables. Ainsi, si vous utilisez Bison, prévoyez une variable nommée BISON dont la valeur par défaut est fixée par « BISON = bison », et référez-vous-y avec $(BISON) chaque fois que vous devez utiliser Bison.
Les utilitaires de gestion de fichiers tels que ln, rm, mv, etc., n'ont pas besoin d'être référencés au travers de variables de cette façon, car les utilisateurs n'ont pas besoin de les remplacer par d'autres programmes.
Chaque variable de nom de programme devrait être accompagnée d'une variable d'options servant à fournir des options au programme. Le nom de la variable d'options s'obtient en ajoutant « FLAGS » au nom de la variable de nom de programme : par exemple BISONFLAGS. (Les noms CFLAGS pour le compilateur C, YFLAGS pour yacc et LFLAGS pour lex font exception à cette règle, mais nous les conservons parce qu'ils sont standard.) Utilisez CPPFLAGS dans toute commande de compilation qui exécute le préprocesseur, et LDFLAGS dans toute commande de compilation qui effectue l'édition de liens, ainsi que dans tout usage direct de ld.
S'il existe des options du compilateur C qui doivent être utilisées pour compiler correctement certains fichiers, ne les incluez pas dans CFLAGS. Les utilisateurs s'attendent à pouvoir spécifier CFLAGS librement eux-mêmes. À la place, faites en sorte de transmettre les options nécessaires au compilateur C indépendamment de CFLAGS, en les écrivant explicitement dans les commandes de compilation ou en définissant une règle implicite, comme ceci :
CFLAGS = -g
ALL_CFLAGS = -I. $(CFLAGS)
.c.o:
$(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
Vous pouvez en revanche inclure l'option « -g » dans CFLAGS, car elle n'est pas indispensable à une compilation correcte. Considérez-la comme un simple choix par défaut recommandé. Si le paquet est conçu pour être compilé par défaut avec GCC, vous pouvez tout aussi bien inclure « -O » dans la valeur par défaut de CFLAGS.
Placez CFLAGS en dernier dans la commande de compilation, après les autres variables contenant des options du compilateur, afin que l'utilisateur puisse utiliser CFLAGS pour redéfinir les autres.
CFLAGS devrait être utilisé dans toute invocation du compilateur C, aussi bien pour la compilation que pour l'édition de liens.
Tout Makefile devrait définir la variable INSTALL, qui est la commande de base pour installer un fichier sur le système.
Tout Makefile devrait également définir les variables INSTALL_PROGRAM et INSTALL_DATA. (La valeur par défaut de INSTALL_PROGRAM devrait être $(INSTALL) ; celle de INSTALL_DATA devrait être ${INSTALL} -m 644.) Il devrait ensuite utiliser ces variables comme commandes pour l'installation effective, respectivement pour les fichiers exécutables et non exécutables. L'usage minimal de ces variables est le suivant :
$(INSTALL_PROGRAM) foo $(bindir)/foo $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
Cependant, il est préférable de prendre en charge un préfixe DESTDIR sur les fichiers cibles, comme expliqué dans la section suivante.
Il est admis, mais non obligatoire, d'installer plusieurs fichiers en une seule commande, le dernier argument étant un répertoire, comme ceci :
$(INSTALL_PROGRAM) foo bar baz $(bindir)
DESTDIR : prise en charge des installations par étapes
DESTDIR est une variable ajoutée en préfixe à chaque fichier cible installé, comme ceci :
$(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo $(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a
La variable DESTDIR est spécifiée par l'utilisateur sur la ligne de commande de make sous forme de nom de fichier absolu. Par exemple :
make DESTDIR=/tmp/stage install
DESTDIR ne devrait être pris en charge que dans les cibles install* et uninstall*, car ce sont les seules cibles où il est utile.
Si votre étape d'installation installait normalement /usr/local/bin/foo et /usr/local/lib/libfoo.a, alors une installation invoquée comme dans l'exemple ci-dessus installerait à la place /tmp/stage/usr/local/bin/foo et /tmp/stage/usr/local/lib/libfoo.a.
Ajouter ainsi la variable DESTDIR en préfixe à chaque cible permet les installations par étapes (staged installs), où les fichiers installés ne sont pas placés directement à leur emplacement attendu, mais sont d'abord copiés dans un emplacement temporaire (DESTDIR). Les fichiers installés conservent néanmoins leur structure de répertoires relative, et les noms de fichiers éventuellement incorporés ne sont pas modifiés.
Vous ne devriez jamais fixer la valeur de DESTDIR dans votre Makefile ; ainsi, par défaut, les fichiers sont installés à leur emplacement attendu. De plus, spécifier DESTDIR ne devrait en rien modifier le fonctionnement du logiciel ; sa valeur ne devrait donc être incluse dans le contenu d'aucun fichier.
La prise en charge de DESTDIR est couramment utilisée pour la création de paquets. Elle est également utile aux utilisateurs qui veulent comprendre où un paquet donné installera quoi, et permet aux utilisateurs qui n'ont pas normalement les droits d'installer dans des zones protégées de construire et d'installer avant d'obtenir ces droits. Enfin, elle peut être utile avec des outils tels que stow, où le code est installé à un endroit mais paraît installé ailleurs au moyen de liens symboliques ou d'opérations de montage particulières. C'est pourquoi, bien que ce ne soit pas une exigence absolue, nous recommandons fortement que les paquets GNU prennent en charge DESTDIR.
Les répertoires d'installation devraient toujours être désignés par des variables, afin de pouvoir facilement installer à un emplacement non standard. Les noms standard de ces variables et les valeurs qu'elles devraient avoir dans les paquets GNU sont décrits ci-dessous. Ils reposent sur une disposition standard du système de fichiers, dont des variantes sont utilisées dans GNU/Linux et d'autres systèmes d'exploitation modernes.
Les personnes qui installent sont censées pouvoir redéfinir ces valeurs lors de l'appel de make (par exemple make prefix=/usr install) ou de configure (par exemple configure --prefix=/usr). Les paquets GNU ne devraient pas essayer de deviner quelle valeur conviendrait à ces variables sur le système où ils sont installés : utilisez les réglages par défaut spécifiés ici, afin que tous les paquets GNU se comportent de façon identique, permettant à la personne qui installe d'obtenir la disposition souhaitée.
Tous les répertoires d'installation, ainsi que leurs répertoires parents, devraient être créés (si nécessaire) avant qu'on n'y installe quoi que ce soit.
Les deux premières variables fixent la racine de l'installation. Tous les autres répertoires d'installation devraient être des sous-répertoires de l'un de ces deux-là, et rien ne devrait être installé directement dans ces deux répertoires.
prefixPréfixe utilisé pour construire les valeurs par défaut des variables énumérées ci-dessous. La valeur par défaut de prefix devrait être /usr/local. Lors de la construction du système GNU complet, le préfixe sera vide et /usr sera un lien symbolique vers /. (Si vous utilisez Autoconf, écrivez-le « @prefix@ ».)
Exécuter « make install » avec une valeur de prefix différente de celle utilisée pour construire le programme ne devrait pas recompiler le programme.
exec_prefixPréfixe utilisé pour construire les valeurs par défaut de certaines des variables énumérées ci-dessous. La valeur par défaut de exec_prefix devrait être $(prefix). (Si vous utilisez Autoconf, écrivez-le « @exec_prefix@ ».)
En général, $(exec_prefix) est utilisé pour les répertoires contenant des fichiers spécifiques à la machine (tels que les exécutables et les bibliothèques de sous-programmes), tandis que $(prefix) est utilisé directement pour les autres répertoires.
Exécuter « make install » avec une valeur de exec_prefix différente de celle utilisée pour construire le programme ne devrait pas recompiler le programme.
Les programmes exécutables sont installés dans l'un des répertoires suivants.
bindirRépertoire où installer les programmes exécutables que les utilisateurs peuvent lancer. Il s'agit normalement de /usr/local/bin, mais écrivez-le $(exec_prefix)/bin. (Si vous utilisez Autoconf, écrivez-le « @bindir@ ».)
sbindirRépertoire où installer les programmes exécutables qui peuvent être lancés depuis le shell, mais ne sont généralement utiles qu'aux administrateurs système. Il s'agit normalement de /usr/local/sbin, mais écrivez-le $(exec_prefix)/sbin. (Si vous utilisez Autoconf, écrivez-le « @sbindir@ ».)
libexecdirRépertoire où installer les programmes exécutables destinés à être lancés par d'autres programmes plutôt que par les utilisateurs. Il s'agit normalement de /usr/local/libexec, mais écrivez-le $(exec_prefix)/libexec. (Si vous utilisez Autoconf, écrivez-le « @libexecdir@ ».)
La définition de « libexecdir » est la même pour tous les paquets ; vous devriez donc installer les données de votre paquet dans un sous-répertoire de celui-ci. La plupart des paquets installent leurs données sous $(libexecdir)/package-name/, parfois dans des sous-répertoires supplémentaires de celui-ci (par exemple $(libexecdir)/package-name/machine/version).
Les fichiers de données utilisés par le programme pendant son exécution se répartissent en catégories selon deux axes.
Cela fait six possibilités. Toutefois, nous voulons décourager l'usage de fichiers dépendant de l'architecture, hormis les fichiers objets et les bibliothèques. Il est bien plus propre de rendre les autres fichiers de données indépendants de l'architecture, et ce n'est généralement pas si difficile.
Voici les variables que les Makefiles devraient utiliser pour spécifier où placer ces différents types de fichiers :
Racine de l'arborescence de répertoires pour les fichiers de données en lecture seule et indépendants de l'architecture. Il s'agit normalement de /usr/local/share, mais écrivez-le $(prefix)/share. (Si vous utilisez Autoconf, écrivez-le « @datarootdir@ ».) La valeur par défaut de « datadir » est fondée sur cette variable ; il en va de même pour « infodir », « mandir » et d'autres.
Répertoire où installer les fichiers de données propres à ce programme, en lecture seule et indépendants de l'architecture. Il s'agit habituellement du même emplacement que « datarootdir », mais nous utilisons deux variables distinctes afin que vous puissiez déplacer ces fichiers propres au programme sans modifier l'emplacement des fichiers Info, des pages de manuel, etc.
Il s'agit normalement de /usr/local/share, mais écrivez-le $(datarootdir). (Si vous utilisez Autoconf, écrivez-le « @datadir@ ».)
La définition de « datadir » est la même pour tous les paquets ; vous devriez donc installer vos données dans un sous-répertoire de celui-ci. La plupart des paquets installent leurs données sous $(datadir)/package-name/.
Répertoire où installer les fichiers de données en lecture seule qui concernent une seule machine, c'est-à-dire les fichiers de configuration d'un hôte. Les fichiers de configuration des messageries et du réseau, /etc/passwd, etc., relèvent de cette catégorie. Tous les fichiers de ce répertoire devraient être des fichiers texte ASCII ordinaires. Il s'agit normalement de /usr/local/etc, mais écrivez-le $(prefix)/etc. (Si vous utilisez Autoconf, écrivez-le « @sysconfdir@ ».)
N'installez pas d'exécutables dans ce répertoire (ils relèvent probablement de $(libexecdir) ou $(sbindir)). N'y installez pas non plus de fichiers modifiés au cours normal de leur utilisation (à l'exception des programmes dont le but est de changer la configuration du système). Ceux-là relèvent probablement de $(localstatedir).
Répertoire où installer les fichiers de données indépendants de l'architecture que les programmes modifient pendant leur exécution. Il s'agit normalement de /usr/local/com, mais écrivez-le $(prefix)/com. (Si vous utilisez Autoconf, écrivez-le « @sharedstatedir@ ».)
Répertoire où installer les fichiers de données que les programmes modifient pendant leur exécution et qui concernent une machine particulière. Les utilisateurs ne devraient jamais avoir besoin de modifier les fichiers de ce répertoire pour configurer le fonctionnement du paquet ; placez ce type d'informations de configuration dans des fichiers distincts, situés dans $(datadir) ou $(sysconfdir). $(localstatedir) est normalement /usr/local/var, mais écrivez-le $(prefix)/var. (Si vous utilisez Autoconf, écrivez-le « @localstatedir@ ».)
Répertoire où installer les fichiers de données que les programmes modifient pendant leur exécution, qui concernent une machine particulière et qui n'ont pas besoin de subsister plus longtemps que l'exécution du programme ; les fichiers placés ici sont généralement de longue durée, par exemple jusqu'au prochain redémarrage. Les fichiers PID des démons système en sont un usage typique. De plus, ce répertoire ne devrait pas être nettoyé, sauf peut-être au redémarrage, alors que le /tmp général (TMPDIR) peut l'être à tout moment. Il s'agit normalement de /var/run, mais écrivez-le $(localstatedir)/run. En faire une variable distincte permet par exemple d'utiliser /run si on le souhaite. (Si vous utilisez Autoconf 2.70 ou ultérieur, écrivez-le « @runstatedir@ ».)
Les variables suivantes spécifient le répertoire où installer certains types de fichiers particuliers, si votre programme en possède. Tout paquet GNU devrait posséder des fichiers Info, donc tout programme a besoin de « infodir », mais ils n'ont pas tous besoin de « libdir » ou de « lispdir ».
Répertoire où installer les fichiers d'en-tête que les programmes utilisateurs incluent avec la directive de préprocesseur C « #include ». Il s'agit normalement de /usr/local/include, mais écrivez-le $(prefix)/include. (Si vous utilisez Autoconf, écrivez-le « @includedir@ ».)
La plupart des compilateurs autres que GCC ne cherchent pas les fichiers d'en-tête dans le répertoire /usr/local/include. Installer les fichiers d'en-tête de cette façon n'est donc utile qu'avec GCC. Parfois ce n'est pas un problème, car certaines bibliothèques ne sont véritablement destinées à fonctionner qu'avec GCC. Mais certaines bibliothèques sont destinées à fonctionner avec d'autres compilateurs. Celles-ci devraient installer leurs fichiers d'en-tête à deux emplacements, l'un spécifié par includedir et l'autre par oldincludedir.
Répertoire où installer les fichiers d'en-tête « #include » destinés à des compilateurs autres que GCC. Il s'agit normalement de /usr/include. (Si vous utilisez Autoconf, vous pouvez l'écrire « @oldincludedir@ ».)
Les commandes du Makefile devraient vérifier si la valeur de oldincludedir est vide. Si elle l'est, elles ne devraient pas essayer de l'utiliser ; elles devraient renoncer à la seconde installation des fichiers d'en-tête.
Un paquet ne devrait pas remplacer un en-tête existant dans ce répertoire à moins que cet en-tête provienne du même paquet. Ainsi, si votre paquet Foo fournit un fichier d'en-tête foo.h, alors il devrait installer ce fichier d'en-tête dans le répertoire oldincludedir si : (1) il n'y a pas de foo.h à cet endroit, ou (2) le foo.h qui s'y trouve provient du paquet Foo.
Pour déterminer si foo.h provient du paquet Foo, placez dans le fichier une chaîne magique distinctive (au sein d'un commentaire) et recherchez cette chaîne avec grep.
Répertoire où installer les fichiers de documentation (autres qu'Info) de ce paquet. Par défaut, ce devrait être /usr/local/share/doc/yourpkg, mais écrivez-le $(datarootdir)/doc/yourpkg. (Si vous utilisez Autoconf, écrivez-le « @docdir@ ».) Le sous-répertoire yourpkg (qui peut inclure un numéro de version) évite les collisions entre fichiers portant des noms courants comme README.
Répertoire où installer les fichiers Info de ce paquet. Par défaut, ce devrait être /usr/local/share/info, mais écrivez-le $(datarootdir)/info. (Si vous utilisez Autoconf, écrivez-le « @infodir@ ».) infodir est distinct de docdir pour des raisons de compatibilité avec les pratiques existantes.
Répertoires où installer les fichiers de documentation dans le format correspondant. Ils devraient tous être réglés sur $(docdir) par défaut. (Si vous utilisez Autoconf, écrivez-les « @htmldir@ », « @dvidir@ », etc.) Les paquets qui fournissent plusieurs traductions de leur documentation devraient les installer dans « $(htmldir)/ »ll, « $(pdfdir)/ »ll, etc., où ll est une abréviation de locale telle que « en » ou « pt_BR ».
Répertoire pour les fichiers objets et les bibliothèques de code objet. N'y installez pas d'exécutables ; ils devraient probablement aller plutôt dans $(libexecdir). La valeur de libdir est normalement /usr/local/lib, mais écrivez-le $(exec_prefix)/lib. (Si vous utilisez Autoconf, écrivez-le « @libdir@ ».)
Répertoire où installer les éventuels fichiers Emacs Lisp de ce paquet. Par défaut, ce devrait être /usr/local/share/emacs/site-lisp, mais écrivez-le $(datarootdir)/emacs/site-lisp.
Si vous utilisez Autoconf, écrivez la valeur par défaut « @lispdir@ ». Pour que « @lispdir@ » fonctionne, vous avez besoin des lignes suivantes dans votre fichier configure.ac :
lispdir='${datarootdir}/emacs/site-lisp'
AC_SUBST(lispdir)
Répertoire où installer les catalogues de messages propres à chaque locale pour ce paquet. Par défaut, ce devrait être /usr/local/share/locale, mais écrivez-le $(datarootdir)/locale. (Si vous utilisez Autoconf, écrivez-le « @localedir@ ».) Ce répertoire comporte habituellement un sous-répertoire par locale.
Les pages de manuel de style Unix sont installées dans l'un des emplacements suivants :
Répertoire de plus haut niveau où installer les pages de manuel (s'il y en a) de ce paquet. Il s'agit normalement de /usr/local/share/man, mais vous devriez l'écrire $(datarootdir)/man. (Si vous utilisez Autoconf, écrivez-le « @mandir@ ».)
Répertoire où installer les pages de manuel de la section 1. Écrivez-le $(mandir)/man1.
Répertoire où installer les pages de manuel de la section 2. Écrivez-le $(mandir)/man2.
Ne faites pas de la documentation principale d'un logiciel GNU une page de manuel. Écrivez plutôt un manuel en Texinfo. Les pages de manuel ne sont là que pour les personnes qui exécutent des logiciels GNU sous Unix, ce qui n'est qu'un usage secondaire.
Extension du nom de fichier de la page de manuel installée. Elle devrait comporter un point suivi du chiffre approprié ; ce devrait normalement être « .1 ».
Extension du nom de fichier des pages de manuel installées de la section 1.
Extension du nom de fichier des pages de manuel installées de la section 2.
Utilisez ces noms au lieu de « manext » si le paquet doit installer des pages de manuel dans plusieurs sections du manuel.
Et enfin, vous devriez définir la variable suivante :
Répertoire des sources à compiler. La valeur de cette variable est normalement insérée par le script shell configure. (Si vous utilisez Autoconf, utilisez « srcdir = @srcdir@ ».)
Par exemple :
# Common prefix for installation directories. # NOTE: This directory must exist when you start the install. prefix = /usr/local datarootdir = $(prefix)/share datadir = $(datarootdir) exec_prefix = $(prefix) # Where to put the executable for the command 'gcc'. bindir = $(exec_prefix)/bin # Where to put the directories used by the compiler. libexecdir = $(exec_prefix)/libexec # Where to put the Info files. infodir = $(datarootdir)/info
Si votre programme installe un grand nombre de fichiers dans l'un des répertoires standard spécifiés par l'utilisateur, il peut être utile de les regrouper dans un sous-répertoire propre à ce programme. Si vous le faites, vous devriez écrire la règle install de manière à créer ces sous-répertoires.
N'attendez pas de l'utilisateur qu'il inclue le nom du sous-répertoire dans la valeur de l'une des variables énumérées ci-dessus. L'idée d'avoir un ensemble uniforme de noms de variables pour les répertoires d'installation est de permettre à l'utilisateur de spécifier exactement les mêmes valeurs pour plusieurs paquets GNU différents. Pour que cela soit utile, tous les paquets doivent être conçus de manière à se comporter raisonnablement lorsque l'utilisateur procède ainsi.
Il se peut que toutes ces variables ne soient pas implémentées dans la version actuelle d'Autoconf et/ou d'Automake ; mais depuis Autoconf 2.60, nous estimons qu'elles le sont toutes. Lorsque certaines manquent, les descriptions données ici servent de spécifications pour ce qu'Autoconf devra implémenter. En tant que programmeur, vous pouvez soit utiliser une version de développement d'Autoconf, soit éviter d'utiliser ces variables jusqu'à la sortie d'une version stable qui les prend en charge.
Tous les programmes GNU devraient avoir les cibles suivantes dans leur Makefile :
Compile l'intégralité du programme. Ce devrait être la cible par défaut. Cette cible n'a pas besoin de régénérer les fichiers de documentation : les fichiers Info devraient normalement être inclus dans la distribution, et les fichiers DVI (et autres formats de documentation) ne devraient être produits que sur demande explicite.
Par défaut, les règles de Make devraient compiler et faire l'édition de liens avec « -g », afin que les programmes exécutables contiennent des symboles de débogage. Sinon, vous êtes pour ainsi dire démuni face à un plantage, et il est souvent loin d'être facile de le reproduire avec une nouvelle construction.
Compile le programme et copie les exécutables, les bibliothèques, etc., aux emplacements où ils doivent résider pour une utilisation réelle. S'il existe un test simple pour vérifier qu'un programme est correctement installé, cette cible devrait l'exécuter.
Ne dépouillez pas (strip) les exécutables lors de leur installation. Cela facilite le débogage qui pourrait s'avérer nécessaire par la suite ; de plus, l'espace disque est aujourd'hui bon marché et les chargeurs dynamiques font généralement en sorte que les sections de débogage ne soient pas chargées lors de l'exécution normale. Les utilisateurs qui ont besoin de binaires dépouillés peuvent invoquer la cible install-strip pour cela.
Si possible, écrivez la règle de la cible install de manière qu'elle ne modifie rien dans le répertoire où le programme a été construit, à condition que « make all » vienne d'être effectué. C'est pratique pour construire le programme sous un nom d'utilisateur et l'installer sous un autre.
Les commandes devraient créer tous les répertoires où des fichiers doivent être installés, s'ils n'existent pas déjà. Cela comprend les répertoires spécifiés comme valeurs des variables prefix et exec_prefix, ainsi que tous les sous-répertoires nécessaires. Une façon de procéder consiste à utiliser une cible installdirs, décrite ci-dessous.
Faites précéder de « - » toute commande d'installation d'une page de manuel, afin que make ignore les éventuelles erreurs. C'est au cas où il existerait des systèmes sur lesquels le système de documentation des pages de manuel Unix n'est pas installé.
La façon d'installer les fichiers Info est de les copier dans $(infodir) avec $(INSTALL_DATA) (voir Variables pour spécifier les commandes), puis d'exécuter le programme install-info s'il est présent. install-info est un programme qui édite le fichier dir d'Info pour ajouter ou mettre à jour l'entrée de menu du fichier Info donné ; il fait partie du paquet Texinfo.
Voici un exemple de règle pour installer un fichier Info, qui tente aussi de gérer quelques situations supplémentaires, comme l'absence de install-info.
do-install-info: foo.info installdirs
$(NORMAL_INSTALL)
# Prefer an info file in . to one in srcdir.
if test -f foo.info; then d=.; \
else d="$(srcdir)"; fi; \
$(INSTALL_DATA) $$d/foo.info \
"$(DESTDIR)$(infodir)/foo.info"
# Run install-info only if it exists.
# Use 'if' instead of just prepending '-' to the
# line so we notice real errors from install-info.
# Use '$(SHELL) -c' because some shells do not
# fail gracefully when there is an unknown command.
$(POST_INSTALL)
if $(SHELL) -c 'install-info --version' \
>/dev/null 2>&1; then \
install-info --dir-file="$(DESTDIR)$(infodir)/dir" \
"$(DESTDIR)$(infodir)/foo.info"; \
else true; fi
Lorsque vous écrivez la cible install, vous devez classer toutes les commandes en trois catégories : les commandes normales, les commandes de pré-installation (pre-installation) et les commandes de post-installation (post-installation). Voir Catégories de commandes d'installation.
Ces cibles installent la documentation dans des formats autres qu'Info ; elles sont destinées à être appelées explicitement par la personne qui installe le paquet, si ce format est souhaité. GNU préfère les fichiers Info, c'est pourquoi Info doit être installé par la cible install.
Lorsque vous avez de nombreux fichiers de documentation à installer, nous vous recommandons d'éviter les collisions et le désordre en faisant en sorte que ces cibles installent dans des sous-répertoires du répertoire d'installation approprié, tel que htmldir. À titre d'exemple, si votre paquet comporte plusieurs manuels et que vous souhaitez installer une documentation HTML composée de nombreux fichiers (telle que la sortie en mode « split » de makeinfo --html), vous voudrez certainement utiliser des sous-répertoires ; sinon, deux nœuds de même nom appartenant à des manuels différents s'écraseraient l'un l'autre.
Faites en sorte que ces cibles install-format invoquent les commandes de la cible format, par exemple en faisant de format un prérequis.
Supprime tous les fichiers installés, c'est-à-dire les copies créées par les cibles « install » et « install-* ».
Cette règle ne devrait pas modifier les répertoires où la compilation est effectuée, mais seulement ceux où les fichiers sont installés.
Les commandes de désinstallation se répartissent en trois catégories, tout comme les commandes d'installation. Voir Catégories de commandes d'installation.
Comme install, mais dépouille (strip) les fichiers exécutables lors de leur installation. Dans les cas simples, cette cible peut utiliser la cible install de façon simple :
install-strip:
$(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \
install
Mais si le paquet installe des scripts en plus de véritables exécutables, la cible install-strip ne peut pas se contenter de renvoyer à la cible install : elle doit dépouiller les exécutables sans dépouiller les scripts.
install-strip ne devrait pas dépouiller les exécutables du répertoire de construction qui sont copiés en vue de l'installation. Elle ne devrait dépouiller que les copies installées.
Normalement, nous ne recommandons pas de dépouiller un exécutable à moins d'être sûr que le programme est exempt de bogues. Il peut toutefois être raisonnable d'installer un exécutable dépouillé pour l'exécution réelle, tout en conservant ailleurs l'exécutable non dépouillé au cas où il y aurait un bogue.
Supprime tous les fichiers du répertoire courant qui sont normalement créés lors de la construction du programme. Supprime aussi les fichiers situés dans d'autres répertoires s'ils sont créés par ce makefile. Cependant, ne supprimez pas les fichiers qui enregistrent la configuration. Préservez également les fichiers qui pourraient être produits par la construction, mais qui ne le sont normalement pas parce que la distribution les fournit. Il n'est pas nécessaire de supprimer les répertoires parents créés avec « mkdir -p », puisqu'ils auraient pu exister de toute façon.
Supprimez ici les fichiers .dvi s'ils ne font pas partie de la distribution.
Supprime tous les fichiers du répertoire courant (ou créés par ce makefile) qui sont produits par la configuration ou la construction du programme. Si vous avez décompressé les sources et construit le programme sans créer aucun autre fichier, « make distclean » ne devrait laisser que les fichiers qui figuraient dans la distribution. Cependant, il n'est pas nécessaire de supprimer les répertoires parents créés avec « mkdir -p », puisqu'ils auraient pu exister de toute façon.
Comme « clean », mais peut s'abstenir de supprimer quelques fichiers que l'on ne souhaite normalement pas recompiler. Par exemple, la cible « mostlyclean » de GCC ne supprime pas libgcc.a, car il est rarement nécessaire de le recompiler et cela prend beaucoup de temps.
Supprime presque tout ce qui peut être reconstruit avec ce Makefile. Cela inclut généralement tout ce que supprime distclean, et davantage : les fichiers source C produits par Bison, les tables de tags, les fichiers Info, etc.
Nous disons « presque tout » parce qu'exécuter la commande « make maintainer-clean » ne devrait pas supprimer configure, même si configure peut être refait à l'aide d'une règle du Makefile. Plus généralement, « make maintainer-clean » ne devrait rien supprimer de ce qui doit exister pour exécuter configure puis commencer à construire le programme. Il n'est pas non plus nécessaire de supprimer les répertoires parents créés avec « mkdir -p », puisqu'ils auraient pu exister de toute façon. Ce sont les seules exceptions ; maintainer-clean devrait supprimer tout le reste de ce qui peut être reconstruit.
La cible « maintainer-clean » est destinée à être utilisée par le mainteneur du paquet, et non par les utilisateurs ordinaires. Reconstruire certains des fichiers que « make maintainer-clean » supprime peut nécessiter des outils particuliers. Comme ces fichiers sont normalement inclus dans la distribution, nous ne nous soucions pas de les rendre faciles à reconstruire. S'il vous faut décompresser à nouveau la distribution complète, ne nous en tenez pas rigueur.
Pour que les utilisateurs en aient conscience, les commandes de la cible particulière maintainer-clean devraient commencer par ces deux lignes :
@echo 'This command is intended for maintainers to use; it' @echo 'deletes files that may need special tools to rebuild.'
Met à jour une table de tags pour ce programme.
Génère les fichiers Info nécessaires. La meilleure façon d'écrire les règles est la suivante :
info: foo.info
foo.info: foo.texi chap1.texi chap2.texi
$(MAKEINFO) $(srcdir)/foo.texi
Vous devez définir la variable MAKEINFO dans le Makefile. Elle devrait exécuter le programme makeinfo, qui fait partie de la distribution Texinfo.
Normalement, une distribution GNU est livrée avec des fichiers Info, ce qui signifie que les fichiers Info sont présents dans le répertoire source. Par conséquent, la règle Make d'un fichier Info devrait le mettre à jour dans le répertoire source. Lorsque les utilisateurs construisent le paquet, Make ne met ordinairement pas à jour les fichiers Info, car ceux-ci sont déjà à jour.
Génère les fichiers de documentation dans le format indiqué. Ces cibles devraient toujours exister, mais l'une quelconque (ou toutes) peut être un no-op si le format de sortie correspondant ne peut pas être généré. Ces cibles ne devraient pas être des prérequis de la cible all ; l'utilisateur doit les invoquer manuellement.
Voici un exemple de règle pour générer des fichiers DVI à partir de Texinfo :
dvi: foo.dvi
foo.dvi: foo.texi chap1.texi chap2.texi
$(TEXI2DVI) $(srcdir)/foo.texi
Vous devez définir la variable TEXI2DVI dans le Makefile. Elle devrait exécuter le programme texi2dvi, qui fait partie de la distribution Texinfo. (texi2dvi utilise TeX pour effectuer le véritable travail de composition. TeX n'est pas distribué avec Texinfo.) Vous pouvez aussi écrire uniquement les prérequis et laisser GNU make fournir la commande.
Voici un autre exemple, celui-ci pour générer du HTML à partir de Texinfo :
html: foo.html
foo.html: foo.texi chap1.texi chap2.texi
$(TEXI2HTML) $(srcdir)/foo.texi
Là encore, vous définiriez la variable TEXI2HTML dans le Makefile ; par exemple, elle pourrait exécuter makeinfo --no-split --html (makeinfo fait partie de la distribution Texinfo).
Crée un fichier tar de distribution pour ce programme. Le fichier tar devrait être conçu de manière que les noms de fichiers qu'il contient commencent par le nom d'un sous-répertoire qui est le nom du paquet dont il est la distribution. Ce nom peut inclure le numéro de version.
Par exemple, le fichier tar de distribution de GCC version 1.40 se décompresse dans un sous-répertoire nommé gcc-1.40.
La façon la plus simple de procéder est de créer un sous-répertoire convenablement nommé, d'utiliser ln ou cp pour y installer les fichiers appropriés, puis de regrouper ce sous-répertoire avec tar.
Compressez le fichier tar avec gzip. Par exemple, le fichier de distribution réel de GCC version 1.40 s'appelle gcc-1.40.tar.gz. Il est permis de prendre également en charge d'autres formats de compression libres.
La cible dist devrait dépendre explicitement de tous les fichiers non source qui figurent dans la distribution, afin de s'assurer qu'ils sont à jour dans la distribution. Voir la section Making Releases du document GNU Coding Standards.
Effectue les autotests (s'il y en a). L'utilisateur doit construire le programme avant d'exécuter les tests, mais il n'a pas besoin de l'installer ; vous devriez écrire les autotests de manière qu'ils fonctionnent lorsque le programme est construit mais non installé.
Les cibles suivantes sont proposées comme noms conventionnels, pour les programmes auxquels elles sont utiles.
installcheckEffectue les tests d'installation (s'il y en a). L'utilisateur doit construire et installer le programme avant d'exécuter les tests. Ne supposez pas que $(bindir) figure dans le chemin de recherche.
installdirsIl est utile d'ajouter une cible nommée « installdirs » pour créer les répertoires où les fichiers sont installés, ainsi que leurs répertoires parents. Il existe un script nommé mkinstalldirs qui est pratique pour cela ; vous le trouverez dans le paquet Gnulib. Vous pouvez utiliser une règle comme celle-ci :
# Make sure all installation directories (e.g. $(bindir))
# actually exist by making them if necessary.
installdirs: mkinstalldirs
$(srcdir)/mkinstalldirs $(bindir) $(datadir) \
$(libdir) $(infodir) \
$(mandir)
ou, si vous souhaitez prendre en charge DESTDIR (fortement encouragé),
# Make sure all installation directories (e.g. $(bindir))
# actually exist by making them if necessary.
installdirs: mkinstalldirs
$(srcdir)/mkinstalldirs \
$(DESTDIR)$(bindir) $(DESTDIR)$(datadir) \
$(DESTDIR)$(libdir) $(DESTDIR)$(infodir) \
$(DESTDIR)$(mandir)
Cette règle ne devrait pas modifier les répertoires où la compilation est effectuée. Elle ne devrait rien faire d'autre que créer les répertoires d'installation.
Lorsque vous écrivez la cible install, vous devez classer toutes les commandes en trois catégories : les commandes normales, les commandes de pré-installation (pre-installation) et les commandes de post-installation (post-installation).
Les commandes normales déplacent les fichiers à leur emplacement adéquat et fixent leur mode (permissions). Elles ne doivent modifier aucun fichier autre que ceux qui proviennent entièrement du paquet auquel ils appartiennent.
Les commandes de pré-installation et de post-installation peuvent modifier d'autres fichiers ; en particulier, elles peuvent éditer des fichiers de configuration globaux ou des bases de données.
Les commandes de pré-installation sont généralement exécutées avant les commandes normales, et les commandes de post-installation après les commandes normales.
L'usage le plus courant d'une commande de post-installation est l'exécution de install-info. Cela ne peut pas se faire au moyen d'une commande normale, car cette opération modifie un fichier (le répertoire Info) qui ne provient pas entièrement et exclusivement du paquet en cours d'installation. C'est une commande de post-installation parce qu'elle doit être exécutée après la commande normale qui installe les fichiers Info du paquet.
La plupart des programmes n'ont besoin d'aucune commande de pré-installation, mais nous prévoyons cette fonctionnalité au cas où elle serait nécessaire.
Pour classer les commandes de la règle install dans ces trois catégories, insérez parmi elles des lignes de catégorie (category lines). Une ligne de catégorie spécifie la catégorie des commandes qui la suivent.
Une ligne de catégorie est constituée d'une tabulation, d'une référence à une variable Make particulière, et d'un commentaire facultatif en fin de ligne. Il existe trois variables que vous pouvez utiliser, une par catégorie ; le nom de la variable spécifie la catégorie. Les lignes de catégorie sont des no-ops lors de l'exécution ordinaire, car ces trois variables Make sont normalement indéfinies (et vous ne devriez pas les définir dans le makefile).
Voici les trois lignes de catégorie possibles, chacune avec un commentaire qui en explique le sens :
$(PRE_INSTALL) # Commandes de pré-installation à suivre.
$(POST_INSTALL) # Commandes de post-installation à suivre.
$(NORMAL_INSTALL) # Commandes normales à suivre.
Si vous n'utilisez pas de ligne de catégorie au début de la règle install, toutes les commandes sont classées comme normales jusqu'à la première ligne de catégorie. Si vous n'utilisez aucune ligne de catégorie, toutes les commandes sont classées comme normales.
Voici les lignes de catégorie pour uninstall :
$(PRE_UNINSTALL) # Commandes de pré-désinstallation à suivre.
$(POST_UNINSTALL) # Commandes de post-désinstallation à suivre.
$(NORMAL_UNINSTALL) # Commandes normales à suivre.
Typiquement, une commande de pré-désinstallation servirait à supprimer des entrées du répertoire Info.
Si la cible install ou uninstall a des prérequis qui jouent le rôle de sous-programmes d'installation, alors vous devriez commencer les commandes de chaque prérequis par une ligne de catégorie, et commencer aussi les commandes de la cible principale par une ligne de catégorie. Ainsi, vous pouvez garantir que chaque commande est placée dans la bonne catégorie, quel que soit le prérequis effectivement exécuté.
Les commandes de pré-installation et de post-installation ne devraient exécuter aucun programme autre que ceux-ci :
[ basename bash cat chgrp chmod chown cmp cp dd diff echo expand expr false find getopt grep gunzip gzip hostname install install-info kill ldconfig ln ls md5sum mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee test touch true uname xargs yes
La raison pour laquelle on distingue ainsi les commandes est la création de paquets binaires. Typiquement, un paquet binaire contient tous les exécutables et autres fichiers à installer, et dispose de sa propre méthode pour les installer ; il n'a donc pas besoin d'exécuter les commandes d'installation normales. Mais installer le paquet binaire nécessite bel et bien d'exécuter les commandes de pré-installation et de post-installation.
Les programmes qui construisent des paquets binaires fonctionnent en extrayant les commandes de pré-installation et de post-installation. Voici une façon d'extraire les commandes de pré-installation (l'option -s de make est nécessaire pour faire taire les messages signalant l'entrée dans les sous-répertoires) :
make -s -n install -o all \
PRE_INSTALL=pre-install \
POST_INSTALL=post-install \
NORMAL_INSTALL=normal-install \
| gawk -f pre-install.awk
où le fichier pre-install.awk pourrait contenir ceci :
$0 ~ /^(normal-install|post-install)[ \t]*$/ {on = 0}
on {print $0}
$0 ~ /^pre-install[ \t]*$/ {on = 1}