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: binary/SNF4CGP, binary/SNFClient,
  binary/SNF2Check, Scripts, Doc, 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.

During the build process, the binary/<AppName> directories (where
<AppName> is the name of the executable) are populated with the object
files and executable.  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
SNF4CGP/Makefile.am:

  1) SNF4CGP_SOURCES for the cpp files for SNF4CGP.

In the top-level Makefile.am:

  1) noinst_HEADERS for the header files for SNF4CGP.  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
----------------------

Do the following to prepare system newly checked out for building:

  1) Copy configure.ac.in to configure.ac.

  2) Edit configure.ac, replacing REPLACE_WITH_VERSION with the
     SNFMilter version.  The contents of ../Version.txt contains the
     SNFMilter version.

  3) Run "autoreconf --install".

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.

These can be safely ignored.

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

  1) './configure'

  2) 'make'

  This command compiles and builds the software, including the
  configuration files and documentation.  The input documentation and
  configuration files have a suffix of "in".  For example, the
  default.html file is created from default.html.in.  Make any changes
  to default.html.in, since the new default.html file is created by
  the build system would overwrite any existing default.html file.

  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
  CGPSNF-$(VERSION)-MODULE.tar.gz that contains the binary CommuniGate
  Pro module.  The executable SNF4CGP/SNF4CGP is renamed to CGPSNF in
  this tarball.

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=CGPSNF-$(VERSION)-MODULE.tar.gz

The following line defines the name of the module directory:

  MOD_DIR=CGPSNF

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.in file might need to be updated to reflect any
changes.

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

The build system generates sample configuration files, scripts and
documentationthat take into account where the SNF4CGP distribution is
installed, as well as the SNF4CGP version.  These sample configuration
and documentation files are part of the module tarball, and are
installed.  The Doc/default.html file, created from
Doc/default.html.in, 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.