igraph 参考手册

用于使用 igraph C 库

搜索手册

第 2 章。 安装

本章描述如何从源代码构建和安装 igraph。最新稳定版本的源代码存档始终可以从 igraph 网站获取。igraph 也包含在许多 Linux 发行版中,以及一些包管理器中,如vcpkg(在 Windows 上很方便),MacPorts(macOS)和Homebrew(macOS),这些提供了更简单的安装方式。如果您决定使用它们,请查阅它们的文档以了解如何安装软件包。

1. 前提条件

要从源代码构建 igraph,您至少需要

  • CMake 3.18 或更高版本

  • C 和 C++ 编译器

支持 Visual Studio 2015 及更高版本。早期版本的 Visual Studio 可能可以工作,也可能无法工作。

某些功能还需要以下库

igraph 为了方便起见捆绑了一些库。但是,最好使用这些库的外部版本,这可以提高性能。这些是

  • GMP(捆绑的替代方案是 Mini-GMP)

  • GLPK(4.57 或更高版本)

  • ARPACK

  • plfit

  • 提供BLAS API 的库(macOS 上默认可用;OpenBLAS 是其他系统上的一个选项)

  • 提供LAPACK API 的库(macOS 上默认可用;OpenBLAS 是其他系统上的一个选项)

构建 igraph 的开发版本时,还需要bisonflexgit。发布的版本不需要这些工具。

要运行测试,还需要diff

2. 安装

2.1. 一般构建说明

igraph 使用基于 CMake 的构建系统。要编译它,

  • 进入 igraph 源代码所在的目录

    $ cd igraph
    

  • 创建一个新目录。这是 igraph 将要构建的地方

    $ mkdir build
    $ cd build
    

  • 运行 CMake,它会自动配置 igraph,并报告配置

    $ cmake ..
    

    要设置非默认安装位置,例如 /opt/local,请使用

    cmake .. -DCMAKE_INSTALL_PREFIX=/opt/local

  • 仔细检查输出,并确保所有您需要的功能都已启用。如果 CMake 无法找到某些库,某些功能(如 GraphML 支持)可能已被自动禁用。

  • 有几种方法可以调整配置

    • 在类 Unix 系统上运行 ccmake .,或在 Windows 上运行 cmake-gui 以获得方便的界面。

    • 只需编辑 CMakeCache.txt 文件。下面列出了一些相关的选项。

  • 一旦配置被调整,再次运行 cmake ..

  • 一旦 igraph 成功配置,就可以使用以下命令构建、测试和安装它

    $ cmake --build .
    $ cmake --build . --target check
    $ cmake --install .
    

2.2. Windows 的具体说明

2.2.1. Microsoft Visual Studio

使用 Visual Studio,构建 igraph 的步骤通常与上面相同。但是,由于 Visual Studio CMake 生成器是一个多配置生成器,我们必须使用 --config 选项为每个构建命令指定配置(通常是 Release 或 Debug)

mkdir build
cd build
cmake ..
cmake --build . --config Release
cmake --build . --target check --config Release

构建开发版本时,系统上必须提供 bisonflexwinflexbison(Bison 3.x 版本)可能对此有用——确保可执行文件在系统 PATH 中。最简单的安装选项可能是从Chocolatey 包管理器安装 winflexbison3

2.2.1.1. vcpkg

大多数外部依赖项可以使用 vcpkg 方便地安装。请注意,igraph 捆绑了除 libxml2 之外的所有依赖项,这是 GraphML 支持所需要的。

为了使用 vcpkg,通过在命令行上执行 vcpkg.exe integrate install 将其集成到构建环境中。配置 igraph 时,按照说明使用 -DCMAKE_TOOLCHAIN_FILE=... 将 CMake 指向正确的 vcpkg.cmake 文件。

此外,在运行 cmake 时,您可能需要使用 -DVCPKG_TARGET_TRIPLET 设置适当的三元组,例如,在使用包的共享构建时将其设置为 x64-windows,或者在使用静态构建时将其设置为 x64-windows-static。同样,在安装包时,您还需要指定此目标三元组。例如,要将 libxml2 安装为共享库,请使用 vcpkg.exe install libxml2:x64-windows,要将 libxml2 安装为静态库,请使用 vcpkg.exe install libxml2:x64-windows-static。此外,还可以使用带有动态运行时链接的静态库,使用 x64-windows-static-md 三元组。

