Generate a Nix expression that builds a reproducible development environment
Usage
rix(
r_ver = "latest",
r_pkgs = NULL,
system_pkgs = NULL,
git_pkgs = NULL,
local_r_pkgs = NULL,
tex_pkgs = NULL,
ide = c("other", "code", "radian", "rstudio", "rserver"),
project_path,
overwrite = FALSE,
print = FALSE,
message_type = "simple",
shell_hook = NULL
)
Arguments
- r_ver
Character, defaults to "latest". The required R version, for example "4.0.0". You can check which R versions are available using
available_r()
. For reproducibility purposes, you can also provide anixpkgs
revision directly. For older versions of R,nix-build
might fail with an error stating 'this derivation is not meant to be built'. In this case, simply drop into the shell withnix-shell
instead of building it first. It is also possible to provide either "bleeding_edge" or "frozen_edge" if you need an environment with bleeding edge packages. Read more in the "Details" section below.- r_pkgs
Vector of characters. List the required R packages for your analysis here.
- system_pkgs
Vector of characters. List further software you wish to install that are not R packages such as command line applications for example. You can look for available software on the NixOS website https://search.nixos.org/packages?channel=unstable&from=0&size=50&sort=relevance&type=packages&query= # nolint
- git_pkgs
List. A list of packages to install from Git. See details for more information.
- local_r_pkgs
List. A list of local packages to install. These packages need to be in the
.tar.gz
or.zip
formats and must be in the same folder as the generated "default.nix" file.- tex_pkgs
Vector of characters. A set of TeX packages to install. Use this if you need to compile
.tex
documents, or build PDF documents using Quarto. If you don't know which package to add, start by adding "amsmath". See the Vignette "Authoring LaTeX documents" for more details.- ide
Character, defaults to "other". If you wish to use RStudio to work interactively use "rstudio" or "rserver" for the server version. Use "code" for Visual Studio Code. You can also use "radian", an interactive REPL. For other editors, use "other". This has been tested with RStudio, VS Code and Emacs. If other editors don't work, please open an issue.
- project_path
Character. Where to write
default.nix
, for example "/home/path/to/project". The file will thus be written to the file "/home/path/to/project/default.nix". If the folder does not exist, it will be created.- overwrite
Logical, defaults to FALSE. If TRUE, overwrite the
default.nix
file in the specified path.Logical, defaults to FALSE. If TRUE, print
default.nix
to console.- message_type
Character. Message type, defaults to
"simple"
, which gives minimal but sufficient feedback. Other values are currently"quiet
, which generates the files without message, and"verbose"
, displays all the messages.- shell_hook
Character of length 1, defaults to
NULL
. Commands added to theshellHook
variable are executed when the Nix shell starts. So by default, usingnix-shell default.nix
will start a specific program, possibly with flags (separated by space), and/or do shell actions. You can for example useshell_hook = R
, if you want to directly enter the declared Nix R session when dropping into the Nix shell. @details This function will write adefault.nix
and an.Rprofile
in the chosen path. Using the Nix package manager, it is then possible to build a reproducible development environment using thenix-build
command in the path. This environment will contain the chosen version of R and packages, and will not interfere with any other installed version (via Nix or not) on your machine. Every dependency, including both R package dependencies but also system dependencies like compilers will get installed as well in that environment.It is possible to use environments built with Nix interactively, either from the terminal, or using an interface such as RStudio. If you want to use RStudio, set the
ide
argument to"rstudio"
. Please be aware that RStudio is not available for macOS through Nix. As such, you may want to use another editor on macOS. To use Visual Studio Code (or Codium), set theide
argument to"code"
, which will add the{languageserver}
R package to the list of R packages to be installed by Nix in that environment. You can use the version of Visual Studio Code or Codium you already use, or also install it using Nix (by adding "vscode" or "vscodium" to the list ofsystem_pkgs
). For non-interactive use, or to use the environment from the command line, or from another editor (such as Emacs or Vim), set theide
argument to"other"
. We recommend reading thevignette("e-interactive-use")
for more details.Packages to install from Github or Gitlab must be provided in a list of 3 elements: "package_name", "repo_url" and "commit". To install several packages, provide a list of lists of these 3 elements, one per package to install. It is also possible to install old versions of packages by specifying a version. For example, to install the latest version of
{AER}
but an old version of{ggplot2}
, you could write:r_pkgs = c("AER", "ggplot2@2.2.1")
. Note however that doing this could result in dependency hell, because an older version of a package might need older versions of its dependencies, but other packages might need more recent versions of the same dependencies. If instead you want to use an environment as it would have looked at the time of{ggplot2}
's version 2.2.1 release, then use the Nix revision closest to that date, by settingr_ver = "3.1.0"
, which was the version of R current at the time. This ensures that Nix builds a completely coherent environment. For security purposes, users that wish to install packages from Github/Gitlab or from the CRAN archives must provide a security hash for each package.{rix}
automatically precomputes this hash for the source directory of R packages from GitHub/Gitlab or from the CRAN archives, to make sure the expected trusted sources that match the precomputed hashes in thedefault.nix
are downloaded. If Nix is available, then the hash will be computed on the user's machine, however, if Nix is not available, then the hash gets computed on a server that we set up for this purposes. This server then returns the security hash as well as the dependencies of the packages. It is possible to control this behaviour usingoptions(rix.sri_hash=x)
, wherex
is one of "check_nix" (the default), "locally" (use the local Nix installation) or "api_server" (use the remote server to compute and return the hash).Note that installing packages from Git or old versions using the
"@"
notation or local packages, does not leverage Nix's capabilities for dependency solving. As such, you might have trouble installing these packages. If that is the case, open an issue on{rix}
's Github repository.By default, the Nix shell will be configured with
"en_US.UTF-8"
for the relevant locale variables (LANG
,LC_ALL
,LC_TIME
,LC_MONETARY
,LC_PAPER
,LC_MEASUREMENT
). This is done to ensure locale reproducibility by default in Nix environments created withrix()
. If there are good reasons to not stick to the default, you can set your preferred locale variables viaoptions(rix.nix_locale_variables = list(LANG = "de_CH.UTF-8", <...>)
and the aforementioned locale variable names.It is possible to use
"bleeding_edge
" or"frozen_edge
" as the value for ther_ver
argument. This will create an environment with the very latest R packages."bleeding_edge
" means that every time you will build the environment, the packages will get updated. This is especially useful for environments that need to be constantly updated, for example when developing a package. In contrast,"frozen_edge
" will create an environment that will remain stable at build time. So if you create adefault.nix
file using"bleeding_edge
", each time you build it usingnix-build
that environment will be up-to-date. With"frozen_edge
" that environment will be up-to-date on the date that thedefault.nix
will be generated, and then each subsequent call tonix-build
will result in the same environment. We highly recommend you read the vignette titled "z - Advanced topic: Understanding the rPackages set release cycle and using bleeding edge packages".
Value
Nothing, this function only has the side-effect of writing two files:
default.nix
and .Rprofile
in the working directory. default.nix
contains a Nix expression to build a reproducible environment using the Nix
package manager, and .Rprofile
ensures that a running R session from a
Nix environment cannot access local libraries, nor install packages using
install.packages()
(nor remove nor update them).
Examples
if (FALSE) { # \dontrun{
# Build an environment with the latest version of R
# and the dplyr and ggplot2 packages
rix(
r_ver = "latest",
r_pkgs = c("dplyr", "ggplot2"),
system_pkgs = NULL,
git_pkgs = NULL,
local_r_pkgs = NULL,
ide = "code",
project_path = path_default_nix,
overwrite = TRUE,
print = TRUE,
message_type = "simple",
shell_hook = NULL
)
} # }