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