### Install via Nix

Source: https://github.com/cmyr/cargo-instruments/blob/main/README.md

Use nix-shell to provide dependencies and build from source.

```sh
$ nix-shell --command 'cargo install cargo-instruments' --pure -p \
	darwin.apple_sdk.frameworks.SystemConfiguration \
	darwin.apple_sdk.frameworks.CoreServices \
	rustc cargo sccache libgit2 pkg-config libiconv \
	llvmPackages_13.libclang openssl
```

--------------------------------

### Install via Homebrew

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/README.md

Installs the cargo-instruments binary using the Homebrew package manager.

```bash
brew install cargo-instruments
```

--------------------------------

### Install cargo-instruments via Cargo

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/project-overview.md

Standard installation method using the Rust package manager.

```bash
cargo install cargo-instruments
```

```bash
cargo install --features vendored-openssl cargo-instruments
```

--------------------------------

### Trace File Example

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/configuration.md

A concrete example of a generated trace file name.

```text
myapp_Time-Profiler_2024-01-15_143025-123.trace
```

--------------------------------

### Install via Cargo

Source: https://github.com/cmyr/cargo-instruments/blob/main/README.md

Install from source using Cargo. Use the vendored-openssl feature if OpenSSL is missing or installation fails.

```sh
$ cargo install cargo-instruments
```

```sh
$ cargo install --features vendored-openssl cargo-instruments
```

--------------------------------

### Profile workspace package example

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/README.md

Targets a specific package and example within a workspace using the allocation profiler.

```bash
cargo instruments -p mypackage --example myexample -t alloc
```

--------------------------------

### Install via Homebrew

Source: https://github.com/cmyr/cargo-instruments/blob/main/README.md

Use Homebrew to install the package on macOS.

```sh
$ brew install cargo-instruments
```

--------------------------------

### Execute Profiling Command

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-instruments.md

Example of constructing and executing a profiling command for a binary.

```rust
let xcode = XcodeInstruments::detect()?;
let mut cmd = xcode.profiling_command("Time Profiler", Path::new("trace.trace"), Some(30000))?;
cmd.arg("/path/to/binary").arg("binary_arg");
let output = cmd.output()?;
```

--------------------------------

### Install with vendored OpenSSL

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/configuration.md

Use this command to install cargo-instruments with a vendored copy of OpenSSL when the system version is unavailable.

```bash
cargo install --features vendored-openssl cargo-instruments
```

--------------------------------

### Combined Profiling Example

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-opt.md

A complex command demonstrating multiple flags used in conjunction.

```bash
# Complex example: workspace package, custom features, release mode, time limit, custom output
$ cargo instruments -p foo --bin bar -t time \
    --release \
    --features "feature1 feature2" \
    --time-limit 30000 \
    -o ~/profiling/my_trace.trace \
    -- arg1 arg2 arg3
```

--------------------------------

### Verify Xcode Instruments Installation

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/errors.md

Commands to verify the installation of Xcode Instruments based on the macOS version.

```bash
xctrace --version  # For macOS 10.15+
instruments -h    # For macOS 10.13-10.14
```

--------------------------------

### List available templates

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/configuration.md

Displays all available Instruments templates and exits without starting a profiling session.

```bash
cargo instruments --list-templates
```

--------------------------------

### Verify Xcode Templates

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/errors.md

Commands to manually list available Xcode templates to verify the installation is functional.

```bash
xcrun xctrace list templates    # macOS 10.15+
instruments -s templates       # macOS 10.13-10.14
```

--------------------------------

### Profile Binaries with Cargo Instruments

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/project-overview.md

Examples of profiling different targets using various templates and time limits.

```bash
# Profile main binary with Time Profiler
cargo instruments -t time

# Profile example binary
cargo instruments -t alloc --example my_example --time-limit 10000

# Profile from specific workspace package
cargo instruments -p foo --bin bar -t sys
```

--------------------------------

### Get Package from AppConfig

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-opt.md

Retrieves the package configuration based on CLI input.

```rust
fn get_package(&self) -> Package
```

--------------------------------

### Demangled symbol example

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-demangle.md

Example of the same symbol after being processed by the demangle module.

```text
<alloc::vec::Vec<T, A> as alloc::vec::spec_extend::SpecExtend<T, I>>::spec_extend
```

--------------------------------

### Mangled symbol example

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-demangle.md

Example of a mangled Rust symbol as it appears before processing.

