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
,
qui sera installé dans le répertoire
extension
.controlprefix
/share/extension
MODULEDIR
#
Sous-répertoire de
dans lequel les fichiers DATA et DOCS seront installés
(s'il n'est pas défini, la valeur par défaut est prefix
/shareextension
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
,
qui nécessitent d'être construit au préalable
prefix
/share/$MODULEDIR
DATA_TSEARCH
#
Fichiers divers à installer dans
prefix
/share/tsearch_data
DOCS
#
Fichiers divers à installer dans
prefix
/doc/$MODULEDIR
HEADERS
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_$MODULE
HEADERS_built_$MODULE
#
fichiers à installer (après la construction si indiqué) sous
,
où prefix
/include/server/$MODULEDIR/$MODULE$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
,
qui nécessitent d'être construit au préalable.
prefix
/bin
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.
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.