INSTALL
changeset 1184 3c00344f49c9
parent 1040 60c0c3ed8d11
parent 1064 fc3854d936f7
     1.1 --- a/INSTALL	Mon Jul 16 16:21:40 2018 +0200
     1.2 +++ b/INSTALL	Wed Oct 17 19:14:07 2018 +0200
     1.3 @@ -1,197 +1,167 @@
     1.4  Installation Instructions
     1.5  =========================
     1.6  
     1.7 -Since you are reading this I assume you already obtained one of the release
     1.8 -tarballs and successfully extracted it. The latest version of LEMON is
     1.9 -available at our web page (http://lemon.cs.elte.hu/).
    1.10 +This file contains instructions for building and installing LEMON from
    1.11 +source on Linux. The process on Windows is similar.
    1.12  
    1.13 -LEMON provides two different build environments, one is based on "autotool",
    1.14 -while the other is based on "cmake". This file contains instructions only for
    1.15 -the former one, which is the recommended build environment on Linux, Mac OSX
    1.16 -and other unices or if you use Cygwin on Windows. For cmake installation
    1.17 -instructions visit http://lemon.cs.elte.hu.
    1.18 +Note that it is not necessary to install LEMON in order to use
    1.19 +it. Instead, you can easily integrate it with your own code
    1.20 +directly. For instructions, see
    1.21 +https://lemon.cs.elte.hu/trac/lemon/wiki/HowToCompile
    1.22 +
    1.23  
    1.24  In order to install LEMON from the extracted source tarball you have to
    1.25  issue the following commands:
    1.26  
    1.27 -   1. `cd lemon-x.y.z'
    1.28 +   1. Step into the root of the source directory.
    1.29  
    1.30 -      This command changes to the directory which was created when you
    1.31 -      extracted the sources. The x.y.z part is a version number.
    1.32 +      $ cd lemon-x.y.z
    1.33  
    1.34 -   2. `./configure'
    1.35 +   2. Create a build subdirectory and step into it.
    1.36  
    1.37 -      This command runs the configure shell script, which does some checks and
    1.38 -      creates the makefiles.
    1.39 +      $ mkdir build
    1.40 +      $ cd build
    1.41  
    1.42 -   3. `make'
    1.43 +   3. Perform system checks and create the makefiles.
    1.44  
    1.45 -      This command compiles the non-template part of LEMON into libemon.a
    1.46 -      file. It also compiles the programs in the tools subdirectory by
    1.47 -      default.
    1.48 +      $ cmake ..
    1.49  
    1.50 -   4. `make check'
    1.51 +   4. Build LEMON.
    1.52  
    1.53 -      This step is optional, but recommended. It runs the test programs that
    1.54 -      we developed for LEMON to check whether the library works properly on
    1.55 -      your platform.
    1.56 +      $ make 
    1.57  
    1.58 -   5. `make install'
    1.59 +      This command compiles the non-template part of LEMON into
    1.60 +      libemon.a file. It also compiles the programs in the 'tools' and
    1.61 +      'demo' subdirectories.
    1.62 +
    1.63 +   5. [Optional] Compile and run the self-tests.
    1.64 +
    1.65 +      $ make check
    1.66 +
    1.67 +   5. [Optional] Generate the user documentation.
    1.68 +
    1.69 +      $ make html
    1.70 +
    1.71 +      The release tarballs already include the documentation.
    1.72 +
    1.73 +      Note that for this step you need to have the following tools
    1.74 +      installed: Python, Doxygen, Graphviz, Ghostscript, LaTeX.
    1.75 +
    1.76 +   6. [Optional] Install LEMON
    1.77 +
    1.78 +      $ make install
    1.79  
    1.80        This command installs LEMON under /usr/local (you will need root
    1.81 -      privileges to be able to do that). If you want to install it to some
    1.82 -      other location, then pass the --prefix=DIRECTORY flag to configure in
    1.83 -      step 2. For example: `./configure --prefix=/home/username/lemon'.
    1.84 -
    1.85 -   6. `make install-html'
    1.86 -
    1.87 -      This command installs the documentation under share/doc/lemon/docs. The
    1.88 -      generated documentation is included in the tarball. If you want to
    1.89 -      generate it yourself, then run `make html'. Note that for this you need
    1.90 -      to have the following programs installed: Doxygen, Graphviz, Ghostscript,
    1.91 -      Latex.
    1.92 -
    1.93 +      privileges to be able to do that). If you want to install it to
    1.94 +      some other location, then pass the
    1.95 +      -DCMAKE_INSTALL_PREFIX=DIRECTORY flag to cmake in Step 3.
    1.96 +      For example:
    1.97 +      
    1.98 +      $ cmake -DCMAKE_INSTALL_PREFIX=/home/username/lemon'
    1.99  
   1.100  Configure Options and Variables
   1.101  ===============================
   1.102  
   1.103 -In step 2 you can customize the actions of configure by setting variables
   1.104 -and passing options to it. This can be done like this:
   1.105 -`./configure [OPTION]... [VARIABLE=VALUE]...'
   1.106 +In Step 3, you can customize the build process by passing options to CMAKE.
   1.107  
   1.108 -Below you will find some useful variables and options (see `./configure --help'
   1.109 -for more):
   1.110 +$ cmake [OPTIONS] ..
   1.111  
   1.112 -CXX='comp'
   1.113 +You find a list of the most useful options below.
   1.114  
   1.115 -  Change the C++ compiler to 'comp'.
   1.116 -
   1.117 -CXXFLAGS='flags'
   1.118 -
   1.119 -  Pass the 'flags' to the compiler. For example CXXFLAGS='-O3 -march=pentium-m'
   1.120 -  turns on generation of aggressively optimized Pentium-M specific code.
   1.121 -
   1.122 ---prefix=PREFIX
   1.123 +-DCMAKE_INSTALL_PREFIX=PREFIX
   1.124  
   1.125    Set the installation prefix to PREFIX. By default it is /usr/local.
   1.126  
   1.127 ---enable-tools
   1.128 +-DCMAKE_BUILD_TYPE=[Release|Debug|Maintainer|...]
   1.129  
   1.130 -   Build the programs in the tools subdirectory (default).
   1.131 +  This sets the compiler options. The choices are the following
   1.132  
   1.133 ---disable-tools
   1.134 +  'Release': A strong optimization is turned on (-O3 with gcc). This
   1.135 +    is the default setting and we strongly recommend using this for
   1.136 +    the final compilation.
   1.137  
   1.138 -   Do not build the programs in the tools subdirectory.
   1.139 +  'Debug': Optimization is turned off and debug info is added (-O0
   1.140 +    -ggdb with gcc). If is recommended during the development.
   1.141  
   1.142 ---with-glpk[=PREFIX]
   1.143 +  'Maintainer': The same as 'Debug' but the compiler warnings are
   1.144 +    converted to errors (-Werror with gcc). In addition, 'make' will
   1.145 +    also automatically compile and execute the test codes. It is the
   1.146 +    best way of ensuring that LEMON codebase is clean and safe.
   1.147  
   1.148 -   Enable GLPK support (default). You should specify the prefix too if
   1.149 -   you installed GLPK to some non-standard location (e.g. your home
   1.150 -   directory). If it is not found, GLPK support will be disabled.
   1.151 +  'RelWithDebInfo': Optimized build with debug info.
   1.152  
   1.153 ---with-glpk-includedir=DIR
   1.154 +  'MinSizeRel': Size optimized build (-Os with gcc)
   1.155  
   1.156 -   The directory where the GLPK header files are located. This is only
   1.157 -   useful when the GLPK headers and libraries are not under the same
   1.158 -   prefix (which is unlikely).
   1.159 +-DTEST_WITH_VALGRIND=YES
   1.160  
   1.161 ---with-glpk-libdir=DIR
   1.162 +  Using this, the test codes will be executed using valgrind. It is a
   1.163 +  very effective way of identifying indexing problems and memory leaks.
   1.164  
   1.165 -   The directory where the GLPK libraries are located. This is only
   1.166 -   useful when the GLPK headers and libraries are not under the same
   1.167 -   prefix (which is unlikely).
   1.168 +-DCMAKE_CXX_COMPILER=path-to-compiler
   1.169  
   1.170 ---without-glpk
   1.171 +  Change the compiler to be used.
   1.172  
   1.173 -   Disable GLPK support.
   1.174 +-DBUILD_SHARED_LIBS=TRUE
   1.175  
   1.176 ---with-cplex[=PREFIX]
   1.177 +  Build shared library instead of static one. Think twice if you
   1.178 +  really want to use this option.
   1.179  
   1.180 -   Enable CPLEX support (default). You should specify the prefix too
   1.181 -   if you installed CPLEX to some non-standard location
   1.182 -   (e.g. /opt/ilog/cplex75). If it is not found, CPLEX support will be
   1.183 -   disabled.
   1.184 +-DLEMON_DOC_SOURCE_BROWSER=YES
   1.185  
   1.186 ---with-cplex-includedir=DIR
   1.187 +  Include the browsable cross referenced LEMON source code into the
   1.188 +  doc. It makes the doc quite bloated, but may be useful for
   1.189 +  developing LEMON itself.
   1.190  
   1.191 -   The directory where the CPLEX header files are located. This is
   1.192 -   only useful when the CPLEX headers and libraries are not under the
   1.193 -   same prefix (e.g.  /usr/local/cplex/cplex75/include).
   1.194 +-DLEMON_DOC_USE_MATHJAX=YES
   1.195  
   1.196 ---with-cplex-libdir=DIR
   1.197 +  Use MathJax (http://mathjax.org) for rendering the math formulae in
   1.198 +  the doc.  It of much higher quality compared to the default LaTeX
   1.199 +  generated static images and it allows copy&paste of the formulae to
   1.200 +  LaTeX, Open Office, MS Word etc. documents.
   1.201  
   1.202 -   The directory where the CPLEX libraries are located. This is only
   1.203 -   useful when the CPLEX headers and libraries are not under the same
   1.204 -   prefix (e.g.
   1.205 -   /usr/local/cplex/cplex75/lib/i86_linux2_glibc2.2_gcc3.0/static_pic_mt).
   1.206 +  On the other hand, it needs either Internet access or a locally
   1.207 +  installed version of MathJax to properly render the doc.
   1.208  
   1.209 ---without-cplex
   1.210 +-DLEMON_DOC_MATHJAX_RELPATH=DIRECTORY
   1.211 +  
   1.212 +  The location of the MathJax library. It defaults to
   1.213 +  http://www.mathjax.org/mathjax, which necessitates Internet access
   1.214 +  for proper rendering. The easiest way to make it usable offline is
   1.215 +  to set this parameter to 'mathjax' and copy all files of the MathJax
   1.216 +  library into the 'doc/html/mathjax' subdirectory of the build
   1.217 +  location.
   1.218  
   1.219 -   Disable CPLEX support.
   1.220 +  See http://docs.mathjax.org/en/latest/installation.html for more details.
   1.221  
   1.222 ---with-soplex[=PREFIX]
   1.223 +  
   1.224 +-DLEMON_ENABLE_GLPK=NO
   1.225 +-DLEMON_ENABLE_COIN=NO
   1.226 +-DLEMON_ENABLE_ILOG=NO
   1.227  
   1.228 -   Enable SoPlex support (default). You should specify the prefix too if
   1.229 -   you installed SoPlex to some non-standard location (e.g. your home
   1.230 -   directory). If it is not found, SoPlex support will be disabled.
   1.231 +  Enable optional third party libraries. They are all enabled by default. 
   1.232  
   1.233 ---with-soplex-includedir=DIR
   1.234 +-DLEMON_DEFAULT_LP=GLPK
   1.235  
   1.236 -   The directory where the SoPlex header files are located. This is only
   1.237 -   useful when the SoPlex headers and libraries are not under the same
   1.238 -   prefix (which is unlikely).
   1.239 +  Sets the default LP solver backend. The supported values are
   1.240 +  CPLEX, CLP and GLPK. By default, it is set to the first one which
   1.241 +  is enabled and succesfully discovered.
   1.242  
   1.243 ---with-soplex-libdir=DIR
   1.244 +-DLEMON_DEFAULT_MIP=GLPK
   1.245  
   1.246 -   The directory where the SoPlex libraries are located. This is only
   1.247 -   useful when the SoPlex headers and libraries are not under the same
   1.248 -   prefix (which is unlikely).
   1.249 +  Sets the default MIP solver backend. The supported values are
   1.250 +  CPLEX, CBC and GLPK. By default, it is set to the first one which
   1.251 +  is enabled and succesfully discovered.
   1.252  
   1.253 ---without-soplex
   1.254 +-DGLPK_ROOT_DIR=DIRECTORY
   1.255 +-DCOIN_ROOT_DIR=DIRECTORY
   1.256 +-DILOG_ROOT_DIR=DIRECTORY
   1.257  
   1.258 -   Disable SoPlex support.
   1.259 -
   1.260 ---with-coin[=PREFIX]
   1.261 -
   1.262 -   Enable support for COIN-OR solvers (CLP and CBC). You should
   1.263 -   specify the prefix too. (by default, COIN-OR tools install
   1.264 -   themselves to the source code directory). This command enables the
   1.265 -   solvers that are actually found.
   1.266 -
   1.267 ---with-coin-includedir=DIR
   1.268 -
   1.269 -   The directory where the COIN-OR header files are located. This is
   1.270 -   only useful when the COIN-OR headers and libraries are not under
   1.271 -   the same prefix (which is unlikely).
   1.272 -
   1.273 ---with-coin-libdir=DIR
   1.274 -
   1.275 -   The directory where the COIN-OR libraries are located. This is only
   1.276 -   useful when the COIN-OR headers and libraries are not under the
   1.277 -   same prefix (which is unlikely).
   1.278 -
   1.279 ---without-coin
   1.280 -
   1.281 -   Disable COIN-OR support.
   1.282 -
   1.283 +  Root directory prefixes of optional third party libraries.
   1.284  
   1.285  Makefile Variables
   1.286  ==================
   1.287  
   1.288 -Some Makefile variables are reserved by the GNU Coding Standards for
   1.289 -the use of the "user" - the person building the package. For instance,
   1.290 -CXX and CXXFLAGS are such variables, and have the same meaning as
   1.291 -explained in the previous section. These variables can be set on the
   1.292 -command line when invoking `make' like this:
   1.293 -`make [VARIABLE=VALUE]...'
   1.294 +make VERBOSE=1
   1.295  
   1.296 -WARNINGCXXFLAGS is a non-standard Makefile variable introduced by us
   1.297 -to hold several compiler flags related to warnings. Its default value
   1.298 -can be overridden when invoking `make'. For example to disable all
   1.299 -warning flags use `make WARNINGCXXFLAGS='.
   1.300 -
   1.301 -In order to turn off a single flag from the default set of warning
   1.302 -flags, you can use the CXXFLAGS variable, since this is passed after
   1.303 -WARNINGCXXFLAGS. For example to turn off `-Wold-style-cast' (which is
   1.304 -used by default when g++ is detected) you can use
   1.305 -`make CXXFLAGS="-g -O2 -Wno-old-style-cast"'.
   1.306 +   This results in a more verbose output by showing the full
   1.307 +   compiler and linker commands.
   1.308 \ No newline at end of file