Lubuntu/cmake
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge branch 'experimental'

Browse Source
This commit is contained in:
Felix Geyer 2018-11-29 20:25:38 +01:00
commit 3cf5a2808e
1416 changed files with 32123 additions and 16838 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Auxiliary/cmake-mode.el
View File

@ -55,7 +55,7 @@ set the path with these commands:
(* (or (not (any space "()#\\\n")) (and ?\\ nonl)))))
(defconst cmake-regex-token
(rx-to-string `(group (or (regexp ,cmake-regex-comment)
?( ?)
?\( ?\)
(regexp ,cmake-regex-argument-unquoted)
(regexp ,cmake-regex-argument-quoted)))))
(defconst cmake-regex-indented

35
Auxiliary/vim/cmake.vim.in
View File

@ -19,8 +19,10 @@ endif
let s:keepcpo= &cpo
set cpo&vim
syn region cmakeComment start="#" end="$" contains=cmakeTodo,cmakeLuaComment,@Spell
syn region cmakeLuaComment start="\[\z(=*\)\[" end="\]\z1\]" contains=cmakeTodo,@Spell
syn region cmakeBracketArgument start="\[\z(=\?\|=[0-9]*\)\[" end="\]\z1\]" contains=cmakeTodo,@Spell
syn region cmakeComment start="#" end="$" contains=cmakeTodo,@Spell
syn region cmakeBracketComment start="#\[\z(=\?\|=[0-9]*\)\[" end="\]\z1\]" contains=cmakeTodo,@Spell
syn match cmakeEscaped /\(\\\\\|\\"\|\\n\|\\t\)/ contained
syn region cmakeRegistry start="\[" end="]" contained oneline contains=cmakeTodo,cmakeEscaped
@ -33,7 +35,7 @@ syn region cmakeVariableValue start="${" end="}" contained oneline contains=cmak
syn region cmakeEnvironment start="$ENV{" end="}" contained oneline contains=cmakeTodo
syn region cmakeArguments start="(" end=")" contains=ALLBUT,cmakeCommand,cmakeCommandConditional,cmakeCommandRepeat,cmakeCommandDeprecated,cmakeArguments,cmakeTodo
syn region cmakeArguments start="(" end=")" contains=ALLBUT,cmakeCommand,cmakeCommandConditional,cmakeCommandRepeat,cmakeCommandDeprecated,cmakeCommandManuallyAdded,cmakeArguments,cmakeTodo
syn case match
@ -75,6 +77,8 @@ syn keyword cmakeTodo
\ TODO FIXME XXX
\ contained
hi def link cmakeBracketArgument String
hi def link cmakeBracketComment Comment
hi def link cmakeCommand Function
hi def link cmakeCommandConditional Conditional
hi def link cmakeCommandDeprecated WarningMsg
@ -84,7 +88,6 @@ hi def link cmakeEnvironment Special
hi def link cmakeEscaped Special
hi def link cmakeGeneratorExpression WarningMsg
hi def link cmakeGeneratorExpressions Constant
hi def link cmakeLuaComment Comment
hi def link cmakeModule Include
hi def link cmakeProperty Constant
hi def link cmakeRegistry Underlined
@ -95,6 +98,30 @@ hi def link cmakeVariable Identifier
@KEYWORDS_HIGHLIGHT@
" Manually added - difficult to parse out of documentation
syn case ignore
syn keyword cmakeCommandManuallyAdded
\ configure_package_config_file write_basic_package_version_file
\ nextgroup=cmakeArguments
syn case match
syn keyword cmakeKWconfigure_package_config_file contained
\ INSTALL_DESTINATION PATH_VARS NO_SET_AND_CHECK_MACRO NO_CHECK_REQUIRED_COMPONENTS_MACRO INSTALL_PREFIX
syn keyword cmakeKWconfigure_package_config_file_constants contained
\ AnyNewerVersion SameMajorVersion SameMinorVersion ExactVersion
syn keyword cmakeKWwrite_basic_package_version_file contained
\ VERSION COMPATIBILITY
hi def link cmakeCommandManuallyAdded Function
hi def link cmakeKWconfigure_package_config_file ModeMsg
hi def link cmakeKWwrite_basic_package_version_file ModeMsg
hi def link cmakeKWconfigure_package_config_file_constants Constant
let b:current_syntax = "cmake"
let &cpo = s:keepcpo

25
Auxiliary/vim/extract-upper-case.pl
View File

@ -103,25 +103,25 @@ while(<IN>)
my @tmp = grep { ! exists $conditional{$_} and
! exists $loop{$_} and
! exists $deprecated{$_} } @commands;
print OUT " " x 12 , "\\ ", join(" ", @tmp), "\n";
print_list(\*OUT, @tmp);
} elsif ($1 eq "VARIABLE_LIST") {
print OUT " " x 12 , "\\ ", join(" ", sort keys %variables), "\n";
print_list(\*OUT, keys %variables);
} elsif ($1 eq "MODULES") {
print OUT " " x 12 , "\\ ", join("\n", @modules), "\n";
print_list(\*OUT, @modules);
} elsif ($1 eq "GENERATOR_EXPRESSIONS") {
print OUT " " x 12 , "\\ ", join(" ", @generator_expr), "\n";
print_list(\*OUT, @generator_expr);
} elsif ($1 eq "CONDITIONALS") {
print OUT " " x 12 , "\\ ", join(" ", sort keys %conditional), "\n";
print_list(\*OUT, keys %conditional);
} elsif ($1 eq "LOOPS") {
print OUT " " x 12 , "\\ ", join(" ", sort keys %loop), "\n";
print_list(\*OUT, keys %loop);
} elsif ($1 eq "DEPRECATED") {
print OUT " " x 12 , "\\ ", join(" ", sort keys %deprecated), "\n";
print_list(\*OUT, keys %deprecated);
} elsif ($1 eq "PROPERTIES") {
print OUT " " x 12 , "\\ ", join(" ", sort keys %properties), "\n";
print_list(\*OUT, keys %properties);
} elsif ($1 eq "KEYWORDS") {
foreach my $k (sort keys %keywords) {
print OUT "syn keyword cmakeKW$k contained\n";
print OUT " " x 12, "\\ ", join(" ", @{$keywords{$k}}), "\n";
print_list(\*OUT, @{$keywords{$k}});
print OUT "\n";
push @keyword_hi, "hi def link cmakeKW$k ModeMsg";
}
@ -164,3 +164,10 @@ sub extract_upper
return @word;
}
sub print_list
{
my $O = shift;
my $indent = " " x 12 . "\\ ";
print $O $indent, join("\n" . $indent, sort @_), "\n";
}

2264
Auxiliary/vim/syntax/cmake.vim
View File

File diff suppressed because one or more lines are too long

14
CMakeLists.txt
View File

@ -285,7 +285,8 @@ if(CMake_RUN_IWYU)
message(FATAL_ERROR "CMake_RUN_IWYU is ON but include-what-you-use is not found!")
endif()
set(CMAKE_CXX_INCLUDE_WHAT_YOU_USE
"${IWYU_COMMAND};-Xiwyu;--mapping_file=${CMake_SOURCE_DIR}/Utilities/IWYU/mapping.imp;-w;-DCMAKE_IWYU")
"${IWYU_COMMAND};-Xiwyu;--mapping_file=${CMake_SOURCE_DIR}/Utilities/IWYU/mapping.imp;-w")
list(APPEND CMAKE_CXX_INCLUDE_WHAT_YOU_USE ${CMake_IWYU_OPTIONS})
endif()
@ -409,7 +410,6 @@ macro (CMAKE_BUILD_UTILITIES)
set(CURL_SPECIAL_ZLIB_H ${CMAKE_ZLIB_HEADER})
set(CURL_SPECIAL_LIBZ_INCLUDES ${CMAKE_ZLIB_INCLUDES})
set(CURL_SPECIAL_LIBZ ${CMAKE_ZLIB_LIBRARIES})
add_definitions(-DCURL_STATICLIB)
set(CMAKE_CURL_INCLUDES)
set(CMAKE_CURL_LIBRARIES cmcurl)
if(CMAKE_TESTS_CDASH_SERVER)
@ -497,7 +497,7 @@ macro (CMAKE_BUILD_UTILITIES)
#---------------------------------------------------------------------
# Build or use system libarchive for CMake and CTest.
if(CMAKE_USE_SYSTEM_LIBARCHIVE)
find_package(LibArchive 3.0.0)
find_package(LibArchive 3.1.0)
if(NOT LibArchive_FOUND)
message(FATAL_ERROR "CMAKE_USE_SYSTEM_LIBARCHIVE is ON but LibArchive is not found!")
endif()
@ -512,6 +512,7 @@ macro (CMAKE_BUILD_UTILITIES)
set(ENABLE_NETTLE OFF CACHE INTERNAL "Enable use of Nettle")
set(ENABLE_OPENSSL ${CMAKE_USE_OPENSSL} CACHE INTERNAL "Enable use of OpenSSL")
set(ENABLE_LZMA ON CACHE INTERNAL "Enable the use of the system LZMA library if found")
set(ENABLE_LZ4 OFF CACHE INTERNAL "Enable the use of the system LZ4 library if found")
set(ENABLE_LZO OFF CACHE INTERNAL "Enable the use of the system LZO library if found")
set(ENABLE_ZLIB ON CACHE INTERNAL "Enable the use of the system ZLIB library if found")
set(ENABLE_BZip2 ON CACHE INTERNAL "Enable the use of the system BZip2 library if found")
@ -790,9 +791,10 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE)
endif()
endif()
# add a test
add_test(SystemInformationNew "${CMAKE_CMAKE_COMMAND}"
--system-information -G "${CMAKE_GENERATOR}" )
if(BUILD_TESTING)
add_test(SystemInformationNew "${CMAKE_CMAKE_COMMAND}"
--system-information -G "${CMAKE_GENERATOR}" )
endif()
if(NOT CMake_TEST_EXTERNAL_CMAKE)
# Install license file as it requires.

18
CONTRIBUTING.rst
View File

@ -36,7 +36,9 @@ To contribute patches:
#. Push a topic branch to a personal repository fork on GitLab.
#. Create a GitLab Merge Request targeting the upstream ``master`` branch
(even if the change is intended for merge to the ``release`` branch).
Check the box to allow edits from maintainers.
Check the box labelled "Allow commits from members who can merge to the
target branch". This will allow maintainers to make minor edits on your
behalf.
The merge request will enter the `CMake Review Process`_ for consideration.
@ -47,6 +49,20 @@ The merge request will enter the `CMake Review Process`_ for consideration.
.. _`commit messages`: Help/dev/review.rst#commit-messages
.. _`CMake Review Process`: Help/dev/review.rst
CMake Dashboard Client
======================
The *integration testing* step of the `CMake Review Process`_ uses a set of
testing machines that follow an integration branch on their own schedule to
drive testing and submit results to the `CMake CDash Page`_. Anyone is
welcome to provide testing machines in order to help keep support for their
platforms working.
See documentation on `CMake Testing Process`_ for more information.
.. _`CMake CDash Page`: https://open.cdash.org/index.php?project=CMake
.. _`CMake Testing Process`: Help/dev/testing.rst
License
=======

2
CTestCustom.cmake.in
View File

@ -2,6 +2,7 @@ list(APPEND CTEST_CUSTOM_ERROR_MATCH
"ERROR:")
list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION
"warning: cast from 'char\\*' to 'cmCursesWidget\\*' increases required alignment of target type" # Occurs when using Solaris's system libform
"xtree.[0-9]+. : warning C4702: unreachable code"
"warning LNK4221"
"warning LNK4204" # Occurs by race condition with objects in small libs
@ -92,6 +93,7 @@ list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION
"cmFortranLexer.cxx:[0-9]+:[0-9]+: warning: Call to 'realloc' has an allocation size of 0 bytes"
"testProcess.*warning: Dereference of null pointer .loaded from variable .invalidAddress.."
"liblzma/simple/x86.c:[0-9]+:[0-9]+: warning: The result of the '<<' expression is undefined"
"liblzma/common/index_encoder.c:[0-9]+:[0-9]+: warning: Value stored to .* during its initialization is never read"
"libuv/src/.*:[0-9]+:[0-9]+: warning: Dereference of null pointer"
"libuv/src/.*:[0-9]+:[0-9]+: warning: The left operand of '==' is a garbage value"
)

2
Help/command/FIND_XXX.txt
View File

@ -137,7 +137,7 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
.. |FIND_ARGS_XXX| replace:: <VAR> NAMES name
On OS X the :variable:`CMAKE_FIND_FRAMEWORK` and
On macOS the :variable:`CMAKE_FIND_FRAMEWORK` and
:variable:`CMAKE_FIND_APPBUNDLE` variables determine the order of
preference between Apple-style and unix-style package components.

10
Help/command/LINK_OPTIONS_LINKER.txt Normal file
View File

@ -0,0 +1,10 @@
To pass options to the linker tool, each compiler driver has is own syntax.
The ``LINKER:`` prefix can be used to specify, in a portable way, options
to pass to the linker tool. The ``LINKER:`` prefix is replaced by the required
driver option and the rest of the option string defines linker arguments using
``,`` as separator. These arguments will be formatted according to the
:variable:`CMAKE_<LANG>_LINKER_WRAPPER_FLAG` and
:variable:`CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP` variables.
For example, ``"LINKER:-z,defs"`` becomes ``-Xlinker -z -Xlinker defs`` for
``Clang`` and ``-Wl,-z,defs`` for ``GNU GCC``.

2
Help/command/COMPILE_OPTIONS_SHELL.txt → Help/command/OPTIONS_SHELL.txt
View File

@ -1,4 +1,4 @@
The final set of compile options used for a target is constructed by
The final set of compile or link options used for a target is constructed by
accumulating options from the current target and the usage requirements of
it dependencies. The set of options is de-duplicated to avoid repetition.
While beneficial for individual options, the de-duplication step can break

2
Help/command/add_compile_options.rst
View File

@ -22,4 +22,4 @@ the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
manual for available expressions. See the :manual:`cmake-buildsystem(7)`
manual for more on defining buildsystem properties.
.. include:: COMPILE_OPTIONS_SHELL.txt
.. include:: OPTIONS_SHELL.txt

3
Help/command/add_custom_command.rst
View File

@ -182,6 +182,9 @@ The options are:
If it is a relative path it will be interpreted relative to the
build tree directory corresponding to the current source directory.
Arguments to ``WORKING_DIRECTORY`` may use
:manual:`generator expressions <cmake-generator-expressions(7)>`.
``DEPFILE``
Specify a ``.d`` depfile for the :generator:`Ninja` generator.
A ``.d`` file holds dependencies usually emitted by the custom

3
Help/command/add_custom_target.rst
View File

@ -121,3 +121,6 @@ The options are:
Execute the command with the given current working directory.
If it is a relative path it will be interpreted relative to the
build tree directory corresponding to the current source directory.
Arguments to ``WORKING_DIRECTORY`` may use
:manual:`generator expressions <cmake-generator-expressions(7)>`.

3
Help/command/add_library.rst
View File

@ -35,7 +35,7 @@ variable :variable:`BUILD_SHARED_LIBS` is ``ON``. For ``SHARED`` and
``MODULE`` libraries the :prop_tgt:`POSITION_INDEPENDENT_CODE` target
property is set to ``ON`` automatically.
A ``SHARED`` or ``STATIC`` library may be marked with the :prop_tgt:`FRAMEWORK`
target property to create an OS X Framework.
target property to create an macOS Framework.
If a library does not export any symbols, it must not be declared as a
``SHARED`` library. For example, a Windows resource DLL or a managed C++/CLI
@ -153,6 +153,7 @@ the interface target using the commands:
* :command:`set_property`,
* :command:`target_link_libraries(INTERFACE)`,
* :command:`target_link_options(INTERFACE)`,
* :command:`target_include_directories(INTERFACE)`,
* :command:`target_compile_options(INTERFACE)`,
* :command:`target_compile_definitions(INTERFACE)`, and

26
Help/command/add_link_options.rst Normal file
View File

@ -0,0 +1,26 @@
add_link_options
----------------
Adds options to the link of shared library, module and executable targets.
::
add_link_options(<option> ...)
Adds options to the link step for targets in the current directory and below
that are added after this command is invoked. See documentation of the
:prop_dir:`directory <LINK_OPTIONS>` and
:prop_tgt:`target <LINK_OPTIONS>` ``LINK_OPTIONS`` properties.
This command can be used to add any options, but alternative commands
exist to add libraries (:command:`target_link_libraries` or
:command:`link_libraries`).
Arguments to ``add_link_options`` may use "generator expressions" with
the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
manual for available expressions. See the :manual:`cmake-buildsystem(7)`
manual for more on defining buildsystem properties.
.. include:: LINK_OPTIONS_LINKER.txt
.. include:: OPTIONS_SHELL.txt

12
Help/command/cmake_host_system_information.rst
View File

@ -20,10 +20,10 @@ Key Description
``NUMBER_OF_PHYSICAL_CORES`` Number of physical cores
``HOSTNAME`` Hostname
``FQDN`` Fully qualified domain name
``TOTAL_VIRTUAL_MEMORY`` Total virtual memory in megabytes
``AVAILABLE_VIRTUAL_MEMORY`` Available virtual memory in megabytes
``TOTAL_PHYSICAL_MEMORY`` Total physical memory in megabytes
``AVAILABLE_PHYSICAL_MEMORY`` Available physical memory in megabytes
``TOTAL_VIRTUAL_MEMORY`` Total virtual memory in MiB [#mebibytes]_
``AVAILABLE_VIRTUAL_MEMORY`` Available virtual memory in MiB [#mebibytes]_
``TOTAL_PHYSICAL_MEMORY`` Total physical memory in MiB [#mebibytes]_
``AVAILABLE_PHYSICAL_MEMORY`` Available physical memory in MiB [#mebibytes]_
``IS_64BIT`` One if processor is 64Bit
``HAS_FPU`` One if processor has floating point unit
``HAS_MMX`` One if processor supports MMX instructions
@ -44,3 +44,7 @@ Key Description
``OS_VERSION`` The OS build ID
``OS_PLATFORM`` See :variable:`CMAKE_HOST_SYSTEM_PROCESSOR`
============================= ================================================
.. rubric:: Footnotes
.. [#mebibytes] One MiB (mebibyte) is equal to 1024x1024 bytes.

10
Help/command/ctest_submit.rst
View File

@ -10,6 +10,7 @@ Perform the :ref:`CTest Submit Step` as a :ref:`Dashboard Client`.
[RETRY_COUNT <count>]
[RETRY_DELAY <delay>]
[RETURN_VALUE <result-var>]
[CAPTURE_CMAKE_ERROR <result-var>]
[QUIET]
)
@ -52,6 +53,10 @@ The options are:
Store in the ``<result-var>`` variable ``0`` for success and
non-zero on failure.
``CAPTURE_CMAKE_ERROR <result-var>``
Store in the ``<result-var>`` variable -1 if there are any errors running
the command and prevent ctest from returning non-zero if an error occurs.
``QUIET``
Suppress all non-error messages that would have otherwise been
printed to the console.
@ -65,6 +70,7 @@ Submit to CDash Upload API
[HTTPHEADER <header>]
[RETRY_COUNT <count>]
[RETRY_DELAY <delay>]
[RETURN_VALUE <result-var>]
[QUIET])
This second signature is used to upload files to CDash via the CDash
@ -73,5 +79,5 @@ with a content hash of the file. If CDash does not already have the file,
then it is uploaded. Along with the file, a CDash type string is specified
to tell CDash which handler to use to process the data.
This signature accepts the ``HTTPHEADER``, ``RETRY_COUNT``, ``RETRY_DELAY``, and
``QUIET`` options as described above.
This signature accepts the ``HTTPHEADER``, ``RETRY_COUNT``, ``RETRY_DELAY``,
``RETURN_VALUE`` and ``QUIET`` options as described above.

9
Help/command/ctest_update.rst
View File

@ -5,7 +5,10 @@ Perform the :ref:`CTest Update Step` as a :ref:`Dashboard Client`.
::
ctest_update([SOURCE <source-dir>] [RETURN_VALUE <result-var>] [QUIET])
ctest_update([SOURCE <source-dir>]
[RETURN_VALUE <result-var>]
[CAPTURE_CMAKE_ERROR <result-var>]
[QUIET])
Update the source tree from version control and record results in
``Update.xml`` for submission with the :command:`ctest_submit` command.
@ -20,6 +23,10 @@ The options are:
Store in the ``<result-var>`` variable the number of files
updated or ``-1`` on error.
``CAPTURE_CMAKE_ERROR <result-var>``
Store in the ``<result-var>`` variable -1 if there are any errors running
the command and prevent ctest from returning non-zero if an error occurs.
``QUIET``
Tell CTest to suppress most non-error messages that it would
have otherwise printed to the console. CTest will still report

8
Help/command/export.rst
View File

@ -51,15 +51,15 @@ unspecified.
::
export(PACKAGE <name>)
export(PACKAGE <PackageName>)
Store the current build directory in the CMake user package registry
for package ``<name>``. The find_package command may consider the
directory while searching for package ``<name>``. This helps dependent
for package ``<PackageName>``. The find_package command may consider the
directory while searching for package ``<PackageName>``. This helps dependent
projects find and use a package from the current project's build tree
without help from the user. Note that the entry in the package
registry that this command creates works only in conjunction with a
package configuration file (``<name>Config.cmake``) that works with the
package configuration file (``<PackageName>Config.cmake``) that works with the
build tree. In some cases, for example for packaging and for system
wide installations, it is not desirable to write the user package
registry. If the :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` variable

157
Help/command/find_package.rst
View File

@ -1,21 +1,29 @@
find_package
------------
Load settings for an external project.
.. only:: html
.. contents::
Find an external project, and load its settings.
.. _`basic signature`:
Basic Signature and Module Mode
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
::
find_package(<package> [version] [EXACT] [QUIET] [MODULE]
find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE]
[REQUIRED] [[COMPONENTS] [components...]]
[OPTIONAL_COMPONENTS components...]
[NO_POLICY_SCOPE])
Finds and loads settings from an external project. ``<package>_FOUND``
Finds and loads settings from an external project. ``<PackageName>_FOUND``
will be set to indicate whether the package was found. When the
package is found package-specific information is provided through
variables and :ref:`Imported Targets` documented by the package itself. The
``QUIET`` option disables messages if the package cannot be found. The
``MODULE`` option disables the second signature documented below. The
``REQUIRED`` option stops processing with an error message if the package
cannot be found.
@ -33,28 +41,35 @@ should be compatible (format is ``major[.minor[.patch[.tweak]]]``). The
inside a find-module, the corresponding arguments are forwarded
automatically from the outer call (including the ``EXACT`` flag for
``[version]``). Version support is currently provided only on a
package-by-package basis (details below).
package-by-package basis (see the `Version Selection`_ section below).
User code should generally look for packages using the above simple
signature. The remainder of this command documentation specifies the
See the :command:`cmake_policy` command documentation for discussion
of the ``NO_POLICY_SCOPE`` option.
The command has two modes by which it searches for packages: "Module"
mode and "Config" mode. The above signature selects Module mode.
If no module is found the command falls back to Config mode, described
below. This fall back is disabled if the ``MODULE`` option is given.
In Module mode, CMake searches for a file called ``Find<PackageName>.cmake``
in the :variable:`CMAKE_MODULE_PATH` followed by the CMake installation.
If the file is found, it is read and processed by CMake. It is responsible
for finding the package, checking the version, and producing any needed
messages. Some find-modules provide limited or no support for versioning;
check the module documentation.
Full Signature and Config Mode
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
User code should generally look for packages using the above `basic
signature`_. The remainder of this command documentation specifies the
full command signature and details of the search process. Project
maintainers wishing to provide a package to be found by this command
are encouraged to read on.
The command has two modes by which it searches for packages: "Module"
mode and "Config" mode. Module mode is available when the command is
invoked with the above reduced signature. CMake searches for a file
called ``Find<package>.cmake`` in the :variable:`CMAKE_MODULE_PATH`
followed by the CMake installation. If the file is found, it is read
and processed by CMake. It is responsible for finding the package,
checking the version, and producing any needed messages. Many
find-modules provide limited or no support for versioning; check
the module documentation. If no module is found and the ``MODULE``
option is not given the command proceeds to Config mode.
The complete Config mode command signature is::
find_package(<package> [version] [EXACT] [QUIET]
find_package(<PackageName> [version] [EXACT] [QUIET]
[REQUIRED] [[COMPONENTS] [components...]]
[CONFIG|NO_MODULE]
[NO_POLICY_SCOPE]
@ -76,37 +91,44 @@ The complete Config mode command signature is::
ONLY_CMAKE_FIND_ROOT_PATH |
NO_CMAKE_FIND_ROOT_PATH])
The ``CONFIG`` option may be used to skip Module mode explicitly and
switch to Config mode. It is synonymous to using ``NO_MODULE``. Config
mode is also implied by use of options not specified in the reduced
signature.
The ``CONFIG`` option, the synonymous ``NO_MODULE`` option, or the use
of options not specified in the `basic signature`_ all enforce pure Config
mode. In pure Config mode, the command skips Module mode search and
proceeds at once with Config mode search.
Config mode attempts to locate a configuration file provided by the
package to be found. A cache entry called ``<package>_DIR`` is created to
Config mode search attempts to locate a configuration file provided by the
package to be found. A cache entry called ``<PackageName>_DIR`` is created to
hold the directory containing the file. By default the command
searches for a package with the name ``<package>``. If the ``NAMES`` option
is given the names following it are used instead of ``<package>``. The
command searches for a file called ``<name>Config.cmake`` or
``<lower-case-name>-config.cmake`` for each name specified. A
replacement set of possible configuration file names may be given
searches for a package with the name ``<PackageName>``. If the ``NAMES`` option
is given the names following it are used instead of ``<PackageName>``.
The command searches for a file called ``<PackageName>Config.cmake`` or
``<lower-case-package-name>-config.cmake`` for each name specified.
A replacement set of possible configuration file names may be given
using the ``CONFIGS`` option. The search procedure is specified below.
Once found, the configuration file is read and processed by CMake.
Since the file is provided by the package it already knows the
location of package contents. The full path to the configuration file
is stored in the cmake variable ``<package>_CONFIG``.
is stored in the cmake variable ``<PackageName>_CONFIG``.
All configuration files which have been considered by CMake while
searching for an installation of the package with an appropriate
version are stored in the cmake variable ``<package>_CONSIDERED_CONFIGS``,
the associated versions in ``<package>_CONSIDERED_VERSIONS``.
version are stored in the cmake variable ``<PackageName>_CONSIDERED_CONFIGS``,
the associated versions in ``<PackageName>_CONSIDERED_VERSIONS``.
If the package configuration file cannot be found CMake will generate
an error describing the problem unless the ``QUIET`` argument is
specified. If ``REQUIRED`` is specified and the package is not found a
fatal error is generated and the configure step stops executing. If
``<package>_DIR`` has been set to a directory not containing a
``<PackageName>_DIR`` has been set to a directory not containing a
configuration file CMake will ignore it and search from scratch.
Package maintainers providing CMake package configuration files are
encouraged to name and install them such that the `Search Procedure`_
outlined below will find them without requiring use of additional options.
Version Selection
^^^^^^^^^^^^^^^^^
When the ``[version]`` argument is given Config mode will only find a
version of the package that claims compatibility with the requested
version (format is ``major[.minor[.patch[.tweak]]]``). If the ``EXACT``
@ -127,7 +149,7 @@ version file is loaded in a nested scope in which the following
variables have been defined:
``PACKAGE_FIND_NAME``
the ``<package>`` name
the ``<PackageName>``
``PACKAGE_FIND_VERSION``
full requested version string
``PACKAGE_FIND_VERSION_MAJOR``
@ -158,17 +180,17 @@ whether the configuration file provides an acceptable version. They
are not available after the find_package call returns. If the version
is acceptable the following variables are set:
``<package>_VERSION``
``<PackageName>_VERSION``
full provided version string
``<package>_VERSION_MAJOR``
``<PackageName>_VERSION_MAJOR``
major version if provided, else 0
``<package>_VERSION_MINOR``
``<PackageName>_VERSION_MINOR``
minor version if provided, else 0
``<package>_VERSION_PATCH``
``<PackageName>_VERSION_PATCH``
patch version if provided, else 0
``<package>_VERSION_TWEAK``
``<PackageName>_VERSION_TWEAK``
tweak version if provided, else 0
``<package>_VERSION_COUNT``
``<PackageName>_VERSION_COUNT``
number of version components, 0 to 4
and the corresponding package configuration file is loaded.
@ -187,17 +209,8 @@ For instance in order to select the highest version one can set::
before calling ``find_package``.
Config mode provides an elaborate interface and search procedure.
Much of the interface is provided for completeness and for use
internally by find-modules loaded by Module mode. Most user code
should simply call::
find_package(<package> [major[.minor]] [EXACT] [REQUIRED|QUIET])
in order to find a package. Package maintainers providing CMake
package configuration files are encouraged to name and install them
such that the procedure outlined below will find them without
requiring use of additional options.
Search Procedure
^^^^^^^^^^^^^^^^
CMake constructs a set of possible installation prefixes for the
package. Under each prefix several directories are searched for a
@ -216,7 +229,7 @@ Each entry is meant for installation trees following Windows (W), UNIX
<prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/ (W/U)
<prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/ (W/U)
On systems supporting OS X Frameworks and Application Bundles the
On systems supporting macOS Frameworks and Application Bundles the
following directories are searched for frameworks or bundles
containing a configuration file::
@ -228,7 +241,7 @@ containing a configuration file::
<prefix>/<name>.app/Contents/Resources/CMake/ (A)
In all cases the ``<name>`` is treated as case-insensitive and corresponds
to any of the names specified (``<package>`` or names given by ``NAMES``).
to any of the names specified (``<PackageName>`` or names given by ``NAMES``).
Paths with ``lib/<arch>`` are enabled if the
:variable:`CMAKE_LIBRARY_ARCHITECTURE` variable is set. ``lib*`` includes one
@ -286,7 +299,7 @@ enabled.
(``;`` on Windows and ``:`` on UNIX).
This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed::
<package>_DIR
<PackageName>_DIR
CMAKE_PREFIX_PATH
CMAKE_FRAMEWORK_PATH
CMAKE_APPBUNDLE_PATH
@ -329,7 +342,7 @@ enabled.
hard-coded guesses.
.. |FIND_XXX| replace:: find_package
.. |FIND_ARGS_XXX| replace:: <package>
.. |FIND_ARGS_XXX| replace:: <PackageName>
.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
:variable:`CMAKE_FIND_ROOT_PATH_MODE_PACKAGE`
@ -339,33 +352,36 @@ enabled.
Every non-REQUIRED ``find_package`` call can be disabled by setting the
:variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable to ``TRUE``.
Package File Interface Variables
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When loading a find module or package configuration file ``find_package``
defines variables to provide information about the call arguments (and
restores their original state before returning):
``CMAKE_FIND_PACKAGE_NAME``
the ``<package>`` name which is searched for
``<package>_FIND_REQUIRED``
the ``<PackageName>`` which is searched for
``<PackageName>_FIND_REQUIRED``
true if ``REQUIRED`` option was given
``<package>_FIND_QUIETLY``
``<PackageName>_FIND_QUIETLY``
true if ``QUIET`` option was given
``<package>_FIND_VERSION``
``<PackageName>_FIND_VERSION``
full requested version string
``<package>_FIND_VERSION_MAJOR``
``<PackageName>_FIND_VERSION_MAJOR``
major version if requested, else 0
``<package>_FIND_VERSION_MINOR``
``<PackageName>_FIND_VERSION_MINOR``
minor version if requested, else 0
``<package>_FIND_VERSION_PATCH``
``<PackageName>_FIND_VERSION_PATCH``
patch version if requested, else 0
``<package>_FIND_VERSION_TWEAK``
``<PackageName>_FIND_VERSION_TWEAK``
tweak version if requested, else 0
``<package>_FIND_VERSION_COUNT``
``<PackageName>_FIND_VERSION_COUNT``
number of version components, 0 to 4
``<package>_FIND_VERSION_EXACT``
``<PackageName>_FIND_VERSION_EXACT``
true if ``EXACT`` option was given
``<package>_FIND_COMPONENTS``
``<PackageName>_FIND_COMPONENTS``
list of requested components
``<package>_FIND_REQUIRED_<c>``
``<PackageName>_FIND_REQUIRED_<c>``
true if component ``<c>`` is required,
false if component ``<c>`` is optional
@ -375,8 +391,5 @@ In Config mode ``find_package`` handles ``REQUIRED``, ``QUIET``, and
``[version]`` options automatically but leaves it to the package
configuration file to handle components in a way that makes sense
for the package. The package configuration file may set
``<package>_FOUND`` to false to tell ``find_package`` that component
``<PackageName>_FOUND`` to false to tell ``find_package`` that component
requirements are not satisfied.
See the :command:`cmake_policy` command documentation for discussion
of the ``NO_POLICY_SCOPE`` option.

20
Help/command/if.rst
View File

@ -148,23 +148,33 @@ Possible expressions are:
``if(<variable|string> VERSION_LESS <variable|string>)``
Component-wise integer version number comparison (version format is
``major[.minor[.patch[.tweak]]]``).
``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero).
Any non-integer version component or non-integer trailing part of a version
component effectively truncates the string at that point.
``if(<variable|string> VERSION_GREATER <variable|string>)``
Component-wise integer version number comparison (version format is
``major[.minor[.patch[.tweak]]]``).
``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero).
Any non-integer version component or non-integer trailing part of a version
component effectively truncates the string at that point.
``if(<variable|string> VERSION_EQUAL <variable|string>)``
Component-wise integer version number comparison (version format is
``major[.minor[.patch[.tweak]]]``).
``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero).
Any non-integer version component or non-integer trailing part of a version
component effectively truncates the string at that point.
``if(<variable|string> VERSION_LESS_EQUAL <variable|string>)``
Component-wise integer version number comparison (version format is
``major[.minor[.patch[.tweak]]]``).
``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero).
Any non-integer version component or non-integer trailing part of a version
component effectively truncates the string at that point.
``if(<variable|string> VERSION_GREATER_EQUAL <variable|string>)``
Component-wise integer version number comparison (version format is
``major[.minor[.patch[.tweak]]]``).
``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero).
Any non-integer version component or non-integer trailing part of a version
component effectively truncates the string at that point.
``if(<variable|string> IN_LIST <variable>)``
True if the given element is contained in the named list variable.

