dlprotoc

https://docs.rs/dlprotoc
Admin
dlprotoc is a Rust crate that downloads protoc binaries for use in Cargo build scripts, eliminating...
Tokens:11,210
Snippets:114
Trust Score:9.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### Usage Example

Source: https://docs.rs/dlprotoc/latest/dlprotoc

Demonstrates how to add the dlprotoc crate to your build dependencies and use the `download_protoc` function in your `build.rs` file.

```APIDOC
## Usage

Add the `dlprotoc` crate to `build-dependencies` in `Cargo.toml`:

```toml
[build-dependencies]
dlprotoc = "0"
```

In `build.rs`, call `download_protoc` before calling `compile_protos`:

```rust
fn main() -> Result<(), Box<dyn std::error::Error>> {
    dlprotoc::download_protoc()?;
    prost_build::compile_protos(&["src/example.proto"], &["src/"])?;
    Ok(())
}
```
```

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

### Check Protoc Execution

Source: https://docs.rs/dlprotoc/latest/src/dlprotoc/lib.rs.html

Verifies that the protoc executable within the extracted zip archive functions correctly by checking its version. This is part of the setup and validation process for protoc.

```rust
fn check_write_protoc(write_protoc_fn: impl Fn(&Path) -> Result<(), Error>) {
    let tempdir = tempfile::tempdir().unwrap();
    let protoc_zip_dir_path = tempdir.path().join("protoc_zip");

    write_protoc_fn(&protoc_zip_dir_path).unwrap();

    // check that the include dir exists
    assert!(protoc_zip_dir_path.join("include").is_dir());

    // run protoc and make sure it "works"
    let protoc_path = protoc_zip_dir_path.join("bin").join("protoc");
    let output = Command::new(protoc_path).arg("--version").output().unwrap();
    let version_output = String::from_utf8_lossy(&output.stdout);
    let expected_end = format!("{LATEST_VERSION}\n");
    assert!(
        version_output.ends_with(&expected_end),
        "unexpected version output: {version_output}"
    );
}
```

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

### Get Known Protoc Hash

Source: https://docs.rs/dlprotoc/latest/src/dlprotoc/versions.rs.html

Searches through a list of known protoc versions and their hashes to find a match for the given OS, CPU architecture, and version. Returns an error if no match is found.

```rust
pub fn known_hash(os: OS, cpu: CPUArch, version: &str) -> Result<Sha256HashResult, Error> {
    for known in KNOWN_VERSIONS {
        if known.os == os && known.cpu == cpu && known.version == version {
            return Ok(known.hash);
        }
    }
    Err(Error::from_string(format!(
        "unknown hash for {os} {cpu} {version}"
    )))
}
```

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

### Get Error Description (Deprecated)

Source: https://docs.rs/dlprotoc/latest/dlprotoc/struct.Error.html

Deprecated method for getting a string description of the error. Users should prefer using the Display implementation or `to_string()`.

```rust
fn description(&self) -> &str
```

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

### Define OS Enum

Source: https://docs.rs/dlprotoc/latest/src/dlprotoc/versions.rs.html

Defines an enum for operating systems (Linux, OSX) and implements methods to get the current OS, all defined OS values, and their Rust identifiers.

```rust
pub enum OS {
    /// Linux: "linux" in protoc URLs.
    Linux,
    /// Mac OS X / Darwin: "macos" in protoc URLs.
    #[expect(
        clippy::upper_case_acronyms,
        reason = "OSX is a permitted all-caps acronym"
    )]
    OSX,
    // TODO: Windows,
}

impl OS {
    /// Returns the operating system executing this function.
    ///
    /// # Panics
    /// If this is run on an unsupported operating system.
    #[must_use]
    pub fn current() -> Self {
        match std::env::consts::OS {
            "linux" => Self::Linux,
            "macos" => Self::OSX,
            unsupported_os => panic!("unsupported OS: {unsupported_os}"),
        }
    }

    /// Returns all defined enum values.
    #[must_use]
    pub const fn all() -> &'static [Self] {
        &[Self::Linux, Self::OSX]
    }

    /// Returns the Rust enum identifier as used in code.
    #[must_use]
    pub const fn rust_identifier(self) -> &'static str {
        match self {
            Self::Linux => "Linux",
            Self::OSX => "OSX",
        }
    }
}
```

```rust
impl Display for OS {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let s = match self {
            Self::Linux => "linux",
            Self::OSX => "osx",
        };
        write!(f, "{s}")
    }
}
```

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

### Get Error Cause (Deprecated)

Source: https://docs.rs/dlprotoc/latest/dlprotoc/struct.Error.html

Deprecated method for getting the cause of the error. It has been replaced by `Error::source`, which offers better support for downcasting.

```rust
fn cause(&self) -> Option<&dyn Error>
```

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

### Get Source Error

Source: https://docs.rs/dlprotoc/latest/dlprotoc/struct.Error.html

Returns the underlying source error, if any, for the current Error instance. This is part of the standard Error trait implementation.

```rust
fn source(&self) -> Option<&(dyn Error + 'static)>
```

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

### Define CPUArch Enum

Source: https://docs.rs/dlprotoc/latest/src/dlprotoc/versions.rs.html

