[2391] | 1 | /* -*- C++ -*- |
---|
| 2 | * |
---|
| 3 | * This file is a part of LEMON, a generic C++ optimization library |
---|
| 4 | * |
---|
| 5 | * Copyright (C) 2003-2007 |
---|
| 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 | |
---|
[1173] | 19 | /** |
---|
| 20 | \page getstart How to start using LEMON |
---|
| 21 | |
---|
[1519] | 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 |
---|
[2167] | 27 | difficulties don't hesitate to <a href="mailto:etik-ol@cs.elte.hu">ask</a>. |
---|
[1175] | 28 | |
---|
[1637] | 29 | |
---|
[1514] | 30 | \section requirementsLEMON Hardware and software requirements |
---|
[1175] | 31 | |
---|
[1519] | 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. |
---|
[1514] | 35 | |
---|
[1519] | 36 | You will need a recent C++ compiler. Our primary target is the GNU C++ |
---|
[1637] | 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 |
---|
[1519] | 39 | work (but not the earlier versions). If you want to develop with LEMON |
---|
| 40 | under Windows you could consider using Cygwin. |
---|
[1514] | 41 | |
---|
[1637] | 42 | In this description we will suppose a Linux environment and GNU C++ Compiler. |
---|
[1514] | 43 | |
---|
[1637] | 44 | |
---|
| 45 | \subsection requirementsLP LP solver requirements |
---|
| 46 | |
---|
| 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 |
---|
| 50 | compile time. |
---|
| 51 | |
---|
| 52 | |
---|
[1173] | 53 | \section downloadLEMON How to download LEMON |
---|
| 54 | |
---|
[1511] | 55 | You can download LEMON from the LEMON web site: |
---|
[1637] | 56 | http://lemon.cs.elte.hu/download.html . |
---|
[1519] | 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. |
---|
[1514] | 62 | |
---|
[1175] | 63 | |
---|
[1173] | 64 | \section installLEMON How to install LEMON |
---|
| 65 | |
---|
[1528] | 66 | In order to install LEMON you have to do the following steps. |
---|
[1173] | 67 | |
---|
[1519] | 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 |
---|
| 71 | commands: |
---|
[1511] | 72 | |
---|
[1519] | 73 | \verbatim |
---|
[1511] | 74 | tar xvzf lemon-0.3.1.tar.gz |
---|
| 75 | cd lemon-0.3.1 |
---|
| 76 | ./configure |
---|
| 77 | make |
---|
[1528] | 78 | make check #(This is optional, but recommended. It runs a bunch of tests.) |
---|
[1511] | 79 | make install |
---|
[1519] | 80 | \endverbatim |
---|
[1511] | 81 | |
---|
[1519] | 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 |
---|
[1528] | 85 | pass the \c --prefix=DIRECTORY flag to \c ./configure, for example: |
---|
| 86 | |
---|
| 87 | \verbatim |
---|
[2167] | 88 | ./configure --prefix=/home/username/lemon |
---|
[1528] | 89 | \endverbatim |
---|
| 90 | |
---|
| 91 | In what follows we will assume that you were able to install to directory |
---|
[1519] | 92 | \c /usr/local, otherwise some extra care is to be taken to use the |
---|
| 93 | library. |
---|
[1511] | 94 | |
---|
[1514] | 95 | We briefly explain these commands below. |
---|
| 96 | |
---|
[1519] | 97 | \verbatim |
---|
[1514] | 98 | tar xvzf lemon-0.3.1.tar.gz |
---|
[1519] | 99 | \endverbatim |
---|
| 100 | This command untars the <tt>tar.gz</tt> file into a directory named <tt> |
---|
| 101 | lemon-0.3.1</tt>. |
---|
[1514] | 102 | |
---|
[1519] | 103 | \verbatim |
---|
[1514] | 104 | cd lemon-0.3.1 |
---|
[1519] | 105 | \endverbatim |
---|
[1514] | 106 | Enters the directory. |
---|
| 107 | |
---|
[1519] | 108 | \verbatim |
---|
[1514] | 109 | ./configure |
---|
[1519] | 110 | \endverbatim |
---|
[1514] | 111 | Does some configuration (creates makefiles etc). |
---|
| 112 | |
---|
[1519] | 113 | \verbatim |
---|
[1514] | 114 | make |
---|
[1519] | 115 | \endverbatim |
---|
| 116 | This command compiles the non-template part of LEMON into |
---|
| 117 | <b>libemon.a</b> file. It also compiles some benchmark and demo |
---|
| 118 | programs. |
---|
[1514] | 119 | |
---|
[1519] | 120 | \verbatim |
---|
| 121 | make check |
---|
| 122 | \endverbatim |
---|
| 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 |
---|
| 125 | your platform. |
---|
[1514] | 126 | |
---|
[1519] | 127 | \verbatim |
---|
[1514] | 128 | make install |
---|
[1519] | 129 | \endverbatim |
---|
[1514] | 130 | This will copy the directory structure to its final destination (e.g. to \c |
---|
[1519] | 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 |
---|
[1637] | 133 | the \c configure to install the library in non-default location. |
---|
| 134 | |
---|
| 135 | |
---|
| 136 | \subsection configureFlags Configure flags |
---|
| 137 | |
---|
| 138 | You can pass the following flags to \c ./configure (see \c ./configure --help |
---|
| 139 | for more): |
---|
| 140 | |
---|
| 141 | \verbatim |
---|
| 142 | --with-glpk[=PREFIX] |
---|
| 143 | \endverbatim |
---|
| 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. |
---|
| 147 | |
---|
| 148 | \verbatim |
---|
| 149 | --with-glpk-includedir=DIR |
---|
| 150 | \endverbatim |
---|
| 151 | The directory where the GLPK header files are located. This is only useful when |
---|
[1713] | 152 | the GLPK headers and libraries are not under the same prefix (which is |
---|
| 153 | unlikely). |
---|
[1637] | 154 | |
---|
| 155 | \verbatim |
---|
| 156 | --with-glpk-libdir=DIR |
---|
| 157 | \endverbatim |
---|
| 158 | The directory where the GLPK libraries are located. This is only useful when |
---|
[1713] | 159 | the GLPK headers and libraries are not under the same prefix (which is |
---|
| 160 | unlikely). |
---|
[1637] | 161 | |
---|
| 162 | \verbatim |
---|
| 163 | --without-glpk |
---|
| 164 | \endverbatim |
---|
| 165 | Disable GLPK support. |
---|
| 166 | |
---|
| 167 | \verbatim |
---|
| 168 | --with-cplex[=PREFIX] |
---|
| 169 | \endverbatim |
---|
| 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. |
---|
| 173 | |
---|
| 174 | \verbatim |
---|
| 175 | --with-cplex-includedir=DIR |
---|
| 176 | \endverbatim |
---|
| 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. |
---|
| 179 | |
---|
| 180 | \verbatim |
---|
| 181 | --with-cplex-libdir=DIR |
---|
| 182 | \endverbatim |
---|
| 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. |
---|
| 185 | |
---|
| 186 | \verbatim |
---|
| 187 | --without-cplex |
---|
| 188 | \endverbatim |
---|
| 189 | Disable CPLEX support. |
---|
| 190 | |
---|
| 191 | |
---|
| 192 | \section svnCheckout How to checkout LEMON form our Subversion repository |
---|
| 193 | |
---|
| 194 | You can obtain the latest version of LEMON from our Subversion repository. To |
---|
| 195 | do this issue the following command: |
---|
| 196 | \verbatim |
---|
| 197 | svn co https://lemon.cs.elte.hu/svn/hugo/trunk lemon |
---|
| 198 | \endverbatim |
---|
| 199 | Use "lemon" as username, the password is empty. |
---|
| 200 | |
---|
| 201 | |
---|
| 202 | \section svnCompile How to compile the source from the repository |
---|
| 203 | |
---|
| 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 |
---|
| 207 | following tools: |
---|
| 208 | |
---|
| 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> |
---|
| 213 | |
---|
| 214 | To generate the documentation, run \c make \c doc. You will need |
---|
| 215 | <a href="http://www.doxygen.org/">Doxygen</a> for this. |
---|
| 216 | |
---|
| 217 | You can pass the \c --enable-doc=full flag to \c ./configure to generate the |
---|
| 218 | internal documentation too. |
---|
| 219 | |
---|
| 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 |
---|
| 222 | bit). |
---|
[1175] | 223 | |
---|
[1173] | 224 | \section helloworld My first program using LEMON |
---|
| 225 | |
---|
[1519] | 226 | If you have installed LEMON on your system you can paste the |
---|
[1520] | 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. |
---|
[1173] | 230 | |
---|
[1640] | 231 | \dontinclude hello_lemon.cc |
---|
| 232 | \skip include |
---|
| 233 | \until } |
---|
[1175] | 234 | |
---|
[1514] | 235 | First let us briefly explain how this program works. |
---|
[1175] | 236 | |
---|
| 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. |
---|
| 239 | |
---|
[1713] | 240 | After some convenience typedefs we create a graph and add three nodes to it. |
---|
[1175] | 241 | Then we add edges to it to form a complete graph. |
---|
| 242 | |
---|
| 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. |
---|
| 248 | |
---|
| 249 | We can also iterate through all edges of the graph very similarly. The |
---|
| 250 | \c target and |
---|
| 251 | \c source member functions can be used to access the endpoints of an edge. |
---|
| 252 | |
---|
[1520] | 253 | If your installation of LEMON into directory \c /usr/local was |
---|
[1713] | 254 | successful, then it is very easy to compile this program with the |
---|
[1520] | 255 | following command (the argument <tt>-lemon</tt> tells the compiler |
---|
| 256 | that we are using the installed library LEMON): |
---|
[1514] | 257 | |
---|
[1519] | 258 | \verbatim |
---|
| 259 | g++ hello_lemon.cc -o hello_lemon -lemon |
---|
| 260 | \endverbatim |
---|
| 261 | |
---|
| 262 | As a result you will get the exacutable \c hello_lemon in |
---|
[1514] | 263 | this directory that you can run by the command |
---|
[1519] | 264 | \verbatim |
---|
| 265 | ./hello_lemon |
---|
| 266 | \endverbatim |
---|
[1514] | 267 | |
---|
| 268 | |
---|
[1519] | 269 | If everything has gone well then the previous code fragment prints |
---|
| 270 | out the following: |
---|
[1175] | 271 | |
---|
[1519] | 272 | \verbatim |
---|
[1175] | 273 | Nodes: 2 1 0 |
---|
| 274 | |
---|
| 275 | Edges: (0,2) (1,2) (0,1) (2,1) (1,0) (2,0) |
---|
[1519] | 276 | \endverbatim |
---|
[1175] | 277 | |
---|
[1514] | 278 | Congratulations! |
---|
[1175] | 279 | |
---|
[1519] | 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 |
---|
[1175] | 283 | \ref demoprograms "Demo Programs" page! |
---|
| 284 | |
---|
| 285 | |
---|
| 286 | */ |
---|