diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d0be8dab..90b1b805 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -70,6 +70,56 @@ Sometimes there's something that Rojo doesn't do that it probably should. Please file issues and we'll try to help figure out what the best way forward is. +## Profiling with Tracy + +Rojo can be built with [Tracy](https://github.com/wolfpld/tracy) support to help find performance problems. Snapshot, patch, and build code paths are instrumented with the [`profiling`](https://crates.io/crates/profiling) crate. + +### Installing Tracy + +1. Download the Tracy profiler UI from the [Tracy releases page](https://github.com/wolfpld/tracy/releases), or build it from source. Each release includes a `tracy.pdf` manual with build instructions. +2. Use a Tracy version that matches Rojo's `tracy-client` dependency. Check the `tracy-client-sys` version in [`Cargo.lock`](Cargo.lock) and find the corresponding Tracy release in the [tracy-client version table](https://crates.io/crates/tracy-client#version-support-table). + +### Building Rojo with Tracy support + +```bash +cargo build --features profile-with-tracy +``` + +For meaningful performance data, prefer a release build: + +```bash +cargo build --release --features profile-with-tracy +``` + +### Capturing a trace + +1. Start the Tracy profiler UI. +2. Run Rojo with the feature enabled, for example: + +```bash +cargo run --release --features profile-with-tracy -- serve +``` + +3. In Tracy, connect to the running `rojo` process. +4. Perform the actions you want to profile (syncing, building, etc.) and inspect the timeline in Tracy. + +Short-lived commands like `build` may exit before Tracy can connect. Set `TRACY_NO_EXIT=1` to keep the process alive until you connect (not supported on macOS): + +```bash +TRACY_NO_EXIT=1 cargo run --release --features profile-with-tracy -- build test-projects/benchmark_small_place --output /tmp/out.rbxlx +``` + +On macOS, prefer profiling long-running commands like `serve` instead. + +### Adding instrumentation + +Use these `profiling` macros in Rust code: + +* `#[profiling::function]` on a function traces the entire function body. +* `profiling::scope!("name")` traces a block within a function. + +These macros compile to no-ops unless the `profile-with-tracy` feature is enabled. + ## Local Development Gotchas If your build fails with an error about a missing path under `plugin/Packages`, such as `plugin/Packages/Roact`, you need to update your Git submodules. diff --git a/Cargo.toml b/Cargo.toml index 9d37c22a..f04dbcdc 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -31,7 +31,8 @@ default = [] dev_live_assets = [] # Run Rojo with this feature to open a Tracy session. -# Currently uses protocol v63, last supported in Tracy 0.9.1. +# See CONTRIBUTING.md for setup instructions. Match the Tracy GUI version to +# the tracy-client-sys version in Cargo.lock (see the tracy-client version table). profile-with-tracy = ["profiling/profile-with-tracy"] [workspace]