METAL-NT(1) Metal METAL-NT(1)

metal-nt - metal native translator

metal-nt [options] [filename]

metal-nt is a tool translating AIR virtual code to native code. The translation process is driven by the input file kind and an optional script, specified via the -N option. Each file kind has an associated script kind. Each script kind supports multiple formats. In particular, for those scripts backed by a FlatBuffer, both the JSON and binary representation of the FlatBuffer are valid script formats.

The translation of an assembly or object file produces a target specific assembly file, or a MachO MH_OBJECT file. AIR assembly/objects scripts can be used to customize the translation process. They are both backed by FlatBuffers. The file extensions of the FlatBuffer JSON representations are .aira-json and .airo-json. The file extensions of the FlatBuffer binary representations are .aira and .airo.

The translation of an executable MetalLib results in a MachO MH_GPU_EXECUTE file. Each qualified function in the MetalLib is translated independently. An AIR function script can be used to customize the translation process of a single qualified function. AIR functions scripts are backed by FlatBuffers. The file extension for the Flatbuffer JSON encoding is .airf-json. The file extension of the Flatbuffer binary encoding is .airf. If a function script is not specified, all the qualified functions in the MetalLib are translated. This still results in a single MachO being generated, containing the translation of all the qualified functions.

The translation of a MetalLib dynamic library produces a MachO MH_GPU_DYLIB. An AIR dynamic library script can be used to customize the translation process. Such script is backed by a Flatbuffer. The file extension of the JSON encoding is .aird-json. The file extension of the binary encoding is .aird.

A pipeline can be created by invoking metal-nt with an executable MetalLib and an AIR pipeline script. AIR pipeline scripts are backed by Flatbuffers. The Flatbuffer JSON encoding file extension is .airp-json. The Flatbuffer binary encoding file extension is .airp. The provided MetalLib must contains all the qualified functions referenced by the AIR pipeline script. The output of a pipeline translation is a MachO MH_GPU_EXECUTE.

Plugins implementing translation to binary code might provide support for builtin scripts. Such kind of scripts does not require any assembly, object, or MetalLib file input. The output of a builtin translation is a MachO MH_GPU_EXECUTE. The file extension and contents of builtin scripts are specific to each plugin. Refer to each plugin documentation for more information.

Metal pipelines scripts describe how to create a pipeline using a syntax that mirrors the one provided by the Metal.framework API. They are backed by Flatbuffers. The JSON encoding file extension is .mtlp-json. The binary encoding file extension is .mtlp.

Metal pipelines scripts are way more expressive than AIR pipeline scripts. Qualified functions of a specific MetalLib can be directly referenced from a Metal pipelines script, removing the need of providing a MetalLib argument to metal-nt. They also allow to specialize qualified functions and to stitch them together prior of pipeline creation.

The output of a Metal pipelines script translation is a MachO of type MH_GPU_EXECUTE that contains the translation of all the pipelines described by the Metal pipelines script.

Display all the architectures that can be targeted.

Display all the implementations that can be targeted by the specified architecture.

Display whether the specified target is supported. <platform> is one of the following strings:
  • ios
  • ios-simulator
  • mac-catalyst
  • tvos
  • tvos-simulator
  • watchos
  • watchos-simulator
  • xros
  • xros-simulator
  • macos

The format of <min_version> is a version number such as 16.0 or 16.2.


Display all the architectures that can be targeted for the specified target. <platform> and <min_version> follow the same rules documented for the -available flag.

Select the architecture to target.

Set the platform name, minimum deployment target version, and the SDK version the output is going to be built against. <platform> is one of the following strings:
  • ios
  • ios-simulator
  • mac-catalyst
  • tvos
  • tvos-simulator
  • watchos
  • watchos-simulator
  • xros
  • xros-simulator
  • macos

Specifying a newer min or SDK version allows to assume features of that OS or SDK in the output file. The format of <min_version> and <sdk_version> is a version number such as 16.0 or 16.2.


Load a plugin supporting translation for a set of architectures or providing legalization passes.

Prints information about all the loaded plugins.

Translate an assembly file.

Override the configuration file path.

Set a translation script.

Specify the output file name. Defaults to "-" -- i.e. standard output.

Set the number of threads to be used in parallel translation. Default to the number of CPUs.

Add <dirname> to the MetalLib search path. This allows to use relative paths when referencing to a MetalLib in Metal pipelines scripts.

Set the system root.

Set the runtime directory.

Stop translation after performing <stage>. Valid values are:
  • metal-script stop after Metal to AIR script translation
  • specialize stop after function constant specialization
  • stitch stop after function stitching
  • translate stop after AIR to native code translation
  • package stop after packaging of multiple native codes


Save all the temporaries files in the current working directory.

Forward <value> to the LLVM command line parser.

Forward <value> to the plugins command line parser.

Do not perform any optimization in the translation process.

Embed generated libraries that are not used by targets.

Display available options.

${TOOLCHAIN}/lib/air-nt/config.yaml Default configuration file

To build Metal pipelines:

$ metal-nt -arch amdgpu_gfx600 foobar-air64.metallib -N foobar.mtlp-json -o foobar.metallib


To build a Metal dynamic library:

$ metal-nt -arch amdgpu_gfx600 libfoo-air64.metallib -o libfoo.metallib


To build Metal pipelines without directly referencing any MetalLib:

$ metal-nt -arch amdgpu_gfx600 -L my-libs-dir -N foobar.mtlp-json


To report bugs, please visit <https://developer.apple.com/bug-reporting/>.

metal-arch(1) metal-pipelines-script(5)

Metal Shading Language Specification: <https://developer.apple.com/metal/Metal-Shading-Language-Specification.pdf>

2014-2024, The Metal Team

July 10, 2024 32023