wiki:user-configure

Version 16 (modified by andreasw, 14 years ago) (diff)

cleaned up

Preparing the Compilation

Here we only describe the configuration procedure on UNIX-like systems (including Linux, Cygwin, and MSys), where the user can run the configure shell script. If you are using the MS Developer Studio, you are referred to the MSDevStudio project page.

If you have problems, have a look at the troubleshooting page.

Running the configure script

Assume that you have dowloaded the package Pkg in the directory Coin-Pkg.

Before you can compile the source code using make, the Makefiles have to be created, so that they contain the correct compiler names and options, as well as other system dependent information. To this purpose, the configure shell scripts in the package's base directory (e.g., Coin-Clp) and in the projects' main directories (such as Coin-Clp/Clp) perform a number of tests and create the final Makefiles. In addition, a configure script usually creates a header file (such as Coin-Clp/Clp/inc/config_clp.h) for the individual project, which contains #defines to help the source code to adapt to different platforms.

To run the configuration scripts, you go into base directory of the downloaded COIN package (e.g., Coin-Pkg), and type

./configure

This picks default settings for compilers and compiler options. You can change some aspects of the configuration by providing arguments to the configuration script, as described below.

If the configuration is successful, the configure script usually prints a message indicating this. If the configuration fails, the output on the screen, or the more detailed output in the config.log in the same directory might help to find the cause. If you look at the config.log file, you should go to the bottom of this file and page up, until you see the error message; at the end of the file configure still outputs the results of the tests, even in case of failure.

If you are not able to fix the problem and want to contact the maintainers, you should submit a bug ticket at the corresponding Trac page and attach the config.log file.

Note: If you rerun configure after a successful configuration run, you should do a make distclean if you changed the options for configure; see also the make target description at the Compiling and installing the package page.

Giving Options to the configure Script

There are two types of arguments that can be given to the configure script. The first set of arguments have the form of regular command line options, such as --enable-debug or -C. The second set of options works through variables, and those can be provided either on the command line, or can be set as environment variables.

An alternative to providing configuration options through the command line is the config.site file, see below.

For most COIN packages, several configuration scripts are run recursively. You need to specify the options for all subprojects (e.g., Clp and CoinUtils) when you run the base configure script, since they are given to the subconfigure scripts.

You can see a list of all available options by running

./configure --help=recursive

Command Line Arguments for configure

The command line arguments are given to configure simply as additional arguments for to the command line. Some common arguments are described here, but there might be additional options that you can find on the home pages for the individual COIN projects.

  • -C: Makes configure use a cache file to speed up the tests when they been performed earlier. If you rerun configure with different options (so that the results of tests might change), you should delete the config.cache file before the rerun.
  • --prefix: By default, the binaries and header files are installed (by make install) into bin, lib, and include directories of where the main configuration scripts was run. If you prefer to have make install install in a different location (such as $HOME), you need to use this option, e.g., with --prefix=$HOME.
  • --enable-debug: This causes configure to select the debug compiler options. It also defines the preprocessor macro COIN_DEBUG, which in some source code is use to activate additional (time-consuming) consistency tests.
  • --enable-static: By default, the COIN libraries are compiled as shared libraries or DLLs, at least on platforms that support this. If you want to also have static libraries to be generated as well, you need to specify this option.
  • --disable-shared: If you want only static libraries to be compiled and no shared objects or DLLs, you should specify this option.
  • --with-gnu-packages: Some of the COIN projects can make use of GNU packages (such as zlib, bzlib, or readline). Since those are usually provided under the GPL license, which has rather strong conditions, the configuration scripts do not check for the availability of those packages by default. If you want to compile the COIN code so that it uses GNU packages, you need to provide this option.
  • Further options of the form --enable-... and with-... might be understood by the configuration scripts for specific COIN projects. For example, if you want to tell the Open Solver Interface (OSI) that you want to compile the Cplex solver interface, you need to specify the --with-cplex-lib and --with-cplex-incdir options with the appropriate values. (If such a value consists of more than one word, you need to enclose it in quotation marks.) For example:

--with-cplex-lib="-L/usr/ilog/cplex90/lib/static_pic -lcplex"

assuming that the cplex library (usually named libcplex.a)

is located in /usr/ilog/cplex90/lib/static_pic. Note that, on some systems, the threading library must be added for cplex to work. In this case, the string is:

--with-cplex-lib="-L/usr/ilog/cplex90/lib/static_pic -lcplex -lpthread"

For the include string:

--with-cplex-incdir=/usr/ilog/cplex90/include/ilcplex

assuming that the header file cplex.h is located in the directory

/usr/ilog/cplex90/include/ilcplex.

A typical call for the configuration script would then look like

./configure --with-cplex-lib=="-L/usr/ilog/cplex90/lib/static_pic -lcplex" \
            --with-cplex-incdir= usr/ilog/cplex90/include/ilcplex \
            --enable-static -C

Variable Arguments for configure

Other options, usually related to compilation configuration (such as compiler names and options) can be set as variables. The values for those variables can be either provided as environment variables (e.g., set in your shell startup script), or on the command line. Values set on the command line overwrite values set in the environment. If you want to set the value of a variable (such as CXX) in the comamnd line for configure, you simply list the variable, followed immediately by an = and the value, possibly enclosed in quotation marks (such as CXX="cl").

