Recursive AI

Treat HLSL compiler warnings as errors

OneShader is a free, open-source HLSL compiler library for .NET from Recursive AI. MIT or Apache-2.0, no native dependencies.

Use -WX to fail a shader build on warnings. Warning.hlsl is in the zip; its first line, #warning Demo warning, triggers the example.

Terminal
dotnet tool install -g RecursiveAI.OneShader.Tool

Requires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.

Terminal
oneshader -WX Warning.hlsl -Fo out.spv

Unzip the example, then dotnet run.

The command exits with code 1 and doesn’t write out.spv:

Text
Warning.hlsl(1,1): warning OSH0115: #warning Demo warning
oneshader: error: warnings were reported and -WX is set; fix them or remove -WX.

The full program

Warning.hlsl contains a pixel shader that would compile if the warning were allowed:

HLSL
#warning Demo warning
[shader("pixel")]
float4 PSMain() : SV_Target { return 1; }

The project restores the pinned local tool from dotnet-tools.json; you don’t need the global install to run the zip. It checks the tool’s exit code and whether the tool wrote a file at a fresh output path.

The C# program only demonstrates the expected failure; in a real build, call oneshader -WX directly so the build runner sees the tool’s exit code.

C#
using System.Diagnostics;
 
var restore = Run("tool", "restore");
if (restore != 0) return restore;
 
var output = Path.Combine(Path.GetTempPath(), $"{Guid.NewGuid():N}.spv");
try
{
    var exit = Run("oneshader", "-WX", "Warning.hlsl", "-Fo", output);
    Console.WriteLine($"Exit code: {exit}");
    Console.WriteLine($"SPIR-V written: {File.Exists(output)}");
    return exit == 1 && !File.Exists(output) ? 0 : 1;
}
finally
{
    File.Delete(output);
}
 
static int Run(params string[] args)
{
    var start = new ProcessStartInfo("dotnet")
    {
        UseShellExecute = false,
        RedirectStandardOutput = true
    };
    foreach (var arg in args) start.ArgumentList.Add(arg);
    using var process = Process.Start(start)!;
    var stdout = process.StandardOutput.ReadToEnd();
    process.WaitForExit();
    if (process.ExitCode != 0) Console.Write(stdout);
    return process.ExitCode;
}

dotnet run prints:

Text
Warning.hlsl(1,1): warning OSH0115: #warning Demo warning
oneshader: error: warnings were reported and -WX is set; fix them or remove -WX.
Exit code: 1
SPIR-V written: False

The wrapper itself returns 0 when the deliberate failure behaves as expected.

Variations

Allow the warning but keep it in the log. With this fixture, removing -WX writes out.spv and returns 0:

Terminal
oneshader Warning.hlsl -Fo out.spv

The short answer

Pass -WX to the OneShader command line. The compiler still labels each warning warning, then the tool emits a separate error and exits with code 1 before writing output. It’s the command’s exit status, not the label on an individual diagnostic, that tells a build runner to stop. The -WX flag keeps the same warnings-as-errors meaning when you migrate an existing SPIR-V build.

What is the difference between a warning and an error?

A warning reports something worth checking even though compilation can continue. An error means the shader did not compile successfully. The fixture uses an explicit #warning so you can see that distinction without relying on a particular numeric conversion or shader feature to trigger it. Without -WX the shader compiles; the same warning appears on standard error either way. Check the process exit code rather than treating any text on standard error as a failed build.

Should I treat shader warnings as errors?

Use -WX in a build step when you want any reported shader warning to block the artifact. For example, if a job packages SPIR-V after compiling it, make packaging depend on a successful compiler exit. A failed compile does not remove previously written shader files, so a file left from an earlier build is not evidence that the current compile succeeded. Use a fresh output directory if stale files might otherwise be picked up. The flag applies to this shader command; it does not change the warning policy for a C# project or for a separate call to the runtime compiler API.

How do I disable treating warnings as errors?

Remove -WX from the invocation that is failing. That leaves warnings in the log but lets a successful compile write its files. It won’t turn a shader error into a warning: if the compiler rejects the source, the command still fails. If warnings are only welcome during local experiments, leave the flag off those local commands and keep it on in the build step that produces your release shaders.

All oneshader recipes