1Introduction

zdxc is a from-scratch HLSL 2021 compiler written in Zig. It emits DXIL and SPIR-V and has no package dependencies. The same compiler is available through four interfaces:

The source language is HLSL 2021; -HV 2021 is the only language version. DXIL output is signed by zdxc itself, so no separate dxil library is needed.

2Getting started

Requirements

Install Zig 0.17.0 or newer. zdxc has no library or package dependencies.

Build

Run the build from the zdxc package directory:

zig build -Doptimize=ReleaseFast

The default install contains:

zig-out/bin/zdxc          command-line compiler
zig-out/lib/libzdxc.a     static C library
zig-out/include/zdxc.h    public C header

Build a shared C library instead with -Dlinkage=dynamic. Cross-compilation uses Zig's usual target option:

zig build -Dtarget=x86_64-windows-gnu -Doptimize=ReleaseFast

Compile a shader

The command line follows dxc. Specify a target profile, entry point, input, and output file:

./zig-out/bin/zdxc -T cs_6_0 -E main shader.hlsl -Fo shader.dxil
./zig-out/bin/zdxc -T vs_6_0 -E main -spirv shader.hlsl -Fo shader.spv

Use zdxc -help for the complete option list and zdxc --version for the compiler version.

3Command line

zdxc accepts dxc command-line arguments. A compilation can read its input from a file or, through the library interfaces, from memory.

DXIL is the default backend. Add -spirv for SPIR-V, with the -fvk-* and -fspv-* options controlling Vulkan bindings, layout, and target environment.

Diagnostics and exit status

Diagnostics follow dxc's command-line format. Exit status is 0 for success, 1 for bad options or input/output failures, and 5 for source compilation errors. Warnings can appear in successful compilations.

4Batch compilation

zdxc --job=build/shaders.json compiles every shader a job file lists in one process, on all cores. Starting a process costs more than compiling most shaders (about 2 ms against a few hundred microseconds), so a build with many shaders is much faster this way than with one compiler run per shader.

On the 1,481 corpus shaders zdxc compiles (10-core M-series Mac, release build):

The job file

{
  "threads": 8,
  "args": ["-HV", "2021", "-I", "shaders/include"],
  "jobs": [
    { "args": ["-T", "cs_6_0", "shaders/blur.hlsl", "-Fo", "out/blur.dxo"] },
    { "args": ["-T", "ps_6_0", "-E", "PS", "shaders/mesh.hlsl", "-Fo", "out/mesh_ps.dxo"] },
    { "args": ["-T", "vs_6_0", "-E", "VS", "-spirv", "shaders/mesh.hlsl", "-Fo", "out/mesh_vs.spv"] }
  ]
}

• jobs (required): each job's args is a dxc command line without the program name — any option zdxc accepts on its own command line.
• args (optional): options shared by every job.
• threads (optional): how many shaders compile at once. Defaults to the number of CPUs.

A job's full command line is the file's args, then any options given next to --job on the real command line, then the job's own args. So zdxc --job=shaders.json -O3 -Qstrip_debug adds -O3 -Qstrip_debug to every job, and a job can override a shared option where a later option wins on the command line. Unknown fields are errors, reported with their line and column.

Paths in the file are relative to the current directory, as on the command line, not to the job file. --job cannot appear inside a job file.

Output and exit code

Every job writes its own -Fo / -Fh / ... outputs. What a job prints — diagnostics, and text output such as -P without a file — comes out exactly as one zdxc run of that command line would print it, kept together and in job order, whatever order the jobs finish in. The outputs are byte-identical to separate runs.

When jobs fail, the other jobs still run, and a last line says how many failed:

zdxc: 2 of 112 jobs failed

The exit code is 0 when every job succeeds; otherwise 1 if any job failed on its command line or on I/O (a missing input, an unwritable output), else 5 (compile errors) — the codes one zdxc run uses.

Reading and writing files is kept off the compiling threads: one thread reads the jobs' input files ahead of the compiles, and another writes their outputs after them. Files the jobs include are read once for the whole run, so a header that every shader includes is opened once (a file that changes while the run is going is not read again). An output that cannot be written is reported after every job's output, and fails its job.

5The C API

zdxc is also a library with a small C API, include/zdxc.h. Unlike dxcompiler, it links statically: there is no DLL to ship or load, no COM, and nothing to link besides the platform's C library.

zig build                       # zig-out/lib/libzdxc.a, zig-out/include/zdxc.h
zig build -Dlinkage=dynamic     # libzdxc.so / .dylib / zdxc.dll instead
zig build -Dtarget=x86_64-windows-gnu -Doptimize=ReleaseFast

Link libzdxc.a like any static library (cc app.c -Izig-out/include zig-out/lib/libzdxc.a). It exports only the zdxc_* functions; the compiler runtime it carries is hidden. For a macOS binary you ship, give the target a minimum version (-Dtarget=aarch64-macos.13.0), or the linker warns that the library was built for a newer macOS than the app.

Compiling

A compilation is a dxc command line, with the outputs returned in memory:

#include <zdxc.h>

const char *args[] = {"-T", "ps_6_0", "-E", "PS", "-D", "SHADOWS=1"};
zdxc_compile_info info = {
    .size = sizeof info,
    .args = args,
    .arg_count = 6,
    .source = text,
    .source_size = text_size,
    .source_name = "mesh.hlsl",
};
zdxc_result *r = zdxc_compile(&info);
if (!r) return OUT_OF_MEMORY;

