alpar@2391: /* -*- C++ -*- alpar@2391: * alpar@2391: * This file is a part of LEMON, a generic C++ optimization library alpar@2391: * alpar@2391: * Copyright (C) 2003-2007 alpar@2391: * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport alpar@2391: * (Egervary Research Group on Combinatorial Optimization, EGRES). alpar@2391: * alpar@2391: * Permission to use, modify and distribute this software is granted alpar@2391: * provided that this copyright notice appears in all copies. For alpar@2391: * precise terms see the accompanying LICENSE file. alpar@2391: * alpar@2391: * This software is provided "AS IS" with no warranty of any kind, alpar@2391: * express or implied, and with no claim as to its suitability for any alpar@2391: * purpose. alpar@2391: * alpar@2391: */ alpar@2391: athos@1173: /** athos@1173: \page getstart How to start using LEMON athos@1173: klao@1519: In this page we detail how to start using LEMON, from downloading it to klao@1519: your computer, through the steps of installation, to showing a simple klao@1519: "Hello World" type program that already uses LEMON. We assume that you klao@1519: have a basic knowledge of your operating system and \c C++ programming klao@1519: language. The procedure is pretty straightforward, but if you have any deba@2395: difficulties don't hesitate to deba@2395: ask. athos@1175: ladanyi@1637: athos@1514: \section requirementsLEMON Hardware and software requirements athos@1175: klao@1519: In LEMON we use C++ templates heavily, thus compilation takes a klao@1519: considerable amount of time and memory. So some decent box would be klao@1519: advantageous. But otherwise there are no special hardware requirements. athos@1514: klao@1519: You will need a recent C++ compiler. Our primary target is the GNU C++ ladanyi@1637: Compiler (g++), from version 3.3 upwards. We also checked the Intel C++ ladanyi@1637: Compiler (icc). Microsoft Visual C++ .NET 2003 was also reported to klao@1519: work (but not the earlier versions). If you want to develop with LEMON klao@1519: under Windows you could consider using Cygwin. athos@1514: ladanyi@1637: In this description we will suppose a Linux environment and GNU C++ Compiler. athos@1514: ladanyi@1637: ladanyi@1637: \subsection requirementsLP LP solver requirements ladanyi@1637: deba@2395: The LEMON LP solver interface can use the GLPK (GNU Linear Programming deba@2395: Kit) ,CPLEX (was tested with CPLEX 7.5) and SoPlex solver. If you want deba@2395: to use it you will need at least one of these. See \ref configureFlags deba@2395: how to enable these at compile time. ladanyi@1637: ladanyi@1637: athos@1173: \section downloadLEMON How to download LEMON athos@1173: athos@1511: You can download LEMON from the LEMON web site: deba@2395: deba@2395: http://lemon.cs.elte.hu/site/products/ . klao@1519: There you will find released versions in form of .tar.gz files. klao@1519: If you want a developer version (for example you want to contribute in klao@1519: developing the library LEMON) then you might want to use our Subversion klao@1519: repository. This case is not detailed here, so from now on we suppose that klao@1519: you downloaded a tar.gz file. athos@1514: athos@1175: athos@1173: \section installLEMON How to install LEMON athos@1173: athos@1528: In order to install LEMON you have to do the following steps. athos@1173: klao@1519: Download the tarball (named lemon-x.y.z.tar.gz where \c x,\c y klao@1519: and \c z are numbers indicating the version of the library: in our example klao@1519: we will have lemon-0.3.1.tar.gz) and issue the following klao@1519: commands: athos@1511: klao@1519: \verbatim athos@1511: tar xvzf lemon-0.3.1.tar.gz athos@1511: cd lemon-0.3.1 athos@1511: ./configure athos@1511: make athos@1528: make check #(This is optional, but recommended. It runs a bunch of tests.) athos@1511: make install klao@1519: \endverbatim athos@1511: klao@1519: These commands install LEMON under \c /usr/local (you will klao@1519: need root privileges to be able to install to that klao@1519: directory). If you want to install it to some other place, then athos@1528: pass the \c --prefix=DIRECTORY flag to \c ./configure, for example: athos@1528: athos@1528: \verbatim ladanyi@2167: ./configure --prefix=/home/username/lemon athos@1528: \endverbatim athos@1528: athos@1528: In what follows we will assume that you were able to install to directory klao@1519: \c /usr/local, otherwise some extra care is to be taken to use the klao@1519: library. athos@1511: athos@1514: We briefly explain these commands below. athos@1514: klao@1519: \verbatim athos@1514: tar xvzf lemon-0.3.1.tar.gz klao@1519: \endverbatim klao@1519: This command untars the tar.gz file into a directory named klao@1519: lemon-0.3.1. athos@1514: klao@1519: \verbatim athos@1514: cd lemon-0.3.1 klao@1519: \endverbatim athos@1514: Enters the directory. athos@1514: klao@1519: \verbatim athos@1514: ./configure klao@1519: \endverbatim athos@1514: Does some configuration (creates makefiles etc). athos@1514: klao@1519: \verbatim athos@1514: make klao@1519: \endverbatim klao@1519: This command compiles the non-template part of LEMON into klao@1519: libemon.a file. It also compiles some benchmark and demo klao@1519: programs. athos@1514: klao@1519: \verbatim klao@1519: make check klao@1519: \endverbatim klao@1519: This is an optional step: it runs the test programs that we klao@1519: developed for LEMON to check whether the library works properly on klao@1519: your platform. athos@1514: klao@1519: \verbatim athos@1514: make install klao@1519: \endverbatim athos@1514: This will copy the directory structure to its final destination (e.g. to \c klao@1519: /usr/local) so that your system can access it. This command should klao@1519: be issued as "root", unless you provided a \c --prefix switch to ladanyi@1637: the \c configure to install the library in non-default location. ladanyi@1637: ladanyi@1637: ladanyi@1637: \subsection configureFlags Configure flags ladanyi@1637: ladanyi@1637: You can pass the following flags to \c ./configure (see \c ./configure --help ladanyi@1637: for more): ladanyi@1637: ladanyi@1637: \verbatim ladanyi@1637: --with-glpk[=PREFIX] ladanyi@1637: \endverbatim ladanyi@1637: Enable GLPK support (default). You should specify the prefix too if you ladanyi@1637: installed it to some non-standard location (e.g. your home directory). If ladanyi@1637: GLPK is not found, then GLPK support will be disabled. ladanyi@1637: ladanyi@1637: \verbatim ladanyi@1637: --with-glpk-includedir=DIR ladanyi@1637: \endverbatim ladanyi@1637: The directory where the GLPK header files are located. This is only useful when alpar@1713: the GLPK headers and libraries are not under the same prefix (which is alpar@1713: unlikely). ladanyi@1637: ladanyi@1637: \verbatim ladanyi@1637: --with-glpk-libdir=DIR ladanyi@1637: \endverbatim ladanyi@1637: The directory where the GLPK libraries are located. This is only useful when alpar@1713: the GLPK headers and libraries are not under the same prefix (which is alpar@1713: unlikely). ladanyi@1637: ladanyi@1637: \verbatim ladanyi@1637: --without-glpk ladanyi@1637: \endverbatim ladanyi@1637: Disable GLPK support. ladanyi@1637: ladanyi@1637: \verbatim ladanyi@1637: --with-cplex[=PREFIX] ladanyi@1637: \endverbatim ladanyi@1637: Enable CPLEX support (default). You should specify the prefix too if you ladanyi@1637: installed it to some non-standard location (e.g. \c /opt/ilog/cplex75). If ladanyi@1637: CPLEX is not found, then CPLEX support will be disabled. ladanyi@1637: ladanyi@1637: \verbatim ladanyi@1637: --with-cplex-includedir=DIR ladanyi@1637: \endverbatim ladanyi@1637: The directory where the CPLEX header files are located. This is only useful ladanyi@1637: when the CPLEX headers and libraries are not under the same prefix. ladanyi@1637: ladanyi@1637: \verbatim ladanyi@1637: --with-cplex-libdir=DIR ladanyi@1637: \endverbatim ladanyi@1637: The directory where the CPLEX libraries are located. This is only useful when ladanyi@1637: the CPLEX headers and libraries are not under the same prefix. ladanyi@1637: ladanyi@1637: \verbatim ladanyi@1637: --without-cplex ladanyi@1637: \endverbatim ladanyi@1637: Disable CPLEX support. ladanyi@1637: deba@2395: \verbatim deba@2395: --with-soplex[=PREFIX] deba@2395: \endverbatim deba@2395: Enable SoPlex support (default). You should specify the prefix too if deba@2395: you installed it to some non-standard location. If SoPlex is not deba@2395: found, then SoPlex support will be disabled. deba@2395: deba@2395: \verbatim deba@2395: --with-soplex-includedir=DIR deba@2395: \endverbatim deba@2395: The directory where the SoPlex header files are located. This is only useful deba@2395: when the SoPlex headers and libraries are not under the same prefix. deba@2395: deba@2395: \verbatim deba@2395: --with-soplex-libdir=DIR deba@2395: \endverbatim deba@2395: The directory where the SoPlex libraries are located. This is only useful when deba@2395: the SoPlex headers and libraries are not under the same prefix. deba@2395: deba@2395: \verbatim deba@2395: --without-soplex deba@2395: \endverbatim deba@2395: Disable SoPlex support. deba@2395: ladanyi@1637: ladanyi@1637: \section svnCheckout How to checkout LEMON form our Subversion repository ladanyi@1637: ladanyi@1637: You can obtain the latest version of LEMON from our Subversion repository. To ladanyi@1637: do this issue the following command: ladanyi@1637: \verbatim deba@2395: svn co https://lemon.cs.elte.hu/svn/lemon/trunk lemon-src ladanyi@1637: \endverbatim ladanyi@1637: Use "lemon" as username, the password is empty. ladanyi@1637: ladanyi@1637: ladanyi@1637: \section svnCompile How to compile the source from the repository ladanyi@1637: deba@2395: You can compile the code from the repository similarly to the packaged deba@2395: version, but you will need to run \c autoreconf \c -vi or deba@2395: \c ./bootstrap in some older environment before \c ./configure. See \c deba@2395: ./configure \c --help for options. For bootstrapping you will need the ladanyi@1637: following tools: ladanyi@1637: ladanyi@1637: - automake (1.7 or newer) ladanyi@1637: - autoconf (2.59 or newer) ladanyi@1637: - libtool ladanyi@1637: - pkgconfig ladanyi@1637: ladanyi@1637: To generate the documentation, run \c make \c doc. You will need ladanyi@1637: Doxygen for this. ladanyi@1637: ladanyi@1637: You can pass the \c --enable-doc=full flag to \c ./configure to generate the ladanyi@1637: internal documentation too. ladanyi@1637: ladanyi@1637: If you pass the \c --disable-doc flag to \c ./configure then the documentation ladanyi@1637: won't be installed, when you run \c make \c install (this speeds things up a ladanyi@1637: bit). athos@1175: athos@1173: \section helloworld My first program using LEMON athos@1173: klao@1519: If you have installed LEMON on your system you can paste the klao@1520: following code segment into a file (you can find it as \c klao@1520: demo/hello_lemon.cc in the LEMON package) to have a first working klao@1520: program that uses library LEMON. athos@1173: alpar@1640: \dontinclude hello_lemon.cc alpar@1640: \skip include alpar@1640: \until } athos@1175: athos@1514: First let us briefly explain how this program works. athos@1175: athos@1175: ListGraph is one of LEMON's graph classes. It is based on linked lists, athos@1175: therefore iterating throuh its edges and nodes is fast. athos@1175: alpar@1713: After some convenience typedefs we create a graph and add three nodes to it. athos@1175: Then we add edges to it to form a complete graph. athos@1175: athos@1175: Then we iterate through all nodes of the graph. We use a constructor of the athos@1175: node iterator to initialize it to the first node. The operator++ is used to athos@1175: step to the next node. Using operator++ on the iterator pointing to the last athos@1175: node invalidates the iterator i.e. sets its value to athos@1175: \ref lemon::INVALID "INVALID". This is what we exploit in the stop condition. athos@1175: athos@1175: We can also iterate through all edges of the graph very similarly. The athos@1175: \c target and athos@1175: \c source member functions can be used to access the endpoints of an edge. athos@1175: klao@1520: If your installation of LEMON into directory \c /usr/local was alpar@1713: successful, then it is very easy to compile this program with the klao@1520: following command (the argument -lemon tells the compiler klao@1520: that we are using the installed library LEMON): athos@1514: klao@1519: \verbatim klao@1519: g++ hello_lemon.cc -o hello_lemon -lemon klao@1519: \endverbatim klao@1519: klao@1519: As a result you will get the exacutable \c hello_lemon in athos@1514: this directory that you can run by the command klao@1519: \verbatim klao@1519: ./hello_lemon klao@1519: \endverbatim athos@1514: athos@1514: klao@1519: If everything has gone well then the previous code fragment prints klao@1519: out the following: athos@1175: klao@1519: \verbatim athos@1175: Nodes: 2 1 0 athos@1175: athos@1175: Edges: (0,2) (1,2) (0,1) (2,1) (1,0) (2,0) klao@1519: \endverbatim athos@1175: athos@1514: Congratulations! athos@1175: klao@1519: If you want to see more features, go to the klao@1519: \ref quicktour "Quick Tour to LEMON", klao@1519: if you want to see see some demo programs then go to our athos@1175: \ref demoprograms "Demo Programs" page! athos@1175: athos@1175: athos@1175: */