Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Documentation feedback #109

Closed
wants to merge 7 commits into from
Closed

Documentation feedback #109

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
6c23331
some suggestions
philipp-baumann Jan 25, 2024
cec8b89
feedback suggestions
philipp-baumann Jan 25, 2024
2e1572a
add links
philipp-baumann Jan 25, 2024
99b7f0f
according review
philipp-baumann Jan 27, 2024
49b3ed2
install it first
philipp-baumann Jan 27, 2024
258529d
detail PATH issue
philipp-baumann Jan 27, 2024
0376f7f
edit
philipp-baumann Jan 27, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
81 changes: 48 additions & 33 deletions README.Rmd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 how to build software
philipp-baumann marked this conversation as resolved.
Show resolved Hide resolved
packages and manage configurations in declarative way. This makes sure that
philipp-baumann marked this conversation as resolved.
Show resolved Hide resolved
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. Using
{rix}, you can define and build isolated R environments through Nix package
philipp-baumann marked this conversation as resolved.
Show resolved Hide resolved
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 their builds extremely well in deterministic manner. It is also
philipp-baumann marked this conversation as resolved.
Show resolved Hide resolved
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
Expand All @@ -68,9 +76,10 @@ 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 function (and objects in the call stack) in a different
philipp-baumann marked this conversation as resolved.
Show resolved Hide resolved
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
Expand Down Expand Up @@ -98,6 +107,9 @@ the Nix package manager must be installed.

*If you are not familiar with Nix or `{rix}` skip to the next section.*

<details>

<summary>Click to exand</summary>
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
Expand Down Expand Up @@ -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.
</details>

## 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")`
b-rodrigues marked this conversation as resolved.
Show resolved Hide resolved
([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.
Expand Down
94 changes: 55 additions & 39 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 how to build software packages and manage configurations in
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. Using {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 their builds extremely well in 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
Expand All @@ -70,9 +78,10 @@ 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 function (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
Expand Down Expand Up @@ -102,6 +111,11 @@ installed.

*If you are not familiar with Nix or `{rix}` skip to the next section.*

<details>
<summary>
Click to exand
</summary>

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
Expand Down Expand Up @@ -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.
</details>

## 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

Expand Down
Loading