<!--
{
  "documentType" : "article",
  "framework" : "Metal",
  "identifier" : "/documentation/Metal/shader-libraries",
  "metadataVersion" : "0.1.0",
  "role" : "collectionGroup",
  "title" : "Shader libraries"
}
-->

# Shader libraries

Manage and load your app’s Metal shaders.

## Discussion

A Metal library represents a collection of one or more shaders. Xcode creates a library from the shader source files in a project, a Metal intermediate representation (IR) file, or a binary archive file. You can also create IR files from Metal source code by running the Metal compiler in a command-line environment.

Apps create the default library instance by calling a Metal device’s [`makeDefaultLibrary()`](/documentation/Metal/MTLDevice/makeDefaultLibrary()) method. The default library contains all the shaders from a project’s shader source files, which Xcode compiles at build time. Apps create additional libraries by passing an IR file to an [`MTLDevice`](/documentation/Metal/MTLDevice) instance’s [`makeLibrary(URL:)`](/documentation/Metal/MTLDevice/makeLibrary(URL:)) method or one of its sibling methods. The device can also create a library directly from source code by passing it as a string to the [`makeLibrary(source:options:)`](/documentation/Metal/MTLDevice/makeLibrary(source:options:)) method. See [Shader library and archive creation](/documentation/Metal/shader-library-and-archive-creation) for more information.

You can apply a shader from a library to a pipeline state’s entry point, such as the [`computeFunction`](/documentation/Metal/MTLComputePipelineDescriptor/computeFunction) property for a compute pass. Start by retrieving an [`MTLFunction`](/documentation/Metal/MTLFunction) instance from a library, which is a reference to the library’s shader, by calling its [`makeFunction(name:)`](/documentation/Metal/MTLLibrary/makeFunction(name:)) method or a sibling method. Then set the function instance to the appropriate property of a pipeline descriptor. For example, an app can retrieve a vertex stage’s entry point shader from a library and assign it to the [`vertexFunction`](/documentation/Metal/MTLRenderPipelineDescriptor/vertexFunction) property of an [`MTLRenderPipelineDescriptor`](/documentation/Metal/MTLRenderPipelineDescriptor).

Dynamic libraries are a collection of other shaders, typically utility functions, that support the entry point shaders for a pipeline state. To create a dynamic library, pass an [`MTLLibrary`](/documentation/Metal/MTLLibrary) instance to a device’s [`makeDynamicLibrary(library:)`](/documentation/Metal/MTLDevice/makeDynamicLibrary(library:)) method, or pass a file URL to [`makeDynamicLibrary(url:)`](/documentation/Metal/MTLDevice/makeDynamicLibrary(url:)). Add a dynamic library to a pipeline state by including it in an array of a pipeline descriptor’s preloaded libraries property. For example, if a vertex shader calls a shader in a dynamic library, directly or indirectly, add that dynamic library to the [`vertexPreloadedLibraries`](/documentation/Metal/MTLRenderPipelineDescriptor/vertexPreloadedLibraries) property’s array. You can also build dynamic libraries with the Metal compiler in Terminal.

Binary archives are precompiled static libraries for specific GPU architectures that allow you to avoid the cost of runtime shader compilation. Because Metal automatically builds and caches shaders on the device running an app, use binary archives as part of your distributed app, or deliver them through content updates. See [Creating binary archives from device-built pipeline state objects](/documentation/Metal/creating-binary-archives-from-device-built-pipeline-state-objects) for more information on how to build and distribute binary archives for any device that supports Metal.

## Topics

### Shader compilation

Compile and manipulate Metal shader libraries from the command line.

[Metal libraries](/documentation/Metal/metal-libraries)

Compile and manage Metal libraries from the command line.

[Metal dynamic libraries](/documentation/Metal/metal-dynamic-libraries)

Create a single Metal library containing reusable code to reduce library size and avoid repeated shader compilation at runtime.

[Metal binary archives](/documentation/Metal/metal-binary-archives)

Distribute precompiled GPU-specific binaries as part of your app to avoid runtime compilation of Metal shaders.

[`MTL4Compiler`](/documentation/Metal/MTL4Compiler)

A abstraction for a pipeline state and shader function compiler.

