Nginx does not officially provide a mechanism to build out-of-tree modules,
however, this can be achieved by using all the headers and the configure
scripts in the auto/ directory. As a result, a nginx-dev package can thus be
developed for build out-of-tree modules.
The detailed steps to build an out-of-tree module in the headers-only nginx
source tree is:
1. Execute the configure script of nginx, with the same configure arguments
(excluding the reference to other dynamic modules, but including the reference
to depending modules as a built-in module). To prevent the configure scripts
modifying the nginx ource tree, we can 1. point the build dir to a directory
elsewhere, to generate all the build time files outside; 2. slightly patch the
configure scripts to prevent generating a makefile directly in the source tree,
which simply includes the generated makefile at the build dir.
2. Execute make at the source tree, but providing the generated makefile in the
build dir. The command is `make -C /path/to/nginx/source -f
/path/to/build_dir/Makefile modules`
To make sure the compiled module is compatible with the nginx binary and the
nginx binaries with the same upstream version, the key points are:
- Module signature: A module signature containing the (upstream) version number
and encoding the necessary configuration flags is put in each module as well as
the nginx binary itself. When loading a module, nginx will compare the signature
on the module with its own. As long as the configure flags, especially those
encoded in the signature, and the version of the nginx source used to build the
module are the same as thoes used to build the nginx binary, the moudle can pass
the signature check. As a result, the module can depend on the exact nginx
upstream version, ignoring the debian revison.
- ABI compatibility: We should maintain nginx precisely, to prevent making any
ABI changes between different debian revisions.
- Build check: When building the module, we can perform a simple module loading
check via `nginx -t`. This test serves as a "smoking test", to ensure we are
actually building loadable modules.
Summing all the above up and adding the necessary automation scripts for module
packaging, the nginx-dev package can be composed, including the following parts:
- The headers and configure scripts: generated and filtered out from the source
tree. The scripts are slightly patched to prevent generating a makefile directly
in the source tree, as stated above;
- The recorded configure options: all the modules built should include these
options when configured;
- dh_nginx script and its man page: modified from the original dh_nginx script,
adding a "--in-nginx-tree" option. When specified, the behavior remains the same
as the original version (so the option is added in the rule building the
in-package modules). When not specified, the dependency added into misc:Depends
will be the exact upstream nginx version, ignoring the debian revision. E.g.
nginx-common >= 1.20.2, << 1.20.2.1~
- a debhelper sequence plugin which can be enabled by module packages with `dh
--with=nginx`, inserting `dh_nginx` after `dh_install`
- a build system plugin which can bu enabled by module packages with `dh
--buildsystem=nginx_mod`, automating the module building process using the steps
mentioned before.
- autoscript templates used by dh_nginx are also installed without modification.
Currently. the architecture of nginx-dev is any because nginx has arch related
dependencies, which is brought in by http-lua module. After it is
removed from the nginx source tree, the architecture can be changed to
all since no binary is included in this package.
