### download_protoc() Source: https://context7.com/evanj/dlprotoc-rs/llms.txt Primary build script entry point. Fetches the protoc binary for the current OS and CPU architecture, verifies its SHA-256 hash, extracts it into Cargo's OUT_DIR, and sets the PROTOC environment variable. ```APIDOC ## `download_protoc()` — Primary build script entry point Fetches the protoc binary for the current OS and CPU architecture, verifies its SHA-256 hash, extracts it into Cargo's `OUT_DIR`, and sets the `PROTOC` environment variable so that `prost-build` and `tonic-build` can locate the compiler automatically. Must be called from inside a Cargo build script where the `OUT_DIR` environment variable is set by Cargo. ### Usage Example (prost-build) ```toml # Cargo.toml [build-dependencies] dlprotoc = "0" prost-build = "0" ``` ```rust // build.rs fn main() -> Result<(), Box> { // Downloads protoc to $OUT_DIR/protoc_zip/bin/protoc and sets PROTOC env var. // Skips the download if the binary already exists (cached from a previous build). dlprotoc::download_protoc()?; // prost-build will now find protoc via the PROTOC env var set above. prost_build::compile_protos(&["src/messages.proto"], &["src/"])?; Ok(()) } ``` ### Usage Example (tonic-build) ```rust // build.rs — with tonic-build fn main() -> Result<(), Box> { dlprotoc::download_protoc()?; tonic_build::compile_protos("proto/helloworld.proto")?; Ok(()) } ``` ### Expected Behavior: - On first build: downloads the protoc zip from `https://github.com/protocolbuffers/protobuf/releases/`, verifies the SHA-256 digest, and extracts to `$OUT_DIR/protoc_zip/`. - On subsequent builds: prints `dlprotoc: warning: not downloading; protoc already exists at ...` and reuses the cached binary. - On hash mismatch: returns `Err(Error { message: "hash mismatch for linux x86_64 34.1" })`. - Outside a build script (no `OUT_DIR`): returns `Err(Error { message: "env var OUT_DIR: ..." })`. ``` -------------------------------- ### Download protoc for tonic-build in build.rs Source: https://context7.com/evanj/dlprotoc-rs/llms.txt Use dlprotoc::download_protoc() in your build.rs to obtain the protoc binary for tonic-build. This function automatically sets the PROTOC environment variable, which tonic-build uses to locate the compiler. Subsequent builds will reuse the cached binary. ```rust // build.rs — with tonic-build fn main() -> Result<(), Box> { dlprotoc::download_protoc()?; tonic_build::compile_protos("proto/helloworld.proto")?; Ok(()) } ``` -------------------------------- ### Download protoc for prost-build in build.rs Source: https://context7.com/evanj/dlprotoc-rs/llms.txt Call dlprotoc::download_protoc() from your build.rs to fetch the protoc binary. This sets the PROTOC environment variable, allowing prost-build to find it automatically. The download is cached. ```rust // build.rs fn main() -> Result<(), Box> { // Downloads protoc to $OUT_DIR/protoc_zip/bin/protoc and sets PROTOC env var. // Skips the download if the binary already exists (cached from a previous build). dlprotoc::download_protoc()?; // prost-build will now find protoc via the PROTOC env var set above. prost_build::compile_protos(&["src/messages.proto"], &["src/"])?; Ok(()) } ``` -------------------------------- ### Select Target Operating System Source: https://context7.com/evanj/dlprotoc-rs/llms.txt Represents the target operating system for the protoc binary and implements `Display` for URL path segments. `OS::current()` detects the OS at runtime. ```rust use dlprotoc::OS; // Detect at runtime let os = OS::current(); // OS::Linux on Linux, OS::OSX on macOS // Iterate all supported OSes (used by protochashes tool) for os in OS::all() { println!("{os}"); // prints: linux, osx } // Use Display to get URL segment assert_eq!(format!("{}", OS::Linux), "linux"); assert_eq!(format!("{}", OS::OSX), "osx"); ``` -------------------------------- ### download_unverified(os, cpu, version) Source: https://context7.com/evanj/dlprotoc-rs/llms.txt Low-level binary downloader. Downloads a raw protoc zip archive for any specified OS, CPU architecture, and version string without performing hash verification. Intended for use by maintenance tools. ```APIDOC ## `download_unverified(os, cpu, version)` — Low-level binary downloader Downloads a raw protoc zip archive for any specified OS, CPU architecture, and version string without performing hash verification. This is a public function intended for use by the bundled `protochashes` maintenance binary when computing hashes for new protoc releases to add to `KNOWN_VERSIONS`. ### Parameters - **os** (`OS` enum) - Required - The operating system for which to download protoc. - **cpu** (`CPUArch` enum) - Required - The CPU architecture for which to download protoc. - **version** (`&str`) - Required - The version string of protoc to download (e.g., "34.1"). ### Usage Example ```rust use dlprotoc::{OS, CPUArch, download_unverified, protoc_hash}; fn main() -> Result<(), Box> { // Download the Linux x86_64 build of protoc 34.1 without hash checking let zip_bytes = download_unverified(OS::Linux, CPUArch::X86_64, "34.1")?; println!("Downloaded {} bytes", zip_bytes.len()); // Compute SHA-256 for the downloaded archive let hash = protoc_hash(&zip_bytes); let hex: String = hash.iter().map(|b| format!("{b:02x}")).collect(); println!("SHA-256: {hex}"); // Output: SHA-256: af27ea66cd26938fe48587804ca7d4817457a08350021a1c6e23a27ccc8c6904 Ok(()) } ``` ### Supported OS Variants: | `OS` variant | URL segment | |---|---| | `OS::Linux` | `linux` | | `OS::OSX` | `osx` | ### Supported CPU Variants: | `CPUArch` variant | URL segment | |---|---| | `CPUArch::X86_64` | `x86_64` | | `CPUArch::AArch64` | `aarch_64` | ### Download URL Format: `https://github.com/protocolbuffers/protobuf/releases/download/v{version}/protoc-{version}-{os}-{cpu}.zip` ``` -------------------------------- ### Release crate (maintainer) Source: https://github.com/evanj/dlprotoc-rs/blob/main/README.md Commands for testing and publishing the crate. Includes dry-run publishing, actual publishing, tagging the release, pushing the tag, and creating a Github release. ```bash make && cargo publish --dry-run ``` ```bash cargo publish ``` ```bash (VERSION=$(cargo pkgid | sed 's/.*@//'); git tag -a "v$VERSION" -m "release version $VERSION") ``` ```bash git push --tags ``` -------------------------------- ### Add dlprotoc to build dependencies Source: https://context7.com/evanj/dlprotoc-rs/llms.txt Include dlprotoc and prost-build in your Cargo.toml to manage protoc downloads within your build script. ```toml # Cargo.toml [build-dependencies] dlprotoc = "0" prost-build = "0" ``` -------------------------------- ### Select Target CPU Architecture Source: https://context7.com/evanj/dlprotoc-rs/llms.txt Represents the target CPU architecture for the protoc binary and implements `Display` for URL path segments. `CPUArch::current()` detects the architecture at runtime. ```rust use dlprotoc::CPUArch; // Detect at runtime let cpu = CPUArch::current(); // CPUArch::X86_64 or CPUArch::AArch64 // Iterate all supported architectures for cpu in CPUArch::all() { println!("{cpu}"); // prints: aarch_64, x86_64 } // URL segments used in download URLs assert_eq!(format!("{}", CPUArch::X86_64), "x86_64"); assert_eq!(format!("{}", CPUArch::AArch64), "aarch_64"); ``` -------------------------------- ### Download protoc without verification Source: https://context7.com/evanj/dlprotoc-rs/llms.txt Use download_unverified to fetch a protoc zip archive for a specific OS, CPU architecture, and version without hash checking. This is useful for the protochashes maintenance tool. The function returns the raw zip bytes. ```rust use dlprotoc::{OS, CPUArch, download_unverified, protoc_hash}; fn main() -> Result<(), Box> { // Download the Linux x86_64 build of protoc 34.1 without hash checking let zip_bytes = download_unverified(OS::Linux, CPUArch::X86_64, "34.1")?; println!("Downloaded {} bytes", zip_bytes.len()); // Compute SHA-256 for the downloaded archive let hash = protoc_hash(&zip_bytes); let hex: String = hash.iter().map(|b| format!("{b:02x}")).collect(); println!("SHA-256: {hex}"); // Output: SHA-256: af27ea66cd26938fe48587804ca7d4817457a08350021a1c6e23a27ccc8c6904 Ok(()) } ``` -------------------------------- ### Download protoc in Cargo build script Source: https://github.com/evanj/dlprotoc-rs/blob/main/README.md Call `dlprotoc::download_protoc()` before `prost_build::compile_protos(...)` in your `build.rs` file. This ensures protoc is available for Protocol Buffer compilation. ```rust fn main() -> Result<(), Box> { dlprotoc::download_protoc()?; prost_build::compile_protos(&["src/example.proto"], &["src/"])?; Ok(()) } ``` -------------------------------- ### OS enum Source: https://context7.com/evanj/dlprotoc-rs/llms.txt Represents the target operating system for the protoc binary. Implements `Display` to produce the URL path segment used in GitHub release URLs. `OS::current()` detects the OS at runtime from `std::env::consts::OS`; it panics on unsupported platforms (currently Windows). ```APIDOC ## `OS` enum — Operating system selector Represents the target operating system for the protoc binary. Implements `Display` to produce the URL path segment used in GitHub release URLs. `OS::current()` detects the OS at runtime from `std::env::consts::OS`; it panics on unsupported platforms (currently Windows). ```rust use dlprotoc::OS; // Detect at runtime let os = OS::current(); // OS::Linux on Linux, OS::OSX on macOS // Iterate all supported OSes (used by protochashes tool) for os in OS::all() { println!("{os}"); // prints: linux, osx } // Use Display to get URL segment assert_eq!(format!("{}", OS::Linux), "linux"); assert_eq!(format!("{}", OS::OSX), "osx"); ``` ``` -------------------------------- ### Maintainer Tool for Adding New Protoc Versions Source: https://context7.com/evanj/dlprotoc-rs/llms.txt A bundled binary used by crate maintainers to download all platform variants of a new protoc release and print `KnownVersion` struct definitions for `versions.rs`. ```bash # Download protoc 35.0 for all OS/arch combinations and print KnownVersion entries cargo run -- 35.0 ``` -------------------------------- ### protochashes binary Source: https://context7.com/evanj/dlprotoc-rs/llms.txt A bundled binary used by crate maintainers to download all platform variants of a new protoc release and print the `KnownVersion` struct definitions ready to paste into `versions.rs`. ```APIDOC ## `protochashes` binary — Maintainer tool for adding new protoc versions A bundled binary (`src/bin/protochashes/main.rs`) used by crate maintainers to download all platform variants of a new protoc release and print the `KnownVersion` struct definitions ready to paste into `versions.rs`. ```bash # Download protoc 35.0 for all OS/arch combinations and print KnownVersion entries cargo run -- 35.0 ``` **Example output:** ``` KnownVersion { os: OS::Linux, cpu: CPUArch::AArch64, version: "35.0", hash: hex!("..."), }, KnownVersion { os: OS::Linux, cpu: CPUArch::X86_64, version: "35.0", hash: hex!("..."), }, KnownVersion { os: OS::OSX, cpu: CPUArch::AArch64, version: "35.0", hash: hex!("..."), }, KnownVersion { os: OS::OSX, cpu: CPUArch::X86_64, version: "35.0", hash: hex!("..."), }, ``` After running this tool, the printed structs are appended to the `KNOWN_VERSIONS` slice in `src/versions.rs`, the crate version in `Cargo.toml` is updated to `{crate_version}+{protoc_version}`, and the change is submitted as a pull request. ``` -------------------------------- ### protoc_hash Source: https://context7.com/evanj/dlprotoc-rs/llms.txt Computes a raw 32-byte SHA-256 hash of the provided byte slice using the `sha2` crate. The return value is a `[u8; 32]` array. Used internally to verify downloaded protoc archives and externally by the `protochashes` tool to generate new hash entries. ```APIDOC ## `protoc_hash(data)` — SHA-256 digest of binary data Computes a raw 32-byte SHA-256 hash of the provided byte slice using the `sha2` crate. The return value is a `[u8; 32]` array. Used internally to verify downloaded protoc archives and externally by the `protochashes` tool to generate new hash entries. ```rust use dlprotoc::protoc_hash; fn main() { let data = b"hello world"; let hash: [u8; 32] = protoc_hash(data); // Format as lowercase hex string let hex: String = hash.iter().map(|b| format!("{b:02x}")).collect(); println!("{hex}"); // Output: b94d27b9934d3e08a52e52d7da7dabfac484efe04294e576b4b5f2fd35c37c2d... (truncated) } ``` ``` -------------------------------- ### Update protoc versions (maintainer) Source: https://github.com/evanj/dlprotoc-rs/blob/main/README.md This command is used by maintainers to fetch a new protoc version and generate the necessary struct definitions for the `KNOWN_VERSIONS` array. Ensure you provide the desired version number as an argument. ```bash cargo run -- (version e.g 27.0) ``` -------------------------------- ### CPUArch enum Source: https://context7.com/evanj/dlprotoc-rs/llms.txt Represents the target CPU architecture for the protoc binary. Implements `Display` to produce the URL path segment. `CPUArch::current()` detects the architecture at runtime from `std::env::consts::ARCH`; it panics on unsupported architectures. ```APIDOC ## `CPUArch` enum — CPU architecture selector Represents the target CPU architecture for the protoc binary. Implements `Display` to produce the URL path segment. `CPUArch::current()` detects the architecture at runtime from `std::env::consts::ARCH`; it panics on unsupported architectures. ```rust use dlprotoc::CPUArch; // Detect at runtime let cpu = CPUArch::current(); // CPUArch::X86_64 or CPUArch::AArch64 // Iterate all supported architectures for cpu in CPUArch::all() { println!("{cpu}"); // prints: aarch_64, x86_64 } // URL segments used in download URLs assert_eq!(format!("{}", CPUArch::X86_64), "x86_64"); assert_eq!(format!("{}", CPUArch::AArch64), "aarch_64"); ``` ``` -------------------------------- ### Compute SHA-256 Hash of Binary Data Source: https://context7.com/evanj/dlprotoc-rs/llms.txt Computes a raw 32-byte SHA-256 hash of the provided byte slice. Used internally for verifying downloaded archives and externally for generating hash entries. ```rust use dlprotoc::protoc_hash; fn main() { let data = b"hello world"; let hash: [u8; 32] = protoc_hash(data); // Format as lowercase hex string let hex: String = hash.iter().map(|b| format!("{b:02x}")).collect(); println!("{hex}"); // Output: b94d27b9934d3e08a52e52d7da7dabfac484efe04294e576b4b5f2fd35c37c2d... (truncated) } ``` -------------------------------- ### Handle Crate Errors Source: https://context7.com/evanj/dlprotoc-rs/llms.txt A simple string-message error type that implements `std::error::Error`, `Display`, and `From` conversions for common error types. Errors carry human-readable messages for propagation. ```rust use dlprotoc::Error; // Construct directly let err = Error::from_string("something went wrong".to_string()); assert_eq!(err.to_string(), "something went wrong"); // Use as a boxed std::error::Error let boxed: Box = Box::new(Error::from_string("oops".to_string())); eprintln!("Build error: {boxed}"); // Typical usage in build.rs — propagate with ? fn main() -> Result<(), Box> { dlprotoc::download_protoc()?; // dlprotoc::Error converts to Box automatically prost_build::compile_protos(&["src/example.proto"], &["src/"])?; Ok(()) } ``` -------------------------------- ### Error type Source: https://context7.com/evanj/dlprotoc-rs/llms.txt A simple string-message error type that implements `std::error::Error`, `Display`, and `From` conversions for `reqwest::Error`, `zip::result::ZipError`, and `std::io::Error`. Errors are not expected to be pattern-matched; they carry a human-readable message for propagation. ```APIDOC ## `Error` type — Crate error type A simple string-message error type that implements `std::error::Error`, `Display`, and `From` conversions for `reqwest::Error`, `zip::result::ZipError`, and `std::io::Error`. Errors are not expected to be pattern-matched; they carry a human-readable message for propagation. ```rust use dlprotoc::Error; // Construct directly let err = Error::from_string("something went wrong".to_string()); assert_eq!(err.to_string(), "something went wrong"); // Use as a boxed std::error::Error let boxed: Box = Box::new(Error::from_string("oops".to_string())); eprintln!("Build error: {boxed}"); // Typical usage in build.rs — propagate with ? fn main() -> Result<(), Box> { dlprotoc::download_protoc()?; // dlprotoc::Error converts to Box automatically prost_build::compile_protos(&["src/example.proto"], &["src/"])?; Ok(()) } ``` ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.