---
title: Assortment of header-only libraries
author: 
- name: Aaron Lun
  email: infinite.monkeys.with.keyboards@gmail.com
date: "`r Sys.Date()`"
output:
  BiocStyle::html_document:
    toc: true
package: assorthead
vignette: >
  %\VignetteIndexEntry{User's Guide}
  %\VignetteEngine{knitr::rmarkdown}
---

```{r style, echo=FALSE}
library(BiocStyle)
knitr::opts_chunk$set(error=FALSE, warning=FALSE, message=FALSE)
self <- Biocpkg("assorthead")
```

# Overview

`r self` vendors an assortment of header-only C++ libraries for use in Bioconductor packages. 
The use of a central repository avoids duplicate vendoring of libraries across multiple R packages,
and enables better coordination of version updates across cohorts of interdependent C++ libraries.
This package is minimalistic by design to ensure that downstream packages are not burdened with more transitive dependencies.

# Quick start

To use `r self` in a Bioconductor package,
just add it to the `LinkingTo` field in the `DESCRIPTION`:

```
LinkingTo: assorthead
```

The package C++ code can `#include` any of the available libraries, for example:

```cpp
#include "Eigen/Dense"
#include "annoy/annoylib.h"
#include "annoy/kissrandom.h"
#include "tatami/tatami.hpp"
```

# Available libraries

```{r, results="asis", echo=FALSE}
fname <- system.file("manifest.csv", package='assorthead')
manifest <- read.csv(fname)

cat("|Name|Version|Description|\n")
cat("|----|-------|-----------|\n")
for (i in seq_len(nrow(manifest))) {
    cat(sprintf("|[**%s**](%s)|%s|%s|\n", manifest$name[i], manifest$url[i], manifest$version[i], manifest$description[i]))
}
```

# Using interfaces

The `r Biocpkg("beachmat")` package contains the `initializeCpp()` function, which creates an external pointer to a `tatami::Matrix`.
Similarly, the `r Biocpkg("BiocNeighbors")` package can create external pointers to various **knncolle** objects via its `defineBuilder()` and `buildIndex()` functions.
Downstream packages can use these pointers in their own C++ code by compiling against the relevant interfaces in `r self`.
This means that downstream packages do not need to re-compile all of the relevant header libraries to get full functionality of `r Biocpkg("beachmat")`, `r Biocpkg("BiocNeighbors")`, etc.
It also allows the C++ code of downstream packages to handle extensions to each framework, e.g., new matrix types in `r Biocpkg("beachmat.hdf5")`.
Check out each of the packages for more specific instructions on how to use its external pointers.

# Contributing

If you want to add new libraries or update existing versions,
make a [pull request](https://github.com/LTLA/assorthead/pulls) with appropriate motifications in the `inst/fetch.R` file.