nginx-module.eclass

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. Additionally, NGINX_MOD_INSTALL_CONF_STUB may be set to automatically generate load_module .conf stubs for 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_link_lib() function.

If the package genuinely depends on first-party NGINX module(s), the helper ngx_mod_gen_nginx_dep() might be used to generate the suitable dependency string for depending on first-party modules. For more advanced setups, ngx_force_module() and ngx_usex_module() might be of interest.

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_compile() 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
}

EAPI porting notes:

• 8 -> 9: * NGINX_MOD_S is removed completely. Eclass die's if its set. * NGINX_MOD_INSTALL_CONF_STUB is enabled unconditionally.

Supported EAPIs

8 9

Exported Phases

• pkg_postinst

• src_compile

• src_test

• src_install

• src_prepare

• src_configure

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.

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.

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
}

ngx_mod_link_lib <pkgconfig module name>

Adds the necessary CFLAGS and LDFLAGS to link the NGINX module with the library specified by its <pkgconfig module name>. The {C,LD}FLAGS are obtained using pkgconfig. The caller must ensure that pkgconfig has been added to BDEPEND.

ngx_gen_dep <module name> [<module name>...]

Generates dependency string on the specified first-party NGINX module(s) in the proper format and prints it to stdout. Each specified module may optionally terminate with a 4-style use dependency default state. If the 4-style default state is not specified, '(-)' is inserted by default.

The dependencies on the respective subsystems are added automatically. For example, the following invocation:

ngx_gen_dep http_rewrite

generates something like

www-servers/nginx:*[http(-),nginx_modules_http_rewrite(-)]

Example:

# If the SSL functionality is enabled, we require either the stream_ssl or
# http_ssl module to be enabled in NGINX. If http_ssl is not available, we
# assume the respective functionality is on.
RDEPEND="
    ssl? (
        || (
            $(ngx_gen_dep 'http_ssl(+)' stream_ssl)
        )
    )
"

ngx_force_module [-t] <module> [<module>...]

Enable or disable the specified first-party NGINX module(s). To disable a module, prefix it with a bang: '!'. If the same module is supplied multiple times, the later module overrides the previous ones.

If the '-t' option is specified, the not found module is not treated as an error and is instead ignored. If '-t' is not specified, if the module is not found, the build is aborted with die. The option might be useful for newer or older modules, that might not be present in all NGINX versions.

Example:

# Force enable the http_ssl module.
ngx_force_module http_ssl

# Force disable the stream_ssl module
ngx_force_module !stream_ssl

# The following call overrides the first call, forcing http_ssl off.
ngx_force_module !http_ssl

# Do not die if http_foo_bar is not found, but do try to force enable it if
# present.
ngx_force_module -t http_foo_bar

ngx_usex_module [-n] [-t] <use flag> <module> [<module>...]

Disables or enables the specified first-party NGINX module(s) based on the specified USE flag.

Let myflag be the specified USE flag. If 'use myflag' is true, passes all specified modules to ngx_force_module(). If 'use myflag' is false and '-n' has not been specified, passes the inversion of all specified modules to ngx_force_module(). For the accepted module syntax refer to ngx_force_module() description.

By default, if any of the specified modules do not exist, the build is aborted. This can be overriden by supplying '-t'. See ngx_force_module() for behaviour when this flag is supplied.

Example:

# Enable the http_fastcgi and http_uwsgi if and only if our fastcgi USE flag is
# enabled. Otherwise, disables http_fastcgi and http_uwsgi.
ngx_usex_module fastcgi http_fastcgi http_uwsgi

# Enable http_ssl and disable http_rewrite if USE=lazy is set. If USE=-lazy is
# set, this is equivalent to 'ngx_force_module !http_ssl !http_rewrite'
ngx_usex_module lazy http_ssl !http_rewrite

# The following is equivalent to
#    use !ssl && ngx_force_module  stream_pass !stream_ssl
#    use  ssl && ngx_force_module !stream_pass  stream_ssl
ngx_usex_module !ssl stream_pass !stream_ssl

# The following is equivalent to
#    use imap && ngx_force_module mail_imap mail_smtp
ngx_usex_module -n imap mail_imap mail_smtp

# The following is equivalent to
#    use !fancy && ngx_force_module -t http_gd http_autoindex
ngx_usex_module -n -t !fancy http_gd http_autoindex

nginx-module_src_prepare

Creates a fake build environment.

In the build environment initialisation part, the following symbolic links are created (to not copy files over):

• '${NGINX_S}/src' -> '/usr/include/nginx',

• '${NGINX_S}/auto' -> '/usr/src/nginx/auto',

• '${NGINX_S}/configure' -> '/usr/src/nginx/configure'.

For additional information of what resides under linked paths, see the nginx.eclass source, namely the nginx_src_install() function.

In the end, 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 restores ./configure flags, if the respective file is present. Otherwise, this function 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.

Autogenerates load_module .conf stub(s) and installs them into /etc/nginx/modules-available. Afterwards, the installed modules can be conveniently enabled or disabled by adding or removing symlinks to modules-available from /etc/nginx/modules-enabled. See nginx_src_install() in nginx.eclass for more details on how NGINX loads these stubs.

nginx-module_pkg_postinst

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

Variables

NGINX_MOD_S

This variable is deprecated in EAPI 8 and banned in EAPI 9. ${S} must be used directly instead.

Deprecated description: Holds the path to the module source directory, used in various phase functions. If unset at the time of inherit, defaults to ${S}.

NGINX_MOD_CONFIG_DIR = ""}"

Holds the path of the directory containing the config script relative to the module source directory specified by the ${S} variable. If unset at the time of inherit, defaults to "" (an empty string, meaning the config script is located at the root of the module source directory).

For example, in www-nginx/njs, S="${WORKDIR}/${P}" and NGINX_MOD_CONFIG_DIR="nginx".

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 by the nginx-module_src_compile() phase function. Its contents are undefined before the function has been called.

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

Set to directory containing tests relative to ${S} before calling nginx-module_src_test() to override the default directory where tests for this package are stored. 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 all the modules specified in this array.

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.

If NGINX_MOD_OPENRESTY_TESTS is not set, this variable has no effect.

If NGINX_MOD_OVERRIDE_TEST_BDEPEND is not set, this array must be set prior to inheriting the eclass to populate BDEPEND. In any case, this variable must ultimately be set before nginx-module_src_test() is called.

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.

NGINX_MOD_INSTALL_CONF_STUB = 1

Set to a non-empty value before calling nginx-module_src_install() to generate and install load_module .conf stub(s) for the package. See nginx-module_src_install() for details.

In EAPI 9, the functionality is enabled unconditionally, unless NGINX_MOD_DONT_INSTALL_CONF_STUB is set to a non-empty value.

NGINX_MOD_DONT_INSTALL_CONF_STUB

Set to a non-empty value before calling nginx-module_src_install() to NOT generate load_module .conf stub(s) for the package. Setting this variable also disables displaying instructions on how to enable the module in nginx-module_pkg_postinst().

Setting this might be useful for modules that are not meant to be used directly, for example ngx_devel_kit. See nginx-module_src_install() for details.

Authors

Zurab Kvachadze <zurabid2016@gmail.com>

Maintainers

Zurab Kvachadze <zurabid2016@gmail.com>

Reporting Bugs

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