Defines an enum for CPU architectures (AArch64, X86_64) and implements methods to get the current architecture, all defined architectures, and their code labels.

```rust
pub enum CPUArch {
    /// ARM AArch64: "aarch64" in protoc URLs.
    #[allow(clippy::doc_markdown)]
    AArch64,
    /// Intel/AMD x86-64: "x86_64" in protoc URLs.
    #[allow(clippy::doc_markdown)]
    X86_64,
}

impl CPUArch {
    /// Returns the CPU architecture executing this function.
    ///
    /// # Panics
    /// If run on an unsupported architecture.
    #[must_use]
    pub fn current() -> Self {
        match std::env::consts::ARCH {
            "aarch64" => Self::AArch64,
            "x86_64" => Self::X86_64,
            unsupported_arch => panic!("unsupported arch: {unsupported_arch}"),
        }
    }

    /// Returns all defined enum values.
    #[must_use]
    pub const fn all() -> &'static [Self] {
        &[Self::AArch64, Self::X86_64]
    }

    /// Returns the Rust enum identifier as used in code.
    #[must_use]
    pub const fn code_label(self) -> &'static str {
        match self {
            Self::AArch64 => "AArch64",
            Self::X86_64 => "X86_64",
        }
    }
}
```

```rust
impl Display for CPUArch {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let s = match self {
            Self::AArch64 => "aarch_64",
            Self::X86_64 => "x86_64",
        };
        write!(f, "{s}")
    }
}
```

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

### Get Type ID

Source: https://docs.rs/dlprotoc/latest/dlprotoc/struct.Error.html

Implements the Any trait to retrieve the TypeId of a type. This is a blanket implementation applicable to any type T that is 'static and ?Sized.

```rust
fn type_id(&self) -> TypeId
```

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

### download_protoc

Source: https://docs.rs/dlprotoc/latest/dlprotoc

Downloads protoc to the `OUT_DIR` environment variable and sets the `PROTOC` environment variable so prost-build or tonic-build can find it.

```APIDOC
## Functions

download_protoc
    Downloads protoc to the `OUT_DIR` environment variable and sets the `PROTOC` environment variable so prost-build or tonic-build can find it.
```

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

### Simulate Protoc Download and Unpack

Source: https://docs.rs/dlprotoc/latest/src/dlprotoc/lib.rs.html

Tests the unpacking logic without actual network access by creating a fake zip archive in memory. This snippet demonstrates creating a zip file with a script and a proto definition.

```rust
let mut zip_data = Vec::new();
let mut zip_w = ZipWriter::new(Cursor::new(&mut zip_data));
let exe_options = SimpleFileOptions::default().unix_permissions(0o755);
zip_w.start_file("bin/protoc", exe_options).unwrap();
let script_contents = format!("#!/bin/sh\necho protoc fake version {LATEST_VERSION}\n");
zip_w.write_all(script_contents.as_bytes()).unwrap();

zip_w
    .start_file(
        "include/google/protobuf/duration.proto",
        SimpleFileOptions::default(),
    )
    .unwrap();
```

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

### Download protoc in build.rs

Source: https://docs.rs/dlprotoc

In your `build.rs` file, call `dlprotoc::download_protoc()` before compiling your Protocol Buffer definitions. This ensures the protoc binary is available for build tools.

```rust
fn main() -> Result<(), Box<dyn std::error::Error>> {
    dlprotoc::download_protoc()?;
    prost_build::compile_protos(&["src/example.proto"], &["src/"])?;
    Ok(())
}
```

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

### download_protoc

Source: https://docs.rs/dlprotoc/latest/dlprotoc/fn.download_protoc.html

Downloads protoc to the OUT_DIR environment variable and sets the PROTOC environment variable so prost-build or tonic-build can find it. Intended to be called from a Cargo build script (build.rs).

```APIDOC
## Function download_protoc

### Signature
```rust
pub fn download_protoc() -> Result<(), Error>
```

### Description
Downloads protoc to the `OUT_DIR` environment variable and sets the `PROTOC` environment variable so prost-build or tonic-build can find it. Intended to be called from a Cargo build script (`build.rs`).

### Errors
Returns an `Error` if it fails to fetch protoc over the Internet, fails to verify it, or fails to unzip it.
```

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

### Download protoc and set PROTOC environment variable

Source: https://docs.rs/dlprotoc/latest/src/dlprotoc/lib.rs.html

Downloads protoc to the `OUT_DIR` environment variable and sets the `PROTOC` environment variable for prost-build or tonic-build. Intended for use in a Cargo build script (`build.rs`). Returns an error if fetching, verifying, or unzipping protoc fails.

```rust
pub fn download_protoc() -> Result<(), Error> {
    let out_dir = std::env::var(CARGO_BUILD_OUT_ENV_VAR)
        .map_err(|e| Error::with_prefix(format!("env var {CARGO_BUILD_OUT_ENV_VAR}"), e))?;
    let protoc_distribution_path = Path::new(&out_dir).join("protoc_zip");
    if protoc_distribution_path.exists() {
        // TODO: version the download so updates are applied: Does Cargo solve this for us?
        println!(
            "dlprotoc: warning: not downloading; protoc already exists at {}",
            protoc_distribution_path.display()
        );
    } else {
        write_protoc(&protoc_distribution_path)?;
    }

    let protoc_path = protoc_distribution_path.join("bin").join("protoc");
    unsafe {
        std::env::set_var(PROST_PROTOC_ENV_VAR, protoc_path);
    }

    Ok(())
}
```

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

