Help/cpack_gen/rpm.rst

   1 CPack RPM Generator
   2 -------------------
   3
   4 The built in (binary) CPack RPM generator (Unix only)
   5
   6 Variables specific to CPack RPM generator
   7 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   8
   9 The CPack RPM generator may be used to create RPM packages using :module:`CPack`.
  10 The CPack RPM generator is a :module:`CPack` generator thus it uses the
  11 ``CPACK_XXX`` variables used by :module:`CPack`.
  12
  13 The CPack RPM generator has specific features which are controlled by the specifics
  14 ``CPACK_RPM_XXX`` variables.
  15
  16 ``CPACK_RPM_<COMPONENT>_XXXX`` variables may be used in order to have
  17 **component** specific values.  Note however that ``<COMPONENT>`` refers to the
  18 **grouping name** written in upper case. It may be either a component name or
  19 a component GROUP name. Usually those variables correspond to RPM spec file
  20 entities. One may find information about spec files here
  21 https://rpm.org/documentation
  22
  23 .. versionchanged:: 3.6
  24
  25  `<COMPONENT>` part of variables is preferred to be in upper case (e.g. if
  26  component is named ``foo`` then use ``CPACK_RPM_FOO_XXXX`` variable name format)
  27  as is with other ``CPACK_<COMPONENT>_XXXX`` variables.
  28  For the purposes of back compatibility (CMake/CPack version 3.5 and lower)
  29  support for same cased component (e.g. ``fOo`` would be used as
  30  ``CPACK_RPM_fOo_XXXX``) is still supported for variables defined in older
  31  versions of CMake/CPack but is not guaranteed for variables that
  32  will be added in the future. For the sake of back compatibility same cased
  33  component variables also override upper cased versions where both are
  34  present.
  35
  36 Here are some CPack RPM generator wiki resources that are here for historic
  37 reasons and are no longer maintained but may still prove useful:
  38
  39  - https://gitlab.kitware.com/cmake/community/-/wikis/doc/cpack/Configuration
  40  - https://gitlab.kitware.com/cmake/community/-/wikis/doc/cpack/PackageGenerators#rpm-unix-only
  41
  42 List of CPack RPM generator specific variables:
  43
  44 .. variable:: CPACK_RPM_COMPONENT_INSTALL
  45
  46  Enable component packaging for CPack RPM generator
  47
  48  * Mandatory : NO
  49  * Default   : OFF
  50
  51  If enabled (``ON``) multiple packages are generated. By default
  52  a single package containing files of all components is generated.
  53
  54 .. variable:: CPACK_RPM_PACKAGE_SUMMARY
  55               CPACK_RPM_<component>_PACKAGE_SUMMARY
  56
  57  The RPM package summary.
  58
  59  * Mandatory : YES
  60  * Default   : :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY`
  61
  62  .. versionadded:: 3.2
  63   Per-component ``CPACK_RPM_<component>_PACKAGE_SUMMARY`` variables.
  64
  65 .. variable:: CPACK_RPM_PACKAGE_NAME
  66               CPACK_RPM_<component>_PACKAGE_NAME
  67
  68  The RPM package name.
  69
  70  * Mandatory : YES
  71  * Default   : :variable:`CPACK_PACKAGE_NAME`
  72
  73  .. versionadded:: 3.5
  74   Per-component ``CPACK_RPM_<component>_PACKAGE_NAME`` variables.
  75
  76 .. variable:: CPACK_RPM_FILE_NAME
  77               CPACK_RPM_<component>_FILE_NAME
  78
  79  .. versionadded:: 3.6
  80
  81  Package file name.
  82
  83  * Mandatory : YES
  84  * Default   : ``<CPACK_PACKAGE_FILE_NAME>[-<component>].rpm`` with spaces
  85                replaced by '-'
  86
  87  This may be set to ``RPM-DEFAULT`` to allow ``rpmbuild`` tool to generate package
  88  file name by itself.
  89  Alternatively provided package file name must end with ``.rpm`` suffix.
  90
  91  .. note::
  92
  93    By using user provided spec file, rpm macro extensions such as for
  94    generating ``debuginfo`` packages or by simply using multiple components more
  95    than one rpm file may be generated, either from a single spec file or from
  96    multiple spec files (each component execution produces its own spec file).
  97    In such cases duplicate file names may occur as a result of this variable
  98    setting or spec file content structure. Duplicate files get overwritten
  99    and it is up to the packager to set the variables in a manner that will
 100    prevent such errors.
 101
 102 .. variable:: CPACK_RPM_MAIN_COMPONENT
 103
 104  .. versionadded:: 3.8
 105
 106  Main component that is packaged without component suffix.
 107
 108  * Mandatory : NO
 109  * Default   : -
 110
 111  This variable can be set to any component or group name so that component or
 112  group rpm package is generated without component suffix in filename and
 113  package name.
 114
 115 .. variable:: CPACK_RPM_PACKAGE_EPOCH
 116
 117  .. versionadded:: 3.10
 118
 119  The RPM package epoch
 120
 121  * Mandatory : No
 122  * Default   : -
 123
 124  Optional number that should be incremented when changing versioning schemas
 125  or fixing mistakes in the version numbers of older packages.
 126
 127 .. variable:: CPACK_RPM_PACKAGE_VERSION
 128
 129  The RPM package version.
 130
 131  * Mandatory : YES
 132  * Default   : :variable:`CPACK_PACKAGE_VERSION`
 133
 134 .. variable:: CPACK_RPM_PACKAGE_ARCHITECTURE
 135               CPACK_RPM_<component>_PACKAGE_ARCHITECTURE
 136
 137  The RPM package architecture.
 138
 139  * Mandatory : YES
 140  * Default   : Native architecture output by ``uname -m``
 141
 142  This may be set to ``noarch`` if you know you are building a ``noarch`` package.
 143
 144  .. versionadded:: 3.3
 145   Per-component ``CPACK_RPM_<component>_PACKAGE_ARCHITECTURE`` variables.
 146
 147 .. variable:: CPACK_RPM_PACKAGE_RELEASE
 148
 149  The RPM package release.
 150
 151  * Mandatory : YES
 152  * Default   : 1
 153
 154  This is the numbering of the RPM package itself, i.e. the version of the
 155  packaging and not the version of the content (see
 156  :variable:`CPACK_RPM_PACKAGE_VERSION`). One may change the default value if
 157  the previous packaging was buggy and/or you want to put here a fancy Linux
 158  distro specific numbering.
 159
 160 .. note::
 161
 162  This is the string that goes into the RPM ``Release:`` field. Some distros
 163  (e.g. Fedora, CentOS) require ``1%{?dist}`` format and not just a number.
 164  ``%{?dist}`` part can be added by setting :variable:`CPACK_RPM_PACKAGE_RELEASE_DIST`.
 165
 166 .. variable:: CPACK_RPM_PACKAGE_RELEASE_DIST
 167
 168  .. versionadded:: 3.6
 169
 170  The dist tag that is added  RPM ``Release:`` field.
 171
 172  * Mandatory : NO
 173  * Default   : OFF
 174
 175  This is the reported ``%{dist}`` tag from the current distribution or empty
 176  ``%{dist}`` if RPM macro is not set. If this variable is set then RPM
 177  ``Release:`` field value is set to ``${CPACK_RPM_PACKAGE_RELEASE}%{?dist}``.
 178
 179 .. variable:: CPACK_RPM_PACKAGE_LICENSE
 180
 181  The RPM package license policy.
 182
 183  * Mandatory : YES
 184  * Default   : "unknown"
 185
 186 .. variable:: CPACK_RPM_PACKAGE_GROUP
 187               CPACK_RPM_<component>_PACKAGE_GROUP
 188
 189  The RPM package group.
 190
 191  * Mandatory : YES
 192  * Default   : "unknown"
 193
 194  .. versionadded:: 3.5
 195   Per-component ``CPACK_RPM_<component>_PACKAGE_GROUP`` variables.
 196
 197 .. variable:: CPACK_RPM_PACKAGE_VENDOR
 198
 199  The RPM package vendor.
 200
 201  * Mandatory : YES
 202  * Default   : CPACK_PACKAGE_VENDOR if set or "unknown"
 203
 204 .. variable:: CPACK_RPM_PACKAGE_URL
 205               CPACK_RPM_<component>_PACKAGE_URL
 206
 207  The projects URL.
 208
 209  * Mandatory : NO
 210  * Default   : :variable:`CMAKE_PROJECT_HOMEPAGE_URL`
 211
 212  .. versionadded:: 3.12
 213   The ``CMAKE_PROJECT_HOMEPAGE_URL`` variable.
 214
 215 .. variable:: CPACK_RPM_PACKAGE_DESCRIPTION
 216               CPACK_RPM_<component>_PACKAGE_DESCRIPTION
 217
 218  RPM package description.
 219
 220  * Mandatory : YES
 221  * Default : :variable:`CPACK_COMPONENT_<compName>_DESCRIPTION` (component
 222    based installers only) if set, :variable:`CPACK_PACKAGE_DESCRIPTION_FILE`
 223    if set or "no package description available"
 224
 225  .. versionadded:: 3.2
 226   Per-component ``CPACK_RPM_<component>_PACKAGE_DESCRIPTION`` variables.
 227
 228 .. variable:: CPACK_RPM_COMPRESSION_TYPE
 229
 230  RPM compression type.
 231
 232  * Mandatory : NO
 233  * Default   : -
 234
 235  May be used to override RPM compression type to be used to build the
 236  RPM. For example some Linux distribution now default to ``lzma`` or ``xz``
 237  compression whereas older cannot use such RPM. Using this one can enforce
 238  compression type to be used.
 239
 240  Possible values are:
 241
 242  - lzma
 243  - xz
 244  - bzip2
 245  - gzip
 246
 247 .. variable:: CPACK_RPM_PACKAGE_AUTOREQ
 248               CPACK_RPM_<component>_PACKAGE_AUTOREQ
 249
 250  RPM spec autoreq field.
 251
 252  * Mandatory : NO
 253  * Default   : -
 254
 255  May be used to enable (``1``, ``yes``) or disable (``0``, ``no``) automatic
 256  shared libraries dependency detection. Dependencies are added to requires list.
 257
 258  .. note::
 259
 260    By default automatic dependency detection is enabled by rpm generator.
 261
 262 .. variable:: CPACK_RPM_PACKAGE_AUTOPROV
 263               CPACK_RPM_<component>_PACKAGE_AUTOPROV
 264
 265  RPM spec autoprov field.
 266
 267  * Mandatory : NO
 268  * Default   : -
 269
 270  May be used to enable (``1``, ``yes``) or disable (``0``, ``no``)
 271  automatic listing of shared libraries that are provided by the package.
 272  Shared libraries are added to provides list.
 273
 274  .. note::
 275
 276    By default automatic provides detection is enabled by rpm generator.
 277
 278 .. variable:: CPACK_RPM_PACKAGE_AUTOREQPROV
 279               CPACK_RPM_<component>_PACKAGE_AUTOREQPROV
 280
 281  RPM spec autoreqprov field.
 282
 283  * Mandatory : NO
 284  * Default   : -
 285
 286  Variable enables/disables autoreq and autoprov at the same time.
 287  See :variable:`CPACK_RPM_PACKAGE_AUTOREQ` and
 288  :variable:`CPACK_RPM_PACKAGE_AUTOPROV` for more details.
 289
 290  .. note::
 291
 292    By default automatic detection feature is enabled by rpm.
 293
 294 .. variable:: CPACK_RPM_PACKAGE_REQUIRES
 295               CPACK_RPM_<component>_PACKAGE_REQUIRES
 296
 297  RPM spec requires field.
 298
 299  * Mandatory : NO
 300  * Default   : -
 301
 302  May be used to set RPM dependencies (requires). Note that you must enclose
 303  the complete requires string between quotes, for example::
 304
 305   set(CPACK_RPM_PACKAGE_REQUIRES "python >= 2.5.0, cmake >= 2.8")
 306
 307  The required package list of an RPM file could be printed with::
 308
 309   rpm -qp --requires file.rpm
 310
 311 .. variable:: CPACK_RPM_PACKAGE_CONFLICTS
 312               CPACK_RPM_<component>_PACKAGE_CONFLICTS
 313
 314  RPM spec conflicts field.
 315
 316  * Mandatory : NO
 317  * Default   : -
 318
 319  May be used to set negative RPM dependencies (conflicts). Note that you must
 320  enclose the complete requires string between quotes, for example::
 321
 322   set(CPACK_RPM_PACKAGE_CONFLICTS "libxml2")
 323
 324  The conflicting package list of an RPM file could be printed with::
 325
 326   rpm -qp --conflicts file.rpm
 327
 328 .. variable:: CPACK_RPM_PACKAGE_REQUIRES_PRE
 329               CPACK_RPM_<component>_PACKAGE_REQUIRES_PRE
 330
 331  .. versionadded:: 3.2
 332
 333  RPM spec requires(pre) field.
 334
 335  * Mandatory : NO
 336  * Default   : -
 337
 338  May be used to set RPM preinstall dependencies (requires(pre)). Note that
 339  you must enclose the complete requires string between quotes, for example::
 340
 341   set(CPACK_RPM_PACKAGE_REQUIRES_PRE "shadow-utils, initscripts")
 342
 343 .. variable:: CPACK_RPM_PACKAGE_REQUIRES_POST
 344               CPACK_RPM_<component>_PACKAGE_REQUIRES_POST
 345
 346  .. versionadded:: 3.2
 347
 348  RPM spec requires(post) field.
 349
 350  * Mandatory : NO
 351  * Default   : -
 352
 353  May be used to set RPM postinstall dependencies (requires(post)). Note that
 354  you must enclose the complete requires string between quotes, for example::
 355
 356   set(CPACK_RPM_PACKAGE_REQUIRES_POST "shadow-utils, initscripts")
 357
 358 .. variable:: CPACK_RPM_PACKAGE_REQUIRES_POSTUN
 359               CPACK_RPM_<component>_PACKAGE_REQUIRES_POSTUN
 360
 361  .. versionadded:: 3.2
 362
 363  RPM spec requires(postun) field.
 364
 365  * Mandatory : NO
 366  * Default   : -
 367
 368  May be used to set RPM postuninstall dependencies (requires(postun)). Note
 369  that you must enclose the complete requires string between quotes, for
 370  example::
 371
 372   set(CPACK_RPM_PACKAGE_REQUIRES_POSTUN "shadow-utils, initscripts")
 373
 374 .. variable:: CPACK_RPM_PACKAGE_REQUIRES_PREUN
 375               CPACK_RPM_<component>_PACKAGE_REQUIRES_PREUN
 376
 377  .. versionadded:: 3.2
 378
 379  RPM spec requires(preun) field.
 380
 381  * Mandatory : NO
 382  * Default   : -
 383
 384  May be used to set RPM preuninstall dependencies (requires(preun)). Note that
 385  you must enclose the complete requires string between quotes, for example::
 386
 387   set(CPACK_RPM_PACKAGE_REQUIRES_PREUN "shadow-utils, initscripts")
 388
 389 .. variable:: CPACK_RPM_PACKAGE_SUGGESTS
 390               CPACK_RPM_<component>_PACKAGE_SUGGESTS
 391
 392  RPM spec suggest field.
 393
 394  * Mandatory : NO
 395  * Default   : -
 396
 397  May be used to set weak RPM dependencies (suggests). If ``rpmbuild`` doesn't
 398  support the ``Suggests`` tag, CPack will emit a warning and ignore this
 399  variable. Note that you must enclose the complete requires string between
 400  quotes.
 401
 402 .. variable:: CPACK_RPM_PACKAGE_PROVIDES
 403               CPACK_RPM_<component>_PACKAGE_PROVIDES
 404
 405  RPM spec provides field.
 406
 407  * Mandatory : NO
 408  * Default   : -
 409
 410  May be used to set RPM dependencies (provides). The provided package list
 411  of an RPM file could be printed with::
 412
 413   rpm -qp --provides file.rpm
 414
 415 .. variable:: CPACK_RPM_PACKAGE_OBSOLETES
 416               CPACK_RPM_<component>_PACKAGE_OBSOLETES
 417
 418  RPM spec obsoletes field.
 419
 420  * Mandatory : NO
 421  * Default   : -
 422
 423  May be used to set RPM packages that are obsoleted by this one.
 424
 425 .. variable:: CPACK_RPM_PACKAGE_RELOCATABLE
 426
 427  build a relocatable RPM.
 428
 429  * Mandatory : NO
 430  * Default   : CPACK_PACKAGE_RELOCATABLE
 431
 432  If this variable is set to TRUE or ON, the CPack RPM generator will try
 433  to build a relocatable RPM package. A relocatable RPM may
 434  be installed using::
 435
 436   rpm --prefix or --relocate
 437
 438  in order to install it at an alternate place see rpm(8). Note that
 439  currently this may fail if :variable:`CPACK_SET_DESTDIR` is set to ``ON``. If
 440  :variable:`CPACK_SET_DESTDIR` is set then you will get a warning message but
 441  if there is file installed with absolute path you'll get unexpected behavior.
 442
 443 .. variable:: CPACK_RPM_SPEC_INSTALL_POST
 444
 445  Deprecated - use :variable:`CPACK_RPM_SPEC_MORE_DEFINE` instead.
 446
 447  * Mandatory : NO
 448  * Default   : -
 449  * Deprecated: YES
 450
 451  May be used to override the ``__spec_install_post`` section within the
 452  generated spec file.  This affects the install step during package creation,
 453  not during package installation.  For adding operations to be performed
 454  during package installation, use
 455  :variable:`CPACK_RPM_POST_INSTALL_SCRIPT_FILE` instead.
 456
 457 .. variable:: CPACK_RPM_SPEC_MORE_DEFINE
 458
 459  RPM extended spec definitions lines.
 460
 461  * Mandatory : NO
 462  * Default   : -
 463
 464  May be used to add any ``%define`` lines to the generated spec file.  An
 465  example of its use is to prevent stripping of executables (but note that
 466  this may also disable other default post install processing)::
 467
 468    set(CPACK_RPM_SPEC_MORE_DEFINE "%define __spec_install_post /bin/true")
 469
 470 .. variable:: CPACK_RPM_PACKAGE_DEBUG
 471
 472  Toggle CPack RPM generator debug output.
 473
 474  * Mandatory : NO
 475  * Default   : -
 476
 477  May be set when invoking cpack in order to trace debug information
 478  during CPack RPM run. For example you may launch CPack like this::
 479
 480   cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -G RPM
 481
 482 .. variable:: CPACK_RPM_USER_BINARY_SPECFILE
 483               CPACK_RPM_<componentName>_USER_BINARY_SPECFILE
 484
 485  A user provided spec file.
 486
 487  * Mandatory : NO
 488  * Default   : -
 489
 490  May be set by the user in order to specify a USER binary spec file
 491  to be used by the CPack RPM generator instead of generating the file.
 492  The specified file will be processed by configure_file( @ONLY).
 493
 494 .. variable:: CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE
 495
 496  Spec file template.
 497
 498  * Mandatory : NO
 499  * Default   : -
 500
 501  If set CPack will generate a template for USER specified binary
 502  spec file and stop with an error. For example launch CPack like this::
 503
 504   cpack -D CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE=1 -G RPM
 505
 506  The user may then use this file in order to hand-craft is own
 507  binary spec file which may be used with
 508  :variable:`CPACK_RPM_USER_BINARY_SPECFILE`.
 509
 510 .. variable:: CPACK_RPM_PRE_INSTALL_SCRIPT_FILE
 511               CPACK_RPM_PRE_UNINSTALL_SCRIPT_FILE
 512               CPACK_RPM_PRE_TRANS_SCRIPT_FILE
 513
 514  Path to file containing pre install/uninstall/transaction script.
 515
 516  * Mandatory : NO
 517  * Default   : -
 518
 519  May be used to embed a pre installation/uninstallation/transaction script in the spec file.
 520  The referred script file (or both) will be read and directly
 521  put after the ``%pre`` or ``%preun`` section
 522  If :variable:`CPACK_RPM_COMPONENT_INSTALL` is set to ON the install/uninstall/transaction
 523  script for each component can be overridden with
 524  ``CPACK_RPM_<COMPONENT>_PRE_INSTALL_SCRIPT_FILE``,
 525  ``CPACK_RPM_<COMPONENT>_PRE_UNINSTALL_SCRIPT_FILE``, and
 526  ``CPACK_RPM_<COMPONENT>_PRE_TRANS_SCRIPT_FILE``
 527  One may verify which scriptlet has been included with::
 528
 529   rpm -qp --scripts  package.rpm
 530
 531  .. versionadded:: 3.18
 532   The ``CPACK_RPM_PRE_TRANS_SCRIPT_FILE`` variable.
 533
 534 .. variable:: CPACK_RPM_POST_INSTALL_SCRIPT_FILE
 535               CPACK_RPM_POST_UNINSTALL_SCRIPT_FILE
 536               CPACK_RPM_POST_TRANS_SCRIPT_FILE
 537
 538  Path to file containing post install/uninstall/transaction script.
 539
 540  * Mandatory : NO
 541  * Default   : -
 542
 543  May be used to embed a post installation/uninstallation/transaction script in the spec file.
 544  The referred script file (or both) will be read and directly
 545  put after the ``%post`` or ``%postun`` section.
 546  If :variable:`CPACK_RPM_COMPONENT_INSTALL` is set to ON the install/uninstall/transaction
 547  script for each component can be overridden with
 548  ``CPACK_RPM_<COMPONENT>_POST_INSTALL_SCRIPT_FILE``,
 549  ``CPACK_RPM_<COMPONENT>_POST_UNINSTALL_SCRIPT_FILE``, and
 550  ``CPACK_RPM_<COMPONENT>_POST_TRANS_SCRIPT_FILE``
 551  One may verify which scriptlet has been included with::
 552
 553   rpm -qp --scripts  package.rpm
 554
 555  .. versionadded:: 3.18
 556   The ``CPACK_RPM_POST_TRANS_SCRIPT_FILE`` variable.
 557
 558 .. variable:: CPACK_RPM_USER_FILELIST
 559               CPACK_RPM_<COMPONENT>_USER_FILELIST
 560
 561  * Mandatory : NO
 562  * Default   : -
 563
 564  May be used to explicitly specify ``%(<directive>)`` file line
 565  in the spec file. Like ``%config(noreplace)`` or any other directive
 566  that be found in the ``%files`` section. Since
 567  the CPack RPM generator is generating the list of files (and directories) the
 568  user specified files of the ``CPACK_RPM_<COMPONENT>_USER_FILELIST`` list will
 569  be removed from the generated list. If referring to directories do
 570  not add a trailing slash.
 571
 572  .. versionadded:: 3.8
 573   You can have multiple directives per line, as in
 574   ``%attr(600,root,root) %config(noreplace)``.
 575
 576 .. variable:: CPACK_RPM_CHANGELOG_FILE
 577
 578  RPM changelog file.
 579
 580  * Mandatory : NO
 581  * Default   : -
 582
 583  May be used to embed a changelog in the spec file.
 584  The referred file will be read and directly put after the ``%changelog``
 585  section.
 586
 587 .. variable:: CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST
 588
 589  list of path to be excluded.
 590
 591  * Mandatory : NO
 592  * Default   : /etc /etc/init.d /usr /usr/bin /usr/include /usr/lib
 593                /usr/libx32 /usr/lib64 /usr/share /usr/share/aclocal
 594                /usr/share/doc
 595
 596  May be used to exclude path (directories or files) from the auto-generated
 597  list of paths discovered by CPack RPM. The default value contains a
 598  reasonable set of values if the variable is not defined by the user. If the
 599  variable is defined by the user then the CPack RPM generator will NOT any of
 600  the default path. If you want to add some path to the default list then you
 601  can use :variable:`CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST_ADDITION` variable.
 602
 603  .. versionadded:: 3.10
 604   Added ``/usr/share/aclocal`` to the default list of excludes.
 605
 606 .. variable:: CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST_ADDITION
 607
 608  additional list of path to be excluded.
 609
 610  * Mandatory : NO
 611  * Default   : -
 612
 613  May be used to add more exclude path (directories or files) from the initial
 614  default list of excluded paths. See
 615  :variable:`CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST`.
 616
 617 .. variable:: CPACK_RPM_RELOCATION_PATHS
 618
 619  .. versionadded:: 3.2
 620
 621  Packages relocation paths list.
 622
 623  * Mandatory : NO
 624  * Default   : -
 625
 626  May be used to specify more than one relocation path per relocatable RPM.
 627  Variable contains a list of relocation paths that if relative are prefixed
 628  by the value of :variable:`CPACK_RPM_<COMPONENT>_PACKAGE_PREFIX` or by the
 629  value of :variable:`CPACK_PACKAGING_INSTALL_PREFIX` if the component version
 630  is not provided.
 631  Variable is not component based as its content can be used to set a different
 632  path prefix for e.g. binary dir and documentation dir at the same time.
 633  Only prefixes that are required by a certain component are added to that
 634  component - component must contain at least one file/directory/symbolic link
 635  with :variable:`CPACK_RPM_RELOCATION_PATHS` prefix for a certain relocation
 636  path to be added. Package will not contain any relocation paths if there are
 637  no files/directories/symbolic links on any of the provided prefix locations.
 638  Packages that either do not contain any relocation paths or contain
 639  files/directories/symbolic links that are outside relocation paths print
 640  out an ``AUTHOR_WARNING`` that RPM will be partially relocatable.
 641
 642 .. variable:: CPACK_RPM_<COMPONENT>_PACKAGE_PREFIX
 643
 644  .. versionadded:: 3.2
 645
 646  Per component relocation path install prefix.
 647
 648  * Mandatory : NO
 649  * Default   : CPACK_PACKAGING_INSTALL_PREFIX
 650
 651  May be used to set per component :variable:`CPACK_PACKAGING_INSTALL_PREFIX`
 652  for relocatable RPM packages.
 653
 654 .. variable:: CPACK_RPM_NO_INSTALL_PREFIX_RELOCATION
 655               CPACK_RPM_NO_<COMPONENT>_INSTALL_PREFIX_RELOCATION
 656
 657  .. versionadded:: 3.3
 658
 659  Removal of default install prefix from relocation paths list.
 660
 661  * Mandatory : NO
 662  * Default   : CPACK_PACKAGING_INSTALL_PREFIX or CPACK_RPM_<COMPONENT>_PACKAGE_PREFIX
 663                are treated as one of relocation paths
 664
 665  May be used to remove CPACK_PACKAGING_INSTALL_PREFIX and CPACK_RPM_<COMPONENT>_PACKAGE_PREFIX
 666  from relocatable RPM prefix paths.
 667
 668 .. variable:: CPACK_RPM_ADDITIONAL_MAN_DIRS
 669
 670  .. versionadded:: 3.3
 671
 672  * Mandatory : NO
 673  * Default   : -
 674
 675  May be used to set additional man dirs that could potentially be compressed
 676  by brp-compress RPM macro. Variable content must be a list of regular
 677  expressions that point to directories containing man files or to man files
 678  directly. Note that in order to compress man pages a path must also be
 679  present in brp-compress RPM script and that brp-compress script must be
 680  added to RPM configuration by the operating system.
 681
 682  Regular expressions that are added by default were taken from brp-compress
 683  RPM macro:
 684
 685  - /usr/man/man.*
 686  - /usr/man/.*/man.*
 687  - /usr/info.*
 688  - /usr/share/man/man.*
 689  - /usr/share/man/.*/man.*
 690  - /usr/share/info.*
 691  - /usr/kerberos/man.*
 692  - /usr/X11R6/man/man.*
 693  - /usr/lib/perl5/man/man.*
 694  - /usr/share/doc/.*/man/man.*
 695  - /usr/lib/.*/man/man.*
 696
 697 .. variable:: CPACK_RPM_DEFAULT_USER
 698               CPACK_RPM_<compName>_DEFAULT_USER
 699
 700  .. versionadded:: 3.6
 701
 702  default user ownership of RPM content
 703
 704  * Mandatory : NO
 705  * Default   : root
 706
 707  Value should be user name and not UID.
 708  Note that <compName> must be in upper-case.
 709
 710 .. variable:: CPACK_RPM_DEFAULT_GROUP
 711               CPACK_RPM_<compName>_DEFAULT_GROUP
 712
 713  .. versionadded:: 3.6
 714
 715  default group ownership of RPM content
 716
 717  * Mandatory : NO
 718  * Default   : root
 719
 720  Value should be group name and not GID.
 721  Note that <compName> must be in upper-case.
 722
 723 .. variable:: CPACK_RPM_DEFAULT_FILE_PERMISSIONS
 724               CPACK_RPM_<compName>_DEFAULT_FILE_PERMISSIONS
 725
 726  .. versionadded:: 3.6
 727
 728  default permissions used for packaged files
 729
 730  * Mandatory : NO
 731  * Default   : - (system default)
 732
 733  Accepted values are lists with ``PERMISSIONS``. Valid permissions
 734  are:
 735
 736  - OWNER_READ
 737  - OWNER_WRITE
 738  - OWNER_EXECUTE
 739  - GROUP_READ
 740  - GROUP_WRITE
 741  - GROUP_EXECUTE
 742  - WORLD_READ
 743  - WORLD_WRITE
 744  - WORLD_EXECUTE
 745
 746  Note that <compName> must be in upper-case.
 747
 748 .. variable:: CPACK_RPM_DEFAULT_DIR_PERMISSIONS
 749               CPACK_RPM_<compName>_DEFAULT_DIR_PERMISSIONS
 750
 751  .. versionadded:: 3.6
 752
 753  default permissions used for packaged directories
 754
 755  * Mandatory : NO
 756  * Default   : - (system default)
 757
 758  Accepted values are lists with PERMISSIONS. Valid permissions
 759  are the same as for :variable:`CPACK_RPM_DEFAULT_FILE_PERMISSIONS`.
 760  Note that <compName> must be in upper-case.
 761
 762 .. variable:: CPACK_RPM_INSTALL_WITH_EXEC
 763
 764  .. versionadded:: 3.11
 765
 766  force execute permissions on programs and shared libraries
 767
 768  * Mandatory : NO
 769  * Default   : - (system default)
 770
 771  Force set owner, group and world execute permissions on programs and shared
 772  libraries. This can be used for creating valid rpm packages on systems such
 773  as Debian where shared libraries do not have execute permissions set.
 774
 775 .. note::
 776
 777  Programs and shared libraries without execute permissions are ignored during
 778  separation of debug symbols from the binary for debuginfo packages.
 779
 780 Packaging of Symbolic Links
 781 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 782
 783 .. versionadded:: 3.3
 784
 785 The CPack RPM generator supports packaging of symbolic links::
 786
 787   execute_process(COMMAND ${CMAKE_COMMAND}
 788     -E create_symlink <relative_path_location> <symlink_name>)
 789   install(FILES ${CMAKE_CURRENT_BINARY_DIR}/<symlink_name>
 790     DESTINATION <symlink_location> COMPONENT libraries)
 791
 792 Symbolic links will be optimized (paths will be shortened if possible)
 793 before being added to the package or if multiple relocation paths are
 794 detected, a post install symlink relocation script will be generated.
 795
 796 Symbolic links may point to locations that are not packaged by the same
 797 package (either a different component or even not packaged at all) but
 798 those locations will be treated as if they were a part of the package
 799 while determining if symlink should be either created or present in a
 800 post install script - depending on relocation paths.
 801
 802 .. versionchanged:: 3.6
 803  Symbolic links that point to locations outside packaging path produce a
 804  warning and are treated as non relocatable permanent symbolic links.
 805  Previous versions of CMake produced an error in this case.
 806
 807 Currently there are a few limitations though:
 808
 809 * For component based packaging component interdependency is not checked
 810   when processing symbolic links. Symbolic links pointing to content of
 811   a different component are treated the same way as if pointing to location
 812   that will not be packaged.
 813
 814 * Symbolic links pointing to a location through one or more intermediate
 815   symbolic links will not be handled differently - if the intermediate
 816   symbolic link(s) is also on a relocatable path, relocating it during
 817   package installation may cause initial symbolic link to point to an
 818   invalid location.
 819
 820 Packaging of debug information
 821 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 822
 823 .. versionadded:: 3.7
 824
 825 Debuginfo packages contain debug symbols and sources for debugging packaged
 826 binaries.
 827
 828 Debuginfo RPM packaging has its own set of variables:
 829
 830 .. variable:: CPACK_RPM_DEBUGINFO_PACKAGE
 831               CPACK_RPM_<component>_DEBUGINFO_PACKAGE
 832
 833  Enable generation of debuginfo RPM package(s).
 834
 835  * Mandatory : NO
 836  * Default   : OFF
 837
 838 .. note::
 839
 840  Binaries must contain debug symbols before packaging so use either ``Debug``
 841  or ``RelWithDebInfo`` for :variable:`CMAKE_BUILD_TYPE` variable value.
 842
 843  Additionally, if :variable:`CPACK_STRIP_FILES` is set, the files will be stripped before
 844  they get to the RPM generator, so will not contain debug symbols and
 845  a debuginfo package will not get built. Do not use with :variable:`CPACK_STRIP_FILES`.
 846
 847 .. note::
 848
 849  Packages generated from packages without binary files, with binary files but
 850  without execute permissions or without debug symbols will cause packaging
 851  termination.
 852
 853 .. variable:: CPACK_BUILD_SOURCE_DIRS
 854
 855  Provides locations of root directories of source files from which binaries
 856  were built.
 857
 858  * Mandatory : YES if :variable:`CPACK_RPM_DEBUGINFO_PACKAGE` is set
 859  * Default   : -
 860
 861 .. note::
 862
 863  For CMake project :variable:`CPACK_BUILD_SOURCE_DIRS` is set by default to
 864  point to :variable:`CMAKE_SOURCE_DIR` and :variable:`CMAKE_BINARY_DIR` paths.
 865
 866 .. note::
 867
 868  Sources with path prefixes that do not fall under any location provided with
 869  :variable:`CPACK_BUILD_SOURCE_DIRS` will not be present in debuginfo package.
 870
 871 .. variable:: CPACK_RPM_BUILD_SOURCE_DIRS_PREFIX
 872               CPACK_RPM_<component>_BUILD_SOURCE_DIRS_PREFIX
 873
 874  Prefix of location where sources will be placed during package installation.
 875
 876  * Mandatory : YES if :variable:`CPACK_RPM_DEBUGINFO_PACKAGE` is set
 877  * Default   : "/usr/src/debug/<CPACK_PACKAGE_FILE_NAME>" and
 878                for component packaging "/usr/src/debug/<CPACK_PACKAGE_FILE_NAME>-<component>"
 879
 880 .. note::
 881
 882  Each source path prefix is additionally suffixed by ``src_<index>`` where
 883  index is index of the path used from :variable:`CPACK_BUILD_SOURCE_DIRS`
 884  variable. This produces ``<CPACK_RPM_BUILD_SOURCE_DIRS_PREFIX>/src_<index>``
 885  replacement path.
 886  Limitation is that replaced path part must be shorter or of equal
 887  length than the length of its replacement. If that is not the case either
 888  :variable:`CPACK_RPM_BUILD_SOURCE_DIRS_PREFIX` variable has to be set to
 889  a shorter path or source directories must be placed on a longer path.
 890
 891 .. variable:: CPACK_RPM_DEBUGINFO_EXCLUDE_DIRS
 892
 893  Directories containing sources that should be excluded from debuginfo packages.
 894
 895  * Mandatory : NO
 896  * Default   : "/usr /usr/src /usr/src/debug"
 897
 898  Listed paths are owned by other RPM packages and should therefore not be
 899  deleted on debuginfo package uninstallation.
 900
 901 .. variable:: CPACK_RPM_DEBUGINFO_EXCLUDE_DIRS_ADDITION
 902
 903  Paths that should be appended to :variable:`CPACK_RPM_DEBUGINFO_EXCLUDE_DIRS`
 904  for exclusion.
 905
 906  * Mandatory : NO
 907  * Default   : -
 908
 909 .. variable:: CPACK_RPM_DEBUGINFO_SINGLE_PACKAGE
 910
 911  .. versionadded:: 3.8
 912
 913  Create a single debuginfo package even if components packaging is set.
 914
 915  * Mandatory : NO
 916  * Default   : OFF
 917
 918  When this variable is enabled it produces a single debuginfo package even if
 919  component packaging is enabled.
 920
 921  When using this feature in combination with components packaging and there is
 922  more than one component this variable requires :variable:`CPACK_RPM_MAIN_COMPONENT`
 923  to be set.
 924
 925 .. note::
 926
 927  If none of the :variable:`CPACK_RPM_<component>_DEBUGINFO_PACKAGE` variables
 928  is set then :variable:`CPACK_RPM_DEBUGINFO_PACKAGE` is automatically set to
 929  ``ON`` when :variable:`CPACK_RPM_DEBUGINFO_SINGLE_PACKAGE` is set.
 930
 931 .. variable:: CPACK_RPM_DEBUGINFO_FILE_NAME
 932               CPACK_RPM_<component>_DEBUGINFO_FILE_NAME
 933
 934  .. versionadded:: 3.9
 935
 936  Debuginfo package file name.
 937
 938  * Mandatory : NO
 939  * Default   : rpmbuild tool generated package file name
 940
 941  Alternatively provided debuginfo package file name must end with ``.rpm``
 942  suffix and should differ from file names of other generated packages.
 943
 944  Variable may contain ``@cpack_component@`` placeholder which will be
 945  replaced by component name if component packaging is enabled otherwise it
 946  deletes the placeholder.
 947
 948  Setting the variable to ``RPM-DEFAULT`` may be used to explicitly set
 949  filename generation to default.
 950
 951 .. note::
 952
 953  :variable:`CPACK_RPM_FILE_NAME` also supports rpmbuild tool generated package
 954  file name - disabled by default but can be enabled by setting the variable to
 955  ``RPM-DEFAULT``.
 956
 957 Packaging of sources (SRPM)
 958 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 959
 960 .. versionadded:: 3.7
 961
 962 SRPM packaging is enabled by setting :variable:`CPACK_RPM_PACKAGE_SOURCES`
 963 variable while usually using :variable:`CPACK_INSTALLED_DIRECTORIES` variable
 964 to provide directory containing CMakeLists.txt and source files.
 965
 966 For CMake projects SRPM package would be produced by executing::
 967
 968   cpack -G RPM --config ./CPackSourceConfig.cmake
 969
 970 .. note::
 971
 972  Produced SRPM package is expected to be built with :manual:`cmake(1)` executable
 973  and packaged with :manual:`cpack(1)` executable so CMakeLists.txt has to be
 974  located in root source directory and must be able to generate binary rpm
 975  packages by executing :option:`cpack -G` command. The two executables as well as
 976  rpmbuild must also be present when generating binary rpm packages from the
 977  produced SRPM package.
 978
 979 Once the SRPM package is generated it can be used to generate binary packages
 980 by creating a directory structure for rpm generation and executing rpmbuild
 981 tool::
 982
 983   mkdir -p build_dir/{BUILD,BUILDROOT,RPMS,SOURCES,SPECS,SRPMS}
 984   rpmbuild --define "_topdir <path_to_build_dir>" --rebuild <SRPM_file_name>
 985
 986 Generated packages will be located in build_dir/RPMS directory or its sub
 987 directories.
 988
 989 .. note::
 990
 991  SRPM package internally uses CPack/RPM generator to generate binary packages
 992  so CMakeScripts.txt can decide during the SRPM to binary rpm generation step
 993  what content the package(s) should have as well as how they should be packaged
 994  (monolithic or components). CMake can decide this for e.g. by reading environment
 995  variables set by the package manager before starting the process of generating
 996  binary rpm packages. This way a single SRPM package can be used to produce
 997  different binary rpm packages on different platforms depending on the platform's
 998  packaging rules.
 999
1000 Source RPM packaging has its own set of variables:
1001
1002 .. variable:: CPACK_RPM_PACKAGE_SOURCES
1003
1004  Should the content be packaged as a source rpm (default is binary rpm).
1005
1006  * Mandatory : NO
1007  * Default   : OFF
1008
1009 .. note::
1010
1011  For cmake projects :variable:`CPACK_RPM_PACKAGE_SOURCES` variable is set
1012  to ``OFF`` in CPackConfig.cmake and ``ON`` in CPackSourceConfig.cmake
1013  generated files.
1014
1015 .. variable:: CPACK_RPM_SOURCE_PKG_BUILD_PARAMS
1016
1017  Additional command-line parameters provided to :manual:`cmake(1)` executable.
1018
1019  * Mandatory : NO
1020  * Default   : -
1021
1022 .. variable:: CPACK_RPM_SOURCE_PKG_PACKAGING_INSTALL_PREFIX
1023
1024  Packaging install prefix that would be provided in :variable:`CPACK_PACKAGING_INSTALL_PREFIX`
1025  variable for producing binary RPM packages.
1026
1027  * Mandatory : YES
1028  * Default   : "/"
1029
1030 .. variable:: CPACK_RPM_BUILDREQUIRES
1031
1032  List of source rpm build dependencies.
1033
1034  * Mandatory : NO
1035  * Default   : -
1036
1037  May be used to set source RPM build dependencies (BuildRequires). Note that
1038  you must enclose the complete build requirements string between quotes, for
1039  example::
1040
1041   set(CPACK_RPM_BUILDREQUIRES "python >= 2.5.0, cmake >= 2.8")
1042
1043 .. variable:: CPACK_RPM_REQUIRES_EXCLUDE_FROM
1044
1045  .. versionadded:: 3.22
1046
1047  * Mandatory : NO
1048  * Default   : -
1049
1050  May be used to keep the dependency generator from scanning specific files
1051  or directories for dependencies.  Note that you can use a regular
1052  expression that matches all of the directories or files, for example::
1053
1054   set(CPACK_RPM_REQUIRES_EXCLUDE_FROM "bin/libqsqloci.*\\.so.*")