---
title: "d2 - Installing system tools and TexLive packages in a Nix environment"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{d2-installing-system-tools-and-texlive-packages-in-a-nix-environment}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

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

## Introduction

More than 100'000 pieces of software are available through the Nix package
manager. Nix’s repository of packages is called `nixpkgs` and it includes the
entirety of CRAN and Bioconductor. `nixpkgs` is actually "just" a Github
repository containing thousands upon thousands of Nix expressions. When
installing a package, these expressions get evaluated, and the package in
question gets installed. What "installed" means can vary: sometimes the package
gets built from source, sometimes a pre-compiled binary package for your
operating system gets downloaded and made available.

For example,
[here](https://github.com/NixOS/nixpkgs/blob/dce218f4f35440622d2056f93ddc335351763bb4/pkgs/development/libraries/quarto/default.nix)
is the Nix expression that downloads and installs [Quarto](https://quarto.org/).
This is an example of an expression that downloads the pre-compiled
binary from Quarto’s own Github repository, and then installs it. The
installation process in this case is essentially making sure that Quarto is able
to find its dependencies, which also get installed from Nix, and some R and
Python packages to make Quarto work well with both languages also get installed.

It is possible to use `rix()` to add tools to an environment and this vignette
explains how.


## Adding tools to an environment

The call below generates a `default.nix` that defines an environment with the
latest version of R available in `nixpkgs`. The R `{quarto}` package is also
installed, as well as the `quarto` command line tool (required to edit Quarto
documents from R using the `{quarto}` package) and git:

```{r, eval = F}
path_default_nix <- tempdir()

rix(
  r_ver = "latest",
  r_pkgs = c("quarto"),
  system_pkgs = c("quarto", "git"),
  git_pkgs = NULL,
  ide = "other",
  project_path = path_default_nix,
  overwrite = TRUE
)
```

```{r parsermd-chunk-2, echo = F}
#> # This file was generated by the {rix} R package v0.7.1 on 2024-07-01
#> # with following call:
#> # >rix(r_ver = "12a9c0004bc987afb1ff511ebb97b67497a68e22",
#> #  > r_pkgs = c("quarto"),
#> #  > system_pkgs = c("quarto",
#> #  > "git"),
#> #  > git_pkgs = NULL,
#> #  > ide = "other",
#> #  > project_path = path_default_nix,
#> #  > overwrite = TRUE)
#> # It uses nixpkgs' revision 12a9c0004bc987afb1ff511ebb97b67497a68e22 for reproducibility purposes
#> # which will install R version latest.
#> # Report any issues to https://github.com/ropensci/rix
#> let
#>  pkgs = import (fetchTarball "https://github.com/NixOS/nixpkgs/archive/12a9c0004bc987afb1ff511ebb97b67497a68e22.tar.gz") {};
#>
#>   rpkgs = builtins.attrValues {
#>     inherit (pkgs.rPackages)
#>       quarto;
#>   };
#>
#>   system_packages = builtins.attrValues {
#>     inherit (pkgs)
#>       quarto
#>       git
#>       R
#>       glibcLocales
#>       nix;
#>   };
#>
#> in
#>
#> pkgs.mkShell {
#>   LOCALE_ARCHIVE = if pkgs.system == "x86_64-linux" then  "${pkgs.glibcLocales}/lib/locale/locale-archive" else "";
#>   LANG = "en_US.UTF-8";
#>    LC_ALL = "en_US.UTF-8";
#>    LC_TIME = "en_US.UTF-8";
#>    LC_MONETARY = "en_US.UTF-8";
#>    LC_PAPER = "en_US.UTF-8";
#>    LC_MEASUREMENT = "en_US.UTF-8";
#>
#>   buildInputs = [  rpkgs  system_packages   ];
#>
#> }
```

You can look for all the available software
[here](https://search.nixos.org/packages?channel=unstable&from=0&size=50&sort=relevance&type=packages&query=).
Simply look for the right package name, and add it to the `system_pkgs` argument
of `rix()`. If you have trouble finding something, don’t hesitate to 
[open an issue ](https://github.com/ropensci/rix/issues) and ask for support!

## Installing TexLive packages

Whether you use Quarto, Rmarkdown, or Sweave, literate programming with R
requires a TexLive distribution to be installed. You can use `rix()` to install
a minimalist TexLive distribution and then add the packages that you require as
you go. The basic use is to simply add a TexLive package to the `tex_pkgs`
argument of `rix()` like this:

```{r, eval = F}
path_default_nix <- tempdir()

rix(
  r_ver = "latest",
  r_pkgs = c("quarto"),
  system_pkgs = "quarto",
  tex_pkgs = c("amsmath"),
  ide = "other",
  project_path = path_default_nix,
  overwrite = TRUE,
  print = TRUE
)
#> # This file was generated by the {rix} R package v0.7.1 on 2024-07-01
#> # with following call:
#> # >rix(r_ver = "12a9c0004bc987afb1ff511ebb97b67497a68e22",
#> #  > r_pkgs = c("quarto"),
#> #  > system_pkgs = "quarto",
#> #  > tex_pkgs = c("amsmath"),
#> #  > ide = "other",
#> #  > project_path = path_default_nix,
#> #  > overwrite = TRUE,
#> #  > print = TRUE)
#> # It uses nixpkgs' revision 12a9c0004bc987afb1ff511ebb97b67497a68e22 for reproducibility purposes
#> # which will install R version latest.
#> # Report any issues to https://github.com/ropensci/rix
#> let
#>  pkgs = import (fetchTarball "https://github.com/NixOS/nixpkgs/archive/12a9c0004bc987afb1ff511ebb97b67497a68e22.tar.gz") {};
#>
#>   rpkgs = builtins.attrValues {
#>     inherit (pkgs.rPackages)
#>       quarto;
#>   };
#>
#>   tex = (pkgs.texlive.combine {
#>     inherit (pkgs.texlive)
#>       scheme-small
#>       amsmath;
#>   });
#>
#>   system_packages = builtins.attrValues {
#>     inherit (pkgs)
#>       quarto
#>       R
#>       glibcLocales
#>       nix;
#>   };
#>
#> in
#>
#> pkgs.mkShell {
#>   LOCALE_ARCHIVE = if pkgs.system == "x86_64-linux" then  "${pkgs.glibcLocales}/lib/locale/locale-archive" else "";
#>   LANG = "en_US.UTF-8";
#>    LC_ALL = "en_US.UTF-8";
#>    LC_TIME = "en_US.UTF-8";
#>    LC_MONETARY = "en_US.UTF-8";
#>    LC_PAPER = "en_US.UTF-8";
#>    LC_MEASUREMENT = "en_US.UTF-8";
#>
#>   buildInputs = [  rpkgs tex system_packages   ];
#>
#> }
```

This will automically add the *small* TexLive distribution available through
`nixpkgs` with the `amsmath` LaTex package. To know more about setting up
environments for literate programming, refer to the vignette
`vignette("z-advanced-topic-building-an-environment-for-literate-programming")`.

## Installing IDEs

Environments built with Nix are not completely cut off from the rest of your
system, and as such, you should be able to use your usual IDE to interact with
Nix environments. The only exception is RStudio. Everything will be explained in
greater detail in the vignette `vignette("e-interactive-use")`.