igraph Reference Manual (original) (raw)

Chapter 2. Installation

This chapter describes building igraph from source code and installing it. The source archive of the latest stable release is always availablefrom the igraph website. igraph is also included in many Linux distributions, as well as several package managers such as vcpkg (convenient on Windows),MacPorts (macOS) andHomebrew (macOS), which provide an easier means of installation. If you decide to use them, please consult their documentation on how to install packages.

1. Prerequisites

To build igraph from sources, you will need at least:

Visual Studio 2015 and later are supported. Earlier Visual Studio versions may or may not work.

Certain features also require the following libraries:

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:

When building the development version of igraph,bison, flex andgit 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

igraph uses aCMake-based build system. To compile it,

2.2. Specific instructions for Windows

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 installingwinflexbison3 from theChocolatey package manager.

2.2.1.1. vcpkg

Most external dependencies can be conveniently installed usingvcpkg. 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 executingvcpkg.exe integrate install on the command line. When configuring igraph, point CMake to the correctvcpkg.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 runningcmake, for exampling, setting it tox64-windows when using shared builds of packages orx64-windows-static when using static builds. Similarly, you also need to specify this target triplet when installing packages. For example, to installlibxml2 as a shared library, usevcpkg.exe install libxml2:x64-windows and to install libxml2 as a static library, usevcpkg.exe install libxml2:x64-windows-static. In addition, there is the possibility to use a static library with dynamic runtime linking using thex64-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 runningpacman -Syuu.

The instructions below assume that you want to compile for a 64-bit target.

Install the following packages using pacman -S.

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

2.3. Notable configuration options

The following options may be set to ON orOFF. Some of them have an AUTO setting, which chooses a reasonable default based on what libraries are available on the current system.

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 thehtml, pdf or info targets for the HTML, PDF and Info 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 andfop. Building the Texinfo documentation also requires the docbook2X package, xmllint andmakeinfo.

4. Notes for package maintainers

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 options 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 (e.g., ARPACK) are linked against.

For example, to force igraph to use external versions of all dependencies except plfit, 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_GMP=OFF
-DIGRAPH_USE_INTERNAL_PLFIT=ON
-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. However, running this program is not possible when cross-compiling without providing a userspace emulator that can run executables of the target platform on the host system. Therefore, when cross-compiling, you either need to provide such an emulator with theCMAKE_CROSSCOMPILING_EMULATOR option, or you need to specify a pre-generated version of the arith.h header file through the F2C_EXTERNAL_ARITH_HEADER CMake option. An example version of this header follows for the x86_64 and arm64 target architectures 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

igraph also checks whether the endianness of uint64_t matches the endianness of double on the platform being compiled. This is needed to ensure that certain functions in igraph's random number generator work properly. However, it is not possible to execute this check when cross-compiling without an emulator, so in this case igraph simply assumes that the endianness matches (which is the case for the vast majority of platforms anyway). The only case where you might run into problems is when you cross-compile for Apple Silicon (arm64) from an Intel-based Mac, in which case CMake might not realize that you are cross-compiling and will try to execute the check anyway. You can work around this by settingIEEE754_DOUBLE_ENDIANNESS_MATCHES to ON explicitly before invoking CMake.

Providing an emulator in CMAKE_CROSSCOMPILING_EMULATOR has the added benefit that you can run the compiled unit tests on the host platform. We have experimented with cross-compiling to 64-bit ARM CPUs (aarch64) on 64-bit Intel CPUs (amd64), and we can confirm that using qemu-aarch64 works as a cross-compiling emulator in this setup.

4.4. Additional notes