source: lemon-0.x/doc/getstart.dox @ 1519:17e367a93cbb

/**
\page getstart How to start using LEMON

In this page we detail how to start using LEMON, from downloading it to
your computer, through the steps of installation, to showing a simple
"Hello World" type program that already uses LEMON. We assume that you
have a basic knowledge of your operating system and \c C++ programming
language. The procedure is pretty straightforward, but if you have any
difficulties don't hesitate to
<a href="http://lemon.cs.elte.hu/mailinglists.html">ask</a>.

\section requirementsLEMON Hardware and software requirements

In LEMON we use C++ templates heavily, thus compilation takes a
considerable amount of time and memory. So some decent box would be
advantageous. But otherwise there are no special hardware requirements.

You will need a recent C++ compiler. Our primary target is the GNU C++
Compiler (g++), from version 3.3 upwards. We also checked the Intel C
compiler (icc). Microsoft Visual C++ .NET version was also reported to
work (but not the earlier versions). If you want to develop with LEMON
under Windows you could consider using Cygwin.


In this description we will suppose a linux environment and GNU C Compiler.

\section downloadLEMON How to download LEMON

You can download LEMON from the LEMON web site:
http://lemon.cs.elte.hu/dowload.html.
There you will find released versions in form of <tt>.tar.gz</tt> files.
If you want a developer version (for example you want to contribute in
developing the library LEMON) then you might want to use our Subversion
repository. This case is not detailed here, so from now on we suppose that
you downloaded a tar.gz file.



\section installLEMON How to install LEMON

In order to install LEMON you have to do the following

Download the tarball (named <tt>lemon-x.y.z.tar.gz</tt> where \c x,\c y
and \c z are numbers indicating the version of the library: in our example
we will have <tt>lemon-0.3.1.tar.gz</tt>) and issue the following
commands:

\verbatim
tar xvzf lemon-0.3.1.tar.gz
cd lemon-0.3.1
./configure
make
make check   #(This is optional, but recomended. It runs a bunch of tests.)
make install
\endverbatim

These commands install LEMON under \c /usr/local (you will
need root privileges to be able to install to that
directory). If you want to install it to some other place, then
pass the \c --prefix=DIR flag to \c ./configure. In what follows
we will assume that you were able to install to directory
\c /usr/local, otherwise some extra care is to be taken to use the
library.

We briefly explain these commands below.

\verbatim
tar xvzf lemon-0.3.1.tar.gz
\endverbatim
This command untars the <tt>tar.gz</tt> file into a directory named <tt>
lemon-0.3.1</tt>.

\verbatim
cd lemon-0.3.1
\endverbatim
Enters the directory.

\verbatim
./configure
\endverbatim
Does some configuration (creates makefiles etc).
\todo Explain the most important switches here (gui, doc, glpk, cplex).

\verbatim
make
\endverbatim
This command compiles the non-template part of LEMON into
<b>libemon.a</b> file. It also compiles some benchmark and demo
programs.

\verbatim
make check
\endverbatim
This is an optional step: it runs the test programs that we
developed for LEMON to check whether the library works properly on
your platform.

\verbatim
make install
\endverbatim
This will copy the directory structure to its final destination (e.g. to \c
/usr/local) so that your system can access it. This command should
be issued as "root", unless you provided a \c --prefix switch to
the \c cofugure to install the library in non-default location.

\section helloworld My first program using LEMON

If you have installed LEMON on your system you can paste the
following code segment into a file (named e.g. \c hello_lemon.cc)
to have a first working program that uses library LEMON.

\code
#include <iostream>
#include <lemon/list_graph.h>

int main()
{
  typedef lemon::ListGraph Graph;
  typedef Graph::EdgeIt EdgeIt;
  typedef Graph::NodeIt NodeIt;
  using lemon::INVALID;

  Graph g;
  
  for (int i = 0; i < 3; i++)
    g.addNode();
  
  for (NodeIt i(g); i!=INVALID; ++i)
    for (NodeIt j(g); j!=INVALID; ++j)
      if (i != j) g.addEdge(i, j);

  std::cout << "Nodes:";
  for (NodeIt i(g); i!=INVALID; ++i)
    std::cout << " " << g.id(i);
  std::cout << std::endl;

  std::cout << "Edges:";
  for (EdgeIt i(g); i!=INVALID; ++i)
    std::cout << " (" << g.id(g.source(i)) << "," << g.id(g.target(i)) << ")";
  std::cout << std::endl;
}
\endcode

First let us briefly explain how this program works.

ListGraph is one of LEMON's graph classes. It is based on linked lists,
therefore iterating throuh its edges and nodes is fast.

After some convenient typedefs we create a graph and add three nodes to it.
Then we add edges to it to form a complete graph.

Then we iterate through all nodes of the graph. We use a constructor of the
node iterator to initialize it to the first node. The operator++ is used to
step to the next node. Using operator++ on the iterator pointing to the last
node invalidates the iterator i.e. sets its value to
\ref lemon::INVALID "INVALID". This is what we exploit in the stop condition.

We can also iterate through all edges of the graph very similarly. The 
\c target and
\c source member functions can be used to access the endpoints of an edge.

If you have saved the preceding code into a file named, say, \c
hello_lemon.cc and your installation of LEMON into directory \c
/usr/local was successful then it is very easy to compile this
program with the following command (the argument <tt>-lemon</tt>
tells the compiler that we are using the installed library LEMON):

\verbatim
g++ hello_lemon.cc -o hello_lemon -lemon
\endverbatim

As a result you will get the exacutable \c hello_lemon in
this directory that you can run by the command 
\verbatim
./hello_lemon
\endverbatim


If everything has gone well then the previous code fragment prints
out the following:

\verbatim
Nodes: 2 1 0

Edges: (0,2) (1,2) (0,1) (2,1) (1,0) (2,0)
\endverbatim

Congratulations!

If you want to see more features, go to the
\ref quicktour "Quick Tour to LEMON",
if you want to see see some demo programs then go to our 
\ref demoprograms "Demo Programs" page! 


*/