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

To contribute to the code, you will need git installed locally, and you may prefer to use an additional git GUI client such as GitHub Desktop. See the section on RStudio and VS Code for setting up those editors to work with git.

To install git, please contact your IT department or follow the operating-system specific instructions available in the git documentation.

6.2.2 Development environment

An integrated development environment (IDE) is recommended to organize code files, outputs, and build and debug environments. The most popular IDEs used by the development team are RStudio and Visual Studio (VS) Code. You are welcome to use any IDE or text-editor based workflow.

6.2.2.1 VS Code

Install VS Code and configure it for using R and C++. For those migrating from RStudio to VS Code, this post on migrating to VS code may be helpful. You can also search the VS Code marketplace for additional keymap packages that import key mappings from commonly used text editors (e.g., Sublime, Notepad++, atom, etc.).

A number of optional settings can be added to the user settings (settings.json) file in VS Code to improve the usability of R in VS Code. For example, the settings for interacting with R terminals can be adjusted.

Additional settings for R are available in the extension wiki and shortcuts wiki. The keybindings.json and settings.json can be copied from one computer to another but the settings.json location differs depending on the operating system. Below are some example settings you may want to specify.

{
    // 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
}

Other helpful extensions for VS Code are available in the VScode marketplace, e.g., - 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. - GitLens (or GitLess): Adds more Git functionality. Some of the GitLens functionality is not free, and GitLess is a fork before the addition of these premium features. - A list of extensions that can help make VS Code operate more like RStudio is available by typing `R: Launch Rstudio Addin’ in the command pallete.

6.2.2.2 RStudio

Install RStudio and configure it for working with git if you would like following these instructions.

6.2.3 C++ compiler

Install a C++ compiler that supports the version of C++ being used in FIMS (e.g., gcc 5.0+, clang 5.0+, or MSVC 2015+). You can find the current version of C++ needed by searching for CMAKE_CXX_STANDARD in the CMakeLists.txt file in FIMS. For macOS users, Xcode 9.3+ provides clang 5.0. For Windows users, rtools4 includes gcc.

To ensure the C++ compiler is on your path, open a command prompt and type gcc. If you get the following message, you are all set:

gcc
gcc: fatal error: no input files compilation
terminated.

If not, you will need to add the compiler is in your path by editing the environment variables for your account. In bash you can find out where a program in your path is located by running which <binaryName> replacing the carrots and everything inside of them with the binary name of interest. On Windows, you can push the Windows key, or the search tool next to the Windows Menu, and type env, which will bring up Edit environment variables for your account'. Then selectPath’ and New'. Add the path, e.g.,C:_64-w64-mingw32.static.posix. Close out of this and the previous window and then restart the terminal and R. On linux or mac, the easiset way to fix path issues is to move executables to a folder already in your path. To find existing path folders typeecho $PATH` in the terminal and hit enter and then move the binary to this path, e.g.,

sudo cp ~/Downloads/ninja /usr/bin/

Note that in certain Fisheries centers, NOAA employees do not have administrative privileges enabled to edit the local environmental path. In this situation it is necessary to create a ticket with IT to add cmake and ninja to your PATH on Windows.

Also note that, for linux and mac users, you may need to add executable permissions to the binary after downloading it. You can do that by switching the terminal to the folder where you placed the binary and running the following command, where the example is for the ninja binary:

sudo chmod +x ninja

6.2.4 GoogleTest

You will need to install a build system such as CMake and a compatible build tool such as Ninja, which are both approved by NMFS HQ.

  1. Download the latest version of [CMake(https://cmake.org/download/). Where, Windows users will want cmake-*.*.*-windows-x86_64.zip and users of other platforms can choose the download that best suites their system. Place the unzipped folder in Documents\Apps or another preferred folder.

  2. Download the latest version of ninja for your operating system (e.g., ninja-win.zip) and unzip the application in Documents\Apps or another preferred folder.

  3. Open a new Command Prompt and type cmake. If you see details of usage, cmake is already in your PATH. Now type ninja. If you see a message that starts with ninja:, even if it is an error about not finding build.ninja, this means that ninja is already in your PATH. If either of the previous fail, follow the the instructions in the C++ section on how to add locations to your PATH.

  4. For linux and mac users you may also have to edit the permissions of the binary, see the C++ section for instructions.

6.2.5 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 in /rtools44/mingw64/bin/gdb.exe. See R on Windows FAQ for how to install it and the C++ section for how to add it to your path.

6.2.6 Doxygen

Doxygen is required to build the C++ documentation for FIMS, which automates the generation of documentation from source code comments. To install Doxygen, please follow the instructions in the Doxygen manual. Visit the download page for the 64-bit zip for Windows and tar files for other operating systems. Unzip the download into Documents\Apps\Doxygen or another preferred folder and ensure the location is in your path.

6.2.7 R

The following is needed: - The version of R specified in the DESCRIPTION file or newer (or RStudio version 1.2.5042 or newer) - The version of TMB specified in the DESCRIPTION file or newer - Windows users will need Rtools

6.3 Installing FIMS

6.3.1 Clone and build

Cloning FIMS and building it is a good option if you intend to modify files in FIMS and want to test them out. - Clone the FIMS repository from the terminal via git clone https://github.com/NOAA-FIMS/FIMS.git. - Build FIMS within R using devtools::load_all(), which mimics package building, or devtools::install(), which actually builds the package from local files.

6.3.2 Precompiled

  • Download from R universe within R using install.packages("FIMS", repos = c("https://noaa-fims.r-universe.dev", "https://cloud.r-project.org")).
  • Install from GitHub within R using devtools::install_github("NOAA-FIMS/FIMS) to compile yourself, which allows 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.3 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. 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() before 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 src 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.