doc/getstart.dox
author athos
Fri, 05 Jan 2007 10:59:18 +0000
changeset 2334 c1e936e6a46b
parent 2125 2f2cbe4e78a8
child 2391 14a343be7a5a
permissions -rw-r--r--
I only corrected some errors in the documentation.
     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 <a href="mailto:etik-ol@cs.elte.hu">ask</a>.
    10 
    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 2003 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 In this description we will suppose a Linux environment and GNU C++ Compiler.
    25 
    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 
    35 \section downloadLEMON How to download LEMON
    36 
    37 You can download LEMON from the LEMON web site:
    38 http://lemon.cs.elte.hu/download.html .
    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.
    44 
    45 
    46 \section installLEMON How to install LEMON
    47 
    48 In order to install LEMON you have to do the following steps.
    49 
    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:
    54 
    55 \verbatim
    56 tar xvzf lemon-0.3.1.tar.gz
    57 cd lemon-0.3.1
    58 ./configure
    59 make
    60 make check   #(This is optional, but recommended. It runs a bunch of tests.)
    61 make install
    62 \endverbatim
    63 
    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
    67 pass the \c --prefix=DIRECTORY flag to \c ./configure, for example:
    68 
    69 \verbatim
    70 ./configure --prefix=/home/username/lemon
    71 \endverbatim
    72 
    73 In what follows we will assume that you were able to install to directory
    74 \c /usr/local, otherwise some extra care is to be taken to use the
    75 library.
    76 
    77 We briefly explain these commands below.
    78 
    79 \verbatim
    80 tar xvzf lemon-0.3.1.tar.gz
    81 \endverbatim
    82 This command untars the <tt>tar.gz</tt> file into a directory named <tt>
    83 lemon-0.3.1</tt>.
    84 
    85 \verbatim
    86 cd lemon-0.3.1
    87 \endverbatim
    88 Enters the directory.
    89 
    90 \verbatim
    91 ./configure
    92 \endverbatim
    93 Does some configuration (creates makefiles etc).
    94 
    95 \verbatim
    96 make
    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.
   101 
   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.
   108 
   109 \verbatim
   110 make install
   111 \endverbatim
   112 This will copy the directory structure to its final destination (e.g. to \c
   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
   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
   134 the GLPK headers and libraries are not under the same prefix (which is
   135 unlikely).
   136 
   137 \verbatim
   138 --with-glpk-libdir=DIR
   139 \endverbatim
   140 The directory where the GLPK libraries are located. This is only useful when
   141 the GLPK headers and libraries are not under the same prefix (which is
   142 unlikely).
   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).
   205 
   206 \section helloworld My first program using LEMON
   207 
   208 If you have installed LEMON on your system you can paste the
   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.
   212 
   213 \dontinclude hello_lemon.cc
   214 \skip include
   215 \until }
   216 
   217 First let us briefly explain how this program works.
   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 
   222 After some convenience typedefs we create a graph and add three nodes to it.
   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 
   235 If your installation of LEMON into directory \c /usr/local was
   236 successful, then it is very easy to compile this program with the
   237 following command (the argument <tt>-lemon</tt> tells the compiler
   238 that we are using the installed library LEMON):
   239 
   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
   245 this directory that you can run by the command 
   246 \verbatim
   247 ./hello_lemon
   248 \endverbatim
   249 
   250 
   251 If everything has gone well then the previous code fragment prints
   252 out the following:
   253 
   254 \verbatim
   255 Nodes: 2 1 0
   256 
   257 Edges: (0,2) (1,2) (0,1) (2,1) (1,0) (2,0)
   258 \endverbatim
   259 
   260 Congratulations!
   261 
   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 
   265 \ref demoprograms "Demo Programs" page! 
   266 
   267 
   268 */