From e109e02b125615f45b41072c57aa63eb03850a32 Mon Sep 17 00:00:00 2001
From: Charlie Marsh <charlie.r.marsh@gmail.com>
Date: Sun, 7 Apr 2024 22:48:12 -0400
Subject: [PATCH] Expand documentation in `scripts/bench/__main__.py` (#2875)

Closes https://github.com/astral-sh/uv/issues/1318.
---
 scripts/bench/__main__.py | 48 +++++++++++++++++++++++++++++++++------
 1 file changed, 41 insertions(+), 7 deletions(-)

diff --git a/scripts/bench/__main__.py b/scripts/bench/__main__.py
index a08c1ff31..8e87c262f 100644
--- a/scripts/bench/__main__.py
+++ b/scripts/bench/__main__.py
@@ -1,11 +1,11 @@
 """Benchmark uv against other packaging tools.
 
-This script assumes that `pip`, `pip-tools`, `virtualenv`, `poetry` and `hyperfine` are
-installed, and that a uv release builds exists at `./target/release/uv`
-(relative to the repository root).
-
 This script assumes that Python 3.12 is installed.
 
+By default, this script also assumes that `pip`, `pip-tools`, `virtualenv`, `poetry` and
+`hyperfine` are installed, and that a uv release builds exists at `./target/release/uv`
+(relative to the repository root). However, the set of tools is configurable.
+
 To set up the required environment, run:
 
     cargo build --release
@@ -13,17 +13,51 @@ To set up the required environment, run:
     source .venv/bin/activate
     ./target/release/uv pip sync ./scripts/bench/requirements.txt
 
-Example usage:
+Then, to benchmark uv against `pip-tools`:
 
     python -m scripts.bench --uv --pip-compile requirements.in
 
-Multiple versions of uv can be benchmarked by specifying the path to the binary for
-each build, as in:
+It's most common to benchmark multiple uv versions against one another by building
+from multiple branches and specifying the path to each binary, as in:
 
+    # Build the baseline version.
+    git checkout main
+    cargo build --release
+    mv ./target/release/uv ./target/release/baseline
+
+    # Build the feature version.
+    git checkout feature
+    cargo build --release
+
+    # Run the benchmark.
     python -m scripts.bench \
         --uv-path ./target/release/uv \
         --uv-path ./target/release/baseline \
         requirements.in
+
+By default, the script will run the resolution benchmarks when a `requirements.in` file
+is provided, and the installation benchmarks when a `requirements.txt` file is provided:
+
+    # Run the resolution benchmarks against the Trio project.
+    python -m scripts.bench \
+        --uv-path ./target/release/uv \
+        --uv-path ./target/release/baseline \
+        ./scripts/requirements/trio.in
+
+    # Run the installation benchmarks against the Trio project.
+    python -m scripts.bench \
+        --uv-path ./target/release/uv \
+        --uv-path ./target/release/baseline \
+        ./scripts/requirements/compiled/trio.txt
+
+You can also specify the benchmark to run explicitly:
+
+    # Run the "uncached install" benchmark against the Trio project.
+    python -m scripts.bench \
+        --uv-path ./target/release/uv \
+        --uv-path ./target/release/baseline \
+        --benchmark install-cold \
+        ./scripts/requirements/compiled/trio.txt
 """
 
 import abc