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: */