---
title: "Installation"
author: "Eric Dunipace"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Installation}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

This document will briefly cover the installation process of the header files for users since there are some possible environmental variables that can be used to aid in the download/installation of the CGAL header files on your machine. By default, the package is bundled with header version `r RcppCGAL:::cgal_pkg_state$DEFAULT_VERSION`. If you wish for more control or there is an error, read on!

## Installation without system environment flags
The process of installing is, hopefully, quite simple for most users. 

### You just want the default `r RcppCGAL:::cgal_pkg_state$DEFAULT_VERSION` version
If you don't have any strong desires, do the following:
``` {r, eval = FALSE}
install.packages("RcppCGAL")
```
You will have the CGAL header files!

### You want to install a particular version from a URL
All you have to do is set the environment variable `CGAL_DIR`. In the shell on Unix/Linux machines, you can do
```{bash, eval = FALSE}
export CGAL_DIR="https://some/url/cgalheaders.tar.gz"
```
or you can set it in R directly
```{r, eval = FALSE}
Sys.setenv(CGAL_DIR="https://some/url/cgalheaders.tar.gz")
```

If you have already installed the package, you can use
```{r, eval = FALSE}
set_cgal("https://some/url/cgalheaders.tar.gz")
```
and then re-install package.

### You have a local install you want to use
If you have already installed the CGAL header files and just want to use that, you just need to specify the system path to the CGAL folder, much the same as setting a URL above.

In the Linux/Unix shell you can do
```{bash, eval = FALSE}
export CGAL_DIR="path/to/include/CGAL"
```
or you can set it in R directly
```{r, eval = FALSE}
Sys.setenv(CGAL_DIR="path/to/include/CGAL")
```

If you have already installed the package, you can use
```{r, eval = FALSE}
set_cgal("path/to/include/CGAL)
```
and then re-install package.

## To clean or not to clean
By default, the package will clean any header files that are provided into the `CGAL_DIR` environmental variable. The reason for this is that the CGAL header files have calls to `std::exit`, `std::cerr`, and `std::cout`, which can can cause R to crash or for messages to not appear on the R consol. By default, `RcppCGAL` will search for these funtions and replace them with the `Rcpp` equivalents; however, should you find this isn't happening, please raise an issue on the GitHub!

At this time, the package does leaving the header files uncleaned. If for some reason you have a use case where you would like them not cleaned, please raise an issue on the GitHub for this package!

## Changes from last version install procedure
The last version had an `cgal_install()` function to download the header files on load. This function has been soft deprecated in favor of the default process since some packages may be installed as read only.