### download_unverified

Source: https://docs.rs/dlprotoc/latest/dlprotoc

Downloads protoc without verifying the hash. This should only be used by the dlprotoc crate, and by the `protochashes` tool.

```APIDOC
download_unverified
    Downloads protoc without verifying the hash. This should only be used by the dlprotoc crate, and by the `protochashes` tool.
```

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

### Test Protoc Download and Execution

Source: https://docs.rs/dlprotoc/latest/src/dlprotoc/lib.rs.html

Tests the download_protoc function by simulating network access and executing protoc. This test is ignored by default due to network requirements. It sets environment variables, writes a proto file, and invokes protoc.

```rust
#[test]
#[ignore = "requires network access"]
fn test_write_protoc_real_network_access() -> Result<(), Box<dyn std::error::Error>> {
    // actually downloads from the real URL
    let tempdir = tempfile::tempdir()?;
    // set the PROTOC env var to "" so it gets reset when the test ends
    let reset_protoc_env_var = SetEnvForTest::set(PROST_PROTOC_ENV_VAR, "");
    let reset_out_dir_env_var = SetEnvForTest::set(CARGO_BUILD_OUT_ENV_VAR, tempdir.path());
    download_protoc()?;
    drop(reset_out_dir_env_var);

    let example_proto_path = tempdir.path().join("foo.proto");
    std::fs::write(
        &example_proto_path,
        br#"syntax = "proto3";
package examplepb;
import "google/protobuf/duration.proto";
message M {
    google.protobuf.Duration example_duration = 1;
}
"#,
    )?;

    // run protoc to compile the test proto file
    let protoc_path = std::env::var(PROST_PROTOC_ENV_VAR)?;
    let output = Command::new(protoc_path)
        .arg(&example_proto_path)
        .arg(format!("--proto_path={}", tempdir.path().display()))
        .arg("--descriptor_set_out=/dev/null")
        .output()
        .unwrap();

    let stdout = String::from_utf8_lossy(&output.stdout);
    let stderr = String::from_utf8_lossy(&output.stderr);
    assert!(
        stdout.is_empty() && stderr.is_empty(),
        "expected no output from protoc\nstdout: {stdout}\n stderr: {stderr}\n"
    );

    drop(reset_protoc_env_var);

    Ok(())
}
```

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

### download_protoc

Source: https://docs.rs/dlprotoc/latest/dlprotoc/all.html

Downloads the Protocol Buffer compiler (protoc) executable for the current platform.

```APIDOC
## download_protoc

### Description
Downloads the Protocol Buffer compiler (protoc) executable for the current platform.

### Function Signature
`fn download_protoc() -> Result<PathBuf, Error>`

### Returns
- `Ok(PathBuf)`: A `PathBuf` pointing to the downloaded protoc executable on success.
- `Err(Error)`: An error if the download or extraction fails.
```

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

### Download Protoc Unverified

Source: https://docs.rs/dlprotoc/latest/dlprotoc/fn.download_unverified.html

Downloads protoc without verifying the hash. This should only be used by the dlprotoc crate, and by the `protochashes` tool. Returns an error if it fails to fetch protoc over the Internet.

```rust
pub fn download_unverified(
    os: OS,
    cpu: CPUArch,
    version: &str,
) -> Result<Vec<u8>, Error>
```

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

### Test Download Protoc Error Handling

Source: https://docs.rs/dlprotoc/latest/src/dlprotoc/lib.rs.html

Tests that download_protoc returns an error when the OUT_DIR environment variable is not set, as expected when not run as part of a build script.

```rust
#[test]
fn test_download_protoc_not_build_script() {
    let err = download_protoc().expect_err("must return an error");
    assert!(
        err.to_string().contains("env var OUT_DIR"),
        "download_protoc unexpected error message: {err}"
    );
}
```

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

### Generate Protoc URL

Source: https://docs.rs/dlprotoc/latest/src/dlprotoc/lib.rs.html

Generates the download URL for a specific protoc version, OS, and CPU architecture. Used in tests to verify URL construction.

```rust
let url = make_url(OS::Linux, CPUArch::X86_64, "27.0");
assert_eq!(
    url,
    "https://github.com/protocolbuffers/protobuf/releases/download/v27.0/protoc-27.0-linux-x86_64.zip"
);

let url = make_url(OS::OSX, CPUArch::AArch64, "26.1");
assert_eq!(
    url,
    "https://github.com/protocolbuffers/protobuf/releases/download/v26.1/protoc-26.1-osx-aarch_64.zip"
);
```

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

### download_unverified Function

Source: https://docs.rs/dlprotoc/latest/dlprotoc/fn.download_unverified.html

Downloads protoc without verifying the hash. This function is intended for internal use by the dlprotoc crate and the protochashes tool. It returns a Result containing a vector of bytes representing the downloaded file or an Error if the download fails.