```text
_$LT$alloc..vec..Vec$LT$T$C$A$GT$$u20$as$u20$alloc..vec..spec_extend..SpecExtend$LT$T$C$I$GT$$GT$::spec_extend::hb9d6b49df4cfa5e3
```

--------------------------------

### Target Selection

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-opt.md

Commands for profiling specific project targets like examples, binaries, or benchmarks.

```bash
# Profile a specific example
$ cargo instruments -t alloc --example my_example

# Profile a specific binary
$ cargo instruments -t time --bin my_binary

# Profile a benchmark
$ cargo instruments -t sys --bench my_bench
```

--------------------------------

### Retrieve Available Profiling Templates

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-instruments.md

Queries the installed Instruments for a list of available profiling templates.

```rust
let xcode = XcodeInstruments::detect()?;
let catalog = xcode.available_templates()?;
println!("{}", render_template_catalog(&catalog));
```

--------------------------------

### Workspace package profiling

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/configuration.md

Profiles a specific example within a workspace package using the System Trace template.

```bash
cargo instruments -p mypackage --example myexample -t sys
```

--------------------------------

### Get Target from AppConfig

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-opt.md

Determines the build target based on CLI flags with specific priority order.

```rust
fn get_target(&self) -> Target
```

--------------------------------

### Get macOS Version Signature

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-instruments.md

Signature for the function that retrieves and parses the current macOS version.

```rust
fn get_macos_version() -> Result<Version>
```

--------------------------------

### Detect Xcode Instruments Version

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-instruments.md

Detects the installed version of Xcode Instruments by validating system binaries.

```rust
let xcode = XcodeInstruments::detect()?;
println!("Using: {}", xcode);
```

--------------------------------

### Xcode-select reset command

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/errors.md

Command used to reset Xcode developer directory paths when Xcode or CLT installations are problematic.

```bash
xcode-select --reset
```

--------------------------------

### View help documentation

Source: https://github.com/cmyr/cargo-instruments/blob/main/README.md

Displays the command-line help and usage information.

```text
Profile a binary with Xcode Instruments.

By default, cargo-instruments will build your main binary.

Usage: cargo instruments [OPTIONS] [ARGS]...

Arguments:
  [ARGS]...
          Arguments passed to the target binary.

          To pass flags, precede child args with `--`,
          e.g. `cargo instruments -- -t test1.txt --slow-mode`.

Options:
  -l, --list-templates             List available templates
  -t, --template <TEMPLATE>        Specify the instruments template to run
  -p, --package <NAME>             Specify package for example/bin/bench
      --example <NAME>             Example binary to run
      --bin <NAME>                 Binary to run
      --bench <NAME>               Benchmark target to run
      --release                    Pass --release to cargo
      --profile <NAME>             Pass --profile NAME to cargo
  -o, --output <PATH>              Output .trace file to the given path
      --time-limit <MILLIS>        Limit recording time to the specified value (in milliseconds)
      --no-open                    Do not open the generated trace file in Instruments.app
      --features <CARGO-FEATURES>  Features to pass to cargo
      --manifest-path <PATH>       Path to Cargo.toml
  -h, --help                       Print help (see a summary with '-h')
      --all-features               Activate all features for the selected target
      --no-default-features        Do not activate the default features for the selected target
      --no-demangle                Do not demangle Rust symbols in the profiling output

EXAMPLE:
    cargo instruments -t time    Profile main binary with the (recommended) Time Profiler.
```

--------------------------------

### Initialize AppConfig with minimal arguments

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-opt.md

Demonstrates the default state of the application configuration when only the required template argument is provided.

```rust
let opts = AppConfig::parse_from(["instruments", "-t", "time"]);
// Defaults:
// - list_templates: false
// - template_name: Some("time")
// - package: None → Package::Default
// - target: None → Target::Default
// - release: false → "dev" profile
// - trace_filepath: None → auto-generate in target/instruments/
// - time_limit: None → no limit
// - no_open: false → trace opens automatically
// - features: None → use default features
// - no_demangle: false → symbols will be demangled
// - target_args: vec![] → no arguments passed to binary
```

--------------------------------

### View help and templates

Source: https://github.com/cmyr/cargo-instruments/blob/main/README.md

Commands to display help information or list available profiling templates.

```sh
# View all args and options
$ cargo instruments --help
```

```sh
# View all built-in and custom templates
$ cargo instruments --list-templates
```

--------------------------------

### Access Command-Line Help and Templates

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/configuration.md

Use these commands to view help documentation or list available profiling templates.

