doc/getstart.dox
author alpar
Tue, 26 Jul 2005 13:15:13 +0000
changeset 1587 8f1c317ebeb4
parent 1520 c2c76e4598f6
child 1637 9d64d5672b88
permissions -rw-r--r--
Doc improvements
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
athos@1514
    12
\section requirementsLEMON Hardware and software requirements
athos@1175
    13
klao@1519
    14
In LEMON we use C++ templates heavily, thus compilation takes a
klao@1519
    15
considerable amount of time and memory. So some decent box would be
klao@1519
    16
advantageous. But otherwise there are no special hardware requirements.
athos@1514
    17
klao@1519
    18
You will need a recent C++ compiler. Our primary target is the GNU C++
klao@1519
    19
Compiler (g++), from version 3.3 upwards. We also checked the Intel C
klao@1519
    20
compiler (icc). Microsoft Visual C++ .NET version was also reported to
klao@1519
    21
work (but not the earlier versions). If you want to develop with LEMON
klao@1519
    22
under Windows you could consider using Cygwin.
athos@1514
    23
athos@1514
    24
klao@1519
    25
In this description we will suppose a linux environment and GNU C Compiler.
athos@1175
    26
athos@1173
    27
\section downloadLEMON How to download LEMON
athos@1173
    28
athos@1511
    29
You can download LEMON from the LEMON web site:
athos@1528
    30
http://lemon.cs.elte.hu/download.html.
klao@1519
    31
There you will find released versions in form of <tt>.tar.gz</tt> files.
klao@1519
    32
If you want a developer version (for example you want to contribute in
klao@1519
    33
developing the library LEMON) then you might want to use our Subversion
klao@1519
    34
repository. This case is not detailed here, so from now on we suppose that
klao@1519
    35
you downloaded a tar.gz file.
athos@1514
    36
athos@1175
    37
athos@1173
    38
athos@1173
    39
\section installLEMON How to install LEMON
athos@1173
    40
athos@1528
    41
In order to install LEMON you have to do the following steps.
athos@1173
    42
klao@1519
    43
Download the tarball (named <tt>lemon-x.y.z.tar.gz</tt> where \c x,\c y
klao@1519
    44
and \c z are numbers indicating the version of the library: in our example
klao@1519
    45
we will have <tt>lemon-0.3.1.tar.gz</tt>) and issue the following
klao@1519
    46
commands:
athos@1511
    47
klao@1519
    48
\verbatim
athos@1511
    49
tar xvzf lemon-0.3.1.tar.gz
athos@1511
    50
cd lemon-0.3.1
athos@1511
    51
./configure
athos@1511
    52
make
athos@1528
    53
make check   #(This is optional, but recommended. It runs a bunch of tests.)
athos@1511
    54
make install
klao@1519
    55
\endverbatim
athos@1511
    56
klao@1519
    57
These commands install LEMON under \c /usr/local (you will
klao@1519
    58
need root privileges to be able to install to that
klao@1519
    59
directory). If you want to install it to some other place, then
athos@1528
    60
pass the \c --prefix=DIRECTORY flag to \c ./configure, for example:
athos@1528
    61
athos@1528
    62
\verbatim
athos@1528
    63
./configure --prefix=/home/user1/lemon
athos@1528
    64
\endverbatim
athos@1528
    65
athos@1528
    66
In what follows we will assume that you were able to install to directory
klao@1519
    67
\c /usr/local, otherwise some extra care is to be taken to use the
klao@1519
    68
library.
athos@1511
    69
athos@1514
    70
We briefly explain these commands below.
athos@1514
    71
klao@1519
    72
\verbatim
athos@1514
    73
tar xvzf lemon-0.3.1.tar.gz
klao@1519
    74
\endverbatim
klao@1519
    75
This command untars the <tt>tar.gz</tt> file into a directory named <tt>
klao@1519
    76
lemon-0.3.1</tt>.
athos@1514
    77
klao@1519
    78
\verbatim
athos@1514
    79
cd lemon-0.3.1
klao@1519
    80
\endverbatim
athos@1514
    81
Enters the directory.
athos@1514
    82
klao@1519
    83
\verbatim
athos@1514
    84
./configure
klao@1519
    85
\endverbatim
athos@1514
    86
Does some configuration (creates makefiles etc).
klao@1519
    87