2.2.2. MSYS2

可以从 msys2.org 安装 MSYS2。安装 MSYS2 后,通过打开终端并运行 pacman -Syuu 来确保它是最新的。

以下说明假定您要为 64 位目标进行编译。

使用 pacman -S 安装以下软件包。

  • 最低要求:mingw-w64-x86_64-toolchainmingw-w64-x86_64-cmake

  • 启用某些功能的可选依赖项:mingw-w64-x86_64-gmpmingw-w64-x86_64-libxml2

  • 用于获得更好性能的可选外部库:mingw-w64-x86_64-openblasmingw-w64-x86_64-arpackmingw-w64-x86_64-glpk

  • 仅运行测试需要:diffutils

  • 仅在构建开发版本时需要:gitbisonflex

以下命令将一次安装所有这些

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

为了构建 igraph,请按照上面的一般构建说明,并注意以下几点

  • 使用 MSYS2 时,启动MSYS2 MinGW 64-bit终端,而不是MSYS2 MSYS终端。

  • 请务必安装 mingw-w64-x86_64-cmake 软件包,而不是 cmake 软件包。后者将不起作用。

  • 运行 cmake 时,传递选项 -G"MSYS Makefiles"

  • 请注意,ccmake 当前不可用。只有在安装了 mingw-w64-x86_64-qt5 软件包后才能使用 cmake-gui

2.3. 值得注意的配置选项

以下选项可以设置为 ONOFF。其中一些选项具有 AUTO 设置,该设置根据当前系统上可用的库选择合理的默认值。

  • igraph 为了方便起见捆绑了一些依赖项。IGRAPH_USE_INTERNAL_XXX 标志控制是否应该使用这些依赖项而不是外部版本。将它们设置为 ON 以使用捆绑的(vendored)版本。一般来说,外部版本更可取,因为它们可能更新,并且通常提供更好的性能。

  • IGRAPH_GLPK_SUPPORT:是否利用 GLPK 库。某些功能(如查找最小反馈弧集或通过精确的模块化优化查找社区)需要此库。

  • IGRAPH_GRAPHML_SUPPORT:是否启用对读取和写入 GraphML 文件的支持。需要 libxml2 库。

  • IGRAPH_OPENMP_SUPPORT:是否使用 OpenMP 并行化来加速某些功能,如 PageRank 计算。需要编译器支持。

  • IGRAPH_ENABLE_LTO:是否使用链接时优化构建 igraph,这可以提高性能。并非所有编译器都支持。

  • IGRAPH_ENABLE_TLS:是否启用线程本地存储。从多个线程使用 igraph 时需要。

  • IGRAPH_WARNINGS_AS_ERRORS:是否将编译器警告视为错误。我们努力消除开发过程中的所有编译器警告,因此默认情况下会启用此开关。如果您的编译器为某些我们未预料到的代码部分打印警告,您可以关闭此选项以防止警告停止编译。

  • BUILD_SHARED_LIBS:是否构建共享库而不是静态库。

  • BLA_VENDOR:控制要使用哪个库来实现 BLASLAPACK 功能。

  • CMAKE_INSTALL_PREFIX:igraph 的安装位置。

3. 构建文档

大多数用户不需要构建文档,因为发布 tarball 包含 doc 目录中预先构建的 HTML 文档。

要构建开发版本的文档,只需分别构建 HTML、PDF 和 Info 版本的文档的 htmlpdfinfo 目标。

$ cmake --build . --target html

构建 HTML 文档需要 Python 3、xmltosource-highlight。构建 PDF 文档还需要 xsltprocxmllintfop。构建 Texinfo 文档还需要 docbook2X 软件包、xmllintmakeinfo

4. 给包维护者的提示

本节适用于为 Linux 发行版或其他包管理器打包 igraph 的人员。在打包 igraph 之前,请仔细阅读。