```bash
# Brief help
cargo instruments -h

# Detailed help with examples
cargo instruments --help

# List available templates
cargo instruments --list-templates
```

--------------------------------

### Package and Profile Configuration

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-opt.md

Options for workspace package targeting and build profile selection.

```bash
# Profile binary from specific package in workspace
$ cargo instruments -p mypackage -t time --bin mybin

# Profile in release mode
$ cargo instruments -t time --release

# Profile with custom profile
$ cargo instruments -t time --profile custom-profile
```

--------------------------------

### Execute Profiling Workflow

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-app.md

Demonstrates the entry point for the profiling workflow using parsed CLI configuration.

```rust
use cargo_instruments::opt::AppConfig;
use clap::Parser;

// Parse CLI arguments (normally done in main.rs)
let args = AppConfig::parse();

// Run the profiling workflow
match app::run(args) {
    Ok(()) => {
        // Trace file generated and opened successfully
    }
    Err(e) => {
        eprintln!("Profiling failed: {}", e);
        std::process::exit(1);
    }
}
```

--------------------------------

### launch_instruments

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-app.md

Opens a generated .trace file in Xcode Instruments.

```APIDOC
## launch_instruments(trace_filepath: &Path)

### Description
Opens the generated `.trace` file in Xcode Instruments using the system `open` command. This is the default behavior unless `--no-open` is passed.

### Parameters
- **trace_filepath** (&Path) - Required - Full path to the generated `.trace` file

### Return Type
`Result<()>` - Returns `Ok(())` on successful launch.

### Error Cases
- `open` command not found or fails: "open failed"
```

--------------------------------

### Basic CLI Usage

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-opt.md

Commands for basic profiling and template discovery.

```bash
# Profile main binary with Time Profiler
$ cargo instruments -t time

# Show available templates
$ cargo instruments --list-templates
```

--------------------------------

### Launch Xcode Instruments

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-app.md

Opens a specified .trace file in Xcode Instruments using the system open command.

```rust
fn launch_instruments(trace_filepath: &Path) -> Result<()>
```

--------------------------------

### Prepare trace file path

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-instruments.md

Generates the output trace file path based on user input or a default naming convention.

```text
target/instruments/{binary_name}_{template_name}_{YYYY-MM-DD_HHMMSS-millis}.trace
```

--------------------------------

### Implement Display for Package

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/types.md

Defines string representation for package selection.

```rust
impl Display for Package {
    // Default → "Default: search all packages for example/bin/bench"
    // Package("foo") → "foo"
}
```

--------------------------------

### Custom output path and manual open

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/configuration.md

Profiles using the Allocations template, saves the output to a specific path, and prevents automatic opening of the trace file.

```bash
cargo instruments -t alloc -o ~/profiling/trace.trace --no-open
```

--------------------------------

### Define AppConfig Struct

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/types.md

Parsed CLI arguments and configuration produced by clap.

```rust
pub(crate) struct AppConfig {
    pub(crate) list_templates: bool,
    pub(crate) template_name: Option<String>,
    pub(crate) package: Option<String>,
    pub(crate) example: Option<String>,
    pub(crate) bin: Option<String>,
    pub(crate) bench: Option<String>,
    pub(crate) release: bool,
    pub(crate) profile: Option<String>,
    pub(crate) trace_filepath: Option<PathBuf>,
    pub(crate) time_limit: Option<usize>,
    pub(crate) open: bool,
    pub(crate) no_open: bool,
    pub(crate) features: Option<String>,
    pub(crate) manifest_path: Option<PathBuf>,
    pub(crate) all_features: bool,
    pub(crate) no_default_features: bool,
    pub(crate) no_demangle: bool,
    pub(crate) target_args: Vec<String>,
}
```

--------------------------------

### Profile with specific templates and limits

Source: https://github.com/cmyr/cargo-instruments/blob/main/README.md

Commands to profile binaries using specific templates, with optional time limits and automatic opening.

```sh
# profile the main binary with the Allocations template
$ cargo instruments -t alloc
```

```sh
# profile examples/my_example.rs, with the Allocations template,
# for 10 seconds, and open the trace when finished
$ cargo instruments -t Allocations --example my_example --time-limit 10000 --open
```

--------------------------------

### Profile with all features and custom profile

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/configuration.md

Builds the project with all features enabled using a custom Cargo profile named 'profiling'.

```bash
cargo instruments -t time --all-features --profile=profiling
```

--------------------------------

### Profile main binary with Time Profiler

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/README.md

