passenger 4.0.59 → 4.0.60

data/packaging/debian/debian_specs/nginx/modules/nginx-development-kit/README

@@ -0,0 +1,139 @@
+    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)
+
+
+

data/packaging/debian/debian_specs/nginx/modules/nginx-development-kit/README_AUTO_LIB

@@ -0,0 +1,395 @@
+Nginx Auto Lib Core
+===================
+
+Nginx Auto Lib Core is a generic external library-handler that has been designed to
+facilitate the inclusion of external libraries in modules for the Nginx web server.
+It has been written both for the benefit of Nginx module developers and for the end
+users of those Nginx modules, and can provide a consistent, intelligent, flexible
+cross-platform way to include external libraries.
+
+Any developers of Nginx modules are encouraged to use Auto Lib Core to handle library
+dependencies for their modules rather than writing their own custom handler from scratch.
+
+Note : the latest version can be found at github.com/simpl/ngx_auto_lib
+
+
+Information for end users
+=========================
+
+To include external libraries using Auto Lib to you may need or wish to export some
+variables before you run configure. e.g.
+
+$ export MOZJS=/path/to/mozjs
+$ export MOZJS_SHARED=NO
+$ ./configure ...
+
+In all cases below [PFX] should be replaced with the name of the library (e.g. MOZJS). The
+specific value for [PFX] should be mentioned in the README file for the module that
+uses Auto Lib Core.
+
+
+Search order for paths
+----------------------
+
+(1) [PFX]_INC and [PFX]_LIB
+(2) [PFX] (source or install dir)
+(3) any dirs under [PFX]_BASE (see below)
+(4) any dirs under the parent directory of the Nginx source dir beginning with '[pfx]-'
+(5) standard system paths (including /usr/local, /usr, /opt/local, /opt, /usr/pkg)
+
+If any of 1-3 are specified, then any set values will be searched, and the the Nginx
+source's parent directory and system paths are not searched unless [PFX]_SEARCH_[PLACE]
+variable is set to YES, where PLACE ::= PARENT | SYSTEM. e.g.
+
+$ export OPENSSL_LIB=/path/to/openssl/lib
+$ export OPENSSL_INC=/path/to/openssl/inc
+$ ./configure
+
+will search only in the lib and include paths specified, and
+
+$ export OPENSSL_LIB=/path/to/openssl/lib
+$ export OPENSSL_INC=/path/to/openssl/inc
+$ export OPENSSL_BASE=/path/to/openssl/base
+$ export OPENSSL_SEARCH_PARENT=YES
+$ ./configure --with-openssl=/path/to/openssl
+
+will search first in the lib & inc dirs specified, then in /path/to/openssl, then will
+look for directories in /path/to/openssl/base and then in the Nginx source parent
+directory, but will skip checking the system paths.
+
+Note : apart from system paths, all dirs are checked as both source and install directories,
+so static versions of installed OpenSSL, PCRE, Zlib etc libraries can be used with Nginx
+if desired.
+
+
+Specifying a path to find a library
+-----------------------------------
+
+If the version of a library you wish to include is in any of the standard paths (e.g.
+/usr/local, /usr ...), you will not need to specify a path to include the library.
+
+If you do wish to specify a specific path, in most cases just specifying 
+[PFX]=/path/to/library will be sufficient. e.g.
+
+$ export MOZJS=/path/to/mozjs
+$ ./configure ...
+
+The path can be either a source directory or an install directory. Auto Lib will search
+
+
+Searching under base paths
+--------------------------
+
+Rather than specifying a specific path to find new libraries in non-standard locations,
+you may wish to specify a base path (or just let Auto Lib search the directory that the
+Nginx source is located in). This will then automatically find the most recent versions
+of libraries and check them before older versions.
+
+e.g.
+
+You have installations
+
+/openssl/version/0.9.8m
+/openssl/version/1.0.0a
+...
+
+$ export OPENSSL_BASE=/openssl/version
+$ ./configure ...
+
+Any directories under /openssl/version will be searched IN REVERSE ORDER, i.e. most recent
+version first. Here /openssl/version/1.0.0a would be searched before /openssl/version/0.9.8m.
+
+If [PFX]_BASE_SEARCH_PREFIX=YES, then only directories beginning with '[pfx]-' are searched.
+If [PFX]_BASE_SEARCH_PREFIX=something, then only directories beginning with 'something' are
+searched.
+
+When searching under [PFX]_BASE no prefix is added to the search, but when searching under
+the directory that the Nginx source is located in, the prefix [pfx]- is automatically added.
+
+Note : there is currently a minor bug (due to the implementation of the 'sort' command) 
+means versions that include hyphens (e.g. 1.0.0-beta5) are checked before versions like 
+1.0.0a. This will be fixed soon, and searching of -build folders before normal source ones
+will be added too.
+
+
+
+Shared or static?
+-----------------
+
+The default for most libraries is to look for shared libraries, though this can be overridden
+by the user by setting [PFX]_SHARED=NO.
+
+In the near future the default action will be to look for shared libraries then to look 
+for static libraries in each directory searched unless one of [PFX]_SHARED and/or
+[PFX]_STATIC = NO. If both are set to NO, then Auto Lib will not be used at all.
+
+
+
+Variables that users can set to help find libraries
+---------------------------------------------------
+
+[PFX]                   Location of dir where the library can be found      (PATH, see below)
+[PFX]_INC               Include dir for library headers                     (PATH)
+[PFX]_LIB               Lib dir for library archive/shared objects          (PATH)
+[PFX]_BASE              Base dir under which to search for other dirs       (PATH)
+[PFX]_SEARCH_LIB_INC    Search in [PFX]_INC and [PFX]_LIB if set            (YES|NO, def=YES)
+[PFX]_SEARCH_DIR        Search [PFX] if set                                 (YES|NO, def=YES)
+[PFX]_SEARCH_BASE       Search under [PFX]_BASE if set                      (YES|NO, def=YES)
+[PFX]_SEARCH_PARENT     Search under the dir that the Nginx source is in    (YES|NO, see above)
+[PFX]_SEARCH_SYSTEM     Search in standard system paths                     (YES|NO, see above)
+[PFX]_SHARED            Use shared library rather than static               (YES|NO, def=YES)
+[PFX]_SYSTEM_DIRS       System dirs to search in (PATHS, space-separated, overrides the defaults)
+USE_[PFX]               Whether or not to install the library               (YES|NO, def=YES)
+
+
+Note : for libraries that have configure options (e.g. --with-openssl=/path), the [PFX]
+variable is set automatically by configure, so will not be used if exported.
+
+
+
+Information for module developers
+=================================
+
+How Auto Lib Core works
+-----------------------
+
+Auto Lib Core works as an interface layer between the module and the auto/feature part of
+the Nginx source. This is the file that results in the 'checking for ...' lines that you 
+see when you call ./configure.
+
+auto/feature works by using a few key variables (see below) to generate some C code, trying
+to compile it to see if it works and optionally running the code. This output file is called
+autotest.c (located under the objs/ directory whilst configure is running, but is deleted
+after each call to auto/feature).
+
+Normally, whenever an external library is required, a module developer will write a number 
+of calls to auto/feature manually in their config files - e.g. to check under a range of 
+different possible locations to find a library. Apart from being tedious, this is obviously
+potentially error-prone.
+
+Auto Lib Core will automatically generate all the calls to auto/feature for you, and will
+take into account different operating systems etc in a consistent way, 'intelligent' way.
+
+
+Including Nginx Auto Lib Core with custom modules
+-------------------------------------------------
+
+Option 1 :
+
+- include ngx_auto_lib_core in the same directory that your module config file is
+  located
+- add the following line to your config file
+
+  . $ngx_addon_dir/ngx_auto_lib_core 
+
+NOTE : if you want to include the file in a different directory to your config
+file, you will need to change both the include line in your config file AND
+the line in the ngx_auto_lib_core file that points to the file (it's the line that
+has $ngx_addon_dir/ngx_auto_lib_core in it)
+
+Option 2 :
+
+- make the Nginx Development Kit (github.com/simpl-it/ngx_devel_kit) a dependency 
+  for your module (Auto Lib Core is included automatically with it)
+
+
+Recommended way of including Auto Lib Core
+------------------------------------------
+
+If the Nginx Development Kit (NDK) is already a dependency for your module, then you do
+not need to do anything - just follow the 'using Auto Lib Core' instructions below.
+
+If the NDK is not a dependency for your module, then it is recommended to include a
+copy of ngx_auto_lib_core with your module, but to recommend to users of your module
+to include the NDK when compiling. If the module is not required for anything else, this
+will not make any difference to the Nginx binary that they compile, but will mean they
+will get the latest version of Auto Lib Core (which probably won't change much anyway,
+but you never know).
+
+You will also probably want to include a copy of this readme file for Auto Lib Core
+(at least the user section), and mention what the relevant [PFX] you use for your module
+is in your module's readme file so that users will know what to write for any variables
+that they might use to control the search paths for libraries (see above user section).
+
+
+Using Auto Lib Core
+-------------------
+
+To use Auto Lib Core, you should do the following in your config file for each
+external library that you want to include :
+
+1 - Call ngx_auto_lib_init
+2 - Define any variables used for testing
+3 - Define any hooks (custom functions)
+4 - Call ngx_auto_lib_run
+
+
+Calling ngx_auto_lib_init() and ngx_auto_lib_run()
+--------------------------------------------------
+
+You can pass either one or two variables to ngx_auto_lib_init(). The first is the name of
+the library as it will appear when running ./configure, the second is the prefix that is
+used for internal variables and looking for directory prefixes. If the second is not 
+specified, it defaults to the first.
+
+The init function resets all key variables and functions, so it must be called before 
+setting any other variables or functions that are to be used as hooks (see the notes below).
+
+ngx_auto_lib_run() should be called in the config files after all the variables and hooks
+have been defined. This will then run through all the tests to try to find the external
+library.
+
+
+Variables you can set in your config files
+------------------------------------------
+
+All the variables that you set in Auto Lib Core are similar to the ones you set for
+including libraries in the normal way.
+
+       name                           description
+----------------------------------------------------------------------------------------
+
+core variables (i.e. the ones in the core Nginx source)
+
+ngx_feature_inc_path                CFLAGS and include path info (including -I)
+ngx_feature_incs                    Include/define code inserted before main() in autotest.c
+ngx_feature_libs                    External libraries to add (see below)
+ngx_feature_path                    Space-separated include path
+ngx_feature_run                     Whether to run the autotest binary (default = no)
+ngx_feature_test                    C-code inserted inside main() in autotest.c
+
+extended variables (only work in NALC) :
+
+ngx_feature_add_libs                Add libraries (but do not add include files)
+ngx_feature_add_path                Add extra directories to include path
+ngx_feature_build_dirs              Sub dirs that builds might be found
+ngx_feature_build_inc_dirs          Sub dirs that include files might be found
+ngx_feature_build_lib_dirs          Sub dirs that lib files might be found
+ngx_feature_check_macros_defined    Lib required only if one of these macros is defined
+ngx_feature_check_macros_non_zero   Lib required only if one of these macros is non-zero
+ngx_feature_defines                 Define these macros if the library is found
+ngx_feature_deps                    Deps to add (e.g. to CORE_DEPS) if the library is found
+ngx_feature_exit_if_not_found       Quit configure if the library is not found
+ngx_feature_haves                   Set these macros to 1 if the library is found
+ngx_feature_inc_names               Names for include files (not including the .h)
+ngx_feature_lib_files               Add these files under the lib dir for static inclusions
+ngx_feature_lib_names               Names for lib files (not including -l or .a)
+ngx_feature_modules                 Modules to add if the library is found
+ngx_feature_srcs                    Sources to add (e.g. to ADDON_SRCS) if the lib is found
+ngx_feature_shared                  If set to 'no', then only use static lib versions
+ngx_feature_test_libs               Add these libs when testing, but not to the final binary
+ngx_feature_variables               Set these variables if the library is found
+
+standard variables that are completely over-written (i.e. they won't work with NALC) :
+
+ngx_feature_name                    Message that is displayed after 'checking for' in configure
+
+
+Using these variables
+---------------------
+
+You do not need to set most of these variables, since 'intelligent' guesses are made that
+will work for most cases. With the exception of ngx_feature_test, you should generally use
+the extended variables rather than the core ones, since sensible core variables will be
+automatically generated from them, and will work for both static and shared libraries.
+
+
+Variable defaults
+-----------------
+
+ngx_feature_incs            for i in $ngx_feature_inc_names { #include <$i.h> }
+ngx_feature_libs            for l in $ngx_feature_lib_names { -l$l or $LIB/lib$l.a }
+                            + $ngx_feature_add_libs
+ngx_feature_inc_names       $ngx_feature_lib_names
+ngx_feature_lib_names       $pfx
+pfx                         str_to_lower (if two variables are passed to ngx_auto_lib_init, then
+                            then $2, otherwise, $1)
+
+The easiest way to understand how all the defaults work is probably to look at the source code
+of ngx_auto_lib_test_setup() and to look at the examples in the standard Nginx Auto Lib module
+which has code for OpenSSL, PCRE, Zlib, MD5 and SHA1.
+
+
+Hooks
+-----
+
+To facilitate using Auto Lib Core in a flexible way, a number of 'hooks' have been
+placed in the testing cycle. These hooks are implemented as functions that you define
+in your config file which are called if required by the core library. In the core 
+library they are left as empty functions that return either 0 or 1. Any functions
+you write will 
+
+Note : ngx_auto_lib_init() resets the variables and functions each time it is called, so
+you must DEFINE HOOKS AFTER YOU CALL ngx_auto_lib_init.
+
+Note : an update on what hooks are available will be added later. To see what hooks are
+available, just look in the source code of ngx_auto_lib_core for any functions that just
+return 0 or 1.
+
+See the MD5 and SHA1 libraries of Nginx Auto Lib module for examples.
+
+
+
+Checking that a library is required
+-----------------------------------
+
+Although in most cases Auto Lib Core will be used where external libraries are
+definitely required (for a module to work), this may not always be the case. In the
+standard Nginx Auto Lib module (github.com/simpl-it/ngx_auto_lib) - which is designed
+to improve the inclusion of OpenSSL, PCRE and Zlib libraries and increase compilation
+speed where possible - the libraries are not always required, so checks are made to 
+see if it is necessary.
+
+
+
+How Auto Lib Core checks if a library is required - ngx_auto_lib_check_require()
+------------------------------------------------------------------------------------
+
+- search for USE_[PFX]=YES (it is set to YES by default for most modules)
+- search for any external libraries that have been included in the CORE_LIBS or ADDON_LIBS
+  variables that use the same lib name as any set in ngx_feature_lib_names
+- search for any macros that have been defined either in the CFLAGS variable or using 
+  auto/have or auto/define as set in the ngx_feature_check_macros_defined and 
+  ngx_feature_ngx_macros_non_zero variables
+- any custom checks implemented by creating an ngx_auto_lib_check hook function (which
+  should return 0 if the library is required and return 1 at the end if the module is 
+  not required)
+
+
+
+Guaranteeing that the correct version of a shared library is linked at run time
+-------------------------------------------------------------------------------
+
+Sometimes users will want to use shared libraries that are in non-standard locations
+that the linker may have a problem in locating at run time - even if the correct
+linker path (-L/path/to/lib) is supplied when checking. To make sure that the linker
+can find the library at run time, and to make sure that the linker will use the correct
+version of a library if the library is also located in a standard directory, a run path
+is added to the linker flags (using -Wl,--rpath -Wl,/path/to/lib/dir). In most cases this
+will guarantee that the correct library is used when linking - though care should be taken
+by any users specifying specific paths for libraries that the correct version of the
+library has been linked at run time (e.g. using ldd etc).
+
+As an additional check when running auto/feature, as well as the compilation of the
+autotest.c file, a check is made by ldd to see that the path of the shared library
+that the linker links to is the same as the one specified. This is done because
+
+
+To do
+-----
+
+- change how library paths are searched to include both shared and static libraries
+- touch up documentation
+
+
+License
+-------
+
+    BSD
+
+
+Copyright
+---------
+
+    Marcus Clyne (c) 2010  (http://simpl.it)
+