

Developers are encouraged to read this file if they want
to make changes or add modules to the Inuktitut package. 
They should also read the INSTALL file if they are not familiar
with configure scripts. 

=======================================================
SOURCE TREE & BUILD PROCESS
=======================================================
The package structure has the following features:
	* there is one configure.ac at the top level. autoconf >= 2.52 is recommended 
	  event though older versions may work (ln -s configure.ac configure.in
	  is required for older versions like 2.13.) but there is no guaranty
	* there is one configure header (config/inuk_conf.h) generated by autoheader
	  from the file acconfig.h which should be included by modules that use
	  configurable defines. 
	* as we use automake, there is one Makefile.am in 
	  each directory defining what is to be built, installed, added 
	  to the distribution, ...
	* there is one Makefile.in for each Makefile.am which is 
	  automatically generated by automake and included in the cvs base
	* there are generic rules in config/ which are included by Makefiles.am
    * by default configure does not cache results (see INSTALL), so to speed up 
      the configuration process, use -C in the configure command line.
    * Even though it is not recommanded, we use bash scripting in the configuration
      process. If the basic install shell sh is not bash, try configuring using
      CONFIG_SHELL=/path/to/bash /path/to/bash ./configure ...
	* the OPT flag can be used to add optional flags to the compilation
	* you can (and are encouraged to) configure and build in a separate directory:
	  this is cleaner and give the possibility to build different configurations
	  from the same source tree
	* the build process is as follows:
        _ the headers of each configured module are exported to /include
		- the src dir of each configured module is made: the lib is built, 
		  the objects are exported to resp. include and lib/objs
		  exported objects are prefixed with the name of the module to prevent
                  from name conflicts
		- the lib directory is built: the inuk library is built from objects 
		  that have been previously exported
		- the Tumit directory is built if some traces have been requested
		- the bin, tests, and examples directories are built which 
          consist in doing make in the bin (resp. tests, doc) directories of each 
          configured modules
        - the documentation is built is asked for
	* when debugging a module, it is somewhat annoying to do make in module/src 
      then make in lib and return in the test or bin  directory. 
      The two targets modlib  and install-modlib have been created for this 
	  purpose (install-modlib also install the lib inuk in the install directory). 
	  They can be run everywhere in the module tree. 
	* Makefiles, Makefiles.in, configure are automatically rebuilt when needed. 
	  However it is sometimes annoying under CVS because the dates of the updated 
	  files does not necessarly correspond to the dates when committed. If you do 
      not want this to happen, run the tools/noautoconf.sh and 
      tools/noautomake.sh scripts after an update. However, this requires that
	  Makefiles.in are up to date according to Makefiles.am in the cvs base, 
	  that is automake should be run before committing Makefiles.am and 
      Makefiles.in must also be committed. 
	* different versions of aclocal may pose problem. If so, rerun aclocal before
      configuring
        * You can use the following flags at configure and compile flags 
        (see ./configure --help):
        CXX         C++ compiler command
        CXXFLAGS    C++ compiler flags
        LDFLAGS     linker flags, e.g. -L<lib dir> if you have libraries in a
                    nonstandard directory <lib dir>
        CPPFLAGS    C/C++ preprocessor flags, e.g. -I<include dir> if you have
                    headers in a nonstandard directory <include dir>
        CC          C compiler command
        CFLAGS      C compiler flags
        CXXCPP      C++ preprocessor

        * The used flags are in order :
                - the ones given on the make command line,
                - if none, the ones given on configure command line
                - if none, the default ones

      default ones: CXXFLAGS="-O3 -funroll-loops -D_REENTRANT"
                    CPPFLAGS="-I<build_dir>/include"
      LIBS is also internally used in configure to tell how to link with the 
      inuk lib and will not be scratched by LDFLAGS
      Note that all you can do is redefine these flags. To extend some you need
      to recall the default ones to make or configure. 
      Note also that if you want to remove the default flags at configure time
      you'll need to give xxFLAGS=" " with a white space

