# e - Using an IDE with Nix shells

## Introduction

This vignette describes interactive use of environments built with `{rix}` using an IDE (GUI editor) like RStudio. Depending on your operating system and the editor you wish to use, different settings must be configured.

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")`.

### Our recommendation

The following are the setups we recommend you use to work using an IDE and Nix environments. To be recommended, a setup should:

- be easy to setup;
- work the same on any operating system;
- not require any type of special maintenance.

Regardless of your operating system, a general-purpose editor such as VS Code (or Codium), Emacs, or Neovim meets the above requirements. (Note: Neovim is not covered here due to lack of experience—PRs welcome!) However, some editors perform better on certain platforms.

Also, we recommend you uninstall R if it’s installed system-wide and also remove your local library of packages and instead only use dedicated Nix shells to manage your projects. While we made our possible for Nix shells to not interfere with a system-installed R, we recommend users go into the habit of taking some minutes at the start of a project to properly set up their development environment.

#### Recommended setup on macOS

On macOS, RStudio will only be available through Nix and only for versions 4.4.3 or more recent, or after the 2025-02-28 if you’re using dates. For older versions of R or dates, RStudio is not available for macOS through Nix so you cannot use it. As such, we recommend either VS Code (or Codium) or Positron for older dates or versions. Emacs or Neovim are also good options. See the relevant sections below to set up any of these editors. We also recommend to install the editor on macOS directly, and configure it to interact with Nix shells, instead of using Nix to install the editor, even though it does take some more effort to configure.

#### Recommended setup on Windows

On Windows, since you have to use Nix through WSL, your options are limited to editors that either:

- can be installed on Windows and interact with WSL, or
- can be launched directly from WSL.

We recommend to use an editor you can install directly on Windows and configure to interact nicely with WSL, and it turns out that this is mostly only VS Code (or Codium). There are ways to configure Positron to interact with WSL, but it requires significant effort and this is not discussed here. See this section to learn how to configure VS Code (or Codium).

If you want to use RStudio or Positron, this is also possible but:

- RStudio or Positron should ideally be installed with Nix inside WSL;
- your version of Windows needs to support WSLg which should be fine on Windows 11 or the very latest Windows 10 builds. WSLg allows you to run GUI apps from WSL.

You should also be aware that there is currently a bug in the RStudio Nix package that makes RStudio ignore project-specific `.Rprofile` files, which can be an issue if you also have a system-level library of packages. Instead, you can sure the `.Rprofile` generated by `rix()` yourself or you can uninstall the system-level R and library of packages.

Furthermore, be aware that there is a bug in WSLg that prevents modifier keys like Alt Gr from working properly.

If you prefer Emacs or Neovim, then we recommend to install it in WSL and use it in command line mode, not through WSLg (so starting Emacs with the `- nw` argument).

#### Recommended setup on Linux

On Linux distributions, the only real limitation is that RStudio cannot interact with Nix shells (just like on the other operating systems), so if you want to use RStudio then you need to install it using Nix.

You should also be aware that there is currently a bug in the RStudio Nix package that makes RStudio ignore project-specific `.Rprofile` files, which can be an issue if you also have a system-level library of packages. Instead, you can sure the `.Rprofile` generated by `rix()` yourself or you can uninstall the system-level R and library of packages.

If you use another editor, just follow the relevant instructions below; the question you need to think about is whether you want to use Nix to install the editor inside of the development shell or if you prefer to install your editor yourself using your distribution’s package manager, and configure it to interact with Nix shells. We recommend the latter option, regardless of the editor you choose.

## RStudio

RStudio must be installed by Nix in order to see and use Nix shells. So you cannot use the RStudio already installed on your computer to work with Nix shells. This means you need to set `ide = "rstudio"` if you wish to use RStudio.

You should also be aware that there is currently a bug in the RStudio Nix package that makes RStudio ignore project-specific `.Rprofile` files, which can be an issue if you also have a system-level library of packages. Instead, you can sure the `.Rprofile` generated by `rix()` yourself or you can uninstall the system-level R and library of packages.

