Building From Source

Scarabaeus utilizes Rust code for computationally expensive tasks. If you are developing within SCB or attempting a local build, this code must be compiled. The following will guide a developer through the steps required to compile Rust code and bind it to SCB’s Python front end.

Rust setup instructions adapted from Visual Studio Code for Scarabaeus-specific development.

Install Rust

Follow the instructions provided by the rustup installer, which supports installation for Windows, macOS, and Linux. Once Rust is installed, restart any terminal/Command Prompt and VS Code instances.

Once you’ve installed Rust and restarted all terminals, check to make sure everything is installed by typing in your terminal:

rustc --version

This will output the version of the Rust compiler if it’s installed.

Install and Link rust-analyzer Extension

The rust analyzer extension makes writing Rust code in VS Code significantly easier by providing IDE functionalities like auto-complete, inline errors, and auto-formatting. Install it via the VS Code Extensions tab.

Due to the structure of the src folder, we’ll have to manually link SCB’s Rust module src/scarabaeus_rust/ to rust-analyzer in its settings:

1. Ctrl + Shift + P on Windows/Linux or Cmd + Shift + P on Mac

2. Search for Preferences: Open User Settings and open it

3. In User Settings, search for rust-analyzer: Linked Projects and select Edit in settings.json

4. In the rust-analyzer.linkedProjects field, add: ["src/scarabaeus_rust/Cargo.toml"]

This will allow rust-analyzer to link to our Cargo file. Without it, we won’t be able to utilize the IDE functionalities provided by rust-analyzer.

Build Rust Source

The SCB dev environment includes maturin, which will allow us to build our Rust binaries as a Python package so that they’re callable within SCB’s frontend. SCB’s Rust source code is separated from Python source code, placed in the src/scarabaeus_rust folder. To compile this code, run in your terminal:

(.venv) maturin develop

This will build and bind the Rust code to the Python component of SCB, allowing compiled Rust code to be called within Python. If you are working solely on Python code (under src/scarabaeus), you will only need to run this the first time you’ve cloned the Rust code. However, if you are developing new Rust code, continue to the next step.

Expose (New) Rust Code to Python

If you are modifying or writing any Rust code, you’ll need to define and/or update its corresponding stub in the stub file src/scarabaeus/scarabaeus_rust.pyi before building with maturin develop. This stub file provides the docstrings used for documentation generation as well as inline definitions for any Rust code bound to Python.

Additionally, if you’ve created a brand new class (Rust struct bound to Python class), youll need to add it to the scarabaeus_rust package in the lib file src/scarabaeus_rust/src/lib.rs using:

m.add_class::<ClassName>()?;

Note that the <> are part of the code, not to denote an insertion.