3 * This file is a part of LEMON, a generic C++ optimization library
5 * Copyright (C) 2003-2007
6 * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
7 * (Egervary Research Group on Combinatorial Optimization, EGRES).
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.
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
20 \page getstart How to start using LEMON
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 <a href="mailto:etik-ol@cs.elte.hu">ask</a>.
30 \section requirementsLEMON Hardware and software requirements
32 In LEMON we use C++ templates heavily, thus compilation takes a
33 considerable amount of time and memory. So some decent box would be
34 advantageous. But otherwise there are no special hardware requirements.
36 You will need a recent C++ compiler. Our primary target is the GNU C++
37 Compiler (g++), from version 3.3 upwards. We also checked the Intel C++
38 Compiler (icc). Microsoft Visual C++ .NET 2003 was also reported to
39 work (but not the earlier versions). If you want to develop with LEMON
40 under Windows you could consider using Cygwin.
42 In this description we will suppose a Linux environment and GNU C++ Compiler.
45 \subsection requirementsLP LP solver requirements
47 The LEMON LP solver interface can use the GLPK (GNU Linear Programming Kit)
48 and CPLEX solvers (was tested with CPLEX 7.5). If you want to use it you will
49 need at least one of these. See \ref configureFlags how to enable these at
53 \section downloadLEMON How to download LEMON
55 You can download LEMON from the LEMON web site:
56 http://lemon.cs.elte.hu/download.html .
57 There you will find released versions in form of <tt>.tar.gz</tt> files.
58 If you want a developer version (for example you want to contribute in
59 developing the library LEMON) then you might want to use our Subversion
60 repository. This case is not detailed here, so from now on we suppose that
61 you downloaded a tar.gz file.
64 \section installLEMON How to install LEMON
66 In order to install LEMON you have to do the following steps.
68 Download the tarball (named <tt>lemon-x.y.z.tar.gz</tt> where \c x,\c y
69 and \c z are numbers indicating the version of the library: in our example
70 we will have <tt>lemon-0.3.1.tar.gz</tt>) and issue the following
74 tar xvzf lemon-0.3.1.tar.gz
78 make check #(This is optional, but recommended. It runs a bunch of tests.)
82 These commands install LEMON under \c /usr/local (you will
83 need root privileges to be able to install to that
84 directory). If you want to install it to some other place, then
85 pass the \c --prefix=DIRECTORY flag to \c ./configure, for example:
88 ./configure --prefix=/home/username/lemon
91 In what follows we will assume that you were able to install to directory
92 \c /usr/local, otherwise some extra care is to be taken to use the
95 We briefly explain these commands below.
98 tar xvzf lemon-0.3.1.tar.gz
100 This command untars the <tt>tar.gz</tt> file into a directory named <tt>
106 Enters the directory.
111 Does some configuration (creates makefiles etc).
116 This command compiles the non-template part of LEMON into
117 <b>libemon.a</b> file. It also compiles some benchmark and demo
123 This is an optional step: it runs the test programs that we
124 developed for LEMON to check whether the library works properly on
130 This will copy the directory structure to its final destination (e.g. to \c
131 /usr/local) so that your system can access it. This command should
132 be issued as "root", unless you provided a \c --prefix switch to
133 the \c configure to install the library in non-default location.
136 \subsection configureFlags Configure flags
138 You can pass the following flags to \c ./configure (see \c ./configure --help
144 Enable GLPK support (default). You should specify the prefix too if you
145 installed it to some non-standard location (e.g. your home directory). If
146 GLPK is not found, then GLPK support will be disabled.
149 --with-glpk-includedir=DIR
151 The directory where the GLPK header files are located. This is only useful when
152 the GLPK headers and libraries are not under the same prefix (which is
156 --with-glpk-libdir=DIR
158 The directory where the GLPK libraries are located. This is only useful when
159 the GLPK headers and libraries are not under the same prefix (which is
165 Disable GLPK support.
168 --with-cplex[=PREFIX]
170 Enable CPLEX support (default). You should specify the prefix too if you
171 installed it to some non-standard location (e.g. \c /opt/ilog/cplex75). If
172 CPLEX is not found, then CPLEX support will be disabled.
175 --with-cplex-includedir=DIR
177 The directory where the CPLEX header files are located. This is only useful
178 when the CPLEX headers and libraries are not under the same prefix.
181 --with-cplex-libdir=DIR
183 The directory where the CPLEX libraries are located. This is only useful when
184 the CPLEX headers and libraries are not under the same prefix.
189 Disable CPLEX support.
192 \section svnCheckout How to checkout LEMON form our Subversion repository
194 You can obtain the latest version of LEMON from our Subversion repository. To
195 do this issue the following command:
197 svn co https://lemon.cs.elte.hu/svn/hugo/trunk lemon
199 Use "lemon" as username, the password is empty.
202 \section svnCompile How to compile the source from the repository
204 You can compile the code from the repository similarly to the packaged version,
205 but you will need to run \c ./bootstrap before \c ./configure. See \c
206 ./bootstrap \c --help for options. For bootstrapping you will need the
209 - <a href="http://www.gnu.org/software/automake/">automake</a> (1.7 or newer)
210 - <a href="http://www.gnu.org/software/autoconf/">autoconf</a> (2.59 or newer)
211 - <a href="http://www.gnu.org/software/libtool/">libtool</a>
212 - <a href="http://pkgconfig.freedesktop.org/">pkgconfig</a>
214 To generate the documentation, run \c make \c doc. You will need
215 <a href="http://www.doxygen.org/">Doxygen</a> for this.
217 You can pass the \c --enable-doc=full flag to \c ./configure to generate the
218 internal documentation too.
220 If you pass the \c --disable-doc flag to \c ./configure then the documentation
221 won't be installed, when you run \c make \c install (this speeds things up a
224 \section helloworld My first program using LEMON
226 If you have installed LEMON on your system you can paste the
227 following code segment into a file (you can find it as \c
228 demo/hello_lemon.cc in the LEMON package) to have a first working
229 program that uses library LEMON.
231 \dontinclude hello_lemon.cc
235 First let us briefly explain how this program works.
237 ListGraph is one of LEMON's graph classes. It is based on linked lists,
238 therefore iterating throuh its edges and nodes is fast.
240 After some convenience typedefs we create a graph and add three nodes to it.
241 Then we add edges to it to form a complete graph.
243 Then we iterate through all nodes of the graph. We use a constructor of the
244 node iterator to initialize it to the first node. The operator++ is used to
245 step to the next node. Using operator++ on the iterator pointing to the last
246 node invalidates the iterator i.e. sets its value to
247 \ref lemon::INVALID "INVALID". This is what we exploit in the stop condition.
249 We can also iterate through all edges of the graph very similarly. The
251 \c source member functions can be used to access the endpoints of an edge.
253 If your installation of LEMON into directory \c /usr/local was
254 successful, then it is very easy to compile this program with the
255 following command (the argument <tt>-lemon</tt> tells the compiler
256 that we are using the installed library LEMON):
259 g++ hello_lemon.cc -o hello_lemon -lemon
262 As a result you will get the exacutable \c hello_lemon in
263 this directory that you can run by the command
269 If everything has gone well then the previous code fragment prints
275 Edges: (0,2) (1,2) (0,1) (2,1) (1,0) (2,0)
280 If you want to see more features, go to the
281 \ref quicktour "Quick Tour to LEMON",
282 if you want to see see some demo programs then go to our
283 \ref demoprograms "Demo Programs" page!