Support for embedding Windows Manifest XML to the compiled exe

[expikr]

I don't see anything in the documentation (or any Google Search results) about how to embed an application manifest XML when compiling for Windows (or any info regarding embedding resources of any kind like icons and cursors, for that matter).

Would be nice to support this functionality so that you can actually build Windows apps with hidpi support.

[squeek502]

(or any info regarding embedding resources of any kind like icons and cursors, for that matter).

Zig recently got full support for compiling .rc files and linking the resulting .res files. See #17069 for how to use it.

Will look into manifest files to see what would be involved in supporting them (does LLD handle them?)

EDIT: It looks like the manifest is embedded in the binary as a resource of type RT_MANIFEST. It also looks like lld might have support for embedding manifests on the command line: /manifest:embed /manifestinput:manifestfile, so basic support for this shouldn't be too hard.

Relevant links:

• https://learn.microsoft.com/en-us/cpp/build/reference/manifest-tool-property-pages
• https://learn.microsoft.com/en-us/cpp/build/reference/manifest-create-side-by-side-assembly-manifest
• https://learn.microsoft.com/en-us/cpp/build/reference/manifestinput-specify-manifest-input
• https://learn.microsoft.com/en-us/windows/win32/SbsCs/manifest-files-reference

---

EDIT#2: I believe you could also use an .rc file to get manifest support in the master version of Zig right now:

// Not sure how the ID matters, seems like `1` is commonly used for embedded manifests AFAICT
#define MANIFEST_ID 1
// 24 is the value of RT_MANIFEST, `.rc` files don't have a keyword for RT_MANIFEST but you can specify the type directly like this
MANIFEST_ID 24 "yourmanifest.manifest"

It seems like the XML is just used verbatim as the resource data, so in theory this should work fine.

Seems like there is some processing of the xml file before embedding, so this workaround won't work correctly see #17406 (comment).

[mlarouche]

Also useful to force UTF-8 codepage in a application when using the ASCII version of the API: https://learn.microsoft.com/en-us/gaming/gdk/_content/gc/system/overviews/utf-8

[squeek502]

Looked into this a bit. Some notes:

• An embedded manifest file is really just XML data embedded as a RT_MANIFEST resource (ID = 24)
• The MSVC tool mt.exe is what's used to handle manifest files. The stuff it seems to do:
  • Convert manifest files to UTF-8 before embedding
  • Add and modify some stuff in the XML before embedding
  • Remove whitespace before embedding

For example, this manifest (encoded as UTF-16 LE with BOM):

<?xml version="1.0" encoding="UTF-16"?>
<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
  <assemblyIdentity type="win32" name="..." version="6.0.0.0"/>
  <application>
    <windowsSettings>
      <activeCodePage xmlns="http://schemas.microsoft.com/SMI/2019/WindowsSettings">UTF-8</activeCodePage>
    </windowsSettings>
  </application>
</assembly>

ends up as this when embedded in the .exe (note: mt.exe always includes a BOM encoded as UTF-8 at the start regardless of the input encoding):

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<assembly manifestVersion="1.0" xmlns="urn:schemas-microsoft-com:asm.v1"><assemblyIdentity type="win32" name="..." version="6.0.0.0"></assemblyIdentity><trustInfo xmlns="urn:schemas-microsoft-com:asm.v3"><security><requestedPrivileges><requestedExecutionLevel level="asInvoker" uiAccess="false"></requestedExecutionLevel></requestedPrivileges></security></trustInfo><ms_asmv1:application xmlns:ms_asmv1="urn:schemas-microsoft-com:asm.v1"><ms_asmv1:windowsSettings xmlns:ms_asmv1="urn:schemas-microsoft-com:asm.v1"><activeCodePage xmlns="http://schemas.microsoft.com/SMI/2019/WindowsSettings">UTF-8</activeCodePage></ms_asmv1:windowsSettings></ms_asmv1:application></assembly>

• The modifications mt.exe makes do not seem to actually be necessary for the embedded manifest to work as intended. The UTF-16 encoded manifest embedded directly as a resource (via an .rc file with the contents 1 24 test.manifest) still has the intended effect on the compiled program.
• clang seems to want to call mt.exe for manifest embedding if the host is Windows.

  > clang test.c -Xlinker /manifest:embed -Xlinker /manifestinput:test.manifest -o test.exe
  LINK : fatal error LNK1158: cannot run 'mt.exe'
  

• LLVM has llvm-mt but it seems to not support most options (only .manifest to .manifest conversion?), and I'm unsure how/if it's used by clang. That is, I haven't yet figured out if LLVM supports embedding manifest files when cross-compiling from non-Windows hosts.

---

How I am testing things:

• The "Fusion manifest for an unpackaged Win32 app" from here saved as test.manifest
• test.c (encoded as UTF-8):

  #include <windows.h>
  
  int main() {
      return MessageBoxA(NULL, "кириллица", "hello", MB_OK);
  }

• test.rc:

  1 24 "test.manifest"
  

Compiling with clang:

clang test.c -luser32 -Wl,/manifest:embed -Wl,/manifestinput:test.manifest -o test-clang.exe

Compiling with zig + mt.exe

zig build-exe test.c -lc -femit-bin=test-mt.exe
mt.exe -manifest test.manifest -outputresource:test-mt.exe

Compiling with zig only:

zig build-exe test.c test.rc -lc -femit-bin=test-zig.exe

All 3 produce this (expected) result:

If the manifest was not included, the message box would instead show up like this:

---

So, the options as I see them currently:

1. Go down the rabbit-hole and create a full cross-platform mt.exe alternative. This would involve at minimum an XML parser.
2. Investigate LLVM more and see if passing /manifest:embed /manifestinput:test.manifest linker flags would be enough to get cross-compilation of manifest files working
3. Auto-generate .rc files for .manifest files and just embed the XML verbatim. This would get us support for manifest files really quickly almost for free, but may not support all possible manifests, as there may be something about the transformations mt.exe do that actually matter.

[squeek502]

Implemented option 3 here: #17448. Still figuring out how viable it is.

[squeek502]

@expikr, that sort of thing was discussed in #17069 (comment)

My position is basically the same as it was then:

My position is that the clunky RC language is necessary for use cases that I think Zig cares about (compiling existing .rc files, people that know how to write RC files not needing to learn something new), and that Zig making its own better "compiles to .res" language/build system would not be able to enable the same use cases. It would be nicer to use for sure, but I think the potential benefit is small enough that it's not worth the effort.

Also worth noting that if you want to write a Build step that takes a .zon and outputs an .rc file, then that could technically be done in userland right now (addWin32ResourceFile can accept a generated file). Or, put another way, it would be possible to implement it as a 3rd party library that then could get merged into Zig if it ends up being useful.