35.16. Outils de construction d'extension

Si vous comptez distribuer vos propres modules d'extension PostgreSQL™, la mise en œuvre d'un système de construction multiplateforme sera réellement difficile. Cependant, PostgreSQL™ met à disposition des outils pour construire des extensions, appelés PGXS, permettant à de simples extensions d'être construites sur un serveur déjà installé. PGXS est principalement destiné aux extensions qui incluent du code C, bien qu'il puisse être utilisé aussi pour des extensions composées exclusivement de code SQL. PGXS n'a pas toutefois été conçu pour être un framework de construction universel qui pourrait construire tout logiciel s'interfaçant avec PostgreSQL™. Il automatise simplement des règles de construction communes pour des extensions simples. Pour des paquetages plus complexes, vous aurez toujours besoin d'écrire vos propres systèmes de construction.

Pour utiliser le système PGXS pour votre extension, vous devez écrire un simple makefile. Dans ce makefile, vous devez définir plusieurs variables et inclure le makefile de PGXS. Voici un exemple qui construit une extension nommée isbn_issn, qui consiste en une bibliothèque qui contient du code C, un fichier de contrôle d'extension, un script SQL et une documentation texte :

MODULES = isbn_issn
EXTENSION = isbn_issn
DATA = isbn_issn--1.0.sql
DOCS = README.isbn_issn

PG_CONFIG = pg_config
PGXS := $(shell $(PG_CONFIG) --pgxs)
include $(PGXS)
   

Les trois dernières lignes devraient toujours être les mêmes. En début de fichier, vous pouvez assigner des variables ou ajouter des règles make personnalisées.

Définissez une de ces trois variables pour spécifier ce qui est construit :

MODULES

liste des bibliothèques à constuire depuis les fichiers sources communs (ne pas inclure les suffixes de bibliothèques dans la liste)

MODULE_big

Une bibliothèque à construire depuis plusieurs fichiers source (listez les fichiers objets dans la variable OBJS).

PROGRAM

Un programme exécutable à construire (listez les fichiers objet dans la variable OBJS).

Les variables suivantes peuvent aussi être définies :

EXTENSION

Nom(s) de l'extension ; pour chaque nom, vous devez fournir un fichier extension.control, qui sera installé dans le répertoire prefix/share/extension

MODULEDIR

Sous-répertoire de prefix/share dans lequel les fichiers DATA et DOCS seront installés (s'il n'est pas défini, la valeur par défaut est extension si EXTENSION est défini et contrib dans le cas contraire)

DATA

Fichiers divers à installer dans prefix/share/$MODULEDIR

DATA_built

Fichiers divers à installer dans prefix/share/$MODULEDIR, qui nécessitent d'être construit au préalable

DATA_TSEARCH

Fichiers divers à installer dans prefix/share/tsearch_data

DOCS

Fichiers divers à installer dans prefix/doc/$MODULEDIR

SCRIPTS

Fichiers de scripts (non binaires) à installer dans prefix/bin

SCRIPTS_built

Fichiers de script (non binaires) à installer dans prefix/bin, qui nécessitent d'être construit au préalable.

REGRESS

Liste de tests de regression (sans suffixe), voir plus bas

REGRESS_OPTS

Options supplémentaires à passer à pg_regress

EXTRA_CLEAN

Fichiers supplémentaire à supprimer par la commande make clean

PG_CPPFLAGS

Sera ajouté à CPPFLAGS

PG_LIBS

Sera ajouté à la ligne d'édition de lien de PROGRAM

SHLIB_LINK

Sera ajouté à la ligne d'édition de lien de MODULE_big

PG_CONFIG

Chemin vers le programme pg_config de l'installation de PostgreSQL™ pour laquelle construire la bibliothèque ou le binaire (l'utilisation de pg_config seul permet d'utiliser le premier accessible par votre PATH)

Placez ce fichier de construction comme Makefile dans le répertoire qui contient votre extension. Puis vous pouvez exécuter la commande make pour compiler, et ensuite make install pour déployer le module. Par défaut, l'extension est compilée et installée pour l'installation de PostgreSQL™ qui correspond au premier programme pg_config trouvé dans votre PATH. Vous pouvez utiliser une installation différente en définissant PG_CONFIG pour pointer sur le programme pg_config de votre choix, soit dans le fichier makefile, soit à partir de la ligne de commande de la commande make.

Vous pouvez aussi exécuter make dans un répertoire en dehors de l'arborescence des sources de votre extension, notamment si vous voulez séparer le répertoire de construction. Cette procédure est aussi appelée une construction VPATH. Voici comment :

mkdir build_dir
cd build_dir
make -f /path/to/extension/source/tree/Makefile
make -f /path/to/extension/source/tree/Makefile install
   

Autrement, vous pouvez configurer un répertoire pour une construction VPATH d'une façon similaire à ce qui est fait pour le code du moteur. Une façon de le faire revient à utiliser le script config/prep_buildtree. Une fois que cela est fait, vous pouvez lancer la construction en configurant la variable VPATH de make ainsi 

make VPATH=/path/to/extension/source/tree
make VPATH=/path/to/extension/source/tree install
   

Cette procédure peut fonctionner avec une grande variété de disposition de répertoires.

Les scripts listés dans la variable REGRESS sont utilisés pour des tests de regression de votre module, qui peut être invoqué par make installcheck après avoir effectué make install. Pour que cela fonctionne, vous devez lancer le serveur PosgreSQL™ préalablement. Les fichiers de script listés dans la variable REGRESS doivent apparaître dans le sous-répertoire appelé sql/ du répertoire de votre extension. Ces fichiers doivent avoir l'extension .sql, qui ne doit pas être inclus dans la liste REGRESS du makefile. Pour chaque test, il doit aussi y avoir un fichier qui contient les résultats attendus dans un sous-répertoire nommé expected, avec le même nom mais l'extension .out. La commande make installcheck exécute chaque script de test avec psql, et compare la sortie resultante au fichier de résultat correspondant. Toute différence sera écrite dans le fichier regression.diffs au format diff -c. Notez que l'exécution d'un test qui ne dispose pas des fichiers nécessaires sera rapportée comme une erreur dans le test, donc assurez-vous que tous les fichiers nécessaires soient présents.

[Astuce]

Astuce

Le moyen le plus simple de créer les fichiers nécessaires est de créer des fichiers vides, puis d'effectuer un jeu d'essai (qui bien sûr retournera des anomalies). Étudiez les résultats trouvés dans le répertoire results et copiez-les dans le répertoire expected/ s'ils correspondent à ce que vous attendiez du test correspondant.