### Lockfile Format Example

Source: https://context7.com/bytecodealliance/wit-deps/llms.txt

Example of the TOML format for the wit/deps.lock file, which is auto-generated by wit-deps. It includes entries for direct and transitive dependencies, specifying URLs, SHA digests, and dependency lists.

```toml
# wit/deps.lock  (auto-generated — do not edit by hand)

[clocks]
url    = "https://github.com/WebAssembly/wasi-clocks/archive/main.tar.gz"
sha256 = "be1d8c61e2544e2b48d902c60df73577e293349063344ce752cda4d323f8b913"
sha512 = "0fd7962c62b135da0e584c2b58a55147bf09873848b0bb5bd3913019bc3f8d4b5969fbd6f7f96fd99a015efaf562a3eeafe3bc13049f8572a6e13ef9ef0e7e75"
deps   = ["io"]

[http]
url    = "https://github.com/WebAssembly/wasi-http/archive/main.tar.gz"
sha256 = "8af7a05957ee00ee571422ed49554021e60363a167b46894ca7e5c1326bf4f82"
sha512 = "e0a9bcaf77cf5e47d72c7a316895bc064a7745fe914d18d2a44cc2f3a2d260a51d90d0ab06de8234fd339b8af6cd5bc0fee8ffe8d7d20599be333d173dec6f31"
deps   = ["cli", "filesystem", "io", "random"]

# Transitive entry — no url/path source, only digest
[io]
sha256 = "9f1ad5da70f621bbd4c69e3bd90250a0c12ecfde266aa8f99684fc44bc1e7c15"
sha512 = "6d0a9db6848f24762933d1c168a5b5b1065ba838c253ee20454afeb8dd1a049b918d25deff556083d68095dd3126ae131ac3e738774320eee5d918f5a4b5354e"

```

--------------------------------

### TOML Dependency Manifest Example

Source: https://github.com/bytecodealliance/wit-deps/blob/main/README.md

Define WIT dependencies using URLs, tags, or specific revisions with optional SHA digests for integrity.

```toml
# wit/deps.toml
# Use `wit-deps update` to pull in latest changes from "dynamic" branch references
clocks = "https://github.com/WebAssembly/wasi-clocks/archive/main.tar.gz"
http = "https://github.com/WebAssembly/wasi-http/archive/main.tar.gz"
messaging = "https://github.com/WebAssembly/wasi-messaging/archive/main.tar.gz"
sockets = "https://github.com/WebAssembly/wasi-sockets/archive/main.tar.gz"
sql = "https://github.com/WebAssembly/wasi-sql/archive/main.tar.gz"

# Pin to a tag
io = "https://github.com/rvolosatovs/wasi-io/archive/v0.1.0.tar.gz" # this fork renames `streams` interface for compatibility with wasi-snapshot-preview1

# Pin a dependency to a particular revision and source digests. Each digest is optional
[keyvalue]
url = "https://github.com/WebAssembly/wasi-keyvalue/archive/6f3bd6bca07cb7b25703a13f633e05258d56a2dc.tar.gz"
sha256 = "1755b8f1e9f2e70d0bde06198bf50d12603b454b52bf1f59064c1877baa33dff"
sha512 = "7bc43665a9de73ec7bef075e32f67ed0ebab04a1e47879f9328e8e52edfb35359512c899ab8a52240fecd0c53ff9c036abefe549e5fb99225518a2e0446d66e0"

```

--------------------------------

### Implement Custom Cache Backend in Rust

Source: https://context7.com/bytecodealliance/wit-deps/llms.txt

Shows how to implement a custom caching strategy by implementing the `Cache` trait. This example provides a no-operation cache for testing or air-gapped environments.

