# Linking to beachmat from another package

Aaron Lun

#### 27 April 2020

#### Package

beachmat 2.4.0

# 1 Introduction

The 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 Matrix package, and disk-backed matrices from the HDF5Array package. This document describes how to link to beachmat from the C++ code of another R package.

# 2 Prerequisites for linking

The beachmat package currently has several dependencies:

- The compiler should support the C++11 standard. This usually requires GCC version 4.8.1 or higher. You need to tell the build system to use C++11, by modifying the `SystemRequirements` field of the `DESCRIPTION` file:

        SystemRequirements: C++11

- Rcpp should be installed. You also need to ensure that Rcpp is loaded when your package is loaded. This requires addition of `Rcpp` to the `Imports` field of the `DESCRIPTION` file:

       Imports: Rcpp

  … and a corresponding `importFrom` specification in the `NAMESPACE` file:

       importFrom(Rcpp, sourceCpp)

  (The exact function to be imported doesn’t matter, as long as the namespace is loaded. Check out the Rcpp documentation for more details.)

- DelayedArray and beachmat should be added to the `Suggests` field, as the API will perform some calls to R functions in those packages to query certain parameters.

        Suggests: beachmat, DelayedArray

# 3 Linking to the library

beachmat is a header-only library, so linking is as simple as writing:

    LinkingTo: Rcpp, beachmat

… in your `DESCRIPTION` file. Note that the Rcpp headers must also be included.

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

    system.file(package="beachmat", "include")

    ## [1] "/tmp/Rtmpy5yHU3/Rinst362f6e6c84c2/beachmat/include"

# 4 Common problems

- An `undefined symbol` error starting with `_ZN2H56H5FileC1ERKNSt7_...` usually indicates that Rhdf5lib was compiled with a different GCC version than beachmat-dependent libraries like HDF5Array, leading to incompatibilities in the binaries. This can usually be fixed by re-installing Rhdf5lib prior to installing beachmat.

- An `expected unqualified-id before 'using'` error. This means that the version of GCC used to compile beachmat is out of date and does not fully support C++11.

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.