Créer un module

Si vous désirez ne pas modifier directement les templates pour ainsi pouvoir mettre à jour facilement pkgi lors de ses futures versions (ce qui est une très bonne idée!), vous pouvez créer vous même un module (ex: "monmodule") pour votre application.

Voici les détails de comment procéder :

1. Créez un répertoire pkgi.monmodule/ qui contiendra les fichiers de configuration spécifique à votre application.
2. Créez les fichiers de configurations que vous souhaitez surcharger, par exemple :
   • pkgi.monmodule/etc/apache2/conf.d/maconf-apache.conf
   • pkgi.monmodule/etc/mysql/conf.d/maconf-mysql.cnf
3. Fixez éventuellement en dur les paramètres qui ne bougeront pas.
4. Finalement, ajoutez la chaîne monmodule dans la section MODULES du fichier pkgi.env. Placez le nom de votre module (sans le préfixe pkgi.) tout à la fin de la liste. C'est important pour que vos paramètres surchargent ceux des autre modules.
   Dans l'exemple ci-dessus, maconf-apache.conf sera chargé par apache en plus du classique etc/apache2/apache2.conf et maconf-mysql.cnf sera chargé par mysql en plus du classique etc/mysql/my.cnf

Si vous désirez créer un nouveau module générique (ex: genmodule) pour ainsi le partager avec la communauté de pkgi, vous êtes fortement encouragé à le faire.

Le plus simple pour débuter est de regarder comment les autres modules sont écrits. Par exemple regardez comment le module apache a été écrit. La philosophie KISS de pkgi devrait aider à une compréhension rapide sans même avoir à lire la documentation

Voici cependant plusieurs indicateurs des points à ne pas oublier :

1. Il faut tout d'abord créer un répertoire pkgi/genmodule/ qui contiendra les templates des fichiers de configuration et les templates des lanceurs spécifiques à votre module.
2. Créez un fichier pkgi/genmodule/config.ini qui contiendra les éventuelles variables nécessaires à la configuration de votre module (pour la syntaxe, prenez exemple sur pkgi/apache/config.ini) que vous pourrez ensuite récupérer dans les templates de cette manière :

   <?php echo getenv('APPNAME_HOME'); ?>
   <?php echo getenv('APPNAME_USER'); ?>
   <?php echo getenv('APPNAME_GROUP'); ?>
   ...

   (notez que vous avez également accès aux variables des autres modules, dans l'exemple ce sont des variables fournies par le module core)
   Si vous avez plusieurs items à ajouter sous la même option, créez une nouvelle ligne, comme ici, pour les dépendances système :

   mandatory-sys-dependency[]  = "php5-curl"
   mandatory-sys-dependency[]  = "php5-xsl"

3. Créez alors les templates des fichiers de configuration et les templates des lanceurs en respectant au plus près les structures choisies par Debian :
   • pkgi/genmodule/etc/… : ici vous aurez certainement des fichiers de configuration à placer
   • pkgi/genmodule/usr/bin/… : ici vous aurez peut-être des binaires à en-capsuler
   • pkgi/genmodule/etc/init.d/… : ici vous aurez certainement un lanceur à placer si votre module concerne un démon
4. Testez votre module en gardant à l'esprit que votre module sera réutilisé par d'autres !
5. Finalement il vous reste à créez la documentation de votre module sur ce site pour qu'il soit utilisable par d'autres : http://www.pkgi.net/modules/genmodule
6. Ensuite publiez un pull request sur le dépôt github de pkgi pour que je puisse intégrer le module dans le code source officiel.
7. Un grand merci à vous !

Si vous nommez un fichier ou un répertoire avec le suffixe .pkgi-raw alors ce fichier ou ce répertoire ne sera pas considéré comme un template. Son contenu sera recopié récursivement dans le répertoire de destination.

Exemple : dans le module dokuwiki

Si vous nommez un fichier ou un répertoire avec le suffixe .pkgi-ignore alors ce fichier ou ce répertoire ne sera instancié. Dit autrement, il ne sera pas copié dans le répertoire de destination. (possible depuis la 2.28)

Exemple : dans le module php

Parfois il est nécessaire d'écrire des templates qui vont générer des fichiers alternatifs : par exemple une batterie de lien symbolique (c'est le cas pour le module phpmyadmin). Pour que ces fichiers puissent être connus de pkgi et ainsi s'intégrer parfaitement dans procédures de mise à jour, vous devez utiliser la fonction suivante dans vos templates :

pkgi_track_instance($chemin_de_l_instance_du_fichier);

L'appel de cette fonction aura pour effet d'enregistrer l'instance dans "la mémoire de pkgi" (concrètement dans le répertoire .pkgi/lastmd5/…). Cette fonction est disponible depuis la version 2.29.

Exemple : dans le module phpmyadmin

Parfois il est nécessaire d'exécuter des scripts après l'exécution du build de pkgi. Par exemple : vider un répertoire de cache, initialiser sa base de données, récupérer des sources automatiquement et/ou les compiler, compiler des modules pecl et les paramétrer …

On peut le faire facilement en ajoutant un fichier config.ini à la racine de son module pkgi (ex: pkgi/monmodule/config.ini) et en y ajoutant ce paramètre :

# les commandes à lancer après un build
postinst[] = "bin/mon-super-script"
postinst[] = "bin/mon-second-super-script"

Le chemin d'exécution est celui de la racine de votre application : là où sont déployées les instances de pkgi.

Cette fonctionnalité s'appelait post-build entre la version 2.30 et 2.32 mais depuis la version 2.33 elle a été renommé en postinst pour se rapprocher de la philosophie des paquets debian.

Les scripts de preinst sont disponibles depuis la version Version 2.38 le 5 janvier 2011 de pkgi. Ils sont très similaires au fonctionnement des scripts postinst : ils s'exécutent avant le début du build pkgi. Exemple dans le config.ini :

# les commandes à lancer avant un build
preinst[] = "bin/mon-super-script"
preinst[] = "bin/mon-second-super-script"

Le chemin d'exécution est celui de la racine de votre application : là où sont déployées les instances de pkgi.