Atelier empaquetage façon GNU

Author:	Benjamin Cama <benoar@dolka.fr>
Date:	2016-06-14
License:	CC BY-SA 3.0 ou GFDL 1.3+

Plan

Les raisons de l'empaquetage
Les choses à réaliser avant de commencer
La configuration selon le système utilisé (autoconf)
La fabrication et l'installation du programme (automake)
La distribution
Conclusion

Les raisons de l'empaquetage

Distribuer son logiciel libre facilement
Bien identifier sa version et sa licence
S'assurer de la reproductibilité du processus de génération, et de la disponibilité des sources de chaque fichier distribué
Faire qu'il soit portable
Proposer un déploiement aisé

Les raisons de l'empaquetage façon GNU

Les autotools sont reconnus et éprouvés
Nécessitent des prérequis minimaux (un shell)
Les programmes ainsi équipés sont intégrables facilement dans n'importe quelle distribution Linux
Et on peut facilement créer des paquets pour une distribution à partir d'eux

Les désavantages de la façon GNU

Syntaxe étrange car utilisation de langages anciens
Peut-être légèrement plus « lourde » que d'autres

Choses non abordées aujourd'hui

Mettre en place en site web et une liste de diffusion
Mettre à disposition un dépôt de code source, voire une « forge/hub/lab »
Distribuer de manière sûre son programme (signature) ; important pour la confiance
Comment gérer une communauté
Intégrer notre logiciel comme paquet dans une distribution (Debian, Fedora, Arch, …)

Les choses à réaliser avant de commencer

Attribuer une licence à notre projet
Écrire un « README » (la description de notre projet)

Attribuer une licence à notre projet

La licence est le contrat par lequel vous donnerez le droit aux utilisateurs d'utiliser/copier/modifier votre logiciel : c'est très important ;
Doit figurer de manière précise :
- Chaque fichier source doit comporter sa mention
- Le README (c.f. prochain point) doit également le mentionner
- La GPL conseille d'afficher sa mention lors de son exécution interactive (terminal)
La licence complète doit être présente (fichier COPYING)

Licence publique générale GNU

Si vous utilisez la GNU GPL v3+ :

wget -O COPYING \
  http://www.gnu.org/licenses/gpl.txt

La manière de l'utiliser est à la fin du texte.

Écrire un « README »

Tout programme a besoin d'une introduction : le README (« lisez-moi »)
Très utile pour comprendre — même en deux lignes — un programme
Même utile pour soi-même quand ça fait longtemps qu'on l'a écrit…
Doit indiquer que c'est un logiciel libre, et sous quelle licence il est distribué

La configuration selon le système utilisé (autoconf)

Le schéma de génération des autotools
Premier jet avec autoscan
Configuration de base
Génération du configure
Utilisation d'une bibliothèque à travers pkg-config

Le schéma de génération des autotools

Les fichiers générés et dépendants :

http://ymettier.free.fr/articles_lmag/lmag75/images/aaa2.png

Premier jet avec autoscan

Lancez autoscan à la racine de votre projet
Renommez configure.scan en configure.ac (ou copiez sont contenu)
Lisez le résultat : c'est du shell avec des macros M4 (le langage de macro standard d'Unix, à l'origine)

Configuration de base

Ajustez les macros :

AC_INIT([nom_de_votre_projet], [0.42],
      [moi+bug@chezmoi.fr])
AC_CONFIG_FILES([Makefile …])

Éventuellement :

AC_CONFIG_SRCDIR([où_sont_mes_sources])
AC_CONFIG_HEADERS([config.h])
AC_CONFIG_FILES([foo], [chmod +x foo])

La dernière macro générera un fichier depuis foo.in.

Génération du configure

On utilise normalement autoconf
Mais plus facile d'utiliser autoreconf, qui s'occupe de regénérations intermédiaires :
```
autoreconf --install
```
L'option --install ne sera utilisée que la première fois.

Utilisation d'une bibliothèque à travers pkg-config

Outil assez répandu permettant de détecter une bibliothèque sur un système
Différent de la philosophie autotools mais pratique

Deux macros à utiliser :

PKG_PROG_PKG_CONFIG
PKG_CHECK_MODULES([foo], [libfoo >= 1.2.3])

