METAL-LIBTOOL(1) Metal METAL-LIBTOOL(1)

metal-libtool - create metal libraries

metal-libtool -static -o output [options] filename ...

metal-libtool -dynamic -o output [options] filename ...

metal-libtool -lowering -o output [options] filename ...

The metal-libtool command takes the specified input object files and creates a library for use with the link editor, metal-lld. The library name is specified by output (the argument of the -o flag). The input object files may be in any correct format that contains object files (universal files, archives, object files). metal-libtool will not put any non-object input file into the output library.

metal-libtool can create statically linked libraries, with -static, dynamically linked shared libraries, with -dynamic, or lowering libraries, with -lowering.

Statically linked libraries are ar format files. To build a statically linked library, metal-libtool runs the link editor, metal-lld, with -create-static-library once for each architecture present in the input objects and then metal-lipo to create a universal file if needed.

The archive member name for a table of contents is either "__.SYMDEF" or "__.SYMDEF SORTED" for archives with 32-bit file offsets. The latter being used when when table of contents is sorted. The table of contents archive member name for archives with 64-bit file offsets is either "__.SYMDEF_64" or "__.SYMDEF_64 SORTED".

Dynamically linked libraries, unlike statically linked libraries, are MetalLib format files and not ar format files. Dynamically linked libraries have two restrictions: No symbol may be defined in more than one object file and no common symbol can be used. To build a dynamically linked library, metal-libtool runs the link editor, metal-lld, with -create-shared-library once for each architecture present in the input objects and then metal-lipo to create a universal file if needed.

Lowering libraries are statically linked libraries where each member contains only one symbol with external linkage. To build a lowering library, metal-libtool runs the link editor, metal-lld, with -create-lowering-library once for each architecture present in the input objects and then metal-lipo to create a universal file if needed.

Display available options.

Produce a statically linked library from the input files. This is the default.

Produce a dynamically linked shared library from the input files.

Produce a statically linked lowering library from the input files.

Produce a library for the specific arch.

Alias for -arch_only.

Specifies output filename.

Echo all spawned commands.

Specify the minimum iOS version to build for.

Specify the minimum iOS Simulator version to build for.

Specify the minimum Mac Catalyst version to build for.

Specify the minimum tvOS version to build for.

Specify the minimum tvOS Simulator version to build for.

Specify the minimum watchOS version to build for.

Specify the minimum watchOS Simulator version to build for.

Specify the minimum visionOS version to build for.

Specify the minimum visonOS Simulator version to build for.

Specify the minimum macOS version to build for.

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 name> is one of the following strings:
  • ios
  • ios-simulator
  • mac-catalyst
  • tvos
  • tvos-simulator
  • watchos
  • watchos-simulator
  • xros
  • xros-simulator
  • macos



Specifying a newer <os version> or <sdk version> enables the link editor to assume features of that OS or SDK in the output file. The format of <os version> and <sdk version> is a version number such as 10.13 or 10.14.


Link with library <name>.

Add <dirname> to the libraries search path.

Link with framework <name>.

Add <dirname> to the frameworks search path.

Specify a linker export file.

Set dynamic library install name to <name>.

Only search libraries on directories specified on the command line.

Set the system root.

Save inputs into the final output, mainly for recompilation purposes.

Do not save inputs into the final output.

To create a static library:

$ metal-libtool -create-static-library foo.air bar.air -o libfoobar.a


To create a dynamic library:

$ metal-libtool -create-dynamic-library foo.air bar.air -install_name libfoobar.metallib -o libfoobar.metallib


To link only one architecture:

$ metal-libtool -create-static-library -arch_only air64_v18 foo-air64_v16.air foo-air64_v18.air foo-air64_v111.air -o libfoo.a


The libfoo.a output is a air64_v18 thin archive. It contains two members; foo-air64_v18.air is copied verbatim, while foo-air64_v16.air is upgraded to air64_v18 before putting it into the archive. foo-air64_v111 is ignored, as there is no upgrade path from there to air64_v18.

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

metal-arch(1) metal-lld(1)

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

2014-2024, The Metal Team

July 10, 2024 32023