Chapter 2. Installation

1. 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 (version 4.57 or later)
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.

2. Installation

2.1. General build instructions
2.2. Specific instructions for Windows
2.3. Notable configuration options

2.1. 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:
```
$ cmake ..
```
To set a non-default installation location, such as /opt/local, use:
```
cmake .. -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 or cmake-gui on Windows for a convenient interface.
- Simply edit the CMakeCache.txt file. Some of the relevant options are listed below.
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 .
```

2.2. Specific instructions for Windows

2.2.1. Microsoft Visual Studio
2.2.2. MSYS2

2.2.1. Microsoft Visual Studio

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 (typically Release or Debug) with each build command using the --config option:

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.

2.2.1.1. 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 integrate it in the build environment by executing vcpkg.exe integrate install on the command line. When configuring igraph, point CMake to the correct vcpkg.cmake file using -DCMAKE_TOOLCHAIN_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 when using shared builds of packages or x64-windows-static when using static builds. Similarly, you also need to specify this target triplet when installing packages. 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. In addition, there is the possibility to use a static library with dynamic runtime linking using the x64-windows-static-md triplet.

2.2.2. MSYS2

MSYS2 can be installed from 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-cmake package and not the cmake one. The latter will not work.
When running cmake, pass the option -G"MSYS Makefiles".
Note that ccmake is not currently available. cmake-gui can be used only if the mingw-w64-x86_64-qt5 package is installed.

2.3. 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_XXX flags control whether these should be used instead of external versions. Set them to ON to 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_OPENMP_SUPPORT: whether to use OpenMP parallelization to accelerate certain functions such as PageRank calculation. Compiler support is required.
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.
IGRAPH_WARNINGS_AS_ERRORS: whether to treat compiler warnings as errors. We strive to eliminate all compiler warnings during development so this switch is turned on by default. If your compiler prints warnings for some parts of the code that we did not anticipate, you can turn off this option to prevent the warnings from stopping the compilation.
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.

3. Building the documentation

Most users will not need to build the documentation, as the release tarball contains pre-built HTML documentation in the doc directory.

To build the documentation for the development version, simply build the html or pdf targets for the HTML and PDF versions of the documentation, respectively.

$ cmake --build . --target html

Building the HTML documentation requires Python 3, xmlto and source-highlight. Building the PDF documentation also requires xsltproc, xmllint and fop.

4. Notes for package maintainers

4.1. Auto-detection of dependencies
4.2. Shared and static builds
4.3. Cross-compiling
4.4. Additional notes

This section is for people who package igraph for Linux distros or other package managers. Please read it carefully before packaging igraph.

4.1. Auto-detection of dependencies

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. This should be the same BLAS and LAPACK library that igraph's other dependencies, such as ARPACK and CXSparse are linked against.

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=OFF \
    -DIGRAPH_USE_INTERNAL_LAPACK=OFF \
    -DIGRAPH_USE_INTERNAL_ARPACK=OFF \
    -DIGRAPH_USE_INTERNAL_GLPK=OFF \
    -DIGRAPH_USE_INTERNAL_CXSPARSE=OFF \
    -DIGRAPH_USE_INTERNAL_GMP=OFF \
    -DBLA_VENDOR=OpenBLAS \
    -DIGRAPH_GRAPHML_SUPPORT=ON

4.2. Shared and static builds

On Windows, shared and static builds should not be installed in the same location. If you decide to do so anyway, keep in mind the following: Both builds contain an igraph.lib file. The static one should be renamed to avoid conflict. The headers from the static build are incompatible with the shared library. The headers from the shared build may be used with the static library, but IGRAPH_STATIC must be defined when compiling programs that will link to igraph statically.

These issues do not affect Unix-like systems.

4.3. Cross-compiling

When building igraph with an internal ARPACK, LAPACK or BLAS, it makes use of f2c, which compiles and runs the arithchk program at build time to detect the floating point characteristics of the current system. It writes the results into the arith.h header. Since running this program is not possible when cross-compiling, igraph's build system allows specifying a pre-generated version of this header file through the F2C_EXTERNAL_ARITH_HEADER CMake option. An example version of this header follows for the x86_64 and arm64 target architecures on macOS. Warning: Do not use this version of arith.h on other systems or architectures.

#define IEEE_8087
#define Arith_Kind_ASL 1
#define Long int
#define Intcast (int)(long)
#define Double_Align
#define X64_bit_pointers
#define NANCHECK
#define QNaN0 0x0
#define QNaN1 0x7ff80000

4.4. 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 optimization noticeably improves the performance of some igraph functions. To enable it, use -DIGRAPH_ENABLE_LTO=ON. The AUTO setting is also supported, and will enable link-time optimization only if the current compiler supports it. Note that this is detected by CMake, and the detection is not always accurate.
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.