apxs − outil d’extension d’Apache (APache eXtenSion)

apxs -g [ -S variable=valeur ] -n nom

apxs -q [ -S variable=valeur ] requête...

apxs -c [ -S variable=valeur ] [ -o fichier_dso ] [ -I répertoire_à _inclure ] [ -D variable [ =valeur ] ] [ -L répertoire_de_bibliothèque ] [ -l nom_de_bibliothèque ] [ -Wc,drapeaux-du-compilateur ] [ -Wl,drapeaux-du-lieur ] fichiers...

apxs -i [ -S variable=valeur ] [ -n nom ] [ -a ] [ -A ] fichier_dso...

apxs -e [ -S variable=valeur ] [ -n nom ] [ -a ] [ -A ] fichier_dso...

apxs est un outil pour construire et installer des modules d’extension pour le serveur de protocole de transfert Hypertexte (HTTP) Apache. Ceci est accompli en construisant un objet dynamique partagé (« Dynamic share object » : DSO) à partir d’un ou plusieurs fichiers sources ou objets. Les DSO peuvent ensuite être chargés par le serveur Apache en fonctionnement par la directive « LoadModule » de mod_so.

Ainsi, pour utiliser ce mécanisme d’extension, votre plate-forme doit supporter la spécificité DSO et votre binaire httpd d’Apache doit être construit avec le module mod_so. L’outil apxs se plaint automatiquement si ce n’est pas le cas. Vous pouvez vérifier par vous-même que ces conditions sont réalisées en lançant manuellement la commande :

  $ httpd -l

Le module mod_so devrait faire partie de la liste affichée. Si ces conditions sont réalisées, vous pouvez facilement étendre les fonctionnalités de votre serveur Apache en installant vos propre modules avec le mécanisme DSO grâce à l’aide de l’outil apxs :

  $ apxs -a -c mod_foo.c
  gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo.c
  ld -Bshareable -o mod_foo.so mod_foo.o
  cp mod_foo.so /path/to/apache/libexec/mod_foo.so
  chmod 755 /path/to/apache/libexec/mod_foo.so
  [activating module ‘foo’ in /path/to/apache/etc/httpd.conf]
  $ apachectl restart
  /path/to/apache/sbin/apachectl restart: httpd not running, trying to start
  [Tue Mar 31 11:27:55 1998] [debug] mod_so.c(303): loaded module foo_module
  /path/to/apache/sbin/apachectl restart: httpd started
  $

Les fichiers passés en argument peuvent être de différents types : fichier source en C (.c), fichier objet (.o) ou même archive de bibliothèque (.a). L’outil apxs reconnaît automatiquement les extensions et utilise automatiquement les fichiers sources en C pour la compilation tandis qu’il utilise les fichiers objets et archives pour la phase de liaison. Mais en utilisant de tels objets précompilés, soyez sûr qu’ils sont compilés en code de position indépendante (PIC) pour être capable de les utiliser comme un DSO. Par exemple avec GCC vous avez juste à utiliser -fpic. Pour d’autres compilateurs C, veuillez consulter sa page de manuel ou chercher le drapeau qu’apxs utilise pour compiler les fichiers objets.

Pour plus de détails à propos du support DSO dans Apache, d’abord lisez l’information sur DSO dans htdocs/manual/dso.html, ensuite lisez la documentation de mod_so.

Options courantes :

-n nom

Ceci positionne explicitement le nom du module pour les options -i (installe) et -g (génération de modèles). Utilisez ceci pour spécifier explicitement le nom du module. Pour l’option -g ceci est imposé, pour l’option -i l’outil apxs essaye de déterminer le nom à partir de la source ou (comme un remplacement) au moins en le devinant à partir du nom du fichier.

Options de requête :

-q

Effectuer une requête pour les connaissances d’apxs au sujet de certaines configurations. Les paramètres de requêtes peuvent être un ou plusieurs des noms de variables suivants :

CC

TARGET

CFLAGS

SBINDIR

CFLAGS_SHLIB

INCLUDEDIR

LD_SHLIB

LIBEXECDIR

LDFLAGS_SHLIB

SYSCONFDIR

LIBS_SHLIB

PREFIX Utilisez cette option pour déterminer manuellement les configurations. Par exemple, utilisez :

INC=-I‘apxs -q INCLUDEDIR‘

à l’intérieur de vos « makefiles » si vous avez besoin d’un accès manuel aux fichiers d’en-tête C d’Apache.

Options de configuration :

-S variable=valeur

Cette option change les configurations d’apxs décrites précédemment.

Options de génération de modèles :

-g

Cette option crée un sous-répertoire (voir l’option -n) et à l’intérieur de celui-ci deux fichiers : un exemple de fichier source de module, nommé mod_name.c qui peut être utilisé comme un modèle pour créer vos propre modules ou comme départ rapide pour jouer avec le mécanisme d’apxs, et un « makefile » correspondant, pour une construction et installation encore plus facile de ce module.

Options de compilation DSO :

-c

Indiquer l’opération de compilation. à partir des fichiers passés en argument, il y a d’abord compilation des fichiers sources C (.c) en fichiers objets (.o) correspondants, et ensuite construction d’un DSO dans fichier_dso en liant ces fichiers objets plus les fichiers objets restants (.o et .a). S’il n’y a pas d’option -o spécifiée, le fichier de sortie est deviné à partir du premier nom de fichier parmi les fichiers en argument et devient habituellement par défaut mod_nom.so.

