alpar@7: /* -*- mode: C++; indent-tabs-mode: nil; -*-
alpar@7:  *
alpar@7:  * This file is a part of LEMON, a generic C++ optimization library.
alpar@7:  *
alpar@7:  * Copyright (C) 2003-2008
alpar@7:  * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
alpar@7:  * (Egervary Research Group on Combinatorial Optimization, EGRES).
alpar@7:  *
alpar@7:  * Permission to use, modify and distribute this software is granted
alpar@7:  * provided that this copyright notice appears in all copies. For
alpar@7:  * precise terms see the accompanying LICENSE file.
alpar@7:  *
alpar@7:  * This software is provided "AS IS" with no warranty of any kind,
alpar@7:  * express or implied, and with no claim as to its suitability for any
alpar@7:  * purpose.
alpar@7:  *
alpar@7:  */
alpar@7: 
alpar@7: /**
alpar@7: \page install Installation Guide
alpar@7: 
kpeter@9: In this section we detail how to start using LEMON, from downloading it
kpeter@9: to your computer, through the steps of installation, to showing how to
kpeter@9: compile programs that use LEMON. We assume that you
alpar@7: have a basic knowledge of your operating system and C++ programming
alpar@7: language. The procedure is pretty straightforward, but if you have any
alpar@7: difficulties do not hesitate to
alpar@7: <a href="mailto:lemon-user@lemon.cs.elte.hu"><b>ask</b></a>.
alpar@7: 
alpar@7: \section requirements_lemon Hardware and Software Requirements
alpar@7: 
alpar@7: In LEMON we use C++ templates heavily, thus compilation takes a
alpar@7: considerable amount of time and memory. So some decent box would be
alpar@7: advantageousm, but otherwise there are no special hardware requirements.
alpar@7: 
alpar@7: You will need a recent C++ compiler. Our primary target is the GNU C++
alpar@7: Compiler (g++), from version 3.3 upwards. We also checked the Intel C++
alpar@7: Compiler (icc) and Microsoft Visual C++ (on Windows).
alpar@7: If you want to develop with LEMON under Windows, you can use a Windows
alpar@7: installer or you can consider using Cygwin.
alpar@7: 
alpar@7: In this description we will suppose a Linux environment and GNU C++ Compiler.
alpar@7: If you would like to develop under Windows and use a Windows installer,
kpeter@9: you could skip the following sections and continue reading
kpeter@9: \ref basic_concepts.
alpar@7: However keep in mind that you have to make appropriate steps instead of
kpeter@9: the instructions detailed here to be able to use LEMON with your compiler.
alpar@7: 
alpar@7: \subsection requirements_lp LP Solver Requirements
alpar@7: 
alpar@7: The LEMON LP solver interface can use the GLPK (GNU Linear Programming
alpar@7: Kit), CPLEX and SoPlex solver. If you want to use it, you will need at
alpar@7: least one of these.
alpar@7: See the <b><tt>INSTALL</tt></b> file how to enable these at compile time.
alpar@7: 
alpar@7: \section install_from_source Install from Source
alpar@7: 
alpar@7: You can download LEMON from the web site:
alpar@7: <a href="http://lemon.cs.elte.hu/">http://lemon.cs.elte.hu/</a>.
alpar@7: There you will find released versions in form of <tt>.tar.gz</tt> files
alpar@7: (and Windows installers).
alpar@7: If you want a developer version (for example you want to contribute in
alpar@7: developing LEMON) then you might want to use our Mercurial repository.
kpeter@11: This case is detailed \ref install_hg "later", so from now on we
alpar@7: suppose that you downloaded a <tt>.tar.gz</tt> file.
alpar@7: 
alpar@7: Thus you have to do the following steps.
alpar@7: 
alpar@7: Download the tarball either from the browser or just issuing
alpar@7: 
alpar@7: \verbatim
alpar@7: wget http://lemon.cs.elte.hu/pub/sources/lemon-1.0.tar.gz
alpar@7: \endverbatim
alpar@7: 
alpar@7: \note The tarball is named <tt>lemon-x.y.z.tar.gz</tt> where \c x, \c
alpar@7: y and \c z (which is missing if it is 0) are numbers indicating the
alpar@7: version of the library, in our example we will have
alpar@7: <tt>lemon-1.0.tar.gz</tt>.
alpar@7: 
alpar@7: Then issue the following commands:
alpar@7: 
alpar@7: \verbatim
alpar@7: tar xvzf lemon-1.0.tar.gz
alpar@7: cd lemon-1.0
alpar@7: ./configure
alpar@7: make
alpar@7: make check    # This is optional, but recommended. It runs a bunch of tests.
alpar@7: make install
alpar@7: \endverbatim
alpar@7: 
alpar@7: These commands install LEMON under \c /usr/local (you will
alpar@7: need root privileges to be able to install to that
alpar@7: directory). If you want to install it to some other place, then
alpar@7: pass the \c --prefix=DIRECTORY flag to <tt>./configure</tt>, for example:
alpar@7: 
alpar@7: \verbatim
alpar@7: ./configure --prefix=/home/username/lemon
alpar@7: \endverbatim
alpar@7: 
alpar@7: We briefly explain these commands below.
alpar@7: 
alpar@7: \verbatim
alpar@7: tar xvzf lemon-1.0.tar.gz
alpar@7: \endverbatim
alpar@7: This command untars the <tt>tar.gz</tt> file into a directory named
alpar@7: <tt>lemon-1.0</tt>.
alpar@7: 
alpar@7: \verbatim
alpar@7: cd lemon-1.0
alpar@7: \endverbatim
alpar@7: This command enters the directory.
alpar@7: 
alpar@7: \verbatim
alpar@7: ./configure
alpar@7: \endverbatim
alpar@7: This command runs the configure shell script, which does some checks and
alpar@7: creates the makefiles.
alpar@7: 
alpar@7: \verbatim
alpar@7: make
alpar@7: \endverbatim
alpar@7: This command compiles the non-template part of LEMON into <tt>libemon.a</tt>
alpar@7: file. It also compiles the programs in the tools and demo subdirectories
alpar@7: when enabled.
alpar@7: 
alpar@7: \verbatim
alpar@7: make check
alpar@7: \endverbatim
alpar@7: This step is optional, but recommended. It performes a bunch of library
alpar@7: self-tests.
alpar@7: 
alpar@7: \verbatim
alpar@7: make install
alpar@7: \endverbatim
alpar@7: This command will copy the directory structure to its final destination
alpar@7: (e.g. to \c /usr/local) so that your system can access it.
alpar@7: This command should be issued as "root", unless you provided a
alpar@7: \c --prefix switch to the \c configure to install the library in
alpar@7: non-default location.
alpar@7: 
alpar@7: Several other configure flags can be passed to <tt>./configure</tt>.
alpar@7: For more information see the <b><tt>INSTALL</tt></b> file.
alpar@7: 
kpeter@9: \subsection install_hg Install the Latest Development Version
alpar@7: 
alpar@7: You can also use the latest (developer) version of LEMON from our Mercurial
kpeter@9: repository. You need a couple additional tool for that.
alpar@7: 
alpar@7: - <a href="http://www.selenic.com/mercurial">Mercurial</a>
alpar@7:   - for obtaining the latest code (and for contributing into it)
alpar@7: - <a href="http://www.gnu.org/software/automake/">automake</a> (1.7 or newer)
alpar@7: - <a href="http://www.gnu.org/software/autoconf/">autoconf</a> (2.59 or newer)
alpar@7: - <a href="http://www.gnu.org/software/libtool/">libtool</a>
alpar@7: - <a href="http://pkgconfig.freedesktop.org/">pkgconfig</a>
alpar@7:   - for initializing the build framework
alpar@7: - <a href="http://doxygen.org">Doxygen</a>
alpar@7:   - for generating the documentations (optional, but recommended)
alpar@7: 
alpar@7: Once you have all these tools installed, the process is fairly easy.
kpeter@9: First, you have to get the copy of the latest version.
alpar@7: 
alpar@7: \verbatim
alpar@7: hg clone http://lemon.cs.elte.hu/hg/lemon-main lemon-src
alpar@7: \endverbatim
alpar@7: 
alpar@7: The next step is to initialize the build system.
alpar@7: 
alpar@7: \verbatim
alpar@7: autoreconf -vif
alpar@7: \endverbatim
alpar@7: 
alpar@7: Then the process is the same as in case of using the release tarball.
alpar@7: 
alpar@7: \verbatim
alpar@7: ./configure
alpar@7: make
alpar@7: make check    # This is optional, but recommended. It runs a bunch of tests.
alpar@7: make install
alpar@7: \endverbatim
alpar@7: 
kpeter@9: To generate the documentation, just run
alpar@7: \verbatim
alpar@7: make html
alpar@7: \endverbatim
kpeter@9: \todo Is <tt><b>make html</b></tt> really necessary after
kpeter@9: <tt><b>make install</b></tt>?
kpeter@9: 
kpeter@9: 
kpeter@9: \section install_rpm Install from rpm
kpeter@9: 
kpeter@9: \todo Write this section (\ref install_rpm).
kpeter@9: 
kpeter@9: 
kpeter@9: \section install_user Install Locally to the User
kpeter@9: 
kpeter@9: \todo Write this section (\ref install_user).
kpeter@9: 
kpeter@9: 
kpeter@9: \section compile_codes Compile Codes that Use LEMON
kpeter@9: 
kpeter@9: Now let us see how to use the library after installing it.
kpeter@9: 
kpeter@9: \subsection compile_system_wide If LEMON is Installed System-Wide
kpeter@9: 
kpeter@9: If your installation of LEMON into directory \c /usr/local was
kpeter@9: successful, then you have to issue a command like this to compile a
kpeter@9: source file that uses LEMON.
kpeter@9: 
kpeter@9: \verbatim
kpeter@9: g++ -lemon [other options] <source file>
kpeter@9: \endverbatim
kpeter@9: 
kpeter@9: The argument <tt>-lemon</tt> tells the compiler that we are using the
kpeter@9: installed library LEMON.
kpeter@9: 
kpeter@9: \subsection compile_user_local If LEMON is Installed User-Local
kpeter@9: 
kpeter@9: You have to give more options to the compiler if LEMON is installed
kpeter@11: user-local into a directory (denoted by <tt>&lt;dir&gt;</tt>)
kpeter@9: or if you just skipped the step <tt>make install</tt>.
kpeter@11: In the later case <tt>&lt;dir&gt;</tt> denotes the directory in which the
kpeter@9: the \c make command have been performed.
kpeter@9: 
kpeter@9: \verbatim
kpeter@9: g++ -lemon -I <dir> -L <dir>/lemon/.libs [other options] <source file>
kpeter@9: \endverbatim
kpeter@9: 
kpeter@9: \subsubsection compile_use_pkg_config Use pkg-config
kpeter@9: 
kpeter@9: \todo Write this sub-subsection (\ref compile_use_pkg_config).
alpar@7: 
alpar@7: */