NGINX.ECLASS

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

NAME

nginx.eclass - Provides a common set of functions for building the NGINX server

DESCRIPTION

This eclass automates building, testing and installation of the NGINX server. Essentially, apart from the advanced usage, the ebuild must only define 4 variables prior to inheriting the eclass, everything else is handled by the nginx.eclass. Refer to the individual variable descriptions for documentation. The required variables are:
- NGINX_SUBSYSTEMS
- NGINX_MODULES
- NGINX_UPDATE_STREAM
- NGINX_TESTS_COMMIT And 1 optional variable (see description):
- NGINX_MISC_FILES

SUPPORTED EAPIS

FUNCTIONS

econf_ngx [<args>...]: Call ./configure, passing the supplied arguments. The NGINX 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 'die's 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.
nginx_pkg_setup: Shows important information that a user should pay attention to.
nginx_src_unpack: Unpacks the NGINX sources. For the live version of NGINX, fetches the tip of the Git repository.
nginx_src_prepare: Patches NGINX build system files. Afterwards, calls default_src_prepare.
nginx_src_configure [<args>...]: Configures NGINX. The function initialises the default set of configure flags, coupled with the USE-conditional ones. The function also automatically disables and enables NGINX modules and subsystems listed in NGINX_MODULES and NGINX_SUBSYSTEMS respectively. Custom flags can be supplied as arguments to this function, taking precedence over eclass flags.
nginx_src_compile: Compiles NGINX, setting the correct installation directories for the Perl-related files.
nginx_src_test: Performs tests on the compiled NGINX binary, using Perl's prove.
nginx_src_install: Installs NGINX, including miscellaneous directories under '/var' and documentation. Vimfiles from 'contrib/vim' are also installed by this function. All the files specified in the NGINX_MISC_FILES array are installed in their respective directories. If 'modules' USE flag is enabled, the build system (the './configure' script and the scripts in the 'auto/' directory) is installed into '/usr/src/nginx' and NGINX headers into '/usr/include/nginx'.
nginx_pkg_postinst: Shows various warnings and informational messages to a user. Calls tmpfiles_process() to process the installed tmpfiles.

ECLASS VARIABLES

