# Installation

#### Eric Dunipace

#### 2023-06-17

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, and due to CRAN dependencies relying on the headers for C++ files, the package will download the latest header files from the CGAL GitHub. 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 latest version

If you don’t have any strong desires, do the following:

    install.packages("RcppCGAL")
    cgal_install(cgal_path = NULL, version = NULL,
                 clean_files = TRUE, force = FALSE)

The functions should take care of the rest! You will have the latest version of CGAL from GitHub. This should also happen by default on package installation if there is an internet connection.

### You want to install a particular version from the GitHub

If you have a particular version of the CGAL headers you would like from the GitHub, use the version argument and keep `cgal_path = NULL`.

    install.packages("RcppCGAL")
    cgal_install(cgal_path = NULL, version = "5.5.1",
                 clean_files = TRUE, force = FALSE)

### 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 in the argument `cgal_path`.

    install.packages("RcppCGAL")
    cgal_install(cgal_path = "path/to/CGAL", version = NULL,
                 clean_files = TRUE, force = FALSE)

The function will then copy the files into the R package directory.

### You have a particular URL you want to download the headers from

This is similar to the previous example; you just need to specify the exact location of the header files you want to download.

    install.packages("RcppCGAL")
    cgal_install(cgal_path = "https://some/url/cgalheaders.tar.gz", version = NULL,
                 clean_files = TRUE, force = FALSE)

## Installation with system environment flags

In some case, you may want to install the CGAL header files by default on installation and perhaps you may have a custom path. In this case, you can set two environmental variables.

The first, `CGAL_DIR`, will specify a directory or URL to search for the CGAL header files like above. If it is not set, the package will simply download the latest version or by using the argument of `cgal_path` in the `cgal_install` function. In the shell on Unix/Linux machines, you can do

    export CGAL_DIR="https://some/url/cgalheaders.tar.gz"

or you can set it in R directly

    Sys.setenv(CGAL_DIR="https://some/url/cgalheaders.tar.gz")

The second variable, `CGAL_DOWNLOAD`, will let R know to install the header files automatically when installing the `RcppCGAL` package. If `CGAL_DOWNLOAD` is any other value than 0, the header files will be automatically downloaded. If `CGAL_DOWNLOAD=0` , the header files will not be downloaded. This mean that in most cases, i.e. on CRAN, the header files will be downloaded as long as there is an internet connection. You can set this variable via the shell

or in R

    export CGAL_DOWNLOAD="1"

or you can set it in R directly

    Sys.setenv(CGAL_DOWNLOAD="1")

Then you can install the package and everything should flow automatically.

    install.packages("RcppCGAL")

## Updating header files

The process of updating the files is simple. We can just follow the same procedures as above using the `cgal_install` function but set `force = TRUE`:

    cgal_install(cgal_path = NULL, version = NULL,
                 clean_files = TRUE, force = TRUE)

No need to install the whole package again. This will also give you a warning saying it will overwrite the current header files.

## To clean or not to clean

Pretty much you should always clean the header files—i.e., leave `clean_files = TRUE` untouched. The reason 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!