.\" Man page generated from reStructuredText. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "METAL-TT" "1" "Aug 02, 2023" "32023" "Metal" .SH NAME metal-tt \- metal translation tool .SH SYNOPSIS .sp \fBmetal\-tt\fP [\fIoptions\fP] \fIfilename ...\fP .SH DESCRIPTION .sp \fBmetal\-tt\fP 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: .INDENT 0.0 .TP .B Targets Selection The architectures set is made of all the architectures supported by the toolchain; \fBmetal\-config\fP is used to retrieve such information. That can be overridden by explicitly specifying the architectures to target using the \fI\%\-arch\fP option. Further refinement can be performed using the \fI\%\-gpu\-family\fP option. .TP .B 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. .TP .B Translation The translation stage takes care of translating a \fI\fP 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. .TP .B 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 \fI:program:metal\-pack\fP\&. When multiple architectures have been selected, the output is expected to be an universal file. .UNINDENT .SH OPTIONS .INDENT 0.0 .TP .B \-help Display available options. .UNINDENT .INDENT 0.0 .TP .B \-platform_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. \fI\fP is one of the following strings: .INDENT 7.0 .IP \(bu 2 ios .IP \(bu 2 ios\-simulator .IP \(bu 2 mac\-catalyst .IP \(bu 2 tvos .IP \(bu 2 tvos\-simulator .IP \(bu 2 watchos .IP \(bu 2 watchos\-simulator .IP \(bu 2 macos .UNINDENT .sp Specifying a newer min or SDK version allows to assume features of that OS or SDK in the output file. The format of \fI\fP and \fI\fP is a version number such as 16.0 or 16.2. .UNINDENT .INDENT 0.0 .TP .B \-arch Add \fI\fP 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. .UNINDENT .INDENT 0.0 .TP .B \-target Set target triple we should build for. .UNINDENT .INDENT 0.0 .TP .B \-ios\-version\-min When building for iOS, specify the minimum version supported by your application. .UNINDENT .INDENT 0.0 .TP .B \-ios\-simulator\-version\-min When building for iOS Simulator, specify the minimum version supported by your application. .UNINDENT .INDENT 0.0 .TP .B \-maccatalyst\-version\-min When building for MacCatalyst, specify the minimum version supported by your application. .UNINDENT .INDENT 0.0 .TP .B \-tvos\-version\-min When building for tvOS, specify the minimum version supported by your application. .UNINDENT .INDENT 0.0 .TP .B \-tvos\-simulator\-version\-min When building for tvOS Simulator, specify the minimum version supported by your application. .UNINDENT .INDENT 0.0 .TP .B \-watchos\-version\-min When building for watchOS, specify the minimum version supported by your application. .UNINDENT .INDENT 0.0 .TP .B \-watchos\-simulator\-version\-min When building for watchOS Simulator, specify the minimum version supported by your application. .UNINDENT .INDENT 0.0 .TP .B \-macos\-version\-min When building for macOS, specify the minimum version supported by your application. .UNINDENT .INDENT 0.0 .TP .B \-gpu\-family Add \fI\fP 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. .sp Supported families are \fIapple[1\-8]\fP, \fImac2\fP, \fIcommon[1\-3]\fP, \fImetal3\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-sysroot Set the system root. .UNINDENT .INDENT 0.0 .TP .B \-o Write output to \fI\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-L Add \fI\fP to the MetalLibs search path. Search path is empty by default. .UNINDENT .INDENT 0.0 .TP .B \-pack\-metallibs Optimize storage of MetalLibs, enabled by default. .UNINDENT .INDENT 0.0 .TP .B \-pack\-descriptors Optimize storage of descriptors, enabled by default. .UNINDENT .INDENT 0.0 .TP .B \-pack\-reflections Optimize storage of reflection information, enabled by default. .UNINDENT .INDENT 0.0 .TP .B \-verbose Echo all spawned commands. .UNINDENT .INDENT 0.0 .TP .B \-time\-report Print time taken to run each spawned command. .UNINDENT .SH ENVIRONMENT .INDENT 0.0 .TP .B SDKROOT If \fI\%\-sysroot\fP is unspecified, the system root is read from this environment variable. .UNINDENT .SH EXAMPLES .sp To translate a MetalLib for all architectures supported in the toolchain: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ metal\-tt foo\-air64.metallib \-o foo.metallib .ft P .fi .UNINDENT .UNINDENT .sp While providing a scripts for the native translator stage: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ metal\-tt foo\-air64.metallib foo.mtlp\-json \-o foo.metallib .ft P .fi .UNINDENT .UNINDENT .sp Multiple backend inputs case: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ metal\-tt foo\-air64.metallib bar\-air64.metallib foobar.mtlp\-json \-o foobar.metallib .ft P .fi .UNINDENT .UNINDENT .sp Will result in independently translating the \fI\fP and \fI\fP pairs, followed by an invocation of \fBmetal\-pack\fP to combine the two translation into \fIfoobar.metallib\fP\&. .sp Dual case with multiple scripts: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ metal\-tt foobar\-air64.metallib foo.mtlp\-json bar.mtlp\-json \-o foobar.metallib .ft P .fi .UNINDENT .UNINDENT .sp Will induce independent translation of the \fI\fP and \fI\fP pairs. .sp To force a specific OS version: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ metal\-tt \-ios\-version\-min 16.2 foo\-air64.metallib \-o foo.metallib .ft P .fi .UNINDENT .UNINDENT .sp Will target iOS 16.2 for all architectures found in the toolchain. .SH BUGS .sp To report bugs, please visit <\fI\%https://developer.apple.com/bug\-reporting/\fP>. .SH SEE ALSO .sp \fBmetal\-arch(1)\fP, \fBmetal\-nt(1)\fP, \fBmetal\-pack(1)\fP, \fBmetal\-pipelines\-script(5)\fP .SH INTERNET RESOURCES .nf Metal Shading Language Specification: <\fI\%https://developer.apple.com/metal/Metal\-Shading\-Language\-Specification.pdf\fP> Metal Feature Set Tables: <\fI\%https://developer.apple.com/metal/Metal\-Feature\-Set\-Tables.pdf\fP> .fi .sp .SH COPYRIGHT 2014-2023, The Metal Team .\" Generated by docutils manpage writer. .