NGINX-MODULE.ECLASS

Section: eclass-manpages (5)
Updated: Jul 2025
Index Return to Main Contents

NAME

nginx-module.eclass - Provides a common set of functions for building NGINX's dynamic modules

DESCRIPTION

The nginx-module.eclass automates configuring, building and installing NGINX's dynamic modules. Using this eclass is as simple as calling 'inherit nginx-module'. This eclass automatically adds dependencies on www-servers/nginx. Henceforth, the terms 'package' and 'module' will be used interchangeably to refer to a consumer of nginx-module.eclass.

If a part of package's functionality depends on NGINX configuration (e.g. HMAC generation support depending on http_ssl module being present), the corresponding module's 'config' code should be changed so that the functionality in question is either (1) unconditionally enabled/disabled or (2) can be toggled with a USE flag. That is, an ebuild author should deduce whether a package actually depends on a particular module or on the underlying libraries/APIs. In the example HMAC case, the module actually requires libcrypto, not the http_ssl module, so the ebuild code reflects this by patching the module's 'config' file and depending on dev-libs/openssl directly using the ngx_mod_append_libs() function.

If the module makes use of the ngx_devel_kit (NDK) or any other NGINX module, there are two approaches.

If these dependencies are not USE-conditional ones, they should be specified in the NGINX_MOD_LINK_MODULES array before inheriting the eclass. This way, the dependencies added to {,R}DEPEND variables. Additionally, the package is linked to shared objects of the specified dependencies. See the variable description for details.

If the dependencies are USE-conditional, they should be specified as usual in the relevant *DEPEND variable(s). Then, before nginx-module_src_configure() is called, the dependencies should be linked to by calling the ngx_mod_link_module() function. See the function description for more information.

nginx-module.eclass also supports tests provided by the Test::Nginx Perl module. To enable them, set NGINX_MOD_OPENRESTY_TESTS to a non-empty value prior to inheriting the eclass and, if necessary, populate the NGINX_MOD_TEST_LOAD_ORDER variable. All the packages specified in NGINX_MOD_TEST_LOAD_ORDER are added to BDEPEND.

The code below presents one of the ways the nginx-module.eclass might be used.

Example usage: # This module depends on ngx_devel_kit and ngx-lua-module. NGINX_MOD_LINK_MODULES=(
www-nginx/ngx_devel_kit www-nginx/ngx-lua-module )

# Tests utilise Test::Nginx. NGINX_MOD_OPENRESTY_TESTS=1 # We require ngx-lua-module and ngx-echo for tests, but ngx-echo should # be loaded first. Otherwise, some tests break. NGINX_MOD_TEST_LOAD_ORDER=(
www-nginx/ngx-echo
www-nginx/ngx-lua-module ) inherit nginx-module

IUSE="iconv"

DEPEND="iconv? ( www-nginx/ngx-iconv )" RDEPEND="${DEPEND}"

src_configure() {
    if use iconv; Then
        ngx_mod_link_module "www-nginx/ngx-iconv"
        ...
    fi

nginx-module_src_configure }

SUPPORTED EAPIS

FUNCTIONS

econf_ngx [<args>...]

Call ./configure, passing the supplied arguments. The NGINX's build system consists of many helper scripts, which are executed relative to the working directory. Therefore, the function only supports executing the configure script from the current working directory. This function also checks whether the script is executable. If any of the above conditions are not satisfied, the function aborts the build process with 'die'. It also fails if the script itself exits with a non-zero exit code, unless the function is called with 'nonfatal'. If running ./configure is required, this function should be called.

ngx_mod_pkg_to_sonames <package name>

Takes one argument and prints a null-delimited list of basenames of shared objects corresponding to the supplied package.

The mapping between a package and shared objects goes as follows.

1. The package is stripped of category, yielding a plain
package name.

    2. The plain package name is then used to lookup into the internal
    associative array NGX_MOD_TO_SONAME.  If the lookup fails, the build is
    aborted with 'die'.  'nonfatal' might be used to make the error to find
    shared objects non-fatal.

3. The obtained shared objects are printed to the stdout as a
null-delimited list.

Example usage: # Obtain shared objects provided by www-nginx/ngx-lua-module. mypkg=www-nginx/ngx-lua-module mapfile -d '' lua-sonames < <(ngx_mod_pkg_to_sonames "${mypkg}")

