Linking to beachmat from another package

opts_chunk$set(error=FALSE, message=FALSE, warning=FALSE)


The r Biocpkg("beachmat") package provides a C++ API for handling a variety of R matrix types. The aim is to abstract away the specific type of matrix object when writing C++ extensions, thus simplifying the processing of data stored in those objects. Currently, the API supports double-precision, integer, logical and character matrices. Supported classes include base matrix objects, a number of classes from the r CRANpkg("Matrix") package, and disk-backed matrices from the r Biocpkg("HDF5Array") package. This document describes how to link to r Biocpkg("beachmat") from the C++ code of another R package.

Prerequisites for linking

The beachmat package currently has several dependencies:

Linking to the library

To link successfully to the beachmat library, a package must include both a src/ and src/Makevars file.

Note: the contents of src/ and src/Makevars are almost identical, but not quite. Be careful of the differences.

Create a src/ file with the following lines:

BEACHMAT_LIBS=$(shell echo 'beachmat::pkgconfig("PKG_LIBS")'|\
    "${R_HOME}/bin/R" --vanilla --slave)

... and a src/Makevars file with the following lines:

BEACHMAT_LIBS=`echo 'beachmat::pkgconfig("PKG_LIBS")'|\
    "${R_HOME}/bin/R" --vanilla --slave`

The statement for each platfrom modifies the $PKG_LIBS variable. If your package needs to add to the $PKG_LIBS variable, do so by adding to the PKG_LIBS=$(BEACHMAT_LIBS) line. For example:

PKG_LIBS=$(BEACHMAT_LIBS) -L/path/to/foolib -lfoo

The Linux implementation embeds the location of the beachmat library in the package-specific shared object via the compiler flag -Wl,rpath,path, where path is determined by system.file("lib", package="beachmat"). The path determined by system.file() is from .libPaths() and will resolve all symbolic links. This can cause problems, e.g., when the "head" node of a cluster mimicks the cluster node via a symbolic link to the directory in which beachmat is installed. Use the environment variable BEACHMAT_RPATH to resolve this by setting it to the cluster-node accessible path. Similar arguments apply to r Biocpkg("Rhdf5lib") with the environment variable RHDF5LIB_RPATH.

Including the headers

In order for the C/C++ compiler to find the beachmat package headers during installation, add the following to the LinkingTo field of the DESCRIPTION file:

LinkingTo: Rcpp, Rhdf5lib, beachmat

In C or C++ code files, use standard techniques to include header definitions, e.g., #include "beachmat/numeric_matrix.h" (see r Biocpkg("beachmat", vignette="input.html", label="here") for more details). Header files are available for perusal at the following location (enter in an R session):

{R headers} system.file(package="beachmat", "include")

Common problems

Users can ask for help by making a post on the Bioconductor support site, labelled with the beachmat tag. This is the preferred avenue for questions. New users are advised to read the posting guide before creating a post.

Try the beachmat package in your browser

Any scripts or data that you put into this service are public.

beachmat documentation built on Nov. 1, 2018, 4:22 a.m.