You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259
  1. Developer notes for the SNF4CGP developer distribution
  2. 27 October 2009
  3. Scope
  4. -----
  5. This file contains information for software developers. Ths
  6. information includes the prerequisite software for building, a
  7. description of the build system, and procedures for creating the CGP
  8. module tarball.
  9. Software prerequisites
  10. ----------------------
  11. The build system uses GNU software development system. The following
  12. software is needed for building:
  13. 1) automake
  14. 2) autoconf
  15. 3) libtool
  16. 4) make
  17. 5) g++
  18. 6) tar
  19. 7) curl
  20. 8) pthread development.
  21. These tools are normally available on a Linux system that is
  22. configured as a software development system. The Linux system
  23. installation process usually gives the user a choice of installing a
  24. workstation, server, or software development system. However, not all
  25. Linux distributions give these choices.
  26. If these tools are not installed, they may be installed (or upgraded)
  27. at any time. The commands vary from distribution to distribution.
  28. For Ubuntu, the apt-get command can be used:
  29. 1) 'apt-get install automake'.
  30. 2) 'apt-get install autoconf'.
  31. 3) 'apt-get install libtool'.
  32. 4) 'apt-get install make'.
  33. 5) 'apt-get install g++'.
  34. 6) 'apt-get install tar'.
  35. 7) 'apt-get install curl'.
  36. 8) 'apt-get install libc6-dev' (to install the pthread library).
  37. For creating packages, additional tools are needed. These are listed
  38. in each section for developing packages below.
  39. Structure of the build system
  40. -----------------------------
  41. The following files comprise the build system:
  42. 1) configure.ac. This is the main configuration file. It specifies
  43. the distribution name, version, which libraries are needed, etc.
  44. 2) Makefile.am. This is used to create the top-level Makefile. It
  45. lists which directories are part of the build system
  46. (e.g. SNFMilter), and which extra files are to be part of the
  47. distribution (e.g. BUGS, README, etc).
  48. 3) Makefile.am in each directory: binary/SNF4CGP, binary/SNFClient,
  49. binary/SNF2Check, Scripts, Doc, and config_files. These are used to
  50. create the Makefile files for building, configuring and installing
  51. the software. These Makefile.am files contain lists which source
  52. files are to be used for building, and directions to generate the
  53. configuration files.
  54. During the build process, the binary/<AppName> directories (where
  55. <AppName> is the name of the executable) are populated with the object
  56. files and executable. The system checks the dates of the files, and
  57. recompiles and relinks as necessary.
  58. To add an additional source file , edit the appropriate Makefile.am.
  59. Add the source file to the appropriate variable. For example, in
  60. SNF4CGP/Makefile.am:
  61. 1) SNF4CGP_SOURCES for the cpp files for SNF4CGP.
  62. In the top-level Makefile.am:
  63. 1) noinst_HEADERS for the header files for SNF4CGP. These are part
  64. of the user tarball, but aren't installed into the user system.
  65. Note that files that are not listed will not be included in the
  66. distribution tarball. This allows you to have additional files in
  67. directories (used, for example, for other projects) without
  68. unnecessarily increasing the size of the SNFMilter application or
  69. tarball.
  70. NOTE: If files are added or removed from the build system, the package
  71. configuration files must also be modified. Please see the section on
  72. building packages below for instructions.
  73. Using the build system
  74. ----------------------
  75. Do the following to prepare system newly checked out for building:
  76. 1) Copy configure.ac.in to configure.ac.
  77. 2) Edit configure.ac, replacing REPLACE_WITH_VERSION with the
  78. SNFMilter version. The contents of ../Version.txt contains the
  79. SNFMilter version.
  80. 3) Run "autoreconf --install".
  81. Issue the following command to prepare system newly checked out for
  82. building:
  83. 1) autoreconf --install
  84. On some OSes, running this results in warning messages:
  85. 1) libtoolize: Consider adding `AC_CONFIG_MACRO_DIR([m4])' to
  86. configure.ac
  87. 2) libtoolize: Consider adding `-I m4' to ACLOCAL_AMFLAGS in
  88. Makefile.am.
  89. 3) `CXXFLAGS' is a user variable, you should not override it.
  90. These can be safely ignored.
  91. Issue the following commands for creating a CommuniGate Pro module
  92. tarball (please see the Doc/default.html created during the build
  93. process from Doc/default.html.in) file for how to install the module):
  94. 1) './configure'
  95. 2) 'make'
  96. This command compiles and builds the software, including the
  97. configuration files and documentation. The input documentation and
  98. configuration files have a suffix of "in". For example, the
  99. default.html file is created from default.html.in. Make any changes
  100. to default.html.in, since the new default.html file is created by
  101. the build system would overwrite any existing default.html file.
  102. You can pass flags to the compiler with the following command:
  103. make OTHER_CXXFLAGS=flags
  104. where 'flags' contains the flags. For example, to enable all warnings:
  105. make OTHER_CXXFLAGS='-Wall'
  106. See the compiler documentation for other options.
  107. You can alter any other variable make uses. For example, to build a
  108. static executable, specify LDFLAGS as follows:
  109. make LDFLAGS="-all-static"
  110. See the documentation make and libtool for other options.
  111. 3) 'make module' (as root). This creates a tarball named
  112. CGPSNF-$(VERSION)-MODULE.tar.gz that contains the binary CommuniGate
  113. Pro module. The executable SNF4CGP/SNF4CGP is renamed to CGPSNF in
  114. this tarball.
  115. Please note that the "make install" is not needed. If you accidently
  116. run "make install", you can run "make uninstall" to remove the files
  117. that were installed by "make install".
  118. Other commands:
  119. "make dist" creates a tarball of the form snf-milter-X.Y.Z.tar.gz.
  120. X, Y, and Z, as well as SNFMilter, are specified by the following
  121. line in configure.ac:
  122. AC_INIT(snf4cgp, X.Y.Z)
  123. "make clean", "make distclean", "make maintainer-clean" remove files
  124. that can be recreated. After running "make clean", you'd need to
  125. run "make" to rebuild the system. After running "make distclean" or
  126. "make maintainer-clean", you'd need to run ./configure to build the
  127. system.
  128. Note: The script 'cleanForDist' cleans the developer distribution. It
  129. removes any packages and user tarballs that might have been created,
  130. files created by 'autoreconf --install', and files ending in "~".
  131. After running this command, the directory tree can be imported into a
  132. version control system, or tarred and gzipped.
  133. Changing the version number or package name
  134. -------------------------------------------
  135. To change the version number or package name, do the following:
  136. 1) Update configure.ac:
  137. a) Change the version number and/or package name for the build
  138. system. Do this by modifying the argument to the AC_INIT line in
  139. configure.ac. For example, to change the package name to FOO and
  140. the version to 8.0.2, modify the line to be:
  141. AC_INIT(FOO, 8.0.2)
  142. Changing the contents of the Doc directory in the module tarball
  143. ----------------------------------------------------------------
  144. The contents of the Doc directory of the module tarball are specified
  145. in the Makefile.am file in the top-level directory. Edit the lines
  146. after the line beginning with "EXTRA_DIST =" to change which files are
  147. stored in the Doc directory.
  148. Changing the CGP module tarball name or content
  149. -----------------------------------------------
  150. The CGP module tarball is created by commands in Makefile.am. Look
  151. for a line beginning with "module:". The following line defines the
  152. name of the module tarball:
  153. MOD_TARBALL=CGPSNF-$(VERSION)-MODULE.tar.gz
  154. The following line defines the name of the module directory:
  155. MOD_DIR=CGPSNF
  156. The commands after the line beginning with "module:" create the module
  157. tarball. Modify those commands to alter the content of the module
  158. tarball.
  159. The Doc/default.html.in file might need to be updated to reflect any
  160. changes.
  161. Generation of sample configuration files and scripts
  162. ----------------------------------------------------
  163. The build system generates sample configuration files, scripts and
  164. documentationthat take into account where the SNF4CGP distribution is
  165. installed, as well as the SNF4CGP version. These sample configuration
  166. and documentation files are part of the module tarball, and are
  167. installed. The Doc/default.html file, created from
  168. Doc/default.html.in, contains user instructions for creating the
  169. configuration files from the sample configuration files.
  170. Debugging
  171. ---------
  172. Enable debugging by having the path of the executable contain "debug"
  173. or "Debug". This causes debugging messages to be written to the
  174. SNF4GCP log file.