# Motivation and use of Rtwobitlib

#### Hervé Pagès

### 1. Motivation

Rtwobitlib is an R package that provides the 2bit `C` Library from the UCSC Genome Browser. See this page on the UCSC Genome Browser website for a quick overview of the 2bit format.

The Rtwobitlib package is primarily useful to developers of other R packages who wish to use the 2bit `C` library in their own `C` code.

### 2. Using the 2bit `C` library in the `C` code of your package

#### Find the header files

In order for the `C`/`C++` compiler to find the 2bit header files during compilation of your package, you must add `Rtwobitlib` to the `LinkingTo` field of its `DESCRIPTION` file, e.g.,

    LinkingTo: Rtwobitlib

Note that as of R 3.0.2 `LinkingTo` values can include version specifications, e.g., `LinkingTo: Rtwobitlib (>= 0.3.6)`.

In `C` or `C++` code files, use standard techniques, e.g., `#include <kent/twoBit.h>`. Header files are available for perusal at (enter in an R session)

    inc_path <- system.file(package="Rtwobitlib", "include")
    list.files(inc_path, recursive=TRUE)

    ##  [1] "kent/bits.h"     "kent/cheapcgi.h" "kent/common.h"   "kent/dnaseq.h"
    ##  [5] "kent/dnautil.h"  "kent/errAbort.h" "kent/hash.h"     "kent/linefile.h"
    ##  [9] "kent/localmem.h" "kent/obscure.h"  "kent/sig.h"      "kent/twoBit.h"

#### Compile and link against the library

To compile and link your package successfully against the 2bit library included in Rtwobitlib, you must add a `src/Makevars` file with the following content:

    ## This file uses GNU make syntax $(shell ...) so we need to
    ## have "SystemRequirements: GNU make" in the DESCRIPTION file.

    RTWOBITLIB_LIBS=$(shell "${R_HOME}/bin${R_ARCH_BIN}/Rscript" -e \
        'Rtwobitlib::pkgconfig("PKG_LIBS")')
    RTWOBITLIB_CPPFLAGS=$(shell "${R_HOME}/bin${R_ARCH_BIN}/Rscript" -e \
        'Rtwobitlib::pkgconfig("PKG_CPPFLAGS")')

    PKG_LIBS=$(RTWOBITLIB_LIBS)
    PKG_CPPFLAGS=$(RTWOBITLIB_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=$(RTWOBITLIB_LIBS)` line, e.g.,

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

#### Notes

`Rtwobitlib` provides both static and dynamic versions of the 2bit library on Linux, but only the static version on Windows and macOS. The procedure above will link against the static version of the 2bit library on all platforms.

### 3. R functions defined in Rtwobitlib

Rtwobitlib provides the following R functions: `twobit_read`, `twobit_write`, `twobit_seqlengths`, `twobit_seqstats`.

These functions are implemented in `C` on top of the 2bit library bundled in the package.

Please refer to their man pages (e.g. with `?twobit_seqlengths`) for more information and some examples.