Dev environment
The master branch is the active development branch. R users commonly install straight off the default branch, so master should be kept in an installable state (but not necessarily bug-free). Use feature branches for anything experimental, or potentially breaking.
The following tools are required for local development and build: - git - R >= 4 - nodejs >= 14 - npm >= 7
It is also recommended to install React Developer Tools for client-side debugging.
Install the npm dependencies:
npm installInstall R packages for development:
install.packages("devtools")
install.packages("styler")Debug
If you’re debugging rdeck maps in the browser, you won’t get far without a development build of the javascript and css. The development build isn’t minified and includes inline sourcemaps. Be careful that you do not accidentally commit the development build.
Start the development build watcher by running:
npm run watch-devDebugging the package from the R side of things is pretty standard. Load the package using devtools:
devtools::load_all()Now you can create some test maps interactively and hit breakpoints in the browser javascript console.
Code generation
The R api for creating deck.gl layers and most of the layer validation code is generated from the deck.gl javascript. The code-generation logic is written in javascript and leverages ejs templates. This code can be found in the scripts/ folder.
R scripts containing generated code are: - R/deckgl-layers.R - R/deckgl-validators.R
These files have been annotated with the standard # Generated by rdeck: do not edit by hand as a reminder to avoid modifying them manually.
These files should be regenerated when updating the deck.gl dependency, or when modifying the layer function templates. When regenerating the R api, it is a good idea to diff the latest to see if any parameters have changed that might require documentation.
To re-generate these files:
npm run codegenLayer documentation
The R deck.gl layer functions are generated code, but documentation for these layers are manual. The documentation for layers can be found in R/doc-deckgl-layers.R. Parameters that are common among layers (e.g. name) are located at the bottom of the script, attached to layer_props. Anything unique to a layer or customisation of generic parameters should be added to the appropriate layer documentation block in the same file.
This documentation method is leveraging roxygen inheritance heavily, but doing so on a name that doesn’t exist in the package: layer_props. This is a bit of a hack, but it’s elegant and saves a lot of duplication.