PKG-SNF4CGP-NIX/SNF4CGP_Developer_Package/DEVELOPER_NOTES

       Developer notes for the SNF4CGP developer distribution

			   27 October 2009

Scope
-----

This file contains information for software developers.  Ths
information includes the prerequisite software for building, a
description of the build system, and procedures for creating the CGP
module tarball.

Software prerequisites
----------------------

The build system uses GNU software development system.  The following
software is needed for building:

  1) automake

  2) autoconf

  3) libtool

  4) make

  5) g++

  6) tar

  7) curl

  8) pthread development.

These tools are normally available on a Linux system that is
configured as a software development system.  The Linux system
installation process usually gives the user a choice of installing a
workstation, server, or software development system.  However, not all
Linux distributions give these choices.

If these tools are not installed, they may be installed (or upgraded)
at any time.  The commands vary from distribution to distribution.
For Ubuntu, the apt-get command can be used:

  1) 'apt-get install automake'.

  2) 'apt-get install autoconf'.

  3) 'apt-get install libtool'.

  4) 'apt-get install make'.

  5) 'apt-get install g++'.

  6) 'apt-get install tar'.

  7) 'apt-get install curl'.

  8) 'apt-get install libc6-dev' (to install the pthread library).

For creating packages, additional tools are needed.  These are listed
in each section for developing packages below.

Structure of the build system
-----------------------------

The following files comprise the build system:

  1) configure.ac.  This is the main configuration file.  It specifies
  the distribution name, version, which libraries are needed, etc.

  2) Makefile.am.  This is used to create the top-level Makefile.  It
  lists which directories are part of the build system
  (e.g. SNFMilter), and which extra files are to be part of the
  distribution (e.g. BUGS, README, etc).

  3) Makefile.am in each directory: SNFMilter, SNFClient, SNF2Check,
  CodeDweller, SNFMulti, Scripts, Tests, and config_files.  These are
  used to create the Makefile files for building, configuring and
  installing the software.  These Makefile.am files contain lists
  which source files are to be used for building, and directions to
  generate the configuration files.

In addition, the distribution includes the source files and
configuration files for each of the applications.

During the build process, the files in SNFMulti and CodeDweller are
compiled into a static library.  The applications SNF4CGP, SNFClient,
and SNF2Check link with these libraries.  These libraries are not
installed.  The system checks the dates of the files, and recompiles
and relinks as necessary.

To add an additional source file , edit the appropriate Makefile.am.
Add the source file to the appropriate variable.  For example, in
SNFMilter/Makefile.am:

  1) SNFMilter_SOURCES for the cpp files for SNFMilter.

  2) noinst_HEADERS for the header files for SNFMilter.  These are
  part of the user tarball, but aren't installed into the user system.

Note that files that are not listed will not be included in the
distribution tarball.  This allows you to have additional files in
directories (used, for example, for other projects) without
unnecessarily increasing the size of the SNFMilter application or
tarball.

NOTE: If files are added or removed from the build system, the package
configuration files must also be modified.  Please see the section on
building packages below for instructions.

Using the build system
----------------------

Issue the following command to prepare system newly checked out for
building:

  1) autoreconf --install

On some OSes, running this results in warning messages:

  1) libtoolize: Consider adding `AC_CONFIG_MACRO_DIR([m4])' to
  configure.ac

  2) libtoolize: Consider adding `-I m4' to ACLOCAL_AMFLAGS in
  Makefile.am.

  3) `CXXFLAGS' is a user variable, you should not override it.

  4) shell uname -s: non-POSIX variable name

These can be safely ignored.

Issue the following commands for creating a CommuniGate Pro module
tarball (please see the Doc/default.html file for how to install the
module):

  1) './configure'

  2) 'make'

  You can pass flags to the compiler with the following command:

     make OTHER_CXXFLAGS=flags

  where 'flags' contains the flags.  For example, to enable all warnings:

     make OTHER_CXXFLAGS='-Wall'

  See the compiler documentation for other options.

  You can alter any other variable make uses.  For example, to build a
  static executable, specify LDFLAGS as follows:

     make LDFLAGS="-all-static"

  See the documentation make and libtool for other options.

  3) 'make module' (as root).  This creates a tarball named
  SNF4CGP-$(VERSION)-MODULE.tar.gz that contains the binary
  CommuniGate Pro module.

Please note that the "make install" is not needed.  If you accidently
run "make install", you can run "make uninstall" to remove the files
that were installed by "make install".

Other commands:

  "make dist" creates a tarball of the form snf-milter-X.Y.Z.tar.gz.
  X, Y, and Z, as well as SNFMilter, are specified by the following
  line in configure.ac:

    AC_INIT(snf4cgp, X.Y.Z)

  "make clean", "make distclean", "make maintainer-clean" remove files
  that can be recreated.  After running "make clean", you'd need to
  run "make" to rebuild the system.  After running "make distclean" or
  "make maintainer-clean", you'd need to run ./configure to build the
  system.

Note: The script 'cleanForDist' cleans the developer distribution.  It
removes any packages and user tarballs that might have been created,
files created by 'autoreconf --install', and files ending in "~".
After running this command, the directory tree can be imported into a
version control system, or tarred and gzipped.

Changing the version number or package name
-------------------------------------------

To change the version number or package name, do the following:

  1) Update configure.ac:

     a) Change the version number and/or package name for the build
     system.  Do this by modifying the argument to the AC_INIT line in
     configure.ac.  For example, to change the package name to FOO and
     the version to 8.0.2, modify the line to be:

       AC_INIT(FOO, 8.0.2)

Changing the contents of the Doc directory in the module tarball
----------------------------------------------------------------

The contents of the Doc directory of the module tarball are specified
in the Makefile.am file in the top-level directory.  Edit the lines
after the line beginning with "EXTRA_DIST =" to change which files are
stored in the Doc directory.

Changing the CGP module tarball name or content
-----------------------------------------------

The CGP module tarball is created by commands in Makefile.am.  Look
for a line beginning with "module:".  The following line defines the
name of the module tarball:

  MOD_TARBALL=SNF4CGP-$(VERSION)-$(shell uname -s).tar.gz

The following line defines the name of the module directory:

  MOD_DIR=SNF4CGP

The commands after the line beginning with "module:" create the module
tarball.  Modify those commands to alter the content of the module
tarball.

The Doc/default.html file might need to be updated to reflect any
changes.

Generation of sample configuration files and scripts
----------------------------------------------------

The build system generates sample configuration files and scripts that
take into account where the SNF4CGP distribution is installed.  These
sample configuration files are part of the module tarball, and are
installed.  The Doc/default.html file contains user instructions for
creating the configuration files from the sample configuration files.

Debugging
---------

Enable debugging by having the path of the executable contain "debug"
or "Debug".  This causes debugging messages to be written to the
SNF4GCP log file.