Skip to content

2. Installation

We now describe how abLEMON is obtained, either as a package or from the sources, how a program finds it once it is installed, and which of its parts are optional; a first program, which only needs a compiler and the headers, is described in chapter 3. Most of abLEMON is made of templates, and therefore lives in its headers. The compiled library (libemon, a name kept from LEMON) holds the few parts that are not templates, i.e., the random number generator, the parser of the command line, the colors of graph_to_eps.h, the default tolerances of tolerance.h, the locking on Windows and, when they are enabled, the interfaces to the LP and MIP solvers of chapter 20.

2.1 Packages

The recipes of the packages are in packaging/ of the repository, and each release brings them to the archive of its tag (the workflow release.yml does so, after taking the notes of the release from NEWS). The Homebrew tap of the project works on macOS and Linux:

brew install dmeoli/ablemon/ablemon

Also, the recipes for conda-forge (package ablemon), vcpkg (port ablemon) and Conan have been submitted to the respective indices; at the time of writing (abLEMON 1.9.0) they are still under review. Until they are accepted, the recipes in packaging/ can be used locally, e.g., as an overlay of vcpkg (vcpkg install ablemon --overlay-ports=packaging/vcpkg). Each package installs the headers, the library and the CMake configuration of §2.3. None of them enables the LP and MIP backends of §2.4, which one builds from the sources when they are needed.

2.2 Building from the sources

Building needs CMake 3.19 or later and a compiler that supports C++11. In fact, the library compiles without warnings with GCC, Clang, AppleClang and MSVC (with the flags of the presets below), from C++11 to C++23 (the continuous integration builds each change on Linux, macOS and Windows with these compilers, and also under the address and undefined behavior sanitizers). The usual sequence configures the build directory by cmake -S . -B build -DCMAKE_BUILD_TYPE=Release, compiles by cmake --build build, runs the tests by ctest --test-dir build, and installs by cmake --install build --prefix /usr/local; the tests are those of test/ and the programs of this manual (the files of manual/examples/, which ctest names manual_*), and the installation follows GNUInstallDirs under the given prefix (e.g., the library goes to lib64 or to lib/x86_64-linux-gnu when the system wants it there).

Among the options, CMAKE_CXX_STANDARD is honored when it is set, and is 11 otherwise; BUILD_SHARED_LIBS builds a shared library (on Windows, a DLL). LEMON_BUILD_TESTS, LEMON_BUILD_DEMOS, LEMON_BUILD_TOOLS and LEMON_BUILD_DOC are ON by default, and each of them leaves out a part of the tree when it is OFF (the tests and the programs of the manual, the demos and the contributed programs, the tools, and the documentation, respectively). LEMON_BUILD_MODULE is OFF by default (cf. §2.3), and the four options of the LP and MIP backends are described in §2.4. The warning flags, which depend on the compiler, are not chosen by the build: they are those of LEMON_CXX_WARNING_FLAGS, empty by default (or the environment variable LEMON_CXX_WARNING), and the presets of CMakePresets.json give those of GCC and Clang (gcc-clang) and of MSVC (msvc, which also adds /bigobj and turns off C4250, the inheritance via dominance that the adaptors and the edge sets have by design, and C4996), each with a variant maintainer- that turns the warnings into errors. The version is the value given by -DLEMON_VERSION=..., if any (as the packages do), else the one of the environment variable LEMON_VERSION, else the tag that git describe gives for the sources. It is unknown when none of these exists. The build types Debug and Maintainer define LEMON_ENABLE_DEBUG, which turns on the checks of assert.h (cf. chapter 8); furthermore, Maintainer runs the tests at each build. A project may also take the library in by add_subdirectory() or by FetchContent, in which case only the library is configured, whatever the options say.

For a project built with GNU make, the makefiles of the repository build the library and the tests without a configuration step:

make -f makefile-lib            # lib/libemon.a
make -C test check              # the tests, built and run

Also, makefile-c, which the makefile of a project includes, defines the objects of the library (LEMONOBJ), the external libraries it needs (LEMONLIB), its headers (LEMONH) and the -I directive (LEMONINC); it takes as input the compiler, its options and the directory of the sources.

2.3 Using the installed library

A CMake project finds the installed library by its configuration, which find_package() accepts both as LEMON and as lemon:

find_package(LEMON CONFIG REQUIRED)
target_link_libraries(main PRIVATE LEMON::lemon)

Note that the target LEMON::lemon carries the include directories, the compile definitions and, when the library was built with them, the LP and MIP backends; the variables LEMON_INCLUDE_DIRS and LEMON_LIBRARIES are also set, for the projects that use variables instead of targets. When the version is a number, a version file is installed as well, so that find_package(LEMON 1.9) accepts any later version with the same major number. Also, the installation may be moved to another prefix, since the configuration only uses paths relative to it, and other build systems use pkg-config (pkg-config --cflags --libs lemon). The headers are included as <lemon/...>, and the library is in the namespace lemon, as in LEMON 1.3.1.

With -DLEMON_BUILD_MODULE=ON, the library is also built and installed as the C++20 module lemon, whose interface is lemon/lemon.cppm; a translation unit linked to LEMON::lemon_module may then write import lemon; in place of the includes. This needs CMake 3.28 or later, a generator and a compiler that build modules (e.g., Ninja with Clang 16 and its clang-scan-deps, or MSVC 19.34), and a compiler whose importers find the operators of the standard library that the templates of the module use: GCC (up to version 15, at least) builds the module, but a unit that imports it does not find them. The configuration builds a small module and a unit that imports it to tell (cmake/module-check), and when they do not build, or CMake is older, the option is turned off with a warning that says why.

2.4 Optional backends

The LP and MIP interface of chapter 20 needs at least one external solver: GLPK (LEMON_ENABLE_GLPK), CPLEX (LEMON_ENABLE_ILOG), CLP and CBC of COIN-OR (LEMON_ENABLE_COIN), or SoPlex (LEMON_ENABLE_SOPLEX). Each option is YES by default, i.e., the solver is used if CMake finds it, through its own CMake configuration where it has one. Those found are named by their file names in the installed configuration, so that a project that links LEMON::lemon also links them. The variables LEMON_DEFAULT_LP and LEMON_DEFAULT_MIP choose which of the solvers found the type aliases Lp and Mip of lemon/lp.h refer to; when they are not set, or name a solver that was not found, CMake takes the first one found in the order CPLEX, CLP (CBC for Mip), GLPK and SoPlex (which has no MIP). This choice is recorded in lemon/config.h, which CMake writes in the build directory, and whose macros LEMON_HAVE_LP and LEMON_HAVE_MIP tell a program whether there is a solver at all; when there is none, the two aliases are not defined, while the rest of the library is unaffected.

2.5 Exercises

Exercise 2.1. Build the library with -DCMAKE_CXX_STANDARD=20, run ctest --test-dir build -R manual_, and check that the programs of this manual pass. Then install the library to a temporary prefix, and build the program manual/examples/03-first-program.cc of chapter 3 against the installation, once with find_package(LEMON) and once with pkg-config.

Exercise 2.2. Configure the library on a machine where GLPK is installed, and check in the output of CMake and in lemon/config.h of the build directory which solver Lp and Mip refer to; the test lp_test exercises them.