Contributing Guide

This page distills the contributor-facing essentials. The authoritative project guidance lives in CLAUDE.md and the phase plans under plan/ in the repository.

The purpose (keep this straight)

The product is the in-memory IShaderCompiler library (ShadowDusk.Compiler): add the package, call CompileAsync(fx), get .mgfx bytes — on Linux, macOS, or Windows, with nothing else to install. The CLI and the (future) MGCB plugin are delivery shapes of the same library. The in-browser fiddle is only a sample of reach. There are no substitute compilers: every host runs the same faithful pipeline.

Repository layout

Path What
src/ShadowDusk.Core Contracts & shared types: IShaderCompiler, Result<T,E>, ShaderError, CompilerOptions, CompiledShader, ShaderIR, the MGFX writer, reflection (SpirvReflector), preprocessor.
src/ShadowDusk.HLSL FX9 pre-parser, preprocessor, DXC integration, HLSL reflection, vkd3d-shader + d3dcompiler_47 DXBC backends.
src/ShadowDusk.GLSL SPIR-V → GLSL via SPIRV-Cross + the MonoGameGlslRewriter (MojoShader dialect).
src/ShadowDusk.Compiler EffectCompiler : IShaderCompiler — the product NuGet.
src/ShadowDusk.Cli the mgfxc dotnet tool.
src/ShadowDusk.Wasm in-browser WasmShaderCompiler ([JSImport] DXC + SPIRV-Cross).
src/ShadowDusk.Metal, src/ShadowDusk.MgcbPlugin stubs (not implemented).
tests/ Core/HLSL/GLSL/Compiler unit tests, Integration.Tests, ImageTests, BrowserTests, and fixtures/ (the .fx corpus + golden .mgfx).
samples/ ShaderFiddle.Web, ShaderViewer, mgcb.
tools/ native-binary restore scripts (restore.sh / restore.ps1).

Build & test

./tools/restore.sh                 # or .\tools\restore.ps1  (best-effort; non-fatal)
dotnet build ShadowDusk.slnx
dotnet test  ShadowDusk.slnx
  • Run only unit tests: dotnet test ShadowDusk.slnx --filter "Category!=Integration".
  • Run integration tests: dotnet test ShadowDusk.slnx --filter "Category=Integration" --settings ShadowDusk.runsettings.
  • The --settings ShadowDusk.runsettings flag applies a 5-minute TestSessionTimeout backstop (integration tests touch native DXC/SPIRV-Cross and a spawned CLI; cold antivirus scans can make them slow — add **/bin, **/obj, tools/, and the test %TEMP% to your AV exclusions during development).

Coding conventions

  • #nullable enable in every file; all public APIs nullable-annotated.
  • Prefer sealed classes unless inheritance is explicitly required.
  • async/await all the way down for child-process and native calls — never .Result / .Wait().
  • Errors use the Result<T, TError> discriminated union — no exception-as-control-flow. Compiler errors are Result<CompiledShader, ShaderError[]>.
  • Unit tests are pure (no disk, no process); integration tests carry [Trait("Category","Integration")]. No Thread.Sleep in tests; use CancellationToken with reasonable timeouts.

Doc-comments & this site

The API Reference is generated by DocFX from the XML doc-comments in the four library projects. When adding public API, write <summary>/<param>/<returns>. Note the build sets TreatWarningsAsErrors=true with a high warning level, so enable GenerateDocumentationFile per project carefully (and NoWarn CS1591 during a transition) to avoid turning missing-comment warnings into build errors. The site itself is built from docfx.json + the docfx/ content tree and deployed by .github/workflows/docs.yml.

Commit conventions

  • No Co-Authored-By trailers of any kind (no AI/tool attribution, and not the user's name either — authorship is implicit).
  • No "Generated with …" / tool-attribution lines in commit messages or PR bodies.

Backward compatibility

Stay on MonoGame 3.8.2.1105 / MGFX v10 for the existing outputs; v10 loads everywhere. New backends and formats must be additive opt-in targets, never changes to the existing OpenGL/DX11/v10 output.

Edit this page