(d'abord pour détecter pkg-config puis pour détecter libfoo avec la version adéquate, sous le préfixe foo)

La fabrication et l'installation du programme (automake)

Les « GNU Coding Standards »
Premier Makefile.am
Préparation d'automake
Le schéma de nommage d'automake
La définition d'un programme
Passer de l'information depuis autoconf
Peaufiner la distribution

Les « GNU Coding Standards »

Des règles pour rendre le système GNU propre, cohérant, et facile à installer
Écrites par Richard Stallman et d'autres volontaires
Définissent le besoin d'un configure, de cibles de Makefile standards (install, uninstall, dist, etc)
Contiennent des bonnes pratiques de codage, des recommandations sur la documentation
Permettent une meilleure interopérabilité

Les « GNU Coding Standards », suite

Ce qui nous intéresse pour automake :

Les variables de répertoires standards (qui respectent le Filesystem Hierarchy Standard)
La publication d'un logiciel s'appelle une distribution ! Attention à ce faux-ami.

Premier Makefile.am

Renommez votre Makefile si vous en avez déjà un, ou crééz le
Un Makefile est utilisé même si on ne compile rien, car automake définit également comment est installé votre programme
N'utilisez pas de joker dans le Makefile.am, il faut la liste exacte des fichers inclus dans la distribution

Préparation d'automake

Pour initier automake, ajoutez au configure.ac

AM_INIT_AUTOMAKE

Pour plus de souplesse, vous pouvez éventuellement utiliser :

AM_INIT_AUTOMAKE([foreign])

Le schéma de nommage d'automake

Variables nommées en deux parties (séparées par un underscore) :

Le répertoire d'installation (selon les standard GNU) de(s) l'objet(s) de la variable : bin, doc, sysconf, etc.
Le « primary » (primaire) qui désigne la nature de(s) l'objet(s) : PROGRAMS, LIBRARIES, DATA, etc.

C.f. http://www.gnu.org/software/automake/manual/html_node/Uniform.html#Uniform

La définition d'un programme

La première partie d'une variable peut également être le nom d'un programme objet d'un autre primaire PROGRAMS, pour lequel on utilisera alors un primaire SOURCES ou LDADD par exemple :

bin_PROGRAMS = bar
bar_SOURCES = fichier_a.c fichier_b.c
bar_LDADD = -lpthread

Le schéma de nommage d'automake, suite

Traitement récursif des répertoires avec SUBDIRS (seule)
Éventuellement un préfixe supplémentaire :
- noinst_ pour ne pas installer le fichier
- nodist_ pour ne pas l'inclure dans la distribution
Les fichiers qui ne rentrent dans aucune catégorie mais doivent être distribués vont dans EXTRA_DIST

Passer de l'information depuis autoconf

Définir des variables dans configure.ac pour utiliser dans un Makefile.am ; dans configure.ac
```
AM_CONDITIONAL([HAVE_BAZ],
    [test x$baz_outcome = xyes])
```
Et dans le Makefile.am
```
if HAVE_BAZ
    […]
endif
```

Peaufiner la distribution

Si vous souhaitez modifier la distribution avant qu'elle soit empaquetée, vous pouvez utiliser dans le Makefile.am

dist-hook:
      touch […]

La distribution

Normalement, à ce point, vous avez tout ce qu'il faut pour faire un :

make distcheck

Si ce test passe, c'est que vous avez une distribution correcte ! Vous obtiendrez une archive (tar compressée) que vous pouvez distribuer à vos utilisateurs.

Conseils sur la distribution

Une distribution est normalement unique pour une version donnée : il faut la conserver ; sa somme de contrôle sera utilisée pour vérifier son intégrité
Pour construire une distribution sans vérifier sa conformité, on peut utiliser la cible dist, même si ça n'est pas recommandé

Conclusion

Vous pouver maintenant normalement effectuer dans une distribution de votre programme le fameux :

./configure
make
make install

Félicitations ! Vous facilitez ainsi la vie de ceux qui veulent l'utiliser. Vous permettez également de bien identifier votre logiciel, et vous assurez la disponibilité des sources de tout ce que vous distribuez.

Ressources

Autoconf : http://www.gnu.org/software/autoconf/
Automake : http://www.gnu.org/software/automake/
Gnulib : http://www.gnu.org/software/gnulib/
GNU coding standards : http://www.gnu.org/prep/standards/
Un tutoriel d'Alexandre Duret-Lutz (ÉPITA) : https://www.lrde.epita.fr/~adl/autotools.html
Un tutoriel de Yves Mettier (paru dans GLMF) : http://ymettier.free.fr/articles_lmag/lmag75/lmag75.html

Annexe : Utiliser la GPL (dans les sources)

Au début de chaque fichier source :

Copyright 2013 John Doe

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License […]

Si le copyright n'est pas personnel, on peut ajouter à la fin de l'entête :

Author(s):
    Anne O'Nymous <anne.onymous@example.com>

Annexe : Utiliser la GPL (dans le README)

Dans le README, mettre :

Foobar is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License; see COPYING for
more informations.

Et bien mettre un fichier COPYING avec la licence en entier.

Annexe : Fichier bootstrap minimal

#!/bin/sh
test -n "$srcdir" || srcdir=`dirname "$0"`
test -n "$srcdir" || srcdir=.

cd "$srcdir"
autoreconf --install --verbose

Ce fichier tient compte des constructions hors des sources (avec VPATH).

Annexe : Substituer des variables dans un Makefile

edit = sed -e 's|@datadir[@]|$(datadir)|g' \
        -e 's|@bindir[@]|$(bindir)|g' \
        -e 's|@VERSION[@]|$(VERSION)|g' \
        …

subst_in = rm -f $(1).tmp \
        srcdir='.'; \
        test -f ./$(1).in || srcdir=$(srcdir); \
        $(edit) $${srcdir}/$(1).in > $(1).tmp && \
        mv -f $(1).tmp $(1)

# example use
baz: $(srcdir)/baz.in Makefile
          $(call subst_in,$@)
          chmod +x $@
          chmod a-w $@

À propos de ce document

Ce document pourra se retrouver à l'adresse : http://dolka.fr/bazar/atelier_empaquetage_facon_GNU

Il est distribué selon les termes de la CC BY-SA 3.0 ou la GFDL 1.3+.

Les sources sont rédigées en reStructuredText et le HTML généré par rst2s5.