---
title: "e - Interactive use"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{e-interactive-use}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

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

## Introduction

This vignette describes interactive use of environments built with `{rix}` using
a GUI editor like RStudio. We will discuss three scenarios: one in which you
already have R and RStudio installed on your operating system using the usual
installation method for your operating system, another in which you used Nix
to install R and RStudio, and finally the last scenario assumes you use another
IDE than RStudio, for example VS Code, Emacs, Vim...

It is also possible to evaluate single functions inside a dedicated, separate,
environment from another, main, interactive R session. For more details
regarding this, refer to the vignette `vignette("z-advanced-topic-running-r-or-shell-code-in-nix-from-r")`.

## Scenario 1: you installed R and RStudio using the usual installers

Let's suppose that you are already running R and RStudio and that you wish to
start using `{rix}` to define reproducible environments for your new projects
starting today. These environments will get built using the Nix package manager
and will not only include the required R packages for your project but also a
specific version of R, and any required system-level dependency as well. If you
are used to using RStudio, then you also need to install RStudio using Nix in
these project-specific environments. This is because RStudio re-defines many
environment variables and as such, a version of RStudio installed using the
usual installer for your operating system will not be able "to see" an R
interpreter installed with Nix. As stated in the macOS-specific vignette
`vignette("b2-setting-up-and-using-rix-on-macos")`, RStudio is not available on
macOS through `nixpkgs`. The following instructions are thus only applicable to
Linux and Windows. If you’re on macOS, read the macOS-specific vignette if
that’s not done already, and then come back here and skip to the "scenario 3" of
this vignette.

To run a project-specific version of RStudio and R, you will first need to
create a `default.nix` file and build the environment defined therein using Nix.
Once this is done, you then need to activate the environment before running this
project-specific version of RStudio. Suppose for example that you generated a
`default.nix` file for a project called "kmeans", and suppose that this project
is in the following path: `~/Documents/kmeans` (on Windows it would be something
like `C:\Users\Billy\Documents\kmeans`). For example, here is how you could use
`{rix}` to generate the `default.nix` for this environment:


```{r parsermd-chunk-2, eval = FALSE}
library(rix)

path_to_project <- "~/Documents/kmeans"

rix(
  r_ver = "latest",
  r_pkgs = c("dplyr", "ggplot2"),
  system_pkgs = NULL,
  git_pkgs = NULL,
  ide = "rstudio",
  project_path = path_to_project,
  overwrite = TRUE,
  print = TRUE
)
```

Because you also have R installed through the usual method for your operating
system, you also have a system or user library of packages. This library of
packages will interfere with the library of packages of your R environments
managed by Nix. To avoid this, running `rix()` not only writes a `default.nix`
file in your project's path, but also a custom `.Rprofile` file as well by
calling `rix_init()`. This `.Rprofile` will prevent clashes between your user
library of packages and the Nix environments’ library of packages.

Navigate to that folder using your terminal, and then run `nix-build` to build
the environment, and then `nix-shell`. You will then be *dropped into* a Nix
shell. You can also use `nix-shell --pure` instead, if you want to increase the
isolation of your Nix-R environments. The difference is that in an environment
started with `nix-shell`, you will still be able to access programs from your
system, while with `nix-shell --pure`, only programs installed for that Nix-R
environment will be available. Try something like `which wget` from a shell
started with `nix-shell` and then from a shell started with `nix-shell --pure`
as an example (replace `wget` by any other tool you have installed on your
computer).

Once in the shell, you can type `rstudio` to run this project specific version
of R and RStudio with all the required packages for this project, in this case
`{dplyr}` and `{ggplot2}`. If you get an error

```
qt.glx: qglx_findConfig: Failed to finding...
qt.glx: qglx_findConfig: Failed to finding...
Could not initialize GLX
Aborted (core dumped)
```

then you might need to run this before typing `rstudio`:

```
export QT_XCB_GL_INTEGRATION=none
```

This should solve the issue. In any case, we would be thankful if you opened
an issue if you encountered this bug and if the fix worked for you.

You can then work on it as usual.

You can also define a shortcut to a project that will take care of activating
the environment and launching RStudio. This way, you don't need to start a
terminal in that folder and drop into the Nix environment each time you want to
work on this project. For example, you could define a bash alias like this:

    alias kmeans='nix-shell ~/Documents/kmeans/default.nix --run rstudio

which would then execute RStudio in the right project by simply typing `kmeans`
in a terminal. It's also possible to create an executable script that you can
save in your PATH:

    #!/usr/bin/env nix-shell
    #!nix-shell /home/Billy/Document/kmeans/default.nix -i bash
    rstudio

(if needed, add the `export QT_XCB_GL_INTEGRATION=none` line before `rstudio`).
Name this script something like `kmeans_project`, make it executable (using
`chmod +x kmeans_project`), and now you can run RStudio within this environment
from anywhere.


## Scenario 2: you don't have any regular R and RStudio installation yet

If you don't have R installed you cannot use the `{rix}` package to generate new
expressions. In this case you might consider installing Nix first, and then run
the following command inside your terminal to get dropped into a temporary Nix
shell, which you can then use to generate new `default.nix` files:

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

Running the command above will download R and `{rix}` and then start an R
session inside your terminal. You can now run something like this:

    rix(r_ver = "latest",
        r_pkgs = c("dplyr", "ggplot2"),
        system_pkgs = NULL,
        git_pkgs = NULL,
        ide = "rstudio",
        # change to a project's path or leave it if you're in the right folder already
        project_path = ".", 
        overwrite = TRUE)

to generate a `default.nix`, and then use that file to generate an environment
with R, Rstudio, `{dplyr}` and `{ggplot2}`. If you need to add packages for your
project, rerun the command above, but add the needed packages to `r_pkgs`. If
you need to create a new environment, you could rerun the command above, or you
could install `{rix}` in that environment to generate new `default.nix` files.
Here, there is no need to use `rix_init()` as there won’t be any clash between
your user library of R packages (since you don’t have any), and the R
environments managed by Nix.

## Scenario 3: you use some IDE other than RStudio

VS Code, Positron and Emacs have been tested and unlike RStudio, you can use a
version of VS Code, Positron or Emacs installed through the usual means on your
system with development environments built with Nix. But there's nothing
stopping you from installing a project-specific version of VS Code or Emacs as
well if you wish. Configuration and settings should be accessible across every
version from every environment, since these are globally defined at the level of
your system. This means that to work on a project using VS Code, you would use a
call to `rix()` like so:

```{r, eval = FALSE}
rix(
  r_ver = "latest",
  r_pkgs = c("dplyr", "ggplot2"),
  system_pkgs = NULL,
  git_pkgs = NULL,
  ide = "code",
  project_path = ".",
  overwrite = TRUE
)
```

Notice the `ide = "code"` argument. This will not install VS Code from Nix, but
will install the `{languageserver}` package that is needed for using R with VS
Code. If you want to also install a project-specific version of VS Code, then
use `system_pkgs = "vscode"` or `system_pkgs = "vscodium"` if you prefer VS
Codium over VS Code. For any other editor such as Emacs or Vim, set `ide =
"other"`. Also use `ide = "other"` if you want to run scripts non-interactively,
for example on a CI/CD service.

## Conclusion

You now know the basics of Nix and `{rix}` and can start using it for your
projects! There are still some more vignettes that we recommend you read which
cover advanced topics.