[Pkg-apache-commits] [SCM] Debian packaging for apache2 (Apache HTTPD 2.x) branch, next, updated. 16f9587f481e796025f48d6f83fee746da07a283
Arno Töll
arno at debian.org
Sun Apr 22 15:02:31 UTC 2012
The following commit has been merged in the next branch:
commit 16f9587f481e796025f48d6f83fee746da07a283
Author: Arno Töll <arno at debian.org>
Date: Sun Apr 22 17:02:09 2012 +0200
Formulate several clarifications in PACKAGING, document -m in PACKAGING.
diff --git a/debian/PACKAGING b/debian/PACKAGING
index 470bf51..d87341b 100644
--- a/debian/PACKAGING
+++ b/debian/PACKAGING
@@ -1,24 +1,31 @@
Contents
========
- Overview
+ 1. Overview
- Packaging Modules
+ 2. Packaging Modules
+ 2.1 '.load' and '.conf' files
+ 2.2 Maintainer scripts
- Packaging Sites and Configurations for Web Applications
+ 3. Packaging Sites and Configurations for Web Applications
+ 3.1 Web application module dependencies
+ 3.2 Package dependencies
- Maintainer Scripts
- Enabling Configurations
- Switching MPMs
+ 4. Maintainer Scripts
+ 4.1 Enabling Configurations
+ 4.2 Switching MPMs
- Tools
- a2query
- apache2-maintscript-helper
- dh_apache2
+ 5. Tools
+ 5.1 a2query
+ 5.2 apache2-maintscript-helper
+ 5.3 dh_apache2
+ 6. Version
+ 6.1 Changes
-Overview
-========
+
+1. Overview
+===========
The Apache 2 web server package in Debian supports two types of reverse
dependencies: modules and web applications. They need to be treated differently
@@ -30,8 +37,15 @@ Furthermore, there are several helper tools available to assist on common tasks.
These are outlined in their respective sub sections as well. You should use
these tools to get maintainer scripts and dependencies right.
-Packaging Modules
-=================
+This document follows normative wording of the Debian Policy Manual §1.1 [1]. The
+words must, should and may, and the adjectives required, recommended and optional,
+are used to distinguish the significance of the various guidelines in this policy
+document.
+
+[1] http://www.debian.org/doc/debian-policy/ch-scope.html#s1.1
+
+2. Packaging Modules
+====================
Modules are packages which are installing third party extensions to the Apache 2
web server which can be loaded at runtim to extend the functionality of the core
@@ -42,25 +56,29 @@ to make sure it does not break upon upgrades.
A module package providing an Apache module must obey our policies to make sure
it can be upgraded without breakage at the installation site. To achieve this, a
-package must build-depend on apache2-dev. This package provides the 'apxs'
-compile helper which makes sure the module is compatible with the Apache 2 web
-server and required include header. If an updated package is not buildable
-with Apache 2.2 anymore, the apache2-dev build-dependency should be versioned
-">> 2.4~", because older versions of apache2-threaded-dev provide apache2-dev.
+package must build-depend on apache2-dev. That package provides the 'apxs'
+compile helper which makes sure the module to be compiled is compatible with the
+Apache 2 web server and the C headers the server is providing as a public
+interface. If an updated package is not buildable with Apache 2.2 anymore, the
+apache2-dev build-dependency should be versioned ">> 2.4~", because older versions
+of apache2-threaded-dev did provide apache2-dev.
The resulting binary package should be called libapache2-mod-<modulename> and
MUST NOT depend on apache2 or apache2-bin. Instead a module package must depend
-on our virtual package providing the module magic number denoting the ABI
+on our virtual package providing the module magic number which is denoting the ABI
compatibility version number. The virtual package is called apache2-api-YYYYMMDD
-and guaranteed to be stable among all binary updates of 2.4.x. The dh_apache2
+and is guaranteed to be stable among all binary updates of 2.4.x. The dh_apache2
helper assists to get dependencies right.
+2.1 '.load' and '.conf' files
+-----------------------------
+
The module must install a 'module.load' file to /etc/apache2/modules-available
where 'module' is the name of the installed module without "mod_" prefix. The
'.load' file must contain an appropriate "LoadModule" directive only.
-Additionally maintainers can declare module dependencies and conflicts in a magic
+Additionally maintainers may declare module dependencies and conflicts in a magic
line in '.load' files which need to be resolved to load a module at the
-installation site. This is useful if a module depends that other modules to be
+installation site. This is useful if a module depends on other modules to be
loaded, or to conflict with other modules if they can't be loaded at the same
time. a2enmod and a2dismod will parse "# Depends: module [module [...]]" and "#
Conflicts: module [module [...]]" magic comments, for example to load mod_foo:
@@ -72,20 +90,23 @@ foo.load:
LoadModule foo_module /usr/lib/modules/mod_foo.so
-Additionally, a 'foo.conf' configuration file can be installed along the 'load'
+Additionally, a 'foo.conf' configuration file may be installed along the 'load'
file to configure the module following the same naming scheme if required. This
is useful if the module in question requires some initial configuration to be
useful. No magic comments are recognized in '.conf' files. Aside they have the
-same functionality and requirements as configuration files (see below). You may
-use only directives provided by default or provided by your module in a module
-'.conf' file.
+same functionality and requirements as configuration files (see section 3 below).
+You should use only directives provided by default by our web server configuration
+or which are provided by your module itelf in a supplied '.conf' file.
-In some rare cases it can't be avoided that a module depends on a loaded module
-before the load process can succeed. However, modules are loaded in a sorted
-alphabetical order. In most cases such pre-load dependencies could be avoided
-upstream. If there is no way out that problem, you may want to add a conditional
-Include in your own module file. Suppose mod_foo relies on mod_bar to be loaded
-before, you may want to write a module 'load' file like this:
+In some rare cases it can't be avoided that a module depends on an another module
+to be loaded already before its own load approach can succeed. The module load
+order is guaranteed to be sorted alphabetically which could yield to problems if
+the new module to be loaded sorts later. In most cases such pre-load dependencies
+could be avoided upstream - consider filing a bug. If there is no way out that
+problem, you may want to add a conditional Include in your own module file.
+
+Suppose mod_foo relies on mod_bar to be loaded before, you may want to write a
+module 'load' file like this:
# Depends: bar
<IfModule !mod_bar.c>
@@ -96,9 +117,13 @@ before, you may want to write a module 'load' file like this:
Please note, that the bar.load file must also contain a respective "<IfModule
!mod_bar.c>" guard as it would be loaded twice oterhwise. Use this method
-extremely sparingly. The "Depends:" magic line is still needed, to make sure
+extremely sparingly and in agreement with related package maintainers only. Note,
+such a module '.load' file must still contain a "Depends:" magic line to make sure
that the a2enmod/a2dismod dependency resolver works correctly.
+2.2 Maintainer scripts
+----------------------
+
Maintainer scripts should not invoke a2enmod directly. Instead, the
apache2-maintscript-helper should be used. Please realize, the helper is not
guaranteed to be installed on the target system. There are certain setups which
@@ -117,12 +142,11 @@ files. Additionally it generates appropriate maintainer scripts. The
apache2-maintscript-helper provides a few functions for common tasks. See their
respective reference documentations below.
-Packaging Sites and Configurations for Web Applications
-=======================================================
+If maintainer scripts use a2enmod/a2dismod manually, they must invoke them with
+the "-m" (maintainer mode) switch.
-NOTE: This version of the apache2 package is still experimental. We expect
-that the general configuration will still change in ways that may make it
-necessary to adjust configuration files that are included in web applications.
+3. Packaging Sites and Configurations for Web Applications
+==========================================================
Web applications are different from modules in that they do not have a hard
dependency on the web server. Typically they require a running web server,
@@ -180,13 +204,16 @@ rules you could do something like:
(Note that some common uses of mod_rewrite for web applications can be replaced
by the relatively new FallbackResource directive.)
-On the other hand, there are use cases where a configuration really needs a
-certain module to be enabled. This is tricky to achieve for web applications as
-dependences could lead to complex dependency chains which could break unrelated
-web applications installed along your package. Thus, we do not resolve module
-dependencies for web applications automatically, but they can be expressed, and
-a2enconf will warn the site administrator about modules which need to enabled.
-Moreover, modules can be arbitrarly enabled and disabled, thus a web
+3.1 Web application module dependencies
+---------------------------------------
+
+There are use cases where a configuration really needs a certain module to be
+enabled. This is tricky to achieve for web applications as dependences could lead
+to complex dependency chains which could break unrelated web applications
+installed along your package. Thus, we do not resolve module dependencies for web
+applications automatically, but they may be expressed (see 'load' files in section
+2.1), and a2enconf will warn the site administrator about modules which need to
+enabled. Moreover, modules can be arbitrarly enabled and disabled, thus a web
application must make sure not to break the web server start-up if a required
module is not available.
@@ -200,22 +227,27 @@ server start-up.
For both types of configuration, configurations and sites dh_apache2 can be used
to assist packagers.
-Web applications must depend (or recommend) apache2 only. Web applications must
-not depend or recommend apache2-bin or apache2-data packages. Generally web
-server dependencies should be declared in the form:
+3.2 Package dependencies
+------------------------
+
+Web applications must depend (or recommend respectively) the apache2 package only. Web
+applications must not depend or recommend apache2-bin or apache2-data packages.
+Generally web server dependencies should be declared in the form:
Depends: apache2 | <alternative web servers you support> | httpd-cgi
Using dh_apache2 assists you to do so, although dh_apache2 declares a weaker
-Recommends relation only. If your web application depends on a particular web
-server module you need to depend on it, too. For example, PHP applications might
-need to formulate dependency lines in the form:
+Recommends relation only. While a consolidated and consistent behavior among web
+applications would be desirable, from Apache's point of view, both alternatives
+are acceptable. If your web application depends on a particular web server module
+you need to depend on it, too. For example, PHP applications might need to
+formulate dependency lines in the form:
Depends: libapache2-mod-php5 | php5-cgi | php5-fpm
Recommends: apache2 | <alternative web servers you support> | httpd-cgi
-Similar to modules, web applications can enable their configuration files in
-maintainer scripts. Use of dh_apache2 is recommended to achieve this. Generally
+Similar to modules, web applications may enable their configuration files in
+maintainer scripts. Use of dh_apache2 is recommended to achieve this. Generally,
special care must be taken not to use Apache2 Debian helper scripts like a2query
and a2enmod unconditionally. You can use the apache2-maintscript-helper tools
provided by the apache2 package for common tasks this way:
@@ -230,15 +262,15 @@ apache2-maintscript-helper. Do not enable or disable modules in web
application maintainer scripts, instead protect your configuration by <IfModule>
clauses if you require non-standard modules.
-Maintainer Scripts
-==================
+4. Maintainer Scripts
+=====================
While it was already discussed briefly in previous sections, here follow some
clarifications regarding the invokation of wrapper scripts in maintainer scripts
of modules and web applications.
-Enabling Configurations
------------------------
+4.1 Enabling Configurations
+---------------------------
Both, modules and web applications should use the apache2-maintscript-helper in
general. The helper will obey local policies to decide when to enable a piece of
@@ -271,8 +303,8 @@ Web Applications:
on removal (and on purge anyway), because important files may be missing
(and that's the point of package removal, anyway).
-Switching MPMs
---------------
+4.2 Switching MPMs
+------------------
Only modules are allowed to switch the enabled MPM. Web applications must not
switch the enabled MPM in their maintainer scripts. To actually switch the MPM,
@@ -309,11 +341,14 @@ was changed successfully. Below you find an example snippet:
fi
-Tools
-=====
+5. Tools
+========
+
+This is an overview of tools supplied with the Apache2 package which can assist to
+build web application and module packages.
-apache2-maintscript-helper
---------------------------
+5.1 apache2-maintscript-helper
+------------------------------
The apache2-maintscript-helper is a collection of functions which can be
sourced in maintainer scripts to do required tasks in a simple and
@@ -345,27 +380,27 @@ something went wrong:
echo "Whoops! Something went wrong"
fi
-dh_apache2
-----------
+5.2 dh_apache2
+--------------
dh_apache2 is a debhelper which can be used to install modules, module
configuration, site configuration and global configuration snippets. It assists
you to set appropriate dependencies and maintainer scripts. Refer to
dh_apache2(1) for full usage guidelines.
-a2enmod
--------
+5.2 a2enmod
+-----------
a2enmod and its special invokations a2enconf, a2ensite, a2dismod, a2dissite and
a2disconf can be used to enable all types of Apache 2 configuration files. When
invoking these helpers in maintainer scripts, you should carefully check their
-error return codes. Use these scripts with the -q (quiet) switch only in
-maintainer scripts. Ideally you should not interface with this scripts
-directly, instead it is recommended to use apache2-maintscript-helper. For
-detailed usage refer to their respective man pages.
+error return codes. These scripts must be used with the -q (quiet) and -m
+(maintainer mide) switches only in maintainer scripts. Preferrably you should not
+interface with this scripts directly, instead it is recommended to use
+apache2-maintscript-helper. For detailed usage refer to their respective man pages.
-a2query
--------
+5.3 2query
+----------
a2query is a query tool to retrieve runtime status information about the Apache
2 web server instance. You can use this tool to get information about loaded
@@ -387,3 +422,19 @@ site and make actions dependent on the result like this:
Refer to the a2query(1) man page for the full documentation. Please note, the
apache2-maintscript-helper can be used to inteface with this task as well.
+
+6. Version
+==========
+
+Document version: 1.0
+
+Starting with Apache2 2.4.2-2 this document is versioned. Any change which affects
+packaging are denoted by an increased major nummer, clarifications, spelling fixes
+and minor edits are denoted by minor numbers. In future, a changelog will appear
+here as well.
+
+6.1 Changes
+-----------
+
+1.0:
+ * first version of this document which is versionated.
diff --git a/debian/changelog b/debian/changelog
index d80f513..b574971 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -13,10 +13,10 @@ apache2 (2.4.2-2) experimental; urgency=low
configuration files for consitency.
* Fix "Fix typographic errors in configuration file comments": Thanks to Oxan
van Leeuwen for providing a patch (Closes: #669269)
+ * Formulate several clarifications in PACKAGING, start versioning this document
+ and add normative read hints. Moreover, document the -m switch for a2enmod.
-
-
- -- Arno Töll <arno at debian.org> Fri, 20 Apr 2012 20:10:11 +0200
+ -- Arno Töll <arno at debian.org> Sun, 22 Apr 2012 17:00:25 +0200
apache2 (2.4.2-1) experimental; urgency=low
--
Debian packaging for apache2 (Apache HTTPD 2.x)
More information about the Pkg-apache-commits
mailing list