Thank you for your interest in contributing to Perspective! This guide will teach you everything you need to know to get started hacking on the Perspective codebase.
To switch your development toolchain between the two, use
yarn setup. Once the
setup script has been run, common commands like
yarn build and
automatically call the correct build and test tools.
To run a build, use
If this is the first time you've built Perspective, you'll be asked to generate
.perspectiverc via a short survey. This can be later re-configured via
If everything is successful, you should be able to run any of the
examples/simple like so:
yarn start simple
Docker images with pre-built development environments are provided for the Python libraries.
To build Perspective using Docker, select the option in
perspective-python require the following system dependencies to be installed:
- CMake (version 3.15.4 or higher)
- Boost (version 1.67 or higher, must be built - not header-only)
Perspective.js specifies its Emscripten version dependency in
and the correct version of Emscripten will be installed with other JS
dependencies by running
Building via local EMSDK
To build using an Emscripten install on your local system and not the
Emscripten bundled with Perspective in its
Emscripten SDK, then activate and export the latest
emsdk environment via
We currently use Emscripten version
2.0.6 — deviating from this specific
version of Emscripten can introduce various errors that are extremely difficult
To install this specific version of Emscripten:
./emsdk install 2.0.6
To install the Jupyterlab plugin from your local working directory, give
jupyter labextension install the path to the
jupyter labextension install ./packages/perspective-jupyterlab
Afterwards, you should see it listed as a "local extension" when you run
jupyter labextension list.
Because we do not inline Perspective into the Jupyterlab plugin, your local
changes will not show up in Jupyterlab unless you use
according to the directions below:
- Ensure that your Jupyterlab is built by running
jupyter lab build.
- Inside each directory in
yarn link. This will create a symlink to your local build that we will use inside Jupyterlab.
- From the Perspective root, run
yarn jlab_link. This is a script that will find your Jupyterlab installation and tell Jupyterlab to use these symlinks when it looks for Perspective packages, instead of fetching them from NPM.
- When you make a local change, make sure you run
jupyter lab buildso that it fetches the newest changes.
- Whenever you run
jupyter lab clean, you will need to run
yarn jlab_linkagain to re-register the symlinks.
To build the Python library, first configure your project to Python via
yarn setup, then run:
perspective-python supports Python 3.7 and upwards, as well as Python 2.7.17.
To build the Python 2 version of the library, use the
yarn build --python2
Install system dependencies through Homebrew:
brew install cmake brew install email@example.com brew install flatbuffers
If you're building the Python 2 version of the library, make sure your version
of Python 2 is the latest version (
2.7.17) supplied by Homebrew, and not the
earlier version that ships with MacOS. To install Python 2 using Homebrew:
brew install python2
You need to use bash in order to build Perspective packages. To successfully build on Windows 10, enable Windows Subsystem for Linux (WSL) and install the Linux distribution of your choice.
Create symbolic links to easily access Windows directories and projects modified via Windows. This way, you can modify any of the Perspective files using your favorite editors on Windows and build via Linux.
Follow the Linux specific instructions to install Emscripten and all prerequisite tools.
On Ubuntu, CMake will mistakenly resolve the system headers in
rather than the emscripten supplied versions. You can resolve this by moving
flatbuffers dependencies to somewhere other than
into Perspective's own
src dir (as per
apt-get install libboost-all-dev cp -r /usr/include/boost ./packages/perspective/src/include/ cd ./packages/perspective/src/include/ git clone https://github.com/google/flatbuffers.git cd flatbuffers cmake -G "Unix Makefiles" make ln -s /usr/local/flatbuffers/flatc /usr/local/bin/flatc chmod +x /usr/local/flatbuffers/flatc
You can run the test suite simply with the standard NPM command, which will both build the test suite for every package and run them.
yarn test [--debug]
A test name regex can be passed to
jest via the same
yarn test -t 'button test (A|B)'
asserts behavior of the
@finos/perspective library, and a suite of
Puppeteer tests, which
assert the behavior of the rest of the UI facing packages. For the latter,
you'll need Docker installed, as these tests use a Puppeteer and Chrome build
installed in a Docker container.
The Puppeteer/UI tests are a form of
which use screenshots to compare current and previous behavior of
<perspective-viewer> and its plugins. The results of each comparison are
stored in each package's
test/results/results.json file, and the screenshots
themselves are stored in the package's
screenshots/ directory, though only the
former should be checked into GIT. When a test in these suites fails, a
file.diff.png are also generated, showing the divergent
screenshot and a contrast diff respectively, so you can verify that the changed
behavior either does or does not reflect your patch. If you're confident that
the screenshots reflect your change, you can update the new hashes manually in
test/results/results.json file, or update all hashes with the
yarn test --write
For quick local iteration and debugging failing tests, the Puppeteer tests can
use a local copy of Puppeteer, rather than relying on the supplied Docker image.
These will run much quicker, and can be optionally run without
for debugging test failures quickly. However, due to rendering inconsistencies
between platforms, the resulting test hashes will not match the ones saved in
results.json, so you will need to re-run the suite with the
--write flag to
results.local.json file specific to your OS.
To toggle between local and Docker Puppeteer, run
This will install a local copy of Puppeteer via
yarn the first time it is run,
if a local Puppeteer is not found.
The Python test suite is built on Pytest, and it asserts the correct behavior of the Python library.
If you have built the library with the
--python2 flag, make sure to run the
test suite using the
--python2 flag as well. Running a version of
perspective-python built against Python 2 in Python 3 (and vice versa) is not
Verbosity in the tests can be enabled with the
Troubleshooting installation from source
If you are installing from a source distribution (sdist), make sure you have the System Dependencies installed.
Try installing in verbose mode:
pip install -vv perspective-python
The most common culprits are:
- CMake version too old
- Boost headers are missing or too old
- Flatbuffers not installed prior to installing Perspective
Timezones in Python Tests
Python tests are configured to use the
UTC time zone. If running tests locally,
you might find that datetime-related tests fail to assert the correct values. To
correct this, run tests with the
TZ=UTC yarn test --verbose
You can generate benchmarks specific to your machine's OS and CPU architecture
with Perspective's benchmark suite, which will generate a
report.html file in
build/ directory of every package which supports benchmarks, as well as a
results.json file in the
bench/results/, which can be checked in to GIT with
your changes to preserve them for future comparison.
The benchmarks report and
results.json show a histogram of current
performance, as well as that of the previous
results.json. Running this should
probably be standard practice after making a large change which may affect
performance, but please create a baseline
results.json entry for your test
machine on a commit before your changes first, such that the effects of your PR
can be properly compared.