---
title: "System configuration"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{System configuration}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

# System dependency specification file

`rfacts` has strict system dependencies.

* FACTS Linux engines (>= 6.2.4)
* FLFLL (>= 6.2.4)
* Mono (>= 5.20.1.19)

Before you can use `rfacts` to simulate trials in R, you must specify the paths to all these executable files in a CSV file. You can see an example CSV file at [`inst/example_paths.csv`](https://github.com/EliLillyCo/rfacts/blob/main/inst/example_paths.csv) in the `rfacts` package source.

```{r}
path <- system.file("example_paths.csv", package = "rfacts")
writeLines(readLines(path))
```

## Required columns

* `executable_type`: Must be "mono", "flfll", or "engine" to denote the general type of the executable.
* `facts_version`: The version of FACTS with which this executable is compatible.
* `path`: File path to the executable.
* `engine_name`: For engines only. Name of the engine.
  Must be one of the engine types in the example CSV file at `system.file("example_paths.csv", package = "rfacts")`.
* `param_set`: For engines only. Parameter set designation listed in the XML code of FACTS files for that engine.
* `param_type`: For engines only. Parameter type designation listed in the XML code of FACTS files for that engine.

# Connecting `rfacts` to the system dependencies

To allow `rfacts` to find the CSV file above, you must set the `RFACTS_PATHS` environment variable. For a single R session, you can do this with `Sys.setenv(RFACTS_PATHS = "path/to/file.csv")`. To set `RFACTS_PATHS` permanently for all future sessions, open your `.Renviron` file with `usethis::edit_r_environ()` and add a line with `RFACTS_PATHS=path/to/file.csv`. Then, restart R so the changes take effect. Verify that you did this correctly by checking the value of the environment variable.

```{r, echo = FALSE}
old_rfacts_paths <- Sys.getenv("RFACTS_PATHS")
Sys.setenv(
  RFACTS_PATHS = system.file(
    "example_paths.csv",
    package = "rfacts",
    mustWork = TRUE
  )
)
```

```{r}
Sys.getenv("RFACTS_PATHS")
```

Check the system dependency information with `rfacts_paths()`.

```{r}
library(rfacts)
rfacts_paths()
```

Use `rfacts_sitrep()` to verify that all the executables exist and are indeed executable. This vignette uses toy paths that do not actually exist. In your setup, if `exists` and `is_executable` are all `TRUE`, then your setup is configured correctly.

```{r}
rfacts_sitrep()
```

```{r, include = FALSE}
Sys.setenv(RFACTS_PATHS = old_rfacts_paths)
detach("package:rfacts", unload=TRUE)
```

If you change `RFACTS_PATHS`, you need to call `reset_rfacts_paths()` or restart R in order for the changes to take effect.