# Linking to Rhdf5lib
Date: 2017-10-30

Mike L. Smith1

1de.NBI & EMBL Heidelberg

#### 30 October 2017

#### Package

Rhdf5lib 1.0.0

# Contents

# 1 Motivation

Rhdf5lib provides 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 package. Using Rhdf5lib make 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.

Rhdf5 is very much inspired by the zlibbioc and Rhtslib packages.

# 2 Usage

There is an example package, usingRhdf5lib, that demonstrates how packages should link to Rhdf5lib.

## 2.1 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. Note: the contents of `src/Makevars.win` and `src/Makevars` are almost identical, but not quite. Be careful of the differences.

Create a `src/Makevars.win` file with the following lines

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

and a `src/Makevars` file with the following lines

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

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=$(RHDF5_LIBS)` line, e.g.,

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

## 2.2 Locating the library headers

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

    LinkingTo: Rhtslib

In you C or C++ code files, you can then use the standard include techniques, e.g., `#include "hdf5.h"` or `#include "c++/hdf5.h"`. C header files do not need a subfolder specified, while C++ headers are located under c++. 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:

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

    ## [1] "/tmp/RtmpFSRrIL/Rinst15b1695bb59d/Rhdf5lib/include"

# 3 Funding

MLS was supported by the BMBF-funded Heidelberg Center for Human Bioinformatics (HD-HuB) within the German Network for Bioinformatics Infrastructure (de.NBI), Förderkennzeichen #031A537B

# Session info

    ## R version 3.4.2 (2017-09-28)
    ## Platform: x86_64-pc-linux-gnu (64-bit)
    ## Running under: Ubuntu 16.04.3 LTS
    ##
    ## Matrix products: default
    ## BLAS: /home/biocbuild/bbs-3.6-bioc/R/lib/libRblas.so
    ## LAPACK: /home/biocbuild/bbs-3.6-bioc/R/lib/libRlapack.so
    ##
    ## locale:
    ##  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C
    ##  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=C
    ##  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8
    ##  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C
    ##  [9] LC_ADDRESS=C               LC_TELEPHONE=C
    ## [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
    ##
    ## attached base packages:
    ## [1] stats     graphics  grDevices utils     datasets  methods   base
    ##
    ## other attached packages:
    ## [1] BiocStyle_2.6.0
    ##
    ## loaded via a namespace (and not attached):
    ##  [1] compiler_3.4.2  backports_1.1.1 bookdown_0.5    magrittr_1.5
    ##  [5] rprojroot_1.2   htmltools_0.3.6 tools_3.4.2     yaml_2.1.14
    ##  [9] Rcpp_0.12.13    stringi_1.1.5   rmarkdown_1.6   knitr_1.17
    ## [13] stringr_1.2.0   digest_0.6.12   evaluate_0.10.1