[3] | 1 | /* -*- mode: C++; indent-tabs-mode: nil; -*- |
---|
| 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 | /** |
---|
[6] | 20 | \page getting_started Getting Started |
---|
[3] | 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++ programming |
---|
| 26 | language. The procedure is pretty straightforward, but if you have any |
---|
[6] | 27 | difficulties do not hesitate to |
---|
[3] | 28 | <a href="mailto:lemon-user@lemon.cs.elte.hu"><b>ask</b></a>. |
---|
| 29 | |
---|
| 30 | \section requirements_lemon Hardware and Software Requirements |
---|
| 31 | |
---|
| 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 |
---|
[6] | 34 | advantageousm, but otherwise there are no special hardware requirements. |
---|
[3] | 35 | |
---|
| 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++ |
---|
[6] | 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. |
---|
[3] | 41 | |
---|
| 42 | In this description we will suppose a Linux environment and GNU C++ Compiler. |
---|
[6] | 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 |
---|
| 47 | with your compiler. |
---|
[3] | 48 | |
---|
| 49 | \subsection requirements_lp LP Solver Requirements |
---|
| 50 | |
---|
| 51 | The LEMON LP solver interface can use the GLPK (GNU Linear Programming |
---|
[6] | 52 | Kit), CPLEX and SoPlex solver. If you want to use it, you will need at |
---|
| 53 | least one of these. |
---|
| 54 | See the <b><tt>INSTALL</tt></b> file how to enable these at compile time. |
---|
[3] | 55 | |
---|
| 56 | \section download_lemon How to Download LEMON |
---|
| 57 | |
---|
[6] | 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). |
---|
[3] | 62 | If you want a developer version (for example you want to contribute in |
---|
[6] | 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. |
---|
[3] | 66 | |
---|
| 67 | \section install_lemon How to Install LEMON |
---|
| 68 | |
---|
| 69 | In order to install LEMON you have to do the following steps. |
---|
| 70 | |
---|
| 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: |
---|
| 74 | |
---|
| 75 | \verbatim |
---|
| 76 | tar xvzf lemon-1.0.tar.gz |
---|
| 77 | cd lemon-1.0 |
---|
| 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 library. |
---|
| 95 | |
---|
| 96 | We briefly explain these commands below. |
---|
| 97 | |
---|
| 98 | \verbatim |
---|
| 99 | tar xvzf lemon-1.0.tar.gz |
---|
| 100 | \endverbatim |
---|
| 101 | This command untars the <tt>tar.gz</tt> file into a directory named |
---|
| 102 | <tt>lemon-1.0</tt>. |
---|
| 103 | |
---|
| 104 | \verbatim |
---|
| 105 | cd lemon-1.0 |
---|
| 106 | \endverbatim |
---|
| 107 | This command enters the directory. |
---|
| 108 | |
---|
| 109 | \verbatim |
---|
| 110 | ./configure |
---|
| 111 | \endverbatim |
---|
| 112 | This command runs the configure shell script, which does some checks and |
---|
| 113 | creates the makefiles. |
---|
| 114 | |
---|
| 115 | \verbatim |
---|
| 116 | make |
---|
| 117 | \endverbatim |
---|
| 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 |
---|
| 120 | when enabled. |
---|
| 121 | |
---|
| 122 | \verbatim |
---|
| 123 | make check |
---|
| 124 | \endverbatim |
---|
| 125 | This step is optional, but recommended. It runs the test programs that |
---|
[6] | 126 | have been developed for LEMON to check whether the library works properly on |
---|
[3] | 127 | your platform. |
---|
| 128 | |
---|
| 129 | \verbatim |
---|
| 130 | make install |
---|
| 131 | \endverbatim |
---|
| 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. |
---|
| 137 | |
---|
| 138 | Several other configure flags can be passed to <tt>./configure</tt>. |
---|
[6] | 139 | For more information see the <b><tt>INSTALL</tt></b> file. |
---|
[3] | 140 | |
---|
| 141 | \section hg_checkout How to Checkout LEMON from our Mercurial Repository |
---|
| 142 | |
---|
[6] | 143 | You can obtain the latest (developer) version of LEMON from our Mercurial |
---|
| 144 | repository. To do this issue the following command. |
---|
[3] | 145 | \verbatim |
---|
[6] | 146 | hg clone http://lemon.cs.elte.hu/hg/lemon-main lemon-src |
---|
[3] | 147 | \endverbatim |
---|
| 148 | |
---|
| 149 | \section hg_compile How to Compile the Source from the Repository |
---|
| 150 | |
---|
| 151 | You can compile the code from the repository similarly to the packaged |
---|
[6] | 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 |
---|
[3] | 154 | <tt>./configure</tt>. See <tt>./configure --help</tt> for options. |
---|
| 155 | For bootstrapping you will need the following tools: |
---|
| 156 | |
---|
| 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> |
---|
| 161 | |
---|
| 162 | To generate the documentation, run <tt>make html</tt>. |
---|
| 163 | You will need <a href="http://www.doxygen.org/">Doxygen</a> for this. |
---|
| 164 | |
---|
[6] | 165 | \section hello_lemon Compile Your First Code |
---|
| 166 | |
---|
| 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. |
---|
| 170 | |
---|
| 171 | \dontinclude hello_lemon.cc |
---|
| 172 | \skip #include |
---|
| 173 | \until } |
---|
| 174 | |
---|
| 175 | First let us briefly explain how this example program works. |
---|
| 176 | (The used notions will be discussed in detail in the following chapter.) |
---|
| 177 | |
---|
| 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 |
---|
| 182 | arcs is fast. |
---|
| 183 | |
---|
| 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 |
---|
| 186 | first node. |
---|
| 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. |
---|
| 193 | |
---|
| 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. |
---|
| 197 | |
---|
| 198 | Now let's compile this simple example program. |
---|
| 199 | |
---|
| 200 | \subsection hello_lemon_system If LEMON is Installed System-Wide |
---|
| 201 | |
---|
| 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): |
---|
| 206 | |
---|
| 207 | \verbatim |
---|
| 208 | g++ hello_lemon.cc -o hello_lemon -lemon |
---|
| 209 | \endverbatim |
---|
| 210 | |
---|
| 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. |
---|
| 213 | |
---|
| 214 | \verbatim |
---|
| 215 | ./hello_lemon |
---|
| 216 | \endverbatim |
---|
| 217 | |
---|
| 218 | \subsection hello_lemon_user If LEMON is Installed User-Local |
---|
| 219 | |
---|
| 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. |
---|
| 224 | |
---|
| 225 | \verbatim |
---|
| 226 | g++ -I ~/lemon hello_lemon.cc -o hello_lemon -lemon -L ~/lemon/lemon/.libs |
---|
| 227 | \endverbatim |
---|
| 228 | |
---|
| 229 | \subsubsection hello_lemon_pkg_config Use pkg-config |
---|
| 230 | |
---|
| 231 | \todo Write this sub-subsection (\ref hello_lemon_pkg_config). |
---|
| 232 | |
---|
| 233 | If everything has gone well, then our program prints out the followings. |
---|
| 234 | |
---|
| 235 | \verbatim |
---|
| 236 | Hello World! |
---|
| 237 | This is LEMON library here. We have a direceted graph. |
---|
| 238 | |
---|
| 239 | Nodes: 3 2 1 0 |
---|
| 240 | Arcs: (2,3) (1,3) (1,2) (0,2) (0,1) |
---|
| 241 | |
---|
| 242 | There is a map on the arcs (length): |
---|
| 243 | |
---|
| 244 | length(2,3)=10 |
---|
| 245 | length(1,3)=25 |
---|
| 246 | length(1,2)=5 |
---|
| 247 | length(0,2)=20 |
---|
| 248 | length(0,1)=10 |
---|
| 249 | \endverbatim |
---|
| 250 | |
---|
| 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 |
---|
| 253 | order). |
---|
| 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. |
---|
| 258 | |
---|
| 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 |
---|
| 261 | of LEMON. |
---|
| 262 | Otherwise if you encountered problems that you did not manage to solve, |
---|
| 263 | do not hesitate to |
---|
| 264 | <a href="mailto:lemon-user@lemon.cs.elte.hu"><b>contact us</b></a>. |
---|
| 265 | |
---|
[3] | 266 | */ |
---|