NGINX_SUBSYSTEMS (REQUIRED) (SET BEFORE INHERIT): An array of individual NGINX "servers" or, as they are called in this eclass, subsystems. An optional '+' prefix represents a default-enabled state. The variable must be an exact representation of the upstream policy, i.e. the subsystems that are enabled-by-default upstream must be prefixed with a '+' in this array and the subsystems that are disabled-by-default must not be prefixed with a '+'. Not following this rule will break NGINX build system. As of the time of writing, there are 3 subsystems: "http", "stream", and "mail". The naming is the exact representation of ./configure's '--with' and '--without' options with the mentioned parts stripped and '+' appended where relevant: '--without-http' -> '+http' (means 'http' is enabled by default), '--with-stream' -> 'stream', etc.
Example usage: NGINX_SUBSYSTEMS=( +http stream mail )
NGINX_MODULES (REQUIRED) (SET BEFORE INHERIT): An array of bundled NGINX modules names with optional '+' prefix representing a default-enabled state. The variable must be an exact representation of the upstream policy, i.e. the modules that are enabled-by-default upstream must be prefixed with a '+' in this array and the modules that are disabled-by-default must not be prefixed with a '+'. Not following this rule will break NGINX build system. The naming scheme is exactly the same as used by the ./configure script with '--with(out)' and '_module' parts stripped and the '+' prefix applied where necessary: '--with-http_v2_module' -> 'http_v2', '--without-http_autoindex_module' -> '+http_autoindex', '--without-stream_limit_conn_module' -> '+stream_limit_conn', etc.
Example usage: NGINX_MODULES=(         +http_rewrite http_ssl +http_gzip
        +stream_access
        +mail_imap
        http_{geoip,perl}
)
NGINX_UPDATE_STREAM (REQUIRED) (SET BEFORE INHERIT): This variable must contain the update stream of NGINX. The list of all possible update streams is set by the NGX_UPDATE_STREAMS_LIST variable. An ebuild must not set SLOT manually. The eclass will automatically set SLOT and add blocks on other update streams into RDEPEND variable, based on this variable. NGINX_UPDATE_STREAM might be set to a special value: 'live'. Doing this makes the eclass fetch the live (latest) version of NGINX from its Git repository. This behaviour can be further configured by setting the following variables (refer to each variable description for documentation):
- NGINX_GIT_URI
- NGINX_GIT_TESTS_URI
Example usage: NGINX_UPDATE_STREAM=mainline
NGX_UPDATE_STREAMS_LIST = ( stable mainline live ): Read-only array that contains all the possible NGINX update streams.
NGINX_TESTS_COMMIT (REQUIRED) (SET BEFORE INHERIT): This variable must contain a valid commit hash of nginx-tests[1] repository. The tests for NGINX are unversioned, therefore their snapshot is obtained from the specified commit. Only in case NGINX_UPDATE_STREAM is set to 'live', this variable might also be set exactly to 'live' in order to fetch the latest version of the nginx-tests[1] repository. [1]: https://github.com/nginx/nginx-tests/
Example usage: NGINX_TESTS_COMMIT=345f9b74cd296695b188937b9ade246033476071
NGINX_GIT_URI = https://github.com/nginx/nginx}": May be set to an alternative URI of NGINX Git repository for the live version to be fetched from. Defaults to "https://github.com/nginx/nginx".
NGINX_GIT_TESTS_URI = https://github.com/nginx/nginx-tests}": May be set to an alternative URI of NGINX tests Git repository for the live version to be fetched from. Defaults to "https://github.com/nginx/nginx-tests".
NGINX_MISC_FILES: This array holds filenames of miscellaneous files in FILESDIR. The files that are specified in this array are installed to various locations, based on their file extension. The "file extension <-> path" mappings are as follows:
'.conf'      -> '/etc/nginx'
'.service'   ->  systemd unit directory
'.initd'     -> '/etc/init.d'
'.confd'     -> '/etc/conf.d'
'.logrotate' -> '/etc/logrotate.d'
'.tmpfiles'  -> '/usr/lib/tmpfiles.d' This variable exists to avoid (1) hardcoding specific versions of the files that may change due to revisions (the revisions happen rather frequently in case of NGINX), (2) repeating the code which installs the files in every ebuild, and (3) requiring these miscellaneous files to exist at all.
Example usage: NGINX_MISC_FILES=(
nginx-r5.initd nginx-r4.conf nginx-r1.confd nginx-{r2.logrotate,r2.service} )
OVERRIDE_NGINX_MOD_REQUIRED_USE (SET BEFORE INHERIT): Set this to a non-empty value prior to inheriting the eclass to NOT automatically fill the REQUIRED_USE variable with inter-module dependencies. For details, see _ngx_set_mod_required_use() function description below.
OVERRIDE_NGINX_MOD_DEPEND (SET BEFORE INHERIT): Set this to a non-empty value prior to inheriting the eclass to NOT automatically fill the BDEPEND, DEPEND, and RDEPEND variables with module dependencies. For details, see _ngx_set_mod_depend() function description below.
OVERRIDE_NGINX_MOD_TEST_DEPEND (SET BEFORE INHERIT): Set this to a non-empty value prior to inheriting the eclass to NOT automatically fill the BDEPEND variable with module test dependencies. For details, see _ngx_set_mod_test_depend() function description below.
NGX_TESTS_S = "${WORKDIR}/nginx-tests-${NGINX_TESTS_COMMIT}" (GENERATED BY ECLASS): Variable set to the work directory of the NGINX tests.

AUTHORS

Zurab Kvachadze <zurabid2016@gmail.com>

MAINTAINERS

Zurab Kvachadze <zurabid2016@gmail.com>

REPORTING BUGS

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

FILES

nginx.eclass

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