```rust
use async_trait::async_trait;
use wit_deps::{Cache, cache::Local as LocalCache};
use url::Url;

// Use the built-in local disk cache
fn get_local_cache() -> Option<LocalCache> {
    LocalCache::cache_dir() // returns None if OS cache dir is unavailable
}

// Implement a custom no-op cache (e.g., for testing or air-gapped environments)
struct NoCache;

#[async_trait]
impl Cache for NoCache {
    type Read = tokio::io::Empty;
    type Write = tokio::io::Sink;

    async fn get(&self, _url: &Url) -> anyhow::Result<Option<Self::Read>> {
        Ok(None) // always miss
    }

    async fn insert(&self, _url: &Url) -> anyhow::Result<Self::Write> {
        Ok(tokio::io::sink()) // discard writes
    }
}

#[tokio::main]
async fn main() {
    if let Some(cache) = get_local_cache() {
        println!(/*Cache directory*/"Cache directory: {{}}", cache);
    } else {
        println!(/*No cache available*/"No cache available.");
    }
}

```

--------------------------------

### Unpack WIT files from a tar stream

Source: https://context7.com/bytecodealliance/wit-deps/llms.txt

This low-level utility unpacks `.wit` files from a `tar` archive stream into a specified destination directory. It recognizes WIT files in various path structures and returns a map of transitive dependency identifiers to their installed paths.

```rust
use std::collections::HashSet;
use wit_deps::untar;
use tokio::fs::File;
use async_compression::tokio::bufread::GzipDecoder;
use tokio::io::BufReader;

#[tokio::main]
async fn main() -> std::io::Result<()> {
    let file = File::open("clocks.tar.gz").await?;
    let decoder = GzipDecoder::new(BufReader::new(file));

    // skip_deps: identifiers already present — won't be overwritten
    let skip_deps: HashSet<String> = HashSet::new();

    let transitive = untar(
        decoder,
        "wit/deps/clocks",  // destination directory
        &skip_deps,
        "",                 // prefix within archive, empty = auto-detect
    ).await?;

    for (id, path) in &transitive {
        println!("Transitive dep '{}' at {}", id, path.display());
    }
    Ok(())
}

```

--------------------------------

### untar

Source: https://context7.com/bytecodealliance/wit-deps/llms.txt

Unpacks WIT files from a tar stream into a destination directory. This low-level utility recognizes WIT files in various standard locations within the archive and returns a map of transitive dependency identifiers to their installed paths.

