Add optional warnings for windows-bindgen to improve diagnostics

[kennykerr]

This adds the ability to retrieve any warnings that the bindgen function may decide to collect and return as part of code generation that may or may not be an error depending on the context. For example, let's say you're calling bindgen as follows from your build script:

fn main() {
    windows_bindgen::bindgen([
        "--out",
        "src/bindings.rs",
        "--filter",
        "Windows.Win32.System.Com.IPersistFile",
    ]);
}

All goes well until you realize that the IPersistFile.Load method was omitted due to a missing dependency. This may or may not be what you wanted. If not, it can be quite tedious to chase down all of the missing dependencies for a larger filter that may span multiple interfaces with many dozens or even hundreds of methods.

Fortunately, windows-bindgen can gather these up and return this information for you:

fn main() {
    let warnings = windows_bindgen::bindgen([
        "--out",
        "src/bindings.rs",
        "--filter",
        "Windows.Win32.System.Com.IPersistFile",
    ]);

    if !warnings.is_empty() {
        panic!("{warnings}");
    }
}

The resulting Warnings type is just a collection of strings. It also provides a convenient unwrap method to make your build scripts a bit more concise if you prefer:

fn main() {
    windows_bindgen::bindgen([
        "--out",
        "src/bindings.rs",
        "--filter",
        "Windows.Win32.System.Com.IPersistFile",
    ]).unwrap();
}

Either way, here's what the panic message contains:

  thread 'main' panicked at build.rs:7:8:
  skipping `Windows.Win32.System.Com.IPersistFile.Load` due to missing dependencies:
    Windows.Win32.System.Com.STGM

You can then decide to add STGM to your filter and the Load method will be generated and the "warning" disappears:

fn main() {
    windows_bindgen::bindgen([
        "--out",
        "src/bindings.rs",
        "--filter",
        "Windows.Win32.System.Com.IPersistFile",
        "Windows.Win32.System.Com.STGM",
    ]).unwrap();
}

The solution is generic enough that other warnings can conceivably be added in future. And no you can't turn off some warnings. 🙃 Use it for diagnostics and then turn it off if you'd like to skip some but not all methods. For anything more elaborate, feel free to enumerate the warnings yourself.

[riverar]

Very cool, this will save a bunch of time, thanks!