Merge remote-tracking branch 'origin/devel' into docs/lldb

hturner · hturner · commit 30a7490f2096 · 2025-12-10T11:15:17.000+13:00
diff --git a/.Rprofile b/.Rprofile
@@ -9,6 +9,27 @@
 # .libPaths() already includes site library for default R version.
 .libPaths(c(.libPaths(), .Library.site))
 
+# Source initialization script for VSCode R extension
+source("~/.vscode-R/init.R")
+.First.sys()
+
+# The remotes package is installed to install httpgd from GitHub
+# The gdiff package is installed to support visual difference testing
+
+# Configure r-universe for binary package installations dynamically
+linux_binary_repo <- function(universe){
+  runiverse <- sprintf('r-universe.dev/bin/linux/%s-%s/%s/',
+                       system2('lsb_release', '-sc', stdout = TRUE),
+                       R.version$arch,
+                       substr(getRversion(), 1, 3))
+  sprintf('https://%s.%s', universe, runiverse)
+}
+
+# Set repos for CRAN to use r-universe linux binaries
+options(repos = c(
+  cran = linux_binary_repo("cran")
+))
+
 # For PNG graphics uncomment following lines
 # options(vsc.use_httpgd = FALSE,
 #         vsc.dev.args = list(width = 800, height = 600))
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
@@ -1,6 +1,8 @@
 {
     "name": "R-Dev-Env",
     "image": "ghcr.io/r-devel/r-dev-env:devel",
+    "runArgs": ["--cap-add=SYS_PTRACE"],
+    "remoteUser": "vscode",
     "hostRequirements": {
         "cpus": 4
     },
@@ -9,7 +11,6 @@
             "settings": {
                 "git.ignoredRepositories": ["."],
                   "files.exclude": {
-                       "**/.vscode": true,
                        "**/.devcontainer": true,
                        "**/.git": true,
                        "**/.github": true,
@@ -43,9 +44,10 @@
                 "johnstoncode.svn-scm",
                 "ms-vscode.cpptools",
                 "MS-vsliveshare.vsliveshare",
-                "natqe.reload"
+                "natqe.reload",
+                "vadimcn.vscode-lldb"
             ]
         }
     },
-    "postCreateCommand": "find . -wholename '*.git*'  -type d -prune -o -type f -exec chown vscode:vscode {} \\; && sh /workspaces/r-dev-env/scripts/localscript.sh"
+    "postCreateCommand": "bash ./scripts/localscript.sh"
 }
diff --git a/.devcontainer/launch.json b/.devcontainer/launch.json
@@ -0,0 +1,12 @@
+{
+"version": "0.2.0",
+"configurations": [
+    {
+      "name": "(lldb) Attach to R",
+      "type": "lldb",
+      "request": "attach",
+      "pid": "${command:pickMyProcess}",
+      "stopOnEntry": false
+    }
+  ]
+}
diff --git a/.gitignore b/.gitignore
@@ -1,8 +1,9 @@
-R-4.1.3/
-R-4.1.3.tar.gz
-R-devel/
-R-devel.tar.gz
+/build
+/svn
 /venv
 .cache/
-.Rproj.user
 .vscode/
+.Rhistory
+.Rproj.user
+*.Rproj
+*/allow_ptrace
diff --git a/Dockerfile b/Dockerfile
@@ -8,6 +8,7 @@ RUN sed -i.bak "/^#.*deb-src.*universe$/s/^# //g" /etc/apt/sources.list \
       software-properties-common \
       subversion \
       libmagick++-dev \
+      libpoppler-cpp-dev \
     && add-apt-repository --enable-source --yes "ppa:marutter/rrutter4.0" \
     && wget -qO- https://cloud.r-project.org/bin/linux/ubuntu/marutter_pubkey.asc | tee -a /etc/apt/trusted.gpg.d/cran_ubuntu_key.asc \
     && apt-get update \
