---
title: Packaging the igraph C library
author:
- name: Aaron Lun
  email: infinite.monkeys.with.keyboards@gmail.com
date: "Revised: December 7, 2025"
output:
  BiocStyle::html_document
package: Rigraphlib
vignette: >
  %\VignetteIndexEntry{Using the igraph C library}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, echo=FALSE, results="hide", message=FALSE}
require(knitr)
opts_chunk$set(error=FALSE, message=FALSE, warning=FALSE)

library(BiocStyle)
self <- Biocpkg("Rigraphlib")
```

# Overview

`r self` builds the **igraph** static library for use in R/Bioconductor packages.
This is primarily intended for R packages that wrap other C/C++ libraries that depend on the **igraph** C library
and cannot easily be modified to use the usual `r CRANpkg("igraph")` R package.
By vendoring in the source code, we also reduce our susceptibility to out-of-release-schedule changes in results due to `r CRANpkg("igraph")` updates.
This also allows developers to access functionality that might yet not be available from the R bindings.

Currently, this package contains version `r Rigraphlib::version(TRUE)` of the C **igraph** library.

# Quick start

Downstream package developers can use `r self` by adding:

```
Imports: Rigraphlib
```

to their package `DESCRIPTION`, and setting:

```bash
RIGRAPH_FLAGS=$(shell "${R_HOME}/bin${R_ARCH_BIN}/Rscript" -e 'Rigraphlib::pkgconfig("PKG_CPPFLAGS")')
PKG_CPPFLAGS=$(RIGRAPH_FLAGS)
RIGRAPH_LIBS=$(shell "${R_HOME}/bin${R_ARCH_BIN}/Rscript" -e 'Rigraphlib::pkgconfig("PKG_LIBS")')
PKG_LIBS=$(RIGRAPH_LIBS) $(LAPACK_LIBS) $(BLAS_LIBS) $(FLIBS) 
```

in their `src/Makevars`.
We use R's own BLAS and LAPACK libraries to avoid redundant recompilation of **igraph**'s vendored copies.

# For R administrators

If the `RIGRAPHLIB_PKG_CPPFLAGS` environment is set, its contents will be printed by `pkgconfig("PKG_CPPFLAGS")`.
Similarly, if the `RIGRAPHLIB_PKG_LIBS` environment is set, its contents will be printed by `pkgconfig("PKG_LIBS")`.
These take precedence over any other options or environment variables.

If the `RIGRAPHLIB_USE_SYSTEM_LIBRARY` environment variable is set to 1 during or after installation of `r self`,
`pkgconfig()` will instead call `pkg-config igraph` to link to the system **igraph** installation.
In addition, if this environment variable is set during `r self` installation,
the vendored source code will not be compiled unless the `RIGRAPHLIB_FORCE_BUILD` environment variable is set to 1.

In both cases, the version of **igraph** referenced by any custom flags should be consistent with the version of the vendored **igraph** source.
This ensures that downstream packages based on `r self` will build and run as expected.

# Session information {-}

```{r}
sessionInfo()
```