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

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

```{r setup}
library(tsdrtools)
```

The goal of tsdrtools is to make it easier for R users of TSD to install packages that fail install using the TSD mini-CRAN. 
Certain R-packages require compilation outside of TSD before they can be installed, and as such can be burdensome for some users to administer.

Since packages often have a myriad of dependencies, this process can becomes increasingly cumbersome, as all these extra packages also need to be obtained, which again might require special compilation. 

In the two step procedure here, a package is downloaded together with all dependent packages, zipped into an archive for easy import into TSD, where it can be unzipped and installed using a special function.

## Installation

You can install the development version of tsdrtools 
```{r eval = FALSE}
install.packages("remotes")
remotes::install_github("LCBC-UIO/tsdrtools")
```

for installation of this package inside TSD, download the newest source file from
[https://github.com/LCBC-UiO/tsdrtools/](https://github.com/LCBC-UiO/tsdrtools/).

Transfer the package to TSD (import it), and install as a source package.
```{r eval = FALSE}
install.packages("/path/to/tsdrtools.tar.gz", repo = NULL)
```


## Examples

This package contains two main functions:

1. `tsd_package_prepare()` is used outside of TSD, with internet connection to prepare a package for install within TSD.  
2. Once step 1 is completed and data transfered to TSD, the `tsd_package_install()` is used within TSD to install the package within TSD.  

```{r prepare-package, eval = FALSE}
library(tsdrtools)

# outside TSD
tsd_package_prepare("dplyr")

# within TSD
status <- tsd_package_prepare("dplyr.zip")
```

By saving the output of `tsd_package_prepare` you can scope the potential error messages from the install after they have occurred. 
Failed installs may happen not only because we have yet to discover some issue with certain packages, but also because there might be OS dependencies that a package needs to work, which might not be installed on your TSD VM. 
In such cases, having the error and showing it to IT would help them get the necessary OS libraries installed for you.

```{r, echo = FALSE}
deps <- tsdrtools:::get_dependency_tree("dplyr", repos = "https://cran.rstudio.com/", verbose = FALSE)
pkgs <- as.data.frame(available.packages(repos = "https://cran.rstudio.com/" ))
pkgs <- pkgs[na.omit(match(deps, pkgs$Package)),c("Package", "Version")]

status <- list(
  success = data.frame(
    success = ifelse(pkgs$Package == "crayon", "failed", "success"),
    pkg = pkgs$Package,
    version =  pkgs$Version
  ),
  error_logs = list(
    crayon = c("The full build error", "will appear here.", "This is just a mock example")
  )
)

status <- as_tsdrtools_install(status)
```

```{r}
# View install status
status

error_logs(status)
```


## Limitations
Currently the package will only prepare and install packages that are available on CRAN. 
We are working on a version that might allow downloading and making available packages from other repositories, and welcome any contribution that will help us achieve this.
