---
title: "Accessing 3rd-Party Libraries"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Accessing 3rd-Party Libraries}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---


```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
knitr::knit_engines$set(callme = callme:::callme_engine)
library(callme)
```

```{css, echo=FALSE}
.callme         { background-color: #E3F2FD; }
pre.callme span { background-color: #E3F2FD; }
```

## Introduction

When linking to a third party library it will often be necessary to explicitly 
specify a number of things:

* `#include` the header file in the C code
* Use `PKG_CPPFLAGS` to nominate the search path for where the header file
  may be found (`-I` flag)
* Use `PKG_LIBS` to specify
    * Additional search paths for libraries (`-L` flag)
    * which libraries to link to (`-l` flag)

## Example: Linking to `zlib`


```{callme}
#| PKG_LIBS = "-lz"
#include <R.h>
#include <Rinternals.h>
#include "zlib.h"
  
SEXP get_zlib_version(void) {
  // const char * ZEXPORT zlibVersion(void);
  return mkString(zlibVersion());
}
```

```{r eval=FALSE}
# Compile the code with explicit link to library
compile(code, PKG_LIBS = "-lz")
```


```{r}
# Call the function
get_zlib_version()
```

## Possible variations

```{r eval = FALSE}
# include a search path for the library
compile(code, PKG_LIBS = "-L/local/libs -lz")

# Include a search path for the header
compile(code, PKG_LIBS = "-lz", PKG_CPPFLAGS = "-I/usr/local/include")

# Link to a drop-in replacement
compile(code, PKG_LIBS = "-lzlibng")

# Use "pkg-config" to automatically determine appropriate flags
compile(code, PKG_LIBS = "`pkg-config --libs zlib`", 
        PKG_CPPFLAGS = "`pkg-config --cflags zlib`")
```