[rustc.git] / src / tools / cargo / src / doc / contrib / src / tests / profiling.md

# Benchmarking and Profiling

## Internal profiler

Cargo has a basic, hierarchical profiler built-in. The environment variable
`CARGO_PROFILE` can be set to an integer which specifies how deep in the
profile stack to print results for.

```sh
# Output first three levels of profiling info
CARGO_PROFILE=3 cargo generate-lockfile
```

## Benchmarking

### Benchsuite

Head over to the [`benches`
directory](https://github.com/rust-lang/cargo/tree/master/benches) for more
information about the benchmarking suite.

### Informal benchmarking

The overhead for starting a build should be kept as low as possible
(preferably, well under 0.5 seconds on most projects and systems). Currently,
the primary parts that affect this are:

* Running the resolver.
* Querying the index.
* Checking git dependencies.
* Scanning the local project.
* Building the unit dependency graph.

One way to test this is to use [hyperfine]. This is a tool that can be used to
measure the difference between different commands and settings. Usually this
is done by measuring the time it takes for `cargo build` to finish in a large
project where the build is fresh (no actual compilation is performed). Just
run `cargo build` once before using hyperfine.

[hyperfine]: https://github.com/sharkdp/hyperfine
Commit	Line	Data
0a29b90c FG	1	# Benchmarking and Profiling
	2
	3	## Internal profiler
	4
	5	Cargo has a basic, hierarchical profiler built-in. The environment variable
	6	`CARGO_PROFILE` can be set to an integer which specifies how deep in the
	7	profile stack to print results for.
	8
	9	```sh
	10	# Output first three levels of profiling info
	11	CARGO_PROFILE=3 cargo generate-lockfile
	12	```
	13
	14	## Benchmarking
	15
	16	### Benchsuite
	17
	18	Head over to the [`benches`
	19	directory](https://github.com/rust-lang/cargo/tree/master/benches) for more
	20	information about the benchmarking suite.
	21
	22	### Informal benchmarking
	23
	24	The overhead for starting a build should be kept as low as possible
	25	(preferably, well under 0.5 seconds on most projects and systems). Currently,
	26	the primary parts that affect this are:
	27
	28	* Running the resolver.
	29	* Querying the index.
	30	* Checking git dependencies.
	31	* Scanning the local project.
	32	* Building the unit dependency graph.
	33
	34	One way to test this is to use [hyperfine]. This is a tool that can be used to
	35	measure the difference between different commands and settings. Usually this
	36	is done by measuring the time it takes for `cargo build` to finish in a large
	37	project where the build is fresh (no actual compilation is performed). Just
	38	run `cargo build` once before using hyperfine.
	39
	40	[hyperfine]: https://github.com/sharkdp/hyperfine