Return value: Null-delimited list of basenames of shared objects corresponding to the supplied package.

ngx_mod_append_libs [<linker flags>...]

Adds the passed arguments to the list of flags used for the linking the module's shared objects. Flags may be of any form accepted by linker. See the nginx_src_install() function in nginx.eclass for more details.

This function has no effect after nginx-module_src_configure() has been called.

Example usage: ngx_mod_append_libs "-L/usr/$(get_libdir)/nginx/modules" \ "$("$(tc-getPKG_CONFIG)" --libs luajit)"

ngx_mod_setup_link_modules

Adds necessary linker arguments for linking to other NGINX modules' share objects installed in /usr/$(get_libdir)/nginx/modules by calling ngx_mod_append_libs(). This function takes no arguments.

This function is called internally by the ngx_mod_link_module() function. ngx_mod_setup_link_modules() keeps track whether it has already been called, doing nothing if it is called again after the first execution.

ngx_mod_link_module <package name>

Add the required linker flags to link to the shared objects provided by the package passed as the argument. This function automatically calls ngx_mod_setup_link_modules(), if it has not been called. If the specified package provides more than one shared object, all of the shared objects are linked to. As ngx_mod_append_libs(), this function has no effect after nginx-module_src_configure has been called.

This function uses the ngx_mod_pkg_to_sonames() function under the hood to map package names to shared objects. If there are no predefined mappings for the selected package, the NGX_MOD_TO_SONAME associative array may be changed manually, as presented in the following code excerpt.

NGX_MOD_TO_SONAME+=(
[www-nginx/ngx-pkg-name]="the_corresponding_soname_without_dot_so_suffix" )

See the default value of NGX_MOD_TO_SONAME for examples.

This function might be used to implement USE-conditional dependency on another NGINX module. See the code snipped below for an example of such usage.

Example usage: inherit nginx-module

DEPEND="iconv? ( www-nginx/ngx-iconv )" RDEPEND="${DEPEND}"

src_configure() {
    if use iconv; then
        ngx_mod_link_module "www-nginx/ngx-iconv"
        ...
    fi

nginx-module_src_configure }

nginx-module_src_unpack

Unpacks the sources and sets up the build directory in S=${WORKDIR}/nginx. Creates the following symbolic links (to not copy the files over):
- '${S}/src' -> '/usr/include/nginx',
- '${S}/auto' -> '/usr/src/nginx/auto',
- '${S}/configure' -> '/usr/src/nginx/configure'. For additional information, see the nginx.eclass source, namely the nginx_src_install() function.

nginx-module_src_prepare

Patches module's initialisation code so that any module's preprocessor definitions appear in the separate '__ngx_gentoo_mod_config.h' file inside the 'build' directory. This function also makes module's "config" script clear whatever content build/ngx_auto_config.h may have at the time of invocation. Then, default_src_prepare() is called.

nginx-module_src_configure

Configures the dynamic module by calling NGINX's ./configure script. Custom flags can be supplied as arguments to the function, taking precedence over eclass's flags. This assembles ngx_auto_config.h from the system ngx_auto_config.h and __ngx_gentoo_mod_config.h (see nginx-module_src_prepare()), and ngx_auto_headers.h from the system ngx_auto_headers.h. Also, sets environment variables and appends necessary libraries if NGINX_MOD_LINK_MODULES is set.

nginx-module_src_compile

Compiles the module(s) by calling "make modules" and fills the NGINX_MOD_SHARED_OBJECTS array.

nginx-module_src_test

If NGINX_MOD_OPENRESTY_TESTS is set to a non-empty value, tests the compiled module using Test::Nginx (dev-perl/Test-Nginx).

nginx-module_src_install

Installs the compiled module(s) into /usr/${libdir}/nginx/modules.

nginx-module_pkg_postinst

Shows the instructions on how to enable and use the just-compiled module.

ECLASS VARIABLES

NGINX_MOD_S = ${S}}"

Holds the path to the module sources directory, used in the nginx-module_src_configure() phase function. If unset at the time of inherit, defaults to ${S}.

NGINX_MOD_SHARED_OBJECTS (GENERATED BY ECLASS)

An array containing the basenames of all compiled shared objects (with the extension ".so"). For some modules, may consist of more than one shared object.

This variable is set in the nginx-module_src_compile() function. Its contents are undefined before that.

