Changes between Version 15 and Version 16 of user-configure


Ignore:
Timestamp:
Jun 2, 2006 12:16:23 PM (14 years ago)
Author:
andreasw
Comment:

cleaned up

Legend:

Unmodified
Added
Removed
Modified
  • user-configure

    v15 v16  
    33Here 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 [http://projects.coin-or.org/MSDevStudio MSDevStudio project page].
    44
    5 If you have problems, have a look at the [http://projects.coin-or.org/BuildTools/wiki/user-troubleshooting troubleshooting page.]
     5If you have problems, have a look at the [wiki:user-troubleshooting troubleshooting page.]
    66
    77== Running the {{{configure}}} script ==
     
    1010in the directory {{{Coin-Pkg}}}.
    1111
    12 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 shell scripts {{{configure}}} in the package's base directory (e.g., {{{Coin-Pkg}}}) and in the projects main directories (such as {{{Coin-Pkg/Pkg}}}) perform a number of tests and create the final Makefiles.  In addition, a {{{configure}}} script usually creates a header file (such as {{{Coin-Pkg/inc/config_clp.h}}}) for the individual packages, which contains {{{#define}}}s to help the source code to adapt to different platforms.
     12Before 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 {{{#define}}}s to help the source code to adapt to different platforms.
    1313
    1414To run the configuration scripts, you go into base directory of the downloaded COIN package (e.g., {{{Coin-Pkg}}}), and type
     
    2020This 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.
    2121
    22 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.
     22If 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.
    2323
    2424If 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.
    2525
    26 '''Note:'''  If you rerun {{{configure}}} after a configuration run, you should do a {{{make distclean}}} if you changed the options for {{{configure}}}, see also the {{{make}}} target description at the [wiki:user-compile Compiling and installing the package] page.
     26'''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 [wiki:user-compile Compiling and installing the package] page.
    2727
    28 == Giving Options to the {{{configure}}} script ==
     28== Giving Options to the {{{configure}}} Script ==
    2929
    30 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.
     30There 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.
    3131
    3232An alternative to providing configuration options through the command line is the {{{config.site}}} file, see below.
    3333
    34 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 sub{{{configure}}} scripts.
     34For 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 sub{{{configure}}} scripts.
    3535
    36 You can see a list of all available (documented) options by running
     36You can see a '''list of all available options''' by running
    3737
    3838{{{
     
    4242=== Command Line Arguments for {{{configure}}} ===
    4343
    44 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.
     44The 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'''.
    4545
    46  * '''{{{-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.
     46 * '''-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.
    4747
    48  * '''{{{--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}}}.
     48 * '''--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}}}.
    4949
    50  * '''{{{--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.
     50 * '''--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'''.
    5151
    52  * '''{{{--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.
     52 * '''--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.
    5353
    54  * '''{{{--disable-shared}}}''': If you want only static libraries to be compiled and no shared objects or DLLs, you should specify this option.
     54 * '''--disable-shared''': If you want '''only static libraries''' to be compiled and no shared objects or DLLs, you should specify this option.
    5555
    56  * '''{{{--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 those packages, you need to provide this option.
     56 * '''--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.
    5757
    58  * 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:
     58 * 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:
    5959
    6060    {{{--with-cplex-lib}}}="-L/usr/ilog/cplex90/lib/static_pic -lcplex"
     
    8585=== Variable Arguments for {{{configure}}} ===
    8686
    87 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").
     87Other 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").
    8888
    8989Commonly used variable arguments are
    9090
    91  * '''{{{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}}}.
     91 * '''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}}}.
    9292
    93  * '''{{{CFLAGS}}}''':  C compiler falgs.  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.
     93 * '''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.
    9494
    95  * '''{{{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.
     95 * '''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.
    9696
    97  * '''{{{CXXFLAGS}}}''':  C++ compiler falgs.  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.
     97 * '''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.
    9898
    99  * '''{{{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.
     99 * '''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.
    100100
    101  * '''{{{FFLAGS}}}''':  Fortran compiler falgs.  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.
     101 * '''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.
    102102
    103  * '''{{{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"}}}).
     103 * '''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"}}}).
    104104
    105  * '''{{{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"}}}).
     105 * '''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"}}}).
    106106
    107  * '''{{{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"}}}).
     107 * '''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"}}}).
    108108
    109109A complete invokation of the configure script could look like:
     
    116116== Specifying Options in a {{{config.site}}} File ==
    117117
    118 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.
     118Setting 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.
    119119
    120 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.
     120The 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.
    121121
    122 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}}}.
     122The {{{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}}}.
    123123
    124 An example {{{config.site}}} file can be found in the {{{BuildTools/config.site}}} directory.
     124''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!''
     125
     126An '''example config.site file''' can be found in the {{{BuildTools}}} directory.
    125127
    126128== Performing a VPATH Compilation ==
    127129
    128 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).
     130If 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).
    129131
    130132To 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