### RStudio on macOS

To use RStudio on macOS simply use `ide = "rstudio"`, but be aware that this will only work for R version 4.4.3 at least, or for a date on or after the 2025-02-28. If you don’t need to work with older versions of R or older date, RStudio is an appropriate choice. Then, build the environment using `nix-build` and drop into the shell using `nix-shell`. Then, type `rstudio` to start RStudio. If you wish, you can even put the `rstudio` command in the shell hook to start it immediately as you run `nix-shell`.

### RStudio on Linux or Windows

To use RStudio on Linux or Windows simply use `ide = "rstudio"`. Then, build the environment using `nix-build` and drop into the shell using `nix-shell`. Then, type `rstudio` to start RStudio. On Windows, you need to have `WSLg` enabled, which should be the case on the latest versions of Windows. If you wish, you can even put the `rstudio` command in the shell hook to start it immediately as you run `nix-shell`.

On Linux and WSL, depending on your desktop environment, you might see the following error message when trying to launch RStudio:

    qt.glx: qglx_findConfig: Failed to finding matching FBConfig for QSurfaceFormat(version 2.0, options QFlags<QSurfaceFormat::FormatOption>(), depthBufferSize -1, redBufferSize 1, greenBufferSize 1, blueBufferSize 1, alphaBufferSize -1, stencilBufferSize -1, samples -1, swapBehavior QSurfaceFormat::SingleBuffer, swapInterval 1, colorSpace QSurfaceFormat::DefaultColorSpace, profile  QSurfaceFormat::NoProfile)
    Could not initialize GLX
    Aborted (core dumped)

in this case, run the following before running RStudio:

    export QT_XCB_GL_INTEGRATION=none

## Positron

### Letting Nix manage Positron on any operating system

If you want to install Positron with Nix, you need a call that looks like this:

    rix(
      date = ...,
      r_pkgs = c(...), # whatever packages you need
      ide = "positron",
      ...
    )

The advantage of letting Nix handle Positron is that you don’t need to configure anything else. Simply build your environment using `nix-build`, then activate the shell using `nix-shell` and run `positron` to start using Positron in the right environment (you can even put the `positron` command in the shell hook to start it immediately as you run `nix-shell`). Settings and extensions are shared between all the different Positrons of all your different shells so you don’t need to waste time reconfiguring different instances of Positron, and Nix shells that use the same version of Positron will not install it twice, but simply reuse it. However, if the version is slightly different, then a new version will be installed.

To avoid having different versions of Positron installed on your system, you can instead opt for the option where you install a single Positron instance on your system and use it with all the Nix shells.

### Configuring Positron installed on macOS to interact with Nix shells

If you prefer to use the Positron you have installed system-wide, then generate environments by setting `ide = "none"`:

    rix(
      date = ...,
      r_pkgs = c(...),
      ide = "none",
      ...
    )

Start by installing Positron using the official `.dmg` installer. Start Positron, and then the command palette using `COMMAND-SHIFT-P`. In the search bar, type `"Install 'positron' command in PATH"` and click on it: this will make it possible to start Positron from a terminal. Quit Positron completely. To use it with a Nix shell, open a terminal and navigate to the project’s folder, then activate the shell using `nix-shell` and now start Positron by typing `positron`. In the top right corner of Positron, you will now be able to select the R interpreter defined in the Nix shell.

### Configuring Positron installed on Linux or Windows to interact with Nix shells

On Linux, simply install Positron using the installer (the `.deb` or `.rpm` package depending on your distribution) and on Windows DO NOT INSTALL Positron using the Windows installer! You need to install Positron in your WSL distribution. Assuming your distribution is Ubuntu, download `.deb` package and put it in a folder in your WSL distribution, or run the following from line from Ubuntu (change Positron’s version to whatever is current):

    wget https://github.com/posit-dev/positron/releases/download/2025.02.0-137/Positron-2025.02.0-137-x64.deb

then run:

    sudo dpkg -i Positron-2025.02.0-137-x64.deb

This will install Positron in WSL.