```APIDOC
## Rust function: `untar` — Unpack WIT files from a tar stream

Low-level utility that unpacks `.wit` files from a `tar` archive stream into a destination directory. Recognises WIT files at paths like `wit/*.wit`, `<root>/wit/*.wit`, `deps/<id>/*.wit`, etc. Returns a map of transitive dependency identifiers to their installed paths.

```rust
use std::collections::HashSet;
use wit_deps::untar;
use tokio::fs::File;
use async_compression::tokio::bufread::GzipDecoder;
use tokio::io::BufReader;

#[tokio::main]
async fn main() -> std::io::Result<()> {
    let file = File::open("clocks.tar.gz").await?;
    let decoder = GzipDecoder::new(BufReader::new(file));

    // skip_deps: identifiers already present — won't be overwritten
    let skip_deps: HashSet<String> = HashSet::new();

    let transitive = untar(
        decoder,
        "wit/deps/clocks",  // destination directory
        &skip_deps,
        "",                 // prefix within archive, empty = auto-detect
    ).await?;

    for (id, path) in &transitive {
        println!("Transitive dep '{}' at {}", id, path.display());
    }
    Ok(())
}
```
```

--------------------------------

### Synchronize WIT Dependencies with Manifest

Source: https://context7.com/bytecodealliance/wit-deps/llms.txt

Use `wit-deps lock` to sync the `wit/deps` directory with `wit/deps.toml` and `wit/deps.lock`. Use `--check` in CI to fail if updates are needed. Custom paths for manifest, lockfile, and dependencies can be specified.

```sh
# Basic lock — sync wit/deps with wit/deps.toml (default paths)
wit-deps lock
```

```sh
# Check mode — fail if deps were not already in sync (for CI enforcement)
wit-deps lock --check
```

```sh
# Custom paths
wit-deps lock \
  --manifest custom/deps.toml \
  --lock    custom/deps.lock \
  --deps    custom/deps
```

```sh
# Behind a corporate proxy
export PROXY_SERVER=proxy.corp.example.com:8080
export PROXY_USERNAME='alice'
export PROXY_PASSWORD='s3cret'
wit-deps lock
```

--------------------------------

### TOML Manifest with Local Path and URL

Source: https://github.com/bytecodealliance/wit-deps/blob/main/README.md

Specify WIT dependencies using a local path or a URL with optional digests.

```toml
# wit/deps.toml
mywit = "./path/to/my/wit"

[logging]
url = "https://github.com/WebAssembly/wasi-logging/archive/d106e59b25297d0496e6a5d221ad090e19c3aaa3.tar.gz"
sha256 = "4bb4aeab99e7323b30d107aab78e88b2265c1598cc438bc5fbc0d16bb63e798f"
sha512 = "13b52b59afd98dd4938e3a651fad631d41a2e84ce781df5d8957eded77a8e1ac4277e771a10225cd4a3a9eae369ed7e8fee6e26f9991a2caa7c97c4a758b1ae6"

```

--------------------------------

### Parse and iterate over WIT manifests

Source: https://context7.com/bytecodealliance/wit-deps/llms.txt

Demonstrates how to parse a WIT manifest from a TOML string into `Manifest` and `ManifestEntry` types. It shows how to handle both URL-based and local path-based entries, including optional fields like digests and prefixes for URL entries.

```rust
use wit_deps::{Manifest, manifest::Entry};

fn main() -> anyhow::Result<()> {
    // Parse from TOML string
    let manifest: Manifest = toml::from_str(r#"clocks = "https://github.com/WebAssembly/wasi-clocks/archive/main.tar.gz"

    [http]
    url    = "https://github.com/WebAssembly/wasi-http/archive/main.tar.gz"
    sha256 = "8af7a05957ee00ee571422ed49554021e60363a167b46894ca7e5c1326bf4f82"
    sha512 = "e0a9bcaf77cf5e47d72c7a316895bc064a7745fe914d18d2a44cc2f3a2d260a51d90d0ab06de8234fd339b8af6cd5bc0fee8ffe8d7d20599be333d173dec6f31"

    mywit = "./local/interfaces"
"#)?;

    for (name, entry) in manifest.iter() {
        match entry {
            Entry::Url { url, sha256, prefix, .. } => {
                println!("{name}: URL={url}, pinned={}", sha256.is_some());
            }
            Entry::Path(p) => {
                println!("{name}: local path={}", p.display());
            }
        }
    }
    Ok(())
}

```

--------------------------------

### Package WIT files into a deterministic tar archive

Source: https://context7.com/bytecodealliance/wit-deps/llms.txt

Reads all `.wit` files from a directory and creates a deterministic tar archive with a `wit/` path prefix. This function is useful for packaging WIT dependencies for distribution or archival. It supports writing to a file or directly to stdout.

```rust
use wit_deps::tar;
use tokio::fs::File;

#[tokio::main]
async fn main() -> std::io::Result<()> {
    // Archive to a file
    let output = File::create("my-interface.tar").await?;
    tar("wit/deps/clocks", output).await?;

    // Archive to stdout
    tar("wit/deps/http", tokio::io::stdout()).await?;

    Ok(())
}

```

--------------------------------

### tar

Source: https://context7.com/bytecodealliance/wit-deps/llms.txt

Packages WIT files from a directory into a deterministic tar archive. This function reads all `.wit` files from a specified directory and writes them into a tar archive under the `wit/` path prefix, ensuring no timestamps and sorted file order. It returns the writer after completion.

```APIDOC
## Rust function: `tar` — Package WIT files into a deterministic tar archive

Reads all `.wit` files from a directory and writes them into a deterministic tar archive (no timestamps, sorted file order) under the `wit/` path prefix. Returns the writer after completion.

```rust
use wit_deps::tar;
use tokio::fs::File;

#[tokio::main]
async fn main() -> std::io::Result<()> {
    // Archive to a file
    let output = File::create("my-interface.tar").await?;
    tar("wit/deps/clocks", output).await?;

    // Archive to stdout
    tar("wit/deps/http", tokio::io::stdout()).await?;

    Ok(())
}
```
```

--------------------------------

### Proxy Environment Variables for wit-deps

Source: https://github.com/bytecodealliance/wit-deps/blob/main/README.md

Configure proxy settings for `wit-deps` by exporting these environment variables.

```bash
export PROXY_SERVER={yourproxyaddress}:{port}
export PROXY_USERNAME='{yourproxyusername}'
export PROXY_PASSWORD='{yourproxypassword}'

```

--------------------------------

### Rust build.rs Integration with wit-deps

Source: https://github.com/bytecodealliance/wit-deps/blob/main/README.md

Use the `wit-deps::lock!` macro in your `build.rs` file to automatically manage WIT dependencies.

```rust
wit_deps::lock!();

```

--------------------------------

### Re-fetch and Re-lock All WIT Dependencies

Source: https://context7.com/bytecodealliance/wit-deps/llms.txt

Use `wit-deps update` to ignore the existing lockfile, re-fetch all dependencies from their sources, update `wit/deps`, and write a new `wit/deps.lock`. This is useful for pulling the latest changes from branch-pinned URLs.

```sh
# Re-fetch all deps from their URLs (ignores existing lock)
wit-deps update
```

```sh
# Custom paths
wit-deps update \
  --manifest wit/deps.toml \
  --lock     wit/deps.lock \
  --deps     wit/deps
```

--------------------------------

### lock_sync! macro

Source: https://context7.com/bytecodealliance/wit-deps/llms.txt

A convenience wrapper around `lock!` that spins up a multi-threaded Tokio runtime internally. Requires the default `sync` feature. Ideal for `build.rs` scripts that are not already async.

```APIDOC
## Rust macro: `lock_sync!` — Synchronous build-script integration

A convenience wrapper around `lock!` that spins up a multi-threaded Tokio runtime internally. Requires the default `sync` feature. Ideal for `build.rs` scripts that are not already async.

```rust
// build.rs  (synchronous — no async fn required)
fn main() -> std::io::Result<()> {
    // Locks wit/deps using wit/deps.toml and wit/deps.lock
    wit_deps::lock_sync!()?;

    // Custom WIT directory
    // wit_deps::lock_sync!("my-wit")?;

    Ok(())
}
```
```

--------------------------------

### TOML Manifest: URL Dependencies

Source: https://context7.com/bytecodealliance/wit-deps/llms.txt

Define URL dependencies in `wit/deps.toml` using a TOML format. Entries can be simple URLs or structured with `url`, optional `sha256`/`sha512` digests for verification, and a `prefix` to specify a subdirectory within the archive.

```toml
# wit/deps.toml

# Simple URL — always fetches the latest from this branch reference
clocks = "https://github.com/WebAssembly/wasi-clocks/archive/main.tar.gz"
```

```toml
# Pinned to a specific commit/tag with optional digest verification
[keyvalue]
url    = "https://github.com/WebAssembly/wasi-keyvalue/archive/v0.2.0-draft.tar.gz"
sha256 = "8698bc1d8b4764674b753bb880ea584f453bdadb79fc676ced9eebd1c3d91fd9"
sha512 = "38b9033c581f6e6c5ee1cbceff8fb2167847b46726e8b04b10ae66c97ae592fb2eb585f722efd9d07419651ec21d96fbcc313f156d20734f2fc3e273ba2815ac"
```

```toml
# Multiple deps from a single monorepo tarball — use `prefix` to select subdirectory
cli        = { url = "https://github.com/WebAssembly/WASI/releases/download/v0.2.10/wasi-wit-0.2.10.tar.gz", prefix = "wasi-wit-0.2.10/cli" }
filesystem = { url = "https://github.com/WebAssembly/WASI/releases/download/v0.2.10/wasi-wit-0.2.10.tar.gz", prefix = "wasi-wit-0.2.10/filesystem" }
http       = { url = "https://github.com/WebAssembly/WASI/releases/download/v0.2.10/wasi-wit-0.2.10.tar.gz", prefix = "wasi-wit-0.2.10/http" }
```

--------------------------------

### Force-update dependencies from file paths with `update_path`

Source: https://context7.com/bytecodealliance/wit-deps/llms.txt

Use `update_path` to unconditionally re-fetch all dependencies, ignoring the existing lockfile and always generating a new one. This is useful for picking up changes from branch-pinned URLs. Ensure the `wit_deps` crate is added to your build dependencies.

```rust
use wit_deps::update_path;

#[tokio::main] async fn main() -> anyhow::Result<()> {
    // Re-resolves all deps from scratch, overwriting wit/deps.lock
    update_path(
        "wit/deps.toml",
        "wit/deps.lock",
        "wit/deps",
    ).await?;

    println!("All dependencies updated.");
    Ok(())
}

```

--------------------------------

### TOML Manifest: Local Path Dependencies

Source: https://context7.com/bytecodealliance/wit-deps/llms.txt

Define local path dependencies in `wit/deps.toml` by specifying a directory path. This can be done using a short form with a bare path string or a long form with an explicit `path` key within a TOML table.

```toml
# wit/deps.toml

# Short form: bare path string
mywit = "./path/to/my/wit"
```

```toml
# Long form: explicit path key
[logging]
path = "../shared-interfaces/logging"
```

--------------------------------

### Synchronous build-script integration with `lock_sync!` macro

Source: https://context7.com/bytecodealliance/wit-deps/llms.txt

The `lock_sync!` macro provides synchronous integration for Rust build scripts. It internally manages a Tokio runtime, making it suitable for build scripts that are not already asynchronous. Requires the default `sync` feature.

```rust
// build.rs  (synchronous — no async fn required)
fn main() -> std::io::Result<()> {
    // Locks wit/deps using wit/deps.toml and wit/deps.lock
    wit_deps::lock_sync!()?;

    // Custom WIT directory
    // wit_deps::lock_sync!("my-wit")?;

    Ok(())
}

```

--------------------------------

### Manifest and ManifestEntry

Source: https://context7.com/bytecodealliance/wit-deps/llms.txt

Defines the `Manifest` and `ManifestEntry` types for representing dependency information. `Manifest` is a `HashMap<Identifier, Entry>` deserializable from TOML, and `Entry` is an enum with variants for remote URLs (`Entry::Url`) and local paths (`Entry::Path`).

```APIDOC
## Rust types: `Manifest` and `ManifestEntry`

`Manifest` is a `HashMap<Identifier, Entry>` deserializable from TOML. `Entry` is an enum with two variants: `Entry::Url` (remote gzipped tarball with optional digests and prefix) and `Entry::Path` (local directory). Both can be constructed programmatically.

```rust
use wit_deps::{Manifest, manifest::Entry};

fn main() -> anyhow::Result<()> {
    // Parse from TOML string
    let manifest: Manifest = toml::from_str(r#"\
        clocks = "https://github.com/WebAssembly/wasi-clocks/archive/main.tar.gz"

        [http]
        url    = "https://github.com/WebAssembly/wasi-http/archive/main.tar.gz"
        sha256 = "8af7a05957ee00ee571422ed49554021e60363a167b46894ca7e5c1326bf4f82"
        sha512 = "e0a9bcaf77cf5e47d72c7a316895bc064a7745fe914d18d2a44cc2f3a2d260a51d90d0ab06de8234fd339b8af6cd5bc0fee8ffe8d7d20599be333d173dec6f31"

        mywit = "./local/interfaces"
    "#)?;

    for (name, entry) in manifest.iter() {
        match entry {
            Entry::Url { url, sha256, prefix, .. } => {
                println!("{name}: URL={url}, pinned={}", sha256.is_some());
            }
            Entry::Path(p) => {
                println!("{name}: local path={}", p.display());
            }
        }
    }
    Ok(())
}
```
```

--------------------------------

### lock! macro

Source: https://context7.com/bytecodealliance/wit-deps/llms.txt

The `lock!` macro is the primary way to use `wit-deps` from a Rust `build.rs`. It reads the manifest at compile time, checks the lockfile, fetches missing/outdated dependencies, and writes the lockfile. Must be called inside a Tokio async context.

```APIDOC
## Rust macro: `lock!` — Async build-script integration

The `lock!` macro is the primary way to use `wit-deps` from a Rust `build.rs`. It reads the manifest at compile time, checks the lockfile, fetches missing/outdated dependencies, and writes the lockfile. Must be called inside a Tokio async context.

```rust
// build.rs
use wit_deps::lock;

#[tokio::main]
async fn main() -> std::io::Result<()> {
    // Uses default paths: wit/deps.toml, wit/deps.lock, wit/deps
    lock!().await?;

    // Or specify a custom WIT directory (e.g., "my-wit")
    // lock!("my-wit").await?;

    Ok(())
}
```
```

--------------------------------

### Deserialize and Iterate TOML Lockfile in Rust

Source: https://context7.com/bytecodealliance/wit-deps/llms.txt

Demonstrates deserializing a TOML lockfile string into a `Lock` struct and iterating through its entries. Shows how to access dependency sources, digests, and transitive dependencies.

```rust
use wit_deps::{Lock, lock::Entry as LockEntry, lock::EntrySource};

fn main() -> anyhow::Result<()> {
    let toml_str = r#"[clocks]
url    = "https://github.com/WebAssembly/wasi-clocks/archive/main.tar.gz"
sha256 = "be1d8c61e2544e2b48d902c60df73577e293349063344ce752cda4d323f8b913"
sha512 = "0fd7962c62b135da0e584c2b58a55147bf09873848b0bb5bd3913019bc3f8d4b5969fbd6f7f96fd99a015efaf562a3eeafe3bc13049f8572a6e13ef9ef0e7e75"
deps   = ["io"]

[io]
sha256 = "9f1ad5da70f621bbd4c69e3bd90250a0c12ecfde266aa8f99684fc44bc1e7c15"
sha512 = "6d0a9db6848f24762933d1c168a5b5b1065ba838c253ee20454afeb8dd1a049b918d25deff556083d68095dd3126ae131ac3e738774320eee5d918f5a4b5354e"
"#;

    let lock: Lock = toml::from_str(toml_str)?;

    for (id, entry) in lock.iter() {
        match &entry.source {
            Some(EntrySource::Url { url, .. }) => println!(/*id*/"{{id}}": from {{url}})", url),
            Some(EntrySource::Path { path })   => println!(/*id*/"{{id}}": from {{}}", path.display()),
            None => println!(/*id*/"{{id}}": transitive (no source)"),
        }
        println!(/*sha256*/"  sha256={{}}", hex::encode(entry.digest.sha256));
        println!(/*transitive deps*/"  transitive deps: {{:?}}", entry.deps);
    }

    // Round-trip back to TOML
    let serialized = toml::to_string(&lock)?;
    println!(/*Re-serialized*/"\nRe-serialized:\n{{}}", serialized);
    Ok(())
}

