Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Make Windows support more obvious #344

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 42 additions & 23 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,24 @@ wonderful [Inferno](https://github.com/jonhoo/inferno) all-rust flamegraph gener
Windows is getting [dtrace support](https://techcommunity.microsoft.com/t5/Windows-Kernel-Internals/DTrace-on-Windows/ba-p/362902),
so if you try this out please let us know how it goes. :D

## Installation

\[cargo-\]flamegraph supports
- [Linux](#linux): Relies on `perf`
- [MacOS](#macos): Relies on `dtrace`
- [Windows](#windows): Native support with the [blondie](https://github.com/nico-abram/blondie) library. Also works with `dtrace` on Windows.

```
cargo install flamegraph
```

This will make the `flamegraph` and
`cargo-flamegraph` binaries available in your cargo
binary directory. On most systems this is
usually something like `~/.cargo/bin`.

## Linux

**Note**: If you're using lld or mold on Linux, you must use the `--no-rosegment` flag. Otherwise perf will not be able to generate accurate stack traces ([explanation](https://crbug.com/919499#c16)). For example, for lld:

```toml
Expand All @@ -33,19 +51,6 @@ linker = "clang"
rustflags = ["-Clink-arg=-fuse-ld=/usr/local/bin/mold", "-Clink-arg=-Wl,--no-rosegment"]
```

## Installation

```
cargo install flamegraph
```

This will make the `flamegraph` and
`cargo-flamegraph` binaries available in your cargo
binary directory. On most systems this is
usually something like `~/.cargo/bin`.

Requirements on Linux:

#### Debian (x86 and aarch)
**Note**: Debian bullseye (the current stable version as of 2022) packages an outdated version of Rust which does not meet flamegraph's requirements. You should use [rustup](https://rustup.rs/) to install an up-to-date version of Rust, or upgrade to Debian bookworm (the current testing version) or newer.

Expand All @@ -68,6 +73,30 @@ sudo apt install linux-tools-raspi
```bash
sudo apt install linux-tools-common linux-tools-generic
```
## MacOS

#### DTrace on macOS

On macOS, there is no alternative to running as superuser in order to
enable DTrace. This should be done by invoking `sudo flamegraph ...` or
`cargo flamegraph --root ...`. Do not do `sudo cargo flamegraph ...`;
this can cause problems due to Cargo's build system being run as root.

Be aware that if the binary being tested is user-aware, this does
change its behaviour.

## Windows

#### Blondie Backend

This is enabled by default.
Windows is supported out-of-the-box, thanks to [Nicolas Abram](https://github.com/nico-abram)'s excellent [blondie](https://github.com/nico-abram/blondie) library.

#### DTrace on Windows

Alternatively, one can [install DTrace on Windows](https://learn.microsoft.com/en-us/windows-hardware/drivers/devtest/dtrace). If found, flamegraph will always prefer using `dtrace` over the built-in Windows support.
If you try this out please let us know how it goes. :D
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please remove this last sentence.



## Shell auto-completion

Expand Down Expand Up @@ -189,16 +218,6 @@ be acceptable for your security needs etc...
echo -1 | sudo tee /proc/sys/kernel/perf_event_paranoid
```

### DTrace on macOS

On macOS, there is no alternative to running as superuser in order to
enable DTrace. This should be done by invoking `sudo flamegraph ...` or
`cargo flamegraph --root ...`. Do not do `sudo cargo flamegraph ...`;
this can cause problems due to Cargo's build system being run as root.

Be aware that if the binary being tested is user-aware, this does
change its behaviour.

## Improving output when running with `--release`

Due to optimizations etc... sometimes the quality
Expand Down