productbuild(1) | General Commands Manual | productbuild(1) |
productbuild
—
Build a product archive for the macOS Installer or the Mac
App Store.
productbuild |
[--product requirements-plist]
{--component component-path
[install-path]}
product-output-path |
productbuild |
{--content content-path}
product-output-path |
productbuild |
[--product requirements-plist]
{--root root-path
install-path}
product-output-path |
productbuild |
[options] --distribution
dist-path [--package-path
search-path]
product-output-path |
productbuild |
--synthesize [--product
requirements-plist]
{--package pkg-path}
distribution-output-path |
A product archive is a flat file with a
.pkg extension. productbuild
creates a deployable product archive, which can be used with the OS X
Installer, or submitted to the Mac App Store. It has 5 different modes, as
shown in the SYNOPSIS above:
--component
option. You can specify additional requirements using a
PRE-INSTALL
REQUIREMENTS PROPERTY LIST. When you specify a bundle,
productbuild
automatically creates a component
package, much like pkgbuild(1), and
synthesizes a distribution file.--content
option.DSTROOT
setting. Use the
productbuild
--root
option
to specify that destination root directory and its install path. You can
specify additional requirements using a
PRE-INSTALL
REQUIREMENTS PROPERTY LIST. When you specify a root,
productbuild
automatically creates a component
package, much like pkgbuild(1), and
synthesizes a distribution file.--distribution
option
to specify the path to it, and the --package-path
option to specify the directory where the component packages are found (if
they are not in the current working directory). All packages referenced by
the distribution will be incorporated into the resulting product
archive.When
creating product archives for submission to the Mac App Store, use
only the --component
mode of
productbuild
. The other modes will create product
archives that are compatible with the OS X Installer, but are not
necessarily acceptable for the Mac App Store.
--distribution
dist-path--package-path
flag.
If --distribution
is omitted, a
distribution will be synthesized to install all of the bundles given by
--component
flags, or all of the packages given
by --package
flags.
--package-path
search-pathproductbuild
will search in
search-path for component packages named in the
distribution. You can use multiple --package-path
flags if necessary. The current working directory is searched
automatically.--resources
rsrc-dirproductbuild
will copy the resources from
rsrc-dir into the resulting product archive.
rsrc-dir can contain unlocalized resources (such as
image files) and/or standard lproj directories (e.g.
English.lproj) containing localized resources
(such as strings files).--ui
interface-type--ui
to select one for building the product
archive: this controls which package references are used. The
interface-type should match the value of the
“ui” attribute on the desired choices-outline. The default
is to use the choices-outline with no ui attribute.
If used without --distribution
, the
given interface-type will be used for the
choices-outline of the synthesized distribution.
--identifier
product-identifier--version
product-version--component
component-path
[install-path]Valid only if --distribution
is not
specified.
--component-compression
compression-mode--component
option. This option does not
affect the compression used for plugins or scripts. Three
compression-mode arguments are supported:productbuild
to automatically select
newer, more efficient compression algorithms based on properties of the
component, such as supported operating system versions. (See
os in the
PRE-INSTALL
REQUIREMENTS PROPERTY LIST section for more details on specifying
operating system requirements.)--component-compression
entirely. It is currently
equivalent to legacy but may change in future releases
of OS X.
Note that the Mac App Store may override the specified compression-mode for submitted product archives.
Valid with --component
only. To
control compression of component packages with
--distribution
or --root
use pkgbuild(1) and reference
each component package in a distribution file.
--content
content-pathValid only if --distribution
is not
specified.
--root
root-path install-pathValid only if --distribution
is not
specified.
--package
pkg-path [install-path]Valid only if --distribution
is not
specified.
If the package provided was created by the
pkgbuild
tool with the
--large-payload
option specified, then its large
payload format will be preserved. The generated product's distribution
will include a minimum system version requirement of
macOS 12.0
or the minimum allowable system
version(s) in the requirements property list, whichever is greater.
--synthesize
--product
requirements-plist--scripts
scripts-path--plugins
plugins-path--large-payload
productbuild
to construct a product where the
included payload format supports large files. A large file is defined as
any file that is 8 GiB
or larger.
Note:
Opting into
--large-payload
enforces a distribution
requirement that mandates macOS 12.0
or
later.
--sign
identity-name--keychain
keychain-path--cert
certificate-name--timestamp
--timestamp=none
--quiet
--synthesize
is used, the path to which the
synthesized distribution will be written.When you use productbuild
to synthesize a
distribution (e.g. with the --component
option), you
can specify pre-install requirements in a separate property list file,
specified with the --product
option. (When you use
Xcode to create a package for the Mac App Store, you can specify this file
using the "Pre-install Requirements Property List" build
setting.)
At the top level, this property list is a dictionary, with the following keys:
Key | Description |
os | Minimum allowable OS versions (array of strings) |
arch | Supported architectures (array of strings) |
ram | Minimum required RAM in gigabytes (real) |
bundle | Specific bundles that must exist on the system (array of dictionaries) |
all-bundles | Are all of the bundles specified required? (Boolean) |
gl-renderer | Required OpenGL capabilities (string) |
cl-device | Required OpenCL capabilities (string) |
metal-device | Required Metal capabilities (string) |
single-graphics-device | Requires that OpenGL, OpenCL, and Metal requirements be met by a single device. (Boolean) |
sysctl-requirements | Additional required hardware properties (string) |
home | Should installation be allowed in user home directory? (Boolean) |
NOTE: Some of the other requirements imply their own minimum system versions, which may override the values set here. This is noted below where applicable.
NOTE: On Apple Silicon, the macOS Installer will evaluate the product's distribution under Rosetta 2 unless the arch key includes the arm64 architecture specifier. Some distribution properties may be evaluated differently between Rosetta 2 and native execution, such as the predicate specified by the sysctl-requirements key. If the distribution is evaluated under Rosetta 2, any package scripts inside of product will be executed with Rosetta 2 at install time.
NOTE: Starting on macOS 11.0 (Big Sur), productbuild will automatically specify support for both arm64 and x86_64 unless a custom value for arch is provided.
Key Path | Description |
version | The supported OpenGL version as a double (e.g. major.minor). |
extensions | An array of OpenGL extension strings supported. |
limits.<gl-parameter> | The integer value of the named GL parameter (see below). |
limits.param<value> | The integer value of the GL parameter named by enum <value> (see below). |
Note that arbitrary GL parameters can be checked via the limits key, using the same symbolic name #defined by the GL headers. For example:
( version >= 2.0 OR ( ( 'GL_ARB_texture_float' IN extensions OR 'GL_ATI_texture_float' IN extensions ) AND 'GL_ARB_vertex_blend' IN extensions ) ) AND ( limits.GL_MAX_TEXTURE_SIZE >= 1024 AND limits.GL_MAX_TEXTURE_STACK_DEPTH > 8 )
Note that recently-introduced GL parameters may not be recognized by their symbolic names, in which case you can use the alternate form of param<value>, where <value> is the enum (integer) value of the parameter. For example:
limits.param0x0D33 >= 1024
NOTE: The gl-renderer requirement is ignored on versions of Mac OS X before 10.6.8. For this reason, specifying gl-renderer will cause the minimum system version to be raised to 10.6.8. This may override the values set via the os key.
Key Path | Description |
version | The supported OpenCL version as a double (e.g. major.minor). |
extensions | An array of OpenCL extension strings supported. |
limits.<cl-parameter> | The integer value of the named CL deviceInfo parameter. |
limits.param<value> | The integer value of the CL parameter named by enum <value>. |
NOTE: The cl-device requirement is ignored on versions of Mac OS X before 10.7. For this reason, specifying cl-device will cause the minimum system version to be raised to 10.7. This may override the values set via the os key.
KeyPath | Description |
deviceName | The name of the Metal Device that the hardware is using. <string> |
supportedFeatureSets | An array of Metal (MTLFeatureSet) feature sets that the device supports. <array<string>> |
isRemovable | The device is considered to be removable. This is useful for requiring an eGPU. <bool> |
isHeadless | The device can not and does not have any displays attached. <bool> |
isLowPowerDevice | Returns if the device is the low power device for automatic gfx switching. <bool> |
rasterOrderGroupsSupported | The device supports raster order groups. <bool> |
argumentBuffersTier | The graphics buffer tier that the device supports. <integer> |
NOTE: The metal-device requirement is ignored on versions of macOS before 10.14.4. For this reason, specifying metal-device will cause the minimum system version to be raised to 10.14.4. This may override the value set via the os key.
NOTE: An example of an MTLFeatureSet that would go into the supportedFeatureSets array would be MTLFeatureSet_macOS_GPUFamily1_v1 , a list of the current feature sets can be found in MTLDevice.h inside of Metal.framework.
If the gl-device, cl-renderer, and metal-device are specified, all of the requirements must be satisfied. By default, the requirements are considered met even if one graphics device satisfies the OpenGL requirement and a different one satisfies the OpenCL one (Same with Metal). If you want to require that a single device satisfies all of the graphics requirements, add the single-graphics-device key with a value of true.
NOTE: Setting the single-graphics-device to true will only be honored if all three of the graphics types are specified ( gl-device, cl-device, metal-device ). However, since legacy packages before 10.14.4 are supported, it can also be used if only gl-device and cl-device are specified.
hw.physicalcpu > 1
Or:
( hw.optional.aes == 1 AND hw.memsize >= 4294967296 )
NOTE: The sysctl-requirements predicate is ignored on versions of OS X before 10.10. For this reason, specifying sysctl-requirements will cause the minimum system version to be raised to 10.10. This may override the values set via the os key.
Key | Description |
id | The CFBundleIdentifier of the bundle (required) |
path | The default path of the bundle (required) |
CFBundleShortVersionString | The minimum short version string of the bundle (optional) |
search | Search for bundle if not found at default path? (Boolean, optional) |
The given default path will be checked first. Only if the bundle does not exist at that path, and search is given as true, the bundle identifier (id) will be used to find the bundle (this is appropriate for applications which the user might move). If the bundle is found through either method, and its version is greater than or equal to the given CFBundleShortVersionString, the requirement is met. (If CFBundleShortVersionString is omitted, the bundle need only exist.)
If you specify multiple bundles, all must exist, unless you specify the all-bundles key with a value of false, in which case only one of the bundles must exist.
If the bundle requirement is
not met, the Installer must have a localized explanation to display to
the user. This should be provided in the
InfoPlist.strings resource of your top-level
bundle (as specified with --component
), under
the
RequiredBundlesDescription
key.
When creating a product archive, you can optionally add a digital
signature to the archive. You will need to have a certificate and
corresponding private key -- together called an “identity” --
in one of your accessible keychains. To add a signature, specify the name of
the identity using the --sign
option. The identity's
name is the same as the “Common Name” of the certificate.
If you want to search for the identity in a specific keychain,
specify the path to the keychain file using the
--keychain
option. Otherwise, the default keychain
search path is used.
productbuild
will embed the signing
certificate in the product archive, as well as any intermediate certificates
that are found in the keychain. If you need to embed additional certificates
to form a chain of trust between the signing certificate and a trusted root
certificate on the system, use the --cert
option to
give the Common Name of the intermediate certificate. Multiple
--cert
options may be used to embed multiple
intermediate certificates.
The signature can optionally include a trusted timestamp. This is
enabled by default when signing with a Developer ID identity, but it can be
enabled explicitly using the --timestamp
option. A
timestamp server must be contacted to embed a trusted timestamp. If you
aren't connected to the Internet, you can use
--timestamp=none
to disable timestamps, even for a
Developer ID identity.
Note that component packages do not need to be signed (e.g. with pkgbuild(1)) before adding them to a signed product archive. The signature on the product archive protects the entire product, including the added packages.
If you want to postpone signing the product archive until it has been tested and is ready to deploy, you can use productsign(1) when you are ready to add the signature.
productbuild
--component build/Release/Sample.app /Applications
Product.pkg
Build the archive Product.pkg to install Sample.app under /Applications, synthesizing a distribution. This is typical for building a Mac App Store archive.
productbuild
--product def.plist --component build/Release/Sample.app /Applications
Product.pkg
Build the archive Product.pkg to install Sample.app under /Applications, synthesizing a distribution with the requirements from def.plist. This is typical for building a Mac App Store archive with pre-install requirements.
productbuild
--distribution Product.dist --package-path /tmp/Packages
Product.pkg
Build the archive Product.pkg using Product.dist, searching for packages referenced by that distribution in /tmp/Packages (as well as in CWD).
productbuild
--distribution Product.dist --resources Resources
Product.pkg
Build the archive Product.pkg using Product.dist, incorporating the resources found under the Resources directory.
productbuild
--distribution Product.dist --sign sample-identity
Product.pkg
Build the archive Product.pkg using Product.dist, and sign the
resulting archive using the identity sample-identity. You will be
prompted to allow productbuild
to access the
keychain item, unless Always Allow was chosen previously.
productbuild
--package /tmp/a.pkg --package /tmp/b.pkg Product.pkg
Build the archive Product.pkg with the component packages /tmp/a.pkg and /tmp/b.pkg, synthesizing a distribution.
January 19, 2021 | macOS |