COIN-OR::LEMON - Graph Library

source: lemon-0.x/doc/getstart.dox @ 2627:197e2ea11bad

Last change on this file since 2627:197e2ea11bad was 2553:bfced05fa852, checked in by Alpar Juttner, 16 years ago

Happy New Year to LEMON (+ better update-copyright-header script)

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