Skip to content

Commit

Permalink
vignette
Browse files Browse the repository at this point in the history
  • Loading branch information
Bruno Rodrigues committed Jul 30, 2023
1 parent 70d36d7 commit d6ae2aa
Show file tree
Hide file tree
Showing 2 changed files with 238 additions and 87 deletions.
144 changes: 77 additions & 67 deletions dev/building_envs_with_rix.Rmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,52 +9,57 @@ editor_options:

The goal of `{rix}` is to provide an easy way to generate `default.nix` files.
These files are used by the Nix package manager to build an environment
according to the instructions defined in the file. Users can specify which
version of R, R packages, other needed software, IDE etc should be available
within that environment. Writing such files can be daunting for newcomers, and
so `{rix}` provides a function called `rix()`, which generates such a file.

`{rix}` does not require Nix to be installed to generate `default.nix` files, so
you could generate the file on one machine, and then build and use the environment
on another machine that has Nix installed on it (or on a CI/CD service like Github
Actions for example). If you wish to fully take advantage of Nix, I suggest you use
[Determinate System's installer](https://zero-to-nix.com/start/install). Nix can be
installed on Linux, macOS and Windows (but on Windows WSL2 must be enabled).

On Linux, once Nix is instaled, all the software that will be installed will be saved
to the `/nix` directory on the root partition. Complete development environments built
with Nix can take up much space, so if the available space on your root parttion is limited,
I 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:
according to the instructions defined in it. Users can specify which version of
R, R packages, other needed software, IDE etc should be available within that
environment. Writing such files can be daunting for newcomers, and so `{rix}`
provides a function called `rix()`, which takes care of the bulk of the work

`{rix}` does not require Nix to be installed to generate `default.nix` files, so
you could generate the file on one machine, and then build and use the
environment on another machine that has Nix installed on it (or on a CI/CD
service like Github Actions for example). If you wish to fully take advantage of
Nix, I suggest you use [Determinate System's
installer](https://zero-to-nix.com/start/install). Nix can be installed on
Linux, macOS and Windows (but on Windows WSL2 must be enabled).

On Linux, once Nix is instaled, all the software that will be installed will be
saved to the `/nix` directory on the root partition. Complete development
environments built with Nix can take up much space, so if the available space on
your root parttion is limited, I 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
```

If you have enough space on your root partition, you can ignore the above instructions.
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.

## Nix environments

An environment bulit by Nix is not totally isolated from the rest of the system. Suppose
that you the program `sl` installed on your system, and suppose you build a Nix
environment that also comes with `sl`. If you activate that environment, the version of `sl`
that will run when called is the one included in the Nix environment. If, however, you start
`sl` in a Nix environment that does not come with it, then your system's `sl` will get
used instead. This can be useful when working interactively with a Nix environment, because
you can use your usual IDE to work with it. The only exception is RStudio: RStudio looks
for R in predefined paths and cannot "see" the R from a Nix environment, it will instead
use the version installed on your machine. This means that if you use RStudio to work
interactively with R, you will need to install RStudio inside that environment.
`rix::rix()` does that for you.
An environment built by Nix is not totally isolated from the rest of the system.
Suppose that you the program `sl` installed on your system, and suppose you
build a Nix environment that also comes with `sl`. If you activate that
environment, the version of `sl` that will run when called is the one included
in the Nix environment. If, however, you start `sl` in a Nix environment that
does not come with it, then your system's `sl` will get used instead. This can
be useful when working interactively with a Nix environment, because you can use
your usual IDE to work with it. The only exception is RStudio: RStudio looks for
R in predefined paths and cannot "see" the R provided by a Nix environment, it
will instead use the version installed on your machine. This means that if you
use RStudio to work interactively with R, you will need to install RStudio
inside that environment. `rix::rix()` can generate a `default.nix` file that
does that.

## Day-to-day use of {rix}

The ideal workflow when using `{rix}` is to create a new, separate environment
at the start of a project. Let's say that you wish to analyse some data set, and
need `{dplyr}` and `{ggplot2}`. Let's also suppose that you use RStudio as your IDE.
With the `rix::rix()` function, you can easily generate the right `default.nix` file.
You need to provide the following inputs to `rix()`:
need `{dplyr}` and `{ggplot2}`. Let's also suppose that you use RStudio as your
IDE. With the `rix::rix()` function, you can easily generate the right
`default.nix` file. You need to provide the following inputs to `rix()`:

- `r_ver`: the version of R required. Use "current" for the latest version;
- `r_pkgs`: the required R packages. For example "dplyr";
Expand Down Expand Up @@ -84,29 +89,30 @@ This generates the following `default.nix` file:
cat(readLines(paste0(path_default_nix, "/default.nix")), sep = "\n")
```

To start using this environment, open a console in the folder containing `default.nix`
and use the following Nix command:
To start using this environment, open a console in the folder containing
`default.nix` and use the following Nix command:

```
nix-build
```

`nix-build` is a Nix command that builds an environment according to the specifications found
in a `default.nix` file. Once the environment is done building, you should find a new file
called `result` next to the `default.nix` file. This file is a symlink to the software
installed by Nix. To now use the environment, type:
`nix-build` is a Nix command that builds an environment according to the
specifications found in a `default.nix` file. Once the environment is done
building, you should find a new file called `result` next to the `default.nix`
file. This file is a symlink to the software installed by Nix. To now use the
environment, type:

```
nix-shell
```

You can now start RStudio by typing RStudio. This will start a version of RStudio specific
to this environment. If you already had RStudio installed by using your operating system's
installer, that version of RStudio will not be able to interact with Nix environments. This is
because RStudio looks for R in certain specific paths that don't include any Nix environments.

This is not the case with other editors like Visual Studio Code or Emacs. If you use Visual Studio
Code, you can use following call to `rix()`:
You can now start the RStudio provided by that environment by typing `rstudio`.
This will start a version of RStudio specific to this environment. If you
already had RStudio installed by using your operating system's installer, that
version of RStudio will not be able to interact with Nix environments. This is
because RStudio looks for R in certain specific paths that don't include any Nix
environments. This is not the case with other editors like Visual Studio Code or
Emacs. If you use Visual Studio Code, you can use the following call to `rix()`:

```{r}
path_default_nix <- tempdir()
Expand All @@ -128,21 +134,21 @@ This generates the following `default.nix` file:
cat(readLines(paste0(path_default_nix, "/default.nix")), sep = "\n")
```

As you can see, specifying `ide = "code"` adds the `{languageserver}` package
to the list of packages that must be installed for this environment. This is because
Visual Studio Code requires this package to interact with R. This will
not install a Nix environment-specific version of Visual Studio Code. Now, instead of typing
`rstudio` in the Nix shell of your environment, type `code` and this will start the
Visual Studio Code you usually use.
As you can see, specifying `ide = "code"` adds the `{languageserver}` package to
the list of packages that must be installed for this environment. This is
because Visual Studio Code requires this package to interact with R. This will
not install a Nix environment-specific version of Visual Studio Code. Now,
instead of typing `rstudio` in the Nix shell of your environment, type `code`
and this will start the Visual Studio Code you usually use.

If you use another editor, like Emacs, then use `ide = "other"`, and start that editor inside
an activated Nix environment.
If you use another editor, like Emacs, then use `ide = "other"`, and start that
editor inside an activated Nix environment.

## Running old projects with {rix}

The example below shows how to create a `default.nix` with instructions to build
an environment with R version 4.2.1, the `{dplyr}` and `{janitor}` packages
and no specific IDE:
an environment with R version 4.2.1, the `{dplyr}` and `{janitor}` packages and
no specific IDE:

```{r}
path_default_nix <- tempdir()
Expand All @@ -163,16 +169,19 @@ The file looks like this:
cat(readLines(paste0(path_default_nix, "/default.nix")), sep = "\n")
```

The first following line is quite important, as it shows which *revision* of
`nixpkgs` is being used for this environment. The *revision* is the commit
hash of that particular release of `nixpkgs`, here: `79b3d4bcae8`. This revision
of `nixpkgs` is the one that shipped version 4.2.1 of R, so the `{dplyr}` and
`{janitor}` packages that will get installed will be the versions available
in that revision as well.
The first line is quite important, as it shows which *revision* of `nixpkgs` is
being used for this environment. The *revision* is the commit hash of that
particular release of `nixpkgs`, here: `79b3d4bcae8`. This revision of `nixpkgs`
is the one that shipped version 4.2.1 of R, so the `{dplyr}` and `{janitor}`
packages that will get installed will be the versions available in that revision
as well. This means that R versions and package versions are always coupled when
using Nix. However, if you need a specific version of R, but also a specific
version of a package that is not available in that particular Nix revision, one
solution is to install that package from Github.

## Installing packages from Github

It is also possible to insall packages from Github:
It is also possible to install packages from Github:

```{r}
rix(r_ver = "4.2.1",
Expand All @@ -198,7 +207,8 @@ rix(r_ver = "4.2.1",
cat(readLines(paste0(path_default_nix, "/default.nix")), sep = "\n")
```

This will install two packages from Github: the `{housing}` package, from the `fusen` branch. The
commit is also provided, to pin the exact version of the package needed. The `{fusen}` package
is also installed.
This will install two packages from Github: the `{housing}` package and more
specifically the code as it is in the `fusen` branch. The commit is also
provided, to pin the exact version of the package needed. The `{fusen}` package
is also installed, from the main branch at commit `d617172447d`.

Loading

0 comments on commit d6ae2aa

Please sign in to comment.