productbuild

productbuild(1)              General Commands Manual             productbuild(1)

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

SYNOPSIS
     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

DESCRIPTION
     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:

     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 OS X 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 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-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 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 OS X Installer
             application.

     --plugins plugins-path
             The contents of plugins-path is added to the product archive for
             use by the OS X 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 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:

     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)

     •   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 11.0 (Big Sur), 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)

macOS                           January 19, 2021                           macOS