Document published-crate workflows for `windows-bindgen`

[tim-weis]

Suggestion

The documentation in docs/crates/windows-bindgen.md sufficiently covers the leaf-application case: add a build script that runs code generation and surface the generated artifacts.

That pattern also works for crate authors, so long as --out is directed toward %OUT_DIR%.

What the documentation does not cover is the case where a crate author wants the generated code to be part of the published crate itself, while still keeping code generation in situ during development.

Could the documentation be updated to include this use case?

[kennykerr]

What do you mean by published crate? Like the windows or windows-sys crates where the bindings are simply published as is?

[tim-weis]

Consider a hypothetical tickcount crate with the following shape:

Cargo.toml

[package]
name = "tickcount"
version = "0.1.0"
edition = "2024"

[dependencies]
windows-link = "0.2"

[build-dependencies]
windows-bindgen = "0.66" 

build.rs

use windows_bindgen::bindgen;

fn main() {
    bindgen([
        "--out",
        "src/bindings.rs",
        "--flat",
        "--sys",
        "--filter",
        "GetTickCount64",
    ])
    .unwrap();
}

src/lib.rs

mod bindings;
use bindings::GetTickCount64;

pub fn get_tick_count() -> u64 {
    unsafe { GetTickCount64() }
}

When publishing this crate, I would like to swap out the build script and windows-bindgen dependency for the generated src/bindings.rs file. Obviously, I could literally just do that, though I'd also like to keep the binding generation support for future updates.

When I initially submitted the issue, I genuinely didn't know how to approach this. I've since moved to a Cargo workspace with a binary bindgen workspace member to separate code generation and the library, while keeping both under the same repository. It would be helpful to have the documentation cover this use case.