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/ directories (where 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 ---------------------- 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.