diff --git a/dev/building_envs_with_rix.Rmd b/dev/building_envs_with_rix.Rmd index b3f47050..83cebe4f 100644 --- a/dev/building_envs_with_rix.Rmd +++ b/dev/building_envs_with_rix.Rmd @@ -214,3 +214,5 @@ 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`. +To learn more about using `{rix}` on a daily basis, read the [Interactive +use](https://b-rodrigues.github.io/rix/articles/interactive-use.html) vignette. diff --git a/dev/config_fusen.yaml b/dev/config_fusen.yaml index 712e78a0..35cda2bb 100644 --- a/dev/config_fusen.yaml +++ b/dev/config_fusen.yaml @@ -37,6 +37,19 @@ data_doc.Rmd: check: true document: true overwrite: 'yes' +interactive_use.Rmd: + path: dev/interactive_use.Rmd + state: active + R: [] + tests: [] + vignettes: vignettes/interactive-use.Rmd + inflate: + flat_file: dev/interactive_use.Rmd + vignette_name: Interactive use + open_vignette: true + check: true + document: true + overwrite: 'yes' non_interactive_use.Rmd: path: dev/non_interactive_use.Rmd state: active diff --git a/dev/interactive_use.Rmd b/dev/interactive_use.Rmd index b5969d7c..d5dd4d80 100644 --- a/dev/interactive_use.Rmd +++ b/dev/interactive_use.Rmd @@ -10,29 +10,32 @@ editor_options: This vignette describes interactive use of environments built with `{rix}` using a GUI editor like RStudio. I will discuss two scenarios: one in which you already have R and RStudio installed on your operating system using the usual -installation method for your operating system, and another in which you used -Nix to install R and RStudio (or any other IDE). +installation method for your operating system, and another in which you used Nix +to install R and RStudio (or any other IDE). ## Scenario 1: you installed R and RStudio as usual 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 -henceforth. 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. If you are used to using RStudio, then you also need to -install RStudio using Nix. To run this project specific version of RStudio, 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 +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. 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`). Navigate to that folder using your terminal, -and then run `nix-shell`. You will then be *dropped into* a Nix shell. From there -you can type `rstudio` to run this project specific version of RStudio with all -the packages. You can then work on it as usual. +and then run `nix-shell`. You will then be *dropped into* a Nix shell. From +there you can type `rstudio` to run this project specific version of RStudio +with all the packages. 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. For example, you could define a bash alias -like this: +the environment and launching rstudio. For example, you could define a bash +alias like this: ``` alias kmeans='nix-shell ~/Documents/kmeans/default.nix --run rstudio @@ -96,3 +99,10 @@ into an R console. From there you can start using `{rix}` to generate new and more complex environments. ## Other IDEs + +Visual Studio Code and Emacs have been tested and unlike RStudio, you can use +the version of either VS Code or Emacs that you already have installed on your +system. But there's nothing stopping you from installing a project-specific +version of VS Code or Emacs as well. Configuration and settings should be +accessible across every version from every environment, since these are globally +defined at the level of your system. diff --git a/vignettes/building-reproducible-development-environments-with-rix.Rmd b/vignettes/building-reproducible-development-environments-with-rix.Rmd index f8a3d889..abd00ec5 100644 --- a/vignettes/building-reproducible-development-environments-with-rix.Rmd +++ b/vignettes/building-reproducible-development-environments-with-rix.Rmd @@ -240,4 +240,6 @@ 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`. +To learn more about using `{rix}` on a daily basis, read the [Interactive +use](https://b-rodrigues.github.io/rix/articles/interactive-use.html) vignette. diff --git a/vignettes/interactive-use.Rmd b/vignettes/interactive-use.Rmd index 2d86d513..4db9fb56 100644 --- a/vignettes/interactive-use.Rmd +++ b/vignettes/interactive-use.Rmd @@ -18,7 +18,113 @@ knitr::opts_chunk$set( library(rix) ``` - + ## Introduction +This vignette describes interactive use of environments built with `{rix}` using +a GUI editor like RStudio. I will discuss two scenarios: one in which you +already have R and RStudio installed on your operating system using the usual +installation method for your operating system, and another in which you used Nix +to install R and RStudio (or any other IDE). + + +## Scenario 1: you installed R and RStudio as usual + +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. 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`). Navigate to that folder using your terminal, +and then run `nix-shell`. You will then be *dropped into* a Nix shell. From +there you can type `rstudio` to run this project specific version of RStudio +with all the packages. 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. 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 +``` + +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 install R and RStudio using Nix + +In case 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 using the expression below, which will install the latest development +version of `{rix}` and R: + +``` +{ pkgs ? import (fetchTarball "https://github.com/NixOS/nixpkgs/archive/8ad5e8132c5dcf977e308e7bf5517cc6cc0bf7d8.tar.gz") {} }: + +with pkgs; + +let + bootstrap_env = rWrapper.override { + packages = with rPackages; [ + + (buildRPackage { + name = "rix"; + src = fetchgit { + url = "https://github.com/b-rodrigues/rix/"; + branchName = "master"; + rev = "935fb194b38adfb085a5bda9ebe5dc5bb504f2cb"; + sha256 = "sha256-qMKcBcoemx3CcayA0Vt3LcDCAskhWyWXJBJVN8BaIOw="; + }; + propagatedBuildInputs = [ + httr + jsonlite + ]; + }) + ]; + }; +in +mkShell { + buildInputs = [bootstrap_env]; + shellHook = "R"; +} + +``` + +Save this into a `default.nix` file and run `nix-build` then `nix-shell` to drop +into an R console. From there you can start using `{rix}` to generate new and +more complex environments. + + +## Other IDEs + +Visual Studio Code and Emacs have been tested and unlike RStudio, you can use +the version of either VS Code or Emacs that you already have installed on your +system. But there's nothing stopping you from installing a project-specific +version of VS Code or Emacs as well. Configuration and settings should be +accessible across every version from every environment, since these are globally +defined at the level of your system. +