diff --git a/README.Rmd b/README.Rmd
index 1bfef961..46948211 100644
--- a/README.Rmd
+++ b/README.Rmd
@@ -29,35 +29,43 @@ knitr::opts_chunk$set(
## Introduction
-`{rix}` is an R package that leverages Nix, a powerful package manager focusing
-on reproducible builds. With Nix, it is possible to create project-specific
-environments that contain a project-specific version of R and R packages (as
-well as other tools or languages, if needed). You can use `{rix}` and Nix to
-replace `{renv}` and Docker with one single tool. Nix is an incredibly useful
-piece of software for ensuring reproducibility of projects, in research or
-otherwise, or for running web applications like Shiny apps or `{plumber}` APIs
-in a controlled environment.
-
-Nix has quite a high entry cost though, because Nix is a complex piece of
-software that comes with its own programming language (also called Nix) whose
-purpose is to solve a complex problem: installing software in a reproducible
-manner, on any operating system or hardware.
-
-`{rix}` provides functions to help you write Nix expressions (written in the Nix
-language): these expressions can then be used by the Nix package manager to
-build completely reproducible development environments. These environments can
-be used for interactive data analysis or running pipelines in a CI/CD
-environment. Environments built with Nix contain R and all the required packages
-that you need for your project: there are currently more than 80.000 pieces of
-software available through the Nix package manager, including the entirety of
-CRAN and Bioconductor packages. It is also possible to install older releases of
-packages, or install packages from GitHub.
-
-The Nix package manager is extremely powerful: not only it handles all the
-dependencies of any package extremely well, it is also possible with it to
-reproduce environments containing old releases of software. It is thus possible
-to build environments that contain R version 4.0.0 (for example) to run an old
-project originally developed on that version of R.
+`{rix}` is an R package that leverages [Nix](https://nixos.org/),
+a powerful package manager focusing on reproducible builds. With Nix, it is
+possible to create project-specific environments that contain a project-specific
+version of R and R packages (as well as other tools or languages, if needed).
+You can use `{rix}` and Nix to replace `{renv}` and Docker with one single tool.
+Nix is an incredibly useful piece of software for ensuring reproducibility of
+projects, in research or otherwise. For example, it allows you run web
+applications like Shiny apps or `{plumber}` APIs in a controlled environment.
+
+Nix has a fairly high entry cost though. Nix is a complex piece of software that
+comes with its own programming language, which is also called Nix. Its purpose
+is to solve a complex problem: defining instructions on how to build software
+packages and manage configurations in a declarative way. This makes sure that
+software gets installed in fully reproducible manner, on any operating system or
+hardware.
+
+`{rix}` provides functions to help you write and deploy Nix expressions (written
+in the Nix language). These expressions will be the inputs for the Nix package
+manager, to build sets of software packages and provide them in a reproducible
+development environment. These environments can be used for interactive data
+analysis, or reproduced when running pipelines in CI/CD systems. On the
+[Nixpkgs collection](https://github.com/nixos/nixpkgs), there are currently more
+than 80.000 pieces of software available through the Nix package manager.
+Through {rix}, you can define and build isolated R environments through Nix
+package manager with ease. Like this, environments contain R and all the
+required packages that you need for your project. You can also add any other
+software tool available. The Nix R ecosystem currently includes the entirety of
+CRAN and Bioconductor packages. Like with any other programming language and
+software, it is also possible to install older releases of R packages, or
+install packages from GitHub at defined states.
+
+The Nix package manager is extremely powerful. Not only does it handle all the
+dependencies of any package extremely well in a deterministic manner, it is also
+possible with it to reproduce environments containing old releases of software.
+It is thus possible to build environments containing R version 4.0.0 (for
+example) to run an old project that was originally developed on that version of
+R.
As stated above, with Nix, it is essentially possible to replace `{renv}` and
Docker combined. If you need other tools or languages like Python or Julia, this
@@ -68,15 +76,26 @@ WSL2) and `{rix}` comes with the following features:
- have several versions of R and R packages installed at the same time on the
same system;
- define complete development environments as code and use them anywhere;
-- run single function in a different environment (potentially with a different R
- version and R packages) for an interactive R session and get back the output
- of that function using `with_nix()`;
+- run single R functions (and objects in the call stack) in a different
+ environment (potentially with a different R version and R packages) for an
+ interactive R session, and get back the output of that function using
+ `with_nix()`;
`{rix}` does not require Nix to be installed on your system to generate
expressions. This means that you can generate expressions on a system on which
you cannot easily install software, and then use these expressions on the cloud
or on a CI/CD environment to build the project there.
+If you have R installed, you can start straight away from your R session by
+first installing `{rix}`:
+
+```{r, eval=FALSE}
+install.packages("rix", repos = c("https://b-rodrigues.r-universe.dev",
+ "https://cloud.r-project.org"))
+
+library("rix")
+```
+
Here is an example of how to define an environment "as code" using `rix()`:
```{r, eval = F}
@@ -98,6 +117,9 @@ the Nix package manager must be installed.
*If you are not familiar with Nix or `{rix}` skip to the next section.*
+
+
+Click to expand
If you are already familiar with Nix and R, and simply want to get started as
quickly as possible, you can start by installing Nix using the installer from
[Determinate
@@ -110,16 +132,6 @@ curl --proto '=https' --tlsv1.2 -sSf \
sh -s -- install
```
-If you have R installed, you can start straight away from your R session by first
-installing `{rix}`:
-
-```{r, eval=FALSE}
-install.packages("rix", repos = c("https://b-rodrigues.r-universe.dev",
- "https://cloud.r-project.org"))
-
-library("rix")
-```
-
You can check that everything works well by trying to build the Nix expression
that ships with `{rix}`. Nix expressions are typically saved into files with the
name `default.nix` or `shell.nix`. This expression installs the latest version
@@ -151,11 +163,14 @@ nix-shell --expr "$(curl -sl https://raw.githubusercontent.com/b-rodrigues/rix/m
You can then create new development environment definitions, build them, and
start using them.
+
## Getting started for new users
To get started with `{rix}` and Nix, you should read the following vignette
-`vignette("a-getting-started")`. The vignettes are numbered to get you to learn
+`vignette("a-getting-started")`
+([online documentation](https://b-rodrigues.github.io/rix/articles/a-getting-started.html)).
+The vignettes are numbered to get you to learn
how to use `{rix}` and Nix smoothly. There’s a lot of info, so take your time
reading the vignettes. Don’t hesitate to open an issue if something is not
clear.
diff --git a/README.md b/README.md
index f046eeb6..f31c38d1 100644
--- a/README.md
+++ b/README.md
@@ -26,38 +26,46 @@ rix](https://b-rodrigues.r-universe.dev/badges/rix?scale=1&color=pink&style=roun
## Introduction
-`{rix}` is an R package that leverages Nix, a powerful package manager
-focusing on reproducible builds. With Nix, it is possible to create
-project-specific environments that contain a project-specific version of
-R and R packages (as well as other tools or languages, if needed). You
-can use `{rix}` and Nix to replace `{renv}` and Docker with one single
-tool. Nix is an incredibly useful piece of software for ensuring
-reproducibility of projects, in research or otherwise, or for running
-web applications like Shiny apps or `{plumber}` APIs in a controlled
-environment.
-
-Nix has quite a high entry cost though, because Nix is a complex piece
-of software that comes with its own programming language (also called
-Nix) whose purpose is to solve a complex problem: installing software in
-a reproducible manner, on any operating system or hardware.
-
-`{rix}` provides functions to help you write Nix expressions (written in
-the Nix language): these expressions can then be used by the Nix package
-manager to build completely reproducible development environments. These
-environments can be used for interactive data analysis or running
-pipelines in a CI/CD environment. Environments built with Nix contain R
-and all the required packages that you need for your project: there are
-currently more than 80.000 pieces of software available through the Nix
-package manager, including the entirety of CRAN and Bioconductor
-packages. It is also possible to install older releases of packages, or
-install packages from GitHub.
-
-The Nix package manager is extremely powerful: not only it handles all
-the dependencies of any package extremely well, it is also possible with
-it to reproduce environments containing old releases of software. It is
-thus possible to build environments that contain R version 4.0.0 (for
-example) to run an old project originally developed on that version of
-R.
+`{rix}` is an R package that leverages [Nix](https://nixos.org/), a
+powerful package manager focusing on reproducible builds. With Nix, it
+is possible to create project-specific environments that contain a
+project-specific version of R and R packages (as well as other tools or
+languages, if needed). You can use `{rix}` and Nix to replace `{renv}`
+and Docker with one single tool. Nix is an incredibly useful piece of
+software for ensuring reproducibility of projects, in research or
+otherwise. For example, it allows you run web applications like Shiny
+apps or `{plumber}` APIs in a controlled environment.
+
+Nix has a fairly high entry cost though. Nix is a complex piece of
+software that comes with its own programming language, which is also
+called Nix. Its purpose is to solve a complex problem: defining
+instructions on how to build software packages and manage configurations
+in a declarative way. This makes sure that software gets installed in
+fully reproducible manner, on any operating system or hardware.
+
+`{rix}` provides functions to help you write and deploy Nix expressions
+(written in the Nix language). These expressions will be the inputs for
+the Nix package manager, to build sets of software packages and provide
+them in a reproducible development environment. These environments can
+be used for interactive data analysis, or reproduced when running
+pipelines in CI/CD systems. On the [Nixpkgs
+collection](https://github.com/nixos/nixpkgs), there are currently more
+than 80.000 pieces of software available through the Nix package
+manager. Through {rix}, you can define and build isolated R environments
+through Nix package manager with ease. Like this, environments contain R
+and all the required packages that you need for your project. You can
+also add any other software tool available. The Nix R ecosystem
+currently includes the entirety of CRAN and Bioconductor packages. Like
+with any other programming language and software, it is also possible to
+install older releases of R packages, or install packages from GitHub at
+defined states.
+
+The Nix package manager is extremely powerful. Not only does it handle
+all the dependencies of any package extremely well in a deterministic
+manner, it is also possible with it to reproduce environments containing
+old releases of software. It is thus possible to build environments
+containing R version 4.0.0 (for example) to run an old project that was
+originally developed on that version of R.
As stated above, with Nix, it is essentially possible to replace
`{renv}` and Docker combined. If you need other tools or languages like
@@ -70,15 +78,26 @@ features:
on the same system;
- define complete development environments as code and use them
anywhere;
-- run single function in a different environment (potentially with a
- different R version and R packages) for an interactive R session and
- get back the output of that function using `with_nix()`;
+- run single R functions (and objects in the call stack) in a different
+ environment (potentially with a different R version and R packages)
+ for an interactive R session, and get back the output of that function
+ using `with_nix()`;
`{rix}` does not require Nix to be installed on your system to generate
expressions. This means that you can generate expressions on a system on
which you cannot easily install software, and then use these expressions
on the cloud or on a CI/CD environment to build the project there.
+If you have R installed, you can start straight away from your R session
+by first installing `{rix}`:
+
+``` r
+install.packages("rix", repos = c("https://b-rodrigues.r-universe.dev",
+ "https://cloud.r-project.org"))
+
+library("rix")
+```
+
Here is an example of how to define an environment “as code” using
`rix()`:
@@ -102,6 +121,11 @@ installed.
*If you are not familiar with Nix or `{rix}` skip to the next section.*
+
+
+Click to expand
+
+
If you are already familiar with Nix and R, and simply want to get
started as quickly as possible, you can start by installing Nix using
the installer from [Determinate
@@ -114,16 +138,6 @@ curl --proto '=https' --tlsv1.2 -sSf \
sh -s -- install
```
-If you have R installed, you can start straight away from your R session
-by first installing `{rix}`:
-
-``` r
-install.packages("rix", repos = c("https://b-rodrigues.r-universe.dev",
- "https://cloud.r-project.org"))
-
-library("rix")
-```
-
You can check that everything works well by trying to build the Nix
expression that ships with `{rix}`. Nix expressions are typically saved
into files with the name `default.nix` or `shell.nix`. This expression
@@ -154,14 +168,16 @@ installed, you can run a temporary R session with R using this command
You can then create new development environment definitions, build them,
and start using them.
+
## Getting started for new users
To get started with `{rix}` and Nix, you should read the following
-vignette `vignette("a-getting-started")`. The vignettes are numbered to
-get you to learn how to use `{rix}` and Nix smoothly. There’s a lot of
-info, so take your time reading the vignettes. Don’t hesitate to open an
-issue if something is not clear.
+vignette `vignette("a-getting-started")` ([online
+documentation](https://b-rodrigues.github.io/rix/articles/a-getting-started.html)).
+The vignettes are numbered to get you to learn how to use `{rix}` and
+Nix smoothly. There’s a lot of info, so take your time reading the
+vignettes. Don’t hesitate to open an issue if something is not clear.
### Docker
diff --git a/dev/2b-macos.Rmd b/dev/2b-macos.Rmd
index aa3fc5e5..7e04eeeb 100644
--- a/dev/2b-macos.Rmd
+++ b/dev/2b-macos.Rmd
@@ -93,13 +93,32 @@ next vignette `vignette("c-using-rix-to-build-project-specific-environments")` t
### Shared libraries issue
-When using environments built with Nix on macOS, you might get error messages
-refering to "shared libraries", which indicate that your user library of R
-packages is interfering with the project-specific Nix environment. In this case,
-you might want to set up a project-specific `.Rprofile` using `rix::rix_init()`.
-This function generates an `.Rprofile` file on the root of your project and
-ensures that the Nix environment only loads R packages from its own
-project-specific library. This should solve the issue.
+When using environments built with Nix on macOS, you might get crashes
+(segmentation faults) refering to "shared libraries". These indicate that your
+user library of R packages is interfering with the project-specific Nix
+environment. The system's user library that Nix packaged R by default includes
+appears in the search paths (check `libPaths()`). For macOS, the user library is
+at
+`/Library/Frameworks/R.framework/Versions/.-/Resources/library`;
+we have observed crashes with R packages that depend on system libraries, such
+as {data.table} or {dplyr}, and their (reverse) dependencies. Because user
+libraries from the system would also appear on the search path in R from
+`nixpkgs` for Linux, we think its a good idea to force isolation of R packages
+by making them behave in a runtime-pure manner. To make this happen, we
+recommend that you set up a project-specific `.Rprofile` using
+`rix::rix_init()`. This way, only packages declaratively defined in your
+`default.nix` and built to be part of the Nix store (one R package is one
+separate derivation listed in a unique Nix path) appear on the R library path.
+
+As an example, call `rix::rix()` like this.
+
+``` r
+# see ?rix_init for more details
+rix_init(
+ project_path = "./rix_darwin",
+ profile_action = "create_missing"
+)
+```
### RStudio and other development interfaces on macOS