Repository files navigation

Nginx Development Kit (NDK)

• Name
• Synopsis
• Status
• Features
• Design
  • modular
  • auto-generated & easily extensible
• Usage for users
  • Building as a dynamic module
• Usage for developers
  • Warning: using NDK_ALL
• Modules using NDK
• TODO
• License
• Contributing / Feedback
• Authors
• Special Thanks

The NDK is an Nginx module that is designed to extend the core functionality of theexcellent Nginx webserver in a way that can be used as a basis of other Nginx modules.

It has functions and macros to deal with generic tasks that don't currently havegeneric code as part of the core distribution. The NDK itself adds few featuresthat are seen from a user's point of view - it's just designed to help reduce thecode that Nginx module developers need to write.

Nginx module developers wishing to use any of the features in the NDK should specifythat the NDK is a dependency of their module, and that users will need to compileit as well when they compile their own modules. They will also need to declare intheir own modules which features of the NDK they wish to use (explained below).

If you are not an Nginx module developer, then the only useful part of this projectwill be the 'usage for users' section below.

Back to TOC

The NDK is now considered to be stable. It is already being used in quite a few thirdparty modules (see list below).

Back to TOC

• additional conf_set functions for regexes, complex/script values, paths...
• macros to simplify tasks like checking for NULL values when doing ngx_array_push
• patches to the main source code
• ngx_auto_lib_core generic external library handler is included (see separate readme)

Back to TOC

The kit itself is designed in a modular way, so that only the required code is compiled.It's possible to add just a single NDK module, a few or all of them.

Back to TOC

Many of the macros available in the NDK are auto-generated from simple configurationfiles. This makes creating similar macros for your own code very simple - it's usuallyjust the case of adding an extra line to a config file and re-running the build script.

Back to TOC

If another Nginx module you wish to use specifies that the NDK is a dependency, youwill need to do the following :

1. download the source (https://github.com/simpl/ngx_devel_kit)
2. unpack the source (tar -xzf $name)
3. compile Nginx with the following extra option--add-module=/path/to/ngx_devel_kit.

e.g.

./configure --add-module=/path/to/ngx_devel_kit \            --add-module=/path/to/another/module

Back to TOC

Starting from NGINX 1.9.11, you can also compile this module as a dynamic module, by using the--add-dynamic-module=PATH option instead of--add-module=PATH on the./configure command line above. And then you can explicitly load the module in yournginx.conf via theload_moduledirective, for example,

load_module /path/to/modules/ndk_http_module.so;load_module /path/to/another/module.so;

Back to TOC

To use the NDK in your own module, you need to add the following:

1. add this line to your module

#include<ndk.h>

Note: since the NDK includes the following lines

#include<ngx_config.h>#include<ngx_core.h>#include<ngx_http.h>

you can replace these with the single include above.2. add the following line in the config file for your module:

have=NDK_[module_name]. auto/have

for each NDK module that you wish to use (you need to include auto/have multipletimes if you wish to use multiple NDK modules.

Note: the old method of setting

CFLAGS="$CFLAGS -DNDK_[module_name]"

is now deprecated. It will still work, but results in unnecessary lines beingdisplayed when compiling Nginx.

Back to TOC

You can also setNDK_ALL to include all the NDK modules. This is primarily asa convenience in the early stages of development of another module. However,

DO NOT LEAVENDK_ALL IN YOUR CONFIG FILE WHEN PUBLISHING

Although the NDK is fairly small now, it could in time become a large repositoryof code that would, if using NDK_ALL, result in considerably more code being compiledthan is necessary.

Back to TOC

The following 3rd-party modules make use of NDK.

• ngx_http_lua_module
• ngx_http_set_misc_module
• ngx_http_encrypted_session_module
• ngx_http_form_input_module
• ngx_http_iconv_module
• ngx_http_array_var_module

If you would like to add your module to this list, please let us know.

Back to TOC

• documentation for modules that don't already have it
• additional phase-handler functions
• generically testing for needing to add a handler
• remove dependency of set_var on OpenSSL being compiled in
• for backward compatability, add the ndk_macros

Back to TOC

Copyright (c) 2010-2018, Marcus Clyne

All rights reserved.

Redistribution and use in source and binary forms, with or without modification, arepermitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list ofconditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list ofconditions and the following disclaimer in the documentation and/or other materialsprovided with the distribution.
3. Neither the name of the copyright holder nor the names of its contributors may be usedto endorse or promote products derived from this software without specific priorwritten permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESSOR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OFMERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THECOPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTEGOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSEDAND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDINGNEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IFADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Back to TOC

If you are an Nginx module developer, and have developed some functions that aregeneric in nature (or would be easily adapted to be so), then please send them tome at the address below, and I'll addmclyne to the kit.

Back to TOC

Marcus Clyne

Back to TOC

A special thanks goes toYichun Zhang for helping to maintainthis module.

Back to TOC