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