Executes the time profiler on the primary binary of the current project.

```bash
cargo instruments -t time
```

--------------------------------

### Construct Profiling Command

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-instruments.md

Builds a system command for profiling a binary using a specific template.

```sh
xcrun xctrace record --template "Template Name" \
    [--time-limit Nms] \
    --output /path/to/output.trace \
    [--target-stdin /dev/ttyXX --target-stdout /dev/ttyXX] \
    --launch -- <binary> [args...]
```

```sh
instruments -t "Template Name" \
    -D /path/to/output.trace \
    [-l N] \
    <binary> [args...]
```

--------------------------------

### Run Project Tests

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/project-overview.md

Executes the unit test suite for the codebase.

```bash
cargo test
```

--------------------------------

### Generate a trace file

Source: https://github.com/cmyr/cargo-instruments/blob/main/README.md

Creates a new trace file using the specified Instruments template.

```sh
$ cargo instruments -t Allocations
```

--------------------------------

### Convert AppConfig to CargoOpts

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/types.md

Demonstrates the conversion of parsed application configuration into compilation options.

```rust
let app_config = AppConfig::parse();
let cargo_opts = app_config.to_cargo_opts()?;
// cargo_opts.profile = "release" (if --release passed)
// cargo_opts.target = Target::Bin("foo") (if --bin foo passed)
```

--------------------------------

### Target Type Definitions

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/INDEX.md

Enumerations for defining build targets and package selection.

```text
Target (enum)
 ├─ Default
 ├─ Bin(String)
 ├─ Example(String)
 └─ Bench(String)

Package (enum)
 ├─ Default
 └─ Package(String)
```

--------------------------------

### Profile in release mode with time limit

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/README.md

Runs the profiler in release mode with a specified duration limit in milliseconds.

```bash
cargo instruments -t time --release --time-limit 30000
```

--------------------------------

### Symbol Handling and Binary Arguments

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-opt.md

Configuration for symbol demangling and passing arguments directly to the profiled binary.

```bash
# Do not demangle Rust symbols
$ cargo instruments -t time --no-demangle

# Pass arguments to the profiled binary
$ cargo instruments -t time -- --binary-arg1 value1 --binary-arg2 value2
```

--------------------------------

### Render TemplateCatalog to string

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-instruments.md

Formats the template catalog into a human-readable two-column table for terminal output.

```rust
pub fn render_template_catalog(catalog: &TemplateCatalog) -> String
```

```rust
let catalog = xcode.available_templates()?;
let output = render_template_catalog(&catalog);
println!("{}", output);
// Outputs:
// Xcode Instruments templates:
//
// built-in                abbrev
// --------------------------------
// Time Profiler           (time)
// Allocations             (alloc)
// ...
```

--------------------------------

### Parse CLI arguments

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-opt.md

Demonstrates how to parse the command-line arguments into the Cli enum structure.

```rust
use clap::Parser;
let opt::Cli::Instruments(args) = opt::Cli::parse();
```

--------------------------------

### Open trace file manually

Source: https://github.com/cmyr/cargo-instruments/blob/main/README.md

Opens a generated trace file in Instruments.app.

```sh
$ open target/instruments/mybin_Allocations_2021-05-09T12_34_56.trace
```

--------------------------------

### Manual build verification command

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/errors.md

Standard cargo command to verify build integrity when automated build steps fail.

```bash
cargo build
```

--------------------------------

### Specify target for profiling

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/errors.md

Use the --bin flag to select a specific binary when multiple targets are present.

```bash
cargo instruments -t time --bin mybin
```

--------------------------------

### Output and Time Control

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-opt.md

Options for defining trace output paths, recording duration, and automatic file opening behavior.

```bash
# Specify custom output path
$ cargo instruments -t time -o /tmp/trace.trace

# Limit recording to 10 seconds
$ cargo instruments -t time --time-limit 10000

# Do not open trace file automatically
$ cargo instruments -t time --no-open
```

--------------------------------

### List templates command

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/errors.md

Command to verify available template names when template-related errors occur.

```bash
--list-templates
```

--------------------------------

### Profile specific package and binary

Source: https://github.com/cmyr/cargo-instruments/blob/main/README.md

Targets a specific package and binary within a workspace.

```sh
$ cargo instruments --package foo --template alloc --bin bar
```

--------------------------------

### Execute profile_target function

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-instruments.md

Runs the profiler on a target binary using the provided configuration and workspace context.