=======================================================
ADDING A MODULE
=======================================================
To add a module, say MyMod, you need to do the followings:
	* copy the the template directory: NewModTemplate
	  to a new directory ginving it the name of your module, that is MyMod:
		cp -r NewModTemplate MyMod
	* add source files in MyMod/src, tests in MyMod/tests, binaries in
	  MyMod/bin, and doc files in MyMod/doc
	* adjust the different Makefiles.am to what you need and the MyMod/AUTHORS file
	* in configure.ac:
		- copy the "template for new modules" section just before it
		- remove the unecessary comments,
		- replace any MyMod with the name of your module (the name of the directoy)
		  and mymod with the name of your module in small letters
		- add a line in AC_OUTPUT with list of files to be configured, that is
		  at least all the makefiles 
        * use the variable compile_MyMod_CPPFLAGS to add flags to compile the 
          module library and variable compile_MyMod_LIBS to add additional 
          libraries (see COR_net as example)
	* you can define new m4 macros if you need in acinclude.m4 and then run aclocal
	* if you want to use traces, please read the documentation and get inspired of 
	  what is done for the Psocket module

=======================================================
MAKING A DISTRIBUTION
=======================================================
Automake generates target to help the building of a distribution, that is
a .tgz which should contain all what is needed to configure and rebuild the 
inuktitut libraries and executables. Applications need not to be included but 
can be included as examples, provinding they are sufficiently comprehensive for 
users.

'make dist' at the top level builds the .tgz at the top level of the build directory. It includes all the files needed to configure the package (configure, configure.ac, Makefiles.am, and Makefiles.in, etc.), sources and headers required to build the libs and binaries, the files needed to build the documentation, the files needed to build the tests.

Most of the files are automatically includes by automake. However some may be missing and must be explitly included using the variable EXTRA_DIST. 

By default the variable uses the SUBDIRS variable to know which directories to look in when building the distibution. This may pose a problem for directories that are conditianally built according to how the package has been configured. For this reason we sometimes use instead the DISTDIRS variable which is used in place of SUBDIRS if it exists.

Automake also generates the distcheck target which is aimed at verifying that a distribution is correct. It builds the .tgz, uncompresses it in a directory, configures and builds it in a separate one. DISTCHECK_CONFIGURE_FLAGS is defined in top level Makefile.am to tell arguments to pass to configure when doing 'make distcheck'. To function this requires the ebvironement varible CORBADIR do be defined to the path to a valid corba installation.

=======================================================
RPM
=======================================================
There is a spec file for building rpms for Mandrake. You can either "rpmize" 
the usual way (see Mandrake howto at http://www.linux-mandrake.com/en/howtos/mdk-rpm/mdk-rpm.html) or type 'make rpm' in the top level directory.

Remark: 
- the process is rather long, so make sure the code compile before doing that
- you will need to create RPM directories and files like explained at http://www.linux-mandrake.com/en/howtos/mdk-rpm/mdk-rpm.html before doing 'make rpm'


=======================================================
TESTING
=======================================================
Automake generates a ckeck target (type 'make check') which execute tests listed in 
TEST variable of Makefiles.am. Some tests in NetworkCore/tests will do tests with different possible configurations. They can be controlled using the following environment variables:
* INUK_PRIMARY_NETS: use $INUK_PRIMARY_NETS networks to launch tests [default is all configuired primary nets]
* INUK_TEST_NETS: test only $INUK_TEST_NETS networks [default is all configuired secondary nets]
* INUK_MIN_NODES: test from INUK_MIN_NODES nodes [default is 2]
* INUK_MAX_NODES: test with up to INUK_MAX_NODES nodes [default is 4]
* INUK_TIMEOUT: delay before a test is considered dead [default 60 seconds]
* INUK_REPEAT: number of times each test is repeated

=======================================================
AUTOTOOLS URLS
=======================================================
You can find the docs for autoconf & automake at the following URLs:
http://www.gnu.org/manual/autoconf/index.html
http://www.gnu.org/manual/automake/index.html