Example value: ngx_http_lua_module.so

NGX_MOD_TO_SONAME

An associative array that maps NGINX module package names to their shared object names. For example, 'ngx-lua-module' is mapped to 'ngx_http_lua_module'. The shared objects are specified without the '.so' suffix. May be changed/appended to at any time by an ebuild to override/add shared object mappings.

NGINX_MOD_LINK_MODULES (SET BEFORE INHERIT)

Set to package names of the NGINX module dependencies of this module. This array must be set prior to inheriting the eclass.

All the modules specified in this array are added to DEPEND and RDEPEND. This might be disabled by setting NGINX_MOD_OVERRIDE_LINK_DEPEND to a non-empty value. Additionally, the listed modules are added to the NEEDED sections of the current module's shared objects, i.e. the current module is dynamically linked to the shared objects corresponding to packages specified in NGINX_MOD_LINK_MODULES.

Each element of the array specifies a dependency of an ebuild. An entry consists of a category followed by a package name: ${CATEGORY}/${PN}.

To determine the shared object corresponding to an entry, the eclass looks up the respective mapping, specified in the NGX_MOD_TO_SONAME array (see the array description for more information). If no match is found, the build is aborted with 'die'.

Example usage: # This module depends on both NDK and ngx-lua-module. NGINX_MOD_LINK_MODULES=(
www-nginx/ngx_devel_kit
www-nginx/ngx-lua-module ) inherit nginx-module

NGINX_MOD_OVERRIDE_LINK_DEPEND (SET BEFORE INHERIT)

Set to a non-empty value prior to inheriting the eclass so that the modules listed in NGINX_MOD_LINK_MODULES are not automatically added to DEPEND and RDEPEND.

NGINX_MOD_OPENRESTY_TESTS (SET BEFORE INHERIT)

Set to non-empty value to enable prior to inheriting the eclass to enable the tests via the Test::Nginx (dev-perl/Test-Nginx) testing scaffold. See the description of the NGINX_MOD_TEST_LOAD_ORDER variable for more details.

NGINX_MOD_TEST_DIR ?= t

Set to directory containing tests relative to NGINX_MOD_S. If NGINX_MOD_OPENRESTY_TESTS is not set, has no effect. Defaults to "t".

NGINX_MOD_TEST_LOAD_ORDER (SET BEFORE INHERIT)

If NGINX_MOD_OPENRESTY_TESTS is set to a non-empty value, this array specifies simultaneously the test dependencies of the current module and, since NGINX is sensitive to the order of module loading, their load order. As a special workaround, the current module could also be specified as an entry in order to force a specific load order. If the current module is not listed in this array, it is loaded first, before its test dependencies.

All the modules specified in this array, barring the current module, are added to test BDEPEND. This behaviour may be disabled by setting the NGINX_MOD_OVERRIDE_TEST_BDEPEND variable to a non-empty value.

The format of each entry is the same as in the NGINX_MOD_LINK_MODULES variable. See its description for details.

The shared object names obtained from each entry are then used to populate the TEST_NGINX_LOAD_MODULES environment variable. TEST_NGINX_LOAD_MODULES instructs Test::Nginx in what order and which shared objects should be loaded during tests.

This array must be set prior to inheriting the eclass. If NGINX_MOD_OPENRESTY_TESTS is not set, this variable has no effect.

Example: NGINX_MOD_OPENRESTY_TESTS=1 NGINX_MOD_TEST_LOAD_ORDER=(
www-nginx/ngx-lua-module www-nginx/ngx-eval
www-nginx/{my-cool-module,my-another-module} )

NGINX_MOD_OVERRIDE_TEST_BDEPEND (SET BEFORE INHERIT)

Set to a non-empty value prior to inheriting the eclass so that the modules listed in NGINX_MOD_TEST_LOAD_ORDER are not automatically added to BDEPEND. Has no effect if either NGINX_MOD_OPENRESTY_TESTS or NGINX_MOD_TEST_LOAD_ORDER are not set.

AUTHORS

Zurab Kvachadze <zurabid2016@gmail.com>

MAINTAINERS

Zurab Kvachadze <zurabid2016@gmail.com>

REPORTING BUGS

Please report bugs via https://bugs.gentoo.org/

FILES

nginx-module.eclass

This document was created by man2html, using the manual pages.
Time: 03:27:00 GMT, July 07, 2025