```rust
pub(crate) fn profile_target(
    target_filepath: &Path,
    xctrace_tool: &XcodeInstruments,
    app_config: &AppConfig,
    workspace: &Workspace,
) -> Result<PathBuf>
```

```rust
let target = Path::new("target/debug/mybin");
let xcode = XcodeInstruments::detect()?;
let app_config = AppConfig { template_name: Some("time".into()), .. };
let workspace = Workspace::new(&manifest_path, &config)?;

let trace_path = profile_target(&target, &xcode, &app_config, &workspace)?;
println!("Trace file: {}", trace_path.display());
// Outputs: target/instruments/mybin_Time-Profiler_2024-01-15_143025-123.trace
```

--------------------------------

### Feature Configuration

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-opt.md

Commands to manage cargo features during the profiling process.

```bash
# Enable specific features
$ cargo instruments -t time --features "feature1 feature2"

# Enable all features
$ cargo instruments -t time --all-features

# Disable default features
$ cargo instruments -t time --no-default-features
```

--------------------------------

### Configuration Type Hierarchy

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/INDEX.md

Visual representation of the conversion from CLI enum variants to the internal AppConfig and CargoOpts structures.

```text
Cli (enum)
  └─ Instruments variant
       └─ AppConfig (struct)
            ├─ package: Option<String>
            ├─ bin: Option<String>
            ├─ example: Option<String>
            ├─ bench: Option<String>
            ├─ template_name: Option<String>
            ├─ time_limit: Option<usize>
            ├─ trace_filepath: Option<PathBuf>
            ├─ features: Option<String>
            ├─ manifest_path: Option<PathBuf>
            ├─ target_args: Vec<String>
            └─ [flags: bool]
            
             ↓ (converted to)
             
            CargoOpts (struct)
             ├─ package: Package
             ├─ target: Target
             ├─ profile: String
             └─ features: CliFeatures
```

--------------------------------

### Verify Xcode developer directory path

Source: https://github.com/cmyr/cargo-instruments/blob/main/README.md

Check the current active developer directory path to ensure Xcode is correctly configured.

```sh
$ xcode-select --print-path
/Applications/Xcode.app/Contents/Developer
```

--------------------------------

### Define Documentation Structure

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/README.md

Standardized template for module documentation within the project.

```text
1. Module overview
2. Type definitions (if any)
3. Public functions/methods
   - Signature
   - Parameters table
   - Return type
   - Error conditions
   - Usage examples
4. Implementation details
5. Integration notes
```

--------------------------------

### Access TemplateCatalog

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/types.md

Retrieves and displays available templates from the catalog.

```rust
let catalog = xcode.available_templates()?;
println!("{}", render_template_catalog(&catalog));
```

--------------------------------

### Trace File Naming Format

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/configuration.md

The default naming convention for trace files when the --output flag is not provided.

```text
{binary_name}_{template_name}_{YYYY-MM-DD}_{HHMMSS}-{millis}.trace
```

--------------------------------

### codesign

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-app.md

Signs a binary with the necessary entitlements for profiling on ARM64 Macs.

```APIDOC
## codesign(path: &Path, workspace: &Workspace)

### Description
Code-signs the binary with an entitlement plist granting `com.apple.security.get-task-allow`, required for profiling on ARM64 Macs. Creates a temporary `entitlements.plist` in the target directory and applies the code signature.

### Parameters
- **path** (&Path) - Required - Path to the binary executable to sign
- **workspace** (&Workspace) - Required - Workspace for error reporting

### Return Type
`Result<()>` - Returns `Ok(())` on successful signing.

### Error Cases
- Failed to get target directory: "failed to get target directory"
- Entitlements file write fails: I/O error
- `codesign` command fails: "Code signing failed" with stdout/stderr captured
```

--------------------------------

### Configure Cargo debug info settings

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-app.md

Sets the split_debuginfo property to 'packed' to ensure DWARF debug information is embedded in the binary.

```rust
compile_options.build_config.split_debuginfo = 'packed'
```

--------------------------------

### Implement Display for XcodeInstruments

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-instruments.md

Provides a string representation for the XcodeInstruments struct, identifying the underlying binary.

```rust
impl Display for XcodeInstruments {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        // Outputs: "xctrace" or "legacy instruments binary"
    }
}
```

--------------------------------

### Instruments Type Definitions

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/INDEX.md

Structures and enums for managing Xcode instruments and template catalogs.