@@ -22,11 +23,14 @@ RUN Rscript -e "runiverse <- sprintf('r-universe.dev/bin/linux/%s-%s/%s/', \
                                  R.version\$arch, \
                                  substr(getRversion(), 1, 3)); \
                 print('Installing packages...'); \
-                install.packages(c('languageserver', 'httpgd'), \
-                 repos = c(runiverse = paste0('https://cran.', runiverse), \
-                           nx10 = paste0('https://nx10.', runiverse))); \
+                install.packages(c('languageserver', 'gdiff', 'remotes'), \
+                 repos = c(runiverse = paste0('https://cran.', runiverse))); \
+                print('Installing httpgd from GitHub...'); \
+                remotes::install_github('nx10/httpgd'); \
                 print('Packages installed.')"
 
 # Define env var used in GitHub Actions that build and deploy container
 ARG CONTAINER_VERSION
 ENV CONTAINER_VERSION=${CONTAINER_VERSION}
+
+USER vscode
diff --git a/INIT b/INIT
diff --git a/docs/assets/rdev3_5.png b/docs/assets/rdev3_5.png
diff --git a/docs/container_setup/github_codespace/creating_codespace.md b/docs/container_setup/github_codespace/creating_codespace.md
@@ -20,3 +20,32 @@ GitHub Codespaces' button and then click the green 'Create Codespace' button.
 
 3. You will be taken to a VS Code editor within your browser.
 ![codespace](../../assets/rdev3.png)
