{"id":13648787,"url":"https://github.com/cmyr/cargo-instruments","last_synced_at":"2025-05-14T07:09:42.785Z","repository":{"id":40747935,"uuid":"176036585","full_name":"cmyr/cargo-instruments","owner":"cmyr","description":"A cargo plugin to generate Xcode Instruments trace files","archived":false,"fork":false,"pushed_at":"2025-04-28T19:19:59.000Z","size":605,"stargazers_count":715,"open_issues_count":27,"forks_count":35,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-04-28T19:34:43.467Z","etag":null,"topics":["cargo","cargo-plugin","profiling","rust-tools"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cmyr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-03-16T23:44:23.000Z","updated_at":"2025-04-28T18:26:35.000Z","dependencies_parsed_at":"2023-10-14T19:29:44.458Z","dependency_job_id":"a5dddba2-3638-46a4-ac81-27b9ec5c24ac","html_url":"https://github.com/cmyr/cargo-instruments","commit_stats":{"total_commits":78,"total_committers":18,"mean_commits":4.333333333333333,"dds":0.2948717948717948,"last_synced_commit":"409b01e0b7a123f32aba2dae0b1d5a96c744ac53"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmyr%2Fcargo-instruments","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmyr%2Fcargo-instruments/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmyr%2Fcargo-instruments/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmyr%2Fcargo-instruments/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cmyr","download_url":"https://codeload.github.com/cmyr/cargo-instruments/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254092788,"owners_count":22013290,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cargo","cargo-plugin","profiling","rust-tools"],"created_at":"2024-08-02T01:04:32.548Z","updated_at":"2025-05-14T07:09:37.767Z","avatar_url":"https://github.com/cmyr.png","language":"Rust","funding_links":[],"categories":["Rust","others"],"sub_categories":[],"readme":"# cargo-instruments\n\nEasily profile your rust crate with Xcode [Instruments].\n\n`cargo-instruments` is the glue between Cargo and Xcode's bundled profiling\nsuite. It allows you to easily profile any binary in your crate, generating\nfiles that can be viewed in the Instruments app.\n\n![Instruments Time Profiler](https://raw.githubusercontent.com/cmyr/cargo-instruments/screenshots/instruments_time1.png)\n![Instruments System Trace](https://raw.githubusercontent.com/cmyr/cargo-instruments/screenshots/instruments_sys1.png)\n\n## Pre-requisites\n\n### Xcode Instruments\n\nThis crate only works on macOS because it uses [Instruments] for profiling\nand creating the trace file. The benefit is that Instruments provides great\ntemplates and UI to explore the Profiling Trace.\n\nTo install Xcode Instruments, simply install the Command Line Tools:\n\n```sh\n$ xcode-select --install\n```\n\n### Compatibility\n\nThis crate works on macOS 10.13+. In practice, it transparently detects and\nuses the appropriate Xcode Instruments version based on your macOS version:\neither `/usr/bin/instruments` on older macOS, or starting with macOS 10.15, the\nnew `xcrun xctrace`.\n\n## Installation\n\n### brew\n\nThe simplest way to install is via Homebrew:\n\n```sh\n$ brew install cargo-instruments\n```\n\nAlternatively, you can install from source.\n\n### Building from Source\n\nFirst, ensure that you are running macOS, with Cargo, Xcode, and the Xcode\nCommand Line Tools installed.\n\nIf OpenSSL is installed (e.g., via `brew`), then install with\n\n```sh\n$ cargo install cargo-instruments\n```\n\nIf OpenSSL is not installed or if `cargo install` fails with an error message starting with \"Could not find directory of OpenSSL installation, and this `-sys` crate cannot proceed without this knowledge,\" then install with\n\n```sh\n$ cargo install --features vendored-openssl cargo-instruments\n```\n\n#### Building from Source on nix\n\nIf you're using [nix](https://nixos.org/guides/install-nix.html), this command should provide all dependencies and build `cargo-instruments` from source:\n\n```sh\n$ nix-shell --command 'cargo install cargo-instruments' --pure -p \\\n\tdarwin.apple_sdk.frameworks.SystemConfiguration \\\n\tdarwin.apple_sdk.frameworks.CoreServices \\\n\trustc cargo sccache libgit2 pkg-config libiconv \\\n\tllvmPackages_13.libclang openssl\n```\n\n## Usage\n\n### Basic\n\n`cargo-instruments` requires a binary target to run. By default, it will try to\nbuild the current crate's `main.rs`. You can specify an alternative binary by\nusing the `--bin` or `--example` flags, or a benchmark target with the `--bench`\nflag.\n\nAssuming your crate has one binary target named `mybin`, and you want to profile\nusing the `Allocations` Instruments template:\n\n_Generate a new trace file_ (by default saved in `target/instruments`)\n\n```sh\n$ cargo instruments -t Allocations\n```\n\n_Open the trace file in Instruments.app manually_\n\nBy default the trace file will immediately be opened with `Instruments.app`. If you do not want this behavior use the `--no-open` flag.\n\n```sh\n$ open target/instruments/mybin_Allocations_2021-05-09T12_34_56.trace\n```\n\nIf there are multiple packages, you can specify the package to profile with\nthe `--package` flag.\n\nFor example, you use Cargo's workspace to manage multiple packages. To profile\nthe bin `bar` of the package `foo`:\n\n```sh\n$ cargo instruments --package foo --template alloc --bin bar\n```\n\nIn many cases, a package only has one binary. In this case `--package` behaves the\nsame as `--bin`.\n\n### Profiling application in release mode\n\nWhen profiling the application in release mode the compiler doesn't provide\ndebugging symbols in the default configuration.\n\nTo let the compiler generate the debugging symbols even in release mode you\ncan append the following section in your `Cargo.toml`.\n\n```toml\n[profile.release]\ndebug = true\n```\n\n### All options\n\nAs usual, thanks to Clap, running `cargo instruments -h` prints the compact help.\n\n```\ncargo-instruments 0.4.8\nProfile a binary with Xcode Instruments.\n\nBy default, cargo-instruments will build your main binary.\n\nUSAGE:\n    cargo instruments [FLAGS] [OPTIONS] --template \u003cTEMPLATE\u003e [ARGS]...\n\nFLAGS:\n    -h, --help                   Prints help information\n    -l, --list-templates         List available templates\n        --no-open                Do not open the generated trace file in Instruments.app\n        --release                Pass --release to cargo\n    -V, --version                Prints version information\n        --all-features           Activate all features for the selected target\n        --no-default-features    Do not activate the default features for the selected target\n\nOPTIONS:\n        --bench \u003cNAME\u003e                 Benchmark target to run\n        --bin \u003cNAME\u003e                   Binary to run\n        --example \u003cNAME\u003e               Example binary to run\n        --features \u003cCARGO-FEATURES\u003e    Features to pass to cargo\n        --manifest-path \u003cPATH\u003e         Path to Cargo.toml\n    -p, --package \u003cNAME\u003e               Specify package for example/bin/bench\n        --profile \u003cNAME\u003e               Pass --profile NAME to cargo\n    -t, --template \u003cTEMPLATE\u003e          Specify the instruments template to run\n        --time-limit \u003cMILLIS\u003e          Limit recording time to the specified value (in milliseconds)\n    -o, --output \u003cPATH\u003e                Output .trace file to the given path\n\nARGS:\n    \u003cARGS\u003e...    Arguments passed to the target binary\n\nEXAMPLE:\n    cargo instruments -t time    Profile main binary with the (recommended) Time Profiler.\n```\n\nAnd `cargo instruments --help` provides more detail.\n\n### Templates\n\nInstruments has the concept of 'templates', which describe sets of dtrace\nprobes that can be enabled. You can ask `cargo-instruments` to list available\ntemplates, including your custom ones (see help above). If you don't provide a\ntemplate name, you will be prompted to choose one.\n\nTypically, the built-in templates are\n\n    built-in            abbrev\n    --------------------------\n    Activity Monitor\n    Allocations         (alloc)\n    Animation Hitches\n    App Launch\n    Core Data\n    Counters\n    Energy Log\n    File Activity       (io)\n    Game Performance\n    Leaks\n    Logging\n    Metal System Trace\n    Network\n    SceneKit\n    SwiftUI\n    System Trace        (sys)\n    Time Profiler       (time)\n    Zombies\n\n### Examples\n\n```sh\n# View all args and options\n$ cargo instruments --help\n```\n\n```sh\n# View all built-in and custom templates\n$ cargo instruments --list-templates\n```\n\n```sh\n# profile the main binary with the Allocations template\n$ cargo instruments -t alloc\n```\n\n```sh\n# profile examples/my_example.rs, with the Allocations template,\n# for 10 seconds, and open the trace when finished\n$ cargo instruments -t Allocations --example my_example --time-limit 10000 --open\n```\n\n## Resources\n\n[Instruments Help][instruments]\n\n### WWDC videos\n\nThe best source of information about Instruments is likely the various WWDC\nsessions over the years:\n\n- [Profiling in Depth](https://developer.apple.com/videos/play/wwdc2015/412/)\n- [Using Time Profiler in Instruments](https://developer.apple.com/videos/play/wwdc2016/418/)\n- [System Trace in Depth](https://developer.apple.com/videos/play/wwdc2016/411/)\n- [Creating Custom Instruments](https://developer.apple.com/videos/play/wwdc2018/410/)\n\n[instruments]: https://help.apple.com/instruments/mac/10.0/\n[time profiler]: https://help.apple.com/instruments/mac/10.0/#/dev44b2b437\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcmyr%2Fcargo-instruments","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcmyr%2Fcargo-instruments","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcmyr%2Fcargo-instruments/lists"}