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:
- Targets
Selection
- 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.
- Build
Planning
- 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.
- Translation
- 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.
- Storage
Optimization
- 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.
- -help
- Display available options.
- -platform_version
<platform> <min_version> <sdk_version>
- 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
- 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.
- -arch
<arch>
- 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.
- -gpu-family
<family>
- 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.
- -L <dirname>
- Add <dirname> to the MetalLibs search path. Search path is
empty by default.
- SDKROOT
- 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-2023, The Metal Team