Then, navigate to your project’s folder and start the Nix shell using `nix-shell` and then Positron by typing `positron`. On Linux, this will start your system-level Positron, on Windows, this will start the WSL Positron using WSLg. That WSL Positron is available for any Nix shells from WSL.

## VS Code/Codium

You can use VS Code or Codium (henceforth, I’ll refer to both these editors simply as “Code”) with Nix shells by either installing it through Nix (so by setting `ide = "code"` or `ide = "codium"`) or by installing it on your operating system and then configure it to be able to interact with Nix shells. In any case, you will need to install the `{languageserver}` R package for Code to interact properly with the R console.

Settings and extensions are shared between all the different Codes of all your different shells so you don’t need to waste time reconfiguring different instances of Code, and Nix shells that use the same version of Code will not install it twice, but simply reuse it. However, if the version is slightly different, then a new version will be installed.

To avoid having different versions of Code installed on your system, you can instead opt for the option where you install Code for your system using the usual installation method (so an installer for Windows or macOS, through your operating system’s package manager for any Linux distribution), and instead configure it to interact with Nix shells.

If you’re on Windows, using Code like this is particularly interesting, because it allows you to install Code on Windows as usual, and then you can configure it to interact with a Nix shell, even if it’s running from WSL. This is a very seamless experience.

### Letting Nix manage VS Code/Codium

So, concretely, if you want to install Code with Nix, you need a call that looks like this:

    rix(
      date = ...,
      r_pkgs = ...,
      ide = "code", # or "codium"
      ...
    )

But if you prefer to use the Code you have installed system-wide, then you need to add the `{languageserver}` package and use `ide = "none"`:

    rix(
      date = ...,
      r_pkgs = c("languageserver", ...), # languageserver is needed
      ide = "none",
      ...
    )

The advantage of letting Nix handle Code is that you don’t need to configure anything else. Simply build your environment using `nix-build`, then activate the shell using `nix-shell` and run `code` (for VS Code) or `codium` (for Codium). You can even put the `code` (or `codium`) command in the shell hook argument to have it start as soon as you drop in the development shell using `nix-shell`.

### Configuring native VS Code/Codium on your operating system

The same instructions apply whether your host operating system is Linux, macOS or Windows. The first step is of course to install Code on your operating system using the usual means of installing software.

If you’re on Windows, install Code on Windows, not in WSL. Code on Windows is able to interact with WSL seamlessly and before continuing here, please follow these instructions.

Then, you need to install a piece of software called `direnv`: `direnv` will automatically load Nix shells when you open a project that contains a `default.nix` file in an editor. It works on any operating system and many editors support it, including Code. Follow the instructions for your operating system here but if you’re using Windows, install `direnv` in WSL, so follow the instructions for whatever Linux distribution you’re using there (likely Ubuntu), or use Nix to install `direnv` if you prefer (this is the way I recommend to install it on macOS, unless you already use `brew`):

    nix-env -f '<nixpkgs>' -iA direnv

This will install `direnv` and make it available even outside of Nix shells!

Then, in Code, install the direnv extension (and also the WSL extension if you’re on Windows, as explained in the official documentation linked above!). Finally, add a file called `.envrc` and simply write `use nix` in it. Now, open the project’s folder using `File > Open Folder...` and you will see a pop-up stating `direnv: /PATH/TO/PROJECT/.envrc is blocked` and a button to allow it. Click `Allow` and then open an R script. You might get another pop-up asking you to restart the extension, so click `Restart`. Be aware that at this point, `direnv` will run `nix-shell` and so will start building the environment. If that particular environment hasn’t been built and cached yet, it might take some time before Code will be able to interact with it. You might get yet another popup, this time from the R Code extension complaining that R can’t be found. In this case, simply restart Code and open the project folder again: now it should work every time. For a new project, simply repeat this process:

- Generate the project’s `default.nix` file;
- Build it using `nix-build`;
- Create an `.envrc` and write `use nix` in it;
- Open the project’s folder in Code and click allow when prompted;
- Restart the extension and Code if necessary.

