Documentation Apache pour les développeurs

1.  À propos de ce document

Ce document détaille les nouvelles eclass, ce que nous avons changé depuis le précédent modèle d'Apache, et la façon dont les ebuilds ont besoin d'être modifiés pour tenir compte des avantages de nos nouvelles eclass. Si vous êtes un utilisateur à la recherche d'informations pour la mise à jour d'Apache, veuillez plutôt consulter le documentation de la mise à jour d'Apache.

2.  Ce qui a changé

Vue d'ensemble

Nous avons fait beaucoup de changements concernant la procédure d'installation et d'utilisation d'Apache et de ses modules sous Gentoo. Cela facilite les tâches de maintenance et permet de suivre de près les versions en amont. Voici nos changements :

• Correction de nombreux bogues
• Changement des chemins d'installation et de configuration
• Création des eclass depend.apache et apache-module
• Fusion des fichiers apache.conf et commonapache.conf en un seul fichier très similaire à la version de base
• Dédoublement de apr et apr-utils en-dehors du paquet principal d'Apache pour ceux qui ne nécessitent plus Apache
• Mise à jour et estampillage d'une version pour presque chaque module
• Mise à disposition d'un plus grand nombre de MPM
• Ajout du support de lingerd
• Fixation du support des longs fichiers
• Et bien plus encore, je suis sûr que j'en oublie...

Localisation des chemins d'Apache

Afin de suivre de plus près l'installation d'Apache en amont et celle des autres distributions, les chemins suivant ont changé :

Apache 2.x

3.  Mise à jour d'un ebuild

Avec nos nouveaux changements, pratiquement chaque ebuild qui dépend d'Apache doit être modifié. L'équipe d'Apache a déjà pris compte d'une grande majorité de ces paquets, car ils en sont responsables. Mais il en reste plusieurs qui appartiennent à d'autres mainteneurs et qui ont besoin d'être mis à jour.

Ce chapitre a pour but de guider un développeur à travers la mise à jour d'un ebuild pour utiliser les nouvelles eclass, en s'appuyant sur un de nos paquets les plus complexes, www-apache/mod_ldap_userdir par exemple.

Vue d'ensemble des changements nécessaires

• Une nouvelle révision sera nécessaire tant que les versions modifiées pour les nouvelles eclass ne sont pas rétro-compatibles avec les anciennes versions d'Apache.
• Assurez-vous d'avoir mis votre KEYWORDS en instable et (si les paquets d'Apache sont encore masqués) ajoutez-les au fichier package.mask.
• Remplacez chaque DEPEND d'Apache par need_apache1 (pour les modules de Apache-1*), par need_apache2 (pour les modules d'Apache-2*), ou par need_apache (pour les modules qui peuvent dépendre d'Apache-1* ou d'Apache-2* — selon les variables USE indiquées).
• Retirez n'importe quel code spécifique qui modifie le SLOT ou DEPEND avec des « bidouilles » telles que has_version.
• Vérifiez que le src_compile par défaut dans l'eclass est fonctionnel. Si ce n'est pas le cas, réglez APXS1_ARGS et/ou APXS2_ARGS pour compiler les autres fichiers requis.
• Généralement toutes les fonctions peuvent être retirées de l'ebuild.
• Modifiez le fichier de configuration des modules afin d'utiliser les directives IfDefine pour charger et configurer le module.
• Ajoutez les fichiers de documentation dans DOCFILES.
• Spécifiez les fichiers de configuration que src_install devra installer : APACHE1_MOD_CONF, APACHE2_MOD_CONF.
• Spécifiez le IfDefine que le module utilise dans son fichier de configuration, pkg_postinst peut vous donner des informations utiles pour activer le module : APACHE1_MOD_DEFINE, APACHE2_MOD_DEFINE.
• N'oubliez pas de le tester — suivez les instructions de mise à jour de ce document si vous ne l'avez pas déjà fait.

Ebuilds globaux

+inherit apache-module
+
-IUSE="apache2 ssl"
+IUSE="ssl"

 DESCRIPTION="Apache module that enables ~/public_html from an LDAP directory."
 HOMEPAGE="http://horde.net/~jwm/software/mod_ldap_userdir/"
-KEYWORDS="x86 ppc"
+KEYWORDS="~x86 ~ppc"

 SRC_URI="http://horde.net/~jwm/software/mod_ldap_userdir/${P}.tar.gz"