[`MTL4CompilerDescriptor`](/documentation/Metal/MTL4CompilerDescriptor)

Groups together properties for creating a compiler context.

[`MTL4CompilerTask`](/documentation/Metal/MTL4CompilerTask)

A reference to an asynchronous compilation task that you initiate from a compiler instance.

[`MTL4CompilerTaskOptions`](/documentation/Metal/MTL4CompilerTaskOptions)

The configuration options that control the behavior of a compilation task for a Metal 4 compiler instance.

[`MTL4CompilerTaskStatus`](/documentation/Metal/MTL4CompilerTaskStatus)

Represents the status of a compiler task.

[`MTL4Archive`](/documentation/Metal/MTL4Archive)

A read-only container that stores pipeline states from a shader compiler.

[`MTL4BinaryFunction`](/documentation/Metal/MTL4BinaryFunction)

Represents a binary function.

[`MTL4BinaryFunctionDescriptor`](/documentation/Metal/MTL4BinaryFunctionDescriptor)

Base interface for other function-derived interfaces.

[`MTL4BinaryFunctionOptions`](/documentation/Metal/MTL4BinaryFunctionOptions)

Options for configuring the creation of binary functions.

[`MTL4PipelineStageDynamicLinkingDescriptor`](/documentation/Metal/MTL4PipelineStageDynamicLinkingDescriptor)

Groups together properties to drive the dynamic linking process of a pipeline stage.

### Pipeline compilation

[`MTL4BlendState`](/documentation/Metal/MTL4BlendState)

Enumeration for controlling the blend state of a pipeline state object.

[`MTL4FunctionDescriptor`](/documentation/Metal/MTL4FunctionDescriptor)

Base interface for describing a Metal 4 shader function.

[`MTL4IndirectCommandBufferSupportState`](/documentation/Metal/MTL4IndirectCommandBufferSupportState)

Enumeration for controlling support for [`MTLIndirectCommandBuffer`](/documentation/Metal/MTLIndirectCommandBuffer).

[`MTL4LibraryDescriptor`](/documentation/Metal/MTL4LibraryDescriptor)

Serves as the base descriptor for creating a Metal library.

[`MTL4LibraryFunctionDescriptor`](/documentation/Metal/MTL4LibraryFunctionDescriptor)

Describes a shader function from a Metal library.

[`MTL4LogicalToPhysicalColorAttachmentMappingState`](/documentation/Metal/MTL4LogicalToPhysicalColorAttachmentMappingState)

Enumerates possible behaviors of how a pipeline maps its logical outputs to its color attachments.

[`MTL4NewBinaryFunctionCompletionHandler`](/documentation/Metal/MTL4NewBinaryFunctionCompletionHandler)

Provides a signature for a callback block that Metal calls when the compiler finishes a build task for a binary function.

[`MTL4NewMachineLearningPipelineStateCompletionHandler`](/documentation/Metal/MTL4NewMachineLearningPipelineStateCompletionHandler)

Provides a signature for a callback block that Metal calls when the compiler finishes a build task for a machine learning pipeline state.

[`MTL4ShaderReflection`](/documentation/Metal/MTL4ShaderReflection)

Option mask for requesting reflection information at pipeline build time.

[`MTL4SpecializedFunctionDescriptor`](/documentation/Metal/MTL4SpecializedFunctionDescriptor)

Groups together properties to configure and create a specialized function by passing it to a factory method.

[`MTL4AlphaToCoverageState`](/documentation/Metal/MTL4AlphaToCoverageState)

Enumeration for controlling alpha-to-coverage state of a pipeline state object.

[`MTL4AlphaToOneState`](/documentation/Metal/MTL4AlphaToOneState)

Enumeration for controlling alpha-to-one state of a pipeline state object.

[`MTL4StaticLinkingDescriptor`](/documentation/Metal/MTL4StaticLinkingDescriptor)

Groups together properties to drive a static linking process.

[`MTL4StitchedFunctionDescriptor`](/documentation/Metal/MTL4StitchedFunctionDescriptor)

Groups together properties that describe a shader function suitable for stitching.

[`MTLFunctionReflection`](/documentation/Metal/MTLFunctionReflection)

Represents a reflection object containing information about a function in a Metal library.

