%\VignetteIndexEntry{Using zlibbioc C libraries}
%\VignetteDepends{}
%\VignettePackage{zlibbioc}
\documentclass[]{article}

\usepackage{times}
\usepackage{hyperref}

\newcommand{\Rfunction}[1]{{\texttt{#1}}}
\newcommand{\Robject}[1]{{\texttt{#1}}}
\newcommand{\Rpackage}[1]{{\textit{#1}}}
\newcommand{\Rmethod}[1]{{\texttt{#1}}}
\newcommand{\Rfunarg}[1]{{\texttt{#1}}}
\newcommand{\Rclass}[1]{{\textit{#1}}}
\newcommand{\Rcode}[1]{{\texttt{#1}}}

\newcommand{\software}[1]{\textsf{#1}}
\newcommand{\zlib}{\software{zlib}}
\newcommand{\R}{\software{R}}
\newcommand{\Bioconductor}{\software{Bioconductor}}

\title{Using \Rpackage{zlibbioc}}
\author{Martin Morgan}
\date{Modified: 29 September, 2011. Compiled: \today}

\begin{document}

\maketitle

The \Rpackage{zlibbioc} package is meant as a utility for package
developers. It contains the source code to the
\href{http://zlib.net}{\zlib} library, and can be used to access
\zlib{} shared library functionality. The library is made available as
\verb|libzbioc|.

The \Rpackage{zlibbioc} package is installed in the normal \R{}
manner. The \verb|libzbioc| library is always built on Windows, but on
other platforms it is only built when provided with the configure
option \verb|--with-libzbioc|, e.g., as
\begin{verbatim}
R CMD INSTALL --configure-args="--with-libzbioc" zlibioc_<...>.tar.gz
\end{verbatim}
or
\begin{verbatim}
> install.pacakges("zlibbioc_<...>.tar.gz", 
                   configure.args="--with-libzbioc")
\end{verbatim}
MacOS has \verb|zlib| installed, so building the libraries are neither
necessary nor supported on that platform. Advanced use cases may
require consultation of instructions in
\verb|zlibbioc/src/zlib-1.2.5/configure|.


All packages wishing to use the libraries in \Rpackage{zlibbioc} must
\begin{itemize}
\item Add \texttt{Imports: zlibbioc} to the \verb|DESCRIPTION| file.
\item Add \texttt{import(zlibbioc)} to the \verb|NAMESPACE| file.
\end{itemize}
Reference the relevant include file in your C source code:
\begin{verbatim}
#include "zlib.h"
\end{verbatim}
The content of the include files can be found in the
\Rpackage{zlibbioc} source (under \verb|src/zlib-1.2.5|) or at their
installed location.

On Windows, the recommended approach is to link to the DLL. This
requires that the appropriate header files are available to the gcc
compiler, and that the DLL is discovered by the linker.
\begin{itemize}
\item Create a file \verb|src/Makevars.win| including the following
  lines:
\begin{verbatim}
ZLIB_CFLAGS+=$(shell echo 'zlibbioc::pkgconfig("PKG_CFLAGS")'|\
    "${R_HOME}/bin/R" --vanilla --slave)
PKG_LIBS+=$(shell echo 'zlibbioc::pkgconfig("PKG_LIBS_shared")' |\
    "${R_HOME}/bin/R" --vanilla --slave)
%.o: %.c
    $(CC) $(ZLIB_CFLAGS) $(ALL_CPPFLAGS) $(ALL_CFLAGS) -c $< -o $@
\end{verbatim}
Packages with \verb|C++| code also require the rule (replace
\verb|.cc| with \verb|.cpp| as necessary)
\begin{verbatim}
%.o: %.cc
    $(CXX) $(ZLIB_CFLAGS) $(ALL_CPPFLAGS) $(ALL_CXXFLAGS) -c $< -o $@
\end{verbatim}
(remember that  the second line of each rule begins with a tab, not spaces).
\end{itemize}

On Linux and other platforms, the most portable solution is to link to
static libraries
\begin{itemize}
\item Create a file \verb|src/Makevars| including the following lines:
\begin{verbatim}
PKG_CFLAGS+=$(shell echo 'zlibbioc::pkgconfig("PKG_CFLAGS")'|\
    "${R_HOME}/bin/R" --vanilla --slave)
PKG_LIBS+=$(shell echo 'zlibbioc::pkgconfig("PKG_LIBS_static")'|\
    "${R_HOME}/bin/R" --vanilla --slave)
\end{verbatim}
\end{itemize}
It is also possible to link to the shared library (see qualifications
about portability in `Writing \R{} Extensions') with
\begin{verbatim}
PKG_CFLAGS+=$(shell echo 'zlibbioc::pkgconfig("PKG_CFLAGS")'|\
    "${R_HOME}/bin/R" --vanilla --slave)
PKG_LIBS+=$(shell echo 'zlibbioc::pkgconfig("PKG_LIBS_shared")' |\
    "${R_HOME}/bin/R" --vanilla --slave)
\end{verbatim}

The \Rpackage{Rsamtools} package is a more complex example
illustrating this approach.

\end{document}