```

--------------------------------

### Force-update dependencies from in-memory strings

Source: https://context7.com/bytecodealliance/wit-deps/llms.txt

Use this low-level function when you have the manifest content as a string and need to generate a fresh lock file. It discards any previously existing lock.

```rust
use wit_deps::update;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let manifest = r#"
http     = "https://github.com/WebAssembly/wasi-http/archive/main.tar.gz"
sockets  = "https://github.com/WebAssembly/wasi-sockets/archive/main.tar.gz"
"#;

    let new_lock = update(
        Some("wit"),   // base path for resolving relative path deps
        manifest,
        "wit/deps",
    ).await?;

    std::fs::write("wit/deps.lock", &new_lock)?;
    println!("New lock:\n{new_lock}");
    Ok(())
}

```

--------------------------------

### Async build-script integration with `lock!` macro

Source: https://context7.com/bytecodealliance/wit-deps/llms.txt

Use the `lock!` macro in Rust build scripts for async integration. It reads the manifest, checks the lockfile, fetches dependencies, and updates the lockfile. Must be called within a Tokio async context.

```rust
// build.rs
use wit_deps::lock;

#[tokio::main] async fn main() -> std::io::Result<()> {
    // Uses default paths: wit/deps.toml, wit/deps.lock, wit/deps
    lock!().await?;

    // Or specify a custom WIT directory (e.g., "my-wit")
    // lock!("my-wit").await?;

    Ok(())
}

