Doc: How to generate my own .winmd from .h files and create a Rust crate depending on this one

[poliorcetics]

Doc request

I have header files in C that use the windows API through windows.h. I would like to generate .winmd metadata and then generate a Rust crate that would depend on this one (preferably windows but I can live with windows-sys).

I suspect, as this crate see more and more adoption, other people will want to do this. If this could be documented in somewhat-reproducible steps, it would be very nice.

Where I am at the moment

I managed to install ClangSharpPInvokeGenerator on Linux (somewhat long to get everything, but not that hard).

Now when I do ClangSharpPInvokeGenerator -o testgen -n my-company-crate -f my_company_header.h --language c, I get an error saying windows.h has not been found.

I suppose I can get past that by doing all this in a Windows VM (slow, but at least it will work easier I think).

How do I generate Rust code after that ?

Meta

I'm not sure if this is the correct place for such an issue, I saw nothing in the README about a place to discuss such "meta-issues"

[riverar]

I can take this on/write it up. I've done this several times now and am currently migrating another crate as well.

[kennykerr]

microsoft/windows-rs#1093 tracks generating metadata directly in Rust.

Until then @riverar can show you how to use the win32 metadata tooling to do so, but that's not specific to the windows crate, so perhaps this issue should be transferred to that repo for documentation.

[poliorcetics]

Generating a .winmd is only part of this issue.

My overall concern is having a documented way to generate crates from .h files that are compatible with windows-rs that way everyone will have the same HANDLE, the same WIN32_ERROR and so on, making it much much easier to publish such crates and make them interact with one another.

Having a way to do all this (even if it needs some external tools, though Rust-only tooling would be a very nice cherry on my cake) in a CI or a personal computer easily would make updating and maintaining such crates much more practical.

I'm aware this is a big issue and I don't want @riverar to feel pressured, take the needed time, this is not urgent !

[kennykerr]

I'm working on making the bindgen crate, used to generate the windows crate, easier to use. That should at least simplify part of this issue.

[riverar]

Closing as this has no direct correlation to the windows crate. Still working on this though! Will ping you again as soon as possible.

[riverar]

Re-opening this because it's becoming a hot issue that we essentially need to address, whether via FAQ edits, documentation (about 50% complete), additional tooling, etc.

[kennykerr]

I'm going to transfer this issue to the win32 metadata repo - that project should rightly own any documentation related to winmd generation from headers.

[mikebattista]

Assigning to @riverar based on the discussion.

[riverar]

https://withinrafael.com/2023/01/18/generating-metadata-for-the-windows-crate is now up @poliorcetics, feedback welcome!

[mikebattista]

@riverar I added an FAQ linking to your docs. Nice work!

[MarijnS95]

@riverar thanks for that write-up! Will you be doing a followup (perhaps requiring windows_bindgen changes) to (re)generate namespaces within Windows.? That's what we need in microsoft/DirectX-Headers#82 where it currently uses a whole bunch of super:: relations to (Foundation:: and other) modules/types that I do not want to generate as part of that crate (and should instead come from ::windows::...). It is probably non-trivial to tell the generator exactly what symbols or entire namespaces (all part of the same namespace tree) are built locally, and let everything else be sourced externally?

[riverar]

@MarijnS95 Hm, wasn't planning on that. I think the DirectX crate work you're doing needs to root at Microsoft. not the windows crate reserved Windows..

[MarijnS95]

@riverar sure, thinking of it that might immediately solve all these problems at once... As long as I generate the .winmd to use a different namespace.

[poliorcetics]

I have read the post, though I'll only have time to test next week (I hope not later), but it seems very well put together, congratulations and many thanks!

I wonder if this would work in a nix environment with the windows SDK installed (with the proper variables set as necessary), but I can live with having to compile bindings on windows once in while if it means getting rid of manually written bindings 🎉

[riverar]

@MarijnS95 Might be metadata tooling running with the first type it found. Maybe you can workaround that with something similar to https://github.com/microsoft/win32metadata/blob/main/generation/WinSDK/requiredNamespacesForNames.rsp

[riverar]

and see if @kennykerr can publish this to https://crates.io/crates/windows-directx in due time.

The windows prefix, like in namespaces, is ideally best left for Windows OS APIs. For this upcoming crate, microsoft-directx seems more fitting for an official crate (e.g. microsoft-dia)

[damyanp]

The windows prefix, like in namespaces, is ideally best left for Windows OS APIs.

The APIs described in the DirectX headers are Windows OS APIs though and I'm not sure that they're really the same case as microsoft-dia which really is a separate SDK.

I think that the overlapping definitions problem is one that we're going to have to tackle head on.

[riverar]

Marked my comment as outdated, as we're discovering the DirectX SDK is just a faster moving ship vehicle microsoft/DirectX-Headers#82 (comment)