Building From Source#

Last revised on 2026 MAY 28 by Z. Ellis.

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:

Ctrl + Shift + P on Windows/Linux or Cmd + Shift + P on Mac
Search for Preferences: Open User Settings and open it
In User Settings, search for rust-analyzer: Linked Projects and select Edit in settings.json
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. This will generate a few build artifacts that will clutter the file explorer. The next step will help you configure VSCode to hide these artifacts.

Hide Build Artifacts#

After running maturin develop, two files will be generated in the src/scarabaeus path:

a decoder ring that provides a map from compiled Rust code to the terminal so that errors can be displayed
the actual compiled Rust code

Depending on your OS, these two files will take different forms. Regardless, they’re not files that we will need access to and clutter the folder structure, so we’ll exclude them from VSCode’s explorer:

Ctrl + , on Windows/Linux or Cmd + , on Mac
Search for Files:Exclude and select Add Pattern

For Windows, add the following patterns:

**/*.pdb to hide the decoder ring
**/*.pyd to hide the compiled Rust binaries

For Linux, add the following patterns:

**/*.dwp to hide the decoder ring
**/*.so to hide the compiled Rust binaries

For Mac, add the following patterns:

**/*.dSYM to hide the decoder ring
**/*.so to hide the compiled Rust binaries

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.