```

--------------------------------

### Lock dependencies from file paths with `lock_path`

Source: https://context7.com/bytecodealliance/wit-deps/llms.txt

The `lock_path` function reads manifest and lock files from disk, synchronizes dependencies, and updates the lockfile if necessary. It returns `true` if the lockfile was updated and `false` otherwise. Ensure the `wit_deps` crate is added to your build dependencies.

```rust
use wit_deps::lock_path;

#[tokio::main] async fn main() -> anyhow::Result<()> {
    let updated = lock_path(
        "wit/deps.toml",   // manifest path
        "wit/deps.lock",   // lock path (created if absent)
        "wit/deps",        // output deps directory
    ).await?;

    if updated {
        println!("Dependencies updated.");
    } else {
        println!("Dependencies already in sync.");
    }
    Ok(())
}

```

--------------------------------

### Archive a Dependency's WIT Subtree

Source: https://context7.com/bytecodealliance/wit-deps/llms.txt

Use `wit-deps tar` to archive a specific dependency's WIT subdirectory into a gzipped tarball. The output can be piped to stdout or written to a file using `--output`. Custom dependency directories can be specified with `--deps`.

```sh
# Archive the "http" dependency to stdout (pipe into another tool)
wit-deps tar http | gzip -d | tar -tv
```

```sh
# Write the "clocks" dependency archive to a file
wit-deps tar clocks --output clocks.tar
```

```sh
# Custom deps directory
wit-deps tar --deps custom/deps sockets --output sockets.tar
```

--------------------------------

### lock_path function

Source: https://context7.com/bytecodealliance/wit-deps/llms.txt

Reads a manifest file and an optional lock file from disk, ensures `deps` is in sync, and writes back an updated lockfile when needed. Returns `true` if the lock was updated, `false` if already in sync.

```APIDOC
## Rust function: `lock_path` — Lock from file paths

