Generating and loading a Metal library symbol file
Debug your Metal shaders from your production apps by creating companion symbol files at compile time and loading them at debug time.
Overview
With Xcode 13 or later, you can generate a separate symbol file for each Metal library built for a project. Each symbol file is a companion file that stores useful debugging information for the Metal library it represents. By separating each Metal library from its symbols, you can:
Build and deploy a Metal library without source code — a requirement for apps on the App Store.
Debug that same Metal library at a later time by loading its companion symbol file in Xcode.
Avoid building each library twice — once for release and then again for debugging.
See Debugging the shaders within a draw command or compute dispatch to learn how to debug your Metal shaders.
Generate a symbol file with a single command
Generate a Metal library’s symbol file in a single command by running the Metal compiler with the -frecord-sources=flat option.
% xcrun -sdk macosx metal -frecord-sources=flat Shadow.metal PointLights.metal DirectionalLight.metalThe -frecord-sources=flat option, which replaces the deprecated -MO=<value> option, tells the Metal compiler to create two files:
default.metallib, the compiled Metal librarydefault.metallibsym, the library’s companion symbol file
Generate a symbol file with multiple commands
You can also generate a Metal library’s symbol file with multiple commands, which may be more appropriate for your workflow than the single-command technique. For those scenarios, you can generate each Metal library and its companion symbol file by following these steps:
Compile each Metal source file to a Metal IR (intermediate representation) file.
Generate a Metal library with the source by linking its IR files.
Separate the library’s source and save it as a companion symbol file.
First, compile each Metal source file to a Metal IR file by passing the -c option to the compiler.
% xcrun -sdk macosx metal -c -frecord-sources Shadow.metal
% xcrun -sdk macosx metal -c -frecord-sources PointLights.metal
% xcrun -sdk macosx metal -c -frecord-sources DirectionalLight.metalThe -frecord-sources option tells the Metal compiler to embed the symbols in the IR output file for that command. However, this command doesn’t create a separate symbols file at this time, which is why the -frecord-sources option doesn’t include the =flat suffix.
Next, generate a Metal library by linking the IR files.
% xcrun -sdk macosx metal -frecord-sources -o LightsAndShadow.metallib Shadow.air PointLights.air DirectionalLight.airSeparate the sources from the library and create a companion symbol file by running the metal-dsymutil command.
% xcrun -sdk macosx metal-dsymutil -flat -remove-source LightsAndShadow.metallibThe -remove-source option modifies the Metal library file by removing its embedded source information. At the same time, the command’s -flat option saves that source and other symbol information to a symbol file. After the command finishes execution, the directory contains both the modified Metal library and its new companion symbol file:
LightsAndShadow.metallibLightsAndShadow.metallibsym
Load a symbol file in Xcode
As you debug a shader, Xcode automatically presents a prompt when it doesn’t have access to a shader library’s source code.
[Image]
Click the Import Sources button and select the shader’s companion symbol file.
[Image]
Add your shader library’s companion symbol file by clicking the Add button (+) and locating the file. Select a directory to tell Xcode to find all companion symbol files that match any Metal libraries in the current Metal debugging capture. The dialog reflects each library’s symbol file in a list as you add them.
[Image]
Click Done when you finish adding your companion symbol files. Xcode imports the shader source and profiling information from each companion symbol file for the Metal library it represents.