Help/cpack_gen/productbuild.rst

   1 CPack productbuild Generator
   2 ----------------------------
   3
   4 .. versionadded:: 3.7
   5
   6 productbuild CPack generator (macOS).
   7
   8 Variables specific to CPack productbuild generator
   9 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  10
  11 The following variable is specific to installers built on Mac
  12 macOS using ProductBuild:
  13
  14 .. variable:: CPACK_COMMAND_PRODUCTBUILD
  15
  16  Path to the ``productbuild(1)`` command used to generate a product archive for
  17  the macOS Installer or Mac App Store.  This variable can be used to override
  18  the automatically detected command (or specify its location if the
  19  auto-detection fails to find it).
  20
  21 .. variable:: CPACK_PRODUCTBUILD_IDENTIFIER
  22
  23  .. versionadded:: 3.23
  24
  25  Set the unique (non-localized) product identifier to be associated with the
  26  product (i.e., ``com.kitware.cmake``). Any component product names will be
  27  appended to this value.
  28
  29 .. variable:: CPACK_PRODUCTBUILD_IDENTITY_NAME
  30
  31  .. versionadded:: 3.8
  32
  33  Adds a digital signature to the resulting package.
  34
  35
  36 .. variable:: CPACK_PRODUCTBUILD_KEYCHAIN_PATH
  37
  38  .. versionadded:: 3.8
  39
  40  Specify a specific keychain to search for the signing identity.
  41
  42
  43 .. variable:: CPACK_COMMAND_PKGBUILD
  44
  45  Path to the ``pkgbuild(1)`` command used to generate an macOS component package
  46  on macOS.  This variable can be used to override the automatically detected
  47  command (or specify its location if the auto-detection fails to find it).
  48
  49
  50 .. variable:: CPACK_PKGBUILD_IDENTITY_NAME
  51
  52  .. versionadded:: 3.8
  53
  54  Adds a digital signature to the resulting package.
  55
  56
  57 .. variable:: CPACK_PKGBUILD_KEYCHAIN_PATH
  58
  59  .. versionadded:: 3.8
  60
  61  Specify a specific keychain to search for the signing identity.
  62
  63
  64 .. variable:: CPACK_PREFLIGHT_<COMP>_SCRIPT
  65
  66  Full path to a file that will be used as the ``preinstall`` script for the
  67  named ``<COMP>`` component's package, where ``<COMP>`` is the uppercased
  68  component name.  No ``preinstall`` script is added if this variable is not
  69  defined for a given component.
  70
  71
  72 .. variable:: CPACK_POSTFLIGHT_<COMP>_SCRIPT
  73
  74  Full path to a file that will be used as the ``postinstall`` script for the
  75  named ``<COMP>`` component's package, where ``<COMP>`` is the uppercased
  76  component name.  No ``postinstall`` script is added if this variable is not
  77  defined for a given component.
  78
  79 .. variable:: CPACK_PRODUCTBUILD_RESOURCES_DIR
  80
  81  .. versionadded:: 3.9
  82
  83  If specified the productbuild generator copies files from this directory
  84  (including subdirectories) to the ``Resources`` directory. This is done
  85  before the :variable:`CPACK_RESOURCE_FILE_WELCOME`,
  86  :variable:`CPACK_RESOURCE_FILE_README`, and
  87  :variable:`CPACK_RESOURCE_FILE_LICENSE` files are copied.
  88
  89 .. variable:: CPACK_PRODUCTBUILD_DOMAINS
  90
  91  .. versionadded:: 3.23
  92
  93  This option enables more granular control over where the product may be
  94  installed. When it is set to true, a ``domains`` element of the following
  95  form will be added to the productbuild Distribution XML:
  96
  97  .. code-block:: xml
  98
  99     <domains enable_anywhere="true" enable_currentUserHome="false" enable_localSystem="true"/>
 100
 101  The default values are as shown above, but can be overridden with
 102  :variable:`CPACK_PRODUCTBUILD_DOMAINS_ANYWHERE`,
 103  :variable:`CPACK_PRODUCTBUILD_DOMAINS_USER`, and
 104  :variable:`CPACK_PRODUCTBUILD_DOMAINS_ROOT`.
 105
 106 .. variable:: CPACK_PRODUCTBUILD_DOMAINS_ANYWHERE
 107
 108  .. versionadded:: 3.23
 109
 110  May be used to override the ``enable_anywhere`` attribute in the ``domains``
 111  element of the Distribution XML. When set to true, the product can be
 112  installed at the root of any volume, including non-system volumes.
 113
 114  :variable:`CPACK_PRODUCTBUILD_DOMAINS` must be set to true for this variable
 115  to have any effect.
 116
 117 .. variable:: CPACK_PRODUCTBUILD_DOMAINS_USER
 118
 119  .. versionadded:: 3.23
 120
 121  May be used to override the ``enable_currentUserHome`` attribute in the
 122  ``domains`` element of the Distribution XML. When set to true, the product
 123  can be installed into the current user's home directory. Note that when
 124  installing into the user's home directory, the following additional
 125  requirements will apply:
 126
 127  * The installer may not write outside the user's home directory.
 128  * The install will be performed as the current user rather than as ``root``.
 129    This may have ramifications for :variable:`CPACK_PREFLIGHT_<COMP>_SCRIPT`
 130    and :variable:`CPACK_POSTFLIGHT_<COMP>_SCRIPT`.
 131  * Administrative privileges will not be needed to perform the install.
 132
 133  :variable:`CPACK_PRODUCTBUILD_DOMAINS` must be set to true for this variable
 134  to have any effect.
 135
 136 .. variable:: CPACK_PRODUCTBUILD_DOMAINS_ROOT
 137
 138  .. versionadded:: 3.23
 139
 140  May be used to override the ``enable_localSystem`` attribute in the
 141  ``domains`` element of the Distribution XML. When set to true, the product
 142  can be installed in the root directory. This should normally be set to true
 143  unless the product should only be installed to the user's home directory.
 144
 145  :variable:`CPACK_PRODUCTBUILD_DOMAINS` must be set to true for this variable
 146  to have any effect.
 147
 148 Background Image
 149 """"""""""""""""
 150
 151 .. versionadded:: 3.17
 152
 153 This group of variables controls the background image of the generated
 154 installer.
 155
 156 .. variable:: CPACK_PRODUCTBUILD_BACKGROUND
 157
 158  Adds a background to Distribution XML if specified. The value contains the
 159  path to image in ``Resources`` directory.
 160
 161 .. variable:: CPACK_PRODUCTBUILD_BACKGROUND_ALIGNMENT
 162
 163  Adds an ``alignment`` attribute to the background in Distribution XML.
 164  Refer to Apple documentation for valid values.
 165
 166 .. variable:: CPACK_PRODUCTBUILD_BACKGROUND_SCALING
 167
 168  Adds a ``scaling`` attribute to the background in Distribution XML.
 169  Refer to Apple documentation for valid values.
 170
 171 .. variable:: CPACK_PRODUCTBUILD_BACKGROUND_MIME_TYPE
 172
 173  Adds a ``mime-type`` attribute to the background in Distribution XML.
 174  The option contains MIME type of an image.
 175
 176 .. variable:: CPACK_PRODUCTBUILD_BACKGROUND_UTI
 177
 178  Adds an ``uti`` attribute to the background in Distribution XML.
 179  The option contains UTI type of an image.
 180
 181 .. variable:: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA
 182
 183  Adds a background for the Dark Aqua theme to Distribution XML if
 184  specified. The value contains the path to image in ``Resources``
 185  directory.
 186
 187 .. variable:: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA_ALIGNMENT
 188
 189  Does the same as :variable:`CPACK_PRODUCTBUILD_BACKGROUND_ALIGNMENT` option,
 190  but for the dark theme.
 191
 192 .. variable:: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA_SCALING
 193
 194  Does the same as :variable:`CPACK_PRODUCTBUILD_BACKGROUND_SCALING` option,
 195  but for the dark theme.
 196
 197 .. variable:: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA_MIME_TYPE
 198
 199  Does the same as :variable:`CPACK_PRODUCTBUILD_BACKGROUND_MIME_TYPE` option,
 200  but for the dark theme.
 201
 202 .. variable:: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA_UTI
 203
 204  Does the same as :variable:`CPACK_PRODUCTBUILD_BACKGROUND_UTI` option,
 205  but for the dark theme.
 206
 207 Distribution XML Template
 208 ^^^^^^^^^^^^^^^^^^^^^^^^^
 209
 210 CPack uses a template file to generate the ``distribution.dist`` file used
 211 internally by this package generator. Ordinarily, CMake provides the template
 212 file, but projects may supply their own by placing a file called
 213 ``CPack.distribution.dist.in`` in one of the directories listed in the
 214 :variable:`CMAKE_MODULE_PATH` variable. CPack will then pick up the project's
 215 template file instead of using its own.
 216
 217 The ``distribution.dist`` file is generated by performing substitutions
 218 similar to the :command:`configure_file` command. Any variable set when
 219 CPack runs will be available for substitution using the usual ``@...@``
 220 form. The following variables are also set internally and made available for
 221 substitution:
 222
 223 ``CPACK_RESOURCE_FILE_LICENSE_NOPATH``
 224   Same as :variable:`CPACK_RESOURCE_FILE_LICENSE` except without the path.
 225   The named file will be available in the same directory as the generated
 226   ``distribution.dist`` file.
 227
 228 ``CPACK_RESOURCE_FILE_README_NOPATH``
 229   Same as :variable:`CPACK_RESOURCE_FILE_README` except without the path.
 230   The named file will be available in the same directory as the generated
 231   ``distribution.dist`` file.
 232
 233 ``CPACK_RESOURCE_FILE_WELCOME_NOPATH``
 234   Same as :variable:`CPACK_RESOURCE_FILE_WELCOME` except without the path.
 235   The named file will be available in the same directory as the generated
 236   ``distribution.dist`` file.
 237
 238 ``CPACK_APPLE_PKG_INSTALLER_CONTENT``
 239   .. versionadded:: 3.23
 240
 241   This contains all the XML elements that specify installer-wide options
 242   (including domain details), default backgrounds and the choices outline.
 243
 244 ``CPACK_PACKAGEMAKER_CHOICES``
 245   .. deprecated:: 3.23
 246
 247   This contains only the XML elements that specify the default backgrounds
 248   and the choices outline. It does not include the installer-wide options or
 249   any domain details. Use ``CPACK_APPLE_PKG_INSTALLER_CONTENT`` instead.