---
title: "Setting Up and Using Nix and Rix on Linux and Windows"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Setting up and using Nix and rix on Linux and Windows}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

```{r, include=FALSE}
library(rix)
```

*This vignette will discuss Linux and Windows-specific topics. If you're not
using either of these systems, you can ignore this vignette, and read the
`vignette("setting-up-macos")`
vignette instead.*

## Introduction

When it comes to Nix, there are really only two supported operating systems:
macOS and Linux distributions. Windows is "supported" because it is actually
running Linux thanks to WSL2. In practice this means that Linux distributions
and Windows can be considered one system, and macOS another, separate, system.
Because Windows is really running Linux under the hood thanks to WSL2, this
means that WSL2 needs to be running on your Windows system before you attempt to
install Nix. But it is important to know that you can run `{rix}` even if you
don't have Nix installed, which means you can generate Nix expressions, you just
can't build them. So if you can’t install Nix on your system, but have R already
installed, you can skip to the last section of this vignette to simply install
the `{rix}` package.

## Why rix *and* Nix?

You don't have to install Nix to use `{rix}`: you can generate valid Nix
expressions using `{rix}` even on a system where Nix isn't present. However,
this means that you won't be able to build these expressions on that system.

## Installing Nix

### Windows pre-requisites

If you are on Windows, you need the Windows Subsystem for Linux 2 (WSL2) to run
Nix. If you are on a recent version of Windows 10 or 11, you can simply run this
as an administrator in PowerShell:

```bash
wsl --install
```

