1 /* -*- mode: C++; indent-tabs-mode: nil; -*-
3 * This file is a part of LEMON, a generic C++ optimization library.
5 * Copyright (C) 2003-2008
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 getting_started Getting Started
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++ programming
26 language. The procedure is pretty straightforward, but if you have any
27 difficulties do not hesitate to
28 <a href="mailto:lemon-user@lemon.cs.elte.hu"><b>ask</b></a>.
30 \section requirements_lemon 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 advantageousm, 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) and Microsoft Visual C++ (on Windows).
39 If you want to develop with LEMON under Windows, you can use a Windows
40 installer or you can consider using Cygwin.
42 In this description we will suppose a Linux environment and GNU C++ Compiler.
43 If you would like to develop under Windows and use a Windows installer,
44 you could skip the following sections and continue reading \ref hello_lemon.
45 However keep in mind that you have to make appropriate steps instead of
46 the instructions detailed here to be able to compile the example code
49 \subsection requirements_lp LP Solver Requirements
51 The LEMON LP solver interface can use the GLPK (GNU Linear Programming
52 Kit), CPLEX and SoPlex solver. If you want to use it, you will need at
54 See the <b><tt>INSTALL</tt></b> file how to enable these at compile time.
56 \section download_lemon How to Download LEMON
58 You can download LEMON from our web site:
59 <a href="http://lemon.cs.elte.hu/">http://lemon.cs.elte.hu/</a>.
60 There you will find released versions in form of <tt>.tar.gz</tt> files
61 (and Windows installers).
62 If you want a developer version (for example you want to contribute in
63 developing LEMON) then you might want to use our Mercurial repository.
64 This case is detailed \ref hg_checkout "later", so from now on we
65 suppose that you downloaded a <tt>.tar.gz</tt> file.
67 \section install_lemon How to Install LEMON
69 In order to install LEMON you have to do the following steps.
71 Download the tarball (named <tt>lemon-x.y.z.tar.gz</tt> where \c x, \c y
72 and \c z are numbers indicating the version of the library, in our example
73 we will have <tt>lemon-1.0.tar.gz</tt>) and issue the following commands:
76 tar xvzf lemon-1.0.tar.gz
80 make check # This is optional, but recommended. It runs a bunch of tests.
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:
90 ./configure --prefix=/home/username/lemon
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 library.
96 We briefly explain these commands below.
99 tar xvzf lemon-1.0.tar.gz
101 This command untars the <tt>tar.gz</tt> file into a directory named
107 This command enters the directory.
112 This command runs the configure shell script, which does some checks and
113 creates the makefiles.
118 This command compiles the non-template part of LEMON into <tt>libemon.a</tt>
119 file. It also compiles the programs in the tools and demo subdirectories
125 This step is optional, but recommended. It runs the test programs that
126 have been developed for LEMON to check whether the library works properly on
132 This command will copy the directory structure to its final destination
133 (e.g. to \c /usr/local) so that your system can access it.
134 This command should be issued as "root", unless you provided a
135 \c --prefix switch to the \c configure to install the library in
136 non-default location.
138 Several other configure flags can be passed to <tt>./configure</tt>.
139 For more information see the <b><tt>INSTALL</tt></b> file.
141 \section hg_checkout How to Checkout LEMON from our Mercurial Repository
143 You can obtain the latest (developer) version of LEMON from our Mercurial
144 repository. To do this issue the following command.
146 hg clone http://lemon.cs.elte.hu/hg/lemon-main lemon-src
149 \section hg_compile How to Compile the Source from the Repository
151 You can compile the code from the repository similarly to the packaged
152 version, but you will need to run <b><tt>autoreconf -vif</tt></b>
153 (or <b><tt>./bootstrap</tt></b> in some older environment) before
154 <tt>./configure</tt>. See <tt>./configure --help</tt> for options.
155 For bootstrapping you will need the following tools:
157 - <a href="http://www.gnu.org/software/automake/">automake</a> (1.7 or newer)
158 - <a href="http://www.gnu.org/software/autoconf/">autoconf</a> (2.59 or newer)
159 - <a href="http://www.gnu.org/software/libtool/">libtool</a>
160 - <a href="http://pkgconfig.freedesktop.org/">pkgconfig</a>
162 To generate the documentation, run <tt>make html</tt>.
163 You will need <a href="http://www.doxygen.org/">Doxygen</a> for this.
165 \section hello_lemon Compile Your First Code
167 If you have installed LEMON on your system you can paste the following
168 code segment into a file called <tt>hello_lemon.cc</tt> to have a first
169 working program that uses LEMON.
171 \dontinclude hello_lemon.cc
175 First let us briefly explain how this example program works.
176 (The used notions will be discussed in detail in the following chapter.)
178 After some convenience typedefs we create a directed graph (\e digraph)
179 and add some nodes and arcs to it.
180 ListDigraph is one of the digraph classes implemented in LEMON.
181 It is based on linked lists, therefore iterating through its nodes and
184 Then we iterate through all nodes of the digraph and print their unique
185 IDs. We use a constructor of the node iterator to initialize it to the
187 The <tt>operator++</tt> is used to step to the next node. After the last
188 node the iterator becomes invalid (i.e. it is set to \c INVALID).
189 This is what we exploit in the stop condition.
190 We iterate through all arcs of the digraph very similarly and print the
191 IDs of their source (tail) and target (head) nodes using the \c source()
192 and \c target() member functions.
194 After that we create an arc map, which is actually a mapping that assigns
195 an \c int value (length) to each arc, and we set this value for each arc.
196 Finally we iterate through all arcs again and print their lengths.
198 Now let's compile this simple example program.
200 \subsection hello_lemon_system If LEMON is Installed System-Wide
202 If your installation of LEMON into directory \c /usr/local was
203 successful, then it is very easy to compile this program with the
204 following command (the argument <tt>-lemon</tt> tells the compiler
205 that we are using the installed LEMON):
208 g++ hello_lemon.cc -o hello_lemon -lemon
211 As a result you will get the exacutable \c hello_lemon in the current
212 directory, which you can run by the following command.
218 \subsection hello_lemon_user If LEMON is Installed User-Local
220 Compiling the code is a bit more difficult if you installed LEMON
221 user-local into a directory (e.g. <tt>~/lemon</tt>) or if you just
222 skipped the step <tt>make install</tt>.
223 You have to issue a command like this.
226 g++ -I ~/lemon hello_lemon.cc -o hello_lemon -lemon -L ~/lemon/lemon/.libs
229 \subsubsection hello_lemon_pkg_config Use pkg-config
231 \todo Write this sub-subsection (\ref hello_lemon_pkg_config).
233 If everything has gone well, then our program prints out the followings.
237 This is LEMON library here. We have a direceted graph.
240 Arcs: (2,3) (1,3) (1,2) (0,2) (0,1)
242 There is a map on the arcs (length):
251 You may note that iterating through the nodes and arcs is done in the
252 reverse order compared to the creating order (the IDs are in decreasing
254 This is due to implementation aspects, that may differ at other graph
255 types, moreover it may be changed in the next releases.
256 Thus you should not exploit this method in any way, you should not
257 suppose anything about the iteration order.
259 If you managed to compile and run this example code without any problems,
260 you can go on reading this tutorial to get to know more features and tools
262 Otherwise if you encountered problems that you did not manage to solve,
264 <a href="mailto:lemon-user@lemon.cs.elte.hu"><b>contact us</b></a>.