diff --git a/docs/tutorials/building_r.md b/docs/tutorials/building_r.md index 7e6a59e1..695d5cc4 100644 --- a/docs/tutorials/building_r.md +++ b/docs/tutorials/building_r.md @@ -1,5 +1,5 @@ -**1) Environment variables** +#### 1. Environment variable - We have environment variables defining paths to directories for building R and storing the source code. @@ -10,7 +10,7 @@ ![alt text](../assets/rdev6.png) -**2) svn checkout** +#### 2. svn checkout - The svn checkout command lets us create a local copy of a specific tag/branch of a repository. @@ -26,7 +26,7 @@ ![alt text](../assets/rdev8.png) -**3) Download recommended packages for R** +#### 3. Download recommended packages for R To build R with the recommended packages, we need to run the `tools/rsync-recommended` script from the source directory to download the @@ -38,7 +38,7 @@ $TOP_SRCDIR/tools/rsync-recommended ![alt text](../assets/rdev9.png) -**4) Change to the build directory** +#### 4. Change to the build director - To keep the source directory clean, we change to a build directory to configure and build R. @@ -55,7 +55,7 @@ mkdir -p $BUILDDIR cd $BUILDDIR ``` -**5) Configure the build** +#### 5. Configure the build - After we change directory, we must run the configure script from the source directory. This step takes ~1 minute on the codespace. @@ -77,7 +77,7 @@ $TOP_SRCDIR/configure --with-valgrind-instrumentation=1 ![alt text](../assets/rdev7.png) -**6) Build R** +#### 6. Build Having configured R, we run `make` to build R. This take 5-10 minutes on the codespace. @@ -86,7 +86,7 @@ codespace. make ``` -**7) Check R** +#### 7. Check R Check that the build of R passes R's standard checks: @@ -94,11 +94,11 @@ Check that the build of R passes R's standard checks: make check ``` -This takes a couple of minutes in the codespace. The check will stop with a +This takes a couple of minutes in the codespace. The check will stop with an error message if any of the tests fail. If this happens, see [SVN Help](./svn_help.md) for how to revert to a version that passes check. -**8) Make R terminals use the built R** +#### 8) Make R terminals use the built R Run the `which_r` script to set which R to use for R terminals in VSCode. When prompted, enter the number corresponding to `r-devel` @@ -122,7 +122,7 @@ built![^1] selected version is saved in the VSCode settings, so will be saved when you stop and restart the codespace. -**9) Make contributions** +#### 9) Make contributions - After having built the current development version of R, we can now make changes to the source code and contribute to the project. diff --git a/docs/tutorials/multi_r_compilation.md b/docs/tutorials/multi_r_compilation.md index f6d71261..4f95073e 100644 --- a/docs/tutorials/multi_r_compilation.md +++ b/docs/tutorials/multi_r_compilation.md @@ -10,62 +10,66 @@ It can be helpful to work with multiple versions of R: You can build multiple R versions in the same Codespaces environment. -1. First choose a name for the R version. This will be used to identify the - version and to name the build/source directory. By default, we use the name - `r-devel` and the environment variables `BUILDDIR` and `TOP_SRCDIR` are set - to match. +#### 1.Choose a name - For illustration, we will use `r-devel-raw`, which you might use to name a - version of R that you never modify. +First choose a name for the R version. This will be used to identify the `r-devel` +and the environment variables `BUILDDIR` and `TOP_SRCDIR` are set to match. -2. You can set the `BUILDDIR` and `TOP_SRCDIR` environment variables to match - your chosen name using the `set_build_r` function: +For illustration, we will use `r-devel-raw`, which you might use to name a +version of R that you never modify. - - Open a terminal in the codespace. +#### 2. Set environment variables - - Run the `set_build_r` function with your chosen name as the argument, e.g. +You can set the `BUILDDIR` and `TOP_SRCDIR` environment variables to match your +chosen name using the `set_build_r` function: - ```bash - set_build_r r-devel-raw - ``` +- Open a terminal in the codespace. - The new values of the environment variables will be printed as - confirmation: +- Run the `set_build_r` function with your chosen name as the argument, e.g. - ```bash - BUILDDIR is now set to /workspaces/r-dev-env/build/r-devel-raw - TOP_SRCDIR is now set to /workspaces/r-dev-env/svn/r-devel-raw - ``` +```bash +set_build_r r-devel-raw +``` -3. If you have an unmodified build of R-devel using the default name of - `r-devel`, you can simply copy the sources and the build to the new - directories with `rsync`: +The new values of the environment variables will be printed as confirmation: - ```bash - rsync -a "$(dirname "$BUILDDIR")/r-devel/"* $BUILDDIR - rsync -a "$(dirname "$TOP_SRCDIR")/r-devel/"* $TOP_SRCDIR - ``` +```bash +BUILDDIR is now set to /workspaces/r-dev-env/build/r-devel-raw +TOP_SRCDIR is now set to /workspaces/r-dev-env/svn/r-devel-raw +``` - Otherwise you can follow the steps in the [Building R](./building_r.md) - tutorial to checkout the R sources and build R using the new source and - build directories. +#### 3. Synchronise builds -4. Once you have a build of R under the new build directory, you will see your - chosen name in the choices when running the `which_r` script to select the - version of R to run in new terminals, e.g. +If you have an unmodified build of R-devel using the default name of +directories with `rsync`: - ```bash - which_r - ``` +```bash +rsync -a "$(dirname "$BUILDDIR")/r-devel/"* $BUILDDIR +rsync -a "$(dirname "$TOP_SRCDIR")/r-devel/"* $TOP_SRCDIR +``` - ```bash - Which version of R should be used in new R terminals? - 1. R 4.4.0 (release version built into this container) - Additional R builds available: - 2. r-devel - 3. r-devel-raw +Otherwise you can follow the steps in the [Building R](./building_r.md) +tutorial to checkout the R sources and build R using the new source and +build directories. + +4. Check your build is available + +Once you have a build of R under the new build directory, you will see your +chosen name in the choices when running the `which_r` script to select the +version of R to run in new terminals, e.g. + +```bash +which_r +``` + +```bash +Which version of R should be used in new R terminals? +1. R 4.4.0 (release version built into this container) +Additional R builds available: +2. r-devel +3. r-devel-raw Enter the number corresponding to the selected version: - ``` +``` !!! Note diff --git a/docs/tutorials/patch_update.md b/docs/tutorials/patch_update.md index 1a75b5c5..ba44c72d 100644 --- a/docs/tutorials/patch_update.md +++ b/docs/tutorials/patch_update.md @@ -4,13 +4,13 @@ a change to R, e.g. a fix for a bug. To make a patch -1) Update your local copy of the source +#### 1. Update your local copy of the source If you have not recently updated your local copy of the R Subversion repository, follow the instructions in [Updating the Source Code](./update_source.md) to do this first. -2) Create a patch file +#### 2. Create a patch file Go to the source directory and use `svn diff` to create a patch. diff --git a/docs/tutorials/running_r.md b/docs/tutorials/running_r.md index 0d31d242..bfbd54d7 100644 --- a/docs/tutorials/running_r.md +++ b/docs/tutorials/running_r.md @@ -1,5 +1,7 @@ -1) Create a file in VS Code ending with a .R extension. You can create new files +#### 1. Create a new file + +Create a file in VS Code ending with a .R extension. You can create new files by clicking on the new file icon in VS Code Explorer, or use the `code` command in the terminal to create and open an R file @@ -7,14 +9,17 @@ in the terminal to create and open an R file code R/test.R ``` -![alt text](../assets/rdev4.png) +![Screen shot of VSCode running the Containerised R Development Environment.](../assets/rdev4.png) -2) You should see `R:(not attached)` in the Status Bar at the bottom of the +You should see `R:(not attached)` in the Status Bar at the bottom of the VSCode window. -![alt text](../assets/rdev11.png) +![Status bar of VSCode showing message that `R:(not attached)`.](../assets/rdev11.png) + +#### 2. Launch R -3) Click on the `R:(not attached)` link to launch an R terminal. You can then +Click on the `R:(not attached)` link to launch an R terminal. You can then send code from the `.R` file to the R terminal by pressing `cmd/ctrl + enter`. -![alt text](../assets/rdev12.png) ![alt text](../assets/rdev5.png) +![Screen shot of R session running in the Terminal tab of VSCode.](../assets/rdev12.png) +![VSCode screen shot showing R terminal and plot in a separate tab.](../assets/rdev5.png) diff --git a/docs/tutorials/update_source.md b/docs/tutorials/update_source.md index b052c093..ed375b08 100644 --- a/docs/tutorials/update_source.md +++ b/docs/tutorials/update_source.md @@ -3,11 +3,11 @@ multiple times a day. It's a good idea to update your local copy of the source code from time to time, especially before creating a patch. To do so, follow these steps: -#### 1) Close R terminal +#### 1. Close R terminal If you have an R terminal open, quit R or close the terminal. -#### 2) Go to the source directory +#### 2. Go to the source directory In a bash terminal, change to the source directory @@ -15,7 +15,7 @@ In a bash terminal, change to the source directory cd $TOP_SRCDIR ``` -#### 3) Review local changes +#### 3. Review local changes Use the Subversion diff command to review changes you have made to source code @@ -23,7 +23,7 @@ Use the Subversion diff command to review changes you have made to source code svn diff ``` -#### 4) Revert changes (optional) +#### 4. Revert changes (optional) If you no longer want to keep your local changes, you can revert them. @@ -45,7 +45,7 @@ Revert all local changes svn revert -R . ``` -#### 5) Rebuild and check with any local changes +#### 5. Rebuild and check with any local changes If you have no local changes remaining, skip to the next step. @@ -66,7 +66,7 @@ to continue cd $TOP_SRCDIR ``` -#### 6) Update using svn +#### 6. Update using svn Use the Subversion command `update` to update your local copy with the latest changes by the R Core Team. @@ -75,7 +75,7 @@ changes by the R Core Team. svn update ``` -#### 7) Rebuild and check with the updates +#### 7. Rebuild and check with the updates To rebuild R with the latest changes from the R Core Team and any local changes you have kept, go to the build directory to build and check R