1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/getting_started.dox	Sat Oct 11 13:13:09 2008 +0200
     1.3 @@ -0,0 +1,160 @@
     1.4 +/* -*- mode: C++; indent-tabs-mode: nil; -*-
     1.5 + *
     1.6 + * This file is a part of LEMON, a generic C++ optimization library.
     1.7 + *
     1.8 + * Copyright (C) 2003-2008
     1.9 + * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
    1.10 + * (Egervary Research Group on Combinatorial Optimization, EGRES).
    1.11 + *
    1.12 + * Permission to use, modify and distribute this software is granted
    1.13 + * provided that this copyright notice appears in all copies. For
    1.14 + * precise terms see the accompanying LICENSE file.
    1.15 + *
    1.16 + * This software is provided "AS IS" with no warranty of any kind,
    1.17 + * express or implied, and with no claim as to its suitability for any
    1.18 + * purpose.
    1.19 + *
    1.20 + */
    1.21 +
    1.22 +/**
    1.23 +\page getting_started How to Start Using LEMON
    1.24 +
    1.25 +In this page we detail how to start using LEMON, from downloading it to
    1.26 +your computer, through the steps of installation, to showing a simple
    1.27 +"Hello World" type program that already uses LEMON. We assume that you
    1.28 +have a basic knowledge of your operating system and C++ programming
    1.29 +language. The procedure is pretty straightforward, but if you have any
    1.30 +difficulties don't hesitate to
    1.31 +<a href="mailto:lemon-user@lemon.cs.elte.hu"><b>ask</b></a>.
    1.32 +
    1.33 +\section requirements_lemon Hardware and Software Requirements
    1.34 +
    1.35 +In LEMON we use C++ templates heavily, thus compilation takes a
    1.36 +considerable amount of time and memory. So some decent box would be
    1.37 +advantageous. But otherwise there are no special hardware requirements.
    1.38 +
    1.39 +You will need a recent C++ compiler. Our primary target is the GNU C++
    1.40 +Compiler (g++), from version 3.3 upwards. We also checked the Intel C++
    1.41 +Compiler (icc) and Microsoft Visual C++ .NET 2003, 2005.
    1.42 +If you want to develop with LEMON under Windows you could consider
    1.43 +using Cygwin.
    1.44 +
    1.45 +In this description we will suppose a Linux environment and GNU C++ Compiler.
    1.46 +
    1.47 +\subsection requirements_lp LP Solver Requirements
    1.48 +
    1.49 +The LEMON LP solver interface can use the GLPK (GNU Linear Programming
    1.50 +Kit), CPLEX (was tested with CPLEX 7.5) and SoPlex solver. If you want
    1.51 +to use it you will need at least one of these. See \ref configure_flags
    1.52 +how to enable these at compile time.
    1.53 +
    1.54 +\section download_lemon How to Download LEMON
    1.55 +
    1.56 +You can download LEMON from the LEMON web site:
    1.57 +<a href="http://lemon.cs.elte.hu/">https://lemon.cs.elte.hu/</a>.
    1.58 +There you will find released versions in form of <tt>.tar.gz</tt> files.
    1.59 +If you want a developer version (for example you want to contribute in
    1.60 +developing the library LEMON) then you might want to use our Mercurial
    1.61 +repository. This case is detailed later, so from now on we suppose that
    1.62 +you downloaded a <tt>.tar.gz</tt> file.
    1.63 +
    1.64 +\section install_lemon How to Install LEMON
    1.65 +
    1.66 +In order to install LEMON you have to do the following steps.
    1.67 +
    1.68 +Download the tarball (named <tt>lemon-x.y.z.tar.gz</tt> where \c x, \c y
    1.69 +and \c z are numbers indicating the version of the library, in our example
    1.70 +we will have <tt>lemon-1.0.tar.gz</tt>) and issue the following commands:
    1.71 +
    1.72 +\verbatim
    1.73 +tar xvzf lemon-1.0.tar.gz
    1.74 +cd lemon-1.0
    1.75 +./configure
    1.76 +make
    1.77 +make check    # This is optional, but recommended. It runs a bunch of tests.
    1.78 +make install
    1.79 +\endverbatim
    1.80 +
    1.81 +These commands install LEMON under \c /usr/local (you will
    1.82 +need root privileges to be able to install to that
    1.83 +directory). If you want to install it to some other place, then
    1.84 +pass the \c --prefix=DIRECTORY flag to <tt>./configure</tt>, for example:
    1.85 +
    1.86 +\verbatim
    1.87 +./configure --prefix=/home/username/lemon
    1.88 +\endverbatim
    1.89 +
    1.90 +In what follows we will assume that you were able to install to directory
    1.91 +\c /usr/local, otherwise some extra care is to be taken to use the library.
    1.92 +
    1.93 +We briefly explain these commands below.
    1.94 +
    1.95 +\verbatim
    1.96 +tar xvzf lemon-1.0.tar.gz
    1.97 +\endverbatim
    1.98 +This command untars the <tt>tar.gz</tt> file into a directory named
    1.99 +<tt>lemon-1.0</tt>.
   1.100 +
   1.101 +\verbatim
   1.102 +cd lemon-1.0
   1.103 +\endverbatim
   1.104 +This command enters the directory.
   1.105 +
   1.106 +\verbatim
   1.107 +./configure
   1.108 +\endverbatim
   1.109 +This command runs the configure shell script, which does some checks and
   1.110 +creates the makefiles.
   1.111 +
   1.112 +\verbatim
   1.113 +make
   1.114 +\endverbatim
   1.115 +This command compiles the non-template part of LEMON into <tt>libemon.a</tt>
   1.116 +file. It also compiles the programs in the tools and demo subdirectories
   1.117 +when enabled.
   1.118 +
   1.119 +\verbatim
   1.120 +make check
   1.121 +\endverbatim
   1.122 +This step is optional, but recommended. It runs the test programs that
   1.123 +we developed for LEMON to check whether the library works properly on
   1.124 +your platform.
   1.125 +
   1.126 +\verbatim
   1.127 +make install
   1.128 +\endverbatim
   1.129 +This command will copy the directory structure to its final destination
   1.130 +(e.g. to \c /usr/local) so that your system can access it.
   1.131 +This command should be issued as "root", unless you provided a
   1.132 +\c --prefix switch to the \c configure to install the library in
   1.133 +non-default location.
   1.134 +
   1.135 +Several other configure flags can be passed to <tt>./configure</tt>.
   1.136 +For more information see <tt>./configure --help</tt> and the INSTALL
   1.137 +file in the install directory.
   1.138 +
   1.139 +\section hg_checkout How to Checkout LEMON from our Mercurial Repository
   1.140 +
   1.141 +You can obtain the latest version of LEMON from our Mercurial repository.
   1.142 +To do this issue the following command:
   1.143 +\verbatim
   1.144 +hg clone http://lemon.cs.elte.hu/hg/lemon lemon-src
   1.145 +\endverbatim
   1.146 +
   1.147 +\section hg_compile How to Compile the Source from the Repository
   1.148 +
   1.149 +You can compile the code from the repository similarly to the packaged
   1.150 +version, but you will need to run <b><tt>autoreconf -vif</tt></b> or
   1.151 +<b><tt>./bootstrap</tt></b> in some older environment before
   1.152 +<tt>./configure</tt>. See <tt>./configure --help</tt> for options.
   1.153 +For bootstrapping you will need the following tools:
   1.154 +
   1.155 + - <a href="http://www.gnu.org/software/automake/">automake</a> (1.7 or newer)
   1.156 + - <a href="http://www.gnu.org/software/autoconf/">autoconf</a> (2.59 or newer)
   1.157 + - <a href="http://www.gnu.org/software/libtool/">libtool</a>
   1.158 + - <a href="http://pkgconfig.freedesktop.org/">pkgconfig</a>
   1.159 +
   1.160 +To generate the documentation, run <tt>make html</tt>.
   1.161 +You will need <a href="http://www.doxygen.org/">Doxygen</a> for this.
   1.162 +
   1.163 +*/