productbuild(1) BSD General Commands Manual productbuild(1)
NAME
productbuild -- Build deployable product from Mac OS X Installer pack-
ages.
SYNOPSIS
productbuild [options] --distribution dist-path
[--package-path search-path] product-output-path
productbuild [--product definition-plist]
{--component component-path install-path}
product-output-path
productbuild --synthesize [--product definition-plist]
{--package pkg-path} distribution-output-path
DESCRIPTION
productbuild creates a deployable product archive, which can be used with
the Mac OS X Installer. It has three different modes, as shown in the
SYNOPSIS above:
1. 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.
2. Create a product archive from one or more bundles (or component
packages). If you don't have a distribution, but want to always
install the same bundles, specify each bundle and its install loca-
tion using the --component option. productbuild will create a prod-
uct archive which installs the specified components, using a synthe-
sized distribution. You can specify additional parameters and
requirements using a PRODUCT DEFINITION PROPERTY LIST. When you
specify a bundle, productbuild automatically creates a component
package, much like pkgbuild(1). However, if you have already cre-
ated a component package and want to archive it with a synthesized
distribution, you can use the --package option instead of
--component.
3. Synthesize a distribution for one or more component packages. This
also synthesizes a distribution (also using an optional PRODUCT
DEFINITION 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.
A product archive is a single, flat file with a .pkg extension. Although
it appears to be the same type as a simple component package, it differs
by virtue of containing a distribution and localized resources. Although
either type of .pkg can be opened by the Mac OS X Installer, product ar-
chives are preferred, because they give the developer more control over
presentation and more flexibility in packaging.
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.
--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 definition-plist
When synthesizing a distribution, use the parameters and
requirements from definition-plist. See PRODUCT DEFINITION
PROPERTY LIST.
--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
--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.
PRODUCT DEFINITION PROPERTY LIST
When you use productbuild to synthesize a distribution (e.g. with the
--component option), you can specify additional parameters and require-
ments in a separate property list file, specified with the --product
option. 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.)
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.
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 --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 --component build/Release/Sample.app /Applications
Product.pkg
Build the archive Product.pkg to install Sample.app under /Appli-
cations, synthesizing a distribution.
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 parameters and
requirements from def.plist.
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)
Mac OS September 15, 2010 Mac OS
Mac OS X 10.7 - Generated Tue Aug 9 20:40:19 CDT 2011