This is a draft of the installation instructions with cmake. It will eventually replace these instructions. igraph developers: Feel free to edit as needed.
Note to interested readers: igraph is an open-source project. All development happens in the open. If you want to test the development version, you can check out the develop branch and build it using the instructions below. Beware that changes happen quickly and regularly!
For the impatient
mkdir build && cd build
cmake ..
cmake --build .
cmake --install .
Prerequisites
To build igraph from sources, you will need at least:
- CMake 3.16 or later
- C and C++ compilers
Visual Studio 2015 and later are supported. Earlier Visual Studio versions may or may not work.
Certain features also require the following libraries:
- libxml2, required for GraphML support
igraph bundles a number of libraries for convenience. However, it is preferable to use external versions of these libraries, which may improve performance. These are:
- GMP (the bundled alternative is Mini-GMP)
- GLPK
- ARPACK
- CXSparse from SuiteSparse
- A library providing a BLAS API (available by default on macOS; OpenBLAS is one option on other systems)
- A library providing a LAPACK API (available by default on macOS; OpenBLAS is one option on other systems)
When building the development version of igraph, bison, flex and git are also required. Released versions do not require these tools.
To run the tests, diff is also required.
Installation
General build instructions
igraph uses a CMake-based build system. To compile it,
- Enter the directory where the igraph sources are:
cd igraph - Create a new directory. This is where igraph will be built:
mkdir build cd build - Run cmake, which will automatically configure igraph, and report the configuration:
To set a non-default installation location, such ascmake ../opt/local, usecmake .. -DCMAKE_INSTALL_PREFIX=/opt/local - Check the output carefully, and ensure that all features you need are enabled. If cmake could not find certain libraries, some features such as GraphML support may have been automatically disabled.
- There are several ways to adjust the configuration:
- Run
ccmake .on Unix-like systems orcmake-guion Windows for a convenient interface. - Simply edit the
CMakeCache.txtfile. Some of the relevant options are listed below.
- Run
- Once the configuration has been adjusted, run
cmake ..again. - Once igraph has been successfully configured, it can be built, tested and installed using:
cmake --build . cmake --build . --target check cmake --install .
Specific instructions for Windows
Microsoft Visual Studio
– TODO –
With Visual Studio, the steps to build igraph are generally the same as above. However, since the Visual Studio CMake generator is a multi-configuration one, we must specify the configuration with each build command using the --config Release option:
When compiling with Visual Studio, we must specify the configuration (Release or Debug) and separate building and running the tests. To build igraph in Release configuration, first configure it:
mkdir build
cd build
cmake ..
cmake --build . --config Release
cmake --build . --target check --config Release
When building the development version, bison and flex must be available on the system. winflexbison for Bison version 3.x can be useful for this purpose—make sure that the executables are in the system PATH. The easiest installation option is probably by installing winflexbison3 from the Chocolatey package manager.
vcpkg
Most external dependencies can be conveniently installed using vcpkg. Note that igraph bundles all dependencies except libxml2, which is needed for GraphML support.
In order to use vcpkg, please integrate the vcpkg in the build environment by executing vcpkg.exe integrate install. Please note that you should add the -DCMAKE_TOOLCHAIN_FILE to point to the correct vcpkg.cmake file, as instructed.
Additionally, it might be that you need to set the appropriate so-called triplet using -DVCPKG_TARGET_TRIPLET when running cmake, for exampling, setting it to x64-windows for shared builds or x64-windows-static for static builds. Similarly, you also need to specify this target triplet when installing pacakges. For example, to install libxml2 as a shared library, use vcpkg.exe install libxml2:x64-windows and to install libxml2 as a static library, use vcpkg.exe install libxml2:x64-windows-static.
For some external libraries with vcpkg, there are some known issues. When building with an external suitesparse shared library, the suitesparse library is not copied over to the build directory, resulting in failing tests, see issue #1492. When building against OpenBLAS, this results a few differences in some unit tests, see issue #1491.
MSYS2
MSYS2 can be installed from www.msys2.org. After installing MSYS2, ensure that it is up to date by opening a terminal and running pacman -Syuu.
The instructions below assume that you want to compile for a 64-bit target.
Install the following packages using pacman -S.
- Minimal requirements:
mingw-w64-x86_64-toolchain,mingw-w64-x86_64-cmake. - Optional dependencies that enable certain features:
mingw-w64-x86_64-gmp,mingw-w64-x86_64-libxml2 - Optional external libraries for better performance:
mingw-w64-x86_64-openblas,mingw-w64-x86_64-suitesparse,mingw-w64-x86_64-arpack,mingw-w64-x86_64-glpk - Only needed for running the tests:
diffutils - Required only when building the development version:
git,bison,flex
The following command will install of these at once:
pacman -S \
mingw-w64-x86_64-toolchain mingw-w64-x86_64-cmake \
mingw-w64-x86_64-gmp mingw-w64-x86_64-libxml2 \
mingw-w64-x86_64-openblas mingw-w64-x86_64-suitesparse mingw-w64-x86_64-arpack mingw-w64-x86_64-glpk \
diffutils \
git bison flex
In order to build igraph, follow the General build instructions above, paying attention to the following:
- When using MSYS2, start the “MSYS2 MinGW 64-bit” terminal, and not the “MSYS2 MSYS” one.
- Be sure to install the
mingw-w64-x86_64-cmakepackage and not thecmakeone. The latter will not work. - When running
cmake, pass the option-G"MSYS Makefiles". - Note that
ccmakeis not currently available.cmake-guican be used only if themingw-w64-x86_64-qt5package is installed.
Notable configuration options
The following options may be set to ON or OFF. Some of them have an AUTO setting, which chooses a reasonable default based on what libraries are available on the current system.
-
igraph bundles some of its dependencies for convenience. The
IGRAPH_USE_INTERNAL_XXXflags control whether these should be used instead of external versions. Set them toONto use the bundled (“vendored”) versions. Generally, external versions are preferable as they may be newer and usually provide better performance. -
IGRAPH_GLPK_SUPPORT: whether to make use of the GLPK library. Some features, such as finding a minimum feedback arc set or finding communities through exact modularity optimization, require this. -
IGRAPH_GRAPHML_SUPPORT: whether to enable support for reading and writing GraphML files. Requires the libxml2 library. -
IGRAPH_ENABLE_LTO: whether to build igraph with link-time optimization, which improves performance. Not supported with all compilers. -
IGRAPH_ENABLE_TLS: whether to enable thread-local storage. Required when using igraph from multiple threads. -
BUILD_SHARED_LIBS: whether to build a shared library instead of a static one. -
BLA_VENDOR: controls which library to use for BLAS and LAPACK functionality. -
CMAKE_INSTALL_PREFIX: the location where igraph will be installed
Compiling programs that use igraph
If igraph was built as a static library on Windows, it is necessary to define IGRAPH_STATIC when building programs that will link to igraph.
Notes for package maintainers
This section is for people who package igraph for Linux distros or other package managers.
igraph bundles several of its dependencies (or simplified versions of its dependencies). During configuration time, it checks whether each dependency is present on the system. If yes, it uses it. Otherwise, it falls back to the bundled (“vendored”) version. In order to make configuration as deterministic as possible, you may want to disable this auto-detection. To do so, set each of the IGRAPH_USE_INTERNAL_XXX option described above. Additionally, set BLA_VENDOR to use the BLAS and LAPACK implementations of your choice.
For example, to force igraph to use external versions of all dependencies, and to use OpenBLAS for BLAS/LAPACK, use
cmake .. -DIGRAPH_USE_INTERNAL_BLAS=0 -DIGRAPH_USE_INTERNAL_LAPACK=0 -DIGRAPH_USE_INTERNAL_ARPACK=0 -DIGRAPH_USE_INTERNAL_GLPK=0 -DIGRAPH_USE_INTERNAL_CXSPARSE=0 -DIGRAPH_USE_INTERNAL_GMP=0 -DBLA_VENDOR=OpenBLAS -DIGRAPH_GRAPHML_SUPPORT=1
Additional notes:
- As of igraph 0.9, there is no tangible benefit to using an external GMP, as igraph does not yet use GMP in any performance-critical way. The bundled Mini-GMP is sufficient.
- Link-time optimizaton noticeably improved the performance of some igraph functions. To enable it, use
-DIGRAPH_ENABLE_LTO=1. - We saw occasional hangs on Windows when igraph was built for a 32-bit target with MinGW and linked to OpenBLAS. We believe this to be an issue with OpenBLAS, not igraph. On this platform, you may want to opt for a different BLAS/LAPACK or the bundled BLAS/LAPACK.