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