---
title: "Motivation and use of _Rtwobitlib_"
author:
- name: Hervé Pagès
  affiliation: Fred Hutchinson Cancer Research Center, Seattle, WA
date: "Last edited 22 April 2024"
package: Rtwobitlib
vignette: >
  %\VignetteIndexEntry{Motivation and use of Rtwobitlib}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
output:
  rmarkdown::html_document
---


### 1. Motivation

**Rtwobitlib** is an R package that provides the _2bit_ `C` Library
from the UCSC Genome Browser.
See [this page](https://genome.ucsc.edu/FAQ/FAQformat.html#format7) 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)

```{R headers}
inc_path <- system.file(package="Rtwobitlib", "include")
list.files(inc_path, recursive=TRUE)
```

#### 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.