```APIDOC
## Function download_unverified

### Signature
```rust
pub fn download_unverified(os: OS, cpu: CPUArch, version: &str) -> Result<Vec<u8>, Error>
```

### Description
Downloads the protoc binary for a given operating system, CPU architecture, and version without performing any hash verification. This function should be used with caution and is primarily intended for internal use within the `dlprotoc` crate and the `protochashes` tool.

### Parameters
* `os` (OS): The target operating system.
* `cpu` (CPUArch): The target CPU architecture.
* `version` (str): The version of protoc to download.

### Returns
* `Result<Vec<u8>, Error>`: On success, returns a `Vec<u8>` containing the downloaded protoc binary. On failure, returns an `Error`.

### Errors
Returns an error if it fails to fetch protoc over the Internet.
```

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

### Write Protoc Zip Data

Source: https://docs.rs/dlprotoc/latest/src/dlprotoc/lib.rs.html

Writes protoc zip data to a destination directory. This function is useful for testing purposes.

```rust
fn write_protoc_zip_data(destination_dir: &Path, protoc_zip_bytes: &[u8]) -> Result<(), Error> {
    let mut zip = zip::ZipArchive::new(Cursor::new(&protoc_zip_bytes))?;
    zip.extract(destination_dir)?;
    Ok(())
}
```

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

### protoc_hash

Source: https://docs.rs/dlprotoc/latest/dlprotoc/fn.protoc_hash.html

Hashes data using the algorithm used to verify protoc binaries (currently SHA-256). This should only be used by the protochashes tool.

```APIDOC
## Function protoc_hash

### Signature
```rust
pub fn protoc_hash(data: &[u8]) -> [u8; 32]
```

### Description
Hashes data using the algorithm used to verify protoc binaries (currently SHA-256). This should only be used by the `protochashes` tool.

### Parameters
* `data` - A slice of bytes to be hashed.
```

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

### Add dlprotoc to build-dependencies

Source: https://docs.rs/dlprotoc

Include the dlprotoc crate in your project's `Cargo.toml` under `build-dependencies` to enable its functionality in build scripts.

```toml
[build-dependencies]
dlprotoc = "0"
```

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

### Policy AND Combination

Source: https://docs.rs/dlprotoc/latest/dlprotoc/struct.Error.html

Combines two policies using a logical AND. The resulting policy follows only if both self and other policies follow.

```rust
fn and<P, B, E>(self, other: P) -> And<T, P>
where T: Policy<B, E>, P: Policy<B, E>
```

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

### Write Protoc Zip Data

Source: https://docs.rs/dlprotoc/latest/src/dlprotoc/lib.rs.html

Writes protoc binary data into a zip archive. This function is used internally for setting up protoc for execution.

```rust
fn write_protoc_zip_data(destination: &Path, zip_data: &[u8]) -> Result<(), Error> {
    let mut zip_w = zip::ZipWriter::new(File::create(destination)?);
    zip_w.start_file("protoc.zip", Default::default()).unwrap();
    zip_w.write_all(zip_data).unwrap();
    zip_w.finish().unwrap();
    Ok(())
}
```

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

### Calculate protoc hash

Source: https://docs.rs/dlprotoc/latest/src/dlprotoc/lib.rs.html

Hashes data using the algorithm for verifying protoc binaries (currently SHA-256). This function is intended for use by the `protochashes` tool.

```rust
pub fn protoc_hash(data: &[u8]) -> [u8; 32] {
    let mut hasher = Sha256::new();
    hasher.update(data);
    let hash = hasher.finalize();

    let mut result = [0; 32];
    result.copy_from_slice(&hash);
    result
}
```

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

### Protoc Known Versions Data

Source: https://docs.rs/dlprotoc/latest/src/dlprotoc/versions.rs.html

Defines a constant array of KnownVersion structs, each containing the OS, CPUArch, version string, and SHA256 hash for a specific protoc binary release.

```rust
const KNOWN_VERSIONS: &[KnownVersion] = &[
    KnownVersion {
        os: OS::Linux,
        cpu: CPUArch::X86_64,
        version: "27.0",
        hash: hex!("e2bdce49564dbad4676023d174d9cdcf932238bc0b56a8349a5cb27bbafc26b0"),
    },
    KnownVersion {
        os: OS::Linux,
        cpu: CPUArch::AArch64,
        version: "27.0",
        hash: hex!("1e4b2d8b145afe99a36602f305165761e46d2525aa94cbb907e2e983be6717ac"),
    },
    KnownVersion {
        os: OS::Linux,
        cpu: CPUArch::AArch64,
        version: "27.1",
        hash: hex!("8809c2ec85368c6b6e9af161b6771a153aa92670a24adbe46dd34fa02a04df2f"),
    },
    KnownVersion {
        os: OS::Linux,
        cpu: CPUArch::X86_64,
        version: "27.1",
        hash: hex!("8970e3d8bbd67d53768fe8c2e3971bdd71e51cfe2001ca06dacad17258a7dae3"),
    },
];
```

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

### Provide Error Context (Nightly Only)

Source: https://docs.rs/dlprotoc/latest/dlprotoc/struct.Error.html

An experimental, nightly-only API that provides type-based access to error context, intended for error reporting. Requires the `error_generic_member_access` feature.

```rust
fn provide<'a>(&'a self, request: &mut Request<'a>)
```

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

