/* -*- mode: C++; indent-tabs-mode: nil; -*-

 *

 * This file is a part of LEMON, a generic C++ optimization library.

 *

 * Copyright (C) 2003-2008

 * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport

 * (Egervary Research Group on Combinatorial Optimization, EGRES).

 *

 * Permission to use, modify and distribute this software is granted

 * provided that this copyright notice appears in all copies. For

 * precise terms see the accompanying LICENSE file.

 *

 * This software is provided "AS IS" with no warranty of any kind,

 * express or implied, and with no claim as to its suitability for any

 * purpose.

 *

 */

/**

\page getting_started Getting Started

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++ programming

language. The procedure is pretty straightforward, but if you have any

difficulties do not hesitate to

<a href="mailto:lemon-user@lemon.cs.elte.hu"><b>ask</b></a>.

\section requirements_lemon 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

advantageousm, 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) and Microsoft Visual C++ (on Windows).

If you want to develop with LEMON under Windows, you can use a Windows

installer or you can consider using Cygwin.

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

If you would like to develop under Windows and use a Windows installer,

you could skip the following sections and continue reading \ref hello_lemon.

However keep in mind that you have to make appropriate steps instead of

the instructions detailed here to be able to compile the example code

with your compiler.

\subsection requirements_lp LP Solver Requirements

The LEMON LP solver interface can use the GLPK (GNU Linear Programming

Kit), CPLEX and SoPlex solver. If you want to use it, you will need at

least one of these.

See the <b><tt>INSTALL</tt></b> file how to enable these at compile time.

\section download_lemon How to Download LEMON

You can download LEMON from our web site:

<a href="http://lemon.cs.elte.hu/">http://lemon.cs.elte.hu/</a>.

There you will find released versions in form of <tt>.tar.gz</tt> files

(and Windows installers).

If you want a developer version (for example you want to contribute in

developing LEMON) then you might want to use our Mercurial repository.

This case is detailed \ref hg_checkout "later", so from now on we

suppose that you downloaded a <tt>.tar.gz</tt> file.

\section install_lemon How to Install LEMON

In order to install LEMON you have to do the following steps.

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-1.0.tar.gz</tt>) and issue the following commands:

\verbatim

tar xvzf lemon-1.0.tar.gz

cd lemon-1.0

./configure

make

make check    # This is optional, but recommended. 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=DIRECTORY flag to <tt>./configure</tt>, for example:

\verbatim

./configure --prefix=/home/username/lemon

\endverbatim

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-1.0.tar.gz

\endverbatim

This command untars the <tt>tar.gz</tt> file into a directory named

<tt>lemon-1.0</tt>.

\verbatim

cd lemon-1.0

\endverbatim

This command enters the directory.

\verbatim

./configure

\endverbatim

This command runs the configure shell script, which does some checks and

creates the makefiles.

\verbatim

make

\endverbatim

This command compiles the non-template part of LEMON into <tt>libemon.a</tt>

file. It also compiles the programs in the tools and demo subdirectories

when enabled.

\verbatim

make check

\endverbatim

This step is optional, but recommended. It runs the test programs that

have been developed for LEMON to check whether the library works properly on

your platform.

\verbatim

make install

\endverbatim

This command 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 configure to install the library in

non-default location.

Several other configure flags can be passed to <tt>./configure</tt>.

For more information see the <b><tt>INSTALL</tt></b> file.

\section hg_checkout How to Checkout LEMON from our Mercurial Repository

You can obtain the latest (developer) version of LEMON from our Mercurial

repository. To do this issue the following command.

\verbatim

hg clone http://lemon.cs.elte.hu/hg/lemon-main lemon-src

\endverbatim

\section hg_compile How to Compile the Source from the Repository

You can compile the code from the repository similarly to the packaged

version, but you will need to run <b><tt>autoreconf -vif</tt></b>

(or <b><tt>./bootstrap</tt></b> in some older environment) before

<tt>./configure</tt>. See <tt>./configure --help</tt> for options.

For bootstrapping you will need the following tools:

 - <a href="http://www.gnu.org/software/automake/">automake</a> (1.7 or newer)

 - <a href="http://www.gnu.org/software/autoconf/">autoconf</a> (2.59 or newer)

 - <a href="http://www.gnu.org/software/libtool/">libtool</a>

 - <a href="http://pkgconfig.freedesktop.org/">pkgconfig</a>

To generate the documentation, run <tt>make html</tt>.

You will need <a href="http://www.doxygen.org/">Doxygen</a> for this.

\section hello_lemon Compile Your First Code

If you have installed LEMON on your system you can paste the following

code segment into a file called <tt>hello_lemon.cc</tt> to have a first

working program that uses LEMON.

\dontinclude hello_lemon.cc

\skip #include

\until }

First let us briefly explain how this example program works.

(The used notions will be discussed in detail in the following chapter.)

After some convenience typedefs we create a directed graph (\e digraph)

and add some nodes and arcs to it.

ListDigraph is one of the digraph classes implemented in LEMON.

It is based on linked lists, therefore iterating through its nodes and

arcs is fast.

Then we iterate through all nodes of the digraph and print their unique

IDs. We use a constructor of the node iterator to initialize it to the

first node.

The <tt>operator++</tt> is used to step to the next node. After the last

node the iterator becomes invalid (i.e. it is set to \c INVALID).

This is what we exploit in the stop condition.

We iterate through all arcs of the digraph very similarly and print the

IDs of their source (tail) and target (head) nodes using the \c source()

and \c target() member functions.

After that we create an arc map, which is actually a mapping that assigns

an \c int value (length) to each arc, and we set this value for each arc.

Finally we iterate through all arcs again and print their lengths.

Now let's compile this simple example program.

\subsection hello_lemon_system If LEMON is Installed System-Wide

If 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 LEMON):

\verbatim

g++ hello_lemon.cc -o hello_lemon -lemon

\endverbatim

As a result you will get the exacutable \c hello_lemon in the current

directory, which you can run by the following command.

\verbatim

./hello_lemon

\endverbatim

\subsection hello_lemon_user If LEMON is Installed User-Local

Compiling the code is a bit more difficult if you installed LEMON

user-local into a directory (e.g. <tt>~/lemon</tt>) or if you just

skipped the step <tt>make install</tt>.

You have to issue a command like this.

\verbatim

g++ -I ~/lemon hello_lemon.cc -o hello_lemon -lemon -L ~/lemon/lemon/.libs

\endverbatim

\subsubsection hello_lemon_pkg_config Use pkg-config

\todo Write this sub-subsection (\ref hello_lemon_pkg_config).

If everything has gone well, then our program prints out the followings.

\verbatim

Hello World!

This is LEMON library here. We have a direceted graph.

Nodes: 3 2 1 0

Arcs: (2,3) (1,3) (1,2) (0,2) (0,1)

There is a map on the arcs (length):

length(2,3)=10

length(1,3)=25

length(1,2)=5

length(0,2)=20

length(0,1)=10

\endverbatim

You may note that iterating through the nodes and arcs is done in the

reverse order compared to the creating order (the IDs are in decreasing

order).

This is due to implementation aspects, that may differ at other graph

types, moreover it may be changed in the next releases.

Thus you should not exploit this method in any way, you should not

suppose anything about the iteration order.

If you managed to compile and run this example code without any problems,

you can go on reading this tutorial to get to know more features and tools

of LEMON.

Otherwise if you encountered problems that you did not manage to solve,

do not hesitate to

<a href="mailto:lemon-user@lemon.cs.elte.hu"><b>contact us</b></a>.

*/