WIP: vignette for with_nix()

do an interactive rebase#

dev/running_r_or_shell_code_in_nix_from_r.Rmd

@@ -5,9 +5,11 @@ editor_options:
   chunk_output_type: console
 ---
 
+# Testing Code in Evolving Software Dependency Environments with Confidence
+
 Adhering to sound versioning practices is crucial for ensuring the reproducibility of software. Despite the expertise in software engineering, the ever-growing complexity and continuous development of new, potentially disruptive features present significant challenges in maintaining code functionality over time. This pertains not only to backward compatibility but also to future-proofing. When code handles critical production loads and relies on numerous external software libraries, it's likely that these dependencies will evolve. Infrastructure-as-code and other DevOps principles shine in addressing these challenges. However, they may appear less approachable and more labor-intensive for the average R developer.
 
-Are you ready to test your custom R functions and system commands in a a different environment with isolated software builds that are both pure at build and at runtime, without leaving the R console? Let's introduce `with_nix()`. `with_nix()` will evaluate custom R code or shell commands with command line interfaces provided by Nixpkgs in a Nix environment, and thereby bring the read-eval-print-loop feeling.
+Are you ready to test your custom R functions and system commands in a a different environment with isolated software builds that are both pure at build and at runtime, without leaving the R console? Let's introduce `with_nix()`. `with_nix()` will evaluate custom R code or shell commands with command line interfaces provided by Nixpkgs in a Nix environment, and thereby bring the read-eval-print-loop feeling. Not only can you evaluate custom R functions or shell commands in Nix environments, but you can also bring the results back to your current R session as R objects.
 
 ## **Two Operational Modes of Computations in Environments: 'System-to-Nix' and 'Nix-to-Nix'**
 
@@ -18,19 +20,24 @@ We aim to accommodate various use cases, considering a gradient of declarativity
 
 ## Case study 1: Evolution of base R
 
+1.  **'System-to-Nix'** environments: We assume that you launch an R session with an R version defined on your host operating system, either from the terminal or an integrated development environment like RStudio. You need to make sure that you actively control and know where you installed R and R packages from, and at what versions. You may have interactively tested that your custom function pipeline worked for the current setup. Most importantly, you want to check whether you get your computations running and achieve identical results when going back to a Nix revision that represent either newer or also older versions of R and package sources.
+2.  **'Nix-to-Nix'** environments: Your goals of testing code are the same as in 1., but you want more fine-grained control in the source environment where you launch \`with_nix()\` from, too. You are probably on the way of getting a passionate Nix user.
+
+# Case study 1: Evolution of base R
+
 Carefully curated software improves over time, so does R. We pick an example from the R changelog, the following [literal entry in R 4.2.0](https://cran.r-project.org/doc/manuals/r-release/NEWS.html):
 
 -   "`as.vector()` gains a `data.frame` method which returns a simple named list, also clearing a long standing 'FIXME' to enable `as.vector(<data.frame>, mode="list")`. This breaks code relying on `as.vector(<data.frame>)` to return the unchanged data frame."
 
-The goal is to illustrate this change.
+The goal is to illustrate this change in behavior before and after R version 4.2.0.
 
-### Setting up the software environment
+## Setting up the software environment
 
 We first create a isolated directory to prepare for a Nix environment, and write a custom `.Rprofile` file as well. Startup code written to this local `.Rprofile` will make sure that the system's user library (R_LIBS_USER) is excluded from library paths to load packages from. The R derivation in Nixpkgs includes the user library at first position (returned by `.libPaths()`). This is nice to install packages from a Nix-R session environment in ad-hoc and interactive manner. However, this comes at the cost that one needs be aware of potential run-time pollution of packages outside the pool of paths per package from the nix store. On macOS, we experienced a high-chance of segmentation faults when accidentally loading packages and linked system libraries from the system's user library, to give an example. rix::init() writes a configuration that takes care of runtime-pure R package libraries from declaratively defined Nix builds. Additionally, it modifies `.libPaths()` in the running R session.
 
 ```{r, eval=FALSE}
 library("rix")
