Update README

README.md

@@ -4,10 +4,36 @@ An experimental Python package manager.
 
 ## Usage
 
+To resolve a `requirements.in` file:
+
+```shell
+cargo run -p puffin-cli -- compile requirements.in
+```
+
+To install from a resolved `requirements.txt` file:
+
 ```shell
 cargo run -p puffin-cli -- install requirements.txt
 ```
 
+## Benchmarks
+
+To compare a warm run of `puffin` to `pip`:
+
+```shell
+hyperfine --runs 10 --warmup 3 \
+    "./target/release/puffin-cli install requirements.txt" \
+    "pip install -r requirements.txt"
+```
+
+To compare a cold run of `puffin` to `pip`:
+
+```shell
+hyperfine --runs 10 --warmup 3 \
+    "./target/release/puffin-cli install requirements.txt --no-cache" \
+    "pip install -r requirements.txt --ignore-installed --no-cache-dir"
+```
+
 ## License
 
 Puffin is licensed under either of

crates/puffin-cli/src/commands/compile.rs

@@ -12,6 +12,7 @@ use puffin_resolve::resolve;
 
 use crate::commands::ExitStatus;
 
+/// Resolve a set of requirements into a set of pinned versions.
 pub(crate) async fn compile(src: &Path, cache: Option<&Path>) -> Result<ExitStatus> {
     // Read the `requirements.txt` from disk.
     let requirements_txt = std::fs::read_to_string(src)?;

crates/puffin-cli/src/commands/install.rs

@@ -15,6 +15,7 @@ use puffin_resolve::resolve;
 
 use crate::commands::ExitStatus;
 
+/// Install a set of requirements into the current Python environment.
 pub(crate) async fn install(src: &Path, cache: Option<&Path>) -> Result<ExitStatus> {
     // Read the `requirements.txt` from disk.
     let requirements_txt = std::fs::read_to_string(src)?;
@@ -46,6 +47,7 @@ pub(crate) async fn install(src: &Path, cache: Option<&Path>) -> Result<ExitStat
     };
 
     // Resolve the dependencies.
+    // TODO(charlie): When installing, assume `--no-deps`.
     let resolution = resolve(&requirements, markers, &tags, &client).await?;
 
     // Create a temporary directory, in which we'll store the wheels.

requirements.in

@@ -0,0 +1 @@
+black

requirements.txt

@@ -1 +1,6 @@
-black
+click==8.1.7
+pathspec==0.11.2
+packaging==23.2
+platformdirs==3.11.0
+black==23.9.1
+mypy-extensions==1.0.0