Commonly used variable arguments are

  • CC: Name of the C compiler. If this is not given, the configure script tries a list of compiler names. You only need to specify this if you are not happy with the default selection. If you want to compile the code in a non-default bit mode (say, 64bit on AIX), you should specify the corresponding flag here (e.g., CC='xlc -q64'), and not in CFLAGS.
  • CFLAGS: C compiler flags. If this is not given, the configure script chooses a default set of compiler flags, depending on the compiler, operating system, and whether the --enable-debug flag is given.
  • CXX: Name of the C++ compiler. If this is not given, the configure script tries a list of compiler names. You only need to specify this if you are not happy with the default selection. If you want to compile the code in a non-default bit mode (say, 64bit on AIX), you should specify the corresponding flag here (e.g., CXX='xlC -q64'), and not in CXXFLAGS. This only applies to packages that require the C++ compiler.
  • CXXFLAGS: C++ compiler flags. If this is not given, the configure script chooses a default set of compiler flags, depending on the compiler, operating system, and whether the --enable-debug flag is given. This only applies to packages that require the C++ compiler.
  • F77: Name of the Fortran compiler. If this is not given, the configure script tries a list of compiler names. You only need to specify this if you are not happy with the default selection. If you want to compile the code in a non-default bit mode (say, 64bit on AIX), you should specify the corresponding flag here (e.g., F77='xlf -q64'), and not in FFLAGS. This only applies to packages that require the Fortran compiler.
  • FFLAGS: Fortran compiler flags. If this is not given, the configure script chooses a default set of compiler flags, depending on the compiler, operating system, and whether the --enable-debug flag is given. This only applies to packages that require the Fortran compiler.
  • ADDDEFS: If you want to have the C and C++ compile use additional -D preprocessor macro defintions, you should list them in this variable (e.g., ADDDEFS="-DPARANOIA").
  • AR: Program for handling archives. The default selection usually works fine. Only on some systems (such as AIX), it is necessary to specify additional flags when compiling in 64bit mode (e.g., AR="ar -X64").
  • NM: Program for listing symbols in object files. The default selection usually works fine. Only on some systems (such as AIX), it is necessary to specify additional flags when compiling in 64bit mode (e.g., NM="nm -X64").

A complete invokation of the configure script could look like:

./configure CXX="xlC -q64" CC="xlc -q64" F77="xlf -q64" AR="ar -X64" \
            NM="nm -X64" --enable-gnu-packages -C

Specifying Options in a config.site File

Setting all configuration arguments in the command line for configure can be somewhat inconvenient. You can alternatively specify your choices in a file that is automatically read when configure is run.

The name of this file is config.site. The configure script looks for it in the share subdirectory of the installation directory (i.e., what you speficy with the --prefix argument, or by default in the share subdirectory of where you run configure). You can specify a different location and name by setting the environment variable CONFIG_SITE to the full path to your config.site file, including the file name itself.

The config.site file is a shell script (for bin/sh) and needs to follow the shell's syntax. It is used to set values of shell variables that are internally used by the configure script. In case of variable arguments (such as CC), the name that should be used in config.site is identical to the name that could be specified in the command line. For --enable-...-type arguments, the corresponding config.site shell variable is enable_... with the dashes replaced by underscore; to specify that the features is to be used, set this variable to yes, and to disable it, set it to no. For --with-...-type arguments use the variable name with_..., again with dashes replaced by underscores, and set it to the chosen value. If no value is required, set it to yes, and to mimic a --without... option, set the corresponding with_... variable to no.

Note: Since the config.site file is a shell script, you must not have any whitespace before and after the "=" symbol in a variable assignment''

An example config.site file can be found in the BuildTools directory.

Performing a VPATH Compilation

If you follow the above instructions, the compiled files will be in the same directories as the source files. It is possible to compile the code in a different place than where the source code is (using the make VPATH feature). This can, for example, be handy, if you want to have several compiled versions around (e.g., for different operating systems when you are working on a shared files system, or a production and debug version).

To do a VPATH compilation, you simply run the configure script in the directory where you want to have the compiled files. E.g., if the base directory of the COIN packages is in $HOME/Coin-Pkg and you want to compile the code in $HOME/Obj/debug/Coin-Pkg, you go into the latter directory and type

$HOME/Coin-Pkg/configure --enable-debug -C

(Of course, you use those options for configure that you want to use, not necessarily the above ones.) After you run configure, you will find the same directory structure under $HOME/Obj/debug/Coin-Pkg as in $HOME/Coin-Pkg (at least those directories that have source code in $HOME/Coin-Pkg), together with the Makefiles. To compile the code, you how enter the make commands in $HOME/Obj/debug/Coin-Pkg. Note, that if you install the code and didn't specify a specific installation location with the --prefix flag, the installed files will go into bin, lib, and include subdirectories of $HOME/Obj/debug/Coin-Pkg.

Note: A VPATH compilation is not possible, if you ran configure already in the source code directory ($HOME/Coin-Pkg in the example above). You would need to do a make distclean in the source code directory first.