manpagez: man pages & more
man productbuild(1)
Home | html | info | man
productbuild(1)           BSD General Commands Manual          productbuild(1)


NAME

     productbuild -- Build a product archive for the OS X 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 spec-
          ify additional requirements using a PRE-INSTALL REQUIREMENTS
          PROPERTY LIST.  When you specify a bundle, productbuild automati-
          cally creates a component package, much like pkgbuild(1), and syn-
          thesizes 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 distribu-
          tion 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 presen-
                 tation, choices and packages to be installed by the product.
                 Each of the package names referenced in the given distribu-
                 tion file must be found in a path specified with the
                 --package-path flag.

                 If --distribution is omitted, a distribution will be synthe-
                 sized 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 pack-
                 ages named in the distribution. You can use multiple
                 --package-path flags if necessary. The current working direc-
                 tory 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 direc-
                 tories (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 ar-
                 chive: 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 distribu-
                 tion.

     --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 distri-
                 bution. 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.

     --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 prod-
                 uct archive (as its own component package) and to the synthe-
                 sized 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 ar-
                 chive 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.

     --synthesize
                 Write the synthesized distribution directly instead of incor-
                 porating 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.

     --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 iden-
                 tity. 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 synthe-
                   sized 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 sepa-
     rate 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)
     single-graphics-device    Must OpenGL and OpenCL requirements be met by a
                                                                                                single
                                                                                                device?
                                                                                                (Boolean)
     home                      Should installation be allowed in user home
                                                                                                directory?
                                                                                                (Boolean)

     o   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.

     o   The arch key specifies the supported architectures, e.g. i386 and/or
         x86_64. Note that i386 allows both 32- and 64-bit systems, but if you
         specify only x86_64, a 64-bit system is required.

     o   The ram key specifies the minimum amount of RAM required, in giga-
         bytes.

     o   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 param-
         eter. 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.

     o   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 predi-
         cate.  The given predicate string must be convertible to an NSPredi-
         cate, 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>.

         If both cl-device and gl-renderer are specified, both must be satis-
         fied. By default, the requirements are considered met even if one
         graphics device satisfies the OpenGL requirement and a different one
         satisfies the OpenCL one.  If you want to require that a single
         device satisfies both, add the single-graphics-device key with a
         value of true.

         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.

     o   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 iden-
         tifier (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 speci-
         fied with --component), under the RequiredBundlesDescription key.

     o   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 signa-
     ture to the archive.  You will need to have a certificate and correspond-
     ing private key -- together called an ``identity'' -- in one of your
     accessible keychains. To add a signature, specify the name of the iden-
     tity 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 inter-
     mediate 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 signa-
     ture 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 /Appli-
             cations, synthesizing a distribution. This is typical for build-
             ing 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 /Appli-
             cations, 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)

Mac OS                        September 15, 2010                        Mac OS

Mac OS X 10.9 - Generated Sun Oct 13 09:33:26 CDT 2013
© manpagez.com 2000-2021
Individual documents may contain additional copyright information.