Reads a manifest file and an optional lock file from disk, ensures `deps` is in sync, and writes back an updated lockfile when needed. Returns `true` if the lock was updated, `false` if already in sync.

```rust
use wit_deps::lock_path;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let updated = lock_path(
        "wit/deps.toml",   // manifest path
        "wit/deps.lock",   // lock path (created if absent)
        "wit/deps",        // output deps directory
    ).await?;

    if updated {
        println!("Dependencies updated.");
    } else {
        println!("Dependencies already in sync.");
    }
    Ok(())
}
```
```

--------------------------------

### update

Source: https://context7.com/bytecodealliance/wit-deps/llms.txt

Force-updates dependencies from in-memory manifest strings. This low-level function takes a manifest string directly and always produces a fresh TOML-encoded lock string, discarding any previously existing lock.

```APIDOC
## Rust function: `update` — Force-update from in-memory strings

Low-level version of `update_path` that takes a manifest string directly and always produces a fresh TOML-encoded lock string, discarding any previously existing lock.

```rust
use wit_deps::update;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let manifest = r#"\
http     = "https://github.com/WebAssembly/wasi-http/archive/main.tar.gz"
sockets  = "https://github.com/WebAssembly/wasi-sockets/archive/main.tar.gz"
"#;

    let new_lock = update(
        Some("wit"),   // base path for resolving relative path deps
        manifest,
        "wit/deps",
    ).await?;

    std::fs::write("wit/deps.lock", &new_lock)?;
    println!("New lock:\n{new_lock}");
    Ok(())
}
```
```

--------------------------------

### Lock dependencies from in-memory strings with `lock`

Source: https://context7.com/bytecodealliance/wit-deps/llms.txt

The `lock` function is a low-level API for locking dependencies using in-memory strings for the manifest and lock contents. It returns a new TOML-encoded lock string if updates were needed, or `None` if already in sync. Useful when manifest/lock content originates from sources other than the filesystem. Ensure the `wit_deps` crate is added to your build dependencies.

```rust
use wit_deps::lock;

