PostgreSQLLa base de données la plus sophistiquée au monde.
Documentation PostgreSQL 13.14 » Programmation serveur » Étendre SQL » Outils de construction d'extension

37.18. 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, un fichier d'en-tête (seulement nécessaire si les autres modules pourraient avoir besoin d'accéder aux fonctions de l'extension sans passer par le SQL) et une documentation texte :

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

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 à construire 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

HEADERS_built

Fichiers pour (en option construire et) installer sous prefix/include/server/$MODULEDIR/$MODULE_big.

Contrairement à DATA_built, les fichiers dans HEADERS_built ne sont pas supprimés par la cible clean ; si vous voulez les supprimer, ajoutez les aussi à EXTRA_CLEAN ou ajoutez vos propres règles pour le faire.

HEADERS_built_$MODULE

fichiers à installer (après la construction si indiqué) sous prefix/include/server/$MODULEDIR/$MODULE, où $MODULE doit être un nom de module utilisé dans MODULES ou MODULE_big.

Contrairement à DATA_built, les fichiers dans HEADERS_built_$MODULE ne sont pas supprimées par la cible clean ; si vous voulez les supprimer, ajoutez les aussi à EXTRA_CLEAN ou ajoutez vos propres règles pour le faire.

Il est autorisé d'utiliser les deux variables pour le même module ou toute combinaison, sauf si vous avez deux noms de module dans la liste MODULES qui diffèrent seulement par la présence d'un préfixe built_, qui causerait une ambiguité. Dans ce cas (peu) probable, vous devez utiliser seulement les variables HEADERS_built_$MODULE.

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

ISOLATION

Liste de cas de tests d'isolation, voir ci-dessous pour plus de détails

ISOLATION_OPTS

Options supplémentaires pour réussir pg_isolation_regress

TAP_TESTS

Option définissant si les tests TAP doivent être exécutées, voir ci-dessous.

NO_INSTALLCHECK

Ne pas définir de cible installcheck, utile par exemple si les tests nécessitent une configuration spéciale, ou n'utilisent pas pg_regress

EXTRA_CLEAN

Fichiers supplémentaire à supprimer par la commande make clean

PG_CPPFLAGS

Sera ajouté au début de CPPFLAGS

PG_CFLAGS

Sera ajouté à CFLAGS

PG_CXXFLAGS

Sera ajouté à CXXFLAGS

PG_LDFLAGS

Sera ajouté au début de LDFLAGS

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 PostgreSQL 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 résultante 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.

Les scripts listés dans la variable ISOLATION sont utilisés pour des tests sur le comportement en cas de stress dû à des sessions concurrentes avec votre module, tests qui peuvent être invoqués par make installcheck après avoir exécuté make install. Pour que ceci fonctionne, vous devez avoir un serveur PostgreSQL fonctionnel. Les fichiers scripts listés dans ISOLATION doivent apparaître dans un sous-répertoire nommé specs/ du répertoire de votre extension. Ces fichiers doivent avoir une extension .spec, qui ne doit pas être incluse dans la liste ISOLATION du makefile. Pour chaque test, il doit aussi y avoir un fichier contenant la sortie attendue dans un sous-répertoire nommé expected/, avec le même nom et une extension .out. make installcheck exécute chaque script de test et compare la sortie résultante au fichier correspondant attendu. Toute différence sera écrite dans le fichier output_iso/regression.diffs au format diff -c. Notez qu'essayer d'exécuter un test dont le fichier attendu manque sera rapporté comme un problème, donc assurez-vous que vous avez tous les fichiers attendus.

TAP_TESTS active l'utilisation des tests TAP. Les données de chaque exécution sont présentes dans un sous-répertoire nommé tmp_check/. Voir aussi Section 32.4 pour plus de détails.

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 (for tests in REGRESS), or output_iso/results/ directory (for tests in ISOLATION), et copiez-les dans le répertoire expected/ s'ils correspondent à ce que vous attendiez du test correspondant.