```text
XcodeInstruments (enum)
 ├─ XcTrace
 └─ InstrumentsBinary

TemplateCatalog (struct)
 ├─ standard_templates: Vec<String>
 └─ custom_templates: Vec<String>
```

--------------------------------

### Cargo Profile Configuration

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/configuration.md

Required Cargo profile setting to ensure DWARF debug information is embedded in the binary.

```toml
[profile.<profile-name>]
split-debuginfo = 'packed'
```

--------------------------------

### Implement Display for Target

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/types.md

Defines string representation for different Cargo target types.

```rust
impl Display for Target {
    // Default → "default"
    // Example("foo") → "foo (example)"
    // Bin("bar") → "bar (bin)"
    // Bench("baz") → "baz (bench)"
}
```

--------------------------------

### Sign ARM64 binaries with codesign

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-app.md

Applies an ad-hoc code signature with the com.apple.security.get-task-allow entitlement. Required for profiling on ARM64 macOS targets.

```rust
#[cfg(target_arch = "aarch64")]
fn codesign(path: &Path, workspace: &Workspace) -> Result<()>
```

--------------------------------

### Time limit configuration flag

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/errors.md

Flag used to adjust profiling duration to prevent timeouts.

```bash
--time-limit
```

--------------------------------

### Pass arguments to profiled binary

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/configuration.md

Passes specific command-line arguments to the binary being profiled after the double-dash separator.

```bash
cargo instruments -t time -- --config myconfig.toml --verbose
```

--------------------------------

### demangle_binary

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-demangle.md

The demangle_binary function is the primary entry point for demangling Rust symbols in a Mach-O binary. It performs in-place patching of symbol tables, invalidates the macOS symbol cache, and processes associated dSYM bundles.

```APIDOC
## demangle_binary

### Description
Demangles Rust symbol names in a Mach-O binary in-place. This function updates the primary symbol table, clears the macOS `coresymbolicationd` cache, and demangles any adjacent dSYM bundles.

### Signature
`pub fn demangle_binary(path: &Path) -> Result<()>`

### Parameters
- **path** (`&Path`) - Required - The file system path to the compiled Mach-O binary executable.

### Return Type
- `Result<()>` - Returns `Ok(())` on success, or an error if the binary is invalid or I/O operations fail.

### Error Cases
- I/O errors if the file cannot be read.
- Parsing errors if the file is not a valid Mach-O binary.
- Errors if load commands cannot be read.

### Example
```rust
use std::path::Path;

let binary_path = Path::new("target/debug/myapp");
demangle_binary(binary_path)?;
```
```

--------------------------------

### Define TemplateCatalog struct

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-instruments.md

Represents the collection of available Xcode Instruments templates.

```rust
pub struct TemplateCatalog {
    pub standard_templates: Vec<String>, // Built-in templates
    pub custom_templates: Vec<String>,   // User-defined templates
}
```

--------------------------------

### Parse xctrace template list

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-instruments.md

Parses output from xcrun xctrace list templates, expecting specific formatted sections for standard and custom templates.

```text
== Standard Templates ==
Time Profiler
Allocations
...

== Custom Templates ==
MyTemplate
```

--------------------------------

### Define MachoInfo struct

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/types.md

Stores metadata extracted from Mach-O binary load commands.

```rust
struct MachoInfo {
    string_regions: Vec<Range<usize>>,
    uuid: Option<String>,
}
```

--------------------------------

### Convert UTF-8 Bytes to Semver Signature

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-instruments.md

Signature for the function that converts raw command output bytes into a semantic version.

```rust
fn semver_from_utf8(version: &[u8]) -> Result<Version>
```

--------------------------------

### Resolve Template Name

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-instruments.md

Maps template abbreviations to their full names. Returns the input string if no abbreviation match is found.

```rust
fn resolve_template_name(template_name: &str) -> &str
```

```rust
assert_eq!(resolve_template_name("time"), "Time Profiler");
assert_eq!(resolve_template_name("Time Profiler"), "Time Profiler");
```

--------------------------------

### Locate dSYM DWARF file

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-demangle.md

Searches for a DWARF file within a dSYM bundle adjacent to the provided binary path.

```rust
let binary = Path::new("target/debug/myapp");
if let Some(dsym_dwarf) = find_dsym_dwarf(binary) {
    println!("Found dSYM: {}", dsym_dwarf.display());
    // Prints: target/debug/myapp.dSYM/Contents/Resources/DWARF/myapp
}
```

--------------------------------

### Define CLI structure with clap

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-opt.md

