---
title: "Linking to Rhdf5lib"
author:
- name: Mike L. Smith
  affiliation: de.NBI & EMBL Heidelberg
package: Rhdf5lib
output:
  BiocStyle::html_document
vignette: |
  %\VignetteIndexEntry{Linking to Rhdf5lib}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---
# Motivation

`r BiocStyle::Biocpkg("Rhdf5lib")` provides versions of the C and C++ HDF5 libraries. It is primarily useful to developers of other R packages who want to make use of the capabilities of the HDF5 library directly in the C or C++ code of their own packages, rather than using a higher level interface such as the [**rhdf5**](http://bioconductor.org/packages/rhdf5/) package.  Using **Rhdf5lib** makes life easier for users, as they do not have to worry about installing libraries at a system level, and for developers since they can work with a defined version of the library rather than developing strategies to cope with the potential for multiple versions.

**Rhdf5lib** is very much inspired by the [**zlibbioc**](http://bioconductor.org/packages/zlibbioc/) and [**Rhtslib**](http://bioconductor.org/packages/Rhtslib/) packages.

# Usage

There is an example package,
[**usingRhdf5lib**](https://github.com/grimbough/usingRhdf5lib), that
demonstrates how packages should link to **Rhdf5lib**.

## Link to the library

To link successfully to the HDF5 library included in **Rhdf5lib** a package must include *both* a `src/Makevars.win` *and* `src/Makevars` file.  

Add the following lines to both `src/Makevars` and `src/Makevars.win`

    RHDF5_LIBS=$(shell "${R_HOME}/bin${R_ARCH_BIN}/Rscript" -e \ 
        'Rhdf5lib::pkgconfig("PKG_C_LIBS")') 
    PKG_LIBS=$(RHDF5_LIBS)

Alternatively if using the C++ interface, please add the following lines instead:

    RHDF5_LIBS=$(shell "${R_HOME}/bin${R_ARCH_BIN}/Rscript" -e \ 
        'Rhdf5lib::pkgconfig("PKG_CXX_LIBS")') 
    PKG_LIBS=$(RHDF5_LIBS)

The statement for each platform modifies the `$PKG_LIBS` variable. If your package needs to add additional information to the `$PKG_LIBS` variable, do so by adding to the `PKG_LIBS=$(RHDF5_LIBS)` line, e.g.,

    PKG_LIBS=$(RHDF5_LIBS) -L/path/to/foolib -lfoo
    
*Note that the use of `$(shell ...)` necessitates using GNU Make, and you need to make this requirement explicit in your package's DESCRIPTION file via the entry:*

    SystemRequirements: GNU make
    
The default behaviour of `Rhdf5lib::pkgconfig()` is to report the location of the shared library as the result of `system.file("lib", package="Rhdf5lib")`.  If this is inappropriate for your system e.g. a cluster with a shared file system, use the environment variable `RHDF5LIB_RPATH` to override this and set an appropriate location for your infrastructure.

Valid options to provide to `pkgconfig()`  are: `PKG_C_LIBS`, `PKG_CXX_LIBS`, `PKG_C_HL_LIBS` and `PKG_CXX_HL_LIBS`.  Choose the most appropriate depending upon whether your linking code requires the C++ API (`C` vs `CXX`) and/or the HDF5 'high-level' API (`HL`).  Choosing options that you don't require should not harm performance, but will result in a larger library and potentially greater memory usage for your application, so it is good practice to select only the features you need.

## Locating the library headers

In order for the C/C++ compiler to find the HDF5 headers during package installation, add **Rhdf5lib** to the *LinkingTo* field of the DESCRIPTION file of your package, e.g.

    LinkingTo: Rhdf5lib

In you C or C++ code files, you can then use the standard include techniques, e.g., `#include "hdf5.h"` or `#include "H5Cpp.h"`.  You can inspect the header files manually to check their names and declared functions.  To find their location on your system you can use the following code:

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

# Configuration arguments for non-standard system setups

Because potential issues are likely to be different with the switch to a CMake build system, we start from a clean slate and have not implemented any of the configuration options that were available in the previous version of **Rhdf5lib**.  If you have a non-standard system setup and would like to see support for it, please open an issue on the GitHub repository for this package.

# Funding

MLS was supported by the BMBF-funded Heidelberg Center for Human Bioinformatics (HD-HuB) within the German Network for Bioinformatics Infrastructure ([de.NBI](https://www.denbi.de)), Grant Number #031A537B

![](de.NBI-Logo.PNG){ width=50% }

# Session info {.unnumbered}

```{r sessionInfo, echo=FALSE}
sessionInfo()
```