-DEPEND="=net-www/apache-1*
-       apache2? ( =net-www/apache-2* )
-       ssl? ( dev-libs/openssl )
-       net-nds/openldap"
+DEPEND="ssl? ( dev-libs/openssl )
+       net-nds/openldap"

 LICENSE="GPL-1"
 SLOT="0"
+
+DOCFILES="DIRECTIVES README user-ldif posixAccount-objectclass"
+APACHE1_MOD_CONF="${PVR}/47_mod_ldap_userdir"
+APACHE2_MOD_CONF="${PVR}/47_mod_ldap_userdir"
+APACHE1_MOD_DEFINE="LDAPuserdir"
+APACHE2_MOD_DEFINE="LDAPuserdir"
+
+need_apache

Nous commençons avec inherit apache-module qui hérite également depend.apache. depend.apache définit les localisations qu'utilise Apache et, plus important, définit trois DEPEND : APACHE1_DEPEND pour les paquets qui ont besoin d'Apache-1*, APACHE2_DEPEND pour les paquets qui ont besoin d'Apache-2*, et APACHE_DEPEND pour les paquets qui peuvent avoir besoin soit d'Apache-1* soit d'Apache-2* et qui laissent à la variable USE apache2 le soin de déterminer cela.

apache-module s'occupe d'une lourde tâche pour les paquets de module en définissant des valeurs convenables par défaut pour pkg_setup, src_compile, src_install et pkg_postinst.

Comme depend.apache ajoute apache2 à IUSE si nécessaire, vous ne devez plus le définir explicitement dans l'IUSE des ebuilds. Vous devrez cependant le laisser défini si vous employez cette variable USE dans votre ebuild quelque part.

depend.apache s'exécute en ajoutant le DEPEND Apache correct à votre DEPEND (si vous appelez l'une des fonctions de need_apache{|1|2}), ainsi vous pouvez retirer le traitement du DEPEND Apache de votre ebuild.

DOCFILES est utilisé par src_install dans apache-modules pour installer toutes les documentations. src_install détecte automatiquement les fichiers html et les autres fichiers, et utilise dodoc ou dohtml pour les installer à leur bonne place.