4.1. 依赖项的自动检测

igraph 捆绑了它的几个依赖项(或依赖项的简化版本)。在配置时,它会检查每个依赖项是否存在于系统上。如果存在,则使用它。否则,它会回退到捆绑的(vendored)版本。为了使配置尽可能具有确定性,您可能需要禁用此自动检测。为此,请设置上面描述的每个 IGRAPH_USE_INTERNAL_XXX 选项。此外,设置 BLA_VENDOR 以使用您选择的 BLAS 和 LAPACK 实现。这应该与 igraph 的其他依赖项(例如,ARPACK)链接的 BLAS 和 LAPACK 库相同。

例如,要强制 igraph 使用除 plfit 之外的所有依赖项的外部版本,并使用 OpenBLAS 用于 BLAS/LAPACK,请使用

$ 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. 共享和静态构建

在 Windows 上,共享和静态构建不应安装在同一位置。如果您决定这样做,请记住以下几点:两个构建都包含一个 igraph.lib 文件。静态文件应该重命名以避免冲突。静态构建中的头文件与共享库不兼容。共享构建中的头文件可以与静态库一起使用,但是在编译将静态链接到 igraph 的程序时必须定义 IGRAPH_STATIC

这些问题不会影响类 Unix 系统。

4.3. 交叉编译

在使用内部 ARPACK、LAPACK 或 BLAS 构建 igraph 时,它会使用 f2c,它在构建时编译并运行 arithchk 程序,以检测当前系统的浮点特征。它将结果写入 arith.h 头文件中。但是,在不提供可以在主机系统上运行目标平台的可执行文件的用户空间模拟器的情况下进行交叉编译时,无法运行此程序。因此,在交叉编译时,您需要使用 CMAKE_CROSSCOMPILING_EMULATOR 选项提供这样的模拟器,或者您需要通过 F2C_EXTERNAL_ARITH_HEADER CMake 选项指定预生成的 arith.h 头文件版本。以下是 macOS 上 x86_64 和 arm64 目标体系结构的此头文件的示例版本。警告:请勿在其他系统或体系结构上使用此版本的 arith.h

#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 还会检查 uint64_t 的字节序是否与正在编译的平台上 double 的字节序匹配。这是为了确保 igraph 的随机数生成器中的某些函数正常工作。但是,如果没有模拟器,则无法在交叉编译时执行此检查,因此在这种情况下,igraph 只是假设字节序匹配(无论如何,这对于绝大多数平台都是如此)。您可能遇到问题的唯一情况是从基于 Intel 的 Mac 为 Apple Silicon(arm64)进行交叉编译,在这种情况下,CMake 可能无法意识到您正在进行交叉编译,并且仍然会尝试执行检查。您可以通过在调用 CMake 之前将 IEEE754_DOUBLE_ENDIANNESS_MATCHES 显式设置为 ON 来解决此问题。

CMAKE_CROSSCOMPILING_EMULATOR 中提供模拟器还有一个好处,您可以运行主机平台上编译的单元测试。我们已经尝试过在 64 位 Intel CPU(amd64)上交叉编译到 64 位 ARM CPU(aarch64),我们可以确认在此设置中使用 qemu-aarch64 作为交叉编译模拟器有效。

4.4. 附加说明

  • 从 igraph 0.10 开始,使用外部 GMP 没有明显的好处,因为 igraph 尚未以任何性能关键的方式使用 GMP。捆绑的 Mini-GMP 就足够了。

  • 链接时优化显着提高了某些 igraph 函数的性能。要启用它,请使用 -DIGRAPH_ENABLE_LTO=ONAUTO 设置也受支持,并且仅在当前编译器支持链接时优化时才启用链接时优化。请注意,这是由 CMake 检测的,并且检测并非总是准确的。

  • 我们看到在 Windows 上使用 MinGW 为 32 位目标构建 igraph 并链接到 OpenBLAS 时偶尔会出现挂起。我们认为这是 OpenBLAS 的问题,而不是 igraph 的问题。在此平台上,您可能希望选择不同的 BLAS/LAPACK 或捆绑的 BLAS/LAPACK。