Another option is to create the `.envrc` file and write `use nix` in it, then open a terminal, navigate to the project’s folder, and run `direnv allow`. Doing this before open Code should not prompt you anymore.

## Emacs

### Letting Nix manage Emacs

Emacs can be installed through Nix, but is not an option of the `ide` argument. This is because there are several versions of Emacs available through Nix (find these versions here) so install whatever version you want by putting it in `system_pkgs` like so:

    rix(
      date = ...,
      r_pkgs = c(...), # whatever packages you need
      system_pkgs = "emacs",
      ...
    )

This doesn’t require any further configuration to use. Simply drop in the Nix shell using `nix-shell` and type `emacs`. You can set the `emacs` command as the shell hook so Emacs starts automatically upon entering the shell. On Windows, if WSLg is enabled, it’ll start Emacs from WSL, if not, it’ll start it as a terminal application. we recommend using Emacs as a terminal application instead of through WSLg, as there is a bug in WSLg that prevents modifier keys like AltGr from working properly. This is quite problematic with Emacs, so we recommend using it in cli mode using `emacs -nw`.

### Configuring native Emacs on your operating system

You can install Emacs on Linux and macOS and configure it to interact with Nix shells. Install Emacs using the usual means of installing software on your operating system. On Windows you cannot use the native Emacs installed on Windows to interact with WSL, so you will need to install Emacs on WSL. If your WSL distribution is Ubuntu (which it likely is), you can install Emacs with:

    sudo apt update
    sudo apt install -y emacs

Because you’re using the Emacs from your operating system, generate `default.nix` shells by setting `ide = "other"`:

    rix(
      date = ...,
      r_pkgs = c(...), # whatever packages you need
      ide = "other",
      ...
    )

Then, you need to install a piece of software called `direnv`: `direnv` will automatically load Nix shells when you open a project that contains a `default.nix` file in an editor. It works on any operating system and many editors support it, including Emacs. Follow the instructions for your operating system here but if you’re using Windows, install `direnv` in WSL, so follow the instructions for whatever Linux distribution you’re using there (likely Ubuntu), or use Nix to install `direnv` if you prefer (this is the way I recommend to install it on macOS, unless you already use `brew`):

    nix-env -f '<nixpkgs>' -iA direnv

This will install `direnv` and make it available even outside of Nix shells!

Then install the Emacs `direnv` package. Finally, add a file called `.envrc` and simply write `use nix` in it. Now, open the project’s folder in a terminal and type `direnv allow`. Be aware that at this point, `direnv` will run `nix-shell` and so will start building the environment. If that particular environment hasn’t been built and cached yet, it might take some time. Starting Emacs and loading a script from that folder will now load the environment for you automatically. On Windows, starting Emacs from WSL will start the Linux GUI version using WSLg. As mentioned in the introduction, be aware that there is a bug in WSLg that prevents modifier keys like Alt Gr from working properly. This is quite problematic with Emacs, so we recommend using it in cli mode using `emacs -nw`.

For a new project, simply repeat this process:

- Generate the project’s `default.nix` file;
- Build it using `nix-build`;
- Create an `.envrc` and write `use nix` in it;
- Open the project’s folder in a terminal and run `direnv allow`.

## Making a launcher to start your editor

If you don’t use `direnv` to automatically load the Nix shell with your editor, you can also create a launcher using `rix::make_launcher("rstudio")` (change `"rstudio"` to whichever command starts your editor). This will create a script called `start-EDITOR.sh` where `EDITOR` will be replaced by what you used before.

The contents of the script are the following:

    #!/usr/bin/env nix-shell
    #!nix-shell default.nix -i bash
    EDITOR

Give this script execution rights (by using `chmod +x start-EDITOR.sh` in a terminal) and you’ll be able to start your editor in the right environment by either clicking on it, or by running `./start-EDITOR.sh` in the terminal.

(On Linux, if you use RStudio, and only if needed, add the `export QT_XCB_GL_INTEGRATION=none` line before `rstudio`).

You can also define a shortcut to a project that will take care of activating the environment and launching your editor. 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 for your project that uses the K-means algorithm.