Apache HTTP Server Version 1.3

Réorganisation des Sources

Pour la version 1.3, les répertoires sources d'Apache ont été réorganisés. Cette réorganisation a eu lieu pour simplifier la structure des répertoires, rendre plus facile l'ajout de modules supplémentaires, et donner aux auteurs de modules un moyen de spécifier les options de compilation ou encore de distribuer des modules binaires.

Sommaire des modifications

Les répertoires sources sont modifiés de plusieurs manières:

Les fichiers sources des hors modules sont déplacés de src à src/main
Les fichiers sources des modules qui se trouvaient précédemment dans src sont maintenant dans src/modules/standard
Le support d'un répertoire se trouve maintenant dans src/support

De plus, les améliorations suivantes ont été apportées :

Les patches spécifiques à chaque OS peuvent être ajoutées dans le répertoire src/os .Il contient actuellement des informations pour unix, OS/2 et les plates-formes Windows 32.

Configuration : la syntaxe pour ajouter de nouveaux modules a été simplifiée. Les utilisateurs n'ont plus besoin d'entrer le nom de la structure d'un module. De plus, les nouveaux modules peuvent être situés n'importe où dans le système de fichiers, ou typiquement dans des sous-répertoires (nouvellement créés ou préexistants) de src/modules.
Les auteurs des modules peuvent utiliser des instructions simplifiées pour permettre l'addition de leurs modules à la compilation d'Apache. Maintenant, ils peuvent également fournir des informations de compilation, requises par Configure, au même titre que les librairies supplémentaires.
Les auteurs de modules peuvent distribuer les versions précompilées (.a or .o) de leurs modules si nécessaire, avec un fichier de définition de module "module definition file", lequel contient les informations demandées par Configure.
Tous les sous-répertoires (main, modules/* and os/*) sont construits comme des librairies.

Ajout de modules

Les modules sont ajoutés à Apache en spécifiant une référence dans src/Configuration puis en activant Configure et make. Dans les versions d'Apache antérieures à la version 1.3, la ligne ajoutée à Configuration ressemblait à ceci:

  Module    status_module    mod_status.o

Désormais, dans la version 1.3 d'Apache, la ligne AddModule devra être utilisée à la place de celle ci-dessus, et ressemblera en général à ceci :

  AddModule    modules/standard/mod_status.o

L'argument de AddModule est le chemin d'accès au fichier source ou objet du module, relativement à src, .

Normalement, quand vous ajoutez un module, vous devez suivre les instructions fournies par l'auteur du module. Cependant si le module se présente sous la forme d'un seul fichier source, mod_foo.c, alors le chemin recommandé pour ajouter ce module à Apache doit être défini comme suit:

Mettre mod_foo.c dans le répertoire src/modules/extra
Aller dans le répertoire src et ajouter la ligne suivante au fichier de Configuration
AddModule modules/extra/mod_foo.o
Exécuter ./Configure
Exécuter make

Nouveaux utilitaires pour les auteurs de modules

Dans les anciennes versions d'Apache, les nouveaux modules étaient ajoutés au répertoire src , et si le module nécessitait la définition d'options de compilation supplémentaires (comme une explicitation de librairie) , ces dernières auraient du être ajoutées au fichier Configuration. L'utilisateur aurait également dû donner le nom du module dans la structure Apache à ajouter sur la ligne "Module" dans le fichier de Configuration.

Désormais sous Apache 1.3 , les auteurs de modules peuvent utiliser ces nouvelles fonctionnalités :

De manière simplifiée, le fichier de Configuration commande le module AddModule, lequel demande seulement un chemin d'accès vers le module source ou le fichier objet.
Si le module requiert des options de compilation (telles que des librairies supplémentaires), elles peuvent être spécifiées dans le fichier source du module ou dans un fichier externe appelé "module definition file".
Si un module est distribué directement dans son format binaire (.o ou .a), alors un fichier externe nommé "module definition file" devra également être distribué, lequel donne les informations nécessaires à l'utilitaire Configure pour ajouter le module, les librairies supplémentaires et le nom du module dans la structure d'Apache.
Les modules peuvent être placés partout dans le système de fichiers, mais de préférence dans un sous-répertoire de src/modules.
Si le module est dans le propre répertoire d'Apache, ce dernier peut automatiquement créer un Makefile pour construire le module et générer un fichier contenant les dépendances du module.

Le reste de ce document montre comment construire des modules pour les versions postérieures à la version 1.3 d'Apache, et indique les informations à fournir aux utilisateurs finaux de ces modules.

Construction d'une distribution simple de sources Apache

Considérez un ajout simple d'un module, distribué sous la forme d'un fichier unique. Par exemple, supposons qu'il s'appelle mod_demo.c. L'archive de ce module devrait être composée de deux fichiers, dans un nom de répertoire approprié. Par exemple:

mod_demo/mod_demo.c
mod_demo/Makefile.tmpl

(Bien sûr, les instructions destinées à l'utilisateur (README, etc.), peuvent également être fournies dans l'archive). Vous devez indiquer aux utilisateurs qu'ils pourront extraire cette archive du répertoire src/modules dans l'arborescence des sources d'Apache. Cela créera un nouveau répertoire appelé src/modules/mod_demo. Les utilisateurs devront en outre ajouter la ligne suivante au fichier de Configuration :

  AddModule  modules/mod_demo/mod_demo.o

Puis exécuter les utilitaires Configure et make comme d'habitude.

Le fichier mod_demo/Makefile.tmpl devra contenir les dépendances induites par le source du module. Par exemple, un module élémentaire, lequel s'interface avec quelques API standards de modules existants dans Apache pourrait ressembler à ceci:

  mod_demo.o: mod_demo.c $(INCDIR)/httpd.h $(INCDIR)/http_protocol.h

Quand l'utilisateur exécutera Configure , Apache créera un makefile complet pour construire ce module. Si ce module exige également que quelques options de compilation supplémentaires soient fournies, telles que la spécification de certaines librairies, on se reportera à la section suivante.

Si des fichiers d'en-tête sont fournis avec le module, ceux-ci seront ajoutés à l'archive. Si le module est composé de multiples fichiers sources, il pourra être construit à l'intérieur d'une librairie à l'aide d'un makefile fourni . Dans ce cas, il faudra distribuer le makefile sous la forme d'un fichier mod_demo/Makefile et ne pas faire apparaître de fichier mod_demo/Makefile.tmpl. Si Configure trouve un fichier Makefile.tmpl , il suppose qu'il est possible de remplacer un quelconque Makefile existant, sans que cela présente un risque quelconque pour la construction.

Reportez-vous au répertoire src/modules/standard pour un exemple de répertoire d'implémentation de module dans lequel le makefile a été automatiquement créé à partir d'un fichier Makefile.tmpl (notez que ce répertoire montre également comment organiser de nombreux modules dans un répertoire unique). Consultez src/modules/proxy et src/modules/example pour des exemples de modules construits à partir de makefiles fournis par le programmeur (lesquels créent respectivement une librairie et un fichier objet).

Adjonction d'informations de compilation

Les fichiers sources d'Apache (ou les fichiers de définition de modules, voir ci-dessous) peuvent contenir des informations utilisées par l'utilitaire Configure pour donner des options de compilation supplémentaires, telles que des spécifications de librairies complémentaires. Par exemple, si mod_demo dans l'exemple ci-dessus exige également qu'Apache soit lié à une librairie DBM , alors le texte suivant peut être inséré dans le source mod_demo.c :

/*
 * Module definition information - the part between the -START and -END
 * lines below is used by Configure. This could be stored in a separate
 * instead.
 *
 * MODULE-DEFINITION-START
 * Name: demo_module
 * ConfigStart
    LIBS="$LIBS $DBM_LIB"
    if [ "X$DBM_LIB" != "X" ]; then
        echo " + using $DBM_LIB for mod_demo"
    fi
 * ConfigEnd
 * MODULE-DEFINITION-END
 */

Notez que cet exemple contient un commentaire "C" à cacher au compilateur. Tout ce qui se trouve entre les labels MODULE-DEFINITION-START et MODULE-DEFINITION-END est exploité par l'utilitaire Configure. Le nom : cette ligne donne le nom de du module tel que le connaît la structure Apache. Ce n'est pas réellement nécessaire dans ce cas, car en cas d'omission, Configure sait générer un nom par défaut basé sur le nom du fichier source d'origine (ex. si le fichier s'appelle "mod_demo", l'en-tête "mod_" sera enlevée, et le suffixe "_module" rajouté pour obtenir le nom dans la structure. C'est valable pour tous les modules distribués avec Apache).

Les lignes entre ConfigStart et ConfigEnd sont exécutées par Configure et peuvent être utilisées pour spécifier des options de compilation et des librairies. Dans le cas concret ci-dessus, la librairie DBM est ajoutée (extraite à partir de $DBM_LIB) aux librairies standard de compilation ($LIB) et un message est affiché.

Consultez le fichier de distribution par défaut mod_auth_dbm.c pour avoir un exemple de définition de module ajouté.

Informations de définition de module en vue d'une distribution de binaires

Si le module a pour but d'être distribué sous la forme de modules binaires (objets ou librairies) plutôt que sources, il n'est pas possible d'ajouter des informations de définition de module au fichier source. Dans ce cas, celles-ci peuvent être placées dans un fichier séparé, lequel a le même nom de base que le fichier objet ou librairie, mais avec une extension .module . Ainsi, par exemple, si le fichier objet du module distribué est mod_demo.o, le fichier de définition de module devra être appelé mod_demo.module. Il contient les mêmes informations que ci-dessus, mais n'a pas besoin d'être à l'intérieur d'un commentaire C ni délimité par MODULE-DEFINITION-START etc. Par exemple:

Name: demo_module
ConfigStart
 LIBS="$LIBS $DBM_LIB"
 if [ "X$DBM_LIB" != "X" ]; then
     echo " + using $DBM_LIB for mod_demo"
 fi
ConfigEnd

Consultez le source de distribution par défault mod_auth_db.module pour un exemple définition de module séparé.