Compiling With Metal Shaderconverter

---
name: compiling-with-metal-shaderconverter
description: ALWAYS use when compiling DXIL/HLSL to metallib with Metal shader converter (commonly referred to as MSC) via the metal-shaderconverter CLI or libmetalirconverter (IRCompiler, IRObject, IRShaderReflection) at runtime. Covers offline/runtime DXIL compilation, root signatures, reflection output, ray tracing shaders, geometry/tessellation emulation compilation, framebuffer fetch in HLSL, programmable blending in HLSL, Metal_HLSL.inc, and compatibility flags. Do NOT trigger for binding compiled shaders to encoders — use integrating-metal-shaderconverter-shaders for that.
---

# Metal shader converter — CLI & Library

## Overview

Two modes: **CLI** (`metal-shaderconverter`) for offline/build-time compilation, **library** (`libmetalirconverter` C API) for runtime compilation. Both produce metallibs consumed by the Metal framework. Use the CLI for build pipelines and asset cooking; use the library when DXIL must be compiled at runtime (e.g., an engine that ships DXIL and compiles to metallib on first load).

For binding compiled shaders to Metal encoders at draw/dispatch time, see `integrating-metal-shaderconverter-shaders`.

## Decision Guide

| Scenario | Use |
|---|---|
| Build pipeline, asset cooking, offline shader cache | CLI |
| Compile DXIL to metallib at runtime | Library |
| Dynamic root signatures not known until runtime | Library |
| Generate reflection JSON for binding code | CLI (`--output-reflection-file`) |
| Runtime reflection after compilation | Library (`IRShaderReflection`) |

---