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