Initial revision of DEVELOPER_NOTES.

git-svn-id: https://svn.microneil.com/svn/PKG-SNF4CGP-NIX/trunk@7 7ef522f6-be79-40a8-b7df-0a85b3383509

SNF4CGP_Developer_Package/DEVELOPER_NOTES

@@ -0,0 +1,224 @@
+       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'
+
+  3) 'make module' (as root).
+
+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 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)-$(shell uname -s).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 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.