DEVELOPING.md

A developer's guide to regl

This document is to help make it easier to contribute to regl. It describes how some common workflows associated and how to get started with helping out.

Basic set up

To set up the development environment for regl, you first need to install nodejs. Any version >0.10 is supported. Once this is done, you can install regl's development dependencies using the following npm command:

npm install

Examples

regl has tons of examples. To run them locally, you can use budo, which is a minimal HTTP server integrated with browserify. To install budo, run the following command:

npm install -g budo

Then go into the example folder and run any example with the following command:

budo example/basic.js --open

Where you can replace basic.js with the name of whatever example you want to run.

Adding an example

To add an example, just create a javascript file in the example folder. Each example should have a header comment at the top of the page that describes how it works. This comment may contain HTML tags.

If your example needs any static data, please put them in the example/assets directory.

To add an image for your example, take a screen shot, name it myexample.png and place it in the example/img folder.

Style guidelines

regl adheres to the standard style. The reason for this is to prevent "bikeshed" type discussions about code style and configuration that distract from actual issues.

In addition to the standard style guidelines, we also enforce two extra constraints for technical reasons:

• All test cases, benchmarks and library code must be written using strict ES5 style.
• All examples use ES6

The reason we do not use ES6 in the library or test code is that regl supports node 0.10, which does not implement ES6. Because the examples are meant to be illustrative we do not enforce the same strict compatibility requirements.

For markdown, we're using remark and remark-lint.

Tests

regl uses tape for unit testing. As a result, you can run any specific unit test directly in node like you would any other script without using any special unit test harness. For example, to just run the texture2D tests, you could run the following command from the root directory:

node test/texture2d.js

To run all of the test cases in a batch, use the npm test script, which is the following command:

npm test

IMPORTANT Before submitting a pull request, be sure to run the test cases first. If you don't do it, the CI system will flag your PR and you won't be able to merge.

Some test cases make use of browser specific extensions and may need to run in a browser environment. To run the test suite in a browser, use the following command:

npm run test-browser

regl also uses istanbul to measure code coverage for the test suite. To generate a coverage report, use the following command:

npm run cover

Then you can view the results in coverage/lcov-report/index.html

Adding a test case

To add a test case, create a new file in the test/ folder and then add a reference to it in test/index.js. Take a look at the examples in the test folder for help.

Benchmarks

To run the benchmarks, use this command:

npm run bench-node

This will run the benchmarks in node.js, and output the results to stdout in json-format. If you want to see prettified benchmarks results, run

npm run bench-node -- --pretty

If you want to run the benchmarks in the browser, just run

npm run bench-browser

If you want to run the benchmarks on a bunch of commits in the history of the repo, do

npm run bench-history 10

This script will, starting from the current HEAD, run the benchmarks through all the 10 latest commits, and write all the benchmark data as json to a file.

Note that the script will run git stash before switching to the old commits, and then in the end it will switch to the original HEAD and run git stash pop, in order to ensure that no uncommited changes are lost.

Also note that there is a so-called ancestor commit, and the script will NOT run any benchmarks beyond the ancestor commit. This is because that beyond this ancestor commit, the benchmarking environment had not yet been properly set up, so the benchmarking results produced by these commits should not be used.

Then you can create pretty graphs from the benchmark data outputted from bench-history. Just do

npm run bench-graph bench/bench-result-2f95fbcf3e60dff98c4b.json

where bench/bench-result-2f95fbcf3e60dff98c4b.json is the file outputted by bench-history. The script will create an HTML-file with graphs made with d3 from the data, and automatically open the HTML-file in your default browser.

Adding a benchmark

The easiest way to add a new benchmark is to copy an existing benchmark (see for example bench/clear.js), modify it, and add an entry to bench/list.js

Size measurements

You can also get a report of the current bundle size of regl using disc. An up to date set of stats can be found in www/size.html.

To regenerate these results, run the command

npm run build-size

Comparisons

The comparisons pages is autogenerated from the contents of the compare/ directory. Each sub directory in the compare directory contains a task, and each task directory contains several implementations of this task.

An implementation may be either a raw JavaScript file (which is compiled with browserify) or an HTML web page. Each task must contain an image of the expected results (called expected.png) and a description called description.txt.

Rebuilding the web assets

To rebuild all redistributable assets and the static website, use the command:

npm run build

Find something to do

Check out the change log for planned features and tasks.

There is also a list of open issues on GitHub that need work. Anything with the "help wanted" tag may be good for a beginner starting out.

Alternatively, if you want to propose a new feature or report a bug, you should open an issue on GitHub.

There is also active discussion in the gitter chat. If you join there, you can usually find someone to talk to.