Skip to content

Latest commit

 

History

History
230 lines (163 loc) · 6.88 KB

DEVELOPMENT.md

File metadata and controls

230 lines (163 loc) · 6.88 KB

Developer Guide (How to build Perspective from this repo)

This guide will teach you everything you need to know to get started hacking on the Perspective codebase. Please see CONTRIBUTING.md for contribution guidelines.

If you're coming to this project as principally a JavaScript developer, please be aware that Perspective is quite a bit more complex than a typical NPM package due to the mixed-language nature of the project; we've done quite a bit to make sure the newcomer experience is as straightforward as possible, but some things might not work the way you're used to!

Perspective is organized as a monorepo, and uses lerna to manage dependencies.

This guide provides instructions for both the JavaScript and Python libraries. To switch your development toolchain between the two, use pnpm run setup. Once the setup script has been run, common commands like pnpm run build and pnpm run test automatically call the correct build and test tools.

System Dependencies

Perspective.js and perspective-python require the following system dependencies to be installed:

This list may be non-exhaustive depending on your OS/environment; please open a thread in Discussions if you have any questions

Build

Make sure you have the system dependencies installed. For specifics depending on your OS, check the system-specific instructions below.

To run a build, use

pnpm run build

If this is the first time you've built Perspective, you'll be asked to generate a .perspectiverc via a short survey. This can be later re-configured via

pnpm run setup

If everything is successful, you should be able to run any of the examples/ packages, e.g. examples/blocks like so:

pnpm run start blocks

Perspective.js

To build the JavaScript library, which includes WebAssembly compilation, Emscripten and its prerequisites are required.

Perspective.js specifies its Emscripten version dependency in package.json, and the correct version of Emscripten will be installed with other JS dependencies by running pnpm install.

Building via local EMSDK

To build using an Emscripten install on your local system and not the Emscripten bundled with Perspective in its package.json, install the Emscripten SDK, then activate and export the latest emsdk environment via emsdk_env.sh:

source emsdk/emsdk_env.sh

Deviating from this specific version of Emscripten specified in the project's package.json can introduce various errors that are extremely difficult to debug.

To install a specific version of Emscripten (e.g. 2.0.6):

./emsdk install 2.0.6

perspective-python

To build the Python library, first configure your project to build Python via pnpm run setup. Then, install the requirements corresponding to your version of python, e.g.

pip install -r rust/perspective-python/requirements.txt

perspective-python supports Python 3.11 and upwards.

perspective-jupyterlab

To install the Jupyterlab/Jupyter Notebook plugins from your local working directory, simply install python/perspective with pip as you might normally do.

# builds labextension to the perspective-python python package root directory
PACKAGE=perspective-jupyterlab pnpm run build
# editable install of the python package
pnpm -F @perspective-dev/python develop:maturin
# set up symlink of our labextension to jupyter share directory
# this directory's path is in the output of `jupyter labextension list`
pnpm -F @perspective-dev/python develop:labextension

Afterwards, you should see it listed as a "local extension" when you run jupyter labextension list and as a normal extension when you run jupyter nbextension list.

System-Specific Instructions

MacOS/OSX

Install system dependencies through Homebrew:

brew install cmake llvm@17
brew link llvm@17 # optional, see below

On M1 (Apple Silicon) systems, make sure your brew-installed dependencies are in /opt/homebrew (the default location), and that /opt/homebrew/bin is on the PATH.

If you do not want to link the llvm@17 keg, then while developing ensure it is on your PATH too, like this:

PATH=$(brew --prefix llvm@17)/bin:$PATH

Note: Perspective vendors its C++ extensions, so you may run into trouble building if you have brew-installed versions of libraries, such as flatbuffers.

Windows 10+

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.

Ubuntu/Debian

On Ubuntu, CMake will mistakenly resolve the system headers in /usr/include rather than the emscripten supplied versions. You can resolve this by moving boost dependencies to somewhere other than /usr/include - into Perspective's own src dir (as per here).

apt-get install libboost-all-dev
cp -r /usr/include/boost ./packages/perspective/src/include/

Test

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.

pnpm run test

JavaScript

The JavaScript test suite is composed of two sections: a Node.js test, which asserts behavior of the @perspective-dev/client library, and a suite of Playwright tests, which assert the behavior of the rest of the UI facing packages.

pnpm run test --update-snapshots

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 is too old
  • Boost headers are missing or too old

Benchmark

You can generate benchmarks specific to your machine's OS and CPU architecture with Perspective's benchmark suite, which will host a live dashboard at http://localhost:8080 as well as output a result benchmark.arrow file.

pnpm run bench