Development environment

Learn how to setup your dev experience for rsonpath to effectively contribute to the codebase.

Supported systems

Unless you're specifically going to develop SIMD support for a new platform, you will need an x86_64 CPU with AVX2 support! Unfortunately, for comfortable development you need to support at least one of the SIMD architectures we target. Currently that's only x86_64 with avx2+pclmulqdq.

Preliminaries

Fork the repo and clone the repository locally.

You will obviously need Rust (see rustup.rs), at least in the MSRV (see Cargo.toml rust-version). Get the nightly toolchain as well with rustup install nightly.

Get just from your favourite package manager (like cargo) and also cargo-hack. Some of those are automated by our Justfile, but it's better to setup your own environment.

Just and development workflow

We use just, which is a modern command runner, a better alternative to build tools like make. A lot of standard dev tasks are automated with the Justfile. As a start run just init from repository's root to setup submodules and git hooks automatically. Then run just build to make sure the project builds.

Cheatsheet

You can list all commands with just -l, but here's a cheatsheet with most common commands. All of them have a one-letter alias.

• just b – build the binary in debug mode;
• just r *ARGS – run the debug binary with given arguments, e.g. just r '$.a.b' -v
• just v – verify that the lib and bin compile (with cargo check);
• just t – run the fast unit tests of the library.

Running tests

Run just test to execute all tests in the project. This includes real dataset end-to-end tests, so might take a minute or so. The just t command runs only unit tests, which is very quick, and just doctest runs doctests.

Note that just test runs the tests for all possible feature sets, so it will fail if your platform does not support the simd feature.

For more details on different test suites and testing methodology we apply check out Testing.

Linting

To verify your code before pushing, use just verify. It will make sure it's formatted correctly, builds, passes all tests, and doesn't emit warnings. It will also build the documentation. There are specialised commands for lighter verifications, like v, verify-fmt, and verify-clippy.

Benchmarks

Benchmarks are contained in a separate repo, rsonpath-benchmarks, included as a git submodule. To run the benches there, go to the submodule (/crates/rsonpath-benchmarks) and run just bench. This will run the main benchmark. For more details consult TODO.