doc/getstart.dox
author convert-repo
Thu, 04 Mar 2010 19:34:55 +0000
changeset 2659 611ced85018b
parent 2470 46818ce27a60
permissions -rw-r--r--
update tags
     1 /* -*- C++ -*-
     2  *
     3  * This file is a part of LEMON, a generic C++ optimization library
     4  *
     5  * Copyright (C) 2003-2008
     6  * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
     7  * (Egervary Research Group on Combinatorial Optimization, EGRES).
     8  *
     9  * Permission to use, modify and distribute this software is granted
    10  * provided that this copyright notice appears in all copies. For
    11  * precise terms see the accompanying LICENSE file.
    12  *
    13  * This software is provided "AS IS" with no warranty of any kind,
    14  * express or implied, and with no claim as to its suitability for any
    15  * purpose.
    16  *
    17  */
    18 
    19 /**
    20 \page getstart How to start using LEMON
    21 
    22 In this page we detail how to start using LEMON, from downloading it to
    23 your computer, through the steps of installation, to showing a simple
    24 "Hello World" type program that already uses LEMON. We assume that you
    25 have a basic knowledge of your operating system and \c C++ programming
    26 language. The procedure is pretty straightforward, but if you have any
    27 difficulties don't hesitate to 
    28 <a href="mailto:lemon-user@lemon.cs.elte.hu">ask</a>.
    29 
    30 
    31 \section requirementsLEMON Hardware and software requirements
    32 
    33 In LEMON we use C++ templates heavily, thus compilation takes a
    34 considerable amount of time and memory. So some decent box would be
    35 advantageous. But otherwise there are no special hardware requirements.
    36 
    37 You will need a recent C++ compiler. Our primary target is the GNU C++
    38 Compiler (g++), from version 3.3 upwards. We also checked the Intel C++
    39 Compiler (icc). Microsoft Visual C++ .NET 2003 was also reported to
    40 work (but not the earlier versions). If you want to develop with LEMON
    41 under Windows you could consider using Cygwin.
    42 
    43 In this description we will suppose a Linux environment and GNU C++ Compiler.
    44 
    45 
    46 \subsection requirementsLP LP solver requirements
    47 
    48 The LEMON LP solver interface can use the GLPK (GNU Linear Programming
    49 Kit) ,CPLEX (was tested with CPLEX 7.5) and SoPlex solver. If you want
    50 to use it you will need at least one of these. See \ref configureFlags
    51 how to enable these at compile time.
    52 
    53 
    54 \section downloadLEMON How to download LEMON
    55 
    56 You can download LEMON from the LEMON web site:
    57 <a href="https://lemon.cs.elte.hu/site/products/">
    58 https://lemon.cs.elte.hu/site/products/</a> .
    59 There you will find released versions in form of <tt>.tar.gz</tt> files.
    60 If you want a developer version (for example you want to contribute in
    61 developing the library LEMON) then you might want to use our Subversion
    62 repository. This case is detailed later, so from now on we suppose that
    63 you downloaded a <tt>.tar.gz</tt> file.
    64 
    65 
    66 \section installLEMON How to install LEMON
    67 
    68 In order to install LEMON you have to do the following steps.
    69 
    70 Download the tarball (named <tt>lemon-x.y.z.tar.gz</tt> where \c x,\c y
    71 and \c z are numbers indicating the version of the library: in our example
    72 we will have <tt>lemon-0.3.1.tar.gz</tt>) and issue the following
    73 commands:
    74 
    75 \verbatim
    76 tar xvzf lemon-0.3.1.tar.gz
    77 cd lemon-0.3.1
    78 ./configure
    79 make
    80 make check   #(This is optional, but recommended. It runs a bunch of tests.)
    81 make install
    82 \endverbatim
    83 
    84 These commands install LEMON under \c /usr/local (you will
    85 need root privileges to be able to install to that
    86 directory). If you want to install it to some other place, then
    87 pass the \c --prefix=DIRECTORY flag to <tt>./configure</tt>, for example:
    88 
    89 \verbatim
    90 ./configure --prefix=/home/username/lemon
    91 \endverbatim
    92 
    93 In what follows we will assume that you were able to install to directory
    94 \c /usr/local, otherwise some extra care is to be taken to use the
    95 library.
    96 
    97 We briefly explain these commands below.
    98 
    99 \verbatim
   100 tar xvzf lemon-0.3.1.tar.gz
   101 \endverbatim
   102 This command untars the <tt>tar.gz</tt> file into a directory named <tt>
   103 lemon-0.3.1</tt>.
   104 
   105 \verbatim
   106 cd lemon-0.3.1
   107 \endverbatim
   108 Enters the directory.
   109 
   110 \verbatim
   111 ./configure
   112 \endverbatim
   113 Does some configuration (creates makefiles etc).
   114 
   115 \verbatim
   116 make
   117 \endverbatim
   118 This command compiles the non-template part of LEMON into
   119 <b>libemon.a</b> file. It also compiles some benchmark and demo
   120 programs.
   121 
   122 \verbatim
   123 make check
   124 \endverbatim
   125 This is an optional step: it runs the test programs that we
   126 developed for LEMON to check whether the library works properly on
   127 your platform.
   128 
   129 \verbatim
   130 make install
   131 \endverbatim
   132 This will copy the directory structure to its final destination (e.g. to \c
   133 /usr/local) so that your system can access it. This command should
   134 be issued as "root", unless you provided a \c --prefix switch to
   135 the \c configure to install the library in non-default location.
   136 
   137 
   138 \subsection configureFlags Configure flags
   139 
   140 You can pass the following flags to <tt>./configure</tt> (see <tt>./configure</tt> --help
   141 for more):
   142 
   143 \verbatim
   144 --with-glpk[=PREFIX]
   145 \endverbatim
   146 Enable GLPK support (default). You should specify the prefix too if you
   147 installed it to some non-standard location (e.g. your home directory). If
   148 GLPK is not found, then GLPK support will be disabled.
   149 
   150 \verbatim
   151 --with-glpk-includedir=DIR
   152 \endverbatim
   153 The directory where the GLPK header files are located. This is only useful when
   154 the GLPK headers and libraries are not under the same prefix (which is
   155 unlikely).
   156 
   157 \verbatim
   158 --with-glpk-libdir=DIR
   159 \endverbatim
   160 The directory where the GLPK libraries are located. This is only useful when
   161 the GLPK headers and libraries are not under the same prefix (which is
   162 unlikely).
   163 
   164 \verbatim
   165 --without-glpk
   166 \endverbatim
   167 Disable GLPK support.
   168 
   169 \verbatim
   170 --with-cplex[=PREFIX]
   171 \endverbatim
   172 Enable CPLEX support (default). You should specify the prefix too if you
   173 installed it to some non-standard location (e.g. \c /opt/ilog/cplex75). If
   174 CPLEX is not found, then CPLEX support will be disabled.
   175 
   176 \verbatim
   177 --with-cplex-includedir=DIR
   178 \endverbatim
   179 The directory where the CPLEX header files are located. This is only useful
   180 when the CPLEX headers and libraries are not under the same prefix.
   181 
   182 \verbatim
   183 --with-cplex-libdir=DIR
   184 \endverbatim
   185 The directory where the CPLEX libraries are located. This is only useful when
   186 the CPLEX headers and libraries are not under the same prefix.
   187 
   188 \verbatim
   189 --without-cplex
   190 \endverbatim
   191 Disable CPLEX support.
   192 
   193 \verbatim 
   194 --with-soplex[=PREFIX] 
   195 \endverbatim 
   196 Enable SoPlex support (default). You should specify the prefix too if
   197 you installed it to some non-standard location. If SoPlex is not
   198 found, then SoPlex support will be disabled.
   199 
   200 \verbatim
   201 --with-soplex-includedir=DIR
   202 \endverbatim
   203 The directory where the SoPlex header files are located. This is only useful
   204 when the SoPlex headers and libraries are not under the same prefix.
   205 
   206 \verbatim
   207 --with-soplex-libdir=DIR
   208 \endverbatim
   209 The directory where the SoPlex libraries are located. This is only useful when
   210 the SoPlex headers and libraries are not under the same prefix.
   211 
   212 \verbatim
   213 --without-soplex
   214 \endverbatim
   215 Disable SoPlex support.
   216 
   217 
   218 \section svnCheckout How to checkout LEMON form our Subversion repository
   219 
   220 You can obtain the latest version of LEMON from our Subversion repository. To
   221 do this issue the following command:
   222 \verbatim
   223 svn co https://lemon.cs.elte.hu/svn/lemon/trunk lemon-src
   224 \endverbatim
   225 Use "lemon" as username, the password is empty.
   226 
   227 
   228 \section svnCompile How to compile the source from the repository
   229 
   230 You can compile the code from the repository similarly to the packaged
   231 version, but you will need to run \c autoreconf \c -vi or 
   232 <tt>./bootstrap</tt> in some older environment before <tt>./configure</tt>. See \c
   233 ./configure \c --help for options. For bootstrapping you will need the
   234 following tools:
   235 
   236  - <a href="http://www.gnu.org/software/automake/">automake</a> (1.7 or newer)
   237  - <a href="http://www.gnu.org/software/autoconf/">autoconf</a> (2.59 or newer)
   238  - <a href="http://www.gnu.org/software/libtool/">libtool</a>
   239  - <a href="http://pkgconfig.freedesktop.org/">pkgconfig</a>
   240 
   241 To generate the documentation, run \c make \c doc. You will need
   242 <a href="http://www.doxygen.org/">Doxygen</a> for this.
   243 
   244 You can pass the \c --enable-doc=full flag to <tt>./configure</tt> to generate the
   245 internal documentation too.
   246 
   247 If you pass the \c --disable-doc flag to <tt>./configure</tt> then the documentation
   248 won't be installed, when you run \c make \c install (this speeds things up a
   249 bit).
   250 
   251 \section helloworld My first program using LEMON
   252 
   253 If you have installed LEMON on your system you can paste the
   254 following code segment into a file (you can find it as \c
   255 demo/hello_lemon.cc in the LEMON package) to have a first working
   256 program that uses library LEMON.
   257 
   258 \dontinclude hello_lemon.cc
   259 \skip include
   260 \until }
   261 
   262 First let us briefly explain how this program works.
   263 
   264 ListGraph is one of LEMON's graph classes. It is based on linked lists,
   265 therefore iterating throuh its edges and nodes is fast.
   266 
   267 After some convenience typedefs we create a graph and add three nodes to it.
   268 Then we add edges to it to form a complete graph.
   269 
   270 Then we iterate through all nodes of the graph. We use a constructor of the
   271 node iterator to initialize it to the first node. The operator++ is used to
   272 step to the next node. Using operator++ on the iterator pointing to the last
   273 node invalidates the iterator i.e. sets its value to
   274 \ref lemon::INVALID "INVALID". This is what we exploit in the stop condition.
   275 
   276 We can also iterate through all edges of the graph very similarly. The 
   277 \c target and
   278 \c source member functions can be used to access the endpoints of an edge.
   279 
   280 If your installation of LEMON into directory \c /usr/local was
   281 successful, then it is very easy to compile this program with the
   282 following command (the argument <tt>-lemon</tt> tells the compiler
   283 that we are using the installed library LEMON):
   284 
   285 \verbatim
   286 g++ hello_lemon.cc -o hello_lemon -lemon
   287 \endverbatim
   288 
   289 As a result you will get the exacutable \c hello_lemon in
   290 this directory that you can run by the command 
   291 \verbatim
   292 ./hello_lemon
   293 \endverbatim
   294 
   295 
   296 If everything has gone well then the previous code fragment prints
   297 out the following:
   298 
   299 \verbatim
   300 Nodes: 2 1 0
   301 
   302 Edges: (0,2) (1,2) (0,1) (2,1) (1,0) (2,0)
   303 \endverbatim
   304 
   305 Congratulations!
   306 
   307 If you want to see more features, go to the
   308 \ref quicktour "Quick Tour to LEMON",
   309 if you want to see some demo programs then go to our 
   310 \ref demoprograms "Demo Programs" page! 
   311 
   312 
   313 */