Changes between Version 1 and Version 2 of pm-project-config

Timestamp:

May 31, 2006 8:06:27 PM (15 years ago)

Author:

andreasw

Comment:

started first draft

pm-project-config

@@ -3 +3 @@
 The purpose of the configuration script in a project's main directory ({{{Clp}}} and {{{CoinUtils}}} in the [wiki:user-directories example]) is to test everything required for the compilation of the project's source code, and to set up all Makefiles.
 
-The beginning and the end of the file follow the [wiki:pm-structure-config basic structure] of {{{configure.ac}}} files.  The body for a project main directory {{{configure.ac}}} file then looks like this:
+The beginning and the end of the file follow the [wiki:pm-structure-config basic structure] of {{{configure.ac}}} files.  The body for a project main directory {{{configure.ac}}} contains the following parts:
+
+ * Initialization of tools and checks for programs, such as compiler
+ * Checks for other COIN components
+ * Checks for third party libraries (such as GNU's zlib or a third party LP solver)
+ * Generation of links to files required for unit tests or example programs in case of a VPATH configuration
+ * Other project specific tests and settings (such as byte size of types, existence of header files etc)
+
+In the following we describe the indiviual parts of the {{{configure.ac}} file body in more details and present examples.
+
+== Initialization of Tools and Compilers ==
+
+This part usually looks like this:
 
 {{{
+#############################################################################
+#                         Standard build tool stuff                         #
+#############################################################################
 
+# Get the system type
+AC_CANONICAL_BUILD
+
+# If this project depends on external projects, the Externals file in
+# the source root directory contains definition of where to find those
+# externals.  The following macro ensures that those externals are
+# retrieved by svn if they are not there yet.
+AC_COIN_PROJECTDIR_INIT
+
+# Check if user wants to produce debugging code
+AC_COIN_DEBUG_COMPILE
+
+# Get the name of the C compiler and appropriate compiler options
+AC_COIN_PROG_CC
+
+# Get the name of the C++ compiler and appropriate compiler options
+AC_COIN_PROG_CXX
+
+# Initialize automake and libtool
+AC_COIN_INIT_AUTO_TOOLS
 }}}
+
+ * The '''AC_CANONICAL_BUILD''' makes the {{{configure}}} script check the host type, on which the script is run.
+
+ * '''AC_COIN_PROJECTDIR_INIT''' is a COIN specific macro that inializes a few things and should be included at this place
+
+ * The macro '''AC_COIN_DEBUG_COMPILE''' makes the {{{--enable-debug}}} flag available for {{{configure}}}.  It also sets the Automake conditional accordingly, as well as the {{{COIN_DEBUG}}} for the configuration header file.
+
+ * The macros '''AC_COIN_PROG_CC''' and '''AC_COIN_PROG_CXX''' determine the name of the C and C++ compiler, and chooses the default compiler options.  One only needs to specify those compilers that are required to compile the source code in the project. If the source code contains Fortran files, one should use '''AC_COIN_PROG_F77'''.
+
+ * Finally, the '''AC_COIN_INIT_AUTO_TOOLS''' sets everything up that is required to have Automake and Libtool work correctly.
+
+== Check for Other COIN Components ==
+
+This part looks like this:
+
+{{{
+#############################################################################
+#                              COIN components                              #
+#############################################################################
+
+AC_COIN_HAS_PROJECT(Cbc)
+AC_COIN_HAS_PROJECT(Cgl)
+AC_COIN_HAS_PROJECT(Clp)
+AC_COIN_HAS_PROJECT(CoinUtils)
+AC_COIN_HAS_PROJECT(DyLP)
+AC_COIN_HAS_PROJECT(Osi)
+AC_COIN_HAS_PROJECT(Sym)
+AC_COIN_HAS_PROJECT(Vol)
+}}}
+
+Here, for each COIN project that is required to compile the libraries and programs in this project (including unit tests and example programs), we list its name as argument of one '''AC_COIN_HAS_PROJECT'''.  This example is taken from Cbc, and as you see, the project itself should also be listed.
+
+The final {{{configure}}} script will search for the project; first, it will check if itself is this package (by comparing with the name that is given to {{{AC_INIT}}} at the beginning of the {{{configure.ac}}} file), and otherwise looks for a parallel subdirectory with the projects name.
+
+If the project is found, a {{{#define}}} will set in the configuration header files with the name {{{COIN_HAS_PRJCT}}} (where {{{PRJCT}}} is replaced by the name of the project in all capital letters, e.g., {{{COIN_HAS_CLP}}} in the example above).  Also, an Automake conditional with the same name will be set to true.
+
+The project can be listed in any order.
+
+== Checks For Third-Party Components ==
+
+For a few third-party packages we have defined special COIN macros, namely for those packages that are released under the GNU Public License (GLP).  Those libraries will only be used, if the user specified the {{{--enable-gnu-packages}}} flag for {{{configure}}}.  So far, those macros are
+
+ * '''AC_COIN_CHECK_GNU_ZLIB''': Check for the zlib compression library
+ * '''AC_COIN_CHECK_GNU_BZLIB''': Check for the bzlib compression library
+ * '''AC_COIN_CHECK_GNU_READLINE''': Check for the readline library.
+
+Those macros check for the availability of those packages (if required by the user).  If the package is available, it adds the flags required for linking to the {{{ADDLIBS}}} output variable, {{{#define}}}s the preprocessor {{{COIN_HAS_ZLIB}}} (and similar) in the configuration header file, and defines an Automake conditional with the same name.
+
+We also provide a generic macro for testing the availability of other third-party libraries, called '''AC_COIN_HAS_USER_LIBRARY'''.
+A typical invocation looks like this:
+
+{{{
+AC_COIN_HAS_USER_LIBRARY([Cplex],[CPX],[cplex.h],[CPXgetstat])
+}}}
+
+The arguments have to following meaning:
+
+ 1. ''Name of the package''.