### Known Protoc Versions Data

Source: https://docs.rs/dlprotoc/latest/src/dlprotoc/versions.rs.html

This array defines known versions of the protoc compiler, specifying the OS, CPU architecture, version string, and the SHA256 hash for each.

```rust
KnownVersion {
        os: OS::OSX,
        cpu: CPUArch::AArch64,
        version: "33.0",
        hash: hex!("3cf55dd47118bd2efda9cd26b74f8bbbfcf5beb1bf606bc56ad4c001b543f6d3"),
    },
```

```rust
KnownVersion {
        os: OS::OSX,
        cpu: CPUArch::X86_64,
        version: "33.0",
        hash: hex!("e4e50a703147a92d1a5a2d3a34c9e41717f67ade67d4be72b9a466eb8f22fe87"),
    },
```

```rust
KnownVersion {
        os: OS::Linux,
        cpu: CPUArch::AArch64,
        version: "33.2",
        hash: hex!("706662a332683aa2fffe1c4ea61588279d31679cd42d91c7d60a69651768edb8"),
    },
```

```rust
KnownVersion {
        os: OS::Linux,
        cpu: CPUArch::X86_64,
        version: "33.2",
        hash: hex!("b24b53f87c151bfd48b112fe4c3a6e6574e5198874f38036aff41df3456b8caf"),
    },
```

```rust
KnownVersion {
        os: OS::OSX,
        cpu: CPUArch::AArch64,
        version: "33.2",
        hash: hex!("5be1427127788c9f7dd7d606c3e69843dd3587327dea993917ffcb77e7234b44"),
    },
```

```rust
KnownVersion {
        os: OS::OSX,
        cpu: CPUArch::X86_64,
        version: "33.2",
        hash: hex!("dba51cfcc85076d56e7de01a647865c5a7f995c3dce427d5215b53e50b7be43f"),
    },
```

```rust
KnownVersion {
        os: OS::Linux,
        cpu: CPUArch::AArch64,
        version: "33.5",
        hash: hex!("2b0fcf9b2c32cbadccc0eb7a88b841fffecd4a06fc80acdba2b5be45e815c38a"),
    },
```

```rust
KnownVersion {
        os: OS::Linux,
        cpu: CPUArch::X86_64,
        version: "33.5",
        hash: hex!("24e58fb231d50306ee28491f33a170301e99540f7e29ca461e0e80fd1239f8d1"),
    },
```

```rust
KnownVersion {
        os: OS::OSX,
        cpu: CPUArch::AArch64,
        version: "33.5",
        hash: hex!("7084c6482e3bb416a33fe2162ba566711773b842e6953bf6cb181647b9ef57c0"),
    },
```

```rust
KnownVersion {
        os: OS::OSX,
        cpu: CPUArch::X86_64,
        version: "33.5",
        hash: hex!("7f31625f8bec4929082ae9209e101c1c03692624457cc6332f83736db495ee92"),
    },
```

```rust
KnownVersion {
        os: OS::Linux,
        cpu: CPUArch::AArch64,
        version: "34.0",
        hash: hex!("f0b8aad28be5ea6150c082f96ac57e028154afb9ee29f4ce092b5a39df8ae6c8"),
    },
```

```rust
KnownVersion {
        os: OS::Linux,
        cpu: CPUArch::X86_64,
        version: "34.0",
        hash: hex!("e9a91b6fcfe4177ec2cd35fc8f15c1e811fa0ecdef9372755cd6d3513d5faaab"),
    },
```

```rust
KnownVersion {
        os: OS::OSX,
        cpu: CPUArch::AArch64,
        version: "34.0",
        hash: hex!("3ef35187a3c8aed81ee57e792227e483e558fa56c93fce525e569bff55794c1a"),
    },
```

```rust
KnownVersion {
        os: OS::OSX,
        cpu: CPUArch::X86_64,
        version: "34.0",
        hash: hex!("d58fcd413a9ed458283d54023e409fd5cf767da4ed225d1ffaffd83cf2764f53"),
    },
```

```rust
KnownVersion {
        os: OS::Linux,
        cpu: CPUArch::AArch64,
        version: "34.1",
        hash: hex!("31c5e9e3c7bf013cf41fb97765ee255c140024a6b175b6cc9b64beddd7c23ba7"),
    },
```

```rust
KnownVersion {
        os: OS::Linux,
        cpu: CPUArch::X86_64,
        version: "34.1",
        hash: hex!("af27ea66cd26938fe48587804ca7d4817457a08350021a1c6e23a27ccc8c6904"),
    },
```

```rust
KnownVersion {
        os: OS::OSX,
        cpu: CPUArch::AArch64,
        version: "34.1",
        hash: hex!("2c7e92b8b578916937df132b3032e2e8e6c170862ecf7a8333094a6f3d03650c"),
    },
```

```rust
KnownVersion {
        os: OS::OSX,
        cpu: CPUArch::X86_64,
        version: "34.1",
        hash: hex!("ab124429c1f49951f03b6c0c0e911fec04e2c7c20de5c935e0cde7353bbd016c"),
    },
```

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

### Test Known Hash for Current Platform

Source: https://docs.rs/dlprotoc/latest/src/dlprotoc/versions.rs.html

