pkgbuild(1) | General Commands Manual | pkgbuild(1) |
pkgbuild
— Build a
macOS Installer component package from on-disk files
pkgbuild |
[options] --root root-path
[--component-plist
plist-path]
package-output-path |
pkgbuild |
--analyze --root
root-path
plist-output-path |
pkgbuild |
[options] {--component
component-path}
package-output-path |
A “component package” contains payload to be installed by the OS X Installer. Although a component package can be installed on its own, it is typically incorporated into a product archive, along with a “distribution” and localized resources, using productbuild(1).
To create a
product archive for submission to the Mac App Store, do not use
pkgbuild
. Instead, use
productbuild(1) directly.
pkgbuild
has three different modes, as
shown in the SYNOPSIS above:
DSTROOT
setting. Use the
--root
option to specify that destination root
directory to pkgbuild
, and the entire contents of
the directory tree will be included in the output package.pkgbuild
to a destination root as above, but
instead of outputting a package, pkgbuild
outputs
a component property list (see
COMPONENT PROPERTY
LIST). By editing this property list and specifying it with
--component-plist
when you subsequently build the
package, you can control bundle-specific Installer behavior.--component
option to
specify one or more bundles that should be incorporated into the package.
Note that only
bundles
can be specified with --component
.--root
root-path--component
component-path--root
.--component-plist
plist-path--root
, you can use
--component-plist
to identity the bundles within
that destination root, and control how the OS X Installer handles those
bundles. See more at
COMPONENT PROPERTY LIST.
If you add bundles and need to update your component property list, you
can specify the old version with --component-plist
when running pkgbuild
with
--analyze
, and the old settings will be propagated
to the output for still-extant bundles.--scripts
scripts-path--nopayload
--identifier
pkg-identifierpkgbuild
will infer an identifier when building a
package from a single component, but will fail otherwise if the identifier
has not been set.--version
pkg-version--install-location
install-pathpkgbuild
attempts to infer a sensible install path if this option is not used, but
it may not choose correctly. Note that whether or not the default install
location is actually used by the OS X Installer depends on the
distribution file you deploy with the package.--analyze
--root
. See
COMPONENT PROPERTY
LIST.--prior
pkg-pathpkgbuild
will read the package at
pkg-path and use the same package identifier and
install location contained therein. The version number in the prior
package will be converted to an integer and incremented, and the result
used for the new package. Note that pkgbuild
makes
no attempt to verify that the prior package is in any way equivalent to
the one being built, so you must make sure you point it to a logically
equivalent package.--filter
filter-expression--root
will include the entire
contents of the given root-path in the package
payload, except for any .svn or
CVS directories, and any
.DS_Store files. You can override these default
filters by specifying one or more --filter
options. Each filter-expression is an
re_format(7)
“extended” expression: any path in the root which matches
any of the given expressions will be excluded from the package payload.
(Note that specifying even one --filter
inhibits
the default filters, so you must respecify the default filters if you
still want them to be used.)--ownership
(recommended
|
preserve
|
preserve-other
)--ownership preserve
so
that pkgbuild
archives the exact ownership of the
on-disk files. Alternatively, if you have just a few files to adjust,
--ownership preserve-other
will apply the
recommended UID and GID to those files that are owned by the user running
pkgbuild
, but leave other files unchanged. Note
that pkgbuild
never changes the ownership of the
actual on-disk files, only the ownership that is archived into the
package.--large-payload
pkgbuild
to construct a package where the included
payload format supports large files. A large file is defined as any file
that is 8 GiB
or larger.
Warning:
The
--large-payload
option generates packages that
are only compatible with macOS 12.0
and above.
Packages using this feature will fail to install or extract on previous
releases. Specifying this option requires the user to pass
[--min-os-version 12.0]
or later to acknowledge
this requirement.
--compression
compression-modepkgbuild
to automatically select newer,
more efficient compression algorithms based on what is provided to
[--min-os-version <version>].
--min-os-version
os-versionproductbuild(1).
Some of the options in this tool
require this argument to be provided.--sign
identity-name--keychain
keychain-path--cert
certificate-name--timestamp
--timestamp=none
--quiet
--analyze
is used, the path to which the
template component property list will be written.When you package a destination root, you can use a component property list to specify how bundles in that root should be handled by the OS X Installer. This property list should be an array of dictionaries, where each dictionary specifies a single bundle. The dictionary keys are as follows:
Key | Description |
RootRelativeBundlePath | Path to bundle relative to the destination root (string) |
BundleIsRelocatable | Install bundle over previous version if moved by user? (bool) |
BundleIsVersionChecked | Don't install bundle if newer version on disk? (bool) |
BundleHasStrictIdentifier | Require identical bundle identifiers at install path? (bool) |
BundleOverwriteAction | How to treat existing on-disk version of bundle (string) |
BundlePreInstallScriptPath | Relative path to bundle-specific preinstall script |
BundlePostInstallScriptPath | Relative path to bundle-specific postinstall script |
ChildBundles | Bundles under this bundle (array of dictionaries) |
The easiest way to create a component property list is to use the
--analyze
option and point
pkgbuild
at your current destination root. The
output will be a component property list with default attributes, which you
can then edit as needed. You can also specify a previous version of your
component property list when using --analyze
, which
will cause the attributes of previously existing bundles to be propagated
forward.
BundleOverwriteAction specifies how an existing
version of the bundle on disk should be handled if the version in the
package is installed. Despite the name, both upgrade
and update do no version checking. Conditionally
installing based on version is controlled entirely by
BundleIsVersionChecked.
If you specify
upgrade, the bundle in the package atomically replaces
any version on disk; this has the effect of deleting old paths that no
longer exist in the new version of the bundle. If you specify
update, the bundle in the package overwrites the
version on disk, and any files not contained in the package will be left
intact; this is appropriate when you are delivering an update-only package.
Another effect of update is that the package bundle
will not be installed at all if there is not already a version on disk; this
allows a package to deliver an update for an app that the user might have
deleted.
BundlePreInstallScriptPath and
BundlePostInstallScriptPath are meaningful only if
--scripts
was used to specify a scripts directory.
The paths given by these keys must be relative to the scripts directory.
ChildBundles can be used to represent nesting of bundles, but it does not change the meaning of RootRelativeBundlePath within lower-level dictionaries (i.e. it is always relative to the destination root). If you write a component property list manually, you do not need to use ChildBundles at all; you can simply put all bundle dictionaries in the top-level array.
When creating a package, you can optionally add a digital
signature to the package. 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.
pkgbuild
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 if you are going to create a signed product with the resulting package, using productbuild(1), there is no reason to sign the individual package.
pkgbuild
--identifier com.sample.pkg.app --root /tmp/Sample.dst
Sample.pkg
Build the package Sample.pkg using the entire contents of the destination root /tmp/Sample.dst.
pkgbuild
--analyze --root /tmp/Sample.dst components.plist
Analyze the destination root /tmp/Sample.dst, and write a template component property list to components.plist.
pkgbuild
--identifier com.sample.pkg.app --root /tmp/Sample.dst --component-plist
components-edited.plist Sample.pkg
Build the package Sample.pkg using the destination root /tmp/Sample.dst, using the bundle-specific behaviors indicated in components-edited.plist.
pkgbuild
--identifier com.sample.pkg.app --root /tmp/Sample.dst --sign
sample-identity Sample.pkg
Build the package Sample.pkg using the destination root
/tmp/Sample.dst, and sign the resulting package using the identity
sample-identity. You will be prompted to allow
pkgbuild
to access the keychain item, unless
Always Allow was chosen previously.
July 1, 2021 | macOS |