-path_env_1 <- file.path(".", "_env-1_R4-2-0")
+path_env_1 <- file.path(".", "_env_1_R4-2-0")
 init(
   project_path = path_env_1,
   rprofile_action = "overwrite",
@@ -42,15 +49,19 @@ Next, we write a \`default.nix\` file containing Nix expressions that pin R vers
 
 ```{r, eval=FALSE}
 rix(
-  r_version = "4.2.0",
+  r_ver = "4.2.0",
   overwrite = TRUE,
   project_path = path_env_1
 )
 ```
 
+We know have set up the configuration for R 4.2.0 set up in a `default.nix` file in the folder `./env-1R-4-2-0.`
+
 ```{r, eval=FALSE}
 df <- data.frame(a = 1:3, b = 4:6)
-as.vector(x = df, mode ="list")
+out <- as.vector(x = df, mode ="list")
 ```
 
 ## Case study 2: Breaking changes in {stringr} 1.5.0
+
+We add one more layer to the reproducibility of R. User libraries from CRAN or GitHub, one thing that makes R shine is the huge collection of software packages available from the community.

vignettes/running-r-or-shell-code-in-nix-from-r.Rmd

@@ -20,9 +20,11 @@ library(rix)
 
 <!-- WARNING - This vignette is generated by {fusen} from dev/running_r_or_shell_code_in_nix_from_r.Rmd: do not edit by hand -->
 
+# Testing Code in Evolving Software Dependency Environments with Confidence
+
 Adhering to sound versioning practices is crucial for ensuring the reproducibility of software. Despite the expertise in software engineering, the ever-growing complexity and continuous development of new, potentially disruptive features present significant challenges in maintaining code functionality over time. This pertains not only to backward compatibility but also to future-proofing. When code handles critical production loads and relies on numerous external software libraries, it's likely that these dependencies will evolve. Infrastructure-as-code and other DevOps principles shine in addressing these challenges. However, they may appear less approachable and more labor-intensive for the average R developer.
 
-Are you ready to test your custom R functions and system commands in a a different environment with isolated software builds that are both pure at build and at runtime, without leaving the R console? Let's introduce `with_nix()`. `with_nix()` will evaluate custom R code or shell commands with command line interfaces provided by Nixpkgs in a Nix environment, and thereby bring the read-eval-print-loop feeling.
+Are you ready to test your custom R functions and system commands in a a different environment with isolated software builds that are both pure at build and at runtime, without leaving the R console? Let's introduce `with_nix()`. `with_nix()` will evaluate custom R code or shell commands with command line interfaces provided by Nixpkgs in a Nix environment, and thereby bring the read-eval-print-loop feeling. Not only can you evaluate custom R functions or shell commands in Nix environments, but you can also bring the results back to your current R session as R objects.
 
 
 ## **Two Operational Modes of Computations in Environments: 'System-to-Nix' and 'Nix-to-Nix'**
@@ -35,21 +37,27 @@ We aim to accommodate various use cases, considering a gradient of declarativity
 
 ## Case study 1: Evolution of base R
 
+1.  **'System-to-Nix'** environments: We assume that you launch an R session with an R version defined on your host operating system, either from the terminal or an integrated development environment like RStudio. You need to make sure that you actively control and know where you installed R and R packages from, and at what versions. You may have interactively tested that your custom function pipeline worked for the current setup. Most importantly, you want to check whether you get your computations running and achieve identical results when going back to a Nix revision that represent either newer or also older versions of R and package sources.
+2.  **'Nix-to-Nix'** environments: Your goals of testing code are the same as in 1., but you want more fine-grained control in the source environment where you launch \`with_nix()\` from, too. You are probably on the way of getting a passionate Nix user.
+
+
+# Case study 1: Evolution of base R
+
 Carefully curated software improves over time, so does R. We pick an example from the R changelog, the following [literal entry in R 4.2.0](https://cran.r-project.org/doc/manuals/r-release/NEWS.html):
 
 -   "`as.vector()` gains a `data.frame` method which returns a simple named list, also clearing a long standing 'FIXME' to enable `as.vector(<data.frame>, mode="list")`. This breaks code relying on `as.vector(<data.frame>)` to return the unchanged data frame."
 
-The goal is to illustrate this change.
+The goal is to illustrate this change in behavior before and after R version 4.2.0.
 
 
-### Setting up the software environment
+## Setting up the software environment
 
 We first create a isolated directory to prepare for a Nix environment, and write a custom `.Rprofile` file as well. Startup code written to this local `.Rprofile` will make sure that the system's user library (R_LIBS_USER) is excluded from library paths to load packages from. The R derivation in Nixpkgs includes the user library at first position (returned by `.libPaths()`). This is nice to install packages from a Nix-R session environment in ad-hoc and interactive manner. However, this comes at the cost that one needs be aware of potential run-time pollution of packages outside the pool of paths per package from the nix store. On macOS, we experienced a high-chance of segmentation faults when accidentally loading packages and linked system libraries from the system's user library, to give an example. rix::init() writes a configuration that takes care of runtime-pure R package libraries from declaratively defined Nix builds. Additionally, it modifies `.libPaths()` in the running R session.
 
 
 ```{r eval = FALSE}
 library("rix")
-path_env_1 <- file.path(".", "_env-1_R4-2-0")
+path_env_1 <- file.path(".", "_env_1_R4-2-0")
 init(
   project_path = path_env_1,
   rprofile_action = "overwrite",
@@ -62,16 +70,21 @@ Next, we write a \`default.nix\` file containing Nix expressions that pin R vers
 
 ```{r eval = FALSE}
 rix(
-  r_version = "4.2.0",
+  r_ver = "4.2.0",
   overwrite = TRUE,
   project_path = path_env_1
 )
 ```
 
+We know have set up the configuration for R 4.2.0 set up in a `default.nix` file in the folder `./env-1R-4-2-0.`
+
+
 ```{r eval = FALSE}
 df <- data.frame(a = 1:3, b = 4:6)
-as.vector(x = df, mode ="list")
+out <- as.vector(x = df, mode ="list")
 ```
 
 ## Case study 2: Breaking changes in {stringr} 1.5.0
 
+We add one more layer to the reproducibility of R. User libraries from CRAN or GitHub, one thing that makes R shine is the huge collection of software packages available from the community.
+