---
title: "Installing packages on TSD from mini-CRAN"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{minicran-tsd-install}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
options(rmarkdown.html_vignette.check_title = FALSE)
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = FALSE
)
```

USIT periodically downloads packages from CRAN, Bioconductor and a couple other repositories into TSD for easy install by users. 
However, by default, R is set up to look for repositories online (i.e. CRAN), which is not available on TSD because it is an offline server (you have no internet access inside TSD).
To be able to connect to the downloaded repository within TSD and install packages, you need to change where the `install.packages()` function looks for packages within TSD. 

```{r}
install.packages("Y", repos = "https://cran.tsd.usit.no")
```

USIT has placed the mini-CRAN repository at https://cran.tsd.usit.no within TSD, and therefore supplying `repos = "https://cran.tsd.usit.no"` to the install function will connect you there instead of failed attempts to CRAN. 

Installing packages are not usually one-time things though. 
Usually we have quite some packages we want to install, and try different packages to get our work done.
It's inconvenient to have to remember the link within TSD where the package-repo is.

It is therefore recommended to place in a file called `$HOME/.Rprofile` the following information:

```{r}
local({
       r = getOption("repos")
       r["CRAN"] <- "https://cran.tsd.usit.no"
       r["BIOCONDUCTOR"] <- "https://bioconductor.tsd.usit.no"
       r["BIOCONDUCTOR-annotation"] <- "https://bioconductor.tsd.usit.no/data/annotation"
       r["BIOCONDUCTOR-experiment"] <- "https://bioconductor.tsd.usit.no/data/experiment"
       r["BioC_mirror"] <- "https://bioconductor.tsd.usit.no"
       options(repos=r)
       options(BIOCONDUCTOR_ONLINE_VERSION_DIAGNOSIS = FALSE)
       options(download.file.method = "libcurl")
       })
```

if you do not yet have a `$HOME/.Rprofile` file, create it in the terminal by:

```{sh}
# create file
touch $HOME/.Rprofile

# open to edit
gedit $HOME/.Rprofile
```

Restarting R will now mean `install.packages()` always looks for new packages you ask for in the two CRAN and Bioconductor repositories available within TSD.

For more information about R packages installs, see [official USIT support pages for R](https://www.uio.no/english/services/it/research/sensitive-data/use-tsd/software/r/index.html)

# When installs from mini-CRAN fail
If your install fails from within TSD even with these settings, there are usually one of two culprits:

1. There are other system requirements not yet met (linux libs or c++ compilers missing)  
2. The package requires internett to install, because it the package itself does not contain all the necessary information (like stringi)

## Solving problem 1

### system libs missing
If there are other system requirements needed, your packages will fail installation with messages looking something like so :

```{r}
configure: error: "libxml not found"
```

TSD runs what is called minimal-install Linux operative systems. 
This means there are quite some system libraries that certain R-packages use that are not available by default.
Thankfully, USIT are very helpful in getting these installed and available upon request.
Annoyingly, the package installs will fail at the first system requirement not met, and as such, you might need several rounds with IT untill all necessary libs are installed. 

### Clang missing
Another possible error you will see, would be some error relating to `clang` or `cpp` compiler missing. 
This means that the package you want to install has some c++ (another programming language) dependency, and it cannot find a compiler for that language. 
Thankfully, you can easily connect to a c++ compiler through the TSD software modules.

```{bash}
module load gcc
```

By loading in `gcc` (GNU c++ compiler) _before_ starting R, this problem is solved. 
We highly recommend creating a `.bash_profile` in your home directory that automatically loads in `gcc` for you at terminal start-up if you regularly use R-packages that require it. 

```{sh}
# create file
touch $HOME/.bash_profile

# open to edit
gedit $HOME/.bash_profile
```

Add
```{bash}
#!/bin/bash

# load gcc for R-pkgs
module load gcc
```

save and restart your terminal. 
`gcc` should now always be available when you start R from the terminal. 

## Solving problem 2
The tsdrtools package is specifically made to handle problem no. 2.
By using `tsd_package_prepare()` outside TSD, the function will download your wanted package pluss all its dependencies into a zip-folder. 
This folder can be transferred into TSD, and installed using the function `tsd_package_install()`, on the zip-folder imported.

This should install your package into your main library path.