Documentation PostgreSQL 14.22 » Programmation serveur » Étendre SQL » Outils de construction d'extension

Précédent | Niveau supérieur | Suivant
38.17. Empaqueter des objets dans une extension | Sommaire | Chapitre 39. Déclencheurs (triggers)

## 38.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_INSTALL`

  Ne pas définir de cible `install`, utile pour les modules de test qui n'ont pas besoin que le produit soit installé

`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 33.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.