Defines the top-level cargo subcommand parsing structure using the Parser derive macro.

```rust
#[derive(Parser)]
#[command(bin_name = "cargo")]
pub(crate) enum Cli {
    /// Profile a binary with Xcode Instruments.
    ///
    /// By default, cargo-instruments will build your main binary.
    #[command(
        name = "instruments",
        after_help = "EXAMPLE:\n    cargo instruments -t time    Profile main binary with the (recommended) Time Profiler."
    )]
    Instruments(AppConfig),
}
```

--------------------------------

### render_template_catalog

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-instruments.md

Renders a TemplateCatalog as a human-readable two-column table showing built-in and custom templates with abbreviations.

```APIDOC
## render_template_catalog(catalog: &TemplateCatalog) -> String

### Description
Renders a `TemplateCatalog` as a human-readable two-column table showing built-in and custom templates with abbreviations for terminal display.

### Parameters
- **catalog** (`&TemplateCatalog`) - Required - Template catalog to render

### Return Type
`String` - Formatted template listing

### Example
```rust
let catalog = xcode.available_templates()?;
let output = render_template_catalog(&catalog);
println!("{}", output);
```
```

--------------------------------

### Define CargoOpts struct

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/types.md

Represents cargo-specific compilation options derived from CLI arguments.

```rust
pub(crate) struct CargoOpts {
    pub(crate) package: Package,
    pub(crate) target: Target,
    pub(crate) profile: String,
    pub(crate) features: CliFeatures,
}
```

--------------------------------

### Define TemplateCatalog Struct

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/types.md

Container for available Xcode Instruments profiling templates organized by type.

```rust
pub struct TemplateCatalog {
    standard_templates: Vec<String>,
    custom_templates: Vec<String>,
}
```

--------------------------------

### Enable debug symbols in release mode

Source: https://github.com/cmyr/cargo-instruments/blob/main/README.md

Configures Cargo to generate debug symbols for release builds, which is necessary for accurate profiling.

```toml
[profile.release]
debug = true
```

--------------------------------

### Reset Xcode developer directory path

Source: https://github.com/cmyr/cargo-instruments/blob/main/README.md

Reset the active developer directory path if the current configuration is incorrect.

```sh
$ sudo xcode-select --reset
```

--------------------------------

### Define XcodeInstruments Enum

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/types.md

Represents the version of Xcode Instruments detected on the system.

```rust
pub enum XcodeInstruments {
    XcTrace,           // macOS 10.15+: xcrun xctrace
    InstrumentsBinary, // macOS 10.13-10.14: /usr/bin/instruments
}
```

--------------------------------

### MachoInfo Struct Definition

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-demangle.md

Represents the metadata structure containing symbol string ranges and binary UUID.

```rust
struct MachoInfo {
    /// Byte ranges containing null-terminated symbol name strings.
    /// Typically the `LC_SYMTAB` string table and the `__debug_str` DWARF section.
    string_regions: Vec<Range<usize>>,
    
    /// The binary's UUID from `LC_UUID`, used to invalidate the
    /// `coresymbolicationd` symbol cache after patching.
    uuid: Option<String>,
}
```

--------------------------------

### demangle_macho

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-demangle.md

Parses a Mach-O file, demangles symbols in place, writes the modified binary, and extracts the UUID.

```APIDOC
## Function: `demangle_macho(path: &Path) -> Result<Option<String>>`

### Description
Low-level function that demangles symbols in a single Mach-O file. It parses the Mach-O structure, demangles symbols in place, writes the modified binary back to disk, and retrieves the binary's UUID.

### Parameters
- **path** (`&Path`) - Required - Path to a Mach-O file (binary or dSYM DWARF file)

### Return Type
`Result<Option<String>>` — Returns `Ok(Some(uuid))` if UUID found, `Ok(None)` if not, or error if parsing fails.

### Example
```rust
let uuid = demangle_macho(Path::new("target/debug/app.dSYM/Contents/Resources/DWARF/app"))?;
if let Some(uuid) = uuid {
    println!("Binary UUID: {}", uuid);
}
```
```

--------------------------------

### Demangle symbols in a Mach-O file

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-demangle.md

Processes a Mach-O binary or dSYM file to demangle symbols in-place and extract the UUID.

```rust
// Demangle a standalone DWARF file
let uuid = demangle_macho(Path::new("target/debug/app.dSYM/Contents/Resources/DWARF/app"))?;
if let Some(uuid) = uuid {
    println!("Binary UUID: {}", uuid);
}
```

