Skip to content

BUILD.md

Latest commit

 

History

History
209 lines (150 loc) · 6.57 KB

BUILD.md

File metadata and controls

209 lines (150 loc) · 6.57 KB

Building Rerun

This is a guide to how to build Rerun.

See also

Getting started with the repository

First, install the Rust toolchain using the installer from https://rustup.rs/.

Then, clone the repository:

git clone git@github.com:rerun-io/rerun.git
cd rerun

Now install the pixi package manager: https://github.com/prefix-dev/pixi?tab=readme-ov-file#installation

Make sure cargo --version prints 1.74.0 once you are done.

If you are using an Apple-silicon Mac (M1, M2), make sure rustc -vV outputs host: aarch64-apple-darwin. If not, this should fix it:

rustup set default-host aarch64-apple-darwin && rustup install 1.74.0

Additionally, we use cargo-cranky for defining which Clippy lints are active and cargo-deny for linting crate versions. You don't need to install these for building, but it's highly recommended when contributing changes to Rust code.

cargo install cargo-cranky
cargo install --locked cargo-deny

Building and running the viewer

Use this command for building and running the viewer:

pixi run rerun

This custom cargo command is enabled by an alias located in .cargo/config.toml.

Running the Rust examples

All Rust examples are set up as separate executables, so they can be run by specifying the corresponding package, for example:

cargo run -p dna

Building and installing the Rerun Python SDK

Rerun is available as a package on PyPi and can be installed with pip install rerun-sdk.

Additionally, prebuilt dev wheels from head of main are available at https://github.com/rerun-io/rerun/releases/tag/prerelease.

If you want to build from source, use the following instructions.

Mac/Linux

First, a local virtual environment must be created and the necessary dependencies installed (this needs to be done only once):

Linux/Mac:

just py-dev-env
source venv/bin/activate

Windows (powershell):

just py-dev-env
.\venv\Scripts\Activate.ps1

Then, the SDK can be compiled and installed in the virtual environment using the following command:

just py-build

This needs to be repeated each time the Rust source code is updated, for example after updating your clone using git pull.

Now you can run the python examples from the repository, given that you're still in the virtual environment.

python examples/python/minimal/main.py

Building and installing the Rerun C++ SDK

On Windows you have to have a system install of Visual Studio 2022 in order to compile the SDK and samples.

All other dependencies are downloaded by Pixi! You can run tests with:

just cpp-test

and build all C++ artifacts with:

just cpp-build-all

Building the docs

High-level documentation for rerun can be found at http://rerun.io/docs. It is built from the separate repository rerun-docs.

Building for the web

If you want to build a standalone rerun executable that contains the web-viewer and a websocket server, you need to install the wasm32-unknown-unknown rust target and ensure the web_viewer feature flag is set when building rerun. This is automatically done by this shortcut which builds & runs the web viewer:

pixi run rerun-web

If you're on Windows you have to make sure that your git client creates symlinks, otherwise you may get errors during the build. Run git config --show-scope --show-origin core.symlinks to check if symlinks are enabled. You may need to turn on Windows developer mode in order to give the mklink command sufficient permissions. See also this Stack Overflow reply on the issue.

Improving compile times

As of today, we link everything statically in both debug and release builds, which makes custom linkers and split debuginfo the two most impactful tools we have at our disposal in order to improve compile times.

These tools can be configured through your Cargo configuration, available at $HOME/.cargo/config.toml.

macOS

On x64 macOS, use the zld linker and keep debuginfo in a single separate file.

Pre-requisites:

  • Install zld: brew install michaeleisel/zld/zld.

config.toml (x64):

[target.x86_64-apple-darwin]
rustflags = [
    "-C",
    "link-arg=-fuse-ld=/usr/local/bin/zld",
    "-C",
    "split-debuginfo=packed",
]

On Apple-silicon Mac (M1, M2), the default settings are already pretty good. The default linker is just as good as zld. Do NOT set split-debuginfo=packed, as that will make linking a lot slower. You can set split-debuginfo=unpacked for a small improvement.

config.toml (M1, M2):

[target.aarch64-apple-darwin]
rustflags = [
    "-C",
    "split-debuginfo=unpacked",
]

Linux

On Linux, use the mold linker and keep DWARF debuginfo in separate files.

Pre-requisites:

  • Install mold through your package manager.

config.toml:

[target.x86_64-unknown-linux-gnu]
linker = "clang"
rustflags = [
    "-C",
    "link-arg=-fuse-ld=/usr/bin/mold",
    "-C",
    "split-debuginfo=unpacked",
]

Windows

On Windows, use LLVM's lld linker and keep debuginfo in a single separate file.

Pre-requisites:

  • Install lld:
cargo install -f cargo-binutils
rustup component add llvm-tools-preview

config.toml:

[target.x86_64-pc-windows-msvc]
linker = "rust-lld.exe"
rustflags = [
    "-C",
    "split-debuginfo=packed",
]