-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy path06-developer-software-guide.Rmd
163 lines (114 loc) · 12.8 KB
/
06-developer-software-guide.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
# 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.
## Codespaces as an alternative to installing software
An alternative to setting up this software locally is using [GitHub Codespaces](https://docs.github.com/en/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](https://docs.github.com/en/codespaces/developing-in-a-codespace/creating-a-codespace-for-a-repository?tool=webui#creating-a-codespace-for-a-repository).
## Software to install
### git
To contribute to the code, you will need git installed locally, and you may prefer to use an additional git [GUI client](https://git-scm.com/downloads/guis) such as GitHub Desktop. See the section on [RStudio](#rstudio) and [VS Code](#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](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).
### 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](https://www.rstudio.com/) and [Visual Studio (VS) Code](https://code.visualstudio.com/). You are welcome to use any IDE or text-editor based workflow.
#### VS Code
Install [VS Code](https://code.visualstudio.com/Download) and configure it for using [`R`](https://github.com/REditorSupport/vscode-R/wiki/Installation:-Windows) and [`C++`](https://code.visualstudio.com/docs/languages/cpp). For those migrating from RStudio to VS Code, [this post on migrating to VS code](https://statnmap.com/2021-10-09-how-not-to-be-lost-with-vscode-when-coming-from-rstudio/) 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](https://github.com/REditorSupport/vscode-R/wiki/Interacting-with-R-terminals#sending-code-to-r-terminals) can be adjusted.
Additional settings for R are available in the [extension wiki](https://github.com/REditorSupport/vscode-R/wiki/Extension-settings) and [shortcuts wiki](https://github.com/REditorSupport/vscode-R/wiki/Keyboard-shortcuts). The keybindings.json and settings.json can be copied from one computer to another but the [settings.json location differs](https://code.visualstudio.com/docs/getstarted/settings#_settings-file-locations) depending on the operating system. Below are some example settings you may want to specify.
```json
{
// 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](https://code.visualstudio.com/docs/getstarted/tips-and-tricks#_vertical-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.
#### RStudio
Install [RStudio](https://posit.co/download/rstudio-desktop/) and configure it for working with git if you would like following these [instructions](https://happygitwithr.com/rstudio-git-GitHub.html).
### 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](https://github.com/NOAA-FIMS/FIMS/blob/f0d4e766ddfc70c6dbb99e92385298c31ccff136/CMakeLists.txt#L10). For macOS users, Xcode 9.3+ provides clang 5.0. For Windows users, [rtools4](https://cran.r-project.org/bin/windows/Rtools/rtools40.html) 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:
```bash
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 select `Path' and `New'. Add the path, e.g., `C:\rtools44\x86_64-w64-mingw32.static.posix\bin`. 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 type `echo $PATH` in the terminal and hit enter and then move the binary to this path, e.g.,
```bash
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:
```bash
sudo chmod +x ninja
```
### GoogleTest
You will need to install a build system such as [[CMake]{.ul}](https://cmake.org/) and a compatible build tool such as [[Ninja]{.ul}](https://ninja-build.org/), which are both approved by NMFS HQ.
1. Download the latest version of [[CMake]{.ul}(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.
1. Download the latest version of [[ninja]{.ul}](https://github.com/ninja-build/ninja/releases) for your operating system (e.g., `ninja-win.zip`) and unzip the application in `Documents\Apps` or another preferred folder.
1. 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](#c++-compiler) on how to add locations to your PATH.
1. For linux and mac users you may also have to edit the permissions of the binary, see the [C++ section for instructions](#c++-compiler).
### 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](https://github.com/r-windows/docs/blob/master/faq.md#does-rtools40-include-a-debugger) for how to install it and the [C++ section](#c++-compiler) for how to add it to your path.
### 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](https://www.doxygen.nl/manual/install.html). Visit the [download page](https://www.doxygen.nl/download.html) 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](#c++-compiler).
### R
The following is needed:
- The version of R [specified in the DESCRIPTION file](https://github.com/NOAA-FIMS/FIMS/blob/f0d4e766ddfc70c6dbb99e92385298c31ccff136/DESCRIPTION#L57) or newer (or RStudio version 1.2.5042 or newer)
- The version of [`TMB`](https://github.com/kaskr/adcomp/wiki/Download) [specified in the DESCRIPTION file](https://github.com/NOAA-FIMS/FIMS/blob/f0d4e766ddfc70c6dbb99e92385298c31ccff136/DESCRIPTION#L65) or newer
- Windows users will need [Rtools](https://cran.r-project.org/bin/windows/Rtools)
## Installing FIMS
### 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](https://github.com/NOAA-FIMS/FIMS) from the terminal via `git clone https://github.com/NOAA-FIMS/FIMS.git`.
- Build FIMS within R using `devtools::install()` which builds the package from local files and installs it within your R library. Thus, when you use `library(FIMS)` the build of FIMS from your cloned files will be used. Note, that if you update your cloned files you will need to install FIMS again.
- Installing FIMS with `devtools::load_all()` is not recommended because the function uses shim files for things like `system.file()` which can cause FIMS to not function as expected. For example, if you try to optimize the same model twice, you will more than likely not get estimates of uncertainty from the second model run. The reason is currently unknown but the behavior does not exist if you build FIMS with `devtools::install()` so that is what we recommend. Additionally, `devtools::load_all()` adds the debugger flag `-O0 -g` which leads to Windows users seeing `Fatal error: can't write <xxx> bytes to section .text of FIMS.o: 'file too big`. Thus, Windows users need to run `withr::local_options(pkg.build_extra_flags = FALSE)` at the beginning of every R session before calling `devtools::load_all()`. If you want to compile FIMS with the debugger turned on you will need to run the {withr} function in addition to manually modifying the call to PKG_CXXFLAGS in the [Makevars.win](https://github.com/NOAA-FIMS/FIMS/blob/doc-install/src/Makevars.win) file in `src` to `PKG_CXXFLAGS = -DTMB_MODEL -DTMB_EIGEN_DISABLE_WARNINGS -O1 -g`.
### 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).
## Getting Help
Please report bugs along with a minimal reproducible example on GitHub [Issues](https://github.com/NOAA-FIMS/FIMS/issues).