diff options
| author | biao716.wang <biao716.wang@samsung.com> | 2020-03-19 01:04:30 +0900 |
|---|---|---|
| committer | biao716.wang <biao716.wang@samsung.com> | 2020-03-19 01:04:30 +0900 |
| commit | 1d6613f4446f69f63beddf2d97c201154fb35e33 (patch) | |
| tree | f32eae75900a0df14ab8fa1e2bd436af159ef91d /Help | |
| parent | aabcd8e66e3268a232efe2e416635d5b6bf84ad5 (diff) | |
| download | cmake-upstream/3.16.4.tar.gz cmake-upstream/3.16.4.tar.bz2 cmake-upstream/3.16.4.zip | |
Imported Upstream version 3.16.4upstream/3.16.4
Change-Id: Ic5262ea6c0872b353ea2dc35fe1e944063ae8409
Signed-off-by: biao716.wang <biao716.wang@samsung.com>
Diffstat (limited to 'Help')
993 files changed, 24560 insertions, 4122 deletions
diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index 7db221cb8..42bf52b08 100644 --- a/Help/command/FIND_XXX.txt +++ b/Help/command/FIND_XXX.txt @@ -16,6 +16,7 @@ The general signature is: [PATH_SUFFIXES suffix1 [suffix2 ...]] [DOC "cache documentation string"] [NO_DEFAULT_PATH] + [NO_PACKAGE_ROOT_PATH] [NO_CMAKE_PATH] [NO_CMAKE_ENVIRONMENT_PATH] [NO_SYSTEM_ENVIRONMENT_PATH] @@ -60,6 +61,13 @@ If ``NO_DEFAULT_PATH`` is specified, then no additional paths are added to the search. If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: +.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR| replace:: + |prefix_XXX_SUBDIR| for each ``<prefix>`` in the + :variable:`<PackageName>_ROOT` CMake variable and the + :envvar:`<PackageName>_ROOT` environment variable if + called from within a find module loaded by + :command:`find_package(<PackageName>)` + .. |CMAKE_PREFIX_PATH_XXX_SUBDIR| replace:: |prefix_XXX_SUBDIR| for each ``<prefix>`` in :variable:`CMAKE_PREFIX_PATH` @@ -71,50 +79,72 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: |prefix_XXX_SUBDIR| for each ``<prefix>`` in :variable:`CMAKE_SYSTEM_PREFIX_PATH` -1. Search paths specified in cmake-specific cache variables. +1. If called from within a find module or any other script loaded by a call to + :command:`find_package(<PackageName>)`, search prefixes unique to the + current package being found. Specifically, look in the + :variable:`<PackageName>_ROOT` CMake variable and the + :envvar:`<PackageName>_ROOT` environment variable. + The package root variables are maintained as a stack, so if called from + nested find modules or config packages, root paths from the parent's find + module or config package will be searched after paths from the current + module or package. In other words, the search order would be + ``<CurrentPackage>_ROOT``, ``ENV{<CurrentPackage>_ROOT}``, + ``<ParentPackage>_ROOT``, ``ENV{<ParentPackage>_ROOT}``, etc. + This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed or by setting + the :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` to ``FALSE``. + See policy :policy:`CMP0074`. + + * |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| + +2. Search paths specified in cmake-specific cache variables. These are intended to be used on the command line with a ``-DVAR=value``. - The values are interpreted as :ref:`;-lists <CMake Language Lists>`. - This can be skipped if ``NO_CMAKE_PATH`` is passed. + The values are interpreted as :ref:`semicolon-separated lists <CMake Language Lists>`. + This can be skipped if ``NO_CMAKE_PATH`` is passed or by setting the + :variable:`CMAKE_FIND_USE_CMAKE_PATH` to ``FALSE``. * |CMAKE_PREFIX_PATH_XXX| * |CMAKE_XXX_PATH| * |CMAKE_XXX_MAC_PATH| -2. Search paths specified in cmake-specific environment variables. +3. Search paths specified in cmake-specific environment variables. These are intended to be set in the user's shell configuration, and therefore use the host's native path separator (``;`` on Windows and ``:`` on UNIX). - This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed. + This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed or + by setting the :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` to ``FALSE``. * |CMAKE_PREFIX_PATH_XXX| * |CMAKE_XXX_PATH| * |CMAKE_XXX_MAC_PATH| -3. Search the paths specified by the ``HINTS`` option. +4. Search the paths specified by the ``HINTS`` option. These should be paths computed by system introspection, such as a hint provided by the location of another item already found. Hard-coded guesses should be specified with the ``PATHS`` option. -4. Search the standard system environment variables. - This can be skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is an argument. +5. Search the standard system environment variables. + This can be skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is passed or by + setting the :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH` to ``FALSE``. * |SYSTEM_ENVIRONMENT_PATH_XXX| + * |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| -5. Search cmake variables defined in the Platform files +6. Search cmake variables defined in the Platform files for the current system. This can be skipped if ``NO_CMAKE_SYSTEM_PATH`` - is passed. + is passed or by setting the :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH` + to ``FALSE``. * |CMAKE_SYSTEM_PREFIX_PATH_XXX| * |CMAKE_SYSTEM_XXX_PATH| * |CMAKE_SYSTEM_XXX_MAC_PATH| -6. Search the paths specified by the PATHS option +7. Search the paths specified by the PATHS option or in the short-hand version of the command. These are typically hard-coded guesses. .. |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. diff --git a/Help/command/LINK_OPTIONS_LINKER.txt b/Help/command/LINK_OPTIONS_LINKER.txt new file mode 100644 index 000000000..3f66181be --- /dev/null +++ b/Help/command/LINK_OPTIONS_LINKER.txt @@ -0,0 +1,22 @@ +To pass options to the linker tool, each compiler driver has its own syntax. +The ``LINKER:`` prefix and ``,`` separator can be used to specify, in a portable +way, options to pass to the linker tool. ``LINKER:`` is replaced by the +appropriate driver option and ``,`` by the appropriate driver separator. +The driver prefix and driver separator are given by the values of 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``. + +The ``LINKER:`` prefix can be specified as part of a ``SHELL:`` prefix +expression. + +The ``LINKER:`` prefix supports, as an alternative syntax, specification of +arguments using the ``SHELL:`` prefix and space as separator. The previous +example then becomes ``"LINKER:SHELL:-z defs"``. + +.. note:: + + Specifying the ``SHELL:`` prefix anywhere other than at the beginning of the + ``LINKER:`` prefix is not supported. diff --git a/Help/command/OPTIONS_SHELL.txt b/Help/command/OPTIONS_SHELL.txt new file mode 100644 index 000000000..0f8ec323c --- /dev/null +++ b/Help/command/OPTIONS_SHELL.txt @@ -0,0 +1,9 @@ +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 +its dependencies. The set of options is de-duplicated to avoid repetition. +While beneficial for individual options, the de-duplication step can break +up option groups. For example, ``-D A -D B`` becomes ``-D A B``. One may +specify a group of options using shell-like quoting along with a ``SHELL:`` +prefix. The ``SHELL:`` prefix is dropped, and the rest of the option string +is parsed using the :command:`separate_arguments` ``UNIX_COMMAND`` mode. +For example, ``"SHELL:-D A" "SHELL:-D B"`` becomes ``-D A -D B``. diff --git a/Help/command/add_compile_definitions.rst b/Help/command/add_compile_definitions.rst new file mode 100644 index 000000000..8225da783 --- /dev/null +++ b/Help/command/add_compile_definitions.rst @@ -0,0 +1,23 @@ +add_compile_definitions +----------------------- + +Add preprocessor definitions to the compilation of source files. + +.. code-block:: cmake + + add_compile_definitions(<definition> ...) + +Adds preprocessor definitions to the compiler command line for targets in the +current directory and below (whether added before or after this command is +invoked). See documentation of the :prop_dir:`directory <COMPILE_DEFINITIONS>` +and :prop_tgt:`target <COMPILE_DEFINITIONS>` ``COMPILE_DEFINITIONS`` properties. + +Definitions are specified using the syntax ``VAR`` or ``VAR=value``. +Function-style definitions are not supported. CMake will automatically +escape the value correctly for the native build system (note that CMake +language syntax may require escapes to specify some values). + +Arguments to ``add_compile_definitions`` 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. diff --git a/Help/command/add_compile_options.rst b/Help/command/add_compile_options.rst index 3fe2a3330..43805c3a9 100644 --- a/Help/command/add_compile_options.rst +++ b/Help/command/add_compile_options.rst @@ -1,23 +1,48 @@ add_compile_options ------------------- -Adds options to the compilation of source files. +Add options to the compilation of source files. -:: +.. code-block:: cmake add_compile_options(<option> ...) -Adds options to the compiler command line for targets in the current -directory and below that are added after this command is invoked. -See documentation of the :prop_dir:`directory <COMPILE_OPTIONS>` and -:prop_tgt:`target <COMPILE_OPTIONS>` ``COMPILE_OPTIONS`` properties. +Adds options to the :prop_dir:`COMPILE_OPTIONS` directory property. +These options are used when compiling targets from the current +directory and below. -This command can be used to add any options, but alternative commands -exist to add preprocessor definitions (:command:`target_compile_definitions` -and :command:`add_definitions`) or include directories -(:command:`target_include_directories` and :command:`include_directories`). +Arguments +^^^^^^^^^ Arguments to ``add_compile_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:: OPTIONS_SHELL.txt + +Example +^^^^^^^ + +Since different compilers support different options, a typical use of +this command is in a compiler-specific conditional clause: + +.. code-block:: cmake + + if (MSVC) + # warning level 4 and all warnings as errors + add_compile_options(/W4 /WX) + else() + # lots of warnings and all warnings as errors + add_compile_options(-Wall -Wextra -pedantic -Werror) + endif() + +See Also +^^^^^^^^ + +This command can be used to add any options. However, for +adding preprocessor definitions and include directories it is recommended +to use the more specific commands :command:`add_compile_definitions` +and :command:`include_directories`. + +The command :command:`target_compile_options` adds target-specific options. diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index d03840633..aba374261 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -8,7 +8,9 @@ There are two main signatures for ``add_custom_command``. Generating Files ^^^^^^^^^^^^^^^^ -The first signature is for adding a custom command to produce an output:: +The first signature is for adding a custom command to produce an output: + +.. code-block:: cmake add_custom_command(OUTPUT output1 [output2 ...] COMMAND command1 [ARGS] [args1...] @@ -21,6 +23,7 @@ The first signature is for adding a custom command to produce an output:: [WORKING_DIRECTORY dir] [COMMENT comment] [DEPFILE depfile] + [JOB_POOL job_pool] [VERBATIM] [APPEND] [USES_TERMINAL] [COMMAND_EXPAND_LISTS]) @@ -65,9 +68,6 @@ The options are: order-only dependencies to ensure the byproducts will be available before their dependents build. - The ``BYPRODUCTS`` option is ignored on non-Ninja generators - except to mark byproducts ``GENERATED``. - ``COMMAND`` Specify the command-line(s) to execute at build time. If more than one ``COMMAND`` is specified they will be executed in order, @@ -79,25 +79,33 @@ The options are: will be ignored. If ``COMMAND`` specifies an executable target name (created by the - :command:`add_executable` command) it will automatically be replaced - by the location of the executable created at build time. If set, the - :prop_tgt:`CROSSCOMPILING_EMULATOR` executable target property will - also be prepended to the command to allow the executable to run on - the host. - (Use the ``TARGET_FILE`` - :manual:`generator expression <cmake-generator-expressions(7)>` to - reference an executable later in the command line.) - Additionally a target-level dependency will be added so that the - executable target will be built before any target using this custom - command. However this does NOT add a file-level dependency that - would cause the custom command to re-run whenever the executable is - recompiled. + :command:`add_executable` command), it will automatically be replaced + by the location of the executable created at build time if either of + the following is true: + + * The target is not being cross-compiled (i.e. the + :variable:`CMAKE_CROSSCOMPILING` variable is not set to true). + * The target is being cross-compiled and an emulator is provided (i.e. + its :prop_tgt:`CROSSCOMPILING_EMULATOR` target property is set). + In this case, the contents of :prop_tgt:`CROSSCOMPILING_EMULATOR` will be + prepended to the command before the location of the target executable. + + If neither of the above conditions are met, it is assumed that the + command name is a program to be found on the ``PATH`` at build time. Arguments to ``COMMAND`` may use :manual:`generator expressions <cmake-generator-expressions(7)>`. - References to target names in generator expressions imply target-level - dependencies, but NOT file-level dependencies. List target names with - the ``DEPENDS`` option to add file-level dependencies. + Use the ``TARGET_FILE`` generator expression to refer to the location of + a target later in the command line (i.e. as a command argument rather + than as the command to execute). + + Whenever a target is used as a command to execute or is mentioned in a + generator expression as a command argument, a target-level dependency + will be added automatically so that the mentioned target will be built + before any target using this custom command. However this does NOT add + a file-level dependency that would cause the custom command to re-run + whenever the executable is recompiled. List target names with + the ``DEPENDS`` option to add such file-level dependencies. ``COMMENT`` Display the given message before the commands are executed at @@ -108,6 +116,9 @@ The options are: an ``OUTPUT`` of another custom command in the same directory (``CMakeLists.txt`` file) CMake automatically brings the other custom command into the target in which this command is built. + A target-level dependency is added if any dependency is listed as + ``BYPRODUCTS`` of a target or any of its build events in the same + directory to ensure the byproducts will be available. If ``DEPENDS`` is not specified the command will run whenever the ``OUTPUT`` is missing; if the command does not actually create the ``OUTPUT`` then the rule will always run. @@ -142,12 +153,21 @@ The options are: Note that the ``IMPLICIT_DEPENDS`` option is currently supported only for Makefile generators and will be ignored by other generators. +``JOB_POOL`` + Specify a :prop_gbl:`pool <JOB_POOLS>` for the :generator:`Ninja` + generator. Incompatible with ``USES_TERMINAL``, which implies + the ``console`` pool. + Using a pool that is not defined by :prop_gbl:`JOB_POOLS` causes + an error by ninja at build time. + ``MAIN_DEPENDENCY`` Specify the primary input source file to the command. This is treated just like any value given to the ``DEPENDS`` option but also suggests to Visual Studio generators where to hang - the custom command. At most one custom command may specify a - given source file as its main dependency. + the custom command. Each source file may have at most one command + specifying it as its main dependency. A compile command (i.e. for a + library or an executable) counts as an implicit main dependency which + gets silently overwritten by a custom command specification. ``OUTPUT`` Specify the output files the command is expected to produce. @@ -180,6 +200,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 @@ -195,7 +218,7 @@ before or after building the target. The command becomes part of the target and will only execute when the target itself is built. If the target is already built, the command will not execute. -:: +.. code-block:: cmake add_custom_command(TARGET <target> PRE_BUILD | PRE_LINK | POST_BUILD @@ -204,7 +227,8 @@ target is already built, the command will not execute. [BYPRODUCTS [files...]] [WORKING_DIRECTORY dir] [COMMENT comment] - [VERBATIM] [USES_TERMINAL]) + [VERBATIM] [USES_TERMINAL] + [COMMAND_EXPAND_LISTS]) This defines a new command that will be associated with building the specified ``<target>``. The ``<target>`` must be defined in the current @@ -214,10 +238,9 @@ When the command will happen is determined by which of the following is specified: ``PRE_BUILD`` - Run before any other rules are executed within the target. - This is supported only on Visual Studio 8 or later. - For all other generators ``PRE_BUILD`` will be treated as - ``PRE_LINK``. + On :ref:`Visual Studio Generators`, run before any other rules are + executed within the target. + On other generators, run just before ``PRE_LINK`` commands. ``PRE_LINK`` Run after sources have been compiled but before linking the binary or running the librarian or archiver tool of a static library. @@ -225,3 +248,13 @@ of the following is specified: :command:`add_custom_target` command. ``POST_BUILD`` Run after all other rules within the target have been executed. + +.. note:: + Because generator expressions can be used in custom commands, + it is possible to define ``COMMAND`` lines or whole custom commands + which evaluate to empty strings for certain configurations. + For **Visual Studio 2010 (and newer)** generators these command + lines or custom commands will be omitted for the specific + configuration and no "empty-string-command" will be added. + + This allows to add individual build events for every configuration. diff --git a/Help/command/add_custom_target.rst b/Help/command/add_custom_target.rst index bd61c8b96..2d5f5f081 100644 --- a/Help/command/add_custom_target.rst +++ b/Help/command/add_custom_target.rst @@ -3,7 +3,7 @@ add_custom_target Add a target with no output so it will always be built. -:: +.. code-block:: cmake add_custom_target(Name [ALL] [command1 [args1...]] [COMMAND command2 [args2...] ...] @@ -11,6 +11,7 @@ Add a target with no output so it will always be built. [BYPRODUCTS [files...]] [WORKING_DIRECTORY dir] [COMMENT comment] + [JOB_POOL job_pool] [VERBATIM] [USES_TERMINAL] [COMMAND_EXPAND_LISTS] [SOURCES src1 [src2...]]) @@ -48,9 +49,6 @@ The options are: order-only dependencies to ensure the byproducts will be available before their dependents build. - The ``BYPRODUCTS`` option is ignored on non-Ninja generators - except to mark byproducts ``GENERATED``. - ``COMMAND`` Specify the command-line(s) to execute at build time. If more than one ``COMMAND`` is specified they will be executed in order, @@ -60,18 +58,30 @@ The options are: a ``COMMAND`` to launch it.) If ``COMMAND`` specifies an executable target name (created by the - :command:`add_executable` command) it will automatically be replaced - by the location of the executable created at build time. If set, the - :prop_tgt:`CROSSCOMPILING_EMULATOR` executable target property will - also be prepended to the command to allow the executable to run on - the host. - Additionally a target-level dependency will be added so that the - executable target will be built before this custom target. + :command:`add_executable` command), it will automatically be replaced + by the location of the executable created at build time if either of + the following is true: + + * The target is not being cross-compiled (i.e. the + :variable:`CMAKE_CROSSCOMPILING` variable is not set to true). + * The target is being cross-compiled and an emulator is provided (i.e. + its :prop_tgt:`CROSSCOMPILING_EMULATOR` target property is set). + In this case, the contents of :prop_tgt:`CROSSCOMPILING_EMULATOR` will be + prepended to the command before the location of the target executable. + + If neither of the above conditions are met, it is assumed that the + command name is a program to be found on the ``PATH`` at build time. Arguments to ``COMMAND`` may use :manual:`generator expressions <cmake-generator-expressions(7)>`. - References to target names in generator expressions imply target-level - dependencies. + Use the ``TARGET_FILE`` generator expression to refer to the location of + a target later in the command line (i.e. as a command argument rather + than as the command to execute). + + Whenever a target is used as a command to execute or is mentioned in a + generator expression as a command argument, a target-level dependency + will be added automatically so that the mentioned target will be built + before this custom target. The command and arguments are optional and if not specified an empty target will be created. @@ -85,6 +95,9 @@ The options are: :command:`add_custom_command` command calls in the same directory (``CMakeLists.txt`` file). They will be brought up to date when the target is built. + A target-level dependency is added if any dependency is a byproduct + of a target or any of its build events in the same directory to ensure + the byproducts will be available before this target is built. Use the :command:`add_dependencies` command to add dependencies on other targets. @@ -97,6 +110,13 @@ The options are: ``${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTORIES>,;-I>" foo.cc`` to be properly expanded. +``JOB_POOL`` + Specify a :prop_gbl:`pool <JOB_POOLS>` for the :generator:`Ninja` + generator. Incompatible with ``USES_TERMINAL``, which implies + the ``console`` pool. + Using a pool that is not defined by :prop_gbl:`JOB_POOLS` causes + an error by ninja at build time. + ``SOURCES`` Specify additional source files to be included in the custom target. Specified source files will be added to IDE project files for @@ -121,3 +141,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)>`. diff --git a/Help/command/add_definitions.rst b/Help/command/add_definitions.rst index a04faf591..d06b01c9a 100644 --- a/Help/command/add_definitions.rst +++ b/Help/command/add_definitions.rst @@ -1,18 +1,26 @@ add_definitions --------------- -Adds -D define flags to the compilation of source files. +Add -D define flags to the compilation of source files. -:: +.. code-block:: cmake add_definitions(-DFOO -DBAR ...) Adds definitions to the compiler command line for targets in the current directory and below (whether added before or after this command is invoked). This command can be used to add any flags, but it is intended to add -preprocessor definitions (see the :command:`add_compile_options` command -to add other flags). -Flags beginning in -D or /D that look like preprocessor definitions are +preprocessor definitions. + +.. note:: + + This command has been superseded by alternatives: + + * Use :command:`add_compile_definitions` to add preprocessor definitions. + * Use :command:`include_directories` to add include directories. + * Use :command:`add_compile_options` to add other options. + +Flags beginning in ``-D`` or ``/D`` that look like preprocessor definitions are automatically added to the :prop_dir:`COMPILE_DEFINITIONS` directory property for the current directory. Definitions with non-trivial values may be left in the set of flags instead of being converted for reasons of diff --git a/Help/command/add_dependencies.rst b/Help/command/add_dependencies.rst index 7a6614328..de219a508 100644 --- a/Help/command/add_dependencies.rst +++ b/Help/command/add_dependencies.rst @@ -3,11 +3,11 @@ add_dependencies Add a dependency between top-level targets. -:: +.. code-block:: cmake add_dependencies(<target> [<target-dependency>]...) -Make a top-level ``<target>`` depend on other top-level targets to +Makes a top-level ``<target>`` depend on other top-level targets to ensure that they build before ``<target>`` does. A top-level target is one created by one of the :command:`add_executable`, :command:`add_library`, or :command:`add_custom_target` commands diff --git a/Help/command/add_executable.rst b/Help/command/add_executable.rst index c088796e4..0a7d7e151 100644 --- a/Help/command/add_executable.rst +++ b/Help/command/add_executable.rst @@ -3,18 +3,19 @@ add_executable Add an executable to the project using the specified source files. -:: +.. code-block:: cmake add_executable(<name> [WIN32] [MACOSX_BUNDLE] [EXCLUDE_FROM_ALL] - source1 [source2 ...]) + [source1] [source2 ...]) Adds an executable target called ``<name>`` to be built from the source -files listed in the command invocation. The ``<name>`` corresponds to the -logical target name and must be globally unique within a project. The -actual file name of the executable built is constructed based on -conventions of the native platform (such as ``<name>.exe`` or just -``<name>``). +files listed in the command invocation. (The source files can be omitted +here if they are added later using :command:`target_sources`.) The +``<name>`` corresponds to the logical target name and must be globally +unique within a project. The actual file name of the executable built is +constructed based on conventions of the native platform (such as +``<name>.exe`` or just ``<name>``). By default the executable file will be created in the build tree directory corresponding to the source tree directory in which the @@ -46,7 +47,7 @@ within IDE. -------------------------------------------------------------------------- -:: +.. code-block:: cmake add_executable(<name> IMPORTED [GLOBAL]) @@ -66,15 +67,16 @@ properties for more information. -------------------------------------------------------------------------- -:: +.. code-block:: cmake add_executable(<name> ALIAS <target>) Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can be used to refer to ``<target>`` in subsequent commands. The ``<name>`` does not appear in the generated buildsystem as a make target. The -``<target>`` may not be an :ref:`Imported Target <Imported Targets>` or an -``ALIAS``. ``ALIAS`` targets can be used as targets to read properties +``<target>`` may not be a non-``GLOBAL`` +:ref:`Imported Target <Imported Targets>` or an ``ALIAS``. +``ALIAS`` targets can be used as targets to read properties from, executables for custom commands and custom targets. They can also be tested for existence with the regular :command:`if(TARGET)` subcommand. The ``<name>`` may not be used to modify properties of ``<target>``, that diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst index de5335eff..7274e4474 100644 --- a/Help/command/add_library.rst +++ b/Help/command/add_library.rst @@ -10,17 +10,18 @@ Add a library to the project using the specified source files. Normal Libraries ^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake add_library(<name> [STATIC | SHARED | MODULE] [EXCLUDE_FROM_ALL] - source1 [source2 ...]) + [source1] [source2 ...]) Adds a library target called ``<name>`` to be built from the source files -listed in the command invocation. The ``<name>`` corresponds to the -logical target name and must be globally unique within a project. The -actual file name of the library built is constructed based on -conventions of the native platform (such as ``lib<name>.a`` or +listed in the command invocation. (The source files can be omitted here +if they are added later using :command:`target_sources`.) The ``<name>`` +corresponds to the logical target name and must be globally unique within +a project. The actual file name of the library built is constructed based +on conventions of the native platform (such as ``lib<name>.a`` or ``<name>.lib``). ``STATIC``, ``SHARED``, or ``MODULE`` may be given to specify the type of @@ -34,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 @@ -66,7 +67,7 @@ within IDE. Imported Libraries ^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake add_library(<name> <SHARED|STATIC|MODULE|OBJECT|UNKNOWN> IMPORTED [GLOBAL]) @@ -79,16 +80,30 @@ option extends visibility. It may be referenced like any target built within the project. ``IMPORTED`` libraries are useful for convenient reference from commands like :command:`target_link_libraries`. Details about the imported library are specified by setting properties whose names -begin in ``IMPORTED_`` and ``INTERFACE_``. The most important such -property is :prop_tgt:`IMPORTED_LOCATION` (and its per-configuration -variant :prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) which specifies the -location of the main library file on disk. See documentation of the -``IMPORTED_*`` and ``INTERFACE_*`` properties for more information. +begin in ``IMPORTED_`` and ``INTERFACE_``. + +The most important properties are: + +* :prop_tgt:`IMPORTED_LOCATION` (and its per-configuration + variant :prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) which specifies the + location of the main library file on disk. +* :prop_tgt:`IMPORTED_OBJECTS` (and :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>`) + for object libraries, specifies the locations of object files on disk. +* :prop_tgt:`PUBLIC_HEADER` files to be installed during :command:`install` invocation + +See documentation of the ``IMPORTED_*`` and ``INTERFACE_*`` properties +for more information. + +An ``UNKNOWN`` library type is typically only used in the implementation of +:ref:`Find Modules`. It allows the path to an imported library (often found +using the :command:`find_library` command) to be used without having to know +what type of library it is. This is especially useful on Windows where a +static library and a DLL's import library both have the same file extension. Object Libraries ^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake add_library(<name> OBJECT <src>...) @@ -109,22 +124,23 @@ along with those compiled from their own sources. Object libraries may contain only sources that compile, header files, and other files that would not affect linking of a normal library (e.g. ``.txt``). They may contain custom commands generating such sources, but not -``PRE_BUILD``, ``PRE_LINK``, or ``POST_BUILD`` commands. Object libraries -cannot be linked. Some native build systems may not like targets that -have only object files, so consider adding at least one real source file -to any target that references ``$<TARGET_OBJECTS:objlib>``. +``PRE_BUILD``, ``PRE_LINK``, or ``POST_BUILD`` commands. Some native build +systems (such as Xcode) may not like targets that have only object files, so +consider adding at least one real source file to any target that references +``$<TARGET_OBJECTS:objlib>``. Alias Libraries ^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake add_library(<name> ALIAS <target>) Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can be used to refer to ``<target>`` in subsequent commands. The ``<name>`` does not appear in the generated buildsystem as a make target. The ``<target>`` -may not be an :ref:`Imported Target <Imported Targets>` or an ``ALIAS``. +may not be a non-``GLOBAL`` :ref:`Imported Target <Imported Targets>` or an +``ALIAS``. ``ALIAS`` targets can be used as linkable targets and as targets to read properties from. They can also be tested for existence with the regular :command:`if(TARGET)` subcommand. The ``<name>`` may not be used @@ -136,7 +152,7 @@ installed or exported. Interface Libraries ^^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake add_library(<name> INTERFACE [IMPORTED [GLOBAL]]) @@ -148,6 +164,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 diff --git a/Help/command/add_link_options.rst b/Help/command/add_link_options.rst new file mode 100644 index 000000000..a83005b06 --- /dev/null +++ b/Help/command/add_link_options.rst @@ -0,0 +1,31 @@ +add_link_options +---------------- + +Add options to the link step for executable, shared library or module +library targets in the current directory and below that are added after +this command is invoked. + +.. code-block:: cmake + + add_link_options(<option> ...) + +This command can be used to add any link options, but alternative commands +exist to add libraries (:command:`target_link_libraries` or +:command:`link_libraries`). See documentation of the +:prop_dir:`directory <LINK_OPTIONS>` and +:prop_tgt:`target <LINK_OPTIONS>` ``LINK_OPTIONS`` properties. + +.. note:: + + This command cannot be used to add options for static library targets, + since they do not use a linker. To add archiver or MSVC librarian flags, + see the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property. + +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:: OPTIONS_SHELL.txt + +.. include:: LINK_OPTIONS_LINKER.txt diff --git a/Help/command/add_subdirectory.rst b/Help/command/add_subdirectory.rst index e97925302..8dba986ba 100644 --- a/Help/command/add_subdirectory.rst +++ b/Help/command/add_subdirectory.rst @@ -3,12 +3,11 @@ add_subdirectory Add a subdirectory to the build. -:: +.. code-block:: cmake - add_subdirectory(source_dir [binary_dir] - [EXCLUDE_FROM_ALL]) + add_subdirectory(source_dir [binary_dir] [EXCLUDE_FROM_ALL]) -Add a subdirectory to the build. The source_dir specifies the +Adds a subdirectory to the build. The source_dir specifies the directory in which the source CMakeLists.txt and code files are located. If it is a relative path it will be evaluated with respect to the current directory (the typical usage), but it may also be an @@ -30,7 +29,7 @@ project that is useful but not necessary, such as a set of examples. Typically the subdirectory should contain its own :command:`project` command invocation so that a full build system will be generated in the subdirectory (such as a VS IDE solution file). Note that inter-target -dependencies supercede this exclusion. If a target built by the +dependencies supersede this exclusion. If a target built by the parent project depends on a target in the subdirectory, the dependee target will be included in the parent project build system to satisfy the dependency. diff --git a/Help/command/add_test.rst b/Help/command/add_test.rst index d8a96e9b9..a77ba37cc 100644 --- a/Help/command/add_test.rst +++ b/Help/command/add_test.rst @@ -3,13 +3,14 @@ add_test Add a test to the project to be run by :manual:`ctest(1)`. -:: +.. code-block:: cmake add_test(NAME <name> COMMAND <command> [<arg>...] [CONFIGURATIONS <config>...] - [WORKING_DIRECTORY <dir>]) + [WORKING_DIRECTORY <dir>] + [COMMAND_EXPAND_LISTS]) -Add a test called ``<name>``. The test name may not contain spaces, +Adds a test called ``<name>``. The test name may not contain spaces, quotes, or other characters special in CMake syntax. The options are: ``COMMAND`` @@ -28,18 +29,26 @@ quotes, or other characters special in CMake syntax. The options are: directory set to the build directory corresponding to the current source directory. +``COMMAND_EXPAND_LISTS`` + Lists in ``COMMAND`` arguments will be expanded, including those + created with + :manual:`generator expressions <cmake-generator-expressions(7)>`. + The given test command is expected to exit with code ``0`` to pass and non-zero to fail, or vice-versa if the :prop_test:`WILL_FAIL` test property is set. Any output written to stdout or stderr will be captured by :manual:`ctest(1)` but does not affect the pass/fail status -unless the :prop_test:`PASS_REGULAR_EXPRESSION` or -:prop_test:`FAIL_REGULAR_EXPRESSION` test property is used. +unless the :prop_test:`PASS_REGULAR_EXPRESSION`, +:prop_test:`FAIL_REGULAR_EXPRESSION` or +:prop_test:`SKIP_REGULAR_EXPRESSION` test property is used. The ``COMMAND`` and ``WORKING_DIRECTORY`` options may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. -Example usage:: +Example usage: + +.. code-block:: cmake add_test(NAME mytest COMMAND testDriver --config $<CONFIGURATION> @@ -53,11 +62,12 @@ file produced by target ``myexe``. CMake will generate tests only if the :command:`enable_testing` command has been invoked. The :module:`CTest` module invokes the - command automatically when the ``BUILD_TESTING`` option is ``ON``. + command automatically unless the ``BUILD_TESTING`` option is turned + ``OFF``. --------------------------------------------------------------------- -:: +.. code-block:: cmake add_test(<name> <command> [<arg>...]) diff --git a/Help/command/aux_source_directory.rst b/Help/command/aux_source_directory.rst index dcd1cdfc3..9619f357f 100644 --- a/Help/command/aux_source_directory.rst +++ b/Help/command/aux_source_directory.rst @@ -3,7 +3,7 @@ aux_source_directory Find all source files in a directory. -:: +.. code-block:: cmake aux_source_directory(<dir> <variable>) @@ -11,14 +11,14 @@ Collects the names of all the source files in the specified directory and stores the list in the ``<variable>`` provided. This command is intended to be used by projects that use explicit template instantiation. Template instantiation files can be stored in a -"Templates" subdirectory and collected automatically using this +``Templates`` subdirectory and collected automatically using this command to avoid manually listing all instantiations. It is tempting to use this command to avoid writing the list of source files for a library or executable target. While this seems to work, there is no way for CMake to generate a build system that knows when a new source file has been added. Normally the generated build system -knows when it needs to rerun CMake because the CMakeLists.txt file is +knows when it needs to rerun CMake because the ``CMakeLists.txt`` file is modified to add a new source. When the source is just added to the directory without modifying this file, one would have to manually rerun CMake to generate a build system incorporating the new file. diff --git a/Help/command/break.rst b/Help/command/break.rst index fc2cd3c7b..4875a2bf2 100644 --- a/Help/command/break.rst +++ b/Help/command/break.rst @@ -3,10 +3,10 @@ break Break from an enclosing foreach or while loop. -:: +.. code-block:: cmake break() -Breaks from an enclosing foreach loop or while loop +Breaks from an enclosing :command:`foreach` or :command:`while` loop. See also the :command:`continue` command. diff --git a/Help/command/build_command.rst b/Help/command/build_command.rst index b83edaf57..6659005be 100644 --- a/Help/command/build_command.rst +++ b/Help/command/build_command.rst @@ -14,7 +14,7 @@ This is mainly intended for internal use by the :module:`CTest` module. Sets the given ``<variable>`` to a command-line string of the form:: - <cmake> --build . [--config <config>] [--target <target>] [-- -i] + <cmake> --build . [--config <config>] [--target <target>...] [-- -i] where ``<cmake>`` is the location of the :manual:`cmake(1)` command-line tool, and ``<config>`` and ``<target>`` are the values provided to the diff --git a/Help/command/build_name.rst b/Help/command/build_name.rst index f717db1dd..2a1fbae62 100644 --- a/Help/command/build_name.rst +++ b/Help/command/build_name.rst @@ -1,7 +1,7 @@ build_name ---------- -Disallowed. See CMake Policy :policy:`CMP0036`. +Disallowed since version 3.0. See CMake Policy :policy:`CMP0036`. Use ``${CMAKE_SYSTEM}`` and ``${CMAKE_CXX_COMPILER}`` instead. diff --git a/Help/command/cmake_host_system_information.rst b/Help/command/cmake_host_system_information.rst index 9402d57e9..2e9563aab 100644 --- a/Help/command/cmake_host_system_information.rst +++ b/Help/command/cmake_host_system_information.rst @@ -3,7 +3,7 @@ cmake_host_system_information Query host system specific information. -:: +.. code-block:: cmake cmake_host_system_information(RESULT <variable> QUERY <key> ...) @@ -13,13 +13,38 @@ queried. The list of queried values is stored in ``<variable>``. ``<key>`` can be one of the following values: -:: +============================= ================================================ +Key Description +============================= ================================================ +``NUMBER_OF_LOGICAL_CORES`` Number of logical cores +``NUMBER_OF_PHYSICAL_CORES`` Number of physical cores +``HOSTNAME`` Hostname +``FQDN`` Fully qualified domain name +``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 +``HAS_MMX_PLUS`` One if processor supports Ext. MMX instructions +``HAS_SSE`` One if processor supports SSE instructions +``HAS_SSE2`` One if processor supports SSE2 instructions +``HAS_SSE_FP`` One if processor supports SSE FP instructions +``HAS_SSE_MMX`` One if processor supports SSE MMX instructions +``HAS_AMD_3DNOW`` One if processor supports 3DNow instructions +``HAS_AMD_3DNOW_PLUS`` One if processor supports 3DNow+ instructions +``HAS_IA64`` One if IA64 processor emulating x86 +``HAS_SERIAL_NUMBER`` One if processor has serial number +``PROCESSOR_SERIAL_NUMBER`` Processor serial number +``PROCESSOR_NAME`` Human readable processor name +``PROCESSOR_DESCRIPTION`` Human readable full processor description +``OS_NAME`` See :variable:`CMAKE_HOST_SYSTEM_NAME` +``OS_RELEASE`` The OS sub-type e.g. on Windows ``Professional`` +``OS_VERSION`` The OS build ID +``OS_PLATFORM`` See :variable:`CMAKE_HOST_SYSTEM_PROCESSOR` +============================= ================================================ - NUMBER_OF_LOGICAL_CORES = Number of logical cores. - 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. +.. rubric:: Footnotes + +.. [#mebibytes] One MiB (mebibyte) is equal to 1024x1024 bytes. diff --git a/Help/command/cmake_minimum_required.rst b/Help/command/cmake_minimum_required.rst index 9535bf34f..e6ebcf0db 100644 --- a/Help/command/cmake_minimum_required.rst +++ b/Help/command/cmake_minimum_required.rst @@ -1,14 +1,26 @@ cmake_minimum_required ---------------------- -Set the minimum required version of cmake for a project and -update `Policy Settings`_ to match the version given:: +Require a minimum version of cmake. - cmake_minimum_required(VERSION major.minor[.patch[.tweak]] - [FATAL_ERROR]) +.. code-block:: cmake -If the current version of CMake is lower than that required it will -stop processing the project and report an error. + cmake_minimum_required(VERSION <min>[...<max>] [FATAL_ERROR]) + +Sets the minimum required version of cmake for a project. +Also updates the policy settings as explained below. + +``<min>`` and the optional ``<max>`` are each CMake versions of the form +``major.minor[.patch[.tweak]]``, and the ``...`` is literal. + +If the running version of CMake is lower than the ``<min>`` required +version it will stop processing the project and report an error. +The optional ``<max>`` version, if specified, must be at least the +``<min>`` version and affects policy settings as described below. +If the running version of CMake is older than 3.12, the extra ``...`` +dots will be seen as version component separators, resulting in the +``...<max>`` part being ignored and preserving the pre-3.12 behavior +of basing policies on ``<min>``. The ``FATAL_ERROR`` option is accepted but ignored by CMake 2.6 and higher. It should be specified so CMake versions 2.4 and lower fail @@ -30,21 +42,27 @@ Policy Settings The ``cmake_minimum_required(VERSION)`` command implicitly invokes the :command:`cmake_policy(VERSION)` command to specify that the current -project code is written for the given version of CMake. -All policies introduced in the specified version or earlier will be -set to use NEW behavior. All policies introduced after the specified -version will be unset. This effectively requests behavior preferred +project code is written for the given range of CMake versions. +All policies known to the running version of CMake and introduced +in the ``<min>`` (or ``<max>``, if specified) version or earlier will +be set to use ``NEW`` behavior. All policies introduced in later +versions will be unset. This effectively requests behavior preferred as of a given CMake version and tells newer CMake versions to warn about their new policies. -When a version higher than 2.4 is specified the command implicitly -invokes:: +When a ``<min>`` version higher than 2.4 is specified the command +implicitly invokes + +.. code-block:: cmake + + cmake_policy(VERSION <min>[...<max>]) - cmake_policy(VERSION major[.minor[.patch[.tweak]]]) +which sets CMake policies based on the range of versions specified. +When a ``<min>`` version 2.4 or lower is given the command implicitly +invokes -which sets the cmake policy version level to the version specified. -When version 2.4 or lower is given the command implicitly invokes:: +.. code-block:: cmake - cmake_policy(VERSION 2.4) + cmake_policy(VERSION 2.4[...<max>]) which enables compatibility features for CMake 2.4 and lower. diff --git a/Help/command/cmake_parse_arguments.rst b/Help/command/cmake_parse_arguments.rst index ec4ffed3a..fcd36d0a3 100644 --- a/Help/command/cmake_parse_arguments.rst +++ b/Help/command/cmake_parse_arguments.rst @@ -1,26 +1,28 @@ cmake_parse_arguments --------------------- -``cmake_parse_arguments`` is intended to be used in macros or functions for -parsing the arguments given to that macro or function. It processes the -arguments and defines a set of variables which hold the values of the -respective options. +Parse function or macro arguments. -:: +.. code-block:: cmake cmake_parse_arguments(<prefix> <options> <one_value_keywords> - <multi_value_keywords> args...) + <multi_value_keywords> <args>...) - cmake_parse_arguments(PARSE_ARGV N <prefix> <options> <one_value_keywords> - <multi_value_keywords>) + cmake_parse_arguments(PARSE_ARGV <N> <prefix> <options> + <one_value_keywords> <multi_value_keywords>) -The first signature reads processes arguments passed in the ``args...``. +This command is for use in macros or functions. +It processes the arguments given to that macro or function, +and defines a set of variables which hold the values of the +respective options. + +The first signature reads processes arguments passed in the ``<args>...``. This may be used in either a :command:`macro` or a :command:`function`. The ``PARSE_ARGV`` signature is only for use in a :command:`function` body. In this case the arguments that are parsed come from the ``ARGV#`` variables of the calling function. The parsing starts with -the Nth argument, where ``N`` is an unsigned integer. This allows for +the ``<N>``-th argument, where ``<N>`` is an unsigned integer. This allows for the values to have special characters like ``;`` in them. The ``<options>`` argument contains all options for the respective macro, @@ -43,23 +45,31 @@ macro which can be followed by more than one value, like e.g. the ``<multi_value_keywords>``. A warning will be emitted if uniqueness is violated. -When done, ``cmake_parse_arguments`` will have defined for each of the +When done, ``cmake_parse_arguments`` will consider for each of the keywords listed in ``<options>``, ``<one_value_keywords>`` and ``<multi_value_keywords>`` a variable composed of the given ``<prefix>`` followed by ``"_"`` and the name of the respective keyword. These -variables will then hold the respective value from the argument list. -For the ``<options>`` keywords this will be ``TRUE`` or ``FALSE``. +variables will then hold the respective value from the argument list +or be undefined if the associated option could not be found. +For the ``<options>`` keywords, these will always be defined, +to ``TRUE`` or ``FALSE``, whether the option is in the argument list or not. All remaining arguments are collected in a variable -``<prefix>_UNPARSED_ARGUMENTS``, this can be checked afterwards to see +``<prefix>_UNPARSED_ARGUMENTS`` that will be undefined if all arguments +were recognized. This can be checked afterwards to see whether your macro was called with unrecognized parameters. -As an example here a ``my_install()`` macro, which takes similar arguments -as the real :command:`install` command: +``<one_value_keywords>`` and ``<multi_value_keywords>`` that were given no +values at all are collected in a variable ``<prefix>_KEYWORDS_MISSING_VALUES`` +that will be undefined if all keywords received values. This can be checked +to see if there were keywords without any values given. + +Consider the following example macro, ``my_install()``, which takes similar +arguments to the real :command:`install` command: .. code-block:: cmake - function(MY_INSTALL) + macro(my_install) set(options OPTIONAL FAST) set(oneValueArgs DESTINATION RENAME) set(multiValueArgs TARGETS CONFIGURATIONS) @@ -72,25 +82,28 @@ Assume ``my_install()`` has been called like this: .. code-block:: cmake - my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub) + my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub CONFIGURATIONS) -After the ``cmake_parse_arguments`` call the macro will have set the -following variables:: +After the ``cmake_parse_arguments`` call the macro will have set or undefined +the following variables:: MY_INSTALL_OPTIONAL = TRUE - MY_INSTALL_FAST = FALSE (was not used in call to my_install) + MY_INSTALL_FAST = FALSE # was not used in call to my_install MY_INSTALL_DESTINATION = "bin" - MY_INSTALL_RENAME = "" (was not used) + MY_INSTALL_RENAME <UNDEFINED> # was not used MY_INSTALL_TARGETS = "foo;bar" - MY_INSTALL_CONFIGURATIONS = "" (was not used) - MY_INSTALL_UNPARSED_ARGUMENTS = "blub" (nothing expected after "OPTIONAL") + MY_INSTALL_CONFIGURATIONS <UNDEFINED> # was not used + MY_INSTALL_UNPARSED_ARGUMENTS = "blub" # nothing expected after "OPTIONAL" + MY_INSTALL_KEYWORDS_MISSING_VALUES = "CONFIGURATIONS" + # No value for "CONFIGURATIONS" given You can then continue and process these variables. -Keywords terminate lists of values, e.g. if directly after a -one_value_keyword another recognized keyword follows, this is +Keywords terminate lists of values, e.g. if directly after a +``one_value_keyword`` another recognized keyword follows, this is interpreted as the beginning of the new option. E.g. ``my_install(TARGETS foo DESTINATION OPTIONAL)`` would result in ``MY_INSTALL_DESTINATION`` set to ``"OPTIONAL"``, but as ``OPTIONAL`` -is a keyword itself ``MY_INSTALL_DESTINATION`` will be empty and -``MY_INSTALL_OPTIONAL`` will therefore be set to ``TRUE``. +is a keyword itself ``MY_INSTALL_DESTINATION`` will be empty (but added +to ``MY_INSTALL_KEYWORDS_MISSING_VALUES``) and ``MY_INSTALL_OPTIONAL`` will +therefore be set to ``TRUE``. diff --git a/Help/command/cmake_policy.rst b/Help/command/cmake_policy.rst index b51b9512c..4bc7807bb 100644 --- a/Help/command/cmake_policy.rst +++ b/Help/command/cmake_policy.rst @@ -22,19 +22,29 @@ Setting Policies by CMake Version The ``cmake_policy`` command is used to set policies to ``OLD`` or ``NEW`` behavior. While setting policies individually is supported, we -encourage projects to set policies based on CMake versions:: - - cmake_policy(VERSION major.minor[.patch[.tweak]]) - -Specify that the current CMake code is written for the given -version of CMake. All policies introduced in the specified version or -earlier will be set to use ``NEW`` behavior. All policies introduced -after the specified version will be unset (unless the +encourage projects to set policies based on CMake versions: + +.. code-block:: cmake + + cmake_policy(VERSION <min>[...<max>]) + +``<min>`` and the optional ``<max>`` are each CMake versions of the form +``major.minor[.patch[.tweak]]``, and the ``...`` is literal. The ``<min>`` +version must be at least ``2.4`` and at most the running version of CMake. +The ``<max>`` version, if specified, must be at least the ``<min>`` version +but may exceed the running version of CMake. If the running version of +CMake is older than 3.12, the extra ``...`` dots will be seen as version +component separators, resulting in the ``...<max>`` part being ignored and +preserving the pre-3.12 behavior of basing policies on ``<min>``. + +This specifies that the current CMake code is written for the given +range of CMake versions. All policies known to the running version of CMake +and introduced in the ``<min>`` (or ``<max>``, if specified) version +or earlier will be set to use ``NEW`` behavior. All policies +introduced in later versions will be unset (unless the :variable:`CMAKE_POLICY_DEFAULT_CMP<NNNN>` variable sets a default). This effectively requests behavior preferred as of a given CMake version and tells newer CMake versions to warn about their new policies. -The policy version specified must be at least 2.4 or the command will -report an error. Note that the :command:`cmake_minimum_required(VERSION)` command implicitly calls ``cmake_policy(VERSION)`` too. @@ -42,7 +52,7 @@ command implicitly calls ``cmake_policy(VERSION)`` too. Setting Policies Explicitly ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake cmake_policy(SET CMP<NNNN> NEW) cmake_policy(SET CMP<NNNN> OLD) @@ -58,7 +68,7 @@ policy state to ``NEW``. Checking Policy Settings ^^^^^^^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake cmake_policy(GET CMP<NNNN> <variable>) @@ -70,14 +80,16 @@ CMake Policy Stack ^^^^^^^^^^^^^^^^^^ CMake keeps policy settings on a stack, so changes made by the -cmake_policy command affect only the top of the stack. A new entry on +``cmake_policy`` command affect only the top of the stack. A new entry on the policy stack is managed automatically for each subdirectory to protect its parents and siblings. CMake also manages a new entry for scripts loaded by :command:`include` and :command:`find_package` commands except when invoked with the ``NO_POLICY_SCOPE`` option (see also policy :policy:`CMP0011`). The ``cmake_policy`` command provides an interface to manage custom -entries on the policy stack:: +entries on the policy stack: + +.. code-block:: cmake cmake_policy(PUSH) cmake_policy(POP) diff --git a/Help/command/configure_file.rst b/Help/command/configure_file.rst index 4304f095b..29e85bd16 100644 --- a/Help/command/configure_file.rst +++ b/Help/command/configure_file.rst @@ -3,7 +3,7 @@ configure_file Copy a file to another location and modify its contents. -:: +.. code-block:: cmake configure_file(<input> <output> [COPYONLY] [ESCAPE_QUOTES] [@ONLY] @@ -13,15 +13,21 @@ Copies an ``<input>`` file to an ``<output>`` file and substitutes variable values referenced as ``@VAR@`` or ``${VAR}`` in the input file content. Each variable reference will be replaced with the current value of the variable, or the empty string if the variable -is not defined. Furthermore, input lines of the form:: +is not defined. Furthermore, input lines of the form + +.. code-block:: c #cmakedefine VAR ... -will be replaced with either:: +will be replaced with either + +.. code-block:: c #define VAR ... -or:: +or + +.. code-block:: c /* #undef VAR */ @@ -30,9 +36,27 @@ a false constant by the :command:`if` command. The "..." content on the line after the variable name, if any, is processed as above. Input file lines of the form ``#cmakedefine01 VAR`` will be replaced with either ``#define VAR 1`` or ``#define VAR 0`` similarly. +The result lines (with the exception of the ``#undef`` comments) can be +indented using spaces and/or tabs between the ``#`` character +and the ``cmakedefine`` or ``cmakedefine01`` words. This whitespace +indentation will be preserved in the output lines: + +.. code-block:: c + + # cmakedefine VAR + # cmakedefine01 VAR + +will be replaced, if ``VAR`` is defined, with + +.. code-block:: c + + # define VAR + # define VAR 1 If the input file is modified the build system will re-run CMake to re-configure the file and generate the build system again. +The generated file is modified and its timestamp updated on subsequent +cmake runs only if its content is changed. The arguments are: diff --git a/Help/command/continue.rst b/Help/command/continue.rst index 1c7d6730c..31c7089a1 100644 --- a/Help/command/continue.rst +++ b/Help/command/continue.rst @@ -3,10 +3,12 @@ continue Continue to the top of enclosing foreach or while loop. -:: +.. code-block:: cmake continue() The ``continue`` command allows a cmake script to abort the rest of a block in a :command:`foreach` or :command:`while` loop, and start at the top of -the next iteration. See also the :command:`break` command. +the next iteration. + +See also the :command:`break` command. diff --git a/Help/command/create_test_sourcelist.rst b/Help/command/create_test_sourcelist.rst index dde6812e1..77e37c50f 100644 --- a/Help/command/create_test_sourcelist.rst +++ b/Help/command/create_test_sourcelist.rst @@ -3,7 +3,7 @@ create_test_sourcelist Create a test driver and source list for building test programs. -:: +.. code-block:: cmake create_test_sourcelist(sourceListName driverName test1 test2 test3 diff --git a/Help/command/ctest_build.rst b/Help/command/ctest_build.rst index 55bb4a317..66e1844e9 100644 --- a/Help/command/ctest_build.rst +++ b/Help/command/ctest_build.rst @@ -50,9 +50,7 @@ The options are: for an example. ``PROJECT_NAME <project-name>`` - Set the name of the project to build. This should correspond - to the top-level call to the :command:`project` command. - If not specified the ``CTEST_PROJECT_NAME`` variable will be checked. + Ignored. This was once used but is no longer needed. ``TARGET <target-name>`` Specify the name of a target to build. If not specified the diff --git a/Help/command/ctest_coverage.rst b/Help/command/ctest_coverage.rst index 8d27b9c1b..d50f63498 100644 --- a/Help/command/ctest_coverage.rst +++ b/Help/command/ctest_coverage.rst @@ -8,7 +8,7 @@ Perform the :ref:`CTest Coverage Step` as a :ref:`Dashboard Client`. ctest_coverage([BUILD <build-dir>] [APPEND] [LABELS <label>...] [RETURN_VALUE <result-var>] - [CAPTURE_CMAKE_ERROR <result-var] + [CAPTURE_CMAKE_ERROR <result-var>] [QUIET] ) diff --git a/Help/command/ctest_start.rst b/Help/command/ctest_start.rst index 63db32f4e..f0704aca5 100644 --- a/Help/command/ctest_start.rst +++ b/Help/command/ctest_start.rst @@ -5,21 +5,79 @@ Starts the testing for a given model :: - ctest_start(Model [TRACK <track>] [APPEND] [source [binary]] [QUIET]) + ctest_start(<model> [<source> [<binary>]] [GROUP <group>] [QUIET]) + + ctest_start([<model> [<source> [<binary>]]] [GROUP <group>] APPEND [QUIET]) Starts the testing for a given model. The command should be called -after the binary directory is initialized. If the 'source' and -'binary' directory are not specified, it reads the -:variable:`CTEST_SOURCE_DIRECTORY` and :variable:`CTEST_BINARY_DIRECTORY`. -If the track is -specified, the submissions will go to the specified track. If APPEND -is used, the existing TAG is used rather than creating a new one based -on the current time stamp. If ``QUIET`` is used, CTest will suppress any -non-error messages that it otherwise would have printed to the console. - -If the :variable:`CTEST_CHECKOUT_COMMAND` variable -(or the :variable:`CTEST_CVS_CHECKOUT` variable) -is set, its content is treated as command-line. The command is -invoked with the current working directory set to the parent of the source -directory, even if the source directory already exists. This can be used -to create the source tree from a version control repository. +after the binary directory is initialized. + +The parameters are as follows: + +``<model>`` + Set the dashboard model. Must be one of ``Experimental``, ``Continuous``, or + ``Nightly``. This parameter is required unless ``APPEND`` is specified. + +``<source>`` + Set the source directory. If not specified, the value of + :variable:`CTEST_SOURCE_DIRECTORY` is used instead. + +``<binary>`` + Set the binary directory. If not specified, the value of + :variable:`CTEST_BINARY_DIRECTORY` is used instead. + +``GROUP <group>`` + If ``GROUP`` is used, the submissions will go to the specified group on the + CDash server. If no ``GROUP`` is specified, the name of the model is used by + default. This replaces the deprecated option ``TRACK``. Despite the name + change its behavior is unchanged. + +``APPEND`` + If ``APPEND`` is used, the existing ``TAG`` is used rather than creating a new + one based on the current time stamp. If you use ``APPEND``, you can omit the + ``<model>`` and ``GROUP <group>`` parameters, because they will be read from + the generated ``TAG`` file. For example: + + .. code-block:: cmake + + ctest_start(Experimental GROUP GroupExperimental) + + Later, in another ``ctest -S`` script: + + .. code-block:: cmake + + ctest_start(APPEND) + + When the second script runs ``ctest_start(APPEND)``, it will read the + ``Experimental`` model and ``GroupExperimental`` group from the ``TAG`` file + generated by the first ``ctest_start()`` command. Please note that if you + call ``ctest_start(APPEND)`` and specify a different model or group than + in the first ``ctest_start()`` command, a warning will be issued, and the + new model and group will be used. + +``QUIET`` + If ``QUIET`` is used, CTest will suppress any non-error messages that it + otherwise would have printed to the console. + +The parameters for ``ctest_start()`` can be issued in any order, with the +exception that ``<model>``, ``<source>``, and ``<binary>`` have to appear +in that order with respect to each other. The following are all valid and +equivalent: + +.. code-block:: cmake + + ctest_start(Experimental path/to/source path/to/binary GROUP SomeGroup QUIET APPEND) + + ctest_start(GROUP SomeGroup Experimental QUIET path/to/source APPEND path/to/binary) + + ctest_start(APPEND QUIET Experimental path/to/source GROUP SomeGroup path/to/binary) + +However, for the sake of readability, it is recommended that you order your +parameters in the order listed at the top of this page. + +If the :variable:`CTEST_CHECKOUT_COMMAND` variable (or the +:variable:`CTEST_CVS_CHECKOUT` variable) is set, its content is treated as +command-line. The command is invoked with the current working directory set +to the parent of the source directory, even if the source directory already +exists. This can be used to create the source tree from a version control +repository. diff --git a/Help/command/ctest_submit.rst b/Help/command/ctest_submit.rst index 6b49da392..983fc20ce 100644 --- a/Help/command/ctest_submit.rst +++ b/Help/command/ctest_submit.rst @@ -6,10 +6,13 @@ Perform the :ref:`CTest Submit Step` as a :ref:`Dashboard Client`. :: ctest_submit([PARTS <part>...] [FILES <file>...] + [SUBMIT_URL <url>] + [BUILD_ID <result-var>] [HTTPHEADER <header>] [RETRY_COUNT <count>] [RETRY_DELAY <delay>] [RETURN_VALUE <result-var>] + [CAPTURE_CMAKE_ERROR <result-var>] [QUIET] ) @@ -32,14 +35,31 @@ The options are: ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES Upload = Files prepared for upload by ctest_upload(), in Upload.xml Submit = nothing + Done = Build is complete, in Done.xml ``FILES <file>...`` Specify an explicit list of specific files to be submitted. Each individual file must exist at the time of the call. +``SUBMIT_URL <url>`` + The ``http`` or ``https`` URL of the dashboard server to send the submission + to. If not given, the :variable:`CTEST_SUBMIT_URL` variable is used. + +``BUILD_ID <result-var>`` + Store in the ``<result-var>`` variable the ID assigned to this build by + CDash. + ``HTTPHEADER <HTTP-header>`` Specify HTTP header to be included in the request to CDash during submission. - This suboption can be repeated several times. + For example, CDash can be configured to only accept submissions from + authenticated clients. In this case, you should provide a bearer token in your + header: + + .. code-block:: cmake + + ctest_submit(HTTPHEADER "Authorization: Bearer <auth-token>") + + This suboption can be repeated several times for multiple headers. ``RETRY_COUNT <count>`` Specify how many times to retry a timed-out submission. @@ -52,6 +72,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. @@ -62,16 +86,19 @@ Submit to CDash Upload API :: ctest_submit(CDASH_UPLOAD <file> [CDASH_UPLOAD_TYPE <type>] + [SUBMIT_URL <url>] [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 -file upload API. The api first sends a request to upload to CDash along +file upload API. The API first sends a request to upload to CDash along 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 ``SUBMIT_URL``, ``BUILD_ID``, ``HTTPHEADER``, +``RETRY_COUNT``, ``RETRY_DELAY``, ``RETURN_VALUE`` and ``QUIET`` options +as described above. diff --git a/Help/command/ctest_test.rst b/Help/command/ctest_test.rst index 4a69491d5..7a3393b4d 100644 --- a/Help/command/ctest_test.rst +++ b/Help/command/ctest_test.rst @@ -17,6 +17,7 @@ Perform the :ref:`CTest Test Step` as a :ref:`Dashboard Client`. [EXCLUDE_FIXTURE_SETUP <regex>] [EXCLUDE_FIXTURE_CLEANUP <regex>] [PARALLEL_LEVEL <level>] + [RESOURCE_SPEC_FILE <file>] [TEST_LOAD <threshold>] [SCHEDULE_RANDOM <ON|OFF>] [STOP_TIME <time-of-day>] @@ -82,6 +83,11 @@ The options are: Specify a positive number representing the number of tests to be run in parallel. +``RESOURCE_SPEC_FILE <file>`` + Specify a + :ref:`resource specification file <ctest-resource-specification-file>`. See + :ref:`ctest-resource-allocation` for more information. + ``TEST_LOAD <threshold>`` While running tests in parallel, try not to start tests when they may cause the CPU load to pass above a given threshold. If not diff --git a/Help/command/ctest_update.rst b/Help/command/ctest_update.rst index b205bca93..96a11c913 100644 --- a/Help/command/ctest_update.rst +++ b/Help/command/ctest_update.rst @@ -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 @@ -28,4 +35,5 @@ The options are: The update always follows the version control branch currently checked out in the source directory. See the :ref:`CTest Update Step` -documentation for more information. +documentation for information about variables that change the behavior +of ``ctest_update()``. diff --git a/Help/command/define_property.rst b/Help/command/define_property.rst index 873c6cabb..8f7439bbe 100644 --- a/Help/command/define_property.rst +++ b/Help/command/define_property.rst @@ -3,7 +3,7 @@ define_property Define and document custom properties. -:: +.. code-block:: cmake define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE | TEST | VARIABLE | CACHED_VARIABLE> @@ -11,7 +11,7 @@ Define and document custom properties. BRIEF_DOCS <brief-doc> [docs...] FULL_DOCS <full-doc> [docs...]) -Define one property in a scope for use with the :command:`set_property` and +Defines one property in a scope for use with the :command:`set_property` and :command:`get_property` commands. This is primarily useful to associate documentation with property names that may be retrieved with the :command:`get_property` command. The first argument determines the kind of @@ -34,10 +34,24 @@ actual scope needs to be given; only the kind of scope is important. The required ``PROPERTY`` option is immediately followed by the name of the property being defined. -If the ``INHERITED`` option then the :command:`get_property` command will -chain up to the next higher scope when the requested property is not set -in the scope given to the command. ``DIRECTORY`` scope chains to -``GLOBAL``. ``TARGET``, ``SOURCE``, and ``TEST`` chain to ``DIRECTORY``. +If the ``INHERITED`` option is given, then the :command:`get_property` command +will chain up to the next higher scope when the requested property is not set +in the scope given to the command. + +* ``DIRECTORY`` scope chains to its parent directory's scope, continuing the + walk up parent directories until a directory has the property set or there + are no more parents. If still not found at the top level directory, it + chains to the ``GLOBAL`` scope. +* ``TARGET``, ``SOURCE`` and ``TEST`` properties chain to ``DIRECTORY`` scope, + including further chaining up the directories, etc. as needed. + +Note that this scope chaining behavior only applies to calls to +:command:`get_property`, :command:`get_directory_property`, +:command:`get_target_property`, :command:`get_source_file_property` and +:command:`get_test_property`. There is no inheriting behavior when *setting* +properties, so using ``APPEND`` or ``APPEND_STRING`` with the +:command:`set_property` command will not consider inherited values when working +out the contents to append to. The ``BRIEF_DOCS`` and ``FULL_DOCS`` options are followed by strings to be associated with the property as its brief and full documentation. diff --git a/Help/command/else.rst b/Help/command/else.rst index 0e5a19810..a98fcd88e 100644 --- a/Help/command/else.rst +++ b/Help/command/else.rst @@ -3,8 +3,8 @@ else Starts the else portion of an if block. -:: +.. code-block:: cmake - else(expression) + else([<condition>]) See the :command:`if` command. diff --git a/Help/command/elseif.rst b/Help/command/elseif.rst index 9a8dfed1d..6bf8646fb 100644 --- a/Help/command/elseif.rst +++ b/Help/command/elseif.rst @@ -1,10 +1,11 @@ elseif ------ -Starts the elseif portion of an if block. +Starts an elseif portion of an if block. -:: +.. code-block:: cmake - elseif(expression) + elseif(<condition>) -See the :command:`if` command. +See the :command:`if` command, especially for the syntax and logic +of the ``<condition>``. diff --git a/Help/command/enable_language.rst b/Help/command/enable_language.rst index 444556151..fdc44f2bc 100644 --- a/Help/command/enable_language.rst +++ b/Help/command/enable_language.rst @@ -1,16 +1,18 @@ enable_language --------------- +Enable a language (CXX/C/OBJC/OBJCXX/Fortran/etc) -Enable a language (CXX/C/Fortran/etc) - -:: +.. code-block:: cmake enable_language(<lang> [OPTIONAL] ) -This command enables support for the named language in CMake. This is -the same as the project command but does not create any of the extra +Enables support for the named language in CMake. This is +the same as the :command:`project` command but does not create any of the extra variables that are created by the project command. Example languages -are CXX, C, Fortran. +are ``CXX``, ``C``, ``CUDA``, ``OBJC``, ``OBJCXX``, ``Fortran``, and ``ASM``. + +If enabling ``ASM``, enable it last so that CMake can check whether +compilers for other languages like ``C`` work for assembly too. This command must be called in file scope, not in a function call. Furthermore, it must be called in the highest directory common to all @@ -19,4 +21,5 @@ indirectly through link dependencies. It is simplest to enable all needed languages in the top-level directory of a project. The ``OPTIONAL`` keyword is a placeholder for future implementation and -does not currently work. +does not currently work. Instead you can use the :module:`CheckLanguage` +module to verify support before enabling. diff --git a/Help/command/enable_testing.rst b/Help/command/enable_testing.rst index 1e3e2799c..3ac1a198a 100644 --- a/Help/command/enable_testing.rst +++ b/Help/command/enable_testing.rst @@ -3,11 +3,18 @@ enable_testing Enable testing for current directory and below. -:: +.. code-block:: cmake enable_testing() -Enables testing for this directory and below. See also the -:command:`add_test` command. Note that ctest expects to find a test file -in the build directory root. Therefore, this command should be in the -source directory root. +Enables testing for this directory and below. + +This command should be in the source directory root +because ctest expects to find a test file in the build +directory root. + +This command is automatically invoked when the :module:`CTest` +module is included, except if the ``BUILD_TESTING`` option is +turned off. + +See also the :command:`add_test` command. diff --git a/Help/command/endforeach.rst b/Help/command/endforeach.rst index 9af972bee..fd923d56a 100644 --- a/Help/command/endforeach.rst +++ b/Help/command/endforeach.rst @@ -3,8 +3,12 @@ endforeach Ends a list of commands in a foreach block. -:: +.. code-block:: cmake - endforeach(expression) + endforeach([<loop_var>]) See the :command:`foreach` command. + +The optional ``<loop_var>`` argument is supported for backward compatibility +only. If used it must be a verbatim repeat of the ``<loop_var>`` argument of +the opening ``foreach`` clause. diff --git a/Help/command/endfunction.rst b/Help/command/endfunction.rst index 6cc196cde..e27129d8a 100644 --- a/Help/command/endfunction.rst +++ b/Help/command/endfunction.rst @@ -3,8 +3,12 @@ endfunction Ends a list of commands in a function block. -:: +.. code-block:: cmake - endfunction(expression) + endfunction([<name>]) See the :command:`function` command. + +The optional ``<name>`` argument is supported for backward compatibility +only. If used it must be a verbatim repeat of the ``<name>`` argument +of the opening ``function`` command. diff --git a/Help/command/endif.rst b/Help/command/endif.rst index a0163bf33..fc4f03822 100644 --- a/Help/command/endif.rst +++ b/Help/command/endif.rst @@ -3,8 +3,12 @@ endif Ends a list of commands in an if block. -:: +.. code-block:: cmake - endif(expression) + endif([<condition>]) See the :command:`if` command. + +The optional ``<condition>`` argument is supported for backward compatibility +only. If used it must be a verbatim repeat of the argument of the opening +``if`` clause. diff --git a/Help/command/endmacro.rst b/Help/command/endmacro.rst index 47327a783..4290ba748 100644 --- a/Help/command/endmacro.rst +++ b/Help/command/endmacro.rst @@ -3,8 +3,12 @@ endmacro Ends a list of commands in a macro block. -:: +.. code-block:: cmake - endmacro(expression) + endmacro([<name>]) See the :command:`macro` command. + +The optional ``<name>`` argument is supported for backward compatibility +only. If used it must be a verbatim repeat of the ``<name>`` argument +of the opening ``macro`` command. diff --git a/Help/command/endwhile.rst b/Help/command/endwhile.rst index 798c20e71..5ef585bdc 100644 --- a/Help/command/endwhile.rst +++ b/Help/command/endwhile.rst @@ -3,8 +3,12 @@ endwhile Ends a list of commands in a while block. -:: +.. code-block:: cmake - endwhile(expression) + endwhile([<condition>]) See the :command:`while` command. + +The optional ``<condition>`` argument is supported for backward compatibility +only. If used it must be a verbatim repeat of the argument of the opening +``while`` clause. diff --git a/Help/command/exec_program.rst b/Help/command/exec_program.rst index 6dfdad394..bc9b06916 100644 --- a/Help/command/exec_program.rst +++ b/Help/command/exec_program.rst @@ -1,7 +1,9 @@ exec_program ------------ -Deprecated. Use the :command:`execute_process` command instead. +.. deprecated:: 3.0 + + Use the :command:`execute_process` command instead. Run an executable program during the processing of the CMakeList.txt file. diff --git a/Help/command/execute_process.rst b/Help/command/execute_process.rst index d617243d1..14f879d03 100644 --- a/Help/command/execute_process.rst +++ b/Help/command/execute_process.rst @@ -5,11 +5,12 @@ Execute one or more child processes. .. code-block:: cmake - execute_process(COMMAND <cmd1> [args1...]] - [COMMAND <cmd2> [args2...] [...]] + execute_process(COMMAND <cmd1> [<arguments>] + [COMMAND <cmd2> [<arguments>]]... [WORKING_DIRECTORY <directory>] [TIMEOUT <seconds>] [RESULT_VARIABLE <variable>] + [RESULTS_VARIABLE <variable>] [OUTPUT_VARIABLE <variable>] [ERROR_VARIABLE <variable>] [INPUT_FILE <file>] @@ -17,11 +18,14 @@ Execute one or more child processes. [ERROR_FILE <file>] [OUTPUT_QUIET] [ERROR_QUIET] + [COMMAND_ECHO <where>] [OUTPUT_STRIP_TRAILING_WHITESPACE] [ERROR_STRIP_TRAILING_WHITESPACE] [ENCODING <name>]) -Runs the given sequence of one or more commands in parallel with the standard +Runs the given sequence of one or more commands. + +Commands are executed concurrently as a pipeline, with the standard output of each process piped to the standard input of the next. A single standard error pipe is used for all processes. @@ -45,14 +49,21 @@ Options: the child processes. ``TIMEOUT`` - The child processes will be terminated if they do not finish in the - specified number of seconds (fractions are allowed). + After the specified number of seconds (fractions allowed), all unfinished + child processes will be terminated, and the ``RESULT_VARIABLE`` will be + set to a string mentioning the "timeout". ``RESULT_VARIABLE`` - The variable will be set to contain the result of running the processes. + The variable will be set to contain the result of last child process. This will be an integer return code from the last child or a string describing an error condition. +``RESULTS_VARIABLE <variable>`` + The variable will be set to contain the result of all processes as a + :ref:`semicolon-separated list <CMake Language Lists>`, in order of the + given ``COMMAND`` arguments. Each entry will be an integer return code + from the corresponding child or a string describing an error condition. + ``OUTPUT_VARIABLE``, ``ERROR_VARIABLE`` The variable named will be set with the contents of the standard output and standard error pipes, respectively. If the same variable is named @@ -67,6 +78,12 @@ Options: ``OUTPUT_QUIET``, ``ERROR_QUIET`` The standard output or standard error results will be quietly ignored. +``COMMAND_ECHO <where>`` + The command being run will be echo'ed to ``<where>`` with ``<where>`` + being set to one of ``STDERR``, ``STDOUT`` or ``NONE``. + See the :variable:`CMAKE_EXECUTE_PROCESS_COMMAND_ECHO` variable for a way + to control the default behavior when this option is not present. + ``ENCODING <name>`` On Windows, the encoding that is used to decode output from the process. Ignored on other platforms. @@ -83,8 +100,10 @@ Options: Use the ANSI codepage. ``OEM`` Use the original equipment manufacturer (OEM) code page. - ``UTF8`` - Use the UTF-8 codepage. + ``UTF8`` or ``UTF-8`` + Use the UTF-8 codepage. Prior to CMake 3.11.0, only ``UTF8`` was accepted + for this encoding. In CMake 3.11.0, ``UTF-8`` was added for consistency with + the `UTF-8 RFC <https://www.ietf.org/rfc/rfc3629>`_ naming convention. If more than one ``OUTPUT_*`` or ``ERROR_*`` option is given for the same pipe the precedence is not specified. diff --git a/Help/command/export.rst b/Help/command/export.rst index 53675a756..2ca705616 100644 --- a/Help/command/export.rst +++ b/Help/command/export.rst @@ -3,11 +3,11 @@ export Export targets from the build tree for use by outside projects. -:: +.. code-block:: cmake export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>]) -Create a file ``<filename>`` that may be included by outside projects to +Creates a file ``<filename>`` that may be included by outside projects to import targets from the current project's build tree. This is useful during cross-compiling to build utility executables that can run on the host platform in one project and then import them into another @@ -25,7 +25,7 @@ export targets from an installation tree. The properties set on the generated IMPORTED targets will have the same values as the final values of the input TARGETS. -:: +.. code-block:: cmake export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>] [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES]) @@ -40,23 +40,37 @@ policy CMP0022 is NEW. If a library target is included in the export but a target to which it links is not included the behavior is unspecified. -:: +.. note:: - export(PACKAGE <name>) + :ref:`Object Libraries` under :generator:`Xcode` have special handling if + multiple architectures are listed in :variable:`CMAKE_OSX_ARCHITECTURES`. + In this case they will be exported as :ref:`Interface Libraries` with + no object files available to clients. This is sufficient to satisfy + transitive usage requirements of other targets that link to the + object libraries in their implementation. + +.. code-block:: cmake + + 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 :command:`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 -is enabled, the ``export(PACKAGE)`` command will do nothing. +registry. + +By default the ``export(PACKAGE)`` command does nothing (see policy +:policy:`CMP0090`) because populating the user package registry has effects +outside the source and build trees. Set the +:variable:`CMAKE_EXPORT_PACKAGE_REGISTRY` variable to add build directories to +the CMake user package registry. -:: +.. code-block:: cmake export(TARGETS [target1 [target2 [...]]] [ANDROID_MK <filename>]) diff --git a/Help/command/export_library_dependencies.rst b/Help/command/export_library_dependencies.rst index 2cb437e77..9753abf54 100644 --- a/Help/command/export_library_dependencies.rst +++ b/Help/command/export_library_dependencies.rst @@ -1,7 +1,7 @@ export_library_dependencies --------------------------- -Disallowed. See CMake Policy :policy:`CMP0033`. +Disallowed since version 3.0. See CMake Policy :policy:`CMP0033`. Use :command:`install(EXPORT)` or :command:`export` command. diff --git a/Help/command/file.rst b/Help/command/file.rst index b2e4eea44..b186177eb 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -3,22 +3,50 @@ file File manipulation command. ------------------------------------------------------------------------------- +Synopsis +^^^^^^^^ -:: +.. parsed-literal:: - file(WRITE <filename> <content>...) - file(APPEND <filename> <content>...) + `Reading`_ + file(`READ`_ <filename> <out-var> [...]) + file(`STRINGS`_ <filename> <out-var> [...]) + file(`\<HASH\> <HASH_>`_ <filename> <out-var>) + file(`TIMESTAMP`_ <filename> <out-var> [...]) + file(`GET_RUNTIME_DEPENDENCIES`_ [...]) -Write ``<content>`` into a file called ``<filename>``. If the file does -not exist, it will be created. If the file already exists, ``WRITE`` -mode will overwrite it and ``APPEND`` mode will append to the end. -(If the file is a build input, use the :command:`configure_file` command -to update the file only when its content changes.) + `Writing`_ + file({`WRITE`_ | `APPEND`_} <filename> <content>...) + file({`TOUCH`_ | `TOUCH_NOCREATE`_} [<file>...]) + file(`GENERATE`_ OUTPUT <output-file> [...]) + + `Filesystem`_ + file({`GLOB`_ | `GLOB_RECURSE`_} <out-var> [...] [<globbing-expr>...]) + file(`RENAME`_ <oldname> <newname>) + file({`REMOVE`_ | `REMOVE_RECURSE`_ } [<files>...]) + file(`MAKE_DIRECTORY`_ [<dir>...]) + file({`COPY`_ | `INSTALL`_} <file>... DESTINATION <dir> [...]) + file(`SIZE`_ <filename> <out-var>) + file(`READ_SYMLINK`_ <linkname> <out-var>) + file(`CREATE_LINK`_ <original> <linkname> [...]) + + `Path Conversion`_ + file(`RELATIVE_PATH`_ <out-var> <directory> <file>) + file({`TO_CMAKE_PATH`_ | `TO_NATIVE_PATH`_} <path> <out-var>) + + `Transfer`_ + file(`DOWNLOAD`_ <url> <file> [...]) + file(`UPLOAD`_ <file> <url> [...]) ------------------------------------------------------------------------------- + `Locking`_ + file(`LOCK`_ <path> [...]) -:: +Reading +^^^^^^^ + +.. _READ: + +.. code-block:: cmake file(READ <filename> <variable> [OFFSET <offset>] [LIMIT <max-in>] [HEX]) @@ -28,9 +56,9 @@ Read content from a file called ``<filename>`` and store it in a read at most ``<max-in>`` bytes. The ``HEX`` option causes data to be converted to a hexadecimal representation (useful for binary data). ------------------------------------------------------------------------------- +.. _STRINGS: -:: +.. code-block:: cmake file(STRINGS <filename> <variable> [<options>...]) @@ -79,9 +107,9 @@ For example, the code stores a list in the variable ``myfile`` in which each item is a line from the input file. ------------------------------------------------------------------------------- +.. _HASH: -:: +.. code-block:: cmake file(<HASH> <filename> <variable>) @@ -90,26 +118,402 @@ store it in a ``<variable>``. The supported ``<HASH>`` algorithm names are those listed by the :ref:`string(\<HASH\>) <Supported Hash Algorithms>` command. ------------------------------------------------------------------------------- +.. _TIMESTAMP: + +.. code-block:: cmake + + file(TIMESTAMP <filename> <variable> [<format>] [UTC]) + +Compute a string representation of the modification time of ``<filename>`` +and store it in ``<variable>``. Should the command be unable to obtain a +timestamp variable will be set to the empty string (""). + +See the :command:`string(TIMESTAMP)` command for documentation of +the ``<format>`` and ``UTC`` options. + +.. _GET_RUNTIME_DEPENDENCIES: + +.. code-block:: cmake + + file(GET_RUNTIME_DEPENDENCIES + [RESOLVED_DEPENDENCIES_VAR <deps_var>] + [UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>] + [CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>] + [EXECUTABLES [<executable_files>...]] + [LIBRARIES [<library_files>...]] + [MODULES [<module_files>...]] + [DIRECTORIES [<directories>...]] + [BUNDLE_EXECUTABLE <bundle_executable_file>] + [PRE_INCLUDE_REGEXES [<regexes>...]] + [PRE_EXCLUDE_REGEXES [<regexes>...]] + [POST_INCLUDE_REGEXES [<regexes>...]] + [POST_EXCLUDE_REGEXES [<regexes>...]] + ) + +Recursively get the list of libraries depended on by the given files. + +Please note that this sub-command is not intended to be used in project mode. +Instead, use it in an :command:`install(CODE)` or :command:`install(SCRIPT)` +block. For example: + +.. code-block:: cmake + + install(CODE [[ + file(GET_RUNTIME_DEPENDENCIES + # ... + ) + ]]) + +The arguments are as follows: + +``RESOLVED_DEPENDENCIES_VAR <deps_var>`` + Name of the variable in which to store the list of resolved dependencies. + +``UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>`` + Name of the variable in which to store the list of unresolved dependencies. + If this variable is not specified, and there are any unresolved dependencies, + an error is issued. + +``CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>`` + Variable prefix in which to store conflicting dependency information. + Dependencies are conflicting if two files with the same name are found in + two different directories. The list of filenames that conflict are stored in + ``<conflicting_deps_prefix>_FILENAMES``. For each filename, the list of paths + that were found for that filename are stored in + ``<conflicting_deps_prefix>_<filename>``. + +``EXECUTABLES <executable_files>`` + List of executable files to read for dependencies. These are executables that + are typically created with :command:`add_executable`, but they do not have to + be created by CMake. On Apple platforms, the paths to these files determine + the value of ``@executable_path`` when recursively resolving the libraries. + Specifying any kind of library (``STATIC``, ``MODULE``, or ``SHARED``) here + will result in undefined behavior. + +``LIBRARIES <library_files>`` + List of library files to read for dependencies. These are libraries that are + typically created with :command:`add_library(SHARED)`, but they do not have + to be created by CMake. Specifying ``STATIC`` libraries, ``MODULE`` + libraries, or executables here will result in undefined behavior. + +``MODULES <module_files>`` + List of loadable module files to read for dependencies. These are modules + that are typically created with :command:`add_library(MODULE)`, but they do + not have to be created by CMake. They are typically used by calling + ``dlopen()`` at runtime rather than linked at link time with ``ld -l``. + Specifying ``STATIC`` libraries, ``SHARED`` libraries, or executables here + will result in undefined behavior. + +``DIRECTORIES <directories>`` + List of additional directories to search for dependencies. On Linux + platforms, these directories are searched if the dependency is not found in + any of the other usual paths. If it is found in such a directory, a warning + is issued, because it means that the file is incomplete (it does not list all + of the directories that contain its dependencies). On Windows platforms, + these directories are searched if the dependency is not found in any of the + other search paths, but no warning is issued, because searching other paths + is a normal part of Windows dependency resolution. On Apple platforms, this + argument has no effect. + +``BUNDLE_EXECUTABLE <bundle_executable_file>`` + Executable to treat as the "bundle executable" when resolving libraries. On + Apple platforms, this argument determines the value of ``@executable_path`` + when recursively resolving libraries for ``LIBRARIES`` and ``MODULES`` files. + It has no effect on ``EXECUTABLES`` files. On other platforms, it has no + effect. This is typically (but not always) one of the executables in the + ``EXECUTABLES`` argument which designates the "main" executable of the + package. + +The following arguments specify filters for including or excluding libraries to +be resolved. See below for a full description of how they work. + +``PRE_INCLUDE_REGEXES <regexes>`` + List of pre-include regexes through which to filter the names of + not-yet-resolved dependencies. + +``PRE_EXCLUDE_REGEXES <regexes>`` + List of pre-exclude regexes through which to filter the names of + not-yet-resolved dependencies. + +``POST_INCLUDE_REGEXES <regexes>`` + List of post-include regexes through which to filter the names of resolved + dependencies. + +``POST_EXCLUDE_REGEXES <regexes>`` + List of post-exclude regexes through which to filter the names of resolved + dependencies. + +These arguments can be used to blacklist unwanted system libraries when +resolving the dependencies, or to whitelist libraries from a specific +directory. The filtering works as follows: + +1. If the not-yet-resolved dependency matches any of the + ``PRE_INCLUDE_REGEXES``, steps 2 and 3 are skipped, and the dependency + resolution proceeds to step 4. +2. If the not-yet-resolved dependency matches any of the + ``PRE_EXCLUDE_REGEXES``, dependency resolution stops for that dependency. +3. Otherwise, dependency resolution proceeds. +4. ``file(GET_RUNTIME_DEPENDENCIES)`` searches for the dependency according to + the linking rules of the platform (see below). +5. If the dependency is found, and its full path matches one of the + ``POST_INCLUDE_REGEXES``, the full path is added to the resolved + dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)`` recursively resolves + that library's own dependencies. Otherwise, resolution proceeds to step 6. +6. If the dependency is found, but its full path matches one of the + ``POST_EXCLUDE_REGEXES``, it is not added to the resolved dependencies, and + dependency resolution stops for that dependency. +7. If the dependency is found, and its full path does not match either + ``POST_INCLUDE_REGEXES`` or ``POST_EXCLUDE_REGEXES``, the full path is added + to the resolved dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)`` + recursively resolves that library's own dependencies. + +Different platforms have different rules for how dependencies are resolved. +These specifics are described here. + +On Linux platforms, library resolution works as follows: + +1. If the depending file does not have any ``RUNPATH`` entries, and the library + exists in one of the depending file's ``RPATH`` entries, or its parents', in + that order, the dependency is resolved to that file. +2. Otherwise, if the depending file has any ``RUNPATH`` entries, and the + library exists in one of those entries, the dependency is resolved to that + file. +3. Otherwise, if the library exists in one of the directories listed by + ``ldconfig``, the dependency is resolved to that file. +4. Otherwise, if the library exists in one of the ``DIRECTORIES`` entries, the + dependency is resolved to that file. In this case, a warning is issued, + because finding a file in one of the ``DIRECTORIES`` means that the + depending file is not complete (it does not list all the directories from + which it pulls dependencies). +5. Otherwise, the dependency is unresolved. + +On Windows platforms, library resolution works as follows: + +1. The dependent DLL name is converted to lowercase. Windows DLL names are + case-insensitive, and some linkers mangle the case of the DLL dependency + names. However, this makes it more difficult for ``PRE_INCLUDE_REGEXES``, + ``PRE_EXCLUDE_REGEXES``, ``POST_INCLUDE_REGEXES``, and + ``POST_EXCLUDE_REGEXES`` to properly filter DLL names - every regex would + have to check for both uppercase and lowercase letters. For example: + + .. code-block:: cmake + + file(GET_RUNTIME_DEPENDENCIES + # ... + PRE_INCLUDE_REGEXES "^[Mm][Yy][Ll][Ii][Bb][Rr][Aa][Rr][Yy]\\.[Dd][Ll][Ll]$" + ) + + Converting the DLL name to lowercase allows the regexes to only match + lowercase names, thus simplifying the regex. For example: + + .. code-block:: cmake + + file(GET_RUNTIME_DEPENDENCIES + # ... + PRE_INCLUDE_REGEXES "^mylibrary\\.dll$" + ) + + This regex will match ``mylibrary.dll`` regardless of how it is cased, + either on disk or in the depending file. (For example, it will match + ``mylibrary.dll``, ``MyLibrary.dll``, and ``MYLIBRARY.DLL``.) + + Please note that the directory portion of any resolved DLLs retains its + casing and is not converted to lowercase. Only the filename portion is + converted. + +2. (**Not yet implemented**) If the depending file is a Windows Store app, and + the dependency is listed as a dependency in the application's package + manifest, the dependency is resolved to that file. +3. Otherwise, if the library exists in the same directory as the depending + file, the dependency is resolved to that file. +4. Otherwise, if the library exists in either the operating system's + ``system32`` directory or the ``Windows`` directory, in that order, the + dependency is resolved to that file. +5. Otherwise, if the library exists in one of the directories specified by + ``DIRECTORIES``, in the order they are listed, the dependency is resolved to + that file. In this case, a warning is not issued, because searching other + directories is a normal part of Windows library resolution. +6. Otherwise, the dependency is unresolved. + +On Apple platforms, library resolution works as follows: + +1. If the dependency starts with ``@executable_path/``, and an ``EXECUTABLES`` + argument is in the process of being resolved, and replacing + ``@executable_path/`` with the directory of the executable yields an + existing file, the dependency is resolved to that file. +2. Otherwise, if the dependency starts with ``@executable_path/``, and there is + a ``BUNDLE_EXECUTABLE`` argument, and replacing ``@executable_path/`` with + the directory of the bundle executable yields an existing file, the + dependency is resolved to that file. +3. Otherwise, if the dependency starts with ``@loader_path/``, and replacing + ``@loader_path/`` with the directory of the depending file yields an + existing file, the dependency is resolved to that file. +4. Otherwise, if the dependency starts with ``@rpath/``, and replacing + ``@rpath/`` with one of the ``RPATH`` entries of the depending file yields + an existing file, the dependency is resolved to that file. Note that + ``RPATH`` entries that start with ``@executable_path/`` or ``@loader_path/`` + also have these items replaced with the appropriate path. +5. Otherwise, if the dependency is an absolute file that exists, the dependency + is resolved to that file. +6. Otherwise, the dependency is unresolved. + +This function accepts several variables that determine which tool is used for +dependency resolution: + +.. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM + + Determines which operating system and executable format the files are built + for. This could be one of several values: + + * ``linux+elf`` + * ``windows+pe`` + * ``macos+macho`` + + If this variable is not specified, it is determined automatically by system + introspection. + +.. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL + + Determines the tool to use for dependency resolution. It could be one of + several values, depending on the value of + :variable:`CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM`: + + ================================================= ============================================= + ``CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM`` ``CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL`` + ================================================= ============================================= + ``linux+elf`` ``objdump`` + ``windows+pe`` ``dumpbin`` + ``windows+pe`` ``objdump`` + ``macos+macho`` ``otool`` + ================================================= ============================================= + + If this variable is not specified, it is determined automatically by system + introspection. + +.. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_COMMAND + + Determines the path to the tool to use for dependency resolution. This is the + actual path to ``objdump``, ``dumpbin``, or ``otool``. + + If this variable is not specified, it is determined automatically by system + introspection. + +Writing +^^^^^^^ + +.. _WRITE: +.. _APPEND: + +.. code-block:: cmake + + file(WRITE <filename> <content>...) + file(APPEND <filename> <content>...) + +Write ``<content>`` into a file called ``<filename>``. If the file does +not exist, it will be created. If the file already exists, ``WRITE`` +mode will overwrite it and ``APPEND`` mode will append to the end. +Any directories in the path specified by ``<filename>`` that do not +exist will be created. + +If the file is a build input, use the :command:`configure_file` command +to update the file only when its content changes. + +.. _TOUCH: +.. _TOUCH_NOCREATE: + +.. code-block:: cmake + + file(TOUCH [<files>...]) + file(TOUCH_NOCREATE [<files>...]) -:: +Create a file with no content if it does not yet exist. If the file already +exists, its access and/or modification will be updated to the time when the +function call is executed. + +Use TOUCH_NOCREATE to touch a file if it exists but not create it. If a file +does not exist it will be silently ignored. + +With TOUCH and TOUCH_NOCREATE the contents of an existing file will not be +modified. + +.. _GENERATE: + +.. code-block:: cmake + + file(GENERATE OUTPUT output-file + <INPUT input-file|CONTENT content> + [CONDITION expression]) + +Generate an output file for each build configuration supported by the current +:manual:`CMake Generator <cmake-generators(7)>`. Evaluate +:manual:`generator expressions <cmake-generator-expressions(7)>` +from the input content to produce the output content. The options are: + +``CONDITION <condition>`` + Generate the output file for a particular configuration only if + the condition is true. The condition must be either ``0`` or ``1`` + after evaluating generator expressions. + +``CONTENT <content>`` + Use the content given explicitly as input. + +``INPUT <input-file>`` + Use the content from a given file as input. + A relative path is treated with respect to the value of + :variable:`CMAKE_CURRENT_SOURCE_DIR`. See policy :policy:`CMP0070`. + +``OUTPUT <output-file>`` + Specify the output file name to generate. Use generator expressions + such as ``$<CONFIG>`` to specify a configuration-specific output file + name. Multiple configurations may generate the same output file only + if the generated content is identical. Otherwise, the ``<output-file>`` + must evaluate to an unique name for each configuration. + A relative path (after evaluating generator expressions) is treated + with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. + See policy :policy:`CMP0070`. + +Exactly one ``CONTENT`` or ``INPUT`` option must be given. A specific +``OUTPUT`` file may be named by at most one invocation of ``file(GENERATE)``. +Generated files are modified and their timestamp updated on subsequent cmake +runs only if their content is changed. + +Note also that ``file(GENERATE)`` does not create the output file until the +generation phase. The output file will not yet have been written when the +``file(GENERATE)`` command returns, it is written only after processing all +of a project's ``CMakeLists.txt`` files. + +Filesystem +^^^^^^^^^^ + +.. _GLOB: +.. _GLOB_RECURSE: + +.. code-block:: cmake file(GLOB <variable> - [LIST_DIRECTORIES true|false] [RELATIVE <path>] + [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS] [<globbing-expressions>...]) file(GLOB_RECURSE <variable> [FOLLOW_SYMLINKS] - [LIST_DIRECTORIES true|false] [RELATIVE <path>] + [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS] [<globbing-expressions>...]) Generate a list of files that match the ``<globbing-expressions>`` and store it into the ``<variable>``. Globbing expressions are similar to regular expressions, but much simpler. If ``RELATIVE`` flag is specified, the results will be returned as relative paths to the given -path. No specific order of results is defined other than that it is -deterministic. If order is important then sort the list explicitly -(e.g. using the :command:`list(SORT)` command). +path. The results will be ordered lexicographically. + +On Windows and macOS, globbing is case-insensitive even if the underlying +filesystem is case-sensitive (both filenames and globbing expressions are +converted to lowercase before matching). On other platforms, globbing is +case-sensitive. -By default ``GLOB`` lists directories - directories are omited in result if +If the ``CONFIGURE_DEPENDS`` flag is specified, CMake will add logic +to the main build system check target to rerun the flagged ``GLOB`` commands +at build time. If any of the outputs change, CMake will regenerate the build +system. + +By default ``GLOB`` lists directories - directories are omitted in result if ``LIST_DIRECTORIES`` is set to false. .. note:: @@ -117,6 +521,10 @@ By default ``GLOB`` lists directories - directories are omited in result if your source tree. If no CMakeLists.txt file changes when a source is added or removed then the generated build system cannot know when to ask CMake to regenerate. + The ``CONFIGURE_DEPENDS`` flag may not work reliably on all generators, or if + a new generator is added in the future that cannot support it, projects using + it will be stuck. Even if ``CONFIGURE_DEPENDS`` works reliably, there is + still a cost to perform the check on every rebuild. Examples of globbing expressions include:: @@ -138,46 +546,168 @@ Examples of recursive globbing include:: /dir/*.py - match all python files in /dir and subdirectories ------------------------------------------------------------------------------- +.. _RENAME: -:: +.. code-block:: cmake file(RENAME <oldname> <newname>) Move a file or directory within a filesystem from ``<oldname>`` to ``<newname>``, replacing the destination atomically. ------------------------------------------------------------------------------- +.. _REMOVE: +.. _REMOVE_RECURSE: -:: +.. code-block:: cmake file(REMOVE [<files>...]) file(REMOVE_RECURSE [<files>...]) Remove the given files. The ``REMOVE_RECURSE`` mode will remove the given files and directories, also non-empty directories. No error is emitted if a -given file does not exist. +given file does not exist. Relative input paths are evaluated with respect +to the current source directory. Empty input paths are ignored with a warning. ------------------------------------------------------------------------------- +.. _MAKE_DIRECTORY: -:: +.. code-block:: cmake file(MAKE_DIRECTORY [<directories>...]) Create the given directories and their parents as needed. ------------------------------------------------------------------------------- +.. _COPY: +.. _INSTALL: -:: +.. code-block:: cmake + + file(<COPY|INSTALL> <files>... DESTINATION <dir> + [FILE_PERMISSIONS <permissions>...] + [DIRECTORY_PERMISSIONS <permissions>...] + [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS] + [FOLLOW_SYMLINK_CHAIN] + [FILES_MATCHING] + [[PATTERN <pattern> | REGEX <regex>] + [EXCLUDE] [PERMISSIONS <permissions>...]] [...]) + +The ``COPY`` signature copies files, directories, and symlinks to a +destination folder. Relative input paths are evaluated with respect +to the current source directory, and a relative destination is +evaluated with respect to the current build directory. Copying +preserves input file timestamps, and optimizes out a file if it exists +at the destination with the same timestamp. Copying preserves input +permissions unless explicit permissions or ``NO_SOURCE_PERMISSIONS`` +are given (default is ``USE_SOURCE_PERMISSIONS``). + +If ``FOLLOW_SYMLINK_CHAIN`` is specified, ``COPY`` will recursively resolve +the symlinks at the paths given until a real file is found, and install +a corresponding symlink in the destination for each symlink encountered. For +each symlink that is installed, the resolution is stripped of the directory, +leaving only the filename, meaning that the new symlink points to a file in +the same directory as the symlink. This feature is useful on some Unix systems, +where libraries are installed as a chain of symlinks with version numbers, with +less specific versions pointing to more specific versions. +``FOLLOW_SYMLINK_CHAIN`` will install all of these symlinks and the library +itself into the destination directory. For example, if you have the following +directory structure: + +* ``/opt/foo/lib/libfoo.so.1.2.3`` +* ``/opt/foo/lib/libfoo.so.1.2 -> libfoo.so.1.2.3`` +* ``/opt/foo/lib/libfoo.so.1 -> libfoo.so.1.2`` +* ``/opt/foo/lib/libfoo.so -> libfoo.so.1`` + +and you do: + +.. code-block:: cmake + + file(COPY /opt/foo/lib/libfoo.so DESTINATION lib FOLLOW_SYMLINK_CHAIN) + +This will install all of the symlinks and ``libfoo.so.1.2.3`` itself into +``lib``. + +See the :command:`install(DIRECTORY)` command for documentation of +permissions, ``FILES_MATCHING``, ``PATTERN``, ``REGEX``, and +``EXCLUDE`` options. Copying directories preserves the structure +of their content even if options are used to select a subset of +files. + +The ``INSTALL`` signature differs slightly from ``COPY``: it prints +status messages (subject to the :variable:`CMAKE_INSTALL_MESSAGE` variable), +and ``NO_SOURCE_PERMISSIONS`` is default. +Installation scripts generated by the :command:`install` command +use this signature (with some undocumented options for internal use). + +.. _SIZE: + +.. code-block:: cmake + + file(SIZE <filename> <variable>) + +Determine the file size of the ``<filename>`` and put the result in +``<variable>`` variable. Requires that ``<filename>`` is a valid path +pointing to a file and is readable. + +.. _READ_SYMLINK: + +.. code-block:: cmake + + file(READ_SYMLINK <linkname> <variable>) + +This subcommand queries the symlink ``<linkname>`` and stores the path it +points to in the result ``<variable>``. If ``<linkname>`` does not exist or +is not a symlink, CMake issues a fatal error. + +Note that this command returns the raw symlink path and does not resolve +a relative path. The following is an example of how to ensure that an +absolute path is obtained: + +.. code-block:: cmake + + set(linkname "/path/to/foo.sym") + file(READ_SYMLINK "${linkname}" result) + if(NOT IS_ABSOLUTE "${result}") + get_filename_component(dir "${linkname}" DIRECTORY) + set(result "${dir}/${result}") + endif() + +.. _CREATE_LINK: + +.. code-block:: cmake + + file(CREATE_LINK <original> <linkname> + [RESULT <result>] [COPY_ON_ERROR] [SYMBOLIC]) + +Create a link ``<linkname>`` that points to ``<original>``. +It will be a hard link by default, but providing the ``SYMBOLIC`` option +results in a symbolic link instead. Hard links require that ``original`` +exists and is a file, not a directory. If ``<linkname>`` already exists, +it will be overwritten. + +The ``<result>`` variable, if specified, receives the status of the operation. +It is set to ``0`` upon success or an error message otherwise. If ``RESULT`` +is not specified and the operation fails, a fatal error is emitted. + +Specifying ``COPY_ON_ERROR`` enables copying the file as a fallback if +creating the link fails. It can be useful for handling situations such as +``<original>`` and ``<linkname>`` being on different drives or mount points, +which would make them unable to support a hard link. + +Path Conversion +^^^^^^^^^^^^^^^ + +.. _RELATIVE_PATH: + +.. code-block:: cmake file(RELATIVE_PATH <variable> <directory> <file>) Compute the relative path from a ``<directory>`` to a ``<file>`` and store it in the ``<variable>``. ------------------------------------------------------------------------------- +.. _TO_CMAKE_PATH: +.. _TO_NATIVE_PATH: -:: +.. code-block:: cmake file(TO_CMAKE_PATH "<path>" <variable>) file(TO_NATIVE_PATH "<path>" <variable>) @@ -193,9 +723,13 @@ path with platform-specific slashes (``\`` on Windows and ``/`` elsewhere). Always use double quotes around the ``<path>`` to be sure it is treated as a single argument to this command. ------------------------------------------------------------------------------- +Transfer +^^^^^^^^ -:: +.. _DOWNLOAD: +.. _UPLOAD: + +.. code-block:: cmake file(DOWNLOAD <url> <file> [<options>...]) file(UPLOAD <file> <url> [<options>...]) @@ -231,6 +765,31 @@ Options to both ``DOWNLOAD`` and ``UPLOAD`` are: ``HTTPHEADER <HTTP-header>`` HTTP header for operation. Suboption can be repeated several times. +``NETRC <level>`` + Specify whether the .netrc file is to be used for operation. If this + option is not specified, the value of the ``CMAKE_NETRC`` variable + will be used instead. + Valid levels are: + + ``IGNORED`` + The .netrc file is ignored. + This is the default. + ``OPTIONAL`` + The .netrc file is optional, and information in the URL is preferred. + The file will be scanned to find which ever information is not specified + in the URL. + ``REQUIRED`` + The .netrc file is required, and information in the URL is ignored. + +``NETRC_FILE <file>`` + Specify an alternative .netrc file to the one in your home directory, + if the ``NETRC`` level is ``OPTIONAL`` or ``REQUIRED``. If this option + is not specified, the value of the ``CMAKE_NETRC_FILE`` variable will + be used instead. + +If neither ``NETRC`` option is given CMake will check variables +``CMAKE_NETRC`` and ``CMAKE_NETRC_FILE``, respectively. + Additional options to ``DOWNLOAD`` are: ``EXPECTED_HASH ALGO=<value>`` @@ -255,96 +814,12 @@ check certificates and/or use ``EXPECTED_HASH`` to verify downloaded content. If neither ``TLS`` option is given CMake will check variables ``CMAKE_TLS_VERIFY`` and ``CMAKE_TLS_CAINFO``, respectively. ------------------------------------------------------------------------------- - -:: - - file(TIMESTAMP <filename> <variable> [<format>] [UTC]) - -Compute a string representation of the modification time of ``<filename>`` -and store it in ``<variable>``. Should the command be unable to obtain a -timestamp variable will be set to the empty string (""). - -See the :command:`string(TIMESTAMP)` command for documentation of -the ``<format>`` and ``UTC`` options. - ------------------------------------------------------------------------------- - -:: - - file(GENERATE OUTPUT output-file - <INPUT input-file|CONTENT content> - [CONDITION expression]) - -Generate an output file for each build configuration supported by the current -:manual:`CMake Generator <cmake-generators(7)>`. Evaluate -:manual:`generator expressions <cmake-generator-expressions(7)>` -from the input content to produce the output content. The options are: - -``CONDITION <condition>`` - Generate the output file for a particular configuration only if - the condition is true. The condition must be either ``0`` or ``1`` - after evaluating generator expressions. - -``CONTENT <content>`` - Use the content given explicitly as input. - -``INPUT <input-file>`` - Use the content from a given file as input. - -``OUTPUT <output-file>`` - Specify the output file name to generate. Use generator expressions - such as ``$<CONFIG>`` to specify a configuration-specific output file - name. Multiple configurations may generate the same output file only - if the generated content is identical. Otherwise, the ``<output-file>`` - must evaluate to an unique name for each configuration. - -Exactly one ``CONTENT`` or ``INPUT`` option must be given. A specific -``OUTPUT`` file may be named by at most one invocation of ``file(GENERATE)``. -Generated files are modified on subsequent cmake runs only if their content -is changed. +Locking +^^^^^^^ -Note also that ``file(GENERATE)`` does not create the output file until the -generation phase. The output file will not yet have been written when the -``file(GENERATE)`` command returns, it is written only after processing all -of a project's ``CMakeLists.txt`` files. - ------------------------------------------------------------------------------- +.. _LOCK: -:: - - file(<COPY|INSTALL> <files>... DESTINATION <dir> - [FILE_PERMISSIONS <permissions>...] - [DIRECTORY_PERMISSIONS <permissions>...] - [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS] - [FILES_MATCHING] - [[PATTERN <pattern> | REGEX <regex>] - [EXCLUDE] [PERMISSIONS <permissions>...]] [...]) - -The ``COPY`` signature copies files, directories, and symlinks to a -destination folder. Relative input paths are evaluated with respect -to the current source directory, and a relative destination is -evaluated with respect to the current build directory. Copying -preserves input file timestamps, and optimizes out a file if it exists -at the destination with the same timestamp. Copying preserves input -permissions unless explicit permissions or ``NO_SOURCE_PERMISSIONS`` -are given (default is ``USE_SOURCE_PERMISSIONS``). - -See the :command:`install(DIRECTORY)` command for documentation of -permissions, ``FILES_MATCHING``, ``PATTERN``, ``REGEX``, and -``EXCLUDE`` options. Copying directories preserves the structure -of their content even if options are used to select a subset of -files. - -The ``INSTALL`` signature differs slightly from ``COPY``: it prints -status messages (subject to the :variable:`CMAKE_INSTALL_MESSAGE` variable), -and ``NO_SOURCE_PERMISSIONS`` is default. -Installation scripts generated by the :command:`install` command -use this signature (with some undocumented options for internal use). - ------------------------------------------------------------------------------- - -:: +.. code-block:: cmake file(LOCK <path> [DIRECTORY] [RELEASE] [GUARD <FUNCTION|FILE|PROCESS>] diff --git a/Help/command/find_file.rst b/Help/command/find_file.rst index e56097bea..3f03f37e3 100644 --- a/Help/command/find_file.rst +++ b/Help/command/find_file.rst @@ -8,17 +8,19 @@ find_file .. |prefix_XXX_SUBDIR| replace:: ``<prefix>/include`` .. |entry_XXX_SUBDIR| replace:: ``<entry>/include`` +.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace:: + ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` + is set, and |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR| .. |CMAKE_PREFIX_PATH_XXX| replace:: ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set, and |CMAKE_PREFIX_PATH_XXX_SUBDIR| .. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_INCLUDE_PATH` .. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_FRAMEWORK_PATH` -.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in ``INCLUDE``. - On Windows hosts: - ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` - is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|, and the - directories in ``PATH`` itself. +.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``PATH`` and ``INCLUDE``. +.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: On Windows hosts: + ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` + is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|. .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace:: ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` diff --git a/Help/command/find_library.rst b/Help/command/find_library.rst index f774f17ec..8a55aca3d 100644 --- a/Help/command/find_library.rst +++ b/Help/command/find_library.rst @@ -8,17 +8,19 @@ find_library .. |prefix_XXX_SUBDIR| replace:: ``<prefix>/lib`` .. |entry_XXX_SUBDIR| replace:: ``<entry>/lib`` +.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace:: + ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set, + and |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR| .. |CMAKE_PREFIX_PATH_XXX| replace:: ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set, and |CMAKE_PREFIX_PATH_XXX_SUBDIR| .. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_LIBRARY_PATH` .. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_FRAMEWORK_PATH` -.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in ``LIB``. - On Windows hosts: - ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set, - and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|, - and the directories in ``PATH`` itself. +.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``PATH`` and ``INCLUDE``. +.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: On Windows hosts: + ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` + is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|. .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace:: ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set, diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index 83f471619..64a16f321 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -1,23 +1,31 @@ find_package ------------ -Load settings for an external project. +.. only:: html -:: + .. contents:: - find_package(<package> [version] [EXACT] [QUIET] [MODULE] +Find an external project, and load its settings. + +.. _`basic signature`: + +Basic Signature and Module Mode +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: cmake + + 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. +``QUIET`` option disables informational messages, including those indicating +that the package cannot be found if it is not ``REQUIRED``. The ``REQUIRED`` +option stops processing with an error message if the package cannot be found. A package-specific list of required components may be listed after the ``COMPONENTS`` option (or after the ``REQUIRED`` option if present). @@ -33,29 +41,47 @@ 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). + +See the :command:`cmake_policy` command documentation for discussion +of the ``NO_POLICY_SCOPE`` option. -User code should generally look for packages using the above simple -signature. The remainder of this command documentation specifies the +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``. +The file is first searched in the :variable:`CMAKE_MODULE_PATH`, +then among the :ref:`Find Modules` provided 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. + +If the ``MODULE`` option is not specfied in the above signature, +CMake first searches for the package using Module mode. Then, if the +package is not found, it searches again using Config mode. A user +may set the variable :variable:`CMAKE_FIND_PACKAGE_PREFER_CONFIG` to +``TRUE`` to direct CMake first search using Config mode before falling +back to Module mode. + +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] +The complete Config mode command signature is + +.. code-block:: cmake + + find_package(<PackageName> [version] [EXACT] [QUIET] [REQUIRED] [[COMPONENTS] [components...]] + [OPTIONAL_COMPONENTS components...] [CONFIG|NO_MODULE] [NO_POLICY_SCOPE] [NAMES name1 [name2 ...]] @@ -64,6 +90,7 @@ The complete Config mode command signature is:: [PATHS path1 [path2 ... ]] [PATH_SUFFIXES suffix1 [suffix2 ...]] [NO_DEFAULT_PATH] + [NO_PACKAGE_ROOT_PATH] [NO_CMAKE_PATH] [NO_CMAKE_ENVIRONMENT_PATH] [NO_SYSTEM_ENVIRONMENT_PATH] @@ -75,37 +102,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`` @@ -126,7 +160,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`` @@ -154,20 +188,20 @@ sets these variables: These variables are checked by the ``find_package`` command to determine whether the configuration file provides an acceptable version. They -are not available after the find_package call returns. If the version +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. @@ -176,47 +210,40 @@ claim compatibility with the version requested it is unspecified which one is chosen: unless the variable :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` is set no attempt is made to choose a highest or closest version number. -To control the order in which ``find_package`` checks for compatibiliy use +To control the order in which ``find_package`` checks for compatibility use the two variables :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` and :variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION`. -For instance in order to select the highest version one can set:: +For instance in order to select the highest version one can set + +.. code-block:: cmake SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL) SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC) 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 configuration file. The tables below show the directories searched. -Each entry is meant for installation trees following Windows (W), UNIX -(U), or Apple (A) conventions:: +Each entry is meant for installation trees following Windows (``W``), UNIX +(``U``), or Apple (``A``) conventions:: <prefix>/ (W) <prefix>/(cmake|CMake)/ (W) <prefix>/<name>*/ (W) <prefix>/<name>*/(cmake|CMake)/ (W) - <prefix>/(lib/<arch>|lib|share)/cmake/<name>*/ (U) - <prefix>/(lib/<arch>|lib|share)/<name>*/ (U) - <prefix>/(lib/<arch>|lib|share)/<name>*/(cmake|CMake)/ (U) - <prefix>/<name>*/(lib/<arch>|lib|share)/cmake/<name>*/ (W/U) - <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 -following directories are searched for frameworks or bundles + <prefix>/(lib/<arch>|lib*|share)/cmake/<name>*/ (U) + <prefix>/(lib/<arch>|lib*|share)/<name>*/ (U) + <prefix>/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/ (U) + <prefix>/<name>*/(lib/<arch>|lib*|share)/cmake/<name>*/ (W/U) + <prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/ (W/U) + <prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/ (W/U) + +On systems supporting macOS :prop_tgt:`FRAMEWORK` and :prop_tgt:`BUNDLE`, the +following directories are searched for Frameworks or Application Bundles containing a configuration file:: <prefix>/<name>.framework/Resources/ (A) @@ -227,20 +254,32 @@ 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. If ``PATH_SUFFIXES`` -is specified the suffixes are appended to each (W) or (U) directory entry -one-by-one. +:variable:`CMAKE_LIBRARY_ARCHITECTURE` variable is set. ``lib*`` includes one +or more of the values ``lib64``, ``lib32``, ``libx32`` or ``lib`` (searched in +that order). + +* Paths with ``lib64`` are searched on 64 bit platforms if the + :prop_gbl:`FIND_LIBRARY_USE_LIB64_PATHS` property is set to ``TRUE``. +* Paths with ``lib32`` are searched on 32 bit platforms if the + :prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS` property is set to ``TRUE``. +* Paths with ``libx32`` are searched on platforms using the x32 ABI + if the :prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS` property is set to ``TRUE``. +* The ``lib`` path is always searched. + +If ``PATH_SUFFIXES`` is specified, the suffixes are appended to each +(``W``) or (``U``) directory entry one-by-one. This set of directories is intended to work in cooperation with projects that provide configuration files in their installation trees. -Directories above marked with (W) are intended for installations on +Directories above marked with (``W``) are intended for installations on Windows where the prefix may point at the top of an application's -installation directory. Those marked with (U) are intended for +installation directory. Those marked with (``U``) are intended for installations on UNIX platforms where the prefix is shared by multiple -packages. This is merely a convention, so all (W) and (U) directories -are still searched on all platforms. Directories marked with (A) are +packages. This is merely a convention, so all (``W``) and (``U``) directories +are still searched on all platforms. Directories marked with (``A``) are intended for installations on Apple platforms. The :variable:`CMAKE_FIND_FRAMEWORK` and :variable:`CMAKE_FIND_APPBUNDLE` variables determine the order of preference. @@ -249,101 +288,127 @@ The set of installation prefixes is constructed using the following steps. If ``NO_DEFAULT_PATH`` is specified all ``NO_*`` options are enabled. -1. Search paths specified in cmake-specific cache variables. These +1. Search paths specified in the :variable:`<PackageName>_ROOT` CMake + variable and the :envvar:`<PackageName>_ROOT` environment variable, + where ``<PackageName>`` is the package to be found. + The package root variables are maintained as a stack so if + called from within a find module, root paths from the parent's find + module will also be searched after paths for the current package. + This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed or by setting + the :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` to ``FALSE``. + See policy :policy:`CMP0074`. + +2. Search paths specified in cmake-specific cache variables. These are intended to be used on the command line with a ``-DVAR=value``. - The values are interpreted as :ref:`;-lists <CMake Language Lists>`. - This can be skipped if ``NO_CMAKE_PATH`` is passed:: + The values are interpreted as :ref:`semicolon-separated lists <CMake Language Lists>`. + This can be skipped if ``NO_CMAKE_PATH`` is passed or by setting the + :variable:`CMAKE_FIND_USE_CMAKE_PATH` to ``FALSE``:: CMAKE_PREFIX_PATH CMAKE_FRAMEWORK_PATH CMAKE_APPBUNDLE_PATH -2. Search paths specified in cmake-specific environment variables. +3. Search paths specified in cmake-specific environment variables. These are intended to be set in the user's shell configuration, and therefore use the host's native path separator (``;`` on Windows and ``:`` on UNIX). - This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed:: + This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed or by setting + the :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` to ``FALSE``:: - <package>_DIR + <PackageName>_DIR CMAKE_PREFIX_PATH CMAKE_FRAMEWORK_PATH CMAKE_APPBUNDLE_PATH -3. Search paths specified by the ``HINTS`` option. These should be paths +4. Search paths specified by the ``HINTS`` option. These should be paths computed by system introspection, such as a hint provided by the location of another item already found. Hard-coded guesses should be specified with the ``PATHS`` option. -4. Search the standard system environment variables. This can be - skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is passed. Path entries +5. Search the standard system environment variables. This can be + skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is passed or by setting the + :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH` to ``FALSE``. Path entries ending in ``/bin`` or ``/sbin`` are automatically converted to their parent directories:: PATH -5. Search paths stored in the CMake :ref:`User Package Registry`. +6. Search paths stored in the CMake :ref:`User Package Registry`. This can be skipped if ``NO_CMAKE_PACKAGE_REGISTRY`` is passed or by - setting the :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` - to ``TRUE``. + setting the variable :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` + to ``FALSE`` or the deprecated variable + :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` to ``TRUE``. + See the :manual:`cmake-packages(7)` manual for details on the user package registry. -6. Search cmake variables defined in the Platform files for the +7. Search cmake variables defined in the Platform files for the current system. This can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is - passed:: + passed or by setting the :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH` + to ``FALSE``:: CMAKE_SYSTEM_PREFIX_PATH CMAKE_SYSTEM_FRAMEWORK_PATH CMAKE_SYSTEM_APPBUNDLE_PATH -7. Search paths stored in the CMake :ref:`System Package Registry`. +8. Search paths stored in the CMake :ref:`System Package Registry`. This can be skipped if ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` is passed - or by setting the + or by setting the :variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY` + variable to ``FALSE`` or the deprecated variable :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` to ``TRUE``. + See the :manual:`cmake-packages(7)` manual for details on the system package registry. -8. Search paths specified by the ``PATHS`` option. These are typically +9. Search paths specified by the ``PATHS`` option. These are typically 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` .. include:: FIND_XXX_ROOT.txt .. include:: FIND_XXX_ORDER.txt +By default the value stored in the result variable will be the path at +which the file is found. The :variable:`CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS` +variable may be set to ``TRUE`` before calling ``find_package`` in order +to resolve symbolic links and store the real path to the file. + 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 @@ -353,8 +418,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. diff --git a/Help/command/find_path.rst b/Help/command/find_path.rst index 76342d020..52ffe3c79 100644 --- a/Help/command/find_path.rst +++ b/Help/command/find_path.rst @@ -8,17 +8,19 @@ find_path .. |prefix_XXX_SUBDIR| replace:: ``<prefix>/include`` .. |entry_XXX_SUBDIR| replace:: ``<entry>/include`` +.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace:: + ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` + is set, and |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR| .. |CMAKE_PREFIX_PATH_XXX| replace:: ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set, and |CMAKE_PREFIX_PATH_XXX_SUBDIR| .. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_INCLUDE_PATH` .. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_FRAMEWORK_PATH` -.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in ``INCLUDE``. - On Windows hosts: - ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` - is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|, and the - directories in ``PATH`` itself. +.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``PATH`` and ``INCLUDE``. +.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: On Windows hosts: + ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` + is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|. .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace:: ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` diff --git a/Help/command/find_program.rst b/Help/command/find_program.rst index d3430c054..e2ff69342 100644 --- a/Help/command/find_program.rst +++ b/Help/command/find_program.rst @@ -8,12 +8,15 @@ find_program .. |prefix_XXX_SUBDIR| replace:: ``<prefix>/[s]bin`` .. |entry_XXX_SUBDIR| replace:: ``<entry>/[s]bin`` +.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace:: + |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR| .. |CMAKE_PREFIX_PATH_XXX| replace:: |CMAKE_PREFIX_PATH_XXX_SUBDIR| .. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_PROGRAM_PATH` .. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_APPBUNDLE_PATH` -.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: ``PATH`` +.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``PATH`` itself. +.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: On Windows hosts no extra search paths are included .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace:: |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| diff --git a/Help/command/fltk_wrap_ui.rst b/Help/command/fltk_wrap_ui.rst index 041e5a7e3..66752729d 100644 --- a/Help/command/fltk_wrap_ui.rst +++ b/Help/command/fltk_wrap_ui.rst @@ -3,7 +3,7 @@ fltk_wrap_ui Create FLTK user interfaces Wrappers. -:: +.. code-block:: cmake fltk_wrap_ui(resultingLibraryName source1 source2 ... sourceN ) diff --git a/Help/command/foreach.rst b/Help/command/foreach.rst index c0f3679d9..ae2afb290 100644 --- a/Help/command/foreach.rst +++ b/Help/command/foreach.rst @@ -3,45 +3,82 @@ foreach Evaluate a group of commands for each value in a list. -:: +.. code-block:: cmake - foreach(loop_var arg1 arg2 ...) - COMMAND1(ARGS ...) - COMMAND2(ARGS ...) - ... - endforeach(loop_var) + foreach(<loop_var> <items>) + <commands> + endforeach() -All commands between foreach and the matching endforeach are recorded -without being invoked. Once the endforeach is evaluated, the recorded -list of commands is invoked once for each argument listed in the -original foreach command. Before each iteration of the loop -``${loop_var}`` will be set as a variable with the current value in the -list. +where ``<items>`` is a list of items that are separated by +semicolon or whitespace. +All commands between ``foreach`` and the matching ``endforeach`` are recorded +without being invoked. Once the ``endforeach`` is evaluated, the recorded +list of commands is invoked once for each item in ``<items>``. +At the beginning of each iteration the variable ``loop_var`` will be set +to the value of the current item. -:: +The commands :command:`break` and :command:`continue` provide means to +escape from the normal control flow. - foreach(loop_var RANGE total) - foreach(loop_var RANGE start stop [step]) +Per legacy, the :command:`endforeach` command admits +an optional ``<loop_var>`` argument. +If used, it must be a verbatim +repeat of the argument of the opening +``foreach`` command. -Foreach can also iterate over a generated range of numbers. There are -three types of this iteration: +.. code-block:: cmake -* When specifying single number, the range will have elements 0 to - "total". + foreach(<loop_var> RANGE <stop>) -* When specifying two numbers, the range will have elements from the - first number to the second number. +In this variant, ``foreach`` iterates over the numbers +0, 1, ... up to (and including) the nonnegative integer ``<stop>``. -* The third optional number is the increment used to iterate from the - first number to the second number. +.. code-block:: cmake -:: + foreach(<loop_var> RANGE <start> <stop> [<step>]) + +In this variant, ``foreach`` iterates over the numbers from +``<start>`` up to at most ``<stop>`` in steps of ``<step>``. +If ``<step>`` is not specified, then the step size is 1. +The three arguments ``<start>`` ``<stop>`` ``<step>`` must +all be nonnegative integers, and ``<stop>`` must not be +smaller than ``<start>``; otherwise you enter the danger zone +of undocumented behavior that may change in future releases. + +.. code-block:: cmake + + foreach(loop_var IN [LISTS [<lists>]] [ITEMS [<items>]]) - foreach(loop_var IN [LISTS [list1 [...]]] - [ITEMS [item1 [...]]]) +In this variant, ``<lists>`` is a whitespace or semicolon +separated list of list-valued variables. The ``foreach`` +command iterates over each item in each given list. +The ``<items>`` following the ``ITEMS`` keyword are processed +as in the first variant of the ``foreach`` command. +The forms ``LISTS A`` and ``ITEMS ${A}`` are +equivalent. + +The following example shows how the ``LISTS`` option is +processed: + +.. code-block:: cmake + + set(A 0;1) + set(B 2 3) + set(C "4 5") + set(D 6;7 8) + set(E "") + foreach(X IN LISTS A B C D E) + message(STATUS "X=${X}") + endforeach() + +yields +:: -Iterates over a precise list of items. The ``LISTS`` option names -list-valued variables to be traversed, including empty elements (an -empty string is a zero-length list). (Note macro -arguments are not variables.) The ``ITEMS`` option ends argument -parsing and includes all arguments following it in the iteration. + -- X=0 + -- X=1 + -- X=2 + -- X=3 + -- X=4 5 + -- X=6 + -- X=7 + -- X=8 diff --git a/Help/command/function.rst b/Help/command/function.rst index 7ffdfee65..53ba75481 100644 --- a/Help/command/function.rst +++ b/Help/command/function.rst @@ -1,36 +1,70 @@ function -------- -Start recording a function for later invocation as a command:: - - function(<name> [arg1 [arg2 [arg3 ...]]]) - COMMAND1(ARGS ...) - COMMAND2(ARGS ...) - ... - endfunction(<name>) - -Define a function named ``<name>`` that takes arguments named ``arg1``, -``arg2``, ``arg3``, (...). -Commands listed after function, but before the matching -:command:`endfunction()`, are not invoked until the function is invoked. -When it is invoked, the commands recorded in the function are first -modified by replacing formal parameters (``${arg1}``) with the arguments -passed, and then invoked as normal commands. -In addition to referencing the formal parameters you can reference the -``ARGC`` variable which will be set to the number of arguments passed -into the function as well as ``ARGV0``, ``ARGV1``, ``ARGV2``, ... which -will have the actual values of the arguments passed in. -This facilitates creating functions with optional arguments. -Additionally ``ARGV`` holds the list of all arguments given to the -function and ``ARGN`` holds the list of arguments past the last expected -argument. -Referencing to ``ARGV#`` arguments beyond ``ARGC`` have undefined -behavior. Checking that ``ARGC`` is greater than ``#`` is the only way -to ensure that ``ARGV#`` was passed to the function as an extra -argument. +Start recording a function for later invocation as a command. + +.. code-block:: cmake + + function(<name> [<arg1> ...]) + <commands> + endfunction() + +Defines a function named ``<name>`` that takes arguments named +``<arg1>``, ... The ``<commands>`` in the function definition +are recorded; they are not executed until the function is invoked. + +Per legacy, the :command:`endfunction` command admits an optional +``<name>`` argument. If used, it must be a verbatim repeat of the +argument of the opening ``function`` command. A function opens a new scope: see :command:`set(var PARENT_SCOPE)` for details. See the :command:`cmake_policy()` command documentation for the behavior of policies inside functions. + +See the :command:`macro()` command documentation for differences +between CMake functions and macros. + +Invocation +^^^^^^^^^^ + +The function invocation is case-insensitive. A function defined as + +.. code-block:: cmake + + function(foo) + <commands> + endfunction() + +can be invoked through any of + +.. code-block:: cmake + + foo() + Foo() + FOO() + +and so on. However, it is strongly recommended to stay with the +case chosen in the function definition. Typically functions use +all-lowercase names. + +Arguments +^^^^^^^^^ + +When the function is invoked, the recorded ``<commands>`` are first +modified by replacing formal parameters (``${arg1}``, ...) with the +arguments passed, and then invoked as normal commands. + +In addition to referencing the formal parameters you can reference the +``ARGC`` variable which will be set to the number of arguments passed +into the function as well as ``ARGV0``, ``ARGV1``, ``ARGV2``, ... which +will have the actual values of the arguments passed in. This facilitates +creating functions with optional arguments. + +Furthermore, ``ARGV`` holds the list of all arguments given to the +function and ``ARGN`` holds the list of arguments past the last expected +argument. Referencing to ``ARGV#`` arguments beyond ``ARGC`` have +undefined behavior. Checking that ``ARGC`` is greater than ``#`` is +the only way to ensure that ``ARGV#`` was passed to the function as an +extra argument. diff --git a/Help/command/get_cmake_property.rst b/Help/command/get_cmake_property.rst index 497ab4eeb..96764a3b9 100644 --- a/Help/command/get_cmake_property.rst +++ b/Help/command/get_cmake_property.rst @@ -3,14 +3,14 @@ get_cmake_property Get a global property of the CMake instance. -:: +.. code-block:: cmake - get_cmake_property(VAR property) + get_cmake_property(<var> <property>) -Get a global property from the CMake instance. The value of the property is -stored in the variable ``VAR``. If the property is not found, ``VAR`` -will be set to "NOTFOUND". See the :manual:`cmake-properties(7)` manual -for available properties. +Gets a global property from the CMake instance. The value of +the ``<property>`` is stored in the variable ``<var>``. +If the property is not found, ``<var>`` will be set to ``NOTFOUND``. +See the :manual:`cmake-properties(7)` manual for available properties. See also the :command:`get_property` command ``GLOBAL`` option. diff --git a/Help/command/get_directory_property.rst b/Help/command/get_directory_property.rst index e50abe0e9..218efa9d3 100644 --- a/Help/command/get_directory_property.rst +++ b/Help/command/get_directory_property.rst @@ -3,17 +3,22 @@ get_directory_property Get a property of ``DIRECTORY`` scope. -:: +.. code-block:: cmake get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>) -Store a property of directory scope in the named variable. If the -property is not defined the empty-string is returned. The ``DIRECTORY`` -argument specifies another directory from which to retrieve the -property value. The specified directory must have already been -traversed by CMake. +Stores a property of directory scope in the named ``<variable>``. +The ``DIRECTORY`` argument specifies another directory from which +to retrieve the property value instead of the current directory. +The specified directory must have already been traversed by CMake. -:: +If the property is not defined for the nominated directory scope, +an empty string is returned. In the case of ``INHERITED`` properties, +if the property is not found for the nominated directory scope, +the search will chain to a parent scope as described for the +:command:`define_property` command. + +.. code-block:: cmake get_directory_property(<variable> [DIRECTORY <dir>] DEFINITION <var-name>) diff --git a/Help/command/get_filename_component.rst b/Help/command/get_filename_component.rst index 14c8cf279..9bbf87714 100644 --- a/Help/command/get_filename_component.rst +++ b/Help/command/get_filename_component.rst @@ -3,13 +3,11 @@ get_filename_component Get a specific component of a full filename. ------------------------------------------------------------------------------- +.. code-block:: cmake -:: - - get_filename_component(<VAR> <FileName> <COMP> [CACHE]) + get_filename_component(<var> <FileName> <mode> [CACHE]) -Set ``<VAR>`` to a component of ``<FileName>``, where ``<COMP>`` is one of: +Sets ``<var>`` to a component of ``<FileName>``, where ``<mode>`` is one of: :: @@ -17,22 +15,19 @@ Set ``<VAR>`` to a component of ``<FileName>``, where ``<COMP>`` is one of: NAME = File name without directory EXT = File name longest extension (.b.c from d/a.b.c) NAME_WE = File name without directory or longest extension + LAST_EXT = File name last extension (.c from d/a.b.c) + NAME_WLE = File name without directory or last extension PATH = Legacy alias for DIRECTORY (use for CMake <= 2.8.11) Paths are returned with forward slashes and have no trailing slashes. -The longest file extension is always considered. If the optional -``CACHE`` argument is specified, the result variable is added to the -cache. +If the optional ``CACHE`` argument is specified, the result variable is +added to the cache. ------------------------------------------------------------------------------- +.. code-block:: cmake -:: + get_filename_component(<var> <FileName> <mode> [BASE_DIR <dir>] [CACHE]) - get_filename_component(<VAR> <FileName> - <COMP> [BASE_DIR <BASE_DIR>] - [CACHE]) - -Set ``<VAR>`` to the absolute path of ``<FileName>``, where ``<COMP>`` is one +Sets ``<var>`` to the absolute path of ``<FileName>``, where ``<mode>`` is one of: :: @@ -41,24 +36,20 @@ of: REALPATH = Full path to existing file with symlinks resolved If the provided ``<FileName>`` is a relative path, it is evaluated relative -to the given base directory ``<BASE_DIR>``. If no base directory is +to the given base directory ``<dir>``. If no base directory is provided, the default base directory will be :variable:`CMAKE_CURRENT_SOURCE_DIR`. -Paths are returned with forward slashes and have no trailing slahes. If the +Paths are returned with forward slashes and have no trailing slashes. If the optional ``CACHE`` argument is specified, the result variable is added to the cache. ------------------------------------------------------------------------------- - -:: +.. code-block:: cmake - get_filename_component(<VAR> <FileName> - PROGRAM [PROGRAM_ARGS <ARG_VAR>] - [CACHE]) + get_filename_component(<var> <FileName> PROGRAM [PROGRAM_ARGS <arg_var>] [CACHE]) The program in ``<FileName>`` will be found in the system search path or left as a full path. If ``PROGRAM_ARGS`` is present with ``PROGRAM``, then any command-line arguments present in the ``<FileName>`` string are split -from the program name and stored in ``<ARG_VAR>``. This is used to +from the program name and stored in ``<arg_var>``. This is used to separate a program name from its arguments in a command line string. diff --git a/Help/command/get_property.rst b/Help/command/get_property.rst index 632ece65c..c0f9b460a 100644 --- a/Help/command/get_property.rst +++ b/Help/command/get_property.rst @@ -3,32 +3,33 @@ get_property Get a property. -:: +.. code-block:: cmake get_property(<variable> <GLOBAL | - DIRECTORY [dir] | + DIRECTORY [<dir>] | TARGET <target> | SOURCE <source> | INSTALL <file> | TEST <test> | CACHE <entry> | - VARIABLE> + VARIABLE > PROPERTY <name> [SET | DEFINED | BRIEF_DOCS | FULL_DOCS]) -Get one property from one object in a scope. The first argument -specifies the variable in which to store the result. The second -argument determines the scope from which to get the property. It must -be one of the following: +Gets one property from one object in a scope. + +The first argument specifies the variable in which to store the result. +The second argument determines the scope from which to get the property. +It must be one of the following: ``GLOBAL`` Scope is unique and does not accept a name. ``DIRECTORY`` Scope defaults to the current directory but another - directory (already processed by CMake) may be named by full or - relative path. + directory (already processed by CMake) may be named by the + full or relative path ``<dir>``. ``TARGET`` Scope must name one existing target. @@ -50,11 +51,15 @@ be one of the following: The required ``PROPERTY`` option is immediately followed by the name of the property to get. If the property is not set an empty value is -returned. If the ``SET`` option is given the variable is set to a boolean +returned, although some properties support inheriting from a parent scope +if defined to behave that way (see :command:`define_property`). + +If the ``SET`` option is given the variable is set to a boolean value indicating whether the property has been set. If the ``DEFINED`` option is given the variable is set to a boolean value indicating whether the property has been defined such as with the :command:`define_property` command. + If ``BRIEF_DOCS`` or ``FULL_DOCS`` is given then the variable is set to a string containing documentation for the requested property. If documentation is requested for a property that has not been defined diff --git a/Help/command/get_source_file_property.rst b/Help/command/get_source_file_property.rst index 3e975c2f9..decec1916 100644 --- a/Help/command/get_source_file_property.rst +++ b/Help/command/get_source_file_property.rst @@ -3,14 +3,20 @@ get_source_file_property Get a property for a source file. -:: +.. code-block:: cmake get_source_file_property(VAR file property) -Get a property from a source file. The value of the property is -stored in the variable ``VAR``. If the property is not found, ``VAR`` -will be set to "NOTFOUND". Use :command:`set_source_files_properties` -to set property values. Source file properties usually control how the -file is built. One property that is always there is :prop_sf:`LOCATION` +Gets a property from a source file. The value of the property is +stored in the variable ``VAR``. If the source property is not found, the +behavior depends on whether it has been defined to be an ``INHERITED`` property +or not (see :command:`define_property`). Non-inherited properties will set +``VAR`` to "NOTFOUND", whereas inherited properties will search the relevant +parent scope as described for the :command:`define_property` command and +if still unable to find the property, ``VAR`` will be set to an empty string. + +Use :command:`set_source_files_properties` to set property values. Source +file properties usually control how the file is built. One property that is +always there is :prop_sf:`LOCATION`. See also the more general :command:`get_property` command. diff --git a/Help/command/get_target_property.rst b/Help/command/get_target_property.rst index 2a72c3af7..11e07eabe 100644 --- a/Help/command/get_target_property.rst +++ b/Help/command/get_target_property.rst @@ -3,16 +3,25 @@ get_target_property Get a property from a target. -:: +.. code-block:: cmake get_target_property(VAR target property) Get a property from a target. The value of the property is stored in -the variable ``VAR``. If the property is not found, ``VAR`` will be set to -"NOTFOUND". Use :command:`set_target_properties` to set property values. +the variable ``VAR``. If the target property is not found, the behavior +depends on whether it has been defined to be an ``INHERITED`` property +or not (see :command:`define_property`). Non-inherited properties will +set ``VAR`` to ``NOTFOUND``, whereas inherited properties will search the +relevant parent scope as described for the :command:`define_property` +command and if still unable to find the property, ``VAR`` will be set to +an empty string. + +Use :command:`set_target_properties` to set target property values. Properties are usually used to control how a target is built, but some query the target instead. This command can get properties for any target so far created. The targets do not need to be in the current ``CMakeLists.txt`` file. See also the more general :command:`get_property` command. + +See :ref:`Target Properties` for the list of properties known to CMake. diff --git a/Help/command/get_test_property.rst b/Help/command/get_test_property.rst index e359f4b3d..e02b9bc77 100644 --- a/Help/command/get_test_property.rst +++ b/Help/command/get_test_property.rst @@ -3,13 +3,19 @@ get_test_property Get a property of the test. -:: +.. code-block:: cmake get_test_property(test property VAR) Get a property from the test. The value of the property is stored in -the variable ``VAR``. If the test or property is not found, ``VAR`` will -be set to "NOTFOUND". For a list of standard properties you can type -``cmake --help-property-list``. +the variable ``VAR``. If the test property is not found, the behavior +depends on whether it has been defined to be an ``INHERITED`` property +or not (see :command:`define_property`). Non-inherited properties will +set ``VAR`` to "NOTFOUND", whereas inherited properties will search the +relevant parent scope as described for the :command:`define_property` +command and if still unable to find the property, ``VAR`` will be set to +an empty string. + +For a list of standard properties you can type ``cmake --help-property-list``. See also the more general :command:`get_property` command. diff --git a/Help/command/if.rst b/Help/command/if.rst index edd343de2..be992df15 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst @@ -3,41 +3,51 @@ if Conditionally execute a group of commands. +Synopsis +^^^^^^^^ + .. code-block:: cmake - if(expression) - # then section. - COMMAND1(ARGS ...) - COMMAND2(ARGS ...) - #... - elseif(expression2) - # elseif section. - COMMAND1(ARGS ...) - COMMAND2(ARGS ...) - #... - else(expression) - # else section. - COMMAND1(ARGS ...) - COMMAND2(ARGS ...) - #... - endif(expression) - -Evaluates the given expression. If the result is true, the commands -in the THEN section are invoked. Otherwise, the commands in the else -section are invoked. The elseif and else sections are optional. You -may have multiple elseif clauses. Note that the expression in the -else and endif clause is optional. Long expressions can be used and -there is a traditional order of precedence. Parenthetical expressions -are evaluated first followed by unary tests such as ``EXISTS``, -``COMMAND``, and ``DEFINED``. Then any binary tests such as -``EQUAL``, ``LESS``, ``LESS_EQUAL, ``GREATER``, ``GREATER_EQUAL``, + if(<condition>) + <commands> + elseif(<condition>) # optional block, can be repeated + <commands> + else() # optional block + <commands> + endif() + +Evaluates the ``condition`` argument of the ``if`` clause according to the +`Condition syntax`_ described below. If the result is true, then the +``commands`` in the ``if`` block are executed. +Otherwise, optional ``elseif`` blocks are processed in the same way. +Finally, if no ``condition`` is true, ``commands`` in the optional ``else`` +block are executed. + +Per legacy, the :command:`else` and :command:`endif` commands admit +an optional ``<condition>`` argument. +If used, it must be a verbatim +repeat of the argument of the opening +``if`` command. + +.. _`Condition Syntax`: + +Condition Syntax +^^^^^^^^^^^^^^^^ + +The following syntax applies to the ``condition`` argument of +the ``if``, ``elseif`` and :command:`while` clauses. + +Compound conditions are evaluated in the following order of precedence: +Innermost parentheses are evaluated first. Next come unary tests such +as ``EXISTS``, ``COMMAND``, and ``DEFINED``. Then binary tests such as +``EQUAL``, ``LESS``, ``LESS_EQUAL``, ``GREATER``, ``GREATER_EQUAL``, ``STREQUAL``, ``STRLESS``, ``STRLESS_EQUAL``, ``STRGREATER``, ``STRGREATER_EQUAL``, ``VERSION_EQUAL``, ``VERSION_LESS``, ``VERSION_LESS_EQUAL``, ``VERSION_GREATER``, ``VERSION_GREATER_EQUAL``, -and ``MATCHES`` will be evaluated. Then boolean ``NOT`` operators and -finally boolean ``AND`` and then ``OR`` operators will be evaluated. +and ``MATCHES``. Then the boolean operators in the order ``NOT``, ``AND``, +and finally ``OR``. -Possible expressions are: +Possible conditions are: ``if(<constant>)`` True if the constant is ``1``, ``ON``, ``YES``, ``TRUE``, ``Y``, @@ -52,14 +62,14 @@ Possible expressions are: True if given a variable that is defined to a value that is not a false constant. False otherwise. (Note macro arguments are not variables.) -``if(NOT <expression>)`` - True if the expression is not true. +``if(NOT <condition>)`` + True if the condition is not true. -``if(<expr1> AND <expr2>)`` - True if both expressions would be considered true individually. +``if(<cond1> AND <cond2>)`` + True if both conditions would be considered true individually. -``if(<expr1> OR <expr2>)`` - True if either expression would be considered true individually. +``if(<cond1> OR <cond2>)`` + True if either condition would be considered true individually. ``if(COMMAND command-name)`` True if the given name is a command, macro or function that can be @@ -80,7 +90,9 @@ Possible expressions are: ``if(EXISTS path-to-file-or-directory)`` True if the named file or directory exists. Behavior is well-defined - only for full paths. + only for full paths. Resolves symbolic links, i.e. if the named file or + directory is a symbolic link, returns true if the target of the + symbolic link exists. ``if(file1 IS_NEWER_THAN file2)`` True if ``file1`` is newer than ``file2`` or if one of the two files doesn't @@ -103,7 +115,7 @@ Possible expressions are: ``if(<variable|string> MATCHES regex)`` True if the given string or variable's value matches the given regular - expression. See :ref:`Regex Specification` for regex format. + condition. See :ref:`Regex Specification` for regex format. ``()`` groups are captured in :variable:`CMAKE_MATCH_<n>` variables. ``if(<variable|string> LESS <variable|string>)`` @@ -148,63 +160,82 @@ 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. -``if(DEFINED <variable>)`` - True if the given variable is defined. It does not matter if the - variable is true or false just if it has been set. (Note macro - arguments are not variables.) +``if(DEFINED <name>|CACHE{<name>}|ENV{<name>})`` + True if a variable, cache variable or environment variable + with given ``<name>`` is defined. The value of the variable + does not matter. Note that macro arguments are not variables. -``if((expression) AND (expression OR (expression)))`` - The expressions inside the parenthesis are evaluated first and then - the remaining expression is evaluated as in the previous examples. +``if((condition) AND (condition OR (condition)))`` + The conditions inside the parenthesis are evaluated first and then + the remaining condition is evaluated as in the previous examples. Where there are nested parenthesis the innermost are evaluated as part - of evaluating the expression that contains them. + of evaluating the condition that contains them. + +Variable Expansion +^^^^^^^^^^^^^^^^^^ The if command was written very early in CMake's history, predating the ``${}`` variable evaluation syntax, and for convenience evaluates variables named by its arguments as shown in the above signatures. Note that normal variable evaluation with ``${}`` applies before the if -command even receives the arguments. Therefore code like:: +command even receives the arguments. Therefore code like + +.. code-block:: cmake set(var1 OFF) set(var2 "var1") if(${var2}) -appears to the if command as:: +appears to the if command as - if(var1) +.. code-block:: cmake + + if(var1) and is evaluated according to the ``if(<variable>)`` case documented above. The result is ``OFF`` which is false. However, if we remove the -``${}`` from the example then the command sees:: +``${}`` from the example then the command sees - if(var2) +.. code-block:: cmake -which is true because ``var2`` is defined to "var1" which is not a false + if(var2) + +which is true because ``var2`` is defined to ``var1`` which is not a false constant. Automatic evaluation applies in the other cases whenever the -above-documented signature accepts ``<variable|string>``: +above-documented condition syntax accepts ``<variable|string>``: * The left hand argument to ``MATCHES`` is first checked to see if it is a defined variable, if so the variable's value is used, otherwise the @@ -242,3 +273,8 @@ specified in a :ref:`Quoted Argument` or a :ref:`Bracket Argument`. A quoted or bracketed variable or keyword will be interpreted as a string and not dereferenced or interpreted. See policy :policy:`CMP0054`. + +There is no automatic evaluation for environment or cache +:ref:`Variable References`. Their values must be referenced as +``$ENV{<name>}`` or ``$CACHE{<name>}`` wherever the above-documented +condition syntax accepts ``<variable|string>``. diff --git a/Help/command/include.rst b/Help/command/include.rst index eeca4c6e3..80968da7b 100644 --- a/Help/command/include.rst +++ b/Help/command/include.rst @@ -3,16 +3,16 @@ include Load and run CMake code from a file or module. -:: +.. code-block:: cmake - include(<file|module> [OPTIONAL] [RESULT_VARIABLE <VAR>] + include(<file|module> [OPTIONAL] [RESULT_VARIABLE <var>] [NO_POLICY_SCOPE]) -Load and run CMake code from the file given. Variable reads and +Loads and runs CMake code from the file given. Variable reads and writes access the scope of the caller (dynamic scoping). If ``OPTIONAL`` is present, then no error is raised if the file does not exist. If -``RESULT_VARIABLE`` is given the variable will be set to the full filename -which has been included or NOTFOUND if it failed. +``RESULT_VARIABLE`` is given the variable ``<var>`` will be set to the +full filename which has been included or ``NOTFOUND`` if it failed. If a module is specified instead of a file, the file with name ``<modulename>.cmake`` is searched first in :variable:`CMAKE_MODULE_PATH`, diff --git a/Help/command/include_directories.rst b/Help/command/include_directories.rst index f69493460..fe281c3c8 100644 --- a/Help/command/include_directories.rst +++ b/Help/command/include_directories.rst @@ -3,7 +3,7 @@ include_directories Add include directories to the build. -:: +.. code-block:: cmake include_directories([AFTER|BEFORE] [SYSTEM] dir1 [dir2 ...]) @@ -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. diff --git a/Help/command/include_external_msproject.rst b/Help/command/include_external_msproject.rst index 335282a30..540a13af8 100644 --- a/Help/command/include_external_msproject.rst +++ b/Help/command/include_external_msproject.rst @@ -3,7 +3,7 @@ include_external_msproject Include an external Microsoft project file in a workspace. -:: +.. code-block:: cmake include_external_msproject(projectname location [TYPE projectTypeGUID] @@ -13,11 +13,11 @@ Include an external Microsoft project file in a workspace. Includes an external Microsoft project in the generated workspace file. Currently does nothing on UNIX. This will create a target -named [projectname]. This can be used in the :command:`add_dependencies` +named ``[projectname]``. This can be used in the :command:`add_dependencies` command to make things depend on the external project. ``TYPE``, ``GUID`` and ``PLATFORM`` are optional parameters that allow one to -specify the type of project, id (GUID) of the project and the name of +specify the type of project, id (``GUID``) of the project and the name of the target platform. This is useful for projects requiring values other than the default (e.g. WIX projects). diff --git a/Help/command/include_guard.rst b/Help/command/include_guard.rst new file mode 100644 index 000000000..877aa86d9 --- /dev/null +++ b/Help/command/include_guard.rst @@ -0,0 +1,46 @@ +include_guard +------------- + +Provides an include guard for the file currently being processed by CMake. + +.. code-block:: cmake + + include_guard([DIRECTORY|GLOBAL]) + +Sets up an include guard for the current CMake file (see the +:variable:`CMAKE_CURRENT_LIST_FILE` variable documentation). + +CMake will end its processing of the current file at the location of the +:command:`include_guard` command if the current file has already been +processed for the applicable scope (see below). This provides functionality +similar to the include guards commonly used in source headers or to the +``#pragma once`` directive. If the current file has been processed previously +for the applicable scope, the effect is as though :command:`return` had been +called. Do not call this command from inside a function being defined within +the current file. + +An optional argument specifying the scope of the guard may be provided. +Possible values for the option are: + +``DIRECTORY`` + The include guard applies within the current directory and below. The file + will only be included once within this directory scope, but may be included + again by other files outside of this directory (i.e. a parent directory or + another directory not pulled in by :command:`add_subdirectory` or + :command:`include` from the current file or its children). + +``GLOBAL`` + The include guard applies globally to the whole build. The current file + will only be included once regardless of the scope. + +If no arguments given, ``include_guard`` has the same scope as a variable, +meaning that the include guard effect is isolated by the most recent +function scope or current directory if no inner function scopes exist. +In this case the command behavior is the same as: + +.. code-block:: cmake + + if(__CURRENT_FILE_VAR__) + return() + endif() + set(__CURRENT_FILE_VAR__ TRUE) diff --git a/Help/command/include_regular_expression.rst b/Help/command/include_regular_expression.rst index ab5a56325..dde837892 100644 --- a/Help/command/include_regular_expression.rst +++ b/Help/command/include_regular_expression.rst @@ -3,11 +3,11 @@ include_regular_expression Set the regular expression used for dependency checking. -:: +.. code-block:: cmake include_regular_expression(regex_match [regex_complain]) -Set the regular expressions used in dependency checking. Only files +Sets the regular expressions used in dependency checking. Only files matching ``regex_match`` will be traced as dependencies. Only files matching ``regex_complain`` will generate warnings if they cannot be found (standard header paths are not searched). The defaults are: diff --git a/Help/command/install.rst b/Help/command/install.rst index 58438b763..5affc5b99 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -1,11 +1,19 @@ install ------- -.. only:: html +Specify rules to run at install time. - .. contents:: +Synopsis +^^^^^^^^ -Specify rules to run at install time. +.. parsed-literal:: + + install(`TARGETS`_ <target>... [...]) + install({`FILES`_ | `PROGRAMS`_} <file>... [...]) + install(`DIRECTORY`_ <dir>... [...]) + install(`SCRIPT`_ <file> [...]) + install(`CODE`_ <code> [...]) + install(`EXPORT`_ <export-name> [...]) Introduction ^^^^^^^^^^^^ @@ -38,7 +46,21 @@ signatures that specify them. The common options are: ``CONFIGURATIONS`` Specify a list of build configurations for which the install rule - applies (Debug, Release, etc.). + applies (Debug, Release, etc.). Note that the values specified for + this option only apply to options listed AFTER the ``CONFIGURATIONS`` + option. For example, to set separate install paths for the Debug and + Release configurations, do the following: + + .. code-block:: cmake + + install(TARGETS target + CONFIGURATIONS Debug + RUNTIME DESTINATION Debug/bin) + install(TARGETS target + CONFIGURATIONS Release + RUNTIME DESTINATION Release/bin) + + Note that ``CONFIGURATIONS`` appears BEFORE ``RUNTIME DESTINATION``. ``COMPONENT`` Specify an installation component name with which the install rule @@ -67,10 +89,20 @@ 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 ^^^^^^^^^^^^^^^^^^ -:: +.. _`install(TARGETS)`: +.. _TARGETS: + +.. code-block:: cmake install(TARGETS targets... [EXPORT <export-name>] [[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE| @@ -79,6 +111,7 @@ Installing Targets [PERMISSIONS permissions...] [CONFIGURATIONS [Debug|Release|...]] [COMPONENT <component>] + [NAMELINK_COMPONENT <component>] [OPTIONAL] [EXCLUDE_FROM_ALL] [NAMELINK_ONLY|NAMELINK_SKIP] ] [...] @@ -86,63 +119,194 @@ Installing Targets ) The ``TARGETS`` form specifies rules for installing targets from a -project. There are six kinds of target files that may be installed: -``ARCHIVE``, ``LIBRARY``, ``RUNTIME``, ``OBJECTS``, ``FRAMEWORK``, and -``BUNDLE``. Executables are treated as ``RUNTIME`` targets, except that -those marked with the ``MACOSX_BUNDLE`` property are treated as ``BUNDLE`` -targets on OS X. Static libraries are treated as ``ARCHIVE`` targets, -except that those marked with the ``FRAMEWORK`` property are treated -as ``FRAMEWORK`` targets on OS X. -Module libraries are always treated as ``LIBRARY`` targets. -For non-DLL platforms shared libraries are treated as ``LIBRARY`` -targets, except that those marked with the ``FRAMEWORK`` property are -treated as ``FRAMEWORK`` targets on OS X. For DLL platforms the DLL -part of a shared library is treated as a ``RUNTIME`` target and the -corresponding import library is treated as an ``ARCHIVE`` target. -All Windows-based systems including Cygwin are DLL platforms. Object -libraries are always treated as ``OBJECTS`` targets. -The ``ARCHIVE``, ``LIBRARY``, ``RUNTIME``, ``OBJECTS``, and ``FRAMEWORK`` -arguments change the type of target to which the subsequent properties -apply. If none is given the installation properties apply to all target -types. If only one is given then only targets of that type will be -installed (which can be used to install just a DLL or just an import -library). - -The ``PRIVATE_HEADER``, ``PUBLIC_HEADER``, and ``RESOURCE`` arguments -cause subsequent properties to be applied to installing a ``FRAMEWORK`` -shared library target's associated files on non-Apple platforms. Rules -defined by these arguments are ignored on Apple platforms because the -associated files are installed into the appropriate locations inside -the framework folder. See documentation of the -:prop_tgt:`PRIVATE_HEADER`, :prop_tgt:`PUBLIC_HEADER`, and -:prop_tgt:`RESOURCE` target properties for details. - -Either ``NAMELINK_ONLY`` or ``NAMELINK_SKIP`` may be specified as a -``LIBRARY`` option. On some platforms a versioned shared library -has a symbolic link such as:: - - lib<name>.so -> lib<name>.so.1 - -where ``lib<name>.so.1`` is the soname of the library and ``lib<name>.so`` -is a "namelink" allowing linkers to find the library when given -``-l<name>``. The ``NAMELINK_ONLY`` option causes installation of only the -namelink when a library target is installed. The ``NAMELINK_SKIP`` option -causes installation of library files other than the namelink when a -library target is installed. When neither option is given both -portions are installed. On platforms where versioned shared libraries -do not have namelinks or when a library is not versioned the -``NAMELINK_SKIP`` option installs the library and the ``NAMELINK_ONLY`` -option installs nothing. See the :prop_tgt:`VERSION` and -:prop_tgt:`SOVERSION` target properties for details on creating versioned -shared libraries. - -The ``INCLUDES DESTINATION`` specifies a list of directories -which will be added to the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` -target property of the ``<targets>`` when exported by the -:command:`install(EXPORT)` command. If a relative path is -specified, it is treated as relative to the ``$<INSTALL_PREFIX>``. -This is independent of the rest of the argument groups and does -not actually install anything. +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 macOS (see ``FRAMEWORK`` + below.) For DLL platforms (all Windows-based systems including + Cygwin), the DLL import library is treated as an ``ARCHIVE`` target. + On AIX, the linker import file created for executables with + :prop_tgt:`ENABLE_EXPORTS` 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 macOS (see + ``FRAMEWORK`` below.) + +``RUNTIME`` + Executables are treated as ``RUNTIME`` objects, except those marked + 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. + +``OBJECTS`` + Object libraries (a simple group of object files) are always treated + as ``OBJECTS`` targets. + +``FRAMEWORK`` + Both static and shared libraries marked with the ``FRAMEWORK`` + property are treated as ``FRAMEWORK`` targets on macOS. + +``BUNDLE`` + Executables marked with the :prop_tgt:`MACOSX_BUNDLE` property are treated as + ``BUNDLE`` targets on macOS. + +``PUBLIC_HEADER`` + Any :prop_tgt:`PUBLIC_HEADER` files associated with a library are installed in + the destination specified by the ``PUBLIC_HEADER`` argument on non-Apple + platforms. Rules defined by this argument are ignored for :prop_tgt:`FRAMEWORK` + libraries on Apple platforms because the associated files are installed + into the appropriate locations inside the framework folder. See + :prop_tgt:`PUBLIC_HEADER` for details. + +``PRIVATE_HEADER`` + Similar to ``PUBLIC_HEADER``, but for ``PRIVATE_HEADER`` files. See + :prop_tgt:`PRIVATE_HEADER` for details. + +``RESOURCE`` + Similar to ``PUBLIC_HEADER`` and ``PRIVATE_HEADER``, but for + ``RESOURCE`` files. See :prop_tgt:`RESOURCE` for details. + +For each of these arguments given, the arguments following them only apply +to the target or file type specified in the argument. If none is given, the +installation properties apply to all target types. If only one is given then +only targets of that type will be installed (which can be used to install +just a DLL or just an import library.) + +For regular executables, static libraries and shared libraries, the +``DESTINATION`` argument is not required. For these target types, when +``DESTINATION`` is omitted, a default destination will be taken from the +appropriate variable from :module:`GNUInstallDirs`, or set to a built-in +default value if that variable is not defined. The same is true for the +public and private headers associated with the installed targets through the +:prop_tgt:`PUBLIC_HEADER` and :prop_tgt:`PRIVATE_HEADER` target properties. +A destination must always be provided for module libraries, Apple bundles and +frameworks. A destination can be omitted for interface and object libraries, +but they are handled differently (see the discussion of this topic toward the +end of this section). + +The following table shows the target types with their associated variables and +built-in defaults that apply when no destination is given: + +================== =============================== ====================== + Target Type GNUInstallDirs Variable Built-In Default +================== =============================== ====================== +``RUNTIME`` ``${CMAKE_INSTALL_BINDIR}`` ``bin`` +``LIBRARY`` ``${CMAKE_INSTALL_LIBDIR}`` ``lib`` +``ARCHIVE`` ``${CMAKE_INSTALL_LIBDIR}`` ``lib`` +``PRIVATE_HEADER`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include`` +``PUBLIC_HEADER`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include`` +================== =============================== ====================== + +Projects wishing to follow the common practice of installing headers into a +project-specific subdirectory will need to provide a destination rather than +rely on the above. + +To make packages compliant with distribution filesystem layout policies, if +projects must specify a ``DESTINATION``, it is recommended that they use a +path that begins with the appropriate :module:`GNUInstallDirs` variable. +This allows package maintainers to control the install destination by setting +the appropriate cache variables. The following example shows a static library +being installed to the default destination provided by +:module:`GNUInstallDirs`, but with its headers installed to a project-specific +subdirectory that follows the above recommendation: + +.. code-block:: cmake + + add_library(mylib STATIC ...) + set_target_properties(mylib PROPERTIES PUBLIC_HEADER mylib.h) + include(GNUInstallDirs) + install(TARGETS mylib + PUBLIC_HEADER + DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj + ) + +In addition to the common options listed above, each target can accept +the following additional arguments: + +``NAMELINK_COMPONENT`` + On some platforms a versioned shared library has a symbolic link such + as:: + + lib<name>.so -> lib<name>.so.1 + + where ``lib<name>.so.1`` is the soname of the library and ``lib<name>.so`` + is a "namelink" allowing linkers to find the library when given + ``-l<name>``. The ``NAMELINK_COMPONENT`` option is similar to the + ``COMPONENT`` option, but it changes the installation component of a shared + library namelink if one is generated. If not specified, this defaults to the + value of ``COMPONENT``. It is an error to use this parameter outside of a + ``LIBRARY`` block. + + Consider the following example: + + .. code-block:: cmake + + install(TARGETS mylib + LIBRARY + COMPONENT Libraries + NAMELINK_COMPONENT Development + PUBLIC_HEADER + COMPONENT Development + ) + + In this scenario, if you choose to install only the ``Development`` + component, both the headers and namelink will be installed without the + library. (If you don't also install the ``Libraries`` component, the + namelink will be a dangling symlink, and projects that link to the library + will have build errors.) If you install only the ``Libraries`` component, + only the library will be installed, without the headers and namelink. + + This option is typically used for package managers that have separate + runtime and development packages. For example, on Debian systems, the + library is expected to be in the runtime package, and the headers and + namelink are expected to be in the development package. + + See the :prop_tgt:`VERSION` and :prop_tgt:`SOVERSION` target properties for + details on creating versioned shared libraries. + +``NAMELINK_ONLY`` + This option causes the installation of only the namelink when a library + target is installed. On platforms where versioned shared libraries do not + have namelinks or when a library is not versioned, the ``NAMELINK_ONLY`` + option installs nothing. It is an error to use this parameter outside of a + ``LIBRARY`` block. + + When ``NAMELINK_ONLY`` is given, either ``NAMELINK_COMPONENT`` or + ``COMPONENT`` may be used to specify the installation component of the + namelink, but ``COMPONENT`` should generally be preferred. + +``NAMELINK_SKIP`` + Similar to ``NAMELINK_ONLY``, but it has the opposite effect: it causes the + installation of library files other than the namelink when a library target + is installed. When neither ``NAMELINK_ONLY`` or ``NAMELINK_SKIP`` are given, + both portions are installed. On platforms where versioned shared libraries + do not have symlinks or when a library is not versioned, ``NAMELINK_SKIP`` + installs the library. It is an error to use this parameter outside of a + ``LIBRARY`` block. + + If ``NAMELINK_SKIP`` is specified, ``NAMELINK_COMPONENT`` has no effect. It + is not recommended to use ``NAMELINK_SKIP`` in conjunction with + ``NAMELINK_COMPONENT``. + +The `install(TARGETS)`_ command can also accept the following options at the +top level: + +``EXPORT`` + This option associates the installed target files with an export called + ``<export-name>``. It must appear before any target options. To actually + install the export file itself, call `install(EXPORT)`_, documented below. + See documentation of the :prop_tgt:`EXPORT_NAME` target property to change + the name of the exported target. + +``INCLUDES DESTINATION`` + This option specifies a list of directories which will be added to the + :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property of the + ``<targets>`` when exported by the `install(EXPORT)`_ command. If a + relative path is specified, it is treated as relative to the + ``$<INSTALL_PREFIX>``. One or more groups of properties may be specified in a single call to the ``TARGETS`` form of this command. A target may be installed more than @@ -164,24 +328,40 @@ the ``mySharedLib`` DLL will be installed to ``<prefix>/bin`` and ``/some/full/path`` and its import library will be installed to ``<prefix>/lib/static`` and ``/some/full/path``. -The ``EXPORT`` option associates the installed target files with an -export called ``<export-name>``. It must appear before any ``RUNTIME``, -``LIBRARY``, ``ARCHIVE``, or ``OBJECTS`` options. To actually install the -export file itself, call ``install(EXPORT)``, documented below. +:ref:`Interface Libraries` may be listed among the targets to install. +They install no artifacts but will be included in an associated ``EXPORT``. +If :ref:`Object Libraries` are listed but given no destination for their +object files, they will be exported as :ref:`Interface Libraries`. +This is sufficient to satisfy transitive usage requirements of other +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. -The install destination given to the target install ``DESTINATION`` may +`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. + +An install destination given as a ``DESTINATION`` argument may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. Installing Files ^^^^^^^^^^^^^^^^ -:: +.. _`install(FILES)`: +.. _`install(PROGRAMS)`: +.. _FILES: +.. _PROGRAMS: + +.. code-block:: cmake - install(<FILES|PROGRAMS> files... DESTINATION <dir> + install(<FILES|PROGRAMS> files... + TYPE <type> | DESTINATION <dir> [PERMISSIONS permissions...] [CONFIGURATIONS [Debug|Release|...]] [COMPONENT <component>] @@ -205,16 +385,71 @@ The list of ``files...`` given to ``FILES`` or ``PROGRAMS`` may use However, if any item begins in a generator expression it must evaluate to a full path. -The install destination given to the files install ``DESTINATION`` may +Either a ``TYPE`` or a ``DESTINATION`` must be provided, but not both. +A ``TYPE`` argument specifies the generic file type of the files being +installed. A destination will then be set automatically by taking the +corresponding variable from :module:`GNUInstallDirs`, or by using a +built-in default if that variable is not defined. See the table below for +the supported file types and their corresponding variables and built-in +defaults. Projects can provide a ``DESTINATION`` argument instead of a +file type if they wish to explicitly define the install destination. + +======================= ================================== ========================= + ``TYPE`` Argument GNUInstallDirs Variable Built-In Default +======================= ================================== ========================= +``BIN`` ``${CMAKE_INSTALL_BINDIR}`` ``bin`` +``SBIN`` ``${CMAKE_INSTALL_SBINDIR}`` ``sbin`` +``LIB`` ``${CMAKE_INSTALL_LIBDIR}`` ``lib`` +``INCLUDE`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include`` +``SYSCONF`` ``${CMAKE_INSTALL_SYSCONFDIR}`` ``etc`` +``SHAREDSTATE`` ``${CMAKE_INSTALL_SHARESTATEDIR}`` ``com`` +``LOCALSTATE`` ``${CMAKE_INSTALL_LOCALSTATEDIR}`` ``var`` +``RUNSTATE`` ``${CMAKE_INSTALL_RUNSTATEDIR}`` ``<LOCALSTATE dir>/run`` +``DATA`` ``${CMAKE_INSTALL_DATADIR}`` ``<DATAROOT dir>`` +``INFO`` ``${CMAKE_INSTALL_INFODIR}`` ``<DATAROOT dir>/info`` +``LOCALE`` ``${CMAKE_INSTALL_LOCALEDIR}`` ``<DATAROOT dir>/locale`` +``MAN`` ``${CMAKE_INSTALL_MANDIR}`` ``<DATAROOT dir>/man`` +``DOC`` ``${CMAKE_INSTALL_DOCDIR}`` ``<DATAROOT dir>/doc`` +======================= ================================== ========================= + +Projects wishing to follow the common practice of installing headers into a +project-specific subdirectory will need to provide a destination rather than +rely on the above. + +Note that some of the types' built-in defaults use the ``DATAROOT`` directory as +a prefix. The ``DATAROOT`` prefix is calculated similarly to the types, with +``CMAKE_INSTALL_DATAROOTDIR`` as the variable and ``share`` as the built-in +default. You cannot use ``DATAROOT`` as a ``TYPE`` parameter; please use +``DATA`` instead. + +To make packages compliant with distribution filesystem layout policies, if +projects must specify a ``DESTINATION``, it is recommended that they use a +path that begins with the appropriate :module:`GNUInstallDirs` variable. +This allows package maintainers to control the install destination by setting +the appropriate cache variables. The following example shows how to follow +this advice while installing headers to a project-specific subdirectory: + +.. code-block:: cmake + + include(GNUInstallDirs) + install(FILES mylib.h + DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj + ) + +An install destination given as a ``DESTINATION`` argument may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. Installing Directories ^^^^^^^^^^^^^^^^^^^^^^ -:: +.. _`install(DIRECTORY)`: +.. _DIRECTORY: + +.. code-block:: cmake - install(DIRECTORY dirs... DESTINATION <dir> + install(DIRECTORY dirs... + TYPE <type> | DESTINATION <dir> [FILE_PERMISSIONS permissions...] [DIRECTORY_PERMISSIONS permissions...] [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER] @@ -285,15 +520,60 @@ will install the ``icons`` directory to ``share/myproj/icons`` and the file permissions, the scripts will be given specific permissions, and any ``CVS`` directories will be excluded. -The list of ``dirs...`` given to ``DIRECTORY`` and the install destination -given to the directory install ``DESTINATION`` may use "generator expressions" +Either a ``TYPE`` or a ``DESTINATION`` must be provided, but not both. +A ``TYPE`` argument specifies the generic file type of the files within the +listed directories being installed. A destination will then be set +automatically by taking the corresponding variable from +:module:`GNUInstallDirs`, or by using a built-in default if that variable +is not defined. See the table below for the supported file types and their +corresponding variables and built-in defaults. Projects can provide a +``DESTINATION`` argument instead of a file type if they wish to explicitly +define the install destination. + +======================= ================================== ========================= + ``TYPE`` Argument GNUInstallDirs Variable Built-In Default +======================= ================================== ========================= +``BIN`` ``${CMAKE_INSTALL_BINDIR}`` ``bin`` +``SBIN`` ``${CMAKE_INSTALL_SBINDIR}`` ``sbin`` +``LIB`` ``${CMAKE_INSTALL_LIBDIR}`` ``lib`` +``INCLUDE`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include`` +``SYSCONF`` ``${CMAKE_INSTALL_SYSCONFDIR}`` ``etc`` +``SHAREDSTATE`` ``${CMAKE_INSTALL_SHARESTATEDIR}`` ``com`` +``LOCALSTATE`` ``${CMAKE_INSTALL_LOCALSTATEDIR}`` ``var`` +``RUNSTATE`` ``${CMAKE_INSTALL_RUNSTATEDIR}`` ``<LOCALSTATE dir>/run`` +``DATA`` ``${CMAKE_INSTALL_DATADIR}`` ``<DATAROOT dir>`` +``INFO`` ``${CMAKE_INSTALL_INFODIR}`` ``<DATAROOT dir>/info`` +``LOCALE`` ``${CMAKE_INSTALL_LOCALEDIR}`` ``<DATAROOT dir>/locale`` +``MAN`` ``${CMAKE_INSTALL_MANDIR}`` ``<DATAROOT dir>/man`` +``DOC`` ``${CMAKE_INSTALL_DOCDIR}`` ``<DATAROOT dir>/doc`` +======================= ================================== ========================= + +Note that some of the types' built-in defaults use the ``DATAROOT`` directory as +a prefix. The ``DATAROOT`` prefix is calculated similarly to the types, with +``CMAKE_INSTALL_DATAROOTDIR`` as the variable and ``share`` as the built-in +default. You cannot use ``DATAROOT`` as a ``TYPE`` parameter; please use +``DATA`` instead. + +To make packages compliant with distribution filesystem layout policies, if +projects must specify a ``DESTINATION``, it is recommended that they use a +path that begins with the appropriate :module:`GNUInstallDirs` variable. +This allows package maintainers to control the install destination by setting +the appropriate cache variables. + +The list of ``dirs...`` given to ``DIRECTORY`` and an install destination +given as a ``DESTINATION`` argument may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. Custom Installation Logic ^^^^^^^^^^^^^^^^^^^^^^^^^ -:: +.. _`install(CODE)`: +.. _`install(SCRIPT)`: +.. _CODE: +.. _SCRIPT: + +.. code-block:: cmake install([[SCRIPT <file>] [CODE <code>]] [COMPONENT <component>] [EXCLUDE_FROM_ALL] [...]) @@ -311,24 +591,32 @@ example, the code will print a message during installation. +``<file>`` or ``<code>`` may use "generator expressions" with the syntax +``$<...>`` (in the case of ``<file>``, this refers to their use in the file +name, not the file's contents). See the +:manual:`cmake-generator-expressions(7)` manual for available expressions. + Installing Exports ^^^^^^^^^^^^^^^^^^ -:: +.. _`install(EXPORT)`: +.. _EXPORT: + +.. code-block:: cmake install(EXPORT <export-name> DESTINATION <dir> [NAMESPACE <namespace>] [[FILE <name>.cmake]| - [EXPORT_ANDROID_MK <name>.mk]] [PERMISSIONS permissions...] [CONFIGURATIONS [Debug|Release|...]] [EXPORT_LINK_INTERFACE_LIBRARIES] [COMPONENT <component>] [EXCLUDE_FROM_ALL]) + install(EXPORT_ANDROID_MK <export-name> DESTINATION <dir> [...]) The ``EXPORT`` form generates and installs a CMake file containing code to import targets from the installation tree into another project. Target installations are associated with the export ``<export-name>`` -using the ``EXPORT`` option of the ``install(TARGETS)`` signature +using the ``EXPORT`` option of the `install(TARGETS)`_ signature documented above. The ``NAMESPACE`` option will prepend ``<namespace>`` to the target names as they are written to the import file. By default the generated file will be called ``<export-name>.cmake`` but the ``FILE`` @@ -340,14 +628,28 @@ generated import file will reference only the matching target configurations. The ``EXPORT_LINK_INTERFACE_LIBRARIES`` keyword, if present, causes the contents of the properties matching ``(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?`` to be exported, when -policy :policy:`CMP0022` is ``NEW``. If a ``COMPONENT`` option is -specified that does not match that given to the targets associated with -``<export-name>`` the behavior is undefined. If a library target is -included in the export but a target to which it links is not included -the behavior is unspecified. - -In additon to cmake language files, the ``EXPORT_ANDROID_MK`` option maybe -used to specifiy an export to the android ndk build system. The Android +policy :policy:`CMP0022` is ``NEW``. + +When a ``COMPONENT`` option is given, the listed ``<component>`` implicitly +depends on all components mentioned in the export set. The exported +``<name>.cmake`` file will require each of the exported components to be +present in order for dependent projects to build properly. For example, a +project may define components ``Runtime`` and ``Development``, with shared +libraries going into the ``Runtime`` component and static libraries and +headers going into the ``Development`` component. The export set would also +typically be part of the ``Development`` component, but it would export +targets from both the ``Runtime`` and ``Development`` components. Therefore, +the ``Runtime`` component would need to be installed if the ``Development`` +component was installed, but not vice versa. If the ``Development`` component +was installed without the ``Runtime`` component, dependent projects that try +to link against it would have build errors. Package managers, such as APT and +RPM, typically handle this by listing the ``Runtime`` component as a dependency +of the ``Development`` component in the package metadata, ensuring that the +library is always installed if the headers and CMake export file are present. + +In addition to cmake language files, the ``EXPORT_ANDROID_MK`` mode maybe +used to specify an export to the android ndk build system. This mode +accepts the same options as the normal export mode. The Android NDK supports the use of prebuilt libraries, both static and shared. This allows cmake to build the libraries of a project and make them available to an ndk build system complete with transitive dependencies, include flags @@ -360,11 +662,11 @@ and installed by the current project. For example, the code install(TARGETS myexe EXPORT myproj DESTINATION bin) install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj) - install(EXPORT_ANDROID_MK myexp DESTINATION share/ndk-modules) + install(EXPORT_ANDROID_MK myproj DESTINATION share/ndk-modules) -will install the executable myexe to ``<prefix>/bin`` and code to import +will install the executable ``myexe`` to ``<prefix>/bin`` and code to import it in the file ``<prefix>/lib/myproj/myproj.cmake`` and -``<prefix>/lib/share/ndk-modules/Android.mk``. An outside project +``<prefix>/share/ndk-modules/Android.mk``. An outside project may load this file with the include command and reference the ``myexe`` executable from the installation tree using the imported target name ``mp_myexe`` as if the target were built in its own tree. @@ -378,3 +680,26 @@ executable from the installation tree using the imported target name those generated by :command:`install_targets`, :command:`install_files`, and :command:`install_programs` commands is not defined. + +Generated Installation Script +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``install()`` command generates a file, ``cmake_install.cmake``, inside +the build directory, which is used internally by the generated install target +and by CPack. You can also invoke this script manually with ``cmake -P``. This +script accepts several variables: + +``COMPONENT`` + Set this variable to install only a single CPack component as opposed to all + of them. For example, if you only want to install the ``Development`` + component, run ``cmake -DCOMPONENT=Development -P cmake_install.cmake``. + +``BUILD_TYPE`` + Set this variable to change the build type if you are using a multi-config + generator. For example, to install with the ``Debug`` configuration, run + ``cmake -DBUILD_TYPE=Debug -P cmake_install.cmake``. + +``DESTDIR`` + This is an environment variable rather than a CMake variable. It allows you + to change the installation prefix on UNIX systems. See :envvar:`DESTDIR` for + details. diff --git a/Help/command/install_files.rst b/Help/command/install_files.rst index 1850be6e1..ff074a8a7 100644 --- a/Help/command/install_files.rst +++ b/Help/command/install_files.rst @@ -1,7 +1,9 @@ install_files ------------- -Deprecated. Use the :command:`install(FILES)` command instead. +.. deprecated:: 3.0 + + Use the :command:`install(FILES)` command instead. This command has been superceded by the :command:`install` command. It is provided for compatibility with older CMake code. The ``FILES`` form is @@ -19,7 +21,7 @@ or its corresponding location in the binary tree may be listed. If a file specified already has an extension, that extension will be removed first. This is useful for providing lists of source files such as foo.cxx when you want the corresponding foo.h to be installed. -A typical extension is '.h'. +A typical extension is ``.h``. :: diff --git a/Help/command/install_programs.rst b/Help/command/install_programs.rst index 79aa486a3..fab64820d 100644 --- a/Help/command/install_programs.rst +++ b/Help/command/install_programs.rst @@ -1,7 +1,9 @@ install_programs ---------------- -Deprecated. Use the :command:`install(PROGRAMS)` command instead. +.. deprecated:: 3.0 + + Use the :command:`install(PROGRAMS)` command instead. This command has been superceded by the :command:`install` command. It is provided for compatibility with older CMake code. The ``FILES`` form is diff --git a/Help/command/install_targets.rst b/Help/command/install_targets.rst index 49ca69694..c9efdce67 100644 --- a/Help/command/install_targets.rst +++ b/Help/command/install_targets.rst @@ -1,7 +1,9 @@ install_targets --------------- -Deprecated. Use the :command:`install(TARGETS)` command instead. +.. deprecated:: 3.0 + + Use the :command:`install(TARGETS)` command instead. This command has been superceded by the :command:`install` command. It is provided for compatibility with older CMake code. diff --git a/Help/command/link_directories.rst b/Help/command/link_directories.rst index 5c64bc609..9cb8faa74 100644 --- a/Help/command/link_directories.rst +++ b/Help/command/link_directories.rst @@ -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. -:: +.. code-block:: cmake - 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. +Adds 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. diff --git a/Help/command/link_libraries.rst b/Help/command/link_libraries.rst index fd5dc3723..8665cb789 100644 --- a/Help/command/link_libraries.rst +++ b/Help/command/link_libraries.rst @@ -3,7 +3,7 @@ link_libraries Link libraries to all targets added later. -:: +.. code-block:: cmake link_libraries([item1 [item2 [...]]] [[debug|optimized|general] <item>] ...) diff --git a/Help/command/list.rst b/Help/command/list.rst index f6b75bc19..50bf417bf 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst @@ -3,66 +3,323 @@ list List operations. -:: +Synopsis +^^^^^^^^ + +.. parsed-literal:: + + `Reading`_ + list(`LENGTH`_ <list> <out-var>) + list(`GET`_ <list> <element index> [<index> ...] <out-var>) + list(`JOIN`_ <list> <glue> <out-var>) + list(`SUBLIST`_ <list> <begin> <length> <out-var>) + + `Search`_ + list(`FIND`_ <list> <value> <out-var>) + + `Modification`_ + list(`APPEND`_ <list> [<element>...]) + list(`FILTER`_ <list> {INCLUDE | EXCLUDE} REGEX <regex>) + list(`INSERT`_ <list> <index> [<element>...]) + list(`POP_BACK`_ <list> [<out-var>...]) + list(`POP_FRONT`_ <list> [<out-var>...]) + list(`PREPEND`_ <list> [<element>...]) + list(`REMOVE_ITEM`_ <list> <value>...) + list(`REMOVE_AT`_ <list> <index>...) + list(`REMOVE_DUPLICATES`_ <list>) + list(`TRANSFORM`_ <list> <ACTION> [...]) + + `Ordering`_ + list(`REVERSE`_ <list>) + list(`SORT`_ <list> [...]) + +Introduction +^^^^^^^^^^^^ + +The list subcommands ``APPEND``, ``INSERT``, ``FILTER``, ``PREPEND``, +``POP_BACK``, ``POP_FRONT``, ``REMOVE_AT``, ``REMOVE_ITEM``, +``REMOVE_DUPLICATES``, ``REVERSE`` and ``SORT`` may create +new values for the list within the current CMake variable scope. Similar to +the :command:`set` command, the LIST command creates new variable values in +the current scope, even if the list itself is actually defined in a parent +scope. To propagate the results of these operations upwards, use +:command:`set` with ``PARENT_SCOPE``, :command:`set` with +``CACHE INTERNAL``, or some other means of value propagation. + +.. note:: + + A list in cmake is a ``;`` separated group of strings. To create a + list the set command can be used. For example, ``set(var a b c d e)`` + creates a list with ``a;b;c;d;e``, and ``set(var "a b c d e")`` creates a + string or a list with one item in it. (Note macro arguments are not + variables, and therefore cannot be used in LIST commands.) + +.. note:: + + When specifying index values, if ``<element index>`` is 0 or greater, it + is indexed from the beginning of the list, with 0 representing the + first list element. If ``<element index>`` is -1 or lesser, it is indexed + from the end of the list, with -1 representing the last list element. + Be careful when counting with negative indices: they do not start from + 0. -0 is equivalent to 0, the first list element. + +Reading +^^^^^^^ + +.. _LENGTH: + +.. code-block:: cmake list(LENGTH <list> <output variable>) - list(GET <list> <element index> [<element index> ...] - <output variable>) + +Returns the list's length. + +.. _GET: + +.. code-block:: cmake + + list(GET <list> <element index> [<element index> ...] <output variable>) + +Returns the list of elements specified by indices from the list. + +.. _JOIN: + +.. code-block:: cmake + + list(JOIN <list> <glue> <output variable>) + +Returns a string joining all list's elements using the glue string. +To join multiple strings, which are not part of a list, use ``JOIN`` operator +from :command:`string` command. + +.. _SUBLIST: + +.. code-block:: cmake + + list(SUBLIST <list> <begin> <length> <output variable>) + +Returns a sublist of the given list. +If ``<length>`` is 0, an empty list will be returned. +If ``<length>`` is -1 or the list is smaller than ``<begin>+<length>`` then +the remaining elements of the list starting at ``<begin>`` will be returned. + +Search +^^^^^^ + +.. _FIND: + +.. code-block:: cmake + + list(FIND <list> <value> <output variable>) + +Returns the index of the element specified in the list or -1 +if it wasn't found. + +Modification +^^^^^^^^^^^^ + +.. _APPEND: + +.. code-block:: cmake + list(APPEND <list> [<element> ...]) + +Appends elements to the list. + +.. _FILTER: + +.. code-block:: cmake + list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>) - list(FIND <list> <value> <output variable>) + +Includes or removes items from the list that match the mode's pattern. +In ``REGEX`` mode, items will be matched against the given regular expression. + +For more information on regular expressions see also the +:command:`string` command. + +.. _INSERT: + +.. code-block:: cmake + list(INSERT <list> <element_index> <element> [<element> ...]) + +Inserts elements to the list to the specified location. + +.. _POP_BACK: + +.. code-block:: cmake + + list(POP_BACK <list> [<out-var>...]) + +If no variable name is given, removes exactly one element. Otherwise, +assign the last element's value to the given variable and removes it, +up to the last variable name given. + +.. _POP_FRONT: + +.. code-block:: cmake + + list(POP_FRONT <list> [<out-var>...]) + +If no variable name is given, removes exactly one element. Otherwise, +assign the first element's value to the given variable and removes it, +up to the last variable name given. + +.. _PREPEND: + +.. code-block:: cmake + + list(PREPEND <list> [<element> ...]) + +Insert elements to the 0th position in the list. + +.. _REMOVE_ITEM: + +.. code-block:: cmake + list(REMOVE_ITEM <list> <value> [<value> ...]) + +Removes all instances of the given items from the list. + +.. _REMOVE_AT: + +.. code-block:: cmake + list(REMOVE_AT <list> <index> [<index> ...]) + +Removes items at given indices from the list. + +.. _REMOVE_DUPLICATES: + +.. code-block:: cmake + list(REMOVE_DUPLICATES <list>) - list(REVERSE <list>) - list(SORT <list>) -``LENGTH`` will return a given list's length. +Removes duplicated items in the list. The relative order of items is preserved, +but if duplicates are encountered, only the first instance is preserved. -``GET`` will return list of elements specified by indices from the list. +.. _TRANSFORM: -``APPEND`` will append elements to the list. +.. code-block:: cmake -``FILTER`` will include or remove items from the list that match the -mode's pattern. -In ``REGEX`` mode, items will be matched against the given regular expression. -For more information on regular expressions see also the :command:`string` -command. + list(TRANSFORM <list> <ACTION> [<SELECTOR>] + [OUTPUT_VARIABLE <output variable>]) -``FIND`` will return the index of the element specified in the list or -1 -if it wasn't found. +Transforms the list by applying an action to all or, by specifying a +``<SELECTOR>``, to the selected elements of the list, storing the result +in-place or in the specified output variable. -``INSERT`` will insert elements to the list to the specified location. +.. note:: -``REMOVE_AT`` and ``REMOVE_ITEM`` will remove items from the list. The -difference is that ``REMOVE_ITEM`` will remove the given items, while -``REMOVE_AT`` will remove the items at the given indices. + The ``TRANSFORM`` sub-command does not change the number of elements in the + list. If a ``<SELECTOR>`` is specified, only some elements will be changed, + the other ones will remain the same as before the transformation. -``REMOVE_DUPLICATES`` will remove duplicated items in the list. +``<ACTION>`` specifies the action to apply to the elements of the list. +The actions have exactly the same semantics as sub-commands of the +:command:`string` command. ``<ACTION>`` must be one of the following: -``REVERSE`` reverses the contents of the list in-place. +``APPEND``, ``PREPEND``: Append, prepend specified value to each element of +the list. -``SORT`` sorts the list in-place alphabetically. + .. code-block:: cmake -The list subcommands ``APPEND``, ``INSERT``, ``FILTER``, ``REMOVE_AT``, -``REMOVE_ITEM``, ``REMOVE_DUPLICATES``, ``REVERSE`` and ``SORT`` may create new -values for the list within the current CMake variable scope. Similar to the -:command:`set` command, the LIST command creates new variable values in the -current scope, even if the list itself is actually defined in a parent -scope. To propagate the results of these operations upwards, use -:command:`set` with ``PARENT_SCOPE``, :command:`set` with -``CACHE INTERNAL``, or some other means of value propagation. + list(TRANSFORM <list> <APPEND|PREPEND> <value> ...) + +``TOUPPER``, ``TOLOWER``: Convert each element of the list to upper, lower +characters. + + .. code-block:: cmake + + list(TRANSFORM <list> <TOLOWER|TOUPPER> ...) + +``STRIP``: Remove leading and trailing spaces from each element of the +list. + + .. code-block:: cmake + + list(TRANSFORM <list> STRIP ...) + +``GENEX_STRIP``: Strip any +:manual:`generator expressions <cmake-generator-expressions(7)>` from each +element of the list. + + .. code-block:: cmake + + list(TRANSFORM <list> GENEX_STRIP ...) + +``REPLACE``: Match the regular expression as many times as possible and +substitute the replacement expression for the match for each element +of the list +(Same semantic as ``REGEX REPLACE`` from :command:`string` command). + + .. code-block:: cmake + + list(TRANSFORM <list> REPLACE <regular_expression> + <replace_expression> ...) + +``<SELECTOR>`` determines which elements of the list will be transformed. +Only one type of selector can be specified at a time. When given, +``<SELECTOR>`` must be one of the following: + +``AT``: Specify a list of indexes. + + .. code-block:: cmake + + list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...) + +``FOR``: Specify a range with, optionally, an increment used to iterate over +the range. + + .. code-block:: cmake + + list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...) + +``REGEX``: Specify a regular expression. Only elements matching the regular +expression will be transformed. + + .. code-block:: cmake + + list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...) + + +Ordering +^^^^^^^^ + +.. _REVERSE: + +.. code-block:: cmake + + list(REVERSE <list>) + +Reverses the contents of the list in-place. + +.. _SORT: + +.. code-block:: cmake + + 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: -NOTES: A list in cmake is a ``;`` separated group of strings. To create a -list the set command can be used. For example, ``set(var a b c d e)`` -creates a list with ``a;b;c;d;e``, and ``set(var "a b c d e")`` creates a -string or a list with one item in it. (Note macro arguments are not -variables, and therefore cannot be used in LIST commands.) - -When specifying index values, if ``<element index>`` is 0 or greater, it -is indexed from the beginning of the list, with 0 representing the -first list element. If ``<element index>`` is -1 or lesser, it is indexed -from the end of the list, with -1 representing the last list element. -Be careful when counting with negative indices: they do not start from -0. -0 is equivalent to 0, the first list element. +* ``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. diff --git a/Help/command/load_cache.rst b/Help/command/load_cache.rst index f1134472d..b89eb6177 100644 --- a/Help/command/load_cache.rst +++ b/Help/command/load_cache.rst @@ -3,21 +3,20 @@ load_cache Load in the values from another project's CMake cache. -:: +.. code-block:: cmake - load_cache(pathToCacheFile READ_WITH_PREFIX - prefix entry1...) + load_cache(pathToBuildDirectory READ_WITH_PREFIX prefix entry1...) -Read the cache and store the requested entries in variables with their +Reads the cache and store the requested entries in variables with their name prefixed with the given prefix. This only reads the values, and does not create entries in the local project's cache. -:: +.. code-block:: cmake - load_cache(pathToCacheFile [EXCLUDE entry1...] + load_cache(pathToBuildDirectory [EXCLUDE entry1...] [INCLUDE_INTERNALS entry1...]) -Load in the values from another cache and store them in the local +Loads in the values from another cache and store them in the local project's cache as internal entries. This is useful for a project that depends on another project built in a different tree. ``EXCLUDE`` option can be used to provide a list of entries to be excluded. diff --git a/Help/command/load_command.rst b/Help/command/load_command.rst index a1576e8b5..dc235994c 100644 --- a/Help/command/load_command.rst +++ b/Help/command/load_command.rst @@ -1,7 +1,7 @@ load_command ------------ -Disallowed. See CMake Policy :policy:`CMP0031`. +Disallowed since version 3.0. See CMake Policy :policy:`CMP0031`. Load a command into a running CMake. diff --git a/Help/command/macro.rst b/Help/command/macro.rst index 6bee69c73..05e5d79ac 100644 --- a/Help/command/macro.rst +++ b/Help/command/macro.rst @@ -1,27 +1,66 @@ macro ----- -Start recording a macro for later invocation as a command:: - - macro(<name> [arg1 [arg2 [arg3 ...]]]) - COMMAND1(ARGS ...) - COMMAND2(ARGS ...) - ... - endmacro(<name>) - -Define a macro named ``<name>`` that takes arguments named ``arg1``, -``arg2``, ``arg3``, (...). -Commands listed after macro, but before the matching -:command:`endmacro()`, are not invoked until the macro is invoked. -When it is invoked, the commands recorded in the macro are first -modified by replacing formal parameters (``${arg1}``) with the arguments -passed, and then invoked as normal commands. +Start recording a macro for later invocation as a command + +.. code-block:: cmake + + macro(<name> [<arg1> ...]) + <commands> + endmacro() + +Defines a macro named ``<name>`` that takes arguments named +``<arg1>``, ... Commands listed after macro, but before the +matching :command:`endmacro()`, are not executed until the macro +is invoked. + +Per legacy, the :command:`endmacro` command admits an optional +``<name>`` argument. If used, it must be a verbatim repeat of the +argument of the opening ``macro`` command. + +See the :command:`cmake_policy()` command documentation for the behavior +of policies inside macros. + +See the :ref:`Macro vs Function` section below for differences +between CMake macros and :command:`functions <function>`. + +Invocation +^^^^^^^^^^ + +The macro invocation is case-insensitive. A macro defined as + +.. code-block:: cmake + + macro(foo) + <commands> + endmacro() + +can be invoked through any of + +.. code-block:: cmake + + foo() + Foo() + FOO() + +and so on. However, it is strongly recommended to stay with the +case chosen in the macro definition. Typically macros use +all-lowercase names. + +Arguments +^^^^^^^^^ + +When a macro is invoked, the commands recorded in the macro are +first modified by replacing formal parameters (``${arg1}``, ...) +with the arguments passed, and then invoked as normal commands. + In addition to referencing the formal parameters you can reference the values ``${ARGC}`` which will be set to the number of arguments passed into the function as well as ``${ARGV0}``, ``${ARGV1}``, ``${ARGV2}``, ... which will have the actual values of the arguments passed in. This facilitates creating macros with optional arguments. -Additionally ``${ARGV}`` holds the list of all arguments given to the + +Furthermore, ``${ARGV}`` holds the list of all arguments given to the macro and ``${ARGN}`` holds the list of arguments past the last expected argument. Referencing to ``${ARGV#}`` arguments beyond ``${ARGC}`` have undefined @@ -29,48 +68,73 @@ behavior. Checking that ``${ARGC}`` is greater than ``#`` is the only way to ensure that ``${ARGV#}`` was passed to the function as an extra argument. -See the :command:`cmake_policy()` command documentation for the behavior -of policies inside macros. +.. _`Macro vs Function`: + +Macro vs Function +^^^^^^^^^^^^^^^^^ -Macro Argument Caveats -^^^^^^^^^^^^^^^^^^^^^^ +The ``macro`` command is very similar to the :command:`function` command. +Nonetheless, there are a few important differences. -Note that the parameters to a macro and values such as ``ARGN`` are -not variables in the usual CMake sense. They are string -replacements much like the C preprocessor would do with a macro. -Therefore you will NOT be able to use commands like:: +In a function, ``ARGN``, ``ARGC``, ``ARGV`` and ``ARGV0``, ``ARGV1``, ... +are true variables in the usual CMake sense. In a macro, they are not, +they are string replacements much like the C preprocessor would do +with a macro. This has a number of consequences, as explained in +the :ref:`Argument Caveats` section below. + +Another difference between macros and functions is the control flow. +A function is executed by transferring control from the calling +statement to the function body. A macro is executed as if the macro +body were pasted in place of the calling statement. This has the +consequence that a :command:`return()` in a macro body does not +just terminate execution of the macro; rather, control is returned +from the scope of the macro call. To avoid confusion, it is recommended +to avoid :command:`return()` in macros altogether. + +.. _`Argument Caveats`: + +Argument Caveats +^^^^^^^^^^^^^^^^ + +Since ``ARGN``, ``ARGC``, ``ARGV``, ``ARGV0`` etc. are not variables, +you will NOT be able to use commands like + +.. code-block:: cmake if(ARGV1) # ARGV1 is not a variable if(DEFINED ARGV2) # ARGV2 is not a variable if(ARGC GREATER 2) # ARGC is not a variable foreach(loop_var IN LISTS ARGN) # ARGN is not a variable -In the first case, you can use ``if(${ARGV1})``. -In the second and third case, the proper way to check if an optional -variable was passed to the macro is to use ``if(${ARGC} GREATER 2)``. -In the last case, you can use ``foreach(loop_var ${ARGN})`` but this -will skip empty arguments. -If you need to include them, you can use:: +In the first case, you can use ``if(${ARGV1})``. In the second and +third case, the proper way to check if an optional variable was +passed to the macro is to use ``if(${ARGC} GREATER 2)``. In the +last case, you can use ``foreach(loop_var ${ARGN})`` but this will +skip empty arguments. If you need to include them, you can use + +.. code-block:: cmake set(list_var "${ARGN}") foreach(loop_var IN LISTS list_var) Note that if you have a variable with the same name in the scope from which the macro is called, using unreferenced names will use the -existing variable instead of the arguments. For example:: +existing variable instead of the arguments. For example: + +.. code-block:: cmake - macro(_BAR) + macro(bar) foreach(arg IN LISTS ARGN) - [...] + <commands> endforeach() endmacro() - function(_FOO) - _bar(x y z) + function(foo) + bar(x y z) endfunction() - _foo(a b c) + foo(a b c) -Will loop over ``a;b;c`` and not over ``x;y;z`` as one might be expecting. +Will loop over ``a;b;c`` and not over ``x;y;z`` as one might have expected. If you want true CMake variables and/or better CMake scope control you should look at the function command. diff --git a/Help/command/make_directory.rst b/Help/command/make_directory.rst index 27ecf5194..8469b0a96 100644 --- a/Help/command/make_directory.rst +++ b/Help/command/make_directory.rst @@ -1,7 +1,9 @@ make_directory -------------- -Deprecated. Use the :command:`file(MAKE_DIRECTORY)` command instead. +.. deprecated:: 3.0 + + Use the :command:`file(MAKE_DIRECTORY)` command instead. :: diff --git a/Help/command/mark_as_advanced.rst b/Help/command/mark_as_advanced.rst index c3f94fc48..5712fb420 100644 --- a/Help/command/mark_as_advanced.rst +++ b/Help/command/mark_as_advanced.rst @@ -3,17 +3,22 @@ mark_as_advanced Mark cmake cached variables as advanced. -:: +.. code-block:: cmake - mark_as_advanced([CLEAR|FORCE] VAR [VAR2 ...]) + mark_as_advanced([CLEAR|FORCE] <var1> ...) -Mark the named cached variables as advanced. An advanced variable -will not be displayed in any of the cmake GUIs unless the show -advanced option is on. If ``CLEAR`` is the first argument advanced -variables are changed back to unadvanced. If ``FORCE`` is the first -argument, then the variable is made advanced. If neither ``FORCE`` nor -``CLEAR`` is specified, new values will be marked as advanced, but if the -variable already has an advanced/non-advanced state, it will not be -changed. +Sets the advanced/non-advanced state of the named +cached variables. -It does nothing in script mode. +An advanced variable will not be displayed in any +of the cmake GUIs unless the ``show advanced`` option is on. +In script mode, the advanced/non-advanced state has no effect. + +If the keyword ``CLEAR`` is given +then advanced variables are changed back to unadvanced. +If the keyword ``FORCE`` is given +then the variables are made advanced. +If neither ``FORCE`` nor ``CLEAR`` is specified, +new values will be marked as advanced, but if a +variable already has an advanced/non-advanced state, +it will not be changed. diff --git a/Help/command/math.rst b/Help/command/math.rst index f99dc3db3..ddb1ec63c 100644 --- a/Help/command/math.rst +++ b/Help/command/math.rst @@ -1,14 +1,37 @@ math ---- -Mathematical expressions. +Evaluate a mathematical expression. -:: +.. code-block:: cmake - math(EXPR <output-variable> <math-expression>) + math(EXPR <variable> "<expression>" [OUTPUT_FORMAT <format>]) -``EXPR`` evaluates mathematical expression and returns result in the -output variable. Example mathematical expression is ``5 * (10 + 13)``. +Evaluates a mathematical ``<expression>`` and sets ``<variable>`` to the +resulting value. The result of the expression must be representable as a +64-bit signed integer. + +The mathematical expression must be given as a string (i.e. enclosed in +double quotation marks). An example is ``"5 * (10 + 13)"``. Supported operators are ``+``, ``-``, ``*``, ``/``, ``%``, ``|``, ``&``, -``^``, ``~``, ``<<``, ``>>``, and ``(...)``. They have the same meaning -as they do in C code. +``^``, ``~``, ``<<``, ``>>``, and ``(...)``; they have the same meaning +as in C code. + +Hexadecimal numbers are recognized when prefixed with ``0x``, as in C code. + +The result is formatted according to the option ``OUTPUT_FORMAT``, +where ``<format>`` is one of + +``HEXADECIMAL`` + Hexadecimal notation as in C code, i. e. starting with "0x". +``DECIMAL`` + Decimal notation. Which is also used if no ``OUTPUT_FORMAT`` option + is specified. + + +For example + +.. code-block:: cmake + + math(EXPR value "100 * 0xA" OUTPUT_FORMAT DECIMAL) # value is set to "1000" + math(EXPR value "100 * 0xA" OUTPUT_FORMAT HEXADECIMAL) # value is set to "0x3e8" diff --git a/Help/command/message.rst b/Help/command/message.rst index 04c62fdff..c614286c1 100644 --- a/Help/command/message.rst +++ b/Help/command/message.rst @@ -3,30 +3,67 @@ message Display a message to the user. -:: +.. code-block:: cmake message([<mode>] "message to display" ...) The optional ``<mode>`` keyword determines the type of message: -:: - - (none) = Important information - STATUS = Incidental information - WARNING = CMake Warning, continue processing - AUTHOR_WARNING = CMake Warning (dev), continue processing - SEND_ERROR = CMake Error, continue processing, - but skip generation - FATAL_ERROR = CMake Error, stop processing and generation - DEPRECATION = CMake Deprecation Error or Warning if variable - CMAKE_ERROR_DEPRECATED or CMAKE_WARN_DEPRECATED - is enabled, respectively, else no message. - -The CMake command-line tool displays STATUS messages on stdout and all -other message types on stderr. The CMake GUI displays all messages in -its log area. The interactive dialogs (ccmake and CMakeSetup) show -STATUS messages one at a time on a status line and other messages in -interactive pop-up boxes. +``FATAL_ERROR`` + CMake Error, stop processing and generation. + +``SEND_ERROR`` + CMake Error, continue processing, but skip generation. + +``WARNING`` + CMake Warning, continue processing. + +``AUTHOR_WARNING`` + CMake Warning (dev), continue processing. + +``DEPRECATION`` + CMake Deprecation Error or Warning if variable + :variable:`CMAKE_ERROR_DEPRECATED` or :variable:`CMAKE_WARN_DEPRECATED` + is enabled, respectively, else no message. + +(none) or ``NOTICE`` + Important message printed to stderr to attract user's attention. + +``STATUS`` + The main interesting messages that project users might be interested in. + Ideally these should be concise, no more than a single line, but still + informative. + +``VERBOSE`` + Detailed informational messages intended for project users. These messages + should provide additional details that won't be of interest in most cases, + but which may be useful to those building the project when they want deeper + insight into what's happening. + +``DEBUG`` + Detailed informational messages intended for developers working on the + project itself as opposed to users who just want to build it. These messages + will not typically be of interest to other users building the project and + will often be closely related to internal implementation details. + +``TRACE`` + Fine-grained messages with very low-level implementation details. Messages + using this log level would normally only be temporary and would expect to be + removed before releasing the project, packaging up the files, etc. + +The CMake command-line tool displays ``STATUS`` to ``TRACE`` messages on stdout +with the message preceded by two hyphens and a space. All other message types +are sent to stderr and are not prefixed with hyphens. The +:manual:`CMake GUI <cmake-gui(1)>` displays all messages in its log area. +The :manual:`curses interface <ccmake(1)>` shows ``STATUS`` to ``TRACE`` +messages one at a time on a status line and other messages in an +interactive pop-up box. The ``--log-level`` command-line option to each of +these tools can be used to control which messages will be shown. + +Messages of log levels ``NOTICE`` and below will also have each line preceded +by the content of the :variable:`CMAKE_MESSAGE_INDENT` variable (converted to +a single string by concatenating its list items). For ``STATUS`` to ``TRACE`` +messages, this indenting content will be inserted after the hyphens. CMake Warning and Error message text displays using a simple markup language. Non-indented text is formatted in line-wrapped paragraphs diff --git a/Help/command/option.rst b/Help/command/option.rst index 91cd0a778..8956307c5 100644 --- a/Help/command/option.rst +++ b/Help/command/option.rst @@ -1,15 +1,16 @@ option ------ -Provides an option that the user can optionally select. +Provide an option that the user can optionally select. -:: +.. code-block:: cmake - option(<option_variable> "help string describing option" - [initial value]) + option(<variable> "<help_text>" [value]) -Provide an option for the user to select as ``ON`` or ``OFF``. If no -initial value is provided, ``OFF`` is used. +Provides an option for the user to select as ``ON`` or ``OFF``. +If no initial ``<value>`` is provided, ``OFF`` is used. +If ``<variable>`` 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`. diff --git a/Help/command/output_required_files.rst b/Help/command/output_required_files.rst index 5e1355763..b3a6e8653 100644 --- a/Help/command/output_required_files.rst +++ b/Help/command/output_required_files.rst @@ -1,7 +1,7 @@ output_required_files --------------------- -Disallowed. See CMake Policy :policy:`CMP0032`. +Disallowed since version 3.0. See CMake Policy :policy:`CMP0032`. Approximate C preprocessor dependency scanning. @@ -14,6 +14,6 @@ more advanced scanner. output_required_files(srcfile outputfile) Outputs a list of all the source files that are required by the -specified srcfile. This list is written into outputfile. This is -similar to writing out the dependencies for srcfile except that it -jumps from .h files into .cxx, .c and .cpp files if possible. +specified ``srcfile``. This list is written into ``outputfile``. This is +similar to writing out the dependencies for ``srcfile`` except that it +jumps from ``.h`` files into ``.cxx``, ``.c`` and ``.cpp`` files if possible. diff --git a/Help/command/project.rst b/Help/command/project.rst index 139f69c9b..395145619 100644 --- a/Help/command/project.rst +++ b/Help/command/project.rst @@ -1,69 +1,130 @@ project ------- -Set a name, version, and enable languages for the entire project. +Set the name of the project. + +Synopsis +^^^^^^^^ .. code-block:: cmake - project(<PROJECT-NAME> [LANGUAGES] [<language-name>...]) + project(<PROJECT-NAME> [<language-name>...]) project(<PROJECT-NAME> [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]] [DESCRIPTION <project-description-string>] + [HOMEPAGE_URL <url-string>] [LANGUAGES <language-name>...]) -Sets the name of the project and stores the name in the -:variable:`PROJECT_NAME` variable. Additionally this sets variables +Sets the name of the project, and stores it in the variable +:variable:`PROJECT_NAME`. When called from the top-level +``CMakeLists.txt`` also stores the project name in the +variable :variable:`CMAKE_PROJECT_NAME`. + +Also sets the variables * :variable:`PROJECT_SOURCE_DIR`, :variable:`<PROJECT-NAME>_SOURCE_DIR` * :variable:`PROJECT_BINARY_DIR`, :variable:`<PROJECT-NAME>_BINARY_DIR` -If ``VERSION`` is specified, given components must be non-negative integers. -If ``VERSION`` is not specified, the default version is the empty string. -The ``VERSION`` option may not be used unless policy :policy:`CMP0048` is -set to ``NEW``. - -The :command:`project()` command stores the version number and its components -in variables - -* :variable:`PROJECT_VERSION`, - :variable:`<PROJECT-NAME>_VERSION` -* :variable:`PROJECT_VERSION_MAJOR`, - :variable:`<PROJECT-NAME>_VERSION_MAJOR` -* :variable:`PROJECT_VERSION_MINOR`, - :variable:`<PROJECT-NAME>_VERSION_MINOR` -* :variable:`PROJECT_VERSION_PATCH`, - :variable:`<PROJECT-NAME>_VERSION_PATCH` -* :variable:`PROJECT_VERSION_TWEAK`, - :variable:`<PROJECT-NAME>_VERSION_TWEAK` - -Variables corresponding to unspecified versions are set to the empty string -(if policy :policy:`CMP0048` is set to ``NEW``). - -If optional ``DESCRIPTION`` is given, then additional :variable:`PROJECT_DESCRIPTION` -variable will be set to its argument. The argument must be a string with short -description of the project (only a few words). - -Optionally you can specify which languages your project supports. -Example languages are ``C``, ``CXX`` (i.e. C++), ``Fortran``, etc. -By default ``C`` and ``CXX`` are enabled if no language options are -given. Specify language ``NONE``, or use the ``LANGUAGES`` keyword -and list no languages, to skip enabling any languages. - -If a variable exists called :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, -the file pointed to by that variable will be included as the last step of the -project command. +Further variables are set by the optional arguments described in the following. +If any of these arguments is not used, then the corresponding variables are +set to the empty string. + +Options +^^^^^^^ + +The options are: + +``VERSION <version>`` + Optional; may not be used unless policy :policy:`CMP0048` is + set to ``NEW``. + + Takes a ``<version>`` argument composed of non-negative integer components, + i.e. ``<major>[.<minor>[.<patch>[.<tweak>]]]``, + and sets the variables + + * :variable:`PROJECT_VERSION`, + :variable:`<PROJECT-NAME>_VERSION` + * :variable:`PROJECT_VERSION_MAJOR`, + :variable:`<PROJECT-NAME>_VERSION_MAJOR` + * :variable:`PROJECT_VERSION_MINOR`, + :variable:`<PROJECT-NAME>_VERSION_MINOR` + * :variable:`PROJECT_VERSION_PATCH`, + :variable:`<PROJECT-NAME>_VERSION_PATCH` + * :variable:`PROJECT_VERSION_TWEAK`, + :variable:`<PROJECT-NAME>_VERSION_TWEAK`. + + When the ``project()`` command is called from the top-level ``CMakeLists.txt``, + then the version is also stored in the variable :variable:`CMAKE_PROJECT_VERSION`. + +``DESCRIPTION <project-description-string>`` + Optional. + Sets the variables + + * :variable:`PROJECT_DESCRIPTION`, :variable:`<PROJECT-NAME>_DESCRIPTION` + + to ``<project-description-string>``. + It is recommended that this description is a relatively short string, + usually no more than a few words. + + When the ``project()`` command is called from the top-level ``CMakeLists.txt``, + then the description is also stored in the variable :variable:`CMAKE_PROJECT_DESCRIPTION`. + +``HOMEPAGE_URL <url-string>`` + Optional. + Sets the variables + + * :variable:`PROJECT_HOMEPAGE_URL`, :variable:`<PROJECT-NAME>_HOMEPAGE_URL` + + to ``<url-string>``, which should be the canonical home URL for the project. + + When the ``project()`` command is called from the top-level ``CMakeLists.txt``, + then the URL also is stored in the variable :variable:`CMAKE_PROJECT_HOMEPAGE_URL`. + +``LANGUAGES <language-name>...`` + Optional. + Can also be specified without ``LANGUAGES`` keyword per the first, short signature. + + Selects which programming languages are needed to build the project. + Supported languages include ``C``, ``CXX`` (i.e. C++), ``CUDA``, + ``OBJC`` (i.e. Objective-C), ``OBJCXX``, ``Fortran``, and ``ASM``. + By default ``C`` and ``CXX`` are enabled if no language options are given. + Specify language ``NONE``, or use the ``LANGUAGES`` keyword and list no languages, + to skip enabling any languages. + + If enabling ``ASM``, list it last so that CMake can check whether + compilers for other languages like ``C`` work for assembly too. + +The variables set through the ``VERSION``, ``DESCRIPTION`` and ``HOMEPAGE_URL`` +options are intended for use as default values in package metadata and documentation. + +Code Injection +^^^^^^^^^^^^^^ + +If the :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` variable is set, the file +pointed to by that variable will be included as the first step of the +``project()`` command. + +If the :variable:`CMAKE_PROJECT_INCLUDE` or +:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE` variables are set, the files +they point to will be included as the last step of the ``project()`` command. +If both are set, then :variable:`CMAKE_PROJECT_INCLUDE` will be included before +:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`. + +Usage +^^^^^ The top-level ``CMakeLists.txt`` file for a project must contain a -literal, direct call to the :command:`project` command; loading one +literal, direct call to the ``project()`` command; loading one through the :command:`include` command is not sufficient. If no such -call exists CMake will implicitly add one to the top that enables the -default languages (``C`` and ``CXX``). +call exists, CMake will issue a warning and pretend there is a +``project(Project)`` at the top to enable the default languages +(``C`` and ``CXX``). .. note:: - Call the :command:`cmake_minimum_required` command at the beginning - of the top-level ``CMakeLists.txt`` file even before calling the - ``project()`` command. It is important to establish version and - policy settings before invoking other commands whose behavior they - may affect. See also policy :policy:`CMP0000`. + Call the ``project()`` command near the top of the top-level + ``CMakeLists.txt``, but *after* calling :command:`cmake_minimum_required`. + It is important to establish version and policy settings before invoking + other commands whose behavior they may affect. + See also policy :policy:`CMP0000`. diff --git a/Help/command/qt_wrap_cpp.rst b/Help/command/qt_wrap_cpp.rst index 3843bf5e9..ce11c2d09 100644 --- a/Help/command/qt_wrap_cpp.rst +++ b/Help/command/qt_wrap_cpp.rst @@ -1,12 +1,23 @@ qt_wrap_cpp ----------- -Create Qt Wrappers. +.. deprecated:: 3.14 -:: + This command was originally added to support Qt 3 before the + :command:`add_custom_command()` command was sufficiently mature. The + :module:`FindQt4` module provides the ``qt4_wrap_cpp()`` macro, which + should be used instead for Qt 4 projects. For projects using Qt 5 or + later, use the equivalent macro provided by Qt itself (e.g. Qt 5 provides + ``qt5_wrap_cpp()``). - qt_wrap_cpp(resultingLibraryName DestName - SourceLists ...) +Manually create Qt Wrappers. -Produce moc files for all the .h files listed in the SourceLists. The +.. code-block:: cmake + + qt_wrap_cpp(resultingLibraryName DestName SourceLists ...) + +Produces moc files for all the .h files listed in the SourceLists. The moc files will be added to the library using the ``DestName`` source list. + +Consider updating the project to use the :prop_tgt:`AUTOMOC` target property +instead for a more automated way of invoking the ``moc`` tool. diff --git a/Help/command/qt_wrap_ui.rst b/Help/command/qt_wrap_ui.rst index f731ed9a8..efbbc5472 100644 --- a/Help/command/qt_wrap_ui.rst +++ b/Help/command/qt_wrap_ui.rst @@ -1,14 +1,26 @@ qt_wrap_ui ---------- -Create Qt user interfaces Wrappers. +.. deprecated:: 3.14 -:: + This command was originally added to support Qt 3 before the + :command:`add_custom_command()` command was sufficiently mature. The + :module:`FindQt4` module provides the ``qt4_wrap_ui()`` macro, which + should be used instead for Qt 4 projects. For projects using Qt 5 or + later, use the equivalent macro provided by Qt itself (e.g. Qt 5 provides + ``qt5_wrap_ui()``). + +Manually create Qt user interfaces Wrappers. + +.. code-block:: cmake qt_wrap_ui(resultingLibraryName HeadersDestName SourcesDestName SourceLists ...) -Produce .h and .cxx files for all the .ui files listed in the +Produces .h and .cxx files for all the .ui files listed in the ``SourceLists``. The .h files will be added to the library using the ``HeadersDestNamesource`` list. The .cxx files will be added to the library using the ``SourcesDestNamesource`` list. + +Consider updating the project to use the :prop_tgt:`AUTOUIC` target property +instead for a more automated way of invoking the ``uic`` tool. diff --git a/Help/command/remove.rst b/Help/command/remove.rst index 462827796..543d01671 100644 --- a/Help/command/remove.rst +++ b/Help/command/remove.rst @@ -1,7 +1,9 @@ remove ------ -Deprecated. Use the :command:`list(REMOVE_ITEM)` command instead. +.. deprecated:: 3.0 + + Use the :command:`list(REMOVE_ITEM)` command instead. :: diff --git a/Help/command/remove_definitions.rst b/Help/command/remove_definitions.rst index ea189181c..faad16dcb 100644 --- a/Help/command/remove_definitions.rst +++ b/Help/command/remove_definitions.rst @@ -1,9 +1,9 @@ remove_definitions ------------------ -Removes -D define flags added by :command:`add_definitions`. +Remove -D define flags added by :command:`add_definitions`. -:: +.. code-block:: cmake remove_definitions(-DFOO -DBAR ...) diff --git a/Help/command/return.rst b/Help/command/return.rst index e49fb3c8d..830992c25 100644 --- a/Help/command/return.rst +++ b/Help/command/return.rst @@ -3,7 +3,7 @@ return Return from a file, directory or function. -:: +.. code-block:: cmake return() @@ -14,5 +14,6 @@ and control is returned to the including file. If it is encountered in a file which is not included by another file, e.g. a ``CMakeLists.txt``, control is returned to the parent directory if there is one. If return is called in a function, control is returned to the caller of the function. -Note that a macro is not a function and does not handle return like a -function does. + +Note that a :command:`macro <macro>`, unlike a :command:`function <function>`, +is expanded in place and therefore cannot handle ``return()``. diff --git a/Help/command/separate_arguments.rst b/Help/command/separate_arguments.rst index 47982a503..fbca859f2 100644 --- a/Help/command/separate_arguments.rst +++ b/Help/command/separate_arguments.rst @@ -1,33 +1,43 @@ separate_arguments ------------------ -Parse space-separated arguments into a semicolon-separated list. +Parse command-line arguments into a semicolon-separated list. -:: +.. code-block:: cmake - separate_arguments(<var> <NATIVE|UNIX|WINDOWS>_COMMAND "<args>") + separate_arguments(<variable> <mode> <args>) -Parses a UNIX- or Windows-style command-line string "<args>" and -stores a semicolon-separated list of the arguments in ``<var>``. The -entire command line must be given in one "<args>" argument. +Parses a space-separated string ``<args>`` into a list of items, +and stores this list in semicolon-separated standard form in ``<variable>``. -The ``UNIX_COMMAND`` mode separates arguments by unquoted whitespace. It -recognizes both single-quote and double-quote pairs. A backslash -escapes the next literal character (``\"`` is ``"``); there are no special -escapes (``\n`` is just ``n``). +This function is intended for parsing command-line arguments. +The entire command line must be passed as one string in the +argument ``<args>``. -The ``WINDOWS_COMMAND`` mode parses a Windows command-line using the same -syntax the runtime library uses to construct argv at startup. It -separates arguments by whitespace that is not double-quoted. -Backslashes are literal unless they precede double-quotes. See the -MSDN article `Parsing C Command-Line Arguments`_ for details. +The exact parsing rules depend on the operating system. +They are specified by the ``<mode>`` argument which must +be one of the following keywords: -The ``NATIVE_COMMAND`` mode parses a Windows command-line if the host -system is Windows, and a UNIX command-line otherwise. +``UNIX_COMMAND`` + Arguments are separated by by unquoted whitespace. + Both single-quote and double-quote pairs are respected. + A backslash escapes the next literal character (``\"`` is ``"``); + there are no special escapes (``\n`` is just ``n``). + +``WINDOWS_COMMAND`` + A Windows command-line is parsed using the same + syntax the runtime library uses to construct argv at startup. It + separates arguments by whitespace that is not double-quoted. + Backslashes are literal unless they precede double-quotes. See the + MSDN article `Parsing C Command-Line Arguments`_ for details. + +``NATIVE_COMMAND`` + Proceeds as in ``WINDOWS_COMMAND`` mode if the host system is Windows. + Otherwise proceeds as in ``UNIX_COMMAND`` mode. .. _`Parsing C Command-Line Arguments`: https://msdn.microsoft.com/library/a1y7w461.aspx -:: +.. code-block:: cmake separate_arguments(<var>) diff --git a/Help/command/set.rst b/Help/command/set.rst index b24ebefeb..c0e02e246 100644 --- a/Help/command/set.rst +++ b/Help/command/set.rst @@ -8,18 +8,18 @@ and cache entries. Signatures of this command that specify a ``<value>...`` placeholder expect zero or more arguments. Multiple arguments will be joined as -a :ref:`;-list <CMake Language Lists>` to form the actual variable +a :ref:`semicolon-separated list <CMake Language Lists>` to form the actual variable value to be set. Zero arguments will cause normal variables to be unset. See the :command:`unset` command to unset variables explicitly. Set Normal Variable ^^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake set(<variable> <value>... [PARENT_SCOPE]) -Set the given ``<variable>`` in the current function or directory scope. +Sets the given ``<variable>`` in the current function or directory scope. If the ``PARENT_SCOPE`` option is given the variable will be set in the scope above the current scope. Each new directory or function @@ -32,11 +32,11 @@ undefined and if it had a value, it is still that value). Set Cache Entry ^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake set(<variable> <value>... CACHE <type> <docstring> [FORCE]) -Set the given cache ``<variable>`` (cache entry). Since cache entries +Sets the given cache ``<variable>`` (cache entry). Since cache entries are meant to provide user-settable values this does not overwrite existing cache entries by default. Use the ``FORCE`` option to overwrite existing entries. @@ -84,8 +84,21 @@ current working directory and convert it to an absolute path. Set Environment Variable ^^^^^^^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake - set(ENV{<variable>} <value>...) + set(ENV{<variable>} [<value>]) -Set the current process environment ``<variable>`` to the given value. +Sets an :manual:`Environment Variable <cmake-env-variables(7)>` +to the given value. +Subsequent calls of ``$ENV{<variable>}`` will return this new value. + +This command affects only the current CMake process, not the process +from which CMake was called, nor the system environment at large, +nor the environment of subsequent build or test processes. + +If no argument is given after ``ENV{<variable>}`` or if ``<value>`` is +an empty string, then this command will clear any existing value of the +environment variable. + +Arguments after ``<value>`` are ignored. If extra arguments are found, +then an author warning is issued. diff --git a/Help/command/set_directory_properties.rst b/Help/command/set_directory_properties.rst index e485fce0a..f02a8e6c7 100644 --- a/Help/command/set_directory_properties.rst +++ b/Help/command/set_directory_properties.rst @@ -1,12 +1,15 @@ set_directory_properties ------------------------ -Set a property of the directory. +Set properties of the current directory and subdirectories. -:: +.. code-block:: cmake - set_directory_properties(PROPERTIES prop1 value1 prop2 value2) + 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. +Sets properties of the current directory and its subdirectories in key-value pairs. + +See also the :command:`set_property(DIRECTORY)` command. + +See :ref:`Directory Properties` for the list of properties known to CMake +and their individual documentation for the behavior of each property. diff --git a/Help/command/set_property.rst b/Help/command/set_property.rst index 5ed788e4a..ec08c8f99 100644 --- a/Help/command/set_property.rst +++ b/Help/command/set_property.rst @@ -3,37 +3,40 @@ set_property Set a named property in a given scope. -:: - - set_property(<GLOBAL | - DIRECTORY [dir] | - TARGET [target1 [target2 ...]] | - SOURCE [src1 [src2 ...]] | - INSTALL [file1 [file2 ...]] | - TEST [test1 [test2 ...]] | - CACHE [entry1 [entry2 ...]]> +.. code-block:: cmake + + set_property(<GLOBAL | + DIRECTORY [<dir>] | + TARGET [<target1> ...] | + SOURCE [<src1> ...] | + INSTALL [<file1> ...] | + TEST [<test1> ...] | + CACHE [<entry1> ...] > [APPEND] [APPEND_STRING] - PROPERTY <name> [value1 [value2 ...]]) + PROPERTY <name> [value1 ...]) -Set one property on zero or more objects of a scope. The first -argument determines the scope in which the property is set. It must -be one of the following: +Sets one property on zero or more objects of a scope. + +The first argument determines the scope in which the property is set. +It must be one of the following: ``GLOBAL`` Scope is unique and does not accept a name. ``DIRECTORY`` - Scope defaults to the current directory but another - directory (already processed by CMake) may be named by full or - relative path. + Scope defaults to the current directory but another directory + (already processed by CMake) may be named by full or relative path. + See also the :command:`set_directory_properties` command. ``TARGET`` Scope may name zero or more existing targets. + See also the :command:`set_target_properties` command. ``SOURCE`` Scope may name zero or more source files. Note that source file properties are visible only to targets added in the same - directory (CMakeLists.txt). + directory (``CMakeLists.txt``). + See also the :command:`set_source_files_properties` command. ``INSTALL`` Scope may name zero or more installed file paths. @@ -45,7 +48,7 @@ be one of the following: Path components have to be separated by forward slashes, must be normalized and are case sensitive. - To reference the installation prefix itself with a relative path use ".". + To reference the installation prefix itself with a relative path use ``.``. Currently installed file properties are only defined for the WIX generator where the given paths are relative @@ -53,17 +56,24 @@ be one of the following: ``TEST`` Scope may name zero or more existing tests. + See also the :command:`set_tests_properties` command. ``CACHE`` Scope must name zero or more cache existing entries. The required ``PROPERTY`` option is immediately followed by the name of the property to set. Remaining arguments are used to compose the -property value in the form of a semicolon-separated list. If the -``APPEND`` option is given the list is appended to any existing property -value. If the ``APPEND_STRING`` option is given the string is append to any -existing property value as string, i.e. it results in a longer string -and not a list of strings. +property value in the form of a semicolon-separated list. + +If the ``APPEND`` option is given the list is appended to any existing +property value. If the ``APPEND_STRING`` option is given the string is +appended to any existing property value as string, i.e. it results in a +longer string and not a list of strings. When using ``APPEND`` or +``APPEND_STRING`` with a property defined to support ``INHERITED`` +behavior (see :command:`define_property`), no inheriting occurs when +finding the initial value to append to. If the property is not already +directly set in the nominated scope, the command will behave as though +``APPEND`` or ``APPEND_STRING`` had not been given. See the :manual:`cmake-properties(7)` manual for a list of properties in each scope. diff --git a/Help/command/set_source_files_properties.rst b/Help/command/set_source_files_properties.rst index b4904e8d0..ab95d7094 100644 --- a/Help/command/set_source_files_properties.rst +++ b/Help/command/set_source_files_properties.rst @@ -3,13 +3,17 @@ set_source_files_properties Source files can have properties that affect how they are built. -:: +.. code-block:: cmake set_source_files_properties([file1 [file2 [...]]] PROPERTIES prop1 value1 [prop2 value2 [...]]) -Set properties associated with source files using a key/value paired -list. See :ref:`Source File Properties` for the list of properties known +Sets properties associated with source files using a key/value paired +list. + +See also the :command:`set_property(SOURCE)` command. + +See :ref:`Source File Properties` for the list of properties known to CMake. Source file properties are visible only to targets added -in the same directory (CMakeLists.txt). +in the same directory (``CMakeLists.txt``). diff --git a/Help/command/set_target_properties.rst b/Help/command/set_target_properties.rst index b894eace3..597be231a 100644 --- a/Help/command/set_target_properties.rst +++ b/Help/command/set_target_properties.rst @@ -3,16 +3,18 @@ set_target_properties Targets can have properties that affect how they are built. -:: +.. code-block:: cmake set_target_properties(target1 target2 ... PROPERTIES prop1 value1 prop2 value2 ...) -Set properties on a target. The syntax for the command is to list all -the files you want to change, and then provide the values you want to +Sets properties on targets. The syntax for the command is to list all +the targets you want to change, and then provide the values you want to set next. You can use any prop value pair you want and extract it later with the :command:`get_property` or :command:`get_target_property` command. +See also the :command:`set_property(TARGET)` command. + See :ref:`Target Properties` for the list of properties known to CMake. diff --git a/Help/command/set_tests_properties.rst b/Help/command/set_tests_properties.rst index 3efb1653e..9bc94ae38 100644 --- a/Help/command/set_tests_properties.rst +++ b/Help/command/set_tests_properties.rst @@ -3,12 +3,15 @@ set_tests_properties Set a property of the tests. -:: +.. code-block:: cmake set_tests_properties(test1 [test2...] PROPERTIES prop1 value1 prop2 value2) -Set a property for the tests. If the test is not found, CMake +Sets a property for the tests. If the test is not found, CMake will report an error. :manual:`Generator expressions <cmake-generator-expressions(7)>` will be -expanded the same as supported by the test's :command:`add_test` call. See -:ref:`Test Properties` for the list of properties known to CMake. +expanded the same as supported by the test's :command:`add_test` call. + +See also the :command:`set_property(TEST)` command. + +See :ref:`Test Properties` for the list of properties known to CMake. diff --git a/Help/command/site_name.rst b/Help/command/site_name.rst index e17c1ee68..1bcaeada0 100644 --- a/Help/command/site_name.rst +++ b/Help/command/site_name.rst @@ -3,6 +3,6 @@ site_name Set the given variable to the name of the computer. -:: +.. code-block:: cmake site_name(variable) diff --git a/Help/command/source_group.rst b/Help/command/source_group.rst index 938ca40f2..6623c9837 100644 --- a/Help/command/source_group.rst +++ b/Help/command/source_group.rst @@ -4,7 +4,7 @@ source_group Define a grouping for source files in IDE project generation. There are two different signatures to create source groups. -:: +.. code-block:: cmake source_group(<name> [FILES <src>...] [REGULAR_EXPRESSION <regex>]) source_group(TREE <root> [PREFIX <prefix>] [FILES <src>...]) diff --git a/Help/command/string.rst b/Help/command/string.rst index 4f0c45c29..81a206112 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -1,81 +1,120 @@ string ------ -.. only:: html - - .. contents:: - String operations. +Synopsis +^^^^^^^^ + +.. parsed-literal:: + + `Search and Replace`_ + string(`FIND`_ <string> <substring> <out-var> [...]) + string(`REPLACE`_ <match-string> <replace-string> <out-var> <input>...) + + `Regular Expressions`_ + string(`REGEX MATCH`_ <match-regex> <out-var> <input>...) + string(`REGEX MATCHALL`_ <match-regex> <out-var> <input>...) + string(`REGEX REPLACE`_ <match-regex> <replace-expr> <out-var> <input>...) + + `Manipulation`_ + string(`APPEND`_ <string-var> [<input>...]) + string(`PREPEND`_ <string-var> [<input>...]) + string(`CONCAT`_ <out-var> [<input>...]) + string(`JOIN`_ <glue> <out-var> [<input>...]) + string(`TOLOWER`_ <string> <out-var>) + string(`TOUPPER`_ <string> <out-var>) + string(`LENGTH`_ <string> <out-var>) + string(`SUBSTRING`_ <string> <begin> <length> <out-var>) + string(`STRIP`_ <string> <out-var>) + string(`GENEX_STRIP`_ <string> <out-var>) + string(`REPEAT`_ <string> <count> <out-var>) + + `Comparison`_ + string(`COMPARE`_ <op> <string1> <string2> <out-var>) + + `Hashing`_ + string(`\<HASH\> <HASH_>`_ <out-var> <input>) + + `Generation`_ + string(`ASCII`_ <number>... <out-var>) + string(`CONFIGURE`_ <string> <out-var> [...]) + string(`MAKE_C_IDENTIFIER`_ <string> <out-var>) + string(`RANDOM`_ [<option>...] <out-var>) + string(`TIMESTAMP`_ <out-var> [<format string>] [UTC]) + string(`UUID`_ <out-var> ...) + Search and Replace ^^^^^^^^^^^^^^^^^^ -FIND -"""" +.. _FIND: -:: +.. code-block:: cmake - string(FIND <string> <substring> <output variable> [REVERSE]) + string(FIND <string> <substring> <output_variable> [REVERSE]) -Return the position where the given substring was found in -the supplied string. If the ``REVERSE`` flag was used, the command will +Return the position where the given ``<substring>`` was found in +the supplied ``<string>``. If the ``REVERSE`` flag was used, the command will search for the position of the last occurrence of the specified -substring. If the substring is not found, a position of -1 is returned. +``<substring>``. If the ``<substring>`` is not found, a position of -1 is +returned. -REPLACE -""""""" +The ``string(FIND)`` subcommand treats all strings as ASCII-only characters. +The index stored in ``<output_variable>`` will also be counted in bytes, +so strings containing multi-byte characters may lead to unexpected results. -:: +.. _REPLACE: + +.. code-block:: cmake string(REPLACE <match_string> - <replace_string> <output variable> + <replace_string> <output_variable> <input> [<input>...]) -Replace all occurrences of ``match_string`` in the input -with ``replace_string`` and store the result in the output. +Replace all occurrences of ``<match_string>`` in the ``<input>`` +with ``<replace_string>`` and store the result in the ``<output_variable>``. Regular Expressions ^^^^^^^^^^^^^^^^^^^ -REGEX MATCH -""""""""""" +.. _`REGEX MATCH`: -:: +.. code-block:: cmake string(REGEX MATCH <regular_expression> - <output variable> <input> [<input>...]) + <output_variable> <input> [<input>...]) -Match the regular expression once and store the match in the output variable. +Match the ``<regular_expression>`` once and store the match in the +``<output_variable>``. All ``<input>`` arguments are concatenated before matching. -REGEX MATCHALL -"""""""""""""" +.. _`REGEX MATCHALL`: -:: +.. code-block:: cmake string(REGEX MATCHALL <regular_expression> - <output variable> <input> [<input>...]) + <output_variable> <input> [<input>...]) -Match the regular expression as many times as possible and store the matches -in the output variable as a list. +Match the ``<regular_expression>`` as many times as possible and store the +matches in the ``<output_variable>`` as a list. All ``<input>`` arguments are concatenated before matching. -REGEX REPLACE -""""""""""""" +.. _`REGEX REPLACE`: -:: +.. code-block:: cmake string(REGEX REPLACE <regular_expression> - <replace_expression> <output variable> + <replacement_expression> <output_variable> <input> [<input>...]) -Match the regular expression as many times as possible and substitute the -replacement expression for the match in the output. +Match the ``<regular_expression>`` as many times as possible and substitute +the ``<replacement_expression>`` for the match in the output. All ``<input>`` arguments are concatenated before matching. -The replace expression may refer to paren-delimited subexpressions of the -match using ``\1``, ``\2``, ..., ``\9``. Note that two backslashes (``\\1``) -are required in CMake code to get a backslash through argument parsing. +The ``<replacement_expression>`` may refer to parenthesis-delimited +subexpressions of the match using ``\1``, ``\2``, ..., ``\9``. Note that +two backslashes (``\\1``) are required in CMake code to get a backslash +through argument parsing. .. _`Regex Specification`: @@ -90,6 +129,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 ``[^ ]`` @@ -120,114 +164,161 @@ 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 ^^^^^^^^^^^^ -APPEND -"""""" +.. _APPEND: -:: +.. code-block:: cmake - string(APPEND <string variable> [<input>...]) + string(APPEND <string_variable> [<input>...]) -Append all the input arguments to the string. +Append all the ``<input>`` arguments to the string. -CONCAT -"""""" +.. _PREPEND: -:: +.. code-block:: cmake - string(CONCAT <output variable> [<input>...]) + string(PREPEND <string_variable> [<input>...]) -Concatenate all the input arguments together and store -the result in the named output variable. +Prepend all the ``<input>`` arguments to the string. -TOLOWER -""""""" +.. _CONCAT: -:: +.. code-block:: cmake - string(TOLOWER <string1> <output variable>) + string(CONCAT <output_variable> [<input>...]) -Convert string to lower characters. +Concatenate all the ``<input>`` arguments together and store +the result in the named ``<output_variable>``. -TOUPPER -""""""" +.. _JOIN: -:: +.. code-block:: cmake - string(TOUPPER <string1> <output variable>) + string(JOIN <glue> <output_variable> [<input>...]) -Convert string to upper characters. +Join all the ``<input>`` arguments together using the ``<glue>`` +string and store the result in the named ``<output_variable>``. -LENGTH -"""""" +To join a list's elements, prefer to use the ``JOIN`` operator +from the :command:`list` command. This allows for the elements to have +special characters like ``;`` in them. -:: +.. _TOLOWER: - string(LENGTH <string> <output variable>) +.. code-block:: cmake -Store in an output variable a given string's length. + string(TOLOWER <string> <output_variable>) -SUBSTRING -""""""""" +Convert ``<string>`` to lower characters. -:: +.. _TOUPPER: + +.. code-block:: cmake + + string(TOUPPER <string> <output_variable>) + +Convert ``<string>`` to upper characters. + +.. _LENGTH: + +.. code-block:: cmake + + string(LENGTH <string> <output_variable>) + +Store in an ``<output_variable>`` a given string's length in bytes. +Note that this means if ``<string>`` contains multi-byte characters, the +result stored in ``<output_variable>`` will *not* be the number of characters. + +.. _SUBSTRING: + +.. code-block:: cmake - string(SUBSTRING <string> <begin> <length> <output variable>) + string(SUBSTRING <string> <begin> <length> <output_variable>) -Store in an output variable a substring of a given string. If length is -``-1`` the remainder of the string starting at begin will be returned. -If string is shorter than length then end of string is used instead. +Store in an ``<output_variable>`` a substring of a given ``<string>``. If +``<length>`` is ``-1`` the remainder of the string starting at ``<begin>`` +will be returned. If ``<string>`` is shorter than ``<length>`` then the +end of the string is used instead. + +Both ``<begin>`` and ``<length>`` are counted in bytes, so care must +be exercised if ``<string>`` could contain multi-byte characters. .. note:: - CMake 3.1 and below reported an error if length pointed past - the end of string. + CMake 3.1 and below reported an error if ``<length>`` pointed past + the end of ``<string>``. -STRIP -""""" +.. _STRIP: -:: +.. code-block:: cmake - string(STRIP <string> <output variable>) + string(STRIP <string> <output_variable>) -Store in an output variable a substring of a given string with leading and -trailing spaces removed. +Store in an ``<output_variable>`` a substring of a given ``<string>`` with +leading and trailing spaces removed. -GENEX_STRIP -""""""""""" +.. _GENEX_STRIP: -:: +.. code-block:: cmake - string(GENEX_STRIP <input string> <output variable>) + string(GENEX_STRIP <string> <output_variable>) Strip any :manual:`generator expressions <cmake-generator-expressions(7)>` -from the ``input string`` and store the result in the ``output variable``. +from the input ``<string>`` and store the result in the ``<output_variable>``. + +.. _REPEAT: + +.. code-block:: cmake + + string(REPEAT <string> <count> <output_variable>) + +Produce the output string as the input ``<string>`` repeated ``<count>`` times. Comparison ^^^^^^^^^^ -:: +.. _COMPARE: + +.. code-block:: cmake - string(COMPARE LESS <string1> <string2> <output variable>) - string(COMPARE GREATER <string1> <string2> <output variable>) - string(COMPARE EQUAL <string1> <string2> <output variable>) - string(COMPARE NOTEQUAL <string1> <string2> <output variable>) - string(COMPARE LESS_EQUAL <string1> <string2> <output variable>) - string(COMPARE GREATER_EQUAL <string1> <string2> <output variable>) + string(COMPARE LESS <string1> <string2> <output_variable>) + string(COMPARE GREATER <string1> <string2> <output_variable>) + string(COMPARE EQUAL <string1> <string2> <output_variable>) + string(COMPARE NOTEQUAL <string1> <string2> <output_variable>) + string(COMPARE LESS_EQUAL <string1> <string2> <output_variable>) + string(COMPARE GREATER_EQUAL <string1> <string2> <output_variable>) -Compare the strings and store true or false in the output variable. +Compare the strings and store true or false in the ``<output_variable>``. .. _`Supported Hash Algorithms`: Hashing ^^^^^^^ -:: +.. _`HASH`: - string(<HASH> <output variable> <input>) +.. code-block:: cmake -Compute a cryptographic hash of the input string. + string(<HASH> <output_variable> <input>) + +Compute a cryptographic hash of the ``<input>`` string. The supported ``<HASH>`` algorithm names are: ``MD5`` @@ -254,56 +345,63 @@ The supported ``<HASH>`` algorithm names are: Generation ^^^^^^^^^^ -ASCII -""""" +.. _ASCII: -:: +.. code-block:: cmake - string(ASCII <number> [<number> ...] <output variable>) + string(ASCII <number> [<number> ...] <output_variable>) Convert all numbers into corresponding ASCII characters. -CONFIGURE -""""""""" +.. _CONFIGURE: -:: +.. code-block:: cmake - string(CONFIGURE <string1> <output variable> + string(CONFIGURE <string> <output_variable> [@ONLY] [ESCAPE_QUOTES]) -Transform a string like :command:`configure_file` transforms a file. +Transform a ``<string>`` like :command:`configure_file` transforms a file. -RANDOM -"""""" +.. _MAKE_C_IDENTIFIER: -:: +.. code-block:: cmake + + string(MAKE_C_IDENTIFIER <string> <output_variable>) + +Convert each non-alphanumeric character in the input ``<string>`` to an +underscore and store the result in the ``<output_variable>``. If the first +character of the ``<string>`` is a digit, an underscore will also be prepended +to the result. + +.. _RANDOM: + +.. code-block:: cmake string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>] - [RANDOM_SEED <seed>] <output variable>) + [RANDOM_SEED <seed>] <output_variable>) -Return a random string of given length consisting of -characters from the given alphabet. Default length is 5 characters +Return a random string of given ``<length>`` consisting of +characters from the given ``<alphabet>``. Default length is 5 characters and default alphabet is all numbers and upper and lower case letters. If an integer ``RANDOM_SEED`` is given, its value will be used to seed the random number generator. -TIMESTAMP -""""""""" +.. _TIMESTAMP: -:: +.. code-block:: cmake - string(TIMESTAMP <output variable> [<format string>] [UTC]) + string(TIMESTAMP <output_variable> [<format_string>] [UTC]) Write a string representation of the current date -and/or time to the output variable. +and/or time to the ``<output_variable>``. -Should the command be unable to obtain a timestamp the output variable -will be set to the empty string "". +If the command is unable to obtain a timestamp, the ``<output_variable>`` +will be set to the empty string ``""``. The optional ``UTC`` flag requests the current date/time representation to be in Coordinated Universal Time (UTC) rather than local time. -The optional ``<format string>`` may contain the following format +The optional ``<format_string>`` may contain the following format specifiers: :: @@ -315,6 +413,7 @@ specifiers: %j The day of the current year (001-366). %m The month of the current year (01-12). %b Abbreviated month name (e.g. Oct). + %B Full month name (e.g. October). %M The minute of the current hour (00-59). %s Seconds since midnight (UTC) 1-Jan-1970 (UNIX time). %S The second of the current minute. @@ -322,46 +421,39 @@ specifiers: %U The week number of the current year (00-53). %w The day of the current week. 0 is Sunday. (0-6) %a Abbreviated weekday name (e.g. Fri). + %A Full weekday name (e.g. Friday). %y The last two digits of the current year (00-99) %Y The current year. Unknown format specifiers will be ignored and copied to the output as-is. -If no explicit ``<format string>`` is given it will default to: +If no explicit ``<format_string>`` is given, it will default to: :: %Y-%m-%dT%H:%M:%S for local time. %Y-%m-%dT%H:%M:%SZ for UTC. - -:: - - string(MAKE_C_IDENTIFIER <input string> <output variable>) - -Write a string which can be used as an identifier in C. - .. note:: If the ``SOURCE_DATE_EPOCH`` environment variable is set, its value will be used instead of the current time. See https://reproducible-builds.org/specs/source-date-epoch/ for details. -UUID -"""" +.. _UUID: -:: +.. code-block:: cmake - string(UUID <output variable> NAMESPACE <namespace> NAME <name> + string(UUID <output_variable> NAMESPACE <namespace> NAME <name> TYPE <MD5|SHA1> [UPPER]) -Create a univerally unique identifier (aka GUID) as per RFC4122 +Create a universally unique identifier (aka GUID) as per RFC4122 based on the hash of the combined values of ``<namespace>`` (which itself has to be a valid UUID) and ``<name>``. The hash algorithm can be either ``MD5`` (Version 3 UUID) or ``SHA1`` (Version 5 UUID). A UUID has the format ``xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`` -where each `x` represents a lower case hexadecimal character. -Where required an uppercase representation can be requested +where each ``x`` represents a lower case hexadecimal character. +Where required, an uppercase representation can be requested with the optional ``UPPER`` flag. diff --git a/Help/command/subdir_depends.rst b/Help/command/subdir_depends.rst index 5676c8f40..0c1b3c1ce 100644 --- a/Help/command/subdir_depends.rst +++ b/Help/command/subdir_depends.rst @@ -1,7 +1,7 @@ subdir_depends -------------- -Disallowed. See CMake Policy :policy:`CMP0029`. +Disallowed since version 3.0. See CMake Policy :policy:`CMP0029`. Does nothing. diff --git a/Help/command/subdirs.rst b/Help/command/subdirs.rst index 43b87d4d7..530951bd1 100644 --- a/Help/command/subdirs.rst +++ b/Help/command/subdirs.rst @@ -1,7 +1,9 @@ subdirs ------- -Deprecated. Use the :command:`add_subdirectory` command instead. +.. deprecated:: 3.0 + + Use the :command:`add_subdirectory` command instead. Add a list of subdirectories to the build. diff --git a/Help/command/target_compile_definitions.rst b/Help/command/target_compile_definitions.rst index 8bd323375..9e9c69093 100644 --- a/Help/command/target_compile_definitions.rst +++ b/Help/command/target_compile_definitions.rst @@ -3,26 +3,37 @@ target_compile_definitions Add compile definitions to a target. -:: +.. code-block:: cmake target_compile_definitions(<target> <INTERFACE|PUBLIC|PRIVATE> [items1...] [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) -Specify compile definitions to use when compiling a given ``<target>``. The +Specifies compile definitions to use when compiling 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:`Imported Target <Imported Targets>`. +:ref:`ALIAS target <Alias Targets>`. 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:`COMPILE_DEFINITIONS` property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the -:prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` property of ``<target>``. The -following arguments specify compile definitions. Repeated calls for the +:prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` property of ``<target>``. +(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items.) +The following arguments specify compile definitions. Repeated calls for the same ``<target>`` append items in the order called. Arguments to ``target_compile_definitions`` 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. + +Any leading ``-D`` on an item will be removed. Empty items are ignored. +For example, the following are all equivalent: + +.. code-block:: cmake + + target_compile_definitions(foo PUBLIC FOO) + target_compile_definitions(foo PUBLIC -DFOO) # -D removed + target_compile_definitions(foo PUBLIC "" FOO) # "" ignored + target_compile_definitions(foo PUBLIC -D FOO) # -D becomes "", then ignored diff --git a/Help/command/target_compile_features.rst b/Help/command/target_compile_features.rst index b66a4ec16..9271cd56c 100644 --- a/Help/command/target_compile_features.rst +++ b/Help/command/target_compile_features.rst @@ -3,11 +3,11 @@ target_compile_features Add expected compiler features to a target. -:: +.. code-block:: cmake target_compile_features(<target> <PRIVATE|PUBLIC|INTERFACE> <feature> [...]) -Specify compiler features required when compiling a given target. If the +Specifies compiler features required when compiling a given target. If the feature is not listed in the :variable:`CMAKE_C_COMPILE_FEATURES` variable or :variable:`CMAKE_CXX_COMPILE_FEATURES` variable, then an error will be reported by CMake. If the use of the feature requires @@ -18,12 +18,13 @@ The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to specify the scope of the features. ``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`COMPILE_FEATURES` property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the -:prop_tgt:`INTERFACE_COMPILE_FEATURES` property of ``<target>``. Repeated -calls for the same ``<target>`` append items. +:prop_tgt:`INTERFACE_COMPILE_FEATURES` property of ``<target>``. +(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items.) +Repeated calls for the same ``<target>`` append items. The named ``<target>`` must have been created by a command such as -:command:`add_executable` or :command:`add_library` and must not be -an ``IMPORTED`` target. +:command:`add_executable` or :command:`add_library` and must not be an +:ref:`ALIAS target <Alias Targets>`. Arguments to ``target_compile_features`` may use "generator expressions" with the syntax ``$<...>``. diff --git a/Help/command/target_compile_options.rst b/Help/command/target_compile_options.rst index 73e01e7f8..47e7d86f8 100644 --- a/Help/command/target_compile_options.rst +++ b/Help/command/target_compile_options.rst @@ -3,35 +3,46 @@ target_compile_options Add compile options to a target. -:: +.. code-block:: cmake target_compile_options(<target> [BEFORE] <INTERFACE|PUBLIC|PRIVATE> [items1...] [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) -Specify compile options to use when compiling 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:`IMPORTED Target <Imported Targets>`. If ``BEFORE`` is specified, -the content will be prepended to the property instead of being appended. +Adds options to the :prop_tgt:`COMPILE_OPTIONS` or +:prop_tgt:`INTERFACE_COMPILE_OPTIONS` target properties. These options +are used when compiling the given ``<target>``, which 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>`. -This command can be used to add any options, but -alternative commands exist to add preprocessor definitions -(:command:`target_compile_definitions` and :command:`add_definitions`) or -include directories (:command:`target_include_directories` and -:command:`include_directories`). See documentation of the -:prop_dir:`directory <COMPILE_OPTIONS>` and -:prop_tgt:`target <COMPILE_OPTIONS>` ``COMPILE_OPTIONS`` properties. +Arguments +^^^^^^^^^ + +If ``BEFORE`` is specified, the content will be prepended to the property +instead of being appended. 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:`COMPILE_OPTIONS` property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the -:prop_tgt:`INTERFACE_COMPILE_OPTIONS` property of ``<target>``. The -following arguments specify compile options. Repeated calls for the same +:prop_tgt:`INTERFACE_COMPILE_OPTIONS` property of ``<target>``. +(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items.) +The following arguments specify compile options. Repeated calls for the same ``<target>`` append items in the order called. Arguments to ``target_compile_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:: OPTIONS_SHELL.txt + +See Also +^^^^^^^^ + +This command can be used to add any options. However, for adding +preprocessor definitions and include directories it is recommended +to use the more specific commands :command:`target_compile_definitions` +and :command:`target_include_directories`. + +For directory-wide settings, there is the command :command:`add_compile_options`. diff --git a/Help/command/target_include_directories.rst b/Help/command/target_include_directories.rst index 30ec2cb27..660e15c9b 100644 --- a/Help/command/target_include_directories.rst +++ b/Help/command/target_include_directories.rst @@ -3,16 +3,16 @@ target_include_directories Add include directories to a target. -:: +.. code-block:: cmake target_include_directories(<target> [SYSTEM] [BEFORE] <INTERFACE|PUBLIC|PRIVATE> [items1...] [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) -Specify include directories to use when compiling a given target. +Specifies include directories to use when compiling 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 -:prop_tgt:`IMPORTED` target. +:ref:`ALIAS target <Alias Targets>`. If ``BEFORE`` is specified, the content will be prepended to the property instead of being appended. @@ -21,9 +21,9 @@ 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:`INCLUDE_DIRECTORIES` property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the -:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` -property of ``<target>``. The following arguments specify include -directories. +:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` property of ``<target>``. +(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items.) +The following arguments specify include directories. Specified include directories may be absolute paths or relative paths. Repeated calls for the same <target> append items in the order called. If diff --git a/Help/command/target_link_directories.rst b/Help/command/target_link_directories.rst new file mode 100644 index 000000000..76da94dc1 --- /dev/null +++ b/Help/command/target_link_directories.rst @@ -0,0 +1,55 @@ +target_link_directories +----------------------- + +Add link directories to a target. + +.. code-block:: cmake + + target_link_directories(<target> [BEFORE] + <INTERFACE|PUBLIC|PRIVATE> [items1...] + [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) + +Specifies 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``). diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst index 30d69f266..c2e7e8ac9 100644 --- a/Help/command/target_link_libraries.rst +++ b/Help/command/target_link_libraries.rst @@ -14,13 +14,19 @@ Overview ^^^^^^^^ This command has several signatures as detailed in subsections below. -All of them have the general form:: +All of them have the general form + +.. code-block:: cmake 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`. -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 @@ -39,6 +45,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. @@ -48,7 +57,7 @@ Each ``<item>`` may be: as when a shared library is detected to have no ``SONAME`` field. See policy :policy:`CMP0060` for discussion of another case. - If the library file is in a Mac OSX framework, the ``Headers`` directory + If the library file is in a macOS framework, the ``Headers`` directory of the framework will also be processed as a :ref:`usage requirement <Target Usage Requirements>`. This has the same effect as passing the framework directory as an include directory. @@ -58,9 +67,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 @@ -69,10 +84,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:`semicolon-separated 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 @@ -83,23 +116,21 @@ 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake target_link_libraries(<target> <PRIVATE|PUBLIC|INTERFACE> <item>... @@ -116,7 +147,7 @@ used for linking ``<target>``. Libraries for both a Target and its Dependents ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake target_link_libraries(<target> <item>...) @@ -134,7 +165,7 @@ exclusively by this signature private. Libraries for a Target and/or its Dependents (Legacy) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake target_link_libraries(<target> <LINK_PRIVATE|LINK_PUBLIC> <lib>... @@ -156,7 +187,7 @@ made part of the :prop_tgt:`INTERFACE_LINK_LIBRARIES`. If policy Libraries for Dependents Only (Legacy) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake target_link_libraries(<target> LINK_INTERFACE_LIBRARIES <item>...) @@ -182,6 +213,70 @@ is not ``NEW``, they are also appended to the ``general`` (or without any keyword) are treated as if specified for both ``debug`` and ``optimized``. +Linking Object Libraries +^^^^^^^^^^^^^^^^^^^^^^^^ + +:ref:`Object Libraries` may be used as the ``<target>`` (first) argument +of ``target_link_libraries`` to specify dependencies of their sources +on other libraries. For example, the code + +.. code-block:: cmake + + add_library(A SHARED a.c) + target_compile_definitions(A PUBLIC A) + + add_library(obj OBJECT obj.c) + target_compile_definitions(obj PUBLIC OBJ) + target_link_libraries(obj PUBLIC A) + +compiles ``obj.c`` with ``-DA -DOBJ`` and establishes usage requirements +for ``obj`` that propagate to its dependents. + +Normal libraries and executables may link to :ref:`Object Libraries` +to get their objects and usage requirements. Continuing the above +example, the code + +.. code-block:: cmake + + add_library(B SHARED b.c) + target_link_libraries(B PUBLIC obj) + +compiles ``b.c`` with ``-DA -DOBJ``, creates shared library ``B`` +with object files from ``b.c`` and ``obj.c``, and links ``B`` to ``A``. +Furthermore, the code + +.. code-block:: cmake + + add_executable(main main.c) + target_link_libraries(main B) + +compiles ``main.c`` with ``-DA -DOBJ`` and links executable ``main`` +to ``B`` and ``A``. The object library's usage requirements are +propagated transitively through ``B``, but its object files are not. + +:ref:`Object Libraries` may "link" to other object libraries to get +usage requirements, but since they do not have a link step nothing +is done with their object files. Continuing from the above example, +the code: + +.. code-block:: cmake + + add_library(obj2 OBJECT obj2.c) + target_link_libraries(obj2 PUBLIC obj) + + add_executable(main2 main2.c) + target_link_libraries(main2 obj2) + +compiles ``obj2.c`` with ``-DA -DOBJ``, creates executable ``main2`` +with object files from ``main2.c`` and ``obj2.c``, and links ``main2`` +to ``A``. + +In other words, when :ref:`Object Libraries` appear in a target's +:prop_tgt:`INTERFACE_LINK_LIBRARIES` property they will be +treated as :ref:`Interface Libraries`, but when they appear in +a target's :prop_tgt:`LINK_LIBRARIES` property their object files +will be included in the link too. + Cyclic Dependencies of Static Libraries ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Help/command/target_link_options.rst b/Help/command/target_link_options.rst new file mode 100644 index 000000000..b5abbc476 --- /dev/null +++ b/Help/command/target_link_options.rst @@ -0,0 +1,48 @@ +target_link_options +------------------- + +Add options to the link step for an executable, shared library or module +library target. + +.. code-block:: cmake + + target_link_options(<target> [BEFORE] + <INTERFACE|PUBLIC|PRIVATE> [items1...] + [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) + +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>`. + +This command can be used to add any link options, but alternative commands +exist to add libraries (:command:`target_link_libraries` or +:command:`link_libraries`). See documentation of the +:prop_dir:`directory <LINK_OPTIONS>` and +:prop_tgt:`target <LINK_OPTIONS>` ``LINK_OPTIONS`` properties. + +.. note:: + + This command cannot be used to add options for static library targets, + since they do not use a linker. To add archiver or MSVC librarian flags, + see the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property. + +If ``BEFORE`` is specified, the content will be prepended to the property +instead of being appended. + +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:: OPTIONS_SHELL.txt + +.. include:: LINK_OPTIONS_LINKER.txt diff --git a/Help/command/target_precompile_headers.rst b/Help/command/target_precompile_headers.rst new file mode 100644 index 000000000..569c7eb11 --- /dev/null +++ b/Help/command/target_precompile_headers.rst @@ -0,0 +1,124 @@ +target_precompile_headers +------------------------- + +Add a list of header files to precompile. + +Precompiling header files can speed up compilation by creating a partially +processed version of some header files, and then using that version during +compilations rather than repeatedly parsing the original headers. + +Main Form +^^^^^^^^^ + +.. code-block:: cmake + + target_precompile_headers(<target> + <INTERFACE|PUBLIC|PRIVATE> [header1...] + [<INTERFACE|PUBLIC|PRIVATE> [header2...] ...]) + +The command adds header files to the :prop_tgt:`PRECOMPILE_HEADERS` and/or +:prop_tgt:`INTERFACE_PRECOMPILE_HEADERS` target properties of ``<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>`. + +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:`PRECOMPILE_HEADERS` property of +``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the +:prop_tgt:`INTERFACE_PRECOMPILE_HEADERS` property of ``<target>`` +(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items). +Repeated calls for the same ``<target>`` will append items in the order called. + +Projects should generally avoid using ``PUBLIC`` or ``INTERFACE`` for targets +that will be :ref:`exported <install(EXPORT)>`, or they should at least use +the ``$<BUILD_INTERFACE:...>`` generator expression to prevent precompile +headers from appearing in an installed exported target. Consumers of a target +should typically be in control of what precompile headers they use, not have +precompile headers forced on them by the targets being consumed (since +precompile headers are not typically usage requirements). A notable exception +to this is where an :ref:`interface library <Interface Libraries>` is created +to define a commonly used set of precompile headers in one place and then other +targets link to that interface library privately. In this case, the interface +library exists specifically to propagate the precompile headers to its +consumers and the consumer is effectively still in control, since it decides +whether to link to the interface library or not. + +The list of header files is used to generate a header file named +``cmake_pch.h|xx`` which is used to generate the precompiled header file +(``.pch``, ``.gch``, ``.pchi``) artifact. The ``cmake_pch.h|xx`` header +file will be force included (``-include`` for GCC, ``/FI`` for MSVC) to +all source files, so sources do not need to have ``#include "pch.h"``. + +Header file names specified with angle brackets (e.g. ``<unordered_map>``) or +explicit double quotes (escaped for the :manual:`cmake-language(7)`, +e.g. ``[["other_header.h"]]``) will be treated as is, and include directories +must be available for the compiler to find them. Other header file names +(e.g. ``project_header.h``) are interpreted as being relative to the current +source directory (e.g. :variable:`CMAKE_CURRENT_SOURCE_DIR`) and will be +included by absolute path. + +Arguments to ``target_precompile_headers()`` may use "generator expressions" +with the syntax ``$<...>``. +See the :manual:`cmake-generator-expressions(7)` manual for available +expressions. See the :manual:`cmake-compile-features(7)` manual for +information on compile features and a list of supported compilers. +The ``$<COMPILE_LANGUAGE:...>`` generator expression is particularly +useful for specifying a language-specific header to precompile for +only one language (e.g. ``CXX`` and not ``C``). For example: + +.. code-block:: cmake + + target_precompile_headers(myTarget + PUBLIC + project_header.h + "$<$<COMPILE_LANGUAGE:CXX>:cxx_only.h>" + PRIVATE + [["other_header.h"]] + <unordered_map> + ) + +When specifying angle brackets inside a :manual:`generator expression +<cmake-generator-expressions(7)>`, be sure to encode the closing ``>`` +as ``$<ANGLE-R>``. For example: + +.. code-block:: cmake + + target_precompile_headers(mylib PRIVATE + "$<$<COMPILE_LANGUAGE:C>:<stddef.h$<ANGLE-R>>" + "$<$<COMPILE_LANGUAGE:CXX>:<cstddef$<ANGLE-R>>" + ) + + +Reusing Precompile Headers +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The command also supports a second signature which can be used to specify that +one target re-uses a precompiled header file artefact from another target +instead of generating its own: + +.. code-block:: cmake + + target_precompile_headers(<target> REUSE_FROM <other_target>) + +This form sets the :prop_tgt:`PRECOMPILE_HEADERS_REUSE_FROM` property to +``<other_target>`` and adds a dependency such that ``<target>`` will depend +on ``<other_target>``. CMake will halt with an error if the +:prop_tgt:`PRECOMPILE_HEADERS` property of ``<target>`` is already set when +the ``REUSE_FROM`` form is used. + +.. note:: + + The ``REUSE_FROM`` form requires the same set of compiler options, + compiler flags and compiler definitions for both ``<target>`` and + ``<other_target>``. Some compilers (e.g. GCC) may issue a warning if the + precompiled header file cannot be used (``-Winvalid-pch``). + +See Also +^^^^^^^^ + +To disable precompile headers for specific targets, see the +:prop_tgt:`DISABLE_PRECOMPILE_HEADERS` target property. + +To prevent precompile headers from being used when compiling a specific +source file, see the :prop_sf:`SKIP_PRECOMPILE_HEADERS` source file property. diff --git a/Help/command/target_sources.rst b/Help/command/target_sources.rst index d6f148d23..27e737bf0 100644 --- a/Help/command/target_sources.rst +++ b/Help/command/target_sources.rst @@ -3,26 +3,32 @@ target_sources Add sources to a target. -:: +.. code-block:: cmake target_sources(<target> <INTERFACE|PUBLIC|PRIVATE> [items1...] [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) -Specify sources to use when compiling a given target. The +Specifies 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:`IMPORTED Target <Imported Targets>`. +:ref:`ALIAS target <Alias Targets>`. 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:`SOURCES` property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the -:prop_tgt:`INTERFACE_SOURCES` property of ``<target>``. The -following arguments specify sources. Repeated calls for the same +:prop_tgt:`INTERFACE_SOURCES` property of ``<target>``. +(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items.) +The following arguments specify sources. Repeated calls for the same ``<target>`` append items in the order called. 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. diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst index 66ea3d7f2..edbf92ce6 100644 --- a/Help/command/try_compile.rst +++ b/Help/command/try_compile.rst @@ -10,14 +10,14 @@ Try building some code. Try Compiling Whole Projects ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake - try_compile(RESULT_VAR <bindir> <srcdir> + try_compile(<resultVar> <bindir> <srcdir> <projectName> [<targetName>] [CMAKE_FLAGS <flags>...] [OUTPUT_VARIABLE <var>]) Try building a project. The success or failure of the ``try_compile``, -i.e. ``TRUE`` or ``FALSE`` respectively, is returned in ``RESULT_VAR``. +i.e. ``TRUE`` or ``FALSE`` respectively, is returned in ``<resultVar>``. In this form, ``<srcdir>`` should contain a complete CMake project with a ``CMakeLists.txt`` file and all sources. The ``<bindir>`` and ``<srcdir>`` @@ -28,11 +28,12 @@ below for the meaning of other options. Try Compiling Source Files ^^^^^^^^^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake - try_compile(RESULT_VAR <bindir> <srcfile|SOURCES srcfile...> + try_compile(<resultVar> <bindir> <srcfile|SOURCES srcfile...> [CMAKE_FLAGS <flags>...] [COMPILE_DEFINITIONS <defs>...] + [LINK_OPTIONS <options>...] [LINK_LIBRARIES <libs>...] [OUTPUT_VARIABLE <var>] [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]] @@ -41,18 +42,27 @@ Try Compiling Source Files [<LANG>_EXTENSIONS <bool>] ) -Try building an executable from one or more source files. The success or -failure of the ``try_compile``, i.e. ``TRUE`` or ``FALSE`` respectively, is -returned in ``RESULT_VAR``. +Try building an executable or static library from one or more source files +(which one is determined by the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` +variable). The success or failure of the ``try_compile``, i.e. ``TRUE`` or +``FALSE`` respectively, is returned in ``<resultVar>``. -In this form the user need only supply one or more source files that include a -definition for ``main``. CMake will create a ``CMakeLists.txt`` file to build -the source(s) as an executable that looks something like this:: +In this form, one or more source files must be provided. If +:variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is unset or is set to ``EXECUTABLE``, +the sources must include a definition for ``main`` and CMake will create a +``CMakeLists.txt`` file to build the source(s) as an executable. +If :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is set to ``STATIC_LIBRARY``, +a static library will be built instead and no definition for ``main`` is +required. For an executable, the generated ``CMakeLists.txt`` file would +contain something like the following: + +.. code-block:: cmake add_definitions(<expanded COMPILE_DEFINITIONS from caller>) include_directories(${INCLUDE_DIRECTORIES}) link_directories(${LINK_DIRECTORIES}) add_executable(cmTryCompileExec <srcfile>...) + target_link_options(cmTryCompileExec PRIVATE <LINK_OPTIONS from caller>) target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES}) The options are: @@ -65,11 +75,11 @@ The options are: are used. ``COMPILE_DEFINITIONS <defs>...`` - Specify ``-Ddefinition`` arguments to pass to ``add_definitions`` + Specify ``-Ddefinition`` arguments to pass to :command:`add_definitions` in the generated test project. ``COPY_FILE <fileName>`` - Copy the linked executable to the given ``<fileName>``. + Copy the built executable or static library to the given ``<fileName>``. ``COPY_FILE_ERROR <var>`` Use after ``COPY_FILE`` to capture into variable ``<var>`` any error @@ -83,20 +93,28 @@ The options are: If this option is specified, any ``-DLINK_LIBRARIES=...`` value given to the ``CMAKE_FLAGS`` option will be ignored. +``LINK_OPTIONS <options>...`` + Specify link step options to pass to :command:`target_link_options` or to + set the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property in the generated + project, depending on the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable. + ``OUTPUT_VARIABLE <var>`` - Store the output from the build process the given variable. + Store the output from the build process in the given variable. ``<LANG>_STANDARD <std>`` Specify the :prop_tgt:`C_STANDARD`, :prop_tgt:`CXX_STANDARD`, + :prop_tgt:`OBJC_STANDARD`, :prop_tgt:`OBJCXX_STANDARD`, or :prop_tgt:`CUDA_STANDARD` target property of the generated project. ``<LANG>_STANDARD_REQUIRED <bool>`` Specify the :prop_tgt:`C_STANDARD_REQUIRED`, - :prop_tgt:`CXX_STANDARD_REQUIRED`, or :prop_tgt:`CUDA_STANDARD_REQUIRED` + :prop_tgt:`CXX_STANDARD_REQUIRED`, :prop_tgt:`OBJC_STANDARD_REQUIRED`, + :prop_tgt:`OBJCXX_STANDARD_REQUIRED`,or :prop_tgt:`CUDA_STANDARD_REQUIRED` target property of the generated project. ``<LANG>_EXTENSIONS <bool>`` Specify the :prop_tgt:`C_EXTENSIONS`, :prop_tgt:`CXX_EXTENSIONS`, + :prop_tgt:`OBJC_EXTENSIONS`, :prop_tgt:`OBJCXX_EXTENSIONS`, or :prop_tgt:`CUDA_EXTENSIONS` target property of the generated project. In this version all files in ``<bindir>/CMakeFiles/CMakeTmp`` will be @@ -105,7 +123,7 @@ passed to ``cmake`` to avoid this clean. However, multiple sequential ``try_compile`` operations reuse this single output directory. If you use ``--debug-trycompile``, you can only debug one ``try_compile`` call at a time. The recommended procedure is to protect all ``try_compile`` calls in your -project by ``if(NOT DEFINED RESULT_VAR)`` logic, configure with cmake +project by ``if(NOT DEFINED <resultVar>)`` logic, configure with cmake all the way through once, then delete the cache entry associated with the try_compile call of interest, and then re-run cmake again with ``--debug-trycompile``. @@ -120,12 +138,19 @@ default values: * :variable:`CMAKE_ENABLE_EXPORTS` * :variable:`CMAKE_LINK_SEARCH_START_STATIC` * :variable:`CMAKE_LINK_SEARCH_END_STATIC` +* :variable:`CMAKE_MSVC_RUNTIME_LIBRARY` * :variable:`CMAKE_POSITION_INDEPENDENT_CODE` If :policy:`CMP0056` is set to ``NEW``, then :variable:`CMAKE_EXE_LINKER_FLAGS` is passed in as well. -The current setting of :policy:`CMP0065` is set in the generated project. +If :policy:`CMP0083` is set to ``NEW``, then in order to obtain correct +behavior at link time, the ``check_pie_supported()`` command from the +:module:`CheckPIESupported` module must be called before using the +:command:`try_compile` command. + +The current settings of :policy:`CMP0065` and :policy:`CMP0083` are propagated +through to the generated test project. Set the :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` variable to choose a build configuration. @@ -135,7 +160,9 @@ the type of target used for the source file signature. Set the :variable:`CMAKE_TRY_COMPILE_PLATFORM_VARIABLES` variable to specify variables that must be propagated into the test project. This variable is -meant for use only in toolchain files. +meant for use only in toolchain files and is only honored by the +``try_compile()`` command for the source files form, not when given a whole +project. If :policy:`CMP0067` is set to ``NEW``, or any of the ``<LANG>_STANDARD``, ``<LANG>_STANDARD_REQUIRED``, or ``<LANG>_EXTENSIONS`` options are used, @@ -147,9 +174,18 @@ then the language standard variables are honored: * :variable:`CMAKE_CXX_STANDARD` * :variable:`CMAKE_CXX_STANDARD_REQUIRED` * :variable:`CMAKE_CXX_EXTENSIONS` +* :variable:`CMAKE_OBJC_STANDARD` +* :variable:`CMAKE_OBJC_STANDARD_REQUIRED` +* :variable:`CMAKE_OBJC_EXTENSIONS` +* :variable:`CMAKE_OBJCXX_STANDARD` +* :variable:`CMAKE_OBJCXX_STANDARD_REQUIRED` +* :variable:`CMAKE_OBJCXX_EXTENSIONS` * :variable:`CMAKE_CUDA_STANDARD` * :variable:`CMAKE_CUDA_STANDARD_REQUIRED` * :variable:`CMAKE_CUDA_EXTENSIONS` Their values are used to set the corresponding target properties in the generated project (unless overridden by an explicit option). + +For the :generator:`Green Hills MULTI` generator the GHS toolset and target +system customization cache variables are also propagated into the test project. diff --git a/Help/command/try_run.rst b/Help/command/try_run.rst index e3bd57d50..d401ebe92 100644 --- a/Help/command/try_run.rst +++ b/Help/command/try_run.rst @@ -10,11 +10,12 @@ Try compiling and then running some code. Try Compiling and Running Source Files ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake - try_run(RUN_RESULT_VAR COMPILE_RESULT_VAR - bindir srcfile [CMAKE_FLAGS <flags>...] + try_run(<runResultVar> <compileResultVar> + <bindir> <srcfile> [CMAKE_FLAGS <flags>...] [COMPILE_DEFINITIONS <defs>...] + [LINK_OPTIONS <options>...] [LINK_LIBRARIES <libs>...] [COMPILE_OUTPUT_VARIABLE <var>] [RUN_OUTPUT_VARIABLE <var>] @@ -22,9 +23,9 @@ Try Compiling and Running Source Files [ARGS <args>...]) Try compiling a ``<srcfile>``. Returns ``TRUE`` or ``FALSE`` for success -or failure in ``COMPILE_RESULT_VAR``. If the compile succeeded, runs the -executable and returns its exit code in ``RUN_RESULT_VAR``. If the -executable was built, but failed to run, then ``RUN_RESULT_VAR`` will be +or failure in ``<compileResultVar>``. If the compile succeeded, runs the +executable and returns its exit code in ``<runResultVar>``. If the +executable was built, but failed to run, then ``<runResultVar>`` will be set to ``FAILED_TO_RUN``. See the :command:`try_compile` command for information on how the test project is constructed to build the source file. @@ -38,7 +39,7 @@ The options are: are used. ``COMPILE_DEFINITIONS <defs>...`` - Specify ``-Ddefinition`` arguments to pass to ``add_definitions`` + Specify ``-Ddefinition`` arguments to pass to :command:`add_definitions` in the generated test project. ``COMPILE_OUTPUT_VARIABLE <var>`` @@ -52,6 +53,10 @@ The options are: If this option is specified, any ``-DLINK_LIBRARIES=...`` value given to the ``CMAKE_FLAGS`` option will be ignored. +``LINK_OPTIONS <options>...`` + Specify link step options to pass to :command:`target_link_options` in the + generated project. + ``OUTPUT_VARIABLE <var>`` Report the compile build output and the output from running the executable in the given variable. This option exists for legacy reasons. Prefer @@ -80,10 +85,10 @@ presetting them in some CMake script file to the values the executable would have produced if it had been run on its actual target platform. These cache entries are: -``<RUN_RESULT_VAR>`` +``<runResultVar>`` Exit code if the executable were to be run on the target platform. -``<RUN_RESULT_VAR>__TRYRUN_OUTPUT`` +``<runResultVar>__TRYRUN_OUTPUT`` Output from stdout and stderr if the executable were to be run on the target platform. This is created only if the ``RUN_OUTPUT_VARIABLE`` or ``OUTPUT_VARIABLE`` option was used. diff --git a/Help/command/unset.rst b/Help/command/unset.rst index a1fc95cc6..75210521e 100644 --- a/Help/command/unset.rst +++ b/Help/command/unset.rst @@ -3,23 +3,39 @@ unset Unset a variable, cache variable, or environment variable. -:: +Unset Normal Variable or Cache Entry +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: cmake 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 for further details. -``<variable>`` can be an environment variable such as: +Unset Environment Variable +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: cmake -:: + unset(ENV{<variable>}) - unset(ENV{LD_LIBRARY_PATH}) +Removes ``<variable>`` from the currently available +:manual:`Environment Variables <cmake-env-variables(7)>`. +Subsequent calls of ``$ENV{<variable>}`` will return the empty string. -in which case the variable will be removed from the current -environment. +This command affects only the current CMake process, not the process +from which CMake was called, nor the system environment at large, +nor the environment of subsequent build or test processes. diff --git a/Help/command/use_mangled_mesa.rst b/Help/command/use_mangled_mesa.rst index 6f4d7aca6..5b0e2ee06 100644 --- a/Help/command/use_mangled_mesa.rst +++ b/Help/command/use_mangled_mesa.rst @@ -1,7 +1,7 @@ use_mangled_mesa ---------------- -Disallowed. See CMake Policy :policy:`CMP0030`. +Disallowed since version 3.0. See CMake Policy :policy:`CMP0030`. Copy mesa headers for use in combination with system GL. @@ -9,7 +9,7 @@ Copy mesa headers for use in combination with system GL. use_mangled_mesa(PATH_TO_MESA OUTPUT_DIRECTORY) -The path to mesa includes, should contain gl_mangle.h. The mesa +The path to mesa includes, should contain ``gl_mangle.h``. The mesa headers are copied to the specified output directory. This allows mangled mesa headers to override other GL headers by being added to the include directory path earlier. diff --git a/Help/command/utility_source.rst b/Help/command/utility_source.rst index ee34492c3..94d6a4e64 100644 --- a/Help/command/utility_source.rst +++ b/Help/command/utility_source.rst @@ -1,7 +1,7 @@ utility_source -------------- -Disallowed. See CMake Policy :policy:`CMP0034`. +Disallowed since version 3.0. See CMake Policy :policy:`CMP0034`. Specify the source tree of a third-party utility. diff --git a/Help/command/variable_requires.rst b/Help/command/variable_requires.rst index 9cf9f3ffd..322b15459 100644 --- a/Help/command/variable_requires.rst +++ b/Help/command/variable_requires.rst @@ -1,7 +1,7 @@ variable_requires ----------------- -Disallowed. See CMake Policy :policy:`CMP0035`. +Disallowed since version 3.0. See CMake Policy :policy:`CMP0035`. Use the :command:`if` command instead. @@ -18,5 +18,5 @@ tested, if that variable is false nothing else is done. If ``TEST_VARIABLE`` is true, then the next argument (``RESULT_VARIABLE``) is a variable that is set to true if all the required variables are set. The rest of the arguments are variables that must be true or not set -to NOTFOUND to avoid an error. If any are not true, an error is +to ``NOTFOUND`` to avoid an error. If any are not true, an error is reported. diff --git a/Help/command/variable_watch.rst b/Help/command/variable_watch.rst index a2df058eb..ce69bcfcd 100644 --- a/Help/command/variable_watch.rst +++ b/Help/command/variable_watch.rst @@ -3,11 +3,13 @@ variable_watch Watch the CMake variable for change. -:: +.. code-block:: cmake - variable_watch(<variable name> [<command to execute>]) + variable_watch(<variable> [<command>]) -If the specified variable changes, the message will be printed about -the variable being changed. If the command is specified, the command -will be executed. The command will receive the following arguments: -COMMAND(<variable> <access> <value> <current list file> <stack>) +If the specified ``<variable>`` changes, a message will be printed +to inform about the change. + +Additionally, if ``<command>`` is given, this command will be executed. +The command will receive the following arguments: +``COMMAND(<variable> <access> <value> <current_list_file> <stack>)`` diff --git a/Help/command/while.rst b/Help/command/while.rst index 7509da309..a4957c1db 100644 --- a/Help/command/while.rst +++ b/Help/command/while.rst @@ -3,15 +3,23 @@ while Evaluate a group of commands while a condition is true -:: +.. code-block:: cmake - while(condition) - COMMAND1(ARGS ...) - COMMAND2(ARGS ...) - ... - endwhile(condition) + while(<condition>) + <commands> + endwhile() All commands between while and the matching :command:`endwhile` are recorded without being invoked. Once the :command:`endwhile` is evaluated, the -recorded list of commands is invoked as long as the condition is true. The -condition is evaluated using the same logic as the :command:`if` command. +recorded list of commands is invoked as long as the ``<condition>`` is true. + +The ``<condition>`` has the same syntax and is evaluated using the same logic +as described at length for the :command:`if` command. + +The commands :command:`break` and :command:`continue` provide means to +escape from the normal control flow. + +Per legacy, the :command:`endwhile` command admits +an optional ``<condition>`` argument. +If used, it must be a verbatim repeat of the argument of the opening +``while`` command. diff --git a/Help/command/write_file.rst b/Help/command/write_file.rst index 40e755763..4d476bd5a 100644 --- a/Help/command/write_file.rst +++ b/Help/command/write_file.rst @@ -1,7 +1,9 @@ write_file ---------- -Deprecated. Use the :command:`file(WRITE)` command instead. +.. deprecated:: 3.0 + + Use the :command:`file(WRITE)` command instead. :: diff --git a/Help/cpack_gen/archive.rst b/Help/cpack_gen/archive.rst new file mode 100644 index 000000000..d455f4b45 --- /dev/null +++ b/Help/cpack_gen/archive.rst @@ -0,0 +1,36 @@ +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) + - TZST (.tar.zst) + - 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. diff --git a/Help/cpack_gen/bundle.rst b/Help/cpack_gen/bundle.rst new file mode 100644 index 000000000..b16dbda03 --- /dev/null +++ b/Help/cpack_gen/bundle.rst @@ -0,0 +1,66 @@ +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 macOS Finder as the + bundle name. Required. + +.. variable:: CPACK_BUNDLE_PLIST + + Path to an macOS Property List (``.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 macOS icon file that will be used as the icon for the generated + bundle. This is the icon that appears in the macOS Finder for the bundle, and + in the macOS 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 + macOS 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 Property List (``.plist``) file that contains your Apple + entitlements for sandboxing your application. This file is required + for submission to the macOS 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). diff --git a/Help/cpack_gen/cygwin.rst b/Help/cpack_gen/cygwin.rst new file mode 100644 index 000000000..1c5f7af91 --- /dev/null +++ b/Help/cpack_gen/cygwin.rst @@ -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. diff --git a/Help/cpack_gen/deb.rst b/Help/cpack_gen/deb.rst new file mode 100644 index 000000000..db71c87e7 --- /dev/null +++ b/Help/cpack_gen/deb.rst @@ -0,0 +1,565 @@ +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 ``CPACK_DEBIAN_XXX`` variables. + +``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 ``dpkg --print-architecture`` (or ``i386`` + if ``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 : ``CPACK_PACKAGE_CONTACT`` + +.. variable:: CPACK_DEBIAN_PACKAGE_DESCRIPTION + CPACK_DEBIAN_<COMPONENT>_DESCRIPTION + + The Debian package description + + * Mandatory : YES + * Default : + + - :variable:`CPACK_DEBIAN_<COMPONENT>_DESCRIPTION` (component + based installers only) if set, or :variable:`CPACK_DEBIAN_PACKAGE_DESCRIPTION` if set, or + - :variable:`CPACK_COMPONENT_<compName>_DESCRIPTION` (component + based installers only) if set, or :variable:`CPACK_PACKAGE_DESCRIPTION` if set, or + - content of the file specified in :variable:`CPACK_PACKAGE_DESCRIPTION_FILE` if set + + If after that description is not set, :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY` going to be + used if set. Otherwise, :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY` will be added as the first + line of description as defined in `Debian Policy Manual`_. + +.. _Debian Policy Manual: https://www.debian.org/doc/debian-policy/ch-controlfields.html#description + +.. 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 : "gnutar" + + Possible value is: + + - gnutar + + .. note:: + + This variable previously defaulted to the ``paxr`` value, but ``dpkg`` + has never supported that tar format. For backwards compatibility the + ``paxr`` value will be mapped to ``gnutar`` and a deprecation message + will be emitted. + +.. 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 ``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 ``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 ``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), + ``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, ``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. diff --git a/Help/cpack_gen/dmg.rst b/Help/cpack_gen/dmg.rst new file mode 100644 index 000000000..1e3788933 --- /dev/null +++ b/Help/cpack_gen/dmg.rst @@ -0,0 +1,101 @@ +CPack DragNDrop Generator +------------------------- + +The DragNDrop CPack generator (macOS) creates a DMG image. + +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). diff --git a/Help/cpack_gen/external.rst b/Help/cpack_gen/external.rst new file mode 100644 index 000000000..406f6be1a --- /dev/null +++ b/Help/cpack_gen/external.rst @@ -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_EXTERNAL_PACKAGE_SCRIPT` instead. + +Staging of installation files may also optionally be +taken care of by the generator when enabled through the +:variable:`CPACK_EXTERNAL_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_EXTERNAL_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_EXTERNAL_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_EXTERNAL_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_EXTERNAL_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_EXTERNAL_REQUESTED_VERSIONS`` (one + that doesn't match ``major.minor``, where ``major`` and ``minor`` are + integers), it is ignored. + +.. variable:: CPACK_EXTERNAL_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_EXTERNAL_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. diff --git a/Help/cpack_gen/freebsd.rst b/Help/cpack_gen/freebsd.rst new file mode 100644 index 000000000..a8dd32050 --- /dev/null +++ b/Help/cpack_gen/freebsd.rst @@ -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 +``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 diff --git a/Help/cpack_gen/ifw.rst b/Help/cpack_gen/ifw.rst new file mode 100644 index 000000000..feccd3db0 --- /dev/null +++ b/Help/cpack_gen/ifw.rst @@ -0,0 +1,339 @@ +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_STYLE_SHEET + + Filename for a stylesheet. + +.. 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 diff --git a/Help/cpack_gen/nsis.rst b/Help/cpack_gen/nsis.rst new file mode 100644 index 000000000..cd2aea682 --- /dev/null +++ b/Help/cpack_gen/nsis.rst @@ -0,0 +1,130 @@ +CPack NSIS Generator +-------------------- + +CPack Nullsoft Scriptable Install System (NSIS) generator specific options + +Variables specific to CPack NSIS generator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following variables are specific to the graphical installers built +on Windows Nullsoft Scriptable Install 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 `Apps & features` + in `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") diff --git a/Help/cpack_gen/nuget.rst b/Help/cpack_gen/nuget.rst new file mode 100644 index 000000000..f8aa6266b --- /dev/null +++ b/Help/cpack_gen/nuget.rst @@ -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 ``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 diff --git a/Help/cpack_gen/packagemaker.rst b/Help/cpack_gen/packagemaker.rst new file mode 100644 index 000000000..e9464b749 --- /dev/null +++ b/Help/cpack_gen/packagemaker.rst @@ -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. diff --git a/Help/cpack_gen/productbuild.rst b/Help/cpack_gen/productbuild.rst new file mode 100644 index 000000000..d22fcd48a --- /dev/null +++ b/Help/cpack_gen/productbuild.rst @@ -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. diff --git a/Help/cpack_gen/rpm.rst b/Help/cpack_gen/rpm.rst new file mode 100644 index 000000000..2693c7b62 --- /dev/null +++ b/Help/cpack_gen/rpm.rst @@ -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 +``CPACK_RPM_XXX`` variables. + +``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 (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") diff --git a/Help/cpack_gen/wix.rst b/Help/cpack_gen/wix.rst new file mode 100644 index 000000000..7fb5a12a7 --- /dev/null +++ b/Help/cpack_gen/wix.rst @@ -0,0 +1,288 @@ +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 + + If this variable is set to ``.``, then application shortcuts will be + created directly in the start menu and the uninstaller shortcut will be + omitted. + +.. 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. diff --git a/Help/dev/README.rst b/Help/dev/README.rst index ce62abc4b..84da4f1d3 100644 --- a/Help/dev/README.rst +++ b/Help/dev/README.rst @@ -36,8 +36,10 @@ Developer Documentation CMake developer documentation is provided by the following documents: * The `CMake Source Code Guide`_. +* The `CMake Documentation Guide`_. .. _`CMake Source Code Guide`: source.rst +.. _`CMake Documentation Guide`: documentation.rst Maintainer Documentation ======================== diff --git a/Help/dev/documentation.rst b/Help/dev/documentation.rst new file mode 100644 index 000000000..c302790aa --- /dev/null +++ b/Help/dev/documentation.rst @@ -0,0 +1,530 @@ +CMake Documentation Guide +************************* + +The following is a guide to the CMake documentation source for developers. +See documentation on `CMake Development`_ for more information. + +.. _`CMake Development`: README.rst + +Help +==== + +The ``Help`` directory contains CMake help manual source files. +They are written using the `reStructuredText`_ markup syntax and +processed by `Sphinx`_ to generate the CMake help manuals. + +.. _`reStructuredText`: http://docutils.sourceforge.net/docs/ref/rst/introduction.html +.. _`Sphinx`: http://sphinx-doc.org + +Markup Constructs +----------------- + +In addition to using Sphinx to generate the CMake help manuals, we +also use a C++-implemented document processor to print documents for +the ``--help-*`` command-line help options. It supports a subset of +reStructuredText markup. When authoring or modifying documents, +please verify that the command-line help looks good in addition to the +Sphinx-generated html and man pages. + +The command-line help processor supports the following constructs +defined by reStructuredText, Sphinx, and a CMake extension to Sphinx. + +.. + Note: This list must be kept consistent with the cmRST implementation. + +CMake Domain directives + Directives defined in the `CMake Domain`_ for defining CMake + documentation objects are printed in command-line help output as + if the lines were normal paragraph text with interpretation. + +CMake Domain interpreted text roles + Interpreted text roles defined in the `CMake Domain`_ for + cross-referencing CMake documentation objects are replaced by their + link text in command-line help output. Other roles are printed + literally and not processed. + +``code-block`` directive + Add a literal code block without interpretation. The command-line + help processor prints the block content without the leading directive + line and with common indentation replaced by one space. + +``include`` directive + Include another document source file. The command-line help + processor prints the included document inline with the referencing + document. + +literal block after ``::`` + A paragraph ending in ``::`` followed by a blank line treats + the following indented block as literal text without interpretation. + The command-line help processor prints the ``::`` literally and + prints the block content with common indentation replaced by one + space. + +``note`` directive + Call out a side note. The command-line help processor prints the + block content as if the lines were normal paragraph text with + interpretation. + +``parsed-literal`` directive + Add a literal block with markup interpretation. The command-line + help processor prints the block content without the leading + directive line and with common indentation replaced by one space. + +``productionlist`` directive + Render context-free grammar productions. The command-line help + processor prints the block content as if the lines were normal + paragraph text with interpretation. + +``replace`` directive + Define a ``|substitution|`` replacement. + The command-line help processor requires a substitution replacement + to be defined before it is referenced. + +``|substitution|`` reference + Reference a substitution replacement previously defined by + the ``replace`` directive. The command-line help processor + performs the substitution and replaces all newlines in the + replacement text with spaces. + +``toctree`` directive + Include other document sources in the Table-of-Contents + document tree. The command-line help processor prints + the referenced documents inline as part of the referencing + document. + +Inline markup constructs not listed above are printed literally in the +command-line help output. We prefer to use inline markup constructs that +look correct in source form, so avoid use of \\-escapes in favor of inline +literals when possible. + +Explicit markup blocks not matching directives listed above are removed from +command-line help output. Do not use them, except for plain ``..`` comments +that are removed by Sphinx too. + +Note that nested indentation of blocks is not recognized by the +command-line help processor. Therefore: + +* Explicit markup blocks are recognized only when not indented + inside other blocks. + +* Literal blocks after paragraphs ending in ``::`` but not + at the top indentation level may consume all indented lines + following them. + +Try to avoid these cases in practice. + +CMake Domain +------------ + +CMake adds a `Sphinx Domain`_ called ``cmake``, also called the +"CMake Domain". It defines several "object" types for CMake +documentation: + +``command`` + A CMake language command. + +``generator`` + A CMake native build system generator. + See the `cmake(1)`_ command-line tool's ``-G`` option. + +``manual`` + A CMake manual page, like the `cmake(1)`_ manual. + +``module`` + A CMake module. + See the `cmake-modules(7)`_ manual + and the `include()`_ command. + +``policy`` + A CMake policy. + See the `cmake-policies(7)`_ manual + and the `cmake_policy()`_ command. + +``prop_cache, prop_dir, prop_gbl, prop_sf, prop_inst, prop_test, prop_tgt`` + A CMake cache, directory, global, source file, installed file, test, + or target property, respectively. See the `cmake-properties(7)`_ + manual and the `set_property()`_ command. + +``variable`` + A CMake language variable. + See the `cmake-variables(7)`_ manual + and the `set()`_ command. + +Documentation objects in the CMake Domain come from two sources. +First, the CMake extension to Sphinx transforms every document named +with the form ``Help/<type>/<file-name>.rst`` to a domain object with +type ``<type>``. The object name is extracted from the document title, +which is expected to be of the form:: + + <object-name> + ------------- + +and to appear at or near the top of the ``.rst`` file before any other +lines starting in a letter, digit, or ``<``. If no such title appears +literally in the ``.rst`` file, the object name is the ``<file-name>``. +If a title does appear, it is expected that ``<file-name>`` is equal +to ``<object-name>`` with any ``<`` and ``>`` characters removed. + +Second, the CMake Domain provides directives to define objects inside +other documents: + +.. code-block:: rst + + .. command:: <command-name> + + This indented block documents <command-name>. + + .. variable:: <variable-name> + + This indented block documents <variable-name>. + +Object types for which no directive is available must be defined using +the first approach above. + +.. _`Sphinx Domain`: http://sphinx-doc.org/domains.html +.. _`cmake(1)`: https://cmake.org/cmake/help/latest/manual/cmake.1.html +.. _`cmake-modules(7)`: https://cmake.org/cmake/help/latest/manual/cmake-modules.7.html +.. _`cmake-policies(7)`: https://cmake.org/cmake/help/latest/manual/cmake-policies.7.html +.. _`cmake-properties(7)`: https://cmake.org/cmake/help/latest/manual/cmake-properties.7.html +.. _`cmake-variables(7)`: https://cmake.org/cmake/help/latest/manual/cmake-variables.7.html +.. _`cmake_policy()`: https://cmake.org/cmake/help/latest/command/cmake_policy.html +.. _`include()`: https://cmake.org/cmake/help/latest/command/include.html +.. _`set()`: https://cmake.org/cmake/help/latest/command/set.html +.. _`set_property()`: https://cmake.org/cmake/help/latest/command/set_property.html + +Cross-References +---------------- + +Sphinx uses reStructuredText interpreted text roles to provide +cross-reference syntax. The `CMake Domain`_ provides for each +domain object type a role of the same name to cross-reference it. +CMake Domain roles are inline markup of the forms:: + + :type:`name` + :type:`text <name>` + +where ``type`` is the domain object type and ``name`` is the +domain object name. In the first form the link text will be +``name`` (or ``name()`` if the type is ``command``) and in +the second form the link text will be the explicit ``text``. +For example, the code: + +.. code-block:: rst + + * The :command:`list` command. + * The :command:`list(APPEND)` sub-command. + * The :command:`list() command <list>`. + * The :command:`list(APPEND) sub-command <list>`. + * The :variable:`CMAKE_VERSION` variable. + * The :prop_tgt:`OUTPUT_NAME_<CONFIG>` target property. + +produces: + +* The `list()`_ command. +* The `list(APPEND)`_ sub-command. +* The `list() command`_. +* The `list(APPEND) sub-command`_. +* The `CMAKE_VERSION`_ variable. +* The `OUTPUT_NAME_<CONFIG>`_ target property. + +Note that CMake Domain roles differ from Sphinx and reStructuredText +convention in that the form ``a<b>``, without a space preceding ``<``, +is interpreted as a name instead of link text with an explicit target. +This is necessary because we use ``<placeholders>`` frequently in +object names like ``OUTPUT_NAME_<CONFIG>``. The form ``a <b>``, +with a space preceding ``<``, is still interpreted as a link text +with an explicit target. + +.. _`list()`: https://cmake.org/cmake/help/latest/command/list.html +.. _`list(APPEND)`: https://cmake.org/cmake/help/latest/command/list.html +.. _`list(APPEND) sub-command`: https://cmake.org/cmake/help/latest/command/list.html +.. _`list() command`: https://cmake.org/cmake/help/latest/command/list.html +.. _`CMAKE_VERSION`: https://cmake.org/cmake/help/latest/variable/CMAKE_VERSION.html +.. _`OUTPUT_NAME_<CONFIG>`: https://cmake.org/cmake/help/latest/prop_tgt/OUTPUT_NAME_CONFIG.html + +Style +----- + +Style: Section Headers +^^^^^^^^^^^^^^^^^^^^^^ + +When marking section titles, make the section decoration line as long as +the title text. Use only a line below the title, not above. For +example: + +.. code-block:: rst + + Title Text + ---------- + +Capitalize the first letter of each non-minor word in the title. + +The section header underline character hierarchy is + +* ``#``: Manual group (part) in the master document +* ``*``: Manual (chapter) title +* ``=``: Section within a manual +* ``-``: Subsection or `CMake Domain`_ object document title +* ``^``: Subsubsection or `CMake Domain`_ object document section +* ``"``: Paragraph or `CMake Domain`_ object document subsection + +Style: Whitespace +^^^^^^^^^^^^^^^^^ + +Use two spaces for indentation. Use two spaces between sentences in +prose. + +Style: Line Length +^^^^^^^^^^^^^^^^^^ + +Prefer to restrict the width of lines to 75-80 columns. This is not a +hard restriction, but writing new paragraphs wrapped at 75 columns +allows space for adding minor content without significant re-wrapping of +content. + +Style: Prose +^^^^^^^^^^^^ + +Use American English spellings in prose. + +Style: Starting Literal Blocks +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Prefer to mark the start of literal blocks with ``::`` at the end of +the preceding paragraph. In cases where the following block gets +a ``code-block`` marker, put a single ``:`` at the end of the preceding +paragraph. + +Style: CMake Command Signatures +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Command signatures should be marked up as plain literal blocks, not as +cmake ``code-blocks``. + +Signatures are separated from preceding content by a section header. +That is, use: + +.. code-block:: rst + + ... preceding paragraph. + + Normal Libraries + ^^^^^^^^^^^^^^^^ + + :: + + add_library(<lib> ...) + + This signature is used for ... + +Signatures of commands should wrap optional parts with square brackets, +and should mark list of optional arguments with an ellipsis (``...``). +Elements of the signature which are specified by the user should be +specified with angle brackets, and may be referred to in prose using +``inline-literal`` syntax. + +Style: Boolean Constants +^^^^^^^^^^^^^^^^^^^^^^^^ + +Use "``OFF``" and "``ON``" for boolean values which can be modified by +the user, such as ``POSITION_INDEPENDENT_CODE``. Such properties +may be "enabled" and "disabled". Use "``True``" and "``False``" for +inherent values which can't be modified after being set, such as the +``IMPORTED`` property of a build target. + +Style: Inline Literals +^^^^^^^^^^^^^^^^^^^^^^ + +Mark up references to keywords in signatures, file names, and other +technical terms with ``inline-literal`` syntax, for example: + +.. code-block:: rst + + If ``WIN32`` is used with :command:`add_executable`, the + :prop_tgt:`WIN32_EXECUTABLE` target property is enabled. That command + creates the file ``<name>.exe`` on Windows. + +Style: Cross-References +^^^^^^^^^^^^^^^^^^^^^^^ + +Mark up linkable references as links, including repeats. +An alternative, which is used by wikipedia +(`<http://en.wikipedia.org/wiki/WP:REPEATLINK>`_), +is to link to a reference only once per article. That style is not used +in CMake documentation. + +Style: Referencing CMake Concepts +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If referring to a concept which corresponds to a property, and that +concept is described in a high-level manual, prefer to link to the +manual section instead of the property. For example: + +.. code-block:: rst + + This command creates an :ref:`Imported Target <Imported Targets>`. + +instead of: + +.. code-block:: rst + + This command creates an :prop_tgt:`IMPORTED` target. + +The latter should be used only when referring specifically to the +property. + +References to manual sections are not automatically created by creating +a section, but code such as: + +.. code-block:: rst + + .. _`Imported Targets`: + +creates a suitable anchor. Use an anchor name which matches the name +of the corresponding section. Refer to the anchor using a +cross-reference with specified text. + +Imported Targets need the ``IMPORTED`` term marked up with care in +particular because the term may refer to a command keyword, a target +property, or a concept. + +Where a property, command or variable is related conceptually to others, +by for example, being related to the buildsystem description, generator +expressions or Qt, each relevant property, command or variable should +link to the primary manual, which provides high-level information. Only +particular information relating to the command should be in the +documentation of the command. + +Style: Referencing CMake Domain Objects +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When referring to `CMake Domain`_ objects such as properties, variables, +commands etc, prefer to link to the target object and follow that with +the type of object it is. For example: + +.. code-block:: rst + + Set the :prop_tgt:`AUTOMOC` target property to ``ON``. + +Instead of + +.. code-block:: rst + + Set the target property :prop_tgt:`AUTOMOC` to ``ON``. + +The ``policy`` directive is an exception, and the type us usually +referred to before the link: + +.. code-block:: rst + + If policy :policy:`CMP0022` is set to ``NEW`` the behavior is ... + +However, markup self-references with ``inline-literal`` syntax. +For example, within the ``add_executable`` command documentation, use + +.. code-block:: rst + + ``add_executable`` + +not + +.. code-block:: rst + + :command:`add_executable` + +which is used elsewhere. + +Modules +======= + +The ``Modules`` directory contains CMake-language ``.cmake`` module files. + +Module Documentation +-------------------- + +To document CMake module ``Modules/<module-name>.cmake``, modify +``Help/manual/cmake-modules.7.rst`` to reference the module in the +``toctree`` directive, in sorted order, as:: + + /module/<module-name> + +Then add the module document file ``Help/module/<module-name>.rst`` +containing just the line:: + + .. cmake-module:: ../../Modules/<module-name>.cmake + +The ``cmake-module`` directive will scan the module file to extract +reStructuredText markup from comment blocks that start in ``.rst:``. +At the top of ``Modules/<module-name>.cmake``, begin with the following +license notice: + +:: + + # Distributed under the OSI-approved BSD 3-Clause License. See accompanying + # file Copyright.txt or https://cmake.org/licensing for details. + +After this notice, add a *BLANK* line. Then, add documentation using +a `Bracket Comment`_ of the form: + +:: + + #[=======================================================================[.rst: + <module-name> + ------------- + + <reStructuredText documentation of module> + #]=======================================================================] + +Any number of ``=`` may be used in the opening and closing brackets +as long as they match. Content on the line containing the closing +bracket is excluded if and only if the line starts in ``#``. + +Additional such ``.rst:`` comments may appear anywhere in the module file. +All such comments must start with ``#`` in the first column. + +For example, a ``Findxxx.cmake`` module may contain: + +:: + + # Distributed under the OSI-approved BSD 3-Clause License. See accompanying + # file Copyright.txt or https://cmake.org/licensing for details. + + #[=======================================================================[.rst: + FindXxx + ------- + + This is a cool module. + This module does really cool stuff. + It can do even more than you think. + + It even needs two paragraphs to tell you about it. + And it defines the following variables: + + ``VAR_COOL`` + this is great isn't it? + ``VAR_REALLY_COOL`` + cool right? + #]=======================================================================] + + <code> + + #[=======================================================================[.rst: + .. command:: xxx_do_something + + This command does something for Xxx:: + + xxx_do_something(some arguments) + #]=======================================================================] + macro(xxx_do_something) + <code> + endmacro() + +Test the documentation formatting by running +``cmake --help-module <module-name>``, and also by enabling the +``SPHINX_HTML`` and ``SPHINX_MAN`` options to build the documentation. +Edit the comments until generated documentation looks satisfactory. To +have a .cmake file in this directory NOT show up in the modules +documentation, simply leave out the ``Help/module/<module-name>.rst`` +file and the ``Help/manual/cmake-modules.7.rst`` toctree entry. + +.. _`Bracket Comment`: https://cmake.org/cmake/help/latest/manual/cmake-language.7.html#bracket-comment diff --git a/Help/dev/maint.rst b/Help/dev/maint.rst index 78c06df65..44e227347 100644 --- a/Help/dev/maint.rst +++ b/Help/dev/maint.rst @@ -8,6 +8,129 @@ See documentation on `CMake Development`_ for more information. .. contents:: Maintainer Processes: +Review a Merge Request +====================== + +The `CMake Review Process`_ requires a maintainer to issue the ``Do: merge`` +command to integrate a merge request. Please check at least the following: + +* If the MR source branch is not named well for the change it makes + (e.g. it is just ``master`` or the patch changed during review), + add a ``Topic-rename: <topic>`` trailing line to the MR description + to provide a better topic name. + +* If the MR introduces a new feature or a user-facing behavior change, + such as a policy, ensure that a ``Help/release/dev/$topic.rst`` file + is added with a release note. + +* If a commit changes a specific area, such as a module, its commit + message should have an ``area:`` prefix on its first line. + +* If a commit fixes a tracked issue, its commit message should have + a trailing line such as ``Fixes: #00000``. + +* Ensure that the MR adds sufficient documentation and test cases. + +* Ensure that the MR has been tested sufficiently. Typically it should + be staged for nightly testing with ``Do: stage``. Then manually + review the `CMake CDash Page`_ to verify that no regressions were + introduced. (Learn to tolerate spurious failures due to idiosyncrasies + of various nightly builders.) + +* Ensure that the MR targets the ``master`` branch. A MR intended for + the ``release`` branch should be based on ``release`` but still merged + to ``master`` first (via ``Do: merge``). A maintainer may then merge + the MR topic to ``release`` manually. + +Maintain Current Release +======================== + +The ``release`` branch is used to maintain the current release or release +candidate. The branch is published with no version number but maintained +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. + +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, making +sure to include a ``Merge-request: !xxxx`` footer in the commit message: + +.. code-block:: shell + + git merge --no-ff $topic + +Merge the ``release-$ver`` branch to ``master``: + +.. code-block:: shell + + git checkout master + git pull + git merge --no-ff release-$ver + +Review new ancestry to ensure nothing unexpected was merged to either branch: + +.. code-block:: shell + + git log --graph --boundary origin/master..master + git log --graph --boundary origin/release..release-$ver + +Publish both ``master`` and ``release`` simultaneously: + +.. code-block:: shell + + git push --atomic origin master release-$ver:release + +.. _`CMake Review Process`: review.rst +.. _`CMake CDash Page`: https://open.cdash.org/index.php?project=CMake + +Create Release Version +====================== + +When the ``release`` branch is ready to create a new release, follow the +steps in the above `Maintain Current Release`_ section to checkout a local +``release-$ver`` branch, where ``$ver`` is the version number of the +current release in the form ``$major.$minor``. + +Edit ``Source/CMakeVersion.cmake`` to set the full version: + +.. code-block:: cmake + + # CMake version number components. + set(CMake_VERSION_MAJOR $major) + set(CMake_VERSION_MINOR $minor) + set(CMake_VERSION_PATCH $patch) + #set(CMake_VERSION_RC $rc) # uncomment for release candidates + +In the following we use the placeholder ``$fullver`` for the full version +number of the new release with the form ``$major.$minor.$patch[-rc$rc]``. +If the version is not a release candidate, comment out the RC version +component above and leave off the ``-rc$rc`` suffix from ``$fullver``. + +Commit the release version with the **exact** message ``CMake $fullver``: + +.. code-block:: shell + + git commit -m "CMake $fullver" + +Tag the release using an annotated tag with the same message as the +commit and named with the **exact** form ``v$fullver``: + +.. code-block:: shell + + git tag -s -m "CMake $fullver" "v$fullver" + +Follow the steps in the above `Maintain Current Release`_ section to +merge the ``release-$ver`` branch into ``master`` and publish both. + Branch a New Release ==================== @@ -94,7 +217,7 @@ Commit with a message such as:: the CMake Release Notes index page. Update ``Source/CMakeVersion.cmake`` to set the version to -``$major.$minor.0-rc1``: +``$major.$minor.0-rc0``: .. code-block:: cmake @@ -102,13 +225,7 @@ Update ``Source/CMakeVersion.cmake`` to set the version to set(CMake_VERSION_MAJOR $major) set(CMake_VERSION_MINOR $minor) set(CMake_VERSION_PATCH 0) - set(CMake_VERSION_RC 1) - -Update ``Utilities/Release/upload_release.cmake``: - -.. code-block:: cmake - - set(VERSION $ver) + set(CMake_VERSION_RC 0) Update uses of ``DEVEL_CMAKE_VERSION`` in the source tree to mention the actual version number: @@ -119,7 +236,7 @@ actual version number: Commit with a message such as:: - CMake $major.$minor.0-rc1 version update + Begin $ver release versioning Merge the ``release-$ver`` branch to ``master``: @@ -147,7 +264,7 @@ Update ``Source/CMakeVersion.cmake`` to set the version to set(CMake_VERSION_MAJOR $major) set(CMake_VERSION_MINOR $minor) set(CMake_VERSION_PATCH $date) - #set(CMake_VERSION_RC 1) + #set(CMake_VERSION_RC 0) Commit with a message such as:: @@ -162,10 +279,11 @@ Push the update to the ``master`` and ``release`` branches: Announce 'release' Branch ------------------------- -Send email to the ``cmake-developers@cmake.org`` mailing list (perhaps -in reply to a release preparation thread) announcing that post-release -development is open:: +Post a topic to the `CMake Discourse Forum Development Category`_ +announcing that post-release development is open:: - I've branched 'release' for $ver. The repository is now open for - post-$ver development. Please rebase open merge requests on 'master' + I've branched `release` for $ver. The repository is now open for + post-$ver development. Please rebase open merge requests on `master` before staging or merging. + +.. _`CMake Discourse Forum Development Category`: https://discourse.cmake.org/c/development diff --git a/Help/dev/review.rst b/Help/dev/review.rst index 9450bf081..cbde6feea 100644 --- a/Help/dev/review.rst +++ b/Help/dev/review.rst @@ -185,6 +185,92 @@ commands to ``@kwrobot`` using the form ``Do: ...``: See the corresponding sections for details on permissions and options for each command. +Commit Messages +--------------- + +Part of the human review is to check that each commit message is appropriate. +The first line of the message should begin with one or two words indicating the +area the commit applies to, followed by a colon and then a brief summary. +Committers should aim to keep this first line short. Any subsequent lines +should be separated from the first by a blank line and provide relevant, useful +information. + +Area Prefix on Commit Messages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The appropriateness of the initial word describing the area the commit applies +to is not something the automatic robot review can judge, so it is up to the +human reviewer to confirm that the area is specified and that it is +appropriate. Good area words include the module name the commit is primarily +fixing, the main C++ source file being edited, ``Help`` for generic +documentation changes or a feature or functionality theme the changes apply to +(e.g. ``server`` or ``Autogen``). Examples of suitable first lines of a commit +message include: + +* ``Help: Fix example in cmake-buildsystem(7) manual`` +* ``FindBoost: Add support for 1.64`` +* ``Autogen: Extended mocInclude tests`` +* ``cmLocalGenerator: Explain standard flag selection logic in comments`` + +Referencing Issues in Commit Messages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If the commit fixes a particular reported issue, this information should +ideally also be part of the commit message. The recommended way to do this is +to place a line at the end of the message in the form ``Fixes: #xxxxx`` where +``xxxxx`` is the GitLab issue number and to separate it from the rest of the +text by a blank line. For example:: + + Help: Fix FooBar example robustness issue + + FooBar supports option X, but the example provided + would not work if Y was also specified. + + Fixes: #12345 + +GitLab will automatically create relevant links to the merge request and will +close the issue when the commit is merged into master. GitLab understands a few +other synonyms for ``Fixes`` and allows much more flexible forms than the +above, but committers should aim for this format for consistency. Note that +such details can alternatively be specified in the merge request description. + +Referencing Commits in Commit Messages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The preferred form for references to other commits is +``commit <shorthash> (<subject>, <date>)``, where: + +* ``<shorthash>``: + The abbreviated hash of the commit. + +* ``<subject>``: + The first line of the commit message. + +* ``<date>``: + The author date of the commit, in its original time zone, formatted as + ``CCYY-MM-DD``. ``git-log(1)`` shows the original time zone by default. + +This may be generated with +``git show -s --date=short --pretty="format:%h (%s, %ad)" <commit>``. + +If the commit is a fix for the mentioned commit, consider using a ``Fixes:`` +trailer in the commit message with the specified format. This trailer should +not be word-wrapped. Note that if there is also an issue for what is being +fixed, it is preferrable to link to the issue instead. + +If relevant, add the first release tag of CMake containing the commit after +the ``<date>``, i.e., ``commit <shorthash> (<subject>, <date>, <tag>)``. + +Alternatively, the full commit ``<hash>`` may be used. + +Revising Commit Messages +^^^^^^^^^^^^^^^^^^^^^^^^ + +Reviewers are encouraged to ask the committer to amend commit messages to +follow these guidelines, but prefer to focus on the changes themselves as a +first priority. Maintainers will also make a check of commit messages before +merging. + Topic Testing ============= @@ -246,6 +332,14 @@ branch (e.g. ``master``) branch followed by a sequence of merges each integrating changes from an open MR that has been staged for integration testing. Each time the target integration branch is updated the stage is rebuilt automatically by merging the staged MR topics again. +The branch is stored in the upstream repository by special refs: + +* ``refs/stage/master/head``: The current topic stage branch. + This is used by continuous builds that report to CDash. +* ``refs/stage/master/nightly/latest``: Topic stage as of 1am UTC each night. + This is used by most nightly builds that report to CDash. +* ``refs/stage/master/nightly/<yyyy>/<mm>/<dd>``: Topic stage as of 1am UTC + on the date specified. This is used for historical reference. `CMake GitLab Project Developers`_ may stage a MR for integration testing by adding a comment with a command among the `comment trailing lines`_:: @@ -283,7 +377,15 @@ command is needed to stage it again. Resolve ======= -A MR may be resolved in one of the following ways. +The workflow used by the CMake project supports a number of different +ways in which a MR can be moved to a resolved state. In addition to +the conventional practices of merging or closing a MR without merging it, +a MR can also be moved to a quasi-resolved state pending some action. +This may involve moving discussion to an issue or it may be the result of +an extended period of inactivity. These quasi-resolved states are used +to help manage the relatively large number of MRs the project receives +and are not an indication of the changes being rejected. The following +sections explain the different resolutions a MR may be given. Merge ----- @@ -324,11 +426,14 @@ The ``Do: merge`` command accepts the following arguments: branch in the constructed merge commit message. Additionally, ``Do: merge`` extracts configuration from trailing lines -in the MR description: +in the MR description (the following have no effect if used in a MR +comment instead): * ``Topic-rename: <topic>``: substitute ``<topic>`` for the name of the MR topic branch in the constructed merge commit message. - The ``-t`` option overrides this. + It is also used in merge commits constructed by ``Do: stage``. + The ``-t`` option to a ``Do: merge`` command overrides any topic + rename set in the MR description. .. _`CMake GitLab Project Masters`: https://gitlab.kitware.com/cmake/cmake/settings/members @@ -336,15 +441,68 @@ Close ----- If review has concluded that the MR should not be integrated then it -may be closed through GitLab. +may be closed through GitLab. This would normally be a final state +with no expectation that the MR would be re-opened in the future. +It is also used when a MR is being superseded by another separate one, +in which case a reference to the new MR should be added to the MR being +closed. Expire ------ If progress on a MR has stalled for a while, it may be closed with a ``workflow:expired`` label and a comment indicating that the MR has -been closed due to inactivity. - -Contributors are welcome to re-open an expired MR when they are ready -to continue work. Please re-open *before* pushing an update to the -MR topic branch to ensure GitLab will still act on the association. +been closed due to inactivity (it may also be done where the MR is blocked +for an extended period by work in a different MR). This is not an +indication that there is a problem with the MR's content, it is only a +practical measure to allow the reviewers to focus attention on MRs that +are actively being worked on. As a guide, the average period of inactivity +before transitioning a MR to the expired state would be around 2 weeks, +but this may decrease to 1 week or less when there is a high number of +open merge requests. + +Reviewers would usually provide a message similar to the following when +resolving a MR as expired:: + + Closing for now. @<MR-author> please re-open when ready to continue work. + +This is to make it clear to contributors that they are welcome to re-open +the expired MR when they are ready to return to working on it and moving +it forward. In the meantime, the MR will appear as ``Closed`` in GitLab, +but it can be differentiated from permanently closed MRs by the presence +of the ``workflow:expired`` label. + +**NOTE:** Please re-open *before* pushing an update to the MR topic branch +to ensure GitLab will still act on the association. If changes are pushed +before re-opening the MR, the reviewer should initiate a ``Do: check`` to +force GitLab to act on the updates. + +External Discussion +------------------- + +In some situations, a series of comments on a MR may develop into a more +involved discussion, or it may become apparent that there are broader +discussions that need to take place before the MR can move forward in an +agreed direction. Such discussions are better suited to GitLab issues +rather than in a MR because MRs may be superseded by a different MR, or +the set of changes may evolve to look quite different to the context in +which the discussions began. When this occurs, reviewers may ask the +MR author to open an issue to discuss things there and they will transition +the MR to a resolved state with the label ``workflow:external-discussion``. +The MR will appear in GitLab as closed, but it can be differentiated from +permanently closed MRs by the presence of the ``workflow:external-discussion`` +label. Reviewers should leave a message clearly explaining the action +so that the MR author understands that the MR closure is temporary and +it is clear what actions need to happen next. The following is an example +of such a message, but it will usually be necessary to tailor the message +to the individual situation:: + + The desired behavior here looks to be more involved than first thought. + Please open an issue so we can discuss the relevant details there. + Once the path forward is clear, we can re-open this MR and continue work. + +When the discussion in the associated issue runs its course and the way +forward is clear, the MR can be re-opened again and the +``workflow:external-discussion`` label removed. Reviewers should ensure +that the issue created contains a reference to the MR so that GitLab +provides a cross-reference to link the two. diff --git a/Help/dev/source.rst b/Help/dev/source.rst index 7e4499559..0f7488be0 100644 --- a/Help/dev/source.rst +++ b/Help/dev/source.rst @@ -9,7 +9,7 @@ See documentation on `CMake Development`_ for more information. C++ Code Style ============== -We use `clang-format`_ version **3.8** to define our style for C++ code in +We use `clang-format`_ version **6.0** to define our style for C++ code in the CMake source tree. See the `.clang-format`_ configuration file for our style settings. Use the `Utilities/Scripts/clang-format.bash`_ script to format source code. It automatically runs ``clang-format`` on the set of @@ -23,38 +23,59 @@ format only a subset of files, such as those that are locally modified. C++ Subset Permitted ==================== -CMake supports compiling as C++98 in addition to C++11 and C++14. -In order to support building on older toolchains some constructs -need to be handled with care: +CMake requires compiling as C++11 or above. However, in order to support +building on older toolchains some constructs need to be handled with care: -* Use ``CM_AUTO_PTR`` instead of ``std::auto_ptr``. +* Do not use ``std::auto_ptr``. - The ``std::auto_ptr`` template is deprecated in C++11. We want to use it - so we can build on C++98 compilers but we do not want to turn off compiler - warnings about deprecated interfaces in general. Use the ``CM_AUTO_PTR`` - macro instead. + The ``std::auto_ptr`` template is deprecated in C++11. Use ``std::unique_ptr``. -* Use ``CM_EQ_DELETE;`` instead of ``= delete;``. +Source Tree Layout +================== - Defining functions as *deleted* is not supported in C++98. Using - ``CM_EQ_DELETE`` will delete the functions if the compiler supports it and - give them no implementation otherwise. Calling such a function will lead - to compiler errors if the compiler supports *deleted* functions and linker - errors otherwise. +The CMake source tree is organized as follows. -* Use ``CM_DISABLE_COPY(Class)`` to mark classes as non-copyable. +* ``Auxiliary/``: + Shell and editor integration files. - The ``CM_DISABLE_COPY`` macro should be used in the private section of a - class to make sure that attempts to copy or assign an instance of the class - lead to compiler errors even if the compiler does not support *deleted* - functions. As a guideline, all polymorphic classes should be made - non-copyable in order to avoid slicing. Classes that are composed of or - derived from non-copyable classes must also be made non-copyable explicitly - with ``CM_DISABLE_COPY``. +* ``Help/``: + Documentation. See the `CMake Documentation Guide`_. -* Use ``size_t`` instead of ``std::size_t``. + * ``Help/dev/``: + Developer documentation. - Various implementations have differing implementation of ``size_t``. - When assigning the result of ``.size()`` on a container for example, - the result should be assigned to ``size_t`` not to ``std::size_t``, - ``unsigned int`` or similar types. + * ``Help/release/dev/``: + Release note snippets for development since last release. + +* ``Licenses/``: + License files for third-party libraries in binary distributions. + +* ``Modules/``: + CMake language modules installed with CMake. + +* ``Packaging/``: + Files used for packaging CMake itself for distribution. + +* ``Source/``: + Source code of CMake itself. + +* ``Templates/``: + Files distributed with CMake as implementation details for generators, + packagers, etc. + +* ``Tests/``: + The test suite. See `Tests/README.rst`_. + +* ``Utilities/``: + Scripts, third-party source code. + + * ``Utilities/Sphinx/``: + Sphinx configuration to build CMake user documentation. + + * ``Utilities/Release/``: + Scripts used to package CMake itself for distribution on ``cmake.org``. + See `Utilities/Release/README.rst`_. + +.. _`CMake Documentation Guide`: documentation.rst +.. _`Tests/README.rst`: ../../Tests/README.rst +.. _`Utilities/Release/README.rst`: ../../Utilities/Release/README.rst diff --git a/Help/dev/testing.rst b/Help/dev/testing.rst index 731930c8f..23d0ca3f2 100644 --- a/Help/dev/testing.rst +++ b/Help/dev/testing.rst @@ -16,7 +16,7 @@ welcome to provide testing machines in order to help keep support for their platforms working. The `CMake Dashboard Scripts Repository`_ provides CTest scripts to drive -nightly, continous, and experimental testing of CMake. Use the following +nightly, continuous, and experimental testing of CMake. Use the following commands to set up a new integration testing client: .. code-block:: console @@ -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 ------------------ diff --git a/Help/envvar/ASM_DIALECT.rst b/Help/envvar/ASM_DIALECT.rst new file mode 100644 index 000000000..a06e3cba2 --- /dev/null +++ b/Help/envvar/ASM_DIALECT.rst @@ -0,0 +1,14 @@ +ASM<DIALECT> +------------ + +.. include:: ENV_VAR.txt + +Preferred executable for compiling a specific dialect of assembly language +files. ``ASM<DIALECT>`` can be ``ASM``, ``ASM_NASM`` (Netwide Assembler), +``ASM_MASM`` (Microsoft Assembler) or ``ASM-ATT`` (Assembler AT&T). +Will only be used by CMake on the first configuration to determine +``ASM<DIALECT>`` compiler, after which the value for ``ASM<DIALECT>`` is stored +in the cache as +:variable:`CMAKE_ASM<DIALECT>_COMPILER <CMAKE_<LANG>_COMPILER>`. For subsequent +configuration runs, the environment variable will be ignored in favor of +:variable:`CMAKE_ASM<DIALECT>_COMPILER <CMAKE_<LANG>_COMPILER>`. diff --git a/Help/envvar/ASM_DIALECTFLAGS.rst b/Help/envvar/ASM_DIALECTFLAGS.rst new file mode 100644 index 000000000..3c3b02a76 --- /dev/null +++ b/Help/envvar/ASM_DIALECTFLAGS.rst @@ -0,0 +1,13 @@ +ASM<DIALECT>FLAGS +----------------- + +.. include:: ENV_VAR.txt + +Default compilation flags to be used when compiling a specific dialect of an +assembly language. ``ASM<DIALECT>FLAGS`` can be ``ASMFLAGS``, ``ASM_NASMFLAGS``, +``ASM_MASMFLAGS`` or ``ASM-ATTFLAGS``. Will only be used by CMake on the +first configuration to determine ``ASM_<DIALECT>`` default compilation +flags, after which the value for ``ASM<DIALECT>FLAGS`` is stored in the cache +as ``CMAKE_ASM<DIALECT>_FLAGS <CMAKE_<LANG>_FLAGS>``. For any configuration +run (including the first), the environment variable will be ignored, if the +``CMAKE_ASM<DIALECT>_FLAGS <CMAKE_<LANG>_FLAGS>`` variable is defined. diff --git a/Help/envvar/CC.rst b/Help/envvar/CC.rst new file mode 100644 index 000000000..ef120593e --- /dev/null +++ b/Help/envvar/CC.rst @@ -0,0 +1,11 @@ +CC +-- + +.. include:: ENV_VAR.txt + +Preferred executable for compiling ``C`` language files. Will only be used by +CMake on the first configuration to determine ``C`` compiler, after which the +value for ``CC`` is stored in the cache as +:variable:`CMAKE_C_COMPILER <CMAKE_<LANG>_COMPILER>`. For any configuration run +(including the first), the environment variable will be ignored if the +:variable:`CMAKE_C_COMPILER <CMAKE_<LANG>_COMPILER>` variable is defined. diff --git a/Help/envvar/CFLAGS.rst b/Help/envvar/CFLAGS.rst new file mode 100644 index 000000000..fda9ccc48 --- /dev/null +++ b/Help/envvar/CFLAGS.rst @@ -0,0 +1,11 @@ +CFLAGS +------ + +.. include:: ENV_VAR.txt + +Default compilation flags to be used when compiling ``C`` files. Will only be +used by CMake on the first configuration to determine ``CC`` default compilation +flags, after which the value for ``CFLAGS`` is stored in the cache +as :variable:`CMAKE_C_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration run +(including the first), the environment variable will be ignored if the +:variable:`CMAKE_C_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined. diff --git a/Help/envvar/CMAKE_BUILD_PARALLEL_LEVEL.rst b/Help/envvar/CMAKE_BUILD_PARALLEL_LEVEL.rst new file mode 100644 index 000000000..199ca3e4b --- /dev/null +++ b/Help/envvar/CMAKE_BUILD_PARALLEL_LEVEL.rst @@ -0,0 +1,11 @@ +CMAKE_BUILD_PARALLEL_LEVEL +-------------------------- + +.. include:: ENV_VAR.txt + +Specifies the maximum number of concurrent processes to use when building +using the ``cmake --build`` command line +:ref:`Build Tool Mode <Build Tool Mode>`. + +If this variable is defined empty the native build tool's default number is +used. diff --git a/Help/envvar/CMAKE_CONFIG_TYPE.rst b/Help/envvar/CMAKE_CONFIG_TYPE.rst new file mode 100644 index 000000000..168593d50 --- /dev/null +++ b/Help/envvar/CMAKE_CONFIG_TYPE.rst @@ -0,0 +1,7 @@ +CMAKE_CONFIG_TYPE +----------------- + +.. include:: ENV_VAR.txt + +The default build configuration for :ref:`Build Tool Mode` and +``ctest`` build handler when there is no explicit configuration given. diff --git a/Help/envvar/CMAKE_GENERATOR.rst b/Help/envvar/CMAKE_GENERATOR.rst new file mode 100644 index 000000000..f2d055f10 --- /dev/null +++ b/Help/envvar/CMAKE_GENERATOR.rst @@ -0,0 +1,16 @@ +CMAKE_GENERATOR +--------------- + +.. include:: ENV_VAR.txt + +Specifies the CMake default generator to use when no generator is supplied +with ``-G``. If the provided value doesn't name a generator known by CMake, +the internal default is used. Either way the resulting generator selection +is stored in the :variable:`CMAKE_GENERATOR` variable. + +Some generators may be additionally configured using the environment +variables: + +* :envvar:`CMAKE_GENERATOR_PLATFORM` +* :envvar:`CMAKE_GENERATOR_TOOLSET` +* :envvar:`CMAKE_GENERATOR_INSTANCE` diff --git a/Help/envvar/CMAKE_GENERATOR_INSTANCE.rst b/Help/envvar/CMAKE_GENERATOR_INSTANCE.rst new file mode 100644 index 000000000..1654fa1db --- /dev/null +++ b/Help/envvar/CMAKE_GENERATOR_INSTANCE.rst @@ -0,0 +1,7 @@ +CMAKE_GENERATOR_INSTANCE +------------------------ + +.. include:: ENV_VAR.txt + +Default value for :variable:`CMAKE_GENERATOR_INSTANCE` if no Cache entry is +present. This value is only applied if :envvar:`CMAKE_GENERATOR` is set. diff --git a/Help/envvar/CMAKE_GENERATOR_PLATFORM.rst b/Help/envvar/CMAKE_GENERATOR_PLATFORM.rst new file mode 100644 index 000000000..917b30b14 --- /dev/null +++ b/Help/envvar/CMAKE_GENERATOR_PLATFORM.rst @@ -0,0 +1,8 @@ +CMAKE_GENERATOR_PLATFORM +------------------------ + +.. include:: ENV_VAR.txt + +Default value for :variable:`CMAKE_GENERATOR_PLATFORM` if no Cache entry +is present and no value is specified by :manual:`cmake(1)` ``-A`` option. +This value is only applied if :envvar:`CMAKE_GENERATOR` is set. diff --git a/Help/envvar/CMAKE_GENERATOR_TOOLSET.rst b/Help/envvar/CMAKE_GENERATOR_TOOLSET.rst new file mode 100644 index 000000000..7ac3856a1 --- /dev/null +++ b/Help/envvar/CMAKE_GENERATOR_TOOLSET.rst @@ -0,0 +1,8 @@ +CMAKE_GENERATOR_TOOLSET +----------------------- + +.. include:: ENV_VAR.txt + +Default value for :variable:`CMAKE_GENERATOR_TOOLSET` if no Cache entry +is present and no value is specified by :manual:`cmake(1)` ``-T`` option. +This value is only applied if :envvar:`CMAKE_GENERATOR` is set. diff --git a/Help/envvar/CMAKE_MSVCIDE_RUN_PATH.rst b/Help/envvar/CMAKE_MSVCIDE_RUN_PATH.rst new file mode 100644 index 000000000..77ead4d55 --- /dev/null +++ b/Help/envvar/CMAKE_MSVCIDE_RUN_PATH.rst @@ -0,0 +1,10 @@ +CMAKE_MSVCIDE_RUN_PATH +---------------------- + +.. include:: ENV_VAR.txt + +Extra PATH locations for custom commands when using +:generator:`Visual Studio 9 2008` (or above) generators. + +The ``CMAKE_MSVCIDE_RUN_PATH`` environment variable sets the default value for +the :variable:`CMAKE_MSVCIDE_RUN_PATH` variable if not already explicitly set. diff --git a/Help/envvar/CMAKE_NO_VERBOSE.rst b/Help/envvar/CMAKE_NO_VERBOSE.rst new file mode 100644 index 000000000..149efbd6f --- /dev/null +++ b/Help/envvar/CMAKE_NO_VERBOSE.rst @@ -0,0 +1,8 @@ +CMAKE_NO_VERBOSE +---------------- + +Disables verbose output from CMake when :envvar:`VERBOSE` environment variable +is set. + +Only your build tool of choice will still print verbose output when you start +to actually build your project. diff --git a/Help/envvar/CMAKE_OSX_ARCHITECTURES.rst b/Help/envvar/CMAKE_OSX_ARCHITECTURES.rst new file mode 100644 index 000000000..ef7d5470b --- /dev/null +++ b/Help/envvar/CMAKE_OSX_ARCHITECTURES.rst @@ -0,0 +1,10 @@ +CMAKE_OSX_ARCHITECTURES +----------------------- + +.. include:: ENV_VAR.txt + +Target specific architectures for macOS. + +The ``CMAKE_OSX_ARCHITECTURES`` environment variable sets the default value for +the :variable:`CMAKE_OSX_ARCHITECTURES` variable. See +:prop_tgt:`OSX_ARCHITECTURES` for more information. diff --git a/Help/envvar/CSFLAGS.rst b/Help/envvar/CSFLAGS.rst new file mode 100644 index 000000000..404bb5930 --- /dev/null +++ b/Help/envvar/CSFLAGS.rst @@ -0,0 +1,11 @@ +CSFLAGS +------- + +.. include:: ENV_VAR.txt + +Preferred executable for compiling ``CSharp`` language files. Will only be +used by CMake on the first configuration to determine ``CSharp`` default +compilation flags, after which the value for ``CSFLAGS`` is stored in the cache +as :variable:`CMAKE_CSharp_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration +run (including the first), the environment variable will be ignored if the +:variable:`CMAKE_CSharp_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined. diff --git a/Help/envvar/CTEST_INTERACTIVE_DEBUG_MODE.rst b/Help/envvar/CTEST_INTERACTIVE_DEBUG_MODE.rst new file mode 100644 index 000000000..e1991b2df --- /dev/null +++ b/Help/envvar/CTEST_INTERACTIVE_DEBUG_MODE.rst @@ -0,0 +1,7 @@ +CTEST_INTERACTIVE_DEBUG_MODE +---------------------------- + +.. include:: ENV_VAR.txt + +Environment variable that will exist and be set to ``1`` when a test executed +by :manual:`ctest(1)` is run in interactive mode. diff --git a/Help/envvar/CTEST_OUTPUT_ON_FAILURE.rst b/Help/envvar/CTEST_OUTPUT_ON_FAILURE.rst new file mode 100644 index 000000000..d8b42624f --- /dev/null +++ b/Help/envvar/CTEST_OUTPUT_ON_FAILURE.rst @@ -0,0 +1,9 @@ +CTEST_OUTPUT_ON_FAILURE +----------------------- + +.. include:: ENV_VAR.txt + +Boolean environment variable that controls if the output should be logged for +failed tests. Set the value to ``1``, ``True``, or ``ON`` to enable output on failure. +See :manual:`ctest(1)` for more information on controlling output of failed +tests. diff --git a/Help/envvar/CTEST_PARALLEL_LEVEL.rst b/Help/envvar/CTEST_PARALLEL_LEVEL.rst new file mode 100644 index 000000000..fd4936e37 --- /dev/null +++ b/Help/envvar/CTEST_PARALLEL_LEVEL.rst @@ -0,0 +1,7 @@ +CTEST_PARALLEL_LEVEL +-------------------- + +.. include:: ENV_VAR.txt + +Specify the number of tests for CTest to run in parallel. See :manual:`ctest(1)` +for more information on parallel test execution. diff --git a/Help/envvar/CTEST_PROGRESS_OUTPUT.rst b/Help/envvar/CTEST_PROGRESS_OUTPUT.rst new file mode 100644 index 000000000..b36a6b8c2 --- /dev/null +++ b/Help/envvar/CTEST_PROGRESS_OUTPUT.rst @@ -0,0 +1,16 @@ +CTEST_PROGRESS_OUTPUT +--------------------- + +.. include:: ENV_VAR.txt + +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. diff --git a/Help/envvar/CTEST_USE_LAUNCHERS_DEFAULT.rst b/Help/envvar/CTEST_USE_LAUNCHERS_DEFAULT.rst new file mode 100644 index 000000000..79dbb79f3 --- /dev/null +++ b/Help/envvar/CTEST_USE_LAUNCHERS_DEFAULT.rst @@ -0,0 +1,6 @@ +CTEST_USE_LAUNCHERS_DEFAULT +--------------------------- + +.. include:: ENV_VAR.txt + +Initializes the :variable:`CTEST_USE_LAUNCHERS` variable if not already defined. diff --git a/Help/envvar/CUDACXX.rst b/Help/envvar/CUDACXX.rst new file mode 100644 index 000000000..10c0f9dd7 --- /dev/null +++ b/Help/envvar/CUDACXX.rst @@ -0,0 +1,11 @@ +CUDACXX +------- + +.. include:: ENV_VAR.txt + +Preferred executable for compiling ``CUDA`` language files. Will only be used by +CMake on the first configuration to determine ``CUDA`` compiler, after which the +value for ``CUDA`` is stored in the cache as +:variable:`CMAKE_CUDA_COMPILER <CMAKE_<LANG>_COMPILER>`. For any configuration +run (including the first), the environment variable will be ignored if the +:variable:`CMAKE_CUDA_COMPILER <CMAKE_<LANG>_COMPILER>` variable is defined. diff --git a/Help/envvar/CUDAFLAGS.rst b/Help/envvar/CUDAFLAGS.rst new file mode 100644 index 000000000..4456d6bf8 --- /dev/null +++ b/Help/envvar/CUDAFLAGS.rst @@ -0,0 +1,11 @@ +CUDAFLAGS +--------- + +.. include:: ENV_VAR.txt + +Default compilation flags to be used when compiling ``CUDA`` files. Will only be +used by CMake on the first configuration to determine ``CUDA`` default +compilation flags, after which the value for ``CUDAFLAGS`` is stored in the +cache as :variable:`CMAKE_CUDA_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration +run (including the first), the environment variable will be ignored if +the :variable:`CMAKE_CUDA_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined. diff --git a/Help/envvar/CUDAHOSTCXX.rst b/Help/envvar/CUDAHOSTCXX.rst new file mode 100644 index 000000000..b9f65bd1e --- /dev/null +++ b/Help/envvar/CUDAHOSTCXX.rst @@ -0,0 +1,15 @@ +CUDAHOSTCXX +----------- + +.. include:: ENV_VAR.txt + +Preferred executable for compiling host code when compiling ``CUDA`` +language files. Will only be used by CMake on the first configuration to +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. diff --git a/Help/envvar/CXX.rst b/Help/envvar/CXX.rst new file mode 100644 index 000000000..d6553501a --- /dev/null +++ b/Help/envvar/CXX.rst @@ -0,0 +1,11 @@ +CXX +--- + +.. include:: ENV_VAR.txt + +Preferred executable for compiling ``CXX`` language files. Will only be used by +CMake on the first configuration to determine ``CXX`` compiler, after which the +value for ``CXX`` is stored in the cache as +:variable:`CMAKE_CXX_COMPILER <CMAKE_<LANG>_COMPILER>`. For any configuration +run (including the first), the environment variable will be ignored if the +:variable:`CMAKE_CXX_COMPILER <CMAKE_<LANG>_COMPILER>` variable is defined. diff --git a/Help/envvar/CXXFLAGS.rst b/Help/envvar/CXXFLAGS.rst new file mode 100644 index 000000000..d7296dca0 --- /dev/null +++ b/Help/envvar/CXXFLAGS.rst @@ -0,0 +1,11 @@ +CXXFLAGS +-------- + +.. include:: ENV_VAR.txt + +Default compilation flags to be used when compiling ``CXX`` (C++) files. Will +only be used by CMake on the first configuration to determine ``CXX`` default +compilation flags, after which the value for ``CXXFLAGS`` is stored in the cache +as :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration run ( +including the first), the environment variable will be ignored if +the :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined. diff --git a/Help/envvar/DASHBOARD_TEST_FROM_CTEST.rst b/Help/envvar/DASHBOARD_TEST_FROM_CTEST.rst new file mode 100644 index 000000000..6a52d6494 --- /dev/null +++ b/Help/envvar/DASHBOARD_TEST_FROM_CTEST.rst @@ -0,0 +1,8 @@ +DASHBOARD_TEST_FROM_CTEST +------------------------- + +.. include:: ENV_VAR.txt + +Environment variable that will exist when a test executed by :manual:`ctest(1)` +is run in non-interactive mode. The value will be equal to +:variable:`CMAKE_VERSION`. diff --git a/Help/envvar/DESTDIR.rst b/Help/envvar/DESTDIR.rst new file mode 100644 index 000000000..d2144ae7c --- /dev/null +++ b/Help/envvar/DESTDIR.rst @@ -0,0 +1,21 @@ +DESTDIR +------- + +.. include:: ENV_VAR.txt + +On UNIX one can use the ``DESTDIR`` mechanism in order to relocate the +whole installation. ``DESTDIR`` means DESTination DIRectory. It is +commonly used by makefile users in order to install software at +non-default location. It is usually invoked like this: + +:: + + make DESTDIR=/home/john install + +which will install the concerned software using the installation +prefix, e.g. ``/usr/local`` prepended with the ``DESTDIR`` value which +finally gives ``/home/john/usr/local``. + +WARNING: ``DESTDIR`` may not be used on Windows because installation +prefix usually contains a drive letter like in ``C:/Program Files`` +which cannot be prepended with some other prefix. diff --git a/Help/envvar/ENV_VAR.txt b/Help/envvar/ENV_VAR.txt new file mode 100644 index 000000000..e1e70cd99 --- /dev/null +++ b/Help/envvar/ENV_VAR.txt @@ -0,0 +1,3 @@ +This is a CMake :ref:`Environment Variable <CMake Language +Environment Variables>`. Its initial value is taken from +the calling process environment. diff --git a/Help/envvar/FC.rst b/Help/envvar/FC.rst new file mode 100644 index 000000000..d6cabbc90 --- /dev/null +++ b/Help/envvar/FC.rst @@ -0,0 +1,12 @@ +FC +-- + +.. include:: ENV_VAR.txt + +Preferred executable for compiling ``Fortran`` language files. Will only be used +by CMake on the first configuration to determine ``Fortran`` compiler, after +which the value for ``Fortran`` is stored in the cache as +:variable:`CMAKE_Fortran_COMPILER <CMAKE_<LANG>_COMPILER>`. For any +configuration run (including the first), the environment variable will be +ignored if the :variable:`CMAKE_Fortran_COMPILER <CMAKE_<LANG>_COMPILER>` +variable is defined. diff --git a/Help/envvar/FFLAGS.rst b/Help/envvar/FFLAGS.rst new file mode 100644 index 000000000..02d3c3461 --- /dev/null +++ b/Help/envvar/FFLAGS.rst @@ -0,0 +1,11 @@ +FFLAGS +------ + +.. include:: ENV_VAR.txt + +Default compilation flags to be used when compiling ``Fortran`` files. Will only +be used by CMake on the first configuration to determine ``Fortran`` default +compilation flags, after which the value for ``FFLAGS`` is stored in the cache +as :variable:`CMAKE_Fortran_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration +run (including the first), the environment variable will be ignored if +the :variable:`CMAKE_Fortran_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined. diff --git a/Help/envvar/LDFLAGS.rst b/Help/envvar/LDFLAGS.rst new file mode 100644 index 000000000..816d6ef77 --- /dev/null +++ b/Help/envvar/LDFLAGS.rst @@ -0,0 +1,12 @@ +LDFLAGS +------- + +.. include:: ENV_VAR.txt + +Will only be used by CMake on the first configuration to determine the default +linker flags, after which the value for ``LDFLAGS`` is stored in the cache +as :variable:`CMAKE_EXE_LINKER_FLAGS_INIT`, +:variable:`CMAKE_SHARED_LINKER_FLAGS_INIT`, and +:variable:`CMAKE_MODULE_LINKER_FLAGS_INIT`. For any configuration run +(including the first), the environment variable will be ignored if the +equivalent ``CMAKE_<TYPE>_LINKER_FLAGS_INIT`` variable is defined. diff --git a/Help/envvar/MACOSX_DEPLOYMENT_TARGET.rst b/Help/envvar/MACOSX_DEPLOYMENT_TARGET.rst new file mode 100644 index 000000000..662bd03ec --- /dev/null +++ b/Help/envvar/MACOSX_DEPLOYMENT_TARGET.rst @@ -0,0 +1,10 @@ +MACOSX_DEPLOYMENT_TARGET +------------------------ + +.. include:: ENV_VAR.txt + +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 +the :variable:`CMAKE_OSX_DEPLOYMENT_TARGET` variable. diff --git a/Help/envvar/PackageName_ROOT.rst b/Help/envvar/PackageName_ROOT.rst new file mode 100644 index 000000000..82b0a069e --- /dev/null +++ b/Help/envvar/PackageName_ROOT.rst @@ -0,0 +1,17 @@ +<PackageName>_ROOT +------------------ + +.. include:: ENV_VAR.txt + +Calls to :command:`find_package(<PackageName>)` will search in prefixes +specified by the ``<PackageName>_ROOT`` environment variable, where +``<PackageName>`` is the name given to the :command:`find_package` call +and ``_ROOT`` is literal. For example, ``find_package(Foo)`` will search +prefixes specified in the ``Foo_ROOT`` environment variable (if set). +See policy :policy:`CMP0074`. + +This variable may hold a single prefix or a list of prefixes separated +by ``:`` on UNIX or ``;`` on Windows (the same as the ``PATH`` environment +variable convention on those platforms). + +See also the :variable:`<PackageName>_ROOT` CMake variable. diff --git a/Help/envvar/RC.rst b/Help/envvar/RC.rst new file mode 100644 index 000000000..557520e8f --- /dev/null +++ b/Help/envvar/RC.rst @@ -0,0 +1,11 @@ +RC +-- + +.. include:: ENV_VAR.txt + +Preferred executable for compiling ``resource`` files. Will only be used by CMake +on the first configuration to determine ``resource`` compiler, after which the +value for ``RC`` is stored in the cache as +:variable:`CMAKE_RC_COMPILER <CMAKE_<LANG>_COMPILER>`. For any configuration run +(including the first), the environment variable will be ignored if the +:variable:`CMAKE_RC_COMPILER <CMAKE_<LANG>_COMPILER>` variable is defined. diff --git a/Help/envvar/RCFLAGS.rst b/Help/envvar/RCFLAGS.rst new file mode 100644 index 000000000..45419fed1 --- /dev/null +++ b/Help/envvar/RCFLAGS.rst @@ -0,0 +1,11 @@ +RCFLAGS +------- + +.. include:: ENV_VAR.txt + +Default compilation flags to be used when compiling ``resource`` files. Will +only be used by CMake on the first configuration to determine ``resource`` +default compilation flags, after which the value for ``RCFLAGS`` is stored in +the cache as :variable:`CMAKE_RC_FLAGS <CMAKE_<LANG>_FLAGS>`. For any +configuration run (including the first), the environment variable will be ignored +if the :variable:`CMAKE_RC_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined. diff --git a/Help/envvar/SWIFTC.rst b/Help/envvar/SWIFTC.rst new file mode 100644 index 000000000..b12e51df9 --- /dev/null +++ b/Help/envvar/SWIFTC.rst @@ -0,0 +1,11 @@ +SWIFTC +------ + +.. include:: ENV_VAR.txt + +Preferred executable for compiling ``Swift`` language files. Will only be used by +CMake on the first configuration to determine ``Swift`` compiler, after which the +value for ``SWIFTC`` is stored in the cache as +:variable:`CMAKE_Swift_COMPILER <CMAKE_<LANG>_COMPILER>`. For any configuration run +(including the first), the environment variable will be ignored if the +:variable:`CMAKE_Swift_COMPILER <CMAKE_<LANG>_COMPILER>` variable is defined. diff --git a/Help/envvar/VERBOSE.rst b/Help/envvar/VERBOSE.rst new file mode 100644 index 000000000..2d775a5be --- /dev/null +++ b/Help/envvar/VERBOSE.rst @@ -0,0 +1,10 @@ +VERBOSE +------- + +Activates verbose output from CMake and your build tools of choice when +you start to actually build your project. + +Note that any given value is ignored. It's just checked for existence. + +See also :ref:`Build Tool Mode <Build Tool Mode>` and +:envvar:`CMAKE_NO_VERBOSE` environment variable diff --git a/Help/generator/CodeBlocks.rst b/Help/generator/CodeBlocks.rst index d03cb0ce6..d830542eb 100644 --- a/Help/generator/CodeBlocks.rst +++ b/Help/generator/CodeBlocks.rst @@ -4,10 +4,14 @@ CodeBlocks Generates CodeBlocks project files. Project files for CodeBlocks will be created in the top directory and -in every subdirectory which features a CMakeLists.txt file containing -a PROJECT() call. Additionally a hierarchy of makefiles is generated -into the build tree. The appropriate make program can build the -project through the default make target. A "make install" target is +in every subdirectory which features a ``CMakeLists.txt`` file containing +a :command:`project` call. Additionally a hierarchy of makefiles is generated +into the build tree. +The :variable:`CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES` variable may +be set to ``ON`` to exclude any files which are located outside of +the project root directory. +The appropriate make program can build the +project through the default ``all`` target. An ``install`` target is also provided. This "extra" generator may be specified as: diff --git a/Help/generator/CodeLite.rst b/Help/generator/CodeLite.rst index 3e60aa6d6..46fa5bef7 100644 --- a/Help/generator/CodeLite.rst +++ b/Help/generator/CodeLite.rst @@ -7,11 +7,11 @@ Project files for CodeLite will be created in the top directory and in every subdirectory which features a CMakeLists.txt file containing a :command:`project` call. The :variable:`CMAKE_CODELITE_USE_TARGETS` variable may be set to ``ON`` -to change the default behaviour from projects to targets as the basis +to change the default behavior from projects to targets as the basis for project files. The appropriate make program can build the -project through the default make target. A "make install" target is -also provided. +project through the default ``all`` target. An ``install`` target +is also provided. This "extra" generator may be specified as: diff --git a/Help/generator/Eclipse CDT4.rst b/Help/generator/Eclipse CDT4.rst index eb68bf094..634e2b6dd 100644 --- a/Help/generator/Eclipse CDT4.rst +++ b/Help/generator/Eclipse CDT4.rst @@ -7,7 +7,7 @@ Project files for Eclipse will be created in the top directory. In out of source builds, a linked resource to the top level source directory will be created. Additionally a hierarchy of makefiles is generated into the build tree. The appropriate make program can build -the project through the default make target. A "make install" target +the project through the default ``all`` target. An ``install`` target is also provided. This "extra" generator may be specified as: diff --git a/Help/generator/Green Hills MULTI.rst b/Help/generator/Green Hills MULTI.rst index 4d3169026..dffc6795d 100644 --- a/Help/generator/Green Hills MULTI.rst +++ b/Help/generator/Green Hills MULTI.rst @@ -3,12 +3,65 @@ Green Hills MULTI Generates Green Hills MULTI project files (experimental, work-in-progress). -Customizations are available through the following cache variables: +The buildsystem has predetermined build-configuration settings that can be controlled +via the :variable:`CMAKE_BUILD_TYPE` variable. + +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>`` option can be used to set the directory location of the toolset. +Both absolute and relative paths are valid. Relative paths use ``GHS_TOOLSET_ROOT`` +as the root. If the toolset is not specified then the latest toolset found in +``GHS_TOOLSET_ROOT`` will be used. + +Cache variables that are used for toolset and target system customization: + +* ``GHS_TARGET_PLATFORM`` + + | Defaults to ``integrity``. + | Usual values are ``integrity``, ``threadx``, ``uvelosity``, ``velosity``, + ``vxworks``, ``standalone``. + +* ``GHS_PRIMARY_TARGET`` + + | Sets ``primaryTarget`` entry in project file. + | Defaults to ``<arch>_<GHS_TARGET_PLATFORM>.tgt``. + +* ``GHS_TOOLSET_ROOT`` + + | Root path for ``toolset`` searches. + | Defaults to ``C:/ghs`` in Windows or ``/usr/ghs`` in Linux. + +* ``GHS_OS_ROOT`` + + | Root path for RTOS searches. + | Defaults to ``C:/ghs`` in Windows or ``/usr/ghs`` in Linux. + +* ``GHS_OS_DIR`` and ``GHS_OS_DIR_OPTION`` + + | Sets ``-os_dir`` entry in project file. + | Defaults to latest platform OS installation at ``GHS_OS_ROOT``. Set this value if + a specific RTOS is to be used. + | ``GHS_OS_DIR_OPTION`` default value is ``-os_dir``. * ``GHS_BSP_NAME`` + + | Sets ``-bsp`` entry in project file. + | Defaults to ``sim<arch>`` for ``integrity`` platforms. + +Customizations are available through the following cache variables: + * ``GHS_CUSTOMIZATION`` * ``GHS_GPJ_MACROS`` -* ``GHS_OS_DIR`` + +The following properties are available: + +* :prop_tgt:`GHS_INTEGRITY_APP` +* :prop_tgt:`GHS_NO_SOURCE_GROUP_FILE` .. note:: This generator is deemed experimental as of CMake |release| diff --git a/Help/generator/KDevelop3.rst b/Help/generator/KDevelop3.rst deleted file mode 100644 index eaa218bc8..000000000 --- a/Help/generator/KDevelop3.rst +++ /dev/null @@ -1,25 +0,0 @@ -KDevelop3 ---------- - -Generates KDevelop 3 project files. - -Project files for KDevelop 3 will be created in the top directory and -in every subdirectory which features a CMakeLists.txt file containing -a PROJECT() call. If you change the settings using KDevelop cmake -will try its best to keep your changes when regenerating the project -files. Additionally a hierarchy of UNIX makefiles is generated into -the build tree. Any standard UNIX-style make program can build the -project through the default make target. A "make install" target is -also provided. - -This "extra" generator may be specified as: - -``KDevelop3 - Unix Makefiles`` - Generate with :generator:`Unix Makefiles`. - -``KDevelop3`` - Generate with :generator:`Unix Makefiles`. - - For historical reasons this extra generator may be specified - directly as the main generator and it will be used as the - extra generator with :generator:`Unix Makefiles` automatically. diff --git a/Help/generator/Kate.rst b/Help/generator/Kate.rst index 9b61a93b3..129bf631b 100644 --- a/Help/generator/Kate.rst +++ b/Help/generator/Kate.rst @@ -5,10 +5,10 @@ Generates Kate project files. A project file for Kate will be created in the top directory in the top level build directory. -To use it in kate, the Project plugin must be enabled. -The project file is loaded in kate simply by opening the -ProjectName.kateproject file in the editor. -If the kate Build-plugin is enabled, all targets generated by CMake are +To use it in Kate, the Project plugin must be enabled. +The project file is loaded in Kate by opening the +``ProjectName.kateproject`` file in the editor. +If the Kate Build-plugin is enabled, all targets generated by CMake are available for building. This "extra" generator may be specified as: diff --git a/Help/generator/MSYS Makefiles.rst b/Help/generator/MSYS Makefiles.rst index f7cfa4461..75b9fe531 100644 --- a/Help/generator/MSYS Makefiles.rst +++ b/Help/generator/MSYS Makefiles.rst @@ -1,7 +1,8 @@ MSYS Makefiles -------------- -Generates makefiles for use with MSYS ``make`` under the MSYS shell. +Generates makefiles for use with MSYS (Minimal SYStem) +``make`` under the MSYS shell. Use this generator in a MSYS shell prompt and using ``make`` as the build tool. The generated makefiles use ``/bin/sh`` as the shell to launch build diff --git a/Help/generator/MinGW Makefiles.rst b/Help/generator/MinGW Makefiles.rst index 9fe5fe3e5..134ea7094 100644 --- a/Help/generator/MinGW Makefiles.rst +++ b/Help/generator/MinGW Makefiles.rst @@ -4,7 +4,8 @@ MinGW Makefiles Generates makefiles for use with ``mingw32-make`` under a Windows command prompt. -Use this generator under a Windows command prompt with MinGW in the ``PATH`` +Use this generator under a Windows command prompt with +MinGW (Minimalist GNU for Windows) in the ``PATH`` and using ``mingw32-make`` as the build tool. The generated makefiles use ``cmd.exe`` as the shell to launch build rules. They are not compatible with MSYS or a unix shell. diff --git a/Help/generator/Ninja.rst b/Help/generator/Ninja.rst index 3bbd9dcbe..c75d2c4cf 100644 --- a/Help/generator/Ninja.rst +++ b/Help/generator/Ninja.rst @@ -3,9 +3,9 @@ Ninja Generates build.ninja files. -A build.ninja file is generated into the build tree. Recent versions -of the ninja program can build the project through the "all" target. -An "install" target is also provided. +A ``build.ninja`` file is generated into the build tree. Use the ninja +program to build the project through the ``all`` target and install the +project through the ``install`` (or ``install/strip``) target. For each subdirectory ``sub/dir`` of the project, additional targets are generated: @@ -16,6 +16,13 @@ are generated: ``sub/dir/install`` Runs the install step in the subdirectory, if any. +``sub/dir/install/strip`` + Runs the install step in the subdirectory followed by a ``CMAKE_STRIP`` command, + if any. + + The ``CMAKE_STRIP`` variable will contain the platform's ``strip`` utility, which + removes symbols information from generated binaries. + ``sub/dir/test`` Runs the test step in the subdirectory, if any. diff --git a/Help/generator/Sublime Text 2.rst b/Help/generator/Sublime Text 2.rst index 0597a9528..0a07ea983 100644 --- a/Help/generator/Sublime Text 2.rst +++ b/Help/generator/Sublime Text 2.rst @@ -4,11 +4,11 @@ Sublime Text 2 Generates Sublime Text 2 project files. Project files for Sublime Text 2 will be created in the top directory -and in every subdirectory which features a CMakeLists.txt file -containing a PROJECT() call. Additionally Makefiles (or build.ninja -files) are generated into the build tree. The appropriate make -program can build the project through the default make target. A -"make install" target is also provided. +and in every subdirectory which features a ``CMakeLists.txt`` file +containing a :command:`project` call. Additionally ``Makefiles`` +(or ``build.ninja`` files) are generated into the build tree. +The appropriate make program can build the project through the default ``all`` +target. An ``install`` target is also provided. This "extra" generator may be specified as: diff --git a/Help/generator/Unix Makefiles.rst b/Help/generator/Unix Makefiles.rst index 97d74a853..dfe4ecbd9 100644 --- a/Help/generator/Unix Makefiles.rst +++ b/Help/generator/Unix Makefiles.rst @@ -3,6 +3,29 @@ Unix Makefiles Generates standard UNIX makefiles. -A hierarchy of UNIX makefiles is generated into the build tree. Any -standard UNIX-style make program can build the project through the -default make target. A "make install" target is also provided. +A hierarchy of UNIX makefiles is generated into the build tree. Use +any standard UNIX-style make program to build the project through +the ``all`` target and install the project through the ``install`` +(or ``install/strip``) target. + +For each subdirectory ``sub/dir`` of the project a UNIX makefile will +be created, containing the following targets: + +``all`` + Depends on all targets required by the subdirectory. + +``install`` + Runs the install step in the subdirectory, if any. + +``install/strip`` + Runs the install step in the subdirectory followed by a ``CMAKE_STRIP`` command, + if any. + + The ``CMAKE_STRIP`` variable will contain the platform's ``strip`` utility, which + removes symbols information from generated binaries. + +``test`` + Runs the test step in the subdirectory, if any. + +``package`` + Runs the package step in the subdirectory, if any. diff --git a/Help/generator/VS_TOOLSET_HOST_ARCH.txt b/Help/generator/VS_TOOLSET_HOST_ARCH.txt index 5d13e7741..029363115 100644 --- a/Help/generator/VS_TOOLSET_HOST_ARCH.txt +++ b/Help/generator/VS_TOOLSET_HOST_ARCH.txt @@ -1,6 +1,7 @@ For each toolset that comes with this version of Visual Studio, there are -variants that are themselves compiled for 32-bit (x86) and 64-bit (x64) hosts -(independent of the architecture they target). By default Visual Studio -chooses the 32-bit variant even on a 64-bit host. One may request use of the -64-bit host tools by adding a ``host=x64`` option to the toolset specification. +variants that are themselves compiled for 32-bit (``x86``) and +64-bit (``x64``) hosts (independent of the architecture they target). +|VS_TOOLSET_HOST_ARCH_DEFAULT| +One may explicitly request use of either the 32-bit or 64-bit host tools +by adding either ``host=x86`` or ``host=x64`` to the toolset specification. See the :variable:`CMAKE_GENERATOR_TOOLSET` variable for details. diff --git a/Help/generator/Visual Studio 10 2010.rst b/Help/generator/Visual Studio 10 2010.rst index 04eef1039..4bf9a8f15 100644 --- a/Help/generator/Visual Studio 10 2010.rst +++ b/Help/generator/Visual Studio 10 2010.rst @@ -3,11 +3,31 @@ 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 default target platform name (architecture) is ``Win32``. + +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 +35,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 ^^^^^^^^^^^^^^^^^ diff --git a/Help/generator/Visual Studio 11 2012.rst b/Help/generator/Visual Studio 11 2012.rst index 347a153b9..5d89a6e7c 100644 --- a/Help/generator/Visual Studio 11 2012.rst +++ b/Help/generator/Visual Studio 11 2012.rst @@ -3,11 +3,33 @@ 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 default target platform name (architecture) is ``Win32``. + +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 +40,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 ^^^^^^^^^^^^^^^^^ diff --git a/Help/generator/Visual Studio 12 2013.rst b/Help/generator/Visual Studio 12 2013.rst index 5071b20ce..fb8e021bc 100644 --- a/Help/generator/Visual Studio 12 2013.rst +++ b/Help/generator/Visual Studio 12 2013.rst @@ -3,11 +3,31 @@ 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 default target platform name (architecture) is ``Win32``. + +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 +35,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 ^^^^^^^^^^^^^^^^^ @@ -25,4 +42,7 @@ The ``v120`` toolset that comes with Visual Studio 12 2013 is selected by default. The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps via the :manual:`cmake(1)` ``-T`` option, to specify another toolset. +.. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace:: + By default this generator uses the 32-bit variant even on a 64-bit host. + .. include:: VS_TOOLSET_HOST_ARCH.txt diff --git a/Help/generator/Visual Studio 14 2015.rst b/Help/generator/Visual Studio 14 2015.rst index 64254b579..7383f7a6f 100644 --- a/Help/generator/Visual Studio 14 2015.rst +++ b/Help/generator/Visual Studio 14 2015.rst @@ -3,11 +3,28 @@ 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 default target platform name (architecture) is ``Win32``. + +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``. @@ -22,4 +39,7 @@ The ``v140`` toolset that comes with Visual Studio 14 2015 is selected by default. The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps via the :manual:`cmake(1)` ``-T`` option, to specify another toolset. +.. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace:: + By default this generator uses the 32-bit variant even on a 64-bit host. + .. include:: VS_TOOLSET_HOST_ARCH.txt diff --git a/Help/generator/Visual Studio 15 2017.rst b/Help/generator/Visual Studio 15 2017.rst index 2ac044968..7e6f0fb20 100644 --- a/Help/generator/Visual Studio 15 2017.rst +++ b/Help/generator/Visual Studio 15 2017.rst @@ -3,11 +3,45 @@ 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 +^^^^^^^^^^^^^ + +Only Visual C++ and C# projects may be generated. Other types of +projects (JavaScript, Powershell, Python, etc.) are not supported. + +Instance Selection +^^^^^^^^^^^^^^^^^^ + +VS 2017 supports multiple installations on the same machine. +The :variable:`CMAKE_GENERATOR_INSTANCE` variable may be set as a +cache entry containing the absolute path to a Visual Studio instance. +If the value is not specified explicitly by the user or a toolchain file, +CMake queries the Visual Studio Installer to locate VS instances, chooses +one, and sets the variable as a cache entry to hold the value persistently. + +When CMake first chooses an instance, if the ``VS150COMNTOOLS`` environment +variable is set and points to the ``Common7/Tools`` directory within +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 default target platform name (architecture) is ``Win32``. + +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 this generator name: +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``. @@ -15,18 +49,6 @@ a target platform name optionally at the end of this generator name: ``Visual Studio 15 2017 ARM`` Specify target platform ``ARM``. -Instance Selection -^^^^^^^^^^^^^^^^^^ - -VS 2017 supports multiple installations on the same machine. -CMake queries the Visual Studio Installer to locate VS instances. -If more than one instance is installed we do not define which one -is chosen by default. If the ``VS150COMNTOOLS`` environment variable -is set and points to the ``Common7/Tools`` directory within one of -the instances, that instance will be used. The environment variable -must remain consistently set whenever CMake is re-run within a given -build tree. - Toolset Selection ^^^^^^^^^^^^^^^^^ @@ -34,4 +56,7 @@ The ``v141`` toolset that comes with Visual Studio 15 2017 is selected by default. The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps via the :manual:`cmake(1)` ``-T`` option, to specify another toolset. +.. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace:: + By default this generator uses the 32-bit variant even on a 64-bit host. + .. include:: VS_TOOLSET_HOST_ARCH.txt diff --git a/Help/generator/Visual Studio 16 2019.rst b/Help/generator/Visual Studio 16 2019.rst new file mode 100644 index 000000000..4aec7f73c --- /dev/null +++ b/Help/generator/Visual Studio 16 2019.rst @@ -0,0 +1,54 @@ +Visual Studio 16 2019 +--------------------- + +Generates Visual Studio 16 (VS 2019) project files. + +Project Types +^^^^^^^^^^^^^ + +Only Visual C++ and C# projects may be generated. Other types of +projects (JavaScript, Powershell, Python, etc.) are not supported. + +Instance Selection +^^^^^^^^^^^^^^^^^^ + +VS 2019 supports multiple installations on the same machine. +The :variable:`CMAKE_GENERATOR_INSTANCE` variable may be set as a +cache entry containing the absolute path to a Visual Studio instance. +If the value is not specified explicitly by the user or a toolchain file, +CMake queries the Visual Studio Installer to locate VS instances, chooses +one, and sets the variable as a cache entry to hold the value persistently. + +When CMake first chooses an instance, if the ``VS160COMNTOOLS`` environment +variable is set and points to the ``Common7/Tools`` directory within +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 default target platform name (architecture) is that of the host +and is provided in the :variable:`CMAKE_VS_PLATFORM_NAME_DEFAULT` variable. + +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 16 2019" -A Win32`` +* ``cmake -G "Visual Studio 16 2019" -A x64`` +* ``cmake -G "Visual Studio 16 2019" -A ARM`` +* ``cmake -G "Visual Studio 16 2019" -A ARM64`` + +Toolset Selection +^^^^^^^^^^^^^^^^^ + +The ``v142`` toolset that comes with Visual Studio 16 2019 is selected by +default. The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps +via the :manual:`cmake(1)` ``-T`` option, to specify another toolset. + +.. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace:: + By default this generator uses the 64-bit variant on x64 hosts and + the 32-bit variant otherwise. + +.. include:: VS_TOOLSET_HOST_ARCH.txt diff --git a/Help/generator/Visual Studio 8 2005.rst b/Help/generator/Visual Studio 8 2005.rst index acbbf01ae..947e7a597 100644 --- a/Help/generator/Visual Studio 8 2005.rst +++ b/Help/generator/Visual Studio 8 2005.rst @@ -1,23 +1,6 @@ Visual Studio 8 2005 -------------------- -Deprecated. Generates Visual Studio 8 2005 project files. - -.. note:: - This generator is deprecated and will be removed in a future version - of CMake. It will still be possible to build with VS 8 2005 tools - using the :generator:`Visual Studio 10 2010` (or above) generator - with :variable:`CMAKE_GENERATOR_TOOLSET` set to ``v80``, or by - using the :generator:`NMake Makefiles` generator. - -The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set -to specify a target platform 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: - -``Visual Studio 8 2005 Win64`` - Specify target platform ``x64``. - -``Visual Studio 8 2005 <WinCE-SDK>`` - Specify target platform matching a Windows CE SDK name. +Removed. This once generated Visual Studio 8 2005 project files, but +the generator has been removed since CMake 3.12. It is still possible to +build with VS 2005 tools using the :generator:`NMake Makefiles` generator. diff --git a/Help/generator/Visual Studio 9 2008.rst b/Help/generator/Visual Studio 9 2008.rst index 40471b92e..a09d047ae 100644 --- a/Help/generator/Visual Studio 9 2008.rst +++ b/Help/generator/Visual Studio 9 2008.rst @@ -3,11 +3,24 @@ 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 default target platform name (architecture) is ``Win32``. + +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``. diff --git a/Help/generator/Xcode.rst b/Help/generator/Xcode.rst index 968c26a70..d893ac504 100644 --- a/Help/generator/Xcode.rst +++ b/Help/generator/Xcode.rst @@ -3,7 +3,7 @@ Xcode Generate Xcode project files. -This supports Xcode 3.0 and above. +This supports Xcode 5.0 and above. Toolset Selection ^^^^^^^^^^^^^^^^^ diff --git a/Help/guide/tutorial/Complete/CMakeLists.txt b/Help/guide/tutorial/Complete/CMakeLists.txt new file mode 100644 index 000000000..eca79d9df --- /dev/null +++ b/Help/guide/tutorial/Complete/CMakeLists.txt @@ -0,0 +1,120 @@ +cmake_minimum_required(VERSION 3.15) + +# set the project name and version +project(Tutorial VERSION 1.0) + +add_library(tutorial_compiler_flags INTERFACE) +target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11) + +# add compiler warning flags just when building this project via +# the BUILD_INTERFACE genex +set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU>") +set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>") +target_compile_options(tutorial_compiler_flags INTERFACE + "$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>" + "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>" +) + +# control where the static and shared libraries are built so that on windows +# we don't need to tinker with the path to run the executable +set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") +set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") +set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") + +option(BUILD_SHARED_LIBS "Build using shared libraries" ON) + +if(APPLE) + set(CMAKE_INSTALL_RPATH "@executable_path/../lib") +elseif(UNIX) + set(CMAKE_INSTALL_RPATH "$ORIGIN/../lib") +endif() + +# configure a header file to pass the version number only +configure_file(TutorialConfig.h.in TutorialConfig.h) + +# add the MathFunctions library +add_subdirectory(MathFunctions) + +# add the executable +add_executable(Tutorial tutorial.cxx) +target_link_libraries(Tutorial PUBLIC MathFunctions) + +# add the binary tree to the search path for include files +# so that we will find TutorialConfig.h +target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + ) + +# add the install targets +install(TARGETS Tutorial DESTINATION bin) +install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" + DESTINATION include + ) + +# enable testing +enable_testing() + +# does the application run +add_test(NAME Runs COMMAND Tutorial 25) + +# does the usage message work? +add_test(NAME Usage COMMAND Tutorial) +set_tests_properties(Usage + PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number" + ) + +# define a function to simplify adding tests +function(do_test target arg result) + add_test(NAME Comp${arg} COMMAND ${target} ${arg}) + set_tests_properties(Comp${arg} + PROPERTIES PASS_REGULAR_EXPRESSION ${result} + ) +endfunction(do_test) + +# do a bunch of result based tests +do_test(Tutorial 4 "4 is 2") +do_test(Tutorial 9 "9 is 3") +do_test(Tutorial 5 "5 is 2.236") +do_test(Tutorial 7 "7 is 2.645") +do_test(Tutorial 25 "25 is 5") +do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial 0.0001 "0.0001 is 0.01") + +include(InstallRequiredSystemLibraries) +set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt") +set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}") +set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}") +include(CPack) + +# install the configuration targets +install(EXPORT MathFunctionsTargets + FILE MathFunctionsTargets.cmake + DESTINATION lib/cmake/MathFunctions +) + +include(CMakePackageConfigHelpers) +# generate the config file that is includes the exports +configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in + "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake" + INSTALL_DESTINATION "lib/cmake/example" + NO_SET_AND_CHECK_MACRO + NO_CHECK_REQUIRED_COMPONENTS_MACRO + ) +# generate the version file for the config file +write_basic_package_version_file( + "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfigVersion.cmake" + VERSION "${Tutorial_VERSION_MAJOR}.${Tutorial_VERSION_MINOR}" + COMPATIBILITY AnyNewerVersion +) + +# install the configuration file +install(FILES + ${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake + DESTINATION lib/cmake/MathFunctions + ) + +# generate the export targets for the build tree +# needs to be after the install(TARGETS ) command +export(EXPORT MathFunctionsTargets + FILE "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsTargets.cmake" +) diff --git a/Help/guide/tutorial/Complete/CTestConfig.cmake b/Help/guide/tutorial/Complete/CTestConfig.cmake new file mode 100644 index 000000000..73efdb1f6 --- /dev/null +++ b/Help/guide/tutorial/Complete/CTestConfig.cmake @@ -0,0 +1,7 @@ +set(CTEST_PROJECT_NAME "CMakeTutorial") +set(CTEST_NIGHTLY_START_TIME "00:00:00 EST") + +set(CTEST_DROP_METHOD "http") +set(CTEST_DROP_SITE "my.cdash.org") +set(CTEST_DROP_LOCATION "/submit.php?project=CMakeTutorial") +set(CTEST_DROP_SITE_CDASH TRUE) diff --git a/Help/guide/tutorial/Complete/Config.cmake.in b/Help/guide/tutorial/Complete/Config.cmake.in new file mode 100644 index 000000000..17cbabd99 --- /dev/null +++ b/Help/guide/tutorial/Complete/Config.cmake.in @@ -0,0 +1,4 @@ + +@PACKAGE_INIT@ + +include ( "${CMAKE_CURRENT_LIST_DIR}/MathFunctionsTargets.cmake" ) diff --git a/Help/guide/tutorial/Complete/License.txt b/Help/guide/tutorial/Complete/License.txt new file mode 100644 index 000000000..c62d00b9e --- /dev/null +++ b/Help/guide/tutorial/Complete/License.txt @@ -0,0 +1,2 @@ +This is the open source License.txt file introduced in +CMake/Tutorial/Step7... diff --git a/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt new file mode 100644 index 000000000..dfa84c941 --- /dev/null +++ b/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt @@ -0,0 +1,63 @@ +# add the library that runs +add_library(MathFunctions MathFunctions.cxx) + +# state that anybody linking to us needs to include the current source dir +# to find MathFunctions.h, while we don't. +target_include_directories(MathFunctions + INTERFACE + $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}> + $<INSTALL_INTERFACE:include> + ) + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) +if(USE_MYMATH) + + target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") + + # first we add the executable that generates the table + add_executable(MakeTable MakeTable.cxx) + target_link_libraries(MakeTable tutorial_compiler_flags) + + # add the command to generate the source code + add_custom_command( + OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h + COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h + DEPENDS MakeTable + ) + + # library that just does sqrt + add_library(SqrtLibrary STATIC + mysqrt.cxx + ${CMAKE_CURRENT_BINARY_DIR}/Table.h + ) + + # state that we depend on our binary dir to find Table.h + target_include_directories(SqrtLibrary PRIVATE + ${CMAKE_CURRENT_BINARY_DIR} + ) + + # state that SqrtLibrary need PIC when the default is shared libraries + set_target_properties(SqrtLibrary PROPERTIES + POSITION_INDEPENDENT_CODE ${BUILD_SHARED_LIBS} + ) + + target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags) + target_link_libraries(MathFunctions PRIVATE SqrtLibrary) +endif() + +target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) + +# define the symbol stating we are using the declspec(dllexport) when +# building on windows +target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH") + +# setup the version numbering +set_property(TARGET MathFunctions PROPERTY VERSION "1.0.0") +set_property(TARGET MathFunctions PROPERTY SOVERSION "1") + +# install rules +install(TARGETS MathFunctions tutorial_compiler_flags + DESTINATION lib + EXPORT MathFunctionsTargets) +install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Complete/MathFunctions/MakeTable.cxx b/Help/guide/tutorial/Complete/MathFunctions/MakeTable.cxx new file mode 100644 index 000000000..ee585568c --- /dev/null +++ b/Help/guide/tutorial/Complete/MathFunctions/MakeTable.cxx @@ -0,0 +1,25 @@ +// A simple program that builds a sqrt table +#include <cmath> +#include <fstream> +#include <iostream> + +int main(int argc, char* argv[]) +{ + // make sure we have enough arguments + if (argc < 2) { + return 1; + } + + std::ofstream fout(argv[1], std::ios_base::out); + const bool fileOpen = fout.is_open(); + if (fileOpen) { + fout << "double sqrtTable[] = {" << std::endl; + for (int i = 0; i < 10; ++i) { + fout << sqrt(static_cast<double>(i)) << "," << std::endl; + } + // close the table with a zero + fout << "0};" << std::endl; + fout.close(); + } + return fileOpen ? 0 : 1; // return 0 if wrote the file +} diff --git a/Help/guide/tutorial/Complete/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Complete/MathFunctions/MathFunctions.cxx new file mode 100644 index 000000000..014530062 --- /dev/null +++ b/Help/guide/tutorial/Complete/MathFunctions/MathFunctions.cxx @@ -0,0 +1,19 @@ + +#include "MathFunctions.h" + +#include <cmath> + +#ifdef USE_MYMATH +# include "mysqrt.h" +#endif + +namespace mathfunctions { +double sqrt(double x) +{ +#ifdef USE_MYMATH + return detail::mysqrt(x); +#else + return std::sqrt(x); +#endif +} +} diff --git a/Help/guide/tutorial/Complete/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Complete/MathFunctions/MathFunctions.h new file mode 100644 index 000000000..3fb547b4a --- /dev/null +++ b/Help/guide/tutorial/Complete/MathFunctions/MathFunctions.h @@ -0,0 +1,14 @@ + +#if defined(_WIN32) +# if defined(EXPORTING_MYMATH) +# define DECLSPEC __declspec(dllexport) +# else +# define DECLSPEC __declspec(dllimport) +# endif +#else // non windows +# define DECLSPEC +#endif + +namespace mathfunctions { +double DECLSPEC sqrt(double x); +} diff --git a/Help/guide/tutorial/Complete/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Complete/MathFunctions/mysqrt.cxx new file mode 100644 index 000000000..8153f18be --- /dev/null +++ b/Help/guide/tutorial/Complete/MathFunctions/mysqrt.cxx @@ -0,0 +1,37 @@ +#include <iostream> + +#include "MathFunctions.h" + +// include the generated table +#include "Table.h" + +namespace mathfunctions { +namespace detail { +// a hack square root calculation using simple operations +double mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + // use the table to help find an initial value + double result = x; + if (x >= 1 && x < 10) { + std::cout << "Use the table to help find an initial value " << std::endl; + result = sqrtTable[static_cast<int>(x)]; + } + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; + } + + return result; +} +} +} diff --git a/Help/guide/tutorial/Complete/MathFunctions/mysqrt.h b/Help/guide/tutorial/Complete/MathFunctions/mysqrt.h new file mode 100644 index 000000000..e1c42ef0c --- /dev/null +++ b/Help/guide/tutorial/Complete/MathFunctions/mysqrt.h @@ -0,0 +1,6 @@ + +namespace mathfunctions { +namespace detail { +double mysqrt(double x); +} +} diff --git a/Help/guide/tutorial/Complete/TutorialConfig.h.in b/Help/guide/tutorial/Complete/TutorialConfig.h.in new file mode 100644 index 000000000..7e4d7fa1f --- /dev/null +++ b/Help/guide/tutorial/Complete/TutorialConfig.h.in @@ -0,0 +1,3 @@ +// the configured options and settings for Tutorial +#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ +#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ diff --git a/Help/guide/tutorial/Complete/tutorial.cxx b/Help/guide/tutorial/Complete/tutorial.cxx new file mode 100644 index 000000000..586d183a7 --- /dev/null +++ b/Help/guide/tutorial/Complete/tutorial.cxx @@ -0,0 +1,26 @@ +// A simple program that computes the square root of a number +#include <iostream> +#include <sstream> +#include <string> + +#include "MathFunctions.h" +#include "TutorialConfig.h" + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." + << Tutorial_VERSION_MINOR << std::endl; + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + const double inputValue = std::stod(argv[1]); + + // calculate square root + const double outputValue = mathfunctions::sqrt(inputValue); + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; + return 0; +} diff --git a/Help/guide/tutorial/Consumer/CMakeLists.txt b/Help/guide/tutorial/Consumer/CMakeLists.txt new file mode 100644 index 000000000..a0e4598bc --- /dev/null +++ b/Help/guide/tutorial/Consumer/CMakeLists.txt @@ -0,0 +1,51 @@ +cmake_minimum_required(VERSION 3.10) + +if(NOT DEFINED CMAKE_CXX_STANDARD) + set(CMAKE_CXX_STANDARD 11) + set(CMAKE_CXX_STANDARD_REQUIRED True) +endif() + + +function(find_external_dependency name) + set(${name}_ROOT "" CACHE PATH "Root directory to find ${name}") + mark_as_advanced(${name}_DIR) + find_package(${name} PATHS ${${name}_ROOT} REQUIRED) +endfunction() + + +project(Consumer) + +find_external_dependency(MathFunctions) + +add_library(consumer consumer.cxx) +target_link_libraries(consumer PUBLIC MathFunctions) + +# install the consumer library +install(TARGETS consumer DESTINATION bin EXPORT ConsumerTargets) + +# install the configuration targets +install(EXPORT ConsumerTargets + FILE ConsumerTargets.cmake + DESTINATION lib/cmake/Consumer +) + +include(CMakePackageConfigHelpers) +# generate the config file that is includes the exports +configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in + "${CMAKE_CURRENT_BINARY_DIR}/ConsumerConfig.cmake" + INSTALL_DESTINATION "lib/cmake/example" + NO_SET_AND_CHECK_MACRO + NO_CHECK_REQUIRED_COMPONENTS_MACRO + ) + +# install the configuration file +install(FILES + ${CMAKE_CURRENT_BINARY_DIR}/ConsumerConfig.cmake + DESTINATION lib/cmake/Consumer + ) + +# generate the export targets for the build tree +# needs to be after the install(TARGETS ) command +export(EXPORT ConsumerTargets + FILE "${CMAKE_CURRENT_BINARY_DIR}/ConsumerTargets.cmake" +) diff --git a/Help/guide/tutorial/Consumer/Config.cmake.in b/Help/guide/tutorial/Consumer/Config.cmake.in new file mode 100644 index 000000000..0b3f1e4ef --- /dev/null +++ b/Help/guide/tutorial/Consumer/Config.cmake.in @@ -0,0 +1,14 @@ + +@PACKAGE_INIT@ + +include(CMakeFindDependencyMacro) + +function(find_external_dependency name) + set(${name}_ROOT "" CACHE PATH "Root directory to find ${name}") + mark_as_advanced(${name}_DIR) + find_dependency(${name} PATHS ${${name}_ROOT} REQUIRED) +endfunction() + +find_external_dependency(MathFunctions) + +include ( "${CMAKE_CURRENT_LIST_DIR}/ConsumerTargets.cmake" ) diff --git a/Help/guide/tutorial/Consumer/consumer.cxx b/Help/guide/tutorial/Consumer/consumer.cxx new file mode 100644 index 000000000..ae7877b5a --- /dev/null +++ b/Help/guide/tutorial/Consumer/consumer.cxx @@ -0,0 +1,11 @@ +// A simple function that computes the square root of a number +#include <iostream> +#include <sstream> +#include <string> + +#include "MathFunctions.h" + +double string_square_root(std::string const& value) +{ + return mathfunctions::sqrt(std::stod(value)); +} diff --git a/Help/guide/tutorial/MultiPackage/CMakeLists.txt b/Help/guide/tutorial/MultiPackage/CMakeLists.txt new file mode 100644 index 000000000..01d417ad4 --- /dev/null +++ b/Help/guide/tutorial/MultiPackage/CMakeLists.txt @@ -0,0 +1,112 @@ +cmake_minimum_required(VERSION 3.10) + +# set the project name and version +project(Tutorial VERSION 1.0) + +set(CMAKE_CXX_STANDARD 11) +set(CMAKE_CXX_STANDARD_REQUIRED True) + + +# control where the static and shared libraries are built so that on windows +# we don't need to tinker with the path to run the executable +set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") +set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") +set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") + +option(BUILD_SHARED_LIBS "Build using shared libraries" ON) + +if(APPLE) + set(CMAKE_INSTALL_RPATH "@executable_path/../lib") +elseif(UNIX) + set(CMAKE_INSTALL_RPATH "$ORIGIN/../lib") +endif() + +# configure a header file to pass the version number only +configure_file(TutorialConfig.h.in TutorialConfig.h) + +# add the MathFunctions library +add_subdirectory(MathFunctions) + +# add the executable +add_executable(Tutorial tutorial.cxx) +target_link_libraries(Tutorial PUBLIC MathFunctions) + +# add the binary tree to the search path for include files +# so that we will find TutorialConfig.h +target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + ) + +# add the install targets +install(TARGETS Tutorial DESTINATION bin) +install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" + DESTINATION include + ) + +# enable testing +enable_testing() + +# does the application run +add_test(NAME Runs COMMAND Tutorial 25) + +# does the usage message work? +add_test(NAME Usage COMMAND Tutorial) +set_tests_properties(Usage + PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number" + ) + +# define a function to simplify adding tests +function(do_test target arg result) + add_test(NAME Comp${arg} COMMAND ${target} ${arg}) + set_tests_properties(Comp${arg} + PROPERTIES PASS_REGULAR_EXPRESSION ${result} + ) +endfunction(do_test) + +# do a bunch of result based tests +do_test(Tutorial 4 "4 is 2") +do_test(Tutorial 9 "9 is 3") +do_test(Tutorial 5 "5 is 2.236") +do_test(Tutorial 7 "7 is 2.645") +do_test(Tutorial 25 "25 is 5") +do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial 0.0001 "0.0001 is 0.01") + +include(InstallRequiredSystemLibraries) +set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt") +set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}") +set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}") +include(CPack) + +# install the configuration targets +install(EXPORT MathFunctionsTargets + FILE MathFunctionsTargets.cmake + DESTINATION lib/cmake/MathFunctions +) + +include(CMakePackageConfigHelpers) +# generate the config file that is includes the exports +configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in + "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake" + INSTALL_DESTINATION "lib/cmake/example" + NO_SET_AND_CHECK_MACRO + NO_CHECK_REQUIRED_COMPONENTS_MACRO + ) +# generate the version file for the config file +write_basic_package_version_file( + "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfigVersion.cmake" + VERSION "${Tutorial_VERSION_MAJOR}.${Tutorial_VERSION_MINOR}" + COMPATIBILITY AnyNewerVersion +) + +# install the configuration file +install(FILES + ${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake + DESTINATION lib/cmake/MathFunctions + ) + +# generate the export targets for the build tree +# needs to be after the install(TARGETS ) command +export(EXPORT MathFunctionsTargets + FILE "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsTargets.cmake" +) diff --git a/Help/guide/tutorial/MultiPackage/Config.cmake.in b/Help/guide/tutorial/MultiPackage/Config.cmake.in new file mode 100644 index 000000000..17cbabd99 --- /dev/null +++ b/Help/guide/tutorial/MultiPackage/Config.cmake.in @@ -0,0 +1,4 @@ + +@PACKAGE_INIT@ + +include ( "${CMAKE_CURRENT_LIST_DIR}/MathFunctionsTargets.cmake" ) diff --git a/Help/guide/tutorial/MultiPackage/License.txt b/Help/guide/tutorial/MultiPackage/License.txt new file mode 100644 index 000000000..c62d00b9e --- /dev/null +++ b/Help/guide/tutorial/MultiPackage/License.txt @@ -0,0 +1,2 @@ +This is the open source License.txt file introduced in +CMake/Tutorial/Step7... diff --git a/Help/guide/tutorial/MultiPackage/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/MultiPackage/MathFunctions/CMakeLists.txt new file mode 100644 index 000000000..a2df2a732 --- /dev/null +++ b/Help/guide/tutorial/MultiPackage/MathFunctions/CMakeLists.txt @@ -0,0 +1,59 @@ +# add the library that runs +add_library(MathFunctions MathFunctions.cxx) + +# state that anybody linking to us needs to include the current source dir +# to find MathFunctions.h, while we don't. +target_include_directories(MathFunctions + INTERFACE + $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}> + $<INSTALL_INTERFACE:include> + ) + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) +if(USE_MYMATH) + + target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") + + # first we add the executable that generates the table + add_executable(MakeTable MakeTable.cxx) + + # add the command to generate the source code + add_custom_command( + OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h + COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h + DEPENDS MakeTable + ) + + # library that just does sqrt + add_library(SqrtLibrary STATIC + mysqrt.cxx + ${CMAKE_CURRENT_BINARY_DIR}/Table.h + ) + + # state that we depend on our binary dir to find Table.h + target_include_directories(SqrtLibrary PRIVATE + ${CMAKE_CURRENT_BINARY_DIR} + ) + + # state that SqrtLibrary need PIC when the default is shared libraries + set_target_properties(SqrtLibrary PROPERTIES + POSITION_INDEPENDENT_CODE ${BUILD_SHARED_LIBS} + ) + + target_link_libraries(MathFunctions PRIVATE SqrtLibrary) +endif() + +# define the symbol stating we are using the declspec(dllexport) when +# building on windows +target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH") + +# setup the version numbering +set_property(TARGET MathFunctions PROPERTY VERSION "1.0.0") +set_property(TARGET MathFunctions PROPERTY SOVERSION "1") + +# install rules +install(TARGETS MathFunctions + DESTINATION lib + EXPORT MathFunctionsTargets) +install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/MultiPackage/MathFunctions/MakeTable.cxx b/Help/guide/tutorial/MultiPackage/MathFunctions/MakeTable.cxx new file mode 100644 index 000000000..ee585568c --- /dev/null +++ b/Help/guide/tutorial/MultiPackage/MathFunctions/MakeTable.cxx @@ -0,0 +1,25 @@ +// A simple program that builds a sqrt table +#include <cmath> +#include <fstream> +#include <iostream> + +int main(int argc, char* argv[]) +{ + // make sure we have enough arguments + if (argc < 2) { + return 1; + } + + std::ofstream fout(argv[1], std::ios_base::out); + const bool fileOpen = fout.is_open(); + if (fileOpen) { + fout << "double sqrtTable[] = {" << std::endl; + for (int i = 0; i < 10; ++i) { + fout << sqrt(static_cast<double>(i)) << "," << std::endl; + } + // close the table with a zero + fout << "0};" << std::endl; + fout.close(); + } + return fileOpen ? 0 : 1; // return 0 if wrote the file +} diff --git a/Help/guide/tutorial/MultiPackage/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/MultiPackage/MathFunctions/MathFunctions.cxx new file mode 100644 index 000000000..014530062 --- /dev/null +++ b/Help/guide/tutorial/MultiPackage/MathFunctions/MathFunctions.cxx @@ -0,0 +1,19 @@ + +#include "MathFunctions.h" + +#include <cmath> + +#ifdef USE_MYMATH +# include "mysqrt.h" +#endif + +namespace mathfunctions { +double sqrt(double x) +{ +#ifdef USE_MYMATH + return detail::mysqrt(x); +#else + return std::sqrt(x); +#endif +} +} diff --git a/Help/guide/tutorial/MultiPackage/MathFunctions/MathFunctions.h b/Help/guide/tutorial/MultiPackage/MathFunctions/MathFunctions.h new file mode 100644 index 000000000..3fb547b4a --- /dev/null +++ b/Help/guide/tutorial/MultiPackage/MathFunctions/MathFunctions.h @@ -0,0 +1,14 @@ + +#if defined(_WIN32) +# if defined(EXPORTING_MYMATH) +# define DECLSPEC __declspec(dllexport) +# else +# define DECLSPEC __declspec(dllimport) +# endif +#else // non windows +# define DECLSPEC +#endif + +namespace mathfunctions { +double DECLSPEC sqrt(double x); +} diff --git a/Help/guide/tutorial/MultiPackage/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/MultiPackage/MathFunctions/mysqrt.cxx new file mode 100644 index 000000000..5e622beb5 --- /dev/null +++ b/Help/guide/tutorial/MultiPackage/MathFunctions/mysqrt.cxx @@ -0,0 +1,38 @@ +#include <iostream> + +#include "MathFunctions.h" + +// include the generated table +#include "Table.h" + +namespace mathfunctions { +namespace detail { +// a hack square root calculation using simple operations +double mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + // use the table to help find an initial value + double result = x; + if (x >= 1 && x < 10) { + result = sqrtTable[static_cast<int>(x)]; + } + + // if we have both log and exp then use them + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; + } + + return result; +} +} +} diff --git a/Help/guide/tutorial/MultiPackage/MathFunctions/mysqrt.h b/Help/guide/tutorial/MultiPackage/MathFunctions/mysqrt.h new file mode 100644 index 000000000..e1c42ef0c --- /dev/null +++ b/Help/guide/tutorial/MultiPackage/MathFunctions/mysqrt.h @@ -0,0 +1,6 @@ + +namespace mathfunctions { +namespace detail { +double mysqrt(double x); +} +} diff --git a/Help/guide/tutorial/MultiPackage/MultiCPackConfig.cmake b/Help/guide/tutorial/MultiPackage/MultiCPackConfig.cmake new file mode 100644 index 000000000..403b633e1 --- /dev/null +++ b/Help/guide/tutorial/MultiPackage/MultiCPackConfig.cmake @@ -0,0 +1,7 @@ + +include("release/CPackConfig.cmake") + +set(CPACK_INSTALL_CMAKE_PROJECTS + "debug;Tutorial;ALL;/" + "release;Tutorial;ALL;/" + ) diff --git a/Help/guide/tutorial/MultiPackage/TutorialConfig.h.in b/Help/guide/tutorial/MultiPackage/TutorialConfig.h.in new file mode 100644 index 000000000..8cd2fc9c6 --- /dev/null +++ b/Help/guide/tutorial/MultiPackage/TutorialConfig.h.in @@ -0,0 +1,3 @@ +// the configured version number +#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ +#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ diff --git a/Help/guide/tutorial/MultiPackage/tutorial.cxx b/Help/guide/tutorial/MultiPackage/tutorial.cxx new file mode 100644 index 000000000..f97805b1c --- /dev/null +++ b/Help/guide/tutorial/MultiPackage/tutorial.cxx @@ -0,0 +1,25 @@ +// A simple program that computes the square root of a number +#include <iostream> +#include <string> + +#include "MathFunctions.h" +#include "TutorialConfig.h" + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." + << Tutorial_VERSION_MINOR << std::endl; + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + double inputValue = std::stod(argv[1]); + + const double outputValue = mathfunctions::sqrt(inputValue); + + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; + return 0; +} diff --git a/Help/guide/tutorial/Step1/tutorial.cxx b/Help/guide/tutorial/Step1/tutorial.cxx new file mode 100644 index 000000000..08323bfac --- /dev/null +++ b/Help/guide/tutorial/Step1/tutorial.cxx @@ -0,0 +1,22 @@ +// A simple program that computes the square root of a number +#include <cmath> +#include <cstdlib> +#include <iostream> +#include <string> + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + const double inputValue = atof(argv[1]); + + // calculate square root + const double outputValue = sqrt(inputValue); + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; + return 0; +} diff --git a/Help/guide/tutorial/Step10/CMakeLists.txt b/Help/guide/tutorial/Step10/CMakeLists.txt new file mode 100644 index 000000000..34ae70c27 --- /dev/null +++ b/Help/guide/tutorial/Step10/CMakeLists.txt @@ -0,0 +1,73 @@ +cmake_minimum_required(VERSION 3.10) + +# set the project name and version +project(Tutorial VERSION 1.0) + +# specify the C++ standard +set(CMAKE_CXX_STANDARD 11) +set(CMAKE_CXX_STANDARD_REQUIRED True) + +# control where the static and shared libraries are built so that on windows +# we don't need to tinker with the path to run the executable +set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") +set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") +set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") + +option(BUILD_SHARED_LIBS "Build using shared libraries" ON) + +# configure a header file to pass the version number only +configure_file(TutorialConfig.h.in TutorialConfig.h) + +# add the MathFunctions library +add_subdirectory(MathFunctions) + +# add the executable +add_executable(Tutorial tutorial.cxx) +target_link_libraries(Tutorial PUBLIC MathFunctions) + +# add the binary tree to the search path for include files +# so that we will find TutorialConfig.h +target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + ) + +# add the install targets +install(TARGETS Tutorial DESTINATION bin) +install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" + DESTINATION include + ) + +# enable testing +include(CTest) + +# does the application run +add_test(NAME Runs COMMAND Tutorial 25) + +# does the usage message work? +add_test(NAME Usage COMMAND Tutorial) +set_tests_properties(Usage + PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number" + ) + +# define a function to simplify adding tests +function(do_test target arg result) + add_test(NAME Comp${arg} COMMAND ${target} ${arg}) + set_tests_properties(Comp${arg} + PROPERTIES PASS_REGULAR_EXPRESSION ${result} + ) +endfunction(do_test) + +# do a bunch of result based tests +do_test(Tutorial 4 "4 is 2") +do_test(Tutorial 9 "9 is 3") +do_test(Tutorial 5 "5 is 2.236") +do_test(Tutorial 7 "7 is 2.645") +do_test(Tutorial 25 "25 is 5") +do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial 0.0001 "0.0001 is 0.01") + +include(InstallRequiredSystemLibraries) +set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt") +set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}") +set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}") +include(CPack) diff --git a/Help/guide/tutorial/Step10/CTestConfig.cmake b/Help/guide/tutorial/Step10/CTestConfig.cmake new file mode 100644 index 000000000..73efdb1f6 --- /dev/null +++ b/Help/guide/tutorial/Step10/CTestConfig.cmake @@ -0,0 +1,7 @@ +set(CTEST_PROJECT_NAME "CMakeTutorial") +set(CTEST_NIGHTLY_START_TIME "00:00:00 EST") + +set(CTEST_DROP_METHOD "http") +set(CTEST_DROP_SITE "my.cdash.org") +set(CTEST_DROP_LOCATION "/submit.php?project=CMakeTutorial") +set(CTEST_DROP_SITE_CDASH TRUE) diff --git a/Help/guide/tutorial/Step10/License.txt b/Help/guide/tutorial/Step10/License.txt new file mode 100644 index 000000000..c62d00b9e --- /dev/null +++ b/Help/guide/tutorial/Step10/License.txt @@ -0,0 +1,2 @@ +This is the open source License.txt file introduced in +CMake/Tutorial/Step7... diff --git a/Help/guide/tutorial/Step10/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step10/MathFunctions/CMakeLists.txt new file mode 100644 index 000000000..e0c06214c --- /dev/null +++ b/Help/guide/tutorial/Step10/MathFunctions/CMakeLists.txt @@ -0,0 +1,51 @@ +# add the library that runs +add_library(MathFunctions MathFunctions.cxx) + +# state that anybody linking to us needs to include the current source dir +# to find MathFunctions.h, while we don't. +target_include_directories(MathFunctions + INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} + ) + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) +if(USE_MYMATH) + + target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") + + # first we add the executable that generates the table + add_executable(MakeTable MakeTable.cxx) + + # add the command to generate the source code + add_custom_command( + OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h + COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h + DEPENDS MakeTable + ) + + # library that just does sqrt + add_library(SqrtLibrary STATIC + mysqrt.cxx + ${CMAKE_CURRENT_BINARY_DIR}/Table.h + ) + + # state that we depend on our binary dir to find Table.h + target_include_directories(SqrtLibrary PRIVATE + ${CMAKE_CURRENT_BINARY_DIR} + ) + + # state that SqrtLibrary need PIC when the default is shared libraries + set_target_properties(SqrtLibrary PROPERTIES + POSITION_INDEPENDENT_CODE ${BUILD_SHARED_LIBS} + ) + + target_link_libraries(MathFunctions PRIVATE SqrtLibrary) +endif() + +# define the symbol stating we are using the declspec(dllexport) when +# building on windows +target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH") + +# install rules +install(TARGETS MathFunctions DESTINATION lib) +install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Step10/MathFunctions/MakeTable.cxx b/Help/guide/tutorial/Step10/MathFunctions/MakeTable.cxx new file mode 100644 index 000000000..ee585568c --- /dev/null +++ b/Help/guide/tutorial/Step10/MathFunctions/MakeTable.cxx @@ -0,0 +1,25 @@ +// A simple program that builds a sqrt table +#include <cmath> +#include <fstream> +#include <iostream> + +int main(int argc, char* argv[]) +{ + // make sure we have enough arguments + if (argc < 2) { + return 1; + } + + std::ofstream fout(argv[1], std::ios_base::out); + const bool fileOpen = fout.is_open(); + if (fileOpen) { + fout << "double sqrtTable[] = {" << std::endl; + for (int i = 0; i < 10; ++i) { + fout << sqrt(static_cast<double>(i)) << "," << std::endl; + } + // close the table with a zero + fout << "0};" << std::endl; + fout.close(); + } + return fileOpen ? 0 : 1; // return 0 if wrote the file +} diff --git a/Help/guide/tutorial/Step10/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step10/MathFunctions/MathFunctions.cxx new file mode 100644 index 000000000..014530062 --- /dev/null +++ b/Help/guide/tutorial/Step10/MathFunctions/MathFunctions.cxx @@ -0,0 +1,19 @@ + +#include "MathFunctions.h" + +#include <cmath> + +#ifdef USE_MYMATH +# include "mysqrt.h" +#endif + +namespace mathfunctions { +double sqrt(double x) +{ +#ifdef USE_MYMATH + return detail::mysqrt(x); +#else + return std::sqrt(x); +#endif +} +} diff --git a/Help/guide/tutorial/Step10/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step10/MathFunctions/MathFunctions.h new file mode 100644 index 000000000..3fb547b4a --- /dev/null +++ b/Help/guide/tutorial/Step10/MathFunctions/MathFunctions.h @@ -0,0 +1,14 @@ + +#if defined(_WIN32) +# if defined(EXPORTING_MYMATH) +# define DECLSPEC __declspec(dllexport) +# else +# define DECLSPEC __declspec(dllimport) +# endif +#else // non windows +# define DECLSPEC +#endif + +namespace mathfunctions { +double DECLSPEC sqrt(double x); +} diff --git a/Help/guide/tutorial/Step10/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step10/MathFunctions/mysqrt.cxx new file mode 100644 index 000000000..8153f18be --- /dev/null +++ b/Help/guide/tutorial/Step10/MathFunctions/mysqrt.cxx @@ -0,0 +1,37 @@ +#include <iostream> + +#include "MathFunctions.h" + +// include the generated table +#include "Table.h" + +namespace mathfunctions { +namespace detail { +// a hack square root calculation using simple operations +double mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + // use the table to help find an initial value + double result = x; + if (x >= 1 && x < 10) { + std::cout << "Use the table to help find an initial value " << std::endl; + result = sqrtTable[static_cast<int>(x)]; + } + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; + } + + return result; +} +} +} diff --git a/Help/guide/tutorial/Step10/MathFunctions/mysqrt.h b/Help/guide/tutorial/Step10/MathFunctions/mysqrt.h new file mode 100644 index 000000000..e1c42ef0c --- /dev/null +++ b/Help/guide/tutorial/Step10/MathFunctions/mysqrt.h @@ -0,0 +1,6 @@ + +namespace mathfunctions { +namespace detail { +double mysqrt(double x); +} +} diff --git a/Help/guide/tutorial/Step10/TutorialConfig.h.in b/Help/guide/tutorial/Step10/TutorialConfig.h.in new file mode 100644 index 000000000..7e4d7fa1f --- /dev/null +++ b/Help/guide/tutorial/Step10/TutorialConfig.h.in @@ -0,0 +1,3 @@ +// the configured options and settings for Tutorial +#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ +#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ diff --git a/Help/guide/tutorial/Step10/tutorial.cxx b/Help/guide/tutorial/Step10/tutorial.cxx new file mode 100644 index 000000000..37a03336c --- /dev/null +++ b/Help/guide/tutorial/Step10/tutorial.cxx @@ -0,0 +1,27 @@ +// A simple program that computes the square root of a number +#include <iostream> +#include <sstream> +#include <string> + +#include "MathFunctions.h" +#include "TutorialConfig.h" + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + // report version + std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." + << Tutorial_VERSION_MINOR << std::endl; + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + const double inputValue = std::stod(argv[1]); + + const double outputValue = mathfunctions::sqrt(inputValue); + + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; + return 0; +} diff --git a/Help/guide/tutorial/Step11/CMakeLists.txt b/Help/guide/tutorial/Step11/CMakeLists.txt new file mode 100644 index 000000000..4763951c7 --- /dev/null +++ b/Help/guide/tutorial/Step11/CMakeLists.txt @@ -0,0 +1,81 @@ +cmake_minimum_required(VERSION 3.15) + +# set the project name and version +project(Tutorial VERSION 1.0) + +add_library(tutorial_compiler_flags INTERFACE) +target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11) + +# add compiler warning flags just when building this project via +# the BUILD_INTERFACE genex +set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU>") +set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>") +target_compile_options(tutorial_compiler_flags INTERFACE + "$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>" + "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>" +) + +# control where the static and shared libraries are built so that on windows +# we don't need to tinker with the path to run the executable +set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") +set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") +set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") + +option(BUILD_SHARED_LIBS "Build using shared libraries" ON) + +# configure a header file to pass the version number only +configure_file(TutorialConfig.h.in TutorialConfig.h) + +# add the MathFunctions library +add_subdirectory(MathFunctions) + +# add the executable +add_executable(Tutorial tutorial.cxx) +target_link_libraries(Tutorial PUBLIC MathFunctions) + +# add the binary tree to the search path for include files +# so that we will find TutorialConfig.h +target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + ) + +# add the install targets +install(TARGETS Tutorial DESTINATION bin) +install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" + DESTINATION include + ) + +# enable testing +enable_testing() + +# does the application run +add_test(NAME Runs COMMAND Tutorial 25) + +# does the usage message work? +add_test(NAME Usage COMMAND Tutorial) +set_tests_properties(Usage + PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number" + ) + +# define a function to simplify adding tests +function(do_test target arg result) + add_test(NAME Comp${arg} COMMAND ${target} ${arg}) + set_tests_properties(Comp${arg} + PROPERTIES PASS_REGULAR_EXPRESSION ${result} + ) +endfunction(do_test) + +# do a bunch of result based tests +do_test(Tutorial 4 "4 is 2") +do_test(Tutorial 9 "9 is 3") +do_test(Tutorial 5 "5 is 2.236") +do_test(Tutorial 7 "7 is 2.645") +do_test(Tutorial 25 "25 is 5") +do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial 0.0001 "0.0001 is 0.01") + +include(InstallRequiredSystemLibraries) +set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt") +set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}") +set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}") +include(CPack) diff --git a/Help/guide/tutorial/Step11/CTestConfig.cmake b/Help/guide/tutorial/Step11/CTestConfig.cmake new file mode 100644 index 000000000..73efdb1f6 --- /dev/null +++ b/Help/guide/tutorial/Step11/CTestConfig.cmake @@ -0,0 +1,7 @@ +set(CTEST_PROJECT_NAME "CMakeTutorial") +set(CTEST_NIGHTLY_START_TIME "00:00:00 EST") + +set(CTEST_DROP_METHOD "http") +set(CTEST_DROP_SITE "my.cdash.org") +set(CTEST_DROP_LOCATION "/submit.php?project=CMakeTutorial") +set(CTEST_DROP_SITE_CDASH TRUE) diff --git a/Help/guide/tutorial/Step11/License.txt b/Help/guide/tutorial/Step11/License.txt new file mode 100644 index 000000000..c62d00b9e --- /dev/null +++ b/Help/guide/tutorial/Step11/License.txt @@ -0,0 +1,2 @@ +This is the open source License.txt file introduced in +CMake/Tutorial/Step7... diff --git a/Help/guide/tutorial/Step11/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step11/MathFunctions/CMakeLists.txt new file mode 100644 index 000000000..e6cb8baca --- /dev/null +++ b/Help/guide/tutorial/Step11/MathFunctions/CMakeLists.txt @@ -0,0 +1,55 @@ +# add the library that runs +add_library(MathFunctions MathFunctions.cxx) + +# state that anybody linking to us needs to include the current source dir +# to find MathFunctions.h, while we don't. +target_include_directories(MathFunctions + INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} + ) + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) +if(USE_MYMATH) + + target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") + + # first we add the executable that generates the table + add_executable(MakeTable MakeTable.cxx) + target_link_libraries(MakeTable tutorial_compiler_flags) + + # add the command to generate the source code + add_custom_command( + OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h + COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h + DEPENDS MakeTable + ) + + # library that just does sqrt + add_library(SqrtLibrary STATIC + mysqrt.cxx + ${CMAKE_CURRENT_BINARY_DIR}/Table.h + ) + + # state that we depend on our binary dir to find Table.h + target_include_directories(SqrtLibrary PRIVATE + ${CMAKE_CURRENT_BINARY_DIR} + ) + + # state that SqrtLibrary need PIC when the default is shared libraries + set_target_properties(SqrtLibrary PROPERTIES + POSITION_INDEPENDENT_CODE ${BUILD_SHARED_LIBS} + ) + + target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags) + target_link_libraries(MathFunctions PRIVATE SqrtLibrary) +endif() + +target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) + +# define the symbol stating we are using the declspec(dllexport) when +#building on windows +target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH") + +# install rules +install(TARGETS MathFunctions DESTINATION lib) +install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Step11/MathFunctions/MakeTable.cxx b/Help/guide/tutorial/Step11/MathFunctions/MakeTable.cxx new file mode 100644 index 000000000..ee585568c --- /dev/null +++ b/Help/guide/tutorial/Step11/MathFunctions/MakeTable.cxx @@ -0,0 +1,25 @@ +// A simple program that builds a sqrt table +#include <cmath> +#include <fstream> +#include <iostream> + +int main(int argc, char* argv[]) +{ + // make sure we have enough arguments + if (argc < 2) { + return 1; + } + + std::ofstream fout(argv[1], std::ios_base::out); + const bool fileOpen = fout.is_open(); + if (fileOpen) { + fout << "double sqrtTable[] = {" << std::endl; + for (int i = 0; i < 10; ++i) { + fout << sqrt(static_cast<double>(i)) << "," << std::endl; + } + // close the table with a zero + fout << "0};" << std::endl; + fout.close(); + } + return fileOpen ? 0 : 1; // return 0 if wrote the file +} diff --git a/Help/guide/tutorial/Step11/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step11/MathFunctions/MathFunctions.cxx new file mode 100644 index 000000000..014530062 --- /dev/null +++ b/Help/guide/tutorial/Step11/MathFunctions/MathFunctions.cxx @@ -0,0 +1,19 @@ + +#include "MathFunctions.h" + +#include <cmath> + +#ifdef USE_MYMATH +# include "mysqrt.h" +#endif + +namespace mathfunctions { +double sqrt(double x) +{ +#ifdef USE_MYMATH + return detail::mysqrt(x); +#else + return std::sqrt(x); +#endif +} +} diff --git a/Help/guide/tutorial/Step11/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step11/MathFunctions/MathFunctions.h new file mode 100644 index 000000000..3fb547b4a --- /dev/null +++ b/Help/guide/tutorial/Step11/MathFunctions/MathFunctions.h @@ -0,0 +1,14 @@ + +#if defined(_WIN32) +# if defined(EXPORTING_MYMATH) +# define DECLSPEC __declspec(dllexport) +# else +# define DECLSPEC __declspec(dllimport) +# endif +#else // non windows +# define DECLSPEC +#endif + +namespace mathfunctions { +double DECLSPEC sqrt(double x); +} diff --git a/Help/guide/tutorial/Step11/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step11/MathFunctions/mysqrt.cxx new file mode 100644 index 000000000..8153f18be --- /dev/null +++ b/Help/guide/tutorial/Step11/MathFunctions/mysqrt.cxx @@ -0,0 +1,37 @@ +#include <iostream> + +#include "MathFunctions.h" + +// include the generated table +#include "Table.h" + +namespace mathfunctions { +namespace detail { +// a hack square root calculation using simple operations +double mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + // use the table to help find an initial value + double result = x; + if (x >= 1 && x < 10) { + std::cout << "Use the table to help find an initial value " << std::endl; + result = sqrtTable[static_cast<int>(x)]; + } + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; + } + + return result; +} +} +} diff --git a/Help/guide/tutorial/Step11/MathFunctions/mysqrt.h b/Help/guide/tutorial/Step11/MathFunctions/mysqrt.h new file mode 100644 index 000000000..e1c42ef0c --- /dev/null +++ b/Help/guide/tutorial/Step11/MathFunctions/mysqrt.h @@ -0,0 +1,6 @@ + +namespace mathfunctions { +namespace detail { +double mysqrt(double x); +} +} diff --git a/Help/guide/tutorial/Step11/TutorialConfig.h.in b/Help/guide/tutorial/Step11/TutorialConfig.h.in new file mode 100644 index 000000000..7e4d7fa1f --- /dev/null +++ b/Help/guide/tutorial/Step11/TutorialConfig.h.in @@ -0,0 +1,3 @@ +// the configured options and settings for Tutorial +#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ +#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ diff --git a/Help/guide/tutorial/Step11/tutorial.cxx b/Help/guide/tutorial/Step11/tutorial.cxx new file mode 100644 index 000000000..a4f44d54f --- /dev/null +++ b/Help/guide/tutorial/Step11/tutorial.cxx @@ -0,0 +1,26 @@ +// A simple program that computes the square root of a number +#include <iostream> +#include <string> + +#include "MathFunctions.h" +#include "TutorialConfig.h" + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + // report version + std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." + << Tutorial_VERSION_MINOR << std::endl; + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + const double inputValue = std::stod(argv[1]); + + const double outputValue = mathfunctions::sqrt(inputValue); + + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; + return 0; +} diff --git a/Help/guide/tutorial/Step2/CMakeLists.txt b/Help/guide/tutorial/Step2/CMakeLists.txt new file mode 100644 index 000000000..7aa59e917 --- /dev/null +++ b/Help/guide/tutorial/Step2/CMakeLists.txt @@ -0,0 +1,21 @@ +cmake_minimum_required(VERSION 3.10) + +# set the project name and version +project(Tutorial VERSION 1.0) + +# specify the C++ standard +set(CMAKE_CXX_STANDARD 11) +set(CMAKE_CXX_STANDARD_REQUIRED True) + +# configure a header file to pass some of the CMake settings +# to the source code +configure_file(TutorialConfig.h.in TutorialConfig.h) + +# add the executable +add_executable(Tutorial tutorial.cxx) + +# add the binary tree to the search path for include files +# so that we will find TutorialConfig.h +target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + ) diff --git a/Help/guide/tutorial/Step2/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step2/MathFunctions/MathFunctions.h new file mode 100644 index 000000000..cd36bccff --- /dev/null +++ b/Help/guide/tutorial/Step2/MathFunctions/MathFunctions.h @@ -0,0 +1 @@ +double mysqrt(double x); diff --git a/Help/guide/tutorial/Step2/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step2/MathFunctions/mysqrt.cxx new file mode 100644 index 000000000..1e4d97ae7 --- /dev/null +++ b/Help/guide/tutorial/Step2/MathFunctions/mysqrt.cxx @@ -0,0 +1,22 @@ +#include <iostream> + +// a hack square root calculation using simple operations +double mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + double result = x; + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; + } + return result; +} diff --git a/Help/guide/tutorial/Step2/TutorialConfig.h.in b/Help/guide/tutorial/Step2/TutorialConfig.h.in new file mode 100644 index 000000000..7e4d7fa1f --- /dev/null +++ b/Help/guide/tutorial/Step2/TutorialConfig.h.in @@ -0,0 +1,3 @@ +// the configured options and settings for Tutorial +#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ +#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ diff --git a/Help/guide/tutorial/Step2/tutorial.cxx b/Help/guide/tutorial/Step2/tutorial.cxx new file mode 100644 index 000000000..53b081053 --- /dev/null +++ b/Help/guide/tutorial/Step2/tutorial.cxx @@ -0,0 +1,26 @@ +// A simple program that computes the square root of a number +#include <cmath> +#include <iostream> +#include <string> + +#include "TutorialConfig.h" + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + // report version + std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." + << Tutorial_VERSION_MINOR << std::endl; + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + const double inputValue = std::stod(argv[1]); + + // calculate square root + const double outputValue = sqrt(inputValue); + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; + return 0; +} diff --git a/Help/guide/tutorial/Step3/CMakeLists.txt b/Help/guide/tutorial/Step3/CMakeLists.txt new file mode 100644 index 000000000..1c128165f --- /dev/null +++ b/Help/guide/tutorial/Step3/CMakeLists.txt @@ -0,0 +1,34 @@ +cmake_minimum_required(VERSION 3.10) + +# set the project name and version +project(Tutorial VERSION 1.0) + +# specify the C++ standard +set(CMAKE_CXX_STANDARD 11) +set(CMAKE_CXX_STANDARD_REQUIRED True) + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) + +# configure a header file to pass some of the CMake settings +# to the source code +configure_file(TutorialConfig.h.in TutorialConfig.h) + +# add the MathFunctions library +if(USE_MYMATH) + add_subdirectory(MathFunctions) + list(APPEND EXTRA_LIBS MathFunctions) + list(APPEND EXTRA_INCLUDES "${PROJECT_SOURCE_DIR}/MathFunctions") +endif() + +# add the executable +add_executable(Tutorial tutorial.cxx) + +target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS}) + +# add the binary tree to the search path for include files +# so that we will find TutorialConfig.h +target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + ${EXTRA_INCLUDES} + ) diff --git a/Help/guide/tutorial/Step3/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step3/MathFunctions/CMakeLists.txt new file mode 100644 index 000000000..8b443a659 --- /dev/null +++ b/Help/guide/tutorial/Step3/MathFunctions/CMakeLists.txt @@ -0,0 +1 @@ +add_library(MathFunctions mysqrt.cxx) diff --git a/Help/guide/tutorial/Step3/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step3/MathFunctions/MathFunctions.h new file mode 100644 index 000000000..cd36bccff --- /dev/null +++ b/Help/guide/tutorial/Step3/MathFunctions/MathFunctions.h @@ -0,0 +1 @@ +double mysqrt(double x); diff --git a/Help/guide/tutorial/Step3/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step3/MathFunctions/mysqrt.cxx new file mode 100644 index 000000000..abe767d5a --- /dev/null +++ b/Help/guide/tutorial/Step3/MathFunctions/mysqrt.cxx @@ -0,0 +1,24 @@ +#include <iostream> + +#include "MathFunctions.h" + +// a hack square root calculation using simple operations +double mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + double result = x; + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; + } + return result; +} diff --git a/Help/guide/tutorial/Step3/TutorialConfig.h.in b/Help/guide/tutorial/Step3/TutorialConfig.h.in new file mode 100644 index 000000000..e23f5213c --- /dev/null +++ b/Help/guide/tutorial/Step3/TutorialConfig.h.in @@ -0,0 +1,4 @@ +// the configured options and settings for Tutorial +#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ +#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ +#cmakedefine USE_MYMATH diff --git a/Help/guide/tutorial/Step3/tutorial.cxx b/Help/guide/tutorial/Step3/tutorial.cxx new file mode 100644 index 000000000..b3c6a4f43 --- /dev/null +++ b/Help/guide/tutorial/Step3/tutorial.cxx @@ -0,0 +1,36 @@ +// A simple program that computes the square root of a number +#include <cmath> +#include <iostream> +#include <string> + +#include "TutorialConfig.h" + +// should we include the MathFunctions header? +#ifdef USE_MYMATH +# include "MathFunctions.h" +#endif + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + // report version + std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." + << Tutorial_VERSION_MINOR << std::endl; + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + const double inputValue = std::stod(argv[1]); + + // which square root function should we use? +#ifdef USE_MYMATH + const double outputValue = mysqrt(inputValue); +#else + const double outputValue = sqrt(inputValue); +#endif + + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; + return 0; +} diff --git a/Help/guide/tutorial/Step4/CMakeLists.txt b/Help/guide/tutorial/Step4/CMakeLists.txt new file mode 100644 index 000000000..38e9b1f72 --- /dev/null +++ b/Help/guide/tutorial/Step4/CMakeLists.txt @@ -0,0 +1,32 @@ +cmake_minimum_required(VERSION 3.10) + +# set the project name and version +project(Tutorial VERSION 1.0) + +# specify the C++ standard +set(CMAKE_CXX_STANDARD 11) +set(CMAKE_CXX_STANDARD_REQUIRED True) + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) + +# configure a header file to pass some of the CMake settings +# to the source code +configure_file(TutorialConfig.h.in TutorialConfig.h) + +# add the MathFunctions library +if(USE_MYMATH) + add_subdirectory(MathFunctions) + list(APPEND EXTRA_LIBS MathFunctions) +endif() + +# add the executable +add_executable(Tutorial tutorial.cxx) + +target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS}) + +# add the binary tree to the search path for include files +# so that we will find TutorialConfig.h +target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + ) diff --git a/Help/guide/tutorial/Step4/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step4/MathFunctions/CMakeLists.txt new file mode 100644 index 000000000..0515852a0 --- /dev/null +++ b/Help/guide/tutorial/Step4/MathFunctions/CMakeLists.txt @@ -0,0 +1,7 @@ +add_library(MathFunctions mysqrt.cxx) + +# state that anybody linking to us needs to include the current source dir +# to find MathFunctions.h, while we don't. +target_include_directories(MathFunctions + INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} + ) diff --git a/Help/guide/tutorial/Step4/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step4/MathFunctions/MathFunctions.h new file mode 100644 index 000000000..cd36bccff --- /dev/null +++ b/Help/guide/tutorial/Step4/MathFunctions/MathFunctions.h @@ -0,0 +1 @@ +double mysqrt(double x); diff --git a/Help/guide/tutorial/Step4/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step4/MathFunctions/mysqrt.cxx new file mode 100644 index 000000000..abe767d5a --- /dev/null +++ b/Help/guide/tutorial/Step4/MathFunctions/mysqrt.cxx @@ -0,0 +1,24 @@ +#include <iostream> + +#include "MathFunctions.h" + +// a hack square root calculation using simple operations +double mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + double result = x; + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; + } + return result; +} diff --git a/Help/guide/tutorial/Step4/TutorialConfig.h.in b/Help/guide/tutorial/Step4/TutorialConfig.h.in new file mode 100644 index 000000000..e23f5213c --- /dev/null +++ b/Help/guide/tutorial/Step4/TutorialConfig.h.in @@ -0,0 +1,4 @@ +// the configured options and settings for Tutorial +#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ +#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ +#cmakedefine USE_MYMATH diff --git a/Help/guide/tutorial/Step4/tutorial.cxx b/Help/guide/tutorial/Step4/tutorial.cxx new file mode 100644 index 000000000..b3c6a4f43 --- /dev/null +++ b/Help/guide/tutorial/Step4/tutorial.cxx @@ -0,0 +1,36 @@ +// A simple program that computes the square root of a number +#include <cmath> +#include <iostream> +#include <string> + +#include "TutorialConfig.h" + +// should we include the MathFunctions header? +#ifdef USE_MYMATH +# include "MathFunctions.h" +#endif + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + // report version + std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." + << Tutorial_VERSION_MINOR << std::endl; + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + const double inputValue = std::stod(argv[1]); + + // which square root function should we use? +#ifdef USE_MYMATH + const double outputValue = mysqrt(inputValue); +#else + const double outputValue = sqrt(inputValue); +#endif + + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; + return 0; +} diff --git a/Help/guide/tutorial/Step5/CMakeLists.txt b/Help/guide/tutorial/Step5/CMakeLists.txt new file mode 100644 index 000000000..c3b375a3d --- /dev/null +++ b/Help/guide/tutorial/Step5/CMakeLists.txt @@ -0,0 +1,66 @@ +cmake_minimum_required(VERSION 3.10) + +# set the project name and version +project(Tutorial VERSION 1.0) + +# specify the C++ standard +set(CMAKE_CXX_STANDARD 11) +set(CMAKE_CXX_STANDARD_REQUIRED True) + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) + +# configure a header file to pass some of the CMake settings +# to the source code +configure_file(TutorialConfig.h.in TutorialConfig.h) + +# add the MathFunctions library +if(USE_MYMATH) + add_subdirectory(MathFunctions) + list(APPEND EXTRA_LIBS MathFunctions) +endif() + +# add the executable +add_executable(Tutorial tutorial.cxx) +target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS}) + +# add the binary tree to the search path for include files +# so that we will find TutorialConfig.h +target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + ) + +# add the install targets +install(TARGETS Tutorial DESTINATION bin) +install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" + DESTINATION include + ) + +# enable testing +enable_testing() + +# does the application run +add_test(NAME Runs COMMAND Tutorial 25) + +# does the usage message work? +add_test(NAME Usage COMMAND Tutorial) +set_tests_properties(Usage + PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number" + ) + +# define a function to simplify adding tests +function(do_test target arg result) + add_test(NAME Comp${arg} COMMAND ${target} ${arg}) + set_tests_properties(Comp${arg} + PROPERTIES PASS_REGULAR_EXPRESSION ${result} + ) +endfunction(do_test) + +# do a bunch of result based tests +do_test(Tutorial 4 "4 is 2") +do_test(Tutorial 9 "9 is 3") +do_test(Tutorial 5 "5 is 2.236") +do_test(Tutorial 7 "7 is 2.645") +do_test(Tutorial 25 "25 is 5") +do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial 0.0001 "0.0001 is 0.01") diff --git a/Help/guide/tutorial/Step5/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step5/MathFunctions/CMakeLists.txt new file mode 100644 index 000000000..b12f27d94 --- /dev/null +++ b/Help/guide/tutorial/Step5/MathFunctions/CMakeLists.txt @@ -0,0 +1,11 @@ +add_library(MathFunctions mysqrt.cxx) + +# state that anybody linking to us needs to include the current source dir +# to find MathFunctions.h, while we don't. +target_include_directories(MathFunctions + INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} + ) + +# install rules +install(TARGETS MathFunctions DESTINATION lib) +install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Step5/MathFunctions/MakeTable.cxx b/Help/guide/tutorial/Step5/MathFunctions/MakeTable.cxx new file mode 100644 index 000000000..ee585568c --- /dev/null +++ b/Help/guide/tutorial/Step5/MathFunctions/MakeTable.cxx @@ -0,0 +1,25 @@ +// A simple program that builds a sqrt table +#include <cmath> +#include <fstream> +#include <iostream> + +int main(int argc, char* argv[]) +{ + // make sure we have enough arguments + if (argc < 2) { + return 1; + } + + std::ofstream fout(argv[1], std::ios_base::out); + const bool fileOpen = fout.is_open(); + if (fileOpen) { + fout << "double sqrtTable[] = {" << std::endl; + for (int i = 0; i < 10; ++i) { + fout << sqrt(static_cast<double>(i)) << "," << std::endl; + } + // close the table with a zero + fout << "0};" << std::endl; + fout.close(); + } + return fileOpen ? 0 : 1; // return 0 if wrote the file +} diff --git a/Help/guide/tutorial/Step5/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step5/MathFunctions/MathFunctions.h new file mode 100644 index 000000000..cd36bccff --- /dev/null +++ b/Help/guide/tutorial/Step5/MathFunctions/MathFunctions.h @@ -0,0 +1 @@ +double mysqrt(double x); diff --git a/Help/guide/tutorial/Step5/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step5/MathFunctions/mysqrt.cxx new file mode 100644 index 000000000..abe767d5a --- /dev/null +++ b/Help/guide/tutorial/Step5/MathFunctions/mysqrt.cxx @@ -0,0 +1,24 @@ +#include <iostream> + +#include "MathFunctions.h" + +// a hack square root calculation using simple operations +double mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + double result = x; + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; + } + return result; +} diff --git a/Help/guide/tutorial/Step5/TutorialConfig.h.in b/Help/guide/tutorial/Step5/TutorialConfig.h.in new file mode 100644 index 000000000..e23f5213c --- /dev/null +++ b/Help/guide/tutorial/Step5/TutorialConfig.h.in @@ -0,0 +1,4 @@ +// the configured options and settings for Tutorial +#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ +#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ +#cmakedefine USE_MYMATH diff --git a/Help/guide/tutorial/Step5/tutorial.cxx b/Help/guide/tutorial/Step5/tutorial.cxx new file mode 100644 index 000000000..b3c6a4f43 --- /dev/null +++ b/Help/guide/tutorial/Step5/tutorial.cxx @@ -0,0 +1,36 @@ +// A simple program that computes the square root of a number +#include <cmath> +#include <iostream> +#include <string> + +#include "TutorialConfig.h" + +// should we include the MathFunctions header? +#ifdef USE_MYMATH +# include "MathFunctions.h" +#endif + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + // report version + std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." + << Tutorial_VERSION_MINOR << std::endl; + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + const double inputValue = std::stod(argv[1]); + + // which square root function should we use? +#ifdef USE_MYMATH + const double outputValue = mysqrt(inputValue); +#else + const double outputValue = sqrt(inputValue); +#endif + + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; + return 0; +} diff --git a/Help/guide/tutorial/Step6/CMakeLists.txt b/Help/guide/tutorial/Step6/CMakeLists.txt new file mode 100644 index 000000000..c3b375a3d --- /dev/null +++ b/Help/guide/tutorial/Step6/CMakeLists.txt @@ -0,0 +1,66 @@ +cmake_minimum_required(VERSION 3.10) + +# set the project name and version +project(Tutorial VERSION 1.0) + +# specify the C++ standard +set(CMAKE_CXX_STANDARD 11) +set(CMAKE_CXX_STANDARD_REQUIRED True) + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) + +# configure a header file to pass some of the CMake settings +# to the source code +configure_file(TutorialConfig.h.in TutorialConfig.h) + +# add the MathFunctions library +if(USE_MYMATH) + add_subdirectory(MathFunctions) + list(APPEND EXTRA_LIBS MathFunctions) +endif() + +# add the executable +add_executable(Tutorial tutorial.cxx) +target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS}) + +# add the binary tree to the search path for include files +# so that we will find TutorialConfig.h +target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + ) + +# add the install targets +install(TARGETS Tutorial DESTINATION bin) +install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" + DESTINATION include + ) + +# enable testing +enable_testing() + +# does the application run +add_test(NAME Runs COMMAND Tutorial 25) + +# does the usage message work? +add_test(NAME Usage COMMAND Tutorial) +set_tests_properties(Usage + PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number" + ) + +# define a function to simplify adding tests +function(do_test target arg result) + add_test(NAME Comp${arg} COMMAND ${target} ${arg}) + set_tests_properties(Comp${arg} + PROPERTIES PASS_REGULAR_EXPRESSION ${result} + ) +endfunction(do_test) + +# do a bunch of result based tests +do_test(Tutorial 4 "4 is 2") +do_test(Tutorial 9 "9 is 3") +do_test(Tutorial 5 "5 is 2.236") +do_test(Tutorial 7 "7 is 2.645") +do_test(Tutorial 25 "25 is 5") +do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial 0.0001 "0.0001 is 0.01") diff --git a/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt new file mode 100644 index 000000000..4bf6024c2 --- /dev/null +++ b/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt @@ -0,0 +1,22 @@ +add_library(MathFunctions mysqrt.cxx) + +# state that anybody linking to us needs to include the current source dir +# to find MathFunctions.h, while we don't. +target_include_directories(MathFunctions + INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} + ) + +# does this system provide the log and exp functions? +include(CheckSymbolExists) +set(CMAKE_REQUIRED_LIBRARIES "m") +check_symbol_exists(log "math.h" HAVE_LOG) +check_symbol_exists(exp "math.h" HAVE_EXP) + +if(HAVE_LOG AND HAVE_EXP) + target_compile_definitions(MathFunctions + PRIVATE "HAVE_LOG" "HAVE_EXP") +endif() + +# install rules +install(TARGETS MathFunctions DESTINATION lib) +install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Step6/MathFunctions/MakeTable.cxx b/Help/guide/tutorial/Step6/MathFunctions/MakeTable.cxx new file mode 100644 index 000000000..ee585568c --- /dev/null +++ b/Help/guide/tutorial/Step6/MathFunctions/MakeTable.cxx @@ -0,0 +1,25 @@ +// A simple program that builds a sqrt table +#include <cmath> +#include <fstream> +#include <iostream> + +int main(int argc, char* argv[]) +{ + // make sure we have enough arguments + if (argc < 2) { + return 1; + } + + std::ofstream fout(argv[1], std::ios_base::out); + const bool fileOpen = fout.is_open(); + if (fileOpen) { + fout << "double sqrtTable[] = {" << std::endl; + for (int i = 0; i < 10; ++i) { + fout << sqrt(static_cast<double>(i)) << "," << std::endl; + } + // close the table with a zero + fout << "0};" << std::endl; + fout.close(); + } + return fileOpen ? 0 : 1; // return 0 if wrote the file +} diff --git a/Help/guide/tutorial/Step6/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step6/MathFunctions/MathFunctions.h new file mode 100644 index 000000000..cd36bccff --- /dev/null +++ b/Help/guide/tutorial/Step6/MathFunctions/MathFunctions.h @@ -0,0 +1 @@ +double mysqrt(double x); diff --git a/Help/guide/tutorial/Step6/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step6/MathFunctions/mysqrt.cxx new file mode 100644 index 000000000..063706365 --- /dev/null +++ b/Help/guide/tutorial/Step6/MathFunctions/mysqrt.cxx @@ -0,0 +1,32 @@ +#include <cmath> +#include <iostream> + +#include "MathFunctions.h" + +// a hack square root calculation using simple operations +double mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + // if we have both log and exp then use them +#if defined(HAVE_LOG) && defined(HAVE_EXP) + double result = exp(log(x) * 0.5); + std::cout << "Computing sqrt of " << x << " to be " << result + << " using log and exp" << std::endl; +#else + double result = x; + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; + } +#endif + return result; +} diff --git a/Help/guide/tutorial/Step6/TutorialConfig.h.in b/Help/guide/tutorial/Step6/TutorialConfig.h.in new file mode 100644 index 000000000..e23f5213c --- /dev/null +++ b/Help/guide/tutorial/Step6/TutorialConfig.h.in @@ -0,0 +1,4 @@ +// the configured options and settings for Tutorial +#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ +#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ +#cmakedefine USE_MYMATH diff --git a/Help/guide/tutorial/Step6/tutorial.cxx b/Help/guide/tutorial/Step6/tutorial.cxx new file mode 100644 index 000000000..b3c6a4f43 --- /dev/null +++ b/Help/guide/tutorial/Step6/tutorial.cxx @@ -0,0 +1,36 @@ +// A simple program that computes the square root of a number +#include <cmath> +#include <iostream> +#include <string> + +#include "TutorialConfig.h" + +// should we include the MathFunctions header? +#ifdef USE_MYMATH +# include "MathFunctions.h" +#endif + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + // report version + std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." + << Tutorial_VERSION_MINOR << std::endl; + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + const double inputValue = std::stod(argv[1]); + + // which square root function should we use? +#ifdef USE_MYMATH + const double outputValue = mysqrt(inputValue); +#else + const double outputValue = sqrt(inputValue); +#endif + + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; + return 0; +} diff --git a/Help/guide/tutorial/Step7/CMakeLists.txt b/Help/guide/tutorial/Step7/CMakeLists.txt new file mode 100644 index 000000000..c3b375a3d --- /dev/null +++ b/Help/guide/tutorial/Step7/CMakeLists.txt @@ -0,0 +1,66 @@ +cmake_minimum_required(VERSION 3.10) + +# set the project name and version +project(Tutorial VERSION 1.0) + +# specify the C++ standard +set(CMAKE_CXX_STANDARD 11) +set(CMAKE_CXX_STANDARD_REQUIRED True) + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) + +# configure a header file to pass some of the CMake settings +# to the source code +configure_file(TutorialConfig.h.in TutorialConfig.h) + +# add the MathFunctions library +if(USE_MYMATH) + add_subdirectory(MathFunctions) + list(APPEND EXTRA_LIBS MathFunctions) +endif() + +# add the executable +add_executable(Tutorial tutorial.cxx) +target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS}) + +# add the binary tree to the search path for include files +# so that we will find TutorialConfig.h +target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + ) + +# add the install targets +install(TARGETS Tutorial DESTINATION bin) +install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" + DESTINATION include + ) + +# enable testing +enable_testing() + +# does the application run +add_test(NAME Runs COMMAND Tutorial 25) + +# does the usage message work? +add_test(NAME Usage COMMAND Tutorial) +set_tests_properties(Usage + PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number" + ) + +# define a function to simplify adding tests +function(do_test target arg result) + add_test(NAME Comp${arg} COMMAND ${target} ${arg}) + set_tests_properties(Comp${arg} + PROPERTIES PASS_REGULAR_EXPRESSION ${result} + ) +endfunction(do_test) + +# do a bunch of result based tests +do_test(Tutorial 4 "4 is 2") +do_test(Tutorial 9 "9 is 3") +do_test(Tutorial 5 "5 is 2.236") +do_test(Tutorial 7 "7 is 2.645") +do_test(Tutorial 25 "25 is 5") +do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial 0.0001 "0.0001 is 0.01") diff --git a/Help/guide/tutorial/Step7/License.txt b/Help/guide/tutorial/Step7/License.txt new file mode 100644 index 000000000..c62d00b9e --- /dev/null +++ b/Help/guide/tutorial/Step7/License.txt @@ -0,0 +1,2 @@ +This is the open source License.txt file introduced in +CMake/Tutorial/Step7... diff --git a/Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt new file mode 100644 index 000000000..9ede4b327 --- /dev/null +++ b/Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt @@ -0,0 +1,29 @@ +# first we add the executable that generates the table +add_executable(MakeTable MakeTable.cxx) + +# add the command to generate the source code +add_custom_command( + OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h + COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h + DEPENDS MakeTable + ) + +# add the main library +add_library(MathFunctions + mysqrt.cxx + ${CMAKE_CURRENT_BINARY_DIR}/Table.h + ) + +# state that anybody linking to us needs to include the current source dir +# to find MathFunctions.h, while we don't. +# state that we depend on Tutorial_BINARY_DIR but consumers don't, as the +# TutorialConfig.h include is an implementation detail +# state that we depend on our binary dir to find Table.h +target_include_directories(MathFunctions + INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} + PRIVATE ${CMAKE_CURRENT_BINARY_DIR} + ) + +# install rules +install(TARGETS MathFunctions DESTINATION lib) +install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Step7/MathFunctions/MakeTable.cxx b/Help/guide/tutorial/Step7/MathFunctions/MakeTable.cxx new file mode 100644 index 000000000..ee585568c --- /dev/null +++ b/Help/guide/tutorial/Step7/MathFunctions/MakeTable.cxx @@ -0,0 +1,25 @@ +// A simple program that builds a sqrt table +#include <cmath> +#include <fstream> +#include <iostream> + +int main(int argc, char* argv[]) +{ + // make sure we have enough arguments + if (argc < 2) { + return 1; + } + + std::ofstream fout(argv[1], std::ios_base::out); + const bool fileOpen = fout.is_open(); + if (fileOpen) { + fout << "double sqrtTable[] = {" << std::endl; + for (int i = 0; i < 10; ++i) { + fout << sqrt(static_cast<double>(i)) << "," << std::endl; + } + // close the table with a zero + fout << "0};" << std::endl; + fout.close(); + } + return fileOpen ? 0 : 1; // return 0 if wrote the file +} diff --git a/Help/guide/tutorial/Step7/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step7/MathFunctions/MathFunctions.h new file mode 100644 index 000000000..cd36bccff --- /dev/null +++ b/Help/guide/tutorial/Step7/MathFunctions/MathFunctions.h @@ -0,0 +1 @@ +double mysqrt(double x); diff --git a/Help/guide/tutorial/Step7/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step7/MathFunctions/mysqrt.cxx new file mode 100644 index 000000000..7d80ee964 --- /dev/null +++ b/Help/guide/tutorial/Step7/MathFunctions/mysqrt.cxx @@ -0,0 +1,33 @@ +#include <iostream> + +#include "MathFunctions.h" + +// include the generated table +#include "Table.h" + +// a hack square root calculation using simple operations +double mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + // use the table to help find an initial value + double result = x; + if (x >= 1 && x < 10) { + std::cout << "Use the table to help find an initial value " << std::endl; + result = sqrtTable[static_cast<int>(x)]; + } + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; + } + + return result; +} diff --git a/Help/guide/tutorial/Step7/TutorialConfig.h.in b/Help/guide/tutorial/Step7/TutorialConfig.h.in new file mode 100644 index 000000000..e23f5213c --- /dev/null +++ b/Help/guide/tutorial/Step7/TutorialConfig.h.in @@ -0,0 +1,4 @@ +// the configured options and settings for Tutorial +#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ +#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ +#cmakedefine USE_MYMATH diff --git a/Help/guide/tutorial/Step7/tutorial.cxx b/Help/guide/tutorial/Step7/tutorial.cxx new file mode 100644 index 000000000..b3c6a4f43 --- /dev/null +++ b/Help/guide/tutorial/Step7/tutorial.cxx @@ -0,0 +1,36 @@ +// A simple program that computes the square root of a number +#include <cmath> +#include <iostream> +#include <string> + +#include "TutorialConfig.h" + +// should we include the MathFunctions header? +#ifdef USE_MYMATH +# include "MathFunctions.h" +#endif + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + // report version + std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." + << Tutorial_VERSION_MINOR << std::endl; + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + const double inputValue = std::stod(argv[1]); + + // which square root function should we use? +#ifdef USE_MYMATH + const double outputValue = mysqrt(inputValue); +#else + const double outputValue = sqrt(inputValue); +#endif + + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; + return 0; +} diff --git a/Help/guide/tutorial/Step8/CMakeLists.txt b/Help/guide/tutorial/Step8/CMakeLists.txt new file mode 100644 index 000000000..19b9913e9 --- /dev/null +++ b/Help/guide/tutorial/Step8/CMakeLists.txt @@ -0,0 +1,73 @@ +cmake_minimum_required(VERSION 3.10) + +# set the project name and version +project(Tutorial VERSION 1.0) + +# specify the C++ standard +set(CMAKE_CXX_STANDARD 11) +set(CMAKE_CXX_STANDARD_REQUIRED True) + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) + +# configure a header file to pass some of the CMake settings +# to the source code +configure_file(TutorialConfig.h.in TutorialConfig.h) + +# add the MathFunctions library +if(USE_MYMATH) + add_subdirectory(MathFunctions) + list(APPEND EXTRA_LIBS MathFunctions) +endif() + +# add the executable +add_executable(Tutorial tutorial.cxx) +target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS}) + +# add the binary tree to the search path for include files +# so that we will find TutorialConfig.h +target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + ) + +# add the install targets +install(TARGETS Tutorial DESTINATION bin) +install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" + DESTINATION include + ) + +# enable testing +enable_testing() + +# does the application run +add_test(NAME Runs COMMAND Tutorial 25) + +# does the usage message work? +add_test(NAME Usage COMMAND Tutorial) +set_tests_properties(Usage + PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number" + ) + +# define a function to simplify adding tests +function(do_test target arg result) + add_test(NAME Comp${arg} COMMAND ${target} ${arg}) + set_tests_properties(Comp${arg} + PROPERTIES PASS_REGULAR_EXPRESSION ${result} + ) +endfunction(do_test) + +# do a bunch of result based tests +do_test(Tutorial 4 "4 is 2") +do_test(Tutorial 9 "9 is 3") +do_test(Tutorial 5 "5 is 2.236") +do_test(Tutorial 7 "7 is 2.645") +do_test(Tutorial 25 "25 is 5") +do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial 0.0001 "0.0001 is 0.01") + +# setup installer +include(InstallRequiredSystemLibraries) +set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt") +set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}") +set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}") +include(CPack) diff --git a/Help/guide/tutorial/Step8/License.txt b/Help/guide/tutorial/Step8/License.txt new file mode 100644 index 000000000..c62d00b9e --- /dev/null +++ b/Help/guide/tutorial/Step8/License.txt @@ -0,0 +1,2 @@ +This is the open source License.txt file introduced in +CMake/Tutorial/Step7... diff --git a/Help/guide/tutorial/Step8/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step8/MathFunctions/CMakeLists.txt new file mode 100644 index 000000000..9ede4b327 --- /dev/null +++ b/Help/guide/tutorial/Step8/MathFunctions/CMakeLists.txt @@ -0,0 +1,29 @@ +# first we add the executable that generates the table +add_executable(MakeTable MakeTable.cxx) + +# add the command to generate the source code +add_custom_command( + OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h + COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h + DEPENDS MakeTable + ) + +# add the main library +add_library(MathFunctions + mysqrt.cxx + ${CMAKE_CURRENT_BINARY_DIR}/Table.h + ) + +# state that anybody linking to us needs to include the current source dir +# to find MathFunctions.h, while we don't. +# state that we depend on Tutorial_BINARY_DIR but consumers don't, as the +# TutorialConfig.h include is an implementation detail +# state that we depend on our binary dir to find Table.h +target_include_directories(MathFunctions + INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} + PRIVATE ${CMAKE_CURRENT_BINARY_DIR} + ) + +# install rules +install(TARGETS MathFunctions DESTINATION lib) +install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Step8/MathFunctions/MakeTable.cxx b/Help/guide/tutorial/Step8/MathFunctions/MakeTable.cxx new file mode 100644 index 000000000..ee585568c --- /dev/null +++ b/Help/guide/tutorial/Step8/MathFunctions/MakeTable.cxx @@ -0,0 +1,25 @@ +// A simple program that builds a sqrt table +#include <cmath> +#include <fstream> +#include <iostream> + +int main(int argc, char* argv[]) +{ + // make sure we have enough arguments + if (argc < 2) { + return 1; + } + + std::ofstream fout(argv[1], std::ios_base::out); + const bool fileOpen = fout.is_open(); + if (fileOpen) { + fout << "double sqrtTable[] = {" << std::endl; + for (int i = 0; i < 10; ++i) { + fout << sqrt(static_cast<double>(i)) << "," << std::endl; + } + // close the table with a zero + fout << "0};" << std::endl; + fout.close(); + } + return fileOpen ? 0 : 1; // return 0 if wrote the file +} diff --git a/Help/guide/tutorial/Step8/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step8/MathFunctions/MathFunctions.h new file mode 100644 index 000000000..cd36bccff --- /dev/null +++ b/Help/guide/tutorial/Step8/MathFunctions/MathFunctions.h @@ -0,0 +1 @@ +double mysqrt(double x); diff --git a/Help/guide/tutorial/Step8/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step8/MathFunctions/mysqrt.cxx new file mode 100644 index 000000000..7d80ee964 --- /dev/null +++ b/Help/guide/tutorial/Step8/MathFunctions/mysqrt.cxx @@ -0,0 +1,33 @@ +#include <iostream> + +#include "MathFunctions.h" + +// include the generated table +#include "Table.h" + +// a hack square root calculation using simple operations +double mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + // use the table to help find an initial value + double result = x; + if (x >= 1 && x < 10) { + std::cout << "Use the table to help find an initial value " << std::endl; + result = sqrtTable[static_cast<int>(x)]; + } + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; + } + + return result; +} diff --git a/Help/guide/tutorial/Step8/TutorialConfig.h.in b/Help/guide/tutorial/Step8/TutorialConfig.h.in new file mode 100644 index 000000000..e23f5213c --- /dev/null +++ b/Help/guide/tutorial/Step8/TutorialConfig.h.in @@ -0,0 +1,4 @@ +// the configured options and settings for Tutorial +#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ +#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ +#cmakedefine USE_MYMATH diff --git a/Help/guide/tutorial/Step8/tutorial.cxx b/Help/guide/tutorial/Step8/tutorial.cxx new file mode 100644 index 000000000..b3c6a4f43 --- /dev/null +++ b/Help/guide/tutorial/Step8/tutorial.cxx @@ -0,0 +1,36 @@ +// A simple program that computes the square root of a number +#include <cmath> +#include <iostream> +#include <string> + +#include "TutorialConfig.h" + +// should we include the MathFunctions header? +#ifdef USE_MYMATH +# include "MathFunctions.h" +#endif + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + // report version + std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." + << Tutorial_VERSION_MINOR << std::endl; + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + const double inputValue = std::stod(argv[1]); + + // which square root function should we use? +#ifdef USE_MYMATH + const double outputValue = mysqrt(inputValue); +#else + const double outputValue = sqrt(inputValue); +#endif + + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; + return 0; +} diff --git a/Help/guide/tutorial/Step9/CMakeLists.txt b/Help/guide/tutorial/Step9/CMakeLists.txt new file mode 100644 index 000000000..d5f1cc897 --- /dev/null +++ b/Help/guide/tutorial/Step9/CMakeLists.txt @@ -0,0 +1,72 @@ +cmake_minimum_required(VERSION 3.10) + +# set the project name and version +project(Tutorial VERSION 1.0) + +# specify the C++ standard +set(CMAKE_CXX_STANDARD 11) +set(CMAKE_CXX_STANDARD_REQUIRED True) + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) + +# configure a header file to pass some of the CMake settings +# to the source code +configure_file(TutorialConfig.h.in TutorialConfig.h) + +# add the MathFunctions library +if(USE_MYMATH) + add_subdirectory(MathFunctions) + list(APPEND EXTRA_LIBS MathFunctions) +endif() + +# add the executable +add_executable(Tutorial tutorial.cxx) +target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS}) + +# add the binary tree to the search path for include files +# so that we will find TutorialConfig.h +target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + ) + +# add the install targets +install(TARGETS Tutorial DESTINATION bin) +install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" + DESTINATION include + ) + +# enable testing +include(CTest) + +# does the application run +add_test(NAME Runs COMMAND Tutorial 25) + +# does the usage message work? +add_test(NAME Usage COMMAND Tutorial) +set_tests_properties(Usage + PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number" + ) + +# define a function to simplify adding tests +function(do_test target arg result) + add_test(NAME Comp${arg} COMMAND ${target} ${arg}) + set_tests_properties(Comp${arg} + PROPERTIES PASS_REGULAR_EXPRESSION ${result} + ) +endfunction(do_test) + +# do a bunch of result based tests +do_test(Tutorial 4 "4 is 2") +do_test(Tutorial 9 "9 is 3") +do_test(Tutorial 5 "5 is 2.236") +do_test(Tutorial 7 "7 is 2.645") +do_test(Tutorial 25 "25 is 5") +do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial 0.0001 "0.0001 is 0.01") + +include(InstallRequiredSystemLibraries) +set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt") +set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}") +set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}") +include(CPack) diff --git a/Help/guide/tutorial/Step9/CTestConfig.cmake b/Help/guide/tutorial/Step9/CTestConfig.cmake new file mode 100644 index 000000000..73efdb1f6 --- /dev/null +++ b/Help/guide/tutorial/Step9/CTestConfig.cmake @@ -0,0 +1,7 @@ +set(CTEST_PROJECT_NAME "CMakeTutorial") +set(CTEST_NIGHTLY_START_TIME "00:00:00 EST") + +set(CTEST_DROP_METHOD "http") +set(CTEST_DROP_SITE "my.cdash.org") +set(CTEST_DROP_LOCATION "/submit.php?project=CMakeTutorial") +set(CTEST_DROP_SITE_CDASH TRUE) diff --git a/Help/guide/tutorial/Step9/License.txt b/Help/guide/tutorial/Step9/License.txt new file mode 100644 index 000000000..c62d00b9e --- /dev/null +++ b/Help/guide/tutorial/Step9/License.txt @@ -0,0 +1,2 @@ +This is the open source License.txt file introduced in +CMake/Tutorial/Step7... diff --git a/Help/guide/tutorial/Step9/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step9/MathFunctions/CMakeLists.txt new file mode 100644 index 000000000..50f0701fe --- /dev/null +++ b/Help/guide/tutorial/Step9/MathFunctions/CMakeLists.txt @@ -0,0 +1,27 @@ +# first we add the executable that generates the table +add_executable(MakeTable MakeTable.cxx) + +# add the command to generate the source code +add_custom_command( + OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h + COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h + DEPENDS MakeTable + ) + +# add the main library +add_library(MathFunctions + mysqrt.cxx + ${CMAKE_CURRENT_BINARY_DIR}/Table.h + ) + +# state that anybody linking to us needs to include the current source dir +# to find MathFunctions.h, while we don't. +# state that we depend on our binary dir to find Table.h +target_include_directories(MathFunctions + INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} + PRIVATE ${CMAKE_CURRENT_BINARY_DIR} + ) + +# install rules +install(TARGETS MathFunctions DESTINATION lib) +install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Step9/MathFunctions/MakeTable.cxx b/Help/guide/tutorial/Step9/MathFunctions/MakeTable.cxx new file mode 100644 index 000000000..ee585568c --- /dev/null +++ b/Help/guide/tutorial/Step9/MathFunctions/MakeTable.cxx @@ -0,0 +1,25 @@ +// A simple program that builds a sqrt table +#include <cmath> +#include <fstream> +#include <iostream> + +int main(int argc, char* argv[]) +{ + // make sure we have enough arguments + if (argc < 2) { + return 1; + } + + std::ofstream fout(argv[1], std::ios_base::out); + const bool fileOpen = fout.is_open(); + if (fileOpen) { + fout << "double sqrtTable[] = {" << std::endl; + for (int i = 0; i < 10; ++i) { + fout << sqrt(static_cast<double>(i)) << "," << std::endl; + } + // close the table with a zero + fout << "0};" << std::endl; + fout.close(); + } + return fileOpen ? 0 : 1; // return 0 if wrote the file +} diff --git a/Help/guide/tutorial/Step9/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step9/MathFunctions/MathFunctions.cxx new file mode 100644 index 000000000..014530062 --- /dev/null +++ b/Help/guide/tutorial/Step9/MathFunctions/MathFunctions.cxx @@ -0,0 +1,19 @@ + +#include "MathFunctions.h" + +#include <cmath> + +#ifdef USE_MYMATH +# include "mysqrt.h" +#endif + +namespace mathfunctions { +double sqrt(double x) +{ +#ifdef USE_MYMATH + return detail::mysqrt(x); +#else + return std::sqrt(x); +#endif +} +} diff --git a/Help/guide/tutorial/Step9/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step9/MathFunctions/MathFunctions.h new file mode 100644 index 000000000..cd36bccff --- /dev/null +++ b/Help/guide/tutorial/Step9/MathFunctions/MathFunctions.h @@ -0,0 +1 @@ +double mysqrt(double x); diff --git a/Help/guide/tutorial/Step9/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step9/MathFunctions/mysqrt.cxx new file mode 100644 index 000000000..7d80ee964 --- /dev/null +++ b/Help/guide/tutorial/Step9/MathFunctions/mysqrt.cxx @@ -0,0 +1,33 @@ +#include <iostream> + +#include "MathFunctions.h" + +// include the generated table +#include "Table.h" + +// a hack square root calculation using simple operations +double mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + // use the table to help find an initial value + double result = x; + if (x >= 1 && x < 10) { + std::cout << "Use the table to help find an initial value " << std::endl; + result = sqrtTable[static_cast<int>(x)]; + } + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; + } + + return result; +} diff --git a/Help/guide/tutorial/Step9/MathFunctions/mysqrt.h b/Help/guide/tutorial/Step9/MathFunctions/mysqrt.h new file mode 100644 index 000000000..e1c42ef0c --- /dev/null +++ b/Help/guide/tutorial/Step9/MathFunctions/mysqrt.h @@ -0,0 +1,6 @@ + +namespace mathfunctions { +namespace detail { +double mysqrt(double x); +} +} diff --git a/Help/guide/tutorial/Step9/TutorialConfig.h.in b/Help/guide/tutorial/Step9/TutorialConfig.h.in new file mode 100644 index 000000000..e23f5213c --- /dev/null +++ b/Help/guide/tutorial/Step9/TutorialConfig.h.in @@ -0,0 +1,4 @@ +// the configured options and settings for Tutorial +#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ +#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ +#cmakedefine USE_MYMATH diff --git a/Help/guide/tutorial/Step9/tutorial.cxx b/Help/guide/tutorial/Step9/tutorial.cxx new file mode 100644 index 000000000..b3c6a4f43 --- /dev/null +++ b/Help/guide/tutorial/Step9/tutorial.cxx @@ -0,0 +1,36 @@ +// A simple program that computes the square root of a number +#include <cmath> +#include <iostream> +#include <string> + +#include "TutorialConfig.h" + +// should we include the MathFunctions header? +#ifdef USE_MYMATH +# include "MathFunctions.h" +#endif + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + // report version + std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." + << Tutorial_VERSION_MINOR << std::endl; + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + const double inputValue = std::stod(argv[1]); + + // which square root function should we use? +#ifdef USE_MYMATH + const double outputValue = mysqrt(inputValue); +#else + const double outputValue = sqrt(inputValue); +#endif + + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; + return 0; +} diff --git a/Help/guide/tutorial/index.rst b/Help/guide/tutorial/index.rst new file mode 100644 index 000000000..d74d16047 --- /dev/null +++ b/Help/guide/tutorial/index.rst @@ -0,0 +1,902 @@ +CMake Tutorial +************** + +.. only:: html + + .. contents:: + +The CMake tutorial provides a step-by-step guide that covers common build +system issues that CMake helps address. Seeing how various topics all +work together in an example project can be very helpful. The tutorial +documentation and source code for examples can be found in the +``Help/guide/tutorial`` directory of the CMake source code tree. Each step has +its own subdirectory containing code that may be used as a starting point. The +tutorial examples are progressive so that each step provides the complete +solution for the previous step. + +A Basic Starting Point (Step 1) +=============================== + +The most basic project is an executable built from source code files. +For simple projects, a three line ``CMakeLists.txt`` file is all that is +required. This will be the starting point for our tutorial. Create a +``CMakeLists.txt`` file in the ``Step1`` directory that looks like: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.10) + + # set the project name + project(Tutorial) + + # add the executable + add_executable(Tutorial tutorial.cxx) + + +Note that this example uses lower case commands in the ``CMakeLists.txt`` file. +Upper, lower, and mixed case commands are supported by CMake. The source +code for ``tutorial.cxx`` is provided in the ``Step1`` directory and can be +used to compute the square root of a number. + +Adding a Version Number and Configured Header File +-------------------------------------------------- + +The first feature we will add is to provide our executable and project with a +version number. While we could do this exclusively in the source code, using +``CMakeLists.txt`` provides more flexibility. + +First, modify the ``CMakeLists.txt`` file to set the version number. + +.. literalinclude:: Step2/CMakeLists.txt + :language: cmake + :end-before: # specify the C++ standard + +Then, configure a header file to pass the version number to the source +code: + +.. literalinclude:: Step2/CMakeLists.txt + :language: cmake + :start-after: # to the source code + :end-before: # add the executable + +Since the configured file will be written into the binary tree, we +must add that directory to the list of paths to search for include +files. Add the following lines to the end of the ``CMakeLists.txt`` file: + +.. literalinclude:: Step2/CMakeLists.txt + :language: cmake + :start-after: # so that we will find TutorialConfig.h + +Using your favorite editor, create ``TutorialConfig.h.in`` in the source +directory with the following contents: + +.. literalinclude:: Step2/TutorialConfig.h.in + :language: cmake + +When CMake configures this header file the values for +``@Tutorial_VERSION_MAJOR@`` and ``@Tutorial_VERSION_MINOR@`` will be +replaced. + +Next modify ``tutorial.cxx`` to include the configured header file, +``TutorialConfig.h``. + +Finally, let's print out the version number by updating ``tutorial.cxx`` as +follows: + +.. literalinclude:: Step2/tutorial.cxx + :language: c++ + :start-after: { + :end-before: // convert input to double + +Specify the C++ Standard +------------------------- + +Next let's add some C++11 features to our project by replacing ``atof`` with +``std::stod`` in ``tutorial.cxx``. At the same time, remove +``#include <cstdlib>``. + +.. literalinclude:: Step2/tutorial.cxx + :language: c++ + :start-after: // convert input to double + :end-before: // calculate square root + +We will need to explicitly state in the CMake code that it should use the +correct flags. The easiest way to enable support for a specific C++ standard +in CMake is by using the ``CMAKE_CXX_STANDARD`` variable. For this tutorial, +set the ``CMAKE_CXX_STANDARD`` variable in the ``CMakeLists.txt`` file to 11 +and ``CMAKE_CXX_STANDARD_REQUIRED`` to True: + +.. literalinclude:: Step2/CMakeLists.txt + :language: cmake + :end-before: # configure a header file to pass some of the CMake settings + +Build and Test +-------------- + +Run **cmake** or **cmake-gui** to configure the project and then build it +with your chosen build tool. + +For example, from the command line we could navigate to the +``Help/guide/tutorial`` directory of the CMake source code tree and run the +following commands: + +.. code-block:: console + + mkdir Step1_build + cd Step1_build + cmake ../Step1 + cmake --build . + +Navigate to the directory where Tutorial was built (likely the make directory +or a Debug or Release build configuration subdirectory) and run these commands: + +.. code-block:: console + + Tutorial 4294967296 + Tutorial 10 + Tutorial + +Adding a Library (Step 2) +========================= + +Now we will add a library to our project. This library will contain our own +implementation for computing the square root of a number. The executable can +then use this library instead of the standard square root function provided by +the compiler. + +For this tutorial we will put the library into a subdirectory +called ``MathFunctions``. This directory already contains a header file, +``MathFunctions.h``, and a source file ``mysqrt.cxx``. The source file has one +function called ``mysqrt`` that provides similar functionality to the +compiler's ``sqrt`` function. + +Add the following one line ``CMakeLists.txt`` file to the ``MathFunctions`` +directory: + +.. literalinclude:: Step3/MathFunctions/CMakeLists.txt + :language: cmake + +To make use of the new library we will add an ``add_subdirectory`` call in the +top-level ``CMakeLists.txt`` file so that the library will get built. We add +the new library to the executable, and add ``MathFunctions`` as an include +directory so that the ``mqsqrt.h`` header file can be found. The last few lines +of the top-level ``CMakeLists.txt`` file should now look like: + +.. code-block:: cmake + + # add the MathFunctions library + add_subdirectory(MathFunctions) + + # add the executable + add_executable(Tutorial tutorial.cxx) + + target_link_libraries(Tutorial PUBLIC MathFunctions) + + # add the binary tree to the search path for include files + # so that we will find TutorialConfig.h + target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + "${PROJECT_SOURCE_DIR}/MathFunctions" + ) + +Now let us make the MathFunctions library optional. While for the tutorial +there really isn’t any need to do so, for larger projects this is a common +occurrence. The first step is to add an option to the top-level +``CMakeLists.txt`` file. + +.. literalinclude:: Step3/CMakeLists.txt + :language: cmake + :start-after: # should we use our own math functions + :end-before: # add the MathFunctions library + +This option will be displayed in the CMake GUI and ccmake with a default +value of ON that can be changed by the user. This setting will be stored in +the cache so that the user does not need to set the value each time they run +CMake on a build directory. + +The next change is to make building and linking the MathFunctions library +conditional. To do this we change the end of the top-level ``CMakeLists.txt`` +file to look like the following: + +.. literalinclude:: Step3/CMakeLists.txt + :language: cmake + :start-after: # add the MathFunctions library + +Note the use of the variable ``EXTRA_LIBS`` to collect up any optional +libraries to later be linked into the executable. The variable +``EXTRA_INCLUDES`` is used similarly for optional header files. This is a +classic approach when dealing with many optional components, we will cover +the modern approach in the next step. + +The corresponding changes to the source code are fairly straightforward. First, +in ``tutorial.cxx``, include the ``MathFunctions.h`` header if we need it: + +.. literalinclude:: Step3/tutorial.cxx + :language: c++ + :start-after: // should we include the MathFunctions header + :end-before: int main + +Then, in the same file, make ``USE_MYMATH`` control which square root +function is used: + +.. literalinclude:: Step3/tutorial.cxx + :language: c++ + :start-after: // which square root function should we use? + :end-before: std::cout << "The square root of + +Since the source code now requires ``USE_MYMATH`` we can add it to +``TutorialConfig.h.in`` with the following line: + +.. literalinclude:: Step3/TutorialConfig.h.in + :language: c + :lines: 4 + +**Exercise**: Why is it important that we configure ``TutorialConfig.h.in`` +after the option for ``USE_MYMATH``? What would happen if we inverted the two? + +Run **cmake** or **cmake-gui** to configure the project and then build it +with your chosen build tool. Then run the built Tutorial executable. + +Use ccmake or the CMake GUI to update the value of ``USE_MYMATH``. Rebuild and +run the tutorial again. Which function gives better results, sqrt or mysqrt? + +Adding Usage Requirements for Library (Step 3) +============================================== + +Usage requirements allow for far better control over a library or executable's +link and include line while also giving more control over the transitive +property of targets inside CMake. The primary commands that leverage usage +requirements are: + + - ``target_compile_definitions`` + - ``target_compile_options`` + - ``target_include_directories`` + - ``target_link_libraries`` + +Let's refactor our code from `Adding a Library (Step 2)`_ to use the modern +CMake approach of usage requirements. We first state that anybody linking to +MathFunctions needs to include the current source directory, while +MathFunctions itself doesn't. So this can become an ``INTERFACE`` usage +requirement. + +Remember ``INTERFACE`` means things that consumers require but the producer +doesn't. Add the following lines to the end of ``MathFunctions/CMakeLists.txt``: + +.. literalinclude:: Step4/MathFunctions/CMakeLists.txt + :language: cmake + :start-after: # to find MathFunctions.h + +Now that we've specified usage requirements for MathFunctions we can safely +remove our uses of the ``EXTRA_INCLUDES`` variable from the top-level +``CMakeLists.txt``, here: + +.. literalinclude:: Step4/CMakeLists.txt + :language: cmake + :start-after: # add the MathFunctions library + :end-before: # add the executable + +And here: + +.. literalinclude:: Step4/CMakeLists.txt + :language: cmake + :start-after: # so that we will find TutorialConfig.h + +Once this is done, run **cmake** or **cmake-gui** to configure the project +and then build it with your chosen build tool or by using ``cmake --build .`` +from the build directory. + +Installing and Testing (Step 4) +=============================== + +Now we can start adding install rules and testing support to our project. + +Install Rules +------------- + +The install rules are fairly simple: for MathFunctions we want to install the +library and header file and for the application we want to install the +executable and configured header. + +So to the end of ``MathFunctions/CMakeLists.txt`` we add: + +.. literalinclude:: Step5/MathFunctions/CMakeLists.txt + :language: cmake + :start-after: # install rules + +And to the end of the top-level ``CMakeLists.txt`` we add: + +.. literalinclude:: Step5/CMakeLists.txt + :language: cmake + :start-after: # add the install targets + :end-before: # enable testing + +That is all that is needed to create a basic local install of the tutorial. + +Run **cmake** or **cmake-gui** to configure the project and then build it +with your chosen build tool. Run the install step by typing +``cmake --install .`` (introduced in 3.15, older versions of CMake must use +``make install``) from the command line, or build the ``INSTALL`` target from +an IDE. This will install the appropriate header files, libraries, and +executables. + +The CMake variable ``CMAKE_INSTALL_PREFIX`` is used to determine the root of +where the files will be installed. If using ``cmake --install`` a custom +installation directory can be given via ``--prefix`` argument. For +multi-configuration tools, use the ``--config`` argument to specify the +configuration. + +Verify that the installed Tutorial runs. + +Testing Support +--------------- + +Next let's test our application. At the end of the top-level ``CMakeLists.txt`` +file we can enable testing and then add a number of basic tests to verify that +the application is working correctly. + +.. literalinclude:: Step5/CMakeLists.txt + :language: cmake + :start-after: # enable testing + +The first test simply verifies that the application runs, does not segfault or +otherwise crash, and has a zero return value. This is the basic form of a CTest +test. + +The next test makes use of the ``PASS_REGULAR_EXPRESSION`` test property to +verify that the output of the test contains certain strings. In this case, +verifying that the usage message is printed when an incorrect number of +arguments are provided. + +Lastly, we have a function called ``do_test`` that runs the application and +verifies that the computed square root is correct for given input. For each +invocation of ``do_test``, another test is added to the project with a name, +input, and expected results based on the passed arguments. + +Rebuild the application and then cd to the binary directory and run +``ctest -N`` and ``ctest -VV``. For multi-config generators (e.g. Visual +Studio), the configuration type must be specified. To run tests in Debug mode, +for example, use ``ctest -C Debug -VV`` from the build directory (not the +Debug subdirectory!). Alternatively, build the ``RUN_TESTS`` target from the +IDE. + +Adding System Introspection (Step 5) +==================================== + +Let us consider adding some code to our project that depends on features the +target platform may not have. For this example, we will add some code that +depends on whether or not the target platform has the ``log`` and ``exp`` +functions. Of course almost every platform has these functions but for this +tutorial assume that they are not common. + +If the platform has ``log`` and ``exp`` then we will use them to compute the +square root in the ``mysqrt`` function. We first test for the availability of +these functions using the ``CheckSymbolExists`` module in the top-level +``CMakeLists.txt``. We're going to use the new defines in +``TutorialConfig.h.in``, so be sure to set them before that file is configured. + +.. literalinclude:: Step6/MathFunctions/CMakeLists.txt + :language: cmake + :start-after: # does this system provide the log and exp functions? + :end-before: if(HAVE_LOG AND HAVE_EXP) + +Now let's add these defines to ``TutorialConfig.h.in`` so that we can use them +from ``mysqrt.cxx``: + +.. code-block:: console + + // does the platform provide exp and log functions? + #cmakedefine HAVE_LOG + #cmakedefine HAVE_EXP + +Modify ``mysqrt.cxx`` to include cmath. Next, in that same file in the +``mysqrt`` function we can provide an alternate implementation based on +``log`` and ``exp`` if they are available on the system using the following +code (don't forget the ``#endif`` before returning the result!): + +.. literalinclude:: Step6/MathFunctions/mysqrt.cxx + :language: c++ + :start-after: // if we have both log and exp then use them + :end-before: // do ten iterations + +Run **cmake** or **cmake-gui** to configure the project and then build it +with your chosen build tool and run the Tutorial executable. + +You will notice that we're not using ``log`` and ``exp``, even if we think they +should be available. We should realize quickly that we have forgotten to include +``TutorialConfig.h`` in ``mysqrt.cxx``. + +We will also need to update ``MathFunctions/CMakeLists.txt`` so ``mysqrt.cxx`` +knows where this file is located: + +.. code-block:: cmake + + target_include_directories(MathFunctions + INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} + PRIVATE ${CMAKE_BINARY_DIR} + ) + +After making this update, go ahead and build the project again and run the built +Tutorial executable. If ``log`` and ``exp`` are still not being used, open the +generated ``TutorialConfig.h`` file from the build directory. Maybe they aren't +available on the current system? + +Which function gives better results now, sqrt or mysqrt? + +Specify Compile Definition +-------------------------- + +Is there a better place for us to save the ``HAVE_LOG`` and ``HAVE_EXP`` values +other than in ``TutorialConfig.h``? Let's try to use +``target_compile_definitions``. + +First, remove the defines from ``TutorialConfig.h.in``. We no longer need to +include ``TutorialConfig.h`` from ``mysqrt.cxx`` or the extra include in +``MathFunctions/CMakeLists.txt``. + +Next, we can move the check for ``HAVE_LOG`` and ``HAVE_EXP`` to +``MathFunctions/CMakeLists.txt`` and then specify those values as ``PRIVATE`` +compile definitions. + +.. literalinclude:: Step6/MathFunctions/CMakeLists.txt + :language: cmake + :start-after: # does this system provide the log and exp functions? + :end-before: # install rules + +After making these updates, go ahead and build the project again. Run the +built Tutorial executable and verify that the results are same as earlier in +this step. + +Adding a Custom Command and Generated File (Step 6) +=================================================== + +Suppose, for the purpose of this tutorial, we decide that we never want to use +the platform ``log`` and ``exp`` functions and instead would like to +generate a table of precomputed values to use in the ``mysqrt`` function. +In this section, we will create the table as part of the build process, +and then compile that table into our application. + +First, let's remove the check for the ``log`` and ``exp`` functions in +``MathFunctions/CMakeLists.txt``. Then remove the check for ``HAVE_LOG`` and +``HAVE_EXP`` from ``mysqrt.cxx``. At the same time, we can remove +:code:`#include <cmath>`. + +In the ``MathFunctions`` subdirectory, a new source file named ``MakeTable.cxx`` +has been provided to generate the table. + +After reviewing the file, we can see that the table is produced as valid C++ +code and that the output filename is passed in as an argument. + +The next step is to add the appropriate commands to the +``MathFunctions/CMakeLists.txt`` file to build the MakeTable executable and +then run it as part of the build process. A few commands are needed to +accomplish this. + +First, at the top of ``MathFunctions/CMakeLists.txt``, the executable for +``MakeTable`` is added as any other executable would be added. + +.. literalinclude:: Step7/MathFunctions/CMakeLists.txt + :language: cmake + :start-after: # first we add the executable that generates the table + :end-before: # add the command to generate the source code + +Then we add a custom command that specifies how to produce ``Table.h`` +by running MakeTable. + +.. literalinclude:: Step7/MathFunctions/CMakeLists.txt + :language: cmake + :start-after: # add the command to generate the source code + :end-before: # add the main library + +Next we have to let CMake know that ``mysqrt.cxx`` depends on the generated +file ``Table.h``. This is done by adding the generated ``Table.h`` to the list +of sources for the library MathFunctions. + +.. literalinclude:: Step7/MathFunctions/CMakeLists.txt + :language: cmake + :start-after: # add the main library + :end-before: # state that anybody linking + +We also have to add the current binary directory to the list of include +directories so that ``Table.h`` can be found and included by ``mysqrt.cxx``. + +.. literalinclude:: Step7/MathFunctions/CMakeLists.txt + :start-after: # state that we depend on our bin + :end-before: # install rules + +Now let's use the generated table. First, modify ``mysqrt.cxx`` to include +``Table.h``. Next, we can rewrite the mysqrt function to use the table: + +.. literalinclude:: Step7/MathFunctions/mysqrt.cxx + :language: c++ + :start-after: // a hack square root calculation using simple operations + +Run **cmake** or **cmake-gui** to configure the project and then build it +with your chosen build tool. + +When this project is built it will first build the ``MakeTable`` executable. +It will then run ``MakeTable`` to produce ``Table.h``. Finally, it will +compile ``mysqrt.cxx`` which includes ``Table.h`` to produce the MathFunctions +library. + +Run the Tutorial executable and verify that it is using the table. + +Building an Installer (Step 7) +============================== + +Next suppose that we want to distribute our project to other people so that +they can use it. We want to provide both binary and source distributions on a +variety of platforms. This is a little different from the install we did +previously in `Installing and Testing (Step 4)`_ , where we were +installing the binaries that we had built from the source code. In this +example we will be building installation packages that support binary +installations and package management features. To accomplish this we will use +CPack to create platform specific installers. Specifically we need to add +a few lines to the bottom of our top-level ``CMakeLists.txt`` file. + +.. literalinclude:: Step8/CMakeLists.txt + :language: cmake + :start-after: # setup installer + +That is all there is to it. We start by including +``InstallRequiredSystemLibraries``. This module will include any runtime +libraries that are needed by the project for the current platform. Next we +set some CPack variables to where we have stored the license and version +information for this project. The version information was set earlier in this +tutorial and the ``license.txt`` has been included in the top-level source +directory for this step. + +Finally we include the CPack module which will use these variables and some +other properties of the current system to setup an installer. + +The next step is to build the project in the usual manner and then run +CPack on it. To build a binary distribution, from the binary directory run: + +.. code-block:: console + + cpack + +To specify the generator, use the ``-G`` option. For multi-config builds, use +``-C`` to specify the configuration. For example: + +.. code-block:: console + + cpack -G ZIP -C Debug + +To create a source distribution you would type: + +.. code-block:: console + + cpack --config CPackSourceConfig.cmake + +Alternatively, run ``make package`` or right click the ``Package`` target and +``Build Project`` from an IDE. + +Run the installer found in the binary directory. Then run the +installed executable and verify that it works. + +Adding Support for a Dashboard (Step 8) +======================================= + +Adding support for submitting our test results to a dashboard is very easy. We +already defined a number of tests for our project in `Testing Support`_. Now we +just have to run those tests and submit them to a dashboard. To include support +for dashboards we include the CTest module in our top-level ``CMakeLists.txt``. + +Replace: + +.. code-block:: cmake + + # enable testing + enable_testing() + +With: + +.. code-block:: cmake + + # enable dashboard scripting + include(CTest) + +The CTest module will automatically call ``enable_testing()``, so +we can remove it from our CMake files. + +We will also need to create a ``CTestConfig.cmake`` file in the top-level +directory where we can specify the name of the project and where to submit the +dashboard. + +.. literalinclude:: Step9/CTestConfig.cmake + :language: cmake + +CTest will read in this file when it runs. To create a simple dashboard you can +run **cmake** or **cmake-gui** to configure the project, but do not build it +yet. Instead, change directory to the binary tree, and then run:: + + ctest [-VV] -D Experimental + +Remember, for multi-config generators (e.g. Visual Studio), the configuration +type must be specified:: + + ctest [-VV] -C Debug -D Experimental + +Or, from an IDE, build the ``Experimental`` target. + +``ctest`` will build and test the project and submit the results to the Kitware +public dashboard. The results of your dashboard will be uploaded to Kitware's +public dashboard here: https://my.cdash.org/index.php?project=CMakeTutorial. + +Mixing Static and Shared (Step 9) +================================= + +In this section we will show how by using the ``BUILD_SHARED_LIBS`` variable +we can control the default behavior of ``add_library``, and allow control +over how libraries without an explicit type (``STATIC``, ``SHARED``, ``MODULE`` +or ``OBJECT``) are built. + +To accomplish this we need to add ``BUILD_SHARED_LIBS`` to the top-level +``CMakeLists.txt``. We use the ``option`` command as it allows users to +optionally select if the value should be On or Off. + +Next we are going to refactor MathFunctions to become a real library that +encapsulates using ``mysqrt`` or ``sqrt``, instead of requiring the calling +code to do this logic. This will also mean that ``USE_MYMATH`` will not control +building MathFuctions, but instead will control the behavior of this library. + +The first step is to update the starting section of the top-level +``CMakeLists.txt`` to look like: + +.. literalinclude:: Step10/CMakeLists.txt + :language: cmake + :end-before: # add the binary tree + +Now that we have made MathFunctions always be used, we will need to update +the logic of that library. So, in ``MathFunctions/CMakeLists.txt`` we need to +create a SqrtLibrary that will conditionally be built when ``USE_MYMATH`` is +enabled. Now, since this is a tutorial, we are going to explicitly require +that SqrtLibrary is built statically. + +The end result is that ``MathFunctions/CMakeLists.txt`` should look like: + +.. literalinclude:: Step10/MathFunctions/CMakeLists.txt + :language: cmake + :lines: 1-36,42- + +Next, update ``MathFunctions/mysqrt.cxx`` to use the ``mathfunctions`` and +``detail`` namespaces: + +.. literalinclude:: Step10/MathFunctions/mysqrt.cxx + :language: c++ + +We also need to make some changes in ``tutorial.cxx``, so that it no longer +uses ``USE_MYMATH``: + +#. Always include ``MathFunctions.h`` +#. Always use ``mathfunctions::sqrt`` +#. Don't include cmath + +Finally, update ``MathFunctions/MathFunctions.h`` to use dll export defines: + +.. literalinclude:: Step10/MathFunctions/MathFunctions.h + :language: c++ + +At this point, if you build everything, you will notice that linking fails +as we are combining a static library without position independent code with a +library that has position independent code. The solution to this is to +explicitly set the ``POSITION_INDEPENDENT_CODE`` target property of SqrtLibrary +to be True no matter the build type. + +.. literalinclude:: Step10/MathFunctions/CMakeLists.txt + :language: cmake + :lines: 37-42 + +**Exercise**: We modified ``MathFunctions.h`` to use dll export defines. +Using CMake documentation can you find a helper module to simplify this? + + +Adding Generator Expressions (Step 10) +====================================== + +Generator expressions are evaluated during build system generation to produce +information specific to each build configuration. + +Generator expressions are allowed in the context of many target properties, +such as ``LINK_LIBRARIES``, ``INCLUDE_DIRECTORIES``, ``COMPILE_DEFINITIONS`` +and others. They may also be used when using commands to populate those +properties, such as ``target_link_libraries()``, +``target_include_directories()``, +``target_compile_definitions()`` and others. + +Generator expressions may be used to enable conditional linking, conditional +definitions used when compiling, conditional include directories and more. +The conditions may be based on the build configuration, target properties, +platform information or any other queryable information. + +There are different types of generator expressions including Logical, +Informational, and Output expressions. + +Logical expressions are used to create conditional output. The basic +expressions are the 0 and 1 expressions. A ``$<0:...>`` results in the empty +string, and ``<1:...>`` results in the content of "...". They can also be +nested. + +A common usage of generator expressions is to conditionally add compiler +flags, such as those for language levels or warnings. A nice pattern is +to associate this information to an ``INTERFACE`` target allowing this +information to propagate. Lets start by constructing an ``INTERFACE`` +target and specifying the required C++ standard level of ``11`` instead +of using ``CMAKE_CXX_STANDARD``. + +So the following code: + +.. literalinclude:: Step10/CMakeLists.txt + :language: cmake + :start-after: project(Tutorial VERSION 1.0) + :end-before: # control where the static and shared libraries are built so that on windows + +Would be replaced with: + +.. literalinclude:: Step11/CMakeLists.txt + :language: cmake + :start-after: project(Tutorial VERSION 1.0) + :end-before: # add compiler warning flags just when building this project via + + +Next we add the desired compiler warning flags that we want for our +project. As warning flags vary based on the compiler we use +the ``COMPILE_LANG_AND_ID`` generator expression to control which +flags to apply given a language and a set of compiler ids as seen +below: + +.. literalinclude:: Step11/CMakeLists.txt + :language: cmake + :start-after: # the BUILD_INTERFACE genex + :end-before: # control where the static and shared libraries are built so that on windows + +Looking at this we see that the warning flags are encapsulated inside a +``BUILD_INTERFACE`` condition. This is done so that consumers of our installed +project will not inherit our warning flags. + + +**Exercise**: Modify ``MathFunctions/CMakeLists.txt`` so that +all targets have a ``target_link_libraries()`` call to ``tutorial_compiler_flags``. + + +Adding Export Configuration (Step 11) +===================================== + +During `Installing and Testing (Step 4)`_ of the tutorial we added the ability +for CMake to install the library and headers of the project. During +`Building an Installer (Step 7)`_ we added the ability to package up this +information so it could be distributed to other people. + +The next step is to add the necessary information so that other CMake projects +can use our project, be it from a build directory, a local install or when +packaged. + +The first step is to update our ``install(TARGETS)`` commands to not only +specify a ``DESTINATION`` but also an ``EXPORT``. The ``EXPORT`` keyword +generates and installs a CMake file containing code to import all targets +listed in the install command from the installation tree. So let's go ahead +and explicitly ``EXPORT`` the MathFunctions library by updating the +``install`` command in ``MathFunctions/CMakeLists.txt`` to look like: + +.. literalinclude:: Complete/MathFunctions/CMakeLists.txt + :language: cmake + :start-after: # install rules + +Now that we have MathFunctions being exported, we also need to explicitly +install the generated ``MathFunctionsTargets.cmake`` file. This is done by +adding the following to the bottom of the top-level ``CMakeLists.txt``: + +.. literalinclude:: Complete/CMakeLists.txt + :language: cmake + :start-after: # install the configuration targets + :end-before: include(CMakePackageConfigHelpers) + +At this point you should try and run CMake. If everything is setup properly +you will see that CMake will generate an error that looks like: + +.. code-block:: console + + Target "MathFunctions" INTERFACE_INCLUDE_DIRECTORIES property contains + path: + + "/Users/robert/Documents/CMakeClass/Tutorial/Step11/MathFunctions" + + which is prefixed in the source directory. + +What CMake is trying to say is that during generating the export information +it will export a path that is intrinsically tied to the current machine and +will not be valid on other machines. The solution to this is to update the +MathFunctions ``target_include_directories`` to understand that it needs +different ``INTERFACE`` locations when being used from within the build +directory and from an install / package. This means converting the +``target_include_directories`` call for MathFunctions to look like: + +.. literalinclude:: Complete/MathFunctions/CMakeLists.txt + :language: cmake + :start-after: # to find MathFunctions.h, while we don't. + :end-before: # should we use our own math functions + +Once this has been updated, we can re-run CMake and verify that it doesn't +warn anymore. + +At this point, we have CMake properly packaging the target information that is +required but we will still need to generate a ``MathFunctionsConfig.cmake`` so +that the CMake ``find_package`` command can find our project. So let's go +ahead and add a new file to the top-level of the project called +``Config.cmake.in`` with the following contents: + +.. literalinclude:: Complete/Config.cmake.in + +Then, to properly configure and install that file, add the following to the +bottom of the top-level ``CMakeLists.txt``: + +.. literalinclude:: Complete/CMakeLists.txt + :language: cmake + :start-after: # install the configuration targets + :end-before: # generate the export + +At this point, we have generated a relocatable CMake Configuration for our +project that can be used after the project has been installed or packaged. If +we want our project to also be used from a build directory we only have to add +the following to the bottom of the top level ``CMakeLists.txt``: + +.. literalinclude:: Complete/CMakeLists.txt + :language: cmake + :start-after: # needs to be after the install(TARGETS ) command + +With this export call we now generate a ``Targets.cmake``, allowing the +configured ``MathFunctionsConfig.cmake`` in the build directory to be used by +other projects, without needing it to be installed. + +Import a CMake Project (Consumer) +================================= + +This example shows how a project can find other CMake packages that +generate ``Config.cmake`` files. + +It also shows how to state a project's external dependencies when generating +a ``Config.cmake``. + +Packaging Debug and Release (MultiPackage) +========================================== + +By default CMake's model is that a build directory only contains a single +configuration, be it Debug, Release, MinSizeRel, or RelWithDebInfo. + +But it is possible to setup CPack to bundle multiple build directories at the +same time to build a package that contains multiple configurations of the +same project. + +First we need to construct a directory called ``multi_config``, which +will contain all the builds that we want to package together. + +Second create a ``debug`` and ``release`` directory underneath +``multi_config``. At the end you should have a layout that looks like: + +.. code-block:: none + + ─ multi_config + ├── debug + └── release + +Now we need to setup debug and release builds, which would roughly entail +the following: + +.. code-block:: console + + cd debug + cmake -DCMAKE_BUILD_TYPE=Debug ../../MultiPackage/ + cmake --build . + cd ../release + cmake -DCMAKE_BUILD_TYPE=Release ../../MultiPackage/ + cmake --build . + cd .. + + +Now that both the debug and release builds are complete, we can use +a custom ``MultiCPackConfig.cmake`` file to package both builds into a single +release. + +.. code-block:: console + + cpack --config ../../MultiPackage/MultiCPackConfig.cmake diff --git a/Help/index.rst b/Help/index.rst index 97cd1073b..cc6cee644 100644 --- a/Help/index.rst +++ b/Help/index.rst @@ -29,17 +29,30 @@ Reference Manuals /manual/cmake-commands.7 /manual/cmake-compile-features.7 /manual/cmake-developer.7 + /manual/cmake-env-variables.7 + /manual/cmake-file-api.7 /manual/cmake-generator-expressions.7 /manual/cmake-generators.7 /manual/cmake-language.7 - /manual/cmake-server.7 /manual/cmake-modules.7 /manual/cmake-packages.7 /manual/cmake-policies.7 /manual/cmake-properties.7 /manual/cmake-qt.7 + /manual/cmake-server.7 /manual/cmake-toolchains.7 /manual/cmake-variables.7 + /manual/cpack-generators.7 + +.. only:: not man + + Guides + ###### + + .. toctree:: + :maxdepth: 1 + + /guide/tutorial/index .. only:: html or text diff --git a/Help/manual/LINKS.txt b/Help/manual/LINKS.txt index 3993ff83d..810fa0b34 100644 --- a/Help/manual/LINKS.txt +++ b/Help/manual/LINKS.txt @@ -5,21 +5,13 @@ Home Page The primary starting point for learning about CMake. -Frequently Asked Questions - https://cmake.org/Wiki/CMake_FAQ - - A Wiki is provided containing answers to frequently asked questions. - -Online Documentation +Online Documentation and Community Resources https://cmake.org/documentation - Links to available documentation may be found on this web page. + Links to available documentation and community resources may be + found on this web page. -Mailing List - https://cmake.org/mailing-lists +Discourse Forum + https://discourse.cmake.org - For help and discussion about using cmake, a mailing list is - provided at cmake@cmake.org. The list is member-post-only but one - may sign up on the CMake web page. Please first read the full - documentation at https://cmake.org before posting questions to - the list. + The Discourse Forum hosts discussion and questions about CMake. diff --git a/Help/manual/OPTIONS_BUILD.txt b/Help/manual/OPTIONS_BUILD.txt index e8b87c923..0947e41cb 100644 --- a/Help/manual/OPTIONS_BUILD.txt +++ b/Help/manual/OPTIONS_BUILD.txt @@ -1,23 +1,34 @@ +``-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. - When cmake is first run in an empty build tree, it creates a - CMakeCache.txt file and populates it with customizable settings for + When CMake is first run in an empty build tree, it creates a + ``CMakeCache.txt`` file and populates it with customizable settings for the project. This option may be used to specify a file from which to load cache entries before the first pass through the project's - cmake listfiles. The loaded entries take priority over the + CMake listfiles. The loaded entries take priority over the project's default values. The given file should be a CMake script - containing SET commands that use the CACHE option, not a + containing :command:`set` commands that use the ``CACHE`` option, not a cache-format file. + References to :variable:`CMAKE_SOURCE_DIR` and :variable:`CMAKE_BINARY_DIR` + within the script evaluate to the top-level source and build tree. + ``-D <var>:<type>=<value>, -D <var>=<value>`` - Create a cmake cache entry. + Create or update a CMake ``CACHE`` entry. - When cmake is first run in an empty build tree, it creates a - CMakeCache.txt file and populates it with customizable settings for + When CMake is first run in an empty build tree, it creates a + ``CMakeCache.txt`` file and populates it with customizable settings for the project. This option may be used to specify a setting that takes priority over the project's default value. The option may be - repeated for as many cache entries as desired. + repeated for as many ``CACHE`` entries as desired. If the ``:<type>`` portion is given it must be one of the types specified by the :command:`set` command documentation for its @@ -31,14 +42,14 @@ ``-D<var>:<type>=<value>`` or ``-D<var>=<value>``. ``-U <globbing_expr>`` - Remove matching entries from CMake cache. + Remove matching entries from CMake ``CACHE``. This option may be used to remove one or more variables from the - CMakeCache.txt file, globbing expressions using * and ? are - supported. The option may be repeated for as many cache entries as + ``CMakeCache.txt`` file, globbing expressions using ``*`` and ``?`` are + supported. The option may be repeated for as many ``CACHE`` entries as desired. - Use with care, you can make your CMakeCache.txt non-working. + Use with care, you can make your ``CMakeCache.txt`` non-working. ``-G <generator-name>`` Specify a build system generator. @@ -48,6 +59,9 @@ build system. Possible generator names are specified in the :manual:`cmake-generators(7)` manual. + If not specified, CMake checks the :envvar:`CMAKE_GENERATOR` environment + variable and otherwise falls back to a builtin default selection. + ``-T <toolset-spec>`` Toolset specification for the generator, if supported. @@ -66,47 +80,47 @@ Suppress developer warnings. Suppress warnings that are meant for the author of the - CMakeLists.txt files. By default this will also turn off + ``CMakeLists.txt`` files. By default this will also turn off deprecation warnings. ``-Wdev`` Enable developer warnings. - Enable warnings that are meant for the author of the CMakeLists.txt + Enable warnings that are meant for the author of the ``CMakeLists.txt`` files. By default this will also turn on deprecation warnings. ``-Werror=dev`` Make developer warnings errors. - Make warnings that are meant for the author of the CMakeLists.txt files + Make warnings that are meant for the author of the ``CMakeLists.txt`` files errors. By default this will also turn on deprecated warnings as errors. ``-Wno-error=dev`` Make developer warnings not errors. - Make warnings that are meant for the author of the CMakeLists.txt files not + Make warnings that are meant for the author of the ``CMakeLists.txt`` files not errors. By default this will also turn off deprecated warnings as errors. ``-Wdeprecated`` Enable deprecated functionality warnings. Enable warnings for usage of deprecated functionality, that are meant - for the author of the CMakeLists.txt files. + for the author of the ``CMakeLists.txt`` files. ``-Wno-deprecated`` Suppress deprecated functionality warnings. Suppress warnings for usage of deprecated functionality, that are meant - for the author of the CMakeLists.txt files. + for the author of the ``CMakeLists.txt`` files. ``-Werror=deprecated`` Make deprecated macro and function warnings errors. Make warnings for usage of deprecated macros and functions, that are meant - for the author of the CMakeLists.txt files, errors. + for the author of the ``CMakeLists.txt`` files, errors. ``-Wno-error=deprecated`` Make deprecated macro and function warnings not errors. Make warnings for usage of deprecated macros and functions, that are meant - for the author of the CMakeLists.txt files, not errors. + for the author of the ``CMakeLists.txt`` files, not errors. diff --git a/Help/manual/ccmake.1.rst b/Help/manual/ccmake.1.rst index a5fe19168..60d45a35d 100644 --- a/Help/manual/ccmake.1.rst +++ b/Help/manual/ccmake.1.rst @@ -8,19 +8,19 @@ Synopsis .. parsed-literal:: - ccmake [<options>] (<path-to-source> | <path-to-existing-build>) + ccmake [<options>] {<path-to-source> | <path-to-existing-build>} Description =========== -The "ccmake" executable is the CMake curses interface. Project +The **ccmake** executable is the CMake curses interface. Project configuration settings may be specified interactively through this GUI. Brief instructions are provided at the bottom of the terminal when the program is running. CMake is a cross-platform build system generator. Projects specify their build process with platform-independent CMake listfiles included -in each directory of a source tree with the name CMakeLists.txt. +in each directory of a source tree with the name ``CMakeLists.txt``. Users build a project by using CMake to generate a build system for a native tool on their platform. diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index 95f5b8735..d8142a263 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -21,7 +21,7 @@ Binary Targets Executables and libraries are defined using the :command:`add_executable` and :command:`add_library` commands. The resulting binary files have -appropriate prefixes, suffixes and extensions for the platform targeted. +appropriate :prop_tgt:`PREFIX`, :prop_tgt:`SUFFIX` and extensions for the platform targeted. Dependencies between binary targets are expressed using the :command:`target_link_libraries` command: @@ -31,7 +31,7 @@ Dependencies between binary targets are expressed using the add_executable(zipapp zipapp.cpp) target_link_libraries(zipapp archive) -``archive`` is defined as a static library -- an archive containing objects +``archive`` is defined as a ``STATIC`` library -- an archive containing objects compiled from ``archive.cpp``, ``zip.cpp``, and ``lzma.cpp``. ``zipapp`` is defined as an executable formed by compiling and linking ``zipapp.cpp``. When linking the ``zipapp`` executable, the ``archive`` static library is @@ -59,7 +59,7 @@ Binary Library Types Normal Libraries ^^^^^^^^^^^^^^^^ -By default, the :command:`add_library` command defines a static library, +By default, the :command:`add_library` command defines a ``STATIC`` library, unless a type is specified. A type may be specified when using the command: .. code-block:: cmake @@ -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. @@ -113,9 +113,9 @@ and it uniquely identifies the bundle. Object Libraries ^^^^^^^^^^^^^^^^ -The ``OBJECT`` library type is also not linked to. It defines a non-archival -collection of object files resulting from compiling the given source files. -The object files collection can be used as source inputs to other targets: +The ``OBJECT`` library type defines a non-archival collection of object files +resulting from compiling the given source files. The object files collection +may be used as source inputs to other targets: .. code-block:: cmake @@ -125,22 +125,31 @@ The object files collection can be used as source inputs to other targets: add_executable(test_exe $<TARGET_OBJECTS:archive> test.cpp) -``OBJECT`` libraries may not be used in the right hand side of -:command:`target_link_libraries`. They also may not be used as the ``TARGET`` -in a use of the :command:`add_custom_command(TARGET)` command signature. They -may be installed, and will be exported as an INTERFACE library. +The link (or archiving) step of those other targets will use the object +files collection in addition to those from their own sources. -Although object libraries may not be named directly in calls to -the :command:`target_link_libraries` command, they can be "linked" -indirectly by using an :ref:`Interface Library <Interface Libraries>` -whose :prop_tgt:`INTERFACE_SOURCES` target property is set to name -``$<TARGET_OBJECTS:objlib>``. +Alternatively, object libraries may be linked into other targets: -Although object libraries may not be used as the ``TARGET`` -in a use of the :command:`add_custom_command(TARGET)` command signature, -the list of objects can be used by :command:`add_custom_command(OUTPUT)` or -:command:`file(GENERATE)` by using ``$<TARGET_OBJECTS:objlib>``. +.. code-block:: cmake + + add_library(archive OBJECT archive.cpp zip.cpp lzma.cpp) + + add_library(archiveExtras STATIC extras.cpp) + target_link_libraries(archiveExtras PUBLIC archive) + + add_executable(test_exe test.cpp) + target_link_libraries(test_exe archive) +The link (or archiving) step of those other targets will use the object +files from ``OBJECT`` libraries that are *directly* linked. Additionally, +usage requirements of the ``OBJECT`` libraries will be honored when compiling +sources in those other targets. Furthermore, those usage requirements +will propagate transitively to dependents of those other targets. + +Object libraries may not be used as the ``TARGET`` in a use of the +:command:`add_custom_command(TARGET)` command signature. However, +the list of objects can be used by :command:`add_custom_command(OUTPUT)` +or :command:`file(GENERATE)` by using ``$<TARGET_OBJECTS:objlib>``. Build Specification and Usage Requirements ========================================== @@ -266,7 +275,7 @@ The :command:`target_link_libraries` command has ``PRIVATE``, Because ``archive`` is a ``PUBLIC`` dependency of ``archiveExtras``, the usage requirements of it are propagated to ``consumer`` too. Because -``serialization`` is a ``PRIVATE`` dependency of ``archive``, the usage +``serialization`` is a ``PRIVATE`` dependency of ``archiveExtras``, the usage requirements of it are not propagated to ``consumer``. Generally, a dependency should be specified in a use of @@ -356,8 +365,8 @@ non-compatible requirements :manual:`cmake(1)` issues a diagnostic: target_link_libraries(exe2 lib1 lib2) The ``lib1`` requirement ``INTERFACE_POSITION_INDEPENDENT_CODE`` is not -"compatible" with the ``POSITION_INDEPENDENT_CODE`` property of the ``exe1`` -target. The library requires that consumers are built as +"compatible" with the :prop_tgt:`POSITION_INDEPENDENT_CODE` property of +the ``exe1`` target. The library requires that consumers are built as position-independent-code, while the executable specifies to not built as position-independent-code, so a diagnostic is issued. @@ -538,10 +547,10 @@ is not known until build-time. Therefore, code such as target_compile_definitions(exe1 PRIVATE DEBUG_BUILD) endif() -may appear to work for ``Makefile`` based and ``Ninja`` generators, but is not -portable to IDE generators. Additionally, the :prop_tgt:`IMPORTED` -configuration-mappings are not accounted for with code like this, so it should -be avoided. +may appear to work for :ref:`Makefile Generators` and :generator:`Ninja` +generators, but is not portable to IDE generators. Additionally, +the :prop_tgt:`IMPORTED` configuration-mappings are not accounted for +with code like this, so it should be avoided. The unary ``TARGET_PROPERTY`` generator expression and the ``TARGET_POLICY`` generator expression are evaluated with the consuming target context. This @@ -687,9 +696,10 @@ property are treated as ``SYSTEM`` include directories, as if they were listed in the :prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` of the dependency. This can result in omission of compiler warnings for headers found in those directories. This behavior for :ref:`imported targets` may -be controlled with the :prop_tgt:`NO_SYSTEM_FROM_IMPORTED` target property. +be controlled by setting the :prop_tgt:`NO_SYSTEM_FROM_IMPORTED` target +property on the *consumers* of imported targets. -If a binary target is linked transitively to a Mac OX framework, the +If a binary target is linked transitively to a macOS :prop_tgt:`FRAMEWORK`, the ``Headers`` directory of the framework is also treated as a usage requirement. This has the same effect as passing the framework directory as an include directory. @@ -774,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` @@ -801,6 +811,10 @@ An *archive* output artifact of a buildsystem target may be: executable target created by the :command:`add_executable` command when its :prop_tgt:`ENABLE_EXPORTS` target property is set. +* On AIX: the linker import file (e.g. ``.imp``) of an executable target + created by the :command:`add_executable` command when its + :prop_tgt:`ENABLE_EXPORTS` target property is set. + The :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY` and :prop_tgt:`ARCHIVE_OUTPUT_NAME` target properties may be used to control archive output artifact locations and names in the build tree. @@ -811,7 +825,7 @@ Directory-Scoped Commands The :command:`target_include_directories`, :command:`target_compile_definitions` and :command:`target_compile_options` commands have an effect on only one -target at a time. The commands :command:`add_definitions`, +target at a time. The commands :command:`add_compile_definitions`, :command:`add_compile_options` and :command:`include_directories` have a similar function, but operate at directory scope instead of target scope for convenience. @@ -830,12 +844,11 @@ Imported Targets An :prop_tgt:`IMPORTED` target represents a pre-existing dependency. Usually such targets are defined by an upstream package and should be treated as -immutable. It is not possible to use an :prop_tgt:`IMPORTED` target in the -left-hand-side of the :command:`target_compile_definitions`, -:command:`target_include_directories`, :command:`target_compile_options` or -:command:`target_link_libraries` commands, as that would be an attempt to -modify it. :prop_tgt:`IMPORTED` targets are designed to be used only in the -right-hand-side of those commands. +immutable. After declaring an :prop_tgt:`IMPORTED` target one can adjust its +target properties by using the customary commands such as +:command:`target_compile_definitions`, :command:`target_include_directories`, +:command:`target_compile_options` or :command:`target_link_libraries` just like +with any other regular target. :prop_tgt:`IMPORTED` targets may have the same usage requirement properties populated as binary targets, such as @@ -968,9 +981,10 @@ are: * Properties matching ``INTERFACE_*`` * Built-in properties matching ``COMPATIBLE_INTERFACE_*`` * ``EXPORT_NAME`` +* ``EXPORT_PROPERTIES`` * ``IMPORTED`` +* ``MANUALLY_ADDED_DEPENDENCIES`` * ``NAME`` -* ``NO_SYSTEM_FROM_IMPORTED`` * Properties matching ``IMPORTED_LIBNAME_*`` * Properties matching ``MAP_IMPORTED_CONFIG_*`` diff --git a/Help/manual/cmake-commands.7.rst b/Help/manual/cmake-commands.7.rst index 611c989a0..59ba89727 100644 --- a/Help/manual/cmake-commands.7.rst +++ b/Help/manual/cmake-commands.7.rst @@ -22,8 +22,8 @@ These commands are always available. /command/cmake_policy /command/configure_file /command/continue - /command/elseif /command/else + /command/elseif /command/endforeach /command/endfunction /command/endif @@ -44,6 +44,7 @@ These commands are always available. /command/get_property /command/if /command/include + /command/include_guard /command/list /command/macro /command/mark_as_advanced @@ -52,9 +53,9 @@ These commands are always available. /command/option /command/return /command/separate_arguments + /command/set /command/set_directory_properties /command/set_property - /command/set /command/site_name /command/string /command/unset @@ -69,6 +70,7 @@ These commands are available only in CMake projects. .. toctree:: :maxdepth: 1 + /command/add_compile_definitions /command/add_compile_options /command/add_custom_command /command/add_custom_target @@ -76,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 @@ -97,8 +100,6 @@ These commands are available only in CMake projects. /command/link_libraries /command/load_cache /command/project - /command/qt_wrap_cpp - /command/qt_wrap_ui /command/remove_definitions /command/set_source_files_properties /command/set_target_properties @@ -108,7 +109,10 @@ 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_precompile_headers /command/target_sources /command/try_compile /command/try_run @@ -140,8 +144,10 @@ These commands are available only in CTest scripts. Deprecated Commands =================== -These commands are available only for compatibility with older -versions of CMake. Do not use them in new code. +These commands are deprecated and are only made available to maintain +backward compatibility. The documentation of each command states the +CMake version in which it was deprecated. Do not use these commands +in new code. .. toctree:: :maxdepth: 1 @@ -155,6 +161,8 @@ versions of CMake. Do not use them in new code. /command/load_command /command/make_directory /command/output_required_files + /command/qt_wrap_cpp + /command/qt_wrap_ui /command/remove /command/subdir_depends /command/subdirs diff --git a/Help/manual/cmake-compile-features.7.rst b/Help/manual/cmake-compile-features.7.rst index 012439500..a14e3222c 100644 --- a/Help/manual/cmake-compile-features.7.rst +++ b/Help/manual/cmake-compile-features.7.rst @@ -28,10 +28,15 @@ CMake knows are known to the compiler, regardless of language standard or compile flags needed to use them. Features known to CMake are named mostly following the same convention -as the Clang feature test macros. The are some exceptions, such as +as the Clang feature test macros. There are some exceptions, such as CMake using ``cxx_final`` and ``cxx_override`` instead of the single ``cxx_override_control`` used by Clang. +Note that there are no separate compile features properties or variables for +the ``OBJC`` or ``OBJCXX`` languages. These are based off ``C`` or ``C++`` +respectively, so the properties and variables for their corresponding base +language should be used instead. + Compile Feature Requirements ============================ @@ -90,21 +95,21 @@ Requiring Language Standards In projects that use a large number of commonly available features from a particular language standard (e.g. C++ 11) one may specify a meta-feature (e.g. ``cxx_std_11``) that requires use of a compiler mode -aware of that standard. This is simpler than specifying all the -features individually, but does not guarantee the existence of any -particular feature. Diagnosis of use of unsupported features will be -delayed until compile time. +that is at minimum aware of that standard, but could be greater. +This is simpler than specifying all the features individually, but does +not guarantee the existence of any particular feature. +Diagnosis of use of unsupported features will be delayed until compile time. For example, if C++ 11 features are used extensively in a project's -header files, then clients must use a compiler mode aware of C++ 11 -or above. This can be requested with the code: +header files, then clients must use a compiler mode that is no less +than C++ 11. This can be requested with the code: .. code-block:: cmake target_compile_features(mylib PUBLIC cxx_std_11) In this example, CMake will ensure the compiler is invoked in a mode -that is aware of C++ 11 (or above), adding flags such as +of at-least C++ 11 (or C++ 14, C++ 17, ...), adding flags such as ``-std=gnu++11`` if necessary. This applies to sources within ``mylib`` as well as any dependents (that may include headers from ``mylib``). @@ -331,12 +336,12 @@ and :prop_gbl:`compile features <CMAKE_CXX_KNOWN_FEATURES>` available from the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the versions specified for each: -* ``AppleClang``: Apple Clang for Xcode versions 4.4 though 6.2. -* ``Clang``: Clang compiler versions 2.9 through 3.4. -* ``GNU``: GNU compiler versions 4.4 through 5.0. -* ``MSVC``: Microsoft Visual Studio versions 2010 through 2017. -* ``SunPro``: Oracle SolarisStudio versions 12.4 through 12.5. -* ``Intel``: Intel compiler versions 12.1 through 17.0. +* ``AppleClang``: Apple Clang for Xcode versions 4.4+. +* ``Clang``: Clang compiler versions 2.9+. +* ``GNU``: GNU compiler versions 4.4+. +* ``MSVC``: Microsoft Visual Studio versions 2010+. +* ``SunPro``: Oracle SolarisStudio versions 12.4+. +* ``Intel``: Intel compiler versions 12.1+. CMake is currently aware of the :prop_tgt:`C standards <C_STANDARD>` and :prop_gbl:`compile features <CMAKE_C_KNOWN_FEATURES>` available from @@ -344,16 +349,16 @@ the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the versions specified for each: * all compilers and versions listed above for C++. -* ``GNU``: GNU compiler versions 3.4 through 5.0. +* ``GNU``: GNU compiler versions 3.4+ CMake is currently aware of the :prop_tgt:`C++ standards <CXX_STANDARD>` and their associated meta-features (e.g. ``cxx_std_11``) available from the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the versions specified for each: -* ``Cray``: Cray Compiler Environment version 8.1 through 8.5.8. -* ``PGI``: PGI version 12.10 through 17.5. -* ``XL``: IBM XL version 10.1 through 13.1.5. +* ``Cray``: Cray Compiler Environment version 8.1+. +* ``PGI``: PGI version 12.10+. +* ``XL``: IBM XL version 10.1+. CMake is currently aware of the :prop_tgt:`C standards <C_STANDARD>` and their associated meta-features (e.g. ``c_std_99``) available from the @@ -361,9 +366,10 @@ following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the versions specified for each: * all compilers and versions listed above with only meta-features for C++. +* ``TI``: Texas Instruments compiler. CMake is currently aware of the :prop_tgt:`CUDA standards <CUDA_STANDARD>` from the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the versions specified for each: -* ``NVIDIA``: NVIDIA nvcc compiler 7.5 though 8.0. +* ``NVIDIA``: NVIDIA nvcc compiler 7.5+. diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst index cd509ac20..85ed935e6 100644 --- a/Help/manual/cmake-developer.7.rst +++ b/Help/manual/cmake-developer.7.rst @@ -10,580 +10,24 @@ cmake-developer(7) Introduction ============ -This manual is intended for reference by developers modifying the CMake -source tree itself, and by those authoring externally-maintained modules. - -Adding Compile Features -======================= - -CMake reports an error if a compiler whose features are known does not report -support for a particular requested feature. A compiler is considered to have -known features if it reports support for at least one feature. - -When adding a new compile feature to CMake, it is therefore necessary to list -support for the feature for all CompilerIds which already have one or more -feature supported, if the new feature is available for any version of the -compiler. - -When adding the first supported feature to a particular CompilerId, it is -necessary to list support for all features known to cmake (See -:variable:`CMAKE_C_COMPILE_FEATURES` and -:variable:`CMAKE_CXX_COMPILE_FEATURES` as appropriate), where available for -the compiler. Ensure that the ``CMAKE_<LANG>_STANDARD_DEFAULT`` is set to -the computed internal variable ``CMAKE_<LANG>_STANDARD_COMPUTED_DEFAULT`` -for compiler versions which should be supported. - -It is sensible to record the features for the most recent version of a -particular CompilerId first, and then work backwards. It is sensible to -try to create a continuous range of versions of feature releases of the -compiler. Gaps in the range indicate incorrect features recorded for -intermediate releases. - -Generally, features are made available for a particular version if the -compiler vendor documents availability of the feature with that -version. Note that sometimes partially implemented features appear to -be functional in previous releases (such as ``cxx_constexpr`` in GNU 4.6, -though availability is documented in GNU 4.7), and sometimes compiler vendors -document availability of features, though supporting infrastructure is -not available (such as ``__has_feature(cxx_generic_lambdas)`` indicating -non-availability in Clang 3.4, though it is documented as available, and -fixed in Clang 3.5). Similar cases for other compilers and versions -need to be investigated when extending CMake to support them. - -When a vendor releases a new version of a known compiler which supports -a previously unsupported feature, and there are already known features for -that compiler, the feature should be listed as supported in CMake for -that version of the compiler as soon as reasonably possible. - -Standard-specific/compiler-specific variables such -``CMAKE_CXX98_COMPILE_FEATURES`` are deliberately not documented. They -only exist for the compiler-specific implementation of adding the ``-std`` -compile flag for compilers which need that. - -Help -==== - -The ``Help`` directory contains CMake help manual source files. -They are written using the `reStructuredText`_ markup syntax and -processed by `Sphinx`_ to generate the CMake help manuals. - -.. _`reStructuredText`: http://docutils.sourceforge.net/docs/ref/rst/introduction.html -.. _`Sphinx`: http://sphinx-doc.org - -Markup Constructs ------------------ - -In addition to using Sphinx to generate the CMake help manuals, we -also use a C++-implemented document processor to print documents for -the ``--help-*`` command-line help options. It supports a subset of -reStructuredText markup. When authoring or modifying documents, -please verify that the command-line help looks good in addition to the -Sphinx-generated html and man pages. - -The command-line help processor supports the following constructs -defined by reStructuredText, Sphinx, and a CMake extension to Sphinx. - -.. - Note: This list must be kept consistent with the cmRST implementation. - -CMake Domain directives - Directives defined in the `CMake Domain`_ for defining CMake - documentation objects are printed in command-line help output as - if the lines were normal paragraph text with interpretation. - -CMake Domain interpreted text roles - Interpreted text roles defined in the `CMake Domain`_ for - cross-referencing CMake documentation objects are replaced by their - link text in command-line help output. Other roles are printed - literally and not processed. - -``code-block`` directive - Add a literal code block without interpretation. The command-line - help processor prints the block content without the leading directive - line and with common indentation replaced by one space. - -``include`` directive - Include another document source file. The command-line help - processor prints the included document inline with the referencing - document. - -literal block after ``::`` - A paragraph ending in ``::`` followed by a blank line treats - the following indented block as literal text without interpretation. - The command-line help processor prints the ``::`` literally and - prints the block content with common indentation replaced by one - space. - -``note`` directive - Call out a side note. The command-line help processor prints the - block content as if the lines were normal paragraph text with - interpretation. - -``parsed-literal`` directive - Add a literal block with markup interpretation. The command-line - help processor prints the block content without the leading - directive line and with common indentation replaced by one space. - -``productionlist`` directive - Render context-free grammar productions. The command-line help - processor prints the block content as if the lines were normal - paragraph text with interpretation. - -``replace`` directive - Define a ``|substitution|`` replacement. - The command-line help processor requires a substitution replacement - to be defined before it is referenced. - -``|substitution|`` reference - Reference a substitution replacement previously defined by - the ``replace`` directive. The command-line help processor - performs the substitution and replaces all newlines in the - replacement text with spaces. - -``toctree`` directive - Include other document sources in the Table-of-Contents - document tree. The command-line help processor prints - the referenced documents inline as part of the referencing - document. - -Inline markup constructs not listed above are printed literally in the -command-line help output. We prefer to use inline markup constructs that -look correct in source form, so avoid use of \\-escapes in favor of inline -literals when possible. - -Explicit markup blocks not matching directives listed above are removed from -command-line help output. Do not use them, except for plain ``..`` comments -that are removed by Sphinx too. +This manual is intended for reference by developers working with +:manual:`cmake-language(7)` code, whether writing their own modules, +authoring their own build systems, or working on CMake itself. -Note that nested indentation of blocks is not recognized by the -command-line help processor. Therefore: - -* Explicit markup blocks are recognized only when not indented - inside other blocks. - -* Literal blocks after paragraphs ending in ``::`` but not - at the top indentation level may consume all indented lines - following them. - -Try to avoid these cases in practice. - -CMake Domain ------------- - -CMake adds a `Sphinx Domain`_ called ``cmake``, also called the -"CMake Domain". It defines several "object" types for CMake -documentation: - -``command`` - A CMake language command. - -``generator`` - A CMake native build system generator. - See the :manual:`cmake(1)` command-line tool's ``-G`` option. - -``manual`` - A CMake manual page, like this :manual:`cmake-developer(7)` manual. - -``module`` - A CMake module. - See the :manual:`cmake-modules(7)` manual - and the :command:`include` command. - -``policy`` - A CMake policy. - See the :manual:`cmake-policies(7)` manual - and the :command:`cmake_policy` command. - -``prop_cache, prop_dir, prop_gbl, prop_sf, prop_inst, prop_test, prop_tgt`` - A CMake cache, directory, global, source file, installed file, test, - or target property, respectively. See the :manual:`cmake-properties(7)` - manual and the :command:`set_property` command. - -``variable`` - A CMake language variable. - See the :manual:`cmake-variables(7)` manual - and the :command:`set` command. - -Documentation objects in the CMake Domain come from two sources. -First, the CMake extension to Sphinx transforms every document named -with the form ``Help/<type>/<file-name>.rst`` to a domain object with -type ``<type>``. The object name is extracted from the document title, -which is expected to be of the form:: - - <object-name> - ------------- - -and to appear at or near the top of the ``.rst`` file before any other -lines starting in a letter, digit, or ``<``. If no such title appears -literally in the ``.rst`` file, the object name is the ``<file-name>``. -If a title does appear, it is expected that ``<file-name>`` is equal -to ``<object-name>`` with any ``<`` and ``>`` characters removed. - -Second, the CMake Domain provides directives to define objects inside -other documents: - -.. code-block:: rst - - .. command:: <command-name> - - This indented block documents <command-name>. - - .. variable:: <variable-name> - - This indented block documents <variable-name>. - -Object types for which no directive is available must be defined using -the first approach above. - -.. _`Sphinx Domain`: http://sphinx-doc.org/domains.html - -Cross-References ----------------- - -Sphinx uses reStructuredText interpreted text roles to provide -cross-reference syntax. The `CMake Domain`_ provides for each -domain object type a role of the same name to cross-reference it. -CMake Domain roles are inline markup of the forms:: - - :type:`name` - :type:`text <name>` - -where ``type`` is the domain object type and ``name`` is the -domain object name. In the first form the link text will be -``name`` (or ``name()`` if the type is ``command``) and in -the second form the link text will be the explicit ``text``. -For example, the code: - -.. code-block:: rst - - * The :command:`list` command. - * The :command:`list(APPEND)` sub-command. - * The :command:`list() command <list>`. - * The :command:`list(APPEND) sub-command <list>`. - * The :variable:`CMAKE_VERSION` variable. - * The :prop_tgt:`OUTPUT_NAME_<CONFIG>` target property. - -produces: - -* The :command:`list` command. -* The :command:`list(APPEND)` sub-command. -* The :command:`list() command <list>`. -* The :command:`list(APPEND) sub-command <list>`. -* The :variable:`CMAKE_VERSION` variable. -* The :prop_tgt:`OUTPUT_NAME_<CONFIG>` target property. - -Note that CMake Domain roles differ from Sphinx and reStructuredText -convention in that the form ``a<b>``, without a space preceding ``<``, -is interpreted as a name instead of link text with an explicit target. -This is necessary because we use ``<placeholders>`` frequently in -object names like ``OUTPUT_NAME_<CONFIG>``. The form ``a <b>``, -with a space preceding ``<``, is still interpreted as a link text -with an explicit target. - -Style ------ - -Style: Section Headers -^^^^^^^^^^^^^^^^^^^^^^ - -When marking section titles, make the section decoration line as long as -the title text. Use only a line below the title, not above. For -example: - -.. code-block:: rst - - Title Text - ---------- - -Capitalize the first letter of each non-minor word in the title. - -The section header underline character hierarchy is - -* ``#``: Manual group (part) in the master document -* ``*``: Manual (chapter) title -* ``=``: Section within a manual -* ``-``: Subsection or `CMake Domain`_ object document title -* ``^``: Subsubsection or `CMake Domain`_ object document section -* ``"``: Paragraph or `CMake Domain`_ object document subsection - -Style: Whitespace -^^^^^^^^^^^^^^^^^ - -Use two spaces for indentation. Use two spaces between sentences in -prose. - -Style: Line Length -^^^^^^^^^^^^^^^^^^ - -Prefer to restrict the width of lines to 75-80 columns. This is not a -hard restriction, but writing new paragraphs wrapped at 75 columns -allows space for adding minor content without significant re-wrapping of -content. - -Style: Prose -^^^^^^^^^^^^ - -Use American English spellings in prose. - -Style: Starting Literal Blocks -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Prefer to mark the start of literal blocks with ``::`` at the end of -the preceding paragraph. In cases where the following block gets -a ``code-block`` marker, put a single ``:`` at the end of the preceding -paragraph. - -Style: CMake Command Signatures -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Command signatures should be marked up as plain literal blocks, not as -cmake ``code-blocks``. - -Signatures are separated from preceding content by a section header. -That is, use: - -.. code-block:: rst - - ... preceding paragraph. - - Normal Libraries - ^^^^^^^^^^^^^^^^ - - :: - - add_library(<lib> ...) - - This signature is used for ... - -Signatures of commands should wrap optional parts with square brackets, -and should mark list of optional arguments with an ellipsis (``...``). -Elements of the signature which are specified by the user should be -specified with angle brackets, and may be referred to in prose using -``inline-literal`` syntax. - -Style: Boolean Constants -^^^^^^^^^^^^^^^^^^^^^^^^ - -Use "``OFF``" and "``ON``" for boolean values which can be modified by -the user, such as :prop_tgt:`POSITION_INDEPENDENT_CODE`. Such properties -may be "enabled" and "disabled". Use "``True``" and "``False``" for -inherent values which can't be modified after being set, such as the -:prop_tgt:`IMPORTED` property of a build target. - -Style: Inline Literals -^^^^^^^^^^^^^^^^^^^^^^ - -Mark up references to keywords in signatures, file names, and other -technical terms with ``inline-literal`` syntax, for example: - -.. code-block:: rst - - If ``WIN32`` is used with :command:`add_executable`, the - :prop_tgt:`WIN32_EXECUTABLE` target property is enabled. That command - creates the file ``<name>.exe`` on Windows. - -Style: Cross-References -^^^^^^^^^^^^^^^^^^^^^^^ - -Mark up linkable references as links, including repeats. -An alternative, which is used by wikipedia -(`<http://en.wikipedia.org/wiki/WP:REPEATLINK>`_), -is to link to a reference only once per article. That style is not used -in CMake documentation. - -Style: Referencing CMake Concepts -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If referring to a concept which corresponds to a property, and that -concept is described in a high-level manual, prefer to link to the -manual section instead of the property. For example: - -.. code-block:: rst - - This command creates an :ref:`Imported Target <Imported Targets>`. - -instead of: - -.. code-block:: rst - - This command creates an :prop_tgt:`IMPORTED` target. - -The latter should be used only when referring specifically to the -property. - -References to manual sections are not automatically created by creating -a section, but code such as: - -.. code-block:: rst - - .. _`Imported Targets`: - -creates a suitable anchor. Use an anchor name which matches the name -of the corresponding section. Refer to the anchor using a -cross-reference with specified text. - -Imported Targets need the ``IMPORTED`` term marked up with care in -particular because the term may refer to a command keyword -(``IMPORTED``), a target property (:prop_tgt:`IMPORTED`), or a -concept (:ref:`Imported Targets`). - -Where a property, command or variable is related conceptually to others, -by for example, being related to the buildsystem description, generator -expressions or Qt, each relevant property, command or variable should -link to the primary manual, which provides high-level information. Only -particular information relating to the command should be in the -documentation of the command. - -Style: Referencing CMake Domain Objects -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -When referring to `CMake Domain`_ objects such as properties, variables, -commands etc, prefer to link to the target object and follow that with -the type of object it is. For example: - -.. code-block:: rst - - Set the :prop_tgt:`AUTOMOC` target property to ``ON``. - -Instead of - -.. code-block:: rst - - Set the target property :prop_tgt:`AUTOMOC` to ``ON``. - -The ``policy`` directive is an exception, and the type us usually -referred to before the link: - -.. code-block:: rst - - If policy :prop_tgt:`CMP0022` is set to ``NEW`` the behavior is ... - -However, markup self-references with ``inline-literal`` syntax. -For example, within the :command:`add_executable` command -documentation, use - -.. code-block:: rst - - ``add_executable`` - -not - -.. code-block:: rst - - :command:`add_executable` - -which is used elsewhere. - -Modules -======= - -The ``Modules`` directory contains CMake-language ``.cmake`` module files. - -Module Documentation --------------------- - -To document CMake module ``Modules/<module-name>.cmake``, modify -``Help/manual/cmake-modules.7.rst`` to reference the module in the -``toctree`` directive, in sorted order, as:: - - /module/<module-name> - -Then add the module document file ``Help/module/<module-name>.rst`` -containing just the line:: - - .. cmake-module:: ../../Modules/<module-name>.cmake - -The ``cmake-module`` directive will scan the module file to extract -reStructuredText markup from comment blocks that start in ``.rst:``. -At the top of ``Modules/<module-name>.cmake``, begin with the following -license notice: - -.. code-block:: cmake - - # Distributed under the OSI-approved BSD 3-Clause License. See accompanying - # file Copyright.txt or https://cmake.org/licensing for details. - -After this notice, add a *BLANK* line. Then, add documentation using -a :ref:`Line Comment` block of the form: - -.. code-block:: cmake - - #.rst: - # <module-name> - # ------------- - # - # <reStructuredText documentation of module> - -or a :ref:`Bracket Comment` of the form: - -:: - - #[[.rst: - <module-name> - ------------- - - <reStructuredText documentation of module> - #]] - -Any number of ``=`` may be used in the opening and closing brackets -as long as they match. Content on the line containing the closing -bracket is excluded if and only if the line starts in ``#``. - -Additional such ``.rst:`` comments may appear anywhere in the module file. -All such comments must start with ``#`` in the first column. - -For example, a ``Modules/Findxxx.cmake`` module may contain: - -:: - - # Distributed under the OSI-approved BSD 3-Clause License. See accompanying - # file Copyright.txt or https://cmake.org/licensing for details. - - #.rst: - # FindXxx - # ------- - # - # This is a cool module. - # This module does really cool stuff. - # It can do even more than you think. - # - # It even needs two paragraphs to tell you about it. - # And it defines the following variables: - # - # * VAR_COOL: this is great isn't it? - # * VAR_REALLY_COOL: cool right? - - <code> - - #[========================================[.rst: - .. command:: xxx_do_something - - This command does something for Xxx:: - - xxx_do_something(some arguments) - #]========================================] - macro(xxx_do_something) - <code> - endmacro() - -Test the documentation formatting by running -``cmake --help-module <module-name>``, and also by enabling the -``SPHINX_HTML`` and ``SPHINX_MAN`` options to build the documentation. -Edit the comments until generated documentation looks satisfactory. To -have a .cmake file in this directory NOT show up in the modules -documentation, simply leave out the ``Help/module/<module-name>.rst`` -file and the ``Help/manual/cmake-modules.7.rst`` toctree entry. +See https://cmake.org/get-involved/ to get involved in development of +CMake upstream. It includes links to contribution instructions, which +in turn link to developer guides for CMake itself. .. _`Find Modules`: 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 ``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 @@ -638,14 +82,11 @@ and required is up to the find module, but should be documented. For internal implementation, it is a generally accepted convention that variables starting with underscore are for temporary use only. -Like all modules, find modules should be properly documented. To add a -module to the CMake documentation, follow the steps in the `Module -Documentation`_ section above. - +.. _`CMake Developer Standard Variable Names`: Standard Variable Names -^^^^^^^^^^^^^^^^^^^^^^^ +----------------------- For a ``FindXxx.cmake`` module that takes the approach of setting variables (either instead of or in addition to creating imported @@ -752,54 +193,81 @@ Make sure you comment them as deprecated, so that no-one starts using them. - A Sample Find Module -^^^^^^^^^^^^^^^^^^^^ +-------------------- -We will describe how to create a simple find module for a library -``Foo``. +We will describe how to create a simple find module for a library ``Foo``. -The first thing that is needed is a license notice. +The top of the module should begin with a license notice, followed by +a blank line, and then followed by a :ref:`Bracket Comment`. The comment +should begin with ``.rst:`` to indicate that the rest of its content is +reStructuredText-format documentation. For example: -.. code-block:: cmake +:: - # Distributed under the OSI-approved BSD 3-Clause License. See accompanying - # file Copyright.txt or https://cmake.org/licensing for details. + # Distributed under the OSI-approved BSD 3-Clause License. See accompanying + # file Copyright.txt or https://cmake.org/licensing for details. -Next we need module documentation. CMake's documentation system requires you -to follow the license notice with a blank line and then with a documentation -marker and the name of the module. You should follow this with a simple -statement of what the module does. + #[=======================================================================[.rst: + FindFoo + ------- -.. code-block:: cmake + Finds the Foo library. - #.rst: - # FindFoo - # ------- - # - # Finds the Foo library - # + Imported Targets + ^^^^^^^^^^^^^^^^ -More description may be required for some packages. If there are -caveats or other details users of the module should be aware of, you can -add further paragraphs below this. Then you need to document what -variables and imported targets are set by the module, such as + This module provides the following imported targets, if found: -.. code-block:: cmake + ``Foo::Foo`` + The Foo library + + Result Variables + ^^^^^^^^^^^^^^^^ + + This will define the following variables: + + ``Foo_FOUND`` + True if the system has the Foo library. + ``Foo_VERSION`` + The version of the Foo library which was found. + ``Foo_INCLUDE_DIRS`` + Include directories needed to use Foo. + ``Foo_LIBRARIES`` + Libraries needed to link to Foo. + + Cache Variables + ^^^^^^^^^^^^^^^ + + The following cache variables may also be set: + + ``Foo_INCLUDE_DIR`` + The directory containing ``foo.h``. + ``Foo_LIBRARY`` + The path to the Foo library. + + #]=======================================================================] + +The module documentation consists of: + +* An underlined heading specifying the module name. + +* A simple description of what the module finds. + More description may be required for some packages. If there are + caveats or other details users of the module should be aware of, + specify them here. + +* A section listing imported targets provided by the module, if any. + +* A section listing result variables provided by the module. - # This will define the following variables:: - # - # Foo_FOUND - True if the system has the Foo library - # Foo_VERSION - The version of the Foo library which was found - # - # and the following imported targets:: - # - # Foo::Foo - The Foo library +* Optionally a section listing cache variables used by the module, if any. -If the package provides any macros, they should be listed here, but can -be documented where they are defined. See the `Module -Documentation`_ section above for more details. +If the package provides any macros or functions, they should be listed in +an additional section, but can be documented by additional ``.rst:`` +comment blocks immediately above where those macros or functions are defined. +The find module implementation may begin below the documentation block. Now the actual libraries and so on have to be found. The code here will obviously vary from module to module (dealing with that, after all, is the point of find modules), but there tends to be a common pattern for libraries. @@ -943,7 +411,7 @@ populated: endif() The ``RELEASE`` variant should be listed first in the property -so that that variant is chosen if the user uses a configuration which is +so that the variant is chosen if the user uses a configuration which is not an exact match for any listed ``IMPORTED_CONFIGURATIONS``. Most of the cache variables should be hidden in the ``ccmake`` interface unless diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst new file mode 100644 index 000000000..96ceb945a --- /dev/null +++ b/Help/manual/cmake-env-variables.7.rst @@ -0,0 +1,73 @@ +.. cmake-manual-description: CMake Environment Variables Reference + +cmake-env-variables(7) +********************** + +.. only:: html + + .. contents:: + +This page lists environment variables that have special +meaning to CMake. + +For general information on environment variables, see the +:ref:`Environment Variables <CMake Language Environment Variables>` +section in the cmake-language manual. + + +Environment Variables that Control the Build +============================================ + +.. toctree:: + :maxdepth: 1 + + /envvar/CMAKE_BUILD_PARALLEL_LEVEL + /envvar/CMAKE_CONFIG_TYPE + /envvar/CMAKE_GENERATOR + /envvar/CMAKE_GENERATOR_INSTANCE + /envvar/CMAKE_GENERATOR_PLATFORM + /envvar/CMAKE_GENERATOR_TOOLSET + /envvar/CMAKE_MSVCIDE_RUN_PATH + /envvar/CMAKE_NO_VERBOSE + /envvar/CMAKE_OSX_ARCHITECTURES + /envvar/DESTDIR + /envvar/LDFLAGS + /envvar/MACOSX_DEPLOYMENT_TARGET + /envvar/PackageName_ROOT + /envvar/VERBOSE + +Environment Variables for Languages +=================================== + +.. toctree:: + :maxdepth: 1 + + /envvar/ASM_DIALECT + /envvar/ASM_DIALECTFLAGS + /envvar/CC + /envvar/CFLAGS + /envvar/CSFLAGS + /envvar/CUDACXX + /envvar/CUDAFLAGS + /envvar/CUDAHOSTCXX + /envvar/CXX + /envvar/CXXFLAGS + /envvar/FC + /envvar/FFLAGS + /envvar/RC + /envvar/RCFLAGS + /envvar/SWIFTC + +Environment Variables for CTest +=============================== + +.. toctree:: + :maxdepth: 1 + + /envvar/CMAKE_CONFIG_TYPE + /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 diff --git a/Help/manual/cmake-file-api.7.rst b/Help/manual/cmake-file-api.7.rst new file mode 100644 index 000000000..04b6ed259 --- /dev/null +++ b/Help/manual/cmake-file-api.7.rst @@ -0,0 +1,1113 @@ +.. cmake-manual-description: CMake File-Based API + +cmake-file-api(7) +***************** + +.. only:: html + + .. contents:: + +Introduction +============ + +CMake provides a file-based API that clients may use to get semantic +information about the buildsystems CMake generates. Clients may use +the API by writing query files to a specific location in a build tree +to request zero or more `Object Kinds`_. When CMake generates the +buildsystem in that build tree it will read the query files and write +reply files for the client to read. + +The file-based API uses a ``<build>/.cmake/api/`` directory at the top +of a build tree. The API is versioned to support changes to the layout +of files within the API directory. API file layout versioning is +orthogonal to the versioning of `Object Kinds`_ used in replies. +This version of CMake supports only one API version, `API v1`_. + +API v1 +====== + +API v1 is housed in the ``<build>/.cmake/api/v1/`` directory. +It has the following subdirectories: + +``query/`` + Holds query files written by clients. + These may be `v1 Shared Stateless Query Files`_, + `v1 Client Stateless Query Files`_, or `v1 Client Stateful Query Files`_. + +``reply/`` + Holds reply files written by CMake whenever it runs to generate a build + system. These are indexed by a `v1 Reply Index File`_ file that may + reference additional `v1 Reply Files`_. CMake owns all reply files. + Clients must never remove them. + + Clients may look for and read a reply index file at any time. + Clients may optionally create the ``reply/`` directory at any time + and monitor it for the appearance of a new reply index file. + +v1 Shared Stateless Query Files +------------------------------- + +Shared stateless query files allow clients to share requests for +major versions of the `Object Kinds`_ and get all requested versions +recognized by the CMake that runs. + +Clients may create shared requests by creating empty files in the +``v1/query/`` directory. The form is:: + + <build>/.cmake/api/v1/query/<kind>-v<major> + +where ``<kind>`` is one of the `Object Kinds`_, ``-v`` is literal, +and ``<major>`` is the major version number. + +Files of this form are stateless shared queries not owned by any specific +client. Once created they should not be removed without external client +coordination or human intervention. + +v1 Client Stateless Query Files +------------------------------- + +Client stateless query files allow clients to create owned requests for +major versions of the `Object Kinds`_ and get all requested versions +recognized by the CMake that runs. + +Clients may create owned requests by creating empty files in +client-specific query subdirectories. The form is:: + + <build>/.cmake/api/v1/query/client-<client>/<kind>-v<major> + +where ``client-`` is literal, ``<client>`` is a string uniquely +identifying the client, ``<kind>`` is one of the `Object Kinds`_, +``-v`` is literal, and ``<major>`` is the major version number. +Each client must choose a unique ``<client>`` identifier via its +own means. + +Files of this form are stateless queries owned by the client ``<client>``. +The owning client may remove them at any time. + +v1 Client Stateful Query Files +------------------------------ + +Stateful query files allow clients to request a list of versions of +each of the `Object Kinds`_ and get only the most recent version +recognized by the CMake that runs. + +Clients may create owned stateful queries by creating ``query.json`` +files in client-specific query subdirectories. The form is:: + + <build>/.cmake/api/v1/query/client-<client>/query.json + +where ``client-`` is literal, ``<client>`` is a string uniquely +identifying the client, and ``query.json`` is literal. Each client +must choose a unique ``<client>`` identifier via its own means. + +``query.json`` files are stateful queries owned by the client ``<client>``. +The owning client may update or remove them at any time. When a +given client installation is updated it may then update the stateful +query it writes to build trees to request newer object versions. +This can be used to avoid asking CMake to generate multiple object +versions unnecessarily. + +A ``query.json`` file must contain a JSON object: + +.. code-block:: json + + { + "requests": [ + { "kind": "<kind>" , "version": 1 }, + { "kind": "<kind>" , "version": { "major": 1, "minor": 2 } }, + { "kind": "<kind>" , "version": [2, 1] }, + { "kind": "<kind>" , "version": [2, { "major": 1, "minor": 2 }] }, + { "kind": "<kind>" , "version": 1, "client": {} }, + { "kind": "..." } + ], + "client": {} + } + +The members are: + +``requests`` + A JSON array containing zero or more requests. Each request is + a JSON object with members: + + ``kind`` + Specifies one of the `Object Kinds`_ to be included in the reply. + + ``version`` + Indicates the version(s) of the object kind that the client + understands. Versions have major and minor components following + semantic version conventions. The value must be + + * a JSON integer specifying a (non-negative) major version number, or + * a JSON object containing ``major`` and (optionally) ``minor`` + members specifying non-negative integer version components, or + * a JSON array whose elements are each one of the above. + + ``client`` + Optional member reserved for use by the client. This value is + preserved in the reply written for the client in the + `v1 Reply Index File`_ but is otherwise ignored. Clients may use + this to pass custom information with a request through to its reply. + + For each requested object kind CMake will choose the *first* version + that it recognizes for that kind among those listed in the request. + The response will use the selected *major* version with the highest + *minor* version known to the running CMake for that major version. + Therefore clients should list all supported major versions in + preferred order along with the minimal minor version required + for each major version. + +``client`` + Optional member reserved for use by the client. This value is + preserved in the reply written for the client in the + `v1 Reply Index File`_ but is otherwise ignored. Clients may use + this to pass custom information with a query through to its reply. + +Other ``query.json`` top-level members are reserved for future use. +If present they are ignored for forward compatibility. + +v1 Reply Index File +------------------- + +CMake writes an ``index-*.json`` file to the ``v1/reply/`` directory +whenever it runs to generate a build system. Clients must read the +reply index file first and may read other `v1 Reply Files`_ only by +following references. The form of the reply index file name is:: + + <build>/.cmake/api/v1/reply/index-<unspecified>.json + +where ``index-`` is literal and ``<unspecified>`` is an unspecified +name selected by CMake. Whenever a new index file is generated it +is given a new name and any old one is deleted. During the short +time between these steps there may be multiple index files present; +the one with the largest name in lexicographic order is the current +index file. + +The reply index file contains a JSON object: + +.. code-block:: json + + { + "cmake": { + "version": { + "major": 3, "minor": 14, "patch": 0, "suffix": "", + "string": "3.14.0", "isDirty": false + }, + "paths": { + "cmake": "/prefix/bin/cmake", + "ctest": "/prefix/bin/ctest", + "cpack": "/prefix/bin/cpack", + "root": "/prefix/share/cmake-3.14" + }, + "generator": { + "name": "Unix Makefiles" + } + }, + "objects": [ + { "kind": "<kind>", + "version": { "major": 1, "minor": 0 }, + "jsonFile": "<file>" }, + { "...": "..." } + ], + "reply": { + "<kind>-v<major>": { "kind": "<kind>", + "version": { "major": 1, "minor": 0 }, + "jsonFile": "<file>" }, + "<unknown>": { "error": "unknown query file" }, + "...": {}, + "client-<client>": { + "<kind>-v<major>": { "kind": "<kind>", + "version": { "major": 1, "minor": 0 }, + "jsonFile": "<file>" }, + "<unknown>": { "error": "unknown query file" }, + "...": {}, + "query.json": { + "requests": [ {}, {}, {} ], + "responses": [ + { "kind": "<kind>", + "version": { "major": 1, "minor": 0 }, + "jsonFile": "<file>" }, + { "error": "unknown query file" }, + { "...": {} } + ], + "client": {} + } + } + } + } + +The members are: + +``cmake`` + A JSON object containing information about the instance of CMake that + generated the reply. It contains members: + + ``version`` + A JSON object specifying the version of CMake with members: + + ``major``, ``minor``, ``patch`` + Integer values specifying the major, minor, and patch version components. + ``suffix`` + A string specifying the version suffix, if any, e.g. ``g0abc3``. + ``string`` + A string specifying the full version in the format + ``<major>.<minor>.<patch>[-<suffix>]``. + ``isDirty`` + A boolean indicating whether the version was built from a version + controlled source tree with local modifications. + + ``paths`` + A JSON object specifying paths to things that come with CMake. + It has members for ``cmake``, ``ctest``, and ``cpack`` whose values + are JSON strings specifying the absolute path to each tool, + represented with forward slashes. It also has a ``root`` member for + the absolute path to the directory containing CMake resources like the + ``Modules/`` directory (see :variable:`CMAKE_ROOT`). + + ``generator`` + A JSON object describing the CMake generator used for the build. + It has members: + + ``name`` + A string specifying the name of the generator. + ``platform`` + If the generator supports :variable:`CMAKE_GENERATOR_PLATFORM`, + this is a string specifying the generator platform name. + +``objects`` + A JSON array listing all versions of all `Object Kinds`_ generated + as part of the reply. Each array entry is a + `v1 Reply File Reference`_. + +``reply`` + A JSON object mirroring the content of the ``query/`` directory + that CMake loaded to produce the reply. The members are of the form + + ``<kind>-v<major>`` + A member of this form appears for each of the + `v1 Shared Stateless Query Files`_ that CMake recognized as a + request for object kind ``<kind>`` with major version ``<major>``. + The value is a `v1 Reply File Reference`_ to the corresponding + reply file for that object kind and version. + + ``<unknown>`` + A member of this form appears for each of the + `v1 Shared Stateless Query Files`_ that CMake did not recognize. + The value is a JSON object with a single ``error`` member + containing a string with an error message indicating that the + query file is unknown. + + ``client-<client>`` + A member of this form appears for each client-owned directory + holding `v1 Client Stateless Query Files`_. + The value is a JSON object mirroring the content of the + ``query/client-<client>/`` directory. The members are of the form: + + ``<kind>-v<major>`` + A member of this form appears for each of the + `v1 Client Stateless Query Files`_ that CMake recognized as a + request for object kind ``<kind>`` with major version ``<major>``. + The value is a `v1 Reply File Reference`_ to the corresponding + reply file for that object kind and version. + + ``<unknown>`` + A member of this form appears for each of the + `v1 Client Stateless Query Files`_ that CMake did not recognize. + The value is a JSON object with a single ``error`` member + containing a string with an error message indicating that the + query file is unknown. + + ``query.json`` + This member appears for clients using + `v1 Client Stateful Query Files`_. + If the ``query.json`` file failed to read or parse as a JSON object, + this member is a JSON object with a single ``error`` member + containing a string with an error message. Otherwise, this member + is a JSON object mirroring the content of the ``query.json`` file. + The members are: + + ``client`` + A copy of the ``query.json`` file ``client`` member, if it exists. + + ``requests`` + A copy of the ``query.json`` file ``requests`` member, if it exists. + + ``responses`` + If the ``query.json`` file ``requests`` member is missing or invalid, + this member is a JSON object with a single ``error`` member + containing a string with an error message. Otherwise, this member + contains a JSON array with a response for each entry of the + ``requests`` array, in the same order. Each response is + + * a JSON object with a single ``error`` member containing a string + with an error message, or + * a `v1 Reply File Reference`_ to the corresponding reply file for + the requested object kind and selected version. + +After reading the reply index file, clients may read the other +`v1 Reply Files`_ it references. + +v1 Reply File Reference +^^^^^^^^^^^^^^^^^^^^^^^ + +The reply index file represents each reference to another reply file +using a JSON object with members: + +``kind`` + A string specifying one of the `Object Kinds`_. +``version`` + A JSON object with members ``major`` and ``minor`` specifying + integer version components of the object kind. +``jsonFile`` + A JSON string specifying a path relative to the reply index file + to another JSON file containing the object. + +v1 Reply Files +-------------- + +Reply files containing specific `Object Kinds`_ are written by CMake. +The names of these files are unspecified and must not be interpreted +by clients. Clients must first read the `v1 Reply Index File`_ and +and follow references to the names of the desired response objects. + +Reply files (including the index file) will never be replaced by +files of the same name but different content. This allows a client +to read the files concurrently with a running CMake that may generate +a new reply. However, after generating a new reply CMake will attempt +to remove reply files from previous runs that it did not just write. +If a client attempts to read a reply file referenced by the index but +finds the file missing, that means a concurrent CMake has generated +a new reply. The client may simply start again by reading the new +reply index file. + +.. _`file-api object kinds`: + +Object Kinds +============ + +The CMake file-based API reports semantic information about the build +system using the following kinds of JSON objects. Each kind of object +is versioned independently using semantic versioning with major and +minor components. Every kind of object has the form: + +.. code-block:: json + + { + "kind": "<kind>", + "version": { "major": 1, "minor": 0 }, + "...": {} + } + +The ``kind`` member is a string specifying the object kind name. +The ``version`` member is a JSON object with ``major`` and ``minor`` +members specifying integer components of the object kind's version. +Additional top-level members are specific to each object kind. + +Object Kind "codemodel" +----------------------- + +The ``codemodel`` object kind describes the build system structure as +modeled by CMake. + +There is only one ``codemodel`` object major version, version 2. +Version 1 does not exist to avoid confusion with that from +:manual:`cmake-server(7)` mode. + +"codemodel" version 2 +^^^^^^^^^^^^^^^^^^^^^ + +``codemodel`` object version 2 is a JSON object: + +.. code-block:: json + + { + "kind": "codemodel", + "version": { "major": 2, "minor": 0 }, + "paths": { + "source": "/path/to/top-level-source-dir", + "build": "/path/to/top-level-build-dir" + }, + "configurations": [ + { + "name": "Debug", + "directories": [ + { + "source": ".", + "build": ".", + "childIndexes": [ 1 ], + "projectIndex": 0, + "targetIndexes": [ 0 ], + "hasInstallRule": true, + "minimumCMakeVersion": { + "string": "3.14" + } + }, + { + "source": "sub", + "build": "sub", + "parentIndex": 0, + "projectIndex": 0, + "targetIndexes": [ 1 ], + "minimumCMakeVersion": { + "string": "3.14" + } + } + ], + "projects": [ + { + "name": "MyProject", + "directoryIndexes": [ 0, 1 ], + "targetIndexes": [ 0, 1 ] + } + ], + "targets": [ + { + "name": "MyExecutable", + "directoryIndex": 0, + "projectIndex": 0, + "jsonFile": "<file>" + }, + { + "name": "MyLibrary", + "directoryIndex": 1, + "projectIndex": 0, + "jsonFile": "<file>" + } + ] + } + ] + } + +The members specific to ``codemodel`` objects are: + +``paths`` + A JSON object containing members: + + ``source`` + A string specifying the absolute path to the top-level source directory, + represented with forward slashes. + + ``build`` + A string specifying the absolute path to the top-level build directory, + represented with forward slashes. + +``configurations`` + A JSON array of entries corresponding to available build configurations. + On single-configuration generators there is one entry for the value + of the :variable:`CMAKE_BUILD_TYPE` variable. For multi-configuration + generators there is an entry for each configuration listed in the + :variable:`CMAKE_CONFIGURATION_TYPES` variable. + Each entry is a JSON object containing members: + + ``name`` + A string specifying the name of the configuration, e.g. ``Debug``. + + ``directories`` + A JSON array of entries each corresponding to a build system directory + whose source directory contains a ``CMakeLists.txt`` file. The first + entry corresponds to the top-level directory. Each entry is a + JSON object containing members: + + ``source`` + A string specifying the path to the source directory, represented + with forward slashes. If the directory is inside the top-level + source directory then the path is specified relative to that + directory (with ``.`` for the top-level source directory itself). + Otherwise the path is absolute. + + ``build`` + A string specifying the path to the build directory, represented + with forward slashes. If the directory is inside the top-level + build directory then the path is specified relative to that + directory (with ``.`` for the top-level build directory itself). + Otherwise the path is absolute. + + ``parentIndex`` + Optional member that is present when the directory is not top-level. + The value is an unsigned integer 0-based index of another entry in + the main ``directories`` array that corresponds to the parent + directory that added this directory as a subdirectory. + + ``childIndexes`` + Optional member that is present when the directory has subdirectories. + The value is a JSON array of entries corresponding to child directories + created by the :command:`add_subdirectory` or :command:`subdirs` + command. Each entry is an unsigned integer 0-based index of another + entry in the main ``directories`` array. + + ``projectIndex`` + An unsigned integer 0-based index into the main ``projects`` array + indicating the build system project to which the this directory belongs. + + ``targetIndexes`` + Optional member that is present when the directory itself has targets, + excluding those belonging to subdirectories. The value is a JSON + array of entries corresponding to the targets. Each entry is an + unsigned integer 0-based index into the main ``targets`` array. + + ``minimumCMakeVersion`` + Optional member present when a minimum required version of CMake is + known for the directory. This is the ``<min>`` version given to the + most local call to the :command:`cmake_minimum_required(VERSION)` + command in the directory itself or one of its ancestors. + The value is a JSON object with one member: + + ``string`` + A string specifying the minimum required version in the format:: + + <major>.<minor>[.<patch>[.<tweak>]][<suffix>] + + Each component is an unsigned integer and the suffix may be an + arbitrary string. + + ``hasInstallRule`` + Optional member that is present with boolean value ``true`` when + the directory or one of its subdirectories contains any + :command:`install` rules, i.e. whether a ``make install`` + or equivalent rule is available. + + ``projects`` + A JSON array of entries corresponding to the top-level project + and sub-projects defined in the build system. Each (sub-)project + corresponds to a source directory whose ``CMakeLists.txt`` file + calls the :command:`project` command with a project name different + from its parent directory. The first entry corresponds to the + top-level project. + + Each entry is a JSON object containing members: + + ``name`` + A string specifying the name given to the :command:`project` command. + + ``parentIndex`` + Optional member that is present when the project is not top-level. + The value is an unsigned integer 0-based index of another entry in + the main ``projects`` array that corresponds to the parent project + that added this project as a sub-project. + + ``childIndexes`` + Optional member that is present when the project has sub-projects. + The value is a JSON array of entries corresponding to the sub-projects. + Each entry is an unsigned integer 0-based index of another + entry in the main ``projects`` array. + + ``directoryIndexes`` + A JSON array of entries corresponding to build system directories + that are part of the project. The first entry corresponds to the + top-level directory of the project. Each entry is an unsigned + integer 0-based index into the main ``directories`` array. + + ``targetIndexes`` + Optional member that is present when the project itself has targets, + excluding those belonging to sub-projects. The value is a JSON + array of entries corresponding to the targets. Each entry is an + unsigned integer 0-based index into the main ``targets`` array. + + ``targets`` + A JSON array of entries corresponding to the build system targets. + Such targets are created by calls to :command:`add_executable`, + :command:`add_library`, and :command:`add_custom_target`, excluding + imported targets and interface libraries (which do not generate any + build rules). Each entry is a JSON object containing members: + + ``name`` + A string specifying the target name. + + ``id`` + A string uniquely identifying the target. This matches the ``id`` + field in the file referenced by ``jsonFile``. + + ``directoryIndex`` + An unsigned integer 0-based index into the main ``directories`` array + indicating the build system directory in which the target is defined. + + ``projectIndex`` + An unsigned integer 0-based index into the main ``projects`` array + indicating the build system project in which the target is defined. + + ``jsonFile`` + A JSON string specifying a path relative to the codemodel file + to another JSON file containing a + `"codemodel" version 2 "target" object`_. + +"codemodel" version 2 "target" object +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A codemodel "target" object is referenced by a `"codemodel" version 2`_ +object's ``targets`` array. Each "target" object is a JSON object +with members: + +``name`` + A string specifying the logical name of the target. + +``id`` + A string uniquely identifying the target. The format is unspecified + and should not be interpreted by clients. + +``type`` + A string specifying the type of the target. The value is one of + ``EXECUTABLE``, ``STATIC_LIBRARY``, ``SHARED_LIBRARY``, + ``MODULE_LIBRARY``, ``OBJECT_LIBRARY``, or ``UTILITY``. + +``backtrace`` + Optional member that is present when a CMake language backtrace to + the command in the source code that created the target is available. + The value is an unsigned integer 0-based index into the + ``backtraceGraph`` member's ``nodes`` array. + +``folder`` + Optional member that is present when the :prop_tgt:`FOLDER` target + property is set. The value is a JSON object with one member: + + ``name`` + A string specifying the name of the target folder. + +``paths`` + A JSON object containing members: + + ``source`` + A string specifying the path to the target's source directory, + represented with forward slashes. If the directory is inside the + top-level source directory then the path is specified relative to + that directory (with ``.`` for the top-level source directory itself). + Otherwise the path is absolute. + + ``build`` + A string specifying the path to the target's build directory, + represented with forward slashes. If the directory is inside the + top-level build directory then the path is specified relative to + that directory (with ``.`` for the top-level build directory itself). + Otherwise the path is absolute. + +``nameOnDisk`` + Optional member that is present for executable and library targets + that are linked or archived into a single primary artifact. + The value is a string specifying the file name of that artifact on disk. + +``artifacts`` + Optional member that is present for executable and library targets + that produce artifacts on disk meant for consumption by dependents. + The value is a JSON array of entries corresponding to the artifacts. + Each entry is a JSON object containing one member: + + ``path`` + A string specifying the path to the file on disk, represented with + forward slashes. If the file is inside the top-level build directory + then the path is specified relative to that directory. + Otherwise the path is absolute. + +``isGeneratorProvided`` + Optional member that is present with boolean value ``true`` if the + target is provided by CMake's build system generator rather than by + a command in the source code. + +``install`` + Optional member that is present when the target has an :command:`install` + rule. The value is a JSON object with members: + + ``prefix`` + A JSON object specifying the installation prefix. It has one member: + + ``path`` + A string specifying the value of :variable:`CMAKE_INSTALL_PREFIX`. + + ``destinations`` + A JSON array of entries specifying an install destination path. + Each entry is a JSON object with members: + + ``path`` + A string specifying the install destination path. The path may + be absolute or relative to the install prefix. + + ``backtrace`` + Optional member that is present when a CMake language backtrace to + the :command:`install` command invocation that specified this + destination is available. The value is an unsigned integer 0-based + index into the ``backtraceGraph`` member's ``nodes`` array. + +``link`` + Optional member that is present for executables and shared library + targets that link into a runtime binary. The value is a JSON object + with members describing the link step: + + ``language`` + A string specifying the language (e.g. ``C``, ``CXX``, ``Fortran``) + of the toolchain is used to invoke the linker. + + ``commandFragments`` + Optional member that is present when fragments of the link command + line invocation are available. The value is a JSON array of entries + specifying ordered fragments. Each entry is a JSON object with members: + + ``fragment`` + A string specifying a fragment of the link command line invocation. + The value is encoded in the build system's native shell format. + + ``role`` + A string specifying the role of the fragment's content: + + * ``flags``: link flags. + * ``libraries``: link library file paths or flags. + * ``libraryPath``: library search path flags. + * ``frameworkPath``: macOS framework search path flags. + + ``lto`` + Optional member that is present with boolean value ``true`` + when link-time optimization (a.k.a. interprocedural optimization + or link-time code generation) is enabled. + + ``sysroot`` + Optional member that is present when the :variable:`CMAKE_SYSROOT_LINK` + or :variable:`CMAKE_SYSROOT` variable is defined. The value is a + JSON object with one member: + + ``path`` + A string specifying the absolute path to the sysroot, represented + with forward slashes. + +``archive`` + Optional member that is present for static library targets. The value + is a JSON object with members describing the archive step: + + ``commandFragments`` + Optional member that is present when fragments of the archiver command + line invocation are available. The value is a JSON array of entries + specifying the fragments. Each entry is a JSON object with members: + + ``fragment`` + A string specifying a fragment of the archiver command line invocation. + The value is encoded in the build system's native shell format. + + ``role`` + A string specifying the role of the fragment's content: + + * ``flags``: archiver flags. + + ``lto`` + Optional member that is present with boolean value ``true`` + when link-time optimization (a.k.a. interprocedural optimization + or link-time code generation) is enabled. + +``dependencies`` + Optional member that is present when the target depends on other targets. + The value is a JSON array of entries corresponding to the dependencies. + Each entry is a JSON object with members: + + ``id`` + A string uniquely identifying the target on which this target depends. + This matches the main ``id`` member of the other target. + + ``backtrace`` + Optional member that is present when a CMake language backtrace to + the :command:`add_dependencies`, :command:`target_link_libraries`, + or other command invocation that created this dependency is + available. The value is an unsigned integer 0-based index into + the ``backtraceGraph`` member's ``nodes`` array. + +``sources`` + A JSON array of entries corresponding to the target's source files. + Each entry is a JSON object with members: + + ``path`` + A string specifying the path to the source file on disk, represented + with forward slashes. If the file is inside the top-level source + directory then the path is specified relative to that directory. + Otherwise the path is absolute. + + ``compileGroupIndex`` + Optional member that is present when the source is compiled. + The value is an unsigned integer 0-based index into the + ``compileGroups`` array. + + ``sourceGroupIndex`` + Optional member that is present when the source is part of a source + group either via the :command:`source_group` command or by default. + The value is an unsigned integer 0-based index into the + ``sourceGroups`` array. + + ``isGenerated`` + Optional member that is present with boolean value ``true`` if + the source is :prop_sf:`GENERATED`. + + ``backtrace`` + Optional member that is present when a CMake language backtrace to + the :command:`target_sources`, :command:`add_executable`, + :command:`add_library`, :command:`add_custom_target`, or other + command invocation that added this source to the target is + available. The value is an unsigned integer 0-based index into + the ``backtraceGraph`` member's ``nodes`` array. + +``sourceGroups`` + Optional member that is present when sources are grouped together by + the :command:`source_group` command or by default. The value is a + JSON array of entries corresponding to the groups. Each entry is + a JSON object with members: + + ``name`` + A string specifying the name of the source group. + + ``sourceIndexes`` + A JSON array listing the sources belonging to the group. + Each entry is an unsigned integer 0-based index into the + main ``sources`` array for the target. + +``compileGroups`` + Optional member that is present when the target has sources that compile. + The value is a JSON array of entries corresponding to groups of sources + that all compile with the same settings. Each entry is a JSON object + with members: + + ``sourceIndexes`` + A JSON array listing the sources belonging to the group. + Each entry is an unsigned integer 0-based index into the + main ``sources`` array for the target. + + ``language`` + A string specifying the language (e.g. ``C``, ``CXX``, ``Fortran``) + of the toolchain is used to compile the source file. + + ``compileCommandFragments`` + Optional member that is present when fragments of the compiler command + line invocation are available. The value is a JSON array of entries + specifying ordered fragments. Each entry is a JSON object with + one member: + + ``fragment`` + A string specifying a fragment of the compile command line invocation. + The value is encoded in the build system's native shell format. + + ``includes`` + Optional member that is present when there are include directories. + The value is a JSON array with an entry for each directory. Each + entry is a JSON object with members: + + ``path`` + A string specifying the path to the include directory, + represented with forward slashes. + + ``isSystem`` + Optional member that is present with boolean value ``true`` if + the include directory is marked as a system include directory. + + ``backtrace`` + Optional member that is present when a CMake language backtrace to + the :command:`target_include_directories` or other command invocation + that added this include directory is available. The value is + an unsigned integer 0-based index into the ``backtraceGraph`` + member's ``nodes`` array. + + ``defines`` + Optional member that is present when there are preprocessor definitions. + The value is a JSON array with an entry for each definition. Each + entry is a JSON object with members: + + ``define`` + A string specifying the preprocessor definition in the format + ``<name>[=<value>]``, e.g. ``DEF`` or ``DEF=1``. + + ``backtrace`` + Optional member that is present when a CMake language backtrace to + the :command:`target_compile_definitions` or other command invocation + that added this preprocessor definition is available. The value is + an unsigned integer 0-based index into the ``backtraceGraph`` + member's ``nodes`` array. + + ``sysroot`` + Optional member that is present when the + :variable:`CMAKE_SYSROOT_COMPILE` or :variable:`CMAKE_SYSROOT` + variable is defined. The value is a JSON object with one member: + + ``path`` + A string specifying the absolute path to the sysroot, represented + with forward slashes. + +``backtraceGraph`` + A JSON object describing the graph of backtraces whose nodes are + referenced from ``backtrace`` members elsewhere. The members are: + + ``nodes`` + A JSON array listing nodes in the backtrace graph. Each entry + is a JSON object with members: + + ``file`` + An unsigned integer 0-based index into the backtrace ``files`` array. + + ``line`` + An optional member present when the node represents a line within + the file. The value is an unsigned integer 1-based line number. + + ``command`` + An optional member present when the node represents a command + invocation within the file. The value is an unsigned integer + 0-based index into the backtrace ``commands`` array. + + ``parent`` + An optional member present when the node is not the bottom of + the call stack. The value is an unsigned integer 0-based index + of another entry in the backtrace ``nodes`` array. + + ``commands`` + A JSON array listing command names referenced by backtrace nodes. + Each entry is a string specifying a command name. + + ``files`` + A JSON array listing CMake language files referenced by backtrace nodes. + Each entry is a string specifying the path to a file, represented + with forward slashes. If the file is inside the top-level source + directory then the path is specified relative to that directory. + Otherwise the path is absolute. + +Object Kind "cache" +------------------- + +The ``cache`` object kind lists cache entries. These are the +:ref:`CMake Language Variables` stored in the persistent cache +(``CMakeCache.txt``) for the build tree. + +There is only one ``cache`` object major version, version 2. +Version 1 does not exist to avoid confusion with that from +:manual:`cmake-server(7)` mode. + +"cache" version 2 +^^^^^^^^^^^^^^^^^ + +``cache`` object version 2 is a JSON object: + +.. code-block:: json + + { + "kind": "cache", + "version": { "major": 2, "minor": 0 }, + "entries": [ + { + "name": "BUILD_SHARED_LIBS", + "value": "ON", + "type": "BOOL", + "properties": [ + { + "name": "HELPSTRING", + "value": "Build shared libraries" + } + ] + }, + { + "name": "CMAKE_GENERATOR", + "value": "Unix Makefiles", + "type": "INTERNAL", + "properties": [ + { + "name": "HELPSTRING", + "value": "Name of generator." + } + ] + } + ] + } + +The members specific to ``cache`` objects are: + +``entries`` + A JSON array whose entries are each a JSON object specifying a + cache entry. The members of each entry are: + + ``name`` + A string specifying the name of the entry. + + ``value`` + A string specifying the value of the entry. + + ``type`` + A string specifying the type of the entry used by + :manual:`cmake-gui(1)` to choose a widget for editing. + + ``properties`` + A JSON array of entries specifying associated + :ref:`cache entry properties <Cache Entry Properties>`. + Each entry is a JSON object containing members: + + ``name`` + A string specifying the name of the cache entry property. + + ``value`` + A string specifying the value of the cache entry property. + +Object Kind "cmakeFiles" +------------------------ + +The ``cmakeFiles`` object kind lists files used by CMake while +configuring and generating the build system. These include the +``CMakeLists.txt`` files as well as included ``.cmake`` files. + +There is only one ``cmakeFiles`` object major version, version 1. + +"cmakeFiles" version 1 +^^^^^^^^^^^^^^^^^^^^^^ + +``cmakeFiles`` object version 1 is a JSON object: + +.. code-block:: json + + { + "kind": "cmakeFiles", + "version": { "major": 1, "minor": 0 }, + "paths": { + "build": "/path/to/top-level-build-dir", + "source": "/path/to/top-level-source-dir" + }, + "inputs": [ + { + "path": "CMakeLists.txt" + }, + { + "isGenerated": true, + "path": "/path/to/top-level-build-dir/.../CMakeSystem.cmake" + }, + { + "isExternal": true, + "path": "/path/to/external/third-party/module.cmake" + }, + { + "isCMake": true, + "isExternal": true, + "path": "/path/to/cmake/Modules/CMakeGenericSystem.cmake" + } + ] + } + +The members specific to ``cmakeFiles`` objects are: + +``paths`` + A JSON object containing members: + + ``source`` + A string specifying the absolute path to the top-level source directory, + represented with forward slashes. + + ``build`` + A string specifying the absolute path to the top-level build directory, + represented with forward slashes. + +``inputs`` + A JSON array whose entries are each a JSON object specifying an input + file used by CMake when configuring and generating the build system. + The members of each entry are: + + ``path`` + A string specifying the path to an input file to CMake, represented + with forward slashes. If the file is inside the top-level source + directory then the path is specified relative to that directory. + Otherwise the path is absolute. + + ``isGenerated`` + Optional member that is present with boolean value ``true`` + if the path specifies a file that is under the top-level + build directory and the build is out-of-source. + This member is not available on in-source builds. + + ``isExternal`` + Optional member that is present with boolean value ``true`` + if the path specifies a file that is not under the top-level + source or build directories. + + ``isCMake`` + Optional member that is present with boolean value ``true`` + if the path specifies a file in the CMake installation. diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index bddb17477..75f4bd48a 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -20,54 +20,74 @@ commands to populate those properties, such as :command:`target_link_libraries`, :command:`target_include_directories`, :command:`target_compile_definitions` and others. -This means that they enable conditional linking, conditional -definitions used when compiling, and conditional include directories and -more. The conditions may be based on the build configuration, target -properties, platform information or any other queryable information. +They enable conditional linking, conditional definitions used when compiling, +conditional include directories, and more. The conditions may be based on +the build configuration, target properties, platform information or any other +queryable information. -Logical Expressions -=================== +Generator expressions have the form ``$<...>``. To avoid confusion, this page +deviates from most of the CMake documentation in that it omits angular brackets +``<...>`` around placeholders like ``condition``, ``string``, ``target``, +among others. -Logical expressions are used to create conditional output. The basic -expressions are the ``0`` and ``1`` expressions. Because other logical -expressions evaluate to either ``0`` or ``1``, they can be composed to -create conditional output:: +Generator expressions can be nested, as shown in most of the examples below. - $<$<CONFIG:Debug>:DEBUG_MODE> +.. _`Boolean Generator Expressions`: -expands to ``DEBUG_MODE`` when the ``Debug`` configuration is used, and -otherwise expands to nothing. - -Available logical expressions are: - -``$<BOOL:...>`` - ``1`` if the ``...`` is true, else ``0`` -``$<AND:?[,?]...>`` - ``1`` if all ``?`` are ``1``, else ``0`` - - The ``?`` must always be either ``0`` or ``1`` in boolean expressions. - -``$<OR:?[,?]...>`` - ``0`` if all ``?`` are ``0``, else ``1`` -``$<NOT:?>`` - ``0`` if ``?`` is ``1``, else ``1`` -``$<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`` -``$<EQUAL:a,b>`` - ``1`` if ``a`` is EQUAL ``b`` in a numeric comparison, else ``0`` -``$<CONFIG:cfg>`` - ``1`` if config is ``cfg``, else ``0``. This is a case-insensitive comparison. - The mapping in :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` is also considered by - this expression when it is evaluated on a property on an :prop_tgt:`IMPORTED` - target. -``$<PLATFORM_ID:comp>`` - ``1`` if the CMake-id of the platform matches ``comp``, otherwise ``0``. -``$<C_COMPILER_ID:comp>`` - ``1`` if the CMake-id of the C compiler matches ``comp``, otherwise ``0``. -``$<CXX_COMPILER_ID:comp>`` - ``1`` if the CMake-id of the CXX compiler matches ``comp``, otherwise ``0``. +Boolean Generator Expressions +============================= + +Boolean expressions evaluate to either ``0`` or ``1``. +They are typically used to construct the condition in a :ref:`conditional +generator expression<Conditional Generator Expressions>`. + +Available boolean expressions are: + +Logical Operators +----------------- + +``$<BOOL:string>`` + Converts ``string`` to ``0`` or ``1``. Evaluates to ``0`` if any of the + following is true: + + * ``string`` is empty, + * ``string`` is a case-insensitive equal of + ``0``, ``FALSE``, ``OFF``, ``N``, ``NO``, ``IGNORE``, or ``NOTFOUND``, or + * ``string`` ends in the suffix ``-NOTFOUND`` (case-sensitive). + + Otherwise evaluates to ``1``. + +``$<AND:conditions>`` + where ``conditions`` is a comma-separated list of boolean expressions. + Evaluates to ``1`` if all conditions are ``1``. + Otherwise evaluates to ``0``. + +``$<OR:conditions>`` + where ``conditions`` is a comma-separated list of boolean expressions. + Evaluates to ``1`` if at least one of the conditions is ``1``. + Otherwise evaluates to ``0``. + +``$<NOT:condition>`` + ``0`` if ``condition`` is ``1``, else ``1``. + +String Comparisons +------------------ + +``$<STREQUAL:string1,string2>`` + ``1`` if ``string1`` and ``string2`` are equal, else ``0``. + The comparison is case-sensitive. For a case-insensitive comparison, + combine with a :ref:`string transforming generator expression + <String Transforming Generator Expressions>`, + + .. code-block:: cmake + + $<STREQUAL:$<UPPER_CASE:${foo}>,"BAR"> # "1" if ${foo} is any of "BAR", "Bar", "bar", ... + +``$<EQUAL:value1,value2>`` + ``1`` if ``value1`` and ``value2`` are numerically equal, else ``0``. +``$<IN_LIST:string,list>`` + ``1`` if ``string`` is member of the semicolon-separated ``list``, else ``0``. + Uses case-sensitive comparisons. ``$<VERSION_LESS:v1,v2>`` ``1`` if ``v1`` is a version less than ``v2``, else ``0``. ``$<VERSION_GREATER:v1,v2>`` @@ -78,76 +98,185 @@ Available logical expressions are: ``1`` if ``v1`` is a version less than or equal to ``v2``, else ``0``. ``$<VERSION_GREATER_EQUAL:v1,v2>`` ``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``. -``$<CXX_COMPILER_VERSION:ver>`` - ``1`` if the version of the CXX compiler matches ``ver``, otherwise ``0``. -``$<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 + + +Variable Queries +---------------- + +``$<TARGET_EXISTS:target>`` + ``1`` if ``target`` exists, else ``0``. +``$<CONFIG:cfg>`` + ``1`` if config is ``cfg``, else ``0``. This is a case-insensitive comparison. + The mapping in :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` is also considered by + this expression when it is evaluated on a property on an :prop_tgt:`IMPORTED` + target. +``$<PLATFORM_ID:platform_ids>`` + where ``platform_ids`` is a comma-separated list. + ``1`` if the CMake's platform id matches any one of the entries in + ``platform_ids``, otherwise ``0``. + See also the :variable:`CMAKE_SYSTEM_NAME` variable. +``$<C_COMPILER_ID:compiler_ids>`` + where ``compiler_ids`` is a comma-separated list. + ``1`` if the CMake's compiler id of the C compiler matches any one + of the entries in ``compiler_ids``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<CXX_COMPILER_ID:compiler_ids>`` + where ``compiler_ids`` is a comma-separated list. + ``1`` if the CMake's compiler id of the CXX compiler matches any one + of the entries in ``compiler_ids``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<CUDA_COMPILER_ID:compiler_ids>`` + where ``compiler_ids`` is a comma-separated list. + ``1`` if the CMake's compiler id of the CUDA compiler matches any one + of the entries in ``compiler_ids``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<OBJC_COMPILER_ID:compiler_ids>`` + where ``compiler_ids`` is a comma-separated list. + ``1`` if the CMake's compiler id of the Objective-C compiler matches any one + of the entries in ``compiler_ids``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<OBJCXX_COMPILER_ID:compiler_ids>`` + where ``compiler_ids`` is a comma-separated list. + ``1`` if the CMake's compiler id of the Objective-C++ compiler matches any one + of the entries in ``compiler_ids``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<Fortran_COMPILER_ID:compiler_ids>`` + where ``compiler_ids`` is a comma-separated list. + ``1`` if the CMake's compiler id of the Fortran compiler matches any one + of the entries in ``compiler_ids``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<C_COMPILER_VERSION:version>`` + ``1`` if the version of the C compiler matches ``version``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<CXX_COMPILER_VERSION:version>`` + ``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<CUDA_COMPILER_VERSION:version>`` + ``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<OBJC_COMPILER_VERSION:version>`` + ``1`` if the version of the OBJC compiler matches ``version``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<OBJCXX_COMPILER_VERSION:version>`` + ``1`` if the version of the OBJCXX compiler matches ``version``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<Fortran_COMPILER_VERSION:version>`` + ``1`` if the version of the Fortran compiler matches ``version``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<TARGET_POLICY:policy>`` + ``1`` if the ``policy`` was NEW when the 'head' target was created, + else ``0``. If the ``policy`` was not set, the warning message for the policy will be emitted. This generator expression only works for a subset of policies. -``$<COMPILE_FEATURES:feature[,feature]...>`` - ``1`` if all of the ``feature`` features are available for the 'head' +``$<COMPILE_FEATURES:features>`` + where ``features`` is a comma-spearated list. + Evaluates to ``1`` if all of the ``features`` are available for the 'head' target, and ``0`` otherwise. If this expression is used while evaluating the link implementation of a target and if any dependency transitively increases the required :prop_tgt:`C_STANDARD` or :prop_tgt:`CXX_STANDARD` for the 'head' target, an error is reported. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. -``$<COMPILE_LANGUAGE:lang>`` - ``1`` when the language used for compilation unit matches ``lang``, - otherwise ``0``. This expression used to specify compile options for - source files of a particular language in a target. For example, to specify - the use of the ``-fno-exceptions`` compile option (compiler id checks - elided): + +.. _`Boolean COMPILE_LANGUAGE Generator Expression`: + +``$<COMPILE_LANG_AND_ID:language,compiler_ids>`` + ``1`` when the language used for compilation unit matches ``language`` and + the CMake's compiler id of the language compiler matches any one of the + entries in ``compiler_ids``, otherwise ``0``. This expression is a short form + for the combination of ``$<COMPILE_LANGUAGE:language>`` and + ``$<LANG_COMPILER_ID:compiler_ids>``. This expression may be used to specify + compile options, compile definitions, and include directories for source files of a + particular language and compiler combination in a target. For example: .. code-block:: cmake - add_executable(myapp main.cpp foo.c bar.cpp) - target_compile_options(myapp - PRIVATE $<$<COMPILE_LANGUAGE:CXX>:-fno-exceptions> + add_executable(myapp main.cpp foo.c bar.cpp zot.cu) + target_compile_definitions(myapp + PRIVATE $<$<COMPILE_LANG_AND_ID:CXX,AppleClang,Clang>:COMPILING_CXX_WITH_CLANG> + $<$<COMPILE_LANG_AND_ID:CXX,Intel>:COMPILING_CXX_WITH_INTEL> + $<$<COMPILE_LANG_AND_ID:C,Clang>:COMPILING_C_WITH_CLANG> ) - This generator expression has limited use because it is not possible to - use it with the Visual Studio generators. Portable buildsystems would - not use this expression, and would create separate libraries for each - source file language instead: + This specifies the use of different compile definitions based on both + the compiler id and compilation language. This example will have a + ``COMPILING_CXX_WITH_CLANG`` compile definition when Clang is the CXX + compiler, and ``COMPILING_CXX_WITH_INTEL`` when Intel is the CXX compiler. + Likewise when the C compiler is Clang it will only see the ``COMPILING_C_WITH_CLANG`` + definition. + + Without the ``COMPILE_LANG_AND_ID`` generator expression the same logic + would be expressed as: .. code-block:: cmake - add_library(myapp_c foo.c) - add_library(myapp_cxx bar.cpp) - target_compile_options(myapp_cxx PUBLIC -fno-exceptions) - add_executable(myapp main.cpp) - target_link_libraries(myapp myapp_c myapp_cxx) + target_compile_definitions(myapp + PRIVATE $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:AppleClang,Clang>>:COMPILING_CXX_WITH_CLANG> + $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:Intel>>:COMPILING_CXX_WITH_INTEL> + $<$<AND:$<COMPILE_LANGUAGE:C>,$<C_COMPILER_ID:Clang>>:COMPILING_C_WITH_CLANG> + ) - The ``Makefile`` and ``Ninja`` based generators can also use this - expression to specify compile-language specific compile definitions - and include directories: +``$<COMPILE_LANGUAGE:languages>`` + ``1`` when the language used for compilation unit matches any of the entries + in ``languages``, otherwise ``0``. This expression may be used to specify + compile options, compile definitions, and include directories for source files of a + particular language in a target. For example: .. code-block:: cmake - add_executable(myapp main.cpp foo.c bar.cpp) + add_executable(myapp main.cpp foo.c bar.cpp zot.cu) + target_compile_options(myapp + PRIVATE $<$<COMPILE_LANGUAGE:CXX>:-fno-exceptions> + ) target_compile_definitions(myapp PRIVATE $<$<COMPILE_LANGUAGE:CXX>:COMPILING_CXX> + $<$<COMPILE_LANGUAGE:CUDA>:COMPILING_CUDA> ) target_include_directories(myapp - PRIVATE $<$<COMPILE_LANGUAGE:CXX>:/opt/foo/cxx_headers> + PRIVATE $<$<COMPILE_LANGUAGE:CXX,CUDA>:/opt/foo/headers> ) -Informational Expressions -========================= + This specifies the use of the ``-fno-exceptions`` compile option, + ``COMPILING_CXX`` compile definition, and ``cxx_headers`` include + directory for C++ only (compiler id checks elided). It also specifies + a ``COMPILING_CUDA`` compile definition for CUDA. + + Note that with :ref:`Visual Studio Generators` and :generator:`Xcode` there + is no way to represent target-wide compile definitions or include directories + separately for ``C`` and ``CXX`` languages. + Also, with :ref:`Visual Studio Generators` there is no way to represent + target-wide flags separately for ``C`` and ``CXX`` languages. Under these + generators, expressions for both C and C++ sources will be evaluated + using ``CXX`` if there are any C++ sources and otherwise using ``C``. + A workaround is to create separate libraries for each source file language + instead: -These expressions expand to some information. The information may be used -directly, eg:: + .. code-block:: cmake + + add_library(myapp_c foo.c) + add_library(myapp_cxx bar.cpp) + target_compile_options(myapp_cxx PUBLIC -fno-exceptions) + add_executable(myapp main.cpp) + target_link_libraries(myapp myapp_c myapp_cxx) + +String-Valued Generator Expressions +=================================== + +These expressions expand to some string. +For example, + +.. code-block:: cmake include_directories(/usr/include/$<CXX_COMPILER_ID>/) expands to ``/usr/include/GNU/`` or ``/usr/include/Clang/`` etc, depending on -the Id of the compiler. +the compiler identifier. + +String-valued expressions may also be combined with other expressions. +Here an example for a string-valued expression within a boolean expressions +within a conditional expression: -These expressions may also may be combined with logical expressions:: +.. code-block:: cmake $<$<VERSION_LESS:$<CXX_COMPILER_VERSION>,4.2.0>:OLD_COMPILER> @@ -155,20 +284,147 @@ expands to ``OLD_COMPILER`` if the :variable:`CMAKE_CXX_COMPILER_VERSION <CMAKE_<LANG>_COMPILER_VERSION>` is less than 4.2.0. -Available informational expressions are: +And here two nested string-valued expressions: + +.. code-block:: cmake + + -I$<JOIN:$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>, -I> + +generates a string of the entries in the :prop_tgt:`INCLUDE_DIRECTORIES` target +property with each entry preceded by ``-I``. + +Expanding on the previous example, if one first wants to check if the +``INCLUDE_DIRECTORIES`` property is non-empty, then it is advisable to +introduce a helper variable to keep the code readable: + +.. code-block:: cmake + + set(prop "$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>") # helper variable + $<$<BOOL:${prop}>:-I$<JOIN:${prop}, -I>> + +The following string-valued generator expressions are available: + +Escaped Characters +------------------ + +String literals to escape the special meaning a character would otherwise have: + +``$<ANGLE-R>`` + A literal ``>``. Used for example to compare strings that contain a ``>``. +``$<COMMA>`` + A literal ``,``. Used for example to compare strings which contain a ``,``. +``$<SEMICOLON>`` + A literal ``;``. Used to prevent list expansion on an argument with ``;``. + +.. _`Conditional Generator Expressions`: + +Conditional Expressions +----------------------- + +Conditional generator expressions depend on a boolean condition +that must be ``0`` or ``1``. + +``$<condition:true_string>`` + Evaluates to ``true_string`` if ``condition`` is ``1``. + Otherwise evaluates to the empty string. + +``$<IF:condition,true_string,false_string>`` + Evaluates to ``true_string`` if ``condition`` is ``1``. + Otherwise evaluates to ``false_string``. + +Typically, the ``condition`` is a :ref:`boolean generator expression +<Boolean Generator Expressions>`. For instance, + +.. code-block:: cmake + + $<$<CONFIG:Debug>:DEBUG_MODE> + +expands to ``DEBUG_MODE`` when the ``Debug`` configuration is used, and +otherwise expands to the empty string. + +.. _`String Transforming Generator Expressions`: + +String Transformations +---------------------- + +``$<JOIN:list,string>`` + Joins the list with the content of ``string``. +``$<REMOVE_DUPLICATES:list>`` + Removes duplicated items in the given ``list``. +``$<FILTER:list,INCLUDE|EXCLUDE,regex>`` + Includes or removes items from ``list`` that match the regular expression ``regex``. +``$<LOWER_CASE:string>`` + Content of ``string`` converted to lower case. +``$<UPPER_CASE:string>`` + Content of ``string`` converted to upper case. + +``$<GENEX_EVAL:expr>`` + Content of ``expr`` evaluated as a generator expression in the current + context. This enables consumption of generator expressions whose + evaluation results itself in generator expressions. +``$<TARGET_GENEX_EVAL:tgt,expr>`` + Content of ``expr`` evaluated as a generator expression in the context of + ``tgt`` target. This enables consumption of custom target properties that + themselves contain generator expressions. + + Having the capability to evaluate generator expressions is very useful when + you want to manage custom properties supporting generator expressions. + For example: + + .. code-block:: cmake + + add_library(foo ...) + + set_property(TARGET foo PROPERTY + CUSTOM_KEYS $<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS> + ) + + add_custom_target(printFooKeys + COMMAND ${CMAKE_COMMAND} -E echo $<TARGET_PROPERTY:foo,CUSTOM_KEYS> + ) + + This naive implementation of the ``printFooKeys`` custom command is wrong + because ``CUSTOM_KEYS`` target property is not evaluated and the content + is passed as is (i.e. ``$<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS>``). + + To have the expected result (i.e. ``FOO_EXTRA_THINGS`` if config is + ``Debug``), it is required to evaluate the output of + ``$<TARGET_PROPERTY:foo,CUSTOM_KEYS>``: + + .. code-block:: cmake + + add_custom_target(printFooKeys + COMMAND ${CMAKE_COMMAND} -E + echo $<TARGET_GENEX_EVAL:foo,$<TARGET_PROPERTY:foo,CUSTOM_KEYS>> + ) + +Variable Queries +---------------- -``$<CONFIGURATION>`` - Configuration name. Deprecated. Use ``CONFIG`` instead. ``$<CONFIG>`` - Configuration name + Configuration name. +``$<CONFIGURATION>`` + Configuration name. Deprecated since CMake 3.0. Use ``CONFIG`` instead. ``$<PLATFORM_ID>`` - The CMake-id of the platform. + The current system's CMake platform id. See also the :variable:`CMAKE_SYSTEM_NAME` variable. ``$<C_COMPILER_ID>`` - The CMake-id of the C compiler used. + The CMake's compiler id of the C compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. ``$<CXX_COMPILER_ID>`` - The CMake-id of the CXX compiler used. + The CMake's compiler id of the CXX compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<CUDA_COMPILER_ID>`` + The CMake's compiler id of the CUDA compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<OBJC_COMPILER_ID>`` + The CMake's compiler id of the OBJC compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<OBJCXX_COMPILER_ID>`` + The CMake's compiler id of the OBJCXX compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<Fortran_COMPILER_ID>`` + The CMake's compiler id of the Fortran compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. ``$<C_COMPILER_VERSION>`` The version of the C compiler used. @@ -176,14 +432,111 @@ Available informational expressions are: ``$<CXX_COMPILER_VERSION>`` The version of the CXX compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<CUDA_COMPILER_VERSION>`` + The version of the CUDA compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<OBJC_COMPILER_VERSION>`` + The version of the OBJC compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<OBJCXX_COMPILER_VERSION>`` + The version of the OBJCXX compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<Fortran_COMPILER_VERSION>`` + The version of the Fortran compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<COMPILE_LANGUAGE>`` + The compile language of source files when evaluating compile options. + See :ref:`the related boolean expression + <Boolean COMPILE_LANGUAGE Generator Expression>` + ``$<COMPILE_LANGUAGE:language>`` + for notes about the portability of this generator expression. + +Target-Dependent Queries +------------------------ + +``$<TARGET_NAME_IF_EXISTS:tgt>`` + Expands to the ``tgt`` if the given target exists, an empty string + otherwise. ``$<TARGET_FILE:tgt>`` - Full path to main file (.exe, .so.1.2, .a) where ``tgt`` is the name of a target. + Full path to main file (.exe, .so.1.2, .a) where ``tgt`` is the name of a + target. +``$<TARGET_FILE_BASE_NAME:tgt>`` + Base name of main file where ``tgt`` is the name of a target. + + The base name corresponds to the target file name (see + ``$<TARGET_FILE_NAME:tgt>``) without prefix and suffix. For example, if + target file name is ``libbase.so``, the base name is ``base``. + + See also the :prop_tgt:`OUTPUT_NAME`, :prop_tgt:`ARCHIVE_OUTPUT_NAME`, + :prop_tgt:`LIBRARY_OUTPUT_NAME` and :prop_tgt:`RUNTIME_OUTPUT_NAME` + target properties and their configuration specific variants + :prop_tgt:`OUTPUT_NAME_<CONFIG>`, :prop_tgt:`ARCHIVE_OUTPUT_NAME_<CONFIG>`, + :prop_tgt:`LIBRARY_OUTPUT_NAME_<CONFIG>` and + :prop_tgt:`RUNTIME_OUTPUT_NAME_<CONFIG>`. + + The :prop_tgt:`<CONFIG>_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target + properties can also be considered. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. +``$<TARGET_FILE_PREFIX:tgt>`` + Prefix of main file where ``tgt`` is the name of a target. + + See also the :prop_tgt:`PREFIX` target property. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. +``$<TARGET_FILE_SUFFIX:tgt>`` + Suffix of main file where ``tgt`` is the name of a target. + + The suffix corresponds to the file extension (such as ".so" or ".exe"). + + See also the :prop_tgt:`SUFFIX` target property. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. ``$<TARGET_FILE_NAME:tgt>`` Name of main file (.exe, .so.1.2, .a). ``$<TARGET_FILE_DIR:tgt>`` Directory of main file (.exe, .so.1.2, .a). ``$<TARGET_LINKER_FILE:tgt>`` File used to link (.a, .lib, .so) where ``tgt`` is the name of a target. +``$<TARGET_LINKER_FILE_BASE_NAME:tgt>`` + Base name of file used to link where ``tgt`` is the name of a target. + + The base name corresponds to the target linker file name (see + ``$<TARGET_LINKER_FILE_NAME:tgt>``) without prefix and suffix. For example, + if target file name is ``libbase.a``, the base name is ``base``. + + See also the :prop_tgt:`OUTPUT_NAME`, :prop_tgt:`ARCHIVE_OUTPUT_NAME`, + and :prop_tgt:`LIBRARY_OUTPUT_NAME` target properties and their configuration + specific variants :prop_tgt:`OUTPUT_NAME_<CONFIG>`, + :prop_tgt:`ARCHIVE_OUTPUT_NAME_<CONFIG>` and + :prop_tgt:`LIBRARY_OUTPUT_NAME_<CONFIG>`. + + The :prop_tgt:`<CONFIG>_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target + properties can also be considered. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. +``$<TARGET_LINKER_FILE_PREFIX:tgt>`` + Prefix of file used to link where ``tgt`` is the name of a target. + + See also the :prop_tgt:`PREFIX` and :prop_tgt:`IMPORT_PREFIX` target + properties. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. +``$<TARGET_LINKER_FILE_SUFFIX:tgt>`` + Suffix of file used to link where ``tgt`` is the name of a target. + + The suffix corresponds to the file extension (such as ".so" or ".lib"). + + See also the :prop_tgt:`SUFFIX` and :prop_tgt:`IMPORT_SUFFIX` target + properties. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. ``$<TARGET_LINKER_FILE_NAME:tgt>`` Name of file used to link (.a, .lib, .so). ``$<TARGET_LINKER_FILE_DIR:tgt>`` @@ -201,6 +554,22 @@ Available informational expressions are: See also the :prop_tgt:`PDB_NAME` and :prop_tgt:`PDB_OUTPUT_DIRECTORY` target properties and their configuration specific variants :prop_tgt:`PDB_NAME_<CONFIG>` and :prop_tgt:`PDB_OUTPUT_DIRECTORY_<CONFIG>`. +``$<TARGET_PDB_FILE_BASE_NAME:tgt>`` + Base name of the linker generated program database file (.pdb) + where ``tgt`` is the name of a target. + + The base name corresponds to the target PDB file name (see + ``$<TARGET_PDB_FILE_NAME:tgt>``) without prefix and suffix. For example, + if target file name is ``base.pdb``, the base name is ``base``. + + See also the :prop_tgt:`PDB_NAME` target property and its configuration + specific variant :prop_tgt:`PDB_NAME_<CONFIG>`. + + The :prop_tgt:`<CONFIG>_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target + properties can also be considered. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. ``$<TARGET_PDB_FILE_NAME:tgt>`` Name of the linker generated program database file (.pdb). ``$<TARGET_PDB_FILE_DIR:tgt>`` @@ -221,49 +590,17 @@ Available informational expressions are: expression is evaluated on. ``$<TARGET_PROPERTY:prop>`` Value of the property ``prop`` on the target on which the generator - expression is evaluated. + expression is evaluated. Note that for generator expressions in + :ref:`Target Usage Requirements` this is the value of the property + on the consuming target rather than the target specifying the + requirement. ``$<INSTALL_PREFIX>`` Content of the install prefix when the target is exported via :command:`install(EXPORT)` and empty otherwise. -``$<COMPILE_LANGUAGE>`` - The compile language of source files when evaluating compile options. See - the unary version for notes about portability of this generator - expression. -Output Expressions -================== +Output-Related Expressions +-------------------------- -These expressions generate output, in some cases depending on an input. These -expressions may be combined with other expressions for information or logical -comparison:: - - -I$<JOIN:$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>, -I> - -generates a string of the entries in the :prop_tgt:`INCLUDE_DIRECTORIES` target -property with each entry preceded by ``-I``. Note that a more-complete use -in this situation would require first checking if the INCLUDE_DIRECTORIES -property is non-empty:: - - $<$<BOOL:${prop}>:-I$<JOIN:${prop}, -I>> - -where ``${prop}`` refers to a helper variable:: - - set(prop "$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>") - -Available output expressions are: - -``$<0:...>`` - Empty string (ignores ``...``) -``$<1:...>`` - Content of ``...`` -``$<JOIN:list,...>`` - Joins the list with the content of ``...`` -``$<ANGLE-R>`` - A literal ``>``. Used to compare strings which contain a ``>`` for example. -``$<COMMA>`` - A literal ``,``. Used to compare strings which contain a ``,`` for example. -``$<SEMICOLON>`` - A literal ``;``. Used to prevent list expansion on an argument with ``;``. ``$<TARGET_NAME:...>`` Marks ``...`` as being the name of a target. This is required if exporting targets to multiple dependent export sets. The ``...`` must be a literal @@ -282,16 +619,39 @@ Available output expressions are: Content of ``...`` when the property is exported using :command:`export`, or when the target is used by another target in the same buildsystem. Expands to the empty string otherwise. -``$<LOWER_CASE:...>`` - Content of ``...`` converted to lower case. -``$<UPPER_CASE:...>`` - Content of ``...`` converted to upper case. ``$<MAKE_C_IDENTIFIER:...>`` - Content of ``...`` converted to a C identifier. + Content of ``...`` converted to a C identifier. The conversion follows the + same behavior as :command:`string(MAKE_C_IDENTIFIER)`. ``$<TARGET_OBJECTS:objLib>`` - List of objects resulting from build of ``objLib``. ``objLib`` must be an - object of type ``OBJECT_LIBRARY``. + List of objects resulting from build of ``objLib``. ``$<SHELL_PATH:...>`` Content of ``...`` converted to shell path style. For example, slashes are converted to backslashes in Windows shells and drive letters are converted to posix paths in MSYS shells. The ``...`` must be an absolute path. + The ``...`` may be a :ref:`semicolon-separated list <CMake Language Lists>` + of paths, in which case each path is converted individually and a result + list is generated using the shell path separator (``:`` on POSIX and + ``;`` on Windows). Be sure to enclose the argument containing this genex + in double quotes in CMake source code so that ``;`` does not split arguments. + +Debugging +========= + +Since generator expressions are evaluated during generation of the buildsystem, +and not during processing of ``CMakeLists.txt`` files, it is not possible to +inspect their result with the :command:`message()` command. + +One possible way to generate debug messages is to add a custom target, + +.. code-block:: cmake + + add_custom_target(genexdebug COMMAND ${CMAKE_COMMAND} -E echo "$<...>") + +The shell command ``make genexdebug`` (invoked after execution of ``cmake``) +would then print the result of ``$<...>``. + +Another way is to write debug messages to a file: + +.. code-block:: cmake + + file(GENERATE OUTPUT filename CONTENT "$<...>") diff --git a/Help/manual/cmake-generators.7.rst b/Help/manual/cmake-generators.7.rst index a37c65b39..41f765220 100644 --- a/Help/manual/cmake-generators.7.rst +++ b/Help/manual/cmake-generators.7.rst @@ -27,6 +27,8 @@ when creating a new build tree. CMake Generators ================ +.. _`Command-Line Build Tool Generators`: + Command-Line Build Tool Generators ---------------------------------- @@ -58,6 +60,8 @@ Ninja Generator /generator/Ninja +.. _`IDE Build Tool Generators`: + IDE Build Tool Generators ------------------------- @@ -83,6 +87,7 @@ Visual Studio Generators /generator/Visual Studio 12 2013 /generator/Visual Studio 14 2015 /generator/Visual Studio 15 2017 + /generator/Visual Studio 16 2019 Other Generators ^^^^^^^^^^^^^^^^ @@ -108,6 +113,5 @@ The following extra generators are known to CMake. /generator/CodeBlocks /generator/CodeLite /generator/Eclipse CDT4 - /generator/KDevelop3 /generator/Kate /generator/Sublime Text 2 diff --git a/Help/manual/cmake-gui.1.rst b/Help/manual/cmake-gui.1.rst index 032b51fda..ff8311bbe 100644 --- a/Help/manual/cmake-gui.1.rst +++ b/Help/manual/cmake-gui.1.rst @@ -9,24 +9,33 @@ Synopsis .. parsed-literal:: cmake-gui [<options>] - cmake-gui [<options>] (<path-to-source> | <path-to-existing-build>) + cmake-gui [<options>] {<path-to-source> | <path-to-existing-build>} + cmake-gui [<options>] -S <path-to-source> -B <path-to-build> Description =========== -The "cmake-gui" executable is the CMake GUI. Project configuration +The **cmake-gui** executable is the CMake GUI. Project configuration settings may be specified interactively. Brief instructions are provided at the bottom of the window when the program is running. CMake is a cross-platform build system generator. Projects specify their build process with platform-independent CMake listfiles included -in each directory of a source tree with the name CMakeLists.txt. +in each directory of a source tree with the name ``CMakeLists.txt``. Users build a project by using CMake to generate a build system for a native tool on their platform. Options ======= +``-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. + .. include:: OPTIONS_HELP.txt See Also diff --git a/Help/manual/cmake-language.7.rst b/Help/manual/cmake-language.7.rst index 27b5d30b4..4ca8e3a26 100644 --- a/Help/manual/cmake-language.7.rst +++ b/Help/manual/cmake-language.7.rst @@ -183,18 +183,18 @@ same length: .. productionlist:: bracket_argument: `bracket_open` `bracket_content` `bracket_close` - bracket_open: '[' '='{len} '[' - bracket_content: <any text not containing a `bracket_close` - : of the same {len} as the `bracket_open`> - bracket_close: ']' '='{len} ']' + bracket_open: '[' '='* '[' + bracket_content: <any text not containing a `bracket_close` with + : the same number of '=' as the `bracket_open`> + bracket_close: ']' '='* ']' .. raw:: latex \end{small} -An opening bracket of length *len >= 0* is written ``[`` followed -by *len* ``=`` followed by ``[`` and the corresponding closing -bracket is written ``]`` followed by *len* ``=`` followed by ``]``. +An opening bracket is written ``[`` followed by zero or more ``=`` followed +by ``[``. The corresponding closing bracket is written ``]`` followed +by the same number of ``=`` followed by ``]``. Brackets do not nest. A unique length may always be chosen for the opening and closing brackets to contain closing brackets of other lengths. @@ -206,9 +206,10 @@ enclosed content, such as `Escape Sequences`_ or `Variable References`_, is performed. A bracket argument is always given to the command invocation as exactly one argument. -For example: +.. No code-block syntax highlighting in the following example + (long string literal not supported by our cmake.py) -.. code-block:: cmake +For example:: message([=[ This is the first line in a bracket argument with bracket length 1. @@ -253,16 +254,22 @@ closing quotes. Both `Escape Sequences`_ and `Variable References`_ are evaluated. A quoted argument is always given to the command invocation as exactly one argument. +.. No code-block syntax highlighting in the following example + (escape \" not supported by our cmake.py) + For example: -:: +.. code-block:: cmake - message("This is a quoted argument containing multiple lines. - This is always one argument even though it contains a ; character. - Both \\-escape sequences and ${variable} references are evaluated. - The text does not end on an escaped double-quote like \". - It does end in an unescaped double quote. - ") + message("This is a quoted argument containing multiple lines. + This is always one argument even though it contains a ; character. + Both \\-escape sequences and ${variable} references are evaluated. + The text does not end on an escaped double-quote like \". + It does end in an unescaped double quote. + ") + +.. No code-block syntax highlighting in the following example + (for conformity with the two above examples) The final ``\`` on any line ending in an odd number of backslashes is treated as a line continuation and ignored along with the @@ -270,11 +277,11 @@ immediately following newline character. For example: .. code-block:: cmake - message("\ - This is the first line of a quoted argument. \ - In fact it is the only line but since it is long \ - the source code uses line continuation.\ - ") + message("\ + This is the first line of a quoted argument. \ + In fact it is the only line but since it is long \ + the source code uses line continuation.\ + ") .. note:: CMake versions prior to 3.0 do not support continuation with ``\``. @@ -334,6 +341,8 @@ For example: beginning of an unquoted argument, and are treated as part of the content. For example, the unquoted arguments ``-Da="b c"``, ``-Da=$(v)``, and ``a" "b"c"d`` are each interpreted literally. + They may instead be written as quoted arguments ``"-Da=\"b c\""``, + ``"-Da=$(v)"``, and ``"a\" \"b\"c\"d"``, respectively. Make-style references are treated literally as part of the content and do not undergo variable expansion. They are treated as part @@ -380,7 +389,7 @@ historical considerations.) Variable References ------------------- -A *variable reference* has the form ``${variable_name}`` and is +A *variable reference* has the form ``${<variable>}`` and is evaluated inside a `Quoted Argument`_ or an `Unquoted Argument`_. A variable reference is replaced by the value of the variable, or by the empty string if the variable is not set. @@ -389,14 +398,24 @@ 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. +An *environment variable reference* has the form ``$ENV{<variable>}``. +See the `Environment Variables`_ section for more information. + +A *cache variable reference* has the form ``$CACHE{<variable>}``. +See :variable:`CACHE` for more information. + +The :command:`if` command has a special condition syntax that +allows for variable references in the short form ``<variable>`` +instead of ``${<variable>}``. +However, environment and cache variables always need to be +referenced as ``$ENV{<variable>}`` or ``$CACHE{<variable>}``. Comments -------- @@ -411,7 +430,7 @@ comments: a `Bracket Comment`_ and a `Line Comment`_. Bracket Comment ^^^^^^^^^^^^^^^ -A ``#`` immediately followed by a `Bracket Argument`_ forms a +A ``#`` immediately followed by a :token:`bracket_open` forms a *bracket comment* consisting of the entire bracket enclosure: .. raw:: latex @@ -442,7 +461,7 @@ For example: Line Comment ^^^^^^^^^^^^ -A ``#`` not immediately followed by a `Bracket Argument`_ forms a +A ``#`` not immediately followed by a :token:`bracket_open` forms a *line comment* that runs until the end of the line: .. raw:: latex @@ -450,7 +469,7 @@ A ``#`` not immediately followed by a `Bracket Argument`_ forms a \begin{small} .. productionlist:: - line_comment: '#' <any text not starting in a `bracket_argument` + line_comment: '#' <any text not starting in a `bracket_open` : and not containing a `newline`> .. raw:: latex @@ -514,7 +533,7 @@ Function Scope create commands that, when invoked, process the recorded commands in a new variable binding scope. A variable "set" or "unset" binds in this scope and is visible for the current function and - any nested calls, but not after the function returns. + any nested calls within it, but not after the function returns. Directory Scope Each of the `Directories`_ in a source tree has its own variable @@ -541,11 +560,41 @@ 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 +The :manual:`cmake-variables(7)` manual documents the many variables that are provided by CMake or have meaning to CMake when set by project code. +.. _`CMake Language Environment Variables`: + +Environment Variables +===================== + +Environment Variables are like ordinary `Variables`_, with the +following differences: + +Scope + Environment variables have global scope in a CMake process. + They are never cached. + +References + `Variable References`_ have the form ``$ENV{<variable>}``. + +Initialization + Initial values of the CMake environment variables are those of + the calling process. + Values can be changed using the :command:`set` and :command:`unset` + commands. + These commands only affect the running CMake process, + not the system environment at large. + Changed values are not written back to the calling process, + and they are not seen by subsequent build or test processes. + +The :manual:`cmake-env-variables(7)` manual documents environment +variables that have special meaning to CMake. + .. _`CMake Language Lists`: Lists diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index 4a03b7a80..c60dc4010 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -3,12 +3,14 @@ cmake-modules(7) **************** -.. only:: html +The modules listed here are part of the CMake distribution. +Projects may provide further modules; their location(s) +can be specified in the :variable:`CMAKE_MODULE_PATH` variable. - .. contents:: +Utility Modules +^^^^^^^^^^^^^^^ -All Modules -=========== +These modules are loaded using the :command:`include` command. .. toctree:: :maxdepth: 1 @@ -26,6 +28,7 @@ All Modules /module/CheckFortranCompilerFlag /module/CheckFortranFunctionExists /module/CheckFortranSourceCompiles + /module/CheckFortranSourceRuns /module/CheckFunctionExists /module/CheckIPOSupported /module/CheckIncludeFileCXX @@ -33,6 +36,13 @@ All Modules /module/CheckIncludeFiles /module/CheckLanguage /module/CheckLibraryExists + /module/CheckOBJCCompilerFlag + /module/CheckOBJCSourceCompiles + /module/CheckOBJCSourceRuns + /module/CheckOBJCXXCompilerFlag + /module/CheckOBJCXXSourceCompiles + /module/CheckOBJCXXSourceRuns + /module/CheckPIESupported /module/CheckPrototypeDefinition /module/CheckStructHasMember /module/CheckSymbolExists @@ -41,33 +51,19 @@ All Modules /module/CMakeAddFortranSubdirectory /module/CMakeBackwardCompatibilityCXX /module/CMakeDependentOption - /module/CMakeDetermineVSServicePack - /module/CMakeExpandImportedTargets /module/CMakeFindDependencyMacro /module/CMakeFindFrameworks /module/CMakeFindPackageMode - /module/CMakeForceCompiler /module/CMakeGraphVizOptions /module/CMakePackageConfigHelpers - /module/CMakeParseArguments /module/CMakePrintHelpers /module/CMakePrintSystemInformation /module/CMakePushCheckState /module/CMakeVerifyManifest - /module/CPackArchive - /module/CPackBundle /module/CPackComponent - /module/CPackCygwin - /module/CPackDeb - /module/CPackDMG /module/CPackIFW /module/CPackIFWConfigureFile - /module/CPackNSIS - /module/CPackPackageMaker - /module/CPackProductBuild - /module/CPackRPM /module/CPack - /module/CPackWIX /module/CSharpUtilities /module/CTest /module/CTestCoverageCollectGCOV @@ -79,6 +75,40 @@ All Modules /module/ExternalData /module/ExternalProject /module/FeatureSummary + /module/FetchContent + /module/FindPackageHandleStandardArgs + /module/FindPackageMessage + /module/FortranCInterface + /module/GenerateExportHeader + /module/GetPrerequisites + /module/GNUInstallDirs + /module/GoogleTest + /module/InstallRequiredSystemLibraries + /module/ProcessorCount + /module/SelectLibraryConfigurations + /module/SquishTestScript + /module/TestBigEndian + /module/TestForANSIForScope + /module/TestForANSIStreamHeaders + /module/TestForSSTREAM + /module/TestForSTDNamespace + /module/UseEcos + /module/UseJavaClassFilelist + /module/UseJava + /module/UseJavaSymlinks + /module/UseSWIG + /module/UsewxWidgets + /module/WriteCompilerDetectionHeader + +Find Modules +^^^^^^^^^^^^ + +These modules search for third-party software. +They are normally called through the :command:`find_package` command. + +.. toctree:: + :maxdepth: 1 + /module/FindALSA /module/FindArmadillo /module/FindASPELL @@ -91,7 +121,6 @@ All Modules /module/FindBZip2 /module/FindCABLE /module/FindCoin3D - /module/FindCUDA /module/FindCups /module/FindCURL /module/FindCurses @@ -102,10 +131,12 @@ All Modules /module/FindDCMTK /module/FindDevIL /module/FindDoxygen + /module/FindEnvModules /module/FindEXPAT /module/FindFLEX /module/FindFLTK2 /module/FindFLTK + /module/FindFontconfig /module/FindFreetype /module/FindGCCXML /module/FindGDAL @@ -128,6 +159,7 @@ All Modules /module/FindIcotool /module/FindICU /module/FindImageMagick + /module/FindIconv /module/FindIntl /module/FindITK /module/FindJasper @@ -139,6 +171,7 @@ All Modules /module/FindLAPACK /module/FindLATEX /module/FindLibArchive + /module/FindLibinput /module/FindLibLZMA /module/FindLibXml2 /module/FindLibXslt @@ -152,6 +185,8 @@ All Modules /module/FindMPEG2 /module/FindMPEG /module/FindMPI + /module/FindODBC + /module/FindOpenACC /module/FindOpenAL /module/FindOpenCL /module/FindOpenGL @@ -179,8 +214,7 @@ All Modules /module/FindosgViewer /module/FindosgVolume /module/FindosgWidget - /module/FindPackageHandleStandardArgs - /module/FindPackageMessage + /module/FindPatch /module/FindPerlLibs /module/FindPerl /module/FindPHP4 @@ -191,11 +225,11 @@ All Modules /module/FindPostgreSQL /module/FindProducer /module/FindProtobuf - /module/FindPythonInterp - /module/FindPythonLibs + /module/FindPython + /module/FindPython2 + /module/FindPython3 /module/FindQt3 /module/FindQt4 - /module/FindQt /module/FindQuickTime /module/FindRTI /module/FindRuby @@ -207,6 +241,7 @@ All Modules /module/FindSDL_ttf /module/FindSelfPackers /module/FindSquish + /module/FindSQLite3 /module/FindSubversion /module/FindSWIG /module/FindTCL @@ -220,36 +255,63 @@ All Modules /module/FindWget /module/FindWish /module/FindwxWidgets - /module/FindwxWindows /module/FindXCTest /module/FindXalanC /module/FindXercesC /module/FindX11 /module/FindXMLRPC /module/FindZLIB - /module/FortranCInterface - /module/GenerateExportHeader - /module/GetPrerequisites - /module/GNUInstallDirs - /module/GoogleTest - /module/InstallRequiredSystemLibraries + +Deprecated Modules +^^^^^^^^^^^^^^^^^^^ + +Deprecated Utility Modules +========================== + +.. toctree:: + :maxdepth: 1 + + /module/CMakeDetermineVSServicePack + /module/CMakeExpandImportedTargets + /module/CMakeForceCompiler + /module/CMakeParseArguments /module/MacroAddFileDependencies - /module/ProcessorCount - /module/SelectLibraryConfigurations - /module/SquishTestScript - /module/TestBigEndian /module/TestCXXAcceptsFlag - /module/TestForANSIForScope - /module/TestForANSIStreamHeaders - /module/TestForSSTREAM - /module/TestForSTDNamespace - /module/UseEcos - /module/UseJavaClassFilelist - /module/UseJava - /module/UseJavaSymlinks /module/UsePkgConfig - /module/UseSWIG - /module/UsewxWidgets /module/Use_wxWindows /module/WriteBasicConfigVersionFile - /module/WriteCompilerDetectionHeader + +Deprecated Find Modules +======================= + +.. toctree:: + :maxdepth: 1 + + /module/FindCUDA + /module/FindPythonInterp + /module/FindPythonLibs + /module/FindQt + /module/FindwxWindows + +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 diff --git a/Help/manual/cmake-packages.7.rst b/Help/manual/cmake-packages.7.rst index c9442bc19..4b2934a8e 100644 --- a/Help/manual/cmake-packages.7.rst +++ b/Help/manual/cmake-packages.7.rst @@ -12,7 +12,7 @@ Introduction Packages provide dependency information to CMake based buildsystems. Packages are found with the :command:`find_package` command. The result of -using ``find_package`` is either a set of :prop_tgt:`IMPORTED` targets, or +using :command:`find_package` is either a set of :prop_tgt:`IMPORTED` targets, or a set of variables corresponding to build-relevant information. Using Packages @@ -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. @@ -647,12 +647,22 @@ Disabling the Package Registry In some cases using the Package Registries is not desirable. CMake allows one to disable them using the following variables: - * :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` disables the - :command:`export(PACKAGE)` command. - * :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` disables the - User Package Registry in all the :command:`find_package` calls. - * :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` disables - the System Package Registry in all the :command:`find_package` calls. +* The :command:`export(PACKAGE)` command does not populate the user + package registry when :policy:`CMP0090` is set to ``NEW`` unless the + :variable:`CMAKE_EXPORT_PACKAGE_REGISTRY` variable explicitly enables it. + When :policy:`CMP0090` is *not* set to ``NEW`` then + :command:`export(PACKAGE)` populates the user package registry unless + the :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` variable explicitly + disables it. +* :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` disables the + User Package Registry in all the :command:`find_package` calls when + set to ``FALSE``. +* Deprecated :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` disables the + User Package Registry in all the :command:`find_package` calls when set + to ``TRUE``. This variable is ignored when + :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` has been set. +* :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` disables + the System Package Registry in all the :command:`find_package` calls. Package Registry Example ------------------------ diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 7b858176f..44ea1a8fd 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -51,6 +51,84 @@ 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.16 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0097: ExternalProject_Add with GIT_SUBMODULES "" initializes no submodules. </policy/CMP0097> + CMP0096: project() preserves leading zeros in version components. </policy/CMP0096> + CMP0095: RPATH entries are properly escaped in the intermediary CMake install script. </policy/CMP0095> + +Policies Introduced by CMake 3.15 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0094: FindPython3, FindPython2 and FindPython use LOCATION for lookup strategy. </policy/CMP0094> + CMP0093: FindBoost reports Boost_VERSION in x.y.z format. </policy/CMP0093> + CMP0092: MSVC warning flags are not in CMAKE_{C,CXX}_FLAGS by default. </policy/CMP0092> + CMP0091: MSVC runtime library flags are selected by an abstraction. </policy/CMP0091> + CMP0090: export(PACKAGE) does not populate package registry by default. </policy/CMP0090> + CMP0089: Compiler id for IBM Clang-based XL compilers is now XLClang. </policy/CMP0089> + +Policies Introduced by CMake 3.14 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0088: FindBISON runs bison in CMAKE_CURRENT_BINARY_DIR when executing. </policy/CMP0088> + CMP0087: install(SCRIPT | CODE) supports generator expressions. </policy/CMP0087> + CMP0086: UseSWIG honors SWIG_MODULE_NAME via -module flag. </policy/CMP0086> + CMP0085: IN_LIST generator expression handles empty list items. </policy/CMP0085> + CMP0084: The FindQt module does not exist for find_package(). </policy/CMP0084> + CMP0083: Add PIE options when linking executable. </policy/CMP0083> + CMP0082: Install rules from add_subdirectory() are interleaved with those in caller. </policy/CMP0082> + + +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 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0075: Include file check macros honor CMAKE_REQUIRED_LIBRARIES. </policy/CMP0075> + CMP0074: find_package uses PackageName_ROOT variables. </policy/CMP0074> + CMP0073: Do not produce legacy _LIB_DEPENDS cache entries. </policy/CMP0073> + +Policies Introduced by CMake 3.11 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0072: FindOpenGL prefers GLVND by default when available. </policy/CMP0072> + +Policies Introduced by CMake 3.10 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0071: Let AUTOMOC and AUTOUIC process GENERATED files. </policy/CMP0071> + CMP0070: Define file(GENERATE) behavior for relative paths. </policy/CMP0070> + Policies Introduced by CMake 3.9 ================================ diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index ec25596f3..e7043714c 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -23,6 +23,7 @@ Properties of Global Scope /prop_gbl/AUTORCC_SOURCE_GROUP /prop_gbl/CMAKE_C_KNOWN_FEATURES /prop_gbl/CMAKE_CXX_KNOWN_FEATURES + /prop_gbl/CMAKE_ROLE /prop_gbl/DEBUG_CONFIGURATIONS /prop_gbl/DISABLED_FEATURES /prop_gbl/ENABLED_FEATURES @@ -40,6 +41,7 @@ Properties of Global Scope /prop_gbl/JOB_POOLS /prop_gbl/PREDEFINED_TARGETS_FOLDER /prop_gbl/ECLIPSE_EXTRA_NATURES + /prop_gbl/ECLIPSE_EXTRA_CPROJECT_CONTENTS /prop_gbl/REPORT_UNDEFINED_PROPERTIES /prop_gbl/RULE_LAUNCH_COMPILE /prop_gbl/RULE_LAUNCH_CUSTOM @@ -59,7 +61,7 @@ Properties on Directories .. toctree:: :maxdepth: 1 - /prop_dir/ADDITIONAL_MAKE_CLEAN_FILES + /prop_dir/ADDITIONAL_CLEAN_FILES /prop_dir/BINARY_DIR /prop_dir/BUILDSYSTEM_TARGETS /prop_dir/CACHE_VARIABLES @@ -74,7 +76,9 @@ Properties on Directories /prop_dir/INCLUDE_REGULAR_EXPRESSION /prop_dir/INTERPROCEDURAL_OPTIMIZATION_CONFIG /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 @@ -83,7 +87,8 @@ Properties on Directories /prop_dir/RULE_LAUNCH_LINK /prop_dir/SOURCE_DIR /prop_dir/SUBDIRECTORIES - /prop_dir/TEST_INCLUDE_FILE + /prop_dir/TESTS + /prop_dir/TEST_INCLUDE_FILES /prop_dir/VARIABLES /prop_dir/VS_GLOBAL_SECTION_POST_section /prop_dir/VS_GLOBAL_SECTION_PRE_section @@ -97,6 +102,7 @@ Properties on Targets .. toctree:: :maxdepth: 1 + /prop_tgt/ADDITIONAL_CLEAN_FILES /prop_tgt/ALIASED_TARGET /prop_tgt/ANDROID_ANT_ADDITIONAL_OPTIONS /prop_tgt/ANDROID_API @@ -120,17 +126,26 @@ Properties on Targets /prop_tgt/ARCHIVE_OUTPUT_NAME_CONFIG /prop_tgt/ARCHIVE_OUTPUT_NAME /prop_tgt/AUTOGEN_BUILD_DIR + /prop_tgt/AUTOGEN_ORIGIN_DEPENDS + /prop_tgt/AUTOGEN_PARALLEL /prop_tgt/AUTOGEN_TARGET_DEPENDS + /prop_tgt/AUTOMOC_COMPILER_PREDEFINES /prop_tgt/AUTOMOC_DEPEND_FILTERS + /prop_tgt/AUTOMOC_EXECUTABLE + /prop_tgt/AUTOMOC_MACRO_NAMES /prop_tgt/AUTOMOC_MOC_OPTIONS + /prop_tgt/AUTOMOC_PATH_PREFIX /prop_tgt/AUTOMOC /prop_tgt/AUTOUIC + /prop_tgt/AUTOUIC_EXECUTABLE /prop_tgt/AUTOUIC_OPTIONS /prop_tgt/AUTOUIC_SEARCH_PATHS /prop_tgt/AUTORCC + /prop_tgt/AUTORCC_EXECUTABLE /prop_tgt/AUTORCC_OPTIONS /prop_tgt/BINARY_DIR /prop_tgt/BUILD_RPATH + /prop_tgt/BUILD_RPATH_USE_ORIGIN /prop_tgt/BUILD_WITH_INSTALL_NAME_DIR /prop_tgt/BUILD_WITH_INSTALL_RPATH /prop_tgt/BUNDLE_EXTENSION @@ -138,6 +153,7 @@ Properties on Targets /prop_tgt/C_EXTENSIONS /prop_tgt/C_STANDARD /prop_tgt/C_STANDARD_REQUIRED + /prop_tgt/COMMON_LANGUAGE_RUNTIME /prop_tgt/COMPATIBLE_INTERFACE_BOOL /prop_tgt/COMPATIBLE_INTERFACE_NUMBER_MAX /prop_tgt/COMPATIBLE_INTERFACE_NUMBER_MIN @@ -165,22 +181,30 @@ Properties on Targets /prop_tgt/DEBUG_POSTFIX /prop_tgt/DEFINE_SYMBOL /prop_tgt/DEPLOYMENT_REMOTE_DIRECTORY + /prop_tgt/DEPLOYMENT_ADDITIONAL_FILES + /prop_tgt/DISABLE_PRECOMPILE_HEADERS + /prop_tgt/DOTNET_TARGET_FRAMEWORK_VERSION /prop_tgt/EchoString /prop_tgt/ENABLE_EXPORTS /prop_tgt/EXCLUDE_FROM_ALL /prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD_CONFIG /prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD /prop_tgt/EXPORT_NAME + /prop_tgt/EXPORT_PROPERTIES /prop_tgt/FOLDER /prop_tgt/Fortran_FORMAT /prop_tgt/Fortran_MODULE_DIRECTORY /prop_tgt/FRAMEWORK /prop_tgt/FRAMEWORK_VERSION /prop_tgt/GENERATOR_FILE_NAME + /prop_tgt/GHS_INTEGRITY_APP + /prop_tgt/GHS_NO_SOURCE_GROUP_FILE /prop_tgt/GNUtoMS /prop_tgt/HAS_CXX /prop_tgt/IMPLICIT_DEPENDS_INCLUDE_TRANSFORM + /prop_tgt/IMPORTED_COMMON_LANGUAGE_RUNTIME /prop_tgt/IMPORTED_CONFIGURATIONS + /prop_tgt/IMPORTED_GLOBAL /prop_tgt/IMPORTED_IMPLIB_CONFIG /prop_tgt/IMPORTED_IMPLIB /prop_tgt/IMPORTED_LIBNAME_CONFIG @@ -206,6 +230,7 @@ Properties on Targets /prop_tgt/IMPORT_SUFFIX /prop_tgt/INCLUDE_DIRECTORIES /prop_tgt/INSTALL_NAME_DIR + /prop_tgt/INSTALL_REMOVE_ENVIRONMENT_RPATH /prop_tgt/INSTALL_RPATH /prop_tgt/INSTALL_RPATH_USE_LINK_PATH /prop_tgt/INTERFACE_AUTOUIC_OPTIONS @@ -213,7 +238,11 @@ 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_PRECOMPILE_HEADERS /prop_tgt/INTERFACE_POSITION_INDEPENDENT_CODE /prop_tgt/INTERFACE_SOURCES /prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES @@ -225,6 +254,7 @@ Properties on Targets /prop_tgt/LABELS /prop_tgt/LANG_CLANG_TIDY /prop_tgt/LANG_COMPILER_LAUNCHER + /prop_tgt/LANG_CPPCHECK /prop_tgt/LANG_CPPLINT /prop_tgt/LANG_INCLUDE_WHAT_YOU_USE /prop_tgt/LANG_VISIBILITY_PRESET @@ -235,6 +265,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 @@ -242,6 +273,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 @@ -253,9 +285,16 @@ Properties on Targets /prop_tgt/MACOSX_RPATH /prop_tgt/MANUALLY_ADDED_DEPENDENCIES /prop_tgt/MAP_IMPORTED_CONFIG_CONFIG + /prop_tgt/MSVC_RUNTIME_LIBRARY /prop_tgt/NAME /prop_tgt/NO_SONAME /prop_tgt/NO_SYSTEM_FROM_IMPORTED + /prop_tgt/OBJC_EXTENSIONS + /prop_tgt/OBJC_STANDARD + /prop_tgt/OBJC_STANDARD_REQUIRED + /prop_tgt/OBJCXX_EXTENSIONS + /prop_tgt/OBJCXX_STANDARD + /prop_tgt/OBJCXX_STANDARD_REQUIRED /prop_tgt/OSX_ARCHITECTURES_CONFIG /prop_tgt/OSX_ARCHITECTURES /prop_tgt/OUTPUT_NAME_CONFIG @@ -265,6 +304,8 @@ Properties on Targets /prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG /prop_tgt/PDB_OUTPUT_DIRECTORY /prop_tgt/POSITION_INDEPENDENT_CODE + /prop_tgt/PRECOMPILE_HEADERS + /prop_tgt/PRECOMPILE_HEADERS_REUSE_FROM /prop_tgt/PREFIX /prop_tgt/PRIVATE_HEADER /prop_tgt/PROJECT_LABEL @@ -283,25 +324,43 @@ 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/Swift_DEPENDENCIES_FILE + /prop_tgt/Swift_LANGUAGE_VERSION + /prop_tgt/Swift_MODULE_DIRECTORY + /prop_tgt/Swift_MODULE_NAME /prop_tgt/TYPE + /prop_tgt/UNITY_BUILD + /prop_tgt/UNITY_BUILD_BATCH_SIZE + /prop_tgt/UNITY_BUILD_CODE_AFTER_INCLUDE + /prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE /prop_tgt/VERSION /prop_tgt/VISIBILITY_INLINES_HIDDEN /prop_tgt/VS_CONFIGURATION_TYPE + /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 /prop_tgt/VS_DOTNET_REFERENCES /prop_tgt/VS_DOTNET_REFERENCES_COPY_LOCAL /prop_tgt/VS_DOTNET_TARGET_FRAMEWORK_VERSION + /prop_tgt/VS_DPI_AWARE /prop_tgt/VS_GLOBAL_KEYWORD /prop_tgt/VS_GLOBAL_PROJECT_TYPES /prop_tgt/VS_GLOBAL_ROOTNAMESPACE /prop_tgt/VS_GLOBAL_variable /prop_tgt/VS_IOT_EXTENSIONS_VERSION /prop_tgt/VS_IOT_STARTUP_TASK + /prop_tgt/VS_JUST_MY_CODE_DEBUGGING /prop_tgt/VS_KEYWORD /prop_tgt/VS_MOBILE_EXTENSIONS_VERSION + /prop_tgt/VS_NO_SOLUTION_DEPLOY + /prop_tgt/VS_PACKAGE_REFERENCES + /prop_tgt/VS_PROJECT_IMPORT /prop_tgt/VS_SCC_AUXPATH /prop_tgt/VS_SCC_LOCALPATH /prop_tgt/VS_SCC_PROJECTNAME @@ -316,7 +375,28 @@ Properties on Targets /prop_tgt/WINDOWS_EXPORT_ALL_SYMBOLS /prop_tgt/XCODE_ATTRIBUTE_an-attribute /prop_tgt/XCODE_EXPLICIT_FILE_TYPE + /prop_tgt/XCODE_GENERATE_SCHEME /prop_tgt/XCODE_PRODUCT_TYPE + /prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER + /prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN + /prop_tgt/XCODE_SCHEME_ARGUMENTS + /prop_tgt/XCODE_SCHEME_DEBUG_AS_ROOT + /prop_tgt/XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING + /prop_tgt/XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER + /prop_tgt/XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS + /prop_tgt/XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE + /prop_tgt/XCODE_SCHEME_ENVIRONMENT + /prop_tgt/XCODE_SCHEME_EXECUTABLE + /prop_tgt/XCODE_SCHEME_GUARD_MALLOC + /prop_tgt/XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP + /prop_tgt/XCODE_SCHEME_MALLOC_GUARD_EDGES + /prop_tgt/XCODE_SCHEME_MALLOC_SCRIBBLE + /prop_tgt/XCODE_SCHEME_MALLOC_STACK + /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_ZOMBIE_OBJECTS /prop_tgt/XCTEST .. _`Test Properties`: @@ -340,10 +420,13 @@ Properties on Tests /prop_test/LABELS /prop_test/MEASUREMENT /prop_test/PASS_REGULAR_EXPRESSION + /prop_test/PROCESSOR_AFFINITY /prop_test/PROCESSORS /prop_test/REQUIRED_FILES + /prop_test/RESOURCE_GROUPS /prop_test/RESOURCE_LOCK /prop_test/RUN_SERIAL + /prop_test/SKIP_REGULAR_EXPRESSION /prop_test/SKIP_RETURN_CODE /prop_test/TIMEOUT /prop_test/TIMEOUT_AFTER_MATCH @@ -363,10 +446,12 @@ Properties on Source Files /prop_sf/AUTORCC_OPTIONS /prop_sf/COMPILE_DEFINITIONS /prop_sf/COMPILE_FLAGS + /prop_sf/COMPILE_OPTIONS /prop_sf/EXTERNAL_OBJECT /prop_sf/Fortran_FORMAT /prop_sf/GENERATED /prop_sf/HEADER_FILE_ONLY + /prop_sf/INCLUDE_DIRECTORIES /prop_sf/KEEP_EXTENSION /prop_sf/LABELS /prop_sf/LANGUAGE @@ -378,6 +463,10 @@ Properties on Source Files /prop_sf/SKIP_AUTOMOC /prop_sf/SKIP_AUTORCC /prop_sf/SKIP_AUTOUIC + /prop_sf/SKIP_PRECOMPILE_HEADERS + /prop_sf/SKIP_UNITY_BUILD_INCLUSION + /prop_sf/Swift_DEPENDENCIES_FILE + /prop_sf/Swift_DIAGNOSTICS_FILE /prop_sf/SYMBOLIC /prop_sf/VS_COPY_TO_OUT_DIR /prop_sf/VS_CSHARP_tagname @@ -385,10 +474,15 @@ Properties on Source Files /prop_sf/VS_DEPLOYMENT_LOCATION /prop_sf/VS_INCLUDE_IN_VSIX /prop_sf/VS_RESOURCE_GENERATOR + /prop_sf/VS_SHADER_DISABLE_OPTIMIZATIONS + /prop_sf/VS_SHADER_ENABLE_DEBUG /prop_sf/VS_SHADER_ENTRYPOINT /prop_sf/VS_SHADER_FLAGS /prop_sf/VS_SHADER_MODEL + /prop_sf/VS_SHADER_OBJECT_FILE_NAME + /prop_sf/VS_SHADER_OUTPUT_HEADER_FILE /prop_sf/VS_SHADER_TYPE + /prop_sf/VS_SHADER_VARIABLE_NAME /prop_sf/VS_TOOL_OVERRIDE.rst /prop_sf/VS_XAML_TYPE /prop_sf/WRAP_EXCLUDE @@ -433,7 +527,9 @@ Deprecated Properties on Directories .. toctree:: :maxdepth: 1 + /prop_dir/ADDITIONAL_MAKE_CLEAN_FILES /prop_dir/COMPILE_DEFINITIONS_CONFIG + /prop_dir/TEST_INCLUDE_FILE Deprecated Properties on Targets diff --git a/Help/manual/cmake-qt.7.rst b/Help/manual/cmake-qt.7.rst index b7f16b9ea..d8d61729e 100644 --- a/Help/manual/cmake-qt.7.rst +++ b/Help/manual/cmake-qt.7.rst @@ -44,14 +44,10 @@ Qt Build Tools Qt relies on some bundled tools for code generation, such as ``moc`` for meta-object code generation, ``uic`` for widget layout and population, -and ``rcc`` for virtual filesystem content generation. These tools may be +and ``rcc`` for virtual file system content generation. These tools may be automatically invoked by :manual:`cmake(1)` if the appropriate conditions are met. The automatic tool invocation may be used with both Qt 4 and Qt 5. -The tools are executed as part of a synthesized custom target generated by -CMake. Target dependencies may be added to that custom target by adding them -to the :prop_tgt:`AUTOGEN_TARGET_DEPENDS` target property. - AUTOMOC ^^^^^^^ @@ -59,9 +55,10 @@ The :prop_tgt:`AUTOMOC` target property controls whether :manual:`cmake(1)` inspects the C++ files in the target to determine if they require ``moc`` to be run, and to create rules to execute ``moc`` at the appropriate time. -If a ``Q_OBJECT`` or ``Q_GADGET`` macro is found in a header file, ``moc`` -will be run on the file. The result will be put into a file named according -to ``moc_<basename>.cpp``. If the macro is found in a C++ implementation +If a macro from :prop_tgt:`AUTOMOC_MACRO_NAMES` is found in a header file, +``moc`` will be run on the file. The result will be put into a file named +according to ``moc_<basename>.cpp``. +If the macro is found in a C++ implementation file, the moc output will be put into a file named according to ``<basename>.moc``, following the Qt conventions. The ``<basename>.moc`` must be included by the user in the C++ implementation file with a preprocessor @@ -72,6 +69,10 @@ Included ``moc_*.cpp`` and ``*.moc`` files will be generated in the automatically added to the target's :prop_tgt:`INCLUDE_DIRECTORIES`. * This differs from CMake 3.7 and below; see their documentation for details. + +* For :prop_gbl:`multi configuration generators <GENERATOR_IS_MULTI_CONFIG>`, + the include directory is ``<AUTOGEN_BUILD_DIR>/include_<CONFIG>``. + * See :prop_tgt:`AUTOGEN_BUILD_DIR`. Not included ``moc_<basename>.cpp`` files will be generated in custom @@ -91,6 +92,9 @@ following targets by setting the :variable:`CMAKE_AUTOMOC` variable. The options to pass to ``moc``. The :variable:`CMAKE_AUTOMOC_MOC_OPTIONS` variable may be populated to pre-set the options for all following targets. +Additional macro names to search for can be added to +:prop_tgt:`AUTOMOC_MACRO_NAMES`. + Additional ``moc`` dependency file names can be extracted from source code by using :prop_tgt:`AUTOMOC_DEPEND_FILTERS`. @@ -124,6 +128,10 @@ The generated generated ``ui_*.h`` files are placed in the automatically added to the target's :prop_tgt:`INCLUDE_DIRECTORIES`. * This differs from CMake 3.7 and below; see their documentation for details. + +* For :prop_gbl:`multi configuration generators <GENERATOR_IS_MULTI_CONFIG>`, + the include directory is ``<AUTOGEN_BUILD_DIR>/include_<CONFIG>``. + * See :prop_tgt:`AUTOGEN_BUILD_DIR`. The :prop_tgt:`AUTOUIC` target property may be pre-set for all following @@ -202,6 +210,34 @@ overrides options from the :prop_tgt:`AUTORCC_OPTIONS` target property. Source files can be excluded from :prop_tgt:`AUTORCC` processing by enabling :prop_sf:`SKIP_AUTORCC` or the broader :prop_sf:`SKIP_AUTOGEN`. +The ``<ORIGIN>_autogen`` target +=============================== + +The ``moc`` and ``uic`` tools are executed as part of a synthesized +``<ORIGIN>_autogen`` :command:`custom target <add_custom_target>` generated by +CMake. By default that ``<ORIGIN>_autogen`` target inherits the dependencies +of the ``<ORIGIN>`` target (see :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS`). +Target dependencies may be added to the ``<ORIGIN>_autogen`` target by adding +them to the :prop_tgt:`AUTOGEN_TARGET_DEPENDS` target property. + +Visual Studio Generators +======================== + +When using the :manual:`Visual Studio generators <cmake-generators(7)>`, CMake +generates a ``PRE_BUILD`` :command:`custom command <add_custom_command>` +instead of the ``<ORIGIN>_autogen`` :command:`custom target <add_custom_target>` +(for :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`). +This isn't always possible though and +an ``<ORIGIN>_autogen`` :command:`custom target <add_custom_target>` is used, +when either + +- the ``<ORIGIN>`` target depends on :prop_sf:`GENERATED` files which aren't + excluded from :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` by + :prop_sf:`SKIP_AUTOMOC`, :prop_sf:`SKIP_AUTOUIC`, :prop_sf:`SKIP_AUTOGEN` + or :policy:`CMP0071` +- :prop_tgt:`AUTOGEN_TARGET_DEPENDS` lists a source file +- :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET` is enabled + qtmain.lib on Windows ===================== diff --git a/Help/manual/cmake-server.7.rst b/Help/manual/cmake-server.7.rst index 9520cc140..8f10b9f0e 100644 --- a/Help/manual/cmake-server.7.rst +++ b/Help/manual/cmake-server.7.rst @@ -7,6 +7,11 @@ cmake-server(7) .. contents:: +.. deprecated:: 3.15 + + This will be removed from a future version of CMake. + Clients should use the :manual:`cmake-file-api(7)` instead. + Introduction ============ @@ -49,10 +54,12 @@ Operation Start :manual:`cmake(1)` in the server command mode, supplying the path to the build directory to process:: - cmake -E server (--debug|--pipe <NAMED_PIPE>) + cmake -E server (--debug|--pipe=<NAMED_PIPE>) The server will communicate using stdin/stdout (with the ``--debug`` parameter) -or using a named pipe (with the ``--pipe <NAMED_PIPE>`` parameter). +or using a named pipe (with the ``--pipe=<NAMED_PIPE>`` parameter). Note +that "named pipe" refers to a local domain socket on Unix and to a named pipe +on Windows. When connecting to the server (via named pipe or by starting it in ``--debug`` mode), the server will reply with a hello message:: @@ -162,7 +169,7 @@ When the server is busy for a long time, it is polite to send back replies of type "progress" to the client. These will contain a "progressMessage" with a string describing the action currently taking place as well as "progressMinimum", "progressMaximum" and "progressCurrent" with integer values -describing the range of progess. +describing the range of progress. Messages of type "progress" will be followed by more "progress" messages or with a message of type "reply" or "error" that complete the request. @@ -254,6 +261,11 @@ versions supported by the cmake server. These are JSON objects with "major" and as experimental. These will contain the "isExperimental" key set to true. Enabling these requires a special command line argument when starting the cmake server mode. +Within a "major" version all "minor" versions are fully backwards compatible. +New "minor" versions may introduce functionality in such a way that existing +clients of the same "major" version will continue to work, provided they +ignore keys in the output that they do not know about. + Example:: [== "CMake Server" ==[ @@ -268,8 +280,9 @@ The first request that the client may send to the server is of type "handshake". This request needs to pass one of the "supportedProtocolVersions" of the "hello" type response received earlier back to the server in the "protocolVersion" field. - -Each protocol version may request additional attributes to be present. +Giving the "major" version of the requested protocol version will make the server +use the latest minor version of that protocol. Use this if you do not explicitly +need to depend on a specific minor version. Protocol version 1.0 requires the following attributes to be set: @@ -280,6 +293,10 @@ Protocol version 1.0 requires the following attributes to be set: * "platform" with the generator platform (if supported by the generator) * "toolset" with the generator toolset (if supported by the generator) +Protocol version 1.2 makes all but the build directory optional, provided +there is a valid cache in the build directory that contains all the other +information already. + Example:: [== "CMake Server" ==[ @@ -448,6 +465,11 @@ Each project object can have the following keys: "name" contains the (sub-)projects name. +"minimumCMakeVersion" + contains the minimum cmake version allowed for this project, null if the + project doesn't specify one. +"hasInstallRule" + true if the project contains any install rules, false otherwise. "sourceDirectory" contains the current source directory "buildDirectory" @@ -471,6 +493,12 @@ Each target object can have the following keys: contains the current source directory. "buildDirectory" contains the current build directory. +"isGeneratorProvided" + true if the target is auto-created by a generator, false otherwise +"hasInstallRule" + true if the target contains any install rules, false otherwise. +"installPaths" + full path to the destination directories defined by target install rules. "artifacts" with a list of build artifacts. The list is sorted with the most important artifacts first (e.g. a .DLL file is listed before a @@ -572,6 +600,51 @@ CMake will reply:: ]== "CMake Server" ==] +Type "ctestInfo" +^^^^^^^^^^^^^^^^ + +The "ctestInfo" request can be used after a project was "compute"d successfully. + +It will list the complete project test structure as it is known to cmake. + +The reply will contain a key "configurations", which will contain a list of +configuration objects. Configuration objects are used to destinquish between +different configurations the build directory might have enabled. While most +generators only support one configuration, others might support several. + +Each configuration object can have the following keys: + +"name" + contains the name of the configuration. The name may be empty. +"projects" + contains a list of project objects, one for each build project. + +Project objects define one (sub-)project defined in the cmake build system. + +Each project object can have the following keys: + +"name" + contains the (sub-)projects name. +"ctestInfo" + contains a list of test objects. + +Each test object can have the following keys: + +"ctestName" + contains the name of the test. +"ctestCommand" + contains the test command. +"properties" + contains a list of test property objects. + +Each test property object can have the following keys: + +"key" + contains the test property key. +"value" + contains the test property value. + + Type "cmakeInputs" ^^^^^^^^^^^^^^^^^^ @@ -616,8 +689,7 @@ and will not survive the build directory getting cleaned out. Type "cache" ^^^^^^^^^^^^ -The "cache" request can be used once a project is configured and will -list the cached configuration values. +The "cache" request will list the cached configuration values. Example:: diff --git a/Help/manual/cmake-toolchains.7.rst b/Help/manual/cmake-toolchains.7.rst index 8554e87f9..f233d0884 100644 --- a/Help/manual/cmake-toolchains.7.rst +++ b/Help/manual/cmake-toolchains.7.rst @@ -26,13 +26,13 @@ built-in variables, such as :variable:`CMAKE_CXX_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` etc are set by invoking the :command:`project` command. If no project command is in the top-level CMakeLists file, one will be implicitly generated. By default -the enabled languages are C and CXX: +the enabled languages are ``C`` and ``CXX``: .. code-block:: cmake project(C_Only C) -A special value of NONE can also be used with the :command:`project` command +A special value of ``NONE`` can also be used with the :command:`project` command to enable no languages: .. code-block:: cmake @@ -101,6 +101,14 @@ values for the compilers. The :variable:`CMAKE_CROSSCOMPILING` variable is set to true when CMake is cross-compiling. +Note that using the :variable:`CMAKE_SOURCE_DIR` or :variable:`CMAKE_BINARY_DIR` +variables inside a toolchain file is typically undesirable. The toolchain +file is used in contexts where these variables have different values when used +in different places (e.g. as part of a call to :command:`try_compile`). In most +cases, where there is a need to evaluate paths inside a toolchain file, the more +appropriate variable to use would be :variable:`CMAKE_CURRENT_LIST_DIR`, since +it always has an unambiguous, predictable value. + Cross Compiling for Linux ------------------------- @@ -391,8 +399,10 @@ Configure use of an Android NDK with the following variables: be false unless using a NDK that does not provide unified headers. :variable:`CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION` - Set to the version of the NDK toolchain to be selected as the compiler. - If not specified, the default will be the latest available GCC toolchain. + On NDK r19 or above, this variable must be unset or set to ``clang``. + On NDK r18 or below, set this to the version of the NDK toolchain to + be selected as the compiler. If not specified, the default will be + the latest available GCC toolchain. :variable:`CMAKE_ANDROID_STL_TYPE` Set to specify which C++ standard library to use. If not specified, @@ -468,10 +478,10 @@ The following variables will be computed and provided automatically: The Android ABI detected from the standalone toolchain. :variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX` - The absolute path prefix to the binutils in the standalone toolchain. + The absolute path prefix to the ``binutils`` in the standalone toolchain. :variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX` - The host platform suffix of the binutils in the standalone toolchain. + The host platform suffix of the ``binutils`` in the standalone toolchain. For example, a toolchain file might contain: @@ -522,3 +532,132 @@ See also target properties: * :prop_tgt:`ANDROID_SECURE_PROPS_PATH` * :prop_tgt:`ANDROID_SKIP_ANT_STEP` * :prop_tgt:`ANDROID_STL_TYPE` + +.. _`Cross Compiling for iOS, tvOS, or watchOS`: + +Cross Compiling for iOS, tvOS, or watchOS +----------------------------------------- + +For cross-compiling to iOS, tvOS, or watchOS, the :generator:`Xcode` +generator is recommended. The :generator:`Unix Makefiles` or +:generator:`Ninja` generators can also be used, but they require the +project to handle more areas like target CPU selection and code signing. + +Any of the three systems can be targeted by setting the +:variable:`CMAKE_SYSTEM_NAME` variable to a value from the table below. +By default, the latest Device SDK is chosen. As for all Apple platforms, +a different SDK (e.g. a simulator) can be selected by setting the +:variable:`CMAKE_OSX_SYSROOT` variable, although this should rarely be +necessary (see :ref:`Switching Between Device and Simulator` below). +A list of available SDKs can be obtained by running ``xcodebuild -showsdks``. + +======= ================= ==================== ================ +OS CMAKE_SYSTEM_NAME Device SDK (default) Simulator SDK +======= ================= ==================== ================ +iOS iOS iphoneos iphonesimulator +tvOS tvOS appletvos appletvsimulator +watchOS watchOS watchos watchsimulator +======= ================= ==================== ================ + +For example, to create a CMake configuration for iOS, the following +command is sufficient: + +.. code-block:: console + + cmake .. -GXcode -DCMAKE_SYSTEM_NAME=iOS + +Variable :variable:`CMAKE_OSX_ARCHITECTURES` can be used to set architectures +for both device and simulator. Variable :variable:`CMAKE_OSX_DEPLOYMENT_TARGET` +can be used to set an iOS/tvOS/watchOS deployment target. + +Next configuration will install fat 5 architectures iOS library +and add the ``-miphoneos-version-min=9.3``/``-mios-simulator-version-min=9.3`` +flags to the compiler: + +.. code-block:: console + + $ cmake -S. -B_builds -GXcode \ + -DCMAKE_SYSTEM_NAME=iOS \ + "-DCMAKE_OSX_ARCHITECTURES=armv7;armv7s;arm64;i386;x86_64" \ + -DCMAKE_OSX_DEPLOYMENT_TARGET=9.3 \ + -DCMAKE_INSTALL_PREFIX=`pwd`/_install \ + -DCMAKE_XCODE_ATTRIBUTE_ONLY_ACTIVE_ARCH=NO \ + -DCMAKE_IOS_INSTALL_COMBINED=YES + +Example: + +.. code-block:: cmake + + # CMakeLists.txt + cmake_minimum_required(VERSION 3.14) + project(foo) + add_library(foo foo.cpp) + install(TARGETS foo DESTINATION lib) + +Install: + +.. code-block:: console + + $ cmake --build _builds --config Release --target install + +Check library: + +.. code-block:: console + + $ lipo -info _install/lib/libfoo.a + Architectures in the fat file: _install/lib/libfoo.a are: i386 armv7 armv7s x86_64 arm64 + +.. code-block:: console + + $ otool -l _install/lib/libfoo.a | grep -A2 LC_VERSION_MIN_IPHONEOS + cmd LC_VERSION_MIN_IPHONEOS + cmdsize 16 + version 9.3 + +Code Signing +^^^^^^^^^^^^ + +Some build artifacts for the embedded Apple platforms require mandatory +code signing. If the :generator:`Xcode` generator is being used and +code signing is required or desired, the development team ID can be +specified via the ``CMAKE_XCODE_ATTRIBUTE_DEVELOPMENT_TEAM`` CMake variable. +This team ID will then be included in the generated Xcode project. +By default, CMake avoids the need for code signing during the internal +configuration phase (i.e compiler ID and feature detection). + +.. _`Switching Between Device and Simulator`: + +Switching Between Device and Simulator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When configuring for any of the embedded platforms, one can target either +real devices or the simulator. Both have their own separate SDK, but CMake +only supports specifying a single SDK for the configuration phase. This +means the developer must select one or the other at configuration time. +When using the :generator:`Xcode` generator, this is less of a limitation +because Xcode still allows you to build for either a device or a simulator, +even though configuration was only performed for one of the two. From +within the Xcode IDE, builds are performed for the selected "destination" +platform. When building from the command line, the desired sdk can be +specified directly by passing a ``-sdk`` option to the underlying build +tool (``xcodebuild``). For example: + +.. code-block:: console + + $ cmake --build ... -- -sdk iphonesimulator + +Please note that checks made during configuration were performed against +the configure-time SDK and might not hold true for other SDKs. Commands +like :command:`find_package`, :command:`find_library`, etc. store and use +details only for the configured SDK/platform, so they can be problematic +if wanting to switch between device and simulator builds. You can follow +the next rules to make device + simulator configuration work: + +- Use explicit ``-l`` linker flag, + e.g. ``target_link_libraries(foo PUBLIC "-lz")`` + +- Use explicit ``-framework`` linker flag, + e.g. ``target_link_libraries(foo PUBLIC "-framework CoreFoundation")`` + +- Use :command:`find_package` only for libraries installed with + :variable:`CMAKE_IOS_INSTALL_COMBINED` feature diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 1a2726dd3..53b7f8ddd 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -7,6 +7,14 @@ cmake-variables(7) .. contents:: +This page documents variables that are provided by CMake +or have meaning to CMake when set by project code. + +For general information on variables, see the +:ref:`Variables <CMake Language Variables>` +section in the cmake-language manual. + + Variables that Provide Information ================================== @@ -24,6 +32,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 @@ -32,7 +41,9 @@ Variables that Provide Information /variable/CMAKE_CURRENT_LIST_FILE /variable/CMAKE_CURRENT_LIST_LINE /variable/CMAKE_CURRENT_SOURCE_DIR + /variable/CMAKE_DIRECTORY_LABELS /variable/CMAKE_DL_LIBS + /variable/CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION /variable/CMAKE_EDIT_COMMAND /variable/CMAKE_EXECUTABLE_SUFFIX /variable/CMAKE_EXTRA_GENERATOR @@ -41,15 +52,17 @@ Variables that Provide Information /variable/CMAKE_FIND_PACKAGE_SORT_DIRECTION /variable/CMAKE_FIND_PACKAGE_SORT_ORDER /variable/CMAKE_GENERATOR + /variable/CMAKE_GENERATOR_INSTANCE /variable/CMAKE_GENERATOR_PLATFORM /variable/CMAKE_GENERATOR_TOOLSET - /variable/CMAKE_HOME_DIRECTORY /variable/CMAKE_IMPORT_LIBRARY_PREFIX /variable/CMAKE_IMPORT_LIBRARY_SUFFIX /variable/CMAKE_JOB_POOL_COMPILE /variable/CMAKE_JOB_POOL_LINK + /variable/CMAKE_JOB_POOLS /variable/CMAKE_LANG_COMPILER_AR /variable/CMAKE_LANG_COMPILER_RANLIB + /variable/CMAKE_LANG_LINK_LIBRARY_SUFFIX /variable/CMAKE_LINK_LIBRARY_SUFFIX /variable/CMAKE_LINK_SEARCH_END_STATIC /variable/CMAKE_LINK_SEARCH_START_STATIC @@ -57,14 +70,24 @@ Variables that Provide Information /variable/CMAKE_MAKE_PROGRAM /variable/CMAKE_MATCH_COUNT /variable/CMAKE_MATCH_n + /variable/CMAKE_MESSAGE_INDENT /variable/CMAKE_MINIMUM_REQUIRED_VERSION /variable/CMAKE_MINOR_VERSION + /variable/CMAKE_NETRC + /variable/CMAKE_NETRC_FILE /variable/CMAKE_PARENT_LIST_FILE /variable/CMAKE_PATCH_VERSION /variable/CMAKE_PROJECT_DESCRIPTION + /variable/CMAKE_PROJECT_HOMEPAGE_URL /variable/CMAKE_PROJECT_NAME + /variable/CMAKE_PROJECT_VERSION + /variable/CMAKE_PROJECT_VERSION_MAJOR + /variable/CMAKE_PROJECT_VERSION_MINOR + /variable/CMAKE_PROJECT_VERSION_PATCH + /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 @@ -76,22 +99,28 @@ Variables that Provide Information /variable/CMAKE_SOURCE_DIR /variable/CMAKE_STATIC_LIBRARY_PREFIX /variable/CMAKE_STATIC_LIBRARY_SUFFIX + /variable/CMAKE_Swift_MODULE_DIRECTORY + /variable/CMAKE_Swift_NUM_THREADS /variable/CMAKE_TOOLCHAIN_FILE /variable/CMAKE_TWEAK_VERSION /variable/CMAKE_VERBOSE_MAKEFILE /variable/CMAKE_VERSION /variable/CMAKE_VS_DEVENV_COMMAND - /variable/CMAKE_VS_INTEL_Fortran_PROJECT_VERSION /variable/CMAKE_VS_MSBUILD_COMMAND /variable/CMAKE_VS_NsightTegra_VERSION /variable/CMAKE_VS_PLATFORM_NAME + /variable/CMAKE_VS_PLATFORM_NAME_DEFAULT /variable/CMAKE_VS_PLATFORM_TOOLSET /variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA + /variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR /variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE + /variable/CMAKE_VS_PLATFORM_TOOLSET_VERSION /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION /variable/CMAKE_XCODE_GENERATE_SCHEME /variable/CMAKE_XCODE_PLATFORM_TOOLSET /variable/PROJECT-NAME_BINARY_DIR + /variable/PROJECT-NAME_DESCRIPTION + /variable/PROJECT-NAME_HOMEPAGE_URL /variable/PROJECT-NAME_SOURCE_DIR /variable/PROJECT-NAME_VERSION /variable/PROJECT-NAME_VERSION_MAJOR @@ -100,6 +129,7 @@ Variables that Provide Information /variable/PROJECT-NAME_VERSION_TWEAK /variable/PROJECT_BINARY_DIR /variable/PROJECT_DESCRIPTION + /variable/PROJECT_HOMEPAGE_URL /variable/PROJECT_NAME /variable/PROJECT_SOURCE_DIR /variable/PROJECT_VERSION @@ -120,6 +150,8 @@ Variables that Change Behavior /variable/CMAKE_AUTOMOC_RELAXED_MODE /variable/CMAKE_BACKWARDS_COMPATIBILITY /variable/CMAKE_BUILD_TYPE + /variable/CMAKE_CODEBLOCKS_COMPILER_ID + /variable/CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES /variable/CMAKE_CODELITE_USE_TARGETS /variable/CMAKE_COLOR_MAKEFILE /variable/CMAKE_CONFIGURATION_TYPES @@ -129,10 +161,13 @@ Variables that Change Behavior /variable/CMAKE_ECLIPSE_GENERATE_LINKED_RESOURCES /variable/CMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT /variable/CMAKE_ECLIPSE_MAKE_ARGUMENTS + /variable/CMAKE_ECLIPSE_RESOURCE_ENCODING /variable/CMAKE_ECLIPSE_VERSION /variable/CMAKE_ERROR_DEPRECATED /variable/CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION + /variable/CMAKE_EXECUTE_PROCESS_COMMAND_ECHO /variable/CMAKE_EXPORT_COMPILE_COMMANDS + /variable/CMAKE_EXPORT_PACKAGE_REGISTRY /variable/CMAKE_EXPORT_NO_PACKAGE_REGISTRY /variable/CMAKE_FIND_APPBUNDLE /variable/CMAKE_FIND_FRAMEWORK @@ -142,34 +177,48 @@ Variables that Change Behavior /variable/CMAKE_FIND_NO_INSTALL_PREFIX /variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY /variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY + /variable/CMAKE_FIND_PACKAGE_PREFER_CONFIG + /variable/CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS /variable/CMAKE_FIND_PACKAGE_WARN_NO_MODULE /variable/CMAKE_FIND_ROOT_PATH /variable/CMAKE_FIND_ROOT_PATH_MODE_INCLUDE /variable/CMAKE_FIND_ROOT_PATH_MODE_LIBRARY /variable/CMAKE_FIND_ROOT_PATH_MODE_PACKAGE /variable/CMAKE_FIND_ROOT_PATH_MODE_PROGRAM + /variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH + /variable/CMAKE_FIND_USE_CMAKE_PATH + /variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH + /variable/CMAKE_FIND_USE_PACKAGE_REGISTRY + /variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH + /variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH + /variable/CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY /variable/CMAKE_FRAMEWORK_PATH /variable/CMAKE_IGNORE_PATH /variable/CMAKE_INCLUDE_DIRECTORIES_BEFORE /variable/CMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE /variable/CMAKE_INCLUDE_PATH /variable/CMAKE_INSTALL_DEFAULT_COMPONENT_NAME + /variable/CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS /variable/CMAKE_INSTALL_MESSAGE /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_MAXIMUM_RECURSION_DEPTH /variable/CMAKE_MODULE_PATH - /variable/CMAKE_NOT_USING_CONFIG_FLAGS /variable/CMAKE_POLICY_DEFAULT_CMPNNNN /variable/CMAKE_POLICY_WARNING_CMPNNNN /variable/CMAKE_PREFIX_PATH /variable/CMAKE_PROGRAM_PATH + /variable/CMAKE_PROJECT_INCLUDE + /variable/CMAKE_PROJECT_INCLUDE_BEFORE /variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE /variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY /variable/CMAKE_STAGING_PREFIX /variable/CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS /variable/CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE + /variable/CMAKE_SUPPRESS_REGENERATION /variable/CMAKE_SYSROOT /variable/CMAKE_SYSROOT_COMPILE /variable/CMAKE_SYSROOT_LINK @@ -183,6 +232,24 @@ Variables that Change Behavior /variable/CMAKE_USER_MAKE_RULES_OVERRIDE /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_DEBUG_DOCUMENT_VERSIONING + /variable/CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER + /variable/CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS + /variable/CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE + /variable/CMAKE_XCODE_SCHEME_GUARD_MALLOC + /variable/CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP + /variable/CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES + /variable/CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE + /variable/CMAKE_XCODE_SCHEME_MALLOC_STACK + /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_ZOMBIE_OBJECTS + /variable/PackageName_ROOT Variables that Describe the System ================================== @@ -211,8 +278,8 @@ Variables that Describe the System /variable/CMAKE_SYSTEM_PROCESSOR /variable/CMAKE_SYSTEM_VERSION /variable/CYGWIN - /variable/ENV /variable/GHS-MULTI + /variable/IOS /variable/MINGW /variable/MSVC /variable/MSVC10 @@ -225,7 +292,9 @@ Variables that Describe the System /variable/MSVC80 /variable/MSVC90 /variable/MSVC_IDE + /variable/MSVC_TOOLSET_VERSION /variable/MSVC_VERSION + /variable/MSYS /variable/UNIX /variable/WIN32 /variable/WINCE @@ -267,32 +336,50 @@ Variables that Control the Build /variable/CMAKE_ANDROID_STL_TYPE /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG + /variable/CMAKE_AUTOGEN_ORIGIN_DEPENDS + /variable/CMAKE_AUTOGEN_PARALLEL + /variable/CMAKE_AUTOGEN_VERBOSE /variable/CMAKE_AUTOMOC + /variable/CMAKE_AUTOMOC_COMPILER_PREDEFINES /variable/CMAKE_AUTOMOC_DEPEND_FILTERS + /variable/CMAKE_AUTOMOC_MACRO_NAMES /variable/CMAKE_AUTOMOC_MOC_OPTIONS + /variable/CMAKE_AUTOMOC_PATH_PREFIX /variable/CMAKE_AUTORCC /variable/CMAKE_AUTORCC_OPTIONS /variable/CMAKE_AUTOUIC /variable/CMAKE_AUTOUIC_OPTIONS /variable/CMAKE_AUTOUIC_SEARCH_PATHS /variable/CMAKE_BUILD_RPATH + /variable/CMAKE_BUILD_RPATH_USE_ORIGIN /variable/CMAKE_BUILD_WITH_INSTALL_NAME_DIR /variable/CMAKE_BUILD_WITH_INSTALL_RPATH /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG /variable/CMAKE_CONFIG_POSTFIX + /variable/CMAKE_CUDA_SEPARABLE_COMPILATION + /variable/CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS /variable/CMAKE_DEBUG_POSTFIX + /variable/CMAKE_DISABLE_PRECOMPILE_HEADERS /variable/CMAKE_ENABLE_EXPORTS /variable/CMAKE_EXE_LINKER_FLAGS /variable/CMAKE_EXE_LINKER_FLAGS_CONFIG /variable/CMAKE_EXE_LINKER_FLAGS_CONFIG_INIT /variable/CMAKE_EXE_LINKER_FLAGS_INIT + /variable/CMAKE_FOLDER + /variable/CMAKE_FRAMEWORK /variable/CMAKE_Fortran_FORMAT /variable/CMAKE_Fortran_MODULE_DIRECTORY + /variable/CMAKE_GHS_NO_SOURCE_GROUP_FILE + /variable/CMAKE_GLOBAL_AUTOGEN_TARGET + /variable/CMAKE_GLOBAL_AUTOGEN_TARGET_NAME + /variable/CMAKE_GLOBAL_AUTORCC_TARGET + /variable/CMAKE_GLOBAL_AUTORCC_TARGET_NAME /variable/CMAKE_GNUtoMS /variable/CMAKE_INCLUDE_CURRENT_DIR /variable/CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE /variable/CMAKE_INSTALL_NAME_DIR + /variable/CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH /variable/CMAKE_INSTALL_RPATH /variable/CMAKE_INSTALL_RPATH_USE_LINK_PATH /variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION @@ -300,8 +387,11 @@ Variables that Control the Build /variable/CMAKE_IOS_INSTALL_COMBINED /variable/CMAKE_LANG_CLANG_TIDY /variable/CMAKE_LANG_COMPILER_LAUNCHER + /variable/CMAKE_LANG_CPPCHECK /variable/CMAKE_LANG_CPPLINT /variable/CMAKE_LANG_INCLUDE_WHAT_YOU_USE + /variable/CMAKE_LANG_LINK_LIBRARY_FILE_FLAG + /variable/CMAKE_LANG_LINK_LIBRARY_FLAG /variable/CMAKE_LANG_VISIBILITY_PRESET /variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY /variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY_CONFIG @@ -319,6 +409,8 @@ Variables that Control the Build /variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG /variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG_INIT /variable/CMAKE_MODULE_LINKER_FLAGS_INIT + /variable/CMAKE_MSVCIDE_RUN_PATH + /variable/CMAKE_MSVC_RUNTIME_LIBRARY /variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX /variable/CMAKE_NO_BUILTIN_CHRPATH /variable/CMAKE_NO_SYSTEM_FROM_IMPORTED @@ -343,10 +435,22 @@ Variables that Control the Build /variable/CMAKE_TRY_COMPILE_CONFIGURATION /variable/CMAKE_TRY_COMPILE_PLATFORM_VARIABLES /variable/CMAKE_TRY_COMPILE_TARGET_TYPE + /variable/CMAKE_UNITY_BUILD + /variable/CMAKE_UNITY_BUILD_BATCH_SIZE /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_JUST_MY_CODE_DEBUGGING + /variable/CMAKE_VS_SDK_EXCLUDE_DIRECTORIES + /variable/CMAKE_VS_SDK_EXECUTABLE_DIRECTORIES + /variable/CMAKE_VS_SDK_INCLUDE_DIRECTORIES + /variable/CMAKE_VS_SDK_LIBRARY_DIRECTORIES + /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 @@ -362,6 +466,7 @@ Variables for Languages /variable/CMAKE_COMPILER_IS_GNUCC /variable/CMAKE_COMPILER_IS_GNUCXX /variable/CMAKE_COMPILER_IS_GNUG77 + /variable/CMAKE_CUDA_HOST_COMPILER /variable/CMAKE_CUDA_EXTENSIONS /variable/CMAKE_CUDA_STANDARD /variable/CMAKE_CUDA_STANDARD_REQUIRED @@ -377,7 +482,6 @@ Variables for Languages /variable/CMAKE_Fortran_MODDIR_DEFAULT /variable/CMAKE_Fortran_MODDIR_FLAG /variable/CMAKE_Fortran_MODOUT_FLAG - /variable/CMAKE_INTERNAL_PLATFORM_ABI /variable/CMAKE_LANG_ANDROID_TOOLCHAIN_MACHINE /variable/CMAKE_LANG_ANDROID_TOOLCHAIN_PREFIX /variable/CMAKE_LANG_ANDROID_TOOLCHAIN_SUFFIX @@ -385,10 +489,10 @@ Variables for Languages /variable/CMAKE_LANG_ARCHIVE_CREATE /variable/CMAKE_LANG_ARCHIVE_FINISH /variable/CMAKE_LANG_COMPILER - /variable/CMAKE_LANG_COMPILER_ABI /variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN /variable/CMAKE_LANG_COMPILER_ID /variable/CMAKE_LANG_COMPILER_LOADED + /variable/CMAKE_LANG_COMPILER_PREDEFINES_COMMAND /variable/CMAKE_LANG_COMPILER_TARGET /variable/CMAKE_LANG_COMPILER_VERSION /variable/CMAKE_LANG_COMPILE_OBJECT @@ -396,6 +500,8 @@ Variables for Languages /variable/CMAKE_LANG_CREATE_SHARED_MODULE /variable/CMAKE_LANG_CREATE_STATIC_LIBRARY /variable/CMAKE_LANG_FLAGS + /variable/CMAKE_LANG_FLAGS_CONFIG + /variable/CMAKE_LANG_FLAGS_CONFIG_INIT /variable/CMAKE_LANG_FLAGS_DEBUG /variable/CMAKE_LANG_FLAGS_DEBUG_INIT /variable/CMAKE_LANG_FLAGS_INIT @@ -405,10 +511,6 @@ Variables for Languages /variable/CMAKE_LANG_FLAGS_RELEASE_INIT /variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO /variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT - /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_DEBUG - /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_MINSIZEREL - /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELEASE - /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELWITHDEBINFO /variable/CMAKE_LANG_IGNORE_EXTENSIONS /variable/CMAKE_LANG_IMPLICIT_INCLUDE_DIRECTORIES /variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES @@ -417,15 +519,22 @@ 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 /variable/CMAKE_LANG_SIMULATE_ID /variable/CMAKE_LANG_SIMULATE_VERSION /variable/CMAKE_LANG_SIZEOF_DATA_PTR /variable/CMAKE_LANG_SOURCE_FILE_EXTENSIONS /variable/CMAKE_LANG_STANDARD_INCLUDE_DIRECTORIES /variable/CMAKE_LANG_STANDARD_LIBRARIES + /variable/CMAKE_OBJC_EXTENSIONS + /variable/CMAKE_OBJC_STANDARD + /variable/CMAKE_OBJC_STANDARD_REQUIRED + /variable/CMAKE_OBJCXX_EXTENSIONS + /variable/CMAKE_OBJCXX_STANDARD + /variable/CMAKE_OBJCXX_STANDARD_REQUIRED /variable/CMAKE_Swift_LANGUAGE_VERSION /variable/CMAKE_USER_MAKE_RULES_OVERRIDE_LANG @@ -461,7 +570,7 @@ Variables for CTest /variable/CTEST_CUSTOM_POST_TEST /variable/CTEST_CUSTOM_PRE_MEMCHECK /variable/CTEST_CUSTOM_PRE_TEST - /variable/CTEST_CUSTOM_TEST_IGNORE + /variable/CTEST_CUSTOM_TESTS_IGNORE /variable/CTEST_CUSTOM_WARNING_EXCEPTION /variable/CTEST_CUSTOM_WARNING_MATCH /variable/CTEST_CVS_CHECKOUT @@ -480,6 +589,7 @@ Variables for CTest /variable/CTEST_GIT_UPDATE_OPTIONS /variable/CTEST_HG_COMMAND /variable/CTEST_HG_UPDATE_OPTIONS + /variable/CTEST_LABELS_FOR_SUBPROJECTS /variable/CTEST_MEMORYCHECK_COMMAND /variable/CTEST_MEMORYCHECK_COMMAND_OPTIONS /variable/CTEST_MEMORYCHECK_SANITIZER_OPTIONS @@ -490,8 +600,10 @@ Variables for CTest /variable/CTEST_P4_COMMAND /variable/CTEST_P4_OPTIONS /variable/CTEST_P4_UPDATE_OPTIONS + /variable/CTEST_RUN_CURRENT_SCRIPT /variable/CTEST_SCP_COMMAND /variable/CTEST_SITE + /variable/CTEST_SUBMIT_URL /variable/CTEST_SOURCE_DIRECTORY /variable/CTEST_SVN_COMMAND /variable/CTEST_SVN_OPTIONS @@ -502,6 +614,7 @@ Variables for CTest /variable/CTEST_UPDATE_COMMAND /variable/CTEST_UPDATE_OPTIONS /variable/CTEST_UPDATE_VERSION_ONLY + /variable/CTEST_UPDATE_VERSION_OVERRIDE /variable/CTEST_USE_LAUNCHERS Variables for CPack @@ -514,7 +627,36 @@ Variables for CPack /variable/CPACK_COMPONENT_INCLUDE_TOPLEVEL_DIRECTORY /variable/CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION /variable/CPACK_INCLUDE_TOPLEVEL_DIRECTORY - /variable/CPACK_INSTALL_SCRIPT + /variable/CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS /variable/CPACK_PACKAGING_INSTALL_PREFIX /variable/CPACK_SET_DESTDIR /variable/CPACK_WARN_ON_ABSOLUTE_INSTALL_DESTINATION + +Variable Expansion Operators +============================ + +.. toctree:: + :maxdepth: 1 + + /variable/CACHE + /variable/ENV + +Internal Variables +================== + +CMake has many internal variables. Most of them are undocumented. +Some of them, however, were at some point described as normal +variables, and therefore may be encountered in legacy code. They +are subject to change, and not recommended for use in project code. + +.. toctree:: + :maxdepth: 1 + + /variable/CMAKE_HOME_DIRECTORY + /variable/CMAKE_INTERNAL_PLATFORM_ABI + /variable/CMAKE_LANG_COMPILER_ABI + /variable/CMAKE_LANG_COMPILER_ARCHITECTURE_ID + /variable/CMAKE_LANG_COMPILER_VERSION_INTERNAL + /variable/CMAKE_LANG_PLATFORM_ID + /variable/CMAKE_NOT_USING_CONFIG_FLAGS + /variable/CMAKE_VS_INTEL_Fortran_PROJECT_VERSION diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index ba925e8ec..4ab55a0d0 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -8,72 +8,190 @@ Synopsis .. parsed-literal:: - cmake [<options>] (<path-to-source> | <path-to-existing-build>) - cmake [(-D <var>=<value>)...] -P <cmake-script-file> - cmake --build <dir> [<options>...] [-- <build-tool-options>...] - cmake -E <command> [<options>...] - cmake --find-package <options>... + `Generate a Project Buildsystem`_ + cmake [<options>] <path-to-source> + cmake [<options>] <path-to-existing-build> + cmake [<options>] -S <path-to-source> -B <path-to-build> + + `Build a Project`_ + cmake --build <dir> [<options>] [-- <build-tool-options>] + + `Install a Project`_ + cmake --install <dir> [<options>] + + `Open a Project`_ + cmake --open <dir> + + `Run a Script`_ + cmake [{-D <var>=<value>}...] -P <cmake-script-file> + + `Run a Command-Line Tool`_ + cmake -E <command> [<options>] + + `Run the Find-Package Tool`_ + cmake --find-package [<options>] + + `View Help`_ + cmake --help[-<topic>] Description =========== -The "cmake" executable is the CMake command-line interface. It may be -used to configure projects in scripts. Project configuration settings -may be specified on the command line with the -D option. +The **cmake** executable is the command-line interface of the cross-platform +buildsystem generator CMake. The above `Synopsis`_ lists various actions +the tool can perform as described in sections below. + +To build a software project with CMake, `Generate a Project Buildsystem`_. +Optionally use **cmake** to `Build a Project`_, `Install a Project`_ or just +run the corresponding build tool (e.g. ``make``) directly. **cmake** can also +be used to `View Help`_. + +The other actions are meant for use by software developers writing +scripts in the :manual:`CMake language <cmake-language(7)>` to support +their builds. + +For graphical user interfaces that may be used in place of **cmake**, +see :manual:`ccmake <ccmake(1)>` and :manual:`cmake-gui <cmake-gui(1)>`. +For command-line interfaces to the CMake testing and packaging facilities, +see :manual:`ctest <ctest(1)>` and :manual:`cpack <cpack(1)>`. + +For more information on CMake at large, `see also`_ the links at the end +of this manual. + + +Introduction to CMake Buildsystems +================================== + +A *buildsystem* describes how to build a project's executables and libraries +from its source code using a *build tool* to automate the process. For +example, a buildsystem may be a ``Makefile`` for use with a command-line +``make`` tool or a project file for an Integrated Development Environment +(IDE). In order to avoid maintaining multiple such buildsystems, a project +may specify its buildsystem abstractly using files written in the +:manual:`CMake language <cmake-language(7)>`. From these files CMake +generates a preferred buildsystem locally for each user through a backend +called a *generator*. + +To generate a buildsystem with CMake, the following must be selected: + +Source Tree + The top-level directory containing source files provided by the project. + The project specifies its buildsystem using files as described in the + :manual:`cmake-language(7)` manual, starting with a top-level file named + ``CMakeLists.txt``. These files specify build targets and their + dependencies as described in the :manual:`cmake-buildsystem(7)` manual. + +Build Tree + The top-level directory in which buildsystem files and build output + artifacts (e.g. executables and libraries) are to be stored. + CMake will write a ``CMakeCache.txt`` file to identify the directory + as a build tree and store persistent information such as buildsystem + configuration options. + + To maintain a pristine source tree, perform an *out-of-source* build + by using a separate dedicated build tree. An *in-source* build in + which the build tree is placed in the same directory as the source + tree is also supported, but discouraged. + +Generator + This chooses the kind of buildsystem to generate. See the + :manual:`cmake-generators(7)` manual for documentation of all generators. + Run ``cmake --help`` to see a list of generators available locally. + Optionally use the ``-G`` option below to specify a generator, or simply + accept the default CMake chooses for the current platform. + + When using one of the :ref:`Command-Line Build Tool Generators` + CMake expects that the environment needed by the compiler toolchain + is already configured in the shell. When using one of the + :ref:`IDE Build Tool Generators`, no particular environment is needed. + + +Generate a Project Buildsystem +============================== + +Run CMake with one of the following command signatures to specify the +source and build trees and generate a buildsystem: + +``cmake [<options>] <path-to-source>`` + Uses the current working directory as the build tree, and + ``<path-to-source>`` as the source tree. The specified path may + be absolute or relative to the current working directory. + The source tree must contain a ``CMakeLists.txt`` file and must + *not* contain a ``CMakeCache.txt`` file because the latter + identifies an existing build tree. For example: + + .. code-block:: console + + $ mkdir build ; cd build + $ cmake ../src + +``cmake [<options>] <path-to-existing-build>`` + Uses ``<path-to-existing-build>`` as the build tree, and loads the + path to the source tree from its ``CMakeCache.txt`` file, which must + have already been generated by a previous run of CMake. The specified + path may be absolute or relative to the current working directory. + For example: + + .. code-block:: console + + $ cd build + $ cmake . + +``cmake [<options>] -S <path-to-source> -B <path-to-build>`` + Uses ``<path-to-build>`` as the build tree and ``<path-to-source>`` + as the source tree. The specified paths may be absolute or relative + to the current working directory. The source tree must contain a + ``CMakeLists.txt`` file. The build tree will be created automatically + if it does not already exist. For example: + + .. code-block:: console + + $ cmake -S src -B build + +In all cases the ``<options>`` may be zero or more of the `Options`_ below. -CMake is a cross-platform build system generator. Projects specify -their build process with platform-independent CMake listfiles included -in each directory of a source tree with the name CMakeLists.txt. -Users build a project by using CMake to generate a build system for a -native tool on their platform. +After generating a buildsystem one may use the corresponding native +build tool to build the project. For example, after using the +:generator:`Unix Makefiles` generator one may run ``make`` directly: + + .. code-block:: console + + $ make + $ make install + +Alternatively, one may use **cmake** to `Build a Project`_ by +automatically choosing and invoking the appropriate native build tool. .. _`CMake Options`: Options -======= +------- .. include:: OPTIONS_BUILD.txt -``-E <command> [<options>...]`` - See `Command-Line Tool Mode`_. - ``-L[A][H]`` List non-advanced cached variables. - List cache variables will run CMake and list all the variables from - the CMake cache that are not marked as INTERNAL or ADVANCED. This - will effectively display current CMake settings, which can then be - changed with -D option. Changing some of the variables may result - in more variables being created. If A is specified, then it will - display also advanced variables. If H is specified, it will also + List ``CACHE`` variables will run CMake and list all the variables from + the CMake ``CACHE`` that are not marked as ``INTERNAL`` or :prop_cache:`ADVANCED`. + This will effectively display current CMake settings, which can then be + changed with ``-D`` option. Changing some of the variables may result + in more variables being created. If ``A`` is specified, then it will + display also advanced variables. If ``H`` is specified, it will also display help for each variable. -``--build <dir>`` - See `Build Tool Mode`_. - ``-N`` View mode only. Only load the cache. Do not actually run configure and generate steps. -``-P <file>`` - Process script mode. - - Process the given cmake file as a script written in the CMake - language. No configure or generate step is performed and the cache - is not modified. If variables are defined using -D, this must be - done before the -P argument. - -``--find-package`` - See `Find-Package Tool Mode`_. - ``--graphviz=[file]`` - Generate graphviz of dependencies, see CMakeGraphVizOptions.cmake for more. + Generate graphviz of dependencies, see :module:`CMakeGraphVizOptions` for more. Generate a graphviz input file that will contain all the library and executable dependencies in the project. See the documentation for - CMakeGraphVizOptions.cmake for more details. + :module:`CMakeGraphVizOptions` for more details. ``--system-information [file]`` Dump information about this system. @@ -82,10 +200,20 @@ Options from the top of a binary tree for a CMake project it will dump additional information such as the cache, log files etc. +``--log-level=<ERROR|WARNING|NOTICE|STATUS|VERBOSE|DEBUG|TRACE>`` + Set the log level. + + The :command:`message` command will only output messages of the specified + log level or higher. The default log level is ``STATUS``. + + For backward compatibility reasons, ``--loglevel`` is also accepted as a + synonym for this option. + ``--debug-trycompile`` - Do not delete the try_compile build tree. Only useful on one try_compile at a time. + Do not delete the :command:`try_compile` build tree. + Only useful on one :command:`try_compile` at a time. - Do not delete the files and directories created for try_compile + Do not delete the files and directories created for :command:`try_compile` calls. This is useful in debugging failed try_compiles. It may however change the results of the try-compiles as old junk from a previous try-compile may cause a different test to either pass or @@ -96,7 +224,7 @@ Options Put cmake in a debug mode. Print extra information during the cmake run like stack traces with - message(send_error ) calls. + :command:`message(SEND_ERROR)` calls. ``--trace`` Put cmake in trace mode. @@ -113,6 +241,9 @@ Options Multiple options are allowed. +``--trace-redirect=<file>`` + Put cmake in trace mode and redirect trace output to a file instead of stderr. + ``--warn-uninitialized`` Warn about uninitialized values. @@ -133,18 +264,20 @@ Options Find problems with variable usage in system files. Normally, unused and uninitialized variables are searched for only - in CMAKE_SOURCE_DIR and CMAKE_BINARY_DIR. This flag tells CMake to - warn about other files as well. + in :variable:`CMAKE_SOURCE_DIR` and :variable:`CMAKE_BINARY_DIR`. + This flag tells CMake to warn about other files as well. -.. include:: OPTIONS_HELP.txt +.. _`Build Tool Mode`: -Build Tool Mode +Build a Project =============== CMake provides a command-line signature to build an already-generated -project binary tree:: +project binary tree: - cmake --build <dir> [<options>...] [-- <build-tool-options>...] +.. code-block:: shell + + cmake --build <dir> [<options>] [-- <build-tool-options>] This abstracts a native build tool's command-line interface with the following options: @@ -152,8 +285,19 @@ following options: ``--build <dir>`` Project binary directory to be built. This is required and must be first. -``--target <tgt>`` - Build ``<tgt>`` instead of default targets. May only be specified once. +``--parallel [<jobs>], -j [<jobs>]`` + The maximum number of concurrent processes to use when building. + If ``<jobs>`` is omitted the native build tool's default number is used. + + The :envvar:`CMAKE_BUILD_PARALLEL_LEVEL` environment variable, if set, + specifies a default parallel level when this option is not given. + + Some native build tools always build in parallel. The use of ``<jobs>`` + value of ``1`` can be used to limit to a single job. + +``--target <tgt>..., -t <tgt>...`` + Build ``<tgt>`` instead of the default target. Multiple targets may be + given, separated by spaces. ``--config <cfg>`` For multi-configuration tools, choose configuration ``<cfg>``. @@ -165,17 +309,89 @@ following options: ``--use-stderr`` Ignored. Behavior is default in CMake >= 3.0. +``--verbose, -v`` + Enable verbose output - if supported - including the build commands to be + executed. + + This option can be omitted if :envvar:`VERBOSE` environment variable or + :variable:`CMAKE_VERBOSE_MAKEFILE` cached variable is set. + + ``--`` Pass remaining options to the native tool. Run ``cmake --build`` with no options for quick help. -Command-Line Tool Mode -====================== +Install a Project +================= + +CMake provides a command-line signature to install an already-generated +project binary tree: + +.. code-block:: shell + + cmake --install <dir> [<options>] + +This may be used after building a project to run installation without +using the generated build system or the native build tool. +The options are: + +``--install <dir>`` + Project binary directory to install. This is required and must be first. + +``--config <cfg>`` + For multi-configuration generators, choose configuration ``<cfg>``. + +``--component <comp>`` + Component-based install. Only install component ``<comp>``. + +``--prefix <prefix>`` + Override the installation prefix, :variable:`CMAKE_INSTALL_PREFIX`. + +``--strip`` + Strip before installing. -CMake provides builtin command-line tools through the signature:: +``-v, --verbose`` + Enable verbose output. - cmake -E <command> [<options>...] + This option can be omitted if :envvar:`VERBOSE` environment variable is set. + +Run ``cmake --install`` with no options for quick help. + +Open a Project +============== + +.. code-block:: shell + + cmake --open <dir> + +Open the generated project in the associated application. This is only +supported by some generators. + + +.. _`Script Processing Mode`: + +Run a Script +============ + +.. code-block:: shell + + cmake [{-D <var>=<value>}...] -P <cmake-script-file> + +Process the given cmake file as a script written in the CMake +language. No configure or generate step is performed and the cache +is not modified. If variables are defined using ``-D``, this must be +done before the ``-P`` argument. + + +Run a Command-Line Tool +======================= + +CMake provides builtin command-line tools through the signature + +.. code-block:: shell + + cmake -E <command> [<options>] Run ``cmake -E`` or ``cmake -E help`` for a summary of commands. Available commands are: @@ -214,30 +430,57 @@ Available commands are: A list of strings with all the extra generators compatible with the generator. + ``fileApi`` + Optional member that is present when the :manual:`cmake-file-api(7)` + is available. The value is a JSON object with one member: + + ``requests`` + A JSON array containing zero or more supported file-api requests. + Each request is a JSON object with members: + + ``kind`` + Specifies one of the supported :ref:`file-api object kinds`. + + ``version`` + A JSON array whose elements are each a JSON object containing + ``major`` and ``minor`` members specifying non-negative integer + version components. + ``serverMode`` ``true`` if cmake supports server-mode and ``false`` otherwise. ``chdir <dir> <cmd> [<arg>...]`` Change the current working directory and run a command. -``compare_files <file1> <file2>`` +``compare_files [--ignore-eol] <file1> <file2>`` Check if ``<file1>`` is same as ``<file2>``. If files are the same, - then returns 0, if not it returns 1. + then returns ``0``, if not it returns ``1``. The ``--ignore-eol`` option + implies line-wise comparison and ignores LF/CRLF differences. ``copy <file>... <destination>`` Copy files to ``<destination>`` (either file or directory). If multiple files are specified, the ``<destination>`` must be directory and it must exist. Wildcards are not supported. + ``copy`` does follow symlinks. That means it does not copy symlinks, + but the files or directories it point to. ``copy_directory <dir>... <destination>`` - Copy directories to ``<destination>`` directory. + Copy content of ``<dir>...`` directories to ``<destination>`` directory. If ``<destination>`` directory does not exist it will be created. + ``copy_directory`` does follow symlinks. ``copy_if_different <file>... <destination>`` Copy files to ``<destination>`` (either file or directory) if they have changed. If multiple files are specified, the ``<destination>`` must be directory and it must exist. + ``copy_if_different`` does follow symlinks. + +``create_symlink <old> <new>`` + Create a symbolic link ``<new>`` naming ``<old>``. + + .. note:: + Path to where ``<new>`` symbolic link will be created has to exist beforehand. ``echo [<string>...]`` Displays arguments as text. @@ -251,6 +494,9 @@ Available commands are: ``environment`` Display the current environment variables. +``false`` + Do nothing, with an exit code of 1. + ``make_directory <dir>...`` Create ``<dir>`` directories. If necessary, create parent directories too. If a directory already exists it will be @@ -262,18 +508,52 @@ Available commands are: 351abe79cd3800b38cdfb25d45015a15 file1.txt 052f86c15bbde68af55c7f7b340ab639 file2.txt +``sha1sum <file>...`` + Create SHA1 checksum of files in ``sha1sum`` compatible format:: + + 4bb7932a29e6f73c97bb9272f2bdc393122f86e0 file1.txt + 1df4c8f318665f9a5f2ed38f55adadb7ef9f559c file2.txt + +``sha224sum <file>...`` + Create SHA224 checksum of files in ``sha224sum`` compatible format:: + + b9b9346bc8437bbda630b0b7ddfc5ea9ca157546dbbf4c613192f930 file1.txt + 6dfbe55f4d2edc5fe5c9197bca51ceaaf824e48eba0cc453088aee24 file2.txt + +``sha256sum <file>...`` + Create SHA256 checksum of files in ``sha256sum`` compatible format:: + + 76713b23615d31680afeb0e9efe94d47d3d4229191198bb46d7485f9cb191acc file1.txt + 15b682ead6c12dedb1baf91231e1e89cfc7974b3787c1e2e01b986bffadae0ea file2.txt + +``sha384sum <file>...`` + Create SHA384 checksum of files in ``sha384sum`` compatible format:: + + acc049fedc091a22f5f2ce39a43b9057fd93c910e9afd76a6411a28a8f2b8a12c73d7129e292f94fc0329c309df49434 file1.txt + 668ddeb108710d271ee21c0f3acbd6a7517e2b78f9181c6a2ff3b8943af92b0195dcb7cce48aa3e17893173c0a39e23d file2.txt + +``sha512sum <file>...`` + Create SHA512 checksum of files in ``sha512sum`` compatible format:: + + 2a78d7a6c5328cfb1467c63beac8ff21794213901eaadafd48e7800289afbc08e5fb3e86aa31116c945ee3d7bf2a6194489ec6101051083d1108defc8e1dba89 file1.txt + 7a0b54896fe5e70cca6dd643ad6f672614b189bf26f8153061c4d219474b05dad08c4e729af9f4b009f1a1a280cb625454bf587c690f4617c27e3aebdf3b7a2d file2.txt + ``remove [-f] <file>...`` Remove the file(s). If any of the listed files already do not exist, the command returns a non-zero exit code, but no message is logged. The ``-f`` option changes the behavior to return a zero exit code (i.e. success) in such situations instead. + ``remove`` does not follow symlinks. That means it remove only symlinks + and not files it point to. -``remove_directory <dir>`` - Remove a directory and its contents. If a directory does - not exist it will be silently ignored. +``remove_directory <dir>...`` + Remove ``<dir>`` directories and their contents. If a directory does + not exist it will be silently ignored. If ``<dir>`` is a symlink to + a directory, just the symlink will be removed. ``rename <oldname> <newname>`` - Rename a file or directory (on one volume). + Rename a file or directory (on one volume). If file with the ``<newname>`` name + already exists, then it will be silently replaced. ``server`` Launch :manual:`cmake-server(7)` mode. @@ -281,44 +561,61 @@ Available commands are: ``sleep <number>...`` Sleep for given number of seconds. -``tar [cxt][vf][zjJ] file.tar [<options>...] [--] [<file>...]`` +``tar [cxt][vf][zjJ] file.tar [<options>] [--] [<pathname>...]`` Create or extract a tar or zip archive. Options are: - ``--`` - Stop interpreting options and treat all remaining arguments - as file names even if they start in ``-``. + ``c`` + Create a new archive containing the specified files. + If used, the ``<pathname>...`` argument is mandatory. + ``x`` + Extract to disk from the archive. + The ``<pathname>...`` argument could be used to extract only selected files + or directories. + When extracting selected files or directories, you must provide their exact + names including the path, as printed by list (``-t``). + ``t`` + List archive contents. + The ``<pathname>...`` argument could be used to list only selected files + or directories. + ``v`` + Produce verbose output. + ``z`` + Compress the resulting archive with gzip. + ``j`` + Compress the resulting archive with bzip2. + ``J`` + Compress the resulting archive with XZ. + ``--zstd`` + Compress the resulting archive with Zstandard. ``--files-from=<file>`` Read file names from the given file, one per line. Blank lines are ignored. Lines may not start in ``-`` except for ``--add-file=<name>`` to add files whose names start in ``-``. - ``--mtime=<date>`` - Specify modification time recorded in tarball entries. ``--format=<format>`` Specify the format of the archive to be created. Supported formats are: ``7zip``, ``gnutar``, ``pax``, ``paxr`` (restricted pax, default), and ``zip``. + ``--mtime=<date>`` + Specify modification time recorded in tarball entries. + ``--`` + Stop interpreting options and treat all remaining arguments + as file names, even if they start with ``-``. + ``time <command> [<args>...]`` - Run command and return elapsed time. + Run command and display elapsed time. -``touch <file>`` - Touch a file. +``touch <file>...`` + Creates ``<file>`` if file do not exist. + If ``<file>`` exists, it is changing ``<file>`` access and modification times. -``touch_nocreate <file>`` +``touch_nocreate <file>...`` 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>``. - -.. note:: - Path to where ``<new>`` symbolic link will be created has to exist beforehand. +``true`` + Do nothing, with an exit code of 0. Windows-specific Command-Line Tools ----------------------------------- @@ -339,24 +636,40 @@ The following ``cmake -E`` commands are available only on Windows: ``write_regv <key> <value>`` Write Windows registry value. -Find-Package Tool Mode -====================== -CMake provides a helper for Makefile-based projects with the signature:: +Run the Find-Package Tool +========================= + +CMake provides a pkg-config like helper for Makefile-based projects: - cmake --find-package <options>... +.. code-block:: shell -This runs in a pkg-config like mode. + cmake --find-package [<options>] -Search a package using :command:`find_package()` and print the resulting flags -to stdout. This can be used to use cmake instead of pkg-config to find -installed libraries in plain Makefile-based projects or in autoconf-based -projects (via ``share/aclocal/cmake.m4``). +It searches a package using :command:`find_package()` and prints the +resulting flags to stdout. This can be used instead of pkg-config +to find installed libraries in plain Makefile-based projects or in +autoconf-based projects (via ``share/aclocal/cmake.m4``). .. note:: This mode is not well-supported due to some technical limitations. It is kept for compatibility but should not be used in new projects. + +View Help +========= + +To print selected pages from the CMake documentation, use + +.. code-block:: shell + + cmake --help[-<topic>] + +with one of the following options: + +.. include:: OPTIONS_HELP.txt + + See Also ======== diff --git a/Help/manual/cpack-generators.7.rst b/Help/manual/cpack-generators.7.rst new file mode 100644 index 000000000..ade9149c1 --- /dev/null +++ b/Help/manual/cpack-generators.7.rst @@ -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 diff --git a/Help/manual/cpack.1.rst b/Help/manual/cpack.1.rst index 4f9f28d4e..395cd4189 100644 --- a/Help/manual/cpack.1.rst +++ b/Help/manual/cpack.1.rst @@ -8,86 +8,102 @@ Synopsis .. parsed-literal:: - cpack -G <generator> [<options>] + cpack [<options>] Description =========== -The "cpack" executable is the CMake packaging program. -CMake-generated build trees created for projects that use the -INSTALL_* commands have packaging support. This program will generate -the package. +The **cpack** executable is the CMake packaging program. It generates +installers and source packages in a variety of formats. -CMake is a cross-platform build system generator. Projects specify -their build process with platform-independent CMake listfiles included -in each directory of a source tree with the name CMakeLists.txt. -Users build a project by using CMake to generate a build system for a -native tool on their platform. +For each installer or package format, **cpack** has a specific backend, +called "generator". A generator is responsible for generating the required +inputs and invoking the specific package creation tools. These installer +or package generators are not to be confused with the makefile generators +of the :manual:`cmake <cmake(1)>` command. -Options -======= +All supported generators are specified in the :manual:`cpack-generators +<cpack-generators(7)>` manual. The command ``cpack --help`` prints a +list of generators supported for the target platform. Which of them are +to be used can be selected through the :variable:`CPACK_GENERATOR` variable +or through the command-line option ``-G``. -``-G <generator>`` - Use the specified generator to generate package. +The **cpack** program is steered by a configuration file written in the +:manual:`CMake language <cmake-language(7)>`. Unless chosen differently +through the command-line option ``--config``, the file ``CPackConfig.cmake`` +in the current directory is used. - CPack may support multiple native packaging systems on certain - platforms. A generator is responsible for generating input files - for particular system and invoking that systems. Possible generator - names are specified in the Generators section. +In the standard CMake workflow, the file ``CPackConfig.cmake`` is generated +by the :manual:`cmake <cmake(1)>` executable, provided the :module:`CPack` +module is included by the project's ``CMakeLists.txt`` file. -``-C <Configuration>`` - Specify the project configuration +Options +======= - This option specifies the configuration that the project was build - with, for example 'Debug', 'Release'. +``-G <generators>`` + ``<generators>`` is a :ref:`semicolon-separated list <CMake Language Lists>` + of generator names. ``cpack`` will iterate through this list and produce + package(s) in that generator's format according to the details provided in + the ``CPackConfig.cmake`` configuration file. If this option is not given, + the :variable:`CPACK_GENERATOR` variable determines the default set of + generators that will be used. + +``-C <configs>`` + Specify the project configuration(s) to be packaged (e.g. ``Debug``, + ``Release``, etc.), where ``<configs>`` is a + :ref:`semicolon-separated list <CMake Language Lists>`. + When the CMake project uses a multi-configuration + generator such as Xcode or Visual Studio, this option is needed to tell + ``cpack`` which built executables to include in the package. + The user is responsible for ensuring that the configuration(s) listed + have already been built before invoking ``cpack``. ``-D <var>=<value>`` - Set a CPack variable. + Set a CPack variable. This will override any value set for ``<var>`` in the + input file read by ``cpack``. - Set a variable that can be used by the generator. +``--config <configFile>`` + Specify the configuration file read by ``cpack`` to provide the packaging + details. By default, ``CPackConfig.cmake`` in the current directory will + be used. -``--config <config file>`` - Specify the config file. - - Specify the config file to use to create the package. By default - CPackConfig.cmake in the current directory will be used. - -``--verbose,-V`` - enable verbose output - - Run cpack with verbose output. +``--verbose, -V`` + Run ``cpack`` with verbose output. This can be used to show more details + from the package generation tools and is suitable for project developers. ``--debug`` - enable debug output (for CPack developers) - - Run cpack with debug output (for CPack developers). - -``-P <package name>`` - override/define CPACK_PACKAGE_NAME - - If the package name is not specified on cpack command line - thenCPack.cmake defines it as CMAKE_PROJECT_NAME - -``-R <package version>`` - override/define CPACK_PACKAGE_VERSION - - If version is not specified on cpack command line thenCPack.cmake - defines it from CPACK_PACKAGE_VERSION_[MAJOR|MINOR|PATCH]look into - CPack.cmake for detail - -``-B <package directory>`` - override/define CPACK_PACKAGE_DIRECTORY - - The directory where CPack will be doing its packaging work.The - resulting package will be found there. Inside this directoryCPack - creates '_CPack_Packages' sub-directory which is theCPack temporary - directory. - -``--vendor <vendor name>`` - override/define CPACK_PACKAGE_VENDOR - - If vendor is not specified on cpack command line (or inside - CMakeLists.txt) thenCPack.cmake defines it with a default value + Run ``cpack`` with debug output. This option is intended mainly for the + developers of ``cpack`` itself and is not normally needed by project + developers. + +``--trace`` + Put the underlying cmake scripts in trace mode. + +``--trace-expand`` + Put the underlying cmake scripts in expanded trace mode. + +``-P <packageName>`` + Override/define the value of the :variable:`CPACK_PACKAGE_NAME` variable used + for packaging. Any value set for this variable in the ``CPackConfig.cmake`` + file will then be ignored. + +``-R <packageVersion>`` + Override/define the value of the :variable:`CPACK_PACKAGE_VERSION` + variable used for packaging. It will override a value set in the + ``CPackConfig.cmake`` file or one automatically computed from + :variable:`CPACK_PACKAGE_VERSION_MAJOR`, + :variable:`CPACK_PACKAGE_VERSION_MINOR` and + :variable:`CPACK_PACKAGE_VERSION_PATCH`. + +``-B <packageDirectory>`` + Override/define :variable:`CPACK_PACKAGE_DIRECTORY`, which controls the + directory where CPack will perform its packaging work. The resultant + package(s) will be created at this location by default and a + ``_CPack_Packages`` subdirectory will also be created below this directory to + use as a working area during package creation. + +``--vendor <vendorName>`` + Override/define :variable:`CPACK_PACKAGE_VENDOR`. .. include:: OPTIONS_HELP.txt diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index a89c4e9bb..e29ebcaf6 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -3,20 +3,27 @@ ctest(1) ******** +.. contents:: + Synopsis ======== .. parsed-literal:: ctest [<options>] + ctest --build-and-test <path-to-source> <path-to-build> + --build-generator <generator> [<options>...] + [--build-options <opts>...] [--test-command <command> [<args>...]] + ctest {-D <dashboard> | -M <model> -T <action> | -S <script> | -SP <script>} + [-- <dashboard-options>...] Description =========== -The "ctest" executable is the CMake test driver program. +The **ctest** executable is the CMake test driver program. CMake-generated build trees created for projects that use the -ENABLE_TESTING and ADD_TEST commands have testing support. This -program will run the tests and report results. +:command:`enable_testing` and :command:`add_test` commands have testing support. +This program will run the tests and report results. Options ======= @@ -26,8 +33,21 @@ Options Some CMake-generated build trees can have multiple build configurations in the same tree. This option can be used to specify - which one should be tested. Example configurations are "Debug" and - "Release". + 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. @@ -49,22 +69,35 @@ 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. - This option allows ctest to resume a test set execution that was + This option allows CTest to resume a test set execution that was previously interrupted. If no interruption occurred, the ``-F`` option will have no effect. ``-j <jobs>, --parallel <jobs>`` Run the tests in parallel using the given number of jobs. - 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``. + This option tells CTest to run the tests in parallel using given + number of jobs. This option can also be set by setting the + :envvar:`CTEST_PARALLEL_LEVEL` environment variable. + + This option can be used with the :prop_test:`PROCESSORS` test property. + + See `Label and Subproject Summary`_. + +``--resource-spec-file <file>`` + Run CTest with :ref:`resource allocation <ctest-resource-allocation>` enabled, + using the + :ref:`resource specification file <ctest-resource-specification-file>` + specified in ``<file>``. + + When ``ctest`` is run as a `Dashboard Client`_ this sets the + ``ResourceSpecFile`` option of the `CTest Test Step`_. ``--test-load <level>`` While running tests in parallel (e.g. with ``-j``), try not to start @@ -74,7 +107,7 @@ Options ``TestLoad`` option of the `CTest Test Step`_. ``-Q,--quiet`` - Make ctest quiet. + Make CTest quiet. This option will suppress all the output. The output log file will still be generated if the ``--output-log`` is specified. Options such @@ -84,37 +117,47 @@ Options ``-O <file>, --output-log <file>`` Output to log file. - This option tells ctest to write all its output to a log file. + This option tells CTest to write all its output to a ``<file>`` log file. -``-N,--show-only`` +``-N,--show-only[=<format>]`` Disable actual execution of tests. - This option tells ctest to list the tests that would be run but not + This option tells CTest to list the tests that would be run but not actually run them. Useful in conjunction with the ``-R`` and ``-E`` options. + ``<format>`` can be one of the following values. + + ``human`` + Human-friendly output. This is not guaranteed to be stable. + This is the default. + + ``json-v1`` + Dump the test information in JSON format. + See `Show as JSON Object Model`_. + ``-L <regex>, --label-regex <regex>`` Run tests with labels matching regular expression. - This option tells ctest to run only the tests whose labels match the + This option tells CTest to run only the tests whose labels match the given regular expression. ``-R <regex>, --tests-regex <regex>`` Run tests matching regular expression. - This option tells ctest to run only the tests whose names match the + This option tells CTest to run only the tests whose names match the given regular expression. ``-E <regex>, --exclude-regex <regex>`` Exclude tests matching regular expression. - This option tells ctest to NOT run the tests whose names match the + This option tells CTest to NOT run the tests whose names match the given regular expression. ``-LE <regex>, --label-exclude <regex>`` Exclude tests with labels matching regular expression. - This option tells ctest to NOT run the tests whose labels match the + This option tells CTest to NOT run the tests whose labels match the given regular expression. ``-FA <regex>, --fixture-exclude-any <regex>`` @@ -137,10 +180,13 @@ Options ``-D <dashboard>, --dashboard <dashboard>`` Execute dashboard test. - This option tells ctest to act as a CDash client and perform a - dashboard test. All tests are <Mode><Test>, where Mode can be - Experimental, Nightly, and Continuous, and Test can be Start, - Update, Configure, Build, Test, Coverage, and Submit. + This option tells CTest to act as a CDash client and perform a + dashboard test. All tests are ``<Mode><Test>``, where ``<Mode>`` can be + ``Experimental``, ``Nightly``, and ``Continuous``, and ``<Test>`` can be + ``Start``, ``Update``, ``Configure``, ``Build``, ``Test``, + ``Coverage``, and ``Submit``. + + See `Dashboard Client`_. ``-D <var>:<type>=<value>`` Define a variable for script mode. @@ -153,35 +199,33 @@ Options ``-M <model>, --test-model <model>`` Sets the model for a dashboard. - This option tells ctest to act as a CDash client where the ``<model>`` + This option tells CTest to act as a CDash client where the ``<model>`` can be ``Experimental``, ``Nightly``, and ``Continuous``. Combining ``-M`` and ``-T`` is similar to ``-D``. + See `Dashboard Client`_. + ``-T <action>, --test-action <action>`` Sets the dashboard action to perform. - This option tells ctest to act as a CDash client and perform some + This option tells CTest to act as a CDash client and perform some action such as ``start``, ``build``, ``test`` etc. See `Dashboard Client Steps`_ for the full list of actions. Combining ``-M`` and ``-T`` is similar to ``-D``. -``--track <track>`` - Specify the track to submit dashboard to - - Submit dashboard to specified track instead of default one. By - default, the dashboard is submitted to Nightly, Experimental, or - Continuous track, but by specifying this option, the track can be - arbitrary. + See `Dashboard Client`_. ``-S <script>, --script <script>`` Execute a dashboard for a configuration. - This option tells ctest to load in a configuration script which sets + This option tells CTest to load in a configuration script which sets a number of parameters such as the binary and source directories. - Then ctest will do what is required to create and run a dashboard. + Then CTest will do what is required to create and run a dashboard. This option basically sets up a dashboard and then runs ``ctest -D`` with the appropriate options. + See `Dashboard Client`_. + ``-SP <script>, --script-new-process <script>`` Execute a dashboard for a configuration. @@ -190,19 +234,15 @@ Options script may modify the environment and you do not want the modified environment to impact other ``-S`` scripts. -``-A <file>, --add-notes <file>`` - Add a notes file with submission. - - This option tells ctest to include a notes file when submitting - dashboard. + See `Dashboard Client`_. ``-I [Start,End,Stride,test#,test#|Test file], --tests-information`` Run a specific number of tests by number. - This option causes ctest to run tests starting at number Start, - ending at number End, and incrementing by Stride. Any additional - numbers after Stride are considered individual test numbers. Start, - End,or stride can be empty. Optionally a file can be given that + This option causes CTest to run tests starting at number ``Start``, + ending at number ``End``, and incrementing by ``Stride``. Any additional + numbers after ``Stride`` are considered individual test numbers. ``Start``, + ``End``, or ``Stride`` can be empty. Optionally a file can be given that contains the same syntax as the command line. ``-U, --union`` @@ -214,11 +254,11 @@ Options ``--rerun-failed`` Run only the tests that failed previously. - This option tells ctest to perform only the tests that failed during - its previous run. When this option is specified, ctest ignores all + This option tells CTest to perform only the tests that failed during + its previous run. When this option is specified, CTest ignores all other options intended to modify the list of tests to run (``-L``, ``-R``, ``-E``, ``-LE``, ``-I``, etc). In the event that CTest runs and no tests - fail, subsequent calls to ctest with the ``--rerun-failed`` option will run + fail, subsequent calls to CTest with the ``--rerun-failed`` option will run the set of tests that most recently failed (if any). ``--repeat-until-fail <n>`` @@ -234,41 +274,154 @@ Options name which can be very annoying. ``--interactive-debug-mode [0|1]`` - Set the interactive mode to 0 or 1. + Set the interactive mode to ``0`` or ``1``. - This option causes ctest to run tests in either an interactive mode + This option causes CTest to run tests in either an interactive mode or a non-interactive mode. On Windows this means that in non-interactive mode, all system debug pop up windows are blocked. - In dashboard mode (Experimental, Nightly, Continuous), the default + In dashboard mode (``Experimental``, ``Nightly``, ``Continuous``), the default is non-interactive. When just running tests not for a dashboard the default is to allow popups and interactive debugging. ``--no-label-summary`` Disable timing summary information for labels. - This option tells ctest not to print summary information for each + This option tells CTest not to print summary information for each label associated with the tests run. If there are no labels on the tests, nothing extra is printed. -``--build-and-test <path-to-source> <path-to-build>`` - Configure, build and run a test. + See `Label and Subproject Summary`_. + +``--no-subproject-summary`` + Disable timing summary information for subprojects. + + This option tells CTest not to print summary information for each + subproject associated with the tests run. If there are no subprojects on the + tests, nothing extra is printed. + + See `Label and Subproject Summary`_. + +``--build-and-test`` +See `Build and Test Mode`_. + +``--test-output-size-passed <size>`` + Limit the output for passed tests to ``<size>`` bytes. + +``--test-output-size-failed <size>`` + Limit the output for failed tests to ``<size>`` bytes. - This option tells ctest to configure (i.e. run cmake on), build, - and or execute a test. The configure and test steps are optional. - The arguments to this command line are the source and binary - directories. - The ``--build-generator`` option *must* be provided to use - ``--build-and-test``. If ``--test-command`` is specified then that will be - run after the build is complete. Other options that affect this - mode are ``--build-target``, ``--build-nocmake``, ``--build-run-dir``, - ``--build-two-config``, ``--build-exe-dir``, - ``--build-project``, ``--build-noclean`` and ``--build-options``. +``--overwrite`` + Overwrite CTest configuration option. + + By default CTest uses configuration options from configuration file. + This option will overwrite the configuration option. + +``--force-new-ctest-process`` + Run child CTest instances as new processes. + + By default CTest will run child CTest instances within the same + process. If this behavior is not desired, this argument will + enforce new processes for child CTest processes. + +``--schedule-random`` + Use a random order for scheduling tests. + + This option will run the tests in a random order. It is commonly + used to detect implicit dependencies in a test suite. + +``--submit-index`` + Legacy option for old Dart2 dashboard server feature. + Do not use. + +``--timeout <seconds>`` + Set the default test timeout. + + This option effectively sets a timeout on all tests that do not + already have a timeout set on them via the :prop_test:`TIMEOUT` + property. + +``--stop-time <time>`` + Set a time at which all tests should stop running. + + Set a real time of day at which all tests should timeout. Example: + ``7:00:00 -0400``. Any time format understood by the curl date parser + is accepted. Local time is assumed if no timezone is specified. + +``--print-labels`` + Print all available test labels. + + This option will not run any tests, it will simply print the list of + all labels associated with the test set. + +.. include:: OPTIONS_HELP.txt + +.. _`Label and Subproject Summary`: + +Label and Subproject Summary +============================ + +CTest prints timing summary information for each ``LABEL`` and subproject +associated with the tests run. The label time summary will not include labels +that are mapped to subprojects. + +When the :prop_test:`PROCESSORS` test property is set, CTest will display a +weighted test timing result in label and subproject summaries. The time is +reported with `sec*proc` instead of just `sec`. + +The weighted time summary reported for each label or subproject ``j`` +is computed as:: + + Weighted Time Summary for Label/Subproject j = + sum(raw_test_time[j,i] * num_processors[j,i], i=1...num_tests[j]) + + for labels/subprojects j=1...total + +where: + +* ``raw_test_time[j,i]``: Wall-clock time for the ``i`` test + for the ``j`` label or subproject +* ``num_processors[j,i]``: Value of the CTest :prop_test:`PROCESSORS` property + for the ``i`` test for the ``j`` label or subproject +* ``num_tests[j]``: Number of tests associated with the ``j`` label or subproject +* ``total``: Total number of labels or subprojects that have at least one test run + +Therefore, the weighted time summary for each label or subproject represents +the amount of time that CTest gave to run the tests for each label or +subproject and gives a good representation of the total expense of the tests +for each label or subproject when compared to other labels or subprojects. + +For example, if ``SubprojectA`` showed ``100 sec*proc`` and ``SubprojectB`` showed +``10 sec*proc``, then CTest allocated approximately 10 times the CPU/core time +to run the tests for ``SubprojectA`` than for ``SubprojectB`` (e.g. so if effort +is going to be expended to reduce the cost of the test suite for the whole +project, then reducing the cost of the test suite for ``SubprojectA`` would +likely have a larger impact than effort to reduce the cost of the test suite +for ``SubprojectB``). + +.. _`Build and Test Mode`: + +Build and Test Mode +=================== + +CTest provides a command-line signature to configure (i.e. run cmake on), +build, and/or execute a test:: + + ctest --build-and-test <path-to-source> <path-to-build> + --build-generator <generator> + [<options>...] + [--build-options <opts>...] + [--test-command <command> [<args>...]] + +The configure and test steps are optional. The arguments to this command line +are the source and binary directories. The ``--build-generator`` option *must* +be provided to use ``--build-and-test``. If ``--test-command`` is specified +then that will be run after the build is complete. Other options that affect +this mode include: ``--build-target`` Specify a specific target to build. - This option goes with the ``--build-and-test`` option, if left out the - ``all`` target is built. + If left out the ``all`` target is built. ``--build-nocmake`` Run the build without running cmake first. @@ -299,91 +452,77 @@ Options Specify the name of the project to build. ``--build-makeprogram`` - Override the make program chosen by CTest with a given one. + Specify the explicit make program to be used by CMake when configuring and + building the project. Only applicable for Make and Ninja based generators. ``--build-noclean`` Skip the make clean step. ``--build-config-sample`` A sample executable to use to determine the configuration that - should be used. e.g. Debug/Release/etc. + should be used. e.g. ``Debug``, ``Release`` etc. ``--build-options`` - Add extra options to the build step. - - This option must be the last option with the exception of - ``--test-command`` + Additional options for configuring the build (i.e. for CMake, not for + the build tool). Note that if this is specified, the ``--build-options`` + keyword and its arguments must be the last option given on the command + line, with the possible exception of ``--test-command``. ``--test-command`` - The test to run with the ``--build-and-test`` option. - -``--test-output-size-passed <size>`` - Limit the output for passed tests to ``<size>`` bytes. - -``--test-output-size-failed <size>`` - Limit the output for failed tests to ``<size>`` bytes. + The command to run as the test step with the ``--build-and-test`` option. + All arguments following this keyword will be assumed to be part of the + test command line, so it must be the last option given. ``--test-timeout`` - The time limit in seconds, internal use only. + The time limit in seconds -``--tomorrow-tag`` - Nightly or experimental starts with next day tag. - - This is useful if the build will not finish in one day. - -``--ctest-config`` - The configuration file used to initialize CTest state when submitting dashboards. +.. _`Dashboard Client`: - This option tells CTest to use different initialization file instead - of CTestConfiguration.tcl. This way multiple initialization files - can be used for example to submit to multiple dashboards. +Dashboard Client +================ -``--overwrite`` - Overwrite CTest configuration option. +CTest can operate as a client for the `CDash`_ software quality dashboard +application. As a dashboard client, CTest performs a sequence of steps +to configure, build, and test software, and then submits the results to +a `CDash`_ server. The command-line signature used to submit to `CDash`_ is:: - By default ctest uses configuration options from configuration file. - This option will overwrite the configuration option. + ctest (-D <dashboard> | -M <model> -T <action> | -S <script> | -SP <script>) + [-- <dashboard-options>...] -``--extra-submit <file>[;<file>]`` - Submit extra files to the dashboard. +Options for Dashboard Client include: - This option will submit extra files to the dashboard. +``--group <group>`` + Specify what group you'd like to submit results to -``--force-new-ctest-process`` - Run child CTest instances as new processes. - - By default CTest will run child CTest instances within the same - process. If this behavior is not desired, this argument will - enforce new processes for child CTest processes. + Submit dashboard to specified group instead of default one. By + default, the dashboard is submitted to Nightly, Experimental, or + Continuous group, but by specifying this option, the group can be + arbitrary. -``--schedule-random`` - Use a random order for scheduling tests. + This replaces the deprecated option ``--track``. + Despite the name change its behavior is unchanged. - This option will run the tests in a random order. It is commonly - used to detect implicit dependencies in a test suite. +``-A <file>, --add-notes <file>`` + Add a notes file with submission. -``--submit-index`` - Legacy option for old Dart2 dashboard server feature. - Do not use. + This option tells CTest to include a notes file when submitting + dashboard. -``--timeout <seconds>`` - Set a global timeout on all tests. +``--tomorrow-tag`` + ``Nightly`` or ``Experimental`` starts with next day tag. - This option will set a global timeout on all tests that do not - already have a timeout set on them. + This is useful if the build will not finish in one day. -``--stop-time <time>`` - Set a time at which all tests should stop running. +``--extra-submit <file>[;<file>]`` + Submit extra files to the dashboard. - Set a real time of day at which all tests should timeout. Example: - ``7:00:00 -0400``. Any time format understood by the curl date parser - is accepted. Local time is assumed if no timezone is specified. + This option will submit extra files to the dashboard. ``--http1.0`` - Submit using HTTP 1.0. + Submit using `HTTP 1.0`. - This option will force CTest to use HTTP 1.0 to submit files to the - dashboard, instead of HTTP 1.1. + This option will force CTest to use `HTTP 1.0` to submit files to the + dashboard, instead of `HTTP 1.1`. ``--no-compress-output`` Do not compress test output when submitting. @@ -392,26 +531,6 @@ Options this to maintain compatibility with an older version of CDash which doesn't support compressed test output. -``--print-labels`` - Print all available test labels. - - This option will not run any tests, it will simply print the list of - all labels associated with the test set. - -.. include:: OPTIONS_HELP.txt - -.. _`Dashboard Client`: - -Dashboard Client -================ - -CTest can operate as a client for the `CDash`_ software quality dashboard -application. As a dashboard client, CTest performs a sequence of steps -to configure, build, and test software, and then submits the results to -a `CDash`_ server. - -.. _`CDash`: http://cdash.org/ - Dashboard Client Steps ---------------------- @@ -606,7 +725,7 @@ Configuration settings to specify the version control tool include: The source tree is updated by ``git fetch`` followed by ``git reset --hard`` to the ``FETCH_HEAD``. The result is the same - as ``git pull`` except that any local moficiations are overwritten. + as ``git pull`` except that any local modifications are overwritten. Use ``GITUpdateCustom`` to specify a different approach. ``GITInitSubmodules`` @@ -716,6 +835,8 @@ Configuration settings to specify the version control tool include: * :module:`CTest` module variable: ``UPDATE_TYPE`` if set, else ``CTEST_UPDATE_TYPE`` +.. _`UpdateVersionOnly`: + ``UpdateVersionOnly`` Specify that you want the version control update command to only discover the current version that is checked out, and not to update @@ -723,7 +844,18 @@ Configuration settings to specify the version control tool include: * `CTest Script`_ variable: :variable:`CTEST_UPDATE_VERSION_ONLY` +.. _`UpdateVersionOverride`: +``UpdateVersionOverride`` + Specify the current version of your source tree. + + When this variable is set to a non-empty string, CTest will report the value + you specified rather than using the update command to discover the current + version that is checked out. Use of this variable supersedes + ``UpdateVersionOnly``. Like ``UpdateVersionOnly``, using this variable tells + CTest not to update the source tree to a different version. + + * `CTest Script`_ variable: :variable:`CTEST_UPDATE_VERSION_OVERRIDE` Additional configuration settings include: @@ -758,6 +890,16 @@ Configuration settings include: * :module:`CTest` module variable: :variable:`CMAKE_COMMAND` followed by :variable:`PROJECT_SOURCE_DIR` +``LabelsForSubprojects`` + Specify a semicolon-separated list of labels that will be treated as + subprojects. This mapping will be passed on to CDash when configure, test or + build results are submitted. + + * `CTest Script`_ variable: :variable:`CTEST_LABELS_FOR_SUBPROJECTS` + * :module:`CTest` module variable: ``CTEST_LABELS_FOR_SUBPROJECTS`` + + See `Label and Subproject Summary`_. + .. _`CTest Build Step`: CTest Build Step @@ -778,7 +920,17 @@ 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 + subprojects. This mapping will be passed on to CDash when configure, test or + build results are submitted. + + * `CTest Script`_ variable: :variable:`CTEST_LABELS_FOR_SUBPROJECTS` + * :module:`CTest` module variable: ``CTEST_LABELS_FOR_SUBPROJECTS`` + + See `Label and Subproject Summary`_. ``MakeCommand`` Command-line to launch the software build process. @@ -815,6 +967,21 @@ Arguments to the command may specify some of the step settings. Configuration settings include: +``ResourceSpecFile`` + Specify a + :ref:`resource specification file <ctest-resource-specification-file>`. See + :ref:`ctest-resource-allocation` for more information. + +``LabelsForSubprojects`` + Specify a semicolon-separated list of labels that will be treated as + subprojects. This mapping will be passed on to CDash when configure, test or + build results are submitted. + + * `CTest Script`_ variable: :variable:`CTEST_LABELS_FOR_SUBPROJECTS` + * :module:`CTest` module variable: ``CTEST_LABELS_FOR_SUBPROJECTS`` + + See `Label and Subproject Summary`_. + ``TestLoad`` While running tests in parallel (e.g. with ``-j``), try not to start tests when they may cause the CPU load to pass above a given threshold. @@ -853,6 +1020,8 @@ Configuration settings include: * `CTest Script`_ variable: :variable:`CTEST_COVERAGE_EXTRA_FLAGS` * :module:`CTest` module variable: ``COVERAGE_EXTRA_FLAGS`` + These options are the first arguments passed to ``CoverageCommand``. + .. _`CTest MemCheck Step`: CTest MemCheck Step @@ -945,7 +1114,7 @@ Configuration settings include: * :module:`CTest` module variable: ``BUILDNAME`` ``CDashVersion`` - Specify the version of `CDash`_ on the server. + Legacy option. Not used. * `CTest Script`_ variable: none, detected from server * :module:`CTest` module variable: ``CTEST_CDASH_VERSION`` @@ -974,55 +1143,58 @@ Configuration settings include: * :module:`CTest` module variable: ``CTEST_CURL_OPTIONS`` ``DropLocation`` - The path on the dashboard server to send the submission. + Legacy option. When ``SubmitURL`` is not set, it is constructed from + ``DropMethod``, ``DropSiteUser``, ``DropSitePassword``, ``DropSite``, and + ``DropLocation``. * `CTest Script`_ variable: :variable:`CTEST_DROP_LOCATION` * :module:`CTest` module variable: ``DROP_LOCATION`` if set, else ``CTEST_DROP_LOCATION`` ``DropMethod`` - Specify the method by which results should be submitted to the - dashboard server. The value may be ``cp``, ``ftp``, ``http``, - ``https``, ``scp``, or ``xmlrpc`` (if CMake was built with - support for it). + Legacy option. When ``SubmitURL`` is not set, it is constructed from + ``DropMethod``, ``DropSiteUser``, ``DropSitePassword``, ``DropSite``, and + ``DropLocation``. * `CTest Script`_ variable: :variable:`CTEST_DROP_METHOD` * :module:`CTest` module variable: ``DROP_METHOD`` if set, else ``CTEST_DROP_METHOD`` ``DropSite`` - The dashboard server name - (for ``ftp``, ``http``, and ``https``, ``scp``, and ``xmlrpc``). + Legacy option. When ``SubmitURL`` is not set, it is constructed from + ``DropMethod``, ``DropSiteUser``, ``DropSitePassword``, ``DropSite``, and + ``DropLocation``. * `CTest Script`_ variable: :variable:`CTEST_DROP_SITE` * :module:`CTest` module variable: ``DROP_SITE`` if set, else ``CTEST_DROP_SITE`` ``DropSitePassword`` - The dashboard server login password, if any - (for ``ftp``, ``http``, and ``https``). + Legacy option. When ``SubmitURL`` is not set, it is constructed from + ``DropMethod``, ``DropSiteUser``, ``DropSitePassword``, ``DropSite``, and + ``DropLocation``. * `CTest Script`_ variable: :variable:`CTEST_DROP_SITE_PASSWORD` * :module:`CTest` module variable: ``DROP_SITE_PASSWORD`` if set, else ``CTEST_DROP_SITE_PASWORD`` ``DropSiteUser`` - The dashboard server login user name, if any - (for ``ftp``, ``http``, and ``https``). + Legacy option. When ``SubmitURL`` is not set, it is constructed from + ``DropMethod``, ``DropSiteUser``, ``DropSitePassword``, ``DropSite``, and + ``DropLocation``. * `CTest Script`_ variable: :variable:`CTEST_DROP_SITE_USER` * :module:`CTest` module variable: ``DROP_SITE_USER`` if set, else ``CTEST_DROP_SITE_USER`` ``IsCDash`` - Specify whether the dashboard server is `CDash`_ or an older - dashboard server implementation requiring ``TriggerSite``. + Legacy option. Not used. * `CTest Script`_ variable: :variable:`CTEST_DROP_SITE_CDASH` * :module:`CTest` module variable: ``CTEST_DROP_SITE_CDASH`` ``ScpCommand`` - ``scp`` command-line tool to use when ``DropMethod`` is ``scp``. + Legacy option. Not used. * `CTest Script`_ variable: :variable:`CTEST_SCP_COMMAND` * :module:`CTest` module variable: ``SCPCOMMAND`` @@ -1035,15 +1207,325 @@ Configuration settings include: * :module:`CTest` module variable: ``SITE``, initialized by the :command:`site_name` command +``SubmitURL`` + The ``http`` or ``https`` URL of the dashboard server to send the submission + to. + + * `CTest Script`_ variable: :variable:`CTEST_SUBMIT_URL` + * :module:`CTest` module variable: ``SUBMIT_URL`` if set, + else ``CTEST_SUBMIT_URL`` + ``TriggerSite`` - Legacy option to support older dashboard server implementations. - Not used when ``IsCDash`` is true. + Legacy option. Not used. * `CTest Script`_ variable: :variable:`CTEST_TRIGGER_SITE` * :module:`CTest` module variable: ``TRIGGER_SITE`` if set, else ``CTEST_TRIGGER_SITE`` +.. _`Show as JSON Object Model`: + +Show as JSON Object Model +========================= + +When the ``--show-only=json-v1`` command line option is given, the test +information is output in JSON format. Version 1.0 of the JSON object +model is defined as follows: + +``kind`` + The string "ctestInfo". + +``version`` + A JSON object specifying the version components. Its members are + + ``major`` + A non-negative integer specifying the major version component. + ``minor`` + A non-negative integer specifying the minor version component. + +``backtraceGraph`` + JSON object representing backtrace information with the + following members: + + ``commands`` + List of command names. + ``files`` + List of file names. + ``nodes`` + List of node JSON objects with members: + + ``command`` + Index into the ``commands`` member of the ``backtraceGraph``. + ``file`` + Index into the ``files`` member of the ``backtraceGraph``. + ``line`` + Line number in the file where the backtrace was added. + ``parent`` + Index into the ``nodes`` member of the ``backtraceGraph`` + representing the parent in the graph. + +``tests`` + A JSON array listing information about each test. Each entry + is a JSON object with members: + + ``name`` + Test name. + ``config`` + Configuration that the test can run on. + Empty string means any config. + ``command`` + List where the first element is the test command and the + remaining elements are the command arguments. + ``backtrace`` + Index into the ``nodes`` member of the ``backtraceGraph``. + ``properties`` + Test properties. + Can contain keys for each of the supported test properties. + +.. _`ctest-resource-allocation`: + +Resource Allocation +=================== + +CTest provides a mechanism for tests to specify the resources that they need +in a fine-grained way, and for users to specify the resources availiable on +the running machine. This allows CTest to internally keep track of which +resources are in use and which are free, scheduling tests in a way that +prevents them from trying to claim resources that are not available. + +A common use case for this feature is for tests that require the use of a GPU. +Multiple tests can simultaneously allocate memory from a GPU, but if too many +tests try to do this at once, some of them will fail to allocate, resulting in +a failed test, even though the test would have succeeded if it had the memory +it needed. By using the resource allocation feature, each test can specify how +much memory it requires from a GPU, allowing CTest to schedule tests in a way +that running several of these tests at once does not exhaust the GPU's memory +pool. + +Please note that CTest has no concept of what a GPU is or how much memory it +has, nor does it have any way of communicating with a GPU to retrieve this +information or perform any memory management. CTest simply keeps track of a +list of abstract resource types, each of which has a certain number of slots +available for tests to use. Each test specifies the number of slots that it +requires from a certain resource, and CTest then schedules them in a way that +prevents the total number of slots in use from exceeding the listed capacity. +When a test is executed, and slots from a resource are allocated to that test, +tests may assume that they have exclusive use of those slots for the duration +of the test's process. + +The CTest resource allocation feature consists of two inputs: + +* The :ref:`resource specification file <ctest-resource-specification-file>`, + described below, which describes the resources available on the system. +* The :prop_test:`RESOURCE_GROUPS` property of tests, which describes the + resources required by the test. + +When CTest runs a test, the resources allocated to that test are passed in the +form of a set of +:ref:`environment variables <ctest-resource-environment-variables>` as +described below. Using this information to decide which resource to connect to +is left to the test writer. + +The ``RESOURCE_GROUPS`` property tells CTest what resources a test expects +to use grouped in a way meaningful to the test. The test itself must read +the :ref:`environment variables <ctest-resource-environment-variables>` to +determine which resources have been allocated to each group. For example, +each group may correspond to a process the test will spawn when executed. + +Note that even if a test specifies a ``RESOURCE_GROUPS`` property, it is still +possible for that to test to run without any resource allocation (and without +the corresponding +:ref:`environment variables <ctest-resource-environment-variables>`) +if the user does not pass a resource specification file. Passing this file, +either through the ``--resource-spec-file`` command-line argument or the +``RESOURCE_SPEC_FILE`` argument to :command:`ctest_test`, is what activates the +resource allocation feature. Tests should check the +``CTEST_RESOURCE_GROUP_COUNT`` environment variable to find out whether or not +resource allocation is activated. This variable will always (and only) be +defined if resource allocation is activated. If resource allocation is not +activated, then the ``CTEST_RESOURCE_GROUP_COUNT`` variable will not exist, +even if it exists for the parent ``ctest`` process. If a test absolutely must +have resource allocation, then it can return a failing exit code or use the +:prop_test:`SKIP_RETURN_CODE` or :prop_test:`SKIP_REGULAR_EXPRESSION` +properties to indicate a skipped test. + +.. _`ctest-resource-specification-file`: + +Resource Specification File +--------------------------- + +The resource specification file is a JSON file which is passed to CTest, either +on the :manual:`ctest(1)` command line as ``--resource-spec-file``, or as the +``RESOURCE_SPEC_FILE`` argument of :command:`ctest_test`. The resource +specification file must be a JSON object. All examples in this document assume +the following resource specification file: + +.. code-block:: json + + { + "version": { + "major": 1, + "minor": 0 + }, + "local": [ + { + "gpus": [ + { + "id": "0", + "slots": 2 + }, + { + "id": "1", + "slots": 4 + }, + { + "id": "2", + "slots": 2 + }, + { + "id": "3" + } + ], + "crypto_chips": [ + { + "id": "card0", + "slots": 4 + } + ] + } + ] + } + +The members are: + +``version`` + An object containing a ``major`` integer field and a ``minor`` integer field. + Currently, the only supported version is major ``1``, minor ``0``. Any other + value is an error. + +``local`` + A JSON array of resource sets present on the system. Currently, this array + is restricted to being of size 1. + + Each array element is a JSON object with members whose names are equal to the + desired resource types, such as ``gpus``. These names must start with a + lowercase letter or an underscore, and subsequent characters can be a + lowercase letter, a digit, or an underscore. Uppercase letters are not + allowed, because certain platforms have case-insensitive environment + variables. See the `Environment Variables`_ section below for + more information. It is recommended that the resource type name be the plural + of a noun, such as ``gpus`` or ``crypto_chips`` (and not ``gpu`` or + ``crypto_chip``.) + + Please note that the names ``gpus`` and ``crypto_chips`` are just examples, + and CTest does not interpret them in any way. You are free to make up any + resource type you want to meet your own requirements. + + The value for each resource type is a JSON array consisting of JSON objects, + each of which describe a specific instance of the specified resource. These + objects have the following members: + + ``id`` + A string consisting of an identifier for the resource. Each character in + the identifier can be a lowercase letter, a digit, or an underscore. + Uppercase letters are not allowed. + + Identifiers must be unique within a resource type. However, they do not + have to be unique across resource types. For example, it is valid to have a + ``gpus`` resource named ``0`` and a ``crypto_chips`` resource named ``0``, + but not two ``gpus`` resources both named ``0``. + + Please note that the IDs ``0``, ``1``, ``2``, ``3``, and ``card0`` are just + examples, and CTest does not interpret them in any way. You are free to + make up any IDs you want to meet your own requirements. + + ``slots`` + An optional unsigned number specifying the number of slots available on the + resource. For example, this could be megabytes of RAM on a GPU, or + cryptography units available on a cryptography chip. If ``slots`` is not + specified, a default value of ``1`` is assumed. + +In the example file above, there are four GPUs with ID's 0 through 3. GPU 0 has +2 slots, GPU 1 has 4, GPU 2 has 2, and GPU 3 has a default of 1 slot. There is +also one cryptography chip with 4 slots. + +``RESOURCE_GROUPS`` Property +---------------------------- + +See :prop_test:`RESOURCE_GROUPS` for a description of this property. + +.. _`ctest-resource-environment-variables`: + +Environment Variables +--------------------- + +Once CTest has decided which resources to allocate to a test, it passes this +information to the test executable as a series of environment variables. For +each example below, we will assume that the test in question has a +:prop_test:`RESOURCE_GROUPS` property of +``2,gpus:2;gpus:4,gpus:1,crypto_chips:2``. + +The following variables are passed to the test process: + +.. envvar:: CTEST_RESOURCE_GROUP_COUNT + + The total number of groups specified by the :prop_test:`RESOURCE_GROUPS` + property. For example: + + * ``CTEST_RESOURCE_GROUP_COUNT=3`` + + This variable will only be defined if :manual:`ctest(1)` has been given a + ``--resource-spec-file``, or if :command:`ctest_test` has been given a + ``RESOURCE_SPEC_FILE``. If no resource specification file has been given, + this variable will not be defined. + +.. envvar:: CTEST_RESOURCE_GROUP_<num> + + The list of resource types allocated to each group, with each item + separated by a comma. ``<num>`` is a number from zero to + ``CTEST_RESOURCE_GROUP_COUNT`` minus one. ``CTEST_RESOURCE_GROUP_<num>`` + is defined for each ``<num>`` in this range. For example: + + * ``CTEST_RESOURCE_GROUP_0=gpus`` + * ``CTEST_RESOURCE_GROUP_1=gpus`` + * ``CTEST_RESOURCE_GROUP_2=crypto_chips,gpus`` + +.. envvar:: CTEST_RESOURCE_GROUP_<num>_<resource-type> + + The list of resource IDs and number of slots from each ID allocated to each + group for a given resource type. This variable consists of a series of + pairs, each pair separated by a semicolon, and with the two items in the pair + separated by a comma. The first item in each pair is ``id:`` followed by the + ID of a resource of type ``<resource-type>``, and the second item is + ``slots:`` followed by the number of slots from that resource allocated to + the given group. For example: + + * ``CTEST_RESOURCE_GROUP_0_GPUS=id:0,slots:2`` + * ``CTEST_RESOURCE_GROUP_1_GPUS=id:2,slots:2`` + * ``CTEST_RESOURCE_GROUP_2_GPUS=id:1,slots:4;id:3,slots:1`` + * ``CTEST_RESOURCE_GROUP_2_CRYPTO_CHIPS=id:card0,slots:2`` + + In this example, group 0 gets 2 slots from GPU ``0``, group 1 gets 2 slots + from GPU ``2``, and group 2 gets 4 slots from GPU ``1``, 1 slot from GPU + ``3``, and 2 slots from cryptography chip ``card0``. + + ``<num>`` is a number from zero to ``CTEST_RESOURCE_GROUP_COUNT`` minus one. + ``<resource-type>`` is the name of a resource type, converted to uppercase. + ``CTEST_RESOURCE_GROUP_<num>_<resource-type>`` is defined for the product + of each ``<num>`` in the range listed above and each resource type listed in + ``CTEST_RESOURCE_GROUP_<num>``. + + Because some platforms have case-insensitive names for environment variables, + the names of resource types may not clash in a case-insensitive environment. + Because of this, for the sake of simplicity, all resource types must be + listed in all lowercase in the + :ref:`resource specification file <ctest-resource-specification-file>` and + in the :prop_test:`RESOURCE_GROUPS` property, and they are converted to all + uppercase in the ``CTEST_RESOURCE_GROUP_<num>_<resource-type>`` environment + variable. + See Also ======== .. include:: LINKS.txt + +.. _`CDash`: http://cdash.org/ diff --git a/Help/module/CPackArchive.rst b/Help/module/CPackArchive.rst index eb8d9d244..8616098cb 100644 --- a/Help/module/CPackArchive.rst +++ b/Help/module/CPackArchive.rst @@ -1 +1,4 @@ -.. cmake-module:: ../../Modules/CPackArchive.cmake +CPackArchive +------------ + +The documentation for the CPack Archive generator has moved here: :cpack_gen:`CPack Archive Generator` diff --git a/Help/module/CPackBundle.rst b/Help/module/CPackBundle.rst index 651e87426..513488427 100644 --- a/Help/module/CPackBundle.rst +++ b/Help/module/CPackBundle.rst @@ -1 +1,4 @@ -.. cmake-module:: ../../Modules/CPackBundle.cmake +CPackBundle +----------- + +The documentation for the CPack Bundle generator has moved here: :cpack_gen:`CPack Bundle Generator` diff --git a/Help/module/CPackCygwin.rst b/Help/module/CPackCygwin.rst index 21f447348..719dfceb1 100644 --- a/Help/module/CPackCygwin.rst +++ b/Help/module/CPackCygwin.rst @@ -1 +1,4 @@ -.. cmake-module:: ../../Modules/CPackCygwin.cmake +CPackCygwin +----------- + +The documentation for the CPack Cygwin generator has moved here: :cpack_gen:`CPack Cygwin Generator` diff --git a/Help/module/CPackDMG.rst b/Help/module/CPackDMG.rst index 784262c5e..e59dcbb7a 100644 --- a/Help/module/CPackDMG.rst +++ b/Help/module/CPackDMG.rst @@ -1 +1,4 @@ -.. cmake-module:: ../../Modules/CPackDMG.cmake +CPackDMG +-------- + +The documentation for the CPack DragNDrop generator has moved here: :cpack_gen:`CPack DragNDrop Generator` diff --git a/Help/module/CPackDeb.rst b/Help/module/CPackDeb.rst index d1526ee49..cd7e5f305 100644 --- a/Help/module/CPackDeb.rst +++ b/Help/module/CPackDeb.rst @@ -1 +1,4 @@ -.. cmake-module:: ../../Modules/CPackDeb.cmake +CPackDeb +-------- + +The documentation for the CPack DEB generator has moved here: :cpack_gen:`CPack DEB Generator` diff --git a/Help/module/CPackFreeBSD.rst b/Help/module/CPackFreeBSD.rst new file mode 100644 index 000000000..69701b8e9 --- /dev/null +++ b/Help/module/CPackFreeBSD.rst @@ -0,0 +1,4 @@ +CPackFreeBSD +------------ + +The documentation for the CPack FreeBSD generator has moved here: :cpack_gen:`CPack FreeBSD Generator` diff --git a/Help/module/CPackNSIS.rst b/Help/module/CPackNSIS.rst index bb35ed60a..2cb407a97 100644 --- a/Help/module/CPackNSIS.rst +++ b/Help/module/CPackNSIS.rst @@ -1 +1,4 @@ -.. cmake-module:: ../../Modules/CPackNSIS.cmake +CPackNSIS +--------- + +The documentation for the CPack NSIS generator has moved here: :cpack_gen:`CPack NSIS Generator` diff --git a/Help/module/CPackNuGet.rst b/Help/module/CPackNuGet.rst new file mode 100644 index 000000000..4f39b3a7e --- /dev/null +++ b/Help/module/CPackNuGet.rst @@ -0,0 +1,4 @@ +CPackNuGet +---------- + +The documentation for the CPack NuGet generator has moved here: :cpack_gen:`CPack NuGet Generator` diff --git a/Help/module/CPackPackageMaker.rst b/Help/module/CPackPackageMaker.rst index de5544869..226b6fd8e 100644 --- a/Help/module/CPackPackageMaker.rst +++ b/Help/module/CPackPackageMaker.rst @@ -1 +1,4 @@ -.. cmake-module:: ../../Modules/CPackPackageMaker.cmake +CPackPackageMaker +----------------- + +The documentation for the CPack PackageMaker generator has moved here: :cpack_gen:`CPack PackageMaker Generator` diff --git a/Help/module/CPackProductBuild.rst b/Help/module/CPackProductBuild.rst index 6081fe48a..8cd9198b4 100644 --- a/Help/module/CPackProductBuild.rst +++ b/Help/module/CPackProductBuild.rst @@ -1 +1,4 @@ -.. cmake-module:: ../../Modules/CPackProductBuild.cmake +CPackProductBuild +----------------- + +The documentation for the CPack productbuild generator has moved here: :cpack_gen:`CPack productbuild Generator` diff --git a/Help/module/CPackRPM.rst b/Help/module/CPackRPM.rst index 28d0e6912..00b7e0ad7 100644 --- a/Help/module/CPackRPM.rst +++ b/Help/module/CPackRPM.rst @@ -1 +1,4 @@ -.. cmake-module:: ../../Modules/CPackRPM.cmake +CPackRPM +-------- + +The documentation for the CPack RPM generator has moved here: :cpack_gen:`CPack RPM Generator` diff --git a/Help/module/CPackWIX.rst b/Help/module/CPackWIX.rst index 1f5e451e9..fd378b86a 100644 --- a/Help/module/CPackWIX.rst +++ b/Help/module/CPackWIX.rst @@ -1 +1,5 @@ -.. cmake-module:: ../../Modules/CPackWIX.cmake +CPackWIX +-------- + +The documentation for the CPack WIX generator has moved here: +:cpack_gen:`CPack WIX Generator` diff --git a/Help/module/CheckFortranSourceRuns.rst b/Help/module/CheckFortranSourceRuns.rst new file mode 100644 index 000000000..a1bff7063 --- /dev/null +++ b/Help/module/CheckFortranSourceRuns.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckFortranSourceRuns.cmake diff --git a/Help/module/CheckOBJCCompilerFlag.rst b/Help/module/CheckOBJCCompilerFlag.rst new file mode 100644 index 000000000..e4bd6fdae --- /dev/null +++ b/Help/module/CheckOBJCCompilerFlag.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckOBJCCompilerFlag.cmake diff --git a/Help/module/CheckOBJCSourceCompiles.rst b/Help/module/CheckOBJCSourceCompiles.rst new file mode 100644 index 000000000..d4a1484ec --- /dev/null +++ b/Help/module/CheckOBJCSourceCompiles.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckOBJCSourceCompiles.cmake diff --git a/Help/module/CheckOBJCSourceRuns.rst b/Help/module/CheckOBJCSourceRuns.rst new file mode 100644 index 000000000..c72f0db20 --- /dev/null +++ b/Help/module/CheckOBJCSourceRuns.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckOBJCSourceRuns.cmake diff --git a/Help/module/CheckOBJCXXCompilerFlag.rst b/Help/module/CheckOBJCXXCompilerFlag.rst new file mode 100644 index 000000000..1518a48ee --- /dev/null +++ b/Help/module/CheckOBJCXXCompilerFlag.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckOBJCXXCompilerFlag.cmake diff --git a/Help/module/CheckOBJCXXSourceCompiles.rst b/Help/module/CheckOBJCXXSourceCompiles.rst new file mode 100644 index 000000000..a1c8ae94e --- /dev/null +++ b/Help/module/CheckOBJCXXSourceCompiles.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckOBJCXXSourceCompiles.cmake diff --git a/Help/module/CheckOBJCXXSourceRuns.rst b/Help/module/CheckOBJCXXSourceRuns.rst new file mode 100644 index 000000000..5198e1b6d --- /dev/null +++ b/Help/module/CheckOBJCXXSourceRuns.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckOBJCXXSourceRuns.cmake diff --git a/Help/module/CheckPIESupported.rst b/Help/module/CheckPIESupported.rst new file mode 100644 index 000000000..02e7b4316 --- /dev/null +++ b/Help/module/CheckPIESupported.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckPIESupported.cmake diff --git a/Help/module/FetchContent.rst b/Help/module/FetchContent.rst new file mode 100644 index 000000000..c130a6dcb --- /dev/null +++ b/Help/module/FetchContent.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FetchContent.cmake diff --git a/Help/module/FindEnvModules.rst b/Help/module/FindEnvModules.rst new file mode 100644 index 000000000..72c120f22 --- /dev/null +++ b/Help/module/FindEnvModules.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindEnvModules.cmake diff --git a/Help/module/FindFontconfig.rst b/Help/module/FindFontconfig.rst new file mode 100644 index 000000000..449fe09d0 --- /dev/null +++ b/Help/module/FindFontconfig.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindFontconfig.cmake diff --git a/Help/module/FindIconv.rst b/Help/module/FindIconv.rst new file mode 100644 index 000000000..c1f3ed080 --- /dev/null +++ b/Help/module/FindIconv.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindIconv.cmake diff --git a/Help/module/FindLibinput.rst b/Help/module/FindLibinput.rst new file mode 100644 index 000000000..a8ca0b024 --- /dev/null +++ b/Help/module/FindLibinput.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindLibinput.cmake diff --git a/Help/module/FindODBC.rst b/Help/module/FindODBC.rst new file mode 100644 index 000000000..8558334df --- /dev/null +++ b/Help/module/FindODBC.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindODBC.cmake diff --git a/Help/module/FindOpenACC.rst b/Help/module/FindOpenACC.rst new file mode 100644 index 000000000..dda330831 --- /dev/null +++ b/Help/module/FindOpenACC.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindOpenACC.cmake diff --git a/Help/module/FindPatch.rst b/Help/module/FindPatch.rst new file mode 100644 index 000000000..ba5e9102d --- /dev/null +++ b/Help/module/FindPatch.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindPatch.cmake diff --git a/Help/module/FindPython.rst b/Help/module/FindPython.rst new file mode 100644 index 000000000..057a350c0 --- /dev/null +++ b/Help/module/FindPython.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindPython.cmake diff --git a/Help/module/FindPython2.rst b/Help/module/FindPython2.rst new file mode 100644 index 000000000..1696bedc1 --- /dev/null +++ b/Help/module/FindPython2.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindPython2.cmake diff --git a/Help/module/FindPython3.rst b/Help/module/FindPython3.rst new file mode 100644 index 000000000..e530ab85c --- /dev/null +++ b/Help/module/FindPython3.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindPython3.cmake diff --git a/Help/module/FindSQLite3.rst b/Help/module/FindSQLite3.rst new file mode 100644 index 000000000..d1910e5a6 --- /dev/null +++ b/Help/module/FindSQLite3.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindSQLite3.cmake diff --git a/Help/policy/CMP0000.rst b/Help/policy/CMP0000.rst index 97ea633b2..aecfa7187 100644 --- a/Help/policy/CMP0000.rst +++ b/Help/policy/CMP0000.rst @@ -7,25 +7,27 @@ CMake requires that projects specify the version of CMake to which they have been written. This policy has been put in place so users trying to build the project may be told when they need to update their CMake. Specifying a version also helps the project build with CMake -versions newer than that specified. Use the cmake_minimum_required -command at the top of your main CMakeLists.txt file: +versions newer than that specified. Use the :command:`cmake_minimum_required` +command at the top of your main ``CMakeLists.txt`` file: :: cmake_minimum_required(VERSION <major>.<minor>) -where "<major>.<minor>" is the version of CMake you want to support -(such as "2.6"). The command will ensure that at least the given +where ``<major>.<minor>`` is the version of CMake you want to support +(such as ``3.14``). The command will ensure that at least the given version of CMake is running and help newer versions be compatible with -the project. See documentation of cmake_minimum_required for details. +the project. See documentation of :command:`cmake_minimum_required` for +details. -Note that the command invocation must appear in the CMakeLists.txt +Note that the command invocation must appear in the ``CMakeLists.txt`` file itself; a call in an included file is not sufficient. However, -the cmake_policy command may be called to set policy CMP0000 to OLD or -NEW behavior explicitly. The OLD behavior is to silently ignore the -missing invocation. The NEW behavior is to issue an error instead of -a warning. An included file may set CMP0000 explicitly to affect how -this policy is enforced for the main CMakeLists.txt file. +the :command:`cmake_policy` command may be called to set policy ``CMP0000`` +to ``OLD`` or ``NEW`` behavior explicitly. The ``OLD`` behavior is to +silently ignore the missing invocation. The ``NEW`` behavior is to issue +an error instead of a warning. An included file may set ``CMP0000`` +explicitly to affect how this policy is enforced for the main +``CMakeLists.txt`` file. This policy was introduced in CMake version 2.6.0. diff --git a/Help/policy/CMP0001.rst b/Help/policy/CMP0001.rst index 09ad38702..6fa64d983 100644 --- a/Help/policy/CMP0001.rst +++ b/Help/policy/CMP0001.rst @@ -1,21 +1,21 @@ CMP0001 ------- -CMAKE_BACKWARDS_COMPATIBILITY should no longer be used. +``CMAKE_BACKWARDS_COMPATIBILITY`` should no longer be used. -The OLD behavior is to check CMAKE_BACKWARDS_COMPATIBILITY and present -it to the user. The NEW behavior is to ignore +The behavior is to check ``CMAKE_BACKWARDS_COMPATIBILITY`` and present +it to the user. The ``NEW`` behavior is to ignore CMAKE_BACKWARDS_COMPATIBILITY completely. -In CMake 2.4 and below the variable CMAKE_BACKWARDS_COMPATIBILITY was +In CMake 2.4 and below the variable ``CMAKE_BACKWARDS_COMPATIBILITY`` was used to request compatibility with earlier versions of CMake. In CMake 2.6 and above all compatibility issues are handled by policies -and the cmake_policy command. However, CMake must still check -CMAKE_BACKWARDS_COMPATIBILITY for projects written for CMake 2.4 and +and the :command:`cmake_policy` command. However, CMake must still check +``CMAKE_BACKWARDS_COMPATIBILITY`` for projects written for CMake 2.4 and below. This policy was introduced in CMake version 2.6.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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 diff --git a/Help/policy/CMP0002.rst b/Help/policy/CMP0002.rst index 7cc53efa1..dc68d5180 100644 --- a/Help/policy/CMP0002.rst +++ b/Help/policy/CMP0002.rst @@ -3,8 +3,8 @@ CMP0002 Logical target names must be globally unique. -Targets names created with add_executable, add_library, or -add_custom_target are logical build target names. Logical target +Targets names created with :command:`add_executable`, :command:`add_library`, or +:command:`add_custom_target` are logical build target names. Logical target names must be globally unique because: :: @@ -16,13 +16,13 @@ names must be globally unique because: The logical name of executable and library targets does not have to correspond to the physical file names built. Consider using the -OUTPUT_NAME target property to create two targets with the same +:prop_tgt:`OUTPUT_NAME` target property to create two targets with the same physical name while keeping logical names distinct. Custom targets must simply have globally unique names (unless one uses the global -property ALLOW_DUPLICATE_CUSTOM_TARGETS with a Makefiles generator). +property :prop_gbl:`ALLOW_DUPLICATE_CUSTOM_TARGETS` with a Makefiles generator). This policy was introduced in CMake version 2.6.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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 diff --git a/Help/policy/CMP0003.rst b/Help/policy/CMP0003.rst index 16b045165..dd90883dc 100644 --- a/Help/policy/CMP0003.rst +++ b/Help/policy/CMP0003.rst @@ -37,7 +37,7 @@ Unfortunately this change can break code like target_link_libraries(myexe /path/to/libA.so B) -where "B" is meant to find "/path/to/libB.so". This code is wrong +where ``B`` is meant to find ``/path/to/libB.so``. This code is wrong because the user is asking the linker to find library B but has not provided a linker search path (which may be added with the link_directories command). However, with the old linking @@ -45,9 +45,9 @@ implementation the code would work accidentally because the linker search path added for library A allowed library B to be found. In order to support projects depending on linker search paths added by -linking to libraries with known full paths, the OLD behavior for this +linking to libraries with known full paths, the ``OLD`` behavior for this policy will add the linker search paths even though they are not -needed for their own libraries. When this policy is set to OLD, CMake +needed for their own libraries. When this policy is set to ``OLD``, CMake will produce a link line such as :: @@ -98,7 +98,7 @@ target. This avoids flooding users with messages for every target when setting the policy once will probably fix all targets. This policy was introduced in CMake version 2.6.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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 diff --git a/Help/policy/CMP0004.rst b/Help/policy/CMP0004.rst index 55da4d293..be6d3079b 100644 --- a/Help/policy/CMP0004.rst +++ b/Help/policy/CMP0004.rst @@ -12,14 +12,15 @@ whitespace from libraries linked with code like This could lead to subtle errors in user projects. -The OLD behavior for this policy is to silently remove leading and -trailing whitespace. The NEW behavior for this policy is to diagnose +The ``OLD`` behavior for this policy is to silently remove leading and +trailing whitespace. The ``NEW`` behavior for this policy is to diagnose the existence of such whitespace as an error. The setting for this policy used when checking the library names is that in effect when the -target is created by an add_executable or add_library command. +target is created by an :command:`add_executable` or :command:`add_library` +command. This policy was introduced in CMake version 2.6.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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 diff --git a/Help/policy/CMP0005.rst b/Help/policy/CMP0005.rst index 66d125fb7..59567d56e 100644 --- a/Help/policy/CMP0005.rst +++ b/Help/policy/CMP0005.rst @@ -12,15 +12,15 @@ CMake versions 2.6 and above support escaping of most values, but cannot assume the user has not added escapes already in an attempt to work around limitations in earlier versions. -The OLD behavior for this policy is to place definition values given +The ``OLD`` behavior for this policy is to place definition values given to add_definitions directly in the generated build rules without -attempting to escape anything. The NEW behavior for this policy is to +attempting to escape anything. The ``NEW`` behavior for this policy is to generate correct escapes for all native build tools automatically. -See documentation of the COMPILE_DEFINITIONS target property for +See documentation of the ``COMPILE_DEFINITIONS`` target property for limitations of the escaping implementation. This policy was introduced in CMake version 2.6.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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 diff --git a/Help/policy/CMP0006.rst b/Help/policy/CMP0006.rst index d1b9ece7f..181958b39 100644 --- a/Help/policy/CMP0006.rst +++ b/Help/policy/CMP0006.rst @@ -1,24 +1,24 @@ CMP0006 ------- -Installing MACOSX_BUNDLE targets requires a BUNDLE DESTINATION. +Installing :prop_tgt:`MACOSX_BUNDLE` targets requires a ``BUNDLE DESTINATION``. -This policy determines whether the install(TARGETS) command must be -given a BUNDLE DESTINATION when asked to install a target with the -MACOSX_BUNDLE property set. CMake 2.4 and below did not distinguish +This policy determines whether the :command:`install(TARGETS)` command must be +given a ``BUNDLE DESTINATION`` when asked to install a target with the +:prop_tgt:`MACOSX_BUNDLE` property set. CMake 2.4 and below did not distinguish application bundles from normal executables when installing targets. -CMake 2.6 provides a BUNDLE option to the install(TARGETS) command -that specifies rules specific to application bundles on the Mac. +CMake 2.6 provides a ``BUNDLE`` option to the :command:`install(TARGETS)` +command that specifies rules specific to application bundles on the Mac. Projects should use this option when installing a target with the -MACOSX_BUNDLE property set. +:prop_tgt:`MACOSX_BUNDLE` property set. -The OLD behavior for this policy is to fall back to the RUNTIME -DESTINATION if a BUNDLE DESTINATION is not given. The NEW behavior -for this policy is to produce an error if a bundle target is installed -without a BUNDLE DESTINATION. +The ``OLD`` behavior for this policy is to fall back to the +``RUNTIME DESTINATION`` if a ``BUNDLE DESTINATION`` is not given. The ``NEW`` +behavior for this policy is to produce an error if a bundle target is installed +without a ``BUNDLE DESTINATION``. This policy was introduced in CMake version 2.6.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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 diff --git a/Help/policy/CMP0007.rst b/Help/policy/CMP0007.rst index 39276457a..1006ed33a 100644 --- a/Help/policy/CMP0007.rst +++ b/Help/policy/CMP0007.rst @@ -5,13 +5,13 @@ list command no longer ignores empty elements. This policy determines whether the list command will ignore empty elements in the list. CMake 2.4 and below list commands ignored all -empty elements in the list. For example, a;b;;c would have length 3 -and not 4. The OLD behavior for this policy is to ignore empty list -elements. The NEW behavior for this policy is to correctly count +empty elements in the list. For example, ``a;b;;c`` would have length 3 +and not 4. The ``OLD`` behavior for this policy is to ignore empty list +elements. The ``NEW`` behavior for this policy is to correctly count empty elements in a list. This policy was introduced in CMake version 2.6.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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 diff --git a/Help/policy/CMP0008.rst b/Help/policy/CMP0008.rst index f1e2ddde5..18ede821c 100644 --- a/Help/policy/CMP0008.rst +++ b/Help/policy/CMP0008.rst @@ -9,26 +9,27 @@ In CMake 2.4 and below it is possible to write code like target_link_libraries(myexe /full/path/to/somelib) -where "somelib" is supposed to be a valid library file name such as -"libsomelib.a" or "somelib.lib". For Makefile generators this +where ``somelib`` is supposed to be a valid library file name such as +``libsomelib.a`` or ``somelib.lib``. For Makefile generators this produces an error at build time because the dependency on the full -path cannot be found. For VS IDE and Xcode generators this used to +path cannot be found. For :ref:`Visual Studio Generators` IDE +and :generator:`Xcode` generators this used to work by accident because CMake would always split off the library directory and ask the linker to search for the library by name -(-lsomelib or somelib.lib). Despite the failure with Makefiles, some -projects have code like this and build only with VS and/or Xcode. +(``-lsomelib`` or ``somelib.lib``). Despite the failure with Makefiles, some +projects have code like this and build only with Visual Studio and/or Xcode. This version of CMake prefers to pass the full path directly to the native build tool, which will fail in this case because it does not name a valid library file. This policy determines what to do with full paths that do not appear -to name a valid library file. The OLD behavior for this policy is to +to name a valid library file. The ``OLD`` behavior for this policy is to split the library name from the path and ask the linker to search for -it. The NEW behavior for this policy is to trust the given path and +it. The ``NEW`` behavior for this policy is to trust the given path and pass it directly to the native build tool unchanged. This policy was introduced in CMake version 2.6.1. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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 diff --git a/Help/policy/CMP0009.rst b/Help/policy/CMP0009.rst index 44baeb449..27cfde0db 100644 --- a/Help/policy/CMP0009.rst +++ b/Help/policy/CMP0009.rst @@ -3,19 +3,19 @@ CMP0009 FILE GLOB_RECURSE calls should not follow symlinks by default. -In CMake 2.6.1 and below, FILE GLOB_RECURSE calls would follow through -symlinks, sometimes coming up with unexpectedly large result sets +In CMake 2.6.1 and below, :command:`file(GLOB_RECURSE)` calls would follow +through symlinks, sometimes coming up with unexpectedly large result sets because of symlinks to top level directories that contain hundreds of thousands of files. This policy determines whether or not to follow symlinks encountered -during a FILE GLOB_RECURSE call. The OLD behavior for this policy is -to follow the symlinks. The NEW behavior for this policy is not to -follow the symlinks by default, but only if FOLLOW_SYMLINKS is given -as an additional argument to the FILE command. +during a :command:`file(GLOB_RECURSE)` call. The ``OLD`` behavior for this +policy is to follow the symlinks. The ``NEW`` behavior for this policy is not +to follow the symlinks by default, but only if ``FOLLOW_SYMLINKS`` is given +as an additional argument to the ``FILE`` command. This policy was introduced in CMake version 2.6.2. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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 diff --git a/Help/policy/CMP0010.rst b/Help/policy/CMP0010.rst index 344d70475..cfae4982a 100644 --- a/Help/policy/CMP0010.rst +++ b/Help/policy/CMP0010.rst @@ -4,17 +4,17 @@ CMP0010 Bad variable reference syntax is an error. In CMake 2.6.2 and below, incorrect variable reference syntax such as -a missing close-brace ("${FOO") was reported but did not stop +a missing close-brace (``${FOO``) was reported but did not stop processing of CMake code. This policy determines whether a bad -variable reference is an error. The OLD behavior for this policy is +variable reference is an error. The ``OLD`` behavior for this policy is to warn about the error, leave the string untouched, and continue. -The NEW behavior for this policy is to report an error. +The ``NEW`` behavior for this policy is to report an error. If :policy:`CMP0053` is set to ``NEW``, this policy has no effect and is treated as always being ``NEW``. This policy was introduced in CMake version 2.6.3. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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 diff --git a/Help/policy/CMP0011.rst b/Help/policy/CMP0011.rst index d281e0ef7..257415c26 100644 --- a/Help/policy/CMP0011.rst +++ b/Help/policy/CMP0011.rst @@ -1,24 +1,25 @@ CMP0011 ------- -Included scripts do automatic cmake_policy PUSH and POP. +Included scripts do automatic :command:`cmake_policy` PUSH and POP. In CMake 2.6.2 and below, CMake Policy settings in scripts loaded by -the include() and find_package() commands would affect the includer. -Explicit invocations of cmake_policy(PUSH) and cmake_policy(POP) were -required to isolate policy changes and protect the includer. While -some scripts intend to affect the policies of their includer, most do -not. In CMake 2.6.3 and above, include() and find_package() by -default PUSH and POP an entry on the policy stack around an included -script, but provide a NO_POLICY_SCOPE option to disable it. This -policy determines whether or not to imply NO_POLICY_SCOPE for -compatibility. The OLD behavior for this policy is to imply -NO_POLICY_SCOPE for include() and find_package() commands. The NEW -behavior for this policy is to allow the commands to do their default -cmake_policy PUSH and POP. +the :command:`include` and :command:`find_package` commands would affect +the includer. Explicit invocations of ``cmake_policy(PUSH)`` and +``cmake_policy(POP)`` were required to isolate policy changes and protect +the includer. While some scripts intend to affect the policies of their +includer, most do not. In CMake 2.6.3 and above, :command:`include` and +:command:`find_package` by default ``PUSH`` and ``POP`` an entry on +the policy stack around an included +script, but provide a ``NO_POLICY_SCOPE`` option to disable it. This +policy determines whether or not to imply ``NO_POLICY_SCOPE`` for +compatibility. The ``OLD`` behavior for this policy is to imply +``NO_POLICY_SCOPE`` for :command:`include` and :command:`find_package` commands. +The ``NEW`` behavior for this policy is to allow the commands to do +their default cmake_policy ``PUSH`` and ``POP``. This policy was introduced in CMake version 2.6.3. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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 diff --git a/Help/policy/CMP0012.rst b/Help/policy/CMP0012.rst index 85d64f4d4..17ec8d33d 100644 --- a/Help/policy/CMP0012.rst +++ b/Help/policy/CMP0012.rst @@ -1,27 +1,28 @@ CMP0012 ------- -if() recognizes numbers and boolean constants. +:command:`if` recognizes numbers and boolean constants. -In CMake versions 2.6.4 and lower the if() command implicitly +In CMake versions 2.6.4 and lower the :command:`if` command implicitly dereferenced arguments corresponding to variables, even those named -like numbers or boolean constants, except for 0 and 1. Numbers and -boolean constants such as true, false, yes, no, on, off, y, n, -notfound, ignore (all case insensitive) were recognized in some cases -but not all. For example, the code "if(TRUE)" might have evaluated as -false. Numbers such as 2 were recognized only in boolean expressions -like "if(NOT 2)" (leading to false) but not as a single-argument like -"if(2)" (also leading to false). Later versions of CMake prefer to +like numbers or boolean constants, except for ``0`` and ``1``. Numbers and +boolean constants such as ``true``, ``false``, ``yes``, ``no``, ``on``, +``off``, ``y``, ``n``, ``notfound``, ``ignore`` (all case insensitive) +were recognized in some cases but not all. For example, the code ``if(TRUE)`` +might have evaluated as ``false``. +Numbers such as 2 were recognized only in boolean expressions +like ``if(NOT 2)`` (leading to ``false``) but not as a single-argument like +``if(2)`` (also leading to ``false``). Later versions of CMake prefer to treat numbers and boolean constants literally, so they should not be used as variable names. -The OLD behavior for this policy is to implicitly dereference -variables named like numbers and boolean constants. The NEW behavior +The ``OLD`` behavior for this policy is to implicitly dereference +variables named like numbers and boolean constants. The ``NEW`` behavior for this policy is to recognize numbers and boolean constants without dereferencing variables with such names. This policy was introduced in CMake version 2.8.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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 diff --git a/Help/policy/CMP0013.rst b/Help/policy/CMP0013.rst index 2fabb8920..dbd67a177 100644 --- a/Help/policy/CMP0013.rst +++ b/Help/policy/CMP0013.rst @@ -9,13 +9,13 @@ generation files would be written and then overwritten in the build tree and could lead to strange behavior. CMake 2.6.4 and above explicitly detect duplicate binary directories. CMake 2.6.4 always considers this case an error. In CMake 2.8.0 and above this policy -determines whether or not the case is an error. The OLD behavior for +determines whether or not the case is an error. The ``OLD`` behavior for this policy is to allow duplicate binary directories. The NEW behavior for this policy is to disallow duplicate binary directories with an error. This policy was introduced in CMake version 2.8.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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 diff --git a/Help/policy/CMP0014.rst b/Help/policy/CMP0014.rst index f1f7b77b8..331dde5ef 100644 --- a/Help/policy/CMP0014.rst +++ b/Help/policy/CMP0014.rst @@ -1,17 +1,17 @@ CMP0014 ------- -Input directories must have CMakeLists.txt. +Input directories must have ``CMakeLists.txt``. -CMake versions before 2.8 silently ignored missing CMakeLists.txt -files in directories referenced by add_subdirectory() or subdirs(), +CMake versions before 2.8 silently ignored missing ``CMakeLists.txt`` +files in directories referenced by :command:`add_subdirectory` or :command:`subdirs`, treating them as if present but empty. In CMake 2.8.0 and above this -policy determines whether or not the case is an error. The OLD -behavior for this policy is to silently ignore the problem. The NEW -behavior for this policy is to report an error. +:command:`cmake_policy` determines whether or not the case is an error. +The ``OLD`` behavior for this policy is to silently ignore the problem. +The ``NEW`` behavior for this policy is to report an error. This policy was introduced in CMake version 2.8.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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 diff --git a/Help/policy/CMP0015.rst b/Help/policy/CMP0015.rst index 9a48e3dac..90d520334 100644 --- a/Help/policy/CMP0015.rst +++ b/Help/policy/CMP0015.rst @@ -1,19 +1,19 @@ CMP0015 ------- -link_directories() treats paths relative to the source dir. + :command:`link_directories` treats paths relative to the source dir. -In CMake 2.8.0 and lower the link_directories() command passed +In CMake 2.8.0 and lower the :command:`link_directories` command passed relative paths unchanged to the linker. In CMake 2.8.1 and above the -link_directories() command prefers to interpret relative paths with -respect to CMAKE_CURRENT_SOURCE_DIR, which is consistent with -include_directories() and other commands. The OLD behavior for this -policy is to use relative paths verbatim in the linker command. The -NEW behavior for this policy is to convert relative paths to absolute -paths by appending the relative path to CMAKE_CURRENT_SOURCE_DIR. +:command:`link_directories` command prefers to interpret relative paths with +respect to ``CMAKE_CURRENT_SOURCE_DIR``, which is consistent with +:command:`include_directories` and other commands. The ``OLD`` behavior for +this policy is to use relative paths verbatim in the linker command. The +``NEW`` behavior for this policy is to convert relative paths to absolute +paths by appending the relative path to ``CMAKE_CURRENT_SOURCE_DIR``. This policy was introduced in CMake version 2.8.1. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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 diff --git a/Help/policy/CMP0016.rst b/Help/policy/CMP0016.rst index cc898c8ca..026d02a9d 100644 --- a/Help/policy/CMP0016.rst +++ b/Help/policy/CMP0016.rst @@ -1,15 +1,16 @@ CMP0016 ------- -target_link_libraries() reports error if its only argument is not a target. +:command:`target_link_libraries` reports error if its only argument +is not a target. -In CMake 2.8.2 and lower the target_link_libraries() command silently +In CMake 2.8.2 and lower the :command:`target_link_libraries` command silently ignored if it was called with only one argument, and this argument wasn't a valid target. In CMake 2.8.3 and above it reports an error in this case. This policy was introduced in CMake version 2.8.3. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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 diff --git a/Help/policy/CMP0017.rst b/Help/policy/CMP0017.rst index 9f0f0380f..ca4664eed 100644 --- a/Help/policy/CMP0017.rst +++ b/Help/policy/CMP0017.rst @@ -4,18 +4,18 @@ CMP0017 Prefer files from the CMake module directory when including from there. Starting with CMake 2.8.4, if a cmake-module shipped with CMake (i.e. -located in the CMake module directory) calls include() or -find_package(), the files located in the CMake module directory are -preferred over the files in CMAKE_MODULE_PATH. This makes sure that -the modules belonging to CMake always get those files included which +located in the CMake module directory) calls :command:`include` or +:command:`find_package`, the files located in the CMake module directory are +preferred over the files in :variable:`CMAKE_MODULE_PATH`. This makes sure +that the modules belonging to CMake always get those files included which they expect, and against which they were developed and tested. In all -other cases, the files found in CMAKE_MODULE_PATH still take -precedence over the ones in the CMake module directory. The OLD +other cases, the files found in :variable:`CMAKE_MODULE_PATH` still take +precedence over the ones in the CMake module directory. The ``OLD`` behavior is to always prefer files from CMAKE_MODULE_PATH over files from the CMake modules directory. This policy was introduced in CMake version 2.8.4. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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 diff --git a/Help/policy/CMP0018.rst b/Help/policy/CMP0018.rst index a3a7a12bd..624840678 100644 --- a/Help/policy/CMP0018.rst +++ b/Help/policy/CMP0018.rst @@ -1,34 +1,35 @@ CMP0018 ------- -Ignore CMAKE_SHARED_LIBRARY_<Lang>_FLAGS variable. +Ignore ``CMAKE_SHARED_LIBRARY_<Lang>_FLAGS`` variable. -CMake 2.8.8 and lower compiled sources in SHARED and MODULE libraries -using the value of the undocumented CMAKE_SHARED_LIBRARY_<Lang>_FLAGS +CMake 2.8.8 and lower compiled sources in ``SHARED`` and ``MODULE`` libraries +using the value of the undocumented ``CMAKE_SHARED_LIBRARY_<Lang>_FLAGS`` platform variable. The variable contained platform-specific flags needed to compile objects for shared libraries. Typically it included -a flag such as -fPIC for position independent code but also included +a flag such as ``-fPIC`` for position independent code but also included other flags needed on certain platforms. CMake 2.8.9 and higher -prefer instead to use the POSITION_INDEPENDENT_CODE target property to -determine what targets should be position independent, and new +prefer instead to use the :prop_tgt:`POSITION_INDEPENDENT_CODE` target +property to determine what targets should be position independent, and new undocumented platform variables to select flags while ignoring -CMAKE_SHARED_LIBRARY_<Lang>_FLAGS completely. +``CMAKE_SHARED_LIBRARY_<Lang>_FLAGS`` completely. The default for either approach produces identical compilation flags, -but if a project modifies CMAKE_SHARED_LIBRARY_<Lang>_FLAGS from its +but if a project modifies ``CMAKE_SHARED_LIBRARY_<Lang>_FLAGS`` from its original value this policy determines which approach to use. -The OLD behavior for this policy is to ignore the -POSITION_INDEPENDENT_CODE property for all targets and use the -modified value of CMAKE_SHARED_LIBRARY_<Lang>_FLAGS for SHARED and -MODULE libraries. +The ``OLD`` behavior for this policy is to ignore the +:prop_tgt:`POSITION_INDEPENDENT_CODE` property for all targets and use the +modified value of ``CMAKE_SHARED_LIBRARY_<Lang>_FLAGS`` for ``SHARED`` and +``MODULE`` libraries. -The NEW behavior for this policy is to ignore -CMAKE_SHARED_LIBRARY_<Lang>_FLAGS whether it is modified or not and -honor the POSITION_INDEPENDENT_CODE target property. +The ``NEW`` behavior for this policy is to ignore +``CMAKE_SHARED_LIBRARY_<Lang>_FLAGS`` whether it is modified or not and +honor the :prop_tgt:`POSITION_INDEPENDENT_CODE` target property. This policy was introduced in CMake version 2.8.9. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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 diff --git a/Help/policy/CMP0019.rst b/Help/policy/CMP0019.rst index 2e3557d32..682dcdf86 100644 --- a/Help/policy/CMP0019.rst +++ b/Help/policy/CMP0019.rst @@ -11,12 +11,12 @@ CMake versions because all variable references are now normally evaluated during CMake language processing. CMake 2.8.11 and higher prefer to skip the extra evaluation. -The OLD behavior for this policy is to re-evaluate the values for -strict compatibility. The NEW behavior for this policy is to leave +The ``OLD`` behavior for this policy is to re-evaluate the values for +strict compatibility. The ``NEW`` behavior for this policy is to leave the values untouched. This policy was introduced in CMake version 2.8.11. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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 diff --git a/Help/policy/CMP0020.rst b/Help/policy/CMP0020.rst index 75ca9deb2..6d27684f2 100644 --- a/Help/policy/CMP0020.rst +++ b/Help/policy/CMP0020.rst @@ -1,27 +1,27 @@ CMP0020 ------- -Automatically link Qt executables to qtmain target on Windows. +Automatically link Qt executables to ``qtmain`` target on Windows. CMake 2.8.10 and lower required users of Qt to always specify a link -dependency to the qtmain.lib static library manually on Windows. +dependency to the ``qtmain.lib`` static library manually on Windows. CMake 2.8.11 gained the ability to evaluate generator expressions -while determining the link dependencies from IMPORTED targets. This +while determining the link dependencies from ``IMPORTED`` targets. This allows CMake itself to automatically link executables which link to Qt -to the qtmain.lib library when using IMPORTED Qt targets. For -applications already linking to qtmain.lib, this should have little +to the ``qtmain.lib`` library when using ``IMPORTED`` Qt targets. For +applications already linking to ``qtmain.lib``, this should have little impact. For applications which supply their own alternative WinMain implementation and for applications which use the QAxServer library, this automatic linking will need to be disabled as per the documentation. -The OLD behavior for this policy is not to link executables to -qtmain.lib automatically when they link to the QtCore IMPORTED target. -The NEW behavior for this policy is to link executables to qtmain.lib -automatically when they link to QtCore IMPORTED target. +The ``OLD`` behavior for this policy is not to link executables to +``qtmain.lib`` automatically when they link to the QtCore ``IMPORTED`` target. +The ``NEW`` behavior for this policy is to link executables to ``qtmain.lib`` +automatically when they link to QtCore ``IMPORTED`` target. This policy was introduced in CMake version 2.8.11. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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 diff --git a/Help/policy/CMP0021.rst b/Help/policy/CMP0021.rst index 3a792ca14..937b106eb 100644 --- a/Help/policy/CMP0021.rst +++ b/Help/policy/CMP0021.rst @@ -1,20 +1,21 @@ CMP0021 ------- -Fatal error on relative paths in INCLUDE_DIRECTORIES target property. +Fatal error on relative paths in :prop_tgt:`INCLUDE_DIRECTORIES` target +property. -CMake 2.8.10.2 and lower allowed the INCLUDE_DIRECTORIES target +CMake 2.8.10.2 and lower allowed the :prop_tgt:`INCLUDE_DIRECTORIES` target property to contain relative paths. The base path for such relative -entries is not well defined. CMake 2.8.12 issues a FATAL_ERROR if the -INCLUDE_DIRECTORIES property contains a relative path. +entries is not well defined. CMake 2.8.12 issues a ``FATAL_ERROR`` if the +:prop_tgt:`INCLUDE_DIRECTORIES` property contains a relative path. -The OLD behavior for this policy is not to warn about relative paths -in the INCLUDE_DIRECTORIES target property. The NEW behavior for this -policy is to issue a FATAL_ERROR if INCLUDE_DIRECTORIES contains a +The ``OLD`` behavior for this policy is not to warn about relative paths +in the ``INCLUDE_DIRECTORIES`` target property. The ``NEW`` behavior for this +policy is to issue a ``FATAL_ERROR`` if ``INCLUDE_DIRECTORIES`` contains a relative path. This policy was introduced in CMake version 2.8.12. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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 diff --git a/Help/policy/CMP0022.rst b/Help/policy/CMP0022.rst index 579d09ac0..be60e375a 100644 --- a/Help/policy/CMP0022.rst +++ b/Help/policy/CMP0022.rst @@ -1,39 +1,39 @@ CMP0022 ------- -INTERFACE_LINK_LIBRARIES defines the link interface. +:prop_tgt:`INTERFACE_LINK_LIBRARIES` defines the link interface. CMake 2.8.11 constructed the 'link interface' of a target from properties matching ``(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?``. The modern way to specify config-sensitive content is to use generator expressions and the ``IMPORTED_`` prefix makes uniform processing of the link interface with generator expressions impossible. The -INTERFACE_LINK_LIBRARIES target property was introduced as a +:prop_tgt:`INTERFACE_LINK_LIBRARIES` target property was introduced as a replacement in CMake 2.8.12. This new property is named consistently -with the INTERFACE_COMPILE_DEFINITIONS, INTERFACE_INCLUDE_DIRECTORIES -and INTERFACE_COMPILE_OPTIONS properties. For in-build targets, CMake +with the ``INTERFACE_COMPILE_DEFINITIONS``, ``INTERFACE_INCLUDE_DIRECTORIES`` +and ``INTERFACE_COMPILE_OPTIONS`` properties. For in-build targets, CMake will use the INTERFACE_LINK_LIBRARIES property as the source of the -link interface only if policy CMP0022 is NEW. When exporting a target -which has this policy set to NEW, only the INTERFACE_LINK_LIBRARIES -property will be processed and generated for the IMPORTED target by -default. A new option to the install(EXPORT) and export commands +link interface only if policy ``CMP0022`` is ``NEW``. When exporting a target +which has this policy set to ``NEW``, only the :prop_tgt:`INTERFACE_LINK_LIBRARIES` +property will be processed and generated for the ``IMPORTED`` target by +default. A new option to the :command:`install(EXPORT)` and export commands allows export of the old-style properties for compatibility with downstream users of CMake versions older than 2.8.12. The -target_link_libraries command will no longer populate the properties -matching LINK_INTERFACE_LIBRARIES(_<CONFIG>)? if this policy is NEW. +:command:`target_link_libraries` command will no longer populate the properties +matching ``LINK_INTERFACE_LIBRARIES(_<CONFIG>)?`` if this policy is ``NEW``. Warning-free future-compatible code which works with CMake 2.8.7 onwards can be written by using the ``LINK_PRIVATE`` and ``LINK_PUBLIC`` keywords of :command:`target_link_libraries`. -The OLD behavior for this policy is to ignore the -INTERFACE_LINK_LIBRARIES property for in-build targets. The NEW -behavior for this policy is to use the INTERFACE_LINK_LIBRARIES +The ``OLD`` behavior for this policy is to ignore the +:prop_tgt:`INTERFACE_LINK_LIBRARIES` property for in-build targets. +The ``NEW`` behavior for this policy is to use the ``INTERFACE_LINK_LIBRARIES`` property for in-build targets, and ignore the old properties matching ``(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?``. This policy was introduced in CMake version 2.8.12. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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 diff --git a/Help/policy/CMP0023.rst b/Help/policy/CMP0023.rst index 76a4900b6..3c72c8195 100644 --- a/Help/policy/CMP0023.rst +++ b/Help/policy/CMP0023.rst @@ -1,15 +1,15 @@ CMP0023 ------- -Plain and keyword target_link_libraries signatures cannot be mixed. +Plain and keyword :command:`target_link_libraries` signatures cannot be mixed. -CMake 2.8.12 introduced the target_link_libraries signature using the -PUBLIC, PRIVATE, and INTERFACE keywords to generalize the LINK_PUBLIC -and LINK_PRIVATE keywords introduced in CMake 2.8.7. Use of -signatures with any of these keywords sets the link interface of a +CMake 2.8.12 introduced the :command:`target_link_libraries` signature using +the ``PUBLIC``, ``PRIVATE``, and ``INTERFACE`` keywords to generalize the +``LINK_PUBLIC`` and ``LINK_PRIVATE`` keywords introduced in CMake 2.8.7. +Use of signatures with any of these keywords sets the link interface of a target explicitly, even if empty. This produces confusing behavior when used in combination with the historical behavior of the plain -target_link_libraries signature. For example, consider the code: +:command:`target_link_libraries` signature. For example, consider the code: :: @@ -20,16 +20,16 @@ After the first line the link interface has not been set explicitly so CMake would use the link implementation, A, as the link interface. However, the second line sets the link interface to empty. In order to avoid this subtle behavior CMake now prefers to disallow mixing the -plain and keyword signatures of target_link_libraries for a single +plain and keyword signatures of :command:`target_link_libraries` for a single target. -The OLD behavior for this policy is to allow keyword and plain -target_link_libraries signatures to be mixed. The NEW behavior for +The ``OLD`` behavior for this policy is to allow keyword and plain +:command:`target_link_libraries` signatures to be mixed. The ``NEW`` behavior for this policy is to not to allow mixing of the keyword and plain signatures. This policy was introduced in CMake version 2.8.12. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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 diff --git a/Help/policy/CMP0024.rst b/Help/policy/CMP0024.rst index 272a56c8d..6e24b0454 100644 --- a/Help/policy/CMP0024.rst +++ b/Help/policy/CMP0024.rst @@ -3,22 +3,23 @@ CMP0024 Disallow include export result. -CMake 2.8.12 and lower allowed use of the include() command with the -result of the export() command. This relies on the assumption that -the export() command has an immediate effect at configure-time during +CMake 2.8.12 and lower allowed use of the :command:`include` command with the +result of the :command:`export` command. This relies on the assumption that +the :command:`export` command has an immediate effect at configure-time during a cmake run. Certain properties of targets are not fully determined until later at generate-time, such as the link language and complete list of link libraries. Future refactoring will change the effect of -the export() command to be executed at generate-time. Use ALIAS +the :command:`export` command to be executed at generate-time. Use ``ALIAS`` targets instead in cases where the goal is to refer to targets by another name. -The OLD behavior for this policy is to allow including the result of -an export() command. The NEW behavior for this policy is not to -allow including the result of an export() command. +The ``OLD`` behavior for this policy is to allow including the result of +an :command:`export` command. The ``NEW`` behavior for this policy is not to +allow including the result of an :command:`export` command. This policy was introduced in CMake version 3.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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 diff --git a/Help/policy/CMP0025.rst b/Help/policy/CMP0025.rst index 62dd50985..ba5e1e948 100644 --- a/Help/policy/CMP0025.rst +++ b/Help/policy/CMP0025.rst @@ -15,13 +15,13 @@ language ``<LANG>`` is enabled by the :command:`project` or :command:`enable_language` command. The policy must be set prior to the invocation of either command. -The OLD behavior for this policy is to use compiler id ``Clang``. The -NEW behavior for this policy is to use compiler id ``AppleClang``. +The ``OLD`` behavior for this policy is to use compiler id ``Clang``. The +``NEW`` behavior for this policy is to use compiler id ``AppleClang``. This policy was introduced in CMake version 3.0. Use the -:command:`cmake_policy` command to set this policy to OLD or NEW explicitly. -Unlike most policies, CMake version |release| does *not* warn -by default when this policy is not set and simply uses OLD behavior. +:command:`cmake_policy` command to set this policy to ``OLD`` or ``NEW`` +explicitly. Unlike most policies, CMake version |release| does *not* warn +by default when this policy is not set and simply uses ``OLD`` behavior. See documentation of the :variable:`CMAKE_POLICY_WARNING_CMP0025 <CMAKE_POLICY_WARNING_CMP<NNNN>>` variable to control the warning. diff --git a/Help/policy/CMP0026.rst b/Help/policy/CMP0026.rst index 3fe1374c8..3401d4a9a 100644 --- a/Help/policy/CMP0026.rst +++ b/Help/policy/CMP0026.rst @@ -3,26 +3,27 @@ CMP0026 Disallow use of the LOCATION property for build targets. -CMake 2.8.12 and lower allowed reading the LOCATION target +CMake 2.8.12 and lower allowed reading the :prop_tgt:`LOCATION` target property (and configuration-specific variants) to determine the eventual location of build targets. This relies on the assumption that all necessary information is available at configure-time to determine the final location and filename of the target. However, this property is not fully determined until later at -generate-time. At generate time, the $<TARGET_FILE> generator -expression can be used to determine the eventual LOCATION of a target +generate-time. At generate time, the ``$<TARGET_FILE>`` generator +expression can be used to determine the eventual :prop_tgt:`LOCATION` of a target output. -Code which reads the LOCATION target property can be ported to use the -$<TARGET_FILE> generator expression together with the file(GENERATE) -subcommand to generate a file containing the target location. +Code which reads the :prop_tgt:`LOCATION` target property can be ported to +use the ``$<TARGET_FILE>`` generator expression together with the +:command:`file(GENERATE)` subcommand to generate a file containing +the target location. -The OLD behavior for this policy is to allow reading the LOCATION -properties from build-targets. The NEW behavior for this policy is to -not to allow reading the LOCATION properties from build-targets. +The ``OLD`` behavior for this policy is to allow reading the :prop_tgt:`LOCATION` +properties from build-targets. The ``NEW`` behavior for this policy is to +not to allow reading the :prop_tgt:`LOCATION` properties from build-targets. This policy was introduced in CMake version 3.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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 diff --git a/Help/policy/CMP0027.rst b/Help/policy/CMP0027.rst index 28913cee4..bf7b6a978 100644 --- a/Help/policy/CMP0027.rst +++ b/Help/policy/CMP0027.rst @@ -4,24 +4,24 @@ CMP0027 Conditionally linked imported targets with missing include directories. CMake 2.8.11 introduced introduced the concept of -INTERFACE_INCLUDE_DIRECTORIES, and a check at cmake time that the -entries in the INTERFACE_INCLUDE_DIRECTORIES of an IMPORTED target -actually exist. CMake 2.8.11 also introduced generator expression -support in the target_link_libraries command. However, if an imported -target is linked as a result of a generator expression evaluation, the -entries in the INTERFACE_INCLUDE_DIRECTORIES of that target were not +:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`, and a check at cmake time that the +entries in the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of an ``IMPORTED`` +target actually exist. CMake 2.8.11 also introduced generator expression +support in the :command:`target_link_libraries` command. However, if an +imported target is linked as a result of a generator expression evaluation, the +entries in the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of that target were not checked for existence as they should be. -The OLD behavior of this policy is to report a warning if an entry in -the INTERFACE_INCLUDE_DIRECTORIES of a generator-expression -conditionally linked IMPORTED target does not exist. +The ``OLD`` behavior of this policy is to report a warning if an entry in +the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of a generator-expression +conditionally linked ``IMPORTED`` target does not exist. -The NEW behavior of this policy is to report an error if an entry in -the INTERFACE_INCLUDE_DIRECTORIES of a generator-expression -conditionally linked IMPORTED target does not exist. +The ``NEW`` behavior of this policy is to report an error if an entry in +the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of a generator-expression +conditionally linked ``IMPORTED`` target does not exist. This policy was introduced in CMake version 3.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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 diff --git a/Help/policy/CMP0028.rst b/Help/policy/CMP0028.rst index be57125d4..ab3822993 100644 --- a/Help/policy/CMP0028.rst +++ b/Help/policy/CMP0028.rst @@ -1,25 +1,25 @@ CMP0028 ------- -Double colon in target name means ALIAS or IMPORTED target. +Double colon in target name means ``ALIAS`` or ``IMPORTED`` target. CMake 2.8.12 and lower allowed the use of targets and files with double -colons in target_link_libraries, with some buildsystem generators. +colons in :command:`target_link_libraries`, with some buildsystem generators. -The use of double-colons is a common pattern used to namespace IMPORTED -targets and ALIAS targets. When computing the link dependencies of a target, -the name of each dependency could either be a target, or a file on disk. -Previously, if a target was not found with a matching name, the name was -considered to refer to a file on disk. This can lead to confusing error +The use of double-colons is a common pattern used to namespace ``IMPORTED`` +targets and ``ALIAS`` targets. When computing the link dependencies of +a target, the name of each dependency could either be a target, or a file +on disk. Previously, if a target was not found with a matching name, the name +was considered to refer to a file on disk. This can lead to confusing error messages if there is a typo in what should be a target name. -The OLD behavior for this policy is to search for targets, then files on disk, -even if the search term contains double-colons. The NEW behavior for this -policy is to issue a FATAL_ERROR if a link dependency contains -double-colons but is not an IMPORTED target or an ALIAS target. +The ``OLD`` behavior for this policy is to search for targets, then files on +disk, even if the search term contains double-colons. The ``NEW`` behavior +for this policy is to issue a ``FATAL_ERROR`` if a link dependency contains +double-colons but is not an ``IMPORTED`` target or an ``ALIAS`` target. This policy was introduced in CMake version 3.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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 diff --git a/Help/policy/CMP0037.rst b/Help/policy/CMP0037.rst index 9f8457c62..9895fb0b4 100644 --- a/Help/policy/CMP0037.rst +++ b/Help/policy/CMP0037.rst @@ -10,19 +10,25 @@ as :manual:`cmake-generator-expressions(7)` and some diagnostics expect target names to match a restricted pattern. Target names may contain upper and lower case letters, numbers, the underscore -character (_), dot(.), plus(+) and minus(-). As a special case, ALIAS -targets and IMPORTED targets may contain two consequtive colons. +character (``_``), dot(``.``), plus(``+``) and minus(``-``). +As a special case, ``ALIAS`` and ``IMPORTED`` targets may contain +two consecutive colons. Target names reserved by one or more CMake generators are not allowed. -Among others these include "all", "help" and "test". +Among others these include ``all``, ``clean``, ``help``, and ``install``. -The OLD behavior for this policy is to allow creating targets with +Target names associated with optional features, such as ``test`` and +``package``, may also be reserved. CMake 3.10 and below always reserve them. +CMake 3.11 and above reserve them only when the corresponding feature is +enabled (e.g. by including the :module:`CTest` or :module:`CPack` modules). + +The ``OLD`` behavior for this policy is to allow creating targets with reserved names or which do not match the validity pattern. -The NEW behavior for this policy is to report an error +The ``NEW`` behavior for this policy is to report an error if an add_* command is used with an invalid target name. This policy was introduced in CMake version 3.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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 diff --git a/Help/policy/CMP0038.rst b/Help/policy/CMP0038.rst index a306d90a9..7fb2209fa 100644 --- a/Help/policy/CMP0038.rst +++ b/Help/policy/CMP0038.rst @@ -7,12 +7,12 @@ CMake 2.8.12 and lower allowed a build target to link to itself directly with a :command:`target_link_libraries` call. This is an indicator of a bug in user code. -The OLD behavior for this policy is to ignore targets which list themselves -in their own link implementation. The NEW behavior for this policy is to +The ``OLD`` behavior for this policy is to ignore targets which list themselves +in their own link implementation. The ``NEW`` behavior for this policy is to report an error if a target attempts to link to itself. This policy was introduced in CMake version 3.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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 diff --git a/Help/policy/CMP0039.rst b/Help/policy/CMP0039.rst index 97d78ae2a..4b14e21ae 100644 --- a/Help/policy/CMP0039.rst +++ b/Help/policy/CMP0039.rst @@ -7,13 +7,13 @@ CMake 2.8.12 and lower allowed using utility targets in the left hand side position of the :command:`target_link_libraries` command. This is an indicator of a bug in user code. -The OLD behavior for this policy is to ignore attempts to set the link -libraries of utility targets. The NEW behavior for this policy is to +The ``OLD`` behavior for this policy is to ignore attempts to set the link +libraries of utility targets. The ``NEW`` behavior for this policy is to report an error if an attempt is made to set the link libraries of a utility target. This policy was introduced in CMake version 3.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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 diff --git a/Help/policy/CMP0040.rst b/Help/policy/CMP0040.rst index d46baf647..0afe5895d 100644 --- a/Help/policy/CMP0040.rst +++ b/Help/policy/CMP0040.rst @@ -2,7 +2,7 @@ CMP0040 ------- The target in the ``TARGET`` signature of :command:`add_custom_command` -must exist and must be defined in current directory. +must exist and must be defined in the current directory. CMake 2.8.12 and lower silently ignored a custom command created with the ``TARGET`` signature of :command:`add_custom_command` diff --git a/Help/policy/CMP0041.rst b/Help/policy/CMP0041.rst index f027d5de9..3b4df3601 100644 --- a/Help/policy/CMP0041.rst +++ b/Help/policy/CMP0041.rst @@ -15,13 +15,13 @@ As an additional diagnostic, the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` gener on an :prop_tgt:`IMPORTED` target for the install location should not contain paths in the source directory or the build directory. -The OLD behavior for this policy is to ignore relative path entries if they -contain a generator expression. The NEW behavior for this policy is to report +The ``OLD`` behavior for this policy is to ignore relative path entries if they +contain a generator expression. The ``NEW`` behavior for this policy is to report an error if a generator expression appears in another location and the path is relative. This policy was introduced in CMake version 3.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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 diff --git a/Help/policy/CMP0042.rst b/Help/policy/CMP0042.rst index 31314b2cd..087756450 100644 --- a/Help/policy/CMP0042.rst +++ b/Help/policy/CMP0042.rst @@ -15,7 +15,7 @@ the :prop_tgt:`INSTALL_NAME_DIR` and :variable:`CMAKE_INSTALL_NAME_DIR` variables. This policy was introduced in CMake version 3.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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 diff --git a/Help/policy/CMP0043.rst b/Help/policy/CMP0043.rst index 9e427c377..05210ac6e 100644 --- a/Help/policy/CMP0043.rst +++ b/Help/policy/CMP0043.rst @@ -35,13 +35,13 @@ or via :command:`target_compile_definitions`: COMPILE_DEFINITIONS $<$<CONFIG:Debug>:DIR_DEBUG_MODE> ) -The OLD behavior for this policy is to consume the content of the suffixed +The ``OLD`` behavior for this policy is to consume the content of the suffixed :prop_tgt:`COMPILE_DEFINITIONS_<CONFIG>` target property when generating the -compilation command. The NEW behavior for this policy is to ignore the content +compilation command. The ``NEW`` behavior for this policy is to ignore the content of the :prop_tgt:`COMPILE_DEFINITIONS_<CONFIG>` target property . This policy was introduced in CMake version 3.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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 diff --git a/Help/policy/CMP0044.rst b/Help/policy/CMP0044.rst index 02afa9f1a..6a4d040b1 100644 --- a/Help/policy/CMP0044.rst +++ b/Help/policy/CMP0044.rst @@ -9,13 +9,13 @@ comparison of the :variable:`CMAKE_<LANG>_COMPILER_ID` with a test value. The possible valid values are lowercase, but the comparison with the test value was performed case-insensitively. -The OLD behavior for this policy is to perform a case-insensitive comparison -with the value in the ``<LANG>_COMPILER_ID`` expression. The NEW behavior +The ``OLD`` behavior for this policy is to perform a case-insensitive comparison +with the value in the ``<LANG>_COMPILER_ID`` expression. The ``NEW`` behavior for this policy is to perform a case-sensitive comparison with the value in the ``<LANG>_COMPILER_ID`` expression. This policy was introduced in CMake version 3.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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 diff --git a/Help/policy/CMP0045.rst b/Help/policy/CMP0045.rst index c7e1a90f6..80e217b18 100644 --- a/Help/policy/CMP0045.rst +++ b/Help/policy/CMP0045.rst @@ -7,13 +7,13 @@ In CMake 2.8.12 and lower, the :command:`get_target_property` command accepted a non-existent target argument without issuing any error or warning. The result variable is set to a ``-NOTFOUND`` value. -The OLD behavior for this policy is to issue no warning and set the result -variable to a ``-NOTFOUND`` value. The NEW behavior +The ``OLD`` behavior for this policy is to issue no warning and set the result +variable to a ``-NOTFOUND`` value. The ``NEW`` behavior for this policy is to issue a ``FATAL_ERROR`` if the command is called with a non-existent target. This policy was introduced in CMake version 3.0. CMake version -|release| warns when the policy is not set and uses OLD behavior. Use -the cmake_policy command to set it to OLD or NEW explicitly. +|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 diff --git a/Help/policy/CMP0046.rst b/Help/policy/CMP0046.rst index 576d1b1cc..bf785842c 100644 --- a/Help/policy/CMP0046.rst +++ b/Help/policy/CMP0046.rst @@ -6,14 +6,14 @@ Error on non-existent dependency in add_dependencies. CMake 2.8.12 and lower silently ignored non-existent dependencies listed in the :command:`add_dependencies` command. -The OLD behavior for this policy is to silently ignore non-existent -dependencies. The NEW behavior for this policy is to report an error +The ``OLD`` behavior for this policy is to silently ignore non-existent +dependencies. The ``NEW`` behavior for this policy is to report an error if non-existent dependencies are listed in the :command:`add_dependencies` command. This policy was introduced in CMake version 3.0. CMake version |release| warns when the policy is not set and uses -OLD behavior. Use the cmake_policy command to set it to OLD or -NEW explicitly. +``OLD`` behavior. Use the :command:`cmake_policy` command to set it +to ``OLD`` or ``NEW`` explicitly. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0047.rst b/Help/policy/CMP0047.rst index 882dd7828..9588edd7a 100644 --- a/Help/policy/CMP0047.rst +++ b/Help/policy/CMP0047.rst @@ -15,14 +15,14 @@ language ``<LANG>`` is enabled by the :command:`project` or :command:`enable_language` command. The policy must be set prior to the invocation of either command. -The OLD behavior for this policy is to use the ``GNU`` compiler id -for the qcc and QCC compiler drivers. The NEW behavior for this policy +The ``OLD`` behavior for this policy is to use the ``GNU`` compiler id +for the qcc and QCC compiler drivers. The ``NEW`` behavior for this policy is to use the ``QCC`` compiler id for those drivers. This policy was introduced in CMake version 3.0. Use the -:command:`cmake_policy` command to set this policy to OLD or NEW explicitly. -Unlike most policies, CMake version |release| does *not* warn -by default when this policy is not set and simply uses OLD behavior. +:command:`cmake_policy` command to set this policy to ``OLD`` or ``NEW`` +explicitly. Unlike most policies, CMake version |release| does *not* warn +by default when this policy is not set and simply uses ``OLD`` behavior. See documentation of the :variable:`CMAKE_POLICY_WARNING_CMP0047 <CMAKE_POLICY_WARNING_CMP<NNNN>>` variable to control the warning. diff --git a/Help/policy/CMP0048.rst b/Help/policy/CMP0048.rst index 0e7e60681..e63ec01a2 100644 --- a/Help/policy/CMP0048.rst +++ b/Help/policy/CMP0048.rst @@ -1,24 +1,24 @@ CMP0048 ------- -The :command:`project` command manages VERSION variables. +The :command:`project` command manages ``VERSION`` variables. CMake version 3.0 introduced the ``VERSION`` option of the :command:`project` command to specify a project version as well as the name. In order to keep :variable:`PROJECT_VERSION` and related variables consistent with variable -:variable:`PROJECT_NAME` it is necessary to set the VERSION variables +:variable:`PROJECT_NAME` it is necessary to set the ``VERSION`` variables to the empty string when no ``VERSION`` is given to :command:`project`. -However, this can change behavior for existing projects that set VERSION +However, this can change behavior for existing projects that set ``VERSION`` variables themselves since :command:`project` may now clear them. This policy controls the behavior for compatibility with such projects. -The OLD behavior for this policy is to leave VERSION variables untouched. -The NEW behavior for this policy is to set VERSION as documented by the +The ``OLD`` behavior for this policy is to leave ``VERSION`` variables untouched. +The ``NEW`` behavior for this policy is to set ``VERSION`` as documented by the :command:`project` command. This policy was introduced in CMake version 3.0. CMake version |release| warns when the policy is not set and uses -OLD behavior. Use the cmake_policy command to set it to OLD or -NEW explicitly. +``OLD`` behavior. Use the :command:`cmake_policy` command to set +it to ``OLD`` or ``NEW`` explicitly. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0049.rst b/Help/policy/CMP0049.rst index a3ce4b1fa..49b20be17 100644 --- a/Help/policy/CMP0049.rst +++ b/Help/policy/CMP0049.rst @@ -3,23 +3,23 @@ CMP0049 Do not expand variables in target source entries. -CMake 2.8.12 and lower performed and extra layer of variable expansion -when evaluating source file names: - -.. code-block:: cmake +CMake 2.8.12 and lower performed an extra layer of variable expansion +when evaluating source file names:: set(a_source foo.c) add_executable(foo \${a_source}) +.. note: no cmake highlighting since this syntax is deprecated + This was undocumented behavior. -The OLD behavior for this policy is to expand such variables when processing -the target sources. The NEW behavior for this policy is to issue an error +The ``OLD`` behavior for this policy is to expand such variables when processing +the target sources. The ``NEW`` behavior for this policy is to issue an error if such variables need to be expanded. This policy was introduced in CMake version 3.0. CMake version |release| warns when the policy is not set and uses -OLD behavior. Use the cmake_policy command to set it to OLD or -NEW explicitly. +``OLD`` behavior. Use the :command:`cmake_policy` command to set +it to ``OLD`` or ``NEW`` explicitly. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0050.rst b/Help/policy/CMP0050.rst index 39e40b698..27e7b1d50 100644 --- a/Help/policy/CMP0050.rst +++ b/Help/policy/CMP0050.rst @@ -8,13 +8,13 @@ which specified an input to a command. This was undocumented behavior. Modern use of CMake associates custom commands with their output, rather than their input. -The OLD behavior for this policy is to allow the use of -:command:`add_custom_command` SOURCE signatures. The NEW behavior for this +The ``OLD`` behavior for this policy is to allow the use of +:command:`add_custom_command` SOURCE signatures. The ``NEW`` behavior for this policy is to issue an error if such a signature is used. This policy was introduced in CMake version 3.0. CMake version |release| warns when the policy is not set and uses -OLD behavior. Use the cmake_policy command to set it to OLD or -NEW explicitly. +``OLD`` behavior. Use the :command:`cmake_policy` command to set it to ``OLD`` or +``NEW`` explicitly. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0052.rst b/Help/policy/CMP0052.rst index 0ea5ace77..ee2e6e8de 100644 --- a/Help/policy/CMP0052.rst +++ b/Help/policy/CMP0052.rst @@ -1,7 +1,8 @@ CMP0052 ------- -Reject source and build dirs in installed INTERFACE_INCLUDE_DIRECTORIES. +Reject source and build dirs in installed +:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`. CMake 3.0 and lower allowed subdirectories of the source directory or build directory to be in the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of @@ -13,9 +14,9 @@ broken if either are removed after installation. See :ref:`Include Directories and Usage Requirements` for more on specifying include directories for targets. -The OLD behavior for this policy is to export the content of the +The ``OLD`` behavior for this policy is to export the content of the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` with the source or binary -directory. The NEW behavior for this +directory. The ``NEW`` behavior for this policy is to issue an error if such a directory is used. This policy was introduced in CMake version 3.1. diff --git a/Help/policy/CMP0053.rst b/Help/policy/CMP0053.rst index 2620a60e0..032b3e5c6 100644 --- a/Help/policy/CMP0053.rst +++ b/Help/policy/CMP0053.rst @@ -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. diff --git a/Help/policy/CMP0055.rst b/Help/policy/CMP0055.rst index b3df758fe..bc5ad086b 100644 --- a/Help/policy/CMP0055.rst +++ b/Help/policy/CMP0055.rst @@ -7,13 +7,13 @@ CMake 3.1 and lower allowed calls to the :command:`break` command outside of a loop context and also ignored any given arguments. This was undefined behavior. -The OLD behavior for this policy is to allow :command:`break` to be placed -outside of loop contexts and ignores any arguments. The NEW behavior for this +The ``OLD`` behavior for this policy is to allow :command:`break` to be placed +outside of loop contexts and ignores any arguments. The ``NEW`` behavior for this policy is to issue an error if a misplaced break or any arguments are found. This policy was introduced in CMake version 3.2. CMake version |release| warns when the policy is not set and uses -OLD behavior. Use the cmake_policy command to set it to OLD or -NEW explicitly. +``OLD`` behavior. Use the :command:`cmake_policy` command to set it to ``OLD`` or +``NEW`` explicitly. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0056.rst b/Help/policy/CMP0056.rst index 3ba89d576..834da844f 100644 --- a/Help/policy/CMP0056.rst +++ b/Help/policy/CMP0056.rst @@ -14,9 +14,9 @@ the generated project. CMake 3.2 and above prefer to set it so that linker flags are honored as well as compiler flags. This policy provides compatibility with the pre-3.2 behavior. -The OLD behavior for this policy is to not set the value of the +The ``OLD`` behavior for this policy is to not set the value of the :variable:`CMAKE_EXE_LINKER_FLAGS` variable in the generated test -project. The NEW behavior for this policy is to set the value of +project. The ``NEW`` behavior for this policy is to set the value of the :variable:`CMAKE_EXE_LINKER_FLAGS` variable in the test project to the same as it is in the calling project. @@ -27,7 +27,7 @@ variable in the cache. This policy was introduced in CMake version 3.2. Unlike most policies, CMake version |release| does *not* warn by default when this policy -is not set and simply uses OLD behavior. See documentation of the +is not set and simply uses ``OLD`` behavior. See documentation of the :variable:`CMAKE_POLICY_WARNING_CMP0056 <CMAKE_POLICY_WARNING_CMP<NNNN>>` variable to control the warning. diff --git a/Help/policy/CMP0060.rst b/Help/policy/CMP0060.rst index 8611affac..98ac2cf69 100644 --- a/Help/policy/CMP0060.rst +++ b/Help/policy/CMP0060.rst @@ -51,14 +51,14 @@ and link libraries by full path even when they are in implicit link directories. Policy ``CMP0060`` provides compatibility for existing projects. -The OLD behavior for this policy is to ask the linker to search for +The ``OLD`` behavior for this policy is to ask the linker to search for libraries whose full paths are known to be in implicit link directories. -The NEW behavior for this policy is to link libraries by full path even +The ``NEW`` behavior for this policy is to link libraries by full path even if they are in implicit link directories. This policy was introduced in CMake version 3.3. Unlike most policies, CMake version |release| does *not* warn by default when this policy -is not set and simply uses OLD behavior. See documentation of the +is not set and simply uses ``OLD`` behavior. See documentation of the :variable:`CMAKE_POLICY_WARNING_CMP0060 <CMAKE_POLICY_WARNING_CMP<NNNN>>` variable to control the warning. diff --git a/Help/policy/CMP0061.rst b/Help/policy/CMP0061.rst index cb2ac2840..57e4161d0 100644 --- a/Help/policy/CMP0061.rst +++ b/Help/policy/CMP0061.rst @@ -21,6 +21,6 @@ add ``-i``. This policy was introduced in CMake version 3.3. Unlike most policies, CMake version |release| does *not* warn when this policy is not set and -simply uses OLD behavior. +simply uses ``OLD`` behavior. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0062.rst b/Help/policy/CMP0062.rst index 9047fffbe..0db7aafd0 100644 --- a/Help/policy/CMP0062.rst +++ b/Help/policy/CMP0062.rst @@ -1,7 +1,7 @@ CMP0062 ------- -Disallow install() of export() result. +Disallow :command:`install` of :command:`export` result. The :command:`export()` command generates a file containing :ref:`Imported Targets`, which is suitable for use from the build diff --git a/Help/policy/CMP0065.rst b/Help/policy/CMP0065.rst index 2ed775dee..b820aad51 100644 --- a/Help/policy/CMP0065.rst +++ b/Help/policy/CMP0065.rst @@ -20,7 +20,7 @@ property is set to ``True``. This policy was introduced in CMake version 3.4. Unlike most policies, CMake version |release| does *not* warn by default when this policy -is not set and simply uses OLD behavior. See documentation of the +is not set and simply uses ``OLD`` behavior. See documentation of the :variable:`CMAKE_POLICY_WARNING_CMP0065 <CMAKE_POLICY_WARNING_CMP<NNNN>>` variable to control the warning. diff --git a/Help/policy/CMP0066.rst b/Help/policy/CMP0066.rst index d1dcb0ec6..e110ae127 100644 --- a/Help/policy/CMP0066.rst +++ b/Help/policy/CMP0066.rst @@ -20,7 +20,7 @@ variabldes like :variable:`CMAKE_<LANG>_FLAGS_DEBUG`. This policy was introduced in CMake version 3.7. Unlike most policies, CMake version |release| does *not* warn by default when this policy -is not set and simply uses OLD behavior. See documentation of the +is not set and simply uses ``OLD`` behavior. See documentation of the :variable:`CMAKE_POLICY_WARNING_CMP0066 <CMAKE_POLICY_WARNING_CMP<NNNN>>` variable to control the warning. diff --git a/Help/policy/CMP0067.rst b/Help/policy/CMP0067.rst index e6dda8018..f802787ff 100644 --- a/Help/policy/CMP0067.rst +++ b/Help/policy/CMP0067.rst @@ -30,7 +30,7 @@ setting variables. This policy was introduced in CMake version 3.8. Unlike most policies, CMake version |release| does *not* warn by default when this policy -is not set and simply uses OLD behavior. See documentation of the +is not set and simply uses ``OLD`` behavior. See documentation of the :variable:`CMAKE_POLICY_WARNING_CMP0067 <CMAKE_POLICY_WARNING_CMP<NNNN>>` variable to control the warning. diff --git a/Help/policy/CMP0070.rst b/Help/policy/CMP0070.rst new file mode 100644 index 000000000..0fb361779 --- /dev/null +++ b/Help/policy/CMP0070.rst @@ -0,0 +1,25 @@ +CMP0070 +------- + +Define :command:`file(GENERATE)` behavior for relative paths. + +CMake 3.10 and newer define that relative paths given to ``INPUT`` and +``OUTPUT`` arguments of ``file(GENERATE)`` are interpreted relative to the +current source and binary directories, respectively. CMake 3.9 and lower did +not define any behavior for relative paths but did not diagnose them either +and accidentally treated them relative to the process working directory. +Policy ``CMP0070`` provides compatibility with projects that used the old +undefined behavior. + +This policy affects behavior of relative paths given to ``file(GENERATE)``. +The ``OLD`` behavior for this policy is to treat the paths relative to the +working directory of CMake. The ``NEW`` behavior for this policy is to +interpret relative paths with respect to the current source or binary +directory of the caller. + +This policy was introduced in CMake version 3.10. 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 diff --git a/Help/policy/CMP0071.rst b/Help/policy/CMP0071.rst new file mode 100644 index 000000000..855ecf0e9 --- /dev/null +++ b/Help/policy/CMP0071.rst @@ -0,0 +1,42 @@ +CMP0071 +------- + +Let :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` process +:prop_sf:`GENERATED` files. + +Since version 3.10, CMake processes **regular** and :prop_sf:`GENERATED` +source files in :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`. +In earlier CMake versions, only **regular** source files were processed. +:prop_sf:`GENERATED` source files were ignored silently. + +This policy affects how source files that are :prop_sf:`GENERATED` +get treated in :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`. + +The ``OLD`` behavior for this policy is to ignore :prop_sf:`GENERATED` +source files in :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`. + +The ``NEW`` behavior for this policy is to process :prop_sf:`GENERATED` +source files in :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` just like regular +source files. + +.. note:: + + To silence the ``CMP0071`` warning source files can be excluded from + :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` processing by setting the + source file properties :prop_sf:`SKIP_AUTOMOC`, :prop_sf:`SKIP_AUTOUIC` or + :prop_sf:`SKIP_AUTOGEN`. + +Source skip example:: + + # ... + set_property(SOURCE /path/to/file1.h PROPERTY SKIP_AUTOMOC ON) + set_property(SOURCE /path/to/file2.h PROPERTY SKIP_AUTOUIC ON) + set_property(SOURCE /path/to/file3.h PROPERTY SKIP_AUTOGEN ON) + # ... + +This policy was introduced in CMake version 3.10. 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 diff --git a/Help/policy/CMP0072.rst b/Help/policy/CMP0072.rst new file mode 100644 index 000000000..3abbad790 --- /dev/null +++ b/Help/policy/CMP0072.rst @@ -0,0 +1,26 @@ +CMP0072 +------- + +:module:`FindOpenGL` prefers GLVND by default when available. + +The :module:`FindOpenGL` module provides an ``OpenGL::GL`` target and an +``OPENGL_LIBRARIES`` variable for projects to use for legacy GL interfaces. +When both a legacy GL library (e.g. ``libGL.so``) and GLVND libraries +for OpenGL and GLX (e.g. ``libOpenGL.so`` and ``libGLX.so``) are available, +the module must choose between them. It documents an ``OpenGL_GL_PREFERENCE`` +variable that can be used to specify an explicit preference. When no such +preference is set, the module must choose a default preference. + +CMake 3.11 and above prefer to choose GLVND libraries. This policy provides +compatibility with projects that expect the legacy GL library to be used. + +The ``OLD`` behavior for this policy is to set ``OpenGL_GL_PREFERENCE`` to +``LEGACY``. The ``NEW`` behavior for this policy is to set +``OpenGL_GL_PREFERENCE`` to ``GLVND``. + +This policy was introduced in CMake version 3.11. 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 diff --git a/Help/policy/CMP0073.rst b/Help/policy/CMP0073.rst new file mode 100644 index 000000000..9bfa0e905 --- /dev/null +++ b/Help/policy/CMP0073.rst @@ -0,0 +1,25 @@ +CMP0073 +------- + +Do not produce legacy ``_LIB_DEPENDS`` cache entries. + +Ancient CMake versions once used ``<tgt>_LIB_DEPENDS`` cache entries to +propagate library link dependencies. This has long been done by other +means, leaving the :command:`export_library_dependencies` command as the +only user of these values. That command has long been disallowed by +policy :policy:`CMP0033`, but the ``<tgt>_LIB_DEPENDS`` cache entries +were left for compatibility with possible non-standard uses by projects. + +CMake 3.12 and above now prefer to not produce these cache entries +at all. This policy provides compatibility with projects that have +not been updated to avoid using them. + +The ``OLD`` behavior for this policy is to set ``<tgt>_LIB_DEPENDS`` cache +entries. The ``NEW`` behavior for this policy is to not set them. + +This policy was introduced in CMake version 3.12. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +Unlike most policies, CMake version |release| does *not* warn +when this policy is not set and simply uses ``OLD`` behavior. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0074.rst b/Help/policy/CMP0074.rst new file mode 100644 index 000000000..63ebf7b43 --- /dev/null +++ b/Help/policy/CMP0074.rst @@ -0,0 +1,23 @@ +CMP0074 +------- + +:command:`find_package` uses ``<PackageName>_ROOT`` variables. + +In CMake 3.12 and above the :command:`find_package(<PackageName>)` command now +searches prefixes specified by the :variable:`<PackageName>_ROOT` CMake +variable and the :envvar:`<PackageName>_ROOT` environment variable. +Package roots are maintained as a stack so nested calls to all ``find_*`` +commands inside find modules and config packages also search the roots as +prefixes. This policy provides compatibility with projects that have not been +updated to avoid using ``<PackageName>_ROOT`` variables for other purposes. + +The ``OLD`` behavior for this policy is to ignore ``<PackageName>_ROOT`` +variables. The ``NEW`` behavior for this policy is to use +``<PackageName>_ROOT`` variables. + +This policy was introduced in CMake version 3.12. 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 diff --git a/Help/policy/CMP0075.rst b/Help/policy/CMP0075.rst new file mode 100644 index 000000000..aa5c3f76f --- /dev/null +++ b/Help/policy/CMP0075.rst @@ -0,0 +1,26 @@ +CMP0075 +------- + +Include file check macros honor ``CMAKE_REQUIRED_LIBRARIES``. + +In CMake 3.12 and above, the + +* ``check_include_file`` macro in the :module:`CheckIncludeFile` module, the +* ``check_include_file_cxx`` macro in the + :module:`CheckIncludeFileCXX` module, and the +* ``check_include_files`` macro in the :module:`CheckIncludeFiles` module + +now prefer to link the check executable to the libraries listed in the +``CMAKE_REQUIRED_LIBRARIES`` variable. This policy provides compatibility +with projects that have not been updated to expect this behavior. + +The ``OLD`` behavior for this policy is to ignore ``CMAKE_REQUIRED_LIBRARIES`` +in the include file check macros. The ``NEW`` behavior of this policy is to +honor ``CMAKE_REQUIRED_LIBRARIES`` in the include file check macros. + +This policy was introduced in CMake version 3.12. 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 diff --git a/Help/policy/CMP0076.rst b/Help/policy/CMP0076.rst new file mode 100644 index 000000000..dd25f80c6 --- /dev/null +++ b/Help/policy/CMP0076.rst @@ -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 diff --git a/Help/policy/CMP0077.rst b/Help/policy/CMP0077.rst new file mode 100644 index 000000000..44797b648 --- /dev/null +++ b/Help/policy/CMP0077.rst @@ -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 diff --git a/Help/policy/CMP0078.rst b/Help/policy/CMP0078.rst new file mode 100644 index 000000000..2e97934f4 --- /dev/null +++ b/Help/policy/CMP0078.rst @@ -0,0 +1,24 @@ +CMP0078 +------- + +:module:`UseSWIG` generates standard target names. + +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 diff --git a/Help/policy/CMP0079.rst b/Help/policy/CMP0079.rst new file mode 100644 index 000000000..0244d6ca6 --- /dev/null +++ b/Help/policy/CMP0079.rst @@ -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 diff --git a/Help/policy/CMP0080.rst b/Help/policy/CMP0080.rst new file mode 100644 index 000000000..5ce9591da --- /dev/null +++ b/Help/policy/CMP0080.rst @@ -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 diff --git a/Help/policy/CMP0081.rst b/Help/policy/CMP0081.rst new file mode 100644 index 000000000..d3b2872c4 --- /dev/null +++ b/Help/policy/CMP0081.rst @@ -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 diff --git a/Help/policy/CMP0082.rst b/Help/policy/CMP0082.rst new file mode 100644 index 000000000..d887616be --- /dev/null +++ b/Help/policy/CMP0082.rst @@ -0,0 +1,26 @@ +CMP0082 +------- + +Install rules from :command:`add_subdirectory` calls are interleaved with +those in caller. + +CMake 3.13 and lower ran the install rules from :command:`add_subdirectory` +after all other install rules, even if :command:`add_subdirectory` was called +before the other install rules. CMake 3.14 and above prefer to interleave +these :command:`add_subdirectory` install rules with the others so that +they are run in the order they are declared. This policy provides +compatibility for projects that have not been updated to expect the +new behavior. + +The ``OLD`` behavior for this policy is to run the install rules from +:command:`add_subdirectory` after the other install rules. The ``NEW`` +behavior for this policy is to run all install rules in the order they are +declared. + +This policy was introduced in CMake version 3.14. Unlike most policies, +CMake version |release| does *not* warn by default when this policy +is not set and simply uses ``OLD`` behavior. See documentation of the +:variable:`CMAKE_POLICY_WARNING_CMP0082 <CMAKE_POLICY_WARNING_CMP<NNNN>>` +variable to control the warning. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0083.rst b/Help/policy/CMP0083.rst new file mode 100644 index 000000000..e0b09cff5 --- /dev/null +++ b/Help/policy/CMP0083.rst @@ -0,0 +1,69 @@ +CMP0083 +------- + +To control generation of Position Independent Executable (``PIE``) or not, some +flags are required at link time. + +CMake 3.13 and lower did not add these link flags when +:prop_tgt:`POSITION_INDEPENDENT_CODE` is set. + +The ``OLD`` behavior for this policy is to not manage ``PIE`` link flags. The +``NEW`` behavior is to add link flags if :prop_tgt:`POSITION_INDEPENDENT_CODE` +is set: + +* Set to ``TRUE``: flags to produce a position independent executable are + passed to the linker step. For example ``-pie`` for ``GCC``. +* Set to ``FALSE``: flags not to produce a position independent executable are + passed to the linker step. For example ``-no-pie`` for ``GCC``. +* Not set: no flags are passed to the linker step. + +Since a given linker may not support ``PIE`` flags in all environments in +which it is used, it is the project's responsibility to use the +:module:`CheckPIESupported` module to check for support to ensure that the +:prop_tgt:`POSITION_INDEPENDENT_CODE` target property for executables will be +honored at link time. + +This policy was introduced in CMake version 3.14. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +Unlike most policies, CMake version |release| does not warn when this policy is +not set and simply uses ``OLD`` behavior. + +.. Note:: + + Android platform has a special handling of ``PIE`` so it is not required + to use the :module:`CheckPIESupported` module to ensure flags are passed to + the linker. + +.. include:: DEPRECATED.txt + +Examples +^^^^^^^^ + +Behave like CMake 3.13 and do not apply any ``PIE`` flags at link stage. + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.13) + project(foo) + + # ... + + add_executable(foo ...) + set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE) + +Use the :module:`CheckPIESupported` module to detect whether ``PIE`` is +supported by the current linker and environment. Apply ``PIE`` flags only +if the linker supports them. + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.14) # CMP0083 NEW + project(foo) + + include(CheckPIESupported) + check_pie_supported() + + # ... + + add_executable(foo ...) + set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE) diff --git a/Help/policy/CMP0084.rst b/Help/policy/CMP0084.rst new file mode 100644 index 000000000..713d295f8 --- /dev/null +++ b/Help/policy/CMP0084.rst @@ -0,0 +1,26 @@ +CMP0084 +------- + +The :module:`FindQt` module does not exist for :command:`find_package`. + +The existence of :module:`FindQt` means that for Qt upstream to provide +package config files that can be found by ``find_package(Qt)``, the consuming +project has to explicitly specify ``find_package(Qt CONFIG)``. Removing this +module gives Qt a path forward for exporting its own config files which can +easily be found by consuming projects. + +This policy pretends that CMake's internal :module:`FindQt` module does not +exist for :command:`find_package`. If a project really wants to use Qt 3 or 4, +it can call ``find_package(Qt[34])``, ``include(FindQt)``, or add +:module:`FindQt` to their :variable:`CMAKE_MODULE_PATH`. + +The ``OLD`` behavior of this policy is for :module:`FindQt` to exist for +:command:`find_package`. The ``NEW`` behavior is to pretend that it doesn't +exist for :command:`find_package`. + +This policy was introduced in CMake version 3.14. 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 diff --git a/Help/policy/CMP0085.rst b/Help/policy/CMP0085.rst new file mode 100644 index 000000000..d9ec9a207 --- /dev/null +++ b/Help/policy/CMP0085.rst @@ -0,0 +1,21 @@ +CMP0085 +------- + +``$<IN_LIST:...>`` handles empty list items. + +In CMake 3.13 and lower, the ``$<IN_LIST:...>`` generator expression always +returned ``0`` if the first argument was empty, even if the list contained an +empty item. This behavior is inconsistent with the ``IN_LIST`` behavior of +:command:`if`, which this generator expression is meant to emulate. CMake 3.14 +and later handles this case correctly. + +The ``OLD`` behavior of this policy is for ``$<IN_LIST:...>`` to always return +``0`` if the first argument is empty. The ``NEW`` behavior is to return ``1`` +if the first argument is empty and the list contains an empty item. + +This policy was introduced in CMake version 3.14. 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 diff --git a/Help/policy/CMP0086.rst b/Help/policy/CMP0086.rst new file mode 100644 index 000000000..4a9e8b80a --- /dev/null +++ b/Help/policy/CMP0086.rst @@ -0,0 +1,20 @@ +CMP0086 +------- + +:module:`UseSWIG` honors ``SWIG_MODULE_NAME`` via ``-module`` flag. + +Starting with CMake 3.14, :module:`UseSWIG` passes option +``-module <module_name>`` to ``SWIG`` compiler if the file property +``SWIG_MODULE_NAME`` is specified. This policy provides compatibility with +projects that expect the legacy behavior. + +The ``OLD`` behavior for this policy is to never pass ``-module`` option. +The ``NEW`` behavior is to pass ``-module`` option to ``SWIG`` compiler if +``SWIG_MODULE_NAME`` is specified. + +This policy was introduced in CMake version 3.14. 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 diff --git a/Help/policy/CMP0087.rst b/Help/policy/CMP0087.rst new file mode 100644 index 000000000..4c45b99e4 --- /dev/null +++ b/Help/policy/CMP0087.rst @@ -0,0 +1,29 @@ +CMP0087 +------- + +:command:`install(CODE)` and :command:`install(SCRIPT)` support generator +expressions. + +In CMake 3.13 and earlier, :command:`install(CODE)` and +:command:`install(SCRIPT)` did not evaluate generator expressions. CMake 3.14 +and later will evaluate generator expressions for :command:`install(CODE)` and +:command:`install(SCRIPT)`. + +The ``OLD`` behavior of this policy is for :command:`install(CODE)` and +:command:`install(SCRIPT)` to not evaluate generator expressions. The ``NEW`` +behavior is to evaluate generator expressions for :command:`install(CODE)` and +:command:`install(SCRIPT)`. + +Note that it is the value of this policy setting at the end of the directory +scope that is important, not its setting at the time of the call to +:command:`install(CODE)` or :command:`install(SCRIPT)`. This has implications +for calling these commands from places that have their own policy scope but not +their own directory scope (e.g. from files brought in via :command:`include()` +rather than :command:`add_subdirectory()`). + +This policy was introduced in CMake version 3.14. 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 diff --git a/Help/policy/CMP0088.rst b/Help/policy/CMP0088.rst new file mode 100644 index 000000000..82c04ef7b --- /dev/null +++ b/Help/policy/CMP0088.rst @@ -0,0 +1,29 @@ +CMP0088 +------- + +:module:`FindBISON` runs bison in :variable:`CMAKE_CURRENT_BINARY_DIR` +when executing. + +The module provides a ``BISON_TARGET`` macro which generates BISON output. +In CMake 3.13 and below the macro would generate a custom command that runs +``bison`` in the source directory. CMake 3.14 and later prefer to run it +in the build directory and use :variable:`CMAKE_CURRENT_BINARY_DIR` as the +``WORKING_DIRECTORY`` of its :command:`add_custom_command` invocation. +This ensures that any implicitly generated file is written to the build +tree rather than the source. + +This policy provides compatibility for projects that have not been updated +to expect the new behavior. + +The ``OLD`` behavior for this policy is for ``BISON_TARGET`` to use +the current source directory for the ``WORKING_DIRECTORY`` and where +to generate implicit files. The ``NEW`` behavior of this policy is to +use the current binary directory for the ``WORKING_DIRECTORY`` and where +to generate implicit files. + +This policy was introduced in CMake version 3.14. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +Unlike most policies, CMake version |release| does *not* warn +when this policy is not set and simply uses ``OLD`` behavior. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0089.rst b/Help/policy/CMP0089.rst new file mode 100644 index 000000000..029de5534 --- /dev/null +++ b/Help/policy/CMP0089.rst @@ -0,0 +1,30 @@ +CMP0089 +------- + +Compiler id for IBM Clang-based XL compilers is now ``XLClang``. + +CMake 3.15 and above recognize that IBM's Clang-based XL compilers +that define ``__ibmxl__`` are a new front-end distinct from ``xlc`` +with a different command line and set of capabilities. +CMake now prefers to present this to projects by setting the +:variable:`CMAKE_<LANG>_COMPILER_ID` variable to ``XLClang`` instead +of ``XL``. However, existing projects may assume the compiler id for +Clang-based XL is just ``XL`` as it was in CMake versions prior to 3.15. +Therefore this policy determines for Clang-based XL compilers which +compiler id to report in the :variable:`CMAKE_<LANG>_COMPILER_ID` +variable after language ``<LANG>`` is enabled by the :command:`project` +or :command:`enable_language` command. The policy must be set prior +to the invocation of either command. + +The ``OLD`` behavior for this policy is to use compiler id ``XL``. The +``NEW`` behavior for this policy is to use compiler id ``XLClang``. + +This policy was introduced in CMake version 3.15. Use the +:command:`cmake_policy` command to set this policy to ``OLD`` or ``NEW`` explicitly. +Unlike most policies, CMake version |release| does *not* warn +by default when this policy is not set and simply uses ``OLD`` behavior. +See documentation of the +:variable:`CMAKE_POLICY_WARNING_CMP0089 <CMAKE_POLICY_WARNING_CMP<NNNN>>` +variable to control the warning. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0090.rst b/Help/policy/CMP0090.rst new file mode 100644 index 000000000..720c17c2a --- /dev/null +++ b/Help/policy/CMP0090.rst @@ -0,0 +1,27 @@ +CMP0090 +------- + +:command:`export(PACKAGE)` does not populate package registry by default. + +In CMake 3.14 and below the :command:`export(PACKAGE)` command populated the +user package registry by default and users needed to set the +:variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` to disable it, e.g. in automated +build and packaging environments. Since the user package registry is stored +outside the build tree, this side effect should not be enabled by default. +Therefore CMake 3.15 and above prefer that :command:`export(PACKAGE)` does +nothing unless an explicit :variable:`CMAKE_EXPORT_PACKAGE_REGISTRY` variable +is set to enable it. This policy provides compatibility with projects that +have not been updated. + +The ``OLD`` behavior for this policy is for :command:`export(PACKAGE)` command +to populate the user package registry unless +:variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` is enabled. +The ``NEW`` behavior is for :command:`export(PACKAGE)` command to do nothing +unless the :variable:`CMAKE_EXPORT_PACKAGE_REGISTRY` is enabled. + +This policy was introduced in CMake version 3.15. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +Unlike most policies, CMake version |release| does *not* warn +when this policy is not set and simply uses ``OLD`` behavior. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0091.rst b/Help/policy/CMP0091.rst new file mode 100644 index 000000000..1a5878a1f --- /dev/null +++ b/Help/policy/CMP0091.rst @@ -0,0 +1,49 @@ +CMP0091 +------- + +MSVC runtime library flags are selected by an abstraction. + +Compilers targeting the MSVC ABI have flags to select the MSVC runtime library. +Runtime library selection typically varies with build configuration because +there is a separate runtime library for Debug builds. + +In CMake 3.14 and below, MSVC runtime library selection flags are added to +the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` cache entries by CMake +automatically. This allows users to edit their cache entries to adjust the +flags. However, the presence of such default flags is problematic for +projects that want to choose a different runtime library programmatically. +In particular, it requires string editing of the +:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` variables with knowledge of the +CMake builtin defaults so they can be replaced. + +CMake 3.15 and above prefer to leave the MSVC runtime library selection flags +out of the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` values and instead +offer a first-class abstraction. The :variable:`CMAKE_MSVC_RUNTIME_LIBRARY` +variable and :prop_tgt:`MSVC_RUNTIME_LIBRARY` target property may be set to +select the MSVC runtime library. If they are not set then CMake uses the +default value ``MultiThreaded$<$<CONFIG:Debug>:Debug>DLL`` which is +equivalent to the original flags. + +This policy provides compatibility with projects that have not been updated +to be aware of the abstraction. The policy setting takes effect as of the +first :command:`project` or :command:`enable_language` command that enables +a language whose compiler targets the MSVC ABI. + +.. note:: + + Once the policy has taken effect at the top of a project, that choice + must be used throughout the tree. In projects that have nested projects + in subdirectories, be sure to convert everything together. + +The ``OLD`` behavior for this policy is to place MSVC runtime library +flags in the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` cache +entries and ignore the :variable:`CMAKE_MSVC_RUNTIME_LIBRARY` abstraction. +The ``NEW`` behavior for this policy is to *not* place MSVC runtime +library flags in the default cache entries and use the abstraction instead. + +This policy was introduced in CMake version 3.15. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +Unlike many policies, CMake version |release| does *not* warn +when this policy is not set and simply uses ``OLD`` behavior. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0092.rst b/Help/policy/CMP0092.rst new file mode 100644 index 000000000..8d3a288ae --- /dev/null +++ b/Help/policy/CMP0092.rst @@ -0,0 +1,38 @@ +CMP0092 +------- + +MSVC warning flags are not in :variable:`CMAKE_<LANG>_FLAGS` by default. + +When using MSVC-like compilers in CMake 3.14 and below, warning flags +like ``/W3`` are added to :variable:`CMAKE_<LANG>_FLAGS` by default. +This is problematic for projects that want to choose a different warning +level programmatically. In particular, it requires string editing of the +:variable:`CMAKE_<LANG>_FLAGS` variables with knowledge of the +CMake builtin defaults so they can be replaced. + +CMake 3.15 and above prefer to leave out warning flags from the value of +:variable:`CMAKE_<LANG>_FLAGS` by default. + +This policy provides compatibility with projects that have not been updated +to expect the lack of warning flags. The policy setting takes effect as of +the first :command:`project` or :command:`enable_language` command that +initializes :variable:`CMAKE_<LANG>_FLAGS` for a given lanuage ``<LANG>``. + +.. note:: + + Once the policy has taken effect at the top of a project for a given + language, that choice must be used throughout the tree for that language. + In projects that have nested projects in subdirectories, be sure to + convert everything together. + +The ``OLD`` behavior for this policy is to place MSVC warning flags in the +default :variable:`CMAKE_<LANG>_FLAGS` cache entries. The ``NEW`` behavior +for this policy is to *not* place MSVC warning flags in the default cache +entries. + +This policy was introduced in CMake version 3.15. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +Unlike many policies, CMake version |release| does *not* warn +when this policy is not set and simply uses ``OLD`` behavior. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0093.rst b/Help/policy/CMP0093.rst new file mode 100644 index 000000000..0ffc493de --- /dev/null +++ b/Help/policy/CMP0093.rst @@ -0,0 +1,24 @@ +CMP0093 +------- + +:module:`FindBoost` reports ``Boost_VERSION`` in ``x.y.z`` format. + +In CMake 3.14 and below the module would report the Boost version +number as specified in the preprocessor definition ``BOOST_VERSION`` in +the ``boost/version.hpp`` file. In CMake 3.15 and later it is preferred +that the reported version number matches the ``x.y.z`` format reported +by the CMake package shipped with Boost ``1.70.0`` and later. The macro +value is still reported in the ``Boost_VERSION_MACRO`` variable. + +The ``OLD`` behavior for this policy is for :module:`FindBoost` to report +``Boost_VERSION`` as specified in the preprocessor definition +``BOOST_VERSION`` in ``boost/version.hpp``. The ``NEW`` behavior for this +policy is for :module:`FindBoost` to report ``Boost_VERSION`` in +``x.y.z`` format. + +This policy was introduced in CMake version 3.15. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +Unlike many policies, CMake version |release| does *not* warn +when this policy is not set and simply uses the ``OLD`` behavior. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0094.rst b/Help/policy/CMP0094.rst new file mode 100644 index 000000000..836f30f09 --- /dev/null +++ b/Help/policy/CMP0094.rst @@ -0,0 +1,22 @@ +CMP0094 +------- + +Modules :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython` +use ``LOCATION`` for lookup strategy. + +Starting with CMake 3.15, Modules :module:`FindPython3`, :module:`FindPython2` +and :module:`FindPython` set value ``LOCATION`` for, respectively, variables +``Python3_FIND_STRATEGY``, ``Python2_FIND_STRATEGY`` and +``Python_FIND_STRATEGY``. This policy provides compatibility with projects that +expect the legacy behavior. + +The ``OLD`` behavior for this policy set value ``VERSION`` for variables +``Python3_FIND_STRATEGY``, ``Python2_FIND_STRATEGY`` and +``Python_FIND_STRATEGY``. + +This policy was introduced in CMake version 3.15. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +Unlike many policies, CMake version |release| does *not* warn +when this policy is not set and simply uses the ``OLD`` behavior. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0095.rst b/Help/policy/CMP0095.rst new file mode 100644 index 000000000..4c56a0524 --- /dev/null +++ b/Help/policy/CMP0095.rst @@ -0,0 +1,30 @@ +CMP0095 +------- + +``RPATH`` entries are properly escaped in the intermediary CMake install script. + +In CMake 3.15 and earlier, ``RPATH`` entries set via +:variable:`CMAKE_INSTALL_RPATH` or via :prop_tgt:`INSTALL_RPATH` have not been +escaped before being inserted into the ``cmake_install.cmake`` script. Dynamic +linkers on ELF-based systems (e.g. Linux and FreeBSD) allow certain keywords in +``RPATH`` entries, such as ``${ORIGIN}`` (More details are available in the +``ld.so`` man pages on those systems). The syntax of these keywords can match +CMake's variable syntax. In order to not be substituted (usually to an empty +string) already by the intermediary ``cmake_install.cmake`` script, the user had +to double-escape such ``RPATH`` keywords, e.g. +``set(CMAKE_INSTALL_RPATH "\\\${ORIGIN}/../lib")``. Since the intermediary +``cmake_install.cmake`` script is an implementation detail of CMake, CMake 3.16 +and later will make sure ``RPATH`` entries are inserted literally by escaping +any coincidental CMake syntax. + +The ``OLD`` behavior of this policy is to not escape ``RPATH`` entries in the +intermediary ``cmake_install.cmake`` script. The ``NEW`` behavior is to properly +escape coincidental CMake syntax in ``RPATH`` entries when generating the +intermediary ``cmake_install.cmake`` script. + +This policy was introduced in CMake version 3.16. CMake version |release| warns +when the policy is not set and detected usage of CMake-like syntax and uses +``OLD`` behavior. Use the :command:`cmake_policy` command to set it to ``OLD`` +or ``NEW`` explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0096.rst b/Help/policy/CMP0096.rst new file mode 100644 index 000000000..8eaf0f95d --- /dev/null +++ b/Help/policy/CMP0096.rst @@ -0,0 +1,25 @@ +CMP0096 +------- + +The :command:`project` command preserves leading zeros in version components. + +When a ``VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]`` argument is given +to the :command:`project` command, it stores the version string in the +``PROJECT_VERSION`` variable and stores individual integer version components +in ``PROJECT_VERSION_{MAJOR,MINOR,PATCH,TWEAK}`` variables (see policy +:policy:`CMP0048`). CMake 3.15 and below dropped leading zeros from each +component. CMake 3.16 and higher prefer to preserve leading zeros. This +policy provides compatibility for projects that have not been updated to +expect the new behavior. + +The ``OLD`` behavior of this policy drops leading zeros in all components, +e.g. such that version ``1.07.06`` becomes ``1.7.6``. The ``NEW`` behavior +of this policy preserves the leading zeros in all components, such that +version ``1.07.06`` remains unchanged. + +This policy was introduced in CMake version 3.16. Unlike many policies, CMake +version |release| does *not* warn when this policy is not set and simply uses +the ``OLD`` behavior. Use the :command:`cmake_policy` command to set it to +``OLD`` or ``NEW`` explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0097.rst b/Help/policy/CMP0097.rst new file mode 100644 index 000000000..4840aa69d --- /dev/null +++ b/Help/policy/CMP0097.rst @@ -0,0 +1,23 @@ +CMP0097 +------- + +:command:`ExternalProject_Add` with ``GIT_SUBMODULES ""`` initializes no +submodules. + +The module provides a ``GIT_SUBMODULES`` option which controls what submodules +to initialize and update. Starting with CMake 3.16, explicitly setting +``GIT_SUBMODULES`` to an empty string means no submodules will be initialized +or updated. + +This policy provides compatibility for projects that have not been updated +to expect the new behavior. + +The ``OLD`` behavior for this policy is for ``GIT_SUBMODULES`` when set to +an empty string to initialize and update all git submodules. +The ``NEW`` behavior for this policy is for ``GIT_SUBMODULES`` when set to +an empty string to initialize and update no git submodules. + +This policy was introduced in CMake version 3.16. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +Unlike most policies, CMake version |release| does *not* warn +when this policy is not set and simply uses ``OLD`` behavior. diff --git a/Help/policy/DISALLOWED_COMMAND.txt b/Help/policy/DISALLOWED_COMMAND.txt index 36280d2b6..6500bb0f3 100644 --- a/Help/policy/DISALLOWED_COMMAND.txt +++ b/Help/policy/DISALLOWED_COMMAND.txt @@ -1,9 +1,9 @@ CMake >= |disallowed_version| prefer that this command never be called. -The OLD behavior for this policy is to allow the command to be called. -The NEW behavior for this policy is to issue a FATAL_ERROR when the +The ``OLD`` behavior for this policy is to allow the command to be called. +The ``NEW`` behavior for this policy is to issue a ``FATAL_ERROR`` when the command is called. This policy was introduced in CMake version |disallowed_version|. CMake version |release| warns when the policy is not set and uses -OLD behavior. Use the cmake_policy command to set it to OLD or -NEW explicitly. +``OLD`` behavior. Use the :command:`cmake_policy` command to set it to ``OLD`` or +``NEW`` explicitly. diff --git a/Help/prop_cache/ADVANCED.rst b/Help/prop_cache/ADVANCED.rst index a0a4f73bb..ec4de9d85 100644 --- a/Help/prop_cache/ADVANCED.rst +++ b/Help/prop_cache/ADVANCED.rst @@ -4,5 +4,5 @@ ADVANCED True if entry should be hidden by default in GUIs. This is a boolean value indicating whether the entry is considered -interesting only for advanced configuration. The mark_as_advanced() +interesting only for advanced configuration. The :command:`mark_as_advanced` command modifies this property. diff --git a/Help/prop_cache/STRINGS.rst b/Help/prop_cache/STRINGS.rst index 2f8e32e3f..0e3c326d2 100644 --- a/Help/prop_cache/STRINGS.rst +++ b/Help/prop_cache/STRINGS.rst @@ -1,9 +1,9 @@ STRINGS ------- -Enumerate possible STRING entry values for GUI selection. +Enumerate possible ``STRING`` entry values for GUI selection. -For cache entries with type STRING, this enumerates a set of values. +For cache entries with type ``STRING``, this enumerates a set of values. CMake GUIs may use this to provide a selection widget instead of a generic string entry field. This is for convenience only. CMake does not enforce that the value matches one of those listed. diff --git a/Help/prop_cache/TYPE.rst b/Help/prop_cache/TYPE.rst index eb75c2ab2..7ca859f68 100644 --- a/Help/prop_cache/TYPE.rst +++ b/Help/prop_cache/TYPE.rst @@ -5,7 +5,7 @@ Widget type for entry in GUIs. Cache entry values are always strings, but CMake GUIs present widgets to help users set values. The GUIs use this property as a hint to -determine the widget type. Valid TYPE values are: +determine the widget type. Valid ``TYPE`` values are: :: @@ -17,5 +17,5 @@ determine the widget type. Valid TYPE values are: STATIC = Value managed by CMake, do not change. UNINITIALIZED = Type not yet specified. -Generally the TYPE of a cache entry should be set by the command which -creates it (set, option, find_library, etc.). +Generally the ``TYPE`` of a cache entry should be set by the command which +creates it ( :command:`set`, :command:`option`, :command:`find_library`, etc.). diff --git a/Help/prop_dir/ADDITIONAL_CLEAN_FILES.rst b/Help/prop_dir/ADDITIONAL_CLEAN_FILES.rst new file mode 100644 index 000000000..051d22a81 --- /dev/null +++ b/Help/prop_dir/ADDITIONAL_CLEAN_FILES.rst @@ -0,0 +1,21 @@ +ADDITIONAL_CLEAN_FILES +---------------------- + +A :ref:`;-list <CMake Language Lists>` of files or directories that will be +removed as a part of the global ``clean`` target. It is useful for +specifying generated files or directories that are used by multiple targets +or by CMake itself, or that are generated in ways which cannot be captured as +outputs or byproducts of custom commands. + +If an additional clean file is specific to a single target only, then the +:prop_tgt:`ADDITIONAL_CLEAN_FILES` target property would usually be a better +choice than this directory property. + +Relative paths are allowed and are interpreted relative to the +current binary directory. + +Contents of ``ADDITIONAL_CLEAN_FILES`` may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. + +This property only works for the :generator:`Ninja` and the Makefile +generators. It is ignored by other generators. diff --git a/Help/prop_dir/ADDITIONAL_MAKE_CLEAN_FILES.rst b/Help/prop_dir/ADDITIONAL_MAKE_CLEAN_FILES.rst index e32eed3ed..b6f616099 100644 --- a/Help/prop_dir/ADDITIONAL_MAKE_CLEAN_FILES.rst +++ b/Help/prop_dir/ADDITIONAL_MAKE_CLEAN_FILES.rst @@ -1,7 +1,17 @@ ADDITIONAL_MAKE_CLEAN_FILES --------------------------- -Additional files to clean during the make clean stage. +.. deprecated:: 3.15 -A list of files that will be cleaned as a part of the "make clean" -stage. + Use :prop_dir:`ADDITIONAL_CLEAN_FILES` instead. + +Additional files to remove during the clean stage. + +A :ref:`;-list <CMake Language Lists>` of files that will be removed as a +part of the ``make clean`` target. + +Arguments to :prop_dir:`ADDITIONAL_MAKE_CLEAN_FILES` may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. + +This property only works for the Makefile generators. +It is ignored on other generators. diff --git a/Help/prop_dir/BUILDSYSTEM_TARGETS.rst b/Help/prop_dir/BUILDSYSTEM_TARGETS.rst index da907cb93..04bb56ec1 100644 --- a/Help/prop_dir/BUILDSYSTEM_TARGETS.rst +++ b/Help/prop_dir/BUILDSYSTEM_TARGETS.rst @@ -2,7 +2,7 @@ BUILDSYSTEM_TARGETS ------------------- This read-only directory property contains a -:ref:`;-list <CMake Language Lists>` of buildsystem targets added in the +:ref:`semicolon-separated list <CMake Language Lists>` of buildsystem targets added in the directory by calls to the :command:`add_library`, :command:`add_executable`, and :command:`add_custom_target` commands. The list does not include any :ref:`Imported Targets` or :ref:`Alias Targets`, but does include diff --git a/Help/prop_dir/COMPILE_DEFINITIONS.rst b/Help/prop_dir/COMPILE_DEFINITIONS.rst index 85adcb58a..18f4567c5 100644 --- a/Help/prop_dir/COMPILE_DEFINITIONS.rst +++ b/Help/prop_dir/COMPILE_DEFINITIONS.rst @@ -4,7 +4,7 @@ COMPILE_DEFINITIONS Preprocessor definitions for compiling a directory's sources. This property specifies the list of options given so far to the -:command:`add_definitions` command. +:command:`add_compile_definitions` (or :command:`add_definitions`) command. The ``COMPILE_DEFINITIONS`` property may be set to a semicolon-separated list of preprocessor definitions using the syntax ``VAR`` or ``VAR=value``. diff --git a/Help/prop_dir/COMPILE_OPTIONS.rst b/Help/prop_dir/COMPILE_OPTIONS.rst index 877deb000..48e8b9b8d 100644 --- a/Help/prop_dir/COMPILE_OPTIONS.rst +++ b/Help/prop_dir/COMPILE_OPTIONS.rst @@ -3,7 +3,7 @@ COMPILE_OPTIONS List of options to pass to the compiler. -This property holds a :ref:`;-list <CMake Language Lists>` of options +This property holds a :ref:`semicolon-separated list <CMake Language Lists>` of options given so far to the :command:`add_compile_options` command. This property is used to initialize the :prop_tgt:`COMPILE_OPTIONS` target diff --git a/Help/prop_dir/EXCLUDE_FROM_ALL.rst b/Help/prop_dir/EXCLUDE_FROM_ALL.rst index 1aa24e44b..8e3cca0c2 100644 --- a/Help/prop_dir/EXCLUDE_FROM_ALL.rst +++ b/Help/prop_dir/EXCLUDE_FROM_ALL.rst @@ -1,9 +1,13 @@ EXCLUDE_FROM_ALL ---------------- -Exclude the directory from the all target of its parent. +Set this directory property to a true value on a subdirectory to exclude +its targets from the "all" target of its ancestors. If excluded, running +e.g. ``make`` in the parent directory will not build targets the +subdirectory by default. This does not affect the "all" target of the +subdirectory itself. Running e.g. ``make`` inside the subdirectory will +still build its targets. -A property on a directory that indicates if its targets are excluded -from the default build target. If it is not, then with a Makefile for -example typing make will cause the targets to be built. The same -concept applies to the default build of other generators. +If the :prop_tgt:`EXCLUDE_FROM_ALL` target property is set on a target +then its value determines whether the target is included in the "all" +target of this directory and its ancestors. diff --git a/Help/prop_dir/IMPLICIT_DEPENDS_INCLUDE_TRANSFORM.rst b/Help/prop_dir/IMPLICIT_DEPENDS_INCLUDE_TRANSFORM.rst index 993f6200e..f5349763a 100644 --- a/Help/prop_dir/IMPLICIT_DEPENDS_INCLUDE_TRANSFORM.rst +++ b/Help/prop_dir/IMPLICIT_DEPENDS_INCLUDE_TRANSFORM.rst @@ -1,15 +1,15 @@ IMPLICIT_DEPENDS_INCLUDE_TRANSFORM ---------------------------------- -Specify #include line transforms for dependencies in a directory. +Specify ``#include`` line transforms for dependencies in a directory. -This property specifies rules to transform macro-like #include lines +This property specifies rules to transform macro-like ``#include`` lines during implicit dependency scanning of C and C++ source files. The list of rules must be semicolon-separated with each entry of the form -"A_MACRO(%)=value-with-%" (the % must be literal). During dependency -scanning occurrences of A_MACRO(...) on #include lines will be +``A_MACRO(%)=value-with-%`` (the ``%`` must be literal). During dependency +scanning occurrences of ``A_MACRO(...)`` on ``#include`` lines will be replaced by the value given with the macro argument substituted for -'%'. For example, the entry +``%``. For example, the entry :: diff --git a/Help/prop_dir/INCLUDE_DIRECTORIES.rst b/Help/prop_dir/INCLUDE_DIRECTORIES.rst index 6789a5644..5d856b80a 100644 --- a/Help/prop_dir/INCLUDE_DIRECTORIES.rst +++ b/Help/prop_dir/INCLUDE_DIRECTORIES.rst @@ -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. diff --git a/Help/prop_dir/INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst b/Help/prop_dir/INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst index 325208656..840a1dbc7 100644 --- a/Help/prop_dir/INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst +++ b/Help/prop_dir/INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst @@ -3,6 +3,6 @@ INTERPROCEDURAL_OPTIMIZATION_<CONFIG> Per-configuration interprocedural optimization for a directory. -This is a per-configuration version of INTERPROCEDURAL_OPTIMIZATION. +This is a per-configuration version of ``INTERPROCEDURAL_OPTIMIZATION``. If set, this property overrides the generic property for the named configuration. diff --git a/Help/prop_dir/LABELS.rst b/Help/prop_dir/LABELS.rst new file mode 100644 index 000000000..de27d906e --- /dev/null +++ b/Help/prop_dir/LABELS.rst @@ -0,0 +1,13 @@ +LABELS +------ + +Specify a list of text labels associated with a directory and all of its +subdirectories. This is equivalent to setting the :prop_tgt:`LABELS` target +property and the :prop_test:`LABELS` test property on all targets and tests in +the current directory and subdirectories. Note: Launchers must enabled to +propagate labels to targets. + +The :variable:`CMAKE_DIRECTORY_LABELS` variable can be used to initialize this +property. + +The list is reported in dashboard submissions. diff --git a/Help/prop_dir/LINK_DIRECTORIES.rst b/Help/prop_dir/LINK_DIRECTORIES.rst index fa375766d..44dc2304e 100644 --- a/Help/prop_dir/LINK_DIRECTORIES.rst +++ b/Help/prop_dir/LINK_DIRECTORIES.rst @@ -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:`semicolon-separated 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. diff --git a/Help/prop_dir/LINK_OPTIONS.rst b/Help/prop_dir/LINK_OPTIONS.rst new file mode 100644 index 000000000..54ac6ddaa --- /dev/null +++ b/Help/prop_dir/LINK_OPTIONS.rst @@ -0,0 +1,17 @@ +LINK_OPTIONS +------------ + +List of options to use for the link step of shared library, module +and executable targets. + +This property holds a :ref:`semicolon-separated list <CMake Language Lists>` of options +given so far to the :command:`add_link_options` command. + +This property is used to initialize the :prop_tgt:`LINK_OPTIONS` target +property when a target is created, which is used by the generators to set +the options for the compiler. + +Contents of ``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. diff --git a/Help/prop_dir/MACROS.rst b/Help/prop_dir/MACROS.rst index e4feadaa5..245cc1b91 100644 --- a/Help/prop_dir/MACROS.rst +++ b/Help/prop_dir/MACROS.rst @@ -4,5 +4,5 @@ MACROS List of macro commands available in the current directory. This read-only property specifies the list of CMake macros currently -defined. It is intended for debugging purposes. See the macro +defined. It is intended for debugging purposes. See the :command:`macro` command. diff --git a/Help/prop_dir/SUBDIRECTORIES.rst b/Help/prop_dir/SUBDIRECTORIES.rst index 2c2ea773e..6a0ac80d8 100644 --- a/Help/prop_dir/SUBDIRECTORIES.rst +++ b/Help/prop_dir/SUBDIRECTORIES.rst @@ -2,7 +2,7 @@ SUBDIRECTORIES -------------- This read-only directory property contains a -:ref:`;-list <CMake Language Lists>` of subdirectories processed so far by +:ref:`semicolon-separated list <CMake Language Lists>` of subdirectories processed so far by the :command:`add_subdirectory` or :command:`subdirs` commands. Each entry is the absolute path to the source directory (containing the ``CMakeLists.txt`` file). This is suitable to pass to the :command:`get_property` command diff --git a/Help/prop_dir/TESTS.rst b/Help/prop_dir/TESTS.rst new file mode 100644 index 000000000..1c9f6e5c6 --- /dev/null +++ b/Help/prop_dir/TESTS.rst @@ -0,0 +1,8 @@ +TESTS +----- + +List of tests. + +This read-only property holds a +:ref:`semicolon-separated list <CMake Language Lists>` of tests +defined so far, in the current directory, by the :command:`add_test` command. diff --git a/Help/prop_dir/TEST_INCLUDE_FILE.rst b/Help/prop_dir/TEST_INCLUDE_FILE.rst index e47795191..31b23829d 100644 --- a/Help/prop_dir/TEST_INCLUDE_FILE.rst +++ b/Help/prop_dir/TEST_INCLUDE_FILE.rst @@ -1,7 +1,9 @@ TEST_INCLUDE_FILE ----------------- +Deprecated. Use :prop_dir:`TEST_INCLUDE_FILES` instead. + A cmake file that will be included when ctest is run. -If you specify TEST_INCLUDE_FILE, that file will be included and +If you specify ``TEST_INCLUDE_FILE``, that file will be included and processed when ctest is run on the directory. diff --git a/Help/prop_dir/TEST_INCLUDE_FILES.rst b/Help/prop_dir/TEST_INCLUDE_FILES.rst new file mode 100644 index 000000000..c3e4602b0 --- /dev/null +++ b/Help/prop_dir/TEST_INCLUDE_FILES.rst @@ -0,0 +1,7 @@ +TEST_INCLUDE_FILES +------------------ + +A list of cmake files that will be included when ctest is run. + +If you specify ``TEST_INCLUDE_FILES``, those files will be included and +processed when ctest is run on the directory. diff --git a/Help/prop_dir/VS_GLOBAL_SECTION_POST_section.rst b/Help/prop_dir/VS_GLOBAL_SECTION_POST_section.rst index a316abec9..b65db99f3 100644 --- a/Help/prop_dir/VS_GLOBAL_SECTION_POST_section.rst +++ b/Help/prop_dir/VS_GLOBAL_SECTION_POST_section.rst @@ -12,20 +12,20 @@ in the solution file: <contents based on property value> EndGlobalSection -The property must be set to a semicolon-separated list of key=value +The property must be set to a semicolon-separated list of ``key=value`` pairs. Each such pair will be transformed into an entry in the solution global section. Whitespace around key and value is ignored. List elements which do not contain an equal sign are skipped. -This property only works for Visual Studio 8 and above; it is ignored +This property only works for Visual Studio 9 and above; it is ignored on other generators. The property only applies when set on a -directory whose CMakeLists.txt contains a project() command. +directory whose ``CMakeLists.txt`` contains a :command:`project` command. -Note that CMake generates postSolution sections ExtensibilityGlobals -and ExtensibilityAddIns by default. If you set the corresponding +Note that CMake generates postSolution sections ``ExtensibilityGlobals`` +and ``ExtensibilityAddIns`` by default. If you set the corresponding property, it will override the default section. For example, setting -VS_GLOBAL_SECTION_POST_ExtensibilityGlobals will override the default -contents of the ExtensibilityGlobals section, while keeping +``VS_GLOBAL_SECTION_POST_ExtensibilityGlobals`` will override the default +contents of the ``ExtensibilityGlobals`` section, while keeping ExtensibilityAddIns on its default. However, CMake will always add a ``SolutionGuid`` to the ``ExtensibilityGlobals`` section if it is not specified explicitly. diff --git a/Help/prop_dir/VS_GLOBAL_SECTION_PRE_section.rst b/Help/prop_dir/VS_GLOBAL_SECTION_PRE_section.rst index 200e8e62f..7f8bf6161 100644 --- a/Help/prop_dir/VS_GLOBAL_SECTION_PRE_section.rst +++ b/Help/prop_dir/VS_GLOBAL_SECTION_PRE_section.rst @@ -12,11 +12,11 @@ in the solution file: <contents based on property value> EndGlobalSection -The property must be set to a semicolon-separated list of key=value +The property must be set to a semicolon-separated list of ``key=value`` pairs. Each such pair will be transformed into an entry in the solution global section. Whitespace around key and value is ignored. List elements which do not contain an equal sign are skipped. -This property only works for Visual Studio 8 and above; it is ignored +This property only works for Visual Studio 9 and above; it is ignored on other generators. The property only applies when set on a -directory whose CMakeLists.txt contains a project() command. +directory whose ``CMakeLists.txt`` contains a :command:`project` command. diff --git a/Help/prop_dir/VS_STARTUP_PROJECT.rst b/Help/prop_dir/VS_STARTUP_PROJECT.rst index 04441b621..2680dfa6c 100644 --- a/Help/prop_dir/VS_STARTUP_PROJECT.rst +++ b/Help/prop_dir/VS_STARTUP_PROJECT.rst @@ -7,7 +7,7 @@ The :ref:`Visual Studio Generators` create a ``.sln`` file for each directory whose ``CMakeLists.txt`` file calls the :command:`project` command. Set this property in the same directory as a :command:`project` command call (e.g. in the top-level ``CMakeLists.txt`` file) to specify the default startup project -for the correpsonding solution file. +for the corresponding solution file. The property must be set to the name of an existing target. This will cause that project to be listed first in the generated solution diff --git a/Help/prop_gbl/ALLOW_DUPLICATE_CUSTOM_TARGETS.rst b/Help/prop_gbl/ALLOW_DUPLICATE_CUSTOM_TARGETS.rst index 8fab50345..19775ff2d 100644 --- a/Help/prop_gbl/ALLOW_DUPLICATE_CUSTOM_TARGETS.rst +++ b/Help/prop_gbl/ALLOW_DUPLICATE_CUSTOM_TARGETS.rst @@ -4,16 +4,18 @@ ALLOW_DUPLICATE_CUSTOM_TARGETS Allow duplicate custom targets to be created. Normally CMake requires that all targets built in a project have -globally unique logical names (see policy CMP0002). This is necessary -to generate meaningful project file names in Xcode and VS IDE +globally unique logical names (see policy :policy:`CMP0002`). +This is necessary to generate meaningful project file names in +:generator:`Xcode` and :ref:`Visual Studio Generators` IDE generators. It also allows the target names to be referenced unambiguously. -Makefile generators are capable of supporting duplicate custom target -names. For projects that care only about Makefile generators and do -not wish to support Xcode or VS IDE generators, one may set this -property to true to allow duplicate custom targets. The property -allows multiple add_custom_target command calls in different +Makefile generators are capable of supporting duplicate :command:`add_custom_target` +names. For projects that care only about :ref:`Makefile Generators` and do +not wish to support :generator:`Xcode` or :ref:`Visual Studio Generators` IDE +generators, one may set this property to ``True`` +to allow duplicate custom targets. The property +allows multiple :command:`add_custom_target` command calls in different directories to specify the same target name. However, setting this property will cause non-Makefile generators to produce an error and refuse to generate the project. diff --git a/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst index 2ad81574f..b921c6b03 100644 --- a/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst +++ b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst @@ -15,16 +15,19 @@ compile features and a list of supported compilers. The features known to this version of CMake are: ``cxx_std_98`` - Compiler mode is aware of C++ 98. + Compiler mode is at least C++ 98. ``cxx_std_11`` - Compiler mode is aware of C++ 11. + Compiler mode is at least C++ 11. ``cxx_std_14`` - Compiler mode is aware of C++ 14. + Compiler mode is at least C++ 14. ``cxx_std_17`` - Compiler mode is aware of C++ 17. + Compiler mode is at least C++ 17. + +``cxx_std_20`` + Compiler mode is at least C++ 20. ``cxx_aggregate_default_initializers`` Aggregate default initializers, as defined in N3605_. diff --git a/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst index 3707fef1e..e5f896ee0 100644 --- a/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst +++ b/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst @@ -14,13 +14,13 @@ compile features and a list of supported compilers. The features known to this version of CMake are: ``c_std_90`` - Compiler mode is aware of C 90. + Compiler mode is at least C 90. ``c_std_99`` - Compiler mode is aware of C 99. + Compiler mode is at least C 99. ``c_std_11`` - Compiler mode is aware of C 11. + Compiler mode is at least C 11. ``c_function_prototypes`` Function prototypes, as defined in ``ISO/IEC 9899:1990``. diff --git a/Help/prop_gbl/CMAKE_ROLE.rst b/Help/prop_gbl/CMAKE_ROLE.rst new file mode 100644 index 000000000..27512fada --- /dev/null +++ b/Help/prop_gbl/CMAKE_ROLE.rst @@ -0,0 +1,20 @@ +CMAKE_ROLE +---------- + +Tells what mode the current running script is in. Could be one of several +values: + +``PROJECT`` + Running in project mode (processing a ``CMakeLists.txt`` file). + +``SCRIPT`` + Running in ``-P`` script mode. + +``FIND_PACKAGE`` + Running in ``--find-package`` mode. + +``CTEST`` + Running in CTest script mode. + +``CPACK`` + Running in CPack. diff --git a/Help/prop_gbl/DEBUG_CONFIGURATIONS.rst b/Help/prop_gbl/DEBUG_CONFIGURATIONS.rst index 690143f82..fec6fdac8 100644 --- a/Help/prop_gbl/DEBUG_CONFIGURATIONS.rst +++ b/Help/prop_gbl/DEBUG_CONFIGURATIONS.rst @@ -4,11 +4,10 @@ DEBUG_CONFIGURATIONS Specify which configurations are for debugging. The value must be a semi-colon separated list of configuration names. -Currently this property is used only by the target_link_libraries -command (see its documentation for details). Additional uses may be -defined in the future. +Currently this property is used only by the :command:`target_link_libraries` +command. Additional uses may be defined in the future. This property must be set at the top level of the project and before -the first target_link_libraries command invocation. If any entry in +the first :command:`target_link_libraries` command invocation. If any entry in the list does not match a valid configuration for the project the behavior is undefined. diff --git a/Help/prop_gbl/DISABLED_FEATURES.rst b/Help/prop_gbl/DISABLED_FEATURES.rst index 111cdf67e..882bbfacd 100644 --- a/Help/prop_gbl/DISABLED_FEATURES.rst +++ b/Help/prop_gbl/DISABLED_FEATURES.rst @@ -5,7 +5,7 @@ List of features which are disabled during the CMake run. List of features which are disabled during the CMake run. By default it contains the names of all packages which were not found. This is -determined using the <NAME>_FOUND variables. Packages which are -searched QUIET are not listed. A project can add its own features to +determined using the ``<NAME>_FOUND`` variables. Packages which are +searched ``QUIET`` are not listed. A project can add its own features to this list. This property is used by the macros in -FeatureSummary.cmake. +``FeatureSummary.cmake``. diff --git a/Help/prop_gbl/ECLIPSE_EXTRA_CPROJECT_CONTENTS.rst b/Help/prop_gbl/ECLIPSE_EXTRA_CPROJECT_CONTENTS.rst new file mode 100644 index 000000000..50c41a923 --- /dev/null +++ b/Help/prop_gbl/ECLIPSE_EXTRA_CPROJECT_CONTENTS.rst @@ -0,0 +1,12 @@ +ECLIPSE_EXTRA_CPROJECT_CONTENTS +------------------------------- + +Additional contents to be inserted into the generated Eclipse cproject file. + +The cproject file defines the CDT specific information. Some third party IDE's +are based on Eclipse with the addition of other information specific to that IDE. +Through this property, it is possible to add this additional contents to +the generated project. +It is expected to contain valid XML. + +Also see the :prop_gbl:`ECLIPSE_EXTRA_NATURES` property. diff --git a/Help/prop_gbl/ECLIPSE_EXTRA_NATURES.rst b/Help/prop_gbl/ECLIPSE_EXTRA_NATURES.rst index 6d1529d3a..a46575ffa 100644 --- a/Help/prop_gbl/ECLIPSE_EXTRA_NATURES.rst +++ b/Help/prop_gbl/ECLIPSE_EXTRA_NATURES.rst @@ -6,3 +6,5 @@ List of natures to add to the generated Eclipse project file. Eclipse projects specify language plugins by using natures. This property should be set to the unique identifier for a nature (which looks like a Java package name). + +Also see the :prop_gbl:`ECLIPSE_EXTRA_CPROJECT_CONTENTS` property. diff --git a/Help/prop_gbl/ENABLED_FEATURES.rst b/Help/prop_gbl/ENABLED_FEATURES.rst index b03da5a45..acbb3d018 100644 --- a/Help/prop_gbl/ENABLED_FEATURES.rst +++ b/Help/prop_gbl/ENABLED_FEATURES.rst @@ -5,7 +5,7 @@ List of features which are enabled during the CMake run. List of features which are enabled during the CMake run. By default it contains the names of all packages which were found. This is -determined using the <NAME>_FOUND variables. Packages which are -searched QUIET are not listed. A project can add its own features to +determined using the ``<NAME>_FOUND`` variables. Packages which are +searched ``QUIET`` are not listed. A project can add its own features to this list. This property is used by the macros in -FeatureSummary.cmake. +``FeatureSummary.cmake``. diff --git a/Help/prop_gbl/JOB_POOLS.rst b/Help/prop_gbl/JOB_POOLS.rst index 2ce74b81c..21da4662d 100644 --- a/Help/prop_gbl/JOB_POOLS.rst +++ b/Help/prop_gbl/JOB_POOLS.rst @@ -18,6 +18,14 @@ Defined pools could be used globally by setting :variable:`CMAKE_JOB_POOL_COMPILE` and :variable:`CMAKE_JOB_POOL_LINK` or per target by setting the target properties :prop_tgt:`JOB_POOL_COMPILE` and :prop_tgt:`JOB_POOL_LINK`. +:command:`Custom commands <add_custom_command>` and +:command:`custom targets <add_custom_target>` can specify pools using the +option ``JOB_POOL``. +Using a pool that is not defined by :prop_gbl:`JOB_POOLS` causes +an error by ninja at build time. + +If not set, this property uses the value of the :variable:`CMAKE_JOB_POOLS` +variable. Build targets provided by CMake that are meant for individual interactive use, such as ``install``, are placed in the ``console`` pool automatically. diff --git a/Help/prop_gbl/RULE_MESSAGES.rst b/Help/prop_gbl/RULE_MESSAGES.rst index 87a5ca613..a9734a730 100644 --- a/Help/prop_gbl/RULE_MESSAGES.rst +++ b/Help/prop_gbl/RULE_MESSAGES.rst @@ -8,6 +8,6 @@ progress message describing what each build rule does. If the property is not set the default is ON. Set the property to OFF to disable granular messages and report only as each target completes. This is intended to allow scripted builds to avoid the build time cost -of detailed reports. If a ``CMAKE_RULE_MESSAGES`` cache entry exists +of detailed reports. If a :variable:`CMAKE_RULE_MESSAGES` cache entry exists its value initializes the value of this property. Non-Makefile generators currently ignore this property. diff --git a/Help/prop_gbl/USE_FOLDERS.rst b/Help/prop_gbl/USE_FOLDERS.rst index a1b4ccb5b..591972327 100644 --- a/Help/prop_gbl/USE_FOLDERS.rst +++ b/Help/prop_gbl/USE_FOLDERS.rst @@ -4,7 +4,7 @@ USE_FOLDERS Use the :prop_tgt:`FOLDER` target property to organize targets into folders. -If not set, CMake treats this property as OFF by default. CMake +If not set, CMake treats this property as ``OFF`` by default. CMake generators that are capable of organizing into a hierarchy of folders use the values of the :prop_tgt:`FOLDER` target property to name those -folders. See also the documentation for the FOLDER target property. +folders. See also the documentation for the :prop_tgt:`FOLDER` target property. diff --git a/Help/prop_gbl/XCODE_EMIT_EFFECTIVE_PLATFORM_NAME.rst b/Help/prop_gbl/XCODE_EMIT_EFFECTIVE_PLATFORM_NAME.rst index 9a6086ed8..950044301 100644 --- a/Help/prop_gbl/XCODE_EMIT_EFFECTIVE_PLATFORM_NAME.rst +++ b/Help/prop_gbl/XCODE_EMIT_EFFECTIVE_PLATFORM_NAME.rst @@ -1,14 +1,15 @@ XCODE_EMIT_EFFECTIVE_PLATFORM_NAME ---------------------------------- -Control emission of ``EFFECTIVE_PLATFORM_NAME`` by the Xcode generator. +Control emission of ``EFFECTIVE_PLATFORM_NAME`` by the :generator:`Xcode` +generator. It is required for building the same target with multiple SDKs. A common use case is the parallel use of ``iphoneos`` and ``iphonesimulator`` SDKs. -Three different states possible that control when the Xcode generator -emits the ``EFFECTIVE_PLATFORM_NAME`` variable: +Three different states possible that control when the :generator:`Xcode` +generator emits the ``EFFECTIVE_PLATFORM_NAME`` variable: - If set to ``ON`` it will always be emitted - If set to ``OFF`` it will never be emitted diff --git a/Help/prop_inst/CPACK_DESKTOP_SHORTCUTS.rst b/Help/prop_inst/CPACK_DESKTOP_SHORTCUTS.rst index 11f2c036c..729ab603c 100644 --- a/Help/prop_inst/CPACK_DESKTOP_SHORTCUTS.rst +++ b/Help/prop_inst/CPACK_DESKTOP_SHORTCUTS.rst @@ -1,7 +1,7 @@ CPACK_DESKTOP_SHORTCUTS ----------------------- -Species a list of shortcut names that should be created on the Desktop +Species a list of shortcut names that should be created on the `Desktop` for this file. -The property is currently only supported by the WIX generator. +The property is currently only supported by the :cpack_gen:`CPack WIX Generator`. diff --git a/Help/prop_inst/CPACK_NEVER_OVERWRITE.rst b/Help/prop_inst/CPACK_NEVER_OVERWRITE.rst index 11f44d0df..4789e253d 100644 --- a/Help/prop_inst/CPACK_NEVER_OVERWRITE.rst +++ b/Help/prop_inst/CPACK_NEVER_OVERWRITE.rst @@ -3,4 +3,4 @@ CPACK_NEVER_OVERWRITE Request that this file not be overwritten on install or reinstall. -The property is currently only supported by the WIX generator. +The property is currently only supported by the :cpack_gen:`CPack WIX Generator`. diff --git a/Help/prop_inst/CPACK_PERMANENT.rst b/Help/prop_inst/CPACK_PERMANENT.rst index 5e191d08e..985de0da9 100644 --- a/Help/prop_inst/CPACK_PERMANENT.rst +++ b/Help/prop_inst/CPACK_PERMANENT.rst @@ -3,4 +3,4 @@ CPACK_PERMANENT Request that this file not be removed on uninstall. -The property is currently only supported by the WIX generator. +The property is currently only supported by the :cpack_gen:`CPack WIX Generator`. diff --git a/Help/prop_inst/CPACK_STARTUP_SHORTCUTS.rst b/Help/prop_inst/CPACK_STARTUP_SHORTCUTS.rst index 8a160223d..d9208b9f9 100644 --- a/Help/prop_inst/CPACK_STARTUP_SHORTCUTS.rst +++ b/Help/prop_inst/CPACK_STARTUP_SHORTCUTS.rst @@ -1,7 +1,7 @@ CPACK_STARTUP_SHORTCUTS ----------------------- -Species a list of shortcut names that should be created in the Startup folder +Species a list of shortcut names that should be created in the `Startup` folder for this file. -The property is currently only supported by the WIX generator. +The property is currently only supported by the :cpack_gen:`CPack WIX Generator`. diff --git a/Help/prop_inst/CPACK_START_MENU_SHORTCUTS.rst b/Help/prop_inst/CPACK_START_MENU_SHORTCUTS.rst index d30ea39fd..092334a5a 100644 --- a/Help/prop_inst/CPACK_START_MENU_SHORTCUTS.rst +++ b/Help/prop_inst/CPACK_START_MENU_SHORTCUTS.rst @@ -1,7 +1,7 @@ CPACK_START_MENU_SHORTCUTS -------------------------- -Species a list of shortcut names that should be created in the Start Menu +Species a list of shortcut names that should be created in the `Start Menu` for this file. -The property is currently only supported by the WIX generator. +The property is currently only supported by the :cpack_gen:`CPack WIX Generator`. diff --git a/Help/prop_inst/CPACK_WIX_ACL.rst b/Help/prop_inst/CPACK_WIX_ACL.rst index 4e13ec48c..c88f42675 100644 --- a/Help/prop_inst/CPACK_WIX_ACL.rst +++ b/Help/prop_inst/CPACK_WIX_ACL.rst @@ -17,3 +17,5 @@ each of which has to match the following format. ``<permission>`` is any of the YesNoType attributes listed here:: http://wixtoolset.org/documentation/manual/v3/xsd/wix/permission.html + +The property is currently only supported by the :cpack_gen:`CPack WIX Generator`. diff --git a/Help/prop_sf/AUTORCC_OPTIONS.rst b/Help/prop_sf/AUTORCC_OPTIONS.rst index d9dc4d33e..2bec033e4 100644 --- a/Help/prop_sf/AUTORCC_OPTIONS.rst +++ b/Help/prop_sf/AUTORCC_OPTIONS.rst @@ -9,5 +9,14 @@ optional ``OPTIONS`` argument of the :module:`qt4_add_resources() <FindQt4>` mac By default it is empty. -The options set on the ``.qrc`` source file may override :prop_tgt:`AUTORCC_OPTIONS` set -on the target. +The options set on the ``.qrc`` source file may override +:prop_tgt:`AUTORCC_OPTIONS` set on the target. + +EXAMPLE +^^^^^^^ + +.. code-block:: cmake + + # ... + set_property(SOURCE resources.qrc PROPERTY AUTORCC_OPTIONS "--compress;9") + # ... diff --git a/Help/prop_sf/AUTOUIC_OPTIONS.rst b/Help/prop_sf/AUTOUIC_OPTIONS.rst index bb48da90f..e2f47ecd2 100644 --- a/Help/prop_sf/AUTOUIC_OPTIONS.rst +++ b/Help/prop_sf/AUTOUIC_OPTIONS.rst @@ -4,11 +4,20 @@ AUTOUIC_OPTIONS Additional options for ``uic`` when using :prop_tgt:`AUTOUIC` This property holds additional command line options -which will be used when ``uic`` is executed during the build via :prop_tgt:`AUTOUIC`, -i.e. it is equivalent to the optional ``OPTIONS`` argument of the -:module:`qt4_wrap_ui() <FindQt4>` macro. +which will be used when ``uic`` is executed during the build via +:prop_tgt:`AUTOUIC`, i.e. it is equivalent to the optional ``OPTIONS`` +argument of the :module:`qt4_wrap_ui() <FindQt4>` macro. By default it is empty. -The options set on the ``.ui`` source file may override :prop_tgt:`AUTOUIC_OPTIONS` set -on the target. +The options set on the ``.ui`` source file may override +:prop_tgt:`AUTOUIC_OPTIONS` set on the target. + +EXAMPLE +^^^^^^^ + +.. code-block:: cmake + + # ... + set_property(SOURCE widget.ui PROPERTY AUTOUIC_OPTIONS "--no-protection") + # ... diff --git a/Help/prop_sf/COMPILE_DEFINITIONS.rst b/Help/prop_sf/COMPILE_DEFINITIONS.rst index 1626825f1..63176901e 100644 --- a/Help/prop_sf/COMPILE_DEFINITIONS.rst +++ b/Help/prop_sf/COMPILE_DEFINITIONS.rst @@ -3,17 +3,27 @@ COMPILE_DEFINITIONS Preprocessor definitions for compiling a source file. -The COMPILE_DEFINITIONS property may be set to a semicolon-separated -list of preprocessor definitions using the syntax VAR or VAR=value. +The ``COMPILE_DEFINITIONS`` property may be set to a semicolon-separated +list of preprocessor definitions using the syntax ``VAR`` or ``VAR=value``. Function-style definitions are not supported. CMake will automatically escape the value correctly for the native build system (note that CMake language syntax may require escapes to specify some values). This property may be set on a per-configuration basis using -the name COMPILE_DEFINITIONS_<CONFIG> where <CONFIG> is an upper-case -name (ex. "COMPILE_DEFINITIONS_DEBUG"). +the name ``COMPILE_DEFINITIONS_<CONFIG>`` where ``<CONFIG>`` is an upper-case +name (ex. ``COMPILE_DEFINITIONS_DEBUG``). CMake will automatically drop some definitions that are not supported by the native build tool. Xcode does not support per-configuration definitions on source files. .. include:: /include/COMPILE_DEFINITIONS_DISCLAIMER.txt + +Contents of ``COMPILE_DEFINITIONS`` may use :manual:`cmake-generator-expressions(7)` +with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` +manual for available expressions. However, :generator:`Xcode` +does not support per-config per-source settings, so expressions +that depend on the build configuration are not allowed with that +generator. + +Generator expressions should be preferred instead of setting the alternative per-configuration +property. diff --git a/Help/prop_sf/COMPILE_DEFINITIONS_CONFIG.rst b/Help/prop_sf/COMPILE_DEFINITIONS_CONFIG.rst index 848707647..ec867b65d 100644 --- a/Help/prop_sf/COMPILE_DEFINITIONS_CONFIG.rst +++ b/Help/prop_sf/COMPILE_DEFINITIONS_CONFIG.rst @@ -5,6 +5,6 @@ Ignored. See CMake Policy :policy:`CMP0043`. Per-configuration preprocessor definitions on a source file. -This is the configuration-specific version of COMPILE_DEFINITIONS. -Note that Xcode does not support per-configuration source file flags -so this property will be ignored by the Xcode generator. +This is the configuration-specific version of :prop_tgt:`COMPILE_DEFINITIONS`. +Note that :generator:`Xcode` does not support per-configuration source +file flags so this property will be ignored by the :generator:`Xcode` generator. diff --git a/Help/prop_sf/COMPILE_FLAGS.rst b/Help/prop_sf/COMPILE_FLAGS.rst index 10121644e..c211b89ac 100644 --- a/Help/prop_sf/COMPILE_FLAGS.rst +++ b/Help/prop_sf/COMPILE_FLAGS.rst @@ -3,8 +3,8 @@ COMPILE_FLAGS Additional flags to be added when compiling this source file. -These flags will be added to the list of compile flags when this -source file builds. Use :prop_sf:`COMPILE_DEFINITIONS` to pass +The ``COMPILE_FLAGS`` property, managed as a string, sets additional compiler +flags used to build source files. Use :prop_sf:`COMPILE_DEFINITIONS` to pass additional preprocessor definitions. Contents of ``COMPILE_FLAGS`` may use "generator expressions" @@ -13,3 +13,7 @@ manual for available expressions. However, :generator:`Xcode` does not support per-config per-source settings, so expressions that depend on the build configuration are not allowed with that generator. + +.. note:: + + This property has been superseded by the :prop_sf:`COMPILE_OPTIONS` property. diff --git a/Help/prop_sf/COMPILE_OPTIONS.rst b/Help/prop_sf/COMPILE_OPTIONS.rst new file mode 100644 index 000000000..7e48271d0 --- /dev/null +++ b/Help/prop_sf/COMPILE_OPTIONS.rst @@ -0,0 +1,21 @@ +COMPILE_OPTIONS +--------------- + +List of additional options to pass to the compiler. + +This property holds a :ref:`semicolon-separated list <CMake Language Lists>` of options +and will be added to the list of compile flags when this +source file builds. Use :prop_sf:`COMPILE_DEFINITIONS` to pass +additional preprocessor definitions and :prop_sf:`INCLUDE_DIRECTORIES` to pass +additional include directories. + +Contents of ``COMPILE_OPTIONS`` may use "generator expressions" with the +syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual +for available expressions. However, :generator:`Xcode` +does not support per-config per-source settings, so expressions +that depend on the build configuration are not allowed with that +generator. + +.. note:: + + This property should be preferred over the :prop_sf:`COMPILE_FLAGS` property. diff --git a/Help/prop_sf/EXTERNAL_OBJECT.rst b/Help/prop_sf/EXTERNAL_OBJECT.rst index efa0e9bea..351c04d51 100644 --- a/Help/prop_sf/EXTERNAL_OBJECT.rst +++ b/Help/prop_sf/EXTERNAL_OBJECT.rst @@ -3,6 +3,6 @@ EXTERNAL_OBJECT If set to true then this is an object file. -If this property is set to true then the source file is really an +If this property is set to ``True`` then the source file is really an object file and should not be compiled. It will still be linked into the target though. diff --git a/Help/prop_sf/Fortran_FORMAT.rst b/Help/prop_sf/Fortran_FORMAT.rst index 69e34aafd..1cbbf4809 100644 --- a/Help/prop_sf/Fortran_FORMAT.rst +++ b/Help/prop_sf/Fortran_FORMAT.rst @@ -1,9 +1,10 @@ Fortran_FORMAT -------------- -Set to FIXED or FREE to indicate the Fortran source layout. +Set to ``FIXED`` or ``FREE`` to indicate the Fortran source layout. This property tells CMake whether a given Fortran source file uses fixed-format or free-format. CMake will pass the corresponding format -flag to the compiler. Consider using the target-wide Fortran_FORMAT -property if all source files in a target share the same format. +flag to the compiler. Consider using the target-wide +:prop_tgt:`Fortran_FORMAT` property if all source files in a target +share the same format. diff --git a/Help/prop_sf/GENERATED.rst b/Help/prop_sf/GENERATED.rst index a3aa12747..d430ee264 100644 --- a/Help/prop_sf/GENERATED.rst +++ b/Help/prop_sf/GENERATED.rst @@ -1,8 +1,23 @@ GENERATED --------- -Is this source file generated as part of the build process. +Is this source file generated as part of the build or CMake process. -If a source file is generated by the build process CMake will handle -it differently in terms of dependency checking etc. Otherwise having -a non-existent source file could create problems. +Tells the internal CMake engine that a source file is generated by an outside +process such as another build step, or the execution of CMake itself. This +information is then used to exempt the file from any existence or validity +checks. Generated files are created by the execution of commands such as +:command:`add_custom_command` and :command:`file(GENERATE)`. + +When a generated file created by an :command:`add_custom_command` command +is explicitly listed as a source file for any target in the same +directory scope (which usually means the same ``CMakeLists.txt`` file), +CMake will automatically create a dependency to make sure the file is +generated before building that target. + +Generated sources may be hidden in some IDE tools, while in others they might +be shown. For the special case of sources generated by CMake's :prop_tgt:`AUTOMOC` +or :prop_tgt:`AUTORCC` functionality, the :prop_gbl:`AUTOGEN_SOURCE_GROUP`, +:prop_gbl:`AUTOMOC_SOURCE_GROUP` and :prop_gbl:`AUTORCC_SOURCE_GROUP` target +properties may influence where the generated sources are grouped in the project's +file lists. diff --git a/Help/prop_sf/INCLUDE_DIRECTORIES.rst b/Help/prop_sf/INCLUDE_DIRECTORIES.rst new file mode 100644 index 000000000..23de70e16 --- /dev/null +++ b/Help/prop_sf/INCLUDE_DIRECTORIES.rst @@ -0,0 +1,18 @@ +INCLUDE_DIRECTORIES +------------------- + +List of preprocessor include file search directories. + +This property holds a :ref:`semicolon-separated list <CMake Language Lists>` of paths +and will be added to the list of include directories when this +source file builds. These directories will take precedence over directories +defined at target level except for :generator:`Xcode` generator due to technical +limitations. + +Relative paths should not be added to this property directly. + +Contents of ``INCLUDE_DIRECTORIES`` may use "generator expressions" with +the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual +for available expressions. However, :generator:`Xcode` does not support +per-config per-source settings, so expressions that depend on the build +configuration are not allowed with that generator. diff --git a/Help/prop_sf/KEEP_EXTENSION.rst b/Help/prop_sf/KEEP_EXTENSION.rst index d6167e5a9..a32f96834 100644 --- a/Help/prop_sf/KEEP_EXTENSION.rst +++ b/Help/prop_sf/KEEP_EXTENSION.rst @@ -6,4 +6,4 @@ Make the output file have the same extension as the source file. If this property is set then the file extension of the output file will be the same as that of the source file. Normally the output file extension is computed based on the language of the source file, for -example .cxx will go to a .o extension. +example ``.cxx`` will go to a ``.o`` extension. diff --git a/Help/prop_sf/LABELS.rst b/Help/prop_sf/LABELS.rst index e1c10696a..d0d2a0a92 100644 --- a/Help/prop_sf/LABELS.rst +++ b/Help/prop_sf/LABELS.rst @@ -4,5 +4,5 @@ LABELS Specify a list of text labels associated with a source file. This property has meaning only when the source file is listed in a -target whose LABELS property is also set. No other semantics are +target whose ``LABELS`` property is also set. No other semantics are currently specified. diff --git a/Help/prop_sf/LANGUAGE.rst b/Help/prop_sf/LANGUAGE.rst index 97bfa20f4..88d438e7b 100644 --- a/Help/prop_sf/LANGUAGE.rst +++ b/Help/prop_sf/LANGUAGE.rst @@ -5,6 +5,7 @@ What programming language is the file. A property that can be set to indicate what programming language the source file is. If it is not set the language is determined based on -the file extension. Typical values are CXX C etc. Setting this +the file extension. Typical values are ``CXX`` (i.e. C++), ``C``, +``CSharp``, ``CUDA``, ``Fortran``, and ``ASM``. Setting this property for a file means this file will be compiled. Do not set this for headers or files that should not be compiled. diff --git a/Help/prop_sf/MACOSX_PACKAGE_LOCATION.rst b/Help/prop_sf/MACOSX_PACKAGE_LOCATION.rst index a064afa63..d185d9197 100644 --- a/Help/prop_sf/MACOSX_PACKAGE_LOCATION.rst +++ b/Help/prop_sf/MACOSX_PACKAGE_LOCATION.rst @@ -3,19 +3,19 @@ MACOSX_PACKAGE_LOCATION Place a source file inside a Application Bundle (:prop_tgt:`MACOSX_BUNDLE`), Core Foundation Bundle (:prop_tgt:`BUNDLE`), -or Framework Bundle (:prop_tgt:`FRAMEWORK`). It is applicable for OS X +or Framework Bundle (:prop_tgt:`FRAMEWORK`). It is applicable for macOS and iOS. Executable targets with the :prop_tgt:`MACOSX_BUNDLE` property set are -built as OS X or iOS application bundles on Apple platforms. Shared +built as macOS or iOS application bundles on Apple platforms. Shared library targets with the :prop_tgt:`FRAMEWORK` property set are built as -OS X or iOS frameworks on Apple platforms. Module library targets with -the :prop_tgt:`BUNDLE` property set are built as OS X ``CFBundle`` bundles +macOS or iOS frameworks on Apple platforms. Module library targets with +the :prop_tgt:`BUNDLE` property set are built as macOS ``CFBundle`` bundles on Apple platforms. Source files listed in the target with this property set will be copied to a directory inside the bundle or framework content -folder specified by the property value. For OS X Application Bundles the -content folder is ``<name>.app/Contents``. For OS X Frameworks the -content folder is ``<name>.framework/Versions/<version>``. For OS X +folder specified by the property value. For macOS Application Bundles the +content folder is ``<name>.app/Contents``. For macOS Frameworks the +content folder is ``<name>.framework/Versions/<version>``. For macOS CFBundles the content folder is ``<name>.bundle/Contents`` (unless the extension is changed). See the :prop_tgt:`PUBLIC_HEADER`, :prop_tgt:`PRIVATE_HEADER`, and :prop_tgt:`RESOURCE` target properties for diff --git a/Help/prop_sf/OBJECT_DEPENDS.rst b/Help/prop_sf/OBJECT_DEPENDS.rst index 1d24960b5..aaff95659 100644 --- a/Help/prop_sf/OBJECT_DEPENDS.rst +++ b/Help/prop_sf/OBJECT_DEPENDS.rst @@ -3,7 +3,7 @@ OBJECT_DEPENDS Additional files on which a compiled object file depends. -Specifies a :ref:`;-list <CMake Language Lists>` of full-paths to +Specifies a :ref:`semicolon-separated list <CMake Language Lists>` of full-paths to files on which any object files compiled from this source file depend. On :ref:`Makefile Generators` and the :generator:`Ninja` generator an object file will be recompiled if any of the named files is newer than it. diff --git a/Help/prop_sf/OBJECT_OUTPUTS.rst b/Help/prop_sf/OBJECT_OUTPUTS.rst index 6a2855374..e7e880b29 100644 --- a/Help/prop_sf/OBJECT_OUTPUTS.rst +++ b/Help/prop_sf/OBJECT_OUTPUTS.rst @@ -1,9 +1,9 @@ OBJECT_OUTPUTS -------------- -Additional outputs for a Makefile rule. +Additional outputs for a :generator:`Ninja` or :ref:`Makefile Generators` rule. Additional outputs created by compilation of this source file. If any of these outputs is missing the object will be recompiled. This is -supported only on Makefile generators and will be ignored on other -generators. +supported only on the :generator:`Ninja` and :ref:`Makefile Generators` +and will be ignored on other generators. diff --git a/Help/prop_sf/SKIP_AUTOGEN.rst b/Help/prop_sf/SKIP_AUTOGEN.rst index 6bf2409b2..f31185a5b 100644 --- a/Help/prop_sf/SKIP_AUTOGEN.rst +++ b/Help/prop_sf/SKIP_AUTOGEN.rst @@ -4,5 +4,14 @@ SKIP_AUTOGEN Exclude the source file from :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTOUIC` and :prop_tgt:`AUTORCC` processing (for Qt projects). -For finer control see :prop_sf:`SKIP_AUTOMOC`, :prop_sf:`SKIP_AUTOUIC` and -:prop_sf:`SKIP_AUTORCC`. +For finer exclusion control see :prop_sf:`SKIP_AUTOMOC`, +:prop_sf:`SKIP_AUTOUIC` and :prop_sf:`SKIP_AUTORCC`. + +EXAMPLE +^^^^^^^ + +.. code-block:: cmake + + # ... + set_property(SOURCE file.h PROPERTY SKIP_AUTOGEN ON) + # ... diff --git a/Help/prop_sf/SKIP_AUTOMOC.rst b/Help/prop_sf/SKIP_AUTOMOC.rst index 2245ca639..a9294489a 100644 --- a/Help/prop_sf/SKIP_AUTOMOC.rst +++ b/Help/prop_sf/SKIP_AUTOMOC.rst @@ -3,4 +3,13 @@ SKIP_AUTOMOC Exclude the source file from :prop_tgt:`AUTOMOC` processing (for Qt projects). -For broader control see :prop_sf:`SKIP_AUTOGEN` +For broader exclusion control see :prop_sf:`SKIP_AUTOGEN`. + +EXAMPLE +^^^^^^^ + +.. code-block:: cmake + + # ... + set_property(SOURCE file.h PROPERTY SKIP_AUTOMOC ON) + # ... diff --git a/Help/prop_sf/SKIP_AUTORCC.rst b/Help/prop_sf/SKIP_AUTORCC.rst index 394d8f8cf..bccccfc93 100644 --- a/Help/prop_sf/SKIP_AUTORCC.rst +++ b/Help/prop_sf/SKIP_AUTORCC.rst @@ -3,4 +3,13 @@ SKIP_AUTORCC Exclude the source file from :prop_tgt:`AUTORCC` processing (for Qt projects). -For broader control see :prop_sf:`SKIP_AUTOGEN` +For broader exclusion control see :prop_sf:`SKIP_AUTOGEN`. + +EXAMPLE +^^^^^^^ + +.. code-block:: cmake + + # ... + set_property(SOURCE file.qrc PROPERTY SKIP_AUTORCC ON) + # ... diff --git a/Help/prop_sf/SKIP_AUTOUIC.rst b/Help/prop_sf/SKIP_AUTOUIC.rst index 50f78ef66..8c962dbfe 100644 --- a/Help/prop_sf/SKIP_AUTOUIC.rst +++ b/Help/prop_sf/SKIP_AUTOUIC.rst @@ -3,4 +3,18 @@ SKIP_AUTOUIC Exclude the source file from :prop_tgt:`AUTOUIC` processing (for Qt projects). -For broader control see :prop_sf:`SKIP_AUTOGEN` +:prop_sf:`SKIP_AUTOUIC` can be set on C++ header and source files and on +``.ui`` files. + +For broader exclusion control see :prop_sf:`SKIP_AUTOGEN`. + +EXAMPLE +^^^^^^^ + +.. code-block:: cmake + + # ... + set_property(SOURCE file.h PROPERTY SKIP_AUTOUIC ON) + set_property(SOURCE file.cpp PROPERTY SKIP_AUTOUIC ON) + set_property(SOURCE widget.ui PROPERTY SKIP_AUTOUIC ON) + # ... diff --git a/Help/prop_sf/SKIP_PRECOMPILE_HEADERS.rst b/Help/prop_sf/SKIP_PRECOMPILE_HEADERS.rst new file mode 100644 index 000000000..5f39f30aa --- /dev/null +++ b/Help/prop_sf/SKIP_PRECOMPILE_HEADERS.rst @@ -0,0 +1,13 @@ +SKIP_PRECOMPILE_HEADERS +----------------------- + +Is this source file skipped by :prop_tgt:`PRECOMPILE_HEADERS` feature. + +This property helps with build problems that one would run into +when using the :prop_tgt:`PRECOMPILE_HEADERS` feature. + +One example would be the usage of Objective-C (*.m) files, and +Objective-C++ (*.mm) files, which lead to compilation failure +because they are treated (in case of Ninja / Makefile generator) +as C, and CXX respectively. The precompile headers are not +compatible between languages. diff --git a/Help/prop_sf/SKIP_UNITY_BUILD_INCLUSION.rst b/Help/prop_sf/SKIP_UNITY_BUILD_INCLUSION.rst new file mode 100644 index 000000000..6d1e60d4a --- /dev/null +++ b/Help/prop_sf/SKIP_UNITY_BUILD_INCLUSION.rst @@ -0,0 +1,11 @@ +SKIP_UNITY_BUILD_INCLUSION +-------------------------- + +Setting this property to true ensures the source file will be skipped by +unity builds when its associated target has its :prop_tgt:`UNITY_BUILD` +property set to true. The source file will instead be compiled on its own +in the same way as it would with unity builds disabled. + +This property helps with "ODR (One definition rule)" problems where combining +a particular source file with others might lead to build errors or other +unintended side effects. diff --git a/Help/prop_sf/SYMBOLIC.rst b/Help/prop_sf/SYMBOLIC.rst index c7d0b2603..8bebe30bb 100644 --- a/Help/prop_sf/SYMBOLIC.rst +++ b/Help/prop_sf/SYMBOLIC.rst @@ -3,6 +3,6 @@ SYMBOLIC Is this just a name for a rule. -If SYMBOLIC (boolean) is set to true the build system will be informed +If ``SYMBOLIC`` (boolean) is set to ``True`` the build system will be informed that the source file is not actually created on disk but instead used as a symbolic name for a build rule. diff --git a/Help/prop_sf/Swift_DEPENDENCIES_FILE.rst b/Help/prop_sf/Swift_DEPENDENCIES_FILE.rst new file mode 100644 index 000000000..faac2df7b --- /dev/null +++ b/Help/prop_sf/Swift_DEPENDENCIES_FILE.rst @@ -0,0 +1,5 @@ +Swift_DEPENDENCIES_FILE +----------------------- + +This property sets the path for the Swift dependency file (swiftdeps) for the +source. If one is not specified, it will default to ``<OBJECT>.swiftdeps``. diff --git a/Help/prop_sf/Swift_DIAGNOSTICS_FILE.rst b/Help/prop_sf/Swift_DIAGNOSTICS_FILE.rst new file mode 100644 index 000000000..5bf5d59cd --- /dev/null +++ b/Help/prop_sf/Swift_DIAGNOSTICS_FILE.rst @@ -0,0 +1,4 @@ +Swift_DIAGNOSTICS_FILE +---------------------- + +This property controls where the Swift diagnostics are serialized. diff --git a/Help/prop_sf/VS_CSHARP_tagname.rst b/Help/prop_sf/VS_CSHARP_tagname.rst index d42159f6d..91c4a06c1 100644 --- a/Help/prop_sf/VS_CSHARP_tagname.rst +++ b/Help/prop_sf/VS_CSHARP_tagname.rst @@ -3,8 +3,9 @@ VS_CSHARP_<tagname> Visual Studio and CSharp source-file-specific configuration. -Tell the Visual Studio generator to set the source file tag -``<tagname>`` to a given value in the generated Visual Studio CSharp +Tell the :manual:`Visual Studio generators <cmake-generators(7)>` +to set the source file tag ``<tagname>`` +to a given value in the generated Visual Studio CSharp project. Ignored on other generators and languages. This property can be used to define dependencies between source files or set any other Visual Studio specific parameters. diff --git a/Help/prop_sf/VS_DEPLOYMENT_CONTENT.rst b/Help/prop_sf/VS_DEPLOYMENT_CONTENT.rst index 9fb3ba3d0..6a38478fe 100644 --- a/Help/prop_sf/VS_DEPLOYMENT_CONTENT.rst +++ b/Help/prop_sf/VS_DEPLOYMENT_CONTENT.rst @@ -2,7 +2,8 @@ VS_DEPLOYMENT_CONTENT --------------------- Mark a source file as content for deployment with a Windows Phone or -Windows Store application when built with a Visual Studio generator. +Windows Store application when built with a +:manual:`Visual Studio generators <cmake-generators(7)>`. The value must evaluate to either ``1`` or ``0`` and may use :manual:`generator expressions <cmake-generator-expressions(7)>` to make the choice based on the build configuration. diff --git a/Help/prop_sf/VS_DEPLOYMENT_LOCATION.rst b/Help/prop_sf/VS_DEPLOYMENT_LOCATION.rst index 303db952b..2ce22fced 100644 --- a/Help/prop_sf/VS_DEPLOYMENT_LOCATION.rst +++ b/Help/prop_sf/VS_DEPLOYMENT_LOCATION.rst @@ -2,7 +2,8 @@ VS_DEPLOYMENT_LOCATION ---------------------- Specifies the deployment location for a content source file with a Windows -Phone or Windows Store application when built with a Visual Studio generator. +Phone or Windows Store application when built +with a :manual:`Visual Studio generators <cmake-generators(7)>`. This property is only applicable when using :prop_sf:`VS_DEPLOYMENT_CONTENT`. The value represent the path relative to the app package and applies to all configurations. diff --git a/Help/prop_sf/VS_INCLUDE_IN_VSIX.rst b/Help/prop_sf/VS_INCLUDE_IN_VSIX.rst index 30f471d30..db470ef00 100644 --- a/Help/prop_sf/VS_INCLUDE_IN_VSIX.rst +++ b/Help/prop_sf/VS_INCLUDE_IN_VSIX.rst @@ -1,6 +1,6 @@ VS_INCLUDE_IN_VSIX ------------------ -Boolean property to specify if the file should be included within a VSIX -extension package. This is needed for development of Visual Studio -extensions. +Boolean property to specify if the file should be included within a +VSIX (Visual Studio Integration Extension) extension package. +This is needed for development of Visual Studio extensions. diff --git a/Help/prop_sf/VS_SHADER_DISABLE_OPTIMIZATIONS.rst b/Help/prop_sf/VS_SHADER_DISABLE_OPTIMIZATIONS.rst new file mode 100644 index 000000000..446dd26d9 --- /dev/null +++ b/Help/prop_sf/VS_SHADER_DISABLE_OPTIMIZATIONS.rst @@ -0,0 +1,6 @@ +VS_SHADER_DISABLE_OPTIMIZATIONS +------------------------------- + +Disable compiler optimizations for an ``.hlsl`` source file. This adds the +``-Od`` flag to the command line for the FxCompiler tool. Specify the value +``true`` for this property to disable compiler optimizations. diff --git a/Help/prop_sf/VS_SHADER_ENABLE_DEBUG.rst b/Help/prop_sf/VS_SHADER_ENABLE_DEBUG.rst new file mode 100644 index 000000000..c0e60a3e3 --- /dev/null +++ b/Help/prop_sf/VS_SHADER_ENABLE_DEBUG.rst @@ -0,0 +1,6 @@ +VS_SHADER_ENABLE_DEBUG +---------------------- + +Enable debugging information for an ``.hlsl`` source file. This adds the +``-Zi`` flag to the command line for the FxCompiler tool. Specify the value +``true`` to generate debugging information for the compiled shader. diff --git a/Help/prop_sf/VS_SHADER_FLAGS.rst b/Help/prop_sf/VS_SHADER_FLAGS.rst index 09011231b..0a53afd1c 100644 --- a/Help/prop_sf/VS_SHADER_FLAGS.rst +++ b/Help/prop_sf/VS_SHADER_FLAGS.rst @@ -1,4 +1,4 @@ VS_SHADER_FLAGS --------------- -Set additional VS shader flags of a ``.hlsl`` source file. +Set additional Visual Studio shader flags of a ``.hlsl`` source file. diff --git a/Help/prop_sf/VS_SHADER_OBJECT_FILE_NAME.rst b/Help/prop_sf/VS_SHADER_OBJECT_FILE_NAME.rst new file mode 100644 index 000000000..093bcc666 --- /dev/null +++ b/Help/prop_sf/VS_SHADER_OBJECT_FILE_NAME.rst @@ -0,0 +1,6 @@ +VS_SHADER_OBJECT_FILE_NAME +-------------------------- + +Specifies a file name for the compiled shader object file for an ``.hlsl`` +source file. This adds the ``-Fo`` flag to the command line for the FxCompiler +tool. diff --git a/Help/prop_sf/VS_SHADER_OUTPUT_HEADER_FILE.rst b/Help/prop_sf/VS_SHADER_OUTPUT_HEADER_FILE.rst new file mode 100644 index 000000000..e6763d332 --- /dev/null +++ b/Help/prop_sf/VS_SHADER_OUTPUT_HEADER_FILE.rst @@ -0,0 +1,5 @@ +VS_SHADER_OUTPUT_HEADER_FILE +---------------------------- + +Set filename for output header file containing object code of a ``.hlsl`` +source file. diff --git a/Help/prop_sf/VS_SHADER_TYPE.rst b/Help/prop_sf/VS_SHADER_TYPE.rst index 688025608..f1048379a 100644 --- a/Help/prop_sf/VS_SHADER_TYPE.rst +++ b/Help/prop_sf/VS_SHADER_TYPE.rst @@ -1,4 +1,4 @@ VS_SHADER_TYPE -------------- -Set the VS shader type of a ``.hlsl`` source file. +Set the Visual Studio shader type of a ``.hlsl`` source file. diff --git a/Help/prop_sf/VS_SHADER_VARIABLE_NAME.rst b/Help/prop_sf/VS_SHADER_VARIABLE_NAME.rst new file mode 100644 index 000000000..1a5e36921 --- /dev/null +++ b/Help/prop_sf/VS_SHADER_VARIABLE_NAME.rst @@ -0,0 +1,5 @@ +VS_SHADER_VARIABLE_NAME +----------------------- + +Set name of variable in header file containing object code of a ``.hlsl`` +source file. diff --git a/Help/prop_sf/VS_XAML_TYPE.rst b/Help/prop_sf/VS_XAML_TYPE.rst index e92191dcb..1a274ba4e 100644 --- a/Help/prop_sf/VS_XAML_TYPE.rst +++ b/Help/prop_sf/VS_XAML_TYPE.rst @@ -1,6 +1,7 @@ VS_XAML_TYPE ------------ -Mark a XAML source file as a different type than the default ``Page``. -The most common usage would be to set the default App.xaml file as -ApplicationDefinition. +Mark a Extensible Application Markup Language (XAML) source file +as a different type than the default ``Page``. +The most common usage would be to set the default ``App.xaml`` file as +``ApplicationDefinition``. diff --git a/Help/prop_sf/WRAP_EXCLUDE.rst b/Help/prop_sf/WRAP_EXCLUDE.rst index 2c79f72a2..638ff0398 100644 --- a/Help/prop_sf/WRAP_EXCLUDE.rst +++ b/Help/prop_sf/WRAP_EXCLUDE.rst @@ -4,7 +4,8 @@ WRAP_EXCLUDE Exclude this source file from any code wrapping techniques. Some packages can wrap source files into alternate languages to -provide additional functionality. For example, C++ code can be -wrapped into Java or Python etc using SWIG etc. If WRAP_EXCLUDE is -set to true (1 etc) that indicates that this source file should not be -wrapped. +provide additional functionality. + +For example, C++ code can be wrapped into Java or Python, using SWIG. +If ``WRAP_EXCLUDE`` is set to ``True``, that indicates that this +source file should not be wrapped. diff --git a/Help/prop_sf/XCODE_EXPLICIT_FILE_TYPE.rst b/Help/prop_sf/XCODE_EXPLICIT_FILE_TYPE.rst index 1b24701a3..b8cf946ea 100644 --- a/Help/prop_sf/XCODE_EXPLICIT_FILE_TYPE.rst +++ b/Help/prop_sf/XCODE_EXPLICIT_FILE_TYPE.rst @@ -1,7 +1,7 @@ XCODE_EXPLICIT_FILE_TYPE ------------------------ -Set the Xcode ``explicitFileType`` attribute on its reference to a +Set the :generator:`Xcode` ``explicitFileType`` attribute on its reference to a source file. CMake computes a default based on file extension but can be told explicitly with this property. diff --git a/Help/prop_sf/XCODE_FILE_ATTRIBUTES.rst b/Help/prop_sf/XCODE_FILE_ATTRIBUTES.rst index 39e69665a..4c93f444a 100644 --- a/Help/prop_sf/XCODE_FILE_ATTRIBUTES.rst +++ b/Help/prop_sf/XCODE_FILE_ATTRIBUTES.rst @@ -1,9 +1,9 @@ XCODE_FILE_ATTRIBUTES --------------------- -Add values to the Xcode ``ATTRIBUTES`` setting on its reference to a +Add values to the :generator:`Xcode` ``ATTRIBUTES`` setting on its reference to a source file. Among other things, this can be used to set the role on -a mig file:: +a ``.mig`` file:: set_source_files_properties(defs.mig PROPERTIES diff --git a/Help/prop_sf/XCODE_LAST_KNOWN_FILE_TYPE.rst b/Help/prop_sf/XCODE_LAST_KNOWN_FILE_TYPE.rst index 42e37574d..b21891fce 100644 --- a/Help/prop_sf/XCODE_LAST_KNOWN_FILE_TYPE.rst +++ b/Help/prop_sf/XCODE_LAST_KNOWN_FILE_TYPE.rst @@ -1,8 +1,8 @@ XCODE_LAST_KNOWN_FILE_TYPE -------------------------- -Set the Xcode ``lastKnownFileType`` attribute on its reference to a -source file. CMake computes a default based on file extension but +Set the :generator:`Xcode` ``lastKnownFileType`` attribute on its reference to +a source file. CMake computes a default based on file extension but can be told explicitly with this property. See also :prop_sf:`XCODE_EXPLICIT_FILE_TYPE`, which is preferred diff --git a/Help/prop_test/COST.rst b/Help/prop_test/COST.rst index 3236a0295..9300d7b27 100644 --- a/Help/prop_test/COST.rst +++ b/Help/prop_test/COST.rst @@ -1,7 +1,14 @@ COST ---- -Set this to a floating point value. Tests in a test set will be run in descending order of cost. +This property describes the cost of a test. When parallel testing is +enabled, tests in the test set will be run in descending order of cost. +Projects can explicitly define the cost of a test by setting this property +to a floating point value. -This property describes the cost of a test. You can explicitly set -this value; tests with higher COST values will run first. +When the cost of a test is not defined by the project, +:manual:`ctest <ctest(1)>` will initially use a default cost of ``0``. +It computes a weighted average of the cost each time a test is run and +uses that as an improved estimate of the cost for the next run. The more +a test is re-run in the same build directory, the more representative the +cost should become. diff --git a/Help/prop_test/DISABLED.rst b/Help/prop_test/DISABLED.rst index c18ae7ffa..1d469e80b 100644 --- a/Help/prop_test/DISABLED.rst +++ b/Help/prop_test/DISABLED.rst @@ -1,15 +1,15 @@ DISABLED -------- -If set to true, the test will be skipped and its status will be 'Not Run'. A -DISABLED test will not be counted in the total number of tests and its -completion status will be reported to CDash as 'Disabled'. +If set to ``True``, the test will be skipped and its status will be 'Not Run'. A +``DISABLED`` test will not be counted in the total number of tests and its +completion status will be reported to CDash as ``Disabled``. -A DISABLED test does not participate in test fixture dependency resolution. -If a DISABLED test has fixture requirements defined in its +A ``DISABLED`` test does not participate in test fixture dependency resolution. +If a ``DISABLED`` test has fixture requirements defined in its :prop_test:`FIXTURES_REQUIRED` property, it will not cause setup or cleanup tests for those fixtures to be added to the test set. -If a test with the :prop_test:`FIXTURES_SETUP` property set is DISABLED, the -fixture behavior will be as though that setup test was passing and any test +If a test with the :prop_test:`FIXTURES_SETUP` property set is ``DISABLED``, +the fixture behavior will be as though that setup test was passing and any test case requiring that fixture will still run. diff --git a/Help/prop_test/ENVIRONMENT.rst b/Help/prop_test/ENVIRONMENT.rst index df9bc9e14..102c7922f 100644 --- a/Help/prop_test/ENVIRONMENT.rst +++ b/Help/prop_test/ENVIRONMENT.rst @@ -4,6 +4,6 @@ ENVIRONMENT Specify environment variables that should be defined for running a test. If set to a list of environment variables and values of the form -MYVAR=value those environment variables will be defined while running +``MYVAR=value`` those environment variables will be defined while running the test. The environment is restored to its previous state after the test is done. diff --git a/Help/prop_test/FIXTURES_CLEANUP.rst b/Help/prop_test/FIXTURES_CLEANUP.rst index f0a4be0ec..3075b4d48 100644 --- a/Help/prop_test/FIXTURES_CLEANUP.rst +++ b/Help/prop_test/FIXTURES_CLEANUP.rst @@ -2,7 +2,8 @@ FIXTURES_CLEANUP ---------------- Specifies a list of fixtures for which the test is to be treated as a cleanup -test. +test. These fixture names are distinct from test case names and are not +required to have any similarity to the names of tests associated with them. Fixture cleanup tests are ordinary tests with all of the usual test functionality. Setting the ``FIXTURES_CLEANUP`` property for a test has two diff --git a/Help/prop_test/FIXTURES_REQUIRED.rst b/Help/prop_test/FIXTURES_REQUIRED.rst index e37dfb57d..e3f60c426 100644 --- a/Help/prop_test/FIXTURES_REQUIRED.rst +++ b/Help/prop_test/FIXTURES_REQUIRED.rst @@ -2,7 +2,7 @@ FIXTURES_REQUIRED ----------------- Specifies a list of fixtures the test requires. Fixture names are case -sensitive. +sensitive and they are not required to have any similarity to test names. Fixtures are a way to attach setup and cleanup tasks to a set of tests. If a test requires a given fixture, then all tests marked as setup tasks for that @@ -19,7 +19,9 @@ some setup tests fail. When CTest is asked to execute only a subset of tests (e.g. by the use of regular expressions or when run with the ``--rerun-failed`` command line option), it will automatically add any setup or cleanup tests for fixtures -required by any of the tests that are in the execution set. +required by any of the tests that are in the execution set. This behavior can +be overridden with the ``-FS``, ``-FC`` and ``-FA`` command line options to +:manual:`ctest(1)` if desired. Since setup and cleanup tasks are also tests, they can have an ordering specified by the :prop_test:`DEPENDS` test property just like any other tests. diff --git a/Help/prop_test/FIXTURES_SETUP.rst b/Help/prop_test/FIXTURES_SETUP.rst index a22021592..fdb21cc76 100644 --- a/Help/prop_test/FIXTURES_SETUP.rst +++ b/Help/prop_test/FIXTURES_SETUP.rst @@ -2,14 +2,15 @@ FIXTURES_SETUP -------------- Specifies a list of fixtures for which the test is to be treated as a setup -test. +test. These fixture names are distinct from test case names and are not +required to have any similarity to the names of tests associated with them. Fixture setup tests are ordinary tests with all of the usual test functionality. Setting the ``FIXTURES_SETUP`` property for a test has two primary effects: - CTest will ensure the test executes before any other test which lists the - fixture(s) in its :prop_test:`FIXTURES_REQUIRED` property. + fixture name(s) in its :prop_test:`FIXTURES_REQUIRED` property. - If CTest is asked to run only a subset of tests (e.g. using regular expressions or the ``--rerun-failed`` option) and the setup test is not in diff --git a/Help/prop_test/MEASUREMENT.rst b/Help/prop_test/MEASUREMENT.rst index bc4936e97..de459ed4e 100644 --- a/Help/prop_test/MEASUREMENT.rst +++ b/Help/prop_test/MEASUREMENT.rst @@ -1,8 +1,8 @@ MEASUREMENT ----------- -Specify a CDASH measurement and value to be reported for a test. +Specify a ``CDASH`` measurement and value to be reported for a test. -If set to a name then that name will be reported to CDASH as a named -measurement with a value of 1. You may also specify a value by -setting MEASUREMENT to "measurement=value". +If set to a name then that name will be reported to ``CDASH`` as a named +measurement with a value of ``1``. You may also specify a value by +setting ``MEASUREMENT`` to ``measurement=value``. diff --git a/Help/prop_test/PROCESSORS.rst b/Help/prop_test/PROCESSORS.rst index 763b6d003..a927c1078 100644 --- a/Help/prop_test/PROCESSORS.rst +++ b/Help/prop_test/PROCESSORS.rst @@ -1,8 +1,16 @@ PROCESSORS ---------- -How many process slots this test requires +Set to specify how many process slots this test requires. +If not set, the default is ``1`` processor. Denotes the number of processors that this test will require. This is typically used for MPI tests, and should be used in conjunction with -the ctest_test PARALLEL_LEVEL option. +the :command:`ctest_test` ``PARALLEL_LEVEL`` option. + +This will also be used to display a weighted test timing result in label and +subproject summaries in the command line output of :manual:`ctest(1)`. The wall +clock time for the test run will be multiplied by this property to give a +better idea of how much cpu resource CTest allocated for the test. + +See also the :prop_test:`PROCESSOR_AFFINITY` test property. diff --git a/Help/prop_test/PROCESSOR_AFFINITY.rst b/Help/prop_test/PROCESSOR_AFFINITY.rst new file mode 100644 index 000000000..38ec17947 --- /dev/null +++ b/Help/prop_test/PROCESSOR_AFFINITY.rst @@ -0,0 +1,11 @@ +PROCESSOR_AFFINITY +------------------ + +Set to a true value to ask CTest to launch the test process with CPU affinity +for a fixed set of processors. If enabled and supported for the current +platform, CTest will choose a set of processors to place in the CPU affinity +mask when launching the test process. The number of processors in the set is +determined by the :prop_test:`PROCESSORS` test property or the number of +processors available to CTest, whichever is smaller. The set of processors +chosen will be disjoint from the processors assigned to other concurrently +running tests that also have the ``PROCESSOR_AFFINITY`` property enabled. diff --git a/Help/prop_test/RESOURCE_GROUPS.rst b/Help/prop_test/RESOURCE_GROUPS.rst new file mode 100644 index 000000000..63c56ce55 --- /dev/null +++ b/Help/prop_test/RESOURCE_GROUPS.rst @@ -0,0 +1,70 @@ +RESOURCE_GROUPS +--------------- + +Specify resources required by a test, grouped in a way that is meaningful to +the test. See :ref:`resource allocation <ctest-resource-allocation>` +for more information on how this property integrates into the CTest resource +allocation feature. + +The ``RESOURCE_GROUPS`` property is a :ref:`semicolon-separated list <CMake +Language Lists>` of group descriptions. Each entry consists of an optional +number of groups using the description followed by a series of resource +requirements for those groups. These requirements (and the number of groups) +are separated by commas. The resource requirements consist of the name of a +resource type, followed by a colon, followed by an unsigned integer +specifying the number of slots required on one resource of the given type. + +The ``RESOURCE_GROUPS`` property tells CTest what resources a test expects +to use grouped in a way meaningful to the test. The test itself must read +the :ref:`environment variables <ctest-resource-environment-variables>` to +determine which resources have been allocated to each group. For example, +each group may correspond to a process the test will spawn when executed. + +Consider the following example: + +.. code-block:: cmake + + add_test(NAME MyTest COMMAND MyExe) + set_property(TEST MyTest PROPERTY RESOURCE_GROUPS + "2,gpus:2" + "gpus:4,crypto_chips:2") + +In this example, there are two group descriptions (implicitly separated by a +semicolon.) The content of the first description is ``2,gpus:2``. This +description specifies 2 groups, each of which requires 2 slots from a single +GPU. The content of the second description is ``gpus:4,crypto_chips:2``. This +description does not specify a group count, so a default of 1 is assumed. +This single group requires 4 slots from a single GPU and 2 slots from a +single cryptography chip. In total, 3 resource groups are specified for this +test, each with its own unique requirements. + +Note that the number of slots following the resource type specifies slots from +a *single* instance of the resource. If the resource group can tolerate +receiving slots from different instances of the same resource, it can indicate +this by splitting the specification into multiple requirements of one slot. For +example: + +.. code-block:: cmake + + add_test(NAME MyTest COMMAND MyExe) + set_property(TEST MyTest PROPERTY RESOURCE_GROUPS + "gpus:1,gpus:1,gpus:1,gpus:1") + +In this case, the single resource group indicates that it needs four GPU slots, +all of which may come from separate GPUs (though they don't have to; CTest may +still assign slots from the same GPU.) + +When CTest sets the :ref:`environment variables +<ctest-resource-environment-variables>` for a test, it assigns a group number +based on the group description, starting at 0 on the left and the number of +groups minus 1 on the right. For example, in the example above, the two +groups in the first description would have IDs of 0 and 1, and the single +group in the second description would have an ID of 2. + +Both the ``RESOURCE_GROUPS`` and :prop_test:`RESOURCE_LOCK` properties serve +similar purposes, but they are distinct and orthogonal. Resources specified by +``RESOURCE_GROUPS`` do not affect :prop_test:`RESOURCE_LOCK`, and vice versa. +Whereas :prop_test:`RESOURCE_LOCK` is a simpler property that is used for +locking one global resource, ``RESOURCE_GROUPS`` is a more advanced property +that allows multiple tests to simultaneously use multiple resources of the +same type, specifying their requirements in a fine-grained manner. diff --git a/Help/prop_test/RESOURCE_LOCK.rst b/Help/prop_test/RESOURCE_LOCK.rst index 755e0aaa3..8b13a01d4 100644 --- a/Help/prop_test/RESOURCE_LOCK.rst +++ b/Help/prop_test/RESOURCE_LOCK.rst @@ -8,3 +8,11 @@ not to run concurrently. See also :prop_test:`FIXTURES_REQUIRED` if the resource requires any setup or cleanup steps. + +Both the :prop_test:`RESOURCE_GROUPS` and ``RESOURCE_LOCK`` properties serve +similar purposes, but they are distinct and orthogonal. Resources specified by +:prop_test:`RESOURCE_GROUPS` do not affect ``RESOURCE_LOCK``, and vice versa. +Whereas ``RESOURCE_LOCK`` is a simpler property that is used for locking one +global resource, :prop_test:`RESOURCE_GROUPS` is a more advanced property +that allows multiple tests to simultaneously use multiple resources of the +same type, specifying their requirements in a fine-grained manner. diff --git a/Help/prop_test/RUN_SERIAL.rst b/Help/prop_test/RUN_SERIAL.rst index 8f65ae18a..ab4c54233 100644 --- a/Help/prop_test/RUN_SERIAL.rst +++ b/Help/prop_test/RUN_SERIAL.rst @@ -3,6 +3,6 @@ RUN_SERIAL Do not run this test in parallel with any other test. -Use this option in conjunction with the ctest_test PARALLEL_LEVEL +Use this option in conjunction with the ctest_test ``PARALLEL_LEVEL`` option to specify that this test should not be run in parallel with any other tests. diff --git a/Help/prop_test/SKIP_REGULAR_EXPRESSION.rst b/Help/prop_test/SKIP_REGULAR_EXPRESSION.rst new file mode 100644 index 000000000..2c6d98049 --- /dev/null +++ b/Help/prop_test/SKIP_REGULAR_EXPRESSION.rst @@ -0,0 +1,17 @@ +SKIP_REGULAR_EXPRESSION +----------------------- + +If the output matches this regular expression the test will be marked as skipped. + +If set, if the output matches one of specified regular expressions, +the test will be marked as skipped. Example: + +.. code-block:: cmake + + set_property(TEST mytest PROPERTY + SKIP_REGULAR_EXPRESSION "[^a-z]Skip" "SKIP" "Skipped" + ) + +``SKIP_REGULAR_EXPRESSION`` expects a list of regular expressions. + +See also the :prop_test:`SKIP_RETURN_CODE` property. diff --git a/Help/prop_test/SKIP_RETURN_CODE.rst b/Help/prop_test/SKIP_RETURN_CODE.rst index c61273c56..23c4c625f 100644 --- a/Help/prop_test/SKIP_RETURN_CODE.rst +++ b/Help/prop_test/SKIP_RETURN_CODE.rst @@ -6,4 +6,7 @@ Return code to mark a test as skipped. Sometimes only a test itself can determine if all requirements for the test are met. If such a situation should not be considered a hard failure a return code of the process can be specified that will mark the test as -"Not Run" if it is encountered. +``Not Run`` if it is encountered. Valid values are in the range of +0 to 255, inclusive. + +See also the :prop_test:`SKIP_REGULAR_EXPRESSION` property. diff --git a/Help/prop_test/WORKING_DIRECTORY.rst b/Help/prop_test/WORKING_DIRECTORY.rst index 5222a197b..92a040967 100644 --- a/Help/prop_test/WORKING_DIRECTORY.rst +++ b/Help/prop_test/WORKING_DIRECTORY.rst @@ -3,5 +3,7 @@ WORKING_DIRECTORY The directory from which the test executable will be called. -If this is not set it is called from the directory the test executable -is located in. +If this is not set, the test will be run with the working directory set to the +binary directory associated with where the test was created (i.e. the +:variable:`CMAKE_CURRENT_BINARY_DIR` for where :command:`add_test` was +called). diff --git a/Help/prop_tgt/ADDITIONAL_CLEAN_FILES.rst b/Help/prop_tgt/ADDITIONAL_CLEAN_FILES.rst new file mode 100644 index 000000000..3b9d965f8 --- /dev/null +++ b/Help/prop_tgt/ADDITIONAL_CLEAN_FILES.rst @@ -0,0 +1,23 @@ +ADDITIONAL_CLEAN_FILES +---------------------- + +A :ref:`;-list <CMake Language Lists>` of files or directories that will be +removed as a part of the global ``clean`` target. It can be used to specify +files and directories that are generated as part of building the target or +that are directly associated with the target in some way (e.g. created as a +result of running the target). + +For custom targets, if such files can be captured as outputs or byproducts +instead, then that should be preferred over adding them to this property. +If an additional clean file is used by multiple targets or isn't +target-specific, then the :prop_dir:`ADDITIONAL_CLEAN_FILES` directory +property may be the more appropriate property to use. + +Relative paths are allowed and are interpreted relative to the +current binary directory. + +Contents of ``ADDITIONAL_CLEAN_FILES`` may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. + +This property only works for the :generator:`Ninja` and the Makefile +generators. It is ignored by other generators. diff --git a/Help/prop_tgt/ANDROID_NATIVE_LIB_DIRECTORIES.rst b/Help/prop_tgt/ANDROID_NATIVE_LIB_DIRECTORIES.rst index bc673804d..d0cd29de8 100644 --- a/Help/prop_tgt/ANDROID_NATIVE_LIB_DIRECTORIES.rst +++ b/Help/prop_tgt/ANDROID_NATIVE_LIB_DIRECTORIES.rst @@ -1,8 +1,8 @@ ANDROID_NATIVE_LIB_DIRECTORIES ------------------------------ -Set the Android property that specifies directories to search for the -.so libraries. +Set the Android property that specifies directories to search for the ``.so`` +libraries. This a string property that contains the directory paths separated by semicolons. diff --git a/Help/prop_tgt/AUTOGEN_BUILD_DIR.rst b/Help/prop_tgt/AUTOGEN_BUILD_DIR.rst index 8db6ede91..909b14c34 100644 --- a/Help/prop_tgt/AUTOGEN_BUILD_DIR.rst +++ b/Help/prop_tgt/AUTOGEN_BUILD_DIR.rst @@ -5,7 +5,7 @@ Directory where :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTOUIC` and :prop_tgt:`AUTORCC` generate files for the target. The directory is created on demand and automatically added to the -:prop_dir:`ADDITIONAL_MAKE_CLEAN_FILES`. +:prop_tgt:`ADDITIONAL_CLEAN_FILES` target property. When unset or empty the directory ``<dir>/<target-name>_autogen`` is used where ``<dir>`` is :variable:`CMAKE_CURRENT_BINARY_DIR` and ``<target-name>`` diff --git a/Help/prop_tgt/AUTOGEN_ORIGIN_DEPENDS.rst b/Help/prop_tgt/AUTOGEN_ORIGIN_DEPENDS.rst new file mode 100644 index 000000000..022bab502 --- /dev/null +++ b/Help/prop_tgt/AUTOGEN_ORIGIN_DEPENDS.rst @@ -0,0 +1,38 @@ +AUTOGEN_ORIGIN_DEPENDS +---------------------- + +Switch for forwarding origin target dependencies to the corresponding +``_autogen`` target. + +Targets which have their :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC` property +``ON`` have a corresponding ``_autogen`` target which generates +``moc`` and ``uic`` files. As this ``_autogen`` target is created at +generate-time, it is not possible to define dependencies of it using +e.g. :command:`add_dependencies`. Instead the +:prop_tgt:`AUTOGEN_ORIGIN_DEPENDS` target property decides whether the origin +target dependencies should be forwarded to the ``_autogen`` target or not. + +By default :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS` is initialized from +:variable:`CMAKE_AUTOGEN_ORIGIN_DEPENDS` which is ``ON`` by default. + +In total the dependencies of the ``_autogen`` target are composed from + +- forwarded origin target dependencies + (enabled by default via :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS`) +- additional user defined dependencies from :prop_tgt:`AUTOGEN_TARGET_DEPENDS` + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. + +Note +^^^^ + +Disabling :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS` is useful to avoid building of +origin target dependencies when building the ``_autogen`` target only. +This is especially interesting when a +:variable:`global autogen target <CMAKE_GLOBAL_AUTOGEN_TARGET>` is enabled. + +When the ``_autogen`` target doesn't require all the origin target's +dependencies, and :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS` is disabled, it might be +necessary to extend :prop_tgt:`AUTOGEN_TARGET_DEPENDS` to add missing +dependencies. diff --git a/Help/prop_tgt/AUTOGEN_PARALLEL.rst b/Help/prop_tgt/AUTOGEN_PARALLEL.rst new file mode 100644 index 000000000..07fbc5a5e --- /dev/null +++ b/Help/prop_tgt/AUTOGEN_PARALLEL.rst @@ -0,0 +1,21 @@ +AUTOGEN_PARALLEL +---------------- + +Number of parallel ``moc`` or ``uic`` processes to start when using +:prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`. + +The custom `<origin>_autogen` target starts a number of threads of which +each one parses a source file and on demand starts a ``moc`` or ``uic`` +process. :prop_tgt:`AUTOGEN_PARALLEL` controls how many parallel threads +(and therefore ``moc`` or ``uic`` processes) are started. + +- An empty (or unset) value or the string ``AUTO`` sets the number of + threads/processes to the number of physical CPUs on the host system. +- A positive non zero integer value sets the exact thread/process count. +- Otherwise a single thread/process is started. + +By default :prop_tgt:`AUTOGEN_PARALLEL` is initialized from +:variable:`CMAKE_AUTOGEN_PARALLEL`. + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. diff --git a/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst b/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst index f522c6bf2..d5c5e147d 100644 --- a/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst +++ b/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst @@ -1,17 +1,36 @@ AUTOGEN_TARGET_DEPENDS ---------------------- -Target dependencies of the corresponding ``_autogen`` target. +Additional target dependencies of the corresponding ``_autogen`` target. -Targets which have their :prop_tgt:`AUTOMOC` target ``ON`` have a -corresponding ``_autogen`` target which is used to autogenerate generate moc -files. As this ``_autogen`` target is created at generate-time, it is not -possible to define dependencies of it, such as to create inputs for the ``moc`` -executable. +Targets which have their :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC` property +``ON`` have a corresponding ``_autogen`` target which generates +``moc`` and ``uic`` files. As this ``_autogen`` target is created at +generate-time, it is not possible to define dependencies of it using +e.g. :command:`add_dependencies`. Instead the +:prop_tgt:`AUTOGEN_TARGET_DEPENDS` target property can be set to a +:ref:`;-list <CMake Language Lists>` of additional dependencies for the +``_autogen`` target. Dependencies can be target names or file names. -The ``AUTOGEN_TARGET_DEPENDS`` target property can be set instead to a list of -dependencies for the ``_autogen`` target. The buildsystem will be generated to -depend on its contents. +In total the dependencies of the ``_autogen`` target are composed from + +- forwarded origin target dependencies + (enabled by default via :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS`) +- additional user defined dependencies from :prop_tgt:`AUTOGEN_TARGET_DEPENDS` See the :manual:`cmake-qt(7)` manual for more information on using CMake with Qt. + +Use cases +^^^^^^^^^ + +If :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC` depends on a file that is either + +- a :prop_sf:`GENERATED` non C++ file (e.g. a :prop_sf:`GENERATED` ``.json`` + or ``.ui`` file) or +- a :prop_sf:`GENERATED` C++ file that isn't recognized by :prop_tgt:`AUTOMOC` + and :prop_tgt:`AUTOUIC` because it's skipped by :prop_sf:`SKIP_AUTOMOC`, + :prop_sf:`SKIP_AUTOUIC`, :prop_sf:`SKIP_AUTOGEN` or :policy:`CMP0071` or +- a file that isn't in the origin target's sources + +it must added to :prop_tgt:`AUTOGEN_TARGET_DEPENDS`. diff --git a/Help/prop_tgt/AUTOMOC.rst b/Help/prop_tgt/AUTOMOC.rst index 0171d20e7..f6dfabdd3 100644 --- a/Help/prop_tgt/AUTOMOC.rst +++ b/Help/prop_tgt/AUTOMOC.rst @@ -1,76 +1,247 @@ AUTOMOC ------- -Should the target be processed with automoc (for Qt projects). +Should the target be processed with auto-moc (for Qt projects). -AUTOMOC is a boolean specifying whether CMake will handle the Qt ``moc`` -preprocessor automatically, i.e. without having to use the -:module:`QT4_WRAP_CPP() <FindQt4>` or QT5_WRAP_CPP() macro. Currently Qt4 and Qt5 are -supported. +:prop_tgt:`AUTOMOC` is a boolean specifying whether CMake will handle the Qt +``moc`` preprocessor automatically, i.e. without having to use the +:module:`QT4_WRAP_CPP() <FindQt4>` or ``QT5_WRAP_CPP()`` macro. +Currently Qt4 and Qt5 are supported. + +This property is initialized by the value of the :variable:`CMAKE_AUTOMOC` +variable if it is set when a target is created. When this property is set ``ON``, CMake will scan the header and -source files at build time and invoke moc accordingly. +source files at build time and invoke ``moc`` accordingly. -* If an ``#include`` statement like ``#include "moc_<basename>.cpp"`` is found, - the ``Q_OBJECT`` or ``Q_GADGET`` macros are expected in an otherwise empty - line of the ``<basename>.h(xx)`` header file. ``moc`` is run on the header - file to generate ``moc_<basename>.cpp`` in the - ``<AUTOGEN_BUILD_DIR>/include`` directory which is automatically added - to the target's :prop_tgt:`INCLUDE_DIRECTORIES`. - This allows the compiler to find the included ``moc_<basename>.cpp`` file - regardless of the location the original source. - * See :prop_tgt:`AUTOGEN_BUILD_DIR`. +Header file processing +^^^^^^^^^^^^^^^^^^^^^^ -* If an ``#include`` statement like ``#include "<basename>.moc"`` is found, - then ``Q_OBJECT`` or ``Q_GADGET`` macros are expected in the current source - file and ``moc`` is run on the source file itself. +At configuration time, a list of header files that should be scanned by +:prop_tgt:`AUTOMOC` is computed from the target's sources. -* Header files that are not included by an ``#include "moc_<basename>.cpp"`` - statement are nonetheless scanned for ``Q_OBJECT`` or ``Q_GADGET`` macros. - The resulting ``moc_<basename>.cpp`` files are generated in custom - directories and automatically included in a generated - ``<AUTOGEN_BUILD_DIR>/mocs_compilation.cpp`` file, - which is compiled as part of the target. +- All header files in the target's sources are added to the scan list. +- For all C++ source files ``<source_base>.<source_extension>`` in the + target's sources, CMake searches for - * The custom directories with checksum - based names help to avoid name collisions for moc files with the same - ``<basename>``. + - a regular header with the same base name + (``<source_base>.<header_extention>``) and + - a private header with the same base name and a ``_p`` suffix + (``<source_base>_p.<header_extention>``) - * See :prop_tgt:`AUTOGEN_BUILD_DIR`. + and adds these to the scan list. -* Additionally, header files with the same base name as a source file, - (like ``<basename>.h``) or ``_p`` appended to the base name (like - ``<basename>_p.h``), are parsed for ``Q_OBJECT`` or ``Q_GADGET`` macros, - and if found, ``moc`` is also executed on those files. +At build time, CMake scans each unknown or modified header file from the +list and searches for -* ``AUTOMOC`` always checks multiple header alternative extensions, - such as ``hpp``, ``hxx``, etc. when searching for headers. +- a Qt macro from :prop_tgt:`AUTOMOC_MACRO_NAMES`, +- additional file dependencies from the ``FILE`` argument of a + ``Q_PLUGIN_METADATA`` macro and +- additional file dependencies detected by filters defined in + :prop_tgt:`AUTOMOC_DEPEND_FILTERS`. -* ``AUTOMOC`` looks for the ``Q_PLUGIN_METADATA`` macro and reruns the - ``moc`` when the file addressed by the ``FILE`` argument of the macro changes. +If a Qt macro is found, then the header will be compiled by the ``moc`` to the +output file ``moc_<base_name>.cpp``. The complete output file path is +described in the section `Output file location`_. -This property is initialized by the value of the :variable:`CMAKE_AUTOMOC` -variable if it is set when a target is created. +The header will be ``moc`` compiled again if a file from the additional file +dependencies changes. + +Header ``moc`` output files ``moc_<base_name>.cpp`` can be included in source +files. In the section `Including header moc files in sources`_ there is more +information on that topic. + + +Source file processing +^^^^^^^^^^^^^^^^^^^^^^ + +At build time, CMake scans each unknown or modified C++ source file from the +target's sources for + +- a Qt macro from :prop_tgt:`AUTOMOC_MACRO_NAMES`, +- includes of header ``moc`` files + (see `Including header moc files in sources`_), +- additional file dependencies from the ``FILE`` argument of a + ``Q_PLUGIN_METADATA`` macro and +- additional file dependencies detected by filters defined in + :prop_tgt:`AUTOMOC_DEPEND_FILTERS`. + +If a Qt macro is found, then the C++ source file +``<base>.<source_extension>`` is expected to as well contain an include +statement + +.. code-block:: c++ + + #include <<base>.moc> // or + #include "<base>.moc" + +The source file then will be compiled by the ``moc`` to the output file +``<base>.moc``. A description of the complete output file path is in section +`Output file location`_. + +The source will be ``moc`` compiled again if a file from the additional file +dependencies changes. + +Including header moc files in sources +""""""""""""""""""""""""""""""""""""" + +A source file can include the ``moc`` output file of a header +``<header_base>.<header_extension>`` by using an include statement of +the form + +.. code-block:: c++ + + #include <moc_<header_base>.cpp> // or + #include "moc_<header_base>.cpp" + +If the ``moc`` output file of a header is included by a source, it will +be generated in a different location than if it was not included. This is +described in the section `Output file location`_. + + +Output file location +^^^^^^^^^^^^^^^^^^^^ + +Included moc output files +""""""""""""""""""""""""" + +``moc`` output files that are included by a source file will be generated in + +- ``<AUTOGEN_BUILD_DIR>/include`` + for single configuration generators or in +- ``<AUTOGEN_BUILD_DIR>/include_<CONFIG>`` + for :prop_gbl:`multi configuration <GENERATOR_IS_MULTI_CONFIG>` generators. + +Where ``<AUTOGEN_BUILD_DIR>`` is the value of the target property +:prop_tgt:`AUTOGEN_BUILD_DIR`. + +The include directory is automatically added to the target's +:prop_tgt:`INCLUDE_DIRECTORIES`. + +Not included moc output files +""""""""""""""""""""""""""""" + +``moc`` output files that are not included in a source file will be generated +in + +- ``<AUTOGEN_BUILD_DIR>/<SOURCE_DIR_CHECKSUM>`` + for single configuration generators or in, +- ``<AUTOGEN_BUILD_DIR>/include_<CONFIG>/<SOURCE_DIR_CHECKSUM>`` + for :prop_gbl:`multi configuration <GENERATOR_IS_MULTI_CONFIG>` generators. + +Where ``<SOURCE_DIR_CHECKSUM>`` is a checksum computed from the relative +parent directory path of the ``moc`` input file. This scheme allows to have +``moc`` input files with the same name in different directories. + +All not included ``moc`` output files will be included automatically by the +CMake generated file + +- ``<AUTOGEN_BUILD_DIR>/mocs_compilation.cpp``, + +which is added to the target's sources. + + +Qt version detection +^^^^^^^^^^^^^^^^^^^^ + +:prop_tgt:`AUTOMOC` enabled targets need to know the Qt major and minor +version they're working with. The major version usually is provided by the +``INTERFACE_QT_MAJOR_VERSION`` property of the ``Qt[45]Core`` library, +that the target links to. To find the minor version, CMake builds a list of +available Qt versions from + +- ``Qt5Core_VERSION_MAJOR`` and ``Qt5Core_VERSION_MINOR`` variables + (usually set by ``find_package(Qt5...)``) +- ``Qt5Core_VERSION_MAJOR`` and ``Qt5Core_VERSION_MINOR`` directory properties +- ``QT_VERSION_MAJOR`` and ``QT_VERSION_MINOR`` variables + (usually set by ``find_package(Qt4...)``) +- ``QT_VERSION_MAJOR`` and ``QT_VERSION_MINOR`` directory properties + +in the context of the :command:`add_executable` or :command:`add_library` call. + +Assumed ``INTERFACE_QT_MAJOR_VERSION`` is a valid number, the first +entry in the list with a matching major version is taken. If no matching major +version was found, an error is generated. +If ``INTERFACE_QT_MAJOR_VERSION`` is not a valid number, the first +entry in the list is taken. -Additional command line options for moc can be set via the -:prop_tgt:`AUTOMOC_MOC_OPTIONS` property. +A ``find_package(Qt[45]...)`` call sets the ``QT/Qt5Core_VERSION_MAJOR/MINOR`` +variables. If the call is in a different context than the +:command:`add_executable` or :command:`add_library` call, e.g. in a function, +then the version variables might not be available to the :prop_tgt:`AUTOMOC` +enabled target. +In that case the version variables can be forwarded from the +`find_package(Qt[45]...)` calling context to the :command:`add_executable` +or :command:`add_library` calling context as directory properties. +The following Qt5 example demonstrates the procedure. -By enabling the :variable:`CMAKE_AUTOMOC_RELAXED_MODE` variable the -rules for searching the files which will be processed by moc can be relaxed. -See the documentation for this variable for more details. +.. code-block:: cmake -The global property :prop_gbl:`AUTOGEN_TARGETS_FOLDER` can be used to group the -automoc targets together in an IDE, e.g. in MSVS. + function (add_qt5_client) + find_package(Qt5 REQUIRED QUIET COMPONENTS Core Widgets) + ... + set_property(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" + PROPERTY Qt5Core_VERSION_MAJOR "${Qt5Core_VERSION_MAJOR}") + set_property(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" + PROPERTY Qt5Core_VERSION_MINOR "${Qt5Core_VERSION_MAJOR}") + ... + endfunction () + ... + add_qt5_client() + add_executable(myTarget main.cpp) + target_link_libraries(myTarget Qt5::QtWidgets) + set_property(TARGET myTarget PROPERTY AUTOMOC ON) -The global property :prop_gbl:`AUTOGEN_SOURCE_GROUP` can be used to group -files generated by :prop_tgt:`AUTOMOC` together in an IDE, e.g. in MSVS. -Additional ``moc`` dependency file names can be extracted from source code -by using :prop_tgt:`AUTOMOC_DEPEND_FILTERS`. +Modifiers +^^^^^^^^^ -Source C++ files can be excluded from :prop_tgt:`AUTOMOC` processing by -enabling :prop_sf:`SKIP_AUTOMOC` or the broader :prop_sf:`SKIP_AUTOGEN`. +:prop_tgt:`AUTOMOC_EXECUTABLE`: +The ``moc`` executable will be detected automatically, but can be forced to +a certain binary using this target property. + +:prop_tgt:`AUTOMOC_MOC_OPTIONS`: +Additional command line options for ``moc`` can be set in this target property. + +:prop_tgt:`AUTOMOC_MACRO_NAMES`: +This list of Qt macro names can be extended to search for additional macros in +headers and sources. + +:prop_tgt:`AUTOMOC_DEPEND_FILTERS`: +``moc`` dependency file names can be extracted from headers or sources by +defining file name filters in this target property. + +:prop_tgt:`AUTOMOC_COMPILER_PREDEFINES`: +Compiler pre definitions for ``moc`` are written to the ``moc_predefs.h`` file. +The generation of this file can be enabled or disabled in this target property. + +:prop_sf:`SKIP_AUTOMOC`: +Sources and headers can be excluded from :prop_tgt:`AUTOMOC` processing by +setting this source file property. + +:prop_sf:`SKIP_AUTOGEN`: +Source files can be excluded from :prop_tgt:`AUTOMOC`, +:prop_tgt:`AUTOUIC` and :prop_tgt:`AUTORCC` processing by +setting this source file property. + +:prop_gbl:`AUTOGEN_SOURCE_GROUP`: +This global property can be used to group files generated by +:prop_tgt:`AUTOMOC` or :prop_tgt:`AUTORCC` together in an IDE, e.g. in MSVS. + +:prop_gbl:`AUTOGEN_TARGETS_FOLDER`: +This global property can be used to group :prop_tgt:`AUTOMOC`, +:prop_tgt:`AUTOUIC` and :prop_tgt:`AUTORCC` targets together in an IDE, +e.g. in MSVS. + +:variable:`CMAKE_GLOBAL_AUTOGEN_TARGET`: +A global ``autogen`` target, that depends on all :prop_tgt:`AUTOMOC` or +:prop_tgt:`AUTOUIC` generated ``<ORIGIN>_autogen`` targets in the project, +will be generated when this variable is ``ON``. + +:prop_tgt:`AUTOGEN_PARALLEL`: +This target property controls the number of ``moc`` or ``uic`` processes to +start in parallel during builds. See the :manual:`cmake-qt(7)` manual for more information on using CMake with Qt. diff --git a/Help/prop_tgt/AUTOMOC_COMPILER_PREDEFINES.rst b/Help/prop_tgt/AUTOMOC_COMPILER_PREDEFINES.rst new file mode 100644 index 000000000..57a647f3c --- /dev/null +++ b/Help/prop_tgt/AUTOMOC_COMPILER_PREDEFINES.rst @@ -0,0 +1,24 @@ +AUTOMOC_COMPILER_PREDEFINES +--------------------------- + +Boolean value used by :prop_tgt:`AUTOMOC` to determine if the +compiler pre definitions file ``moc_predefs.h`` should be generated. + +CMake generates a ``moc_predefs.h`` file with compiler pre definitions +from the output of the command defined in +:variable:`CMAKE_CXX_COMPILER_PREDEFINES_COMMAND <CMAKE_<LANG>_COMPILER_PREDEFINES_COMMAND>` +when + +- :prop_tgt:`AUTOMOC` is enabled, +- :prop_tgt:`AUTOMOC_COMPILER_PREDEFINES` is enabled, +- :variable:`CMAKE_CXX_COMPILER_PREDEFINES_COMMAND <CMAKE_<LANG>_COMPILER_PREDEFINES_COMMAND>` isn't empty and +- the Qt version is greater or equal 5.8. + +The ``moc_predefs.h`` file, which is generated in :prop_tgt:`AUTOGEN_BUILD_DIR`, +is passed to ``moc`` as the argument to the ``--include`` option. + +By default :prop_tgt:`AUTOMOC_COMPILER_PREDEFINES` is initialized from +:variable:`CMAKE_AUTOMOC_COMPILER_PREDEFINES`, which is ON by default. + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. diff --git a/Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst b/Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst index 810cbf4ae..69957bf18 100644 --- a/Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst +++ b/Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst @@ -1,21 +1,27 @@ AUTOMOC_DEPEND_FILTERS ---------------------- -Filter definitions used by :prop_tgt:`AUTOMOC` to extract file names from -source code as additional dependencies for the ``moc`` file. - -This property is only used if the :prop_tgt:`AUTOMOC` property is ``ON`` -for this target. +Filter definitions used by :prop_tgt:`AUTOMOC` to extract file names from a +source file that are registered as additional dependencies for the +``moc`` file of the source file. Filters are defined as ``KEYWORD;REGULAR_EXPRESSION`` pairs. First the file content is searched for ``KEYWORD``. If it is found at least once, then file names are extracted by successively searching for ``REGULAR_EXPRESSION`` and taking the first match group. -Consider a filter extracts the file name ``DEP`` from the content of a file -``FOO``. If ``DEP`` changes, then the ``moc`` file for ``FOO`` gets rebuilt. -The file ``DEP`` is searched for first in the vicinity -of ``FOO`` and afterwards in the target's :prop_tgt:`INCLUDE_DIRECTORIES`. +The file name found in the first match group is searched for + +- first in the vicinity of the source file +- and afterwards in the target's :prop_tgt:`INCLUDE_DIRECTORIES`. + +If any of the extracted files changes, then the ``moc`` file for the source +file gets rebuilt even when the source file itself doesn't change. + +If any of the extracted files is :prop_sf:`GENERATED` or if it is not in the +target's sources, then it might be necessary to add it to the +``_autogen`` target dependencies. +See :prop_tgt:`AUTOGEN_TARGET_DEPENDS` for reference. By default :prop_tgt:`AUTOMOC_DEPEND_FILTERS` is initialized from :variable:`CMAKE_AUTOMOC_DEPEND_FILTERS`, which is empty by default. @@ -24,22 +30,75 @@ See the :manual:`cmake-qt(7)` manual for more information on using CMake with Qt. -Example -------- +Example 1 +^^^^^^^^^ -Consider a file ``FOO.hpp`` holds a custom macro ``OBJ_JSON_FILE`` and we -want the ``moc`` file to depend on the macro`s file name argument:: +A header file ``my_class.hpp`` uses a custom macro ``JSON_FILE_MACRO`` which +is defined in an other header ``macros.hpp``. +We want the ``moc`` file of ``my_class.hpp`` to depend on the file name +argument of ``JSON_FILE_MACRO``:: + // my_class.hpp class My_Class : public QObject { Q_OBJECT - OBJ_JSON_FILE ( "DEP.json" ) + JSON_FILE_MACRO ( "info.json" ) + ... + }; + +In ``CMakeLists.txt`` we add a filter to +:variable:`CMAKE_AUTOMOC_DEPEND_FILTERS` like this:: + + list( APPEND CMAKE_AUTOMOC_DEPEND_FILTERS + "JSON_FILE_MACRO" + "[\n][ \t]*JSON_FILE_MACRO[ \t]*\\([ \t]*\"([^\"]+)\"" + ) + +We assume ``info.json`` is a plain (not :prop_sf:`GENERATED`) file that is +listed in the target's source. Therefore we do not need to add it to +:prop_tgt:`AUTOGEN_TARGET_DEPENDS`. + +Example 2 +^^^^^^^^^ + +In the target ``my_target`` a header file ``complex_class.hpp`` uses a +custom macro ``JSON_BASED_CLASS`` which is defined in an other header +``macros.hpp``:: + + // macros.hpp ... + #define JSON_BASED_CLASS(name, json) \ + class name : public QObject \ + { \ + Q_OBJECT \ + Q_PLUGIN_METADATA(IID "demo" FILE json) \ + name() {} \ }; + ... + +:: -Then we might use :variable:`CMAKE_AUTOMOC_DEPEND_FILTERS` to -define a filter like this:: + // complex_class.hpp + #pragma once + JSON_BASED_CLASS(Complex_Class, "meta.json") + // end of file - set(CMAKE_AUTOMOC_DEPEND_FILTERS - "OBJ_JSON_FILE" "[\n][ \t]*OBJ_JSON_FILE[ \t]*\\([ \t]*\"([^\"]+)\"" +Since ``complex_class.hpp`` doesn't contain a ``Q_OBJECT`` macro it would be +ignored by :prop_tgt:`AUTOMOC`. We change this by adding ``JSON_BASED_CLASS`` +to :variable:`CMAKE_AUTOMOC_MACRO_NAMES`:: + + list(APPEND CMAKE_AUTOMOC_MACRO_NAMES "JSON_BASED_CLASS") + +We want the ``moc`` file of ``complex_class.hpp`` to depend on +``meta.json``. So we add a filter to +:variable:`CMAKE_AUTOMOC_DEPEND_FILTERS`:: + + list(APPEND CMAKE_AUTOMOC_DEPEND_FILTERS + "JSON_BASED_CLASS" + "[\n^][ \t]*JSON_BASED_CLASS[ \t]*\\([^,]*,[ \t]*\"([^\"]+)\"" ) + +Additionally we assume ``meta.json`` is :prop_sf:`GENERATED` which is +why we have to add it to :prop_tgt:`AUTOGEN_TARGET_DEPENDS`:: + + set_property(TARGET my_target APPEND PROPERTY AUTOGEN_TARGET_DEPENDS "meta.json") diff --git a/Help/prop_tgt/AUTOMOC_EXECUTABLE.rst b/Help/prop_tgt/AUTOMOC_EXECUTABLE.rst new file mode 100644 index 000000000..6b66ce81f --- /dev/null +++ b/Help/prop_tgt/AUTOMOC_EXECUTABLE.rst @@ -0,0 +1,15 @@ +AUTOMOC_EXECUTABLE +------------------ + +:prop_tgt:`AUTOMOC_EXECUTABLE` is file path pointing to the ``moc`` +executable to use for :prop_tgt:`AUTOMOC` enabled files. Setting +this property will make CMake skip the automatic detection of the +``moc`` binary as well as the sanity-tests normally run to ensure +that the binary is available and working as expected. + +Usually this property does not need to be set. Only consider this +property if auto-detection of ``moc`` can not work -- e.g. because +you are building the ``moc`` binary as part of your project. + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. diff --git a/Help/prop_tgt/AUTOMOC_MACRO_NAMES.rst b/Help/prop_tgt/AUTOMOC_MACRO_NAMES.rst new file mode 100644 index 000000000..5329bbac9 --- /dev/null +++ b/Help/prop_tgt/AUTOMOC_MACRO_NAMES.rst @@ -0,0 +1,32 @@ +AUTOMOC_MACRO_NAMES +------------------- + +A :ref:`semicolon-separated list <CMake Language Lists>` list of macro names used by +:prop_tgt:`AUTOMOC` to determine if a C++ file needs to be processed by ``moc``. + +This property is only used if the :prop_tgt:`AUTOMOC` property is ``ON`` +for this target. + +When running :prop_tgt:`AUTOMOC`, CMake searches for the strings listed in +:prop_tgt:`AUTOMOC_MACRO_NAMES` in C++ source and header files. +If any of the strings is found + +- as the first non space string on a new line or +- as the first non space string after a ``{`` on a new line, + +then the file will be processed by ``moc``. + +By default :prop_tgt:`AUTOMOC_MACRO_NAMES` is initialized from +:variable:`CMAKE_AUTOMOC_MACRO_NAMES`. + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. + +Example +^^^^^^^ + +In this case the ``Q_OBJECT`` macro is hidden inside another macro +called ``CUSTOM_MACRO``. To let CMake know that source files that contain +``CUSTOM_MACRO`` need to be ``moc`` processed, we call:: + + set_property(TARGET tgt APPEND PROPERTY AUTOMOC_MACRO_NAMES "CUSTOM_MACRO") diff --git a/Help/prop_tgt/AUTOMOC_PATH_PREFIX.rst b/Help/prop_tgt/AUTOMOC_PATH_PREFIX.rst new file mode 100644 index 000000000..e2ebb3ffc --- /dev/null +++ b/Help/prop_tgt/AUTOMOC_PATH_PREFIX.rst @@ -0,0 +1,32 @@ +AUTOMOC_PATH_PREFIX +------------------- + +When this property is ``ON``, CMake will generate the ``-p`` path prefix +option for ``moc`` on :prop_tgt:`AUTOMOC` enabled Qt targets. + +To generate the path prefix, CMake tests if the header compiled by ``moc`` +is in any of the target +:command:`include directories <target_include_directories>`. If so, CMake will +compute the relative path accordingly. If the header is not in the +:command:`include directories <target_include_directories>`, CMake will omit +the ``-p`` path prefix option. ``moc`` usually generates a +relative include path in that case. + +:prop_tgt:`AUTOMOC_PATH_PREFIX` is initialized from the variable +:variable:`CMAKE_AUTOMOC_PATH_PREFIX`, which is ``ON`` by default. + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. + +Reproducible builds +^^^^^^^^^^^^^^^^^^^ + +For reproducible builds is is recommended to keep headers that are ``moc`` +compiled in one of the target +:command:`include directories <target_include_directories>` and set +:prop_tgt:`AUTOMOC_PATH_PREFIX` to ``ON`` (which is the default). This ensures +that + +- ``moc`` output files are identical on different build setups, +- ``moc`` output files will compile correctly when the source and/or + build directory is a symbolic link. diff --git a/Help/prop_tgt/AUTORCC.rst b/Help/prop_tgt/AUTORCC.rst index c0f6a26b2..cca3e583f 100644 --- a/Help/prop_tgt/AUTORCC.rst +++ b/Help/prop_tgt/AUTORCC.rst @@ -1,9 +1,9 @@ AUTORCC ------- -Should the target be processed with autorcc (for Qt projects). +Should the target be processed with auto-rcc (for Qt projects). -``AUTORCC`` is a boolean specifying whether CMake will handle +:prop_tgt:`AUTORCC` is a boolean specifying whether CMake will handle the Qt ``rcc`` code generator automatically, i.e. without having to use the :module:`QT4_ADD_RESOURCES() <FindQt4>` or ``QT5_ADD_RESOURCES()`` macro. Currently Qt4 and Qt5 are supported. @@ -13,22 +13,49 @@ as target sources at build time and invoke ``rcc`` accordingly. This property is initialized by the value of the :variable:`CMAKE_AUTORCC` variable if it is set when a target is created. -Additional command line options for rcc can be set via the -:prop_sf:`AUTORCC_OPTIONS` source file property on the ``.qrc`` file. - -The global property :prop_gbl:`AUTOGEN_TARGETS_FOLDER` can be used to group -the autorcc targets together in an IDE, e.g. in MSVS. - -The global property :prop_gbl:`AUTOGEN_SOURCE_GROUP` can be used to group -files generated by :prop_tgt:`AUTORCC` together in an IDE, e.g. in MSVS. +By default :prop_tgt:`AUTORCC` is processed by a +:command:`custom command <add_custom_command>`. +If the ``.qrc`` file is :prop_sf:`GENERATED`, a +:command:`custom target <add_custom_target>` is used instead. When there are multiple ``.qrc`` files with the same name, CMake will -generate unspecified unique names for ``rcc``. Therefore if -``Q_INIT_RESOURCE()`` or ``Q_CLEANUP_RESOURCE()`` need to be used the +generate unspecified unique output file names for ``rcc``. Therefore, if +``Q_INIT_RESOURCE()`` or ``Q_CLEANUP_RESOURCE()`` need to be used, the ``.qrc`` file name must be unique. -Source files can be excluded from :prop_tgt:`AUTORCC` processing by -enabling :prop_sf:`SKIP_AUTORCC` or the broader :prop_sf:`SKIP_AUTOGEN`. + +Modifiers +^^^^^^^^^ + +:prop_tgt:`AUTORCC_EXECUTABLE`: +The ``rcc`` executable will be detected automatically, but can be forced to +a certain binary by setting this target property. + +:prop_sf:`AUTORCC_OPTIONS`: +Additional command line options for ``rcc`` can be set via this ``.qrc`` +source file property. + +:prop_sf:`SKIP_AUTORCC`: +``.qrc`` files can be excluded from :prop_tgt:`AUTORCC` processing by +setting this source file property. + +:prop_sf:`SKIP_AUTOGEN`: +Source files can be excluded from :prop_tgt:`AUTOMOC`, +:prop_tgt:`AUTOUIC` and :prop_tgt:`AUTORCC` processing by +setting this source file property. + +:prop_gbl:`AUTOGEN_SOURCE_GROUP`: +This global property can be used to group files generated by +:prop_tgt:`AUTOMOC` or :prop_tgt:`AUTORCC` together in an IDE, e.g. in MSVS. + +:prop_gbl:`AUTOGEN_TARGETS_FOLDER`: +This global property can be used to group :prop_tgt:`AUTOMOC`, +:prop_tgt:`AUTOUIC` and :prop_tgt:`AUTORCC` targets together in an IDE, +e.g. in MSVS. + +:variable:`CMAKE_GLOBAL_AUTORCC_TARGET`: +A global ``autorcc`` target that depends on all :prop_tgt:`AUTORCC` targets +in the project will be generated when this variable is ``ON``. See the :manual:`cmake-qt(7)` manual for more information on using CMake with Qt. diff --git a/Help/prop_tgt/AUTORCC_EXECUTABLE.rst b/Help/prop_tgt/AUTORCC_EXECUTABLE.rst new file mode 100644 index 000000000..ca0fbd75b --- /dev/null +++ b/Help/prop_tgt/AUTORCC_EXECUTABLE.rst @@ -0,0 +1,15 @@ +AUTORCC_EXECUTABLE +------------------ + +:prop_tgt:`AUTORCC_EXECUTABLE` is file path pointing to the ``rcc`` +executable to use for :prop_tgt:`AUTORCC` enabled files. Setting +this property will make CMake skip the automatic detection of the +``rcc`` binary as well as the sanity-tests normally run to ensure +that the binary is available and working as expected. + +Usually this property does not need to be set. Only consider this +property if auto-detection of ``rcc`` can not work -- e.g. because +you are building the ``rcc`` binary as part of your project. + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. diff --git a/Help/prop_tgt/AUTORCC_OPTIONS.rst b/Help/prop_tgt/AUTORCC_OPTIONS.rst index 8a0f632c2..d6ade5adb 100644 --- a/Help/prop_tgt/AUTORCC_OPTIONS.rst +++ b/Help/prop_tgt/AUTORCC_OPTIONS.rst @@ -19,3 +19,12 @@ set on the ``.qrc`` source file. See the :manual:`cmake-qt(7)` manual for more information on using CMake with Qt. + +EXAMPLE +^^^^^^^ + +.. code-block:: cmake + + # ... + set_property(TARGET tgt PROPERTY AUTORCC_OPTIONS "--compress;9") + # ... diff --git a/Help/prop_tgt/AUTOUIC.rst b/Help/prop_tgt/AUTOUIC.rst index 6493bbc78..5cf87552c 100644 --- a/Help/prop_tgt/AUTOUIC.rst +++ b/Help/prop_tgt/AUTOUIC.rst @@ -1,34 +1,82 @@ AUTOUIC ------- -Should the target be processed with autouic (for Qt projects). +Should the target be processed with auto-uic (for Qt projects). -``AUTOUIC`` is a boolean specifying whether CMake will handle +:prop_tgt:`AUTOUIC` is a boolean specifying whether CMake will handle the Qt ``uic`` code generator automatically, i.e. without having to use the :module:`QT4_WRAP_UI() <FindQt4>` or ``QT5_WRAP_UI()`` macro. Currently Qt4 and Qt5 are supported. -When this property is ``ON``, CMake will scan the source files at build time -and invoke ``uic`` accordingly. If an ``#include`` statement like -``#include "ui_foo.h"`` is found in ``source.cpp``, a ``foo.ui`` file is -searched for first in the vicinity of ``source.cpp`` and afterwards in the -optional :prop_tgt:`AUTOUIC_SEARCH_PATHS` of the target. -``uic`` is run on the ``foo.ui`` file to generate ``ui_foo.h`` in the directory -``<AUTOGEN_BUILD_DIR>/include``, -which is automatically added to the target's :prop_tgt:`INCLUDE_DIRECTORIES`. - -* See :prop_tgt:`AUTOGEN_BUILD_DIR`. - This property is initialized by the value of the :variable:`CMAKE_AUTOUIC` variable if it is set when a target is created. -Additional command line options for ``uic`` can be set via the -:prop_sf:`AUTOUIC_OPTIONS` source file property on the ``foo.ui`` file. -The global property :prop_gbl:`AUTOGEN_TARGETS_FOLDER` can be used to group the -autouic targets together in an IDE, e.g. in MSVS. +When this property is ``ON``, CMake will scan the header and source files at +build time and invoke ``uic`` accordingly. + + +Header and source file processing +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +At build time, CMake scans each header and source file from the +target's sources for include statements of the form + +.. code-block:: c++ + + #include "ui_<ui_base>.h" + +Once such an include statement is found in a file, CMake searches for the +``uic`` input file ``<ui_base>.ui`` + +- in the vicinity of the file and +- in the :prop_tgt:`AUTOUIC_SEARCH_PATHS` of the target. + +If the ``<ui_base>.ui`` file was found, ``uic`` is called on it to generate +``ui_<ui_base>.h`` in the directory + +- ``<AUTOGEN_BUILD_DIR>/include`` for single configuration generators or in +- ``<AUTOGEN_BUILD_DIR>/include_<CONFIG>`` for + :prop_gbl:`multi configuration <GENERATOR_IS_MULTI_CONFIG>` generators. + +Where ``<AUTOGEN_BUILD_DIR>`` is the value of the target property +:prop_tgt:`AUTOGEN_BUILD_DIR`. + +The include directory is automatically added to the target's +:prop_tgt:`INCLUDE_DIRECTORIES`. + + +Modifiers +^^^^^^^^^ + +:prop_tgt:`AUTOUIC_EXECUTABLE`: +The ``uic`` executable will be detected automatically, but can be forced to +a certain binary using this target property. + +:prop_sf:`AUTOUIC_OPTIONS`: Additional command line options for ``uic`` can +be set via this source file property on a ``<base_name>.ui`` file. + +:prop_sf:`SKIP_AUTOUIC`: +Source files can be excluded from :prop_tgt:`AUTOUIC` processing by setting +this source file property. + +:prop_sf:`SKIP_AUTOGEN`: +Source files can be excluded from :prop_tgt:`AUTOMOC`, +:prop_tgt:`AUTOUIC` and :prop_tgt:`AUTORCC` processing by +setting this source file property. + +:prop_gbl:`AUTOGEN_TARGETS_FOLDER`: +This global property can be used to group :prop_tgt:`AUTOMOC`, +:prop_tgt:`AUTOUIC` and :prop_tgt:`AUTORCC` targets together in an IDE, +e.g. in MSVS. + +:variable:`CMAKE_GLOBAL_AUTOGEN_TARGET`: +A global ``autogen`` target, that depends on all :prop_tgt:`AUTOMOC` or +:prop_tgt:`AUTOUIC` generated ``<ORIGIN>_autogen`` targets in the project, +will be generated when this variable is ``ON``. -Source files can be excluded from :prop_tgt:`AUTOUIC` processing by -enabling :prop_sf:`SKIP_AUTOUIC` or the broader :prop_sf:`SKIP_AUTOGEN`. +:prop_tgt:`AUTOGEN_PARALLEL`: +This target property controls the number of ``moc`` or ``uic`` processes to +start in parallel during builds. See the :manual:`cmake-qt(7)` manual for more information on using CMake with Qt. diff --git a/Help/prop_tgt/AUTOUIC_EXECUTABLE.rst b/Help/prop_tgt/AUTOUIC_EXECUTABLE.rst new file mode 100644 index 000000000..03bd55499 --- /dev/null +++ b/Help/prop_tgt/AUTOUIC_EXECUTABLE.rst @@ -0,0 +1,15 @@ +AUTOUIC_EXECUTABLE +------------------ + +:prop_tgt:`AUTOUIC_EXECUTABLE` is file path pointing to the ``uic`` +executable to use for :prop_tgt:`AUTOUIC` enabled files. Setting +this property will make CMake skip the automatic detection of the +``uic`` binary as well as the sanity-tests normally run to ensure +that the binary is available and working as expected. + +Usually this property does not need to be set. Only consider this +property if auto-detection of ``uic`` can not work -- e.g. because +you are building the ``uic`` binary as part of your project. + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. diff --git a/Help/prop_tgt/AUTOUIC_OPTIONS.rst b/Help/prop_tgt/AUTOUIC_OPTIONS.rst index 9fb042ea6..3f613b952 100644 --- a/Help/prop_tgt/AUTOUIC_OPTIONS.rst +++ b/Help/prop_tgt/AUTOUIC_OPTIONS.rst @@ -23,3 +23,12 @@ expressions. See the :manual:`cmake-qt(7)` manual for more information on using CMake with Qt. + +EXAMPLE +^^^^^^^ + +.. code-block:: cmake + + # ... + set_property(TARGET tgt PROPERTY AUTOUIC_OPTIONS "--no-protection") + # ... diff --git a/Help/prop_tgt/BUILD_RPATH.rst b/Help/prop_tgt/BUILD_RPATH.rst index 27393f5d7..d978b9439 100644 --- a/Help/prop_tgt/BUILD_RPATH.rst +++ b/Help/prop_tgt/BUILD_RPATH.rst @@ -1,10 +1,13 @@ BUILD_RPATH ----------- -A :ref:`;-list <CMake Language Lists>` specifying runtime path (``RPATH``) +A :ref:`semicolon-separated list <CMake Language Lists>` specifying runtime path (``RPATH``) entries to add to binaries linked in the build tree (for platforms that support it). The entries will *not* be used for binaries in the install tree. See also the :prop_tgt:`INSTALL_RPATH` target property. This property is initialized by the value of the variable :variable:`CMAKE_BUILD_RPATH` if it is set when a target is created. + +This property supports +:manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/prop_tgt/BUILD_RPATH_USE_ORIGIN.rst b/Help/prop_tgt/BUILD_RPATH_USE_ORIGIN.rst new file mode 100644 index 000000000..337879780 --- /dev/null +++ b/Help/prop_tgt/BUILD_RPATH_USE_ORIGIN.rst @@ -0,0 +1,24 @@ +BUILD_RPATH_USE_ORIGIN +---------------------- + +Whether to use relative paths for the build ``RPATH``. + +This property is initialized by the value of the variable +:variable:`CMAKE_BUILD_RPATH_USE_ORIGIN`. + +On platforms that support runtime paths (``RPATH``) with the +``$ORIGIN`` token, setting this property to ``TRUE`` enables relative +paths in the build ``RPATH`` for executables and shared libraries that +point to shared libraries in the same build tree. + +Normally the build ``RPATH`` of a binary contains absolute paths +to the directory of each shared library it links to. The ``RPATH`` +entries for directories contained within the build tree can be made +relative to enable relocatable builds and to help achieve reproducible +builds by omitting the build directory from the build environment. + +This property has no effect on platforms that do not support the +``$ORIGIN`` token in ``RPATH``, or when the :variable:`CMAKE_SKIP_RPATH` +variable is set. The runtime path set through the +:prop_tgt:`BUILD_RPATH` target property is also unaffected by this +property. diff --git a/Help/prop_tgt/BUNDLE.rst b/Help/prop_tgt/BUNDLE.rst index 075f017df..c556ac32c 100644 --- a/Help/prop_tgt/BUNDLE.rst +++ b/Help/prop_tgt/BUNDLE.rst @@ -1,7 +1,7 @@ BUNDLE ------ -This target is a ``CFBundle`` on the OS X. +This target is a ``CFBundle`` on the macOS. If a module library target has this property set to true it will be built as a ``CFBundle`` when built on the mac. It will have the directory diff --git a/Help/prop_tgt/BUNDLE_EXTENSION.rst b/Help/prop_tgt/BUNDLE_EXTENSION.rst index 6b3d58023..70de11c40 100644 --- a/Help/prop_tgt/BUNDLE_EXTENSION.rst +++ b/Help/prop_tgt/BUNDLE_EXTENSION.rst @@ -2,7 +2,7 @@ BUNDLE_EXTENSION ---------------- The file extension used to name a :prop_tgt:`BUNDLE`, a :prop_tgt:`FRAMEWORK`, -or a :prop_tgt:`MACOSX_BUNDLE` target on the OS X and iOS. +or a :prop_tgt:`MACOSX_BUNDLE` target on the macOS and iOS. The default value is ``bundle``, ``framework``, or ``app`` for the respective target types. diff --git a/Help/prop_tgt/COMMON_LANGUAGE_RUNTIME.rst b/Help/prop_tgt/COMMON_LANGUAGE_RUNTIME.rst new file mode 100644 index 000000000..052ac6df0 --- /dev/null +++ b/Help/prop_tgt/COMMON_LANGUAGE_RUNTIME.rst @@ -0,0 +1,22 @@ +COMMON_LANGUAGE_RUNTIME +----------------------- + +By setting this target property, the target is configured to build with +``C++/CLI`` support. + +The Visual Studio generator defines the ``clr`` parameter depending on +the value of ``COMMON_LANGUAGE_RUNTIME``: + +* property not set: native C++ (i.e. default) +* property set but empty: mixed unmanaged/managed C++ +* property set to any non empty value: managed C++ + +Supported values: ``""``, ``"pure"``, ``"safe"`` + +This property is only evaluated :ref:`Visual Studio Generators` for +VS 2010 and above. + +To be able to build managed C++ targets with VS 2017 and above the component +``C++/CLI support`` must be installed, which may not be done by default. + +See also :prop_tgt:`IMPORTED_COMMON_LANGUAGE_RUNTIME` diff --git a/Help/prop_tgt/COMPILE_FLAGS.rst b/Help/prop_tgt/COMPILE_FLAGS.rst index 1a5389e48..8fe651b4a 100644 --- a/Help/prop_tgt/COMPILE_FLAGS.rst +++ b/Help/prop_tgt/COMPILE_FLAGS.rst @@ -8,4 +8,4 @@ build sources within the target. Use :prop_tgt:`COMPILE_DEFINITIONS` to pass additional preprocessor definitions. This property is deprecated. Use the :prop_tgt:`COMPILE_OPTIONS` -property or the command:`target_compile_options` command instead. +property or the :command:`target_compile_options` command instead. diff --git a/Help/prop_tgt/COMPILE_OPTIONS.rst b/Help/prop_tgt/COMPILE_OPTIONS.rst index 892ac23e1..0cd683610 100644 --- a/Help/prop_tgt/COMPILE_OPTIONS.rst +++ b/Help/prop_tgt/COMPILE_OPTIONS.rst @@ -3,7 +3,7 @@ COMPILE_OPTIONS List of options to pass to the compiler. -This property holds a :ref:`;-list <CMake Language Lists>` of options +This property holds a :ref:`semicolon-separated list <CMake Language Lists>` of options specified so far for its target. Use the :command:`target_compile_options` command to append more options. diff --git a/Help/prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG.rst b/Help/prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG.rst index 52ef013da..f261756f1 100644 --- a/Help/prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG.rst +++ b/Help/prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG.rst @@ -6,7 +6,7 @@ generated by the compiler while building source files. This is a per-configuration version of :prop_tgt:`COMPILE_PDB_OUTPUT_DIRECTORY`, -but multi-configuration generators (VS, Xcode) do NOT append a +but multi-configuration generators (Visual Studio, Xcode) do NOT append a per-configuration subdirectory to the specified directory. This property is initialized by the value of the :variable:`CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG>` variable diff --git a/Help/prop_tgt/CROSSCOMPILING_EMULATOR.rst b/Help/prop_tgt/CROSSCOMPILING_EMULATOR.rst index a0811bcaa..87c5978bc 100644 --- a/Help/prop_tgt/CROSSCOMPILING_EMULATOR.rst +++ b/Help/prop_tgt/CROSSCOMPILING_EMULATOR.rst @@ -6,6 +6,10 @@ This command will be added as a prefix to :command:`add_test`, :command:`add_custom_command`, and :command:`add_custom_target` commands for built target system executables. +If this property contains a :ref:`semicolon-separated list <CMake Language +Lists>`, then the first value is the command and remaining values are its +arguments. + This property is initialized by the value of the :variable:`CMAKE_CROSSCOMPILING_EMULATOR` variable if it is set when a target is created. diff --git a/Help/prop_tgt/CUDA_RESOLVE_DEVICE_SYMBOLS.rst b/Help/prop_tgt/CUDA_RESOLVE_DEVICE_SYMBOLS.rst index 127d79fb3..dae960fbe 100644 --- a/Help/prop_tgt/CUDA_RESOLVE_DEVICE_SYMBOLS.rst +++ b/Help/prop_tgt/CUDA_RESOLVE_DEVICE_SYMBOLS.rst @@ -1,12 +1,22 @@ CUDA_RESOLVE_DEVICE_SYMBOLS --------------------------- -CUDA only: Enables device linking for the specific static library target +CUDA only: Enables device linking for the specific library target where +required. + +If set, this will tell the required compilers to enable device linking +on the library target. Device linking is an additional link step +required by some CUDA compilers when :prop_tgt:`CUDA_SEPARABLE_COMPILATION` is +enabled. Normally device linking is deferred until a shared library or +executable is generated, allowing for multiple static libraries to resolve +device symbols at the same time when they are used by a shared library or +executable. + +By default static library targets have this property is disabled, +while shared, module, and executable targets have this property enabled. + +Note that device linking is not supported for :ref:`Object Libraries`. -If set this will enable device linking on this static library target. Normally -device linking is deferred until a shared library or executable is generated, -allowing for multiple static libraries to resolve device symbols at the same -time. For instance: diff --git a/Help/prop_tgt/CUDA_SEPARABLE_COMPILATION.rst b/Help/prop_tgt/CUDA_SEPARABLE_COMPILATION.rst index 1c7dd8083..d306d7f82 100644 --- a/Help/prop_tgt/CUDA_SEPARABLE_COMPILATION.rst +++ b/Help/prop_tgt/CUDA_SEPARABLE_COMPILATION.rst @@ -11,3 +11,7 @@ For instance: .. code-block:: cmake set_property(TARGET myexe PROPERTY CUDA_SEPARABLE_COMPILATION ON) + +This property is initialized by the value of the +:variable:`CMAKE_CUDA_SEPARABLE_COMPILATION` variable if it is set when a +target is created. diff --git a/Help/prop_tgt/CUDA_STANDARD.rst b/Help/prop_tgt/CUDA_STANDARD.rst index b26281471..a3a2f5689 100644 --- a/Help/prop_tgt/CUDA_STANDARD.rst +++ b/Help/prop_tgt/CUDA_STANDARD.rst @@ -7,7 +7,7 @@ This property specifies the CUDA/C++ standard whose features are requested to build this target. For some compilers, this results in adding a flag such as ``-std=gnu++11`` to the compile line. -Supported values are ``98``, ``11``. +Supported values are ``98``, ``11``, ``14``. If the value requested does not result in a compile flag being added for the compiler in use, a previous standard flag will be added instead. This diff --git a/Help/prop_tgt/CXX_STANDARD.rst b/Help/prop_tgt/CXX_STANDARD.rst index 30a612db6..ccc014790 100644 --- a/Help/prop_tgt/CXX_STANDARD.rst +++ b/Help/prop_tgt/CXX_STANDARD.rst @@ -6,9 +6,10 @@ The C++ standard whose features are requested to build this target. This property specifies the C++ standard whose features are requested to build this target. For some compilers, this results in adding a flag such as ``-std=gnu++11`` to the compile line. For compilers that -have no notion of a standard level, such as MSVC, this has no effect. +have no notion of a standard level, such as Microsoft Visual C++ before +2015 Update 3, this has no effect. -Supported values are ``98``, ``11``, ``14``, and ``17``. +Supported values are ``98``, ``11``, ``14``, ``17``, and ``20``. If the value requested does not result in a compile flag being added for the compiler in use, a previous standard flag will be added instead. This diff --git a/Help/prop_tgt/C_STANDARD.rst b/Help/prop_tgt/C_STANDARD.rst index 815a68676..e7f7904f2 100644 --- a/Help/prop_tgt/C_STANDARD.rst +++ b/Help/prop_tgt/C_STANDARD.rst @@ -6,7 +6,8 @@ The C standard whose features are requested to build this target. This property specifies the C standard whose features are requested to build this target. For some compilers, this results in adding a flag such as ``-std=gnu11`` to the compile line. For compilers that -have no notion of a standard level, such as MSVC, this has no effect. +have no notion of a standard level, such as Microsoft Visual C++ before +2015 Update 3, this has no effect. Supported values are ``90``, ``99`` and ``11``. diff --git a/Help/prop_tgt/DEBUG_POSTFIX.rst b/Help/prop_tgt/DEBUG_POSTFIX.rst index 1487656d9..04e312e37 100644 --- a/Help/prop_tgt/DEBUG_POSTFIX.rst +++ b/Help/prop_tgt/DEBUG_POSTFIX.rst @@ -1,7 +1,7 @@ DEBUG_POSTFIX ------------- -See target property <CONFIG>_POSTFIX. +See target property ``<CONFIG>_POSTFIX``. -This property is a special case of the more-general <CONFIG>_POSTFIX -property for the DEBUG configuration. +This property is a special case of the more-general ``<CONFIG>_POSTFIX`` +property for the ``DEBUG`` configuration. diff --git a/Help/prop_tgt/DEFINE_SYMBOL.rst b/Help/prop_tgt/DEFINE_SYMBOL.rst index f47f135ea..eb7f93735 100644 --- a/Help/prop_tgt/DEFINE_SYMBOL.rst +++ b/Help/prop_tgt/DEFINE_SYMBOL.rst @@ -3,9 +3,9 @@ DEFINE_SYMBOL Define a symbol when compiling this target's sources. -DEFINE_SYMBOL sets the name of the preprocessor symbol defined when +``DEFINE_SYMBOL`` sets the name of the preprocessor symbol defined when compiling sources in a shared library. If not set here then it is set -to target_EXPORTS by default (with some substitutions if the target is +to ``target_EXPORTS`` by default (with some substitutions if the target is not a valid C identifier). This is useful for headers to know whether they are being included from inside their library or outside to properly setup dllexport/dllimport decorations. diff --git a/Help/prop_tgt/DEPLOYMENT_ADDITIONAL_FILES.rst b/Help/prop_tgt/DEPLOYMENT_ADDITIONAL_FILES.rst new file mode 100644 index 000000000..5e9c19158 --- /dev/null +++ b/Help/prop_tgt/DEPLOYMENT_ADDITIONAL_FILES.rst @@ -0,0 +1,18 @@ +DEPLOYMENT_ADDITIONAL_FILES +--------------------------- + +Set the WinCE project ``AdditionalFiles`` in ``DeploymentTool`` in ``.vcproj`` +files generated by the :generator:`Visual Studio 9 2008` generator. +This is useful when you want to debug on remote WinCE device. +Specify additional files that will be copied to the device. +For example: + +.. code-block:: cmake + + set_property(TARGET ${TARGET} PROPERTY + DEPLOYMENT_ADDITIONAL_FILES "english.lng|local_folder|remote_folder|0" + "german.lng|local_folder|remote_folder|0") + +produces:: + + <DeploymentTool AdditionalFiles="english.lng|local_folder|remote_folder|0;german.lng|local_folder|remote_folder|0" ... /> diff --git a/Help/prop_tgt/DEPLOYMENT_REMOTE_DIRECTORY.rst b/Help/prop_tgt/DEPLOYMENT_REMOTE_DIRECTORY.rst index 1ff5bf01e..368768ae7 100644 --- a/Help/prop_tgt/DEPLOYMENT_REMOTE_DIRECTORY.rst +++ b/Help/prop_tgt/DEPLOYMENT_REMOTE_DIRECTORY.rst @@ -3,8 +3,8 @@ DEPLOYMENT_REMOTE_DIRECTORY Set the WinCE project ``RemoteDirectory`` in ``DeploymentTool`` and ``RemoteExecutable`` in ``DebuggerTool`` in ``.vcproj`` files generated -by the :generator:`Visual Studio 9 2008` and :generator:`Visual Studio 8 2005` -generators. This is useful when you want to debug on remote WinCE device. +by the :generator:`Visual Studio 9 2008` generator. +This is useful when you want to debug on remote WinCE device. For example: .. code-block:: cmake diff --git a/Help/prop_tgt/DISABLE_PRECOMPILE_HEADERS.rst b/Help/prop_tgt/DISABLE_PRECOMPILE_HEADERS.rst new file mode 100644 index 000000000..4cef0231a --- /dev/null +++ b/Help/prop_tgt/DISABLE_PRECOMPILE_HEADERS.rst @@ -0,0 +1,8 @@ +DISABLE_PRECOMPILE_HEADERS +-------------------------- + +Disables the precompilation of header files specified by +:prop_tgt:`PRECOMPILE_HEADERS` property. + +If the property is not set, CMake will use the value provided +by :variable:`CMAKE_DISABLE_PRECOMPILE_HEADERS`. diff --git a/Help/prop_tgt/DOTNET_TARGET_FRAMEWORK_VERSION.rst b/Help/prop_tgt/DOTNET_TARGET_FRAMEWORK_VERSION.rst new file mode 100644 index 000000000..c100326b9 --- /dev/null +++ b/Help/prop_tgt/DOTNET_TARGET_FRAMEWORK_VERSION.rst @@ -0,0 +1,13 @@ +DOTNET_TARGET_FRAMEWORK_VERSION +------------------------------- + +Specify the .NET target framework version. + +Used to specify the .NET target framework version for C++/CLI. For +example: ``v4.5``. + +This property is only evaluated for :ref:`Visual Studio Generators` +VS 2010 and above. + +Can be initialized for all targets using the variable +:variable:`CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION`. diff --git a/Help/prop_tgt/ENABLE_EXPORTS.rst b/Help/prop_tgt/ENABLE_EXPORTS.rst index 9e2230971..0b1064ab4 100644 --- a/Help/prop_tgt/ENABLE_EXPORTS.rst +++ b/Help/prop_tgt/ENABLE_EXPORTS.rst @@ -7,16 +7,25 @@ Normally an executable does not export any symbols because it is the final program. It is possible for an executable to export symbols to be used by loadable modules. When this property is set to true CMake will allow other targets to "link" to the executable with the -:command:`TARGET_LINK_LIBRARIES` command. On all platforms a target-level +:command:`target_link_libraries` command. On all platforms a target-level dependency on the executable is created for targets that link to it. -For DLL platforms an import library will be created for the exported -symbols and then used for linking. All Windows-based systems -including Cygwin are DLL platforms. For non-DLL platforms that -require all symbols to be resolved at link time, such as OS X, the -module will "link" to the executable using a flag like -``-bundle_loader``. For other non-DLL platforms the link rule is simply -ignored since the dynamic loader will automatically bind symbols when -the module is loaded. +Handling of the executable on the link lines of the loadable modules +varies by platform: + +* On Windows-based systems (including Cygwin) an "import library" is + created along with the executable to list the exported symbols. + Loadable modules link to the import library to get the symbols. + +* On macOS, loadable modules link to the executable itself using the + ``-bundle_loader`` flag. + +* On AIX, a linker "import file" is created along with the executable + to list the exported symbols for import when linking other targets. + Loadable modules link to the import file to get the symbols. + +* On other platforms, loadable modules are simply linked without + referencing the executable since the dynamic loader will + automatically bind symbols when the module is loaded. This property is initialized by the value of the variable :variable:`CMAKE_ENABLE_EXPORTS` if it is set when a target is created. diff --git a/Help/prop_tgt/EXCLUDE_FROM_ALL.rst b/Help/prop_tgt/EXCLUDE_FROM_ALL.rst index caa5741f8..3aa296d3b 100644 --- a/Help/prop_tgt/EXCLUDE_FROM_ALL.rst +++ b/Help/prop_tgt/EXCLUDE_FROM_ALL.rst @@ -1,10 +1,21 @@ EXCLUDE_FROM_ALL ---------------- -Exclude the target from the all target. +Set this target property to a true (or false) value to exclude (or include) +the target from the "all" target of the containing directory and its +ancestors. If excluded, running e.g. ``make`` in the containing directory +or its ancestors will not build the target by default. -A property on a target that indicates if the target is excluded from -the default build target. If it is not, then with a Makefile for -example typing make will cause this target to be built. The same -concept applies to the default build of other generators. Installing -a target with EXCLUDE_FROM_ALL set to true has undefined behavior. +If this target property is not set then the target will be included in +the "all" target of the containing directory. Furthermore, it will be +included in the "all" target of its ancestor directories unless the +:prop_dir:`EXCLUDE_FROM_ALL` directory property is set. + +With ``EXCLUDE_FROM_ALL`` set to false or not set at all, the target +will be brought up to date as part of doing a ``make install`` or its +equivalent for the CMake generator being used. If a target has +``EXCLUDE_FROM_ALL`` set to true, then any attempt to install that +target has undefined behavior. Note that such a target can still safely +be listed in an :command:`install(TARGETS)` command as long as the install +components the target belongs to are not part of the set of components +that anything tries to install. diff --git a/Help/prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD.rst b/Help/prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD.rst index a14e48c19..664704bfa 100644 --- a/Help/prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD.rst +++ b/Help/prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD.rst @@ -1,8 +1,8 @@ EXCLUDE_FROM_DEFAULT_BUILD -------------------------- -Exclude target from "Build Solution". +Exclude target from ``Build Solution``. This property is only used by Visual Studio generators. -When set to TRUE, the target will not be built when you press "Build -Solution". +When set to ``TRUE``, the target will not be built when you press +``Build Solution``. diff --git a/Help/prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD_CONFIG.rst b/Help/prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD_CONFIG.rst index 655a9dee0..ad1021aa4 100644 --- a/Help/prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD_CONFIG.rst +++ b/Help/prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD_CONFIG.rst @@ -1,9 +1,10 @@ EXCLUDE_FROM_DEFAULT_BUILD_<CONFIG> ----------------------------------- -Per-configuration version of target exclusion from "Build Solution". +Per-configuration version of target exclusion from ``Build Solution``. This is the configuration-specific version of -EXCLUDE_FROM_DEFAULT_BUILD. If the generic EXCLUDE_FROM_DEFAULT_BUILD -is also set on a target, EXCLUDE_FROM_DEFAULT_BUILD_<CONFIG> takes +:prop_tgt:`EXCLUDE_FROM_DEFAULT_BUILD`. If the generic +:prop_tgt:`EXCLUDE_FROM_DEFAULT_BUILD` is also set on a target, +``EXCLUDE_FROM_DEFAULT_BUILD_<CONFIG>`` takes precedence in configurations for which it has a value. diff --git a/Help/prop_tgt/EXPORT_NAME.rst b/Help/prop_tgt/EXPORT_NAME.rst index 1b4247cc5..0e021d0db 100644 --- a/Help/prop_tgt/EXPORT_NAME.rst +++ b/Help/prop_tgt/EXPORT_NAME.rst @@ -3,6 +3,6 @@ EXPORT_NAME Exported name for target files. -This sets the name for the IMPORTED target generated when it this -target is is exported. If not set, the logical target name is used by -default. +This sets the name for the ``IMPORTED`` target generated by the +:command:`install(EXPORT)` and :command:`export` commands. +If not set, the logical target name is used by default. diff --git a/Help/prop_tgt/EXPORT_PROPERTIES.rst b/Help/prop_tgt/EXPORT_PROPERTIES.rst new file mode 100644 index 000000000..bcf47a624 --- /dev/null +++ b/Help/prop_tgt/EXPORT_PROPERTIES.rst @@ -0,0 +1,14 @@ +EXPORT_PROPERTIES +----------------- + +List additional properties to export for a target. + +This property contains a list of property names that should be exported by +the :command:`install(EXPORT)` and :command:`export` commands. By default +only a limited number of properties are exported. This property can be used +to additionally export other properties as well. + +Properties starting with ``INTERFACE_`` or ``IMPORTED_`` are not allowed as +they are reserved for internal CMake use. + +Properties containing generator expressions are also not allowed. diff --git a/Help/prop_tgt/EchoString.rst b/Help/prop_tgt/EchoString.rst index 32ae2aa8f..352d06258 100644 --- a/Help/prop_tgt/EchoString.rst +++ b/Help/prop_tgt/EchoString.rst @@ -3,5 +3,5 @@ EchoString A message to be displayed when the target is built. -A message to display on some generators (such as makefiles) when the -target is built. +A message to display on some generators (such as :ref:`Makefile Generators`) +when the target is built. diff --git a/Help/prop_tgt/FOLDER.rst b/Help/prop_tgt/FOLDER.rst index bfe4e8e16..f6be9e673 100644 --- a/Help/prop_tgt/FOLDER.rst +++ b/Help/prop_tgt/FOLDER.rst @@ -3,8 +3,11 @@ FOLDER Set the folder name. Use to organize targets in an IDE. -Targets with no FOLDER property will appear as top level entities in -IDEs like Visual Studio. Targets with the same FOLDER property value +Targets with no ``FOLDER`` property will appear as top level entities in +IDEs like Visual Studio. Targets with the same ``FOLDER`` property value will appear next to each other in a folder of that name. To nest -folders, use FOLDER values such as 'GUI/Dialogs' with '/' characters +folders, use ``FOLDER`` values such as 'GUI/Dialogs' with '/' characters separating folder levels. + +This property is initialized by the value of the variable +:variable:`CMAKE_FOLDER` if it is set when a target is created. diff --git a/Help/prop_tgt/FRAMEWORK.rst b/Help/prop_tgt/FRAMEWORK.rst index 495d30e95..3dff1be3c 100644 --- a/Help/prop_tgt/FRAMEWORK.rst +++ b/Help/prop_tgt/FRAMEWORK.rst @@ -1,17 +1,19 @@ FRAMEWORK --------- -Build ``SHARED`` or ``STATIC`` library as Framework Bundle on the OS X and iOS. +Build ``SHARED`` or ``STATIC`` library as Framework Bundle on the macOS and iOS. If such a library target has this property set to ``TRUE`` it will be -built as a framework when built on the OS X and iOS. It will have the +built as a framework when built on the macOS and iOS. It will have the directory structure required for a framework and will be suitable to -be used with the ``-framework`` option +be used with the ``-framework`` option. This property is initialized by the +value of the :variable:`CMAKE_FRAMEWORK` variable if it is set when a target is +created. To customize ``Info.plist`` file in the framework, use :prop_tgt:`MACOSX_FRAMEWORK_INFO_PLIST` target property. -For OS X see also the :prop_tgt:`FRAMEWORK_VERSION` target property. +For macOS see also the :prop_tgt:`FRAMEWORK_VERSION` target property. Example of creation ``dynamicFramework``: diff --git a/Help/prop_tgt/FRAMEWORK_VERSION.rst b/Help/prop_tgt/FRAMEWORK_VERSION.rst index 6aa30268a..c2ae7b98f 100644 --- a/Help/prop_tgt/FRAMEWORK_VERSION.rst +++ b/Help/prop_tgt/FRAMEWORK_VERSION.rst @@ -4,5 +4,5 @@ FRAMEWORK_VERSION Version of a framework created using the :prop_tgt:`FRAMEWORK` target property (e.g. ``A``). -This property only affects OS X, as iOS doesn't have versioned +This property only affects macOS, as iOS doesn't have versioned directory structure. diff --git a/Help/prop_tgt/Fortran_FORMAT.rst b/Help/prop_tgt/Fortran_FORMAT.rst index 0a11d91ca..8704e5f42 100644 --- a/Help/prop_tgt/Fortran_FORMAT.rst +++ b/Help/prop_tgt/Fortran_FORMAT.rst @@ -1,11 +1,11 @@ Fortran_FORMAT -------------- -Set to FIXED or FREE to indicate the Fortran source layout. +Set to ``FIXED`` or ``FREE`` to indicate the Fortran source layout. This property tells CMake whether the Fortran source files in a target use fixed-format or free-format. CMake will pass the corresponding -format flag to the compiler. Use the source-specific Fortran_FORMAT +format flag to the compiler. Use the source-specific ``Fortran_FORMAT`` property to change the format of a specific source file. If the -variable CMAKE_Fortran_FORMAT is set when a target is created its +variable :variable:`CMAKE_Fortran_FORMAT` is set when a target is created its value is used to initialize this property. diff --git a/Help/prop_tgt/Fortran_MODULE_DIRECTORY.rst b/Help/prop_tgt/Fortran_MODULE_DIRECTORY.rst index 9c8643764..e061863b3 100644 --- a/Help/prop_tgt/Fortran_MODULE_DIRECTORY.rst +++ b/Help/prop_tgt/Fortran_MODULE_DIRECTORY.rst @@ -8,10 +8,10 @@ the compiler supports a module output directory this specifies the directory in which the modules will be placed. When this property is not set the modules will be placed in the build directory corresponding to the target's source directory. If the variable -CMAKE_Fortran_MODULE_DIRECTORY is set when a target is created its +:variable:`CMAKE_Fortran_MODULE_DIRECTORY` is set when a target is created its value is used to initialize this property. Note that some compilers will automatically search the module output directory for modules USEd during compilation but others will not. If your sources USE modules their location must be specified by -INCLUDE_DIRECTORIES regardless of this property. +:prop_tgt:`INCLUDE_DIRECTORIES` regardless of this property. diff --git a/Help/prop_tgt/GENERATOR_FILE_NAME.rst b/Help/prop_tgt/GENERATOR_FILE_NAME.rst index 032b22acf..a48610550 100644 --- a/Help/prop_tgt/GENERATOR_FILE_NAME.rst +++ b/Help/prop_tgt/GENERATOR_FILE_NAME.rst @@ -6,4 +6,4 @@ Generator's file for this target. An internal property used by some generators to record the name of the project or dsp file associated with this target. Note that at configure time, this property is only set for targets created by -include_external_msproject(). +:command:`include_external_msproject`. diff --git a/Help/prop_tgt/GHS_INTEGRITY_APP.rst b/Help/prop_tgt/GHS_INTEGRITY_APP.rst new file mode 100644 index 000000000..b6697817a --- /dev/null +++ b/Help/prop_tgt/GHS_INTEGRITY_APP.rst @@ -0,0 +1,10 @@ +GHS_INTEGRITY_APP +----------------- + +``ON`` / ``OFF`` boolean to determine if an executable target should +be treated as an `Integrity Application`. + +If no value is set and if a ``.int`` file is added as a source file to the +executable target it will be treated as an `Integrity Application`. + +Supported on :generator:`Green Hills MULTI`. diff --git a/Help/prop_tgt/GHS_NO_SOURCE_GROUP_FILE.rst b/Help/prop_tgt/GHS_NO_SOURCE_GROUP_FILE.rst new file mode 100644 index 000000000..11ce0b223 --- /dev/null +++ b/Help/prop_tgt/GHS_NO_SOURCE_GROUP_FILE.rst @@ -0,0 +1,13 @@ +GHS_NO_SOURCE_GROUP_FILE +------------------------ + +``ON`` / ``OFF`` boolean to control if the project file for a target should +be one single file or multiple files. + +The default behavior or when the property is ``OFF`` is to generate a project +file for the target and then a sub-project file for each source group. + +When this property is ``ON`` or if :variable:`CMAKE_GHS_NO_SOURCE_GROUP_FILE` +is ``ON`` then only a single project file is generated for the target. + +Supported on :generator:`Green Hills MULTI`. diff --git a/Help/prop_tgt/GNUtoMS.rst b/Help/prop_tgt/GNUtoMS.rst index cf34da9c3..a09ebbfae 100644 --- a/Help/prop_tgt/GNUtoMS.rst +++ b/Help/prop_tgt/GNUtoMS.rst @@ -1,17 +1,17 @@ GNUtoMS ------- -Convert GNU import library (.dll.a) to MS format (.lib). +Convert GNU import library (``.dll.a``) to MS format (``.lib``). When linking a shared library or executable that exports symbols using GNU tools on Windows (MinGW/MSYS) with Visual Studio installed convert -the import library (.dll.a) from GNU to MS format (.lib). Both import -libraries will be installed by install(TARGETS) and exported by -install(EXPORT) and export() to be linked by applications with either -GNU- or MS-compatible tools. +the import library (``.dll.a``) from GNU to MS format (``.lib``). Both import +libraries will be installed by :command:`install(TARGETS)` and exported by +:command:`install(EXPORT)` and :command:`export` to be linked +by applications with either GNU- or MS-compatible tools. -If the variable CMAKE_GNUtoMS is set when a target is created its +If the variable ``CMAKE_GNUtoMS`` is set when a target is created its value is used to initialize this property. The variable must be set -prior to the first command that enables a language such as project() -or enable_language(). CMake provides the variable as an option to the +prior to the first command that enables a language such as :command:`project` +or :command:`enable_language`. CMake provides the variable as an option to the user automatically when configuring on Windows with GNU tools. diff --git a/Help/prop_tgt/HAS_CXX.rst b/Help/prop_tgt/HAS_CXX.rst index 7790932ae..15199b15b 100644 --- a/Help/prop_tgt/HAS_CXX.rst +++ b/Help/prop_tgt/HAS_CXX.rst @@ -3,5 +3,5 @@ HAS_CXX Link the target using the C++ linker tool (obsolete). -This is equivalent to setting the LINKER_LANGUAGE property to CXX. -See that property's documentation for details. +This is equivalent to setting the :prop_tgt:`LINKER_LANGUAGE` +property to ``CXX``. diff --git a/Help/prop_tgt/IMPORTED.rst b/Help/prop_tgt/IMPORTED.rst index 605c1ce6c..22d28aaf7 100644 --- a/Help/prop_tgt/IMPORTED.rst +++ b/Help/prop_tgt/IMPORTED.rst @@ -1,8 +1,8 @@ IMPORTED -------- -Read-only indication of whether a target is IMPORTED. +Read-only indication of whether a target is ``IMPORTED``. The boolean value of this property is ``True`` for targets created with -the IMPORTED option to :command:`add_executable` or :command:`add_library`. +the ``IMPORTED`` option to :command:`add_executable` or :command:`add_library`. It is ``False`` for targets built within the project. diff --git a/Help/prop_tgt/IMPORTED_COMMON_LANGUAGE_RUNTIME.rst b/Help/prop_tgt/IMPORTED_COMMON_LANGUAGE_RUNTIME.rst new file mode 100644 index 000000000..99e3bc45e --- /dev/null +++ b/Help/prop_tgt/IMPORTED_COMMON_LANGUAGE_RUNTIME.rst @@ -0,0 +1,8 @@ +IMPORTED_COMMON_LANGUAGE_RUNTIME +-------------------------------- + +Property to define if the target uses ``C++/CLI``. + +Ignored for non-imported targets. + +See also the :prop_tgt:`COMMON_LANGUAGE_RUNTIME` target property. diff --git a/Help/prop_tgt/IMPORTED_GLOBAL.rst b/Help/prop_tgt/IMPORTED_GLOBAL.rst new file mode 100644 index 000000000..1feca049d --- /dev/null +++ b/Help/prop_tgt/IMPORTED_GLOBAL.rst @@ -0,0 +1,22 @@ +IMPORTED_GLOBAL +--------------- + +Indication of whether an :ref:`IMPORTED target <Imported Targets>` is +globally visible. + +The boolean value of this property is True for targets created with the +``IMPORTED`` ``GLOBAL`` options to :command:`add_executable()` or +:command:`add_library()`. It is always False for targets built within the +project. + +For targets created with the ``IMPORTED`` option to +:command:`add_executable()` or :command:`add_library()` but without the +additional option ``GLOBAL`` this is False, too. However, setting this +property for such a locally ``IMPORTED`` target to True promotes that +target to global scope. This promotion can only be done in the same +directory where that ``IMPORTED`` target was created in the first place. + +Once an imported target has been made global, it cannot be changed back to +non-global. Therefore, if a project sets this property, it may only +provide a value of True. CMake will issue an error if the project tries to +set the property to a non-True value, even if the value was already False. diff --git a/Help/prop_tgt/IMPORTED_IMPLIB.rst b/Help/prop_tgt/IMPORTED_IMPLIB.rst index acf4b321f..c8b6fde95 100644 --- a/Help/prop_tgt/IMPORTED_IMPLIB.rst +++ b/Help/prop_tgt/IMPORTED_IMPLIB.rst @@ -1,7 +1,9 @@ IMPORTED_IMPLIB --------------- -Full path to the import library for an IMPORTED target. +Full path to the import library for an ``IMPORTED`` target. -Set this to the location of the ".lib" part of a windows DLL. Ignored -for non-imported targets. +Set this to the location of the ``.lib`` part of a Windows DLL, or on +AIX set it to an import file created for executables that export symbols +(see the :prop_tgt:`ENABLE_EXPORTS` target property). +Ignored for non-imported targets. diff --git a/Help/prop_tgt/IMPORTED_IMPLIB_CONFIG.rst b/Help/prop_tgt/IMPORTED_IMPLIB_CONFIG.rst index b4b3f0228..5debabc95 100644 --- a/Help/prop_tgt/IMPORTED_IMPLIB_CONFIG.rst +++ b/Help/prop_tgt/IMPORTED_IMPLIB_CONFIG.rst @@ -1,7 +1,7 @@ IMPORTED_IMPLIB_<CONFIG> ------------------------ -<CONFIG>-specific version of IMPORTED_IMPLIB property. +<CONFIG>-specific version of :prop_tgt:`IMPORTED_IMPLIB` property. Configuration names correspond to those provided by the project from which the target is imported. diff --git a/Help/prop_tgt/IMPORTED_LINK_DEPENDENT_LIBRARIES.rst b/Help/prop_tgt/IMPORTED_LINK_DEPENDENT_LIBRARIES.rst index 2db2b0e58..f7e216581 100644 --- a/Help/prop_tgt/IMPORTED_LINK_DEPENDENT_LIBRARIES.rst +++ b/Help/prop_tgt/IMPORTED_LINK_DEPENDENT_LIBRARIES.rst @@ -8,7 +8,7 @@ their implementation. On some platforms the linker searches for the dependent libraries of shared libraries they are including in the link. Set this property to the list of dependent shared libraries of an imported library. The list should be disjoint from the list of -interface libraries in the INTERFACE_LINK_LIBRARIES property. On +interface libraries in the :prop_tgt:`INTERFACE_LINK_LIBRARIES` property. On platforms requiring dependent shared libraries to be found at link time CMake uses this list to add appropriate files or paths to the link command line. Ignored for non-imported targets. diff --git a/Help/prop_tgt/IMPORTED_LINK_DEPENDENT_LIBRARIES_CONFIG.rst b/Help/prop_tgt/IMPORTED_LINK_DEPENDENT_LIBRARIES_CONFIG.rst index ee243c75d..5b9c51308 100644 --- a/Help/prop_tgt/IMPORTED_LINK_DEPENDENT_LIBRARIES_CONFIG.rst +++ b/Help/prop_tgt/IMPORTED_LINK_DEPENDENT_LIBRARIES_CONFIG.rst @@ -1,7 +1,7 @@ IMPORTED_LINK_DEPENDENT_LIBRARIES_<CONFIG> ------------------------------------------ -<CONFIG>-specific version of IMPORTED_LINK_DEPENDENT_LIBRARIES. +<CONFIG>-specific version of :prop_tgt:`IMPORTED_LINK_DEPENDENT_LIBRARIES`. Configuration names correspond to those provided by the project from which the target is imported. If set, this property completely diff --git a/Help/prop_tgt/IMPORTED_LINK_INTERFACE_LANGUAGES.rst b/Help/prop_tgt/IMPORTED_LINK_INTERFACE_LANGUAGES.rst index 5ca9c8b6f..4ed4281f3 100644 --- a/Help/prop_tgt/IMPORTED_LINK_INTERFACE_LANGUAGES.rst +++ b/Help/prop_tgt/IMPORTED_LINK_INTERFACE_LANGUAGES.rst @@ -1,14 +1,14 @@ IMPORTED_LINK_INTERFACE_LANGUAGES --------------------------------- -Languages compiled into an IMPORTED static library. +Languages compiled into an ``IMPORTED`` static library. Set this to the list of languages of source files compiled to produce -a STATIC IMPORTED library (such as "C" or "CXX"). CMake accounts for +a ``STATIC IMPORTED`` library (such as ``C`` or ``CXX``). CMake accounts for these languages when computing how to link a target to the imported library. For example, when a C executable links to an imported C++ static library CMake chooses the C++ linker to satisfy language runtime dependencies of the static library. -This property is ignored for targets that are not STATIC libraries. +This property is ignored for targets that are not ``STATIC`` libraries. This property is ignored for non-imported targets. diff --git a/Help/prop_tgt/IMPORTED_LINK_INTERFACE_LANGUAGES_CONFIG.rst b/Help/prop_tgt/IMPORTED_LINK_INTERFACE_LANGUAGES_CONFIG.rst index d4a10fbdd..40fcf7fcf 100644 --- a/Help/prop_tgt/IMPORTED_LINK_INTERFACE_LANGUAGES_CONFIG.rst +++ b/Help/prop_tgt/IMPORTED_LINK_INTERFACE_LANGUAGES_CONFIG.rst @@ -1,7 +1,7 @@ IMPORTED_LINK_INTERFACE_LANGUAGES_<CONFIG> ------------------------------------------ -<CONFIG>-specific version of IMPORTED_LINK_INTERFACE_LANGUAGES. +<CONFIG>-specific version of :prop_tgt:`IMPORTED_LINK_INTERFACE_LANGUAGES`. Configuration names correspond to those provided by the project from which the target is imported. If set, this property completely diff --git a/Help/prop_tgt/IMPORTED_LINK_INTERFACE_LIBRARIES.rst b/Help/prop_tgt/IMPORTED_LINK_INTERFACE_LIBRARIES.rst index 61134a401..527cf2ebe 100644 --- a/Help/prop_tgt/IMPORTED_LINK_INTERFACE_LIBRARIES.rst +++ b/Help/prop_tgt/IMPORTED_LINK_INTERFACE_LIBRARIES.rst @@ -1,16 +1,16 @@ IMPORTED_LINK_INTERFACE_LIBRARIES --------------------------------- -Transitive link interface of an IMPORTED target. +Transitive link interface of an ``IMPORTED`` target. Set this to the list of libraries whose interface is included when an -IMPORTED library target is linked to another target. The libraries +``IMPORTED`` library target is linked to another target. The libraries will be included on the link line for the target. Unlike the -LINK_INTERFACE_LIBRARIES property, this property applies to all -imported target types, including STATIC libraries. This property is +:prop_tgt:`LINK_INTERFACE_LIBRARIES` property, this property applies to all +imported target types, including ``STATIC`` libraries. This property is ignored for non-imported targets. This property is ignored if the target also has a non-empty -INTERFACE_LINK_LIBRARIES property. +:prop_tgt:`INTERFACE_LINK_LIBRARIES` property. -This property is deprecated. Use INTERFACE_LINK_LIBRARIES instead. +This property is deprecated. Use :prop_tgt:`INTERFACE_LINK_LIBRARIES` instead. diff --git a/Help/prop_tgt/IMPORTED_LINK_INTERFACE_LIBRARIES_CONFIG.rst b/Help/prop_tgt/IMPORTED_LINK_INTERFACE_LIBRARIES_CONFIG.rst index 13b93ba98..050fb1dff 100644 --- a/Help/prop_tgt/IMPORTED_LINK_INTERFACE_LIBRARIES_CONFIG.rst +++ b/Help/prop_tgt/IMPORTED_LINK_INTERFACE_LIBRARIES_CONFIG.rst @@ -1,13 +1,13 @@ IMPORTED_LINK_INTERFACE_LIBRARIES_<CONFIG> ------------------------------------------ -<CONFIG>-specific version of IMPORTED_LINK_INTERFACE_LIBRARIES. +<CONFIG>-specific version of :prop_tgt:`IMPORTED_LINK_INTERFACE_LIBRARIES`. Configuration names correspond to those provided by the project from which the target is imported. If set, this property completely overrides the generic property for the named configuration. This property is ignored if the target also has a non-empty -INTERFACE_LINK_LIBRARIES property. +:prop_tgt:`INTERFACE_LINK_LIBRARIES` property. -This property is deprecated. Use INTERFACE_LINK_LIBRARIES instead. +This property is deprecated. Use :prop_tgt:`INTERFACE_LINK_LIBRARIES` instead. diff --git a/Help/prop_tgt/IMPORTED_LINK_INTERFACE_MULTIPLICITY.rst b/Help/prop_tgt/IMPORTED_LINK_INTERFACE_MULTIPLICITY.rst index 3a86b9985..7a92d96b6 100644 --- a/Help/prop_tgt/IMPORTED_LINK_INTERFACE_MULTIPLICITY.rst +++ b/Help/prop_tgt/IMPORTED_LINK_INTERFACE_MULTIPLICITY.rst @@ -1,6 +1,6 @@ IMPORTED_LINK_INTERFACE_MULTIPLICITY ------------------------------------ -Repetition count for cycles of IMPORTED static libraries. +Repetition count for cycles of ``IMPORTED`` static libraries. -This is LINK_INTERFACE_MULTIPLICITY for IMPORTED targets. +This is :prop_tgt:`LINK_INTERFACE_MULTIPLICITY` for ``IMPORTED`` targets. diff --git a/Help/prop_tgt/IMPORTED_LINK_INTERFACE_MULTIPLICITY_CONFIG.rst b/Help/prop_tgt/IMPORTED_LINK_INTERFACE_MULTIPLICITY_CONFIG.rst index 33b9b8419..758237bf1 100644 --- a/Help/prop_tgt/IMPORTED_LINK_INTERFACE_MULTIPLICITY_CONFIG.rst +++ b/Help/prop_tgt/IMPORTED_LINK_INTERFACE_MULTIPLICITY_CONFIG.rst @@ -1,7 +1,7 @@ IMPORTED_LINK_INTERFACE_MULTIPLICITY_<CONFIG> --------------------------------------------- -<CONFIG>-specific version of IMPORTED_LINK_INTERFACE_MULTIPLICITY. +<CONFIG>-specific version of :prop_tgt:`IMPORTED_LINK_INTERFACE_MULTIPLICITY`. If set, this property completely overrides the generic property for the named configuration. diff --git a/Help/prop_tgt/IMPORTED_LOCATION.rst b/Help/prop_tgt/IMPORTED_LOCATION.rst index 8cfef7343..f0a1646b1 100644 --- a/Help/prop_tgt/IMPORTED_LOCATION.rst +++ b/Help/prop_tgt/IMPORTED_LOCATION.rst @@ -1,21 +1,31 @@ IMPORTED_LOCATION ----------------- -Full path to the main file on disk for an IMPORTED target. +Full path to the main file on disk for an ``IMPORTED`` target. -Set this to the location of an IMPORTED target file on disk. For +Set this to the location of an ``IMPORTED`` target file on disk. For executables this is the location of the executable file. For bundles -on OS X this is the location of the executable file inside -Contents/MacOS under the application bundle folder. For static +on macOS this is the location of the executable file inside +``Contents/MacOS`` under the application bundle folder. For ``STATIC`` libraries and modules this is the location of the library or module. -For shared libraries on non-DLL platforms this is the location of the -shared library. For frameworks on OS X this is the location of the +For ``SHARED`` libraries on non-DLL platforms this is the location of the +shared library. For frameworks on macOS this is the location of the library file symlink just inside the framework folder. For DLLs this -is the location of the ".dll" part of the library. For UNKNOWN +is the location of the ``.dll`` part of the library. For ``UNKNOWN`` libraries this is the location of the file to be linked. Ignored for non-imported targets. -Projects may skip IMPORTED_LOCATION if the configuration-specific -property IMPORTED_LOCATION_<CONFIG> is set. To get the location of an -imported target read one of the LOCATION or LOCATION_<CONFIG> -properties. +The ``IMPORTED_LOCATION`` target property may be overridden for a +given configuration ``<CONFIG>`` by the configuration-specific +:prop_tgt:`IMPORTED_LOCATION_<CONFIG>` target property. Furthermore, +the :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` target property may be +used to map between a project's configurations and those of an imported +target. If none of these is set then the name of any other configuration +listed in the :prop_tgt:`IMPORTED_CONFIGURATIONS` target property may be +selected and its :prop_tgt:`IMPORTED_LOCATION_<CONFIG>` value used. + +To get the location of an imported target read one of the :prop_tgt:`LOCATION` +or ``LOCATION_<CONFIG>`` properties. + +For platforms with import libraries (e.g. Windows) see also +:prop_tgt:`IMPORTED_IMPLIB`. diff --git a/Help/prop_tgt/IMPORTED_LOCATION_CONFIG.rst b/Help/prop_tgt/IMPORTED_LOCATION_CONFIG.rst index f85bb19c9..c5f5f048c 100644 --- a/Help/prop_tgt/IMPORTED_LOCATION_CONFIG.rst +++ b/Help/prop_tgt/IMPORTED_LOCATION_CONFIG.rst @@ -1,7 +1,7 @@ IMPORTED_LOCATION_<CONFIG> -------------------------- -<CONFIG>-specific version of IMPORTED_LOCATION property. +<CONFIG>-specific version of :prop_tgt:`IMPORTED_LOCATION` property. Configuration names correspond to those provided by the project from which the target is imported. diff --git a/Help/prop_tgt/IMPORTED_NO_SONAME.rst b/Help/prop_tgt/IMPORTED_NO_SONAME.rst index 4a1bb447a..cbb764226 100644 --- a/Help/prop_tgt/IMPORTED_NO_SONAME.rst +++ b/Help/prop_tgt/IMPORTED_NO_SONAME.rst @@ -1,9 +1,9 @@ IMPORTED_NO_SONAME ------------------ -Specifies that an IMPORTED shared library target has no "soname". +Specifies that an ``IMPORTED`` shared library target has no ``soname``. Set this property to true for an imported shared library file that has -no "soname" field. CMake may adjust generated link commands for some +no ``soname`` field. CMake may adjust generated link commands for some platforms to prevent the linker from using the path to the library in -place of its missing soname. Ignored for non-imported targets. +place of its missing ``soname``. Ignored for non-imported targets. diff --git a/Help/prop_tgt/IMPORTED_NO_SONAME_CONFIG.rst b/Help/prop_tgt/IMPORTED_NO_SONAME_CONFIG.rst index 22d68220c..76fe471f4 100644 --- a/Help/prop_tgt/IMPORTED_NO_SONAME_CONFIG.rst +++ b/Help/prop_tgt/IMPORTED_NO_SONAME_CONFIG.rst @@ -1,7 +1,7 @@ IMPORTED_NO_SONAME_<CONFIG> --------------------------- -<CONFIG>-specific version of IMPORTED_NO_SONAME property. +<CONFIG>-specific version of :prop_tgt:`IMPORTED_NO_SONAME` property. Configuration names correspond to those provided by the project from which the target is imported. diff --git a/Help/prop_tgt/IMPORTED_OBJECTS.rst b/Help/prop_tgt/IMPORTED_OBJECTS.rst index 222e6cc02..50a329fb3 100644 --- a/Help/prop_tgt/IMPORTED_OBJECTS.rst +++ b/Help/prop_tgt/IMPORTED_OBJECTS.rst @@ -1,7 +1,7 @@ IMPORTED_OBJECTS ---------------- -:ref:`;-list <CMake Language Lists>` of absolute paths to the object +A :ref:`semicolon-separated list <CMake Language Lists>` of absolute paths to the object files on disk for an :ref:`imported <Imported targets>` :ref:`object library <object libraries>`. diff --git a/Help/prop_tgt/IMPORTED_SONAME.rst b/Help/prop_tgt/IMPORTED_SONAME.rst index d80907e3e..bf0c3cbc1 100644 --- a/Help/prop_tgt/IMPORTED_SONAME.rst +++ b/Help/prop_tgt/IMPORTED_SONAME.rst @@ -1,8 +1,8 @@ IMPORTED_SONAME --------------- -The "soname" of an IMPORTED target of shared library type. +The ``soname`` of an ``IMPORTED`` target of shared library type. -Set this to the "soname" embedded in an imported shared library. This +Set this to the ``soname`` embedded in an imported shared library. This is meaningful only on platforms supporting the feature. Ignored for non-imported targets. diff --git a/Help/prop_tgt/IMPORTED_SONAME_CONFIG.rst b/Help/prop_tgt/IMPORTED_SONAME_CONFIG.rst index 6ec9af3f8..59a9d1a45 100644 --- a/Help/prop_tgt/IMPORTED_SONAME_CONFIG.rst +++ b/Help/prop_tgt/IMPORTED_SONAME_CONFIG.rst @@ -1,7 +1,7 @@ IMPORTED_SONAME_<CONFIG> ------------------------ -<CONFIG>-specific version of IMPORTED_SONAME property. +<CONFIG>-specific version of :prop_tgt:`IMPORTED_SONAME` property. Configuration names correspond to those provided by the project from which the target is imported. diff --git a/Help/prop_tgt/IMPORT_PREFIX.rst b/Help/prop_tgt/IMPORT_PREFIX.rst index deede9788..17e381be4 100644 --- a/Help/prop_tgt/IMPORT_PREFIX.rst +++ b/Help/prop_tgt/IMPORT_PREFIX.rst @@ -3,7 +3,7 @@ IMPORT_PREFIX What comes before the import library name. -Similar to the target property PREFIX, but used for import libraries -(typically corresponding to a DLL) instead of regular libraries. A -target property that can be set to override the prefix (such as "lib") +Similar to the target property :prop_tgt:`PREFIX`, but used for import libraries +(typically corresponding to a ``DLL``) instead of regular libraries. A +target property that can be set to override the prefix (such as ``lib``) on an import library name. diff --git a/Help/prop_tgt/IMPORT_SUFFIX.rst b/Help/prop_tgt/IMPORT_SUFFIX.rst index bd0125037..9307115b4 100644 --- a/Help/prop_tgt/IMPORT_SUFFIX.rst +++ b/Help/prop_tgt/IMPORT_SUFFIX.rst @@ -3,7 +3,7 @@ IMPORT_SUFFIX What comes after the import library name. -Similar to the target property SUFFIX, but used for import libraries -(typically corresponding to a DLL) instead of regular libraries. A -target property that can be set to override the suffix (such as -".lib") on an import library name. +Similar to the target property :prop_tgt:`SUFFIX`, but used +for import libraries (typically corresponding to a ``DLL``) instead of +regular libraries. A target property that can be set to override +the suffix (such as ``.lib``) on an import library name. diff --git a/Help/prop_tgt/INCLUDE_DIRECTORIES.rst b/Help/prop_tgt/INCLUDE_DIRECTORIES.rst index 8b40d9c34..b381d1dbd 100644 --- a/Help/prop_tgt/INCLUDE_DIRECTORIES.rst +++ b/Help/prop_tgt/INCLUDE_DIRECTORIES.rst @@ -18,7 +18,7 @@ paths for the compiler. Relative paths should not be added to this property directly. Use one of the commands above instead to handle relative paths. -Contents of ``INCLUDE_DIRECTORIES`` may use "generator expressions" with +Contents of ``INCLUDE_DIRECTORIES`` may use :manual:`cmake-generator-expressions(7)` 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. diff --git a/Help/prop_tgt/INSTALL_NAME_DIR.rst b/Help/prop_tgt/INSTALL_NAME_DIR.rst index a67ec1584..2216072ac 100644 --- a/Help/prop_tgt/INSTALL_NAME_DIR.rst +++ b/Help/prop_tgt/INSTALL_NAME_DIR.rst @@ -1,8 +1,12 @@ INSTALL_NAME_DIR ---------------- -Mac OSX directory name for installed targets. +macOS directory name for installed targets. -INSTALL_NAME_DIR is a string specifying the directory portion of the -"install_name" field of shared libraries on Mac OSX to use in the +``INSTALL_NAME_DIR`` is a string specifying the directory portion of the +"install_name" field of shared libraries on macOS to use in the installed targets. + +This property is initialized by the value of the variable +:variable:`CMAKE_INSTALL_NAME_DIR` if it is set when a target is +created. diff --git a/Help/prop_tgt/INSTALL_REMOVE_ENVIRONMENT_RPATH.rst b/Help/prop_tgt/INSTALL_REMOVE_ENVIRONMENT_RPATH.rst new file mode 100644 index 000000000..72dcaa0b1 --- /dev/null +++ b/Help/prop_tgt/INSTALL_REMOVE_ENVIRONMENT_RPATH.rst @@ -0,0 +1,16 @@ +INSTALL_REMOVE_ENVIRONMENT_RPATH +-------------------------------- + +Controls whether toolchain-defined rpaths should be removed during installation. + +When a target is being installed, CMake may need to rewrite its rpath +information. This occurs when the install rpath (as specified by the +:prop_tgt:`INSTALL_RPATH` target property) has different contents to the rpath +that the target was built with. Some toolchains insert their own rpath +contents into the binary as part of the build. By default, CMake will +preserve those extra inserted contents in the install rpath. For those +scenarios where such toolchain-inserted entries need to be discarded during +install, set the ``INSTALL_REMOVE_ENVIRONMENT_RPATH`` target property to true. + +This property is initialized by the value of +:variable:`CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH` when the target is created. diff --git a/Help/prop_tgt/INSTALL_RPATH.rst b/Help/prop_tgt/INSTALL_RPATH.rst index 6206b6889..93b448830 100644 --- a/Help/prop_tgt/INSTALL_RPATH.rst +++ b/Help/prop_tgt/INSTALL_RPATH.rst @@ -5,5 +5,8 @@ The rpath to use for installed targets. A semicolon-separated list specifying the rpath to use in installed targets (for platforms that support it). This property is initialized -by the value of the variable CMAKE_INSTALL_RPATH if it is set when a -target is created. +by the value of the variable :variable:`CMAKE_INSTALL_RPATH` if it is set when +a target is created. + +This property supports +:manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/prop_tgt/INSTALL_RPATH_USE_LINK_PATH.rst b/Help/prop_tgt/INSTALL_RPATH_USE_LINK_PATH.rst index f0006f85b..d8be9548a 100644 --- a/Help/prop_tgt/INSTALL_RPATH_USE_LINK_PATH.rst +++ b/Help/prop_tgt/INSTALL_RPATH_USE_LINK_PATH.rst @@ -3,8 +3,8 @@ INSTALL_RPATH_USE_LINK_PATH Add paths to linker search and installed rpath. -INSTALL_RPATH_USE_LINK_PATH is a boolean that if set to true will +``INSTALL_RPATH_USE_LINK_PATH`` is a boolean that if set to ``True`` will append directories in the linker search path and outside the project -to the INSTALL_RPATH. This property is initialized by the value of -the variable CMAKE_INSTALL_RPATH_USE_LINK_PATH if it is set when a +to the :prop_tgt:`INSTALL_RPATH`. This property is initialized by the value of +the variable ``CMAKE_INSTALL_RPATH_USE_LINK_PATH`` if it is set when a target is created. diff --git a/Help/prop_tgt/INTERFACE_LINK_DEPENDS.rst b/Help/prop_tgt/INTERFACE_LINK_DEPENDS.rst new file mode 100644 index 000000000..790554d9f --- /dev/null +++ b/Help/prop_tgt/INTERFACE_LINK_DEPENDS.rst @@ -0,0 +1,32 @@ +INTERFACE_LINK_DEPENDS +---------------------- + +Additional public interface files on which a target binary depends for linking. + +This property is supported only by :generator:`Ninja` and +:ref:`Makefile Generators`. +It is intended to specify dependencies on "linker scripts" for +custom Makefile link rules. + +When target dependencies are specified using :command:`target_link_libraries`, +CMake will read this property from all target dependencies to determine the +build properties of the consumer. + +Contents of ``INTERFACE_LINK_DEPENDS`` 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. + +Link dependency files usage requirements commonly differ between the build-tree +and the install-tree. The ``BUILD_INTERFACE`` and ``INSTALL_INTERFACE`` +generator expressions can be used to describe separate usage requirements +based on the usage location. Relative paths are allowed within the +``INSTALL_INTERFACE`` expression and are interpreted relative to the +installation prefix. For example: + +.. code-block:: cmake + + set_property(TARGET mylib PROPERTY INTERFACE_LINK_DEPENDS + $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/mylinkscript> + $<INSTALL_INTERFACE:mylinkscript> # <prefix>/mylinkscript + ) diff --git a/Help/prop_tgt/INTERFACE_LINK_DIRECTORIES.rst b/Help/prop_tgt/INTERFACE_LINK_DIRECTORIES.rst new file mode 100644 index 000000000..56a4ec0ec --- /dev/null +++ b/Help/prop_tgt/INTERFACE_LINK_DIRECTORIES.rst @@ -0,0 +1,9 @@ +INTERFACE_LINK_DIRECTORIES +-------------------------- + +.. |property_name| replace:: link directories +.. |command_name| replace:: :command:`target_link_directories` +.. |PROPERTY_INTERFACE_NAME| replace:: ``INTERFACE_LINK_DIRECTORIES`` +.. |PROPERTY_LINK| replace:: :prop_tgt:`LINK_DIRECTORIES` +.. |PROPERTY_GENEX| replace:: ``$<TARGET_PROPERTY:foo,INTERFACE_LINK_DIRECTORIES>`` +.. include:: INTERFACE_BUILD_PROPERTY.txt diff --git a/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst index 832d12bbc..bf7f72f4c 100644 --- a/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst +++ b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst @@ -17,6 +17,8 @@ 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_LIBRARIES_INDIRECTION.txt + Creating Relocatable Packages ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Help/prop_tgt/INTERFACE_LINK_OPTIONS.rst b/Help/prop_tgt/INTERFACE_LINK_OPTIONS.rst new file mode 100644 index 000000000..c293b986d --- /dev/null +++ b/Help/prop_tgt/INTERFACE_LINK_OPTIONS.rst @@ -0,0 +1,9 @@ +INTERFACE_LINK_OPTIONS +---------------------- + +.. |property_name| replace:: link options +.. |command_name| replace:: :command:`target_link_options` +.. |PROPERTY_INTERFACE_NAME| replace:: ``INTERFACE_LINK_OPTIONS`` +.. |PROPERTY_LINK| replace:: :prop_tgt:`LINK_OPTIONS` +.. |PROPERTY_GENEX| replace:: ``$<TARGET_PROPERTY:foo,INTERFACE_LINK_OPTIONS>`` +.. include:: INTERFACE_BUILD_PROPERTY.txt diff --git a/Help/prop_tgt/INTERFACE_POSITION_INDEPENDENT_CODE.rst b/Help/prop_tgt/INTERFACE_POSITION_INDEPENDENT_CODE.rst index ea700dfe9..4336d7182 100644 --- a/Help/prop_tgt/INTERFACE_POSITION_INDEPENDENT_CODE.rst +++ b/Help/prop_tgt/INTERFACE_POSITION_INDEPENDENT_CODE.rst @@ -14,3 +14,9 @@ undefined, then consumers will determine their :prop_tgt:`POSITION_INDEPENDENT_CODE` property by other means. Consumers must ensure that the targets that they link to have a consistent requirement for their ``INTERFACE_POSITION_INDEPENDENT_CODE`` property. + +Contents of ``INTERFACE_POSITION_INDEPENDENT_CODE`` 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. diff --git a/Help/prop_tgt/INTERFACE_PRECOMPILE_HEADERS.rst b/Help/prop_tgt/INTERFACE_PRECOMPILE_HEADERS.rst new file mode 100644 index 000000000..e2854074c --- /dev/null +++ b/Help/prop_tgt/INTERFACE_PRECOMPILE_HEADERS.rst @@ -0,0 +1,16 @@ +INTERFACE_PRECOMPILE_HEADERS +---------------------------- + +List of interface header files to precompile into consuming targets. + +Targets may populate this property to publish the header files +for consuming targets to precompile. The :command:`target_precompile_headers` +command populates this property with values given to the ``PUBLIC`` and +``INTERFACE`` keywords. Projects may also get and set the property directly. +See the discussion in :command:`target_precompile_headers` for guidance on +appropriate use of this property for installed or exported targets. + +Contents of ``INTERFACE_PRECOMPILE_HEADERS`` 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. diff --git a/Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION.rst b/Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION.rst index 3f68c3128..d3a5e9414 100644 --- a/Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION.rst +++ b/Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION.rst @@ -4,7 +4,9 @@ INTERPROCEDURAL_OPTIMIZATION Enable interprocedural optimization for a target. If set to true, enables interprocedural optimizations if they are -known to be supported by the compiler. +known :module:`to be supported <CheckIPOSupported>` by the compiler. Depending +on value of policy :policy:`CMP0069`, the error will be reported or ignored, +if interprocedural optimization is enabled but not supported. This property is initialized by the :variable:`CMAKE_INTERPROCEDURAL_OPTIMIZATION` variable if it is set when a diff --git a/Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst b/Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst index 782b0f0a6..79d46048b 100644 --- a/Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst +++ b/Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst @@ -3,7 +3,7 @@ INTERPROCEDURAL_OPTIMIZATION_<CONFIG> Per-configuration interprocedural optimization for a target. -This is a per-configuration version of INTERPROCEDURAL_OPTIMIZATION. +This is a per-configuration version of :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION`. If set, this property overrides the generic property for the named configuration. diff --git a/Help/prop_tgt/LANG_CLANG_TIDY.rst b/Help/prop_tgt/LANG_CLANG_TIDY.rst index 2887e235d..2bfef6673 100644 --- a/Help/prop_tgt/LANG_CLANG_TIDY.rst +++ b/Help/prop_tgt/LANG_CLANG_TIDY.rst @@ -3,7 +3,7 @@ This property is implemented only when ``<LANG>`` is ``C`` or ``CXX``. -Specify a :ref:`;-list <CMake Language Lists>` containing a command +Specify a :ref:`semicolon-separated list <CMake Language Lists>` containing a command line for the ``clang-tidy`` tool. The :ref:`Makefile Generators` and the :generator:`Ninja` generator will run this tool along with the compiler and report a warning if the tool reports any problems. diff --git a/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst b/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst index 0fe0b31e5..a6f2b24f6 100644 --- a/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst +++ b/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst @@ -1,9 +1,10 @@ <LANG>_COMPILER_LAUNCHER ------------------------ -This property is implemented only when ``<LANG>`` is ``C`` or ``CXX``. +This property is implemented only when ``<LANG>`` is ``C``, ``CXX``, +``Fortran``, ``OBJC``, ``OBJCXX``, or ``CUDA``. -Specify a :ref:`;-list <CMake Language Lists>` containing a command line +Specify a :ref:`semicolon-separated list <CMake Language Lists>` containing a command line for a compiler launching tool. The :ref:`Makefile Generators` and the :generator:`Ninja` generator will run this tool and pass the compiler and its arguments to the tool. Some example tools are distcc and ccache. diff --git a/Help/prop_tgt/LANG_CPPCHECK.rst b/Help/prop_tgt/LANG_CPPCHECK.rst new file mode 100644 index 000000000..60785d062 --- /dev/null +++ b/Help/prop_tgt/LANG_CPPCHECK.rst @@ -0,0 +1,15 @@ +<LANG>_CPPCHECK +--------------- + +This property is supported only when ``<LANG>`` is ``C`` or ``CXX``. + +Specify a :ref:`semicolon-separated list <CMake Language Lists>` containing a command line +for the ``cppcheck`` static analysis tool. The :ref:`Makefile Generators` +and the :generator:`Ninja` generator will run ``cppcheck`` along with the +compiler and report any problems. If the command-line specifies the +exit code options to ``cppcheck`` then the build will fail if the +tool returns non-zero. + +This property is initialized by the value of the +:variable:`CMAKE_<LANG>_CPPCHECK` variable if it is set when a target is +created. diff --git a/Help/prop_tgt/LANG_CPPLINT.rst b/Help/prop_tgt/LANG_CPPLINT.rst index 14f47d465..9944c88ba 100644 --- a/Help/prop_tgt/LANG_CPPLINT.rst +++ b/Help/prop_tgt/LANG_CPPLINT.rst @@ -3,7 +3,7 @@ This property is supported only when ``<LANG>`` is ``C`` or ``CXX``. -Specify a :ref:`;-list <CMake Language Lists>` containing a command line +Specify a :ref:`semicolon-separated list <CMake Language Lists>` containing a command line for the ``cpplint`` style checker. The :ref:`Makefile Generators` and the :generator:`Ninja` generator will run ``cpplint`` along with the compiler and report any problems. diff --git a/Help/prop_tgt/LANG_INCLUDE_WHAT_YOU_USE.rst b/Help/prop_tgt/LANG_INCLUDE_WHAT_YOU_USE.rst index 26f6d1671..35220e414 100644 --- a/Help/prop_tgt/LANG_INCLUDE_WHAT_YOU_USE.rst +++ b/Help/prop_tgt/LANG_INCLUDE_WHAT_YOU_USE.rst @@ -3,7 +3,7 @@ This property is implemented only when ``<LANG>`` is ``C`` or ``CXX``. -Specify a :ref:`;-list <CMake Language Lists>` containing a command +Specify a :ref:`semicolon-separated list <CMake Language Lists>` containing a command line for the ``include-what-you-use`` tool. The :ref:`Makefile Generators` and the :generator:`Ninja` generator will run this tool along with the compiler and report a warning if the tool reports any problems. diff --git a/Help/prop_tgt/LIBRARY_OUTPUT_DIRECTORY_CONFIG.rst b/Help/prop_tgt/LIBRARY_OUTPUT_DIRECTORY_CONFIG.rst index 28dd404df..5cefc38bb 100644 --- a/Help/prop_tgt/LIBRARY_OUTPUT_DIRECTORY_CONFIG.rst +++ b/Help/prop_tgt/LIBRARY_OUTPUT_DIRECTORY_CONFIG.rst @@ -6,7 +6,8 @@ Per-configuration output directory for This is a per-configuration version of the :prop_tgt:`LIBRARY_OUTPUT_DIRECTORY` target property, but -multi-configuration generators (VS, Xcode) do NOT append a +multi-configuration generators (:ref:`Visual Studio Generators`, +:generator:`Xcode`) do NOT append a per-configuration subdirectory to the specified directory. This property is initialized by the value of the :variable:`CMAKE_LIBRARY_OUTPUT_DIRECTORY_<CONFIG>` variable if diff --git a/Help/prop_tgt/LINKER_LANGUAGE.rst b/Help/prop_tgt/LINKER_LANGUAGE.rst index b1ca86710..b0a572b5c 100644 --- a/Help/prop_tgt/LINKER_LANGUAGE.rst +++ b/Help/prop_tgt/LINKER_LANGUAGE.rst @@ -8,7 +8,7 @@ whose compiler is used to link the target (such as "C" or "CXX"). A typical value for an executable is the language of the source file providing the program entry point (main). If not set, the language with the highest linker preference value is the default. See -documentation of CMAKE_<LANG>_LINKER_PREFERENCE variables. +documentation of :variable:`CMAKE_<LANG>_LINKER_PREFERENCE` variables. If this property is not set by the user, it will be calculated at generate-time by CMake. diff --git a/Help/prop_tgt/LINK_DEPENDS.rst b/Help/prop_tgt/LINK_DEPENDS.rst index 5576b85fa..e59d4c014 100644 --- a/Help/prop_tgt/LINK_DEPENDS.rst +++ b/Help/prop_tgt/LINK_DEPENDS.rst @@ -7,6 +7,12 @@ Specifies a semicolon-separated list of full-paths to files on which the link rule for this target depends. The target binary will be linked if any of the named files is newer than it. -This property is ignored by non-Makefile generators. It is intended -to specify dependencies on "linker scripts" for custom Makefile link +This property is supported only by :generator:`Ninja` and +:ref:`Makefile Generators`. It is +intended to specify dependencies on "linker scripts" for custom Makefile link rules. + +Contents of ``LINK_DEPENDS`` 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. diff --git a/Help/prop_tgt/LINK_DIRECTORIES.rst b/Help/prop_tgt/LINK_DIRECTORIES.rst new file mode 100644 index 000000000..c2905b37d --- /dev/null +++ b/Help/prop_tgt/LINK_DIRECTORIES.rst @@ -0,0 +1,18 @@ +LINK_DIRECTORIES +---------------- + +List of directories to use for the link step of shared library, module +and executable targets. + +This property holds a :ref:`semicolon-separated list <CMake Language Lists>` of directories +specified so far for its target. Use the :command:`target_link_directories` +command to append more search directories. + +This property is initialized by the :prop_dir:`LINK_DIRECTORIES` directory +property when a target is created, and is used by the generators to set +the 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. diff --git a/Help/prop_tgt/LINK_FLAGS.rst b/Help/prop_tgt/LINK_FLAGS.rst index 409d00a29..92cd3c0a5 100644 --- a/Help/prop_tgt/LINK_FLAGS.rst +++ b/Help/prop_tgt/LINK_FLAGS.rst @@ -1,8 +1,16 @@ LINK_FLAGS ---------- -Additional flags to use when linking this target. +Additional flags to use when linking this target if it is a shared library, +module library, or an executable. Static libraries need to use +:prop_tgt:`STATIC_LIBRARY_OPTIONS` or :prop_tgt:`STATIC_LIBRARY_FLAGS` +properties. -The LINK_FLAGS property can be used to add extra flags to the link -step of a target. LINK_FLAGS_<CONFIG> will add to the configuration -<CONFIG>, for example, DEBUG, RELEASE, MINSIZEREL, RELWITHDEBINFO. +The ``LINK_FLAGS`` property, managed as a string, can be used to add extra +flags to the link step of a target. :prop_tgt:`LINK_FLAGS_<CONFIG>` will add +to the configuration ``<CONFIG>``, for example, ``DEBUG``, ``RELEASE``, +``MINSIZEREL``, ``RELWITHDEBINFO``, ... + +.. note:: + + This property has been superseded by :prop_tgt:`LINK_OPTIONS` property. diff --git a/Help/prop_tgt/LINK_FLAGS_CONFIG.rst b/Help/prop_tgt/LINK_FLAGS_CONFIG.rst index ba7adc84f..68c312932 100644 --- a/Help/prop_tgt/LINK_FLAGS_CONFIG.rst +++ b/Help/prop_tgt/LINK_FLAGS_CONFIG.rst @@ -1,6 +1,11 @@ LINK_FLAGS_<CONFIG> ------------------- -Per-configuration linker flags for a target. +Per-configuration linker flags for a ``SHARED`` library, ``MODULE`` or +``EXECUTABLE`` target. -This is the configuration-specific version of LINK_FLAGS. +This is the configuration-specific version of :prop_tgt:`LINK_FLAGS`. + +.. note:: + + This property has been superseded by :prop_tgt:`LINK_OPTIONS` property. diff --git a/Help/prop_tgt/LINK_INTERFACE_MULTIPLICITY.rst b/Help/prop_tgt/LINK_INTERFACE_MULTIPLICITY.rst index 4e26388a9..b798af954 100644 --- a/Help/prop_tgt/LINK_INTERFACE_MULTIPLICITY.rst +++ b/Help/prop_tgt/LINK_INTERFACE_MULTIPLICITY.rst @@ -1,9 +1,9 @@ LINK_INTERFACE_MULTIPLICITY --------------------------- -Repetition count for STATIC libraries with cyclic dependencies. +Repetition count for ``STATIC`` libraries with cyclic dependencies. -When linking to a STATIC library target with cyclic dependencies the +When linking to a ``STATIC`` library target with cyclic dependencies the linker may need to scan more than once through the archives in the strongly connected component of the dependency graph. CMake by default constructs the link line so that the linker will scan through diff --git a/Help/prop_tgt/LINK_INTERFACE_MULTIPLICITY_CONFIG.rst b/Help/prop_tgt/LINK_INTERFACE_MULTIPLICITY_CONFIG.rst index 5ea4a45cf..7c9461fde 100644 --- a/Help/prop_tgt/LINK_INTERFACE_MULTIPLICITY_CONFIG.rst +++ b/Help/prop_tgt/LINK_INTERFACE_MULTIPLICITY_CONFIG.rst @@ -1,8 +1,8 @@ LINK_INTERFACE_MULTIPLICITY_<CONFIG> ------------------------------------ -Per-configuration repetition count for cycles of STATIC libraries. +Per-configuration repetition count for cycles of ``STATIC`` libraries. This is the configuration-specific version of -LINK_INTERFACE_MULTIPLICITY. If set, this property completely +:prop_tgt:`LINK_INTERFACE_MULTIPLICITY`. If set, this property completely overrides the generic property for the named configuration. diff --git a/Help/prop_tgt/LINK_LIBRARIES.rst b/Help/prop_tgt/LINK_LIBRARIES.rst index aa4b9f55f..d88e79881 100644 --- a/Help/prop_tgt/LINK_LIBRARIES.rst +++ b/Help/prop_tgt/LINK_LIBRARIES.rst @@ -15,3 +15,5 @@ Contents of ``LINK_LIBRARIES`` 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_LIBRARIES_INDIRECTION.txt diff --git a/Help/prop_tgt/LINK_LIBRARIES_INDIRECTION.txt b/Help/prop_tgt/LINK_LIBRARIES_INDIRECTION.txt new file mode 100644 index 000000000..1fdb6ad0e --- /dev/null +++ b/Help/prop_tgt/LINK_LIBRARIES_INDIRECTION.txt @@ -0,0 +1,10 @@ +.. note:: + A call to :command:`target_link_libraries(<target> ...)` may update this + property on ``<target>``. If ``<target>`` was not created in the same + directory as the call then :command:`target_link_libraries` will add a + suffix of the form ``::@<directory-id>`` to each entry, where the + ``::@`` is a separator and the ``<directory-id>`` is unspecified. + This tells the generators that the named libraries must be looked up in + the scope of the caller rather than in the scope in which the + ``<target>`` was created. Valid directory ids are stripped on export + by the :command:`install(EXPORT)` and :command:`export` commands. diff --git a/Help/prop_tgt/LINK_OPTIONS.rst b/Help/prop_tgt/LINK_OPTIONS.rst new file mode 100644 index 000000000..2a05ea75a --- /dev/null +++ b/Help/prop_tgt/LINK_OPTIONS.rst @@ -0,0 +1,24 @@ +LINK_OPTIONS +------------ + +List of options to use for the link step of shared library, module +and executable targets. Targets that are static libraries need to use +the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property. + + +This property holds a :ref:`semicolon-separated list <CMake Language Lists>` of options +specified so far for its target. Use the :command:`target_link_options` +command to append more options. + +This property is initialized by the :prop_dir:`LINK_OPTIONS` directory +property when a target is created, and is used by the generators to set +the options for the compiler. + +Contents of ``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. + +.. note:: + + This property must be used in preference to :prop_tgt:`LINK_FLAGS` property. diff --git a/Help/prop_tgt/LINK_SEARCH_END_STATIC.rst b/Help/prop_tgt/LINK_SEARCH_END_STATIC.rst index cf9c87147..fecbb1480 100644 --- a/Help/prop_tgt/LINK_SEARCH_END_STATIC.rst +++ b/Help/prop_tgt/LINK_SEARCH_END_STATIC.rst @@ -3,16 +3,17 @@ LINK_SEARCH_END_STATIC End a link line such that static system libraries are used. -Some linkers support switches such as -Bstatic and -Bdynamic to -determine whether to use static or shared libraries for -lXXX options. +Some linkers support switches such as ``-Bstatic`` and ``-Bdynamic`` to +determine whether to use static or shared libraries for ``-lXXX`` options. CMake uses these options to set the link type for libraries whose full paths are not known or (in some cases) are in implicit link directories for the platform. By default CMake adds an option at the end of the library list (if necessary) to set the linker search type back to its starting type. This property switches the final linker -search type to -Bstatic regardless of how it started. +search type to ``-Bstatic`` regardless of how it started. This property is initialized by the value of the variable -CMAKE_LINK_SEARCH_END_STATIC if it is set when a target is created. +:variable:`CMAKE_LINK_SEARCH_END_STATIC` if it is set +when a target is created. -See also LINK_SEARCH_START_STATIC. +See also :prop_tgt:`LINK_SEARCH_START_STATIC`. diff --git a/Help/prop_tgt/LINK_SEARCH_START_STATIC.rst b/Help/prop_tgt/LINK_SEARCH_START_STATIC.rst index 2e0f9bd33..83cf231c5 100644 --- a/Help/prop_tgt/LINK_SEARCH_START_STATIC.rst +++ b/Help/prop_tgt/LINK_SEARCH_START_STATIC.rst @@ -3,17 +3,18 @@ LINK_SEARCH_START_STATIC Assume the linker looks for static libraries by default. -Some linkers support switches such as -Bstatic and -Bdynamic to -determine whether to use static or shared libraries for -lXXX options. +Some linkers support switches such as ``-Bstatic`` and ``-Bdynamic`` to +determine whether to use static or shared libraries for ``-lXXX`` options. CMake uses these options to set the link type for libraries whose full paths are not known or (in some cases) are in implicit link directories for the platform. By default the linker search type is -assumed to be -Bdynamic at the beginning of the library list. This -property switches the assumption to -Bstatic. It is intended for use -when linking an executable statically (e.g. with the GNU -static +assumed to be ``-Bdynamic`` at the beginning of the library list. This +property switches the assumption to ``-Bstatic``. It is intended for use +when linking an executable statically (e.g. with the GNU ``-static`` option). This property is initialized by the value of the variable -CMAKE_LINK_SEARCH_START_STATIC if it is set when a target is created. + :variable:`CMAKE_LINK_SEARCH_START_STATIC` if it is set + when a target is created. -See also LINK_SEARCH_END_STATIC. +See also :prop_tgt:`LINK_SEARCH_END_STATIC`. diff --git a/Help/prop_tgt/LOCATION.rst b/Help/prop_tgt/LOCATION.rst index 16d5696e5..d058064d6 100644 --- a/Help/prop_tgt/LOCATION.rst +++ b/Help/prop_tgt/LOCATION.rst @@ -4,24 +4,25 @@ LOCATION Read-only location of a target on disk. For an imported target, this read-only property returns the value of -the LOCATION_<CONFIG> property for an unspecified configuration -<CONFIG> provided by the target. +the ``LOCATION_<CONFIG>`` property for an unspecified configuration +``<CONFIG>`` provided by the target. For a non-imported target, this property is provided for compatibility with CMake 2.4 and below. It was meant to get the location of an -executable target's output file for use in add_custom_command. The +executable target's output file for use in :command:`add_custom_command`. The path may contain a build-system-specific portion that is replaced at build time with the configuration getting built (such as -"$(ConfigurationName)" in VS). In CMake 2.6 and above -add_custom_command automatically recognizes a target name in its -COMMAND and DEPENDS options and computes the target location. In -CMake 2.8.4 and above add_custom_command recognizes generator -expressions to refer to target locations anywhere in the command. +``$(ConfigurationName)`` in VS). In CMake 2.6 and above +:command:`add_custom_command` automatically recognizes a target name in its +``COMMAND`` and ``DEPENDS`` options and computes the target location. In +CMake 2.8.4 and above :command:`add_custom_command` recognizes +:manual:`generator expressions <cmake-generator-expressions(7)>` +to refer to target locations anywhere in the command. Therefore this property is not needed for creating custom commands. Do not set properties that affect the location of a target after reading this property. These include properties whose names match -"(RUNTIME|LIBRARY|ARCHIVE)_OUTPUT_(NAME|DIRECTORY)(_<CONFIG>)?", +``(RUNTIME|LIBRARY|ARCHIVE)_OUTPUT_(NAME|DIRECTORY)(_<CONFIG>)?``, ``(IMPLIB_)?(PREFIX|SUFFIX)``, or "LINKER_LANGUAGE". Failure to follow this rule is not diagnosed and leaves the location of the target undefined. diff --git a/Help/prop_tgt/LOCATION_CONFIG.rst b/Help/prop_tgt/LOCATION_CONFIG.rst index ac6bdb786..67de8ed21 100644 --- a/Help/prop_tgt/LOCATION_CONFIG.rst +++ b/Help/prop_tgt/LOCATION_CONFIG.rst @@ -4,17 +4,17 @@ LOCATION_<CONFIG> Read-only property providing a target location on disk. A read-only property that indicates where a target's main file is -located on disk for the configuration <CONFIG>. The property is +located on disk for the configuration ``<CONFIG>``. The property is defined only for library and executable targets. An imported target may provide a set of configurations different from that of the importing project. By default CMake looks for an exact-match but otherwise uses an arbitrary available configuration. Use the -MAP_IMPORTED_CONFIG_<CONFIG> property to map imported configurations -explicitly. +:prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` property to map imported +configurations explicitly. Do not set properties that affect the location of a target after reading this property. These include properties whose names match -"(RUNTIME|LIBRARY|ARCHIVE)_OUTPUT_(NAME|DIRECTORY)(_<CONFIG>)?", -``(IMPLIB_)?(PREFIX|SUFFIX)``, or "LINKER_LANGUAGE". Failure to follow -this rule is not diagnosed and leaves the location of the target -undefined. +``(RUNTIME|LIBRARY|ARCHIVE)_OUTPUT_(NAME|DIRECTORY)(_<CONFIG>)?``, +``(IMPLIB_)?(PREFIX|SUFFIX)``, or :prop_tgt:`LINKER_LANGUAGE`. +Failure to follow this rule is not diagnosed and leaves +the location of the target undefined. diff --git a/Help/prop_tgt/MACOSX_BUNDLE.rst b/Help/prop_tgt/MACOSX_BUNDLE.rst index 7cd80462a..92bce53ee 100644 --- a/Help/prop_tgt/MACOSX_BUNDLE.rst +++ b/Help/prop_tgt/MACOSX_BUNDLE.rst @@ -1,12 +1,12 @@ MACOSX_BUNDLE ------------- -Build an executable as an Application Bundle on OS X or iOS. +Build an executable as an Application Bundle on macOS or iOS. -When this property is set to ``TRUE`` the executable when built on OS X +When this property is set to ``TRUE`` the executable when built on macOS or iOS will be created as an application bundle. This makes it a GUI executable that can be launched from the Finder. See the -:prop_tgt:`MACOSX_FRAMEWORK_INFO_PLIST` target property for information about +:prop_tgt:`MACOSX_BUNDLE_INFO_PLIST` target property for information about creation of the ``Info.plist`` file for the application bundle. This property is initialized by the value of the variable :variable:`CMAKE_MACOSX_BUNDLE` if it is set when a target is created. diff --git a/Help/prop_tgt/MACOSX_BUNDLE_INFO_PLIST.rst b/Help/prop_tgt/MACOSX_BUNDLE_INFO_PLIST.rst index 8515accc2..443a645e4 100644 --- a/Help/prop_tgt/MACOSX_BUNDLE_INFO_PLIST.rst +++ b/Help/prop_tgt/MACOSX_BUNDLE_INFO_PLIST.rst @@ -1,10 +1,10 @@ MACOSX_BUNDLE_INFO_PLIST ------------------------ -Specify a custom ``Info.plist`` template for a OS X and iOS Application Bundle. +Specify a custom ``Info.plist`` template for a macOS and iOS Application Bundle. An executable target with :prop_tgt:`MACOSX_BUNDLE` enabled will be built as an -application bundle on OS X. By default its ``Info.plist`` file is created +application bundle on macOS. By default its ``Info.plist`` file is created by configuring a template called ``MacOSXBundleInfo.plist.in`` located in the :variable:`CMAKE_MODULE_PATH`. This property specifies an alternative template file name which may be a full path. diff --git a/Help/prop_tgt/MACOSX_FRAMEWORK_INFO_PLIST.rst b/Help/prop_tgt/MACOSX_FRAMEWORK_INFO_PLIST.rst index 58f31d495..82fdcc0fb 100644 --- a/Help/prop_tgt/MACOSX_FRAMEWORK_INFO_PLIST.rst +++ b/Help/prop_tgt/MACOSX_FRAMEWORK_INFO_PLIST.rst @@ -1,10 +1,10 @@ MACOSX_FRAMEWORK_INFO_PLIST --------------------------- -Specify a custom ``Info.plist`` template for a OS X and iOS Framework. +Specify a custom ``Info.plist`` template for a macOS and iOS Framework. A library target with :prop_tgt:`FRAMEWORK` enabled will be built as a -framework on OS X. By default its ``Info.plist`` file is created by +framework on macOS. By default its ``Info.plist`` file is created by configuring a template called ``MacOSXFrameworkInfo.plist.in`` located in the :variable:`CMAKE_MODULE_PATH`. This property specifies an alternative template file name which may be a full path. diff --git a/Help/prop_tgt/MACOSX_RPATH.rst b/Help/prop_tgt/MACOSX_RPATH.rst index 1f9a036bf..acd5a7aa4 100644 --- a/Help/prop_tgt/MACOSX_RPATH.rst +++ b/Help/prop_tgt/MACOSX_RPATH.rst @@ -1,7 +1,7 @@ MACOSX_RPATH ------------ -Whether this target on OS X or iOS is located at runtime using rpaths. +Whether this target on macOS or iOS is located at runtime using rpaths. When this property is set to ``TRUE``, the directory portion of the ``install_name`` field of this shared library will be ``@rpath`` diff --git a/Help/prop_tgt/MSVC_RUNTIME_LIBRARY-VALUES.txt b/Help/prop_tgt/MSVC_RUNTIME_LIBRARY-VALUES.txt new file mode 100644 index 000000000..6c6134197 --- /dev/null +++ b/Help/prop_tgt/MSVC_RUNTIME_LIBRARY-VALUES.txt @@ -0,0 +1,20 @@ +``MultiThreaded`` + Compile with ``-MT`` or equivalent flag(s) to use a multi-threaded + statically-linked runtime library. +``MultiThreadedDLL`` + Compile with ``-MD`` or equivalent flag(s) to use a multi-threaded + dynamically-linked runtime library. +``MultiThreadedDebug`` + Compile with ``-MTd`` or equivalent flag(s) to use a multi-threaded + statically-linked runtime library. +``MultiThreadedDebugDLL`` + Compile with ``-MDd`` or equivalent flag(s) to use a multi-threaded + dynamically-linked runtime library. + +The value is ignored on non-MSVC compilers but an unsupported value will +be rejected as an error when using a compiler targeting the MSVC ABI. + +The value may also be the empty string (``""``) in which case no runtime +library selection flag will be added explicitly by CMake. Note that with +:ref:`Visual Studio Generators` the native build system may choose to +add its own default runtime library selection flag. diff --git a/Help/prop_tgt/MSVC_RUNTIME_LIBRARY.rst b/Help/prop_tgt/MSVC_RUNTIME_LIBRARY.rst new file mode 100644 index 000000000..73792def1 --- /dev/null +++ b/Help/prop_tgt/MSVC_RUNTIME_LIBRARY.rst @@ -0,0 +1,29 @@ +MSVC_RUNTIME_LIBRARY +-------------------- + +Select the MSVC runtime library for use by compilers targeting the MSVC ABI. + +The allowed values are: + +.. include:: MSVC_RUNTIME_LIBRARY-VALUES.txt + +Use :manual:`generator expressions <cmake-generator-expressions(7)>` to +support per-configuration specification. For example, the code: + +.. code-block:: cmake + + add_executable(foo foo.c) + set_property(TARGET foo PROPERTY + MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>") + +selects for the target ``foo`` a multi-threaded statically-linked runtime +library with or without debug information depending on the configuration. + +If this property is not set then CMake uses the default value +``MultiThreaded$<$<CONFIG:Debug>:Debug>DLL`` to select a MSVC runtime library. + +.. note:: + + This property has effect only when policy :policy:`CMP0091` is set to ``NEW`` + prior to the first :command:`project` or :command:`enable_language` command + that enables a language using a compiler targeting the MSVC ABI. diff --git a/Help/prop_tgt/NO_SONAME.rst b/Help/prop_tgt/NO_SONAME.rst index ee45ed849..d381a9c3b 100644 --- a/Help/prop_tgt/NO_SONAME.rst +++ b/Help/prop_tgt/NO_SONAME.rst @@ -1,10 +1,10 @@ NO_SONAME --------- -Whether to set "soname" when linking a shared library. +Whether to set ``soname`` when linking a shared library. -Enable this boolean property if a generated shared library -should not have "soname" set. Default is to set "soname" on all +Enable this boolean property if a generated ``SHARED`` library +should not have ``soname`` set. Default is to set ``soname`` on all shared libraries as long as the platform supports it. Generally, use this property only for leaf private libraries or plugins. If you use it on normal shared libraries which other targets diff --git a/Help/prop_tgt/NO_SYSTEM_FROM_IMPORTED.rst b/Help/prop_tgt/NO_SYSTEM_FROM_IMPORTED.rst index 070dd3018..880343de4 100644 --- a/Help/prop_tgt/NO_SYSTEM_FROM_IMPORTED.rst +++ b/Help/prop_tgt/NO_SYSTEM_FROM_IMPORTED.rst @@ -1,11 +1,15 @@ NO_SYSTEM_FROM_IMPORTED ----------------------- -Do not treat includes from IMPORTED target interfaces as SYSTEM. +Do not treat include directories from the interfaces of consumed +:ref:`imported targets` as ``SYSTEM``. -The contents of the INTERFACE_INCLUDE_DIRECTORIES of IMPORTED targets -are treated as SYSTEM includes by default. If this property is -enabled, the contents of the INTERFACE_INCLUDE_DIRECTORIES of IMPORTED -targets are not treated as system includes. This property is -initialized by the value of the variable CMAKE_NO_SYSTEM_FROM_IMPORTED -if it is set when a target is created. +The contents of the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property +of imported targets are treated as ``SYSTEM`` includes by default. If this +property is enabled on a target, compilation of sources in that target will +not treat the contents of the ``INTERFACE_INCLUDE_DIRECTORIES`` of consumed +imported targets as system includes. + +This property is initialized by the value of the +:variable:`CMAKE_NO_SYSTEM_FROM_IMPORTED` variable if it is set when a target +is created. diff --git a/Help/prop_tgt/OBJCXX_EXTENSIONS.rst b/Help/prop_tgt/OBJCXX_EXTENSIONS.rst new file mode 100644 index 000000000..9f9d804b6 --- /dev/null +++ b/Help/prop_tgt/OBJCXX_EXTENSIONS.rst @@ -0,0 +1,20 @@ +OBJCXX_EXTENSIONS +----------------- + +Boolean specifying whether compiler specific extensions are requested. + +This property specifies whether compiler specific extensions should be +used. For some compilers, this results in adding a flag such +as ``-std=gnu++11`` instead of ``-std=c++11`` to the compile line. This +property is ``ON`` by default. The basic ObjC++ standard level is +controlled by the :prop_tgt:`OBJCXX_STANDARD` target property. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. + +If the property is not set, and the project has set the :prop_tgt:`CXX_EXTENSIONS`, +the value of :prop_tgt:`CXX_EXTENSIONS` is set for :prop_tgt:`OBJCXX_EXTENSIONS`. + +This property is initialized by the value of +the :variable:`CMAKE_OBJCXX_EXTENSIONS` variable if it is set when a target +is created. diff --git a/Help/prop_tgt/OBJCXX_STANDARD.rst b/Help/prop_tgt/OBJCXX_STANDARD.rst new file mode 100644 index 000000000..3c925dcba --- /dev/null +++ b/Help/prop_tgt/OBJCXX_STANDARD.rst @@ -0,0 +1,35 @@ +OBJCXX_STANDARD +--------------- + +The ObjC++ standard whose features are requested to build this target. + +This property specifies the ObjC++ standard whose features are requested +to build this target. For some compilers, this results in adding a +flag such as ``-std=gnu++11`` to the compile line. + +Supported values are ``98``, ``11``, ``14``, ``17``, and ``20``. + +If the value requested does not result in a compile flag being added for +the compiler in use, a previous standard flag will be added instead. This +means that using: + +.. code-block:: cmake + + set_property(TARGET tgt PROPERTY OBJCXX_STANDARD 11) + +with a compiler which does not support ``-std=gnu++11`` or an equivalent +flag will not result in an error or warning, but will instead add the +``-std=gnu++98`` flag if supported. This "decay" behavior may be controlled +with the :prop_tgt:`OBJCXX_STANDARD_REQUIRED` target property. +Additionally, the :prop_tgt:`OBJCXX_EXTENSIONS` target property may be used to +control whether compiler-specific extensions are enabled on a per-target basis. + +If the property is not set, and the project has set the :prop_tgt:`CXX_STANDARD`, +the value of :prop_tgt:`CXX_STANDARD` is set for :prop_tgt:`OBJCXX_STANDARD`. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. + +This property is initialized by the value of +the :variable:`CMAKE_OBJCXX_STANDARD` variable if it is set when a target +is created. diff --git a/Help/prop_tgt/OBJCXX_STANDARD_REQUIRED.rst b/Help/prop_tgt/OBJCXX_STANDARD_REQUIRED.rst new file mode 100644 index 000000000..c330abfdd --- /dev/null +++ b/Help/prop_tgt/OBJCXX_STANDARD_REQUIRED.rst @@ -0,0 +1,20 @@ +OBJCXX_STANDARD_REQUIRED +------------------------ + +Boolean describing whether the value of :prop_tgt:`OBJCXX_STANDARD` is a requirement. + +If this property is set to ``ON``, then the value of the +:prop_tgt:`OBJCXX_STANDARD` target property is treated as a requirement. If this +property is ``OFF`` or unset, the :prop_tgt:`OBJCXX_STANDARD` target property is +treated as optional and may "decay" to a previous standard if the requested is +not available. + +If the property is not set, and the project has set the :prop_tgt:`CXX_STANDARD_REQUIRED`, +the value of :prop_tgt:`CXX_STANDARD_REQUIRED` is set for :prop_tgt:`OBJCXX_STANDARD_REQUIRED`. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. + +This property is initialized by the value of +the :variable:`CMAKE_OBJCXX_STANDARD_REQUIRED` variable if it is set when a +target is created. diff --git a/Help/prop_tgt/OBJC_EXTENSIONS.rst b/Help/prop_tgt/OBJC_EXTENSIONS.rst new file mode 100644 index 000000000..2de9e48fe --- /dev/null +++ b/Help/prop_tgt/OBJC_EXTENSIONS.rst @@ -0,0 +1,20 @@ +OBJC_EXTENSIONS +--------------- + +Boolean specifying whether compiler specific extensions are requested. + +This property specifies whether compiler specific extensions should be +used. For some compilers, this results in adding a flag such +as ``-std=gnu11`` instead of ``-std=c11`` to the compile line. This +property is ``ON`` by default. The basic OBJC standard level is +controlled by the :prop_tgt:`OBJC_STANDARD` target property. + +If the property is not set, and the project has set the :prop_tgt:`C_EXTENSIONS`, +the value of :prop_tgt:`C_EXTENSIONS` is set for :prop_tgt:`OBJC_EXTENSIONS`. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. + +This property is initialized by the value of +the :variable:`CMAKE_OBJC_EXTENSIONS` variable if it is set when a target +is created. diff --git a/Help/prop_tgt/OBJC_STANDARD.rst b/Help/prop_tgt/OBJC_STANDARD.rst new file mode 100644 index 000000000..d1e1b2425 --- /dev/null +++ b/Help/prop_tgt/OBJC_STANDARD.rst @@ -0,0 +1,35 @@ +OBJC_STANDARD +------------- + +The OBJC standard whose features are requested to build this target. + +This property specifies the OBJC standard whose features are requested +to build this target. For some compilers, this results in adding a +flag such as ``-std=gnu11`` to the compile line. + +Supported values are ``90``, ``99`` and ``11``. + +If the value requested does not result in a compile flag being added for +the compiler in use, a previous standard flag will be added instead. This +means that using: + +.. code-block:: cmake + + set_property(TARGET tgt PROPERTY OBJC_STANDARD 11) + +with a compiler which does not support ``-std=gnu11`` or an equivalent +flag will not result in an error or warning, but will instead add the +``-std=gnu99`` or ``-std=gnu90`` flag if supported. This "decay" behavior may +be controlled with the :prop_tgt:`OBJC_STANDARD_REQUIRED` target property. +Additionally, the :prop_tgt:`OBJC_EXTENSIONS` target property may be used to +control whether compiler-specific extensions are enabled on a per-target basis. + +If the property is not set, and the project has set the :prop_tgt:`C_STANDARD`, +the value of :prop_tgt:`C_STANDARD` is set for :prop_tgt:`OBJC_STANDARD`. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. + +This property is initialized by the value of +the :variable:`CMAKE_OBJC_STANDARD` variable if it is set when a target +is created. diff --git a/Help/prop_tgt/OBJC_STANDARD_REQUIRED.rst b/Help/prop_tgt/OBJC_STANDARD_REQUIRED.rst new file mode 100644 index 000000000..8cf377cd1 --- /dev/null +++ b/Help/prop_tgt/OBJC_STANDARD_REQUIRED.rst @@ -0,0 +1,20 @@ +OBJC_STANDARD_REQUIRED +---------------------- + +Boolean describing whether the value of :prop_tgt:`OBJC_STANDARD` is a requirement. + +If this property is set to ``ON``, then the value of the +:prop_tgt:`OBJC_STANDARD` target property is treated as a requirement. If this +property is ``OFF`` or unset, the :prop_tgt:`OBJC_STANDARD` target property is +treated as optional and may "decay" to a previous standard if the requested is +not available. + +If the property is not set, and the project has set the :prop_tgt:`C_STANDARD_REQUIRED`, +the value of :prop_tgt:`C_STANDARD_REQUIRED` is set for :prop_tgt:`OBJC_STANDARD_REQUIRED`. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. + +This property is initialized by the value of +the :variable:`CMAKE_OBJC_STANDARD_REQUIRED` variable if it is set when a +target is created. diff --git a/Help/prop_tgt/OSX_ARCHITECTURES.rst b/Help/prop_tgt/OSX_ARCHITECTURES.rst index cefe03f5b..996a4be72 100644 --- a/Help/prop_tgt/OSX_ARCHITECTURES.rst +++ b/Help/prop_tgt/OSX_ARCHITECTURES.rst @@ -1,10 +1,10 @@ OSX_ARCHITECTURES ----------------- -Target specific architectures for OS X. +Target specific architectures for macOS. The ``OSX_ARCHITECTURES`` property sets the target binary architecture for -targets on OS X (``-arch``). This property is initialized by the value of the +targets on macOS (``-arch``). This property is initialized by the value of the variable :variable:`CMAKE_OSX_ARCHITECTURES` if it is set when a target is created. Use :prop_tgt:`OSX_ARCHITECTURES_<CONFIG>` to set the binary architectures on a per-configuration basis, where ``<CONFIG>`` is an diff --git a/Help/prop_tgt/OSX_ARCHITECTURES_CONFIG.rst b/Help/prop_tgt/OSX_ARCHITECTURES_CONFIG.rst index fb78177fb..06da4fb09 100644 --- a/Help/prop_tgt/OSX_ARCHITECTURES_CONFIG.rst +++ b/Help/prop_tgt/OSX_ARCHITECTURES_CONFIG.rst @@ -1,7 +1,7 @@ OSX_ARCHITECTURES_<CONFIG> -------------------------- -Per-configuration OS X and iOS binary architectures for a target. +Per-configuration macOS and iOS binary architectures for a target. This property is the configuration-specific version of :prop_tgt:`OSX_ARCHITECTURES`. diff --git a/Help/prop_tgt/OUTPUT_NAME.rst b/Help/prop_tgt/OUTPUT_NAME.rst index f1bdb7c88..4b33b38e0 100644 --- a/Help/prop_tgt/OUTPUT_NAME.rst +++ b/Help/prop_tgt/OUTPUT_NAME.rst @@ -5,7 +5,8 @@ Output name for target files. This sets the base name for output files created for an executable or library target. If not set, the logical target name is used by -default. +default during generation. The value is not set by default during +configuration. Contents of ``OUTPUT_NAME`` and the variants listed below may use :manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/prop_tgt/PDB_OUTPUT_DIRECTORY.rst b/Help/prop_tgt/PDB_OUTPUT_DIRECTORY.rst index 730cf5776..2f667f364 100644 --- a/Help/prop_tgt/PDB_OUTPUT_DIRECTORY.rst +++ b/Help/prop_tgt/PDB_OUTPUT_DIRECTORY.rst @@ -5,8 +5,14 @@ Output directory for the MS debug symbols ``.pdb`` file generated by the linker for an executable or shared library target. This property specifies the directory into which the MS debug symbols -will be placed by the linker. This property is initialized by the -value of the :variable:`CMAKE_PDB_OUTPUT_DIRECTORY` variable if it is +will be placed by the linker. The property value may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. +Multi-configuration generators append a per-configuration +subdirectory to the specified directory unless a generator expression +is used. + +This property is initialized by the value of the +:variable:`CMAKE_PDB_OUTPUT_DIRECTORY` variable if it is set when a target is created. .. |COMPILE_PDB_XXX| replace:: :prop_tgt:`COMPILE_PDB_OUTPUT_DIRECTORY` diff --git a/Help/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG.rst b/Help/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG.rst index 6037fa0c7..6c550831f 100644 --- a/Help/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG.rst +++ b/Help/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG.rst @@ -5,11 +5,15 @@ Per-configuration output directory for the MS debug symbol ``.pdb`` file generated by the linker for an executable or shared library target. This is a per-configuration version of :prop_tgt:`PDB_OUTPUT_DIRECTORY`, -but multi-configuration generators (VS, Xcode) do NOT append a +but multi-configuration generators (:ref:`Visual Studio Generators`, +:generator:`Xcode`) do NOT append a per-configuration subdirectory to the specified directory. This property is initialized by the value of the :variable:`CMAKE_PDB_OUTPUT_DIRECTORY_<CONFIG>` variable if it is set when a target is created. +Contents of ``PDB_OUTPUT_DIRECTORY_<CONFIG>`` may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. + .. |COMPILE_PDB_XXX| replace:: :prop_tgt:`COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG>` .. include:: PDB_NOTE.txt diff --git a/Help/prop_tgt/POSITION_INDEPENDENT_CODE.rst b/Help/prop_tgt/POSITION_INDEPENDENT_CODE.rst index 54af8c6de..0aaf66bd0 100644 --- a/Help/prop_tgt/POSITION_INDEPENDENT_CODE.rst +++ b/Help/prop_tgt/POSITION_INDEPENDENT_CODE.rst @@ -9,3 +9,8 @@ property is ``True`` by default for ``SHARED`` and ``MODULE`` library targets and ``False`` otherwise. This property is initialized by the value of the :variable:`CMAKE_POSITION_INDEPENDENT_CODE` variable if it is set when a target is created. + +.. note:: + + For executable targets, the link step is controlled by the :policy:`CMP0083` + policy and the :module:`CheckPIESupported` module. diff --git a/Help/prop_tgt/POST_INSTALL_SCRIPT.rst b/Help/prop_tgt/POST_INSTALL_SCRIPT.rst index f1adb40b7..23935bcdf 100644 --- a/Help/prop_tgt/POST_INSTALL_SCRIPT.rst +++ b/Help/prop_tgt/POST_INSTALL_SCRIPT.rst @@ -3,7 +3,7 @@ POST_INSTALL_SCRIPT Deprecated install support. -The PRE_INSTALL_SCRIPT and POST_INSTALL_SCRIPT properties are the old -way to specify CMake scripts to run before and after installing a -target. They are used only when the old INSTALL_TARGETS command is -used to install the target. Use the INSTALL command instead. +The :prop_tgt:`PRE_INSTALL_SCRIPT` and ``POST_INSTALL_SCRIPT`` properties are +the old way to specify CMake scripts to run before and after installing a +target. They are used only when the old ``INSTALL_TARGETS`` command is +used to install the target. Use the :command:`install` command instead. diff --git a/Help/prop_tgt/PRECOMPILE_HEADERS.rst b/Help/prop_tgt/PRECOMPILE_HEADERS.rst new file mode 100644 index 000000000..9e70b654d --- /dev/null +++ b/Help/prop_tgt/PRECOMPILE_HEADERS.rst @@ -0,0 +1,12 @@ +PRECOMPILE_HEADERS +------------------ + +List of header files to precompile. + +This property holds a :ref:`semicolon-separated list <CMake Language Lists>` +of header files to precompile specified so far for its target. +Use the :command:`target_precompile_headers` command to append more header +files. + +This property supports +:manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/prop_tgt/PRECOMPILE_HEADERS_REUSE_FROM.rst b/Help/prop_tgt/PRECOMPILE_HEADERS_REUSE_FROM.rst new file mode 100644 index 000000000..9c3e7eaf3 --- /dev/null +++ b/Help/prop_tgt/PRECOMPILE_HEADERS_REUSE_FROM.rst @@ -0,0 +1,7 @@ +PRECOMPILE_HEADERS_REUSE_FROM +----------------------------- + +Target from which to reuse the precompiled headers build artifact. + +See the second signature of :command:`target_precompile_headers` command +for more detailed information. diff --git a/Help/prop_tgt/PREFIX.rst b/Help/prop_tgt/PREFIX.rst index a16510461..a40129268 100644 --- a/Help/prop_tgt/PREFIX.rst +++ b/Help/prop_tgt/PREFIX.rst @@ -4,4 +4,4 @@ PREFIX What comes before the library name. A target property that can be set to override the prefix (such as -"lib") on a library name. +``lib``) on a library name. diff --git a/Help/prop_tgt/PRE_INSTALL_SCRIPT.rst b/Help/prop_tgt/PRE_INSTALL_SCRIPT.rst index 113d7c56a..43432f4d8 100644 --- a/Help/prop_tgt/PRE_INSTALL_SCRIPT.rst +++ b/Help/prop_tgt/PRE_INSTALL_SCRIPT.rst @@ -3,7 +3,7 @@ PRE_INSTALL_SCRIPT Deprecated install support. -The PRE_INSTALL_SCRIPT and POST_INSTALL_SCRIPT properties are the old -way to specify CMake scripts to run before and after installing a -target. They are used only when the old INSTALL_TARGETS command is -used to install the target. Use the INSTALL command instead. +The ``PRE_INSTALL_SCRIPT`` and :prop_tgt:`POST_INSTALL_SCRIPT` properties are +the old way to specify CMake scripts to run before and after installing a +target. They are used only when the old ``INSTALL_TARGETS`` command is +used to install the target. Use the :command:`install` command instead. diff --git a/Help/prop_tgt/PRIVATE_HEADER.rst b/Help/prop_tgt/PRIVATE_HEADER.rst index c4412ed25..23e1f8e6f 100644 --- a/Help/prop_tgt/PRIVATE_HEADER.rst +++ b/Help/prop_tgt/PRIVATE_HEADER.rst @@ -4,8 +4,8 @@ PRIVATE_HEADER Specify private header files in a :prop_tgt:`FRAMEWORK` shared library target. Shared library targets marked with the :prop_tgt:`FRAMEWORK` property generate -frameworks on OS X, iOS and normal shared libraries on other platforms. +frameworks on macOS, iOS and normal shared libraries on other platforms. This property may be set to a list of header files to be placed in the PrivateHeaders directory inside the framework folder. On non-Apple platforms these headers may be installed using the ``PRIVATE_HEADER`` -option to the ``install(TARGETS)`` command. +option to the :command:`install(TARGETS)` command. diff --git a/Help/prop_tgt/PUBLIC_HEADER.rst b/Help/prop_tgt/PUBLIC_HEADER.rst index d4a636caf..915e39cd2 100644 --- a/Help/prop_tgt/PUBLIC_HEADER.rst +++ b/Help/prop_tgt/PUBLIC_HEADER.rst @@ -4,8 +4,8 @@ PUBLIC_HEADER Specify public header files in a :prop_tgt:`FRAMEWORK` shared library target. Shared library targets marked with the :prop_tgt:`FRAMEWORK` property generate -frameworks on OS X, iOS and normal shared libraries on other platforms. +frameworks on macOS, iOS and normal shared libraries on other platforms. This property may be set to a list of header files to be placed in the ``Headers`` directory inside the framework folder. On non-Apple platforms these headers may be installed using the ``PUBLIC_HEADER`` option to the -``install(TARGETS)`` command. +:command:`install(TARGETS)` command. diff --git a/Help/prop_tgt/RESOURCE.rst b/Help/prop_tgt/RESOURCE.rst index d837f7b33..e5a1cb677 100644 --- a/Help/prop_tgt/RESOURCE.rst +++ b/Help/prop_tgt/RESOURCE.rst @@ -4,12 +4,12 @@ RESOURCE Specify resource files in a :prop_tgt:`FRAMEWORK` or :prop_tgt:`BUNDLE`. Target marked with the :prop_tgt:`FRAMEWORK` or :prop_tgt:`BUNDLE` property -generate framework or application bundle (both OS X and iOS is supported) +generate framework or application bundle (both macOS and iOS is supported) or normal shared libraries on other platforms. This property may be set to a list of files to be placed in the corresponding -directory (eg. ``Resources`` directory for OS X) inside the bundle. +directory (eg. ``Resources`` directory for macOS) inside the bundle. On non-Apple platforms these files may be installed using the ``RESOURCE`` -option to the ``install(TARGETS)`` command. +option to the :command:`install(TARGETS)` command. Following example of Application Bundle: @@ -18,21 +18,18 @@ Following example of Application Bundle: add_executable(ExecutableTarget addDemo.c resourcefile.txt - appresourcedir/appres.txt - ) + appresourcedir/appres.txt) target_link_libraries(ExecutableTarget heymath mul) set(RESOURCE_FILES resourcefile.txt - appresourcedir/appres.txt - ) + appresourcedir/appres.txt) set_target_properties(ExecutableTarget PROPERTIES MACOSX_BUNDLE TRUE MACOSX_FRAMEWORK_IDENTIFIER org.cmake.ExecutableTarget - RESOURCE "${RESOURCE_FILES}" - ) + RESOURCE "${RESOURCE_FILES}") will produce flat structure for iOS systems:: @@ -42,7 +39,7 @@ will produce flat structure for iOS systems:: Info.plist resourcefile.txt -For OS X systems it will produce following directory structure:: +For macOS systems it will produce following directory structure:: ExecutableTarget.app/ Contents @@ -53,7 +50,7 @@ For OS X systems it will produce following directory structure:: appres.txt resourcefile.txt -For Linux, such cmake script produce following files:: +For Linux, such CMake script produce following files:: ExecutableTarget Resources diff --git a/Help/prop_tgt/RUNTIME_OUTPUT_DIRECTORY_CONFIG.rst b/Help/prop_tgt/RUNTIME_OUTPUT_DIRECTORY_CONFIG.rst index 94fb2776a..67277548e 100644 --- a/Help/prop_tgt/RUNTIME_OUTPUT_DIRECTORY_CONFIG.rst +++ b/Help/prop_tgt/RUNTIME_OUTPUT_DIRECTORY_CONFIG.rst @@ -6,7 +6,8 @@ Per-configuration output directory for This is a per-configuration version of the :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` target property, but -multi-configuration generators (VS, Xcode) do NOT append a +multi-configuration generators (:ref:`Visual Studio Generators`, +:generator:`Xcode`) do NOT append a per-configuration subdirectory to the specified directory. This property is initialized by the value of the :variable:`CMAKE_RUNTIME_OUTPUT_DIRECTORY_<CONFIG>` variable if diff --git a/Help/prop_tgt/SKIP_BUILD_RPATH.rst b/Help/prop_tgt/SKIP_BUILD_RPATH.rst index a91fa9ca3..7086b1bc4 100644 --- a/Help/prop_tgt/SKIP_BUILD_RPATH.rst +++ b/Help/prop_tgt/SKIP_BUILD_RPATH.rst @@ -3,7 +3,7 @@ SKIP_BUILD_RPATH Should rpaths be used for the build tree. -SKIP_BUILD_RPATH is a boolean specifying whether to skip automatic +``SKIP_BUILD_RPATH`` is a boolean specifying whether to skip automatic generation of an rpath allowing the target to run from the build tree. This property is initialized by the value of the variable -CMAKE_SKIP_BUILD_RPATH if it is set when a target is created. +:variable:`CMAKE_SKIP_BUILD_RPATH` if it is set when a target is created. diff --git a/Help/prop_tgt/SOVERSION.rst b/Help/prop_tgt/SOVERSION.rst index 82b6b976a..b07c17cfe 100644 --- a/Help/prop_tgt/SOVERSION.rst +++ b/Help/prop_tgt/SOVERSION.rst @@ -20,7 +20,7 @@ These numbers are used as the image version of the binary. Mach-O Versions ^^^^^^^^^^^^^^^ -For shared libraries and executables on Mach-O systems (e.g. OS X, iOS), +For shared libraries and executables on Mach-O systems (e.g. macOS, iOS), the ``SOVERSION`` property corresponds to *compatibility version* and :prop_tgt:`VERSION` to *current version*. See the :prop_tgt:`FRAMEWORK` target property for an example. Versions of Mach-O binaries may be checked with the diff --git a/Help/prop_tgt/STATIC_LIBRARY_FLAGS.rst b/Help/prop_tgt/STATIC_LIBRARY_FLAGS.rst index d3b2cd478..66e0e8b96 100644 --- a/Help/prop_tgt/STATIC_LIBRARY_FLAGS.rst +++ b/Help/prop_tgt/STATIC_LIBRARY_FLAGS.rst @@ -1,6 +1,17 @@ STATIC_LIBRARY_FLAGS -------------------- -Extra flags to use when linking static libraries. +Archiver (or MSVC librarian) flags for a static library target. +Targets that are shared libraries, modules, or executables need to use +the :prop_tgt:`LINK_OPTIONS` or :prop_tgt:`LINK_FLAGS` target properties. -Extra flags to use when linking a static library. +The ``STATIC_LIBRARY_FLAGS`` property, managed as a string, can be used to add +extra flags to the link step of a static library target. +:prop_tgt:`STATIC_LIBRARY_FLAGS_<CONFIG>` will add to the configuration +``<CONFIG>``, for example, ``DEBUG``, ``RELEASE``, ``MINSIZEREL``, +``RELWITHDEBINFO``, ... + +.. note:: + + This property has been superseded by :prop_tgt:`STATIC_LIBRARY_OPTIONS` + property. diff --git a/Help/prop_tgt/STATIC_LIBRARY_FLAGS_CONFIG.rst b/Help/prop_tgt/STATIC_LIBRARY_FLAGS_CONFIG.rst index cca353ddc..5b97941da 100644 --- a/Help/prop_tgt/STATIC_LIBRARY_FLAGS_CONFIG.rst +++ b/Help/prop_tgt/STATIC_LIBRARY_FLAGS_CONFIG.rst @@ -1,6 +1,12 @@ STATIC_LIBRARY_FLAGS_<CONFIG> ----------------------------- -Per-configuration flags for creating a static library. +Per-configuration archiver (or MSVC librarian) flags for a static library +target. -This is the configuration-specific version of STATIC_LIBRARY_FLAGS. +This is the configuration-specific version of :prop_tgt:`STATIC_LIBRARY_FLAGS`. + +.. note:: + + This property has been superseded by :prop_tgt:`STATIC_LIBRARY_OPTIONS` + property. diff --git a/Help/prop_tgt/STATIC_LIBRARY_OPTIONS.rst b/Help/prop_tgt/STATIC_LIBRARY_OPTIONS.rst new file mode 100644 index 000000000..d05fda4aa --- /dev/null +++ b/Help/prop_tgt/STATIC_LIBRARY_OPTIONS.rst @@ -0,0 +1,20 @@ +STATIC_LIBRARY_OPTIONS +---------------------- + +Archiver (or MSVC librarian) flags for a static library target. +Targets that are shared libraries, modules, or executables need to use +the :prop_tgt:`LINK_OPTIONS` target property. + +This property holds a :ref:`semicolon-separated list <CMake Language Lists>` of options +specified so far for its target. Use :command:`set_target_properties` or +:command:`set_property` commands to set its content. + +Contents of ``STATIC_LIBRARY_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. + +.. note:: + + This property must be used in preference to :prop_tgt:`STATIC_LIBRARY_FLAGS` + property. diff --git a/Help/prop_tgt/SUFFIX.rst b/Help/prop_tgt/SUFFIX.rst index 70844be5c..32ec42910 100644 --- a/Help/prop_tgt/SUFFIX.rst +++ b/Help/prop_tgt/SUFFIX.rst @@ -4,4 +4,4 @@ SUFFIX What comes after the target name. A target property that can be set to override the suffix (such as -".so" or ".exe") on the name of a library, module or executable. +``.so`` or ``.exe``) on the name of a library, module or executable. diff --git a/Help/prop_tgt/Swift_DEPENDENCIES_FILE.rst b/Help/prop_tgt/Swift_DEPENDENCIES_FILE.rst new file mode 100644 index 000000000..46c9a1d9b --- /dev/null +++ b/Help/prop_tgt/Swift_DEPENDENCIES_FILE.rst @@ -0,0 +1,5 @@ +Swift_DEPENDENCIES_FILE +----------------------- + +This property sets the path for the Swift dependency file (swiftdep) for the +target. If one is not specified, it will default to ``<TARGET>.swiftdeps``. diff --git a/Help/prop_tgt/Swift_LANGUAGE_VERSION.rst b/Help/prop_tgt/Swift_LANGUAGE_VERSION.rst new file mode 100644 index 000000000..7579447a4 --- /dev/null +++ b/Help/prop_tgt/Swift_LANGUAGE_VERSION.rst @@ -0,0 +1,6 @@ +Swift_LANGUAGE_VERSION +---------------------- + +This property sets the language version for the Swift sources in the target. If +one is not specified, it will default to ``<CMAKE_Swift_LANGUAGE_VERSION>`` if +specified, otherwise it is the latest version supported by the compiler. diff --git a/Help/prop_tgt/Swift_MODULE_DIRECTORY.rst b/Help/prop_tgt/Swift_MODULE_DIRECTORY.rst new file mode 100644 index 000000000..d40425166 --- /dev/null +++ b/Help/prop_tgt/Swift_MODULE_DIRECTORY.rst @@ -0,0 +1,10 @@ +Swift_MODULE_DIRECTORY +---------------------- + +Specify output directory for Swift modules provided by the target. + +If the target contains Swift source files, this specifies the directory in which +the modules will be placed. When this property is not set, the modules will be +placed in the build directory corresponding to the target's source directory. +If the variable :variable:`CMAKE_Swift_MODULE_DIRECTORY` is set when a target is +created its value is used to initialise this property. diff --git a/Help/prop_tgt/Swift_MODULE_NAME.rst b/Help/prop_tgt/Swift_MODULE_NAME.rst new file mode 100644 index 000000000..28660203e --- /dev/null +++ b/Help/prop_tgt/Swift_MODULE_NAME.rst @@ -0,0 +1,5 @@ +Swift_MODULE_NAME +----------------- + +This property specifies the name of the Swift module. It is defaulted to the +name of the target. diff --git a/Help/prop_tgt/TYPE.rst b/Help/prop_tgt/TYPE.rst index 5ac63cc37..3136d119d 100644 --- a/Help/prop_tgt/TYPE.rst +++ b/Help/prop_tgt/TYPE.rst @@ -4,6 +4,6 @@ TYPE The type of the target. This read-only property can be used to test the type of the given -target. It will be one of STATIC_LIBRARY, MODULE_LIBRARY, -SHARED_LIBRARY, INTERFACE_LIBRARY, EXECUTABLE or one of the internal -target types. +target. It will be one of ``STATIC_LIBRARY``, ``MODULE_LIBRARY``, +``SHARED_LIBRARY``, ``OBJECT_LIBRARY``, ``INTERFACE_LIBRARY``, ``EXECUTABLE`` +or one of the internal target types. diff --git a/Help/prop_tgt/UNITY_BUILD.rst b/Help/prop_tgt/UNITY_BUILD.rst new file mode 100644 index 000000000..479802e59 --- /dev/null +++ b/Help/prop_tgt/UNITY_BUILD.rst @@ -0,0 +1,60 @@ +UNITY_BUILD +----------- + +When this property is set to true, the target source files will be combined +into batches for faster compilation. This is done by creating a (set of) +unity sources which ``#include`` the original sources, then compiling these +unity sources instead of the originals. This is known as a *Unity* or *Jumbo* +build. The :prop_tgt:`UNITY_BUILD_BATCH_SIZE` property controls the upper +limit on how many sources can be combined per unity source file. + +Unity builds are not currently supported for all languages. CMake version +|release| supports combining ``C`` and ``CXX`` source files. For targets that +mix source files from more than one language, CMake will separate the languages +such that each generated unity source file only contains sources for a single +language. + +This property is initialized by the value of the :variable:`CMAKE_UNITY_BUILD` +variable when a target is created. + +.. note:: + + Projects should not directly set the ``UNITY_BUILD`` property or its + associated :variable:`CMAKE_UNITY_BUILD` variable to true. Depending + on the capabilities of the build machine and compiler used, it might or + might not be appropriate to enable unity builds. Therefore, this feature + should be under developer control, which would normally be through the + developer choosing whether or not to set the :variable:`CMAKE_UNITY_BUILD` + variable on the :manual:`cmake(1)` command line or some other equivalent + method. However, it IS recommended to set the ``UNITY_BUILD`` target + property to false if it is known that enabling unity builds for the + target can lead to problems. + +ODR (One definition rule) errors +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When multiple source files are included into one source file, as is done +for unity builds, it can potentially lead to ODR errors. CMake provides +a number of measures to help address such problems: + +* Any source file that has a non-empty :prop_sf:`COMPILE_OPTIONS`, + :prop_sf:`COMPILE_DEFINITIONS`, :prop_sf:`COMPILE_FLAGS`, or + :prop_sf:`INCLUDE_DIRECTORIES` source property will not be combined + into a unity source. + +* Projects can prevent an individual source file from being combined into + a unity source by setting its :prop_sf:`SKIP_UNITY_BUILD_INCLUSION` + source property to true. This can be a more effective way to prevent + problems with specific files than disabling unity builds for an entire + target. + +* The :prop_tgt:`UNITY_BUILD_CODE_BEFORE_INCLUDE` and + :prop_tgt:`UNITY_BUILD_CODE_AFTER_INCLUDE` target properties can be used + to inject code into the unity source files before and after every + ``#include`` statement. + +* The order of source files added to the target via commands like + :command:`add_library`, :command:`add_executable` or + :command:`target_sources` will be preserved in the generated unity source + files. This can be used to manually enforce a specific grouping based on + the :prop_tgt:`UNITY_BUILD_BATCH_SIZE` target property. diff --git a/Help/prop_tgt/UNITY_BUILD_BATCH_SIZE.rst b/Help/prop_tgt/UNITY_BUILD_BATCH_SIZE.rst new file mode 100644 index 000000000..44ffe2784 --- /dev/null +++ b/Help/prop_tgt/UNITY_BUILD_BATCH_SIZE.rst @@ -0,0 +1,23 @@ +UNITY_BUILD_BATCH_SIZE +---------------------- + +Specifies the maximum number of source files that can be combined into any one +unity source file when unity builds are enabled by the :prop_tgt:`UNITY_BUILD` +target property. The original source files will be distributed across as many +unity source files as necessary to honor this limit. + +The initial value for this property is taken from the +:variable:`CMAKE_UNITY_BUILD_BATCH_SIZE` variable when the target is created. +If that variable has not been set, the initial value will be 8. + +The batch size needs to be selected carefully. If set too high, the size of +the combined source files could result in the compiler using excessive memory +or hitting other similar limits. In extreme cases, this can even result in +build failure. On the other hand, if the batch size is too low, there will be +little gain in build performance. + +Although strongly discouraged, the batch size may be set to a value of 0 to +combine all the sources for the target into a single unity file, regardless of +how many sources are involved. This runs the risk of creating an excessively +large unity source file and negatively impacting the build performance, so +a value of 0 is not generally recommended. diff --git a/Help/prop_tgt/UNITY_BUILD_CODE_AFTER_INCLUDE.rst b/Help/prop_tgt/UNITY_BUILD_CODE_AFTER_INCLUDE.rst new file mode 100644 index 000000000..7231b6116 --- /dev/null +++ b/Help/prop_tgt/UNITY_BUILD_CODE_AFTER_INCLUDE.rst @@ -0,0 +1,19 @@ +UNITY_BUILD_CODE_AFTER_INCLUDE +------------------------------ + +Code snippet which is included verbatim by the :prop_tgt:`UNITY_BUILD` +feature just after every ``#include`` statement in the generated unity +source files. For example: + +.. code-block:: cmake + + set(after [[ + #if defined(NOMINMAX) + #undef NOMINMAX + #endif + ]]) + set_target_properties(myTarget PROPERTIES + UNITY_BUILD_CODE_AFTER_INCLUDE "${after}" + ) + +See also :prop_tgt:`UNITY_BUILD_CODE_BEFORE_INCLUDE`. diff --git a/Help/prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE.rst b/Help/prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE.rst new file mode 100644 index 000000000..7ed6fa10a --- /dev/null +++ b/Help/prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE.rst @@ -0,0 +1,19 @@ +UNITY_BUILD_CODE_BEFORE_INCLUDE +------------------------------- + +Code snippet which is included verbatim by the :prop_tgt:`UNITY_BUILD` +feature just before every ``#include`` statement in the generated unity +source files. For example: + +.. code-block:: cmake + + set(before [[ + #if !defined(NOMINMAX) + #define NOMINMAX + #endif + ]]) + set_target_properties(myTarget PROPERTIES + UNITY_BUILD_CODE_BEFORE_INCLUDE "${before}" + ) + +See also :prop_tgt:`UNITY_BUILD_CODE_AFTER_INCLUDE`. diff --git a/Help/prop_tgt/VERSION.rst b/Help/prop_tgt/VERSION.rst index 66e7bde71..ff3b3030f 100644 --- a/Help/prop_tgt/VERSION.rst +++ b/Help/prop_tgt/VERSION.rst @@ -22,7 +22,7 @@ These numbers are used as the image version of the binary. Mach-O Versions ^^^^^^^^^^^^^^^ -For shared libraries and executables on Mach-O systems (e.g. OS X, iOS), +For shared libraries and executables on Mach-O systems (e.g. macOS, iOS), the :prop_tgt:`SOVERSION` property correspond to *compatibility version* and ``VERSION`` to *current version*. See the :prop_tgt:`FRAMEWORK` target property for an example. Versions of Mach-O binaries may be checked with the diff --git a/Help/prop_tgt/VS_CONFIGURATION_TYPE.rst b/Help/prop_tgt/VS_CONFIGURATION_TYPE.rst index ff987ffb8..640bed596 100644 --- a/Help/prop_tgt/VS_CONFIGURATION_TYPE.rst +++ b/Help/prop_tgt/VS_CONFIGURATION_TYPE.rst @@ -4,6 +4,8 @@ VS_CONFIGURATION_TYPE Visual Studio project configuration type. Sets the ``ConfigurationType`` attribute for a generated Visual Studio project. +The property value may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. If this property is set, it overrides the default setting that is based on the target type (e.g. ``StaticLibrary``, ``Application``, ...). diff --git a/Help/prop_tgt/VS_DEBUGGER_COMMAND.rst b/Help/prop_tgt/VS_DEBUGGER_COMMAND.rst new file mode 100644 index 000000000..ba5fd0aeb --- /dev/null +++ b/Help/prop_tgt/VS_DEBUGGER_COMMAND.rst @@ -0,0 +1,11 @@ +VS_DEBUGGER_COMMAND +------------------- + +Sets the local debugger command for Visual Studio C++ targets. +The property value may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. +This is defined in ``<LocalDebuggerCommand>`` in the Visual Studio +project file. + +This property only works for Visual Studio 2010 and above; +it is ignored on other generators. diff --git a/Help/prop_tgt/VS_DEBUGGER_COMMAND_ARGUMENTS.rst b/Help/prop_tgt/VS_DEBUGGER_COMMAND_ARGUMENTS.rst new file mode 100644 index 000000000..06ef5d5fc --- /dev/null +++ b/Help/prop_tgt/VS_DEBUGGER_COMMAND_ARGUMENTS.rst @@ -0,0 +1,11 @@ +VS_DEBUGGER_COMMAND_ARGUMENTS +----------------------------- + +Sets the local debugger command line arguments for Visual Studio C++ targets. +The property value may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. +This is defined in ``<LocalDebuggerCommandArguments>`` in the Visual Studio +project file. + +This property only works for Visual Studio 2010 and above; +it is ignored on other generators. diff --git a/Help/prop_tgt/VS_DEBUGGER_ENVIRONMENT.rst b/Help/prop_tgt/VS_DEBUGGER_ENVIRONMENT.rst new file mode 100644 index 000000000..f55ac7bee --- /dev/null +++ b/Help/prop_tgt/VS_DEBUGGER_ENVIRONMENT.rst @@ -0,0 +1,11 @@ +VS_DEBUGGER_ENVIRONMENT +----------------------- + +Sets the local debugger environment for Visual Studio C++ targets. +The property value may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. +This is defined in ``<LocalDebuggerEnvironment>`` in the Visual Studio +project file. + +This property only works for Visual Studio 2010 and above; +it is ignored on other generators. diff --git a/Help/prop_tgt/VS_DEBUGGER_WORKING_DIRECTORY.rst b/Help/prop_tgt/VS_DEBUGGER_WORKING_DIRECTORY.rst index 0af85cbdc..008bbf6e6 100644 --- a/Help/prop_tgt/VS_DEBUGGER_WORKING_DIRECTORY.rst +++ b/Help/prop_tgt/VS_DEBUGGER_WORKING_DIRECTORY.rst @@ -2,5 +2,10 @@ VS_DEBUGGER_WORKING_DIRECTORY ----------------------------- Sets the local debugger working directory for Visual Studio C++ targets. +The property value may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. This is defined in ``<LocalDebuggerWorkingDirectory>`` in the Visual Studio project file. + +This property only works for Visual Studio 2010 and above; +it is ignored on other generators. diff --git a/Help/prop_tgt/VS_DOTNET_REFERENCEPROP_refname_TAG_tagname.rst b/Help/prop_tgt/VS_DOTNET_REFERENCEPROP_refname_TAG_tagname.rst new file mode 100644 index 000000000..ab311eaf6 --- /dev/null +++ b/Help/prop_tgt/VS_DOTNET_REFERENCEPROP_refname_TAG_tagname.rst @@ -0,0 +1,14 @@ +VS_DOTNET_REFERENCEPROP_<refname>_TAG_<tagname> +----------------------------------------------- + +Defines an XML property ``<tagname>`` for a .NET reference +``<refname>``. + +Reference properties can be set for .NET references which are +defined by the target properties :prop_tgt:`VS_DOTNET_REFERENCES`, +:prop_tgt:`VS_DOTNET_REFERENCE_<refname>` +and also for project references to other C# targets which are +established by :command:`target_link_libraries()`. + +This property is only applicable to C# targets and Visual Studio +generators 2010 and later. diff --git a/Help/prop_tgt/VS_DOTNET_TARGET_FRAMEWORK_VERSION.rst b/Help/prop_tgt/VS_DOTNET_TARGET_FRAMEWORK_VERSION.rst index 829d696d5..9f5a313d3 100644 --- a/Help/prop_tgt/VS_DOTNET_TARGET_FRAMEWORK_VERSION.rst +++ b/Help/prop_tgt/VS_DOTNET_TARGET_FRAMEWORK_VERSION.rst @@ -5,3 +5,6 @@ Specify the .NET target framework version. Used to specify the .NET target framework version for C++/CLI. For example, "v4.5". + +This property is deprecated and should not be used anymore. Use +:prop_tgt:`DOTNET_TARGET_FRAMEWORK_VERSION` instead. diff --git a/Help/prop_tgt/VS_DPI_AWARE.rst b/Help/prop_tgt/VS_DPI_AWARE.rst new file mode 100644 index 000000000..82640cc60 --- /dev/null +++ b/Help/prop_tgt/VS_DPI_AWARE.rst @@ -0,0 +1,14 @@ +VS_DPI_AWARE +------------ + +Set the Manifest Tool -> Input and Output -> DPI Awareness in the Visual Studio +target project properties. + +Valid values are ``PerMonitor``, ``ON``, or ``OFF``. + +For example: + +.. code-block:: cmake + + add_executable(myproject myproject.cpp) + set_property(TARGET myproject PROPERTY VS_DPI_AWARE "PerMonitor") diff --git a/Help/prop_tgt/VS_JUST_MY_CODE_DEBUGGING.rst b/Help/prop_tgt/VS_JUST_MY_CODE_DEBUGGING.rst new file mode 100644 index 000000000..42fb8ad86 --- /dev/null +++ b/Help/prop_tgt/VS_JUST_MY_CODE_DEBUGGING.rst @@ -0,0 +1,10 @@ +VS_JUST_MY_CODE_DEBUGGING +------------------------- + +Enable Just My Code with Visual Studio debugger. + +Supported on :ref:`Visual Studio Generators` for VS 2010 and higher, +:ref:`Makefile Generators` and the :generator:`Ninja` generators. + +This property is initialized by the :variable:`CMAKE_VS_JUST_MY_CODE_DEBUGGING` +variable if it is set when a target is created. diff --git a/Help/prop_tgt/VS_NO_SOLUTION_DEPLOY.rst b/Help/prop_tgt/VS_NO_SOLUTION_DEPLOY.rst new file mode 100644 index 000000000..ffcbde572 --- /dev/null +++ b/Help/prop_tgt/VS_NO_SOLUTION_DEPLOY.rst @@ -0,0 +1,46 @@ +VS_NO_SOLUTION_DEPLOY +--------------------- + +Specify that the target should not be marked for deployment to a Windows CE +or Windows Phone device in the generated Visual Studio solution. + +Be default, all EXE and shared library (DLL) targets are marked to deploy to +the target device in the generated Visual Studio solution. + +Generator expressions are supported. + +There are reasons one might want to exclude a target / generated project from +deployment: + +- The library or executable may not be necessary in the primary deploy/debug + scenario, and excluding from deployment saves time in the + develop/download/debug cycle. +- There may be insufficient space on the target device to accommodate all of + the build products. +- Visual Studio 2013 requires a target device IP address be entered for each + target marked for deployment. For large numbers of targets, this can be + tedious. + NOTE: Visual Studio *will* deploy all project dependencies of a project + tagged for deployment to the IP address configured for that project even + if those dependencies are not tagged for deployment. + + +Example 1 +^^^^^^^^^ + +This shows setting the variable for the target foo. + +.. code-block:: cmake + + add_library(foo SHARED foo.cpp) + set_property(TARGET foo PROPERTY VS_NO_SOLUTION_DEPLOY ON) + +Example 2 +^^^^^^^^^ + +This shows setting the variable for the Release configuration only. + +.. code-block:: cmake + + add_library(foo SHARED foo.cpp) + set_property(TARGET foo PROPERTY VS_NO_SOLUTION_DEPLOY "$<CONFIG:Release>") diff --git a/Help/prop_tgt/VS_PACKAGE_REFERENCES.rst b/Help/prop_tgt/VS_PACKAGE_REFERENCES.rst new file mode 100644 index 000000000..5a0465bcc --- /dev/null +++ b/Help/prop_tgt/VS_PACKAGE_REFERENCES.rst @@ -0,0 +1,13 @@ +VS_PACKAGE_REFERENCES +--------------------- + +Visual Studio package references for nuget. + +Adds one or more semicolon-delimited package references to a generated +Visual Studio project. The version of the package will be +underscore delimited. For example, ``boost_1.7.0;nunit_3.12.*``. + +.. code-block:: cmake + + set_property(TARGET ${TARGET_NAME} PROPERTY + VS_PACKAGE_REFERENCES "boost_1.7.0") diff --git a/Help/prop_tgt/VS_PROJECT_IMPORT.rst b/Help/prop_tgt/VS_PROJECT_IMPORT.rst new file mode 100644 index 000000000..569c8ea74 --- /dev/null +++ b/Help/prop_tgt/VS_PROJECT_IMPORT.rst @@ -0,0 +1,8 @@ +VS_PROJECT_IMPORT +----------------- + +Visual Studio managed project imports + +Adds to a generated Visual Studio project one or more semicolon-delimited paths +to .props files needed when building projects from some NuGet packages. +For example, ``my_packages_path/MyPackage.1.0.0/build/MyPackage.props``. diff --git a/Help/prop_tgt/VS_SDK_REFERENCES.rst b/Help/prop_tgt/VS_SDK_REFERENCES.rst index 769a0d1d5..99987f561 100644 --- a/Help/prop_tgt/VS_SDK_REFERENCES.rst +++ b/Help/prop_tgt/VS_SDK_REFERENCES.rst @@ -2,6 +2,6 @@ VS_SDK_REFERENCES ----------------- Visual Studio project SDK references. -Specify a :ref:`;-list <CMake Language Lists>` of SDK references +Specify a :ref:`semicolon-separated list <CMake Language Lists>` of SDK references to be added to a generated Visual Studio project, e.g. ``Microsoft.AdMediatorWindows81, Version=1.0``. diff --git a/Help/prop_tgt/WIN32_EXECUTABLE.rst b/Help/prop_tgt/WIN32_EXECUTABLE.rst index 336d5f7f3..060d16671 100644 --- a/Help/prop_tgt/WIN32_EXECUTABLE.rst +++ b/Help/prop_tgt/WIN32_EXECUTABLE.rst @@ -5,8 +5,9 @@ Build an executable with a WinMain entry point on windows. When this property is set to true the executable when linked on Windows will be created with a WinMain() entry point instead of just -main(). This makes it a GUI executable instead of a console -application. See the CMAKE_MFC_FLAG variable documentation to -configure use of MFC for WinMain executables. This property is -initialized by the value of the variable CMAKE_WIN32_EXECUTABLE if it -is set when a target is created. +main(). This makes it a GUI executable instead of a console application. +See the :variable:`CMAKE_MFC_FLAG` variable documentation to +configure use of the Microsoft Foundation Classes (MFC) for WinMain +executables. This property is initialized by the value of the +:variable:`CMAKE_WIN32_EXECUTABLE` variable if it is set when +a target is created. diff --git a/Help/prop_tgt/XCODE_ATTRIBUTE_an-attribute.rst b/Help/prop_tgt/XCODE_ATTRIBUTE_an-attribute.rst index 7e00ac430..71858c50e 100644 --- a/Help/prop_tgt/XCODE_ATTRIBUTE_an-attribute.rst +++ b/Help/prop_tgt/XCODE_ATTRIBUTE_an-attribute.rst @@ -3,8 +3,8 @@ XCODE_ATTRIBUTE_<an-attribute> Set Xcode target attributes directly. -Tell the Xcode generator to set '<an-attribute>' to a given value in -the generated Xcode project. Ignored on other generators. +Tell the :generator:`Xcode` generator to set '<an-attribute>' to a given +value in the generated Xcode project. Ignored on other generators. See the :variable:`CMAKE_XCODE_ATTRIBUTE_<an-attribute>` variable to set attributes on all targets in a directory tree. diff --git a/Help/prop_tgt/XCODE_GENERATE_SCHEME.rst b/Help/prop_tgt/XCODE_GENERATE_SCHEME.rst new file mode 100644 index 000000000..0e182cfc2 --- /dev/null +++ b/Help/prop_tgt/XCODE_GENERATE_SCHEME.rst @@ -0,0 +1,40 @@ +XCODE_GENERATE_SCHEME +--------------------- + +If enabled, the :generator:`Xcode` generator will generate schema files. These +are useful to invoke analyze, archive, build-for-testing and test +actions from the command line. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_GENERATE_SCHEME` if it is set when a target +is created. + +The following target properties overwrite the default of the +corresponding settings on the "Diagnostic" tab for each schema file. +Each of those is initialized by the respective ``CMAKE_`` variable +at target creation time. + +- :prop_tgt:`XCODE_SCHEME_ADDRESS_SANITIZER` +- :prop_tgt:`XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN` +- :prop_tgt:`XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER` +- :prop_tgt:`XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS` +- :prop_tgt:`XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE` +- :prop_tgt:`XCODE_SCHEME_GUARD_MALLOC` +- :prop_tgt:`XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP` +- :prop_tgt:`XCODE_SCHEME_MALLOC_GUARD_EDGES` +- :prop_tgt:`XCODE_SCHEME_MALLOC_SCRIBBLE` +- :prop_tgt:`XCODE_SCHEME_MALLOC_STACK` +- :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_ZOMBIE_OBJECTS` + +The following target properties will be applied on the +"Info", "Arguments", and "Options" tab: + +- :prop_tgt:`XCODE_SCHEME_ARGUMENTS` +- :prop_tgt:`XCODE_SCHEME_DEBUG_AS_ROOT` +- :prop_tgt:`XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING` +- :prop_tgt:`XCODE_SCHEME_ENVIRONMENT` +- :prop_tgt:`XCODE_SCHEME_EXECUTABLE` diff --git a/Help/prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER.rst b/Help/prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER.rst new file mode 100644 index 000000000..cc9bac2e6 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_ADDRESS_SANITIZER +------------------------------ + +Whether to enable ``Address Sanitizer`` in the Diagnostics +section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER` if it is set +when a target is created. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN.rst b/Help/prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN.rst new file mode 100644 index 000000000..37a043a1a --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN +----------------------------------------------- + +Whether to enable ``Detect use of stack after return`` +in the Diagnostics section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN` +if it is set when a target is created. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/prop_tgt/XCODE_SCHEME_ARGUMENTS.rst b/Help/prop_tgt/XCODE_SCHEME_ARGUMENTS.rst new file mode 100644 index 000000000..1f228e34c --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_ARGUMENTS.rst @@ -0,0 +1,10 @@ +XCODE_SCHEME_ARGUMENTS +---------------------- + +Specify command line arguments that should be added to the Arguments +section of the generated Xcode scheme. + +If set to a list of arguments those will be added to the scheme. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/prop_tgt/XCODE_SCHEME_DEBUG_AS_ROOT.rst b/Help/prop_tgt/XCODE_SCHEME_DEBUG_AS_ROOT.rst new file mode 100644 index 000000000..5407e807b --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_DEBUG_AS_ROOT.rst @@ -0,0 +1,7 @@ +XCODE_SCHEME_DEBUG_AS_ROOT +-------------------------- + +Whether to debug the target as 'root'. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/prop_tgt/XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING.rst b/Help/prop_tgt/XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING.rst new file mode 100644 index 000000000..9afeedd99 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING.rst @@ -0,0 +1,13 @@ +XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING +-------------------------------------- + +Whether to enable +``Allow debugging when using document Versions Browser`` +in the Options section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING` +if it is set when a target is created. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/prop_tgt/XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER.rst b/Help/prop_tgt/XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER.rst new file mode 100644 index 000000000..1a6fcfd2e --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER +---------------------------------------- + +Whether to disable the ``Main Thread Checker`` +in the Diagnostics section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER` +if it is set when a target is created. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/prop_tgt/XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS.rst b/Help/prop_tgt/XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS.rst new file mode 100644 index 000000000..922402290 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS +---------------------------------- + +Whether to enable ``Dynamic Library Loads`` +in the Diagnostics section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS` if it is set +when a target is created. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/prop_tgt/XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE.rst b/Help/prop_tgt/XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE.rst new file mode 100644 index 000000000..203c80329 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE +------------------------------------- + +Whether to enable ``Dynamic Linker API usage`` +in the Diagnostics section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE` if it is set +when a target is created. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/prop_tgt/XCODE_SCHEME_ENVIRONMENT.rst b/Help/prop_tgt/XCODE_SCHEME_ENVIRONMENT.rst new file mode 100644 index 000000000..c6d875e88 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_ENVIRONMENT.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_ENVIRONMENT +------------------------ + +Specify environment variables that should be added to the Arguments +section of the generated Xcode scheme. + +If set to a list of environment variables and values of the form +``MYVAR=value`` those environment variables will be added to the +scheme. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/prop_tgt/XCODE_SCHEME_EXECUTABLE.rst b/Help/prop_tgt/XCODE_SCHEME_EXECUTABLE.rst new file mode 100644 index 000000000..104841b7c --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_EXECUTABLE.rst @@ -0,0 +1,9 @@ +XCODE_SCHEME_EXECUTABLE +----------------------- + +Specify path to executable in the Info section of the generated +Xcode scheme. If not set the schema generator will select the +current target if it is actually executable. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/prop_tgt/XCODE_SCHEME_GUARD_MALLOC.rst b/Help/prop_tgt/XCODE_SCHEME_GUARD_MALLOC.rst new file mode 100644 index 000000000..c4e83da2f --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_GUARD_MALLOC.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_GUARD_MALLOC +------------------------------ + +Whether to enable ``Guard Malloc`` +in the Diagnostics section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_GUARD_MALLOC` if it is set +when a target is created. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/prop_tgt/XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP.rst b/Help/prop_tgt/XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP.rst new file mode 100644 index 000000000..73992c3c3 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP.rst @@ -0,0 +1,13 @@ +XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP +------------------------------------- + +Whether to enable the ``Main Thread Checker`` option +``Pause on issues`` +in the Diagnostics section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP` if it is set +when a target is created. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/prop_tgt/XCODE_SCHEME_MALLOC_GUARD_EDGES.rst b/Help/prop_tgt/XCODE_SCHEME_MALLOC_GUARD_EDGES.rst new file mode 100644 index 000000000..ca761c05b --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_MALLOC_GUARD_EDGES.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_MALLOC_GUARD_EDGES +------------------------------- + +Whether to enable ``Malloc Guard Edges`` +in the Diagnostics section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES` if it is set +when a target is created. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/prop_tgt/XCODE_SCHEME_MALLOC_SCRIBBLE.rst b/Help/prop_tgt/XCODE_SCHEME_MALLOC_SCRIBBLE.rst new file mode 100644 index 000000000..c5ddb950f --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_MALLOC_SCRIBBLE.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_MALLOC_SCRIBBLE +------------------------------ + +Whether to enable ``Malloc Scribble`` +in the Diagnostics section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE` if it is set +when a target is created. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/prop_tgt/XCODE_SCHEME_MALLOC_STACK.rst b/Help/prop_tgt/XCODE_SCHEME_MALLOC_STACK.rst new file mode 100644 index 000000000..170f33d90 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_MALLOC_STACK.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_MALLOC_STACK +------------------------- + +Whether to enable ``Malloc Stack`` in the Diagnostics +section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_MALLOC_STACK` if it is set +when a target is created. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/prop_tgt/XCODE_SCHEME_THREAD_SANITIZER.rst b/Help/prop_tgt/XCODE_SCHEME_THREAD_SANITIZER.rst new file mode 100644 index 000000000..bb70141f3 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_THREAD_SANITIZER.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_THREAD_SANITIZER +----------------------------- + +Whether to enable ``Thread Sanitizer`` in the Diagnostics +section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_THREAD_SANITIZER` if it is set +when a target is created. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/prop_tgt/XCODE_SCHEME_THREAD_SANITIZER_STOP.rst b/Help/prop_tgt/XCODE_SCHEME_THREAD_SANITIZER_STOP.rst new file mode 100644 index 000000000..5deadb16e --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_THREAD_SANITIZER_STOP.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_THREAD_SANITIZER_STOP +---------------------------------- + +Whether to enable ``Thread Sanitizer - Pause on issues`` +in the Diagnostics section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP` if it is set +when a target is created. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER.rst b/Help/prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER.rst new file mode 100644 index 000000000..0cd823dec --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER +------------------------------------------ + +Whether to enable ``Undefined Behavior Sanitizer`` +in the Diagnostics section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER` +if it is set when a target is created. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP.rst b/Help/prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP.rst new file mode 100644 index 000000000..d1a9bca2c --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP.rst @@ -0,0 +1,13 @@ +XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP +----------------------------------------------- + +Whether to enable ``Undefined Behavior Sanitizer`` option +``Pause on issues`` +in the Diagnostics section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP` +if it is set when a target is created. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/prop_tgt/XCODE_SCHEME_ZOMBIE_OBJECTS.rst b/Help/prop_tgt/XCODE_SCHEME_ZOMBIE_OBJECTS.rst new file mode 100644 index 000000000..6e70e8be9 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_ZOMBIE_OBJECTS.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_ZOMBIE_OBJECTS +------------------------------ + +Whether to enable ``Zombie Objects`` +in the Diagnostics section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS` if it is set +when a target is created. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/release/3.0.rst b/Help/release/3.0.rst index d02f94093..64491e310 100644 --- a/Help/release/3.0.rst +++ b/Help/release/3.0.rst @@ -224,7 +224,7 @@ Modules option to change the ``boost`` prefix on library names. * The :module:`FindBoost` module learned to control search - for libraies with the ``g`` tag (for MS debug runtime) with + for libraries with the ``g`` tag (for MS debug runtime) with a new ``Boost_USE_DEBUG_RUNTIME`` option. It is ``ON`` by default to preserve existing behavior. diff --git a/Help/release/3.1.rst b/Help/release/3.1.rst index dca42cdcd..8bea28f70 100644 --- a/Help/release/3.1.rst +++ b/Help/release/3.1.rst @@ -289,16 +289,16 @@ CPack ----- * :manual:`cpack(1)` gained an ``IFW`` generator to package using - Qt Framework Installer tools. See the :module:`CPackIFW` module. + Qt Framework Installer tools. See the :cpack_gen:`CPack IFW Generator`. * :manual:`cpack(1)` gained ``7Z`` and ``TXZ`` generators supporting lzma-compressed archives. -* The :module:`CPackDeb` module learned a new +* The :cpack_gen:`CPack DEB Generator` learned a new :variable:`CPACK_DEBIAN_COMPRESSION_TYPE` variable to set the tarball compression type. -* The :manual:`cpack(1)` ``WiX`` generator learned to support +* The :cpack_gen:`CPack WIX Generator` learned to support a :prop_inst:`CPACK_WIX_ACL` installed file property to specify an Access Control List. diff --git a/Help/release/3.10.rst b/Help/release/3.10.rst new file mode 100644 index 000000000..03eda362d --- /dev/null +++ b/Help/release/3.10.rst @@ -0,0 +1,282 @@ +CMake 3.10 Release Notes +************************ + +.. only:: html + + .. contents:: + +Changes made since CMake 3.9 include the following. + +New Features +============ + +Platforms +--------- + +* The `flang`_ Fortran compiler is now supported, with compiler id ``Flang``. + +* A new minimal platform file for ``Midipix`` was added. + +* Support for the MSVC ARM64 architecture was added. + Visual Studio 2017 Update 4 and above offer an ARM64 toolchain. + +* Support for the IAR ARM Compiler was improved. + +.. _`flang`: https://github.com/flang-compiler/flang + +Generators +---------- + +* The :ref:`Makefile Generators` and the :generator:`Ninja` generator learned + to add compiler launcher tools like ccache along with the compiler for the + ``CUDA`` language (``C`` and ``CXX`` were supported previously). See the + :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER` variable and + :prop_tgt:`<LANG>_COMPILER_LAUNCHER` target property for details. + +* The :generator:`CodeBlocks` extra generator learned to optionally exclude + files from outside the project root directory from the generated project. + See the :variable:`CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES` variable. + +Commands +-------- + +* The :command:`cmake_host_system_information` command learned more keys + to get information about the processor capabilities and the host OS + version. + +* The :command:`configure_file` command learned to support indented + ``# cmakedefine`` and ``# cmakedefine01``. Spaces and/or tabs between + the ``#`` character and the ``cmakedefine``/``cmakedefine01`` words + are now understood and preserved in the output. + +* The :command:`execute_process` command gained a ``RESULTS_VARIABLE`` + option to collect a list of results from all children in a pipeline + of processes when multiple ``COMMAND`` arguments are given. + +* The :command:`include_guard` command was introduced to allow guarding + CMake scripts from being included more than once. The command supports + ``DIRECTORY`` and ``GLOBAL`` options to adjust the corresponding include guard + scope. If no options given, include guard is similar to basic variable-based + check. + +* The :command:`string` command learned a new ``PREPEND`` subcommand. + +* The :command:`string(TIMESTAMP)` command now supports ``%A`` + for full weekday name and ``%B`` for full month name. + +Variables +--------- + +* A :variable:`CMAKE_DIRECTORY_LABELS` variable was added to specify + labels for all tests in a directory. + +Properties +---------- + +* A :prop_tgt:`<LANG>_CPPCHECK` target property and supporting + :variable:`CMAKE_<LANG>_CPPCHECK` variable were introduced to tell + the :ref:`Makefile Generators` and the :generator:`Ninja` generator to + run ``cppcheck`` with the compiler for ``C`` and ``CXX`` languages. + +* A :prop_dir:`LABELS` directory property was added to specify labels + for all targets and tests in a directory. + +* A :prop_dir:`TEST_INCLUDE_FILES` directory property was added to + list any number of files to be included when running tests with + :manual:`ctest(1)`. This generalizes the :prop_dir:`TEST_INCLUDE_FILE` + property. + +* The :prop_tgt:`VS_DOTNET_REFERENCEPROP_<refname>_TAG_<tagname>` + target property was added to support custom XML tags for reference + assemblies in C# targets. + +* Source file properties :prop_sf:`VS_SHADER_OUTPUT_HEADER_FILE` and + :prop_sf:`VS_SHADER_VARIABLE_NAME` have been added to specify more + details of ``.hlsl`` sources with :ref:`Visual Studio Generators`. + +Modules +------- + +* The :module:`FindCurses` module gained a ``CURSES_NEED_WIDE`` option + to request the wide-character variant. + +* The :module:`FindEXPAT` module now provides imported targets. + +* The :module:`FindFreetype` module now provides imported targets. + +* :module:`FindMPI` gained a number of new features, including: + + * Language-specific components have been added to the module. + * Many more MPI environments are now supported. + * The environmental support for Fortran has been improved. + * A user now has fine-grained control over the MPI selection process, + including passing custom parameters to the MPI compiler. + * The version of the implemented MPI standard is now being exposed. + * MPI-2 C++ bindings can now be detected and also suppressed if so desired. + * The available Fortran bindings are now being detected and verified. + * Various MPI-3 information can be requested, including the library version + and Fortran capabilities of the individual bindings. + * Statically linked MPI implementations are supported. + +* A :module:`FindOpenACC` module was added to detect compiler support + for OpenACC. Currently only supports PGI, GNU and Cray compilers. + +* The :module:`FindOpenGL` module gained support for GLVND on Linux. + +* The :module:`FindOpenMP` module gained support for + language-specific components. + +* A :module:`FindPatch` module was added to find the ``patch`` + command-line executable. + +* The :module:`FindProtobuf` module :command:`protobuf_generate_cpp` command + gained a ``DESCRIPTORS`` option to generate descriptor files. + +* The :module:`GoogleTest` module gained a new command + :command:`gtest_discover_tests` implementing dynamic (build-time) test + discovery. Unlike the source parsing approach, dynamic discovery executes + the test (in 'list available tests' mode) at build time to discover tests. + This is robust against unusual ways of labeling tests, provides much better + support for advanced features such as parameterized tests, and does not + require re-running CMake to discover added or removed tests within a test + executable. Note that a breaking change was made in CMake 3.10.3 to address + an ambiguity of the ``TIMEOUT`` keyword (see :ref:`Release Notes 3.10.3`). + +* The :module:`InstallRequiredSystemLibraries` module gained support + for installing Intel compiler runtimes. + +Autogen +------- + +* When using :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC` with a + multi configuration generator (e.g. :generator:`Xcode`), + included ``*.moc``, ``moc_*.cpp`` and ``ui_*.h`` files are generated in + ``<AUTOGEN_BUILD_DIR>/include_<CONFIG>`` instead of + ``<AUTOGEN_BUILD_DIR>/include``. + +* When using :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC`, + source files that are :prop_sf:`GENERATED` will be processed as well. + They were ignored by :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` + in earlier releases. + See policy :policy:`CMP0071`. + +* When using :prop_tgt:`AUTOMOC`, CMake searches for the strings ``Q_OBJECT``, + ``Q_GADGET`` or ``Q_NAMESPACE`` in a source file to determine if it needs + to be ``moc`` processed. The new :variable:`CMAKE_AUTOMOC_MACRO_NAMES` + variable and :prop_tgt:`AUTOMOC_MACRO_NAMES` target property may be set + to register additional strings (macro names) to search for. + +* When using :prop_tgt:`AUTOMOC`, the new + :variable:`CMAKE_AUTOMOC_COMPILER_PREDEFINES` variable and + :prop_tgt:`AUTOMOC_COMPILER_PREDEFINES` target property specify whether + to enable or disable the generation of the compiler pre definitions file + ``moc_predefs.h``. + +CTest +----- + +* A :variable:`CTEST_LABELS_FOR_SUBPROJECTS` CTest module variable and CTest + script variable were added to specify a list of labels that should be + treated as subprojects by CDash. To use this value in both the CTest module + and the ctest command line :ref:`Dashboard Client` mode (e.g. ``ctest -S``) + set it in the ``CTestConfig.cmake`` config file. + +CPack +----- + +* A :cpack_gen:`CPack FreeBSD Generator` was added for FreeBSD ``pkg(8)``. + +* The :cpack_gen:`CPack DEB Generator` was enabled on Windows. While not + fully featured (due to the lack of external UNIX tools) this will allow + building basic cross-platform Debian packages. + +* The :cpack_gen:`CPack DEB Generator` learned to set package release + version in ``Version`` info property. + See the :variable:`CPACK_DEBIAN_PACKAGE_RELEASE` variable. + +* The :cpack_gen:`CPack DEB Generator` learned more strict package + version checking that complies with Debian rules. + +* The :module:`CPackIFW` module :command:`cpack_ifw_configure_component` and + :command:`cpack_ifw_configure_component_group` commands gained a new + ``REPLACES`` and ``CHECKABLE`` options. + +* The :cpack_gen:`CPack IFW Generator` gained new + :variable:`CPACK_IFW_PACKAGE_FILE_EXTENSION` variable to customize + target binary format. + +* The :cpack_gen:`CPack IFW Generator` gained new + :variable:`CPACK_IFW_REPOSITORIES_DIRECTORIES` variable to specify + additional repositories dirs that will be used to resolve and + repack dependent components. This feature is only available when + using QtIFW 3.1 or later. + +* The :cpack_gen:`CPack RPM Generator` and :cpack_gen:`CPack DEB Generator` + learned to set the package epoch version. + See :variable:`CPACK_RPM_PACKAGE_EPOCH` and + :variable:`CPACK_DEBIAN_PACKAGE_EPOCH` variables. + +Other +----- + +* The :manual:`cmake(1)` ``-E`` mode gained support for ``sha1sum``, + ``sha224sum``, ``sha256sum``, ``sha384sum``, and ``sha512sum``. + +* The graphviz output now distinguishes among the different dependency types + ``PUBLIC``, ``PRIVATE`` and ``INTERFACE`` and represents them in the output + graph as solid, dashed and dotted edges. + +Deprecated and Removed Features +=============================== + +* Support for building CMake itself with C++98 compilers was dropped. + CMake is now implemented using C++11. + +* Support for building CMake on HP-UX has been dropped pending better + support for C++11 and a port of libuv. See `CMake Issue 17137`_. + Use CMake 3.9 or lower instead for HP-UX support. + +.. _`CMake Issue 17137`: https://gitlab.kitware.com/cmake/cmake/issues/17137 + +Other Changes +============= + +* On FreeBSD the C++ compiler named ``c++`` is now the preferred default. + +* The :command:`file(GENERATE)` command now interprets relative paths + given to its ``OUTPUT`` and ``INPUT`` arguments with respect to the + caller's current binary and source directories, respectively. + See policy :policy:`CMP0070`. + +* The :command:`get_filename_component` ``PROGRAM`` mode semantics + have been revised to not tolerate unquoted spaces in the path + to the program while also accepting arguments. While technically + incompatible with the old behavior, it is expected that behavior + under typical use cases with properly-quoted command-lines has + not changed. + +Updates +======= + +Changes made since CMake 3.10.0 include the following. + +3.10.1 +------ + +* The :manual:`cmake-server(7)` ``codemodel`` response ``crossReferences`` + field added by 3.10.0 has been dropped due to excessive memory usage. + Another approach will be needed to provide backtrace information. + +.. _`Release Notes 3.10.3`: + +3.10.3 +------ + +* CMake 3.10.1 added a ``TIMEOUT`` option to :command:`gtest_discover_tests` + from the :module:`GoogleTest` module. That keyword clashed with the + ``TIMEOUT`` test property, which is one of the common properties that + would be set with the command's ``PROPERTIES`` keyword, usually leading + to legal but unintended behavior. The keyword was changed to + ``DISCOVERY_TIMEOUT`` in CMake 3.10.3 to address this problem. The + ambiguous behavior of the :command:`gtest_discover_tests` command's + ``TIMEOUT`` keyword in 3.10.1 and 3.10.2 has not been preserved. diff --git a/Help/release/3.11.rst b/Help/release/3.11.rst new file mode 100644 index 000000000..a80657d2d --- /dev/null +++ b/Help/release/3.11.rst @@ -0,0 +1,307 @@ +CMake 3.11 Release Notes +************************ + +.. only:: html + + .. contents:: + +Changes made since CMake 3.10 include the following. + +New Features +============ + +Platforms +--------- + +* TI C/C++ compilers are now supported by the :generator:`Ninja` generator. + +Generators +---------- + +* The :generator:`CodeBlocks` extra generator learned to check a + :variable:`CMAKE_CODEBLOCKS_COMPILER_ID` variable for a custom + compiler identification value to place in the project file. + +* The :ref:`Makefile Generators` and the :generator:`Ninja` generator learned + to add compiler launcher tools along with the compiler for the ``Fortran`` + language (``C``, ``CXX``, and ``CUDA`` were supported previously). + See the :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER` variable and + :prop_tgt:`<LANG>_COMPILER_LAUNCHER` target property for details. + +* :ref:`Visual Studio Generators` learned to support the ``COMPILE_LANGUAGE`` + :manual:`generator expression <cmake-generator-expressions(7)>` in + target-wide :prop_tgt:`COMPILE_DEFINITIONS`, + :prop_tgt:`INCLUDE_DIRECTORIES`, :prop_tgt:`COMPILE_OPTIONS`, and + :command:`file(GENERATE)`. See generator expression documentation + for caveats. + +* The :generator:`Xcode` generator learned to support the ``COMPILE_LANGUAGE`` + :manual:`generator expression <cmake-generator-expressions(7)>` in + target-wide :prop_tgt:`COMPILE_DEFINITIONS` and + :prop_tgt:`INCLUDE_DIRECTORIES`. It previously supported only + :prop_tgt:`COMPILE_OPTIONS` and :command:`file(GENERATE)`. + See generator expression documentation for caveats. + +Commands +-------- + +* :command:`add_library` and :command:`add_executable` commands can now be + called without any sources and will not complain as long as sources are + added later via the :command:`target_sources` command. + +* The :command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands + gained ``NETRC`` and ``NETRC_FILE`` options to specify use of a + ``.netrc`` file. + +* The :command:`target_compile_definitions` command learned to set the + :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` property on + :ref:`Imported Targets`. + +* The :command:`target_compile_features` command learned to set the + :prop_tgt:`INTERFACE_COMPILE_FEATURES` property on :ref:`Imported Targets`. + +* The :command:`target_compile_options` command learned to set the + :prop_tgt:`INTERFACE_COMPILE_OPTIONS` property on :ref:`Imported Targets`. + +* The :command:`target_include_directories` command learned to set the + :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` property on + :ref:`Imported Targets`. + +* The :command:`target_sources` command learned to set the + :prop_tgt:`INTERFACE_SOURCES` property on :ref:`Imported Targets`. + +* The :command:`target_link_libraries` command learned to set the + :prop_tgt:`INTERFACE_LINK_LIBRARIES` property on :ref:`Imported Targets`. + +Variables +--------- + +* A :variable:`CMAKE_GENERATOR_INSTANCE` variable was introduced + to hold the selected instance of the generator's corresponding + native tools if multiple are available. This is used by the + :generator:`Visual Studio 15 2017` generator to hold the + selected instance of Visual Studio persistently. + +* A :variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` variable was added + to enable setting of default permissions for directories created implicitly + during installation of files by :command:`install` and + :command:`file(INSTALL)`, e.g. during ``make install``. + +* A :variable:`CMAKE_JOB_POOLS` variable was added specify a value to use for + the :prop_gbl:`JOB_POOLS` property. This enables control over build + parallelism with command line configuration parameters when using the Ninja + generator. + +* The :variable:`CMAKE_NETRC` and :variable:`CMAKE_NETRC_FILE` variables + were added to specify use of a ``.netrc`` file by the + :command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands and + the :module:`ExternalProject` module. + +* A :variable:`CMAKE_CUDA_SEPARABLE_COMPILATION` variable was added to + initialize the :prop_tgt:`CUDA_SEPARABLE_COMPILATION` target property + on targets when they are created. + +Properties +---------- + +* The :prop_sf:`COMPILE_DEFINITIONS` source file property learned to support + :manual:`generator expressions <cmake-generator-expressions(7)>`. + +* A :prop_sf:`COMPILE_OPTIONS` source file property was added to manage list + of options to pass to the compiler. + +* An :prop_tgt:`IMPORTED_GLOBAL` target property was added to indicate + whether an :ref:`IMPORTED target <Imported Targets>` is globally visible. + It is automatically set to a true value for targets created with the + ``GLOBAL`` option to :command:`add_library` or :command:`add_executable`. + Additionally, project code may now *promote* a local imported target + to be globally visible by setting this property to ``TRUE``. + +* An :prop_sf:`INCLUDE_DIRECTORIES` source file property was added to specify + list of preprocessor include file search directories. + +* Source file properties :prop_sf:`VS_SHADER_DISABLE_OPTIMIZATIONS` and + :prop_sf:`VS_SHADER_ENABLE_DEBUG` have been added to specify more + details of ``.hlsl`` sources with :ref:`Visual Studio Generators`. + +Modules +------- + +* The :module:`CheckIncludeFiles` module :command:`CHECK_INCLUDE_FILES` + command gained a ``LANGUAGE`` option to specify whether to check using the + ``C`` or ``CXX`` compiler. + +* The :module:`CMakePackageConfigHelpers` module + :command:`write_basic_package_version_file` command learned a new + ``SameMinorVersion`` mode for the ``COMPATIBILITY`` argument. + +* The :module:`ExternalProject` module learned to substitute ``<DOWNLOAD_DIR>`` + in comments, commands, working directory and byproducts. + +* The :module:`ExternalProject` module gained ``NETRC`` and ``NETRC_FILE`` + options to specify use of a ``.netrc`` file. + +* A new :module:`FetchContent` module was added which supports populating + content at configure time using any of the download/update methods + supported by :command:`ExternalProject_Add`. This allows the content + to be used immediately during the configure stage, such as with + :command:`add_subdirectory`, etc. Hierarchical project structures are + well supported, allowing parent projects to override the content details + of child projects and ensuring content is not populated multiple times + throughout the whole project tree. + +* The :module:`FindBLAS` and :module:`FindLAPACK` modules learned to support + `FLAME`_ ``blis`` and ``libflame``. + +* The :module:`FindDoxygen` module :command:`doxygen_add_docs` function + now supports a new ``DOXYGEN_VERBATIM_VARS`` list variable. Any + ``DOXYGEN_...`` variable contained in that list will bypass the automatic + quoting logic, leaving its contents untouched when transferring them to the + output ``Doxyfile``. + +* A :module:`FindIconv` module was added to locate iconv support. + +* The :module:`GenerateExportHeader` module ``GENERATE_EXPORT_HEADER`` command + gained an ``INCLUDE_GUARD_NAME`` option to change the name of the include + guard symbol written to the generated export header. + Additionally, it now adds a comment after the closing ``#endif`` on the + generated export header's include guard. + +* The :module:`UseJava` module ``add_jar`` command gained a + ``GENERATE_NATIVE_HEADERS`` option to generate native header files + using ``javac -h`` for ``javac`` 1.8 or above. This supersedes + ``create_javah``, which no longer works with JDK 1.10 and above due + to removal of the ``javah`` tool by `JEP 313`_. + +.. _`FLAME`: https://github.com/flame +.. _`JEP 313`: http://openjdk.java.net/jeps/313 + +Autogen +------- + +* When using :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC`, CMake now starts + multiple parallel ``moc`` or ``uic`` processes to reduce the build time. + A new :variable:`CMAKE_AUTOGEN_PARALLEL` variable and + :prop_tgt:`AUTOGEN_PARALLEL` target property may be set to specify the + number of parallel ``moc`` or ``uic`` processes to start. The default + is derived from the number of CPUs on the host. + +CTest +----- + +* The :command:`ctest_start` command no longer sets + :variable:`CTEST_RUN_CURRENT_SCRIPT` due to issues with scoping if it is + called from inside a function. Instead, it sets an internal variable in + CTest. However, setting :variable:`CTEST_RUN_CURRENT_SCRIPT` to 0 at the + global scope still prevents the script from being re-run at the end. + +CPack +----- + +* :manual:`cpack(1)` gained ``--trace`` and ``--trace-expand`` options. + +* The :cpack_gen:`CPack IFW Generator` gained new + :variable:`CPACK_IFW_PACKAGE_REMOVE_TARGET_DIR` variable to control + if the target directory should not be deleted when uninstalling. + +* The :cpack_gen:`CPack RPM Generator` learned to enable enforcing of execute + privileges on programs and shared libraries. + See :variable:`CPACK_RPM_INSTALL_WITH_EXEC` variable. + +* A :variable:`CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` variable was added + which serves the same purpose during packaging (e.g. ``make package``) as the + :variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` variable serves during + installation (e.g. ``make install``). + +Other +----- + +* :ref:`Alias Targets` may now alias :ref:`Imported Targets` that are + created with the ``GLOBAL`` option to :command:`add_library`. + +* :ref:`Interface Libraries` may now have custom properties set on them if + they start with either an underscore (``_``) or a lowercase ASCII character. + The original intention was to only allow properties which made sense for + ``INTERFACE`` libraries, but it also blocked usage of custom properties. + +* The :manual:`cmake(1)` ``--open <dir>`` command-line option was added + to open generated IDE projects like Visual Studio solutions or Xcode + projects. + +Deprecated and Removed Features +=============================== + +* An explicit deprecation diagnostic was added for policies ``CMP0037`` + through ``CMP0054`` (``CMP0036`` and below were already deprecated). + The :manual:`cmake-policies(7)` manual explains that the OLD behaviors + of all policies are deprecated and that projects should port to the + NEW behaviors. + +* The ``KDevelop3`` generator has been removed. + +Other Changes +============= + +* Policy :policy:`CMP0037` no longer reserves target names associated + with optional features, such as ``test`` and ``package``, unless + the corresponding feature is enabled. + +* The :module:`FindOpenGL` module now prefers GLVND libraries if available. + See policy :policy:`CMP0072`. + +* The minimum deployment target set in the + :variable:`CMAKE_OSX_DEPLOYMENT_TARGET` variable used to be only + applied for macOS regardless of the selected SDK. It is now properly + set for the target platform selected by :variable:`CMAKE_OSX_SYSROOT`. + For example, if the sysroot variable specifies an iOS SDK then the + value in ``CMAKE_OSX_DEPLOYMENT_TARGET`` is interpreted as minimum + iOS version. + +* The :generator:`Xcode` generator behavior of generating one project + file per :command:`project()` command may now be controlled with the + :variable:`CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY` variable. + This could be useful to speed up the CMake generation step for + large projects and to work-around a bug in the ``ZERO_CHECK`` logic. + +* Since the ``CMakeCache.txt`` format does not support newlines in values, + values containing newlines are now truncated before writing to the file. + In addition, a warning comment is written to the cache file, and a warning + message is displayed to the user on the console. + +Updates +======= + +Changes made since CMake 3.11.0 include the following. + +3.11.1 +------ + +* The :module:`CheckIncludeFile` module ``check_include_file`` macro, + :module:`CheckIncludeFileCXX` module ``check_include_file_cxx`` macro, + and :module:`CheckIncludeFiles` module ``check_include_files`` macro + were taught to honor the ``CMAKE_REQUIRED_LIBRARIES`` variable in + CMake 3.11.0. This has been reverted due to changing behavior of + checks for existing projects. It may be restored in the future + with a policy for compatibility. + +3.11.2 +------ + +* Calling :command:`add_library` to create an alias of an imported + target that is not globally visible now causes an error again as + it did prior to 3.11.0. This diagnostic was accidentally dropped + from CMake 3.11.0 and 3.11.1 by the change to allow globally visible + imported targets to be aliased. + +* The :module:`FindQt4` module ``qt4_wrap_cpp``, ``qt4_wrap_ui`` and + ``qt4_add_resources`` macros now set :prop_sf:`SKIP_AUTOMOC` and + :prop_sf:`SKIP_AUTOUIC` on their generated files. These files never + need to be processed by moc or uic, and we must say so explicitly to + account for policy :policy:`CMP0071`. + +3.11.3 +------ + +* CMake 3.11.0 introduced support for resolving symbolic links on + Windows in code paths that typically do so on UNIX. This has been + reverted due to breakage on ``subst`` drives. diff --git a/Help/release/3.12.rst b/Help/release/3.12.rst new file mode 100644 index 000000000..481027ec7 --- /dev/null +++ b/Help/release/3.12.rst @@ -0,0 +1,305 @@ +CMake 3.12 Release Notes +************************ + +.. only:: html + + .. contents:: + +Changes made since CMake 3.11 include the following. + +New Features +============ + +Generators +---------- + +* The :ref:`Visual Studio Generators` for VS 2017 learned to support a + ``version=14.##`` option in the :variable:`CMAKE_GENERATOR_TOOLSET` + value (e.g. via the :manual:`cmake(1)` ``-T`` option) to specify a + toolset version number. + +Command-Line +------------ + +* The :manual:`cmake(1)` :ref:`Build Tool Mode` (``cmake --build``) gained + ``--parallel [<jobs>]`` and ``-j [<jobs>]`` options to specify a parallel + build level. They map to corresponding options of the native build tool. + +Commands +-------- + +* The :command:`add_compile_definitions` command was added to set preprocessor + definitions at directory level. This supersedes :command:`add_definitions`. + +* The :command:`cmake_minimum_required` and :command:`cmake_policy(VERSION)` + commands now accept a version range using the form ``<min>[...<max>]``. + The ``<min>`` version is required but policies are set based on the + older of the running CMake version and the version specified by + ``<max>``. This allows projects to specify a range of versions + for which they have been updated and avoid explicit policy settings. + +* The :command:`file(GLOB)` and :command:`file(GLOB_RECURSE)` commands + learned a new flag ``CONFIGURE_DEPENDS`` which enables expression of + build system dependency on globbed directory's contents. + +* The :command:`file(TOUCH)` and :command:`file(TOUCH_NOCREATE)` commands + were added to expose ``TOUCH`` functionality without having to use + CMake's command-line tool mode with :command:`execute_process`. + +* The :command:`find_package` command now searches prefixes specified by + the :variable:`<PackageName>_ROOT` CMake variable and the + :envvar:`<PackageName>_ROOT` environment variable. Package roots are + maintained as a stack so nested calls to all ``find_*`` commands inside + find modules also search the roots as prefixes. + See policy :policy:`CMP0074`. + +* The :command:`install` command learned an optional ``NAMELINK_COMPONENT`` + parameter, which allows you to change the component for a shared library's + namelink. If none is specified, the value of ``COMPONENT`` is used by + default. + +* The :command:`list` command learned a ``JOIN`` sub-command + to concatenate list's elements separated by a glue string. + +* The :command:`list` command learned a ``SUBLIST`` sub-command + to get a sublist of the list. + +* The :command:`list` command learned a ``TRANSFORM`` sub-command + to apply various string transformation to list's elements. + +* The :command:`project` command learned an optional ``HOMEPAGE_URL`` + parameter which has the effect of setting variables like + :variable:`PROJECT_HOMEPAGE_URL`, :variable:`<PROJECT-NAME>_HOMEPAGE_URL` + and :variable:`CMAKE_PROJECT_HOMEPAGE_URL`. + +* The :command:`string` command learned a ``JOIN`` sub-command + to concatenate input strings separated by a glue string. + +* :command:`target_compile_options` and :command:`add_compile_options` + commands gained a ``SHELL:`` prefix to specify a group of related + options using shell-like quoting. + +* The :command:`target_link_libraries` command now supports + :ref:`Object Libraries`. Linking to an object library uses its object + files in direct dependents and also propagates usage requirements. + +Variables +--------- + +* The :variable:`CMAKE_FOLDER` variable was added to initialize the + :prop_tgt:`FOLDER` property on all targets. + +* The :variable:`CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION` variable + was defined to initialize all + :prop_tgt:`DOTNET_TARGET_FRAMEWORK_VERSION` target properties. + +* ``CMAKE_PROJECT_VERSION*`` variables have been introduced: + + - :variable:`CMAKE_PROJECT_VERSION` + - :variable:`CMAKE_PROJECT_VERSION_MAJOR` + - :variable:`CMAKE_PROJECT_VERSION_MINOR` + - :variable:`CMAKE_PROJECT_VERSION_PATCH` + - :variable:`CMAKE_PROJECT_VERSION_TWEAK` + +* The :variable:`CMAKE_SUPPRESS_REGENERATION` variable was extended to + support the :generator:`Ninja` and :ref:`Makefile Generators`. + It is also now documented. + +* ``CMAKE_VS_SDK_*_DIRECTORIES`` variables were defined to tell + :ref:`Visual Studio Generators` for VS 2010 and above how to populate + fields in ``.vcxproj`` files that specify SDK directories. The + variables are: + + - :variable:`CMAKE_VS_SDK_EXCLUDE_DIRECTORIES` + - :variable:`CMAKE_VS_SDK_EXECUTABLE_DIRECTORIES` + - :variable:`CMAKE_VS_SDK_INCLUDE_DIRECTORIES` + - :variable:`CMAKE_VS_SDK_LIBRARY_DIRECTORIES` + - :variable:`CMAKE_VS_SDK_LIBRARY_WINRT_DIRECTORIES` + - :variable:`CMAKE_VS_SDK_REFERENCE_DIRECTORIES` + - :variable:`CMAKE_VS_SDK_SOURCE_DIRECTORIES` + +* A :variable:`MSVC_TOOLSET_VERSION` variable was added to provide the + MSVC toolset version associated with the current MSVC compiler version + in :variable:`MSVC_VERSION`. + +Properties +---------- + +* The :prop_tgt:`COMMON_LANGUAGE_RUNTIME` target property was introduced + to configure the use of managed C++ for :ref:`Visual Studio Generators` + for VS 2010 and above. + A corresponding :prop_tgt:`IMPORTED_COMMON_LANGUAGE_RUNTIME` target + property was added to support ``C++/CLI`` for imported targets. + +* The :prop_tgt:`DOTNET_TARGET_FRAMEWORK_VERSION` target property + was introduced as replacement for + :prop_tgt:`VS_DOTNET_TARGET_FRAMEWORK_VERSION`, which is considered + deprecated now. + +* An :prop_tgt:`EXPORT_PROPERTIES` target property was added to specify a + custom list of target properties to include in targets exported by the + :command:`install(EXPORT)` and :command:`export` commands. + +* The :prop_tgt:`PDB_OUTPUT_DIRECTORY` property learned to support + :manual:`generator expressions <cmake-generator-expressions(7)>`. + +* A :prop_dir:`TESTS` directory property was added to hold the list of + tests defined by the :command:`add_test` command. + +* A :prop_tgt:`VS_DEBUGGER_COMMAND` target property was created to set the + debugging command line with :ref:`Visual Studio Generators` for VS 2010 + and above. + +* HLSL source file properties :prop_sf:`VS_SHADER_DISABLE_OPTIMIZATIONS` + and :prop_sf:`VS_SHADER_ENABLE_DEBUG` gained support for generator + expressions. + +* HLSL source file property :prop_sf:`VS_SHADER_OBJECT_FILE_NAME` has been + added to the :ref:`Visual Studio Generators` for VS 2010 and above. + The property specifies the file name of the compiled shader object. + +Modules +------- + +* The :module:`FindALSA` module now provides imported targets. + +* The :module:`FindCURL` module now provides imported targets. + +* The :module:`FindJPEG` module now provides imported targets. + +* The :module:`FindLibXml2` module now provides imported targets. + +* The :module:`FindMatlab` module now supports the Matlab Runtime + Compiler (MCR) for compiling and linking matlab extensions. + +* A :module:`FindODBC` module was added to find an Open Database Connectivity + (ODBC) library. + +* The :module:`FindPkgConfig` module has learned to export the found + libraries with full path for direct consumption with the + :command:`target_link_libraries` command. + +* New :module:`FindPython3` and :module:`FindPython2` modules, as well as + a new :module:`FindPython` module, have been added to provide a new way + to locate python environments. + +* The :module:`UseSWIG` module gained a whole refresh and is now more + consistent with standard CMake commands to generate libraries and is + fully configurable through properties. + +* The :module:`UseSWIG` module learned to manage multiple behaviors through + ``UseSWIG_MODULE_VERSION`` variable to ensure legacy support as well as more + robust handling of ``SWIG`` advanced features (like ``%template``). + +* The :module:`UseSWIG` module learned to support CSHARP variant + wrapper files. + +* The :module:`WriteCompilerDetectionHeader` module gained a ``BARE_FEATURES`` + option to add a compatibility define for the exact keyword of a new language + feature. + +Generator Expressions +--------------------- + +* A new ``$<GENEX_EVAL:...>`` and ``$<TARGET_GENEX_EVAL:target,...>`` + :manual:`generator expression <cmake-generator-expressions(7)>` + has been added to enable consumption of generator expressions whose + evaluation results itself in generator expressions. + +* A new ``$<IN_LIST:...>`` + :manual:`generator expression <cmake-generator-expressions(7)>` + has been added. + +* A new ``$<TARGET_EXISTS:...>`` + :manual:`generator expression <cmake-generator-expressions(7)>` + has been added. + +* A new ``$<TARGET_NAME_IF_EXISTS:...>`` + :manual:`generator expression <cmake-generator-expressions(7)>` + has been added. + +CTest +----- + +* The :command:`ctest_start` command has been reworked so that you can simply + call ``ctest_start(APPEND)`` and it will read all the needed information from + the TAG file. The argument parsing has also been relaxed so that the order of + the arguments is less significant. + +* A :prop_test:`PROCESSOR_AFFINITY` test property was added to request + that CTest run a test with CPU affinity for a set of processors + disjoint from other concurrently running tests with the property set. + +CPack +----- + +* The :module:`CPack` module now uses variables + :variable:`CMAKE_PROJECT_VERSION_MAJOR`, + :variable:`CMAKE_PROJECT_VERSION_MINOR` and + :variable:`CMAKE_PROJECT_VERSION_PATCH` + to initialize corresponding CPack variables. + +* A :cpack_gen:`CPack NuGet Generator` was was added with basic + support for `NuGet`_. + +.. _NuGet: https://docs.microsoft.com/en-us/nuget/what-is-nuget + +Other +----- + +* The :manual:`Compile Features <cmake-compile-features(7)>` functionality + is now aware of C++ 20. No specific features are yet enumerated besides + the ``cxx_std_20`` meta-feature. + +* The :manual:`Compile Features <cmake-compile-features(7)>` functionality + is now aware of the availability of C features in MSVC since VS 2010. + +* The :manual:`Compile Features <cmake-compile-features(7)>` functionality + is now aware of C language standards supported by Texas Instruments C + compilers. + +Deprecated and Removed Features +=============================== + +* The :generator:`Visual Studio 8 2005` generator has been removed. + +* CMake no longer produces ``<tgt>_LIB_DEPENDS`` cache entries + for library targets. See policy :policy:`CMP0073`. + +Other Changes +============= + +* Include flags for directories marked as ``SYSTEM`` are now moved after + non-system directories. The ``-isystem`` flag does this automatically, + so moving them explicitly to the end makes the behavior consistent on + compilers that do not have any ``-isystem`` flag. + +* Fortran dependency scanning now supports dependencies implied by + `Fortran Submodules`_. + +* The existence and functionality of the file + ``${CMAKE_BINARY_DIR}/cmake_install.cmake`` has now been documented in the + :command:`install` documentation so that external packaging software can take + advantage of CPack-style component installs. + +* The :module:`CheckIncludeFile` module ``check_include_file`` macro + learned to honor the ``CMAKE_REQUIRED_LIBRARIES`` variable. + See policy :policy:`CMP0075`. + +* The :module:`CheckIncludeFileCXX` module ``check_include_file_cxx`` macro + learned to honor the ``CMAKE_REQUIRED_LIBRARIES`` variable. + See policy :policy:`CMP0075`. + +* The :module:`CheckIncludeFiles` module ``check_include_files`` macro + learned to honor the ``CMAKE_REQUIRED_LIBRARIES`` variable. + See policy :policy:`CMP0075`. + +* The :manual:`cmake(1)` ``-E copy_directory`` tool now fails when the + source directory does not exist. Previously it succeeded by creating + an empty destination directory. + +* The :module:`UseSWIG` module :command:`swig_add_library` command + (and legacy ``swig_add_module`` command) now set the prefix of + Java modules to ``""`` for MINGW, MSYS, and CYGWIN environments. + +.. _`Fortran Submodules`: http://fortranwiki.org/fortran/show/Submodules diff --git a/Help/release/3.13.rst b/Help/release/3.13.rst new file mode 100644 index 000000000..a8dd0baf7 --- /dev/null +++ b/Help/release/3.13.rst @@ -0,0 +1,289 @@ +CMake 3.13 Release Notes +************************ + +.. only:: html + + .. contents:: + +Changes made since CMake 3.12 include the following. + +New Features +============ + +Generators +---------- + +* The :ref:`Visual Studio Generators` for VS 2010 and above learned to + support the :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property + and supporting :module:`CheckIPOSupported` module. + +* The :generator:`Xcode` generator learned to configure more Xcode Scheme + fields. See the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable. + +* The :generator:`Green Hills MULTI` generator has been updated: + + - Added support for architecture selection through + :variable:`CMAKE_GENERATOR_PLATFORM`: + e.g. ``arm``, ``ppc``, and ``86``. + + - Added support for toolset selection through + :variable:`CMAKE_GENERATOR_TOOLSET`, + e.g. ``comp_201205``, ``comp_201510``, ``comp_201722_beta``. + + - Added support for platform selection through ``GHS_TARGET_PLATFORM``, + e.g. ``integrity``, ``linux``, ``standalone``, etc. + + - No longer checks that ``arm`` based compilers are installed but ensures + that the correct ``gbuild.exe`` exists. + + - No longer hard-codes ARM files, BSP, toolset, or OS locations. + +Command-Line +------------ + +* The :manual:`cmake(1)` command gained the ``-S <source_dir>`` + command line option to specify the location of the source directory. + This option can be used independently of ``-B``. + +* The :manual:`cmake(1)` command gained the ``-B <build_dir>`` + command line option to specify the location of the build directory. + This option can be used independently of ``-S``. + +* The :manual:`cmake(1)` ``-E create_symlink`` command can now be used + on Windows. + +Commands +-------- + +* The :command:`add_custom_command` and :command:`add_custom_target` commands + learned to support generator expressions in ``WORKING_DIRECTORY`` options. + +* The :command:`add_link_options` command was created to add link + options in the current directory. + +* The :command:`install(TARGETS)` command learned to install targets + created outside the current directory. + +* The :command:`link_directories` command gained options to control + insertion position. + +* The :command:`list(SORT)` command gained options to control the + comparison operation used to order the entries. + +* The :command:`math` command gained options for hexadecimal. + +* The :command:`target_link_directories` command was created to + specify link directories for targets and their dependents. + +* The :command:`target_link_options` command was created to + specify link options for targets and their dependents. + +* The :command:`target_link_libraries` command may now be called + to modify targets created outside the current directory. + See policy :policy:`CMP0079`. + +Variables +--------- + +* A :variable:`CMAKE_AUTOGEN_VERBOSE` variable was added to optionally + increase the verbosity of :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTOUIC` + and :prop_tgt:`AUTORCC` from within CMake project code. + +* A :variable:`CMAKE_VS_GLOBALS` variable was added to initialize + :prop_tgt:`VS_GLOBAL_<variable>` target properties on targets as + they are created. + +Properties +---------- + +* The :prop_tgt:`DEPLOYMENT_ADDITIONAL_FILES` target property was + added to tell the :generator:`Visual Studio 9 2008` generator + to specify additional files for deployment to WinCE devices + for remote debugging. + +* The :prop_tgt:`INTERFACE_LINK_DEPENDS` target property was created + to specify transitive link dependencies on files. + +* The :prop_tgt:`LINK_DEPENDS` target property learned to support + :manual:`generator expressions <cmake-generator-expressions(7)>`. + +* :prop_tgt:`LINK_DIRECTORIES` and :prop_tgt:`INTERFACE_LINK_DIRECTORIES` + target properties were added to collect link directories for a target + and its dependents. Use the :command:`target_link_directories` command + to set them. + +* :prop_tgt:`LINK_OPTIONS` and :prop_tgt:`INTERFACE_LINK_OPTIONS` target + properties were added to collect link options for a target and its + dependents. Use the :command:`target_link_options` command to set them. + +* A :prop_dir:`LINK_OPTIONS` directory property was added to collect + link options for targets created under the current directory. + Use the :command:`add_link_options` command to set it. + +* A :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property was created + to specify archiver options to use when creating static libraries. + +* A :prop_tgt:`VS_DEBUGGER_COMMAND_ARGUMENTS` target property was created to + set the debugging command line arguments with + :ref:`Visual Studio Generators` for VS 2010 and above. + +* A :prop_tgt:`VS_DEBUGGER_ENVIRONMENT` target property was created to + set the debugging environment with + :ref:`Visual Studio Generators` for VS 2010 and above. + +* The :prop_tgt:`VS_DEBUGGER_COMMAND` and + :prop_tgt:`VS_DEBUGGER_WORKING_DIRECTORY` target properties + now support generator expressions. + +Modules +------- + +* The :module:`FindBoost` module gained a ``Boost_ARCHITECTURE`` option + to specify a Boost architecture-specific library filename fragment. + +* The :module:`FindCURL` module learned to find debug and release variants + separately. + +* The :module:`FindMatlab` module gained new components ``ENGINE_LIBRARY`` and + ``DATAARRAY_LIBRARY`` to request finding the Matlab C++ Engine and DataArray + libraries respectively. + +* The :module:`FindMatlab` module now explicitly exports mexFunction in Visual + Studio. + +* The :module:`FindMatlab` module gained a new ``MCC_COMPILER`` + component to request finding the Matlab Compiler add-on. + +* The :module:`FindPkgConfig` module gained an option to create imported + targets in global scope. + +* The :module:`FindPkgConfig` module gained support for ``<`` and ``>`` + operators for version checks in addition to the already supported + operators ``>=``, ``<=``, and ``=``. + +* Modules :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython` + gain capability to control order of resource lookup on macOS (Framework) and + Windows (Registry). + +* The :module:`FindSubversion` module ``Subversion_WC_INFO`` command + gained an ``IGNORE_SVN_FAILURE`` option to suppress failures, + e.g. when the source tree is not under Subversion control. + +* The :module:`UseSWIG` module learned to manage target property + :prop_tgt:`INCLUDE_DIRECTORIES` for ``SWIG`` compilation. + +CTest +----- + +* :manual:`ctest(1)` gained a ``--progress`` option to enable a live + test progress summary when output goes to a terminal. + +CPack +----- + +* The :cpack_gen:`CPack DEB Generator` learned to split debug symbols into + a corresponding .ddeb package when ``CPACK_DEBIAN_DEBUGINFO_PACKAGE`` is + set. + +* The :cpack_gen:`CPack DEB Generator` learned to honor the ``SOURCE_DATE_EPOCH`` + environment variable when packaging files. This is useful for generating + reproducible packages. + +* CPack gained a new :cpack_gen:`CPack External Generator` which is used to + export the CPack metadata in a format that other software can understand. The + intention of this generator is to allow external packaging software to take + advantage of CPack's features when it may not be possible to use CPack for + the entire packaging process. + +Deprecated and Removed Features +=============================== + +* An explicit deprecation diagnostic was added for policies ``CMP0055`` + through ``CMP0063`` (``CMP0054`` and below were already deprecated). + The :manual:`cmake-policies(7)` manual explains that the OLD behaviors + of all policies are deprecated and that projects should port to the + NEW behaviors. + +Other Changes +============= + +* The precompiled binaries provided on ``cmake.org`` now include + qthelp-format documentation. + +* The :command:`option` command now honors an existing normal variable + of the same name and does nothing instead of possibly creating a cache + entry (or setting its type) and removing the normal variable. + See policy :policy:`CMP0077`. + +* The :ref:`Makefile Generators` learned to remove custom command and + custom target byproducts during ``make clean``. + +* The :command:`target_sources` command now interprets relative source file + paths as relative to the current source directory. This simplifies + incrementally building up a target's sources from subdirectories. The + :policy:`CMP0076` policy was added to provide backward compatibility with + the old behavior where required. + +* The :module:`BundleUtilities` module may no longer be included at configure + time. This was always a bug anyway. See policy :policy:`CMP0080`. + +* The :module:`UseSWIG` module has changed strategy for target naming. + See policy :policy:`CMP0078`. + +* The :prop_tgt:`LINK_DIRECTORIES` target property now expects absolute paths. + See policy :policy:`CMP0081`. + +* The CPack generators have been moved into their own separate section + in the documentation, rather than having the documentation in their + internal implementation modules. + These internal implementation modules are also no longer available + to scripts that may have been incorrectly including them, because + they should never have been available in the first place. + +Updates +======= + +Changes made since CMake 3.13.0 include the following. + +3.13.2 +------ + +* CMake 3.13.0 included a change to pass compiler implicit include + directories to the ``moc`` tool for :prop_tgt:`AUTOMOC`. This has + been reverted due to regressing existing builds and will need + further investigation before being re-introduced in a later release. + +3.13.3 +------ + +* The :generator:`Visual Studio 15 2017` generator has been fixed to work + when VS 2019 is installed. + +* CMake now checks that at least one of the source or binary directory + is specified when running CMake and issues an error if both are missing. + This has always been a documented requirement, but the implementation + previously accidentally accepted cases in which neither are specified + so long as some other argument is given, and silently used the current + working directory as the source and build tree. + +3.13.4 +------ + +* The error added by 3.13.3 in cases that neither a source or binary + directory is specified has been downgraded to a warning. While this + was never intended, documented, nor supported behavior, some projects + relied on it. The error has been downgraded to a warning for the + remainder of the 3.13.x release series to allow a transition period, + but it may become a fatal error again in a later release. Scripts + relying on the old behavior can be trivially fixed by specifying + the path to the source tree (even if just ``.``) explicitly and + continue to work with all versions of CMake. + +3.13.5 +------ + +* In CMake 3.13.0 through 3.13.4, calling :command:`target_link_libraries` + to add ``PRIVATE`` dependencies to a static library created in another + directory (under policy :policy:`CMP0079` ``NEW`` behavior) would + incorrectly propagate usage requirements of those dependencies to + dependents that link the static library. This has been fixed. diff --git a/Help/release/3.14.rst b/Help/release/3.14.rst new file mode 100644 index 000000000..8a9738c84 --- /dev/null +++ b/Help/release/3.14.rst @@ -0,0 +1,438 @@ +CMake 3.14 Release Notes +************************ + +.. only:: html + + .. contents:: + +Changes made since CMake 3.13 include the following. + +New Features +============ + +Generators +---------- + +* The :generator:`Visual Studio 16 2019` generator was added. This is + experimental and based on "Visual Studio 2019 Preview 4" because this + version of VS has not been released. + + The VS 2019 generator differs from generators for earlier versions + in that it does not provide variants that specify the target platform + in the generator name. Instead :variable:`CMAKE_GENERATOR_PLATFORM` + must be used, e.g. through the ``-A`` command-line option. Furthermore, + the default target platform (architecture) is now based on the *host* + platform. The VS host toolset selection is now based on the host + architecture as well. + +* The :generator:`Green Hills MULTI` generator has been updated: + + * Now supports :ref:`Object Libraries`. + + * Now warns on unsupported project types such as shared libraries. + + * Now generates a top-level ``<PROJECT-NAME>.top.gpj`` for each directory + calling the :command:`project` command. The top-level project file + ``default.gpj`` is no longer created. + + * Now honors target renaming and destination output control properties + such as :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` and :prop_tgt:`OUTPUT_NAME`. + This also fixes support for installation rules generated by + :command:`install`. + + * Now honors source file properties :prop_sf:`INCLUDE_DIRECTORIES`, + :prop_sf:`COMPILE_DEFINITIONS`, and :prop_sf:`COMPILE_OPTIONS`. + + * Now supports Dynamic Download Integrity Applications which did not include + Integrate Files via :prop_tgt:`GHS_INTEGRITY_APP` and setting a target + link flag of ``-dynamic``. + + * The contents of project files now sorts sources groups and files by name. + Set the :prop_tgt:`GHS_NO_SOURCE_GROUP_FILE` target property to ``ON`` to + generate a single project file for the target instead of a project file for + each source group. Set the :variable:`CMAKE_GHS_NO_SOURCE_GROUP_FILE` + variable to enable this for all targets. + +File-Based API +-------------- + +* A file-based api for clients to get semantic buildsystem information + has been added. See the :manual:`cmake-file-api(7)` manual. + This is intended to replace the :manual:`cmake-server(7)` mode for IDEs. + +Platforms +--------- + +* CMake now supports :ref:`Cross Compiling for iOS, tvOS, or watchOS` + using simple toolchain files. + +Command-Line +------------ + +* The :manual:`cmake(1)` :ref:`Build Tool Mode <Build Tool Mode>` + (``cmake --build``) gained ``--verbose`` and ``-v`` options to + specify verbose build output. Some generators such as Xcode don't + support this option currently. + +* The :manual:`cmake(1)` ``-E compare_files`` command learned a new + ``--ignore-eol`` option to specify that end-of-line differences + (e.g. LF vs CRLF) should be ignored when comparing files. + +* The :manual:`cmake-gui(1)` dialog gained new ``-S`` and ``-B`` arguments to + explicitly specify source and build directories. + +Commands +-------- + +* The :command:`file` command learned a new sub-command, ``CREATE_LINK``, + which can be used to create hard or symbolic links. + +* The :command:`file` command learned a new sub-command, ``READ_SYMLINK``, + which can be used to determine the path that a symlink points to. + +* The :command:`file` command gained a ``SIZE`` mode to get the size + of a file on disk. + +* The :command:`find_package` command learned to optionally resolve + symbolic links in the paths to package configuration files. + See the :variable:`CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS` variable. + +* The :command:`get_filename_component` command gained new + ``LAST_EXT`` and ``NAME_WLE`` variants to work with the + extension after the last ``.`` in the name. + +* The :command:`if` command gained support for checking if cache variables + are defined with the ``DEFINED CACHE{VAR}`` syntax. + +* The :command:`install(CODE)` and :command:`install(SCRIPT)` commands + learned to support generator expressions. See policy :policy:`CMP0087`. + +* The :command:`install(TARGETS)` command learned how to install to an + appropriate default directory for a given target type, based on + variables from the :module:`GNUInstallDirs` module and built-in defaults, + in lieu of a ``DESTINATION`` argument. + +* The :command:`install(FILES)` and :command:`install(DIRECTORY)` commands + learned a new set of parameters for installing files as a file type, + setting the destination based on the appropriate variables from + :module:`GNUInstallDirs` and built-in defaults, in lieu of a + ``DESTINATION`` argument. + +* The :command:`list` operations ``REMOVE_ITEM``, ``REMOVE_DUPLICATES``, + ``SORT``, ``REVERSE``, and ``FILTER`` all now accept a non-existent variable + as the list since these operations on empty lists is also the empty list. + +* The :command:`list` operation ``REMOVE_AT`` now indicates that the given + indices are invalid for a non-existent variable or empty list. + +* The :command:`try_compile` and :command:`try_run` commands gained a new + ``LINK_OPTIONS`` option. + +Variables +--------- + +* A :variable:`CMAKE_BUILD_RPATH_USE_ORIGIN` variable and corresponding + :prop_tgt:`BUILD_RPATH_USE_ORIGIN` target property were added to + enable use of relative runtime paths (RPATHs). This helps achieving + relocatable and reproducible builds that are invariant of the build + directory. + +* A :variable:`CMAKE_VS_PLATFORM_NAME_DEFAULT` variable was added for + :ref:`Visual Studio Generators` to report their default platform used + when :variable:`CMAKE_GENERATOR_PLATFORM` is not set explicitly. + +Properties +---------- + +* A :prop_gbl:`CMAKE_ROLE` global property was added to allow scripts to + determine whether they're running in project mode, script mode, + find-package mode, CTest, or CPack. + +* The :prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` target property is now supported + on shared library, module library, and executable targets. Previously it was + only honored on static libraries. + +* The :prop_tgt:`EXCLUDE_FROM_ALL` target property was created to override + the setting of its directory. A target will now be built as part of "all" + if its :prop_tgt:`EXCLUDE_FROM_ALL` property is set to ``OFF``, even if its + containing directory is marked as :prop_dir:`EXCLUDE_FROM_ALL`. + +* :prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE` target property gains the + support of :manual:`generator expressions <cmake-generator-expressions(7)>`. + +Modules +------- + +* The family of modules to check capabilities (like + :module:`CheckCSourceCompiles`) gain capability to manage ``LINK_OPTIONS``. + +* A :module:`CheckFortranSourceRuns` module was added to provide a + :command:`check_fortran_source_runs` command to check if a Fortran + source snippet compiles and runs. + +* The :module:`CMakePackageConfigHelpers` module's + :command:`write_basic_package_version_file` command gained a new + ``ARCH_INDEPENDENT`` option for supporting architecture-independent + packages. + +* The :module:`ExternalProject` module :command:`ExternalProject_Add` command + gained ``LOG_DIR`` and ``LOG_MERGED_STDOUTERR`` options to control logging. + +* The :module:`ExternalProject` module :command:`ExternalProject_Add` command + gained ``LOG_PATCH`` to optionally log the patch step. + +* The :module:`ExternalProject` module :command:`ExternalProject_Add` command + learned to apply ``SOURCE_SUBDIR`` when ``BUILD_IN_SOURCE`` is also used. + The ``BUILD_COMMAND`` is run in the given ``SOURCE_SUBDIR`` of the + ``SOURCE_DIR``. + +* The :module:`FetchContent` module gained a new + :command:`FetchContent_MakeAvailable` command. It accepts a list of + dependency names, which it then iterates over, populating and adding + each one to the main build using the canonical pattern. This + significantly reduces the amount of boilerplate needed in a project. + +* The :module:`FindBISON` module's ``BISON_TARGET`` command now runs ``bison`` + with :variable:`CMAKE_CURRENT_BINARY_DIR` as the working directory. + See policy :policy:`CMP0088`. + +* The :module:`FindCURL` module gained support for requesting + protocols as package components. + +* The :module:`FindFontconfig` module was added to find `fontconfig`_. + +* The :module:`FindGDAL` module now provides imported targets. + +* The :module:`FindGIF` module now provides imported targets. + +* The :module:`FindGit` module now provides an imported target for the + Git executable. + +* The :module:`FindIce` module learned to find ``slice2confluence`` + and ``slice2matlab``. + +* The :module:`FindLibinput` module was added to find `libinput`_. + +* The :module:`FindLibLZMA` module now provides imported targets. + +* The :module:`FindMatlab` module gained new options ``R2017b`` and + ``R2018a`` to specify the MEX API version to use; these options + mirror the new options to the ``mex`` command in MATLAB R2018a. + The option ``MX_LIBRARY`` is no longer needed. + +* The :module:`FindPostgreSQL` module now provides imported targets. + +* The :module:`FindPython`, :module:`FindPython2`, and :module:`FindPython3` + modules gained support for ``NumPy`` component. + +* The :module:`FindPython2`, :module:`FindPython3`, and :module:`FindPython` + modules now support running in script mode by skipping the creation of + imported targets and helper functions. + +* The :module:`FindSQLite3` module was added to find the SQLite v3.x library. + +* The :module:`FindX11` had the following variables renamed in order to match + their library names rather than header names. The old variables are provided + for compatibility: + + - ``X11_Xxf86misc_INCLUDE_PATH`` instead of ``X11_xf86misc_INCLUDE_PATH`` + - ``X11_Xxf86misc_LIB`` instead of ``X11_xf86misc_LIB`` + - ``X11_Xxf86misc_FOUND`` instead of ``X11_xf86misc_FOUND`` + - ``X11_Xxf86vm_INCLUDE_PATH`` instead of ``X11_xf86vmode_INCLUDE_PATH`` + - ``X11_Xxf86vm_LIB`` instead of ``X11_xf86vmode_LIB`` + - ``X11_Xxf86vm_FOUND`` instead of ``X11_xf86vmode_FOUND`` + - ``X11_xkbfile_INCLUDE_PATH`` instead of ``X11_Xkbfile_INCLUDE_PATH`` + - ``X11_xkbfile_LIB`` instead of ``X11_Xkbfile_LIB`` + - ``X11_xkbfile_FOUND`` instead of ``X11_Xkbfile_FOUND`` + - ``X11_Xtst_INCLUDE_PATH`` instead of ``X11_XTest_INCLUDE_PATH`` + - ``X11_Xtst_LIB`` instead of ``X11_XTest_LIB`` + - ``X11_Xtst_FOUND`` instead of ``X11_XTest_FOUND`` + - ``X11_Xss_INCLUDE_PATH`` instead of ``X11_Xscreensaver_INCLUDE_PATH`` + - ``X11_Xss_LIB`` instead of ``X11_Xscreensaver_LIB`` + - ``X11_Xss_FOUND`` instead of ``X11_Xscreensaver_FOUND`` + + The following variables are deprecated completely since they were + essentially duplicates: + + - ``X11_Xinput_INCLUDE_PATH`` (use ``X11_Xi_INCLUDE_PATH``) + - ``X11_Xinput_LIB`` (use ``X11_Xi_LIB``) + - ``X11_Xinput_FOUND`` (use ``X11_Xi_FOUND``) + +* The :module:`FindX11` now provides ``X11_Xext_INCLUDE_PATH``. + +* The :module:`FindX11` now provides imported targets. + +* The :module:`UseSWIG` module learned to pass ``-module <module_name>`` to + the ``SWIG`` compiler if the file property ``SWIG_MODULE_NAME`` is defined. + See policy :policy:`CMP0086`. + +* The :module:`UseSWIG` module gained an option to specify + ``SWIG`` source file extensions. + +.. _`fontconfig`: https://www.freedesktop.org/wiki/Software/fontconfig/ +.. _`libinput`: https://www.freedesktop.org/wiki/Software/libinput/ + +Generator Expressions +--------------------- + +* The ``$<Fortran_COMPILER_ID:...>`` and ``$<Fortran_COMPILER_VERSION:...>`` + :manual:`generator expressions <cmake-generator-expressions(7)>` were added. + +* The ``$<IN_LIST:...>`` generator expression now correctly handles an + empty argument. See :policy:`CMP0085` for details. + +Autogen +------- + +* The :prop_tgt:`AUTOMOC_EXECUTABLE`, :prop_tgt:`AUTORCC_EXECUTABLE`, and + :prop_tgt:`AUTOUIC_EXECUTABLE` target properties were added. They all + take a path to an executable and force automoc/autorcc/autouic to use + this executable. + + Setting these will also prevent the configure time testing for these + executables. This is mainly useful when you build these tools yourself. + +* The new variables :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET`, + :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET_NAME`, + :variable:`CMAKE_GLOBAL_AUTORCC_TARGET` and + :variable:`CMAKE_GLOBAL_AUTORCC_TARGET_NAME` control the generation + of global ``autogen`` and ``autorcc`` targets. + +* A new :variable:`CMAKE_AUTOGEN_ORIGIN_DEPENDS` variable and + :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS` target property may be set to enable or + disable forwarding of the origin target dependencies to the corresponding + ``_autogen`` target. + +CTest +----- + +* :manual:`ctest(1)` gained a ``--show-only=json-v1`` option to show the + list of tests in a machine-readable JSON format. + See the :ref:`Show as JSON Object Model` section of the manual. + +* The :command:`ctest_submit` command learned a new ``Done`` part that can be used + to inform CDash that a build is complete and that no more parts will be uploaded. + +* CTest learned to accept the dashboard server submission URL from a single + variable. See the ``SubmitURL`` setting in :manual:`ctest(1)`, + the :variable:`CTEST_SUBMIT_URL` variable, and the ``SUBMIT_URL`` + argument of the :command:`ctest_submit` command. + +Deprecated and Removed Features +=============================== + +* An explicit deprecation diagnostic was added for policies ``CMP0064`` + and ``CMP0065`` (``CMP0063`` and below were already deprecated). + The :manual:`cmake-policies(7)` manual explains that the OLD behaviors + of all policies are deprecated and that projects should port to the + NEW behaviors. + +* The :generator:`Xcode` generator deprecated support for Xcode + versions prior to Xcode 5. Support for those will be dropped in a + future version of CMake. + +* The :module:`FindQt` module is no longer used by the :command:`find_package` + command as a find module. This allows the Qt Project upstream to optionally + provide its own ``QtConfig.cmake`` package configuration file and have + applications use it via ``find_package(Qt)`` rather than + ``find_package(Qt CONFIG)``. See policy :policy:`CMP0084`. + +* Support for running CMake on Windows XP and Windows Vista has been dropped. + The precompiled Windows binaries provided on ``cmake.org`` now require + Windows 7 or higher. + +* CTest no longer supports submissions via ``ftp``, ``scp``, ``cp``, and + ``xmlrpc``. CDash is the only maintained testing dashboard for CTest, + and it only supports submissions over ``http`` and ``https``. + +Other Changes +============= + +* Object library linking has been fixed to propagate private link libraries + of object libraries to consuming targets. + +* Install rules under :command:`add_subdirectory` now interleave with those in + the calling directory. See policy :policy:`CMP0082` for details. + +* CMake now imposes a maximum recursion limit to prevent a stack overflow on + scripts that recurse infinitely. The limit can be adjusted at runtime with + :variable:`CMAKE_MAXIMUM_RECURSION_DEPTH`. + +* When using cppcheck via the :variable:`CMAKE_<LANG>_CPPCHECK` variable + or :prop_tgt:`<LANG>_CPPCHECK` property, the build will now fail if + ``cppcheck`` returns non-zero as configured by its command-line options. + +* Required link options to manage Position Independent Executable are now + added when :prop_tgt:`POSITION_INDEPENDENT_CODE` is set. The project is + responsible for using the :module:`CheckPIESupported` module to check for + ``PIE`` support to ensure that the :prop_tgt:`POSITION_INDEPENDENT_CODE` + target property will be honored at link time for executables. This behavior + is controlled by policy :policy:`CMP0083`. + +* :ref:`Visual Studio Generators` for VS 2010 and above learned + to support the ``VS_DEBUGGER_*`` properties on targets created + via :command:`add_custom_target`. + +* The :module:`CPack` module no longer defaults to the ``paxr`` value in the + :variable:`CPACK_DEBIAN_ARCHIVE_TYPE` variable, because ``dpkg`` has + never supported the PAX tar format. The ``paxr`` value will be mapped + to ``gnutar`` and a deprecation message emitted. + +* CMake no longer issues a warning if a target listed in an + :command:`install(TARGETS)` command has its :prop_tgt:`EXCLUDE_FROM_ALL` + property set to true. + +Updates +======= + +Changes made since CMake 3.14.0 include the following. + +3.14.1 +------ + +* The :module:`FindFontconfig` module added by 3.14.0 accidentally + used uppercase ``FONTCONFIG_*`` variable names that do not match + our conventions. 3.14.1 revises the module to use ``Fontconfig_*`` + variable names. This is incompatible with 3.14.0 but since the + module is new in the 3.14 series usage should not yet be widespread. + +3.14.3 +------ + +* The :variable:`CMAKE_VS_PLATFORM_NAME_DEFAULT` variable was added + to help toolchain files work with the :generator:`Visual Studio 16 2019` + generator where the default platform now depends on the host platform. + +3.14.4 +------ + +* In CMake 3.14.0 through 3.14.3, calling :command:`target_link_libraries` + to add ``PRIVATE`` dependencies to a static library created in another + directory (under policy :policy:`CMP0079` ``NEW`` behavior) would + incorrectly propagate usage requirements of those dependencies to + dependents that link the static library. This has been fixed. + The bug also existed in 3.13.0 through 3.13.4 and is fixed in 3.13.5. + +3.14.5 +------ + +* Entries of the ``CPATH`` environment variable are no longer excluded + from explicit use via :command:`include_directories` and + :command:`target_include_directories` as they were in CMake 3.14.0 + through 3.14.4. + +3.14.6 +------ + +* In CMake 3.14.0 through 3.14.5, the :module:`FindBISON` module + policy :policy:`CMP0088` ``NEW`` behavior accidentally interpreted + a relative path to the ``.y`` input as relative to the build tree + directory instead of the source tree directory. This has been fixed. + +3.14.7 +------ + +* In CMake 3.14.0 through 3.14.6, the :prop_dir:`EXCLUDE_FROM_ALL` + directory property was regressed from pre-3.14 behavior and caused + targets within the directory to be excluded even from its own "all". + This has been fixed. diff --git a/Help/release/3.15.rst b/Help/release/3.15.rst new file mode 100644 index 000000000..957e6e958 --- /dev/null +++ b/Help/release/3.15.rst @@ -0,0 +1,387 @@ +CMake 3.15 Release Notes +************************ + +.. only:: html + + .. contents:: + +Changes made since CMake 3.14 include the following. + +New Features +============ + +Generators +---------- + +* The :generator:`Xcode` generator now supports per-target schemes. + See the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable and + :prop_tgt:`XCODE_GENERATE_SCHEME` target property. + +* The :generator:`Green Hills MULTI` generator has been updated: + + * It now supports the :command:`add_custom_command` and + :command:`add_custom_target` commands. + + * It is now available on Linux. + +Languages +--------- + +* Preliminary support for the ``Swift`` language was added to the + :generator:`Ninja` generator: + + * Use the :envvar:`SWIFTC` environment variable to specify a compiler. + + * The :prop_tgt:`Swift_DEPENDENCIES_FILE` target property and + :prop_sf:`Swift_DEPENDENCIES_FILE` source file property were added + to customize dependency files. + + * The :prop_tgt:`Swift_MODULE_NAME` target property was added to + customize the Swift module name. + + * The :prop_sf:`Swift_DIAGNOSTICS_FILE` source property was added to + indicate where to write the serialised Swift diagnostics. + + The Swift support is experimental, not considered stable, and may change + in future releases of CMake. + +Compilers +--------- + +* The ``Clang`` compiler variant on Windows that targets the MSVC ABI + but has a GNU-like command line is now supported. + +* Support for the Clang-based ARM compiler was added with compiler id + ``ARMClang``. + +* Support was added for the IAR compiler architectures Renesas RX, + RL78, RH850 and Texas Instruments MSP430. + +* Support was added for the IAR compilers built for Linux (IAR BuildLx). + +Command-Line +------------ + +* The :envvar:`CMAKE_GENERATOR` environment variable was added + to specify a default generator to use when :manual:`cmake(1)` is + run without a ``-G`` option. Additionally, environment variables + :envvar:`CMAKE_GENERATOR_PLATFORM`, :envvar:`CMAKE_GENERATOR_TOOLSET`, + and :envvar:`CMAKE_GENERATOR_INSTANCE` were created to configure + the generator. + +* The :manual:`cmake(1)` ``--build`` tool ``--target`` parameter gained support + for multiple targets, e.g. ``cmake --build . --target Library1 Library2``. + It now also has a short form ``-t`` alias, e.g. + ``cmake --build . -t Library1 Library2``. + +* The :manual:`cmake(1)` command gained a new ``--install`` option. + This may be used after building a project to run installation without + using the generated build system or the native build tool. + +* The :manual:`cmake(1)` command learned a new CLI option ``--loglevel``. + +* The :manual:`cmake(1)` ``-E remove_directory`` command-line tool learned + to support removing multiple directories. + +* The :manual:`cmake(1)` ``-E tar`` tool has been improved: + + * It now continues adding files to an archive even if some of the files + are not readable. This behavior is more consistent with the + classic ``tar`` tool. + + * It now parses all flags, and if an invalid flag was provided, a + warning is issued. + + * It now displays an error if no action flag was specified, along with a + list of possible actions: ``t`` (list), ``c`` (create) or ``x`` (extract). + + * It now supports extracting (``-x``) or listing (``-t``) only specific + files or directories. + + * It now supports Zstandard compression with a ``--zstd`` option. + Zstandard was designed to give a compression ratio comparable to that + of the DEFLATE (zip) algorithm, but faster, especially for decompression. + +Commands +-------- + +* The :command:`add_custom_command` and :command:`add_custom_target` commands + gained a new ``JOB_POOL`` option that works with the :generator:`Ninja` + generator to set the pool variable on the build statement. + +* The :command:`add_library` command ``ALIAS`` option learned to support + import libraries of the ``UNKNOWN`` type. + +* The :command:`cmake_parse_arguments` command gained an additional + ``<prefix>_KEYWORDS_MISSING_VALUES`` output variable to report + keyword arguments that were given by the caller with no values. + +* The :command:`execute_process` command gained a ``COMMAND_ECHO`` option + and supporting :variable:`CMAKE_EXECUTE_PROCESS_COMMAND_ECHO` variable + to enable echoing of the command-line string before execution. + +* The :command:`file(INSTALL)` command learned a new argument, + ``FOLLOW_SYMLINK_CHAIN``, which can be used to recursively resolve and + install symlinks. + +* :command:`list` learned new sub-commands: + ``PREPEND``, ``POP_FRONT`` and ``POP_BACK``. + +* The :command:`message` command learned new types: + ``NOTICE``, ``VERBOSE``, ``DEBUG`` and ``TRACE``. + +* The :command:`string` learned a new sub-command ``REPEAT``. + +Variables +--------- + +* The :variable:`CMAKE_CROSSCOMPILING_EMULATOR` variable and corresponding + :prop_tgt:`CROSSCOMPILING_EMULATOR` target property learned to support + arguments to the emulator. + +* The :variable:`CMAKE_FIND_PACKAGE_PREFER_CONFIG` variable was added to tell + :command:`find_package` calls to look for a package configuration + file first even if a find module is available. + +* The :variable:`CMAKE_FRAMEWORK` variable was added to initialize the + :prop_tgt:`FRAMEWORK` property on all targets. + +* The :variable:`CMAKE_VS_JUST_MY_CODE_DEBUGGING` variable and + :prop_tgt:`VS_JUST_MY_CODE_DEBUGGING` target property were added to + enable the Just My Code feature of the Visual Studio Debugger when + compiling with MSVC cl 19.05 and higher. + +* The :variable:`CMAKE_MSVC_RUNTIME_LIBRARY` variable and + :prop_tgt:`MSVC_RUNTIME_LIBRARY` target property were introduced to + select the runtime library used by compilers targeting the MSVC ABI. + See policy :policy:`CMP0091`. + +* The :variable:`CMAKE_PROJECT_INCLUDE` and + :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` variables were added to allow + injection of custom code at the sites of :command:`project` calls + without knowing the project name a priori. + +Properties +---------- + +* The :prop_tgt:`ADDITIONAL_CLEAN_FILES` target property and + :prop_dir:`ADDITIONAL_CLEAN_FILES` directory property were added. + They allow to register additional files that should be removed during + the clean stage. + +* The :prop_tgt:`PUBLIC_HEADER` and :prop_tgt:`PRIVATE_HEADER` properties + may now be set on :ref:`Interface Libraries`. The headers specified by those + properties can be installed using the :command:`install(TARGETS)` command by + passing the ``PUBLIC_HEADER`` and ``PRIVATE_HEADER`` arguments respectively. + +* The :prop_tgt:`VS_PACKAGE_REFERENCES` target property was added to + tell :ref:`Visual Studio Generators` to add references to ``nuget`` + packages. + +* The :prop_tgt:`VS_PROJECT_IMPORT` target property was added to allow + managed Visual Studio project files to import external ``.props`` files. + +* The :prop_tgt:`VS_NO_SOLUTION_DEPLOY` target property was added to + tell :ref:`Visual Studio Generators` whether to deploy an artifact + to the WinCE or Windows Phone target device. + +Modules +------- + +* The :module:`FindBoost` module was reworked to expose a more consistent + user experience between its "Config" and "Module" modes and with other + find modules in general. + + * A new imported target ``Boost::headers`` is now defined (same + as ``Boost::boost``). + + * New output variables ``Boost_VERSION_MACRO``, + ``Boost_VERSION_MAJOR``, ``Boost_VERSION_MINOR``, + ``Boost_VERSION_PATCH``, and ``Boost_VERSION_COUNT`` + were added. + + * The ``QUIET`` argument passed to :command:`find_package` is no + longer ignored in config mode. Note that the CMake package shipped with + Boost ``1.70.0`` ignores the ``QUIET`` argument passed to + :command:`find_package`. This is fixed in the next Boost release. + + * The input switch ``Boost_DETAILED_FAILURE_MSG`` was removed. + + * ``Boost_VERSION`` now reports the version in ``x.y.z`` + format in module mode. See policy :policy:`CMP0093`. + +* The :module:`FindCups` module now provides imported targets. + +* The :module:`FindEnvModules` module was added to use Lua- and TCL-based + environment modules in :ref:`CTest Scripts <CTest Script>`. + +* The :module:`FindGLEW` module now provides an interface more consistent + with what upstream GLEW provides in its own CMake package files. + +* The :module:`FindPkgConfig` now populates :prop_tgt:`INTERFACE_LINK_OPTIONS` + property of imported targets with other (non-library) linker flags. + +* The :module:`FindPostgreSQL` module learned to find debug and release + variants separately. + +* Modules :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython` + gained additional lookup strategies and controls, and a new default. + See policy :policy:`CMP0094`. + +* Modules :module:`FindPython`, :module:`FindPython2` and :module:`FindPython3` + gain a new target (respectively ``Python::Module``, ``Python2::Module`` + and ``Python3::Module``) which can be used to develop Python modules. + +* Modules :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython` + gain capability to control how virtual environments are handled. + +* The :module:`UseSWIG` module learned to manage alternate library names + by passing ``-interface <library_name>`` for ``python`` language or + ``-dllimport <library_name>`` for ``CSharp`` language to the ``SWIG`` + compiler. + +Generator Expressions +--------------------- + +* The :manual:`generator expressions <cmake-generator-expressions(7)>` + ``C_COMPILER_ID``, ``CXX_COMPILER_ID``, ``CUDA_COMPILER_ID``, + ``Fortran_COMPILER_ID``, ``COMPILE_LANGUAGE``, ``COMPILE_LANG_AND_ID``, and + ``PLATFORM_ID`` learned to support matching one value from a comma-separated + list. + +* The ``$<CUDA_COMPILER_ID:...>`` and ``$<CUDA_COMPILER_VERSION:...>`` + :manual:`generator expressions <cmake-generator-expressions(7)>` were added. + +* The ``$<COMPILE_LANG_AND_ID:...>`` generator expression was introduced to + allow specification of compile options for target files based on the + :variable:`CMAKE_<LANG>_COMPILER_ID` and :prop_sf:`LANGUAGE` of + each source file. + +* A ``$<FILTER:list,INCLUDE|EXCLUDE,regex>`` + :manual:`generator expression <cmake-generator-expressions(7)>` + has been added. + +* A ``$<REMOVE_DUPLICATES:list>`` + :manual:`generator expression <cmake-generator-expressions(7)>` + has been added. + +* The ``$<SHELL_PATH:...>`` :manual:`generator expression + <cmake-generator-expressions(7)>` gained support for a list of paths. + +* New ``$<TARGET_FILE*>`` :manual:`generator expressions + <cmake-generator-expressions(7)>` were added to retrieve the prefix, base + name, and suffix of the file names of various artifacts: + + * ``$<TARGET_FILE_PREFIX:...>`` + * ``$<TARGET_FILE_BASE_NAME:...>`` + * ``$<TARGET_FILE_SUFFIX:...>`` + * ``$<TARGET_LINKER_FILE_PREFIX:...>`` + * ``$<TARGET_LINKER_FILE_BASE_NAME:...>`` + * ``$<TARGET_LINKER_FILE_SUFFIX:...>`` + * ``$<TARGET_PDB_FILE_BASE_NAME:...>`` + +* The ``$<TARGET_OBJECTS:...>`` :manual:`generator expression + <cmake-generator-expressions(7)>` is now supported on ``SHARED``, + ``STATIC``, ``MODULE`` libraries and executables. + +CTest +----- + +* The :command:`ctest_submit` command learned a new option: ``BUILD_ID``. + This can be used to store the ID assigned to this build by CDash to a + variable. + +* The :command:`ctest_update` command learned to honor a new variable: + :variable:`CTEST_UPDATE_VERSION_OVERRIDE`. This can be used to specify + the current version of your source tree rather than using the update + command to discover the current version that is checked out. + +CPack +----- + +* The :cpack_gen:`CPack IFW Generator` gained a new + :variable:`CPACK_IFW_PACKAGE_STYLE_SHEET` variable to customize the + installer stylesheet. + +Deprecated and Removed Features +=============================== + +* The :manual:`cmake-server(7)` mode has been deprecated and will be + removed from a future version of CMake. Please port clients to use + the :manual:`cmake-file-api(7)` instead. + +* The :prop_dir:`ADDITIONAL_MAKE_CLEAN_FILES` directory property is now + deprecated. Use the :prop_dir:`ADDITIONAL_CLEAN_FILES` directory property + instead. + +* The variable :variable:`CMAKE_AUTOMOC_RELAXED_MODE` is considered + deprecated. Support still exists but will be removed in future versions. + +* The :command:`export(PACKAGE)` command now does nothing unless + enabled via :variable:`CMAKE_EXPORT_PACKAGE_REGISTRY`. + See policy :policy:`CMP0090`. + +* The :generator:`Xcode` generator now requires at least Xcode 5. + +* An explicit deprecation diagnostic was added for policy ``CMP0066`` + (``CMP0065`` and below were already deprecated). + The :manual:`cmake-policies(7)` manual explains that the OLD behaviors + of all policies are deprecated and that projects should port to the + NEW behaviors. + +Other Changes +============= + +* CMake learned how to compile C++14 with the IBM AIX XL compiler + and the SunPro compiler and to compile C++20 with the AppleClang compiler. + +* With MSVC-like compilers the value of :variable:`CMAKE_<LANG>_FLAGS` + no longer contains warning flags like ``/W3`` by default. + See policy :policy:`CMP0092`. + +* IBM Clang-based XL compilers that define ``__ibmxl__`` now use the + compiler id ``XLClang`` instead of ``XL``. See policy :policy:`CMP0089`. + +* The :command:`file(REMOVE)` and :command:`file(REMOVE_RECURSE)` commands + were changed to ignore empty arguments with a warning instead of treating + them as a relative path and removing the contents of the current directory. + +Updates +======= + +Changes made since CMake 3.15.0 include the following. + +3.15.1 +------ + +* In CMake 3.15.0 support for the GNU-like ``Clang`` compiler targeting the + MSVC ABI implemented :variable:`CMAKE_CXX_STANDARD` values 98 and 11 using + the corresponding ``-std=`` flags. However, these modes do not work with + the MSVC standard library. Therefore CMake 3.15.1 passes C++14 standard + flags even for C++98 and C++11. This is consistent with MSVC itself which + always runs in a mode aware of C++14. + +* Preliminary Swift support added in 3.15.0 has been updated. + +3.15.2 +------ + +* In CMake 3.15.0 and 3.15.1 the :variable:`CMAKE_FIND_PACKAGE_PREFER_CONFIG` + variable caused the :command:`find_package` command to fail on a missing + package even without the ``REQUIRED`` option. This has been fixed. + +3.15.3 +------ + +* ``CrayPrgEnv`` compiler wrapper support has been updated for the 19.06 + release of the Cray Programming Environment for which the default linking + mode on XC Cray systems is now dynamic instead of static. + +3.15.4 +------ + +* In CMake 3.15.0 through 3.15.3, the :prop_dir:`EXCLUDE_FROM_ALL` + directory property was regressed from pre-3.14 behavior and caused + targets within the directory to be excluded even from its own "all". + This has been fixed. + The bug also existed in 3.14.0 through 3.14.6 and is fixed in 3.14.7. diff --git a/Help/release/3.16.rst b/Help/release/3.16.rst new file mode 100644 index 000000000..0d1cc1ed6 --- /dev/null +++ b/Help/release/3.16.rst @@ -0,0 +1,279 @@ +CMake 3.16 Release Notes +************************ + +.. only:: html + + .. contents:: + +Changes made since CMake 3.15 include the following. + +New Features +============ + +Languages +--------- + +* CMake learned to support the Objective C (``OBJC``) and Objective C++ + (``OBJCXX``) languages. They may be enabled via the :command:`project` + and :command:`enable_language` commands. When ``OBJC`` or ``OBJCXX`` + is enabled, source files with the ``.m`` or ``.mm``, respectively, + will be compiled as Objective C or C++. Otherwise they will be treated + as plain C++ sources as they were before. + +Compilers +--------- + +* The ``Clang`` compiler is now supported on ``Solaris``. + +Platforms +--------- + +* On AIX, executables using the :prop_tgt:`ENABLE_EXPORTS` target property + now produce a linker import file with a ``.imp`` extension in addition + to the executable file. Plugins (created via :command:`add_library` with + the ``MODULE`` option) that use :command:`target_link_libraries` to link + to the executable for its symbols are now linked using the import file. + The :command:`install(TARGETS)` command now installs the import file as + an ``ARCHIVE`` artifact. + +* On AIX, runtime linking is no longer enabled by default. CMake provides + the linker enough information to resolve all symbols up front. + One may manually enable runtime linking for shared libraries and/or + loadable modules by adding ``-Wl,-G`` to their link flags + (e.g. in the :variable:`CMAKE_SHARED_LINKER_FLAGS` or + :variable:`CMAKE_MODULE_LINKER_FLAGS` variable). + One may manually enable runtime linking for executables by adding + ``-Wl,-brtl`` to their link flags (e.g. in the + :variable:`CMAKE_EXE_LINKER_FLAGS` variable). + +Command-Line +------------ + +* :manual:`cmake(1)` ``-E`` now supports ``true`` and ``false`` commands, + which do nothing while returning exit codes of 0 and 1, respectively. + +* :manual:`cmake(1)` gained a ``--trace-redirect=<file>`` command line + option that can be used to redirect ``--trace`` output to a file instead + of ``stderr``. + +* The :manual:`cmake(1)` ``--loglevel`` command line option has been + renamed to ``--log-level`` to make it consistent with the naming of other + command line options. The ``--loglevel`` option is still supported to + preserve backward compatibility. + +Commands +-------- + +* The :command:`add_test` command learned the option ``COMMAND_EXPAND_LISTS`` + which causes lists in the ``COMMAND`` argument to be expanded, including + lists created by generator expressions. + +* The :command:`file` command learned a new sub-command, + ``GET_RUNTIME_DEPENDENCIES``, which allows you to recursively get the list of + libraries linked by an executable or library. This sub-command is intended as + a replacement for :module:`GetPrerequisites`. + +* The :command:`find_file`, :command:`find_library`, :command:`find_path`, + :command:`find_package`, and :command:`find_program` commands have learned to + check the following variables to control the default behavior for groups of + search locations: + + * :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` - Controls the default + behavior of searching the :variable:`<PackageName>_ROOT` variables. + + * :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` - Controls the default + behavior of searching the CMake-specific environment variables. + + * :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH` - Controls the default + behavior of searching the standard system environment variables. + + * :variable:`CMAKE_FIND_USE_CMAKE_PATH` - Controls the default behavior of + searching the CMake-specific cache variables. + + * :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH` - Controls the default + behavior of searching the platform-specific CMake variables. + +* The :command:`find_package` command has learned to check the + :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` variable to control the default + behavior of searching the CMake user package registry and to check the + :variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY` variable to control + the default behavior of searching the CMake system package registry. + +* The :command:`message` command learned indentation control with the new + :variable:`CMAKE_MESSAGE_INDENT` variable. + +* The :command:`target_precompile_headers` command was added to specify + a list of headers to precompile for faster compilation times. + +Variables +--------- + +* The :variable:`CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS` variable has been + introduced to optionally initialize the + :prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` target property. + +* The :variable:`CMAKE_ECLIPSE_RESOURCE_ENCODING` variable was added to + specify the resource encoding for the the :generator:`Eclipse CDT4` extra + generator. + +* The :variable:`CMAKE_UNITY_BUILD` variable was added to initialize the + :prop_tgt:`UNITY_BUILD` target property to tell generators to batch + include source files for faster compilation times. + +Properties +---------- + +* The :prop_tgt:`BUILD_RPATH` and :prop_tgt:`INSTALL_RPATH` target properties + now support :manual:`generator expressions <cmake-generator-expressions(7)>`. + +* The :prop_tgt:`INSTALL_REMOVE_ENVIRONMENT_RPATH` target property was + added to remove compiler-defined ``RPATH`` entries from a target. + This property is initialized by the + :variable:`CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH` variable. + +* The :prop_tgt:`PRECOMPILE_HEADERS` target property was added to specify + a list of headers to precompile for faster compilation times. + Set it using the :command:`target_precompile_headers` command. + +* The :prop_tgt:`UNITY_BUILD` target property was added to tell + generators to batch include source files for faster compilation + times. + +* The :prop_tgt:`VS_CONFIGURATION_TYPE` target property now supports + :manual:`generator expressions <cmake-generator-expressions(7)>`. + +* The :prop_tgt:`VS_DPI_AWARE` target property was added to tell + :ref:`Visual Studio Generators` to set the ``EnableDpiAwareness`` + property in ``.vcxproj`` files. + +* The :prop_tgt:`XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING` target property was + added to tell the :generator:`Xcode` generator to set the value of the + ``Allow debugging when using document Versions Browser`` schema option. + +Modules +------- + +* The :module:`FindDoxygen` module :command:`doxygen_add_docs` command + gained a new ``USE_STAMP_FILE`` option. When this option present, + the custom target created by the command will only re-run Doxygen if + any of the source files have changed since the last successful run. + +* The :module:`FindGnuTLS` module now provides an imported target. + +* The :module:`FindPackageHandleStandardArgs` module + :command:`find_package_handle_standard_args` command gained + a new ``REASON_FAILURE_MESSAGE`` option to specify a message + giving the reason for the failure. + +* The :module:`FindPkgConfig` module :command:`pkg_search_module` macro + now defines a ``<prefix>_MODULE_NAME`` result variable containing the + first matching module name. + +* The :module:`FindPython3` and :module:`FindPython` modules gained + options to control which ``ABIs`` will be searched. + +* The :module:`FindPython3`, :module:`FindPython2`, and :module:`FindPython` + modules now support direct specification of artifacts via cache entries. + +Autogen +------- + +* When using :prop_tgt:`AUTOMOC`, CMake now generates the ``-p`` path prefix + option for ``moc``. This ensures that ``moc`` output files are identical + on different build setups (given, that the headers compiled by ``moc`` are + in an :command:`include directory <target_include_directories>`). + Also it ensures that ``moc`` output files will compile correctly when the + source and/or build directory is a symbolic link. + + The ``moc`` path prefix generation behavior can be configured by setting + the new :variable:`CMAKE_AUTOMOC_PATH_PREFIX` variable and/or + :prop_tgt:`AUTOMOC_PATH_PREFIX` target property. + +CTest +----- + +* :manual:`ctest(1)` now has the ability to schedule tests based on resource + requirements for each test. See :ref:`ctest-resource-allocation` for + details. + +* A new test property, :prop_test:`SKIP_REGULAR_EXPRESSION`, has been added. + This property is similar to :prop_test:`FAIL_REGULAR_EXPRESSION` and + :prop_test:`PASS_REGULAR_EXPRESSION`, but with the same meaning as + :prop_test:`SKIP_RETURN_CODE`. This is useful, for example, in cases where + the user has no control over the return code of the test. For example, in + Catch2, the return value is the number of assertion failed, therefore it is + impossible to use it for :prop_test:`SKIP_RETURN_CODE`. + +CPack +----- + +* :manual:`cpack(1)` learned support for multiple configurations for ``-C`` + option. + +* The :cpack_gen:`CPack DEB Generator` is now able to format generic text + (usually used as the description for multiple CPack generators) according + to the `Debian Policy Manual`_. See the + :variable:`CPACK_PACKAGE_DESCRIPTION_FILE` and + :variable:`CPACK_DEBIAN_<COMPONENT>_DESCRIPTION` variables. + +* The :cpack_gen:`CPack Archive Generator` learned to generate ``.tar.zst`` + packages with Zstandard compression. + +.. _`Debian Policy Manual`: https://www.debian.org/doc/debian-policy/ch-controlfields.html#description + +Deprecated and Removed Features +=============================== + +* An explicit deprecation diagnostic was added for policy ``CMP0067`` + (``CMP0066`` and below were already deprecated). + The :manual:`cmake-policies(7)` manual explains that the OLD behaviors + of all policies are deprecated and that projects should port to the + NEW behaviors. + +* The :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` variable has been + deprecated. Use the :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` variable + instead. + +* The :module:`GetPrerequisites` module has been deprecated, as it has been + superceded by :command:`file(GET_RUNTIME_DEPENDENCIES)`. + +* The ``CPACK_INSTALL_SCRIPT`` variable has been deprecated in favor of the + new, more accurately named :variable:`CPACK_INSTALL_SCRIPTS` variable. + +Other Changes +============= + +* The :manual:`cmake(1)` ``-C <initial-cache>`` option now evaluates the + initial cache script with :variable:`CMAKE_SOURCE_DIR` and + :variable:`CMAKE_BINARY_DIR` set to the top-level source and build trees. + +* The :manual:`cmake(1)` ``-E remove_directory`` command-line tool, + when given the path to a symlink to a directory, now removes just + the symlink. It no longer removes content of the linked directory. + +* The :manual:`ctest(1)` ``--build-makeprogram`` command-line option now + specifies the make program used when configuring a project with the + :generator:`Ninja` generator or the :ref:`Makefile Generators`. + +* The :module:`ExternalProject` module :command:`ExternalProject_Add` command + has been updated so that ``GIT_SUBMODULES ""`` initializes no submodules. + See policy :policy:`CMP0097`. + +* The :module:`FindGTest` module has been updated to recognize + MSVC build trees generated by GTest 1.8.1. + +* The :command:`project` command no longer strips leading zeros in version + components. See policy :policy:`CMP0096`. + +* The Qt Compressed Help file is now named ``CMake.qch``, which no longer + contains the release version in the file name. When CMake is upgraded + in-place, the name and location of this file will remain constant. + Tools such as IDEs, help viewers, etc. should now be able to refer to this + file at a fixed location that remains valid across CMake upgrades. + +* ``RPATH`` entries are properly escaped in the generated CMake scripts + used for installation. See policy :policy:`CMP0095`. + +* When using :variable:`CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS` on Windows the + auto-generated exports are now updated only when the object files + providing the symbols are updated. diff --git a/Help/release/3.2.rst b/Help/release/3.2.rst index 8abb1ca62..992d44b65 100644 --- a/Help/release/3.2.rst +++ b/Help/release/3.2.rst @@ -156,27 +156,27 @@ CTest CPack ----- -* The :module:`CPackRPM` module learned options to set per-component +* The :cpack_gen:`CPack RPM Generator` learned options to set per-component descriptions and summaries. See the :variable:`CPACK_RPM_<component>_PACKAGE_DESCRIPTION` and :variable:`CPACK_RPM_<component>_PACKAGE_SUMMARY` variables. -* The :module:`CPackRPM` module learned options to specify +* The :cpack_gen:`CPack RPM Generator` learned options to specify requirements for pre- and post-install scripts. See the :variable:`CPACK_RPM_PACKAGE_REQUIRES_PRE` and :variable:`CPACK_RPM_PACKAGE_REQUIRES_POST` variables. -* The :module:`CPackRPM` module learned options to specify +* The :cpack_gen:`CPack RPM Generator` learned options to specify requirements for pre- and post-uninstall scripts. See the :variable:`CPACK_RPM_PACKAGE_REQUIRES_PREUN` and :variable:`CPACK_RPM_PACKAGE_REQUIRES_POSTUN` variables. -* The :module:`CPackRPM` module learned a new +* The :cpack_gen:`CPack RPM Generator` learned a new :variable:`CPACK_RPM_<COMPONENT>_PACKAGE_PREFIX` variable to specify a component-specific value to use instead of :variable:`CPACK_PACKAGING_INSTALL_PREFIX`. -* The :module:`CPackRPM` module learned a new +* The :cpack_gen:`CPack RPM Generator` learned a new :variable:`CPACK_RPM_RELOCATION_PATHS` variable to specify multiple relocation prefixes for a single rpm package. diff --git a/Help/release/3.3.rst b/Help/release/3.3.rst index 0beb354ac..6657e8df1 100644 --- a/Help/release/3.3.rst +++ b/Help/release/3.3.rst @@ -169,26 +169,26 @@ CTest CPack ----- -* The :manual:`cpack(1)` ``IFW`` generator and the :module:`CPackIFW` - module learned to support Qt Framework Installer 2.0 tools. +* The :cpack_gen:`CPack IFW Generator` learned to support + Qt Framework Installer 2.0 tools. -* The :module:`CPackDeb` module learned a new +* The :cpack_gen:`CPack DEB Generator` learned a new :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS` variable to specify per-component use of ``dpkg-shlibdeps``. -* The :module:`CPackDeb` module learned a new +* The :cpack_gen:`CPack DEB Generator` learned a new :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS` option to specify per-component dependencies. -* The :module:`CPackRPM` module learned to package symbolic links +* The :cpack_gen:`CPack RPM Generator` learned to package symbolic links more cleanly and now supports directory symlinks with recent ``rpmbuild`` versions. -* The :module:`CPackRPM` module learned a new +* The :cpack_gen:`CPack RPM Generator` learned a new :variable:`CPACK_RPM_ADDITIONAL_MAN_DIRS` variable to specify directories containing man pages for the brp-compress RPM macro. -* The :module:`CPackRPM` module learned a new +* The :cpack_gen:`CPack RPM Generator` learned a new :variable:`CPACK_RPM_<component>_PACKAGE_ARCHITECTURE` variable to specify a component-specific package architecture. diff --git a/Help/release/3.4.rst b/Help/release/3.4.rst index 89c5561d3..943d26716 100644 --- a/Help/release/3.4.rst +++ b/Help/release/3.4.rst @@ -66,7 +66,7 @@ Variables Properties ---------- -* :ref:`Visual Studio Generators` learned to support additonal +* :ref:`Visual Studio Generators` learned to support additional target properties to customize projects for NVIDIA Nsight Tegra Visual Studio Edition: @@ -197,7 +197,7 @@ CTest CPack ----- -* The :module:`CPackDeb` module learned to set package dependencies +* The :cpack_gen:`CPack DEB Generator` learned to set package dependencies per component. See variables: * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_BREAKS` @@ -249,11 +249,11 @@ Other Changes :module:`CheckSymbolExists`, and :module:`FindThreads` modules learned to work in environments where only CXX is enabled. -* The :module:`CPackDeb` module now correctly excludes symlinks during package - checksum calculation. +* The :cpack_gen:`CPack DEB Generator` now correctly excludes symlinks + during package checksum calculation. -* The :module:`CPackDeb` no longer uses fakeroot and system tar program for - packaging. +* The :cpack_gen:`CPack DEB Generator` no longer uses fakeroot and + system tar program for packaging. * The :module:`CPack` module no longer mangles settings with CMake-special characters when they're used as defaults for other settings. The macro diff --git a/Help/release/3.5.rst b/Help/release/3.5.rst index 009eb3c7c..58a5d4eef 100644 --- a/Help/release/3.5.rst +++ b/Help/release/3.5.rst @@ -120,31 +120,33 @@ Platforms CPack ----- -* The :module:`CPackDMG` module learned new variable to specify AppleScript - file run to customize appearance of ``DragNDrop`` installer folder, - including background image setting using supplied PNG or multi-resolution - TIFF file. See the :variable:`CPACK_DMG_DS_STORE_SETUP_SCRIPT` and +* The :cpack_gen:`CPack DragNDrop Generator` learned new variable to + specify AppleScript file run to customize appearance of ``DragNDrop`` + installer folder, including background image setting using supplied + PNG or multi-resolution TIFF file. + See the :variable:`CPACK_DMG_DS_STORE_SETUP_SCRIPT` and :variable:`CPACK_DMG_BACKGROUND_IMAGE` variables. -* The :module:`CPackDeb` module learned to set the optional config +* The :cpack_gen:`CPack DEB Generator` learned to set the optional config file ``Source`` field using a monolithic or per-component variable. See :variable:`CPACK_DEBIAN_PACKAGE_SOURCE`. -* The :module:`CPackDeb` module learned to set Package, Section +* The :cpack_gen:`CPack DEB Generator` learned to set Package, Section and Priority control fields per-component. See variables :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_SECTION` and :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_PRIORITY`. -* The :module:`CPack DragNDrop generator <CPackDMG>` learned to add +* The :cpack_gen:`CPack DragNDrop Generator` learned to add multi-lingual SLAs to a DMG which is presented to the user when they try to mount the DMG. See the :variable:`CPACK_DMG_SLA_LANGUAGES` and :variable:`CPACK_DMG_SLA_DIR` variables for details. -* The :module:`CPackNSIS` module learned new variables to add bitmaps to the - installer. See the :variable:`CPACK_NSIS_MUI_WELCOMEFINISHPAGE_BITMAP` +* The :cpack_gen:`CPack NSIS Generator` learned new variables to + add bitmaps to the installer. + See the :variable:`CPACK_NSIS_MUI_WELCOMEFINISHPAGE_BITMAP` and :variable:`CPACK_NSIS_MUI_UNWELCOMEFINISHPAGE_BITMAP` variables. -* The :module:`CPackRPM` module learned to set Name and Group +* The :cpack_gen:`CPack RPM Generator` learned to set Name and Group control fields per-component. See :variable:`CPACK_RPM_<component>_PACKAGE_NAME` and :variable:`CPACK_RPM_<component>_PACKAGE_GROUP`. diff --git a/Help/release/3.6.rst b/Help/release/3.6.rst index 144537de0..f0add07ff 100644 --- a/Help/release/3.6.rst +++ b/Help/release/3.6.rst @@ -111,7 +111,7 @@ Modules * The :module:`ExternalProject` module learned to initialize Git submodules recursively and also to initialize new submodules on updates. Use the - ``GIT_SUBMODULES`` option to restrict which submodules are initalized and + ``GIT_SUBMODULES`` option to restrict which submodules are initialized and updated. * The :module:`ExternalProject` module leared the ``DOWNLOAD_NO_EXTRACT 1`` @@ -165,25 +165,25 @@ CTest CPack ----- -* The :module:`CPackDeb` module learned how to handle ``$ORIGIN`` +* The :cpack_gen:`CPack DEB Generator` learned how to handle ``$ORIGIN`` in ``CMAKE_INSTALL_RPATH`` when :variable:`CPACK_DEBIAN_PACKAGE_SHLIBDEPS` is used for dependency auto detection. -* The :module:`CPackDeb` module learned how to generate ``DEBIAN/shlibs`` - contorl file when package contains shared libraries. +* The :cpack_gen:`CPack DEB Generator` learned how to generate + ``DEBIAN/shlibs`` contorl file when package contains shared libraries. -* The :module:`CPackDeb` module learned how to generate ``DEBIAN/postinst`` and - ``DEBIAN/postrm`` files if the package installs libraries in - ldconfig-controlled locations (e.g. ``/lib/``, ``/usr/lib/``). +* The :cpack_gen:`CPack DEB Generator` learned how to generate + ``DEBIAN/postinst`` and ``DEBIAN/postrm`` files if the package installs + libraries in ldconfig-controlled locations (e.g. ``/lib/``, ``/usr/lib/``). -* The :module:`CPackDeb` module learned how to generate dependencies between - Debian packages if multi-component setup is used and +* The :cpack_gen:`CPack DEB Generator` learned how to generate dependencies + between Debian packages if multi-component setup is used and :variable:`CPACK_COMPONENT_<compName>_DEPENDS` variables are set. For backward compatibility this feature is disabled by default. See :variable:`CPACK_DEBIAN_ENABLE_COMPONENT_DEPENDS`. -* The :module:`CPackDeb` module learned how to set custom package file names - including how to generate properly-named Debian packages:: +* The :cpack_gen:`CPack DEB Generator` learned how to set custom package + file names including how to generate properly-named Debian packages:: <PackageName>_<VersionNumber>-<DebianRevisionNumber>_<DebianArchitecture>.deb @@ -191,42 +191,44 @@ CPack :variable:`CPACK_DEBIAN_FILE_NAME` and :variable:`CPACK_DEBIAN_<COMPONENT>_FILE_NAME`. -* The :module:`CPackDeb` module learned how to set the package release number - (``DebianRevisionNumber`` in package file name when used in combination with - ``DEB-DEFAULT`` value set by :variable:`CPACK_DEBIAN_FILE_NAME`). See - :variable:`CPACK_DEBIAN_PACKAGE_RELEASE`. +* The :cpack_gen:`CPack DEB Generator` learned how to set the package + release number (``DebianRevisionNumber`` in package file name when + used in combination with ``DEB-DEFAULT`` value set by + :variable:`CPACK_DEBIAN_FILE_NAME`). + See :variable:`CPACK_DEBIAN_PACKAGE_RELEASE`. -* The :module:`CPackDeb` module learned how to set the package architecture - per-component. See :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_ARCHITECTURE`. +* The :cpack_gen:`CPack DEB Generator` learned how to set the package + architecture per-component. + See :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_ARCHITECTURE`. -* The :module:`CPackDMG` module learned a new option to tell the CPack - ``DragNDrop`` generaor to skip the ``/Applications`` symlink. +* The :cpack_gen:`CPack DragNDrop Generator` learned a new option to skip the + ``/Applications`` symlink. See the :variable:`CPACK_DMG_DISABLE_APPLICATIONS_SYMLINK` variable. * The :module:`CPackIFW` module gained a new :command:`cpack_ifw_update_repository` command to update a QtIFW-specific repository from a remote repository. -* The :module:`CPackRPM` module learned how to set RPM ``dist`` tag as part of - RPM ``Release:`` tag when enabled (mandatory on some Linux distributions for - e.g. on Fedora). +* The :cpack_gen:`CPack RPM Generator` learned how to set RPM ``dist`` tag + as part of RPM ``Release:`` tag when enabled (mandatory on some Linux + distributions for e.g. on Fedora). See :variable:`CPACK_RPM_PACKAGE_RELEASE_DIST`. -* The :module:`CPackRPM` module learned how to set default values for owning - user/group and file/directory permissions of package content. +* The :cpack_gen:`CPack RPM Generator` learned how to set default values + for owning user/group and file/directory permissions of package content. See :variable:`CPACK_RPM_DEFAULT_USER`, :variable:`CPACK_RPM_DEFAULT_GROUP`, :variable:`CPACK_RPM_DEFAULT_FILE_PERMISSIONS`, :variable:`CPACK_RPM_DEFAULT_DIR_PERMISSIONS` and their per component counterparts. -* The :module:`CPackRPM` module learned how to set user defined package file - names, how to specify that rpmbuild should decide on file name format as - well as handling of multiple rpm packages generated by a single user defined - spec file. +* The :cpack_gen:`CPack RPM Generator` learned how to set user defined + package file names, how to specify that rpmbuild should decide on file + name format as well as handling of multiple rpm packages generated by a + single user defined spec file. See :variable:`CPACK_RPM_PACKAGE_NAME` and :variable:`CPACK_RPM_<component>_PACKAGE_NAME`. -* The :module:`CPackRPM` module learned how to correctly handle symlinks +* The :cpack_gen:`CPack RPM Generator` learned how to correctly handle symlinks that are pointing outside generated packages. Other @@ -249,7 +251,7 @@ Deprecated and Removed Features Users that keep some ``<prefix>/bin`` directories in the ``PATH`` just for their tools do not necessarily want any supporting ``<prefix>/lib`` directories searched. One may set the ``CMAKE_PREFIX_PATH`` environment - variable with a :ref:`;-list <CMake Language Lists>` of prefixes that are + variable with a :ref:`semicolon-separated list <CMake Language Lists>` of prefixes that are to be searched. * The :generator:`Visual Studio 7 .NET 2003` generator is now @@ -296,7 +298,7 @@ Other Changes Input variables of the old case will be honored if provided, and output variables of the old case are always provided. -* The :module:`CPackRPM` module now supports upper cased component +* The :cpack_gen:`CPack RPM Generator` now supports upper cased component names in per component CPackRPM specific variables. E.g. component named ``foo`` now expects component specific variable to be ``CPACK_RPM_FOO_PACKAGE_NAME`` while before diff --git a/Help/release/3.7.rst b/Help/release/3.7.rst index 4c51af43e..345c056df 100644 --- a/Help/release/3.7.rst +++ b/Help/release/3.7.rst @@ -221,13 +221,12 @@ CTest CPack ----- -* CPack gained a ``productbuild`` generator on OS X, configured by - the :module:`CPackProductBuild` module. +* CPack gained a :cpack_gen:`CPack productbuild Generator` on OS X. * CPack gained a new :variable:`CPACK_PACKAGE_CHECKSUM` variable to enable generation of a checksum file for each package file. -* The :module:`CPackDeb` module learned to support long file names +* The :cpack_gen:`CPack DEB Generator` learned to support long file names when archive format is set to GNU tar. See :variable:`CPACK_DEBIAN_ARCHIVE_TYPE` @@ -237,35 +236,35 @@ CPack * The :module:`CPackIFW` module :command:`cpack_ifw_configure_component` and :command:`cpack_ifw_configure_component_group` commands gained a new - ``USER_INTERFACES`` option to add a list of additonal pages to the IFW + ``USER_INTERFACES`` option to add a list of additional pages to the IFW installer. -* The :module:`CPackRPM` module learned to generate debuginfo +* The :cpack_gen:`CPack RPM Generator` learned to generate debuginfo packages on demand. See :variable:`CPACK_RPM_DEBUGINFO_PACKAGE` and its per component version. -* The :module:`CPackRPM` module learned to generate source rpm +* The :cpack_gen:`CPack RPM Generator` learned to generate source rpm (SRPM) packages on demand. See :variable:`CPACK_RPM_PACKAGE_SOURCES`, :variable:`CPACK_RPM_SOURCE_PKG_BUILD_PARAMS` and :variable:`CPACK_RPM_SOURCE_PKG_PACKAGING_INSTALL_PREFIX`. -* The CPack NSIS generator now supports +* The :cpack_gen:`CPack NSIS Generator` now supports :variable:`CPACK_NSIS_<compName>_INSTALL_DIRECTORY`. This can be used to set component specific installation directories. -* The CPack WIX generator now supports +* The :cpack_gen:`CPack WIX Generator` now supports :variable:`CPACK_WIX_SKIP_PROGRAM_FOLDER` to allow specification of a custom absolute installation prefix outside of the ProgramFiles folders. -* The CPack WIX generator now supports +* The :cpack_gen:`CPack WIX Generator` now supports :variable:`CPACK_COMPONENT_<compName>_DISABLED`. This can be used to deselect a component from being installed by default. -* The CPack WIX generator now supports :variable:`CPACK_WIX_PATCH_FILE` - fragments for Feature elements. +* The :cpack_gen:`CPack WIX Generator` now supports + :variable:`CPACK_WIX_PATCH_FILE` fragments for Feature elements. -* The CPack WIX generator now supports +* The :cpack_gen:`CPack WIX Generator` now supports :variable:`CPACK_WIX_ROOT_FEATURE_TITLE` and :variable:`CPACK_WIX_ROOT_FEATURE_DESCRIPTION` to allow the specification of a custom title and description for the root feature element. diff --git a/Help/release/3.8.rst b/Help/release/3.8.rst index efb2aa5a7..de51a7bc3 100644 --- a/Help/release/3.8.rst +++ b/Help/release/3.8.rst @@ -307,7 +307,7 @@ CPack option now is deprecated and will be removed in a future version of CMake. Please use new ``SORTING_PRIORITY`` option instead. -* The :module:`CPackIFW` module gained new +* The :cpack_gen:`CPack IFW Generator` gained new :variable:`CPACK_IFW_PACKAGE_WATERMARK`, :variable:`CPACK_IFW_PACKAGE_BANNER`, :variable:`CPACK_IFW_PACKAGE_BACKGROUND`, @@ -317,26 +317,26 @@ CPack :variable:`CPACK_IFW_PACKAGE_TITLE_COLOR` variables to customize a QtIFW installer look. -* The :module:`CPackProductBuild` module gained options to sign packages. +* The :cpack_gen:`CPack productbuild Generator` gained options to sign packages. See the variables :variable:`CPACK_PRODUCTBUILD_IDENTITY_NAME`, :variable:`CPACK_PRODUCTBUILD_KEYCHAIN_PATH`, :variable:`CPACK_PKGBUILD_IDENTITY_NAME`, and :variable:`CPACK_PKGBUILD_KEYCHAIN_PATH`. -* The :module:`CPackRPM` module learned to omit tags that are not supported by - provided ``rpmbuild`` tool. If unsupported tags are set they are ignored - and a developer warning is printed out. +* The :cpack_gen:`CPack RPM Generator` learned to omit tags that are not + supported by provided ``rpmbuild`` tool. If unsupported tags are set they + are ignored and a developer warning is printed out. -* The :module:`CPackRPM` module learned to generate main component package - which forces generation of a rpm for defined component without component - suffix in filename and package name. +* The :cpack_gen:`CPack RPM Generator` learned to generate main component + package which forces generation of a rpm for defined component without + component suffix in filename and package name. See :variable:`CPACK_RPM_MAIN_COMPONENT` variable. -* The :module:`CPackRPM` module learned to generate a single ``debuginfo`` - package on demand even if components packaging is used. +* The :cpack_gen:`CPack RPM Generator` learned to generate a single + ``debuginfo`` package on demand even if components packaging is used. See :variable:`CPACK_RPM_DEBUGINFO_SINGLE_PACKAGE` variable. -* The :module:`CPackRPM` module learned to support +* The :cpack_gen:`CPack RPM Generator` learned to support multiple directives per file when using :variable:`CPACK_RPM_USER_FILELIST` variable. diff --git a/Help/release/3.9.rst b/Help/release/3.9.rst index 897e268b5..89da62751 100644 --- a/Help/release/3.9.rst +++ b/Help/release/3.9.rst @@ -150,7 +150,7 @@ Modules * The :module:`CMakeFindDependencyMacro` module ``find_dependency`` macro now forwards all arguments to the underlying :command:`find_package` call. Existing uses will continue to function as before, but callers can - now access the full suite of arguments that ``find_package`` accepts. + now access the full suite of arguments that :command:`find_package` accepts. * The :module:`FeatureSummary` module :command:`feature_summary` command now accepts the new ``DEFAULT_DESCRIPTION`` option that will print the default @@ -206,7 +206,7 @@ CTest CPack ----- -* The :module:`CPackArchive` module learned to modify the filename +* The :cpack_gen:`CPack Archive Generator` learned to modify the filename per-component. See the :variable:`CPACK_ARCHIVE_FILE_NAME` variable and its per-component version :variable:`CPACK_ARCHIVE_<component>_FILE_NAME`. @@ -220,23 +220,24 @@ CPack internationalization support for ``DISPLAY_NAME`` and ``DESCRIPTION`` options. -* The :module:`CPackIFW` module learned the new hint :variable:`CPACK_IFW_ROOT` - variable for finding the QtIFW tool suite installed in a non-standard place. +* The :cpack_gen:`CPack IFW Generator` learned the new hint + :variable:`CPACK_IFW_ROOT` variable for finding the QtIFW tool suite + installed in a non-standard place. -* The :module:`CPackProductBuild` module gained a new +* The :cpack_gen:`CPack productbuild Generator` gained a new :variable:`CPACK_PRODUCTBUILD_RESOURCES_DIR` variable to specify resources to be copied into the ``Resources`` directory. -* The :module:`CPackRPM` module learned to modify the ``debuginfo`` package - name. See the :variable:`CPACK_RPM_DEBUGINFO_FILE_NAME` variable. +* The :cpack_gen:`CPack RPM Generator` learned to modify the ``debuginfo`` + package name. See the :variable:`CPACK_RPM_DEBUGINFO_FILE_NAME` variable. -* The :module:`CPackWIX` module patching system now has the ability to set - additional attributes. This can be done by specifying attributes with - the ``CPackWiXFragment`` XML tag after the ``Id`` attribute. +* The :cpack_gen:`CPack WIX Generator` patching system now has the + ability to set additional attributes. This can be done by specifying + attributes with the ``CPackWiXFragment`` XML tag after the ``Id`` attribute. See the :variable:`CPACK_WIX_PATCH_FILE` variable. -* The CPack WIX generator implemented a new +* The :cpack_gen:`CPack WIX Generator` implemented a new :variable:`CPACK_WIX_ROOT_FOLDER_ID` variable which allows using a custom root folder ID instead of the default ``ProgramFilesFolder`` / ``ProgramFiles64Folder``. diff --git a/Help/release/index.rst b/Help/release/index.rst index 6af282cff..0cc3f9726 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -13,6 +13,13 @@ Releases .. toctree:: :maxdepth: 1 + 3.16 <3.16> + 3.15 <3.15> + 3.14 <3.14> + 3.13 <3.13> + 3.12 <3.12> + 3.11 <3.11> + 3.10 <3.10> 3.9 <3.9> 3.8 <3.8> 3.7 <3.7> diff --git a/Help/variable/APPLE.rst b/Help/variable/APPLE.rst index 75eecf183..810d5fc3a 100644 --- a/Help/variable/APPLE.rst +++ b/Help/variable/APPLE.rst @@ -1,6 +1,5 @@ APPLE ----- -``True`` if running on OS X. - -Set to ``true`` on OS X. +Set to ``True`` when the target system is an Apple platform +(macOS, iOS, tvOS or watchOS). diff --git a/Help/variable/CACHE.rst b/Help/variable/CACHE.rst new file mode 100644 index 000000000..2cef27efa --- /dev/null +++ b/Help/variable/CACHE.rst @@ -0,0 +1,18 @@ +CACHE +----- + +Operator to read cache variables. + +Use the syntax ``$CACHE{VAR}`` to read cache entry ``VAR``. +See the :ref:`cmake-language(7) variables <CMake Language Variables>` +documentation for more complete documentation of the interaction of +normal variables and cache entries. + +When evaluating :ref:`Variable References` of the form ``${VAR}``, +CMake first searches for a normal variable with that name, and if not +found CMake will search for a cache entry with that name. +The ``$CACHE{VAR}`` syntax can be used to do direct cache lookup and +ignore any existing normal variable. + +See the :command:`set` and :command:`unset` commands to see how to +write or remove cache variables. diff --git a/Help/variable/CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION.rst b/Help/variable/CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION.rst index 5ae55d15b..22808e3ed 100644 --- a/Help/variable/CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION.rst +++ b/Help/variable/CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION.rst @@ -3,7 +3,11 @@ CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION When :ref:`Cross Compiling for Android with the NDK`, this variable may be set to specify the version of the toolchain to be used -as the compiler. The variable must be set to one of these forms: +as the compiler. + +On NDK r19 or above, this variable must be unset or set to ``clang``. + +On NDK r18 or below, this variable must be set to one of these forms: * ``<major>.<minor>``: GCC of specified version * ``clang<major>.<minor>``: Clang of specified version diff --git a/Help/variable/CMAKE_ANDROID_STL_TYPE.rst b/Help/variable/CMAKE_ANDROID_STL_TYPE.rst index cfb76aa04..d174575c8 100644 --- a/Help/variable/CMAKE_ANDROID_STL_TYPE.rst +++ b/Help/variable/CMAKE_ANDROID_STL_TYPE.rst @@ -30,7 +30,8 @@ set to specify the STL variant to be used. The value may be one of: ``stlport_shared`` STLport Shared -The default value is ``gnustl_static``. Note that this default differs from +The default value is ``gnustl_static`` on NDK versions that provide it +and otherwise ``c++_static``. Note that this default differs from the native NDK build system because CMake may be used to build projects for Android that are not natively implemented for it and use the C++ standard library. diff --git a/Help/variable/CMAKE_APPBUNDLE_PATH.rst b/Help/variable/CMAKE_APPBUNDLE_PATH.rst index 2bc79ac3a..1c7ca51c2 100644 --- a/Help/variable/CMAKE_APPBUNDLE_PATH.rst +++ b/Help/variable/CMAKE_APPBUNDLE_PATH.rst @@ -1,6 +1,6 @@ CMAKE_APPBUNDLE_PATH -------------------- -:ref:`;-list <CMake Language Lists>` of directories specifying a search path -for OS X application bundles used by the :command:`find_program`, and +:ref:`Semicolon-separated list <CMake Language Lists>` of directories specifying a search path +for macOS application bundles used by the :command:`find_program`, and :command:`find_package` commands. diff --git a/Help/variable/CMAKE_ARGC.rst b/Help/variable/CMAKE_ARGC.rst index aec97119a..30db2a2da 100644 --- a/Help/variable/CMAKE_ARGC.rst +++ b/Help/variable/CMAKE_ARGC.rst @@ -3,6 +3,6 @@ CMAKE_ARGC Number of command line arguments passed to CMake in script mode. -When run in :ref:`-P <CMake Options>` script mode, CMake sets this variable to -the number of command line arguments. See also :variable:`CMAKE_ARGV0`, -``1``, ``2`` ... +When run in :ref:`-P <Script Processing Mode>` script mode, CMake sets this +variable to the number of command line arguments. See also +:variable:`CMAKE_ARGV0`, ``1``, ``2`` ... diff --git a/Help/variable/CMAKE_ARGV0.rst b/Help/variable/CMAKE_ARGV0.rst index 8b1ecb79e..c4d1c219e 100644 --- a/Help/variable/CMAKE_ARGV0.rst +++ b/Help/variable/CMAKE_ARGV0.rst @@ -3,7 +3,7 @@ CMAKE_ARGV0 Command line argument passed to CMake in script mode. -When run in :ref:`-P <CMake Options>` script mode, CMake sets this variable to -the first command line argument. It then also sets ``CMAKE_ARGV1``, +When run in :ref:`-P <Script Processing Mode>` script mode, CMake sets this +variable to the first command line argument. It then also sets ``CMAKE_ARGV1``, ``CMAKE_ARGV2``, ... and so on, up to the number of command line arguments given. See also :variable:`CMAKE_ARGC`. diff --git a/Help/variable/CMAKE_AUTOGEN_ORIGIN_DEPENDS.rst b/Help/variable/CMAKE_AUTOGEN_ORIGIN_DEPENDS.rst new file mode 100644 index 000000000..1398e7856 --- /dev/null +++ b/Help/variable/CMAKE_AUTOGEN_ORIGIN_DEPENDS.rst @@ -0,0 +1,11 @@ +CMAKE_AUTOGEN_ORIGIN_DEPENDS +---------------------------- + +Switch for forwarding origin target dependencies to the corresponding +``_autogen`` targets. + +This variable is used to initialize the :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS` +property on all the targets. See that target property for additional +information. + +By default :variable:`CMAKE_AUTOGEN_ORIGIN_DEPENDS` is ``ON``. diff --git a/Help/variable/CMAKE_AUTOGEN_PARALLEL.rst b/Help/variable/CMAKE_AUTOGEN_PARALLEL.rst new file mode 100644 index 000000000..dd9499af3 --- /dev/null +++ b/Help/variable/CMAKE_AUTOGEN_PARALLEL.rst @@ -0,0 +1,10 @@ +CMAKE_AUTOGEN_PARALLEL +---------------------- + +Number of parallel ``moc`` or ``uic`` processes to start when using +:prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`. + +This variable is used to initialize the :prop_tgt:`AUTOGEN_PARALLEL` property +on all the targets. See that target property for additional information. + +By default :variable:`CMAKE_AUTOGEN_PARALLEL` is unset. diff --git a/Help/variable/CMAKE_AUTOGEN_VERBOSE.rst b/Help/variable/CMAKE_AUTOGEN_VERBOSE.rst new file mode 100644 index 000000000..bad9cf2b3 --- /dev/null +++ b/Help/variable/CMAKE_AUTOGEN_VERBOSE.rst @@ -0,0 +1,13 @@ +CMAKE_AUTOGEN_VERBOSE +--------------------- + +Sets the verbosity of :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTOUIC` and +:prop_tgt:`AUTORCC`. A positive integer value or a true boolean value +lets the ``AUTO*`` generators output additional processing information. + +Setting :variable:`CMAKE_AUTOGEN_VERBOSE` has the same effect +as setting the ``VERBOSE`` environment variable during +generation (e.g. by calling ``make VERBOSE=1``). +The extra verbosity is limited to the ``AUTO*`` generators though. + +By default :variable:`CMAKE_AUTOGEN_VERBOSE` is unset. diff --git a/Help/variable/CMAKE_AUTOMOC_COMPILER_PREDEFINES.rst b/Help/variable/CMAKE_AUTOMOC_COMPILER_PREDEFINES.rst new file mode 100644 index 000000000..7e1c53d06 --- /dev/null +++ b/Help/variable/CMAKE_AUTOMOC_COMPILER_PREDEFINES.rst @@ -0,0 +1,8 @@ +CMAKE_AUTOMOC_COMPILER_PREDEFINES +--------------------------------- + +This variable is used to initialize the :prop_tgt:`AUTOMOC_COMPILER_PREDEFINES` +property on all the targets. See that target property for additional +information. + +By default it is ON. diff --git a/Help/variable/CMAKE_AUTOMOC_MACRO_NAMES.rst b/Help/variable/CMAKE_AUTOMOC_MACRO_NAMES.rst new file mode 100644 index 000000000..ba1b9d27a --- /dev/null +++ b/Help/variable/CMAKE_AUTOMOC_MACRO_NAMES.rst @@ -0,0 +1,20 @@ +CMAKE_AUTOMOC_MACRO_NAMES +---------------------------- + +:ref:`Semicolon-separated list <CMake Language Lists>` list of macro names used by +:variable:`CMAKE_AUTOMOC` to determine if a C++ file needs to be +processed by ``moc``. + +This variable is used to initialize the :prop_tgt:`AUTOMOC_MACRO_NAMES` +property on all the targets. See that target property for additional +information. + +The default value is ``Q_OBJECT;Q_GADGET;Q_NAMESPACE``. + +Example +^^^^^^^ +Let CMake know that source files that contain ``CUSTOM_MACRO`` must be ``moc`` +processed as well:: + + set(CMAKE_AUTOMOC ON) + list(APPEND CMAKE_AUTOMOC_MACRO_NAMES "CUSTOM_MACRO") diff --git a/Help/variable/CMAKE_AUTOMOC_PATH_PREFIX.rst b/Help/variable/CMAKE_AUTOMOC_PATH_PREFIX.rst new file mode 100644 index 000000000..dca0b0657 --- /dev/null +++ b/Help/variable/CMAKE_AUTOMOC_PATH_PREFIX.rst @@ -0,0 +1,11 @@ +CMAKE_AUTOMOC_PATH_PREFIX +------------------------- + +Whether to generate the ``-p`` path prefix option for ``moc`` on +:prop_tgt:`AUTOMOC` enabled Qt targets. + +This variable is used to initialize the :prop_tgt:`AUTOMOC_PATH_PREFIX` +property on all the targets. See that target property for additional +information. + +The default value is ``ON``. diff --git a/Help/variable/CMAKE_AUTOMOC_RELAXED_MODE.rst b/Help/variable/CMAKE_AUTOMOC_RELAXED_MODE.rst index addc62de4..6c0c61b11 100644 --- a/Help/variable/CMAKE_AUTOMOC_RELAXED_MODE.rst +++ b/Help/variable/CMAKE_AUTOMOC_RELAXED_MODE.rst @@ -1,6 +1,8 @@ CMAKE_AUTOMOC_RELAXED_MODE -------------------------- +.. deprecated:: 3.15 + Switch between strict and relaxed automoc mode. By default, :prop_tgt:`AUTOMOC` behaves exactly as described in the diff --git a/Help/variable/CMAKE_AUTORCC_OPTIONS.rst b/Help/variable/CMAKE_AUTORCC_OPTIONS.rst index 298cb6be7..815d39d41 100644 --- a/Help/variable/CMAKE_AUTORCC_OPTIONS.rst +++ b/Help/variable/CMAKE_AUTORCC_OPTIONS.rst @@ -1,7 +1,16 @@ CMAKE_AUTORCC_OPTIONS --------------------- -Whether to handle ``rcc`` automatically for Qt targets. +Additional options for ``rcc`` when using :variable:`CMAKE_AUTORCC`. This variable is used to initialize the :prop_tgt:`AUTORCC_OPTIONS` property on all the targets. See that target property for additional information. + +EXAMPLE +^^^^^^^ + +.. code-block:: cmake + + # ... + set(CMAKE_AUTORCC_OPTIONS "--compress;9") + # ... diff --git a/Help/variable/CMAKE_AUTOUIC_OPTIONS.rst b/Help/variable/CMAKE_AUTOUIC_OPTIONS.rst index 3c9b8c4f5..28fa92f16 100644 --- a/Help/variable/CMAKE_AUTOUIC_OPTIONS.rst +++ b/Help/variable/CMAKE_AUTOUIC_OPTIONS.rst @@ -1,7 +1,16 @@ CMAKE_AUTOUIC_OPTIONS --------------------- -Whether to handle ``uic`` automatically for Qt targets. +Additional options for ``uic`` when using :variable:`CMAKE_AUTOUIC`. This variable is used to initialize the :prop_tgt:`AUTOUIC_OPTIONS` property on all the targets. See that target property for additional information. + +EXAMPLE +^^^^^^^ + +.. code-block:: cmake + + # ... + set_property(CMAKE_AUTOUIC_OPTIONS "--no-protection") + # ... diff --git a/Help/variable/CMAKE_BUILD_RPATH.rst b/Help/variable/CMAKE_BUILD_RPATH.rst index f20eb418f..f5d53b88c 100644 --- a/Help/variable/CMAKE_BUILD_RPATH.rst +++ b/Help/variable/CMAKE_BUILD_RPATH.rst @@ -1,7 +1,7 @@ CMAKE_BUILD_RPATH ----------------- -A :ref:`;-list <CMake Language Lists>` specifying runtime path (``RPATH``) +:ref:`Semicolon-separated list <CMake Language Lists>` specifying runtime path (``RPATH``) entries to add to binaries linked in the build tree (for platforms that support it). The entries will *not* be used for binaries in the install tree. See also the :variable:`CMAKE_INSTALL_RPATH` variable. diff --git a/Help/variable/CMAKE_BUILD_RPATH_USE_ORIGIN.rst b/Help/variable/CMAKE_BUILD_RPATH_USE_ORIGIN.rst new file mode 100644 index 000000000..e34ede6ad --- /dev/null +++ b/Help/variable/CMAKE_BUILD_RPATH_USE_ORIGIN.rst @@ -0,0 +1,7 @@ +CMAKE_BUILD_RPATH_USE_ORIGIN +---------------------------- + +Whether to use relative paths for the build ``RPATH``. + +This is used to initialize the :prop_tgt:`BUILD_RPATH_USE_ORIGIN` target +property for all targets, see that property for more details. diff --git a/Help/variable/CMAKE_BUILD_TYPE.rst b/Help/variable/CMAKE_BUILD_TYPE.rst index 2d54d6049..2d35635ac 100644 --- a/Help/variable/CMAKE_BUILD_TYPE.rst +++ b/Help/variable/CMAKE_BUILD_TYPE.rst @@ -5,7 +5,7 @@ Specifies the build type on single-configuration generators. This statically specifies what build type (configuration) will be built in this build tree. Possible values are empty, ``Debug``, ``Release``, -``RelWithDebInfo`` and ``MinSizeRel``. This variable is only meaningful to +``RelWithDebInfo``, ``MinSizeRel``, ... This variable is only meaningful to single-configuration generators (such as :ref:`Makefile Generators` and :generator:`Ninja`) i.e. those which choose a single configuration when CMake runs to generate a build tree as opposed to multi-configuration generators @@ -13,7 +13,7 @@ which offer selection of the build configuration within the generated build environment. There are many per-config properties and variables (usually following clean ``SOME_VAR_<CONFIG>`` order conventions), such as ``CMAKE_C_FLAGS_<CONFIG>``, specified as uppercase: -``CMAKE_C_FLAGS_[DEBUG|RELEASE|RELWITHDEBINFO|MINSIZEREL]``. For example, +``CMAKE_C_FLAGS_[DEBUG|RELEASE|RELWITHDEBINFO|MINSIZEREL|...]``. For example, in a build tree configured to build type ``Debug``, CMake will see to having :variable:`CMAKE_C_FLAGS_DEBUG <CMAKE_<LANG>_FLAGS_DEBUG>` settings get added to the :variable:`CMAKE_C_FLAGS <CMAKE_<LANG>_FLAGS>` settings. See diff --git a/Help/variable/CMAKE_CFG_INTDIR.rst b/Help/variable/CMAKE_CFG_INTDIR.rst index c36599adf..af82f7571 100644 --- a/Help/variable/CMAKE_CFG_INTDIR.rst +++ b/Help/variable/CMAKE_CFG_INTDIR.rst @@ -12,7 +12,7 @@ Example values: :: - $(ConfigurationName) = Visual Studio 8, 9 + $(ConfigurationName) = Visual Studio 9 $(Configuration) = Visual Studio 10 $(CONFIGURATION) = Xcode . = Make-based tools diff --git a/Help/variable/CMAKE_CODEBLOCKS_COMPILER_ID.rst b/Help/variable/CMAKE_CODEBLOCKS_COMPILER_ID.rst new file mode 100644 index 000000000..ad2709dc3 --- /dev/null +++ b/Help/variable/CMAKE_CODEBLOCKS_COMPILER_ID.rst @@ -0,0 +1,13 @@ +CMAKE_CODEBLOCKS_COMPILER_ID +---------------------------- + +Change the compiler id in the generated CodeBlocks project files. + +CodeBlocks uses its own compiler id string which differs from +:variable:`CMAKE_<LANG>_COMPILER_ID`. If this variable is left empty, +CMake tries to recognize the CodeBlocks compiler id automatically. +Otherwise the specified string is used in the CodeBlocks project file. +See the CodeBlocks documentation for valid compiler id strings. + +Other IDEs like QtCreator that also use the CodeBlocks generator may ignore +this setting. diff --git a/Help/variable/CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES.rst b/Help/variable/CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES.rst new file mode 100644 index 000000000..80ffce3a7 --- /dev/null +++ b/Help/variable/CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES.rst @@ -0,0 +1,7 @@ +CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES +--------------------------------------- + +Change the way the CodeBlocks generator creates project files. + +If this variable evaluates to ``ON`` the generator excludes from +the project file any files that are located outside the project root. diff --git a/Help/variable/CMAKE_CPACK_COMMAND.rst b/Help/variable/CMAKE_CPACK_COMMAND.rst new file mode 100644 index 000000000..559108a1a --- /dev/null +++ b/Help/variable/CMAKE_CPACK_COMMAND.rst @@ -0,0 +1,8 @@ +CMAKE_CPACK_COMMAND +------------------- + +Full path to :manual:`cpack(1)` command installed with CMake. + +This is the full path to the CPack executable :manual:`cpack(1)` which is +useful from custom commands that want to use the :manual:`cmake(1)` ``-E`` +option for portable system commands. diff --git a/Help/variable/CMAKE_CROSSCOMPILING.rst b/Help/variable/CMAKE_CROSSCOMPILING.rst index cf9865b61..7e6ec3371 100644 --- a/Help/variable/CMAKE_CROSSCOMPILING.rst +++ b/Help/variable/CMAKE_CROSSCOMPILING.rst @@ -1,8 +1,27 @@ CMAKE_CROSSCOMPILING -------------------- -Is CMake currently cross compiling. +Intended to indicate whether CMake is cross compiling, but note limitations +discussed below. -This variable will be set to true by CMake if CMake is cross -compiling. Specifically if the build platform is different from the -target platform. +This variable will be set to true by CMake if the :variable:`CMAKE_SYSTEM_NAME` +variable has been set manually (i.e. in a toolchain file or as a cache entry +from the :manual:`cmake <cmake(1)>` command line). In most cases, manually +setting :variable:`CMAKE_SYSTEM_NAME` will only be done when cross compiling, +since it will otherwise be given the same value as +:variable:`CMAKE_HOST_SYSTEM_NAME` if not manually set, which is correct for +the non-cross-compiling case. In the event that :variable:`CMAKE_SYSTEM_NAME` +is manually set to the same value as :variable:`CMAKE_HOST_SYSTEM_NAME`, then +``CMAKE_CROSSCOMPILING`` will still be set to true. + +Another case to be aware of is that builds targeting Apple platforms other than +macOS are handled differently to other cross compiling scenarios. Rather than +relying on :variable:`CMAKE_SYSTEM_NAME` to select the target platform, Apple +device builds use :variable:`CMAKE_OSX_SYSROOT` to select the appropriate SDK, +which indirectly determines the target platform. Furthermore, when using the +:generator:`Xcode` generator, developers can switch between device and +simulator builds at build time rather than having a single +choice at configure time, so the concept +of whether the build is cross compiling or not is more complex. Therefore, the +use of ``CMAKE_CROSSCOMPILING`` is not recommended for projects targeting Apple +devices. diff --git a/Help/variable/CMAKE_CROSSCOMPILING_EMULATOR.rst b/Help/variable/CMAKE_CROSSCOMPILING_EMULATOR.rst index 95d2c7ffc..1d013b7a6 100644 --- a/Help/variable/CMAKE_CROSSCOMPILING_EMULATOR.rst +++ b/Help/variable/CMAKE_CROSSCOMPILING_EMULATOR.rst @@ -5,8 +5,12 @@ This variable is only used when :variable:`CMAKE_CROSSCOMPILING` is on. It should point to a command on the host system that can run executable built for the target system. +If this variable contains a :ref:`semicolon-separated list <CMake Language +Lists>`, then the first value is the command and remaining values are its +arguments. + The command will be used to run :command:`try_run` generated executables, -which avoids manual population of the TryRunResults.cmake file. +which avoids manual population of the ``TryRunResults.cmake`` file. It is also used as the default value for the :prop_tgt:`CROSSCOMPILING_EMULATOR` target property of executables. diff --git a/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst b/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst new file mode 100644 index 000000000..6d34c5ccc --- /dev/null +++ b/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst @@ -0,0 +1,8 @@ +CMAKE_CUDA_HOST_COMPILER +------------------------ + +Executable to use when compiling host code when compiling ``CUDA`` language +files. Maps to the ``nvcc -ccbin`` option. Will only be used by CMake on the first +configuration to determine a valid host compiler for ``CUDA``. After a valid +host compiler has been found, this value is read-only. This variable takes +priority over the :envvar:`CUDAHOSTCXX` environment variable. diff --git a/Help/variable/CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS.rst b/Help/variable/CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS.rst new file mode 100644 index 000000000..fc835cd12 --- /dev/null +++ b/Help/variable/CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS.rst @@ -0,0 +1,6 @@ +CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS +--------------------------------- + +Default value for :prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` target +property. This variable is used to initialize the property on each target as +it is created. diff --git a/Help/variable/CMAKE_CUDA_SEPARABLE_COMPILATION.rst b/Help/variable/CMAKE_CUDA_SEPARABLE_COMPILATION.rst new file mode 100644 index 000000000..eef92fb16 --- /dev/null +++ b/Help/variable/CMAKE_CUDA_SEPARABLE_COMPILATION.rst @@ -0,0 +1,6 @@ +CMAKE_CUDA_SEPARABLE_COMPILATION +-------------------------------- + +Default value for :prop_tgt:`CUDA_SEPARABLE_COMPILATION` target property. +This variable is used to initialize the property on each target as it is +created. diff --git a/Help/variable/CMAKE_CUDA_TOOLKIT_INCLUDE_DIRECTORIES.rst b/Help/variable/CMAKE_CUDA_TOOLKIT_INCLUDE_DIRECTORIES.rst index 768f571c0..7de50a5a7 100644 --- a/Help/variable/CMAKE_CUDA_TOOLKIT_INCLUDE_DIRECTORIES.rst +++ b/Help/variable/CMAKE_CUDA_TOOLKIT_INCLUDE_DIRECTORIES.rst @@ -2,6 +2,6 @@ CMAKE_CUDA_TOOLKIT_INCLUDE_DIRECTORIES -------------------------------------- When the ``CUDA`` language has been enabled, this provides a -:ref:`;-list <CMake Language Lists>` of include directories provided +:ref:`semicolon-separated list <CMake Language Lists>` of include directories provided by the CUDA Toolkit. The value may be useful for C++ source files to include CUDA headers. diff --git a/Help/variable/CMAKE_DEBUG_TARGET_PROPERTIES.rst b/Help/variable/CMAKE_DEBUG_TARGET_PROPERTIES.rst index 513276e57..a1fa1fffa 100644 --- a/Help/variable/CMAKE_DEBUG_TARGET_PROPERTIES.rst +++ b/Help/variable/CMAKE_DEBUG_TARGET_PROPERTIES.rst @@ -5,10 +5,19 @@ Enables tracing output for target properties. This variable can be populated with a list of properties to generate debug output for when evaluating target properties. Currently it can -only be used when evaluating the :prop_tgt:`INCLUDE_DIRECTORIES`, -:prop_tgt:`COMPILE_DEFINITIONS`, :prop_tgt:`COMPILE_OPTIONS`, -:prop_tgt:`AUTOUIC_OPTIONS`, :prop_tgt:`SOURCES`, :prop_tgt:`COMPILE_FEATURES`, -:prop_tgt:`POSITION_INDEPENDENT_CODE` target properties and any other property -listed in :prop_tgt:`COMPATIBLE_INTERFACE_STRING` and other -``COMPATIBLE_INTERFACE_`` properties. It outputs an origin for each entry in -the target property. Default is unset. +only be used when evaluating: + +* :prop_tgt:`AUTOUIC_OPTIONS` +* :prop_tgt:`COMPILE_DEFINITIONS` +* :prop_tgt:`COMPILE_FEATURES` +* :prop_tgt:`COMPILE_OPTIONS` +* :prop_tgt:`INCLUDE_DIRECTORIES` +* :prop_tgt:`LINK_DIRECTORIES` +* :prop_tgt:`LINK_OPTIONS` +* :prop_tgt:`POSITION_INDEPENDENT_CODE` +* :prop_tgt:`SOURCES` + +target properties and any other property listed in +:prop_tgt:`COMPATIBLE_INTERFACE_STRING` and other +``COMPATIBLE_INTERFACE_`` properties. It outputs an origin for each entry +in the target property. Default is unset. diff --git a/Help/variable/CMAKE_DIRECTORY_LABELS.rst b/Help/variable/CMAKE_DIRECTORY_LABELS.rst new file mode 100644 index 000000000..2a6c41000 --- /dev/null +++ b/Help/variable/CMAKE_DIRECTORY_LABELS.rst @@ -0,0 +1,6 @@ +CMAKE_DIRECTORY_LABELS +----------------------- + +Specify labels for the current directory. + +This is used to initialize the :prop_dir:`LABELS` directory property. diff --git a/Help/variable/CMAKE_DISABLE_PRECOMPILE_HEADERS.rst b/Help/variable/CMAKE_DISABLE_PRECOMPILE_HEADERS.rst new file mode 100644 index 000000000..7c30edebc --- /dev/null +++ b/Help/variable/CMAKE_DISABLE_PRECOMPILE_HEADERS.rst @@ -0,0 +1,6 @@ +CMAKE_DISABLE_PRECOMPILE_HEADERS +-------------------------------- + +Default value for :prop_tgt:`DISABLE_PRECOMPILE_HEADERS` of targets. + +By default ``CMAKE_DISABLE_PRECOMPILE_HEADERS`` is ``OFF``. diff --git a/Help/variable/CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION.rst b/Help/variable/CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION.rst new file mode 100644 index 000000000..124fefef1 --- /dev/null +++ b/Help/variable/CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION.rst @@ -0,0 +1,16 @@ +CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION +------------------------------------- + +Default value for :prop_tgt:`DOTNET_TARGET_FRAMEWORK_VERSION` +property of targets. + +This variable is used to initialize the +:prop_tgt:`DOTNET_TARGET_FRAMEWORK_VERSION` property on all +targets. See that target property for additional information. + +Setting ``CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION`` may be necessary +when working with ``C#`` and newer .NET framework versions to +avoid referencing errors with the ``ALL_BUILD`` CMake target. + +This variable is only evaluated for :ref:`Visual Studio Generators` +VS 2010 and above. diff --git a/Help/variable/CMAKE_ECLIPSE_RESOURCE_ENCODING.rst b/Help/variable/CMAKE_ECLIPSE_RESOURCE_ENCODING.rst new file mode 100644 index 000000000..314efe5fe --- /dev/null +++ b/Help/variable/CMAKE_ECLIPSE_RESOURCE_ENCODING.rst @@ -0,0 +1,6 @@ +CMAKE_ECLIPSE_RESOURCE_ENCODING +------------------------------- + +This cache variable tells the :generator:`Eclipse CDT4` project generator +to set the resource encoding to the given value in generated project files. +If no value is given, no encoding will be set. diff --git a/Help/variable/CMAKE_ENABLE_EXPORTS.rst b/Help/variable/CMAKE_ENABLE_EXPORTS.rst index 9a877e7e6..8848da123 100644 --- a/Help/variable/CMAKE_ENABLE_EXPORTS.rst +++ b/Help/variable/CMAKE_ENABLE_EXPORTS.rst @@ -1,22 +1,8 @@ CMAKE_ENABLE_EXPORTS -------------------- -Specify whether an executable exports symbols for loadable modules. +Specify whether executables export symbols for loadable modules. -Normally an executable does not export any symbols because it is the -final program. It is possible for an executable to export symbols to -be used by loadable modules. When this property is set to true CMake -will allow other targets to ``link`` to the executable with the -:command:`TARGET_LINK_LIBRARIES` command. On all platforms a target-level -dependency on the executable is created for targets that link to it. -For DLL platforms an import library will be created for the exported -symbols and then used for linking. All Windows-based systems -including Cygwin are DLL platforms. For non-DLL platforms that -require all symbols to be resolved at link time, such as OS X, the -module will ``link`` to the executable using a flag like -``-bundle_loader``. For other non-DLL platforms the link rule is simply -ignored since the dynamic loader will automatically bind symbols when -the module is loaded. - -This variable is used to initialize the target property -:prop_tgt:`ENABLE_EXPORTS` for executable targets. +This variable is used to initialize the :prop_tgt:`ENABLE_EXPORTS` target +property for executable targets when they are created by calls to the +:command:`add_executable` command. See the property documentation for details. diff --git a/Help/variable/CMAKE_EXECUTE_PROCESS_COMMAND_ECHO.rst b/Help/variable/CMAKE_EXECUTE_PROCESS_COMMAND_ECHO.rst new file mode 100644 index 000000000..76561d82b --- /dev/null +++ b/Help/variable/CMAKE_EXECUTE_PROCESS_COMMAND_ECHO.rst @@ -0,0 +1,6 @@ +CMAKE_EXECUTE_PROCESS_COMMAND_ECHO +---------------------------------- + +If this variable is set to ``STDERR``, ``STDOUT`` or ``NONE`` then commands +in :command:`execute_process` calls will be printed to either stderr or +stdout or not at all. diff --git a/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst b/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst index 8776279e8..4548abcc7 100644 --- a/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst +++ b/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst @@ -28,3 +28,7 @@ form. The format of the JSON file looks like: .. note:: This option is implemented only by :ref:`Makefile Generators` and the :generator:`Ninja`. It is ignored on other generators. + + This option currently does not work well in combination with + the :prop_tgt:`UNITY_BUILD` target property or the + :variable:`CMAKE_UNITY_BUILD` variable. diff --git a/Help/variable/CMAKE_EXPORT_NO_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_EXPORT_NO_PACKAGE_REGISTRY.rst index ee109ba1a..768ed64bf 100644 --- a/Help/variable/CMAKE_EXPORT_NO_PACKAGE_REGISTRY.rst +++ b/Help/variable/CMAKE_EXPORT_NO_PACKAGE_REGISTRY.rst @@ -1,11 +1,16 @@ CMAKE_EXPORT_NO_PACKAGE_REGISTRY -------------------------------- -Disable the :command:`export(PACKAGE)` command. +Disable the :command:`export(PACKAGE)` command when :policy:`CMP0090` +is not set to ``NEW``. 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 is enabled, +If the ``CMAKE_EXPORT_NO_PACKAGE_REGISTRY`` variable is enabled, the :command:`export(PACKAGE)` command will do nothing. +If :policy:`CMP0090` is set to ``NEW`` this variable does nothing, and the +:variable:`CMAKE_EXPORT_PACKAGE_REGISTRY` variable controls the behavior +instead. + See also :ref:`Disabling the Package Registry`. diff --git a/Help/variable/CMAKE_EXPORT_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_EXPORT_PACKAGE_REGISTRY.rst new file mode 100644 index 000000000..3476a199c --- /dev/null +++ b/Help/variable/CMAKE_EXPORT_PACKAGE_REGISTRY.rst @@ -0,0 +1,15 @@ +CMAKE_EXPORT_PACKAGE_REGISTRY +----------------------------- + +Enables the :command:`export(PACKAGE)` command when :policy:`CMP0090` +is set to ``NEW``. + +The :command:`export(PACKAGE)` command does nothing by default. In some cases +it is desirable to write to the user package registry, so the +``CMAKE_EXPORT_PACKAGE_REGISTRY`` variable may be set to enable it. + +If :policy:`CMP0090` is *not* set to ``NEW`` this variable does nothing, and +the :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` variable controls the behavior +instead. + +See also :ref:`Disabling the Package Registry`. diff --git a/Help/variable/CMAKE_EXTRA_GENERATOR.rst b/Help/variable/CMAKE_EXTRA_GENERATOR.rst index 4d513e474..2c9232345 100644 --- a/Help/variable/CMAKE_EXTRA_GENERATOR.rst +++ b/Help/variable/CMAKE_EXTRA_GENERATOR.rst @@ -4,7 +4,7 @@ CMAKE_EXTRA_GENERATOR The extra generator used to build the project. See :manual:`cmake-generators(7)`. -When using the Eclipse, CodeBlocks or KDevelop generators, CMake +When using the Eclipse, CodeBlocks, CodeLite, Kate or Sublime generators, CMake generates Makefiles (:variable:`CMAKE_GENERATOR`) and additionally project files for the respective IDE. This IDE project file generator is stored in ``CMAKE_EXTRA_GENERATOR`` (e.g. ``Eclipse CDT4``). diff --git a/Help/variable/CMAKE_FIND_APPBUNDLE.rst b/Help/variable/CMAKE_FIND_APPBUNDLE.rst index e0727b547..7a05facf8 100644 --- a/Help/variable/CMAKE_FIND_APPBUNDLE.rst +++ b/Help/variable/CMAKE_FIND_APPBUNDLE.rst @@ -2,9 +2,9 @@ CMAKE_FIND_APPBUNDLE -------------------- This variable affects how ``find_*`` commands choose between -OS X Application Bundles and unix-style package components. +macOS Application Bundles and unix-style package components. -On Darwin or systems supporting OS X Application Bundles, the +On Darwin or systems supporting macOS Application Bundles, the ``CMAKE_FIND_APPBUNDLE`` variable can be set to empty or one of the following: diff --git a/Help/variable/CMAKE_FIND_FRAMEWORK.rst b/Help/variable/CMAKE_FIND_FRAMEWORK.rst index 790694ac5..4d5078fb6 100644 --- a/Help/variable/CMAKE_FIND_FRAMEWORK.rst +++ b/Help/variable/CMAKE_FIND_FRAMEWORK.rst @@ -2,9 +2,9 @@ CMAKE_FIND_FRAMEWORK -------------------- This variable affects how ``find_*`` commands choose between -OS X Frameworks and unix-style package components. +macOS Frameworks and unix-style package components. -On Darwin or systems supporting OS X Frameworks, the +On Darwin or systems supporting macOS Frameworks, the ``CMAKE_FIND_FRAMEWORK`` variable can be set to empty or one of the following: diff --git a/Help/variable/CMAKE_FIND_NO_INSTALL_PREFIX.rst b/Help/variable/CMAKE_FIND_NO_INSTALL_PREFIX.rst index c49d2641b..789dc99aa 100644 --- a/Help/variable/CMAKE_FIND_NO_INSTALL_PREFIX.rst +++ b/Help/variable/CMAKE_FIND_NO_INSTALL_PREFIX.rst @@ -1,15 +1,19 @@ CMAKE_FIND_NO_INSTALL_PREFIX ---------------------------- -Ignore the :variable:`CMAKE_INSTALL_PREFIX` when searching for assets. +Exclude the values of the :variable:`CMAKE_INSTALL_PREFIX` and +:variable:`CMAKE_STAGING_PREFIX` variables from +:variable:`CMAKE_SYSTEM_PREFIX_PATH`. CMake adds these project-destination +prefixes to :variable:`CMAKE_SYSTEM_PREFIX_PATH` by default in order to +support building a series of dependent packages and installing them into +a common prefix. Set ``CMAKE_FIND_NO_INSTALL_PREFIX`` to ``TRUE`` +to suppress this behavior. -CMake adds the :variable:`CMAKE_INSTALL_PREFIX` and the -:variable:`CMAKE_STAGING_PREFIX` variable to the -:variable:`CMAKE_SYSTEM_PREFIX_PATH` by default. This variable may be set -on the command line to control that behavior. +The :variable:`CMAKE_SYSTEM_PREFIX_PATH` is initialized on the first call to a +:command:`project` or :command:`enable_language` command. Therefore one must +set ``CMAKE_FIND_NO_INSTALL_PREFIX`` before this in order to take effect. A +user may set the variable as a cache entry on the command line to achieve this. -Set ``CMAKE_FIND_NO_INSTALL_PREFIX`` to ``TRUE`` to tell -:command:`find_package` not to search in the :variable:`CMAKE_INSTALL_PREFIX` -or :variable:`CMAKE_STAGING_PREFIX` by default. Note that the -prefix may still be searched for other reasons, such as being the same prefix -as the CMake installation, or for being a built-in system prefix. +Note that the prefix(es) may still be searched for other reasons, such as being +the same prefix as the CMake installation, or for being a built-in system +prefix. diff --git a/Help/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY.rst index 90584710e..4ee9d8b81 100644 --- a/Help/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY.rst +++ b/Help/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY.rst @@ -1,12 +1,23 @@ CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY -------------------------------------- -Skip :ref:`User Package Registry` in :command:`find_package` calls. +.. deprecated:: 3.16 + + Use the :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` variable instead. + +By default this variable is not set. If neither +:variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` nor +``CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY`` is set, then +:command:`find_package()` will use the :ref:`User Package Registry` +unless the ``NO_CMAKE_PACKAGE_REGISTRY`` option is provided. + +``CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY`` is ignored if +:variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` is set. In some cases, for example to locate only system wide installations, it is not desirable to use the :ref:`User Package Registry` when searching for packages. If the :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` -variable is enabled, all the :command:`find_package` commands will skip +variable is ``TRUE``, all the :command:`find_package` commands will skip the :ref:`User Package Registry` as if they were called with the ``NO_CMAKE_PACKAGE_REGISTRY`` argument. diff --git a/Help/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY.rst index 44588b17a..107c183eb 100644 --- a/Help/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY.rst +++ b/Help/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY.rst @@ -1,12 +1,23 @@ CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY --------------------------------------------- -Skip :ref:`System Package Registry` in :command:`find_package` calls. +.. deprecated:: 3.16 + + Use the :variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY` variable instead. + +By default this variable is not set. If neither +:variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY` nor +``CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY`` is set, then +:command:`find_package()` will use the :ref:`System Package Registry` +unless the ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` option is provided. + +``CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY`` is ignored if +:variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY` is set. In some cases, it is not desirable to use the :ref:`System Package Registry` when searching for packages. If the :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` variable is -enabled, all the :command:`find_package` commands will skip +``TRUE``, all the :command:`find_package` commands will skip the :ref:`System Package Registry` as if they were called with the ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` argument. diff --git a/Help/variable/CMAKE_FIND_PACKAGE_PREFER_CONFIG.rst b/Help/variable/CMAKE_FIND_PACKAGE_PREFER_CONFIG.rst new file mode 100644 index 000000000..db658a1e0 --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_PREFER_CONFIG.rst @@ -0,0 +1,27 @@ +CMAKE_FIND_PACKAGE_PREFER_CONFIG +--------------------------------- + +Tell :command:`find_package` to try "Config" mode before "Module" mode if no +mode was specified. + +The command :command:`find_package` operates without an explicit mode when +the reduced signature is used without the ``MODULE`` option. In this case, +by default, CMake first tries Module mode by searching for a +``Find<pkg>.cmake`` module. If it fails, CMake then searches for the package +using Config mode. + +Set ``CMAKE_FIND_PACKAGE_PREFER_CONFIG`` to ``TRUE`` to tell +:command:`find_package` to first search using Config mode before falling back +to Module mode. + +This variable may be useful when a developer has compiled a custom version of +a common library and wishes to link it to a dependent project. If this +variable is set to ``TRUE``, it would prevent a dependent project's call +to :command:`find_package` from selecting the default library located by the +system's ``Find<pkg>.cmake`` module before finding the developer's custom +built library. + +Once this variable is set, it is the responsibility of the exported +``<pkg>Config.cmake`` files to provide the same result variables as the +``Find<pkg>.cmake`` modules so that dependent projects can use them +interchangeably. diff --git a/Help/variable/CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS.rst b/Help/variable/CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS.rst new file mode 100644 index 000000000..dfbde2035 --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS.rst @@ -0,0 +1,10 @@ +CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS +----------------------------------- + +Set to ``TRUE`` to tell :command:`find_package` calls to resolve symbolic +links in the value of ``<PackageName>_DIR``. + +This is helpful in use cases where the package search path points at a +proxy directory in which symlinks to the real package locations appear. +This is not enabled by default because there are also common use cases +in which the symlinks should be preserved. diff --git a/Help/variable/CMAKE_FIND_PACKAGE_WARN_NO_MODULE.rst b/Help/variable/CMAKE_FIND_PACKAGE_WARN_NO_MODULE.rst index f1116bb62..5c4f23a4a 100644 --- a/Help/variable/CMAKE_FIND_PACKAGE_WARN_NO_MODULE.rst +++ b/Help/variable/CMAKE_FIND_PACKAGE_WARN_NO_MODULE.rst @@ -17,3 +17,6 @@ Set ``CMAKE_FIND_PACKAGE_WARN_NO_MODULE`` to ``TRUE`` to tell :command:`find_package` to warn when it implicitly assumes Config mode. This helps developers enforce use of an explicit mode in all calls to :command:`find_package` within a project. + +This variable has no effect if :variable:`CMAKE_FIND_PACKAGE_PREFER_CONFIG` is +set to ``TRUE``. diff --git a/Help/variable/CMAKE_FIND_ROOT_PATH.rst b/Help/variable/CMAKE_FIND_ROOT_PATH.rst index ba2cf313e..6172c56ae 100644 --- a/Help/variable/CMAKE_FIND_ROOT_PATH.rst +++ b/Help/variable/CMAKE_FIND_ROOT_PATH.rst @@ -1,7 +1,7 @@ CMAKE_FIND_ROOT_PATH -------------------- -:ref:`;-list <CMake Language Lists>` of root paths to search on the filesystem. +:ref:`Semicolon-separated list <CMake Language Lists>` of root paths to search on the filesystem. This variable is most useful when cross-compiling. CMake uses the paths in this list as alternative roots to find filesystem items with diff --git a/Help/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.rst b/Help/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.rst new file mode 100644 index 000000000..957e956f3 --- /dev/null +++ b/Help/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.rst @@ -0,0 +1,24 @@ +CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH +------------------------------------- + +Controls the default behavior of the following commands for whether or not to +search paths provided by cmake-specific environment variables: + +* :command:`find_program` +* :command:`find_library` +* :command:`find_file` +* :command:`find_path` +* :command:`find_package` + +This is useful in cross-compiling environments. + +By default this variable is not set, which is equivalent to it having +a value of ``TRUE``. Explicit options given to the above commands +take precedence over this variable. + +See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`, +:variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`, +and :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` variables. diff --git a/Help/variable/CMAKE_FIND_USE_CMAKE_PATH.rst b/Help/variable/CMAKE_FIND_USE_CMAKE_PATH.rst new file mode 100644 index 000000000..d2bdb09b5 --- /dev/null +++ b/Help/variable/CMAKE_FIND_USE_CMAKE_PATH.rst @@ -0,0 +1,24 @@ +CMAKE_FIND_USE_CMAKE_PATH +------------------------- + +Controls the default behavior of the following commands for whether or not to +search paths provided by cmake-specific cache variables: + +* :command:`find_program` +* :command:`find_library` +* :command:`find_file` +* :command:`find_path` +* :command:`find_package` + +This is useful in cross-compiling environments. + +By default this variable is not set, which is equivalent to it having +a value of ``TRUE``. Explicit options given to the above commands +take precedence over this variable. + +See also the :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`, +:variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`, +and :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` variables. diff --git a/Help/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.rst b/Help/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.rst new file mode 100644 index 000000000..b99081d3e --- /dev/null +++ b/Help/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.rst @@ -0,0 +1,24 @@ +CMAKE_FIND_USE_CMAKE_SYSTEM_PATH +-------------------------------- + +Controls the default behavior of the following commands for whether or not to +search paths provided by platform-specific cmake variables: + +* :command:`find_program` +* :command:`find_library` +* :command:`find_file` +* :command:`find_path` +* :command:`find_package` + +This is useful in cross-compiling environments. + +By default this variable is not set, which is equivalent to it having +a value of ``TRUE``. Explicit options given to the above commands +take precedence over this variable. + +See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`, +:variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`, +and :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` variables. diff --git a/Help/variable/CMAKE_FIND_USE_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_FIND_USE_PACKAGE_REGISTRY.rst new file mode 100644 index 000000000..7c7ca3618 --- /dev/null +++ b/Help/variable/CMAKE_FIND_USE_PACKAGE_REGISTRY.rst @@ -0,0 +1,30 @@ +CMAKE_FIND_USE_PACKAGE_REGISTRY +------------------------------- + +Controls the default behavior of the :command:`find_package` command for +whether or not to search paths provided by the :ref:`User Package Registry`. + +By default this variable is not set and the behavior will fall back +to that determined by the deprecated +:variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` variable. If that is +also not set, then :command:`find_package` will use the +:ref:`User Package Registry` unless the ``NO_CMAKE_PACKAGE_REGISTRY`` option +is provided. + +This variable takes precedence over +:variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` when both are set. + +In some cases, for example to locate only system wide installations, it +is not desirable to use the :ref:`User Package Registry` when searching +for packages. If the :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` +variable is ``FALSE``, all the :command:`find_package` commands will skip +the :ref:`User Package Registry` as if they were called with the +``NO_CMAKE_PACKAGE_REGISTRY`` argument. + +See also :ref:`Disabling the Package Registry` and the +:variable:`CMAKE_FIND_USE_CMAKE_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`, +and :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` variables. diff --git a/Help/variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH.rst b/Help/variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH.rst new file mode 100644 index 000000000..e7f5b0ff8 --- /dev/null +++ b/Help/variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH.rst @@ -0,0 +1,22 @@ +CMAKE_FIND_USE_PACKAGE_ROOT_PATH +-------------------------------- + +Controls the default behavior of the following commands for whether or not to +search paths provided by :variable:`<PackageName>_ROOT` variables: + +* :command:`find_program` +* :command:`find_library` +* :command:`find_file` +* :command:`find_path` +* :command:`find_package` + +By default this variable is not set, which is equivalent to it having +a value of ``TRUE``. Explicit options given to the above commands +take precedence over this variable. + +See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`, +and :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` variables. diff --git a/Help/variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.rst b/Help/variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.rst new file mode 100644 index 000000000..fbaba5a73 --- /dev/null +++ b/Help/variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.rst @@ -0,0 +1,24 @@ +CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH +-------------------------------------- + +Controls the default behavior of the following commands for whether or not to +search paths provided by standard system environment variables: + +* :command:`find_program` +* :command:`find_library` +* :command:`find_file` +* :command:`find_path` +* :command:`find_package` + +This is useful in cross-compiling environments. + +By default this variable is not set, which is equivalent to it having +a value of ``TRUE``. Explicit options given to the above commands +take precedence over this variable. + +See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, +:variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`, +:variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH`, +and :variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY` variables. diff --git a/Help/variable/CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY.rst new file mode 100644 index 000000000..cb4eec5d1 --- /dev/null +++ b/Help/variable/CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY.rst @@ -0,0 +1,31 @@ +CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY +-------------------------------------- + +Controls searching the :ref:`System Package Registry` by the +:command:`find_package` command. + +By default this variable is not set and the behavior will fall back +to that determined by the deprecated +:variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` variable. +If that is also not set, then :command:`find_package()` will use the +:ref:`System Package Registry` unless the ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` +option is provided. + +This variable takes precedence over +:variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` when both are set. + +In some cases, for example to locate only user specific installations, it +is not desirable to use the :ref:`System Package Registry` when searching +for packages. If the ``CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`` +variable is ``FALSE``, all the :command:`find_package` commands will skip +the :ref:`System Package Registry` as if they were called with the +``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` argument. + +See also :ref:`Disabling the Package Registry`. + +See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`, +and :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` variables. diff --git a/Help/variable/CMAKE_FOLDER.rst b/Help/variable/CMAKE_FOLDER.rst new file mode 100644 index 000000000..50a2b88d7 --- /dev/null +++ b/Help/variable/CMAKE_FOLDER.rst @@ -0,0 +1,7 @@ +CMAKE_FOLDER +------------ + +Set the folder name. Use to organize targets in an IDE. + +This variable is used to initialize the :prop_tgt:`FOLDER` property on all the +targets. See that target property for additional information. diff --git a/Help/variable/CMAKE_FRAMEWORK.rst b/Help/variable/CMAKE_FRAMEWORK.rst new file mode 100644 index 000000000..591041c8b --- /dev/null +++ b/Help/variable/CMAKE_FRAMEWORK.rst @@ -0,0 +1,7 @@ +CMAKE_FRAMEWORK +--------------- + +Default value for :prop_tgt:`FRAMEWORK` of targets. + +This variable is used to initialize the :prop_tgt:`FRAMEWORK` property on +all the targets. See that target property for additional information. diff --git a/Help/variable/CMAKE_FRAMEWORK_PATH.rst b/Help/variable/CMAKE_FRAMEWORK_PATH.rst index 5ff08e679..13ade4e5f 100644 --- a/Help/variable/CMAKE_FRAMEWORK_PATH.rst +++ b/Help/variable/CMAKE_FRAMEWORK_PATH.rst @@ -1,7 +1,7 @@ CMAKE_FRAMEWORK_PATH -------------------- -:ref:`;-list <CMake Language Lists>` of directories specifying a search path -for OS X frameworks used by the :command:`find_library`, +:ref:`Semicolon-separated list <CMake Language Lists>` of directories specifying a search path +for macOS frameworks used by the :command:`find_library`, :command:`find_package`, :command:`find_path`, and :command:`find_file` commands. diff --git a/Help/variable/CMAKE_GENERATOR.rst b/Help/variable/CMAKE_GENERATOR.rst index cce04c136..ec52cd4d8 100644 --- a/Help/variable/CMAKE_GENERATOR.rst +++ b/Help/variable/CMAKE_GENERATOR.rst @@ -5,3 +5,8 @@ The generator used to build the project. See :manual:`cmake-generators(7)`. The name of the generator that is being used to generate the build files. (e.g. ``Unix Makefiles``, ``Ninja``, etc.) + +The value of this variable should never be modified by project code. +A generator may be selected via the :manual:`cmake(1)` ``-G`` option, +interactively in :manual:`cmake-gui(1)`, or via the :envvar:`CMAKE_GENERATOR` +environment variable. diff --git a/Help/variable/CMAKE_GENERATOR_INSTANCE.rst b/Help/variable/CMAKE_GENERATOR_INSTANCE.rst new file mode 100644 index 000000000..3657ed4ff --- /dev/null +++ b/Help/variable/CMAKE_GENERATOR_INSTANCE.rst @@ -0,0 +1,25 @@ +CMAKE_GENERATOR_INSTANCE +------------------------ + +Generator-specific instance specification provided by user. + +Some CMake generators support selection of an instance of the native build +system when multiple instances are available. If the user specifies an +instance (e.g. by setting this cache entry or via the +:envvar:`CMAKE_GENERATOR_INSTANCE` environment variable), or after a default +instance is chosen when a build tree is first configured, the value will be +available in this variable. + +The value of this variable should never be modified by project code. +A toolchain file specified by the :variable:`CMAKE_TOOLCHAIN_FILE` +variable may initialize ``CMAKE_GENERATOR_INSTANCE`` as a cache entry. +Once a given build tree has been initialized with a particular value +for this variable, changing the value has undefined behavior. + +Instance specification is supported only on specific generators: + +* For the :generator:`Visual Studio 15 2017` generator (and above) + this specifies the absolute path to the VS installation directory + of the selected VS instance. + +See native build system documentation for allowed instance values. diff --git a/Help/variable/CMAKE_GENERATOR_PLATFORM.rst b/Help/variable/CMAKE_GENERATOR_PLATFORM.rst index 50412ffff..2c115a3ab 100644 --- a/Help/variable/CMAKE_GENERATOR_PLATFORM.rst +++ b/Help/variable/CMAKE_GENERATOR_PLATFORM.rst @@ -6,7 +6,8 @@ Generator-specific target platform specification provided by user. Some CMake generators support a target platform name to be given to the native build system to choose a compiler toolchain. If the user specifies a platform name (e.g. via the :manual:`cmake(1)` ``-A`` -option) the value will be available in this variable. +option or via the :envvar:`CMAKE_GENERATOR_PLATFORM` environment variable) +the value will be available in this variable. The value of this variable should never be modified by project code. A toolchain file specified by the :variable:`CMAKE_TOOLCHAIN_FILE` @@ -19,6 +20,8 @@ Platform specification is supported only on specific generators: * For :ref:`Visual Studio Generators` with VS 2005 and above this specifies the target architecture. +* For :generator:`Green Hills MULTI` this specifies the target architecture. + See native build system documentation for allowed platform names. Visual Studio Platform Selection diff --git a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst index 11c37d746..222824f6a 100644 --- a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst +++ b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst @@ -5,7 +5,8 @@ Native build system toolset specification provided by user. Some CMake generators support a toolset specification to tell the native build system how to choose a compiler. If the user specifies -a toolset (e.g. via the :manual:`cmake(1)` ``-T`` option) the value +a toolset (e.g. via the :manual:`cmake(1)` ``-T`` option or via +the :envvar:`CMAKE_GENERATOR_TOOLSET` environment variable) the value will be available in this variable. The value of this variable should never be modified by project code. @@ -18,6 +19,7 @@ Toolset specification is supported only on specific generators: * :ref:`Visual Studio Generators` for VS 2010 and above * The :generator:`Xcode` generator for Xcode 3.0 and above +* The :generator:`Green Hills MULTI` generator See native build system documentation for allowed toolset names. @@ -38,13 +40,21 @@ The ``key=value`` pairs form a comma-separated list of options to specify generator-specific details of the toolset selection. Supported pairs are: -``cuda=<version>`` - Specify the CUDA toolkit version to use. Supported by VS 2010 - and above with the CUDA toolkit VS integration installed. - See the :variable:`CMAKE_VS_PLATFORM_TOOLSET_CUDA` variable. +``cuda=<version>|<path>`` + Specify the CUDA toolkit version to use or the path to a + standalone CUDA toolkit directory. Supported by VS 2010 + and above. The version can only be used with the CUDA + toolkit VS integration globally installed. + See the :variable:`CMAKE_VS_PLATFORM_TOOLSET_CUDA` and + :variable:`CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR` variables. -``host=x64`` - Request use of the native ``x64`` toolchain on ``x64`` hosts. +``host=<arch>`` + Specify the host tools architecture as ``x64`` or ``x86``. Supported by VS 2013 and above. See the :variable:`CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE` variable. + +``version=<version>`` + Specify the toolset version to use. Supported by VS 2017 + and above with the specified toolset installed. + See the :variable:`CMAKE_VS_PLATFORM_TOOLSET_VERSION` variable. diff --git a/Help/variable/CMAKE_GHS_NO_SOURCE_GROUP_FILE.rst b/Help/variable/CMAKE_GHS_NO_SOURCE_GROUP_FILE.rst new file mode 100644 index 000000000..b6768a131 --- /dev/null +++ b/Help/variable/CMAKE_GHS_NO_SOURCE_GROUP_FILE.rst @@ -0,0 +1,6 @@ +CMAKE_GHS_NO_SOURCE_GROUP_FILE +------------------------------ + +``ON`` / ``OFF`` boolean to control if the project file for a target should +be one single file or multiple files. Refer to +:prop_tgt:`GHS_NO_SOURCE_GROUP_FILE` for further details. diff --git a/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET.rst b/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET.rst new file mode 100644 index 000000000..e82867dfd --- /dev/null +++ b/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET.rst @@ -0,0 +1,26 @@ +CMAKE_GLOBAL_AUTOGEN_TARGET +--------------------------- + +Switch to enable generation of a global ``autogen`` target. + +When :variable:`CMAKE_GLOBAL_AUTORCC_TARGET` is enabled, a custom target +``autogen`` is generated. This target depends on all :prop_tgt:`AUTOMOC` and +:prop_tgt:`AUTOUIC` generated ``<ORIGIN>_autogen`` targets in the project. +By building the global ``autogen`` target, all :prop_tgt:`AUTOMOC` and +:prop_tgt:`AUTOUIC` files in the project will be generated. + +The name of the global ``autogen`` target can be changed by setting +:variable:`CMAKE_GLOBAL_AUTOGEN_TARGET_NAME`. + +By default :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET` is unset. + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. + +Note +^^^^ + +``<ORIGIN>_autogen`` targets by default inherit their origin target's +dependencies. This might result in unintended dependency target +builds when only ``<ORIGIN>_autogen`` targets are built. A solution is to +disable :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS` on the respective origin targets. diff --git a/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET_NAME.rst b/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET_NAME.rst new file mode 100644 index 000000000..c86a5d0af --- /dev/null +++ b/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET_NAME.rst @@ -0,0 +1,13 @@ +CMAKE_GLOBAL_AUTOGEN_TARGET_NAME +-------------------------------- + +Change the name of the global ``autogen`` target. + +When :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET` is enabled, a global custom target +named ``autogen`` is created. :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET_NAME` +allows to set a different name for that target. + +By default :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET_NAME` is unset. + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. diff --git a/Help/variable/CMAKE_GLOBAL_AUTORCC_TARGET.rst b/Help/variable/CMAKE_GLOBAL_AUTORCC_TARGET.rst new file mode 100644 index 000000000..f92128cda --- /dev/null +++ b/Help/variable/CMAKE_GLOBAL_AUTORCC_TARGET.rst @@ -0,0 +1,18 @@ +CMAKE_GLOBAL_AUTORCC_TARGET +--------------------------- + +Switch to enable generation of a global ``autorcc`` target. + +When :variable:`CMAKE_GLOBAL_AUTORCC_TARGET` is enabled, a custom target +``autorcc`` is generated. This target depends on all :prop_tgt:`AUTORCC` +generated ``<ORIGIN>_arcc_<QRC>`` targets in the project. +By building the global ``autorcc`` target, all :prop_tgt:`AUTORCC` +files in the project will be generated. + +The name of the global ``autorcc`` target can be changed by setting +:variable:`CMAKE_GLOBAL_AUTORCC_TARGET_NAME`. + +By default :variable:`CMAKE_GLOBAL_AUTORCC_TARGET` is unset. + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. diff --git a/Help/variable/CMAKE_GLOBAL_AUTORCC_TARGET_NAME.rst b/Help/variable/CMAKE_GLOBAL_AUTORCC_TARGET_NAME.rst new file mode 100644 index 000000000..c6e05de4e --- /dev/null +++ b/Help/variable/CMAKE_GLOBAL_AUTORCC_TARGET_NAME.rst @@ -0,0 +1,13 @@ +CMAKE_GLOBAL_AUTORCC_TARGET_NAME +-------------------------------- + +Change the name of the global ``autorcc`` target. + +When :variable:`CMAKE_GLOBAL_AUTORCC_TARGET` is enabled, a global custom target +named ``autorcc`` is created. :variable:`CMAKE_GLOBAL_AUTORCC_TARGET_NAME` +allows to set a different name for that target. + +By default :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET_NAME` is unset. + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. diff --git a/Help/variable/CMAKE_HOME_DIRECTORY.rst b/Help/variable/CMAKE_HOME_DIRECTORY.rst index fdc5d8190..b03d95618 100644 --- a/Help/variable/CMAKE_HOME_DIRECTORY.rst +++ b/Help/variable/CMAKE_HOME_DIRECTORY.rst @@ -1,6 +1,9 @@ CMAKE_HOME_DIRECTORY -------------------- -Path to top of source tree. +Path to top of source tree. Same as :variable:`CMAKE_SOURCE_DIR`. -This is the path to the top level of the source tree. +This is an internal cache entry used to locate the source directory +when loading a ``CMakeCache.txt`` from a build tree. It should not +be used in project code. The variable :variable:`CMAKE_SOURCE_DIR` +has the same value and should be preferred. diff --git a/Help/variable/CMAKE_HOST_APPLE.rst b/Help/variable/CMAKE_HOST_APPLE.rst index ac7b03004..9c205ec34 100644 --- a/Help/variable/CMAKE_HOST_APPLE.rst +++ b/Help/variable/CMAKE_HOST_APPLE.rst @@ -1,6 +1,6 @@ CMAKE_HOST_APPLE ---------------- -``True`` for Apple OS X operating systems. +``True`` for Apple macOS operating systems. -Set to ``true`` when the host system is Apple OS X. +Set to ``true`` when the host system is Apple macOS. diff --git a/Help/variable/CMAKE_HOST_SYSTEM.rst b/Help/variable/CMAKE_HOST_SYSTEM.rst index c2a8f1a5f..12d11d198 100644 --- a/Help/variable/CMAKE_HOST_SYSTEM.rst +++ b/Help/variable/CMAKE_HOST_SYSTEM.rst @@ -1,7 +1,7 @@ CMAKE_HOST_SYSTEM ----------------- -Composit Name of OS CMake is being run on. +Composite Name of OS CMake is being run on. This variable is the composite of :variable:`CMAKE_HOST_SYSTEM_NAME` and :variable:`CMAKE_HOST_SYSTEM_VERSION`, e.g. diff --git a/Help/variable/CMAKE_HOST_SYSTEM_NAME.rst b/Help/variable/CMAKE_HOST_SYSTEM_NAME.rst index c67359272..e8926771c 100644 --- a/Help/variable/CMAKE_HOST_SYSTEM_NAME.rst +++ b/Help/variable/CMAKE_HOST_SYSTEM_NAME.rst @@ -4,5 +4,5 @@ CMAKE_HOST_SYSTEM_NAME Name of the OS CMake is running on. On systems that have the uname command, this variable is set to the -output of ``uname -s``. ``Linux``, ``Windows``, and ``Darwin`` for OS X +output of ``uname -s``. ``Linux``, ``Windows``, and ``Darwin`` for macOS are the values found on the big three operating systems. diff --git a/Help/variable/CMAKE_IGNORE_PATH.rst b/Help/variable/CMAKE_IGNORE_PATH.rst index 92f377086..4bca34b7e 100644 --- a/Help/variable/CMAKE_IGNORE_PATH.rst +++ b/Help/variable/CMAKE_IGNORE_PATH.rst @@ -1,7 +1,7 @@ CMAKE_IGNORE_PATH ----------------- -:ref:`;-list <CMake Language Lists>` of directories to be *ignored* by +:ref:`Semicolon-separated list <CMake Language Lists>` of directories to be *ignored* by the :command:`find_program`, :command:`find_library`, :command:`find_file`, and :command:`find_path` commands. This is useful in cross-compiling environments where some system directories contain incompatible but diff --git a/Help/variable/CMAKE_INCLUDE_CURRENT_DIR.rst b/Help/variable/CMAKE_INCLUDE_CURRENT_DIR.rst index 6eea322f8..98d99eb64 100644 --- a/Help/variable/CMAKE_INCLUDE_CURRENT_DIR.rst +++ b/Help/variable/CMAKE_INCLUDE_CURRENT_DIR.rst @@ -1,7 +1,7 @@ CMAKE_INCLUDE_CURRENT_DIR ------------------------- -Automatically add the current source- and build directories to the include path. +Automatically add the current source and build directories to the include path. If this variable is enabled, CMake automatically adds :variable:`CMAKE_CURRENT_SOURCE_DIR` and :variable:`CMAKE_CURRENT_BINARY_DIR` diff --git a/Help/variable/CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE.rst b/Help/variable/CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE.rst index 5fc95f00b..697682ba6 100644 --- a/Help/variable/CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE.rst +++ b/Help/variable/CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE.rst @@ -1,7 +1,7 @@ CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE -------------------------------------- -Automatically add the current source- and build directories to the +Automatically add the current source and build directories to the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property. If this variable is enabled, CMake automatically adds for each shared diff --git a/Help/variable/CMAKE_INCLUDE_PATH.rst b/Help/variable/CMAKE_INCLUDE_PATH.rst index e4e7f2cfc..4918e9960 100644 --- a/Help/variable/CMAKE_INCLUDE_PATH.rst +++ b/Help/variable/CMAKE_INCLUDE_PATH.rst @@ -1,7 +1,7 @@ CMAKE_INCLUDE_PATH ------------------ -:ref:`;-list <CMake Language Lists>` of directories specifying a search path +:ref:`Semicolon-separated list <CMake Language Lists>` of directories specifying a search path for the :command:`find_file` and :command:`find_path` commands. By default it is empty, it is intended to be set by the project. See also :variable:`CMAKE_SYSTEM_INCLUDE_PATH` and :variable:`CMAKE_PREFIX_PATH`. diff --git a/Help/variable/CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS.rst b/Help/variable/CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS.rst new file mode 100644 index 000000000..f994fbe87 --- /dev/null +++ b/Help/variable/CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS.rst @@ -0,0 +1,29 @@ +CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS +------------------------------------------- + +Default permissions for directories created implicitly during installation +of files by :command:`install` and :command:`file(INSTALL)`. + +If ``make install`` is invoked and directories are implicitly created they +get permissions set by :variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` +variable or platform specific default permissions if the variable is not set. + +Implicitly created directories are created if they are not explicitly installed +by :command:`install` command but are needed to install a file on a certain +path. Example of such locations are directories created due to the setting of +:variable:`CMAKE_INSTALL_PREFIX`. + +Expected content of the :variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` +variable is a list of permissions that can be used by :command:`install` command +`PERMISSIONS` section. + +Example usage: + +:: + + set(CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS + OWNER_READ + OWNER_WRITE + OWNER_EXECUTE + GROUP_READ + ) diff --git a/Help/variable/CMAKE_INSTALL_NAME_DIR.rst b/Help/variable/CMAKE_INSTALL_NAME_DIR.rst index 1f2d62bf6..5ba4c04cb 100644 --- a/Help/variable/CMAKE_INSTALL_NAME_DIR.rst +++ b/Help/variable/CMAKE_INSTALL_NAME_DIR.rst @@ -1,7 +1,7 @@ CMAKE_INSTALL_NAME_DIR ---------------------- -OS X directory name for installed targets. +macOS directory name for installed targets. ``CMAKE_INSTALL_NAME_DIR`` is used to initialize the :prop_tgt:`INSTALL_NAME_DIR` property on all targets. See that target diff --git a/Help/variable/CMAKE_INSTALL_PREFIX.rst b/Help/variable/CMAKE_INSTALL_PREFIX.rst index 7bd87d6aa..02ba645c7 100644 --- a/Help/variable/CMAKE_INSTALL_PREFIX.rst +++ b/Help/variable/CMAKE_INSTALL_PREFIX.rst @@ -10,21 +10,7 @@ See :variable:`CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT` for how a project might choose its own default. On UNIX one can use the ``DESTDIR`` mechanism in order to relocate the -whole installation. ``DESTDIR`` means DESTination DIRectory. It is -commonly used by makefile users in order to install software at -non-default location. It is usually invoked like this: - -:: - - make DESTDIR=/home/john install - -which will install the concerned software using the installation -prefix, e.g. ``/usr/local`` prepended with the ``DESTDIR`` value which -finally gives ``/home/john/usr/local``. - -WARNING: ``DESTDIR`` may not be used on Windows because installation -prefix usually contains a drive letter like in ``C:/Program Files`` -which cannot be prepended with some other prefix. +whole installation. See :envvar:`DESTDIR` for more information. The installation prefix is also added to :variable:`CMAKE_SYSTEM_PREFIX_PATH` so that :command:`find_package`, :command:`find_program`, diff --git a/Help/variable/CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH.rst b/Help/variable/CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH.rst new file mode 100644 index 000000000..76ca3da02 --- /dev/null +++ b/Help/variable/CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH.rst @@ -0,0 +1,9 @@ +CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH +-------------------------------------- + +Sets the default for whether toolchain-defined rpaths should be removed during +installation. + +``CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH`` is a boolean that provides the +default value for the :prop_tgt:`INSTALL_REMOVE_ENVIRONMENT_RPATH` property +of all subsequently created targets. diff --git a/Help/variable/CMAKE_JOB_POOLS.rst b/Help/variable/CMAKE_JOB_POOLS.rst new file mode 100644 index 000000000..72b50b490 --- /dev/null +++ b/Help/variable/CMAKE_JOB_POOLS.rst @@ -0,0 +1,6 @@ +CMAKE_JOB_POOLS +--------------- + +If the :prop_gbl:`JOB_POOLS` global property is not set, the value +of this variable is used in its place. See :prop_gbl:`JOB_POOLS` +for additional information. diff --git a/Help/variable/CMAKE_JOB_POOL_LINK.rst b/Help/variable/CMAKE_JOB_POOL_LINK.rst index 338f7714e..eeee6e069 100644 --- a/Help/variable/CMAKE_JOB_POOL_LINK.rst +++ b/Help/variable/CMAKE_JOB_POOL_LINK.rst @@ -1,5 +1,5 @@ CMAKE_JOB_POOL_LINK ----------------------- +------------------- This variable is used to initialize the :prop_tgt:`JOB_POOL_LINK` property on all the targets. See :prop_tgt:`JOB_POOL_LINK` diff --git a/Help/variable/CMAKE_LANG_CLANG_TIDY.rst b/Help/variable/CMAKE_LANG_CLANG_TIDY.rst index 492c12c6d..bd49de369 100644 --- a/Help/variable/CMAKE_LANG_CLANG_TIDY.rst +++ b/Help/variable/CMAKE_LANG_CLANG_TIDY.rst @@ -1,6 +1,13 @@ CMAKE_<LANG>_CLANG_TIDY ----------------------- -Default value for :prop_tgt:`<LANG>_CLANG_TIDY` target property. +Default value for :prop_tgt:`<LANG>_CLANG_TIDY` target property +when ``<LANG>`` is ``C`` or ``CXX``. + This variable is used to initialize the property on each target as it is -created. This is done only when ``<LANG>`` is ``C`` or ``CXX``. +created. For example: + +.. code-block:: cmake + + set(CMAKE_CXX_CLANG_TIDY clang-tidy -checks=-*,readability-*) + add_executable(foo foo.cxx) diff --git a/Help/variable/CMAKE_LANG_COMPILER_ARCHITECTURE_ID.rst b/Help/variable/CMAKE_LANG_COMPILER_ARCHITECTURE_ID.rst new file mode 100644 index 000000000..054c64884 --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_ARCHITECTURE_ID.rst @@ -0,0 +1,8 @@ +CMAKE_<LANG>_COMPILER_ARCHITECTURE_ID +------------------------------------- + +An internal variable subject to change. + +This is used to identify the variant of a compiler based on its target +architecture. For some compilers this is needed to determine the correct +usage. diff --git a/Help/variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN.rst b/Help/variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN.rst index 5be935bad..cbe35441e 100644 --- a/Help/variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN.rst +++ b/Help/variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN.rst @@ -6,7 +6,7 @@ The external toolchain for cross-compiling, if supported. Some compiler toolchains do not ship their own auxiliary utilities such as archivers and linkers. The compiler driver may support a command-line argument to specify the location of such tools. -``CMAKE_<LANG>_COMPILER_EXTERNAL_TOOLCHAIN`` may be set to a path to a path to +``CMAKE_<LANG>_COMPILER_EXTERNAL_TOOLCHAIN`` may be set to a path to the external toolchain and will be passed to the compiler driver if supported. This variable may only be set in a toolchain file specified by diff --git a/Help/variable/CMAKE_LANG_COMPILER_ID.rst b/Help/variable/CMAKE_LANG_COMPILER_ID.rst index 0fab10ca8..8eb4fb612 100644 --- a/Help/variable/CMAKE_LANG_COMPILER_ID.rst +++ b/Help/variable/CMAKE_LANG_COMPILER_ID.rst @@ -12,16 +12,19 @@ include: ADSP = Analog VisualDSP++ (analog.com) AppleClang = Apple Clang (apple.com) ARMCC = ARM Compiler (arm.com) + ARMClang = ARM Compiler based on Clang (arm.com) Bruce = Bruce C Compiler CCur = Concurrent Fortran (ccur.com) Clang = LLVM Clang (clang.llvm.org) Cray = Cray Compiler (cray.com) Embarcadero, Borland = Embarcadero (embarcadero.com) + Flang = Flang LLVM Fortran Compiler G95 = G95 Fortran (g95.org) GNU = GNU Compiler Collection (gcc.gnu.org) + GHS = Green Hills Software (www.ghs.com) HP = Hewlett-Packard Compiler (hp.com) + IAR = IAR Systems (iar.com) Intel = Intel Compiler (intel.com) - MIPSpro = SGI MIPSpro (sgi.com) MSVC = Microsoft Visual Studio (microsoft.com) NVIDIA = NVIDIA CUDA Compiler (nvidia.com) OpenWatcom = Open Watcom (openwatcom.org) @@ -32,6 +35,7 @@ include: TI = Texas Instruments (ti.com) TinyCC = Tiny C Compiler (tinycc.org) XL, VisualAge, zOS = IBM XL (ibm.com) + XLClang = IBM Clang-based XL (ibm.com) This variable is not guaranteed to be defined for all compilers or languages. diff --git a/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst b/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst index 7961f609e..6b7e35a0a 100644 --- a/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst +++ b/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst @@ -3,4 +3,5 @@ CMAKE_<LANG>_COMPILER_LAUNCHER Default value for :prop_tgt:`<LANG>_COMPILER_LAUNCHER` target property. This variable is used to initialize the property on each target as it is -created. This is done only when ``<LANG>`` is ``C`` or ``CXX``. +created. This is done only when ``<LANG>`` is ``C``, ``CXX``, ``Fortran``, +``OBJC``, ``OBJCXX``, or ``CUDA``. diff --git a/Help/variable/CMAKE_LANG_COMPILER_PREDEFINES_COMMAND.rst b/Help/variable/CMAKE_LANG_COMPILER_PREDEFINES_COMMAND.rst new file mode 100644 index 000000000..e050f43e6 --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_PREDEFINES_COMMAND.rst @@ -0,0 +1,8 @@ +CMAKE_<LANG>_COMPILER_PREDEFINES_COMMAND +---------------------------------------- + +Command that outputs the compiler pre definitions. + +See :prop_tgt:`AUTOMOC` which uses +:variable:`CMAKE_CXX_COMPILER_PREDEFINES_COMMAND <CMAKE_<LANG>_COMPILER_PREDEFINES_COMMAND>` +to generate the :prop_tgt:`AUTOMOC_COMPILER_PREDEFINES`. diff --git a/Help/variable/CMAKE_LANG_COMPILER_VERSION_INTERNAL.rst b/Help/variable/CMAKE_LANG_COMPILER_VERSION_INTERNAL.rst new file mode 100644 index 000000000..c3cd9801a --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_VERSION_INTERNAL.rst @@ -0,0 +1,8 @@ +CMAKE_<LANG>_COMPILER_VERSION_INTERNAL +-------------------------------------- + +An internal variable subject to change. + +This is used to identify the variant of a compiler based on an internal +version number. For some compilers this is needed to determine the +correct usage. diff --git a/Help/variable/CMAKE_LANG_CPPCHECK.rst b/Help/variable/CMAKE_LANG_CPPCHECK.rst new file mode 100644 index 000000000..50b478fd0 --- /dev/null +++ b/Help/variable/CMAKE_LANG_CPPCHECK.rst @@ -0,0 +1,6 @@ +CMAKE_<LANG>_CPPCHECK +--------------------- + +Default value for :prop_tgt:`<LANG>_CPPCHECK` target property. This variable +is used to initialize the property on each target as it is created. This +is done only when ``<LANG>`` is ``C`` or ``CXX``. diff --git a/Help/variable/CMAKE_LANG_CREATE_SHARED_LIBRARY.rst b/Help/variable/CMAKE_LANG_CREATE_SHARED_LIBRARY.rst index be89f8529..16fcc0344 100644 --- a/Help/variable/CMAKE_LANG_CREATE_SHARED_LIBRARY.rst +++ b/Help/variable/CMAKE_LANG_CREATE_SHARED_LIBRARY.rst @@ -4,4 +4,5 @@ CMAKE_<LANG>_CREATE_SHARED_LIBRARY Rule variable to create a shared library. This is a rule variable that tells CMake how to create a shared -library for the language ``<LANG>``. +library for the language ``<LANG>``. This rule variable is a ``;`` delimited +list of commands to run to perform the linking step. diff --git a/Help/variable/CMAKE_LANG_CREATE_SHARED_MODULE.rst b/Help/variable/CMAKE_LANG_CREATE_SHARED_MODULE.rst index ae5f69d56..807229dec 100644 --- a/Help/variable/CMAKE_LANG_CREATE_SHARED_MODULE.rst +++ b/Help/variable/CMAKE_LANG_CREATE_SHARED_MODULE.rst @@ -4,4 +4,5 @@ CMAKE_<LANG>_CREATE_SHARED_MODULE Rule variable to create a shared module. This is a rule variable that tells CMake how to create a shared -library for the language ``<LANG>``. +library for the language ``<LANG>``. This rule variable is a ``;`` delimited +list of commands to run. diff --git a/Help/variable/CMAKE_LANG_FLAGS.rst b/Help/variable/CMAKE_LANG_FLAGS.rst index c57d92cbf..14b2694ef 100644 --- a/Help/variable/CMAKE_LANG_FLAGS.rst +++ b/Help/variable/CMAKE_LANG_FLAGS.rst @@ -4,3 +4,14 @@ CMAKE_<LANG>_FLAGS Flags for all build types. ``<LANG>`` flags used regardless of the value of :variable:`CMAKE_BUILD_TYPE`. + +This is initialized for each language from environment variables: + +* ``CMAKE_C_FLAGS``: + Initialized by the :envvar:`CFLAGS` environment variable. +* ``CMAKE_CXX_FLAGS``: + Initialized by the :envvar:`CXXFLAGS` environment variable. +* ``CMAKE_CUDA_FLAGS``: + Initialized by the :envvar:`CUDAFLAGS` environment variable. +* ``CMAKE_Fortran_FLAGS``: + Initialized by the :envvar:`FFLAGS` environment variable. diff --git a/Help/variable/CMAKE_LANG_FLAGS_CONFIG.rst b/Help/variable/CMAKE_LANG_FLAGS_CONFIG.rst new file mode 100644 index 000000000..1dbd03640 --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_CONFIG.rst @@ -0,0 +1,4 @@ +CMAKE_<LANG>_FLAGS_<CONFIG> +--------------------------- + +Flags for language ``<LANG>`` when building for the ``<CONFIG>`` configuration. diff --git a/Help/variable/CMAKE_LANG_FLAGS_CONFIG_INIT.rst b/Help/variable/CMAKE_LANG_FLAGS_CONFIG_INIT.rst new file mode 100644 index 000000000..1eb5b3f61 --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_CONFIG_INIT.rst @@ -0,0 +1,10 @@ +CMAKE_<LANG>_FLAGS_<CONFIG>_INIT +-------------------------------- + +Value used to initialize the :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` cache +entry the first time a build tree is configured for language ``<LANG>``. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also :variable:`CMAKE_<LANG>_FLAGS_INIT`. diff --git a/Help/variable/CMAKE_LANG_FLAGS_DEBUG.rst b/Help/variable/CMAKE_LANG_FLAGS_DEBUG.rst index a233d4ad7..6be424aa9 100644 --- a/Help/variable/CMAKE_LANG_FLAGS_DEBUG.rst +++ b/Help/variable/CMAKE_LANG_FLAGS_DEBUG.rst @@ -1,6 +1,5 @@ CMAKE_<LANG>_FLAGS_DEBUG ------------------------ -Flags for ``Debug`` build type or configuration. - -``<LANG>`` flags used when :variable:`CMAKE_BUILD_TYPE` is ``Debug``. +This variable is the ``Debug`` variant of the +:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` variable. diff --git a/Help/variable/CMAKE_LANG_FLAGS_DEBUG_INIT.rst b/Help/variable/CMAKE_LANG_FLAGS_DEBUG_INIT.rst index dcddb2e26..de7fcfc1d 100644 --- a/Help/variable/CMAKE_LANG_FLAGS_DEBUG_INIT.rst +++ b/Help/variable/CMAKE_LANG_FLAGS_DEBUG_INIT.rst @@ -1,10 +1,5 @@ CMAKE_<LANG>_FLAGS_DEBUG_INIT ----------------------------- -Value used to initialize the :variable:`CMAKE_<LANG>_FLAGS_DEBUG` cache -entry the first time a build tree is configured for language ``<LANG>``. -This variable is meant to be set by a :variable:`toolchain file -<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to -the value based on the environment and target platform. - -See also :variable:`CMAKE_<LANG>_FLAGS_INIT`. +This variable is the ``Debug`` variant of the +:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>_INIT` variable. diff --git a/Help/variable/CMAKE_LANG_FLAGS_INIT.rst b/Help/variable/CMAKE_LANG_FLAGS_INIT.rst index 1d32cc3fd..a88d1229e 100644 --- a/Help/variable/CMAKE_LANG_FLAGS_INIT.rst +++ b/Help/variable/CMAKE_LANG_FLAGS_INIT.rst @@ -7,9 +7,5 @@ This variable is meant to be set by a :variable:`toolchain file <CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to the value based on the environment and target platform. -See also the configuration-specific variables: - -* :variable:`CMAKE_<LANG>_FLAGS_DEBUG_INIT` -* :variable:`CMAKE_<LANG>_FLAGS_RELEASE_INIT` -* :variable:`CMAKE_<LANG>_FLAGS_MINSIZEREL_INIT` -* :variable:`CMAKE_<LANG>_FLAGS_RELWITHDEBINFO_INIT` +See also the configuration-specific +:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>_INIT` variable. diff --git a/Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL.rst b/Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL.rst index a9436c184..634fab9d6 100644 --- a/Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL.rst +++ b/Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL.rst @@ -1,7 +1,5 @@ CMAKE_<LANG>_FLAGS_MINSIZEREL ----------------------------- -Flags for ``MinSizeRel`` build type or configuration. - -``<LANG>`` flags used when :variable:`CMAKE_BUILD_TYPE` is ``MinSizeRel`` -(short for minimum size release). +This variable is the ``MinSizeRel`` variant of the +:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` variable. diff --git a/Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL_INIT.rst b/Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL_INIT.rst index c0aedf403..1e7003cec 100644 --- a/Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL_INIT.rst +++ b/Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL_INIT.rst @@ -1,10 +1,5 @@ CMAKE_<LANG>_FLAGS_MINSIZEREL_INIT ---------------------------------- -Value used to initialize the :variable:`CMAKE_<LANG>_FLAGS_MINSIZEREL` -cache entry the first time a build tree is configured for language ``<LANG>``. -This variable is meant to be set by a :variable:`toolchain file -<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to -the value based on the environment and target platform. - -See also :variable:`CMAKE_<LANG>_FLAGS_INIT`. +This variable is the ``MinSizeRel`` variant of the +:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>_INIT` variable. diff --git a/Help/variable/CMAKE_LANG_FLAGS_RELEASE.rst b/Help/variable/CMAKE_LANG_FLAGS_RELEASE.rst index ffc5d795d..3baeab090 100644 --- a/Help/variable/CMAKE_LANG_FLAGS_RELEASE.rst +++ b/Help/variable/CMAKE_LANG_FLAGS_RELEASE.rst @@ -1,6 +1,5 @@ CMAKE_<LANG>_FLAGS_RELEASE -------------------------- -Flags for ``Release`` build type or configuration. - -``<LANG>`` flags used when :variable:`CMAKE_BUILD_TYPE` is ``Release``. +This variable is the ``Release`` variant of the +:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` variable. diff --git a/Help/variable/CMAKE_LANG_FLAGS_RELEASE_INIT.rst b/Help/variable/CMAKE_LANG_FLAGS_RELEASE_INIT.rst index 59f92ff6f..e7c73fea6 100644 --- a/Help/variable/CMAKE_LANG_FLAGS_RELEASE_INIT.rst +++ b/Help/variable/CMAKE_LANG_FLAGS_RELEASE_INIT.rst @@ -1,10 +1,5 @@ CMAKE_<LANG>_FLAGS_RELEASE_INIT ------------------------------- -Value used to initialize the :variable:`CMAKE_<LANG>_FLAGS_RELEASE` -cache entry the first time a build tree is configured for language ``<LANG>``. -This variable is meant to be set by a :variable:`toolchain file -<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to -the value based on the environment and target platform. - -See also :variable:`CMAKE_<LANG>_FLAGS_INIT`. +This variable is the ``Release`` variant of the +:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>_INIT` variable. diff --git a/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO.rst b/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO.rst index 962768e44..67a507377 100644 --- a/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO.rst +++ b/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO.rst @@ -1,7 +1,5 @@ CMAKE_<LANG>_FLAGS_RELWITHDEBINFO --------------------------------- -Flags for ``RelWithDebInfo`` type or configuration. - -``<LANG>`` flags used when :variable:`CMAKE_BUILD_TYPE` is ``RelWithDebInfo`` -(short for Release With Debug Information). +This variable is the ``RelWithDebInfo`` variant of the +:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` variable. diff --git a/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT.rst b/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT.rst index 915f02305..3ab39753d 100644 --- a/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT.rst +++ b/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT.rst @@ -1,10 +1,5 @@ CMAKE_<LANG>_FLAGS_RELWITHDEBINFO_INIT -------------------------------------- -Value used to initialize the :variable:`CMAKE_<LANG>_FLAGS_RELWITHDEBINFO` -cache entry the first time a build tree is configured for language ``<LANG>``. -This variable is meant to be set by a :variable:`toolchain file -<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to -the value based on the environment and target platform. - -See also :variable:`CMAKE_<LANG>_FLAGS_INIT`. +This variable is the ``RelWithDebInfo`` variant of the +:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>_INIT` variable. diff --git a/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_DEBUG.rst b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_DEBUG.rst deleted file mode 100644 index 1f639a3ba..000000000 --- a/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_DEBUG.rst +++ /dev/null @@ -1,6 +0,0 @@ -CMAKE_<LANG>_GHS_KERNEL_FLAGS_DEBUG ------------------------------------ - -GHS kernel flags for ``Debug`` build type or configuration. - -``<LANG>`` flags used when :variable:`CMAKE_BUILD_TYPE` is ``Debug``. diff --git a/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_MINSIZEREL.rst b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_MINSIZEREL.rst deleted file mode 100644 index 94e21150a..000000000 --- a/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_MINSIZEREL.rst +++ /dev/null @@ -1,7 +0,0 @@ -CMAKE_<LANG>_GHS_KERNEL_FLAGS_MINSIZEREL ----------------------------------------- - -GHS kernel flags for ``MinSizeRel`` build type or configuration. - -``<LANG>`` flags used when :variable:`CMAKE_BUILD_TYPE` is ``MinSizeRel`` -(short for minimum size release). diff --git a/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELEASE.rst b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELEASE.rst deleted file mode 100644 index 74566efca..000000000 --- a/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELEASE.rst +++ /dev/null @@ -1,6 +0,0 @@ -CMAKE_<LANG>_GHS_KERNEL_FLAGS_RELEASE -------------------------------------- - -GHS kernel flags for ``Release`` build type or configuration. - -``<LANG>`` flags used when :variable:`CMAKE_BUILD_TYPE` is ``Release``. diff --git a/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELWITHDEBINFO.rst b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELWITHDEBINFO.rst deleted file mode 100644 index d148193d8..000000000 --- a/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELWITHDEBINFO.rst +++ /dev/null @@ -1,7 +0,0 @@ -CMAKE_<LANG>_GHS_KERNEL_FLAGS_RELWITHDEBINFO --------------------------------------------- - -GHS kernel flags for ``RelWithDebInfo`` type or configuration. - -``<LANG>`` flags used when :variable:`CMAKE_BUILD_TYPE` is ``RelWithDebInfo`` -(short for Release With Debug Information). diff --git a/Help/variable/CMAKE_LANG_IMPLICIT_INCLUDE_DIRECTORIES.rst b/Help/variable/CMAKE_LANG_IMPLICIT_INCLUDE_DIRECTORIES.rst index cc8085107..e361fd98e 100644 --- a/Help/variable/CMAKE_LANG_IMPLICIT_INCLUDE_DIRECTORIES.rst +++ b/Help/variable/CMAKE_LANG_IMPLICIT_INCLUDE_DIRECTORIES.rst @@ -6,4 +6,9 @@ Directories implicitly searched by the compiler for header files. CMake does not explicitly specify these directories on compiler command lines for language ``<LANG>``. This prevents system include directories from being treated as user include directories on some -compilers. +compilers, which is important for ``C``, ``CXX``, and ``CUDA`` to +avoid overriding standard library headers. + +This value is not used for ``Fortran`` because it has no standard +library headers and some compilers do not search their implicit +include directories for module ``.mod`` files. diff --git a/Help/variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES.rst b/Help/variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES.rst index a0bd8303c..e9e04be6e 100644 --- a/Help/variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES.rst +++ b/Help/variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES.rst @@ -9,9 +9,12 @@ These paths are implicit linker search directories for the compiler's language. CMake automatically detects these directories for each language and reports the results in this variable. -When a library in one of these directories is given by full path to -:command:`target_link_libraries` CMake will generate the ``-l<name>`` form on -link lines to ensure the linker searches its implicit directories for the -library. Note that some toolchains read implicit directories from an -environment variable such as ``LIBRARY_PATH`` so keep its value consistent -when operating in a given build tree. +Some toolchains read implicit directories from an environment variable such as +``LIBRARY_PATH``. If using such an environment variable, keep its value +consistent when operating in a given build tree because CMake saves the value +detected when first creating a build tree. + +If policy :policy:`CMP0060` is not set to ``NEW``, then when a library in one +of these directories is given by full path to :command:`target_link_libraries` +CMake will generate the ``-l<name>`` form on link lines for historical +purposes. diff --git a/Help/variable/CMAKE_LANG_LINKER_WRAPPER_FLAG.rst b/Help/variable/CMAKE_LANG_LINKER_WRAPPER_FLAG.rst new file mode 100644 index 000000000..df514075c --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINKER_WRAPPER_FLAG.rst @@ -0,0 +1,39 @@ +CMAKE_<LANG>_LINKER_WRAPPER_FLAG +-------------------------------- + +Defines the syntax of compiler driver option to pass options to the linker +tool. It will be used to translate the ``LINKER:`` prefix in the link options +(see :command:`add_link_options` and :command:`target_link_options`). + +This variable holds a :ref:`semicolon-separated list <CMake Language Lists>` of tokens. +If a space (i.e. " ") is specified as last token, flag and ``LINKER:`` +arguments will be specified as separate arguments to the compiler driver. +The :variable:`CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP` variable can be specified +to manage concatenation of arguments. + +For example, for ``Clang`` we have: + +.. code-block:: cmake + + set (CMAKE_C_LINKER_WRAPPER_FLAG "-Xlinker" " ") + +Specifying ``"LINKER:-z,defs"`` will be transformed in +``-Xlinker -z -Xlinker defs``. + +For ``GNU GCC``: + +.. code-block:: cmake + + set (CMAKE_C_LINKER_WRAPPER_FLAG "-Wl,") + set (CMAKE_C_LINKER_WRAPPER_FLAG_SEP ",") + +Specifying ``"LINKER:-z,defs"`` will be transformed in ``-Wl,-z,defs``. + +And for ``SunPro``: + +.. code-block:: cmake + + set (CMAKE_C_LINKER_WRAPPER_FLAG "-Qoption" "ld" " ") + set (CMAKE_C_LINKER_WRAPPER_FLAG_SEP ",") + +Specifying ``"LINKER:-z,defs"`` will be transformed in ``-Qoption ld -z,defs``. diff --git a/Help/variable/CMAKE_LANG_LINKER_WRAPPER_FLAG_SEP.rst b/Help/variable/CMAKE_LANG_LINKER_WRAPPER_FLAG_SEP.rst new file mode 100644 index 000000000..faf14815c --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINKER_WRAPPER_FLAG_SEP.rst @@ -0,0 +1,9 @@ +CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP +------------------------------------ + +This variable is used with :variable:`CMAKE_<LANG>_LINKER_WRAPPER_FLAG` +variable to format ``LINKER:`` prefix in the link options +(see :command:`add_link_options` and :command:`target_link_options`). + +When specified, arguments of the ``LINKER:`` prefix will be concatenated using +this value as separator. diff --git a/Help/variable/CMAKE_LANG_LINK_LIBRARY_FILE_FLAG.rst b/Help/variable/CMAKE_LANG_LINK_LIBRARY_FILE_FLAG.rst new file mode 100644 index 000000000..d54f08022 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_LIBRARY_FILE_FLAG.rst @@ -0,0 +1,8 @@ +CMAKE_<LANG>_LINK_LIBRARY_FILE_FLAG +----------------------------------- + +Language-specific flag to be used to link a library specified by +a path to its file. + +The flag will be used before a library file path is given to the +linker. This is needed only on very few platforms. diff --git a/Help/variable/CMAKE_LANG_LINK_LIBRARY_FLAG.rst b/Help/variable/CMAKE_LANG_LINK_LIBRARY_FLAG.rst new file mode 100644 index 000000000..d7bb0d875 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_LIBRARY_FLAG.rst @@ -0,0 +1,7 @@ +CMAKE_<LANG>_LINK_LIBRARY_FLAG +------------------------------ + +Flag to be used to link a library into a shared library or executable. + +This flag will be used to specify a library to link to a shared library or an +executable for the specific language. On most compilers this is ``-l``. diff --git a/Help/variable/CMAKE_LANG_LINK_LIBRARY_SUFFIX.rst b/Help/variable/CMAKE_LANG_LINK_LIBRARY_SUFFIX.rst new file mode 100644 index 000000000..a37865795 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_LIBRARY_SUFFIX.rst @@ -0,0 +1,6 @@ +CMAKE_<LANG>_LINK_LIBRARY_SUFFIX +-------------------------------- + +Language-specific suffix for libraries that you link to. + +The suffix to use for the end of a library filename, ``.lib`` on Windows. diff --git a/Help/variable/CMAKE_LIBRARY_PATH.rst b/Help/variable/CMAKE_LIBRARY_PATH.rst index b1770dc26..8135b6581 100644 --- a/Help/variable/CMAKE_LIBRARY_PATH.rst +++ b/Help/variable/CMAKE_LIBRARY_PATH.rst @@ -1,7 +1,7 @@ CMAKE_LIBRARY_PATH ------------------ -:ref:`;-list <CMake Language Lists>` of directories specifying a search path +:ref:`Semicolon-separated list <CMake Language Lists>` of directories specifying a search path for the :command:`find_library` command. By default it is empty, it is intended to be set by the project. See also :variable:`CMAKE_SYSTEM_LIBRARY_PATH` and :variable:`CMAKE_PREFIX_PATH`. diff --git a/Help/variable/CMAKE_LINK_DIRECTORIES_BEFORE.rst b/Help/variable/CMAKE_LINK_DIRECTORIES_BEFORE.rst new file mode 100644 index 000000000..026ca35b3 --- /dev/null +++ b/Help/variable/CMAKE_LINK_DIRECTORIES_BEFORE.rst @@ -0,0 +1,9 @@ +CMAKE_LINK_DIRECTORIES_BEFORE +----------------------------- + +Whether to append or prepend directories by default in +:command:`link_directories`. + +This variable affects the default behavior of the :command:`link_directories` +command. Setting this variable to ``ON`` is equivalent to using the ``BEFORE`` +option in all uses of that command. diff --git a/Help/variable/CMAKE_MACOSX_BUNDLE.rst b/Help/variable/CMAKE_MACOSX_BUNDLE.rst index 0badaf0da..43ddff517 100644 --- a/Help/variable/CMAKE_MACOSX_BUNDLE.rst +++ b/Help/variable/CMAKE_MACOSX_BUNDLE.rst @@ -5,3 +5,6 @@ Default value for :prop_tgt:`MACOSX_BUNDLE` of targets. This variable is used to initialize the :prop_tgt:`MACOSX_BUNDLE` property on all the targets. See that target property for additional information. + +This variable is set to ``ON`` by default if :variable:`CMAKE_SYSTEM_NAME` +equals to :ref:`iOS, tvOS or watchOS <Cross Compiling for iOS, tvOS, or watchOS>`. diff --git a/Help/variable/CMAKE_MACOSX_RPATH.rst b/Help/variable/CMAKE_MACOSX_RPATH.rst index 042e807f5..2fc648d61 100644 --- a/Help/variable/CMAKE_MACOSX_RPATH.rst +++ b/Help/variable/CMAKE_MACOSX_RPATH.rst @@ -1,7 +1,7 @@ CMAKE_MACOSX_RPATH ------------------- -Whether to use rpaths on OS X and iOS. +Whether to use rpaths on macOS and iOS. This variable is used to initialize the :prop_tgt:`MACOSX_RPATH` property on all targets. diff --git a/Help/variable/CMAKE_MAKE_PROGRAM.rst b/Help/variable/CMAKE_MAKE_PROGRAM.rst index a3b997af2..a3c8b7c8a 100644 --- a/Help/variable/CMAKE_MAKE_PROGRAM.rst +++ b/Help/variable/CMAKE_MAKE_PROGRAM.rst @@ -19,15 +19,11 @@ to configure the project: This generator stores ``CMAKE_MAKE_PROGRAM`` in the CMake cache so that it may be edited by the user. -* The :generator:`Xcode` generator sets this to ``xcodebuild`` (or possibly an - otherwise undocumented ``cmakexbuild`` wrapper implementing some - workarounds). +* The :generator:`Xcode` generator sets this to ``xcodebuild``. This generator prefers to lookup the build tool at build time rather than to store ``CMAKE_MAKE_PROGRAM`` in the CMake cache - ahead of time. This is because ``xcodebuild`` is easy to find, - the ``cmakexbuild`` wrapper is needed only for older Xcode versions, - and the path to ``cmakexbuild`` may be outdated if CMake itself moves. + ahead of time. This is because ``xcodebuild`` is easy to find. For compatibility with versions of CMake prior to 3.2, if a user or project explicitly adds ``CMAKE_MAKE_PROGRAM`` to @@ -55,9 +51,12 @@ to configure the project: the CMake cache then CMake will use the specified value if possible. -* The :generator:`Green Hills MULTI` generator sets this to ``gbuild``. - If a user or project explicitly adds ``CMAKE_MAKE_PROGRAM`` to - the CMake cache then CMake will use the specified value. +* The :generator:`Green Hills MULTI` generator sets this to the full + path to ``gbuild.exe(Windows)`` or ``gbuild(Linux)`` based upon + the toolset being used. + + Once the generator has initialized a particular value for this + variable, changing the value has undefined behavior. The ``CMAKE_MAKE_PROGRAM`` variable is set for use by project code. The value is also used by the :manual:`cmake(1)` ``--build`` and diff --git a/Help/variable/CMAKE_MAXIMUM_RECURSION_DEPTH.rst b/Help/variable/CMAKE_MAXIMUM_RECURSION_DEPTH.rst new file mode 100644 index 000000000..7110b1685 --- /dev/null +++ b/Help/variable/CMAKE_MAXIMUM_RECURSION_DEPTH.rst @@ -0,0 +1,33 @@ +CMAKE_MAXIMUM_RECURSION_DEPTH +----------------------------- + +Maximum recursion depth for CMake scripts. It is intended to be set on the +command line with ``-DCMAKE_MAXIMUM_RECURSION_DEPTH=<x>``, or within +``CMakeLists.txt`` by projects that require a large recursion depth. Projects +that set this variable should provide the user with a way to override it. For +example: + +.. code-block:: cmake + + # About to perform deeply recursive actions + if(NOT CMAKE_MAXIMUM_RECURSION_DEPTH) + set(CMAKE_MAXIMUM_RECURSION_DEPTH 2000) + endif() + +If it is not set, or is set to a non-integer value, a sensible default limit is +used. If the recursion limit is reached, the script terminates immediately with +a fatal error. + +Calling any of the following commands increases the recursion depth: + +* :command:`include` +* :command:`find_package` +* :command:`add_subdirectory` +* :command:`try_compile` +* :command:`ctest_read_custom_files` +* :command:`ctest_run_script` (unless ``NEW_PROCESS`` is specified) +* User-defined :command:`function`'s and :command:`macro`'s (note that + :command:`function` and :command:`macro` themselves don't increase recursion + depth) +* Reading or writing variables that are being watched by a + :command:`variable_watch` diff --git a/Help/variable/CMAKE_MESSAGE_INDENT.rst b/Help/variable/CMAKE_MESSAGE_INDENT.rst new file mode 100644 index 000000000..7e44a4cad --- /dev/null +++ b/Help/variable/CMAKE_MESSAGE_INDENT.rst @@ -0,0 +1,32 @@ +CMAKE_MESSAGE_INDENT +-------------------- + +The :command:`message` command joins the strings from this list and for +log levels of ``NOTICE`` and below, it prepends the resultant string to +each line of the message. + +Example: + +.. code-block:: cmake + + list(APPEND listVar one two three) + + message(VERBOSE [[Collected items in the "listVar":]]) + list(APPEND CMAKE_MESSAGE_INDENT " ") + + foreach(item IN LISTS listVar) + message(VERBOSE ${item}) + endforeach() + + list(POP_BACK CMAKE_MESSAGE_INDENT) + message(VERBOSE "No more indent") + +Which results in the following output: + +.. code-block:: none + + -- Collected items in the "listVar": + -- one + -- two + -- three + -- No more indent diff --git a/Help/variable/CMAKE_MFC_FLAG.rst b/Help/variable/CMAKE_MFC_FLAG.rst index 5a392bfbb..2c4d1c551 100644 --- a/Help/variable/CMAKE_MFC_FLAG.rst +++ b/Help/variable/CMAKE_MFC_FLAG.rst @@ -1,15 +1,16 @@ CMAKE_MFC_FLAG -------------- -Tell cmake to use MFC for an executable or dll. +Use the MFC library for an executable or dll. -This can be set in a ``CMakeLists.txt`` file and will enable MFC in the -application. It should be set to ``1`` for the static MFC library, and ``2`` -for the shared MFC library. This is used in Visual Studio -project files. The CMakeSetup dialog used MFC and the ``CMakeLists.txt`` -looks like this: +Enables the use of the Microsoft Foundation Classes (MFC). +It should be set to ``1`` for the static MFC library, and +``2`` for the shared MFC library. This is used in Visual Studio +project files. -:: +Usage example: + +.. code-block:: cmake add_definitions(-D_AFXDLL) set(CMAKE_MFC_FLAG 2) diff --git a/Help/variable/CMAKE_MINIMUM_REQUIRED_VERSION.rst b/Help/variable/CMAKE_MINIMUM_REQUIRED_VERSION.rst index 5a51634db..f466468d8 100644 --- a/Help/variable/CMAKE_MINIMUM_REQUIRED_VERSION.rst +++ b/Help/variable/CMAKE_MINIMUM_REQUIRED_VERSION.rst @@ -1,7 +1,5 @@ CMAKE_MINIMUM_REQUIRED_VERSION ------------------------------ -Version specified to :command:`cmake_minimum_required` command - -Variable containing the ``VERSION`` component specified in the -:command:`cmake_minimum_required` command. +The ``<min>`` version of CMake given to the most recent call to the +:command:`cmake_minimum_required(VERSION)` command. diff --git a/Help/variable/CMAKE_MODULE_PATH.rst b/Help/variable/CMAKE_MODULE_PATH.rst index 5ea7cbbc0..4dcf6b526 100644 --- a/Help/variable/CMAKE_MODULE_PATH.rst +++ b/Help/variable/CMAKE_MODULE_PATH.rst @@ -1,7 +1,7 @@ CMAKE_MODULE_PATH ----------------- -:ref:`;-list <CMake Language Lists>` of directories specifying a search path -for CMake modules to be loaded by the the :command:`include` or +:ref:`Semicolon-separated list <CMake Language Lists>` of directories specifying a search path +for CMake modules to be loaded by the :command:`include` or :command:`find_package` commands before checking the default modules that come with CMake. By default it is empty, it is intended to be set by the project. diff --git a/Help/variable/CMAKE_MSVCIDE_RUN_PATH.rst b/Help/variable/CMAKE_MSVCIDE_RUN_PATH.rst new file mode 100644 index 000000000..22e727f37 --- /dev/null +++ b/Help/variable/CMAKE_MSVCIDE_RUN_PATH.rst @@ -0,0 +1,10 @@ +CMAKE_MSVCIDE_RUN_PATH +---------------------- + +Extra PATH locations that should be used when executing +:command:`add_custom_command` or :command:`add_custom_target` when using the +:generator:`Visual Studio 9 2008` (or above) generator. This allows +for running commands and using dll's that the IDE environment is not aware of. + +If not set explicitly the value is initialized by the ``CMAKE_MSVCIDE_RUN_PATH`` +environment variable, if set, and otherwise left empty. diff --git a/Help/variable/CMAKE_MSVC_RUNTIME_LIBRARY.rst b/Help/variable/CMAKE_MSVC_RUNTIME_LIBRARY.rst new file mode 100644 index 000000000..8b54e7ecc --- /dev/null +++ b/Help/variable/CMAKE_MSVC_RUNTIME_LIBRARY.rst @@ -0,0 +1,32 @@ +CMAKE_MSVC_RUNTIME_LIBRARY +-------------------------- + +Select the MSVC runtime library for use by compilers targeting the MSVC ABI. +This variable is used to initialize the :prop_tgt:`MSVC_RUNTIME_LIBRARY` +property on all targets as they are created. It is also propagated by +calls to the :command:`try_compile` command into the test project. + +The allowed values are: + +.. include:: ../prop_tgt/MSVC_RUNTIME_LIBRARY-VALUES.txt + +Use :manual:`generator expressions <cmake-generator-expressions(7)>` to +support per-configuration specification. For example, the code: + +.. code-block:: cmake + + set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>") + +selects for all following targets a multi-threaded statically-linked runtime +library with or without debug information depending on the configuration. + +If this variable is not set then the :prop_tgt:`MSVC_RUNTIME_LIBRARY` target +property will not be set automatically. If that property is not set then +CMake uses the default value ``MultiThreaded$<$<CONFIG:Debug>:Debug>DLL`` +to select a MSVC runtime library. + +.. note:: + + This variable has effect only when policy :policy:`CMP0091` is set to ``NEW`` + prior to the first :command:`project` or :command:`enable_language` command + that enables a language using a compiler targeting the MSVC ABI. diff --git a/Help/variable/CMAKE_NETRC.rst b/Help/variable/CMAKE_NETRC.rst new file mode 100644 index 000000000..903ec31b6 --- /dev/null +++ b/Help/variable/CMAKE_NETRC.rst @@ -0,0 +1,9 @@ +CMAKE_NETRC +----------- + +This variable is used to initialize the ``NETRC`` option for +:command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands and the +module :module:`ExternalProject`. See those commands for additional +information. + +The local option takes precedence over this variable. diff --git a/Help/variable/CMAKE_NETRC_FILE.rst b/Help/variable/CMAKE_NETRC_FILE.rst new file mode 100644 index 000000000..0f09afe86 --- /dev/null +++ b/Help/variable/CMAKE_NETRC_FILE.rst @@ -0,0 +1,9 @@ +CMAKE_NETRC_FILE +---------------- + +This variable is used to initialize the ``NETRC_FILE`` option for +:command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands and the +module :module:`ExternalProject`. See those commands for additional +information. + +The local option takes precedence over this variable. diff --git a/Help/variable/CMAKE_OBJCXX_EXTENSIONS.rst b/Help/variable/CMAKE_OBJCXX_EXTENSIONS.rst new file mode 100644 index 000000000..8afa6f275 --- /dev/null +++ b/Help/variable/CMAKE_OBJCXX_EXTENSIONS.rst @@ -0,0 +1,11 @@ +CMAKE_OBJCXX_EXTENSIONS +----------------------- + +Default value for :prop_tgt:`OBJCXX_EXTENSIONS` property of targets. + +This variable is used to initialize the :prop_tgt:`OBJCXX_EXTENSIONS` +property on all targets. See that target property for additional +information. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_OBJCXX_STANDARD.rst b/Help/variable/CMAKE_OBJCXX_STANDARD.rst new file mode 100644 index 000000000..4e5016a40 --- /dev/null +++ b/Help/variable/CMAKE_OBJCXX_STANDARD.rst @@ -0,0 +1,11 @@ +CMAKE_OBJCXX_STANDARD +--------------------- + +Default value for :prop_tgt:`OBJCXX_STANDARD` property of targets. + +This variable is used to initialize the :prop_tgt:`OBJCXX_STANDARD` +property on all targets. See that target property for additional +information. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_OBJCXX_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_OBJCXX_STANDARD_REQUIRED.rst new file mode 100644 index 000000000..3a0602acf --- /dev/null +++ b/Help/variable/CMAKE_OBJCXX_STANDARD_REQUIRED.rst @@ -0,0 +1,11 @@ +CMAKE_OBJCXX_STANDARD_REQUIRED +------------------------------ + +Default value for :prop_tgt:`OBJCXX_STANDARD_REQUIRED` property of targets. + +This variable is used to initialize the :prop_tgt:`OBJCXX_STANDARD_REQUIRED` +property on all targets. See that target property for additional +information. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_OBJC_EXTENSIONS.rst b/Help/variable/CMAKE_OBJC_EXTENSIONS.rst new file mode 100644 index 000000000..d9619d8f2 --- /dev/null +++ b/Help/variable/CMAKE_OBJC_EXTENSIONS.rst @@ -0,0 +1,11 @@ +CMAKE_OBJC_EXTENSIONS +--------------------- + +Default value for :prop_tgt:`OBJC_EXTENSIONS` property of targets. + +This variable is used to initialize the :prop_tgt:`OBJC_EXTENSIONS` +property on all targets. See that target property for additional +information. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_OBJC_STANDARD.rst b/Help/variable/CMAKE_OBJC_STANDARD.rst new file mode 100644 index 000000000..976c44145 --- /dev/null +++ b/Help/variable/CMAKE_OBJC_STANDARD.rst @@ -0,0 +1,11 @@ +CMAKE_OBJC_STANDARD +------------------- + +Default value for :prop_tgt:`OBJC_STANDARD` property of targets. + +This variable is used to initialize the :prop_tgt:`OBJC_STANDARD` +property on all targets. See that target property for additional +information. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_OBJC_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_OBJC_STANDARD_REQUIRED.rst new file mode 100644 index 000000000..5c02096dc --- /dev/null +++ b/Help/variable/CMAKE_OBJC_STANDARD_REQUIRED.rst @@ -0,0 +1,11 @@ +CMAKE_OBJC_STANDARD_REQUIRED +---------------------------- + +Default value for :prop_tgt:`OBJC_STANDARD_REQUIRED` property of targets. + +This variable is used to initialize the :prop_tgt:`OBJC_STANDARD_REQUIRED` +property on all targets. See that target property for additional +information. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_OSX_ARCHITECTURES.rst b/Help/variable/CMAKE_OSX_ARCHITECTURES.rst index 93916dd62..fdaca28e3 100644 --- a/Help/variable/CMAKE_OSX_ARCHITECTURES.rst +++ b/Help/variable/CMAKE_OSX_ARCHITECTURES.rst @@ -1,10 +1,10 @@ CMAKE_OSX_ARCHITECTURES ----------------------- -Target specific architectures for OS X and iOS. +Target specific architectures for macOS and iOS. This variable is used to initialize the :prop_tgt:`OSX_ARCHITECTURES` -property on each target as it is creaed. See that target property +property on each target as it is created. See that target property for additional information. .. include:: CMAKE_OSX_VARIABLE.txt diff --git a/Help/variable/CMAKE_OSX_DEPLOYMENT_TARGET.rst b/Help/variable/CMAKE_OSX_DEPLOYMENT_TARGET.rst index 4fb2caa4f..9df5edda6 100644 --- a/Help/variable/CMAKE_OSX_DEPLOYMENT_TARGET.rst +++ b/Help/variable/CMAKE_OSX_DEPLOYMENT_TARGET.rst @@ -1,10 +1,12 @@ CMAKE_OSX_DEPLOYMENT_TARGET --------------------------- -Specify the minimum version of OS X on which the target binaries are -to be deployed. CMake uses this value for the ``-mmacosx-version-min`` -flag and to help choose the default SDK -(see :variable:`CMAKE_OSX_SYSROOT`). +Specify the minimum version of the target platform (e.g. macOS or iOS) +on which the target binaries are to be deployed. CMake uses this +variable value for the ``-mmacosx-version-min`` flag or their respective +target platform equivalents. For older Xcode versions that shipped +multiple macOS SDKs this variable also helps to choose the SDK in case +:variable:`CMAKE_OSX_SYSROOT` is unset. If not set explicitly the value is initialized by the ``MACOSX_DEPLOYMENT_TARGET`` environment variable, if set, diff --git a/Help/variable/CMAKE_OSX_SYSROOT.rst b/Help/variable/CMAKE_OSX_SYSROOT.rst index f1d58c6b5..db9fccdd1 100644 --- a/Help/variable/CMAKE_OSX_SYSROOT.rst +++ b/Help/variable/CMAKE_OSX_SYSROOT.rst @@ -1,7 +1,7 @@ CMAKE_OSX_SYSROOT ----------------- -Specify the location or name of the OS X platform SDK to be used. +Specify the location or name of the macOS platform SDK to be used. CMake uses this value to compute the value of the ``-isysroot`` flag or equivalent and to help the ``find_*`` commands locate files in the SDK. diff --git a/Help/variable/CMAKE_OSX_VARIABLE.txt b/Help/variable/CMAKE_OSX_VARIABLE.txt index 385f871f3..16f3c1a1a 100644 --- a/Help/variable/CMAKE_OSX_VARIABLE.txt +++ b/Help/variable/CMAKE_OSX_VARIABLE.txt @@ -2,5 +2,10 @@ The value of this variable should be set prior to the first :command:`project` or :command:`enable_language` command invocation because it may influence configuration of the toolchain and flags. It is intended to be set locally by the user creating a build tree. +This variable should be set as a ``CACHE`` entry (or else CMake may +remove it while initializing a cache entry of the same name). -This variable is ignored on platforms other than OS X. +Despite the ``OSX`` part in the variable name(s) they apply also to +other SDKs than macOS like iOS, tvOS, or watchOS. + +This variable is ignored on platforms other than Apple. diff --git a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst index aa23b65f9..fc52e7b5d 100644 --- a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst +++ b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst @@ -19,6 +19,10 @@ warn by default: policy :policy:`CMP0066`. * ``CMAKE_POLICY_WARNING_CMP0067`` controls the warning for policy :policy:`CMP0067`. +* ``CMAKE_POLICY_WARNING_CMP0082`` controls the warning for + policy :policy:`CMP0082`. +* ``CMAKE_POLICY_WARNING_CMP0089`` controls the warning for + policy :policy:`CMP0089`. This variable should not be set by a project in CMake code. Project developers running CMake may set this variable in their cache to diff --git a/Help/variable/CMAKE_PREFIX_PATH.rst b/Help/variable/CMAKE_PREFIX_PATH.rst index c2a4a6038..1d4fd0b42 100644 --- a/Help/variable/CMAKE_PREFIX_PATH.rst +++ b/Help/variable/CMAKE_PREFIX_PATH.rst @@ -1,7 +1,7 @@ CMAKE_PREFIX_PATH ----------------- -:ref:`;-list <CMake Language Lists>` of directories specifying installation +:ref:`Semicolon-separated list <CMake Language Lists>` of directories specifying installation *prefixes* to be searched by the :command:`find_package`, :command:`find_program`, :command:`find_library`, :command:`find_file`, and :command:`find_path` commands. Each command will add appropriate diff --git a/Help/variable/CMAKE_PROGRAM_PATH.rst b/Help/variable/CMAKE_PROGRAM_PATH.rst index 799e1192c..2d0c090df 100644 --- a/Help/variable/CMAKE_PROGRAM_PATH.rst +++ b/Help/variable/CMAKE_PROGRAM_PATH.rst @@ -1,7 +1,7 @@ CMAKE_PROGRAM_PATH ------------------ -:ref:`;-list <CMake Language Lists>` of directories specifying a search path +:ref:`Semicolon-separated list <CMake Language Lists>` of directories specifying a search path for the :command:`find_program` command. By default it is empty, it is intended to be set by the project. See also :variable:`CMAKE_SYSTEM_PROGRAM_PATH` and :variable:`CMAKE_PREFIX_PATH`. diff --git a/Help/variable/CMAKE_PROJECT_DESCRIPTION.rst b/Help/variable/CMAKE_PROJECT_DESCRIPTION.rst index f1911eced..51b0592ea 100644 --- a/Help/variable/CMAKE_PROJECT_DESCRIPTION.rst +++ b/Help/variable/CMAKE_PROJECT_DESCRIPTION.rst @@ -1,7 +1,35 @@ CMAKE_PROJECT_DESCRIPTION ------------------------- -The description of the current project. +The description of the top level project. -This specifies description of the current project from the closest inherited -:command:`project` command. +This variable holds the description of the project as specified in the top +level CMakeLists.txt file by a :command:`project` command. In the event that +the top level CMakeLists.txt contains multiple :command:`project` calls, +the most recently called one from that top level CMakeLists.txt will determine +the value that ``CMAKE_PROJECT_DESCRIPTION`` contains. For example, consider +the following top level CMakeLists.txt: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.0) + project(First DESCRIPTION "I am First") + project(Second DESCRIPTION "I am Second") + add_subdirectory(sub) + project(Third DESCRIPTION "I am Third") + +And ``sub/CMakeLists.txt`` with the following contents: + +.. code-block:: cmake + + project(SubProj DESCRIPTION "I am SubProj") + message("CMAKE_PROJECT_DESCRIPTION = ${CMAKE_PROJECT_DESCRIPTION}") + +The most recently seen :command:`project` command from the top level +CMakeLists.txt would be ``project(Second ...)``, so this will print:: + + CMAKE_PROJECT_DESCRIPTION = I am Second + +To obtain the description from the most recent call to :command:`project` in +the current directory scope or above, see the :variable:`PROJECT_DESCRIPTION` +variable. diff --git a/Help/variable/CMAKE_PROJECT_HOMEPAGE_URL.rst b/Help/variable/CMAKE_PROJECT_HOMEPAGE_URL.rst new file mode 100644 index 000000000..ee0bf7c19 --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_HOMEPAGE_URL.rst @@ -0,0 +1,35 @@ +CMAKE_PROJECT_HOMEPAGE_URL +-------------------------- + +The homepage URL of the top level project. + +This variable holds the homepage URL of the project as specified in the top +level CMakeLists.txt file by a :command:`project` command. In the event that +the top level CMakeLists.txt contains multiple :command:`project` calls, +the most recently called one from that top level CMakeLists.txt will determine +the value that ``CMAKE_PROJECT_HOMEPAGE_URL`` contains. For example, consider +the following top level CMakeLists.txt: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.0) + project(First HOMEPAGE_URL "http://first.example.com") + project(Second HOMEPAGE_URL "http://second.example.com") + add_subdirectory(sub) + project(Third HOMEPAGE_URL "http://third.example.com") + +And ``sub/CMakeLists.txt`` with the following contents: + +.. code-block:: cmake + + project(SubProj HOMEPAGE_URL "http://subproj.example.com") + message("CMAKE_PROJECT_HOMEPAGE_URL = ${CMAKE_PROJECT_HOMEPAGE_URL}") + +The most recently seen :command:`project` command from the top level +CMakeLists.txt would be ``project(Second ...)``, so this will print:: + + CMAKE_PROJECT_HOMEPAGE_URL = http://second.example.com + +To obtain the homepage URL from the most recent call to :command:`project` in +the current directory scope or above, see the :variable:`PROJECT_HOMEPAGE_URL` +variable. diff --git a/Help/variable/CMAKE_PROJECT_INCLUDE.rst b/Help/variable/CMAKE_PROJECT_INCLUDE.rst new file mode 100644 index 000000000..965c94ee7 --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_INCLUDE.rst @@ -0,0 +1,9 @@ +CMAKE_PROJECT_INCLUDE +--------------------- + +A CMake language file or module to be included as the last step of all +:command:`project` command calls. This is intended for injecting custom code +into project builds without modifying their source. + +See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE` and +:variable:`CMAKE_PROJECT_INCLUDE_BEFORE` variables. diff --git a/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst b/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst new file mode 100644 index 000000000..70b15e662 --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst @@ -0,0 +1,9 @@ +CMAKE_PROJECT_INCLUDE_BEFORE +---------------------------- + +A CMake language file or module to be included as the first step of all +:command:`project` command calls. This is intended for injecting custom code +into project builds without modifying their source. + +See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE` and +:variable:`CMAKE_PROJECT_INCLUDE` variables. diff --git a/Help/variable/CMAKE_PROJECT_NAME.rst b/Help/variable/CMAKE_PROJECT_NAME.rst index 431e9f302..94b8dbab8 100644 --- a/Help/variable/CMAKE_PROJECT_NAME.rst +++ b/Help/variable/CMAKE_PROJECT_NAME.rst @@ -1,7 +1,35 @@ CMAKE_PROJECT_NAME ------------------ -The name of the current project. +The name of the top level project. -This specifies name of the current project from the closest inherited -:command:`project` command. +This variable holds the name of the project as specified in the top +level CMakeLists.txt file by a :command:`project` command. In the event that +the top level CMakeLists.txt contains multiple :command:`project` calls, +the most recently called one from that top level CMakeLists.txt will determine +the name that ``CMAKE_PROJECT_NAME`` contains. For example, consider +the following top level CMakeLists.txt: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.0) + project(First) + project(Second) + add_subdirectory(sub) + project(Third) + +And ``sub/CMakeLists.txt`` with the following contents: + +.. code-block:: cmake + + project(SubProj) + message("CMAKE_PROJECT_NAME = ${CMAKE_PROJECT_NAME}") + +The most recently seen :command:`project` command from the top level +CMakeLists.txt would be ``project(Second)``, so this will print:: + + CMAKE_PROJECT_NAME = Second + +To obtain the name from the most recent call to :command:`project` in +the current directory scope or above, see the :variable:`PROJECT_NAME` +variable. diff --git a/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst index ba9df5a34..3485c38e4 100644 --- a/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst +++ b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst @@ -1,6 +1,10 @@ CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE ------------------------------------ -A CMake language file or module to be included by the :command:`project` -command. This is is intended for injecting custom code into project -builds without modifying their source. +A CMake language file or module to be included as the last step of any +:command:`project` command calls that specify ``<PROJECT-NAME>`` as the project +name. This is intended for injecting custom code into project builds without +modifying their source. + +See also the :variable:`CMAKE_PROJECT_INCLUDE` and +:variable:`CMAKE_PROJECT_INCLUDE_BEFORE` variables. diff --git a/Help/variable/CMAKE_PROJECT_VERSION.rst b/Help/variable/CMAKE_PROJECT_VERSION.rst new file mode 100644 index 000000000..4f8f55605 --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_VERSION.rst @@ -0,0 +1,35 @@ +CMAKE_PROJECT_VERSION +--------------------- + +The version of the top level project. + +This variable holds the version of the project as specified in the top +level CMakeLists.txt file by a :command:`project` command. In the event that +the top level CMakeLists.txt contains multiple :command:`project` calls, +the most recently called one from that top level CMakeLists.txt will determine +the value that ``CMAKE_PROJECT_VERSION`` contains. For example, consider +the following top level CMakeLists.txt: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.0) + project(First VERSION 1.2.3) + project(Second VERSION 3.4.5) + add_subdirectory(sub) + project(Third VERSION 6.7.8) + +And ``sub/CMakeLists.txt`` with the following contents: + +.. code-block:: cmake + + project(SubProj VERSION 1) + message("CMAKE_PROJECT_VERSION = ${CMAKE_PROJECT_VERSION}") + +The most recently seen :command:`project` command from the top level +CMakeLists.txt would be ``project(Second ...)``, so this will print:: + + CMAKE_PROJECT_VERSION = 3.4.5 + +To obtain the version from the most recent call to :command:`project` in +the current directory scope or above, see the :variable:`PROJECT_VERSION` +variable. diff --git a/Help/variable/CMAKE_PROJECT_VERSION_MAJOR.rst b/Help/variable/CMAKE_PROJECT_VERSION_MAJOR.rst new file mode 100644 index 000000000..f1001acaf --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_VERSION_MAJOR.rst @@ -0,0 +1,9 @@ +CMAKE_PROJECT_VERSION_MAJOR +--------------------------- + +The major version of the top level project. + +This variable holds the major version of the project as specified in the top +level CMakeLists.txt file by a :command:`project` command. Please see +:variable:`CMAKE_PROJECT_VERSION` documentation for the behavior when +multiple :command:`project` commands are used in the sources. diff --git a/Help/variable/CMAKE_PROJECT_VERSION_MINOR.rst b/Help/variable/CMAKE_PROJECT_VERSION_MINOR.rst new file mode 100644 index 000000000..13202be98 --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_VERSION_MINOR.rst @@ -0,0 +1,9 @@ +CMAKE_PROJECT_VERSION_MINOR +--------------------------- + +The minor version of the top level project. + +This variable holds the minor version of the project as specified in the top +level CMakeLists.txt file by a :command:`project` command. Please see +:variable:`CMAKE_PROJECT_VERSION` documentation for the behavior when +multiple :command:`project` commands are used in the sources. diff --git a/Help/variable/CMAKE_PROJECT_VERSION_PATCH.rst b/Help/variable/CMAKE_PROJECT_VERSION_PATCH.rst new file mode 100644 index 000000000..b8570d9fe --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_VERSION_PATCH.rst @@ -0,0 +1,9 @@ +CMAKE_PROJECT_VERSION_PATCH +--------------------------- + +The patch version of the top level project. + +This variable holds the patch version of the project as specified in the top +level CMakeLists.txt file by a :command:`project` command. Please see +:variable:`CMAKE_PROJECT_VERSION` documentation for the behavior when +multiple :command:`project` commands are used in the sources. diff --git a/Help/variable/CMAKE_PROJECT_VERSION_TWEAK.rst b/Help/variable/CMAKE_PROJECT_VERSION_TWEAK.rst new file mode 100644 index 000000000..e1ad4be33 --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_VERSION_TWEAK.rst @@ -0,0 +1,9 @@ +CMAKE_PROJECT_VERSION_TWEAK +--------------------------- + +The tweak version of the top level project. + +This variable holds the tweak version of the project as specified in the top +level CMakeLists.txt file by a :command:`project` command. Please see +:variable:`CMAKE_PROJECT_VERSION` documentation for the behavior when +multiple :command:`project` commands are used in the sources. diff --git a/Help/variable/CMAKE_RULE_MESSAGES.rst b/Help/variable/CMAKE_RULE_MESSAGES.rst new file mode 100644 index 000000000..7460a81ee --- /dev/null +++ b/Help/variable/CMAKE_RULE_MESSAGES.rst @@ -0,0 +1,8 @@ +CMAKE_RULE_MESSAGES +------------------- + +Specify whether to report a message for each make rule. + +If set in the cache it is used to initialize the value of the :prop_gbl:`RULE_MESSAGES` property. +Users may disable the option in their local build tree to disable granular messages +and report only as each target completes in Makefile builds. diff --git a/Help/variable/CMAKE_SKIP_INSTALL_RULES.rst b/Help/variable/CMAKE_SKIP_INSTALL_RULES.rst index 44966f32f..b77bb686a 100644 --- a/Help/variable/CMAKE_SKIP_INSTALL_RULES.rst +++ b/Help/variable/CMAKE_SKIP_INSTALL_RULES.rst @@ -3,6 +3,6 @@ CMAKE_SKIP_INSTALL_RULES Whether to disable generation of installation rules. -If ``TRUE``, cmake will neither generate installaton rules nor +If ``TRUE``, CMake will neither generate installation rules nor will it generate ``cmake_install.cmake`` files. This variable is ``FALSE`` by default. diff --git a/Help/variable/CMAKE_SOURCE_DIR.rst b/Help/variable/CMAKE_SOURCE_DIR.rst index 416fbe1a8..d1f179838 100644 --- a/Help/variable/CMAKE_SOURCE_DIR.rst +++ b/Help/variable/CMAKE_SOURCE_DIR.rst @@ -7,7 +7,7 @@ This is the full path to the top level of the current CMake source tree. For an in-source build, this would be the same as :variable:`CMAKE_BINARY_DIR`. -When run in -P script mode, CMake sets the variables +When run in ``-P`` script mode, CMake sets the variables :variable:`CMAKE_BINARY_DIR`, :variable:`CMAKE_SOURCE_DIR`, :variable:`CMAKE_CURRENT_BINARY_DIR` and :variable:`CMAKE_CURRENT_SOURCE_DIR` to the current working directory. diff --git a/Help/variable/CMAKE_STAGING_PREFIX.rst b/Help/variable/CMAKE_STAGING_PREFIX.rst index 1310e9471..bdb97faef 100644 --- a/Help/variable/CMAKE_STAGING_PREFIX.rst +++ b/Help/variable/CMAKE_STAGING_PREFIX.rst @@ -5,10 +5,10 @@ This variable may be set to a path to install to when cross-compiling. This can be useful if the path in :variable:`CMAKE_SYSROOT` is read-only, or otherwise should remain pristine. -The ``CMAKE_STAGING_PREFIX`` location is also used as a search prefix by the -``find_*`` commands. This can be controlled by setting the +The :variable:`CMAKE_STAGING_PREFIX` location is also used as a search prefix +by the ``find_*`` commands. This can be controlled by setting the :variable:`CMAKE_FIND_NO_INSTALL_PREFIX` variable. -If any RPATH/RUNPATH entries passed to the linker contain the -``CMAKE_STAGING_PREFIX``, the matching path fragments are replaced with the -:variable:`CMAKE_INSTALL_PREFIX`. +If any ``RPATH``/``RUNPATH`` entries passed to the linker contain the +:variable:`CMAKE_STAGING_PREFIX`, the matching path fragments are replaced +with the :variable:`CMAKE_INSTALL_PREFIX`. diff --git a/Help/variable/CMAKE_STATIC_LINKER_FLAGS.rst b/Help/variable/CMAKE_STATIC_LINKER_FLAGS.rst index 9c38673aa..1a810ce14 100644 --- a/Help/variable/CMAKE_STATIC_LINKER_FLAGS.rst +++ b/Help/variable/CMAKE_STATIC_LINKER_FLAGS.rst @@ -1,6 +1,12 @@ CMAKE_STATIC_LINKER_FLAGS ------------------------- -Linker flags to be used to create static libraries. +Flags to be used to create static libraries. These flags will be passed +to the archiver when creating a static library. -These flags will be used by the linker when creating a static library. +See also :variable:`CMAKE_STATIC_LINKER_FLAGS_<CONFIG>`. + +.. note:: + Static libraries do not actually link. They are essentially archives + of object files. The use of the name "linker" in the name of this + variable is kept for compatibility. diff --git a/Help/variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG.rst b/Help/variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG.rst index b9f8003c7..e561dc645 100644 --- a/Help/variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG.rst +++ b/Help/variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG.rst @@ -1,7 +1,13 @@ CMAKE_STATIC_LINKER_FLAGS_<CONFIG> ---------------------------------- -Flags to be used when linking a static library. +Flags to be used to create static libraries. These flags will be passed +to the archiver when creating a static library in the ``<CONFIG>`` +configuration. -Same as ``CMAKE_C_FLAGS_*`` but used by the linker when creating static -libraries. +See also :variable:`CMAKE_STATIC_LINKER_FLAGS`. + +.. note:: + Static libraries do not actually link. They are essentially archives + of object files. The use of the name "linker" in the name of this + variable is kept for compatibility. diff --git a/Help/variable/CMAKE_SUPPRESS_REGENERATION.rst b/Help/variable/CMAKE_SUPPRESS_REGENERATION.rst new file mode 100644 index 000000000..96184dd5e --- /dev/null +++ b/Help/variable/CMAKE_SUPPRESS_REGENERATION.rst @@ -0,0 +1,11 @@ +CMAKE_SUPPRESS_REGENERATION +--------------------------- + +If ``CMAKE_SUPPRESS_REGENERATION`` is ``OFF``, which is default, then CMake +adds a special target on which all other targets depend that checks the build +system and optionally re-runs CMake to regenerate the build system when +the target specification source changes. + +If this variable evaluates to ``ON`` at the end of the top-level +``CMakeLists.txt`` file, CMake will not add the regeneration target to the +build system or perform any build system checks. diff --git a/Help/variable/CMAKE_SYSROOT.rst b/Help/variable/CMAKE_SYSROOT.rst index 64f81bbc2..35b944fa4 100644 --- a/Help/variable/CMAKE_SYSROOT.rst +++ b/Help/variable/CMAKE_SYSROOT.rst @@ -4,8 +4,8 @@ CMAKE_SYSROOT Path to pass to the compiler in the ``--sysroot`` flag. The ``CMAKE_SYSROOT`` content is passed to the compiler in the ``--sysroot`` -flag, if supported. The path is also stripped from the RPATH/RUNPATH if -necessary on installation. The ``CMAKE_SYSROOT`` is also used to prefix +flag, if supported. The path is also stripped from the ``RPATH``/``RUNPATH`` +if necessary on installation. The ``CMAKE_SYSROOT`` is also used to prefix paths searched by the ``find_*`` commands. This variable may only be set in a toolchain file specified by diff --git a/Help/variable/CMAKE_SYSTEM_APPBUNDLE_PATH.rst b/Help/variable/CMAKE_SYSTEM_APPBUNDLE_PATH.rst index 3c6687c6e..666af4615 100644 --- a/Help/variable/CMAKE_SYSTEM_APPBUNDLE_PATH.rst +++ b/Help/variable/CMAKE_SYSTEM_APPBUNDLE_PATH.rst @@ -1,7 +1,7 @@ CMAKE_SYSTEM_APPBUNDLE_PATH --------------------------- -Search path for OS X application bundles used by the :command:`find_program`, +Search path for macOS application bundles used by the :command:`find_program`, and :command:`find_package` commands. By default it contains the standard directories for the current system. It is *not* intended to be modified by the project, use :variable:`CMAKE_APPBUNDLE_PATH` for this. diff --git a/Help/variable/CMAKE_SYSTEM_FRAMEWORK_PATH.rst b/Help/variable/CMAKE_SYSTEM_FRAMEWORK_PATH.rst index 1e8b0d947..14ba18eff 100644 --- a/Help/variable/CMAKE_SYSTEM_FRAMEWORK_PATH.rst +++ b/Help/variable/CMAKE_SYSTEM_FRAMEWORK_PATH.rst @@ -1,7 +1,7 @@ CMAKE_SYSTEM_FRAMEWORK_PATH --------------------------- -Search path for OS X frameworks used by the :command:`find_library`, +Search path for macOS frameworks used by the :command:`find_library`, :command:`find_package`, :command:`find_path`, and :command:`find_file` commands. By default it contains the standard directories for the current system. It is *not* intended to be modified by the project, diff --git a/Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst b/Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst index 4ad7e33ce..6afbd337a 100644 --- a/Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst +++ b/Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst @@ -1,7 +1,7 @@ CMAKE_SYSTEM_IGNORE_PATH ------------------------ -:ref:`;-list <CMake Language Lists>` of directories to be *ignored* by +:ref:`Semicolon-separated list <CMake Language Lists>` of directories to be *ignored* by the :command:`find_program`, :command:`find_library`, :command:`find_file`, and :command:`find_path` commands. This is useful in cross-compiling environments where some system directories contain incompatible but diff --git a/Help/variable/CMAKE_SYSTEM_INCLUDE_PATH.rst b/Help/variable/CMAKE_SYSTEM_INCLUDE_PATH.rst index 2c14345c0..680404ef5 100644 --- a/Help/variable/CMAKE_SYSTEM_INCLUDE_PATH.rst +++ b/Help/variable/CMAKE_SYSTEM_INCLUDE_PATH.rst @@ -1,7 +1,7 @@ CMAKE_SYSTEM_INCLUDE_PATH ------------------------- -:ref:`;-list <CMake Language Lists>` of directories specifying a search path +:ref:`Semicolon-separated list <CMake Language Lists>` of directories specifying a search path for the :command:`find_file` and :command:`find_path` commands. By default this contains the standard directories for the current system. It is *not* intended to be modified by the project; use :variable:`CMAKE_INCLUDE_PATH` for diff --git a/Help/variable/CMAKE_SYSTEM_LIBRARY_PATH.rst b/Help/variable/CMAKE_SYSTEM_LIBRARY_PATH.rst index 3969cb94c..116832bf9 100644 --- a/Help/variable/CMAKE_SYSTEM_LIBRARY_PATH.rst +++ b/Help/variable/CMAKE_SYSTEM_LIBRARY_PATH.rst @@ -1,7 +1,7 @@ CMAKE_SYSTEM_LIBRARY_PATH ------------------------- -:ref:`;-list <CMake Language Lists>` of directories specifying a search path +:ref:`Semicolon-separated list <CMake Language Lists>` of directories specifying a search path for the :command:`find_library` command. By default this contains the standard directories for the current system. It is *not* intended to be modified by the project; use :variable:`CMAKE_LIBRARY_PATH` for this. diff --git a/Help/variable/CMAKE_SYSTEM_NAME.rst b/Help/variable/CMAKE_SYSTEM_NAME.rst index c3a42e5b4..fef53eecb 100644 --- a/Help/variable/CMAKE_SYSTEM_NAME.rst +++ b/Help/variable/CMAKE_SYSTEM_NAME.rst @@ -4,6 +4,9 @@ CMAKE_SYSTEM_NAME The name of the operating system for which CMake is to build. See the :variable:`CMAKE_SYSTEM_VERSION` variable for the OS version. +Note that ``CMAKE_SYSTEM_NAME`` is not set to anything by default when running +in script mode, since it's not building anything. + System Name for Host Builds ^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst b/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst index e74dfad18..87a9d06a8 100644 --- a/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst +++ b/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst @@ -1,7 +1,7 @@ CMAKE_SYSTEM_PREFIX_PATH ------------------------ -:ref:`;-list <CMake Language Lists>` of directories specifying installation +:ref:`Semicolon-separated list <CMake Language Lists>` of directories specifying installation *prefixes* to be searched by the :command:`find_package`, :command:`find_program`, :command:`find_library`, :command:`find_file`, and :command:`find_path` commands. Each command will add appropriate @@ -10,8 +10,11 @@ documentation. By default this contains the standard directories for the current system, the :variable:`CMAKE_INSTALL_PREFIX`, and the :variable:`CMAKE_STAGING_PREFIX`. -It is *not* intended to be modified by the project; use -:variable:`CMAKE_PREFIX_PATH` for this. +The installation and staging prefixes may be excluded by setting +the :variable:`CMAKE_FIND_NO_INSTALL_PREFIX` variable. + +``CMAKE_SYSTEM_PREFIX_PATH`` is *not* intended to be modified by the project; +use :variable:`CMAKE_PREFIX_PATH` for this. See also :variable:`CMAKE_SYSTEM_INCLUDE_PATH`, :variable:`CMAKE_SYSTEM_LIBRARY_PATH`, :variable:`CMAKE_SYSTEM_PROGRAM_PATH`, diff --git a/Help/variable/CMAKE_SYSTEM_PROCESSOR.rst b/Help/variable/CMAKE_SYSTEM_PROCESSOR.rst index 09280dee6..8ad89f128 100644 --- a/Help/variable/CMAKE_SYSTEM_PROCESSOR.rst +++ b/Help/variable/CMAKE_SYSTEM_PROCESSOR.rst @@ -6,5 +6,3 @@ The name of the CPU CMake is building for. This variable is the same as :variable:`CMAKE_HOST_SYSTEM_PROCESSOR` if you build for the host system instead of the target system when cross compiling. - -* The :generator:`Green Hills MULTI` generator sets this to ``ARM`` by default. diff --git a/Help/variable/CMAKE_SYSTEM_PROGRAM_PATH.rst b/Help/variable/CMAKE_SYSTEM_PROGRAM_PATH.rst index cf1b83e80..9b7036182 100644 --- a/Help/variable/CMAKE_SYSTEM_PROGRAM_PATH.rst +++ b/Help/variable/CMAKE_SYSTEM_PROGRAM_PATH.rst @@ -1,7 +1,7 @@ CMAKE_SYSTEM_PROGRAM_PATH ------------------------- -:ref:`;-list <CMake Language Lists>` of directories specifying a search path +:ref:`Semicolon-separated list <CMake Language Lists>` of directories specifying a search path for the :command:`find_program` command. By default this contains the standard directories for the current system. It is *not* intended to be modified by the project; use :variable:`CMAKE_PROGRAM_PATH` for this. diff --git a/Help/variable/CMAKE_Swift_LANGUAGE_VERSION.rst b/Help/variable/CMAKE_Swift_LANGUAGE_VERSION.rst index 50121e286..b4a74eb03 100644 --- a/Help/variable/CMAKE_Swift_LANGUAGE_VERSION.rst +++ b/Help/variable/CMAKE_Swift_LANGUAGE_VERSION.rst @@ -1,5 +1,9 @@ CMAKE_Swift_LANGUAGE_VERSION ---------------------------- -Set to the Swift language version number. If not set, the legacy "2.3" -version is assumed. +Set to the Swift language version number. If not set, the oldest legacy +version known to be available in the host Xcode version is assumed: + +* Swift ``4.0`` for Xcode 10.2 and above. +* Swift ``3.0`` for Xcode 8.3 and above. +* Swift ``2.3`` for Xcode 8.2 and below. diff --git a/Help/variable/CMAKE_Swift_MODULE_DIRECTORY.rst b/Help/variable/CMAKE_Swift_MODULE_DIRECTORY.rst new file mode 100644 index 000000000..b11253bc1 --- /dev/null +++ b/Help/variable/CMAKE_Swift_MODULE_DIRECTORY.rst @@ -0,0 +1,8 @@ +CMAKE_Swift_MODULE_DIRECTORY +---------------------------- + +Swift module output directory. + +This variable is used to initialise the :prop_tgt:`Swift_MODULE_DIRECTORY` +property on all the targets. See the target property for additional +information. diff --git a/Help/variable/CMAKE_Swift_NUM_THREADS.rst b/Help/variable/CMAKE_Swift_NUM_THREADS.rst new file mode 100644 index 000000000..cb3367855 --- /dev/null +++ b/Help/variable/CMAKE_Swift_NUM_THREADS.rst @@ -0,0 +1,8 @@ +CMAKE_Swift_NUM_THREADS +----------------------- + +Number of threads for parallel compilation for Swift targets. + +This variable controls the number of parallel jobs that the swift driver creates +for building targets. If not specified, it will default to the number of +logical CPUs on the host. diff --git a/Help/variable/CMAKE_UNITY_BUILD.rst b/Help/variable/CMAKE_UNITY_BUILD.rst new file mode 100644 index 000000000..a86cd67ff --- /dev/null +++ b/Help/variable/CMAKE_UNITY_BUILD.rst @@ -0,0 +1,20 @@ +CMAKE_UNITY_BUILD +----------------- + +This variable is used to initialize the :prop_tgt:`UNITY_BUILD` +property of targets when they are created. Setting it to true +enables batch compilation of multiple sources within each target. +This feature is known as a *Unity* or *Jumbo* build. + +Projects should not set this variable, it is intended as a developer +control to be set on the :manual:`cmake(1)` command line or other +equivalent methods. The developer must have the ability to enable or +disable unity builds according to the capabilities of their own machine +and compiler. + +By default, this variable is not set, which will result in unity builds +being disabled. + +.. note:: + This option currently does not work well in combination with + the :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` variable. diff --git a/Help/variable/CMAKE_UNITY_BUILD_BATCH_SIZE.rst b/Help/variable/CMAKE_UNITY_BUILD_BATCH_SIZE.rst new file mode 100644 index 000000000..7988d4b28 --- /dev/null +++ b/Help/variable/CMAKE_UNITY_BUILD_BATCH_SIZE.rst @@ -0,0 +1,7 @@ +CMAKE_UNITY_BUILD_BATCH_SIZE +---------------------------- + +This variable is used to initialize the :prop_tgt:`UNITY_BUILD_BATCH_SIZE` +property of targets when they are created. It specifies the default upper +limit on the number of source files that may be combined in any one unity +source file when unity builds are enabled for a target. diff --git a/Help/variable/CMAKE_VS_DEVENV_COMMAND.rst b/Help/variable/CMAKE_VS_DEVENV_COMMAND.rst index 51b42dd4b..f109a9eda 100644 --- a/Help/variable/CMAKE_VS_DEVENV_COMMAND.rst +++ b/Help/variable/CMAKE_VS_DEVENV_COMMAND.rst @@ -1,7 +1,7 @@ CMAKE_VS_DEVENV_COMMAND ----------------------- -The generators for :generator:`Visual Studio 8 2005` and above set this +The generators for :generator:`Visual Studio 9 2008` and above set this variable to the ``devenv.com`` command installed with the corresponding Visual Studio version. Note that this variable may be empty on Visual Studio Express editions because they do not provide this tool. diff --git a/Help/variable/CMAKE_VS_GLOBALS.rst b/Help/variable/CMAKE_VS_GLOBALS.rst new file mode 100644 index 000000000..83777b619 --- /dev/null +++ b/Help/variable/CMAKE_VS_GLOBALS.rst @@ -0,0 +1,21 @@ +CMAKE_VS_GLOBALS +---------------- + +List of ``Key=Value`` records to be set per target as target properties +:prop_tgt:`VS_GLOBAL_<variable>` with ``variable=Key`` and value ``Value``. + +For example: + +.. code-block:: cmake + + set(CMAKE_VS_GLOBALS + "DefaultLanguage=en-US" + "MinimumVisualStudioVersion=14.0" + ) + +will set properties ``VS_GLOBAL_DefaultLanguage`` to ``en-US`` and +``VS_GLOBAL_MinimumVisualStudioVersion`` to ``14.0`` for all targets +(except for ``INTERFACE`` libraries). + +This variable is meant to be set by a +:variable:`toolchain file <CMAKE_TOOLCHAIN_FILE>`. diff --git a/Help/variable/CMAKE_VS_INTEL_Fortran_PROJECT_VERSION.rst b/Help/variable/CMAKE_VS_INTEL_Fortran_PROJECT_VERSION.rst index 6d196f917..ceedf2861 100644 --- a/Help/variable/CMAKE_VS_INTEL_Fortran_PROJECT_VERSION.rst +++ b/Help/variable/CMAKE_VS_INTEL_Fortran_PROJECT_VERSION.rst @@ -1,7 +1,7 @@ CMAKE_VS_INTEL_Fortran_PROJECT_VERSION -------------------------------------- -When generating for :generator:`Visual Studio 8 2005` or greater with the Intel +When generating for :generator:`Visual Studio 9 2008` or greater with the Intel Fortran plugin installed, this specifies the ``.vfproj`` project file format version. This is intended for internal use by CMake and should not be used by project code. diff --git a/Help/variable/CMAKE_VS_JUST_MY_CODE_DEBUGGING.rst b/Help/variable/CMAKE_VS_JUST_MY_CODE_DEBUGGING.rst new file mode 100644 index 000000000..546cdf492 --- /dev/null +++ b/Help/variable/CMAKE_VS_JUST_MY_CODE_DEBUGGING.rst @@ -0,0 +1,8 @@ +CMAKE_VS_JUST_MY_CODE_DEBUGGING +------------------------------- + +Enable Just My Code with Visual Studio debugger. + +This variable is used to initialize the :prop_tgt:`VS_JUST_MY_CODE_DEBUGGING` +property on all targets when they are created. See that target property for +additional information. diff --git a/Help/variable/CMAKE_VS_PLATFORM_NAME.rst b/Help/variable/CMAKE_VS_PLATFORM_NAME.rst index a532743fb..7a4642a31 100644 --- a/Help/variable/CMAKE_VS_PLATFORM_NAME.rst +++ b/Help/variable/CMAKE_VS_PLATFORM_NAME.rst @@ -1,8 +1,10 @@ CMAKE_VS_PLATFORM_NAME ---------------------- -Visual Studio target platform name. +Visual Studio target platform name used by the current generator. VS 8 and above allow project files to specify a target platform. CMake provides the name of the chosen platform in this variable. See the :variable:`CMAKE_GENERATOR_PLATFORM` variable for details. + +See also the :variable:`CMAKE_VS_PLATFORM_NAME_DEFAULT` variable. diff --git a/Help/variable/CMAKE_VS_PLATFORM_NAME_DEFAULT.rst b/Help/variable/CMAKE_VS_PLATFORM_NAME_DEFAULT.rst new file mode 100644 index 000000000..c18e6fd37 --- /dev/null +++ b/Help/variable/CMAKE_VS_PLATFORM_NAME_DEFAULT.rst @@ -0,0 +1,9 @@ +CMAKE_VS_PLATFORM_NAME_DEFAULT +------------------------------ + +Default for the Visual Studio target platform name for the current generator +without considering the value of the :variable:`CMAKE_GENERATOR_PLATFORM` +variable. For :ref:`Visual Studio Generators` for VS 2017 and below this is +always ``Win32``. For VS 2019 and above this is based on the host platform. + +See also the :variable:`CMAKE_VS_PLATFORM_NAME` variable. diff --git a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA.rst b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA.rst index 1604a7667..67b7f7401 100644 --- a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA.rst +++ b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA.rst @@ -6,7 +6,9 @@ NVIDIA CUDA Toolkit version whose Visual Studio toolset to use. The :ref:`Visual Studio Generators` for VS 2010 and above support using a CUDA toolset provided by a CUDA Toolkit. The toolset version number may be specified by a field in :variable:`CMAKE_GENERATOR_TOOLSET` of -the form ``cuda=8.0``. If none is specified CMake will choose a default -version. CMake provides the selected CUDA toolset version in this variable. +the form ``cuda=8.0``. Or it is automatically detected if a path to +a standalone CUDA directory is specified in the form ``cuda=C:\path\to\cuda``. +If none is specified CMake will choose a default version. +CMake provides the selected CUDA toolset version in this variable. The value may be empty if no CUDA Toolkit with Visual Studio integration is installed. diff --git a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR.rst b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR.rst new file mode 100644 index 000000000..060648afc --- /dev/null +++ b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR.rst @@ -0,0 +1,16 @@ +CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR +----------------------------------------- + +Path to standalone NVIDIA CUDA Toolkit (eg. extracted from installer). + +The :ref:`Visual Studio Generators` for VS 2010 and above support using +a standalone (non-installed) NVIDIA CUDA toolkit. The path +may be specified by a field in :variable:`CMAKE_GENERATOR_TOOLSET` of +the form ``cuda=C:\path\to\cuda``. The given directory must at least +contain a folder ``.\nvcc`` and must provide Visual Studio integration +files in path ``.\CUDAVisualStudioIntegration\extras\ +visual_studio_integration\MSBuildExtensions\``. One can create a standalone +CUDA toolkit directory by either opening a installer with 7zip or +copying the files that are extracted by the running installer. +The value may be empty if no path to a standalone CUDA Toolkit was +specified. diff --git a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE.rst b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE.rst index 9b59c52a6..99ac90ddc 100644 --- a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE.rst +++ b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE.rst @@ -3,8 +3,8 @@ CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE Visual Studio preferred tool architecture. -The :ref:`Visual Studio Generators` for VS 2013 and above support optional -selection of a 64-bit toolchain on 64-bit hosts by specifying a ``host=x64`` -value in the :variable:`CMAKE_GENERATOR_TOOLSET` option. CMake provides -the selected toolchain architecture preference in this variable (either -``x64`` or empty). +The :ref:`Visual Studio Generators` for VS 2013 and above support using +either the 32-bit or 64-bit host toolchains by specifying a ``host=x86`` +or ``host=x64`` value in the :variable:`CMAKE_GENERATOR_TOOLSET` option. +CMake provides the selected toolchain architecture preference in this +variable (``x86``, ``x64``, or empty). diff --git a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_VERSION.rst b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_VERSION.rst new file mode 100644 index 000000000..4d9b978f4 --- /dev/null +++ b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_VERSION.rst @@ -0,0 +1,11 @@ +CMAKE_VS_PLATFORM_TOOLSET_VERSION +--------------------------------- + +Visual Studio Platform Toolset version. + +The :ref:`Visual Studio Generators` for VS 2017 and above allow to +select minor versions of the same toolset. The toolset version number +may be specified by a field in :variable:`CMAKE_GENERATOR_TOOLSET` of +the form ``version=14.11``. If none is specified CMake will choose a default +toolset. The value may be empty if no minor version was selected and the +default is used. diff --git a/Help/variable/CMAKE_VS_SDK_EXCLUDE_DIRECTORIES.rst b/Help/variable/CMAKE_VS_SDK_EXCLUDE_DIRECTORIES.rst new file mode 100644 index 000000000..36c4dccca --- /dev/null +++ b/Help/variable/CMAKE_VS_SDK_EXCLUDE_DIRECTORIES.rst @@ -0,0 +1,4 @@ +CMAKE_VS_SDK_EXCLUDE_DIRECTORIES +-------------------------------- + +This variable allows to override Visual Studio default Exclude Directories. diff --git a/Help/variable/CMAKE_VS_SDK_EXECUTABLE_DIRECTORIES.rst b/Help/variable/CMAKE_VS_SDK_EXECUTABLE_DIRECTORIES.rst new file mode 100644 index 000000000..3ec755ba9 --- /dev/null +++ b/Help/variable/CMAKE_VS_SDK_EXECUTABLE_DIRECTORIES.rst @@ -0,0 +1,4 @@ +CMAKE_VS_SDK_EXECUTABLE_DIRECTORIES +----------------------------------- + +This variable allows to override Visual Studio default Executable Directories. diff --git a/Help/variable/CMAKE_VS_SDK_INCLUDE_DIRECTORIES.rst b/Help/variable/CMAKE_VS_SDK_INCLUDE_DIRECTORIES.rst new file mode 100644 index 000000000..da10bdea9 --- /dev/null +++ b/Help/variable/CMAKE_VS_SDK_INCLUDE_DIRECTORIES.rst @@ -0,0 +1,4 @@ +CMAKE_VS_SDK_INCLUDE_DIRECTORIES +-------------------------------- + +This variable allows to override Visual Studio default Include Directories. diff --git a/Help/variable/CMAKE_VS_SDK_LIBRARY_DIRECTORIES.rst b/Help/variable/CMAKE_VS_SDK_LIBRARY_DIRECTORIES.rst new file mode 100644 index 000000000..b33754a47 --- /dev/null +++ b/Help/variable/CMAKE_VS_SDK_LIBRARY_DIRECTORIES.rst @@ -0,0 +1,4 @@ +CMAKE_VS_SDK_LIBRARY_DIRECTORIES +-------------------------------- + +This variable allows to override Visual Studio default Library Directories. diff --git a/Help/variable/CMAKE_VS_SDK_LIBRARY_WINRT_DIRECTORIES.rst b/Help/variable/CMAKE_VS_SDK_LIBRARY_WINRT_DIRECTORIES.rst new file mode 100644 index 000000000..b0222157b --- /dev/null +++ b/Help/variable/CMAKE_VS_SDK_LIBRARY_WINRT_DIRECTORIES.rst @@ -0,0 +1,5 @@ +CMAKE_VS_SDK_LIBRARY_WINRT_DIRECTORIES +-------------------------------------- + +This variable allows to override Visual Studio default Library WinRT +Directories. diff --git a/Help/variable/CMAKE_VS_SDK_REFERENCE_DIRECTORIES.rst b/Help/variable/CMAKE_VS_SDK_REFERENCE_DIRECTORIES.rst new file mode 100644 index 000000000..c03f0aed2 --- /dev/null +++ b/Help/variable/CMAKE_VS_SDK_REFERENCE_DIRECTORIES.rst @@ -0,0 +1,4 @@ +CMAKE_VS_SDK_REFERENCE_DIRECTORIES +---------------------------------- + +This variable allows to override Visual Studio default Reference Directories. diff --git a/Help/variable/CMAKE_VS_SDK_SOURCE_DIRECTORIES.rst b/Help/variable/CMAKE_VS_SDK_SOURCE_DIRECTORIES.rst new file mode 100644 index 000000000..0c73f064a --- /dev/null +++ b/Help/variable/CMAKE_VS_SDK_SOURCE_DIRECTORIES.rst @@ -0,0 +1,4 @@ +CMAKE_VS_SDK_SOURCE_DIRECTORIES +------------------------------- + +This variable allows to override Visual Studio default Source Directories. diff --git a/Help/variable/CMAKE_VS_WINRT_BY_DEFAULT.rst b/Help/variable/CMAKE_VS_WINRT_BY_DEFAULT.rst new file mode 100644 index 000000000..2ba8fe27e --- /dev/null +++ b/Help/variable/CMAKE_VS_WINRT_BY_DEFAULT.rst @@ -0,0 +1,8 @@ +CMAKE_VS_WINRT_BY_DEFAULT +------------------------- + +Tell :ref:`Visual Studio Generators` for VS 2010 and above that the +target platform compiles as WinRT by default (compiles with ``/ZW``). + +This variable is meant to be set by a +:variable:`toolchain file <CMAKE_TOOLCHAIN_FILE>` for such platforms. diff --git a/Help/variable/CMAKE_XCODE_GENERATE_SCHEME.rst b/Help/variable/CMAKE_XCODE_GENERATE_SCHEME.rst index c9fcc92e0..5b1a003f0 100644 --- a/Help/variable/CMAKE_XCODE_GENERATE_SCHEME.rst +++ b/Help/variable/CMAKE_XCODE_GENERATE_SCHEME.rst @@ -1,11 +1,10 @@ CMAKE_XCODE_GENERATE_SCHEME --------------------------- -If enabled, the Xcode generator will generate schema files. Those are +If enabled, the :generator:`Xcode` generator will generate schema files. These are useful to invoke analyze, archive, build-for-testing and test actions from the command line. -.. note:: - - The Xcode Schema Generator is still experimental and subject to - change. +This variable initializes the +:prop_tgt:`XCODE_GENERATE_SCHEME` +target property on all targets. diff --git a/Help/variable/CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY.rst b/Help/variable/CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY.rst new file mode 100644 index 000000000..ea3e240b1 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY.rst @@ -0,0 +1,9 @@ +CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY +------------------------------------------- + +If enabled, the :generator:`Xcode` generator will generate only a +single Xcode project file for the topmost :command:`project()` command +instead of generating one for every ``project()`` command. + +This could be useful to speed up the CMake generation step for +large projects and to work-around a bug in the ``ZERO_CHECK`` logic. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER.rst b/Help/variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER.rst new file mode 100644 index 000000000..b972ba573 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER +------------------------------------ + +Whether to enable ``Address Sanitizer`` in the Diagnostics +section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_ADDRESS_SANITIZER` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN.rst b/Help/variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN.rst new file mode 100644 index 000000000..59eb32df3 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN +----------------------------------------------------- + +Whether to enable ``Detect use of stack after return`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING.rst b/Help/variable/CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING.rst new file mode 100644 index 000000000..a264d36c8 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING.rst @@ -0,0 +1,13 @@ +CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING +-------------------------------------------- + +Whether to enable +``Allow debugging when using document Versions Browser`` +in the Options section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER.rst b/Help/variable/CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER.rst new file mode 100644 index 000000000..71bcf4235 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER +---------------------------------------------- + +Whether to disable the ``Main Thread Checker`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS.rst b/Help/variable/CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS.rst new file mode 100644 index 000000000..53f55e604 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS +---------------------------------------- + +Whether to enable ``Dynamic Library Loads`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE.rst b/Help/variable/CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE.rst new file mode 100644 index 000000000..784ceb6b7 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE +------------------------------------------- + +Whether to enable ``Dynamic Linker API usage`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_GUARD_MALLOC.rst b/Help/variable/CMAKE_XCODE_SCHEME_GUARD_MALLOC.rst new file mode 100644 index 000000000..9350244b0 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_GUARD_MALLOC.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_GUARD_MALLOC +------------------------------- + +Whether to enable ``Guard Malloc`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_GUARD_MALLOC` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP.rst b/Help/variable/CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP.rst new file mode 100644 index 000000000..45a2dad69 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP.rst @@ -0,0 +1,13 @@ +CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP +------------------------------------------- + +Whether to enable the ``Main Thread Checker`` option +``Pause on issues`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES.rst b/Help/variable/CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES.rst new file mode 100644 index 000000000..94d1c61fb --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES +------------------------------------- + +Whether to enable ``Malloc Guard Edges`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_MALLOC_GUARD_EDGES` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE.rst b/Help/variable/CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE.rst new file mode 100644 index 000000000..9bf0eb419 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE +---------------------------------- + +Whether to enable ``Malloc Scribble`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_MALLOC_SCRIBBLE` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_MALLOC_STACK.rst b/Help/variable/CMAKE_XCODE_SCHEME_MALLOC_STACK.rst new file mode 100644 index 000000000..4cc21ee2b --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_MALLOC_STACK.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_MALLOC_STACK +------------------------------- + +Whether to enable ``Malloc Stack`` in the Diagnostics +section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_MALLOC_STACK` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER.rst b/Help/variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER.rst new file mode 100644 index 000000000..6d1b56eea --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_THREAD_SANITIZER +----------------------------------- + +Whether to enable ``Thread Sanitizer`` in the Diagnostics +section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_THREAD_SANITIZER` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP.rst b/Help/variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP.rst new file mode 100644 index 000000000..de40478ea --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP +---------------------------------------- + +Whether to enable ``Thread Sanitizer - Pause on issues`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_THREAD_SANITIZER_STOP` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER.rst b/Help/variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER.rst new file mode 100644 index 000000000..ec5df6613 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER +------------------------------------------------ + +Whether to enable ``Undefined Behavior Sanitizer`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP.rst b/Help/variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP.rst new file mode 100644 index 000000000..dcec9b0ea --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP.rst @@ -0,0 +1,13 @@ +CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP +----------------------------------------------------- + +Whether to enable ``Undefined Behavior Sanitizer`` option +``Pause on issues`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS.rst b/Help/variable/CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS.rst new file mode 100644 index 000000000..82e9d76cc --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS +--------------------------------- + +Whether to enable ``Zombie Objects`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_ZOMBIE_OBJECTS` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION.rst b/Help/variable/CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION.rst index 5dad6bd68..30ae23638 100644 --- a/Help/variable/CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION.rst +++ b/Help/variable/CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION.rst @@ -5,7 +5,7 @@ Ask CPack to error out as soon as a file with absolute ``INSTALL DESTINATION`` is encountered. The fatal error is emitted before the installation of the offending -file takes place. Some CPack generators, like NSIS, enforce this +file takes place. Some CPack generators, like ``NSIS``, enforce this internally. This variable triggers the definition of :variable:`CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION` when CPack runs. diff --git a/Help/variable/CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS.rst b/Help/variable/CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS.rst new file mode 100644 index 000000000..83d5ce7fc --- /dev/null +++ b/Help/variable/CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS.rst @@ -0,0 +1,11 @@ +CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS +------------------------------------------- + +Default permissions for implicitly created directories during packaging. + +This variable serves the same purpose during packaging as the +:variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` variable +serves during installation (e.g. ``make install``). + +If `include(CPack)` is used then by default this variable is set to the content +of :variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS`. diff --git a/Help/variable/CPACK_INSTALL_SCRIPT.rst b/Help/variable/CPACK_INSTALL_SCRIPT.rst deleted file mode 100644 index 12a48a40d..000000000 --- a/Help/variable/CPACK_INSTALL_SCRIPT.rst +++ /dev/null @@ -1,8 +0,0 @@ -CPACK_INSTALL_SCRIPT --------------------- - -Extra CMake script provided by the user. - -If set this CMake script will be executed by CPack during its local -[CPack-private] installation which is done right before packaging the -files. The script is not called by e.g.: ``make install``. diff --git a/Help/variable/CTEST_CUSTOM_TEST_IGNORE.rst b/Help/variable/CTEST_CUSTOM_TESTS_IGNORE.rst index 6114e608c..57222ca1e 100644 --- a/Help/variable/CTEST_CUSTOM_TEST_IGNORE.rst +++ b/Help/variable/CTEST_CUSTOM_TESTS_IGNORE.rst @@ -1,5 +1,5 @@ -CTEST_CUSTOM_TEST_IGNORE ------------------------- +CTEST_CUSTOM_TESTS_IGNORE +------------------------- A list of regular expressions to use to exclude tests during the :command:`ctest_test` command. diff --git a/Help/variable/CTEST_CUSTOM_WARNING_EXCEPTION.rst b/Help/variable/CTEST_CUSTOM_WARNING_EXCEPTION.rst index 36fa37d92..a03d47342 100644 --- a/Help/variable/CTEST_CUSTOM_WARNING_EXCEPTION.rst +++ b/Help/variable/CTEST_CUSTOM_WARNING_EXCEPTION.rst @@ -2,6 +2,6 @@ CTEST_CUSTOM_WARNING_EXCEPTION ------------------------------ A list of regular expressions which will be used to exclude when detecting -warning messages in build outputs by the :command:`ctest_test` command. +warning messages in build outputs by the :command:`ctest_build` command. .. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_CUSTOM_WARNING_MATCH.rst b/Help/variable/CTEST_CUSTOM_WARNING_MATCH.rst index a35be96b5..18aa6b31d 100644 --- a/Help/variable/CTEST_CUSTOM_WARNING_MATCH.rst +++ b/Help/variable/CTEST_CUSTOM_WARNING_MATCH.rst @@ -2,6 +2,6 @@ CTEST_CUSTOM_WARNING_MATCH -------------------------- A list of regular expressions which will be used to detect warning messages in -build outputs by the :command:`ctest_test` command. +build outputs by the :command:`ctest_build` command. .. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_LABELS_FOR_SUBPROJECTS.rst b/Help/variable/CTEST_LABELS_FOR_SUBPROJECTS.rst new file mode 100644 index 000000000..959596bf3 --- /dev/null +++ b/Help/variable/CTEST_LABELS_FOR_SUBPROJECTS.rst @@ -0,0 +1,5 @@ +CTEST_LABELS_FOR_SUBPROJECTS +---------------------------- + +Specify the CTest ``LabelsForSubprojects`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_RUN_CURRENT_SCRIPT.rst b/Help/variable/CTEST_RUN_CURRENT_SCRIPT.rst new file mode 100644 index 000000000..abc123c09 --- /dev/null +++ b/Help/variable/CTEST_RUN_CURRENT_SCRIPT.rst @@ -0,0 +1,5 @@ +CTEST_RUN_CURRENT_SCRIPT +------------------------ + +Setting this to 0 prevents :manual:`ctest(1)` from being run again when it +reaches the end of a script run by calling ``ctest -S``. diff --git a/Help/variable/CTEST_SCP_COMMAND.rst b/Help/variable/CTEST_SCP_COMMAND.rst index 0f128b14a..19ea8b33d 100644 --- a/Help/variable/CTEST_SCP_COMMAND.rst +++ b/Help/variable/CTEST_SCP_COMMAND.rst @@ -1,5 +1,4 @@ CTEST_SCP_COMMAND ----------------- -Specify the CTest ``SCPCommand`` setting -in a :manual:`ctest(1)` dashboard client script. +Legacy option. Not used. diff --git a/Help/variable/CTEST_SUBMIT_URL.rst b/Help/variable/CTEST_SUBMIT_URL.rst new file mode 100644 index 000000000..7d84da4b4 --- /dev/null +++ b/Help/variable/CTEST_SUBMIT_URL.rst @@ -0,0 +1,5 @@ +CTEST_SUBMIT_URL +---------------- + +Specify the CTest ``SubmitURL`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_TRIGGER_SITE.rst b/Help/variable/CTEST_TRIGGER_SITE.rst index de9242807..a50e405cc 100644 --- a/Help/variable/CTEST_TRIGGER_SITE.rst +++ b/Help/variable/CTEST_TRIGGER_SITE.rst @@ -1,5 +1,4 @@ CTEST_TRIGGER_SITE ------------------ -Specify the CTest ``TriggerSite`` setting -in a :manual:`ctest(1)` dashboard client script. +Legacy option. Not used. diff --git a/Help/variable/CTEST_UPDATE_VERSION_ONLY.rst b/Help/variable/CTEST_UPDATE_VERSION_ONLY.rst index e646e6eea..a862baa14 100644 --- a/Help/variable/CTEST_UPDATE_VERSION_ONLY.rst +++ b/Help/variable/CTEST_UPDATE_VERSION_ONLY.rst @@ -1,5 +1,5 @@ CTEST_UPDATE_VERSION_ONLY ------------------------- -Specify the CTest ``UpdateVersionOnly`` setting +Specify the CTest :ref:`UpdateVersionOnly <UpdateVersionOnly>` setting in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_UPDATE_VERSION_OVERRIDE.rst b/Help/variable/CTEST_UPDATE_VERSION_OVERRIDE.rst new file mode 100644 index 000000000..39fbaba79 --- /dev/null +++ b/Help/variable/CTEST_UPDATE_VERSION_OVERRIDE.rst @@ -0,0 +1,5 @@ +CTEST_UPDATE_VERSION_OVERRIDE +----------------------------- + +Specify the CTest :ref:`UpdateVersionOverride <UpdateVersionOverride>` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/ENV.rst b/Help/variable/ENV.rst index 368152aeb..2b439342e 100644 --- a/Help/variable/ENV.rst +++ b/Help/variable/ENV.rst @@ -1,7 +1,12 @@ ENV --- -Access environment variables. +Operator to read environment variables. -Use the syntax ``$ENV{VAR}`` to read environment variable ``VAR``. See also -the :command:`set` command to set ``ENV{VAR}``. +Use the syntax ``$ENV{VAR}`` to read environment variable ``VAR``. + +To test whether an environment variable is defined, use the signature +``if(DEFINED ENV{<name>})`` of the :command:`if` command. + +See the :command:`set` and :command:`unset` commands to see how to +write or remove environment variables. diff --git a/Help/variable/GHS-MULTI.rst b/Help/variable/GHS-MULTI.rst index 0f91be8ad..fe3b17e18 100644 --- a/Help/variable/GHS-MULTI.rst +++ b/Help/variable/GHS-MULTI.rst @@ -1,4 +1,4 @@ GHS-MULTI --------- -True when using Green Hills MULTI +``True`` when using :generator:`Green Hills MULTI` generator. diff --git a/Help/variable/IOS.rst b/Help/variable/IOS.rst new file mode 100644 index 000000000..e5cc3f69c --- /dev/null +++ b/Help/variable/IOS.rst @@ -0,0 +1,4 @@ +IOS +--- + +Set to ``1`` when the target system (:variable:`CMAKE_SYSTEM_NAME`) is ``iOS``. diff --git a/Help/variable/LIBRARY_OUTPUT_PATH.rst b/Help/variable/LIBRARY_OUTPUT_PATH.rst index ba02911e6..bb4328f5b 100644 --- a/Help/variable/LIBRARY_OUTPUT_PATH.rst +++ b/Help/variable/LIBRARY_OUTPUT_PATH.rst @@ -5,5 +5,5 @@ Old library location variable. The target properties :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY`, :prop_tgt:`LIBRARY_OUTPUT_DIRECTORY`, and :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` -supercede this variable for a target if they are set. Library targets are +supersede this variable for a target if they are set. Library targets are otherwise placed in this directory. diff --git a/Help/variable/MSVC.rst b/Help/variable/MSVC.rst index 22a087a77..ca8775cb3 100644 --- a/Help/variable/MSVC.rst +++ b/Help/variable/MSVC.rst @@ -1,8 +1,8 @@ MSVC ---- -``True`` when using Microsoft Visual C++. - -Set to ``true`` when the compiler is some version of Microsoft Visual C++. +Set to ``true`` when the compiler is some version of Microsoft Visual +C++ or another compiler simulating Visual C++. Any compiler defining +``_MSC_VER`` is considered simulating Visual C++. See also the :variable:`MSVC_VERSION` variable. diff --git a/Help/variable/MSVC_TOOLSET_VERSION.rst b/Help/variable/MSVC_TOOLSET_VERSION.rst new file mode 100644 index 000000000..f4a33e246 --- /dev/null +++ b/Help/variable/MSVC_TOOLSET_VERSION.rst @@ -0,0 +1,22 @@ +MSVC_TOOLSET_VERSION +-------------------- + +The toolset version of Microsoft Visual C/C++ being used if any. +If MSVC-like is being used, this variable is set based on the version +of the compiler as given by the :variable:`MSVC_VERSION` variable. + +Known toolset version numbers are:: + + 80 = VS 2005 (8.0) + 90 = VS 2008 (9.0) + 100 = VS 2010 (10.0) + 110 = VS 2012 (11.0) + 120 = VS 2013 (12.0) + 140 = VS 2015 (14.0) + 141 = VS 2017 (15.0) + 142 = VS 2019 (16.0) + +Compiler versions newer than those known to CMake will be reported +as the latest known toolset version. + +See also the :variable:`MSVC_VERSION` variable. diff --git a/Help/variable/MSVC_VERSION.rst b/Help/variable/MSVC_VERSION.rst index 8932147c6..45df37fa0 100644 --- a/Help/variable/MSVC_VERSION.rst +++ b/Help/variable/MSVC_VERSION.rst @@ -2,16 +2,23 @@ MSVC_VERSION ------------ The version of Microsoft Visual C/C++ being used if any. +If a compiler simulating Visual C++ is being used, this variable is set +to the toolset version simulated as given by the ``_MSC_VER`` +preprocessor definition. Known version numbers are:: - 1200 = VS 6.0 - 1300 = VS 7.0 - 1310 = VS 7.1 - 1400 = VS 8.0 - 1500 = VS 9.0 - 1600 = VS 10.0 - 1700 = VS 11.0 - 1800 = VS 12.0 - 1900 = VS 14.0 - 1910 = VS 15.0 + 1200 = VS 6.0 + 1300 = VS 7.0 + 1310 = VS 7.1 + 1400 = VS 8.0 (v80 toolset) + 1500 = VS 9.0 (v90 toolset) + 1600 = VS 10.0 (v100 toolset) + 1700 = VS 11.0 (v110 toolset) + 1800 = VS 12.0 (v120 toolset) + 1900 = VS 14.0 (v140 toolset) + 1910-1919 = VS 15.0 (v141 toolset) + 1920-1929 = VS 16.0 (v142 toolset) + +See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` and +:variable:`MSVC_TOOLSET_VERSION` variable. diff --git a/Help/variable/MSYS.rst b/Help/variable/MSYS.rst new file mode 100644 index 000000000..25ddc7f73 --- /dev/null +++ b/Help/variable/MSYS.rst @@ -0,0 +1,4 @@ +MSYS +---- + +``True`` when using the :generator:`MSYS Makefiles` generator. diff --git a/Help/variable/PROJECT-NAME_DESCRIPTION.rst b/Help/variable/PROJECT-NAME_DESCRIPTION.rst new file mode 100644 index 000000000..2b88b1acf --- /dev/null +++ b/Help/variable/PROJECT-NAME_DESCRIPTION.rst @@ -0,0 +1,5 @@ +<PROJECT-NAME>_DESCRIPTION +-------------------------- + +Value given to the ``DESCRIPTION`` option of the most recent call to the +:command:`project` command with project name ``<PROJECT-NAME>``, if any. diff --git a/Help/variable/PROJECT-NAME_HOMEPAGE_URL.rst b/Help/variable/PROJECT-NAME_HOMEPAGE_URL.rst new file mode 100644 index 000000000..22cc304b0 --- /dev/null +++ b/Help/variable/PROJECT-NAME_HOMEPAGE_URL.rst @@ -0,0 +1,5 @@ +<PROJECT-NAME>_HOMEPAGE_URL +--------------------------- + +Value given to the ``HOMEPAGE_URL`` option of the most recent call to the +:command:`project` command with project name ``<PROJECT-NAME>``, if any. diff --git a/Help/variable/PROJECT_DESCRIPTION.rst b/Help/variable/PROJECT_DESCRIPTION.rst index 05ede8fcc..2833e1101 100644 --- a/Help/variable/PROJECT_DESCRIPTION.rst +++ b/Help/variable/PROJECT_DESCRIPTION.rst @@ -3,4 +3,7 @@ PROJECT_DESCRIPTION Short project description given to the project command. -This is the description given to the most recent :command:`project` command. +This is the description given to the most recently called :command:`project` +command in the current directory scope or above. To obtain the description +of the top level project, see the :variable:`CMAKE_PROJECT_DESCRIPTION` +variable. diff --git a/Help/variable/PROJECT_HOMEPAGE_URL.rst b/Help/variable/PROJECT_HOMEPAGE_URL.rst new file mode 100644 index 000000000..754c9e8b3 --- /dev/null +++ b/Help/variable/PROJECT_HOMEPAGE_URL.rst @@ -0,0 +1,9 @@ +PROJECT_HOMEPAGE_URL +-------------------- + +The homepage URL of the project. + +This is the homepage URL given to the most recently called :command:`project` +command in the current directory scope or above. To obtain the homepage URL +of the top level project, see the :variable:`CMAKE_PROJECT_HOMEPAGE_URL` +variable. diff --git a/Help/variable/PROJECT_NAME.rst b/Help/variable/PROJECT_NAME.rst index 61aa8bc00..672680a71 100644 --- a/Help/variable/PROJECT_NAME.rst +++ b/Help/variable/PROJECT_NAME.rst @@ -3,4 +3,6 @@ PROJECT_NAME Name of the project given to the project command. -This is the name given to the most recent :command:`project` command. +This is the name given to the most recently called :command:`project` +command in the current directory scope or above. To obtain the name of +the top level project, see the :variable:`CMAKE_PROJECT_NAME` variable. diff --git a/Help/variable/PackageName_ROOT.rst b/Help/variable/PackageName_ROOT.rst new file mode 100644 index 000000000..1c2fd34f3 --- /dev/null +++ b/Help/variable/PackageName_ROOT.rst @@ -0,0 +1,14 @@ +<PackageName>_ROOT +------------------ + +Calls to :command:`find_package(<PackageName>)` will search in prefixes +specified by the ``<PackageName>_ROOT`` CMake variable, where +``<PackageName>`` is the name given to the :command:`find_package` call +and ``_ROOT`` is literal. For example, ``find_package(Foo)`` will search +prefixes specified in the ``Foo_ROOT`` CMake variable (if set). +See policy :policy:`CMP0074`. + +This variable may hold a single prefix or a +:ref:`semicolon-separated list <CMake Language Lists>` of multiple prefixes. + +See also the :envvar:`<PackageName>_ROOT` environment variable. diff --git a/Help/variable/UNIX.rst b/Help/variable/UNIX.rst index 0877b7c07..49d866838 100644 --- a/Help/variable/UNIX.rst +++ b/Help/variable/UNIX.rst @@ -1,7 +1,7 @@ UNIX ---- -``True`` for UNIX and UNIX like operating systems. - -Set to ``true`` when the target system is UNIX or UNIX like (i.e. -:variable:`APPLE` and :variable:`CYGWIN`). +Set to ``True`` when the target system is UNIX or UNIX-like +(e.g. :variable:`APPLE` and :variable:`CYGWIN`). The +:variable:`CMAKE_SYSTEM_NAME` variable should be queried if +a more specific understanding of the target system is required. diff --git a/Help/variable/WIN32.rst b/Help/variable/WIN32.rst index 218906955..78ab77279 100644 --- a/Help/variable/WIN32.rst +++ b/Help/variable/WIN32.rst @@ -1,6 +1,4 @@ WIN32 ----- -``True`` on Windows systems, including Win64. - -Set to ``true`` when the target system is Windows. +Set to ``True`` when the target system is Windows, including Win64. diff --git a/Help/variable/XCODE_VERSION.rst b/Help/variable/XCODE_VERSION.rst index b85d41e91..9caf19a41 100644 --- a/Help/variable/XCODE_VERSION.rst +++ b/Help/variable/XCODE_VERSION.rst @@ -3,5 +3,5 @@ XCODE_VERSION Version of Xcode (:generator:`Xcode` generator only). -Under the Xcode generator, this is the version of Xcode as specified -in ``Xcode.app/Contents/version.plist`` (such as ``3.1.2``). +Under the :generator:`Xcode` generator, this is the version of Xcode +as specified in ``Xcode.app/Contents/version.plist`` (such as ``3.1.2``). |