-o fichier_dso

Spécifier explicitement le nom du fichier DSO créé. S’il n’est pas spécifié, et que le nom ne peut pas être deviné à partir de la liste de fichiers, le nom mod_unknown.so est utilisé.

-D variable[=valeur]

Cette option est passée directement à la/aux commande(s) de compilation. Utilisez cette option pour ajouter vos définitions au processus de construction.

-I répertoire_à _inclure

Cette option est passée directement à la/aux commande(s) de compilation. Utilisez cette option pour ajouter vos répertoires à chercher au processus de construction.

-L libdir

Cette option est passée directement à la commande du lieur. Utilisez cette option pour ajouter vos répertoires de bibliothèques à chercher au processus de construction.

-l libname

Cette option est passée directement à la commande du lieur. Utilisez cette option pour ajouter vos bibliothèques à chercher au processus de construction.

-Wc,drapeaux-du-compilateur

Cette option passe des drapeaux de compilateur comme drapeaux additionnels à la commande du compilateur. Utilisez cette option pour ajouter des options spécifiques du compilateur local.

-Wl,drapeaux-du-lieur

Cette option passe des drapeaux de lieur comme drapeaux additionnels à la commande du lieur. Utilisez cette option pour ajouter des options spécifiques au lieur local.

Options d’installation et de configuration DSO :

-i

Cette option indique l’opération d’installation et installe un ou plusieurs DSOs dans le répertoire libexec du server.

-a

Cette option active le module en ajoutant automatiquement au fichier de configuration d’Apache httpd.conf une ligne « LoadModule » correspondante, ou en l’activant si elle existe déjà .

-A

Identique à l’option -a mais la directive « LoadModule » créée est pré-fixée avec le signe dièse (#), le module est préparé pour une activation ultérieure mais initialement désactivé.

-e

Cette option indique l’opération d’édition, qui peut être utilisée avec les options -a et -A pareillement à l’opération -i pour éditer le fichier de configuration httpd.conf d’Apache sans tenter d’installer le module.

Supposons que vous avez un module Apache nommé mod_foo.c disponible qui pourrait étendre la fonctionnalité du serveur Apache. Pour réaliser ceci, vous devez d’abord compiler la source C en DSO, qui convient au chargement dans le serveur Apache en fonctionnement, via la commande suivante :

  $ apxs -c mod_foo.c
  gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo.c
  ld -Bshareable -o mod_foo.so mod_foo.o
  $

Ensuite, vous devez mettre à jour la configuration d’Apache en étant sûr qu’une directive « LoadModule » est présente pour charger le DSO. Pour simplifier cette étape, apxs fournie une façon automatique pour installer le DSO dans le répertoire libexec et mettre à jour le fichier httpd.conf en conséquence. Ceci peut être accompli en lançant :

  $ apxs -i -a mod_foo.c
  cp mod_foo.so /path/to/apache/libexec/mod_foo.so
  chmod 755 /path/to/apache/libexec/mod_foo.so
  [activating module ‘foo’ in /path/to/apache/etc/httpd.conf]
  $

Ainsi une ligne nommée

  LoadModule foo_module libexec/mod_foo.so

est ajoutée au fichier de configuration si elle n’est pas encore présente. Si vous voulez avoir cette opération désactivée, utilisez l’option -A, exemple :

$ apxs -i -A mod_foo.c

Pour un test rapide du mécanisme d’apxs vous pouvez créer un exemple de modèle de module Apache et un « makefile » correspondant via :

$ apxs -g -n foo
  Creating [DIR]  foo
  Creating [FILE] foo/Makefile
  Creating [FILE] foo/mod_foo.c
  $

Ensuite, vous pouvez immédiatement compiler ce module exemple en DSO et le charger dans le serveur Apache :

  $ cd foo
  $ make all reload
  apxs -c mod_foo.c
  gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo.c
  ld -Bshareable -o mod_foo.so mod_foo.o
  apxs -i -a -n "foo" mod_foo.so
  cp mod_foo.so /path/to/apache/libexec/mod_foo.so
  chmod 755 /path/to/apache/libexec/mod_foo.so
  [activating module ‘foo’ in /path/to/apache/etc/httpd.conf]
  $ apachectl restart
   /path/to/apache/sbin/apachectl restart: httpd not running, trying to start
   [Tue Mar 31 11:27:55 1998] [debug] mod_so.c(303): loaded module foo_module
  /path/to/apache/sbin/apachectl restart: httpd started
  $

Vous pouvez même utiliser apxs pour compiler des modules complexes en dehors de l’arborescence d’Apache, comme PHP3, parce que apxs reconnaît automatiquement les fichiers sources C et les fichiers objets.

  $ cd php3
  $ ./configure --with-shared-apache=../apache-1.3
  $ apxs -c -o libphp3.so mod_php3.c libmodphp3-so.a
  gcc -fpic -DSHARED_MODULE -I/tmp/apache/include  -c mod_php3.c
  ld -Bshareable -o libphp3.so mod_php3.o libmodphp3-so.a
  $

Seulement les fichiers sources en C sont compilés pendant que les fichiers objets restant sont utilisés pendant la phase de liaison.

apachectl(1), httpd(8).

Aymeric Nys , <aymeric@nnx.com>.

Gérard Delafond