%\VignetteIndexEntry{Using samtools C libraries}
%\VignetteDepends{}
%\VignetteKeywords{Short read, I/0, samtools}
%\VignettePackage{Rsamtools}
\documentclass{article}

<<style, echo=FALSE, results=tex>>=
BiocStyle::latex()
@
\newcommand{\bam}{\texttt{BAM}}

\title{Using samtools C libraries with \Biocpkg{Rsamtools}}
\author{Martin Morgan}
\date{Modified: 20 March, 2015. Compiled: \today}

\begin{document}

\maketitle

\tableofcontents

This document is meant for package developers wanting to use the
\href{http://samtools.sourceforge.net/}{samtools} C libraries provided
by \Biocpkg{Rsamtools}. The instructions here are based on the
`Writing R Extensions' manual associated with R-2.13; consult the
current version of the manual for up-to-date instructions.

\section{Background}

\Biocpkg{Rsamtools} arranges to install static versions of the
\verb|libbam| and \verb|libbcf| libraries. The idea is that other
packages can use these to implement C functionality that uses these
libraries. This means that the samtools libraries are available in a
consistent version to users across platforms, without requiring
installation of additional software.

\Biocpkg{Rsamtools} takes the following approach. On installation,
\Biocpkg{Rsamtools} contains a snapshot of the samtools library source
code under \verb|src/samtools|. \Biocpkg{Rsamtools} makes static
version(s) of the samtools libraries \verb|libbam.a| and
\verb|libbcf.a|. These static libraries are specific to the operating
system on which \Biocpkg{Rsamtools} is being installed, are found
under \verb|usrlib${R_ARCH}| in the user library location specified by
the mechanism (e.g., \Rfunction{biocLite},
\Rfunction{install.packages}) used to install \Biocpkg{Rsamtools}. At
the same time, \Biocpkg{Rsamtools} copies headers required to use the
library to the location \verb|include/samtools|.

\section{Use}

To use these libraries, the third party package developer needs to (1)
discover the appropriate header files when their package is built, and
(2) link in the libraries.

Note that in order to link correctly across platforms your package
must provide \emph{both} the respective \verb|src/Makevars| \emph{and}
\verb|src/Makevars.win| files.

\subsection{Discover header files}

To discover appropriate header files at package installation time, add
\begin{verbatim}
LinkingTo: Rsamtools
\end{verbatim}
to the \verb|DESCRIPTION| file, and reference the relevant include
files as, for instance,
\begin{verbatim}
#include "samtools/bam.h"
\end{verbatim}
The content of the include files can be found in the \Biocpkg{Rsamtools}
source (under \verb|src/samtools|) or at their installed location.

\subsection{Link to static libraries}

Linking to the static libraries is accomplished by including the
following code in \verb|src/Makevars.win| for \emph{Windows}:

\begin{verbatim}
SAMVARS=$(shell echo 'cat(system.file("usretc", .Platform[["r_arch"]],\
    "Rsamtools.mk", package="Rsamtools", mustWork=TRUE))' |\
    "${R_HOME}/bin/R" --vanilla --slave)
include $(SAMVARS)

PKG_LIBS=$(SAMTOOLS_LIBS)
PKG_CPPFLAGS=$(SAMTOOLS_CPPFLAGS)
\end{verbatim}

and with the following code in \verb|src/Makevars| for all other platforms:

\begin{verbatim}
SAMTOOLS_PATH=\
    `echo 'cat(system.file("usrlib", .Platform[["r_arch"]], \
        package="Rsamtools", mustWork=TRUE))' |\
        "${R_HOME}/bin/R" --vanilla --slave`
SAMTOOLS_LIBS="$(SAMTOOLS_PATH)/libbam.a" "$(SAMTOOLS_PATH)/libbcf.a"\
    "$(SAMTOOLS_PATH)/libtabix.a" -lz -pthread
SAMTOOLS_CPPFLAGS=-D_USE_KNETFILE -DBGZF_CACHE -D_FILE_OFFSET_BITS=64 \
    -D_LARGEFILE64_SOURCE

PKG_LIBS=$(SAMTOOLS_LIBS)
PKG_CPPFLAGS=$(SAMTOOLS_CPPFLAGS)
\end{verbatim}

This updates the environment variables \verb|$PKG_CPPFLAGS| and
\verb|$PKG_LIBS|; if your \verb|Makevars|/\verb|Makevars.win| modifies
these also, do so by adding to the respecitve line, e.g.,

\begin{verbatim}
PKG_LIBS=$(SAMTOOLS_LIBS) -lfoo
PKG_CPPFLAGS=$(SAMTOOLS_CPPFLAGS) -I/path/bar
\end{verbatim}

\end{document}