Using the GitHub dxcompiler.dll

The simplest way for shader authors to build their shaders is to install the Windows SDK. Along with all the other files that support Windows applications and games, you'll get a command-line tool to build shaders (dxc.exe) as well as the the .dlls that support the actual functionality.

If you have Visual Studio installed, you can search your Start menu for something along the lines of 'Developer Command Prompt for VS 2017' and bring up a console program. Note that the name will vary a bit depending on what version of Visual Studio you may have installed. In any case, if you type where dxc on the command prompt, you'll get the path to dxc.exe as installed on your computer. For example, I have one such copy at C:\Program Files (x86)\Windows Kits\10\bin\10.0.15063.0\x86\dxc.exe. There is also a dxcompiler.dll next to that binary which provides most of the actual compiler functionality.

You will also find another copy of dxcompiler in a directory such as C:\Program Files (x86)\Windows Kits\10\Redist\D3D\x86\dxcompiler.dll, next to a few other files. Importantly, you'll also see dxil.dll there - more on that in a bit.

The DirectX Shader Compiler project over at https://github.com/Microsoft/DirectXShaderCompiler provides you the ability to build your own dxcompiler.dll compiler library. This allows you to build additional features, tooling, or fix issues that you care about or would like to see work differently. If there is a feature or a fix that we're building that interests you and you don't want to wait for a new Windows SDK to be released, you can grab binaries from GitHub or build them yourself.

It is important to note that the GitHub project will build dxcompiler.dll but not dxil.dll. By default, the binaries built from GitHub are set up such that they will perform validation of generated shaders, but they won't sign them. Unsigned shaders are fine to use in experimental mode, but will fail on an end user's computer with a message such as the following (in this case, for a compute shader).

 D3D12 ERROR: ID3D12Device::CreateComputeShader: Compute Shader is corrupt or in an unrecognized format. [ STATE_CREATION ERROR #322: CREATECOMPUTESHADER_INVALIDSHADERBYTECODE]

If you look at the warning when an unsigned shader is compiler, you'll see the following message.

 warning: DXIL.dll not found.  Resulting DXIL will not be signed for use in release environments.

To fix this, simply make dxil.dll available during compilation. The compiler will defer validation to this component, which is essentially the same validation code as that available on GitHub, but publicly and properly versioned so hardware drivers have a well-known and deterministic set of verified invariants to rely on (and possibly a reference for historical issues). And that's why there's both a dxcompiler.dll and dxil.dll available for redistribution - you can substitute your own dxcompiler.dll if you want to make changes to the language or compilation process, but dxil.dll will make sure that the instructions are sound for the hardware driver.

Of course, for features that are in development, you may compile a shader for which there is no matching dxil.dll that will accept it - and that's the point of experimental modes to begin with; it's at a subject-to-change point in time.

Enjoy!