debian/modules/nginx-development-kit/README

    Nginx Development Kit (NDK)
    ===========================

Synopsis

    The NDK is an Nginx module that is designed to extend the core functionality of the 
    excellent 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 have
    generic code as part of the core distribution.  The NDK itself adds few features
    that are seen from a user's point of view - it's just designed to help reduce the
    code that Nginx module developers need to write.

    Nginx module developers wishing to use any of the features in the NDK should specify 
    that the NDK is a dependency of their module, and that users will need to compile
    it as well when they compile their own modules.  They will also need to declare in
    their 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 project
    will be the 'usage for users' section below.


Status

    The NDK is now considered to be stable. It is already being used in quite a few third
    party modules.


Features

    - 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)



Design

    modular :

    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.

    auto-generated & easily extensible :

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


Usage for users

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

    1 - download the source (http://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/src

        e.g.

        ./configure --add-module=/path/to/ndk/base  --add-module=/path/to/another/mod


Usage for developers

    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 multiple
        times 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 being
        displayed when compiling Nginx.


    Warning : using NDK_ALL

        You can also set NDK_ALL to include all the NDK modules.  This is primarily as
        a convenience in the early stages of development of another module. However,

        DO NOT LEAVE 'NDK_ALL' IN YOUR CONFIG FILE WHEN PUBLISHING

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


Todo

    - 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


License

    BSD


Contributing / Feedback

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

    
Author

    Marcus Clyne (contact at simpl dot it)