Building a Library with Metal's Command-Line Tools

Manually compiling Metal Shading Language source code and building a Metal library without using Xcode involves the following process:

1. Use the metal tool to compile each .metal file into a single .air file, which stores an intermediate representation of Metal Shading Language source code.

2. Optionally, use the metal-ar tool to archive several .air files together into a single .metalar file. (The metal-ar tool is similar to the UNIX ar tool.)

3. Use the metallib tool to build .air or .metalar files into a single .metallib file, which stores the Metal library.

The following code shows the minimum number of commands that you need to compile and build a single .metal file into a single .metallib file. You can run these commands in the Terminal app and use the -help command to display the available options for each Metal tool. This example uses the macosx SDK, but you can use the iphoneos or appletvos SDK instead.

xcrun -sdk macosx metal -c MyLibrary.metal -o MyLibrary.air
xcrun -sdk macosx metallib MyLibrary.air -o MyLibrary.metallib

After you've built a library with Metal's command-line tools, add the resulting .metallib file to your Xcode project. Then, at runtime, call the makeLibrary(filepath:) method to retrieve and access your library as a MTLLibrary object.

guard let libraryFile = Bundle.main.path(forResource: "MyLibrary", ofType: "metallib") else { return }
do {
    let myLibrary = try device.makeLibrary(filepath: libraryFile)
} catch let error {
    print("Library error: \(error.localizedDescription)")
}