Project:Apache/Developer Documentation

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

Overview
This chapter will guide a developer through creating an ebuild using one of our more complex packages,  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:

Overview of apache-module ebuilds

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

Ebuild Globals
We start off with  which also inherits. defines the locations Apache uses and more importantly, defines three s:   for those packages that need Apache-2.2*,   for those packages that need Apache-2*, and   for those packages that need either any version of Apache.

does the heavy lifting for the module packages by defining sane defaults for, ,  and.

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

is used by the in  to install all the documentation. automatically detects html files and other files and uses either or  to install them to their correct locations.

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

tells the eclass which the module uses. It is used for displaying instructions to the user on how to enable the module.

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 and adding items to  will be sufficient.

src_install
In most cases,  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.

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

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  can be added, but should also run   inside it.

With the default configuration of Apache, we dont't need to have the user modify their to enable a module. All the files in the  directory are included automatically. Every file there should be completely wrapped in an  block so that the directives in that file are only used if the user adds a   to their  file.

Configuration file
Every module configuration file needs to be wrapped in  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 file.

Acknowledgements
We would like to thank the following authors and editors for their contributions to this guide:
 * Michael Stewart
 * Benedikt Böhm