package

github.com/mjblack/winmd

1.5.0 / published Nov 11, 2026 / repository

Crystal Windows Metadata bindings generator

winmd

Win32 API metadata bindings generator.

The generator supports:

  • JSON metadata input (win32json-style)
  • Native .winmd input via ecma335

Installation

  1. Add the dependency to your shard.yml:

    dependencies:
      winmd:
        github: mjblack/winmd
  2. Run shards install

Usage

Run the command bin\winmd.exe from the shard itself or from your own shard.

Examples:

# Existing JSON-based flow
bin/winmd generate ./path/to/json ./out

# Native WinMD flow
bin/winmd generate --source-format winmd ./winmd/Windows.Win32.winmd ./out

Both flows read the optional override files (data_type_aliases.json, dll_exceptions.json, fun_exceptions.json, overrides.json) from the current directory, so run the generator from the directory that holds them. Examples live in examples/overrides.

WinMD input

With --source-format winmd the metadata is parsed by the ecma335 shard and converted, namespace by namespace, into the same document shape that win32json produces. Everything downstream (templates, overrides, aliases) is shared with the JSON flow, so the output is laid out and named identically. Constants, enums, structs, unions (with nested types and per-architecture variants), native typedefs, function pointers, COM interfaces and functions are all imported.

Extra flags for this mode:

  • --dump-json DIR writes the intermediate <Api>.json documents to DIR. They are useful for diffing against real win32json output or for debugging a conversion.
  • --associated-enums types integer parameters and struct fields that carry an AssociatedEnum attribute as that enum. Current metadata declares these as plain integers; the flag reproduces the enum-typed signatures that older metadata (and win32json builds based on it) had.

GUID-valued constants are emitted as LibC::GUID values, and PROPERTYKEY / DEVPROPKEY constants as struct values, in addition to what the JSON flow produces. Constants typed by a pointer typedef (HKEY_LOCAL_MACHINE, INVALID_HANDLE_VALUE, HWND_BROADCAST, ...) are emitted as typed pointers, e.g. HKEY.new(0xffffffff80000002_u64), matching the casts in the C headers.

Functions that Crystal's LibC already declares

A C function may only be declared once per program unless every declaration has the same signature, so functions that Crystal's standard library already declares in lib LibC (GetLastError, CloseHandle, HeapAlloc, ...) are not declared again in the generated lib C. Their module-level wrappers are still generated and forward to the stdlib declaration:

# Forwards to `LibC.HeapAlloc`, which Crystal's standard library declares in `c/heapapi`.
def heapAlloc(hHeap : Win32cr::Foundation::HANDLE, dwFlags : Win32cr::System::Memory::HEAP_FLAGS, dwBytes : LibC::UIntPtrT) : Void*
  Win32cr::LibCBridge.ret(::LibC.HeapAlloc(Win32cr::LibCBridge.arg(hHeap, ::LibC::HANDLE), ...), Pointer(Void))
end

The two sides spell the same C types differently (a Flags enum vs DWORD, Win32cr::Foundation::FILETIME* vs LibC::FILETIME*, HKEY vs the opaque LibC::HKEY), so a generated src/<lib>/libc_bridge.cr converts each argument to LibC's type and the result back. Files with such wrappers require the stdlib file that declares the function (c/heapapi, ...).

The list of functions is not built into winmd. At generation time it asks the crystal on PATH (or WINMD_CRYSTAL) for its stdlib location and default target and parses every fun declared under src/lib_c/<target>/ and src/crystal/system/<os>/, so it always matches the compiler that will build the bindings. winmd libc prints the names and winmd libc --signatures the declarations. Where no compiler is available, --libc-funs FILE supplies the names (one per line) instead; without signatures the wrappers of those functions are commented out, as are those of names listed in fun_exceptions.json (for functions your own code declares in LibC).

Development

Build the CLI:

shards install --skip-postinstall
shards build

Run the specs:

crystal spec

The importer integration specs need Windows.Win32.winmd. Fetch the version pinned in winmd.version into winmd/ (or point WINMD_FIXTURE at a copy):

pwsh ./scripts/fetch-winmd.ps1

CI (.github/workflows/ci.yml) runs the specs on Windows and then generates bindings from the pinned metadata and compiles a set of representative namespaces.

Releasing

Bump version in shard.yml, merge, then push a matching tag:

git tag -a v1.4.0 -m "winmd 1.4.0"
git push origin v1.4.0

The release workflow (.github/workflows/release.yml) checks that the tag matches shard.yml, runs the specs, builds a static winmd.exe, and publishes a GitHub release with winmd-<version>-windows-x86_64.zip (binary, README, LICENSE, example override files) and its SHA-256. Run it manually from the Actions tab with an existing tag to attach a binary to a release that was created by hand.

Contributing

  1. Fork it (https://github.com/mjblack/winmd/fork)
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

Contributors

API