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