wehub-resource-sync
231 lines
6.9 KiB
Markdown
231 lines
6.9 KiB
Markdown
# 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`](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](https://github.com/babel/babel/blob/master/doc/design/monorepo.md),
|
|
and uses [lerna](https://lernajs.io/) 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:
|
|
|
|
- [CMake](https://cmake.org/) (version 3.29.5 or higher)
|
|
- [pnpm](https://pnpm.io/).
|
|
|
|
**_This list may be non-exhaustive depending on your OS/environment; please open
|
|
a thread in
|
|
[Discussions](https://github.com/perspective-dev/perspective/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](#system-specific-instructions)
|
|
below.
|
|
|
|
To run a build, use
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
pnpm run setup
|
|
```
|
|
|
|
If everything is successful, you should be able to run any of the `examples/`
|
|
packages, e.g. `examples/blocks` like so:
|
|
|
|
```bash
|
|
pnpm run start blocks
|
|
```
|
|
|
|
## `Perspective.js`
|
|
|
|
To build the JavaScript library, which includes WebAssembly compilation,
|
|
[Emscripten](https://github.com/kripken/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](https://emscripten.org/docs/getting_started/downloads.html) the
|
|
Emscripten SDK, then activate and export the latest `emsdk` environment via
|
|
[`emsdk_env.sh`](https://github.com/juj/emsdk):
|
|
|
|
```bash
|
|
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`):
|
|
|
|
```bash
|
|
./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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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](https://docs.microsoft.com/en-us/windows/wsl/install-win10)
|
|
(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](http://vclf.blogspot.com/2014/08/emscripten-linking-to-boost-libraries.html)).
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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](https://playwright.dev/) tests, which assert the behavior of the
|
|
rest of the UI facing packages.
|
|
|
|
```bash
|
|
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](#system-dependencies) installed.
|
|
|
|
Try installing in verbose mode:
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
pnpm run bench
|
|
```
|