6
Help/command/include_directories.rst
View File

@ -33,3 +33,9 @@ Arguments to ``include_directories`` may use "generator expressions" with
the syntax "$<...>". See the :manual:`cmake-generator-expressions(7)`
manual for available expressions. See the :manual:`cmake-buildsystem(7)`
manual for more on defining buildsystem properties.
.. note::
Prefer the :command:`target_include_directories` command to add include
directories to individual targets and optionally propagate/export them
to dependents.

25
Help/command/install.rst
View File

@ -89,6 +89,13 @@ Command signatures that install files may print messages during
installation. Use the :variable:`CMAKE_INSTALL_MESSAGE` variable
to control which messages are printed.
Many of the ``install()`` variants implicitly create the directories
containing the installed files. If
:variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` is set, these
directories will be created with the permissions specified. Otherwise,
they will be created according to the uname rules on Unix-like platforms.
Windows platforms are unaffected.
Installing Targets
^^^^^^^^^^^^^^^^^^
@ -115,19 +122,19 @@ project. There are several kinds of target files that may be installed:
``ARCHIVE``
Static libraries are treated as ``ARCHIVE`` targets, except those
marked with the ``FRAMEWORK`` property on OS X (see ``FRAMEWORK``
marked with the ``FRAMEWORK`` property on macOS (see ``FRAMEWORK``
below.) For DLL platforms (all Windows-based systems including
Cygwin), the DLL import library is treated as an ``ARCHIVE`` target.
``LIBRARY``
Module libraries are always treated as ``LIBRARY`` targets. For non-
DLL platforms shared libraries are treated as ``LIBRARY`` targets,
except those marked with the ``FRAMEWORK`` property on OS X (see
except those marked with the ``FRAMEWORK`` property on macOS (see
``FRAMEWORK`` below.)
``RUNTIME``
Executables are treated as ``RUNTIME`` objects, except those marked
with the ``MACOSX_BUNDLE`` property on OS X (see ``BUNDLE`` below.)
with the ``MACOSX_BUNDLE`` property on macOS (see ``BUNDLE`` below.)
For DLL platforms (all Windows-based systems including Cygwin), the
DLL part of a shared library is treated as a ``RUNTIME`` target.
@ -137,11 +144,11 @@ project. There are several kinds of target files that may be installed:
``FRAMEWORK``
Both static and shared libraries marked with the ``FRAMEWORK``
property are treated as ``FRAMEWORK`` targets on OS X.
property are treated as ``FRAMEWORK`` targets on macOS.
``BUNDLE``
Executables marked with the ``MACOSX_BUNDLE`` property are treated as
``BUNDLE`` targets on OS X.
``BUNDLE`` targets on macOS.
``PUBLIC_HEADER``
Any ``PUBLIC_HEADER`` files associated with a library are installed in
@ -280,6 +287,14 @@ targets that link to the object libraries in their implementation.
Installing a target with the :prop_tgt:`EXCLUDE_FROM_ALL` target property
set to ``TRUE`` has undefined behavior.
:command:`install(TARGETS)` can install targets that were created in
other directories. When using such cross-directory install rules, running
``make install`` (or similar) from a subdirectory will not guarantee that
targets from other directories are up-to-date. You can use
:command:`target_link_libraries` or :command:`add_dependencies`
to ensure that such out-of-directory targets are built before the
subdirectory-specific install rules are run.
The install destination given to the target install ``DESTINATION`` may
use "generator expressions" with the syntax ``$<...>``. See the
:manual:`cmake-generator-expressions(7)` manual for available expressions.

50
Help/command/link_directories.rst
View File

@ -1,19 +1,51 @@
link_directories
----------------
Specify directories in which the linker will look for libraries.
Add directories in which the linker will look for libraries.
::
link_directories(directory1 directory2 ...)
link_directories([AFTER|BEFORE] directory1 [directory2 ...])
Specify the paths in which the linker should search for libraries.
The command will apply only to targets created after it is called.
Add the paths in which the linker should search for libraries.
Relative paths given to this command are interpreted as relative to
the current source directory, see :policy:`CMP0015`.
Note that this command is rarely necessary. Library locations
returned by :command:`find_package` and :command:`find_library` are
absolute paths. Pass these absolute library file paths directly to the
:command:`target_link_libraries` command. CMake will ensure the linker finds
them.
The directories are added to the :prop_dir:`LINK_DIRECTORIES` directory
property for the current ``CMakeLists.txt`` file, converting relative
paths to absolute as needed.
The command will apply only to targets created after it is called.
By default the directories specified are appended onto the current list of
directories. This default behavior can be changed by setting
:variable:`CMAKE_LINK_DIRECTORIES_BEFORE` to ``ON``. By using
``AFTER`` or ``BEFORE`` explicitly, you can select between appending and
prepending, independent of the default.
Arguments to ``link_directories`` may use "generator expressions" with
the syntax "$<...>". See the :manual:`cmake-generator-expressions(7)`
manual for available expressions. See the :manual:`cmake-buildsystem(7)`
manual for more on defining buildsystem properties.
.. note::
This command is rarely necessary and should be avoided where there are
other choices. Prefer to pass full absolute paths to libraries where
possible, since this ensures the correct library will always be linked.
The :command:`find_library` command provides the full path, which can
generally be used directly in calls to :command:`target_link_libraries`.
Situations where a library search path may be needed include:
- Project generators like Xcode where the user can switch target
architecture at build time, but a full path to a library cannot
be used because it only provides one architecture (i.e. it is not
a universal binary).
- Libraries may themselves have other private library dependencies
that expect to be found via ``RPATH`` mechanisms, but some linkers
are not able to fully decode those paths (e.g. due to the presence
of things like ``$ORIGIN``).
If a library search path must be provided, prefer to localize the effect
where possible by using the :command:`target_link_directories` command
rather than ``link_directories()``. The target-specific command can also
control how the search directories propagate to other dependent targets.

26
Help/command/list.rst
View File

@ -28,7 +28,7 @@ Synopsis
`Ordering`_
list(`REVERSE`_ <list>)
list(`SORT`_ <list>)
list(`SORT`_ <list> [...])
Introduction
^^^^^^^^^^^^
@ -253,7 +253,27 @@ Reverses the contents of the list in-place.
::
list(SORT <list>)
list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>])
Sorts the list in-place alphabetically.
Use the ``COMPARE`` keyword to select the comparison method for sorting.
The ``<compare>`` option should be one of:
* ``STRING``: Sorts a list of strings alphabetically. This is the
default behavior if the ``COMPARE`` option is not given.
* ``FILE_BASENAME``: Sorts a list of pathnames of files by their basenames.
Use the ``CASE`` keyword to select a case sensitive or case insensitive
sort mode. The ``<case>`` option should be one of:
* ``SENSITIVE``: List items are sorted in a case-sensitive manner. This is
the default behavior if the ``CASE`` option is not given.
* ``INSENSITIVE``: List items are sorted case insensitively. The order of
items which differ only by upper/lowercase is not specified.
To control the sort order, the ``ORDER`` keyword can be given.
The ``<order>`` option should be one of:
* ``ASCENDING``: Sorts the list in ascending order. This is the default
behavior when the ``ORDER`` option is not given.
* ``DESCENDING``: Sorts the list in descending order.

18
Help/command/math.rst
View File

@ -5,10 +5,26 @@ Mathematical expressions.
::
math(EXPR <output-variable> <math-expression>)
math(EXPR <output-variable> <math-expression> [OUTPUT_FORMAT <format>])
``EXPR`` evaluates mathematical expression and returns result in the
output variable. Example mathematical expression is ``5 * (10 + 13)``.
Supported operators are ``+``, ``-``, ``*``, ``/``, ``%``, ``|``, ``&``,
``^``, ``~``, ``<<``, ``>>``, and ``(...)``. They have the same meaning
as they do in C code.
Numeric constants are evaluated in decimal or hexadecimal representation.
The result is formatted according to the option "OUTPUT_FORMAT" ,
where ``<format>`` is one of:
::
HEXADECIMAL = Result in output variable will be formatted in C code
Hexadecimal notation.
DECIMAL = Result in output variable will be formatted in decimal notation.
For example::
math(EXPR value "100 * 0xA" DECIMAL) results in value is set to "1000"
math(EXPR value "100 * 0xA" HEXADECIMAL) results in value is set to "0x3e8"

4
Help/command/option.rst
View File

@ -9,7 +9,9 @@ Provides an option that the user can optionally select.
[initial value])
Provide an option for the user to select as ``ON`` or ``OFF``. If no
initial value is provided, ``OFF`` is used.
initial value is provided, ``OFF`` is used. If the option is already
set as a normal variable then the command does nothing
(see policy :policy:`CMP0077`).
If you have options that depend on the values of other options, see
the module help for :module:`CMakeDependentOption`.

2
Help/command/project.rst
View File

@ -44,6 +44,7 @@ Variables corresponding to unspecified versions are set to the empty string
If the optional ``DESCRIPTION`` is given, then :variable:`PROJECT_DESCRIPTION`
and :variable:`<PROJECT-NAME>_DESCRIPTION` will be set to its argument.
These variables will be cleared if ``DESCRIPTION`` is not given.
The description is expected to be a relatively short string, usually no more
than a few words.
@ -51,6 +52,7 @@ The optional ``HOMEPAGE_URL`` sets the analogous variables
:variable:`PROJECT_HOMEPAGE_URL` and :variable:`<PROJECT-NAME>_HOMEPAGE_URL`.
When this option is given, the URL provided should be the canonical home for
the project.
These variables will be cleared if ``HOMEPAGE_URL`` is not given.
Note that the description and homepage URL may be used as defaults for
things like packaging meta-data, documentation, etc.

7
Help/command/set_directory_properties.rst
View File

@ -1,12 +1,11 @@
set_directory_properties
------------------------
Set a property of the directory.
Set properties of the current directory and subdirectories in key-value pairs.
::
set_directory_properties(PROPERTIES prop1 value1 prop2 value2)
Set a property for the current directory and subdirectories. See
:ref:`Directory Properties` for the list of properties known
to CMake.
See :ref:`Directory Properties` for the list of properties known to CMake
and their individual documentation for the behavior of each property.

21
Help/command/string.rst
View File

@ -121,6 +121,11 @@ The following characters have special meaning in regular expressions:
Matches at end of input
``.``
Matches any single character
``\<char>``
Matches the single character specified by ``<char>``. Use this to
match special regex characters, e.g. ``\.`` for a literal ``.``
or ``\\`` for a literal backslash ``\``. Escaping a non-special
character is unnecessary but allowed, e.g. ``\a`` matches ``a``.
``[ ]``
Matches any character(s) inside the brackets
``[^ ]``
@ -151,6 +156,22 @@ has lower precedence than concatenation. This means that the regular
expression ``^ab+d$`` matches ``abbd`` but not ``ababd``, and the regular
expression ``^(ab|cd)$`` matches ``ab`` but not ``abd``.
CMake language :ref:`Escape Sequences` such as ``\t``, ``\r``, ``\n``,
and ``\\`` may be used to construct literal tabs, carriage returns,
newlines, and backslashes (respectively) to pass in a regex. For example:
* The quoted argument ``"[ \t\r\n]"`` specifies a regex that matches
any single whitespace character.
* The quoted argument ``"[/\\]"`` specifies a regex that matches
a single forward slash ``/`` or backslash ``\``.
* The quoted argument ``"[A-Za-z0-9_]"`` specifies a regex that matches
any single "word" character in the C locale.
* The quoted argument ``"\\(\\a\\+b\\)"`` specifies a regex that matches
the exact string ``(a+b)``. Each ``\\`` is parsed in a quoted argument
as just ``\``, so the regex itself is actually ``\(\a\+\b\)``. This
can alternatively be specified in a :ref:`bracket argument` without
having to escape the backslashes, e.g. ``[[\(\a\+\b\)]]``.
Manipulation
^^^^^^^^^^^^

2
Help/command/target_compile_options.rst
View File

@ -39,4 +39,4 @@ with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
manual for available expressions. See the :manual:`cmake-buildsystem(7)`
manual for more on defining buildsystem properties.
.. include:: COMPILE_OPTIONS_SHELL.txt
.. include:: OPTIONS_SHELL.txt

55
Help/command/target_link_directories.rst Normal file
View File

