Chapter 6 Developer Software Guide

This section describes the software you will need to contribute to this project. This is in addition to the software dependencies described in the user installation guide which you should ensure are installed first.

6.0.1 git

You will need git installed locally, and you may prefer to use an additional git GUI client such as GitKraken or GitHub Desktop. If your preferred git client is the RStudio IDE, you can configure Git and RStudio integration following these instructions.

To install git, please follow the instructions on this page for your operating system. You can find the downloads for your operating system on the left-hand navigation bar on that page.

6.0.2 Development environment

An integrated development environment is recommended to organize code files, outputs, and build and debug environments. The most popular IDEs on the development team are RStudio and Visual Studio Code. You are welcome to use another IDE or a text-editor based workflow if you strongly prefer that.

6.0.3 vscode setup

Please follow the instructions here to set up vscode for use with R.

For those migrating from R studio to VS code, this post on migrating to VS code may be helpful.

In addition to those instructions, you may need to install the vscDebugger package here using the command:

remotes::install_github("ManuelHentschel/vscDebugger")

To improve the plot viewer when creating plots in R, install the httpgd package:

install.packages("httpgd")

To add syntax highlighting and other features to the R terminal, radian can be installed. Note needs to be installed first in order to download radian.

A number of optional settings that could be added to the user settings (settings.json) file in vscode to improve the usability of R in VS code.

For example, the settings for interacting with R terminals can be adjusted.

Here are some that you may want to use with FIMS:

{
    // Associate .RMD files with markdown:
    "files.associations": {
        "*.Rmd": "markdown",
    },
    // A cmake setting
    "cmake.configureOnOpen": true, 
    // Set where the rulers are, needed for Rewrap. 72 is the default we have
    // decided on for FIMS repositories.z
    "editor.rulers": [
        72
    ],
    // Should the editor suggest inline edits?
    "editor.inlineSuggest.enabled": true,
    // Settings for github copilot and which languages to use it with or not.
    "github.copilot.enable": {
        "*": true,
        "yaml": false,
        "plaintext": false,
        "markdown": false,
        "latex": false,
        "r": false
    }, 
    // Setting for sending R code from the editor to the terminal
    "r.alwaysUseActiveTerminal": true,
    // Needed to send large chunks of code to the r terminal when using radian
    "r.bracketedPaste": true,
    // Needed to use httpgd for plotting in vscode
    "r.plot.useHttpgd": true,
    // path to the r terminal (in this case, radian). Necessary to get the terminal to use radian.
    "r.rterm.windows": "C://Users//my.name//AppData//Local//Programs//Python//Python310//Scripts//radian.exe", //Use this only for Windows 
    // options for the r terminal
    "r.rterm.option": [
        "--no-save",
        "--no-restore",
        "max.print=500"
    ],
    // Setting for whether to allow linting of documents or not
    "r.lsp.diagnostics": true,
    // When looking at diffs under the version control tab, should whitspace be ignored?
    "diffEditor.ignoreTrimWhitespace": false,
    // What is the max number of lines that are printed as output to the terminal?
    "terminal.integrated.scrollback": 10000
}

Some suggested R shortcuts could be helpful.

To set up C++ with vscode, instructions are here.

Other helpful extensions that can be found in the VScode marketplace are: - Github Copilot: An AI tool that helps with line completion - Live Share: Collaborate on the same file remotely with other developers - Rewrap: Helps rewrapping comments and text lines at a specified character count. Note that to get it working it will be necessary to add rulers - There are a number of keymap packages that import key mappings from commonly used text editors (e.g., Sublime, Notepad++, atom, etc.). Searching “keymap” in the marketplace should help find these. - GitLens (or GitLess): Adds more Git functionality. Note that some of the GitLens functionality is not free, and GitLess is a fork before the addition of these premium features.

Note that the keybindings.json and settings.json could be copied from one computer to another to make it easier to set up VS code with the settings needed. Note that the settings.json location differs depending on the operating system.

Typically, it is good practice to not restore old sessions after shutting down the IDE. To avoid restoring old sessions in the VS Code terminals (including R terminal), in the Setting User Interface within VS Code (get to this by opening the command palette and searching for Preferences: Open Settings (UI)), under Features > Terminal, uncheck the option “Enable Persistent Sessions.”

Rstudio addins can be accessed by searching for Rstudio addin in the command palette. Clicking on “R: Launch Rstudio Addin” should provide a list of addin options.

6.0.4 C++ compiler

Windows users who installed Rtools should have a C++ compiler (gcc) as part of the bundle. To ensure the C++ compiler is on your path, open a command prompt and type gcc. If you get the below message, you are all set:

gcc: fatal error: no input files compilation
terminated.

If not, you will need to check that the compiler is on the path. The easiest way to do so is by creating a text file .Renviron in your Documents folder which contains the following line:

PATH="${RTOOLS40_HOME}\usr\bin;${PATH}"

You can do this with a text editor, or from R like so (note that in R code you need to escape backslashes):

write('PATH="${RTOOLS40_HOME}\\usr\\bin;${PATH}"', file = "~/.Renviron", append = TRUE)

Restart R, and verify that make can be found, which should show the path to your Rtools installation.

Sys.which("make") ##
"C:\\rtools40\\usr\\bin\\make.exe"

6.0.5 GoogleTest

You will need to install CMake and ninja and validate you have the correct setup by following the steps outlined in the test case template.

6.0.6 GDB debugger

Windows users who use GoogleTest may need GDB debugger to see what is going on inside of the program while it executes, or what the program is doing at the moment it crashed. rtools40 includes the GDB debugger. The steps below help install 64-bit version gdb.exe.

  • Open Command Prompt and type gdb. If you see details of usage, GDB debugger is already in your PATH. If not, follow the instructions below to install GDB debugger and add it to your PATH.
  • Install Rtools following the instructions here
  • Open ~/rtools40/mingw64.exe to run commands in the mingw64 shell. Run command pacman -Sy mingw-w64-x86_64-gdb to install 64-bit version (more information can be found in R on Windows FAQ)
  • Type Y in the mingw64 shell to proceed with installation
  • Check whether ~/rtools40/mingw64/bin/gdb.exe exists or not
  • Add rtools40 to the PATH and you can check that the path is working by running which gdb in a command window