1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
|
---
title: "Motivation and use of _Rhtslib_"
author: "Nathaniel Hayden, Martin Morgan"
date: "Compiled `r doc_date()`; Modified 30 April 2022"
package: "`r pkg_ver('Rhtslib')`"
abstract: >
This package provides version 1.15.1 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
See the [`Rsamtools`](https://github.com/Bioconductor/Rsamtools) package
for an example of a package that compiles and links against `Rhtslib`.
## Find headers
In order for the C/C++ compiler to find HTSlib headers (and zlib
headers on Windows) during installation of your package, you must
add `Rhtslib` and `zlibbioc` to the `LinkingTo` field of its
`DESCRIPTION` file, 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
"htslib/hts.h"`. Header files are available for perusal at (enter
in an R session)
```{R headers}
system.file(package="Rhtslib", "include")
```
## Compile and link against the library
To compile and link your package successfully against the HTSlib included
in `r Biocpkg("Rhtslib")`, you must include a `src/Makevars` file.
Create a `src/Makevars` file with the following lines
RHTSLIB_LIBS=$(shell "${R_HOME}/bin${R_ARCH_BIN}/Rscript" -e \
'Rhtslib::pkgconfig("PKG_LIBS")')
RHTSLIB_CPPFLAGS=$(shell "${R_HOME}/bin${R_ARCH_BIN}/Rscript" -e \
'Rhtslib::pkgconfig("PKG_CPPFLAGS")')
PKG_LIBS=$(RHTSLIB_LIBS)
PKG_CPPFLAGS=$(RHTSLIB_CPPFLAGS)
Note that `$(shell ...)` is GNU make syntax so you should add `GNU make`
to the `SystemRequirements` field of the `DESCRIPTION` file of your package,
e.g.,
SystemRequirements: GNU make
The reason we use `$(shell echo ...)` rather than back-ticks (e.g.
`` `echo ...` ``) is because the latter causes problems when, after
evaluation, `PKG_LIBS` and/or `PKG_CPPFLAGS` contain paths with
whitespaces in them.
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
[comment]: # H.P. - May 3, 2019: We've switched to static linking on
[comment]: # Linux so this is no longer relevant.
[comment]: #
[comment]: # The Linux implementation embeds the location of the hts
[comment]: # library in the Rhtslib shared object via the compiler
[comment]: # flag `-Wl,rpath,path`, where path is determined by
[comment]: # `system.file("usrlib", package="Rhtslib")`. The
[comment]: # path determined by `system.file()` is from `.libPaths()`,
[comment]: # and has resolved symbolic links to their actual path.
[comment]: # This can cause problems, e.g., when the 'head' node of
[comment]: # a cluster mimicks the cluster node via a symbolic link to
[comment]: # the directory in which Rhtslib is installed. Use the
[comment]: # environment variable `RHTSLIB_RPATH` to resolve this by
[comment]: # setting it to the cluster-node accessible path.
# 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. The procedure above will link against the static library
version of HTSlib on all platforms.
|
