Building a shader library by precompiling source files

Create a shader library that you can add to an Xcode project with the Metal compiler tools in a command-line environment.

Overview

Manually compile your Metal Shading Language (MSL) source files into a Metal shader library outside of an Xcode project with the Metal command-line tools. The metal compiler tool converts each shader source file into an intermediate representation file. The metal and metal-ar tools then compile intermediate representation files into a library and a binary archive, respectively.

[Image]

You can create a library from one or more intermediate representation files, one or more archive files, or a combination of both.

Compile a shader source file into a library

The simplest way to compile and build a single MSL source file into a library file is with two commands. The first command invokes the metal compiler tool, which compiles the source file into an intermediate representation file.

% xcrun -sdk macosx metal -o Shadow.ir  -c Shadow.metal
% xcrun -sdk macosx metal -o PointLights.ir  -c PointLights.metal
% xcrun -sdk macosx metal -o DirectionalLight.ir  -c DirectionalLight.metal

The -o option indicates the output file name and the -c option tells the tool to preprocess, compile, and assemble the source file.

Optionally, you can combine several intermediate representation files into a single Metal archive with the metal-ar tool.

% xcrun -sdk macosx metal-ar -q Lights.metalar DirectionalLight.ir PointLights.ir

The -q option tells the tool to quickly append to its argument, which creates a new archive file if it doesn’t already exist.

Build a Metal library from one or more intermediate representation files, one or more archive files, or a combination of both with the metal tool.

% xcrun -sdk macosx metal -o LightsAndShadow.metallib Lights.metalar Shadow.ir

The command produces a Metal library that your app can load at runtime. One way to do this is by adding it to your project’s build targets in Xcode.

Retrieve and load a library

At runtime, you can access a library by creating an MTLLibrary instance with the makeLibrary(URL:) method.