---
title: "Motivation and use of _Rhtslib_"
author: "Nathaniel Hayden, Martin Morgan"
date: "Compiled `r doc_date()`;  Modified 12 March 2018"
package: "`r pkg_ver('Rhtslib')`"
abstract: >
  This package provides version 1.7 of the 'HTSlib' C library for
  high-throughput sequence analysis. The package is primarily useful
  to developers of other R packages who wish to make use of
  HTSlib. Motivation and instructions for use of this package are in
  this vignette.
vignette: >
  %\VignetteIndexEntry{Motivation and use of Rhtslib}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
output: 
  BiocStyle::html_document
---

# Motivation

`r Biocpkg("Rhtslib")` is an R package that provides the C `HTSlib`
library for high-throughput sequence data analysis. The library
provides APIs for creating, indexing, manipulating, and analyzing data
in SAM/BAM/CRAM sequence files and VCF/BCF2 variant files. See the
[HTSlib website](http://www.htslib.org/) for complete details and
documentation.

The `r Biocpkg("Rhtslib")` package is primarily useful to developers
of other R packages who want to use the HTSlib facilities in the C
code of their own packages.

## HTSlib version

The version of the included HTSlib is displayed at package load time,
but a user can also query the HTSlib version directly by calling
`Rhtslib:::htsVersion()` in an R session. The current version of the
package is `r (capture.output(Rhtslib:::htsVersion(), type="message"))`.

Effort is made to update the included version of HTSlib with minor
version releases from the HTSlib authors. If you notice the included
HTSlib is older than the current minor release of HTSlib, please
contact the `r Biocpkg("Rhtslib")` maintainer.

## Motivation

There are several advantages to using `Rhtslib`, rather than requiring
an explicit user system dependency on `htslib` directly.

- Using `Rhtslib` means that your users (who are not always
  sophisticated system administrators) do not need to manually install
  their own library.
- Your application uses a defined version of `htslib`, so that you as
  a developer can rely on presence of specific features (and bugs!)
  rather than writing code to manage different library versions.
  
# Use

There is an example package,
[`link2Rhtslib`](https://github.com/nhayden/link2Rhtslib), that
demonstrates how reverse dependencies should link to `Rhtslib`.

## Link to the library

To link successfully to the HTSlib included in `r Biocpkg("Rhtslib")`
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

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

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

    RHTSLIB_LIBS=`echo 'Rhtslib::pkgconfig("PKG_LIBS")'|\
        "${R_HOME}/bin/R" --vanilla --slave`
    PKG_LIBS=$(RHTSLIB_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=$(RHTSLIB_LIBS)` line, e.g.,

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

The Linux implementation embeds the location of the hts library in the
Rhtslib shared object via the compiler flag `-Wl,rpath,path`, where
path is determined by `system.file("usrlib", package="Rhtslib")`. The
path determined by `system.file()` is from `.libPaths()`, and has
resolved symbolic links to their actual path. 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 Rhtslib is installed. Use the
environment variable `RHTSLIB_RPATH` to resolve this by setting it to
the cluster-node accessible path.

## Find headers

In order for the C/C++ compiler to find HTSlib headers (and zlib
headers on Windows) during package installation, add `Rhtslib` and
`zlibbioc` to the `LinkingTo` field of the DESCRIPTION file of your
package, e.g.,

    LinkingTo: Rhtslib, zlibbioc

Note that as of R 3.0.2 `LinkingTo` values can include version
specifications, e.g., `LinkingTo: Rhtslib (>= 0.99.10)`.
    
In C or C++ code files, use standard techniques, e.g., `#include
"hts.h"`. Header files are available for perusal at (enter in an R
session)

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

# Implementation notes

`Rhtslib` provides both static and dynamic library versions of HTSlib
on Linux and Mac OS X platforms, but only the static version on
Windows. In most cases, for Linux and Mac OS X the procedure above
will link to the dynamic library version of HTSlib. Please let the
maintainer know if you run into issues with this strategy.