This test ensures that a known hash exists for the current operating system and CPU architecture for the latest version of protoc.

```rust
#[test]
    fn test_known_hash() {
        // ensure we know a hash for the current platform
        known_hash(OS::current(), CPUArch::current(), LATEST_VERSION).unwrap();
    }
```

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

### Policy OR Combination

Source: https://docs.rs/dlprotoc/latest/dlprotoc/struct.Error.html

Combines two policies using a logical OR. The resulting policy follows if either self or other policy follows.

```rust
fn or<P, B, E>(self, other: P) -> Or<T, P>
where T: Policy<B, E>, P: Policy<B, E>
```

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

### Error Creation

Source: https://docs.rs/dlprotoc/latest/dlprotoc/struct.Error.html

Methods available for creating new Error instances.

```APIDOC
## Error Creation

### `pub const fn from_string(message: String) -> Self`
Creates an Error from a String message.

### `pub fn with_prefix(prefix: impl Borrow<str>, e: impl Display) -> Self`
Creates an Error with a given prefix and another displayable error.
```

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

### protoc_hash

Source: https://docs.rs/dlprotoc/latest/dlprotoc/all.html

Calculates the SHA256 hash of the downloaded Protocol Buffer compiler (protoc) executable.

```APIDOC
## protoc_hash

### Description
Calculates the SHA256 hash of the downloaded Protocol Buffer compiler (protoc) executable. This is used for verification purposes.

### Function Signature
`fn protoc_hash(protoc_path: &Path) -> Result<String, Error>`

### Parameters
- `protoc_path` (*&Path*): A reference to the path of the protoc executable.

### Returns
- `Ok(String)`: The SHA256 hash of the protoc executable as a hexadecimal string on success.
- `Err(Error)`: An error if the hash calculation fails.
```

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

### Set Environment Variable for Test

Source: https://docs.rs/dlprotoc/latest/src/dlprotoc/lib.rs.html

A helper struct to temporarily set environment variables for tests and restore their previous values upon dropping. Uses unsafe for `set_var`.

```rust
struct SetEnvForTest<'a> {
    name: &'a str,
    previous: Option<String>,
}

impl<'a> SetEnvForTest<'a> {
    fn set(name: &'a str, value: impl AsRef<OsStr>) -> Result<Self, std::env::VarError> {
        let previous = match std::env::var(name) {
            Ok(value) => Some(value),
            Err(std::env::VarError::NotPresent) => None,
            Err(e) => return Err(e),
        };
        unsafe {
            std::env::set_var(name, value);
        }
        Ok(Self { name, previous })
    }
}

impl Drop for SetEnvForTest<'_> {
    fn drop(&mut self) {
        unsafe {
            match &self.previous {
                Some(value) => std::env::set_var(self.name, value),
                None => std::env::remove_var(self.name),
            }
        }
    }
}
```

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

### Create Error with Prefix

Source: https://docs.rs/dlprotoc/latest/dlprotoc/struct.Error.html

Constructs a new Error instance with an added prefix to the error message. This function is generic over the type of the prefix and the error to be displayed.

```rust
pub fn with_prefix(prefix: impl Borrow<str>, e: impl Display) -> Self
```

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

### Convert via From

Source: https://docs.rs/dlprotoc/latest/dlprotoc/struct.Error.html

Implements the Into trait, which allows converting a type T into a type U if U implements From<T>. This is a blanket implementation.

```rust
fn into(self) -> U
```

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

### Convert to String

Source: https://docs.rs/dlprotoc/latest/dlprotoc/struct.Error.html

Implements the ToString trait, providing a method to convert a value into a String. This is a blanket implementation for types that implement Display.

```rust
fn to_string(&self) -> String
```

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

### Same Type Output

Source: https://docs.rs/dlprotoc/latest/dlprotoc/struct.Error.html

Defines the associated type Output to be the same as Self. This is part of the Same trait implementation.

```rust
type Output = T
```

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

### Try Convert to String

Source: https://docs.rs/dlprotoc/latest/dlprotoc/struct.Error.html

Implements the ToStringFallible trait, offering a fallible conversion to String that avoids panicking on out-of-memory errors.

```rust
fn try_to_string(&self) -> Result<String, TryReserveError>
```

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

### Validate dlprotoc Versions

Source: https://docs.rs/dlprotoc/latest/src/dlprotoc/versions.rs.html

Iterates through known dlprotoc versions, asserting they are in ascending order and that no duplicates are inserted. Ensures the last processed version matches the LATEST_VERSION constant.

```rust
{
            assert!(known_version.version >= last_version);
            last_version = known_version.version;

            let key = KnownVersionKey {
                os: known_version.os,
                cpu: known_version.cpu,
                version: known_version.version.to_string(),
            };
            let newly_inserted = all_versions.insert(key.clone());
            assert!(newly_inserted, "duplicate version: {key:?}");
        }

        assert_eq!(LATEST_VERSION, last_version);
    }
}
```

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

### Error Trait Implementations

Source: https://docs.rs/dlprotoc/latest/dlprotoc/struct.Error.html

Key trait implementations for the Error type, providing standard error handling capabilities.