#[tokio::main] async fn main() -> anyhow::Result<()> {
    let manifest = r#"clocks = "https://github.com/WebAssembly/wasi-clocks/archive/main.tar.gz""#;

    // Pass existing lock contents, or None to create a fresh one
    let existing_lock: Option<String> = std::fs::read_to_string("wit/deps.lock").ok();

    match lock(
        Some("wit"),         // base path for relative path deps
        manifest,
        existing_lock,
        "wit/deps",
    ).await? {
        Some(new_lock) => {
            std::fs::write("wit/deps.lock", &new_lock)?;
            println!("Lock updated:\n{new_lock}");
        }
        None => println!("Already in sync."),
    }
    Ok(())
}

```

--------------------------------

### lock function

Source: https://context7.com/bytecodealliance/wit-deps/llms.txt

Low-level API that accepts manifest and lock contents as strings and a deps path. Returns a new TOML-encoded lock string when an update was needed, or `None` if already in sync. Useful when manifest/lock content comes from sources other than the filesystem.

```APIDOC
## Rust function: `lock` — Lock from in-memory strings

Low-level API that accepts manifest and lock contents as strings and a deps path. Returns a new TOML-encoded lock string when an update was needed, or `None` if already in sync. Useful when manifest/lock content comes from sources other than the filesystem.

