├── VERSION ├── docs ├── assets │ ├── image.png │ ├── rdev1.png │ ├── rdev10.png │ ├── rdev11.png │ ├── rdev12.png │ ├── rdev13.png │ ├── rdev14.png │ ├── rdev15.png │ ├── rdev16.png │ ├── rdev17.png │ ├── rdev18.png │ ├── rdev19.png │ ├── rdev20.png │ ├── rdev21.png │ ├── rdev22.png │ ├── rdev23.png │ ├── rdev24.png │ ├── rdev25.png │ ├── rdev3.png │ ├── rdev4.png │ ├── rdev5.png │ ├── rdev6.png │ ├── rdev7.png │ ├── rdev8.png │ ├── rdev9.png │ ├── gitpod1.png │ ├── gitpod2.png │ ├── gitpod3.png │ ├── gitpod4.png │ ├── gitpod5.png │ ├── gitpod6.png │ ├── live-share.png │ ├── live-share2.png │ ├── live-share3.png │ ├── live-share4.png │ ├── live-share5.png │ ├── live-share6.png │ ├── manage_codespace.png │ └── manage_workspace.png ├── contributor_guide │ ├── contributing_to_codebase.md │ └── contributing_to_docs.md ├── resources.md ├── container_setup │ ├── gitpod_workspace │ │ ├── live_share.md │ │ ├── workspacestart.md │ │ └── workspacestop_and_restart.md │ ├── index.md │ ├── github_codespace │ │ ├── creating_codespace.md │ │ ├── codespacestartstop.md │ │ └── live_share.md │ └── local_setup │ │ └── localsetup.md ├── tutorials │ ├── running_r.md │ ├── patch_update.md │ ├── svn_help.md │ ├── update_source.md │ ├── contribution_workflow.md │ ├── multi_r_compilation.md │ └── building_r.md ├── index.md └── troubleshoot.md ├── .gitignore ├── .gitpod.yml ├── CITATION.cff ├── scripts ├── set_build_r.sh ├── welcome_msg.sh ├── localscript.sh ├── optimize.R └── which_r.sh ├── .markdownlint-cli2.yaml ├── .github ├── ISSUE_TEMPLATE │ └── release-new-version-of-devcontainer.md ├── workflows │ ├── optimize-docs-images.yml │ ├── schedule-docker-build.yml │ ├── build-and-publish-image.yml │ ├── build-gitpod-image.yml │ └── build-mkdocs-website.yml └── README.md ├── .Rprofile ├── .pre-commit-config.yaml ├── LICENSE ├── .devcontainer └── devcontainer.json ├── Dockerfile ├── .gitpod.Dockerfile ├── reinstall-cmake.sh ├── INDEX.md ├── mkdocs.yml ├── NEWS.md ├── CODE_OF_CONDUCT.md └── CONTRIBUTING.md /VERSION: -------------------------------------------------------------------------------- 1 | 0.3.0 2 | -------------------------------------------------------------------------------- /docs/assets/image.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/r-dev-env/HEAD/docs/assets/image.png -------------------------------------------------------------------------------- /docs/assets/rdev1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/r-dev-env/HEAD/docs/assets/rdev1.png -------------------------------------------------------------------------------- /docs/assets/rdev10.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/r-dev-env/HEAD/docs/assets/rdev10.png -------------------------------------------------------------------------------- /docs/assets/rdev11.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/r-dev-env/HEAD/docs/assets/rdev11.png -------------------------------------------------------------------------------- /docs/assets/rdev12.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/r-dev-env/HEAD/docs/assets/rdev12.png -------------------------------------------------------------------------------- /docs/assets/rdev13.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/r-dev-env/HEAD/docs/assets/rdev13.png -------------------------------------------------------------------------------- /docs/assets/rdev14.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/r-dev-env/HEAD/docs/assets/rdev14.png -------------------------------------------------------------------------------- /docs/assets/rdev15.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/r-dev-env/HEAD/docs/assets/rdev15.png -------------------------------------------------------------------------------- /docs/assets/rdev16.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/r-dev-env/HEAD/docs/assets/rdev16.png -------------------------------------------------------------------------------- /docs/assets/rdev17.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/r-dev-env/HEAD/docs/assets/rdev17.png -------------------------------------------------------------------------------- /docs/assets/rdev18.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/r-dev-env/HEAD/docs/assets/rdev18.png -------------------------------------------------------------------------------- /docs/assets/rdev19.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/r-dev-env/HEAD/docs/assets/rdev19.png -------------------------------------------------------------------------------- /docs/assets/rdev20.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/r-dev-env/HEAD/docs/assets/rdev20.png -------------------------------------------------------------------------------- /docs/assets/rdev21.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/r-dev-env/HEAD/docs/assets/rdev21.png -------------------------------------------------------------------------------- /docs/assets/rdev22.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/r-dev-env/HEAD/docs/assets/rdev22.png -------------------------------------------------------------------------------- /docs/assets/rdev23.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/r-dev-env/HEAD/docs/assets/rdev23.png -------------------------------------------------------------------------------- /docs/assets/rdev24.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/r-dev-env/HEAD/docs/assets/rdev24.png -------------------------------------------------------------------------------- /docs/assets/rdev25.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/r-dev-env/HEAD/docs/assets/rdev25.png -------------------------------------------------------------------------------- /docs/assets/rdev3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/r-dev-env/HEAD/docs/assets/rdev3.png -------------------------------------------------------------------------------- /docs/assets/rdev4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/r-dev-env/HEAD/docs/assets/rdev4.png -------------------------------------------------------------------------------- /docs/assets/rdev5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/r-dev-env/HEAD/docs/assets/rdev5.png -------------------------------------------------------------------------------- /docs/assets/rdev6.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/r-dev-env/HEAD/docs/assets/rdev6.png -------------------------------------------------------------------------------- /docs/assets/rdev7.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/r-dev-env/HEAD/docs/assets/rdev7.png -------------------------------------------------------------------------------- /docs/assets/rdev8.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/r-dev-env/HEAD/docs/assets/rdev8.png -------------------------------------------------------------------------------- /docs/assets/rdev9.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/r-dev-env/HEAD/docs/assets/rdev9.png -------------------------------------------------------------------------------- /docs/assets/gitpod1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/r-dev-env/HEAD/docs/assets/gitpod1.png -------------------------------------------------------------------------------- /docs/assets/gitpod2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/r-dev-env/HEAD/docs/assets/gitpod2.png -------------------------------------------------------------------------------- /docs/assets/gitpod3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/r-dev-env/HEAD/docs/assets/gitpod3.png -------------------------------------------------------------------------------- /docs/assets/gitpod4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/r-dev-env/HEAD/docs/assets/gitpod4.png -------------------------------------------------------------------------------- /docs/assets/gitpod5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/r-dev-env/HEAD/docs/assets/gitpod5.png -------------------------------------------------------------------------------- /docs/assets/gitpod6.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/r-dev-env/HEAD/docs/assets/gitpod6.png -------------------------------------------------------------------------------- /docs/assets/live-share.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/r-dev-env/HEAD/docs/assets/live-share.png -------------------------------------------------------------------------------- /docs/assets/live-share2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/r-dev-env/HEAD/docs/assets/live-share2.png -------------------------------------------------------------------------------- /docs/assets/live-share3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/r-dev-env/HEAD/docs/assets/live-share3.png -------------------------------------------------------------------------------- /docs/assets/live-share4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/r-dev-env/HEAD/docs/assets/live-share4.png -------------------------------------------------------------------------------- /docs/assets/live-share5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/r-dev-env/HEAD/docs/assets/live-share5.png -------------------------------------------------------------------------------- /docs/assets/live-share6.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/r-dev-env/HEAD/docs/assets/live-share6.png -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | R-4.1.3/ 2 | R-4.1.3.tar.gz 3 | R-devel/ 4 | R-devel.tar.gz 5 | /venv 6 | .cache/ 7 | .Rproj.user 8 | -------------------------------------------------------------------------------- /docs/assets/manage_codespace.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/r-dev-env/HEAD/docs/assets/manage_codespace.png -------------------------------------------------------------------------------- /docs/assets/manage_workspace.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-devel/r-dev-env/HEAD/docs/assets/manage_workspace.png -------------------------------------------------------------------------------- /docs/contributor_guide/contributing_to_codebase.md: -------------------------------------------------------------------------------- 1 | ##### R-Dev-Env Docker Image BUild Workflow 2 | 3 | ![alt text](../assets/image.png) 4 | 5 | 1. 6 | -------------------------------------------------------------------------------- /.gitpod.yml: -------------------------------------------------------------------------------- 1 | image: ghcr.io/r-devel/r-dev-env:gitpod.devel 2 | 3 | tasks: 4 | - name: Initial Setup for R-dev-env Gitpod Workspace 5 | before: | 6 | bash /workspace/r-dev-env/scripts/localscript.sh 7 | source ~/.bashrc 8 | 9 | 10 | vscode: 11 | extensions: 12 | - REditorSupport.r 13 | - johnstoncode.svn-scm 14 | -------------------------------------------------------------------------------- /CITATION.cff: -------------------------------------------------------------------------------- 1 | cff-version: 1.2.0 2 | message: "If you use this software, please cite it as below." 3 | authors: 4 | - family-names: Shirdhankar 5 | given-names: Atharva 6 | - family-names: Turner 7 | given-names: Heather 8 | - family-names: Tripp 9 | given-names: James 10 | - family-name: Emsley 11 | given-names: Iain 12 | 13 | title: "R Development Container" 14 | version: 0.3.0 15 | doi: 16 | date-released: 04-09-2024 17 | -------------------------------------------------------------------------------- /docs/resources.md: -------------------------------------------------------------------------------- 1 | # Useful Links 2 | 3 | * [R in Visual Studio code](https://code.visualstudio.com/docs/languages/r) 4 | * [VSCode R Wiki](https://github.com/REditorSupport/vscode-R/wiki) 5 | * [Getting started with Dev Containers](https://code.visualstudio.com/docs/devcontainers/tutorial) 6 | * [Install Docker Desktop](https://www.docker.com/products/docker-desktop/) 7 | * [Installing Docker on Linux](https://docs.docker.com/desktop/install/linux-install/) 8 | -------------------------------------------------------------------------------- /scripts/set_build_r.sh: -------------------------------------------------------------------------------- 1 | set_build_r() { 2 | if [ -z "$1" ]; then 3 | echo "Usage: set_build_r " 4 | echo "BUILDDIR is currently set to $BUILDDIR" 5 | echo "TOP_SRCDIR is currently set to $TOP_SRCDIR" 6 | else 7 | NAME=$1 8 | export BUILDDIR="$WORK_DIR/build/$NAME" 9 | export TOP_SRCDIR="$WORK_DIR/svn/$NAME" 10 | echo "BUILDDIR is now set to $BUILDDIR" 11 | echo "TOP_SRCDIR is now set to $TOP_SRCDIR" 12 | fi 13 | } 14 | -------------------------------------------------------------------------------- /docs/container_setup/gitpod_workspace/live_share.md: -------------------------------------------------------------------------------- 1 | ## Gitpod Live Share Alternative 2 | 3 | 1. Gitpod live share can be started from dashboard itself by clicking on `Share` 4 | option on dashboard. 5 | 6 | ![liveshare](../../assets/gitpod5.png) 7 | 8 | 2. After that whenever you open Gitpod Workspace the live share is enabled and 9 | ready to share workspace with others. 10 | 11 | ![liveshare](../../assets/gitpod6.png) 12 | 13 | !!! Note: The live share will be enabled even if you close the workspace. 14 | -------------------------------------------------------------------------------- /.markdownlint-cli2.yaml: -------------------------------------------------------------------------------- 1 | config: 2 | 3 | # MD013 - line-length 4 | line_length: 5 | line_length: 80 6 | code_blocks: false 7 | tables: false 8 | html: 9 | allowed_elements: 10 | - div 11 | - figure 12 | # MD029 - ol-prefix disabled as ordered lists are interspersed wit code in multiple places 13 | ol-prefix: false 14 | # MD041 - first-line-heading disable due to splitting of sections across multiple files 15 | first-line-h1: false 16 | 17 | globs: 18 | 19 | - "docs/**/*.md" 20 | - "*.md" 21 | 22 | 23 | fix: true 24 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/release-new-version-of-devcontainer.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Release new version of devcontainer 3 | about: Steps to take before release 4 | title: Release version [number] 5 | labels: '' 6 | assignees: '' 7 | 8 | --- 9 | 10 | Checklist for release: 11 | 12 | - [ ] Update NEWS file 13 | - [ ] Update CITATION.cff 14 | - [ ] Update VERSION 15 | - [ ] In devcontainer.json, update `"image": "ghcr.io/r-devel/r-dev-env:devel"` 16 | to `"image": "ghcr.io/r-devel/r-dev-env:main"`,, 17 | - [ ] Make PR to main branch - needs approving review! 18 | - [ ] Make sure docker container is rebuilt 19 | - [ ] Test container and fix any issues 20 | - [ ] Make GitHub release 21 | -------------------------------------------------------------------------------- /.Rprofile: -------------------------------------------------------------------------------- 1 | # Set site library for full use of VSCode-R extension. 2 | # This is where packages required by VSCode-R extension are installed, specifically 3 | # - jsonlite and rlang for R Session Watcher (needed to open HTML help pages) 4 | # - languageserver for code completion 5 | # - httpgd for http graphics device 6 | # These are built and installed for the default R version when container is built. 7 | 8 | .Library.site <- "/usr/local/lib/R/site-library" 9 | # .libPaths() already includes site library for default R version. 10 | .libPaths(c(.libPaths(), .Library.site)) 11 | 12 | # For PNG graphics uncomment following lines 13 | # options(vsc.use_httpgd = FALSE, 14 | # vsc.dev.args = list(width = 800, height = 600)) 15 | -------------------------------------------------------------------------------- /docs/tutorials/running_r.md: -------------------------------------------------------------------------------- 1 | 2 | 1) Create a file in VS Code ending with a .R extension. You can create new files 3 | by clicking on the new file icon in VS Code Explorer, or use the `code` command 4 | in the terminal to create and open an R file 5 | 6 | ```bash 7 | code R/test.R 8 | ``` 9 | 10 | ![alt text](../assets/rdev4.png) 11 | 12 | 2) You should see `R:(not attached)` in the Status Bar at the bottom of the 13 | VSCode window. 14 | 15 | ![alt text](../assets/rdev11.png) 16 | 17 | 3) Click on the `R:(not attached)` link to launch an R terminal. You can then 18 | send code from the `.R` file to the R terminal by pressing `cmd/ctrl + enter`. 19 | 20 | ![alt text](../assets/rdev12.png) ![alt text](../assets/rdev5.png) 21 | -------------------------------------------------------------------------------- /.pre-commit-config.yaml: -------------------------------------------------------------------------------- 1 | # See https://pre-commit.com for more information 2 | # See https://pre-commit.com/hooks.html for more hooks 3 | repos: 4 | - repo: https://github.com/pre-commit/pre-commit-hooks 5 | rev: v6.0.0 6 | hooks: 7 | - id: trailing-whitespace 8 | - id: end-of-file-fixer 9 | - id: check-yaml 10 | - id: check-added-large-files 11 | 12 | - repo: https://github.com/DavidAnson/markdownlint-cli2 13 | rev: v0.20.0 14 | hooks: 15 | - id: markdownlint-cli2 16 | args: [] 17 | 18 | ci: 19 | autofix_prs: true 20 | autofix_commit_msg: '[pre-commit.ci] Fixing issues with pre-commit' 21 | autoupdate_schedule: weekly 22 | autoupdate_commit_msg: '[pre-commit.ci] pre-commit-autoupdate' 23 | skip: [] # Optionally list ids of hooks to skip on CI 24 | -------------------------------------------------------------------------------- /docs/container_setup/index.md: -------------------------------------------------------------------------------- 1 | # Container Setup 2 | 3 | You can run the R Dev Container in one of the ways: 4 | 5 | - **GitHub Codespaces**: Offers 60 hours per month of free usage for 2-core 6 | set-ups and 15GB of free storage. The R Dev Container codespace is set up to 7 | use 4 cores by default, which gives users 30 hours per month of free 8 | usage. Check out the [Codespace pricing 9 | docs](https://docs.github.com/en/billing/managing-billing-for-github-codespaces/about-billing-for-github-codespaces#about-github-codespaces-pricing) 10 | for more information. 11 | 12 | - **Gitpod Workspaces**: Offers 50 hours per month of free usage. Check out the 13 | [Gitpod pricing docs](https://www.gitpod.io/pricing) for more information. 14 | 15 | - **Local Setup**: Currently recommended for Linux users only. 16 | 17 | Explore the sub-sections for detailed instructions on setting up and using the 18 | container for each option. 19 | -------------------------------------------------------------------------------- /docs/index.md: -------------------------------------------------------------------------------- 1 | # R Dev Container 2 | 3 | ## Project Background 4 | 5 | The standard development process used by members of the R Core Team involves an 6 | iterative process of making changes to the source code, re-building R and 7 | exploring/testing the changes made. This process presents a big hurdle for new 8 | contributors to R, as setting up their system to build R can be non-trivial, 9 | requiring a lot of trouble-shooting, especially on Windows and macOS. On Linux 10 | and macOS, it is not straight-forward to work with different versions of R 11 | side-by-side and care needs to be taken not to corrupt or over-write the user's 12 | existing version of R/R packages. 13 | 14 | For these reasons, we propose to create containerized development environments 15 | for R. Our focus will be on creating a complete environment, including an IDE, 16 | that will provide a familiar space for R developers to work on contributions to 17 | base R. 18 | 19 | ## Contributors 20 | 21 | GSoC contributor: Atharva Shirdhankar 22 | 23 | Mentors: Heather Turner, James Tripp, Iain Emsley 24 | -------------------------------------------------------------------------------- /scripts/welcome_msg.sh: -------------------------------------------------------------------------------- 1 | # This script is run everytime workspace is started (when bash terminal started) 2 | #!/bin/bash 3 | 4 | # define helper environment variables based on workspace root ($PWD at start) 5 | export WORK_DIR=$PWD 6 | export BUILDDIR="$WORK_DIR/build/r-devel" 7 | export TOP_SRCDIR="$WORK_DIR/svn/r-devel" 8 | export PATCHDIR="$WORK_DIR/patches" 9 | 10 | # clear the screen before displaying welcome message 11 | clear 12 | 13 | # welcome message to add to bashrc 14 | echo -e " 15 | Welcome to the R Dev Container v$CONTAINER_VERSION 16 | 17 | Here you can modify, compile and use R as described in 18 | the r development guide: 19 | https://contributor.r-project.org/rdevguide/GetStart.html#building-r 20 | 21 | 22 | To help you, we have already set the following environment variables: 23 | 24 | BUILDDIR = \"$BUILDDIR\" 25 | TOP_SRCDIR = \"$TOP_SRCDIR\" 26 | PATCHDIR = \"$PATCHDIR\" 27 | 28 | Have fun \U0001F601 29 | " 30 | 31 | # open INDEX.md if INIT file exists 32 | if [ -f "INIT" ]; then 33 | sleep 2 34 | code INDEX.md 35 | rm INIT 36 | fi 37 | -------------------------------------------------------------------------------- /scripts/localscript.sh: -------------------------------------------------------------------------------- 1 | # This script is run after the workspace is created 2 | #!/bin/bash 3 | 4 | local_script(){ 5 | 6 | # Workspace root is $PWD at the start 7 | WORK_DIR=$PWD 8 | VSCODE_DIR="$WORK_DIR/.vscode" 9 | DEVCONTAINER_JSON="$WORK_DIR/.devcontainer/devcontainer.json" 10 | 11 | # Create patch directory in workspace root ($PWD at start) 12 | PATCHDIR="$WORK_DIR/patches" 13 | mkdir -p $PATCHDIR 14 | mkdir -p $VSCODE_DIR 15 | 16 | # Copy the which_r and set_build_r function definitions to .bashrc 17 | cat $WORK_DIR/scripts/which_r.sh >> ~/.bashrc 18 | cat $WORK_DIR/scripts/set_build_r.sh >> ~/.bashrc 19 | 20 | # Copy over the welcome message script to be run when bash terminal starts 21 | cat $WORK_DIR/scripts/welcome_msg.sh >> ~/.bashrc 22 | 23 | #bash ~/.bashrc 24 | 25 | # Remove git directory if it exists 26 | rm -rf .git 27 | 28 | # copying vscode extension settings from devcontainer json to vscode settings json using jq 29 | if [ -f "$DEVCONTAINER_JSON" ]; then 30 | jq '.customizations.vscode.settings' "$DEVCONTAINER_JSON" > "$VSCODE_DIR/settings.json" 31 | fi 32 | 33 | 34 | } 35 | 36 | 37 | # Run the main function 38 | local_script 39 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2023 R Development Container authors 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /.devcontainer/devcontainer.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "R-Dev-Env", 3 | "image": "ghcr.io/r-devel/r-dev-env:main", 4 | "hostRequirements": { 5 | "cpus": 4 6 | }, 7 | "customizations": { 8 | "vscode": { 9 | "settings": { 10 | "r.lsp.diagnostics": false, 11 | "r.plot.useHttpgd": true, 12 | "r.rpath.linux": "/usr/bin/R", 13 | "r.rterm.linux": "/usr/bin/R", 14 | "terminal.integrated.sendKeybindingsToShell": true, 15 | "svn.multipleFolders.enabled": true, 16 | "workbench.editorAssociations": { 17 | "*.md": "vscode.markdown.preview.editor" 18 | }, 19 | "workbench.welcomePage.walkthroughs.openOnInstall": false 20 | }, 21 | "extensions": [ 22 | "REditorSupport.r", 23 | "mads-hartmann.bash-ide-vscode", 24 | "johnstoncode.svn-scm", 25 | "ms-vscode.cpptools", 26 | "MS-vsliveshare.vsliveshare" 27 | ] 28 | } 29 | }, 30 | "postCreateCommand": "chown -R vscode:vscode /workspaces/r-dev-env && sh /workspaces/r-dev-env/scripts/localscript.sh" 31 | } 32 | -------------------------------------------------------------------------------- /scripts/optimize.R: -------------------------------------------------------------------------------- 1 | library(magick) 2 | library(tools) 3 | 4 | # Define the directory containing images 5 | image_dir <- file.path("docs", "assets") 6 | 7 | # Get all photos in the directory with specified extensions 8 | files <- dir(image_dir, pattern = "\\.(jpeg|jpg|png)$", ignore.case = TRUE) 9 | 10 | # Process each file 11 | for (i in seq_along(files)) { 12 | # Read the image 13 | file_path <- file.path(image_dir, files[i]) 14 | img <- tryCatch({ 15 | image_read(file_path) 16 | }, error = function(e) { 17 | message("Error reading image: ", file_path) 18 | next 19 | }) 20 | 21 | # Resize the image to 1000 px width using Lanczos filter for resampling 22 | img <- image_resize(img, geometry_size_pixels(width = 1000), filter = "Lanczos") 23 | 24 | # Define the output path, changing the extension to .png 25 | output_path <- file_path_sans_ext(file_path) 26 | output_path <- paste0(output_path, ".png") 27 | 28 | # Write the optimized image (overwrite original image) as PNG with compression 29 | tryCatch({ 30 | image_write(img, output_path, format = "png", compression = "Zip") 31 | }, error = function(e) { 32 | message("Error writing image: ", output_path) 33 | }) 34 | } 35 | -------------------------------------------------------------------------------- /docs/troubleshoot.md: -------------------------------------------------------------------------------- 1 | While working with an R Dev Container, you may encounter some known errors. Here 2 | are a few common ones: 3 | 4 | 1. #### Error: Rsync Connection Limit Reached, Preventing New Connections 5 | 6 | **Description :** When attempting to use rsync, you may encounter the 7 | following error message: 8 | 9 | ```bash 10 | $TOP_SRCDIR/tools/rsync-recommended @ERROR: max connections (59) reached -- try again later rsync error: error starting client-server protocol (code 5) at main.c(1863) [Receiver=3.2.7] *** rsync failed to update Recommended files *** 11 | ``` 12 | 13 | **Cause :** This error occurs because the rsync server has reached its 14 | maximum allowed number of simultaneous connections, which is set to 59. As a 15 | result, new connection attempts are rejected until some of the existing 16 | connections are closed. 17 | 18 | **Solutions :** 19 | 1. Retry After Some Time : Wait for a few minutes and try running the rsync 20 | command again. The number of active connections may decrease, allowing 21 | you to connect. 22 | 2. Restart Codespace : Sometimes, simply restarting your Codespace can 23 | resolve temporary connection issues. Try restarting your Codespace and 24 | then attempt the rsync command again. 25 | -------------------------------------------------------------------------------- /docs/tutorials/patch_update.md: -------------------------------------------------------------------------------- 1 | A patch file captures the local changes (additions and deletions) to the source 2 | code. It can be shared on [R's Bugzilla](https://bugs.r-project.org/) to propose 3 | a change to R, e.g. a fix for a bug. 4 | 5 | To make a patch 6 | 7 | 1) Update your local copy of the source 8 | 9 | If you have not recently updated your local copy of the R Subversion repository, 10 | follow the instructions in [Updating the Source Code](./update_source.md) to do 11 | this first. 12 | 13 | 2) Create a patch file 14 | 15 | Go to the source directory and use `svn diff` to create a patch. 16 | 17 | **Use a descriptive patch name with the bug number and a short description, 18 | rather than a generic name like `patch.diff`.** 19 | 20 | ```bash 21 | cd $TOP_SRCDIR 22 | svn diff > $PATCHDIR/16629-infinite-recursion.diff 23 | ``` 24 | 25 | The example above uses `16629-infinite-recursion.diff` - this name follows the 26 | convention: bug number (16629), short description (infinite-recursion), and 27 | `.diff` extension, making patches easy to identify and review. 28 | 29 | The patch file will be saved in the directory specified by the PATCHDIR 30 | environment variable that is defined when the codespace starts. 31 | 32 | ```bash 33 | ls $PATCHDIR 34 | ``` 35 | 36 | lists all patch files in your patch directory, allowing you to easily 37 | see and verify the patch files you have created. 38 | -------------------------------------------------------------------------------- /Dockerfile: -------------------------------------------------------------------------------- 1 | FROM mcr.microsoft.com/devcontainers/cpp:dev-ubuntu-22.04 2 | 3 | ARG REINSTALL_CMAKE_VERSION_FROM_SOURCE="none" 4 | 5 | # Optionally install the cmake for vcpkg 6 | COPY ./reinstall-cmake.sh /tmp/ 7 | 8 | RUN if [ "${REINSTALL_CMAKE_VERSION_FROM_SOURCE}" != "none" ]; then \ 9 | chmod +x /tmp/reinstall-cmake.sh && /tmp/reinstall-cmake.sh ${REINSTALL_CMAKE_VERSION_FROM_SOURCE}; \ 10 | fi \ 11 | && rm -f /tmp/reinstall-cmake.sh 12 | 13 | RUN sed -i.bak "/^#.*deb-src.*universe$/s/^# //g" /etc/apt/sources.list \ 14 | && echo "deb https://cloud.r-project.org/bin/linux/ubuntu jammy-cran40/" >> /etc/apt/sources.list \ 15 | && wget -qO- https://cloud.r-project.org/bin/linux/ubuntu/marutter_pubkey.asc | sudo tee -a /etc/apt/trusted.gpg.d/cran_ubuntu_key.asc \ 16 | && apt update \ 17 | && apt -y install subversion \ 18 | && apt -y build-dep r-base-dev \ 19 | && apt -y install r-base-dev \ 20 | && Rscript -e "install.packages('languageserver', repos='https://cran.rstudio.com')" \ 21 | && Rscript -e "install.packages('httpgd', repos='https://cran.rstudio.com')" 22 | 23 | RUN apt install shellcheck 24 | RUN apt install -y ccache 25 | #RUN /usr/sbin/update-ccache-symlinks 26 | #RUN echo 'export PATH="/usr/lib/ccache:$PATH"' | tee -a /home/vscode/.bashrc 27 | 28 | 29 | 30 | ARG CONTAINER_VERSION 31 | ENV CONTAINER_VERSION ${CONTAINER_VERSION} 32 | -------------------------------------------------------------------------------- /docs/container_setup/gitpod_workspace/workspacestart.md: -------------------------------------------------------------------------------- 1 | 2 | ### Starting a Gitpod Workspace 3 | 4 | 1. **Log In:** Go to the [Gitpod login page](https://gitpod.io/login/) and sign 5 | in with your GitHub, GitLab, or Bitbucket account. This allows Gitpod to create 6 | workspaces from your repositories. 7 | 8 | 2. **Create a workspace using the R Dev Container repo:** Click the Gitpod badge 9 | below to open the Gitpod workspace creation dialog with the relevant options 10 | pre-filled: 11 | 12 |
[![Open in 13 | Gitpod](https://img.shields.io/badge/Gitpod-Open%20in%20Gitpod-blue?logo=gitpod&style=for-the-badge)](https://gitpod.io/github.com/r-devel/r-dev-env/tree/main){:target="_blank"} 14 |
15 | 16 |
![start gitpod 17 | workspace](../../assets/gitpod1.png){width="70%"}
18 | 19 | Click the "Continue" button in the Gitpod dialog to create a workspace. It 20 | will take approximately 15-20 minutes to create the workspace for the first 21 | time. The environment will be cached for faster startup in the future. 22 | 23 | !!! Note Changing the resource option from Standard to Large will reduce the 24 | free monthly Gitpod usage, which is 50 hours per month of Standard 25 | workspace usage. See the 26 | [billing](https://www.gitpod.io/docs/configure/billing) docs for more 27 | information. 28 | -------------------------------------------------------------------------------- /.gitpod.Dockerfile: -------------------------------------------------------------------------------- 1 | FROM gitpod/workspace-full:latest 2 | 3 | USER root 4 | 5 | ARG REINSTALL_CMAKE_VERSION_FROM_SOURCE="none" 6 | 7 | # Optionally install the cmake for vcpkg 8 | COPY ./reinstall-cmake.sh /tmp/ 9 | 10 | RUN if [ "${REINSTALL_CMAKE_VERSION_FROM_SOURCE}" != "none" ]; then \ 11 | chmod +x /tmp/reinstall-cmake.sh && /tmp/reinstall-cmake.sh ${REINSTALL_CMAKE_VERSION_FROM_SOURCE}; \ 12 | fi \ 13 | && rm -f /tmp/reinstall-cmake.sh 14 | 15 | RUN sed -i.bak "/^#.*deb-src.*universe$/s/^# //g" /etc/apt/sources.list \ 16 | && echo "deb https://cloud.r-project.org/bin/linux/ubuntu jammy-cran40/" >> /etc/apt/sources.list \ 17 | && wget -qO- https://cloud.r-project.org/bin/linux/ubuntu/marutter_pubkey.asc | sudo tee -a /etc/apt/trusted.gpg.d/cran_ubuntu_key.asc \ 18 | && apt update \ 19 | && apt -y install subversion \ 20 | && apt -y build-dep r-base-dev \ 21 | && apt -y install r-base-dev \ 22 | && apt -y install valgrind \ 23 | && Rscript -e "install.packages('languageserver', repos='https://cran.rstudio.com')" \ 24 | && Rscript -e "install.packages('httpgd', repos='https://cran.rstudio.com')" 25 | 26 | RUN apt install -y shellcheck 27 | RUN apt install -y ccache 28 | RUN apt install -y rsync 29 | #RUN /usr/sbin/update-ccache-symlinks 30 | #RUN echo 'export PATH="/usr/lib/ccache:$PATH"' | tee -a /home/vscode/.bashrc 31 | 32 | 33 | ARG CONTAINER_VERSION 34 | ENV CONTAINER_VERSION ${CONTAINER_VERSION} 35 | -------------------------------------------------------------------------------- /.github/workflows/optimize-docs-images.yml: -------------------------------------------------------------------------------- 1 | name: Optimize Docs Images 2 | 3 | on: 4 | pull_request: 5 | branches: ["main","devel"] 6 | types: [closed] 7 | paths: 8 | - 'docs/assets/**' 9 | 10 | jobs: 11 | optimize-images: 12 | if: ${{github.event_name == 'pull_request' && github.event.action == 'closed' && github.event.pull_request.merged == true}} 13 | runs-on: ubuntu-latest 14 | 15 | steps: 16 | - name: Checkout repository 17 | uses: actions/checkout@v2 18 | 19 | - name: Setup R 20 | uses: r-lib/actions/setup-r@v2 21 | 22 | - name: Install system dependencies 23 | run: | 24 | sudo apt-get update 25 | sudo apt-get install -y libmagick++-dev libcurl4-openssl-dev 26 | 27 | - name: Install R packages 28 | run: | 29 | R -e 'install.packages(c("magick"), repos = "https://cloud.r-project.org/")' 30 | 31 | - name: Optimize images 32 | run: | 33 | Rscript ./scripts/optimize.R 34 | 35 | - name: Commit and push optimized images 36 | if: github.ref == 'refs/heads/devel' && github.event_name == 'push' 37 | run: | 38 | git config --global user.name "github-actions[bot]" 39 | git config --global user.email "github-actions[bot]@users.noreply.github.com" 40 | git add docs/assets 41 | git commit -m 'Optimize docs images' 42 | git push 43 | env: 44 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 45 | -------------------------------------------------------------------------------- /docs/container_setup/github_codespace/creating_codespace.md: -------------------------------------------------------------------------------- 1 | 2 | 1. From the main branch of the [r-dev-env 3 | repo](https://github.com/r-devel/r-dev-env/tree/main), click on the 'Open in 4 | GitHub Codespaces' button and then click the green 'Create Codespace' button. 5 | ![create codespace](../../assets/rdev1.png) 6 | 7 | !!! Note You will see the message "Codespace usage for this repository is 8 | paid for by ...", with your username. Don't panic! 9 | 10 | GitHub Codespaces offers 120 core hours of free usage per month for every GitHub user. So the actual number of free hours is 120 divided by the number of cores you are using to run your codespaces. 11 | For the r-dev-env codespace we have set the codespace usage to 4 cores which leads to 30hrs of free usage per month. This can be changed according to your preference. 12 | 13 | For more details about codespaces billing, see the [Codespaces Billing Docs](https://github.com/features/codespaces). 14 | You can calculate your GitHub services usage with the [GitHub Services 15 | Pricing Calculator](https://github.com/pricing/calculator) and check your usage allowance under "Codespaces" on your [GitHub Billing page](https://github.com/settings/billing). 16 | 17 | 2. The codespace setup screen will then be shown. Starting the container may 18 | take a minute or so. 19 | 20 | 3. You will be taken to a VSCode editor within your browser. 21 | ![codespace](../../assets/rdev3.png) 22 | -------------------------------------------------------------------------------- /docs/contributor_guide/contributing_to_docs.md: -------------------------------------------------------------------------------- 1 | 2 | ##### Installation Setup 3 | 4 | 1. Fork and Clone the repo - 5 | 6 | 2. Change directory to r-dev-env 7 | 8 | 3. Create virtual environment using python venv 9 | 10 | ```bash 11 | python3 -m venv venv 12 | ``` 13 | 14 | 4. Now activate the virtual environment 15 | 16 | ```bash 17 | source ./venv/bin/activate 18 | ``` 19 | 20 | 5. Now install libraries and dependencies for mkdocs 21 | 22 | ```bash 23 | pip install mkdocs "mkdocs-material[imaging]" 24 | ``` 25 | 26 | 6. After setting up the virtual environment and installing necessary libraries, 27 | navigate to the root directory of the project where the `mkdocs.yml` file is 28 | located. 29 | 30 | 7. To start the local development server and preview changes, run the following 31 | command: 32 | 33 | ```bash 34 | mkdocs serve 35 | ``` 36 | 37 | This will compile the documentation and serve it locally. You can access the 38 | documentation by opening a web browser and navigating to 39 | . 40 | 41 | 8. Edit Documentation: Make changes to the documentation content files located 42 | in the `docs` directory. You can use Markdown syntax for formatting. 43 | 44 | 9. Preview Changes: As you make changes, the local development server will 45 | automatically detect them and update the preview in real-time. Refresh your 46 | browser to see the changes. 47 | 48 | **N.B.** There is a known issue with mkdocs not alwayds finding Cairo. The issue 49 | and suggested fixes are on the [MkDocs Image 50 | Processing](https://squidfunk.github.io/mkdocs-material/plugins/requirements/image-processing/) 51 | page. 52 | -------------------------------------------------------------------------------- /.github/workflows/schedule-docker-build.yml: -------------------------------------------------------------------------------- 1 | name: Build and publish Docker image (Schedule Workflow) 2 | 3 | on: 4 | schedule: 5 | - cron: '0 0 1,15 * *' 6 | 7 | 8 | env: 9 | REGISTRY: ghcr.io 10 | IMAGE_NAME: ${{ github.repository }} 11 | 12 | jobs: 13 | build-and-push-image: 14 | runs-on: ubuntu-latest 15 | permissions: 16 | contents: read 17 | packages: write 18 | strategy: 19 | matrix: 20 | branch: [main, devel] 21 | 22 | steps: 23 | - name: Checkout repository 24 | uses: actions/checkout@v4 25 | with: 26 | ref: ${{ matrix.branch }} #branch to be checkout 27 | 28 | - name: Extract version number 29 | run: | 30 | VER=$(cat VERSION) 31 | echo "VERSION=$VER" >> $GITHUB_ENV 32 | 33 | - name: Log in to the Container registry 34 | uses: docker/login-action@v3 35 | with: 36 | registry: ${{ env.REGISTRY }} 37 | username: ${{ github.actor }} 38 | password: ${{ secrets.GITHUB_TOKEN }} 39 | 40 | - name: Extract metadata (tags, labels) for Docker 41 | id: meta 42 | uses: docker/metadata-action@v5 43 | with: 44 | images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} 45 | tags: | 46 | type=ref,event=branch 47 | type=ref,event=pr 48 | type=semver,pattern={{ env.VERSION }} 49 | type=sha 50 | 51 | - name: Build and push Docker image 52 | uses: docker/build-push-action@v5 53 | with: 54 | context: . 55 | push: true 56 | build-args: | 57 | "CONTAINER_VERSION=${{ env.VERSION }}" 58 | tags: ${{ steps.meta.outputs.tags }} 59 | labels: ${{ steps.meta.outputs.labels }} 60 | -------------------------------------------------------------------------------- /reinstall-cmake.sh: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env bash 2 | #------------------------------------------------------------------------------------------------------------- 3 | # Copyright (c) Microsoft Corporation. All rights reserved. 4 | # Licensed under the MIT License. See https://go.microsoft.com/fwlink/?linkid=2090316 for license information. 5 | #------------------------------------------------------------------------------------------------------------- 6 | # 7 | set -e 8 | 9 | CMAKE_VERSION=${1:-"none"} 10 | 11 | if [ "${CMAKE_VERSION}" = "none" ]; then 12 | echo "No CMake version specified, skipping CMake reinstallation" 13 | exit 0 14 | fi 15 | 16 | # Cleanup temporary directory and associated files when exiting the script. 17 | cleanup() { 18 | EXIT_CODE=$? 19 | set +e 20 | if [[ -n "${TMP_DIR}" ]]; then 21 | echo "Executing cleanup of tmp files" 22 | rm -Rf "${TMP_DIR}" 23 | fi 24 | exit $EXIT_CODE 25 | } 26 | trap cleanup EXIT 27 | 28 | 29 | echo "Installing CMake..." 30 | apt-get -y purge --auto-remove cmake 31 | mkdir -p /opt/cmake 32 | 33 | architecture=$(dpkg --print-architecture) 34 | case "${architecture}" in 35 | arm64) 36 | ARCH=aarch64 ;; 37 | amd64) 38 | ARCH=x86_64 ;; 39 | *) 40 | echo "Unsupported architecture ${architecture}." 41 | exit 1 42 | ;; 43 | esac 44 | 45 | CMAKE_BINARY_NAME="cmake-${CMAKE_VERSION}-linux-${ARCH}.sh" 46 | CMAKE_CHECKSUM_NAME="cmake-${CMAKE_VERSION}-SHA-256.txt" 47 | TMP_DIR=$(mktemp -d -t cmake-XXXXXXXXXX) 48 | 49 | echo "${TMP_DIR}" 50 | cd "${TMP_DIR}" 51 | 52 | curl -sSL "https://github.com/Kitware/CMake/releases/download/v${CMAKE_VERSION}/${CMAKE_BINARY_NAME}" -O 53 | curl -sSL "https://github.com/Kitware/CMake/releases/download/v${CMAKE_VERSION}/${CMAKE_CHECKSUM_NAME}" -O 54 | 55 | sha256sum -c --ignore-missing "${CMAKE_CHECKSUM_NAME}" 56 | sh "${TMP_DIR}/${CMAKE_BINARY_NAME}" --prefix=/opt/cmake --skip-license 57 | 58 | ln -s /opt/cmake/bin/cmake /usr/local/bin/cmake 59 | -------------------------------------------------------------------------------- /.github/workflows/build-and-publish-image.yml: -------------------------------------------------------------------------------- 1 | # This workflow uses actions that are not certified by GitHub. 2 | # They are provided by a third-party and are governed by 3 | # separate terms of service, privacy policy, and support 4 | # documentation. 5 | 6 | name: Build and publish Docker image 7 | 8 | on: 9 | workflow_dispatch: 10 | pull_request: 11 | branches: ["main","devel"] 12 | types: [closed] 13 | paths: 14 | - '.github/workflows/build-and-publish-image.yml' 15 | - 'Dockerfile' 16 | - 'reinstall-cmake.sh' 17 | - 'VERSION' 18 | 19 | 20 | env: 21 | REGISTRY: ghcr.io 22 | IMAGE_NAME: ${{ github.repository }} 23 | 24 | jobs: 25 | build-and-push-image: 26 | if: ${{github.event_name == 'pull_request' && github.event.action == 'closed' && github.event.pull_request.merged == true}} 27 | runs-on: ubuntu-latest 28 | permissions: 29 | contents: read 30 | packages: write 31 | 32 | steps: 33 | - name: Checkout repository 34 | uses: actions/checkout@v4 35 | 36 | - name: Extract version number 37 | run: | 38 | VER=$(cat VERSION) 39 | echo "VERSION=$VER" >> $GITHUB_ENV 40 | 41 | - name: Log in to the Container registry 42 | uses: docker/login-action@v3 43 | with: 44 | registry: ${{ env.REGISTRY }} 45 | username: ${{ github.actor }} 46 | password: ${{ secrets.GITHUB_TOKEN }} 47 | 48 | - name: Extract metadata (tags, labels) for Docker 49 | id: meta 50 | uses: docker/metadata-action@v5 51 | with: 52 | images: ${{ env.REGISTRY }}/${{ github.repository }} 53 | tags: | 54 | type=ref,event=branch 55 | type=ref,event=pr 56 | type=semver,pattern={{ env.VERSION }} 57 | type=sha 58 | 59 | - name: Build and push Docker image 60 | uses: docker/build-push-action@v5 61 | with: 62 | context: . 63 | push: true 64 | tags: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.ref_name }} 65 | build-args: | 66 | CONTAINER_VERSION=${{ env.VERSION }} 67 | labels: ${{ steps.meta.outputs.labels }} 68 | -------------------------------------------------------------------------------- /.github/workflows/build-gitpod-image.yml: -------------------------------------------------------------------------------- 1 | # This workflow uses actions that are not certified by GitHub. 2 | # They are provided by a third-party and are governed by 3 | # separate terms of service, privacy policy, and support 4 | # documentation. 5 | 6 | name: Build and publish Gitpod Docker image 7 | 8 | on: 9 | workflow_dispatch: 10 | pull_request: 11 | branches: ["main","devel"] 12 | types: [closed] 13 | paths: 14 | - '.github/workflows/build-gitpod-image.yml' 15 | - '.gitpod.Dockerfile' 16 | - '.gitpod.yml' 17 | - 'reinstall-cmake.sh' 18 | - 'VERSION' 19 | 20 | 21 | env: 22 | REGISTRY: ghcr.io 23 | IMAGE_NAME: ${{ github.repository }} 24 | 25 | jobs: 26 | build-and-push-image: 27 | if: ${{github.event_name == 'pull_request' && github.event.action == 'closed' && github.event.pull_request.merged == true}} 28 | runs-on: ubuntu-latest 29 | permissions: 30 | contents: read 31 | packages: write 32 | 33 | steps: 34 | - name: Checkout repository 35 | uses: actions/checkout@v4 36 | 37 | - name: Extract version number 38 | run: | 39 | VER=$(cat VERSION) 40 | echo "VERSION=$VER" >> $GITHUB_ENV 41 | 42 | - name: Log in to the Container registry 43 | uses: docker/login-action@v3 44 | with: 45 | registry: ${{ env.REGISTRY }} 46 | username: ${{ github.actor }} 47 | password: ${{ secrets.GITHUB_TOKEN }} 48 | 49 | - name: Extract metadata (tags, labels) for Docker 50 | id: meta 51 | uses: docker/metadata-action@v5 52 | with: 53 | images: ${{ env.REGISTRY }}/${{ github.repository }} 54 | tags: | 55 | type=ref,event=branch 56 | type=ref,event=pr 57 | type=semver,pattern={{ env.VERSION }} 58 | type=sha 59 | 60 | - name: Build and push Docker image 61 | uses: docker/build-push-action@v5 62 | with: 63 | context: . 64 | file: .gitpod.Dockerfile 65 | push: true 66 | tags: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:gitpod.${{ github.ref_name }} 67 | build-args: | 68 | CONTAINER_VERSION=${{ env.VERSION }} 69 | labels: ${{ steps.meta.outputs.labels }} 70 | -------------------------------------------------------------------------------- /docs/tutorials/svn_help.md: -------------------------------------------------------------------------------- 1 | ## Checking out a different revision 2 | 3 | You can check out a specific revision of the R sources with 4 | 5 | ```bash 6 | svn checkout -r 1234 https://svn.r-project.org/R/trunk/ $TOP_SRCDIR 7 | ``` 8 | 9 | ### Finding the last revision that passed check 10 | 11 | Occasionally, the latest revision of the R sources does not pass `make check`. 12 | In this case, it can be a good idea to revert to an earlier revision until the R 13 | Core Team have made further updates to fix the issue. 14 | 15 | Visit the [Build from 16 | SVN](https://github.com/r-devel/r-svn/actions/workflows/build-svn.yaml) page 17 | that summarises attempted builds of R using GitHub actions on the unofficial 18 | GitHub mirror. Find the latest run that completed successfully (green 19 | checkmark) and use the commit message to search for the corresponding Subversion 20 | revision. For example, to search the last 10 revisions for the log message 21 | "More @apifun and such annotations" 22 | 23 | ```bash 24 | cd $TOP_SRCDIR 25 | svn log --limit 10 --search "More @apifun and such annotations" 26 | ``` 27 | 28 | ```bash 29 | /workspaces/r-dev-env/svn/r-devel $ svn log --limit 10 --search "More @apifun and such annotations" 30 | ------------------------------------------------------------------------ 31 | r86726 | luke | 2024-06-12 18:00:19 +0000 (Wed, 12 Jun 2024) | 2 lines 32 | 33 | More @apifun and such annotations. 34 | 35 | ------------------------------------------------------------------------ 36 | r86723 | luke | 2024-06-11 20:31:36 +0000 (Tue, 11 Jun 2024) | 2 lines 37 | 38 | More @apifun and such annotations. 39 | 40 | ------------------------------------------------------------------------ 41 | ``` 42 | 43 | If you have already attempted to build R, you can re-run the make with the 44 | version identified in your search as follows: 45 | 46 | ```bash 47 | svn checkout -r 86726 https://svn.r-project.org/R/trunk/ $TOP_SRCDIR 48 | cd $BUILDDIR 49 | make 50 | make check 51 | ``` 52 | 53 | Otherwise, follow the full instructions in [Building R](./building_r.md), 54 | updating the svn checkout command to use the required revision. 55 | 56 | ## Further Subversion Help 57 | 58 | For further help on Subversion, refer to the online book [Version Control with 59 | Subversion](https://svnbook.red-bean.com/). 60 | -------------------------------------------------------------------------------- /docs/tutorials/update_source.md: -------------------------------------------------------------------------------- 1 | The R Core Team commit changes to the development version of R sometimes 2 | multiple times a day. It's a good idea to update your local copy of the source 3 | code from time to time, especially before creating a patch. To do so, follow 4 | these steps: 5 | 6 | #### 1) Close R terminal 7 | 8 | If you have an R terminal open, quit R or close the terminal. 9 | 10 | #### 2) Go to the source directory 11 | 12 | In a bash terminal, change to the source directory 13 | 14 | ```bash 15 | cd $TOP_SRCDIR 16 | ``` 17 | 18 | #### 3) Review local changes 19 | 20 | Use the Subversion diff command to review changes you have made to source code 21 | 22 | ```bash 23 | svn diff 24 | ``` 25 | 26 | #### 4) Revert changes (optional) 27 | 28 | If you no longer want to keep your local changes, you can revert them. 29 | 30 | Revert the changes made in specific file 31 | 32 | ```bash 33 | svn revert src/library/utils/R/askYesNo.R 34 | ``` 35 | 36 | Revert changes in a directory 37 | 38 | ```bash 39 | svn revert src/lib/utils 40 | ``` 41 | 42 | Revert all local changes 43 | 44 | ```bash 45 | svn revert -R . 46 | ``` 47 | 48 | #### 5) Rebuild and check with any local changes 49 | 50 | If you have no local changes remaining, skip to the next step. 51 | 52 | Otherwise, go to the build directory to build and check R with your local 53 | changes. 54 | 55 | ```bash 56 | cd $BUILDDIR 57 | make 58 | make check 59 | ``` 60 | 61 | If the check fails with an error, you have broken something with your local 62 | changes. Fix this before proceeding. Otherwise go back to the source directory 63 | to continue 64 | 65 | ```bash 66 | cd $TOP_SRCDIR 67 | ``` 68 | 69 | #### 6) Update using svn 70 | 71 | Use the Subversion command `update` to update your local copy with the latest 72 | changes by the R Core Team. 73 | 74 | ```bash 75 | svn update 76 | ``` 77 | 78 | #### 7) Rebuild and check with the updates 79 | 80 | To rebuild R with the latest changes from the R Core Team and any local changes 81 | you have kept, go to the build directory to build and check R 82 | 83 | ```bash 84 | cd $BUILDDIR 85 | make 86 | make check 87 | ``` 88 | 89 | If the check fails, this will be due to recent changes made by the R Core 90 | Team. See [SVN Help](./svn_help.md) for how to revert to a version that passes 91 | check. 92 | -------------------------------------------------------------------------------- /INDEX.md: -------------------------------------------------------------------------------- 1 | # Welcome to the R Dev Container 2 | 3 | If you haven't seen them yet, you can find the [R Dev Container 4 | Docs](https://contributor.r-project.org/r-dev-env/) online. 5 | 6 | This index links to underlying markdown files for key sections of the docs, so 7 | you can preview them right here in VS Code. 8 | 9 | ## Working with the container 10 | 11 | The links below give more information on using the container via GitHub 12 | Codespaces or Gitpod Workspaces. Take a moment to review how to stop and 13 | restart your container, so you can continue your work. If you are collaborating 14 | with others, you may want to use Live Share so that you can share the same 15 | workspace. 16 | 17 | ### Github Codespace 18 | 19 | - [Stopping and Restarting 20 | Codespace](docs/container_setup/github_codespace/codespacestartstop.md) 21 | - [Collaborating with Live 22 | Share](docs/container_setup/github_codespace/live_share.md) 23 | 24 | ### Gitpod Workspace 25 | 26 | - [Stopping and Restarting 27 | Codespace](docs/container_setup/gitpod_workspace/workspacestop_and_restart.md) 28 | - [Collaborating with Live 29 | Share](docs/container_setup/gitpod_workspace/live_share.md) 30 | 31 | ## Tutorials 32 | 33 | Learn how to use the container with these mini tutorials. If you have used R in 34 | VSCode before, you can skip Tutorial 1. Tutorials 2 and 3 are the minimum to 35 | get started with R development. You can run through these in about 30 minutes. 36 | You can refer to the remaining sections as needed! 37 | 38 | 1. [Running R](docs/tutorials/running_r.md) 39 | 2. [Building R](docs/tutorials/building_r.md) 40 | 3. [R Contribution Workflow](docs/tutorials/contribution_workflow.md) 41 | 4. [Updating Source Code](docs/tutorials/update_source.md) 42 | 5. [Creating a Patch File](docs/tutorials/patch_update.md) 43 | 6. [Multiple R versions](docs/tutorials/multi_r_compilation.md) 44 | 7. [SVN Help](docs/tutorials/svn_help.md) 45 | 46 | ## Further docs 47 | 48 | See the [full documentation](https://contributor.r-project.org/r-dev-env/) for 49 | background information on this project, how to contribute to the 50 | [documentation](docs/contributor_guide/contributing_to_docs.md) or the 51 | [codebase](docs/contributor_guide/contributing_to_codebase.md), [external 52 | resources](docs/resources.md) and [troubleshooting](docs/troubleshoot.md). 53 | -------------------------------------------------------------------------------- /docs/container_setup/gitpod_workspace/workspacestop_and_restart.md: -------------------------------------------------------------------------------- 1 | ### Stopping a Gitpod Workspace 2 | 3 | 1. **Locate the Gitpod Command Palette Button:** To stop the current workspace, 4 | look for the orange Gitpod command palette button in the bottom left corner of 5 | the workspace. 6 | 7 | ![stop gitpod workspace](../../assets/gitpod2.png) 8 | 2. **Open the Command Palette and Stop the Workspace:** After clicking on the 9 | Gitpod command palette button, a pop-up will appear from the top of the 10 | screen. Select the Gitpod: Stop Workspace option to stop the current workspace. 11 | 12 | ![stop gitpod workspace](../../assets/gitpod3.png) 13 | 14 | !!! Note Stopping a workspace will save its state, so you can resume later 15 | without losing your progress. 16 | 17 | ### Restarting a Gitpod Workspace 18 | 19 | 1. **Open Gitpod Dashboard:** Once you're in the Gitpod dashboard, navigate to 20 | the "Workspaces" section. In the "Workspaces" section, you will see a list of 21 | your current and past workspaces. Locate the workspace you want to 22 | restart. Stopped workspaces will have an indicator showing they are not running. 23 | 24 | ![restart gitpod workspace](../../assets/gitpod4.png) 25 | 2. **Restart the Workspace:** To restart a workspace, click on the workspace in 26 | the list you want to restart. This will launch the workspace, restoring it to 27 | the state it was in when it was last stopped. 28 | 29 | ### Managing and Sustaining Codespaces 30 | 31 | #### Gitpod Workspace Pinning 32 | 33 | 34 | 35 | **Purpose:** Workspace pinning prevents important workspaces from being 36 | automatically deleted. 37 | 38 | **Pinned Workspace:** A workspace that has been pinned will never be deleted, 39 | regardless of inactivity or other automated processes. 40 | 41 | **How to Pin:** 42 | 43 | - Navigate to your workspace list in the Gitpod dashboard. 44 | - Identify the workspace you want to keep permanently. 45 | - Pin the workspace to ensure it remains available and is not subject to 46 | deletion. ![manage gitpod workspace](../../assets/manage_workspace.png) 47 | 48 | **Benefits:** 49 | 50 | Protects critical projects or environments from accidental loss. Ensures 51 | long-term availability of specific workspaces that you frequently use or need to 52 | preserve. 53 | 54 | 55 | -------------------------------------------------------------------------------- /scripts/which_r.sh: -------------------------------------------------------------------------------- 1 | 2 | 3 | which_r() { 4 | # Specify the parent directory 5 | parent_dir="$WORK_DIR/build" 6 | 7 | # Path to the settings.json file 8 | settings_file_path=$WORK_DIR/.vscode/settings.json 9 | 10 | built_in_r_version=$(R --version | grep "^R version" | awk '{print $3}') 11 | 12 | # Ask user which R version to use 13 | echo "Which version of R should be used in new R terminals?" 14 | echo " 1. R $built_in_r_version (release version built into this container)" 15 | 16 | # Check for additional R versions in subdirectories 17 | if [ -d "$parent_dir" ]; then 18 | # Create an array to store subdirectory names 19 | subdirs=() 20 | 21 | # Loop through subdirectories and print numbered list 22 | counter=2 # Start counter at 2 to avoid conflict with built-in R 23 | for dir in "$parent_dir"/*; do 24 | if [ -d "$dir/bin" ] && [ -x "$dir/bin/R" ]; then 25 | subdir=$(basename "$dir") 26 | subdirs+=("$subdir") # Populate subdirs array 27 | echo " $counter. $subdir" 28 | ((counter++)) 29 | fi 30 | done 31 | fi 32 | 33 | # If no additional R builds were found 34 | if [ ${#subdirs[@]} -eq 0 ]; then 35 | range=1 36 | echo "No additional R builds available." 37 | else 38 | range=$((counter - 1)) 39 | fi 40 | 41 | # Get user choice 42 | read -p "Enter the number corresponding to the selected version: " choice 43 | 44 | # Define selected version based on choice 45 | if [[ "$choice" -eq 1 ]]; then 46 | # Use built-in R 47 | selected_version="/usr/bin/R" 48 | elif [[ "$choice" -ge 2 ]] && [[ "$choice" -lt "$counter" ]]; then 49 | # Use R from chosen subdirectory 50 | chosen_subdir="${subdirs[((choice - 2))]}" 51 | selected_version="$parent_dir/$chosen_subdir/bin/R" 52 | else 53 | # Invalid choice, default to built-in R 54 | if [[ $range -eq 1 ]]; then 55 | echo "Invalid choice, please enter 1. Defaulting to built-in R version." 56 | else 57 | echo "Invalid choice, please select options between 1 to $range. Defaulting to built-in R version." 58 | fi 59 | selected_version="/usr/bin/R" 60 | fi 61 | 62 | # Update settings.json with the chosen R path 63 | updated_settings_data=$(cat "$settings_file_path" | jq --arg subdir "$selected_version" '."r.rterm.linux"=$subdir') 64 | echo "$updated_settings_data" > "$settings_file_path" 65 | 66 | echo "R terminal will now use version: $selected_version" 67 | } 68 | -------------------------------------------------------------------------------- /docs/container_setup/local_setup/localsetup.md: -------------------------------------------------------------------------------- 1 | !!! note Local setup is not recommended on macOS or Windows as the Docker 2 | container will work via a Virtual Machine and building R will take far 3 | longer (e.g. a full build may take 1 hour vs 10 minutes!). 4 | 5 | We can also use this codespace locally. For that we need to have some 6 | prerequisites installed. 7 | 8 | #### > Prerequisites 9 | 10 | 1. Docker Engine or Docker Desktop. You can find the docker desktop install 11 | instructions on [Docker Desktop 12 | Docs](https://www.docker.com/products/docker-desktop/). 13 | 2. VSCode Editor. You can download and install from [VSCode 14 | website](https://code.visualstudio.com/download). 15 | 16 | #### > Steps to run R Development Container locally 17 | 18 | 1. Clone the [R Dev Container Github 19 | repo](https://github.com/r-devel/r-dev-env/) 20 | 2. In a terminal, change directory to r-dev-env 21 | 22 | ```bash 23 | cd r-dev-env 24 | ``` 25 | 26 | 3. Restart VSCode in the `r-dev-env` directory with the command: 27 | 28 | ```bash 29 | code . 30 | ``` 31 | 32 | 4. Checkout the main branch and pull the latest changes 33 | 34 | ```bash 35 | git checkout main 36 | git pull 37 | ``` 38 | 39 | The main branch provides the stable release. If you require an in-development 40 | feature, use the devel branch instead. 41 | 42 | 5. After this step please be sure that your docker engine is started. If you 43 | have installed Docker Desktop just open the Docker Desktop app the engine 44 | starts automatically and if you are using just docker engine make sure to 45 | start it with the following command 46 | 47 | ```bash 48 | systemctl start docker 49 | ``` 50 | 51 | 6. We can see pop-up at the bottom right of the VSCode editor which says reopen 52 | in Dev Container. Click on `Reopen in DevContainer` button. ![start 53 | localsetup](../../assets/rdev13.png) 54 | 55 | 7. After clicking on that button we will see our container is getting ready. It 56 | will take some time. So till that time you can have coffee :) ![start 57 | localsetup](../../assets/rdev24.png) 58 | 8. We can also test whether the dev container is working or not by just printing 59 | the environment variables mentioned in the welcome message on the terminal. And 60 | there we go!!! We have setup our R Dev Container locally. ![start 61 | localsetup](../../assets/rdev25.png) 62 | 63 | 9. The container will be closed when you close VSCode. To reopen the container, 64 | open the `r-dev-env` directory in VSCode. 65 | -------------------------------------------------------------------------------- /.github/workflows/build-mkdocs-website.yml: -------------------------------------------------------------------------------- 1 | name: Build MKDocs website 2 | 3 | on: 4 | workflow_dispatch: 5 | pull_request: 6 | branches: ["main","devel"] 7 | types: [closed] 8 | paths: 9 | - '.github/workflows/build-mkdocs-website.yml' 10 | - 'docs/**/**' 11 | - 'mkdocs.yml' 12 | 13 | jobs: 14 | build-and-deploy: 15 | if: | 16 | github.event_name == 'workflow_dispatch' || 17 | (github.event_name == 'pull_request' && github.event.pull_request.merged == true) 18 | runs-on: ubuntu-latest 19 | permissions: 20 | contents: write 21 | 22 | steps: 23 | - name: Checkout repository 24 | uses: actions/checkout@v4 25 | 26 | - name: Set up Python 27 | uses: actions/setup-python@v5 28 | with: 29 | python-version: 3.x 30 | 31 | - name: Install dependencies 32 | run: pip install mkdocs mkdocs-material[imaging] 33 | 34 | - name: Determine deployment settings 35 | id: config 36 | run: | 37 | if [[ "${{ github.ref_name }}" == "main" ]]; then 38 | echo "target_repo=${{ github.repository }}" >> "$GITHUB_OUTPUT" 39 | echo "url=https://contributor.r-project.org/r-dev-env" >> "$GITHUB_OUTPUT" 40 | else 41 | echo "target_repo=r-devel/r-dev-env-devel" >> "$GITHUB_OUTPUT" 42 | echo "url=https://contributor.r-project.org/r-dev-env-devel" >> "$GITHUB_OUTPUT" 43 | fi 44 | 45 | - name: Modify site_url in mkdocs.yml 46 | run: | 47 | echo "Setting site_url to ${{ steps.config.outputs.url }}" 48 | sed -i "s|^site_url:.*|site_url: '${{ steps.config.outputs.url }}'|" mkdocs.yml 49 | 50 | - name: Build MkDocs 51 | run: mkdocs build 52 | 53 | - name: Validate PAT 54 | env: 55 | GH_PAT: ${{ secrets.R_DEV_ENV_DOCS }} 56 | run: | 57 | curl -H "Authorization: token $GH_PAT" https://api.github.com/user || { 58 | echo "PAT is invalid or expired" >&2 59 | exit 1 60 | } 61 | 62 | - name: Deploy to GitHub Pages 63 | env: 64 | GH_PAT: ${{ secrets.R_DEV_ENV_DOCS }} 65 | run: | 66 | echo "Deploying from branch: ${{ github.ref_name }}" 67 | echo "Commit: ${{ github.sha }}" 68 | git config --global credential.helper store 69 | echo "https://x-access-token:${GH_PAT}@github.com" > ~/.git-credentials 70 | git remote set-url origin https://github.com/${{ steps.config.outputs.target_repo }} 71 | mkdocs gh-deploy --config-file mkdocs.yml --remote-branch gh-pages --force 72 | -------------------------------------------------------------------------------- /docs/tutorials/contribution_workflow.md: -------------------------------------------------------------------------------- 1 | #### 1. Example Contribution Workflow using the R Dev Container 2 | 3 | - To start working in R we will click on `R:(not attach)` which is in the bottom 4 | right of the VSCode window. This will open an R terminal for us. 5 | 6 | ![alt text](../assets/rdev11.png) 7 | 8 | ![alt text](../assets/rdev12.png) 9 | 10 | - We can now run R commands. We will use the `utils::askYesNo()` function as an 11 | example 12 | 13 | ![alt text](../assets/rdev19.png) 14 | 15 | ```Rconsole 16 | > askYesNo("Is this a good example?") 17 | Is this a good example? (Yes/no/cancel) Yes 18 | [1] TRUE 19 | ``` 20 | 21 | #### 2. Editing Source Code 22 | 23 | - Edit the source code of `utils::askYesNo()` to change the default options. The 24 | source code can be found in `$TOP_SRCDIR/src/library/utils/R/askYesNo.R`. 25 | - You can redirect to that file using 26 | 27 | ```bash 28 | code $TOP_SRCDIR/src/library/utils/R/askYesNo.R 29 | ``` 30 | 31 | **> Before edit:** ![alt text](../assets/rdev20.png) 32 | 33 | ```R title="askYesNo.R" linenums="20" 34 | prompts = getOption("askYesNo", gettext(c("Yes", "No", "Cancel"))), 35 | ``` 36 | 37 | **> With edit (for example - change to whatever you like!):** 38 | 39 | ![alt text](../assets/rdev21.png) 40 | 41 | ```R title="askYesNo.R" linenums="20" 42 | prompts = getOption("askYesNo", gettext(c("Oh yeah!", "Don't think so", "Cancel"))), 43 | ``` 44 | 45 | #### 3. Rebuild R 46 | 47 | - We can re-build R with our changes. Since we have only modified the utils 48 | package, rebuilding R will only re-build the utils package. 49 | - First we need to be inside $BUILDDIR. 50 | - Quit R with `q()` or by closing the R terminal. 51 | - In the bash terminal, change to the build directory: 52 | 53 | ```bash 54 | cd $BUILDDIR 55 | ``` 56 | 57 | - Now run the `make` command to rebuild R with the changes you made in 58 | step 2. This will be much faster than the full build! 59 | 60 | ```bash 61 | make 62 | ``` 63 | 64 | ![alt text](../assets/rdev22.png) 65 | 66 | - Optionally run `make check` to run R's test suite with your local changes. You 67 | may skip this step while you are iterating on a bug fix or other development, 68 | until you are ready to [create a patch](./patch_update.md). 69 | 70 | - To use the re-built R, simply open a new R terminal. 71 | 72 | #### 4. Cross check and Re-running Code 73 | 74 | - Check the edit has worked as expected by re-running the example code: ![alt 75 | text](../assets/rdev23.png) 76 | 77 | ```Rconsole 78 | > askYesNo("Is this a good example?") 79 | Is this a good example? (Oh yeah!/don't think so/cancel) Oh yeah! 80 | [1] TRUE 81 | ``` 82 | -------------------------------------------------------------------------------- /mkdocs.yml: -------------------------------------------------------------------------------- 1 | site_name: R Devel Container Docs 2 | repo_name: r-devel/r-dev-env 3 | repo_url: https://github.com/r-devel/r-dev-env 4 | nav: 5 | - 'Home': 'index.md' 6 | - 'Container Setup': 7 | - 'Overview': 'container_setup/index.md' 8 | - 'Github Codespace': 9 | - 'Starting Codespace': 'container_setup/github_codespace/creating_codespace.md' 10 | - 'Stopping and Restarting' : 'container_setup/github_codespace/codespacestartstop.md' 11 | - 'Collaborating with Live Share' : 'container_setup/github_codespace/live_share.md' 12 | - 'Gitpod Workspace': 13 | - 'Start Workspace': 'container_setup/gitpod_workspace/workspacestart.md' 14 | - 'Stopping and Restarting' : 'container_setup/gitpod_workspace/workspacestop_and_restart.md' 15 | - 'Collaborating with Live Share' : 'container_setup/gitpod_workspace/live_share.md' 16 | - 'Local Setup' : 17 | - 'Docker': 'container_setup/local_setup/localsetup.md' 18 | - 'Tutorials': 19 | - 'Running R' : 'tutorials/running_r.md' 20 | - 'Building R': 'tutorials/building_r.md' 21 | - 'R Contribution Workflow' : 'tutorials/contribution_workflow.md' 22 | - 'Updating Source Code' : 'tutorials/update_source.md' 23 | - 'Creating a Patch File' : 'tutorials/patch_update.md' 24 | - 'Multiple R Versions' : 'tutorials/multi_r_compilation.md' 25 | - 'SVN Help' : 'tutorials/svn_help.md' 26 | - 'Contributor Guide' : 27 | - 'contributor_guide/contributing_to_docs.md' 28 | - 'contributor_guide/contributing_to_codebase.md' 29 | - 'Resources' : 'resources.md' 30 | - 'Troubleshooting Info' : 'troubleshoot.md' 31 | theme: 32 | name: material 33 | features: 34 | - navigation.tabs 35 | - navigation.sections 36 | - toc.integrate 37 | - navigation.top 38 | - search.suggest 39 | - search.highlight 40 | - search.share 41 | - content.tabs.link 42 | - content.code.annotation 43 | - content.code.copy 44 | 45 | 46 | palette: 47 | - scheme: default 48 | toggle: 49 | icon: material/brightness-7 50 | name: Switch to dark mode 51 | primary: indigo 52 | accent: blue 53 | - scheme: slate 54 | toggle: 55 | icon: material/brightness-4 56 | name: Switch to light mode 57 | primary: indigo 58 | accent: blue 59 | 60 | plugins: 61 | - social 62 | - search 63 | 64 | extra: 65 | social: 66 | - icon: fontawesome/brands/github 67 | link: https://github.com/r-devel/r-dev-env/ 68 | - icon: fontawesome/brands/slack 69 | link: https://r-contributors.slack.com/ 70 | 71 | markdown_extensions: 72 | - pymdownx.highlight: 73 | anchor_linenums: true 74 | - pymdownx.inlinehilite 75 | - pymdownx.snippets 76 | - admonition 77 | - pymdownx.arithmatex: 78 | generic: true 79 | - footnotes 80 | - pymdownx.details 81 | - pymdownx.superfences 82 | - pymdownx.mark 83 | - attr_list 84 | -------------------------------------------------------------------------------- /NEWS.md: -------------------------------------------------------------------------------- 1 | ## R Development Container 0.3 2 | 3 | - Implemented Gitpod setup with GitHub Actions workflow to build Docker images 4 | for the Gitpod workspace. 5 | - Improved `which_r` script with version choice validation and updated both 6 | `which_r` and `set_build_r` scripts for enhanced functionality. 7 | - Resolved local setup permission issues to ensure smoother operation within the 8 | devcontainer environment on Linux. 9 | - Restructured documentation to incorporate Gitpod alternative setup. 10 | - Implemented a workflow to optimize images so that documentation files are more 11 | lightweight. 12 | 13 | ## R Development Container 0.2 14 | 15 | - Documentation split into set of markdown files. These are used to create the 16 | documentation website and the 17 | user-focused pages can be accessed directly within the codespace, linked from 18 | an index that opens when the codespace first starts. New documentation 19 | pages/topics: 20 | - Restarting and stopping the codespace 21 | - Live Share 22 | - Local Setup 23 | - Updating Source Code 24 | - Creating a patch file 25 | - Multiple R Versions 26 | - SVN Help 27 | - Contributor Guide (for R Dev Container itself) 28 | - Troubleshooting 29 | - Building R documentation now instructs to build R with recommended packages as 30 | it only takes a few more minutes to set up and enables all the tests to be run 31 | with `make check`. 32 | - Updated GitHub Actions, so that the container is rebuilt twice a month with 33 | updated software, including the latest version of R. 34 | - Disconnected Codespace from r-dev-env GitHub repository, so changes are not 35 | tracked as changes to code for the container itself. 36 | - Updated Codespace settings so that checkouts of the R sources are recognised 37 | as Subversion repositories, connecting to VS Code version control tab. 38 | - Updated Codespace settings so that the R code linter is turned off (cannot 39 | define linter for base R!) 40 | - Enabled httpgd graphics device to replace the default of plotting to PNG. 41 | - Modified the default settings of `$BUILDDIR` and `$TOP_SRCDIR` to give a more 42 | logical setup for working with multiple R versions. 43 | - Added `which_r` script to set the R version to use in R terminals, rather than 44 | using `sudo make install` to overwrite installed R release version. 45 | - Added `set_build_r` bash function to facilitate custom settings of `$BUILDDIR` 46 | and `$TOP_SRCDIR` for working with multiple R versions. 47 | 48 | ## R Development Container 0.1 49 | 50 | First version of the R Development Container, including: 51 | 52 | - DevContainer definition for creating a codespace allowing users to build R in 53 | a web based environment 54 | - Instructions for building the current version of R from the SVN trunk within 55 | the DevContainer in the README.md file 56 | - Contributor workflow instructions in the README.md file 57 | - Docker image build from the dev-container branch which contains the 58 | requirements for building base R. The image is available from 59 | 60 | - Project website build from the website branch and available at 61 | 62 | 63 | We hope the R Development Container helps you in your R journey 😊 64 | -------------------------------------------------------------------------------- /docs/tutorials/multi_r_compilation.md: -------------------------------------------------------------------------------- 1 | The [Building R](./building_r.md) and [R Contribution Workflow](./building_r.md) 2 | tutorials use the simplest set up, working on a single copy of the R sources. 3 | 4 | It can be helpful to work with multiple versions of R: 5 | 6 | - to compare your modifications with an unmodified copy, e.g. to compare speed 7 | or memory usage, or 8 | - to work on independent changes, so that each patch only contains the changes 9 | for one bug fix or new feature. 10 | 11 | You can build multiple R versions in the same Codespaces environment. 12 | 13 | 1. First choose a name for the R version. This will be used to identify the 14 | version and to name the build/source directory. By default, we use the name 15 | `r-devel` and the environment variables `BUILDDIR` and `TOP_SRCDIR` are set 16 | to match. 17 | 18 | For illustration, we will use `r-devel-raw`, which you might use to name a 19 | version of R that you never modify. 20 | 21 | 2. You can set the `BUILDDIR` and `TOP_SRCDIR` environment variables to match 22 | your chosen name using the `set_build_r` function: 23 | 24 | - Open a terminal in the codespace. 25 | 26 | - Run the `set_build_r` function with your chosen name as the argument, e.g. 27 | 28 | ```bash 29 | set_build_r r-devel-raw 30 | ``` 31 | 32 | The new values of the environment variables will be printed as 33 | confirmation: 34 | 35 | ```bash 36 | BUILDDIR is now set to /workspaces/r-dev-env/build/r-devel-raw 37 | TOP_SRCDIR is now set to /workspaces/r-dev-env/svn/r-devel-raw 38 | ``` 39 | 40 | 3. If you have an unmodified build of R-devel using the default name of 41 | `r-devel`, you can simply copy the sources and the build to the new 42 | directories with `rsync`: 43 | 44 | ```bash 45 | rsync -a "$(dirname "$BUILDDIR")/r-devel/"* $BUILDDIR 46 | rsync -a "$(dirname "$TOP_SRCDIR")/r-devel/"* $TOP_SRCDIR 47 | ``` 48 | 49 | Otherwise you can follow the steps in the [Building R](./building_r.md) 50 | tutorial to checkout the R sources and build R using the new source and 51 | build directories. 52 | 53 | 4. Once you have a build of R under the new build directory, you will see your 54 | chosen name in the choices when running the `which_r` script to select the 55 | version of R to run in new terminals, e.g. 56 | 57 | ```bash 58 | which_r 59 | ``` 60 | 61 | ```bash 62 | Which version of R should be used in new R terminals? 63 | 1. R 4.4.0 (release version built into this container) 64 | Additional R builds available: 65 | 2. r-devel 66 | 3. r-devel-raw 67 | Enter the number corresponding to the selected version: 68 | ``` 69 | 70 | 71 | !!! Note 72 | `BUILDDIR` and `TOP_SRCDIR` will be set to the defaults using the label `r-devel` 73 | whenever a new bash terminal is opened, e.g. when the codespace is restarted. 74 | 75 | Whenever following instructions that use these variables to refer to the build 76 | and source directory, be sure they are pointing to the desired version! 77 | 78 | You can check the values any time with 79 | 80 | ```bash 81 | echo $BUILDDIR 82 | echo $TOP_SRCDIR 83 | ``` 84 | 85 | and switch with `set_build_r `. 86 | 87 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Code of Conduct - R Dev Container 2 | 3 | ## Our Pledge 4 | 5 | In the interest of fostering an open and welcoming environment, we as 6 | contributors and maintainers pledge to make participation in our project and 7 | our community a harassment-free experience for everyone, regardless of age, body 8 | size, disability, ethnicity, sex characteristics, gender identity and expression, 9 | level of experience, education, socio-economic status, nationality, personal 10 | appearance, race, religion, or sexual identity and orientation. 11 | 12 | ## Our Standards 13 | 14 | Examples of behavior that contributes to a positive environment for our 15 | community include: 16 | 17 | * Demonstrating empathy and kindness toward other people 18 | * Being respectful of differing opinions, viewpoints, and experiences 19 | * Giving and gracefully accepting constructive feedback 20 | * Accepting responsibility and apologizing to those affected by our mistakes, 21 | and learning from the experience 22 | * Focusing on what is best not just for us as individuals, but for the 23 | overall community 24 | 25 | Examples of unacceptable behavior include: 26 | 27 | * The use of sexualized language or imagery, and sexual attention or 28 | advances 29 | * Trolling, insulting or derogatory comments, and personal or political attacks 30 | * Public or private harassment 31 | * Publishing others' private information, such as a physical or email 32 | address, without their explicit permission 33 | * Other conduct which could reasonably be considered inappropriate in a 34 | professional setting 35 | 36 | ## Our Responsibilities 37 | 38 | Project maintainers are responsible for clarifying and enforcing our standards of 39 | acceptable behavior and will take appropriate and fair corrective action in 40 | response to any instances of unacceptable behavior. 41 | 42 | Project maintainers have the right and responsibility to remove, edit, or reject 43 | comments, commits, code, wiki edits, issues, and other contributions that are 44 | not aligned to this Code of Conduct, or to ban 45 | temporarily or permanently any contributor for other behaviors that they deem 46 | inappropriate, threatening, offensive, or harmful. 47 | 48 | ## Scope 49 | 50 | This Code of Conduct applies within all community spaces, and also applies when 51 | an individual is officially representing the community in public spaces. 52 | Examples of representing our community include using an official e-mail address, 53 | posting via an official social media account, or acting as an appointed 54 | representative at an online or offline event. 55 | 56 | ## Enforcement 57 | 58 | Instances of abusive, harassing, or otherwise unacceptable behavior may be 59 | reported to the community leaders responsible for enforcement at . 60 | All complaints will be reviewed and investigated promptly and fairly. 61 | 62 | All community leaders are obligated to respect the privacy and security of the 63 | reporter of any incident. 64 | 65 | ## Attribution 66 | 67 | This Code of Conduct is adapted from the [Contributor Covenant](https://contributor-covenant.org/) 68 | , version [1.4](https://www.contributor-covenant.org/version/1/4/code-of-conduct/code_of_conduct.md) 69 | and [2.0](https://www.contributor-covenant.org/version/2/0/code_of_conduct/code_of_conduct.md) 70 | , and was generated by [contributing-gen](https://github.com/bttger/contributing-gen). 71 | -------------------------------------------------------------------------------- /docs/container_setup/github_codespace/codespacestartstop.md: -------------------------------------------------------------------------------- 1 | #### How to Stop Codespaces? 2 | 3 | - To stop codespaces we just need to navigate to the Codespaces option in the 4 | bottom left of the Codespace panel. 5 | 6 | ![stop codespace](../../assets/rdev14.png) 7 | 8 | - After clicking on codespaces option we will get a drop down above something 9 | like this👇 10 | 11 | ![stop codespace](../../assets/rdev15.png) 12 | 13 | - Click on "Stop Current Codespace". It will stop the codespaces you are 14 | currently using or running. 15 | 16 | - You will be redirected to a Restart Codespaces page. The page shows a link to 17 | restart the codespace you just stopped. 18 | 19 | ![stop codespace](../../assets/rdev16.png) 20 | 21 | #### Idle timeout 22 | 23 | If you do not interact with the codespace, it will close automatically when it 24 | reaches the idle timeout limit. By default, this is 30 minutes, but you can [set 25 | a personal 26 | timeout](https://docs.github.com/en/codespaces/setting-your-user-preferences/setting-your-timeout-period-for-github-codespaces#setting-your-default-timeout-period) 27 | limit in your GitHub settings. 28 | 29 | The code changes and operations we have performed inside the codespace will 30 | still be inside the stopped codespace. If your codespace is stopped then you can 31 | restart it as shown below. 32 | 33 | #### How to Restart Codespaces again? 34 | 35 | - Go to [github.com/codespaces](https://github.com/codespaces) 36 | - Here we can see a list of the codespaces we have created ![stop 37 | codespace](../../assets/rdev17.png) 38 | - To restart it, we can just click on the codespaces we wanted to use and it 39 | will start the codespaces again for us. 40 | - You can also see an active label added to the codespaces we just started 41 | ![stop codespace](../../assets/rdev18.png) 42 | 43 | #### Managing and Sustaining Codespaces 44 | 45 | ##### Setting a Default Retention Period for Your Codespaces 46 | 47 | **Access Settings:** 48 | 49 | - Click your profile photo in the upper-right corner of any GitHub page. 50 | - Click "Settings." 51 | 52 | **Navigate to Codespaces Settings:** 53 | 54 | - In the sidebar, under "Code, planning, and automation," click "Codespaces." 55 | 56 | **Set Retention Period:** 57 | 58 | - Under "Default retention period," enter the number of days (between 0 and 30) 59 | for which you want your codespaces to be retained after they have been stopped. 60 | Example: Setting it to 30 days. ![retain 61 | codespace](../../assets/manage_codespace.png) 62 | 63 | **Warning:** 64 | 65 | - Setting the retention period to 0 days will result in immediate deletion of 66 | codespaces when stopped or when they timeout due to inactivity. For more 67 | details, refer to "Setting your timeout period for GitHub Codespaces." 68 | 69 | **Save Changes:** 70 | 71 | - Click "Save" to apply the new retention period. 72 | 73 | This allows you to customize how long your codespaces are kept before automatic 74 | deletion, balancing convenience and storage management. 75 | 76 | **Auto Delete Codespace:** 77 | 78 | - Go to the "Your codespaces" page at 79 | [github.com/codespaces](https://github.com/codespaces). 80 | - Find the codespace you want to exempt from deletion. 81 | - Click the options menu (three dots) to the right of the codespace. 82 | - Select "Auto Delete Codespace" from the dropdown menu. The bookmarked 83 | codespaces will not be auto-deleted. 84 | -------------------------------------------------------------------------------- /.github/README.md: -------------------------------------------------------------------------------- 1 | # R Dev Container 2 | 3 | ![Release](https://img.shields.io/github/v/release/r-devel/r-dev-env) 4 | 5 | The aim of the R Dev Container is to provide a standard environment for the 6 | exploration and development of the R source code. A prototype was developed 7 | under Google Summer of Code 2023 and development is continuing under Google 8 | Summer of Code 2024. 9 | 10 | ## Getting started 11 | 12 | ### Run in a web browser with GitHub Codespace 13 | 14 | Click on the button below followed by "Create Codespace" to create and enter 15 | your own web based containerised develoment environment. 16 | 17 | [![Open in GitHub 18 | Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=647768262&machine=premiumLinux&devcontainer_path=.devcontainer%2Fdevcontainer.json&location=WestUs2) 19 | 20 | The [Starting Codespace 21 | section](https://contributor.r-project.org/r-dev-env/container_setup/github_codespace/creating_codespace/) 22 | of the R Dev Container Docs will walk you through the process. Then you can work 23 | through the tutorials in the docs to lean how to use the codespace for R 24 | development. 25 | 26 | More details about GitHub codespaces can be found in the [GitHub Codespaces 27 | Docs](https://docs.github.com/en/codespaces/overview). GitHub currently offers 28 | up to 60 hours for free on dual core codespaces. 29 | 30 | [![Open in Gitpod](https://img.shields.io/badge/Gitpod-Open%20in%20Gitpod-blue?logo=gitpod&style=for-the-badge)](https://gitpod.io/github.com/r-devel/r-dev-env/tree/main) 31 | 32 | The [Starting Gitpod 33 | section](https://contributor.r-project.org/r-dev-env/container_setup/gitpod_workspace/workspacestart/) 34 | of the R Dev Container Docs will walk you through the process. Then you can 35 | work through the tutorials in the docs to lean how to use the codespace for R 36 | development. 37 | 38 | More details about Gitpod Workspaces can be found in the 39 | [Gitpod Workspace Docs](https://www.gitpod.io/docs/introduction). Gitpod 40 | currently offers Up to 896 cores, 12,000 GB RAM & GPUs in free tier. 41 | 42 | ### Run on your local computer 43 | 44 | The R Dev Container can also be run locally on your computer. Running the 45 | environment requires you to have Docker, VSCode, and the VSCode Dev Containers 46 | extension installed. Upon opening a copy of the [r-dev-env 47 | repository](https://github.com/r-devel/r-dev-env) in VSCode you will be prompted 48 | to start the dev container. 49 | 50 | The [Local setup 51 | section](https://contributor.r-project.org/r-dev-env/container_setup/local_setup/localsetup/) 52 | of the R Dev Container Docs will walk you through the process. Then you can 53 | work through the following the tutorials in the docs to learn how to use the 54 | codespace for R development. 55 | 56 | More information about Dev Containers can be found in the [Microsoft 57 | Documentation](https://code.visualstudio.com/docs/devcontainers/containers). 58 | 59 | ## Project Background 60 | 61 | The standard development process used by members of the R Core Team involves an 62 | iterative process of making changes to the source code, re-building R and 63 | exploring/testing the changes made. This process presents a big hurdle for new 64 | contributors to R, as setting up their system to build R can be non-trivial, 65 | requiring a lot of trouble-shooting, especially on Windows and macOS. On Linux 66 | and macOS, it is not straight-forward to work with different versions of R 67 | side-by-side and care needs to be taken not to corrupt or over-write the user's 68 | existing version of R/R packages. 69 | 70 | For these reasons, we propose to create containerized development environments 71 | for R. Our focus will be on creating a complete environment, including an IDE, 72 | that will provide a familiar space for R developers to work on contributions to 73 | base R. 74 | 75 | ## Contributors 76 | 77 | GSoC contributor: Atharva Shirdhankar 78 | 79 | Mentors: Heather Turner, James Tripp, Iain Emsley 80 | -------------------------------------------------------------------------------- /docs/container_setup/github_codespace/live_share.md: -------------------------------------------------------------------------------- 1 | Live Share is a powerful feature that allows you to collaborate with others in 2 | real time directly within VS Code/GitHub Codespaces. You can share your code, 3 | terminal, debugging sessions, and more with your collaborators. To use Live 4 | Share with the R Dev Container follow the guide below. 5 | 6 | !!! Note 7 | 8 | If you are using the R Dev Container locally you must have the Live Share Extension installed to start a Live Share Session. You will be asked to sign in using your Microsoft or GitHub account when starting the session. 9 | 10 | ### Start a Live Share Session 11 | 12 | 1. **Click the "Live Share" button** in the status bar. Alternatively you can 13 | go to Live Share extension tab and select from the options to share with 14 | read/write permission or share with read-only permission. ![alt 15 | text](../../assets/live-share.png) 16 | 17 | 2. **Share the Link**: A sharing link will be generated and copied to the 18 | clipboard for sharing with your collaborators. From the pop-up dialog, you can 19 | copy the link again or switch the permissions from read/write to read-only (or 20 | vice versa). ![alt text](../../assets/live-share2.png) 21 | 22 | ### Join a Live Share Session 23 | 24 | 1. **Receive the link** from the host. The link will be of the form 25 | `https://prod.liveshare.vsengsaas.visualstudio.com/join?[37 alphanumberic 26 | characters]` 27 | 2. **Choose how to join the session:** 28 | 29 | - **Open the link in a web browser**: click the link to open it in your web 30 | browser. If you have VS Code installed locally, a pop-up dialog will give 31 | you the choice of continuing in the web or opening the session in VS 32 | Code. You can join the session anonymously or sign in with your Microsoft 33 | or GitHub account. 34 | - **Copy the link into VSCode or the R Dev Container Codespace**: From the 35 | Live share extension tab, click the "Join" button. If you are using VS Code 36 | locally, you can choose to join the session anonymously or sign in with your 37 | Microsoft or GitHub account. If you are using the Codespace, you will already be 38 | signed in with your GitHub account. A pop-up at the top of the VSCode window 39 | will ask for the Live Share session link. Paste the link and click 'Enter'. 40 | ![alt text](../../assets/live-share3.png). 41 | 42 | 3. **Wait to be accepted by the host**. The host will receive a pop-up message 43 | where they can accept your request to join. 44 | 45 | ### Collaborate in Real-Time 46 | 47 | Once joined, you can: 48 | 49 | - **Edit Code Together**: Both the host and guests can edit files, and changes 50 | will be synchronized in real-time. 51 | - **Share Terminals**: The host can share bash or R terminals. Guests can see 52 | the terminal output and, if granted permission, type commands. 53 | - **Live Chat**: Session chat can be opened from the Live share extension tab. 54 | ![alt text](../../assets/live-share6.png) ![alt 55 | text](../../assets/live-share5.png) 56 | 57 | ### Manage control 58 | 59 | 1. **Manage permissions**: In a session with read/write permissions, the host 60 | can change permissions for each shared terminal by right-clicking the 61 | terminal name on the Live Share tab. 62 | 2. **Follow Mode**: Both the host and guests can enable "Follow Mode" to follow 63 | each other’s cursor and view. 64 | 65 | ### Session persistance 66 | 67 | You can rejoin a session if disconnected, and your previous state will be 68 | restored. 69 | 70 | ### Close a Live Share Session 71 | 72 | When you want to close the live share session, you can go to Live Share 73 | Extension tab and click on stop icon. ![alt 74 | text](../../assets/live-share4.png). 75 | 76 | If you are a guest, the live share session will continue to run without you. If 77 | you are the host this will close the session for everyone. 78 | 79 | Alternatively, you can click the "Live Share" button in the status bar to leave 80 | or stop the session. 81 | 82 | ### Tips for Effective Collaboration 83 | 84 | - **Use Voice/Video Chat**: Combine Live Share with a voice or video call (e.g., 85 | Zoom, Teams, etc.) for better communication. 86 | - **Share Comments**: Use comments in the code to communicate specific points or 87 | suggestions. 88 | -------------------------------------------------------------------------------- /docs/tutorials/building_r.md: -------------------------------------------------------------------------------- 1 | 2 | **1) Environment variables** 3 | 4 | - We have environment variables defining paths to directories for building R and 5 | storing the source code. 6 | - `BUILDDIR` defines the build directory: `/workspaces/r-dev-env/build/r-devel`. 7 | - `TOP_SRCDIR` defines the source directory: `/workspaces/r-dev-env/svn/r-devel` 8 | - The environment variables are set in the codespace image and are available 9 | when the codespace starts. 10 | 11 | ![alt text](../assets/rdev6.png) 12 | 13 | **2) svn checkout** 14 | 15 | - The svn checkout command lets us create a local copy of a specific tag/branch 16 | of a repository. 17 | - We can check out the latest version of the trunk (the main branch) of the R 18 | sources to $TOP_SRCDIR as follows: 19 | 20 | ```bash 21 | svn checkout https://svn.r-project.org/R/trunk/ $TOP_SRCDIR 22 | ``` 23 | 24 | - Output : We get file structure something like this after checking out R source 25 | code from R svn repository. 26 | 27 | ![alt text](../assets/rdev8.png) 28 | 29 | **3) Download recommended packages for R** 30 | 31 | To build R with the recommended packages, we need to run the 32 | `tools/rsync-recommended` script from the source directory to download the 33 | source code for these packages: 34 | 35 | ```bash 36 | $TOP_SRCDIR/tools/rsync-recommended 37 | ``` 38 | 39 | ![alt text](../assets/rdev9.png) 40 | 41 | **4) Change to the build directory** 42 | 43 | - To keep the source directory clean, we change to a build directory to 44 | configure and build R. 45 | 46 | - First create the directory specified by the BUILDDIR environment variable. 47 | 48 | ```bash 49 | mkdir -p $BUILDDIR 50 | ``` 51 | 52 | - Then we can change directory from root to the build directory. 53 | 54 | ```bash 55 | cd $BUILDDIR 56 | ``` 57 | 58 | **5) Configure the build** 59 | 60 | - After we change directory, we must run the configure script from the source 61 | directory. This step takes ~1 minute on the codespace. 62 | 63 | ```bash 64 | $TOP_SRCDIR/configure --with-valgrind-instrumentation=1 65 | 66 | ``` 67 | 68 | 69 | !!! Note 70 | The `--with-valgrind-instrumentation` option is set to 1 for effective use 71 | of valgrind. See the [Using 72 | valgrind](https://cran.r-project.org/doc/manuals/R-exts.html#Using-valgrind) 73 | section of the R-admin manual for more information. 74 | 75 | 76 | - The configure cmd prepares for building R, creating files and folders inside 77 | the BUILDDIR directory. 78 | - Output : We get file structure something like this after using configure 79 | command. 80 | 81 | ![alt text](../assets/rdev7.png) 82 | 83 | **6) Build R** 84 | 85 | Having configured R, we run `make` to build R. This take 5-10 minutes on the 86 | codespace. 87 | 88 | ```bash 89 | make 90 | ``` 91 | 92 | **7) Check R** 93 | 94 | Check that the build of R passes R's standard checks: 95 | 96 | ```bash 97 | make check 98 | ``` 99 | 100 | This takes a couple of minutes in the codespace. The check will stop with a 101 | error message if any of the tests fail. If this happens, see [SVN 102 | Help](./svn_help.md) for how to revert to a version that passes check. 103 | 104 | **8) Make R terminals use the built R** 105 | 106 | Run the `which_r` script to set which R to use for R terminals in VSCode. When 107 | prompted, enter the number corresponding to `r-devel` 108 | 109 | ```bash 110 | which_r 111 | ``` 112 | 113 | ```bash 114 | Which version of R should be used in new R terminals? 115 | 1. R 4.4.0 (release version built into this container) 116 | Additional R builds available: 117 | 2. r-devel 118 | Enter the number corresponding to the selected version: 119 | ``` 120 | 121 | This means that new R terminals will use the version of R you have just 122 | built![^1] 123 | 124 | [^1]: To switch back to the release version, run `which_r` and type `1`. The 125 | selected version is saved in the VSCode settings, so will be saved when you stop 126 | and restart the codespace. 127 | 128 | **9) Make contributions** 129 | 130 | - After having built the current development version of R, we can now make 131 | changes to the source code and contribute to the project. 132 | - Follow the [R Contribution Workflow](./contribution_workflow.md) tutorial to 133 | learn how to do this. 134 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | 2 | # Contributing to the R Dev Container 3 | 4 | First off, thanks for taking the time to contribute! ❤️ 5 | 6 | All types of contributions are encouraged and valued. See the [Table of 7 | Contents](#table-of-contents) for different ways to help and details about how 8 | this project handles them. Please make sure to read the relevant section before 9 | making your contribution. It will make it a lot easier for us maintainers and 10 | smooth out the experience for all involved. The community looks forward to your 11 | contributions. 🎉 12 | 13 | > And if you like the project, but just don't have time to contribute, that's 14 | > fine. There are other easy ways to support the project and show your 15 | > appreciation, which we would also be very happy about: 16 | > 17 | > - Star the project 18 | > - Tweet about it 19 | > - Refer this project in your project's readme 20 | > - Mention the project at local meetups and tell your friends/colleagues 21 | 22 | 23 | ## Table of Contents 24 | 25 | 26 | - [Code of Conduct](#code-of-conduct) 27 | - [I Have a Question](#i-have-a-question) 28 | - [I Want To Contribute](#i-want-to-contribute) 29 | - [Reporting Bugs](#reporting-bugs) 30 | - [Suggesting Enhancements](#suggesting-enhancements) 31 | - [Your First Code Contribution](#your-first-code-contribution) 32 | - [Improving The Documentation](#improving-the-documentation) 33 | - [Styleguides](#styleguides) 34 | - [Commit Messages](#commit-messages) 35 | - [Join The Project Team](#join-the-project-team) 36 | 37 | 38 | ## Code of Conduct 39 | 40 | This project and everyone participating in it is governed by the [R Dev 41 | Container Code of 42 | Conduct](https://github.com/r-devel/r-dev-env/blob/master/CODE_OF_CONDUCT.md). 43 | By participating, you are expected to uphold this code. Please report 44 | unacceptable behavior to . 45 | 46 | ## I Have a Question 47 | 48 | > If you want to ask a question, we assume that you have read the available 49 | > documentation. 50 | 51 | Before you ask a question, it is best to search for existing 52 | [Issues](https://github.com/r-devel/r-dev-env/issues) that might help you. In 53 | case you have found a suitable issue and still need clarification, you can write 54 | your question in this issue. It is also advisable to search the internet for 55 | answers first. 56 | 57 | If you then still feel the need to ask a question and need clarification, we 58 | recommend the following: 59 | 60 | - Open an [Issue](https://github.com/r-devel/r-dev-env/issues/new). 61 | - Provide as much context as you can about what you're running into. 62 | - Provide project and platform versions (nodejs, npm, etc), depending on what 63 | seems relevant. 64 | 65 | We will then take care of the issue as soon as possible. 66 | 67 | 82 | 83 | ## I Want To Contribute 84 | 85 | > ### Legal Notice 86 | > 87 | > When contributing to this project, you must agree that you have authored 100% 88 | > of the content, that you have the necessary rights to the content and that the 89 | > content you contribute may be provided under the project license. 90 | 91 | ### Reporting Bugs 92 | 93 | 94 | #### Before Submitting a Bug Report 95 | 96 | A good bug report shouldn't leave others needing to chase you up for more 97 | information. Therefore, we ask you to investigate carefully, collect information 98 | and describe the issue in detail in your report. Please complete the following 99 | steps in advance to help us fix any potential bug as fast as possible. 100 | 101 | - Make sure that you are using the latest version. 102 | - Determine if your bug is really a bug and not an error on your side e.g. using 103 | incompatible environment components/versions (Make sure that you have read the 104 | documentation. 105 | - To see if other users have experienced (and potentially already solved) the 106 | same issue you are having, check if there is not already a bug report existing 107 | for your bug or error in the [bug 108 | tracker](https://github.com/r-devel/r-dev-env/issues?q=label%3Abug). 109 | 110 | 111 | #### How Do I Submit a Good Bug Report? 112 | 113 | > You must never report security related issues, vulnerabilities or bugs 114 | including sensitive information to the issue tracker, or elsewhere in 115 | public. Instead sensitive bugs must be sent by email to 116 | . 118 | 119 | We use GitHub issues to track bugs and errors. If you run into an issue with the 120 | project: 121 | 122 | - Open an [Issue](https://github.com/r-devel/r-dev-env/issues/new). (Since we 123 | can't be sure at this point whether it is a bug or not, we ask you not to talk 124 | about a bug yet and not to label the issue.) 125 | - Explain the behavior you would expect and the actual behavior. 126 | - Please provide as much context as possible and describe the *reproduction 127 | steps* that someone else can follow to recreate the issue on their own. This 128 | usually includes your code. For good bug reports you should isolate the 129 | problem and create a reduced test case. 130 | - Provide the information you collected in the previous section. 131 | 132 | 135 | 136 | ### Suggesting Enhancements 137 | 138 | This section guides you through submitting an enhancement suggestion for the R 139 | Dev Container, **including completely new features and minor improvements to 140 | existing functionality**. Following these guidelines will help maintainers and 141 | the community to understand your suggestion and find related suggestions. 142 | 143 | 144 | #### Before Submitting an Enhancement 145 | 146 | - Make sure that you are using the latest version. 147 | - Read the documentation carefully and find out if the functionality is already 148 | covered, maybe by an individual configuration. 149 | - Perform a [search](https://github.com/r-devel/r-dev-env/issues) to see if the 150 | enhancement has already been suggested. If it has, add a comment to the 151 | existing issue instead of opening a new one. 152 | - Find out whether your idea fits with the scope and aims of the project. It's 153 | up to you to make a strong case to convince the project's developers of the 154 | merits of this feature. Keep in mind that we want features that will be useful 155 | to the majority of our users and not just a small subset. 156 | 157 | 158 | #### How Do I Submit a Good Enhancement Suggestion? 159 | 160 | Enhancement suggestions are tracked as [GitHub 161 | issues](https://github.com/r-devel/r-dev-env/issues). 162 | 163 | - Use a **clear and descriptive title** for the issue to identify the 164 | suggestion. 165 | - Provide a **step-by-step description of the suggested enhancement** in as many 166 | details as possible. 167 | - **Describe the current behavior** and **explain which behavior you expected to 168 | see instead** and why. At this point you can also tell which alternatives do 169 | not work for you. 170 | - You may want to **include screenshots and animated GIFs** which help you 171 | demonstrate the steps or point out the part which the suggestion is related 172 | to. You can use [this tool](https://www.cockos.com/licecap/) to record GIFs on 173 | macOS and Windows, and [this tool](https://github.com/colinkeenan/silentcast) 174 | or [this tool](https://github.com/GNOME/byzanz) on Linux. 176 | - **Explain why this enhancement would be useful** to most R Dev Container 177 | users. You may also want to point out the other projects that solved it better 178 | and which could serve as inspiration. 179 | 180 | 183 | 184 | 185 | ## Attribution 186 | 187 | This guide is based on the **contributing-gen**. [Make your 188 | own](https://github.com/bttger/contributing-gen)! 189 | --------------------------------------------------------------------------------