+
+4. Rename your codespace and manage auto-delete for easier identification and to
+   prevent accidental removal:
+
+    By default, your codespace will have a randomly generated name. Renaming it to
+    something descriptive — such as referencing the issue or feature you’re working
+    on makes it much easier to manage your codespaces. You can also disable
+    auto-delete to ensure your codespace isn't removed unexpectedly:
+
+    - Open your [GitHub Codespaces dashboard](https://github.com/codespaces)
+    (<https://github.com/codespaces>) in your browser.
+    - Find the codespace you just created (it will show the repository name and
+    the current random display name).
+    - A: Click the ellipsis (**...**) next to your codespace to open the
+    options menu.
+    - B: Select **Rename** from the dropdown.
+    - Enter a descriptive new display name, e.g.,
+    `Bug 7084 - text() recycling problems` or
+    `Ignore deprecated/defunct fns in checkS3methods`, and confirm.
+    - C: In the same options menu, click on **Auto-delete codespace** to toggle
+     off auto-delete (remove the check mark). This will prevent the
+     codespace from being deleted automatically.
+
+    ![rename codespace](../../assets/rdev3_5.png)
+
+    !!! Tip
+
+        You can rename your codespace at any time. The display name is
+        for your convenience and **does not** affect your code or environment.
diff --git a/docs/container_setup/local_setup/localsetup.md b/docs/container_setup/local_setup/localsetup.md
@@ -1,64 +1,75 @@
-!!! note Local setup is not recommended on macOS or Windows as the Docker
+!!! note
+    Local setup is not recommended on macOS or Windows as the Docker
     container will work via a Virtual Machine and building R will take far
     longer (e.g. a full build may take 1 hour vs 10 minutes!).
 
 We can also use this codespace locally. For that we need to have some
 prerequisites installed.
 
-#### > Prerequisites
+#### Prerequisites
 
 1. Docker Engine or Docker Desktop. You can find the docker desktop install
    instructions on [Docker Desktop
    Docs](https://www.docker.com/products/docker-desktop/).
 2. VSCode Editor. You can download and install from [VSCode
    website](https://code.visualstudio.com/download).
 
-#### > Steps to run R Development Container locally
+#### Steps to run R Development Container locally
 
 1. Clone the [R Dev Container Github
    repo](https://github.com/r-devel/r-dev-env/)
+
 2. In a terminal, change directory to r-dev-env
 
-```bash
-cd r-dev-env
-```
+      ```bash
+      cd r-dev-env
+      ```
 
 3. Restart VSCode in the `r-dev-env` directory with the command:
 
-```bash
-code .
-```
+      ```bash
+      code .
+      ```
 
 4. Checkout the main branch and pull the latest changes
 
-```bash
-git checkout main
-git pull
-```
+      ```bash
+      git checkout main
+      git pull
+      ```
 
-The main branch provides the stable release. If you require an in-development
-feature, use the devel branch instead.
+      The main branch provides the stable release. If you require an in-development
+      feature, use the devel branch instead.
 
 5. After this step please be sure that your docker engine is started. If you
    have installed Docker Desktop just open the Docker Desktop app the engine
    starts automatically and if you are using just docker engine make sure to
    start it with the following command
 
-```bash
-systemctl start docker
-```
+      ```bash
+      systemctl start docker
+      ```
 
 6. We can see pop-up at the bottom right of the VSCode editor which says reopen
-in Dev Container.  Click on `Reopen in DevContainer` button.  ![start
-localsetup](../../assets/rdev13.png)
+in Dev Container.
+Click on `Reopen in Container` button.
+
+    ![startlocalsetup](../../assets/rdev13.png)
 
 7. After clicking on that button we will see our container is getting ready. It
 will take some time. So till that time you can have coffee :) ![start
 localsetup](../../assets/rdev24.png)
+
 8. We can also test whether the dev container is working or not by just printing
-the environment variables mentioned in the welcome message on the terminal. And
-there we go!!! We have setup our R Dev Container locally.  ![start
-localsetup](../../assets/rdev25.png)
+the environment variables mentioned in the welcome message on the terminal.
+
+      ```console
+      $ echo $BUILDDIR
+      /workspaces/r-dev-env/bin/R
+      ```
+
+      And there we go!!! We have setup our R Dev Container locally.  ![start
+      localsetup](../../assets/rdev25.png)
 
 9. The container will be closed when you close VSCode. To reopen the container,
    open the `r-dev-env` directory in VSCode.
diff --git a/docs/css/custom.css b/docs/css/custom.css
@@ -0,0 +1,37 @@
+/* customise CSS for bash code chunks and bash sessions ("console") */
+
+/* .gp = Generic Prompt (e.g., shell prompt like $ or >) */
+/* default: var(--md-code-hl-generic-color); */
+/* prompts treated as normal code in bash code chunks */
+.language-console.highlight code span.gp{
+  color: #7aa2cd;
+}
+
+/* .go = Generic output: output from a command */
+/* default: var(--md-code-hl-generic-color); */
+.language-console.highlight code span.go,
+.language-bash.highlight code span.go {
+  color: var(--md-code-hl-generic-color);
+}
+
+/* .nb = Built-in name like print, echo */
+/* default: var(--md-code-hl-constant-color); */
+.language-console.highlight code span.nb,
+.language-bash.highlight code span.nb {
+  color: var(--md-code-hl-constant-color);
+}
+
+/* .nv = Named variables like $BUILDDIR */
+/* default: var(--md-code-hl-variable-color); */
+/* use same as normal text: var(--md-code-fg-color); */
+.language-console.highlight code span.nv,
+.language-bash.highlight code span.nv {
+  color: var(--md-code-fg-color);
+}
+
+/* .c1 = Built-in name like print, echo */
+/* default: var(--md-code-hl-comment-color); */
+.language-console.highlight code span.c1,
+.language-bash.highlight code span.c1 {
+  color: var(--md-code-hl-comment-color);
+}
diff --git a/docs/tutorials/building_r.md b/docs/tutorials/building_r.md
@@ -61,8 +61,7 @@ cd $BUILDDIR
 directory.  This step takes ~1 minute on the codespace.
 
 ```bash
-$TOP_SRCDIR/configure --with-valgrind-instrumentation=1
-
+$TOP_SRCDIR/configure --with-valgrind-instrumentation=1 CFLAGS="-g -O0"
 ```
 
 <!-- markdownlint-disable MD046 -->
@@ -71,6 +70,9 @@ $TOP_SRCDIR/configure --with-valgrind-instrumentation=1
     of valgrind. See the [Using
     valgrind](https://cran.r-project.org/doc/manuals/R-exts.html#Using-valgrind)
     section of the R-admin manual for more information.
+    The `CFLAGS="-g -O0"` setting compiles C code with debugging symbols
+    (`-g`) and disables optimization (`-O0`) so the compiled code closely
+    matches the original source, which aids debugging.
 <!-- markdownlint-enable MD046 -->
 
 - The configure cmd prepares for building R, creating files and folders inside
diff --git a/docs/tutorials/running_r.md b/docs/tutorials/running_r.md
@@ -31,4 +31,8 @@ Click on the `R:(not attached)` link to launch an R terminal.
 3) You can then send code from the `.R` file to the R terminal by pressing
 `cmd/ctrl + enter`.
 
+```R
+hist(rnorm(1000))
+```
+
 ![alt text](../assets/rdev5.png)
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -59,6 +59,9 @@ theme:
       primary: indigo
       accent: blue
 
+extra_css:
+  - css/custom.css
+
 plugins:
   - social
   - search
@@ -72,6 +75,8 @@ extra:
 
 markdown_extensions:
   - pymdownx.highlight:
+      use_pygments: true
+      pygments_lang_class: true
       anchor_linenums: true
   - pymdownx.inlinehilite
   - pymdownx.snippets
diff --git a/scripts/allow_ptrace.c b/scripts/allow_ptrace.c
@@ -0,0 +1,16 @@
+#include <sys/prctl.h>
+#include <unistd.h>
+#include <stdio.h>
+
+int main(int argc, char **argv) {
+    if (argc < 2) {
+        fprintf(stderr, "usage: %s <path-to-R> [args...]\n", argv[0]);
+        return 2;
+    }
+    /* allow ptrace for this process (persists across exec) */
+    prctl(PR_SET_PTRACER, PR_SET_PTRACER_ANY);
+    /* exec the provided R binary with the remaining args */
+    execv(argv[1], &argv[1]);
+    perror("execv");
+    return 1;
+}
diff --git a/scripts/launch_r.sh b/scripts/launch_r.sh
@@ -0,0 +1,4 @@
+#!/bin/bash
+
+# `which_r.sh` sets the R binary used in the command below
+exec ./scripts/allow_ptrace /usr/bin/R "$@"
diff --git a/scripts/localscript.sh b/scripts/localscript.sh
@@ -27,11 +27,28 @@ cat $WORK_DIR/scripts/welcome_msg.sh >> ~/.bashrc
 # Remove git directory if it exists
 #rm -rf .git
 
+# copy launch.json for debugging config if present
+if [ -f "$WORK_DIR/.devcontainer/launch.json" ]; then
+    cp "$WORK_DIR/.devcontainer/launch.json" "$VSCODE_DIR/launch.json"
+fi
+
 # copying vscode extension settings from devcontainer json to vscode settings json using jq
 if [ -f "$DEVCONTAINER_JSON" ]; then
         jq '.customizations.vscode.settings' "$DEVCONTAINER_JSON" > "$VSCODE_DIR/settings.json"
 fi
 
+# Update r.rterm.linux setting to use the launch_r.sh script with full dynamic path
+if [ -f "$VSCODE_DIR/settings.json" ]; then
+    tmpfile="${VSCODE_DIR/settings.json}.tmp.$$"
+    jq --arg rterm "$WORK_DIR/scripts/launch_r.sh" '."r.rterm.linux"=$rterm' "$VSCODE_DIR/settings.json" > "$tmpfile" && mv "$tmpfile" "$VSCODE_DIR/settings.json"
+fi
+
+# Compile the ptrace helper executable
+gcc -O2 -o "$WORK_DIR/scripts/allow_ptrace" "$WORK_DIR/scripts/allow_ptrace.c"
+chmod +x "$WORK_DIR/scripts/allow_ptrace"
+
+# Mark the wrapper executable
+chmod +x "$WORK_DIR/scripts/launch_r.sh"
 
 }
 
diff --git a/scripts/welcome_msg.sh b/scripts/welcome_msg.sh
diff --git a/scripts/which_r.sh b/scripts/which_r.sh