--------------------------------

### Define Package Enum

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/types.md

Represents package selection in a Cargo workspace.

```rust
pub(crate) enum Package {
    Default,         // Default behavior (all packages or workspace default)
    Package(String), // Specific named package
}
```

--------------------------------

### Demangle a binary executable

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-demangle.md

Use this function to patch mangled Rust symbols in a binary and its dSYM bundle. Requires a valid path to the binary and handles potential I/O or Mach-O parsing errors.

```rust
use std::path::Path;

let binary_path = Path::new("target/debug/myapp");
demangle_binary(binary_path)?;

// After this call:
// - Symbol names in the binary are demangled
// - dSYM bundle (if present) is demangled
// - macOS symbol cache is invalidated
```

--------------------------------

### Parse Mach-O Binary Data

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-demangle.md

Reads a binary file and extracts metadata including string regions and UUID.

```rust
let binary_data = std::fs::read("target/debug/app")?;
let info = parse_macho(&binary_data)?;
println!("String regions: {}", info.string_regions.len());
println!("UUID: {:?}", info.uuid);
```

--------------------------------

### Implement From for Package

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/types.md

Converts the internal Package enum to Cargo-specific types.

```rust
impl From<Package> for Packages {
    // Package::Default → Packages::Default
    // Package::Package(s) → Packages::Packages(vec![s])
}
```

--------------------------------

### Integrate Demangling in app::run

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-demangle.md

Conditional execution of symbol demangling within the application lifecycle, falling back to cache invalidation if disabled.

```rust
if !app_config.no_demangle {
    if let Err(e) = demangle::demangle_binary(&target_filepath) {
        workspace.gctx().shell().warn(format!(
            "failed to demangle symbols: {e:#}\n\
             Note: symbol demangling is experimental..."
        ))?;
    }
} else {
    demangle::just_invalidate_symbol_cache(&target_filepath);
}
```

--------------------------------

### fn parse_macho

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-demangle.md

Parses a Mach-O file's load commands to extract string regions and the binary UUID.

```APIDOC
## fn parse_macho

### Description
Parses a Mach-O file's load commands to extract string regions (from LC_SYMTAB and __debug_str) and the binary UUID (from LC_UUID).

### Signature
`fn parse_macho(data: &[u8]) -> Result<MachoInfo>`

### Parameters
- **data** (`&[u8]`) - Required - Binary file contents

### Return Type
`Result<MachoInfo>` - Parsed Mach-O metadata containing string regions and UUID.

### Example
```rust
let binary_data = std::fs::read("target/debug/app")?;
let info = parse_macho(&binary_data)?;
println!("String regions: {}", info.string_regions.len());
println!("UUID: {:?}", info.uuid);
```
```

--------------------------------

### Abbreviate Template Name

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-instruments.md

Retrieves the abbreviation for a given template name. Returns None if no abbreviation is defined.

```rust
fn abbrev_name(template_name: &str) -> Option<&str>
```

```rust
assert_eq!(abbrev_name("Time Profiler"), Some("time"));
assert_eq!(abbrev_name("Unknown"), None);
```

--------------------------------

### Define CliFeatures struct

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/types.md

Represents cargo feature configuration derived from command-line flags.

```rust
pub struct CliFeatures {
    pub features: IndexSet<InternedString>,
    pub all_features: bool,
    pub uses_default_features: bool,
}
```

--------------------------------

### Parse UUID from Binary Data

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-demangle.md

Extracts a UUID string from raw Mach-O binary data.

```rust
fn parse_uuid(data: &[u8]) -> Option<String>
```

--------------------------------

### demangle_region

Source: https://github.com/cmyr/cargo-instruments/blob/main/_autodocs/api-reference-demangle.md

Walks a specific byte range of null-terminated C strings and demangles Rust symbols in place.

```APIDOC
## Function: `demangle_region(data: &mut [u8], region: Range<usize>) -> usize`

### Description
Walks a region of null-terminated C strings and demangles each mangled Rust symbol in place. If the demangled name is longer than the original, the original mangled name is preserved.

### Parameters
- **data** (`&mut [u8]`) - Required - Mutable reference to the binary file data
- **region** (`Range<usize>`) - Required - Byte range containing null-terminated strings

### Return Type
`usize` — Number of symbol names successfully demangled.

### Example
```rust
let mut data = vec![/* binary data with symbols */];
let count = demangle_region(&mut data, 0..1000);
println!("Demangled {} symbols", count);
```
```