Draft document for installation with cmake

This is a draft of the installation instructions with cmake. It will eventually replace https://igraph.org/c/#startc 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!


Prerequisites

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

  • CMake 3.16 or later
  • C and C++ compilers

Certain features also require the following libraries:

  • GMP, required for big integer arithmetic
  • 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:

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

Specific instructions for Windows

Microsoft Visual Studio

– TODO –

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

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_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.

There is something incomplete with BLAS/LAPACK detection. On success, it says so, but no info provided on which concrete installation is used.

Does it fail? Can you post the cmake output please?

If you look in the CMakeCache.txt file, you will be able to see which BLAS libraries it found, but not which ones it chose to use.

All macOS systems come with a BLAS/LAPACK implementation pre-installed. To use it, run cmake as

cmake .. -DBLA_VEDOR=Apple

More info here: https://cmake.org/cmake/help/latest/module/FindBLAS.html


The most fool-proof way to compile is to use all-vendored libraries, and disable those which are not vendored (i.e. GMP and libxml2 for GraphML support). It is easiest to run ccmake and set all the IGRAPH_USE_INTERNAL flags to ON (left-right key), disable GMP support and disable GraphML support.

Correction: it does in fact output the BLAS it uses (it outputs only that, even if it finds multiple).

On my machine, I see:

-- Found BLAS: /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.15.sdk/System/Library/Frameworks/Accelerate.framework  

or

-- Found BLAS: /opt/local/lib/libopenblas.dylib  

depending on what I have installed, but never both.

here is what I see

-- Version number from Git: 0.9.0-dev+c490d1c4
-- Detected Homebrew with install prefix: /usr/local, adding to CMake search paths.
-- A library with LAPACK API found.
-- Could NOT find ARPACK (missing: ARPACK_LIBRARY) 
-- Found GMP: /usr/local/include/gmp.h and /usr/local/lib/libgmp.dylib
-- Detected Homebrew with install prefix: /usr/local, adding to CMake search paths.
-- A library with LAPACK API found.
-- Found GMP: /usr/local/include/gmp.h and /usr/local/lib/libgmp.dylib
--  
-- -----[ Build configuration ]----
-- Version:      0.9.0-dev+c490d1c4
-- CMake build type:        default
-- Library type:             static
--  
-- ----------[ Features ]----------
-- GLPK for optimization:       yes
-- GMP for big integers:        yes
-- Reading GraphML files:       yes
-- Thread-local storage:         no
-- Link-time optimization:       no
--  
-- --------[ Dependencies ]--------
-- ARPACK:                 vendored
-- BISON:                       yes
-- BLAS:                        yes
-- CXSparse:                    yes
-- FLEX:                        yes
-- GLPK:                        yes
-- GMP:                         yes
-- LAPACK:                      yes
-- LibXml2:                     yes
--  
-- -----------[ Testing ]----------
-- Diff tool:                  diff
-- Sanitizers:                 none
-- Verify 'finally' stack:       no
--  
-- --------[ Documentation ]-------
-- HTML:                         no
-- PDF:                          no
--  
-- igraph configured successfully.
--  
-- Configuring done
-- Generating done
-- Build files have been written to: /Users/dima/software/igraph/build

as you see, BLAS found, LAPACK found, but where, is not clear.

Also, the info about GMP is printed twice!