You can find further installation notes at [this official Microsoft
documentation](https://learn.microsoft.com/en-us/windows/wsl/install).

We recommend to activate systemd in Ubuntu WSL2, mainly because this supports
other users than `root` running Nix. To set this up, please do as outlined
in [the official Microsoft WSL documentation](https://learn.microsoft.com/en-us/windows/wsl/systemd#how-to-enable-systemd):

```sh
# in WSL2 Ubuntu shell

sudo -i
nano /etc/wsl.conf
```

This will open the `/etc/wsl.conf` in a nano, a command
line text editor. Add the following line:

```
[boot]
systemd=true
```

Save the file with CTRL-O and then quit nano with CTRL-X.
Then, type the following line in powershell:

```bash
wsl --shutdown
```

and then relaunch WSL (Ubuntu) from the start menu.

Afterwards, you can install Nix like business as usual. You can proceed with the
Determinate Systems installer.

### Using the Determinate Systems installer

You can use `{rix}` to generate Nix expressions even if you don't have Nix
installed on your system, but obviously, you need to install Nix if you actually
want to build the defined development environment and use them.

Installing (and
uninstalling) Nix is quite simple, thanks to the installer from [Determinate
Systems](https://determinate.systems/posts/determinate-nix-installer), a company
that provides services and tools built on Nix.

Do not use your operating system’s package manager to install Nix. Instead,
simply open a terminal and run the following line (on Windows, if you cannot or
have decided not to activate systemd, then you have to append `--init none` to
the command. You can find more details about this on [The Determinate Nix
Installer page](https://github.com/DeterminateSystems/nix-installer)):

```{sh parsermd-chunk-1, eval = FALSE}
curl --proto '=https' --tlsv1.2 -sSf \
    -L https://install.determinate.systems/nix | \
     sh -s -- install
```

Then, configure the `rstats-on-nix` binary cache. This will download pre-built
binaries of many R packages, significantly speeding up the building process.
Many thanks to [Cachix](https://www.cachix.org/) for sponsoring the
`rstats-on-nix` cache!

### Recommended: Using setup_cachix()

The simplest approach is to use `{rix}`'s `setup_cachix()` function from R.
First, start R from a Nix shell:

```bash
nix-shell -p R rPackages.rix
```

On first use, this may take a few minutes (up to 5 minutes) as Nix downloads R
and required packages. Be patient! Subsequent runs will be instant.

Then run:

```r
rix::setup_cachix()
```
 
This configures the cache in `~/.config/nix/nix.conf`. You also need to add
yourself as a trusted user so Nix allows you to use the cache. Run the
following one-liner:

```bash
echo "trusted-users = root $USER" | sudo tee -a /etc/nix/nix.custom.conf && sudo systemctl restart nix-daemon
```

This works for both standard Nix installations and Determinate Nix
installations. If you see warnings like `ignoring untrusted substituter`, this
means the trusted-users configuration is not in place.

### Alternative: Using the cachix client

Alternatively, you can use the `cachix` command-line client:

```bash
nix-env -iA cachix -f https://cachix.org/api/v1/install
cachix use rstats-on-nix
```

Note: If you installed Nix using the Determinate Systems installer, this
approach will not work because `/etc/nix/nix.conf` is protected and restored
on restart. Use `setup_cachix()` instead.

### NixOS users

If you are using NixOS, the Nix configuration is managed declaratively through
your system configuration, so `setup_cachix()` and `cachix use` will not work.
Instead, add the cache to your `configuration.nix`:

```nix
nix.settings = {
  substituters = [
    "https://cache.nixos.org"
    "https://rstats-on-nix.cachix.org"
  ];
  trusted-public-keys = [
    "cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY="
    "rstats-on-nix.cachix.org-1:vdiiVgocg6WeJrODIqdprZRUrhi1JzhBnXv7aWI6+F0="
  ];
};
```

If you use Home Manager, add this to your home configuration instead:

```nix
nix.settings = {
  substituters = [
    "https://rstats-on-nix.cachix.org"
  ];
  trusted-public-keys = [
    "rstats-on-nix.cachix.org-1:vdiiVgocg6WeJrODIqdprZRUrhi1JzhBnXv7aWI6+F0="
  ];
};
```

Then rebuild your system with `sudo nixos-rebuild switch` (or `home-manager
switch` for Home Manager).

On Linux, once Nix is installed, all the software that will be installed through
Nix will be saved to the `/nix` directory on the root partition. It is common
for Linux users to have a separate partition for `/`, which may be small.
Complete development environments built with Nix can take up much space, so if
the available space on your root partition is limited, we advise you to mount
the `/nix` folder on another partition with more space (for example, a secondary
hard drive). For this, edit `/etc/fstab` and add the following line at the end:

```
/home/path_to/nix /nix none bind 0 0
```

This will map `/nix` to `/home/path_to/nix` which can be on a larger partition.
If you have enough space on your root partition, you can ignore the above
instructions.

## Case 1: you don’t have R installed and wish to install it using Nix as well

If you have successfully installed Nix, but don't have yet R installed on your
system, you could install R as you would usually do on your operating system,
and then install the `{rix}` package, and from there, generate project-specific
expressions and build them. But you could also install R using Nix. Running the
following line in a terminal will drop you in an interactive R session that you
can use to start generating expressions:

```
nix-shell -p R rPackages.rix
```

or if you prefer the development version of `{rix}`:

```
nix-shell --expr "$(curl -sl https://raw.githubusercontent.com/ropensci/rix/master/inst/extdata/default.nix)"
```

This should immediately start an R session inside your terminal. You can now run
something like this:

```{r, eval = F}
library(rix)

rix(
  r_ver = "4.4.2",
  r_pkgs = c("dplyr", "ggplot2"),
  system_pkgs = NULL,
  git_pkgs = NULL,
  ide = "none",
  project_path = ".",
  overwrite = TRUE
)
```

to generate a `default.nix`, and then use that file to generate an environment
with R, `{dplyr}` and `{ggplot2}`. If you need to add packages for your project,
rerun the command above, but add the needed packages to `r_pkgs`. Beware that if
your already have a `default.nix` file in the working directory, running `rix()`
with the `overwrite = TRUE` argument will overwrite it! So make sure that you
are using a version control system for your projects to avoid bad surprises.

More details about managing project-specific `default.nix` are detailled in the
vignette `vignette("installing-r-packages")` and
`vignette("installing-system-tools")`.

You could also include `{rix}` in your project-specific environments, by
generating a `default.nix` like so:

```{r, eval = F}
rix(
  r_ver = "latest-upstream",
  r_pkgs = NULL,
  git_pkgs = list(
    package_name = "rix",
    repo_url = "https://github.com/ropensci/rix",
    commit = "76d1bdd03d78589d399b4b9d473ecde616920a82"
  ),
  ide = "none",
  project_path = ".",
  overwrite = TRUE
)
```

Change the commit to a more recent one and adapt the `project_path` argument if needed.

## Case 2: you have R installed through your OS's package manager

*Note: this package's authors recommend you only have R versions managed by
Nix, and not mix a system-wide installation of R with Nix-managed R shells.*

If you have installed R on your system through the usual means of installation
(so not with Nix, as described before), you can install the `{rix}` package as
usual as well. To install `{rix}`, run:

```{r parsermd-chunk-2-0, eval = FALSE}
install.packages("rix")
```

or use r-universe:

```{r parsermd-chunk-2, eval = FALSE}
install.packages("rix", repos = c(
  "https://ropensci.r-universe.dev",
  "https://cloud.r-project.org"
))
```

You can then use the `{rix}` package to generate expressions. Consult the next
vignette `vignette("project-environments")` to
learn more.

## Configuring an IDE

We recommend you continue with the next vignettes vignette
`vignette("installing-r-packages")` and
`vignette("installing-system-tools")`,
and also `vignette("configuring-ide")` which will guide you through setting
you your editor to use Nix shells effectively.

## Other "Nix"es

There are several implementations of the Nix package manager that you might want
to try if you're feeling adventurous... for now, we recommend to stick with Nix.

You can give [Lix](https://lix.systems/install/) a try, or
[Tvix](https://tvix.dev/).