APACHE1_MOD_CONF et APACHE2_MOD_CONF définissent le fichier de configuration à installer pour le module. Ceci est utilisé pendant le src_install, ainsi ils peuvent être liés à ce que vous avez défini pour APXS1_S ou APXS2_S (par défaut à ${S}/src si c'est un répertoire, ou juste ${S}).

APACHE1_MOD_DEFINE et APACHE2_MOD_DEFINE indiquent aux eclass de quelle directive <IfDefine MODULENAME> le module se sert. Il est utilisé pour afficher à l'utilisateur des commandes sur la façon d'activer le module.

src_compile

src_compile peut être nécessaire si le module requiert des étapes spéciales que l'eclass ne peut traiter. Ce serait un cas assez exceptionnel. Dans la plupart des cas, en passant juste en revue le fichier Makefile et en ajoutant les éléments à APXS1_ARGS ou APXS2_ARGS, cela devrait être suffisant.

-src_compile() {
-   local myconf
-   if use apache2; then
-       myconf="${myconf} --with-apxs2=/usr/sbin/apxs2"
-   else
-       myconf="${myconf} --with-apxs=/usr/sbin/apxs"
-   fi
-
-   use ssl && myconf="${myconf} -with-tls"
-
-   myconf="${myconf} --with-activate"
-   ./configure ${myconf} || die "Configure failed"
-   make clean
-   make || die "Make failed"
-}

+src_compile() {
+   local myargs="-lldap -llber -c ${PN}.c"
+   use ssl && myargs="${myargs} -D TLS=1"
+
+   APXS2_ARGS="${myargs}"
+   APXS1_ARGS="${myargs}"
+
+   apache-module_src_compile
+
+}

src_install

Dans la plupart des cas, src_install ne sera pas nécessaire. Il y a des exceptions quand d'autres répertoires ont besoin d'être installés ou quand les droits de fichiers doivent être changés.

-src_install() {
-   if use apache2; then
-       exeinto /usr/lib/apache2-extramodules
-       doexe mod_ldap_userdir.so
-   else
-       exeinto /usr/lib/apache-extramodules
-       doexe mod_ldap_userdir.so
-   fi
-   dodoc DIRECTIVES README user-ldif posixAccount-objectclass
-}
+src_install() {
+   apache-module_src_install
+   if [ "${APACHE_VERSION}" == "2" ]; then
+       fperms 600 ${APACHE2_MODULES_CONFDIR}/$(basename ${APACHE2_MOD_CONF})
+   else
+       fperms 600 ${APACHE1_MODULES_CONFDIR}/$(basename ${APACHE1_MOD_CONF})
+   fi
+}

Comme vous pouvez le voir, dans mod_ldap_userdir nous avions en fait ajouté quelques corrections qui n'étaient pas présentes dans la révision précédente — l'ajout d'un fichier de configuration et le réglage des permissions appropriées dessus. Mais nous permettons encore la présentation de apache-module en appelant apache-module_src_install à l'intérieur de notre src_install. Dans la plupart des cas, src_install ne sera pas nécessaire du tout.

src_install traite complètement l'installation du module, la configuration des fichiers et la documentation aux endroits corrects.

Autres fonctions

Dans la plupart des cas, il ne devrait y avoir ni pkg_postinst ni pkg_config pendant que les eclass manipulent des instructions d'affichage à l'utilisateur à propos de l'activation d'un module et de l'emplacement du fichier de configuration. Si des instructions additionnelles d'installation sont nécessaires, alors un pkg_postinst peut être ajouté, mais il devrait alors exécuter apache1_pkg_postinst ou apache2_pkg_postinst à l'intérieur de lui-même.

-pkg_postinst() {
-   if use apache2; then
-       elog "Adjust /etc/apache2/conf/modules.d/47_mod_ldap_userdir.conf to match your setup and"
-       elog "add '-D LDAPuserdir' to your APACHE2_OPTS in /etc/conf.d/apache2"
-       elog "To configure the package run \"ebuild /var/db/pkg/net-www/${PF}/${PF}.ebuild config\""
-   fi
-}
-
-pkg_config() {
-   /usr/sbin/apacheaddmod \
-       ${ROOT}/etc/apache/conf/apache.conf \
-       extramodules/mod_ldap_userdir.so mod_ldap_userdir.c ldap_userdir_module \
-       define=LDAPuserdir addconf=conf/addon-modules/47_mod_ldap_userdir.conf
-}

Avec la nouvelle configration par défaut d'Apache, nous n'avons plus besoin d'obliger l'utilisateur à modifier son fichier httpd.conf pour activer le module. Tous les fichiers *.conf du répertoire modules.d sont inclus automatiquement. Chaque fichier présent devra être complètement compris dans un bloc <IfDefine MODULENAME>, de telle sorte que les directives dans ce fichier ne soient utilisées que si les utilisateurs ajoutent un "-D MODULENAME" à leur fichier /etc/conf.d/apache{|2}.

Fichier de configuration

La plupart des fichiers de configuration n'auront besoin que de peu de changements. Voici le principal à surveiller pour être sûr qu'il utilise le chemin correct au chargement du module :

(Ancienne directive :)
LoadModule ldap_userdir_module extramodules/mod_ldap_userdir.so

(Nouvelle directive :)
LoadModule ldap_userdir_module modules/mod_ldap_userdir.so

Ainsi, chaque fichier de configuration de module a besoin d'être compris dans un bloc <IfDefine MODULENAME>. Si vous ne faites pas cela, alors Apache chargera le module par défaut, ce que nous ne voulons pas — le chargement du module doit être contrôlé par l'utilisateur, en utilisant le fichier /etc/conf.d/apache{|2}.

<IfDefine LDAPuserdir>
  <IfModule !mod_ldap_userdir.c>
    # Load the module:
    LoadModule ldap_userdir_module modules/mod_ldap_userdir.so
  </IfModule>
</IfDefine>

<IfModule mod_ldap_userdir.c>
# Mettez une bonne configuration par défaut ici :

    LDAPUserDir             public_html
    LDAPUserDirDNInfo       cn=root,dc=yourcompany,dc=com yourpassword
    LDAPUserDirBaseDN       ou=People,dc=yourcompany,dc=com

</IfModule>

4.  Eclass apache-module

Description

L'eclass apache-module fournit des fonctions convenables par défaut pour la compilation des modules Apache. Puisque la plupart des modules sont compilés exactement de la même manière, ceci permet aux ebuilds de modules d'être extrêmement simples.

Fonctions

Variables

5.  Eclass depend.apache

Description

L'eclass depend.apache règle les localisations par défaut des différents chemins d'Apache et gère les paramètres des dépendances sur Apache. En général, cette eclass ne devrait pas être utilisée par les modules. Elle devrait seulement être employée pour les programmes qui doivent dépendre d'Apache mais qui ne sont pas des modules. (Les modules devraient employer l'eclass apache-module.)

Fonctions

Variables

Ce document est protégé par la licence Creative Commons : Paternité - Partage des Conditions Initiales à l'Identique 2.5.