Added new build options and shader file inclusion overrides.

[sinnwrig]

Description

Multiple new options have been added to the build system in order to build mach-dxcompiler for more various use cases, and an addition to the API has been made in order to override default DXC file inclusion behavior.

Additional Build Features

Four new build options have been added to build.zig:

• -Dshared Build machdxcompiler as a shared library alongside the static library.
• -Dspirv Build SPIR-V codegen support for machdxcompiler.
• -Dskip_executables Skip building machdxcompiler executable (Implicitly skips tests)
• -Dskip_tests Skip building machdxcompiler-tests executable

API Changes

• machDxcCompile function signature has been changed, accepting a MachDxcCompileOptions struct.

  • MachDxcCompileOptions struct typedef has been added, containing the following fields:
    • char const* code` (UTF-8)
    • size_t code_len
    • char const* const* args (UTF-8)
    • size_t args_len
    • MachDxcIncludeCallbacks* include_callbacks (null falls back to default behavior)

• The ability to override the default DXC file includer has been added to the C API.

  • MachDxcIncludeCallbacks struct typedef has been added, containing the following fields:

    • MachDxcIncludeFunc* include_func
    • MachDxcFreeIncludeFunc* free_func
    • void* context

  • MachDxcIncludeResult struct typedef has been added, containing the following fields:

    • const char* header_data (UTF-8)
    • size_t header_length

  • MachDxcIncludeFunc function type definition has been added.

    • Receives void* as context.
    • Receives const char* as header name in UTF-8.
    • Returns MachDxcIncludeResult*.

  • MachDxcFreeIncludeFunc function type definition has been added.

    • Receives void* as context.
    • Receives MachDxcIncludeResult* to free.
    • Returns int exit code.

Implementation details

• Shared library building links the static library when compiling a minimal .cpp file.

• Executable and test generation are now behind compilation flags.

• SPIR-V codegen support builds tools/clang/lib/SPIRV sources in addition to core DXC sources, and links to an external dependency on hexops/spirv-tools.

• DXC inclusion behavior has been routed through the provided function pointers using a minimal class inheriting from IDxcIncludeHandler.

Known Issues

• There appears to be no issues with SPIR-V compilation or shared library support. However, certain combinations of input arguments, such as mixing '-Zi' with '-spirv' may cause segmentation faults.

[emidoots]

@sinnwrig can you rebase onto latest main which updates the zig version? I'll review this soon

[emidoots]

getting this merged upstream here might be a fair bit of work - we can chat about it though

[sinnwrig]

getting this merged upstream here might be a fair bit of work - we can chat about it though

Looking at the reviews, a lot of problems should be resolved if an external repo of SPIRV-Tools built with zig is used instead.

[sinnwrig]

spirv compilation now depends on hexops/spirv-tools in the .zon file.

[PaperPrototype]

why is this not merged yet

[emidoots]

Closing in favor of https://github.com/hexops/mach-dxcompiler/pull/7 which I promise I will actually merge soon.