@ -0,0 +1,55 @@
target_link_directories
-----------------------
Add link directories to a target.
::
target_link_directories(<target> [BEFORE]
<INTERFACE|PUBLIC|PRIVATE> [items1...]
[<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
Specify the paths in which the linker should search for libraries when
linking a given target. Each item can be an absolute or relative path,
with the latter being interpreted as relative to the current source
directory. These items will be added to the link command.
The named ``<target>`` must have been created by a command such as
:command:`add_executable` or :command:`add_library` and must not be an
:ref:`ALIAS target <Alias Targets>`.
The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
specify the scope of the items that follow them. ``PRIVATE`` and
``PUBLIC`` items will populate the :prop_tgt:`LINK_DIRECTORIES` property
of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
:prop_tgt:`INTERFACE_LINK_DIRECTORIES` property of ``<target>``
(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items).
Each item specifies a link directory and will be converted to an absolute
path if necessary before adding it to the relevant property. Repeated
calls for the same ``<target>`` append items in the order called.
If ``BEFORE`` is specified, the content will be prepended to the relevant
property instead of being appended.
Arguments to ``target_link_directories`` may use "generator expressions"
with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
manual for available expressions. See the :manual:`cmake-buildsystem(7)`
manual for more on defining buildsystem properties.
.. note::
This command is rarely necessary and should be avoided where there are
other choices. Prefer to pass full absolute paths to libraries where
possible, since this ensures the correct library will always be linked.
The :command:`find_library` command provides the full path, which can
generally be used directly in calls to :command:`target_link_libraries`.
Situations where a library search path may be needed include:
- Project generators like Xcode where the user can switch target
architecture at build time, but a full path to a library cannot
be used because it only provides one architecture (i.e. it is not
a universal binary).
- Libraries may themselves have other private library dependencies
that expect to be found via ``RPATH`` mechanisms, but some linkers
are not able to fully decode those paths (e.g. due to the presence
of things like ``$ORIGIN``).

50
Help/command/target_link_libraries.rst
View File

@ -18,10 +18,13 @@ All of them have the general form::
target_link_libraries(<target> ... <item>... ...)
The named ``<target>`` must have been created in the current directory by
a command such as :command:`add_executable` or :command:`add_library` and
must not be an :ref:`ALIAS target <Alias Targets>`.
Repeated calls for the same ``<target>`` append items in the order called.
The named ``<target>`` must have been created by a command such as
:command:`add_executable` or :command:`add_library` and must not be an
:ref:`ALIAS target <Alias Targets>`. If policy :policy:`CMP0079` is not
set to ``NEW`` then the target must have been created in the current
directory. Repeated calls for the same ``<target>`` append items in
the order called.
Each ``<item>`` may be:
* **A library target name**: The generated link line will have the
@ -40,6 +43,9 @@ Each ``<item>`` may be:
the library instead of using the full path
(e.g. ``/usr/lib/libfoo.so`` becomes ``-lfoo``).
The full path to the target's artifact will be quoted/escaped for
the shell automatically.
* **A full path to a library file**: The generated link line will
normally preserve the full path to the file. The buildsystem will
have a dependency to re-link ``<target>`` if the library file changes.
@ -59,9 +65,15 @@ Each ``<item>`` may be:
imported into generated project files. This is not supported by other
generators.
The full path to the library file will be quoted/escaped for
the shell automatically.
* **A plain library name**: The generated link line will ask the linker
to search for the library (e.g. ``foo`` becomes ``-lfoo`` or ``foo.lib``).
The library name/flag is treated as a command-line string fragment and
will be used with no extra quoting or escaping.
* **A link flag**: Item names starting with ``-``, but not ``-l`` or
``-framework``, are treated as linker flags. Note that such flags will
be treated like any other library link item for purposes of transitive
@ -70,10 +82,28 @@ Each ``<item>`` may be:
Link flags specified here are inserted into the link command in the same
place as the link libraries. This might not be correct, depending on
the linker. Use the :prop_tgt:`LINK_FLAGS` target property to add link
the linker. Use the :prop_tgt:`LINK_OPTIONS` target property or
:command:`target_link_options` command to add link
flags explicitly. The flags will then be placed at the toolchain-defined
flag position in the link command.
The link flag is treated as a command-line string fragment and
will be used with no extra quoting or escaping.
* **A generator expression**: A ``$<...>`` :manual:`generator expression
<cmake-generator-expressions(7)>` may evaluate to any of the above
items or to a :ref:`;-list <CMake Language Lists>` of them.
If the ``...`` contains any ``;`` characters, e.g. after evaluation
of a ``${list}`` variable, be sure to use an explicitly quoted
argument ``"$<...>"`` so that this command receives it as a
single ``<item>``.
Additionally, a generator expression may be used as a fragment of
any of the above items, e.g. ``foo$<1:_d>``.
Note that generator expressions will not be used in OLD handling of
policy :policy:`CMP0003` or policy :policy:`CMP0004`.
* A ``debug``, ``optimized``, or ``general`` keyword immediately followed
by another ``<item>``. The item following such a keyword will be used
only for the corresponding build configuration. The ``debug`` keyword
@ -84,18 +114,16 @@ Each ``<item>`` may be:
optional. Higher granularity may be achieved for per-configuration
rules by creating and linking to
:ref:`IMPORTED library targets <Imported Targets>`.
These keywords are interpreted immediately by this command and therefore
have no special meaning when produced by a generator expression.
Items containing ``::``, such as ``Foo::Bar``, are assumed to be
:ref:`IMPORTED <Imported Targets>` or :ref:`ALIAS <Alias Targets>` library
target names and will cause an error if no such target exists.
See policy :policy:`CMP0028`.
Arguments to ``target_link_libraries`` may use "generator expressions"
with the syntax ``$<...>``. Note however, that generator expressions
will not be used in OLD handling of :policy:`CMP0003` or :policy:`CMP0004`.
See the :manual:`cmake-generator-expressions(7)` manual for available
expressions. See the :manual:`cmake-buildsystem(7)` manual for more on
defining buildsystem properties.
See the :manual:`cmake-buildsystem(7)` manual for more on defining
buildsystem properties.
Libraries for a Target and/or its Dependents
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

42
Help/command/target_link_options.rst Normal file
View File

@ -0,0 +1,42 @@
target_link_options
-------------------
Add link options to a target.
::
target_link_options(<target> [BEFORE]
<INTERFACE|PUBLIC|PRIVATE> [items1...]
[<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
Specify link options to use when linking a given target. The
named ``<target>`` must have been created by a command such as
:command:`add_executable` or :command:`add_library` and must not be an
:ref:`ALIAS target <Alias Targets>`.
If ``BEFORE`` is specified, the content will be prepended to the property
instead of being appended.
This command can be used to add any options, but
alternative commands exist to add libraries
(:command:`target_link_libraries` and :command:`link_libraries`).
See documentation of the :prop_dir:`directory <LINK_OPTIONS>` and
:prop_tgt:`target <LINK_OPTIONS>` ``LINK_OPTIONS`` properties.
The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC``
items will populate the :prop_tgt:`LINK_OPTIONS` property of
``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
:prop_tgt:`INTERFACE_LINK_OPTIONS` property of ``<target>``.
(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items.)
The following arguments specify link options. Repeated calls for the same
``<target>`` append items in the order called.
Arguments to ``target_link_options`` may use "generator expressions"
with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
manual for available expressions. See the :manual:`cmake-buildsystem(7)`
manual for more on defining buildsystem properties.
.. include:: LINK_OPTIONS_LINKER.txt
.. include:: OPTIONS_SHELL.txt

7
Help/command/target_sources.rst
View File

@ -9,7 +9,9 @@ Add sources to a target.
<INTERFACE|PUBLIC|PRIVATE> [items1...]
[<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
Specify sources to use when compiling a given target. The
Specify sources to use when compiling a given target. Relative
source file paths are interpreted as being relative to the current
source directory (i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`). The
named ``<target>`` must have been created by a command such as
:command:`add_executable` or :command:`add_library` and must not be an
:ref:`ALIAS target <Alias Targets>`.
@ -27,3 +29,6 @@ Arguments to ``target_sources`` may use "generator expressions"
with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
manual for available expressions. See the :manual:`cmake-buildsystem(7)`
manual for more on defining buildsystem properties.
See also the :policy:`CMP0076` policy for older behavior related to the
handling of relative source file paths.

13
Help/command/unset.rst
View File

@ -7,9 +7,16 @@ Unset a variable, cache variable, or environment variable.
unset(<variable> [CACHE | PARENT_SCOPE])
Removes the specified variable causing it to become undefined. If
``CACHE`` is present then the variable is removed from the cache instead
of the current scope.
Removes a normal variable from the current scope, causing it
to become undefined. If ``CACHE`` is present, then a cache variable
is removed instead of a normal variable. Note that when evaluating
:ref:`Variable References` of the form ``${VAR}``, CMake first searches
for a normal variable with that name. If no such normal variable exists,
CMake will then search for a cache entry with that name. Because of this
unsetting a normal variable can expose a cache variable that was previously
hidden. To force a variable reference of the form ``${VAR}`` to return an
empty string, use ``set(<variable> "")``, which clears the normal variable
but leaves it defined.
If ``PARENT_SCOPE`` is present then the variable is removed from the scope
above the current scope. See the same option in the :command:`set` command

35
Help/cpack_gen/archive.rst Normal file
View File

@ -0,0 +1,35 @@
CPack Archive Generator
-----------------------
Archive CPack generator that supports packaging of sources and binaries in
different formats:
- 7Z - 7zip - (.7z)
- TBZ2 (.tar.bz2)
- TGZ (.tar.gz)
- TXZ (.tar.xz)
- TZ (.tar.Z)
- ZIP (.zip)
Variables specific to CPack Archive generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. variable:: CPACK_ARCHIVE_FILE_NAME
CPACK_ARCHIVE_<component>_FILE_NAME
Package file name without extension which is added automatically depending
on the archive format.
* Mandatory : YES
* Default : ``<CPACK_PACKAGE_FILE_NAME>[-<component>].<extension>`` with
spaces replaced by '-'
.. variable:: CPACK_ARCHIVE_COMPONENT_INSTALL
Enable component packaging for CPackArchive
* Mandatory : NO
* Default : OFF
If enabled (ON) multiple packages are generated. By default a single package
containing files of all components is generated.

64
Help/cpack_gen/bundle.rst Normal file
View File

@ -0,0 +1,64 @@
CPack Bundle Generator
----------------------
CPack Bundle generator (macOS) specific options
Variables specific to CPack Bundle generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Installers built on macOS using the Bundle generator use the
aforementioned DragNDrop (``CPACK_DMG_xxx``) variables, plus the following
Bundle-specific parameters (``CPACK_BUNDLE_xxx``).
.. variable:: CPACK_BUNDLE_NAME
The name of the generated bundle. This appears in the OSX finder as the
bundle name. Required.
.. variable:: CPACK_BUNDLE_PLIST
Path to an OSX plist file that will be used for the generated bundle. This
assumes that the caller has generated or specified their own Info.plist
file. Required.
.. variable:: CPACK_BUNDLE_ICON
Path to an OSX icon file that will be used as the icon for the generated
bundle. This is the icon that appears in the OSX finder for the bundle, and
in the OSX dock when the bundle is opened. Required.
.. variable:: CPACK_BUNDLE_STARTUP_COMMAND
Path to a startup script. This is a path to an executable or script that
will be run whenever an end-user double-clicks the generated bundle in the
OSX Finder. Optional.
.. variable:: CPACK_BUNDLE_APPLE_CERT_APP
The name of your Apple supplied code signing certificate for the application.
The name usually takes the form ``Developer ID Application: [Name]`` or
``3rd Party Mac Developer Application: [Name]``. If this variable is not set
the application will not be signed.
.. variable:: CPACK_BUNDLE_APPLE_ENTITLEMENTS
The name of the ``Plist`` file that contains your apple entitlements for sandboxing
your application. This file is required for submission to the Mac App Store.
.. variable:: CPACK_BUNDLE_APPLE_CODESIGN_FILES
A list of additional files that you wish to be signed. You do not need to
list the main application folder, or the main executable. You should
list any frameworks and plugins that are included in your app bundle.
.. variable:: CPACK_BUNDLE_APPLE_CODESIGN_PARAMETER
Additional parameter that will passed to ``codesign``.
Default value: ``--deep -f``
.. variable:: CPACK_COMMAND_CODESIGN
Path to the ``codesign(1)`` command used to sign applications with an
Apple cert. This variable can be used to override the automatically
detected command (or specify its location if the auto-detection fails
to find it).

23
Help/cpack_gen/cygwin.rst Normal file
View File

@ -0,0 +1,23 @@
CPack Cygwin Generator
----------------------
Cygwin CPack generator (Cygwin).
Variables specific to CPack Cygwin generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The
following variable is specific to installers build on and/or for
Cygwin:
.. variable:: CPACK_CYGWIN_PATCH_NUMBER
The Cygwin patch number. FIXME: This documentation is incomplete.
.. variable:: CPACK_CYGWIN_PATCH_FILE
The Cygwin patch file. FIXME: This documentation is incomplete.
.. variable:: CPACK_CYGWIN_BUILD_SCRIPT
The Cygwin build script. FIXME: This documentation is incomplete.

557
Help/cpack_gen/deb.rst Normal file
View File

@ -0,0 +1,557 @@
CPack Deb Generator
-------------------
The built in (binary) CPack Deb generator (Unix only)
Variables specific to CPack Debian (DEB) generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The CPack Deb generator may be used to create Deb package using :module:`CPack`.
The CPack Deb generator is a :module:`CPack` generator thus it uses the
``CPACK_XXX`` variables used by :module:`CPack`.
The CPack Deb generator should work on any Linux host but it will produce
better deb package when Debian specific tools ``dpkg-xxx`` are usable on
the build system.
The CPack Deb generator has specific features which are controlled by the
specifics :code:`CPACK_DEBIAN_XXX` variables.
:code:`CPACK_DEBIAN_<COMPONENT>_XXXX` variables may be used in order to have
**component** specific values. Note however that ``<COMPONENT>`` refers to
the **grouping name** written in upper case. It may be either a component name
or a component GROUP name.
Here are some CPack Deb generator wiki resources that are here for historic
reasons and are no longer maintained but may still prove useful:
- https://gitlab.kitware.com/cmake/community/wikis/doc/cpack/Configuration
- https://gitlab.kitware.com/cmake/community/wikis/doc/cpack/PackageGenerators#deb-unix-only
List of CPack Deb generator specific variables:
.. variable:: CPACK_DEB_COMPONENT_INSTALL
Enable component packaging for CPackDEB
* Mandatory : NO
* Default : OFF
If enabled (ON) multiple packages are generated. By default a single package
containing files of all components is generated.
.. variable:: CPACK_DEBIAN_PACKAGE_NAME
CPACK_DEBIAN_<COMPONENT>_PACKAGE_NAME
Set Package control field (variable is automatically transformed to lower
case).
* Mandatory : YES
* Default :
- :variable:`CPACK_PACKAGE_NAME` for non-component based
installations
- :variable:`CPACK_DEBIAN_PACKAGE_NAME` suffixed with -<COMPONENT>
for component-based installations.
See https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Source
.. variable:: CPACK_DEBIAN_FILE_NAME
CPACK_DEBIAN_<COMPONENT>_FILE_NAME
Package file name.
* Mandatory : YES
* Default : ``<CPACK_PACKAGE_FILE_NAME>[-<component>].deb``
This may be set to ``DEB-DEFAULT`` to allow the CPack Deb generator to generate
package file name by itself in deb format::
<PackageName>_<VersionNumber>-<DebianRevisionNumber>_<DebianArchitecture>.deb
Alternatively provided package file name must end
with either ``.deb`` or ``.ipk`` suffix.
.. note::
Preferred setting of this variable is ``DEB-DEFAULT`` but for backward
compatibility with the CPack Deb generator in CMake prior to version 3.6 this
feature is disabled by default.
.. note::
By using non default filenames duplicate names may occur. Duplicate files
get overwritten and it is up to the packager to set the variables in a
manner that will prevent such errors.
.. variable:: CPACK_DEBIAN_PACKAGE_EPOCH
The Debian package epoch
* Mandatory : No
* Default : -
Optional number that should be incremented when changing versioning schemas
or fixing mistakes in the version numbers of older packages.
.. variable:: CPACK_DEBIAN_PACKAGE_VERSION
The Debian package version
* Mandatory : YES
* Default : :variable:`CPACK_PACKAGE_VERSION`
This variable may contain only alphanumerics (A-Za-z0-9) and the characters
. + - ~ (full stop, plus, hyphen, tilde) and should start with a digit. If
:variable:`CPACK_DEBIAN_PACKAGE_RELEASE` is not set then hyphens are not
allowed.
.. note::
For backward compatibility with CMake 3.9 and lower a failed test of this
variable's content is not a hard error when both
:variable:`CPACK_DEBIAN_PACKAGE_RELEASE` and
:variable:`CPACK_DEBIAN_PACKAGE_EPOCH` variables are not set. An author
warning is reported instead.
.. variable:: CPACK_DEBIAN_PACKAGE_RELEASE
The Debian package release - Debian revision number.
* Mandatory : No
* Default : -
This is the numbering of the DEB package itself, i.e. the version of the
packaging and not the version of the content (see
:variable:`CPACK_DEBIAN_PACKAGE_VERSION`). One may change the default value
if the previous packaging was buggy and/or you want to put here a fancy Linux
distro specific numbering.
.. variable:: CPACK_DEBIAN_PACKAGE_ARCHITECTURE
CPACK_DEBIAN_<COMPONENT>_PACKAGE_ARCHITECTURE
The Debian package architecture
* Mandatory : YES
* Default : Output of :code:`dpkg --print-architecture` (or :code:`i386`
if :code:`dpkg` is not found)
.. variable:: CPACK_DEBIAN_PACKAGE_DEPENDS
CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS
Sets the Debian dependencies of this package.
* Mandatory : NO
* Default :
- An empty string for non-component based installations
- :variable:`CPACK_DEBIAN_PACKAGE_DEPENDS` for component-based
installations.
.. note::
If :variable:`CPACK_DEBIAN_PACKAGE_SHLIBDEPS` or
more specifically :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS`
is set for this component, the discovered dependencies will be appended
to :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS` instead of
:variable:`CPACK_DEBIAN_PACKAGE_DEPENDS`. If
:variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS` is an empty string,
only the automatically discovered dependencies will be set for this
component.
Example::
set(CPACK_DEBIAN_PACKAGE_DEPENDS "libc6 (>= 2.3.1-6), libc6 (< 2.4)")
.. variable:: CPACK_DEBIAN_ENABLE_COMPONENT_DEPENDS
Sets inter component dependencies if listed with
:variable:`CPACK_COMPONENT_<compName>_DEPENDS` variables.
* Mandatory : NO
* Default : -
.. variable:: CPACK_DEBIAN_PACKAGE_MAINTAINER
The Debian package maintainer
* Mandatory : YES
* Default : :code:`CPACK_PACKAGE_CONTACT`
.. variable:: CPACK_DEBIAN_PACKAGE_DESCRIPTION
CPACK_COMPONENT_<COMPONENT>_DESCRIPTION
The Debian package description
* Mandatory : YES
* Default :
- :variable:`CPACK_DEBIAN_PACKAGE_DESCRIPTION` if set or
- :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY`
.. variable:: CPACK_DEBIAN_PACKAGE_SECTION
CPACK_DEBIAN_<COMPONENT>_PACKAGE_SECTION
Set Section control field e.g. admin, devel, doc, ...
* Mandatory : YES
* Default : "devel"
See https://www.debian.org/doc/debian-policy/ch-archive.html#s-subsections
.. variable:: CPACK_DEBIAN_ARCHIVE_TYPE
The archive format used for creating the Debian package.
* Mandatory : YES
* Default : "paxr"
Possible values are:
- paxr
- gnutar
.. note::
Default pax archive format is the most portable format and generates
packages that do not treat sparse files specially.
GNU tar format on the other hand supports longer filenames.
.. variable:: CPACK_DEBIAN_COMPRESSION_TYPE
The compression used for creating the Debian package.
* Mandatory : YES
* Default : "gzip"
Possible values are:
- lzma
- xz
- bzip2
- gzip
.. variable:: CPACK_DEBIAN_PACKAGE_PRIORITY
CPACK_DEBIAN_<COMPONENT>_PACKAGE_PRIORITY
Set Priority control field e.g. required, important, standard, optional,
extra
* Mandatory : YES
* Default : "optional"
See https://www.debian.org/doc/debian-policy/ch-archive.html#s-priorities
.. variable:: CPACK_DEBIAN_PACKAGE_HOMEPAGE
The URL of the web site for this package, preferably (when applicable) the
site from which the original source can be obtained and any additional
upstream documentation or information may be found.
* Mandatory : NO
* Default : :variable:`CMAKE_PROJECT_HOMEPAGE_URL`
.. note::
The content of this field is a simple URL without any surrounding
characters such as <>.
.. variable:: CPACK_DEBIAN_PACKAGE_SHLIBDEPS
CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS
May be set to ON in order to use :code:`dpkg-shlibdeps` to generate
better package dependency list.
* Mandatory : NO
* Default :
- :variable:`CPACK_DEBIAN_PACKAGE_SHLIBDEPS` if set or
- OFF
.. note::
You may need set :variable:`CMAKE_INSTALL_RPATH` to an appropriate value
if you use this feature, because if you don't :code:`dpkg-shlibdeps`
may fail to find your own shared libs.
See https://gitlab.kitware.com/cmake/community/wikis/doc/cmake/RPATH-handling
.. variable:: CPACK_DEBIAN_PACKAGE_DEBUG
May be set when invoking cpack in order to trace debug information
during the CPack Deb generator run.
* Mandatory : NO
* Default : -
.. variable:: CPACK_DEBIAN_PACKAGE_PREDEPENDS
CPACK_DEBIAN_<COMPONENT>_PACKAGE_PREDEPENDS
Sets the `Pre-Depends` field of the Debian package.
Like :variable:`Depends <CPACK_DEBIAN_PACKAGE_DEPENDS>`, except that it
also forces :code:`dpkg` to complete installation of the packages named
before even starting the installation of the package which declares the
pre-dependency.
* Mandatory : NO
* Default :
- An empty string for non-component based installations
- :variable:`CPACK_DEBIAN_PACKAGE_PREDEPENDS` for component-based
installations.
See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
.. variable:: CPACK_DEBIAN_PACKAGE_ENHANCES
CPACK_DEBIAN_<COMPONENT>_PACKAGE_ENHANCES
Sets the `Enhances` field of the Debian package.
Similar to :variable:`Suggests <CPACK_DEBIAN_PACKAGE_SUGGESTS>` but works
in the opposite direction: declares that a package can enhance the
functionality of another package.
* Mandatory : NO
* Default :
- An empty string for non-component based installations
- :variable:`CPACK_DEBIAN_PACKAGE_ENHANCES` for component-based
installations.
See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
.. variable:: CPACK_DEBIAN_PACKAGE_BREAKS
CPACK_DEBIAN_<COMPONENT>_PACKAGE_BREAKS
Sets the `Breaks` field of the Debian package.
When a binary package (P) declares that it breaks other packages (B),
:code:`dpkg` will not allow the package (P) which declares `Breaks` be
**unpacked** unless the packages that will be broken (B) are deconfigured
first.
As long as the package (P) is configured, the previously deconfigured
packages (B) cannot be reconfigured again.
* Mandatory : NO
* Default :
- An empty string for non-component based installations
- :variable:`CPACK_DEBIAN_PACKAGE_BREAKS` for component-based
installations.
See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-breaks
.. variable:: CPACK_DEBIAN_PACKAGE_CONFLICTS
CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONFLICTS
Sets the `Conflicts` field of the Debian package.
When one binary package declares a conflict with another using a `Conflicts`
field, :code:`dpkg` will not allow them to be unpacked on the system at
the same time.
* Mandatory : NO
* Default :
- An empty string for non-component based installations
- :variable:`CPACK_DEBIAN_PACKAGE_CONFLICTS` for component-based
installations.
See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-conflicts
.. note::
This is a stronger restriction than
:variable:`Breaks <CPACK_DEBIAN_PACKAGE_BREAKS>`, which prevents the
broken package from being configured while the breaking package is in
the "Unpacked" state but allows both packages to be unpacked at the same
time.
.. variable:: CPACK_DEBIAN_PACKAGE_PROVIDES
CPACK_DEBIAN_<COMPONENT>_PACKAGE_PROVIDES
Sets the `Provides` field of the Debian package.
A virtual package is one which appears in the `Provides` control field of
another package.
* Mandatory : NO
* Default :
- An empty string for non-component based installations
- :variable:`CPACK_DEBIAN_PACKAGE_PROVIDES` for component-based
installations.
See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-virtual
.. variable:: CPACK_DEBIAN_PACKAGE_REPLACES
CPACK_DEBIAN_<COMPONENT>_PACKAGE_REPLACES
Sets the `Replaces` field of the Debian package.
Packages can declare in their control file that they should overwrite
files in certain other packages, or completely replace other packages.
* Mandatory : NO
* Default :
- An empty string for non-component based installations
- :variable:`CPACK_DEBIAN_PACKAGE_REPLACES` for component-based
installations.
See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
.. variable:: CPACK_DEBIAN_PACKAGE_RECOMMENDS
CPACK_DEBIAN_<COMPONENT>_PACKAGE_RECOMMENDS
Sets the `Recommends` field of the Debian package.
Allows packages to declare a strong, but not absolute, dependency on other
packages.
* Mandatory : NO
* Default :
- An empty string for non-component based installations
- :variable:`CPACK_DEBIAN_PACKAGE_RECOMMENDS` for component-based
installations.
See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
.. variable:: CPACK_DEBIAN_PACKAGE_SUGGESTS
CPACK_DEBIAN_<COMPONENT>_PACKAGE_SUGGESTS
Sets the `Suggests` field of the Debian package.
Allows packages to declare a suggested package install grouping.
* Mandatory : NO
* Default :
- An empty string for non-component based installations
- :variable:`CPACK_DEBIAN_PACKAGE_SUGGESTS` for component-based
installations.
See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
.. variable:: CPACK_DEBIAN_PACKAGE_GENERATE_SHLIBS
* Mandatory : NO
* Default : OFF
Allows to generate shlibs control file automatically. Compatibility is defined by
:variable:`CPACK_DEBIAN_PACKAGE_GENERATE_SHLIBS_POLICY` variable value.
.. note::
Libraries are only considered if they have both library name and version
set. This can be done by setting SOVERSION property with
:command:`set_target_properties` command.
.. variable:: CPACK_DEBIAN_PACKAGE_GENERATE_SHLIBS_POLICY
Compatibility policy for auto-generated shlibs control file.
* Mandatory : NO
* Default : "="
Defines compatibility policy for auto-generated shlibs control file.
Possible values: "=", ">="
See https://www.debian.org/doc/debian-policy/ch-sharedlibs.html#s-sharedlibs-shlibdeps
.. variable:: CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA
CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONTROL_EXTRA
This variable allow advanced user to add custom script to the
control.tar.gz.
Typical usage is for conffiles, postinst, postrm, prerm.
* Mandatory : NO
* Default : -
Usage::
set(CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA
"${CMAKE_CURRENT_SOURCE_DIR}/prerm;${CMAKE_CURRENT_SOURCE_DIR}/postrm")
.. note::
The original permissions of the files will be used in the final
package unless the variable
:variable:`CPACK_DEBIAN_PACKAGE_CONTROL_STRICT_PERMISSION` is set.
In particular, the scripts should have the proper executable
flag prior to the generation of the package.
.. variable:: CPACK_DEBIAN_PACKAGE_CONTROL_STRICT_PERMISSION
CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONTROL_STRICT_PERMISSION
This variable indicates if the Debian policy on control files should be
strictly followed.
* Mandatory : NO
* Default : FALSE
Usage::
set(CPACK_DEBIAN_PACKAGE_CONTROL_STRICT_PERMISSION TRUE)
.. note::
This overrides the permissions on the original files, following the rules
set by Debian policy
https://www.debian.org/doc/debian-policy/ch-files.html#s-permissions-owners
.. variable:: CPACK_DEBIAN_PACKAGE_SOURCE
CPACK_DEBIAN_<COMPONENT>_PACKAGE_SOURCE
Sets the ``Source`` field of the binary Debian package.
When the binary package name is not the same as the source package name
(in particular when several components/binaries are generated from one
source) the source from which the binary has been generated should be
indicated with the field ``Source``.
* Mandatory : NO
* Default :
- An empty string for non-component based installations
- :variable:`CPACK_DEBIAN_PACKAGE_SOURCE` for component-based
installations.
See https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Source
.. note::
This value is not interpreted. It is possible to pass an optional
revision number of the referenced source package as well.
Packaging of debug information
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Dbgsym packages contain debug symbols for debugging packaged binaries.
Dbgsym packaging has its own set of variables:
.. variable:: CPACK_DEBIAN_DEBUGINFO_PACKAGE
CPACK_DEBIAN_<component>_DEBUGINFO_PACKAGE
Enable generation of dbgsym .ddeb package(s).
* Mandatory : NO
* Default : OFF
.. note::
Binaries must contain debug symbols before packaging so use either ``Debug``
or ``RelWithDebInfo`` for :variable:`CMAKE_BUILD_TYPE` variable value.
Building Debian packages on Windows
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To communicate UNIX file permissions from the install stage
to the CPack DEB generator the "cmake_mode_t" NTFS
alternate data stream (ADT) is used.
When a filesystem without ADT support is used only owner read/write
permissions can be preserved.
Reproducible packages
^^^^^^^^^^^^^^^^^^^^^
The environment variable ``SOURCE_DATE_EPOCH`` may be set to a UNIX
timestamp, defined as the number of seconds, excluding leap seconds,
since 01 Jan 1970 00:00:00 UTC. If set, the CPack Deb generator will
use its value for timestamps in the package.

101
Help/cpack_gen/dmg.rst Normal file
View File

@ -0,0 +1,101 @@
CPack DMG Generator
-------------------
DragNDrop CPack generator (macOS).
Variables specific to CPack DragNDrop generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following variables are specific to the DragNDrop installers built
on macOS:
.. variable:: CPACK_DMG_VOLUME_NAME
The volume name of the generated disk image. Defaults to
CPACK_PACKAGE_FILE_NAME.
.. variable:: CPACK_DMG_FORMAT
The disk image format. Common values are ``UDRO`` (UDIF read-only), ``UDZO`` (UDIF
zlib-compressed) or ``UDBZ`` (UDIF bzip2-compressed). Refer to ``hdiutil(1)`` for
more information on other available formats. Defaults to ``UDZO``.
.. variable:: CPACK_DMG_DS_STORE
Path to a custom ``.DS_Store`` file. This ``.DS_Store`` file can be used to
specify the Finder window position/geometry and layout (such as hidden
toolbars, placement of the icons etc.). This file has to be generated by
the Finder (either manually or through AppleScript) using a normal folder
from which the ``.DS_Store`` file can then be extracted.
.. variable:: CPACK_DMG_DS_STORE_SETUP_SCRIPT
Path to a custom AppleScript file. This AppleScript is used to generate
a ``.DS_Store`` file which specifies the Finder window position/geometry and
layout (such as hidden toolbars, placement of the icons etc.).
By specifying a custom AppleScript there is no need to use
``CPACK_DMG_DS_STORE``, as the ``.DS_Store`` that is generated by the AppleScript
will be packaged.
.. variable:: CPACK_DMG_BACKGROUND_IMAGE
Path to an image file to be used as the background. This file will be
copied to ``.background``/``background.<ext>``, where ``<ext>`` is the original image file
extension. The background image is installed into the image before
``CPACK_DMG_DS_STORE_SETUP_SCRIPT`` is executed or ``CPACK_DMG_DS_STORE`` is
installed. By default no background image is set.
.. variable:: CPACK_DMG_DISABLE_APPLICATIONS_SYMLINK
Default behaviour is to include a symlink to ``/Applications`` in the DMG.
Set this option to ``ON`` to avoid adding the symlink.
.. variable:: CPACK_DMG_SLA_DIR
Directory where license and menu files for different languages are stored.
Setting this causes CPack to look for a ``<language>.menu.txt`` and
``<language>.license.txt`` file for every language defined in
``CPACK_DMG_SLA_LANGUAGES``. If both this variable and
``CPACK_RESOURCE_FILE_LICENSE`` are set, CPack will only look for the menu
files and use the same license file for all languages.
.. variable:: CPACK_DMG_SLA_LANGUAGES
Languages for which a license agreement is provided when mounting the
generated DMG. A menu file consists of 9 lines of text. The first line is
is the name of the language itself, uppercase, in English (e.g. German).
The other lines are translations of the following strings:
- Agree
- Disagree
- Print
- Save...
- You agree to the terms of the License Agreement when you click the
"Agree" button.
- Software License Agreement
- This text cannot be saved. The disk may be full or locked, or the file
may be locked.
- Unable to print. Make sure you have selected a printer.
For every language in this list, CPack will try to find files
``<language>.menu.txt`` and ``<language>.license.txt`` in the directory
specified by the :variable:`CPACK_DMG_SLA_DIR` variable.
.. variable:: CPACK_COMMAND_HDIUTIL
Path to the ``hdiutil(1)`` command used to operate on disk image files on
macOS. This variable can be used to override the automatically detected
command (or specify its location if the auto-detection fails to find it).
.. variable:: CPACK_COMMAND_SETFILE
Path to the ``SetFile(1)`` command used to set extended attributes on files and
directories on macOS. This variable can be used to override the
automatically detected command (or specify its location if the
auto-detection fails to find it).
.. variable:: CPACK_COMMAND_REZ
Path to the ``Rez(1)`` command used to compile resources on macOS. This
variable can be used to override the automatically detected command (or
specify its location if the auto-detection fails to find it).

283
Help/cpack_gen/external.rst Normal file
View File

@ -0,0 +1,283 @@
CPack External Generator
------------------------
CPack provides many generators to create packages for a variety of platforms
and packaging systems. The intention is for CMake/CPack to be a complete
end-to-end solution for building and packaging a software project. However, it
may not always be possible to use CPack for the entire packaging process, due
to either technical limitations or policies that require the use of certain
tools. For this reason, CPack provides the "External" generator, which allows
external packaging software to take advantage of some of the functionality
provided by CPack, such as component installation and the dependency graph.
Integration with External Packaging Tools
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The CPack External generator generates a .json file containing the
CPack internal metadata, which gives external software information
on how to package the software. External packaging software may itself
invoke CPack, consume the generated metadata,
install and package files as required.
Alternatively CPack can invoke an external packaging software
through an optional custom CMake script in
:variable:`CPACK_EXT_PACKAGE_SCRIPT` instead.
Staging of installation files may also optionally be
taken care of by the generator when enabled through the
:variable:`CPACK_EXT_ENABLE_STAGING` variable.
JSON Format
^^^^^^^^^^^
The JSON metadata file contains a list of CPack components and component groups,
the various options passed to :command:`cpack_add_component` and
:command:`cpack_add_component_group`, the dependencies between the components
and component groups, and various other options passed to CPack.
The JSON's root object will always provide two fields:
``formatVersionMajor`` and ``formatVersionMinor``, which are always integers
that describe the output format of the generator. Backwards-compatible changes
to the output format (for example, adding a new field that didn't exist before)
cause the minor version to be incremented, and backwards-incompatible changes
(for example, deleting a field or changing its meaning) cause the major version
to be incremented and the minor version reset to 0. The format version is
always of the format ``major.minor``. In other words, it always has exactly two
parts, separated by a period.
You can request one or more specific versions of the output format as described
below with :variable:`CPACK_EXT_REQUESTED_VERSIONS`. The output format will
have a major version that exactly matches the requested major version, and a
minor version that is greater than or equal to the requested minor version. If
no version is requested with :variable:`CPACK_EXT_REQUESTED_VERSIONS`, the
latest known major version is used by default. Currently, the only supported
format is 1.0, which is described below.
Version 1.0
***********
In addition to the standard format fields, format version 1.0 provides the
following fields in the root:
``components``
The ``components`` field is an object with component names as the keys and
objects describing the components as the values. The component objects have
the following fields:
``name``
The name of the component. This is always the same as the key in the
``components`` object.
``displayName``
The value of the ``DISPLAY_NAME`` field passed to
:command:`cpack_add_component`.
``description``
The value of the ``DESCRIPTION`` field passed to
:command:`cpack_add_component`.
``isHidden``
True if ``HIDDEN`` was passed to :command:`cpack_add_component`, false if
it was not.
``isRequired``
True if ``REQUIRED`` was passed to :command:`cpack_add_component`, false if
it was not.
``isDisabledByDefault``
True if ``DISABLED`` was passed to :command:`cpack_add_component`, false if
it was not.
``group``
Only present if ``GROUP`` was passed to :command:`cpack_add_component`. If
so, this field is a string value containing the component's group.
``dependencies``
An array of components the component depends on. This contains the values
in the ``DEPENDS`` argument passed to :command:`cpack_add_component`. If no
``DEPENDS`` argument was passed, this is an empty list.
``installationTypes``
An array of installation types the component is part of. This contains the
values in the ``INSTALL_TYPES`` argument passed to
:command:`cpack_add_component`. If no ``INSTALL_TYPES`` argument was
passed, this is an empty list.
``isDownloaded``
True if ``DOWNLOADED`` was passed to :command:`cpack_add_component`, false
if it was not.
``archiveFile``
The name of the archive file passed with the ``ARCHIVE_FILE`` argument to
:command:`cpack_add_component`. If no ``ARCHIVE_FILE`` argument was passed,
this is an empty string.
``componentGroups``
The ``componentGroups`` field is an object with component group names as the
keys and objects describing the component groups as the values. The component
group objects have the following fields:
``name``
The name of the component group. This is always the same as the key in the
``componentGroups`` object.
``displayName``
The value of the ``DISPLAY_NAME`` field passed to
:command:`cpack_add_component_group`.
``description``
The value of the ``DESCRIPTION`` field passed to
:command:`cpack_add_component_group`.
``parentGroup``
Only present if ``PARENT_GROUP`` was passed to
:command:`cpack_add_component_group`. If so, this field is a string value
containing the component group's parent group.
``isExpandedByDefault``
True if ``EXPANDED`` was passed to :command:`cpack_add_component_group`,
false if it was not.
``isBold``
True if ``BOLD_TITLE`` was passed to :command:`cpack_add_component_group`,
false if it was not.
``components``
An array of names of components that are direct members of the group
(components that have this group as their ``GROUP``). Components of
subgroups are not included.
``subgroups``
An array of names of component groups that are subgroups of the group
(groups that have this group as their ``PARENT_GROUP``).
``installationTypes``
The ``installationTypes`` field is an object with installation type names as
the keys and objects describing the installation types as the values. The
installation type objects have the following fields:
``name``
The name of the installation type. This is always the same as the key in
the ``installationTypes`` object.
``displayName``
The value of the ``DISPLAY_NAME`` field passed to
:command:`cpack_add_install_type`.
``index``
The integer index of the installation type in the list.
``projects``
The ``projects`` field is an array of objects describing CMake projects which
comprise the CPack project. The values in this field are derived from
:variable:`CPACK_INSTALL_CMAKE_PROJECTS`. In most cases, this will be only a
single project. The project objects have the following fields:
``projectName``
The project name passed to :variable:`CPACK_INSTALL_CMAKE_PROJECTS`.
``component``
The name of the component or component set which comprises the project.
``directory``
The build directory of the CMake project. This is the directory which
contains the ``cmake_install.cmake`` script.
``subDirectory``
The subdirectory to install the project into inside the CPack package.
``packageName``
The package name given in :variable:`CPACK_PACKAGE_NAME`. Only present if
this option is set.
``packageVersion``
The package version given in :variable:`CPACK_PACKAGE_VERSION`. Only present
if this option is set.
``packageDescriptionFile``
The package description file given in
:variable:`CPACK_PACKAGE_DESCRIPTION_FILE`. Only present if this option is
set.
``packageDescriptionSummary``
The package description summary given in
:variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY`. Only present if this option is
set.
``buildConfig``
The build configuration given to CPack with the ``-C`` option. Only present
if this option is set.
``defaultDirectoryPermissions``
The default directory permissions given in
:variable:`CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS`. Only present if this
option is set.
``setDestdir``
True if :variable:`CPACK_SET_DESTDIR` is true, false if it is not.
``packagingInstallPrefix``
The install prefix given in :variable:`CPACK_PACKAGING_INSTALL_PREFIX`. Only
present if :variable:`CPACK_SET_DESTDIR` is true.
``stripFiles``
True if :variable:`CPACK_STRIP_FILES` is true, false if it is not.
``warnOnAbsoluteInstallDestination``
True if :variable:`CPACK_WARN_ON_ABSOLUTE_INSTALL_DESTINATION` is true, false
if it is not.
``errorOnAbsoluteInstallDestination``
True if :variable:`CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION` is true,
false if it is not.
Variables specific to CPack External generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. variable:: CPACK_EXT_REQUESTED_VERSIONS
This variable is used to request a specific version of the CPack External
generator. It is a list of ``major.minor`` values, separated by semicolons.
If this variable is set to a non-empty value, the CPack External generator
will iterate through each item in the list to search for a version that it
knows how to generate. Requested versions should be listed in order of
descending preference by the client software, as the first matching version
in the list will be generated.
The generator knows how to generate the version if it has a versioned
generator whose major version exactly matches the requested major version,
and whose minor version is greater than or equal to the requested minor
version. For example, if ``CPACK_EXT_REQUESTED_VERSIONS`` contains 1.0, and
the CPack External generator knows how to generate 1.1, it will generate 1.1.
If the generator doesn't know how to generate a version in the list, it skips
the version and looks at the next one. If it doesn't know how to generate any
of the requested versions, an error is thrown.
If this variable is not set, or is empty, the CPack External generator will
generate the highest major and minor version that it knows how to generate.
If an invalid version is encountered in ``CPACK_EXT_REQUESTED_VERSIONS`` (one
that doesn't match ``major.minor``, where ``major`` and ``minor`` are
integers), it is ignored.
.. variable:: CPACK_EXT_ENABLE_STAGING
This variable can be set to true to enable optional installation
into a temporary staging area which can then be picked up
and packaged by an external packaging tool.
The top level directory used by CPack for the current packaging
task is contained in ``CPACK_TOPLEVEL_DIRECTORY``.
It is automatically cleaned up on each run before packaging is initiated
and can be used for custom temporary files required by
the external packaging tool.
It also contains the staging area ``CPACK_TEMPORARY_DIRECTORY``
into which CPack performs the installation when staging is enabled.
.. variable:: CPACK_EXT_PACKAGE_SCRIPT
This variable can optionally specify the full path to
a CMake script file to be run as part of the CPack invocation.
It is invoked after (optional) staging took place and may
run an external packaging tool. The script has access to
the variables defined by the CPack config file.

138
Help/cpack_gen/freebsd.rst Normal file
View File

@ -0,0 +1,138 @@
CPack FreeBSD Generator
-----------------------
The built in (binary) CPack FreeBSD (pkg) generator (Unix only)
Variables specific to CPack FreeBSD (pkg) generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The CPack FreeBSD generator may be used to create pkg(8) packages -- these may
be used on FreeBSD, DragonflyBSD, NetBSD, OpenBSD, but also on Linux or OSX,
depending on the installed package-management tools -- using :module:`CPack`.
The CPack FreeBSD generator is a :module:`CPack` generator and uses the
``CPACK_XXX`` variables used by :module:`CPack`. It tries to re-use packaging
information that may already be specified for Debian packages for the
:cpack_gen:`CPack Deb Generator`. It also tries to re-use RPM packaging
information when Debian does not specify.
The CPack FreeBSD generator should work on any host with libpkg installed. The
packages it produces are specific to the host architecture and ABI.
The CPack FreeBSD generator sets package-metadata through
:code:`CPACK_FREEBSD_XXX` variables. The CPack FreeBSD generator, unlike the
CPack Deb generator, does not specially support componentized packages; a
single package is created from all the software artifacts created through
CMake.
All of the variables can be set specifically for FreeBSD packaging in
the CPackConfig file or in CMakeLists.txt, but most of them have defaults
that use general settings (e.g. CMAKE_PROJECT_NAME) or Debian-specific
variables when those make sense (e.g. the homepage of an upstream project
is usually unchanged by the flavor of packaging). When there is no Debian
information to fall back on, but the RPM packaging has it, fall back to
the RPM information (e.g. package license).
.. variable:: CPACK_FREEBSD_PACKAGE_NAME
Sets the package name (in the package manifest, but also affects the
output filename).
* Mandatory: YES
* Default:
- :variable:`CPACK_PACKAGE_NAME` (this is always set by CPack itself,
based on CMAKE_PROJECT_NAME).
.. variable:: CPACK_FREEBSD_PACKAGE_COMMENT
Sets the package comment. This is the short description displayed by
pkg(8) in standard "pkg info" output.
* Mandatory: YES
* Default:
- :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY` (this is always set
by CPack itself, if nothing else sets it explicitly).
- :variable:`PROJECT_DESCRIPTION` (this can be set with the DESCRIPTION
parameter for :command:`project`).
.. variable:: CPACK_FREEBSD_PACKAGE_DESCRIPTION
Sets the package description. This is the long description of the package,
given by "pkg info" with a specific package as argument.
* Mandatory: YES
* Default:
- :variable:`CPACK_DEBIAN_PACKAGE_DESCRIPTION` (this may be set already
for Debian packaging, so we may as well re-use it).
.. variable:: CPACK_FREEBSD_PACKAGE_WWW
The URL of the web site for this package, preferably (when applicable) the
site from which the original source can be obtained and any additional
upstream documentation or information may be found.
* Mandatory: YES
* Default:
- :variable:`CMAKE_PROJECT_HOMEPAGE_URL`, or if that is not set,
:variable:`CPACK_DEBIAN_PACKAGE_HOMEPAGE` (this may be set already
for Debian packaging, so we may as well re-use it).
.. variable:: CPACK_FREEBSD_PACKAGE_LICENSE
The license, or licenses, which apply to this software package. This must
be one or more license-identifiers that pkg recognizes as acceptable license
identifiers (e.g. "GPLv2").
* Mandatory: YES
* Default:
- :variable:`CPACK_RPM_PACKAGE_LICENSE`
.. variable:: CPACK_FREEBSD_PACKAGE_LICENSE_LOGIC
This variable is only of importance if there is more than one license.
The default is "single", which is only applicable to a single license.
Other acceptable values are determined by pkg -- those are "dual" or "multi" --
meaning choice (OR) or simultaneous (AND) application of the licenses.
* Mandatory: NO
* Default: single
.. variable:: CPACK_FREEBSD_PACKAGE_MAINTAINER
The FreeBSD maintainer (e.g. kde@freebsd.org) of this package.
* Mandatory: YES
* Default: none
.. variable:: CPACK_FREEBSD_PACKAGE_ORIGIN
The origin (ports label) of this package; for packages built by CPack
outside of the ports system this is of less importance. The default
puts the package somewhere under misc/, as a stopgap.
* Mandatory: YES
* Default: misc/<package name>
.. variable:: CPACK_FREEBSD_PACKAGE_CATEGORIES
The ports categories where this package lives (if it were to be built
from ports). If none is set a single category is determined based on
the package origin.
* Mandatory: YES
* Default: derived from ORIGIN
.. variable:: CPACK_FREEBSD_PACKAGE_DEPS
A list of package origins that should be added as package dependencies.
These are in the form <category>/<packagename>, e.g. x11/libkonq.
No version information needs to be provided (this is not included
in the manifest).
* Mandatory: NO
* Default: empty

335
Help/cpack_gen/ifw.rst Normal file
View File

@ -0,0 +1,335 @@
CPack IFW Generator
-------------------
See :module:`CPackIFW` for details on the CPackIFW module.
.. _QtIFW: http://doc.qt.io/qtinstallerframework/index.html
Overview
^^^^^^^^
CPack ``IFW`` generator helps you to create online and offline
binary cross-platform installers with a graphical user interface.
CPack IFW generator prepares project installation and generates configuration
and meta information for QtIFW_ tools.
The QtIFW_ provides a set of tools and utilities to create
installers for the supported desktop Qt platforms: Linux, Microsoft Windows,
and macOS.
You should also install QtIFW_ to use CPack ``IFW`` generator.
Hints
^^^^^
Generally, the CPack ``IFW`` generator automatically finds QtIFW_ tools,
but if you don't use a default path for installation of the QtIFW_ tools,
the path may be specified in either a CMake or an environment variable:
.. variable:: CPACK_IFW_ROOT
An CMake variable which specifies the location of the QtIFW_ tool suite.
The variable will be cached in the ``CPackConfig.cmake`` file and used at
CPack runtime.
.. variable:: QTIFWDIR
An environment variable which specifies the location of the QtIFW_ tool
suite.
.. note::
The specified path should not contain "bin" at the end
(for example: "D:\\DevTools\\QtIFW2.0.5").
The :variable:`CPACK_IFW_ROOT` variable has a higher priority and overrides
the value of the :variable:`QTIFWDIR` variable.
Internationalization
^^^^^^^^^^^^^^^^^^^^
Some variables and command arguments support internationalization via
CMake script. This is an optional feature.
Installers created by QtIFW_ tools have built-in support for
internationalization and many phrases are localized to many languages,
but this does not apply to the description of the your components and groups
that will be distributed.
Localization of the description of your components and groups is useful for
users of your installers.
A localized variable or argument can contain a single default value, and a
set of pairs the name of the locale and the localized value.
For example:
.. code-block:: cmake
set(LOCALIZABLE_VARIABLE "Default value"
en "English value"
en_US "American value"
en_GB "Great Britain value"
)
Variables
^^^^^^^^^
You can use the following variables to change behavior of CPack ``IFW``
generator.
Debug
"""""
.. variable:: CPACK_IFW_VERBOSE
Set to ``ON`` to enable addition debug output.
By default is ``OFF``.
Package
"""""""
.. variable:: CPACK_IFW_PACKAGE_TITLE
Name of the installer as displayed on the title bar.
By default used :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY`.
.. variable:: CPACK_IFW_PACKAGE_PUBLISHER
Publisher of the software (as shown in the Windows Control Panel).
By default used :variable:`CPACK_PACKAGE_VENDOR`.
.. variable:: CPACK_IFW_PRODUCT_URL
URL to a page that contains product information on your web site.
.. variable:: CPACK_IFW_PACKAGE_ICON
Filename for a custom installer icon. The actual file is '.icns' (macOS),
'.ico' (Windows). No functionality on Unix.
.. variable:: CPACK_IFW_PACKAGE_WINDOW_ICON
Filename for a custom window icon in PNG format for the Installer
application.
.. variable:: CPACK_IFW_PACKAGE_LOGO
Filename for a logo is used as QWizard::LogoPixmap.
.. variable:: CPACK_IFW_PACKAGE_WATERMARK
Filename for a watermark is used as QWizard::WatermarkPixmap.
.. variable:: CPACK_IFW_PACKAGE_BANNER
Filename for a banner is used as QWizard::BannerPixmap.
.. variable:: CPACK_IFW_PACKAGE_BACKGROUND
Filename for an image used as QWizard::BackgroundPixmap (only used by MacStyle).
.. variable:: CPACK_IFW_PACKAGE_WIZARD_STYLE
Wizard style to be used ("Modern", "Mac", "Aero" or "Classic").
.. variable:: CPACK_IFW_PACKAGE_WIZARD_DEFAULT_WIDTH
Default width of the wizard in pixels. Setting a banner image will override this.
.. variable:: CPACK_IFW_PACKAGE_WIZARD_DEFAULT_HEIGHT
Default height of the wizard in pixels. Setting a watermark image will override this.
.. variable:: CPACK_IFW_PACKAGE_TITLE_COLOR
Color of the titles and subtitles (takes an HTML color code, such as "#88FF33").
.. variable:: CPACK_IFW_PACKAGE_START_MENU_DIRECTORY
Name of the default program group for the product in the Windows Start menu.
By default used :variable:`CPACK_IFW_PACKAGE_NAME`.
.. variable:: CPACK_IFW_TARGET_DIRECTORY
Default target directory for installation.
By default used
"@ApplicationsDir@/:variable:`CPACK_PACKAGE_INSTALL_DIRECTORY`"
You can use predefined variables.
.. variable:: CPACK_IFW_ADMIN_TARGET_DIRECTORY
Default target directory for installation with administrator rights.
You can use predefined variables.
.. variable:: CPACK_IFW_PACKAGE_GROUP
The group, which will be used to configure the root package
.. variable:: CPACK_IFW_PACKAGE_NAME
The root package name, which will be used if configuration group is not
specified
.. variable:: CPACK_IFW_PACKAGE_MAINTENANCE_TOOL_NAME
Filename of the generated maintenance tool.
The platform-specific executable file extension is appended.
By default used QtIFW_ defaults (``maintenancetool``).
.. variable:: CPACK_IFW_PACKAGE_REMOVE_TARGET_DIR
Set to ``OFF`` if the target directory should not be deleted when uninstalling.
Is ``ON`` by default
.. variable:: CPACK_IFW_PACKAGE_MAINTENANCE_TOOL_INI_FILE
Filename for the configuration of the generated maintenance tool.
By default used QtIFW_ defaults (``maintenancetool.ini``).
.. variable:: CPACK_IFW_PACKAGE_ALLOW_NON_ASCII_CHARACTERS
Set to ``ON`` if the installation path can contain non-ASCII characters.
Is ``ON`` for QtIFW_ less 2.0 tools.
.. variable:: CPACK_IFW_PACKAGE_ALLOW_SPACE_IN_PATH
Set to ``OFF`` if the installation path cannot contain space characters.
Is ``ON`` for QtIFW_ less 2.0 tools.
.. variable:: CPACK_IFW_PACKAGE_CONTROL_SCRIPT
Filename for a custom installer control script.
.. variable:: CPACK_IFW_PACKAGE_RESOURCES
List of additional resources ('.qrc' files) to include in the installer
binary.
You can use :command:`cpack_ifw_add_package_resources` command to resolve
relative paths.
.. variable:: CPACK_IFW_PACKAGE_FILE_EXTENSION
The target binary extension.
On Linux, the name of the target binary is automatically extended with
'.run', if you do not specify the extension.
On Windows, the target is created as an application with the extension
'.exe', which is automatically added, if not supplied.
On Mac, the target is created as an DMG disk image with the extension
'.dmg', which is automatically added, if not supplied.
.. variable:: CPACK_IFW_REPOSITORIES_ALL
The list of remote repositories.
The default value of this variable is computed by CPack and contains
all repositories added with command :command:`cpack_ifw_add_repository`
or updated with command :command:`cpack_ifw_update_repository`.
.. variable:: CPACK_IFW_DOWNLOAD_ALL
If this is ``ON`` all components will be downloaded.
By default is ``OFF`` or used value
from ``CPACK_DOWNLOAD_ALL`` if set
Components
""""""""""
.. variable:: CPACK_IFW_RESOLVE_DUPLICATE_NAMES
Resolve duplicate names when installing components with groups.
.. variable:: CPACK_IFW_PACKAGES_DIRECTORIES
Additional prepared packages dirs that will be used to resolve
dependent components.
.. variable:: CPACK_IFW_REPOSITORIES_DIRECTORIES
Additional prepared repository dirs that will be used to resolve and
repack dependent components. This feature available only
since QtIFW_ 3.1.
Tools
"""""
.. variable:: CPACK_IFW_FRAMEWORK_VERSION
The version of used QtIFW_ tools.
.. variable:: CPACK_IFW_BINARYCREATOR_EXECUTABLE
The path to "binarycreator" command line client.
This variable is cached and may be configured if needed.
.. variable:: CPACK_IFW_REPOGEN_EXECUTABLE
The path to "repogen" command line client.
This variable is cached and may be configured if needed.
.. variable:: CPACK_IFW_INSTALLERBASE_EXECUTABLE
The path to "installerbase" installer executable base.
This variable is cached and may be configured if needed.
.. variable:: CPACK_IFW_DEVTOOL_EXECUTABLE
The path to "devtool" command line client.
This variable is cached and may be configured if needed.
Online installer
^^^^^^^^^^^^^^^^
By default CPack IFW generator makes offline installer. This means that all
components will be packaged into a binary file.
To make a component downloaded, you must set the ``DOWNLOADED`` option in
:command:`cpack_add_component`.
Then you would use the command :command:`cpack_configure_downloads`.
If you set ``ALL`` option all components will be downloaded.
You also can use command :command:`cpack_ifw_add_repository` and
variable :variable:`CPACK_IFW_DOWNLOAD_ALL` for more specific configuration.
CPack IFW generator creates "repository" dir in current binary dir. You
would copy content of this dir to specified ``site`` (``url``).
See Also
^^^^^^^^
Qt Installer Framework Manual:
* Index page:
http://doc.qt.io/qtinstallerframework/index.html
* Component Scripting:
http://doc.qt.io/qtinstallerframework/scripting.html
* Predefined Variables:
http://doc.qt.io/qtinstallerframework/scripting.html#predefined-variables
* Promoting Updates:
http://doc.qt.io/qtinstallerframework/ifw-updates.html
Download Qt Installer Framework for you platform from Qt site:
http://download.qt.io/official_releases/qt-installer-framework

130
Help/cpack_gen/nsis.rst Normal file
View File

@ -0,0 +1,130 @@
CPack NSIS Generator
--------------------
CPack NSIS generator specific options
Variables specific to CPack NSIS generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following variables are specific to the graphical installers built
on Windows using the Nullsoft Installation System.
.. variable:: CPACK_NSIS_INSTALL_ROOT
The default installation directory presented to the end user by the NSIS
installer is under this root dir. The full directory presented to the end
user is: ${CPACK_NSIS_INSTALL_ROOT}/${CPACK_PACKAGE_INSTALL_DIRECTORY}
.. variable:: CPACK_NSIS_MUI_ICON
An icon filename. The name of a ``*.ico`` file used as the main icon for the
generated install program.
.. variable:: CPACK_NSIS_MUI_UNIICON
An icon filename. The name of a ``*.ico`` file used as the main icon for the
generated uninstall program.
.. variable:: CPACK_NSIS_INSTALLER_MUI_ICON_CODE
undocumented.
.. variable:: CPACK_NSIS_MUI_WELCOMEFINISHPAGE_BITMAP
The filename of a bitmap to use as the NSIS MUI_WELCOMEFINISHPAGE_BITMAP.
.. variable:: CPACK_NSIS_MUI_UNWELCOMEFINISHPAGE_BITMAP
The filename of a bitmap to use as the NSIS MUI_UNWELCOMEFINISHPAGE_BITMAP.
.. variable:: CPACK_NSIS_EXTRA_PREINSTALL_COMMANDS
Extra NSIS commands that will be added to the beginning of the install
Section, before your install tree is available on the target system.
.. variable:: CPACK_NSIS_EXTRA_INSTALL_COMMANDS
Extra NSIS commands that will be added to the end of the install Section,
after your install tree is available on the target system.
.. variable:: CPACK_NSIS_EXTRA_UNINSTALL_COMMANDS
Extra NSIS commands that will be added to the uninstall Section, before
your install tree is removed from the target system.
.. variable:: CPACK_NSIS_COMPRESSOR
The arguments that will be passed to the NSIS SetCompressor command.
.. variable:: CPACK_NSIS_ENABLE_UNINSTALL_BEFORE_INSTALL
Ask about uninstalling previous versions first. If this is set to "ON",
then an installer will look for previous installed versions and if one is
found, ask the user whether to uninstall it before proceeding with the
install.
.. variable:: CPACK_NSIS_MODIFY_PATH
Modify PATH toggle. If this is set to "ON", then an extra page will appear
in the installer that will allow the user to choose whether the program
directory should be added to the system PATH variable.
.. variable:: CPACK_NSIS_DISPLAY_NAME
The display name string that appears in the Windows Add/Remove Program
control panel
.. variable:: CPACK_NSIS_PACKAGE_NAME
The title displayed at the top of the installer.
.. variable:: CPACK_NSIS_INSTALLED_ICON_NAME
A path to the executable that contains the installer icon.
.. variable:: CPACK_NSIS_HELP_LINK
URL to a web site providing assistance in installing your application.
.. variable:: CPACK_NSIS_URL_INFO_ABOUT
URL to a web site providing more information about your application.
.. variable:: CPACK_NSIS_CONTACT
Contact information for questions and comments about the installation
process.
.. variable:: CPACK_NSIS_<compName>_INSTALL_DIRECTORY
Custom install directory for the specified component <compName> instead
of $INSTDIR.
.. variable:: CPACK_NSIS_CREATE_ICONS_EXTRA
Additional NSIS commands for creating start menu shortcuts.
.. variable:: CPACK_NSIS_DELETE_ICONS_EXTRA
Additional NSIS commands to uninstall start menu shortcuts.
.. variable:: CPACK_NSIS_EXECUTABLES_DIRECTORY
Creating NSIS start menu links assumes that they are in 'bin' unless this
variable is set. For example, you would set this to 'exec' if your
executables are in an exec directory.
.. variable:: CPACK_NSIS_MUI_FINISHPAGE_RUN
Specify an executable to add an option to run on the finish page of the
NSIS installer.
.. variable:: CPACK_NSIS_MENU_LINKS
Specify links in [application] menu. This should contain a list of pair
"link" "link name". The link may be a URL or a path relative to
installation prefix. Like::
set(CPACK_NSIS_MENU_LINKS
"doc/cmake-@CMake_VERSION_MAJOR@.@CMake_VERSION_MINOR@/cmake.html"
"CMake Help" "https://cmake.org" "CMake Web Site")

189
Help/cpack_gen/nuget.rst Normal file
View File

@ -0,0 +1,189 @@
CPack NuGet Generator
---------------------
When build a NuGet package there is no direct way to control an output
filename due a lack of the corresponding CLI option of NuGet, so there
is no ``CPACK_NUGET_PACKAGE_FILENAME`` variable. To form the output filename
NuGet uses the package name and the version according to its built-in rules.
Also, be aware that including a top level directory
(``CPACK_INCLUDE_TOPLEVEL_DIRECTORY``) is ignored by this generator.
Variables specific to CPack NuGet generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The CPack NuGet generator may be used to create NuGet packages using
:module:`CPack`. The CPack NuGet generator is a :module:`CPack` generator thus
it uses the ``CPACK_XXX`` variables used by :module:`CPack`.
The CPack NuGet generator has specific features which are controlled by the
specifics :code:`CPACK_NUGET_XXX` variables. In the "one per group" mode
(see :variable:`CPACK_COMPONENTS_GROUPING`), ``<compName>`` placeholder
in the variables below would contain a group name (uppercased and turned into
a "C" identifier).
List of CPack NuGet generator specific variables:
.. variable:: CPACK_NUGET_COMPONENT_INSTALL
Enable component packaging for CPack NuGet generator
* Mandatory : NO
* Default : OFF
.. variable:: CPACK_NUGET_PACKAGE_NAME
CPACK_NUGET_<compName>_PACKAGE_NAME
The NUGET package name.
* Mandatory : YES
* Default : :variable:`CPACK_PACKAGE_NAME`
.. variable:: CPACK_NUGET_PACKAGE_VERSION
CPACK_NUGET_<compName>_PACKAGE_VERSION
The NuGet package version.
* Mandatory : YES
* Default : :variable:`CPACK_PACKAGE_VERSION`
.. variable:: CPACK_NUGET_PACKAGE_DESCRIPTION
CPACK_NUGET_<compName>_PACKAGE_DESCRIPTION
A long description of the package for UI display.
* Mandatory : YES
* Default :
- :variable:`CPACK_COMPONENT_<compName>_DESCRIPTION`,
- ``CPACK_COMPONENT_GROUP_<groupName>_DESCRIPTION``,
- :variable:`CPACK_PACKAGE_DESCRIPTION`
.. variable:: CPACK_NUGET_PACKAGE_AUTHORS
CPACK_NUGET_<compName>_PACKAGE_AUTHORS
A comma-separated list of packages authors, matching the profile names
on nuget.org_. These are displayed in the NuGet Gallery on
nuget.org_ and are used to cross-reference packages by the same
authors.
* Mandatory : YES
* Default : :variable:`CPACK_PACKAGE_VENDOR`
.. variable:: CPACK_NUGET_PACKAGE_TITLE
CPACK_NUGET_<compName>_PACKAGE_TITLE
A human-friendly title of the package, typically used in UI displays
as on nuget.org_ and the Package Manager in Visual Studio. If not
specified, the package ID is used.
* Mandatory : NO
* Default :
- :variable:`CPACK_COMPONENT_<compName>_DISPLAY_NAME`,
- ``CPACK_COMPONENT_GROUP_<groupName>_DISPLAY_NAME``
.. variable:: CPACK_NUGET_PACKAGE_OWNERS
CPACK_NUGET_<compName>_PACKAGE_OWNERS
A comma-separated list of the package creators using profile names
on nuget.org_. This is often the same list as in authors,
and is ignored when uploading the package to nuget.org_.
* Mandatory : NO
* Default : -
.. variable:: CPACK_NUGET_PACKAGE_HOMEPAGE_URL
CPACK_NUGET_<compName>_PACKAGE_HOMEPAGE_URL
A URL for the package's home page, often shown in UI displays as well
as nuget.org_.
* Mandatory : NO
* Default : :variable:`CPACK_PACKAGE_HOMEPAGE_URL`
.. variable:: CPACK_NUGET_PACKAGE_LICENSEURL
CPACK_NUGET_<compName>_PACKAGE_LICENSEURL
A URL for the package's license, often shown in UI displays as well
as nuget.org_.
* Mandatory : NO
* Default : -
.. variable:: CPACK_NUGET_PACKAGE_ICONURL
CPACK_NUGET_<compName>_PACKAGE_ICONURL
A URL for a 64x64 image with transparency background to use as the
icon for the package in UI display.
* Mandatory : NO
* Default : -
.. variable:: CPACK_NUGET_PACKAGE_DESCRIPTION_SUMMARY
CPACK_NUGET_<compName>_PACKAGE_DESCRIPTION_SUMMARY
A short description of the package for UI display. If omitted, a
truncated version of description is used.
* Mandatory : NO
* Default : :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY`
.. variable:: CPACK_NUGET_PACKAGE_RELEASE_NOTES
CPACK_NUGET_<compName>_PACKAGE_RELEASE_NOTES
A description of the changes made in this release of the package,
often used in UI like the Updates tab of the Visual Studio Package
Manager in place of the package description.
* Mandatory : NO
* Default : -
.. variable:: CPACK_NUGET_PACKAGE_COPYRIGHT
CPACK_NUGET_<compName>_PACKAGE_COPYRIGHT
Copyright details for the package.
* Mandatory : NO
* Default : -
.. variable:: CPACK_NUGET_PACKAGE_TAGS
CPACK_NUGET_<compName>_PACKAGE_TAGS
A space-delimited list of tags and keywords that describe the
package and aid discoverability of packages through search and
filtering.
* Mandatory : NO
* Default : -
.. variable:: CPACK_NUGET_PACKAGE_DEPENDENCIES
CPACK_NUGET_<compName>_PACKAGE_DEPENDENCIES
A list of package dependencies.
* Mandatory : NO
* Default : -
.. variable:: CPACK_NUGET_PACKAGE_DEPENDENCIES_<dependency>_VERSION
CPACK_NUGET_<compName>_PACKAGE_DEPENDENCIES_<dependency>_VERSION
A `version specification`_ for the particular dependency, where
``<dependency>`` is an item of the dependency list (see above)
transformed with ``MAKE_C_IDENTIFIER`` function of :command:`string`
command.
* Mandatory : NO
* Default : -
.. variable:: CPACK_NUGET_PACKAGE_DEBUG
Enable debug messages while executing CPack NuGet generator.
* Mandatory : NO
* Default : OFF
.. _nuget.org: http://nuget.org
.. _version specification: https://docs.microsoft.com/en-us/nuget/reference/package-versioning#version-ranges-and-wildcards
.. NuGet spec docs https://docs.microsoft.com/en-us/nuget/reference/nuspec

23
Help/cpack_gen/packagemaker.rst Normal file
View File

@ -0,0 +1,23 @@
CPack PackageMaker Generator
----------------------------
PackageMaker CPack generator (macOS).
Variables specific to CPack PackageMaker generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following variable is specific to installers built on Mac
macOS using PackageMaker:
.. variable:: CPACK_OSX_PACKAGE_VERSION
The version of macOS that the resulting PackageMaker archive should be
compatible with. Different versions of macOS support different
features. For example, CPack can only build component-based installers for
macOS 10.4 or newer, and can only build installers that download
component son-the-fly for macOS 10.5 or newer. If left blank, this value
will be set to the minimum version of macOS that supports the requested
features. Set this variable to some value (e.g., 10.4) only if you want to
guarantee that your installer will work on that version of macOS, and
don't mind missing extra features available in the installer shipping with
later versions of macOS.

68
Help/cpack_gen/productbuild.rst Normal file
View File

@ -0,0 +1,68 @@
CPack productbuild Generator
----------------------------
productbuild CPack generator (macOS).
Variables specific to CPack productbuild generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following variable is specific to installers built on Mac
macOS using ProductBuild:
.. variable:: CPACK_COMMAND_PRODUCTBUILD
Path to the ``productbuild(1)`` command used to generate a product archive for
the macOS Installer or Mac App Store. This variable can be used to override
the automatically detected command (or specify its location if the
auto-detection fails to find it).
.. variable:: CPACK_PRODUCTBUILD_IDENTITY_NAME
Adds a digital signature to the resulting package.
.. variable:: CPACK_PRODUCTBUILD_KEYCHAIN_PATH
Specify a specific keychain to search for the signing identity.
.. variable:: CPACK_COMMAND_PKGBUILD
Path to the ``pkgbuild(1)`` command used to generate an macOS component package
on macOS. This variable can be used to override the automatically detected
command (or specify its location if the auto-detection fails to find it).
.. variable:: CPACK_PKGBUILD_IDENTITY_NAME
Adds a digital signature to the resulting package.
.. variable:: CPACK_PKGBUILD_KEYCHAIN_PATH
Specify a specific keychain to search for the signing identity.
.. variable:: CPACK_PREFLIGHT_<COMP>_SCRIPT
Full path to a file that will be used as the ``preinstall`` script for the
named ``<COMP>`` component's package, where ``<COMP>`` is the uppercased
component name. No ``preinstall`` script is added if this variable is not
defined for a given component.
.. variable:: CPACK_POSTFLIGHT_<COMP>_SCRIPT
Full path to a file that will be used as the ``postinstall`` script for the
named ``<COMP>`` component's package, where ``<COMP>`` is the uppercased
component name. No ``postinstall`` script is added if this variable is not
defined for a given component.
.. variable:: CPACK_PRODUCTBUILD_RESOURCES_DIR
If specified the productbuild generator copies files from this directory
(including subdirectories) to the ``Resources`` directory. This is done
before the :variable:`CPACK_RESOURCE_FILE_WELCOME`,
:variable:`CPACK_RESOURCE_FILE_README`, and
:variable:`CPACK_RESOURCE_FILE_LICENSE` files are copied.

955
Help/cpack_gen/rpm.rst Normal file
View File

@ -0,0 +1,955 @@
CPack RPM Generator
-------------------
The built in (binary) CPack RPM generator (Unix only)
Variables specific to CPack RPM generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The CPack RPM generator may be used to create RPM packages using :module:`CPack`.
The CPack RPM generator is a :module:`CPack` generator thus it uses the
``CPACK_XXX`` variables used by :module:`CPack`.
The CPack RPM generator has specific features which are controlled by the specifics
:code:`CPACK_RPM_XXX` variables.
:code:`CPACK_RPM_<COMPONENT>_XXXX` variables may be used in order to have
**component** specific values. Note however that ``<COMPONENT>`` refers to the
**grouping name** written in upper case. It may be either a component name or
a component GROUP name. Usually those variables correspond to RPM spec file
entities. One may find information about spec files here
http://www.rpm.org/wiki/Docs
.. note::
`<COMPONENT>` part of variables is preferred to be in upper case (for e.g. if
component is named `foo` then use `CPACK_RPM_FOO_XXXX` variable name format)
as is with other `CPACK_<COMPONENT>_XXXX` variables.
For the purposes of back compatibility (CMake/CPack version 3.5 and lower)
support for same cased component (e.g. `fOo` would be used as
`CPACK_RPM_fOo_XXXX`) is still supported for variables defined in older
versions of CMake/CPack but is not guaranteed for variables that
will be added in the future. For the sake of back compatibility same cased
component variables also override upper cased versions where both are
present.
Here are some CPack RPM generator wiki resources that are here for historic reasons and
are no longer maintained but may still prove useful:
- https://gitlab.kitware.com/cmake/community/wikis/doc/cpack/Configuration
- https://gitlab.kitware.com/cmake/community/wikis/doc/cpack/PackageGenerators#rpm-unix-only
List of CPack RPM generator specific variables:
.. variable:: CPACK_RPM_COMPONENT_INSTALL
Enable component packaging for CPack RPM generator
* Mandatory : NO
* Default : OFF
If enabled (ON) multiple packages are generated. By default a single package
containing files of all components is generated.
.. variable:: CPACK_RPM_PACKAGE_SUMMARY
CPACK_RPM_<component>_PACKAGE_SUMMARY
The RPM package summary.
* Mandatory : YES
* Default : :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY`
.. variable:: CPACK_RPM_PACKAGE_NAME
CPACK_RPM_<component>_PACKAGE_NAME
The RPM package name.
* Mandatory : YES
* Default : :variable:`CPACK_PACKAGE_NAME`
.. variable:: CPACK_RPM_FILE_NAME
CPACK_RPM_<component>_FILE_NAME
Package file name.
* Mandatory : YES
* Default : ``<CPACK_PACKAGE_FILE_NAME>[-<component>].rpm`` with spaces
replaced by '-'
This may be set to ``RPM-DEFAULT`` to allow rpmbuild tool to generate package
file name by itself.
Alternatively provided package file name must end with ``.rpm`` suffix.
.. note::
By using user provided spec file, rpm macro extensions such as for
generating debuginfo packages or by simply using multiple components more
than one rpm file may be generated, either from a single spec file or from
multiple spec files (each component execution produces its own spec file).
In such cases duplicate file names may occur as a result of this variable
setting or spec file content structure. Duplicate files get overwritten
and it is up to the packager to set the variables in a manner that will
prevent such errors.
.. variable:: CPACK_RPM_MAIN_COMPONENT
Main component that is packaged without component suffix.
* Mandatory : NO
* Default : -
This variable can be set to any component or group name so that component or
group rpm package is generated without component suffix in filename and
package name.
.. variable:: CPACK_RPM_PACKAGE_EPOCH
The RPM package epoch
* Mandatory : No
* Default : -
Optional number that should be incremented when changing versioning schemas
or fixing mistakes in the version numbers of older packages.
.. variable:: CPACK_RPM_PACKAGE_VERSION
The RPM package version.
* Mandatory : YES
* Default : :variable:`CPACK_PACKAGE_VERSION`
.. variable:: CPACK_RPM_PACKAGE_ARCHITECTURE
CPACK_RPM_<component>_PACKAGE_ARCHITECTURE
The RPM package architecture.
* Mandatory : YES
* Default : Native architecture output by ``uname -m``
This may be set to ``noarch`` if you know you are building a noarch package.
.. variable:: CPACK_RPM_PACKAGE_RELEASE
The RPM package release.
* Mandatory : YES
* Default : 1
This is the numbering of the RPM package itself, i.e. the version of the
packaging and not the version of the content (see
:variable:`CPACK_RPM_PACKAGE_VERSION`). One may change the default value if
the previous packaging was buggy and/or you want to put here a fancy Linux
distro specific numbering.
.. note::
This is the string that goes into the RPM ``Release:`` field. Some distros
(e.g. Fedora, CentOS) require ``1%{?dist}`` format and not just a number.
``%{?dist}`` part can be added by setting :variable:`CPACK_RPM_PACKAGE_RELEASE_DIST`.
.. variable:: CPACK_RPM_PACKAGE_RELEASE_DIST
The dist tag that is added RPM ``Release:`` field.
* Mandatory : NO
* Default : OFF
This is the reported ``%{dist}`` tag from the current distribution or empty
``%{dist}`` if RPM macro is not set. If this variable is set then RPM
``Release:`` field value is set to ``${CPACK_RPM_PACKAGE_RELEASE}%{?dist}``.
.. variable:: CPACK_RPM_PACKAGE_LICENSE
The RPM package license policy.
* Mandatory : YES
* Default : "unknown"
.. variable:: CPACK_RPM_PACKAGE_GROUP
CPACK_RPM_<component>_PACKAGE_GROUP
The RPM package group.
* Mandatory : YES
* Default : "unknown"
.. variable:: CPACK_RPM_PACKAGE_VENDOR
The RPM package vendor.
* Mandatory : YES
* Default : CPACK_PACKAGE_VENDOR if set or "unknown"
.. variable:: CPACK_RPM_PACKAGE_URL
CPACK_RPM_<component>_PACKAGE_URL
The projects URL.
* Mandatory : NO
* Default : :variable:`CMAKE_PROJECT_HOMEPAGE_URL`
.. variable:: CPACK_RPM_PACKAGE_DESCRIPTION
CPACK_RPM_<component>_PACKAGE_DESCRIPTION
RPM package description.
* Mandatory : YES
* Default : :variable:`CPACK_COMPONENT_<compName>_DESCRIPTION` (component
based installers only) if set, :variable:`CPACK_PACKAGE_DESCRIPTION_FILE`
if set or "no package description available"
.. variable:: CPACK_RPM_COMPRESSION_TYPE
RPM compression type.
* Mandatory : NO
* Default : -
May be used to override RPM compression type to be used to build the
RPM. For example some Linux distribution now default to lzma or xz
compression whereas older cannot use such RPM. Using this one can enforce
compression type to be used.
Possible values are:
- lzma
- xz
- bzip2
- gzip
.. variable:: CPACK_RPM_PACKAGE_AUTOREQ
CPACK_RPM_<component>_PACKAGE_AUTOREQ
RPM spec autoreq field.
* Mandatory : NO
* Default : -
May be used to enable (1, yes) or disable (0, no) automatic shared libraries
dependency detection. Dependencies are added to requires list.
.. note::
By default automatic dependency detection is enabled by rpm generator.
.. variable:: CPACK_RPM_PACKAGE_AUTOPROV
CPACK_RPM_<component>_PACKAGE_AUTOPROV
RPM spec autoprov field.
* Mandatory : NO
* Default : -
May be used to enable (1, yes) or disable (0, no) automatic listing of shared
libraries that are provided by the package. Shared libraries are added to
provides list.
.. note::
By default automatic provides detection is enabled by rpm generator.
.. variable:: CPACK_RPM_PACKAGE_AUTOREQPROV
CPACK_RPM_<component>_PACKAGE_AUTOREQPROV
RPM spec autoreqprov field.
* Mandatory : NO
* Default : -
Variable enables/disables autoreq and autoprov at the same time.
See :variable:`CPACK_RPM_PACKAGE_AUTOREQ` and :variable:`CPACK_RPM_PACKAGE_AUTOPROV`
for more details.
.. note::
By default automatic detection feature is enabled by rpm.
.. variable:: CPACK_RPM_PACKAGE_REQUIRES
CPACK_RPM_<component>_PACKAGE_REQUIRES
RPM spec requires field.
* Mandatory : NO
* Default : -
May be used to set RPM dependencies (requires). Note that you must enclose
the complete requires string between quotes, for example::
set(CPACK_RPM_PACKAGE_REQUIRES "python >= 2.5.0, cmake >= 2.8")
The required package list of an RPM file could be printed with::
rpm -qp --requires file.rpm
.. variable:: CPACK_RPM_PACKAGE_CONFLICTS
CPACK_RPM_<component>_PACKAGE_CONFLICTS
RPM spec conflicts field.
* Mandatory : NO
* Default : -
May be used to set negative RPM dependencies (conflicts). Note that you must
enclose the complete requires string between quotes, for example::
set(CPACK_RPM_PACKAGE_CONFLICTS "libxml2")
The conflicting package list of an RPM file could be printed with::
rpm -qp --conflicts file.rpm
.. variable:: CPACK_RPM_PACKAGE_REQUIRES_PRE
CPACK_RPM_<component>_PACKAGE_REQUIRES_PRE
RPM spec requires(pre) field.
* Mandatory : NO
* Default : -
May be used to set RPM preinstall dependencies (requires(pre)). Note that
you must enclose the complete requires string between quotes, for example::
set(CPACK_RPM_PACKAGE_REQUIRES_PRE "shadow-utils, initscripts")
.. variable:: CPACK_RPM_PACKAGE_REQUIRES_POST
CPACK_RPM_<component>_PACKAGE_REQUIRES_POST
RPM spec requires(post) field.
* Mandatory : NO
* Default : -
May be used to set RPM postinstall dependencies (requires(post)). Note that
you must enclose the complete requires string between quotes, for example::
set(CPACK_RPM_PACKAGE_REQUIRES_POST "shadow-utils, initscripts")
.. variable:: CPACK_RPM_PACKAGE_REQUIRES_POSTUN
CPACK_RPM_<component>_PACKAGE_REQUIRES_POSTUN
RPM spec requires(postun) field.
* Mandatory : NO
* Default : -
May be used to set RPM postuninstall dependencies (requires(postun)). Note
that you must enclose the complete requires string between quotes, for
example::
set(CPACK_RPM_PACKAGE_REQUIRES_POSTUN "shadow-utils, initscripts")
.. variable:: CPACK_RPM_PACKAGE_REQUIRES_PREUN
CPACK_RPM_<component>_PACKAGE_REQUIRES_PREUN
RPM spec requires(preun) field.
* Mandatory : NO
* Default : -
May be used to set RPM preuninstall dependencies (requires(preun)). Note that
you must enclose the complete requires string between quotes, for example::
set(CPACK_RPM_PACKAGE_REQUIRES_PREUN "shadow-utils, initscripts")
.. variable:: CPACK_RPM_PACKAGE_SUGGESTS
CPACK_RPM_<component>_PACKAGE_SUGGESTS
RPM spec suggest field.
* Mandatory : NO
* Default : -
May be used to set weak RPM dependencies (suggests). Note that you must
enclose the complete requires string between quotes.
.. variable:: CPACK_RPM_PACKAGE_PROVIDES
CPACK_RPM_<component>_PACKAGE_PROVIDES
RPM spec provides field.
* Mandatory : NO
* Default : -
May be used to set RPM dependencies (provides). The provided package list
of an RPM file could be printed with::
rpm -qp --provides file.rpm
.. variable:: CPACK_RPM_PACKAGE_OBSOLETES
CPACK_RPM_<component>_PACKAGE_OBSOLETES
RPM spec obsoletes field.
* Mandatory : NO
* Default : -
May be used to set RPM packages that are obsoleted by this one.
.. variable:: CPACK_RPM_PACKAGE_RELOCATABLE
build a relocatable RPM.
* Mandatory : NO
* Default : CPACK_PACKAGE_RELOCATABLE
If this variable is set to TRUE or ON, the CPack RPM generator will try
to build a relocatable RPM package. A relocatable RPM may
be installed using::
rpm --prefix or --relocate
in order to install it at an alternate place see rpm(8). Note that
currently this may fail if :variable:`CPACK_SET_DESTDIR` is set to ``ON``. If
:variable:`CPACK_SET_DESTDIR` is set then you will get a warning message but
if there is file installed with absolute path you'll get unexpected behavior.
.. variable:: CPACK_RPM_SPEC_INSTALL_POST
Deprecated - use :variable:`CPACK_RPM_SPEC_MORE_DEFINE` instead.
* Mandatory : NO
* Default : -
* Deprecated: YES
May be used to override the ``__spec_install_post`` section within the
generated spec file. This affects the install step during package creation,
not during package installation. For adding operations to be performed
during package installation, use
:variable:`CPACK_RPM_POST_INSTALL_SCRIPT_FILE` instead.
.. variable:: CPACK_RPM_SPEC_MORE_DEFINE
RPM extended spec definitions lines.
* Mandatory : NO
* Default : -
May be used to add any ``%define`` lines to the generated spec file. An
example of its use is to prevent stripping of executables (but note that
this may also disable other default post install processing)::
set(CPACK_RPM_SPEC_MORE_DEFINE "%define __spec_install_post /bin/true")
.. variable:: CPACK_RPM_PACKAGE_DEBUG
Toggle CPack RPM generator debug output.
* Mandatory : NO
* Default : -
May be set when invoking cpack in order to trace debug information
during CPack RPM run. For example you may launch CPack like this::
cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -G RPM
.. variable:: CPACK_RPM_USER_BINARY_SPECFILE
CPACK_RPM_<componentName>_USER_BINARY_SPECFILE
A user provided spec file.
* Mandatory : NO
* Default : -
May be set by the user in order to specify a USER binary spec file
to be used by the CPack RPM generator instead of generating the file.
The specified file will be processed by configure_file( @ONLY).
.. variable:: CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE
Spec file template.
* Mandatory : NO
* Default : -
If set CPack will generate a template for USER specified binary
spec file and stop with an error. For example launch CPack like this::
cpack -D CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE=1 -G RPM
The user may then use this file in order to hand-craft is own
binary spec file which may be used with
:variable:`CPACK_RPM_USER_BINARY_SPECFILE`.
.. variable:: CPACK_RPM_PRE_INSTALL_SCRIPT_FILE
CPACK_RPM_PRE_UNINSTALL_SCRIPT_FILE
Path to file containing pre (un)install script.
* Mandatory : NO
* Default : -
May be used to embed a pre (un)installation script in the spec file.
The referred script file (or both) will be read and directly
put after the ``%pre`` or ``%preun`` section
If :variable:`CPACK_RPM_COMPONENT_INSTALL` is set to ON the (un)install
script for each component can be overridden with
``CPACK_RPM_<COMPONENT>_PRE_INSTALL_SCRIPT_FILE`` and
``CPACK_RPM_<COMPONENT>_PRE_UNINSTALL_SCRIPT_FILE``.
One may verify which scriptlet has been included with::
rpm -qp --scripts package.rpm
.. variable:: CPACK_RPM_POST_INSTALL_SCRIPT_FILE
CPACK_RPM_POST_UNINSTALL_SCRIPT_FILE
Path to file containing post (un)install script.
* Mandatory : NO
* Default : -
May be used to embed a post (un)installation script in the spec file.
The referred script file (or both) will be read and directly
put after the ``%post`` or ``%postun`` section.
If :variable:`CPACK_RPM_COMPONENT_INSTALL` is set to ON the (un)install
script for each component can be overridden with
``CPACK_RPM_<COMPONENT>_POST_INSTALL_SCRIPT_FILE`` and
``CPACK_RPM_<COMPONENT>_POST_UNINSTALL_SCRIPT_FILE``.
One may verify which scriptlet has been included with::
rpm -qp --scripts package.rpm
.. variable:: CPACK_RPM_USER_FILELIST
CPACK_RPM_<COMPONENT>_USER_FILELIST
* Mandatory : NO
* Default : -
May be used to explicitly specify ``%(<directive>)`` file line
in the spec file. Like ``%config(noreplace)`` or any other directive
that be found in the ``%files`` section. You can have multiple directives
per line, as in ``%attr(600,root,root) %config(noreplace)``. Since
the CPack RPM generator is generating the list of files (and directories) the
user specified files of the ``CPACK_RPM_<COMPONENT>_USER_FILELIST`` list will
be removed from the generated list. If referring to directories do
not add a trailing slash.
.. variable:: CPACK_RPM_CHANGELOG_FILE
RPM changelog file.
* Mandatory : NO
* Default : -
May be used to embed a changelog in the spec file.
The referred file will be read and directly put after the ``%changelog``
section.
.. variable:: CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST
list of path to be excluded.
* Mandatory : NO
* Default : /etc /etc/init.d /usr /usr/bin /usr/include /usr/lib
/usr/libx32 /usr/lib64 /usr/share /usr/share/aclocal
/usr/share/doc
May be used to exclude path (directories or files) from the auto-generated
list of paths discovered by CPack RPM. The default value contains a
reasonable set of values if the variable is not defined by the user. If the
variable is defined by the user then the CPack RPM generator will NOT any of
the default path. If you want to add some path to the default list then you
can use :variable:`CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST_ADDITION` variable.
.. variable:: CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST_ADDITION
additional list of path to be excluded.
* Mandatory : NO
* Default : -
May be used to add more exclude path (directories or files) from the initial
default list of excluded paths. See
:variable:`CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST`.
.. variable:: CPACK_RPM_RELOCATION_PATHS
Packages relocation paths list.
* Mandatory : NO
* Default : -
May be used to specify more than one relocation path per relocatable RPM.
Variable contains a list of relocation paths that if relative are prefixed
by the value of :variable:`CPACK_RPM_<COMPONENT>_PACKAGE_PREFIX` or by the
value of :variable:`CPACK_PACKAGING_INSTALL_PREFIX` if the component version
is not provided.
Variable is not component based as its content can be used to set a different
path prefix for e.g. binary dir and documentation dir at the same time.
Only prefixes that are required by a certain component are added to that
component - component must contain at least one file/directory/symbolic link
with :variable:`CPACK_RPM_RELOCATION_PATHS` prefix for a certain relocation
path to be added. Package will not contain any relocation paths if there are
no files/directories/symbolic links on any of the provided prefix locations.
Packages that either do not contain any relocation paths or contain
files/directories/symbolic links that are outside relocation paths print
out an ``AUTHOR_WARNING`` that RPM will be partially relocatable.
.. variable:: CPACK_RPM_<COMPONENT>_PACKAGE_PREFIX
Per component relocation path install prefix.
* Mandatory : NO
* Default : CPACK_PACKAGING_INSTALL_PREFIX
May be used to set per component :variable:`CPACK_PACKAGING_INSTALL_PREFIX`
for relocatable RPM packages.
.. variable:: CPACK_RPM_NO_INSTALL_PREFIX_RELOCATION
CPACK_RPM_NO_<COMPONENT>_INSTALL_PREFIX_RELOCATION
Removal of default install prefix from relocation paths list.
* Mandatory : NO
* Default : CPACK_PACKAGING_INSTALL_PREFIX or CPACK_RPM_<COMPONENT>_PACKAGE_PREFIX
are treated as one of relocation paths
May be used to remove CPACK_PACKAGING_INSTALL_PREFIX and CPACK_RPM_<COMPONENT>_PACKAGE_PREFIX
from relocatable RPM prefix paths.
.. variable:: CPACK_RPM_ADDITIONAL_MAN_DIRS
* Mandatory : NO
* Default : -
May be used to set additional man dirs that could potentially be compressed
by brp-compress RPM macro. Variable content must be a list of regular
expressions that point to directories containing man files or to man files
directly. Note that in order to compress man pages a path must also be
present in brp-compress RPM script and that brp-compress script must be
added to RPM configuration by the operating system.
Regular expressions that are added by default were taken from brp-compress
RPM macro:
- /usr/man/man.*
- /usr/man/.*/man.*
- /usr/info.*
- /usr/share/man/man.*
- /usr/share/man/.*/man.*
- /usr/share/info.*
- /usr/kerberos/man.*
- /usr/X11R6/man/man.*
- /usr/lib/perl5/man/man.*
- /usr/share/doc/.*/man/man.*
- /usr/lib/.*/man/man.*
.. variable:: CPACK_RPM_DEFAULT_USER
CPACK_RPM_<compName>_DEFAULT_USER
default user ownership of RPM content
* Mandatory : NO
* Default : root
Value should be user name and not UID.
Note that <compName> must be in upper-case.
.. variable:: CPACK_RPM_DEFAULT_GROUP
CPACK_RPM_<compName>_DEFAULT_GROUP
default group ownership of RPM content
* Mandatory : NO
* Default : root
Value should be group name and not GID.
Note that <compName> must be in upper-case.
.. variable:: CPACK_RPM_DEFAULT_FILE_PERMISSIONS
CPACK_RPM_<compName>_DEFAULT_FILE_PERMISSIONS
default permissions used for packaged files
* Mandatory : NO
* Default : - (system default)
Accepted values are lists with ``PERMISSIONS``. Valid permissions
are:
- OWNER_READ
- OWNER_WRITE
- OWNER_EXECUTE
- GROUP_READ
- GROUP_WRITE
- GROUP_EXECUTE
- WORLD_READ
- WORLD_WRITE
- WORLD_EXECUTE
Note that <compName> must be in upper-case.
.. variable:: CPACK_RPM_DEFAULT_DIR_PERMISSIONS
CPACK_RPM_<compName>_DEFAULT_DIR_PERMISSIONS
default permissions used for packaged directories
* Mandatory : NO
* Default : - (system default)
Accepted values are lists with PERMISSIONS. Valid permissions
are the same as for :variable:`CPACK_RPM_DEFAULT_FILE_PERMISSIONS`.
Note that <compName> must be in upper-case.
.. variable:: CPACK_RPM_INSTALL_WITH_EXEC
force execute permissions on programs and shared libraries
* Mandatory : NO
* Default : - (system default)
Force set owner, group and world execute permissions on programs and shared
libraries. This can be used for creating valid rpm packages on systems such
as Debian where shared libraries do not have execute permissions set.
.. note::
Programs and shared libraries without execute permissions are ignored during
separation of debug symbols from the binary for debuginfo packages.
Packaging of Symbolic Links
^^^^^^^^^^^^^^^^^^^^^^^^^^^
The CPack RPM generator supports packaging of symbolic links::
execute_process(COMMAND ${CMAKE_COMMAND}
-E create_symlink <relative_path_location> <symlink_name>)
install(FILES ${CMAKE_CURRENT_BINARY_DIR}/<symlink_name>
DESTINATION <symlink_location> COMPONENT libraries)
Symbolic links will be optimized (paths will be shortened if possible)
before being added to the package or if multiple relocation paths are
detected, a post install symlink relocation script will be generated.
Symbolic links may point to locations that are not packaged by the same
package (either a different component or even not packaged at all) but
those locations will be treated as if they were a part of the package
while determining if symlink should be either created or present in a
post install script - depending on relocation paths.
Symbolic links that point to locations outside packaging path produce a
warning and are treated as non relocatable permanent symbolic links.
Currently there are a few limitations though:
* For component based packaging component interdependency is not checked
when processing symbolic links. Symbolic links pointing to content of
a different component are treated the same way as if pointing to location
that will not be packaged.
* Symbolic links pointing to a location through one or more intermediate
symbolic links will not be handled differently - if the intermediate
symbolic link(s) is also on a relocatable path, relocating it during
package installation may cause initial symbolic link to point to an
invalid location.
Packaging of debug information
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Debuginfo packages contain debug symbols and sources for debugging packaged
binaries.
Debuginfo RPM packaging has its own set of variables:
.. variable:: CPACK_RPM_DEBUGINFO_PACKAGE
CPACK_RPM_<component>_DEBUGINFO_PACKAGE
Enable generation of debuginfo RPM package(s).
* Mandatory : NO
* Default : OFF
.. note::
Binaries must contain debug symbols before packaging so use either ``Debug``
or ``RelWithDebInfo`` for :variable:`CMAKE_BUILD_TYPE` variable value.
.. note::
Packages generated from packages without binary files, with binary files but
without execute permissions or without debug symbols will cause packaging
termination.
.. variable:: CPACK_BUILD_SOURCE_DIRS
Provides locations of root directories of source files from which binaries
were built.
* Mandatory : YES if :variable:`CPACK_RPM_DEBUGINFO_PACKAGE` is set
* Default : -
.. note::
For CMake project :variable:`CPACK_BUILD_SOURCE_DIRS` is set by default to
point to :variable:`CMAKE_SOURCE_DIR` and :variable:`CMAKE_BINARY_DIR` paths.
.. note::
Sources with path prefixes that do not fall under any location provided with
:variable:`CPACK_BUILD_SOURCE_DIRS` will not be present in debuginfo package.
.. variable:: CPACK_RPM_BUILD_SOURCE_DIRS_PREFIX
CPACK_RPM_<component>_BUILD_SOURCE_DIRS_PREFIX
Prefix of location where sources will be placed during package installation.
* Mandatory : YES if :variable:`CPACK_RPM_DEBUGINFO_PACKAGE` is set
* Default : "/usr/src/debug/<CPACK_PACKAGE_FILE_NAME>" and
for component packaging "/usr/src/debug/<CPACK_PACKAGE_FILE_NAME>-<component>"
.. note::
Each source path prefix is additionally suffixed by ``src_<index>`` where
index is index of the path used from :variable:`CPACK_BUILD_SOURCE_DIRS`
variable. This produces ``<CPACK_RPM_BUILD_SOURCE_DIRS_PREFIX>/src_<index>``
replacement path.
Limitation is that replaced path part must be shorter or of equal
length than the length of its replacement. If that is not the case either
:variable:`CPACK_RPM_BUILD_SOURCE_DIRS_PREFIX` variable has to be set to
a shorter path or source directories must be placed on a longer path.
.. variable:: CPACK_RPM_DEBUGINFO_EXCLUDE_DIRS
Directories containing sources that should be excluded from debuginfo packages.
* Mandatory : NO
* Default : "/usr /usr/src /usr/src/debug"
Listed paths are owned by other RPM packages and should therefore not be
deleted on debuginfo package uninstallation.
.. variable:: CPACK_RPM_DEBUGINFO_EXCLUDE_DIRS_ADDITION
Paths that should be appended to :variable:`CPACK_RPM_DEBUGINFO_EXCLUDE_DIRS`
for exclusion.
* Mandatory : NO
* Default : -
.. variable:: CPACK_RPM_DEBUGINFO_SINGLE_PACKAGE
Create a single debuginfo package even if components packaging is set.
* Mandatory : NO
* Default : OFF
When this variable is enabled it produces a single debuginfo package even if
component packaging is enabled.
When using this feature in combination with components packaging and there is
more than one component this variable requires :variable:`CPACK_RPM_MAIN_COMPONENT`
to be set.
.. note::
If none of the :variable:`CPACK_RPM_<component>_DEBUGINFO_PACKAGE` variables
is set then :variable:`CPACK_RPM_DEBUGINFO_PACKAGE` is automatically set to
``ON`` when :variable:`CPACK_RPM_DEBUGINFO_SINGLE_PACKAGE` is set.
.. variable:: CPACK_RPM_DEBUGINFO_FILE_NAME
CPACK_RPM_<component>_DEBUGINFO_FILE_NAME
Debuginfo package file name.
* Mandatory : NO
* Default : rpmbuild tool generated package file name
Alternatively provided debuginfo package file name must end with ``.rpm``
suffix and should differ from file names of other generated packages.
Variable may contain ``@cpack_component@`` placeholder which will be
replaced by component name if component packaging is enabled otherwise it
deletes the placeholder.
Setting the variable to ``RPM-DEFAULT`` may be used to explicitly set
filename generation to default.
.. note::
:variable:`CPACK_RPM_FILE_NAME` also supports rpmbuild tool generated package
file name - disabled by default but can be enabled by setting the variable to
``RPM-DEFAULT``.
Packaging of sources (SRPM)
^^^^^^^^^^^^^^^^^^^^^^^^^^^
SRPM packaging is enabled by setting :variable:`CPACK_RPM_PACKAGE_SOURCES`
variable while usually using :variable:`CPACK_INSTALLED_DIRECTORIES` variable
to provide directory containing CMakeLists.txt and source files.
For CMake projects SRPM package would be produced by executing::
cpack -G RPM --config ./CPackSourceConfig.cmake
.. note::
Produced SRPM package is expected to be built with :manual:`cmake(1)` executable
and packaged with :manual:`cpack(1)` executable so CMakeLists.txt has to be
located in root source directory and must be able to generate binary rpm
packages by executing ``cpack -G`` command. The two executables as well as
rpmbuild must also be present when generating binary rpm packages from the
produced SRPM package.
Once the SRPM package is generated it can be used to generate binary packages
by creating a directory structure for rpm generation and executing rpmbuild
tool::
mkdir -p build_dir/{BUILD,BUILDROOT,RPMS,SOURCES,SPECS,SRPMS}
rpmbuild --define "_topdir <path_to_build_dir>" --rebuild <SRPM_file_name>
Generated packages will be located in build_dir/RPMS directory or its sub
directories.
.. note::
SRPM package internally uses CPack/RPM generator to generate binary packages
so CMakeScripts.txt can decide during the SRPM to binary rpm generation step
what content the package(s) should have as well as how they should be packaged
(monolithic or components). CMake can decide this for e.g. by reading environment
variables set by the package manager before starting the process of generating
binary rpm packages. This way a single SRPM package can be used to produce
different binary rpm packages on different platforms depending on the platform's
packaging rules.
Source RPM packaging has its own set of variables:
.. variable:: CPACK_RPM_PACKAGE_SOURCES
Should the content be packaged as a source rpm (default is binary rpm).
* Mandatory : NO
* Default : OFF
.. note::
For cmake projects :variable:`CPACK_RPM_PACKAGE_SOURCES` variable is set
to ``OFF`` in CPackConfig.cmake and ``ON`` in CPackSourceConfig.cmake
generated files.
.. variable:: CPACK_RPM_SOURCE_PKG_BUILD_PARAMS
Additional command-line parameters provided to :manual:`cmake(1)` executable.
* Mandatory : NO
* Default : -
.. variable:: CPACK_RPM_SOURCE_PKG_PACKAGING_INSTALL_PREFIX
Packaging install prefix that would be provided in :variable:`CPACK_PACKAGING_INSTALL_PREFIX`
variable for producing binary RPM packages.
* Mandatory : YES
* Default : "/"
.. VARIABLE:: CPACK_RPM_BUILDREQUIRES
List of source rpm build dependencies.
* Mandatory : NO
* Default : -
May be used to set source RPM build dependencies (BuildRequires). Note that
you must enclose the complete build requirements string between quotes, for
example::
set(CPACK_RPM_BUILDREQUIRES "python >= 2.5.0, cmake >= 2.8")

284
Help/cpack_gen/wix.rst Normal file
View File

@ -0,0 +1,284 @@
CPack WiX Generator
-------------------
CPack WiX generator specific options
Variables specific to CPack WiX generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following variables are specific to the installers built on
Windows using WiX.
.. variable:: CPACK_WIX_UPGRADE_GUID
Upgrade GUID (``Product/@UpgradeCode``)
Will be automatically generated unless explicitly provided.
It should be explicitly set to a constant generated globally unique
identifier (GUID) to allow your installers to replace existing
installations that use the same GUID.
You may for example explicitly set this variable in your
CMakeLists.txt to the value that has been generated per default. You
should not use GUIDs that you did not generate yourself or which may
belong to other projects.
A GUID shall have the following fixed length syntax::
XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
(each X represents an uppercase hexadecimal digit)
.. variable:: CPACK_WIX_PRODUCT_GUID
Product GUID (``Product/@Id``)
Will be automatically generated unless explicitly provided.
If explicitly provided this will set the Product Id of your installer.
The installer will abort if it detects a pre-existing installation that
uses the same GUID.
The GUID shall use the syntax described for CPACK_WIX_UPGRADE_GUID.
.. variable:: CPACK_WIX_LICENSE_RTF
RTF License File
If CPACK_RESOURCE_FILE_LICENSE has an .rtf extension it is used as-is.
If CPACK_RESOURCE_FILE_LICENSE has an .txt extension it is implicitly
converted to RTF by the WiX Generator.
The expected encoding of the .txt file is UTF-8.
With CPACK_WIX_LICENSE_RTF you can override the license file used by the
WiX Generator in case CPACK_RESOURCE_FILE_LICENSE is in an unsupported
format or the .txt -> .rtf conversion does not work as expected.
.. variable:: CPACK_WIX_PRODUCT_ICON
The Icon shown next to the program name in Add/Remove programs.
If set, this icon is used in place of the default icon.
.. variable:: CPACK_WIX_UI_REF
This variable allows you to override the Id of the ``<UIRef>`` element
in the WiX template.
The default is ``WixUI_InstallDir`` in case no CPack components have
been defined and ``WixUI_FeatureTree`` otherwise.
.. variable:: CPACK_WIX_UI_BANNER
The bitmap will appear at the top of all installer pages other than the
welcome and completion dialogs.
If set, this image will replace the default banner image.
This image must be 493 by 58 pixels.
.. variable:: CPACK_WIX_UI_DIALOG
Background bitmap used on the welcome and completion dialogs.
If this variable is set, the installer will replace the default dialog
image.
This image must be 493 by 312 pixels.
.. variable:: CPACK_WIX_PROGRAM_MENU_FOLDER
Start menu folder name for launcher.
If this variable is not set, it will be initialized with CPACK_PACKAGE_NAME
.. variable:: CPACK_WIX_CULTURES
Language(s) of the installer
Languages are compiled into the WixUI extension library. To use them,
simply provide the name of the culture. If you specify more than one
culture identifier in a comma or semicolon delimited list, the first one
that is found will be used. You can find a list of supported languages at:
http://wix.sourceforge.net/manual-wix3/WixUI_localization.htm
.. variable:: CPACK_WIX_TEMPLATE
Template file for WiX generation
If this variable is set, the specified template will be used to generate
the WiX wxs file. This should be used if further customization of the
output is required.
If this variable is not set, the default MSI template included with CMake
will be used.
.. variable:: CPACK_WIX_PATCH_FILE
Optional list of XML files with fragments to be inserted into
generated WiX sources
This optional variable can be used to specify an XML file that the
WiX generator will use to inject fragments into its generated
source files.
Patch files understood by the CPack WiX generator
roughly follow this RELAX NG compact schema:
.. code-block:: none
start = CPackWiXPatch
CPackWiXPatch = element CPackWiXPatch { CPackWiXFragment* }
CPackWiXFragment = element CPackWiXFragment
{
attribute Id { string },
fragmentContent*
}
fragmentContent = element * - CPackWiXFragment
{
(attribute * { text } | text | fragmentContent)*
}
Currently fragments can be injected into most
Component, File, Directory and Feature elements.
The following additional special Ids can be used:
* ``#PRODUCT`` for the ``<Product>`` element.
* ``#PRODUCTFEATURE`` for the root ``<Feature>`` element.
The following example illustrates how this works.
Given that the WiX generator creates the following XML element:
.. code-block:: xml
<Component Id="CM_CP_applications.bin.my_libapp.exe" Guid="*"/>
The following XML patch file may be used to inject an Environment element
into it:
.. code-block:: xml
<CPackWiXPatch>
<CPackWiXFragment Id="CM_CP_applications.bin.my_libapp.exe">
<Environment Id="MyEnvironment" Action="set"
Name="MyVariableName" Value="MyVariableValue"/>
</CPackWiXFragment>
</CPackWiXPatch>
.. variable:: CPACK_WIX_EXTRA_SOURCES
Extra WiX source files
This variable provides an optional list of extra WiX source files (.wxs)
that should be compiled and linked. The full path to source files is
required.
.. variable:: CPACK_WIX_EXTRA_OBJECTS
Extra WiX object files or libraries
This variable provides an optional list of extra WiX object (.wixobj)
and/or WiX library (.wixlib) files. The full path to objects and libraries
is required.
.. variable:: CPACK_WIX_EXTENSIONS
This variable provides a list of additional extensions for the WiX
tools light and candle.
.. variable:: CPACK_WIX_<TOOL>_EXTENSIONS
This is the tool specific version of CPACK_WIX_EXTENSIONS.
``<TOOL>`` can be either LIGHT or CANDLE.
.. variable:: CPACK_WIX_<TOOL>_EXTRA_FLAGS
This list variable allows you to pass additional
flags to the WiX tool ``<TOOL>``.
Use it at your own risk.
Future versions of CPack may generate flags which may be in conflict
with your own flags.
``<TOOL>`` can be either LIGHT or CANDLE.
.. variable:: CPACK_WIX_CMAKE_PACKAGE_REGISTRY
If this variable is set the generated installer will create
an entry in the windows registry key
``HKEY_LOCAL_MACHINE\Software\Kitware\CMake\Packages\<PackageName>``
The value for ``<PackageName>`` is provided by this variable.
Assuming you also install a CMake configuration file this will
allow other CMake projects to find your package with
the :command:`find_package` command.
.. variable:: CPACK_WIX_PROPERTY_<PROPERTY>
This variable can be used to provide a value for
the Windows Installer property ``<PROPERTY>``
The following list contains some example properties that can be used to
customize information under
"Programs and Features" (also known as "Add or Remove Programs")
* ARPCOMMENTS - Comments
* ARPHELPLINK - Help and support information URL
* ARPURLINFOABOUT - General information URL
* ARPURLUPDATEINFO - Update information URL
* ARPHELPTELEPHONE - Help and support telephone number
* ARPSIZE - Size (in kilobytes) of the application
.. variable:: CPACK_WIX_ROOT_FEATURE_TITLE
Sets the name of the root install feature in the WIX installer. Same as
CPACK_COMPONENT_<compName>_DISPLAY_NAME for components.
.. variable:: CPACK_WIX_ROOT_FEATURE_DESCRIPTION
Sets the description of the root install feature in the WIX installer. Same as
CPACK_COMPONENT_<compName>_DESCRIPTION for components.
.. variable:: CPACK_WIX_SKIP_PROGRAM_FOLDER
If this variable is set to true, the default install location
of the generated package will be CPACK_PACKAGE_INSTALL_DIRECTORY directly.
The install location will not be located relatively below
ProgramFiles or ProgramFiles64.
.. note::
Installers created with this feature do not take differences
between the system on which the installer is created
and the system on which the installer might be used into account.
It is therefore possible that the installer e.g. might try to install
onto a drive that is unavailable or unintended or a path that does not
follow the localization or convention of the system on which the
installation is performed.
.. variable:: CPACK_WIX_ROOT_FOLDER_ID
This variable allows specification of a custom root folder ID.
The generator specific ``<64>`` token can be used for
folder IDs that come in 32-bit and 64-bit variants.
In 32-bit builds the token will expand empty while in 64-bit builds
it will expand to ``64``.
When unset generated installers will default installing to
``ProgramFiles<64>Folder``.
.. variable:: CPACK_WIX_ROOT
This variable can optionally be set to the root directory
of a custom WiX Toolset installation.
When unspecified CPack will try to locate a WiX Toolset
installation via the ``WIX`` environment variable instead.

9
Help/dev/maint.rst
View File

@ -51,15 +51,18 @@ using a local branch named ``release-$ver``, where ``$ver`` is the version
number of the current release in the form ``$major.$minor``. It is always
merged into ``master`` before publishing.
To merge some ``$topic`` branch into ``release``, first create the local
branch:
Before merging a ``$topic`` branch into ``release``, verify that the
``$topic`` branch has already been merged to ``master`` via the usual
``Do: merge`` process. Then, to merge the ``$topic`` branch into
``release``, start by creating the local branch:
.. code-block:: shell
git fetch origin
git checkout -b release-$ver origin/release
Merge the ``$topic`` branch into the local ``release-$ver`` branch:
Merge the ``$topic`` branch into the local ``release-$ver`` branch, making
sure to include a ``Merge-request: !xxxx`` footer in the commit message:
.. code-block:: shell

3
Help/dev/testing.rst
View File

@ -26,13 +26,14 @@ commands to set up a new integration testing client:
$ git clone https://gitlab.kitware.com/cmake/dashboard-scripts.git CMakeScripts
$ cd CMakeScripts
The ``cmake_common.cmake`` script contains comments at the top with
The `cmake_common.cmake`_ script contains comments at the top with
instructions to set up a testing client. As it instructs, create a
CTest script with local settings and include ``cmake_common.cmake``.
.. _`CMake Review Process`: review.rst
.. _`CMake CDash Page`: https://open.cdash.org/index.php?project=CMake
.. _`CMake Dashboard Scripts Repository`: https://gitlab.kitware.com/cmake/dashboard-scripts
.. _`cmake_common.cmake`: https://gitlab.kitware.com/cmake/dashboard-scripts/blob/master/cmake_common.cmake
Nightly Start Time
------------------

2
Help/envvar/CMAKE_OSX_ARCHITECTURES.rst
View File

@ -1,7 +1,7 @@
CMAKE_OSX_ARCHITECTURES
-----------------------
Target specific architectures for OS X.
Target specific architectures for macOS.
The ``CMAKE_OSX_ARCHITECTURES`` environment variable sets the default value for
the :variable:`CMAKE_OSX_ARCHITECTURES` variable. See

14
Help/envvar/CTEST_PROGRESS_OUTPUT.rst Normal file
View File

@ -0,0 +1,14 @@
CTEST_PROGRESS_OUTPUT
---------------------
Boolean environment variable that affects how :manual:`ctest <ctest(1)>`
command output reports overall progress. When set to 1, TRUE, ON or anything
else that evaluates to boolean true, progress is reported by repeatedly
updating the same line. This greatly reduces the overall verbosity, but is
only supported when output is sent directly to a terminal. If the environment
variable is not set or has a value that evaluates to false, output is reported
normally with each test having its own start and end lines logged to the
output.
The ``--progress`` option to :manual:`ctest <ctest(1)>` overrides this
environment variable if both are given.

4
Help/envvar/CUDAHOSTCXX.rst
View File

@ -7,3 +7,7 @@ determine ``CUDA`` host compiler, after which the value for ``CUDAHOSTCXX`` is
stored in the cache as :variable:`CMAKE_CUDA_HOST_COMPILER`. For any
configuration run (including the first), the environment variable will be
ignored if the :variable:`CMAKE_CUDA_HOST_COMPILER` variable is defined.
This environment variable is primarily meant for use with projects that
enable ``CUDA`` as a first-class language. The :module:`FindCUDA`
module will also use it to initialize its ``CUDA_HOST_COMPILER`` setting.

2
Help/envvar/MACOSX_DEPLOYMENT_TARGET.rst
View File

@ -1,7 +1,7 @@
MACOSX_DEPLOYMENT_TARGET
------------------------
Specify the minimum version of OS X on which the target binaries are
Specify the minimum version of macOS on which the target binaries are
to be deployed.
The ``MACOSX_DEPLOYMENT_TARGET`` environment variable sets the default value for

40
Help/generator/Green Hills MULTI.rst
View File

@ -3,12 +3,48 @@ Green Hills MULTI
Generates Green Hills MULTI project files (experimental, work-in-progress).
Customizations are available through the following cache variables:
Customizations that are used to pick toolset and target system:
The ``-A <arch>`` can be supplied for setting the target architecture.
``<arch>`` usually is one of "arm", "ppc", "86", etcetera. If the target architecture
is not specified then the default architecture of "arm" will be used.
The ``-T <toolset>`` can be supplied for setting the toolset to be used.
All toolsets are expected to be located at ``GHS_TOOLSET_ROOT``.
If the toolset is not specified then the latest toolset will be used.
* ``GHS_TARGET_PLATFORM``
Default to ``integrity``.
Usual values are ``integrity``, ``threadx``, ``uvelosity``,
``velosity``, ``vxworks``, ``standalone``.
* ``GHS_PRIMARY_TARGET``
Sets ``primaryTarget`` field in project file.
Defaults to ``<arch>_<GHS_TARGET_PLATFORM>.tgt``.
* ``GHS_TOOLSET_ROOT``
Default to ``C:/ghs``. Root path for ``toolset``.
* ``GHS_OS_ROOT``
Default to ``C:/ghs``. Root path for RTOS searches.
* ``GHS_OS_DIR``
Default to latest platform OS installation at ``GHS_OS_ROOT``. Set this value if
a specific RTOS is to be used.
* ``GHS_BSP_NAME``
Defaults to ``sim<arch>`` if not set by user.
Customizations are available through the following cache variables:
* ``GHS_CUSTOMIZATION``
* ``GHS_GPJ_MACROS``
* ``GHS_OS_DIR``
.. note::
This generator is deemed experimental as of CMake |release|

27
Help/generator/Visual Studio 10 2010.rst
View File

@ -3,11 +3,29 @@ Visual Studio 10 2010
Generates Visual Studio 10 (VS 2010) project files.
The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set
to specify a target platform name (architecture).
For compatibility with CMake versions prior to 3.0, one may specify this
generator using the name ``Visual Studio 10`` without the year component.
Project Types
^^^^^^^^^^^^^
Only Visual C++ and C# projects may be generated. Other types of
projects (Database, Website, etc.) are not supported.
Platform Selection
^^^^^^^^^^^^^^^^^^
The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps
via the :manual:`cmake(1)` ``-A`` option, to specify a target platform
name (architecture). For example:
* ``cmake -G "Visual Studio 10 2010" -A Win32``
* ``cmake -G "Visual Studio 10 2010" -A x64``
* ``cmake -G "Visual Studio 10 2010" -A Itanium``
For compatibility with CMake versions prior to 3.1, one may specify
a target platform name optionally at the end of this generator name:
a target platform name optionally at the end of the generator name.
This is supported only for:
``Visual Studio 10 2010 Win64``
Specify target platform ``x64``.
@ -15,9 +33,6 @@ a target platform name optionally at the end of this generator name:
``Visual Studio 10 2010 IA64``
Specify target platform ``Itanium``.
For compatibility with CMake versions prior to 3.0, one may specify this
generator using the name ``Visual Studio 10`` without the year component.
Toolset Selection
^^^^^^^^^^^^^^^^^

29
Help/generator/Visual Studio 11 2012.rst
View File

@ -3,11 +3,31 @@ Visual Studio 11 2012
Generates Visual Studio 11 (VS 2012) project files.
The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set
to specify a target platform name (architecture).
For compatibility with CMake versions prior to 3.0, one may specify this
generator using the name "Visual Studio 11" without the year component.
Project Types
^^^^^^^^^^^^^
Only Visual C++ and C# projects may be generated. Other types of
projects (JavaScript, Database, Website, etc.) are not supported.
Platform Selection
^^^^^^^^^^^^^^^^^^
The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps
via the :manual:`cmake(1)` ``-A`` option, to specify a target platform
name (architecture). For example:
* ``cmake -G "Visual Studio 11 2012" -A Win32``
* ``cmake -G "Visual Studio 11 2012" -A x64``
* ``cmake -G "Visual Studio 11 2012" -A ARM``
* ``cmake -G "Visual Studio 11 2012" -A <WinCE-SDK>``
(Specify a target platform matching a Windows CE SDK name.)
For compatibility with CMake versions prior to 3.1, one may specify
a target platform name optionally at the end of this generator name:
a target platform name optionally at the end of the generator name.
This is supported only for:
``Visual Studio 11 2012 Win64``
Specify target platform ``x64``.
@ -18,9 +38,6 @@ a target platform name optionally at the end of this generator name:
``Visual Studio 11 2012 <WinCE-SDK>``
Specify target platform matching a Windows CE SDK name.
For compatibility with CMake versions prior to 3.0, one may specify this
generator using the name "Visual Studio 11" without the year component.
Toolset Selection
^^^^^^^^^^^^^^^^^

27
Help/generator/Visual Studio 12 2013.rst
View File

@ -3,11 +3,29 @@ Visual Studio 12 2013
Generates Visual Studio 12 (VS 2013) project files.
The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set
to specify a target platform name (architecture).
For compatibility with CMake versions prior to 3.0, one may specify this
generator using the name "Visual Studio 12" without the year component.
Project Types
^^^^^^^^^^^^^
Only Visual C++ and C# projects may be generated. Other types of
projects (JavaScript, Powershell, Python, etc.) are not supported.
Platform Selection
^^^^^^^^^^^^^^^^^^
The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps
via the :manual:`cmake(1)` ``-A`` option, to specify a target platform
name (architecture). For example:
* ``cmake -G "Visual Studio 12 2013" -A Win32``
* ``cmake -G "Visual Studio 12 2013" -A x64``
* ``cmake -G "Visual Studio 12 2013" -A ARM``
For compatibility with CMake versions prior to 3.1, one may specify
a target platform name optionally at the end of this generator name:
a target platform name optionally at the end of the generator name.
This is supported only for:
``Visual Studio 12 2013 Win64``
Specify target platform ``x64``.
@ -15,9 +33,6 @@ a target platform name optionally at the end of this generator name:
``Visual Studio 12 2013 ARM``
Specify target platform ``ARM``.
For compatibility with CMake versions prior to 3.0, one may specify this
generator using the name "Visual Studio 12" without the year component.
Toolset Selection
^^^^^^^^^^^^^^^^^

21
Help/generator/Visual Studio 14 2015.rst
View File

@ -3,11 +3,26 @@ Visual Studio 14 2015
Generates Visual Studio 14 (VS 2015) project files.
The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set
to specify a target platform name (architecture).
Project Types
^^^^^^^^^^^^^
Only Visual C++ and C# projects may be generated. Other types of
projects (JavaScript, Powershell, Python, etc.) are not supported.
Platform Selection
^^^^^^^^^^^^^^^^^^
The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps
via the :manual:`cmake(1)` ``-A`` option, to specify a target platform
name (architecture). For example:
* ``cmake -G "Visual Studio 14 2015" -A Win32``
* ``cmake -G "Visual Studio 14 2015" -A x64``
* ``cmake -G "Visual Studio 14 2015" -A ARM``
For compatibility with CMake versions prior to 3.1, one may specify
a target platform name optionally at the end of this generator name:
a target platform name optionally at the end of the generator name.
This is supported only for:
``Visual Studio 14 2015 Win64``
Specify target platform ``x64``.

36
Help/generator/Visual Studio 15 2017.rst
View File

@ -3,17 +3,11 @@ Visual Studio 15 2017
Generates Visual Studio 15 (VS 2017) project files.
The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set
to specify a target platform name (architecture).
Project Types
^^^^^^^^^^^^^
For compatibility with CMake versions prior to 3.1, one may specify
a target platform name optionally at the end of this generator name:
``Visual Studio 15 2017 Win64``
Specify target platform ``x64``.
``Visual Studio 15 2017 ARM``
Specify target platform ``ARM``.
Only Visual C++ and C# projects may be generated. Other types of
projects (JavaScript, Powershell, Python, etc.) are not supported.
Instance Selection
^^^^^^^^^^^^^^^^^^
@ -31,6 +25,28 @@ one of the instances, that instance will be used. Otherwise, if more
than one instance is installed we do not define which one is chosen
by default.
Platform Selection
^^^^^^^^^^^^^^^^^^
The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps
via the :manual:`cmake(1)` ``-A`` option, to specify a target platform
name (architecture). For example:
* ``cmake -G "Visual Studio 15 2017" -A Win32``
* ``cmake -G "Visual Studio 15 2017" -A x64``
* ``cmake -G "Visual Studio 15 2017" -A ARM``
* ``cmake -G "Visual Studio 15 2017" -A ARM64``
For compatibility with CMake versions prior to 3.1, one may specify
a target platform name optionally at the end of the generator name.
This is supported only for:
``Visual Studio 15 2017 Win64``
Specify target platform ``x64``.
``Visual Studio 15 2017 ARM``
Specify target platform ``ARM``.
Toolset Selection
^^^^^^^^^^^^^^^^^

17
Help/generator/Visual Studio 9 2008.rst
View File

@ -3,11 +3,22 @@ Visual Studio 9 2008
Generates Visual Studio 9 2008 project files.
The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set
to specify a target platform name.
Platform Selection
^^^^^^^^^^^^^^^^^^
The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps
via the :manual:`cmake(1)` ``-A`` option, to specify a target platform
name (architecture). For example:
* ``cmake -G "Visual Studio 9 2008" -A Win32``
* ``cmake -G "Visual Studio 9 2008" -A x64``
* ``cmake -G "Visual Studio 9 2008" -A Itanium``
* ``cmake -G "Visual Studio 9 2008" -A <WinCE-SDK>``
(Specify a target platform matching a Windows CE SDK name.)
For compatibility with CMake versions prior to 3.1, one may specify
a target platform name optionally at the end of this generator name:
a target platform name optionally at the end of the generator name.
This is supported only for:
``Visual Studio 9 2008 Win64``
Specify target platform ``x64``.

1
Help/index.rst
View File

@ -41,6 +41,7 @@ Reference Manuals
/manual/cmake-server.7
/manual/cmake-toolchains.7
/manual/cmake-variables.7
/manual/cpack-generators.7
.. only:: html or text

8
Help/manual/OPTIONS_BUILD.txt
View File

@ -1,3 +1,11 @@
``-S <path-to-source>``
Path to root directory of the CMake project to build.
``-B <path-to-build>``
Path to directory which CMake will use as the root of build directory.
If the directory doesn't already exist CMake will make it.
``-C <initial-cache>``
Pre-load a script to populate the cache.

4
Help/manual/cmake-buildsystem.7.rst
View File

@ -95,7 +95,7 @@ Apple Frameworks
""""""""""""""""
A ``SHARED`` library may be marked with the :prop_tgt:`FRAMEWORK`
target property to create an OS X or iOS Framework Bundle.
target property to create an macOS or iOS Framework Bundle.
The ``MACOSX_FRAMEWORK_IDENTIFIER`` sets ``CFBundleIdentifier`` key
and it uniquely identifies the bundle.
@ -784,7 +784,7 @@ A *library* output artifact of a buildsystem target may be:
with the ``MODULE`` option.
* On non-DLL platforms: the shared library file (e.g. ``.so`` or ``.dylib``)
of a shared shared library target created by the :command:`add_library`
of a shared library target created by the :command:`add_library`
command with the ``SHARED`` option.
The :prop_tgt:`LIBRARY_OUTPUT_DIRECTORY` and :prop_tgt:`LIBRARY_OUTPUT_NAME`

3
Help/manual/cmake-commands.7.rst
View File

@ -78,6 +78,7 @@ These commands are available only in CMake projects.
/command/add_dependencies
/command/add_executable
/command/add_library
/command/add_link_options
/command/add_subdirectory
/command/add_test
/command/aux_source_directory
@ -110,7 +111,9 @@ These commands are available only in CMake projects.
/command/target_compile_features
/command/target_compile_options
/command/target_include_directories
/command/target_link_directories
/command/target_link_libraries
/command/target_link_options
/command/target_sources
/command/try_compile
/command/try_run

6
Help/manual/cmake-developer.7.rst
View File

@ -579,11 +579,11 @@ file and the ``Help/manual/cmake-modules.7.rst`` toctree entry.
Find Modules
------------
A "find module" is a ``Modules/Find<package>.cmake`` file to be loaded
by the :command:`find_package` command when invoked for ``<package>``.
A "find module" is a ``Modules/Find<PackageName>.cmake`` file to be loaded
by the :command:`find_package` command when invoked for ``<PackageName>``.
The primary task of a find module is to determine whether a package
exists on the system, set the ``<package>_FOUND`` variable to reflect
exists on the system, set the ``<PackageName>_FOUND`` variable to reflect
this and provide any variables, macros and imported targets required to
use the package. A find module is useful in cases where an upstream
library does not provide a

1
Help/manual/cmake-env-variables.7.rst
View File

@ -53,5 +53,6 @@ Environment Variables for CTest
/envvar/CTEST_INTERACTIVE_DEBUG_MODE
/envvar/CTEST_OUTPUT_ON_FAILURE
/envvar/CTEST_PARALLEL_LEVEL
/envvar/CTEST_PROGRESS_OUTPUT
/envvar/CTEST_USE_LAUNCHERS_DEFAULT
/envvar/DASHBOARD_TEST_FROM_CTEST

7
Help/manual/cmake-generator-expressions.7.rst
View File

@ -51,7 +51,7 @@ Available logical expressions are:
``0`` if all ``?`` are ``0``, else ``1``
``$<NOT:?>``
``0`` if ``?`` is ``1``, else ``1``
``$<IF:?,true-value...,false-value...>```
``$<IF:?,true-value...,false-value...>``
``true-value...`` if ``?`` is ``1``, ``false-value...`` if ``?`` is ``0``
``$<STREQUAL:a,b>``
``1`` if ``a`` is STREQUAL ``b``, else ``0``
@ -68,10 +68,13 @@ Available logical expressions are:
target.
``$<PLATFORM_ID:comp>``
``1`` if the CMake-id of the platform matches ``comp``, otherwise ``0``.
See also the :variable:`CMAKE_SYSTEM_NAME` variable.
``$<C_COMPILER_ID:comp>``
``1`` if the CMake-id of the C compiler matches ``comp``, otherwise ``0``.
See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable.
``$<CXX_COMPILER_ID:comp>``
``1`` if the CMake-id of the CXX compiler matches ``comp``, otherwise ``0``.
See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable.
``$<VERSION_LESS:v1,v2>``
``1`` if ``v1`` is a version less than ``v2``, else ``0``.
``$<VERSION_GREATER:v1,v2>``
@ -84,8 +87,10 @@ Available logical expressions are:
``1`` if ``v1`` is a version greater than or equal to ``v2``, else ``0``.
``$<C_COMPILER_VERSION:ver>``
``1`` if the version of the C compiler matches ``ver``, otherwise ``0``.
See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable.
``$<CXX_COMPILER_VERSION:ver>``
``1`` if the version of the CXX compiler matches ``ver``, otherwise ``0``.
See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable.
``$<TARGET_POLICY:pol>``
``1`` if the policy ``pol`` was NEW when the 'head' target was created,
else ``0``. If the policy was not set, the warning message for the policy

12
Help/manual/cmake-language.7.rst
View File

@ -391,14 +391,20 @@ inside out, e.g. ``${outer_${inner_variable}_variable}``.
Literal variable references may consist of alphanumeric characters,
the characters ``/_.+-``, and `Escape Sequences`_. Nested references
may be used to evaluate variables of any name. (See also policy
:policy:`CMP0053` documentation for historical considerations.)
may be used to evaluate variables of any name. See also policy
:policy:`CMP0053` documentation for historical considerations and reasons why
the ``$`` is also technically permitted but is discouraged.
The `Variables`_ section documents the scope of variable names
and how their values are set.
An *environment variable reference* has the form ``$ENV{VAR}`` and
is evaluated in the same contexts as a normal variable reference.
See :variable:`ENV` for more information.
A *cache variable reference* has the form ``$CACHE{VAR}`` and
is evaluated in the same contexts as a normal variable reference.
See :variable:`CACHE` for more information.
Comments
--------
@ -543,6 +549,8 @@ to the binding in the current directory scope, if any. If a
is found, or no binding is found, CMake then searches for a
cache entry. If a cache entry is found, its value is used.
Otherwise, the variable reference evaluates to an empty string.
The ``$CACHE{VAR}`` syntax can be used to do direct cache entry
lookups.
The :manual:`cmake-variables(7)` manual documents many variables
that are provided by CMake or have meaning to CMake when set

35
Help/manual/cmake-modules.7.rst
View File

@ -54,22 +54,10 @@ All Modules
/module/CMakePrintSystemInformation
/module/CMakePushCheckState
/module/CMakeVerifyManifest
/module/CPackArchive
/module/CPackBundle
/module/CPackComponent
/module/CPackCygwin
/module/CPackDeb
/module/CPackDMG
/module/CPackFreeBSD
/module/CPackIFW
/module/CPackIFWConfigureFile
/module/CPackNSIS
/module/CPackNuGet
/module/CPackPackageMaker
/module/CPackProductBuild
/module/CPackRPM
/module/CPack
/module/CPackWIX
/module/CSharpUtilities
/module/CTest
/module/CTestCoverageCollectGCOV
@ -263,3 +251,26 @@ All Modules
/module/Use_wxWindows
/module/WriteBasicConfigVersionFile
/module/WriteCompilerDetectionHeader
Legacy CPack Modules
====================
These modules used to be mistakenly exposed to the user, and have been moved
out of user visibility. They are for CPack internal use, and should never be
used directly.
.. toctree::
:maxdepth: 1
/module/CPackArchive
/module/CPackBundle
/module/CPackCygwin
/module/CPackDeb
/module/CPackDMG
/module/CPackFreeBSD
/module/CPackNSIS
/module/CPackNuGet
/module/CPackPackageMaker
/module/CPackProductBuild
/module/CPackRPM
/module/CPackWIX

50
Help/manual/cmake-packages.7.rst
View File

@ -73,7 +73,7 @@ Handling of ``COMPONENTS`` and ``OPTIONAL_COMPONENTS`` is defined by the
package.
By setting the :variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable to
``TRUE``, the ``PackageName`` package will not be searched, and will always
``TRUE``, the ``<PackageName>`` package will not be searched, and will always
be ``NOTFOUND``.
.. _`Config File Packages`:
@ -92,9 +92,9 @@ packages, that is, they belong with the header files and any other files
provided to assist downstreams in using the package.
A set of variables which provide package status information are also set
automatically when using a config-file package. The ``<Package>_FOUND``
automatically when using a config-file package. The ``<PackageName>_FOUND``
variable is set to true or false, depending on whether the package was
found. The ``<Package>_DIR`` cache variable is set to the location of the
found. The ``<PackageName>_DIR`` cache variable is set to the location of the
package configuration file.
Find-module Packages
@ -108,10 +108,10 @@ file, it is not shipped with upstream, but is used by downstream to find the
files by guessing locations of files with platform-specific hints.
Unlike the case of an upstream-provided package configuration file, no single point
of reference identifies the package as being found, so the ``<Package>_FOUND``
of reference identifies the package as being found, so the ``<PackageName>_FOUND``
variable is not automatically set by the :command:`find_package` command. It
can still be expected to be set by convention however and should be set by
the author of the Find-module. Similarly there is no ``<Package>_DIR`` variable,
the author of the Find-module. Similarly there is no ``<PackageName>_DIR`` variable,
but each of the artifacts such as library locations and header file locations
provide a separate cache variable.
@ -197,7 +197,7 @@ When the :command:`find_package` command loads a version file it first sets the
following variables:
``PACKAGE_FIND_NAME``
The <package> name
The ``<PackageName>``
``PACKAGE_FIND_VERSION``
Full requested version string
@ -240,26 +240,26 @@ variables. When the version file claims to be an acceptable match for the
requested version the find_package command sets the following variables for
use by the project:
``<package>_VERSION``
``<PackageName>_VERSION``
Full provided version string
``<package>_VERSION_MAJOR``
``<PackageName>_VERSION_MAJOR``
Major version if provided, else 0
``<package>_VERSION_MINOR``
``<PackageName>_VERSION_MINOR``
Minor version if provided, else 0
``<package>_VERSION_PATCH``
``<PackageName>_VERSION_PATCH``
Patch version if provided, else 0
``<package>_VERSION_TWEAK``
``<PackageName>_VERSION_TWEAK``
Tweak version if provided, else 0
``<package>_VERSION_COUNT``
``<PackageName>_VERSION_COUNT``
Number of version components, 0 to 4
The variables report the version of the package that was actually found.
The ``<package>`` part of their name matches the argument given to the
The ``<PackageName>`` part of their name matches the argument given to the
:command:`find_package` command.
.. _`Creating Packages`:
@ -347,8 +347,8 @@ The :module:`CMakePackageConfigHelpers` module provides a macro for creating
a simple ``ConfigVersion.cmake`` file. This file sets the version of the
package. It is read by CMake when :command:`find_package` is called to
determine the compatibility with the requested version, and to set some
version-specific variables ``<Package>_VERSION``, ``<Package>_VERSION_MAJOR``,
``<Package>_VERSION_MINOR`` etc. The :command:`install(EXPORT)` command is
version-specific variables ``<PackageName>_VERSION``, ``<PackageName>_VERSION_MAJOR``,
``<PackageName>_VERSION_MINOR`` etc. The :command:`install(EXPORT)` command is
used to export the targets in the ``ClimbingStatsTargets`` export-set, defined
previously by the :command:`install(TARGETS)` command. This command generates
the ``ClimbingStatsTargets.cmake`` file to contain :prop_tgt:`IMPORTED`
@ -432,8 +432,8 @@ the dependency is not found, along with a diagnostic that the ``ClimbingStats``
package can not be used without the ``Stats`` package.
If ``COMPONENTS`` are specified when the downstream uses :command:`find_package`,
they are listed in the ``<Package>_FIND_COMPONENTS`` variable. If a particular
component is non-optional, then the ``<Package>_FIND_REQUIRED_<comp>`` will
they are listed in the ``<PackageName>_FIND_COMPONENTS`` variable. If a particular
component is non-optional, then the ``<PackageName>_FIND_REQUIRED_<comp>`` will
be true. This can be tested with logic in the package configuration file:
.. code-block:: cmake
@ -580,8 +580,8 @@ non-standard install locations or directly in their own build trees.
A project may populate either the user or system registry (using its own
means, see below) to refer to its location.
In either case the package should store at the registered location a
`Package Configuration File`_ (``<package>Config.cmake``) and optionally a
`Package Version File`_ (``<package>ConfigVersion.cmake``).
`Package Configuration File`_ (``<PackageName>Config.cmake``) and optionally a
`Package Version File`_ (``<PackageName>ConfigVersion.cmake``).
The :command:`find_package` command searches the two package registries
as two of the search steps specified in its documentation. If it has
@ -603,18 +603,18 @@ must be manually taught to register their packages if desired.
On Windows the user package registry is stored in the Windows registry
under a key in ``HKEY_CURRENT_USER``.
A ``<package>`` may appear under registry key::
A ``<PackageName>`` may appear under registry key::
HKEY_CURRENT_USER\Software\Kitware\CMake\Packages\<package>
HKEY_CURRENT_USER\Software\Kitware\CMake\Packages\<PackageName>
as a ``REG_SZ`` value, with arbitrary name, that specifies the directory
containing the package configuration file.
On UNIX platforms the user package registry is stored in the user home
directory under ``~/.cmake/packages``. A ``<package>`` may appear under
directory under ``~/.cmake/packages``. A ``<PackageName>`` may appear under
the directory::
~/.cmake/packages/<package>
~/.cmake/packages/<PackageName>
as a file, with arbitrary name, whose content specifies the directory
containing the package configuration file.
@ -629,10 +629,10 @@ CMake currently provides no interface to add to the system package registry.
Installers must be manually taught to register their packages if desired.
On Windows the system package registry is stored in the Windows registry
under a key in ``HKEY_LOCAL_MACHINE``. A ``<package>`` may appear under
under a key in ``HKEY_LOCAL_MACHINE``. A ``<PackageName>`` may appear under
registry key::
HKEY_LOCAL_MACHINE\Software\Kitware\CMake\Packages\<package>
HKEY_LOCAL_MACHINE\Software\Kitware\CMake\Packages\<PackageName>
as a ``REG_SZ`` value, with arbitrary name, that specifies the directory
containing the package configuration file.

13
Help/manual/cmake-policies.7.rst
View File

@ -51,6 +51,19 @@ The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used
to determine whether to report an error on use of deprecated macros or
functions.
Policies Introduced by CMake 3.13
=================================
.. toctree::
:maxdepth: 1
CMP0081: Relative paths not allowed in LINK_DIRECTORIES target property. </policy/CMP0081>
CMP0080: BundleUtilities cannot be included at configure time. </policy/CMP0080>
CMP0079: target_link_libraries allows use with targets in other directories. </policy/CMP0079>
CMP0078: UseSWIG generates standard target names. </policy/CMP0078>
CMP0077: option() honors normal variables. </policy/CMP0077>
CMP0076: target_sources() command converts relative paths to absolute. </policy/CMP0076>
Policies Introduced by CMake 3.12
=================================

31
Help/manual/cmake-properties.7.rst
View File

@ -77,6 +77,7 @@ Properties on Directories
/prop_dir/INTERPROCEDURAL_OPTIMIZATION
/prop_dir/LABELS
/prop_dir/LINK_DIRECTORIES
/prop_dir/LINK_OPTIONS
/prop_dir/LISTFILE_STACK
/prop_dir/MACROS
/prop_dir/PARENT_DIRECTORY
@ -172,6 +173,7 @@ Properties on Targets
/prop_tgt/DEBUG_POSTFIX
/prop_tgt/DEFINE_SYMBOL
/prop_tgt/DEPLOYMENT_REMOTE_DIRECTORY
/prop_tgt/DEPLOYMENT_ADDITIONAL_FILES
/prop_tgt/DOTNET_TARGET_FRAMEWORK_VERSION
/prop_tgt/EchoString
/prop_tgt/ENABLE_EXPORTS
@ -197,6 +199,7 @@ Properties on Targets
/prop_tgt/IMPORTED_LIBNAME_CONFIG
/prop_tgt/IMPORTED_LIBNAME
/prop_tgt/IMPORTED_LINK_DEPENDENT_LIBRARIES_CONFIG
/prop_tgt/IMPORTED_LINK_DEPENDENT_LIBRARIES_CONFIG
/prop_tgt/IMPORTED_LINK_DEPENDENT_LIBRARIES
/prop_tgt/IMPORTED_LINK_INTERFACE_LANGUAGES_CONFIG
/prop_tgt/IMPORTED_LINK_INTERFACE_LANGUAGES
@ -224,7 +227,10 @@ Properties on Targets
/prop_tgt/INTERFACE_COMPILE_FEATURES
/prop_tgt/INTERFACE_COMPILE_OPTIONS
/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES
/prop_tgt/INTERFACE_LINK_DEPENDS
/prop_tgt/INTERFACE_LINK_DIRECTORIES
/prop_tgt/INTERFACE_LINK_LIBRARIES
/prop_tgt/INTERFACE_LINK_OPTIONS
/prop_tgt/INTERFACE_POSITION_INDEPENDENT_CODE
/prop_tgt/INTERFACE_SOURCES
/prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES
@ -247,6 +253,7 @@ Properties on Targets
/prop_tgt/LINK_DEPENDS_NO_SHARED
/prop_tgt/LINK_DEPENDS
/prop_tgt/LINKER_LANGUAGE
/prop_tgt/LINK_DIRECTORIES
/prop_tgt/LINK_FLAGS_CONFIG
/prop_tgt/LINK_FLAGS
/prop_tgt/LINK_INTERFACE_LIBRARIES_CONFIG
@ -254,6 +261,7 @@ Properties on Targets
/prop_tgt/LINK_INTERFACE_MULTIPLICITY_CONFIG
/prop_tgt/LINK_INTERFACE_MULTIPLICITY
/prop_tgt/LINK_LIBRARIES
/prop_tgt/LINK_OPTIONS
/prop_tgt/LINK_SEARCH_END_STATIC
/prop_tgt/LINK_SEARCH_START_STATIC
/prop_tgt/LINK_WHAT_YOU_USE
@ -295,13 +303,16 @@ Properties on Targets
/prop_tgt/SOVERSION
/prop_tgt/STATIC_LIBRARY_FLAGS_CONFIG
/prop_tgt/STATIC_LIBRARY_FLAGS
/prop_tgt/STATIC_LIBRARY_OPTIONS
/prop_tgt/SUFFIX
/prop_tgt/TYPE
/prop_tgt/VERSION
/prop_tgt/VISIBILITY_INLINES_HIDDEN
/prop_tgt/VS_CONFIGURATION_TYPE
/prop_tgt/VS_DEBUGGER_WORKING_DIRECTORY
/prop_tgt/VS_DEBUGGER_COMMAND
/prop_tgt/VS_DEBUGGER_COMMAND_ARGUMENTS
/prop_tgt/VS_DEBUGGER_ENVIRONMENT
/prop_tgt/VS_DEBUGGER_WORKING_DIRECTORY
/prop_tgt/VS_DESKTOP_EXTENSIONS_VERSION
/prop_tgt/VS_DOTNET_REFERENCE_refname
/prop_tgt/VS_DOTNET_REFERENCEPROP_refname_TAG_tagname
@ -331,6 +342,24 @@ Properties on Targets
/prop_tgt/XCODE_ATTRIBUTE_an-attribute
/prop_tgt/XCODE_EXPLICIT_FILE_TYPE
/prop_tgt/XCODE_PRODUCT_TYPE
/prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER
/prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN
/prop_tgt/XCODE_SCHEME_THREAD_SANITIZER
/prop_tgt/XCODE_SCHEME_THREAD_SANITIZER_STOP
/prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER
/prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP
/prop_tgt/XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER
/prop_tgt/XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP
/prop_tgt/XCODE_SCHEME_MALLOC_SCRIBBLE
/prop_tgt/XCODE_SCHEME_MALLOC_GUARD_EDGES
/prop_tgt/XCODE_SCHEME_GUARD_MALLOC
/prop_tgt/XCODE_SCHEME_ZOMBIE_OBJECTS
/prop_tgt/XCODE_SCHEME_MALLOC_STACK
/prop_tgt/XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE
/prop_tgt/XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS
/prop_tgt/XCODE_SCHEME_EXECUTABLE
/prop_tgt/XCODE_SCHEME_ARGUMENTS
/prop_tgt/XCODE_SCHEME_ENVIRONMENT
/prop_tgt/XCTEST
.. _`Test Properties`:

24
Help/manual/cmake-variables.7.rst
View File

@ -24,6 +24,7 @@ Variables that Provide Information
/variable/CMAKE_CACHE_PATCH_VERSION
/variable/CMAKE_CFG_INTDIR
/variable/CMAKE_COMMAND
/variable/CMAKE_CPACK_COMMAND
/variable/CMAKE_CROSSCOMPILING
/variable/CMAKE_CROSSCOMPILING_EMULATOR
/variable/CMAKE_CTEST_COMMAND
@ -77,6 +78,7 @@ Variables that Provide Information
/variable/CMAKE_PROJECT_VERSION_TWEAK
/variable/CMAKE_RANLIB
/variable/CMAKE_ROOT
/variable/CMAKE_RULE_MESSAGES
/variable/CMAKE_SCRIPT_MODE_FILE
/variable/CMAKE_SHARED_LIBRARY_PREFIX
/variable/CMAKE_SHARED_LIBRARY_SUFFIX
@ -177,6 +179,7 @@ Variables that Change Behavior
/variable/CMAKE_INSTALL_PREFIX
/variable/CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT
/variable/CMAKE_LIBRARY_PATH
/variable/CMAKE_LINK_DIRECTORIES_BEFORE
/variable/CMAKE_MFC_FLAG
/variable/CMAKE_MODULE_PATH
/variable/CMAKE_NOT_USING_CONFIG_FLAGS
@ -204,6 +207,21 @@ Variables that Change Behavior
/variable/CMAKE_WARN_DEPRECATED
/variable/CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION
/variable/CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY
/variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER
/variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN
/variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER
/variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP
/variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER
/variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP
/variable/CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER
/variable/CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP
/variable/CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE
/variable/CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES
/variable/CMAKE_XCODE_SCHEME_GUARD_MALLOC
/variable/CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS
/variable/CMAKE_XCODE_SCHEME_MALLOC_STACK
/variable/CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE
/variable/CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS
/variable/PackageName_ROOT
Variables that Describe the System
@ -215,6 +233,7 @@ Variables that Describe the System
/variable/ANDROID
/variable/APPLE
/variable/BORLAND
/variable/CACHE
/variable/CMAKE_CL_64
/variable/CMAKE_COMPILER_2005
/variable/CMAKE_HOST_APPLE
@ -291,6 +310,7 @@ Variables that Control the Build
/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY
/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG
/variable/CMAKE_AUTOGEN_PARALLEL
/variable/CMAKE_AUTOGEN_VERBOSE
/variable/CMAKE_AUTOMOC
/variable/CMAKE_AUTOMOC_COMPILER_PREDEFINES
/variable/CMAKE_AUTOMOC_DEPEND_FILTERS
@ -375,6 +395,7 @@ Variables that Control the Build
/variable/CMAKE_TRY_COMPILE_TARGET_TYPE
/variable/CMAKE_USE_RELATIVE_PATHS
/variable/CMAKE_VISIBILITY_INLINES_HIDDEN
/variable/CMAKE_VS_GLOBALS
/variable/CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD
/variable/CMAKE_VS_INCLUDE_PACKAGE_TO_DEFAULT_BUILD
/variable/CMAKE_VS_SDK_EXCLUDE_DIRECTORIES
@ -384,6 +405,7 @@ Variables that Control the Build
/variable/CMAKE_VS_SDK_LIBRARY_WINRT_DIRECTORIES
/variable/CMAKE_VS_SDK_REFERENCE_DIRECTORIES
/variable/CMAKE_VS_SDK_SOURCE_DIRECTORIES
/variable/CMAKE_VS_WINRT_BY_DEFAULT
/variable/CMAKE_WIN32_EXECUTABLE
/variable/CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS
/variable/CMAKE_XCODE_ATTRIBUTE_an-attribute
@ -461,6 +483,8 @@ Variables for Languages
/variable/CMAKE_LANG_LIBRARY_ARCHITECTURE
/variable/CMAKE_LANG_LINKER_PREFERENCE
/variable/CMAKE_LANG_LINKER_PREFERENCE_PROPAGATES
/variable/CMAKE_LANG_LINKER_WRAPPER_FLAG
/variable/CMAKE_LANG_LINKER_WRAPPER_FLAG_SEP
/variable/CMAKE_LANG_LINK_EXECUTABLE
/variable/CMAKE_LANG_OUTPUT_EXTENSION
/variable/CMAKE_LANG_PLATFORM_ID

6
Help/manual/cmake.1.rst
View File

@ -9,6 +9,7 @@ Synopsis
.. parsed-literal::
cmake [<options>] {<path-to-source> | <path-to-existing-build>}
cmake [<options>] -S <path-to-source> -B <path-to-build>
cmake [{-D <var>=<value>}...] -P <cmake-script-file>
cmake --build <dir> [<options>...] [-- <build-tool-options>...]
cmake --open <dir>
@ -353,11 +354,6 @@ Available commands are:
Touch a file if it exists but do not create it. If a file does
not exist it will be silently ignored.
UNIX-specific Command-Line Tools
--------------------------------
The following ``cmake -E`` commands are available only on UNIX:
``create_symlink <old> <new>``
Create a symbolic link ``<new>`` naming ``<old>``.

29
Help/manual/cpack-generators.7.rst Normal file
View File

@ -0,0 +1,29 @@
.. cmake-manual-description: CPack Generator Reference
cpack-generators(7)
*******************
.. only:: html
.. contents::
Generators
==========
.. toctree::
:maxdepth: 1
/cpack_gen/archive
/cpack_gen/bundle
/cpack_gen/cygwin
/cpack_gen/deb
/cpack_gen/dmg
/cpack_gen/external
/cpack_gen/freebsd
/cpack_gen/ifw
/cpack_gen/nsis
/cpack_gen/nuget
/cpack_gen/packagemaker
/cpack_gen/productbuild
/cpack_gen/rpm
/cpack_gen/wix

21
Help/manual/ctest.1.rst
View File

@ -35,6 +35,19 @@ Options
which one should be tested. Example configurations are "Debug" and
"Release".
``--progress``
Enable short progress output from tests.
When the output of ``ctest`` is being sent directly to a terminal, the
progress through the set of tests is reported by updating the same line
rather than printing start and end messages for each test on new lines.
This can significantly reduce the verbosity of the test output.
Test completion messages are still output on their own line for failed
tests and the final test summary will also still be logged.
This option can also be enabled by setting the environment variable
:envvar:`CTEST_PROGRESS_OUTPUT`.
``-V,--verbose``
Enable verbose output from tests.
@ -55,8 +68,8 @@ Options
``--output-on-failure``
Output anything outputted by the test program if the test should fail.
This option can also be enabled by setting the environment variable
``CTEST_OUTPUT_ON_FAILURE``.
This option can also be enabled by setting the
:envvar:`CTEST_OUTPUT_ON_FAILURE` environment variable
``-F``
Enable failover.
@ -70,7 +83,7 @@ Options
This option tells CTest to run the tests in parallel using given
number of jobs. This option can also be set by setting the
environment variable ``CTEST_PARALLEL_LEVEL``.
:envvar:`CTEST_PARALLEL_LEVEL` environment variable.
This option can be used with the :prop_test:`PROCESSORS` test property.
@ -867,7 +880,7 @@ Configuration settings include:
* `CTest Script`_ variable: :variable:`CTEST_CONFIGURATION_TYPE`
* :module:`CTest` module variable: ``DEFAULT_CTEST_CONFIGURATION_TYPE``,
initialized by the ``CMAKE_CONFIG_TYPE`` environment variable
initialized by the :envvar:`CMAKE_CONFIG_TYPE` environment variable
``LabelsForSubprojects``
Specify a semicolon-separated list of labels that will be treated as

5
Help/module/CPackArchive.rst
View File

@ -1 +1,4 @@
.. cmake-module:: ../../Modules/CPackArchive.cmake
CPackArchive
------------
The documentation for the CPack Archive generator has moved here: :cpack_gen:`CPack Archive Generator`

5
Help/module/CPackBundle.rst
View File

@ -1 +1,4 @@
.. cmake-module:: ../../Modules/CPackBundle.cmake
CPackBundle
-----------
The documentation for the CPack Bundle generator has moved here: :cpack_gen:`CPack Bundle Generator`

5
Help/module/CPackCygwin.rst
View File

@ -1 +1,4 @@
.. cmake-module:: ../../Modules/CPackCygwin.cmake
CPackCygwin
-----------
The documentation for the CPack Cygwin generator has moved here: :cpack_gen:`CPack Cygwin Generator`

5
Help/module/CPackDMG.rst
View File

@ -1 +1,4 @@
.. cmake-module:: ../../Modules/CPackDMG.cmake
CPackDMG
--------
The documentation for the CPack DMG generator has moved here: :cpack_gen:`CPack DMG Generator`

5
Help/module/CPackDeb.rst
View File

@ -1 +1,4 @@
.. cmake-module:: ../../Modules/CPackDeb.cmake
CPackDeb
--------
The documentation for the CPack Deb generator has moved here: :cpack_gen:`CPack Deb Generator`

5
Help/module/CPackFreeBSD.rst
View File

@ -1 +1,4 @@
.. cmake-module:: ../../Modules/CPackFreeBSD.cmake
CPackFreeBSD
------------
The documentation for the CPack FreeBSD generator has moved here: :cpack_gen:`CPack FreeBSD Generator`

5
Help/module/CPackNSIS.rst
View File

@ -1 +1,4 @@
.. cmake-module:: ../../Modules/CPackNSIS.cmake
CPackNSIS
---------
The documentation for the CPack NSIS generator has moved here: :cpack_gen:`CPack NSIS Generator`

5
Help/module/CPackNuGet.rst
View File

@ -1 +1,4 @@
.. cmake-module:: ../../Modules/CPackNuGet.cmake
CPackNuGet
----------
The documentation for the CPack NuGet generator has moved here: :cpack_gen:`CPack NuGet Generator`

5
Help/module/CPackPackageMaker.rst
View File

@ -1 +1,4 @@
.. cmake-module:: ../../Modules/CPackPackageMaker.cmake
CPackPackageMaker
-----------------
The documentation for the CPack PackageMaker generator has moved here: :cpack_gen:`CPack PackageMaker Generator`

5
Help/module/CPackProductBuild.rst
View File

@ -1 +1,4 @@
.. cmake-module:: ../../Modules/CPackProductBuild.cmake
CPackProductBuild
-----------------
The documentation for the CPack productbuild generator has moved here: :cpack_gen:`CPack productbuild Generator`

5
Help/module/CPackRPM.rst
View File

@ -1 +1,4 @@
.. cmake-module:: ../../Modules/CPackRPM.cmake
CPackRPM
--------
The documentation for the CPack RPM generator has moved here: :cpack_gen:`CPack RPM Generator`

5
Help/module/CPackWIX.rst
View File

@ -1 +1,4 @@
.. cmake-module:: ../../Modules/CPackWIX.cmake
CPackWIX
--------
The documentation for the CPack WiX generator has moved here: :cpack_gen:`CPack WiX Generator`

4
Help/policy/CMP0053.rst
View File

@ -16,6 +16,10 @@ cleaned up to simplify the behavior. Specifically:
* Literal ``${VAR}`` reference syntax may contain only
alphanumeric characters (``A-Z``, ``a-z``, ``0-9``) and
the characters ``_``, ``.``, ``/``, ``-``, and ``+``.
Note that ``$`` is technically allowed in the ``NEW`` behavior, but is
invalid for ``OLD`` behavior. This is due to an oversight during the
implementation of :policy:`CMP0053` and its use as a literal variable
reference is discouraged for this reason.
Variables with other characters in their name may still
be referenced indirectly, e.g.

26
Help/policy/CMP0076.rst Normal file
View File

@ -0,0 +1,26 @@
CMP0076
-------
The :command:`target_sources` command converts relative paths to absolute.
In CMake 3.13 and above, the :command:`target_sources` command now converts
relative source file paths to absolute paths in the following cases:
* Source files are added to the target's :prop_tgt:`INTERFACE_SOURCES`
property.
* The target's :prop_tgt:`SOURCE_DIR` property differs from
:variable:`CMAKE_CURRENT_SOURCE_DIR`.
A path that begins with a generator expression is always left unmodified.
This policy provides compatibility with projects that have not been updated
to expect this behavior. The ``OLD`` behavior for this policy is to leave
all relative source file paths unmodified. The ``NEW`` behavior of this
policy is to convert relative paths to absolute according to above rules.
This policy was introduced in CMake version 3.13. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior.
Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW``
explicitly.
.. include:: DEPRECATED.txt

52
Help/policy/CMP0077.rst Normal file
View File

@ -0,0 +1,52 @@
CMP0077
-------
:command:`option` honors normal variables.
The :command:`option` command is typically used to create a cache entry
to allow users to set the option. However, there are cases in which a
normal (non-cached) variable of the same name as the option may be
defined by the project prior to calling the :command:`option` command.
For example, a project that embeds another project as a subdirectory
may want to hard-code options of the subproject to build the way it needs.
For historical reasons in CMake 3.12 and below the :command:`option`
command *removes* a normal (non-cached) variable of the same name when:
* a cache entry of the specified name does not exist at all, or
* a cache entry of the specified name exists but has not been given
a type (e.g. via ``-D<name>=ON`` on the command line).
In both of these cases (typically on the first run in a new build tree),
the :command:`option` command gives the cache entry type ``BOOL`` and
removes any normal (non-cached) variable of the same name. In the
remaining case that the cache entry of the specified name already
exists and has a type (typically on later runs in a build tree), the
:command:`option` command changes nothing and any normal variable of
the same name remains set.
In CMake 3.13 and above the :command:`option` command prefers to
do nothing when a normal variable of the given name already exists.
It does not create or update a cache entry or remove the normal variable.
The new behavior is consistent between the first and later runs in a
build tree. This policy provides compatibility with projects that have
not been updated to expect the new behavior.
When the :command:`option` command sees a normal variable of the given
name:
* The ``OLD`` behavior for this policy is to proceed even when a normal
variable of the same name exists. If the cache entry does not already
exist and have a type then it is created and/or given a type and the
normal variable is removed.
* The ``NEW`` behavior for this policy is to do nothing when a normal
variable of the same name exists. The normal variable is not removed.
The cache entry is not created or updated and is ignored if it exists.
This policy was introduced in CMake version 3.13. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior.
Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW``
explicitly.
.. include:: DEPRECATED.txt

22
Help/policy/CMP0078.rst Normal file
View File

@ -0,0 +1,22 @@
CMP0078
-------
Starting with CMake 3.13, :module:`UseSWIG` generates now standard target
names. This policy provides compatibility with projects that expect the legacy
behavior.
The ``OLD`` behavior for this policy relies on
``UseSWIG_TARGET_NAME_PREFERENCE`` variable that can be used to specify an
explicit preference. The value may be one of:
* ``LEGACY``: legacy strategy is applied. Variable
``SWIG_MODULE_<name>_REAL_NAME`` must be used to get real target name.
This is the default if not specified.
* ``STANDARD``: target name matches specified name.
This policy was introduced in CMake version 3.13. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior.
Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW``
explicitly.
.. include:: DEPRECATED.txt

40
Help/policy/CMP0079.rst Normal file
View File

@ -0,0 +1,40 @@
CMP0079
-------
:command:`target_link_libraries` allows use with targets in other directories.
Prior to CMake 3.13 the :command:`target_link_libraries` command did not
accept targets not created in the calling directory as its first argument
for calls that update the :prop_tgt:`LINK_LIBRARIES` of the target itself.
It did accidentally accept targets from other directories on calls that
only update the :prop_tgt:`INTERFACE_LINK_LIBRARIES`, but would simply
add entries to the property as if the call were made in the original
directory. Thus link interface libraries specified this way were always
looked up by generators in the scope of the original target rather than
in the scope that called :command:`target_link_libraries`.
CMake 3.13 now allows the :command:`target_link_libraries` command to
be called from any directory to add link dependencies and link interface
libraries to targets created in other directories. The entries are added
to :prop_tgt:`LINK_LIBRARIES` and :prop_tgt:`INTERFACE_LINK_LIBRARIES`
using a special (internal) suffix to tell the generators to look up the
names in the calling scope rather than the scope that created the target.
This policy provides compatibility with projects that already use
:command:`target_link_libraries` with the ``INTERFACE`` keyword
on a target in another directory to add :prop_tgt:`INTERFACE_LINK_LIBRARIES`
entries to be looked up in the target's directory. Such projects should
be updated to be aware of the new scoping rules in that case.
The ``OLD`` behavior of this policy is to disallow
:command:`target_link_libraries` calls naming targets from another directory
except in the previously accidentally allowed case of using the ``INTERFACE``
keyword only. The ``NEW`` behavior of this policy is to allow all such
calls but use the new scoping rules.
This policy was introduced in CMake version 3.13. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior.
Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW``
explicitly.
.. include:: DEPRECATED.txt

25
Help/policy/CMP0080.rst Normal file
View File

@ -0,0 +1,25 @@
CMP0080
-------
:module:`BundleUtilities` cannot be included at configure time.
The macros provided by :module:`BundleUtilities` are intended to be invoked
at install time rather than at configure time, because they depend on the
listed targets already existing at the time they are invoked. If they are
invoked at configure time, the targets haven't been built yet, and the
commands will fail.
This policy restricts the inclusion of :module:`BundleUtilities` to
``cmake -P`` style scripts and install rules. Specifically, it looks for the
presence of :variable:`CMAKE_GENERATOR` and throws a fatal error if it exists.
The ``OLD`` behavior of this policy is to allow :module:`BundleUtilities` to
be included at configure time. The ``NEW`` behavior of this policy is to
disallow such inclusion.
This policy was introduced in CMake version 3.13. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior.
Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW``
explicitly.
.. include:: DEPRECATED.txt

22
Help/policy/CMP0081.rst Normal file
View File

@ -0,0 +1,22 @@
CMP0081
-------
Relative paths not allowed in :prop_tgt:`LINK_DIRECTORIES` target property.
CMake 3.12 and lower allowed the :prop_dir:`LINK_DIRECTORIES` directory
property to contain relative paths. The base path for such relative
entries is not well defined. CMake 3.13 and later will issue a
``FATAL_ERROR`` if the :prop_tgt:`LINK_DIRECTORIES` target property
(which is initialized by the :prop_dir:`LINK_DIRECTORIES` directory property)
contains a relative path.
The ``OLD`` behavior for this policy is not to warn about relative paths
in the :prop_tgt:`LINK_DIRECTORIES` target property. The ``NEW`` behavior for
this policy is to issue a ``FATAL_ERROR`` if :prop_tgt:`LINK_DIRECTORIES`
contains a relative path.
This policy was introduced in CMake version 3.13. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. include:: DEPRECATED.txt

12
Help/prop_dir/INCLUDE_DIRECTORIES.rst
View File

@ -11,11 +11,17 @@ target property, which is used by the generators to set the include
directories for the compiler.
In addition to accepting values from that command, values may be set
directly on any directory using the :command:`set_property` command. A
directory gets its initial value from its parent directory if it has one.
The initial value of the :prop_tgt:`INCLUDE_DIRECTORIES` target property
directly on any directory using the :command:`set_property` command, and can be
set on the current directory using the :command:`set_directory_properties`
command. A directory gets its initial value from its parent directory if it has
one. The initial value of the :prop_tgt:`INCLUDE_DIRECTORIES` target property
comes from the value of this property. Both directory and target property
values are adjusted by calls to the :command:`include_directories` command.
Calls to :command:`set_property` or :command:`set_directory_properties`,
however, will update the directory property value without updating target
property values. Therefore direct property updates must be made before
calls to :command:`add_executable` or :command:`add_library` for targets
they are meant to affect.
The target property values are used by the generators to set the
include paths for the compiler.

15
Help/prop_dir/LINK_DIRECTORIES.rst
View File

@ -3,6 +3,15 @@ LINK_DIRECTORIES
List of linker search directories.
This read-only property specifies the list of directories given so far
to the link_directories command. It is intended for debugging
purposes.
This property holds a :ref:`;-list <CMake Language Lists>` of directories
and is typically populated using the :command:`link_directories` command.
It gets its initial value from its parent directory, if it has one.
The directory property is used to initialize the :prop_tgt:`LINK_DIRECTORIES`
target property when a target is created. That target property is used
by the generators to set the library search directories for the linker.
Contents of ``LINK_DIRECTORIES`` may use "generator expressions" with
the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
manual for available expressions. See the :manual:`cmake-buildsystem(7)`
manual for more on defining buildsystem properties.

Some files were not shown because too many files have changed in this diff Show More