winmd
Version, currently 1.5.06 versions
github.com/mjblack/winmd
Crystal Windows Metadata bindings generator
Installation
# Add this to your shard.yml
dependencies:
winmd:
github: mjblack/winmd
version: ~> 1.5.0Then run:
shards installshard.yml
- Crystal
>= 1.19.1- License
- MIT
- Author
- Matthew J. Black
- Target
winmdfrom src/cli.cr
Dependencies
Runtime Dependencies
- admiral*github: jwaldrip/admiral.cr
- ecma335~> 1.2.0github: mjblack/ecma335
- git-repository*github: place-labs/git-repository
Development Dependencies
- ameba*github: crystal-ameba/amebadev
README
winmd
Win32 API metadata bindings generator.
The generator supports:
- JSON metadata input (win32json-style)
- Native
.winmdinput viaecma335
Installation
-
Add the dependency to your
shard.yml:dependencies: winmd: github: mjblack/winmd -
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 DIRwrites the intermediate<Api>.jsondocuments toDIR. They are useful for diffing against real win32json output or for debugging a conversion.--associated-enumstypes integer parameters and struct fields that carry anAssociatedEnumattribute 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
- Fork it (https://github.com/mjblack/winmd/fork)
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - Create a new Pull Request
Contributors
- Matthew J. Black - creator and maintainer
Documentation
Built from the current release. The first visit to a release nobody has asked for starts its build.
Links
This release
- Version
1.5.0- Tagged
- Nov 11, 2026
- Commit
71a0ae427cf5- Crystal
>= 1.19.1- Indexed
- yes
Dependents
Repository
github.com/mjblack/winmd
Metadata
- Created
- Aug 12, 2026
- Updated
- Nov 12, 2026
- Synced
- Nov 12, 2026
- Versions
- 6