[`MTLNewDynamicLibraryCompletionHandler`](/documentation/Metal/MTLNewDynamicLibraryCompletionHandler)

### Pipeline harvesting

[`MTL4PipelineDataSetSerializer`](/documentation/Metal/MTL4PipelineDataSetSerializer)

A fast-addition container for collecting data during pipeline state creation.

[`MTL4PipelineDataSetSerializerConfiguration`](/documentation/Metal/MTL4PipelineDataSetSerializerConfiguration)

Configuration options for pipeline dataset serializer objects.

[`MTL4PipelineDataSetSerializerDescriptor`](/documentation/Metal/MTL4PipelineDataSetSerializerDescriptor)

Groups together properties to create a pipeline data set serializer.

[`MTL4PipelineDescriptor`](/documentation/Metal/MTL4PipelineDescriptor)

Base type for descriptors you use for building pipeline state objects.

[`MTL4PipelineOptions`](/documentation/Metal/MTL4PipelineOptions)

Provides options controlling how to compile a pipeline state.

### Shader library management

[`MTLLibrary`](/documentation/Metal/MTLLibrary)

A collection of Metal shader functions.

[`MTLDynamicLibrary`](/documentation/Metal/MTLDynamicLibrary)

A dynamically linkable representation of compiled shader code for a specific Metal device object.

[`MTLBinaryArchive`](/documentation/Metal/MTLBinaryArchive)

A container for pipeline state descriptors and their associated compiled shader code.

[`MTLCompileOptions`](/documentation/Metal/MTLCompileOptions)

Compilation settings for a Metal shader library.

[`MTLLibraryType`](/documentation/Metal/MTLLibraryType)

A set of options for Metal library types.

[`MTLLanguageVersion`](/documentation/Metal/MTLLanguageVersion)

Metal shading language versions.

[`MTLCompileSymbolVisibility`](/documentation/Metal/MTLCompileSymbolVisibility)

[`MTLLibraryOptimizationLevel`](/documentation/Metal/MTLLibraryOptimizationLevel)

The optimization options for the Metal compiler.

### Shader functions

[`MTLFunctionDescriptor`](/documentation/Metal/MTLFunctionDescriptor)

A description of a function object to create.

[`MTLFunction`](/documentation/Metal/MTLFunction)

A interface that represents a public shader function in a Metal library.

[`MTLFunctionHandle`](/documentation/Metal/MTLFunctionHandle)

An object representing a function that you can add to a visible function table.

[`MTLVisibleFunctionTableDescriptor`](/documentation/Metal/MTLVisibleFunctionTableDescriptor)

A specification of how to create a visible function table.

[`MTLVisibleFunctionTable`](/documentation/Metal/MTLVisibleFunctionTable)

A table of shader functions visible to your app that you can pass into compute commands to customize the behavior of a shader.

[`MTLIntersectionFunctionDescriptor`](/documentation/Metal/MTLIntersectionFunctionDescriptor)

A description of an intersection function that performs an intersection test.

[`MTLIntersectionFunctionTableDescriptor`](/documentation/Metal/MTLIntersectionFunctionTableDescriptor)

A specification of how to create an intersection function table.

[`MTLIntersectionFunctionTable`](/documentation/Metal/MTLIntersectionFunctionTable)

A table of intersection functions that Metal calls to perform ray-tracing intersection tests.

### Stitched function libraries

[Customizing shaders using function pointers and stitching](/documentation/Metal/customizing-shaders-using-function-pointers-and-stitching)

Define custom shader behavior at runtime by creating functions from existing ones and preferentially linking to others in a dynamic library.

[`MTLStitchedLibraryDescriptor`](/documentation/Metal/MTLStitchedLibraryDescriptor)

A description of a new library of procedurally generated functions.

[`MTLFunctionStitchingGraph`](/documentation/Metal/MTLFunctionStitchingGraph)

A description of a new stitched function.

[`MTLFunctionStitchingInputNode`](/documentation/Metal/MTLFunctionStitchingInputNode)

A call graph node that describes an input to the call graph.

[`MTLFunctionStitchingFunctionNode`](/documentation/Metal/MTLFunctionStitchingFunctionNode)

A call graph node that describes a function call and its inputs.

[`MTLFunctionStitchingNode`](/documentation/Metal/MTLFunctionStitchingNode)

