Chapter 6 Developer Software and Installation Guide

This section describes the software you will need to contribute to this project as well as ways FIMS can be installed.

6.1 Codespaces as an alternative to installing software

An alternative to setting up this software locally is using GitHub Codespaces.

The FIMS repository already has a file to set up all of the needed software, so there is no need to install anything locally.

To start a codespace on the FIMS repository, follow the GitHub documentation for creating a Codespace.

6.2 Software to Install

6.2.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.2.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.2.3 vscode setup

Install Visual Studio Code and configure it for using R.

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

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.2.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="${RTOOLS44_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="${RTOOLS44_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:\\rtools44\\usr\\bin\\make.exe"

6.2.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.2.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. rtools44 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 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 ~/rtools44/mingw64/bin/gdb.exe exists or not
  • Add rtools44 to the PATH and you can check that the path is working by running which gdb in a command window

6.2.7 Doxygen

To build C++ documentation website for FIMS, a documentation generator Doxygen needs to be installed. Doxygen automates the generation of documentation from source code comments. To install Doxygen, please follow the instructions here to install Doxygen on various operating systems. Below are steps to install 64-bit version of Doxygen 1.11.0 on Windows.

  • Download doxygen-1.11.0.windows.x64.bin.zip and extract the applications to Documents\Apps\Doxygen or other preferred folder.

  • Add Doxygen to the PATH by following similar instructions here.

  • Open a command window and run where doxygen to check if Doxygen is added to the PATH.

  • Two commands on the command line are needed to generate C++ documentation for FIMS locally:

cmake -S. -B build -G Ninja
cmake -- build build

6.2.8 R Installation Requirements

The following is needed: - R version 4.0.0 or newer (or RStudio version 1.2.5042 or newer) - the devtools R package - TMB version 1.8.0 or newer (install instructions) - For windows users: Rtools4 (available on the CRAN website)

6.3 Installing FIMS

6.3.1 Install Options for Developers

Use the following options from the R console:

  • Clone FIMS and build using devtools::load_all() (mimics package building) or devtools::install() (actually builds package from local files). These are good options if you intend to modify files in FIMS and want to test them out.
  • Use install.packages("FIMS", repos = c("https://noaa-fims.r-universe.dev", "https://cloud.r-project.org")) to download the latest precompiled version from R universe or devtools::install_github("NOAA-FIMS/FIMS) to compile yourself. devtools::install_github() has options to all you to be more specific about which version of the code is being built (e.g., you can refer to a tag or branch, which is not possible with the R universe install).

6.3.2 Windows: Fixing Fatal Error

Windows users can expect to see some derivative of the following error message in their R session if they have not yet set some flags using {withr}.

Fatal error: can't write <xxx> bytes to section .text of FIMS.o: 'file too big

You can easily fix this by running the following line in your local R session. Note that this call will need to be repeated each time you open a new session.

withr::local_options(pkg.build_extra_flags = FALSE)

This fix does not work when devtools::test() is called and FIMS is re-compiled. The call to devtools::test() in this case overwrites the local options set by withr. Compile FIMS first using devtools::load_all() prior to running devtools::test().

This fix removes the debugger flag -O0 -g from being automatically inserted for certain devtools calls (e.g. devtools::load_all()). Windows developers wanting to compile FIMS with the debugger turned on will need to run the above script in addition to manually modifying the call to PKG_CXXFLAGS in the Makevars.win file in the src directory to the following:

PKG_CXXFLAGS =  -DTMB_MODEL  -DTMB_EIGEN_DISABLE_WARNINGS -O1 -g

To turn off the debugger flag, remove the -O1 -g flag:

PKG_CXXFLAGS =  -DTMB_MODEL  -DTMB_EIGEN_DISABLE_WARNINGS

6.4 Getting Help

Please report bugs along with a minimal reproducible example on GitHub Issues