Project:Apache/Developer Documentation

From Gentoo Wiki
Jump to:navigation Jump to:search

This document provides details about the eclasses available for developers of packages that relate to the Apache webserver.

Apache Module Howto

Overview

This chapter will guide a developer through creating an ebuild using one of our more complex packages, www-apache/mod_ldap_userdir as an example. All Apache modules need to use the apache-module.eclass in order to work with future changes to the apache core.

Apache Path Locations

In order to closely follow how upstream and other distributions install apache, the following paths must be used as specified by depend.apache.eclass:

Use Variable Path
Server Root APACHE_BASEDIR /usr/lib/apache2/
Configuration Directory APACHE_CONFDIR /etc/apache2/
Vhosts Configuration APACHE_VHOSTS_CONFDIR /etc/apache2/vhosts.d/
Modules Configuration APACHE_MODULES_CONFDIR /etc/apache2/modules.d/
Module Binaries APACHE_MODULESDIR /usr/lib/apache2/modules/
Include Files Directory APACHE_INCLUDEDIR /usr/include/apache2/
Apache Binary APACHE_BIN /usr/sbin/apache2
Apache Control Script APACHE_CTL /usr/sbin/apache2ctl
APXS Binary APXS /usr/sbin/apxs2
Note
If your package isn't actually a module but just needs to know the paths Apache uses, just inherit depend.apache and use the variables made available to you in the eclass. See the depend.apache.eclass documentation.

Overview of apache-module ebuilds

  • Generally all functions can be removed from the ebuild
  • Check to see if the default src_compile in the eclass will work. If not, set APXS2_ARGS to compile other files as required.
  • Replace any DEPEND on Apache with one of the need_apache* functions described in the depend.apache.eclass documentation.
  • Create the module configuration file to use IfDefine s to load and configure the module
  • Add any documentation files to DOCFILES
  • Specify the configuration file src_install should install: APACHE2_MOD_CONF
  • Specify the IfDefine that the module uses in its configuration file so pkg_postinst can give user information on how to enable the module: APACHE2_MOD_DEFINE

Ebuild Globals

CODE mod_ldap_userdir-1.1.12 (edited)
inherit apache-module

DESCRIPTION="Apache module that enables ~/public_html from an LDAP directory."
HOMEPAGE="http://horde.net/~jwm/software/mod_ldap_userdir/"
SRC_URI="http://horde.net/~jwm/software/mod_ldap_userdir/${P}.tar.gz"

LICENSE="GPL-1"
SLOT="0"
KEYWORDS="~ppc ~x86"
IUSE="ssl"

DEPEND="ssl? ( dev-libs/openssl )
    net-nds/openldap"
RDEPEND="${DEPEND}"

DOCFILES="DIRECTIVES README user-ldif posixAccount-objectclass"

APXS2_ARGS="-lldap -llber -c ${PN}.c"
APACHE2_MOD_CONF="47_mod_ldap_userdir"
APACHE2_MOD_DEFINE="LDAP_USERDIR"

need_apache2_2

We start off with inherit apache-module which also inherits depend.apache. depend.apache defines the locations Apache uses and more importantly, defines three DEPENDs: APACHE2_2_DEPEND for those packages that need Apache-2.2*, APACHE2_DEPEND for those packages that need Apache-2*, and APACHE_DEPEND for those packages that need either any version of Apache.

apache-module does the heavy lifting for the module packages by defining sane defaults forpkg_setup,src_compile ,src_install andpkg_postinst.

depend.apache handles adding the correct Apache DEPEND to your DEPEND (if you call one of theneed_apache* functions) so you can skip the apache DEPEND handling in your ebuild.

DOCFILES is used by thesrc_install inapache-modules to install all the documentation.src_install automatically detects html files and other files and uses eitherdodoc ordohtml to install them to their correct locations.

APACHE2_MOD_CONF define the configuration file to install for the module. This is used duringsrc_install and needs to be relative toFILESDIR . See theapache-module.eclass documentation for details.

APACHE2_MOD_DEFINE tells the eclass which<IfDefine MODULENAME> the module uses. It is used for displaying instructions to the user on how to enable the module.

src_compile

src_compile may be needed if the module requires special steps that the eclass can't handle. This would be a rare case. In most cases, just reviewing the Makefile and adding items toAPXS2_ARGS will be sufficient.

CODE mod_ldap_userdir-1.1.12 (edited)
src_compile() {
    econf || die "econf failed"
    use ssl && APXS2_ARGS="${APXS2_ARGS} -DTLS=1"
    apache-module_src_compile
}
Note
In general, if APXS2_ARGS needs to be different, it is defined in global space. mod_ldap_userdir is different in this respect, because the state of the ssl USE-flag affects those variables and it's more efficient to only set those values in src_compile rather than run the USE check during every invocation of the ebuild.

src_install

In most cases, src_install will not be needed. The exceptions are when there are other directories that need to be installed or when file permissions need to be changed.

CODE mod_ldap_userdir-1.1.12 (edited)
src_install() {
    apache-module_src_install
    fperms 600 "${APACHE_MODULES_CONFDIR}"/47_mod_ldap_userdir.conf
}

As you can see, in mod_ldap_userdir we need to set the proper permissions on its configuration file. But we still let apache-module strut it's stuff by calling apache-module_src_install inside our src_install . In most cases, src_install will not be needed at all.

src_install completely handles installing the module, configuration files and documentation into the correct places.

Other functions

In most cases, there should not be any pkg_postinst or pkg_config as the eclass handles outputting instructions to the user about enabling a module and where the configuration file is. If additional setup instructions are needed, then a pkg_postinst can be added, but should also run apache-module_pkg_postinst inside it.

With the default configuration of Apache, we dont't need to have the user modify their httpd.conf to enable a module. All the

  • .conf files in the modules.d directory are included automatically. Every file there should be completely wrapped in an <IfDefine MODULENAME> block so that the directives in that file are only used if the user adds a "-D MODULENAME" to their /etc/conf.d/apache2 file.

Configuration file

Every module configuration file needs to be wrapped in <IfDefine MODULENAME> blocks. If you don't do this, then Apache will load the module by default, which we don't want - module loading is to be controlled by the user, using the /etc/conf.d/apache2 file.

CODE sample config file
<IfDefine LDAP_USERDIR>
LoadModule ldap_userdir_module modules/mod_ldap_userdir.so

# Put a good default configuration here:
LDAPUserDir             public_html
LDAPUserDirDNInfo       cn=root,dc=yourcompany,dc=com yourpassword
LDAPUserDirBaseDN       ou=People,dc=yourcompany,dc=com

</IfDefine>

Acknowledgements

We would like to thank the following authors and editors for their contributions to this guide:

  • Michael Stewart
  • Benedikt Böhm
Retrieved from "https://wiki.gentoo.org/index.php?title=Project:Apache/Developer_Documentation&oldid=746340"