Skip to content

Commit

Permalink
style(tutorials): Standardising sub-headings and layout
Browse files Browse the repository at this point in the history 
As part of r-devel#191 the style of sub-headings for instructions in the `docs/tutorials/` section.

+ Level 2 markdown headings have been used, where numbering is required these have been included as the number followed
  by a period.
+ Bullet points have been converted to paragraphs.
+ alt text added to images.
+ titles added to code blocks.
  • Loading branch information
@ns-rse
ns-rse committed Oct 18, 2024
1 parent e7fe4e4 commit 31430f9
Show file tree
Hide file tree
Showing 7 changed files with 189 additions and 186 deletions.
104 changes: 50 additions & 54 deletions docs/tutorials/building_r.md
View file
Original file line number Diff line number Diff line change
@@ -1,113 +1,110 @@
<!-- markdownlint-disable MD036 -->
**1) Environment variables**

- We have environment variables defining paths to directories for building R and
storing the source code.
This tutorial takes you through the process of building in the workspace container.

## 1. Environment variable

We have environment variables defining paths to directories for building R and
storing the source code.

- `BUILDDIR` defines the build directory: `/workspaces/r-dev-env/build/r-devel`.
- `TOP_SRCDIR` defines the source directory: `/workspaces/r-dev-env/svn/r-devel`
- The environment variables are set in the codespace image and are available
when the codespace starts.
- `PATCHDIR` defines the patch directory: `/workspaces/r-dev-env-/patches`

![alt text](../assets/rdev6.png)
The environment variables are set in the codespace image and are available
when the codespace starts.

**2) svn checkout**
![Startup message of Containerised R Development Environment showing the environment variables](../assets/rdev6.png)

- The svn checkout command lets us create a local copy of a specific tag/branch
of a repository.
- We can check out the latest version of the trunk (the main branch) of the R
sources to $TOP_SRCDIR as follows:
## 2. svn checkout

```bash
svn checkout https://svn.r-project.org/R/trunk/ $TOP_SRCDIR
```
R uses [Apache Subversion](https://subversion.apache.org/), an older version
control system than Git, to version control the code.

The `svn checkout` command lets us create a local copy of a specific tag/branch
of a repository. We can check out the latest version of the trunk (the `main`
branch) of the R sources to `$TOP_SRCDIR` as follows:

```bash title="Checking out the main branch to $TOP_SRCDIR"
svn checkout https://svn.r-project.org/R/trunk/ $TOP_SRCDIR
```

- Output : We get file structure something like this after checking out R source
code from R svn repository.
We get file structure something like this after checking out R source code from
R svn repository.

![alt text](../assets/rdev8.png)
![Directory structure of the `main` branch after checkout](../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
source code for these packages:

```bash
```bash title="Synchronising the recommended packages"
$TOP_SRCDIR/tools/rsync-recommended
```

![alt text](../assets/rdev9.png)
![Synchronising the recommended packages](../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.
To keep the source directory clean, we change to a build directory to configure
and build R.

- First create the directory specified by the BUILDDIR environment variable.
Create and change to the directory specified by the BUILDDIR environment variable.

```bash
```bash title="Creating the $BUILDDIR and moving to it"
mkdir -p $BUILDDIR
```

- Then we can change directory from root to the build directory.

```bash
cd $BUILDDIR
```

**5) Configure the build**
## 5. Configure the build

- After we change directory, we must run the configure script from the source
After we change directory, we must run the configure script from the source
directory. This step takes ~1 minute on the codespace.

```bash
```bash title="Configuring the build"
$TOP_SRCDIR/configure --with-valgrind-instrumentation=1
```

!!! Note
<!-- markdownlint-disable MD046 -->
The `--with-valgrind-instrumentation` option is set to 1 for effective use of valgrind. See the [Using valgrind](https://cran.r-project.org/doc/manuals/R-exts.html#Using-valgrind) section of the R-admin manual for more information.
<!-- markdownlint-enable MD046 -->

- The configure cmd prepares for building R, creating files and folders inside
the BUILDDIR directory.
- Output : We get file structure something like this after using configure
command.
The configure command prepares for building R, creating files and folders inside
the `$BUILDDIR` directory.

![alt text](../assets/rdev7.png)
![File structure after having configure the build](../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.

```bash
```bash title="Building R using make"
make
```

**7) Check R**
## 7. Check R

Check that the build of R passes R's standard checks:

```bash
```bash title="Running the test suite using make check"
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`

```bash
```bash title="Checking which version of R is being used."
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:
Expand All @@ -122,9 +119,8 @@ 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.
- Follow the [R Contribution Workflow](./contribution_workflow.md) tutorial to
learn how to do this.
After having built the current development version of R, we can now make
changes to the source code and contribute to the project. The [R Contribution
Workflow](./contribution_workflow.md) tutorial goes through this process.
95 changes: 55 additions & 40 deletions docs/tutorials/contribution_workflow.md
View file
Original file line number Diff line number Diff line change
@@ -1,80 +1,95 @@
#### 1. Example Contribution Workflow using the R Dev Container
This tutorial takes you through the various steps of making contributions to the
R code base

- To start working in R we will click on `R:(not attach)` which is in the bottom
right of the VSCode window. This will open an R terminal for us.
## 1. Attach to the R workspace

![alt text](../assets/rdev11.png)
To start working in R we need to first attach to a workspace session of R. To do
this click on `R:(not attach)` at the bottom right of the VSCode window. This
will open an R terminal for us.

![alt text](../assets/rdev12.png)
Figure: VSCode before attaching to an R Workspace session

- We can now run R commands. We will use the `utils::askYesNo()` function as an
example
![VSCode before attaching to an R Workspace session](../assets/rdev11.png)

![alt text](../assets/rdev19.png)
![VSCode after attaching to an R Workspace session](../assets/rdev12.png)

```R
> askYesNo("Is this a good example?")
Is this a good example? (Yes/no/cancel) Yes
[1] TRUE
We can now run R commands. We will use the `utils::askYesNo()` function as an
example

```R title="Running the existing askYesNo() function."
> askYesNo("Is this a good example?")
Is this a good example? (Yes/no/cancel) Yes
[1] TRUE
```

#### 2. Editing Source Code
## 2. Editing Source Code

Edit the source code of `utils::askYesNo()` to change the default options. The
source code can be found in `$TOP_SRCDIR/src/library/utils/R/askYesNo.R` and
we want to edit line 20 where the `prompts` option is set.

- Edit the source code of `utils::askYesNo()` to change the default options. The
source code can be found in `$TOP_SRCDIR/src/library/utils/R/askYesNo.R`.
- You can redirect to that file using
You can redirect to that file using...

```bash
code $TOP_SRCDIR/src/library/utils/R/askYesNo.R
```

**> Before edit:** ![alt text](../assets/rdev20.png)
**Before edit:**

```R title="askYesNo.R" linenums="20"
prompts = getOption("askYesNo", gettext(c("Yes", "No", "Cancel"))),
![askYesNo.R before editing](../assets/rdev20.png)

```R title="askYesNo.R before editing" linenums="20"
> prompts = getOption("askYesNo", gettext(c("Yes", "No", "Cancel"))),
```

**> With edit (for example - change to whatever you like!):**
**With edit (for example - change to whatever you like!):**

![alt text](../assets/rdev21.png)
![askYesNo.R after editing](../assets/rdev21.png)

```R title="askYesNo.R" linenums="20"
prompts = getOption("askYesNo", gettext(c("Oh yeah!", "Don't think so", "Cancel"))),
```R title="askYesNo.R after editing" linenums="20"
> prompts = getOption("askYesNo", gettext(c("Oh yeah!", "Don't think so", "Cancel"))),
```

#### 3. Rebuild R
## 3. Rebuild R

We are now ready to re-build R with our changes. Since we have only modified the
utils package, rebuilding R will only re-build the utils package.

- We can re-build R with our changes. Since we have only modified the utils
package, rebuilding R will only re-build the utils package.
- First we need to be inside $BUILDDIR.
- Quit R with `q()` or by closing the R terminal.
- In the bash terminal, change to the build directory:
Quit R with `q()` or by closing the R terminal and in the bash terminal change
directory th the build directory. This is stored in the environment variable
`$BUILDDIR` so we can...

```bash
cd $BUILDDIR
```

- Now run the `make` command to rebuild R with the changes you made in
step 2. This will be much faster than the full build!
Now run the `make` command to rebuild R with the changes you made in step 2.
This will be much faster than the full build because only the changes we made to
the utils package are rebuild.

```bash
make
```

![alt text](../assets/rdev22.png)
![Output rebuilding R using make](../assets/rdev22.png)

It's a good idea to check the changes you have made have not broken anything.
R comes with a test suite and you can run that on your local changes by
running `make check` to run R's test suite against your local changes. You may
skip this step while you are iterating on a bug fix or other development, until
you are ready to [create a patch](./patch_update.md) but remember to run the
tests before creating a patch.

- Optionally run `make check` to run R's test suite with your local changes. You
may skip this step while you are iterating on a bug fix or other development,
until you are ready to [create a patch](./patch_update.md).
To use the re-built R, simply open a new R terminal.

- To use the re-built R, simply open a new R terminal.
## 4. Cross check and Re-running Code

#### 4. Cross check and Re-running Code
You can check the edit has worked as expected by in the re-built R by re-running
the example code:

- Check the edit has worked as expected by re-running the example code: ![alt
text](../assets/rdev23.png)
![Example showing the modified output of askYesNo()](../assets/rdev23.png)

```R
```R title="Example showing the modified output of askYesNo()"
> askYesNo("Is this a good example?")
Is this a good example? (Oh yeah!/don't think so/cancel) Oh yeah!
[1] TRUE
Expand Down
Loading

0 comments on commit 31430f9

Please sign in to comment.