Using API Notes to Annotate Win32 Header Files

Development Windows
,
1

As a matter of personal interest, I was writing some Win32 code with Swift. The core header support is excellent, thanks I believe to @compnerd and his patient work.

But I'd like to work at tweaking some of the annotations. For example, in the following call:

MessageBoxA(nil, "Hello from Swift running on Windows", "Swift Message Box", UINT(MB_ICONINFORMATION))

MB_ICONINFORMATION is declared in the C headers as 0x00000040L, which Swift interprets as a signed value. Ideally we'd fix this so that it was interpreted as an unsigned value, so the cast isn't required in the MessageBoxA call.

My understanding was that we can use API Notes to add an annotation that would be picked up at compile time. And indeed, I see vcruntime.apinotes in the platform folder alongside the corresponding .modulemap file.

But when I try and create winsdk.apinotes in the same folder as a sidecar to the .modulemap file, it doesn't seem to get picked up by the compiler.

Is there something else I have to do to get the .apinotes file to be recognized by the compiler?

3 Likes
2

The compiler uses the recognized support files as a VFS overlay to provide seamless integration, without actually copying them (if you noticed the Traditional Installation steps…).

So the workaround is simple: copy your winsdk.apinotes to where winsdk.modulemap actually is: %UniversalCRTSdkDir%\Include\%UCRTVersion%\um\. If you don’t have administrator access, or do not want to patch every time Windows SDK is upgraded, you can also put it in %SDK_ROOT%\usr\lib\swift\apinotes\, where Apple OSes put their system API notes.

3

Thanks for the quick reply.

I wasn't able to get my API notes working by putting them into %SDKROOT%\usr\lib\swift\appnotes, but putting a copy into %UniversalCRTSdkDir%\Include\%UCRTVersion%\um\ worked a treat. Thanks for sharing the magic incantation!

4

Adding additional APINotes for the imports is a great idea, but not something that I've gotten around to. I don't think that there is anything that is preventing this work other than time, and so if you have a starting point for this, I think that would be a welcome addition. Perhaps we could even start draining some of the overloads that are in the WinSDK overlay.

1 Like
5

This was an apparent typo:)

6

Ah, just in the forum. I did get the right directory in Windows, though, and it didn't work:

C:\Users\timsneath\AppData\Local\Programs\Swift\Platforms\5.10.0\Windows.platform\Developer\SDKs\Windows.sdk\usr\lib\swift\apinotes>dir
 Volume in drive C has no label.
 Volume Serial Number is 3687-05AC

 Directory of C:\Users\timsneath\AppData\Local\Programs\Swift\Platforms\5.10.0\Windows.platform\Developer\SDKs\Windows.sdk\usr\lib\swift\apinotes

03/28/2024  01:43 PM    <DIR>          .
03/25/2024  12:32 PM    <DIR>          ..
03/05/2024  06:20 PM               205 std.apinotes
03/28/2024  02:03 PM               331 winsdk.apinotes
               2 File(s)            536 bytes
               2 Dir(s)  197,678,280,704 bytes free