```APIDOC
## Error Trait Implementations

### `impl Debug for Error`
Provides a debug representation for the Error.

### `impl Display for Error`
Provides a display representation for the Error.

### `impl Error for Error`
Implements the standard `std::error::Error` trait.
- `source()`: Returns the lower-level source of this error, if any.
- `description()`: Deprecated. Use `Display` or `to_string()`.
- `cause()`: Deprecated. Replaced by `source()`.
- `provide()`: Nightly-only experimental API for error report access.

### `impl From<Error> for Error`
Allows converting an Error into itself.

### `impl From<ZipError> for Error`
Allows converting a `ZipError` into a dlprotoc `Error`.
```

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

### with_current_subscriber

Source: https://docs.rs/dlprotoc/latest/dlprotoc/struct.Error.html

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. This is useful for ensuring that logging or other subscriber-based operations are correctly associated with the current context.

```APIDOC
## fn with_current_subscriber(self) -> WithDispatch<Self>

### Description
Attaches the current default `Subscriber` to this type, returning a `WithDispatch` wrapper.

### Method
`with_current_subscriber`

### Parameters
- `self`: The instance of the struct to which the subscriber will be attached.

### Returns
- `WithDispatch<Self>`: A wrapper type that has the subscriber attached.
```

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

### Test Known Versions Constant Integrity

Source: https://docs.rs/dlprotoc/latest/src/dlprotoc/versions.rs.html

This test verifies the integrity of the `KNOWN_VERSIONS` constant by checking for uniqueness and ensuring the versions are in increasing order. It uses a `HashSet` to detect duplicates and iterates through the versions to compare them lexicographically.

```rust
#[test]
    fn test_known_versions_constant() {
        #[derive(Clone, Debug, PartialEq, Eq, Hash)]
        struct KnownVersionKey {
            os: OS,
            cpu: CPUArch,
            version: String,
        }
        // check that KNOWN_VERSIONS is increasing and unique
        let mut all_versions = HashSet::new();
        let mut last_version = KNOWN_VERSIONS[0].version;
        for known_version in KNOWN_VERSIONS {
            // This should be a semver comparsion, but is testing a string comparion.
            // This will work with protoc versions since they are two digits, but can easily fail
            // e.g. if there are a lot of point releases, because "27.10" should be greater than "27.9"
```

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

### Attach Subscriber

Source: https://docs.rs/dlprotoc/latest/dlprotoc/struct.Error.html

Implements the WithSubscriber trait to attach a Subscriber to a type, returning a WithDispatch wrapper. The subscriber must be convertible into a Dispatch.

```rust
fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>
```

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

### Create Error from String

Source: https://docs.rs/dlprotoc/latest/dlprotoc/struct.Error.html

Constructs a new Error instance from a given String message. This is a constant function, meaning it can be evaluated at compile time.

```rust
pub const fn from_string(message: String) -> Self
```

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

### OS Enum Definition

Source: https://docs.rs/dlprotoc/latest/dlprotoc/type.OS.html

Declares an empty enum for OS. This might be a placeholder or used in conjunction with features.

```rust
pub enum OS {}
```

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

### OS Type Alias Definition

Source: https://docs.rs/dlprotoc/latest/dlprotoc/type.OS.html

Defines a type alias for OS. This is a common pattern for re-exporting or aliasing types.

```rust
pub type OS = OS;
```

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

### Try Convert From U to T

Source: https://docs.rs/dlprotoc/latest/dlprotoc/struct.Error.html

Implements the TryFrom trait for fallible conversions from type U to type T. The associated Error type is Infallible.

```rust
type Error = Infallible
```

```rust
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
```

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

### OS Type Alias

Source: https://docs.rs/dlprotoc/latest/dlprotoc/type.OS.html

This snippet shows the definition of the OS type alias, which is defined as an alias to itself.

```APIDOC
## OS Type Alias

```rust
pub type OS = OS;
```
```

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

### Try Convert From T to U

Source: https://docs.rs/dlprotoc/latest/dlprotoc/struct.Error.html

Implements the TryInto trait for fallible conversions from type T to type U. The associated Error type is determined by U's TryFrom implementation.

```rust
type Error = <U as TryFrom<T>>::Error
```

```rust
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
```

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

### Convert From Error to Error

Source: https://docs.rs/dlprotoc/latest/dlprotoc/struct.Error.html

Implements the From trait to allow converting an Error into itself. This is a trivial conversion.

```rust
fn from(e: Error) -> Self
```

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

### Convert From ZipError to Error

Source: https://docs.rs/dlprotoc/latest/dlprotoc/struct.Error.html

Implements the From trait to convert a ZipError into a dlprotoc Error. This allows integrating errors from the zip crate into the dlprotoc error handling.

```rust
fn from(e: ZipError) -> Self
```

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

### Define CPUArch Enum

Source: https://docs.rs/dlprotoc/latest/dlprotoc/type.CPUArch.html

This snippet shows the underlying definition of CPUArch as an empty enum.

```rust
pub enum CPUArch {}
```

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

### Identity Conversion

Source: https://docs.rs/dlprotoc/latest/dlprotoc/struct.Error.html

Implements the From trait for an identity conversion, where a type is converted into itself. This is a blanket implementation for any type T.

```rust
fn from(t: T) -> T
```

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

### Define CPUArch Type Alias