const char *diags = zdxc_result_output(r, ZDXC_OUTPUT_DIAGNOSTICS, NULL);
if (diags) fputs(diags, stderr);            /* errors, or warnings on success */

if (zdxc_result_status(r) == ZDXC_STATUS_OK) {
    size_t size;
    const void *dxil = zdxc_result_output(r, ZDXC_OUTPUT_OBJECT, &size);
    upload(dxil, size);
}
zdxc_result_free(r);

• Options are exactly the command line's (-T, -E, -D, -I, -spirv, -fvk-*, -Zpr, -O3, ...), without the program name.
• The source is in memory (source, with or without a trailing NUL), or, when source is NULL, the input file named in the options.
• Files — the input when given by name, and every #include candidate — are read from disk relative to the current directory, unless you pass a read_file callback. The callback gets each candidate path (the including file's directory, then each -I directory) and returns 0 with the file's bytes, or nonzero to try the next candidate. Returned memory only has to last until zdxc_compile returns.
• Status is ZDXC_STATUS_OK (0), ZDXC_STATUS_FAILED (1: bad options, unreadable input) or ZDXC_STATUS_COMPILE_FAILED (5: errors in the source) — the command line's exit codes. zdxc_compile returns NULL only when out of memory.
• Outputs are OBJECT (a DXIL container or SPIR-V module), DIAGNOSTICS, PREPROCESSED (-P), ROOT_SIGNATURE (-Frs) and TEXT (-help, --version). Each is NUL-terminated for convenience and lives until zdxc_result_free. zdxc_result_output_name gives the name an option assigned (-Fo, -Fi, -Frs); zdxc never writes files.

The output is byte-for-byte what the command line writes for the same options and files.

Threads

zdxc has no global state. Any number of threads may call zdxc_compile at once, and a result may be read or freed on any thread.

Zig

Zig projects can skip the C API: depend on this package and import the zdxc module, whose compile.compile(arena, request) is what the C API wraps.

6The DXC drop-in

Programs that run DXC usually do it in one of two ways: they call the dxc executable, or they load dxcompiler (dxcompiler.dll, libdxcompiler.so, libdxcompiler.dylib) and call DxcCreateInstance. SDL_shadercross, for one, does the second. The dropin step builds both on top of zdxc, so these programs can use zdxc without being changed:

zig build dropin                # zig-out/bin/dxc, zig-out/lib/libdxcompiler.{so,dylib}
zig build dropin -Dtarget=x86_64-windows-gnu -Doptimize=ReleaseFast
                                # zig-out/bin/dxc.exe, dxcompiler.dll, lib/dxcompiler.lib

Put them where the program looks for DXC, in place of DXC's files. There is no dxil.dll: zdxc signs DXIL itself.

• dxc is the zdxc command line under DXC's name.
• dxcompiler exports DxcCreateInstance and DxcCreateInstance2, with dxcapi.h's ABI. On Windows it imports only kernel32 and ntdll. On other platforms it links the C library and nothing else.

What the library implements

Compile takes the same arguments as the command line and follows DXC:

• Status. A compile error is a successful call whose status is E_FAIL. A bad option has status E_INVALIDARG.
• Outputs. The result holds the same outputs DXC's does: the object, the errors (UTF-8, empty when there are none), the shader hash for DXIL, the root signature, -P text, and the names given with -Fo, -Fi and -Frs.
• Includes. Includes go through the IDxcIncludeHandler you pass, with paths spelled the way DXC spells them (./inc/common.hlsli). With no handler, includes fail, as they do in DXC.
• Accepted-but-ignored options. Options that zdxc accepts but does not act on yet produce no note here. Many clients treat any diagnostic text as a warning.

Classes and methods that are not implemented return REGDB_E_CLASSNOTREG or E_NOTIMPL. These include:

• the legacy IDxcCompiler and IDxcCompiler2 interfaces;
• Disassemble;
• CreateReflection, BuildArguments and GetPDBContents;
• the validator, linker, container and PDB classes.

The result has no DXC_OUT_REFLECTION output (the reflection container that CreateReflection reads).

Language support is zdxc's own: HLSL 2021, with -HV 2021 as the only version.

7Zig integration

Declare zdxc as a package dependency, then make its module available to your executable or library:

const zdxc = b.dependency("zdxc", .{
    .target = target,
    .optimize = optimize,
});
exe.root_module.addImport("zdxc", zdxc.module("zdxc"));

Import the module and call the same compilation layer used by the command line and C API:

const std = @import("std");
const zdxc = @import("zdxc");

pub fn compileShader(arena: std.mem.Allocator, io: std.Io, source: []const u8) !zdxc.compile.Result {
    return zdxc.compile.compile(arena, .{
        .args = &.{ "-T", "ps_6_0", "-E", "PS", "-D", "SHADOWS=1" },
        .source = source,
        .source_name = "mesh.hlsl",
        .io = io,
    });
}

The returned result contains the status, object, diagnostics, and any requested auxiliary outputs. Its allocations belong to the supplied arena. The compiler does not write files; -Fo, -Fi, and -Frs only name the corresponding in-memory outputs.

8API reference

The public C API is declared in zdxc.h. Each symbol below has its declaration, ownership rules, and a link to the corresponding source line.