```rust
use wit_deps::lock;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let manifest = r#" 
clocks = "https://github.com/WebAssembly/wasi-clocks/archive/main.tar.gz"
"#;

    // Pass existing lock contents, or None to create a fresh one
    let existing_lock: Option<String> = std::fs::read_to_string("wit/deps.lock").ok();

    match lock(
        Some("wit"),         // base path for relative path deps
        manifest,
        existing_lock,
        "wit/deps",
    ).await? {
        Some(new_lock) => {
            std::fs::write("wit/deps.lock", &new_lock)?;
            println!("Lock updated:\n{new_lock}");
        }
        None => println!("Already in sync."),
    }
    Ok(())
}
```
```

--------------------------------

### update_path function

Source: https://context7.com/bytecodealliance/wit-deps/llms.txt

Like `lock_path` but unconditionally re-fetches all dependencies (ignores existing lock), always writing a fresh lockfile. Used to pick up changes from branch-pinned URLs.

```APIDOC
## Rust function: `update_path` — Force-update from file paths

Like `lock_path` but unconditionally re-fetches all dependencies (ignores existing lock), always writing a fresh lockfile. Used to pick up changes from branch-pinned URLs.

```rust
use wit_deps::update_path;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Re-resolves all deps from scratch, overwriting wit/deps.lock
    update_path(
        "wit/deps.toml",
        "wit/deps.lock",
        "wit/deps",
    ).await?;

    println!("All dependencies updated.");
    Ok(())
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.