Functions and Libraries

Compiling Metal shading language source code is one of the most expensive stages in the lifetime of a Metal app. Metal minimizes this cost by allowing you to compile graphics and compute functions at build time, then load them as a library at runtime.

Build Your Library at Build Time

When you build your app, Xcode automatically compiles your .metal source files and builds them into a single default library. To obtain the resulting MTLLibrary object, call the newDefaultLibrary method once during your initial Metal setup.

Building your library at runtime incurs a significant performance cost. Do so only if your graphics and compute functions are created dynamically at runtime. In all other situations, always build your library at build time.

Important

The #include directive is not supported at runtime for user files.

Group Your Functions into a Single Library

Using Xcode to build a single default library is the fastest and most efficient build option. If you must use Metal’s command line utilities or runtime methods to build your library, coalesce your Metal shading language source code and group all your functions into a single library. Avoid creating multiple libraries, if possible.