.ig Copyright (c) 2019 Apple Inc. All Rights Reserved. .. .Dd December 31, 2018 .Os "Darwin" .Dt VTOOL 1 .Sh NAME .Nm vtool .Nd Mach-O version number utility .\" SYNOPSIS .Sh SYNOPSIS .Nm .Op Fl arch Aq arch .Ar ... .Aq Ar show\ command .Ar ... .Ar file .Nm .Op Fl arch Aq arch .Ar ... .Aq Ar set\ command .Ar ... .Op Fl replace .Fl output Ar out_file .Ar file .Nm .Op Fl arch Aq arch .Ar ... .Aq Ar remove\ command .Ar ... .Fl output Ar out_file .Ar file .Nm .Fl help .\" DESCRIPTION .Sh DESCRIPTION The .Nm utility displays and edits build and source version numbers embedded in the .Xr Mach-O 5 file format. These version numbers are stored within the Mach-O load commands, as described in the .Aq Pa mach-o/loader.h header file and in the .Sx VERSION LOAD COMMANDS section below. When editing files, a new .Ar out_file must be specified using the .Fl output flag; .Nm will only ever write to a single output file, and input files are never modified in place. .Pp .Nm operates in one of three functional modes (in addition to a .Em help mode) depending on the type of arguments specified on the command line: .Em show , .Em set , and .Em remove . All of these modes operate on .Dq universal (multi-architecture) files as well as ordinary Mach-O files. The .Fl arch flag limits operation to one or more architectures within a universal file. .Pp .Bl -tag -width "XXkeepParent" .It Em Show Show options include .Fl show , .Fl show-build , .Fl show-source , and .Fl show-space . Only one of these commands may be specified. The version information will be printed in a manner similar to .Xr otool 1 or .Xr otool-classic 1 . .It Em Set Set options include .Fl set-build-tool , .Fl set-build-version , .Fl set-source-version , and .Fl set-version-min . Any number of these commands can be combined in a single .Nm invocation. You can use these set commands to add a new build version to a Mach-O or to replace an existing version for a specific platform. When used with the .Fl replace option, all existing build versions will be entirely replaced by the new build versions specified on the command line. .It Em Remove Remove options include .Fl remove-build-tool , .Fl remove-build-version , and .Fl remove-source-version . Any number of these commands can be combined in a single .Nm invocation. .El .Pp Currently .Nm only operates on final linked binaries, such as executable files, dynamic libraries, and bundles. Because the executable code in Mach-O final linked binaries cannot be moved or resized, and because the load commands reside between the mach header and the executable code, there is only a limited amount of space available for .Nm to save changes. Set operations that add or resize load commands may fail if there isn't enough space in the Mach-O file availble to hold the new load commands. .\" OPTIONS .Sh OPTIONS .Bl -tag -width "XXkeepParent" .It Fl arch Aq arch Specifies the architecture, .Aq arch , for .Nm to operate on when the file is a universal (multi-architecture) file. See .Xr arch 3 for the current list of architectures. More than one architecture can be specified, and by default .Nm will operate on all architectures in a universal file. .It Fl h , help Print full usage. .It Fl o , output Ar out_file Commands that create new files write to the .Ar out_file file specified by the .Fl output flag. This option is required for all set and remove commands. .It Fl r , replace When used with .Fl set-build-version or .Fl set-version-min the .Fl replace option instructs .Nm to discard all of the existing build versions from the input file. Use this to change a file's platform in a single call to .Nm . When used with the .Fl set-build-tool command, .Nm will discard all of the existing tool versions from the specified platform's build version. This option has no effect on source versions. .It Fl remove-build-tool Ar platform tool Removes .Ar tool from the .Ar platform build version. A build version for the specified platform must exist in the input file and that build version must be an .Dv LC_BUILD_VERSION . Must be used with .Fl output . See .Sx VERSION LOAD COMMANDS for more information on platform and tool values. .It Fl remove-build-version Ar platform Removes the build version for the specified .Ar platform . Must be used with .Fl output . See .Sx VERSION LOAD COMMANDS for more information on platform values. .It Fl remove-source-version Removes the source version from the Mach-O file. Must be used with .Fl output . .It Fl set-build-tool Ar platform tool version Updates the build version load command for .Ar platform to include the specified .Ar tool , adding a new tool entry if necessary. The build version must be an .Em LC_BUILD_VERSION load command which either already existss within the input file or is newly specified on the command line. The .Ar version field takes the format X.Y.Z. Must be used with .Fl output . See .Sx VERSION LOAD COMMANDS for more information on platform and tool values. .It Fl set-build-version Ar platform minos sdk Op Fl tool Ar tool version Create or update the .Em LC_BUILD_VERSION load command for .Ar platform to include the specified .Ar minos and .Ar sdk version numbers, and zero or more optional tools. The .Ar minos , sdk , and tool .Ar version all take the format X.Y.Z. Must be used with .Fl output . See .Sx VERSION LOAD COMMANDS for more information on platform and tool values. .It Fl set-source-version Ar version Create or update the source version load command. .Ar version takes the format A.B.C.D.E. Must be used with .Fl output . .It Fl set-version-min Ar platform minos sdk Create or update an .Em LC_VERSION_MIN_* load command for .Ar platform . This option is included to support older operating systems, and generally one should favor .Fl set-build-version instead. Note that version min load commands do not support tool versions, and not all platforms can be expressed using version min load commands. Must be used with .Fl output . .It Fl show , show-all Display the build and source versions within the specified file. This option cannot be combined with other commands. .It Fl show-build Display the build versions within the specified file. This option cannot be combined with other commands. .It Fl show-source Display the source version within the specified file. This option cannot be combined with other commands. .It Fl show-space Show the space in the file consumed by the mach header and the existing load commands, and measure the amount of additional space available for adding new load commands. .It Fl A single dash instructs .Nm to stop parsing arguments. This is useful for operating on files whose names would otherwise be interpreted as an option or flag. .El .\" VERSION LOAD COMMANDS .Sh VERSION LOAD COMMANDS Modern Mach-O files can contain multiple build versions, one for each unqiue .Em platform represented in the file. A platform is a loosely-defined concept within Mach-O, most often used to identify different Darwin operating systems, such as .Em macOS and .Em iOS . Platforms and tools can be specified either by name (e.g., .Qq macos or .Qq clang ) or by number (e.g., .Qq 1 ) . Common platform and tool constants are defined in .Aq Pa mach-o/loader.h and .Nm will display platform and tool names when invoked with .Fl help . .Pp Modern Mach-O files store build information in one or more .Dv LC_BUILD_VERSION load commands. .Dv LC_BUILD_VERSION supports arbitrary platforms and can include version information about the tools used to build the Mach-O file. Older Mach-O files use a .Dq version min load command, such as .Dv LC_VERSION_MIN_MACOSX . While version min commands are appropriate when deploying Mach-O files on older operating systems, be aware that they do not support tool versions, and version min load commands do not exist for all possible platforms. In some cases .Dv LC_BUILD_VERSION and .Dv LC_VERSION_MIN_* load commands can appear in a single Mach-O file, but many restrictions apply, and .Nm may not enforce these restrictions. .Nm will prevent you from writing more than one build version load command for the same platform. .Pp Source versions are stored in a single .Dv LC_SOURCE_VERSION load command. .Pp When writing new load commands, .Nm will attempt to preserve the order of the load commands as they appear on the command line. No attempt is made to preserve positions relative to other existing load commands. Editing an existing load command may have the side effect of moving the load command to the end of the load command list. .\" SEE ALSO .Sh SEE ALSO .Xr ld 1 , .Xr lipo 1 , .Xr otool-classic 1 , .Xr arch 3 , .Xr Mach-O 5 . .\" HISTORY .Sh HISTORY .Em LC_BUILD_VERSION first appeared in macOS 10.13 in 2017 for use with the bridgeOS platform. .Pp .Em LC_BUILD_VERSION became the default build version load command for the macOS, iOS, tvOS, and watchOS platforms in 2018 with macOS 10.14, iOS 12.0, and friends. The list of platforms also grew to include iOSSimulator, tvOSSimulator, and watchOSSimulator. .Pp .Nm first appeared in macOS 10.15 and iOS 13.0 in 2019. .\" BUGS .Sh BUGS .Nm will write load commands in a different order than .Xr ld 1 . .Pp Currently .Nm does not work with object files or archives.