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.

DEVELOPER_NOTES 8.3KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251
  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: SNFMilter, SNFClient, SNF2Check,
  49. CodeDweller, SNFMulti, Scripts, Tests, and config_files. These are
  50. used to create the Makefile files for building, configuring and
  51. installing the software. These Makefile.am files contain lists
  52. which source files are to be used for building, and directions to
  53. generate the configuration files.
  54. In addition, the distribution includes the source files and
  55. configuration files for each of the applications.
  56. During the build process, the files in SNFMulti and CodeDweller are
  57. compiled into a static library. The applications SNF4CGP, SNFClient,
  58. and SNF2Check link with these libraries. These libraries are not
  59. installed. The system checks the dates of the files, and recompiles
  60. and relinks as necessary.
  61. To add an additional source file , edit the appropriate Makefile.am.
  62. Add the source file to the appropriate variable. For example, in
  63. SNFMilter/Makefile.am:
  64. 1) SNFMilter_SOURCES for the cpp files for SNFMilter.
  65. 2) noinst_HEADERS for the header files for SNFMilter. These are
  66. part of the user tarball, but aren't installed into the user system.
  67. Note that files that are not listed will not be included in the
  68. distribution tarball. This allows you to have additional files in
  69. directories (used, for example, for other projects) without
  70. unnecessarily increasing the size of the SNFMilter application or
  71. tarball.
  72. NOTE: If files are added or removed from the build system, the package
  73. configuration files must also be modified. Please see the section on
  74. building packages below for instructions.
  75. Using the build system
  76. ----------------------
  77. Issue the following command to prepare system newly checked out for
  78. building:
  79. 1) autoreconf --install
  80. On some OSes, running this results in warning messages:
  81. 1) libtoolize: Consider adding `AC_CONFIG_MACRO_DIR([m4])' to
  82. configure.ac
  83. 2) libtoolize: Consider adding `-I m4' to ACLOCAL_AMFLAGS in
  84. Makefile.am.
  85. 3) `CXXFLAGS' is a user variable, you should not override it.
  86. These can be safely ignored.
  87. Issue the following commands for creating a CommuniGate Pro module
  88. tarball (please see the Doc/default.html created during the build
  89. process from Doc/default.html.in) file for how to install the module):
  90. 1) './configure'
  91. 2) 'make'
  92. This command compiles and builds the software, including the
  93. configuration files and documentation. The input documentation and
  94. configuration files have a suffix of "in". For example, the
  95. default.html file is created from default.html.in. Make any changes
  96. to default.html.in, since the new default.html file is created by
  97. the build system would overwrite any existing default.html file.
  98. You can pass flags to the compiler with the following command:
  99. make OTHER_CXXFLAGS=flags
  100. where 'flags' contains the flags. For example, to enable all warnings:
  101. make OTHER_CXXFLAGS='-Wall'
  102. See the compiler documentation for other options.
  103. You can alter any other variable make uses. For example, to build a
  104. static executable, specify LDFLAGS as follows:
  105. make LDFLAGS="-all-static"
  106. See the documentation make and libtool for other options.
  107. 3) 'make module' (as root). This creates a tarball named
  108. CGPSNF-$(VERSION)-MODULE.tar.gz that contains the binary CommuniGate
  109. Pro module. The executable SNF4CGP/SNF4CGP is renamed to CGPSNF in
  110. this tarball.
  111. Please note that the "make install" is not needed. If you accidently
  112. run "make install", you can run "make uninstall" to remove the files
  113. that were installed by "make install".
  114. Other commands:
  115. "make dist" creates a tarball of the form snf-milter-X.Y.Z.tar.gz.
  116. X, Y, and Z, as well as SNFMilter, are specified by the following
  117. line in configure.ac:
  118. AC_INIT(snf4cgp, X.Y.Z)
  119. "make clean", "make distclean", "make maintainer-clean" remove files
  120. that can be recreated. After running "make clean", you'd need to
  121. run "make" to rebuild the system. After running "make distclean" or
  122. "make maintainer-clean", you'd need to run ./configure to build the
  123. system.
  124. Note: The script 'cleanForDist' cleans the developer distribution. It
  125. removes any packages and user tarballs that might have been created,
  126. files created by 'autoreconf --install', and files ending in "~".
  127. After running this command, the directory tree can be imported into a
  128. version control system, or tarred and gzipped.
  129. Changing the version number or package name
  130. -------------------------------------------
  131. To change the version number or package name, do the following:
  132. 1) Update configure.ac:
  133. a) Change the version number and/or package name for the build
  134. system. Do this by modifying the argument to the AC_INIT line in
  135. configure.ac. For example, to change the package name to FOO and
  136. the version to 8.0.2, modify the line to be:
  137. AC_INIT(FOO, 8.0.2)
  138. Changing the contents of the Doc directory in the module tarball
  139. ----------------------------------------------------------------
  140. The contents of the Doc directory of the module tarball are specified
  141. in the Makefile.am file in the top-level directory. Edit the lines
  142. after the line beginning with "EXTRA_DIST =" to change which files are
  143. stored in the Doc directory.
  144. Changing the CGP module tarball name or content
  145. -----------------------------------------------
  146. The CGP module tarball is created by commands in Makefile.am. Look
  147. for a line beginning with "module:". The following line defines the
  148. name of the module tarball:
  149. MOD_TARBALL=CGPSNF-$(VERSION)-MODULE.tar.gz
  150. The following line defines the name of the module directory:
  151. MOD_DIR=CGPSNF
  152. The commands after the line beginning with "module:" create the module
  153. tarball. Modify those commands to alter the content of the module
  154. tarball.
  155. The Doc/default.html.in file might need to be updated to reflect any
  156. changes.
  157. Generation of sample configuration files and scripts
  158. ----------------------------------------------------
  159. The build system generates sample configuration files, scripts and
  160. documentationthat take into account where the SNF4CGP distribution is
  161. installed, as well as the SNF4CGP version. These sample configuration
  162. and documentation files are part of the module tarball, and are
  163. installed. The Doc/default.html file, created from
  164. Doc/default.html.in, contains user instructions for creating the
  165. configuration files from the sample configuration files.
  166. Debugging
  167. ---------
  168. Enable debugging by having the path of the executable contain "debug"
  169. or "Debug". This causes debugging messages to be written to the
  170. SNF4GCP log file.