README for the modules building system

** Files in the modules directory:
 
 bin/ 		binary produced by modules
 lib/ 		libraries produced by modules
 include/ 	interfaces produced by modules
 Makefile	targets: all clean doc
 modules	list of modules needed by each target
 Doxyfile	doxygen configuration file
 src/ 		the modules sources

** Modules policy:

 ** building policy

 Each module must include in the makefile $(CONFIG) that defines:

 CC, LD, AR, STRIP, RANLIB, HCC, HLD, HAR, HSTRIP, HRANLIB,
 CFLAGS, HCFLAGS, LDFLAGS, HLDFLAGS, EXEEXTENSION, STATICEXTENSION, 
 SHAREDEXTENSION, OS.

 These variables must be used as the compiler, linker, etc.
 The modules makefile is also called defining PREFIX, CONFIG and TARGET.

 A module file may contain something like:
 
 #ifdef HAVE_CONFIG_H
 #	include "config.h"
 #endif
 
 to integrate the global #define for the projects, like 
 VERSION and PROGRAMNAME and other options for compilation not concerning 
 platform but only the software itself.

 Each module's Makefile must have these targets:

 all, clean.

 The first must compile and link lib$(TARGET)$(STATICEXTENSION) and
 copy it to $(PREFIX)/lib ; then copy all the .h needed to $(PREFIX)/include.
 The other targets are trivial.

 Each module must be subscribed in modules/src/subscribed, and the 
 right Makefile.template* will be used to build it. As a special case a module
 may have an ad-hoc Makefile, but you are encouraged to use default Makefiles.
 
 Makefile.template is a generic makefile that can be personalized by 
 adding these files to the module directory:  source, interface, shared.
 The first contains the .c files that must be compiled, while the second 
 defines the .h file that should be copied to $(PREFIX)/include. The third
 contains -l flags to link the shared library. The shared library is built only
 if this file is present.

 Contrib modules should be in the vanilla module-version.tar.gz format and 
 may be patched with a patch module-version.diff present in the same directory.
 Makefile.template-contrib must be used as a Makefile to do this. See the lua 
 module for a working example.

 Special packages can use their own Makefile. This is useful in some special
 modules, but weakens the build system, so be careful.

 ** name policy

 Lua bindings packages must be called packagename_lua, as with lua-only packages
 (containing .lua modules).

 ** documentation
 
 C modules must be documented with doxygen.
 
 A .lua file must be documented in the luadoc way.
 
 Example of a commented lua file. Note that . at the end of line are important.

 <begin>
 ---
 -- description of the file, required in pkg files

 ---
 -- function brief.
 -- function long
 -- @param name type description,remember name can't be n.
 -- @return type description
 function prototype or defined value
 <end>

 A handmade binding can't be documented via the .lua, so you have to add
 a .luadoc file. This file is a lua documented file containing only the
 functions prototypes and their documentation.

** COPYING

 All modules in the modules directory are copyrighted under the GNU/GPL license,
 except the ones containing a different license specification.
 
** eof