PKG-SNF-CS-NIX/SNF_CS_Developer_Package/DEVELOPER_NOTES

       Developer notes for the SNFServer developer distribution

                           27 January 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 binary
packages.

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).

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. binary/SNFServer), and which extra files are to be part of the
  distribution (e.g. BUGS, README, etc).

  3) Makefile.am in each directory: binary/SNFServer,
  binary/SNFClient, binary/SNF2Check, binary/SNFServerConfig, 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.

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
binary/SNFServer/Makefile.am:

  1) SNFServer_SOURCES for the cpp files for SNFServer.

In the top-level Makefile.am:

  1) noinst_HEADERS for the header files for SNFServer.  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 SNFServer application or
tarball.

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

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

  1) autoreconf --install

Issue the following commands for building (the ./configure command
needs options; see the INSTALL file or run './configure --help' for
more info):

  1) ./configure --enable-os-type=Ubuntu --sysconfdir=/etc
  --prefix=/usr

  2) make

The "./configure" command configures the system for installation into
the default directory.  The default directory '/usr/local', but can be
specified to be '/var/spool/snfilter' by adding the following line in
configure.ac:

  AC_PREFIX_DEFAULT([/var/spool/snfilter])

This can be overridden when running configure:

  ./configure --prefix=installation_directory

where installation_directory is the directory to install the software.

Other commands:

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

    AC_INIT(snf-server, X.Y.Z)

  "make install" installs the software (currently copies SNFServer to
  the bin subdirectory of the installation directory.  I expect it
  will be modified to install other files (configuration files,
  scripts, etc).

  "make uninstall" removes the software from the installation
  directory.

  "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.

  "make dist" creates a tarball for the user.  The name is
  snf-server-X.Y.Z.tar.gz, and the files are extracted into the
  directory snf-server-X.Y.Z.

  "make distcheck" tests a user tarball.  This command extracts,
  configures, builds, and installs in temporary directories.  After
  verifying that each operation was successful, the command removes
  the temporary directories.

  "make maintainer-clean" removes many of the files that can be
  created.  After running this, you would need to run ./configure.

Note: The script 'cleanForDist' cleans the developer distribution.  It
removes any 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)

Build-time configuration parameters
-----------------------------------

The configure script accepts the following command-line parameters in
addition to the standard parameters;

    --enable-os-type=TYPE

  where TYPE specifies the operating system for which SNFServer is to
  be configured.

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

The build system generates sample configuration files and scripts that
take into account where the SNFServer distribution is installed.  For
example, if the distribution is built as follows:

  ./configure --prefix=/home/temp --enable-os-type=OpenBSD

then the sample rulebase download script getRulebase.sample would
download the rulebase to /home/temp/share/snf-server.  The other files
(SNFServer.xml.sample, and SNFServer) would also be generated to take
the specified prefix into account.