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


     pkgbuild -- Build an OS X Installer component package from on-disk files


     pkgbuild [options] --root root-path [--component-plist plist-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:

     1.   Package a complete 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 --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.

     2.   Create a template component property list (analyze mode). You point
          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.

     3.   Package one or more individual bundles. If you don't have a destina-
          tion root, you can use the --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
                 Package the entire contents of the directory tree at
                 root-path, typically a destination root created by

     --component component-path
                 The bundle at component-path is added to the package. Valid
                 only if you don't use --root.

     --component-plist plist-path
                 If you specify --root, you can use --component-plist to iden-
                 tity 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
                 Archive the entire contents of scripts-path as the package
                 scripts. If this directory contains scripts named preinstall
                 and/or postinstall, these will be run as the top-level
                 scripts of the package. If you want to run scripts for spe-
                 cific bundles, you must specify those in a component property
                 list; see more at COMPONENT PROPERTY LIST.  Any other files
                 under scripts-path will be used only if the top-level or com-
                 ponent-specific scripts invoke them.

                 Indicates that the package will contain only scripts, with no

     --identifier pkg-identifier
                 Specify a unique identifier for this package. The OS X
                 Installer recognizes a package as being an upgrade to an
                 already-installed package only if the package identifiers
                 match, so it is advisable to set a meaningful, consistent
                 identifier when you build the package.  pkgbuild will infer
                 an identifier when building a package from a single compo-
                 nent, but will fail otherwise if the identifier has not been

     --version pkg-version
                 Specify a version for the package. Packages with the same
                 identifier are compared using this version, to determine if
                 the package is an upgrade or downgrade. If you don't specify
                 a version, a default of zero is assumed, but this may prevent
                 proper upgrade/downgrade checking.

     --install-location install-path
                 Specify the default install location for the contents of the
                 package. For example, if you specify a single application
                 component, you might specify an install-path of
                 /Applications.  pkgbuild attempts to infer a sensible install
                 path if this option is not used, but it may not choose cor-
                 rectly. Note that whether or not the default install location
                 is actually used by the OS X Installer depends on the distri-
                 bution file you deploy with the package.

     --analyze   Instead of creating a package, create a template component
                 property list from the destination root given with --root.
                 See COMPONENT PROPERTY LIST.

     --prior pkg-path
                 In addition to the options above, you can also set the pack-
                 age identifier, version and install location by pointing to a
                 prior version of the same package.  pkgbuild 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 incre-
                 mented, 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
                 By default, --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 pack-
                 age payload. (Note that specifying even one --filter inhibits
                 the default filters, so you must respecify the default fil-
                 ters if you still want them to be used.)

     --ownership (recommended | preserve | preserve-other)
                 By default, when the payload is archived into the package,
                 the recommended UID and GID will be applied to all files.
                 (Generally, this will be root:wheel, which ensures that files
                 installed in the system domain are root-owned, while files
                 installed in the user home directory will be owned by that
                 user.) If you have special ownership requirements, you should
                 use chmod(1) to adjust the ownership of the source files, and
                 use --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.

     --sign identity-name
                 Adds a digital signature to the resulting package. See SIGNED

     --keychain keychain-path
                 Specify a specific keychain to search for the signing iden-
                 tity. See SIGNED PACKAGES

     --cert certificate-name
                 Specify an intermediate certificate to be embedded in the
                 package. See SIGNED_PACKAGES

                 Include a trusted timestamp with the signature. See

                 Disable trusted timestamp, regardless of identity. See

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

                   The path to which the package will be written.

                   When --analyze is used, the path to which the template com-
                   ponent 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

     Key                            Description
     RootRelativeBundlePath         Path to bundle relative to the destination
     BundleIsRelocatable            Install bundle over previous version if
     BundleIsVersionChecked         Don't install bundle if newer version on
     BundleHasStrictIdentifier      Require identical bundle identifiers at
     BundleOverwriteAction          How to treat existing on-disk version of
     BundlePreInstallScriptPath     Relative path to bundle-specific
     BundlePostInstallScriptPath    Relative path to bundle-specific
     ChildBundles                   Bundles under this bundle (array of

     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 when the version in the package is installed. 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 bun-
     dle in the package overwrites the version on disk, and any files not con-
     tained 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 dictio-
     naries (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 pri-
     vate 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 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 if you are going to create a signed product with the resulting
     package, using productbuild(1), there is no reason to sign the individual


     pkgbuild --identifier --root /tmp/Sample.dst

             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 tem-
             plate component property list to components.plist.

     pkgbuild --identifier --root /tmp/Sample.dst
             --component-plist components-edited.plist Sample.pkg

             Build the package Sample.pkg using the destination root /tmp/Sam-
             ple.dst, using the bundle-specific behaviors indicated in compo-

     pkgbuild --identifier --root /tmp/Sample.dst --sign
             sample-identity Sample.pkg

             Build the package Sample.pkg using the destination root /tmp/Sam-
             ple.dst, and sign the resulting package using the identity sam-
             ple-identity. You will be prompted to allow pkgbuild to access
             the keychain item, unless Always Allow was chosen previously.


     productbuild(1), xcodebuild(1)

Mac OS                        September 15, 2010                        Mac OS

Mac OS X 10.8 - Generated Mon Aug 20 15:39:00 CDT 2012
© 2000-2024
Individual documents may contain additional copyright information.