\todo Explain the most important switches here (gui, doc, glpk, cplex).
athos@1514
    88
klao@1519
    89
\verbatim
athos@1514
    90
make
klao@1519
    91
\endverbatim
klao@1519
    92
This command compiles the non-template part of LEMON into
klao@1519
    93
<b>libemon.a</b> file. It also compiles some benchmark and demo
klao@1519
    94
programs.
athos@1514
    95
klao@1519
    96
\verbatim
klao@1519
    97
make check
klao@1519
    98
\endverbatim
klao@1519
    99
This is an optional step: it runs the test programs that we
klao@1519
   100
developed for LEMON to check whether the library works properly on
klao@1519
   101
your platform.
athos@1514
   102
klao@1519
   103
\verbatim
athos@1514
   104
make install
klao@1519
   105
\endverbatim
athos@1514
   106
This will copy the directory structure to its final destination (e.g. to \c
klao@1519
   107
/usr/local) so that your system can access it. This command should
klao@1519
   108
be issued as "root", unless you provided a \c --prefix switch to
klao@1519
   109
the \c cofugure to install the library in non-default location.
athos@1175
   110
athos@1173
   111
\section helloworld My first program using LEMON
athos@1173
   112
klao@1519
   113
If you have installed LEMON on your system you can paste the
klao@1520
   114
following code segment into a file (you can find it as \c
klao@1520
   115
demo/hello_lemon.cc in the LEMON package) to have a first working
klao@1520
   116
program that uses library LEMON.
athos@1173
   117
klao@1520
   118
\include hello_lemon.cc
athos@1175
   119
athos@1514
   120
First let us briefly explain how this program works.
athos@1175
   121
athos@1175
   122
ListGraph is one of LEMON's graph classes. It is based on linked lists,
athos@1175
   123
therefore iterating throuh its edges and nodes is fast.
athos@1175
   124
athos@1175
   125
After some convenient typedefs we create a graph and add three nodes to it.
athos@1175
   126
Then we add edges to it to form a complete graph.
athos@1175
   127
athos@1175
   128
Then we iterate through all nodes of the graph. We use a constructor of the
athos@1175
   129
node iterator to initialize it to the first node. The operator++ is used to
athos@1175
   130
step to the next node. Using operator++ on the iterator pointing to the last
athos@1175
   131
node invalidates the iterator i.e. sets its value to
athos@1175
   132
\ref lemon::INVALID "INVALID". This is what we exploit in the stop condition.
athos@1175
   133
athos@1175
   134
We can also iterate through all edges of the graph very similarly. The 
athos@1175
   135
\c target and
athos@1175
   136
\c source member functions can be used to access the endpoints of an edge.
athos@1175
   137
klao@1520
   138
If your installation of LEMON into directory \c /usr/local was
klao@1520
   139
successful then it is very easy to compile this program with the
klao@1520
   140
following command (the argument <tt>-lemon</tt> tells the compiler
klao@1520
   141
that we are using the installed library LEMON):
athos@1514
   142
klao@1519
   143
\verbatim
klao@1519
   144
g++ hello_lemon.cc -o hello_lemon -lemon
klao@1519
   145
\endverbatim
klao@1519
   146
klao@1519
   147
As a result you will get the exacutable \c hello_lemon in
athos@1514
   148
this directory that you can run by the command 
klao@1519
   149
\verbatim
klao@1519
   150
./hello_lemon
klao@1519
   151
\endverbatim
athos@1514
   152
athos@1514
   153
klao@1519
   154
If everything has gone well then the previous code fragment prints
klao@1519
   155
out the following:
athos@1175
   156
klao@1519
   157
\verbatim
athos@1175
   158
Nodes: 2 1 0
athos@1175
   159
athos@1175
   160
Edges: (0,2) (1,2) (0,1) (2,1) (1,0) (2,0)
klao@1519
   161
\endverbatim
athos@1175
   162
athos@1514
   163
Congratulations!
athos@1175
   164
klao@1519
   165
If you want to see more features, go to the
klao@1519
   166
\ref quicktour "Quick Tour to LEMON",
klao@1519
   167
if you want to see see some demo programs then go to our 
athos@1175
   168
\ref demoprograms "Demo Programs" page! 
athos@1175
   169
athos@1175
   170
athos@1175
   171
*/