chore: import upstream snapshot with attribution
This commit is contained in:
wehub-resource-sync
+230
@@ -0,0 +1,230 @@
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user