kpeter@3: /* -*- mode: C++; indent-tabs-mode: nil; -*-
kpeter@3: *
kpeter@3: * This file is a part of LEMON, a generic C++ optimization library.
kpeter@3: *
kpeter@3: * Copyright (C) 2003-2008
kpeter@3: * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
kpeter@3: * (Egervary Research Group on Combinatorial Optimization, EGRES).
kpeter@3: *
kpeter@3: * Permission to use, modify and distribute this software is granted
kpeter@3: * provided that this copyright notice appears in all copies. For
kpeter@3: * precise terms see the accompanying LICENSE file.
kpeter@3: *
kpeter@3: * This software is provided "AS IS" with no warranty of any kind,
kpeter@3: * express or implied, and with no claim as to its suitability for any
kpeter@3: * purpose.
kpeter@3: *
kpeter@3: */
kpeter@3:
kpeter@3: /**
kpeter@6: \page getting_started Getting Started
kpeter@3:
kpeter@3: In this page we detail how to start using LEMON, from downloading it to
kpeter@3: your computer, through the steps of installation, to showing a simple
kpeter@3: "Hello World" type program that already uses LEMON. We assume that you
kpeter@3: have a basic knowledge of your operating system and C++ programming
kpeter@3: language. The procedure is pretty straightforward, but if you have any
kpeter@6: difficulties do not hesitate to
kpeter@3: ask.
kpeter@3:
kpeter@3: \section requirements_lemon Hardware and Software Requirements
kpeter@3:
kpeter@3: In LEMON we use C++ templates heavily, thus compilation takes a
kpeter@3: considerable amount of time and memory. So some decent box would be
kpeter@6: advantageousm, but otherwise there are no special hardware requirements.
kpeter@3:
kpeter@3: You will need a recent C++ compiler. Our primary target is the GNU C++
kpeter@3: Compiler (g++), from version 3.3 upwards. We also checked the Intel C++
kpeter@6: Compiler (icc) and Microsoft Visual C++ (on Windows).
kpeter@6: If you want to develop with LEMON under Windows, you can use a Windows
kpeter@6: installer or you can consider using Cygwin.
kpeter@3:
kpeter@3: In this description we will suppose a Linux environment and GNU C++ Compiler.
kpeter@6: If you would like to develop under Windows and use a Windows installer,
kpeter@6: you could skip the following sections and continue reading \ref hello_lemon.
kpeter@6: However keep in mind that you have to make appropriate steps instead of
kpeter@6: the instructions detailed here to be able to compile the example code
kpeter@6: with your compiler.
kpeter@3:
kpeter@3: \subsection requirements_lp LP Solver Requirements
kpeter@3:
kpeter@3: The LEMON LP solver interface can use the GLPK (GNU Linear Programming
kpeter@6: Kit), CPLEX and SoPlex solver. If you want to use it, you will need at
kpeter@6: least one of these.
kpeter@6: See the INSTALL file how to enable these at compile time.
kpeter@3:
kpeter@3: \section download_lemon How to Download LEMON
kpeter@3:
kpeter@6: You can download LEMON from our web site:
kpeter@6: http://lemon.cs.elte.hu/.
kpeter@6: There you will find released versions in form of .tar.gz files
kpeter@6: (and Windows installers).
kpeter@3: If you want a developer version (for example you want to contribute in
kpeter@6: developing LEMON) then you might want to use our Mercurial repository.
kpeter@6: This case is detailed \ref hg_checkout "later", so from now on we
kpeter@6: suppose that you downloaded a .tar.gz file.
kpeter@3:
kpeter@3: \section install_lemon How to Install LEMON
kpeter@3:
kpeter@3: In order to install LEMON you have to do the following steps.
kpeter@3:
kpeter@3: Download the tarball (named lemon-x.y.z.tar.gz where \c x, \c y
kpeter@3: and \c z are numbers indicating the version of the library, in our example
kpeter@3: we will have lemon-1.0.tar.gz) and issue the following commands:
kpeter@3:
kpeter@3: \verbatim
kpeter@3: tar xvzf lemon-1.0.tar.gz
kpeter@3: cd lemon-1.0
kpeter@3: ./configure
kpeter@3: make
kpeter@3: make check # This is optional, but recommended. It runs a bunch of tests.
kpeter@3: make install
kpeter@3: \endverbatim
kpeter@3:
kpeter@3: These commands install LEMON under \c /usr/local (you will
kpeter@3: need root privileges to be able to install to that
kpeter@3: directory). If you want to install it to some other place, then
kpeter@3: pass the \c --prefix=DIRECTORY flag to ./configure, for example:
kpeter@3:
kpeter@3: \verbatim
kpeter@3: ./configure --prefix=/home/username/lemon
kpeter@3: \endverbatim
kpeter@3:
kpeter@3: In what follows we will assume that you were able to install to directory
kpeter@3: \c /usr/local, otherwise some extra care is to be taken to use the library.
kpeter@3:
kpeter@3: We briefly explain these commands below.
kpeter@3:
kpeter@3: \verbatim
kpeter@3: tar xvzf lemon-1.0.tar.gz
kpeter@3: \endverbatim
kpeter@3: This command untars the tar.gz file into a directory named
kpeter@3: lemon-1.0.
kpeter@3:
kpeter@3: \verbatim
kpeter@3: cd lemon-1.0
kpeter@3: \endverbatim
kpeter@3: This command enters the directory.
kpeter@3:
kpeter@3: \verbatim
kpeter@3: ./configure
kpeter@3: \endverbatim
kpeter@3: This command runs the configure shell script, which does some checks and
kpeter@3: creates the makefiles.
kpeter@3:
kpeter@3: \verbatim
kpeter@3: make
kpeter@3: \endverbatim
kpeter@3: This command compiles the non-template part of LEMON into libemon.a
kpeter@3: file. It also compiles the programs in the tools and demo subdirectories
kpeter@3: when enabled.
kpeter@3:
kpeter@3: \verbatim
kpeter@3: make check
kpeter@3: \endverbatim
kpeter@3: This step is optional, but recommended. It runs the test programs that
kpeter@6: have been developed for LEMON to check whether the library works properly on
kpeter@3: your platform.
kpeter@3:
kpeter@3: \verbatim
kpeter@3: make install
kpeter@3: \endverbatim
kpeter@3: This command will copy the directory structure to its final destination
kpeter@3: (e.g. to \c /usr/local) so that your system can access it.
kpeter@3: This command should be issued as "root", unless you provided a
kpeter@3: \c --prefix switch to the \c configure to install the library in
kpeter@3: non-default location.
kpeter@3:
kpeter@3: Several other configure flags can be passed to ./configure.
kpeter@6: For more information see the INSTALL file.
kpeter@3:
kpeter@3: \section hg_checkout How to Checkout LEMON from our Mercurial Repository
kpeter@3:
kpeter@6: You can obtain the latest (developer) version of LEMON from our Mercurial
kpeter@6: repository. To do this issue the following command.
kpeter@3: \verbatim
kpeter@6: hg clone http://lemon.cs.elte.hu/hg/lemon-main lemon-src
kpeter@3: \endverbatim
kpeter@3:
kpeter@3: \section hg_compile How to Compile the Source from the Repository
kpeter@3:
kpeter@3: You can compile the code from the repository similarly to the packaged
kpeter@6: version, but you will need to run autoreconf -vif
kpeter@6: (or ./bootstrap in some older environment) before
kpeter@3: ./configure. See ./configure --help for options.
kpeter@3: For bootstrapping you will need the following tools:
kpeter@3:
kpeter@3: - automake (1.7 or newer)
kpeter@3: - autoconf (2.59 or newer)
kpeter@3: - libtool
kpeter@3: - pkgconfig
kpeter@3:
kpeter@3: To generate the documentation, run make html.
kpeter@3: You will need Doxygen for this.
kpeter@3:
kpeter@6: \section hello_lemon Compile Your First Code
kpeter@6:
kpeter@6: If you have installed LEMON on your system you can paste the following
kpeter@6: code segment into a file called hello_lemon.cc to have a first
kpeter@6: working program that uses LEMON.
kpeter@6:
kpeter@6: \dontinclude hello_lemon.cc
kpeter@6: \skip #include
kpeter@6: \until }
kpeter@6:
kpeter@6: First let us briefly explain how this example program works.
kpeter@6: (The used notions will be discussed in detail in the following chapter.)
kpeter@6:
kpeter@6: After some convenience typedefs we create a directed graph (\e digraph)
kpeter@6: and add some nodes and arcs to it.
kpeter@6: ListDigraph is one of the digraph classes implemented in LEMON.
kpeter@6: It is based on linked lists, therefore iterating through its nodes and
kpeter@6: arcs is fast.
kpeter@6:
kpeter@6: Then we iterate through all nodes of the digraph and print their unique
kpeter@6: IDs. We use a constructor of the node iterator to initialize it to the
kpeter@6: first node.
kpeter@6: The operator++ is used to step to the next node. After the last
kpeter@6: node the iterator becomes invalid (i.e. it is set to \c INVALID).
kpeter@6: This is what we exploit in the stop condition.
kpeter@6: We iterate through all arcs of the digraph very similarly and print the
kpeter@6: IDs of their source (tail) and target (head) nodes using the \c source()
kpeter@6: and \c target() member functions.
kpeter@6:
kpeter@6: After that we create an arc map, which is actually a mapping that assigns
kpeter@6: an \c int value (length) to each arc, and we set this value for each arc.
kpeter@6: Finally we iterate through all arcs again and print their lengths.
kpeter@6:
kpeter@6: Now let's compile this simple example program.
kpeter@6:
kpeter@6: \subsection hello_lemon_system If LEMON is Installed System-Wide
kpeter@6:
kpeter@6: If your installation of LEMON into directory \c /usr/local was
kpeter@6: successful, then it is very easy to compile this program with the
kpeter@6: following command (the argument -lemon tells the compiler
kpeter@6: that we are using the installed LEMON):
kpeter@6:
kpeter@6: \verbatim
kpeter@6: g++ hello_lemon.cc -o hello_lemon -lemon
kpeter@6: \endverbatim
kpeter@6:
kpeter@6: As a result you will get the exacutable \c hello_lemon in the current
kpeter@6: directory, which you can run by the following command.
kpeter@6:
kpeter@6: \verbatim
kpeter@6: ./hello_lemon
kpeter@6: \endverbatim
kpeter@6:
kpeter@6: \subsection hello_lemon_user If LEMON is Installed User-Local
kpeter@6:
kpeter@6: Compiling the code is a bit more difficult if you installed LEMON
kpeter@6: user-local into a directory (e.g. ~/lemon) or if you just
kpeter@6: skipped the step make install.
kpeter@6: You have to issue a command like this.
kpeter@6:
kpeter@6: \verbatim
kpeter@6: g++ -I ~/lemon hello_lemon.cc -o hello_lemon -lemon -L ~/lemon/lemon/.libs
kpeter@6: \endverbatim
kpeter@6:
kpeter@6: \subsubsection hello_lemon_pkg_config Use pkg-config
kpeter@6:
kpeter@6: \todo Write this sub-subsection (\ref hello_lemon_pkg_config).
kpeter@6:
kpeter@6: If everything has gone well, then our program prints out the followings.
kpeter@6:
kpeter@6: \verbatim
kpeter@6: Hello World!
kpeter@6: This is LEMON library here. We have a direceted graph.
kpeter@6:
kpeter@6: Nodes: 3 2 1 0
kpeter@6: Arcs: (2,3) (1,3) (1,2) (0,2) (0,1)
kpeter@6:
kpeter@6: There is a map on the arcs (length):
kpeter@6:
kpeter@6: length(2,3)=10
kpeter@6: length(1,3)=25
kpeter@6: length(1,2)=5
kpeter@6: length(0,2)=20
kpeter@6: length(0,1)=10
kpeter@6: \endverbatim
kpeter@6:
kpeter@6: You may note that iterating through the nodes and arcs is done in the
kpeter@6: reverse order compared to the creating order (the IDs are in decreasing
kpeter@6: order).
kpeter@6: This is due to implementation aspects, that may differ at other graph
kpeter@6: types, moreover it may be changed in the next releases.
kpeter@6: Thus you should not exploit this method in any way, you should not
kpeter@6: suppose anything about the iteration order.
kpeter@6:
kpeter@6: If you managed to compile and run this example code without any problems,
kpeter@6: you can go on reading this tutorial to get to know more features and tools
kpeter@6: of LEMON.
kpeter@6: Otherwise if you encountered problems that you did not manage to solve,
kpeter@6: do not hesitate to
kpeter@6: contact us.
kpeter@6:
kpeter@3: */