installing-packages.qmd

# Installing packages


## a highly simplified package lifecycle
```{mermaid}
%%{init: {"theme": "dark" } }%%
graph TD
Source -- "devtools::build()" --> Bundled
Bundled -- "devtools::build(binary = TRUE)"--> Binary 
Binary --"install.packages()"--> Installed 
Installed --"library()"--> Loaded 
```


```{mermaid}
%%{init: {"theme": "dark" } }%%
flowchart TD
subgraph dev
  direction LR
Source -- "devtools::build()" --> Bundled
Bundled -- "devtools::build(binary = TRUE)"--> Binary 
end
subgraph use
direction LR
Binary --"install.packages()"--> Installed 
Installed --"library()"--> Loaded 
end
```

[R Packages](https://r-pkgs.org/Structure.html) covers these phases of the package lifecycle in much more detail.

## Binary packages

- where to get them
- how to know you got them

##  Source packages

The most common type of package you install is a **binary** package. Packages
released on CRAN are built as pre-compiled binaries.

However often it is useful to install packages which do not have a pre-built
binary version available. This allows you to install development versions not
yet released on CRAN, as well as older versions of released packages. It also lets
you build your own packages locally.

To install a source package you will need to [setup a development environment](#setting-up-a-development-environment).

There are a few main functions used to install source packages.

- `devtools::install_dev()` to install the latest development version of a CRAN package. ^[This will only work if the package includes a link to the development location in the package DESCRIPTION]
- `devtools::install_github()` to install a package directly from GitHub, even if it is not on CRAN.
- `devtools::install_version()` to install previously released CRAN versions of a package.

For example `devtools::install_dev("dplyr")` will install the development
version of dplyr. `devtools::install_github("jimhester/lookup")` will install
Jim's lookup package (which is not on CRAN), and
`devtools::install_version("readr", "1.0.0")` will install readr 1.0.0.

It is also possible to [fork, clone and work with a package
directly](https://happygitwithr.com/fork.html) then use `devtools::install()`
and `devtools::load_all()` to work with the package locally like you would with
a package you have created yourself.

## Setting up a development environment

### Windows: system prep

On Windows the compiler collection needed for installing packages from source
is called Rtools.

Rtools is **NOT an R package**, so it is not installed with
`install.packages()`. Instead download it from
<http://cran.r-project.org/bin/windows/Rtools/> and run the installer.

During the Rtools installation you will see a window asking you to “Select
Additional Tasks”.

- Do _not_ select the box for
“Add rtools to system PATH”, `devtools` and RStudio should put Rtools on the PATH
automatically when it is needed.
- Do select the box for "Save version information to registry" (it should be selected by default).

### macOS: system prep

On macOS you will need to install the Xcode Command Line Tools, which may
already be installed. You can check if they are by running

```r
devtools::has_devel()
```

If they are not installed you have a few options.

- Minimalist approach (what I do): Install Xcode Command Line Tools.
  In the shell:
  ```{.bash}
  xcode-select --install
  ```
- Install the current release of full [Xcode from the Mac App Store](https://itunes.apple.com/ca/app/xcode/id497799835?mt=12). WAY more
  stuff than you need but the advantage is App Store convenience.

#### What about Homebrew?

Users on macOS often install R with [homebrew](https://brew.sh/) via this **formula**:

```{.bash}
brew install r
```

Unfortunately, when R is installed in this way it is not compatible with the
CRAN package binaries, which means you must build and install all packages from
source. This takes additional time during installation and can lead to more
time spent dealing with installation issues if a package fails to compile.

Instead, if you prefer the convenience of homebrew, we recommend installing the
`r` **cask**. *NOTE: the cask used to be named `r-app` but the `-app` suffix was
dropped due to [a homebrew policy change around 2019-03-11](/~https://github.com/Homebrew/homebrew-cask/pull/59689)*. 

```{.bash}
brew install --cask r
```

This will install the CRAN R distribution, so all package binaries will be
available just like they would be from installing R manually.

### Linux system prep

Most Linux systems will typically be equipped with the necessary tools for building packages from source.
The system package manager (e.g. `apt`, `yum`, `zypper`, etc.) can be used to install tools if they are missing.

### Verify system prep

```{.r}
devtools::has_devel()
```

If this function runs without error then congratulations, your R installation
is properly set up!

### What about Conda?

Some users use [conda](https://conda.io) in python contexts and
notice that conda now also provides (some) R package binaries.

However we would suggest avoiding conda at this time, only a limited number of
all CRAN packages are available ^[~1,500 out of ~13,000 as of this writing] and
many users run into installation problems trying to use `install.packages()`
inside conda environments. Using `install.packages()` also means you no longer
declare all dependencies in the same location. Which means your work is less
reproducible than if you always install only conda packages.

For these reasons we suggest you either restrict yourself only to packages
available as official conda packages, or avoid using conda for R.

## Installation to a temporary library

It is sometimes useful to install packages to a temporary library, so that they
don't affect your normal packages. This can be done by using the `lib` argument
to the devtools install functions, then using `lib.loc` in `library()` when you
load the package.

```r
library(devtools)

tmp_lib <- "~/tmp/tmp_library"
dir.create(tmp_lib)

devtools::install_github("dill/beyonce", lib = tmp_lib)

## restart R

## explicitly load the affected packages from the temporary library
library(beyonce, lib.loc = tmp_lib)

## your experimentation goes here

## done? clean up!
unlink(tmp_lib, recursive = TRUE)
```

::: {.callout-note}
[Try the activity](https://raw.githubusercontent.com/jimhester/wtf-source-package/master/01_source-package_spartan.R): `usethis::use_course("rstd.io/wtf-source-package")`

To practice installing various types of source packages.
:::