---
title: "Linking to beachmat from another package"
author: "Aaron Lun"
package: beachmat
output: 
  BiocStyle::html_document:
    toc_float: yes
vignette: >
  %\VignetteIndexEntry{1. Linking to beachmat from another package}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}  
---

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

# Introduction

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:

- 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

-  `r CRANpkg("Rcpp")` should be installed.
You also need to ensure that `r CRANpkg("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 `r CRANpkg("Rcpp")` documentation for more details.)

- `r Biocpkg("DelayedArray")` and  `r Biocpkg("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

# Linking to the library

`r Biocpkg("beachmat")` is a header-only library, so linking is as simple as writing:

```
LinkingTo: Rcpp, beachmat
```

... in your `DESCRIPTION` file. 
Note that the `r CRANpkg("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 `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

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

- An `expected unqualified-id before 'using'` error.
This means that the version of GCC used to compile `r Biocpkg("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](https://support.bioconductor.org), labelled with the _beachmat_ tag.
This is the preferred avenue for questions.
New users are advised to read the [posting guide](https://www.bioconductor.org/help/support/posting-guide/) before creating a post.