/* -*- mode: C++; indent-tabs-mode: nil; -*-

  *

  * This file is a part of LEMON, a generic C++ optimization library.

  *

  * Copyright (C) 2003-2008

  * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport

  * (Egervary Research Group on Combinatorial Optimization, EGRES).

  *

  * Permission to use, modify and distribute this software is granted

  * provided that this copyright notice appears in all copies. For

  * precise terms see the accompanying LICENSE file.

  *

  * This software is provided "AS IS" with no warranty of any kind,

  * express or implied, and with no claim as to its suitability for any

  * purpose.

  *

  */

 /**

 [PAGE]install[PAGE] Installation Guide

 In this section we detail how to start using LEMON, from downloading it

 to your computer, through the steps of installation, to showing how to

 compile programs that use LEMON. We assume that you

 have a basic knowledge of your operating system and C++ programming

 language. The procedure is pretty straightforward, but if you have any

 difficulties do not hesitate to

 <a href="mailto:lemon-user@lemon.cs.elte.hu"><b>ask</b></a>.

 [SEC]requirements_lemon[SEC] Hardware and Software Requirements

 In LEMON we use C++ templates heavily, thus compilation takes a

 considerable amount of time and memory. So some decent box would be

 advantageousm, but otherwise there are no special hardware requirements.

 You will need a recent C++ compiler. Our primary target is the GNU C++

 Compiler (g++), from version 3.3 upwards. We also checked the Intel C++

 Compiler (icc) and Microsoft Visual C++ (on Windows).

 If you want to develop with LEMON under Windows, you can use a Windows

 installer or you can consider using Cygwin.

 In this description we will suppose a Linux environment and GNU C++ Compiler.

 If you would like to develop under Windows and use a Windows installer,

 you could skip the following sections and continue reading

 \ref basic_concepts.

 However keep in mind that you have to make appropriate steps instead of

 the instructions detailed here to be able to use LEMON with your compiler.

 [SEC]requirements_lp[SEC] LP Solver Requirements

 The LEMON LP solver interface can use the GLPK (GNU Linear Programming

 Kit), CPLEX and SoPlex solver. If you want to use it, you will need at

 least one of these.

 See the <b><tt>INSTALL</tt></b> file how to enable these at compile time.

 [SEC]install_from_source[SEC] Install from Source

 You can download LEMON from the web site:

 <a href="http://lemon.cs.elte.hu/">http://lemon.cs.elte.hu/</a>.

 There you will find released versions in form of <tt>.tar.gz</tt> files

 (and Windows installers).

 If you want a developer version (for example you want to contribute in

 developing LEMON) then you might want to use our Mercurial repository.

 This case is detailed \ref hg_checkout "later", so from now on we

 suppose that you downloaded a <tt>.tar.gz</tt> file.

 Thus you have to do the following steps.

 Download the tarball either from the browser or just issuing

 \verbatim

 wget http://lemon.cs.elte.hu/pub/sources/lemon-1.0.tar.gz

 \endverbatim

 \note The tarball is named <tt>lemon-x.y.z.tar.gz</tt> where \c x, \c

 y and \c z (which is missing if it is 0) are numbers indicating the

 version of the library, in our example we will have

 <tt>lemon-1.0.tar.gz</tt>.

 Then issue the following commands:

 \verbatim

 tar xvzf lemon-1.0.tar.gz

 cd lemon-1.0

 ./configure

 make

 make check    # This is optional, but recommended. It runs a bunch of tests.

 make install

 \endverbatim

 These commands install LEMON under \c /usr/local (you will

 need root privileges to be able to install to that

 directory). If you want to install it to some other place, then

 pass the \c --prefix=DIRECTORY flag to <tt>./configure</tt>, for example:

 \verbatim

 ./configure --prefix=/home/username/lemon

 \endverbatim

 We briefly explain these commands below.

 \verbatim

 tar xvzf lemon-1.0.tar.gz

 \endverbatim

 This command untars the <tt>tar.gz</tt> file into a directory named

 <tt>lemon-1.0</tt>.

 \verbatim

 cd lemon-1.0

 \endverbatim

 This command enters the directory.

 \verbatim

 ./configure

 \endverbatim

 This command runs the configure shell script, which does some checks and

 creates the makefiles.

 \verbatim

 make

 \endverbatim

 This command compiles the non-template part of LEMON into <tt>libemon.a</tt>

 file. It also compiles the programs in the tools and demo subdirectories

 when enabled.

 \verbatim

 make check

 \endverbatim

 This step is optional, but recommended. It performes a bunch of library

 self-tests.

 \verbatim

 make install

 \endverbatim

 This command will copy the directory structure to its final destination

 (e.g. to \c /usr/local) so that your system can access it.

 This command should be issued as "root", unless you provided a

 \c --prefix switch to the \c configure to install the library in

 non-default location.

 Several other configure flags can be passed to <tt>./configure</tt>.

 For more information see the <b><tt>INSTALL</tt></b> file.

 [SEC]install_hg[SEC] Install the Latest Development Version

 You can also use the latest (developer) version of LEMON from our Mercurial

 repository. You need a couple additional tool for that.

 - <a href="http://www.selenic.com/mercurial">Mercurial</a>

   - for obtaining the latest code (and for contributing into it)

 - <a href="http://www.gnu.org/software/automake/">automake</a> (1.7 or newer)

 - <a href="http://www.gnu.org/software/autoconf/">autoconf</a> (2.59 or newer)

 - <a href="http://www.gnu.org/software/libtool/">libtool</a>

 - <a href="http://pkgconfig.freedesktop.org/">pkgconfig</a>

   - for initializing the build framework

 - <a href="http://doxygen.org">Doxygen</a>

   - for generating the documentations (optional, but recommended)

 Once you have all these tools installed, the process is fairly easy.

 First, you have to get the copy of the latest version.

 \verbatim

 hg clone http://lemon.cs.elte.hu/hg/lemon-main lemon-src

 \endverbatim

 The next step is to initialize the build system.

 \verbatim

 autoreconf -vif

 \endverbatim

 Then the process is the same as in case of using the release tarball.

 \verbatim

 ./configure

 make

 make check    # This is optional, but recommended. It runs a bunch of tests.

 make install

 \endverbatim

 To generate the documentation, just run

 \verbatim

 make html

 \endverbatim

 \todo Is <tt><b>make html</b></tt> really necessary after

 <tt><b>make install</b></tt>?

 [SEC]install_rpm[SEC] Install from rpm

 \todo Write this section (\ref install_rpm).

 [SEC]install_user[SEC] Install Locally to the User

 \todo Write this section (\ref install_user).

 [SEC]compile_codes[SEC] Compile Codes that Use LEMON

 Now let us see how to use the library after installing it.

 [SEC]compile_system_wide[SEC] If LEMON is Installed System-Wide

 If your installation of LEMON into directory \c /usr/local was

 successful, then you have to issue a command like this to compile a

 source file that uses LEMON.

 \verbatim

 g++ -lemon [other options] <source file>

 \endverbatim

 The argument <tt>-lemon</tt> tells the compiler that we are using the

 installed library LEMON.

 [SEC]compile_user_local[SEC] If LEMON is Installed User-Local

 You have to give more options to the compiler if LEMON is installed

 user-local into a directory (denoted by <tt><dir></tt>)

 or if you just skipped the step <tt>make install</tt>.

 In the later case <tt><dir></tt> denotes the directory in which the

 the \c make command have been performed.

 \verbatim

 g++ -lemon -I <dir> -L <dir>/lemon/.libs [other options] <source file>

 \endverbatim

 [SEC]compile_use_pkg_config[SEC] Use pkg-config

 \todo Write this sub-subsection (\ref compile_use_pkg_config).

 [TRAILER]

 */