With this project, you can generate bindings to the Windows API for the V programming language.

Setting up

Before you run v run src, you will need to run the ./setup.ps1 script. The script will:

1. Download Microsoft.Windows.SDK.Win32Metadata from nuget, unpack it, move the .winmd file out of the extracted folder, and delete the zip file
2. Download Microsoft.Windows.SDK.Win32Docs from nuget, unpack it, move the apidocs.msgpack file out of the extracted folder, and delete the zip file
3. Generate a JSON file from the msgpack file using python. I have yet to figure out how to use the V implementation of msgpack for this, so that I can skip the conversion to JSON.

You can now run v run src to build the projection.

Motivation

All useful programs running on Windows eventually require calling into the Windows kernel. This means your program must link to some Windows library at a binary level, and include an associated C header file at a source level. To make use of the included structs and functions defined in Windows' C header files, you must redeclare these symbols in a .v.c file.

This is a manual process spanning thousands of structs and functions across the entire Windows API. Automating this collectively saves an enormous amount of manual labor across the V ecosystem.

Current plans

I plan on implementing two different sources of Windows metadata. One source is the json emitted by win32json. This is the easiest way to consume the metadata. The other alternative is to parse the winmd files generated by win32metadata.

The pros and cons of win32json:

• 🟩 Way simpler implementation
• 🟩 Cross platform
• 🟨 Might not always be 100% up to date with win32metadata

The pros and cons of using the metadata API:

• 🟩 Always up to date with win32metadata
• 🟨 Windows only. Generating the bindings is Windows only, using it is cross plaform

The pros and cons of rolling my own WinMD parser:

• 🟩 Always up to date with win32metadata
• 🟩 Cross platform
• 🟩 Basis for other community projects such as .NET interop
• 🟧 Vastly more time consuming

What is a winmd file?

Microsoft currently uses ClangSharp to scrape Windows C headers, outputting an .idl file in C# (or more specifically, ecma-335 compliant code). The C# output is then further compiled to a common language runtime (CLR) assembly, which is the final step. You now have a .winmd file.

Using the metadata API

Loading and reading winmd files is done with the metadata API. If you're not familiar with COM, read both the official documentation and a deep-dive article on COM in plain C. If you're not familiar with the CLR and the CLR assembly file format, read the official documentation and see the links in further reading further down in this readme

Instead of using CoCreateInstance directly, there is a factory function MetaDataGetDispenser we can use to kick things off. With the dispenser, we use OpenScope to open a winmd file, specifying either IID_IMetaDataTables2, IID_IMetaDataImport2 or IID_IMetaDataAssemblyImport as the interface.

Roadmap

Check the milestones. I'll try to update the milestones with new issues to reflect the progress.

Further reading

• Anatomy of a .NET Assembly – CLR metadata 1
• Anatomy of a .NET Assembly – CLR metadata 2
• Anatomy of a .NET Assembly – CLR metadata 3
• Anatomy of a .NET Assembly – Methods
• Anatomy of a .NET Assembly – PE Headers
• Anatomy of a .NET Assembly – Signature encodings
• Anatomy of a .NET Assembly – Custom attribute encoding
• Anatomy of a .NET Assembly – Type forwards
• Anatomy of a .NET Assembly – The CLR Loader stub
• Anatomy of a .NET Assembly – The DOS stub