METAL-TT(1) Metal METAL-TT(1)

metal-tt - metal translation tool

metal-tt [options] filename ...

metal-tt is a tool transforming AIR virtual code to native code. It encompass architectures selection, build planning, translation, and storage optimization. While MetalTT is highly integrated, it is important to understand the stages of translation. These stages are:

The architectures set is made of all the architectures supported by the toolchain; metal-config is used to retrieve such information. That can be overridden by explicitly specifying the architectures to target using the -arch option. Further refinement can be performed using the -gpu-family option.
Inputs falls into two categories: backend inputs and scripts. Backend inputs includes assembly and object files. Depending on the number of backend inputs and script, different build plans are produced. When only one backend input is provided, a plan to translate that input against all the provided scripts -- if any -- is produced. When only one script is provided, a plan to translate the script against all the backed inputs -- if any -- is produced. The case where there are multiple backend inputs and scripts is not supported.
The translation stage takes care of translating a <backend input, script> pair to native code. This stage is performed for each selected architecture. Moreover, the build planning stage might decide to perform multiple translation, such as in the case where a single backend input needs to be translated against multiple scripts. Each individual translation is performed via an architecture specific translator.
This stage put together all the outputs of the translation step into one single file. The goal is to factorize common data structures that might be encoded multiple times into each output of the translation stage. This stage is performed via :program:metal-pack. When multiple architectures have been selected, the output is expected to be an universal file.

Display available options.

This is set to indicate the platform, oldest supported version of that platform that output is to be used on, and the SDK that the output was 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.


Add <arch> to the list of architectures to build for. Can be specified multiple times. Default behavior is to build to all the architectures supported by the toolchain.

Set target triple we should build for.

When building for iOS, specify the minimum version supported by your application.

When building for iOS Simulator, specify the minimum version supported by your application.

When building for MacCatalyst, specify the minimum version supported by your application.

When building for tvOS, specify the minimum version supported by your application.

When building for tvOS Simulator, specify the minimum version supported by your application.

When building for watchOS, specify the minimum version supported by your application.

When building for watchOS Simulator, specify the minimum version supported by your application.

When building for visionOS, specify the minimum version supported by your application.

When building for visionOS Simulator, specify the minimum version supported by your application.

When building for macOS, specify the minimum version supported by your application.

Add <family> to the list of viable GPU families. Only architectures that supports at least one of the viable families are targeted. By default all the families are viable.

Supported families are apple[1-8], mac2, common[1-3], metal3.


Set the system root.

Write output to <filename>.

Add <dirname> to the MetalLibs search path. Search path is empty by default.

Optimize storage of MetalLibs, enabled by default.

Optimize storage of descriptors, enabled by default.

Optimize storage of reflection information, enabled by default.

Cache intermediate products on a disk cache.

Do not cache intermediate products on a disk cache.

Embed generated libraries that are not used by targets, disabled by default.

Do not embed generated libraries that are not used by targets.

Echo all spawned commands.

Print time taken to run each spawned command.

If -sysroot is unspecified, the system root is read from this environment variable.

To translate a MetalLib for all architectures supported in the toolchain:

$ metal-tt foo-air64.metallib -o foo.metallib


While providing a scripts for the native translator stage:

$ metal-tt foo-air64.metallib foo.mtlp-json -o foo.metallib


Multiple backend inputs case:

$ metal-tt foo-air64.metallib bar-air64.metallib foobar.mtlp-json -o foobar.metallib


Will result in independently translating the <foo-air64.metallib, foobar.mtlp-json> and <bar-air64.metallib, foobar.mtlp-json> pairs, followed by an invocation of metal-pack to combine the two translation into foobar.metallib.

Dual case with multiple scripts:

$ metal-tt foobar-air64.metallib foo.mtlp-json bar.mtlp-json -o foobar.metallib


Will induce independent translation of the <foobar-air64.metallib, foo.mtlp-json> and <foobar-air64.metallib, bar.mtlp-json> pairs.

To force a specific OS version:

$ metal-tt -ios-version-min 16.2 foo-air64.metallib -o foo.metallib


Will target iOS 16.2 for all architectures found in the toolchain.

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

metal-arch(1), metal-nt(1), metal-pack(1), metal-pipelines-script(5)

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

2014-2024, The Metal Team

April 30, 2024 32023