NAME

productbuild — Build a product archive for the macOS Installer or the Mac App Store.

SYNOPSIS

DESCRIPTION

A product archive is a flat file with a .pkg extension. productbuild creates a deployable product archive, which can be used with the macOS Installer, or submitted to the Mac App Store. It has 5 different modes, as shown in the SYNOPSIS above:

1. Create a product archive from a bundle (e.g. for the Mac App Store). If you have a self-contained bundle (e.g. an app) that always gets installed to the same location (e.g. /Applications), specify the bundle and install path using the --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.
2. Create a product archive for in-app content. Specify in-app content using the --content option.
3. Create a product archive from a destination root. When you use xcodebuild(1) with the install action, the result is a destination root, either under /tmp, or in whatever location you specify with the Xcode 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.
4. Create a product archive using a distribution file. If you have a distribution file, use the --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.
5. Synthesize a distribution for one or more component packages. This also synthesizes a distribution (also using an optional PRE-INSTALL REQUIREMENTS PROPERTY LIST), but writes out the resulting distribution instead of incorporating it into a product archive. This can serve as a starting point if a more sophisticated distribution is required.

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 macOS Installer, but are not necessarily acceptable for the Mac App Store.

ARGUMENTS AND OPTIONS

--distribution dist-path

Use the distribution file at dist-path to define the presentation, choices and packages to be installed by the product. Each of the package names referenced in the given distribution file must be found in a path specified with the --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-path

productbuild 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-dir

productbuild 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

If the distribution has multiple choices-outline elements, you can use --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

The given unique (non-localized) product-identifier will be associated with the product.

--version product-version

The given product-version string will be associated with the product.

--component component-path [install-path]

The bundle at component-path is added to the product archive (as its own component package) and to the synthesized distribution. If install-path is specified, it is used as the default install location for the bundle. (If you omit install-path, a location is inferred from the given component-path.)

Valid only if --distribution is not specified.

--component-compression compression-mode

Allows control of compression used for storing any components added via the --component option. This option does not affect the compression used for plugins or scripts. Three compression-mode arguments are supported:

• legacy forces a 10.5-compatible compression algorithm for all components.
• auto enables 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.)
• default provides identical behavior to omitting --component-compression entirely. It is currently equivalent to legacy but may change in future releases of macOS.

  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-path

The contents of the directory at content-path are added to the product archive (as its own component package) and to the synthesized distribution.

Valid only if --distribution is not specified.

--root root-path install-path

The entire directory tree at root-path is added to the product archive (as its own component package) and to the synthesized distribution. This is typically used for a destination root created by xcodebuild(1).

Valid only if --distribution is not specified.

--package pkg-path [install-path]

The component package at pkg-path is added to the product archive and to the synthesized distribution. If install-path is specified, it is used as the default install location for the package, overriding any default location specified by the component package itself.

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 Monterey (12.0) or the minimum allowable system version(s) in the requirements property list, whichever is greater.

--synthesize

Write the synthesized distribution directly instead of incorporating it into a product archive.

--product requirements-plist

When synthesizing a distribution, use the requirements from requirements-plist. See PRE-INSTALL REQUIREMENTS PROPERTY LIST (this was formerly called the "product definition property list").

--scripts scripts-path

The contents of scripts-path is added to the product archive for use by system.run() commands in the distribution. This is valid only for product archives targeted to the macOS Installer application.

--plugins plugins-path

The contents of plugins-path is added to the product archive for use by the macOS Installer application's plugin mechanism. It will normally contain a InstallerSections.plist file, and one or more plugin bundles.

--large-payload

By default, packages that are nested inside of products have a per‐file size limit associated with them. This method instructs 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 Monterey (12.0) or later.

--sign identity-name

Adds a digital signature to the resulting package. See SIGNED PRODUCT ARCHIVES

--keychain keychain-path

Specify a specific keychain to search for the signing identity. See SIGNED PRODUCT ARCHIVES

--cert certificate-name

Specify an intermediate certificate to be embedded in the package. See SIGNED PRODUCT ARCHIVES

--timestamp

Include a trusted timestamp with the signature. See SIGNED PRODUCT ARCHIVES

--timestamp=none

Disable trusted timestamp, regardless of identity. See SIGNED PRODUCT ARCHIVES

--quiet

Inhibits status messages on stdout. Any error messages are still sent to stderr.

product-output-path

The path to which the product archive will be written.

distribution-output-path

When --synthesize is used, the path to which the synthesized distribution will be written.

PRE-INSTALL REQUIREMENTS PROPERTY LIST

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:

• The os key defines one or more minimum system versions. You might have multiple versions if a certain OS update is required for a given major OS version. For example, if you specify 10.5.4 and 10.6.2, Leopard would be allowed from 10.5.4 up, and Snow Leopard from 10.6.2 up, but 10.6 and 10.6.1 would be rejected. There is no upper-bound associated with the highest value given.

  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.

• The arch key specifies the supported architectures, e.g. x86_64 and/or arm64. Note that i386 infers x86_64, for compatibility reasons.

  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 Big Sur (11.0), productbuild will automatically specify support for both arm64 and x86_64 unless a custom value for arch is provided.

• The ram key specifies the minimum amount of RAM required, in gigabytes.
• The gl-renderer key specifies a predicate, against which each of the OpenGL hardware renderers will be checked. For the product to be installed, at least one of the renderers must match the requirements of the predicate. The given predicate string must be convertible to an NSPredicate, and can use the following key paths:

  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.

• The cl-device key specifies a predicate, against which each of the OpenCL GPU devices will be checked. For the product to be installed, at least one of the devices must match the requirements of the predicate. The given predicate string must be convertible to an NSPredicate, and can use the following key paths:

  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.

• The metal-device key specifies a predicate, against which each of the Metal GPU devices will be checked. For the product to be installed, at least one of the devices must match the requirements of the predicate. The given predicate string must be convertible to an NSPredicate, and can use the following key paths:

  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.

• The sysctl-requirements key specifies a predicate, against which additional hardware requirements will be checked. The predicate uses the sysctl(2) facility to obtain hardware properties for the system in use. Note that only a subset of sysctl(2) variables are available, including most of the hw.* tree and kern.ostype, kern.osrelease, kern.osrevision, and kern.version from the kern.* tree. For example:

     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.

• The bundle key specifies one or more bundles that must already exist on the system (possibly at some minimum version) for the product to be installed. For example, this might be appropriate if the product installs a plugin, and you need to ensure that a compatible version of the host application is available. Each object in this array is a dictionary with the following keys:

  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.

• The home key, if set to true, designates that the product can be installed under the user's home directory, as an alternative to installing on the system for all users. This should be enabled only if the entire product can be installed in the home directory and be functional. (Home directory installation is disabled by default.) Note that home directory installation is not supported for the Mac App Store.

SIGNED PRODUCT ARCHIVES

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.

EXAMPLES

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.

SEE ALSO

pkgbuild(1), productsign(1), xcodebuild(1)