A protocol to identify call graph nodes.

[`MTLFunctionStitchingAttributeAlwaysInline`](/documentation/Metal/MTLFunctionStitchingAttributeAlwaysInline)

An attribute to specify that Metal needs to inline all of the function calls when generating the stitched function.

[`MTLFunctionStitchingAttribute`](/documentation/Metal/MTLFunctionStitchingAttribute)

A protocol to identify types that customize how the Metal compiler stitches a function together.

### Compile-time variant functions

[`MTLFunctionConstant`](/documentation/Metal/MTLFunctionConstant)

A constant that specializes the behavior of a shader.

[`MTLFunctionConstantValues`](/documentation/Metal/MTLFunctionConstantValues)

A set of constant values that specialize a graphics or compute GPU function.

### Introspection data

[`MTLComputePipelineReflection`](/documentation/Metal/MTLComputePipelineReflection)

Information about the arguments of a compute function.

[`MTLAutoreleasedComputePipelineReflection`](/documentation/Metal/MTLAutoreleasedComputePipelineReflection)

A convenience type alias for an autoreleased compute pipeline reflection object.

[`MTLRenderPipelineReflection`](/documentation/Metal/MTLRenderPipelineReflection)

Information about the arguments of a graphics function.

[`MTLAutoreleasedRenderPipelineReflection`](/documentation/Metal/MTLAutoreleasedRenderPipelineReflection)

A convenience type alias for an autoreleased pipeline reflection instance.

[`MTLBindingType`](/documentation/Metal/MTLBindingType)

[`MTLBinding`](/documentation/Metal/MTLBinding)

[`MTLBindingAccess`](/documentation/Metal/MTLBindingAccess)

[`MTLBufferBinding`](/documentation/Metal/MTLBufferBinding)

[`MTLTextureBinding`](/documentation/Metal/MTLTextureBinding)

[`MTLThreadgroupBinding`](/documentation/Metal/MTLThreadgroupBinding)

[`MTLObjectPayloadBinding`](/documentation/Metal/MTLObjectPayloadBinding)

### Function arguments

[`MTLAttribute`](/documentation/Metal/MTLAttribute)

An object that describes an attribute defined in the stage-in argument for a shader.

[`MTLVertexAttribute`](/documentation/Metal/MTLVertexAttribute)

An instance that represents an attribute of a vertex function.

[`MTLArgument`](/documentation/Metal/MTLArgument)

Information about an argument of a graphics or compute function.

[`MTLAutoreleasedArgument`](/documentation/Metal/MTLAutoreleasedArgument)

A convenience type alias for an autoreleased argument instance.

[`MTLArgumentType`](/documentation/Metal/MTLArgumentType)

The resource type for an argument of a function.

[`MTLArgumentAccess`](/documentation/Metal/MTLArgumentAccess)

Function access restrictions to argument data in the shading language code.

### Shader types

[`MTLType`](/documentation/Metal/MTLType)

A description of a data type.

[`MTLDataType`](/documentation/Metal/MTLDataType)

The parameter type options for GPU functions, such as shaders and compute kernels.

[`MTLArrayType`](/documentation/Metal/MTLArrayType)

A description of an array.

[`MTLStructType`](/documentation/Metal/MTLStructType)

A description of a structure.

[`MTLStructMember`](/documentation/Metal/MTLStructMember)

An instance that provides information about a field in a structure.

[`MTLPointerType`](/documentation/Metal/MTLPointerType)

A description of a pointer.

[`MTLTextureReferenceType`](/documentation/Metal/MTLTextureReferenceType)

A description of a texture.

### Shader logging

[`MTLLogStateDescriptor`](/documentation/Metal/MTLLogStateDescriptor)

An interface that represents a log state configuration.

[`MTLLogState`](/documentation/Metal/MTLLogState)

A container for shader log messages.

### Errors

[`MTLLibraryError`](/documentation/Metal/MTLLibraryError-swift.struct)

Metal errors related to libraries.

[`MTLLibraryError.Code`](/documentation/Metal/MTLLibraryError-swift.struct/Code)

Error codes for Metal library errors.

[`MTLLibraryErrorDomain`](/documentation/Metal/MTLLibraryErrorDomain)

The error domain for Metal libraries.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)