New Config Shell File

雨点打透心脏的1/2处 2022-05-24 06:25 167阅读 0赞

With NGINX 1.9.11 onwards the way `config` shell file should be written has changed. It is still compatible with the [old method][] but the new method should be used if the module is intended to be a dynamic module.

The new format works when compiling a module as either a static or dynamic module. The config file is in Bourne shell format which is the same as the old method.

An example of the new format is as follows:

ngx_module_type=HTTP
    ngx_module_name=ngx_http_my_module
    ngx_module_srcs="$ngx_addon_dir/ngx_http_my_module.c"
    
    . auto/module
    
    ngx_addon_name=$ngx_module_name

You do not need to set empty variables for things that are not required as these will be cleared for each module by the build system.

Note

the `. auto/module` line is required to trigger the new module build system.

If the module is to be used with previous versions of NGINX it is possible to have a config file support bothe the old and new methods. See the [Converting Static Modules to Dynamic Modules][] guide for an example of this.

## Compiling ##

With the new configure system a module can be added to the configure line with `--add-module=/path/to/module` for static compilation and `--add-dynamic-module=/path/to/module` for dynamic compilation.

## Options ##

`ngx_module_type`

The type of module to build. Possible options are `HTTP`, `CORE`, `HTTP_FILTER`, `HTTP_INIT_FILTER`, `HTTP_AUX_FILTER`, `MAIL`, `STREAM` or `MISC`

`ngx_module_name`

The name of the module. This is used in the build system for compiling a dynamic module. Multiple whitespace separated values are possible here for multiple modules in a single set of source files, the first name in this list will be used for the name of the output binary for a dynamic module. See the complex example in [Converting Static Modules to Dynamic Modules][]. The names used in this should be the same names as the [`moduledefinition struct`][moduledefinition struct].

`ngx_module_incs`

Include paths required to build the module.

`ngx_module_deps`

A list of `.h` files which are part of the module which are required to build it.

`ngx_module_srcs`

A whitespace separated list of source files used to compile the module. The `$ngx_addon_dir` variable can be used as a placeholder for the path of the module source.

`ngx_module_libs`

A list of libraries to link with the module. For example libpthread would be linked using `ngx_module_libs=-lpthread`. The following macros can be used to link against the same libraries as NGINX: `LIBXSLT`, `LIBGD`, `GEOIP`, `PCRE`, `OPENSSL`, `MD5`, `SHA1`, `ZLIB` and `PERL`.

`ngx_addon_name`

Supplies the name of the module in the console output text of the `configure` script.

`ngx_module_link`

This is set by the build system to `DYNAMIC` for a dynamic module or `ADDON` for a static module. It is not used often but can be useful if something different needs to happen for different compile modes. The value of this variable can be tested using a standard `if` as used in a shell script.

`ngx_module_order`

Set the load order for the module which is useful for `HTTP_FILTER` and `HTTP_AUX_FILTER` module types.

The order is stored in a reverse list. The `ngx_http_copy_filter_module` is near the bottom of the list so is one of the first to be executed. This reads the data for other filters. Near the top of the list is `ngx_http_write_filter_module` which writes the data out and is one of the last to be executed.

The format for this option is typically the current module’s name followed by a whitespace separated list of modules to insert before, and therefore execute after. The module will be inserted before the last module in the list that is found to be currently loaded.

By default for filter modules this is set to `"$ngx_module_name ngx_http_copy_filter"` which will insert the module before the copy filter in the list and therefore will execute after the copy filter. For other module types the default is empty.

[old method]: https://www.nginx.com/resources/wiki/extending/old_config/
[Converting Static Modules to Dynamic Modules]: https://www.nginx.com/resources/wiki/extending/converting/
[moduledefinition struct]: https://www.nginx.com/resources/wiki/extending/api/main/#c.ngx_module_t