cargo-samply 0.3.3

A cargo subcommand to automate the process of running samply for project binaries
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134

# Cargo Samply

[![Continuous integration](https://github.com/PhilippPolterauer/cargo-samply/actions/workflows/ci.yml/badge.svg)](https://github.com/PhilippPolterauer/cargo-samply/actions/workflows/ci.yml)
[![docs.rs](https://img.shields.io/docsrs/cargo-samply/latest)](https://docs.rs/cargo-samply)
![GitHub License](https://img.shields.io/github/license/PhilippPolterauer/cargo-samply?style=flat&link=https%3A%2F%2Fgithub.com%2FPhilippPolterauer%2Fcargo-samply%3Ftab%3DMIT-1-ov-file)

A cargo subcommand to automate the process of running `cargo build` with a certain profile and `samply` afterwards.
This tool simplifies profiling Rust applications by managing build profiles and coordinating with the `samply` profiler.

## Installation

You can install it from crates.io or directly from github.com:

```bash
# Install cargo-samply
cargo install cargo-samply

# Install samply (required dependency)
cargo install samply
```

Or install from git:

```bash
cargo install --git https://github.com/PhilippPolterauer/cargo-samply.git
```

**Note**: You must have `samply` installed and available in your PATH for profiling to work.

## Usage

```console
$ cargo samply --help
The samply subcommand

Usage: cargo samply [OPTIONS] [TRAILING_ARGUMENTS]...

Arguments:
  [TRAILING_ARGUMENTS]...  Trailing arguments passed to the binary being profiled

Options:
  -p, --profile <PROFILE>    Build with the specified profile [default: samply]
  -b, --bin <BIN>            Binary to run
  -e, --example <EXAMPLE>    Example to run
  -f, --features <FEATURES>  Build features to enable
      --no-default-features  Disable default features
  -v, --verbose              Print extra output to help debug problems
  -q, --quiet                Suppress all output except errors
  -n, --no-samply            Disable the automatic samply start
  -h, --help                 Print help
  -V, --version              Print version

```

## Example Usage

### Basic Profiling

A minimal example on how to use `cargo-samply`.

```console
$ cargo install cargo-samply
$ cargo new mybinary
     Created binary (application) `mybinary` package
$ cd mybinary
$ cargo samply
```

When opening the server address (127.0.0.1:3001) the output should look like the following:

![Samply Web View](https://raw.githubusercontent.com/PhilippPolterauer/cargo-samply/main/doc/samply-web.png)

### Advanced Usage

```bash
# Profile a specific binary
cargo samply --bin my-binary

# Profile an example
cargo samply --example my-example

# Use a different profile
cargo samply --profile release

# Enable specific features
cargo samply --features feature1,feature2

# Run with verbose output
cargo samply --verbose

# Just run the binary without profiling
cargo samply --no-samply

# Pass arguments to the binary
cargo samply -- arg1 arg2 --flag value
```

## Development

This project includes a `justfile` for common development tasks. Install [just](https://github.com/casey/just) and use:

```bash
# Run tests (matches CI configuration)
just test

# Update test snapshots when needed
just test-overwrite

# Clean all target directories
just clean-all

# Clean only test project target directories
just clean

# Clean only main project
just clean-main
```

### Testing

The project uses `trycmd` for integration testing, which validates CLI behavior against snapshot files.
When making changes that affect command output:

1. Run `just test` to see if tests pass
2. If output has changed intentionally, run `just test-overwrite` to update snapshots
3. Review the changes in git to ensure they're correct

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run `just test` to ensure tests pass
5. Submit a pull request