diff --git a/docs/src/performance.md b/docs/src/performance.md index 10c7b383447..e51ae6b9511 100644 --- a/docs/src/performance.md +++ b/docs/src/performance.md @@ -1,4 +1,4 @@ - + # Performance Profiling Tutorial @@ -56,6 +56,47 @@ Hyperfine provides summary statistics including: Look for consistent patterns rather than focusing on individual runs, and be aware of system noise that might affect results. +## Integrated Benchmarking + +Utilities include integrated benchmarks in `src/uu/*/benches/*` using [CodSpeed](https://codspeed.io/) and [Divan](https://github.com/nvzqz/divan). + +**Important**: Before starting performance optimization work, you should add a benchmark for the utility. This provides a baseline for measuring improvements and ensures changes have measurable impact. + +### Running Benchmarks + +```bash +# Build and run benchmarks for a specific utility +cargo codspeed build -p uu_expand +cargo codspeed run -p uu_expand +``` + +### Writing Benchmarks + +Use common functions from `src/uucore/src/lib/features/benchmark.rs`: + +```rust +use divan::{Bencher, black_box}; +use uu_expand::uumain; +use uucore::benchmark::{create_test_file, run_util_function, text_data}; + +#[divan::bench(args = [10_000, 100_000])] +fn bench_expand(bencher: Bencher, num_lines: usize) { + let data = text_data::generate_ascii_data(num_lines); + let temp_dir = tempfile::tempdir().unwrap(); + let file_path = create_test_file(&data, temp_dir.path()); + + bencher.bench(|| { + black_box(run_util_function(uumain, &[file_path.to_str().unwrap()])); + }); +} + +fn main() { + divan::main(); +} +``` + +Common helpers include `text_data::generate_*()` for test data and `fs_tree::create_*()` for directory structures. + ## Using Samply for Profiling [Samply](https://github.com/mstange/samply) is a sampling profiler that helps you identify performance bottlenecks in your code.