Source: https://docs.rs/dlprotoc/latest/dlprotoc/type.CPUArch.html

This snippet shows the definition of the CPUArch type alias, which is aliased to itself.

```rust
pub type CPUArch = CPUArch;
```

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

### Instrument with Span

Source: https://docs.rs/dlprotoc/latest/dlprotoc/struct.Error.html

Implements the Instrument trait to attach a Span to a type for tracing purposes. This returns an Instrumented wrapper.

```rust
fn instrument(self, span: Span) -> Instrumented<Self>
```

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

### CPUArch Type Alias

Source: https://docs.rs/dlprotoc/latest/dlprotoc/type.CPUArch.html

This snippet shows the definition of the CPUArch type alias, indicating it is an alias for itself, which is common in Rust for re-exporting or defining types.

```APIDOC
## CPUArch

### Summary
```rust
pub type CPUArch = CPUArch;
```
```

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

### Aliased Type OS

Source: https://docs.rs/dlprotoc/latest/dlprotoc/type.OS.html

This snippet shows the aliased type for OS, which is an empty enum.

```APIDOC
## Aliased Type OS

```rust
pub enum OS {}
```
```

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

### Implement std::error::Error for Custom Error

Source: https://docs.rs/dlprotoc/latest/src/dlprotoc/lib.rs.html

Ensures that the custom `Error` type can be used as a standard Rust `Error`. This allows for consistent error handling across different parts of the application.

```rust
    // ensures we can use this error as a std Error
    let err: Box<dyn std::error::Error> = Box::new(Error::from_string(String::from("test")));
    assert_eq!("test", err.to_string());
```

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

### Borrow Mutable

Source: https://docs.rs/dlprotoc/latest/dlprotoc/struct.Error.html

Implements the BorrowMut trait for mutable borrowing. This is a blanket implementation for any type T.

```rust
fn borrow_mut(&mut self) -> &mut T
```

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

### Format Error for Debugging

Source: https://docs.rs/dlprotoc/latest/dlprotoc/struct.Error.html

Implements the Debug trait for the Error struct, allowing it to be formatted for debugging purposes using a given Formatter.

```rust
fn fmt(&self, f: &mut Formatter<'_>) -> Result
```

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

### Instrument in Current Span

Source: https://docs.rs/dlprotoc/latest/dlprotoc/struct.Error.html

Implements the Instrument trait to attach the current Span to a type for tracing. This returns an Instrumented wrapper.

```rust
fn in_current_span(self) -> Instrumented<Self>
```

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

### Aliased Type: CPUArch Enum

Source: https://docs.rs/dlprotoc/latest/dlprotoc/type.CPUArch.html

This snippet shows the definition of the enum that CPUArch is aliased to. In this case, it's an empty enum, which might be used as a placeholder or for future expansion.

```APIDOC
## Aliased Type

```rust
pub enum CPUArch {}
```
```

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

### Borrow Immutable

Source: https://docs.rs/dlprotoc/latest/dlprotoc/struct.Error.html

Implements the Borrow trait for immutable borrowing. This is a blanket implementation for any type T.

```rust
fn borrow(&self) -> &T
```

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

### dlprotoc Error Struct Definition

Source: https://docs.rs/dlprotoc/latest/dlprotoc/struct.Error.html

Defines the Error struct used by the dlprotoc crate. This struct is intended to encapsulate error messages and is not designed for direct user handling.

```rust
pub struct Error { /* private fields */ }
```

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

### Error Struct Definition

Source: https://docs.rs/dlprotoc/latest/dlprotoc/struct.Error.html

The basic structure of the Error type, which is intended to be opaque to the user and only contains a message.

```APIDOC
```rust
pub struct Error { /* private fields */ }
```
```

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

### Custom Error Type Definition

Source: https://docs.rs/dlprotoc/latest/src/dlprotoc/error.rs.html

Defines the `Error` struct with a message field and provides methods for creating and formatting error instances. This is the primary error type for the dlprotoc crate.

```rust
use std::{borrow::Borrow, fmt::Display};

use zip::result::ZipError;

/// The Error type returned by the dlprotoc crate.
///
/// This type only contains a message, so it is not expected to be handled.
#[derive(Debug)]
pub struct Error {
    message: String,
}

impl Error {
    #[must_use]
    pub const fn from_string(message: String) -> Self {
        Self { message }
    }

    pub fn with_prefix(prefix: impl Borrow<str>, e: impl Display) -> Self {
        Self {
            message: format!("{}: {e}", prefix.borrow()),
        }
    }
}

impl Display for Error {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.message)
    }
}

impl std::error::Error for Error {}

impl From<ZipError> for Error {
    fn from(e: zip::result::ZipError) -> Self {
        Self::with_prefix("zip error", e)
    }
}

impl From<std::io::Error> for Error {
    fn from(e: std::io::Error) -> Self {
        Self::with_prefix("io error", e)
    }
}

impl From<reqwest::Error> for Error {
    fn from(e: reqwest::Error) -> Self {
        let message = if let Some(url) = e.url() {
            format!("failed downloading protoc from url: {url}: {e}")
        } else {
            format!("failed downloading protoc: {e}")
        };
        Self::from_string(message)
    }
}
```
Tokens:
Raw