diff options
Diffstat (limited to 'Help')
1960 files changed, 67684 insertions, 0 deletions
diff --git a/Help/command/DEVICE_LINK_OPTIONS.txt b/Help/command/DEVICE_LINK_OPTIONS.txt new file mode 100644 index 0000000..1297cd0 --- /dev/null +++ b/Help/command/DEVICE_LINK_OPTIONS.txt @@ -0,0 +1,12 @@ + +.. versionadded:: 3.18 + When a device link step is involved, which is controlled by + :prop_tgt:`CUDA_SEPARABLE_COMPILATION` and + :prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` properties and policy :policy:`CMP0105`, + the raw options will be delivered to the host and device link steps (wrapped in + ``-Xcompiler`` or equivalent for device link). Options wrapped with + ``$<DEVICE_LINK:...>`` + :manual:`generator expression <cmake-generator-expressions(7)>` will be used + only for the device link step. Options wrapped with ``$<HOST_LINK:...>`` + :manual:`generator expression <cmake-generator-expressions(7)>` will be used + only for the host link step. diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt new file mode 100644 index 0000000..aae1c38 --- /dev/null +++ b/Help/command/FIND_XXX.txt @@ -0,0 +1,167 @@ +A short-hand signature is: + +.. parsed-literal:: + + |FIND_XXX| (<VAR> name1 [path1 path2 ...]) + +The general signature is: + +.. parsed-literal:: + + |FIND_XXX| ( + <VAR> + name | |NAMES| + [HINTS [path | ENV var]... ] + [PATHS [path | ENV var]... ] + [PATH_SUFFIXES suffix1 [suffix2 ...]] + [DOC "cache documentation string"] + [REQUIRED] + [NO_DEFAULT_PATH] + [NO_PACKAGE_ROOT_PATH] + [NO_CMAKE_PATH] + [NO_CMAKE_ENVIRONMENT_PATH] + [NO_SYSTEM_ENVIRONMENT_PATH] + [NO_CMAKE_SYSTEM_PATH] + [CMAKE_FIND_ROOT_PATH_BOTH | + ONLY_CMAKE_FIND_ROOT_PATH | + NO_CMAKE_FIND_ROOT_PATH] + ) + +This command is used to find a |SEARCH_XXX_DESC|. +A cache entry named by ``<VAR>`` is created to store the result +of this command. +If the |SEARCH_XXX| is found the result is stored in the variable +and the search will not be repeated unless the variable is cleared. +If nothing is found, the result will be ``<VAR>-NOTFOUND``. + +Options include: + +``NAMES`` + Specify one or more possible names for the |SEARCH_XXX|. + + When using this to specify names with and without a version + suffix, we recommend specifying the unversioned name first + so that locally-built packages can be found before those + provided by distributions. + +``HINTS``, ``PATHS`` + Specify directories to search in addition to the default locations. + The ``ENV var`` sub-option reads paths from a system environment + variable. + +``PATH_SUFFIXES`` + Specify additional subdirectories to check below each directory + location otherwise considered. + +``DOC`` + Specify the documentation string for the ``<VAR>`` cache entry. + +``REQUIRED`` + .. versionadded:: 3.18 + + Stop processing with an error message if nothing is found, otherwise + the search will be attempted again the next time |FIND_XXX| is invoked + with the same variable. + +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` + +.. |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR| replace:: + |prefix_XXX_SUBDIR| for each ``<prefix>/[s]bin`` in ``PATH``, and + |entry_XXX_SUBDIR| for other entries in ``PATH`` + +.. |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| replace:: + |prefix_XXX_SUBDIR| for each ``<prefix>`` in + :variable:`CMAKE_SYSTEM_PREFIX_PATH` + +1. .. versionadded:: 3.12 + 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:`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| + +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 or + by setting the :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` to ``FALSE``. + + * |CMAKE_PREFIX_PATH_XXX| + * |CMAKE_XXX_PATH| + * |CMAKE_XXX_MAC_PATH| + +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. + +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| + +6. Search cmake variables defined in the Platform files + for the current system. This can be skipped if ``NO_CMAKE_SYSTEM_PATH`` + 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| + + The platform paths that these variables contain are locations that + typically include installed software. An example being ``/usr/local`` for + UNIX based platforms. + +7. Search the paths specified by the PATHS option + or in the short-hand version of the command. + These are typically hard-coded guesses. + +.. versionadded:: 3.16 + Added ``CMAKE_FIND_USE_<CATEGORY>_PATH`` variables to globally disable + various search locations. + +.. |FIND_ARGS_XXX| replace:: <VAR> NAMES name + +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. + +.. include:: FIND_XXX_ROOT.txt +.. include:: FIND_XXX_ORDER.txt diff --git a/Help/command/FIND_XXX_ORDER.txt b/Help/command/FIND_XXX_ORDER.txt new file mode 100644 index 0000000..bac2419 --- /dev/null +++ b/Help/command/FIND_XXX_ORDER.txt @@ -0,0 +1,12 @@ +The default search order is designed to be most-specific to +least-specific for common use cases. +Projects may override the order by simply calling the command +multiple times and using the ``NO_*`` options: + +.. parsed-literal:: + + |FIND_XXX| (|FIND_ARGS_XXX| PATHS paths... NO_DEFAULT_PATH) + |FIND_XXX| (|FIND_ARGS_XXX|) + +Once one of the calls succeeds the result variable will be set +and stored in the cache so that no call will search again. diff --git a/Help/command/FIND_XXX_ROOT.txt b/Help/command/FIND_XXX_ROOT.txt new file mode 100644 index 0000000..fab2303 --- /dev/null +++ b/Help/command/FIND_XXX_ROOT.txt @@ -0,0 +1,29 @@ +The CMake variable :variable:`CMAKE_FIND_ROOT_PATH` specifies one or more +directories to be prepended to all other search directories. This +effectively "re-roots" the entire search under given locations. +Paths which are descendants of the :variable:`CMAKE_STAGING_PREFIX` are excluded +from this re-rooting, because that variable is always a path on the host system. +By default the :variable:`CMAKE_FIND_ROOT_PATH` is empty. + +The :variable:`CMAKE_SYSROOT` variable can also be used to specify exactly one +directory to use as a prefix. Setting :variable:`CMAKE_SYSROOT` also has other +effects. See the documentation for that variable for more. + +These variables are especially useful when cross-compiling to +point to the root directory of the target environment and CMake will +search there too. By default at first the directories listed in +:variable:`CMAKE_FIND_ROOT_PATH` are searched, then the :variable:`CMAKE_SYSROOT` +directory is searched, and then the non-rooted directories will be +searched. The default behavior can be adjusted by setting +|CMAKE_FIND_ROOT_PATH_MODE_XXX|. This behavior can be manually +overridden on a per-call basis using options: + +``CMAKE_FIND_ROOT_PATH_BOTH`` + Search in the order described above. + +``NO_CMAKE_FIND_ROOT_PATH`` + Do not use the :variable:`CMAKE_FIND_ROOT_PATH` variable. + +``ONLY_CMAKE_FIND_ROOT_PATH`` + Search only the re-rooted directories and directories below + :variable:`CMAKE_STAGING_PREFIX`. diff --git a/Help/command/LINK_OPTIONS_LINKER.txt b/Help/command/LINK_OPTIONS_LINKER.txt new file mode 100644 index 0000000..3f66181 --- /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 0000000..4051ffe --- /dev/null +++ b/Help/command/OPTIONS_SHELL.txt @@ -0,0 +1,11 @@ +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. + +.. versionadded:: 3.12 + 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 0000000..48e33be --- /dev/null +++ b/Help/command/add_compile_definitions.rst @@ -0,0 +1,27 @@ +add_compile_definitions +----------------------- + +.. versionadded:: 3.12 + +Add preprocessor definitions to the compilation of source files. + +.. code-block:: cmake + + add_compile_definitions(<definition> ...) + +Adds preprocessor definitions to the compiler command line. + +The preprocessor definitions are added to the :prop_dir:`COMPILE_DEFINITIONS` +directory property for the current ``CMakeLists`` file. They are also added to +the :prop_tgt:`COMPILE_DEFINITIONS` target property for each target in the +current ``CMakeLists`` file. + +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 new file mode 100644 index 0000000..36f403c --- /dev/null +++ b/Help/command/add_compile_options.rst @@ -0,0 +1,51 @@ +add_compile_options +------------------- + +Add options to the compilation of source files. + +.. code-block:: cmake + + add_compile_options(<option> ...) + +Adds options to the :prop_dir:`COMPILE_OPTIONS` directory property. +These options are used when compiling targets from the current +directory and below. + +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. + +The source file property :prop_sf:`COMPILE_OPTIONS` adds options to one +source file. diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst new file mode 100644 index 0000000..569f1e8 --- /dev/null +++ b/Help/command/add_custom_command.rst @@ -0,0 +1,435 @@ +add_custom_command +------------------ + +Add a custom build rule to the generated build system. + +There are two main signatures for ``add_custom_command``. + +Generating Files +^^^^^^^^^^^^^^^^ + +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...] + [COMMAND command2 [ARGS] [args2...] ...] + [MAIN_DEPENDENCY depend] + [DEPENDS [depends...]] + [BYPRODUCTS [files...]] + [IMPLICIT_DEPENDS <lang1> depend1 + [<lang2> depend2] ...] + [WORKING_DIRECTORY dir] + [COMMENT comment] + [DEPFILE depfile] + [JOB_POOL job_pool] + [VERBATIM] [APPEND] [USES_TERMINAL] + [COMMAND_EXPAND_LISTS]) + +This defines a command to generate specified ``OUTPUT`` file(s). +A target created in the same directory (``CMakeLists.txt`` file) +that specifies any output of the custom command as a source file +is given a rule to generate the file using the command at build time. +Do not list the output in more than one independent target that +may build in parallel or the two instances of the rule may conflict +(instead use the :command:`add_custom_target` command to drive the +command and make the other targets depend on that one). +In makefile terms this creates a new target in the following form:: + + OUTPUT: MAIN_DEPENDENCY DEPENDS + COMMAND + +The options are: + +``APPEND`` + Append the ``COMMAND`` and ``DEPENDS`` option values to the custom + command for the first output specified. There must have already + been a previous call to this command with the same output. + + If the previous call specified the output via a generator expression, + the output specified by the current call must match in at least one + configuration after evaluating generator expressions. In this case, + the appended commands and dependencies apply to all configurations. + + The ``COMMENT``, ``MAIN_DEPENDENCY``, and ``WORKING_DIRECTORY`` + options are currently ignored when APPEND is given, but may be + used in the future. + +``BYPRODUCTS`` + .. versionadded:: 3.2 + + Specify the files the command is expected to produce but whose + modification time may or may not be newer than the dependencies. + If a byproduct name is a relative path it will be interpreted + relative to the build tree directory corresponding to the + current source directory. + Each byproduct file will be marked with the :prop_sf:`GENERATED` + source file property automatically. + + Explicit specification of byproducts is supported by the + :generator:`Ninja` generator to tell the ``ninja`` build tool + how to regenerate byproducts when they are missing. It is + also useful when other build rules (e.g. custom commands) + depend on the byproducts. Ninja requires a build rule for any + generated file on which another rule depends even if there are + order-only dependencies to ensure the byproducts will be + available before their dependents build. + + The :ref:`Makefile Generators` will remove ``BYPRODUCTS`` and other + :prop_sf:`GENERATED` files during ``make clean``. + + .. versionadded:: 3.20 + Arguments to ``BYPRODUCTS`` may use a restricted set of + :manual:`generator expressions <cmake-generator-expressions(7)>`. + :ref:`Target-dependent expressions <Target-Dependent Queries>` are not + permitted. + +``COMMAND`` + Specify the command-line(s) to execute at build time. + If more than one ``COMMAND`` is specified they will be executed in order, + but *not* necessarily composed into a stateful shell or batch script. + (To run a full script, use the :command:`configure_file` command or the + :command:`file(GENERATE)` command to create it, and then specify + a ``COMMAND`` to launch it.) + The optional ``ARGS`` argument is for backward compatibility and + 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 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). + * .. versionadded:: 3.6 + 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)>`. + Use the :genex:`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 one of the following target based generator expressions are used as + a command to execute or is mentioned in 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 + (see policy :policy:`CMP0112`). + + * ``TARGET_FILE`` + * ``TARGET_LINKER_FILE`` + * ``TARGET_SONAME_FILE`` + * ``TARGET_PDB_FILE`` + + This target-level dependency 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 + build time. + +``DEPENDS`` + Specify files on which the command depends. Each argument is converted + to a dependency as follows: + + 1. If the argument is the name of a target (created by the + :command:`add_custom_target`, :command:`add_executable`, or + :command:`add_library` command) a target-level dependency is + created to make sure the target is built before any target + using this custom command. Additionally, if the target is an + executable or library, a file-level dependency is created to + cause the custom command to re-run whenever the target is + recompiled. + + 2. If the argument is an absolute path, a file-level dependency + is created on that path. + + 3. If the argument is the name of a source file that has been + added to a target or on which a source file property has been set, + a file-level dependency is created on that source file. + + 4. If the argument is a relative path and it exists in the current + source directory, a file-level dependency is created on that + file in the current source directory. + + 5. Otherwise, a file-level dependency is created on that path relative + to the current binary directory. + + If any dependency is 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. + + .. versionadded:: 3.16 + 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``, the rule will always run. + + .. versionadded:: 3.1 + Arguments to ``DEPENDS`` may use + :manual:`generator expressions <cmake-generator-expressions(7)>`. + +``COMMAND_EXPAND_LISTS`` + .. versionadded:: 3.8 + + Lists in ``COMMAND`` arguments will be expanded, including those + created with + :manual:`generator expressions <cmake-generator-expressions(7)>`, + allowing ``COMMAND`` arguments such as + ``${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTORIES>,;-I>" foo.cc`` + to be properly expanded. + +``IMPLICIT_DEPENDS`` + Request scanning of implicit dependencies of an input file. + The language given specifies the programming language whose + corresponding dependency scanner should be used. + Currently only ``C`` and ``CXX`` language scanners are supported. + The language has to be specified for every file in the + ``IMPLICIT_DEPENDS`` list. Dependencies discovered from the + scanning are added to those of the custom command at build time. + Note that the ``IMPLICIT_DEPENDS`` option is currently supported + only for Makefile generators and will be ignored by other generators. + + .. note:: + + This option cannot be specified at the same time as ``DEPFILE`` option. + +``JOB_POOL`` + .. versionadded:: 3.15 + + 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. 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. + If an output name is a relative path it will be interpreted + relative to the build tree directory corresponding to the + current source directory. + Each output file will be marked with the :prop_sf:`GENERATED` + source file property automatically. + If the output of the custom command is not actually created + as a file on disk it should be marked with the :prop_sf:`SYMBOLIC` + source file property. + + .. versionadded:: 3.20 + Arguments to ``OUTPUT`` may use a restricted set of + :manual:`generator expressions <cmake-generator-expressions(7)>`. + :ref:`Target-dependent expressions <Target-Dependent Queries>` are not + permitted. + +``USES_TERMINAL`` + .. versionadded:: 3.2 + + The command will be given direct access to the terminal if possible. + With the :generator:`Ninja` generator, this places the command in + the ``console`` :prop_gbl:`pool <JOB_POOLS>`. + +``VERBATIM`` + All arguments to the commands will be escaped properly for the + build tool so that the invoked command receives each argument + unchanged. Note that one level of escapes is still used by the + CMake language processor before add_custom_command even sees the + arguments. Use of ``VERBATIM`` is recommended as it enables + correct behavior. When ``VERBATIM`` is not given the behavior + is platform specific because there is no protection of + tool-specific special characters. + +``WORKING_DIRECTORY`` + 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. + + .. versionadded:: 3.13 + Arguments to ``WORKING_DIRECTORY`` may use + :manual:`generator expressions <cmake-generator-expressions(7)>`. + +``DEPFILE`` + .. versionadded:: 3.7 + + Specify a ``.d`` depfile for the :generator:`Ninja`, :generator:`Xcode` and + :ref:`Makefile <Makefile Generators>` generators. The depfile may use + "generator expressions" with the syntax ``$<...>``. See the + :manual:`generator-expressions(7) <cmake-generator-expressions(7)>` manual + for available expressions. A ``.d`` file holds dependencies usually emitted + by the custom command itself. + + Using ``DEPFILE`` with other generators than :generator:`Ninja`, + :generator:`Xcode` or :ref:`Makefile <Makefile Generators>` is an error. + + .. versionadded:: 3.20 + Added the support of :ref:`Makefile Generators`. + + .. versionadded:: 3.21 + Added the support of :generator:`Xcode` generator and + :manual:`generator expressions <cmake-generator-expressions(7)>`. + + If the ``DEPFILE`` argument is relative, it should be relative to + :variable:`CMAKE_CURRENT_BINARY_DIR`, and any relative paths inside the + ``DEPFILE`` should also be relative to :variable:`CMAKE_CURRENT_BINARY_DIR` + (see policy :policy:`CMP0116`. This policy is always ``NEW`` for + :ref:`Makefile <Makefile Generators>` and :generator:`Xcode` generators). + + .. note:: + + For :ref:`Makefile Generators`, this option cannot be specified at the + same time as ``IMPLICIT_DEPENDS`` option. + +Examples: Generating Files +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Custom commands may be used to generate source files. +For example, the code: + +.. code-block:: cmake + + add_custom_command( + OUTPUT out.c + COMMAND someTool -i ${CMAKE_CURRENT_SOURCE_DIR}/in.txt + -o out.c + DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/in.txt + VERBATIM) + add_library(myLib out.c) + +adds a custom command to run ``someTool`` to generate ``out.c`` and then +compile the generated source as part of a library. The generation rule +will re-run whenever ``in.txt`` changes. + +.. versionadded:: 3.20 + One may use generator expressions to specify per-configuration outputs. + For example, the code: + + .. code-block:: cmake + + add_custom_command( + OUTPUT "out-$<CONFIG>.c" + COMMAND someTool -i ${CMAKE_CURRENT_SOURCE_DIR}/in.txt + -o "out-$<CONFIG>.c" + -c "$<CONFIG>" + DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/in.txt + VERBATIM) + add_library(myLib "out-$<CONFIG>.c") + + adds a custom command to run ``someTool`` to generate ``out-<config>.c``, + where ``<config>`` is the build configuration, and then compile the generated + source as part of a library. + +Build Events +^^^^^^^^^^^^ + +The second signature adds a custom command to a target such as a +library or executable. This is useful for performing an operation +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 + COMMAND command1 [ARGS] [args1...] + [COMMAND command2 [ARGS] [args2...] ...] + [BYPRODUCTS [files...]] + [WORKING_DIRECTORY dir] + [COMMENT comment] + [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 +directory; targets defined in other directories may not be specified. + +When the command will happen is determined by which +of the following is specified: + +``PRE_BUILD`` + 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. + This is not defined for targets created by the + :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. + +Examples: Build Events +^^^^^^^^^^^^^^^^^^^^^^ + +A ``POST_BUILD`` event may be used to post-process a binary after linking. +For example, the code: + +.. code-block:: cmake + + add_executable(myExe myExe.c) + add_custom_command( + TARGET myExe POST_BUILD + COMMAND someHasher -i "$<TARGET_FILE:myExe>" + -o "$<TARGET_FILE:myExe>.hash" + VERBATIM) + +will run ``someHasher`` to produce a ``.hash`` file next to the executable +after linking. + +.. versionadded:: 3.20 + One may use generator expressions to specify per-configuration byproducts. + For example, the code: + + .. code-block:: cmake + + add_library(myPlugin MODULE myPlugin.c) + add_custom_command( + TARGET myPlugin POST_BUILD + COMMAND someHasher -i "$<TARGET_FILE:myPlugin>" + --as-code "myPlugin-hash-$<CONFIG>.c" + BYPRODUCTS "myPlugin-hash-$<CONFIG>.c" + VERBATIM) + add_executable(myExe myExe.c "myPlugin-hash-$<CONFIG>.c") + + will run ``someHasher`` after linking ``myPlugin``, e.g. to produce a ``.c`` + file containing code to check the hash of ``myPlugin`` that the ``myExe`` + executable can use to verify it before loading. + +Ninja Multi-Config +^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 3.20 + + ``add_custom_command`` supports the :generator:`Ninja Multi-Config` + generator's cross-config capabilities. See the generator documentation + for more information. diff --git a/Help/command/add_custom_target.rst b/Help/command/add_custom_target.rst new file mode 100644 index 0000000..def23fa --- /dev/null +++ b/Help/command/add_custom_target.rst @@ -0,0 +1,181 @@ +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...] ...] + [DEPENDS depend depend depend ... ] + [BYPRODUCTS [files...]] + [WORKING_DIRECTORY dir] + [COMMENT comment] + [JOB_POOL job_pool] + [VERBATIM] [USES_TERMINAL] + [COMMAND_EXPAND_LISTS] + [SOURCES src1 [src2...]]) + +Adds a target with the given name that executes the given commands. +The target has no output file and is *always considered out of date* +even if the commands try to create a file with the name of the target. +Use the :command:`add_custom_command` command to generate a file with +dependencies. By default nothing depends on the custom target. Use +the :command:`add_dependencies` command to add dependencies to or +from other targets. + +The options are: + +``ALL`` + Indicate that this target should be added to the default build + target so that it will be run every time (the command cannot be + called ``ALL``). + +``BYPRODUCTS`` + .. versionadded:: 3.2 + + Specify the files the command is expected to produce but whose + modification time may or may not be updated on subsequent builds. + If a byproduct name is a relative path it will be interpreted + relative to the build tree directory corresponding to the + current source directory. + Each byproduct file will be marked with the :prop_sf:`GENERATED` + source file property automatically. + + Explicit specification of byproducts is supported by the + :generator:`Ninja` generator to tell the ``ninja`` build tool + how to regenerate byproducts when they are missing. It is + also useful when other build rules (e.g. custom commands) + depend on the byproducts. Ninja requires a build rule for any + generated file on which another rule depends even if there are + order-only dependencies to ensure the byproducts will be + available before their dependents build. + + The :ref:`Makefile Generators` will remove ``BYPRODUCTS`` and other + :prop_sf:`GENERATED` files during ``make clean``. + + .. versionadded:: 3.20 + Arguments to ``BYPRODUCTS`` may use a restricted set of + :manual:`generator expressions <cmake-generator-expressions(7)>`. + :ref:`Target-dependent expressions <Target-Dependent Queries>` are not + permitted. + +``COMMAND`` + Specify the command-line(s) to execute at build time. + If more than one ``COMMAND`` is specified they will be executed in order, + but *not* necessarily composed into a stateful shell or batch script. + (To run a full script, use the :command:`configure_file` command or the + :command:`file(GENERATE)` command to create it, and then specify + 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 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). + * .. versionadded:: 3.6 + 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)>`. + Use the :genex:`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 one of the following target based generator expressions are used as + a command to execute or is mentioned in a command argument, a target-level + dependency will be added automatically so that the mentioned target will be + built before this custom target (see policy :policy:`CMP0112`). + + * ``TARGET_FILE`` + * ``TARGET_LINKER_FILE`` + * ``TARGET_SONAME_FILE`` + * ``TARGET_PDB_FILE`` + + The command and arguments are optional and if not specified an empty + target will be created. + +``COMMENT`` + Display the given message before the commands are executed at + build time. + +``DEPENDS`` + Reference files and outputs of custom commands created with + :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. + + .. versionchanged:: 3.16 + 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. + +``COMMAND_EXPAND_LISTS`` + .. versionadded:: 3.8 + + Lists in ``COMMAND`` arguments will be expanded, including those + created with + :manual:`generator expressions <cmake-generator-expressions(7)>`, + allowing ``COMMAND`` arguments such as + ``${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTORIES>,;-I>" foo.cc`` + to be properly expanded. + +``JOB_POOL`` + .. versionadded:: 3.15 + + 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 + convenience in editing even if they have no build rules. + +``VERBATIM`` + All arguments to the commands will be escaped properly for the + build tool so that the invoked command receives each argument + unchanged. Note that one level of escapes is still used by the + CMake language processor before ``add_custom_target`` even sees + the arguments. Use of ``VERBATIM`` is recommended as it enables + correct behavior. When ``VERBATIM`` is not given the behavior + is platform specific because there is no protection of + tool-specific special characters. + +``USES_TERMINAL`` + .. versionadded:: 3.2 + + The command will be given direct access to the terminal if possible. + With the :generator:`Ninja` generator, this places the command in + the ``console`` :prop_gbl:`pool <JOB_POOLS>`. + +``WORKING_DIRECTORY`` + 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. + + .. versionadded:: 3.13 + Arguments to ``WORKING_DIRECTORY`` may use + :manual:`generator expressions <cmake-generator-expressions(7)>`. + +Ninja Multi-Config +^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 3.20 + + ``add_custom_target`` supports the :generator:`Ninja Multi-Config` + generator's cross-config capabilities. See the generator documentation + for more information. diff --git a/Help/command/add_definitions.rst b/Help/command/add_definitions.rst new file mode 100644 index 0000000..fe69188 --- /dev/null +++ b/Help/command/add_definitions.rst @@ -0,0 +1,35 @@ +add_definitions +--------------- + +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, whether added before or after this command is invoked, and for +the ones in sub-directories added after. This command can be used to add any +flags, but it is intended to add 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 +backwards compatibility. See documentation of the +:prop_dir:`directory <COMPILE_DEFINITIONS>`, +:prop_tgt:`target <COMPILE_DEFINITIONS>`, +:prop_sf:`source file <COMPILE_DEFINITIONS>` ``COMPILE_DEFINITIONS`` +properties for details on adding preprocessor definitions to specific +scopes and configurations. + +See the :manual:`cmake-buildsystem(7)` manual for more on defining +buildsystem properties. diff --git a/Help/command/add_dependencies.rst b/Help/command/add_dependencies.rst new file mode 100644 index 0000000..14c0183 --- /dev/null +++ b/Help/command/add_dependencies.rst @@ -0,0 +1,26 @@ +add_dependencies +---------------- + +Add a dependency between top-level targets. + +.. code-block:: cmake + + add_dependencies(<target> [<target-dependency>]...) + +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 +(but not targets generated by CMake like ``install``). + +Dependencies added to an :ref:`imported target <Imported Targets>` +or an :ref:`interface library <Interface Libraries>` are followed +transitively in its place since the target itself does not build. + +.. versionadded:: 3.3 + Allow adding dependencies to interface libraries. + +See the ``DEPENDS`` option of :command:`add_custom_target` and +:command:`add_custom_command` commands for adding file-level +dependencies in custom rules. See the :prop_sf:`OBJECT_DEPENDS` +source file property to add file-level dependencies to object files. diff --git a/Help/command/add_executable.rst b/Help/command/add_executable.rst new file mode 100644 index 0000000..dde9429 --- /dev/null +++ b/Help/command/add_executable.rst @@ -0,0 +1,109 @@ +add_executable +-------------- + +.. only:: html + + .. contents:: + +Add an executable to the project using the specified source files. + +Normal Executables +^^^^^^^^^^^^^^^^^^ + +.. code-block:: cmake + + add_executable(<name> [WIN32] [MACOSX_BUNDLE] + [EXCLUDE_FROM_ALL] + [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>``). + +.. versionadded:: 3.1 + Source arguments to ``add_executable`` may use "generator expressions" with + the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` + manual for available expressions. + +.. versionadded:: 3.11 + The source files can be omitted if they are added later using + :command:`target_sources`. + +By default the executable file will be created in the build tree +directory corresponding to the source tree directory in which the +command was invoked. See documentation of the +:prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` target property to change this +location. See documentation of the :prop_tgt:`OUTPUT_NAME` target property +to change the ``<name>`` part of the final file name. + +If ``WIN32`` is given the property :prop_tgt:`WIN32_EXECUTABLE` will be +set on the target created. See documentation of that target property for +details. + +If ``MACOSX_BUNDLE`` is given the corresponding property will be set on +the created target. See documentation of the :prop_tgt:`MACOSX_BUNDLE` +target property for details. + +If ``EXCLUDE_FROM_ALL`` is given the corresponding property will be set on +the created target. See documentation of the :prop_tgt:`EXCLUDE_FROM_ALL` +target property for details. + +See the :manual:`cmake-buildsystem(7)` manual for more on defining +buildsystem properties. + +See also :prop_sf:`HEADER_FILE_ONLY` on what to do if some sources are +pre-processed, and you want to have the original sources reachable from +within IDE. + +Imported Executables +^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: cmake + + add_executable(<name> IMPORTED [GLOBAL]) + +An :ref:`IMPORTED executable target <Imported Targets>` references an +executable file located outside the project. No rules are generated to +build it, and the :prop_tgt:`IMPORTED` target property is ``True``. The +target name has scope in the directory in which it is created and below, but +the ``GLOBAL`` option extends visibility. It may be referenced like any +target built within the project. ``IMPORTED`` executables are useful +for convenient reference from commands like :command:`add_custom_command`. +Details about the imported executable are specified by setting properties +whose names begin in ``IMPORTED_``. The most important such property is +:prop_tgt:`IMPORTED_LOCATION` (and its per-configuration version +:prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) which specifies the location of +the main executable file on disk. See documentation of the ``IMPORTED_*`` +properties for more information. + +Alias Executables +^^^^^^^^^^^^^^^^^ + +.. 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 ``ALIAS``. + +.. versionadded:: 3.11 + An ``ALIAS`` can target a ``GLOBAL`` :ref:`Imported Target <Imported Targets>` + +.. versionadded:: 3.18 + An ``ALIAS`` can target a non-``GLOBAL`` Imported Target. Such alias is + scoped to the directory in which it is created and subdirectories. + The :prop_tgt:`ALIAS_GLOBAL` target property can be used to check if the + alias is global or not. + +``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 +is, it may not be used as the operand of :command:`set_property`, +:command:`set_target_properties`, :command:`target_link_libraries` etc. +An ``ALIAS`` target may not be installed or exported. diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst new file mode 100644 index 0000000..dfc6500 --- /dev/null +++ b/Help/command/add_library.rst @@ -0,0 +1,259 @@ +add_library +----------- + +.. only:: html + + .. contents:: + +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] + [<source>...]) + +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 +``<name>.lib``). + +.. versionadded:: 3.1 + Source arguments to ``add_library`` may use "generator expressions" with + the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` + manual for available expressions. + +.. versionadded:: 3.11 + The source files can be omitted if they are added later using + :command:`target_sources`. + +``STATIC``, ``SHARED``, or ``MODULE`` may be given to specify the type of +library to be created. ``STATIC`` libraries are archives of object files +for use when linking other targets. ``SHARED`` libraries are linked +dynamically and loaded at runtime. ``MODULE`` libraries are plugins that +are not linked into other targets but may be loaded dynamically at runtime +using dlopen-like functionality. If no type is given explicitly the +type is ``STATIC`` or ``SHARED`` based on whether the current value of the +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`` library may be marked with the :prop_tgt:`FRAMEWORK` +target property to create an macOS Framework. + +.. versionadded:: 3.8 + A ``STATIC`` library may be marked with the :prop_tgt:`FRAMEWORK` + target property to create a static 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 +DLL that exports no unmanaged symbols would need to be a ``MODULE`` library. +This is because CMake expects a ``SHARED`` library to always have an +associated import library on Windows. + +By default the library file will be created in the build tree directory +corresponding to the source tree directory in which the command was +invoked. See documentation of the :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY`, +:prop_tgt:`LIBRARY_OUTPUT_DIRECTORY`, and +:prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` target properties to change this +location. See documentation of the :prop_tgt:`OUTPUT_NAME` target +property to change the ``<name>`` part of the final file name. + +If ``EXCLUDE_FROM_ALL`` is given the corresponding property will be set on +the created target. See documentation of the :prop_tgt:`EXCLUDE_FROM_ALL` +target property for details. + +See the :manual:`cmake-buildsystem(7)` manual for more on defining +buildsystem properties. + +See also :prop_sf:`HEADER_FILE_ONLY` on what to do if some sources are +pre-processed, and you want to have the original sources reachable from +within IDE. + +Object Libraries +^^^^^^^^^^^^^^^^ + +.. code-block:: cmake + + add_library(<name> OBJECT [<source>...]) + +Creates an :ref:`Object Library <Object Libraries>`. An object library +compiles source files but does not archive or link their object files into a +library. Instead other targets created by :command:`add_library` or +:command:`add_executable` may reference the objects using an expression of the +form ``$<TARGET_OBJECTS:objlib>`` as a source, where ``objlib`` is the +object library name. For example: + +.. code-block:: cmake + + add_library(... $<TARGET_OBJECTS:objlib> ...) + add_executable(... $<TARGET_OBJECTS:objlib> ...) + +will include objlib's object files in a library and an executable +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. 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>``. + +.. versionadded:: 3.12 + Object libraries can be linked to with :command:`target_link_libraries`. + +Interface Libraries +^^^^^^^^^^^^^^^^^^^ + +.. code-block:: cmake + + add_library(<name> INTERFACE) + +Creates an :ref:`Interface Library <Interface Libraries>`. +An ``INTERFACE`` library target does not compile sources and does +not produce a library artifact on disk. However, it may have +properties set on it and it may be installed and exported. +Typically, ``INTERFACE_*`` properties are populated on an 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 +* :command:`target_sources(INTERFACE)`, + +and then it is used as an argument to :command:`target_link_libraries` +like any other target. + +An interface library created with the above signature has no source files +itself and is not included as a target in the generated buildsystem. + +.. versionadded:: 3.15 + An interface library can have :prop_tgt:`PUBLIC_HEADER` and + :prop_tgt:`PRIVATE_HEADER` properties. The headers specified by those + properties can be installed using the :command:`install(TARGETS)` command. + +.. versionadded:: 3.19 + An interface library target may be created with source files: + + .. code-block:: cmake + + add_library(<name> INTERFACE [<source>...] [EXCLUDE_FROM_ALL]) + + Source files may be listed directly in the ``add_library`` call or added + later by calls to :command:`target_sources` with the ``PRIVATE`` or + ``PUBLIC`` keywords. + + If an interface library has source files (i.e. the :prop_tgt:`SOURCES` + target property is set), it will appear in the generated buildsystem + as a build target much like a target defined by the + :command:`add_custom_target` command. It does not compile any sources, + but does contain build rules for custom commands created by the + :command:`add_custom_command` command. + +.. note:: + In most command signatures where the ``INTERFACE`` keyword appears, + the items listed after it only become part of that target's usage + requirements and are not part of the target's own settings. However, + in this signature of ``add_library``, the ``INTERFACE`` keyword refers + to the library type only. Sources listed after it in the ``add_library`` + call are ``PRIVATE`` to the interface library and do not appear in its + :prop_tgt:`INTERFACE_SOURCES` target property. + +Imported Libraries +^^^^^^^^^^^^^^^^^^ + +.. code-block:: cmake + + add_library(<name> <type> IMPORTED [GLOBAL]) + +Creates an :ref:`IMPORTED library target <Imported Targets>` called ``<name>``. +No rules are generated to build it, and the :prop_tgt:`IMPORTED` target +property is ``True``. The target name has scope in the directory in which +it is created and below, but the ``GLOBAL`` 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 ``<type>`` must be one of: + +``STATIC``, ``SHARED``, ``MODULE``, ``UNKNOWN`` + References a library file located outside the project. The + :prop_tgt:`IMPORTED_LOCATION` target property (or its per-configuration + variant :prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) specifies the + location of the main library file on disk: + + * For a ``SHARED`` library on most non-Windows platforms, the main library + file is the ``.so`` or ``.dylib`` file used by both linkers and dynamic + loaders. If the referenced library file has a ``SONAME`` (or on macOS, + has a ``LC_ID_DYLIB`` starting in ``@rpath/``), the value of that field + should be set in the :prop_tgt:`IMPORTED_SONAME` target property. + If the referenced library file does not have a ``SONAME``, but the + platform supports it, then the :prop_tgt:`IMPORTED_NO_SONAME` target + property should be set. + + * For a ``SHARED`` library on Windows, the :prop_tgt:`IMPORTED_IMPLIB` + target property (or its per-configuration variant + :prop_tgt:`IMPORTED_IMPLIB_<CONFIG>`) specifies the location of the + DLL import library file (``.lib`` or ``.dll.a``) on disk, and the + ``IMPORTED_LOCATION`` is the location of the ``.dll`` runtime + library (and is optional). + + Additional usage requirements may be specified in ``INTERFACE_*`` properties. + + 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`` + References a set of object files located outside the project. + The :prop_tgt:`IMPORTED_OBJECTS` target property (or its per-configuration + variant :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>`) specifies the locations of + object files on disk. + Additional usage requirements may be specified in ``INTERFACE_*`` properties. + +``INTERFACE`` + Does not reference any library or object files on disk, but may + specify usage requirements in ``INTERFACE_*`` properties. + +See documentation of the ``IMPORTED_*`` and ``INTERFACE_*`` properties +for more information. + +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 ``ALIAS``. + +.. versionadded:: 3.11 + An ``ALIAS`` can target a ``GLOBAL`` :ref:`Imported Target <Imported Targets>` + +.. versionadded:: 3.18 + An ``ALIAS`` can target a non-``GLOBAL`` Imported Target. Such alias is + scoped to the directory in which it is created and below. + The :prop_tgt:`ALIAS_GLOBAL` target property can be used to check if the + alias is global or not. + +``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 +to modify properties of ``<target>``, that is, it may not be used as the +operand of :command:`set_property`, :command:`set_target_properties`, +:command:`target_link_libraries` etc. An ``ALIAS`` target may not be +installed or exported. diff --git a/Help/command/add_link_options.rst b/Help/command/add_link_options.rst new file mode 100644 index 0000000..f03e7c0 --- /dev/null +++ b/Help/command/add_link_options.rst @@ -0,0 +1,35 @@ +add_link_options +---------------- + +.. versionadded:: 3.13 + +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:: DEVICE_LINK_OPTIONS.txt + +.. include:: OPTIONS_SHELL.txt + +.. include:: LINK_OPTIONS_LINKER.txt diff --git a/Help/command/add_subdirectory.rst b/Help/command/add_subdirectory.rst new file mode 100644 index 0000000..8dba986 --- /dev/null +++ b/Help/command/add_subdirectory.rst @@ -0,0 +1,35 @@ +add_subdirectory +---------------- + +Add a subdirectory to the build. + +.. code-block:: cmake + + add_subdirectory(source_dir [binary_dir] [EXCLUDE_FROM_ALL]) + +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 +absolute path. The ``binary_dir`` specifies the directory in which to +place the output files. If it is a relative path it will be evaluated +with respect to the current output directory, but it may also be an +absolute path. If ``binary_dir`` is not specified, the value of +``source_dir``, before expanding any relative path, will be used (the +typical usage). The CMakeLists.txt file in the specified source +directory will be processed immediately by CMake before processing in +the current input file continues beyond this command. + +If the ``EXCLUDE_FROM_ALL`` argument is provided then targets in the +subdirectory will not be included in the ``ALL`` target of the parent +directory by default, and will be excluded from IDE project files. +Users must explicitly build targets in the subdirectory. This is +meant for use when the subdirectory contains a separate part of the +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 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 new file mode 100644 index 0000000..95cd037 --- /dev/null +++ b/Help/command/add_test.rst @@ -0,0 +1,82 @@ +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>] + [COMMAND_EXPAND_LISTS]) + +Adds a test called ``<name>``. The test name may contain arbitrary +characters, expressed as a :ref:`Quoted Argument` or :ref:`Bracket Argument` +if necessary. See policy :policy:`CMP0110`. The options are: + +``COMMAND`` + Specify the test command-line. If ``<command>`` specifies an + executable target (created by :command:`add_executable`) it will + automatically be replaced by the location of the executable created + at build time. + +``CONFIGURATIONS`` + Restrict execution of the test only to the named configurations. + +``WORKING_DIRECTORY`` + Set the :prop_test:`WORKING_DIRECTORY` test property to + specify the working directory in which to execute the test. + If not specified the test will be run with the current working + directory set to the build directory corresponding to the + current source directory. + +``COMMAND_EXPAND_LISTS`` + .. versionadded:: 3.16 + + 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`, +:prop_test:`FAIL_REGULAR_EXPRESSION` or +:prop_test:`SKIP_REGULAR_EXPRESSION` test property is used. + +.. versionadded:: 3.16 + Added :prop_test:`SKIP_REGULAR_EXPRESSION` property. + +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: + +.. code-block:: cmake + + add_test(NAME mytest + COMMAND testDriver --config $<CONFIG> + --exe $<TARGET_FILE:myexe>) + +This creates a test ``mytest`` whose command runs a ``testDriver`` tool +passing the configuration name and the full path to the executable +file produced by target ``myexe``. + +.. note:: + + CMake will generate tests only if the :command:`enable_testing` + command has been invoked. The :module:`CTest` module invokes the + command automatically unless the ``BUILD_TESTING`` option is turned + ``OFF``. + +--------------------------------------------------------------------- + +.. code-block:: cmake + + add_test(<name> <command> [<arg>...]) + +Add a test called ``<name>`` with the given command-line. Unlike +the above ``NAME`` signature no transformation is performed on the +command-line to support target names or generator expressions. diff --git a/Help/command/aux_source_directory.rst b/Help/command/aux_source_directory.rst new file mode 100644 index 0000000..9619f35 --- /dev/null +++ b/Help/command/aux_source_directory.rst @@ -0,0 +1,24 @@ +aux_source_directory +-------------------- + +Find all source files in a directory. + +.. code-block:: cmake + + aux_source_directory(<dir> <variable>) + +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 +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 +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 new file mode 100644 index 0000000..4875a2b --- /dev/null +++ b/Help/command/break.rst @@ -0,0 +1,12 @@ +break +----- + +Break from an enclosing foreach or while loop. + +.. code-block:: cmake + + break() + +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 new file mode 100644 index 0000000..6659005 --- /dev/null +++ b/Help/command/build_command.rst @@ -0,0 +1,45 @@ +build_command +------------- + +Get a command line to build the current project. +This is mainly intended for internal use by the :module:`CTest` module. + +.. code-block:: cmake + + build_command(<variable> + [CONFIGURATION <config>] + [TARGET <target>] + [PROJECT_NAME <projname>] # legacy, causes warning + ) + +Sets the given ``<variable>`` to a command-line string of the form:: + + <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 +``CONFIGURATION`` and ``TARGET`` options, if any. The trailing ``-- -i`` +option is added for :ref:`Makefile Generators` if policy :policy:`CMP0061` +is not set to ``NEW``. + +When invoked, this ``cmake --build`` command line will launch the +underlying build system tool. + +.. code-block:: cmake + + build_command(<cachevariable> <makecommand>) + +This second signature is deprecated, but still available for backwards +compatibility. Use the first signature instead. + +It sets the given ``<cachevariable>`` to a command-line string as +above but without the ``--target`` option. +The ``<makecommand>`` is ignored but should be the full path to +devenv, nmake, make or one of the end user build tools +for legacy invocations. + +.. note:: + In CMake versions prior to 3.0 this command returned a command + line that directly invokes the native build tool for the current + generator. Their implementation of the ``PROJECT_NAME`` option + had no useful effects, so CMake now warns on use of the option. diff --git a/Help/command/build_name.rst b/Help/command/build_name.rst new file mode 100644 index 0000000..2a1fbae --- /dev/null +++ b/Help/command/build_name.rst @@ -0,0 +1,15 @@ +build_name +---------- + +Disallowed since version 3.0. See CMake Policy :policy:`CMP0036`. + +Use ``${CMAKE_SYSTEM}`` and ``${CMAKE_CXX_COMPILER}`` instead. + +:: + + build_name(variable) + +Sets the specified variable to a string representing the platform and +compiler settings. These values are now available through the +:variable:`CMAKE_SYSTEM` and +:variable:`CMAKE_CXX_COMPILER <CMAKE_<LANG>_COMPILER>` variables. diff --git a/Help/command/cmake_host_system_information.rst b/Help/command/cmake_host_system_information.rst new file mode 100644 index 0000000..2b902a9 --- /dev/null +++ b/Help/command/cmake_host_system_information.rst @@ -0,0 +1,58 @@ +cmake_host_system_information +----------------------------- + +Query host system specific information. + +.. code-block:: cmake + + cmake_host_system_information(RESULT <variable> QUERY <key> ...) + +Queries system information of the host system on which cmake runs. +One or more ``<key>`` can be provided to select the information to be +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]_ +============================= ================================================ + +.. versionadded:: 3.10 + Additional ``<key>`` values are available: + +============================= ================================================ +Key Description +============================= ================================================ +``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` +============================= ================================================ + +.. rubric:: Footnotes + +.. [#mebibytes] One MiB (mebibyte) is equal to 1024x1024 bytes. diff --git a/Help/command/cmake_language.rst b/Help/command/cmake_language.rst new file mode 100644 index 0000000..99f874b --- /dev/null +++ b/Help/command/cmake_language.rst @@ -0,0 +1,227 @@ +cmake_language +-------------- + +.. versionadded:: 3.18 + +Call meta-operations on CMake commands. + +Synopsis +^^^^^^^^ + +.. parsed-literal:: + + cmake_language(`CALL`_ <command> [<arg>...]) + cmake_language(`EVAL`_ CODE <code>...) + cmake_language(`DEFER`_ <options>... CALL <command> [<arg>...]) + +Introduction +^^^^^^^^^^^^ + +This command will call meta-operations on built-in CMake commands or +those created via the :command:`macro` or :command:`function` commands. + +``cmake_language`` does not introduce a new variable or policy scope. + +Calling Commands +^^^^^^^^^^^^^^^^ + +.. _CALL: + +.. code-block:: cmake + + cmake_language(CALL <command> [<arg>...]) + +Calls the named ``<command>`` with the given arguments (if any). +For example, the code: + +.. code-block:: cmake + + set(message_command "message") + cmake_language(CALL ${message_command} STATUS "Hello World!") + +is equivalent to + +.. code-block:: cmake + + message(STATUS "Hello World!") + +.. note:: + To ensure consistency of the code, the following commands are not allowed: + + * ``if`` / ``elseif`` / ``else`` / ``endif`` + * ``while`` / ``endwhile`` + * ``foreach`` / ``endforeach`` + * ``function`` / ``endfunction`` + * ``macro`` / ``endmacro`` + +Evaluating Code +^^^^^^^^^^^^^^^ + +.. _EVAL: + +.. code-block:: cmake + + cmake_language(EVAL CODE <code>...) + +Evaluates the ``<code>...`` as CMake code. + +For example, the code: + +.. code-block:: cmake + + set(A TRUE) + set(B TRUE) + set(C TRUE) + set(condition "(A AND B) OR C") + + cmake_language(EVAL CODE " + if (${condition}) + message(STATUS TRUE) + else() + message(STATUS FALSE) + endif()" + ) + +is equivalent to + +.. code-block:: cmake + + set(A TRUE) + set(B TRUE) + set(C TRUE) + set(condition "(A AND B) OR C") + + file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/eval.cmake " + if (${condition}) + message(STATUS TRUE) + else() + message(STATUS FALSE) + endif()" + ) + + include(${CMAKE_CURRENT_BINARY_DIR}/eval.cmake) + +Deferring Calls +^^^^^^^^^^^^^^^ + +.. versionadded:: 3.19 + +.. _DEFER: + +.. code-block:: cmake + + cmake_language(DEFER <options>... CALL <command> [<arg>...]) + +Schedules a call to the named ``<command>`` with the given arguments (if any) +to occur at a later time. By default, deferred calls are executed as if +written at the end of the current directory's ``CMakeLists.txt`` file, +except that they run even after a :command:`return` call. Variable +references in arguments are evaluated at the time the deferred call is +executed. + +The options are: + +``DIRECTORY <dir>`` + Schedule the call for the end of the given directory instead of the + current directory. The ``<dir>`` may reference either a source + directory or its corresponding binary directory. Relative paths are + treated as relative to the current source directory. + + The given directory must be known to CMake, being either the top-level + directory or one added by :command:`add_subdirectory`. Furthermore, + the given directory must not yet be finished processing. This means + it can be the current directory or one of its ancestors. + +``ID <id>`` + Specify an identification for the deferred call. + The ``<id>`` may not be empty and may not begin with a capital letter ``A-Z``. + The ``<id>`` may begin with an underscore (``_``) only if it was generated + automatically by an earlier call that used ``ID_VAR`` to get the id. + +``ID_VAR <var>`` + Specify a variable in which to store the identification for the + deferred call. If ``ID <id>`` is not given, a new identification + will be generated and the generated id will start with an underscore (``_``). + +The currently scheduled list of deferred calls may be retrieved: + +.. code-block:: cmake + + cmake_language(DEFER [DIRECTORY <dir>] GET_CALL_IDS <var>) + +This will store in ``<var>`` a :ref:`semicolon-separated list <CMake Language +Lists>` of deferred call ids. The ids are for the directory scope in which +the calls have been deferred to (i.e. where they will be executed), which can +be different to the scope in which they were created. The ``DIRECTORY`` +option can be used to specify the scope for which to retrieve the call ids. +If that option is not given, the call ids for the current directory scope will +be returned. + +Details of a specific call may be retrieved from its id: + +.. code-block:: cmake + + cmake_language(DEFER [DIRECTORY <dir>] GET_CALL <id> <var>) + +This will store in ``<var>`` a :ref:`semicolon-separated list <CMake Language +Lists>` in which the first element is the name of the command to be +called, and the remaining elements are its unevaluated arguments (any +contained ``;`` characters are included literally and cannot be distinguished +from multiple arguments). If multiple calls are scheduled with the same id, +this retrieves the first one. If no call is scheduled with the given id in +the specified ``DIRECTORY`` scope (or the current directory scope if no +``DIRECTORY`` option is given), this stores an empty string in the variable. + +Deferred calls may be canceled by their id: + +.. code-block:: cmake + + cmake_language(DEFER [DIRECTORY <dir>] CANCEL_CALL <id>...) + +This cancels all deferred calls matching any of the given ids in the specified +``DIRECTORY`` scope (or the current directory scope if no ``DIRECTORY`` option +is given). Unknown ids are silently ignored. + +Deferred Call Examples +"""""""""""""""""""""" + +For example, the code: + +.. code-block:: cmake + + cmake_language(DEFER CALL message "${deferred_message}") + cmake_language(DEFER ID_VAR id CALL message "Cancelled Message") + cmake_language(DEFER CANCEL_CALL ${id}) + message("Immediate Message") + set(deferred_message "Deferred Message") + +prints:: + + Immediate Message + Deferred Message + +The ``Cancelled Message`` is never printed because its command is +cancelled. The ``deferred_message`` variable reference is not evaluated +until the call site, so it can be set after the deferred call is scheduled. + +In order to evaluate variable references immediately when scheduling a +deferred call, wrap it using ``cmake_language(EVAL)``. However, note that +arguments will be re-evaluated in the deferred call, though that can be +avoided by using bracket arguments. For example: + +.. code-block:: cmake + + set(deferred_message "Deferred Message 1") + set(re_evaluated [[${deferred_message}]]) + cmake_language(EVAL CODE " + cmake_language(DEFER CALL message [[${deferred_message}]]) + cmake_language(DEFER CALL message \"${re_evaluated}\") + ") + message("Immediate Message") + set(deferred_message "Deferred Message 2") + +also prints:: + + Immediate Message + Deferred Message 1 + Deferred Message 2 diff --git a/Help/command/cmake_minimum_required.rst b/Help/command/cmake_minimum_required.rst new file mode 100644 index 0000000..2cc3cfe --- /dev/null +++ b/Help/command/cmake_minimum_required.rst @@ -0,0 +1,76 @@ +cmake_minimum_required +---------------------- + +Require a minimum version of cmake. + +.. code-block:: cmake + + cmake_minimum_required(VERSION <min>[...<policy_max>] [FATAL_ERROR]) + +.. versionadded:: 3.12 + The optional ``<policy_max>`` version. + +Sets the minimum required version of cmake for a project. +Also updates the policy settings as explained below. + +``<min>`` and the optional ``<policy_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 ``<policy_max>`` version, if specified, must be at least the +``<min>`` version and affects policy settings as described in `Policy Settings`_. +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 command will set the value of the +:variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable to ``<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 +with an error instead of just a warning. + +.. note:: + Call the ``cmake_minimum_required()`` command at the beginning of + the top-level ``CMakeLists.txt`` file even before calling the + :command:`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`. + + Calling ``cmake_minimum_required()`` inside a :command:`function` + limits some effects to the function scope when invoked. Such calls + should not be made with the intention of having global effects. + +.. _`Policy Settings`: + +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 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 ``<min>`` version higher than 2.4 is specified the command +implicitly invokes + +.. code-block:: cmake + + cmake_policy(VERSION <min>[...<max>]) + +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 + +.. code-block:: cmake + + 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 new file mode 100644 index 0000000..7c85da6 --- /dev/null +++ b/Help/command/cmake_parse_arguments.rst @@ -0,0 +1,115 @@ +cmake_parse_arguments +--------------------- + +Parse function or macro arguments. + +.. code-block:: cmake + + cmake_parse_arguments(<prefix> <options> <one_value_keywords> + <multi_value_keywords> <args>...) + + cmake_parse_arguments(PARSE_ARGV <N> <prefix> <options> + <one_value_keywords> <multi_value_keywords>) + +.. versionadded:: 3.5 + This command is implemented natively. Previously, it has been defined in the + module :module:`CMakeParseArguments`. + +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`. + +.. versionadded:: 3.7 + 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 ``<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, +i.e. keywords which can be used when calling the macro without any value +following, like e.g. the ``OPTIONAL`` keyword of the :command:`install` +command. + +The ``<one_value_keywords>`` argument contains all keywords for this macro +which are followed by one value, like e.g. ``DESTINATION`` keyword of the +:command:`install` command. + +The ``<multi_value_keywords>`` argument contains all keywords for this +macro which can be followed by more than one value, like e.g. the +``TARGETS`` or ``FILES`` keywords of the :command:`install` command. + +.. versionchanged:: 3.5 + All keywords shall be unique. I.e. every keyword shall only be specified + once in either ``<options>``, ``<one_value_keywords>`` or + ``<multi_value_keywords>``. A warning will be emitted if uniqueness is + violated. + +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 +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`` that will be undefined if all arguments +were recognized. This can be checked afterwards to see +whether your macro was called with unrecognized parameters. + +.. versionadded:: 3.15 + ``<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 + + macro(my_install) + set(options OPTIONAL FAST) + set(oneValueArgs DESTINATION RENAME) + set(multiValueArgs TARGETS CONFIGURATIONS) + cmake_parse_arguments(MY_INSTALL "${options}" "${oneValueArgs}" + "${multiValueArgs}" ${ARGN} ) + + # ... + +Assume ``my_install()`` has been called like this: + +.. code-block:: cmake + + my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub CONFIGURATIONS) + +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_DESTINATION = "bin" + MY_INSTALL_RENAME <UNDEFINED> # was not used + MY_INSTALL_TARGETS = "foo;bar" + 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 +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 (but added +to ``MY_INSTALL_KEYWORDS_MISSING_VALUES``) and ``MY_INSTALL_OPTIONAL`` will +therefore be set to ``TRUE``. diff --git a/Help/command/cmake_path.rst b/Help/command/cmake_path.rst new file mode 100644 index 0000000..a8999f3 --- /dev/null +++ b/Help/command/cmake_path.rst @@ -0,0 +1,784 @@ +cmake_path +---------- + +.. versionadded:: 3.20 + +This command is for the manipulation of paths. Only syntactic aspects of +paths are handled, there is no interaction of any kind with any underlying +file system. The path may represent a non-existing path or even one that +is not allowed to exist on the current file system or platform. +For operations that do interact with the filesystem, see the :command:`file` +command. + +.. note:: + + The ``cmake_path`` command handles paths in the format of the build system + (i.e. the host platform), not the target system. When cross-compiling, + if the path contains elements that are not representable on the host + platform (e.g. a drive letter when the host is not Windows), the results + will be unpredictable. + +Synopsis +^^^^^^^^ + +.. parsed-literal:: + + `Conventions`_ + + `Path Structure And Terminology`_ + + `Normalization`_ + + `Decomposition`_ + cmake_path(`GET`_ <path-var> :ref:`ROOT_NAME <GET_ROOT_NAME>` <out-var>) + cmake_path(`GET`_ <path-var> :ref:`ROOT_DIRECTORY <GET_ROOT_DIRECTORY>` <out-var>) + cmake_path(`GET`_ <path-var> :ref:`ROOT_PATH <GET_ROOT_PATH>` <out-var>) + cmake_path(`GET`_ <path-var> :ref:`FILENAME <GET_FILENAME>` <out-var>) + cmake_path(`GET`_ <path-var> :ref:`EXTENSION <GET_EXTENSION>` [LAST_ONLY] <out-var>) + cmake_path(`GET`_ <path-var> :ref:`STEM <GET_STEM>` [LAST_ONLY] <out-var>) + cmake_path(`GET`_ <path-var> :ref:`RELATIVE_PART <GET_RELATIVE_PART>` <out-var>) + cmake_path(`GET`_ <path-var> :ref:`PARENT_PATH <GET_PARENT_PATH>` <out-var>) + + `Query`_ + cmake_path(`HAS_ROOT_NAME`_ <path-var> <out-var>) + cmake_path(`HAS_ROOT_DIRECTORY`_ <path-var> <out-var>) + cmake_path(`HAS_ROOT_PATH`_ <path-var> <out-var>) + cmake_path(`HAS_FILENAME`_ <path-var> <out-var>) + cmake_path(`HAS_EXTENSION`_ <path-var> <out-var>) + cmake_path(`HAS_STEM`_ <path-var> <out-var>) + cmake_path(`HAS_RELATIVE_PART`_ <path-var> <out-var>) + cmake_path(`HAS_PARENT_PATH`_ <path-var> <out-var>) + cmake_path(`IS_ABSOLUTE`_ <path-var> <out-var>) + cmake_path(`IS_RELATIVE`_ <path-var> <out-var>) + cmake_path(`IS_PREFIX`_ <path-var> <input> [NORMALIZE] <out-var>) + cmake_path(`COMPARE`_ <input1> <OP> <input2> <out-var>) + + `Modification`_ + cmake_path(:ref:`SET <cmake_path-SET>` <path-var> [NORMALIZE] <input>) + cmake_path(`APPEND`_ <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>]) + cmake_path(`APPEND_STRING`_ <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>]) + cmake_path(`REMOVE_FILENAME`_ <path-var> [OUTPUT_VARIABLE <out-var>]) + cmake_path(`REPLACE_FILENAME`_ <path-var> <input> [OUTPUT_VARIABLE <out-var>]) + cmake_path(`REMOVE_EXTENSION`_ <path-var> [LAST_ONLY] [OUTPUT_VARIABLE <out-var>]) + cmake_path(`REPLACE_EXTENSION`_ <path-var> [LAST_ONLY] <input> [OUTPUT_VARIABLE <out-var>]) + + `Generation`_ + cmake_path(`NORMAL_PATH`_ <path-var> [OUTPUT_VARIABLE <out-var>]) + cmake_path(`RELATIVE_PATH`_ <path-var> [BASE_DIRECTORY <input>] [OUTPUT_VARIABLE <out-var>]) + cmake_path(`ABSOLUTE_PATH`_ <path-var> [BASE_DIRECTORY <input>] [NORMALIZE] [OUTPUT_VARIABLE <out-var>]) + + `Native Conversion`_ + cmake_path(`NATIVE_PATH`_ <path-var> [NORMALIZE] <out-var>) + cmake_path(`CONVERT`_ <input> `TO_CMAKE_PATH_LIST`_ <out-var>) + cmake_path(`CONVERT`_ <input> `TO_NATIVE_PATH_LIST`_ <out-var>) + + `Hashing`_ + cmake_path(`HASH`_ <path-var> <out-var>) + +Conventions +^^^^^^^^^^^ + +The following conventions are used in this command's documentation: + +``<path-var>`` + Always the name of a variable. For commands that expect a ``<path-var>`` + as input, the variable must exist and it is expected to hold a single path. + +``<input>`` + A string literal which may contain a path, path fragment, or multiple paths + with a special separator depending on the command. See the description of + each command to see how this is interpreted. + +``<input>...`` + Zero or more string literal arguments. + +``<out-var>`` + The name of a variable into which the result of a command will be written. + + +Path Structure And Terminology +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A path has the following structure (all components are optional, with some +constraints): + +:: + + root-name root-directory-separator (item-name directory-separator)* filename + +``root-name`` + Identifies the root on a filesystem with multiple roots (such as ``"C:"`` + or ``"//myserver"``). It is optional. + +``root-directory-separator`` + A directory separator that, if present, indicates that this path is + absolute. If it is missing and the first element other than the + ``root-name`` is an ``item-name``, then the path is relative. + +``item-name`` + A sequence of characters that aren't directory separators. This name may + identify a file, a hard link, a symbolic link, or a directory. Two special + cases are recognized: + + * The item name consisting of a single dot character ``.`` is a + directory name that refers to the current directory. + + * The item name consisting of two dot characters ``..`` is a + directory name that refers to the parent directory. + + The ``(...)*`` pattern shown above is to indicate that there can be zero + or more item names, with multiple items separated by a + ``directory-separator``. The ``()*`` characters are not part of the path. + +``directory-separator`` + The only recognized directory separator is a forward slash character ``/``. + If this character is repeated, it is treated as a single directory + separator. In other words, ``/usr///////lib`` is the same as ``/usr/lib``. + +.. _FILENAME_DEF: +.. _EXTENSION_DEF: +.. _STEM_DEF: + +``filename`` + A path has a ``filename`` if it does not end with a ``directory-separator``. + The ``filename`` is effectively the last ``item-name`` of the path, so it + can also be a hard link, symbolic link or a directory. + + A ``filename`` can have an *extension*. By default, the extension is + defined as the sub-string beginning at the left-most period (including + the period) and until the end of the ``filename``. In commands that + accept a ``LAST_ONLY`` keyword, ``LAST_ONLY`` changes the interpretation + to the sub-string beginning at the right-most period. + + The following exceptions apply to the above interpretation: + + * If the first character in the ``filename`` is a period, that period is + ignored (i.e. a ``filename`` like ``".profile"`` is treated as having + no extension). + + * If the ``filename`` is either ``.`` or ``..``, it has no extension. + + The *stem* is the part of the ``filename`` before the extension. + +Some commands refer to a ``root-path``. This is the concatenation of +``root-name`` and ``root-directory-separator``, either or both of which can +be empty. A ``relative-part`` refers to the full path with any ``root-path`` +removed. + + +Creating A Path Variable +^^^^^^^^^^^^^^^^^^^^^^^^ + +While a path can be created with care using an ordinary :command:`set` +command, it is recommended to use :ref:`cmake_path(SET) <cmake_path-SET>` +instead, as it automatically converts the path to the required form where +required. The :ref:`cmake_path(APPEND) <APPEND>` subcommand may +be another suitable alternative where a path needs to be constructed by +joining fragments. The following example compares the three methods for +constructing the same path: + +.. code-block:: cmake + + set(path1 "${CMAKE_CURRENT_SOURCE_DIR}/data") + + cmake_path(SET path2 "${CMAKE_CURRENT_SOURCE_DIR}/data") + + cmake_path(APPEND path3 "${CMAKE_CURRENT_SOURCE_DIR}" "data") + +`Modification`_ and `Generation`_ sub-commands can either store the result +in-place, or in a separate variable named after an ``OUTPUT_VARIABLE`` +keyword. All other sub-commands store the result in a mandatory ``<out-var>`` +variable. + +.. _Normalization: + +Normalization +^^^^^^^^^^^^^ + +Some sub-commands support *normalizing* a path. The algorithm used to +normalize a path is as follows: + +1. If the path is empty, stop (the normalized form of an empty path is + also an empty path). +2. Replace each ``directory-separator``, which may consist of multiple + separators, with a single ``/`` (``/a///b --> /a/b``). +3. Remove each solitary period (``.``) and any immediately following + ``directory-separator`` (``/a/./b/. --> /a/b``). +4. Remove each ``item-name`` (other than ``..``) that is immediately + followed by a ``directory-separator`` and a ``..``, along with any + immediately following ``directory-separator`` (``/a/b/../c --> a/c``). +5. If there is a ``root-directory``, remove any ``..`` and any + ``directory-separators`` immediately following them. The parent of the + root directory is treated as still the root directory (``/../a --> /a``). +6. If the last ``item-name`` is ``..``, remove any trailing + ``directory-separator`` (``../ --> ..``). +7. If the path is empty by this stage, add a ``dot`` (normal form of ``./`` + is ``.``). + + +Decomposition +^^^^^^^^^^^^^ + +.. _GET: +.. _GET_ROOT_NAME: +.. _GET_ROOT_DIRECTORY: +.. _GET_ROOT_PATH: +.. _GET_FILENAME: +.. _GET_EXTENSION: +.. _GET_STEM: +.. _GET_RELATIVE_PART: +.. _GET_PARENT_PATH: + +The following forms of the ``GET`` subcommand each retrieve a different +component or group of components from a path. See +`Path Structure And Terminology`_ for the meaning of each path component. + +:: + + cmake_path(GET <path-var> ROOT_NAME <out-var>) + cmake_path(GET <path-var> ROOT_DIRECTORY <out-var>) + cmake_path(GET <path-var> ROOT_PATH <out-var>) + cmake_path(GET <path-var> FILENAME <out-var>) + cmake_path(GET <path-var> EXTENSION [LAST_ONLY] <out-var>) + cmake_path(GET <path-var> STEM [LAST_ONLY] <out-var>) + cmake_path(GET <path-var> RELATIVE_PART <out-var>) + cmake_path(GET <path-var> PARENT_PATH <out-var>) + +If a requested component is not present in the path, an empty string will be +stored in ``<out-var>``. For example, only Windows systems have the concept +of a ``root-name``, so when the host machine is non-Windows, the ``ROOT_NAME`` +subcommand will always return an empty string. + +For ``PARENT_PATH``, if the `HAS_RELATIVE_PART`_ subcommand returns false, +the result is a copy of ``<path-var>``. Note that this implies that a root +directory is considered to have a parent, with that parent being itself. +Where `HAS_RELATIVE_PART`_ returns true, the result will essentially be +``<path-var>`` with one less element. + +Root examples +""""""""""""" + +.. code-block:: cmake + + set(path "c:/a") + + cmake_path(GET path ROOT_NAME rootName) + cmake_path(GET path ROOT_DIRECTORY rootDir) + cmake_path(GET path ROOT_PATH rootPath) + + message("Root name is \"${rootName}\"") + message("Root directory is \"${rootDir}\"") + message("Root path is \"${rootPath}\"") + +:: + + Root name is "c:" + Root directory is "/" + Root path is "c:/" + +Filename examples +""""""""""""""""" + +.. code-block:: cmake + + set(path "/a/b") + cmake_path(GET path FILENAME filename) + message("First filename is \"${filename}\"") + + # Trailing slash means filename is empty + set(path "/a/b/") + cmake_path(GET path FILENAME filename) + message("Second filename is \"${filename}\"") + +:: + + First filename is "b" + Second filename is "" + +Extension and stem examples +""""""""""""""""""""""""""" + +.. code-block:: cmake + + set(path "name.ext1.ext2") + + cmake_path(GET path EXTENSION fullExt) + cmake_path(GET path STEM fullStem) + message("Full extension is \"${fullExt}\"") + message("Full stem is \"${fullStem}\"") + + # Effect of LAST_ONLY + cmake_path(GET path EXTENSION LAST_ONLY lastExt) + cmake_path(GET path STEM LAST_ONLY lastStem) + message("Last extension is \"${lastExt}\"") + message("Last stem is \"${lastStem}\"") + + # Special cases + set(dotPath "/a/.") + set(dotDotPath "/a/..") + set(someMorePath "/a/.some.more") + cmake_path(GET dotPath EXTENSION dotExt) + cmake_path(GET dotPath STEM dotStem) + cmake_path(GET dotDotPath EXTENSION dotDotExt) + cmake_path(GET dotDotPath STEM dotDotStem) + cmake_path(GET dotMorePath EXTENSION someMoreExt) + cmake_path(GET dotMorePath STEM someMoreStem) + message("Dot extension is \"${dotExt}\"") + message("Dot stem is \"${dotStem}\"") + message("Dot-dot extension is \"${dotDotExt}\"") + message("Dot-dot stem is \"${dotDotStem}\"") + message(".some.more extension is \"${someMoreExt}\"") + message(".some.more stem is \"${someMoreStem}\"") + +:: + + Full extension is ".ext1.ext2" + Full stem is "name" + Last extension is ".ext2" + Last stem is "name.ext1" + Dot extension is "" + Dot stem is "." + Dot-dot extension is "" + Dot-dot stem is ".." + .some.more extension is ".more" + .some.more stem is ".some" + +Relative part examples +"""""""""""""""""""""" + +.. code-block:: cmake + + set(path "c:/a/b") + cmake_path(GET path RELATIVE_PART result) + message("Relative part is \"${result}\"") + + set(path "c/d") + cmake_path(GET path RELATIVE_PART result) + message("Relative part is \"${result}\"") + + set(path "/") + cmake_path(GET path RELATIVE_PART result) + message("Relative part is \"${result}\"") + +:: + + Relative part is "a/b" + Relative part is "c/d" + Relative part is "" + +Path traversal examples +""""""""""""""""""""""" + +.. code-block:: cmake + + set(path "c:/a/b") + cmake_path(GET path PARENT_PATH result) + message("Parent path is \"${result}\"") + + set(path "c:/") + cmake_path(GET path PARENT_PATH result) + message("Parent path is \"${result}\"") + +:: + + Parent path is "c:/a" + Parent path is "c:/" + + +Query +^^^^^ + +Each of the ``GET`` subcommands has a corresponding ``HAS_...`` +subcommand which can be used to discover whether a particular path +component is present. See `Path Structure And Terminology`_ for the +meaning of each path component. + +.. _HAS_ROOT_NAME: +.. _HAS_ROOT_DIRECTORY: +.. _HAS_ROOT_PATH: +.. _HAS_FILENAME: +.. _HAS_EXTENSION: +.. _HAS_STEM: +.. _HAS_RELATIVE_PART: +.. _HAS_PARENT_PATH: + +:: + + cmake_path(HAS_ROOT_NAME <path-var> <out-var>) + cmake_path(HAS_ROOT_DIRECTORY <path-var> <out-var>) + cmake_path(HAS_ROOT_PATH <path-var> <out-var>) + cmake_path(HAS_FILENAME <path-var> <out-var>) + cmake_path(HAS_EXTENSION <path-var> <out-var>) + cmake_path(HAS_STEM <path-var> <out-var>) + cmake_path(HAS_RELATIVE_PART <path-var> <out-var>) + cmake_path(HAS_PARENT_PATH <path-var> <out-var>) + +Each of the above follows the predictable pattern of setting ``<out-var>`` +to true if the path has the associated component, or false otherwise. +Note the following special cases: + +* For ``HAS_ROOT_PATH``, a true result will only be returned if at least one + of ``root-name`` or ``root-directory`` is non-empty. + +* For ``HAS_PARENT_PATH``, the root directory is also considered to have a + parent, which will be itself. The result is true except if the path + consists of just a :ref:`filename <FILENAME_DEF>`. + +.. _IS_ABSOLUTE: + +:: + + cmake_path(IS_ABSOLUTE <path-var> <out-var>) + +Sets ``<out-var>`` to true if ``<path-var>`` is absolute. An absolute path +is a path that unambiguously identifies the location of a file without +reference to an additional starting location. On Windows, this means the +path must have both a ``root-name`` and a ``root-directory-separator`` to be +considered absolute. On other platforms, just a ``root-directory-separator`` +is sufficient. Note that this means on Windows, ``IS_ABSOLUTE`` can be +false while ``HAS_ROOT_DIRECTORY`` can be true. + +.. _IS_RELATIVE: + +:: + + cmake_path(IS_RELATIVE <path-var> <out-var>) + +This will store the opposite of ``IS_ABSOLUTE`` in ``<out-var>``. + +.. _IS_PREFIX: + +:: + + cmake_path(IS_PREFIX <path-var> <input> [NORMALIZE] <out-var>) + +Checks if ``<path-var>`` is the prefix of ``<input>``. + +When the ``NORMALIZE`` option is specified, ``<path-var>`` and ``<input>`` +are :ref:`normalized <Normalization>` before the check. + +.. code-block:: cmake + + set(path "/a/b/c/d") + cmake_path(IS_PREFIX path "/a/b" result) # result = true + cmake_path(IS_PREFIX path "/x/y/z" result) # result = false + + set(path "/a/b") + cmake_path(IS_PREFIX path "/a/c/../b" NORMALIZE result) # result = true + +.. _COMPARE: + +:: + + cmake_path(COMPARE <input1> EQUAL <input2> <out-var>) + cmake_path(COMPARE <input1> NOT_EQUAL <input2> <out-var>) + +Compares the lexical representations of two paths provided as string literals. +No normalization is performed on either path. Equality is determined +according to the following pseudo-code logic: + +:: + + if(NOT <input1>.root_name() STREQUAL <input2>.root_name()) + return FALSE + + if(<input1>.has_root_directory() XOR <input2>.has_root_directory()) + return FALSE + + Return FALSE if a relative portion of <input1> is not lexicographically + equal to the relative portion of <input2>. This comparison is performed path + component-wise. If all of the components compare equal, then return TRUE. + +.. note:: + Unlike most other ``cmake_path()`` subcommands, the ``COMPARE`` subcommand + takes literal strings as input, not the names of variables. + + +Modification +^^^^^^^^^^^^ + +.. _cmake_path-SET: + +:: + + cmake_path(SET <path-var> [NORMALIZE] <input>) + +Assign the ``<input>`` path to ``<path-var>``. If ``<input>`` is a native +path, it is converted into a cmake-style path with forward-slashes +(``/``). On Windows, the long filename marker is taken into account. + +When the ``NORMALIZE`` option is specified, the path is :ref:`normalized +<Normalization>` before the conversion. + +For example: + +.. code-block:: cmake + + set(native_path "c:\\a\\b/..\\c") + cmake_path(SET path "${native_path}") + message("CMake path is \"${path}\"") + + cmake_path(SET path NORMALIZE "${native_path}") + message("Normalized CMake path is \"${path}\"") + +Output:: + + CMake path is "c:/a/b/../c" + Normalized CMake path is "c:/a/c" + +.. _APPEND: + +:: + + cmake_path(APPEND <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>]) + +Append all the ``<input>`` arguments to the ``<path-var>`` using ``/`` as +the ``directory-separator``. Depending on the ``<input>``, the previous +contents of ``<path-var>`` may be discarded. For each ``<input>`` argument, +the following algorithm (pseudo-code) applies: + +:: + + # <path> is the contents of <path-var> + + if(<input>.is_absolute() OR + (<input>.has_root_name() AND + NOT <input>.root_name() STREQUAL <path>.root_name())) + replace <path> with <input> + return() + endif() + + if(<input>.has_root_directory()) + remove any root-directory and the entire relative path from <path> + elseif(<path>.has_filename() OR + (NOT <path-var>.has_root_directory() OR <path>.is_absolute())) + append directory-separator to <path> + endif() + + append <input> omitting any root-name to <path> + +.. _APPEND_STRING: + +:: + + cmake_path(APPEND_STRING <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>]) + +Append all the ``<input>`` arguments to the ``<path-var>`` without adding any +``directory-separator``. + +.. _REMOVE_FILENAME: + +:: + + cmake_path(REMOVE_FILENAME <path-var> [OUTPUT_VARIABLE <out-var>]) + +Removes the :ref:`filename <FILENAME_DEF>` component (as returned by +:ref:`GET ... FILENAME <GET_FILENAME>`) from ``<path-var>``. After removal, +any trailing ``directory-separator`` is left alone, if present. + +If ``OUTPUT_VARIABLE`` is not given, then after this function returns, +`HAS_FILENAME`_ returns false for ``<path-var>``. + +For example: + +.. code-block:: cmake + + set(path "/a/b") + cmake_path(REMOVE_FILENAME path) + message("First path is \"${path}\"") + + # filename is now already empty, the following removes nothing + cmake_path(REMOVE_FILENAME path) + message("Second path is \"${result}\"") + +Output:: + + First path is "/a/" + Second path is "/a/" + +.. _REPLACE_FILENAME: + +:: + + cmake_path(REPLACE_FILENAME <path-var> <input> [OUTPUT_VARIABLE <out-var>]) + +Replaces the :ref:`filename <FILENAME_DEF>` component from ``<path-var>`` +with ``<input>``. If ``<path-var>`` has no filename component (i.e. +`HAS_FILENAME`_ returns false), the path is unchanged. The operation is +equivalent to the following: + +.. code-block:: cmake + + cmake_path(HAS_FILENAME path has_filename) + if(has_filename) + cmake_path(REMOVE_FILENAME path) + cmake_path(APPEND path input); + endif() + +.. _REMOVE_EXTENSION: + +:: + + cmake_path(REMOVE_EXTENSION <path-var> [LAST_ONLY] + [OUTPUT_VARIABLE <out-var>]) + +Removes the :ref:`extension <EXTENSION_DEF>`, if any, from ``<path-var>``. + +.. _REPLACE_EXTENSION: + +:: + + cmake_path(REPLACE_EXTENSION <path-var> [LAST_ONLY] <input> + [OUTPUT_VARIABLE <out-var>]) + +Replaces the :ref:`extension <EXTENSION_DEF>` with ``<input>``. Its effect +is equivalent to the following: + +.. code-block:: cmake + + cmake_path(REMOVE_EXTENSION path) + if(NOT "input" MATCHES "^\\.") + cmake_path(APPEND_STRING path ".") + endif() + cmake_path(APPEND_STRING path "input") + + +Generation +^^^^^^^^^^ + +.. _NORMAL_PATH: + +:: + + cmake_path(NORMAL_PATH <path-var> [OUTPUT_VARIABLE <out-var>]) + +Normalize ``<path-var>`` according the steps described in :ref:`Normalization`. + +.. _cmake_path-RELATIVE_PATH: +.. _RELATIVE_PATH: + +:: + + cmake_path(RELATIVE_PATH <path-var> [BASE_DIRECTORY <input>] + [OUTPUT_VARIABLE <out-var>]) + +Modifies ``<path-var>`` to make it relative to the ``BASE_DIRECTORY`` argument. +If ``BASE_DIRECTORY`` is not specified, the default base directory will be +:variable:`CMAKE_CURRENT_SOURCE_DIR`. + +For reference, the algorithm used to compute the relative path is the same +as that used by C++ +`std::filesystem::path::lexically_relative +<https://en.cppreference.com/w/cpp/filesystem/path/lexically_normal>`_. + +.. _ABSOLUTE_PATH: + +:: + + cmake_path(ABSOLUTE_PATH <path-var> [BASE_DIRECTORY <input>] [NORMALIZE] + [OUTPUT_VARIABLE <out-var>]) + +If ``<path-var>`` is a relative path (`IS_RELATIVE`_ is true), it is evaluated +relative to the given base directory specified by ``BASE_DIRECTORY`` option. +If ``BASE_DIRECTORY`` is not specified, the default base directory will be +:variable:`CMAKE_CURRENT_SOURCE_DIR`. + +When the ``NORMALIZE`` option is specified, the path is :ref:`normalized +<Normalization>` after the path computation. + +Because ``cmake_path()`` does not access the filesystem, symbolic links are +not resolved. To compute a real path with symbolic links resolved, use the +:command:`file(REAL_PATH)` command instead. + +Native Conversion +^^^^^^^^^^^^^^^^^ + +For commands in this section, *native* refers to the host platform, not the +target platform when cross-compiling. + +.. _cmake_path-NATIVE_PATH: +.. _NATIVE_PATH: + +:: + + cmake_path(NATIVE_PATH <path-var> [NORMALIZE] <out-var>) + +Converts a cmake-style ``<path-var>`` into a native path with +platform-specific slashes (``\`` on Windows hosts and ``/`` elsewhere). + +When the ``NORMALIZE`` option is specified, the path is :ref:`normalized +<Normalization>` before the conversion. + +.. _CONVERT: +.. _cmake_path-TO_CMAKE_PATH_LIST: +.. _TO_CMAKE_PATH_LIST: + +:: + + cmake_path(CONVERT <input> TO_CMAKE_PATH_LIST <out-var> [NORMALIZE]) + +Converts a native ``<input>`` path into a cmake-style path with forward +slashes (``/``). On Windows hosts, the long filename marker is taken into +account. The input can be a single path or a system search path like +``$ENV{PATH}``. A search path will be converted to a cmake-style list +separated by ``;`` characters (on non-Windows platforms, this essentially +means ``:`` separators are replaced with ``;``). The result of the +conversion is stored in the ``<out-var>`` variable. + +When the ``NORMALIZE`` option is specified, the path is :ref:`normalized +<Normalization>` before the conversion. + +.. note:: + Unlike most other ``cmake_path()`` subcommands, the ``CONVERT`` subcommand + takes a literal string as input, not the name of a variable. + +.. _cmake_path-TO_NATIVE_PATH_LIST: +.. _TO_NATIVE_PATH_LIST: + +:: + + cmake_path(CONVERT <input> TO_NATIVE_PATH_LIST <out-var> [NORMALIZE]) + +Converts a cmake-style ``<input>`` path into a native path with +platform-specific slashes (``\`` on Windows hosts and ``/`` elsewhere). +The input can be a single path or a cmake-style list. A list will be +converted into a native search path (``;``-separated on Windows, +``:``-separated on other platforms). The result of the conversion is +stored in the ``<out-var>`` variable. + +When the ``NORMALIZE`` option is specified, the path is :ref:`normalized +<Normalization>` before the conversion. + +.. note:: + Unlike most other ``cmake_path()`` subcommands, the ``CONVERT`` subcommand + takes a literal string as input, not the name of a variable. + +For example: + +.. code-block:: cmake + + set(paths "/a/b/c" "/x/y/z") + cmake_path(CONVERT "${paths}" TO_NATIVE_PATH_LIST native_paths) + message("Native path list is \"${native_paths}\"") + +Output on Windows:: + + Native path list is "\a\b\c;\x\y\z" + +Output on all other platforms:: + + Native path list is "/a/b/c:/x/y/z" + +Hashing +^^^^^^^ + +.. _HASH: + +:: + + cmake_path(HASH <path-var> <out-var>) + +Compute a hash value of ``<path-var>`` such that for two paths ``p1`` and +``p2`` that compare equal (:ref:`COMPARE ... EQUAL <COMPARE>`), the hash +value of ``p1`` is equal to the hash value of ``p2``. The path is always +:ref:`normalized <Normalization>` before the hash is computed. diff --git a/Help/command/cmake_policy.rst b/Help/command/cmake_policy.rst new file mode 100644 index 0000000..94060d9 --- /dev/null +++ b/Help/command/cmake_policy.rst @@ -0,0 +1,111 @@ +cmake_policy +------------ + +Manage CMake Policy settings. See the :manual:`cmake-policies(7)` +manual for defined policies. + +As CMake evolves it is sometimes necessary to change existing behavior +in order to fix bugs or improve implementations of existing features. +The CMake Policy mechanism is designed to help keep existing projects +building as new versions of CMake introduce changes in behavior. Each +new policy (behavioral change) is given an identifier of the form +``CMP<NNNN>`` where ``<NNNN>`` is an integer index. Documentation +associated with each policy describes the ``OLD`` and ``NEW`` behavior +and the reason the policy was introduced. Projects may set each policy +to select the desired behavior. When CMake needs to know which behavior +to use it checks for a setting specified by the project. If no +setting is available the ``OLD`` behavior is assumed and a warning is +produced requesting that the policy be set. + +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: + +.. code-block:: cmake + + cmake_policy(VERSION <min>[...<max>]) + +.. versionadded:: 3.12 + The optional ``<max>`` version. + +``<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. + +Note that the :command:`cmake_minimum_required(VERSION)` +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) + +Tell CMake to use the ``OLD`` or ``NEW`` behavior for a given policy. +Projects depending on the old behavior of a given policy may silence a +policy warning by setting the policy state to ``OLD``. Alternatively +one may fix the project to work with the new behavior and set the +policy state to ``NEW``. + +.. include:: ../policy/DEPRECATED.txt + +Checking Policy Settings +^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: cmake + + cmake_policy(GET CMP<NNNN> <variable>) + +Check whether a given policy is set to ``OLD`` or ``NEW`` behavior. +The output ``<variable>`` value will be ``OLD`` or ``NEW`` if the +policy is set, and empty otherwise. + +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 +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: + +.. code-block:: cmake + + cmake_policy(PUSH) + cmake_policy(POP) + +Each ``PUSH`` must have a matching ``POP`` to erase any changes. +This is useful to make temporary changes to policy settings. +Calls to the :command:`cmake_minimum_required(VERSION)`, +``cmake_policy(VERSION)``, or ``cmake_policy(SET)`` commands +influence only the current top of the policy stack. + +Commands created by the :command:`function` and :command:`macro` +commands record policy settings when they are created and +use the pre-record policies when they are invoked. If the function or +macro implementation sets policies, the changes automatically +propagate up through callers until they reach the closest nested +policy stack entry. diff --git a/Help/command/configure_file.rst b/Help/command/configure_file.rst new file mode 100644 index 0000000..086668c --- /dev/null +++ b/Help/command/configure_file.rst @@ -0,0 +1,183 @@ +configure_file +-------------- + +Copy a file to another location and modify its contents. + +.. code-block:: cmake + + configure_file(<input> <output> + [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS | + FILE_PERMISSIONS <permissions>...] + [COPYONLY] [ESCAPE_QUOTES] [@ONLY] + [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ]) + +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 + +.. code-block:: c + + #cmakedefine VAR ... + +will be replaced with either + +.. code-block:: c + + #define VAR ... + +or + +.. code-block:: c + + /* #undef VAR */ + +depending on whether ``VAR`` is set in CMake to any value not considered +a false constant by the :command:`if` command. The "..." content on the +line after the variable name, if any, is processed as above. + +Unlike lines of the form ``#cmakedefine VAR ...``, in lines of the form +``#cmakedefine01 VAR``, ``VAR`` itself will expand to ``VAR 0`` or ``VAR 1`` +rather than being assigned the value ``...``. Therefore, input lines of the form + +.. code-block:: c + + #cmakedefine01 VAR + +will be replaced with either + +.. code-block:: c + + #define VAR 0 + +or + +.. code-block:: c + + #define VAR 1 + +Input lines of the form ``#cmakedefine01 VAR ...`` will expand +as ``#cmakedefine01 VAR ... 0`` or ``#cmakedefine01 VAR ... 0``, +which may lead to undefined behavior. + +.. versionadded:: 3.10 + 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: + +``<input>`` + Path to the input file. A relative path is treated with respect to + the value of :variable:`CMAKE_CURRENT_SOURCE_DIR`. The input path + must be a file, not a directory. + +``<output>`` + Path to the output file or directory. A relative path is treated + with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. + If the path names an existing directory the output file is placed + in that directory with the same file name as the input file. + +``NO_SOURCE_PERMISSIONS`` + .. versionadded:: 3.19 + + Do not transfer the permissions of the input file to the output file. + The copied file permissions default to the standard 644 value + (-rw-r--r--). + +``USE_SOURCE_PERMISSIONS`` + .. versionadded:: 3.20 + + Transfer the permissions of the input file to the output file. + This is already the default behavior if none of the three permissions-related + keywords are given (``NO_SOURCE_PERMISSIONS``, ``USE_SOURCE_PERMISSIONS`` + or ``FILE_PERMISSIONS``). The ``USE_SOURCE_PERMISSIONS`` keyword mostly + serves as a way of making the intended behavior clearer at the call site. + +``FILE_PERMISSIONS <permissions>...`` + .. versionadded:: 3.20 + + Ignore the input file's permissions and use the specified ``<permissions>`` + for the output file instead. + +``COPYONLY`` + Copy the file without replacing any variable references or other + content. This option may not be used with ``NEWLINE_STYLE``. + +``ESCAPE_QUOTES`` + Escape any substituted quotes with backslashes (C-style). + +``@ONLY`` + Restrict variable replacement to references of the form ``@VAR@``. + This is useful for configuring scripts that use ``${VAR}`` syntax. + +``NEWLINE_STYLE <style>`` + Specify the newline style for the output file. Specify + ``UNIX`` or ``LF`` for ``\n`` newlines, or specify + ``DOS``, ``WIN32``, or ``CRLF`` for ``\r\n`` newlines. + This option may not be used with ``COPYONLY``. + +Example +^^^^^^^ + +Consider a source tree containing a ``foo.h.in`` file: + +.. code-block:: c + + #cmakedefine FOO_ENABLE + #cmakedefine FOO_STRING "@FOO_STRING@" + +An adjacent ``CMakeLists.txt`` may use ``configure_file`` to +configure the header: + +.. code-block:: cmake + + option(FOO_ENABLE "Enable Foo" ON) + if(FOO_ENABLE) + set(FOO_STRING "foo") + endif() + configure_file(foo.h.in foo.h @ONLY) + +This creates a ``foo.h`` in the build directory corresponding to +this source directory. If the ``FOO_ENABLE`` option is on, the +configured file will contain: + +.. code-block:: c + + #define FOO_ENABLE + #define FOO_STRING "foo" + +Otherwise it will contain: + +.. code-block:: c + + /* #undef FOO_ENABLE */ + /* #undef FOO_STRING */ + +One may then use the :command:`include_directories` command to +specify the output directory as an include directory: + +.. code-block:: cmake + + include_directories(${CMAKE_CURRENT_BINARY_DIR}) + +so that sources may include the header as ``#include <foo.h>``. diff --git a/Help/command/continue.rst b/Help/command/continue.rst new file mode 100644 index 0000000..f62802e --- /dev/null +++ b/Help/command/continue.rst @@ -0,0 +1,16 @@ +continue +-------- + +.. versionadded:: 3.2 + +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. diff --git a/Help/command/create_test_sourcelist.rst b/Help/command/create_test_sourcelist.rst new file mode 100644 index 0000000..77e37c5 --- /dev/null +++ b/Help/command/create_test_sourcelist.rst @@ -0,0 +1,30 @@ +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 + EXTRA_INCLUDE include.h + FUNCTION function) + +A test driver is a program that links together many small tests into a +single executable. This is useful when building static executables +with large libraries to shrink the total required size. The list of +source files needed to build the test driver will be in +``sourceListName``. ``driverName`` is the name of the test driver program. +The rest of the arguments consist of a list of test source files, can +be semicolon separated. Each test source file should have a function +in it that is the same name as the file with no extension (foo.cxx +should have int foo(int, char*[]);) ``driverName`` will be able to call +each of the tests by name on the command line. If ``EXTRA_INCLUDE`` is +specified, then the next argument is included into the generated file. +If ``FUNCTION`` is specified, then the next argument is taken as a +function name that is passed a pointer to ac and av. This can be used +to add extra command line processing to each test. The +``CMAKE_TESTDRIVER_BEFORE_TESTMAIN`` cmake variable can be set to +have code that will be placed directly before calling the test main function. +``CMAKE_TESTDRIVER_AFTER_TESTMAIN`` can be set to have code that +will be placed directly after the call to the test main function. diff --git a/Help/command/ctest_build.rst b/Help/command/ctest_build.rst new file mode 100644 index 0000000..4d6dc5a --- /dev/null +++ b/Help/command/ctest_build.rst @@ -0,0 +1,85 @@ +ctest_build +----------- + +Perform the :ref:`CTest Build Step` as a :ref:`Dashboard Client`. + +:: + + ctest_build([BUILD <build-dir>] [APPEND] + [CONFIGURATION <config>] + [FLAGS <flags>] + [PROJECT_NAME <project-name>] + [TARGET <target-name>] + [NUMBER_ERRORS <num-err-var>] + [NUMBER_WARNINGS <num-warn-var>] + [RETURN_VALUE <result-var>] + [CAPTURE_CMAKE_ERROR <result-var>] + ) + +Build the project and store results in ``Build.xml`` +for submission with the :command:`ctest_submit` command. + +The :variable:`CTEST_BUILD_COMMAND` variable may be set to explicitly +specify the build command line. Otherwise the build command line is +computed automatically based on the options given. + +The options are: + +``BUILD <build-dir>`` + Specify the top-level build directory. If not given, the + :variable:`CTEST_BINARY_DIRECTORY` variable is used. + +``APPEND`` + Mark ``Build.xml`` for append to results previously submitted to a + dashboard server since the last :command:`ctest_start` call. + Append semantics are defined by the dashboard server in use. + This does *not* cause results to be appended to a ``.xml`` file + produced by a previous call to this command. + +``CONFIGURATION <config>`` + Specify the build configuration (e.g. ``Debug``). If not + specified the ``CTEST_BUILD_CONFIGURATION`` variable will be checked. + Otherwise the ``-C <cfg>`` option given to the :manual:`ctest(1)` + command will be used, if any. + +``FLAGS <flags>`` + Pass additional arguments to the underlying build command. + If not specified the ``CTEST_BUILD_FLAGS`` variable will be checked. + This can, e.g., be used to trigger a parallel build using the + ``-j`` option of make. See the :module:`ProcessorCount` module + for an example. + +``PROJECT_NAME <project-name>`` + Ignored since CMake 3.0. + + .. versionchanged:: 3.14 + This value is no longer required. + +``TARGET <target-name>`` + Specify the name of a target to build. If not specified the + ``CTEST_BUILD_TARGET`` variable will be checked. Otherwise the + default target will be built. This is the "all" target + (called ``ALL_BUILD`` in :ref:`Visual Studio Generators`). + +``NUMBER_ERRORS <num-err-var>`` + Store the number of build errors detected in the given variable. + +``NUMBER_WARNINGS <num-warn-var>`` + Store the number of build warnings detected in the given variable. + +``RETURN_VALUE <result-var>`` + Store the return value of the native build tool in the given variable. + +``CAPTURE_CMAKE_ERROR <result-var>`` + .. versionadded:: 3.7 + + 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`` + .. versionadded:: 3.3 + + Suppress any CTest-specific non-error output that would have been + printed to the console otherwise. The summary of warnings / errors, + as well as the output from the native build tool is unaffected by + this option. diff --git a/Help/command/ctest_configure.rst b/Help/command/ctest_configure.rst new file mode 100644 index 0000000..95712aa --- /dev/null +++ b/Help/command/ctest_configure.rst @@ -0,0 +1,50 @@ +ctest_configure +--------------- + +Perform the :ref:`CTest Configure Step` as a :ref:`Dashboard Client`. + +:: + + ctest_configure([BUILD <build-dir>] [SOURCE <source-dir>] [APPEND] + [OPTIONS <options>] [RETURN_VALUE <result-var>] [QUIET] + [CAPTURE_CMAKE_ERROR <result-var>]) + +Configure the project build tree and record results in ``Configure.xml`` +for submission with the :command:`ctest_submit` command. + +The options are: + +``BUILD <build-dir>`` + Specify the top-level build directory. If not given, the + :variable:`CTEST_BINARY_DIRECTORY` variable is used. + +``SOURCE <source-dir>`` + Specify the source directory. If not given, the + :variable:`CTEST_SOURCE_DIRECTORY` variable is used. + +``APPEND`` + Mark ``Configure.xml`` for append to results previously submitted to a + dashboard server since the last :command:`ctest_start` call. + Append semantics are defined by the dashboard server in use. + This does *not* cause results to be appended to a ``.xml`` file + produced by a previous call to this command. + +``OPTIONS <options>`` + Specify command-line arguments to pass to the configuration tool. + +``RETURN_VALUE <result-var>`` + Store in the ``<result-var>`` variable the return value of the native + configuration tool. + +``CAPTURE_CMAKE_ERROR <result-var>`` + .. versionadded:: 3.7 + + 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`` + .. versionadded:: 3.3 + + Suppress any CTest-specific non-error messages that would have + otherwise been printed to the console. Output from the underlying + configure command is not affected. diff --git a/Help/command/ctest_coverage.rst b/Help/command/ctest_coverage.rst new file mode 100644 index 0000000..a6c643b --- /dev/null +++ b/Help/command/ctest_coverage.rst @@ -0,0 +1,50 @@ +ctest_coverage +-------------- + +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>] + [QUIET] + ) + +Collect coverage tool results and stores them in ``Coverage.xml`` +for submission with the :command:`ctest_submit` command. + +The options are: + +``BUILD <build-dir>`` + Specify the top-level build directory. If not given, the + :variable:`CTEST_BINARY_DIRECTORY` variable is used. + +``APPEND`` + Mark ``Coverage.xml`` for append to results previously submitted to a + dashboard server since the last :command:`ctest_start` call. + Append semantics are defined by the dashboard server in use. + This does *not* cause results to be appended to a ``.xml`` file + produced by a previous call to this command. + +``LABELS`` + Filter the coverage report to include only source files labeled + with at least one of the labels specified. + +``RETURN_VALUE <result-var>`` + Store in the ``<result-var>`` variable ``0`` if coverage tools + ran without error and non-zero otherwise. + +``CAPTURE_CMAKE_ERROR <result-var>`` + .. versionadded:: 3.7 + + 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`` + .. versionadded:: 3.3 + + Suppress any CTest-specific non-error output that would have been + printed to the console otherwise. The summary indicating how many + lines of code were covered is unaffected by this option. diff --git a/Help/command/ctest_empty_binary_directory.rst b/Help/command/ctest_empty_binary_directory.rst new file mode 100644 index 0000000..7753667 --- /dev/null +++ b/Help/command/ctest_empty_binary_directory.rst @@ -0,0 +1,12 @@ +ctest_empty_binary_directory +---------------------------- + +empties the binary directory + +:: + + ctest_empty_binary_directory( directory ) + +Removes a binary directory. This command will perform some checks +prior to deleting the directory in an attempt to avoid malicious or +accidental directory deletion. diff --git a/Help/command/ctest_memcheck.rst b/Help/command/ctest_memcheck.rst new file mode 100644 index 0000000..f655c2e --- /dev/null +++ b/Help/command/ctest_memcheck.rst @@ -0,0 +1,40 @@ +ctest_memcheck +-------------- + +Perform the :ref:`CTest MemCheck Step` as a :ref:`Dashboard Client`. + +:: + + ctest_memcheck([BUILD <build-dir>] [APPEND] + [START <start-number>] + [END <end-number>] + [STRIDE <stride-number>] + [EXCLUDE <exclude-regex>] + [INCLUDE <include-regex>] + [EXCLUDE_LABEL <label-exclude-regex>] + [INCLUDE_LABEL <label-include-regex>] + [EXCLUDE_FIXTURE <regex>] + [EXCLUDE_FIXTURE_SETUP <regex>] + [EXCLUDE_FIXTURE_CLEANUP <regex>] + [PARALLEL_LEVEL <level>] + [TEST_LOAD <threshold>] + [SCHEDULE_RANDOM <ON|OFF>] + [STOP_TIME <time-of-day>] + [RETURN_VALUE <result-var>] + [DEFECT_COUNT <defect-count-var>] + [QUIET] + ) + + +Run tests with a dynamic analysis tool and store results in +``MemCheck.xml`` for submission with the :command:`ctest_submit` +command. + +Most options are the same as those for the :command:`ctest_test` command. + +The options unique to this command are: + +``DEFECT_COUNT <defect-count-var>`` + .. versionadded:: 3.8 + + Store in the ``<defect-count-var>`` the number of defects found. diff --git a/Help/command/ctest_read_custom_files.rst b/Help/command/ctest_read_custom_files.rst new file mode 100644 index 0000000..cf8e17a --- /dev/null +++ b/Help/command/ctest_read_custom_files.rst @@ -0,0 +1,14 @@ +ctest_read_custom_files +----------------------- + +read CTestCustom files. + +:: + + ctest_read_custom_files( directory ... ) + +Read all the CTestCustom.ctest or CTestCustom.cmake files from the +given directory. + +By default, invoking :manual:`ctest(1)` without a script will read custom +files from the binary directory. diff --git a/Help/command/ctest_run_script.rst b/Help/command/ctest_run_script.rst new file mode 100644 index 0000000..5ec543e --- /dev/null +++ b/Help/command/ctest_run_script.rst @@ -0,0 +1,15 @@ +ctest_run_script +---------------- + +runs a ctest -S script + +:: + + ctest_run_script([NEW_PROCESS] script_file_name script_file_name1 + script_file_name2 ... [RETURN_VALUE var]) + +Runs a script or scripts much like if it was run from ctest -S. If no +argument is provided then the current script is run using the current +settings of the variables. If ``NEW_PROCESS`` is specified then each +script will be run in a separate process.If ``RETURN_VALUE`` is specified +the return value of the last script run will be put into ``var``. diff --git a/Help/command/ctest_sleep.rst b/Help/command/ctest_sleep.rst new file mode 100644 index 0000000..16a914c --- /dev/null +++ b/Help/command/ctest_sleep.rst @@ -0,0 +1,16 @@ +ctest_sleep +----------- + +sleeps for some amount of time + +:: + + ctest_sleep(<seconds>) + +Sleep for given number of seconds. + +:: + + ctest_sleep(<time1> <duration> <time2>) + +Sleep for t=(time1 + duration - time2) seconds if t > 0. diff --git a/Help/command/ctest_start.rst b/Help/command/ctest_start.rst new file mode 100644 index 0000000..c0f3c6d --- /dev/null +++ b/Help/command/ctest_start.rst @@ -0,0 +1,88 @@ +ctest_start +----------- + +Starts the testing for a given model + +:: + + 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. + +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. + + .. versionchanged:: 3.16 + 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`` + .. versionadded:: 3.3 + + 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 new file mode 100644 index 0000000..e6d277f --- /dev/null +++ b/Help/command/ctest_submit.rst @@ -0,0 +1,130 @@ +ctest_submit +------------ + +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] + ) + +Submit results to a dashboard server. +By default all available parts are submitted. + +The options are: + +``PARTS <part>...`` + Specify a subset of parts to submit. Valid part names are:: + + Start = nothing + Update = ctest_update results, in Update.xml + Configure = ctest_configure results, in Configure.xml + Build = ctest_build results, in Build.xml + Test = ctest_test results, in Test.xml + Coverage = ctest_coverage results, in Coverage.xml + MemCheck = ctest_memcheck results, in DynamicAnalysis.xml + Notes = Files listed by CTEST_NOTES_FILES, in Notes.xml + 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>`` + .. versionadded:: 3.14 + + 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>`` + .. versionadded:: 3.15 + + Store in the ``<result-var>`` variable the ID assigned to this build by + CDash. + +``HTTPHEADER <HTTP-header>`` + .. versionadded:: 3.9 + + Specify HTTP header to be included in the request to CDash during submission. + 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. + +``RETRY_DELAY <delay>`` + Specify how long (in seconds) to wait after a timed-out submission + before attempting to re-submit. + +``RETURN_VALUE <result-var>`` + Store in the ``<result-var>`` variable ``0`` for success and + non-zero on failure. + +``CAPTURE_CMAKE_ERROR <result-var>`` + .. versionadded:: 3.13 + + 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`` + .. versionadded:: 3.3 + + Suppress all non-error messages that would have otherwise been + printed to the console. + +Submit to CDash Upload API +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 3.2 + +:: + + ctest_submit(CDASH_UPLOAD <file> [CDASH_UPLOAD_TYPE <type>] + [SUBMIT_URL <url>] + [BUILD_ID <result-var>] + [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 +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 interprets options in the same way as the first one. + +.. versionadded:: 3.8 + Added the ``RETRY_COUNT``, ``RETRY_DELAY``, ``QUIET`` options. + +.. versionadded:: 3.9 + Added the ``HTTPHEADER`` option. + +.. versionadded:: 3.13 + Added the ``RETURN_VALUE`` option. + +.. versionadded:: 3.14 + Added the ``SUBMIT_URL`` option. + +.. versionadded:: 3.15 + Added the ``BUILD_ID`` option. diff --git a/Help/command/ctest_test.rst b/Help/command/ctest_test.rst new file mode 100644 index 0000000..b4493a0 --- /dev/null +++ b/Help/command/ctest_test.rst @@ -0,0 +1,162 @@ +ctest_test +---------- + +Perform the :ref:`CTest Test Step` as a :ref:`Dashboard Client`. + +:: + + ctest_test([BUILD <build-dir>] [APPEND] + [START <start-number>] + [END <end-number>] + [STRIDE <stride-number>] + [EXCLUDE <exclude-regex>] + [INCLUDE <include-regex>] + [EXCLUDE_LABEL <label-exclude-regex>] + [INCLUDE_LABEL <label-include-regex>] + [EXCLUDE_FIXTURE <regex>] + [EXCLUDE_FIXTURE_SETUP <regex>] + [EXCLUDE_FIXTURE_CLEANUP <regex>] + [PARALLEL_LEVEL <level>] + [RESOURCE_SPEC_FILE <file>] + [TEST_LOAD <threshold>] + [SCHEDULE_RANDOM <ON|OFF>] + [STOP_ON_FAILURE] + [STOP_TIME <time-of-day>] + [RETURN_VALUE <result-var>] + [CAPTURE_CMAKE_ERROR <result-var>] + [REPEAT <mode>:<n>] + [QUIET] + ) + +Run tests in the project build tree and store results in +``Test.xml`` for submission with the :command:`ctest_submit` command. + +The options are: + +``BUILD <build-dir>`` + Specify the top-level build directory. If not given, the + :variable:`CTEST_BINARY_DIRECTORY` variable is used. + +``APPEND`` + Mark ``Test.xml`` for append to results previously submitted to a + dashboard server since the last :command:`ctest_start` call. + Append semantics are defined by the dashboard server in use. + This does *not* cause results to be appended to a ``.xml`` file + produced by a previous call to this command. + +``START <start-number>`` + Specify the beginning of a range of test numbers. + +``END <end-number>`` + Specify the end of a range of test numbers. + +``STRIDE <stride-number>`` + Specify the stride by which to step across a range of test numbers. + +``EXCLUDE <exclude-regex>`` + Specify a regular expression matching test names to exclude. + +``INCLUDE <include-regex>`` + Specify a regular expression matching test names to include. + Tests not matching this expression are excluded. + +``EXCLUDE_LABEL <label-exclude-regex>`` + Specify a regular expression matching test labels to exclude. + +``INCLUDE_LABEL <label-include-regex>`` + Specify a regular expression matching test labels to include. + Tests not matching this expression are excluded. + +``EXCLUDE_FIXTURE <regex>`` + .. versionadded:: 3.7 + + If a test in the set of tests to be executed requires a particular fixture, + that fixture's setup and cleanup tests would normally be added to the test + set automatically. This option prevents adding setup or cleanup tests for + fixtures matching the ``<regex>``. Note that all other fixture behavior is + retained, including test dependencies and skipping tests that have fixture + setup tests that fail. + +``EXCLUDE_FIXTURE_SETUP <regex>`` + .. versionadded:: 3.7 + + Same as ``EXCLUDE_FIXTURE`` except only matching setup tests are excluded. + +``EXCLUDE_FIXTURE_CLEANUP <regex>`` + .. versionadded:: 3.7 + + Same as ``EXCLUDE_FIXTURE`` except only matching cleanup tests are excluded. + +``PARALLEL_LEVEL <level>`` + Specify a positive number representing the number of tests to + be run in parallel. + +``RESOURCE_SPEC_FILE <file>`` + .. versionadded:: 3.16 + + Specify a + :ref:`resource specification file <ctest-resource-specification-file>`. See + :ref:`ctest-resource-allocation` for more information. + +``TEST_LOAD <threshold>`` + .. versionadded:: 3.4 + + 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 + specified the :variable:`CTEST_TEST_LOAD` variable will be checked, + and then the ``--test-load`` command-line argument to :manual:`ctest(1)`. + See also the ``TestLoad`` setting in the :ref:`CTest Test Step`. + +``REPEAT <mode>:<n>`` + .. versionadded:: 3.17 + + Run tests repeatedly based on the given ``<mode>`` up to ``<n>`` times. + The modes are: + + ``UNTIL_FAIL`` + Require each test to run ``<n>`` times without failing in order to pass. + This is useful in finding sporadic failures in test cases. + + ``UNTIL_PASS`` + Allow each test to run up to ``<n>`` times in order to pass. + Repeats tests if they fail for any reason. + This is useful in tolerating sporadic failures in test cases. + + ``AFTER_TIMEOUT`` + Allow each test to run up to ``<n>`` times in order to pass. + Repeats tests only if they timeout. + This is useful in tolerating sporadic timeouts in test cases + on busy machines. + +``SCHEDULE_RANDOM <ON|OFF>`` + Launch tests in a random order. This may be useful for detecting + implicit test dependencies. + +``STOP_ON_FAILURE`` + .. versionadded:: 3.18 + + Stop the execution of the tests once one has failed. + +``STOP_TIME <time-of-day>`` + Specify a time of day at which the tests should all stop running. + +``RETURN_VALUE <result-var>`` + Store in the ``<result-var>`` variable ``0`` if all tests passed. + Store non-zero if anything went wrong. + +``CAPTURE_CMAKE_ERROR <result-var>`` + .. versionadded:: 3.7 + + 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`` + .. versionadded:: 3.3 + + Suppress any CTest-specific non-error messages that would have otherwise + been printed to the console. Output from the underlying test command is not + affected. Summary info detailing the percentage of passing tests is also + unaffected by the ``QUIET`` option. + +See also the :variable:`CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE` +and :variable:`CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE` variables. diff --git a/Help/command/ctest_update.rst b/Help/command/ctest_update.rst new file mode 100644 index 0000000..63f991b --- /dev/null +++ b/Help/command/ctest_update.rst @@ -0,0 +1,43 @@ +ctest_update +------------ + +Perform the :ref:`CTest Update Step` as a :ref:`Dashboard Client`. + +:: + + 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. + +The options are: + +``SOURCE <source-dir>`` + Specify the source directory. If not given, the + :variable:`CTEST_SOURCE_DIRECTORY` variable is used. + +``RETURN_VALUE <result-var>`` + Store in the ``<result-var>`` variable the number of files + updated or ``-1`` on error. + +``CAPTURE_CMAKE_ERROR <result-var>`` + .. versionadded:: 3.13 + + 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`` + .. versionadded:: 3.3 + + Tell CTest to suppress most non-error messages that it would + have otherwise printed to the console. CTest will still report + the new revision of the repository and any conflicting files + that were found. + +The update always follows the version control branch currently checked +out in the source directory. See the :ref:`CTest Update Step` +documentation for information about variables that change the behavior +of ``ctest_update()``. diff --git a/Help/command/ctest_upload.rst b/Help/command/ctest_upload.rst new file mode 100644 index 0000000..ffddd0a --- /dev/null +++ b/Help/command/ctest_upload.rst @@ -0,0 +1,26 @@ +ctest_upload +------------ + +Upload files to a dashboard server as a :ref:`Dashboard Client`. + +:: + + ctest_upload(FILES <file>... [QUIET] [CAPTURE_CMAKE_ERROR <result-var>]) + +The options are: + +``FILES <file>...`` + Specify a list of files to be sent along with the build results to the + dashboard server. + +``QUIET`` + .. versionadded:: 3.3 + + Suppress any CTest-specific non-error output that would have been + printed to the console otherwise. + +``CAPTURE_CMAKE_ERROR <result-var>`` + .. versionadded:: 3.7 + + 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. diff --git a/Help/command/define_property.rst b/Help/command/define_property.rst new file mode 100644 index 0000000..8f7439b --- /dev/null +++ b/Help/command/define_property.rst @@ -0,0 +1,59 @@ +define_property +--------------- + +Define and document custom properties. + +.. code-block:: cmake + + define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE | + TEST | VARIABLE | CACHED_VARIABLE> + PROPERTY <name> [INHERITED] + BRIEF_DOCS <brief-doc> [docs...] + FULL_DOCS <full-doc> [docs...]) + +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 +scope in which the property should be used. It must be one of the +following: + +:: + + GLOBAL = associated with the global namespace + DIRECTORY = associated with one directory + TARGET = associated with one target + SOURCE = associated with one source file + TEST = associated with a test named with add_test + VARIABLE = documents a CMake language variable + CACHED_VARIABLE = documents a CMake cache variable + +Note that unlike :command:`set_property` and :command:`get_property` no +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 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. +Corresponding options to the :command:`get_property` command will retrieve +the documentation. diff --git a/Help/command/else.rst b/Help/command/else.rst new file mode 100644 index 0000000..a98fcd8 --- /dev/null +++ b/Help/command/else.rst @@ -0,0 +1,10 @@ +else +---- + +Starts the else portion of an if block. + +.. code-block:: cmake + + else([<condition>]) + +See the :command:`if` command. diff --git a/Help/command/elseif.rst b/Help/command/elseif.rst new file mode 100644 index 0000000..6bf8646 --- /dev/null +++ b/Help/command/elseif.rst @@ -0,0 +1,11 @@ +elseif +------ + +Starts an elseif portion of an if block. + +.. code-block:: cmake + + elseif(<condition>) + +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 new file mode 100644 index 0000000..ce765de --- /dev/null +++ b/Help/command/enable_language.rst @@ -0,0 +1,35 @@ +enable_language +--------------- +Enable a language (CXX/C/OBJC/OBJCXX/Fortran/etc) + +.. code-block:: cmake + + enable_language(<lang> [OPTIONAL] ) + +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``, ``CUDA``, ``OBJC``, ``OBJCXX``, ``Fortran``, +``ISPC``, and ``ASM``. + +.. versionadded:: 3.8 + Added ``CUDA`` support. + +.. versionadded:: 3.16 + Added ``OBJC`` and ``OBJCXX`` support. + +.. versionadded:: 3.18 + Added ``ISPC`` support. + +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 +targets using the named language directly for compiling sources or +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. 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 new file mode 100644 index 0000000..3ac1a19 --- /dev/null +++ b/Help/command/enable_testing.rst @@ -0,0 +1,20 @@ +enable_testing +-------------- + +Enable testing for current directory and below. + +.. code-block:: cmake + + enable_testing() + +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 new file mode 100644 index 0000000..fd923d5 --- /dev/null +++ b/Help/command/endforeach.rst @@ -0,0 +1,14 @@ +endforeach +---------- + +Ends a list of commands in a foreach block. + +.. code-block:: cmake + + 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 new file mode 100644 index 0000000..e27129d --- /dev/null +++ b/Help/command/endfunction.rst @@ -0,0 +1,14 @@ +endfunction +----------- + +Ends a list of commands in a function block. + +.. code-block:: cmake + + 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 new file mode 100644 index 0000000..fc4f038 --- /dev/null +++ b/Help/command/endif.rst @@ -0,0 +1,14 @@ +endif +----- + +Ends a list of commands in an if block. + +.. code-block:: cmake + + 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 new file mode 100644 index 0000000..4290ba7 --- /dev/null +++ b/Help/command/endmacro.rst @@ -0,0 +1,14 @@ +endmacro +-------- + +Ends a list of commands in a macro block. + +.. code-block:: cmake + + 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 new file mode 100644 index 0000000..5ef585b --- /dev/null +++ b/Help/command/endwhile.rst @@ -0,0 +1,14 @@ +endwhile +-------- + +Ends a list of commands in a while block. + +.. code-block:: cmake + + 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 new file mode 100644 index 0000000..bc9b069 --- /dev/null +++ b/Help/command/exec_program.rst @@ -0,0 +1,26 @@ +exec_program +------------ + +.. deprecated:: 3.0 + + Use the :command:`execute_process` command instead. + +Run an executable program during the processing of the CMakeList.txt +file. + +:: + + exec_program(Executable [directory in which to run] + [ARGS <arguments to executable>] + [OUTPUT_VARIABLE <var>] + [RETURN_VALUE <var>]) + +The executable is run in the optionally specified directory. The +executable can include arguments if it is double quoted, but it is +better to use the optional ``ARGS`` argument to specify arguments to the +program. This is because cmake will then be able to escape spaces in +the executable path. An optional argument ``OUTPUT_VARIABLE`` specifies a +variable in which to store the output. To capture the return value of +the execution, provide a ``RETURN_VALUE``. If ``OUTPUT_VARIABLE`` is +specified, then no output will go to the stdout/stderr of the console +running cmake. diff --git a/Help/command/execute_process.rst b/Help/command/execute_process.rst new file mode 100644 index 0000000..82fcd46 --- /dev/null +++ b/Help/command/execute_process.rst @@ -0,0 +1,158 @@ +execute_process +--------------- + +Execute one or more child processes. + +.. code-block:: cmake + + 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>] + [OUTPUT_FILE <file>] + [ERROR_FILE <file>] + [OUTPUT_QUIET] + [ERROR_QUIET] + [COMMAND_ECHO <where>] + [OUTPUT_STRIP_TRAILING_WHITESPACE] + [ERROR_STRIP_TRAILING_WHITESPACE] + [ENCODING <name>] + [ECHO_OUTPUT_VARIABLE] + [ECHO_ERROR_VARIABLE] + [COMMAND_ERROR_IS_FATAL <ANY|LAST>]) + +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. + +Options: + +``COMMAND`` + A child process command line. + + CMake executes the child process using operating system APIs directly. + All arguments are passed VERBATIM to the child process. + No intermediate shell is used, so shell operators such as ``>`` + are treated as normal arguments. + (Use the ``INPUT_*``, ``OUTPUT_*``, and ``ERROR_*`` options to + redirect stdin, stdout, and stderr.) + + If a sequential execution of multiple commands is required, use multiple + :command:`execute_process` calls with a single ``COMMAND`` argument. + +``WORKING_DIRECTORY`` + The named directory will be set as the current working directory of + the child processes. + +``TIMEOUT`` + 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 last child process. + This will be an integer return code from the last child or a string + describing an error condition. + +``RESULTS_VARIABLE <variable>`` + .. versionadded:: 3.10 + + 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 + for both pipes their output will be merged in the order produced. + +``INPUT_FILE, OUTPUT_FILE``, ``ERROR_FILE`` + The file named will be attached to the standard input of the first + process, standard output of the last process, or standard error of + all processes, respectively. + + .. versionadded:: 3.3 + If the same file is named for both output and error then it will be used + for both. + +``OUTPUT_QUIET``, ``ERROR_QUIET`` + The standard output or standard error results will be quietly ignored. + +``COMMAND_ECHO <where>`` + .. versionadded:: 3.15 + + 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>`` + .. versionadded:: 3.8 + + On Windows, the encoding that is used to decode output from the process. + Ignored on other platforms. + Valid encoding names are: + + ``NONE`` + Perform no decoding. This assumes that the process output is encoded + in the same way as CMake's internal encoding (UTF-8). + This is the default. + ``AUTO`` + Use the current active console's codepage or if that isn't + available then use ANSI. + ``ANSI`` + Use the ANSI codepage. + ``OEM`` + Use the original equipment manufacturer (OEM) code page. + ``UTF8`` or ``UTF-8`` + Use the UTF-8 codepage. + + .. versionadded:: 3.11 + Accept ``UTF-8`` spelling for consistency with the + `UTF-8 RFC <https://www.ietf.org/rfc/rfc3629>`_ naming convention. + +``ECHO_OUTPUT_VARIABLE``, ``ECHO_ERROR_VARIABLE`` + .. versionadded:: 3.18 + + The standard output or standard error will not be exclusively redirected to + the configured variables. + + The output will be duplicated, it will be sent into the configured variables + and also on standard output or standard error. + + This is analogous to the ``tee`` Unix command. + +``COMMAND_ERROR_IS_FATAL <ANY|LAST>`` + .. versionadded:: 3.19 + + The option following ``COMMAND_ERROR_IS_FATAL`` determines the behavior when + an error is encountered: + + ``ANY`` + If any of the commands in the list of commands fail, the + ``execute_process()`` command halts with an error. + + ``LAST`` + If the last command in the list of commands fails, the + ``execute_process()`` command halts with an error. Commands earlier in the + list will not cause a fatal error. + +If more than one ``OUTPUT_*`` or ``ERROR_*`` option is given for the +same pipe the precedence is not specified. +If no ``OUTPUT_*`` or ``ERROR_*`` options are given the output will +be shared with the corresponding pipes of the CMake process itself. + +The :command:`execute_process` command is a newer more powerful version of +:command:`exec_program`, but the old command has been kept for compatibility. +Both commands run while CMake is processing the project prior to build +system generation. Use :command:`add_custom_target` and +:command:`add_custom_command` to create custom commands that run at +build time. diff --git a/Help/command/export.rst b/Help/command/export.rst new file mode 100644 index 0000000..e8a1fa7 --- /dev/null +++ b/Help/command/export.rst @@ -0,0 +1,93 @@ +export +------ + +Export targets from the build tree for use by outside projects. + +.. code-block:: cmake + + export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>]) + +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 +project being compiled for the target platform. If the ``NAMESPACE`` +option is given the ``<namespace>`` string will be prepended to all target +names written to the file. + +Target installations are associated with the export ``<export-name>`` +using the ``EXPORT`` option of the :command:`install(TARGETS)` command. + +The file created by this command is specific to the build tree and +should never be installed. See the :command:`install(EXPORT)` command to +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]) + +This signature is similar to the ``EXPORT`` signature, but targets are listed +explicitly rather than specified as an export-name. If the APPEND option is +given the generated code will be appended to the file instead of overwriting it. +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 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:: + + :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 ``<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 (``<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. + +.. versionchanged:: 3.1 + If the :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` variable + is enabled, the ``export(PACKAGE)`` command will do nothing. + +.. versionchanged:: 3.15 + 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>]) + +.. versionadded:: 3.7 + +This signature exports cmake built targets to the android ndk build system +by creating an Android.mk file that references the prebuilt targets. 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 +and defines required to use the libraries. The signature takes a list of +targets and puts them in the Android.mk file specified by the ``<filename>`` +given. This signature can only be used if policy CMP0022 is NEW for all +targets given. A error will be issued if that policy is set to OLD for one +of the targets. diff --git a/Help/command/export_library_dependencies.rst b/Help/command/export_library_dependencies.rst new file mode 100644 index 0000000..9753abf --- /dev/null +++ b/Help/command/export_library_dependencies.rst @@ -0,0 +1,28 @@ +export_library_dependencies +--------------------------- + +Disallowed since version 3.0. See CMake Policy :policy:`CMP0033`. + +Use :command:`install(EXPORT)` or :command:`export` command. + +This command generates an old-style library dependencies file. +Projects requiring CMake 2.6 or later should not use the command. Use +instead the :command:`install(EXPORT)` command to help export targets from an +installation tree and the :command:`export` command to export targets from a +build tree. + +The old-style library dependencies file does not take into account +per-configuration names of libraries or the +:prop_tgt:`LINK_INTERFACE_LIBRARIES` target property. + +:: + + export_library_dependencies(<file> [APPEND]) + +Create a file named ``<file>`` that can be included into a CMake listfile +with the INCLUDE command. The file will contain a number of SET +commands that will set all the variables needed for library dependency +information. This should be the last command in the top level +CMakeLists.txt file of the project. If the ``APPEND`` option is +specified, the SET commands will be appended to the given file instead +of replacing it. diff --git a/Help/command/file.rst b/Help/command/file.rst new file mode 100644 index 0000000..62642cf --- /dev/null +++ b/Help/command/file.rst @@ -0,0 +1,1183 @@ +file +---- + +File manipulation command. + +This command is dedicated to file and path manipulation requiring access to the +filesystem. + +For other path manipulation, handling only syntactic aspects, have a look at +:command:`cmake_path` command. + +.. note:: + + The sub-commands `RELATIVE_PATH`_, `TO_CMAKE_PATH`_ and `TO_NATIVE_PATH`_ has + been superseded, respectively, by sub-commands + :ref:`RELATIVE_PATH <cmake_path-RELATIVE_PATH>`, + :ref:`CONVERT ... TO_CMAKE_PATH_LIST <cmake_path-TO_CMAKE_PATH_LIST>` and + :ref:`CONVERT ... TO_NATIVE_PATH_LIST <cmake_path-TO_NATIVE_PATH_LIST>` of + :command:`cmake_path` command. + +Synopsis +^^^^^^^^ + +.. parsed-literal:: + + `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`_ [...]) + + `Writing`_ + file({`WRITE`_ | `APPEND`_} <filename> <content>...) + file({`TOUCH`_ | `TOUCH_NOCREATE`_} [<file>...]) + file(`GENERATE`_ OUTPUT <output-file> [...]) + file(`CONFIGURE`_ OUTPUT <output-file> CONTENT <content> [...]) + + `Filesystem`_ + file({`GLOB`_ | `GLOB_RECURSE`_} <out-var> [...] [<globbing-expr>...]) + file(`RENAME`_ <oldname> <newname> [...]) + file(`COPY_FILE`_ <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> [...]) + file(`CHMOD`_ <files>... <directories>... PERMISSIONS <permissions>... [...]) + file(`CHMOD_RECURSE`_ <files>... <directories>... PERMISSIONS <permissions>... [...]) + + `Path Conversion`_ + file(`REAL_PATH`_ <path> <out-var> [BASE_DIRECTORY <dir>]) + 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> [...]) + + `Archiving`_ + file(`ARCHIVE_CREATE`_ OUTPUT <archive> PATHS <paths>... [...]) + file(`ARCHIVE_EXTRACT`_ INPUT <archive> [...]) + +Reading +^^^^^^^ + +.. _READ: + +.. code-block:: cmake + + file(READ <filename> <variable> + [OFFSET <offset>] [LIMIT <max-in>] [HEX]) + +Read content from a file called ``<filename>`` and store it in a +``<variable>``. Optionally start from the given ``<offset>`` and +read at most ``<max-in>`` bytes. The ``HEX`` option causes data to +be converted to a hexadecimal representation (useful for binary data). If the +``HEX`` option is specified, letters in the output (``a`` through ``f``) are in +lowercase. + +.. _STRINGS: + +.. code-block:: cmake + + file(STRINGS <filename> <variable> [<options>...]) + +Parse a list of ASCII strings from ``<filename>`` and store it in +``<variable>``. Binary data in the file are ignored. Carriage return +(``\r``, CR) characters are ignored. The options are: + +``LENGTH_MAXIMUM <max-len>`` + Consider only strings of at most a given length. + +``LENGTH_MINIMUM <min-len>`` + Consider only strings of at least a given length. + +``LIMIT_COUNT <max-num>`` + Limit the number of distinct strings to be extracted. + +``LIMIT_INPUT <max-in>`` + Limit the number of input bytes to read from the file. + +``LIMIT_OUTPUT <max-out>`` + Limit the number of total bytes to store in the ``<variable>``. + +``NEWLINE_CONSUME`` + Treat newline characters (``\n``, LF) as part of string content + instead of terminating at them. + +``NO_HEX_CONVERSION`` + Intel Hex and Motorola S-record files are automatically converted to + binary while reading unless this option is given. + +``REGEX <regex>`` + Consider only strings that match the given regular expression. + +``ENCODING <encoding-type>`` + .. versionadded:: 3.1 + + Consider strings of a given encoding. Currently supported encodings are: + ``UTF-8``, ``UTF-16LE``, ``UTF-16BE``, ``UTF-32LE``, ``UTF-32BE``. + If the ``ENCODING`` option is not provided and the file has a Byte Order Mark, + the ``ENCODING`` option will be defaulted to respect the Byte Order Mark. + + .. versionadded:: 3.2 + Added the ``UTF-16LE``, ``UTF-16BE``, ``UTF-32LE``, ``UTF-32BE`` encodings. + +For example, the code + +.. code-block:: cmake + + file(STRINGS myfile.txt myfile) + +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>) + +Compute a cryptographic hash of the content of ``<filename>`` and +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>...]] + ) + +.. versionadded:: 3.16 + +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 exclude unwanted system libraries when +resolving the dependencies, or to include 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 by the value of + ``CMAKE_OBJDUMP`` if set, else by system introspection. + + .. versionadded:: 3.18 + Use ``CMAKE_OBJDUMP`` if set. + +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>...]) + +.. versionadded:: 3.12 + +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] [TARGET target] + [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS | + FILE_PERMISSIONS <permissions>...] + [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ]) + +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. + + .. versionchanged:: 3.10 + 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. + + .. versionchanged:: 3.10 + A relative path (after evaluating generator expressions) is treated + with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. + See policy :policy:`CMP0070`. + +``TARGET <target>`` + .. versionadded:: 3.19 + + Specify which target to use when evaluating generator expressions that + require a target for evaluation (e.g. ``$<COMPILE_FEATURES:...>``, + ``$<TARGET_PROPERTY:prop>``). + +``NO_SOURCE_PERMISSIONS`` + .. versionadded:: 3.20 + + The generated file permissions default to the standard 644 value + (-rw-r--r--). + +``USE_SOURCE_PERMISSIONS`` + .. versionadded:: 3.20 + + Transfer the file permissions of the ``INPUT`` file to the generated file. + This is already the default behavior if none of the three permissions-related + keywords are given (``NO_SOURCE_PERMISSIONS``, ``USE_SOURCE_PERMISSIONS`` + or ``FILE_PERMISSIONS``). The ``USE_SOURCE_PERMISSIONS`` keyword mostly + serves as a way of making the intended behavior clearer at the call site. + It is an error to specify this option without ``INPUT``. + +``FILE_PERMISSIONS <permissions>...`` + .. versionadded:: 3.20 + + Use the specified permissions for the generated file. + +``NEWLINE_STYLE <style>`` + .. versionadded:: 3.20 + + Specify the newline style for the generated file. Specify + ``UNIX`` or ``LF`` for ``\n`` newlines, or specify + ``DOS``, ``WIN32``, or ``CRLF`` for ``\r\n`` newlines. + +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. + +.. _CONFIGURE: + +.. code-block:: cmake + + file(CONFIGURE OUTPUT output-file + CONTENT content + [ESCAPE_QUOTES] [@ONLY] + [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ]) + +.. versionadded:: 3.18 + +Generate an output file using the input given by ``CONTENT`` and substitute +variable values referenced as ``@VAR@`` or ``${VAR}`` contained therein. The +substitution rules behave the same as the :command:`configure_file` command. +In order to match :command:`configure_file`'s behavior, generator expressions +are not supported for both ``OUTPUT`` and ``CONTENT``. + +The arguments are: + +``OUTPUT <output-file>`` + Specify the output file name to generate. A relative path is treated with + respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. + ``<output-file>`` does not support generator expressions. + +``CONTENT <content>`` + Use the content given explicitly as input. + ``<content>`` does not support generator expressions. + +``ESCAPE_QUOTES`` + Escape any substituted quotes with backslashes (C-style). + +``@ONLY`` + Restrict variable replacement to references of the form ``@VAR@``. + This is useful for configuring scripts that use ``${VAR}`` syntax. + +``NEWLINE_STYLE <style>`` + Specify the newline style for the output file. Specify + ``UNIX`` or ``LF`` for ``\n`` newlines, or specify + ``DOS``, ``WIN32``, or ``CRLF`` for ``\r\n`` newlines. + +Filesystem +^^^^^^^^^^ + +.. _GLOB: +.. _GLOB_RECURSE: + +.. code-block:: cmake + + file(GLOB <variable> + [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS] + [<globbing-expressions>...]) + file(GLOB_RECURSE <variable> [FOLLOW_SYMLINKS] + [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. + +.. versionchanged:: 3.6 + 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. + +.. versionadded:: 3.3 + By default ``GLOB`` lists directories - directories are omitted in result if + ``LIST_DIRECTORIES`` is set to false. + +.. versionadded:: 3.12 + 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. + +.. note:: + We do not recommend using GLOB to collect a list of source files from + 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:: + + *.cxx - match all files with extension cxx + *.vt? - match all files with extension vta,...,vtz + f[3-5].txt - match files f3.txt, f4.txt, f5.txt + +The ``GLOB_RECURSE`` mode will traverse all the subdirectories of the +matched directory and match the files. Subdirectories that are symlinks +are only traversed if ``FOLLOW_SYMLINKS`` is given or policy +:policy:`CMP0009` is not set to ``NEW``. + +.. versionadded:: 3.3 + By default ``GLOB_RECURSE`` omits directories from result list - setting + ``LIST_DIRECTORIES`` to true adds directories to result list. + If ``FOLLOW_SYMLINKS`` is given or policy :policy:`CMP0009` is not set to + ``NEW`` then ``LIST_DIRECTORIES`` treats symlinks as directories. + +Examples of recursive globbing include:: + + /dir/*.py - match all python files in /dir and subdirectories + +.. _RENAME: + +.. code-block:: cmake + + file(RENAME <oldname> <newname> + [RESULT <result>] + [NO_REPLACE]) + +Move a file or directory within a filesystem from ``<oldname>`` to +``<newname>``, replacing the destination atomically. + +The options are: + +``RESULT <result>`` + Set ``<result>`` variable to ``0`` on success or an error message otherwise. + If ``RESULT`` is not specified and the operation fails, an error is emitted. + +``NO_REPLACE`` + If the ``<newname>`` path already exists, do not replace it. + If ``RESULT <result>`` is used, the result variable will be + set to ``NO_REPLACE``. Otherwise, an error is emitted. + +.. _COPY_FILE: + +.. code-block:: cmake + + file(COPY_FILE <oldname> <newname> + [RESULT <result>] + [ONLY_IF_DIFFERENT]) + +Copy a file from ``<oldname>`` to ``<newname>``. Directories are not +supported. Symlinks are ignored and ``<oldfile>``'s content is read and +written to ``<newname>`` as a new file. + +The options are: + +``RESULT <result>`` + Set ``<result>`` variable to ``0`` on success or an error message otherwise. + If ``RESULT`` is not specified and the operation fails, an error is emitted. + +``ONLY_IF_DIFFERENT`` + If the ``<newname>`` path already exists, do not replace it if it is the + same as ``<oldname>``. Otherwise, an error is emitted. + +.. _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. Relative input paths are evaluated with respect +to the current source directory. + +.. versionchanged:: 3.15 + Empty input paths are ignored with a warning. Previous versions of CMake + interpreted empty string as a relative path with respect to the current + directory and removed its contents. + +.. _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> + [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS] + [FILE_PERMISSIONS <permissions>...] + [DIRECTORY_PERMISSIONS <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``). + +.. versionadded:: 3.15 + 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>) + +.. versionadded:: 3.14 + +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>) + +.. versionadded:: 3.14 + +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]) + +.. versionadded:: 3.14 + +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. + +.. _CHMOD: + +.. code-block:: cmake + + file(CHMOD <files>... <directories>... + [PERMISSIONS <permissions>...] + [FILE_PERMISSIONS <permissions>...] + [DIRECTORY_PERMISSIONS <permissions>...]) + +.. versionadded:: 3.19 + +Set the permissions for the ``<files>...`` and ``<directories>...`` specified. +Valid permissions are ``OWNER_READ``, ``OWNER_WRITE``, ``OWNER_EXECUTE``, +``GROUP_READ``, ``GROUP_WRITE``, ``GROUP_EXECUTE``, ``WORLD_READ``, +``WORLD_WRITE``, ``WORLD_EXECUTE``, ``SETUID``, ``SETGID``. + +Valid combination of keywords are: + +``PERMISSIONS`` + All items are changed. + +``FILE_PERMISSIONS`` + Only files are changed. + +``DIRECTORY_PERMISSIONS`` + Only directories are changed. + +``PERMISSIONS`` and ``FILE_PERMISSIONS`` + ``FILE_PERMISSIONS`` overrides ``PERMISSIONS`` for files. + +``PERMISSIONS`` and ``DIRECTORY_PERMISSIONS`` + ``DIRECTORY_PERMISSIONS`` overrides ``PERMISSIONS`` for directories. + +``FILE_PERMISSIONS`` and ``DIRECTORY_PERMISSIONS`` + Use ``FILE_PERMISSIONS`` for files and ``DIRECTORY_PERMISSIONS`` for + directories. + + +.. _CHMOD_RECURSE: + +.. code-block:: cmake + + file(CHMOD_RECURSE <files>... <directories>... + [PERMISSIONS <permissions>...] + [FILE_PERMISSIONS <permissions>...] + [DIRECTORY_PERMISSIONS <permissions>...]) + +.. versionadded:: 3.19 + +Same as `CHMOD`_, but change the permissions of files and directories present in +the ``<directories>...`` recursively. + +Path Conversion +^^^^^^^^^^^^^^^ + +.. _REAL_PATH: + +.. code-block:: cmake + + file(REAL_PATH <path> <out-var> [BASE_DIRECTORY <dir>]) + +.. versionadded:: 3.19 + +Compute the absolute path to an existing file or directory with symlinks +resolved. + +If the provided ``<path>`` is a relative path, it is evaluated relative to the +given base directory ``<dir>``. If no base directory is provided, the default +base directory will be :variable:`CMAKE_CURRENT_SOURCE_DIR`. + +.. _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>) + +The ``TO_CMAKE_PATH`` mode converts a native ``<path>`` into a cmake-style +path with forward-slashes (``/``). The input can be a single path or a +system search path like ``$ENV{PATH}``. A search path will be converted +to a cmake-style list separated by ``;`` characters. + +The ``TO_NATIVE_PATH`` mode converts a cmake-style ``<path>`` into a native +path with platform-specific slashes (``\`` on Windows hosts 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>...]) + +The ``DOWNLOAD`` subcommand downloads the given ``<url>`` to a local ``<file>``. +The ``UPLOAD`` mode uploads a local ``<file>`` to a given ``<url>``. + +.. versionadded:: 3.19 + If ``<file>`` is not specified for ``file(DOWNLOAD)``, the file is not saved. + This can be useful if you want to know if a file can be downloaded (for example, + to check that it exists) without actually saving it anywhere. + +Options to both ``DOWNLOAD`` and ``UPLOAD`` are: + +``INACTIVITY_TIMEOUT <seconds>`` + Terminate the operation after a period of inactivity. + +``LOG <variable>`` + Store a human-readable log of the operation in a variable. + +``SHOW_PROGRESS`` + Print progress information as status messages until the operation is + complete. + +``STATUS <variable>`` + Store the resulting status of the operation in a variable. + The status is a ``;`` separated list of length 2. + The first element is the numeric return value for the operation, + and the second element is a string value for the error. + A ``0`` numeric error means no error in the operation. + +``TIMEOUT <seconds>`` + Terminate the operation after a given total time has elapsed. + +``USERPWD <username>:<password>`` + .. versionadded:: 3.7 + + Set username and password for operation. + +``HTTPHEADER <HTTP-header>`` + .. versionadded:: 3.7 + + HTTP header for operation. Suboption can be repeated several times. + +``NETRC <level>`` + .. versionadded:: 3.11 + + 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>`` + .. versionadded:: 3.11 + + 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. + +``TLS_VERIFY <ON|OFF>`` + Specify whether to verify the server certificate for ``https://`` URLs. + The default is to *not* verify. + + .. versionadded:: 3.18 + Added support to ``file(UPLOAD)``. + +``TLS_CAINFO <file>`` + Specify a custom Certificate Authority file for ``https://`` URLs. + + .. versionadded:: 3.18 + Added support to ``file(UPLOAD)``. + +For ``https://`` URLs CMake must be built with OpenSSL support. ``TLS/SSL`` +certificates are not checked by default. Set ``TLS_VERIFY`` to ``ON`` to +check certificates. If neither ``TLS`` option is given CMake will check +variables ``CMAKE_TLS_VERIFY`` and ``CMAKE_TLS_CAINFO``, respectively. + +Additional options to ``DOWNLOAD`` are: + +``EXPECTED_HASH ALGO=<value>`` + + Verify that the downloaded content hash matches the expected value, where + ``ALGO`` is one of the algorithms supported by ``file(<HASH>)``. + If it does not match, the operation fails with an error. It is an error to + specify this if ``DOWNLOAD`` is not given a ``<file>``. + +``EXPECTED_MD5 <value>`` + Historical short-hand for ``EXPECTED_HASH MD5=<value>``. It is an error to + specify this if ``DOWNLOAD`` is not given a ``<file>``. + +Locking +^^^^^^^ + +.. _LOCK: + +.. code-block:: cmake + + file(LOCK <path> [DIRECTORY] [RELEASE] + [GUARD <FUNCTION|FILE|PROCESS>] + [RESULT_VARIABLE <variable>] + [TIMEOUT <seconds>]) + +.. versionadded:: 3.2 + +Lock a file specified by ``<path>`` if no ``DIRECTORY`` option present and file +``<path>/cmake.lock`` otherwise. File will be locked for scope defined by +``GUARD`` option (default value is ``PROCESS``). ``RELEASE`` option can be used +to unlock file explicitly. If option ``TIMEOUT`` is not specified CMake will +wait until lock succeed or until fatal error occurs. If ``TIMEOUT`` is set to +``0`` lock will be tried once and result will be reported immediately. If +``TIMEOUT`` is not ``0`` CMake will try to lock file for the period specified +by ``<seconds>`` value. Any errors will be interpreted as fatal if there is no +``RESULT_VARIABLE`` option. Otherwise result will be stored in ``<variable>`` +and will be ``0`` on success or error message on failure. + +Note that lock is advisory - there is no guarantee that other processes will +respect this lock, i.e. lock synchronize two or more CMake instances sharing +some modifiable resources. Similar logic applied to ``DIRECTORY`` option - +locking parent directory doesn't prevent other ``LOCK`` commands to lock any +child directory or file. + +Trying to lock file twice is not allowed. Any intermediate directories and +file itself will be created if they not exist. ``GUARD`` and ``TIMEOUT`` +options ignored on ``RELEASE`` operation. + +Archiving +^^^^^^^^^ + +.. _ARCHIVE_CREATE: + +.. code-block:: cmake + + file(ARCHIVE_CREATE OUTPUT <archive> + PATHS <paths>... + [FORMAT <format>] + [COMPRESSION <compression> [COMPRESSION_LEVEL <compression-level>]] + [MTIME <mtime>] + [VERBOSE]) + +.. versionadded:: 3.18 + +Creates the specified ``<archive>`` file with the files and directories +listed in ``<paths>``. Note that ``<paths>`` must list actual files or +directories, wildcards are not supported. + +Use the ``FORMAT`` option to specify the archive format. Supported values +for ``<format>`` are ``7zip``, ``gnutar``, ``pax``, ``paxr``, ``raw`` and +``zip``. If ``FORMAT`` is not given, the default format is ``paxr``. + +Some archive formats allow the type of compression to be specified. +The ``7zip`` and ``zip`` archive formats already imply a specific type of +compression. The other formats use no compression by default, but can be +directed to do so with the ``COMPRESSION`` option. Valid values for +``<compression>`` are ``None``, ``BZip2``, ``GZip``, ``XZ``, and ``Zstd``. + +.. versionadded:: 3.19 + The compression level can be specified with the ``COMPRESSION_LEVEL`` option. + The ``<compression-level>`` should be between 0-9, with the default being 0. + The ``COMPRESSION`` option must be present when ``COMPRESSION_LEVEL`` is given. + +.. note:: + With ``FORMAT`` set to ``raw`` only one file will be compressed with the + compression type specified by ``COMPRESSION``. + +The ``VERBOSE`` option enables verbose output for the archive operation. + +To specify the modification time recorded in tarball entries, use +the ``MTIME`` option. + +.. _ARCHIVE_EXTRACT: + +.. code-block:: cmake + + file(ARCHIVE_EXTRACT INPUT <archive> + [DESTINATION <dir>] + [PATTERNS <patterns>...] + [LIST_ONLY] + [VERBOSE]) + +.. versionadded:: 3.18 + +Extracts or lists the content of the specified ``<archive>``. + +The directory where the content of the archive will be extracted to can +be specified using the ``DESTINATION`` option. If the directory does not +exist, it will be created. If ``DESTINATION`` is not given, the current +binary directory will be used. + +If required, you may select which files and directories to list or extract +from the archive using the specified ``<patterns>``. Wildcards are supported. +If the ``PATTERNS`` option is not given, the entire archive will be listed or +extracted. + +``LIST_ONLY`` will list the files in the archive rather than extract them. + +With ``VERBOSE``, the command will produce verbose output. diff --git a/Help/command/find_file.rst b/Help/command/find_file.rst new file mode 100644 index 0000000..39dfb85 --- /dev/null +++ b/Help/command/find_file.rst @@ -0,0 +1,37 @@ +find_file +--------- + +.. |FIND_XXX| replace:: find_file +.. |NAMES| replace:: NAMES name1 [name2 ...] +.. |SEARCH_XXX| replace:: full path to a file +.. |SEARCH_XXX_DESC| replace:: full path to named 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:: The directories in ``INCLUDE`` + and ``PATH``. +.. |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` + is set, and |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| +.. |CMAKE_SYSTEM_XXX_PATH| replace:: + :variable:`CMAKE_SYSTEM_INCLUDE_PATH` +.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: + :variable:`CMAKE_SYSTEM_FRAMEWORK_PATH` + +.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace:: + :variable:`CMAKE_FIND_ROOT_PATH_MODE_INCLUDE` + +.. include:: FIND_XXX.txt diff --git a/Help/command/find_library.rst b/Help/command/find_library.rst new file mode 100644 index 0000000..ab957ce --- /dev/null +++ b/Help/command/find_library.rst @@ -0,0 +1,82 @@ +find_library +------------ + +.. |FIND_XXX| replace:: find_library +.. |NAMES| replace:: NAMES name1 [name2 ...] [NAMES_PER_DIR] +.. |SEARCH_XXX| replace:: library +.. |SEARCH_XXX_DESC| replace:: 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:: The directories in ``LIB`` + and ``PATH``. +.. |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, + and |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| +.. |CMAKE_SYSTEM_XXX_PATH| replace:: + :variable:`CMAKE_SYSTEM_LIBRARY_PATH` +.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: + :variable:`CMAKE_SYSTEM_FRAMEWORK_PATH` + +.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace:: + :variable:`CMAKE_FIND_ROOT_PATH_MODE_LIBRARY` + +.. include:: FIND_XXX.txt + +When more than one value is given to the ``NAMES`` option this command by +default will consider one name at a time and search every directory +for it. The ``NAMES_PER_DIR`` option tells this command to consider one +directory at a time and search for all names in it. + +Each library name given to the ``NAMES`` option is first considered +as a library file name and then considered with platform-specific +prefixes (e.g. ``lib``) and suffixes (e.g. ``.so``). Therefore one +may specify library file names such as ``libfoo.a`` directly. +This can be used to locate static libraries on UNIX-like systems. + +If the library found is a framework, then ``<VAR>`` will be set to the full +path to the framework ``<fullPath>/A.framework``. When a full path to a +framework is used as a library, CMake will use a ``-framework A``, and a +``-F<fullPath>`` to link the framework to the target. + +If the :variable:`CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX` variable is set all +search paths will be tested as normal, with the suffix appended, and with +all matches of ``lib/`` replaced with +``lib${CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX}/``. This variable overrides +the :prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS`, +:prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS`, +and :prop_gbl:`FIND_LIBRARY_USE_LIB64_PATHS` global properties. + +If the :prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS` global property is set +all search paths will be tested as normal, with ``32/`` appended, and +with all matches of ``lib/`` replaced with ``lib32/``. This property is +automatically set for the platforms that are known to need it if at +least one of the languages supported by the :command:`project` command +is enabled. + +If the :prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS` global property is set +all search paths will be tested as normal, with ``x32/`` appended, and +with all matches of ``lib/`` replaced with ``libx32/``. This property is +automatically set for the platforms that are known to need it if at +least one of the languages supported by the :command:`project` command +is enabled. + +If the :prop_gbl:`FIND_LIBRARY_USE_LIB64_PATHS` global property is set +all search paths will be tested as normal, with ``64/`` appended, and +with all matches of ``lib/`` replaced with ``lib64/``. This property is +automatically set for the platforms that are known to need it if at +least one of the languages supported by the :command:`project` command +is enabled. diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst new file mode 100644 index 0000000..3dfd62f --- /dev/null +++ b/Help/command/find_package.rst @@ -0,0 +1,540 @@ +find_package +------------ + +.. only:: html + + .. contents:: + +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. ``<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 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). +Additional optional components may be listed after +``OPTIONAL_COMPONENTS``. Available components and their influence on +whether a package is considered to be found are defined by the target +package. + +.. _FIND_PACKAGE_VERSION_FORMAT: + +The ``[version]`` argument requests a version with which the package found +should be compatible. There are two possible forms in which it may be +specified: + + * A single version with the format ``major[.minor[.patch[.tweak]]]``. + * A version range with the format ``versionMin...[<]versionMax`` where + ``versionMin`` and ``versionMax`` have the same format as the single + version. By default, both end points are included. By specifying ``<``, + the upper end point will be excluded. Version ranges are only supported + with CMake 3.19 or later. + +The ``EXACT`` option requests that the version be matched exactly. This option +is incompatible with the specification of a version range. + +If no ``[version]`` and/or component list is given to a recursive invocation +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 (see the `Version Selection`_ section below). +When a version range is specified but the package is only designed to expect +a single version, the package will ignore the upper end point of the range and +only take the single version at the lower end of the range into account. + +See the :command:`cmake_policy` command documentation for discussion +of the ``NO_POLICY_SCOPE`` option. + +The command has two modes by which it searches for packages: "Module" +mode and "Config" mode. The above signature selects Module mode. +If no module is found the command falls back to Config mode, described +below. This fall back is disabled if the ``MODULE`` option is given. + +In Module mode, CMake searches for a file called ``Find<PackageName>.cmake``. +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 specified 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 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 ...]] + [CONFIGS config1 [config2 ...]] + [HINTS path1 [path2 ... ]] + [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] + [NO_CMAKE_PACKAGE_REGISTRY] + [NO_CMAKE_BUILDS_PATH] # Deprecated; does nothing. + [NO_CMAKE_SYSTEM_PATH] + [NO_CMAKE_SYSTEM_PACKAGE_REGISTRY] + [CMAKE_FIND_ROOT_PATH_BOTH | + ONLY_CMAKE_FIND_ROOT_PATH | + NO_CMAKE_FIND_ROOT_PATH]) + +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 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 ``<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 ``<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 ``<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 +``<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 (see :ref:`format specification <FIND_PACKAGE_VERSION_FORMAT>`). If the +``EXACT`` option is given, only a version of the package claiming an exact match +of the requested version may be found. CMake does not establish any +convention for the meaning of version numbers. Package version +numbers are checked by "version" files provided by the packages +themselves. For a candidate package configuration file +``<config-file>.cmake`` the corresponding version file is located next +to it and named either ``<config-file>-version.cmake`` or +``<config-file>Version.cmake``. If no such version file is available +then the configuration file is assumed to not be compatible with any +requested version. A basic version file containing generic version +matching code can be created using the +:module:`CMakePackageConfigHelpers` module. When a version file +is found it is loaded to check the requested version number. The +version file is loaded in a nested scope in which the following +variables have been defined: + +``PACKAGE_FIND_NAME`` + The ``<PackageName>`` +``PACKAGE_FIND_VERSION`` + Full requested version string +``PACKAGE_FIND_VERSION_MAJOR`` + Major version if requested, else 0 +``PACKAGE_FIND_VERSION_MINOR`` + Minor version if requested, else 0 +``PACKAGE_FIND_VERSION_PATCH`` + Patch version if requested, else 0 +``PACKAGE_FIND_VERSION_TWEAK`` + Tweak version if requested, else 0 +``PACKAGE_FIND_VERSION_COUNT`` + Number of version components, 0 to 4 + +When a version range is specified, the above version variables will hold +values based on the lower end of the version range. This is to preserve +compatibility with packages that have not been implemented to expect version +ranges. In addition, the version range will be described by the following +variables: + +``PACKAGE_FIND_VERSION_RANGE`` + Full requested version range string +``PACKAGE_FIND_VERSION_RANGE_MIN`` + This specifies whether the lower end point of the version range should be + included or excluded. Currently, the only supported value for this variable + is ``INCLUDE``. +``PACKAGE_FIND_VERSION_RANGE_MAX`` + This specifies whether the upper end point of the version range should be + included or excluded. The supported values for this variable are + ``INCLUDE`` and ``EXCLUDE``. + +``PACKAGE_FIND_VERSION_MIN`` + Full requested version string of the lower end point of the range +``PACKAGE_FIND_VERSION_MIN_MAJOR`` + Major version of the lower end point if requested, else 0 +``PACKAGE_FIND_VERSION_MIN_MINOR`` + Minor version of the lower end point if requested, else 0 +``PACKAGE_FIND_VERSION_MIN_PATCH`` + Patch version of the lower end point if requested, else 0 +``PACKAGE_FIND_VERSION_MIN_TWEAK`` + Tweak version of the lower end point if requested, else 0 +``PACKAGE_FIND_VERSION_MIN_COUNT`` + Number of version components of the lower end point, 0 to 4 + +``PACKAGE_FIND_VERSION_MAX`` + Full requested version string of the upper end point of the range +``PACKAGE_FIND_VERSION_MAX_MAJOR`` + Major version of the upper end point if requested, else 0 +``PACKAGE_FIND_VERSION_MAX_MINOR`` + Minor version of the upper end point if requested, else 0 +``PACKAGE_FIND_VERSION_MAX_PATCH`` + Patch version of the upper end point if requested, else 0 +``PACKAGE_FIND_VERSION_MAX_TWEAK`` + Tweak version of the upper end point if requested, else 0 +``PACKAGE_FIND_VERSION_MAX_COUNT`` + Number of version components of the upper end point, 0 to 4 + +Regardless of whether a single version or a version range is specified, the +variable ``PACKAGE_FIND_VERSION_COMPLETE`` will be defined and will hold +the full requested version string as specified. + +The version file checks whether it satisfies the requested version and +sets these variables: + +``PACKAGE_VERSION`` + Full provided version string +``PACKAGE_VERSION_EXACT`` + True if version is exact match +``PACKAGE_VERSION_COMPATIBLE`` + True if version is compatible +``PACKAGE_VERSION_UNSUITABLE`` + True if unsuitable as any version + +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 +is acceptable the following variables are set: + +``<PackageName>_VERSION`` + Full provided version string +``<PackageName>_VERSION_MAJOR`` + Major version if provided, else 0 +``<PackageName>_VERSION_MINOR`` + Minor version if provided, else 0 +``<PackageName>_VERSION_PATCH`` + Patch version if provided, else 0 +``<PackageName>_VERSION_TWEAK`` + Tweak version if provided, else 0 +``<PackageName>_VERSION_COUNT`` + Number of version components, 0 to 4 + +and the corresponding package configuration file is loaded. +When multiple package configuration files are available whose version files +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 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 + +.. code-block:: cmake + + SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL) + SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC) + +before calling ``find_package``. + +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:: + + <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 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) + <prefix>/<name>.framework/Resources/CMake/ (A) + <prefix>/<name>.framework/Versions/*/Resources/ (A) + <prefix>/<name>.framework/Versions/*/Resources/CMake/ (A) + <prefix>/<name>.app/Contents/Resources/ (A) + <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 (``<PackageName>`` or names given by ``NAMES``). + +Paths with ``lib/<arch>`` are enabled if the +: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 +Windows where the prefix may point at the top of an application's +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 +intended for installations on Apple platforms. The +:variable:`CMAKE_FIND_FRAMEWORK` and :variable:`CMAKE_FIND_APPBUNDLE` +variables determine the order of preference. + +The set of installation prefixes is constructed using the following +steps. If ``NO_DEFAULT_PATH`` is specified all ``NO_*`` options are +enabled. + +1. .. versionadded:: 3.12 + 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:`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``: + + * :variable:`CMAKE_PREFIX_PATH` + * :variable:`CMAKE_FRAMEWORK_PATH` + * :variable:`CMAKE_APPBUNDLE_PATH` + +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 or by setting + the :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` to ``FALSE``: + + * ``<PackageName>_DIR`` + * :envvar:`CMAKE_PREFIX_PATH` + * ``CMAKE_FRAMEWORK_PATH`` + * ``CMAKE_APPBUNDLE_PATH`` + +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. + +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`` + +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 :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. + +7. Search cmake variables defined in the Platform files for the + current system. This can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is + passed or by setting the :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH` + to ``FALSE``: + + * :variable:`CMAKE_SYSTEM_PREFIX_PATH` + * :variable:`CMAKE_SYSTEM_FRAMEWORK_PATH` + * :variable:`CMAKE_SYSTEM_APPBUNDLE_PATH` + + The platform paths that these variables contain are locations that + typically include installed software. An example being ``/usr/local`` for + UNIX based platforms. + +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 :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. + +9. Search paths specified by the ``PATHS`` option. These are typically + hard-coded guesses. + +.. versionadded:: 3.16 + Added the ``CMAKE_FIND_USE_<CATEGORY>_PATH`` variables to globally disable + various search locations. + +.. |FIND_XXX| replace:: find_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 ``<PackageName>`` which is searched for +``<PackageName>_FIND_REQUIRED`` + True if ``REQUIRED`` option was given +``<PackageName>_FIND_QUIETLY`` + True if ``QUIET`` option was given +``<PackageName>_FIND_VERSION`` + Full requested version string +``<PackageName>_FIND_VERSION_MAJOR`` + Major version if requested, else 0 +``<PackageName>_FIND_VERSION_MINOR`` + Minor version if requested, else 0 +``<PackageName>_FIND_VERSION_PATCH`` + Patch version if requested, else 0 +``<PackageName>_FIND_VERSION_TWEAK`` + Tweak version if requested, else 0 +``<PackageName>_FIND_VERSION_COUNT`` + Number of version components, 0 to 4 +``<PackageName>_FIND_VERSION_EXACT`` + True if ``EXACT`` option was given +``<PackageName>_FIND_COMPONENTS`` + List of requested components +``<PackageName>_FIND_REQUIRED_<c>`` + True if component ``<c>`` is required, + false if component ``<c>`` is optional + +When a version range is specified, the above version variables will hold +values based on the lower end of the version range. This is to preserve +compatibility with packages that have not been implemented to expect version +ranges. In addition, the version range will be described by the following +variables: + +``<PackageName>_FIND_VERSION_RANGE`` + Full requested version range string +``<PackageName>_FIND_VERSION_RANGE_MIN`` + This specifies whether the lower end point of the version range is + included or excluded. Currently, ``INCLUDE`` is the only supported value. +``<PackageName>_FIND_VERSION_RANGE_MAX`` + This specifies whether the upper end point of the version range is + included or excluded. The possible values for this variable are + ``INCLUDE`` or ``EXCLUDE``. + +``<PackageName>_FIND_VERSION_MIN`` + Full requested version string of the lower end point of the range +``<PackageName>_FIND_VERSION_MIN_MAJOR`` + Major version of the lower end point if requested, else 0 +``<PackageName>_FIND_VERSION_MIN_MINOR`` + Minor version of the lower end point if requested, else 0 +``<PackageName>_FIND_VERSION_MIN_PATCH`` + Patch version of the lower end point if requested, else 0 +``<PackageName>_FIND_VERSION_MIN_TWEAK`` + Tweak version of the lower end point if requested, else 0 +``<PackageName>_FIND_VERSION_MIN_COUNT`` + Number of version components of the lower end point, 0 to 4 + +``<PackageName>_FIND_VERSION_MAX`` + Full requested version string of the upper end point of the range +``<PackageName>_FIND_VERSION_MAX_MAJOR`` + Major version of the upper end point if requested, else 0 +``<PackageName>_FIND_VERSION_MAX_MINOR`` + Minor version of the upper end point if requested, else 0 +``<PackageName>_FIND_VERSION_MAX_PATCH`` + Patch version of the upper end point if requested, else 0 +``<PackageName>_FIND_VERSION_MAX_TWEAK`` + Tweak version of the upper end point if requested, else 0 +``<PackageName>_FIND_VERSION_MAX_COUNT`` + Number of version components of the upper end point, 0 to 4 + +Regardless of whether a single version or a version range is specified, the +variable ``<PackageName>_FIND_VERSION_COMPLETE`` will be defined and will hold +the full requested version string as specified. + +In Module mode the loaded find module is responsible to honor the +request detailed by these variables; see the find module for details. +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 +``<PackageName>_FOUND`` to false to tell ``find_package`` that component +requirements are not satisfied. diff --git a/Help/command/find_path.rst b/Help/command/find_path.rst new file mode 100644 index 0000000..ec66771 --- /dev/null +++ b/Help/command/find_path.rst @@ -0,0 +1,42 @@ +find_path +--------- + +.. |FIND_XXX| replace:: find_path +.. |NAMES| replace:: NAMES name1 [name2 ...] +.. |SEARCH_XXX| replace:: file in a directory +.. |SEARCH_XXX_DESC| replace:: directory containing the named 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:: The directories in ``INCLUDE`` + and ``PATH``. +.. |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` + is set, and |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| +.. |CMAKE_SYSTEM_XXX_PATH| replace:: + :variable:`CMAKE_SYSTEM_INCLUDE_PATH` +.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: + :variable:`CMAKE_SYSTEM_FRAMEWORK_PATH` + +.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace:: + :variable:`CMAKE_FIND_ROOT_PATH_MODE_INCLUDE` + +.. include:: FIND_XXX.txt + +When searching for frameworks, if the file is specified as ``A/b.h``, then +the framework search will look for ``A.framework/Headers/b.h``. If that +is found the path will be set to the path to the framework. CMake +will convert this to the correct ``-F`` option to include the file. diff --git a/Help/command/find_program.rst b/Help/command/find_program.rst new file mode 100644 index 0000000..e2ff693 --- /dev/null +++ b/Help/command/find_program.rst @@ -0,0 +1,36 @@ +find_program +------------ + +.. |FIND_XXX| replace:: find_program +.. |NAMES| replace:: NAMES name1 [name2 ...] [NAMES_PER_DIR] +.. |SEARCH_XXX| replace:: program +.. |SEARCH_XXX_DESC| replace:: 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:: 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| +.. |CMAKE_SYSTEM_XXX_PATH| replace:: + :variable:`CMAKE_SYSTEM_PROGRAM_PATH` +.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: + :variable:`CMAKE_SYSTEM_APPBUNDLE_PATH` + +.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace:: + :variable:`CMAKE_FIND_ROOT_PATH_MODE_PROGRAM` + +.. include:: FIND_XXX.txt + +When more than one value is given to the ``NAMES`` option this command by +default will consider one name at a time and search every directory +for it. The ``NAMES_PER_DIR`` option tells this command to consider one +directory at a time and search for all names in it. diff --git a/Help/command/fltk_wrap_ui.rst b/Help/command/fltk_wrap_ui.rst new file mode 100644 index 0000000..6675272 --- /dev/null +++ b/Help/command/fltk_wrap_ui.rst @@ -0,0 +1,14 @@ +fltk_wrap_ui +------------ + +Create FLTK user interfaces Wrappers. + +.. code-block:: cmake + + fltk_wrap_ui(resultingLibraryName source1 + source2 ... sourceN ) + +Produce .h and .cxx files for all the .fl and .fld files listed. The +resulting .h and .cxx files will be added to a variable named +``resultingLibraryName_FLTK_UI_SRCS`` which should be added to your +library. diff --git a/Help/command/foreach.rst b/Help/command/foreach.rst new file mode 100644 index 0000000..8de6deb --- /dev/null +++ b/Help/command/foreach.rst @@ -0,0 +1,129 @@ +foreach +------- + +Evaluate a group of commands for each value in a list. + +.. code-block:: cmake + + foreach(<loop_var> <items>) + <commands> + endforeach() + +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. + +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. + +.. code-block:: cmake + + foreach(<loop_var> RANGE <stop>) + +In this variant, ``foreach`` iterates over the numbers +0, 1, ... up to (and including) the nonnegative integer ``<stop>``. + +.. 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>]]) + +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 +:: + + -- X=0 + -- X=1 + -- X=2 + -- X=3 + -- X=4 5 + -- X=6 + -- X=7 + -- X=8 + + +.. code-block:: cmake + + foreach(<loop_var>... IN ZIP_LISTS <lists>) + +.. versionadded:: 3.17 + +In this variant, ``<lists>`` is a whitespace or semicolon +separated list of list-valued variables. The ``foreach`` +command iterates over each list simultaneously setting the +iteration variables as follows: + +- if the only ``loop_var`` given, then it sets a series of + ``loop_var_N`` variables to the current item from the + corresponding list; +- if multiple variable names passed, their count should match + the lists variables count; +- if any of the lists are shorter, the corresponding iteration + variable is not defined for the current iteration. + +.. code-block:: cmake + + list(APPEND English one two three four) + list(APPEND Bahasa satu dua tiga) + + foreach(num IN ZIP_LISTS English Bahasa) + message(STATUS "num_0=${num_0}, num_1=${num_1}") + endforeach() + + foreach(en ba IN ZIP_LISTS English Bahasa) + message(STATUS "en=${en}, ba=${ba}") + endforeach() + +yields +:: + + -- num_0=one, num_1=satu + -- num_0=two, num_1=dua + -- num_0=three, num_1=tiga + -- num_0=four, num_1= + -- en=one, ba=satu + -- en=two, ba=dua + -- en=three, ba=tiga + -- en=four, ba= diff --git a/Help/command/function.rst b/Help/command/function.rst new file mode 100644 index 0000000..3d25aa4 --- /dev/null +++ b/Help/command/function.rst @@ -0,0 +1,75 @@ +function +-------- + +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() + cmake_language(CALL 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. + +.. versionadded:: 3.18 + The :command:`cmake_language(CALL ...)` command can also be used to + invoke the function. + +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 new file mode 100644 index 0000000..96764a3 --- /dev/null +++ b/Help/command/get_cmake_property.rst @@ -0,0 +1,20 @@ +get_cmake_property +------------------ + +Get a global property of the CMake instance. + +.. code-block:: cmake + + get_cmake_property(<var> <property>) + +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. + +In addition to global properties, this command (for historical reasons) +also supports the :prop_dir:`VARIABLES` and :prop_dir:`MACROS` directory +properties. It also supports a special ``COMPONENTS`` global property that +lists the components given to the :command:`install` command. diff --git a/Help/command/get_directory_property.rst b/Help/command/get_directory_property.rst new file mode 100644 index 0000000..0ccbfb0 --- /dev/null +++ b/Help/command/get_directory_property.rst @@ -0,0 +1,36 @@ +get_directory_property +---------------------- + +Get a property of ``DIRECTORY`` scope. + +.. code-block:: cmake + + get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>) + +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. +Relative paths are treated as relative to the +current source directory. CMake must already know about the directory, +either by having added it through a call to :command:`add_subdirectory` +or being the top level directory. + +.. versionadded:: 3.19 + ``<dir>`` may reference a binary directory. + +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>) + +Get a variable definition from a directory. This form is useful to +get a variable definition from another directory. + +See also the more general :command:`get_property` command. diff --git a/Help/command/get_filename_component.rst b/Help/command/get_filename_component.rst new file mode 100644 index 0000000..be9d00a --- /dev/null +++ b/Help/command/get_filename_component.rst @@ -0,0 +1,65 @@ +get_filename_component +---------------------- + +Get a specific component of a full filename. + +.. versionchanged:: 3.19 + This command been superseded by :command:`cmake_path` command, except + ``REALPATH`` now offered by :ref:`file(REAL_PATH) <REAL_PATH>` command and + ``PROGRAM`` now available in :command:`separate_arguments(PROGRAM)` command. + +.. code-block:: cmake + + get_filename_component(<var> <FileName> <mode> [CACHE]) + +Sets ``<var>`` to a component of ``<FileName>``, where ``<mode>`` is one of: + +:: + + DIRECTORY = Directory without file name + NAME = File name without directory + EXT = File name longest extension (.b.c from d/a.b.c) + NAME_WE = File name with neither the directory nor the longest extension + LAST_EXT = File name last extension (.c from d/a.b.c) + NAME_WLE = File name with neither the directory nor the last extension + PATH = Legacy alias for DIRECTORY (use for CMake <= 2.8.11) + +.. versionadded:: 3.14 + Added the ``LAST_EXT`` and ``NAME_WLE`` modes. + +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> <mode> [BASE_DIR <dir>] [CACHE]) + +.. versionadded:: 3.4 + +Sets ``<var>`` to the absolute path of ``<FileName>``, where ``<mode>`` is one +of: + +:: + + ABSOLUTE = Full path to file + 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 ``<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 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]) + +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 +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 new file mode 100644 index 0000000..f77d8af --- /dev/null +++ b/Help/command/get_property.rst @@ -0,0 +1,101 @@ +get_property +------------ + +Get a property. + +.. code-block:: cmake + + get_property(<variable> + <GLOBAL | + DIRECTORY [<dir>] | + TARGET <target> | + SOURCE <source> | + [DIRECTORY <dir> | TARGET_DIRECTORY <target>] | + INSTALL <file> | + TEST <test> | + CACHE <entry> | + VARIABLE > + PROPERTY <name> + [SET | DEFINED | BRIEF_DOCS | FULL_DOCS]) + +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 the + full or relative path ``<dir>``. + Relative paths are treated as relative to the current source directory. + See also the :command:`get_directory_property` command. + + .. versionadded:: 3.19 + ``<dir>`` may reference a binary directory. + +``TARGET`` + Scope must name one existing target. + See also the :command:`get_target_property` command. + +``SOURCE`` + Scope must name one source file. By default, the source file's property + will be read from the current source directory's scope. + + .. versionadded:: 3.18 + Directory scope can be overridden with one of the following sub-options: + + ``DIRECTORY <dir>`` + The source file property will be read from the ``<dir>`` directory's + scope. CMake must already know about + the directory, either by having added it through a call + to :command:`add_subdirectory` or ``<dir>`` being the top level directory. + Relative paths are treated as relative to the current source directory. + + .. versionadded:: 3.19 + ``<dir>`` may reference a binary directory. + + ``TARGET_DIRECTORY <target>`` + The source file property will be read from the directory scope in which + ``<target>`` was created (``<target>`` must therefore already exist). + + See also the :command:`get_source_file_property` command. + +``INSTALL`` + .. versionadded:: 3.1 + + Scope must name one installed file path. + +``TEST`` + Scope must name one existing test. + See also the :command:`get_test_property` command. + +``CACHE`` + Scope must name one cache entry. + +``VARIABLE`` + Scope is unique and does not accept a name. + +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, 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 +``NOTFOUND`` is returned. + +.. note:: + + The :prop_sf:`GENERATED` source file property may be globally visible. + See its documentation for details. diff --git a/Help/command/get_source_file_property.rst b/Help/command/get_source_file_property.rst new file mode 100644 index 0000000..ae41565 --- /dev/null +++ b/Help/command/get_source_file_property.rst @@ -0,0 +1,47 @@ +get_source_file_property +------------------------ + +Get a property for a source file. + +.. code-block:: cmake + + get_source_file_property(<variable> <file> + [DIRECTORY <dir> | TARGET_DIRECTORY <target>] + <property>) + +Gets a property from a source file. The value of the property is +stored in the specified ``<variable>``. 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 ``variable`` 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, ``variable`` will be set to +an empty string. + +By default, the source file's property will be read from the current source +directory's scope. + +.. versionadded:: 3.18 + Directory scope can be overridden with one of the following sub-options: + + ``DIRECTORY <dir>`` + The source file property will be read from the ``<dir>`` directory's + scope. CMake must already know about that source directory, either by + having added it through a call to :command:`add_subdirectory` or ``<dir>`` + being the top level source directory. Relative paths are treated as + relative to the current source directory. + + ``TARGET_DIRECTORY <target>`` + The source file property will be read from the directory scope in which + ``<target>`` was created (``<target>`` must therefore already exist). + +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. + +.. note:: + + The :prop_sf:`GENERATED` source file property may be globally visible. + See its documentation for details. diff --git a/Help/command/get_target_property.rst b/Help/command/get_target_property.rst new file mode 100644 index 0000000..985b1ff --- /dev/null +++ b/Help/command/get_target_property.rst @@ -0,0 +1,27 @@ +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 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 ``<VAR>-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 new file mode 100644 index 0000000..e02b9bc --- /dev/null +++ b/Help/command/get_test_property.rst @@ -0,0 +1,21 @@ +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 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 new file mode 100644 index 0000000..fbf3e36 --- /dev/null +++ b/Help/command/if.rst @@ -0,0 +1,364 @@ +if +-- + +Conditionally execute a group of commands. + +Synopsis +^^^^^^^^ + +.. code-block:: cmake + + 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`_. Then the boolean operators in the order `NOT`_, `AND`_, +and finally `OR`_. + +Basic Expressions +""""""""""""""""" + +``if(<constant>)`` + True if the constant is ``1``, ``ON``, ``YES``, ``TRUE``, ``Y``, + or a non-zero number. False if the constant is ``0``, ``OFF``, + ``NO``, ``FALSE``, ``N``, ``IGNORE``, ``NOTFOUND``, the empty string, + or ends in the suffix ``-NOTFOUND``. Named boolean constants are + case-insensitive. If the argument is not one of these specific + constants, it is treated as a variable or string and the following + signature is used. + +``if(<variable|string>)`` + 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.) + +Logic Operators +""""""""""""""" + +.. _NOT: + +``if(NOT <condition>)`` + True if the condition is not true. + +.. _AND: + +``if(<cond1> AND <cond2>)`` + True if both conditions would be considered true individually. + +.. _OR: + +``if(<cond1> OR <cond2>)`` + True if either condition would be considered true individually. + +``if((condition) AND (condition OR (condition)))`` + The conditions inside the parenthesis are evaluated first and then + the remaining condition is evaluated as in the other examples. + Where there are nested parenthesis the innermost are evaluated as part + of evaluating the condition that contains them. + +Existence Checks +"""""""""""""""" + +.. _COMMAND: + +``if(COMMAND command-name)`` + True if the given name is a command, macro or function that can be + invoked. + +``if(POLICY policy-id)`` + True if the given name is an existing policy (of the form ``CMP<NNNN>``). + +``if(TARGET target-name)`` + True if the given name is an existing logical target name created + by a call to the :command:`add_executable`, :command:`add_library`, + or :command:`add_custom_target` command that has already been invoked + (in any directory). + +``if(TEST test-name)`` + .. versionadded:: 3.3 + True if the given name is an existing test name created by the + :command:`add_test` command. + +.. _DEFINED: + +``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. + + .. versionadded:: 3.14 + Added support for ``CACHE{<name>}`` variables. + +``if(<variable|string> IN_LIST <variable>)`` + .. versionadded:: 3.3 + True if the given element is contained in the named list variable. + +File Operations +""""""""""""""" + +.. _EXISTS: + +``if(EXISTS path-to-file-or-directory)`` + True if the named file or directory exists. Behavior is well-defined + only for explicit full paths (a leading ``~/`` is not expanded as + a home directory and is considered a relative path). + 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 + exist. Behavior is well-defined only for full paths. If the file + time stamps are exactly the same, an ``IS_NEWER_THAN`` comparison returns + true, so that any dependent build operations will occur in the event + of a tie. This includes the case of passing the same file name for + both file1 and file2. + +``if(IS_DIRECTORY path-to-directory)`` + True if the given name is a directory. Behavior is well-defined only + for full paths. + +``if(IS_SYMLINK file-name)`` + True if the given name is a symbolic link. Behavior is well-defined + only for full paths. + +``if(IS_ABSOLUTE path)`` + True if the given path is an absolute path. Note the following special + cases: + + * An empty ``path`` evaluates to false. + * On Windows hosts, any ``path`` that begins with a drive letter and colon + (e.g. ``C:``), a forward slash or a backslash will evaluate to true. + This means a path like ``C:no\base\dir`` will evaluate to true, even + though the non-drive part of the path is relative. + * On non-Windows hosts, any ``path`` that begins with a tilde (``~``) + evaluates to true. + +Comparisons +""""""""""" + +.. _MATCHES: + +``if(<variable|string> MATCHES regex)`` + True if the given string or variable's value matches the given regular + condition. See :ref:`Regex Specification` for regex format. + + .. versionadded:: 3.9 + ``()`` groups are captured in :variable:`CMAKE_MATCH_<n>` variables. + +.. _LESS: + +``if(<variable|string> LESS <variable|string>)`` + True if the given string or variable's value is a valid number and less + than that on the right. + +.. _GREATER: + +``if(<variable|string> GREATER <variable|string>)`` + True if the given string or variable's value is a valid number and greater + than that on the right. + +.. _EQUAL: + +``if(<variable|string> EQUAL <variable|string>)`` + True if the given string or variable's value is a valid number and equal + to that on the right. + +.. _LESS_EQUAL: + +``if(<variable|string> LESS_EQUAL <variable|string>)`` + .. versionadded:: 3.7 + True if the given string or variable's value is a valid number and less + than or equal to that on the right. + +.. _GREATER_EQUAL: + +``if(<variable|string> GREATER_EQUAL <variable|string>)`` + .. versionadded:: 3.7 + True if the given string or variable's value is a valid number and greater + than or equal to that on the right. + +.. _STRLESS: + +``if(<variable|string> STRLESS <variable|string>)`` + True if the given string or variable's value is lexicographically less + than the string or variable on the right. + +.. _STRGREATER: + +``if(<variable|string> STRGREATER <variable|string>)`` + True if the given string or variable's value is lexicographically greater + than the string or variable on the right. + +.. _STREQUAL: + +``if(<variable|string> STREQUAL <variable|string>)`` + True if the given string or variable's value is lexicographically equal + to the string or variable on the right. + +.. _STRLESS_EQUAL: + +``if(<variable|string> STRLESS_EQUAL <variable|string>)`` + .. versionadded:: 3.7 + True if the given string or variable's value is lexicographically less + than or equal to the string or variable on the right. + +.. _STRGREATER_EQUAL: + +``if(<variable|string> STRGREATER_EQUAL <variable|string>)`` + .. versionadded:: 3.7 + True if the given string or variable's value is lexicographically greater + than or equal to the string or variable on the right. + +Version Comparisons +""""""""""""""""""" + +.. _VERSION_LESS: + +``if(<variable|string> VERSION_LESS <variable|string>)`` + Component-wise integer version number comparison (version format is + ``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. + +.. _VERSION_GREATER: + +``if(<variable|string> VERSION_GREATER <variable|string>)`` + Component-wise integer version number comparison (version format is + ``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. + +.. _VERSION_EQUAL: + +``if(<variable|string> VERSION_EQUAL <variable|string>)`` + Component-wise integer version number comparison (version format is + ``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. + +.. _VERSION_LESS_EQUAL: + +``if(<variable|string> VERSION_LESS_EQUAL <variable|string>)`` + .. versionadded:: 3.7 + Component-wise integer version number comparison (version format is + ``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. + +.. _VERSION_GREATER_EQUAL: + +``if(<variable|string> VERSION_GREATER_EQUAL <variable|string>)`` + .. versionadded:: 3.7 + Component-wise integer version number comparison (version format is + ``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. + +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 + +.. code-block:: cmake + + set(var1 OFF) + set(var2 "var1") + if(${var2}) + +appears to the if command as + +.. 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 + +.. code-block:: cmake + + 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 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 + original value is used. + +* If the left hand argument to ``MATCHES`` is missing it returns false + without error + +* Both left and right hand arguments to ``LESS``, ``GREATER``, ``EQUAL``, + ``LESS_EQUAL``, and ``GREATER_EQUAL``, are independently tested to see if + they are defined variables, if so their defined values are used otherwise + the original value is used. + +* Both left and right hand arguments to ``STRLESS``, ``STRGREATER``, + ``STREQUAL``, ``STRLESS_EQUAL``, and ``STRGREATER_EQUAL`` are independently + tested to see if they are defined variables, if so their defined values are + used otherwise the original value is used. + +* Both left and right hand arguments to ``VERSION_LESS``, + ``VERSION_GREATER``, ``VERSION_EQUAL``, ``VERSION_LESS_EQUAL``, and + ``VERSION_GREATER_EQUAL`` are independently tested to see if they are defined + variables, if so their defined values are used otherwise the original value + is used. + +* The right hand argument to ``NOT`` is tested to see if it is a boolean + constant, if so the value is used, otherwise it is assumed to be a + variable and it is dereferenced. + +* The left and right hand arguments to ``AND`` and ``OR`` are independently + tested to see if they are boolean constants, if so they are used as + such, otherwise they are assumed to be variables and are dereferenced. + +.. versionchanged:: 3.1 + To prevent ambiguity, potential variable or keyword names can be + 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 new file mode 100644 index 0000000..80968da --- /dev/null +++ b/Help/command/include.rst @@ -0,0 +1,25 @@ +include +------- + +Load and run CMake code from a file or module. + +.. code-block:: cmake + + include(<file|module> [OPTIONAL] [RESULT_VARIABLE <var>] + [NO_POLICY_SCOPE]) + +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 ``<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`, +then in the CMake module directory. There is one exception to this: if +the file which calls ``include()`` is located itself in the CMake builtin +module directory, then first the CMake builtin module directory is searched and +:variable:`CMAKE_MODULE_PATH` afterwards. See also policy :policy:`CMP0017`. + +See the :command:`cmake_policy` command documentation for discussion of the +``NO_POLICY_SCOPE`` option. diff --git a/Help/command/include_directories.rst b/Help/command/include_directories.rst new file mode 100644 index 0000000..fe281c3 --- /dev/null +++ b/Help/command/include_directories.rst @@ -0,0 +1,41 @@ +include_directories +------------------- + +Add include directories to the build. + +.. code-block:: cmake + + include_directories([AFTER|BEFORE] [SYSTEM] dir1 [dir2 ...]) + +Add the given directories to those the compiler uses to search for +include files. Relative paths are interpreted as relative to the +current source directory. + +The include directories are added to the :prop_dir:`INCLUDE_DIRECTORIES` +directory property for the current ``CMakeLists`` file. They are also +added to the :prop_tgt:`INCLUDE_DIRECTORIES` target property for each +target in the current ``CMakeLists`` file. The target property values +are the ones used by the generators. + +By default the directories specified are appended onto the current list of +directories. This default behavior can be changed by setting +:variable:`CMAKE_INCLUDE_DIRECTORIES_BEFORE` to ``ON``. By using +``AFTER`` or ``BEFORE`` explicitly, you can select between appending and +prepending, independent of the default. + +If the ``SYSTEM`` option is given, the compiler will be told the +directories are meant as system include directories on some platforms. +Signalling this setting might achieve effects such as the compiler +skipping warnings, or these fixed-install system files not being +considered in dependency calculations - see compiler docs. + +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 new file mode 100644 index 0000000..4354654 --- /dev/null +++ b/Help/command/include_external_msproject.rst @@ -0,0 +1,27 @@ +include_external_msproject +-------------------------- + +Include an external Microsoft project file in a workspace. + +.. code-block:: cmake + + include_external_msproject(projectname location + [TYPE projectTypeGUID] + [GUID projectGUID] + [PLATFORM platformName] + dep1 dep2 ...) + +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` +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 +the target platform. This is useful for projects requiring values +other than the default (e.g. WIX projects). + +.. versionadded:: 3.9 + If the imported project has different configuration names than the + current project, set the :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` + target property to specify the mapping. diff --git a/Help/command/include_guard.rst b/Help/command/include_guard.rst new file mode 100644 index 0000000..dca3b6f --- /dev/null +++ b/Help/command/include_guard.rst @@ -0,0 +1,48 @@ +include_guard +------------- + +.. versionadded:: 3.10 + +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 new file mode 100644 index 0000000..dde8378 --- /dev/null +++ b/Help/command/include_regular_expression.rst @@ -0,0 +1,18 @@ +include_regular_expression +-------------------------- + +Set the regular expression used for dependency checking. + +.. code-block:: cmake + + include_regular_expression(regex_match [regex_complain]) + +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: + +:: + + regex_match = "^.*$" (match everything) + regex_complain = "^$" (match empty string only) diff --git a/Help/command/install.rst b/Help/command/install.rst new file mode 100644 index 0000000..35207f4 --- /dev/null +++ b/Help/command/install.rst @@ -0,0 +1,762 @@ +install +------- + +Specify rules to run at install time. + +Synopsis +^^^^^^^^ + +.. parsed-literal:: + + install(`TARGETS`_ <target>... [...]) + install({`FILES`_ | `PROGRAMS`_} <file>... [...]) + install(`DIRECTORY`_ <dir>... [...]) + install(`SCRIPT`_ <file> [...]) + install(`CODE`_ <code> [...]) + install(`EXPORT`_ <export-name> [...]) + +Introduction +^^^^^^^^^^^^ + +This command generates installation rules for a project. Install rules +specified by calls to the ``install()`` command within a source directory +are executed in order during installation. + +.. versionchanged:: 3.14 + Install rules in subdirectories + added by calls to the :command:`add_subdirectory` command are interleaved + with those in the parent directory to run in the order declared (see + policy :policy:`CMP0082`). + +There are multiple signatures for this command. Some of them define +installation options for files and targets. Options common to +multiple signatures are covered here but they are valid only for +signatures that specify them. The common options are: + +``DESTINATION`` + Specify the directory on disk to which a file will be installed. + Arguments can be relative or absolute paths. + + If a relative path is given it is interpreted relative to the value + of the :variable:`CMAKE_INSTALL_PREFIX` variable. + The prefix can be relocated at install time using the ``DESTDIR`` + mechanism explained in the :variable:`CMAKE_INSTALL_PREFIX` variable + documentation. + + If an absolute path (with a leading slash or drive letter) is given + it is used verbatim. + + As absolute paths are not supported by :manual:`cpack <cpack(1)>` installer + generators, it is preferable to use relative paths throughout. + In particular, there is no need to make paths absolute by prepending + :variable:`CMAKE_INSTALL_PREFIX`; this prefix is used by default if + the DESTINATION is a relative path. + +``PERMISSIONS`` + Specify permissions for installed files. Valid permissions are + ``OWNER_READ``, ``OWNER_WRITE``, ``OWNER_EXECUTE``, ``GROUP_READ``, + ``GROUP_WRITE``, ``GROUP_EXECUTE``, ``WORLD_READ``, ``WORLD_WRITE``, + ``WORLD_EXECUTE``, ``SETUID``, and ``SETGID``. Permissions that do + not make sense on certain platforms are ignored on those platforms. + +``CONFIGURATIONS`` + Specify a list of build configurations for which the install rule + 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 + is associated, such as "runtime" or "development". During + component-specific installation only install rules associated with + the given component name will be executed. During a full installation + all components are installed unless marked with ``EXCLUDE_FROM_ALL``. + If ``COMPONENT`` is not provided a default component "Unspecified" is + created. The default component name may be controlled with the + :variable:`CMAKE_INSTALL_DEFAULT_COMPONENT_NAME` variable. + +``EXCLUDE_FROM_ALL`` + .. versionadded:: 3.6 + + Specify that the file is excluded from a full installation and only + installed as part of a component-specific installation + +``RENAME`` + Specify a name for an installed file that may be different from the + original file. Renaming is allowed only when a single file is + installed by the command. + +``OPTIONAL`` + Specify that it is not an error if the file to be installed does + not exist. + +.. versionadded:: 3.1 + Command signatures that install files may print messages during + installation. Use the :variable:`CMAKE_INSTALL_MESSAGE` variable + to control which messages are printed. + +.. versionadded:: 3.11 + 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| + PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE] + [DESTINATION <dir>] + [PERMISSIONS permissions...] + [CONFIGURATIONS [Debug|Release|...]] + [COMPONENT <component>] + [NAMELINK_COMPONENT <component>] + [OPTIONAL] [EXCLUDE_FROM_ALL] + [NAMELINK_ONLY|NAMELINK_SKIP] + ] [...] + [INCLUDES DESTINATION [<dir> ...]] + ) + +The ``TARGETS`` form specifies rules for installing targets from a +project. There are several kinds of target :ref:`Output Artifacts` +that may be installed: + +``ARCHIVE`` + Target artifacts of this kind include: + + * *Static libraries* + (except on macOS when marked as ``FRAMEWORK``, see below); + * *DLL import libraries* + (on all Windows-based systems including Cygwin; they have extension + ``.lib``, in contrast to the ``.dll`` libraries that go to ``RUNTIME``); + * On AIX, the *linker import file* created for executables with + :prop_tgt:`ENABLE_EXPORTS` enabled. + +``LIBRARY`` + Target artifacts of this kind include: + + * *Shared libraries*, except + + - DLLs (these go to ``RUNTIME``, see below), + - on macOS when marked as ``FRAMEWORK`` (see below). + +``RUNTIME`` + Target artifacts of this kind include: + + * *Executables* + (except on macOS when marked as ``MACOSX_BUNDLE``, see ``BUNDLE`` below); + * DLLs (on all Windows-based systems including Cygwin; note that the + accompanying import libraries are of kind ``ARCHIVE``). + +``OBJECTS`` + .. versionadded:: 3.9 + + Object files associated with *object libraries*. + +``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`` + .. versionadded:: 3.12 + + 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 +once to different locations. Consider hypothetical targets ``myExe``, +``mySharedLib``, and ``myStaticLib``. The code: + +.. code-block:: cmake + + install(TARGETS myExe mySharedLib myStaticLib + RUNTIME DESTINATION bin + LIBRARY DESTINATION lib + ARCHIVE DESTINATION lib/static) + install(TARGETS mySharedLib DESTINATION /some/full/path) + +will install ``myExe`` to ``<prefix>/bin`` and ``myStaticLib`` to +``<prefix>/lib/static``. On non-DLL platforms ``mySharedLib`` will be +installed to ``<prefix>/lib`` and ``/some/full/path``. On DLL platforms +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``. + +: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. + +.. versionadded:: 3.3 + 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. + +.. versionadded:: 3.13 + `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. + +Installing Files +^^^^^^^^^^^^^^^^ + +.. _`install(FILES)`: +.. _`install(PROGRAMS)`: +.. _FILES: +.. _PROGRAMS: + +.. code-block:: cmake + + install(<FILES|PROGRAMS> files... + TYPE <type> | DESTINATION <dir> + [PERMISSIONS permissions...] + [CONFIGURATIONS [Debug|Release|...]] + [COMPONENT <component>] + [RENAME <name>] [OPTIONAL] [EXCLUDE_FROM_ALL]) + +The ``FILES`` form specifies rules for installing files for a project. +File names given as relative paths are interpreted with respect to the +current source directory. Files installed by this form are by default +given permissions ``OWNER_WRITE``, ``OWNER_READ``, ``GROUP_READ``, and +``WORLD_READ`` if no ``PERMISSIONS`` argument is given. + +The ``PROGRAMS`` form is identical to the ``FILES`` form except that the +default permissions for the installed file also include ``OWNER_EXECUTE``, +``GROUP_EXECUTE``, and ``WORLD_EXECUTE``. This form is intended to install +programs that are not targets, such as shell scripts. Use the ``TARGETS`` +form to install targets built within the project. + +The list of ``files...`` given to ``FILES`` or ``PROGRAMS`` may use +"generator expressions" with the syntax ``$<...>``. See the +:manual:`cmake-generator-expressions(7)` manual for available expressions. +However, if any item begins in a generator expression it must evaluate +to a full path. + +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 + ) + +.. versionadded:: 3.4 + 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. + +.. versionadded:: 3.20 + An install rename given as a ``RENAME`` 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... + TYPE <type> | DESTINATION <dir> + [FILE_PERMISSIONS permissions...] + [DIRECTORY_PERMISSIONS permissions...] + [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER] + [CONFIGURATIONS [Debug|Release|...]] + [COMPONENT <component>] [EXCLUDE_FROM_ALL] + [FILES_MATCHING] + [[PATTERN <pattern> | REGEX <regex>] + [EXCLUDE] [PERMISSIONS permissions...]] [...]) + +The ``DIRECTORY`` form installs contents of one or more directories to a +given destination. The directory structure is copied verbatim to the +destination. The last component of each directory name is appended to +the destination directory but a trailing slash may be used to avoid +this because it leaves the last component empty. Directory names +given as relative paths are interpreted with respect to the current +source directory. If no input directory names are given the +destination directory will be created but nothing will be installed +into it. The ``FILE_PERMISSIONS`` and ``DIRECTORY_PERMISSIONS`` options +specify permissions given to files and directories in the destination. +If ``USE_SOURCE_PERMISSIONS`` is specified and ``FILE_PERMISSIONS`` is not, +file permissions will be copied from the source directory structure. +If no permissions are specified files will be given the default +permissions specified in the ``FILES`` form of the command, and the +directories will be given the default permissions specified in the +``PROGRAMS`` form of the command. + +.. versionadded:: 3.1 + The ``MESSAGE_NEVER`` option disables file installation status output. + +Installation of directories may be controlled with fine granularity +using the ``PATTERN`` or ``REGEX`` options. These "match" options specify a +globbing pattern or regular expression to match directories or files +encountered within input directories. They may be used to apply +certain options (see below) to a subset of the files and directories +encountered. The full path to each input file or directory (with +forward slashes) is matched against the expression. A ``PATTERN`` will +match only complete file names: the portion of the full path matching +the pattern must occur at the end of the file name and be preceded by +a slash. A ``REGEX`` will match any portion of the full path but it may +use ``/`` and ``$`` to simulate the ``PATTERN`` behavior. By default all +files and directories are installed whether or not they are matched. +The ``FILES_MATCHING`` option may be given before the first match option +to disable installation of files (but not directories) not matched by +any expression. For example, the code + +.. code-block:: cmake + + install(DIRECTORY src/ DESTINATION include/myproj + FILES_MATCHING PATTERN "*.h") + +will extract and install header files from a source tree. + +Some options may follow a ``PATTERN`` or ``REGEX`` expression and are applied +only to files or directories matching them. The ``EXCLUDE`` option will +skip the matched file or directory. The ``PERMISSIONS`` option overrides +the permissions setting for the matched file or directory. For +example the code + +.. code-block:: cmake + + install(DIRECTORY icons scripts/ DESTINATION share/myproj + PATTERN "CVS" EXCLUDE + PATTERN "scripts/*" + PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ + GROUP_EXECUTE GROUP_READ) + +will install the ``icons`` directory to ``share/myproj/icons`` and the +``scripts`` directory to ``share/myproj``. The icons will get default +file permissions, the scripts will be given specific permissions, and any +``CVS`` directories will be excluded. + +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. + +.. versionadded:: 3.4 + 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. + +.. versionadded:: 3.5 + The list of ``dirs...`` given to ``DIRECTORY`` may use + "generator expressions" too. + +Custom Installation Logic +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. _`install(CODE)`: +.. _`install(SCRIPT)`: +.. _CODE: +.. _SCRIPT: + +.. code-block:: cmake + + install([[SCRIPT <file>] [CODE <code>]] + [COMPONENT <component>] [EXCLUDE_FROM_ALL] [...]) + +The ``SCRIPT`` form will invoke the given CMake script files during +installation. If the script file name is a relative path it will be +interpreted with respect to the current source directory. The ``CODE`` +form will invoke the given CMake code during installation. Code is +specified as a single argument inside a double-quoted string. For +example, the code + +.. code-block:: cmake + + install(CODE "MESSAGE(\"Sample install message.\")") + +will print a message during installation. + +.. versionadded:: 3.14 + ``<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]| + [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 +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`` +option may be used to specify a different name. The value given to +the ``FILE`` option must be a file name with the ``.cmake`` extension. +If a ``CONFIGURATIONS`` option is given then the file will only be installed +when one of the named configurations is installed. Additionally, the +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``. + +.. note:: + The installed ``<export-name>.cmake`` file may come with additional + per-configuration ``<export-name>-*.cmake`` files to be loaded by + globbing. Do not use an export name that is the same as the package + name in combination with installing a ``<package-name>-config.cmake`` + file or the latter may be incorrectly matched by the glob and loaded. + +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. + +.. versionadded:: 3.7 + 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 + and defines required to use the libraries. + +The ``EXPORT`` form is useful to help outside projects use targets built +and installed by the current project. For example, the code + +.. code-block:: cmake + + install(TARGETS myexe EXPORT myproj DESTINATION bin) + install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj) + install(EXPORT_ANDROID_MK myproj DESTINATION share/ndk-modules) + +will install the executable ``myexe`` to ``<prefix>/bin`` and code to import +it in the file ``<prefix>/lib/myproj/myproj.cmake`` and +``<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. + +.. note:: + This command supercedes the :command:`install_targets` command and + the :prop_tgt:`PRE_INSTALL_SCRIPT` and :prop_tgt:`POST_INSTALL_SCRIPT` + target properties. It also replaces the ``FILES`` forms of the + :command:`install_files` and :command:`install_programs` commands. + The processing order of these install rules relative to + those generated by :command:`install_targets`, + :command:`install_files`, and :command:`install_programs` commands + is not defined. + +Generated Installation Script +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. note:: + + Use of this feature is not recommended. Please consider using the + ``--install`` argument of :manual:`cmake(1)` instead. + +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 new file mode 100644 index 0000000..ff074a8 --- /dev/null +++ b/Help/command/install_files.rst @@ -0,0 +1,41 @@ +install_files +------------- + +.. 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 +directly replaced by the ``FILES`` form of the :command:`install` +command. The regexp form can be expressed more clearly using the ``GLOB`` +form of the :command:`file` command. + +:: + + install_files(<dir> extension file file ...) + +Create rules to install the listed files with the given extension into +the given directory. Only files existing in the current source tree +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``. + +:: + + install_files(<dir> regexp) + +Any files in the current source directory that match the regular +expression will be installed. + +:: + + install_files(<dir> FILES file file ...) + +Any files listed after the ``FILES`` keyword will be installed explicitly +from the names given. Full paths are allowed in this form. + +The directory ``<dir>`` is relative to the installation prefix, which is +stored in the variable :variable:`CMAKE_INSTALL_PREFIX`. diff --git a/Help/command/install_programs.rst b/Help/command/install_programs.rst new file mode 100644 index 0000000..fab6482 --- /dev/null +++ b/Help/command/install_programs.rst @@ -0,0 +1,36 @@ +install_programs +---------------- + +.. 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 +directly replaced by the ``PROGRAMS`` form of the :command:`install` +command. The regexp form can be expressed more clearly using the ``GLOB`` +form of the :command:`file` command. + +:: + + install_programs(<dir> file1 file2 [file3 ...]) + install_programs(<dir> FILES file1 [file2 ...]) + +Create rules to install the listed programs into the given directory. +Use the ``FILES`` argument to guarantee that the file list version of the +command will be used even when there is only one argument. + +:: + + install_programs(<dir> regexp) + +In the second form any program in the current source directory that +matches the regular expression will be installed. + +This command is intended to install programs that are not built by +cmake, such as shell scripts. See the ``TARGETS`` form of the +:command:`install` command to create installation rules for targets built +by cmake. + +The directory ``<dir>`` is relative to the installation prefix, which is +stored in the variable :variable:`CMAKE_INSTALL_PREFIX`. diff --git a/Help/command/install_targets.rst b/Help/command/install_targets.rst new file mode 100644 index 0000000..c9efdce --- /dev/null +++ b/Help/command/install_targets.rst @@ -0,0 +1,19 @@ +install_targets +--------------- + +.. 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. + +:: + + install_targets(<dir> [RUNTIME_DIRECTORY dir] target target) + +Create rules to install the listed targets into the given directory. +The directory ``<dir>`` is relative to the installation prefix, which is +stored in the variable :variable:`CMAKE_INSTALL_PREFIX`. If +``RUNTIME_DIRECTORY`` is specified, then on systems with special runtime +files (Windows DLL), the files will be copied to that directory. diff --git a/Help/command/link_directories.rst b/Help/command/link_directories.rst new file mode 100644 index 0000000..6732402 --- /dev/null +++ b/Help/command/link_directories.rst @@ -0,0 +1,55 @@ +link_directories +---------------- + +Add directories in which the linker will look for libraries. + +.. code-block:: cmake + + link_directories([AFTER|BEFORE] directory1 [directory2 ...]) + +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`. + +The command will apply only to targets created after it is called. + +.. versionadded:: 3.13 + 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. See the :manual:`cmake-buildsystem(7)` + manual for more on defining buildsystem properties. + +.. versionadded:: 3.13 + 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. + +.. versionadded:: 3.13 + Arguments to ``link_directories`` may use "generator expressions" with + the syntax "$<...>". See the :manual:`cmake-generator-expressions(7)` + manual for available expressions. + +.. 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 new file mode 100644 index 0000000..8665cb7 --- /dev/null +++ b/Help/command/link_libraries.rst @@ -0,0 +1,19 @@ +link_libraries +-------------- + +Link libraries to all targets added later. + +.. code-block:: cmake + + link_libraries([item1 [item2 [...]]] + [[debug|optimized|general] <item>] ...) + +Specify libraries or flags to use when linking any targets created later in +the current directory or below by commands such as :command:`add_executable` +or :command:`add_library`. See the :command:`target_link_libraries` command +for meaning of arguments. + +.. note:: + The :command:`target_link_libraries` command should be preferred whenever + possible. Library dependencies are chained automatically, so directory-wide + specification of link libraries is rarely needed. diff --git a/Help/command/list.rst b/Help/command/list.rst new file mode 100644 index 0000000..7accc5a --- /dev/null +++ b/Help/command/list.rst @@ -0,0 +1,353 @@ +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>) + +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>) + +.. versionadded:: 3.12 + +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>) + +.. versionadded:: 3.12 + +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>) + +.. versionadded:: 3.6 + +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>...]) + +.. versionadded:: 3.15 + +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>...]) + +.. versionadded:: 3.15 + +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> ...]) + +.. versionadded:: 3.15 + +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>) + +Removes duplicated items in the list. The relative order of items is preserved, +but if duplicates are encountered, only the first instance is preserved. + +.. _TRANSFORM: + +.. code-block:: cmake + + list(TRANSFORM <list> <ACTION> [<SELECTOR>] + [OUTPUT_VARIABLE <output variable>]) + +.. versionadded:: 3.12 + +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. + +.. note:: + + 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. + +``<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: + +``APPEND``, ``PREPEND``: Append, prepend specified value to each element of +the list. + + .. code-block:: cmake + + 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. + +.. versionadded:: 3.13 + Added the ``COMPARE``, ``CASE``, and ``ORDER`` options. + +.. versionadded:: 3.18 + Added the ``COMPARE NATURAL`` option. + +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. +* ``NATURAL``: Sorts a list of strings using natural order + (see ``strverscmp(3)`` manual), i.e. such that contiguous digits + are compared as whole numbers. + For example: the following list `10.0 1.1 2.1 8.0 2.0 3.1` + will be sorted as `1.1 2.0 2.1 3.1 8.0 10.0` if the ``NATURAL`` + comparison is selected where it will be sorted as + `1.1 10.0 2.0 2.1 3.1 8.0` with the ``STRING`` comparison. + +Use the ``CASE`` keyword to select a case sensitive or case insensitive +sort mode. The ``<case>`` option should be one of: + +* ``SENSITIVE``: List items are sorted in a case-sensitive manner. This is + the default behavior if the ``CASE`` option is not given. +* ``INSENSITIVE``: List items are sorted case insensitively. The order of + items which differ only by upper/lowercase is not specified. + +To control the sort order, the ``ORDER`` keyword can be given. +The ``<order>`` option should be one of: + +* ``ASCENDING``: Sorts the list in ascending order. This is the default + behavior when the ``ORDER`` option is not given. +* ``DESCENDING``: Sorts the list in descending order. diff --git a/Help/command/load_cache.rst b/Help/command/load_cache.rst new file mode 100644 index 0000000..b89eb61 --- /dev/null +++ b/Help/command/load_cache.rst @@ -0,0 +1,26 @@ +load_cache +---------- + +Load in the values from another project's CMake cache. + +.. code-block:: cmake + + load_cache(pathToBuildDirectory READ_WITH_PREFIX prefix entry1...) + +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(pathToBuildDirectory [EXCLUDE entry1...] + [INCLUDE_INTERNALS entry1...]) + +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. +``INCLUDE_INTERNALS`` can be used to provide a list of internal entries to +be included. Normally, no internal entries are brought in. Use of +this form of the command is strongly discouraged, but it is provided +for backward compatibility. diff --git a/Help/command/load_command.rst b/Help/command/load_command.rst new file mode 100644 index 0000000..dc23599 --- /dev/null +++ b/Help/command/load_command.rst @@ -0,0 +1,23 @@ +load_command +------------ + +Disallowed since version 3.0. See CMake Policy :policy:`CMP0031`. + +Load a command into a running CMake. + +:: + + load_command(COMMAND_NAME <loc1> [loc2 ...]) + +The given locations are searched for a library whose name is +cmCOMMAND_NAME. If found, it is loaded as a module and the command is +added to the set of available CMake commands. Usually, +:command:`try_compile` is used before this command to compile the +module. If the command is successfully loaded a variable named + +:: + + CMAKE_LOADED_COMMAND_<COMMAND_NAME> + +will be set to the full path of the module that was loaded. Otherwise +the variable will not be set. diff --git a/Help/command/macro.rst b/Help/command/macro.rst new file mode 100644 index 0000000..5fe4c00 --- /dev/null +++ b/Help/command/macro.rst @@ -0,0 +1,151 @@ +macro +----- + +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() + cmake_language(CALL 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. + +.. versionadded:: 3.18 + The :command:`cmake_language(CALL ...)` command can also be used to + invoke the macro. + +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. + +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 +behavior. Checking that ``${ARGC}`` is greater than ``#`` is the only +way to ensure that ``${ARGV#}`` was passed to the function as an extra +argument. + +.. _`Macro vs Function`: + +Macro vs Function +^^^^^^^^^^^^^^^^^ + +The ``macro`` command is very similar to the :command:`function` command. +Nonetheless, there are a few important differences. + +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. + +Unlike a function, the :variable:`CMAKE_CURRENT_FUNCTION`, +:variable:`CMAKE_CURRENT_FUNCTION_LIST_DIR`, +:variable:`CMAKE_CURRENT_FUNCTION_LIST_FILE`, +:variable:`CMAKE_CURRENT_FUNCTION_LIST_LINE` variables are not +set for a macro. + +.. _`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 + +.. 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: + +.. code-block:: cmake + + macro(bar) + foreach(arg IN LISTS ARGN) + <commands> + endforeach() + endmacro() + + function(foo) + bar(x y z) + endfunction() + + foo(a b c) + +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 new file mode 100644 index 0000000..8469b0a --- /dev/null +++ b/Help/command/make_directory.rst @@ -0,0 +1,14 @@ +make_directory +-------------- + +.. deprecated:: 3.0 + + Use the :command:`file(MAKE_DIRECTORY)` command instead. + +:: + + make_directory(directory) + +Creates the specified directory. Full paths should be given. Any +parent directories that do not exist will also be created. Use with +care. diff --git a/Help/command/mark_as_advanced.rst b/Help/command/mark_as_advanced.rst new file mode 100644 index 0000000..201363f --- /dev/null +++ b/Help/command/mark_as_advanced.rst @@ -0,0 +1,28 @@ +mark_as_advanced +---------------- + +Mark cmake cached variables as advanced. + +.. code-block:: cmake + + mark_as_advanced([CLEAR|FORCE] <var1> ...) + +Sets the advanced/non-advanced state of the named +cached variables. + +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. + +.. versionchanged:: 3.17 + Variables passed to this command which are not already in the cache + are ignored. See policy :policy:`CMP0102`. diff --git a/Help/command/math.rst b/Help/command/math.rst new file mode 100644 index 0000000..8386aab --- /dev/null +++ b/Help/command/math.rst @@ -0,0 +1,38 @@ +math +---- + +Evaluate a mathematical expression. + +.. code-block:: cmake + + math(EXPR <variable> "<expression>" [OUTPUT_FORMAT <format>]) + +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 in C code. + +.. versionadded:: 3.13 + Hexadecimal numbers are recognized when prefixed with ``0x``, as in C code. + +.. versionadded:: 3.13 + 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 new file mode 100644 index 0000000..e44803e --- /dev/null +++ b/Help/command/message.rst @@ -0,0 +1,191 @@ +message +------- + +Log a message. + +Synopsis +^^^^^^^^ + +.. parsed-literal:: + + `General messages`_ + message([<mode>] "message text" ...) + + `Reporting checks`_ + message(<checkState> "message text" ...) + + +General messages +^^^^^^^^^^^^^^^^ + +.. code-block:: cmake + + message([<mode>] "message text" ...) + +Record the specified message text in the log. If more than one message +string is given, they are concatenated into a single message with no +separator between the strings. + +The optional ``<mode>`` keyword determines the type of message, which +influences the way the message is handled: + +``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. + +.. versionadded:: 3.15 + Added the ``NOTICE``, ``VERBOSE``, ``DEBUG``, and ``TRACE`` levels. + +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. + +.. versionadded:: 3.17 + To make a log level persist between CMake runs, the + :variable:`CMAKE_MESSAGE_LOG_LEVEL` variable can be set instead. + Note that the command line option takes precedence over the cache variable. + +.. versionadded:: 3.16 + Messages of log levels ``NOTICE`` and below will 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. + +.. versionadded:: 3.17 + Messages of log levels ``NOTICE`` and below can also have each line preceded + with context of the form ``[some.context.example]``. The content between the + square brackets is obtained by converting the :variable:`CMAKE_MESSAGE_CONTEXT` + list variable to a dot-separated string. The message context will always + appear before any indenting content but after any automatically added leading + hyphens. By default, message context is not shown, it has to be explicitly + enabled by giving the :manual:`cmake <cmake(1)>` ``--log-context`` + command-line option or by setting the :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` + variable to true. See the :variable:`CMAKE_MESSAGE_CONTEXT` documentation for + usage examples. + +CMake Warning and Error message text displays using a simple markup +language. Non-indented text is formatted in line-wrapped paragraphs +delimited by newlines. Indented text is considered pre-formatted. + + +Reporting checks +^^^^^^^^^^^^^^^^ + +.. versionadded:: 3.17 + +A common pattern in CMake output is a message indicating the start of some +sort of check, followed by another message reporting the result of that check. +For example: + +.. code-block:: cmake + + message(STATUS "Looking for someheader.h") + #... do the checks, set checkSuccess with the result + if(checkSuccess) + message(STATUS "Looking for someheader.h - found") + else() + message(STATUS "Looking for someheader.h - not found") + endif() + +This can be more robustly and conveniently expressed using the ``CHECK_...`` +keyword form of the ``message()`` command: + +.. code-block:: cmake + + message(<checkState> "message" ...) + +where ``<checkState>`` must be one of the following: + + ``CHECK_START`` + Record a concise message about the check about to be performed. + + ``CHECK_PASS`` + Record a successful result for a check. + + ``CHECK_FAIL`` + Record an unsuccessful result for a check. + +When recording a check result, the command repeats the message from the most +recently started check for which no result has yet been reported, then some +separator characters and then the message text provided after the +``CHECK_PASS`` or ``CHECK_FAIL`` keyword. Check messages are always reported +at ``STATUS`` log level. + +Checks may be nested and every ``CHECK_START`` should have exactly one +matching ``CHECK_PASS`` or ``CHECK_FAIL``. +The :variable:`CMAKE_MESSAGE_INDENT` variable can also be used to add +indenting to nested checks if desired. For example: + +.. code-block:: cmake + + message(CHECK_START "Finding my things") + list(APPEND CMAKE_MESSAGE_INDENT " ") + unset(missingComponents) + + message(CHECK_START "Finding partA") + # ... do check, assume we find A + message(CHECK_PASS "found") + + message(CHECK_START "Finding partB") + # ... do check, assume we don't find B + list(APPEND missingComponents B) + message(CHECK_FAIL "not found") + + list(POP_BACK CMAKE_MESSAGE_INDENT) + if(missingComponents) + message(CHECK_FAIL "missing components: ${missingComponents}") + else() + message(CHECK_PASS "all components found") + endif() + +Output from the above would appear something like the following:: + + -- Finding my things + -- Finding partA + -- Finding partA - found + -- Finding partB + -- Finding partB - not found + -- Finding my things - missing components: B diff --git a/Help/command/option.rst b/Help/command/option.rst new file mode 100644 index 0000000..02b8dac --- /dev/null +++ b/Help/command/option.rst @@ -0,0 +1,16 @@ +option +------ + +Provide an option that the user can optionally select. + +.. code-block:: cmake + + option(<variable> "<help_text>" [value]) + +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 or cache 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 new file mode 100644 index 0000000..b3a6e86 --- /dev/null +++ b/Help/command/output_required_files.rst @@ -0,0 +1,19 @@ +output_required_files +--------------------- + +Disallowed since version 3.0. See CMake Policy :policy:`CMP0032`. + +Approximate C preprocessor dependency scanning. + +This command exists only because ancient CMake versions provided it. +CMake handles preprocessor dependency scanning automatically using a +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. diff --git a/Help/command/project.rst b/Help/command/project.rst new file mode 100644 index 0000000..8a6bc1e --- /dev/null +++ b/Help/command/project.rst @@ -0,0 +1,164 @@ +project +------- + +Set the name of the project. + +Synopsis +^^^^^^^^ + +.. code-block:: cmake + + 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 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` + Absolute path to the source directory for the project. + +:variable:`PROJECT_BINARY_DIR`, :variable:`<PROJECT-NAME>_BINARY_DIR` + Absolute path to the binary directory for the project. + +:variable:`PROJECT_IS_TOP_LEVEL`, :variable:`<PROJECT-NAME>_IS_TOP_LEVEL` + .. versionadded:: 3.21 + + Boolean value indicating whether the project is top-level. + +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`. + + .. versionadded:: 3.12 + 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>`` + .. versionadded:: 3.9 + + 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`. + + .. versionadded:: 3.12 + Added the ``<PROJECT-NAME>_DESCRIPTION`` variable. + +``HOMEPAGE_URL <url-string>`` + .. versionadded:: 3.12 + + 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``, ``ISPC``, 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. + + .. versionadded:: 3.8 + Added ``CUDA`` support. + + .. versionadded:: 3.16 + Added ``OBJC`` and ``OBJCXX`` support. + + .. versionadded:: 3.18 + Added ``ISPC`` support. + + 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` or +:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE` variables are set, +the files they point to will be included as the first step of the +``project()`` command. +If both are set, then :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` will be +included before :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`. + +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`. + +.. versionadded:: 3.15 + Added the ``CMAKE_PROJECT_INCLUDE`` and ``CMAKE_PROJECT_INCLUDE_BEFORE`` + variables. + +.. versionadded:: 3.17 + Added the ``CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`` variable. + +Usage +^^^^^ + +The top-level ``CMakeLists.txt`` file for a project must contain a +literal, direct call to the ``project()`` command; loading one +through the :command:`include` command is not sufficient. If no such +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 ``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 new file mode 100644 index 0000000..ce11c2d --- /dev/null +++ b/Help/command/qt_wrap_cpp.rst @@ -0,0 +1,23 @@ +qt_wrap_cpp +----------- + +.. 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()``). + +Manually create Qt Wrappers. + +.. 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 new file mode 100644 index 0000000..efbbc54 --- /dev/null +++ b/Help/command/qt_wrap_ui.rst @@ -0,0 +1,26 @@ +qt_wrap_ui +---------- + +.. 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 ...) + +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 new file mode 100644 index 0000000..543d016 --- /dev/null +++ b/Help/command/remove.rst @@ -0,0 +1,14 @@ +remove +------ + +.. deprecated:: 3.0 + + Use the :command:`list(REMOVE_ITEM)` command instead. + +:: + + remove(VAR VALUE VALUE ...) + +Removes ``VALUE`` from the variable ``VAR``. This is typically used to +remove entries from a vector (e.g. semicolon separated list). ``VALUE`` +is expanded. diff --git a/Help/command/remove_definitions.rst b/Help/command/remove_definitions.rst new file mode 100644 index 0000000..faad16d --- /dev/null +++ b/Help/command/remove_definitions.rst @@ -0,0 +1,11 @@ +remove_definitions +------------------ + +Remove -D define flags added by :command:`add_definitions`. + +.. code-block:: cmake + + remove_definitions(-DFOO -DBAR ...) + +Removes flags (added by :command:`add_definitions`) from the compiler +command line for sources in the current directory and below. diff --git a/Help/command/return.rst b/Help/command/return.rst new file mode 100644 index 0000000..ec009d8 --- /dev/null +++ b/Help/command/return.rst @@ -0,0 +1,20 @@ +return +------ + +Return from a file, directory or function. + +.. code-block:: cmake + + return() + +Returns from a file, directory or function. When this command is +encountered in an included file (via :command:`include` or +:command:`find_package`), it causes processing of the current file to stop +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``, +deferred calls scheduled by :command:`cmake_language(DEFER)` are invoked and +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 :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 new file mode 100644 index 0000000..f66af35 --- /dev/null +++ b/Help/command/separate_arguments.rst @@ -0,0 +1,80 @@ +separate_arguments +------------------ + +Parse command-line arguments into a semicolon-separated list. + +.. code-block:: cmake + + separate_arguments(<variable> <mode> [PROGRAM [SEPARATE_ARGS]] <args>) + +Parses a space-separated string ``<args>`` into a list of items, +and stores this list in semicolon-separated standard form in ``<variable>``. + +This function is intended for parsing command-line arguments. +The entire command line must be passed as one string in the +argument ``<args>``. + +The exact parsing rules depend on the operating system. +They are specified by the ``<mode>`` argument which must +be one of the following keywords: + +``UNIX_COMMAND`` + Arguments are separated 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`` + .. versionadded:: 3.9 + + Proceeds as in ``WINDOWS_COMMAND`` mode if the host system is Windows. + Otherwise proceeds as in ``UNIX_COMMAND`` mode. + +``PROGRAM`` + .. versionadded:: 3.19 + + The first item in ``<args>`` is assumed to be an executable and will be + searched in the system search path or left as a full path. If not found, + ``<variable>`` will be empty. Otherwise, ``<variable>`` is a list of 2 + elements: + + 0. Absolute path of the program + 1. Any command-line arguments present in ``<args>`` as a string + + For example: + + .. code-block:: cmake + + separate_arguments (out UNIX_COMMAND PROGRAM "cc -c main.c") + + * First element of the list: ``/path/to/cc`` + * Second element of the list: ``" -c main.c"`` + +``SEPARATE_ARGS`` + When this sub-option of ``PROGRAM`` option is specified, command-line + arguments will be split as well and stored in ``<variable>``. + + For example: + + .. code-block:: cmake + + separate_arguments (out UNIX_COMMAND PROGRAM SEPARATE_ARGS "cc -c main.c") + + The contents of ``out`` will be: ``/path/to/cc;-c;main.c`` + +.. _`Parsing C Command-Line Arguments`: https://msdn.microsoft.com/library/a1y7w461.aspx + +.. code-block:: cmake + + separate_arguments(<var>) + +Convert the value of ``<var>`` to a semi-colon separated list. All +spaces are replaced with ';'. This helps with generating command +lines. diff --git a/Help/command/set.rst b/Help/command/set.rst new file mode 100644 index 0000000..c0e02e2 --- /dev/null +++ b/Help/command/set.rst @@ -0,0 +1,104 @@ +set +--- + +Set a normal, cache, or environment variable to a given value. +See the :ref:`cmake-language(7) variables <CMake Language Variables>` +documentation for the scopes and interaction of normal variables +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:`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]) + +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 +creates a new scope. This command will set the value of a variable +into the parent directory or calling function (whichever is applicable +to the case at hand). The previous state of the variable's value stays the +same in the current scope (e.g., if it was undefined before, it is still +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]) + +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. + +The ``<type>`` must be specified as one of: + +``BOOL`` + Boolean ``ON/OFF`` value. :manual:`cmake-gui(1)` offers a checkbox. + +``FILEPATH`` + Path to a file on disk. :manual:`cmake-gui(1)` offers a file dialog. + +``PATH`` + Path to a directory on disk. :manual:`cmake-gui(1)` offers a file dialog. + +``STRING`` + A line of text. :manual:`cmake-gui(1)` offers a text field or a + drop-down selection if the :prop_cache:`STRINGS` cache entry + property is set. + +``INTERNAL`` + A line of text. :manual:`cmake-gui(1)` does not show internal entries. + They may be used to store variables persistently across runs. + Use of this type implies ``FORCE``. + +The ``<docstring>`` must be specified as a line of text providing +a quick summary of the option for presentation to :manual:`cmake-gui(1)` +users. + +If the cache entry does not exist prior to the call or the ``FORCE`` +option is given then the cache entry will be set to the given value. +Furthermore, any normal variable binding in the current scope will +be removed to expose the newly cached value to any immediately +following evaluation. + +It is possible for the cache entry to exist prior to the call but +have no type set if it was created on the :manual:`cmake(1)` command +line by a user through the ``-D<var>=<value>`` option without +specifying a type. In this case the ``set`` command will add the +type. Furthermore, if the ``<type>`` is ``PATH`` or ``FILEPATH`` +and the ``<value>`` provided on the command line is a relative path, +then the ``set`` command will treat the path as relative to the +current working directory and convert it to an absolute path. + +Set Environment Variable +^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: cmake + + set(ENV{<variable>} [<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 new file mode 100644 index 0000000..f02a8e6 --- /dev/null +++ b/Help/command/set_directory_properties.rst @@ -0,0 +1,15 @@ +set_directory_properties +------------------------ + +Set properties of the current directory and subdirectories. + +.. code-block:: cmake + + set_directory_properties(PROPERTIES prop1 value1 [prop2 value2] ...) + +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 new file mode 100644 index 0000000..bf437b4 --- /dev/null +++ b/Help/command/set_property.rst @@ -0,0 +1,112 @@ +set_property +------------ + +Set a named property in a given scope. + +.. code-block:: cmake + + set_property(<GLOBAL | + DIRECTORY [<dir>] | + TARGET [<target1> ...] | + SOURCE [<src1> ...] + [DIRECTORY <dirs> ...] | + [TARGET_DIRECTORY <targets> ...] + INSTALL [<file1> ...] | + TEST [<test1> ...] | + CACHE [<entry1> ...] > + [APPEND] [APPEND_STRING] + PROPERTY <name> [<value1> ...]) + +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 other directories + (already processed by CMake) may be named by full or relative path. + Relative paths are treated as relative to the current source directory. + See also the :command:`set_directory_properties` command. + + .. versionadded:: 3.19 + ``<dir>`` may reference a binary directory. + +``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. By default, source file properties + are only visible to targets added in the same directory (``CMakeLists.txt``). + + .. versionadded:: 3.18 + Visibility can be set in other directory scopes using one or both of the + following sub-options: + + ``DIRECTORY <dirs>...`` + The source file property will be set in each of the ``<dirs>`` + directories' scopes. CMake must already know about + each of these directories, either by having added them through a call to + :command:`add_subdirectory` or it being the top level source directory. + Relative paths are treated as relative to the current source directory. + + .. versionadded:: 3.19 + ``<dirs>`` may reference a binary directory. + + ``TARGET_DIRECTORY <targets>...`` + The source file property will be set in each of the directory scopes + where any of the specified ``<targets>`` were created (the ``<targets>`` + must therefore already exist). + + See also the :command:`set_source_files_properties` command. + +``INSTALL`` + .. versionadded:: 3.1 + + Scope may name zero or more installed file paths. + These are made available to CPack to influence deployment. + + Both the property key and value may use generator expressions. + Specific properties may apply to installed files and/or directories. + + 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 ``.``. + + Currently installed file properties are only defined for + the WIX generator where the given paths are relative + to the installation prefix. + +``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 (except that empty values are ignored and not appended). +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. + +.. note:: + + The :prop_sf:`GENERATED` source file property may be globally visible. + See its documentation for details. diff --git a/Help/command/set_source_files_properties.rst b/Help/command/set_source_files_properties.rst new file mode 100644 index 0000000..61c69a2 --- /dev/null +++ b/Help/command/set_source_files_properties.rst @@ -0,0 +1,43 @@ +set_source_files_properties +--------------------------- + +Source files can have properties that affect how they are built. + +.. code-block:: cmake + + set_source_files_properties(<files> ... + [DIRECTORY <dirs> ...] + [TARGET_DIRECTORY <targets> ...] + PROPERTIES <prop1> <value1> + [<prop2> <value2>] ...) + +Sets properties associated with source files using a key/value paired +list. + +.. versionadded:: 3.18 + By default, source file properties are only visible to targets added in the + same directory (``CMakeLists.txt``). Visibility can be set in other directory + scopes using one or both of the following options: + +``DIRECTORY <dirs>...`` + The source file properties will be set in each of the ``<dirs>`` + directories' scopes. CMake must already know about each of these + source directories, either by having added them through a call to + :command:`add_subdirectory` or it being the top level source directory. + Relative paths are treated as relative to the current source directory. + +``TARGET_DIRECTORY <targets>...`` + The source file properties will be set in each of the directory scopes + where any of the specified ``<targets>`` were created (the ``<targets>`` + must therefore already exist). + +Use :command:`get_source_file_property` to get property values. +See also the :command:`set_property(SOURCE)` command. + +See :ref:`Source File Properties` for the list of properties known +to CMake. + +.. note:: + + The :prop_sf:`GENERATED` source file property may be globally visible. + See its documentation for details. diff --git a/Help/command/set_target_properties.rst b/Help/command/set_target_properties.rst new file mode 100644 index 0000000..597be23 --- /dev/null +++ b/Help/command/set_target_properties.rst @@ -0,0 +1,20 @@ +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 ...) + +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 new file mode 100644 index 0000000..9bc94ae --- /dev/null +++ b/Help/command/set_tests_properties.rst @@ -0,0 +1,17 @@ +set_tests_properties +-------------------- + +Set a property of the tests. + +.. code-block:: cmake + + set_tests_properties(test1 [test2...] PROPERTIES prop1 value1 prop2 value2) + +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 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 new file mode 100644 index 0000000..09b5a9f --- /dev/null +++ b/Help/command/site_name.rst @@ -0,0 +1,12 @@ +site_name +--------- + +Set the given variable to the name of the computer. + +.. code-block:: cmake + + site_name(variable) + +On UNIX-like platforms, if the variable ``HOSTNAME`` is set, its value +will be executed as a command expected to print out the host name, +much like the ``hostname`` command-line tool. diff --git a/Help/command/source_group.rst b/Help/command/source_group.rst new file mode 100644 index 0000000..5db1ec8 --- /dev/null +++ b/Help/command/source_group.rst @@ -0,0 +1,67 @@ +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>...]) + +Defines a group into which sources will be placed in project files. +This is intended to set up file tabs in Visual Studio. +The options are: + +``TREE`` + .. versionadded:: 3.8 + + CMake will automatically detect, from ``<src>`` files paths, source groups + it needs to create, to keep structure of source groups analogically to the + actual files and directories structure in the project. Paths of ``<src>`` + files will be cut to be relative to ``<root>``. + +``PREFIX`` + .. versionadded:: 3.8 + + Source group and files located directly in ``<root>`` path, will be placed + in ``<prefix>`` source groups. + +``FILES`` + Any source file specified explicitly will be placed in group + ``<name>``. Relative paths are interpreted with respect to the + current source directory. + +``REGULAR_EXPRESSION`` + Any source file whose name matches the regular expression will + be placed in group ``<name>``. + +If a source file matches multiple groups, the *last* group that +explicitly lists the file with ``FILES`` will be favored, if any. +If no group explicitly lists the file, the *last* group whose +regular expression matches the file will be favored. + +The ``<name>`` of the group and ``<prefix>`` argument may contain forward +slashes or backslashes to specify subgroups. Backslashes need to be escaped +appropriately: + +.. code-block:: cmake + + source_group(base/subdir ...) + source_group(outer\\inner ...) + source_group(TREE <root> PREFIX sources\\inc ...) + +.. versionadded:: 3.18 + Allow using forward slashes (``/``) to specify subgroups. + +For backwards compatibility, the short-hand signature + +.. code-block:: cmake + + source_group(<name> <regex>) + +is equivalent to + +.. code-block:: cmake + + source_group(<name> REGULAR_EXPRESSION <regex>) diff --git a/Help/command/string.rst b/Help/command/string.rst new file mode 100644 index 0000000..8ad0089 --- /dev/null +++ b/Help/command/string.rst @@ -0,0 +1,612 @@ +string +------ + +String operations. + +Synopsis +^^^^^^^^ + +.. parsed-literal:: + + `Search and Replace`_ + string(`FIND`_ <string> <substring> <out-var> [...]) + string(`REPLACE`_ <match-string> <replace-string> <out-var> <input>...) + 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(`HEX`_ <string> <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> ...) + + `JSON`_ + string(JSON <out-var> [ERROR_VARIABLE <error-var>] + {`GET`_ | `TYPE`_ | :ref:`LENGTH <JSONLENGTH>` | `REMOVE`_} + <json-string> <member|index> [<member|index> ...]) + string(JSON <out-var> [ERROR_VARIABLE <error-var>] + `MEMBER`_ <json-string> + [<member|index> ...] <index>) + string(JSON <out-var> [ERROR_VARIABLE <error-var>] + `SET`_ <json-string> + <member|index> [<member|index> ...] <value>) + string(JSON <out-var> [ERROR_VARIABLE <error-var>] + `EQUAL`_ <json-string1> <json-string2>) + +Search and Replace +^^^^^^^^^^^^^^^^^^ + +Search and Replace With Plain Strings +""""""""""""""""""""""""""""""""""""" + +.. _FIND: + +.. code-block:: cmake + + 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 +search for the position of the last occurrence of the specified +``<substring>``. If the ``<substring>`` is not found, a position of -1 is +returned. + +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> + <input> [<input>...]) + +Replace all occurrences of ``<match_string>`` in the ``<input>`` +with ``<replace_string>`` and store the result in the ``<output_variable>``. + +Search and Replace With Regular Expressions +""""""""""""""""""""""""""""""""""""""""""" + +.. _`REGEX MATCH`: + +.. code-block:: cmake + + string(REGEX MATCH <regular_expression> + <output_variable> <input> [<input>...]) + +Match the ``<regular_expression>`` once and store the match in the +``<output_variable>``. +All ``<input>`` arguments are concatenated before matching. +Regular expressions are specified in the subsection just below. + +.. _`REGEX MATCHALL`: + +.. code-block:: cmake + + string(REGEX MATCHALL <regular_expression> + <output_variable> <input> [<input>...]) + +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`: + +.. code-block:: cmake + + string(REGEX REPLACE <regular_expression> + <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. +All ``<input>`` arguments are concatenated before matching. + +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`: + +Regex Specification +""""""""""""""""""" + +The following characters have special meaning in regular expressions: + +``^`` + Matches at beginning of input +``$`` + 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 +``[^ ]`` + Matches any character(s) not inside the brackets +``-`` + Inside brackets, specifies an inclusive range between + characters on either side e.g. ``[a-f]`` is ``[abcdef]`` + To match a literal ``-`` using brackets, make it the first + or the last character e.g. ``[+*/-]`` matches basic + mathematical operators. +``*`` + Matches preceding pattern zero or more times +``+`` + Matches preceding pattern one or more times +``?`` + Matches preceding pattern zero or once only +``|`` + Matches a pattern on either side of the ``|`` +``()`` + Saves a matched subexpression, which can be referenced + in the ``REGEX REPLACE`` operation. + + .. versionadded:: 3.9 + All regular expression-related commands, including e.g. + :command:`if(MATCHES)`, save subgroup matches in the variables + :variable:`CMAKE_MATCH_<n>` for ``<n>`` 0..9. + +``*``, ``+`` and ``?`` have higher precedence than concatenation. ``|`` +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: + +.. code-block:: cmake + + string(APPEND <string_variable> [<input>...]) + +.. versionadded:: 3.4 + +Append all the ``<input>`` arguments to the string. + +.. _PREPEND: + +.. code-block:: cmake + + string(PREPEND <string_variable> [<input>...]) + +.. versionadded:: 3.10 + +Prepend all the ``<input>`` arguments to the string. + +.. _CONCAT: + +.. code-block:: cmake + + string(CONCAT <output_variable> [<input>...]) + +Concatenate all the ``<input>`` arguments together and store +the result in the named ``<output_variable>``. + +.. _JOIN: + +.. code-block:: cmake + + string(JOIN <glue> <output_variable> [<input>...]) + +.. versionadded:: 3.12 + +Join all the ``<input>`` arguments together using the ``<glue>`` +string and store the result in the named ``<output_variable>``. + +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: + +.. code-block:: cmake + + string(TOLOWER <string> <output_variable>) + +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>) + +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. + +.. versionchanged:: 3.2 + If ``<string>`` is shorter than ``<length>`` then the end of the string + is used instead. Previous versions of CMake reported an error in this case. + +Both ``<begin>`` and ``<length>`` are counted in bytes, so care must +be exercised if ``<string>`` could contain multi-byte characters. + +.. _STRIP: + +.. code-block:: cmake + + string(STRIP <string> <output_variable>) + +Store in an ``<output_variable>`` a substring of a given ``<string>`` with +leading and trailing spaces removed. + +.. _GENEX_STRIP: + +.. code-block:: cmake + + string(GENEX_STRIP <string> <output_variable>) + +.. versionadded:: 3.1 + +Strip any :manual:`generator expressions <cmake-generator-expressions(7)>` +from the input ``<string>`` and store the result in the ``<output_variable>``. + +.. _REPEAT: + +.. code-block:: cmake + + string(REPEAT <string> <count> <output_variable>) + +.. versionadded:: 3.15 + +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>) + +Compare the strings and store true or false in the ``<output_variable>``. + +.. versionadded:: 3.7 + Added the ``LESS_EQUAL`` and ``GREATER_EQUAL`` options. + +.. _`Supported Hash Algorithms`: + +Hashing +^^^^^^^ + +.. _`HASH`: + +.. code-block:: cmake + + string(<HASH> <output_variable> <input>) + +Compute a cryptographic hash of the ``<input>`` string. +The supported ``<HASH>`` algorithm names are: + +``MD5`` + Message-Digest Algorithm 5, RFC 1321. +``SHA1`` + US Secure Hash Algorithm 1, RFC 3174. +``SHA224`` + US Secure Hash Algorithms, RFC 4634. +``SHA256`` + US Secure Hash Algorithms, RFC 4634. +``SHA384`` + US Secure Hash Algorithms, RFC 4634. +``SHA512`` + US Secure Hash Algorithms, RFC 4634. +``SHA3_224`` + Keccak SHA-3. +``SHA3_256`` + Keccak SHA-3. +``SHA3_384`` + Keccak SHA-3. +``SHA3_512`` + Keccak SHA-3. + +.. versionadded:: 3.8 + Added the ``SHA3_*`` hash algorithms. + +Generation +^^^^^^^^^^ + +.. _ASCII: + +.. code-block:: cmake + + string(ASCII <number> [<number> ...] <output_variable>) + +Convert all numbers into corresponding ASCII characters. + +.. _HEX: + +.. code-block:: cmake + + string(HEX <string> <output_variable>) + +.. versionadded:: 3.18 + +Convert each byte in the input ``<string>`` to its hexadecimal representation +and store the concatenated hex digits in the ``<output_variable>``. Letters in +the output (``a`` through ``f``) are in lowercase. + +.. _CONFIGURE: + +.. code-block:: cmake + + string(CONFIGURE <string> <output_variable> + [@ONLY] [ESCAPE_QUOTES]) + +Transform a ``<string>`` like :command:`configure_file` transforms a file. + +.. _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>) + +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: + +.. code-block:: cmake + + string(TIMESTAMP <output_variable> [<format_string>] [UTC]) + +Write a string representation of the current date +and/or time to the ``<output_variable>``. + +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 +specifiers: + +:: + + %% A literal percent sign (%). + %d The day of the current month (01-31). + %H The hour on a 24-hour clock (00-23). + %I The hour on a 12-hour clock (01-12). + %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. + 60 represents a leap second. (00-60) + %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. + +.. versionadded:: 3.6 + ``%s`` format specifier (UNIX time). + +.. versionadded:: 3.7 + ``%a`` and ``%b`` format specifiers (abbreviated month and weekday names). + +.. versionadded:: 3.8 + ``%%`` specifier (literal ``%``). + +.. versionadded:: 3.7 + ``%A`` and ``%B`` format specifiers (full month and weekday names). + +Unknown format specifiers will be ignored and copied to the output +as-is. + +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. + +.. versionadded:: 3.8 + 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: + +.. code-block:: cmake + + string(UUID <output_variable> NAMESPACE <namespace> NAME <name> + TYPE <MD5|SHA1> [UPPER]) + +.. versionadded:: 3.1 + +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 +with the optional ``UPPER`` flag. + +.. _JSON: + +JSON +^^^^ + +.. versionadded:: 3.19 + +Functionality for querying a JSON string. + +.. note:: + In each of the following JSON-related subcommands, if the optional + ``ERROR_VARIABLE`` argument is given, errors will be reported in + ``<error-variable>`` and the ``<out-var>`` will be set to + ``<member|index>-[<member|index>...]-NOTFOUND`` with the path elements + up to the point where the error occurred, or just ``NOTFOUND`` if there + is no relevant path. If an error occurs but the ``ERROR_VARIABLE`` + option is not present, a fatal error message is generated. If no error + occurs, the ``<error-variable>`` will be set to ``NOTFOUND``. + +.. _GET: +.. code-block:: cmake + + string(JSON <out-var> [ERROR_VARIABLE <error-variable>] + GET <json-string> <member|index> [<member|index> ...]) + +Get an element from ``<json-string>`` at the location given +by the list of ``<member|index>`` arguments. +Array and object elements will be returned as a JSON string. +Boolean elements will be returned as ``ON`` or ``OFF``. +Null elements will be returned as an empty string. +Number and string types will be returned as strings. + +.. _TYPE: +.. code-block:: cmake + + string(JSON <out-var> [ERROR_VARIABLE <error-variable>] + TYPE <json-string> <member|index> [<member|index> ...]) + +Get the type of an element in ``<json-string>`` at the location +given by the list of ``<member|index>`` arguments. The ``<out-var>`` +will be set to one of ``NULL``, ``NUMBER``, ``STRING``, ``BOOLEAN``, +``ARRAY``, or ``OBJECT``. + +.. _MEMBER: +.. code-block:: cmake + + string(JSON <out-var> [ERROR_VARIABLE <error-var>] + MEMBER <json-string> + [<member|index> ...] <index>) + +Get the name of the ``<index>``-th member in ``<json-string>`` at the location +given by the list of ``<member|index>`` arguments. +Requires an element of object type. + +.. _JSONLENGTH: +.. code-block:: cmake + + string(JSON <out-var> [ERROR_VARIABLE <error-variable>] + LENGTH <json-string> <member|index> [<member|index> ...]) + +Get the length of an element in ``<json-string>`` at the location +given by the list of ``<member|index>`` arguments. +Requires an element of array or object type. + +.. _REMOVE: +.. code-block:: cmake + + string(JSON <out-var> [ERROR_VARIABLE <error-variable>] + REMOVE <json-string> <member|index> [<member|index> ...]) + +Remove an element from ``<json-string>`` at the location +given by the list of ``<member|index>`` arguments. The JSON string +without the removed element will be stored in ``<out-var>``. + +.. _SET: +.. code-block:: cmake + + string(JSON <out-var> [ERROR_VARIABLE <error-variable>] + SET <json-string> <member|index> [<member|index> ...] <value>) + +Set an element in ``<json-string>`` at the location +given by the list of ``<member|index>`` arguments to ``<value>``. +The contents of ``<value>`` should be valid JSON. + +.. _EQUAL: +.. code-block:: cmake + + string(JSON <out-var> [ERROR_VARIABLE <error-var>] + EQUAL <json-string1> <json-string2>) + +Compare the two JSON objects given by ``<json-string1>`` and ``<json-string2>`` +for equality. The contents of ``<json-string1>`` and ``<json-string2>`` +should be valid JSON. The ``<out-var>`` will be set to a true value if the +JSON objects are considered equal, or a false value otherwise. diff --git a/Help/command/subdir_depends.rst b/Help/command/subdir_depends.rst new file mode 100644 index 0000000..0c1b3c1 --- /dev/null +++ b/Help/command/subdir_depends.rst @@ -0,0 +1,13 @@ +subdir_depends +-------------- + +Disallowed since version 3.0. See CMake Policy :policy:`CMP0029`. + +Does nothing. + +:: + + subdir_depends(subdir dep1 dep2 ...) + +Does not do anything. This command used to help projects order +parallel builds correctly. This functionality is now automatic. diff --git a/Help/command/subdirs.rst b/Help/command/subdirs.rst new file mode 100644 index 0000000..530951b --- /dev/null +++ b/Help/command/subdirs.rst @@ -0,0 +1,26 @@ +subdirs +------- + +.. deprecated:: 3.0 + + Use the :command:`add_subdirectory` command instead. + +Add a list of subdirectories to the build. + +:: + + subdirs(dir1 dir2 ...[EXCLUDE_FROM_ALL exclude_dir1 exclude_dir2 ...] + [PREORDER] ) + +Add a list of subdirectories to the build. The :command:`add_subdirectory` +command should be used instead of ``subdirs`` although ``subdirs`` will still +work. This will cause any CMakeLists.txt files in the sub directories +to be processed by CMake. Any directories after the ``PREORDER`` flag are +traversed first by makefile builds, the ``PREORDER`` flag has no effect on +IDE projects. Any directories after the ``EXCLUDE_FROM_ALL`` marker will +not be included in the top level makefile or project file. This is +useful for having CMake create makefiles or projects for a set of +examples in a project. You would want CMake to generate makefiles or +project files for all the examples at the same time, but you would not +want them to show up in the top level project or be built each time +make is run from the top. diff --git a/Help/command/target_compile_definitions.rst b/Help/command/target_compile_definitions.rst new file mode 100644 index 0000000..3fb113a --- /dev/null +++ b/Help/command/target_compile_definitions.rst @@ -0,0 +1,50 @@ +target_compile_definitions +-------------------------- + +Add compile definitions to a target. + +.. code-block:: cmake + + target_compile_definitions(<target> + <INTERFACE|PUBLIC|PRIVATE> [items1...] + [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) + +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:`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 +same ``<target>`` append items in the order called. + +.. versionadded:: 3.11 + Allow setting ``INTERFACE`` items on :ref:`IMPORTED targets <Imported Targets>`. + +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 + +Definitions may optionally have values: + +.. code-block:: cmake + + target_compile_definitions(foo PUBLIC FOO=1) + +Note that many compilers treat ``-DFOO`` as equivalent to ``-DFOO=1``, but +other tools may not recognize this in all circumstances (e.g. IntelliSense). diff --git a/Help/command/target_compile_features.rst b/Help/command/target_compile_features.rst new file mode 100644 index 0000000..58502bf --- /dev/null +++ b/Help/command/target_compile_features.rst @@ -0,0 +1,37 @@ +target_compile_features +----------------------- + +.. versionadded:: 3.1 + +Add expected compiler features to a target. + +.. code-block:: cmake + + target_compile_features(<target> <PRIVATE|PUBLIC|INTERFACE> <feature> [...]) + +Specifies compiler features required when compiling a given target. If the +feature is not listed in the :variable:`CMAKE_C_COMPILE_FEATURES`, +:variable:`CMAKE_CUDA_COMPILE_FEATURES`, or :variable:`CMAKE_CXX_COMPILE_FEATURES` +variables, then an error will be reported by CMake. If the use of the feature requires +an additional compiler flag, such as ``-std=gnu++11``, the flag will be added +automatically. + +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. + +.. versionadded:: 3.11 + Allow setting ``INTERFACE`` items on :ref:`IMPORTED targets <Imported Targets>`. + +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>`. + +Arguments to ``target_compile_features`` 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. diff --git a/Help/command/target_compile_options.rst b/Help/command/target_compile_options.rst new file mode 100644 index 0000000..e45b209 --- /dev/null +++ b/Help/command/target_compile_options.rst @@ -0,0 +1,52 @@ +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...] ...]) + +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>`. + +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 +``<target>`` append items in the order called. + +.. versionadded:: 3.11 + Allow setting ``INTERFACE`` items on :ref:`IMPORTED targets <Imported Targets>`. + +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`. + +For file-specific settings, there is the source file property :prop_sf:`COMPILE_OPTIONS`. diff --git a/Help/command/target_include_directories.rst b/Help/command/target_include_directories.rst new file mode 100644 index 0000000..3e53b2e --- /dev/null +++ b/Help/command/target_include_directories.rst @@ -0,0 +1,64 @@ +target_include_directories +-------------------------- + +Add include directories to a target. + +.. code-block:: cmake + + target_include_directories(<target> [SYSTEM] [AFTER|BEFORE] + <INTERFACE|PUBLIC|PRIVATE> [items1...] + [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) + +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 +:ref:`ALIAS target <Alias Targets>`. + +By using ``AFTER`` or ``BEFORE`` explicitly, you can select between appending +and prepending, independent of the default. + +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. + +.. versionadded:: 3.11 + Allow setting ``INTERFACE`` items on :ref:`IMPORTED targets <Imported Targets>`. + +Specified include directories may be absolute paths or relative paths. +Repeated calls for the same <target> append items in the order called. If +``SYSTEM`` is specified, the compiler will be told the +directories are meant as system include directories on some platforms +(signalling this setting might achieve effects such as the compiler +skipping warnings, or these fixed-install system files not being +considered in dependency calculations - see compiler docs). If ``SYSTEM`` +is used together with ``PUBLIC`` or ``INTERFACE``, the +:prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` target property will be +populated with the specified directories. + +Arguments to ``target_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. + +Include directories 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 + + target_include_directories(mylib PUBLIC + $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib> + $<INSTALL_INTERFACE:include/mylib> # <prefix>/include/mylib + ) + +Creating Relocatable Packages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` +.. include:: /include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt diff --git a/Help/command/target_link_directories.rst b/Help/command/target_link_directories.rst new file mode 100644 index 0000000..bb75a3d --- /dev/null +++ b/Help/command/target_link_directories.rst @@ -0,0 +1,57 @@ +target_link_directories +----------------------- + +.. versionadded:: 3.13 + +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 new file mode 100644 index 0000000..872e264 --- /dev/null +++ b/Help/command/target_link_libraries.rst @@ -0,0 +1,322 @@ +target_link_libraries +--------------------- + +.. only:: html + + .. contents:: + +Specify libraries or flags to use when linking a given target and/or +its dependents. :ref:`Usage requirements <Target Usage Requirements>` +from linked library targets will be propagated. Usage requirements +of a target's dependencies affect compilation of its own sources. + +Overview +^^^^^^^^ + +This command has several signatures as detailed in subsections below. +All of them have the general form + +.. code-block:: cmake + + target_link_libraries(<target> ... <item>... ...) + +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. + +.. versionadded:: 3.13 + The ``<target>`` doesn't have to be defined in the same directory as the + ``target_link_libraries`` call. + +Each ``<item>`` may be: + +* **A library target name**: The generated link line will have the + full path to the linkable library file associated with the target. + The buildsystem will have a dependency to re-link ``<target>`` if + the library file changes. + + The named target must be created by :command:`add_library` within + the project or as an :ref:`IMPORTED library <Imported Targets>`. + If it is created within the project an ordering dependency will + automatically be added in the build system to make sure the named + library target is up-to-date before the ``<target>`` links. + + If an imported library has the :prop_tgt:`IMPORTED_NO_SONAME` + target property set, CMake may ask the linker to search for + 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. + + There are some cases where CMake may ask the linker to search for + the library (e.g. ``/usr/lib/libfoo.so`` becomes ``-lfoo``), such + 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 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. + + .. versionadded:: 3.8 + On :ref:`Visual Studio Generators` for VS 2010 and above, library files + ending in ``.targets`` will be treated as MSBuild targets files and + 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 + dependencies, so they are generally safe to specify only as private link + items that will not propagate to dependents. + + 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_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. + + .. versionadded:: 3.13 + :prop_tgt:`LINK_OPTIONS` target property and :command:`target_link_options` + command. For earlier versions of CMake, use :prop_tgt:`LINK_FLAGS` + property instead. + + 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 + corresponds to the ``Debug`` configuration (or to configurations named + in the :prop_gbl:`DEBUG_CONFIGURATIONS` global property if it is set). + The ``optimized`` keyword corresponds to all other configurations. The + ``general`` keyword corresponds to all configurations, and is purely + 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`. + +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>... + [<PRIVATE|PUBLIC|INTERFACE> <item>...]...) + +The ``PUBLIC``, ``PRIVATE`` and ``INTERFACE`` keywords can be used to +specify both the link dependencies and the link interface in one command. +Libraries and targets following ``PUBLIC`` are linked to, and are made +part of the link interface. Libraries and targets following ``PRIVATE`` +are linked to, but are not made part of the link interface. Libraries +following ``INTERFACE`` are appended to the link interface and are not +used for linking ``<target>``. + +Libraries for both a Target and its Dependents +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: cmake + + target_link_libraries(<target> <item>...) + +Library dependencies are transitive by default with this signature. +When this target is linked into another target then the libraries +linked to this target will appear on the link line for the other +target too. This transitive "link interface" is stored in the +:prop_tgt:`INTERFACE_LINK_LIBRARIES` target property and may be overridden +by setting the property directly. When :policy:`CMP0022` is not set to +``NEW``, transitive linking is built in but may be overridden by the +:prop_tgt:`LINK_INTERFACE_LIBRARIES` property. Calls to other signatures +of this command may set the property making any libraries linked +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>... + [<LINK_PRIVATE|LINK_PUBLIC> <lib>...]...) + +The ``LINK_PUBLIC`` and ``LINK_PRIVATE`` modes can be used to specify both +the link dependencies and the link interface in one command. + +This signature is for compatibility only. Prefer the ``PUBLIC`` or +``PRIVATE`` keywords instead. + +Libraries and targets following ``LINK_PUBLIC`` are linked to, and are +made part of the :prop_tgt:`INTERFACE_LINK_LIBRARIES`. If policy +:policy:`CMP0022` is not ``NEW``, they are also made part of the +:prop_tgt:`LINK_INTERFACE_LIBRARIES`. Libraries and targets following +``LINK_PRIVATE`` are linked to, but are not made part of the +:prop_tgt:`INTERFACE_LINK_LIBRARIES` (or :prop_tgt:`LINK_INTERFACE_LIBRARIES`). + +Libraries for Dependents Only (Legacy) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: cmake + + target_link_libraries(<target> LINK_INTERFACE_LIBRARIES <item>...) + +The ``LINK_INTERFACE_LIBRARIES`` mode appends the libraries to the +:prop_tgt:`INTERFACE_LINK_LIBRARIES` target property instead of using them +for linking. If policy :policy:`CMP0022` is not ``NEW``, then this mode +also appends libraries to the :prop_tgt:`LINK_INTERFACE_LIBRARIES` and its +per-configuration equivalent. + +This signature is for compatibility only. Prefer the ``INTERFACE`` mode +instead. + +Libraries specified as ``debug`` are wrapped in a generator expression to +correspond to debug builds. If policy :policy:`CMP0022` is +not ``NEW``, the libraries are also appended to the +:prop_tgt:`LINK_INTERFACE_LIBRARIES_DEBUG <LINK_INTERFACE_LIBRARIES_<CONFIG>>` +property (or to the properties corresponding to configurations listed in +the :prop_gbl:`DEBUG_CONFIGURATIONS` global property if it is set). +Libraries specified as ``optimized`` are appended to the +:prop_tgt:`INTERFACE_LINK_LIBRARIES` property. If policy :policy:`CMP0022` +is not ``NEW``, they are also appended to the +:prop_tgt:`LINK_INTERFACE_LIBRARIES` property. Libraries specified as +``general`` (or without any keyword) are treated as if specified for both +``debug`` and ``optimized``. + +Linking Object Libraries +^^^^^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 3.12 + +: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 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The library dependency graph is normally acyclic (a DAG), but in the case +of mutually-dependent ``STATIC`` libraries CMake allows the graph to +contain cycles (strongly connected components). When another target links +to one of the libraries, CMake repeats the entire connected component. +For example, the code + +.. code-block:: cmake + + add_library(A STATIC a.c) + add_library(B STATIC b.c) + target_link_libraries(A B) + target_link_libraries(B A) + add_executable(main main.c) + target_link_libraries(main A) + +links ``main`` to ``A B A B``. While one repetition is usually +sufficient, pathological object file and symbol arrangements can require +more. One may handle such cases by using the +:prop_tgt:`LINK_INTERFACE_MULTIPLICITY` target property or by manually +repeating the component in the last ``target_link_libraries`` call. +However, if two archives are really so interdependent they should probably +be combined into a single archive, perhaps by using :ref:`Object Libraries`. + +Creating Relocatable Packages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_LINK_LIBRARIES` +.. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt diff --git a/Help/command/target_link_options.rst b/Help/command/target_link_options.rst new file mode 100644 index 0000000..87dff39 --- /dev/null +++ b/Help/command/target_link_options.rst @@ -0,0 +1,54 @@ +target_link_options +------------------- + +.. versionadded:: 3.13 + +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>``. +The following arguments specify link options. Repeated calls for the same +``<target>`` append items in the order called. + +.. note:: + :ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items. + +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:: DEVICE_LINK_OPTIONS.txt + +.. 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 0000000..9f7dabb --- /dev/null +++ b/Help/command/target_precompile_headers.rst @@ -0,0 +1,125 @@ +target_precompile_headers +------------------------- + +.. versionadded:: 3.16 + +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 :genex:`$<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. For example: + +.. code-block:: cmake + + target_precompile_headers(myTarget + PUBLIC + project_header.h + PRIVATE + [["other_header.h"]] + <unordered_map> + ) + +Arguments to ``target_precompile_headers()`` may use "generator expressions" +with the syntax ``$<...>``. +See the :manual:`cmake-generator-expressions(7)` manual for available +expressions. +The :genex:`$<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``). In this case, header +file names that are not explicitly in double quotes or angle brackets +must be specified by absolute path. Also, when specifying angle brackets +inside a generator expression, be sure to encode the closing ``>`` as +``$<ANGLE-R>``. For example: + +.. code-block:: cmake + + target_precompile_headers(mylib PRIVATE + "$<$<COMPILE_LANGUAGE:CXX>:${CMAKE_CURRENT_SOURCE_DIR}/cxx_only.h>" + "$<$<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 artifact 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 new file mode 100644 index 0000000..520614a --- /dev/null +++ b/Help/command/target_sources.rst @@ -0,0 +1,48 @@ +target_sources +-------------- + +.. versionadded:: 3.1 + +Add sources to a target. + +.. code-block:: cmake + + target_sources(<target> + <INTERFACE|PUBLIC|PRIVATE> [items1...] + [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) + +Specifies sources to use when building a target and/or its dependents. +The named ``<target>`` must have been created by a command such as +:command:`add_executable` or :command:`add_library` or +:command:`add_custom_target` and must not be an +:ref:`ALIAS target <Alias Targets>`. + +.. versionchanged:: 3.13 + Relative source file paths are interpreted as being relative to the current + source directory (i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`). + See policy :policy:`CMP0076`. + +.. versionadded:: 3.20 + ``<target>`` can be a custom target. + +The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to +specify the scope of the items following them. ``PRIVATE`` and ``PUBLIC`` +items will populate the :prop_tgt:`SOURCES` property of +``<target>``, which are used when building the target itself. +``PUBLIC`` and ``INTERFACE`` items will populate the +:prop_tgt:`INTERFACE_SOURCES` property of ``<target>``, which are used +when building dependents. +The following arguments specify sources. Repeated calls for the same +``<target>`` append items in the order called. The targets created by +:command:`add_custom_target` can only have ``PRIVATE`` scope. + +.. versionadded:: 3.3 + Allow exporting targets with :prop_tgt:`INTERFACE_SOURCES`. + +.. versionadded:: 3.11 + Allow setting ``INTERFACE`` items on :ref:`IMPORTED targets <Imported Targets>`. + +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. diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst new file mode 100644 index 0000000..06da910 --- /dev/null +++ b/Help/command/try_compile.rst @@ -0,0 +1,214 @@ +try_compile +----------- + +.. only:: html + + .. contents:: + +Try building some code. + +Try Compiling Whole Projects +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: cmake + + 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 ``<resultVar>``. + +.. versionadded:: 3.14 + The name of the ``<resultVar>`` is defined by the user. Previously, it had + a fixed name ``RESULT_VAR``. + +In this form, ``<srcdir>`` should contain a complete CMake project with a +``CMakeLists.txt`` file and all sources. The ``<bindir>`` and ``<srcdir>`` +will not be deleted after this command is run. Specify ``<targetName>`` to +build a specific target instead of the ``all`` or ``ALL_BUILD`` target. See +below for the meaning of other options. + +Try Compiling Source Files +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: cmake + + 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>]] + [<LANG>_STANDARD <std>] + [<LANG>_STANDARD_REQUIRED <bool>] + [<LANG>_EXTENSIONS <bool>] + ) + +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>``. + +.. versionadded:: 3.14 + The name of the ``<resultVar>`` is defined by the user. Previously, it had + a fixed name ``RESULT_VAR``. + +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: + +``CMAKE_FLAGS <flags>...`` + Specify flags of the form ``-DVAR:TYPE=VALUE`` to be passed to + the ``cmake`` command-line used to drive the test build. + The above example shows how values for variables + ``INCLUDE_DIRECTORIES``, ``LINK_DIRECTORIES``, and ``LINK_LIBRARIES`` + are used. + +``COMPILE_DEFINITIONS <defs>...`` + Specify ``-Ddefinition`` arguments to pass to :command:`add_definitions` + in the generated test project. + +``COPY_FILE <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 + message encountered while trying to copy the file. + +``LINK_LIBRARIES <libs>...`` + Specify libraries to be linked in the generated project. + The list of libraries may refer to system libraries and to + :ref:`Imported Targets <Imported Targets>` from the calling project. + + If this option is specified, any ``-DLINK_LIBRARIES=...`` value + given to the ``CMAKE_FLAGS`` option will be ignored. + +``LINK_OPTIONS <options>...`` + .. versionadded:: 3.14 + + 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 in the given variable. + +``<LANG>_STANDARD <std>`` + .. versionadded:: 3.8 + + 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>`` + .. versionadded:: 3.8 + + Specify the :prop_tgt:`C_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>`` + .. versionadded:: 3.8 + + 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 +cleaned automatically. For debugging, ``--debug-trycompile`` can be +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 <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``. + +Other Behavior Settings +^^^^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 3.4 + If set, the following variables are passed in to the generated + try_compile CMakeLists.txt to initialize compile target properties with + default values: + + * :variable:`CMAKE_CUDA_RUNTIME_LIBRARY` + * :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. + +.. versionchanged:: 3.14 + 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. + +.. versionadded:: 3.6 + Set the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable to specify + the type of target used for the source file signature. + +.. versionadded:: 3.6 + 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 and is only honored by the + ``try_compile()`` command for the source files form, not when given a whole + project. + +.. versionchanged:: 3.8 + If :policy:`CMP0067` is set to ``NEW``, or any of the ``<LANG>_STANDARD``, + ``<LANG>_STANDARD_REQUIRED``, or ``<LANG>_EXTENSIONS`` options are used, + then the language standard variables are honored: + + * :variable:`CMAKE_C_STANDARD` + * :variable:`CMAKE_C_STANDARD_REQUIRED` + * :variable:`CMAKE_C_EXTENSIONS` + * :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). + +.. versionchanged:: 3.14 + 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 new file mode 100644 index 0000000..404de98 --- /dev/null +++ b/Help/command/try_run.rst @@ -0,0 +1,123 @@ +try_run +------- + +.. only:: html + + .. contents:: + +Try compiling and then running some code. + +Try Compiling and Running Source Files +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: cmake + + 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>] + [OUTPUT_VARIABLE <var>] + [WORKING_DIRECTORY <var>] + [ARGS <args>...]) + +Try compiling a ``<srcfile>``. Returns ``TRUE`` or ``FALSE`` for success +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. + +.. versionadded:: 3.14 + The names of the result variables ``<runResultVar>`` and + ``<compileResultVar>`` are defined by the user. Previously, they had + fixed names ``RUN_RESULT_VAR`` and ``COMPILE_RESULT_VAR``. + +The options are: + +``CMAKE_FLAGS <flags>...`` + Specify flags of the form ``-DVAR:TYPE=VALUE`` to be passed to + the ``cmake`` command-line used to drive the test build. + The example in :command:`try_compile` shows how values for variables + ``INCLUDE_DIRECTORIES``, ``LINK_DIRECTORIES``, and ``LINK_LIBRARIES`` + are used. + +``COMPILE_DEFINITIONS <defs>...`` + Specify ``-Ddefinition`` arguments to pass to :command:`add_definitions` + in the generated test project. + +``COMPILE_OUTPUT_VARIABLE <var>`` + Report the compile step build output in a given variable. + +``LINK_LIBRARIES <libs>...`` + .. versionadded:: 3.2 + + Specify libraries to be linked in the generated project. + The list of libraries may refer to system libraries and to + :ref:`Imported Targets <Imported Targets>` from the calling project. + + If this option is specified, any ``-DLINK_LIBRARIES=...`` value + given to the ``CMAKE_FLAGS`` option will be ignored. + +``LINK_OPTIONS <options>...`` + .. versionadded:: 3.14 + + 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 + ``COMPILE_OUTPUT_VARIABLE`` and ``RUN_OUTPUT_VARIABLE`` instead. + +``RUN_OUTPUT_VARIABLE <var>`` + Report the output from running the executable in a given variable. + +``WORKING_DIRECTORY <var>`` + .. versionadded:: 3.20 + + Run the executable in the given directory. If no ``WORKING_DIRECTORY`` is + specified, the executable will run in ``<bindir>``. + +Other Behavior Settings +^^^^^^^^^^^^^^^^^^^^^^^ + +Set the :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` variable to choose +a build configuration. + +Behavior when Cross Compiling +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 3.3 + Use ``CMAKE_CROSSCOMPILING_EMULATOR`` when running cross-compiled + binaries. + +When cross compiling, the executable compiled in the first step +usually cannot be run on the build host. The ``try_run`` command checks +the :variable:`CMAKE_CROSSCOMPILING` variable to detect whether CMake is in +cross-compiling mode. If that is the case, it will still try to compile +the executable, but it will not try to run the executable unless the +:variable:`CMAKE_CROSSCOMPILING_EMULATOR` variable is set. Instead it +will create cache variables which must be filled by the user or by +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: + +``<runResultVar>`` + Exit code if the executable were to be run on the target platform. + +``<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. + +In order to make cross compiling your project easier, use ``try_run`` +only if really required. If you use ``try_run``, use the +``RUN_OUTPUT_VARIABLE`` or ``OUTPUT_VARIABLE`` options only if really +required. Using them will require that when cross-compiling, the cache +variables will have to be set manually to the output of the executable. +You can also "guard" the calls to ``try_run`` with an :command:`if` +block checking the :variable:`CMAKE_CROSSCOMPILING` variable and +provide an easy-to-preset alternative for this case. diff --git a/Help/command/unset.rst b/Help/command/unset.rst new file mode 100644 index 0000000..7521052 --- /dev/null +++ b/Help/command/unset.rst @@ -0,0 +1,41 @@ +unset +----- + +Unset a variable, cache variable, or environment variable. + +Unset Normal Variable or Cache Entry +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: cmake + + unset(<variable> [CACHE | PARENT_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. + +Unset Environment Variable +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: cmake + + unset(ENV{<variable>}) + +Removes ``<variable>`` from the currently available +:manual:`Environment Variables <cmake-env-variables(7)>`. +Subsequent calls of ``$ENV{<variable>}`` will return the empty string. + +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 new file mode 100644 index 0000000..5b0e2ee --- /dev/null +++ b/Help/command/use_mangled_mesa.rst @@ -0,0 +1,15 @@ +use_mangled_mesa +---------------- + +Disallowed since version 3.0. See CMake Policy :policy:`CMP0030`. + +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 +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 new file mode 100644 index 0000000..94d6a4e --- /dev/null +++ b/Help/command/utility_source.rst @@ -0,0 +1,24 @@ +utility_source +-------------- + +Disallowed since version 3.0. See CMake Policy :policy:`CMP0034`. + +Specify the source tree of a third-party utility. + +:: + + utility_source(cache_entry executable_name + path_to_source [file1 file2 ...]) + +When a third-party utility's source is included in the distribution, +this command specifies its location and name. The cache entry will +not be set unless the ``path_to_source`` and all listed files exist. It +is assumed that the source tree of the utility will have been built +before it is needed. + +When cross compiling CMake will print a warning if a ``utility_source()`` +command is executed, because in many cases it is used to build an +executable which is executed later on. This doesn't work when cross +compiling, since the executable can run only on their target platform. +So in this case the cache entry has to be adjusted manually so it +points to an executable which is runnable on the build host. diff --git a/Help/command/variable_requires.rst b/Help/command/variable_requires.rst new file mode 100644 index 0000000..322b154 --- /dev/null +++ b/Help/command/variable_requires.rst @@ -0,0 +1,22 @@ +variable_requires +----------------- + +Disallowed since version 3.0. See CMake Policy :policy:`CMP0035`. + +Use the :command:`if` command instead. + +Assert satisfaction of an option's required variables. + +:: + + variable_requires(TEST_VARIABLE RESULT_VARIABLE + REQUIRED_VARIABLE1 + REQUIRED_VARIABLE2 ...) + +The first argument (``TEST_VARIABLE``) is the name of the variable to be +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 +reported. diff --git a/Help/command/variable_watch.rst b/Help/command/variable_watch.rst new file mode 100644 index 0000000..8293f5a --- /dev/null +++ b/Help/command/variable_watch.rst @@ -0,0 +1,48 @@ +variable_watch +-------------- + +Watch the CMake variable for change. + +.. code-block:: cmake + + variable_watch(<variable> [<command>]) + +If the specified ``<variable>`` changes and no ``<command>`` is given, +a message will be printed to inform about the change. + +If ``<command>`` is given, this command will be executed instead. +The command will receive the following arguments: +``COMMAND(<variable> <access> <value> <current_list_file> <stack>)`` + +``<variable>`` + Name of the variable being accessed. + +``<access>`` + One of ``READ_ACCESS``, ``UNKNOWN_READ_ACCESS``, ``MODIFIED_ACCESS``, + ``UNKNOWN_MODIFIED_ACCESS``, or ``REMOVED_ACCESS``. The ``UNKNOWN_`` + values are only used when the variable has never been set. Once set, + they are never used again during the same CMake run, even if the + variable is later unset. + +``<value>`` + The value of the variable. On a modification, this is the new + (modified) value of the variable. On removal, the value is empty. + +``<current_list_file>`` + Full path to the file doing the access. + +``<stack>`` + List of absolute paths of all files currently on the stack of file + inclusion, with the bottom-most file first and the currently + processed file (that is, ``current_list_file``) last. + +Note that for some accesses such as :command:`list(APPEND)`, the watcher +is executed twice, first with a read access and then with a write one. +Also note that an :command:`if(DEFINED)` query on the variable does not +register as an access and the watcher is not executed. + +Only non-cache variables can be watched using this command. Access to +cache variables is never watched. However, the existence of a cache +variable ``var`` causes accesses to the non-cache variable ``var`` to +not use the ``UNKNOWN_`` prefix, even if a non-cache variable ``var`` +has never existed. diff --git a/Help/command/while.rst b/Help/command/while.rst new file mode 100644 index 0000000..a4957c1 --- /dev/null +++ b/Help/command/while.rst @@ -0,0 +1,25 @@ +while +----- + +Evaluate a group of commands while a condition is true + +.. code-block:: cmake + + 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>`` 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 new file mode 100644 index 0000000..4d476bd --- /dev/null +++ b/Help/command/write_file.rst @@ -0,0 +1,22 @@ +write_file +---------- + +.. deprecated:: 3.0 + + Use the :command:`file(WRITE)` command instead. + +:: + + write_file(filename "message to write"... [APPEND]) + +The first argument is the file name, the rest of the arguments are +messages to write. If the argument ``APPEND`` is specified, then the +message will be appended. + +NOTE 1: :command:`file(WRITE)` and :command:`file(APPEND)` do exactly +the same as this one but add some more functionality. + +NOTE 2: When using ``write_file`` the produced file cannot be used as an +input to CMake (CONFIGURE_FILE, source file ...) because it will lead +to an infinite loop. Use :command:`configure_file` if you want to +generate input files to CMake. diff --git a/Help/cpack_gen/archive.rst b/Help/cpack_gen/archive.rst new file mode 100644 index 0000000..b941812 --- /dev/null +++ b/Help/cpack_gen/archive.rst @@ -0,0 +1,88 @@ +CPack Archive Generator +----------------------- + +CPack generator for packaging files into an archive, which can have +any of the following formats: + + - 7Z - 7zip - (.7z) + - TBZ2 (.tar.bz2) + - TGZ (.tar.gz) + - TXZ (.tar.xz) + - TZ (.tar.Z) + - TZST (.tar.zst) + - ZIP (.zip) + +.. versionadded:: 3.1 + ``7Z`` and ``TXZ`` formats support. + +.. versionadded:: 3.16 + ``TZST`` format support. + +When this generator is called from ``CPackSourceConfig.cmake`` (or through +the ``package_source`` target), then the generated archive will contain all +files in the project directory, except those specified in +:variable:`CPACK_SOURCE_IGNORE_FILES`. The following is one example of +packaging all source files of a project: + +.. code-block:: cmake + + set(CPACK_SOURCE_GENERATOR "TGZ") + set(CPACK_SOURCE_IGNORE_FILES + \\.git/ + build/ + ".*~$" + ) + set(CPACK_VERBATIM_VARIABLES YES) + include(CPack) + +When this generator is called from ``CPackConfig.cmake`` (or through the +``package`` target), then the generated archive will contain all files +that have been installed via CMake's :command:`install` command (and the +deprecated commands :command:`install_files`, :command:`install_programs`, +and :command:`install_targets`). + +Variables specific to CPack Archive generator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. variable:: CPACK_ARCHIVE_FILE_NAME + CPACK_ARCHIVE_<component>_FILE_NAME + + Package file name without extension. The extension is determined from the + archive format (see list above) and automatically appended to the file name. + The default is ``<CPACK_PACKAGE_FILE_NAME>[-<component>]``, with spaces + replaced by '-'. + + .. versionadded:: 3.9 + Per-component ``CPACK_ARCHIVE_<component>_FILE_NAME`` variables. + +.. variable:: CPACK_ARCHIVE_COMPONENT_INSTALL + + Enable component packaging. If enabled (ON), then the archive generator + creates multiple packages. The default is OFF, which means that a single + package containing files of all components is generated. + +Variables used by CPack Archive generator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +These variables are used by the Archive generator, but are also available to +CPack generators which are essentially archives at their core. These include: + + - :cpack_gen:`CPack Cygwin Generator` + - :cpack_gen:`CPack FreeBSD Generator` + +.. variable:: CPACK_ARCHIVE_THREADS + + .. versionadded:: 3.18 + + The number of threads to use when performing the compression. If set to + ``0``, the number of available cores on the machine will be used instead. + The default is ``1`` which limits compression to a single thread. Note that + not all compression modes support threading in all environments. Currently, + only the XZ compression may support it. + + See also the :variable:`CPACK_THREADS` variable. + +.. note:: + + Official CMake binaries available on ``cmake.org`` ship with a ``liblzma`` + that does not support parallel compression. diff --git a/Help/cpack_gen/bundle.rst b/Help/cpack_gen/bundle.rst new file mode 100644 index 0000000..5e335c0 --- /dev/null +++ b/Help/cpack_gen/bundle.rst @@ -0,0 +1,76 @@ +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 + + .. versionadded:: 3.2 + + 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 + + .. versionadded:: 3.2 + + 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 + + .. versionadded:: 3.2 + + 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 + + .. versionadded:: 3.3 + + Additional parameter that will passed to ``codesign``. + Default value: ``--deep -f`` + +.. variable:: CPACK_COMMAND_CODESIGN + + .. versionadded:: 3.2 + + 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 0000000..c537a79 --- /dev/null +++ b/Help/cpack_gen/cygwin.rst @@ -0,0 +1,30 @@ +CPack Cygwin Generator +---------------------- + +Cygwin CPack generator (Cygwin). + +Variables affecting the CPack Cygwin generator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- .. versionadded:: 3.18 + :variable:`CPACK_ARCHIVE_THREADS` + + +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 0000000..03c4ea8 --- /dev/null +++ b/Help/cpack_gen/deb.rst @@ -0,0 +1,678 @@ +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. + + .. versionadded:: 3.5 + Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_NAME`` variables. + + See https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Source + +.. variable:: CPACK_DEBIAN_FILE_NAME + CPACK_DEBIAN_<COMPONENT>_FILE_NAME + + .. versionadded:: 3.6 + + 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. + + .. versionadded:: 3.10 + ``.ipk`` suffix used by OPKG packaging system. + + .. 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 + + .. versionadded:: 3.10 + + 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 + + .. versionadded:: 3.6 + + 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) + + .. versionadded:: 3.6 + Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_ARCHITECTURE`` variables. + +.. 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. + + + .. versionadded:: 3.3 + Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS`` variables. + + .. 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 + + .. versionadded:: 3.6 + + 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`_. + + .. versionadded:: 3.3 + Per-component ``CPACK_COMPONENT_<compName>_DESCRIPTION`` variables. + + .. versionadded:: 3.16 + Per-component ``CPACK_DEBIAN_<COMPONENT>_DESCRIPTION`` variables. + + .. versionadded:: 3.16 + The ``CPACK_PACKAGE_DESCRIPTION_FILE`` variable. + +.. _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" + + .. versionadded:: 3.5 + Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_SECTION`` variables. + + See https://www.debian.org/doc/debian-policy/ch-archive.html#s-subsections + +.. variable:: CPACK_DEBIAN_ARCHIVE_TYPE + + .. versionadded:: 3.7 + + .. deprecated:: 3.14 + + 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 + + .. versionadded:: 3.1 + + 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" + + .. versionadded:: 3.5 + Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_PRIORITY`` varables. + + 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` + + .. versionadded:: 3.12 + The ``CMAKE_PROJECT_HOMEPAGE_URL`` variable. + + .. 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 + + .. note:: + + You can also set :variable:`CPACK_DEBIAN_PACKAGE_SHLIBDEPS_PRIVATE_DIRS` + to an appropriate value if you use this feature, in order to please + ``dpkg-shlibdeps``. However, you should only do this for private + shared libraries that could not get resolved otherwise. + + .. versionadded:: 3.3 + Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS`` variables. + + .. versionadded:: 3.6 + Correct handling of ``$ORIGIN`` in :variable:`CMAKE_INSTALL_RPATH`. + +.. variable:: CPACK_DEBIAN_PACKAGE_SHLIBDEPS_PRIVATE_DIRS + + .. versionadded:: 3.20 + + May be set to a list of directories that will be given to ``dpkg-shlibdeps`` + via its ``-l`` option. These will be searched by ``dpkg-shlibdeps`` in order + to find private shared library dependencies. + + * Mandatory : NO + * Default : + + .. note:: + + You should prefer to set :variable:`CMAKE_INSTALL_RPATH` to an appropriate + value if you use ``dpkg-shlibdeps``. The current option is really only + needed for private shared library dependencies. + +.. 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. + + .. versionadded:: 3.4 + Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_PREDEPENDS`` variables. + + 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. + + .. versionadded:: 3.4 + Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_ENHANCES`` variables. + + 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. + + .. versionadded:: 3.4 + Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_BREAKS`` variables. + + 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. + + .. versionadded:: 3.4 + Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONFLICTS`` variables. + + 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. + + .. versionadded:: 3.4 + Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_PROVIDES`` variables. + + 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. + + .. versionadded:: 3.4 + Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_REPLACES`` variables. + + 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. + + .. versionadded:: 3.4 + Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_RECOMMENDS`` variables. + + 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. + + .. versionadded:: 3.4 + Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_SUGGESTS`` variables. + + See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps + +.. variable:: CPACK_DEBIAN_PACKAGE_GENERATE_SHLIBS + + .. versionadded:: 3.6 + + * 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 + + .. versionadded:: 3.6 + + 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") + + .. versionadded:: 3.4 + Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONTROL_EXTRA`` variables. + +.. variable:: CPACK_DEBIAN_PACKAGE_CONTROL_STRICT_PERMISSION + CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONTROL_STRICT_PERMISSION + + .. versionadded:: 3.4 + + 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) + + 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 + + .. note:: + + The original permissions of the files will be used in the final + package unless this variable is set to ``TRUE``. + In particular, the scripts should have the proper executable + flag prior to the generation of the package. + +.. variable:: CPACK_DEBIAN_PACKAGE_SOURCE + CPACK_DEBIAN_<COMPONENT>_PACKAGE_SOURCE + + .. versionadded:: 3.5 + + 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 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 3.13 + +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 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 3.10 + +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 +^^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 3.13 + +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 0000000..ec2cf1e --- /dev/null +++ b/Help/cpack_gen/dmg.rst @@ -0,0 +1,129 @@ +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 + + .. versionadded:: 3.5 + + 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 + + .. versionadded:: 3.6 + + 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 + + .. versionadded:: 3.5 + + 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`` or ``<language>.license.rtf`` 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. If both + ``<language>.license.txt`` and ``<language>.license.rtf`` exist, the ``.txt`` + file will be used. + + .. versionadded:: 3.17 + RTF support. + +.. variable:: CPACK_DMG_SLA_LANGUAGES + + .. versionadded:: 3.5 + + 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_DMG_<component>_FILE_NAME + + .. versionadded:: 3.17 + + File name when packaging ``<component>`` as its own DMG + (``CPACK_COMPONENTS_GROUPING`` set to IGNORE). + + - Default: ``CPACK_PACKAGE_FILE_NAME-<component>`` + +.. variable:: CPACK_DMG_FILESYSTEM + + The filesystem format. Common values are ``APFS`` and ``HFS+``. + See ``man hdiutil`` for a full list of supported formats. + Defaults to ``HFS+``. + +.. 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 0000000..4c083f0 --- /dev/null +++ b/Help/cpack_gen/external.rst @@ -0,0 +1,294 @@ +CPack External Generator +------------------------ + +.. versionadded:: 3.13 + +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. + +.. variable:: CPACK_EXTERNAL_BUILT_PACKAGES + + .. versionadded:: 3.19 + + The ``CPACK_EXTERNAL_PACKAGE_SCRIPT`` script may set this list variable to the + full paths of generated package files. CPack will copy these files from the + staging directory back to the top build directory and possibly produce + checksum files if the :variable:`CPACK_PACKAGE_CHECKSUM` is set. diff --git a/Help/cpack_gen/freebsd.rst b/Help/cpack_gen/freebsd.rst new file mode 100644 index 0000000..2c93569 --- /dev/null +++ b/Help/cpack_gen/freebsd.rst @@ -0,0 +1,149 @@ +CPack FreeBSD Generator +----------------------- + +.. versionadded:: 3.10 + +The built in (binary) CPack FreeBSD (pkg) generator (Unix only) + +Variables affecting the CPack FreeBSD (pkg) generator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- .. versionadded:: 3.18 + :variable:`CPACK_ARCHIVE_THREADS` + +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). + + .. versionadded:: 3.12 + The ``CMAKE_PROJECT_HOMEPAGE_URL`` variable. + +.. 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 0000000..6817eac --- /dev/null +++ b/Help/cpack_gen/ifw.rst @@ -0,0 +1,407 @@ +CPack IFW Generator +------------------- + +.. versionadded:: 3.1 + +Configure and run the Qt Installer Framework to generate a Qt installer. + +.. only:: html + + .. contents:: + +Overview +^^^^^^^^ + +This :manual:`cpack generator <cpack-generators(7)>` generates +configuration and meta information for the `Qt Installer Framework +<http://doc.qt.io/qtinstallerframework/index.html>`_ (QtIFW), +and runs QtIFW tools to generate a Qt installer. + +QtIFW provides tools and utilities to create installers for +the platforms supported by `Qt <https://www.qt.io>`_: Linux, +Microsoft Windows, and macOS. + +To make use of this generator, QtIFW needs to be installed. +The :module:`CPackIFW` module looks for the location of the +QtIFW command-line utilities, and defines several commands to +control the behavior of this generator. + +Variables +^^^^^^^^^ + +You can use the following variables to change behavior of CPack ``IFW`` +generator. + +Debug +""""" + +.. variable:: CPACK_IFW_VERBOSE + + .. versionadded:: 3.3 + + 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 + + .. versionadded:: 3.8 + + Filename for a watermark is used as QWizard::WatermarkPixmap. + +.. variable:: CPACK_IFW_PACKAGE_BANNER + + .. versionadded:: 3.8 + + Filename for a banner is used as QWizard::BannerPixmap. + +.. variable:: CPACK_IFW_PACKAGE_BACKGROUND + + .. versionadded:: 3.8 + + Filename for an image used as QWizard::BackgroundPixmap (only used by MacStyle). + +.. variable:: CPACK_IFW_PACKAGE_WIZARD_STYLE + + .. versionadded:: 3.8 + + Wizard style to be used ("Modern", "Mac", "Aero" or "Classic"). + +.. variable:: CPACK_IFW_PACKAGE_WIZARD_DEFAULT_WIDTH + + .. versionadded:: 3.8 + + Default width of the wizard in pixels. Setting a banner image will override this. + +.. variable:: CPACK_IFW_PACKAGE_WIZARD_DEFAULT_HEIGHT + + .. versionadded:: 3.8 + + Default height of the wizard in pixels. Setting a watermark image will override this. + +.. variable:: CPACK_IFW_PACKAGE_WIZARD_SHOW_PAGE_LIST + + .. versionadded:: 3.20 + + Set to ``OFF`` if the widget listing installer pages on the left side of the wizard should not be shown. + + It is ``ON`` by default, but will only have an effect if using QtIFW 4.0 or later. + +.. variable:: CPACK_IFW_PACKAGE_TITLE_COLOR + + .. versionadded:: 3.8 + + Color of the titles and subtitles (takes an HTML color code, such as "#88FF33"). + +.. variable:: CPACK_IFW_PACKAGE_STYLE_SHEET + + .. versionadded:: 3.15 + + Filename for a stylesheet. + +.. variable:: CPACK_IFW_TARGET_DIRECTORY + + Default target directory for installation. + By default used + "@ApplicationsDir@/:variable:`CPACK_PACKAGE_INSTALL_DIRECTORY`" + (variables embedded in '@' are expanded by the + `QtIFW scripting engine <https://doc.qt.io/qtinstallerframework/scripting.html>`_). + + 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_REMOVE_TARGET_DIR + + .. versionadded:: 3.11 + + Set to ``OFF`` if the target directory should not be deleted when uninstalling. + + Is ``ON`` by default + +.. 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_START_MENU_DIRECTORY + + .. versionadded:: 3.3 + + 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_PACKAGE_MAINTENANCE_TOOL_NAME + + .. versionadded:: 3.3 + + Filename of the generated maintenance tool. + The platform-specific executable file extension is appended. + + By default used QtIFW defaults (``maintenancetool``). + +.. variable:: CPACK_IFW_PACKAGE_MAINTENANCE_TOOL_INI_FILE + + .. versionadded:: 3.3 + + Filename for the configuration of the generated maintenance tool. + + By default used QtIFW defaults (``maintenancetool.ini``). + +.. variable:: CPACK_IFW_PACKAGE_ALLOW_NON_ASCII_CHARACTERS + + .. versionadded:: 3.3 + + 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 + + .. versionadded:: 3.3 + + 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 + + .. versionadded:: 3.3 + + Filename for a custom installer control script. + +.. variable:: CPACK_IFW_PACKAGE_RESOURCES + + .. versionadded:: 3.7 + + 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 + + .. versionadded:: 3.10 + + 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 + + .. versionadded:: 3.10 + + Additional prepared repository dirs that will be used to resolve and + repack dependent components. This feature available only + since QtIFW 3.1. + +QtIFW Tools +""""""""""" + +.. variable:: CPACK_IFW_FRAMEWORK_VERSION + + .. versionadded:: 3.3 + + The version of used QtIFW tools. + +The following variables provide the locations of the QtIFW +command-line tools as discovered by the module :module:`CPackIFW`. +These variables are cached, and may be configured if needed. + +.. variable:: CPACK_IFW_ARCHIVEGEN_EXECUTABLE + + .. versionadded:: 3.19 + + The path to ``archivegen``. + +.. variable:: CPACK_IFW_BINARYCREATOR_EXECUTABLE + + The path to ``binarycreator``. + +.. variable:: CPACK_IFW_REPOGEN_EXECUTABLE + + The path to ``repogen``. + +.. variable:: CPACK_IFW_INSTALLERBASE_EXECUTABLE + + The path to ``installerbase``. + +.. variable:: CPACK_IFW_DEVTOOL_EXECUTABLE + + The path to ``devtool``. + +Hints for Finding QtIFW +""""""""""""""""""""""" + +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 + + .. versionadded:: 3.9 + + 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. + +Other Settings +^^^^^^^^^^^^^^ + +Online installer +"""""""""""""""" + +By default, this generator generates an *offline installer*. This means that +that all packaged files are fully contained in the installer executable. + +In contrast, an *online installer* will download some or all components from +a remote server. + +The ``DOWNLOADED`` option in the :command:`cpack_add_component` command +specifies that a component is to be downloaded. Alternatively, the ``ALL`` +option in the :command:`cpack_configure_downloads` command specifies that +`all` components are to be be downloaded. + +The :command:`cpack_ifw_add_repository` command and the +:variable:`CPACK_IFW_DOWNLOAD_ALL` variable allow for more specific +configuration. + +When there are online components, CPack will write them to archive files. +The help page of the :module:`CPackComponent` module, especially the section +on the :command:`cpack_configure_downloads` function, explains how to make +these files accessible from a download URL. + +Internationalization +"""""""""""""""""""" + +.. versionadded:: 3.9 + +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" + ) + +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 your 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 0000000..02e33ba --- /dev/null +++ b/Help/cpack_gen/nsis.rst @@ -0,0 +1,203 @@ +CPack NSIS Generator +-------------------- + +CPack Nullsoft Scriptable Install System (NSIS) generator specific options. + +.. versionchanged:: 3.17 + The NSIS generator requires NSIS 3.0 or newer. + +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 + + .. versionadded:: 3.5 + + The filename of a bitmap to use as the NSIS ``MUI_WELCOMEFINISHPAGE_BITMAP``. + +.. variable:: CPACK_NSIS_MUI_UNWELCOMEFINISHPAGE_BITMAP + + .. versionadded:: 3.5 + + 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 + + .. versionadded:: 3.7 + + 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") + +.. variable:: CPACK_NSIS_UNINSTALL_NAME + + .. versionadded:: 3.17 + + Specify the name of the program to uninstall the version. + Default is ``Uninstall``. + +.. variable:: CPACK_NSIS_WELCOME_TITLE + + .. versionadded:: 3.17 + + The title to display on the top of the page for the welcome page. + +.. variable:: CPACK_NSIS_WELCOME_TITLE_3LINES + + .. versionadded:: 3.17 + + Display the title in the welcome page on 3 lines instead of 2. + +.. variable:: CPACK_NSIS_FINISH_TITLE + + .. versionadded:: 3.17 + + The title to display on the top of the page for the finish page. + +.. variable:: CPACK_NSIS_FINISH_TITLE_3LINES + + .. versionadded:: 3.17 + + Display the title in the finish page on 3 lines instead of 2. + +.. variable:: CPACK_NSIS_MUI_HEADERIMAGE + + .. versionadded:: 3.17 + + The image to display on the header of installers pages. + +.. variable:: CPACK_NSIS_MANIFEST_DPI_AWARE + + .. versionadded:: 3.18 + + If set, declares that the installer is DPI-aware. + +.. variable:: CPACK_NSIS_BRANDING_TEXT + + .. versionadded:: 3.20 + + If set, updates the text at the bottom of the install window. + To set the string to blank, use a space (" "). + +.. variable:: CPACK_NSIS_BRANDING_TEXT_TRIM_POSITION + + .. versionadded:: 3.20 + + If set, trim down the size of the control to the size of the branding text string. + Allowed values for this variable are ``LEFT``, ``CENTER`` or ``RIGHT``. + If not specified, the default behavior is ``LEFT``. + +.. variable:: CPACK_NSIS_EXECUTABLE + + .. versionadded:: 3.21 + + If set, specify the name of the NSIS executable. Default is ``makensis``. diff --git a/Help/cpack_gen/nuget.rst b/Help/cpack_gen/nuget.rst new file mode 100644 index 0000000..c980dd6 --- /dev/null +++ b/Help/cpack_gen/nuget.rst @@ -0,0 +1,255 @@ +CPack NuGet Generator +--------------------- + +.. versionadded:: 3.12 + +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_FILE_NAME`` 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. ``CPACK_NUGET_PACKAGE_NAME`` is used as the + package ``id`` on nuget.org_ + + * 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 + + An 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 + + .. deprecated:: 3.20 + Use a local license file + (:variable:`CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME`) + or a `(SPDX) license identifier`_ + (:variable:`CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION`) instead. + + An URL for the package's license, often shown in UI displays as well + as on nuget.org_. + + * Mandatory : NO + * Default : - + +.. variable:: CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION + CPACK_NUGET_<compName>_PACKAGE_LICENSE_EXPRESSION + + .. versionadded:: 3.20 + + A Software Package Data Exchange `(SPDX) license identifier`_ such as + ``MIT``, ``BSD-3-Clause``, or ``LGPL-3.0-or-later``. In the case of a + choice of licenses or more complex restrictions, compound license + expressions may be formed using boolean operators, for example + ``MIT OR BSD-3-Clause``. See the `SPDX specification`_ for guidance + on forming complex license expressions. + + If ``CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME`` is specified, + ``CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION`` is ignored. + + * Mandatory : NO + * Default : - + +.. variable:: CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME + CPACK_NUGET_<compName>_PACKAGE_LICENSE_FILE_NAME + + The package's license file in :file:`.txt` or :file:`.md` format. + + If ``CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME`` is specified, + ``CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION`` is ignored. + + .. versionadded:: 3.20 + + * Mandatory : NO + * Default : - + +.. variable:: CPACK_NUGET_PACKAGE_ICONURL + CPACK_NUGET_<compName>_PACKAGE_ICONURL + + .. deprecated:: 3.20 + Use a local icon file (:variable:`CPACK_NUGET_PACKAGE_ICON`) instead. + + An 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_ICON + CPACK_NUGET_<compName>_PACKAGE_ICON + + .. versionadded:: 3.20 + + The filename of 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_LANGUAGE + CPACK_NUGET_<compName>_PACKAGE_LANGUAGE + + .. versionadded:: 3.20 + + Locale specifier for the package, for example ``en_CA``. + + * 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 +.. _(SPDX) license identifier: https://spdx.org/licenses/ +.. _SPDX specification: https://spdx.github.io/spdx-spec/appendix-IV-SPDX-license-expressions/ + +.. 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 0000000..256446d --- /dev/null +++ b/Help/cpack_gen/packagemaker.rst @@ -0,0 +1,87 @@ +CPack PackageMaker Generator +---------------------------- + +PackageMaker CPack generator (macOS). + +.. deprecated:: 3.17 + + Xcode no longer distributes the PackageMaker tools. + This CPack generator will be removed in a future version of CPack. + +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 + components on-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. + +Background Image +"""""""""""""""" + +.. versionadded:: 3.17 + +This group of variables controls the background image of the generated +installer. + +.. variable:: CPACK_PACKAGEMAKER_BACKGROUND + + Adds a background to Distribution XML if specified. The value contains the + path to image in ``Resources`` directory. + +.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_ALIGNMENT + + Adds an ``alignment`` attribute to the background in Distribution XML. + Refer to Apple documentation for valid values. + +.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_SCALING + + Adds a ``scaling`` attribute to the background in Distribution XML. + Refer to Apple documentation for valid values. + +.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_MIME_TYPE + + Adds a ``mime-type`` attribute to the background in Distribution XML. + The option contains MIME type of an image. + +.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_UTI + + Adds an ``uti`` attribute to the background in Distribution XML. + The option contains UTI type of an image. + +.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA + + Adds a background for the Dark Aqua theme to Distribution XML if + specified. The value contains the path to image in ``Resources`` + directory. + +.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_ALIGNMENT + + Does the same as :variable:`CPACK_PACKAGEMAKER_BACKGROUND_ALIGNMENT` option, + but for the dark theme. + +.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_SCALING + + Does the same as :variable:`CPACK_PACKAGEMAKER_BACKGROUND_SCALING` option, + but for the dark theme. + +.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_MIME_TYPE + + Does the same as :variable:`CPACK_PACKAGEMAKER_BACKGROUND_MIME_TYPE` option, + but for the dark theme. + +.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_UTI + + Does the same as :variable:`CPACK_PACKAGEMAKER_BACKGROUND_UTI` option, + but for the dark theme. diff --git a/Help/cpack_gen/productbuild.rst b/Help/cpack_gen/productbuild.rst new file mode 100644 index 0000000..cf3041f --- /dev/null +++ b/Help/cpack_gen/productbuild.rst @@ -0,0 +1,138 @@ +CPack productbuild Generator +---------------------------- + +.. versionadded:: 3.7 + +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 + + .. versionadded:: 3.8 + + Adds a digital signature to the resulting package. + + +.. variable:: CPACK_PRODUCTBUILD_KEYCHAIN_PATH + + .. versionadded:: 3.8 + + 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 + + .. versionadded:: 3.8 + + Adds a digital signature to the resulting package. + + +.. variable:: CPACK_PKGBUILD_KEYCHAIN_PATH + + .. versionadded:: 3.8 + + 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 + + .. versionadded:: 3.9 + + 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. + +Background Image +"""""""""""""""" + +.. versionadded:: 3.17 + +This group of variables controls the background image of the generated +installer. + +.. variable:: CPACK_PRODUCTBUILD_BACKGROUND + + Adds a background to Distribution XML if specified. The value contains the + path to image in ``Resources`` directory. + +.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_ALIGNMENT + + Adds an ``alignment`` attribute to the background in Distribution XML. + Refer to Apple documentation for valid values. + +.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_SCALING + + Adds a ``scaling`` attribute to the background in Distribution XML. + Refer to Apple documentation for valid values. + +.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_MIME_TYPE + + Adds a ``mime-type`` attribute to the background in Distribution XML. + The option contains MIME type of an image. + +.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_UTI + + Adds an ``uti`` attribute to the background in Distribution XML. + The option contains UTI type of an image. + +.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA + + Adds a background for the Dark Aqua theme to Distribution XML if + specified. The value contains the path to image in ``Resources`` + directory. + +.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA_ALIGNMENT + + Does the same as :variable:`CPACK_PRODUCTBUILD_BACKGROUND_ALIGNMENT` option, + but for the dark theme. + +.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA_SCALING + + Does the same as :variable:`CPACK_PRODUCTBUILD_BACKGROUND_SCALING` option, + but for the dark theme. + +.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA_MIME_TYPE + + Does the same as :variable:`CPACK_PRODUCTBUILD_BACKGROUND_MIME_TYPE` option, + but for the dark theme. + +.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA_UTI + + Does the same as :variable:`CPACK_PRODUCTBUILD_BACKGROUND_UTI` option, + but for the dark theme. diff --git a/Help/cpack_gen/rpm.rst b/Help/cpack_gen/rpm.rst new file mode 100644 index 0000000..5260a1d --- /dev/null +++ b/Help/cpack_gen/rpm.rst @@ -0,0 +1,1035 @@ +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 + +.. versionchanged:: 3.6 + + `<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` + + .. versionadded:: 3.2 + Per-component ``CPACK_RPM_<component>_PACKAGE_SUMMARY`` variables. + +.. variable:: CPACK_RPM_PACKAGE_NAME + CPACK_RPM_<component>_PACKAGE_NAME + + The RPM package name. + + * Mandatory : YES + * Default : :variable:`CPACK_PACKAGE_NAME` + + .. versionadded:: 3.5 + Per-component ``CPACK_RPM_<component>_PACKAGE_NAME`` variables. + +.. variable:: CPACK_RPM_FILE_NAME + CPACK_RPM_<component>_FILE_NAME + + .. versionadded:: 3.6 + + 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 + + .. versionadded:: 3.8 + + 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 + + .. versionadded:: 3.10 + + 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. + + .. versionadded:: 3.3 + Per-component ``CPACK_RPM_<component>_PACKAGE_ARCHITECTURE`` variables. + +.. 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 + + .. versionadded:: 3.6 + + 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" + + .. versionadded:: 3.5 + Per-component ``CPACK_RPM_<component>_PACKAGE_GROUP`` variables. + +.. 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` + + .. versionadded:: 3.12 + The ``CMAKE_PROJECT_HOMEPAGE_URL`` variable. + +.. 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" + + .. versionadded:: 3.2 + Per-component ``CPACK_RPM_<component>_PACKAGE_DESCRIPTION`` variables. + +.. 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 + + .. versionadded:: 3.2 + + 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 + + .. versionadded:: 3.2 + + 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 + + .. versionadded:: 3.2 + + 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 + + .. versionadded:: 3.2 + + 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 + CPACK_RPM_PRE_TRANS_SCRIPT_FILE + + Path to file containing pre install/uninstall/transaction script. + + * Mandatory : NO + * Default : - + + May be used to embed a pre installation/uninstallation/transaction 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 install/uninstall/transaction + script for each component can be overridden with + ``CPACK_RPM_<COMPONENT>_PRE_INSTALL_SCRIPT_FILE``, + ``CPACK_RPM_<COMPONENT>_PRE_UNINSTALL_SCRIPT_FILE``, and + ``CPACK_RPM_<COMPONENT>_PRE_TRANS_SCRIPT_FILE`` + One may verify which scriptlet has been included with:: + + rpm -qp --scripts package.rpm + + .. versionadded:: 3.18 + The ``CPACK_RPM_PRE_TRANS_SCRIPT_FILE`` variable. + +.. variable:: CPACK_RPM_POST_INSTALL_SCRIPT_FILE + CPACK_RPM_POST_UNINSTALL_SCRIPT_FILE + CPACK_RPM_POST_TRANS_SCRIPT_FILE + + Path to file containing post install/uninstall/transaction script. + + * Mandatory : NO + * Default : - + + May be used to embed a post installation/uninstallation/transaction 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 install/uninstall/transaction + script for each component can be overridden with + ``CPACK_RPM_<COMPONENT>_POST_INSTALL_SCRIPT_FILE``, + ``CPACK_RPM_<COMPONENT>_POST_UNINSTALL_SCRIPT_FILE``, and + ``CPACK_RPM_<COMPONENT>_POST_TRANS_SCRIPT_FILE`` + One may verify which scriptlet has been included with:: + + rpm -qp --scripts package.rpm + + .. versionadded:: 3.18 + The ``CPACK_RPM_POST_TRANS_SCRIPT_FILE`` variable. + +.. 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. 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. + + .. versionadded:: 3.8 + You can have multiple directives per line, as in + ``%attr(600,root,root) %config(noreplace)``. + +.. 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. + + .. versionadded:: 3.10 + Added ``/usr/share/aclocal`` to the default list of excludes. + +.. 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 + + .. versionadded:: 3.2 + + 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 + + .. versionadded:: 3.2 + + 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 + + .. versionadded:: 3.3 + + 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 + + .. versionadded:: 3.3 + + * 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 + + .. versionadded:: 3.6 + + 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 + + .. versionadded:: 3.6 + + 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 + + .. versionadded:: 3.6 + + 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 + + .. versionadded:: 3.6 + + 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 + + .. versionadded:: 3.11 + + 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 +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 3.3 + +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. + +.. versionchanged:: 3.6 + Symbolic links that point to locations outside packaging path produce a + warning and are treated as non relocatable permanent symbolic links. + Previous versions of CMake produced an error in this case. + +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 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 3.7 + +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 + + .. versionadded:: 3.8 + + 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 + + .. versionadded:: 3.9 + + 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) +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 3.7 + +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 0000000..79f835e --- /dev/null +++ b/Help/cpack_gen/wix.rst @@ -0,0 +1,322 @@ +CPack WIX Generator +------------------- + +CPack WIX generator specific options + +.. versionadded:: 3.7 + Support :variable:`CPACK_COMPONENT_<compName>_DISABLED` variable. + +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 + + .. versionadded:: 3.16 + 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. + + .. versionadded:: 3.5 + Support listing multiple patch files. + + 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. + + .. versionadded:: 3.3 + The following additional special Ids can be used: + + * ``#PRODUCT`` for the ``<Product>`` element. + * ``#PRODUCTFEATURE`` for the root ``<Feature>`` element. + + .. versionadded:: 3.7 + Support patching arbitrary ``<Feature>`` elements. + + .. versionadded:: 3.9 + Allow setting additional attributes. + + 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> + + .. versionadded:: 3.1 + + 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 + + .. versionadded:: 3.7 + + 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 + + .. versionadded:: 3.7 + + 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 + + .. versionadded:: 3.7 + + 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 + + .. versionadded:: 3.9 + + 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. + +.. variable:: CPACK_WIX_CUSTOM_XMLNS + + .. versionadded:: 3.19 + + This variable provides a list of custom namespace declarations that are necessary + for using WiX extensions. Each declaration should be in the form name=url, where + name is the plain namespace without the usual xmlns: prefix and url is an unquoted + namespace url. A list of commonly known WiX schemata can be found here: + https://wixtoolset.org/documentation/manual/v3/xsd/ diff --git a/Help/dev/README.rst b/Help/dev/README.rst new file mode 100644 index 0000000..9c3878b --- /dev/null +++ b/Help/dev/README.rst @@ -0,0 +1,53 @@ +CMake Development +***************** + +This directory contains documentation about development of CMake itself. +It is not part of the user documentation distributed with CMake. + +Contributor Instructions +======================== + +See `CONTRIBUTING.rst`_ for instructions to contribute changes. + +The process for contributing changes is the same whether or not one +has been invited to participate directly in upstream development. + +.. _`CONTRIBUTING.rst`: ../../CONTRIBUTING.rst + +Upstream Development +==================== + +CMake uses `Kitware's GitLab Instance`_ to manage development, review, and +integration of changes. The `CMake Repository`_ holds the integration +branches and tags. Upstream development processes are covered by the +following documents: + +* The `CMake Review Process`_ manages integration of changes. +* The `CMake Testing Process`_ drives integration testing. + +.. _`Kitware's GitLab Instance`: https://gitlab.kitware.com +.. _`CMake Repository`: https://gitlab.kitware.com/cmake/cmake +.. _`CMake Review Process`: review.rst +.. _`CMake Testing Process`: testing.rst + +Developer Documentation +======================= + +CMake developer documentation is provided by the following documents: + +* The `CMake Source Code Guide`_. +* The `CMake Documentation Guide`_. +* The `CMake Experimental Features Guide`_. + +.. _`CMake Source Code Guide`: source.rst +.. _`CMake Documentation Guide`: documentation.rst +.. _`CMake Experimental Features Guide`: experimental.rst + +Maintainer Documentation +======================== + +CMake maintainer documentation is provided by the following documents: + +* The `CMake Maintainer Guide`_. + +.. _`CMake Maintainer Guide`: maint.rst diff --git a/Help/dev/documentation.rst b/Help/dev/documentation.rst new file mode 100644 index 0000000..29fc880 --- /dev/null +++ b/Help/dev/documentation.rst @@ -0,0 +1,556 @@ +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. + +``cpack_gen`` + A CPack package generator. + See the `cpack(1)`_ command-line tool's ``-G`` option. + +``envvar`` + An environment variable. + See the `cmake-env-variables(7)`_ manual + and the `set()`_ command. + +``generator`` + A CMake native build system generator. + See the `cmake(1)`_ command-line tool's ``-G`` option. + +``genex`` + A CMake generator expression. + See the `cmake-generator-expressions(7)`_ manual. + +``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, +or in the case of a ``$<genex-name>`` or ``$<genex-name:...>``, the +``genex-name``. + +Second, the CMake Domain provides directives to define objects inside +other documents: + +.. code-block:: rst + + .. command:: <command-name> + + This indented block documents <command-name>. + + .. envvar:: <envvar-name> + + This indented block documents <envvar-name>. + + .. genex:: <genex-name> + + This indented block documents <genex-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-env-variables(7)`: https://cmake.org/cmake/help/latest/manual/cmake-env-variables.7.html +.. _`cmake-generator-expressions(7)`: https://cmake.org/cmake/help/latest/manual/cmake-generator-expressions.7.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 +.. _`cpack(1)`: https://cmake.org/cmake/help/latest/manual/cpack.1.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/experimental.rst b/Help/dev/experimental.rst new file mode 100644 index 0000000..d019161 --- /dev/null +++ b/Help/dev/experimental.rst @@ -0,0 +1,70 @@ +CMake Experimental Features Guide +********************************* + +The following is a guide to CMake experimental features that are +under development and not yet included in official documentation. +See documentation on `CMake Development`_ for more information. + +.. _`CMake Development`: README.rst + +C++20 Module Dependencies +========================= + +The Ninja generator has experimental infrastructure supporting C++20 module +dependency scanning. This is similar to the Fortran modules support, but +relies on external tools to scan C++20 translation units for module +dependencies. The approach is described by Kitware's `D1483r1`_ paper. + +The ``CMAKE_EXPERIMENTAL_CXX_MODULE_DYNDEP`` variable can be set to ``1`` +in order to activate this undocumented experimental infrastructure. This +is **intended to make the functionality available to compiler writers** so +they can use it to develop and test their dependency scanning tool. +The ``CMAKE_EXPERIMENTAL_CXX_SCANDEP_SOURCE`` variable must also be set +to tell CMake how to invoke the C++20 module dependency scanning tool. + +For example, add code like the following to a test project: + +.. code-block:: cmake + + set(CMAKE_EXPERIMENTAL_CXX_MODULE_DYNDEP 1) + string(CONCAT CMAKE_EXPERIMENTAL_CXX_SCANDEP_SOURCE + "<CMAKE_CXX_COMPILER> <DEFINES> <INCLUDES> <FLAGS> <SOURCE>" + " -MT <DYNDEP_FILE> -MD -MF <DEP_FILE>" + " ${flags_to_scan_deps} -fdep-file=<DYNDEP_FILE> -fdep-output=<OBJECT>" + ) + +The tool specified by ``CMAKE_EXPERIMENTAL_CXX_SCANDEP_SOURCE`` is +expected to process the translation unit, write preprocessor dependencies +to the file specified by the ``<DEP_FILE>`` placeholder, and write module +dependencies to the file specified by the ``<DYNDEP_FILE>`` placeholder. + +The module dependencies should be written in the format described +by the `P1689r3`_ paper. + +Compiler writers may try out their scanning functionality using +the `cxx-modules-sandbox`_ test project, modified to set variables +as above for their compiler. + +For compilers that generate module maps, tell CMake as follows: + +.. code-block:: cmake + + set(CMAKE_EXPERIMENTAL_CXX_MODULE_MAP_FORMAT "gcc") + set(CMAKE_EXPERIMENTAL_CXX_MODULE_MAP_FLAG + "${compiler_flags_for_module_map} -fmodule-mapper=<MODULE_MAP_FILE>") + +Currently, the only supported format is ``gcc``. The format is described in +the GCC documentation, but the relevant section for the purposes of CMake is: + + A mapping file consisting of space-separated module-name, filename + pairs, one per line. Only the mappings for the direct imports and any + module export name need be provided. If other mappings are provided, + they override those stored in any imported CMI files. A repository + root may be specified in the mapping file by using ``$root`` as the + module name in the first active line. + + -- GCC module mapper documentation + +.. _`D1483r1`: https://mathstuf.fedorapeople.org/fortran-modules/fortran-modules.html +.. _`P1689r3`: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2020/p1689r3.html +.. _`cxx-modules-sandbox`: https://github.com/mathstuf/cxx-modules-sandbox diff --git a/Help/dev/maint.rst b/Help/dev/maint.rst new file mode 100644 index 0000000..664b7a4 --- /dev/null +++ b/Help/dev/maint.rst @@ -0,0 +1,369 @@ +CMake Maintainer Guide +********************** + +The following is a guide to CMake maintenance processes. +See documentation on `CMake Development`_ for more information. + +.. _`CMake Development`: README.rst + +.. 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 (or part of it) should be backported + to the ``release`` branch (and is already based on a commit + contained in the ``release`` branch), add a ``Backport: release`` or + ``Backport: release:<commit-ish>`` trailing line to the MR description. + +* 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 target + ``master``. Use the above-mentioned ``Backport: release`` line to tell + ``Do: merge`` to merge to both. If a MR is merged without the backport + line, a maintainer may still 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. + +To merge an open MR to the ``release`` branch, edit its description to +use the ``Backport: release`` line mentioned above and then ``Do: merge`` +normally. To update the ``release`` branch manually (e.g. to merge a +``$topic`` branch that was merged without the backport line), use the +following procedure. + +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 +==================== + +This section covers how to start a new ``release`` branch for a major or +minor version bump (patch releases remain on their existing branch). + +In the following we use the placeholder ``$ver`` to represent the +version number of the new release with the form ``$major.$minor``, +and ``$prev`` to represent the version number of the prior release. + +Review Prior Release +-------------------- + +Review the history around the prior release branch: + +.. code-block:: shell + + git log --graph --boundary \ + ^$(git rev-list --grep="Merge topic 'doc-.*-relnotes'" -n 1 master)~1 \ + $(git rev-list --grep="Begin post-.* development" -n 1 master) \ + $(git tag --list *-rc1| tail -1) + +Consolidate Release Notes +------------------------- + +Starting from a clean work tree on ``master``, create a topic branch to +use for consolidating the release notes: + +.. code-block:: shell + + git checkout -b doc-$ver-relnotes + +Run the `consolidate-relnotes.bash`_ script: + +.. code-block:: shell + + Utilities/Release/consolidate-relnotes.bash $ver $prev + +.. _`consolidate-relnotes.bash`: ../../Utilities/Release/consolidate-relnotes.bash + +This moves notes from the ``Help/release/dev/*.rst`` files into a versioned +``Help/release/$ver.rst`` file and updates ``Help/release/index.rst`` to +link to the new document. Commit the changes with a message such as:: + + Help: Consolidate $ver release notes + + Run the `Utilities/Release/consolidate-relnotes.bash` script to move + notes from `Help/release/dev/*` into `Help/release/$ver.rst`. + +Manually edit ``Help/release/$ver.rst`` to add section headers, organize +the notes, and revise wording. Then commit with a message such as:: + + Help: Organize and revise $ver release notes + + Add section headers similar to the $prev release notes and move each + individual bullet into an appropriate section. Revise a few bullets. + +Update Sphinx ``versionadded`` directives in documents added since +the previous release by running the `update_versions.py`_ script: + +.. code-block:: shell + + Utilities/Sphinx/update_versions.py --since v$prev.0 --overwrite + +.. _`update_versions.py`: ../../Utilities/Sphinx/update_versions.py + +Commit the changes with a message such as:: + + Help: Update Sphinx versionadded directives for $ver release + + Run the script: + + Utilities/Sphinx/update_versions.py --since v$prev.0 --overwrite + +Open a merge request with the ``doc-$ver-relnotes`` branch for review +and integration. Further steps may proceed after this has been merged +to ``master``. + +Update 'release' Branch +----------------------- + +Starting from a clean work tree on ``master``, create a new ``release-$ver`` +branch locally: + +.. code-block:: shell + + git checkout -b release-$ver origin/master + +Remove the development branch release note infrastructure: + +.. code-block:: shell + + git rm Help/release/dev/0-sample-topic.rst + sed -i '/^\.\. include:: dev.txt/ {N;d}' Help/release/index.rst + +Commit with a message such as:: + + Help: Drop development topic notes to prepare release + + Release versions do not have the development topic section of + the CMake Release Notes index page. + +Update ``.gitlab-ci.yml`` to drop the ``upload:`` jobs from the +packaging pipeline by renaming them to start in ``.``: + +.. code-block:: shell + + sed -i 's/^upload:/.upload:/' .gitlab-ci.yml + +Commit with a message such as:: + + gitlab-ci: Drop package pipeline upload jobs for release branch + + The package pipeline for release versions should not upload packages + automatically to our archive of nightly development versions. + +Update ``Source/CMakeVersion.cmake`` to set the version to +``$major.$minor.0-rc0``: + +.. code-block:: cmake + + # CMake version number components. + set(CMake_VERSION_MAJOR $major) + set(CMake_VERSION_MINOR $minor) + set(CMake_VERSION_PATCH 0) + set(CMake_VERSION_RC 0) + +Update uses of ``DEVEL_CMAKE_VERSION`` in the source tree to mention the +actual version number: + +.. code-block:: shell + + $EDITOR $(git grep -l DEVEL_CMAKE_VERSION) + +Commit with a message such as:: + + Begin $ver release versioning + +Merge the ``release-$ver`` branch to ``master``: + +.. code-block:: shell + + git checkout master + git pull + git merge --no-ff release-$ver + +Begin post-release development by restoring the development branch release +note infrastructure, the nightly package pipeline upload jobs, and +the version date from ``origin/master``: + +.. code-block:: shell + + git checkout origin/master -- \ + Source/CMakeVersion.cmake Help/release/dev/0-sample-topic.rst + sed -i $'/^Releases/ i\\\n.. include:: dev.txt\\\n' Help/release/index.rst + sed -i 's/^\.upload:/upload:/' .gitlab-ci.yml + +Update ``Source/CMakeVersion.cmake`` to set the version to +``$major.$minor.$date``: + +.. code-block:: cmake + + # CMake version number components. + set(CMake_VERSION_MAJOR $major) + set(CMake_VERSION_MINOR $minor) + set(CMake_VERSION_PATCH $date) + #set(CMake_VERSION_RC 0) + +Commit with a message such as:: + + Begin post-$ver development + +Push the update to the ``master`` and ``release`` branches: + +.. code-block:: shell + + git push --atomic origin master release-$ver:release + +Announce 'release' Branch +------------------------- + +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` + before staging or merging. + +.. _`CMake Discourse Forum Development Category`: https://discourse.cmake.org/c/development + +Initial Post-Release Development +-------------------------------- + +Deprecate policies more than 8 release series old by updating the +policy range check in ``cmMakefile::SetPolicy``. +Commit with a message such as:: + + Add deprecation warnings for policies CMP#### and below + + The OLD behaviors of all policies are deprecated, but only by + documentation. Add an explicit deprecation diagnostic for policies + introduced in CMake $OLDVER and below to encourage projects to port + away from setting policies to OLD. + +Update the ``cmake_policy`` version range generated by ``install(EXPORT)`` +in ``cmExportFileGenerator::GeneratePolicyHeaderCode`` to end at the +previous release. We use one release back since we now know all the +policies added for that version. Commit with a message such as:: + + export: Increase maximum policy version in exported files to $prev + + The files generatd by `install(EXPORT)` and `export()` commands + are known to work with policies as of CMake $prev, so enable them + in sufficiently new CMake versions. + +Update the ``cmake_minimum_required`` version range in CMake itself: + +* ``CMakeLists.txt`` +* ``Utilities/Doxygen/CMakeLists.txt`` +* ``Utilities/Sphinx/CMakeLists.txt`` + +to end in the previous release. Commit with a message such as:: + + Configure CMake itself with policies through CMake $prev diff --git a/Help/dev/review.rst b/Help/dev/review.rst new file mode 100644 index 0000000..10ff87b --- /dev/null +++ b/Help/dev/review.rst @@ -0,0 +1,541 @@ +CMake Review Process +******************** + +The following documents the process for reviewing and integrating changes. +See `CONTRIBUTING.rst`_ for instructions to contribute changes. +See documentation on `CMake Development`_ for more information. + +.. _`CONTRIBUTING.rst`: ../../CONTRIBUTING.rst +.. _`CMake Development`: README.rst + +.. contents:: The review process consists of the following steps: + +Merge Request +============= + +A user initiates the review process for a change by pushing a *topic +branch* to his or her own fork of the `CMake Repository`_ on GitLab and +creating a *merge request* ("MR"). The new MR will appear on the +`CMake Merge Requests Page`_. The rest of the review and integration +process is managed by the merge request page for the change. + +During the review process, the MR submitter should address review comments +or test failures by updating the MR with a (force-)push of the topic +branch. The update initiates a new round of review. + +We recommend that users enable the "Remove source branch when merge +request is accepted" option when creating the MR or by editing it. +This will cause the MR topic branch to be automatically removed from +the user's fork during the `Merge`_ step. + +.. _`CMake Merge Requests Page`: https://gitlab.kitware.com/cmake/cmake/-/merge_requests +.. _`CMake Repository`: https://gitlab.kitware.com/cmake/cmake + +Workflow Status +--------------- + +`CMake GitLab Project Developers`_ may set one of the following labels +in GitLab to track the state of a MR: + +* ``workflow:wip`` indicates that the MR needs additional updates from + the MR submitter before further review. Use this label after making + comments that require such updates. + +* ``workflow:in-review`` indicates that the MR awaits feedback from a + human reviewer or from `Topic Testing`_. Use this label after making + comments requesting such feedback. + +* ``workflow:nightly-testing`` indicates that the MR awaits results + of `Integration Testing`_. Use this label after making comments + requesting such staging. + +* ``workflow:expired`` indicates that the MR has been closed due + to a period of inactivity. See the `Expire`_ step. Use this label + after closing a MR for this reason. + +* ``workflow:external-discussion`` indicates that the MR has been closed + pending discussion elsewhere. See the `External Discussion`_ step. + Use this label after closing a MR for this reason. + +The workflow status labels are intended to be mutually exclusive, +so please remove any existing workflow label when adding one. + +.. _`CMake GitLab Project Developers`: https://gitlab.kitware.com/cmake/cmake/-/settings/members + +Robot Review +============ + +The "Kitware Robot" (``@kwrobot``) automatically performs basic checks on +the commits proposed in a MR. If all is well the robot silently reports +a successful "build" status to GitLab. Otherwise the robot posts a comment +with its diagnostics. **A topic may not be merged until the automatic +review succeeds.** + +Note that the MR submitter is expected to address the robot's comments by +*rewriting* the commits named by the robot's diagnostics (e.g., via +``git rebase -i``). This is because the robot checks each commit individually, +not the topic as a whole. This is done in order to ensure that commits in the +middle of a topic do not, for example, add a giant file which is then later +removed in the topic. + +Automatic Check +--------------- + +The automatic check is repeated whenever the topic branch is updated. +One may explicitly request a re-check by adding a comment with the +following command among the `comment trailing lines`_:: + + Do: check + +``@kwrobot`` will add an award emoji to the comment to indicate that it +was processed and also run its checks again. + +Automatic Format +---------------- + +The automatic check will reject commits introducing source code not +formatted according to ``clang-format``. One may ask the robot to +automatically rewrite the MR topic branch with expected formatting +by adding a comment with the following command among the +`comment trailing lines`_:: + + Do: reformat + +``@kwrobot`` will add an award emoji to the comment to indicate that it +was processed and also rewrite the MR topic branch and force-push an +updated version with every commit formatted as expected by the check. + +Human Review +============ + +Anyone is welcome to review merge requests and make comments! + +Please make comments directly on the MR page Discussion and Changes tabs +and not on individual commits. Comments on a commit may disappear +from the MR page if the commit is rewritten in response. + +Reviewers may add comments providing feedback or to acknowledge their +approval. Lines of specific forms will be extracted during the `merge`_ +step and included as trailing lines of the generated merge commit message. +Each review comment consists of up to two parts which must be specified +in the following order: `comment body`_, then `comment trailing lines`_. +Each part is optional, but they must be specified in this order. + +Comment Body +------------ + +The body of a comment may be free-form `GitLab Flavored Markdown`_. +See GitLab documentation on `Special GitLab References`_ to add links to +things like issues, commits, or other merge requests (even across projects). + +Additionally, a line in the comment body may start with one of the +following votes: + +* ``-1`` or ``:-1:`` indicates "the change is not ready for integration". + +* ``+1`` or ``:+1:`` indicates "I like the change". + This adds an ``Acked-by:`` trailer to the `merge`_ commit message. + +* ``+2`` indicates "the change is ready for integration". + This adds a ``Reviewed-by:`` trailer to the `merge`_ commit message. + +* ``+3`` indicates "I have tested the change and verified it works". + This adds a ``Tested-by:`` trailer to the `merge`_ commit message. + +.. _`GitLab Flavored Markdown`: https://gitlab.kitware.com/help/user/markdown.md +.. _`Special GitLab References`: https://gitlab.kitware.com/help/user/markdown.md#special-gitlab-references + +Comment Trailing Lines +---------------------- + +Zero or more *trailing* lines in the last section of a comment may appear +with the form ``Key: Value``. The first such line should be separated +from a preceding `comment body`_ by a blank line. Any key-value pair(s) +may be specified for human reference. A few specific keys have meaning to +``@kwrobot`` as follows. + +Comment Trailer Votes +^^^^^^^^^^^^^^^^^^^^^ + +Among the `comment trailing lines`_ one may cast a vote using one of the +following pairs followed by nothing but whitespace before the end of the line: + +* ``Rejected-by: me`` indicates "the change is not ready for integration". +* ``Acked-by: me`` indicates "I like the change". + This adds an ``Acked-by:`` trailer to the `merge`_ commit message. +* ``Reviewed-by: me`` indicates "the change is ready for integration". + This adds a ``Reviewed-by:`` trailer to the `merge`_ commit message. +* ``Tested-by: me`` indicates "I have tested the change and verified it works". + This adds a ``Tested-by:`` trailer to the `merge`_ commit message. + +Each ``me`` reference may instead be an ``@username`` reference or a full +``Real Name <user@domain>`` reference to credit someone else for performing +the review. References to ``me`` and ``@username`` will automatically be +transformed into a real name and email address according to the user's +GitLab account profile. + +Comment Trailer Commands +^^^^^^^^^^^^^^^^^^^^^^^^ + +Among the `comment trailing lines`_ authorized users may issue special +commands to ``@kwrobot`` using the form ``Do: ...``: + +* ``Do: check`` explicitly re-runs the robot `Automatic Check`_. +* ``Do: reformat`` rewrites the MR topic for `Automatic Format`_. +* ``Do: test`` submits the MR for `Topic Testing`_. +* ``Do: stage`` submits the MR for `Integration Testing`_. +* ``Do: merge`` submits the MR for `Merge`_. + +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 --pretty=reference <commit>`` with +Git 2.25 and newer. Older versions of Git can generate the same format via +``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 preferable 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>)``. +Or, use the output of ``git describe --contains <commit>`` as the ``<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 +============= + +CMake uses `GitLab CI`_ to test merge requests, configured by the top-level +``.gitlab-ci.yml`` file. Results may be seen both on the merge request's +pipeline page and on the `CMake CDash Page`_. Filtered CDash results +showing just the pipeline's jobs can be reached by selecting the ``cdash`` +job in the ``External`` stage of the pipeline. + +Lint and documentation build jobs run automatically after every push. +Heavier jobs require a manual trigger to run: + +* Merge request authors may visit their merge request's pipeline and click the + "Play" button on one or more jobs manually. If the merge request has the + "Allow commits from members who can merge to the target branch" check box + enabled, CMake maintainers may use the "Play" button too. + +* `CMake GitLab Project Developers`_ may trigger CI on a merge request by + adding a comment with a command among the `comment trailing lines`_:: + + Do: test + + ``@kwrobot`` will add an award emoji to the comment to indicate that it + was processed and also trigger all manual jobs in the merge request's + pipeline. + + The ``Do: test`` command accepts the following arguments: + + * ``--named <regex>``, ``-n <regex>``: Trigger jobs matching ``<regex>`` + anywhere in their name. Job names may be seen on the merge request's + pipeline page. + * ``--stage <stage>``, ``-s <stage>``: Only affect jobs in a given stage. + Stage names may be seen on the merge request's pipeline page. Note that + the names are determined by what is in the ``.gitlab-ci.yml`` file and may + be capitalized in the web page, so lowercasing the webpage's display name + for stages may be required. + * ``--action <action>``, ``-a <action>``: The action to perform on the jobs. + Possible actions: + + * ``manual`` (the default): Start jobs awaiting manual interaction. + * ``unsuccessful``: Start or restart jobs which have not completed + successfully. + * ``failed``: Restart jobs which have completed, but without success. + * ``completed``: Restart all completed jobs. + +If the merge request topic branch is updated by a push, a new manual trigger +using one of the above methods is needed to start CI again. + +.. _`GitLab CI`: https://gitlab.kitware.com/help/ci/README.md +.. _`CMake CDash Page`: https://open.cdash.org/index.php?project=CMake + +Integration Testing +=================== + +The above `topic testing`_ tests the MR topic independent of other +merge requests and on only a few key platforms and configurations. +The `CMake Testing Process`_ also has a large number of machines +provided by Kitware and generous volunteers that cover nearly all +supported platforms, generators, and configurations. In order to +avoid overwhelming these resources, they do not test every MR +individually. Instead, these machines follow an *integration branch*, +run tests on a nightly basis (or continuously during the day), and +post to the `CMake CDash Page`_. Some follow ``master``. Most follow +a special integration branch, the *topic stage*. + +The topic stage is a special branch maintained by the "Kitware Robot" +(``@kwrobot``). It consists of the head of the MR target integration +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`_:: + + Do: stage + +``@kwrobot`` will add an award emoji to the comment to indicate that it +was processed and also attempt to add the MR topic branch to the topic +stage. If the MR cannot be added (e.g. due to conflicts) the robot will +post a comment explaining what went wrong. + +Once a MR has been added to the topic stage it will remain on the stage +until one of the following occurs: + +* The MR topic branch is updated by a push. + +* The MR target integration branch (e.g. ``master``) branch is updated + and the MR cannot be merged into the topic stage again due to conflicts. + +* A developer or the submitter posts an explicit ``Do: unstage`` command. + This is useful to remove a MR from the topic stage when one is not ready + to push an update to the MR topic branch. It is unnecessary to explicitly + unstage just before or after pushing an update because the push will cause + the MR to be unstaged automatically. + +* The MR is closed. + +* The MR is merged. + +Once a MR has been removed from the topic stage a new ``Do: stage`` +command is needed to stage it again. + +.. _`CMake Testing Process`: testing.rst + +Resolve +======= + +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 +----- + +Once review has concluded that the MR topic is ready for integration, +`CMake GitLab Project Masters`_ may merge the topic by adding a comment +with a command among the `comment trailing lines`_:: + + Do: merge + +``@kwrobot`` will add an award emoji to the comment to indicate that it +was processed and also attempt to merge the MR topic branch to the MR +target integration branch (e.g. ``master``). If the MR cannot be merged +(e.g. due to conflicts) the robot will post a comment explaining what +went wrong. If the MR is merged the robot will also remove the source +branch from the user's fork if the corresponding MR option was checked. + +The robot automatically constructs a merge commit message of the following +form:: + + Merge topic 'mr-topic-branch-name' + + 00000000 commit message subject line (one line per commit) + + Acked-by: Kitware Robot <kwrobot@kitware.com> + Merge-request: !0000 + +Mention of the commit short sha1s and MR number helps GitLab link the +commits back to the merge request and indicates when they were merged. +The ``Acked-by:`` trailer shown indicates that `Robot Review`_ passed. +Additional ``Acked-by:``, ``Reviewed-by:``, and similar trailers may be +collected from `Human Review`_ comments that have been made since the +last time the MR topic branch was updated with a push. + +The ``Do: merge`` command accepts the following arguments: + +* ``-t <topic>``: substitute ``<topic>`` for the name of the MR topic + branch in the constructed merge commit message. + +Additionally, ``Do: merge`` extracts configuration from trailing lines +in the MR description (the following have no effect if used in a MR +comment instead): + +* ``Backport: release[:<commit-ish>]``: merge the topic branch into + the ``release`` branch to backport the change. This is allowed + only if the topic branch is based on a commit in ``release`` already. + If only part of the topic branch should be backported, specify it as + ``:<commit-ish>``. The ``<commit-ish>`` may use `git rev-parse`_ + syntax to reference commits relative to the topic ``HEAD``. + See additional `backport instructions`_ for details. + For example: + + ``Backport: release`` + Merge the topic branch head into both ``release`` and ``master``. + ``Backport: release:HEAD~1^2`` + Merge the topic branch head's parent's second parent commit into + the ``release`` branch. Merge the topic branch head to ``master``. + +* ``Topic-rename: <topic>``: substitute ``<topic>`` for the name of + the MR topic branch in the constructed merge commit message. + 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 +.. _`backport instructions`: https://gitlab.kitware.com/utils/git-workflow/-/wikis/Backport-topics +.. _`git rev-parse`: https://git-scm.com/docs/git-rev-parse + +Close +----- + +If review has concluded that the MR should not be integrated then it +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 (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 new file mode 100644 index 0000000..9be4451 --- /dev/null +++ b/Help/dev/source.rst @@ -0,0 +1,244 @@ +CMake Source Code Guide +*********************** + +The following is a guide to the CMake source code for developers. +See documentation on `CMake Development`_ for more information. + +.. _`CMake Development`: README.rst + +C++ Code Style +============== + +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 +source files for which we enforce style. The script also has options to +format only a subset of files, such as those that are locally modified. + +.. _`clang-format`: http://clang.llvm.org/docs/ClangFormat.html +.. _`.clang-format`: ../../.clang-format +.. _`Utilities/Scripts/clang-format.bash`: ../../Utilities/Scripts/clang-format.bash + +C++ Subset Permitted +==================== + +CMake requires compiling as C++11 in order to support building on older +toolchains. However, to facilitate development, some standard library +features from more recent C++ standards are supported through a compatibility +layer. These features are defined under the namespace ``cm`` and headers +are accessible under the ``cm/`` directory. The headers under ``cm/`` can +be used in place of the standard ones when extended features are needed. +For example ``<cm/memory>`` can be used in place of ``<memory>``. + +Available features are: + +* From ``C++14``: + + * ``<cm/iomanip>``: + ``cm::quoted`` + + * ``<cm/iterator>``: + ``cm::make_reverse_iterator``, ``cm::cbegin``, ``cm::cend``, + ``cm::rbegin``, ``cm::rend``, ``cm::crbegin``, ``cm::crend`` + + * ``<cm/memory>``: + ``cm::make_unique`` + + * ``<cm/shared_mutex>``: + ``cm::shared_lock`` + + * ``<cm/type_traits>``: + ``cm::enable_if_t`` + +* From ``C++17``: + + * ``<cm/algorithm>``: + ``cm::clamp`` + + * ``cm/filesystem>``: + ``cm::filesystem::path`` + + * ``<cm/iterator>``: + ``cm::size``, ``cm::empty``, ``cm::data`` + + * ``<cm/optional>``: + ``cm::nullopt_t``, ``cm::nullopt``, ``cm::optional``, + ``cm::make_optional``, ``cm::bad_optional_access`` + + * ``<cm/shared_mutex>``: + ``cm::shared_mutex`` + + * ``<cm/string_view>``: + ``cm::string_view`` + + * ``<cm/type_traits>``: + ``cm::bool_constant``, ``cm::invoke_result_t``, ``cm::invoke_result``, + ``cm::void_t`` + + * ``<cm/utility>``: + ``cm::in_place_t``, ``cm::in_place`` + +* From ``C++20``: + + * ``<cm/deque>``: + ``cm::erase``, ``cm::erase_if`` + + * ``<cm/list>``: + ``cm::erase``, ``cm::erase_if`` + + * ``<cm/map>`` : + ``cm::erase_if`` + + * ``<cm/set>`` : + ``cm::erase_if`` + + * ``<cm/string>``: + ``cm::erase``, ``cm::erase_if`` + + * ``<cm/unordered_map>``: + ``cm::erase_if`` + + * ``<cm/unordered_set>``: + ``cm::erase_if`` + + * ``<cm/vector>``: + ``cm::erase``, ``cm::erase_if`` + +Additionally, some useful non-standard extensions to the C++ standard library +are available in headers under the directory ``cmext/`` in namespace ``cm``. +These are: + +* ``<cmext/algorithm>``: + + * ``cm::append``: + Append elements to a sequential container. + + * ``cm::contains``: + Checks if element or key is contained in container. + +* ``<cmext/iterator>``: + + * ``cm::is_terator``: + Checks if a type is an iterator type. + + * ``cm::is_input_iterator``: + Checks if a type is an input iterator type. + + * ``cm::is_range``: + Checks if a type is a range type: functions ``std::begin()`` and + ``std::end()`` apply. + + * ``cm::is_input_range``: + Checks if a type is an input range type: functions ``std::begin()`` and + ``std::end()`` apply and return an input iterator. + +* ``<cmext/memory>``: + + * ``cm::static_reference_cast``: + Apply a ``static_cast`` to a smart pointer. + + * ``cm::dynamic_reference_cast``: + Apply a ``dynamic_cast`` to a smart pointer. + +* ``<cmext/type_traits>``: + + * ``cm::is_container``: + Checks if a type is a container type. + + * ``cm::is_associative_container``: + Checks if a type is an associative container type. + + * ``cm::is_unordered_associative_container``: + Checks if a type is an unordered associative container type. + + * ``cm::is_sequence_container``: + Checks if a type is a sequence container type. + + * ``cm::is_unique_ptr``: + Checks if a type is a ``std::unique_ptr`` type. + +CMake assumes the compiler supports ``#pragma once``. Use this for all +hand-written header files. + +Dynamic Memory Management +========================= + +To ensure efficient memory management, i.e. no memory leaks, it is required +to use smart pointers. Any dynamic memory allocation must be handled by a +smart pointer such as ``std::unique_ptr`` or ``std::shared_ptr``. + +It is allowed to pass raw pointers between objects to enable objects sharing. +A raw pointer **must** not be deleted. Only the object(s) owning the smart +pointer are allowed to delete dynamically allocated memory. + +Third Parties +============= + +To build CMake, some third parties are needed. Under ``Utilities`` +directory, are versions of these third parties which can be used as an +alternate to the ones provided by the system. + +To enable the selection of the third parties between the system and CMake ones, +in CMake sources, third parties headers must be prefixed by ``cm3p/`` +(for example: ``<cm3p/json/reader.h>``). These wrappers are located under +``Utilities/cm3p`` directory. + +Source Tree Layout +================== + +The CMake source tree is organized as follows. + +* ``Auxiliary/``: + Shell and editor integration files. + +* ``Help/``: + Documentation. See the `CMake Documentation Guide`_. + + * ``Help/dev/``: + Developer documentation. + + * ``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/std/cm``: + Support files for various C++ standards. + + * ``Utilities/std/cmext``: + Extensions to the C++ STL. + + * ``Utilities/cm3p``: + Public headers for third parties needed to build CMake. + + * ``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 new file mode 100644 index 0000000..279e4b2 --- /dev/null +++ b/Help/dev/testing.rst @@ -0,0 +1,43 @@ +CMake Testing Process +********************* + +The following documents the process for running integration testing builds. +See documentation on `CMake Development`_ for more information. + +.. _`CMake Development`: README.rst + +CMake Dashboard Scripts +======================= + +The *integration testing* step of the `CMake Review Process`_ uses a set of +testing machines that follow an integration branch on their own schedule to +drive testing and submit results to the `CMake CDash Page`_. Anyone is +welcome to provide testing machines in order to help keep support for their +platforms working. + +The `CMake Dashboard Scripts Repository`_ provides CTest scripts to drive +nightly, continuous, and experimental testing of CMake. Use the following +commands to set up a new integration testing client: + +.. code-block:: console + + $ mkdir -p ~/Dashboards + $ cd ~/Dashboards + $ git clone https://gitlab.kitware.com/cmake/dashboard-scripts.git CMakeScripts + $ cd CMakeScripts + +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 +------------------ + +The ``cmake_common.cmake`` script expects its includer to be run from a +nightly scheduled task (cron job). Schedule such tasks for sometime after +``1:00am UTC``, the time at which our nightly testing branches fast-forward. diff --git a/Help/envvar/ASM_DIALECT.rst b/Help/envvar/ASM_DIALECT.rst new file mode 100644 index 0000000..c89515e --- /dev/null +++ b/Help/envvar/ASM_DIALECT.rst @@ -0,0 +1,22 @@ +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>`. + +.. note:: + Options that are required to make the compiler work correctly can be included; + they can not be changed. + +.. code-block:: console + + $ export ASM="custom-compiler --arg1 --arg2" diff --git a/Help/envvar/ASM_DIALECTFLAGS.rst b/Help/envvar/ASM_DIALECTFLAGS.rst new file mode 100644 index 0000000..2e1c6d2 --- /dev/null +++ b/Help/envvar/ASM_DIALECTFLAGS.rst @@ -0,0 +1,15 @@ +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. + +See also :variable:`CMAKE_ASM<DIALECT>_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`. diff --git a/Help/envvar/CC.rst b/Help/envvar/CC.rst new file mode 100644 index 0000000..1bb8d51 --- /dev/null +++ b/Help/envvar/CC.rst @@ -0,0 +1,19 @@ +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. + +.. note:: + Options that are required to make the compiler work correctly can be included; + they can not be changed. + +.. code-block:: console + + $ export CC="custom-compiler --arg1 --arg2" diff --git a/Help/envvar/CCMAKE_COLORS.rst b/Help/envvar/CCMAKE_COLORS.rst new file mode 100644 index 0000000..4e76bf8 --- /dev/null +++ b/Help/envvar/CCMAKE_COLORS.rst @@ -0,0 +1,36 @@ +CCMAKE_COLORS +------------- + +.. versionadded:: 3.18 + +Determines what colors are used by the CMake curses interface, +when run on a terminal that supports colors. +The syntax follows the same conventions as ``LS_COLORS``; +that is, a list of key/value pairs separated by ``:``. + +Keys are a single letter corresponding to a CMake cache variable type: + +- ``s``: A ``STRING``. +- ``p``: A ``FILEPATH``. +- ``c``: A value which has an associated list of choices. +- ``y``: A ``BOOL`` which has a true-like value (e.g. ``ON``, ``YES``). +- ``n``: A ``BOOL`` which has a false-like value (e.g. ``OFF``, ``NO``). + +Values are an integer number that specifies what color to use. +``0`` is black (you probably don't want to use that). +Others are determined by your terminal's color support. +Most (color) terminals will support at least 8 or 16 colors. +Some will support up to 256 colors. The colors will likely match +`this chart <https://upload.wikimedia.org/wikipedia/commons/1/15/Xterm_256color_chart.svg>`_, +although the first 16 colors may match the original +`CGA color palette <https://en.wikipedia.org/wiki/Color_Graphics_Adapter#Color_palette>`_. +(Many modern terminal emulators also allow their color palette, +at least for the first 16 colors, to be configured by the user.) + +Note that fairly minimal checking is done for bad colors +(although a value higher than what curses believes your terminal supports +will be silently ignored) or bad syntax. + +For example:: + + CCMAKE_COLORS='s=39:p=220:c=207:n=196:y=46' diff --git a/Help/envvar/CFLAGS.rst b/Help/envvar/CFLAGS.rst new file mode 100644 index 0000000..190b4f4 --- /dev/null +++ b/Help/envvar/CFLAGS.rst @@ -0,0 +1,13 @@ +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. + +See also :variable:`CMAKE_C_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`. diff --git a/Help/envvar/CMAKE_APPLE_SILICON_PROCESSOR.rst b/Help/envvar/CMAKE_APPLE_SILICON_PROCESSOR.rst new file mode 100644 index 0000000..adecb72 --- /dev/null +++ b/Help/envvar/CMAKE_APPLE_SILICON_PROCESSOR.rst @@ -0,0 +1,13 @@ +CMAKE_APPLE_SILICON_PROCESSOR +----------------------------- + +.. versionadded:: 3.19.2 + +.. include:: ENV_VAR.txt + +On Apple Silicon hosts running macOS, set this environment variable to tell +CMake what architecture to use for :variable:`CMAKE_HOST_SYSTEM_PROCESSOR`. +The value must be either ``arm64`` or ``x86_64``. + +The :variable:`CMAKE_APPLE_SILICON_PROCESSOR` normal variable, if set, +overrides this environment variable. diff --git a/Help/envvar/CMAKE_BUILD_PARALLEL_LEVEL.rst b/Help/envvar/CMAKE_BUILD_PARALLEL_LEVEL.rst new file mode 100644 index 0000000..dbc589a --- /dev/null +++ b/Help/envvar/CMAKE_BUILD_PARALLEL_LEVEL.rst @@ -0,0 +1,13 @@ +CMAKE_BUILD_PARALLEL_LEVEL +-------------------------- + +.. versionadded:: 3.12 + +.. 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 0000000..168593d --- /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_EXPORT_COMPILE_COMMANDS.rst b/Help/envvar/CMAKE_EXPORT_COMPILE_COMMANDS.rst new file mode 100644 index 0000000..9e678be --- /dev/null +++ b/Help/envvar/CMAKE_EXPORT_COMPILE_COMMANDS.rst @@ -0,0 +1,11 @@ +CMAKE_EXPORT_COMPILE_COMMANDS +----------------------------- + +.. versionadded:: 3.17 + +.. include:: ENV_VAR.txt + +The default value for :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` when there +is no explicit configuration given on the first run while creating a new +build tree. On later runs in an existing build tree the value persists in +the cache as :variable:`CMAKE_EXPORT_COMPILE_COMMANDS`. diff --git a/Help/envvar/CMAKE_GENERATOR.rst b/Help/envvar/CMAKE_GENERATOR.rst new file mode 100644 index 0000000..3488b04 --- /dev/null +++ b/Help/envvar/CMAKE_GENERATOR.rst @@ -0,0 +1,18 @@ +CMAKE_GENERATOR +--------------- + +.. versionadded:: 3.15 + +.. 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 0000000..8ca7d80 --- /dev/null +++ b/Help/envvar/CMAKE_GENERATOR_INSTANCE.rst @@ -0,0 +1,9 @@ +CMAKE_GENERATOR_INSTANCE +------------------------ + +.. versionadded:: 3.15 + +.. 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 0000000..b039845 --- /dev/null +++ b/Help/envvar/CMAKE_GENERATOR_PLATFORM.rst @@ -0,0 +1,10 @@ +CMAKE_GENERATOR_PLATFORM +------------------------ + +.. versionadded:: 3.15 + +.. 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 0000000..394dd88 --- /dev/null +++ b/Help/envvar/CMAKE_GENERATOR_TOOLSET.rst @@ -0,0 +1,10 @@ +CMAKE_GENERATOR_TOOLSET +----------------------- + +.. versionadded:: 3.15 + +.. 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_LANG_COMPILER_LAUNCHER.rst b/Help/envvar/CMAKE_LANG_COMPILER_LAUNCHER.rst new file mode 100644 index 0000000..c384fa1 --- /dev/null +++ b/Help/envvar/CMAKE_LANG_COMPILER_LAUNCHER.rst @@ -0,0 +1,12 @@ +CMAKE_<LANG>_COMPILER_LAUNCHER +------------------------------ + +.. versionadded:: 3.17 + +.. include:: ENV_VAR.txt + +Default compiler launcher to use for the specified language. Will only be used +by CMake to initialize the variable on the first configuration. Afterwards, it +is available through the cache setting of the variable of the same name. For +any configuration run (including the first), the environment variable will be +ignored if the :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER` variable is defined. diff --git a/Help/envvar/CMAKE_MSVCIDE_RUN_PATH.rst b/Help/envvar/CMAKE_MSVCIDE_RUN_PATH.rst new file mode 100644 index 0000000..77ead4d --- /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 0000000..fe733f8 --- /dev/null +++ b/Help/envvar/CMAKE_NO_VERBOSE.rst @@ -0,0 +1,10 @@ +CMAKE_NO_VERBOSE +---------------- + +.. versionadded:: 3.14 + +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 0000000..ef7d547 --- /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/CMAKE_PREFIX_PATH.rst b/Help/envvar/CMAKE_PREFIX_PATH.rst new file mode 100644 index 0000000..276fdd6 --- /dev/null +++ b/Help/envvar/CMAKE_PREFIX_PATH.rst @@ -0,0 +1,17 @@ +CMAKE_PREFIX_PATH +----------------- + +.. include:: ENV_VAR.txt + +The ``CMAKE_PREFIX_PATH`` environment variable may be set to a list 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 subdirectories (like ``bin``, ``lib``, or ``include``) +as specified in its own documentation. + +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:`CMAKE_PREFIX_PATH` CMake variable. diff --git a/Help/envvar/CSFLAGS.rst b/Help/envvar/CSFLAGS.rst new file mode 100644 index 0000000..784328a --- /dev/null +++ b/Help/envvar/CSFLAGS.rst @@ -0,0 +1,15 @@ +CSFLAGS +------- + +.. versionadded:: 3.9.2 + +.. include:: ENV_VAR.txt + +Default compilation flags to be used when compiling ``CSharp`` 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. + +See also :variable:`CMAKE_CSharp_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`. diff --git a/Help/envvar/CTEST_INTERACTIVE_DEBUG_MODE.rst b/Help/envvar/CTEST_INTERACTIVE_DEBUG_MODE.rst new file mode 100644 index 0000000..e1991b2 --- /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 0000000..d8b4262 --- /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 0000000..fd4936e --- /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 0000000..8c29d7d --- /dev/null +++ b/Help/envvar/CTEST_PROGRESS_OUTPUT.rst @@ -0,0 +1,18 @@ +CTEST_PROGRESS_OUTPUT +--------------------- + +.. versionadded:: 3.13 + +.. 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 0000000..79dbb79 --- /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/CUDAARCHS.rst b/Help/envvar/CUDAARCHS.rst new file mode 100644 index 0000000..82369cd --- /dev/null +++ b/Help/envvar/CUDAARCHS.rst @@ -0,0 +1,13 @@ +CUDAARCHS +--------- + +.. versionadded:: 3.20 + +.. include:: ENV_VAR.txt + +Value used to initialize :variable:`CMAKE_CUDA_ARCHITECTURES` on the first +configuration if it's not already defined. Subsequent runs will use the value +stored in the cache. + +This is a semicolon-separated list of architectures as described in +:prop_tgt:`CUDA_ARCHITECTURES`. diff --git a/Help/envvar/CUDACXX.rst b/Help/envvar/CUDACXX.rst new file mode 100644 index 0000000..1722128 --- /dev/null +++ b/Help/envvar/CUDACXX.rst @@ -0,0 +1,21 @@ +CUDACXX +------- + +.. versionadded:: 3.8 + +.. 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. + +.. note:: + Options that are required to make the compiler work correctly can be included; + they can not be changed. + +.. code-block:: console + + $ export CUDACXX="custom-compiler --arg1 --arg2" diff --git a/Help/envvar/CUDAFLAGS.rst b/Help/envvar/CUDAFLAGS.rst new file mode 100644 index 0000000..af577a0 --- /dev/null +++ b/Help/envvar/CUDAFLAGS.rst @@ -0,0 +1,15 @@ +CUDAFLAGS +--------- + +.. versionadded:: 3.8 + +.. 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. + +See also :variable:`CMAKE_CUDA_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`. diff --git a/Help/envvar/CUDAHOSTCXX.rst b/Help/envvar/CUDAHOSTCXX.rst new file mode 100644 index 0000000..963f9d1 --- /dev/null +++ b/Help/envvar/CUDAHOSTCXX.rst @@ -0,0 +1,20 @@ +CUDAHOSTCXX +----------- + +.. versionadded:: 3.8 + +.. 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. + +.. versionadded:: 3.13 + The :module:`FindCUDA` + module will use this variable to initialize its ``CUDA_HOST_COMPILER`` setting. diff --git a/Help/envvar/CXX.rst b/Help/envvar/CXX.rst new file mode 100644 index 0000000..61ba5b8 --- /dev/null +++ b/Help/envvar/CXX.rst @@ -0,0 +1,19 @@ +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. + +.. note:: + Options that are required to make the compiler work correctly can be included; + they can not be changed. + +.. code-block:: console + + $ export CXX="custom-compiler --arg1 --arg2" diff --git a/Help/envvar/CXXFLAGS.rst b/Help/envvar/CXXFLAGS.rst new file mode 100644 index 0000000..460a347 --- /dev/null +++ b/Help/envvar/CXXFLAGS.rst @@ -0,0 +1,13 @@ +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. + +See also :variable:`CMAKE_CXX_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`. diff --git a/Help/envvar/DASHBOARD_TEST_FROM_CTEST.rst b/Help/envvar/DASHBOARD_TEST_FROM_CTEST.rst new file mode 100644 index 0000000..6a52d64 --- /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 0000000..d2144ae --- /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 0000000..e1e70cd --- /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 0000000..70e1475 --- /dev/null +++ b/Help/envvar/FC.rst @@ -0,0 +1,20 @@ +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. + +.. note:: + Options that are required to make the compiler work correctly can be included; + they can not be changed. + +.. code-block:: console + + $ export FC="custom-compiler --arg1 --arg2" diff --git a/Help/envvar/FFLAGS.rst b/Help/envvar/FFLAGS.rst new file mode 100644 index 0000000..53bffb6 --- /dev/null +++ b/Help/envvar/FFLAGS.rst @@ -0,0 +1,13 @@ +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. + +See also :variable:`CMAKE_Fortran_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`. diff --git a/Help/envvar/ISPC.rst b/Help/envvar/ISPC.rst new file mode 100644 index 0000000..bcd6260 --- /dev/null +++ b/Help/envvar/ISPC.rst @@ -0,0 +1,13 @@ +ISPC +------- + +.. versionadded:: 3.19 + +.. include:: ENV_VAR.txt + +Preferred executable for compiling ``ISPC`` language files. Will only be used by +CMake on the first configuration to determine ``ISPC`` compiler, after which the +value for ``ISPC`` is stored in the cache as +:variable:`CMAKE_ISPC_COMPILER <CMAKE_<LANG>_COMPILER>`. For any configuration +run (including the first), the environment variable will be ignored if the +:variable:`CMAKE_ISPC_COMPILER <CMAKE_<LANG>_COMPILER>` variable is defined. diff --git a/Help/envvar/ISPCFLAGS.rst b/Help/envvar/ISPCFLAGS.rst new file mode 100644 index 0000000..21df037 --- /dev/null +++ b/Help/envvar/ISPCFLAGS.rst @@ -0,0 +1,15 @@ +ISPCFLAGS +--------- + +.. versionadded:: 3.19 + +.. include:: ENV_VAR.txt + +Default compilation flags to be used when compiling ``ISPC`` files. Will only be +used by CMake on the first configuration to determine ``ISPC`` default +compilation flags, after which the value for ``ISPCFLAGS`` is stored in the +cache as :variable:`CMAKE_ISPC_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration +run (including the first), the environment variable will be ignored if +the :variable:`CMAKE_ISPC_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined. + +See also :variable:`CMAKE_ISPC_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`. diff --git a/Help/envvar/LDFLAGS.rst b/Help/envvar/LDFLAGS.rst new file mode 100644 index 0000000..816d6ef --- /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 0000000..662bd03 --- /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/OBJC.rst b/Help/envvar/OBJC.rst new file mode 100644 index 0000000..2d95806 --- /dev/null +++ b/Help/envvar/OBJC.rst @@ -0,0 +1,16 @@ +OBJC +---- + +.. versionadded:: 3.16.7 + +.. include:: ENV_VAR.txt + +Preferred executable for compiling ``OBJC`` language files. Will only be used +by CMake on the first configuration to determine ``OBJC`` compiler, after +which the value for ``OBJC`` is stored in the cache as +:variable:`CMAKE_OBJC_COMPILER <CMAKE_<LANG>_COMPILER>`. For any configuration +run (including the first), the environment variable will be ignored if the +:variable:`CMAKE_OBJC_COMPILER <CMAKE_<LANG>_COMPILER>` variable is defined. + +If ``OBJC`` is not defined, the :envvar:`CC` environment variable will +be checked instead. diff --git a/Help/envvar/OBJCXX.rst b/Help/envvar/OBJCXX.rst new file mode 100644 index 0000000..71286d9 --- /dev/null +++ b/Help/envvar/OBJCXX.rst @@ -0,0 +1,16 @@ +OBJCXX +------ + +.. versionadded:: 3.16.7 + +.. include:: ENV_VAR.txt + +Preferred executable for compiling ``OBJCXX`` language files. Will only be used +by CMake on the first configuration to determine ``OBJCXX`` compiler, after +which the value for ``OBJCXX`` is stored in the cache as +:variable:`CMAKE_OBJCXX_COMPILER <CMAKE_<LANG>_COMPILER>`. For any configuration +run (including the first), the environment variable will be ignored if the +:variable:`CMAKE_OBJCXX_COMPILER <CMAKE_<LANG>_COMPILER>` variable is defined. + +If ``OBJCXX`` is not defined, the :envvar:`CXX` environment variable will +be checked instead. diff --git a/Help/envvar/PackageName_ROOT.rst b/Help/envvar/PackageName_ROOT.rst new file mode 100644 index 0000000..0cdd384 --- /dev/null +++ b/Help/envvar/PackageName_ROOT.rst @@ -0,0 +1,19 @@ +<PackageName>_ROOT +------------------ + +.. versionadded:: 3.12 + +.. 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 0000000..8a9324d --- /dev/null +++ b/Help/envvar/RC.rst @@ -0,0 +1,19 @@ +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. + +.. note:: + Options that are required to make the compiler work correctly can be included; + they can not be changed. + +.. code-block:: console + + $ export RC="custom-compiler --arg1 --arg2" diff --git a/Help/envvar/RCFLAGS.rst b/Help/envvar/RCFLAGS.rst new file mode 100644 index 0000000..bc43cb2 --- /dev/null +++ b/Help/envvar/RCFLAGS.rst @@ -0,0 +1,13 @@ +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. + +See also :variable:`CMAKE_RC_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`. diff --git a/Help/envvar/SWIFTC.rst b/Help/envvar/SWIFTC.rst new file mode 100644 index 0000000..896e156 --- /dev/null +++ b/Help/envvar/SWIFTC.rst @@ -0,0 +1,21 @@ +SWIFTC +------ + +.. versionadded:: 3.15 + +.. 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. + +.. note:: + Options that are required to make the compiler work correctly can be included; + they can not be changed. + +.. code-block:: console + + $ export SWIFTC="custom-compiler --arg1 --arg2" diff --git a/Help/envvar/VERBOSE.rst b/Help/envvar/VERBOSE.rst new file mode 100644 index 0000000..5911951 --- /dev/null +++ b/Help/envvar/VERBOSE.rst @@ -0,0 +1,12 @@ +VERBOSE +------- + +.. versionadded:: 3.14 + +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/Borland Makefiles.rst b/Help/generator/Borland Makefiles.rst new file mode 100644 index 0000000..c00d00a --- /dev/null +++ b/Help/generator/Borland Makefiles.rst @@ -0,0 +1,4 @@ +Borland Makefiles +----------------- + +Generates Borland makefiles. diff --git a/Help/generator/CodeBlocks.rst b/Help/generator/CodeBlocks.rst new file mode 100644 index 0000000..85da715 --- /dev/null +++ b/Help/generator/CodeBlocks.rst @@ -0,0 +1,35 @@ +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 :command:`project` call. Additionally a hierarchy of makefiles is generated +into the build tree. +The appropriate make program can build the +project through the default ``all`` target. An ``install`` target is +also provided. + +.. versionadded:: 3.10 + 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. + +This "extra" generator may be specified as: + +``CodeBlocks - MinGW Makefiles`` + Generate with :generator:`MinGW Makefiles`. + +``CodeBlocks - NMake Makefiles`` + Generate with :generator:`NMake Makefiles`. + +``CodeBlocks - NMake Makefiles JOM`` + .. versionadded:: 3.8 + Generate with :generator:`NMake Makefiles JOM`. + +``CodeBlocks - Ninja`` + Generate with :generator:`Ninja`. + +``CodeBlocks - Unix Makefiles`` + Generate with :generator:`Unix Makefiles`. diff --git a/Help/generator/CodeLite.rst b/Help/generator/CodeLite.rst new file mode 100644 index 0000000..4f276df --- /dev/null +++ b/Help/generator/CodeLite.rst @@ -0,0 +1,30 @@ +CodeLite +---------- + +Generates CodeLite project files. + +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 appropriate make program can build the +project through the default ``all`` target. An ``install`` target +is also provided. + +.. versionadded:: 3.7 + The :variable:`CMAKE_CODELITE_USE_TARGETS` variable may be set to ``ON`` + to change the default behavior from projects to targets as the basis + for project files. + +This "extra" generator may be specified as: + +``CodeLite - MinGW Makefiles`` + Generate with :generator:`MinGW Makefiles`. + +``CodeLite - NMake Makefiles`` + Generate with :generator:`NMake Makefiles`. + +``CodeLite - Ninja`` + Generate with :generator:`Ninja`. + +``CodeLite - Unix Makefiles`` + Generate with :generator:`Unix Makefiles`. diff --git a/Help/generator/Eclipse CDT4.rst b/Help/generator/Eclipse CDT4.rst new file mode 100644 index 0000000..634e2b6 --- /dev/null +++ b/Help/generator/Eclipse CDT4.rst @@ -0,0 +1,25 @@ +Eclipse CDT4 +------------ + +Generates Eclipse CDT 4.0 project files. + +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 ``all`` target. An ``install`` target +is also provided. + +This "extra" generator may be specified as: + +``Eclipse CDT4 - MinGW Makefiles`` + Generate with :generator:`MinGW Makefiles`. + +``Eclipse CDT4 - NMake Makefiles`` + Generate with :generator:`NMake Makefiles`. + +``Eclipse CDT4 - Ninja`` + Generate with :generator:`Ninja`. + +``Eclipse CDT4 - Unix Makefiles`` + Generate with :generator:`Unix Makefiles`. diff --git a/Help/generator/Green Hills MULTI.rst b/Help/generator/Green Hills MULTI.rst new file mode 100644 index 0000000..5d2b1cd --- /dev/null +++ b/Help/generator/Green Hills MULTI.rst @@ -0,0 +1,88 @@ +Green Hills MULTI +----------------- + +.. versionadded:: 3.3 + +.. versionadded:: 3.15 + Linux support. + +Generates Green Hills MULTI project files (experimental, work-in-progress). + +Customizations are available through the following cache variables: + +* ``GHS_CUSTOMIZATION`` +* ``GHS_GPJ_MACROS`` + +.. versionadded:: 3.14 + The buildsystem has predetermined build-configuration settings that can be controlled + via the :variable:`CMAKE_BUILD_TYPE` variable. + +Toolset and Platform Selection +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 3.13 + +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``. + + .. versionadded:: 3.15 + The ``GHS_OS_DIR_OPTION`` variable. + +* ``GHS_BSP_NAME`` + + | Sets ``-bsp`` entry in project file. + | Defaults to ``sim<arch>`` for ``integrity`` platforms. + +Target Properties +^^^^^^^^^^^^^^^^^ + +.. versionadded:: 3.14 + +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| + and is still a work in progress. Future versions of CMake + may make breaking changes as the generator matures. diff --git a/Help/generator/Kate.rst b/Help/generator/Kate.rst new file mode 100644 index 0000000..129bf63 --- /dev/null +++ b/Help/generator/Kate.rst @@ -0,0 +1,26 @@ +Kate +---- + +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 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: + +``Kate - MinGW Makefiles`` + Generate with :generator:`MinGW Makefiles`. + +``Kate - NMake Makefiles`` + Generate with :generator:`NMake Makefiles`. + +``Kate - Ninja`` + Generate with :generator:`Ninja`. + +``Kate - Unix Makefiles`` + Generate with :generator:`Unix Makefiles`. diff --git a/Help/generator/MSYS Makefiles.rst b/Help/generator/MSYS Makefiles.rst new file mode 100644 index 0000000..75b9fe5 --- /dev/null +++ b/Help/generator/MSYS Makefiles.rst @@ -0,0 +1,12 @@ +MSYS Makefiles +-------------- + +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 +rules. They are not compatible with a Windows command prompt. + +To build under a Windows command prompt, use the +:generator:`MinGW Makefiles` generator. diff --git a/Help/generator/MinGW Makefiles.rst b/Help/generator/MinGW Makefiles.rst new file mode 100644 index 0000000..134ea70 --- /dev/null +++ b/Help/generator/MinGW Makefiles.rst @@ -0,0 +1,13 @@ +MinGW Makefiles +--------------- + +Generates makefiles for use with ``mingw32-make`` under a Windows command +prompt. + +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. + +To build under the MSYS shell, use the :generator:`MSYS Makefiles` generator. diff --git a/Help/generator/NMake Makefiles JOM.rst b/Help/generator/NMake Makefiles JOM.rst new file mode 100644 index 0000000..e0f4c90 --- /dev/null +++ b/Help/generator/NMake Makefiles JOM.rst @@ -0,0 +1,7 @@ +NMake Makefiles JOM +------------------- + +Generates JOM makefiles. + +.. versionadded:: 3.8 + :generator:`CodeBlocks` generator can be used as an extra generator. diff --git a/Help/generator/NMake Makefiles.rst b/Help/generator/NMake Makefiles.rst new file mode 100644 index 0000000..89f2479 --- /dev/null +++ b/Help/generator/NMake Makefiles.rst @@ -0,0 +1,4 @@ +NMake Makefiles +--------------- + +Generates NMake makefiles. diff --git a/Help/generator/Ninja Multi-Config.rst b/Help/generator/Ninja Multi-Config.rst new file mode 100644 index 0000000..8901192 --- /dev/null +++ b/Help/generator/Ninja Multi-Config.rst @@ -0,0 +1,163 @@ +Ninja Multi-Config +------------------ + +.. versionadded:: 3.17 + +Generates multiple ``build-<Config>.ninja`` files. + +This generator is very much like the :generator:`Ninja` generator, but with +some key differences. Only these differences will be discussed in this +document. + +Unlike the :generator:`Ninja` generator, ``Ninja Multi-Config`` generates +multiple configurations at once with :variable:`CMAKE_CONFIGURATION_TYPES` +instead of only one configuration with :variable:`CMAKE_BUILD_TYPE`. One +``build-<Config>.ninja`` file will be generated for each of these +configurations (with ``<Config>`` being the configuration name.) These files +are intended to be run with ``ninja -f build-<Config>.ninja``. A +``build.ninja`` file is also generated, using the configuration from either +:variable:`CMAKE_DEFAULT_BUILD_TYPE` or the first item from +:variable:`CMAKE_CONFIGURATION_TYPES`. + +``cmake --build . --config <Config>`` will always use ``build-<Config>.ninja`` +to build. If no ``--config`` argument is specified, ``cmake --build .`` will +use ``build.ninja``. + +Each ``build-<Config>.ninja`` file contains ``<target>`` targets as well as +``<target>:<Config>`` targets, where ``<Config>`` is the same as the +configuration specified in ``build-<Config>.ninja`` Additionally, if +cross-config mode is enabled, ``build-<Config>.ninja`` may contain +``<target>:<OtherConfig>`` targets, where ``<OtherConfig>`` is a cross-config, +as well as ``<target>:all``, which builds the target in all cross-configs. See +below for how to enable cross-config mode. + +The ``Ninja Multi-Config`` generator recognizes the following variables: + +:variable:`CMAKE_CONFIGURATION_TYPES` + Specifies the total set of configurations to build. + +:variable:`CMAKE_CROSS_CONFIGS` + Specifies a :ref:`semicolon-separated list <CMake Language Lists>` of + configurations available from all ``build-<Config>.ninja`` files. + +:variable:`CMAKE_DEFAULT_BUILD_TYPE` + Specifies the configuration to use by default in a ``build.ninja`` file. + +:variable:`CMAKE_DEFAULT_CONFIGS` + Specifies a :ref:`semicolon-separated list <CMake Language Lists>` of + configurations to build for a target in ``build.ninja`` + if no ``:<Config>`` suffix is specified. + +Consider the following example: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.16) + project(MultiConfigNinja C) + + add_executable(generator generator.c) + add_custom_command(OUTPUT generated.c COMMAND generator generated.c) + add_library(generated ${CMAKE_BINARY_DIR}/generated.c) + +Now assume you configure the project with ``Ninja Multi-Config`` and run one of +the following commands: + +.. code-block:: shell + + ninja -f build-Debug.ninja generated + # OR + cmake --build . --config Debug --target generated + +This would build the ``Debug`` configuration of ``generator``, which would be +used to generate ``generated.c``, which would be used to build the ``Debug`` +configuration of ``generated``. + +But if :variable:`CMAKE_CROSS_CONFIGS` is set to ``all``, and you run the +following instead: + +.. code-block:: shell + + ninja -f build-Release.ninja generated:Debug + # OR + cmake --build . --config Release --target generated:Debug + +This would build the ``Release`` configuration of ``generator``, which would be +used to generate ``generated.c``, which would be used to build the ``Debug`` +configuration of ``generated``. This is useful for running a release-optimized +version of a generator utility while still building the debug version of the +targets built with the generated code. + +Custom Commands +^^^^^^^^^^^^^^^ + +.. versionadded:: 3.20 + +The ``Ninja Multi-Config`` generator adds extra capabilities to +:command:`add_custom_command` and :command:`add_custom_target` through its +cross-config mode. The ``COMMAND``, ``DEPENDS``, and ``WORKING_DIRECTORY`` +arguments can be evaluated in the context of either the "command config" (the +"native" configuration of the ``build-<Config>.ninja`` file in use) or the +"output config" (the configuration used to evaluate the ``OUTPUT`` and +``BYPRODUCTS``). + +If either ``OUTPUT`` or ``BYPRODUCTS`` names a path that is common to +more than one configuration (e.g. it does not use any generator expressions), +all arguments are evaluated in the command config by default. +If all ``OUTPUT`` and ``BYPRODUCTS`` paths are unique to each configuration +(e.g. by using the ``$<CONFIG>`` generator expression), the first argument of +``COMMAND`` is still evaluated in the command config by default, while all +subsequent arguments, as well as the arguments to ``DEPENDS`` and +``WORKING_DIRECTORY``, are evaluated in the output config. These defaults can +be overridden with the ``$<OUTPUT_CONFIG:...>`` and ``$<COMMAND_CONFIG:...>`` +generator-expressions. Note that if a target is specified by its name in +``DEPENDS``, or as the first argument of ``COMMAND``, it is always evaluated +in the command config, even if it is wrapped in ``$<OUTPUT_CONFIG:...>`` +(because its plain name is not a generator expression). + +As an example, consider the following: + +.. code-block:: cmake + + add_custom_command( + OUTPUT "$<CONFIG>.txt" + COMMAND generator "$<CONFIG>.txt" "$<OUTPUT_CONFIG:$<CONFIG>>" "$<COMMAND_CONFIG:$<CONFIG>>" + DEPENDS tgt1 "$<TARGET_FILE:tgt2>" "$<OUTPUT_CONFIG:$<TARGET_FILE:tgt3>>" "$<COMMAND_CONFIG:$<TARGET_FILE:tgt4>>" + ) + +Assume that ``generator``, ``tgt1``, ``tgt2``, ``tgt3``, and ``tgt4`` are all +executable targets, and assume that ``$<CONFIG>.txt`` is built in the ``Debug`` +output config using the ``Release`` command config. The ``Release`` build of +the ``generator`` target is called with ``Debug.txt Debug Release`` as +arguments. The command depends on the ``Release`` builds of ``tgt1`` and +``tgt4``, and the ``Debug`` builds of ``tgt2`` and ``tgt3``. + +``PRE_BUILD``, ``PRE_LINK``, and ``POST_BUILD`` custom commands for targets +only get run in their "native" configuration (the ``Release`` configuration in +the ``build-Release.ninja`` file) unless they have no ``BYPRODUCTS`` or their +``BYPRODUCTS`` are unique per config. Consider the following example: + +.. code-block:: cmake + + add_executable(exe main.c) + add_custom_command( + TARGET exe + POST_BUILD + COMMAND ${CMAKE_COMMAND} -E echo "Running no-byproduct command" + ) + add_custom_command( + TARGET exe + POST_BUILD + COMMAND ${CMAKE_COMMAND} -E echo "Running separate-byproduct command for $<CONFIG>" + BYPRODUCTS $<CONFIG>.txt + ) + add_custom_command( + TARGET exe + POST_BUILD + COMMAND ${CMAKE_COMMAND} -E echo "Running common-byproduct command for $<CONFIG>" + BYPRODUCTS exe.txt + ) + +In this example, if you build ``exe:Debug`` in ``build-Release.ninja``, the +first and second custom commands get run, since their byproducts are unique +per-config, but the last custom command does not. However, if you build +``exe:Release`` in ``build-Release.ninja``, all three custom commands get run. diff --git a/Help/generator/Ninja.rst b/Help/generator/Ninja.rst new file mode 100644 index 0000000..f3ba222 --- /dev/null +++ b/Help/generator/Ninja.rst @@ -0,0 +1,67 @@ +Ninja +----- + +Generates ``build.ninja`` files. + +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: + +``sub/dir/all`` + + .. versionadded:: 3.6 + + Depends on all targets required by the subdirectory. + +``sub/dir/install`` + + .. versionadded:: 3.7 + + Runs the install step in the subdirectory, if any. + +``sub/dir/install/strip`` + + .. versionadded:: 3.7 + 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`` + + .. versionadded:: 3.7 + + Runs the test step in the subdirectory, if any. + +``sub/dir/package`` + + .. versionadded:: 3.7 + + Runs the package step in the subdirectory, if any. + +Fortran Support +^^^^^^^^^^^^^^^ + +.. versionadded:: 3.7 + +The ``Ninja`` generator conditionally supports Fortran when the ``ninja`` +tool is at least version 1.10 (which has the required features). + +Swift Support +^^^^^^^^^^^^^ + +.. versionadded:: 3.15 + +The Swift support is experimental, not considered stable, and may change +in future releases of CMake. + +See Also +^^^^^^^^ + +.. versionadded:: 3.17 + The :generator:`Ninja Multi-Config` generator is similar to the ``Ninja`` + generator, but generates multiple configurations at once. diff --git a/Help/generator/Sublime Text 2.rst b/Help/generator/Sublime Text 2.rst new file mode 100644 index 0000000..0a07ea9 --- /dev/null +++ b/Help/generator/Sublime Text 2.rst @@ -0,0 +1,25 @@ +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 :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: + +``Sublime Text 2 - MinGW Makefiles`` + Generate with :generator:`MinGW Makefiles`. + +``Sublime Text 2 - NMake Makefiles`` + Generate with :generator:`NMake Makefiles`. + +``Sublime Text 2 - Ninja`` + Generate with :generator:`Ninja`. + +``Sublime Text 2 - Unix Makefiles`` + Generate with :generator:`Unix Makefiles`. diff --git a/Help/generator/Unix Makefiles.rst b/Help/generator/Unix Makefiles.rst new file mode 100644 index 0000000..dfe4ecb --- /dev/null +++ b/Help/generator/Unix Makefiles.rst @@ -0,0 +1,31 @@ +Unix Makefiles +-------------- + +Generates standard UNIX makefiles. + +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 new file mode 100644 index 0000000..e361719 --- /dev/null +++ b/Help/generator/VS_TOOLSET_HOST_ARCH.txt @@ -0,0 +1,11 @@ +.. versionadded:: 3.8 + 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). + |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. + +.. versionadded:: 3.14 + Added suport for ``host=x86`` option. diff --git a/Help/generator/Visual Studio 10 2010.rst b/Help/generator/Visual Studio 10 2010.rst new file mode 100644 index 0000000..b4376d8 --- /dev/null +++ b/Help/generator/Visual Studio 10 2010.rst @@ -0,0 +1,44 @@ +Visual Studio 10 2010 +--------------------- + +Generates Visual Studio 10 (VS 2010) project files. + +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``. + +.. versionadded:: 3.1 + 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 the generator name. +This is supported only for: + +``Visual Studio 10 2010 Win64`` + Specify target platform ``x64``. + +``Visual Studio 10 2010 IA64`` + Specify target platform ``Itanium``. + +Toolset Selection +^^^^^^^^^^^^^^^^^ + +The ``v100`` toolset that comes with Visual Studio 10 2010 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. diff --git a/Help/generator/Visual Studio 11 2012.rst b/Help/generator/Visual Studio 11 2012.rst new file mode 100644 index 0000000..932548b --- /dev/null +++ b/Help/generator/Visual Studio 11 2012.rst @@ -0,0 +1,49 @@ +Visual Studio 11 2012 +--------------------- + +Generates Visual Studio 11 (VS 2012) project files. + +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``. + +.. versionadded:: 3.1 + 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 the generator name. +This is supported only for: + +``Visual Studio 11 2012 Win64`` + Specify target platform ``x64``. + +``Visual Studio 11 2012 ARM`` + Specify target platform ``ARM``. + +``Visual Studio 11 2012 <WinCE-SDK>`` + Specify target platform matching a Windows CE SDK name. + +Toolset Selection +^^^^^^^^^^^^^^^^^ + +The ``v110`` toolset that comes with Visual Studio 11 2012 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. diff --git a/Help/generator/Visual Studio 12 2013.rst b/Help/generator/Visual Studio 12 2013.rst new file mode 100644 index 0000000..b5fa1bf --- /dev/null +++ b/Help/generator/Visual Studio 12 2013.rst @@ -0,0 +1,49 @@ +Visual Studio 12 2013 +--------------------- + +Generates Visual Studio 12 (VS 2013) project files. + +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``. + +.. versionadded:: 3.1 + 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 the generator name. +This is supported only for: + +``Visual Studio 12 2013 Win64`` + Specify target platform ``x64``. + +``Visual Studio 12 2013 ARM`` + Specify target platform ``ARM``. + +Toolset Selection +^^^^^^^^^^^^^^^^^ + +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 new file mode 100644 index 0000000..9c61641 --- /dev/null +++ b/Help/generator/Visual Studio 14 2015.rst @@ -0,0 +1,65 @@ +Visual Studio 14 2015 +--------------------- + +.. versionadded:: 3.1 + +Generates Visual Studio 14 (VS 2015) project files. + +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 the generator name. +This is supported only for: + +``Visual Studio 14 2015 Win64`` + Specify target platform ``x64``. + +``Visual Studio 14 2015 ARM`` + Specify target platform ``ARM``. + +Toolset Selection +^^^^^^^^^^^^^^^^^ + +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 + +.. _`Windows 10 SDK Maximum Version for VS 2015`: + +Windows 10 SDK Maximum Version for VS 2015 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 3.19 + +Microsoft stated in a "Windows 10 October 2018 Update" blog post that Windows +10 SDK versions (15063, 16299, 17134, 17763) are not supported by VS 2015 and +are only supported by VS 2017 and later. Therefore by default CMake +automatically ignores Windows 10 SDKs beyond ``10.0.14393.0``. + +However, there are other recommendations for certain driver/Win32 builds that +indicate otherwise. A user can override this behavior by either setting the +:variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM` to a false value +or setting the :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM` to +the string value of the required maximum (e.g. ``10.0.15063.0``). diff --git a/Help/generator/Visual Studio 15 2017.rst b/Help/generator/Visual Studio 15 2017.rst new file mode 100644 index 0000000..a002f2f --- /dev/null +++ b/Help/generator/Visual Studio 15 2017.rst @@ -0,0 +1,66 @@ +Visual Studio 15 2017 +--------------------- + +.. versionadded:: 3.7.1 + +Generates Visual Studio 15 (VS 2017) 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 +^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 3.9 + 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. + +.. versionadded:: 3.11 + 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 the generator name. +This is supported only for: + +``Visual Studio 15 2017 Win64`` + Specify target platform ``x64``. + +``Visual Studio 15 2017 ARM`` + Specify target platform ``ARM``. + +Toolset Selection +^^^^^^^^^^^^^^^^^ + +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 0000000..3da8091 --- /dev/null +++ b/Help/generator/Visual Studio 16 2019.rst @@ -0,0 +1,56 @@ +Visual Studio 16 2019 +--------------------- + +.. versionadded:: 3.14 + +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 6.rst b/Help/generator/Visual Studio 6.rst new file mode 100644 index 0000000..2dd07e0 --- /dev/null +++ b/Help/generator/Visual Studio 6.rst @@ -0,0 +1,6 @@ +Visual Studio 6 +--------------- + +Removed. This once generated Visual Studio 6 project files, but the +generator has been removed since CMake 3.6. It is still possible to +build with VS 6 tools using the :generator:`NMake Makefiles` generator. diff --git a/Help/generator/Visual Studio 7 .NET 2003.rst b/Help/generator/Visual Studio 7 .NET 2003.rst new file mode 100644 index 0000000..d4c7869 --- /dev/null +++ b/Help/generator/Visual Studio 7 .NET 2003.rst @@ -0,0 +1,6 @@ +Visual Studio 7 .NET 2003 +------------------------- + +Removed. This once generated Visual Studio .NET 2003 project files, but +the generator has been removed since CMake 3.9. It is still possible to +build with VS 7.1 tools using the :generator:`NMake Makefiles` generator. diff --git a/Help/generator/Visual Studio 7.rst b/Help/generator/Visual Studio 7.rst new file mode 100644 index 0000000..54d29df --- /dev/null +++ b/Help/generator/Visual Studio 7.rst @@ -0,0 +1,6 @@ +Visual Studio 7 +--------------- + +Removed. This once generated Visual Studio .NET 2002 project files, but +the generator has been removed since CMake 3.6. It is still possible to +build with VS 7.0 tools using the :generator:`NMake Makefiles` generator. diff --git a/Help/generator/Visual Studio 8 2005.rst b/Help/generator/Visual Studio 8 2005.rst new file mode 100644 index 0000000..947e7a5 --- /dev/null +++ b/Help/generator/Visual Studio 8 2005.rst @@ -0,0 +1,6 @@ +Visual Studio 8 2005 +-------------------- + +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 new file mode 100644 index 0000000..644f936 --- /dev/null +++ b/Help/generator/Visual Studio 9 2008.rst @@ -0,0 +1,33 @@ +Visual Studio 9 2008 +-------------------- + +Generates Visual Studio 9 2008 project files. + +Platform Selection +^^^^^^^^^^^^^^^^^^ + +The default target platform name (architecture) is ``Win32``. + +.. versionadded:: 3.1 + 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 the generator name. +This is supported only for: + +``Visual Studio 9 2008 Win64`` + Specify target platform ``x64``. + +``Visual Studio 9 2008 IA64`` + Specify target platform ``Itanium``. + +``Visual Studio 9 2008 <WinCE-SDK>`` + Specify target platform matching a Windows CE SDK name. diff --git a/Help/generator/Watcom WMake.rst b/Help/generator/Watcom WMake.rst new file mode 100644 index 0000000..09bdc3d --- /dev/null +++ b/Help/generator/Watcom WMake.rst @@ -0,0 +1,4 @@ +Watcom WMake +------------ + +Generates Watcom WMake makefiles. diff --git a/Help/generator/Xcode.rst b/Help/generator/Xcode.rst new file mode 100644 index 0000000..e4900a1 --- /dev/null +++ b/Help/generator/Xcode.rst @@ -0,0 +1,46 @@ +Xcode +----- + +Generate Xcode project files. + +.. versionchanged:: 3.15 + This generator supports Xcode 5.0 and above. + +.. _`Xcode Build System Selection`: + +Toolset and Build System Selection +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +By default Xcode is allowed to select its own default toolchain. +The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps +via the :manual:`cmake(1)` ``-T`` option, to specify another toolset. + +.. versionadded:: 3.19 + This generator supports toolset specification using one of these forms: + +* ``toolset`` +* ``toolset[,key=value]*`` +* ``key=value[,key=value]*`` + +The ``toolset`` specifies the toolset name. The selected toolset name +is provided in the :variable:`CMAKE_XCODE_PLATFORM_TOOLSET` variable. + +The ``key=value`` pairs form a comma-separated list of options to +specify generator-specific details of the toolset selection. +Supported pairs are: + +``buildsystem=<variant>`` + Specify the buildsystem variant to use. + See the :variable:`CMAKE_XCODE_BUILD_SYSTEM` variable for allowed values. + + For example, to select the original build system under Xcode 12, + run :manual:`cmake(1)` with the option ``-T buildsystem=1``. + +Swift Support +^^^^^^^^^^^^^ + +.. versionadded:: 3.4 + +When using the :generator:`Xcode` generator with Xcode 6.1 or higher, +one may enable the ``Swift`` language with the :command:`enable_language` +command or the :command:`project`. diff --git a/Help/guide/ide-integration/index.rst b/Help/guide/ide-integration/index.rst new file mode 100644 index 0000000..addf932 --- /dev/null +++ b/Help/guide/ide-integration/index.rst @@ -0,0 +1,126 @@ +IDE Integration Guide +********************* + +.. only:: html + + .. contents:: + +Introduction +============ + +Integrated development environments (IDEs) may want to integrate with CMake to +improve the development experience for CMake users. This document lays out the +recommended best practices for such integration. + +Bundling +======== + +Many IDE vendors will want to bundle a copy of CMake with their IDE. IDEs that +bundle CMake should present the user with the option of using an external CMake +installation instead of the bundled one, in case the bundled copy becomes +outdated and the user wants to use a newer version. + +While IDE vendors may be tempted to bundle different versions of CMake with +their application, such practice is not recommended. CMake has strong +guarantees of backwards compatibility, and there is no reason not to use a +newer version of CMake than what a project requires, or indeed, the very latest +version. Therefore, it is recommended that IDE vendors that bundle CMake with +their application always include the very latest patch version of CMake +available at the time of release. + +As a suggestion, IDEs may also ship a copy of the Ninja buildsystem alongside +CMake. Ninja is highly performant and well-supported on all platforms that +support CMake. IDEs that bundle Ninja should use Ninja 1.10 or later, which +contains features needed to support Fortran builds. + +Presets +======= + +CMake supports a file format called ``CMakePresets.json``, and its +user-specific counterpart, ``CMakeUserPresets.json``. This file contains +information on the various configure presets that a user may want. Each preset +may have a different compiler, build flags, etc. The details of this format are +explained in the :manual:`cmake(1)` manual. + +IDE vendors are encouraged to read and evaluate this file the same way CMake +does, and present the user with the presets listed in the file. Users should be +able to see (and possibly edit) the CMake cache variables, environment +variables, and command line options that are defined for a given preset. The +IDE should then construct the list of appropriate :manual:`cmake(1)` command +line arguments based on these settings, rather than using the ``--preset=`` +option directly. The ``--preset=`` option is intended only as a convenient +frontend for command line users, and should not be used by the IDE. + +For example, if a preset named ``ninja`` specifies ``Ninja`` as the generator +and ``${sourceDir}/build`` as the build directory, instead of running: + +.. code-block:: console + + cmake -S /path/to/source --preset=ninja + +the IDE should instead calculate the settings of the ``ninja`` preset, and then +run: + +.. code-block:: console + + cmake -S /path/to/source -B /path/to/source/build -G Ninja + +While reading, parsing, and evaluating the contents of ``CMakePresets.json`` is +straightforward, it is not trivial. In addition to the documentation, IDE +vendors may also wish to refer to the CMake source code and test cases for a +better understanding of how to implement the format. +:download:`This file </manual/presets/schema.json>` provides a machine-readable +JSON schema for the ``CMakePresets.json`` format that IDE vendors may find +useful for validation and providing editing assistance. + +Configuring +=========== + +IDEs that invoke :manual:`cmake(1)` to run the configure step may wish to +receive information about the artifacts that the build will produce, as well +as the include directories, compile definitions, etc. used to build the +artifacts. Such information can be obtained by using the +:manual:`File API <cmake-file-api(7)>`. The manual page for the File API +contains more information about the API and how to invoke it. +:manual:`Server mode <cmake-server(7)>` was removed as of CMake 3.20 and +should not be used on CMake 3.14 or later. + +IDEs should avoid creating more build trees than necessary, and only create +multiple build trees if the user wishes to switch to a different compiler, +use different compile flags, etc. In particular, IDEs should NOT create +multiple single-config build trees which all have the same properties except +for a differing :variable:`CMAKE_BUILD_TYPE`, effectively creating a +multi-config environment. Instead, the :generator:`Ninja Multi-Config` +generator, in conjunction with the :manual:`File API <cmake-file-api(7)>` to +get the list of build configurations, should be used for this purpose. + +IDEs should not use the "extra generators" with Makefile or Ninja generators, +which generate IDE project files in addition to the Makefile or Ninja files. +Instead the :manual:`File API <cmake-file-api(7)>` should be used to get the +list of build artifacts. + +Building +======== + +If a Makefile or Ninja generator is used to generate the build tree, it is not +recommended to invoke ``make`` or ``ninja`` directly. Instead, it is +recommended that the IDE invoke :manual:`cmake(1)` with the ``--build`` +argument, which will in turn invoke the appropriate build tool. + +If an IDE project generator is used, such as :generator:`Xcode` or one of the +Visual Studio generators, and the IDE understands the project format used, the +IDE should read the project file and build it the same way it would otherwise. + +The :manual:`File API <cmake-file-api(7)>` can be used to obtain a list of +build configurations from the build tree, and the IDE should present this list +to the user to select a build configuration. + +Testing +======= + +:manual:`ctest(1)` supports outputting a JSON format with information about the +available tests and test configurations. IDEs which want to run CTest should +obtain this information and use it to present the user with a list of tests. + +IDEs should not invoke the ``test`` target of the generated buildsystem. +Instead, they should invoke :manual:`ctest(1)` directly. diff --git a/Help/guide/importing-exporting/Downstream/CMakeLists.txt b/Help/guide/importing-exporting/Downstream/CMakeLists.txt new file mode 100644 index 0000000..381c875 --- /dev/null +++ b/Help/guide/importing-exporting/Downstream/CMakeLists.txt @@ -0,0 +1,15 @@ +cmake_minimum_required(VERSION 3.15) +project(Downstream) + +# specify the C++ standard +set(CMAKE_CXX_STANDARD 11) +set(CMAKE_CXX_STANDARD_REQUIRED True) + +# find MathFunctions +find_package(MathFunctions 3.4.1 EXACT) + +# create executable +add_executable(myexe main.cc) + +# use MathFunctions library +target_link_libraries(myexe PRIVATE MathFunctions::MathFunctions) diff --git a/Help/guide/importing-exporting/Downstream/main.cc b/Help/guide/importing-exporting/Downstream/main.cc new file mode 100644 index 0000000..8574373 --- /dev/null +++ b/Help/guide/importing-exporting/Downstream/main.cc @@ -0,0 +1,23 @@ +// A simple program that outputs the square root of a number +#include <iostream> +#include <string> + +#include "MathFunctions.h" + +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 = std::stod(argv[1]); + + // calculate square root + const double sqrt = MathFunctions::sqrt(inputValue); + std::cout << "The square root of " << inputValue << " is " << sqrt + << std::endl; + + return 0; +} diff --git a/Help/guide/importing-exporting/DownstreamComponents/CMakeLists.txt b/Help/guide/importing-exporting/DownstreamComponents/CMakeLists.txt new file mode 100644 index 0000000..88b46c8 --- /dev/null +++ b/Help/guide/importing-exporting/DownstreamComponents/CMakeLists.txt @@ -0,0 +1,18 @@ +cmake_minimum_required(VERSION 3.15) +project(DownstreamComponents) + +# specify the C++ standard +set(CMAKE_CXX_STANDARD 11) +set(CMAKE_CXX_STANDARD_REQUIRED True) + +# find MathFunctions +find_package(MathFunctions 3.4 COMPONENTS Addition SquareRoot) + +# create executable +add_executable(myexe main.cc) + +# use MathFunctions library +target_link_libraries(myexe PRIVATE MathFunctions::Addition MathFunctions::SquareRoot) + +# Workaround for GCC on AIX to avoid -isystem, not needed in general. +set_property(TARGET myexe PROPERTY NO_SYSTEM_FROM_IMPORTED 1) diff --git a/Help/guide/importing-exporting/DownstreamComponents/main.cc b/Help/guide/importing-exporting/DownstreamComponents/main.cc new file mode 100644 index 0000000..f5e8fa6 --- /dev/null +++ b/Help/guide/importing-exporting/DownstreamComponents/main.cc @@ -0,0 +1,28 @@ +// A simple program that outputs the square root of a number +#include <iostream> +#include <string> + +#include "Addition.h" +#include "SquareRoot.h" + +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 = std::stod(argv[1]); + + // calculate square root + const double sqrt = MathFunctions::sqrt(inputValue); + std::cout << "The square root of " << inputValue << " is " << sqrt + << std::endl; + + // calculate sum + const double sum = MathFunctions::add(inputValue, inputValue); + std::cout << inputValue << " + " << inputValue << " = " << sum << std::endl; + + return 0; +} diff --git a/Help/guide/importing-exporting/Importing/CMakeLists.txt b/Help/guide/importing-exporting/Importing/CMakeLists.txt new file mode 100644 index 0000000..fe7d704 --- /dev/null +++ b/Help/guide/importing-exporting/Importing/CMakeLists.txt @@ -0,0 +1,19 @@ +cmake_minimum_required(VERSION 3.15) +project(Importing) + +# specify the C++ standard +set(CMAKE_CXX_STANDARD 11) +set(CMAKE_CXX_STANDARD_REQUIRED True) + +# Add executable +add_executable(myexe IMPORTED) + +# Set imported location +set_property(TARGET myexe PROPERTY + IMPORTED_LOCATION "../InstallMyExe/bin/myexe") + +# Add custom command to create source file +add_custom_command(OUTPUT main.cc COMMAND myexe) + +# Use source file +add_executable(mynewexe main.cc) diff --git a/Help/guide/importing-exporting/MathFunctions/CMakeLists.txt b/Help/guide/importing-exporting/MathFunctions/CMakeLists.txt new file mode 100644 index 0000000..d277b54 --- /dev/null +++ b/Help/guide/importing-exporting/MathFunctions/CMakeLists.txt @@ -0,0 +1,78 @@ +cmake_minimum_required(VERSION 3.15) +project(MathFunctions) + +# make cache variables for install destinations +include(GNUInstallDirs) + +# specify the C++ standard +set(CMAKE_CXX_STANDARD 11) +set(CMAKE_CXX_STANDARD_REQUIRED True) + +# create library +add_library(MathFunctions STATIC MathFunctions.cxx) + +# add include directories +target_include_directories(MathFunctions + PUBLIC + "$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>" + "$<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>" +) + +# install the target and create export-set +install(TARGETS MathFunctions + EXPORT MathFunctionsTargets + LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR} + ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR} + RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR} + INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR} +) + +# install header file +install(FILES MathFunctions.h DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}) + +# generate and install export file +install(EXPORT MathFunctionsTargets + FILE MathFunctionsTargets.cmake + NAMESPACE MathFunctions:: + DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MathFunctions +) + +# include CMakePackageConfigHelpers macro +include(CMakePackageConfigHelpers) + +# set version +set(version 3.4.1) + +set_property(TARGET MathFunctions PROPERTY VERSION ${version}) +set_property(TARGET MathFunctions PROPERTY SOVERSION 3) +set_property(TARGET MathFunctions PROPERTY + INTERFACE_MathFunctions_MAJOR_VERSION 3) +set_property(TARGET MathFunctions APPEND PROPERTY + COMPATIBLE_INTERFACE_STRING MathFunctions_MAJOR_VERSION +) + +# generate the version file for the config file +write_basic_package_version_file( + "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfigVersion.cmake" + VERSION "${version}" + COMPATIBILITY AnyNewerVersion +) + +# create config file +configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in + "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake" + INSTALL_DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MathFunctions +) + +# install config files +install(FILES + "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake" + "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfigVersion.cmake" + DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MathFunctions +) + +# generate the export targets for the build tree +export(EXPORT MathFunctionsTargets + FILE "${CMAKE_CURRENT_BINARY_DIR}/cmake/MathFunctionsTargets.cmake" + NAMESPACE MathFunctions:: +) diff --git a/Help/guide/importing-exporting/MathFunctions/Config.cmake.in b/Help/guide/importing-exporting/MathFunctions/Config.cmake.in new file mode 100644 index 0000000..eba1ff6 --- /dev/null +++ b/Help/guide/importing-exporting/MathFunctions/Config.cmake.in @@ -0,0 +1,5 @@ +@PACKAGE_INIT@ + +include("${CMAKE_CURRENT_LIST_DIR}/MathFunctionsTargets.cmake") + +check_required_components(MathFunctions) diff --git a/Help/guide/importing-exporting/MathFunctions/MathFunctions.cxx b/Help/guide/importing-exporting/MathFunctions/MathFunctions.cxx new file mode 100644 index 0000000..e75fe74 --- /dev/null +++ b/Help/guide/importing-exporting/MathFunctions/MathFunctions.cxx @@ -0,0 +1,10 @@ +#include "MathFunctions.h" + +#include <cmath> + +namespace MathFunctions { +double sqrt(double x) +{ + return std::sqrt(x); +} +} diff --git a/Help/guide/importing-exporting/MathFunctions/MathFunctions.h b/Help/guide/importing-exporting/MathFunctions/MathFunctions.h new file mode 100644 index 0000000..b38596d --- /dev/null +++ b/Help/guide/importing-exporting/MathFunctions/MathFunctions.h @@ -0,0 +1,5 @@ +#pragma once + +namespace MathFunctions { +double sqrt(double x); +} diff --git a/Help/guide/importing-exporting/MathFunctionsComponents/Addition/Addition.cxx b/Help/guide/importing-exporting/MathFunctionsComponents/Addition/Addition.cxx new file mode 100644 index 0000000..0a6b98b --- /dev/null +++ b/Help/guide/importing-exporting/MathFunctionsComponents/Addition/Addition.cxx @@ -0,0 +1,8 @@ +#include "Addition.h" + +namespace MathFunctions { +double add(double x, double y) +{ + return x + y; +} +} diff --git a/Help/guide/importing-exporting/MathFunctionsComponents/Addition/Addition.h b/Help/guide/importing-exporting/MathFunctionsComponents/Addition/Addition.h new file mode 100644 index 0000000..b061d5e --- /dev/null +++ b/Help/guide/importing-exporting/MathFunctionsComponents/Addition/Addition.h @@ -0,0 +1,5 @@ +#pragma once + +namespace MathFunctions { +double add(double x, double y); +} diff --git a/Help/guide/importing-exporting/MathFunctionsComponents/Addition/CMakeLists.txt b/Help/guide/importing-exporting/MathFunctionsComponents/Addition/CMakeLists.txt new file mode 100644 index 0000000..9de935e --- /dev/null +++ b/Help/guide/importing-exporting/MathFunctionsComponents/Addition/CMakeLists.txt @@ -0,0 +1,30 @@ +# create library +add_library(Addition STATIC Addition.cxx) + +add_library(MathFunctions::Addition ALIAS Addition) + +# add include directories +target_include_directories(Addition + PUBLIC + "$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>" + $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}> +) + +# install the target and create export-set +install(TARGETS Addition + EXPORT AdditionTargets + LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR} + ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR} + RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR} + INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR} +) + +# install header file +install(FILES Addition.h DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}) + +# generate and install export file +install(EXPORT AdditionTargets + FILE MathFunctionsAdditionTargets.cmake + NAMESPACE MathFunctions:: + DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MathFunctions +) diff --git a/Help/guide/importing-exporting/MathFunctionsComponents/CMakeLists.txt b/Help/guide/importing-exporting/MathFunctionsComponents/CMakeLists.txt new file mode 100644 index 0000000..90ee89f --- /dev/null +++ b/Help/guide/importing-exporting/MathFunctionsComponents/CMakeLists.txt @@ -0,0 +1,39 @@ +cmake_minimum_required(VERSION 3.15) +project(MathFunctionsComponents) + +# make cache variables for install destinations +include(GNUInstallDirs) + +# specify the C++ standard +set(CMAKE_CXX_STANDARD 11) +set(CMAKE_CXX_STANDARD_REQUIRED True) + +add_subdirectory(Addition) +add_subdirectory(SquareRoot) + +# include CMakePackageConfigHelpers macro +include(CMakePackageConfigHelpers) + +# set version +set(version 3.4.1) + +# generate the version file for the config file +write_basic_package_version_file( + "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfigVersion.cmake" + VERSION "${version}" + COMPATIBILITY AnyNewerVersion +) + +# create config file +configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in + "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake" + INSTALL_DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MathFunctions + NO_CHECK_REQUIRED_COMPONENTS_MACRO +) + +# install config files +install(FILES + "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake" + "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfigVersion.cmake" + DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MathFunctions +) diff --git a/Help/guide/importing-exporting/MathFunctionsComponents/Config.cmake.in b/Help/guide/importing-exporting/MathFunctionsComponents/Config.cmake.in new file mode 100644 index 0000000..09f6c35 --- /dev/null +++ b/Help/guide/importing-exporting/MathFunctionsComponents/Config.cmake.in @@ -0,0 +1,11 @@ +@PACKAGE_INIT@ + +set(_supported_components Addition SquareRoot) + +foreach(_comp ${MathFunctions_FIND_COMPONENTS}) + if (NOT _comp IN_LIST _supported_components) + set(MathFunctions_FOUND False) + set(MathFunctions_NOT_FOUND_MESSAGE "Unsupported component: ${_comp}") + endif() + include("${CMAKE_CURRENT_LIST_DIR}/MathFunctions${_comp}Targets.cmake") +endforeach() diff --git a/Help/guide/importing-exporting/MathFunctionsComponents/MathFunctions.cxx b/Help/guide/importing-exporting/MathFunctionsComponents/MathFunctions.cxx new file mode 100644 index 0000000..e75fe74 --- /dev/null +++ b/Help/guide/importing-exporting/MathFunctionsComponents/MathFunctions.cxx @@ -0,0 +1,10 @@ +#include "MathFunctions.h" + +#include <cmath> + +namespace MathFunctions { +double sqrt(double x) +{ + return std::sqrt(x); +} +} diff --git a/Help/guide/importing-exporting/MathFunctionsComponents/MathFunctions.h b/Help/guide/importing-exporting/MathFunctionsComponents/MathFunctions.h new file mode 100644 index 0000000..b38596d --- /dev/null +++ b/Help/guide/importing-exporting/MathFunctionsComponents/MathFunctions.h @@ -0,0 +1,5 @@ +#pragma once + +namespace MathFunctions { +double sqrt(double x); +} diff --git a/Help/guide/importing-exporting/MathFunctionsComponents/SquareRoot/CMakeLists.txt b/Help/guide/importing-exporting/MathFunctionsComponents/SquareRoot/CMakeLists.txt new file mode 100644 index 0000000..517c5e2 --- /dev/null +++ b/Help/guide/importing-exporting/MathFunctionsComponents/SquareRoot/CMakeLists.txt @@ -0,0 +1,30 @@ +# create library +add_library(SquareRoot STATIC SquareRoot.cxx) + +add_library(MathFunctions::SquareRoot ALIAS SquareRoot) + +# add include directories +target_include_directories(SquareRoot + PUBLIC + "$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>" + "$<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>" +) + +# install the target and create export-set +install(TARGETS SquareRoot + EXPORT SquareRootTargets + LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR} + ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR} + RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR} + INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR} +) + +# install header file +install(FILES SquareRoot.h DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}) + +# generate and install export file +install(EXPORT SquareRootTargets + FILE MathFunctionsSquareRootTargets.cmake + NAMESPACE MathFunctions:: + DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MathFunctions +) diff --git a/Help/guide/importing-exporting/MathFunctionsComponents/SquareRoot/SquareRoot.cxx b/Help/guide/importing-exporting/MathFunctionsComponents/SquareRoot/SquareRoot.cxx new file mode 100644 index 0000000..29c0c4a --- /dev/null +++ b/Help/guide/importing-exporting/MathFunctionsComponents/SquareRoot/SquareRoot.cxx @@ -0,0 +1,10 @@ +#include "SquareRoot.h" + +#include <cmath> + +namespace MathFunctions { +double sqrt(double x) +{ + return std::sqrt(x); +} +} diff --git a/Help/guide/importing-exporting/MathFunctionsComponents/SquareRoot/SquareRoot.h b/Help/guide/importing-exporting/MathFunctionsComponents/SquareRoot/SquareRoot.h new file mode 100644 index 0000000..b38596d --- /dev/null +++ b/Help/guide/importing-exporting/MathFunctionsComponents/SquareRoot/SquareRoot.h @@ -0,0 +1,5 @@ +#pragma once + +namespace MathFunctions { +double sqrt(double x); +} diff --git a/Help/guide/importing-exporting/MyExe/CMakeLists.txt b/Help/guide/importing-exporting/MyExe/CMakeLists.txt new file mode 100644 index 0000000..34e37a4 --- /dev/null +++ b/Help/guide/importing-exporting/MyExe/CMakeLists.txt @@ -0,0 +1,12 @@ +cmake_minimum_required(VERSION 3.15) +project(MyExe) + +# specify the C++ standard +set(CMAKE_CXX_STANDARD 11) +set(CMAKE_CXX_STANDARD_REQUIRED True) + +# Add executable +add_executable(myexe main.cxx) + +# install executable +install(TARGETS myexe) diff --git a/Help/guide/importing-exporting/MyExe/main.cxx b/Help/guide/importing-exporting/MyExe/main.cxx new file mode 100644 index 0000000..35ab2a7 --- /dev/null +++ b/Help/guide/importing-exporting/MyExe/main.cxx @@ -0,0 +1,16 @@ +// A simple program that outputs a file with the given name +#include <fstream> +#include <iostream> + +int main(int argc, char* argv[]) +{ + std::ofstream outfile("main.cc"); + outfile << "int main(int argc, char* argv[])" << std::endl; + outfile << "{" << std::endl; + outfile << " // Your code here" << std::endl; + outfile << " return 0;" << std::endl; + outfile << "}" << std::endl; + outfile.close(); + + return 0; +} diff --git a/Help/guide/importing-exporting/index.rst b/Help/guide/importing-exporting/index.rst new file mode 100644 index 0000000..3e60250 --- /dev/null +++ b/Help/guide/importing-exporting/index.rst @@ -0,0 +1,772 @@ +Importing and Exporting Guide +***************************** + +.. only:: html + + .. contents:: + +Introduction +============ + +In this guide, we will present the concept of :prop_tgt:`IMPORTED` targets +and demonstrate how to import existing executable or library files from disk +into a CMake project. We will then show how CMake supports exporting targets +from one CMake-based project and importing them into another. Finally, we +will demonstrate how to package a project with a configuration file to allow +for easy integration into other CMake projects. This guide and the complete +example source code can be found in the ``Help/guide/importing-exporting`` +directory of the CMake source code tree. + + +Importing Targets +================= + +:prop_tgt:`IMPORTED` targets are used to convert files outside of a CMake +project into logical targets inside of the project. :prop_tgt:`IMPORTED` +targets are created using the ``IMPORTED`` option of the +:command:`add_executable` and :command:`add_library` commands. No build +files are generated for :prop_tgt:`IMPORTED` targets. Once imported, +:prop_tgt:`IMPORTED` targets may be referenced like any other target within +the project and provide a convenient, flexible reference to outside +executables and libraries. + +By default, the :prop_tgt:`IMPORTED` target name has scope in the directory in +which it is created and below. We can use the ``GLOBAL`` option to extended +visibility so that the target is accessible globally in the build system. + +Details about the :prop_tgt:`IMPORTED` target are specified by setting +properties whose names begin in ``IMPORTED_`` and ``INTERFACE_``. For example, +:prop_tgt:`IMPORTED_LOCATION` contains the full path to the target on +disk. + +Importing Executables +--------------------- + +To start, we will walk through a simple example that creates an +:prop_tgt:`IMPORTED` executable target and then references it from the +:command:`add_custom_command` command. + +We'll need to do some setup to get started. We want to create an executable +that when run creates a basic ``main.cc`` file in the current directory. The +details of this project are not important. Navigate to +``Help/guide/importing-exporting/MyExe``, create a build directory, run +:manual:`cmake <cmake(1)>` and build and install the project. + +.. code-block:: console + + $ cd Help/guide/importing-exporting/MyExe + $ mkdir build + $ cd build + $ cmake .. + $ cmake --build . + $ cmake --install . --prefix <install location> + $ <install location>/myexe + $ ls + [...] main.cc [...] + +Now we can import this executable into another CMake project. The source code +for this section is available in ``Help/guide/importing-exporting/Importing``. +In the CMakeLists file, use the :command:`add_executable` command to create a +new target called ``myexe``. Use the ``IMPORTED`` option to tell CMake that +this target references an executable file located outside of the project. No +rules will be generated to build it and the :prop_tgt:`IMPORTED` target +property will be set to ``true``. + +.. literalinclude:: Importing/CMakeLists.txt + :language: cmake + :start-after: # Add executable + :end-before: # Set imported location + +Next, set the :prop_tgt:`IMPORTED_LOCATION` property of the target using +the :command:`set_property` command. This will tell CMake the location of the +target on disk. The location may need to be adjusted to the +``<install location>`` specified in the previous step. + +.. literalinclude:: Importing/CMakeLists.txt + :language: cmake + :start-after: # Set imported location + :end-before: # Add custom command + +We can now reference this :prop_tgt:`IMPORTED` target just like any target +built within the project. In this instance, let's imagine that we want to use +the generated source file in our project. Use the :prop_tgt:`IMPORTED` +target in the :command:`add_custom_command` command: + +.. literalinclude:: Importing/CMakeLists.txt + :language: cmake + :start-after: # Add custom command + :end-before: # Use source file + +As ``COMMAND`` specifies an executable target name, it will automatically be +replaced by the location of the executable given by the +:prop_tgt:`IMPORTED_LOCATION` property above. + +Finally, use the output from :command:`add_custom_command`: + +.. literalinclude:: Importing/CMakeLists.txt + :language: cmake + :start-after: # Use source file + +Importing Libraries +------------------- + +In a similar manner, libraries from other projects may be accessed through +:prop_tgt:`IMPORTED` targets. + +Note: The full source code for the examples in this section is not provided +and is left as an exercise for the reader. + +In the CMakeLists file, add an :prop_tgt:`IMPORTED` library and specify its +location on disk: + +.. code-block:: cmake + + add_library(foo STATIC IMPORTED) + set_property(TARGET foo PROPERTY + IMPORTED_LOCATION "/path/to/libfoo.a") + +Then use the :prop_tgt:`IMPORTED` library inside of our project: + +.. code-block:: cmake + + add_executable(myexe src1.c src2.c) + target_link_libraries(myexe PRIVATE foo) + + +On Windows, a .dll and its .lib import library may be imported together: + +.. code-block:: cmake + + add_library(bar SHARED IMPORTED) + set_property(TARGET bar PROPERTY + IMPORTED_LOCATION "c:/path/to/bar.dll") + set_property(TARGET bar PROPERTY + IMPORTED_IMPLIB "c:/path/to/bar.lib") + add_executable(myexe src1.c src2.c) + target_link_libraries(myexe PRIVATE bar) + +A library with multiple configurations may be imported with a single target: + +.. code-block:: cmake + + find_library(math_REL NAMES m) + find_library(math_DBG NAMES md) + add_library(math STATIC IMPORTED GLOBAL) + set_target_properties(math PROPERTIES + IMPORTED_LOCATION "${math_REL}" + IMPORTED_LOCATION_DEBUG "${math_DBG}" + IMPORTED_CONFIGURATIONS "RELEASE;DEBUG" + ) + add_executable(myexe src1.c src2.c) + target_link_libraries(myexe PRIVATE math) + +The generated build system will link ``myexe`` to ``m.lib`` when built in the +release configuration, and ``md.lib`` when built in the debug configuration. + +Exporting Targets +================= + +While :prop_tgt:`IMPORTED` targets on their own are useful, they still +require that the project that imports them knows the locations of the target +files on disk. The real power of :prop_tgt:`IMPORTED` targets is when the +project providing the target files also provides a CMake file to help import +them. A project can be setup to produce the necessary information so that it +can easily be used by other CMake projects be it from a build directory, a +local install or when packaged. + +In the remaining sections, we will walk through a set of example projects +step-by-step. The first project will create and install a library and +corresponding CMake configuration and package files. The second project will +use the generated package. + +Let's start by looking at the ``MathFunctions`` project in the +``Help/guide/importing-exporting/MathFunctions`` directory. Here we have a +header file ``MathFunctions.h`` that declares a ``sqrt`` function: + +.. literalinclude:: MathFunctions/MathFunctions.h + :language: c++ + +And a corresponding source file ``MathFunctions.cxx``: + +.. literalinclude:: MathFunctions/MathFunctions.cxx + :language: c++ + +Don't worry too much about the specifics of the C++ files, they are just meant +to be a simple example that will compile and run on many build systems. + +Now we can create a ``CMakeLists.txt`` file for the ``MathFunctions`` +project. Start by specifying the :command:`cmake_minimum_required` version and +:command:`project` name: + +.. literalinclude:: MathFunctions/CMakeLists.txt + :language: cmake + :end-before: # create library + +The :module:`GNUInstallDirs` module is included in order to provide the +project with the flexibility to install into different platform layouts by +making the directories available as cache variables. + +Create a library called ``MathFunctions`` with the :command:`add_library` +command: + +.. literalinclude:: MathFunctions/CMakeLists.txt + :language: cmake + :start-after: # create library + :end-before: # add include directories + +And then use the :command:`target_include_directories` command to specify the +include directories for the target: + +.. literalinclude:: MathFunctions/CMakeLists.txt + :language: cmake + :start-after: # add include directories + :end-before: # install the target and create export-set + +We need to tell CMake that we want to use different include directories +depending on if we're building the library or using it from an installed +location. If we don't do this, when CMake creates the export information it +will export a path that is specific to the current build directory +and will not be valid for other projects. We can use +:manual:`generator expressions <cmake-generator-expressions(7)>` to specify +that if we're building the library include the current source directory. +Otherwise, when installed, include the ``include`` directory. See the `Creating +Relocatable Packages`_ section for more details. + +The :command:`install(TARGETS)` and :command:`install(EXPORT)` commands +work together to install both targets (a library in our case) and a CMake +file designed to make it easy to import the targets into another CMake project. + +First, in the :command:`install(TARGETS)` command we will specify the target, +the ``EXPORT`` name and the destinations that tell CMake where to install the +targets. + +.. literalinclude:: MathFunctions/CMakeLists.txt + :language: cmake + :start-after: # install the target and create export-set + :end-before: # install header file + +Here, the ``EXPORT`` option tells CMake to create an export called +``MathFunctionsTargets``. The generated :prop_tgt:`IMPORTED` targets have +appropriate properties set to define their +:ref:`usage requirements <Target Usage Requirements>`, such as +:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`, +:prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` and other relevant built-in +``INTERFACE_`` properties. The ``INTERFACE`` variant of user-defined +properties listed in :prop_tgt:`COMPATIBLE_INTERFACE_STRING` and other +:ref:`Compatible Interface Properties` are also propagated to the +generated :prop_tgt:`IMPORTED` targets. For example, in this case, the +:prop_tgt:`IMPORTED` target will have its +:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` property populated with +the directory specified by the ``INCLUDES DESTINATION`` property. As a +relative path was given, it is treated as relative to the +:variable:`CMAKE_INSTALL_PREFIX`. + +Note, we have *not* asked CMake to install the export yet. + +We don't want to forget to install the ``MathFunctions.h`` header file with the +:command:`install(FILES)` command. The header file should be installed to the +``include`` directory, as specified by the +:command:`target_include_directories` command above. + +.. literalinclude:: MathFunctions/CMakeLists.txt + :language: cmake + :start-after: # install header file + :end-before: # generate and install export file + +Now that the ``MathFunctions`` library and header file are installed, we also +need to explicitly install the ``MathFunctionsTargets`` export details. Use +the :command:`install(EXPORT)` command to export the targets in +``MathFunctionsTargets``, as defined by the :command:`install(TARGETS)` +command. + +.. literalinclude:: MathFunctions/CMakeLists.txt + :language: cmake + :start-after: # generate and install export file + :end-before: # include CMakePackageConfigHelpers macro + +This command generates the ``MathFunctionsTargets.cmake`` file and arranges +to install it to ``lib/cmake``. The file contains code suitable for +use by downstreams to import all targets listed in the install command from +the installation tree. + +The ``NAMESPACE`` option will prepend ``MathFunctions::`` to the target names +as they are written to the export file. This convention of double-colons +gives CMake a hint that the name is an :prop_tgt:`IMPORTED` target when it +is used by downstream projects. This way, CMake can issue a diagnostic +message if the package providing it was not found. + +The generated export file contains code that creates an :prop_tgt:`IMPORTED` library. + +.. code-block:: cmake + + # Create imported target MathFunctions::MathFunctions + add_library(MathFunctions::MathFunctions STATIC IMPORTED) + + set_target_properties(MathFunctions::MathFunctions PROPERTIES + INTERFACE_INCLUDE_DIRECTORIES "${_IMPORT_PREFIX}/include" + ) + +This code is very similar to the example we created by hand in the +`Importing Libraries`_ section. Note that ``${_IMPORT_PREFIX}`` is computed +relative to the file location. + +An outside project may load this file with the :command:`include` command and +reference the ``MathFunctions`` library from the installation tree as if it +were built in its own tree. For example: + +.. code-block:: cmake + :linenos: + + include(${INSTALL_PREFIX}/lib/cmake/MathFunctionTargets.cmake) + add_executable(myexe src1.c src2.c ) + target_link_libraries(myexe PRIVATE MathFunctions::MathFunctions) + +Line 1 loads the target CMake file. Although we only exported a single +target, this file may import any number of targets. Their locations are +computed relative to the file location so that the install tree may be +easily moved. Line 3 references the imported ``MathFunctions`` library. The +resulting build system will link to the library from its installed location. + +Executables may also be exported and imported using the same process. + +Any number of target installations may be associated with the same +export name. Export names are considered global so any directory may +contribute a target installation. The :command:`install(EXPORT)` command only +needs to be called once to install a file that references all targets. Below +is an example of how multiple exports may be combined into a single +export file, even if they are in different subdirectories of the project. + +.. code-block:: cmake + + # A/CMakeLists.txt + add_executable(myexe src1.c) + install(TARGETS myexe DESTINATION lib/myproj + EXPORT myproj-targets) + + # B/CMakeLists.txt + add_library(foo STATIC foo1.c) + install(TARGETS foo DESTINATION lib EXPORTS myproj-targets) + + # Top CMakeLists.txt + add_subdirectory (A) + add_subdirectory (B) + install(EXPORT myproj-targets DESTINATION lib/myproj) + +Creating Packages +----------------- + +At this point, the ``MathFunctions`` project is exporting the target +information required to be used by other projects. We can make this project +even easier for other projects to use by generating a configuration file so +that the CMake :command:`find_package` command can find our project. + +To start, we will need to make a few additions to the ``CMakeLists.txt`` +file. First, include the :module:`CMakePackageConfigHelpers` module to get +access to some helper functions for creating config files. + +.. literalinclude:: MathFunctions/CMakeLists.txt + :language: cmake + :start-after: # include CMakePackageConfigHelpers macro + :end-before: # set version + +Then we will create a package configuration file and a package version file. + +Creating a Package Configuration File +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use the :command:`configure_package_config_file` command provided by the +:module:`CMakePackageConfigHelpers` to generate the package configuration +file. Note that this command should be used instead of the plain +:command:`configure_file` command. It helps to ensure that the resulting +package is relocatable by avoiding hardcoded paths in the installed +configuration file. The path given to ``INSTALL_DESTINATION`` must be the +destination where the ``MathFunctionsConfig.cmake`` file will be installed. +We will examine the contents of the package configuration file in the next +section. + +.. literalinclude:: MathFunctions/CMakeLists.txt + :language: cmake + :start-after: # create config file + :end-before: # install config files + +Install the generated configuration files with the :command:`INSTALL(files)` +command. Both ``MathFunctionsConfigVersion.cmake`` and +``MathFunctionsConfig.cmake`` are installed to the same location, completing +the package. + +.. literalinclude:: MathFunctions/CMakeLists.txt + :language: cmake + :start-after: # install config files + :end-before: # generate the export targets for the build tree + +Now we need to create the package configuration file itself. In this case, the +``Config.cmake.in`` file is very simple but sufficient to allow downstreams +to use the :prop_tgt:`IMPORTED` targets. + +.. literalinclude:: MathFunctions/Config.cmake.in + +The first line of the file contains only the string ``@PACKAGE_INIT@``. This +expands when the file is configured and allows the use of relocatable paths +prefixed with ``PACKAGE_``. It also provides the ``set_and_check()`` and +``check_required_components()`` macros. + +The ``check_required_components`` helper macro ensures that all requested, +non-optional components have been found by checking the +``<Package>_<Component>_FOUND`` variables for all required components. This +macro should be called at the end of the package configuration file even if the +package does not have any components. This way, CMake can make sure that the +downstream project hasn't specified any non-existent components. If +``check_required_components`` fails, the ``<Package>_FOUND`` variable is set to +FALSE, and the package is considered to be not found. + +The ``set_and_check()`` macro should be used in configuration files instead +of the normal ``set()`` command for setting directories and file locations. +If a referenced file or directory does not exist, the macro will fail. + +If any macros should be provided by the ``MathFunctions`` package, they should +be in a separate file which is installed to the same location as the +``MathFunctionsConfig.cmake`` file, and included from there. + +**All required dependencies of a package must also be found in the package +configuration file.** Let's imagine that we require the ``Stats`` library in +our project. In the CMakeLists file, we would add: + +.. code-block:: cmake + + find_package(Stats 2.6.4 REQUIRED) + target_link_libraries(MathFunctions PUBLIC Stats::Types) + +As the ``Stats::Types`` target is a ``PUBLIC`` dependency of ``MathFunctions``, +downstreams must also find the ``Stats`` package and link to the +``Stats::Types`` library. The ``Stats`` package should be found in the +configuration file to ensure this. + +.. code-block:: cmake + + include(CMakeFindDependencyMacro) + find_dependency(Stats 2.6.4) + +The ``find_dependency`` macro from the :module:`CMakeFindDependencyMacro` +module helps by propagating whether the package is ``REQUIRED``, or +``QUIET``, etc. The ``find_dependency`` macro also sets +``MathFunctions_FOUND`` to ``False`` if the dependency is not found, along +with a diagnostic that the ``MathFunctions`` package cannot be used without +the ``Stats`` package. + +**Exercise:** Add a required library to the ``MathFunctions`` project. + +Creating a Package Version File +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The :module:`CMakePackageConfigHelpers` module provides the +:command:`write_basic_package_version_file` command for creating a simple +package version file. This file 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 such as ``<PackageName>_VERSION``, +``<PackageName>_VERSION_MAJOR``, ``<PackageName>_VERSION_MINOR``, etc. See +:manual:`cmake-packages <cmake-packages(7)>` documentation for more details. + +.. literalinclude:: MathFunctions/CMakeLists.txt + :language: cmake + :start-after: # set version + :end-before: # create config file + +In our example, ``MathFunctions_MAJOR_VERSION`` is defined as a +:prop_tgt:`COMPATIBLE_INTERFACE_STRING` which means that it must be +compatible among the dependencies of any depender. By setting this +custom defined user property in this version and in the next version of +``MathFunctions``, :manual:`cmake <cmake(1)>` will issue a diagnostic if +there is an attempt to use version 3 together with version 4. Packages can +choose to employ such a pattern if different major versions of the package +are designed to be incompatible. + + +Exporting Targets from the Build Tree +------------------------------------- + +Typically, projects are built and installed before being used by an outside +project. However, in some cases, it is desirable to export targets directly +from a build tree. The targets may then be used by an outside project that +references the build tree with no installation involved. The :command:`export` +command is used to generate a file exporting targets from a project build tree. + +If we want our example project to also be used from a build directory we only +have to add the following to ``CMakeLists.txt``: + +.. literalinclude:: MathFunctions/CMakeLists.txt + :language: cmake + :start-after: # generate the export targets for the build tree + +Here we use the :command:`export` command to generate the export targets for +the build tree. In this case, we'll create a file called +``MathFunctionsTargets.cmake`` in the ``cmake`` subdirectory of the build +directory. The generated file contains the required code to import the target +and may be loaded by an outside project that is aware of the project build +tree. This file is specific to the build-tree, and **is not relocatable**. + +It is possible to create a suitable package configuration file and package +version file to define a package for the build tree which may be used without +installation. Consumers of the build tree can simply ensure that the +:variable:`CMAKE_PREFIX_PATH` contains the build directory, or set the +``MathFunctions_DIR`` to ``<build_dir>/MathFunctions`` in the cache. + +An example application of this feature is for building an executable on a host +platform when cross-compiling. The project containing the executable may be +built on the host platform and then the project that is being cross-compiled +for another platform may load it. + +Building and Installing a Package +--------------------------------- + +At this point, we have generated a relocatable CMake configuration for our +project that can be used after the project has been installed. Let's try to +build the ``MathFunctions`` project: + +.. code-block:: console + + mkdir MathFunctions_build + cd MathFunctions_build + cmake ../MathFunctions + cmake --build . + +In the build directory, notice that the file ``MathFunctionsTargets.cmake`` +has been created in the ``cmake`` subdirectory. + +Now install the project: + +.. code-block:: console + + $ cmake --install . --prefix "/home/myuser/installdir" + +Creating Relocatable Packages +============================= + +Packages created by :command:`install(EXPORT)` are designed to be relocatable, +using paths relative to the location of the package itself. They must not +reference absolute paths of files on the machine where the package is built +that will not exist on the machines where the package may be installed. + +When defining the interface of a target for ``EXPORT``, keep in mind that the +include directories should be specified as relative paths to the +:variable:`CMAKE_INSTALL_PREFIX` but should not explicitly include the +:variable:`CMAKE_INSTALL_PREFIX`: + +.. code-block:: cmake + + target_include_directories(tgt INTERFACE + # Wrong, not relocatable: + $<INSTALL_INTERFACE:${CMAKE_INSTALL_PREFIX}/include/TgtName> + ) + + target_include_directories(tgt INTERFACE + # Ok, relocatable: + $<INSTALL_INTERFACE:include/TgtName> + ) + +The ``$<INSTALL_PREFIX>`` +:manual:`generator expression <cmake-generator-expressions(7)>` may be used as +a placeholder for the install prefix without resulting in a non-relocatable +package. This is necessary if complex generator expressions are used: + +.. code-block:: cmake + + target_include_directories(tgt INTERFACE + # Ok, relocatable: + $<INSTALL_INTERFACE:$<INSTALL_PREFIX>/include/TgtName> + ) + +This also applies to paths referencing external dependencies. +It is not advisable to populate any properties which may contain +paths, such as :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` or +:prop_tgt:`INTERFACE_LINK_LIBRARIES`, with paths relevant to dependencies. +For example, this code may not work well for a relocatable package: + +.. code-block:: cmake + + target_link_libraries(MathFunctions INTERFACE + ${Foo_LIBRARIES} ${Bar_LIBRARIES} + ) + target_include_directories(MathFunctions INTERFACE + "$<INSTALL_INTERFACE:${Foo_INCLUDE_DIRS};${Bar_INCLUDE_DIRS}>" + ) + +The referenced variables may contain the absolute paths to libraries +and include directories **as found on the machine the package was made on**. +This would create a package with hard-coded paths to dependencies not +suitable for relocation. + +Ideally such dependencies should be used through their own +:ref:`IMPORTED targets <Imported Targets>` that have their own +:prop_tgt:`IMPORTED_LOCATION` and usage requirement properties +such as :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` populated +appropriately. Those imported targets may then be used with +the :command:`target_link_libraries` command for ``MathFunctions``: + +.. code-block:: cmake + + target_link_libraries(MathFunctions INTERFACE Foo::Foo Bar::Bar) + +With this approach the package references its external dependencies +only through the names of :ref:`IMPORTED targets <Imported Targets>`. +When a consumer uses the installed package, the consumer will run the +appropriate :command:`find_package` commands (via the ``find_dependency`` +macro described above) to find the dependencies and populate the +imported targets with appropriate paths on their own machine. + +Using the Package Configuration File +==================================== + +Now we're ready to create a project to use the installed ``MathFunctions`` +library. In this section we will be using source code from +``Help\guide\importing-exporting\Downstream``. In this directory, there is a +source file called ``main.cc`` that uses the ``MathFunctions`` library to +calculate the square root of a given number and then prints the results: + +.. literalinclude:: Downstream/main.cc + :language: c++ + +As before, we'll start with the :command:`cmake_minimum_required` and +:command:`project` commands in the ``CMakeLists.txt`` file. For this project, +we'll also specify the C++ standard. + +.. literalinclude:: Downstream/CMakeLists.txt + :language: cmake + :end-before: # find MathFunctions + +We can use the :command:`find_package` command: + +.. literalinclude:: Downstream/CMakeLists.txt + :language: cmake + :start-after: # find MathFunctions + :end-before: # create executable + +Create an exectuable: + +.. literalinclude:: Downstream/CMakeLists.txt + :language: cmake + :start-after: # create executable + :end-before: # use MathFunctions library + +And link to the ``MathFunctions`` library: + +.. literalinclude:: Downstream/CMakeLists.txt + :language: cmake + :start-after: # use MathFunctions library + +That's it! Now let's try to build the ``Downstream`` project. + +.. code-block:: console + + mkdir Downstream_build + cd Downstream_build + cmake ../Downstream + cmake --build . + +A warning may have appeared during CMake configuration: + +.. code-block:: console + + CMake Warning at CMakeLists.txt:4 (find_package): + By not providing "FindMathFunctions.cmake" in CMAKE_MODULE_PATH this + project has asked CMake to find a package configuration file provided by + "MathFunctions", but CMake did not find one. + + Could not find a package configuration file provided by "MathFunctions" + with any of the following names: + + MathFunctionsConfig.cmake + mathfunctions-config.cmake + + Add the installation prefix of "MathFunctions" to CMAKE_PREFIX_PATH or set + "MathFunctions_DIR" to a directory containing one of the above files. If + "MathFunctions" provides a separate development package or SDK, be sure it + has been installed. + +Set the ``CMAKE_PREFIX_PATH`` to where MathFunctions was installed previously +and try again. Ensure that the newly created executable runs as expected. + +Adding Components +================= + +Let's edit the ``MathFunctions`` project to use components. The source code for +this section can be found in +``Help\guide\importing-exporting\MathFunctionsComponents``. The CMakeLists file +for this project adds two subdirectories: ``Addition`` and ``SquareRoot``. + +.. literalinclude:: MathFunctionsComponents/CMakeLists.txt + :language: cmake + :end-before: # include CMakePackageConfigHelpers macro + +Generate and install the package configuration and package version files: + +.. literalinclude:: MathFunctionsComponents/CMakeLists.txt + :language: cmake + :start-after: # include CMakePackageConfigHelpers macro + +If ``COMPONENTS`` are specified when the downstream uses +:command:`find_package`, they are listed in the +``<PackageName>_FIND_COMPONENTS`` variable. We can use this variable to verify +that all necessary component targets are included in ``Config.cmake.in``. At +the same time, this function will act as a custom ``check_required_components`` +macro to ensure that the downstream only attempts to use supported components. + +.. literalinclude:: MathFunctionsComponents/Config.cmake.in + +Here, the ``MathFunctions_NOT_FOUND_MESSAGE`` is set to a diagnosis that the +package could not be found because an invalid component was specified. This +message variable can be set for any case where the ``_FOUND`` variable is set +to ``False``, and will be displayed to the user. + +The ``Addition`` and ``SquareRoot`` directories are similar. Let's look at one +of the CMakeLists files: + +.. literalinclude:: MathFunctionsComponents/SquareRoot/CMakeLists.txt + :language: cmake + +Now we can build the project as described in earlier sections. To test using +this package, we can use the project in +``Help\guide\importing-exporting\DownstreamComponents``. There's two +differences from the previous ``Downstream`` project. First, we need to find +the package components. Change the ``find_package`` line from: + +.. literalinclude:: Downstream/CMakeLists.txt + :language: cmake + :start-after: # find MathFunctions + :end-before: # create executable + +To: + +.. literalinclude:: DownstreamComponents/CMakeLists.txt + :language: cmake + :start-after: # find MathFunctions + :end-before: # create executable + +and the ``target_link_libraries`` line from: + +.. literalinclude:: Downstream/CMakeLists.txt + :language: cmake + :start-after: # use MathFunctions library + +To: + +.. literalinclude:: DownstreamComponents/CMakeLists.txt + :language: cmake + :start-after: # use MathFunctions library + :end-before: # Workaround for GCC on AIX to avoid -isystem + +In ``main.cc``, replace ``#include MathFunctions.h`` with: + +.. literalinclude:: DownstreamComponents/main.cc + :language: c + :start-after: #include <string> + :end-before: int main + +Finally, use the ``Addition`` library: + +.. literalinclude:: DownstreamComponents/main.cc + :language: c + :start-after: // calculate sum + :end-before: return 0; + +Build the ``Downstream`` project and confirm that it can find and use the +package components. diff --git a/Help/guide/tutorial/Complete/CMakeLists.txt b/Help/guide/tutorial/Complete/CMakeLists.txt new file mode 100644 index 0000000..4d8a3ad --- /dev/null +++ b/Help/guide/tutorial/Complete/CMakeLists.txt @@ -0,0 +1,124 @@ +cmake_minimum_required(VERSION 3.15) + +# set the project name and version +project(Tutorial VERSION 1.0) + +set(CMAKE_DEBUG_POSTFIX d) + +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) +set_target_properties(Tutorial PROPERTIES DEBUG_POSTFIX ${CMAKE_DEBUG_POSTFIX}) + +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 0000000..73efdb1 --- /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 0000000..17cbabd --- /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 0000000..c62d00b --- /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 0000000..a47d5e0 --- /dev/null +++ b/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt @@ -0,0 +1,67 @@ +# 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 PRIVATE 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 +set(installable_libs MathFunctions tutorial_compiler_flags) +if(TARGET SqrtLibrary) + list(APPEND installable_libs SqrtLibrary) +endif() +install(TARGETS ${installable_libs} + 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 0000000..ee58556 --- /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 0000000..0145300 --- /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 0000000..3fb547b --- /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 0000000..8153f18 --- /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 0000000..e1c42ef --- /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/MultiCPackConfig.cmake b/Help/guide/tutorial/Complete/MultiCPackConfig.cmake new file mode 100644 index 0000000..c2583df --- /dev/null +++ b/Help/guide/tutorial/Complete/MultiCPackConfig.cmake @@ -0,0 +1,6 @@ +include("release/CPackConfig.cmake") + +set(CPACK_INSTALL_CMAKE_PROJECTS + "debug;Tutorial;ALL;/" + "release;Tutorial;ALL;/" + ) diff --git a/Help/guide/tutorial/Complete/TutorialConfig.h.in b/Help/guide/tutorial/Complete/TutorialConfig.h.in new file mode 100644 index 0000000..7e4d7fa --- /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 0000000..a4f44d5 --- /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 <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/Step1/tutorial.cxx b/Help/guide/tutorial/Step1/tutorial.cxx new file mode 100644 index 0000000..08323bf --- /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 0000000..34ae70c --- /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 0000000..73efdb1 --- /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 0000000..c62d00b --- /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 0000000..0bfe20c --- /dev/null +++ b/Help/guide/tutorial/Step10/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) + + # 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 +set(installable_libs MathFunctions) +if(TARGET SqrtLibrary) + list(APPEND installable_libs SqrtLibrary) +endif() +install(TARGETS ${installable_libs} 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 0000000..ee58556 --- /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 0000000..0145300 --- /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 0000000..3fb547b --- /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 0000000..8153f18 --- /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 0000000..e1c42ef --- /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 0000000..7e4d7fa --- /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 0000000..37a0333 --- /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 0000000..4763951 --- /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 0000000..73efdb1 --- /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 0000000..c62d00b --- /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 0000000..0d287ca --- /dev/null +++ b/Help/guide/tutorial/Step11/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 ${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 PRIVATE 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 +set(installable_libs MathFunctions tutorial_compiler_flags) +if(TARGET SqrtLibrary) + list(APPEND installable_libs SqrtLibrary) +endif() +install(TARGETS ${installable_libs} 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 0000000..ee58556 --- /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 0000000..0145300 --- /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 0000000..3fb547b --- /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 0000000..8153f18 --- /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 0000000..e1c42ef --- /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 0000000..7e4d7fa --- /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 0000000..a4f44d5 --- /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/Step12/CMakeLists.txt b/Help/guide/tutorial/Step12/CMakeLists.txt new file mode 100644 index 0000000..1b0c826 --- /dev/null +++ b/Help/guide/tutorial/Step12/CMakeLists.txt @@ -0,0 +1,121 @@ +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 + ${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfigVersion.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/Step12/CTestConfig.cmake b/Help/guide/tutorial/Step12/CTestConfig.cmake new file mode 100644 index 0000000..73efdb1 --- /dev/null +++ b/Help/guide/tutorial/Step12/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/Step12/Config.cmake.in b/Help/guide/tutorial/Step12/Config.cmake.in new file mode 100644 index 0000000..17cbabd --- /dev/null +++ b/Help/guide/tutorial/Step12/Config.cmake.in @@ -0,0 +1,4 @@ + +@PACKAGE_INIT@ + +include ( "${CMAKE_CURRENT_LIST_DIR}/MathFunctionsTargets.cmake" ) diff --git a/Help/guide/tutorial/Step12/License.txt b/Help/guide/tutorial/Step12/License.txt new file mode 100644 index 0000000..c62d00b --- /dev/null +++ b/Help/guide/tutorial/Step12/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/Step12/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step12/MathFunctions/CMakeLists.txt new file mode 100644 index 0000000..ea3861c --- /dev/null +++ b/Help/guide/tutorial/Step12/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 PRIVATE 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 +set(installable_libs MathFunctions tutorial_compiler_flags) +if(TARGET SqrtLibrary) + list(APPEND installable_libs SqrtLibrary) +endif() +install(TARGETS ${installable_libs} + DESTINATION lib + EXPORT MathFunctionsTargets) +install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Step12/MathFunctions/MakeTable.cxx b/Help/guide/tutorial/Step12/MathFunctions/MakeTable.cxx new file mode 100644 index 0000000..ee58556 --- /dev/null +++ b/Help/guide/tutorial/Step12/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/Step12/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step12/MathFunctions/MathFunctions.cxx new file mode 100644 index 0000000..0145300 --- /dev/null +++ b/Help/guide/tutorial/Step12/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/Step12/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step12/MathFunctions/MathFunctions.h new file mode 100644 index 0000000..3fb547b --- /dev/null +++ b/Help/guide/tutorial/Step12/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/Step12/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step12/MathFunctions/mysqrt.cxx new file mode 100644 index 0000000..8153f18 --- /dev/null +++ b/Help/guide/tutorial/Step12/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/Step12/MathFunctions/mysqrt.h b/Help/guide/tutorial/Step12/MathFunctions/mysqrt.h new file mode 100644 index 0000000..e1c42ef --- /dev/null +++ b/Help/guide/tutorial/Step12/MathFunctions/mysqrt.h @@ -0,0 +1,6 @@ + +namespace mathfunctions { +namespace detail { +double mysqrt(double x); +} +} diff --git a/Help/guide/tutorial/Step12/TutorialConfig.h.in b/Help/guide/tutorial/Step12/TutorialConfig.h.in new file mode 100644 index 0000000..7e4d7fa --- /dev/null +++ b/Help/guide/tutorial/Step12/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/Step12/tutorial.cxx b/Help/guide/tutorial/Step12/tutorial.cxx new file mode 100644 index 0000000..a4f44d5 --- /dev/null +++ b/Help/guide/tutorial/Step12/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 0000000..7aa59e9 --- /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 0000000..cd36bcc --- /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 0000000..1e4d97a --- /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 0000000..7e4d7fa --- /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 0000000..53b0810 --- /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 0000000..1c12816 --- /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 0000000..8b443a6 --- /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 0000000..cd36bcc --- /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 0000000..abe767d --- /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 0000000..e23f521 --- /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 0000000..b3c6a4f --- /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 0000000..38e9b1f --- /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 0000000..0515852 --- /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 0000000..cd36bcc --- /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 0000000..abe767d --- /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 0000000..e23f521 --- /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 0000000..b3c6a4f --- /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 0000000..c3b375a --- /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 0000000..b12f27d --- /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/MathFunctions.h b/Help/guide/tutorial/Step5/MathFunctions/MathFunctions.h new file mode 100644 index 0000000..cd36bcc --- /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 0000000..abe767d --- /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 0000000..e23f521 --- /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 0000000..b3c6a4f --- /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 0000000..c3b375a --- /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 0000000..f64c6ac --- /dev/null +++ b/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt @@ -0,0 +1,32 @@ +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) +check_symbol_exists(log "math.h" HAVE_LOG) +check_symbol_exists(exp "math.h" HAVE_EXP) +if(NOT (HAVE_LOG AND HAVE_EXP)) + unset(HAVE_LOG CACHE) + unset(HAVE_EXP CACHE) + 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_link_libraries(MathFunctions PRIVATE m) + endif() +endif() + +# add compile definitions +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 0000000..ee58556 --- /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 0000000..cd36bcc --- /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 0000000..0637063 --- /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 0000000..e23f521 --- /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 0000000..b3c6a4f --- /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 0000000..c3b375a --- /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 0000000..c62d00b --- /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 0000000..9ede4b3 --- /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 0000000..ee58556 --- /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 0000000..cd36bcc --- /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 0000000..7d80ee9 --- /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 0000000..e23f521 --- /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 0000000..b3c6a4f --- /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 0000000..19b9913 --- /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 0000000..c62d00b --- /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 0000000..9ede4b3 --- /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 0000000..ee58556 --- /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 0000000..cd36bcc --- /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 0000000..7d80ee9 --- /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 0000000..e23f521 --- /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 0000000..b3c6a4f --- /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 0000000..d5f1cc8 --- /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 0000000..73efdb1 --- /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 0000000..c62d00b --- /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 0000000..50f0701 --- /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 0000000..ee58556 --- /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 0000000..0145300 --- /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 0000000..cd36bcc --- /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 0000000..7d80ee9 --- /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 0000000..e1c42ef --- /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 0000000..e23f521 --- /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 0000000..b3c6a4f --- /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 0000000..94753d5 --- /dev/null +++ b/Help/guide/tutorial/index.rst @@ -0,0 +1,946 @@ +CMake Tutorial +************** + +.. only:: html + + .. contents:: + +Introduction +============ + +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 use the :command:`project` command +to set the project name and 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 executable name and 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 :variable:`CMAKE_CXX_STANDARD` variable. For this +tutorial, set the :variable:`CMAKE_CXX_STANDARD` variable in the +``CMakeLists.txt`` file to 11 and :variable:`CMAKE_CXX_STANDARD_REQUIRED` to +True. Make sure to add the ``CMAKE_CXX_STANDARD`` declarations above the call +to ``add_executable``. + +.. literalinclude:: Step2/CMakeLists.txt + :language: cmake + :end-before: # configure a header file to pass some of the CMake settings + +Build and Test +-------------- + +Run the :manual:`cmake <cmake(1)>` executable or the +:manual:`cmake-gui <cmake-gui(1)>` 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 create a +build directory: + +.. code-block:: console + + mkdir Step1_build + +Next, navigate to the build directory and run CMake to configure the project +and generate a native build system: + +.. code-block:: console + + cd Step1_build + cmake ../Step1 + +Then call that build system to actually compile/link the project: + +.. code-block:: console + + cmake --build . + +Finally, try to use the newly built ``Tutorial`` with 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 :command:`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 ``mysqrt.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 :manual:`cmake-gui <cmake-gui(1)>` and +:manual:`ccmake <ccmake(1)>` +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 the :manual:`cmake <cmake(1)>` executable or the +:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it +with your chosen build tool. Then run the built Tutorial executable. + +Now let's update the value of ``USE_MYMATH``. The easiest way is to use the +:manual:`cmake-gui <cmake-gui(1)>` or :manual:`ccmake <ccmake(1)>` if you're +in the terminal. Or, alternatively, if you want to change the option from the +command-line, try: + +.. code-block:: console + + cmake ../Step2 -DUSE_MYMATH=OFF + +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: + + - :command:`target_compile_definitions` + - :command:`target_compile_options` + - :command:`target_include_directories` + - :command:`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 the :manual:`cmake <cmake(1)>` executable or the +:manual:`cmake-gui <cmake-gui(1)>` 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. + +Now run the :manual:`cmake <cmake(1)>` executable or the +:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it +with your chosen build tool. + +Then run the install step by using the ``install`` option of the +:manual:`cmake <cmake(1)>` command (introduced in 3.15, older versions of +CMake must use ``make install``) from the command line. For +multi-configuration tools, don't forget to use the ``--config`` argument to +specify the configuration. If using an IDE, simply build the ``INSTALL`` +target. This step will install the appropriate header files, libraries, and +executables. For example: + +.. code-block:: console + + cmake --install . + +The CMake variable :variable:`CMAKE_INSTALL_PREFIX` is used to determine the +root of where the files will be installed. If using the ``cmake --install`` +command, the installation prefix can be overridden via the ``--prefix`` +argument. For example: + +.. code-block:: console + + cmake --install . --prefix "/home/myuser/installdir" + +Navigate to the install directory and 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 :prop_test:`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 the +:manual:`ctest <ctest(1)>` executable: ``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 :module:`CheckSymbolExists` module in +``MathFunctions/CMakeLists.txt``. On some platforms, we will need to link to +the m library. If ``log`` and ``exp`` are not initially found, require the m +library and try again. + +.. literalinclude:: Step6/MathFunctions/CMakeLists.txt + :language: cmake + :start-after: # does this system provide the log and exp functions? + :end-before: # add compile definitions + +If available, use :command:`target_compile_definitions` to specify +``HAVE_LOG`` and ``HAVE_EXP`` as ``PRIVATE`` compile definitions. + +.. literalinclude:: Step6/MathFunctions/CMakeLists.txt + :language: cmake + :start-after: # add compile definitions + :end-before: # install rules + +If ``log`` and ``exp`` are available on the system, then we will use them to +compute the square root in the ``mysqrt`` function. Add the following code to +the ``mysqrt`` function in ``MathFunctions/mysqrt.cxx`` (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 + +We will also need to modify ``mysqrt.cxx`` to include ``cmath``. + +.. literalinclude:: Step6/MathFunctions/mysqrt.cxx + :language: c++ + :end-before: #include <iostream> + +Run the :manual:`cmake <cmake(1)>` executable or the +:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it +with your chosen build tool and run the Tutorial executable. + +Which function gives better results now, sqrt or mysqrt? + +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 + :language: cmake + :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 the :manual:`cmake <cmake(1)>` executable or the +:manual:`cmake-gui <cmake-gui(1)>` 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 +:module:`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 :module:`CPack module <CPack>` 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 the +:manual:`cpack <cpack(1)>` executable. 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 simple. 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 :module:`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 :module:`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 + +The :manual:`ctest <ctest(1)>` executable will read in this file when it runs. +To create a simple dashboard you can run the :manual:`cmake <cmake(1)>` +executable or the :manual:`cmake-gui <cmake-gui(1)>` 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. + +The :manual:`ctest <ctest(1)>` executable will build and test the project and +submit the results to Kitware's public dashboard: +https://my.cdash.org/index.php?project=CMakeTutorial. + +Mixing Static and Shared (Step 9) +================================= + +In this section we will show how the :variable:`BUILD_SHARED_LIBS` variable can +be used to control the default behavior of :command:`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 :variable:`BUILD_SHARED_LIBS` to the +top-level ``CMakeLists.txt``. We use the :command:`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 MathFunctions, 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 and installed 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 may 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 :prop_tgt:`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) +====================================== + +:manual:`Generator expressions <cmake-generator-expressions(7)>` are evaluated +during build system generation to produce information specific to each build +configuration. + +:manual:`Generator expressions <cmake-generator-expressions(7)>` are allowed in +the context of many target properties, such as :prop_tgt:`LINK_LIBRARIES`, +:prop_tgt:`INCLUDE_DIRECTORIES`, :prop_tgt:`COMPILE_DEFINITIONS` and others. +They may also be used when using commands to populate those properties, such as +:command:`target_link_libraries`, :command:`target_include_directories`, +:command:`target_compile_definitions` and others. + +:manual:`Generator expressions <cmake-generator-expressions(7)>` 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 +:manual:`generator expressions <cmake-generator-expressions(7)>` 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 +:manual:`generator expressions <cmake-generator-expressions(7)>` 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. Let's start by constructing an +``INTERFACE`` target and specifying the required C++ standard level of ``11`` +instead of using :variable:`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 :command:`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 :command:`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 :command:`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 +:command:`target_include_directories` call for MathFunctions to look like: + +.. literalinclude:: Step12/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 :command:`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:: Step12/Config.cmake.in + +Then, to properly configure and install that file, add the following to the +bottom of the top-level ``CMakeLists.txt``: + +.. literalinclude:: Step12/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:: Step12/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. + +Packaging Debug and Release (Step 12) +===================================== + +**Note:** This example is valid for single-configuration generators and will +not work for multi-configuration generators (e.g. Visual Studio). + +By default, CMake's model is that a build directory only contains a single +configuration, be it Debug, Release, MinSizeRel, or RelWithDebInfo. It is +possible, however, to setup CPack to bundle multiple build directories and +construct a package that contains multiple configurations of the same project. + +First, we want to ensure that the debug and release builds use different names +for the executables and libraries that will be installed. Let's use `d` as the +postfix for the debug executable and libraries. + +Set :variable:`CMAKE_DEBUG_POSTFIX` near the beginning of the top-level +``CMakeLists.txt`` file: + +.. literalinclude:: Complete/CMakeLists.txt + :language: cmake + :start-after: project(Tutorial VERSION 1.0) + :end-before: target_compile_features(tutorial_compiler_flags + +And the :prop_tgt:`DEBUG_POSTFIX` property on the tutorial executable: + +.. literalinclude:: Complete/CMakeLists.txt + :language: cmake + :start-after: # add the executable + :end-before: # add the binary tree to the search path for include files + +Let's also add version numbering to the MathFunctions library. In +``MathFunctions/CMakeLists.txt``, set the :prop_tgt:`VERSION` and +:prop_tgt:`SOVERSION` properties: + +.. literalinclude:: Complete/MathFunctions/CMakeLists.txt + :language: cmake + :start-after: # setup the version numbering + :end-before: # install rules + +From the ``Step12`` directory, create ``debug`` and ``release`` +subbdirectories. The layout will look like: + +.. code-block:: none + + - Step12 + - debug + - release + +Now we need to setup debug and release builds. We can use +:variable:`CMAKE_BUILD_TYPE` to set the configuration type: + +.. code-block:: console + + cd debug + cmake -DCMAKE_BUILD_TYPE=Debug .. + cmake --build . + cd ../release + cmake -DCMAKE_BUILD_TYPE=Release .. + cmake --build . + +Now that both the debug and release builds are complete, we can use a custom +configuration file to package both builds into a single release. In the +``Step12`` directory, create a file called ``MultiCPackConfig.cmake``. In this +file, first include the default configuration file that was created by the +:manual:`cmake <cmake(1)>` executable. + +Next, use the ``CPACK_INSTALL_CMAKE_PROJECTS`` variable to specify which +projects to install. In this case, we want to install both debug and release. + +.. literalinclude:: Complete/MultiCPackConfig.cmake + :language: cmake + +From the ``Step12`` directory, run :manual:`cpack <cpack(1)>` specifying our +custom configuration file with the ``config`` option: + +.. code-block:: console + + cpack --config MultiCPackConfig.cmake diff --git a/Help/guide/user-interaction/GUI-Add-Entry.png b/Help/guide/user-interaction/GUI-Add-Entry.png Binary files differnew file mode 100644 index 0000000..1e9be7e --- /dev/null +++ b/Help/guide/user-interaction/GUI-Add-Entry.png diff --git a/Help/guide/user-interaction/GUI-Choose-Generator.png b/Help/guide/user-interaction/GUI-Choose-Generator.png Binary files differnew file mode 100644 index 0000000..19ad2c0 --- /dev/null +++ b/Help/guide/user-interaction/GUI-Choose-Generator.png diff --git a/Help/guide/user-interaction/GUI-Configure-Dialog.png b/Help/guide/user-interaction/GUI-Configure-Dialog.png Binary files differnew file mode 100644 index 0000000..9839cac --- /dev/null +++ b/Help/guide/user-interaction/GUI-Configure-Dialog.png diff --git a/Help/guide/user-interaction/GUI-Source-Binary.png b/Help/guide/user-interaction/GUI-Source-Binary.png Binary files differnew file mode 100644 index 0000000..e338354 --- /dev/null +++ b/Help/guide/user-interaction/GUI-Source-Binary.png diff --git a/Help/guide/user-interaction/VS-Choose-Arch.png b/Help/guide/user-interaction/VS-Choose-Arch.png Binary files differnew file mode 100644 index 0000000..816b0f4 --- /dev/null +++ b/Help/guide/user-interaction/VS-Choose-Arch.png diff --git a/Help/guide/user-interaction/index.rst b/Help/guide/user-interaction/index.rst new file mode 100644 index 0000000..ba8196b --- /dev/null +++ b/Help/guide/user-interaction/index.rst @@ -0,0 +1,767 @@ +User Interaction Guide +********************** + +.. only:: html + + .. contents:: + +Introduction +============ + +Where a software package supplies a CMake-based buildsystem +with the source of their software, the consumer of the +software is required to run a CMake user interaction tool +in order to build it. + +Well-behaved CMake-based buildsystems do not create any +output in the source directory, so typically, the user +performs an out-of-source build and performs the build +there. First, CMake must be instructed to generate a +suitable buildsystem, then the user invokes a build tool +to process that generated buildsystem. The generated +buildsystem is specific to the machine used to generate +it and is not redistributable. Each consumer of a provided +source software package is required to use CMake to +generate a buildsystem specific to their system. + +Generated buildsystems should generally be treated as +read-only. The CMake files as a primary artifact should +completely specify the buildsystem and there should be no +reason to populate properties manually in an IDE for +example after generating the buildsystem. CMake will +periodically rewrite the generated buildsystem, so +modifications by users will be overwritten. + +The features and user interfaces described in this manual +are available for all CMake-based build systems by virtue +of providing CMake files. + +The CMake tooling may report errors to the user when +processing provided CMake files, such as reporting that +the compiler is not supported, or the compiler does not +support a required compile option, or a dependency can +not be found. These errors must be resolved by the user +by choosing a different compiler, +:guide:`installing dependencies <Using Dependencies Guide>`, +or instructing CMake where to find them, etc. + +Command Line cmake tool +----------------------- + +A simple but typical use of :manual:`cmake(1)` with a fresh +copy of software source code is to create a build directory +and invoke cmake there: + +.. code-block:: console + + $ cd some_software-1.4.2 + $ mkdir build + $ cd build + $ cmake .. -DCMAKE_INSTALL_PREFIX=/opt/the/prefix + $ cmake --build . + $ cmake --build . --target install + +It is recommended to build in a separate directory to the +source because that keeps the source directory pristine, +allows for building a single source with multiple +toolchains, and allows easy clearing of build artifacts by +simply deleting the build directory. + +The CMake tooling may report warnings which are intended +for the provider of the software, not intended for the +consumer of the software. Such warnings end with "This +warning is for project developers". Users may disable +such warnings by passing the ``-Wno-dev`` flag to +:manual:`cmake(1)`. + +cmake-gui tool +-------------- + +Users more accustomed to GUI interfaces may use the +:manual:`cmake-gui(1)` tool to invoke CMake and generate +a buildsystem. + +The source and binary directories must first be +populated. It is always advised to use different +directories for the source and the build. + +.. image:: GUI-Source-Binary.png + :alt: Choosing source and binary directories + +Generating a Buildsystem +======================== + +There are several user interface tools which may be used +to generate a buildsystem from CMake files. The +:manual:`ccmake(1)` and :manual:`cmake-gui(1)` tools guide +the user through setting the various necessary options. +The :manual:`cmake(1)` tool can be invoked to specify +options on the command line. This manual describes options +which may be set using any of the user interface tools, +though the mode of setting an option is different for each +tool. + +Command line environment +------------------------ + +When invoking :manual:`cmake(1)` with a command line +buildsystem such as ``Makefiles`` or ``Ninja``, it is +necessary to use the correct build environment to +ensure that build tools are available. CMake must be +able to find the appropriate +:variable:`build tool <CMAKE_MAKE_PROGRAM>`, +compiler, linker and other tools as needed. + +On Linux systems, the appropriate tools are often +provided in system-wide locations and may be readily +installed through the system package manager. Other +toolchains provided by the user or installed in +non-default locations can also be used. + +When cross-compiling, some platforms may require +environment variables to be set or may provide +scripts to set the environment. + +Visual Studio ships multiple command prompts and +``vcvarsall.bat`` scripts for setting up the +correct environments for command line buildsystems. While +not strictly necessary to use a corresponding +command line environment when using a Visual Studio +generator, doing so has no disadvantages. + +When using Xcode, there can be more than one Xcode +version installed. Which one to use can be selected +in a number of different ways, but the most common +methods are: + +* Setting the default version in the preferences + of the Xcode IDE. +* Setting the default version via the ``xcode-select`` + command line tool. +* Overriding the default version by setting the + ``DEVELOPER_DIR`` environment variable when running + CMake and the build tool. + +For convenience, :manual:`cmake-gui(1)` provides an +environment variable editor. + +Command line ``-G`` option +-------------------------- + +CMake chooses a generator by default based on the +platform. Usually, the default generator is sufficient +to allow the user to proceed to build the software. + +The user may override the default generator with +the ``-G`` option: + +.. code-block:: console + + $ cmake .. -G Ninja + +The output of ``cmake --help`` includes a list of +:manual:`generators <cmake-generators(7)>` available +for the user to choose from. Note that generator +names are case sensitive. + +On Unix-like systems (including Mac OS X), the +:generator:`Unix Makefiles` generator is used by +default. A variant of that generator can also be used +on Windows in various environments, such as the +:generator:`NMake Makefiles` and +:generator:`MinGW Makefiles` generator. These generators +generate a ``Makefile`` variant which can be executed +with ``make``, ``gmake``, ``nmake`` or similar tools. +See the individual generator documentation for more +information on targeted environments and tools. + +The :generator:`Ninja` generator is available on all +major platforms. ``ninja`` is a build tool similar +in use-cases to ``make``, but with a focus on +performance and efficiency. + +On Windows, :manual:`cmake(1)` can be used to generate +solutions for the Visual Studio IDE. Visual Studio +versions may be specified by the product name of the +IDE, which includes a four-digit year. Aliases are +provided for other means by which Visual Studio +versions are sometimes referred to, such as two +digits which correspond to the product version of the +VisualC++ compiler, or a combination of the two: + +.. code-block:: console + + $ cmake .. -G "Visual Studio 2019" + $ cmake .. -G "Visual Studio 16" + $ cmake .. -G "Visual Studio 16 2019" + +Visual Studio generators can target different architectures. +One can specify the target architecture using the `-A` option: + +.. code-block:: console + + cmake .. -G "Visual Studio 2019" -A x64 + cmake .. -G "Visual Studio 16" -A ARM + cmake .. -G "Visual Studio 16 2019" -A ARM64 + +On Apple, the :generator:`Xcode` generator may be used to +generate project files for the Xcode IDE. + +Some IDEs such as KDevelop4, QtCreator and CLion have +native support for CMake-based buildsystems. Those IDEs +provide user interface for selecting an underlying +generator to use, typically a choice between a ``Makefile`` +or a ``Ninja`` based generator. + +Note that it is not possible to change the generator +with ``-G`` after the first invocation of CMake. To +change the generator, the build directory must be +deleted and the build must be started from scratch. + +When generating Visual Studio project and solutions +files several other options are available to use when +initially running :manual:`cmake(1)`. + +The Visual Studio toolset can be specified with the +``-T`` option: + +.. code-block:: console + + $ # Build with the clang-cl toolset + $ cmake.exe .. -G "Visual Studio 16 2019" -A x64 -T ClangCL + $ # Build targeting Windows XP + $ cmake.exe .. -G "Visual Studio 16 2019" -A x64 -T v120_xp + +Whereas the ``-A`` option specifies the _target_ +architecture, the ``-T`` option can be used to specify +details of the toolchain used. For example, `-Thost=x64` +can be given to select the 64-bit version of the host +tools. The following demonstrates how to use 64-bit +tools and also build for a 64-bit target architecture: + +.. code-block:: console + + $ cmake .. -G "Visual Studio 16 2019" -A x64 -Thost=x64 + +Choosing a generator in cmake-gui +--------------------------------- + +The "Configure" button triggers a new dialog to +select the CMake generator to use. + +.. image:: GUI-Configure-Dialog.png + :alt: Configuring a generator + +All generators available on the command line are also +available in :manual:`cmake-gui(1)`. + +.. image:: GUI-Choose-Generator.png + :alt: Choosing a generator + +When choosing a Visual Studio generator, further options +are available to set an architecture to generate for. + +.. image:: VS-Choose-Arch.png + :alt: Choosing an architecture for Visual Studio generators + +.. _`Setting Build Variables`: + +Setting Build Variables +======================= + +Software projects often require variables to be +set on the command line when invoking CMake. Some of +the most commonly used CMake variables are listed in +the table below: + +========================================== ============================================================ + Variable Meaning +========================================== ============================================================ + :variable:`CMAKE_PREFIX_PATH` Path to search for + :guide:`dependent packages <Using Dependencies Guide>` + :variable:`CMAKE_MODULE_PATH` Path to search for additional CMake modules + :variable:`CMAKE_BUILD_TYPE` Build configuration, such as + ``Debug`` or ``Release``, determining + debug/optimization flags. This is only + relevant for single-configuration buildsystems such + as ``Makefile`` and ``Ninja``. Multi-configuration + buildsystems such as those for Visual Studio and Xcode + ignore this setting. + :variable:`CMAKE_INSTALL_PREFIX` Location to install the + software to with the + ``install`` build target + :variable:`CMAKE_TOOLCHAIN_FILE` File containing cross-compiling + data such as + :manual:`toolchains and sysroots <cmake-toolchains(7)>`. + :variable:`BUILD_SHARED_LIBS` Whether to build shared + instead of static libraries + for :command:`add_library` + commands used without a type + :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` Generate a ``compile_commands.json`` + file for use with clang-based tools +========================================== ============================================================ + +Other project-specific variables may be available +to control builds, such as enabling or disabling +components of the project. + +There is no convention provided by CMake for how +such variables are named between different +provided buildsystems, except that variables with +the prefix ``CMAKE_`` usually refer to options +provided by CMake itself and should not be used +in third-party options, which should use +their own prefix instead. The +:manual:`cmake-gui(1)` tool can display options +in groups defined by their prefix, so it makes +sense for third parties to ensure that they use a +self-consistent prefix. + +Setting variables on the command line +------------------------------------- + +CMake variables can be set on the command line either +when creating the initial build: + +.. code-block:: console + + $ mkdir build + $ cd build + $ cmake .. -G Ninja -DCMAKE_BUILD_TYPE=Debug + +or later on a subsequent invocation of +:manual:`cmake(1)`: + +.. code-block:: console + + $ cd build + $ cmake . -DCMAKE_BUILD_TYPE=Debug + +The ``-U`` flag may be used to unset variables +on the :manual:`cmake(1)` command line: + +.. code-block:: console + + $ cd build + $ cmake . -UMyPackage_DIR + +A CMake buildsystem which was initially created +on the command line can be modified using the +:manual:`cmake-gui(1)` and vice-versa. + +The :manual:`cmake(1)` tool allows specifying a +file to use to populate the initial cache using +the ``-C`` option. This can be useful to simplify +commands and scripts which repeatedly require the +same cache entries. + +Setting variables with cmake-gui +-------------------------------- + +Variables may be set in the cmake-gui using the "Add Entry" +button. This triggers a new dialog to set the value of +the variable. + +.. image:: GUI-Add-Entry.png + :alt: Editing a cache entry + +The main view of the :manual:`cmake-gui(1)` user interface +can be used to edit existing variables. + +The CMake Cache +--------------- + +When CMake is executed, it needs to find the locations of +compilers, tools and dependencies. It also needs to be +able to consistently re-generate a buildsystem to use the +same compile/link flags and paths to dependencies. Such +parameters are also required to be configurable by the +user because they are paths and options specific to the +users system. + +When it is first executed, CMake generates a +``CMakeCache.txt`` file in the build directory containing +key-value pairs for such artifacts. The cache file can be +viewed or edited by the user by running the +:manual:`cmake-gui(1)` or :manual:`ccmake(1)` tool. The +tools provide an interactive interface for re-configuring +the provided software and re-generating the buildsystem, +as is needed after editing cached values. Each cache +entry may have an associated short help text which is +displayed in the user interface tools. + +The cache entries may also have a type to signify how it +should be presented in the user interface. For example, +a cache entry of type ``BOOL`` can be edited by a +checkbox in a user interface, a ``STRING`` can be edited +in a text field, and a ``FILEPATH`` while similar to a +``STRING`` should also provide a way to locate filesystem +paths using a file dialog. An entry of type ``STRING`` +may provide a restricted list of allowed values which are +then provided in a drop-down menu in the +:manual:`cmake-gui(1)` user interface (see the +:prop_cache:`STRINGS` cache property). + +The CMake files shipped with a software package may also +define boolean toggle options using the :command:`option` +command. The command creates a cache entry which has a +help text and a default value. Such cache entries are +typically specific to the provided software and affect +the configuration of the build, such as whether tests +and examples are built, whether to build with exceptions +enabled etc. + +Presets +======= + +CMake understands a file, ``CMakePresets.json``, and its +user-specific counterpart, ``CMakeUserPresets.json``, for +saving presets for commonly-used configure settings. These +presets can set the build directory, generator, cache +variables, environment variables, and other command-line +options. All of these options can be overridden by the +user. The full details of the ``CMakePresets.json`` format +are listed in the :manual:`cmake-presets(7)` manual. + +Using presets on the command-line +--------------------------------- + +When using the :manual:`cmake(1)` command line tool, a +preset can be invoked by using the ``--preset`` option. If +``--preset`` is specified, the generator and build +directory are not required, but can be specified to +override them. For example, if you have the following +``CMakePresets.json`` file: + +.. code-block:: json + + { + "version": 1, + "configurePresets": [ + { + "name": "ninja-release", + "binaryDir": "${sourceDir}/build/${presetName}", + "generator": "Ninja", + "cacheVariables": { + "CMAKE_BUILD_TYPE": "Release" + } + } + ] + } + +and you run the following: + +.. code-block:: console + + cmake -S /path/to/source --preset=ninja-release + +This will generate a build directory in +``/path/to/source/build/ninja-release`` with the +:generator:`Ninja` generator, and with +:variable:`CMAKE_BUILD_TYPE` set to ``Release``. + +If you want to see the list of available presets, you can +run: + +.. code-block:: console + + cmake -S /path/to/source --list-presets + +This will list the presets available in +``/path/to/source/CMakePresets.json`` and +``/path/to/source/CMakeUsersPresets.json`` without +generating a build tree. + +Using presets in cmake-gui +-------------------------- + +If a project has presets available, either through +``CMakePresets.json`` or ``CMakeUserPresets.json``, the +list of presets will appear in a drop-down menu in +:manual:`cmake-gui(1)` between the source directory and +the binary directory. Choosing a preset sets the binary +directory, generator, environment variables, and cache +variables, but all of these options can be overridden after +a preset is selected. + +Invoking the Buildsystem +======================== + +After generating the buildsystem, the software can be +built by invoking the particular build tool. In the +case of the IDE generators, this can involve loading +the generated project file into the IDE to invoke the +build. + +CMake is aware of the specific build tool needed to invoke +a build so in general, to build a buildsystem or project +from the command line after generating, the following +command may be invoked in the build directory: + +.. code-block:: console + + $ cmake --build . + +The ``--build`` flag enables a particular mode of +operation for the :manual:`cmake(1)` tool. It invokes +the :variable:`CMAKE_MAKE_PROGRAM` command associated +with the :manual:`generator <cmake-generators(7)>`, or +the build tool configured by the user. + +The ``--build`` mode also accepts the parameter +``--target`` to specify a particular target to build, +for example a particular library, executable or +custom target, or a particular special target like +``install``: + +.. code-block:: console + + $ cmake --build . --target myexe + +The ``--build`` mode also accepts a ``--config`` parameter +in the case of multi-config generators to specify which +particular configuration to build: + +.. code-block:: console + + $ cmake --build . --target myexe --config Release + +The ``--config`` option has no effect if the generator +generates a buildsystem specific to a configuration which +is chosen when invoking cmake with the +:variable:`CMAKE_BUILD_TYPE` variable. + +Some buildsystems omit details of command lines invoked +during the build. The ``--verbose`` flag can be used to +cause those command lines to be shown: + +.. code-block:: console + + $ cmake --build . --target myexe --verbose + +The ``--build`` mode can also pass particular command +line options to the underlying build tool by listing +them after ``--``. This can be useful to specify +options to the build tool, such as to continue the +build after a failed job, where CMake does not +provide a high-level user interface. + +For all generators, it is possible to run the underlying +build tool after invoking CMake. For example, ``make`` +may be executed after generating with the +:generator:`Unix Makefiles` generator to invoke the build, +or ``ninja`` after generating with the :generator:`Ninja` +generator etc. The IDE buildsystems usually provide +command line tooling for building a project which can +also be invoked. + +Selecting a Target +------------------ + +Each executable and library described in the CMake files +is a build target, and the buildsystem may describe +custom targets, either for internal use, or for user +consumption, for example to create documentation. + +CMake provides some built-in targets for all buildsystems +providing CMake files. + +``all`` + The default target used by ``Makefile`` and ``Ninja`` + generators. Builds all targets in the buildsystem, + except those which are excluded by their + :prop_tgt:`EXCLUDE_FROM_ALL` target property or + :prop_dir:`EXCLUDE_FROM_ALL` directory property. The + name ``ALL_BUILD`` is used for this purpose for the + Xcode and Visual Studio generators. +``help`` + Lists the targets available for build. This target is + available when using the :generator:`Unix Makefiles` or + :generator:`Ninja` generator, and the exact output is + tool-specific. +``clean`` + Delete built object files and other output files. The + ``Makefile`` based generators create a ``clean`` target + per directory, so that an individual directory can be + cleaned. The ``Ninja`` tool provides its own granular + ``-t clean`` system. +``test`` + Runs tests. This target is only automatically available + if the CMake files provide CTest-based tests. See also + `Running Tests`_. +``install`` + Installs the software. This target is only automatically + available if the software defines install rules with the + :command:`install` command. See also + `Software Installation`_. +``package`` + Creates a binary package. This target is only + automatically available if the CMake files provide + CPack-based packages. +``package_source`` + Creates a source package. This target is only + automatically available if the CMake files provide + CPack-based packages. + +For ``Makefile`` based systems, ``/fast`` variants of binary +build targets are provided. The ``/fast`` variants are used +to build the specified target without regard for its +dependencies. The dependencies are not checked and +are not rebuilt if out of date. The :generator:`Ninja` +generator is sufficiently fast at dependency checking that +such targets are not provided for that generator. + +``Makefile`` based systems also provide build-targets to +preprocess, assemble and compile individual files in a +particular directory. + +.. code-block:: console + + $ make foo.cpp.i + $ make foo.cpp.s + $ make foo.cpp.o + +The file extension is built into the name of the target +because another file with the same name but a different +extension may exist. However, build-targets without the +file extension are also provided. + +.. code-block:: console + + $ make foo.i + $ make foo.s + $ make foo.o + +In buildsystems which contain ``foo.c`` and ``foo.cpp``, +building the ``foo.i`` target will preprocess both files. + +Specifying a Build Program +-------------------------- + +The program invoked by the ``--build`` mode is determined +by the :variable:`CMAKE_MAKE_PROGRAM` variable. For most +generators, the particular program does not need to be +configured. + +===================== =========================== =========================== + Generator Default make program Alternatives +===================== =========================== =========================== + XCode ``xcodebuild`` + Unix Makefiles ``make`` + NMake Makefiles ``nmake`` ``jom`` + NMake Makefiles JOM ``jom`` ``nmake`` + MinGW Makefiles ``mingw32-make`` + MSYS Makefiles ``make`` + Ninja ``ninja`` + Visual Studio ``msbuild`` + Watcom WMake ``wmake`` +===================== =========================== =========================== + +The ``jom`` tool is capable of reading makefiles of the +``NMake`` flavor and building in parallel, while the +``nmake`` tool always builds serially. After generating +with the :generator:`NMake Makefiles` generator a user +can run ``jom`` instead of ``nmake``. The ``--build`` +mode would also use ``jom`` if the +:variable:`CMAKE_MAKE_PROGRAM` was set to ``jom`` while +using the :generator:`NMake Makefiles` generator, and +as a convenience, the :generator:`NMake Makefiles JOM` +generator is provided to find ``jom`` in the normal way +and use it as the :variable:`CMAKE_MAKE_PROGRAM`. For +completeness, ``nmake`` is an alternative tool which +can process the output of the +:generator:`NMake Makefiles JOM` generator, but doing +so would be a pessimisation. + +Software Installation +===================== + +The :variable:`CMAKE_INSTALL_PREFIX` variable can be +set in the CMake cache to specify where to install the +provided software. If the provided software has install +rules, specified using the :command:`install` command, +they will install artifacts into that prefix. On Windows, +the default installation location corresponds to the +``ProgramFiles`` system directory which may be +architecture specific. On Unix hosts, ``/usr/local`` is +the default installation location. + +The :variable:`CMAKE_INSTALL_PREFIX` variable always +refers to the installation prefix on the target +filesystem. + +In cross-compiling or packaging scenarios where the +sysroot is read-only or where the sysroot should otherwise +remain pristine, the :variable:`CMAKE_STAGING_PREFIX` +variable can be set to a location to actually install +the files. + +The commands: + +.. code-block:: console + + $ cmake .. -DCMAKE_INSTALL_PREFIX=/usr/local \ + -DCMAKE_SYSROOT=$HOME/root \ + -DCMAKE_STAGING_PREFIX=/tmp/package + $ cmake --build . + $ cmake --build . --target install + +result in files being installed to paths such +as ``/tmp/package/lib/libfoo.so`` on the host machine. +The ``/usr/local`` location on the host machine is +not affected. + +Some provided software may specify ``uninstall`` rules, +but CMake does not generate such rules by default itself. + +Running Tests +============= + +The :manual:`ctest(1)` tool is shipped with the CMake +distribution to execute provided tests and report +results. The ``test`` build-target is provided to run +all available tests, but the :manual:`ctest(1)` tool +allows granular control over which tests to run, how to +run them, and how to report results. Executing +:manual:`ctest(1)` in the build directory is equivalent +to running the ``test`` target: + +.. code-block:: console + + $ ctest + +A regular expression can be passed to run only tests +which match the expression. To run only tests with +``Qt`` in their name: + +.. code-block:: console + + $ ctest -R Qt + +Tests can be excluded by regular expression too. To +run only tests without ``Qt`` in their name: + +.. code-block:: console + + $ ctest -E Qt + +Tests can be run in parallel by passing ``-j`` arguments +to :manual:`ctest(1)`: + +.. code-block:: console + + $ ctest -R Qt -j8 + +The environment variable :envvar:`CTEST_PARALLEL_LEVEL` +can alternatively be set to avoid the need to pass +``-j``. + +By default :manual:`ctest(1)` does not print the output +from the tests. The command line argument ``-V`` (or +``--verbose``) enables verbose mode to print the +output from all tests. +The ``--output-on-failure`` option prints the test +output for failing tests only. The environment variable +:envvar:`CTEST_OUTPUT_ON_FAILURE` +can be set to ``1`` as an alternative to passing the +``--output-on-failure`` option to :manual:`ctest(1)`. diff --git a/Help/guide/using-dependencies/index.rst b/Help/guide/using-dependencies/index.rst new file mode 100644 index 0000000..f4d7845 --- /dev/null +++ b/Help/guide/using-dependencies/index.rst @@ -0,0 +1,200 @@ +Using Dependencies Guide +************************ + +.. only:: html + + .. contents:: + +Introduction +============ + +For developers wishing to use CMake to consume a third +party binary package, there are multiple possibilities +regarding how to optimally do so, depending on how +CMake-aware the third-party library is. + +CMake files provided with a software package contain +instructions for finding each build dependency. Some +build dependencies are optional in that the build may +succeed with a different feature set if the dependency +is missing, and some dependencies are required. CMake +searches well-known locations for each dependency, and +the provided software may supply additional hints or +locations to CMake to find each dependency. + +If a required dependency is not found by +:manual:`cmake(1)`, the cache is populated with an entry +which contains a ``NOTFOUND`` value. This value can be +replaced by specifying it on the command line, or in +the :manual:`ccmake(1)` or :manual:`cmake-gui(1)` tool. +See the :guide:`User Interaction Guide` for +more about setting cache entries. + +Libraries providing Config-file packages +======================================== + +The most convenient way for a third-party to provide library +binaries for use with CMake is to provide +:ref:`Config File Packages`. These packages are text files +shipped with the library which instruct CMake how to use the +library binaries and associated headers, helper tools and +CMake macros provided by the library. + +The config files can usually be found in a directory whose +name matches the pattern ``lib/cmake/<PackageName>``, though +they may be in other locations instead. The +``<PackageName>`` corresponds to use in CMake code with the +:command:`find_package` command such as +``find_package(PackageName REQUIRED)``. + +The ``lib/cmake/<PackageName>`` directory will contain a +file which is either named ``<PackageName>Config.cmake`` +or ``<PackageName>-config.cmake``. This is the entry point +to the package for CMake. A separate optional file named +``<PackageName>ConfigVersion.cmake`` may also exist in the +directory. This file is used by CMake to determine whether +the version of the third party package satisfies uses of the +:command:`find_package` command which specify version +constraints. It is optional to specify a version when using +:command:`find_package`, even if a ``ConfigVersion`` file is +present. + +If the ``Config.cmake`` file is found and the +optionally-specified version is satisfied, then the CMake +:command:`find_package` command considers the package to be +found and the entire library package is assumed to be +complete as designed. + +There may be additional files providing CMake macros or +:ref:`imported targets` for you to use. CMake does not +enforce any naming convention for these +files. They are related to the primary ``Config`` file by +use of the CMake :command:`include` command. + +:guide:`Invoking CMake <User Interaction Guide>` with the +intent of using a package of third party binaries requires +that cmake :command:`find_package` commands succeed in finding +the package. If the location of the package is in a directory +known to CMake, the :command:`find_package` call should +succeed. The directories known to cmake are platform-specific. +For example, packages installed on Linux with a standard +system package manager will be found in the ``/usr`` prefix +automatically. Packages installed in ``Program Files`` on +Windows will similarly be found automatically. + +Packages which are not found automatically are in locations +not predictable to CMake such as ``/opt/mylib`` or +``$HOME/dev/prefix``. This is a normal situation and CMake +provides several ways for users to specify where to find +such libraries. + +The :variable:`CMAKE_PREFIX_PATH` variable may be +:ref:`set when invoking CMake <Setting Build Variables>`. +It is treated as a list of paths to search for +:ref:`Config File Packages`. A package installed in +``/opt/somepackage`` will typically install config files +such as +``/opt/somepackage/lib/cmake/somePackage/SomePackageConfig.cmake``. +In that case, ``/opt/somepackage`` should be added to +:variable:`CMAKE_PREFIX_PATH`. + +The environment variable ``CMAKE_PREFIX_PATH`` may also be +populated with prefixes to search for packages. Like the +``PATH`` environment variable, this is a list and needs to use +the platform-specific environment variable list item separator +(``:`` on Unix and ``;`` on Windows). + +The :variable:`CMAKE_PREFIX_PATH` variable provides convenience +in cases where multiple prefixes need to be specified, or when +multiple different package binaries are available in the same +prefix. Paths to packages may also be specified by setting +variables matching ``<PackageName>_DIR``, such as +``SomePackage_DIR``. Note that this is not a prefix but should +be a full path to a directory containing a config-style package +file, such as ``/opt/somepackage/lib/cmake/SomePackage/`` in +the above example. + +Imported Targets from Packages +============================== + +A third-party package which provides config-file packages may +also provide :ref:`Imported targets`. These will be +specified in files containing configuration-specific file +paths relevant to the package, such as debug and release +versions of libraries. + +Often the third-party package documentation will point out the +names of imported targets available after a successful +``find_package`` for a library. Those imported target names +can be used with the :command:`target_link_libraries` command. + +A complete example which makes a simple use of a third party +library might look like: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.10) + project(MyExeProject VERSION 1.0.0) + + find_package(SomePackage REQUIRED) + add_executable(MyExe main.cpp) + target_link_libraries(MyExe PRIVATE SomePrefix::LibName) + +See :manual:`cmake-buildsystem(7)` for further information +about developing a CMake buildsystem. + +Libraries not Providing Config-file Packages +-------------------------------------------- + +Third-party libraries which do not provide config-file packages +can still be found with the :command:`find_package` command, if +a ``FindSomePackage.cmake`` file is available. + +These module-file packages are different to config-file packages +in that: + +#. They should not be provided by the third party, except + perhaps in the form of documentation +#. The availability of a ``Find<PackageName>.cmake`` file does + not indicate the availability of the binaries themselves. +#. CMake does not search the :variable:`CMAKE_PREFIX_PATH` for + ``Find<PackageName>.cmake`` files. Instead CMake searches + for such files in the :variable:`CMAKE_MODULE_PATH` + variable. It is common for users to set the + :variable:`CMAKE_MODULE_PATH` when running CMake, and it is + common for CMake projects to append to + :variable:`CMAKE_MODULE_PATH` to allow use of local + module-file packages. +#. CMake ships ``Find<PackageName>.cmake`` files for some + :manual:`third party packages <cmake-modules(7)>` + for convenience in cases where the third party does + not provide config-file packages directly. These files are + a maintenance burden for CMake, so new Find modules are + generally not added to CMake anymore. Third-parties should + provide config file packages instead of relying on a Find + module to be provided by CMake. + +Module-file packages may also provide :ref:`Imported targets`. +A complete example which finds such a package might look +like: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.10) + project(MyExeProject VERSION 1.0.0) + + find_package(PNG REQUIRED) + + # Add path to a FindSomePackage.cmake file + list(APPEND CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake") + find_package(SomePackage REQUIRED) + + add_executable(MyExe main.cpp) + target_link_libraries(MyExe PRIVATE + PNG::PNG + SomePrefix::LibName + ) + +The :variable:`<PackageName>_ROOT` variable is also +searched as a prefix for :command:`find_package` calls using +module-file packages such as ``FindSomePackage``. diff --git a/Help/include/COMPILE_DEFINITIONS_DISCLAIMER.txt b/Help/include/COMPILE_DEFINITIONS_DISCLAIMER.txt new file mode 100644 index 0000000..6797d0e --- /dev/null +++ b/Help/include/COMPILE_DEFINITIONS_DISCLAIMER.txt @@ -0,0 +1,18 @@ +Disclaimer: Most native build tools have poor support for escaping +certain values. CMake has work-arounds for many cases but some values +may just not be possible to pass correctly. If a value does not seem +to be escaped correctly, do not attempt to work-around the problem by +adding escape sequences to the value. Your work-around may break in a +future version of CMake that has improved escape support. Instead +consider defining the macro in a (configured) header file. Then +report the limitation. Known limitations include:: + + # - broken almost everywhere + ; - broken in VS IDE 7.0 and Borland Makefiles + , - broken in VS IDE + % - broken in some cases in NMake + & | - broken in some cases on MinGW + ^ < > \" - broken in most Make tools on Windows + +CMake does not reject these values outright because they do work in +some cases. Use with caution. diff --git a/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt b/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt new file mode 100644 index 0000000..a54d728 --- /dev/null +++ b/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt @@ -0,0 +1,18 @@ + +Note that it is not advisable to populate the ``INSTALL_INTERFACE`` of the +|INTERFACE_PROPERTY_LINK| of a target with absolute paths to the include +directories of dependencies. That would hard-code into installed packages +the include directory paths for dependencies +**as found on the machine the package was made on**. + +The ``INSTALL_INTERFACE`` of the |INTERFACE_PROPERTY_LINK| is only +suitable for specifying the required include directories for headers +provided with the target itself, not those provided by the transitive +dependencies listed in its :prop_tgt:`INTERFACE_LINK_LIBRARIES` target +property. Those dependencies should themselves be targets that specify +their own header locations in |INTERFACE_PROPERTY_LINK|. + +See the :ref:`Creating Relocatable Packages` section of the +:manual:`cmake-packages(7)` manual for discussion of additional care +that must be taken when specifying usage requirements while creating +packages for redistribution. diff --git a/Help/include/INTERFACE_LINK_LIBRARIES_WARNING.txt b/Help/include/INTERFACE_LINK_LIBRARIES_WARNING.txt new file mode 100644 index 0000000..46e84ac --- /dev/null +++ b/Help/include/INTERFACE_LINK_LIBRARIES_WARNING.txt @@ -0,0 +1,10 @@ + +Note that it is not advisable to populate the +|INTERFACE_PROPERTY_LINK| of a target with absolute paths to dependencies. +That would hard-code into installed packages the library file paths +for dependencies **as found on the machine the package was made on**. + +See the :ref:`Creating Relocatable Packages` section of the +:manual:`cmake-packages(7)` manual for discussion of additional care +that must be taken when specifying usage requirements while creating +packages for redistribution. diff --git a/Help/index.rst b/Help/index.rst new file mode 100644 index 0000000..fdbf847 --- /dev/null +++ b/Help/index.rst @@ -0,0 +1,107 @@ +.. title:: CMake Reference Documentation + +Introduction +############ + +CMake is a tool to manage building of source code. Originally, CMake was +designed as a generator for various dialects of ``Makefile``, today +CMake generates modern buildsystems such as ``Ninja`` as well as project +files for IDEs such as Visual Studio and Xcode. + +CMake is widely used for the C and C++ languages, but it may be used to +build source code of other languages too. + +People encountering CMake for the first time may have different initial +goals. To learn how to build a source code package downloaded from the +internet, start with the :guide:`User Interaction Guide`. +This will detail the steps needed to run the :manual:`cmake(1)` or +:manual:`cmake-gui(1)` executable and how to choose a generator, and +how to complete the build. + +The :guide:`Using Dependencies Guide` is aimed at developers +wishing to get started using a third-party library. + +For developers starting a project using CMake, the :guide:`CMake Tutorial` +is a suitable starting point. The :manual:`cmake-buildsystem(7)` +manual is aimed at developers expanding their knowledge of maintaining +a buildsystem and becoming familiar with the build targets that +can be represented in CMake. The :manual:`cmake-packages(7)` manual +explains how to create packages which can easily be consumed by +third-party CMake-based buildsystems. + +Command-Line Tools +################## + +.. toctree:: + :maxdepth: 1 + + /manual/cmake.1 + /manual/ctest.1 + /manual/cpack.1 + +Interactive Dialogs +################### + +.. toctree:: + :maxdepth: 1 + + /manual/cmake-gui.1 + /manual/ccmake.1 + +Reference Manuals +################# + +.. toctree:: + :maxdepth: 1 + + /manual/cmake-buildsystem.7 + /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-modules.7 + /manual/cmake-packages.7 + /manual/cmake-policies.7 + /manual/cmake-presets.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 + /guide/user-interaction/index + /guide/using-dependencies/index + /guide/importing-exporting/index + /guide/ide-integration/index + +.. only:: html or text + + Release Notes + ############# + + .. toctree:: + :maxdepth: 1 + + /release/index + +.. only:: html + + Index and Search + ################ + + * :ref:`genindex` + * :ref:`search` diff --git a/Help/manual/ID_RESERVE.txt b/Help/manual/ID_RESERVE.txt new file mode 100644 index 0000000..be2b163 --- /dev/null +++ b/Help/manual/ID_RESERVE.txt @@ -0,0 +1,7 @@ +.. note:: + + CMake reserves identifiers that: + + * begin with ``CMAKE_`` (upper-, lower-, or mixed-case), or + * begin with ``_CMAKE_`` (upper-, lower-, or mixed-case), or + * begin with ``_`` followed by the name of any :manual:`CMake Command <cmake-commands(7)>`. diff --git a/Help/manual/LINKS.txt b/Help/manual/LINKS.txt new file mode 100644 index 0000000..810fa0b --- /dev/null +++ b/Help/manual/LINKS.txt @@ -0,0 +1,17 @@ +The following resources are available to get help using CMake: + +Home Page + https://cmake.org + + The primary starting point for learning about CMake. + +Online Documentation and Community Resources + https://cmake.org/documentation + + Links to available documentation and community resources may be + found on this web page. + +Discourse Forum + https://discourse.cmake.org + + The Discourse Forum hosts discussion and questions about CMake. diff --git a/Help/manual/OPTIONS_BUILD.txt b/Help/manual/OPTIONS_BUILD.txt new file mode 100644 index 0000000..c4f83f7 --- /dev/null +++ b/Help/manual/OPTIONS_BUILD.txt @@ -0,0 +1,134 @@ +``-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 + 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 + project's default values. The given file should be a CMake script + 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 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 + 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. + + If the ``:<type>`` portion is given it must be one of the types + specified by the :command:`set` command documentation for its + ``CACHE`` signature. + If the ``:<type>`` portion is omitted the entry will be created + with no type if it does not exist with a type already. If a + command in the project sets the type to ``PATH`` or ``FILEPATH`` + then the ``<value>`` will be converted to an absolute path. + + This option may also be given as a single argument: + ``-D<var>:<type>=<value>`` or ``-D<var>=<value>``. + +``-U <globbing_expr>`` + 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 + desired. + + Use with care, you can make your ``CMakeCache.txt`` non-working. + +``-G <generator-name>`` + Specify a build system generator. + + CMake may support multiple native build systems on certain + platforms. A generator is responsible for generating a particular + 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. + + Some CMake generators support a toolset specification to tell + the native build system how to choose a compiler. See the + :variable:`CMAKE_GENERATOR_TOOLSET` variable for details. + +``-A <platform-name>`` + Specify platform name if supported by generator. + + Some CMake generators support a platform name to be given to the + native build system to choose a compiler or SDK. See the + :variable:`CMAKE_GENERATOR_PLATFORM` variable for details. + +``--toolchain <path-to-file>`` + Specify the cross compiling toolchain file, equivalant to setting + :variable:`CMAKE_TOOLCHAIN_FILE` variable. + +``--install-prefix <directory>`` + Specify the installation directory, used by the + :variable:`CMAKE_INSTALL_PREFIX` variable. Must be an absolute path. + +``-Wno-dev`` + Suppress developer warnings. + + Suppress warnings that are meant for the author of the + ``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`` + 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 + 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 + 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. + +``-Wno-deprecated`` + Suppress deprecated functionality warnings. + + Suppress warnings for usage of deprecated functionality, that are meant + 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. + +``-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. diff --git a/Help/manual/OPTIONS_HELP.txt b/Help/manual/OPTIONS_HELP.txt new file mode 100644 index 0000000..feeca7d --- /dev/null +++ b/Help/manual/OPTIONS_HELP.txt @@ -0,0 +1,136 @@ +.. |file| replace:: The help is printed to a named <f>ile if given. + +``--help,-help,-usage,-h,-H,/?`` + Print usage information and exit. + + Usage describes the basic command line interface and its options. + +``--version,-version,/V [<f>]`` + Show program name/version banner and exit. + + If a file is specified, the version is written into it. + |file| + +``--help-full [<f>]`` + Print all help manuals and exit. + + All manuals are printed in a human-readable text format. + |file| + +``--help-manual <man> [<f>]`` + Print one help manual and exit. + + The specified manual is printed in a human-readable text format. + |file| + +``--help-manual-list [<f>]`` + List help manuals available and exit. + + The list contains all manuals for which help may be obtained by + using the ``--help-manual`` option followed by a manual name. + |file| + +``--help-command <cmd> [<f>]`` + Print help for one command and exit. + + The :manual:`cmake-commands(7)` manual entry for ``<cmd>`` is + printed in a human-readable text format. + |file| + +``--help-command-list [<f>]`` + List commands with help available and exit. + + The list contains all commands for which help may be obtained by + using the ``--help-command`` option followed by a command name. + |file| + +``--help-commands [<f>]`` + Print cmake-commands manual and exit. + + The :manual:`cmake-commands(7)` manual is printed in a + human-readable text format. + |file| + +``--help-module <mod> [<f>]`` + Print help for one module and exit. + + The :manual:`cmake-modules(7)` manual entry for ``<mod>`` is printed + in a human-readable text format. + |file| + +``--help-module-list [<f>]`` + List modules with help available and exit. + + The list contains all modules for which help may be obtained by + using the ``--help-module`` option followed by a module name. + |file| + +``--help-modules [<f>]`` + Print cmake-modules manual and exit. + + The :manual:`cmake-modules(7)` manual is printed in a human-readable + text format. + |file| + +``--help-policy <cmp> [<f>]`` + Print help for one policy and exit. + + The :manual:`cmake-policies(7)` manual entry for ``<cmp>`` is + printed in a human-readable text format. + |file| + +``--help-policy-list [<f>]`` + List policies with help available and exit. + + The list contains all policies for which help may be obtained by + using the ``--help-policy`` option followed by a policy name. + |file| + +``--help-policies [<f>]`` + Print cmake-policies manual and exit. + + The :manual:`cmake-policies(7)` manual is printed in a + human-readable text format. + |file| + +``--help-property <prop> [<f>]`` + Print help for one property and exit. + + The :manual:`cmake-properties(7)` manual entries for ``<prop>`` are + printed in a human-readable text format. + |file| + +``--help-property-list [<f>]`` + List properties with help available and exit. + + The list contains all properties for which help may be obtained by + using the ``--help-property`` option followed by a property name. + |file| + +``--help-properties [<f>]`` + Print cmake-properties manual and exit. + + The :manual:`cmake-properties(7)` manual is printed in a + human-readable text format. + |file| + +``--help-variable <var> [<f>]`` + Print help for one variable and exit. + + The :manual:`cmake-variables(7)` manual entry for ``<var>`` is + printed in a human-readable text format. + |file| + +``--help-variable-list [<f>]`` + List variables with help available and exit. + + The list contains all variables for which help may be obtained by + using the ``--help-variable`` option followed by a variable name. + |file| + +``--help-variables [<f>]`` + Print cmake-variables manual and exit. + + The :manual:`cmake-variables(7)` manual is printed in a + human-readable text format. + |file| diff --git a/Help/manual/ccmake.1.rst b/Help/manual/ccmake.1.rst new file mode 100644 index 0000000..60d45a3 --- /dev/null +++ b/Help/manual/ccmake.1.rst @@ -0,0 +1,37 @@ +.. cmake-manual-description: CMake Curses Dialog Command-Line Reference + +ccmake(1) +********* + +Synopsis +======== + +.. parsed-literal:: + + ccmake [<options>] {<path-to-source> | <path-to-existing-build>} + +Description +=========== + +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``. +Users build a project by using CMake to generate a build system for a +native tool on their platform. + +Options +======= + +.. include:: OPTIONS_BUILD.txt + +.. include:: OPTIONS_HELP.txt + +See Also +======== + +.. include:: LINKS.txt diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst new file mode 100644 index 0000000..7008383 --- /dev/null +++ b/Help/manual/cmake-buildsystem.7.rst @@ -0,0 +1,1021 @@ +.. cmake-manual-description: CMake Buildsystem Reference + +cmake-buildsystem(7) +******************** + +.. only:: html + + .. contents:: + +Introduction +============ + +A CMake-based buildsystem is organized as a set of high-level logical +targets. Each target corresponds to an executable or library, or +is a custom target containing custom commands. Dependencies between the +targets are expressed in the buildsystem to determine the build order +and the rules for regeneration in response to change. + +Binary Targets +============== + +Executables and libraries are defined using the :command:`add_executable` +and :command:`add_library` commands. The resulting binary files have +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: + +.. code-block:: cmake + + add_library(archive archive.cpp zip.cpp lzma.cpp) + add_executable(zipapp zipapp.cpp) + target_link_libraries(zipapp archive) + +``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 +linked in. + +Binary Executables +------------------ + +The :command:`add_executable` command defines an executable target: + +.. code-block:: cmake + + add_executable(mytool mytool.cpp) + +Commands such as :command:`add_custom_command`, which generates rules to be +run at build time can transparently use an :prop_tgt:`EXECUTABLE <TYPE>` +target as a ``COMMAND`` executable. The buildsystem rules will ensure that +the executable is built before attempting to run the command. + +Binary Library Types +-------------------- + +.. _`Normal Libraries`: + +Normal Libraries +^^^^^^^^^^^^^^^^ + +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 + + add_library(archive SHARED archive.cpp zip.cpp lzma.cpp) + +.. code-block:: cmake + + add_library(archive STATIC archive.cpp zip.cpp lzma.cpp) + +The :variable:`BUILD_SHARED_LIBS` variable may be enabled to change the +behavior of :command:`add_library` to build shared libraries by default. + +In the context of the buildsystem definition as a whole, it is largely +irrelevant whether particular libraries are ``SHARED`` or ``STATIC`` -- +the commands, dependency specifications and other APIs work similarly +regardless of the library type. The ``MODULE`` library type is +dissimilar in that it is generally not linked to -- it is not used in +the right-hand-side of the :command:`target_link_libraries` command. +It is a type which is loaded as a plugin using runtime techniques. +If the library does not export any unmanaged symbols (e.g. Windows +resource DLL, C++/CLI DLL), it is required that the library not be a +``SHARED`` library because CMake expects ``SHARED`` libraries to export +at least one symbol. + +.. code-block:: cmake + + add_library(archive MODULE 7z.cpp) + +.. _`Apple Frameworks`: + +Apple Frameworks +"""""""""""""""" + +A ``SHARED`` library may be marked with the :prop_tgt:`FRAMEWORK` +target property to create an macOS or iOS Framework Bundle. +A library with the ``FRAMEWORK`` target property should also set the +:prop_tgt:`FRAMEWORK_VERSION` target property. This property is typically +set to the value of "A" by macOS conventions. +The ``MACOSX_FRAMEWORK_IDENTIFIER`` sets ``CFBundleIdentifier`` key +and it uniquely identifies the bundle. + +.. code-block:: cmake + + add_library(MyFramework SHARED MyFramework.cpp) + set_target_properties(MyFramework PROPERTIES + FRAMEWORK TRUE + FRAMEWORK_VERSION A # Version "A" is macOS convention + MACOSX_FRAMEWORK_IDENTIFIER org.cmake.MyFramework + ) + +.. _`Object Libraries`: + +Object Libraries +^^^^^^^^^^^^^^^^ + +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 by using the syntax +``$<TARGET_OBJECTS:name>``. This is a +:manual:`generator expression <cmake-generator-expressions(7)>` that can be +used to supply the ``OBJECT`` library content to other targets: + +.. code-block:: cmake + + add_library(archive OBJECT archive.cpp zip.cpp lzma.cpp) + + add_library(archiveExtras STATIC $<TARGET_OBJECTS:archive> extras.cpp) + + add_executable(test_exe $<TARGET_OBJECTS:archive> test.cpp) + +The link (or archiving) step of those other targets will use the object +files collection in addition to those from their own sources. + +Alternatively, object libraries may be linked into other targets: + +.. 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 +========================================== + +The :command:`target_include_directories`, :command:`target_compile_definitions` +and :command:`target_compile_options` commands specify the build specifications +and the usage requirements of binary targets. The commands populate the +:prop_tgt:`INCLUDE_DIRECTORIES`, :prop_tgt:`COMPILE_DEFINITIONS` and +:prop_tgt:`COMPILE_OPTIONS` target properties respectively, and/or the +:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`, :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` +and :prop_tgt:`INTERFACE_COMPILE_OPTIONS` target properties. + +Each of the commands has a ``PRIVATE``, ``PUBLIC`` and ``INTERFACE`` mode. The +``PRIVATE`` mode populates only the non-``INTERFACE_`` variant of the target +property and the ``INTERFACE`` mode populates only the ``INTERFACE_`` variants. +The ``PUBLIC`` mode populates both variants of the respective target property. +Each command may be invoked with multiple uses of each keyword: + +.. code-block:: cmake + + target_compile_definitions(archive + PRIVATE BUILDING_WITH_LZMA + INTERFACE USING_ARCHIVE_LIB + ) + +Note that usage requirements are not designed as a way to make downstreams +use particular :prop_tgt:`COMPILE_OPTIONS` or +:prop_tgt:`COMPILE_DEFINITIONS` etc for convenience only. The contents of +the properties must be **requirements**, not merely recommendations or +convenience. + +See the :ref:`Creating Relocatable Packages` section of the +:manual:`cmake-packages(7)` manual for discussion of additional care +that must be taken when specifying usage requirements while creating +packages for redistribution. + +Target Properties +----------------- + +The contents of the :prop_tgt:`INCLUDE_DIRECTORIES`, +:prop_tgt:`COMPILE_DEFINITIONS` and :prop_tgt:`COMPILE_OPTIONS` target +properties are used appropriately when compiling the source files of a +binary target. + +Entries in the :prop_tgt:`INCLUDE_DIRECTORIES` are added to the compile line +with ``-I`` or ``-isystem`` prefixes and in the order of appearance in the +property value. + +Entries in the :prop_tgt:`COMPILE_DEFINITIONS` are prefixed with ``-D`` or +``/D`` and added to the compile line in an unspecified order. The +:prop_tgt:`DEFINE_SYMBOL` target property is also added as a compile +definition as a special convenience case for ``SHARED`` and ``MODULE`` +library targets. + +Entries in the :prop_tgt:`COMPILE_OPTIONS` are escaped for the shell and added +in the order of appearance in the property value. Several compile options have +special separate handling, such as :prop_tgt:`POSITION_INDEPENDENT_CODE`. + +The contents of the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`, +:prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` and +:prop_tgt:`INTERFACE_COMPILE_OPTIONS` target properties are +*Usage Requirements* -- they specify content which consumers +must use to correctly compile and link with the target they appear on. +For any binary target, the contents of each ``INTERFACE_`` property on +each target specified in a :command:`target_link_libraries` command is +consumed: + +.. code-block:: cmake + + set(srcs archive.cpp zip.cpp) + if (LZMA_FOUND) + list(APPEND srcs lzma.cpp) + endif() + add_library(archive SHARED ${srcs}) + if (LZMA_FOUND) + # The archive library sources are compiled with -DBUILDING_WITH_LZMA + target_compile_definitions(archive PRIVATE BUILDING_WITH_LZMA) + endif() + target_compile_definitions(archive INTERFACE USING_ARCHIVE_LIB) + + add_executable(consumer) + # Link consumer to archive and consume its usage requirements. The consumer + # executable sources are compiled with -DUSING_ARCHIVE_LIB. + target_link_libraries(consumer archive) + +Because it is common to require that the source directory and corresponding +build directory are added to the :prop_tgt:`INCLUDE_DIRECTORIES`, the +:variable:`CMAKE_INCLUDE_CURRENT_DIR` variable can be enabled to conveniently +add the corresponding directories to the :prop_tgt:`INCLUDE_DIRECTORIES` of +all targets. The variable :variable:`CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE` +can be enabled to add the corresponding directories to the +:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of all targets. This makes use of +targets in multiple different directories convenient through use of the +:command:`target_link_libraries` command. + + +.. _`Target Usage Requirements`: + +Transitive Usage Requirements +----------------------------- + +The usage requirements of a target can transitively propagate to dependents. +The :command:`target_link_libraries` command has ``PRIVATE``, +``INTERFACE`` and ``PUBLIC`` keywords to control the propagation. + +.. code-block:: cmake + + add_library(archive archive.cpp) + target_compile_definitions(archive INTERFACE USING_ARCHIVE_LIB) + + add_library(serialization serialization.cpp) + target_compile_definitions(serialization INTERFACE USING_SERIALIZATION_LIB) + + add_library(archiveExtras extras.cpp) + target_link_libraries(archiveExtras PUBLIC archive) + target_link_libraries(archiveExtras PRIVATE serialization) + # archiveExtras is compiled with -DUSING_ARCHIVE_LIB + # and -DUSING_SERIALIZATION_LIB + + add_executable(consumer consumer.cpp) + # consumer is compiled with -DUSING_ARCHIVE_LIB + target_link_libraries(consumer archiveExtras) + +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 ``archiveExtras``, the usage +requirements of it are not propagated to ``consumer``. + +Generally, a dependency should be specified in a use of +:command:`target_link_libraries` with the ``PRIVATE`` keyword if it is used by +only the implementation of a library, and not in the header files. If a +dependency is additionally used in the header files of a library (e.g. for +class inheritance), then it should be specified as a ``PUBLIC`` dependency. +A dependency which is not used by the implementation of a library, but only by +its headers should be specified as an ``INTERFACE`` dependency. The +:command:`target_link_libraries` command may be invoked with multiple uses of +each keyword: + +.. code-block:: cmake + + target_link_libraries(archiveExtras + PUBLIC archive + PRIVATE serialization + ) + +Usage requirements are propagated by reading the ``INTERFACE_`` variants +of target properties from dependencies and appending the values to the +non-``INTERFACE_`` variants of the operand. For example, the +:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of dependencies is read and +appended to the :prop_tgt:`INCLUDE_DIRECTORIES` of the operand. In cases +where order is relevant and maintained, and the order resulting from the +:command:`target_link_libraries` calls does not allow correct compilation, +use of an appropriate command to set the property directly may update the +order. + +For example, if the linked libraries for a target must be specified +in the order ``lib1`` ``lib2`` ``lib3`` , but the include directories must +be specified in the order ``lib3`` ``lib1`` ``lib2``: + +.. code-block:: cmake + + target_link_libraries(myExe lib1 lib2 lib3) + target_include_directories(myExe + PRIVATE $<TARGET_PROPERTY:lib3,INTERFACE_INCLUDE_DIRECTORIES>) + +Note that care must be taken when specifying usage requirements for targets +which will be exported for installation using the :command:`install(EXPORT)` +command. See :ref:`Creating Packages` for more. + +.. _`Compatible Interface Properties`: + +Compatible Interface Properties +------------------------------- + +Some target properties are required to be compatible between a target and +the interface of each dependency. For example, the +:prop_tgt:`POSITION_INDEPENDENT_CODE` target property may specify a +boolean value of whether a target should be compiled as +position-independent-code, which has platform-specific consequences. +A target may also specify the usage requirement +:prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE` to communicate that +consumers must be compiled as position-independent-code. + +.. code-block:: cmake + + add_executable(exe1 exe1.cpp) + set_property(TARGET exe1 PROPERTY POSITION_INDEPENDENT_CODE ON) + + add_library(lib1 SHARED lib1.cpp) + set_property(TARGET lib1 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON) + + add_executable(exe2 exe2.cpp) + target_link_libraries(exe2 lib1) + +Here, both ``exe1`` and ``exe2`` will be compiled as position-independent-code. +``lib1`` will also be compiled as position-independent-code because that is the +default setting for ``SHARED`` libraries. If dependencies have conflicting, +non-compatible requirements :manual:`cmake(1)` issues a diagnostic: + +.. code-block:: cmake + + add_library(lib1 SHARED lib1.cpp) + set_property(TARGET lib1 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON) + + add_library(lib2 SHARED lib2.cpp) + set_property(TARGET lib2 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE OFF) + + add_executable(exe1 exe1.cpp) + target_link_libraries(exe1 lib1) + set_property(TARGET exe1 PROPERTY POSITION_INDEPENDENT_CODE OFF) + + add_executable(exe2 exe2.cpp) + target_link_libraries(exe2 lib1 lib2) + +The ``lib1`` requirement ``INTERFACE_POSITION_INDEPENDENT_CODE`` is not +"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. + +The ``lib1`` and ``lib2`` requirements are not "compatible". One of them +requires that consumers are built as position-independent-code, while +the other requires that consumers are not built as position-independent-code. +Because ``exe2`` links to both and they are in conflict, a CMake error message +is issued:: + + CMake Error: The INTERFACE_POSITION_INDEPENDENT_CODE property of "lib2" does + not agree with the value of POSITION_INDEPENDENT_CODE already determined + for "exe2". + +To be "compatible", the :prop_tgt:`POSITION_INDEPENDENT_CODE` property, +if set must be either the same, in a boolean sense, as the +:prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE` property of all transitively +specified dependencies on which that property is set. + +This property of "compatible interface requirement" may be extended to other +properties by specifying the property in the content of the +:prop_tgt:`COMPATIBLE_INTERFACE_BOOL` target property. Each specified property +must be compatible between the consuming target and the corresponding property +with an ``INTERFACE_`` prefix from each dependency: + +.. code-block:: cmake + + add_library(lib1Version2 SHARED lib1_v2.cpp) + set_property(TARGET lib1Version2 PROPERTY INTERFACE_CUSTOM_PROP ON) + set_property(TARGET lib1Version2 APPEND PROPERTY + COMPATIBLE_INTERFACE_BOOL CUSTOM_PROP + ) + + add_library(lib1Version3 SHARED lib1_v3.cpp) + set_property(TARGET lib1Version3 PROPERTY INTERFACE_CUSTOM_PROP OFF) + + add_executable(exe1 exe1.cpp) + target_link_libraries(exe1 lib1Version2) # CUSTOM_PROP will be ON + + add_executable(exe2 exe2.cpp) + target_link_libraries(exe2 lib1Version2 lib1Version3) # Diagnostic + +Non-boolean properties may also participate in "compatible interface" +computations. Properties specified in the +:prop_tgt:`COMPATIBLE_INTERFACE_STRING` +property must be either unspecified or compare to the same string among +all transitively specified dependencies. This can be useful to ensure +that multiple incompatible versions of a library are not linked together +through transitive requirements of a target: + +.. code-block:: cmake + + add_library(lib1Version2 SHARED lib1_v2.cpp) + set_property(TARGET lib1Version2 PROPERTY INTERFACE_LIB_VERSION 2) + set_property(TARGET lib1Version2 APPEND PROPERTY + COMPATIBLE_INTERFACE_STRING LIB_VERSION + ) + + add_library(lib1Version3 SHARED lib1_v3.cpp) + set_property(TARGET lib1Version3 PROPERTY INTERFACE_LIB_VERSION 3) + + add_executable(exe1 exe1.cpp) + target_link_libraries(exe1 lib1Version2) # LIB_VERSION will be "2" + + add_executable(exe2 exe2.cpp) + target_link_libraries(exe2 lib1Version2 lib1Version3) # Diagnostic + +The :prop_tgt:`COMPATIBLE_INTERFACE_NUMBER_MAX` target property specifies +that content will be evaluated numerically and the maximum number among all +specified will be calculated: + +.. code-block:: cmake + + add_library(lib1Version2 SHARED lib1_v2.cpp) + set_property(TARGET lib1Version2 PROPERTY INTERFACE_CONTAINER_SIZE_REQUIRED 200) + set_property(TARGET lib1Version2 APPEND PROPERTY + COMPATIBLE_INTERFACE_NUMBER_MAX CONTAINER_SIZE_REQUIRED + ) + + add_library(lib1Version3 SHARED lib1_v3.cpp) + set_property(TARGET lib1Version3 PROPERTY INTERFACE_CONTAINER_SIZE_REQUIRED 1000) + + add_executable(exe1 exe1.cpp) + # CONTAINER_SIZE_REQUIRED will be "200" + target_link_libraries(exe1 lib1Version2) + + add_executable(exe2 exe2.cpp) + # CONTAINER_SIZE_REQUIRED will be "1000" + target_link_libraries(exe2 lib1Version2 lib1Version3) + +Similarly, the :prop_tgt:`COMPATIBLE_INTERFACE_NUMBER_MIN` may be used to +calculate the numeric minimum value for a property from dependencies. + +Each calculated "compatible" property value may be read in the consumer at +generate-time using generator expressions. + +Note that for each dependee, the set of properties specified in each +compatible interface property must not intersect with the set specified in +any of the other properties. + +Property Origin Debugging +------------------------- + +Because build specifications can be determined by dependencies, the lack of +locality of code which creates a target and code which is responsible for +setting build specifications may make the code more difficult to reason about. +:manual:`cmake(1)` provides a debugging facility to print the origin of the +contents of properties which may be determined by dependencies. The properties +which can be debugged are listed in the +:variable:`CMAKE_DEBUG_TARGET_PROPERTIES` variable documentation: + +.. code-block:: cmake + + set(CMAKE_DEBUG_TARGET_PROPERTIES + INCLUDE_DIRECTORIES + COMPILE_DEFINITIONS + POSITION_INDEPENDENT_CODE + CONTAINER_SIZE_REQUIRED + LIB_VERSION + ) + add_executable(exe1 exe1.cpp) + +In the case of properties listed in :prop_tgt:`COMPATIBLE_INTERFACE_BOOL` or +:prop_tgt:`COMPATIBLE_INTERFACE_STRING`, the debug output shows which target +was responsible for setting the property, and which other dependencies also +defined the property. In the case of +:prop_tgt:`COMPATIBLE_INTERFACE_NUMBER_MAX` and +:prop_tgt:`COMPATIBLE_INTERFACE_NUMBER_MIN`, the debug output shows the +value of the property from each dependency, and whether the value determines +the new extreme. + +Build Specification with Generator Expressions +---------------------------------------------- + +Build specifications may use +:manual:`generator expressions <cmake-generator-expressions(7)>` containing +content which may be conditional or known only at generate-time. For example, +the calculated "compatible" value of a property may be read with the +``TARGET_PROPERTY`` expression: + +.. code-block:: cmake + + add_library(lib1Version2 SHARED lib1_v2.cpp) + set_property(TARGET lib1Version2 PROPERTY + INTERFACE_CONTAINER_SIZE_REQUIRED 200) + set_property(TARGET lib1Version2 APPEND PROPERTY + COMPATIBLE_INTERFACE_NUMBER_MAX CONTAINER_SIZE_REQUIRED + ) + + add_executable(exe1 exe1.cpp) + target_link_libraries(exe1 lib1Version2) + target_compile_definitions(exe1 PRIVATE + CONTAINER_SIZE=$<TARGET_PROPERTY:CONTAINER_SIZE_REQUIRED> + ) + +In this case, the ``exe1`` source files will be compiled with +``-DCONTAINER_SIZE=200``. + +Configuration determined build specifications may be conveniently set using +the ``CONFIG`` generator expression. + +.. code-block:: cmake + + target_compile_definitions(exe1 PRIVATE + $<$<CONFIG:Debug>:DEBUG_BUILD> + ) + +The ``CONFIG`` parameter is compared case-insensitively with the configuration +being built. In the presence of :prop_tgt:`IMPORTED` targets, the content of +:prop_tgt:`MAP_IMPORTED_CONFIG_DEBUG <MAP_IMPORTED_CONFIG_<CONFIG>>` is also +accounted for by this expression. + +Some buildsystems generated by :manual:`cmake(1)` have a predetermined +build-configuration set in the :variable:`CMAKE_BUILD_TYPE` variable. The +buildsystem for the IDEs such as Visual Studio and Xcode are generated +independent of the build-configuration, and the actual build configuration +is not known until build-time. Therefore, code such as + +.. code-block:: cmake + + string(TOLOWER ${CMAKE_BUILD_TYPE} _type) + if (_type STREQUAL debug) + target_compile_definitions(exe1 PRIVATE DEBUG_BUILD) + endif() + +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 +means that a usage requirement specification may be evaluated differently based +on the consumer: + +.. code-block:: cmake + + add_library(lib1 lib1.cpp) + target_compile_definitions(lib1 INTERFACE + $<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,EXECUTABLE>:LIB1_WITH_EXE> + $<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,SHARED_LIBRARY>:LIB1_WITH_SHARED_LIB> + $<$<TARGET_POLICY:CMP0041>:CONSUMER_CMP0041_NEW> + ) + + add_executable(exe1 exe1.cpp) + target_link_libraries(exe1 lib1) + + cmake_policy(SET CMP0041 NEW) + + add_library(shared_lib shared_lib.cpp) + target_link_libraries(shared_lib lib1) + +The ``exe1`` executable will be compiled with ``-DLIB1_WITH_EXE``, while the +``shared_lib`` shared library will be compiled with ``-DLIB1_WITH_SHARED_LIB`` +and ``-DCONSUMER_CMP0041_NEW``, because policy :policy:`CMP0041` is +``NEW`` at the point where the ``shared_lib`` target is created. + +The ``BUILD_INTERFACE`` expression wraps requirements which are only used when +consumed from a target in the same buildsystem, or when consumed from a target +exported to the build directory using the :command:`export` command. The +``INSTALL_INTERFACE`` expression wraps requirements which are only used when +consumed from a target which has been installed and exported with the +:command:`install(EXPORT)` command: + +.. code-block:: cmake + + add_library(ClimbingStats climbingstats.cpp) + target_compile_definitions(ClimbingStats INTERFACE + $<BUILD_INTERFACE:ClimbingStats_FROM_BUILD_LOCATION> + $<INSTALL_INTERFACE:ClimbingStats_FROM_INSTALLED_LOCATION> + ) + install(TARGETS ClimbingStats EXPORT libExport ${InstallArgs}) + install(EXPORT libExport NAMESPACE Upstream:: + DESTINATION lib/cmake/ClimbingStats) + export(EXPORT libExport NAMESPACE Upstream::) + + add_executable(exe1 exe1.cpp) + target_link_libraries(exe1 ClimbingStats) + +In this case, the ``exe1`` executable will be compiled with +``-DClimbingStats_FROM_BUILD_LOCATION``. The exporting commands generate +:prop_tgt:`IMPORTED` targets with either the ``INSTALL_INTERFACE`` or the +``BUILD_INTERFACE`` omitted, and the ``*_INTERFACE`` marker stripped away. +A separate project consuming the ``ClimbingStats`` package would contain: + +.. code-block:: cmake + + find_package(ClimbingStats REQUIRED) + + add_executable(Downstream main.cpp) + target_link_libraries(Downstream Upstream::ClimbingStats) + +Depending on whether the ``ClimbingStats`` package was used from the build +location or the install location, the ``Downstream`` target would be compiled +with either ``-DClimbingStats_FROM_BUILD_LOCATION`` or +``-DClimbingStats_FROM_INSTALL_LOCATION``. For more about packages and +exporting see the :manual:`cmake-packages(7)` manual. + +.. _`Include Directories and Usage Requirements`: + +Include Directories and Usage Requirements +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Include directories require some special consideration when specified as usage +requirements and when used with generator expressions. The +:command:`target_include_directories` command accepts both relative and +absolute include directories: + +.. code-block:: cmake + + add_library(lib1 lib1.cpp) + target_include_directories(lib1 PRIVATE + /absolute/path + relative/path + ) + +Relative paths are interpreted relative to the source directory where the +command appears. Relative paths are not allowed in the +:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of :prop_tgt:`IMPORTED` targets. + +In cases where a non-trivial generator expression is used, the +``INSTALL_PREFIX`` expression may be used within the argument of an +``INSTALL_INTERFACE`` expression. It is a replacement marker which +expands to the installation prefix when imported by a consuming project. + +Include directories 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 + + add_library(ClimbingStats climbingstats.cpp) + target_include_directories(ClimbingStats INTERFACE + $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/generated> + $<INSTALL_INTERFACE:/absolute/path> + $<INSTALL_INTERFACE:relative/path> + $<INSTALL_INTERFACE:$<INSTALL_PREFIX>/$<CONFIG>/generated> + ) + +Two convenience APIs are provided relating to include directories usage +requirements. The :variable:`CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE` variable +may be enabled, with an equivalent effect to: + +.. code-block:: cmake + + set_property(TARGET tgt APPEND PROPERTY INTERFACE_INCLUDE_DIRECTORIES + $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR};${CMAKE_CURRENT_BINARY_DIR}> + ) + +for each target affected. The convenience for installed targets is +an ``INCLUDES DESTINATION`` component with the :command:`install(TARGETS)` +command: + +.. code-block:: cmake + + install(TARGETS foo bar bat EXPORT tgts ${dest_args} + INCLUDES DESTINATION include + ) + install(EXPORT tgts ${other_args}) + install(FILES ${headers} DESTINATION include) + +This is equivalent to appending ``${CMAKE_INSTALL_PREFIX}/include`` to the +:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of each of the installed +:prop_tgt:`IMPORTED` targets when generated by :command:`install(EXPORT)`. + +When the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of an +:ref:`imported target <Imported targets>` is consumed, the entries in the +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 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 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. + +Link Libraries and Generator Expressions +---------------------------------------- + +Like build specifications, :prop_tgt:`link libraries <LINK_LIBRARIES>` may be +specified with generator expression conditions. However, as consumption of +usage requirements is based on collection from linked dependencies, there is +an additional limitation that the link dependencies must form a "directed +acyclic graph". That is, if linking to a target is dependent on the value of +a target property, that target property may not be dependent on the linked +dependencies: + +.. code-block:: cmake + + add_library(lib1 lib1.cpp) + add_library(lib2 lib2.cpp) + target_link_libraries(lib1 PUBLIC + $<$<TARGET_PROPERTY:POSITION_INDEPENDENT_CODE>:lib2> + ) + add_library(lib3 lib3.cpp) + set_property(TARGET lib3 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON) + + add_executable(exe1 exe1.cpp) + target_link_libraries(exe1 lib1 lib3) + +As the value of the :prop_tgt:`POSITION_INDEPENDENT_CODE` property of +the ``exe1`` target is dependent on the linked libraries (``lib3``), and the +edge of linking ``exe1`` is determined by the same +:prop_tgt:`POSITION_INDEPENDENT_CODE` property, the dependency graph above +contains a cycle. :manual:`cmake(1)` issues an error message. + +.. _`Output Artifacts`: + +Output Artifacts +---------------- + +The buildsystem targets created by the :command:`add_library` and +:command:`add_executable` commands create rules to create binary outputs. +The exact output location of the binaries can only be determined at +generate-time because it can depend on the build-configuration and the +link-language of linked dependencies etc. ``TARGET_FILE``, +``TARGET_LINKER_FILE`` and related expressions can be used to access the +name and location of generated binaries. These expressions do not work +for ``OBJECT`` libraries however, as there is no single file generated +by such libraries which is relevant to the expressions. + +There are three kinds of output artifacts that may be build by targets +as detailed in the following sections. Their classification differs +between DLL platforms and non-DLL platforms. All Windows-based +systems including Cygwin are DLL platforms. + +.. _`Runtime Output Artifacts`: + +Runtime Output Artifacts +^^^^^^^^^^^^^^^^^^^^^^^^ + +A *runtime* output artifact of a buildsystem target may be: + +* The executable file (e.g. ``.exe``) of an executable target + created by the :command:`add_executable` command. + +* On DLL platforms: the executable file (e.g. ``.dll``) of a shared + library target created by the :command:`add_library` command + with the ``SHARED`` option. + +The :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` and :prop_tgt:`RUNTIME_OUTPUT_NAME` +target properties may be used to control runtime output artifact locations +and names in the build tree. + +.. _`Library Output Artifacts`: + +Library Output Artifacts +^^^^^^^^^^^^^^^^^^^^^^^^ + +A *library* output artifact of a buildsystem target may be: + +* The loadable module file (e.g. ``.dll`` or ``.so``) of a module + library target created by the :command:`add_library` command + with the ``MODULE`` option. + +* On non-DLL platforms: the shared library file (e.g. ``.so`` or ``.dylib``) + 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` +target properties may be used to control library output artifact locations +and names in the build tree. + +.. _`Archive Output Artifacts`: + +Archive Output Artifacts +^^^^^^^^^^^^^^^^^^^^^^^^ + +An *archive* output artifact of a buildsystem target may be: + +* The static library file (e.g. ``.lib`` or ``.a``) of a static + library target created by the :command:`add_library` command + with the ``STATIC`` option. + +* On DLL platforms: the import library file (e.g. ``.lib``) of a shared + library target created by the :command:`add_library` command + with the ``SHARED`` option. This file is only guaranteed to exist if + the library exports at least one unmanaged symbol. + +* On DLL platforms: the import library file (e.g. ``.lib``) of an + 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. + +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_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. + +Pseudo Targets +============== + +Some target types do not represent outputs of the buildsystem, but only inputs +such as external dependencies, aliases or other non-build artifacts. Pseudo +targets are not represented in the generated buildsystem. + +.. _`Imported Targets`: + +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. 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 +:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`, +:prop_tgt:`INTERFACE_COMPILE_DEFINITIONS`, +:prop_tgt:`INTERFACE_COMPILE_OPTIONS`, +:prop_tgt:`INTERFACE_LINK_LIBRARIES`, and +:prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE`. + +The :prop_tgt:`LOCATION` may also be read from an IMPORTED target, though there +is rarely reason to do so. Commands such as :command:`add_custom_command` can +transparently use an :prop_tgt:`IMPORTED` :prop_tgt:`EXECUTABLE <TYPE>` target +as a ``COMMAND`` executable. + +The scope of the definition of an :prop_tgt:`IMPORTED` target is the directory +where it was defined. It may be accessed and used from subdirectories, but +not from parent directories or sibling directories. The scope is similar to +the scope of a cmake variable. + +It is also possible to define a ``GLOBAL`` :prop_tgt:`IMPORTED` target which is +accessible globally in the buildsystem. + +See the :manual:`cmake-packages(7)` manual for more on creating packages +with :prop_tgt:`IMPORTED` targets. + +.. _`Alias Targets`: + +Alias Targets +------------- + +An ``ALIAS`` target is a name which may be used interchangeably with +a binary target name in read-only contexts. A primary use-case for ``ALIAS`` +targets is for example or unit test executables accompanying a library, which +may be part of the same buildsystem or built separately based on user +configuration. + +.. code-block:: cmake + + add_library(lib1 lib1.cpp) + install(TARGETS lib1 EXPORT lib1Export ${dest_args}) + install(EXPORT lib1Export NAMESPACE Upstream:: ${other_args}) + + add_library(Upstream::lib1 ALIAS lib1) + +In another directory, we can link unconditionally to the ``Upstream::lib1`` +target, which may be an :prop_tgt:`IMPORTED` target from a package, or an +``ALIAS`` target if built as part of the same buildsystem. + +.. code-block:: cmake + + if (NOT TARGET Upstream::lib1) + find_package(lib1 REQUIRED) + endif() + add_executable(exe1 exe1.cpp) + target_link_libraries(exe1 Upstream::lib1) + +``ALIAS`` targets are not mutable, installable or exportable. They are +entirely local to the buildsystem description. A name can be tested for +whether it is an ``ALIAS`` name by reading the :prop_tgt:`ALIASED_TARGET` +property from it: + +.. code-block:: cmake + + get_target_property(_aliased Upstream::lib1 ALIASED_TARGET) + if(_aliased) + message(STATUS "The name Upstream::lib1 is an ALIAS for ${_aliased}.") + endif() + +.. _`Interface Libraries`: + +Interface Libraries +------------------- + +An ``INTERFACE`` library target does not compile sources and does not +produce a library artifact on disk, so it has no :prop_tgt:`LOCATION`. + +It may specify usage requirements such as +:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`, +:prop_tgt:`INTERFACE_COMPILE_DEFINITIONS`, +:prop_tgt:`INTERFACE_COMPILE_OPTIONS`, +:prop_tgt:`INTERFACE_LINK_LIBRARIES`, +:prop_tgt:`INTERFACE_SOURCES`, +and :prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE`. +Only the ``INTERFACE`` modes of the :command:`target_include_directories`, +:command:`target_compile_definitions`, :command:`target_compile_options`, +:command:`target_sources`, and :command:`target_link_libraries` commands +may be used with ``INTERFACE`` libraries. + +Since CMake 3.19, an ``INTERFACE`` library target may optionally contain +source files. An interface library that contains source files will be +included as a build target in the generated buildsystem. It does not +compile sources, but may contain custom commands to generate other sources. +Additionally, IDEs will show the source files as part of the target for +interactive reading and editing. + +A primary use-case for ``INTERFACE`` libraries is header-only libraries. + +.. code-block:: cmake + + add_library(Eigen INTERFACE + src/eigen.h + src/vector.h + src/matrix.h + ) + target_include_directories(Eigen INTERFACE + $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src> + $<INSTALL_INTERFACE:include/Eigen> + ) + + add_executable(exe1 exe1.cpp) + target_link_libraries(exe1 Eigen) + +Here, the usage requirements from the ``Eigen`` target are consumed and used +when compiling, but it has no effect on linking. + +Another use-case is to employ an entirely target-focussed design for usage +requirements: + +.. code-block:: cmake + + add_library(pic_on INTERFACE) + set_property(TARGET pic_on PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON) + add_library(pic_off INTERFACE) + set_property(TARGET pic_off PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE OFF) + + add_library(enable_rtti INTERFACE) + target_compile_options(enable_rtti INTERFACE + $<$<OR:$<COMPILER_ID:GNU>,$<COMPILER_ID:Clang>>:-rtti> + ) + + add_executable(exe1 exe1.cpp) + target_link_libraries(exe1 pic_on enable_rtti) + +This way, the build specification of ``exe1`` is expressed entirely as linked +targets, and the complexity of compiler-specific flags is encapsulated in an +``INTERFACE`` library target. + +``INTERFACE`` libraries may be installed and exported. Any content they refer +to must be installed separately: + +.. code-block:: cmake + + set(Eigen_headers + src/eigen.h + src/vector.h + src/matrix.h + ) + add_library(Eigen INTERFACE ${Eigen_headers}) + target_include_directories(Eigen INTERFACE + $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src> + $<INSTALL_INTERFACE:include/Eigen> + ) + + install(TARGETS Eigen EXPORT eigenExport) + install(EXPORT eigenExport NAMESPACE Upstream:: + DESTINATION lib/cmake/Eigen + ) + install(FILES ${Eigen_headers} + DESTINATION include/Eigen + ) diff --git a/Help/manual/cmake-commands.7.rst b/Help/manual/cmake-commands.7.rst new file mode 100644 index 0000000..036fa8f --- /dev/null +++ b/Help/manual/cmake-commands.7.rst @@ -0,0 +1,174 @@ +.. cmake-manual-description: CMake Language Command Reference + +cmake-commands(7) +***************** + +.. only:: html + + .. contents:: + +Scripting Commands +================== + +These commands are always available. + +.. toctree:: + :maxdepth: 1 + + /command/break + /command/cmake_host_system_information + /command/cmake_language + /command/cmake_minimum_required + /command/cmake_parse_arguments + /command/cmake_path + /command/cmake_policy + /command/configure_file + /command/continue + /command/else + /command/elseif + /command/endforeach + /command/endfunction + /command/endif + /command/endmacro + /command/endwhile + /command/execute_process + /command/file + /command/find_file + /command/find_library + /command/find_package + /command/find_path + /command/find_program + /command/foreach + /command/function + /command/get_cmake_property + /command/get_directory_property + /command/get_filename_component + /command/get_property + /command/if + /command/include + /command/include_guard + /command/list + /command/macro + /command/mark_as_advanced + /command/math + /command/message + /command/option + /command/return + /command/separate_arguments + /command/set + /command/set_directory_properties + /command/set_property + /command/site_name + /command/string + /command/unset + /command/variable_watch + /command/while + +Project Commands +================ + +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 + /command/add_definitions + /command/add_dependencies + /command/add_executable + /command/add_library + /command/add_link_options + /command/add_subdirectory + /command/add_test + /command/aux_source_directory + /command/build_command + /command/create_test_sourcelist + /command/define_property + /command/enable_language + /command/enable_testing + /command/export + /command/fltk_wrap_ui + /command/get_source_file_property + /command/get_target_property + /command/get_test_property + /command/include_directories + /command/include_external_msproject + /command/include_regular_expression + /command/install + /command/link_directories + /command/link_libraries + /command/load_cache + /command/project + /command/remove_definitions + /command/set_source_files_properties + /command/set_target_properties + /command/set_tests_properties + /command/source_group + /command/target_compile_definitions + /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 + +.. _`CTest Commands`: + +CTest Commands +============== + +These commands are available only in CTest scripts. + +.. toctree:: + :maxdepth: 1 + + /command/ctest_build + /command/ctest_configure + /command/ctest_coverage + /command/ctest_empty_binary_directory + /command/ctest_memcheck + /command/ctest_read_custom_files + /command/ctest_run_script + /command/ctest_sleep + /command/ctest_start + /command/ctest_submit + /command/ctest_test + /command/ctest_update + /command/ctest_upload + +Deprecated Commands +=================== + +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 + + /command/build_name + /command/exec_program + /command/export_library_dependencies + /command/install_files + /command/install_programs + /command/install_targets + /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 + /command/use_mangled_mesa + /command/utility_source + /command/variable_requires + /command/write_file diff --git a/Help/manual/cmake-compile-features.7.rst b/Help/manual/cmake-compile-features.7.rst new file mode 100644 index 0000000..56d16c0 --- /dev/null +++ b/Help/manual/cmake-compile-features.7.rst @@ -0,0 +1,381 @@ +.. cmake-manual-description: CMake Compile Features Reference + +cmake-compile-features(7) +************************* + +.. only:: html + + .. contents:: + +Introduction +============ + +Project source code may depend on, or be conditional on, the availability +of certain features of the compiler. There are three use-cases which arise: +`Compile Feature Requirements`_, `Optional Compile Features`_ +and `Conditional Compilation Options`_. + +While features are typically specified in programming language standards, +CMake provides a primary user interface based on granular handling of +the features, not the language standard that introduced the feature. + +The :prop_gbl:`CMAKE_C_KNOWN_FEATURES`, :prop_gbl:`CMAKE_CUDA_KNOWN_FEATURES`, +and :prop_gbl:`CMAKE_CXX_KNOWN_FEATURES` global properties contain all the +features known to CMake, regardless of compiler support for the feature. +The :variable:`CMAKE_C_COMPILE_FEATURES`, :variable:`CMAKE_CUDA_COMPILE_FEATURES` +, and :variable:`CMAKE_CXX_COMPILE_FEATURES` variables contain all features +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. 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 +============================ + +Compile feature requirements may be specified with the +:command:`target_compile_features` command. For example, if a target must +be compiled with compiler support for the +:prop_gbl:`cxx_constexpr <CMAKE_CXX_KNOWN_FEATURES>` feature: + +.. code-block:: cmake + + add_library(mylib requires_constexpr.cpp) + target_compile_features(mylib PRIVATE cxx_constexpr) + +In processing the requirement for the ``cxx_constexpr`` feature, +:manual:`cmake(1)` will ensure that the in-use C++ compiler is capable +of the feature, and will add any necessary flags such as ``-std=gnu++11`` +to the compile lines of C++ files in the ``mylib`` target. A +``FATAL_ERROR`` is issued if the compiler is not capable of the +feature. + +The exact compile flags and language standard are deliberately not part +of the user interface for this use-case. CMake will compute the +appropriate compile flags to use by considering the features specified +for each target. + +Such compile flags are added even if the compiler supports the +particular feature without the flag. For example, the GNU compiler +supports variadic templates (with a warning) even if ``-std=gnu++98`` is +used. CMake adds the ``-std=gnu++11`` flag if ``cxx_variadic_templates`` +is specified as a requirement. + +In the above example, ``mylib`` requires ``cxx_constexpr`` when it +is built itself, but consumers of ``mylib`` are not required to use a +compiler which supports ``cxx_constexpr``. If the interface of +``mylib`` does require the ``cxx_constexpr`` feature (or any other +known feature), that may be specified with the ``PUBLIC`` or +``INTERFACE`` signatures of :command:`target_compile_features`: + +.. code-block:: cmake + + add_library(mylib requires_constexpr.cpp) + # cxx_constexpr is a usage-requirement + target_compile_features(mylib PUBLIC cxx_constexpr) + + # main.cpp will be compiled with -std=gnu++11 on GNU for cxx_constexpr. + add_executable(myexe main.cpp) + target_link_libraries(myexe mylib) + +Feature requirements are evaluated transitively by consuming the link +implementation. See :manual:`cmake-buildsystem(7)` for more on +transitive behavior of build properties and usage requirements. + +.. _`Requiring Language Standards`: + +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 +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 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 +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``). + +Availability of Compiler Extensions +----------------------------------- + +Because the :prop_tgt:`CXX_EXTENSIONS` target property is ``ON`` by default, +CMake uses extended variants of language dialects by default, such as +``-std=gnu++11`` instead of ``-std=c++11``. That target property may be +set to ``OFF`` to use the non-extended variant of the dialect flag. Note +that because most compilers enable extensions by default, this could +expose cross-platform bugs in user code or in the headers of third-party +dependencies. + +Optional Compile Features +========================= + +Compile features may be preferred if available, without creating a hard +requirement. For example, a library may provides alternative +implementations depending on whether the ``cxx_variadic_templates`` +feature is available: + +.. code-block:: c++ + + #if Foo_COMPILER_CXX_VARIADIC_TEMPLATES + template<int I, int... Is> + struct Interface; + + template<int I> + struct Interface<I> + { + static int accumulate() + { + return I; + } + }; + + template<int I, int... Is> + struct Interface + { + static int accumulate() + { + return I + Interface<Is...>::accumulate(); + } + }; + #else + template<int I1, int I2 = 0, int I3 = 0, int I4 = 0> + struct Interface + { + static int accumulate() { return I1 + I2 + I3 + I4; } + }; + #endif + +Such an interface depends on using the correct preprocessor defines for the +compiler features. CMake can generate a header file containing such +defines using the :module:`WriteCompilerDetectionHeader` module. The +module contains the ``write_compiler_detection_header`` function which +accepts parameters to control the content of the generated header file: + +.. code-block:: cmake + + write_compiler_detection_header( + FILE "${CMAKE_CURRENT_BINARY_DIR}/foo_compiler_detection.h" + PREFIX Foo + COMPILERS GNU + FEATURES + cxx_variadic_templates + ) + +Such a header file may be used internally in the source code of a project, +and it may be installed and used in the interface of library code. + +For each feature listed in ``FEATURES``, a preprocessor definition +is created in the header file, and defined to either ``1`` or ``0``. + +Additionally, some features call for additional defines, such as the +``cxx_final`` and ``cxx_override`` features. Rather than being used in +``#ifdef`` code, the ``final`` keyword is abstracted by a symbol +which is defined to either ``final``, a compiler-specific equivalent, or +to empty. That way, C++ code can be written to unconditionally use the +symbol, and compiler support determines what it is expanded to: + +.. code-block:: c++ + + struct Interface { + virtual void Execute() = 0; + }; + + struct Concrete Foo_FINAL { + void Execute() Foo_OVERRIDE; + }; + +In this case, ``Foo_FINAL`` will expand to ``final`` if the +compiler supports the keyword, or to empty otherwise. + +In this use-case, the CMake code will wish to enable a particular language +standard if available from the compiler. The :prop_tgt:`CXX_STANDARD` +target property variable may be set to the desired language standard +for a particular target, and the :variable:`CMAKE_CXX_STANDARD` may be +set to influence all following targets: + +.. code-block:: cmake + + write_compiler_detection_header( + FILE "${CMAKE_CURRENT_BINARY_DIR}/foo_compiler_detection.h" + PREFIX Foo + COMPILERS GNU + FEATURES + cxx_final cxx_override + ) + + # Includes foo_compiler_detection.h and uses the Foo_FINAL symbol + # which will expand to 'final' if the compiler supports the requested + # CXX_STANDARD. + add_library(foo foo.cpp) + set_property(TARGET foo PROPERTY CXX_STANDARD 11) + + # Includes foo_compiler_detection.h and uses the Foo_FINAL symbol + # which will expand to 'final' if the compiler supports the feature, + # even though CXX_STANDARD is not set explicitly. The requirement of + # cxx_constexpr causes CMake to set CXX_STANDARD internally, which + # affects the compile flags. + add_library(foo_impl foo_impl.cpp) + target_compile_features(foo_impl PRIVATE cxx_constexpr) + +The ``write_compiler_detection_header`` function also creates compatibility +code for other features which have standard equivalents. For example, the +``cxx_static_assert`` feature is emulated with a template and abstracted +via the ``<PREFIX>_STATIC_ASSERT`` and ``<PREFIX>_STATIC_ASSERT_MSG`` +function-macros. + +Conditional Compilation Options +=============================== + +Libraries may provide entirely different header files depending on +requested compiler features. + +For example, a header at ``with_variadics/interface.h`` may contain: + +.. code-block:: c++ + + template<int I, int... Is> + struct Interface; + + template<int I> + struct Interface<I> + { + static int accumulate() + { + return I; + } + }; + + template<int I, int... Is> + struct Interface + { + static int accumulate() + { + return I + Interface<Is...>::accumulate(); + } + }; + +while a header at ``no_variadics/interface.h`` may contain: + +.. code-block:: c++ + + template<int I1, int I2 = 0, int I3 = 0, int I4 = 0> + struct Interface + { + static int accumulate() { return I1 + I2 + I3 + I4; } + }; + +It would be possible to write a abstraction ``interface.h`` header +containing something like: + +.. code-block:: c++ + + #include "foo_compiler_detection.h" + #if Foo_COMPILER_CXX_VARIADIC_TEMPLATES + #include "with_variadics/interface.h" + #else + #include "no_variadics/interface.h" + #endif + +However this could be unmaintainable if there are many files to +abstract. What is needed is to use alternative include directories +depending on the compiler capabilities. + +CMake provides a ``COMPILE_FEATURES`` +:manual:`generator expression <cmake-generator-expressions(7)>` to implement +such conditions. This may be used with the build-property commands such as +:command:`target_include_directories` and :command:`target_link_libraries` +to set the appropriate :manual:`buildsystem <cmake-buildsystem(7)>` +properties: + +.. code-block:: cmake + + add_library(foo INTERFACE) + set(with_variadics ${CMAKE_CURRENT_SOURCE_DIR}/with_variadics) + set(no_variadics ${CMAKE_CURRENT_SOURCE_DIR}/no_variadics) + target_include_directories(foo + INTERFACE + "$<$<COMPILE_FEATURES:cxx_variadic_templates>:${with_variadics}>" + "$<$<NOT:$<COMPILE_FEATURES:cxx_variadic_templates>>:${no_variadics}>" + ) + +Consuming code then simply links to the ``foo`` target as usual and uses +the feature-appropriate include directory + +.. code-block:: cmake + + add_executable(consumer_with consumer_with.cpp) + target_link_libraries(consumer_with foo) + set_property(TARGET consumer_with CXX_STANDARD 11) + + add_executable(consumer_no consumer_no.cpp) + target_link_libraries(consumer_no foo) + +Supported Compilers +=================== + +CMake is currently aware of the :prop_tgt:`C++ standards <CXX_STANDARD>` +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+. +* ``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 +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+ + +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+. +* ``Fujitsu``: Fujitsu HPC compiler 4.0+. +* ``PGI``: PGI version 12.10+. +* ``NVHPC``: NVIDIA HPC compilers version 11.0+. +* ``TI``: Texas Instruments compiler. +* ``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 +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++. + +CMake is currently aware of the :prop_tgt:`CUDA standards <CUDA_STANDARD>` and +their associated meta-features (e.g. ``cuda_std_11``) available from the +following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the +versions specified for each: + +* ``Clang``: Clang compiler 5.0+. +* ``NVIDIA``: NVIDIA nvcc compiler 7.5+. diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst new file mode 100644 index 0000000..fe146de --- /dev/null +++ b/Help/manual/cmake-developer.7.rst @@ -0,0 +1,501 @@ +.. cmake-manual-description: CMake Developer Reference + +cmake-developer(7) +****************** + +.. only:: html + + .. contents:: + +Introduction +============ + +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. + +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 ``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 is +available, 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 :ref:`config file package <Config File Packages>`. + +The traditional approach is to use variables for everything, including +libraries and executables: see the `Standard Variable Names`_ section +below. This is what most of the existing find modules provided by CMake +do. + +The more modern approach is to behave as much like +:ref:`config file packages <Config File Packages>` files as possible, by +providing :ref:`imported target <Imported targets>`. This has the advantage +of propagating :ref:`Target Usage Requirements` to consumers. + +In either case (or even when providing both variables and imported +targets), find modules should provide backwards compatibility with old +versions that had the same name. + +A FindFoo.cmake module will typically be loaded by the command:: + + find_package(Foo [major[.minor[.patch[.tweak]]]] + [EXACT] [QUIET] [REQUIRED] + [[COMPONENTS] [components...]] + [OPTIONAL_COMPONENTS components...] + [NO_POLICY_SCOPE]) + +See the :command:`find_package` documentation for details on what +variables are set for the find module. Most of these are dealt with by +using :module:`FindPackageHandleStandardArgs`. + +Briefly, the module should only locate versions of the package +compatible with the requested version, as described by the +``Foo_FIND_VERSION`` family of variables. If ``Foo_FIND_QUIETLY`` is +set to true, it should avoid printing messages, including anything +complaining about the package not being found. If ``Foo_FIND_REQUIRED`` +is set to true, the module should issue a ``FATAL_ERROR`` if the package +cannot be found. If neither are set to true, it should print a +non-fatal message if it cannot find the package. + +Packages that find multiple semi-independent parts (like bundles of +libraries) should search for the components listed in +``Foo_FIND_COMPONENTS`` if it is set , and only set ``Foo_FOUND`` to +true if for each searched-for component ``<c>`` that was not found, +``Foo_FIND_REQUIRED_<c>`` is not set to true. The ``HANDLE_COMPONENTS`` +argument of ``find_package_handle_standard_args()`` can be used to +implement this. + +If ``Foo_FIND_COMPONENTS`` is not set, which modules are searched for +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. + + +.. _`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 +targets), the following variable names should be used to keep things +consistent between Find modules. Note that all variables start with +``Xxx_``, which (unless otherwise noted) must match exactly the name +of the ``FindXxx.cmake`` file, including upper/lowercase. +This prefix on the variable names ensures that they do not conflict with +variables of other Find modules. The same pattern should also be followed +for any macros, functions and imported targets defined by the Find module. + +``Xxx_INCLUDE_DIRS`` + The final set of include directories listed in one variable for use by + client code. This should not be a cache entry (note that this also means + this variable should not be used as the result variable of a + :command:`find_path` command - see ``Xxx_INCLUDE_DIR`` below for that). + +``Xxx_LIBRARIES`` + The libraries to use with the module. These may be CMake targets, full + absolute paths to a library binary or the name of a library that the + linker must find in its search path. This should not be a cache entry + (note that this also means this variable should not be used as the + result variable of a :command:`find_library` command - see + ``Xxx_LIBRARY`` below for that). + +``Xxx_DEFINITIONS`` + The compile definitions to use when compiling code that uses the module. + This really shouldn't include options such as ``-DHAS_JPEG`` that a client + source-code file uses to decide whether to ``#include <jpeg.h>`` + +``Xxx_EXECUTABLE`` + The full absolute path to an executable. In this case, ``Xxx`` might not + be the name of the module, it might be the name of the tool (usually + converted to all uppercase), assuming that tool has such a well-known name + that it is unlikely that another tool with the same name exists. It would + be appropriate to use this as the result variable of a + :command:`find_program` command. + +``Xxx_YYY_EXECUTABLE`` + Similar to ``Xxx_EXECUTABLE`` except here the ``Xxx`` is always the module + name and ``YYY`` is the tool name (again, usually fully uppercase). + Prefer this form if the tool name is not very widely known or has the + potential to clash with another tool. For greater consistency, also + prefer this form if the module provides more than one executable. + +``Xxx_LIBRARY_DIRS`` + Optionally, the final set of library directories listed in one + variable for use by client code. This should not be a cache entry. + +``Xxx_ROOT_DIR`` + Where to find the base directory of the module. + +``Xxx_VERSION_VV`` + Variables of this form specify whether the ``Xxx`` module being provided + is version ``VV`` of the module. There should not be more than one + variable of this form set to true for a given module. For example, a + module ``Barry`` might have evolved over many years and gone through a + number of different major versions. Version 3 of the ``Barry`` module + might set the variable ``Barry_VERSION_3`` to true, whereas an older + version of the module might set ``Barry_VERSION_2`` to true instead. + It would be an error for both ``Barry_VERSION_3`` and ``Barry_VERSION_2`` + to both be set to true. + +``Xxx_WRAP_YY`` + When a variable of this form is set to false, it indicates that the + relevant wrapping command should not be used. The wrapping command + depends on the module, it may be implied by the module name or it might + be specified by the ``YY`` part of the variable. + +``Xxx_Yy_FOUND`` + For variables of this form, ``Yy`` is the name of a component for the + module. It should match exactly one of the valid component names that + may be passed to the :command:`find_package` command for the module. + If a variable of this form is set to false, it means that the ``Yy`` + component of module ``Xxx`` was not found or is not available. + Variables of this form would typically be used for optional components + so that the caller can check whether an optional component is available. + +``Xxx_FOUND`` + When the :command:`find_package` command returns to the caller, this + variable will be set to true if the module was deemed to have been found + successfully. + +``Xxx_NOT_FOUND_MESSAGE`` + Should be set by config-files in the case that it has set + ``Xxx_FOUND`` to FALSE. The contained message will be printed by the + :command:`find_package` command and by + :command:`find_package_handle_standard_args` to inform the user about the + problem. Use this instead of calling :command:`message` directly to + report a reason for failing to find the module or package. + +``Xxx_RUNTIME_LIBRARY_DIRS`` + Optionally, the runtime library search path for use when running an + executable linked to shared libraries. The list should be used by + user code to create the ``PATH`` on windows or ``LD_LIBRARY_PATH`` on + UNIX. This should not be a cache entry. + +``Xxx_VERSION`` + The full version string of the package found, if any. Note that many + existing modules provide ``Xxx_VERSION_STRING`` instead. + +``Xxx_VERSION_MAJOR`` + The major version of the package found, if any. + +``Xxx_VERSION_MINOR`` + The minor version of the package found, if any. + +``Xxx_VERSION_PATCH`` + The patch version of the package found, if any. + +The following names should not usually be used in ``CMakeLists.txt`` files. +They are intended for use by Find modules to specify and cache the locations +of specific files or directories. Users are typically able to set and edit +these variables to control the behavior of Find modules (like entering the +path to a library manually): + +``Xxx_LIBRARY`` + The path of the library. Use this form only when the module provides a + single library. It is appropriate to use this as the result variable + in a :command:`find_library` command. + +``Xxx_Yy_LIBRARY`` + The path of library ``Yy`` provided by the module ``Xxx``. Use this form + when the module provides more than one library or where other modules may + also provide a library of the same name. It is also appropriate to use + this form as the result variable in a :command:`find_library` command. + +``Xxx_INCLUDE_DIR`` + When the module provides only a single library, this variable can be used + to specify where to find headers for using the library (or more accurately, + the path that consumers of the library should add to their header search + path). It would be appropriate to use this as the result variable in a + :command:`find_path` command. + +``Xxx_Yy_INCLUDE_DIR`` + If the module provides more than one library or where other modules may + also provide a library of the same name, this form is recommended for + specifying where to find headers for using library ``Yy`` provided by + the module. Again, it would be appropriate to use this as the result + variable in a :command:`find_path` command. + +To prevent users being overwhelmed with settings to configure, try to +keep as many options as possible out of the cache, leaving at least one +option which can be used to disable use of the module, or locate a +not-found library (e.g. ``Xxx_ROOT_DIR``). For the same reason, mark +most cache options as advanced. For packages which provide both debug +and release binaries, it is common to create cache variables with a +``_LIBRARY_<CONFIG>`` suffix, such as ``Foo_LIBRARY_RELEASE`` and +``Foo_LIBRARY_DEBUG``. The :module:`SelectLibraryConfigurations` module +can be helpful for such cases. + +While these are the standard variable names, you should provide +backwards compatibility for any old names that were actually in use. +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``. + +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: + +:: + + # Distributed under the OSI-approved BSD 3-Clause License. See accompanying + # file Copyright.txt or https://cmake.org/licensing for details. + + #[=======================================================================[.rst: + FindFoo + ------- + + Finds the Foo library. + + Imported Targets + ^^^^^^^^^^^^^^^^ + + This module provides the following imported targets, if found: + + ``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. + +* Optionally a section listing cache variables used by the module, if any. + +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. + +First, we try to use ``pkg-config`` to find the library. Note that we +cannot rely on this, as it may not be available, but it provides a good +starting point. + +.. code-block:: cmake + + find_package(PkgConfig) + pkg_check_modules(PC_Foo QUIET Foo) + +This should define some variables starting ``PC_Foo_`` that contain the +information from the ``Foo.pc`` file. + +Now we need to find the libraries and include files; we use the +information from ``pkg-config`` to provide hints to CMake about where to +look. + +.. code-block:: cmake + + find_path(Foo_INCLUDE_DIR + NAMES foo.h + PATHS ${PC_Foo_INCLUDE_DIRS} + PATH_SUFFIXES Foo + ) + find_library(Foo_LIBRARY + NAMES foo + PATHS ${PC_Foo_LIBRARY_DIRS} + ) + +Alternatively, if the library is available with multiple configurations, you can +use :module:`SelectLibraryConfigurations` to automatically set the +``Foo_LIBRARY`` variable instead: + +.. code-block:: cmake + + find_library(Foo_LIBRARY_RELEASE + NAMES foo + PATHS ${PC_Foo_LIBRARY_DIRS}/Release + ) + find_library(Foo_LIBRARY_DEBUG + NAMES foo + PATHS ${PC_Foo_LIBRARY_DIRS}/Debug + ) + + include(SelectLibraryConfigurations) + select_library_configurations(Foo) + +If you have a good way of getting the version (from a header file, for +example), you can use that information to set ``Foo_VERSION`` (although +note that find modules have traditionally used ``Foo_VERSION_STRING``, +so you may want to set both). Otherwise, attempt to use the information +from ``pkg-config`` + +.. code-block:: cmake + + set(Foo_VERSION ${PC_Foo_VERSION}) + +Now we can use :module:`FindPackageHandleStandardArgs` to do most of the +rest of the work for us + +.. code-block:: cmake + + include(FindPackageHandleStandardArgs) + find_package_handle_standard_args(Foo + FOUND_VAR Foo_FOUND + REQUIRED_VARS + Foo_LIBRARY + Foo_INCLUDE_DIR + VERSION_VAR Foo_VERSION + ) + +This will check that the ``REQUIRED_VARS`` contain values (that do not +end in ``-NOTFOUND``) and set ``Foo_FOUND`` appropriately. It will also +cache those values. If ``Foo_VERSION`` is set, and a required version +was passed to :command:`find_package`, it will check the requested version +against the one in ``Foo_VERSION``. It will also print messages as +appropriate; note that if the package was found, it will print the +contents of the first required variable to indicate where it was found. + +At this point, we have to provide a way for users of the find module to +link to the library or libraries that were found. There are two +approaches, as discussed in the `Find Modules`_ section above. The +traditional variable approach looks like + +.. code-block:: cmake + + if(Foo_FOUND) + set(Foo_LIBRARIES ${Foo_LIBRARY}) + set(Foo_INCLUDE_DIRS ${Foo_INCLUDE_DIR}) + set(Foo_DEFINITIONS ${PC_Foo_CFLAGS_OTHER}) + endif() + +If more than one library was found, all of them should be included in +these variables (see the `Standard Variable Names`_ section for more +information). + +When providing imported targets, these should be namespaced (hence the +``Foo::`` prefix); CMake will recognize that values passed to +:command:`target_link_libraries` that contain ``::`` in their name are +supposed to be imported targets (rather than just library names), and +will produce appropriate diagnostic messages if that target does not +exist (see policy :policy:`CMP0028`). + +.. code-block:: cmake + + if(Foo_FOUND AND NOT TARGET Foo::Foo) + add_library(Foo::Foo UNKNOWN IMPORTED) + set_target_properties(Foo::Foo PROPERTIES + IMPORTED_LOCATION "${Foo_LIBRARY}" + INTERFACE_COMPILE_OPTIONS "${PC_Foo_CFLAGS_OTHER}" + INTERFACE_INCLUDE_DIRECTORIES "${Foo_INCLUDE_DIR}" + ) + endif() + +One thing to note about this is that the ``INTERFACE_INCLUDE_DIRECTORIES`` and +similar properties should only contain information about the target itself, and +not any of its dependencies. Instead, those dependencies should also be +targets, and CMake should be told that they are dependencies of this target. +CMake will then combine all the necessary information automatically. + +The type of the :prop_tgt:`IMPORTED` target created in the +:command:`add_library` command can always be specified as ``UNKNOWN`` +type. This simplifies the code in cases where static or shared variants may +be found, and CMake will determine the type by inspecting the files. + +If the library is available with multiple configurations, the +:prop_tgt:`IMPORTED_CONFIGURATIONS` target property should also be +populated: + +.. code-block:: cmake + + if(Foo_FOUND) + if (NOT TARGET Foo::Foo) + add_library(Foo::Foo UNKNOWN IMPORTED) + endif() + if (Foo_LIBRARY_RELEASE) + set_property(TARGET Foo::Foo APPEND PROPERTY + IMPORTED_CONFIGURATIONS RELEASE + ) + set_target_properties(Foo::Foo PROPERTIES + IMPORTED_LOCATION_RELEASE "${Foo_LIBRARY_RELEASE}" + ) + endif() + if (Foo_LIBRARY_DEBUG) + set_property(TARGET Foo::Foo APPEND PROPERTY + IMPORTED_CONFIGURATIONS DEBUG + ) + set_target_properties(Foo::Foo PROPERTIES + IMPORTED_LOCATION_DEBUG "${Foo_LIBRARY_DEBUG}" + ) + endif() + set_target_properties(Foo::Foo PROPERTIES + INTERFACE_COMPILE_OPTIONS "${PC_Foo_CFLAGS_OTHER}" + INTERFACE_INCLUDE_DIRECTORIES "${Foo_INCLUDE_DIR}" + ) + endif() + +The ``RELEASE`` variant should be listed first in the property +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 +the user explicitly asks to edit them. + +.. code-block:: cmake + + mark_as_advanced( + Foo_INCLUDE_DIR + Foo_LIBRARY + ) + +If this module replaces an older version, you should set compatibility variables +to cause the least disruption possible. + +.. code-block:: cmake + + # compatibility variables + set(Foo_VERSION_STRING ${Foo_VERSION}) diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst new file mode 100644 index 0000000..bc1fa1d --- /dev/null +++ b/Help/manual/cmake-env-variables.7.rst @@ -0,0 +1,96 @@ +.. 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 Change Behavior +========================================== + +.. toctree:: + :maxdepth: 1 + + /envvar/CMAKE_PREFIX_PATH + +Environment Variables that Control the Build +============================================ + +.. toctree:: + :maxdepth: 1 + + /envvar/CMAKE_APPLE_SILICON_PROCESSOR + /envvar/CMAKE_BUILD_PARALLEL_LEVEL + /envvar/CMAKE_CONFIG_TYPE + /envvar/CMAKE_EXPORT_COMPILE_COMMANDS + /envvar/CMAKE_GENERATOR + /envvar/CMAKE_GENERATOR_INSTANCE + /envvar/CMAKE_GENERATOR_PLATFORM + /envvar/CMAKE_GENERATOR_TOOLSET + /envvar/CMAKE_LANG_COMPILER_LAUNCHER + /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/CUDAARCHS + /envvar/CUDACXX + /envvar/CUDAFLAGS + /envvar/CUDAHOSTCXX + /envvar/CXX + /envvar/CXXFLAGS + /envvar/FC + /envvar/FFLAGS + /envvar/ISPC + /envvar/ISPCFLAGS + /envvar/OBJC + /envvar/OBJCXX + /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 + +Environment Variables for the CMake curses interface +==================================================== + +.. toctree:: + :maxdepth: 1 + + /envvar/CCMAKE_COLORS diff --git a/Help/manual/cmake-file-api.7.rst b/Help/manual/cmake-file-api.7.rst new file mode 100644 index 0000000..cbc3d6d --- /dev/null +++ b/Help/manual/cmake-file-api.7.rst @@ -0,0 +1,1506 @@ +.. 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": { + "multiConfig": false, + "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: + + ``multiConfig`` + A boolean specifying whether the generator supports multiple output + configurations. + ``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": 2 }, + "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" + }, + "jsonFile": "<file>" + }, + { + "source": "sub", + "build": "sub", + "parentIndex": 0, + "projectIndex": 0, + "targetIndexes": [ 1 ], + "minimumCMakeVersion": { + "string": "3.14" + }, + "jsonFile": "<file>" + } + ], + "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. + + ``jsonFile`` + A JSON string specifying a path relative to the codemodel file + to another JSON file containing a + `"codemodel" version 2 "directory" object`_. + + This field was added in codemodel version 2.3. + + ``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 "directory" object +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A codemodel "directory" object is referenced by a `"codemodel" version 2`_ +object's ``directories`` array. Each "directory" object is a JSON object +with members: + +``paths`` + 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. + +``installers`` + A JSON array of entries corresponding to :command:`install` rules. + Each entry is a JSON object containing members: + + ``component`` + A string specifying the component selected by the corresponding + :command:`install` command invocation. + + ``destination`` + Optional member that is present for specific ``type`` values below. + The value is a string specifying the install destination path. + The path may be absolute or relative to the install prefix. + + ``paths`` + Optional member that is present for specific ``type`` values below. + The value is a JSON array of entries corresponding to the paths + (files or directories) to be installed. Each entry is one of: + + * A string specifying the path from which a file or directory + is to be installed. The portion of the path not preceded by + a ``/`` also specifies the path (name) to which the file + or directory is to be installed under the destination. + + * A JSON object with members: + + ``from`` + A string specifying the path from which a file or directory + is to be installed. + + ``to`` + A string specifying the path to which the file or directory + is to be installed under the destination. + + In both cases the paths are represented with forward slashes. If + the "from" path is inside the top-level directory documented by the + corresponding ``type`` value, then the path is specified relative + to that directory. Otherwise the path is absolute. + + ``type`` + A string specifying the type of installation rule. The value is one + of the following, with some variants providing additional members: + + ``file`` + An :command:`install(FILES)` or :command:`install(PROGRAMS)` call. + The ``destination`` and ``paths`` members are populated, with paths + under the top-level *source* directory expressed relative to it. + The ``isOptional`` member may exist. + This type has no additional members. + + ``directory`` + An :command:`install(DIRECTORY)` call. + The ``destination`` and ``paths`` members are populated, with paths + under the top-level *source* directory expressed relative to it. + The ``isOptional`` member may exist. + This type has no additional members. + + ``target`` + An :command:`install(TARGETS)` call. + The ``destination`` and ``paths`` members are populated, with paths + under the top-level *build* directory expressed relative to it. + The ``isOptional`` member may exist. + This type has additional members ``targetId``, ``targetIndex``, + ``targetIsImportLibrary``, and ``targetInstallNamelink``. + + ``export`` + An :command:`install(EXPORT)` call. + The ``destination`` and ``paths`` members are populated, with paths + under the top-level *build* directory expressed relative to it. + The ``paths`` entries refer to files generated automatically by + CMake for installation, and their actual values are considered + private implementation details. + This type has additional members ``exportName`` and ``exportTargets``. + + ``script`` + An :command:`install(SCRIPT)` call. + This type has additional member ``scriptFile``. + + ``code`` + An :command:`install(CODE)` call. + This type has no additional members. + + ``isExcludeFromAll`` + Optional member that is present with boolean value ``true`` when + :command:`install` is called with the ``EXCLUDE_FROM_ALL`` option. + + ``isOptional`` + Optional member that is present with boolean value ``true`` when + :command:`install` is called with the ``OPTIONAL`` option. + This is allowed when ``type`` is ``file``, ``directory``, or ``target``. + + ``targetId`` + Optional member that is present when ``type`` is ``target``. + The value is a string uniquely identifying the target to be installed. + This matches the ``id`` member of the target in the main + "codemodel" object's ``targets`` array. + + ``targetIndex`` + Optional member that is present when ``type`` is ``target``. + The value is an unsigned integer 0-based index into the main "codemodel" + object's ``targets`` array for the target to be installed. + + ``targetIsImportLibrary`` + Optional member that is present when ``type`` is ``target`` and + the installer is for a Windows DLL import library file or for an + AIX linker import file. If present, it has boolean value ``true``. + + ``targetInstallNamelink`` + Optional member that is present when ``type`` is ``target`` and + the installer corresponds to a target that may use symbolic links + to implement the :prop_tgt:`VERSION` and :prop_tgt:`SOVERSION` + target properties. + The value is a string indicating how the installer is supposed to + handle the symlinks: ``skip`` means the installer should skip the + symlinks and install only the real file, and ``only`` means the + installer should install only the symlinks and not the real file. + In all cases the ``paths`` member lists what it actually installs. + + ``exportName`` + Optional member that is present when ``type`` is ``export``. + The value is a string specifying the name of the export. + + ``exportTargets`` + Optional member that is present when ``type`` is ``export``. + The value is a JSON array of entries corresponding to the targets + included in the export. Each entry is a JSON object with members: + + ``id`` + A string uniquely identifying the target. This matches + the ``id`` member of the target in the main "codemodel" + object's ``targets`` array. + + ``index`` + An unsigned integer 0-based index into the main "codemodel" + object's ``targets`` array for the target. + + ``scriptFile`` + Optional member that is present when ``type`` is ``script``. + The value is a string specifying the path to the script 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. + + ``backtrace`` + Optional member that is present when a CMake language backtrace to + the :command:`install` or other command invocation that added this + installer is available. The value is an unsigned integer 0-based + index into the ``backtraceGraph`` member's ``nodes`` array. + +``backtraceGraph`` + A `"codemodel" version 2 "backtrace graph"`_ whose nodes are referenced + from ``backtrace`` members elsewhere in this "directory" 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``, ``INTERFACE_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. + + ``languageStandard`` + Optional member that is present when the language standard is set + explicitly (e.g. via :prop_tgt:`CXX_STANDARD`) or implicitly by + compile features. Each entry is a JSON object with two members: + + ``backtraces`` + Optional member that is present when a CMake language backtrace to + the ``<LANG>_STANDARD`` setting is available. If the language + standard was set implicitly by compile features those are used as + the backtrace(s). It's possible for multiple compile features to + require the same language standard so there could be multiple + backtraces. The value is a JSON array with each entry being an + unsigned integer 0-based index into the ``backtraceGraph`` + member's ``nodes`` array. + + ``standard`` + String representing the language standard. + + This field was added in codemodel version 2.2. + + ``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. + + ``precompileHeaders`` + Optional member that is present when :command:`target_precompile_headers` + or other command invocations set :prop_tgt:`PRECOMPILE_HEADERS` on the + target. The value is a JSON array with an entry for each header. Each + entry is a JSON object with members: + + ``header`` + Full path to the precompile header file. + + ``backtrace`` + Optional member that is present when a CMake language backtrace to + the :command:`target_precompile_headers` or other command invocation + that added this precompiled header is available. The value is an + unsigned integer 0-based index into the ``backtraceGraph`` member's + ``nodes`` array. + + This field was added in codemodel version 2.1. + + ``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 `"codemodel" version 2 "backtrace graph"`_ whose nodes are referenced + from ``backtrace`` members elsewhere in this "target" object. + +"codemodel" version 2 "backtrace graph" +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``backtraceGraph`` member of a `"codemodel" version 2 "directory" object`_, +or `"codemodel" version 2 "target" object`_ is a JSON object describing a +graph of backtraces. Its nodes are referenced from ``backtrace`` members +elsewhere in the containing object. The backtrace graph object 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. + +Object Kind "toolchains" +------------------------ + +The ``toolchains`` object kind lists properties of the toolchains used during +the build. These include the language, compiler path, ID, and version. + +There is only one ``toolchains`` object major version, version 1. + +"toolchains" version 1 +^^^^^^^^^^^^^^^^^^^^^^ + +``toolchains`` object version 1 is a JSON object: + +.. code-block:: json + + { + "kind": "toolchains", + "version": { "major": 1, "minor": 0 }, + "toolchains": [ + { + "language": "C", + "compiler": { + "path": "/usr/bin/cc", + "id": "GNU", + "version": "9.3.0", + "implicit": { + "includeDirectories": [ + "/usr/lib/gcc/x86_64-linux-gnu/9/include", + "/usr/local/include", + "/usr/include/x86_64-linux-gnu", + "/usr/include" + ], + "linkDirectories": [ + "/usr/lib/gcc/x86_64-linux-gnu/9", + "/usr/lib/x86_64-linux-gnu", + "/usr/lib", + "/lib/x86_64-linux-gnu", + "/lib" + ], + "linkFrameworkDirectories": [], + "linkLibraries": [ "gcc", "gcc_s", "c", "gcc", "gcc_s" ] + } + }, + "sourceFileExtensions": [ "c", "m" ] + }, + { + "language": "CXX", + "compiler": { + "path": "/usr/bin/c++", + "id": "GNU", + "version": "9.3.0", + "implicit": { + "includeDirectories": [ + "/usr/include/c++/9", + "/usr/include/x86_64-linux-gnu/c++/9", + "/usr/include/c++/9/backward", + "/usr/lib/gcc/x86_64-linux-gnu/9/include", + "/usr/local/include", + "/usr/include/x86_64-linux-gnu", + "/usr/include" + ], + "linkDirectories": [ + "/usr/lib/gcc/x86_64-linux-gnu/9", + "/usr/lib/x86_64-linux-gnu", + "/usr/lib", + "/lib/x86_64-linux-gnu", + "/lib" + ], + "linkFrameworkDirectories": [], + "linkLibraries": [ + "stdc++", "m", "gcc_s", "gcc", "c", "gcc_s", "gcc" + ] + } + }, + "sourceFileExtensions": [ + "C", "M", "c++", "cc", "cpp", "cxx", "mm", "CPP" + ] + } + ] + } + +The members specific to ``toolchains`` objects are: + +``toolchains`` + A JSON array whose entries are each a JSON object specifying a toolchain + associated with a particular language. The members of each entry are: + + ``language`` + A JSON string specifying the toolchain language, like C or CXX. Language + names are the same as langauge names that can be passed to the + :command:`project` command. Because CMake only supports a single toolchain + per language, this field can be used as a key. + + ``compiler`` + A JSON object containing members: + + ``path`` + Optional member that is present when the + :variable:`CMAKE_<LANG>_COMPILER` variable is defined for the current + language. Its value is a JSON string holding the path to the compiler. + + ``id`` + Optional member that is present when the + :variable:`CMAKE_<LANG>_COMPILER_ID` variable is defined for the current + language. Its value is a JSON string holding the ID (GNU, MSVC, etc.) of + the compiler. + + ``version`` + Optional member that is present when the + :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable is defined for the + current language. Its value is a JSON string holding the version of the + compiler. + + ``target`` + Optional member that is present when the + :variable:`CMAKE_<LANG>_COMPILER_TARGET` variable is defined for the + current language. Its value is a JSON string holding the cross-compiling + target of the compiler. + + ``implicit`` + A JSON object containing members: + + ``includeDirectories`` + Optional member that is present when the + :variable:`CMAKE_<LANG>_IMPLICIT_INCLUDE_DIRECTORIES` variable is + defined for the current language. Its value is a JSON array of JSON + strings where each string holds a path to an implicit include + directory for the compiler. + + ``linkDirectories`` + Optional member that is present when the + :variable:`CMAKE_<LANG>_IMPLICIT_LINK_DIRECTORIES` variable is + defined for the current language. Its value is a JSON array of JSON + strings where each string holds a path to an implicit link directory + for the compiler. + + ``linkFrameworkDirectories`` + Optional member that is present when the + :variable:`CMAKE_<LANG>_IMPLICIT_LINK_FRAMEWORK_DIRECTORIES` variable + is defined for the current language. Its value is a JSON array of JSON + strings where each string holds a path to an implicit link framework + directory for the compiler. + + ``linkLibraries`` + Optional member that is present when the + :variable:`CMAKE_<LANG>_IMPLICIT_LINK_LIBRARIES` variable is defined + for the current language. Its value is a JSON array of JSON strings + where each string holds a path to an implicit link library for the + compiler. + + ``sourceFileExtensions`` + Optional member that is present when the + :variable:`CMAKE_<LANG>_SOURCE_FILE_EXTENSIONS` variable is defined for + the current language. Its value is a JSON array of JSON strings where each + each string holds a file extension (without the leading dot) for the + language. diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst new file mode 100644 index 0000000..775067a --- /dev/null +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -0,0 +1,1061 @@ +.. cmake-manual-description: CMake Generator Expressions + +cmake-generator-expressions(7) +****************************** + +.. only:: html + + .. contents:: + +Introduction +============ + +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 :prop_tgt:`LINK_LIBRARIES`, :prop_tgt:`INCLUDE_DIRECTORIES`, +:prop_tgt:`COMPILE_DEFINITIONS` and others. They may also be used when using +commands to populate those properties, such as :command:`target_link_libraries`, +:command:`target_include_directories`, :command:`target_compile_definitions` +and others. + +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. + +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. + +Generator expressions can be nested, as shown in most of the examples below. + +.. _`Boolean Generator Expressions`: + +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 +----------------- + +.. genex:: $<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``. + +.. genex:: $<AND:conditions> + + where ``conditions`` is a comma-separated list of boolean expressions. + Evaluates to ``1`` if all conditions are ``1``. + Otherwise evaluates to ``0``. + +.. genex:: $<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``. + +.. genex:: $<NOT:condition> + + ``0`` if ``condition`` is ``1``, else ``1``. + +String Comparisons +------------------ + +.. genex:: $<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", ... + +.. genex:: $<EQUAL:value1,value2> + + ``1`` if ``value1`` and ``value2`` are numerically equal, else ``0``. + +.. genex:: $<IN_LIST:string,list> + + ``1`` if ``string`` is member of the semicolon-separated ``list``, else ``0``. + Uses case-sensitive comparisons. + +.. genex:: $<VERSION_LESS:v1,v2> + + ``1`` if ``v1`` is a version less than ``v2``, else ``0``. + +.. genex:: $<VERSION_GREATER:v1,v2> + + ``1`` if ``v1`` is a version greater than ``v2``, else ``0``. + +.. genex:: $<VERSION_EQUAL:v1,v2> + + ``1`` if ``v1`` is the same version as ``v2``, else ``0``. + +.. genex:: $<VERSION_LESS_EQUAL:v1,v2> + + ``1`` if ``v1`` is a version less than or equal to ``v2``, else ``0``. + +.. genex:: $<VERSION_GREATER_EQUAL:v1,v2> + + ``1`` if ``v1`` is a version greater than or equal to ``v2``, else ``0``. + +Variable Queries +---------------- + +.. genex:: $<TARGET_EXISTS:target> + + ``1`` if ``target`` exists, else ``0``. + +.. genex:: $<CONFIG:cfgs> + + ``1`` if config is any one of the entries in ``cfgs``, 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. + +.. genex:: $<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. + +.. genex:: $<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. + +.. genex:: $<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. + +.. genex:: $<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. + +.. genex:: $<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. + +.. genex:: $<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. + +.. genex:: $<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. + +.. genex:: $<ISPC_COMPILER_ID:compiler_ids> + + where ``compiler_ids`` is a comma-separated list. + ``1`` if the CMake's compiler id of the ISPC compiler matches any one + of the entries in ``compiler_ids``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. + +.. genex:: $<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. + +.. genex:: $<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. + +.. genex:: $<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. + +.. genex:: $<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. + +.. genex:: $<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. + +.. genex:: $<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. + +.. genex:: $<ISPC_COMPILER_VERSION:version> + + ``1`` if the version of the ISPC compiler matches ``version``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. + +.. genex:: $<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. + +.. genex:: $<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. + +.. _`Boolean COMPILE_LANGUAGE Generator Expression`: + +.. genex:: $<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 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 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 + + 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> + ) + +.. genex:: $<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 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,CUDA>:/opt/foo/headers> + ) + + 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: + + .. 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) + +.. _`Boolean LINK_LANGUAGE Generator Expression`: + +.. genex:: $<LINK_LANG_AND_ID:language,compiler_ids> + + ``1`` when the language used for link step matches ``language`` and the + CMake's compiler id of the language linker matches any one of the entries + in ``compiler_ids``, otherwise ``0``. This expression is a short form for the + combination of ``$<LINK_LANGUAGE:language>`` and + ``$<LANG_COMPILER_ID:compiler_ids>``. This expression may be used to specify + link libraries, link options, link directories and link dependencies of a + particular language and linker combination in a target. For example: + + .. code-block:: cmake + + add_library(libC_Clang ...) + add_library(libCXX_Clang ...) + add_library(libC_Intel ...) + add_library(libCXX_Intel ...) + + add_executable(myapp main.c) + if (CXX_CONFIG) + target_sources(myapp PRIVATE file.cxx) + endif() + target_link_libraries(myapp + PRIVATE $<$<LINK_LANG_AND_ID:CXX,Clang,AppleClang>:libCXX_Clang> + $<$<LINK_LANG_AND_ID:C,Clang,AppleClang>:libC_Clang> + $<$<LINK_LANG_AND_ID:CXX,Intel>:libCXX_Intel> + $<$<LINK_LANG_AND_ID:C,Intel>:libC_Intel>) + + This specifies the use of different link libraries based on both the + compiler id and link language. This example will have target ``libCXX_Clang`` + as link dependency when ``Clang`` or ``AppleClang`` is the ``CXX`` + linker, and ``libCXX_Intel`` when ``Intel`` is the ``CXX`` linker. + Likewise when the ``C`` linker is ``Clang`` or ``AppleClang``, target + ``libC_Clang`` will be added as link dependency and ``libC_Intel`` when + ``Intel`` is the ``C`` linker. + + See :ref:`the note related to + <Constraints LINK_LANGUAGE Generator Expression>` + ``$<LINK_LANGUAGE:language>`` for constraints about the usage of this + generator expression. + +.. genex:: $<LINK_LANGUAGE:languages> + + ``1`` when the language used for link step matches any of the entries + in ``languages``, otherwise ``0``. This expression may be used to specify + link libraries, link options, link directories and link dependencies of a + particular language in a target. For example: + + .. code-block:: cmake + + add_library(api_C ...) + add_library(api_CXX ...) + add_library(api INTERFACE) + target_link_options(api INTERFACE $<$<LINK_LANGUAGE:C>:-opt_c> + $<$<LINK_LANGUAGE:CXX>:-opt_cxx>) + target_link_libraries(api INTERFACE $<$<LINK_LANGUAGE:C>:api_C> + $<$<LINK_LANGUAGE:CXX>:api_CXX>) + + add_executable(myapp1 main.c) + target_link_options(myapp1 PRIVATE api) + + add_executable(myapp2 main.cpp) + target_link_options(myapp2 PRIVATE api) + + This specifies to use the ``api`` target for linking targets ``myapp1`` and + ``myapp2``. In practice, ``myapp1`` will link with target ``api_C`` and + option ``-opt_c`` because it will use ``C`` as link language. And ``myapp2`` + will link with ``api_CXX`` and option ``-opt_cxx`` because ``CXX`` will be + the link language. + + .. _`Constraints LINK_LANGUAGE Generator Expression`: + + .. note:: + + To determine the link language of a target, it is required to collect, + transitively, all the targets which will be linked to it. So, for link + libraries properties, a double evaluation will be done. During the first + evaluation, ``$<LINK_LANGUAGE:..>`` expressions will always return ``0``. + The link language computed after this first pass will be used to do the + second pass. To avoid inconsistency, it is required that the second pass + do not change the link language. Moreover, to avoid unexpected + side-effects, it is required to specify complete entities as part of the + ``$<LINK_LANGUAGE:..>`` expression. For example: + + .. code-block:: cmake + + add_library(lib STATIC file.cxx) + add_library(libother STATIC file.c) + + # bad usage + add_executable(myapp1 main.c) + target_link_libraries(myapp1 PRIVATE lib$<$<LINK_LANGUAGE:C>:other>) + + # correct usage + add_executable(myapp2 main.c) + target_link_libraries(myapp2 PRIVATE $<$<LINK_LANGUAGE:C>:libother>) + + In this example, for ``myapp1``, the first pass will, unexpectedly, + determine that the link language is ``CXX`` because the evaluation of the + generator expression will be an empty string so ``myapp1`` will depends on + target ``lib`` which is ``C++``. On the contrary, for ``myapp2``, the first + evaluation will give ``C`` as link language, so the second pass will + correctly add target ``libother`` as link dependency. + +.. genex:: $<DEVICE_LINK:list> + + Returns the list if it is the device link step, an empty list otherwise. + The device link step is controlled by :prop_tgt:`CUDA_SEPARABLE_COMPILATION` + and :prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` properties and + policy :policy:`CMP0105`. This expression can only be used to specify link + options. + +.. genex:: $<HOST_LINK:list> + + Returns the list if it is the normal link step, an empty list otherwise. + This expression is mainly useful when a device link step is also involved + (see ``$<DEVICE_LINK:list>`` generator expression). This expression can only + be used to specify link options. + +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 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: + +.. code-block:: cmake + + $<$<VERSION_LESS:$<CXX_COMPILER_VERSION>,4.2.0>:OLD_COMPILER> + +expands to ``OLD_COMPILER`` if the +:variable:`CMAKE_CXX_COMPILER_VERSION <CMAKE_<LANG>_COMPILER_VERSION>` is less +than 4.2.0. + +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: + +.. genex:: $<ANGLE-R> + + A literal ``>``. Used for example to compare strings that contain a ``>``. + +.. genex:: $<COMMA> + + A literal ``,``. Used for example to compare strings which contain a ``,``. + +.. genex:: $<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``. + +.. genex:: $<condition:true_string> + + Evaluates to ``true_string`` if ``condition`` is ``1``. + Otherwise evaluates to the empty string. + +.. genex:: $<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 +---------------------- + +.. genex:: $<JOIN:list,string> + + Joins the list with the content of ``string``. + +.. genex:: $<REMOVE_DUPLICATES:list> + + Removes duplicated items in the given ``list``. + +.. genex:: $<FILTER:list,INCLUDE|EXCLUDE,regex> + + Includes or removes items from ``list`` that match the regular expression ``regex``. + +.. genex:: $<LOWER_CASE:string> + + Content of ``string`` converted to lower case. + +.. genex:: $<UPPER_CASE:string> + + Content of ``string`` converted to upper case. + +.. genex:: $<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. + +.. genex:: $<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 +---------------- + +.. genex:: $<CONFIG> + + Configuration name. + +.. genex:: $<CONFIGURATION> + + Configuration name. Deprecated since CMake 3.0. Use ``CONFIG`` instead. + +.. genex:: $<PLATFORM_ID> + + The current system's CMake platform id. + See also the :variable:`CMAKE_SYSTEM_NAME` variable. + +.. genex:: $<C_COMPILER_ID> + + The CMake's compiler id of the C compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. + +.. genex:: $<CXX_COMPILER_ID> + + The CMake's compiler id of the CXX compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. + +.. genex:: $<CUDA_COMPILER_ID> + + The CMake's compiler id of the CUDA compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. + +.. genex:: $<OBJC_COMPILER_ID> + + The CMake's compiler id of the OBJC compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. + +.. genex:: $<OBJCXX_COMPILER_ID> + + The CMake's compiler id of the OBJCXX compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. + +.. genex:: $<Fortran_COMPILER_ID> + + The CMake's compiler id of the Fortran compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. + +.. genex:: $<ISPC_COMPILER_ID> + + The CMake's compiler id of the ISPC compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. + +.. genex:: $<C_COMPILER_VERSION> + + The version of the C compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. + +.. genex:: $<CXX_COMPILER_VERSION> + + The version of the CXX compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. + +.. genex:: $<CUDA_COMPILER_VERSION> + + The version of the CUDA compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. + +.. genex:: $<OBJC_COMPILER_VERSION> + + The version of the OBJC compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. + +.. genex:: $<OBJCXX_COMPILER_VERSION> + + The version of the OBJCXX compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. + +.. genex:: $<Fortran_COMPILER_VERSION> + + The version of the Fortran compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. + +.. genex:: $<ISPC_COMPILER_VERSION> + + The version of the ISPC compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. + +.. genex:: $<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. + +.. genex:: $<LINK_LANGUAGE> + + The link language of target when evaluating link options. + See :ref:`the related boolean expression + <Boolean LINK_LANGUAGE Generator Expression>` ``$<LINK_LANGUAGE:language>`` + for notes about the portability of this generator expression. + + .. note:: + + This generator expression is not supported by the link libraries + properties to avoid side-effects due to the double evaluation of + these properties. + +.. _`Target-Dependent Queries`: + +Target-Dependent Queries +------------------------ + +These queries refer to a target ``tgt``. This can be any runtime artifact, +namely: + +* an executable target created by :command:`add_executable` +* a shared library target (``.so``, ``.dll`` but not their ``.lib`` import library) + created by :command:`add_library` +* a static library target created by :command:`add_library` + +In the following, "the ``tgt`` filename" means the name of the ``tgt`` +binary file. This has to be distinguished from "the target name", +which is just the string ``tgt``. + +.. genex:: $<TARGET_NAME_IF_EXISTS:tgt> + + The target name ``tgt`` if the target exists, an empty string otherwise. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_FILE:tgt> + + Full path to the ``tgt`` binary file. + +.. genex:: $<TARGET_FILE_BASE_NAME:tgt> + + Base name of ``tgt``, i.e. ``$<TARGET_FILE_NAME:tgt>`` without prefix and + suffix. + For example, if the ``tgt`` filename 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. + +.. genex:: $<TARGET_FILE_PREFIX:tgt> + + Prefix of the ``tgt`` filename (such as ``lib``). + + 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. + +.. genex:: $<TARGET_FILE_SUFFIX:tgt> + + Suffix of the ``tgt`` filename (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. + +.. genex:: $<TARGET_FILE_NAME:tgt> + + The ``tgt`` filename. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). + +.. genex:: $<TARGET_FILE_DIR:tgt> + + Directory of the ``tgt`` binary file. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). + +.. genex:: $<TARGET_LINKER_FILE:tgt> + + File used when linking to the ``tgt`` target. This will usually + be the library that ``tgt`` represents (``.a``, ``.lib``, ``.so``), + but for a shared library on DLL platforms, it would be the ``.lib`` + import library associated with the DLL. + +.. genex:: $<TARGET_LINKER_FILE_BASE_NAME:tgt> + + Base name of file used to link the target ``tgt``, i.e. + ``$<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. + +.. genex:: $<TARGET_LINKER_FILE_PREFIX:tgt> + + Prefix of file used to link target ``tgt``. + + 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. + +.. genex:: $<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. + +.. genex:: $<TARGET_LINKER_FILE_NAME:tgt> + + Name of file used to link target ``tgt``. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). + +.. genex:: $<TARGET_LINKER_FILE_DIR:tgt> + + Directory of file used to link target ``tgt``. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). + +.. genex:: $<TARGET_SONAME_FILE:tgt> + + File with soname (``.so.3``) where ``tgt`` is the name of a target. +.. genex:: $<TARGET_SONAME_FILE_NAME:tgt> + + Name of file with soname (``.so.3``). + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). + +.. genex:: $<TARGET_SONAME_FILE_DIR:tgt> + + Directory of with soname (``.so.3``). + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). + +.. genex:: $<TARGET_PDB_FILE:tgt> + + Full path to the linker generated program database file (.pdb) + where ``tgt`` is the name of a target. + + 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>`. + +.. genex:: $<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. + +.. genex:: $<TARGET_PDB_FILE_NAME:tgt> + + Name of the linker generated program database file (.pdb). + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). + +.. genex:: $<TARGET_PDB_FILE_DIR:tgt> + + Directory of the linker generated program database file (.pdb). + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). + +.. genex:: $<TARGET_BUNDLE_DIR:tgt> + + Full path to the bundle directory (``my.app``, ``my.framework``, or + ``my.bundle``) where ``tgt`` is the name of a target. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). + +.. genex:: $<TARGET_BUNDLE_CONTENT_DIR:tgt> + + Full path to the bundle content directory where ``tgt`` is the name of a + target. For the macOS SDK it leads to ``my.app/Contents``, ``my.framework``, + or ``my.bundle/Contents``. For all other SDKs (e.g. iOS) it leads to + ``my.app``, ``my.framework``, or ``my.bundle`` due to the flat bundle + structure. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). + +.. genex:: $<TARGET_PROPERTY:tgt,prop> + + Value of the property ``prop`` on the target ``tgt``. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_PROPERTY:prop> + + Value of the property ``prop`` on the target for which the expression + is being evaluated. Note that for generator expressions in + :ref:`Target Usage Requirements` this is the consuming target rather + than the target specifying the requirement. + +.. genex:: $<TARGET_RUNTIME_DLLS:tgt> + + List of DLLs that the target depends on at runtime. This is determined by + the locations of all the ``SHARED`` and ``MODULE`` targets in the target's + transitive dependencies. Using this generator expression on targets other + than executables, ``SHARED`` libraries, and ``MODULE`` libraries is an error. + On non-DLL platforms, it evaluates to an empty string. + + This generator expression can be used to copy all of the DLLs that a target + depends on into its output directory in a ``POST_BUILD`` custom command. For + example: + + .. code-block:: cmake + + find_package(foo REQUIRED) + + add_executable(exe main.c) + target_link_libraries(exe PRIVATE foo::foo foo::bar) + add_custom_command(TARGET exe POST_BUILD + COMMAND ${CMAKE_COMMAND} -E copy $<TARGET_RUNTIME_DLLS:exe> $<TARGET_FILE_DIR:exe> + COMMAND_EXPAND_LISTS + ) + +.. genex:: $<INSTALL_PREFIX> + + Content of the install prefix when the target is exported via + :command:`install(EXPORT)`, or when evaluated in + :prop_tgt:`INSTALL_NAME_DIR`, and empty otherwise. + +Output-Related Expressions +-------------------------- + +.. genex:: $<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 + name of a target- it may not contain generator expressions. + +.. genex:: $<LINK_ONLY:...> + + Content of ``...`` except when evaluated in a link interface while + propagating :ref:`Target Usage Requirements`, in which case it is the + empty string. + Intended for use only in an :prop_tgt:`INTERFACE_LINK_LIBRARIES` target + property, perhaps via the :command:`target_link_libraries` command, + to specify private link dependencies without other usage requirements. + +.. genex:: $<INSTALL_INTERFACE:...> + + Content of ``...`` when the property is exported using :command:`install(EXPORT)`, + and empty otherwise. + +.. genex:: $<BUILD_INTERFACE:...> + + 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. + +.. genex:: $<MAKE_C_IDENTIFIER:...> + + Content of ``...`` converted to a C identifier. The conversion follows the + same behavior as :command:`string(MAKE_C_IDENTIFIER)`. + +.. genex:: $<TARGET_OBJECTS:objLib> + + List of objects resulting from build of ``objLib``. + +.. genex:: $<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. + +.. genex:: $<OUTPUT_CONFIG:...> + + .. versionadded:: 3.20 + + Only valid in :command:`add_custom_command` and :command:`add_custom_target` + as the outer-most generator expression in an argument. + With the :generator:`Ninja Multi-Config` generator, generator expressions + in ``...`` are evaluated using the custom command's "output config". + With other generators, the content of ``...`` is evaluated normally. + +.. genex:: $<COMMAND_CONFIG:...> + + .. versionadded:: 3.20 + + Only valid in :command:`add_custom_command` and :command:`add_custom_target` + as the outer-most generator expression in an argument. + With the :generator:`Ninja Multi-Config` generator, generator expressions + in ``...`` are evaluated using the custom command's "command config". + With other generators, the content of ``...`` is evaluated normally. + +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 new file mode 100644 index 0000000..8ca2bf6 --- /dev/null +++ b/Help/manual/cmake-generators.7.rst @@ -0,0 +1,120 @@ +.. cmake-manual-description: CMake Generators Reference + +cmake-generators(7) +******************* + +.. only:: html + + .. contents:: + +Introduction +============ + +A *CMake Generator* is responsible for writing the input files for +a native build system. Exactly one of the `CMake Generators`_ must be +selected for a build tree to determine what native build system is to +be used. Optionally one of the `Extra Generators`_ may be selected +as a variant of some of the `Command-Line Build Tool Generators`_ to +produce project files for an auxiliary IDE. + +CMake Generators are platform-specific so each may be available only +on certain platforms. The :manual:`cmake(1)` command-line tool ``--help`` +output lists available generators on the current platform. Use its ``-G`` +option to specify the generator for a new build tree. +The :manual:`cmake-gui(1)` offers interactive selection of a generator +when creating a new build tree. + +CMake Generators +================ + +.. _`Command-Line Build Tool Generators`: + +Command-Line Build Tool Generators +---------------------------------- + +These generators support command-line build tools. In order to use them, +one must launch CMake from a command-line prompt whose environment is +already configured for the chosen compiler and build tool. + +.. _`Makefile Generators`: + +Makefile Generators +^^^^^^^^^^^^^^^^^^^ + +.. toctree:: + :maxdepth: 1 + + /generator/Borland Makefiles + /generator/MSYS Makefiles + /generator/MinGW Makefiles + /generator/NMake Makefiles + /generator/NMake Makefiles JOM + /generator/Unix Makefiles + /generator/Watcom WMake + +.. _`Ninja Generators`: + +Ninja Generators +^^^^^^^^^^^^^^^^ + +.. toctree:: + :maxdepth: 1 + + /generator/Ninja + /generator/Ninja Multi-Config + +.. _`IDE Build Tool Generators`: + +IDE Build Tool Generators +------------------------- + +These generators support Integrated Development Environment (IDE) +project files. Since the IDEs configure their own environment +one may launch CMake from any environment. + +.. _`Visual Studio Generators`: + +Visual Studio Generators +^^^^^^^^^^^^^^^^^^^^^^^^ + +.. toctree:: + :maxdepth: 1 + + /generator/Visual Studio 6 + /generator/Visual Studio 7 + /generator/Visual Studio 7 .NET 2003 + /generator/Visual Studio 8 2005 + /generator/Visual Studio 9 2008 + /generator/Visual Studio 10 2010 + /generator/Visual Studio 11 2012 + /generator/Visual Studio 12 2013 + /generator/Visual Studio 14 2015 + /generator/Visual Studio 15 2017 + /generator/Visual Studio 16 2019 + +Other Generators +^^^^^^^^^^^^^^^^ + +.. toctree:: + :maxdepth: 1 + + /generator/Green Hills MULTI + /generator/Xcode + +Extra Generators +================ + +Some of the `CMake Generators`_ listed in the :manual:`cmake(1)` +command-line tool ``--help`` output may have variants that specify +an extra generator for an auxiliary IDE tool. Such generator +names have the form ``<extra-generator> - <main-generator>``. +The following extra generators are known to CMake. + +.. toctree:: + :maxdepth: 1 + + /generator/CodeBlocks + /generator/CodeLite + /generator/Eclipse CDT4 + /generator/Kate + /generator/Sublime Text 2 diff --git a/Help/manual/cmake-gui.1.rst b/Help/manual/cmake-gui.1.rst new file mode 100644 index 0000000..281986f --- /dev/null +++ b/Help/manual/cmake-gui.1.rst @@ -0,0 +1,52 @@ +.. cmake-manual-description: CMake GUI Command-Line Reference + +cmake-gui(1) +************ + +Synopsis +======== + +.. parsed-literal:: + + cmake-gui [<options>] + cmake-gui [<options>] {<path-to-source> | <path-to-existing-build>} + cmake-gui [<options>] -S <path-to-source> -B <path-to-build> + cmake-gui [<options>] --browse-manual + +Description +=========== + +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``. +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. + +``--preset=<preset-name>`` + Name of the preset to use from the project's + :manual:`presets <cmake-presets(7)>` files, if it has them. + +``--browse-manual`` + Open the CMake reference manual in a browser and immediately exit. + +.. include:: OPTIONS_HELP.txt + +See Also +======== + +.. include:: LINKS.txt diff --git a/Help/manual/cmake-language.7.rst b/Help/manual/cmake-language.7.rst new file mode 100644 index 0000000..b7f0861 --- /dev/null +++ b/Help/manual/cmake-language.7.rst @@ -0,0 +1,629 @@ +.. cmake-manual-description: CMake Language Reference + +cmake-language(7) +***************** + +.. only:: html + + .. contents:: + +Organization +============ + +CMake input files are written in the "CMake Language" in source files +named ``CMakeLists.txt`` or ending in a ``.cmake`` file name extension. + +CMake Language source files in a project are organized into: + +* `Directories`_ (``CMakeLists.txt``), +* `Scripts`_ (``<script>.cmake``), and +* `Modules`_ (``<module>.cmake``). + +Directories +----------- + +When CMake processes a project source tree, the entry point is +a source file called ``CMakeLists.txt`` in the top-level source +directory. This file may contain the entire build specification +or use the :command:`add_subdirectory` command to add subdirectories +to the build. Each subdirectory added by the command must also +contain a ``CMakeLists.txt`` file as the entry point to that +directory. For each source directory whose ``CMakeLists.txt`` file +is processed CMake generates a corresponding directory in the build +tree to act as the default working and output directory. + +Scripts +------- + +An individual ``<script>.cmake`` source file may be processed +in *script mode* by using the :manual:`cmake(1)` command-line tool +with the ``-P`` option. Script mode simply runs the commands in +the given CMake Language source file and does not generate a +build system. It does not allow CMake commands that define build +targets or actions. + +Modules +------- + +CMake Language code in either `Directories`_ or `Scripts`_ may +use the :command:`include` command to load a ``<module>.cmake`` +source file in the scope of the including context. +See the :manual:`cmake-modules(7)` manual page for documentation +of modules included with the CMake distribution. +Project source trees may also provide their own modules and +specify their location(s) in the :variable:`CMAKE_MODULE_PATH` +variable. + +Syntax +====== + +.. _`CMake Language Encoding`: + +Encoding +-------- + +A CMake Language source file may be written in 7-bit ASCII text for +maximum portability across all supported platforms. Newlines may be +encoded as either ``\n`` or ``\r\n`` but will be converted to ``\n`` +as input files are read. + +Note that the implementation is 8-bit clean so source files may +be encoded as UTF-8 on platforms with system APIs supporting this +encoding. In addition, CMake 3.2 and above support source files +encoded in UTF-8 on Windows (using UTF-16 to call system APIs). +Furthermore, CMake 3.0 and above allow a leading UTF-8 +`Byte-Order Mark`_ in source files. + +.. _`Byte-Order Mark`: http://en.wikipedia.org/wiki/Byte_order_mark + +Source Files +------------ + +A CMake Language source file consists of zero or more +`Command Invocations`_ separated by newlines and optionally +spaces and `Comments`_: + +.. raw:: latex + + \begin{small} + +.. productionlist:: + file: `file_element`* + file_element: `command_invocation` `line_ending` | + : (`bracket_comment`|`space`)* `line_ending` + line_ending: `line_comment`? `newline` + space: <match '[ \t]+'> + newline: <match '\n'> + +.. raw:: latex + + \end{small} + +Note that any source file line not inside `Command Arguments`_ or +a `Bracket Comment`_ can end in a `Line Comment`_. + +.. _`Command Invocations`: + +Command Invocations +------------------- + +A *command invocation* is a name followed by paren-enclosed arguments +separated by whitespace: + +.. raw:: latex + + \begin{small} + +.. productionlist:: + command_invocation: `space`* `identifier` `space`* '(' `arguments` ')' + identifier: <match '[A-Za-z_][A-Za-z0-9_]*'> + arguments: `argument`? `separated_arguments`* + separated_arguments: `separation`+ `argument`? | + : `separation`* '(' `arguments` ')' + separation: `space` | `line_ending` + +.. raw:: latex + + \end{small} + +For example: + +.. code-block:: cmake + + add_executable(hello world.c) + +Command names are case-insensitive. +Nested unquoted parentheses in the arguments must balance. +Each ``(`` or ``)`` is given to the command invocation as +a literal `Unquoted Argument`_. This may be used in calls +to the :command:`if` command to enclose conditions. +For example: + +.. code-block:: cmake + + if(FALSE AND (FALSE OR TRUE)) # evaluates to FALSE + +.. note:: + CMake versions prior to 3.0 require command name identifiers + to be at least 2 characters. + + CMake versions prior to 2.8.12 silently accept an `Unquoted Argument`_ + or a `Quoted Argument`_ immediately following a `Quoted Argument`_ and + not separated by any whitespace. For compatibility, CMake 2.8.12 and + higher accept such code but produce a warning. + +Command Arguments +----------------- + +There are three types of arguments within `Command Invocations`_: + +.. raw:: latex + + \begin{small} + +.. productionlist:: + argument: `bracket_argument` | `quoted_argument` | `unquoted_argument` + +.. raw:: latex + + \end{small} + +.. _`Bracket Argument`: + +Bracket Argument +^^^^^^^^^^^^^^^^ + +A *bracket argument*, inspired by `Lua`_ long bracket syntax, +encloses content between opening and closing "brackets" of the +same length: + +.. raw:: latex + + \begin{small} + +.. productionlist:: + bracket_argument: `bracket_open` `bracket_content` `bracket_close` + 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 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. + +Bracket argument content consists of all text between the opening +and closing brackets, except that one newline immediately following +the opening bracket, if any, is ignored. No evaluation of the +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. + +.. No code-block syntax highlighting in the following example + (long string literal not supported by our cmake.py) + +For example:: + + message([=[ + This is the first line in a bracket argument with bracket length 1. + No \-escape sequences or ${variable} references are evaluated. + This is always one argument even though it contains a ; character. + The text does not end on a closing bracket of length 0 like ]]. + It does end in a closing bracket of length 1. + ]=]) + +.. note:: + CMake versions prior to 3.0 do not support bracket arguments. + They interpret the opening bracket as the start of an + `Unquoted Argument`_. + +.. _`Lua`: http://www.lua.org/ + +.. _`Quoted Argument`: + +Quoted Argument +^^^^^^^^^^^^^^^ + +A *quoted argument* encloses content between opening and closing +double-quote characters: + +.. raw:: latex + + \begin{small} + +.. productionlist:: + quoted_argument: '"' `quoted_element`* '"' + quoted_element: <any character except '\' or '"'> | + : `escape_sequence` | + : `quoted_continuation` + quoted_continuation: '\' `newline` + +.. raw:: latex + + \end{small} + +Quoted argument content consists of all text between opening and +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. + ") + +.. 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 +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.\ + ") + +.. note:: + CMake versions prior to 3.0 do not support continuation with ``\``. + They report errors in quoted arguments containing lines ending in + an odd number of ``\`` characters. + +.. _`Unquoted Argument`: + +Unquoted Argument +^^^^^^^^^^^^^^^^^ + +An *unquoted argument* is not enclosed by any quoting syntax. +It may not contain any whitespace, ``(``, ``)``, ``#``, ``"``, or ``\`` +except when escaped by a backslash: + +.. raw:: latex + + \begin{small} + +.. productionlist:: + unquoted_argument: `unquoted_element`+ | `unquoted_legacy` + unquoted_element: <any character except whitespace or one of '()#"\'> | + : `escape_sequence` + unquoted_legacy: <see note in text> + +.. raw:: latex + + \end{small} + +Unquoted argument content consists of all text in a contiguous block +of allowed or escaped characters. Both `Escape Sequences`_ and +`Variable References`_ are evaluated. The resulting value is divided +in the same way `Lists`_ divide into elements. Each non-empty element +is given to the command invocation as an argument. Therefore an +unquoted argument may be given to a command invocation as zero or +more arguments. + +For example: + +.. code-block:: cmake + + foreach(arg + NoSpace + Escaped\ Space + This;Divides;Into;Five;Arguments + Escaped\;Semicolon + ) + message("${arg}") + endforeach() + +.. note:: + To support legacy CMake code, unquoted arguments may also contain + double-quoted strings (``"..."``, possibly enclosing horizontal + whitespace), and make-style variable references (``$(MAKEVAR)``). + + Unescaped double-quotes must balance, may not appear at the + 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 + of a single argument (rather than as separate ``$``, ``(``, + ``MAKEVAR``, and ``)`` arguments). + + The above "unquoted_legacy" production represents such arguments. + We do not recommend using legacy unquoted arguments in new code. + Instead use a `Quoted Argument`_ or a `Bracket Argument`_ to + represent the content. + +.. _`Escape Sequences`: + +Escape Sequences +---------------- + +An *escape sequence* is a ``\`` followed by one character: + +.. raw:: latex + + \begin{small} + +.. productionlist:: + escape_sequence: `escape_identity` | `escape_encoded` | `escape_semicolon` + escape_identity: '\' <match '[^A-Za-z0-9;]'> + escape_encoded: '\t' | '\r' | '\n' + escape_semicolon: '\;' + +.. raw:: latex + + \end{small} + +A ``\`` followed by a non-alphanumeric character simply encodes the literal +character without interpreting it as syntax. A ``\t``, ``\r``, or ``\n`` +encodes a tab, carriage return, or newline character, respectively. A ``\;`` +outside of any `Variable References`_ encodes itself but may be used in an +`Unquoted Argument`_ to encode the ``;`` without dividing the argument +value on it. A ``\;`` inside `Variable References`_ encodes the literal +``;`` character. (See also policy :policy:`CMP0053` documentation for +historical considerations.) + +.. _`Variable References`: + +Variable References +------------------- + +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. +Variable references can nest and are evaluated from the +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 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{<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 +-------- + +A comment starts with a ``#`` character that is not inside a +`Bracket Argument`_, `Quoted Argument`_, or escaped with ``\`` +as part of an `Unquoted Argument`_. There are two types of +comments: a `Bracket Comment`_ and a `Line Comment`_. + +.. _`Bracket Comment`: + +Bracket Comment +^^^^^^^^^^^^^^^ + +A ``#`` immediately followed by a :token:`bracket_open` forms a +*bracket comment* consisting of the entire bracket enclosure: + +.. raw:: latex + + \begin{small} + +.. productionlist:: + bracket_comment: '#' `bracket_argument` + +.. raw:: latex + + \end{small} + +For example: + +:: + + #[[This is a bracket comment. + It runs until the close bracket.]] + message("First Argument\n" #[[Bracket Comment]] "Second Argument") + +.. note:: + CMake versions prior to 3.0 do not support bracket comments. + They interpret the opening ``#`` as the start of a `Line Comment`_. + +.. _`Line Comment`: + +Line Comment +^^^^^^^^^^^^ + +A ``#`` not immediately followed by a :token:`bracket_open` forms a +*line comment* that runs until the end of the line: + +.. raw:: latex + + \begin{small} + +.. productionlist:: + line_comment: '#' <any text not starting in a `bracket_open` + : and not containing a `newline`> + +.. raw:: latex + + \end{small} + +For example: + +.. code-block:: cmake + + # This is a line comment. + message("First Argument\n" # This is a line comment :) + "Second Argument") # This is a line comment. + +Control Structures +================== + +Conditional Blocks +------------------ + +The :command:`if`/:command:`elseif`/:command:`else`/:command:`endif` +commands delimit code blocks to be executed conditionally. + +Loops +----- + +The :command:`foreach`/:command:`endforeach` and +:command:`while`/:command:`endwhile` commands delimit code +blocks to be executed in a loop. Inside such blocks the +:command:`break` command may be used to terminate the loop +early whereas the :command:`continue` command may be used +to start with the next iteration immediately. + +Command Definitions +------------------- + +The :command:`macro`/:command:`endmacro`, and +:command:`function`/:command:`endfunction` commands delimit +code blocks to be recorded for later invocation as commands. + +.. _`CMake Language Variables`: + +Variables +========= + +Variables are the basic unit of storage in the CMake Language. +Their values are always of string type, though some commands may +interpret the strings as values of other types. +The :command:`set` and :command:`unset` commands explicitly +set or unset a variable, but other commands have semantics +that modify variables as well. +Variable names are case-sensitive and may consist of almost +any text, but we recommend sticking to names consisting only +of alphanumeric characters plus ``_`` and ``-``. + +Variables have dynamic scope. Each variable "set" or "unset" +creates a binding in the current scope: + +Function Scope + `Command Definitions`_ created by the :command:`function` command + 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 within it, but not after the function returns. + +Directory Scope + Each of the `Directories`_ in a source tree has its own variable + bindings. Before processing the ``CMakeLists.txt`` file for a + directory, CMake copies all variable bindings currently defined + in the parent directory, if any, to initialize the new directory + scope. CMake `Scripts`_, when processed with ``cmake -P``, bind + variables in one "directory" scope. + + A variable "set" or "unset" not inside a function call binds + to the current directory scope. + +Persistent Cache + CMake stores a separate set of "cache" variables, or "cache entries", + whose values persist across multiple runs within a project build + tree. Cache entries have an isolated binding scope modified only + by explicit request, such as by the ``CACHE`` option of the + :command:`set` and :command:`unset` commands. + +When evaluating `Variable References`_, CMake first searches the +function call stack, if any, for a binding and then falls back +to the binding in the current directory scope, if any. If a +"set" binding is found, its value is used. If an "unset" binding +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 the many variables +that are provided by CMake or have meaning to CMake when set +by project code. + +.. include:: ID_RESERVE.txt + +.. _`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 +===== + +Although all values in CMake are stored as strings, a string +may be treated as a list in certain contexts, such as during +evaluation of an `Unquoted Argument`_. In such contexts, a string +is divided into list elements by splitting on ``;`` characters not +following an unequal number of ``[`` and ``]`` characters and not +immediately preceded by a ``\``. The sequence ``\;`` does not +divide a value but is replaced by ``;`` in the resulting element. + +A list of elements is represented as a string by concatenating +the elements separated by ``;``. For example, the :command:`set` +command stores multiple values into the destination variable +as a list: + +.. code-block:: cmake + + set(srcs a.c b.c c.c) # sets "srcs" to "a.c;b.c;c.c" + +Lists are meant for simple use cases such as a list of source +files and should not be used for complex data processing tasks. +Most commands that construct lists do not escape ``;`` characters +in list elements, thus flattening nested lists: + +.. code-block:: cmake + + set(x a "b;c") # sets "x" to "a;b;c", not "a;b\;c" diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst new file mode 100644 index 0000000..17c1a1e --- /dev/null +++ b/Help/manual/cmake-modules.7.rst @@ -0,0 +1,322 @@ +.. cmake-manual-description: CMake Modules Reference + +cmake-modules(7) +**************** + +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. + +Utility Modules +^^^^^^^^^^^^^^^ + +These modules are loaded using the :command:`include` command. + +.. toctree:: + :maxdepth: 1 + + /module/AndroidTestUtilities + /module/BundleUtilities + /module/CheckCCompilerFlag + /module/CheckCompilerFlag + /module/CheckCSourceCompiles + /module/CheckCSourceRuns + /module/CheckCXXCompilerFlag + /module/CheckCXXSourceCompiles + /module/CheckCXXSourceRuns + /module/CheckCXXSymbolExists + /module/CheckFortranCompilerFlag + /module/CheckFortranFunctionExists + /module/CheckFortranSourceCompiles + /module/CheckFortranSourceRuns + /module/CheckFunctionExists + /module/CheckIncludeFileCXX + /module/CheckIncludeFile + /module/CheckIncludeFiles + /module/CheckIPOSupported + /module/CheckLanguage + /module/CheckLibraryExists + /module/CheckLinkerFlag + /module/CheckOBJCCompilerFlag + /module/CheckOBJCSourceCompiles + /module/CheckOBJCSourceRuns + /module/CheckOBJCXXCompilerFlag + /module/CheckOBJCXXSourceCompiles + /module/CheckOBJCXXSourceRuns + /module/CheckPIESupported + /module/CheckPrototypeDefinition + /module/CheckSourceCompiles + /module/CheckSourceRuns + /module/CheckStructHasMember + /module/CheckSymbolExists + /module/CheckTypeSize + /module/CheckVariableExists + /module/CMakeAddFortranSubdirectory + /module/CMakeBackwardCompatibilityCXX + /module/CMakeDependentOption + /module/CMakeFindDependencyMacro + /module/CMakeFindFrameworks + /module/CMakeFindPackageMode + /module/CMakeGraphVizOptions + /module/CMakePackageConfigHelpers + /module/CMakePrintHelpers + /module/CMakePrintSystemInformation + /module/CMakePushCheckState + /module/CMakeVerifyManifest + /module/CPack + /module/CPackComponent + /module/CPackIFW + /module/CPackIFWConfigureFile + /module/CSharpUtilities + /module/CTest + /module/CTestCoverageCollectGCOV + /module/CTestScriptMode + /module/CTestUseLaunchers + /module/Dart + /module/DeployQt4 + /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/UseJava + /module/UseSWIG + /module/UsewxWidgets + +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 + /module/FindAVIFile + /module/FindBacktrace + /module/FindBISON + /module/FindBLAS + /module/FindBoost + /module/FindBullet + /module/FindBZip2 + /module/FindCABLE + /module/FindCoin3D + /module/FindCUDAToolkit + /module/FindCups + /module/FindCURL + /module/FindCurses + /module/FindCVS + /module/FindCxxTest + /module/FindCygwin + /module/FindDart + /module/FindDCMTK + /module/FindDevIL + /module/FindDoxygen + /module/FindEnvModules + /module/FindEXPAT + /module/FindFLEX + /module/FindFLTK + /module/FindFLTK2 + /module/FindFontconfig + /module/FindFreetype + /module/FindGCCXML + /module/FindGDAL + /module/FindGettext + /module/FindGIF + /module/FindGit + /module/FindGLEW + /module/FindGLUT + /module/FindGnuplot + /module/FindGnuTLS + /module/FindGSL + /module/FindGTest + /module/FindGTK + /module/FindGTK2 + /module/FindHDF5 + /module/FindHg + /module/FindHSPELL + /module/FindHTMLHelp + /module/FindIce + /module/FindIconv + /module/FindIcotool + /module/FindICU + /module/FindImageMagick + /module/FindIntl + /module/FindITK + /module/FindJasper + /module/FindJava + /module/FindJNI + /module/FindJPEG + /module/FindKDE3 + /module/FindKDE4 + /module/FindLAPACK + /module/FindLATEX + /module/FindLibArchive + /module/FindLibinput + /module/FindLibLZMA + /module/FindLibXml2 + /module/FindLibXslt + /module/FindLTTngUST + /module/FindLua + /module/FindLua50 + /module/FindLua51 + /module/FindMatlab + /module/FindMFC + /module/FindMotif + /module/FindMPEG + /module/FindMPEG2 + /module/FindMPI + /module/FindODBC + /module/FindOpenACC + /module/FindOpenAL + /module/FindOpenCL + /module/FindOpenGL + /module/FindOpenMP + /module/FindOpenSceneGraph + /module/FindOpenSSL + /module/FindOpenThreads + /module/Findosg + /module/Findosg_functions + /module/FindosgAnimation + /module/FindosgDB + /module/FindosgFX + /module/FindosgGA + /module/FindosgIntrospection + /module/FindosgManipulator + /module/FindosgParticle + /module/FindosgPresentation + /module/FindosgProducer + /module/FindosgQt + /module/FindosgShadow + /module/FindosgSim + /module/FindosgTerrain + /module/FindosgText + /module/FindosgUtil + /module/FindosgViewer + /module/FindosgVolume + /module/FindosgWidget + /module/FindPatch + /module/FindPerl + /module/FindPerlLibs + /module/FindPHP4 + /module/FindPhysFS + /module/FindPike + /module/FindPkgConfig + /module/FindPNG + /module/FindPostgreSQL + /module/FindProducer + /module/FindProtobuf + /module/FindPython + /module/FindPython2 + /module/FindPython3 + /module/FindQt3 + /module/FindQt4 + /module/FindQuickTime + /module/FindRTI + /module/FindRuby + /module/FindSDL + /module/FindSDL_image + /module/FindSDL_mixer + /module/FindSDL_net + /module/FindSDL_sound + /module/FindSDL_ttf + /module/FindSelfPackers + /module/FindSquish + /module/FindSQLite3 + /module/FindSubversion + /module/FindSWIG + /module/FindTCL + /module/FindTclsh + /module/FindTclStub + /module/FindThreads + /module/FindTIFF + /module/FindUnixCommands + /module/FindVTK + /module/FindVulkan + /module/FindWget + /module/FindWish + /module/FindwxWidgets + /module/FindX11 + /module/FindXalanC + /module/FindXCTest + /module/FindXercesC + /module/FindXMLRPC + /module/FindZLIB + +Deprecated Modules +^^^^^^^^^^^^^^^^^^^ + +Deprecated Utility Modules +========================== + +.. toctree:: + :maxdepth: 1 + + /module/AddFileDependencies + /module/CMakeDetermineVSServicePack + /module/CMakeExpandImportedTargets + /module/CMakeForceCompiler + /module/CMakeParseArguments + /module/Documentation + /module/MacroAddFileDependencies + /module/TestCXXAcceptsFlag + /module/UseJavaClassFilelist + /module/UseJavaSymlinks + /module/UsePkgConfig + /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 new file mode 100644 index 0000000..4b2934a --- /dev/null +++ b/Help/manual/cmake-packages.7.rst @@ -0,0 +1,719 @@ +.. cmake-manual-description: CMake Packages Reference + +cmake-packages(7) +***************** + +.. only:: html + + .. contents:: + +Introduction +============ + +Packages provide dependency information to CMake based buildsystems. Packages +are found with the :command:`find_package` command. The result of +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 +============== + +CMake provides direct support for two forms of packages, +`Config-file Packages`_ and `Find-module Packages`_. +Indirect support for ``pkg-config`` packages is also provided via +the :module:`FindPkgConfig` module. In all cases, the basic form +of :command:`find_package` calls is the same: + +.. code-block:: cmake + + find_package(Qt4 4.7.0 REQUIRED) # CMake provides a Qt4 find-module + find_package(Qt5Core 5.1.0 REQUIRED) # Qt provides a Qt5 package config file. + find_package(LibXml2 REQUIRED) # Use pkg-config via the LibXml2 find-module + +In cases where it is known that a package configuration file is provided by +upstream, and only that should be used, the ``CONFIG`` keyword may be passed +to :command:`find_package`: + +.. code-block:: cmake + + find_package(Qt5Core 5.1.0 CONFIG REQUIRED) + find_package(Qt5Gui 5.1.0 CONFIG) + +Similarly, the ``MODULE`` keyword says to use only a find-module: + +.. code-block:: cmake + + find_package(Qt4 4.7.0 MODULE REQUIRED) + +Specifying the type of package explicitly improves the error message shown to +the user if it is not found. + +Both types of packages also support specifying components of a package, +either after the ``REQUIRED`` keyword: + +.. code-block:: cmake + + find_package(Qt5 5.1.0 CONFIG REQUIRED Widgets Xml Sql) + +or as a separate ``COMPONENTS`` list: + +.. code-block:: cmake + + find_package(Qt5 5.1.0 COMPONENTS Widgets Xml Sql) + +or as a separate ``OPTIONAL_COMPONENTS`` list: + +.. code-block:: cmake + + find_package(Qt5 5.1.0 COMPONENTS Widgets + OPTIONAL_COMPONENTS Xml Sql + ) + +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 +be ``NOTFOUND``. + +.. _`Config File Packages`: + +Config-file Packages +-------------------- + +A config-file package is a set of files provided by upstreams for downstreams +to use. CMake searches in a number of locations for package configuration files, as +described in the :command:`find_package` documentation. The most simple way for +a CMake user to tell :manual:`cmake(1)` to search in a non-standard prefix for +a package is to set the ``CMAKE_PREFIX_PATH`` cache variable. + +Config-file packages are provided by upstream vendors as part of development +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 ``<PackageName>_FOUND`` +variable is set to true or false, depending on whether the package was +found. The ``<PackageName>_DIR`` cache variable is set to the location of the +package configuration file. + +Find-module Packages +-------------------- + +A find module is a file with a set of rules for finding the required pieces of +a dependency, primarily header files and libraries. Typically, a find module +is needed when the upstream is not built with CMake, or is not CMake-aware +enough to otherwise provide a package configuration file. Unlike a package configuration +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 ``<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 ``<PackageName>_DIR`` variable, +but each of the artifacts such as library locations and header file locations +provide a separate cache variable. + +See the :manual:`cmake-developer(7)` manual for more information about creating +Find-module files. + +Package Layout +============== + +A config-file package consists of a `Package Configuration File`_ and +optionally a `Package Version File`_ provided with the project distribution. + +Package Configuration File +-------------------------- + +Consider a project ``Foo`` that installs the following files:: + + <prefix>/include/foo-1.2/foo.h + <prefix>/lib/foo-1.2/libfoo.a + +It may also provide a CMake package configuration file:: + + <prefix>/lib/cmake/foo-1.2/FooConfig.cmake + +with content defining :prop_tgt:`IMPORTED` targets, or defining variables, such +as: + +.. code-block:: cmake + + # ... + # (compute PREFIX relative to file location) + # ... + set(Foo_INCLUDE_DIRS ${PREFIX}/include/foo-1.2) + set(Foo_LIBRARIES ${PREFIX}/lib/foo-1.2/libfoo.a) + +If another project wishes to use ``Foo`` it need only to locate the ``FooConfig.cmake`` +file and load it to get all the information it needs about package content +locations. Since the package configuration file is provided by the package +installation it already knows all the file locations. + +The :command:`find_package` command may be used to search for the package +configuration file. This command constructs a set of installation prefixes +and searches under each prefix in several locations. Given the name ``Foo``, +it looks for a file called ``FooConfig.cmake`` or ``foo-config.cmake``. +The full set of locations is specified in the :command:`find_package` command +documentation. One place it looks is:: + + <prefix>/lib/cmake/Foo*/ + +where ``Foo*`` is a case-insensitive globbing expression. In our example the +globbing expression will match ``<prefix>/lib/cmake/foo-1.2`` and the package +configuration file will be found. + +Once found, a package configuration file is immediately loaded. It, together +with a package version file, contains all the information the project needs to +use the package. + +Package Version File +-------------------- + +When the :command:`find_package` command finds a candidate package configuration +file it looks next to it for a version file. The version file is loaded to test +whether the package version is an acceptable match for the version requested. +If the version file claims compatibility the configuration file is accepted. +Otherwise it is ignored. + +The name of the package version file must match that of the package configuration +file but has either ``-version`` or ``Version`` appended to the name before +the ``.cmake`` extension. For example, the files:: + + <prefix>/lib/cmake/foo-1.3/foo-config.cmake + <prefix>/lib/cmake/foo-1.3/foo-config-version.cmake + +and:: + + <prefix>/lib/cmake/bar-4.2/BarConfig.cmake + <prefix>/lib/cmake/bar-4.2/BarConfigVersion.cmake + +are each pairs of package configuration files and corresponding package version +files. + +When the :command:`find_package` command loads a version file it first sets the +following variables: + +``PACKAGE_FIND_NAME`` + The ``<PackageName>`` + +``PACKAGE_FIND_VERSION`` + Full requested version string + +``PACKAGE_FIND_VERSION_MAJOR`` + Major version if requested, else 0 + +``PACKAGE_FIND_VERSION_MINOR`` + Minor version if requested, else 0 + +``PACKAGE_FIND_VERSION_PATCH`` + Patch version if requested, else 0 + +``PACKAGE_FIND_VERSION_TWEAK`` + Tweak version if requested, else 0 + +``PACKAGE_FIND_VERSION_COUNT`` + Number of version components, 0 to 4 + +The version file must use these variables to check whether it is compatible or +an exact match for the requested version and set the following variables with +results: + +``PACKAGE_VERSION`` + Full provided version string + +``PACKAGE_VERSION_EXACT`` + True if version is exact match + +``PACKAGE_VERSION_COMPATIBLE`` + True if version is compatible + +``PACKAGE_VERSION_UNSUITABLE`` + True if unsuitable as any version + +Version files are loaded in a nested scope so they are free to set any variables +they wish as part of their computation. The find_package command wipes out the +scope when the version file has completed and it has checked the output +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: + +``<PackageName>_VERSION`` + Full provided version string + +``<PackageName>_VERSION_MAJOR`` + Major version if provided, else 0 + +``<PackageName>_VERSION_MINOR`` + Minor version if provided, else 0 + +``<PackageName>_VERSION_PATCH`` + Patch version if provided, else 0 + +``<PackageName>_VERSION_TWEAK`` + Tweak version if provided, else 0 + +``<PackageName>_VERSION_COUNT`` + Number of version components, 0 to 4 + +The variables report the version of the package that was actually found. +The ``<PackageName>`` part of their name matches the argument given to the +:command:`find_package` command. + +.. _`Creating Packages`: + +Creating Packages +================= + +Usually, the upstream depends on CMake itself and can use some CMake facilities +for creating the package files. Consider an upstream which provides a single +shared library: + +.. code-block:: cmake + + project(UpstreamLib) + + set(CMAKE_INCLUDE_CURRENT_DIR ON) + set(CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE ON) + + set(Upstream_VERSION 3.4.1) + + include(GenerateExportHeader) + + add_library(ClimbingStats SHARED climbingstats.cpp) + generate_export_header(ClimbingStats) + set_property(TARGET ClimbingStats PROPERTY VERSION ${Upstream_VERSION}) + set_property(TARGET ClimbingStats PROPERTY SOVERSION 3) + set_property(TARGET ClimbingStats PROPERTY + INTERFACE_ClimbingStats_MAJOR_VERSION 3) + set_property(TARGET ClimbingStats APPEND PROPERTY + COMPATIBLE_INTERFACE_STRING ClimbingStats_MAJOR_VERSION + ) + + install(TARGETS ClimbingStats EXPORT ClimbingStatsTargets + LIBRARY DESTINATION lib + ARCHIVE DESTINATION lib + RUNTIME DESTINATION bin + INCLUDES DESTINATION include + ) + install( + FILES + climbingstats.h + "${CMAKE_CURRENT_BINARY_DIR}/climbingstats_export.h" + DESTINATION + include + COMPONENT + Devel + ) + + include(CMakePackageConfigHelpers) + write_basic_package_version_file( + "${CMAKE_CURRENT_BINARY_DIR}/ClimbingStats/ClimbingStatsConfigVersion.cmake" + VERSION ${Upstream_VERSION} + COMPATIBILITY AnyNewerVersion + ) + + export(EXPORT ClimbingStatsTargets + FILE "${CMAKE_CURRENT_BINARY_DIR}/ClimbingStats/ClimbingStatsTargets.cmake" + NAMESPACE Upstream:: + ) + configure_file(cmake/ClimbingStatsConfig.cmake + "${CMAKE_CURRENT_BINARY_DIR}/ClimbingStats/ClimbingStatsConfig.cmake" + COPYONLY + ) + + set(ConfigPackageLocation lib/cmake/ClimbingStats) + install(EXPORT ClimbingStatsTargets + FILE + ClimbingStatsTargets.cmake + NAMESPACE + Upstream:: + DESTINATION + ${ConfigPackageLocation} + ) + install( + FILES + cmake/ClimbingStatsConfig.cmake + "${CMAKE_CURRENT_BINARY_DIR}/ClimbingStats/ClimbingStatsConfigVersion.cmake" + DESTINATION + ${ConfigPackageLocation} + COMPONENT + Devel + ) + +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 ``<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` +targets, suitable for use by downstreams and arranges to install it to +``lib/cmake/ClimbingStats``. The generated ``ClimbingStatsConfigVersion.cmake`` +and a ``cmake/ClimbingStatsConfig.cmake`` are installed to the same location, +completing the package. + +The generated :prop_tgt:`IMPORTED` targets have appropriate properties set +to define their :ref:`usage requirements <Target Usage Requirements>`, such as +:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`, +:prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` and other relevant built-in +``INTERFACE_`` properties. The ``INTERFACE`` variant of user-defined +properties listed in :prop_tgt:`COMPATIBLE_INTERFACE_STRING` and +other :ref:`Compatible Interface Properties` are also propagated to the +generated :prop_tgt:`IMPORTED` targets. In the above case, +``ClimbingStats_MAJOR_VERSION`` is defined as a string which must be +compatible among the dependencies of any depender. By setting this custom +defined user property in this version and in the next version of +``ClimbingStats``, :manual:`cmake(1)` will issue a diagnostic if there is an +attempt to use version 3 together with version 4. Packages can choose to +employ such a pattern if different major versions of the package are designed +to be incompatible. + +A ``NAMESPACE`` with double-colons is specified when exporting the targets +for installation. This convention of double-colons gives CMake a hint that +the name is an :prop_tgt:`IMPORTED` target when it is used by downstreams +with the :command:`target_link_libraries` command. This way, CMake can +issue a diagnostic if the package providing it has not yet been found. + +In this case, when using :command:`install(TARGETS)` the ``INCLUDES DESTINATION`` +was specified. This causes the ``IMPORTED`` targets to have their +:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` populated with the ``include`` +directory in the :variable:`CMAKE_INSTALL_PREFIX`. When the ``IMPORTED`` +target is used by downstream, it automatically consumes the entries from +that property. + +Creating a Package Configuration File +------------------------------------- + +In this case, the ``ClimbingStatsConfig.cmake`` file could be as simple as: + +.. code-block:: cmake + + include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsTargets.cmake") + +As this allows downstreams to use the ``IMPORTED`` targets. If any macros +should be provided by the ``ClimbingStats`` package, they should +be in a separate file which is installed to the same location as the +``ClimbingStatsConfig.cmake`` file, and included from there. + +This can also be extended to cover dependencies: + +.. code-block:: cmake + + # ... + add_library(ClimbingStats SHARED climbingstats.cpp) + generate_export_header(ClimbingStats) + + find_package(Stats 2.6.4 REQUIRED) + target_link_libraries(ClimbingStats PUBLIC Stats::Types) + +As the ``Stats::Types`` target is a ``PUBLIC`` dependency of ``ClimbingStats``, +downstreams must also find the ``Stats`` package and link to the ``Stats::Types`` +library. The ``Stats`` package should be found in the ``ClimbingStatsConfig.cmake`` +file to ensure this. The ``find_dependency`` macro from the +:module:`CMakeFindDependencyMacro` helps with this by propagating +whether the package is ``REQUIRED``, or ``QUIET`` etc. All ``REQUIRED`` +dependencies of a package should be found in the ``Config.cmake`` file: + +.. code-block:: cmake + + include(CMakeFindDependencyMacro) + find_dependency(Stats 2.6.4) + + include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsTargets.cmake") + include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsMacros.cmake") + +The ``find_dependency`` macro also sets ``ClimbingStats_FOUND`` to ``False`` if +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 ``<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 + + include(CMakeFindDependencyMacro) + find_dependency(Stats 2.6.4) + + include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsTargets.cmake") + include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsMacros.cmake") + + set(_supported_components Plot Table) + + foreach(_comp ${ClimbingStats_FIND_COMPONENTS}) + if (NOT ";${_supported_components};" MATCHES _comp) + set(ClimbingStats_FOUND False) + set(ClimbingStats_NOT_FOUND_MESSAGE "Unsupported component: ${_comp}") + endif() + include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStats${_comp}Targets.cmake") + endforeach() + +Here, the ``ClimbingStats_NOT_FOUND_MESSAGE`` is set to a diagnosis that the package +could not be found because an invalid component was specified. This message +variable can be set for any case where the ``_FOUND`` variable is set to ``False``, +and will be displayed to the user. + +Creating a Package Configuration File for the Build Tree +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The :command:`export(EXPORT)` command creates an :prop_tgt:`IMPORTED` targets +definition file which is specific to the build-tree, and is not relocatable. +This can similarly be used with a suitable package configuration file and +package version file to define a package for the build tree which may be used +without installation. Consumers of the build tree can simply ensure that the +:variable:`CMAKE_PREFIX_PATH` contains the build directory, or set the +``ClimbingStats_DIR`` to ``<build_dir>/ClimbingStats`` in the cache. + +.. _`Creating Relocatable Packages`: + +Creating Relocatable Packages +----------------------------- + +A relocatable package must not reference absolute paths of files on +the machine where the package is built that will not exist on the +machines where the package may be installed. + +Packages created by :command:`install(EXPORT)` are designed to be relocatable, +using paths relative to the location of the package itself. When defining +the interface of a target for ``EXPORT``, keep in mind that the include +directories should be specified as relative paths which are relative to the +:variable:`CMAKE_INSTALL_PREFIX`: + +.. code-block:: cmake + + target_include_directories(tgt INTERFACE + # Wrong, not relocatable: + $<INSTALL_INTERFACE:${CMAKE_INSTALL_PREFIX}/include/TgtName> + ) + + target_include_directories(tgt INTERFACE + # Ok, relocatable: + $<INSTALL_INTERFACE:include/TgtName> + ) + +The ``$<INSTALL_PREFIX>`` +:manual:`generator expression <cmake-generator-expressions(7)>` may be used as +a placeholder for the install prefix without resulting in a non-relocatable +package. This is necessary if complex generator expressions are used: + +.. code-block:: cmake + + target_include_directories(tgt INTERFACE + # Ok, relocatable: + $<INSTALL_INTERFACE:$<$<CONFIG:Debug>:$<INSTALL_PREFIX>/include/TgtName>> + ) + +This also applies to paths referencing external dependencies. +It is not advisable to populate any properties which may contain +paths, such as :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` and +:prop_tgt:`INTERFACE_LINK_LIBRARIES`, with paths relevant to dependencies. +For example, this code may not work well for a relocatable package: + +.. code-block:: cmake + + target_link_libraries(ClimbingStats INTERFACE + ${Foo_LIBRARIES} ${Bar_LIBRARIES} + ) + target_include_directories(ClimbingStats INTERFACE + "$<INSTALL_INTERFACE:${Foo_INCLUDE_DIRS};${Bar_INCLUDE_DIRS}>" + ) + +The referenced variables may contain the absolute paths to libraries +and include directories **as found on the machine the package was made on**. +This would create a package with hard-coded paths to dependencies and not +suitable for relocation. + +Ideally such dependencies should be used through their own +:ref:`IMPORTED targets <Imported Targets>` that have their own +:prop_tgt:`IMPORTED_LOCATION` and usage requirement properties +such as :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` populated +appropriately. Those imported targets may then be used with +the :command:`target_link_libraries` command for ``ClimbingStats``: + +.. code-block:: cmake + + target_link_libraries(ClimbingStats INTERFACE Foo::Foo Bar::Bar) + +With this approach the package references its external dependencies +only through the names of :ref:`IMPORTED targets <Imported Targets>`. +When a consumer uses the installed package, the consumer will run the +appropriate :command:`find_package` commands (via the ``find_dependency`` +macro described above) to find the dependencies and populate the +imported targets with appropriate paths on their own machine. + +Unfortunately many :manual:`modules <cmake-modules(7)>` shipped with +CMake do not yet provide :ref:`IMPORTED targets <Imported Targets>` +because their development pre-dated this approach. This may improve +incrementally over time. Workarounds to create relocatable packages +using such modules include: + +* When building the package, specify each ``Foo_LIBRARY`` cache + entry as just a library name, e.g. ``-DFoo_LIBRARY=foo``. This + tells the corresponding find module to populate the ``Foo_LIBRARIES`` + with just ``foo`` to ask the linker to search for the library + instead of hard-coding a path. + +* Or, after installing the package content but before creating the + package installation binary for redistribution, manually replace + the absolute paths with placeholders for substitution by the + installation tool when the package is installed. + +.. _`Package Registry`: + +Package Registry +================ + +CMake provides two central locations to register packages that have +been built or installed anywhere on a system: + +* `User Package Registry`_ +* `System Package Registry`_ + +The registries are especially useful to help projects find packages in +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`_ (``<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 +sufficient permissions it also removes stale package registry entries +that refer to directories that do not exist or do not contain a matching +package configuration file. + +.. _`User Package Registry`: + +User Package Registry +--------------------- + +The User Package Registry is stored in a per-user location. +The :command:`export(PACKAGE)` command may be used to register a project +build tree in the user package registry. CMake currently provides no +interface to add install trees to the user package registry. Installers +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 ``<PackageName>`` may appear under registry key:: + + 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 ``<PackageName>`` may appear under +the directory:: + + ~/.cmake/packages/<PackageName> + +as a file, with arbitrary name, whose content specifies the directory +containing the package configuration file. + +.. _`System Package Registry`: + +System Package Registry +----------------------- + +The System Package Registry is stored in a system-wide location. +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 ``<PackageName>`` may appear under +registry key:: + + 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. + +There is no system package registry on non-Windows platforms. + +.. _`Disabling the Package Registry`: + +Disabling the Package Registry +------------------------------ + +In some cases using the Package Registries is not desirable. CMake +allows one to disable them using the following variables: + +* 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 +------------------------ + +A simple convention for naming package registry entries is to use content +hashes. They are deterministic and unlikely to collide +(:command:`export(PACKAGE)` uses this approach). +The name of an entry referencing a specific directory is simply the content +hash of the directory path itself. + +If a project arranges for package registry entries to exist, such as:: + + > reg query HKCU\Software\Kitware\CMake\Packages\MyPackage + HKEY_CURRENT_USER\Software\Kitware\CMake\Packages\MyPackage + 45e7d55f13b87179bb12f907c8de6fc4 REG_SZ c:/Users/Me/Work/lib/cmake/MyPackage + 7b4a9844f681c80ce93190d4e3185db9 REG_SZ c:/Users/Me/Work/MyPackage-build + +or:: + + $ cat ~/.cmake/packages/MyPackage/7d1fb77e07ce59a81bed093bbee945bd + /home/me/work/lib/cmake/MyPackage + $ cat ~/.cmake/packages/MyPackage/f92c1db873a1937f3100706657c63e07 + /home/me/work/MyPackage-build + +then the ``CMakeLists.txt`` code: + +.. code-block:: cmake + + find_package(MyPackage) + +will search the registered locations for package configuration files +(``MyPackageConfig.cmake``). The search order among package registry +entries for a single package is unspecified and the entry names +(hashes in this example) have no meaning. Registered locations may +contain package version files (``MyPackageConfigVersion.cmake``) to +tell :command:`find_package` whether a specific location is suitable +for the version requested. + +Package Registry Ownership +-------------------------- + +Package registry entries are individually owned by the project installations +that they reference. A package installer is responsible for adding its own +entry and the corresponding uninstaller is responsible for removing it. + +The :command:`export(PACKAGE)` command populates the user package registry +with the location of a project build tree. Build trees tend to be deleted by +developers and have no "uninstall" event that could trigger removal of their +entries. In order to keep the registries clean the :command:`find_package` +command automatically removes stale entries it encounters if it has sufficient +permissions. CMake provides no interface to remove an entry referencing an +existing build tree once :command:`export(PACKAGE)` has been invoked. +However, if the project removes its package configuration file from the build +tree then the entry referencing the location will be considered stale. diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst new file mode 100644 index 0000000..5dfa894 --- /dev/null +++ b/Help/manual/cmake-policies.7.rst @@ -0,0 +1,330 @@ +.. cmake-manual-description: CMake Policies Reference + +cmake-policies(7) +***************** + +.. only:: html + + .. contents:: + +Introduction +============ + +Policies in CMake are used to preserve backward compatible behavior +across multiple releases. When a new policy is introduced, newer CMake +versions will begin to warn about the backward compatible behavior. It +is possible to disable the warning by explicitly requesting the OLD, or +backward compatible behavior using the :command:`cmake_policy` command. +It is also possible to request ``NEW``, or non-backward compatible behavior +for a policy, also avoiding the warning. Each policy can also be set to +either ``NEW`` or ``OLD`` behavior explicitly on the command line with the +:variable:`CMAKE_POLICY_DEFAULT_CMP<NNNN>` variable. + +A policy is a deprecation mechanism and not a reliable feature toggle. +A policy should almost never be set to ``OLD``, except to silence warnings +in an otherwise frozen or stable codebase, or temporarily as part of a +larger migration path. The ``OLD`` behavior of each policy is undesirable +and will be replaced with an error condition in a future release. + +The :command:`cmake_minimum_required` command does more than report an +error if a too-old version of CMake is used to build a project. It +also sets all policies introduced in that CMake version or earlier to +``NEW`` behavior. To manage policies without increasing the minimum required +CMake version, the :command:`if(POLICY)` command may be used: + +.. code-block:: cmake + + if(POLICY CMP0990) + cmake_policy(SET CMP0990 NEW) + endif() + +This has the effect of using the ``NEW`` behavior with newer CMake releases which +users may be using and not issuing a compatibility warning. + +The setting of a policy is confined in some cases to not propagate to the +parent scope. For example, if the files read by the :command:`include` command +or the :command:`find_package` command contain a use of :command:`cmake_policy`, +that policy setting will not affect the caller by default. Both commands accept +an optional ``NO_POLICY_SCOPE`` keyword to control this behavior. + +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.21 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0122: UseSWIG use standard library name conventions for csharp language. </policy/CMP0122> + CMP0121: The list command detects invalid indicies. </policy/CMP0121> + +Policies Introduced by CMake 3.20 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0120: The WriteCompilerDetectionHeader module is removed. </policy/CMP0120> + CMP0119: LANGUAGE source file property explicitly compiles as language. </policy/CMP0119> + CMP0118: The GENERATED source file property is now visible in all directories. </policy/CMP0118> + CMP0117: MSVC RTTI flag /GR is not added to CMAKE_CXX_FLAGS by default. </policy/CMP0117> + CMP0116: Ninja generators transform DEPFILEs from add_custom_command(). </policy/CMP0116> + CMP0115: Source file extensions must be explicit. </policy/CMP0115> + +Policies Introduced by CMake 3.19 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0114: ExternalProject step targets fully adopt their steps. </policy/CMP0114> + CMP0113: Makefile generators do not repeat custom commands from target dependencies. </policy/CMP0113> + CMP0112: Target file component generator expressions do not add target dependencies. </policy/CMP0112> + CMP0111: An imported target missing its location property fails during generation. </policy/CMP0111> + CMP0110: add_test() supports arbitrary characters in test names. </policy/CMP0110> + CMP0109: find_program() requires permission to execute but not to read. </policy/CMP0109> + +Policies Introduced by CMake 3.18 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0108: A target cannot link to itself through an alias. </policy/CMP0108> + CMP0107: An ALIAS target cannot overwrite another target. </policy/CMP0107> + CMP0106: The Documentation module is removed. </policy/CMP0106> + CMP0105: Device link step uses the link options. </policy/CMP0105> + CMP0104: CMAKE_CUDA_ARCHITECTURES now detected for NVCC, empty CUDA_ARCHITECTURES not allowed. </policy/CMP0104> + CMP0103: Multiple export() with same FILE without APPEND is not allowed. </policy/CMP0103> + +Policies Introduced by CMake 3.17 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0102: mark_as_advanced() does nothing if a cache entry does not exist. </policy/CMP0102> + CMP0101: target_compile_options honors BEFORE keyword in all scopes. </policy/CMP0101> + CMP0100: Let AUTOMOC and AUTOUIC process .hh header files. </policy/CMP0100> + CMP0099: Link properties are transitive over private dependency on static libraries. </policy/CMP0099> + CMP0098: FindFLEX runs flex in CMAKE_CURRENT_BINARY_DIR when executing. </policy/CMP0098> + +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 +================================ + +.. toctree:: + :maxdepth: 1 + + CMP0069: INTERPROCEDURAL_OPTIMIZATION is enforced when enabled. </policy/CMP0069> + CMP0068: RPATH settings on macOS do not affect install_name. </policy/CMP0068> + +Policies Introduced by CMake 3.8 +================================ + +.. toctree:: + :maxdepth: 1 + + CMP0067: Honor language standard in try_compile() source-file signature. </policy/CMP0067> + +Policies Introduced by CMake 3.7 +================================ + +.. toctree:: + :maxdepth: 1 + + CMP0066: Honor per-config flags in try_compile() source-file signature. </policy/CMP0066> + +Policies Introduced by CMake 3.4 +================================ + +.. toctree:: + :maxdepth: 1 + + CMP0065: Do not add flags to export symbols from executables without the ENABLE_EXPORTS target property. </policy/CMP0065> + CMP0064: Support new TEST if() operator. </policy/CMP0064> + +Policies Introduced by CMake 3.3 +================================ + +.. toctree:: + :maxdepth: 1 + + CMP0063: Honor visibility properties for all target types. </policy/CMP0063> + CMP0062: Disallow install() of export() result. </policy/CMP0062> + CMP0061: CTest does not by default tell make to ignore errors (-i). </policy/CMP0061> + CMP0060: Link libraries by full path even in implicit directories. </policy/CMP0060> + CMP0059: Do not treat DEFINITIONS as a built-in directory property. </policy/CMP0059> + CMP0058: Ninja requires custom command byproducts to be explicit. </policy/CMP0058> + CMP0057: Support new IN_LIST if() operator. </policy/CMP0057> + +Policies Introduced by CMake 3.2 +================================ + +.. toctree:: + :maxdepth: 1 + + CMP0056: Honor link flags in try_compile() source-file signature. </policy/CMP0056> + CMP0055: Strict checking for break() command. </policy/CMP0055> + +Policies Introduced by CMake 3.1 +================================ + +.. toctree:: + :maxdepth: 1 + + CMP0054: Only interpret if() arguments as variables or keywords when unquoted. </policy/CMP0054> + CMP0053: Simplify variable reference and escape sequence evaluation. </policy/CMP0053> + CMP0052: Reject source and build dirs in installed INTERFACE_INCLUDE_DIRECTORIES. </policy/CMP0052> + CMP0051: List TARGET_OBJECTS in SOURCES target property. </policy/CMP0051> + +Policies Introduced by CMake 3.0 +================================ + +.. toctree:: + :maxdepth: 1 + + CMP0050: Disallow add_custom_command SOURCE signatures. </policy/CMP0050> + CMP0049: Do not expand variables in target source entries. </policy/CMP0049> + CMP0048: project() command manages VERSION variables. </policy/CMP0048> + CMP0047: Use QCC compiler id for the qcc drivers on QNX. </policy/CMP0047> + CMP0046: Error on non-existent dependency in add_dependencies. </policy/CMP0046> + CMP0045: Error on non-existent target in get_target_property. </policy/CMP0045> + CMP0044: Case sensitive Lang_COMPILER_ID generator expressions. </policy/CMP0044> + CMP0043: Ignore COMPILE_DEFINITIONS_Config properties. </policy/CMP0043> + CMP0042: MACOSX_RPATH is enabled by default. </policy/CMP0042> + CMP0041: Error on relative include with generator expression. </policy/CMP0041> + CMP0040: The target in the TARGET signature of add_custom_command() must exist. </policy/CMP0040> + CMP0039: Utility targets may not have link dependencies. </policy/CMP0039> + CMP0038: Targets may not link directly to themselves. </policy/CMP0038> + CMP0037: Target names should not be reserved and should match a validity pattern. </policy/CMP0037> + CMP0036: The build_name command should not be called. </policy/CMP0036> + CMP0035: The variable_requires command should not be called. </policy/CMP0035> + CMP0034: The utility_source command should not be called. </policy/CMP0034> + CMP0033: The export_library_dependencies command should not be called. </policy/CMP0033> + CMP0032: The output_required_files command should not be called. </policy/CMP0032> + CMP0031: The load_command command should not be called. </policy/CMP0031> + CMP0030: The use_mangled_mesa command should not be called. </policy/CMP0030> + CMP0029: The subdir_depends command should not be called. </policy/CMP0029> + CMP0028: Double colon in target name means ALIAS or IMPORTED target. </policy/CMP0028> + CMP0027: Conditionally linked imported targets with missing include directories. </policy/CMP0027> + CMP0026: Disallow use of the LOCATION target property. </policy/CMP0026> + CMP0025: Compiler id for Apple Clang is now AppleClang. </policy/CMP0025> + CMP0024: Disallow include export result. </policy/CMP0024> + +Policies Introduced by CMake 2.8 +================================ + +.. toctree:: + :maxdepth: 1 + + CMP0023: Plain and keyword target_link_libraries signatures cannot be mixed. </policy/CMP0023> + CMP0022: INTERFACE_LINK_LIBRARIES defines the link interface. </policy/CMP0022> + CMP0021: Fatal error on relative paths in INCLUDE_DIRECTORIES target property. </policy/CMP0021> + CMP0020: Automatically link Qt executables to qtmain target on Windows. </policy/CMP0020> + CMP0019: Do not re-expand variables in include and link information. </policy/CMP0019> + CMP0018: Ignore CMAKE_SHARED_LIBRARY_Lang_FLAGS variable. </policy/CMP0018> + CMP0017: Prefer files from the CMake module directory when including from there. </policy/CMP0017> + CMP0016: target_link_libraries() reports error if its only argument is not a target. </policy/CMP0016> + CMP0015: link_directories() treats paths relative to the source dir. </policy/CMP0015> + CMP0014: Input directories must have CMakeLists.txt. </policy/CMP0014> + CMP0013: Duplicate binary directories are not allowed. </policy/CMP0013> + CMP0012: if() recognizes numbers and boolean constants. </policy/CMP0012> + +Policies Introduced by CMake 2.6 +================================ + +.. toctree:: + :maxdepth: 1 + + CMP0011: Included scripts do automatic cmake_policy PUSH and POP. </policy/CMP0011> + CMP0010: Bad variable reference syntax is an error. </policy/CMP0010> + CMP0009: FILE GLOB_RECURSE calls should not follow symlinks by default. </policy/CMP0009> + CMP0008: Libraries linked by full-path must have a valid library file name. </policy/CMP0008> + CMP0007: list command no longer ignores empty elements. </policy/CMP0007> + CMP0006: Installing MACOSX_BUNDLE targets requires a BUNDLE DESTINATION. </policy/CMP0006> + CMP0005: Preprocessor definition values are now escaped automatically. </policy/CMP0005> + CMP0004: Libraries linked may not have leading or trailing whitespace. </policy/CMP0004> + CMP0003: Libraries linked via full path no longer produce linker search paths. </policy/CMP0003> + CMP0002: Logical target names must be globally unique. </policy/CMP0002> + CMP0001: CMAKE_BACKWARDS_COMPATIBILITY should no longer be used. </policy/CMP0001> + CMP0000: A minimum required CMake version must be specified. </policy/CMP0000> diff --git a/Help/manual/cmake-presets.7.rst b/Help/manual/cmake-presets.7.rst new file mode 100644 index 0000000..3714004 --- /dev/null +++ b/Help/manual/cmake-presets.7.rst @@ -0,0 +1,998 @@ +.. cmake-manual-description: CMakePresets.json + +cmake-presets(7) +**************** + +.. only:: html + + .. contents:: + +Introduction +============ + +One problem that CMake users often face is sharing settings with other people +for common ways to configure a project. This may be done to support CI builds, +or for users who frequently use the same build. CMake supports two files, +``CMakePresets.json`` and ``CMakeUserPresets.json``, that allow users to +specify common configure options and share them with others. + +``CMakePresets.json`` and ``CMakeUserPresets.json`` live in the project's root +directory. They both have exactly the same format, and both are optional +(though at least one must be present if ``--preset`` is specified.) +``CMakePresets.json`` is meant to save project-wide builds, while +``CMakeUserPresets.json`` is meant for developers to save their own local +builds. ``CMakePresets.json`` may be checked into a version control system, and +``CMakeUserPresets.json`` should NOT be checked in. For example, if a project +is using Git, ``CMakePresets.json`` may be tracked, and +``CMakeUserPresets.json`` should be added to the ``.gitignore``. + +Format +====== + +The files are a JSON document with an object as the root: + +.. literalinclude:: presets/example.json + :language: json + +The root object recognizes the following fields: + +``version`` + + A required integer representing the version of the JSON schema. + The supported versions are ``1``, ``2``, and ``3``. + +``cmakeMinimumRequired`` + + An optional object representing the minimum version of CMake needed to + build this project. This object consists of the following fields: + + ``major`` + + An optional integer representing the major version. + + ``minor`` + + An optional integer representing the minor version. + + ``patch`` + + An optional integer representing the patch version. + +``vendor`` + + An optional map containing vendor-specific information. CMake does not + interpret the contents of this field except to verify that it is a map if + it does exist. However, the keys should be a vendor-specific domain name + followed by a ``/``-separated path. For example, the Example IDE 1.0 could + use ``example.com/ExampleIDE/1.0``. The value of each field can be anything + desired by the vendor, though will typically be a map. + +``configurePresets`` + + An optional array of `Configure Preset`_ objects. + This is allowed in preset files specifying version ``1`` or above. + +``buildPresets`` + + An optional array of `Build Preset`_ objects. + This is allowed in preset files specifying version ``2`` or above. + +``testPresets`` + + An optional array of `Test Preset`_ objects. + This is allowed in preset files specifying version ``2`` or above. + +Configure Preset +^^^^^^^^^^^^^^^^ + +Each entry of the ``configurePresets`` array is a JSON object +that may contain the following fields: + +``name`` + + A required string representing the machine-friendly name of the preset. + This identifier is used in the :ref:`cmake --preset <CMake Options>` option. + There must not be two configure presets in the union of ``CMakePresets.json`` + and ``CMakeUserPresets.json`` in the same directory with the same name. + However, a configure preset may have the same name as a build or test preset. + +``hidden`` + + An optional boolean specifying whether or not a preset should be hidden. + If a preset is hidden, it cannot be used in the ``--preset=`` argument, + will not show up in the :manual:`CMake GUI <cmake-gui(1)>`, and does not + have to have a valid ``generator`` or ``binaryDir``, even from + inheritance. ``hidden`` presets are intended to be used as a base for + other presets to inherit via the ``inherits`` field. + +``inherits`` + + An optional array of strings representing the names of presets to inherit + from. The preset will inherit all of the fields from the ``inherits`` + presets by default (except ``name``, ``hidden``, ``inherits``, + ``description``, and ``displayName``), but can override them as + desired. If multiple ``inherits`` presets provide conflicting values for + the same field, the earlier preset in the ``inherits`` list will be + preferred. Presets in ``CMakePresets.json`` may not inherit from presets + in ``CMakeUserPresets.json``. + + This field can also be a string, which is equivalent to an array + containing one string. + +``condition`` + + An optional `Condition`_ object. This is allowed in preset files specifying + version ``3`` or above. + +``vendor`` + + An optional map containing vendor-specific information. CMake does not + interpret the contents of this field except to verify that it is a map + if it does exist. However, it should follow the same conventions as the + root-level ``vendor`` field. If vendors use their own per-preset + ``vendor`` field, they should implement inheritance in a sensible manner + when appropriate. + +``displayName`` + + An optional string with a human-friendly name of the preset. + +``description`` + + An optional string with a human-friendly description of the preset. + +``generator`` + + An optional string representing the generator to use for the preset. If + ``generator`` is not specified, it must be inherited from the + ``inherits`` preset (unless this preset is ``hidden``). In version ``3`` + or above, this field may be omitted to fall back to regular generator + discovery procedure. + + Note that for Visual Studio generators, unlike in the command line ``-G`` + argument, you cannot include the platform name in the generator name. Use + the ``architecture`` field instead. + +``architecture``, ``toolset`` + + Optional fields representing the platform and toolset, respectively, for + generators that support them. Each may be either a string or an object + with the following fields: + + ``value`` + + An optional string representing the value. + + ``strategy`` + + An optional string telling CMake how to handle the ``architecture`` or + ``toolset`` field. Valid values are: + + ``"set"`` + + Set the respective value. This will result in an error for generators + that do not support the respective field. + + ``"external"`` + + Do not set the value, even if the generator supports it. This is + useful if, for example, a preset uses the Ninja generator, and an IDE + knows how to set up the Visual C++ environment from the + ``architecture`` and ``toolset`` fields. In that case, CMake will + ignore the field, but the IDE can use them to set up the environment + before invoking CMake. + +``binaryDir`` + + An optional string representing the path to the output binary directory. + This field supports `macro expansion`_. If a relative path is specified, + it is calculated relative to the source directory. If ``binaryDir`` is not + specified, it must be inherited from the ``inherits`` preset (unless this + preset is ``hidden``). In version ``3`` or above, this field may be + omitted. + +``installDir`` + + An optional string representing the path to the installation directory. + This field supports `macro expansion`_. If a relative path is specified, + it is calculated relative to the source directory. This is allowed in + preset files specifying version ``3`` or above. + +``cmakeExecutable`` + + An optional string representing the path to the CMake executable to use + for this preset. This is reserved for use by IDEs, and is not used by + CMake itself. IDEs that use this field should expand any macros in it. + +``cacheVariables`` + + An optional map of cache variables. The key is the variable name (which + may not be an empty string), and the value is either ``null``, a boolean + (which is equivalent to a value of ``"TRUE"`` or ``"FALSE"`` and a type + of ``BOOL``), a string representing the value of the variable (which + supports `macro expansion`_), or an object with the following fields: + + ``type`` + + An optional string representing the type of the variable. + + ``value`` + + A required string or boolean representing the value of the variable. + A boolean is equivalent to ``"TRUE"`` or ``"FALSE"``. This field + supports `macro expansion`_. + + Cache variables are inherited through the ``inherits`` field, and the + preset's variables will be the union of its own ``cacheVariables`` and + the ``cacheVariables`` from all its parents. If multiple presets in this + union define the same variable, the standard rules of ``inherits`` are + applied. Setting a variable to ``null`` causes it to not be set, even if + a value was inherited from another preset. + +``environment`` + + An optional map of environment variables. The key is the variable name + (which may not be an empty string), and the value is either ``null`` or + a string representing the value of the variable. Each variable is set + regardless of whether or not a value was given to it by the process's + environment. This field supports `macro expansion`_, and environment + variables in this map may reference each other, and may be listed in any + order, as long as such references do not cause a cycle (for example, + if ``ENV_1`` is ``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``.) + + Environment variables are inherited through the ``inherits`` field, and + the preset's environment will be the union of its own ``environment`` and + the ``environment`` from all its parents. If multiple presets in this + union define the same variable, the standard rules of ``inherits`` are + applied. Setting a variable to ``null`` causes it to not be set, even if + a value was inherited from another preset. + +``warnings`` + + An optional object specifying the warnings to enable. The object may + contain the following fields: + + ``dev`` + + An optional boolean. Equivalent to passing ``-Wdev`` or ``-Wno-dev`` + on the command line. This may not be set to ``false`` if ``errors.dev`` + is set to ``true``. + + ``deprecated`` + + An optional boolean. Equivalent to passing ``-Wdeprecated`` or + ``-Wno-deprecated`` on the command line. This may not be set to + ``false`` if ``errors.deprecated`` is set to ``true``. + + ``uninitialized`` + + An optional boolean. Setting this to ``true`` is equivalent to passing + ``--warn-uninitialized`` on the command line. + + ``unusedCli`` + + An optional boolean. Setting this to ``false`` is equivalent to passing + ``--no-warn-unused-cli`` on the command line. + + ``systemVars`` + + An optional boolean. Setting this to ``true`` is equivalent to passing + ``--check-system-vars`` on the command line. + +``errors`` + + An optional object specifying the errors to enable. The object may + contain the following fields: + + ``dev`` + + An optional boolean. Equivalent to passing ``-Werror=dev`` or + ``-Wno-error=dev`` on the command line. This may not be set to ``true`` + if ``warnings.dev`` is set to ``false``. + + ``deprecated`` + + An optional boolean. Equivalent to passing ``-Werror=deprecated`` or + ``-Wno-error=deprecated`` on the command line. This may not be set to + ``true`` if ``warnings.deprecated`` is set to ``false``. + +``debug`` + + An optional object specifying debug options. The object may contain the + following fields: + + ``output`` + + An optional boolean. Setting this to ``true`` is equivalent to passing + ``--debug-output`` on the command line. + + ``tryCompile`` + + An optional boolean. Setting this to ``true`` is equivalent to passing + ``--debug-trycompile`` on the command line. + + ``find`` + + An optional boolean. Setting this to ``true`` is equivalent to passing + ``--debug-find`` on the command line. + +Build Preset +^^^^^^^^^^^^ + +Each entry of the ``buildPresets`` array is a JSON object +that may contain the following fields: + +``name`` + + A required string representing the machine-friendly name of the preset. + This identifier is used in the + :ref:`cmake --build --preset <Build Tool Mode>` option. + There must not be two build presets in the union of ``CMakePresets.json`` + and ``CMakeUserPresets.json`` in the same directory with the same name. + However, a build preset may have the same name as a configure or test preset. + +``hidden`` + + An optional boolean specifying whether or not a preset should be hidden. + If a preset is hidden, it cannot be used in the ``--preset`` argument + and does not have to have a valid ``configurePreset``, even from + inheritance. ``hidden`` presets are intended to be used as a base for + other presets to inherit via the ``inherits`` field. + +``inherits`` + + An optional array of strings representing the names of presets to + inherit from. The preset will inherit all of the fields from the + ``inherits`` presets by default (except ``name``, ``hidden``, + ``inherits``, ``description``, and ``displayName``), but can override + them as desired. If multiple ``inherits`` presets provide conflicting + values for the same field, the earlier preset in the ``inherits`` list + will be preferred. Presets in ``CMakePresets.json`` may not inherit from + presets in ``CMakeUserPresets.json``. + + This field can also be a string, which is equivalent to an array + containing one string. + +``condition`` + + An optional `Condition`_ object. This is allowed in preset files specifying + version ``3`` or above. + +``vendor`` + + An optional map containing vendor-specific information. CMake does not + interpret the contents of this field except to verify that it is a map + if it does exist. However, it should follow the same conventions as the + root-level ``vendor`` field. If vendors use their own per-preset + ``vendor`` field, they should implement inheritance in a sensible manner + when appropriate. + +``displayName`` + + An optional string with a human-friendly name of the preset. + +``description`` + + An optional string with a human-friendly description of the preset. + +``environment`` + + An optional map of environment variables. The key is the variable name + (which may not be an empty string), and the value is either ``null`` or + a string representing the value of the variable. Each variable is set + regardless of whether or not a value was given to it by the process's + environment. This field supports macro expansion, and environment + variables in this map may reference each other, and may be listed in any + order, as long as such references do not cause a cycle (for example, if + ``ENV_1`` is ``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``.) + + Environment variables are inherited through the ``inherits`` field, and + the preset's environment will be the union of its own ``environment`` + and the ``environment`` from all its parents. If multiple presets in + this union define the same variable, the standard rules of ``inherits`` + are applied. Setting a variable to ``null`` causes it to not be set, + even if a value was inherited from another preset. + +``configurePreset`` + + An optional string specifying the name of a configure preset to + associate with this build preset. If ``configurePreset`` is not + specified, it must be inherited from the inherits preset (unless this + preset is hidden). The build directory is inferred from the configure + preset, so the build will take place in the same ``binaryDir`` that the + configuration did. + +``inheritConfigureEnvironment`` + + An optional boolean that defaults to true. If true, the environment + variables from the associated configure preset are inherited after all + inherited build preset environments, but before environment variables + explicitly specified in this build preset. + +``jobs`` + + An optional integer. Equivalent to passing ``--parallel`` or ``-j`` on + the command line. + +``targets`` + + An optional string or array of strings. Equivalent to passing + ``--target`` or ``-t`` on the command line. Vendors may ignore the + targets property or hide build presets that explicitly specify targets. + This field supports macro expansion. + +``configuration`` + + An optional string. Equivalent to passing ``--config`` on the command + line. + +``cleanFirst`` + + An optional bool. If true, equivalent to passing ``--clean-first`` on + the command line. + +``verbose`` + + An optional bool. If true, equivalent to passing ``--verbose`` on the + command line. + +``nativeToolOptions`` + + An optional array of strings. Equivalent to passing options after ``--`` + on the command line. The array values support macro expansion. + +Test Preset +^^^^^^^^^^^ + +Each entry of the ``testPresets`` array is a JSON object +that may contain the following fields: + +``name`` + + A required string representing the machine-friendly name of the preset. + This identifier is used in the :ref:`ctest --preset <CTest Options>` option. + There must not be two test presets in the union of ``CMakePresets.json`` + and ``CMakeUserPresets.json`` in the same directory with the same name. + However, a test preset may have the same name as a configure or build preset. + +``hidden`` + + An optional boolean specifying whether or not a preset should be hidden. + If a preset is hidden, it cannot be used in the ``--preset`` argument + and does not have to have a valid ``configurePreset``, even from + inheritance. ``hidden`` presets are intended to be used as a base for + other presets to inherit via the ``inherits`` field. + +``inherits`` + + An optional array of strings representing the names of presets to + inherit from. The preset will inherit all of the fields from the + ``inherits`` presets by default (except ``name``, ``hidden``, + ``inherits``, ``description``, and ``displayName``), but can override + them as desired. If multiple ``inherits`` presets provide conflicting + values for the same field, the earlier preset in the ``inherits`` list + will be preferred. Presets in ``CMakePresets.json`` may not inherit from + presets in ``CMakeUserPresets.json``. + + This field can also be a string, which is equivalent to an array + containing one string. + +``condition`` + + An optional `Condition`_ object. This is allowed in preset files specifying + version ``3`` or above. + +``vendor`` + + An optional map containing vendor-specific information. CMake does not + interpret the contents of this field except to verify that it is a map + if it does exist. However, it should follow the same conventions as the + root-level ``vendor`` field. If vendors use their own per-preset + ``vendor`` field, they should implement inheritance in a sensible manner + when appropriate. + +``displayName`` + + An optional string with a human-friendly name of the preset. + +``description`` + + An optional string with a human-friendly description of the preset. + +``environment`` + + An optional map of environment variables. The key is the variable name + (which may not be an empty string), and the value is either ``null`` or + a string representing the value of the variable. Each variable is set + regardless of whether or not a value was given to it by the process's + environment. This field supports macro expansion, and environment + variables in this map may reference each other, and may be listed in any + order, as long as such references do not cause a cycle (for example, if + ``ENV_1`` is ``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``.) + + Environment variables are inherited through the ``inherits`` field, and + the preset's environment will be the union of its own ``environment`` + and the ``environment`` from all its parents. If multiple presets in + this union define the same variable, the standard rules of ``inherits`` + are applied. Setting a variable to ``null`` causes it to not be set, + even if a value was inherited from another preset. + +``configurePreset`` + + An optional string specifying the name of a configure preset to + associate with this test preset. If ``configurePreset`` is not + specified, it must be inherited from the inherits preset (unless this + preset is hidden). The build directory is inferred from the configure + preset, so tests will run in the same ``binaryDir`` that the + configuration did and build did. + +``inheritConfigureEnvironment`` + + An optional boolean that defaults to true. If true, the environment + variables from the associated configure preset are inherited after all + inherited test preset environments, but before environment variables + explicitly specified in this test preset. + +``configuration`` + + An optional string. Equivalent to passing ``--build-config`` on the + command line. + +``overwriteConfigurationFile`` + + An optional array of configuration options to overwrite options + specified in the CTest configuration file. Equivalent to passing + ``--overwrite`` for each value in the array. The array values + support macro expansion. + +``output`` + + An optional object specifying output options. The object may contain the + following fields. + + ``shortProgress`` + + An optional bool. If true, equivalent to passing ``--progress`` on the + command line. + + ``verbosity`` + + An optional string specifying verbosity level. Must be one of the + following: + + ``default`` + + Equivalent to passing no verbosity flags on the command line. + + ``verbose`` + + Equivalent to passing ``--verbose`` on the command line. + + ``extra`` + + Equivalent to passing ``--extra-verbose`` on the command line. + + ``debug`` + + An optional bool. If true, equivalent to passing ``--debug`` on the + command line. + + ``outputOnFailure`` + + An optional bool. If true, equivalent to passing + ``--output-on-failure`` on the command line. + + ``quiet`` + + An optional bool. If true, equivalent to passing ``--quiet`` on the + command line. + + ``outputLogFile`` + + An optional string specifying a path to a log file. Equivalent to + passing ``--output-log`` on the command line. This field supports + macro expansion. + + ``labelSummary`` + + An optional bool. If false, equivalent to passing + ``--no-label-summary`` on the command line. + + ``subprojectSummary`` + + An optional bool. If false, equivalent to passing + ``--no-subproject-summary`` on the command line. + + ``maxPassedTestOutputSize`` + + An optional integer specifying the maximum output for passed tests in + bytes. Equivalent to passing ``--test-output-size-passed`` on the + command line. + + ``maxFailedTestOutputSize`` + + An optional integer specifying the maximum output for failed tests in + bytes. Equivalent to passing ``--test-output-size-failed`` on the + command line. + + ``maxTestNameWidth`` + + An optional integer specifying the maximum width of a test name to + output. Equivalent to passing ``--max-width`` on the command line. + +``filter`` + + An optional object specifying how to filter the tests to run. The object + may contain the following fields. + + ``include`` + + An optional object specifying which tests to include. The object may + contain the following fields. + + ``name`` + + An optional string specifying a regex for test names. Equivalent to + passing ``--tests-regex`` on the command line. This field supports + macro expansion. + + + ``label`` + + An optional string specifying a regex for test labels. Equivalent to + passing ``--label-regex`` on the command line. This field supports + macro expansion. + + ``useUnion`` + + An optional bool. Equivalent to passing ``--union`` on the command + line. + + ``index`` + + An optional object specifying tests to include by test index. The + object may contain the following fields. Can also be an optional + string specifying a file with the command line syntax for + ``--tests-information``. If specified as a string, this field + supports macro expansion. + + ``start`` + + An optional integer specifying a test index to start testing at. + + ``end`` + + An optional integer specifying a test index to stop testing at. + + ``stride`` + + An optional integer specifying the increment. + + ``specificTests`` + + An optional array of integers specifying specific test indices to + run. + + ``exclude`` + + An optional object specifying which tests to exclude. The object may + contain the following fields. + + ``name`` + + An optional string specifying a regex for test names. Equivalent to + passing ``--exclude-regex`` on the command line. This field supports + macro expansion. + + ``label`` + + An optional string specifying a regex for test labels. Equivalent to + passing ``--label-exclude`` on the command line. This field supports + macro expansion. + + ``fixtures`` + + An optional object specifying which fixtures to exclude from adding + tests. The object may contain the following fields. + + ``any`` + + An optional string specifying a regex for text fixtures to exclude + from adding any tests. Equivalent to ``--fixture-exclude-any`` on + the command line. This field supports macro expansion. + + ``setup`` + + An optional string specifying a regex for text fixtures to exclude + from adding setup tests. Equivalent to ``--fixture-exclude-setup`` + on the command line. This field supports macro expansion. + + ``cleanup`` + + An optional string specifying a regex for text fixtures to exclude + from adding cleanup tests. Equivalent to + ``--fixture-exclude-cleanup`` on the command line. This field + supports macro expansion. + +``execution`` + + An optional object specifying options for test execution. The object may + contain the following fields. + + ``stopOnFailure`` + + An optional bool. If true, equivalent to passing ``--stop-on-failure`` + on the command line. + + ``enableFailover`` + + An optional bool. If true, equivalent to passing ``-F`` on the command + line. + + ``jobs`` + + An optional integer. Equivalent to passing ``--parallel`` on the + command line. + + ``resourceSpecFile`` + + An optional string. Equivalent to passing ``--resource-spec-file`` on + the command line. This field supports macro expansion. + + ``testLoad`` + + An optional integer. Equivalent to passing ``--test-load`` on the + command line. + + ``showOnly`` + + An optional string. Equivalent to passing ``--show-only`` on the + command line. The string must be one of the following values: + + ``human`` + + ``json-v1`` + + ``repeat`` + + An optional object specifying how to repeat tests. Equivalent to + passing ``--repeat`` on the command line. The object must have the + following fields. + + ``mode`` + + A required string. Must be one of the following values: + + ``until-fail`` + + ``until-pass`` + + ``after-timeout`` + + ``count`` + + A required integer. + + ``interactiveDebugging`` + + An optional bool. If true, equivalent to passing + ``--interactive-debug-mode 1`` on the command line. If false, + equivalent to passing ``--interactive-debug-mode 0`` on the command + line. + + ``scheduleRandom`` + + An optional bool. If true, equivalent to passing ``--schedule-random`` + on the command line. + + ``timeout`` + + An optional integer. Equivalent to passing ``--timeout`` on the + command line. + + ``noTestsAction`` + + An optional string specifying the behavior if no tests are found. Must + be one of the following values: + + ``default`` + + Equivalent to not passing any value on the command line. + + ``error`` + + Equivalent to passing ``--no-tests=error`` on the command line. + + ``ignore`` + + Equivalent to passing ``--no-tests=ignore`` on the command line. + +Condition +^^^^^^^^^ + +The ``condition`` field of a preset, allowed in preset files specifying version +``3`` or above, is used to determine whether or not the preset is enabled. For +example, this can be used to disable a preset on platforms other than Windows. +``condition`` may be either a boolean, ``null``, or an object. If it is a +boolean, the boolean indicates whether the preset is enabled or disabled. If it +is ``null``, the preset is enabled, but the ``null`` condition is not inherited +by any presets that may inherit from the preset. Sub-conditions (for example in +a ``not``, ``anyOf``, or ``allOf`` condition) may not be ``null``. If it is an +object, it has the following fields: + +``type`` + + A required string with one of the following values: + + ``"const"`` + + Indicates that the condition is constant. This is equivalent to using a + boolean in place of the object. The condition object will have the + following additional fields: + + ``value`` + + A required boolean which provides a constant value for the condition's + evaluation. + + ``"equals"`` + + ``"notEquals"`` + + Indicates that the condition compares two strings to see if they are equal + (or not equal). The condition object will have the following additional + fields: + + ``lhs`` + + First string to compare. This field supports macro expansion. + + ``rhs`` + + Second string to compare. This field supports macro expansion. + + ``"inList"`` + + ``"notInList"`` + + Indicates that the condition searches for a string in a list of strings. + The condition object will have the following additional fields: + + ``string`` + + A required string to search for. This field supports macro expansion. + + ``list`` + + A required list of strings to search. This field supports macro + expansion, and uses short-circuit evaluation. + + ``"matches"`` + + ``"notMatches"`` + + Indicates that the condition searches for a regular expression in a string. + The condition object will have the following additional fields: + + ``string`` + + A required string to search. This field supports macro expansion. + + ``regex`` + + A required regular expression to search for. This field supports macro + expansion. + + ``"anyOf"`` + + ``"allOf"`` + + Indicates that the condition is an aggregation of zero or more nested + conditions. The condition object will have the following additional fields: + + ``conditions`` + + A required array of condition objects. These conditions use short-circuit + evaluation. + + ``"not"`` + + Indicates that the condition is an inversion of another condition. The + condition object will have the following additional fields: + + ``condition`` + + A required condition object. + +Macro Expansion +^^^^^^^^^^^^^^^ + +As mentioned above, some fields support macro expansion. Macros are +recognized in the form ``$<macro-namespace>{<macro-name>}``. All macros are +evaluated in the context of the preset being used, even if the macro is in a +field that was inherited from another preset. For example, if the ``Base`` +preset sets variable ``PRESET_NAME`` to ``${presetName}``, and the +``Derived`` preset inherits from ``Base``, ``PRESET_NAME`` will be set to +``Derived``. + +It is an error to not put a closing brace at the end of a macro name. For +example, ``${sourceDir`` is invalid. A dollar sign (``$``) followed by +anything other than a left curly brace (``{``) with a possible namespace is +interpreted as a literal dollar sign. + +Recognized macros include: + +``${sourceDir}`` + + Path to the project source directory. + +``${sourceParentDir}`` + + Path to the project source directory's parent directory. + +``${sourceDirName}`` + + The last filename component of ``${sourceDir}``. For example, if + ``${sourceDir}`` is ``/path/to/source``, this would be ``source``. + +``${presetName}`` + + Name specified in the preset's ``name`` field. + +``${generator}`` + + Generator specified in the preset's ``generator`` field. For build and + test presets, this will evaluate to the generator specified by + ``configurePreset``. + +``${hostSystemName}`` + + The name of the host operating system. Contains the same value as + :variable:`CMAKE_HOST_SYSTEM_NAME`. This is allowed in preset files + specifying version ``3`` or above. + +``${dollar}`` + + A literal dollar sign (``$``). + +``$env{<variable-name>}`` + + Environment variable with name ``<variable-name>``. The variable name may + not be an empty string. If the variable is defined in the ``environment`` + field, that value is used instead of the value from the parent environment. + If the environment variable is not defined, this evaluates as an empty + string. + + Note that while Windows environment variable names are case-insensitive, + variable names within a preset are still case-sensitive. This may lead to + unexpected results when using inconsistent casing. For best results, keep + the casing of environment variable names consistent. + +``$penv{<variable-name>}`` + + Similar to ``$env{<variable-name>}``, except that the value only comes from + the parent environment, and never from the ``environment`` field. This + allows you to prepend or append values to existing environment variables. + For example, setting ``PATH`` to ``/path/to/ninja/bin:$penv{PATH}`` will + prepend ``/path/to/ninja/bin`` to the ``PATH`` environment variable. This + is needed because ``$env{<variable-name>}`` does not allow circular + references. + +``$vendor{<macro-name>}`` + + An extension point for vendors to insert their own macros. CMake will not + be able to use presets which have a ``$vendor{<macro-name>}`` macro, and + effectively ignores such presets. However, it will still be able to use + other presets from the same file. + + CMake does not make any attempt to interpret ``$vendor{<macro-name>}`` + macros. However, to avoid name collisions, IDE vendors should prefix + ``<macro-name>`` with a very short (preferably <= 4 characters) vendor + identifier prefix, followed by a ``.``, followed by the macro name. For + example, the Example IDE could have ``$vendor{xide.ideInstallDir}``. + +Schema +====== + +:download:`This file </manual/presets/schema.json>` provides a machine-readable +JSON schema for the ``CMakePresets.json`` format. diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst new file mode 100644 index 0000000..60a4028 --- /dev/null +++ b/Help/manual/cmake-properties.7.rst @@ -0,0 +1,587 @@ +.. cmake-manual-description: CMake Properties Reference + +cmake-properties(7) +******************* + +.. only:: html + + .. contents:: + +.. _`Global Properties`: + +Properties of Global Scope +========================== + +.. toctree:: + :maxdepth: 1 + + /prop_gbl/ALLOW_DUPLICATE_CUSTOM_TARGETS + /prop_gbl/AUTOGEN_SOURCE_GROUP + /prop_gbl/AUTOGEN_TARGETS_FOLDER + /prop_gbl/AUTOMOC_SOURCE_GROUP + /prop_gbl/AUTOMOC_TARGETS_FOLDER + /prop_gbl/AUTORCC_SOURCE_GROUP + /prop_gbl/AUTOUIC_SOURCE_GROUP + /prop_gbl/CMAKE_C_KNOWN_FEATURES + /prop_gbl/CMAKE_CUDA_KNOWN_FEATURES + /prop_gbl/CMAKE_CXX_KNOWN_FEATURES + /prop_gbl/CMAKE_ROLE + /prop_gbl/DEBUG_CONFIGURATIONS + /prop_gbl/DISABLED_FEATURES + /prop_gbl/ECLIPSE_EXTRA_CPROJECT_CONTENTS + /prop_gbl/ECLIPSE_EXTRA_NATURES + /prop_gbl/ENABLED_FEATURES + /prop_gbl/ENABLED_LANGUAGES + /prop_gbl/FIND_LIBRARY_USE_LIB32_PATHS + /prop_gbl/FIND_LIBRARY_USE_LIB64_PATHS + /prop_gbl/FIND_LIBRARY_USE_LIBX32_PATHS + /prop_gbl/FIND_LIBRARY_USE_OPENBSD_VERSIONING + /prop_gbl/GENERATOR_IS_MULTI_CONFIG + /prop_gbl/GLOBAL_DEPENDS_DEBUG_MODE + /prop_gbl/GLOBAL_DEPENDS_NO_CYCLES + /prop_gbl/IN_TRY_COMPILE + /prop_gbl/JOB_POOLS + /prop_gbl/PACKAGES_FOUND + /prop_gbl/PACKAGES_NOT_FOUND + /prop_gbl/PREDEFINED_TARGETS_FOLDER + /prop_gbl/REPORT_UNDEFINED_PROPERTIES + /prop_gbl/RULE_LAUNCH_COMPILE + /prop_gbl/RULE_LAUNCH_CUSTOM + /prop_gbl/RULE_LAUNCH_LINK + /prop_gbl/RULE_MESSAGES + /prop_gbl/TARGET_ARCHIVES_MAY_BE_SHARED_LIBS + /prop_gbl/TARGET_MESSAGES + /prop_gbl/TARGET_SUPPORTS_SHARED_LIBS + /prop_gbl/USE_FOLDERS + /prop_gbl/XCODE_EMIT_EFFECTIVE_PLATFORM_NAME + +.. _`Directory Properties`: + +Properties on Directories +========================= + +.. toctree:: + :maxdepth: 1 + + /prop_dir/ADDITIONAL_CLEAN_FILES + /prop_dir/BINARY_DIR + /prop_dir/BUILDSYSTEM_TARGETS + /prop_dir/CACHE_VARIABLES + /prop_dir/CLEAN_NO_CUSTOM + /prop_dir/CMAKE_CONFIGURE_DEPENDS + /prop_dir/COMPILE_DEFINITIONS + /prop_dir/COMPILE_OPTIONS + /prop_dir/DEFINITIONS + /prop_dir/EXCLUDE_FROM_ALL + /prop_dir/IMPLICIT_DEPENDS_INCLUDE_TRANSFORM + /prop_dir/INCLUDE_DIRECTORIES + /prop_dir/INCLUDE_REGULAR_EXPRESSION + /prop_dir/INTERPROCEDURAL_OPTIMIZATION + /prop_dir/INTERPROCEDURAL_OPTIMIZATION_CONFIG + /prop_dir/LABELS + /prop_dir/LINK_DIRECTORIES + /prop_dir/LINK_OPTIONS + /prop_dir/LISTFILE_STACK + /prop_dir/MACROS + /prop_dir/PARENT_DIRECTORY + /prop_dir/RULE_LAUNCH_COMPILE + /prop_dir/RULE_LAUNCH_CUSTOM + /prop_dir/RULE_LAUNCH_LINK + /prop_dir/SOURCE_DIR + /prop_dir/SUBDIRECTORIES + /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 + /prop_dir/VS_STARTUP_PROJECT + +.. _`Target Properties`: + +Properties on Targets +===================== + +.. toctree:: + :maxdepth: 1 + + /prop_tgt/ADDITIONAL_CLEAN_FILES + /prop_tgt/AIX_EXPORT_ALL_SYMBOLS + /prop_tgt/ALIAS_GLOBAL + /prop_tgt/ALIASED_TARGET + /prop_tgt/ANDROID_ANT_ADDITIONAL_OPTIONS + /prop_tgt/ANDROID_API + /prop_tgt/ANDROID_API_MIN + /prop_tgt/ANDROID_ARCH + /prop_tgt/ANDROID_ASSETS_DIRECTORIES + /prop_tgt/ANDROID_GUI + /prop_tgt/ANDROID_JAR_DEPENDENCIES + /prop_tgt/ANDROID_JAR_DIRECTORIES + /prop_tgt/ANDROID_JAVA_SOURCE_DIR + /prop_tgt/ANDROID_NATIVE_LIB_DEPENDENCIES + /prop_tgt/ANDROID_NATIVE_LIB_DIRECTORIES + /prop_tgt/ANDROID_PROCESS_MAX + /prop_tgt/ANDROID_PROGUARD + /prop_tgt/ANDROID_PROGUARD_CONFIG_PATH + /prop_tgt/ANDROID_SECURE_PROPS_PATH + /prop_tgt/ANDROID_SKIP_ANT_STEP + /prop_tgt/ANDROID_STL_TYPE + /prop_tgt/ARCHIVE_OUTPUT_DIRECTORY + /prop_tgt/ARCHIVE_OUTPUT_DIRECTORY_CONFIG + /prop_tgt/ARCHIVE_OUTPUT_NAME + /prop_tgt/ARCHIVE_OUTPUT_NAME_CONFIG + /prop_tgt/AUTOGEN_BUILD_DIR + /prop_tgt/AUTOGEN_ORIGIN_DEPENDS + /prop_tgt/AUTOGEN_PARALLEL + /prop_tgt/AUTOGEN_TARGET_DEPENDS + /prop_tgt/AUTOMOC + /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/AUTORCC + /prop_tgt/AUTORCC_EXECUTABLE + /prop_tgt/AUTORCC_OPTIONS + /prop_tgt/AUTOUIC + /prop_tgt/AUTOUIC_EXECUTABLE + /prop_tgt/AUTOUIC_OPTIONS + /prop_tgt/AUTOUIC_SEARCH_PATHS + /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 + /prop_tgt/BUNDLE_EXTENSION + /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 + /prop_tgt/COMPATIBLE_INTERFACE_STRING + /prop_tgt/COMPILE_DEFINITIONS + /prop_tgt/COMPILE_FEATURES + /prop_tgt/COMPILE_FLAGS + /prop_tgt/COMPILE_OPTIONS + /prop_tgt/COMPILE_PDB_NAME + /prop_tgt/COMPILE_PDB_NAME_CONFIG + /prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY + /prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG + /prop_tgt/CONFIG_OUTPUT_NAME + /prop_tgt/CONFIG_POSTFIX + /prop_tgt/CROSSCOMPILING_EMULATOR + /prop_tgt/CUDA_ARCHITECTURES + /prop_tgt/CUDA_EXTENSIONS + /prop_tgt/CUDA_PTX_COMPILATION + /prop_tgt/CUDA_RESOLVE_DEVICE_SYMBOLS + /prop_tgt/CUDA_RUNTIME_LIBRARY + /prop_tgt/CUDA_SEPARABLE_COMPILATION + /prop_tgt/CUDA_STANDARD + /prop_tgt/CUDA_STANDARD_REQUIRED + /prop_tgt/CXX_EXTENSIONS + /prop_tgt/CXX_STANDARD + /prop_tgt/CXX_STANDARD_REQUIRED + /prop_tgt/DEBUG_POSTFIX + /prop_tgt/DEFINE_SYMBOL + /prop_tgt/DEPLOYMENT_ADDITIONAL_FILES + /prop_tgt/DEPLOYMENT_REMOTE_DIRECTORY + /prop_tgt/DEPRECATION + /prop_tgt/DISABLE_PRECOMPILE_HEADERS + /prop_tgt/DOTNET_TARGET_FRAMEWORK + /prop_tgt/DOTNET_TARGET_FRAMEWORK_VERSION + /prop_tgt/EchoString + /prop_tgt/ENABLE_EXPORTS + /prop_tgt/EXCLUDE_FROM_ALL + /prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD + /prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD_CONFIG + /prop_tgt/EXPORT_COMPILE_COMMANDS + /prop_tgt/EXPORT_NAME + /prop_tgt/EXPORT_PROPERTIES + /prop_tgt/FOLDER + /prop_tgt/Fortran_FORMAT + /prop_tgt/Fortran_MODULE_DIRECTORY + /prop_tgt/Fortran_PREPROCESS + /prop_tgt/FRAMEWORK + /prop_tgt/FRAMEWORK_MULTI_CONFIG_POSTFIX_CONFIG + /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 + /prop_tgt/IMPORTED_COMMON_LANGUAGE_RUNTIME + /prop_tgt/IMPORTED_CONFIGURATIONS + /prop_tgt/IMPORTED_GLOBAL + /prop_tgt/IMPORTED_IMPLIB + /prop_tgt/IMPORTED_IMPLIB_CONFIG + /prop_tgt/IMPORTED_LIBNAME + /prop_tgt/IMPORTED_LIBNAME_CONFIG + /prop_tgt/IMPORTED_LINK_DEPENDENT_LIBRARIES + /prop_tgt/IMPORTED_LINK_DEPENDENT_LIBRARIES_CONFIG + /prop_tgt/IMPORTED_LINK_INTERFACE_LANGUAGES + /prop_tgt/IMPORTED_LINK_INTERFACE_LANGUAGES_CONFIG + /prop_tgt/IMPORTED_LINK_INTERFACE_LIBRARIES + /prop_tgt/IMPORTED_LINK_INTERFACE_LIBRARIES_CONFIG + /prop_tgt/IMPORTED_LINK_INTERFACE_MULTIPLICITY + /prop_tgt/IMPORTED_LINK_INTERFACE_MULTIPLICITY_CONFIG + /prop_tgt/IMPORTED_LOCATION + /prop_tgt/IMPORTED_LOCATION_CONFIG + /prop_tgt/IMPORTED_NO_SONAME + /prop_tgt/IMPORTED_NO_SONAME_CONFIG + /prop_tgt/IMPORTED_OBJECTS + /prop_tgt/IMPORTED_OBJECTS_CONFIG + /prop_tgt/IMPORTED_SONAME + /prop_tgt/IMPORTED_SONAME_CONFIG + /prop_tgt/IMPORT_PREFIX + /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 + /prop_tgt/INTERFACE_COMPILE_DEFINITIONS + /prop_tgt/INTERFACE_COMPILE_FEATURES + /prop_tgt/INTERFACE_COMPILE_OPTIONS + /prop_tgt/INTERFACE_INCLUDE_DIRECTORIES + /prop_tgt/INTERFACE_LINK_DEPENDS + /prop_tgt/INTERFACE_LINK_DIRECTORIES + /prop_tgt/INTERFACE_LINK_LIBRARIES + /prop_tgt/INTERFACE_LINK_OPTIONS + /prop_tgt/INTERFACE_POSITION_INDEPENDENT_CODE + /prop_tgt/INTERFACE_PRECOMPILE_HEADERS + /prop_tgt/INTERFACE_SOURCES + /prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES + /prop_tgt/INTERPROCEDURAL_OPTIMIZATION + /prop_tgt/INTERPROCEDURAL_OPTIMIZATION_CONFIG + /prop_tgt/IOS_INSTALL_COMBINED + /prop_tgt/ISPC_HEADER_DIRECTORY + /prop_tgt/ISPC_HEADER_SUFFIX + /prop_tgt/ISPC_INSTRUCTION_SETS + /prop_tgt/JOB_POOL_COMPILE + /prop_tgt/JOB_POOL_LINK + /prop_tgt/JOB_POOL_PRECOMPILE_HEADER + /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 + /prop_tgt/LIBRARY_OUTPUT_DIRECTORY + /prop_tgt/LIBRARY_OUTPUT_DIRECTORY_CONFIG + /prop_tgt/LIBRARY_OUTPUT_NAME + /prop_tgt/LIBRARY_OUTPUT_NAME_CONFIG + /prop_tgt/LINK_DEPENDS + /prop_tgt/LINK_DEPENDS_NO_SHARED + /prop_tgt/LINK_DIRECTORIES + /prop_tgt/LINK_FLAGS + /prop_tgt/LINK_FLAGS_CONFIG + /prop_tgt/LINK_INTERFACE_LIBRARIES + /prop_tgt/LINK_INTERFACE_LIBRARIES_CONFIG + /prop_tgt/LINK_INTERFACE_MULTIPLICITY + /prop_tgt/LINK_INTERFACE_MULTIPLICITY_CONFIG + /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 + /prop_tgt/LINKER_LANGUAGE + /prop_tgt/LOCATION + /prop_tgt/LOCATION_CONFIG + /prop_tgt/MACHO_COMPATIBILITY_VERSION + /prop_tgt/MACHO_CURRENT_VERSION + /prop_tgt/MACOSX_BUNDLE + /prop_tgt/MACOSX_BUNDLE_INFO_PLIST + /prop_tgt/MACOSX_FRAMEWORK_INFO_PLIST + /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/OPTIMIZE_DEPENDENCIES + /prop_tgt/OSX_ARCHITECTURES + /prop_tgt/OSX_ARCHITECTURES_CONFIG + /prop_tgt/OUTPUT_NAME + /prop_tgt/OUTPUT_NAME_CONFIG + /prop_tgt/PCH_WARN_INVALID + /prop_tgt/PCH_INSTANTIATE_TEMPLATES + /prop_tgt/PDB_NAME + /prop_tgt/PDB_NAME_CONFIG + /prop_tgt/PDB_OUTPUT_DIRECTORY + /prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG + /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 + /prop_tgt/PUBLIC_HEADER + /prop_tgt/RESOURCE + /prop_tgt/RULE_LAUNCH_COMPILE + /prop_tgt/RULE_LAUNCH_CUSTOM + /prop_tgt/RULE_LAUNCH_LINK + /prop_tgt/RUNTIME_OUTPUT_DIRECTORY + /prop_tgt/RUNTIME_OUTPUT_DIRECTORY_CONFIG + /prop_tgt/RUNTIME_OUTPUT_NAME + /prop_tgt/RUNTIME_OUTPUT_NAME_CONFIG + /prop_tgt/SKIP_BUILD_RPATH + /prop_tgt/SOURCE_DIR + /prop_tgt/SOURCES + /prop_tgt/SOVERSION + /prop_tgt/STATIC_LIBRARY_FLAGS + /prop_tgt/STATIC_LIBRARY_FLAGS_CONFIG + /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/UNITY_BUILD_MODE + /prop_tgt/UNITY_BUILD_UNIQUE_ID + /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_DOCUMENTATION_FILE + /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_PLATFORM_TOOLSET + /prop_tgt/VS_PROJECT_IMPORT + /prop_tgt/VS_SCC_AUXPATH + /prop_tgt/VS_SCC_LOCALPATH + /prop_tgt/VS_SCC_PROJECTNAME + /prop_tgt/VS_SCC_PROVIDER + /prop_tgt/VS_SDK_REFERENCES + /prop_tgt/VS_SOLUTION_DEPLOY + /prop_tgt/VS_SOURCE_SETTINGS_tool + /prop_tgt/VS_USER_PROPS + /prop_tgt/VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION + /prop_tgt/VS_WINRT_COMPONENT + /prop_tgt/VS_WINRT_EXTENSIONS + /prop_tgt/VS_WINRT_REFERENCES + /prop_tgt/WIN32_EXECUTABLE + /prop_tgt/WINDOWS_EXPORT_ALL_SYMBOLS + /prop_tgt/XCODE_ATTRIBUTE_an-attribute + /prop_tgt/XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY + /prop_tgt/XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY + /prop_tgt/XCODE_EMBED_type + /prop_tgt/XCODE_EMBED_type_PATH + /prop_tgt/XCODE_EXPLICIT_FILE_TYPE + /prop_tgt/XCODE_GENERATE_SCHEME + /prop_tgt/XCODE_LINK_BUILD_PHASE_MODE + /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_WORKING_DIRECTORY + /prop_tgt/XCODE_SCHEME_ZOMBIE_OBJECTS + /prop_tgt/XCTEST + +.. _`Test Properties`: + +Properties on Tests +=================== + +.. toctree:: + :maxdepth: 1 + + /prop_test/ATTACHED_FILES + /prop_test/ATTACHED_FILES_ON_FAIL + /prop_test/COST + /prop_test/DEPENDS + /prop_test/DISABLED + /prop_test/ENVIRONMENT + /prop_test/FAIL_REGULAR_EXPRESSION + /prop_test/FIXTURES_CLEANUP + /prop_test/FIXTURES_REQUIRED + /prop_test/FIXTURES_SETUP + /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 + /prop_test/WILL_FAIL + /prop_test/WORKING_DIRECTORY + +.. _`Source File Properties`: + +Properties on Source Files +========================== + +.. toctree:: + :maxdepth: 1 + + /prop_sf/ABSTRACT + /prop_sf/AUTORCC_OPTIONS + /prop_sf/AUTOUIC_OPTIONS + /prop_sf/COMPILE_DEFINITIONS + /prop_sf/COMPILE_FLAGS + /prop_sf/COMPILE_OPTIONS + /prop_sf/EXTERNAL_OBJECT + /prop_sf/Fortran_FORMAT + /prop_sf/Fortran_PREPROCESS + /prop_sf/GENERATED + /prop_sf/HEADER_FILE_ONLY + /prop_sf/INCLUDE_DIRECTORIES + /prop_sf/KEEP_EXTENSION + /prop_sf/LABELS + /prop_sf/LANGUAGE + /prop_sf/LOCATION + /prop_sf/MACOSX_PACKAGE_LOCATION + /prop_sf/OBJECT_DEPENDS + /prop_sf/OBJECT_OUTPUTS + /prop_sf/SKIP_AUTOGEN + /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/UNITY_GROUP + /prop_sf/VS_COPY_TO_OUT_DIR + /prop_sf/VS_CSHARP_tagname + /prop_sf/VS_DEPLOYMENT_CONTENT + /prop_sf/VS_DEPLOYMENT_LOCATION + /prop_sf/VS_INCLUDE_IN_VSIX + /prop_sf/VS_RESOURCE_GENERATOR + /prop_sf/VS_SETTINGS + /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 + /prop_sf/XCODE_EXPLICIT_FILE_TYPE + /prop_sf/XCODE_FILE_ATTRIBUTES + /prop_sf/XCODE_LAST_KNOWN_FILE_TYPE + +.. _`Cache Entry Properties`: + +Properties on Cache Entries +=========================== + +.. toctree:: + :maxdepth: 1 + + /prop_cache/ADVANCED + /prop_cache/HELPSTRING + /prop_cache/MODIFIED + /prop_cache/STRINGS + /prop_cache/TYPE + /prop_cache/VALUE + +.. _`Installed File Properties`: + +Properties on Installed Files +============================= + +.. toctree:: + :maxdepth: 1 + + /prop_inst/CPACK_DESKTOP_SHORTCUTS.rst + /prop_inst/CPACK_NEVER_OVERWRITE.rst + /prop_inst/CPACK_PERMANENT.rst + /prop_inst/CPACK_START_MENU_SHORTCUTS.rst + /prop_inst/CPACK_STARTUP_SHORTCUTS.rst + /prop_inst/CPACK_WIX_ACL.rst + + +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 +================================ + +.. toctree:: + :maxdepth: 1 + + /prop_tgt/COMPILE_DEFINITIONS_CONFIG + /prop_tgt/POST_INSTALL_SCRIPT + /prop_tgt/PRE_INSTALL_SCRIPT + + +Deprecated Properties on Source Files +===================================== + +.. toctree:: + :maxdepth: 1 + + /prop_sf/COMPILE_DEFINITIONS_CONFIG diff --git a/Help/manual/cmake-qt.7.rst b/Help/manual/cmake-qt.7.rst new file mode 100644 index 0000000..f156f95 --- /dev/null +++ b/Help/manual/cmake-qt.7.rst @@ -0,0 +1,262 @@ +.. cmake-manual-description: CMake Qt Features Reference + +cmake-qt(7) +*********** + +.. only:: html + + .. contents:: + +Introduction +============ + +CMake can find and use Qt 4 and Qt 5 libraries. The Qt 4 libraries are found +by the :module:`FindQt4` find-module shipped with CMake, whereas the +Qt 5 libraries are found using "Config-file Packages" shipped with Qt 5. See +:manual:`cmake-packages(7)` for more information about CMake packages, and +see `the Qt cmake manual <http://qt-project.org/doc/qt-5/cmake-manual.html>`_ +for your Qt version. + +Qt 4 and Qt 5 may be used together in the same +:manual:`CMake buildsystem <cmake-buildsystem(7)>`: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.8.0 FATAL_ERROR) + + project(Qt4And5) + + set(CMAKE_AUTOMOC ON) + + find_package(Qt5 COMPONENTS Widgets DBus REQUIRED) + add_executable(publisher publisher.cpp) + target_link_libraries(publisher Qt5::Widgets Qt5::DBus) + + find_package(Qt4 REQUIRED) + add_executable(subscriber subscriber.cpp) + target_link_libraries(subscriber Qt4::QtGui Qt4::QtDBus) + +A CMake target may not link to both Qt 4 and Qt 5. A diagnostic is issued if +this is attempted or results from transitive target dependency evaluation. + +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 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. + +.. _`Qt AUTOMOC`: + +AUTOMOC +^^^^^^^ + +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 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 +``#include``. + +Included ``moc_*.cpp`` and ``*.moc`` files will be generated in the +``<AUTOGEN_BUILD_DIR>/include`` directory which is +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 +folders to avoid name collisions and included in a separate +file which is compiled into the target, named either +``<AUTOGEN_BUILD_DIR>/mocs_compilation.cpp`` or +``<AUTOGEN_BUILD_DIR>/mocs_compilation_$<CONFIG>.cpp``. + +* See :prop_tgt:`AUTOGEN_BUILD_DIR`. + +The ``moc`` command line will consume the :prop_tgt:`COMPILE_DEFINITIONS` and +:prop_tgt:`INCLUDE_DIRECTORIES` target properties from the target it is being +invoked for, and for the appropriate build configuration. + +The :prop_tgt:`AUTOMOC` target property may be pre-set for all +following targets by setting the :variable:`CMAKE_AUTOMOC` variable. The +:prop_tgt:`AUTOMOC_MOC_OPTIONS` target property may be populated to set +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`. + +Source C++ files can be excluded from :prop_tgt:`AUTOMOC` processing by +enabling :prop_sf:`SKIP_AUTOMOC` or the broader :prop_sf:`SKIP_AUTOGEN`. + +.. _`Qt AUTOUIC`: + +AUTOUIC +^^^^^^^ + +The :prop_tgt:`AUTOUIC` target property controls whether :manual:`cmake(1)` +inspects the C++ files in the target to determine if they require ``uic`` to +be run, and to create rules to execute ``uic`` at the appropriate time. + +If a preprocessor ``#include`` directive is found which matches +``<path>ui_<basename>.h``, and a ``<basename>.ui`` file exists, +then ``uic`` will be executed to generate the appropriate file. +The ``<basename>.ui`` file is searched for in the following places + +1. ``<source_dir>/<basename>.ui`` +2. ``<source_dir>/<path><basename>.ui`` +3. ``<AUTOUIC_SEARCH_PATHS>/<basename>.ui`` +4. ``<AUTOUIC_SEARCH_PATHS>/<path><basename>.ui`` + +where ``<source_dir>`` is the directory of the C++ file and +:prop_tgt:`AUTOUIC_SEARCH_PATHS` is a list of additional search paths. + +The generated generated ``ui_*.h`` files are placed in the +``<AUTOGEN_BUILD_DIR>/include`` directory which is +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 +targets by setting the :variable:`CMAKE_AUTOUIC` variable. The +:prop_tgt:`AUTOUIC_OPTIONS` target property may be populated to set options +to pass to ``uic``. The :variable:`CMAKE_AUTOUIC_OPTIONS` variable may be +populated to pre-set the options for all following targets. The +:prop_sf:`AUTOUIC_OPTIONS` source file property may be set on the +``<basename>.ui`` file to set particular options for the file. This +overrides options from the :prop_tgt:`AUTOUIC_OPTIONS` target property. + +A target may populate the :prop_tgt:`INTERFACE_AUTOUIC_OPTIONS` target +property with options that should be used when invoking ``uic``. This must be +consistent with the :prop_tgt:`AUTOUIC_OPTIONS` target property content of the +depender target. The :variable:`CMAKE_DEBUG_TARGET_PROPERTIES` variable may +be used to track the origin target of such +:prop_tgt:`INTERFACE_AUTOUIC_OPTIONS`. This means that a library which +provides an alternative translation system for Qt may specify options which +should be used when running ``uic``: + +.. code-block:: cmake + + add_library(KI18n klocalizedstring.cpp) + target_link_libraries(KI18n Qt5::Core) + + # KI18n uses the tr2i18n() function instead of tr(). That function is + # declared in the klocalizedstring.h header. + set(autouic_options + -tr tr2i18n + -include klocalizedstring.h + ) + + set_property(TARGET KI18n APPEND PROPERTY + INTERFACE_AUTOUIC_OPTIONS ${autouic_options} + ) + +A consuming project linking to the target exported from upstream automatically +uses appropriate options when ``uic`` is run by :prop_tgt:`AUTOUIC`, as a +result of linking with the :prop_tgt:`IMPORTED` target: + +.. code-block:: cmake + + set(CMAKE_AUTOUIC ON) + # Uses a libwidget.ui file: + add_library(LibWidget libwidget.cpp) + target_link_libraries(LibWidget + KF5::KI18n + Qt5::Widgets + ) + +Source files can be excluded from :prop_tgt:`AUTOUIC` processing by +enabling :prop_sf:`SKIP_AUTOUIC` or the broader :prop_sf:`SKIP_AUTOGEN`. + +.. _`Qt AUTORCC`: + +AUTORCC +^^^^^^^ + +The :prop_tgt:`AUTORCC` target property controls whether :manual:`cmake(1)` +creates rules to execute ``rcc`` at the appropriate time on source files +which have the suffix ``.qrc``. + +.. code-block:: cmake + + add_executable(myexe main.cpp resource_file.qrc) + +The :prop_tgt:`AUTORCC` target property may be pre-set for all following targets +by setting the :variable:`CMAKE_AUTORCC` variable. The +:prop_tgt:`AUTORCC_OPTIONS` target property may be populated to set options +to pass to ``rcc``. The :variable:`CMAKE_AUTORCC_OPTIONS` variable may be +populated to pre-set the options for all following targets. The +:prop_sf:`AUTORCC_OPTIONS` source file property may be set on the +``<name>.qrc`` file to set particular options for the file. This +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 +===================== + +The Qt 4 and 5 :prop_tgt:`IMPORTED` targets for the QtGui libraries specify +that the qtmain.lib static library shipped with Qt will be linked by all +dependent executables which have the :prop_tgt:`WIN32_EXECUTABLE` enabled. + +To disable this behavior, enable the ``Qt5_NO_LINK_QTMAIN`` target property for +Qt 5 based targets or ``QT4_NO_LINK_QTMAIN`` target property for Qt 4 based +targets. + +.. code-block:: cmake + + add_executable(myexe WIN32 main.cpp) + target_link_libraries(myexe Qt4::QtGui) + + add_executable(myexe_no_qtmain WIN32 main_no_qtmain.cpp) + set_property(TARGET main_no_qtmain PROPERTY QT4_NO_LINK_QTMAIN ON) + target_link_libraries(main_no_qtmain Qt4::QtGui) diff --git a/Help/manual/cmake-server.7.rst b/Help/manual/cmake-server.7.rst new file mode 100644 index 0000000..6c8d0f4 --- /dev/null +++ b/Help/manual/cmake-server.7.rst @@ -0,0 +1,7 @@ +.. cmake-manual-description: CMake Server + +cmake-server(7) +*************** + +The :manual:`cmake(1)` server mode has been removed since CMake 3.20. +Clients should use the :manual:`cmake-file-api(7)` instead. diff --git a/Help/manual/cmake-toolchains.7.rst b/Help/manual/cmake-toolchains.7.rst new file mode 100644 index 0000000..a941310 --- /dev/null +++ b/Help/manual/cmake-toolchains.7.rst @@ -0,0 +1,672 @@ +.. cmake-manual-description: CMake Toolchains Reference + +cmake-toolchains(7) +******************* + +.. only:: html + + .. contents:: + +Introduction +============ + +CMake uses a toolchain of utilities to compile, link libraries and create +archives, and other tasks to drive the build. The toolchain utilities available +are determined by the languages enabled. In normal builds, CMake automatically +determines the toolchain for host builds based on system introspection and +defaults. In cross-compiling scenarios, a toolchain file may be specified +with information about compiler and utility paths. + +Languages +========= + +Languages are enabled by the :command:`project` command. Language-specific +built-in variables, such as +:variable:`CMAKE_CXX_COMPILER <CMAKE_<LANG>_COMPILER>`, +: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``: + +.. code-block:: cmake + + project(C_Only C) + +A special value of ``NONE`` can also be used with the :command:`project` command +to enable no languages: + +.. code-block:: cmake + + project(MyProject NONE) + +The :command:`enable_language` command can be used to enable languages after the +:command:`project` command: + +.. code-block:: cmake + + enable_language(CXX) + +When a language is enabled, CMake finds a compiler for that language, and +determines some information, such as the vendor and version of the compiler, +the target architecture and bitwidth, the location of corresponding utilities +etc. + +The :prop_gbl:`ENABLED_LANGUAGES` global property contains the languages which +are currently enabled. + +Variables and Properties +======================== + +Several variables relate to the language components of a toolchain which are +enabled. :variable:`CMAKE_<LANG>_COMPILER` is the full path to the compiler used +for ``<LANG>``. :variable:`CMAKE_<LANG>_COMPILER_ID` is the identifier used +by CMake for the compiler and :variable:`CMAKE_<LANG>_COMPILER_VERSION` is the +version of the compiler. + +The :variable:`CMAKE_<LANG>_FLAGS` variables and the configuration-specific +equivalents contain flags that will be added to the compile command when +compiling a file of a particular language. + +As the linker is invoked by the compiler driver, CMake needs a way to determine +which compiler to use to invoke the linker. This is calculated by the +:prop_sf:`LANGUAGE` of source files in the target, and in the case of static +libraries, the language of the dependent libraries. The choice CMake makes may +be overridden with the :prop_tgt:`LINKER_LANGUAGE` target property. + +Toolchain Features +================== + +CMake provides the :command:`try_compile` command and wrapper macros such as +:module:`CheckCXXSourceCompiles`, :module:`CheckCXXSymbolExists` and +:module:`CheckIncludeFile` to test capability and availability of various +toolchain features. These APIs test the toolchain in some way and cache the +result so that the test does not have to be performed again the next time +CMake runs. + +Some toolchain features have built-in handling in CMake, and do not require +compile-tests. For example, :prop_tgt:`POSITION_INDEPENDENT_CODE` allows +specifying that a target should be built as position-independent code, if +the compiler supports that feature. The :prop_tgt:`<LANG>_VISIBILITY_PRESET` +and :prop_tgt:`VISIBILITY_INLINES_HIDDEN` target properties add flags for +hidden visibility, if supported by the compiler. + +.. _`Cross Compiling Toolchain`: + +Cross Compiling +=============== + +If :manual:`cmake(1)` is invoked with the command line parameter +``--toolchain path/to/file`` or ``-DCMAKE_TOOLCHAIN_FILE=path/to/file``, the +file will be loaded early to set 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 +------------------------- + +A typical cross-compiling toolchain for Linux has content such +as: + +.. code-block:: cmake + + set(CMAKE_SYSTEM_NAME Linux) + set(CMAKE_SYSTEM_PROCESSOR arm) + + set(CMAKE_SYSROOT /home/devel/rasp-pi-rootfs) + set(CMAKE_STAGING_PREFIX /home/devel/stage) + + set(tools /home/devel/gcc-4.7-linaro-rpi-gnueabihf) + set(CMAKE_C_COMPILER ${tools}/bin/arm-linux-gnueabihf-gcc) + set(CMAKE_CXX_COMPILER ${tools}/bin/arm-linux-gnueabihf-g++) + + set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER) + set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY) + set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY) + set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY) + +The :variable:`CMAKE_SYSTEM_NAME` is the CMake-identifier of the target platform +to build for. + +The :variable:`CMAKE_SYSTEM_PROCESSOR` is the CMake-identifier of the target architecture +to build for. + +The :variable:`CMAKE_SYSROOT` is optional, and may be specified if a sysroot +is available. + +The :variable:`CMAKE_STAGING_PREFIX` is also optional. It may be used to specify +a path on the host to install to. The :variable:`CMAKE_INSTALL_PREFIX` is always +the runtime installation location, even when cross-compiling. + +The :variable:`CMAKE_<LANG>_COMPILER` variables may be set to full paths, or to +names of compilers to search for in standard locations. For toolchains that +do not support linking binaries without custom flags or scripts one may set +the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable to ``STATIC_LIBRARY`` +to tell CMake not to try to link executables during its checks. + +CMake ``find_*`` commands will look in the sysroot, and the :variable:`CMAKE_FIND_ROOT_PATH` +entries by default in all cases, as well as looking in the host system root prefix. +Although this can be controlled on a case-by-case basis, when cross-compiling, it +can be useful to exclude looking in either the host or the target for particular +artifacts. Generally, includes, libraries and packages should be found in the +target system prefixes, whereas executables which must be run as part of the build +should be found only on the host and not on the target. This is the purpose of +the ``CMAKE_FIND_ROOT_PATH_MODE_*`` variables. + +.. _`Cray Cross-Compile`: + +Cross Compiling for the Cray Linux Environment +---------------------------------------------- + +Cross compiling for compute nodes in the Cray Linux Environment can be done +without needing a separate toolchain file. Specifying +``-DCMAKE_SYSTEM_NAME=CrayLinuxEnvironment`` on the CMake command line will +ensure that the appropriate build settings and search paths are configured. +The platform will pull its configuration from the current environment +variables and will configure a project to use the compiler wrappers from the +Cray Programming Environment's ``PrgEnv-*`` modules if present and loaded. + +The default configuration of the Cray Programming Environment is to only +support static libraries. This can be overridden and shared libraries +enabled by setting the ``CRAYPE_LINK_TYPE`` environment variable to +``dynamic``. + +Running CMake without specifying :variable:`CMAKE_SYSTEM_NAME` will +run the configure step in host mode assuming a standard Linux environment. +If not overridden, the ``PrgEnv-*`` compiler wrappers will end up getting used, +which if targeting the either the login node or compute node, is likely not the +desired behavior. The exception to this would be if you are building directly +on a NID instead of cross-compiling from a login node. If trying to build +software for a login node, you will need to either first unload the +currently loaded ``PrgEnv-*`` module or explicitly tell CMake to use the +system compilers in ``/usr/bin`` instead of the Cray wrappers. If instead +targeting a compute node is desired, just specify the +:variable:`CMAKE_SYSTEM_NAME` as mentioned above. + +Cross Compiling using Clang +--------------------------- + +Some compilers such as Clang are inherently cross compilers. +The :variable:`CMAKE_<LANG>_COMPILER_TARGET` can be set to pass a +value to those supported compilers when compiling: + +.. code-block:: cmake + + set(CMAKE_SYSTEM_NAME Linux) + set(CMAKE_SYSTEM_PROCESSOR arm) + + set(triple arm-linux-gnueabihf) + + set(CMAKE_C_COMPILER clang) + set(CMAKE_C_COMPILER_TARGET ${triple}) + set(CMAKE_CXX_COMPILER clang++) + set(CMAKE_CXX_COMPILER_TARGET ${triple}) + +Similarly, some compilers do not ship their own supplementary utilities +such as linkers, but provide a way to specify the location of the external +toolchain which will be used by the compiler driver. The +:variable:`CMAKE_<LANG>_COMPILER_EXTERNAL_TOOLCHAIN` variable can be set in a +toolchain file to pass the path to the compiler driver. + +Cross Compiling for QNX +----------------------- + +As the Clang compiler the QNX QCC compile is inherently a cross compiler. +And the :variable:`CMAKE_<LANG>_COMPILER_TARGET` can be set to pass a +value to those supported compilers when compiling: + +.. code-block:: cmake + + set(CMAKE_SYSTEM_NAME QNX) + + set(arch gcc_ntoarmv7le) + + set(CMAKE_C_COMPILER qcc) + set(CMAKE_C_COMPILER_TARGET ${arch}) + set(CMAKE_CXX_COMPILER QCC) + set(CMAKE_CXX_COMPILER_TARGET ${arch}) + + set(CMAKE_SYSROOT $ENV{QNX_TARGET}) + + +Cross Compiling for Windows CE +------------------------------ + +Cross compiling for Windows CE requires the corresponding SDK being +installed on your system. These SDKs are usually installed under +``C:/Program Files (x86)/Windows CE Tools/SDKs``. + +A toolchain file to configure a Visual Studio generator for +Windows CE may look like this: + +.. code-block:: cmake + + set(CMAKE_SYSTEM_NAME WindowsCE) + + set(CMAKE_SYSTEM_VERSION 8.0) + set(CMAKE_SYSTEM_PROCESSOR arm) + + set(CMAKE_GENERATOR_TOOLSET CE800) # Can be omitted for 8.0 + set(CMAKE_GENERATOR_PLATFORM SDK_AM335X_SK_WEC2013_V310) + +The :variable:`CMAKE_GENERATOR_PLATFORM` tells the generator which SDK to use. +Further :variable:`CMAKE_SYSTEM_VERSION` tells the generator what version of +Windows CE to use. Currently version 8.0 (Windows Embedded Compact 2013) is +supported out of the box. Other versions may require one to set +:variable:`CMAKE_GENERATOR_TOOLSET` to the correct value. + +Cross Compiling for Windows 10 Universal Applications +----------------------------------------------------- + +A toolchain file to configure a Visual Studio generator for a +Windows 10 Universal Application may look like this: + +.. code-block:: cmake + + set(CMAKE_SYSTEM_NAME WindowsStore) + set(CMAKE_SYSTEM_VERSION 10.0) + +A Windows 10 Universal Application targets both Windows Store and +Windows Phone. Specify the :variable:`CMAKE_SYSTEM_VERSION` variable +to be ``10.0`` to build with the latest available Windows 10 SDK. +Specify a more specific version (e.g. ``10.0.10240.0`` for RTM) +to build with the corresponding SDK. + +Cross Compiling for Windows Phone +--------------------------------- + +A toolchain file to configure a Visual Studio generator for +Windows Phone may look like this: + +.. code-block:: cmake + + set(CMAKE_SYSTEM_NAME WindowsPhone) + set(CMAKE_SYSTEM_VERSION 8.1) + +Cross Compiling for Windows Store +--------------------------------- + +A toolchain file to configure a Visual Studio generator for +Windows Store may look like this: + +.. code-block:: cmake + + set(CMAKE_SYSTEM_NAME WindowsStore) + set(CMAKE_SYSTEM_VERSION 8.1) + +.. _`Cross Compiling for Android`: + +Cross Compiling for Android +--------------------------- + +A toolchain file may configure cross-compiling for Android by setting the +:variable:`CMAKE_SYSTEM_NAME` variable to ``Android``. Further configuration +is specific to the Android development environment to be used. + +For :ref:`Visual Studio Generators`, CMake expects :ref:`NVIDIA Nsight Tegra +Visual Studio Edition <Cross Compiling for Android with NVIDIA Nsight Tegra +Visual Studio Edition>` or the :ref:`Visual Studio tools for Android +<Cross Compiling for Android with the NDK>` to be installed. See those sections +for further configuration details. + +For :ref:`Makefile Generators` and the :generator:`Ninja` generator, +CMake expects one of these environments: + +* :ref:`NDK <Cross Compiling for Android with the NDK>` +* :ref:`Standalone Toolchain <Cross Compiling for Android with a Standalone Toolchain>` + +CMake uses the following steps to select one of the environments: + +* If the :variable:`CMAKE_ANDROID_NDK` variable is set, the NDK at the + specified location will be used. + +* Else, if the :variable:`CMAKE_ANDROID_STANDALONE_TOOLCHAIN` variable + is set, the Standalone Toolchain at the specified location will be used. + +* Else, if the :variable:`CMAKE_SYSROOT` variable is set to a directory + of the form ``<ndk>/platforms/android-<api>/arch-<arch>``, the ``<ndk>`` + part will be used as the value of :variable:`CMAKE_ANDROID_NDK` and the + NDK will be used. + +* Else, if the :variable:`CMAKE_SYSROOT` variable is set to a directory of the + form ``<standalone-toolchain>/sysroot``, the ``<standalone-toolchain>`` part + will be used as the value of :variable:`CMAKE_ANDROID_STANDALONE_TOOLCHAIN` + and the Standalone Toolchain will be used. + +* Else, if a cmake variable ``ANDROID_NDK`` is set it will be used + as the value of :variable:`CMAKE_ANDROID_NDK`, and the NDK will be used. + +* Else, if a cmake variable ``ANDROID_STANDALONE_TOOLCHAIN`` is set, it will be + used as the value of :variable:`CMAKE_ANDROID_STANDALONE_TOOLCHAIN`, and the + Standalone Toolchain will be used. + +* Else, if an environment variable ``ANDROID_NDK_ROOT`` or + ``ANDROID_NDK`` is set, it will be used as the value of + :variable:`CMAKE_ANDROID_NDK`, and the NDK will be used. + +* Else, if an environment variable ``ANDROID_STANDALONE_TOOLCHAIN`` is + set then it will be used as the value of + :variable:`CMAKE_ANDROID_STANDALONE_TOOLCHAIN`, and the Standalone + Toolchain will be used. + +* Else, an error diagnostic will be issued that neither the NDK or + Standalone Toolchain can be found. + +.. versionadded:: 3.20 + If an Android NDK is selected, its version number is reported + in the :variable:`CMAKE_ANDROID_NDK_VERSION` variable. + +.. _`Cross Compiling for Android with the NDK`: + +Cross Compiling for Android with the NDK +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A toolchain file may configure :ref:`Makefile Generators`, +:ref:`Ninja Generators`, or :ref:`Visual Studio Generators` to target +Android for cross-compiling. + +Configure use of an Android NDK with the following variables: + +:variable:`CMAKE_SYSTEM_NAME` + Set to ``Android``. Must be specified to enable cross compiling + for Android. + +:variable:`CMAKE_SYSTEM_VERSION` + Set to the Android API level. If not specified, the value is + determined as follows: + + * If the :variable:`CMAKE_ANDROID_API` variable is set, its value + is used as the API level. + * If the :variable:`CMAKE_SYSROOT` variable is set, the API level is + detected from the NDK directory structure containing the sysroot. + * Otherwise, the latest API level available in the NDK is used. + +:variable:`CMAKE_ANDROID_ARCH_ABI` + Set to the Android ABI (architecture). If not specified, this + variable will default to the first supported ABI in the list of + ``armeabi``, ``armeabi-v7a`` and ``arm64-v8a``. + The :variable:`CMAKE_ANDROID_ARCH` variable will be computed + from ``CMAKE_ANDROID_ARCH_ABI`` automatically. + Also see the :variable:`CMAKE_ANDROID_ARM_MODE` and + :variable:`CMAKE_ANDROID_ARM_NEON` variables. + +:variable:`CMAKE_ANDROID_NDK` + Set to the absolute path to the Android NDK root directory. + If not specified, a default for this variable will be chosen + as specified :ref:`above <Cross Compiling for Android>`. + +:variable:`CMAKE_ANDROID_NDK_DEPRECATED_HEADERS` + Set to a true value to use the deprecated per-api-level headers + instead of the unified headers. If not specified, the default will + be false unless using a NDK that does not provide unified headers. + +:variable:`CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION` + 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, + a default will be selected as described in the variable documentation. + +The following variables will be computed and provided automatically: + +:variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX` + The absolute path prefix to the binutils in the NDK toolchain. + +:variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX` + The host platform suffix of the binutils in the NDK toolchain. + + +For example, a toolchain file might contain: + +.. code-block:: cmake + + set(CMAKE_SYSTEM_NAME Android) + set(CMAKE_SYSTEM_VERSION 21) # API level + set(CMAKE_ANDROID_ARCH_ABI arm64-v8a) + set(CMAKE_ANDROID_NDK /path/to/android-ndk) + set(CMAKE_ANDROID_STL_TYPE gnustl_static) + +Alternatively one may specify the values without a toolchain file: + +.. code-block:: console + + $ cmake ../src \ + -DCMAKE_SYSTEM_NAME=Android \ + -DCMAKE_SYSTEM_VERSION=21 \ + -DCMAKE_ANDROID_ARCH_ABI=arm64-v8a \ + -DCMAKE_ANDROID_NDK=/path/to/android-ndk \ + -DCMAKE_ANDROID_STL_TYPE=gnustl_static + +.. _`Cross Compiling for Android with a Standalone Toolchain`: + +Cross Compiling for Android with a Standalone Toolchain +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A toolchain file may configure :ref:`Makefile Generators` or the +:generator:`Ninja` generator to target Android for cross-compiling +using a standalone toolchain. + +Configure use of an Android standalone toolchain with the following variables: + +:variable:`CMAKE_SYSTEM_NAME` + Set to ``Android``. Must be specified to enable cross compiling + for Android. + +:variable:`CMAKE_ANDROID_STANDALONE_TOOLCHAIN` + Set to the absolute path to the standalone toolchain root directory. + A ``${CMAKE_ANDROID_STANDALONE_TOOLCHAIN}/sysroot`` directory + must exist. + If not specified, a default for this variable will be chosen + as specified :ref:`above <Cross Compiling for Android>`. + +:variable:`CMAKE_ANDROID_ARM_MODE` + When the standalone toolchain targets ARM, optionally set this to ``ON`` + to target 32-bit ARM instead of 16-bit Thumb. + See variable documentation for details. + +:variable:`CMAKE_ANDROID_ARM_NEON` + When the standalone toolchain targets ARM v7, optionally set thisto ``ON`` + to target ARM NEON devices. See variable documentation for details. + +The following variables will be computed and provided automatically: + +:variable:`CMAKE_SYSTEM_VERSION` + The Android API level detected from the standalone toolchain. + +:variable:`CMAKE_ANDROID_ARCH_ABI` + 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. + +:variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX` + The host platform suffix of the ``binutils`` in the standalone toolchain. + +For example, a toolchain file might contain: + +.. code-block:: cmake + + set(CMAKE_SYSTEM_NAME Android) + set(CMAKE_ANDROID_STANDALONE_TOOLCHAIN /path/to/android-toolchain) + +Alternatively one may specify the values without a toolchain file: + +.. code-block:: console + + $ cmake ../src \ + -DCMAKE_SYSTEM_NAME=Android \ + -DCMAKE_ANDROID_STANDALONE_TOOLCHAIN=/path/to/android-toolchain + +.. _`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio Edition`: + +Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio Edition +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A toolchain file to configure one of the :ref:`Visual Studio Generators` +to build using NVIDIA Nsight Tegra targeting Android may look like this: + +.. code-block:: cmake + + set(CMAKE_SYSTEM_NAME Android) + +The :variable:`CMAKE_GENERATOR_TOOLSET` may be set to select +the Nsight Tegra "Toolchain Version" value. + +See also target properties: + +* :prop_tgt:`ANDROID_ANT_ADDITIONAL_OPTIONS` +* :prop_tgt:`ANDROID_API_MIN` +* :prop_tgt:`ANDROID_API` +* :prop_tgt:`ANDROID_ARCH` +* :prop_tgt:`ANDROID_ASSETS_DIRECTORIES` +* :prop_tgt:`ANDROID_GUI` +* :prop_tgt:`ANDROID_JAR_DEPENDENCIES` +* :prop_tgt:`ANDROID_JAR_DIRECTORIES` +* :prop_tgt:`ANDROID_JAVA_SOURCE_DIR` +* :prop_tgt:`ANDROID_NATIVE_LIB_DEPENDENCIES` +* :prop_tgt:`ANDROID_NATIVE_LIB_DIRECTORIES` +* :prop_tgt:`ANDROID_PROCESS_MAX` +* :prop_tgt:`ANDROID_PROGUARD_CONFIG_PATH` +* :prop_tgt:`ANDROID_PROGUARD` +* :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 new file mode 100644 index 0000000..37ef053 --- /dev/null +++ b/Help/manual/cmake-variables.7.rst @@ -0,0 +1,706 @@ +.. cmake-manual-description: CMake Variables Reference + +cmake-variables(7) +****************** + +.. only:: html + + .. 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. + +.. include:: ID_RESERVE.txt + +Variables that Provide Information +================================== + +.. toctree:: + :maxdepth: 1 + + /variable/CMAKE_AR + /variable/CMAKE_ARGC + /variable/CMAKE_ARGV0 + /variable/CMAKE_BINARY_DIR + /variable/CMAKE_BUILD_TOOL + /variable/CMAKE_CACHE_MAJOR_VERSION + /variable/CMAKE_CACHE_MINOR_VERSION + /variable/CMAKE_CACHE_PATCH_VERSION + /variable/CMAKE_CACHEFILE_DIR + /variable/CMAKE_CFG_INTDIR + /variable/CMAKE_COMMAND + /variable/CMAKE_CPACK_COMMAND + /variable/CMAKE_CROSSCOMPILING + /variable/CMAKE_CROSSCOMPILING_EMULATOR + /variable/CMAKE_CTEST_COMMAND + /variable/CMAKE_CURRENT_BINARY_DIR + /variable/CMAKE_CURRENT_FUNCTION + /variable/CMAKE_CURRENT_FUNCTION_LIST_DIR + /variable/CMAKE_CURRENT_FUNCTION_LIST_FILE + /variable/CMAKE_CURRENT_FUNCTION_LIST_LINE + /variable/CMAKE_CURRENT_LIST_DIR + /variable/CMAKE_CURRENT_LIST_FILE + /variable/CMAKE_CURRENT_LIST_LINE + /variable/CMAKE_CURRENT_SOURCE_DIR + /variable/CMAKE_DEBUG_TARGET_PROPERTIES + /variable/CMAKE_DIRECTORY_LABELS + /variable/CMAKE_DL_LIBS + /variable/CMAKE_DOTNET_TARGET_FRAMEWORK + /variable/CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION + /variable/CMAKE_EDIT_COMMAND + /variable/CMAKE_EXECUTABLE_SUFFIX + /variable/CMAKE_EXTRA_GENERATOR + /variable/CMAKE_EXTRA_SHARED_LIBRARY_SUFFIXES + /variable/CMAKE_FIND_DEBUG_MODE + /variable/CMAKE_FIND_PACKAGE_NAME + /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_IMPORT_LIBRARY_PREFIX + /variable/CMAKE_IMPORT_LIBRARY_SUFFIX + /variable/CMAKE_JOB_POOL_COMPILE + /variable/CMAKE_JOB_POOL_LINK + /variable/CMAKE_JOB_POOL_PRECOMPILE_HEADER + /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 + /variable/CMAKE_MAJOR_VERSION + /variable/CMAKE_MAKE_PROGRAM + /variable/CMAKE_MATCH_COUNT + /variable/CMAKE_MATCH_n + /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 + /variable/CMAKE_SHARED_MODULE_PREFIX + /variable/CMAKE_SHARED_MODULE_SUFFIX + /variable/CMAKE_SIZEOF_VOID_P + /variable/CMAKE_SKIP_INSTALL_RULES + /variable/CMAKE_SKIP_RPATH + /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_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_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM + /variable/CMAKE_XCODE_BUILD_SYSTEM + /variable/CMAKE_XCODE_PLATFORM_TOOLSET + /variable/PROJECT-NAME_BINARY_DIR + /variable/PROJECT-NAME_DESCRIPTION + /variable/PROJECT-NAME_HOMEPAGE_URL + /variable/PROJECT-NAME_IS_TOP_LEVEL + /variable/PROJECT-NAME_SOURCE_DIR + /variable/PROJECT-NAME_VERSION + /variable/PROJECT-NAME_VERSION_MAJOR + /variable/PROJECT-NAME_VERSION_MINOR + /variable/PROJECT-NAME_VERSION_PATCH + /variable/PROJECT-NAME_VERSION_TWEAK + /variable/PROJECT_BINARY_DIR + /variable/PROJECT_DESCRIPTION + /variable/PROJECT_HOMEPAGE_URL + /variable/PROJECT_IS_TOP_LEVEL + /variable/PROJECT_NAME + /variable/PROJECT_SOURCE_DIR + /variable/PROJECT_VERSION + /variable/PROJECT_VERSION_MAJOR + /variable/PROJECT_VERSION_MINOR + /variable/PROJECT_VERSION_PATCH + /variable/PROJECT_VERSION_TWEAK + +Variables that Change Behavior +============================== + +.. toctree:: + :maxdepth: 1 + + /variable/BUILD_SHARED_LIBS + /variable/CMAKE_ABSOLUTE_DESTINATION_FILES + /variable/CMAKE_APPBUNDLE_PATH + /variable/CMAKE_AUTOMOC_RELAXED_MODE + /variable/CMAKE_BACKWARDS_COMPATIBILITY + /variable/CMAKE_BUILD_TYPE + /variable/CMAKE_CLANG_VFS_OVERLAY + /variable/CMAKE_CODEBLOCKS_COMPILER_ID + /variable/CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES + /variable/CMAKE_CODELITE_USE_TARGETS + /variable/CMAKE_COLOR_MAKEFILE + /variable/CMAKE_CONFIGURATION_TYPES + /variable/CMAKE_DEPENDS_IN_PROJECT_ONLY + /variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName + /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 + /variable/CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX + /variable/CMAKE_FIND_LIBRARY_PREFIXES + /variable/CMAKE_FIND_LIBRARY_SUFFIXES + /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_MESSAGE_CONTEXT + /variable/CMAKE_MESSAGE_CONTEXT_SHOW + /variable/CMAKE_MESSAGE_INDENT + /variable/CMAKE_MESSAGE_LOG_LEVEL + /variable/CMAKE_MODULE_PATH + /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_PROJECT_PROJECT-NAME_INCLUDE_BEFORE + /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 + /variable/CMAKE_SYSTEM_APPBUNDLE_PATH + /variable/CMAKE_SYSTEM_FRAMEWORK_PATH + /variable/CMAKE_SYSTEM_IGNORE_PATH + /variable/CMAKE_SYSTEM_INCLUDE_PATH + /variable/CMAKE_SYSTEM_LIBRARY_PATH + /variable/CMAKE_SYSTEM_PREFIX_PATH + /variable/CMAKE_SYSTEM_PROGRAM_PATH + /variable/CMAKE_USER_MAKE_RULES_OVERRIDE + /variable/CMAKE_WARN_DEPRECATED + /variable/CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION + /variable/CMAKE_XCODE_GENERATE_SCHEME + /variable/CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY + /variable/CMAKE_XCODE_LINK_BUILD_PHASE_MODE + /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_ENVIRONMENT + /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_WORKING_DIRECTORY + /variable/CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS + /variable/PackageName_ROOT + +Variables that Describe the System +================================== + +.. toctree:: + :maxdepth: 1 + + /variable/ANDROID + /variable/APPLE + /variable/BORLAND + /variable/CMAKE_ANDROID_NDK_VERSION + /variable/CMAKE_CL_64 + /variable/CMAKE_COMPILER_2005 + /variable/CMAKE_HOST_APPLE + /variable/CMAKE_HOST_SOLARIS + /variable/CMAKE_HOST_SYSTEM + /variable/CMAKE_HOST_SYSTEM_NAME + /variable/CMAKE_HOST_SYSTEM_PROCESSOR + /variable/CMAKE_HOST_SYSTEM_VERSION + /variable/CMAKE_HOST_UNIX + /variable/CMAKE_HOST_WIN32 + /variable/CMAKE_LIBRARY_ARCHITECTURE + /variable/CMAKE_LIBRARY_ARCHITECTURE_REGEX + /variable/CMAKE_OBJECT_PATH_MAX + /variable/CMAKE_SYSTEM + /variable/CMAKE_SYSTEM_NAME + /variable/CMAKE_SYSTEM_PROCESSOR + /variable/CMAKE_SYSTEM_VERSION + /variable/CYGWIN + /variable/GHS-MULTI + /variable/IOS + /variable/MINGW + /variable/MSVC + /variable/MSVC10 + /variable/MSVC11 + /variable/MSVC12 + /variable/MSVC14 + /variable/MSVC60 + /variable/MSVC70 + /variable/MSVC71 + /variable/MSVC80 + /variable/MSVC90 + /variable/MSVC_IDE + /variable/MSVC_TOOLSET_VERSION + /variable/MSVC_VERSION + /variable/MSYS + /variable/UNIX + /variable/WIN32 + /variable/WINCE + /variable/WINDOWS_PHONE + /variable/WINDOWS_STORE + /variable/XCODE + /variable/XCODE_VERSION + +Variables that Control the Build +================================ + +.. toctree:: + :maxdepth: 1 + + /variable/CMAKE_AIX_EXPORT_ALL_SYMBOLS + /variable/CMAKE_ANDROID_ANT_ADDITIONAL_OPTIONS + /variable/CMAKE_ANDROID_API + /variable/CMAKE_ANDROID_API_MIN + /variable/CMAKE_ANDROID_ARCH + /variable/CMAKE_ANDROID_ARCH_ABI + /variable/CMAKE_ANDROID_ARM_MODE + /variable/CMAKE_ANDROID_ARM_NEON + /variable/CMAKE_ANDROID_ASSETS_DIRECTORIES + /variable/CMAKE_ANDROID_EXCEPTIONS + /variable/CMAKE_ANDROID_GUI + /variable/CMAKE_ANDROID_JAR_DEPENDENCIES + /variable/CMAKE_ANDROID_JAR_DIRECTORIES + /variable/CMAKE_ANDROID_JAVA_SOURCE_DIR + /variable/CMAKE_ANDROID_NATIVE_LIB_DEPENDENCIES + /variable/CMAKE_ANDROID_NATIVE_LIB_DIRECTORIES + /variable/CMAKE_ANDROID_NDK + /variable/CMAKE_ANDROID_NDK_DEPRECATED_HEADERS + /variable/CMAKE_ANDROID_NDK_TOOLCHAIN_HOST_TAG + /variable/CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION + /variable/CMAKE_ANDROID_PROCESS_MAX + /variable/CMAKE_ANDROID_PROGUARD + /variable/CMAKE_ANDROID_PROGUARD_CONFIG_PATH + /variable/CMAKE_ANDROID_RTTI + /variable/CMAKE_ANDROID_SECURE_PROPS_PATH + /variable/CMAKE_ANDROID_SKIP_ANT_STEP + /variable/CMAKE_ANDROID_STANDALONE_TOOLCHAIN + /variable/CMAKE_ANDROID_STL_TYPE + /variable/CMAKE_APPLE_SILICON_PROCESSOR + /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_CROSS_CONFIGS + /variable/CMAKE_CTEST_ARGUMENTS + /variable/CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS + /variable/CMAKE_CUDA_RUNTIME_LIBRARY + /variable/CMAKE_CUDA_SEPARABLE_COMPILATION + /variable/CMAKE_DEBUG_POSTFIX + /variable/CMAKE_DEFAULT_BUILD_TYPE + /variable/CMAKE_DEFAULT_CONFIGS + /variable/CMAKE_DISABLE_PRECOMPILE_HEADERS + /variable/CMAKE_DEPENDS_USE_COMPILER + /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_FRAMEWORK_MULTI_CONFIG_POSTFIX_CONFIG + /variable/CMAKE_Fortran_FORMAT + /variable/CMAKE_Fortran_MODULE_DIRECTORY + /variable/CMAKE_Fortran_PREPROCESS + /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 + /variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION_CONFIG + /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 + /variable/CMAKE_LIBRARY_PATH_FLAG + /variable/CMAKE_LINK_DEF_FILE_FLAG + /variable/CMAKE_LINK_DEPENDS_NO_SHARED + /variable/CMAKE_LINK_INTERFACE_LIBRARIES + /variable/CMAKE_LINK_LIBRARY_FILE_FLAG + /variable/CMAKE_LINK_LIBRARY_FLAG + /variable/CMAKE_LINK_WHAT_YOU_USE + /variable/CMAKE_MACOSX_BUNDLE + /variable/CMAKE_MACOSX_RPATH + /variable/CMAKE_MAP_IMPORTED_CONFIG_CONFIG + /variable/CMAKE_MODULE_LINKER_FLAGS + /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 + /variable/CMAKE_OPTIMIZE_DEPENDENCIES + /variable/CMAKE_OSX_ARCHITECTURES + /variable/CMAKE_OSX_DEPLOYMENT_TARGET + /variable/CMAKE_OSX_SYSROOT + /variable/CMAKE_PCH_WARN_INVALID + /variable/CMAKE_PCH_INSTANTIATE_TEMPLATES + /variable/CMAKE_PDB_OUTPUT_DIRECTORY + /variable/CMAKE_PDB_OUTPUT_DIRECTORY_CONFIG + /variable/CMAKE_POSITION_INDEPENDENT_CODE + /variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY + /variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY_CONFIG + /variable/CMAKE_SHARED_LINKER_FLAGS + /variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG + /variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG_INIT + /variable/CMAKE_SHARED_LINKER_FLAGS_INIT + /variable/CMAKE_SKIP_BUILD_RPATH + /variable/CMAKE_SKIP_INSTALL_RPATH + /variable/CMAKE_STATIC_LINKER_FLAGS + /variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG + /variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG_INIT + /variable/CMAKE_STATIC_LINKER_FLAGS_INIT + /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_UNITY_BUILD_UNIQUE_ID + /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 + /variable/EXECUTABLE_OUTPUT_PATH + /variable/LIBRARY_OUTPUT_PATH + +Variables for Languages +======================= + +.. toctree:: + :maxdepth: 1 + + /variable/CMAKE_COMPILER_IS_GNUCC + /variable/CMAKE_COMPILER_IS_GNUCXX + /variable/CMAKE_COMPILER_IS_GNUG77 + /variable/CMAKE_CUDA_ARCHITECTURES + /variable/CMAKE_CUDA_COMPILE_FEATURES + /variable/CMAKE_CUDA_EXTENSIONS + /variable/CMAKE_CUDA_HOST_COMPILER + /variable/CMAKE_CUDA_STANDARD + /variable/CMAKE_CUDA_STANDARD_REQUIRED + /variable/CMAKE_CUDA_TOOLKIT_INCLUDE_DIRECTORIES + /variable/CMAKE_CXX_COMPILE_FEATURES + /variable/CMAKE_CXX_EXTENSIONS + /variable/CMAKE_CXX_STANDARD + /variable/CMAKE_CXX_STANDARD_REQUIRED + /variable/CMAKE_C_COMPILE_FEATURES + /variable/CMAKE_C_EXTENSIONS + /variable/CMAKE_C_STANDARD + /variable/CMAKE_C_STANDARD_REQUIRED + /variable/CMAKE_Fortran_MODDIR_DEFAULT + /variable/CMAKE_Fortran_MODDIR_FLAG + /variable/CMAKE_Fortran_MODOUT_FLAG + /variable/CMAKE_ISPC_HEADER_DIRECTORY + /variable/CMAKE_ISPC_HEADER_SUFFIX + /variable/CMAKE_ISPC_INSTRUCTION_SETS + /variable/CMAKE_LANG_ANDROID_TOOLCHAIN_MACHINE + /variable/CMAKE_LANG_ANDROID_TOOLCHAIN_PREFIX + /variable/CMAKE_LANG_ANDROID_TOOLCHAIN_SUFFIX + /variable/CMAKE_LANG_ARCHIVE_APPEND + /variable/CMAKE_LANG_ARCHIVE_CREATE + /variable/CMAKE_LANG_ARCHIVE_FINISH + /variable/CMAKE_LANG_BYTE_ORDER + /variable/CMAKE_LANG_COMPILER + /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 + /variable/CMAKE_LANG_CREATE_SHARED_LIBRARY + /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 + /variable/CMAKE_LANG_FLAGS_MINSIZEREL + /variable/CMAKE_LANG_FLAGS_MINSIZEREL_INIT + /variable/CMAKE_LANG_FLAGS_RELEASE + /variable/CMAKE_LANG_FLAGS_RELEASE_INIT + /variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO + /variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT + /variable/CMAKE_LANG_IGNORE_EXTENSIONS + /variable/CMAKE_LANG_IMPLICIT_INCLUDE_DIRECTORIES + /variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES + /variable/CMAKE_LANG_IMPLICIT_LINK_FRAMEWORK_DIRECTORIES + /variable/CMAKE_LANG_IMPLICIT_LINK_LIBRARIES + /variable/CMAKE_LANG_LIBRARY_ARCHITECTURE + /variable/CMAKE_LANG_LINK_EXECUTABLE + /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_OUTPUT_EXTENSION + /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 + +Variables for CTest +=================== + +.. toctree:: + :maxdepth: 1 + + /variable/CTEST_BINARY_DIRECTORY + /variable/CTEST_BUILD_COMMAND + /variable/CTEST_BUILD_NAME + /variable/CTEST_BZR_COMMAND + /variable/CTEST_BZR_UPDATE_OPTIONS + /variable/CTEST_CHANGE_ID + /variable/CTEST_CHECKOUT_COMMAND + /variable/CTEST_CONFIGURATION_TYPE + /variable/CTEST_CONFIGURE_COMMAND + /variable/CTEST_COVERAGE_COMMAND + /variable/CTEST_COVERAGE_EXTRA_FLAGS + /variable/CTEST_CURL_OPTIONS + /variable/CTEST_CUSTOM_COVERAGE_EXCLUDE + /variable/CTEST_CUSTOM_ERROR_EXCEPTION + /variable/CTEST_CUSTOM_ERROR_MATCH + /variable/CTEST_CUSTOM_ERROR_POST_CONTEXT + /variable/CTEST_CUSTOM_ERROR_PRE_CONTEXT + /variable/CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE + /variable/CTEST_CUSTOM_MAXIMUM_NUMBER_OF_ERRORS + /variable/CTEST_CUSTOM_MAXIMUM_NUMBER_OF_WARNINGS + /variable/CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE + /variable/CTEST_CUSTOM_MEMCHECK_IGNORE + /variable/CTEST_CUSTOM_POST_MEMCHECK + /variable/CTEST_CUSTOM_POST_TEST + /variable/CTEST_CUSTOM_PRE_MEMCHECK + /variable/CTEST_CUSTOM_PRE_TEST + /variable/CTEST_CUSTOM_TESTS_IGNORE + /variable/CTEST_CUSTOM_WARNING_EXCEPTION + /variable/CTEST_CUSTOM_WARNING_MATCH + /variable/CTEST_CVS_CHECKOUT + /variable/CTEST_CVS_COMMAND + /variable/CTEST_CVS_UPDATE_OPTIONS + /variable/CTEST_DROP_LOCATION + /variable/CTEST_DROP_METHOD + /variable/CTEST_DROP_SITE + /variable/CTEST_DROP_SITE_CDASH + /variable/CTEST_DROP_SITE_PASSWORD + /variable/CTEST_DROP_SITE_USER + /variable/CTEST_EXTRA_COVERAGE_GLOB + /variable/CTEST_GIT_COMMAND + /variable/CTEST_GIT_INIT_SUBMODULES + /variable/CTEST_GIT_UPDATE_CUSTOM + /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 + /variable/CTEST_MEMORYCHECK_SUPPRESSIONS_FILE + /variable/CTEST_MEMORYCHECK_TYPE + /variable/CTEST_NIGHTLY_START_TIME + /variable/CTEST_P4_CLIENT + /variable/CTEST_P4_COMMAND + /variable/CTEST_P4_OPTIONS + /variable/CTEST_P4_UPDATE_OPTIONS + /variable/CTEST_RESOURCE_SPEC_FILE + /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 + /variable/CTEST_SVN_UPDATE_OPTIONS + /variable/CTEST_TEST_LOAD + /variable/CTEST_TEST_TIMEOUT + /variable/CTEST_TRIGGER_SITE + /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 +=================== + +.. toctree:: + :maxdepth: 1 + + /variable/CPACK_ABSOLUTE_DESTINATION_FILES + /variable/CPACK_COMPONENT_INCLUDE_TOPLEVEL_DIRECTORY + /variable/CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION + /variable/CPACK_INCLUDE_TOPLEVEL_DIRECTORY + /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 new file mode 100644 index 0000000..f416f86 --- /dev/null +++ b/Help/manual/cmake.1.rst @@ -0,0 +1,858 @@ +.. cmake-manual-description: CMake Command-Line Reference + +cmake(1) +******** + +Synopsis +======== + +.. parsed-literal:: + + `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 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`: + +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. + +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 + +``-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 :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. + +``-N`` + View mode only. + + Only load the cache. Do not actually run configure and generate + steps. + +``--graphviz=[file]`` + 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 + :module:`CMakeGraphVizOptions` for more details. + +``--system-information [file]`` + Dump information about this system. + + Dump a wide range of information about the current system. If run + 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``. + + To make a log level persist between CMake runs, set + :variable:`CMAKE_MESSAGE_LOG_LEVEL` as a cache variable instead. + If both the command line option and the variable are given, the command line + option takes precedence. + + For backward compatibility reasons, ``--loglevel`` is also accepted as a + synonym for this option. + +``--log-context`` + Enable the :command:`message` command outputting context attached to each + message. + + This option turns on showing context for the current CMake run only. + To make showing the context persistent for all subsequent CMake runs, set + :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` as a cache variable instead. + When this command line option is given, :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` + is ignored. + +``--debug-trycompile`` + 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 :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 + fail incorrectly. This option is best used for one try-compile at a + time, and only when debugging. + +``--debug-output`` + Put cmake in a debug mode. + + Print extra information during the cmake run like stack traces with + :command:`message(SEND_ERROR)` calls. + +``--debug-find`` + Put cmake find commands in a debug mode. + + Print extra find call information during the cmake run to standard + error. Output is designed for human consumption and not for parsing. + See also the :variable:`CMAKE_FIND_DEBUG_MODE` variable for debugging + a more local part of the project. + +``--trace`` + Put cmake in trace mode. + + Print a trace of all calls made and from where. + +``--trace-expand`` + Put cmake in trace mode. + + Like ``--trace``, but with variables expanded. + +``--trace-format=<format>`` + Put cmake in trace mode and sets the trace output format. + + ``<format>`` can be one of the following values. + + ``human`` + Prints each trace line in a human-readable format. This is the + default format. + + ``json-v1`` + Prints each line as a separate JSON document. Each document is + separated by a newline ( ``\n`` ). It is guaranteed that no + newline characters will be present inside a JSON document. + + JSON trace format: + + .. code-block:: json + + { + "file": "/full/path/to/the/CMake/file.txt", + "line": 0, + "cmd": "add_executable", + "args": ["foo", "bar"], + "time": 1579512535.9687231, + "frame": 2 + } + + The members are: + + ``file`` + The full path to the CMake source file where the function + was called. + + ``line`` + The line in ``file`` of the function call. + + ``defer`` + Optional member that is present when the function call was deferred + by :command:`cmake_language(DEFER)`. If present, its value is a + string containing the deferred call ``<id>``. + + ``cmd`` + The name of the function that was called. + + ``args`` + A string list of all function parameters. + + ``time`` + Timestamp (seconds since epoch) of the function call. + + ``frame`` + Stack frame depth of the function that was called. + + Additionally, the first JSON document outputted contains the + ``version`` key for the current major and minor version of the + + JSON trace format: + + .. code-block:: json + + { + "version": { + "major": 1, + "minor": 1 + } + } + + The members are: + + ``version`` + Indicates the version of the JSON format. The version has a + major and minor components following semantic version conventions. + +``--trace-source=<file>`` + Put cmake in trace mode, but output only lines of a specified file. + + 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. + + Print a warning when an uninitialized variable is used. + +``--warn-unused-vars`` + Does nothing. In CMake versions 3.2 and below this enabled warnings about + unused variables. In CMake versions 3.3 through 3.18 the option was broken. + In CMake 3.19 and above the option has been removed. + +``--no-warn-unused-cli`` + Don't warn about command line options. + + Don't find variables that are declared on the command line, but not + used. + +``--check-system-vars`` + Find problems with variable usage in system files. + + Normally, unused and uninitialized variables are searched for only + in :variable:`CMAKE_SOURCE_DIR` and :variable:`CMAKE_BINARY_DIR`. + This flag tells CMake to warn about other files as well. + +``--profiling-output=<path>`` + Used in conjunction with ``--profiling-format`` to output to a given path. + +``--profiling-format=<file>`` + Enable the output of profiling data of CMake script in the given format. + + This can aid performance analysis of CMake scripts executed. Third party + applications should be used to process the output into human readable format. + + Currently supported values are: + ``google-trace`` Outputs in Google Trace Format, which can be parsed by the + about:tracing tab of Google Chrome or using a plugin for a tool like Trace + Compass. + +``--preset <preset>``, ``--preset=<preset>`` + Reads a :manual:`preset <cmake-presets(7)>` from + ``<path-to-source>/CMakePresets.json`` and + ``<path-to-source>/CMakeUserPresets.json``. The preset may specify the + generator and the build directory, and a list of variables and other + arguments to pass to CMake. The current working directory must contain + CMake preset files. The :manual:`CMake GUI <cmake-gui(1)>` can + also recognize ``CMakePresets.json`` and ``CMakeUserPresets.json`` files. For + full details on these files, see :manual:`cmake-presets(7)`. + + The presets are read before all other command line options. The options + specified by the preset (variables, generator, etc.) can all be overridden by + manually specifying them on the command line. For example, if the preset sets + a variable called ``MYVAR`` to ``1``, but the user sets it to ``2`` with a + ``-D`` argument, the value ``2`` is preferred. + +``--list-presets, --list-presets=<[configure | build | test | all]>`` + Lists the available presets. If no option is specified only configure presets + will be listed. The current working directory must contain CMake preset files. + +.. _`Build Tool Mode`: + +Build a Project +=============== + +CMake provides a command-line signature to build an already-generated +project binary tree: + +.. code-block:: shell + + cmake --build [<dir> | --preset <preset>] [<options>] [-- <build-tool-options>] + +This abstracts a native build tool's command-line interface with the +following options: + +``--build <dir>`` + Project binary directory to be built. This is required (unless a preset + is specified) and must be first. + +``--preset <preset>``, ``--preset=<preset>`` + Use a build preset to specify build options. The project binary directory + is inferred from the ``configurePreset`` key. The current working directory + must contain CMake preset files. + See :manual:`preset <cmake-presets(7)>` for more details. + +``--list-presets`` + Lists the available build presets. The current working directory must + contain CMake preset files. + +``--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>``. + +``--clean-first`` + Build target ``clean`` first, then build. + (To clean only, use ``--target clean``.) + +``--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. + +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>``. + +``--default-directory-permissions <permissions>`` + Default directory install permissions. Permissions in format ``<u=rwx,g=rx,o=rx>``. + +``--prefix <prefix>`` + Override the installation prefix, :variable:`CMAKE_INSTALL_PREFIX`. + +``--strip`` + Strip before installing. + +``-v, --verbose`` + Enable verbose output. + + 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> [-- <unparsed-options>...] + +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. + +Any options after ``--`` are not parsed by CMake, but they are still included +in the set of :variable:`CMAKE_ARGV<n> <CMAKE_ARGV0>` variables passed to the +script (including the ``--`` itself). + + +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: + +``capabilities`` + Report cmake capabilities in JSON format. The output is a JSON object + with the following keys: + + ``version`` + A JSON object with version information. Keys are: + + ``string`` + The full version string as displayed by cmake ``--version``. + ``major`` + The major version number in integer form. + ``minor`` + The minor version number in integer form. + ``patch`` + The patch level in integer form. + ``suffix`` + The cmake version suffix string. + ``isDirty`` + A bool that is set if the cmake build is from a dirty tree. + + ``generators`` + A list available generators. Each generator is a JSON object with the + following keys: + + ``name`` + A string containing the name of the generator. + ``toolsetSupport`` + ``true`` if the generator supports toolsets and ``false`` otherwise. + ``platformSupport`` + ``true`` if the generator supports platforms and ``false`` otherwise. + ``extraGenerators`` + 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. + Always false since CMake 3.20. + +``cat <files>...`` + Concatenate files and print on the standard output. + +``chdir <dir> <cmd> [<arg>...]`` + Change the current working directory and run a command. + +``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``. In case of invalid + arguments, it returns 2. 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 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. + +``create_hardlink <old> <new>`` + Create a hard link ``<new>`` naming ``<old>``. + + .. note:: + Path to where ``<new>`` hard link will be created has to exist beforehand. + ``<old>`` has to exist beforehand. + +``echo [<string>...]`` + Displays arguments as text. + +``echo_append [<string>...]`` + Displays arguments as text but no new line. + +``env [--unset=NAME]... [NAME=VALUE]... COMMAND [ARG]...`` + Run command in a modified environment. + +``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 + silently ignored. + +``md5sum <file>...`` + Create MD5 checksum of files in ``md5sum`` compatible format:: + + 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>...`` + .. deprecated:: 3.17 + + Remove the file(s). The planned behaviour was that 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. + + The implementation was buggy and always returned 0. It cannot be fixed without + breaking backwards compatibility. Use ``rm`` instead. + +``remove_directory <dir>...`` + .. deprecated:: 3.17 + + 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. + Use ``rm`` instead. + +``rename <oldname> <newname>`` + Rename a file or directory (on one volume). If file with the ``<newname>`` name + already exists, then it will be silently replaced. + +``rm [-rRf] <file> <dir>...`` + Remove the files ``<file>`` or directories ``dir``. + Use ``-r`` or ``-R`` to remove directories and their contents recursively. + If any of the listed files/directories 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. + +``server`` + Launch :manual:`cmake-server(7)` mode. + +``sleep <number>...`` + Sleep for given number of seconds. + +``tar [cxt][vf][zjJ] file.tar [<options>] [--] [<pathname>...]`` + Create or extract a tar or zip archive. Options are: + + ``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 ``-``. + ``--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 display elapsed time. + +``touch <file>...`` + Creates ``<file>`` if file do not exist. + If ``<file>`` exists, it is changing ``<file>`` access and modification times. + +``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. + +``true`` + Do nothing, with an exit code of 0. + +Windows-specific Command-Line Tools +----------------------------------- + +The following ``cmake -E`` commands are available only on Windows: + +``delete_regv <key>`` + Delete Windows registry value. + +``env_vs8_wince <sdkname>`` + Displays a batch file which sets the environment for the provided + Windows CE SDK installed in VS2005. + +``env_vs9_wince <sdkname>`` + Displays a batch file which sets the environment for the provided + Windows CE SDK installed in VS2008. + +``write_regv <key> <value>`` + Write Windows registry value. + + +Run the Find-Package Tool +========================= + +CMake provides a pkg-config like helper for Makefile-based projects: + +.. code-block:: shell + + cmake --find-package [<options>] + +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 + +To view the presets available for a project, use + +.. code-block:: shell + + cmake <source-dir> --list-presets + +See Also +======== + +.. include:: LINKS.txt diff --git a/Help/manual/cpack-generators.7.rst b/Help/manual/cpack-generators.7.rst new file mode 100644 index 0000000..ade9149 --- /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 new file mode 100644 index 0000000..395cd41 --- /dev/null +++ b/Help/manual/cpack.1.rst @@ -0,0 +1,113 @@ +.. cmake-manual-description: CPack Command-Line Reference + +cpack(1) +******** + +Synopsis +======== + +.. parsed-literal:: + + cpack [<options>] + +Description +=========== + +The **cpack** executable is the CMake packaging program. It generates +installers and source packages in a variety of formats. + +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. + +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``. + +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. + +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. + +Options +======= + +``-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. This will override any value set for ``<var>`` in the + input file read by ``cpack``. + +``--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. + +``--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`` + 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 + +See Also +======== + +.. include:: LINKS.txt diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst new file mode 100644 index 0000000..68409e1 --- /dev/null +++ b/Help/manual/ctest.1.rst @@ -0,0 +1,1668 @@ +.. cmake-manual-description: CTest Command-Line Reference + +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. +CMake-generated build trees created for projects that use the +:command:`enable_testing` and :command:`add_test` commands have testing support. +This program will run the tests and report results. + +.. _`CTest Options`: + +Options +======= + +``--preset <preset>``, ``--preset=<preset>`` + Use a test preset to specify test options. The project binary directory + is inferred from the ``configurePreset`` key. The current working directory + must contain CMake preset files. + See :manual:`preset <cmake-presets(7)>` for more details. + +``--list-presets`` + Lists the available test presets. The current working directory must contain + CMake preset files. + +``-C <cfg>, --build-config <cfg>`` + Choose configuration to test. + + 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``. + +``--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. + + Test output is normally suppressed and only summary information is + displayed. This option will show all test output. + +``-VV,--extra-verbose`` + Enable more verbose output from tests. + + Test output is normally suppressed and only summary information is + displayed. This option will show even more test output. + +``--debug`` + Displaying more verbose internals of CTest. + + This feature will result in a large number of output that is mostly + useful for debugging dashboard problems. + +``--output-on-failure`` + Output anything outputted by the test program if the test should fail. + This option can also be enabled by setting the + :envvar:`CTEST_OUTPUT_ON_FAILURE` environment variable + +``--stop-on-failure`` + Stop running the tests when the first failure happens. + +``-F`` + Enable failover. + + 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 + :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 + tests when they may cause the CPU load to pass above a given threshold. + + When ``ctest`` is run as a `Dashboard Client`_ this sets the + ``TestLoad`` option of the `CTest Test Step`_. + +``-Q,--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 + as ``--verbose``, ``--extra-verbose``, and ``--debug`` are ignored + if ``--quiet`` is specified. + +``-O <file>, --output-log <file>`` + Output to log file. + + This option tells CTest to write all its output to a ``<file>`` log file. + +``-N,--show-only[=<format>]`` + Disable actual execution of tests. + + 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 + given regular expression. When more than one ``-L`` option is given, + a test will only be run if each regular expression matches at least one + of the test's labels (i.e. the multiple ``-L`` labels form an ``AND`` + relationship). See `Label Matching`_. + +``-R <regex>, --tests-regex <regex>`` + Run tests matching regular expression. + + 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 + 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 + given regular expression. When more than one ``-LE`` option is given, + a test will only be excluded if each regular expression matches at least one + of the test's labels (i.e. the multiple ``-LE`` labels form an ``AND`` + relationship). See `Label Matching`_. + +``-FA <regex>, --fixture-exclude-any <regex>`` + Exclude fixtures matching ``<regex>`` from automatically adding any tests to + the test set. + + If a test in the set of tests to be executed requires a particular fixture, + that fixture's setup and cleanup tests would normally be added to the test set + automatically. This option prevents adding setup or cleanup tests for fixtures + matching the ``<regex>``. Note that all other fixture behavior is retained, + including test dependencies and skipping tests that have fixture setup tests + that fail. + +``-FS <regex>, --fixture-exclude-setup <regex>`` + Same as ``-FA`` except only matching setup tests are excluded. + +``-FC <regex>, --fixture-exclude-cleanup <regex>`` + Same as ``-FA`` except only matching cleanup tests are excluded. + +``-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``. + + See `Dashboard Client`_. + +``-D <var>:<type>=<value>`` + Define a variable for script mode. + + Pass in variable values on the command line. Use in conjunction + with ``-S`` to pass variable values to a dashboard script. Parsing ``-D`` + arguments as variable values is only attempted if the value + following ``-D`` does not match any of the known dashboard types. + +``-M <model>, --test-model <model>`` + Sets the model for a dashboard. + + 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 + 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``. + + 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 + a number of parameters such as the binary and source directories. + 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. + + This option does the same operations as ``-S`` but it will do them in a + separate process. This is primarily useful in cases where the + script may modify the environment and you do not want the modified + environment to impact other ``-S`` scripts. + + 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 + contains the same syntax as the command line. + +``-U, --union`` + Take the Union of ``-I`` and ``-R``. + + When both ``-R`` and ``-I`` are specified by default the intersection of + tests are run. By specifying ``-U`` the union of tests is run instead. + +``--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 + 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 + the set of tests that most recently failed (if any). + +``--repeat <mode>:<n>`` + Run tests repeatedly based on the given ``<mode>`` up to ``<n>`` times. + The modes are: + + ``until-fail`` + Require each test to run ``<n>`` times without failing in order to pass. + This is useful in finding sporadic failures in test cases. + + ``until-pass`` + Allow each test to run up to ``<n>`` times in order to pass. + Repeats tests if they fail for any reason. + This is useful in tolerating sporadic failures in test cases. + + ``after-timeout`` + Allow each test to run up to ``<n>`` times in order to pass. + Repeats tests only if they timeout. + This is useful in tolerating sporadic timeouts in test cases + on busy machines. + +``--repeat-until-fail <n>`` + Equivalent to ``--repeat until-fail:<n>``. + +``--max-width <width>`` + Set the max width for a test name to output. + + Set the maximum width for each test name to show in the output. + This allows the user to widen the output to avoid clipping the test + name which can be very annoying. + +``--interactive-debug-mode [0|1]`` + Set the interactive mode to ``0`` or ``1``. + + 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 + 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 + label associated with the tests run. If there are no labels on the + tests, nothing extra is printed. + + 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-dir <dir>`` +Specify the directory in which to look for tests. + +``--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. + +``--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. + +``--no-tests=<[error|ignore]>`` + Regard no tests found either as error or ignore it. + + If no tests were found, the default behavior of CTest is to always log an + error message but to return an error code in script mode only. This option + unifies the behavior of CTest by either returning an error code if no tests + were found or by ignoring it. + +.. include:: OPTIONS_HELP.txt + +.. _`Label Matching`: + +Label Matching +============== + +Tests may have labels attached to them. Tests may be included +or excluded from a test run by filtering on the labels. +Each individual filter is a regular expression applied to +the labels attached to a test. + +When ``-L`` is used, in order for a test to be included in a +test run, each regular expression must match at least one +label. Using more than one ``-L`` option means "match **all** +of these". + +The ``-LE`` option works just like ``-L``, but excludes tests +rather than including them. A test is excluded if each regular +expression matches at least one label. + +If a test has no labels attached to it, then ``-L`` will never +include that test, and ``-LE`` will never exclude that test. +As an example of tests with labels, consider five tests, +with the following labels: + +* *test1* has labels *tuesday* and *production* +* *test2* has labels *tuesday* and *test* +* *test3* has labels *wednesday* and *production* +* *test4* has label *wednesday* +* *test5* has labels *friday* and *test* + +Running ``ctest`` with ``-L tuesday -L test`` will select *test2*, which has +both labels. Running CTest with ``-L test`` will select *test2* and +*test5*, because both of them have a label that matches that regular +expression. + +Because the matching works with regular expressions, take note that +running CTest with ``-L es`` will match all five tests. +To select the *tuesday* and *wednesday* tests together, use a single +regular expression that matches either of them, like ``-L "tue|wed"``. + +.. _`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. + + If left out the ``all`` target is built. + +``--build-nocmake`` + Run the build without running cmake first. + + Skip the cmake step. + +``--build-run-dir`` + Specify directory to run programs from. + + Directory where programs will be after it has been compiled. + +``--build-two-config`` + Run CMake twice. + +``--build-exe-dir`` + Specify the directory for the executable. + +``--build-generator`` + Specify the generator to use. See the :manual:`cmake-generators(7)` manual. + +``--build-generator-platform`` + Specify the generator-specific platform. + +``--build-generator-toolset`` + Specify the generator-specific toolset. + +``--build-project`` + Specify the name of the project to build. + +``--build-makeprogram`` + 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. + +``--build-options`` + 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 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 + +.. _`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. The command-line signature used to submit to `CDash`_ is:: + + ctest (-D <dashboard> | -M <model> -T <action> | -S <script> | -SP <script>) + [-- <dashboard-options>...] + +Options for Dashboard Client include: + +``--group <group>`` + Specify what group you'd like to submit results to + + 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. + + This replaces the deprecated option ``--track``. + Despite the name change its behavior is unchanged. + +``-A <file>, --add-notes <file>`` + Add a notes file with submission. + + This option tells CTest to include a notes file when submitting + dashboard. + +``--tomorrow-tag`` + ``Nightly`` or ``Experimental`` starts with next day tag. + + This is useful if the build will not finish in one day. + +``--extra-submit <file>[;<file>]`` + Submit extra files to the dashboard. + + This option will submit extra files to the dashboard. + +``--http1.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`. + +``--no-compress-output`` + Do not compress test output when submitting. + + This flag will turn off automatic compression of test output. Use + this to maintain compatibility with an older version of CDash which + doesn't support compressed test output. + +Dashboard Client Steps +---------------------- + +CTest defines an ordered list of testing steps of which some or all may +be run as a dashboard client: + +``Start`` + Start a new dashboard submission to be composed of results recorded + by the following steps. + See the `CTest Start Step`_ section below. + +``Update`` + Update the source tree from its version control repository. + Record the old and new versions and the list of updated source files. + See the `CTest Update Step`_ section below. + +``Configure`` + Configure the software by running a command in the build tree. + Record the configuration output log. + See the `CTest Configure Step`_ section below. + +``Build`` + Build the software by running a command in the build tree. + Record the build output log and detect warnings and errors. + See the `CTest Build Step`_ section below. + +``Test`` + Test the software by loading a ``CTestTestfile.cmake`` + from the build tree and executing the defined tests. + Record the output and result of each test. + See the `CTest Test Step`_ section below. + +``Coverage`` + Compute coverage of the source code by running a coverage + analysis tool and recording its output. + See the `CTest Coverage Step`_ section below. + +``MemCheck`` + Run the software test suite through a memory check tool. + Record the test output, results, and issues reported by the tool. + See the `CTest MemCheck Step`_ section below. + +``Submit`` + Submit results recorded from other testing steps to the + software quality dashboard server. + See the `CTest Submit Step`_ section below. + +Dashboard Client Modes +---------------------- + +CTest defines three modes of operation as a dashboard client: + +``Nightly`` + This mode is intended to be invoked once per day, typically at night. + It enables the ``Start``, ``Update``, ``Configure``, ``Build``, ``Test``, + ``Coverage``, and ``Submit`` steps by default. Selected steps run even + if the ``Update`` step reports no changes to the source tree. + +``Continuous`` + This mode is intended to be invoked repeatedly throughout the day. + It enables the ``Start``, ``Update``, ``Configure``, ``Build``, ``Test``, + ``Coverage``, and ``Submit`` steps by default, but exits after the + ``Update`` step if it reports no changes to the source tree. + +``Experimental`` + This mode is intended to be invoked by a developer to test local changes. + It enables the ``Start``, ``Configure``, ``Build``, ``Test``, ``Coverage``, + and ``Submit`` steps by default. + +Dashboard Client via CTest Command-Line +--------------------------------------- + +CTest can perform testing on an already-generated build tree. +Run the ``ctest`` command with the current working directory set +to the build tree and use one of these signatures:: + + ctest -D <mode>[<step>] + ctest -M <mode> [ -T <step> ]... + +The ``<mode>`` must be one of the above `Dashboard Client Modes`_, +and each ``<step>`` must be one of the above `Dashboard Client Steps`_. + +CTest reads the `Dashboard Client Configuration`_ settings from +a file in the build tree called either ``CTestConfiguration.ini`` +or ``DartConfiguration.tcl`` (the names are historical). The format +of the file is:: + + # Lines starting in '#' are comments. + # Other non-blank lines are key-value pairs. + <setting>: <value> + +where ``<setting>`` is the setting name and ``<value>`` is the +setting value. + +In build trees generated by CMake, this configuration file is +generated by the :module:`CTest` module if included by the project. +The module uses variables to obtain a value for each setting +as documented with the settings below. + +.. _`CTest Script`: + +Dashboard Client via CTest Script +--------------------------------- + +CTest can perform testing driven by a :manual:`cmake-language(7)` +script that creates and maintains the source and build tree as +well as performing the testing steps. Run the ``ctest`` command +with the current working directory set outside of any build tree +and use one of these signatures:: + + ctest -S <script> + ctest -SP <script> + +The ``<script>`` file must call :ref:`CTest Commands` commands +to run testing steps explicitly as documented below. The commands +obtain `Dashboard Client Configuration`_ settings from their +arguments or from variables set in the script. + +Dashboard Client Configuration +============================== + +The `Dashboard Client Steps`_ may be configured by named +settings as documented in the following sections. + +.. _`CTest Start Step`: + +CTest Start Step +---------------- + +Start a new dashboard submission to be composed of results recorded +by the following steps. + +In a `CTest Script`_, the :command:`ctest_start` command runs this step. +Arguments to the command may specify some of the step settings. +The command first runs the command-line specified by the +``CTEST_CHECKOUT_COMMAND`` variable, if set, to initialize the source +directory. + +Configuration settings include: + +``BuildDirectory`` + The full path to the project build tree. + + * `CTest Script`_ variable: :variable:`CTEST_BINARY_DIRECTORY` + * :module:`CTest` module variable: :variable:`PROJECT_BINARY_DIR` + +``SourceDirectory`` + The full path to the project source tree. + + * `CTest Script`_ variable: :variable:`CTEST_SOURCE_DIRECTORY` + * :module:`CTest` module variable: :variable:`PROJECT_SOURCE_DIR` + +.. _`CTest Update Step`: + +CTest Update Step +----------------- + +In a `CTest Script`_, the :command:`ctest_update` command runs this step. +Arguments to the command may specify some of the step settings. + +Configuration settings to specify the version control tool include: + +``BZRCommand`` + ``bzr`` command-line tool to use if source tree is managed by Bazaar. + + * `CTest Script`_ variable: :variable:`CTEST_BZR_COMMAND` + * :module:`CTest` module variable: none + +``BZRUpdateOptions`` + Command-line options to the ``BZRCommand`` when updating the source. + + * `CTest Script`_ variable: :variable:`CTEST_BZR_UPDATE_OPTIONS` + * :module:`CTest` module variable: none + +``CVSCommand`` + ``cvs`` command-line tool to use if source tree is managed by CVS. + + * `CTest Script`_ variable: :variable:`CTEST_CVS_COMMAND` + * :module:`CTest` module variable: ``CVSCOMMAND`` + +``CVSUpdateOptions`` + Command-line options to the ``CVSCommand`` when updating the source. + + * `CTest Script`_ variable: :variable:`CTEST_CVS_UPDATE_OPTIONS` + * :module:`CTest` module variable: ``CVS_UPDATE_OPTIONS`` + +``GITCommand`` + ``git`` command-line tool to use if source tree is managed by Git. + + * `CTest Script`_ variable: :variable:`CTEST_GIT_COMMAND` + * :module:`CTest` module variable: ``GITCOMMAND`` + + 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 modifications are overwritten. + Use ``GITUpdateCustom`` to specify a different approach. + +``GITInitSubmodules`` + If set, CTest will update the repository's submodules before updating. + + * `CTest Script`_ variable: :variable:`CTEST_GIT_INIT_SUBMODULES` + * :module:`CTest` module variable: ``CTEST_GIT_INIT_SUBMODULES`` + +``GITUpdateCustom`` + Specify a custom command line (as a semicolon-separated list) to run + in the source tree (Git work tree) to update it instead of running + the ``GITCommand``. + + * `CTest Script`_ variable: :variable:`CTEST_GIT_UPDATE_CUSTOM` + * :module:`CTest` module variable: ``CTEST_GIT_UPDATE_CUSTOM`` + +``GITUpdateOptions`` + Command-line options to the ``GITCommand`` when updating the source. + + * `CTest Script`_ variable: :variable:`CTEST_GIT_UPDATE_OPTIONS` + * :module:`CTest` module variable: ``GIT_UPDATE_OPTIONS`` + +``HGCommand`` + ``hg`` command-line tool to use if source tree is managed by Mercurial. + + * `CTest Script`_ variable: :variable:`CTEST_HG_COMMAND` + * :module:`CTest` module variable: none + +``HGUpdateOptions`` + Command-line options to the ``HGCommand`` when updating the source. + + * `CTest Script`_ variable: :variable:`CTEST_HG_UPDATE_OPTIONS` + * :module:`CTest` module variable: none + +``P4Client`` + Value of the ``-c`` option to the ``P4Command``. + + * `CTest Script`_ variable: :variable:`CTEST_P4_CLIENT` + * :module:`CTest` module variable: ``CTEST_P4_CLIENT`` + +``P4Command`` + ``p4`` command-line tool to use if source tree is managed by Perforce. + + * `CTest Script`_ variable: :variable:`CTEST_P4_COMMAND` + * :module:`CTest` module variable: ``P4COMMAND`` + +``P4Options`` + Command-line options to the ``P4Command`` for all invocations. + + * `CTest Script`_ variable: :variable:`CTEST_P4_OPTIONS` + * :module:`CTest` module variable: ``CTEST_P4_OPTIONS`` + +``P4UpdateCustom`` + Specify a custom command line (as a semicolon-separated list) to run + in the source tree (Perforce tree) to update it instead of running + the ``P4Command``. + + * `CTest Script`_ variable: none + * :module:`CTest` module variable: ``CTEST_P4_UPDATE_CUSTOM`` + +``P4UpdateOptions`` + Command-line options to the ``P4Command`` when updating the source. + + * `CTest Script`_ variable: :variable:`CTEST_P4_UPDATE_OPTIONS` + * :module:`CTest` module variable: ``CTEST_P4_UPDATE_OPTIONS`` + +``SVNCommand`` + ``svn`` command-line tool to use if source tree is managed by Subversion. + + * `CTest Script`_ variable: :variable:`CTEST_SVN_COMMAND` + * :module:`CTest` module variable: ``SVNCOMMAND`` + +``SVNOptions`` + Command-line options to the ``SVNCommand`` for all invocations. + + * `CTest Script`_ variable: :variable:`CTEST_SVN_OPTIONS` + * :module:`CTest` module variable: ``CTEST_SVN_OPTIONS`` + +``SVNUpdateOptions`` + Command-line options to the ``SVNCommand`` when updating the source. + + * `CTest Script`_ variable: :variable:`CTEST_SVN_UPDATE_OPTIONS` + * :module:`CTest` module variable: ``SVN_UPDATE_OPTIONS`` + +``UpdateCommand`` + Specify the version-control command-line tool to use without + detecting the VCS that manages the source tree. + + * `CTest Script`_ variable: :variable:`CTEST_UPDATE_COMMAND` + * :module:`CTest` module variable: ``<VCS>COMMAND`` + when ``UPDATE_TYPE`` is ``<vcs>``, else ``UPDATE_COMMAND`` + +``UpdateOptions`` + Command-line options to the ``UpdateCommand``. + + * `CTest Script`_ variable: :variable:`CTEST_UPDATE_OPTIONS` + * :module:`CTest` module variable: ``<VCS>_UPDATE_OPTIONS`` + when ``UPDATE_TYPE`` is ``<vcs>``, else ``UPDATE_OPTIONS`` + +``UpdateType`` + Specify the version-control system that manages the source + tree if it cannot be detected automatically. + The value may be ``bzr``, ``cvs``, ``git``, ``hg``, + ``p4``, or ``svn``. + + * `CTest Script`_ variable: none, detected from source tree + * :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 + to a different version. + + * `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: + +``NightlyStartTime`` + In the ``Nightly`` dashboard mode, specify the "nightly start time". + With centralized version control systems (``cvs`` and ``svn``), + the ``Update`` step checks out the version of the software as of + this time so that multiple clients choose a common version to test. + This is not well-defined in distributed version-control systems so + the setting is ignored. + + * `CTest Script`_ variable: :variable:`CTEST_NIGHTLY_START_TIME` + * :module:`CTest` module variable: ``NIGHTLY_START_TIME`` if set, + else ``CTEST_NIGHTLY_START_TIME`` + +.. _`CTest Configure Step`: + +CTest Configure Step +-------------------- + +In a `CTest Script`_, the :command:`ctest_configure` command runs this step. +Arguments to the command may specify some of the step settings. + +Configuration settings include: + +``ConfigureCommand`` + Command-line to launch the software configuration process. + It will be executed in the location specified by the + ``BuildDirectory`` setting. + + * `CTest Script`_ variable: :variable:`CTEST_CONFIGURE_COMMAND` + * :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 +---------------- + +In a `CTest Script`_, the :command:`ctest_build` command runs this step. +Arguments to the command may specify some of the step settings. + +Configuration settings include: + +``DefaultCTestConfigurationType`` + When the build system to be launched allows build-time selection + of the configuration (e.g. ``Debug``, ``Release``), this specifies + the default configuration to be built when no ``-C`` option is + given to the ``ctest`` command. The value will be substituted into + the value of ``MakeCommand`` to replace the literal string + ``${CTEST_CONFIGURATION_TYPE}`` if it appears. + + * `CTest Script`_ variable: :variable:`CTEST_CONFIGURATION_TYPE` + * :module:`CTest` module variable: ``DEFAULT_CTEST_CONFIGURATION_TYPE``, + 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. + It will be executed in the location specified by the + ``BuildDirectory`` setting. + + * `CTest Script`_ variable: :variable:`CTEST_BUILD_COMMAND` + * :module:`CTest` module variable: ``MAKECOMMAND``, + initialized by the :command:`build_command` command + +``UseLaunchers`` + For build trees generated by CMake using one of the + :ref:`Makefile Generators` or the :generator:`Ninja` + generator, specify whether the + ``CTEST_USE_LAUNCHERS`` feature is enabled by the + :module:`CTestUseLaunchers` module (also included by the + :module:`CTest` module). When enabled, the generated build + system wraps each invocation of the compiler, linker, or + custom command line with a "launcher" that communicates + with CTest via environment variables and files to report + granular build warning and error information. Otherwise, + CTest must "scrape" the build output log for diagnostics. + + * `CTest Script`_ variable: :variable:`CTEST_USE_LAUNCHERS` + * :module:`CTest` module variable: ``CTEST_USE_LAUNCHERS`` + +.. _`CTest Test Step`: + +CTest Test Step +--------------- + +In a `CTest Script`_, the :command:`ctest_test` command runs this step. +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>`. + + * `CTest Script`_ variable: :variable:`CTEST_RESOURCE_SPEC_FILE` + * :module:`CTest` module variable: ``CTEST_RESOURCE_SPEC_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. + + * `CTest Script`_ variable: :variable:`CTEST_TEST_LOAD` + * :module:`CTest` module variable: ``CTEST_TEST_LOAD`` + +``TimeOut`` + The default timeout for each test if not specified by the + :prop_test:`TIMEOUT` test property. + + * `CTest Script`_ variable: :variable:`CTEST_TEST_TIMEOUT` + * :module:`CTest` module variable: ``DART_TESTING_TIMEOUT`` + +.. _`CTest Coverage Step`: + +CTest Coverage Step +------------------- + +In a `CTest Script`_, the :command:`ctest_coverage` command runs this step. +Arguments to the command may specify some of the step settings. + +Configuration settings include: + +``CoverageCommand`` + Command-line tool to perform software coverage analysis. + It will be executed in the location specified by the + ``BuildDirectory`` setting. + + * `CTest Script`_ variable: :variable:`CTEST_COVERAGE_COMMAND` + * :module:`CTest` module variable: ``COVERAGE_COMMAND`` + +``CoverageExtraFlags`` + Specify command-line options to the ``CoverageCommand`` tool. + + * `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 +------------------- + +In a `CTest Script`_, the :command:`ctest_memcheck` command runs this step. +Arguments to the command may specify some of the step settings. + +Configuration settings include: + +``MemoryCheckCommand`` + Command-line tool to perform dynamic analysis. Test command lines + will be launched through this tool. + + * `CTest Script`_ variable: :variable:`CTEST_MEMORYCHECK_COMMAND` + * :module:`CTest` module variable: ``MEMORYCHECK_COMMAND`` + +``MemoryCheckCommandOptions`` + Specify command-line options to the ``MemoryCheckCommand`` tool. + They will be placed prior to the test command line. + + * `CTest Script`_ variable: :variable:`CTEST_MEMORYCHECK_COMMAND_OPTIONS` + * :module:`CTest` module variable: ``MEMORYCHECK_COMMAND_OPTIONS`` + +``MemoryCheckType`` + Specify the type of memory checking to perform. + + * `CTest Script`_ variable: :variable:`CTEST_MEMORYCHECK_TYPE` + * :module:`CTest` module variable: ``MEMORYCHECK_TYPE`` + +``MemoryCheckSanitizerOptions`` + Specify options to sanitizers when running with a sanitize-enabled build. + + * `CTest Script`_ variable: :variable:`CTEST_MEMORYCHECK_SANITIZER_OPTIONS` + * :module:`CTest` module variable: ``MEMORYCHECK_SANITIZER_OPTIONS`` + +``MemoryCheckSuppressionFile`` + Specify a file containing suppression rules for the + ``MemoryCheckCommand`` tool. It will be passed with options + appropriate to the tool. + + * `CTest Script`_ variable: :variable:`CTEST_MEMORYCHECK_SUPPRESSIONS_FILE` + * :module:`CTest` module variable: ``MEMORYCHECK_SUPPRESSIONS_FILE`` + +Additional configuration settings include: + +``BoundsCheckerCommand`` + Specify a ``MemoryCheckCommand`` that is known to be command-line + compatible with Bounds Checker. + + * `CTest Script`_ variable: none + * :module:`CTest` module variable: none + +``PurifyCommand`` + Specify a ``MemoryCheckCommand`` that is known to be command-line + compatible with Purify. + + * `CTest Script`_ variable: none + * :module:`CTest` module variable: ``PURIFYCOMMAND`` + +``ValgrindCommand`` + Specify a ``MemoryCheckCommand`` that is known to be command-line + compatible with Valgrind. + + * `CTest Script`_ variable: none + * :module:`CTest` module variable: ``VALGRIND_COMMAND`` + +``ValgrindCommandOptions`` + Specify command-line options to the ``ValgrindCommand`` tool. + They will be placed prior to the test command line. + + * `CTest Script`_ variable: none + * :module:`CTest` module variable: ``VALGRIND_COMMAND_OPTIONS`` + +``DrMemoryCommand`` + Specify a ``MemoryCheckCommand`` that is known to be a command-line + compatible with DrMemory. + + * `CTest Script`_ variable: none + * :module:`CTest` module variable: ``DRMEMORY_COMMAND`` + +``DrMemoryCommandOptions`` + Specify command-line options to the ``DrMemoryCommand`` tool. + They will be placed prior to the test command line. + + * `CTest Script`_ variable: none + * :module:`CTest` module variable: ``DRMEMORY_COMMAND_OPTIONS`` + +``CudaSanitizerCommand`` + Specify a ``MemoryCheckCommand`` that is known to be a command-line + compatible with cuda-memcheck or compute-sanitizer. + + * `CTest Script`_ variable: none + * :module:`CTest` module variable: ``CUDA_SANITIZER_COMMAND`` + +``CudaSanitizerCommandOptions`` + Specify command-line options to the ``CudaSanitizerCommand`` tool. + They will be placed prior to the test command line. + + * `CTest Script`_ variable: none + * :module:`CTest` module variable: ``CUDA_SANITIZER_COMMAND_OPTIONS`` + +.. _`CTest Submit Step`: + +CTest Submit Step +----------------- + +In a `CTest Script`_, the :command:`ctest_submit` command runs this step. +Arguments to the command may specify some of the step settings. + +Configuration settings include: + +``BuildName`` + Describe the dashboard client platform with a short string. + (Operating system, compiler, etc.) + + * `CTest Script`_ variable: :variable:`CTEST_BUILD_NAME` + * :module:`CTest` module variable: ``BUILDNAME`` + +``CDashVersion`` + Legacy option. Not used. + + * `CTest Script`_ variable: none, detected from server + * :module:`CTest` module variable: ``CTEST_CDASH_VERSION`` + +``CTestSubmitRetryCount`` + Specify a number of attempts to retry submission on network failure. + + * `CTest Script`_ variable: none, + use the :command:`ctest_submit` ``RETRY_COUNT`` option. + * :module:`CTest` module variable: ``CTEST_SUBMIT_RETRY_COUNT`` + +``CTestSubmitRetryDelay`` + Specify a delay before retrying submission on network failure. + + * `CTest Script`_ variable: none, + use the :command:`ctest_submit` ``RETRY_DELAY`` option. + * :module:`CTest` module variable: ``CTEST_SUBMIT_RETRY_DELAY`` + +``CurlOptions`` + Specify a semicolon-separated list of options to control the + Curl library that CTest uses internally to connect to the + server. Possible options are ``CURLOPT_SSL_VERIFYPEER_OFF`` + and ``CURLOPT_SSL_VERIFYHOST_OFF``. + + * `CTest Script`_ variable: :variable:`CTEST_CURL_OPTIONS` + * :module:`CTest` module variable: ``CTEST_CURL_OPTIONS`` + +``DropLocation`` + 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`` + 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`` + 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`` + 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`` + 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`` + Legacy option. Not used. + + * `CTest Script`_ variable: :variable:`CTEST_DROP_SITE_CDASH` + * :module:`CTest` module variable: ``CTEST_DROP_SITE_CDASH`` + +``ScpCommand`` + Legacy option. Not used. + + * `CTest Script`_ variable: :variable:`CTEST_SCP_COMMAND` + * :module:`CTest` module variable: ``SCPCOMMAND`` + +``Site`` + Describe the dashboard client host site with a short string. + (Hostname, domain, etc.) + + * `CTest Script`_ variable: :variable:`CTEST_SITE` + * :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. 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 available 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. + +When the resource allocation feature is used, CTest will not oversubscribe +resources. For example, if a resource has 8 slots, CTest will not run tests +that collectively use more than 8 slots at a time. This has the effect of +limiting how many tests can run at any given time, even if a high ``-j`` +argument is used, if those tests all use some slots from the same resource. +In addition, it means that a single test that uses more of a resource than is +available on a machine will not run at all (and will be reported as +``Not Run``). + +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`. If a dashboard script +is used and ``RESOURCE_SPEC_FILE`` is not specified, the value of +:variable:`CTEST_RESOURCE_SPEC_FILE` in the dashboard script is used instead. +If ``--resource-spec-file``, ``RESOURCE_SPEC_FILE``, and +:variable:`CTEST_RESOURCE_SPEC_FILE` in the dashboard script are not specified, +the value of :variable:`CTEST_RESOURCE_SPEC_FILE` in the CMake build is used +instead. If none of these are specified, no resource spec file is used. + +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/manual/presets/example.json b/Help/manual/presets/example.json new file mode 100644 index 0000000..346f342 --- /dev/null +++ b/Help/manual/presets/example.json @@ -0,0 +1,70 @@ +{ + "version": 3, + "cmakeMinimumRequired": { + "major": 3, + "minor": 20, + "patch": 0 + }, + "configurePresets": [ + { + "name": "default", + "displayName": "Default Config", + "description": "Default build using Ninja generator", + "generator": "Ninja", + "binaryDir": "${sourceDir}/build/default", + "cacheVariables": { + "FIRST_CACHE_VARIABLE": { + "type": "BOOL", + "value": "OFF" + }, + "SECOND_CACHE_VARIABLE": "ON" + }, + "environment": { + "MY_ENVIRONMENT_VARIABLE": "Test", + "PATH": "$env{HOME}/ninja/bin:$penv{PATH}" + }, + "vendor": { + "example.com/ExampleIDE/1.0": { + "autoFormat": true + } + } + }, + { + "name": "ninja-multi", + "inherits": "default", + "displayName": "Ninja Multi-Config", + "description": "Default build using Ninja Multi-Config generator", + "generator": "Ninja Multi-Config" + }, + { + "name": "windows-only", + "inherits": "default", + "displayName": "Windows-only configuration", + "description": "This build is only available on Windows", + "condition": { + "type": "equals", + "lhs": "${hostSystemName}", + "rhs": "Windows" + } + } + ], + "buildPresets": [ + { + "name": "default", + "configurePreset": "default" + } + ], + "testPresets": [ + { + "name": "default", + "configurePreset": "default", + "output": {"outputOnFailure": true}, + "execution": {"noTestsAction": "error", "stopOnFailure": true} + } + ], + "vendor": { + "example.com/ExampleIDE/1.0": { + "autoFormat": false + } + } +} diff --git a/Help/manual/presets/schema.json b/Help/manual/presets/schema.json new file mode 100644 index 0000000..e066362 --- /dev/null +++ b/Help/manual/presets/schema.json @@ -0,0 +1,1235 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "description": "The presets specify the generator and the build directory, and optionally a list of variables and other arguments to pass to CMake.", + "oneOf": [ + { + "properties": { + "version": { + "const": 1, + "description": "A required integer representing the version of the JSON schema." + }, + "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"}, + "vendor": { "$ref": "#/definitions/vendor" }, + "configurePresets": { "$ref": "#/definitions/configurePresetsV1"} + }, + "additionalProperties": false + }, + { + "properties": { + "version": { + "const": 2, + "description": "A required integer representing the version of the JSON schema." + }, + "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"}, + "vendor": { "$ref": "#/definitions/vendor" }, + "configurePresets": { "$ref": "#/definitions/configurePresetsV1"}, + "buildPresets": { "$ref": "#/definitions/buildPresetsV2"}, + "testPresets": { "$ref": "#/definitions/testPresetsV2"} + }, + "additionalProperties": false + }, + { + "properties": { + "version": { + "const": 3, + "description": "A required integer representing the version of the JSON schema." + }, + "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"}, + "vendor": { "$ref": "#/definitions/vendor" }, + "configurePresets": { "$ref": "#/definitions/configurePresetsV3"}, + "buildPresets": { "$ref": "#/definitions/buildPresetsV3"}, + "testPresets": { "$ref": "#/definitions/testPresetsV3"} + }, + "additionalProperties": false + } + ], + "required": [ + "version" + ], + "definitions": { + "cmakeMinimumRequired": { + "type": "object", + "description": "An optional object representing the minimum version of CMake needed to build this project.", + "properties": { + "major": { + "type": "integer", + "description": "An optional integer representing the major version." + }, + "minor": { + "type": "integer", + "description": "An optional integer representing the minor version." + }, + "patch": { + "type": "integer", + "description": "An optional integer representing the patch version." + } + }, + "additionalProperties": false + }, + "vendor": { + "type": "object", + "description": "An optional map containing vendor-specific information. CMake does not interpret the contents of this field except to verify that it is a map if it does exist. However, the keys should be a vendor-specific domain name followed by a /-separated path. For example, the Example IDE 1.0 could use example.com/ExampleIDE/1.0. The value of each field can be anything desired by the vendor, though will typically be a map.", + "properties": {} + }, + "configurePresetsItemsV3": { + "type": "array", + "description": "A configure preset object.", + "items": { + "type": "object", + "description": "A configure preset object.", + "properties": { + "binaryDir": { + "type": "string", + "description": "An optional string representing the path to the output binary directory. This field supports macro expansion. If a relative path is specified, it is calculated relative to the source directory. If binaryDir is not specified, the path is calculated using regular methods." + }, + "generator": { + "type": "string", + "description": "An optional string representing the generator to use for the preset. If generator is not specified, the normal generator discovery procedure is used. Note that for Visual Studio generators, unlike in the command line -G argument, you cannot include the platform name in the generator name. Use the architecture field instead." + }, + "installDir": { + "type": "string", + "description": "An optional string representing the path to the output binary directory. This field supports macro expansion. If a relative path is specified, it is calculated relative to the source directory. If binaryDir is not specified, it must be inherited from the inherits preset (unless this preset is hidden)." + }, + "condition": { "$ref": "#/definitions/topCondition" } + } + } + }, + "configurePresetsItemsV1": { + "type": "array", + "description": "An optional array of configure preset objects.", + "items": { + "type": "object", + "description": "A configure preset object.", + "properties": { + "name": { + "type": "string", + "description": "A required string representing the machine-friendly name of the preset. This identifier is used in the --preset argument. There must not be two presets in the union of CMakePresets.json and CMakeUserPresets.json in the same directory with the same name.", + "minLength": 1 + }, + "hidden": { + "type": "boolean", + "description": "An optional boolean specifying whether or not a preset should be hidden. If a preset is hidden, it cannot be used in the --preset= argument, will not show up in the CMake GUI, and does not have to have a valid generator or binaryDir, even from inheritance. Hidden presets are intended to be used as a base for other presets to inherit via the inherits field." + }, + "inherits": { + "anyOf": [ + { + "type": "string", + "description": "An optional string representing the name of the preset to inherit from.", + "minLength": 1 + }, + { + "type": "array", + "description": "An optional array of strings representing the names of presets to inherit from. The preset will inherit all of the fields from the inherits presets by default (except name, hidden, inherits, description, and displayName), but can override them as desired. If multiple inherits presets provide conflicting values for the same field, the earlier preset in the inherits list will be preferred. Presets in CMakePresets.json may not inherit from presets in CMakeUserPresets.json.", + "items": { + "type": "string", + "description": "An optional string representing the name of the preset to inherit from.", + "minLength": 1 + } + } + ] + }, + "vendor": { + "type": "object", + "description": "An optional map containing vendor-specific information. CMake does not interpret the contents of this field except to verify that it is a map if it does exist. However, it should follow the same conventions as the root-level vendor field. If vendors use their own per-preset vendor field, they should implement inheritance in a sensible manner when appropriate.", + "properties": {} + }, + "displayName": { + "type": "string", + "description": "An optional string with a human-friendly name of the preset." + }, + "description": { + "type": "string", + "description": "An optional string with a human-friendly description of the preset." + }, + "generator": { + "type": "string", + "description": "An optional string representing the generator to use for the preset. If generator is not specified, it must be inherited from the inherits preset (unless this preset is hidden). Note that for Visual Studio generators, unlike in the command line -G argument, you cannot include the platform name in the generator name. Use the architecture field instead." + }, + "architecture": { + "anyOf": [ + { + "type": "string", + "description": "An optional string representing the platform for generators that support it." + }, + { + "type": "object", + "description": "An optional object representing the platform for generators that support it.", + "properties": { + "value": { + "type": "string", + "description": "An optional string representing the value." + }, + "strategy": { + "type": "string", + "description": "An optional string telling CMake how to handle the field. Valid values are: \"set\" Set the respective value. This will result in an error for generators that do not support the respective field. \"external\" Do not set the value, even if the generator supports it. This is useful if, for example, a preset uses the Ninja generator, and an IDE knows how to set up the Visual C++ environment from the architecture and toolset fields. In that case, CMake will ignore the field, but the IDE can use them to set up the environment before invoking CMake.", + "enum": [ + "set", + "external" + ] + } + }, + "additionalProperties": false + } + ] + }, + "toolset": { + "anyOf": [ + { + "type": "string", + "description": "An optional string representing the toolset for generators that support it." + }, + { + "type": "object", + "description": "An optional object representing the toolset for generators that support it.", + "properties": { + "value": { + "type": "string", + "description": "An optional string representing the value." + }, + "strategy": { + "type": "string", + "description": "An optional string telling CMake how to handle the field. Valid values are: \"set\" Set the respective value. This will result in an error for generators that do not support the respective field. \"external\" Do not set the value, even if the generator supports it. This is useful if, for example, a preset uses the Ninja generator, and an IDE knows how to set up the Visual C++ environment from the architecture and toolset fields. In that case, CMake will ignore the field, but the IDE can use them to set up the environment before invoking CMake.", + "enum": [ + "set", + "external" + ] + } + }, + "additionalProperties": false + } + ] + }, + "binaryDir": { + "type": "string", + "description": "An optional string representing the path to the output binary directory. This field supports macro expansion. If a relative path is specified, it is calculated relative to the source directory. If binaryDir is not specified, it must be inherited from the inherits preset (unless this preset is hidden)." + }, + "cmakeExecutable": { + "type": "string", + "description": "An optional string representing the path to the CMake executable to use for this preset. This is reserved for use by IDEs, and is not used by CMake itself. IDEs that use this field should expand any macros in it." + }, + "cacheVariables": { + "type": "object", + "description": "An optional map of cache variables. The key is the variable name (which must not be an empty string). Cache variables are inherited through the inherits field, and the preset's variables will be the union of its own cacheVariables and the cacheVariables from all its parents. If multiple presets in this union define the same variable, the standard rules of inherits are applied.", + "properties": {}, + "additionalProperties": { + "anyOf": [ + { + "type": "null", + "description": "Setting a variable to null causes it to not be set, even if a value was inherited from another preset." + }, + { + "type": "boolean", + "description": "A boolean representing the value of the variable. Equivalent to \"TRUE\" or \"FALSE\"." + }, + { + "type": "string", + "description": "A string representing the value of the variable (which supports macro expansion)." + }, + { + "type": "object", + "description": "An object representing the type and value of the variable.", + "properties": { + "type": { + "type": "string", + "description": "An optional string representing the type of the variable. It should be BOOL, FILEPATH, PATH, STRING, or INTERNAL." + }, + "value": { + "anyOf": [ + { + "type": "boolean", + "description": "A required boolean representing the value of the variable. Equivalent to \"TRUE\" or \"FALSE\"." + }, + { + "type": "string", + "description": "A required string representing the value of the variable. This field supports macro expansion." + } + ] + } + }, + "required": [ + "value" + ], + "additionalProperties": false + } + ] + }, + "propertyNames": { + "pattern": "^.+$" + } + }, + "environment": { + "type": "object", + "description": "An optional map of environment variables. The key is the variable name (which must not be an empty string). Each variable is set regardless of whether or not a value was given to it by the process's environment. This field supports macro expansion, and environment variables in this map may reference each other, and may be listed in any order, as long as such references do not cause a cycle (for example,if ENV_1 is $env{ENV_2}, ENV_2 may not be $env{ENV_1}.) Environment variables are inherited through the inherits field, and the preset's environment will be the union of its own environment and the environment from all its parents. If multiple presets in this union define the same variable, the standard rules of inherits are applied. Setting a variable to null causes it to not be set, even if a value was inherited from another preset.", + "properties": {}, + "additionalProperties": { + "anyOf": [ + { + "type": "null", + "description": "Setting a variable to null causes it to not be set, even if a value was inherited from another preset." + }, + { + "type": "string", + "description": "A string representing the value of the variable." + } + ] + }, + "propertyNames": { + "pattern": "^.+$" + } + }, + "warnings": { + "type": "object", + "description": "An optional object specifying warnings.", + "properties": { + "dev": { + "type": "boolean", + "description": "An optional boolean. Equivalent to passing -Wdev or -Wno-dev on the command line. This may not be set to false if errors.dev is set to true." + }, + "deprecated": { + "type": "boolean", + "description": "An optional boolean. Equivalent to passing -Wdeprecated or -Wno-deprecated on the command line. This may not be set to false if errors.deprecated is set to true." + }, + "uninitialized": { + "type": "boolean", + "description": "An optional boolean. Setting this to true is equivalent to passing --warn-uninitialized on the command line." + }, + "unusedCli": { + "type": "boolean", + "description": "An optional boolean. Setting this to false is equivalent to passing --no-warn-unused-cli on the command line." + }, + "systemVars": { + "type": "boolean", + "description": "An optional boolean. Setting this to true is equivalent to passing --check-system-vars on the command line." + } + }, + "additionalProperties": false + }, + "errors": { + "type": "object", + "description": "An optional object specifying errors.", + "properties": { + "dev": { + "type": "boolean", + "description": "An optional boolean. Equivalent to passing -Werror=dev or -Wno-error=dev on the command line. This may not be set to true if warnings.dev is set to false." + }, + "deprecated": { + "type": "boolean", + "description": "An optional boolean. Equivalent to passing -Werror=deprecated or -Wno-error=deprecated on the command line. This may not be set to true if warnings.deprecated is set to false." + } + }, + "additionalProperties": false + }, + "debug": { + "type": "object", + "description": "An optional object specifying debug options.", + "properties": { + "output": { + "type": "boolean", + "description": "An optional boolean. Setting this to true is equivalent to passing --debug-output on the command line." + }, + "tryCompile": { + "type": "boolean", + "description": "An optional boolean. Setting this to true is equivalent to passing --debug-trycompile on the command line." + }, + "find": { + "type": "boolean", + "description": "An optional boolean. Setting this to true is equivalent to passing --debug-find on the command line." + } + }, + "additionalProperties": false + } + } + } + }, + "configurePresetsV3": { + "type": "array", + "description": "An optional array of configure preset objects.", + "allOf": [ + { "$ref": "#/definitions/configurePresetsItemsV1" }, + { "$ref": "#/definitions/configurePresetsItemsV3" } + ], + "items": { + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "generator": {}, + "architecture": {}, + "toolset": {}, + "binaryDir": {}, + "installDir": {}, + "cmakeExecutable": {}, + "cacheVariables": {}, + "environment": {}, + "warnings": {}, + "errors": {}, + "debug": {}, + "condition": {} + }, + "required": [ + "name" + ], + "additionalProperties": false + } + }, + "configurePresetsV1": { + "type": "array", + "description": "An optional array of configure preset objects.", + "allOf": [ + { "$ref": "#/definitions/configurePresetsItemsV1" } + ], + "items": { + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "generator": {}, + "architecture": {}, + "toolset": {}, + "binaryDir": {}, + "cmakeExecutable": {}, + "cacheVariables": {}, + "environment": {}, + "warnings": {}, + "errors": {}, + "debug": {} + }, + "required": [ + "name" + ], + "additionalProperties": false + } + }, + "buildPresetsItemsV3": { + "type": "array", + "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 2 and higher.", + "items": { + "type": "object", + "properties": { + "condition": { "$ref": "#/definitions/topCondition" } + } + } + }, + "buildPresetsItemsV2": { + "type": "array", + "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 2 and higher.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "A required string representing the machine-friendly name of the preset. This identifier is used in the --preset argument. There must not be two presets (configure, build, or test) in the union of CMakePresets.json and CMakeUserPresets.json in the same directory with the same name.", + "minLength": 1 + }, + "hidden": { + "type": "boolean", + "description": "An optional boolean specifying whether or not a preset should be hidden. If a preset is hidden, it cannot be used in the --preset argument, will not show up in the CMake GUI, and does not have to have a valid configurePreset, even from inheritance. Hidden presets are intended to be used as a base for other presets to inherit via the inherits field." + }, + "inherits": { + "anyOf": [ + { + "type": "string", + "description": "An optional string representing the name of the build preset to inherit from.", + "minLength": 1 + }, + { + "type": "array", + "description": "An optional array of strings representing the names of build presets to inherit from. The preset will inherit all of the fields from the inherits presets by default (except name, hidden, inherits, description, and displayName), but can override them as desired. If multiple inherits presets provide conflicting values for the same field, the earlier preset in the inherits list will be preferred. Presets in CMakePresets.json may not inherit from presets in CMakeUserPresets.json.", + "items": { + "type": "string", + "description": "An optional string representing the name of the preset to inherit from.", + "minLength": 1 + } + } + ] + }, + "configurePreset": { + "type": "string", + "description": "An optional string specifying the name of a configure preset to associate with this build preset. If configurePreset is not specified, it must be inherited from the inherits preset (unless this preset is hidden). The build tree directory is inferred from the configure preset.", + "minLength": 1 + }, + "vendor": { + "type": "object", + "description": "An optional map containing vendor-specific information. CMake does not interpret the contents of this field except to verify that it is a map if it does exist. However, it should follow the same conventions as the root-level vendor field. If vendors use their own per-preset vendor field, they should implement inheritance in a sensible manner when appropriate.", + "properties": {} + }, + "displayName": { + "type": "string", + "description": "An optional string with a human-friendly name of the preset." + }, + "description": { + "type": "string", + "description": "An optional string with a human-friendly description of the preset." + }, + "inheritConfigureEnvironment": { + "type": "boolean", + "description": "An optional boolean that defaults to true. If true, the environment variables from the associated configure preset are inherited after all inherited build preset environments, but before environment variables explicitly specified in this build preset." + }, + "environment": { + "type": "object", + "description": "An optional map of environment variables. The key is the variable name (which must not be an empty string). Each variable is set regardless of whether or not a value was given to it by the process's environment. This field supports macro expansion, and environment variables in this map may reference each other, and may be listed in any order, as long as such references do not cause a cycle (for example,if ENV_1 is $env{ENV_2}, ENV_2 may not be $env{ENV_1}.) Environment variables are inherited through the inherits field, and the preset's environment will be the union of its own environment and the environment from all its parents. If multiple presets in this union define the same variable, the standard rules of inherits are applied. Setting a variable to null causes it to not be set, even if a value was inherited from another preset.", + "properties": {}, + "additionalProperties": { + "anyOf": [ + { + "type": "null", + "description": "Setting a variable to null causes it to not be set, even if a value was inherited from another preset." + }, + { + "type": "string", + "description": "A string representing the value of the variable." + } + ] + }, + "propertyNames": { + "pattern": "^.+$" + } + }, + "jobs": { + "type": "integer", + "description": "An optional integer. Equivalent to passing --parallel or -j on the command line." + }, + "targets": { + "anyOf": [ + { + "type": "string", + "description": "An optional string. Equivalent to passing --target or -t on the command line. Vendors may ignore the targets property or hide build presets that explicitly specify targets." + }, + { + "type": "array", + "description": "An optional array of strings. Equivalent to passing --target or -t on the command line. Vendors may ignore the targets property or hide build presets that explicitly specify targets.", + "items": { + "type": "string", + "description": "An optional string. Equivalent to passing --target or -t on the command line. Vendors may ignore the targets property or hide build presets that explicitly specify targets." + } + } + ] + }, + "configuration": { + "type": "string", + "description": "An optional string. Equivalent to passing --config on the command line." + }, + "cleanFirst": { + "type": "boolean", + "description": "An optional boolean. If true, equivalent to passing --clean-first on the command line." + }, + "verbose": { + "type": "boolean", + "description": "An optional boolean. If true, equivalent to passing --verbose on the command line." + }, + "nativeToolOptions": { + "type": "array", + "description": "An optional array of strings. Equivalent to passing options after -- on the command line.", + "items": { + "type": "string", + "description": "An optional string representing an option to pass after -- on the command line." + } + } + }, + "required": [ + "name" + ] + } + }, + "buildPresetsV3": { + "type": "array", + "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 2 and higher.", + "allOf": [ + { "$ref": "#/definitions/buildPresetsItemsV3" }, + { "$ref": "#/definitions/buildPresetsItemsV2" } + ], + "items": { + "type": "object", + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "configurePreset": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "inheritConfigureEnvironment": {}, + "environment": {}, + "jobs": {}, + "targets": {}, + "configuration": {}, + "cleanFirst": {}, + "verbose": {}, + "nativeToolOptions": {}, + "condition": {} + }, + "required": [ + "name" + ], + "additionalProperties": false + } + }, + "buildPresetsV2": { + "type": "array", + "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 2 and higher.", + "allOf": [ + { "$ref": "#/definitions/buildPresetsItemsV2" } + ], + "items": { + "type": "object", + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "configurePreset": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "inheritConfigureEnvironment": {}, + "environment": {}, + "jobs": {}, + "targets": {}, + "configuration": {}, + "cleanFirst": {}, + "verbose": {}, + "nativeToolOptions": {} + }, + "required": [ + "name" + ], + "additionalProperties": false + } + }, + "testPresetsItemsV3": { + "type": "array", + "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 2 and higher.", + "items": { + "type": "object", + "properties": { + "condition": { "$ref": "#/definitions/topCondition" } + } + } + }, + "testPresetsItemsV2": { + "type": "array", + "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 2 and higher.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "A required string representing the machine-friendly name of the preset. This identifier is used in the --preset argument. There must not be two presets (configure, build, or test) in the union of CMakePresets.json and CMakeUserPresets.json in the same directory with the same name.", + "minLength": 1 + }, + "hidden": { + "type": "boolean", + "description": "An optional boolean specifying whether or not a preset should be hidden. If a preset is hidden, it cannot be used in the --preset argument, will not show up in the CMake GUI, and does not have to have a valid configurePreset, even from inheritance. Hidden presets are intended to be used as a base for other presets to inherit via the inherits field." + }, + "inherits": { + "anyOf": [ + { + "type": "string", + "description": "An optional string representing the name of the test preset to inherit from.", + "minLength": 1 + }, + { + "type": "array", + "description": "An optional array of strings representing the names of test presets to inherit from. The preset will inherit all of the fields from the inherits presets by default (except name, hidden, inherits, description, and displayName), but can override them as desired. If multiple inherits presets provide conflicting values for the same field, the earlier preset in the inherits list will be preferred. Presets in CMakePresets.json may not inherit from presets in CMakeUserPresets.json.", + "items": { + "type": "string", + "description": "An optional string representing the name of the preset to inherit from.", + "minLength": 1 + } + } + ] + }, + "configurePreset": { + "type": "string", + "description": "An optional string specifying the name of a configure preset to associate with this test preset. If configurePreset is not specified, it must be inherited from the inherits preset (unless this preset is hidden). The build tree directory is inferred from the configure preset.", + "minLength": 1 + }, + "vendor": { + "type": "object", + "description": "An optional map containing vendor-specific information. CMake does not interpret the contents of this field except to verify that it is a map if it does exist. However, it should follow the same conventions as the root-level vendor field. If vendors use their own per-preset vendor field, they should implement inheritance in a sensible manner when appropriate.", + "properties": {} + }, + "displayName": { + "type": "string", + "description": "An optional string with a human-friendly name of the preset." + }, + "description": { + "type": "string", + "description": "An optional string with a human-friendly description of the preset." + }, + "inheritConfigureEnvironment": { + "type": "boolean", + "description": "An optional boolean that defaults to true. If true, the environment variables from the associated configure preset are inherited after all inherited test preset environments, but before environment variables explicitly specified in this test preset." + }, + "environment": { + "type": "object", + "description": "An optional map of environment variables. The key is the variable name (which must not be an empty string). Each variable is set regardless of whether or not a value was given to it by the process's environment. This field supports macro expansion, and environment variables in this map may reference each other, and may be listed in any order, as long as such references do not cause a cycle (for example,if ENV_1 is $env{ENV_2}, ENV_2 may not be $env{ENV_1}.) Environment variables are inherited through the inherits field, and the preset's environment will be the union of its own environment and the environment from all its parents. If multiple presets in this union define the same variable, the standard rules of inherits are applied. Setting a variable to null causes it to not be set, even if a value was inherited from another preset.", + "properties": {}, + "additionalProperties": { + "anyOf": [ + { + "type": "null", + "description": "Setting a variable to null causes it to not be set, even if a value was inherited from another preset." + }, + { + "type": "string", + "description": "A string representing the value of the variable." + } + ] + }, + "propertyNames": { + "pattern": "^.+$" + } + }, + "configuration": { + "type": "string", + "description": "An optional string. Equivalent to passing --build-config on the command line." + }, + "overwriteConfigurationFile": { + "type": "array", + "description": "An optional array of configuration options to overwrite options specified in the CTest configuration file. Equivalent to passing ``--overwrite`` for each value in the array.", + "items": { + "type": "string", + "description": "An option written as a key-value pair in the form \"key=value\"." + } + }, + "output": { + "type": "object", + "description": "An optional object specifying output options.", + "properties": { + "shortProgress": { + "type": "boolean", + "description": "An optional boolean. If true, equivalent to passing --progress on the command line." + }, + "verbosity": { + "type": "string", + "description": "An optional string specifying verbosity level. Valid values are \"default\" (equivalent to passing no verbosity flags on the command line), \"verbose\" (equivalent to passing --verbose on the command line), and \"extra\" (equivalent to passing --extra-verbose on the command line).", + "enum": [ + "default", "verbose", "extra" + ] + }, + "debug": { + "type": "boolean", + "description": "An optional boolean. If true, equivalent to passing --debug on the command line." + }, + "outputOnFailure": { + "type": "boolean", + "description": "An optional boolean. If true, equivalent to passing --output-on-failure on the command line." + }, + "quiet": { + "type": "boolean", + "description": "An optional boolean. If true, equivalent to passing --quiet on the command line." + }, + "outputLogFile": { + "type": "string", + "description": "An optional string specifying a path to a log file. Equivalent to passing --output-log on the command line." + }, + "labelSummary": { + "type": "boolean", + "description": "An optional boolean. If false, equivalent to passing --no-label-summary on the command line." + }, + "subprojectSummary": { + "type": "boolean", + "description": "An optional boolean. If false, equivalent to passing --no-subproject-summary on the command line." + }, + "maxPassedTestOutputSize": { + "type": "integer", + "description": "An optional integer specifying the maximum output for passed tests in bytes. Equivalent to passing --test-output-size-passed on the command line." + }, + "maxFailedTestOutputSize": { + "type": "integer", + "description": "An optional integer specifying the maximum output for failed tests in bytes. Equivalent to passing --test-output-size-failed on the command line." + }, + "maxTestNameWidth": { + "type": "integer", + "description": "An optional integer specifying the maximum width of a test name to output. Equivalent to passing --max-width on the command line." + } + }, + "additionalProperties": false + }, + "filter": { + "type": "object", + "description": "An optional object specifying how to filter the tests to run.", + "properties": { + "include": { + "type": "object", + "description": "An optional object specifying which tests to include.", + "properties": { + "name": { + "type": "string", + "description": "An optional string specifying a regex for test names. Equivalent to passing --tests-regex on the command line." + }, + "label": { + "type": "string", + "description": "An optional string specifying a regex for test labels. Equivalent to passing --label-regex on the command line." + }, + "index": { + "anyOf": [ + { + "type": "object", + "description": "An optional object specifying tests to include by test index.", + "properties": { + "start": { + "type": "integer", + "description": "An optional integer specifying a test index to start testing at." + }, + "end": { + "type": "integer", + "description": "An optional integer specifying a test index to stop testing at." + }, + "stride": { + "type": "integer", + "description": "An optional integer specifying the increment." + }, + "specificTests": { + "type": "array", + "description": "An optional array of integers specifying specific test indices to run.", + "items": { + "type": "integer", + "description": "An integer specifying the test to run by index." + } + } + }, + "additionalProperties": false + }, + { + "type": "string", + "description": "An optional string specifying a file with the command line syntax for --tests-information." + } + ] + }, + "useUnion": { + "type": "boolean", + "description": "An optional boolean. Equivalent to passing --union on the command line." + } + }, + "additionalProperties": false + }, + "exclude": { + "type": "object", + "description": "An optional object specifying which tests to exclude.", + "properties": { + "name": { + "type": "string", + "description": "An optional string specifying a regex for test names. Equivalent to passing --exclude-regex on the command line." + }, + "label": { + "type": "string", + "description": "An optional string specifying a regex for test labels. Equivalent to passing --label-exclude on the command line." + }, + "fixtures": { + "type": "object", + "description": "An optional object specifying which fixtures to exclude from adding tests.", + "properties": { + "any": { + "type": "string", + "description": "An optional string specifying a regex for text fixtures to exclude from adding any tests. Equivalent to --fixture-exclude-any on the command line." + }, + "setup": { + "type": "string", + "description": "An optional string specifying a regex for text fixtures to exclude from adding setup tests. Equivalent to --fixture-exclude-setup on the command line." + }, + "cleanup": { + "type": "string", + "description": "An optional string specifying a regex for text fixtures to exclude from adding cleanup tests. Equivalent to --fixture-exclude-cleanup on the command line." + } + }, + "additionalProperties": false + } + } + } + }, + "additionalProperties": false + }, + "execution": { + "type": "object", + "description": "An optional object specifying options for test execution.", + "properties": { + "stopOnFailure": { + "type": "boolean", + "description": "An optional boolean. If true, equivalent to passing --stop-on-failure on the command line." + }, + "enableFailover": { + "type": "boolean", + "description": "An optional boolean. If true, equivalent to passing -F on the command line." + }, + "jobs": { + "type": "integer", + "description": "An optional integer. Equivalent to passing --parallel on the command line." + }, + "resourceSpecFile": { + "type": "string", + "description": "An optional string. Equivalent to passing --resource-spec-file on the command line." + }, + "testLoad": { + "type": "integer", + "description": "An optional integer. Equivalent to passing --test-load on the command line." + }, + "showOnly": { + "type": "string", + "description": "An optional string. Equivalent to passing --show-only on the command line. Value must be \"human\" or \"json-v1\".", + "enum": [ + "human", "json-v1" + ] + }, + "repeat": { + "type": "object", + "description": "An optional object specifying how to repeat tests. Equivalent to passing --repeat on the command line.", + "properties": { + "mode": { + "type": "string", + "description": "A required string. Must be one of the following values: \"until-fail\", \"until-pass\", or \"after-timeout\".", + "enum": [ + "until-fail", "until-pass", "after-timeout" + ] + }, + "count": { + "type": "integer", + "description": "A required integer." + } + }, + "required": [ + "mode", "count" + ], + "additionalProperties": false + }, + "interactiveDebugging": { + "type": "boolean", + "description": "An optional boolean. If true, equivalent to passing --interactive-debug-mode 1 on the command line. If false, equivalent to passing --interactive-debug-mode 0 on the command line." + }, + "scheduleRandom": { + "type": "boolean", + "description": "An optional boolean. If true, equivalent to passing --schedule-random on the command line." + }, + "timeout": { + "type": "integer", + "description": "An optional integer. Equivalent to passing --timeout on the command line." + }, + "noTestsAction": { + "type": "string", + "description": "An optional string specifying the behavior if no tests are found. Must be one of the following values: \"default\" (equivalent to not passing any value on the command line), \"error\" (equivalent to passing --no-tests=error on the command line), or \"ignore\" (equivalent to passing --no-tests-ignore on the command line).", + "enum": [ + "default", "error", "ignore" + ] + } + }, + "additionalProperties": false + } + }, + "required": [ + "name" + ] + } + }, + "testPresetsV3": { + "type": "array", + "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 2 and higher.", + "allOf": [ + { "$ref": "#/definitions/testPresetsItemsV2" }, + { "$ref": "#/definitions/testPresetsItemsV3" } + ], + "items": { + "type": "object", + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "configurePreset": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "inheritConfigureEnvironment": {}, + "environment": {}, + "configuration": {}, + "overwriteConfigurationFile": {}, + "output": {}, + "filter": {}, + "execution": {}, + "condition": {} + }, + "required": [ + "name" + ], + "additionalProperties": false + } + }, + "testPresetsV2": { + "type": "array", + "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 2 and higher.", + "allOf": [ + { "$ref": "#/definitions/testPresetsItemsV2" } + ], + "items": { + "type": "object", + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "configurePreset": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "inheritConfigureEnvironment": {}, + "environment": {}, + "configuration": {}, + "overwriteConfigurationFile": {}, + "output": {}, + "filter": {}, + "execution": {} + }, + "required": [ + "name" + ], + "additionalProperties": false + } + }, + "condition": { + "anyOf": [ + { + "type": "boolean", + "description": "A boolean which provides a constant value for the condition's evaluation." + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "const" + }, + "value": { + "type": "boolean", + "description": "A required boolean which provides a constant value for the condition's evaluation." + } + }, + "required": [ + "type", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "equals" + }, + "lhs": { + "type": "string", + "description": "First string to compare. This field supports macro expansion." + }, + "rhs": { + "type": "string", + "description": "Second string to compare. This field supports macro expansion." + } + }, + "required": [ + "type", + "lhs", + "rhs" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "notEquals" + }, + "lhs": { + "type": "string", + "description": "First string to compare. This field supports macro expansion." + }, + "rhs": { + "type": "string", + "description": "Second string to compare. This field supports macro expansion." + } + }, + "required": [ + "type", + "lhs", + "rhs" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "inList" + }, + "string": { + "type": "string", + "description": "A required string to search for. This field supports macro expansion." + }, + "list": { + "type": "array", + "description": "A required list of strings to search. This field supports macro expansion, and uses short-circuit evaluation.", + "items": { + "type": "string" + } + } + }, + "required": [ + "type", + "string", + "list" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "notInList" + }, + "string": { + "type": "string", + "description": "A required string to search for. This field supports macro expansion." + }, + "list": { + "type": "array", + "description": "A required list of strings to search. This field supports macro expansion, and uses short-circuit evaluation.", + "items": { + "type": "string" + } + } + }, + "required": [ + "type", + "string", + "list" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "matches" + }, + "string": { + "type": "string", + "description": "A required string to search. This field supports macro expansion." + }, + "regex": { + "type": "string", + "description": "A required regular expression to search for. This field supports macro expansion." + } + }, + "required": [ + "type", + "string", + "regex" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "notMatches" + }, + "string": { + "type": "string", + "description": "A required string to search. This field supports macro expansion." + }, + "regex": { + "type": "string", + "description": "A required regular expression to search for. This field supports macro expansion." + } + }, + "required": [ + "type", + "string", + "regex" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "anyOf" + }, + "conditions": { + "type": "array", + "description": "A required array of condition objects. These conditions use short-circuit evaluation.", + "items": { "$ref": "#/definitions/condition" } + } + }, + "required": [ + "type", + "conditions" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "allOf" + }, + "conditions": { + "type": "array", + "description": "A required array of condition objects. These conditions use short-circuit evaluation.", + "items": { "$ref": "#/definitions/condition" } + } + }, + "required": [ + "type", + "conditions" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "not" + }, + "condition": { "$ref": "#/definitions/condition" } + }, + "required": [ + "type", + "condition" + ], + "additionalProperties": false + } + ] + }, + "topCondition": { + "anyOf": [ + { "$ref": "#/definitions/condition" }, + { + "type": "null", + "description": "Null indicates that the condition always evaluates to true and is not inherited." + } + ] + } + } +} diff --git a/Help/module/AddFileDependencies.rst b/Help/module/AddFileDependencies.rst new file mode 100644 index 0000000..3cbce33 --- /dev/null +++ b/Help/module/AddFileDependencies.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/AddFileDependencies.cmake diff --git a/Help/module/AndroidTestUtilities.rst b/Help/module/AndroidTestUtilities.rst new file mode 100644 index 0000000..e7ec864 --- /dev/null +++ b/Help/module/AndroidTestUtilities.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/AndroidTestUtilities.cmake diff --git a/Help/module/BundleUtilities.rst b/Help/module/BundleUtilities.rst new file mode 100644 index 0000000..5d9c840 --- /dev/null +++ b/Help/module/BundleUtilities.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/BundleUtilities.cmake diff --git a/Help/module/CMakeAddFortranSubdirectory.rst b/Help/module/CMakeAddFortranSubdirectory.rst new file mode 100644 index 0000000..9abf571 --- /dev/null +++ b/Help/module/CMakeAddFortranSubdirectory.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CMakeAddFortranSubdirectory.cmake diff --git a/Help/module/CMakeBackwardCompatibilityCXX.rst b/Help/module/CMakeBackwardCompatibilityCXX.rst new file mode 100644 index 0000000..05e5f4a --- /dev/null +++ b/Help/module/CMakeBackwardCompatibilityCXX.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CMakeBackwardCompatibilityCXX.cmake diff --git a/Help/module/CMakeDependentOption.rst b/Help/module/CMakeDependentOption.rst new file mode 100644 index 0000000..fd071b5 --- /dev/null +++ b/Help/module/CMakeDependentOption.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CMakeDependentOption.cmake diff --git a/Help/module/CMakeDetermineVSServicePack.rst b/Help/module/CMakeDetermineVSServicePack.rst new file mode 100644 index 0000000..1768533 --- /dev/null +++ b/Help/module/CMakeDetermineVSServicePack.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CMakeDetermineVSServicePack.cmake diff --git a/Help/module/CMakeExpandImportedTargets.rst b/Help/module/CMakeExpandImportedTargets.rst new file mode 100644 index 0000000..1084280 --- /dev/null +++ b/Help/module/CMakeExpandImportedTargets.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CMakeExpandImportedTargets.cmake diff --git a/Help/module/CMakeFindDependencyMacro.rst b/Help/module/CMakeFindDependencyMacro.rst new file mode 100644 index 0000000..5b5b550 --- /dev/null +++ b/Help/module/CMakeFindDependencyMacro.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CMakeFindDependencyMacro.cmake diff --git a/Help/module/CMakeFindFrameworks.rst b/Help/module/CMakeFindFrameworks.rst new file mode 100644 index 0000000..c2c219b --- /dev/null +++ b/Help/module/CMakeFindFrameworks.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CMakeFindFrameworks.cmake diff --git a/Help/module/CMakeFindPackageMode.rst b/Help/module/CMakeFindPackageMode.rst new file mode 100644 index 0000000..d099d19 --- /dev/null +++ b/Help/module/CMakeFindPackageMode.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CMakeFindPackageMode.cmake diff --git a/Help/module/CMakeForceCompiler.rst b/Help/module/CMakeForceCompiler.rst new file mode 100644 index 0000000..3277426 --- /dev/null +++ b/Help/module/CMakeForceCompiler.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CMakeForceCompiler.cmake diff --git a/Help/module/CMakeGraphVizOptions.rst b/Help/module/CMakeGraphVizOptions.rst new file mode 100644 index 0000000..2cd97b3 --- /dev/null +++ b/Help/module/CMakeGraphVizOptions.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CMakeGraphVizOptions.cmake diff --git a/Help/module/CMakePackageConfigHelpers.rst b/Help/module/CMakePackageConfigHelpers.rst new file mode 100644 index 0000000..a291aff --- /dev/null +++ b/Help/module/CMakePackageConfigHelpers.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CMakePackageConfigHelpers.cmake diff --git a/Help/module/CMakeParseArguments.rst b/Help/module/CMakeParseArguments.rst new file mode 100644 index 0000000..810a9dd --- /dev/null +++ b/Help/module/CMakeParseArguments.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CMakeParseArguments.cmake diff --git a/Help/module/CMakePrintHelpers.rst b/Help/module/CMakePrintHelpers.rst new file mode 100644 index 0000000..a75a34f --- /dev/null +++ b/Help/module/CMakePrintHelpers.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CMakePrintHelpers.cmake diff --git a/Help/module/CMakePrintSystemInformation.rst b/Help/module/CMakePrintSystemInformation.rst new file mode 100644 index 0000000..0b5d848 --- /dev/null +++ b/Help/module/CMakePrintSystemInformation.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CMakePrintSystemInformation.cmake diff --git a/Help/module/CMakePushCheckState.rst b/Help/module/CMakePushCheckState.rst new file mode 100644 index 0000000..e897929 --- /dev/null +++ b/Help/module/CMakePushCheckState.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CMakePushCheckState.cmake diff --git a/Help/module/CMakeVerifyManifest.rst b/Help/module/CMakeVerifyManifest.rst new file mode 100644 index 0000000..eeff1bf --- /dev/null +++ b/Help/module/CMakeVerifyManifest.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CMakeVerifyManifest.cmake diff --git a/Help/module/CPack.rst b/Help/module/CPack.rst new file mode 100644 index 0000000..bfbda1f --- /dev/null +++ b/Help/module/CPack.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CPack.cmake diff --git a/Help/module/CPackArchive.rst b/Help/module/CPackArchive.rst new file mode 100644 index 0000000..f5d6da4 --- /dev/null +++ b/Help/module/CPackArchive.rst @@ -0,0 +1,6 @@ +CPackArchive +------------ + +.. versionadded:: 3.9 + +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 new file mode 100644 index 0000000..5134884 --- /dev/null +++ b/Help/module/CPackBundle.rst @@ -0,0 +1,4 @@ +CPackBundle +----------- + +The documentation for the CPack Bundle generator has moved here: :cpack_gen:`CPack Bundle Generator` diff --git a/Help/module/CPackComponent.rst b/Help/module/CPackComponent.rst new file mode 100644 index 0000000..df82836 --- /dev/null +++ b/Help/module/CPackComponent.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CPackComponent.cmake diff --git a/Help/module/CPackCygwin.rst b/Help/module/CPackCygwin.rst new file mode 100644 index 0000000..719dfce --- /dev/null +++ b/Help/module/CPackCygwin.rst @@ -0,0 +1,4 @@ +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 new file mode 100644 index 0000000..e59dcbb --- /dev/null +++ b/Help/module/CPackDMG.rst @@ -0,0 +1,4 @@ +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 new file mode 100644 index 0000000..cd7e5f3 --- /dev/null +++ b/Help/module/CPackDeb.rst @@ -0,0 +1,4 @@ +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 0000000..7ae6164 --- /dev/null +++ b/Help/module/CPackFreeBSD.rst @@ -0,0 +1,6 @@ +CPackFreeBSD +------------ + +.. versionadded:: 3.10 + +The documentation for the CPack FreeBSD generator has moved here: :cpack_gen:`CPack FreeBSD Generator` diff --git a/Help/module/CPackIFW.rst b/Help/module/CPackIFW.rst new file mode 100644 index 0000000..ea05796 --- /dev/null +++ b/Help/module/CPackIFW.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CPackIFW.cmake diff --git a/Help/module/CPackIFWConfigureFile.rst b/Help/module/CPackIFWConfigureFile.rst new file mode 100644 index 0000000..e88517c --- /dev/null +++ b/Help/module/CPackIFWConfigureFile.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CPackIFWConfigureFile.cmake diff --git a/Help/module/CPackNSIS.rst b/Help/module/CPackNSIS.rst new file mode 100644 index 0000000..2cb407a --- /dev/null +++ b/Help/module/CPackNSIS.rst @@ -0,0 +1,4 @@ +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 0000000..bbed7f9 --- /dev/null +++ b/Help/module/CPackNuGet.rst @@ -0,0 +1,6 @@ +CPackNuGet +---------- + +.. versionadded:: 3.12 + +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 new file mode 100644 index 0000000..226b6fd --- /dev/null +++ b/Help/module/CPackPackageMaker.rst @@ -0,0 +1,4 @@ +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 new file mode 100644 index 0000000..e12cd32 --- /dev/null +++ b/Help/module/CPackProductBuild.rst @@ -0,0 +1,6 @@ +CPackProductBuild +----------------- + +.. versionadded:: 3.7 + +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 new file mode 100644 index 0000000..00b7e0a --- /dev/null +++ b/Help/module/CPackRPM.rst @@ -0,0 +1,4 @@ +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 new file mode 100644 index 0000000..fd378b8 --- /dev/null +++ b/Help/module/CPackWIX.rst @@ -0,0 +1,5 @@ +CPackWIX +-------- + +The documentation for the CPack WIX generator has moved here: +:cpack_gen:`CPack WIX Generator` diff --git a/Help/module/CSharpUtilities.rst b/Help/module/CSharpUtilities.rst new file mode 100644 index 0000000..3621bbc --- /dev/null +++ b/Help/module/CSharpUtilities.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CSharpUtilities.cmake diff --git a/Help/module/CTest.rst b/Help/module/CTest.rst new file mode 100644 index 0000000..11a6af7 --- /dev/null +++ b/Help/module/CTest.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CTest.cmake diff --git a/Help/module/CTestCoverageCollectGCOV.rst b/Help/module/CTestCoverageCollectGCOV.rst new file mode 100644 index 0000000..4c5deca --- /dev/null +++ b/Help/module/CTestCoverageCollectGCOV.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CTestCoverageCollectGCOV.cmake diff --git a/Help/module/CTestScriptMode.rst b/Help/module/CTestScriptMode.rst new file mode 100644 index 0000000..be1b044 --- /dev/null +++ b/Help/module/CTestScriptMode.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CTestScriptMode.cmake diff --git a/Help/module/CTestUseLaunchers.rst b/Help/module/CTestUseLaunchers.rst new file mode 100644 index 0000000..688da08 --- /dev/null +++ b/Help/module/CTestUseLaunchers.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CTestUseLaunchers.cmake diff --git a/Help/module/CheckCCompilerFlag.rst b/Help/module/CheckCCompilerFlag.rst new file mode 100644 index 0000000..1be1491 --- /dev/null +++ b/Help/module/CheckCCompilerFlag.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckCCompilerFlag.cmake diff --git a/Help/module/CheckCSourceCompiles.rst b/Help/module/CheckCSourceCompiles.rst new file mode 100644 index 0000000..1fa02f9 --- /dev/null +++ b/Help/module/CheckCSourceCompiles.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckCSourceCompiles.cmake diff --git a/Help/module/CheckCSourceRuns.rst b/Help/module/CheckCSourceRuns.rst new file mode 100644 index 0000000..16b47e6 --- /dev/null +++ b/Help/module/CheckCSourceRuns.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckCSourceRuns.cmake diff --git a/Help/module/CheckCXXCompilerFlag.rst b/Help/module/CheckCXXCompilerFlag.rst new file mode 100644 index 0000000..cfd1f45 --- /dev/null +++ b/Help/module/CheckCXXCompilerFlag.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckCXXCompilerFlag.cmake diff --git a/Help/module/CheckCXXSourceCompiles.rst b/Help/module/CheckCXXSourceCompiles.rst new file mode 100644 index 0000000..d701c4e --- /dev/null +++ b/Help/module/CheckCXXSourceCompiles.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckCXXSourceCompiles.cmake diff --git a/Help/module/CheckCXXSourceRuns.rst b/Help/module/CheckCXXSourceRuns.rst new file mode 100644 index 0000000..caab975 --- /dev/null +++ b/Help/module/CheckCXXSourceRuns.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckCXXSourceRuns.cmake diff --git a/Help/module/CheckCXXSymbolExists.rst b/Help/module/CheckCXXSymbolExists.rst new file mode 100644 index 0000000..fc192e8 --- /dev/null +++ b/Help/module/CheckCXXSymbolExists.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckCXXSymbolExists.cmake diff --git a/Help/module/CheckCompilerFlag.rst b/Help/module/CheckCompilerFlag.rst new file mode 100644 index 0000000..bcf19a8 --- /dev/null +++ b/Help/module/CheckCompilerFlag.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckCompilerFlag.cmake diff --git a/Help/module/CheckFortranCompilerFlag.rst b/Help/module/CheckFortranCompilerFlag.rst new file mode 100644 index 0000000..58bf6ec --- /dev/null +++ b/Help/module/CheckFortranCompilerFlag.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckFortranCompilerFlag.cmake diff --git a/Help/module/CheckFortranFunctionExists.rst b/Help/module/CheckFortranFunctionExists.rst new file mode 100644 index 0000000..3395d05 --- /dev/null +++ b/Help/module/CheckFortranFunctionExists.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckFortranFunctionExists.cmake diff --git a/Help/module/CheckFortranSourceCompiles.rst b/Help/module/CheckFortranSourceCompiles.rst new file mode 100644 index 0000000..b749a2a --- /dev/null +++ b/Help/module/CheckFortranSourceCompiles.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckFortranSourceCompiles.cmake diff --git a/Help/module/CheckFortranSourceRuns.rst b/Help/module/CheckFortranSourceRuns.rst new file mode 100644 index 0000000..a1bff70 --- /dev/null +++ b/Help/module/CheckFortranSourceRuns.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckFortranSourceRuns.cmake diff --git a/Help/module/CheckFunctionExists.rst b/Help/module/CheckFunctionExists.rst new file mode 100644 index 0000000..ed89dc4 --- /dev/null +++ b/Help/module/CheckFunctionExists.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckFunctionExists.cmake diff --git a/Help/module/CheckIPOSupported.rst b/Help/module/CheckIPOSupported.rst new file mode 100644 index 0000000..9c8a77b --- /dev/null +++ b/Help/module/CheckIPOSupported.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckIPOSupported.cmake diff --git a/Help/module/CheckIncludeFile.rst b/Help/module/CheckIncludeFile.rst new file mode 100644 index 0000000..6b83108 --- /dev/null +++ b/Help/module/CheckIncludeFile.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckIncludeFile.cmake diff --git a/Help/module/CheckIncludeFileCXX.rst b/Help/module/CheckIncludeFileCXX.rst new file mode 100644 index 0000000..fdbf39f --- /dev/null +++ b/Help/module/CheckIncludeFileCXX.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckIncludeFileCXX.cmake diff --git a/Help/module/CheckIncludeFiles.rst b/Help/module/CheckIncludeFiles.rst new file mode 100644 index 0000000..b56f145 --- /dev/null +++ b/Help/module/CheckIncludeFiles.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckIncludeFiles.cmake diff --git a/Help/module/CheckLanguage.rst b/Help/module/CheckLanguage.rst new file mode 100644 index 0000000..16f1a3f --- /dev/null +++ b/Help/module/CheckLanguage.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckLanguage.cmake diff --git a/Help/module/CheckLibraryExists.rst b/Help/module/CheckLibraryExists.rst new file mode 100644 index 0000000..7512f46 --- /dev/null +++ b/Help/module/CheckLibraryExists.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckLibraryExists.cmake diff --git a/Help/module/CheckLinkerFlag.rst b/Help/module/CheckLinkerFlag.rst new file mode 100644 index 0000000..4005725 --- /dev/null +++ b/Help/module/CheckLinkerFlag.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckLinkerFlag.cmake diff --git a/Help/module/CheckOBJCCompilerFlag.rst b/Help/module/CheckOBJCCompilerFlag.rst new file mode 100644 index 0000000..e4bd6fd --- /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 0000000..d4a1484 --- /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 0000000..c72f0db --- /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 0000000..1518a48 --- /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 0000000..a1c8ae9 --- /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 0000000..5198e1b --- /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 0000000..02e7b43 --- /dev/null +++ b/Help/module/CheckPIESupported.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckPIESupported.cmake diff --git a/Help/module/CheckPrototypeDefinition.rst b/Help/module/CheckPrototypeDefinition.rst new file mode 100644 index 0000000..073fcb5 --- /dev/null +++ b/Help/module/CheckPrototypeDefinition.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckPrototypeDefinition.cmake diff --git a/Help/module/CheckSourceCompiles.rst b/Help/module/CheckSourceCompiles.rst new file mode 100644 index 0000000..906db0a --- /dev/null +++ b/Help/module/CheckSourceCompiles.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckSourceCompiles.cmake diff --git a/Help/module/CheckSourceRuns.rst b/Help/module/CheckSourceRuns.rst new file mode 100644 index 0000000..d469244 --- /dev/null +++ b/Help/module/CheckSourceRuns.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckSourceRuns.cmake diff --git a/Help/module/CheckStructHasMember.rst b/Help/module/CheckStructHasMember.rst new file mode 100644 index 0000000..5277ad2 --- /dev/null +++ b/Help/module/CheckStructHasMember.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckStructHasMember.cmake diff --git a/Help/module/CheckSymbolExists.rst b/Help/module/CheckSymbolExists.rst new file mode 100644 index 0000000..68ae700 --- /dev/null +++ b/Help/module/CheckSymbolExists.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckSymbolExists.cmake diff --git a/Help/module/CheckTypeSize.rst b/Help/module/CheckTypeSize.rst new file mode 100644 index 0000000..6ad0345 --- /dev/null +++ b/Help/module/CheckTypeSize.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckTypeSize.cmake diff --git a/Help/module/CheckVariableExists.rst b/Help/module/CheckVariableExists.rst new file mode 100644 index 0000000..07f0777 --- /dev/null +++ b/Help/module/CheckVariableExists.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckVariableExists.cmake diff --git a/Help/module/Dart.rst b/Help/module/Dart.rst new file mode 100644 index 0000000..524ac33 --- /dev/null +++ b/Help/module/Dart.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/Dart.cmake diff --git a/Help/module/DeployQt4.rst b/Help/module/DeployQt4.rst new file mode 100644 index 0000000..3c0ef44 --- /dev/null +++ b/Help/module/DeployQt4.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/DeployQt4.cmake diff --git a/Help/module/Documentation.rst b/Help/module/Documentation.rst new file mode 100644 index 0000000..08e2ffb --- /dev/null +++ b/Help/module/Documentation.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/Documentation.cmake diff --git a/Help/module/ExternalData.rst b/Help/module/ExternalData.rst new file mode 100644 index 0000000..f0f8f1d --- /dev/null +++ b/Help/module/ExternalData.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/ExternalData.cmake diff --git a/Help/module/ExternalProject.rst b/Help/module/ExternalProject.rst new file mode 100644 index 0000000..fce7056 --- /dev/null +++ b/Help/module/ExternalProject.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/ExternalProject.cmake diff --git a/Help/module/FeatureSummary.rst b/Help/module/FeatureSummary.rst new file mode 100644 index 0000000..6fd8f38 --- /dev/null +++ b/Help/module/FeatureSummary.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FeatureSummary.cmake diff --git a/Help/module/FetchContent.rst b/Help/module/FetchContent.rst new file mode 100644 index 0000000..c130a6d --- /dev/null +++ b/Help/module/FetchContent.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FetchContent.cmake diff --git a/Help/module/FindALSA.rst b/Help/module/FindALSA.rst new file mode 100644 index 0000000..2a73786 --- /dev/null +++ b/Help/module/FindALSA.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindALSA.cmake diff --git a/Help/module/FindASPELL.rst b/Help/module/FindASPELL.rst new file mode 100644 index 0000000..56dedc4 --- /dev/null +++ b/Help/module/FindASPELL.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindASPELL.cmake diff --git a/Help/module/FindAVIFile.rst b/Help/module/FindAVIFile.rst new file mode 100644 index 0000000..71282a6 --- /dev/null +++ b/Help/module/FindAVIFile.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindAVIFile.cmake diff --git a/Help/module/FindArmadillo.rst b/Help/module/FindArmadillo.rst new file mode 100644 index 0000000..f0ac933 --- /dev/null +++ b/Help/module/FindArmadillo.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindArmadillo.cmake diff --git a/Help/module/FindBISON.rst b/Help/module/FindBISON.rst new file mode 100644 index 0000000..c6e5791 --- /dev/null +++ b/Help/module/FindBISON.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindBISON.cmake diff --git a/Help/module/FindBLAS.rst b/Help/module/FindBLAS.rst new file mode 100644 index 0000000..41f6771 --- /dev/null +++ b/Help/module/FindBLAS.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindBLAS.cmake diff --git a/Help/module/FindBZip2.rst b/Help/module/FindBZip2.rst new file mode 100644 index 0000000..281b1d1 --- /dev/null +++ b/Help/module/FindBZip2.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindBZip2.cmake diff --git a/Help/module/FindBacktrace.rst b/Help/module/FindBacktrace.rst new file mode 100644 index 0000000..e1ca48c --- /dev/null +++ b/Help/module/FindBacktrace.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindBacktrace.cmake diff --git a/Help/module/FindBoost.rst b/Help/module/FindBoost.rst new file mode 100644 index 0000000..1392540 --- /dev/null +++ b/Help/module/FindBoost.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindBoost.cmake diff --git a/Help/module/FindBullet.rst b/Help/module/FindBullet.rst new file mode 100644 index 0000000..4ed2b85 --- /dev/null +++ b/Help/module/FindBullet.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindBullet.cmake diff --git a/Help/module/FindCABLE.rst b/Help/module/FindCABLE.rst new file mode 100644 index 0000000..716d5ab --- /dev/null +++ b/Help/module/FindCABLE.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindCABLE.cmake diff --git a/Help/module/FindCUDA.rst b/Help/module/FindCUDA.rst new file mode 100644 index 0000000..46ffa9f --- /dev/null +++ b/Help/module/FindCUDA.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindCUDA.cmake diff --git a/Help/module/FindCUDAToolkit.rst b/Help/module/FindCUDAToolkit.rst new file mode 100644 index 0000000..5f01d68 --- /dev/null +++ b/Help/module/FindCUDAToolkit.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindCUDAToolkit.cmake diff --git a/Help/module/FindCURL.rst b/Help/module/FindCURL.rst new file mode 100644 index 0000000..e2acc49 --- /dev/null +++ b/Help/module/FindCURL.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindCURL.cmake diff --git a/Help/module/FindCVS.rst b/Help/module/FindCVS.rst new file mode 100644 index 0000000..c891c07 --- /dev/null +++ b/Help/module/FindCVS.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindCVS.cmake diff --git a/Help/module/FindCoin3D.rst b/Help/module/FindCoin3D.rst new file mode 100644 index 0000000..fc70a74 --- /dev/null +++ b/Help/module/FindCoin3D.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindCoin3D.cmake diff --git a/Help/module/FindCups.rst b/Help/module/FindCups.rst new file mode 100644 index 0000000..10d0646 --- /dev/null +++ b/Help/module/FindCups.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindCups.cmake diff --git a/Help/module/FindCurses.rst b/Help/module/FindCurses.rst new file mode 100644 index 0000000..73dd011 --- /dev/null +++ b/Help/module/FindCurses.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindCurses.cmake diff --git a/Help/module/FindCxxTest.rst b/Help/module/FindCxxTest.rst new file mode 100644 index 0000000..4f17c39 --- /dev/null +++ b/Help/module/FindCxxTest.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindCxxTest.cmake diff --git a/Help/module/FindCygwin.rst b/Help/module/FindCygwin.rst new file mode 100644 index 0000000..2e529dd --- /dev/null +++ b/Help/module/FindCygwin.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindCygwin.cmake diff --git a/Help/module/FindDCMTK.rst b/Help/module/FindDCMTK.rst new file mode 100644 index 0000000..8437d55 --- /dev/null +++ b/Help/module/FindDCMTK.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindDCMTK.cmake diff --git a/Help/module/FindDart.rst b/Help/module/FindDart.rst new file mode 100644 index 0000000..6f21ad4 --- /dev/null +++ b/Help/module/FindDart.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindDart.cmake diff --git a/Help/module/FindDevIL.rst b/Help/module/FindDevIL.rst new file mode 100644 index 0000000..91a28dd --- /dev/null +++ b/Help/module/FindDevIL.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindDevIL.cmake diff --git a/Help/module/FindDoxygen.rst b/Help/module/FindDoxygen.rst new file mode 100644 index 0000000..cffe734 --- /dev/null +++ b/Help/module/FindDoxygen.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindDoxygen.cmake diff --git a/Help/module/FindEXPAT.rst b/Help/module/FindEXPAT.rst new file mode 100644 index 0000000..5063680 --- /dev/null +++ b/Help/module/FindEXPAT.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindEXPAT.cmake diff --git a/Help/module/FindEnvModules.rst b/Help/module/FindEnvModules.rst new file mode 100644 index 0000000..72c120f --- /dev/null +++ b/Help/module/FindEnvModules.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindEnvModules.cmake diff --git a/Help/module/FindFLEX.rst b/Help/module/FindFLEX.rst new file mode 100644 index 0000000..cc90791 --- /dev/null +++ b/Help/module/FindFLEX.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindFLEX.cmake diff --git a/Help/module/FindFLTK.rst b/Help/module/FindFLTK.rst new file mode 100644 index 0000000..cc1964c --- /dev/null +++ b/Help/module/FindFLTK.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindFLTK.cmake diff --git a/Help/module/FindFLTK2.rst b/Help/module/FindFLTK2.rst new file mode 100644 index 0000000..5c2acc4 --- /dev/null +++ b/Help/module/FindFLTK2.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindFLTK2.cmake diff --git a/Help/module/FindFontconfig.rst b/Help/module/FindFontconfig.rst new file mode 100644 index 0000000..449fe09 --- /dev/null +++ b/Help/module/FindFontconfig.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindFontconfig.cmake diff --git a/Help/module/FindFreetype.rst b/Help/module/FindFreetype.rst new file mode 100644 index 0000000..424c3fc --- /dev/null +++ b/Help/module/FindFreetype.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindFreetype.cmake diff --git a/Help/module/FindGCCXML.rst b/Help/module/FindGCCXML.rst new file mode 100644 index 0000000..15fd4d0 --- /dev/null +++ b/Help/module/FindGCCXML.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindGCCXML.cmake diff --git a/Help/module/FindGDAL.rst b/Help/module/FindGDAL.rst new file mode 100644 index 0000000..81fcb3a --- /dev/null +++ b/Help/module/FindGDAL.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindGDAL.cmake diff --git a/Help/module/FindGIF.rst b/Help/module/FindGIF.rst new file mode 100644 index 0000000..03d3a75 --- /dev/null +++ b/Help/module/FindGIF.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindGIF.cmake diff --git a/Help/module/FindGLEW.rst b/Help/module/FindGLEW.rst new file mode 100644 index 0000000..77755da --- /dev/null +++ b/Help/module/FindGLEW.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindGLEW.cmake diff --git a/Help/module/FindGLUT.rst b/Help/module/FindGLUT.rst new file mode 100644 index 0000000..40263ee --- /dev/null +++ b/Help/module/FindGLUT.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindGLUT.cmake diff --git a/Help/module/FindGSL.rst b/Help/module/FindGSL.rst new file mode 100644 index 0000000..baf2213 --- /dev/null +++ b/Help/module/FindGSL.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindGSL.cmake diff --git a/Help/module/FindGTK.rst b/Help/module/FindGTK.rst new file mode 100644 index 0000000..1ce6a86 --- /dev/null +++ b/Help/module/FindGTK.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindGTK.cmake diff --git a/Help/module/FindGTK2.rst b/Help/module/FindGTK2.rst new file mode 100644 index 0000000..67c1ba9 --- /dev/null +++ b/Help/module/FindGTK2.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindGTK2.cmake diff --git a/Help/module/FindGTest.rst b/Help/module/FindGTest.rst new file mode 100644 index 0000000..0e3b4d7 --- /dev/null +++ b/Help/module/FindGTest.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindGTest.cmake diff --git a/Help/module/FindGettext.rst b/Help/module/FindGettext.rst new file mode 100644 index 0000000..e880dc0 --- /dev/null +++ b/Help/module/FindGettext.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindGettext.cmake diff --git a/Help/module/FindGit.rst b/Help/module/FindGit.rst new file mode 100644 index 0000000..dd540ef --- /dev/null +++ b/Help/module/FindGit.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindGit.cmake diff --git a/Help/module/FindGnuTLS.rst b/Help/module/FindGnuTLS.rst new file mode 100644 index 0000000..de0c1d4 --- /dev/null +++ b/Help/module/FindGnuTLS.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindGnuTLS.cmake diff --git a/Help/module/FindGnuplot.rst b/Help/module/FindGnuplot.rst new file mode 100644 index 0000000..93a18b6 --- /dev/null +++ b/Help/module/FindGnuplot.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindGnuplot.cmake diff --git a/Help/module/FindHDF5.rst b/Help/module/FindHDF5.rst new file mode 100644 index 0000000..8ac1b8b --- /dev/null +++ b/Help/module/FindHDF5.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindHDF5.cmake diff --git a/Help/module/FindHSPELL.rst b/Help/module/FindHSPELL.rst new file mode 100644 index 0000000..c1905a2 --- /dev/null +++ b/Help/module/FindHSPELL.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindHSPELL.cmake diff --git a/Help/module/FindHTMLHelp.rst b/Help/module/FindHTMLHelp.rst new file mode 100644 index 0000000..47d9c8c --- /dev/null +++ b/Help/module/FindHTMLHelp.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindHTMLHelp.cmake diff --git a/Help/module/FindHg.rst b/Help/module/FindHg.rst new file mode 100644 index 0000000..94aba6f --- /dev/null +++ b/Help/module/FindHg.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindHg.cmake diff --git a/Help/module/FindICU.rst b/Help/module/FindICU.rst new file mode 100644 index 0000000..ee3f4a9 --- /dev/null +++ b/Help/module/FindICU.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindICU.cmake diff --git a/Help/module/FindITK.rst b/Help/module/FindITK.rst new file mode 100644 index 0000000..21a922f --- /dev/null +++ b/Help/module/FindITK.rst @@ -0,0 +1,10 @@ +FindITK +------- + +This module no longer exists. + +This module existed in versions of CMake prior to 3.1, but became +only a thin wrapper around ``find_package(ITK NO_MODULE)`` to +provide compatibility for projects using long-outdated conventions. +Now ``find_package(ITK)`` will search for ``ITKConfig.cmake`` +directly. diff --git a/Help/module/FindIce.rst b/Help/module/FindIce.rst new file mode 100644 index 0000000..3af9405 --- /dev/null +++ b/Help/module/FindIce.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindIce.cmake diff --git a/Help/module/FindIconv.rst b/Help/module/FindIconv.rst new file mode 100644 index 0000000..c1f3ed0 --- /dev/null +++ b/Help/module/FindIconv.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindIconv.cmake diff --git a/Help/module/FindIcotool.rst b/Help/module/FindIcotool.rst new file mode 100644 index 0000000..c139f58 --- /dev/null +++ b/Help/module/FindIcotool.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindIcotool.cmake diff --git a/Help/module/FindImageMagick.rst b/Help/module/FindImageMagick.rst new file mode 100644 index 0000000..3a3596e --- /dev/null +++ b/Help/module/FindImageMagick.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindImageMagick.cmake diff --git a/Help/module/FindIntl.rst b/Help/module/FindIntl.rst new file mode 100644 index 0000000..813e2df --- /dev/null +++ b/Help/module/FindIntl.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindIntl.cmake diff --git a/Help/module/FindJNI.rst b/Help/module/FindJNI.rst new file mode 100644 index 0000000..b753cf8 --- /dev/null +++ b/Help/module/FindJNI.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindJNI.cmake diff --git a/Help/module/FindJPEG.rst b/Help/module/FindJPEG.rst new file mode 100644 index 0000000..8036352 --- /dev/null +++ b/Help/module/FindJPEG.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindJPEG.cmake diff --git a/Help/module/FindJasper.rst b/Help/module/FindJasper.rst new file mode 100644 index 0000000..725a87f --- /dev/null +++ b/Help/module/FindJasper.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindJasper.cmake diff --git a/Help/module/FindJava.rst b/Help/module/FindJava.rst new file mode 100644 index 0000000..39e6b6b --- /dev/null +++ b/Help/module/FindJava.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindJava.cmake diff --git a/Help/module/FindKDE3.rst b/Help/module/FindKDE3.rst new file mode 100644 index 0000000..13ac15c --- /dev/null +++ b/Help/module/FindKDE3.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindKDE3.cmake diff --git a/Help/module/FindKDE4.rst b/Help/module/FindKDE4.rst new file mode 100644 index 0000000..8b22f7f --- /dev/null +++ b/Help/module/FindKDE4.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindKDE4.cmake diff --git a/Help/module/FindLAPACK.rst b/Help/module/FindLAPACK.rst new file mode 100644 index 0000000..6e99090 --- /dev/null +++ b/Help/module/FindLAPACK.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindLAPACK.cmake diff --git a/Help/module/FindLATEX.rst b/Help/module/FindLATEX.rst new file mode 100644 index 0000000..4b14c71 --- /dev/null +++ b/Help/module/FindLATEX.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindLATEX.cmake diff --git a/Help/module/FindLTTngUST.rst b/Help/module/FindLTTngUST.rst new file mode 100644 index 0000000..a775462 --- /dev/null +++ b/Help/module/FindLTTngUST.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindLTTngUST.cmake diff --git a/Help/module/FindLibArchive.rst b/Help/module/FindLibArchive.rst new file mode 100644 index 0000000..c46b1d0 --- /dev/null +++ b/Help/module/FindLibArchive.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindLibArchive.cmake diff --git a/Help/module/FindLibLZMA.rst b/Help/module/FindLibLZMA.rst new file mode 100644 index 0000000..8880158 --- /dev/null +++ b/Help/module/FindLibLZMA.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindLibLZMA.cmake diff --git a/Help/module/FindLibXml2.rst b/Help/module/FindLibXml2.rst new file mode 100644 index 0000000..bbb3225 --- /dev/null +++ b/Help/module/FindLibXml2.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindLibXml2.cmake diff --git a/Help/module/FindLibXslt.rst b/Help/module/FindLibXslt.rst new file mode 100644 index 0000000..4107170 --- /dev/null +++ b/Help/module/FindLibXslt.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindLibXslt.cmake diff --git a/Help/module/FindLibinput.rst b/Help/module/FindLibinput.rst new file mode 100644 index 0000000..a8ca0b0 --- /dev/null +++ b/Help/module/FindLibinput.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindLibinput.cmake diff --git a/Help/module/FindLua.rst b/Help/module/FindLua.rst new file mode 100644 index 0000000..977e5bf --- /dev/null +++ b/Help/module/FindLua.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindLua.cmake diff --git a/Help/module/FindLua50.rst b/Help/module/FindLua50.rst new file mode 100644 index 0000000..0353fc3 --- /dev/null +++ b/Help/module/FindLua50.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindLua50.cmake diff --git a/Help/module/FindLua51.rst b/Help/module/FindLua51.rst new file mode 100644 index 0000000..672ff35 --- /dev/null +++ b/Help/module/FindLua51.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindLua51.cmake diff --git a/Help/module/FindMFC.rst b/Help/module/FindMFC.rst new file mode 100644 index 0000000..a3226a6 --- /dev/null +++ b/Help/module/FindMFC.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindMFC.cmake diff --git a/Help/module/FindMPEG.rst b/Help/module/FindMPEG.rst new file mode 100644 index 0000000..c9ce481 --- /dev/null +++ b/Help/module/FindMPEG.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindMPEG.cmake diff --git a/Help/module/FindMPEG2.rst b/Help/module/FindMPEG2.rst new file mode 100644 index 0000000..f843c89 --- /dev/null +++ b/Help/module/FindMPEG2.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindMPEG2.cmake diff --git a/Help/module/FindMPI.rst b/Help/module/FindMPI.rst new file mode 100644 index 0000000..fad10c7 --- /dev/null +++ b/Help/module/FindMPI.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindMPI.cmake diff --git a/Help/module/FindMatlab.rst b/Help/module/FindMatlab.rst new file mode 100644 index 0000000..43f861a --- /dev/null +++ b/Help/module/FindMatlab.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindMatlab.cmake diff --git a/Help/module/FindMotif.rst b/Help/module/FindMotif.rst new file mode 100644 index 0000000..e602a50 --- /dev/null +++ b/Help/module/FindMotif.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindMotif.cmake diff --git a/Help/module/FindODBC.rst b/Help/module/FindODBC.rst new file mode 100644 index 0000000..8558334 --- /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 0000000..dda3308 --- /dev/null +++ b/Help/module/FindOpenACC.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindOpenACC.cmake diff --git a/Help/module/FindOpenAL.rst b/Help/module/FindOpenAL.rst new file mode 100644 index 0000000..f086556 --- /dev/null +++ b/Help/module/FindOpenAL.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindOpenAL.cmake diff --git a/Help/module/FindOpenCL.rst b/Help/module/FindOpenCL.rst new file mode 100644 index 0000000..e87e289 --- /dev/null +++ b/Help/module/FindOpenCL.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindOpenCL.cmake diff --git a/Help/module/FindOpenGL.rst b/Help/module/FindOpenGL.rst new file mode 100644 index 0000000..85e89bc --- /dev/null +++ b/Help/module/FindOpenGL.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindOpenGL.cmake diff --git a/Help/module/FindOpenMP.rst b/Help/module/FindOpenMP.rst new file mode 100644 index 0000000..01362ab --- /dev/null +++ b/Help/module/FindOpenMP.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindOpenMP.cmake diff --git a/Help/module/FindOpenSSL.rst b/Help/module/FindOpenSSL.rst new file mode 100644 index 0000000..f622bb1 --- /dev/null +++ b/Help/module/FindOpenSSL.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindOpenSSL.cmake diff --git a/Help/module/FindOpenSceneGraph.rst b/Help/module/FindOpenSceneGraph.rst new file mode 100644 index 0000000..4346492 --- /dev/null +++ b/Help/module/FindOpenSceneGraph.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindOpenSceneGraph.cmake diff --git a/Help/module/FindOpenThreads.rst b/Help/module/FindOpenThreads.rst new file mode 100644 index 0000000..bb3f0f9 --- /dev/null +++ b/Help/module/FindOpenThreads.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindOpenThreads.cmake diff --git a/Help/module/FindPHP4.rst b/Help/module/FindPHP4.rst new file mode 100644 index 0000000..1de62e8 --- /dev/null +++ b/Help/module/FindPHP4.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindPHP4.cmake diff --git a/Help/module/FindPNG.rst b/Help/module/FindPNG.rst new file mode 100644 index 0000000..e6d1618 --- /dev/null +++ b/Help/module/FindPNG.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindPNG.cmake diff --git a/Help/module/FindPackageHandleStandardArgs.rst b/Help/module/FindPackageHandleStandardArgs.rst new file mode 100644 index 0000000..feda7ef --- /dev/null +++ b/Help/module/FindPackageHandleStandardArgs.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindPackageHandleStandardArgs.cmake diff --git a/Help/module/FindPackageMessage.rst b/Help/module/FindPackageMessage.rst new file mode 100644 index 0000000..b682d8c --- /dev/null +++ b/Help/module/FindPackageMessage.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindPackageMessage.cmake diff --git a/Help/module/FindPatch.rst b/Help/module/FindPatch.rst new file mode 100644 index 0000000..ba5e910 --- /dev/null +++ b/Help/module/FindPatch.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindPatch.cmake diff --git a/Help/module/FindPerl.rst b/Help/module/FindPerl.rst new file mode 100644 index 0000000..098f4b5 --- /dev/null +++ b/Help/module/FindPerl.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindPerl.cmake diff --git a/Help/module/FindPerlLibs.rst b/Help/module/FindPerlLibs.rst new file mode 100644 index 0000000..8d8bbab --- /dev/null +++ b/Help/module/FindPerlLibs.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindPerlLibs.cmake diff --git a/Help/module/FindPhysFS.rst b/Help/module/FindPhysFS.rst new file mode 100644 index 0000000..21d928b --- /dev/null +++ b/Help/module/FindPhysFS.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindPhysFS.cmake diff --git a/Help/module/FindPike.rst b/Help/module/FindPike.rst new file mode 100644 index 0000000..b096ca4 --- /dev/null +++ b/Help/module/FindPike.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindPike.cmake diff --git a/Help/module/FindPkgConfig.rst b/Help/module/FindPkgConfig.rst new file mode 100644 index 0000000..b8caf74 --- /dev/null +++ b/Help/module/FindPkgConfig.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindPkgConfig.cmake diff --git a/Help/module/FindPostgreSQL.rst b/Help/module/FindPostgreSQL.rst new file mode 100644 index 0000000..b45c07e --- /dev/null +++ b/Help/module/FindPostgreSQL.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindPostgreSQL.cmake diff --git a/Help/module/FindProducer.rst b/Help/module/FindProducer.rst new file mode 100644 index 0000000..1c0c575 --- /dev/null +++ b/Help/module/FindProducer.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindProducer.cmake diff --git a/Help/module/FindProtobuf.rst b/Help/module/FindProtobuf.rst new file mode 100644 index 0000000..b978e01 --- /dev/null +++ b/Help/module/FindProtobuf.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindProtobuf.cmake diff --git a/Help/module/FindPython.rst b/Help/module/FindPython.rst new file mode 100644 index 0000000..057a350 --- /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 0000000..1696bed --- /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 0000000..e530ab8 --- /dev/null +++ b/Help/module/FindPython3.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindPython3.cmake diff --git a/Help/module/FindPythonInterp.rst b/Help/module/FindPythonInterp.rst new file mode 100644 index 0000000..3be2306 --- /dev/null +++ b/Help/module/FindPythonInterp.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindPythonInterp.cmake diff --git a/Help/module/FindPythonLibs.rst b/Help/module/FindPythonLibs.rst new file mode 100644 index 0000000..8f0015d --- /dev/null +++ b/Help/module/FindPythonLibs.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindPythonLibs.cmake diff --git a/Help/module/FindQt.rst b/Help/module/FindQt.rst new file mode 100644 index 0000000..3aa8a26 --- /dev/null +++ b/Help/module/FindQt.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindQt.cmake diff --git a/Help/module/FindQt3.rst b/Help/module/FindQt3.rst new file mode 100644 index 0000000..b933059 --- /dev/null +++ b/Help/module/FindQt3.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindQt3.cmake diff --git a/Help/module/FindQt4.rst b/Help/module/FindQt4.rst new file mode 100644 index 0000000..28036b2 --- /dev/null +++ b/Help/module/FindQt4.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindQt4.cmake diff --git a/Help/module/FindQuickTime.rst b/Help/module/FindQuickTime.rst new file mode 100644 index 0000000..735f7d2 --- /dev/null +++ b/Help/module/FindQuickTime.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindQuickTime.cmake diff --git a/Help/module/FindRTI.rst b/Help/module/FindRTI.rst new file mode 100644 index 0000000..a93ad16 --- /dev/null +++ b/Help/module/FindRTI.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindRTI.cmake diff --git a/Help/module/FindRuby.rst b/Help/module/FindRuby.rst new file mode 100644 index 0000000..a1e7922 --- /dev/null +++ b/Help/module/FindRuby.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindRuby.cmake diff --git a/Help/module/FindSDL.rst b/Help/module/FindSDL.rst new file mode 100644 index 0000000..79893c0 --- /dev/null +++ b/Help/module/FindSDL.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindSDL.cmake diff --git a/Help/module/FindSDL_image.rst b/Help/module/FindSDL_image.rst new file mode 100644 index 0000000..dc69d70 --- /dev/null +++ b/Help/module/FindSDL_image.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindSDL_image.cmake diff --git a/Help/module/FindSDL_mixer.rst b/Help/module/FindSDL_mixer.rst new file mode 100644 index 0000000..1c9c446 --- /dev/null +++ b/Help/module/FindSDL_mixer.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindSDL_mixer.cmake diff --git a/Help/module/FindSDL_net.rst b/Help/module/FindSDL_net.rst new file mode 100644 index 0000000..079d0bb --- /dev/null +++ b/Help/module/FindSDL_net.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindSDL_net.cmake diff --git a/Help/module/FindSDL_sound.rst b/Help/module/FindSDL_sound.rst new file mode 100644 index 0000000..077edf7 --- /dev/null +++ b/Help/module/FindSDL_sound.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindSDL_sound.cmake diff --git a/Help/module/FindSDL_ttf.rst b/Help/module/FindSDL_ttf.rst new file mode 100644 index 0000000..40c5ec4 --- /dev/null +++ b/Help/module/FindSDL_ttf.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindSDL_ttf.cmake diff --git a/Help/module/FindSQLite3.rst b/Help/module/FindSQLite3.rst new file mode 100644 index 0000000..d1910e5 --- /dev/null +++ b/Help/module/FindSQLite3.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindSQLite3.cmake diff --git a/Help/module/FindSWIG.rst b/Help/module/FindSWIG.rst new file mode 100644 index 0000000..9b25b94 --- /dev/null +++ b/Help/module/FindSWIG.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindSWIG.cmake diff --git a/Help/module/FindSelfPackers.rst b/Help/module/FindSelfPackers.rst new file mode 100644 index 0000000..5f2c689 --- /dev/null +++ b/Help/module/FindSelfPackers.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindSelfPackers.cmake diff --git a/Help/module/FindSquish.rst b/Help/module/FindSquish.rst new file mode 100644 index 0000000..dc2c86d --- /dev/null +++ b/Help/module/FindSquish.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindSquish.cmake diff --git a/Help/module/FindSubversion.rst b/Help/module/FindSubversion.rst new file mode 100644 index 0000000..aa15857 --- /dev/null +++ b/Help/module/FindSubversion.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindSubversion.cmake diff --git a/Help/module/FindTCL.rst b/Help/module/FindTCL.rst new file mode 100644 index 0000000..cbd2035 --- /dev/null +++ b/Help/module/FindTCL.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindTCL.cmake diff --git a/Help/module/FindTIFF.rst b/Help/module/FindTIFF.rst new file mode 100644 index 0000000..69f8ca5 --- /dev/null +++ b/Help/module/FindTIFF.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindTIFF.cmake diff --git a/Help/module/FindTclStub.rst b/Help/module/FindTclStub.rst new file mode 100644 index 0000000..6cc5b2d --- /dev/null +++ b/Help/module/FindTclStub.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindTclStub.cmake diff --git a/Help/module/FindTclsh.rst b/Help/module/FindTclsh.rst new file mode 100644 index 0000000..23e7d6b --- /dev/null +++ b/Help/module/FindTclsh.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindTclsh.cmake diff --git a/Help/module/FindThreads.rst b/Help/module/FindThreads.rst new file mode 100644 index 0000000..91967a7 --- /dev/null +++ b/Help/module/FindThreads.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindThreads.cmake diff --git a/Help/module/FindUnixCommands.rst b/Help/module/FindUnixCommands.rst new file mode 100644 index 0000000..9ad05ad --- /dev/null +++ b/Help/module/FindUnixCommands.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindUnixCommands.cmake diff --git a/Help/module/FindVTK.rst b/Help/module/FindVTK.rst new file mode 100644 index 0000000..3bc67c5 --- /dev/null +++ b/Help/module/FindVTK.rst @@ -0,0 +1,10 @@ +FindVTK +------- + +This module no longer exists. + +This module existed in versions of CMake prior to 3.1, but became +only a thin wrapper around ``find_package(VTK NO_MODULE)`` to +provide compatibility for projects using long-outdated conventions. +Now ``find_package(VTK)`` will search for ``VTKConfig.cmake`` +directly. diff --git a/Help/module/FindVulkan.rst b/Help/module/FindVulkan.rst new file mode 100644 index 0000000..adf824e --- /dev/null +++ b/Help/module/FindVulkan.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindVulkan.cmake diff --git a/Help/module/FindWget.rst b/Help/module/FindWget.rst new file mode 100644 index 0000000..06affd4 --- /dev/null +++ b/Help/module/FindWget.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindWget.cmake diff --git a/Help/module/FindWish.rst b/Help/module/FindWish.rst new file mode 100644 index 0000000..76be4cf --- /dev/null +++ b/Help/module/FindWish.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindWish.cmake diff --git a/Help/module/FindX11.rst b/Help/module/FindX11.rst new file mode 100644 index 0000000..906efd7 --- /dev/null +++ b/Help/module/FindX11.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindX11.cmake diff --git a/Help/module/FindXCTest.rst b/Help/module/FindXCTest.rst new file mode 100644 index 0000000..ff6273c --- /dev/null +++ b/Help/module/FindXCTest.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindXCTest.cmake diff --git a/Help/module/FindXMLRPC.rst b/Help/module/FindXMLRPC.rst new file mode 100644 index 0000000..5d11a0c --- /dev/null +++ b/Help/module/FindXMLRPC.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindXMLRPC.cmake diff --git a/Help/module/FindXalanC.rst b/Help/module/FindXalanC.rst new file mode 100644 index 0000000..b99d212 --- /dev/null +++ b/Help/module/FindXalanC.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindXalanC.cmake diff --git a/Help/module/FindXercesC.rst b/Help/module/FindXercesC.rst new file mode 100644 index 0000000..4818071 --- /dev/null +++ b/Help/module/FindXercesC.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindXercesC.cmake diff --git a/Help/module/FindZLIB.rst b/Help/module/FindZLIB.rst new file mode 100644 index 0000000..ded8634 --- /dev/null +++ b/Help/module/FindZLIB.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindZLIB.cmake diff --git a/Help/module/Findosg.rst b/Help/module/Findosg.rst new file mode 100644 index 0000000..6b407ac --- /dev/null +++ b/Help/module/Findosg.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/Findosg.cmake diff --git a/Help/module/FindosgAnimation.rst b/Help/module/FindosgAnimation.rst new file mode 100644 index 0000000..f14a1e7 --- /dev/null +++ b/Help/module/FindosgAnimation.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindosgAnimation.cmake diff --git a/Help/module/FindosgDB.rst b/Help/module/FindosgDB.rst new file mode 100644 index 0000000..9f72bc7 --- /dev/null +++ b/Help/module/FindosgDB.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindosgDB.cmake diff --git a/Help/module/FindosgFX.rst b/Help/module/FindosgFX.rst new file mode 100644 index 0000000..0e1edfb --- /dev/null +++ b/Help/module/FindosgFX.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindosgFX.cmake diff --git a/Help/module/FindosgGA.rst b/Help/module/FindosgGA.rst new file mode 100644 index 0000000..562d73f --- /dev/null +++ b/Help/module/FindosgGA.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindosgGA.cmake diff --git a/Help/module/FindosgIntrospection.rst b/Help/module/FindosgIntrospection.rst new file mode 100644 index 0000000..53621a7 --- /dev/null +++ b/Help/module/FindosgIntrospection.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindosgIntrospection.cmake diff --git a/Help/module/FindosgManipulator.rst b/Help/module/FindosgManipulator.rst new file mode 100644 index 0000000..b9d615d --- /dev/null +++ b/Help/module/FindosgManipulator.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindosgManipulator.cmake diff --git a/Help/module/FindosgParticle.rst b/Help/module/FindosgParticle.rst new file mode 100644 index 0000000..9cf191c --- /dev/null +++ b/Help/module/FindosgParticle.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindosgParticle.cmake diff --git a/Help/module/FindosgPresentation.rst b/Help/module/FindosgPresentation.rst new file mode 100644 index 0000000..cb47841 --- /dev/null +++ b/Help/module/FindosgPresentation.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindosgPresentation.cmake diff --git a/Help/module/FindosgProducer.rst b/Help/module/FindosgProducer.rst new file mode 100644 index 0000000..c502851 --- /dev/null +++ b/Help/module/FindosgProducer.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindosgProducer.cmake diff --git a/Help/module/FindosgQt.rst b/Help/module/FindosgQt.rst new file mode 100644 index 0000000..08c8704 --- /dev/null +++ b/Help/module/FindosgQt.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindosgQt.cmake diff --git a/Help/module/FindosgShadow.rst b/Help/module/FindosgShadow.rst new file mode 100644 index 0000000..fbb22e1 --- /dev/null +++ b/Help/module/FindosgShadow.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindosgShadow.cmake diff --git a/Help/module/FindosgSim.rst b/Help/module/FindosgSim.rst new file mode 100644 index 0000000..9e47b65 --- /dev/null +++ b/Help/module/FindosgSim.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindosgSim.cmake diff --git a/Help/module/FindosgTerrain.rst b/Help/module/FindosgTerrain.rst new file mode 100644 index 0000000..dd401d8 --- /dev/null +++ b/Help/module/FindosgTerrain.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindosgTerrain.cmake diff --git a/Help/module/FindosgText.rst b/Help/module/FindosgText.rst new file mode 100644 index 0000000..bb028fb --- /dev/null +++ b/Help/module/FindosgText.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindosgText.cmake diff --git a/Help/module/FindosgUtil.rst b/Help/module/FindosgUtil.rst new file mode 100644 index 0000000..bb11bdf --- /dev/null +++ b/Help/module/FindosgUtil.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindosgUtil.cmake diff --git a/Help/module/FindosgViewer.rst b/Help/module/FindosgViewer.rst new file mode 100644 index 0000000..5def375 --- /dev/null +++ b/Help/module/FindosgViewer.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindosgViewer.cmake diff --git a/Help/module/FindosgVolume.rst b/Help/module/FindosgVolume.rst new file mode 100644 index 0000000..d836906 --- /dev/null +++ b/Help/module/FindosgVolume.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindosgVolume.cmake diff --git a/Help/module/FindosgWidget.rst b/Help/module/FindosgWidget.rst new file mode 100644 index 0000000..bdd1135 --- /dev/null +++ b/Help/module/FindosgWidget.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindosgWidget.cmake diff --git a/Help/module/Findosg_functions.rst b/Help/module/Findosg_functions.rst new file mode 100644 index 0000000..522e1ac --- /dev/null +++ b/Help/module/Findosg_functions.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/Findosg_functions.cmake diff --git a/Help/module/FindwxWidgets.rst b/Help/module/FindwxWidgets.rst new file mode 100644 index 0000000..519beb7 --- /dev/null +++ b/Help/module/FindwxWidgets.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindwxWidgets.cmake diff --git a/Help/module/FindwxWindows.rst b/Help/module/FindwxWindows.rst new file mode 100644 index 0000000..35c9728 --- /dev/null +++ b/Help/module/FindwxWindows.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindwxWindows.cmake diff --git a/Help/module/FortranCInterface.rst b/Help/module/FortranCInterface.rst new file mode 100644 index 0000000..7afcf15 --- /dev/null +++ b/Help/module/FortranCInterface.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FortranCInterface.cmake diff --git a/Help/module/GNUInstallDirs.rst b/Help/module/GNUInstallDirs.rst new file mode 100644 index 0000000..79d3570 --- /dev/null +++ b/Help/module/GNUInstallDirs.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/GNUInstallDirs.cmake diff --git a/Help/module/GenerateExportHeader.rst b/Help/module/GenerateExportHeader.rst new file mode 100644 index 0000000..115713e --- /dev/null +++ b/Help/module/GenerateExportHeader.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/GenerateExportHeader.cmake diff --git a/Help/module/GetPrerequisites.rst b/Help/module/GetPrerequisites.rst new file mode 100644 index 0000000..84b20c8 --- /dev/null +++ b/Help/module/GetPrerequisites.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/GetPrerequisites.cmake diff --git a/Help/module/GoogleTest.rst b/Help/module/GoogleTest.rst new file mode 100644 index 0000000..3d4cc97 --- /dev/null +++ b/Help/module/GoogleTest.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/GoogleTest.cmake diff --git a/Help/module/InstallRequiredSystemLibraries.rst b/Help/module/InstallRequiredSystemLibraries.rst new file mode 100644 index 0000000..5ea9af3 --- /dev/null +++ b/Help/module/InstallRequiredSystemLibraries.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/InstallRequiredSystemLibraries.cmake diff --git a/Help/module/MacroAddFileDependencies.rst b/Help/module/MacroAddFileDependencies.rst new file mode 100644 index 0000000..5f0bf6b --- /dev/null +++ b/Help/module/MacroAddFileDependencies.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/MacroAddFileDependencies.cmake diff --git a/Help/module/ProcessorCount.rst b/Help/module/ProcessorCount.rst new file mode 100644 index 0000000..0149d09 --- /dev/null +++ b/Help/module/ProcessorCount.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/ProcessorCount.cmake diff --git a/Help/module/SelectLibraryConfigurations.rst b/Help/module/SelectLibraryConfigurations.rst new file mode 100644 index 0000000..14fd6f8 --- /dev/null +++ b/Help/module/SelectLibraryConfigurations.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/SelectLibraryConfigurations.cmake diff --git a/Help/module/SquishTestScript.rst b/Help/module/SquishTestScript.rst new file mode 100644 index 0000000..47da404 --- /dev/null +++ b/Help/module/SquishTestScript.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/SquishTestScript.cmake diff --git a/Help/module/TestBigEndian.rst b/Help/module/TestBigEndian.rst new file mode 100644 index 0000000..f9e4d2f --- /dev/null +++ b/Help/module/TestBigEndian.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/TestBigEndian.cmake diff --git a/Help/module/TestCXXAcceptsFlag.rst b/Help/module/TestCXXAcceptsFlag.rst new file mode 100644 index 0000000..ee3d70a --- /dev/null +++ b/Help/module/TestCXXAcceptsFlag.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/TestCXXAcceptsFlag.cmake diff --git a/Help/module/TestForANSIForScope.rst b/Help/module/TestForANSIForScope.rst new file mode 100644 index 0000000..00d9238 --- /dev/null +++ b/Help/module/TestForANSIForScope.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/TestForANSIForScope.cmake diff --git a/Help/module/TestForANSIStreamHeaders.rst b/Help/module/TestForANSIStreamHeaders.rst new file mode 100644 index 0000000..212a30b --- /dev/null +++ b/Help/module/TestForANSIStreamHeaders.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/TestForANSIStreamHeaders.cmake diff --git a/Help/module/TestForSSTREAM.rst b/Help/module/TestForSSTREAM.rst new file mode 100644 index 0000000..d154751 --- /dev/null +++ b/Help/module/TestForSSTREAM.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/TestForSSTREAM.cmake diff --git a/Help/module/TestForSTDNamespace.rst b/Help/module/TestForSTDNamespace.rst new file mode 100644 index 0000000..ad989e3 --- /dev/null +++ b/Help/module/TestForSTDNamespace.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/TestForSTDNamespace.cmake diff --git a/Help/module/UseEcos.rst b/Help/module/UseEcos.rst new file mode 100644 index 0000000..0e57868 --- /dev/null +++ b/Help/module/UseEcos.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/UseEcos.cmake diff --git a/Help/module/UseJava.rst b/Help/module/UseJava.rst new file mode 100644 index 0000000..fa2f1bd --- /dev/null +++ b/Help/module/UseJava.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/UseJava.cmake diff --git a/Help/module/UseJavaClassFilelist.rst b/Help/module/UseJavaClassFilelist.rst new file mode 100644 index 0000000..29949be --- /dev/null +++ b/Help/module/UseJavaClassFilelist.rst @@ -0,0 +1,6 @@ +UseJavaClassFilelist +-------------------- + +.. versionchanged:: 3.20 + This module was previously documented by mistake and was never meant for + direct inclusion by project code. See the :module:`UseJava` module. diff --git a/Help/module/UseJavaSymlinks.rst b/Help/module/UseJavaSymlinks.rst new file mode 100644 index 0000000..1058a68 --- /dev/null +++ b/Help/module/UseJavaSymlinks.rst @@ -0,0 +1,6 @@ +UseJavaSymlinks +--------------- + +.. versionchanged:: 3.20 + This module was previously documented by mistake and was never meant for + direct inclusion by project code. See the :module:`UseJava` module. diff --git a/Help/module/UsePkgConfig.rst b/Help/module/UsePkgConfig.rst new file mode 100644 index 0000000..668f766 --- /dev/null +++ b/Help/module/UsePkgConfig.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/UsePkgConfig.cmake diff --git a/Help/module/UseSWIG.rst b/Help/module/UseSWIG.rst new file mode 100644 index 0000000..0007c35 --- /dev/null +++ b/Help/module/UseSWIG.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/UseSWIG.cmake diff --git a/Help/module/Use_wxWindows.rst b/Help/module/Use_wxWindows.rst new file mode 100644 index 0000000..a489e98 --- /dev/null +++ b/Help/module/Use_wxWindows.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/Use_wxWindows.cmake diff --git a/Help/module/UsewxWidgets.rst b/Help/module/UsewxWidgets.rst new file mode 100644 index 0000000..6829c2d --- /dev/null +++ b/Help/module/UsewxWidgets.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/UsewxWidgets.cmake diff --git a/Help/module/WriteBasicConfigVersionFile.rst b/Help/module/WriteBasicConfigVersionFile.rst new file mode 100644 index 0000000..c637d5d --- /dev/null +++ b/Help/module/WriteBasicConfigVersionFile.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/WriteBasicConfigVersionFile.cmake diff --git a/Help/module/WriteCompilerDetectionHeader.rst b/Help/module/WriteCompilerDetectionHeader.rst new file mode 100644 index 0000000..4c81b48 --- /dev/null +++ b/Help/module/WriteCompilerDetectionHeader.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/WriteCompilerDetectionHeader.cmake diff --git a/Help/policy/CMP0000.rst b/Help/policy/CMP0000.rst new file mode 100644 index 0000000..aecfa71 --- /dev/null +++ b/Help/policy/CMP0000.rst @@ -0,0 +1,34 @@ +CMP0000 +------- + +A minimum required CMake version must be specified. + +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 :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 ``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 :command:`cmake_minimum_required` for +details. + +Note that the command invocation must appear in the ``CMakeLists.txt`` +file itself; a call in an included file is not sufficient. However, +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. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0001.rst b/Help/policy/CMP0001.rst new file mode 100644 index 0000000..6fa64d9 --- /dev/null +++ b/Help/policy/CMP0001.rst @@ -0,0 +1,21 @@ +CMP0001 +------- + +``CMAKE_BACKWARDS_COMPATIBILITY`` should no longer be used. + +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 +used to request compatibility with earlier versions of CMake. In +CMake 2.6 and above all compatibility issues are handled by policies +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 :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 new file mode 100644 index 0000000..dc68d51 --- /dev/null +++ b/Help/policy/CMP0002.rst @@ -0,0 +1,28 @@ +CMP0002 +------- + +Logical target names must be globally unique. + +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: + +:: + + - Unique names may be referenced unambiguously both in CMake + code and on make tool command lines. + - Logical names are used by Xcode and VS IDE generators + to produce meaningful project names for the targets. + +The logical name of executable and library targets does not have to +correspond to the physical file names built. Consider using the +: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 :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 :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 new file mode 100644 index 0000000..dd90883 --- /dev/null +++ b/Help/policy/CMP0003.rst @@ -0,0 +1,104 @@ +CMP0003 +------- + +Libraries linked via full path no longer produce linker search paths. + +This policy affects how libraries whose full paths are NOT known are +found at link time, but was created due to a change in how CMake deals +with libraries whose full paths are known. Consider the code + +:: + + target_link_libraries(myexe /path/to/libA.so) + +CMake 2.4 and below implemented linking to libraries whose full paths +are known by splitting them on the link line into separate components +consisting of the linker search path and the library name. The +example code might have produced something like + +:: + + ... -L/path/to -lA ... + +in order to link to library A. An analysis was performed to order +multiple link directories such that the linker would find library A in +the desired location, but there are cases in which this does not work. +CMake versions 2.6 and above use the more reliable approach of passing +the full path to libraries directly to the linker in most cases. The +example code now produces something like + +:: + + ... /path/to/libA.so .... + +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 +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 +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 +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 +will produce a link line such as + +:: + + ... -L/path/to /path/to/libA.so -lB ... + +which will allow library B to be found as it was previously. When +this policy is set to NEW, CMake will produce a link line such as + +:: + + ... /path/to/libA.so -lB ... + +which more accurately matches what the project specified. + +The setting for this policy used when generating the link line is that +in effect when the target is created by an add_executable or +add_library command. For the example described above, the code + +:: + + cmake_policy(SET CMP0003 OLD) # or cmake_policy(VERSION 2.4) + add_executable(myexe myexe.c) + target_link_libraries(myexe /path/to/libA.so B) + +will work and suppress the warning for this policy. It may also be +updated to work with the corrected linking approach: + +:: + + cmake_policy(SET CMP0003 NEW) # or cmake_policy(VERSION 2.6) + link_directories(/path/to) # needed to find library B + add_executable(myexe myexe.c) + target_link_libraries(myexe /path/to/libA.so B) + +Even better, library B may be specified with a full path: + +:: + + add_executable(myexe myexe.c) + target_link_libraries(myexe /path/to/libA.so /path/to/libB.so) + +When all items on the link line have known paths CMake does not check +this policy so it has no effect. + +Note that the warning for this policy will be issued for at most one +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 :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 new file mode 100644 index 0000000..be6d307 --- /dev/null +++ b/Help/policy/CMP0004.rst @@ -0,0 +1,26 @@ +CMP0004 +------- + +Libraries linked may not have leading or trailing whitespace. + +CMake versions 2.4 and below silently removed leading and trailing +whitespace from libraries linked with code like + +:: + + target_link_libraries(myexe " A ") + +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 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 :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 :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 new file mode 100644 index 0000000..59567d5 --- /dev/null +++ b/Help/policy/CMP0005.rst @@ -0,0 +1,26 @@ +CMP0005 +------- + +Preprocessor definition values are now escaped automatically. + +This policy determines whether or not CMake should generate escaped +preprocessor definition values added via add_definitions. CMake +versions 2.4 and below assumed that only trivial values would be given +for macros in add_definitions calls. It did not attempt to escape +non-trivial values such as string literals in generated build rules. +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 +to add_definitions directly in the generated build rules without +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 +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 :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 new file mode 100644 index 0000000..181958b --- /dev/null +++ b/Help/policy/CMP0006.rst @@ -0,0 +1,24 @@ +CMP0006 +------- + +Installing :prop_tgt:`MACOSX_BUNDLE` targets requires a ``BUNDLE DESTINATION``. + +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 :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 +: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``. + +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 :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 new file mode 100644 index 0000000..1006ed3 --- /dev/null +++ b/Help/policy/CMP0007.rst @@ -0,0 +1,17 @@ +CMP0007 +------- + +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 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 :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 new file mode 100644 index 0000000..18ede82 --- /dev/null +++ b/Help/policy/CMP0008.rst @@ -0,0 +1,35 @@ +CMP0008 +------- + +Libraries linked by full-path must have a valid library file name. + +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 +produces an error at build time because the dependency on the full +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 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 +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 +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 :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 new file mode 100644 index 0000000..27cfde0 --- /dev/null +++ b/Help/policy/CMP0009.rst @@ -0,0 +1,21 @@ +CMP0009 +------- + +FILE GLOB_RECURSE calls should not follow symlinks by default. + +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 :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 :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 new file mode 100644 index 0000000..cfae498 --- /dev/null +++ b/Help/policy/CMP0010.rst @@ -0,0 +1,20 @@ +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 +processing of CMake code. This policy determines whether a bad +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. + +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 :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 new file mode 100644 index 0000000..257415c --- /dev/null +++ b/Help/policy/CMP0011.rst @@ -0,0 +1,25 @@ +CMP0011 +------- + +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 :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 :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 new file mode 100644 index 0000000..17ec8d3 --- /dev/null +++ b/Help/policy/CMP0012.rst @@ -0,0 +1,28 @@ +CMP0012 +------- + +:command:`if` recognizes numbers and boolean constants. + +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 +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 +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 :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 new file mode 100644 index 0000000..dbd67a1 --- /dev/null +++ b/Help/policy/CMP0013.rst @@ -0,0 +1,21 @@ +CMP0013 +------- + +Duplicate binary directories are not allowed. + +CMake 2.6.3 and below silently permitted add_subdirectory() calls to +create the same binary directory multiple times. During build system +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 +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 :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 new file mode 100644 index 0000000..331dde5 --- /dev/null +++ b/Help/policy/CMP0014.rst @@ -0,0 +1,17 @@ +CMP0014 +------- + +Input directories must have ``CMakeLists.txt``. + +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 +: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 :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 new file mode 100644 index 0000000..90d5203 --- /dev/null +++ b/Help/policy/CMP0015.rst @@ -0,0 +1,19 @@ +CMP0015 +------- + + :command:`link_directories` treats paths relative to the source dir. + +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 +: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 :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 new file mode 100644 index 0000000..026d02a --- /dev/null +++ b/Help/policy/CMP0016.rst @@ -0,0 +1,16 @@ +CMP0016 +------- + +:command:`target_link_libraries` reports error if its only argument +is not a target. + +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 :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 new file mode 100644 index 0000000..ca4664e --- /dev/null +++ b/Help/policy/CMP0017.rst @@ -0,0 +1,21 @@ +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 :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 :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 :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 new file mode 100644 index 0000000..6248406 --- /dev/null +++ b/Help/policy/CMP0018.rst @@ -0,0 +1,35 @@ +CMP0018 +------- + +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`` +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 +other flags needed on certain platforms. CMake 2.8.9 and higher +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. + +The default for either approach produces identical compilation flags, +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 +: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 :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 :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 new file mode 100644 index 0000000..682dcdf --- /dev/null +++ b/Help/policy/CMP0019.rst @@ -0,0 +1,22 @@ +CMP0019 +------- + +Do not re-expand variables in include and link information. + +CMake 2.8.10 and lower re-evaluated values given to the +include_directories, link_directories, and link_libraries commands to +expand any leftover variable references at the end of the +configuration step. This was for strict compatibility with VERY early +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 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 :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 new file mode 100644 index 0000000..6d27684 --- /dev/null +++ b/Help/policy/CMP0020.rst @@ -0,0 +1,27 @@ +CMP0020 +------- + +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. +CMake 2.8.11 gained the ability to evaluate generator expressions +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 +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. + +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 :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 new file mode 100644 index 0000000..937b106 --- /dev/null +++ b/Help/policy/CMP0021.rst @@ -0,0 +1,21 @@ +CMP0021 +------- + +Fatal error on relative paths in :prop_tgt:`INCLUDE_DIRECTORIES` target +property. + +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 +: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 +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 :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 new file mode 100644 index 0000000..be60e37 --- /dev/null +++ b/Help/policy/CMP0022.rst @@ -0,0 +1,39 @@ +CMP0022 +------- + +: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 +: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 +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 :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 +: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 +: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 :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 new file mode 100644 index 0000000..3c72c81 --- /dev/null +++ b/Help/policy/CMP0023.rst @@ -0,0 +1,35 @@ +CMP0023 +------- + +Plain and keyword :command:`target_link_libraries` signatures cannot be mixed. + +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 +:command:`target_link_libraries` signature. For example, consider the code: + +:: + + target_link_libraries(mylib A) + target_link_libraries(mylib PRIVATE B) + +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 :command:`target_link_libraries` for a single +target. + +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 :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 new file mode 100644 index 0000000..6e24b04 --- /dev/null +++ b/Help/policy/CMP0024.rst @@ -0,0 +1,25 @@ +CMP0024 +------- + +Disallow include export result. + +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 :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 :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 :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 new file mode 100644 index 0000000..ba5e1e9 --- /dev/null +++ b/Help/policy/CMP0025.rst @@ -0,0 +1,29 @@ +CMP0025 +------- + +Compiler id for Apple Clang is now ``AppleClang``. + +CMake 3.0 and above recognize that Apple Clang is a different compiler +than upstream Clang and that they have different version numbers. +CMake now prefers to present this to projects by setting the +:variable:`CMAKE_<LANG>_COMPILER_ID` variable to ``AppleClang`` instead +of ``Clang``. However, existing projects may assume the compiler id for +Apple Clang is just ``Clang`` as it was in CMake versions prior to 3.0. +Therefore this policy determines for Apple Clang 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 ``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. +See documentation of the +:variable:`CMAKE_POLICY_WARNING_CMP0025 <CMAKE_POLICY_WARNING_CMP<NNNN>>` +variable to control the warning. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0026.rst b/Help/policy/CMP0026.rst new file mode 100644 index 0000000..e08fd54 --- /dev/null +++ b/Help/policy/CMP0026.rst @@ -0,0 +1,29 @@ +CMP0026 +------- + +Disallow use of the LOCATION property for build targets. + +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 :genex:`$<TARGET_FILE>` generator +expression can be used to determine the eventual :prop_tgt:`LOCATION` of a target +output. + +Code which reads the :prop_tgt:`LOCATION` target property can be ported to +use the :genex:`$<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 :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 :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 new file mode 100644 index 0000000..bf7b6a9 --- /dev/null +++ b/Help/policy/CMP0027.rst @@ -0,0 +1,27 @@ +CMP0027 +------- + +Conditionally linked imported targets with missing include directories. + +CMake 2.8.11 introduced introduced the concept of +: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 :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 :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 :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 new file mode 100644 index 0000000..ab38229 --- /dev/null +++ b/Help/policy/CMP0028.rst @@ -0,0 +1,25 @@ +CMP0028 +------- + +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 :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 +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. + +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 :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0029.rst b/Help/policy/CMP0029.rst new file mode 100644 index 0000000..aa10b97 --- /dev/null +++ b/Help/policy/CMP0029.rst @@ -0,0 +1,12 @@ +CMP0029 +------- + +The :command:`subdir_depends` command should not be called. + +The implementation of this command has been empty since December 2001 +but was kept in CMake for compatibility for a long time. + +.. |disallowed_version| replace:: 3.0 +.. include:: DISALLOWED_COMMAND.txt + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0030.rst b/Help/policy/CMP0030.rst new file mode 100644 index 0000000..81bbb84 --- /dev/null +++ b/Help/policy/CMP0030.rst @@ -0,0 +1,13 @@ +CMP0030 +------- + +The :command:`use_mangled_mesa` command should not be called. + +This command was created in September 2001 to support VTK before +modern CMake language and custom command capabilities. VTK has +not used it in years. + +.. |disallowed_version| replace:: 3.0 +.. include:: DISALLOWED_COMMAND.txt + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0031.rst b/Help/policy/CMP0031.rst new file mode 100644 index 0000000..8c3eef6 --- /dev/null +++ b/Help/policy/CMP0031.rst @@ -0,0 +1,15 @@ +CMP0031 +------- + +The :command:`load_command` command should not be called. + +This command was added in August 2002 to allow projects to add +arbitrary commands implemented in C or C++. However, it does +not work when the toolchain in use does not match the ABI of +the CMake process. It has been mostly superseded by the +:command:`macro` and :command:`function` commands. + +.. |disallowed_version| replace:: 3.0 +.. include:: DISALLOWED_COMMAND.txt + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0032.rst b/Help/policy/CMP0032.rst new file mode 100644 index 0000000..5c1fa4b --- /dev/null +++ b/Help/policy/CMP0032.rst @@ -0,0 +1,15 @@ +CMP0032 +------- + +The :command:`output_required_files` command should not be called. + +This command was added in June 2001 to expose the then-current CMake +implicit dependency scanner. CMake's real implicit dependency scanner +has evolved since then but is not exposed through this command. The +scanning capabilities of this command are very limited and this +functionality is better achieved through dedicated outside tools. + +.. |disallowed_version| replace:: 3.0 +.. include:: DISALLOWED_COMMAND.txt + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0033.rst b/Help/policy/CMP0033.rst new file mode 100644 index 0000000..4a6cc59 --- /dev/null +++ b/Help/policy/CMP0033.rst @@ -0,0 +1,16 @@ +CMP0033 +------- + +The :command:`export_library_dependencies` command should not be called. + +This command was added in January 2003 to export ``<tgt>_LIB_DEPENDS`` +internal CMake cache entries to a file for installation with a project. +This was used at the time to allow transitive link dependencies to +work for applications outside of the original build tree of a project. +The functionality has been superseded by the :command:`export` and +:command:`install(EXPORT)` commands. + +.. |disallowed_version| replace:: 3.0 +.. include:: DISALLOWED_COMMAND.txt + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0034.rst b/Help/policy/CMP0034.rst new file mode 100644 index 0000000..0f3934a --- /dev/null +++ b/Help/policy/CMP0034.rst @@ -0,0 +1,13 @@ +CMP0034 +------- + +The :command:`utility_source` command should not be called. + +This command was introduced in March 2001 to help build executables used to +generate other files. This approach has long been replaced by +:command:`add_executable` combined with :command:`add_custom_command`. + +.. |disallowed_version| replace:: 3.0 +.. include:: DISALLOWED_COMMAND.txt + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0035.rst b/Help/policy/CMP0035.rst new file mode 100644 index 0000000..58199a4 --- /dev/null +++ b/Help/policy/CMP0035.rst @@ -0,0 +1,12 @@ +CMP0035 +------- + +The :command:`variable_requires` command should not be called. + +This command was introduced in November 2001 to perform some conditional +logic. It has long been replaced by the :command:`if` command. + +.. |disallowed_version| replace:: 3.0 +.. include:: DISALLOWED_COMMAND.txt + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0036.rst b/Help/policy/CMP0036.rst new file mode 100644 index 0000000..4bcfc54 --- /dev/null +++ b/Help/policy/CMP0036.rst @@ -0,0 +1,14 @@ +CMP0036 +------- + +The :command:`build_name` command should not be called. + +This command was added in May 2001 to compute a name for the current +operating system and compiler combination. The command has long been +documented as discouraged and replaced by the :variable:`CMAKE_SYSTEM` +and :variable:`CMAKE_<LANG>_COMPILER` variables. + +.. |disallowed_version| replace:: 3.0 +.. include:: DISALLOWED_COMMAND.txt + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0037.rst b/Help/policy/CMP0037.rst new file mode 100644 index 0000000..9895fb0 --- /dev/null +++ b/Help/policy/CMP0037.rst @@ -0,0 +1,34 @@ +CMP0037 +------- + +Target names should not be reserved and should match a validity pattern. + +CMake 2.8.12 and lower allowed creating targets using :command:`add_library`, +:command:`add_executable` and :command:`add_custom_target` with unrestricted +choice for the target name. Newer cmake features such +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`` 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``, ``clean``, ``help``, and ``install``. + +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 +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 :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 new file mode 100644 index 0000000..7fb2209 --- /dev/null +++ b/Help/policy/CMP0038.rst @@ -0,0 +1,18 @@ +CMP0038 +------- + +Targets may not link directly to themselves. + +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 +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 :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 new file mode 100644 index 0000000..4b14e21 --- /dev/null +++ b/Help/policy/CMP0039.rst @@ -0,0 +1,19 @@ +CMP0039 +------- + +Utility targets may not have link dependencies. + +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 +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 :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 new file mode 100644 index 0000000..0afe589 --- /dev/null +++ b/Help/policy/CMP0040.rst @@ -0,0 +1,21 @@ +CMP0040 +------- + +The target in the ``TARGET`` signature of :command:`add_custom_command` +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` +if the target is unknown or was defined outside the current directory. + +The ``OLD`` behavior for this policy is to ignore custom commands +for unknown targets. The ``NEW`` behavior for this policy is to report +an error if the target referenced in :command:`add_custom_command` is +unknown or was defined outside the current directory. + +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 :command:`cmake_policy` command to set it to ``OLD`` or +``NEW`` explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0041.rst b/Help/policy/CMP0041.rst new file mode 100644 index 0000000..3b4df36 --- /dev/null +++ b/Help/policy/CMP0041.rst @@ -0,0 +1,27 @@ +CMP0041 +------- + +Error on relative include with generator expression. + +Diagnostics in CMake 2.8.12 and lower silently ignored an entry in the +:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of a target if it contained a generator +expression at any position. + +The path entries in that target property should not be relative. High-level +API should ensure that by adding either a source directory or a install +directory prefix, as appropriate. + +As an additional diagnostic, the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` generated +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 +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 :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 new file mode 100644 index 0000000..0877564 --- /dev/null +++ b/Help/policy/CMP0042.rst @@ -0,0 +1,21 @@ +CMP0042 +------- + +:prop_tgt:`MACOSX_RPATH` is enabled by default. + +CMake 2.8.12 and newer has support for using ``@rpath`` in a target's install +name. This was enabled by setting the target property +:prop_tgt:`MACOSX_RPATH`. The ``@rpath`` in an install name is a more +flexible and powerful mechanism than ``@executable_path`` or ``@loader_path`` +for locating shared libraries. + +CMake 3.0 and later prefer this property to be ON by default. Projects +wanting ``@rpath`` in a target's install name may remove any setting of +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 :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 new file mode 100644 index 0000000..05210ac --- /dev/null +++ b/Help/policy/CMP0043.rst @@ -0,0 +1,47 @@ +CMP0043 +------- + +Ignore COMPILE_DEFINITIONS_<Config> properties + +CMake 2.8.12 and lower allowed setting the +:prop_tgt:`COMPILE_DEFINITIONS_<CONFIG>` target property and +:prop_dir:`COMPILE_DEFINITIONS_<CONFIG>` directory property to apply +configuration-specific compile definitions. + +Since CMake 2.8.10, the :prop_tgt:`COMPILE_DEFINITIONS` property has supported +:manual:`generator expressions <cmake-generator-expressions(7)>` for setting +configuration-dependent content. The continued existence of the suffixed +variables is redundant, and causes a maintenance burden. Population of the +:prop_tgt:`COMPILE_DEFINITIONS_DEBUG <COMPILE_DEFINITIONS_<CONFIG>>` property +may be replaced with a population of :prop_tgt:`COMPILE_DEFINITIONS` directly +or via :command:`target_compile_definitions`: + +.. code-block:: cmake + + # Old Interfaces: + set_property(TARGET tgt APPEND PROPERTY + COMPILE_DEFINITIONS_DEBUG DEBUG_MODE + ) + set_property(DIRECTORY APPEND PROPERTY + COMPILE_DEFINITIONS_DEBUG DIR_DEBUG_MODE + ) + + # New Interfaces: + set_property(TARGET tgt APPEND PROPERTY + COMPILE_DEFINITIONS $<$<CONFIG:Debug>:DEBUG_MODE> + ) + target_compile_definitions(tgt PRIVATE $<$<CONFIG:Debug>:DEBUG_MODE>) + set_property(DIRECTORY APPEND PROPERTY + COMPILE_DEFINITIONS $<$<CONFIG:Debug>:DIR_DEBUG_MODE> + ) + +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 +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 :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 new file mode 100644 index 0000000..6a4d040 --- /dev/null +++ b/Help/policy/CMP0044.rst @@ -0,0 +1,21 @@ +CMP0044 +------- + +Case sensitive ``<LANG>_COMPILER_ID`` generator expressions + +CMake 2.8.12 introduced the ``<LANG>_COMPILER_ID`` +:manual:`generator expressions <cmake-generator-expressions(7)>` to allow +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 +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 :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 new file mode 100644 index 0000000..80e217b --- /dev/null +++ b/Help/policy/CMP0045.rst @@ -0,0 +1,19 @@ +CMP0045 +------- + +Error on non-existent target in get_target_property. + +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 +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 :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 new file mode 100644 index 0000000..bf78584 --- /dev/null +++ b/Help/policy/CMP0046.rst @@ -0,0 +1,19 @@ +CMP0046 +------- + +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 +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 :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 new file mode 100644 index 0000000..9588edd --- /dev/null +++ b/Help/policy/CMP0047.rst @@ -0,0 +1,30 @@ +CMP0047 +------- + +Use ``QCC`` compiler id for the qcc drivers on QNX. + +CMake 3.0 and above recognize that the QNX qcc compiler driver is +different from the GNU compiler. +CMake now prefers to present this to projects by setting the +:variable:`CMAKE_<LANG>_COMPILER_ID` variable to ``QCC`` instead +of ``GNU``. However, existing projects may assume the compiler id for +QNX qcc is just ``GNU`` as it was in CMake versions prior to 3.0. +Therefore this policy determines for QNX qcc 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 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. +See documentation of the +:variable:`CMAKE_POLICY_WARNING_CMP0047 <CMAKE_POLICY_WARNING_CMP<NNNN>>` +variable to control the warning. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0048.rst b/Help/policy/CMP0048.rst new file mode 100644 index 0000000..e63ec01 --- /dev/null +++ b/Help/policy/CMP0048.rst @@ -0,0 +1,24 @@ +CMP0048 +------- + +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 +to the empty string when no ``VERSION`` is given to :command:`project`. +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 +: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 :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 new file mode 100644 index 0000000..49b20be --- /dev/null +++ b/Help/policy/CMP0049.rst @@ -0,0 +1,25 @@ +CMP0049 +------- + +Do not expand variables in target source entries. + +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 +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 :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 new file mode 100644 index 0000000..27e7b1d --- /dev/null +++ b/Help/policy/CMP0050.rst @@ -0,0 +1,20 @@ +CMP0050 +------- + +Disallow add_custom_command SOURCE signatures. + +CMake 2.8.12 and lower allowed a signature for :command:`add_custom_command` +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 +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 :command:`cmake_policy` command to set it to ``OLD`` or +``NEW`` explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0051.rst b/Help/policy/CMP0051.rst new file mode 100644 index 0000000..3558909 --- /dev/null +++ b/Help/policy/CMP0051.rst @@ -0,0 +1,28 @@ +CMP0051 +------- + +.. versionadded:: 3.1 + +List :genex:`TARGET_OBJECTS` in SOURCES target property. + +CMake 3.0 and lower did not include the ``TARGET_OBJECTS`` +:manual:`generator expression <cmake-generator-expressions(7)>` when +returning the :prop_tgt:`SOURCES` target property. + +Configure-time CMake code is not able to handle generator expressions. If +using the :prop_tgt:`SOURCES` target property at configure time, it may be +necessary to first remove generator expressions using the +:command:`string(GENEX_STRIP)` command. Generate-time CMake code such as +:command:`file(GENERATE)` can handle the content without stripping. + +The ``OLD`` behavior for this policy is to omit ``TARGET_OBJECTS`` +expressions from the :prop_tgt:`SOURCES` target property. The ``NEW`` +behavior for this policy is to include ``TARGET_OBJECTS`` expressions +in the output. + +This policy was introduced in CMake version 3.1. +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/CMP0052.rst b/Help/policy/CMP0052.rst new file mode 100644 index 0000000..c75f9ab --- /dev/null +++ b/Help/policy/CMP0052.rst @@ -0,0 +1,29 @@ +CMP0052 +------- + +.. versionadded:: 3.1 + +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 +installed and exported targets, if the directory was also a subdirectory of +the installation prefix. This makes the installation depend on the +existence of the source dir or binary dir, and the installation will be +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 +:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` with the source or binary +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. +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/CMP0053.rst b/Help/policy/CMP0053.rst new file mode 100644 index 0000000..9b18b2d --- /dev/null +++ b/Help/policy/CMP0053.rst @@ -0,0 +1,52 @@ +CMP0053 +------- + +.. versionadded:: 3.1 + +Simplify variable reference and escape sequence evaluation. + +CMake 3.1 introduced a much faster implementation of evaluation of the +:ref:`Variable References` and :ref:`Escape Sequences` documented in the +:manual:`cmake-language(7)` manual. While the behavior is identical +to the legacy implementation in most cases, some corner cases were +cleaned up to simplify the behavior. Specifically: + +* Expansion of ``@VAR@`` reference syntax defined by the + :command:`configure_file` and :command:`string(CONFIGURE)` + commands is no longer performed in other contexts. + +* 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. + + .. code-block:: cmake + + set(varname "otherwise & disallowed $ characters") + message("${${varname}}") + +* The setting of policy :policy:`CMP0010` is not considered, + so improper variable reference syntax is always an error. + +* More characters are allowed to be escaped in variable names. + Previously, only ``()#" \@^`` were valid characters to + escape. Now any non-alphanumeric, non-semicolon, non-NUL + character may be escaped following the ``escape_identity`` + production in the :ref:`Escape Sequences` section of the + :manual:`cmake-language(7)` manual. + +The ``OLD`` behavior for this policy is to honor the legacy behavior for +variable references and escape sequences. The ``NEW`` behavior is to +use the simpler variable expansion and escape sequence evaluation rules. + +This policy was introduced in CMake version 3.1. +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/CMP0054.rst b/Help/policy/CMP0054.rst new file mode 100644 index 0000000..c7ae019 --- /dev/null +++ b/Help/policy/CMP0054.rst @@ -0,0 +1,54 @@ +CMP0054 +------- + +.. versionadded:: 3.1 + +Only interpret :command:`if` arguments as variables or keywords when unquoted. + +CMake 3.1 and above no longer implicitly dereference variables or +interpret keywords in an :command:`if` command argument when +it is a :ref:`Quoted Argument` or a :ref:`Bracket Argument`. + +The ``OLD`` behavior for this policy is to dereference variables and +interpret keywords even if they are quoted or bracketed. +The ``NEW`` behavior is to not dereference variables or interpret keywords +that have been quoted or bracketed. + +Given the following partial example: + +:: + + set(A E) + set(E "") + + if("${A}" STREQUAL "") + message("Result is TRUE before CMake 3.1 or when CMP0054 is OLD") + else() + message("Result is FALSE in CMake 3.1 and above if CMP0054 is NEW") + endif() + +After explicit expansion of variables this gives: + +:: + + if("E" STREQUAL "") + +With the policy set to ``OLD`` implicit expansion reduces this semantically to: + +:: + + if("" STREQUAL "") + +With the policy set to ``NEW`` the quoted arguments will not be +further dereferenced: + +:: + + if("E" STREQUAL "") + +This policy was introduced in CMake version 3.1. +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/CMP0055.rst b/Help/policy/CMP0055.rst new file mode 100644 index 0000000..47cac8e --- /dev/null +++ b/Help/policy/CMP0055.rst @@ -0,0 +1,21 @@ +CMP0055 +------- + +.. versionadded:: 3.2 + +Strict checking for the :command:`break` command. + +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 +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 :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 new file mode 100644 index 0000000..628a6a1 --- /dev/null +++ b/Help/policy/CMP0056.rst @@ -0,0 +1,36 @@ +CMP0056 +------- + +.. versionadded:: 3.2 + +Honor link flags in :command:`try_compile` source-file signature. + +The :command:`try_compile` command source-file signature generates a +``CMakeLists.txt`` file to build the source file into an executable. +In order to compile the source the same way as it might be compiled +by the calling project, the generated project sets the value of the +:variable:`CMAKE_<LANG>_FLAGS` variable to that in the calling project. +The value of the :variable:`CMAKE_EXE_LINKER_FLAGS` variable may be +needed in some cases too, but CMake 3.1 and lower did not set it in +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 +:variable:`CMAKE_EXE_LINKER_FLAGS` variable in the generated test +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. + +If the project code does not set the policy explicitly, users may +set it on the command line by defining the +:variable:`CMAKE_POLICY_DEFAULT_CMP0056 <CMAKE_POLICY_DEFAULT_CMP<NNNN>>` +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 +:variable:`CMAKE_POLICY_WARNING_CMP0056 <CMAKE_POLICY_WARNING_CMP<NNNN>>` +variable to control the warning. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0057.rst b/Help/policy/CMP0057.rst new file mode 100644 index 0000000..76aebfb --- /dev/null +++ b/Help/policy/CMP0057.rst @@ -0,0 +1,18 @@ +CMP0057 +------- + +.. versionadded:: 3.3 + +Support new :command:`if` IN_LIST operator. + +CMake 3.3 adds support for the new IN_LIST operator. + +The ``OLD`` behavior for this policy is to ignore the IN_LIST operator. +The ``NEW`` behavior is to interpret the IN_LIST operator. + +This policy was introduced in CMake version 3.3. +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/CMP0058.rst b/Help/policy/CMP0058.rst new file mode 100644 index 0000000..06cc74b --- /dev/null +++ b/Help/policy/CMP0058.rst @@ -0,0 +1,112 @@ +CMP0058 +------- + +.. versionadded:: 3.3 + +Ninja requires custom command byproducts to be explicit. + +When an intermediate file generated during the build is consumed +by an expensive operation or a large tree of dependents, one may +reduce the work needed for an incremental rebuild by updating the +file timestamp only when its content changes. With this approach +the generation rule must have a separate output file that is always +updated with a new timestamp that is newer than any dependencies of +the rule so that the build tool re-runs the rule only when the input +changes. We refer to the separate output file as a rule's *witness* +and the generated file as a rule's *byproduct*. + +Byproducts may not be listed as outputs because their timestamps are +allowed to be older than the inputs. No build tools (like ``make``) +that existed when CMake was designed have a way to express byproducts. +Therefore CMake versions prior to 3.2 had no way to specify them. +Projects typically left byproducts undeclared in the rules that +generate them. For example: + +.. code-block:: cmake + + add_custom_command( + OUTPUT witness.txt + COMMAND ${CMAKE_COMMAND} -E copy_if_different + ${CMAKE_CURRENT_SOURCE_DIR}/input.txt + byproduct.txt # timestamp may not change + COMMAND ${CMAKE_COMMAND} -E touch witness.txt + DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/input.txt + ) + add_custom_target(Provider DEPENDS witness.txt) + add_custom_command( + OUTPUT generated.c + COMMAND expensive-task -i byproduct.txt -o generated.c + DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/byproduct.txt + ) + add_library(Consumer generated.c) + add_dependencies(Consumer Provider) + +This works well for all generators except :generator:`Ninja`. +The Ninja build tool sees a rule listing ``byproduct.txt`` +as a dependency and no rule listing it as an output. Ninja then +complains that there is no way to satisfy the dependency and +stops building even though there are order-only dependencies +that ensure ``byproduct.txt`` will exist before its consumers +need it. See discussion of this problem in `Ninja Issue 760`_ +for further details on why Ninja works this way. + +.. _`Ninja Issue 760`: https://github.com/martine/ninja/issues/760 + +Instead of leaving byproducts undeclared in the rules that generate +them, Ninja expects byproducts to be listed along with other outputs. +Such rules may be marked with a ``restat`` option that tells Ninja +to check the timestamps of outputs after the rules run. This +prevents byproducts whose timestamps do not change from causing +their dependents to re-build unnecessarily. + +Since the above approach does not tell CMake what custom command +generates ``byproduct.txt``, the Ninja generator does not have +enough information to add the byproduct as an output of any rule. +CMake 2.8.12 and above work around this problem and allow projects +using the above approach to build by generating ``phony`` build +rules to tell Ninja to tolerate such missing files. However, this +workaround prevents Ninja from diagnosing a dependency that is +really missing. It also works poorly in in-source builds where +every custom command dependency, even on source files, needs to +be treated this way because CMake does not have enough information +to know which files are generated as byproducts of custom commands. + +CMake 3.2 introduced the ``BYPRODUCTS`` option to the +:command:`add_custom_command` and :command:`add_custom_target` +commands. This option allows byproducts to be specified explicitly: + +.. code-block:: cmake + + add_custom_command( + OUTPUT witness.txt + BYPRODUCTS byproduct.txt # explicit byproduct specification + COMMAND ${CMAKE_COMMAND} -E copy_if_different + ${CMAKE_CURRENT_SOURCE_DIR}/input.txt + byproduct.txt # timestamp may not change + ... + +The ``BYPRODUCTS`` option is used by the :generator:`Ninja` generator +to list byproducts among the outputs of the custom commands that +generate them, and is ignored by other generators. + +CMake 3.3 and above prefer to require projects to specify custom +command byproducts explicitly so that it can avoid using the +``phony`` rule workaround altogether. Policy ``CMP0058`` was +introduced to provide compatibility with existing projects that +still need the workaround. + +This policy has no effect on generators other than :generator:`Ninja`. +The ``OLD`` behavior for this policy is to generate Ninja ``phony`` +rules for unknown dependencies in the build tree. The ``NEW`` +behavior for this policy is to not generate these and instead +require projects to specify custom command ``BYPRODUCTS`` explicitly. + +This policy was introduced in CMake version 3.3. +CMake version |release| warns when it sees unknown dependencies in +out-of-source build trees if the policy is not set and then uses +``OLD`` behavior. Use the :command:`cmake_policy` command to set +the policy to ``OLD`` or ``NEW`` explicitly. The policy setting +must be in scope at the end of the top-level ``CMakeLists.txt`` +file of the project and has global effect. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0059.rst b/Help/policy/CMP0059.rst new file mode 100644 index 0000000..6317d05 --- /dev/null +++ b/Help/policy/CMP0059.rst @@ -0,0 +1,21 @@ +CMP0059 +------- + +.. versionadded:: 3.3 + +Do not treat ``DEFINITIONS`` as a built-in directory property. + +CMake 3.3 and above no longer make a list of definitions available through +the :prop_dir:`DEFINITIONS` directory property. The +:prop_dir:`COMPILE_DEFINITIONS` directory property may be used instead. + +The ``OLD`` behavior for this policy is to provide the list of flags given +so far to the :command:`add_definitions` command. The ``NEW`` behavior is +to behave as a normal user-defined directory property. + +This policy was introduced in CMake version 3.3. +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/CMP0060.rst b/Help/policy/CMP0060.rst new file mode 100644 index 0000000..09257d1 --- /dev/null +++ b/Help/policy/CMP0060.rst @@ -0,0 +1,67 @@ +CMP0060 +------- + +.. versionadded:: 3.3 + +Link libraries by full path even in implicit directories. + +Policy :policy:`CMP0003` was introduced with the intention of always +linking library files by full path when a full path is given to the +:command:`target_link_libraries` command. However, on some platforms +(e.g. HP-UX) the compiler front-end adds alternative library search paths +for the current architecture (e.g. ``/usr/lib/<arch>`` has alternatives +to libraries in ``/usr/lib`` for the current architecture). +On such platforms the :command:`find_library` may find a library such as +``/usr/lib/libfoo.so`` that does not belong to the current architecture. + +Prior to policy :policy:`CMP0003` projects would still build in such +cases because the incorrect library path would be converted to ``-lfoo`` +on the link line and the linker would find the proper library in the +arch-specific search path provided by the compiler front-end implicitly. +At the time we chose to remain compatible with such projects by always +converting library files found in implicit link directories to ``-lfoo`` +flags to ask the linker to search for them. This approach allowed existing +projects to continue to build while still linking to libraries outside +implicit link directories via full path (such as those in the build tree). + +CMake does allow projects to override this behavior by using an +:ref:`IMPORTED library target <Imported Targets>` with its +:prop_tgt:`IMPORTED_LOCATION` property set to the desired full path to +a library file. In fact, many :ref:`Find Modules` are learning to provide +:ref:`Imported Targets` instead of just the traditional ``Foo_LIBRARIES`` +variable listing library files. However, this makes the link line +generated for a library found by a Find Module depend on whether it +is linked through an imported target or not, which is inconsistent. +Furthermore, this behavior has been a source of confusion because the +generated link line for a library file depends on its location. It is +also problematic for projects trying to link statically because flags +like ``-Wl,-Bstatic -lfoo -Wl,-Bdynamic`` may be used to help the linker +select ``libfoo.a`` instead of ``libfoo.so`` but then leak dynamic linking +to following libraries. (See the :prop_tgt:`LINK_SEARCH_END_STATIC` +target property for a solution typically used for that problem.) + +When the special case for libraries in implicit link directories was first +introduced the list of implicit link directories was simply hard-coded +(e.g. ``/lib``, ``/usr/lib``, and a few others). Since that time, CMake +has learned to detect the implicit link directories used by the compiler +front-end. If necessary, the :command:`find_library` command could be +taught to use this information to help find libraries of the proper +architecture. + +For these reasons, CMake 3.3 and above prefer to drop the special case +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 +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 +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 +:variable:`CMAKE_POLICY_WARNING_CMP0060 <CMAKE_POLICY_WARNING_CMP<NNNN>>` +variable to control the warning. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0061.rst b/Help/policy/CMP0061.rst new file mode 100644 index 0000000..aca551d --- /dev/null +++ b/Help/policy/CMP0061.rst @@ -0,0 +1,28 @@ +CMP0061 +------- + +.. versionadded:: 3.3 + +CTest does not by default tell ``make`` to ignore errors (``-i``). + +The :command:`ctest_build` and :command:`build_command` commands no +longer generate build commands for :ref:`Makefile Generators` with +the ``-i`` option. Previously this was done to help build as much +of tested projects as possible. However, this behavior is not +consistent with other generators and also causes the return code +of the ``make`` tool to be meaningless. + +Of course users may still add this option manually by setting +:variable:`CTEST_BUILD_COMMAND` or the ``MAKECOMMAND`` cache entry. +See the :ref:`CTest Build Step` ``MakeCommand`` setting documentation +for their effects. + +The ``OLD`` behavior for this policy is to add ``-i`` to ``make`` +calls in CTest. The ``NEW`` behavior for this policy is to not +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. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0062.rst b/Help/policy/CMP0062.rst new file mode 100644 index 0000000..01e93f0 --- /dev/null +++ b/Help/policy/CMP0062.rst @@ -0,0 +1,31 @@ +CMP0062 +------- + +.. versionadded:: 3.3 + +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 +directory. It is not suitable for installation because it contains absolute +paths to buildsystem locations, and is particular to a single build +configuration. + +The :command:`install(EXPORT)` generates and installs files which contain +:ref:`Imported Targets`. These files are generated with relative paths +(unless the user specifies absolute paths), and are designed for +multi-configuration use. See :ref:`Creating Packages` for more. + +CMake 3.3 no longer allows the use of the :command:`install(FILES)` command +with the result of the :command:`export()` command. + +The ``OLD`` behavior for this policy is to allow installing the result of +an :command:`export()` command. The ``NEW`` behavior for this policy is +not to allow installing the result of an :command:`export()` command. + +This policy was introduced in CMake version 3.3. 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/CMP0063.rst b/Help/policy/CMP0063.rst new file mode 100644 index 0000000..fec3ad8 --- /dev/null +++ b/Help/policy/CMP0063.rst @@ -0,0 +1,30 @@ +CMP0063 +------- + +.. versionadded:: 3.3 + +Honor visibility properties for all target types. + +The :prop_tgt:`<LANG>_VISIBILITY_PRESET` and +:prop_tgt:`VISIBILITY_INLINES_HIDDEN` target properties affect visibility +of symbols during dynamic linking. When first introduced these properties +affected compilation of sources only in shared libraries, module libraries, +and executables with the :prop_tgt:`ENABLE_EXPORTS` property set. This +was sufficient for the basic use cases of shared libraries and executables +with plugins. However, some sources may be compiled as part of static +libraries or object libraries and then linked into a shared library later. +CMake 3.3 and above prefer to honor these properties for sources compiled +in all target types. This policy preserves compatibility for projects +expecting the properties to work only for some target types. + +The ``OLD`` behavior for this policy is to ignore the visibility properties +for static libraries, object libraries, and executables without exports. +The ``NEW`` behavior for this policy is to honor the visibility properties +for all target types. + +This policy was introduced in CMake version 3.3. 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/CMP0064.rst b/Help/policy/CMP0064.rst new file mode 100644 index 0000000..0c20c13 --- /dev/null +++ b/Help/policy/CMP0064.rst @@ -0,0 +1,19 @@ +CMP0064 +------- + +.. versionadded:: 3.4 + +Recognize ``TEST`` as a operator for the :command:`if` command. + +The ``TEST`` operator was added to the :command:`if` command to determine if a +given test name was created by the :command:`add_test` command. + +The ``OLD`` behavior for this policy is to ignore the ``TEST`` operator. +The ``NEW`` behavior is to interpret the ``TEST`` operator. + +This policy was introduced in CMake version 3.4. 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/CMP0065.rst b/Help/policy/CMP0065.rst new file mode 100644 index 0000000..8968b91 --- /dev/null +++ b/Help/policy/CMP0065.rst @@ -0,0 +1,29 @@ +CMP0065 +------- + +.. versionadded:: 3.4 + +Do not add flags to export symbols from executables without +the :prop_tgt:`ENABLE_EXPORTS` target property. + +CMake 3.3 and below, for historical reasons, always linked executables +on some platforms with flags like ``-rdynamic`` to export symbols from +the executables for use by any plugins they may load via ``dlopen``. +CMake 3.4 and above prefer to do this only for executables that are +explicitly marked with the :prop_tgt:`ENABLE_EXPORTS` target property. + +The ``OLD`` behavior of this policy is to always use the additional link +flags when linking executables regardless of the value of the +:prop_tgt:`ENABLE_EXPORTS` target property. + +The ``NEW`` behavior of this policy is to only use the additional link +flags when linking executables if the :prop_tgt:`ENABLE_EXPORTS` target +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 +:variable:`CMAKE_POLICY_WARNING_CMP0065 <CMAKE_POLICY_WARNING_CMP<NNNN>>` +variable to control the warning. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0066.rst b/Help/policy/CMP0066.rst new file mode 100644 index 0000000..b08430f --- /dev/null +++ b/Help/policy/CMP0066.rst @@ -0,0 +1,29 @@ +CMP0066 +------- + +.. versionadded:: 3.7 + +Honor per-config flags in :command:`try_compile` source-file signature. + +The source file signature of the :command:`try_compile` command uses the value +of the :variable:`CMAKE_<LANG>_FLAGS` variable in the test project so that the +test compilation works as it would in the main project. However, CMake 3.6 and +below do not also honor config-specific compiler flags such as those in the +:variable:`CMAKE_<LANG>_FLAGS_DEBUG` variable. CMake 3.7 and above prefer to +honor config-specific compiler flags too. This policy provides compatibility +for projects that do not expect config-specific compiler flags to be used. + +The ``OLD`` behavior of this policy is to ignore config-specific flag +variables like :variable:`CMAKE_<LANG>_FLAGS_DEBUG` and only use CMake's +built-in defaults for the current compiler and platform. + +The ``NEW`` behavior of this policy is to honor config-specific flag +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 +:variable:`CMAKE_POLICY_WARNING_CMP0066 <CMAKE_POLICY_WARNING_CMP<NNNN>>` +variable to control the warning. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0067.rst b/Help/policy/CMP0067.rst new file mode 100644 index 0000000..8358bb2 --- /dev/null +++ b/Help/policy/CMP0067.rst @@ -0,0 +1,39 @@ +CMP0067 +------- + +.. versionadded:: 3.8 + +Honor language standard in :command:`try_compile` source-file signature. + +The :command:`try_compile` source file signature is intended to allow +callers to check whether they will be able to compile a given source file +with the current toolchain. In order to match compiler behavior, any +language standard mode should match. However, CMake 3.7 and below did not +do this. CMake 3.8 and above prefer to honor the language standard settings +for ``C``, ``CXX`` (C++), and ``CUDA`` using the values of the variables: + +* :variable:`CMAKE_C_STANDARD` +* :variable:`CMAKE_C_STANDARD_REQUIRED` +* :variable:`CMAKE_C_EXTENSIONS` +* :variable:`CMAKE_CXX_STANDARD` +* :variable:`CMAKE_CXX_STANDARD_REQUIRED` +* :variable:`CMAKE_CXX_EXTENSIONS` +* :variable:`CMAKE_CUDA_STANDARD` +* :variable:`CMAKE_CUDA_STANDARD_REQUIRED` +* :variable:`CMAKE_CUDA_EXTENSIONS` + +This policy provides compatibility for projects that do not expect +the language standard settings to be used automatically. + +The ``OLD`` behavior of this policy is to ignore language standard +setting variables when generating the ``try_compile`` test project. +The ``NEW`` behavior of this policy is to honor language standard +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 +:variable:`CMAKE_POLICY_WARNING_CMP0067 <CMAKE_POLICY_WARNING_CMP<NNNN>>` +variable to control the warning. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0068.rst b/Help/policy/CMP0068.rst new file mode 100644 index 0000000..5d2a4b1 --- /dev/null +++ b/Help/policy/CMP0068.rst @@ -0,0 +1,37 @@ +CMP0068 +------- + +.. versionadded:: 3.9 + +``RPATH`` settings on macOS do not affect ``install_name``. + +CMake 3.9 and newer remove any effect the following settings may have on the +``install_name`` of a target on macOS: + +* :prop_tgt:`BUILD_WITH_INSTALL_RPATH` target property +* :prop_tgt:`SKIP_BUILD_RPATH` target property +* :variable:`CMAKE_SKIP_RPATH` variable +* :variable:`CMAKE_SKIP_INSTALL_RPATH` variable + +Previously, setting :prop_tgt:`BUILD_WITH_INSTALL_RPATH` had the effect of +setting both the ``install_name`` of a target to :prop_tgt:`INSTALL_NAME_DIR` +and the ``RPATH`` to :prop_tgt:`INSTALL_RPATH`. In CMake 3.9, it only affects +setting of ``RPATH``. However, if one wants :prop_tgt:`INSTALL_NAME_DIR` to +apply to the target in the build tree, one may set +:prop_tgt:`BUILD_WITH_INSTALL_NAME_DIR`. + +If :prop_tgt:`SKIP_BUILD_RPATH`, :variable:`CMAKE_SKIP_RPATH` or +:variable:`CMAKE_SKIP_INSTALL_RPATH` were used to strip the directory portion +of the ``install_name`` of a target, one may set ``INSTALL_NAME_DIR=""`` +instead. + +The ``OLD`` behavior of this policy is to use the ``RPATH`` settings for +``install_name`` on macOS. The ``NEW`` behavior of this policy is to ignore +the ``RPATH`` settings for ``install_name`` on macOS. + +This policy was introduced in CMake version 3.9. 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/CMP0069.rst b/Help/policy/CMP0069.rst new file mode 100644 index 0000000..eafac45 --- /dev/null +++ b/Help/policy/CMP0069.rst @@ -0,0 +1,94 @@ +CMP0069 +------- + +.. versionadded:: 3.9 + +:prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` is enforced when enabled. + +CMake 3.9 and newer prefer to add IPO flags whenever the +:prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property is enabled and +produce an error if flags are not known to CMake for the current compiler. +Since a given compiler may not support IPO flags in all environments in which +it is used, it is now the project's responsibility to use the +:module:`CheckIPOSupported` module to check for support before enabling the +:prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property. This approach +allows a project to conditionally activate IPO when supported. It also +allows an end user to set the :variable:`CMAKE_INTERPROCEDURAL_OPTIMIZATION` +variable in an environment known to support IPO even if the project does +not enable the property. + +Since CMake 3.8 and lower only honored :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` +for the Intel compiler on Linux, some projects may unconditionally enable the +target property. Policy ``CMP0069`` provides compatibility with such projects. + +This policy takes effect whenever the IPO property is enabled. The ``OLD`` +behavior for this policy is to add IPO flags only for Intel compiler on Linux. +The ``NEW`` behavior for this policy is to add IPO flags for the current +compiler or produce an error if CMake does not know the flags. + +This policy was introduced in CMake version 3.9. 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 + +Examples +^^^^^^^^ + +Behave like CMake 3.8 and do not apply any IPO flags except for Intel compiler +on Linux: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.8) + project(foo) + + # ... + + set_property(TARGET ... PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE) + +Use the :module:`CheckIPOSupported` module to detect whether IPO is +supported by the current compiler, environment, and CMake version. +Produce a fatal error if support is not available: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.9) # CMP0069 NEW + project(foo) + + include(CheckIPOSupported) + check_ipo_supported() + + # ... + + set_property(TARGET ... PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE) + +Apply IPO flags only if compiler supports it: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.9) # CMP0069 NEW + project(foo) + + include(CheckIPOSupported) + + # ... + + check_ipo_supported(RESULT result) + if(result) + set_property(TARGET ... PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE) + endif() + +Apply IPO flags without any checks. This may lead to build errors if IPO +is not supported by the compiler in the current environment. Produce an +error if CMake does not know IPO flags for the current compiler: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.9) # CMP0069 NEW + project(foo) + + # ... + + set_property(TARGET ... PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE) diff --git a/Help/policy/CMP0070.rst b/Help/policy/CMP0070.rst new file mode 100644 index 0000000..c880d1f --- /dev/null +++ b/Help/policy/CMP0070.rst @@ -0,0 +1,27 @@ +CMP0070 +------- + +.. versionadded:: 3.10 + +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 0000000..700d3b0 --- /dev/null +++ b/Help/policy/CMP0071.rst @@ -0,0 +1,44 @@ +CMP0071 +------- + +.. versionadded:: 3.10 + +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 0000000..1dcdfef --- /dev/null +++ b/Help/policy/CMP0072.rst @@ -0,0 +1,28 @@ +CMP0072 +------- + +.. versionadded:: 3.11 + +: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 0000000..8f0345c --- /dev/null +++ b/Help/policy/CMP0073.rst @@ -0,0 +1,27 @@ +CMP0073 +------- + +.. versionadded:: 3.12 + +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 0000000..863bbb2 --- /dev/null +++ b/Help/policy/CMP0074.rst @@ -0,0 +1,25 @@ +CMP0074 +------- + +.. versionadded:: 3.12 + +: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 0000000..4213782 --- /dev/null +++ b/Help/policy/CMP0075.rst @@ -0,0 +1,28 @@ +CMP0075 +------- + +.. versionadded:: 3.12 + +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 0000000..edca742 --- /dev/null +++ b/Help/policy/CMP0076.rst @@ -0,0 +1,28 @@ +CMP0076 +------- + +.. versionadded:: 3.13 + +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 0000000..174cde9 --- /dev/null +++ b/Help/policy/CMP0077.rst @@ -0,0 +1,54 @@ +CMP0077 +------- + +.. versionadded:: 3.13 + +: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 0000000..89fdb0b --- /dev/null +++ b/Help/policy/CMP0078.rst @@ -0,0 +1,26 @@ +CMP0078 +------- + +.. versionadded:: 3.13 + +: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 0000000..01aa08d --- /dev/null +++ b/Help/policy/CMP0079.rst @@ -0,0 +1,42 @@ +CMP0079 +------- + +.. versionadded:: 3.13 + +: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 0000000..789efea --- /dev/null +++ b/Help/policy/CMP0080.rst @@ -0,0 +1,27 @@ +CMP0080 +------- + +.. versionadded:: 3.13 + +: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 0000000..d1573dd --- /dev/null +++ b/Help/policy/CMP0081.rst @@ -0,0 +1,24 @@ +CMP0081 +------- + +.. versionadded:: 3.13 + +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 0000000..25c9580 --- /dev/null +++ b/Help/policy/CMP0082.rst @@ -0,0 +1,28 @@ +CMP0082 +------- + +.. versionadded:: 3.14 + +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 0000000..7518ee3 --- /dev/null +++ b/Help/policy/CMP0083.rst @@ -0,0 +1,71 @@ +CMP0083 +------- + +.. versionadded:: 3.14 + +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 0000000..9547701 --- /dev/null +++ b/Help/policy/CMP0084.rst @@ -0,0 +1,28 @@ +CMP0084 +------- + +.. versionadded:: 3.14 + +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 0000000..d90c72f --- /dev/null +++ b/Help/policy/CMP0085.rst @@ -0,0 +1,23 @@ +CMP0085 +------- + +.. versionadded:: 3.14 + +``$<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 0000000..725b502 --- /dev/null +++ b/Help/policy/CMP0086.rst @@ -0,0 +1,22 @@ +CMP0086 +------- + +.. versionadded:: 3.14 + +: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 0000000..4a65506 --- /dev/null +++ b/Help/policy/CMP0087.rst @@ -0,0 +1,31 @@ +CMP0087 +------- + +.. versionadded:: 3.14 + +: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 0000000..1840a58 --- /dev/null +++ b/Help/policy/CMP0088.rst @@ -0,0 +1,31 @@ +CMP0088 +------- + +.. versionadded:: 3.14 + +: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 0000000..e3fc77a --- /dev/null +++ b/Help/policy/CMP0089.rst @@ -0,0 +1,32 @@ +CMP0089 +------- + +.. versionadded:: 3.15 + +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 0000000..58dd999 --- /dev/null +++ b/Help/policy/CMP0090.rst @@ -0,0 +1,29 @@ +CMP0090 +------- + +.. versionadded:: 3.15 + +: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 0000000..ffc0ade --- /dev/null +++ b/Help/policy/CMP0091.rst @@ -0,0 +1,51 @@ +CMP0091 +------- + +.. versionadded:: 3.15 + +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 0000000..2f39830 --- /dev/null +++ b/Help/policy/CMP0092.rst @@ -0,0 +1,40 @@ +CMP0092 +------- + +.. versionadded:: 3.15 + +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 language ``<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 0000000..4a9955f --- /dev/null +++ b/Help/policy/CMP0093.rst @@ -0,0 +1,26 @@ +CMP0093 +------- + +.. versionadded:: 3.15 + +: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 0000000..1b57658 --- /dev/null +++ b/Help/policy/CMP0094.rst @@ -0,0 +1,24 @@ +CMP0094 +------- + +.. versionadded:: 3.15 + +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 0000000..ebdbab6 --- /dev/null +++ b/Help/policy/CMP0095.rst @@ -0,0 +1,32 @@ +CMP0095 +------- + +.. versionadded:: 3.16 + +``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 0000000..8fd6f72 --- /dev/null +++ b/Help/policy/CMP0096.rst @@ -0,0 +1,27 @@ +CMP0096 +------- + +.. versionadded:: 3.16 + +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 0000000..2240874 --- /dev/null +++ b/Help/policy/CMP0097.rst @@ -0,0 +1,25 @@ +CMP0097 +------- + +.. versionadded:: 3.16 + +: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/CMP0098.rst b/Help/policy/CMP0098.rst new file mode 100644 index 0000000..e793380 --- /dev/null +++ b/Help/policy/CMP0098.rst @@ -0,0 +1,32 @@ +CMP0098 +------- + +.. versionadded:: 3.17 + +:module:`FindFLEX` runs ``flex`` in directory +:variable:`CMAKE_CURRENT_BINARY_DIR` when executing. + +The module provides a ``FLEX_TARGET`` macro which generates FLEX output. +In CMake 3.16 and below the macro would generate a custom command that runs +``flex`` in the current source directory. CMake 3.17 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 relative to the +build tree rather than the source tree, unless the generated file is +provided as absolute path. + +This policy provides compatibility for projects that have not been updated +to expect the new behavior. + +The ``OLD`` behavior for this policy is for ``FLEX_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`` relative to +which implicit files are generated unless provided as absolute path. + +This policy was introduced in CMake version 3.17. 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/CMP0099.rst b/Help/policy/CMP0099.rst new file mode 100644 index 0000000..0c64949 --- /dev/null +++ b/Help/policy/CMP0099.rst @@ -0,0 +1,26 @@ +CMP0099 +------- + +.. versionadded:: 3.17 + +Target link properties :prop_tgt:`INTERFACE_LINK_OPTIONS`, +:prop_tgt:`INTERFACE_LINK_DIRECTORIES` and :prop_tgt:`INTERFACE_LINK_DEPENDS` +are now transitive over private dependencies of static libraries. + +In CMake 3.16 and below the interface link properties attached to libraries +are not propagated for private dependencies of static libraries. +Only the libraries themselves are propagated to link the dependent binary. +CMake 3.17 and later prefer to propagate all interface link properties. +This policy provides compatibility for projects that have not been updated +to expect the new behavior. + +The ``OLD`` behavior for this policy is to not propagate interface link +properties. The ``NEW`` behavior of this policy is to propagate interface link +properties. + +This policy was introduced in CMake version 3.17. 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/CMP0100.rst b/Help/policy/CMP0100.rst new file mode 100644 index 0000000..730fa82 --- /dev/null +++ b/Help/policy/CMP0100.rst @@ -0,0 +1,42 @@ +CMP0100 +------- + +.. versionadded:: 3.17 + +Let :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` process +header files that end with a ``.hh`` extension. + +Since version 3.17, CMake processes header files that end with a +``.hh`` extension in :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`. +In earlier CMake versions, these header files were ignored by +:prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`. + +This policy affects how header files that end with a ``.hh`` extension +get treated in :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`. + +The ``OLD`` behavior for this policy is to ignore ``.hh`` header files +in :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`. + +The ``NEW`` behavior for this policy is to process ``.hh`` header files +in :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` just like other header files. + +.. note:: + + To silence the ``CMP0100`` 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`. + + .. code-block:: cmake + + # Source skip example: + set_property(SOURCE /path/to/file1.hh PROPERTY SKIP_AUTOMOC ON) + set_property(SOURCE /path/to/file2.hh PROPERTY SKIP_AUTOUIC ON) + set_property(SOURCE /path/to/file3.hh PROPERTY SKIP_AUTOGEN ON) + +This policy was introduced in CMake version 3.17.0. 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/CMP0101.rst b/Help/policy/CMP0101.rst new file mode 100644 index 0000000..f02bccc --- /dev/null +++ b/Help/policy/CMP0101.rst @@ -0,0 +1,22 @@ +CMP0101 +------- + +.. versionadded:: 3.17 + +:command:`target_compile_options` now honors ``BEFORE`` keyword in all scopes. + +In CMake 3.16 and below the :command:`target_compile_options` ignores the +``BEFORE`` keyword in private scope. CMake 3.17 and later honors +``BEFORE`` keyword in all scopes. This policy provides compatibility for +projects that have not been updated to expect the new behavior. + +The ``OLD`` behavior for this policy is to not honor ``BEFORE`` keyword in +private scope. The ``NEW`` behavior of this policy is to honor +``BEFORE`` keyword in all scopes. + +This policy was introduced in CMake version 3.17. 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/CMP0102.rst b/Help/policy/CMP0102.rst new file mode 100644 index 0000000..78b5584 --- /dev/null +++ b/Help/policy/CMP0102.rst @@ -0,0 +1,27 @@ +CMP0102 +------- + +.. versionadded:: 3.17 + +The :command:`mark_as_advanced` command no longer creates a cache entry if one +does not already exist. + +In CMake 3.16 and below, if a variable was not defined at all or just defined +locally, the :command:`mark_as_advanced` command would create a new cache +entry with an ``UNINITIALIZED`` type and no value. When a :command:`find_path` +(or other similar ``find_`` command) would next run, it would find this +undefined cache entry and set it up with an empty string value. This process +would end up deleting the local variable in the process (due to the way the +cache works), effectively clearing any stored ``find_`` results that were only +available in the local scope. + +The ``OLD`` behavior for this policy is to create the empty cache definition. +The ``NEW`` behavior of this policy is to ignore variables which do not +already exist in the cache. + +This policy was introduced in CMake version 3.17. 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/CMP0103.rst b/Help/policy/CMP0103.rst new file mode 100644 index 0000000..b5f44d1 --- /dev/null +++ b/Help/policy/CMP0103.rst @@ -0,0 +1,24 @@ +CMP0103 +------- + +.. versionadded:: 3.18 + +Multiple calls to :command:`export` command with same ``FILE`` without +``APPEND`` is no longer allowed. + +In CMake 3.17 and below, multiple calls to :command:`export` command with the +same ``FILE`` without ``APPEND`` are accepted silently but only the last +occurrence is taken into account during the generation. + +The ``OLD`` behavior for this policy is to ignore the multiple occurrences of + :command:`export` command except the last one. + +The ``NEW`` behavior of this policy is to raise an error on second call to +:command:`export` command with same ``FILE`` without ``APPEND``. + +This policy was introduced in CMake version 3.18. 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/CMP0104.rst b/Help/policy/CMP0104.rst new file mode 100644 index 0000000..b125729 --- /dev/null +++ b/Help/policy/CMP0104.rst @@ -0,0 +1,58 @@ +CMP0104 +------- + +.. versionadded:: 3.18 + +Initialize :variable:`CMAKE_CUDA_ARCHITECTURES` when +:variable:`CMAKE_CUDA_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` is ``NVIDIA``. +Raise an error if :prop_tgt:`CUDA_ARCHITECTURES` is empty. + +:variable:`CMAKE_CUDA_ARCHITECTURES` introduced in CMake 3.18 is used to +initialize :prop_tgt:`CUDA_ARCHITECTURES`, which passes correct code generation +flags to the CUDA compiler. + +Previous to this users had to manually specify the code generation flags. This +policy is for backwards compatibility with manually specifying code generation +flags. + +The ``OLD`` behavior for this policy is to not initialize +:variable:`CMAKE_CUDA_ARCHITECTURES` when +:variable:`CMAKE_CUDA_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` is ``NVIDIA``. +Empty :prop_tgt:`CUDA_ARCHITECTURES` is allowed. + +The ``NEW`` behavior of this policy is to initialize +:variable:`CMAKE_CUDA_ARCHITECTURES` when +:variable:`CMAKE_CUDA_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` is ``NVIDIA`` +and raise an error if :prop_tgt:`CUDA_ARCHITECTURES` is empty during generation. + +If :prop_tgt:`CUDA_ARCHITECTURES` is set to a false value no architectures +flags are passed to the compiler. This is intended to support packagers and +the rare cases where full control over the passed flags is required. + +This policy was introduced in CMake version 3.18. 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 + +Examples +^^^^^^^^ + +.. code-block:: cmake + + set_target_properties(tgt PROPERTIES CUDA_ARCHITECTURES "35;50;72") + +Generates code for real and virtual architectures ``30``, ``50`` and ``72``. + +.. code-block:: cmake + + set_property(TARGET tgt PROPERTY CUDA_ARCHITECTURES 70-real 72-virtual) + +Generates code for real architecture ``70`` and virtual architecture ``72``. + +.. code-block:: cmake + + set_property(TARGET tgt PROPERTY CUDA_ARCHITECTURES OFF) + +CMake will not pass any architecture flags to the compiler. diff --git a/Help/policy/CMP0105.rst b/Help/policy/CMP0105.rst new file mode 100644 index 0000000..097a59a --- /dev/null +++ b/Help/policy/CMP0105.rst @@ -0,0 +1,21 @@ +CMP0105 +------- + +.. versionadded:: 3.18 + +:prop_tgt:`LINK_OPTIONS` and :prop_tgt:`INTERFACE_LINK_OPTIONS` target +properties are now used for the device link step. + +In CMake 3.17 and below, link options are not used by the device link step. + +The ``OLD`` behavior for this policy is to ignore the link options. + +The ``NEW`` behavior of this policy is to use the link options during the +device link step. + +This policy was introduced in CMake version 3.17. 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/CMP0106.rst b/Help/policy/CMP0106.rst new file mode 100644 index 0000000..18a6635 --- /dev/null +++ b/Help/policy/CMP0106.rst @@ -0,0 +1,21 @@ +CMP0106 +------- + +.. versionadded:: 3.18 + +The :module:`Documentation` module is removed. + +The :module:`Documentation` was added as a support mechanism for the VTK +project and was tuned for that project. Instead of CMake providing this module +with (now old) VTK patterns for cache variables and required packages, the +module is now deprecated by CMake itself. + +The ``OLD`` behavior of this policy is for :module:`Documentation` to add +cache variables and find VTK documentation dependent packages. The ``NEW`` +behavior is to act as an empty module. + +This policy was introduced in CMake version 3.18. 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/CMP0107.rst b/Help/policy/CMP0107.rst new file mode 100644 index 0000000..da5ae06 --- /dev/null +++ b/Help/policy/CMP0107.rst @@ -0,0 +1,21 @@ +CMP0107 +------- + +.. versionadded:: 3.18 + +It is not allowed to create an ``ALIAS`` target with the same name as an +another target. + +In CMake 3.17 and below, an ``ALIAS`` target can overwrite silently an existing +target with the same name. + +The ``OLD`` behavior for this policy is to allow target overwrite. + +The ``NEW`` behavior of this policy is to prevent target overwriting. + +This policy was introduced in CMake version 3.17. 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/CMP0108.rst b/Help/policy/CMP0108.rst new file mode 100644 index 0000000..4d1091d --- /dev/null +++ b/Help/policy/CMP0108.rst @@ -0,0 +1,21 @@ +CMP0108 +------- + +.. versionadded:: 3.18 + +A target is not allowed to link to itself even through an ``ALIAS`` target. + +In CMake 3.17 and below, a target can link to a target aliased to itself. + +The ``OLD`` behavior for this policy is to allow a target to link to a target +aliased to itself. + +The ``NEW`` behavior of this policy is to prevent a target to link to itself +through an ``ALIAS`` target. + +This policy was introduced in CMake version 3.17. 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/CMP0109.rst b/Help/policy/CMP0109.rst new file mode 100644 index 0000000..f86287f --- /dev/null +++ b/Help/policy/CMP0109.rst @@ -0,0 +1,24 @@ +CMP0109 +------- + +.. versionadded:: 3.19 + +:command:`find_program` requires permission to execute but not to read. + +In CMake 3.18 and below, the :command:`find_program` command on UNIX +would find files that are readable without requiring execute permission, +and would not find files that are executable without read permission. +In CMake 3.19 and above, ``find_program`` now prefers to require execute +permission but not read permission. This policy provides compatibility +with projects that have not been updated to expect the new behavior. + +The ``OLD`` behavior for this policy is for ``find_program`` to require +read permission but not execute permission. +The ``NEW`` behavior for this policy is for ``find_program`` to require +execute permission but not read permission. + +This policy was introduced in CMake version 3.19. 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/CMP0110.rst b/Help/policy/CMP0110.rst new file mode 100644 index 0000000..25a0008 --- /dev/null +++ b/Help/policy/CMP0110.rst @@ -0,0 +1,26 @@ +CMP0110 +------- + +.. versionadded:: 3.19 + +:command:`add_test` supports arbitrary characters in test names. + +:command:`add_test` can now (officially) create tests with whitespace and +other special characters in its name. Before CMake version 3.19 that was not +allowed, however, it was possible to work around this limitation by explicitly +putting escaped quotes arount the test's name in the ``add_test`` command. + +Although never officially supported several projects in the wild found and +implemented this workaround. However, the new change which officially allows +the ``add_test`` command to support whitespace and other special characters in +test names now breaks that workaround. In order for these projects to work +smoothly with newer CMake versions, this policy was introduced. + +The ``OLD`` behavior of this policy is to still prevent ``add_test`` from +handling whitespace and special characters properly (if not using the +mentioned workaround). The ``NEW`` behavior on the other hand allows names +with whitespace and special characters for tests created by ``add_test``. + +This policy was introduced in CMake version 3.19. 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. diff --git a/Help/policy/CMP0111.rst b/Help/policy/CMP0111.rst new file mode 100644 index 0000000..e327583 --- /dev/null +++ b/Help/policy/CMP0111.rst @@ -0,0 +1,27 @@ +CMP0111 +------- + +.. versionadded:: 3.19 + +An imported target missing its location property fails during generation. + +:ref:`Imported Targets` for library files and executables require that +their location on disk is specified in a target property such as +:prop_tgt:`IMPORTED_LOCATION`, :prop_tgt:`IMPORTED_IMPLIB`, or a +per-configuration equivalent. If a needed location property is not set, +CMake 3.18 and below generate the string ``<TARGET_NAME>-NOTFOUND`` in +its place, which results in failures of the corresponding rules at build +time. CMake 3.19 and above prefer instead to raise an error during +generation. This policy provides compatibility for projects that have +not been updated to expect the new behavior. + +The ``OLD`` behavior of this policy is to generate the location of an imported +unknown, static or shared library target as ``<TARGET_NAME>-NOTFOUND`` if not +set. +The ``NEW`` behavior is to raise an error. + +This policy was introduced in CMake version 3.19. 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/CMP0112.rst b/Help/policy/CMP0112.rst new file mode 100644 index 0000000..313a51e --- /dev/null +++ b/Help/policy/CMP0112.rst @@ -0,0 +1,40 @@ +CMP0112 +------- + +.. versionadded:: 3.19 + +Target file component generator expressions do not add target dependencies. + +The following target-based generator expressions that query for directory or +file name components no longer add a dependency on the evaluated target. + + - ``TARGET_FILE_NAME`` + - ``TARGET_FILE_DIR`` + - ``TARGET_LINKER_FILE_BASE_NAME`` + - ``TARGET_LINKER_FILE_NAME`` + - ``TARGET_LINKER_FILE_DIR`` + - ``TARGET_SONAME_FILE_NAME`` + - ``TARGET_SONAME_FILE_DIR`` + - ``TARGET_PDB_FILE_NAME`` + - ``TARGET_PDB_FILE_DIR`` + - ``TARGET_BUNDLE_DIR`` + - ``TARGET_BUNDLE_CONTENT_DIR`` + + +In CMake 3.18 and lower a dependency on the evaluated target of the above +generator expressions would always be added. CMake 3.19 and above prefer +to not add this dependency. This policy provides compatibility for projects +that have not been updated to expect the new behavior. + +The ``OLD`` behavior for this policy is to add a dependency on the evaluated +target for the above generator expressions. The ``NEW`` behavior of +this policy is to not add a dependency on the evaluated target for the +above generator expressions. + +This policy was introduced in CMake version 3.19. Unlike many 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_CMP0112 <CMAKE_POLICY_WARNING_CMP<NNNN>>` +variable to control the warning. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0113.rst b/Help/policy/CMP0113.rst new file mode 100644 index 0000000..6f56902 --- /dev/null +++ b/Help/policy/CMP0113.rst @@ -0,0 +1,43 @@ +CMP0113 +------- + +.. versionadded:: 3.19 + +:ref:`Makefile Generators` do not repeat custom commands from target +dependencies. + +Consider a chain of custom commands split across two dependent targets: + +.. code-block:: cmake + + add_custom_command(OUTPUT output-not-created + COMMAND ... DEPENDS ...) + set_property(SOURCE output-not-created PROPERTY SYMBOLIC 1) + add_custom_command(OUTPUT output-created + COMMAND ... DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/output-not-created) + add_custom_target(first DEPENDS output-not-created) + add_custom_target(second DEPENDS output-created) + add_dependencies(second first) + +In CMake 3.18 and lower, the Makefile generators put a copy of both custom +commands in the Makefile for target ``second`` even though its dependency on +target ``first`` ensures that the first custom command runs before the second. +Running ``make second`` would cause the first custom command to run once in +the ``first`` target and then again in the ``second`` target. + +CMake 3.19 and above prefer to not duplicate custom commands in a target that +are already generated in other targets on which the target depends (directly or +indirectly). This policy provides compatibility for projects that have not +been updated to expect the new behavior. In particular, projects that relied +on the duplicate execution or that did not properly set the :prop_sf:`SYMBOLIC` +source file property may be affected. + +The ``OLD`` behavior for this policy is to duplicate custom commands in +dependent targets. The ``NEW`` behavior of this policy is to not duplicate +custom commands in dependent targets. + +This policy was introduced in CMake version 3.19. 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/CMP0114.rst b/Help/policy/CMP0114.rst new file mode 100644 index 0000000..ae48478 --- /dev/null +++ b/Help/policy/CMP0114.rst @@ -0,0 +1,85 @@ +CMP0114 +------- + +.. versionadded:: 3.19 + +:module:`ExternalProject` step targets fully adopt their steps. + +The :command:`ExternalProject_Add` ``STEP_TARGETS`` option, and the +:command:`ExternalProject_Add_StepTargets` function, can be used to +create build targets for individual steps of an external project. + +In CMake 3.18 and below, step targets have some limitations: + +* Step targets always depend on targets named by the + :command:`ExternalProject_Add` ``DEPENDS`` option even though + not all steps need them. In order to allow step targets to be created + without those dependencies, the :command:`ExternalProject_Add` + ``INDEPENDENT_STEP_TARGETS`` option or the + :command:`ExternalProject_Add_StepTargets` ``NO_DEPENDS`` option may + be used. However, adding such "independent" step targets makes sense + only for specific steps such as ``download``, ``update``, and ``patch`` + because they do not need any of the external project's build dependencies. + Furthermore, it does not make sense to create independent step targets + for steps that depend on non-independent steps. Such rules are not + enforced, and projects that do not follow them can generate build systems + with confusing and generator-specific behavior. + +* Step targets hold copies of the custom commands implementing their + steps that are separate from the copies in the primary target created + by :command:`ExternalProject_Add`, and the primary target does not + depend on the step targets. In parallel builds that drive the primary + target and step targets concurrently, multiple copies of the steps' + commands may run concurrently and race each other. + + Also, prior to policy :policy:`CMP0113`, the step targets generated + by :ref:`Makefile Generators` also contain all the custom commands + on which their step depends. This can lead to repeated execution of + those steps even in serial builds. + +In CMake 3.19 and above, the :module:`ExternalProject` module prefers +a revised design to address these problems: + +* Each step is classified as "independent" if it does not depend + on other targets named by the :command:`ExternalProject_Add` ``DEPENDS``. + The predefined steps are automatically classified by default: + + * The ``download``, ``update``, and ``patch`` steps are independent. + * The ``configure``, ``build``, ``test``, and ``install`` steps are not. + + For custom steps, the :command:`ExternalProject_Add_Step` command provides + an ``INDEPENDENT`` option to mark them as independent. It is an error to + mark a step as independent if it depends on other steps that are not. Note + that this use of the term "independent" refers only to independence from + external targets and is orthogonal to a step's dependencies on other steps. + +* Step targets created by the :command:`ExternalProject_Add` ``STEP_TARGETS`` + option or the :command:`ExternalProject_Add_Step` function are now + independent if and only if their steps are marked as independent. + The :command:`ExternalProject_Add` ``INDEPENDENT_STEP_TARGETS`` option + and :command:`ExternalProject_Add_StepTargets` ``NO_DEPENDS`` option + are no longer allowed. + +* Step targets, when created, are fully responsible for holding the + custom commands implementing their steps. The primary target created + by :command:`ExternalProject_Add` depends on the step targets, and the + step targets depend on each other. The target-level dependencies match + the file-level dependencies used by the custom commands for each step. + + When the :command:`ExternalProject_Add` ``UPDATE_DISCONNECTED`` or + ``TEST_EXCLUDE_FROM_MAIN`` option is used, or the + :command:`ExternalProject_Add_Step` ``EXCLUDE_FROM_MAIN`` option is used + for a custom step, some step targets may be created automatically. + These are needed to hold the steps commonly depended upon by the primary + target and the disconnected step targets. + +Policy ``CMP0114`` provides compatibility for projects that have not been +updated to expect the new behavior. The ``OLD`` behavior for this policy +is to use the above-documented behavior from 3.18 and below. The ``NEW`` +behavior for this policy is to use the above-documented behavior preferred +by 3.19 and above. + +This policy was introduced in CMake version 3.19. 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. diff --git a/Help/policy/CMP0115.rst b/Help/policy/CMP0115.rst new file mode 100644 index 0000000..7f82c43 --- /dev/null +++ b/Help/policy/CMP0115.rst @@ -0,0 +1,34 @@ +CMP0115 +------- + +.. versionadded:: 3.20 + +Source file extensions must be explicit. + +In CMake 3.19 and below, if a source file could not be found by the name +specified, it would append a list of known extensions to the name to see if +the file with the extension could be found. For example, this would allow the +user to run: + +.. code-block:: cmake + + add_executable(exe main) + +and put ``main.c`` in the executable without specifying the extension. + +Starting in CMake 3.20, CMake prefers all source files to have their extensions +explicitly listed: + +.. code-block:: cmake + + add_executable(exe main.c) + +The ``OLD`` behavior for this policy is to implicitly append known extensions +to source files if they can't be found. The ``NEW`` behavior of this policy is +to not append known extensions and require them to be explicit. + +This policy was introduced in CMake version 3.20. 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/CMP0116.rst b/Help/policy/CMP0116.rst new file mode 100644 index 0000000..18e5a96 --- /dev/null +++ b/Help/policy/CMP0116.rst @@ -0,0 +1,41 @@ +CMP0116 +------- + +.. versionadded:: 3.20 + +Ninja generators transform ``DEPFILE`` s from :command:`add_custom_command`. + +In CMake 3.19 and below, files given to the ``DEPFILE`` argument of +:command:`add_custom_command` were passed directly to Ninja's ``depfile`` +variable without any path resolution. This meant that if +:command:`add_custom_command` was called from a subdirectory (created by +:command:`add_subdirectory`), the ``DEPFILE`` argument would have to be either +an absolute path or a path relative to :variable:`CMAKE_BINARY_DIR`, rather +than :variable:`CMAKE_CURRENT_BINARY_DIR`. In addition, no transformation was +done on the file listed in ``DEPFILE``, which meant that the paths within the +``DEPFILE`` had the same restrictions. + +Starting with CMake 3.20, the ``DEPFILE`` argument is relative to +:variable:`CMAKE_CURRENT_BINARY_DIR` (unless it is absolute), and the paths in +the ``DEPFILE`` are also relative to :variable:`CMAKE_CURRENT_BINARY_DIR`. +CMake automatically transforms the paths in the ``DEPFILE`` (unless they are +absolute) after the custom command is run. The file listed in ``DEPFILE`` is +not modified in any way. Instead, CMake writes the transformation to its own +internal file, and passes this internal file to Ninja's ``depfile`` variable. +This transformation happens regardless of whether or not ``DEPFILE`` is +relative, and regardless of whether or not :command:`add_custom_command` is +called from a subdirectory. + +The ``OLD`` behavior for this policy is to pass the ``DEPFILE`` to Ninja +unaltered. The ``NEW`` behavior for this policy is to transform the ``DEPFILE`` +after running the custom command. The status of ``CMP0116`` is recorded at the +time of the custom command's creation, and you can have custom commands in the +same directory with different values for ``CMP0116`` by setting the policy +before each custom command. + +This policy was introduced in CMake version 3.20. Unlike most policies, +CMake version |release| does *not* warn by default when this policy is not set +(unless ``DEPFILE`` is used in a subdirectory) and simply uses ``OLD`` +behavior. See documentation of the +:variable:`CMAKE_POLICY_WARNING_CMP0116 <CMAKE_POLICY_WARNING_CMP<NNNN>>` +variable to control the warning. diff --git a/Help/policy/CMP0117.rst b/Help/policy/CMP0117.rst new file mode 100644 index 0000000..0c4dd30 --- /dev/null +++ b/Help/policy/CMP0117.rst @@ -0,0 +1,43 @@ +CMP0117 +------- + +.. versionadded:: 3.20 + +MSVC RTTI flag ``/GR`` is not added to +:variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>` by default. + +When using MSVC-like compilers in CMake 3.19 and below, the RTTI flag +``/GR`` is added to :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>` by +default. This behavior is left from support for MSVC versions from Visual +Studio 2003 and below that did not enable RTTI by default. It is no longer +necessary. Furthermore, it is problematic for projects that want to change +to ``/GR-`` programmatically. In particular, it requires string editing of +the :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>` variable with knowledge +of the CMake builtin default so it can be replaced. + +CMake 3.20 and above prefer to leave out ``/GR`` from the value of +:variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>` by default. + +This policy provides compatibility with projects that have not been updated +to expect the lack of the ``/GR`` flag. The policy setting takes effect as +of the first :command:`project` or :command:`enable_language` command that +initializes :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>`. + +.. 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 the MSVC ``/GR`` flag in the +default :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>` cache entry. The +``NEW`` behavior for this policy is to *not* place the MSVC ``/GR`` flag in +the default cache entry. + +This policy was introduced in CMake version 3.20. 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/CMP0118.rst b/Help/policy/CMP0118.rst new file mode 100644 index 0000000..aa7e0f7 --- /dev/null +++ b/Help/policy/CMP0118.rst @@ -0,0 +1,25 @@ +CMP0118 +------- + +.. versionadded:: 3.20 + +The :prop_sf:`GENERATED` source file property is now visible in all directories. + +Whether or not a source file is generated is an all-or-nothing global +property of the source. Consequently, the associated ``GENERATED`` +property is now visible from any directory scope, not only from the scope +for which it was set. + +Additionally, the ``GENERATED`` property may now be set only to boolean +values, and may not be turned off once turned on. + +The ``OLD`` behavior of this policy is to only allow ``GENERATED`` to be +visible from the directory scope for which it was set. The ``NEW`` +behavior on the other hand allows it to be visible from any scope. + +This policy was introduced in CMake version 3.20. 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 with regard +to visibility of the ``GENERATED`` property. However, CMake does warn +about setting the ``GENERATED`` property to a non-boolean value. diff --git a/Help/policy/CMP0119.rst b/Help/policy/CMP0119.rst new file mode 100644 index 0000000..61c8bdc --- /dev/null +++ b/Help/policy/CMP0119.rst @@ -0,0 +1,36 @@ +CMP0119 +------- + +.. versionadded:: 3.20 + +:prop_sf:`LANGUAGE` source file property explicitly compiles as specified +language. + +The :prop_sf:`LANGUAGE` source file property is documented to mean that the +source file is written in the specified language. In CMake 3.19 and below, +setting this property causes CMake to compile the source file using the +compiler for the specified language. However, it only passes an explicit +flag to tell the compiler to treat the source as the specified language +for MSVC-like, XL, and Embarcadero compilers for the ``CXX`` language. +CMake 3.20 and above prefer to also explicitly tell the compiler to use +the specified language using a flag such as ``-x c`` on all compilers +for which such flags are known. + +This policy provides compatibility for projects that have not been updated +to expect this behavior. For example, some projects were setting the +``LANGUAGE`` property to ``C`` on assembly-language ``.S`` source files +in order to compile them using the C compiler. Such projects should be +updated to use ``enable_language(ASM)``, for which CMake will often choose +the C compiler as the assembler on relevant platforms anyway. + +The ``OLD`` behavior for this policy is to interpret the ``LANGUAGE <LANG>`` +property using its undocumented meaning to "use the ``<LANG>`` compiler". +The ``NEW`` behavior for this policy is to interpret the ``LANGUAGE <LANG>`` +property using its documented meaning to "compile as a ``<LANG>`` source". + +This policy was introduced in CMake version 3.20. 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/CMP0120.rst b/Help/policy/CMP0120.rst new file mode 100644 index 0000000..9d2f6c9 --- /dev/null +++ b/Help/policy/CMP0120.rst @@ -0,0 +1,47 @@ +CMP0120 +------- + +.. versionadded:: 3.20 + +The :module:`WriteCompilerDetectionHeader` module is removed. + +CMake versions 3.1 through 3.19 provide this module to generate a +C++ compatibility layer by re-using information from CMake's table of +preprocessor checks for :manual:`cmake-compile-features(7)`. However: + +* Those granular features have been superseded by meta-features for + :ref:`Requiring Language Standards` such as ``cxx_std_11``. Therefore + no new granular feature checks will be added and projects will need to + use other means to conditionally use new C++ features. + +* The module exposes some of CMake's implementation details directly + to C++ translation units. + +* The module's approach effectively provides a header file with CMake, + thus tying the version of the header to the version of CMake. + Many projects found that the :module:`WriteCompilerDetectionHeader` was + best used by manually generating its header locally with a recent version + of CMake and then bundling it with the project source so that it could + be used with older CMake versions. + +For reasons including the above, CMake 3.20 and above prefer to not +provide the :module:`WriteCompilerDetectionHeader` module. This policy +provides compatibility for projects that have not been ported away from +it. Projects using the module should be updated to stop using it. +Alternatives include: + +* Bundle a copy of the generated header in the project's source. +* Use a third-party alternative, such as the CC0-licensed `Hedley`_. +* Drop support for compilers too old to provide the features natively. + +The ``OLD`` behavior of this policy is for inclusion of the deprecated +:module:`WriteCompilerDetectionHeader` module to work. The ``NEW`` +behavior is for inclusion of the module to fail as if it does not exist. + +This policy was introduced in CMake version 3.20. 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 + +.. _`Hedley`: https://nemequ.github.io/hedley/ diff --git a/Help/policy/CMP0121.rst b/Help/policy/CMP0121.rst new file mode 100644 index 0000000..5ef2856 --- /dev/null +++ b/Help/policy/CMP0121.rst @@ -0,0 +1,21 @@ +CMP0121 +------- + +.. versionadded:: 3.21 + +The :command:`list` command now detects invalid indicies. + +Prior to CMake version 3.21, the :command:`list` command's ``GET``, +``INSERT``, ``SUBLIST``, and ``REMOVE_AT`` subcommands did not detect invalid +index arguments. + +The ``OLD`` behavior of this policy is for invalid indicies to be treated as +their integer value (if any) at the start of the string. For example, +``2good4you`` is a ``2`` and ``not_an_integer`` is a ``0``. The ``NEW`` +behavior is for invalid indicies to trigger an error. + +This policy was introduced in CMake version 3.21. 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/CMP0122.rst b/Help/policy/CMP0122.rst new file mode 100644 index 0000000..1ff8c48 --- /dev/null +++ b/Help/policy/CMP0122.rst @@ -0,0 +1,17 @@ +CMP0122 +------- + +.. versionadded:: 3.21 + +:module:`UseSWIG` use library name conventions for ``CSharp`` language. + +Starting with CMake 3.21, :module:`UseSWIG` generates now a library using +default naming conventions. This policy provides compatibility with projects +that expect the legacy behavior. + +This policy was introduced in CMake version 3.21. 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/DEPRECATED.txt b/Help/policy/DEPRECATED.txt new file mode 100644 index 0000000..f66de55 --- /dev/null +++ b/Help/policy/DEPRECATED.txt @@ -0,0 +1,4 @@ +.. note:: + The ``OLD`` behavior of a policy is + :manual:`deprecated by definition <cmake-policies(7)>` + and may be removed in a future version of CMake. diff --git a/Help/policy/DISALLOWED_COMMAND.txt b/Help/policy/DISALLOWED_COMMAND.txt new file mode 100644 index 0000000..6500bb0 --- /dev/null +++ b/Help/policy/DISALLOWED_COMMAND.txt @@ -0,0 +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 +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 :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 new file mode 100644 index 0000000..ec4de9d --- /dev/null +++ b/Help/prop_cache/ADVANCED.rst @@ -0,0 +1,8 @@ +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 :command:`mark_as_advanced` +command modifies this property. diff --git a/Help/prop_cache/HELPSTRING.rst b/Help/prop_cache/HELPSTRING.rst new file mode 100644 index 0000000..71a86d0 --- /dev/null +++ b/Help/prop_cache/HELPSTRING.rst @@ -0,0 +1,7 @@ +HELPSTRING +---------- + +Help associated with entry in GUIs. + +This string summarizes the purpose of an entry to help users set it +through a CMake GUI. diff --git a/Help/prop_cache/MODIFIED.rst b/Help/prop_cache/MODIFIED.rst new file mode 100644 index 0000000..3ad7035 --- /dev/null +++ b/Help/prop_cache/MODIFIED.rst @@ -0,0 +1,7 @@ +MODIFIED +-------- + +Internal management property. Do not set or get. + +This is an internal cache entry property managed by CMake to track +interactive user modification of entries. Ignore it. diff --git a/Help/prop_cache/STRINGS.rst b/Help/prop_cache/STRINGS.rst new file mode 100644 index 0000000..0e3c326 --- /dev/null +++ b/Help/prop_cache/STRINGS.rst @@ -0,0 +1,9 @@ +STRINGS +------- + +Enumerate possible ``STRING`` entry values for GUI selection. + +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 new file mode 100644 index 0000000..7ca859f --- /dev/null +++ b/Help/prop_cache/TYPE.rst @@ -0,0 +1,21 @@ +TYPE +---- + +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: + +:: + + BOOL = Boolean ON/OFF value. + PATH = Path to a directory. + FILEPATH = Path to a file. + STRING = Generic string value. + INTERNAL = Do not present in GUI at all. + 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 ( :command:`set`, :command:`option`, :command:`find_library`, etc.). diff --git a/Help/prop_cache/VALUE.rst b/Help/prop_cache/VALUE.rst new file mode 100644 index 0000000..59aabd4 --- /dev/null +++ b/Help/prop_cache/VALUE.rst @@ -0,0 +1,7 @@ +VALUE +----- + +Value of a cache entry. + +This property maps to the actual value of a cache entry. Setting this +property always sets the value without checking, so use with care. diff --git a/Help/prop_dir/ADDITIONAL_CLEAN_FILES.rst b/Help/prop_dir/ADDITIONAL_CLEAN_FILES.rst new file mode 100644 index 0000000..6097d14 --- /dev/null +++ b/Help/prop_dir/ADDITIONAL_CLEAN_FILES.rst @@ -0,0 +1,23 @@ +ADDITIONAL_CLEAN_FILES +---------------------- + +.. versionadded:: 3.15 + +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 new file mode 100644 index 0000000..b6f6160 --- /dev/null +++ b/Help/prop_dir/ADDITIONAL_MAKE_CLEAN_FILES.rst @@ -0,0 +1,17 @@ +ADDITIONAL_MAKE_CLEAN_FILES +--------------------------- + +.. deprecated:: 3.15 + + 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/BINARY_DIR.rst b/Help/prop_dir/BINARY_DIR.rst new file mode 100644 index 0000000..fcf9d17 --- /dev/null +++ b/Help/prop_dir/BINARY_DIR.rst @@ -0,0 +1,7 @@ +BINARY_DIR +---------- + +.. versionadded:: 3.7 + +This read-only directory property reports absolute path to the binary +directory corresponding to the source on which it is read. diff --git a/Help/prop_dir/BUILDSYSTEM_TARGETS.rst b/Help/prop_dir/BUILDSYSTEM_TARGETS.rst new file mode 100644 index 0000000..5c5893d --- /dev/null +++ b/Help/prop_dir/BUILDSYSTEM_TARGETS.rst @@ -0,0 +1,13 @@ +BUILDSYSTEM_TARGETS +------------------- + +.. versionadded:: 3.7 + +This read-only directory property contains a +: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 +:ref:`Interface Libraries`. Each entry in the list is the logical name +of a target, suitable to pass to the :command:`get_property` command +``TARGET`` option. diff --git a/Help/prop_dir/CACHE_VARIABLES.rst b/Help/prop_dir/CACHE_VARIABLES.rst new file mode 100644 index 0000000..2c66f93 --- /dev/null +++ b/Help/prop_dir/CACHE_VARIABLES.rst @@ -0,0 +1,7 @@ +CACHE_VARIABLES +--------------- + +List of cache variables available in the current directory. + +This read-only property specifies the list of CMake cache variables +currently defined. It is intended for debugging purposes. diff --git a/Help/prop_dir/CLEAN_NO_CUSTOM.rst b/Help/prop_dir/CLEAN_NO_CUSTOM.rst new file mode 100644 index 0000000..5ae78bf --- /dev/null +++ b/Help/prop_dir/CLEAN_NO_CUSTOM.rst @@ -0,0 +1,6 @@ +CLEAN_NO_CUSTOM +--------------- + +Set to true to tell :ref:`Makefile Generators` not to remove the outputs of +custom commands for this directory during the ``make clean`` operation. +This is ignored on other generators because it is not possible to implement. diff --git a/Help/prop_dir/CMAKE_CONFIGURE_DEPENDS.rst b/Help/prop_dir/CMAKE_CONFIGURE_DEPENDS.rst new file mode 100644 index 0000000..b1aef19 --- /dev/null +++ b/Help/prop_dir/CMAKE_CONFIGURE_DEPENDS.rst @@ -0,0 +1,9 @@ +CMAKE_CONFIGURE_DEPENDS +----------------------- + +Tell CMake about additional input files to the configuration process. +If any named file is modified the build system will re-run CMake to +re-configure the file and generate the build system again. + +Specify files as a semicolon-separated list of paths. Relative paths +are interpreted as relative to the current source directory. diff --git a/Help/prop_dir/COMPILE_DEFINITIONS.rst b/Help/prop_dir/COMPILE_DEFINITIONS.rst new file mode 100644 index 0000000..18f4567 --- /dev/null +++ b/Help/prop_dir/COMPILE_DEFINITIONS.rst @@ -0,0 +1,31 @@ +COMPILE_DEFINITIONS +------------------- + +Preprocessor definitions for compiling a directory's sources. + +This property specifies the list of options given so far to the +: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``. +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 will be initialized in each directory by its value in the +directory's parent. + +CMake will automatically drop some definitions that are not supported +by the native build tool. + +.. include:: /include/COMPILE_DEFINITIONS_DISCLAIMER.txt + +Contents of ``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. + +The corresponding :prop_dir:`COMPILE_DEFINITIONS_<CONFIG>` property may +be set to specify per-configuration definitions. Generator expressions +should be preferred instead of setting the alternative property. diff --git a/Help/prop_dir/COMPILE_DEFINITIONS_CONFIG.rst b/Help/prop_dir/COMPILE_DEFINITIONS_CONFIG.rst new file mode 100644 index 0000000..a6af45f --- /dev/null +++ b/Help/prop_dir/COMPILE_DEFINITIONS_CONFIG.rst @@ -0,0 +1,19 @@ +COMPILE_DEFINITIONS_<CONFIG> +---------------------------- + +Ignored. See CMake Policy :policy:`CMP0043`. + +Per-configuration preprocessor definitions in a directory. + +This is the configuration-specific version of :prop_dir:`COMPILE_DEFINITIONS` +where ``<CONFIG>`` is an upper-case name (ex. ``COMPILE_DEFINITIONS_DEBUG``). + +This property will be initialized in each directory by its value in +the directory's parent. + +Contents of ``COMPILE_DEFINITIONS_<CONFIG>`` 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. + +Generator expressions should be preferred instead of setting this property. diff --git a/Help/prop_dir/COMPILE_OPTIONS.rst b/Help/prop_dir/COMPILE_OPTIONS.rst new file mode 100644 index 0000000..48e8b9b --- /dev/null +++ b/Help/prop_dir/COMPILE_OPTIONS.rst @@ -0,0 +1,16 @@ +COMPILE_OPTIONS +--------------- + +List of options to pass to the compiler. + +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 +property when a target is created, which is used by the generators to set +the options for the compiler. + +Contents of ``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. diff --git a/Help/prop_dir/DEFINITIONS.rst b/Help/prop_dir/DEFINITIONS.rst new file mode 100644 index 0000000..79ac3f3 --- /dev/null +++ b/Help/prop_dir/DEFINITIONS.rst @@ -0,0 +1,13 @@ +DEFINITIONS +----------- + +For CMake 2.4 compatibility only. Use :prop_dir:`COMPILE_DEFINITIONS` +instead. + +This read-only property specifies the list of flags given so far to +the :command:`add_definitions` command. It is intended for debugging +purposes. Use the :prop_dir:`COMPILE_DEFINITIONS` directory property +instead. + +This built-in read-only property does not exist if policy +:policy:`CMP0059` is set to ``NEW``. diff --git a/Help/prop_dir/EXCLUDE_FROM_ALL.rst b/Help/prop_dir/EXCLUDE_FROM_ALL.rst new file mode 100644 index 0000000..8e3cca0 --- /dev/null +++ b/Help/prop_dir/EXCLUDE_FROM_ALL.rst @@ -0,0 +1,13 @@ +EXCLUDE_FROM_ALL +---------------- + +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. + +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 new file mode 100644 index 0000000..f534976 --- /dev/null +++ b/Help/prop_dir/IMPLICIT_DEPENDS_INCLUDE_TRANSFORM.rst @@ -0,0 +1,34 @@ +IMPLICIT_DEPENDS_INCLUDE_TRANSFORM +---------------------------------- + +Specify ``#include`` line transforms for dependencies in a directory. + +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 +replaced by the value given with the macro argument substituted for +``%``. For example, the entry + +:: + + MYDIR(%)=<mydir/%> + +will convert lines of the form + +:: + + #include MYDIR(myheader.h) + +to + +:: + + #include <mydir/myheader.h> + +allowing the dependency to be followed. + +This property applies to sources in all targets within a directory. +The property value is initialized in each directory by its value in +the directory's parent. diff --git a/Help/prop_dir/INCLUDE_DIRECTORIES.rst b/Help/prop_dir/INCLUDE_DIRECTORIES.rst new file mode 100644 index 0000000..5d856b8 --- /dev/null +++ b/Help/prop_dir/INCLUDE_DIRECTORIES.rst @@ -0,0 +1,32 @@ +INCLUDE_DIRECTORIES +------------------- + +List of preprocessor include file search directories. + +This property specifies the list of directories given so far to the +:command:`include_directories` command. + +This property is used to populate the :prop_tgt:`INCLUDE_DIRECTORIES` +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, 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. + +Contents of ``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. diff --git a/Help/prop_dir/INCLUDE_REGULAR_EXPRESSION.rst b/Help/prop_dir/INCLUDE_REGULAR_EXPRESSION.rst new file mode 100644 index 0000000..bb90c61 --- /dev/null +++ b/Help/prop_dir/INCLUDE_REGULAR_EXPRESSION.rst @@ -0,0 +1,9 @@ +INCLUDE_REGULAR_EXPRESSION +-------------------------- + +Include file scanning regular expression. + +This property specifies the regular expression used during +dependency scanning to match include files that should be followed. +See the :command:`include_regular_expression` command for a high-level +interface to set this property. diff --git a/Help/prop_dir/INTERPROCEDURAL_OPTIMIZATION.rst b/Help/prop_dir/INTERPROCEDURAL_OPTIMIZATION.rst new file mode 100644 index 0000000..0c78dfb --- /dev/null +++ b/Help/prop_dir/INTERPROCEDURAL_OPTIMIZATION.rst @@ -0,0 +1,7 @@ +INTERPROCEDURAL_OPTIMIZATION +---------------------------- + +Enable interprocedural optimization for targets in a directory. + +If set to true, enables interprocedural optimizations if they are +known to be supported by the compiler. diff --git a/Help/prop_dir/INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst b/Help/prop_dir/INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst new file mode 100644 index 0000000..840a1db --- /dev/null +++ b/Help/prop_dir/INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst @@ -0,0 +1,8 @@ +INTERPROCEDURAL_OPTIMIZATION_<CONFIG> +------------------------------------- + +Per-configuration interprocedural optimization for a directory. + +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 0000000..bf14368 --- /dev/null +++ b/Help/prop_dir/LABELS.rst @@ -0,0 +1,15 @@ +LABELS +------ + +.. versionadded:: 3.10 + +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 new file mode 100644 index 0000000..44dc230 --- /dev/null +++ b/Help/prop_dir/LINK_DIRECTORIES.rst @@ -0,0 +1,17 @@ +LINK_DIRECTORIES +---------------- + +List of linker search directories. + +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 0000000..3a5c72f --- /dev/null +++ b/Help/prop_dir/LINK_OPTIONS.rst @@ -0,0 +1,19 @@ +LINK_OPTIONS +------------ + +.. versionadded:: 3.13 + +List of options to use for the link step of shared library, module +and executable targets as well as the device link step. + +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/LISTFILE_STACK.rst b/Help/prop_dir/LISTFILE_STACK.rst new file mode 100644 index 0000000..22ec4b6 --- /dev/null +++ b/Help/prop_dir/LISTFILE_STACK.rst @@ -0,0 +1,10 @@ +LISTFILE_STACK +-------------- + +The current stack of listfiles being processed. + +This property is mainly useful when trying to debug errors in your +CMake scripts. It returns a list of what list files are currently +being processed, in order. So if one listfile does an +:command:`include` command then that is effectively pushing the +included listfile onto the stack. diff --git a/Help/prop_dir/MACROS.rst b/Help/prop_dir/MACROS.rst new file mode 100644 index 0000000..245cc1b --- /dev/null +++ b/Help/prop_dir/MACROS.rst @@ -0,0 +1,8 @@ +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 :command:`macro` +command. diff --git a/Help/prop_dir/PARENT_DIRECTORY.rst b/Help/prop_dir/PARENT_DIRECTORY.rst new file mode 100644 index 0000000..3bc5824 --- /dev/null +++ b/Help/prop_dir/PARENT_DIRECTORY.rst @@ -0,0 +1,8 @@ +PARENT_DIRECTORY +---------------- + +Source directory that added current subdirectory. + +This read-only property specifies the source directory that added the +current source directory as a subdirectory of the build. In the +top-level directory the value is the empty-string. diff --git a/Help/prop_dir/RULE_LAUNCH_COMPILE.rst b/Help/prop_dir/RULE_LAUNCH_COMPILE.rst new file mode 100644 index 0000000..342d0ae --- /dev/null +++ b/Help/prop_dir/RULE_LAUNCH_COMPILE.rst @@ -0,0 +1,7 @@ +RULE_LAUNCH_COMPILE +------------------- + +Specify a launcher for compile rules. + +See the global property of the same name for details. This overrides +the global property for a directory. diff --git a/Help/prop_dir/RULE_LAUNCH_CUSTOM.rst b/Help/prop_dir/RULE_LAUNCH_CUSTOM.rst new file mode 100644 index 0000000..93d1e01 --- /dev/null +++ b/Help/prop_dir/RULE_LAUNCH_CUSTOM.rst @@ -0,0 +1,7 @@ +RULE_LAUNCH_CUSTOM +------------------ + +Specify a launcher for custom rules. + +See the global property of the same name for details. This overrides +the global property for a directory. diff --git a/Help/prop_dir/RULE_LAUNCH_LINK.rst b/Help/prop_dir/RULE_LAUNCH_LINK.rst new file mode 100644 index 0000000..3cfb236 --- /dev/null +++ b/Help/prop_dir/RULE_LAUNCH_LINK.rst @@ -0,0 +1,7 @@ +RULE_LAUNCH_LINK +---------------- + +Specify a launcher for link rules. + +See the global property of the same name for details. This overrides +the global property for a directory. diff --git a/Help/prop_dir/SOURCE_DIR.rst b/Help/prop_dir/SOURCE_DIR.rst new file mode 100644 index 0000000..d73707d --- /dev/null +++ b/Help/prop_dir/SOURCE_DIR.rst @@ -0,0 +1,7 @@ +SOURCE_DIR +---------- + +.. versionadded:: 3.7 + +This read-only directory property reports absolute path to the source +directory on which it is read. diff --git a/Help/prop_dir/SUBDIRECTORIES.rst b/Help/prop_dir/SUBDIRECTORIES.rst new file mode 100644 index 0000000..71ea496 --- /dev/null +++ b/Help/prop_dir/SUBDIRECTORIES.rst @@ -0,0 +1,17 @@ +SUBDIRECTORIES +-------------- + +.. versionadded:: 3.7 + +This read-only directory property contains a +: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 +``DIRECTORY`` option. + +.. note:: + + The :command:`subdirs` command does not process its arguments until + after the calling directory is fully processed. Therefore looking + up this property in the current directory will not see them. diff --git a/Help/prop_dir/TESTS.rst b/Help/prop_dir/TESTS.rst new file mode 100644 index 0000000..294be17 --- /dev/null +++ b/Help/prop_dir/TESTS.rst @@ -0,0 +1,10 @@ +TESTS +----- + +.. versionadded:: 3.12 + +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 new file mode 100644 index 0000000..31b2382 --- /dev/null +++ b/Help/prop_dir/TEST_INCLUDE_FILE.rst @@ -0,0 +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 +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 0000000..f9a66f4 --- /dev/null +++ b/Help/prop_dir/TEST_INCLUDE_FILES.rst @@ -0,0 +1,9 @@ +TEST_INCLUDE_FILES +------------------ + +.. versionadded:: 3.10 + +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/VARIABLES.rst b/Help/prop_dir/VARIABLES.rst new file mode 100644 index 0000000..0328295 --- /dev/null +++ b/Help/prop_dir/VARIABLES.rst @@ -0,0 +1,7 @@ +VARIABLES +--------- + +List of variables defined in the current directory. + +This read-only property specifies the list of CMake variables +currently defined. It is intended for debugging purposes. diff --git a/Help/prop_dir/VS_GLOBAL_SECTION_POST_section.rst b/Help/prop_dir/VS_GLOBAL_SECTION_POST_section.rst new file mode 100644 index 0000000..b65db99 --- /dev/null +++ b/Help/prop_dir/VS_GLOBAL_SECTION_POST_section.rst @@ -0,0 +1,31 @@ +VS_GLOBAL_SECTION_POST_<section> +-------------------------------- + +Specify a postSolution global section in Visual Studio. + +Setting a property like this generates an entry of the following form +in the solution file: + +:: + + GlobalSection(<section>) = postSolution + <contents based on property value> + EndGlobalSection + +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 9 and above; it is ignored +on other generators. The property only applies when set on a +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 +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 +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 new file mode 100644 index 0000000..7f8bf61 --- /dev/null +++ b/Help/prop_dir/VS_GLOBAL_SECTION_PRE_section.rst @@ -0,0 +1,22 @@ +VS_GLOBAL_SECTION_PRE_<section> +------------------------------- + +Specify a preSolution global section in Visual Studio. + +Setting a property like this generates an entry of the following form +in the solution file: + +:: + + GlobalSection(<section>) = preSolution + <contents based on property value> + EndGlobalSection + +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 9 and above; it is ignored +on other generators. The property only applies when set on a +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 new file mode 100644 index 0000000..8a0c3c8 --- /dev/null +++ b/Help/prop_dir/VS_STARTUP_PROJECT.rst @@ -0,0 +1,20 @@ +VS_STARTUP_PROJECT +------------------ + +.. versionadded:: 3.6 + +Specify the default startup project in a Visual Studio solution. + +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 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 +file causing Visual Studio to make it the startup project if the +solution has never been opened before. + +If this property is not specified, then the ``ALL_BUILD`` project +will be the default. diff --git a/Help/prop_gbl/ALLOW_DUPLICATE_CUSTOM_TARGETS.rst b/Help/prop_gbl/ALLOW_DUPLICATE_CUSTOM_TARGETS.rst new file mode 100644 index 0000000..19775ff --- /dev/null +++ b/Help/prop_gbl/ALLOW_DUPLICATE_CUSTOM_TARGETS.rst @@ -0,0 +1,21 @@ +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 :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 :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/AUTOGEN_SOURCE_GROUP.rst b/Help/prop_gbl/AUTOGEN_SOURCE_GROUP.rst new file mode 100644 index 0000000..07c732b --- /dev/null +++ b/Help/prop_gbl/AUTOGEN_SOURCE_GROUP.rst @@ -0,0 +1,18 @@ +AUTOGEN_SOURCE_GROUP +-------------------- + +.. versionadded:: 3.9 + +Name of the :command:`source_group` for :prop_tgt:`AUTOMOC`, +:prop_tgt:`AUTORCC` and :prop_tgt:`AUTOUIC` generated files. + +Files generated by :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTORCC` and +:prop_tgt:`AUTOUIC` are not always known at configure time and therefore can't +be passed to :command:`source_group`. +:prop_gbl:`AUTOGEN_SOURCE_GROUP` can be used instead to generate or select +a source group for :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTORCC` and +:prop_tgt:`AUTOUIC` generated files. + +For :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTORCC` and :prop_tgt:`AUTOUIC` specific +overrides see :prop_gbl:`AUTOMOC_SOURCE_GROUP`, :prop_gbl:`AUTORCC_SOURCE_GROUP` +and :prop_gbl:`AUTOUIC_SOURCE_GROUP` respectively. diff --git a/Help/prop_gbl/AUTOGEN_TARGETS_FOLDER.rst b/Help/prop_gbl/AUTOGEN_TARGETS_FOLDER.rst new file mode 100644 index 0000000..0b747b2 --- /dev/null +++ b/Help/prop_gbl/AUTOGEN_TARGETS_FOLDER.rst @@ -0,0 +1,9 @@ +AUTOGEN_TARGETS_FOLDER +---------------------- + +Name of :prop_tgt:`FOLDER` for ``*_autogen`` targets that are added +automatically by CMake for targets for which :prop_tgt:`AUTOMOC` is enabled. + +If not set, CMake uses the :prop_tgt:`FOLDER` property of the parent target as a +default value for this property. See also the documentation for the +:prop_tgt:`FOLDER` target property and the :prop_tgt:`AUTOMOC` target property. diff --git a/Help/prop_gbl/AUTOMOC_SOURCE_GROUP.rst b/Help/prop_gbl/AUTOMOC_SOURCE_GROUP.rst new file mode 100644 index 0000000..a266fde --- /dev/null +++ b/Help/prop_gbl/AUTOMOC_SOURCE_GROUP.rst @@ -0,0 +1,9 @@ +AUTOMOC_SOURCE_GROUP +-------------------- + +.. versionadded:: 3.9 + +Name of the :command:`source_group` for :prop_tgt:`AUTOMOC` generated files. + +When set this is used instead of :prop_gbl:`AUTOGEN_SOURCE_GROUP` for +files generated by :prop_tgt:`AUTOMOC`. diff --git a/Help/prop_gbl/AUTOMOC_TARGETS_FOLDER.rst b/Help/prop_gbl/AUTOMOC_TARGETS_FOLDER.rst new file mode 100644 index 0000000..17666e4 --- /dev/null +++ b/Help/prop_gbl/AUTOMOC_TARGETS_FOLDER.rst @@ -0,0 +1,11 @@ +AUTOMOC_TARGETS_FOLDER +---------------------- + +Name of :prop_tgt:`FOLDER` for ``*_autogen`` targets that are added automatically by +CMake for targets for which :prop_tgt:`AUTOMOC` is enabled. + +This property is obsolete. Use :prop_gbl:`AUTOGEN_TARGETS_FOLDER` instead. + +If not set, CMake uses the :prop_tgt:`FOLDER` property of the parent target as a +default value for this property. See also the documentation for the +:prop_tgt:`FOLDER` target property and the :prop_tgt:`AUTOMOC` target property. diff --git a/Help/prop_gbl/AUTORCC_SOURCE_GROUP.rst b/Help/prop_gbl/AUTORCC_SOURCE_GROUP.rst new file mode 100644 index 0000000..54ebabb --- /dev/null +++ b/Help/prop_gbl/AUTORCC_SOURCE_GROUP.rst @@ -0,0 +1,9 @@ +AUTORCC_SOURCE_GROUP +-------------------- + +.. versionadded:: 3.9 + +Name of the :command:`source_group` for :prop_tgt:`AUTORCC` generated files. + +When set this is used instead of :prop_gbl:`AUTOGEN_SOURCE_GROUP` for +files generated by :prop_tgt:`AUTORCC`. diff --git a/Help/prop_gbl/AUTOUIC_SOURCE_GROUP.rst b/Help/prop_gbl/AUTOUIC_SOURCE_GROUP.rst new file mode 100644 index 0000000..79ebfe0 --- /dev/null +++ b/Help/prop_gbl/AUTOUIC_SOURCE_GROUP.rst @@ -0,0 +1,9 @@ +AUTOUIC_SOURCE_GROUP +-------------------- + +.. versionadded:: 3.21 + +Name of the :command:`source_group` for :prop_tgt:`AUTOUIC` generated files. + +When set this is used instead of :prop_gbl:`AUTOGEN_SOURCE_GROUP` for +files generated by :prop_tgt:`AUTOUIC`. diff --git a/Help/prop_gbl/CMAKE_CUDA_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_CUDA_KNOWN_FEATURES.rst new file mode 100644 index 0000000..6bbb870 --- /dev/null +++ b/Help/prop_gbl/CMAKE_CUDA_KNOWN_FEATURES.rst @@ -0,0 +1,35 @@ +CMAKE_CUDA_KNOWN_FEATURES +------------------------- + +.. versionadded:: 3.17 + +List of CUDA features known to this version of CMake. + +The features listed in this global property may be known to be available to the +CUDA compiler. If the feature is available with the C++ compiler, it will +be listed in the :variable:`CMAKE_CUDA_COMPILE_FEATURES` variable. + +The features listed here may be used with the :command:`target_compile_features` +command. See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. + + +The features known to this version of CMake are: + +``cuda_std_03`` + Compiler mode is at least CUDA/C++ 03. + +``cuda_std_11`` + Compiler mode is at least CUDA/C++ 11. + +``cuda_std_14`` + Compiler mode is at least CUDA/C++ 14. + +``cuda_std_17`` + Compiler mode is at least CUDA/C++ 17. + +``cuda_std_20`` + Compiler mode is at least CUDA/C++ 20. + +``cuda_std_23`` + Compiler mode is at least CUDA/C++ 23. diff --git a/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst new file mode 100644 index 0000000..73c0b34 --- /dev/null +++ b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst @@ -0,0 +1,354 @@ +CMAKE_CXX_KNOWN_FEATURES +------------------------ + +.. versionadded:: 3.1 + +List of C++ features known to this version of CMake. + +The features listed in this global property may be known to be available to the +C++ compiler. If the feature is available with the C++ compiler, it will +be listed in the :variable:`CMAKE_CXX_COMPILE_FEATURES` variable. + +The features listed here may be used with the :command:`target_compile_features` +command. See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. + +The features known to this version of CMake are listed below. + +High level meta features indicating C++ standard support +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following meta features indicate general support for the associated +language standard. It reflects the language support claimed by the compiler, +but it does not necessarily imply complete conformance to that standard. + +``cxx_std_98`` + Compiler mode is at least C++ 98. + +``cxx_std_11`` + Compiler mode is at least C++ 11. + +``cxx_std_14`` + Compiler mode is at least C++ 14. + +``cxx_std_17`` + Compiler mode is at least C++ 17. + +``cxx_std_20`` + Compiler mode is at least C++ 20. + +``cxx_std_23`` + Compiler mode is at least C++ 23. + +Low level individual compile features +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For C++ 11 and C++ 14, compilers were sometimes slow to implement certain +language features. CMake provided some individual compile features to help +projects determine whether specific features were available. These individual +features are now less relevant and projects should generally prefer to use the +high level meta features instead. Individual compile features are not provided +for C++ 17 or later. + +See the :manual:`cmake-compile-features(7)` manual for further discussion of +the use of individual compile features. + +Individual features from C++ 98 +""""""""""""""""""""""""""""""" + +``cxx_template_template_parameters`` + Template template parameters, as defined in ``ISO/IEC 14882:1998``. + + +Individual features from C++ 11 +""""""""""""""""""""""""""""""" + +``cxx_alias_templates`` + Template aliases, as defined in N2258_. + + .. _N2258: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2258.pdf + +``cxx_alignas`` + Alignment control ``alignas``, as defined in N2341_. + + .. _N2341: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2341.pdf + +``cxx_alignof`` + Alignment control ``alignof``, as defined in N2341_. + + .. _N2341: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2341.pdf + +``cxx_attributes`` + Generic attributes, as defined in N2761_. + + .. _N2761: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2761.pdf + +``cxx_auto_type`` + Automatic type deduction, as defined in N1984_. + + .. _N1984: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1984.pdf + +``cxx_constexpr`` + Constant expressions, as defined in N2235_. + + .. _N2235: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2235.pdf + + +``cxx_decltype_incomplete_return_types`` + Decltype on incomplete return types, as defined in N3276_. + + .. _N3276 : http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2011/n3276.pdf + +``cxx_decltype`` + Decltype, as defined in N2343_. + + .. _N2343: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2343.pdf + +``cxx_default_function_template_args`` + Default template arguments for function templates, as defined in DR226_ + + .. _DR226: http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#226 + +``cxx_defaulted_functions`` + Defaulted functions, as defined in N2346_. + + .. _N2346: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm + +``cxx_defaulted_move_initializers`` + Defaulted move initializers, as defined in N3053_. + + .. _N3053: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3053.html + +``cxx_delegating_constructors`` + Delegating constructors, as defined in N1986_. + + .. _N1986: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1986.pdf + +``cxx_deleted_functions`` + Deleted functions, as defined in N2346_. + + .. _N2346: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm + +``cxx_enum_forward_declarations`` + Enum forward declarations, as defined in N2764_. + + .. _N2764: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2764.pdf + +``cxx_explicit_conversions`` + Explicit conversion operators, as defined in N2437_. + + .. _N2437: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2437.pdf + +``cxx_extended_friend_declarations`` + Extended friend declarations, as defined in N1791_. + + .. _N1791: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1791.pdf + +``cxx_extern_templates`` + Extern templates, as defined in N1987_. + + .. _N1987: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1987.htm + +``cxx_final`` + Override control ``final`` keyword, as defined in N2928_, N3206_ and N3272_. + + .. _N2928: http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2009/n2928.htm + .. _N3206: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3206.htm + .. _N3272: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2011/n3272.htm + +``cxx_func_identifier`` + Predefined ``__func__`` identifier, as defined in N2340_. + + .. _N2340: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2340.htm + +``cxx_generalized_initializers`` + Initializer lists, as defined in N2672_. + + .. _N2672: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2672.htm + +``cxx_inheriting_constructors`` + Inheriting constructors, as defined in N2540_. + + .. _N2540: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2540.htm + +``cxx_inline_namespaces`` + Inline namespaces, as defined in N2535_. + + .. _N2535: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2535.htm + +``cxx_lambdas`` + Lambda functions, as defined in N2927_. + + .. _N2927: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2009/n2927.pdf + +``cxx_local_type_template_args`` + Local and unnamed types as template arguments, as defined in N2657_. + + .. _N2657: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2657.htm + +``cxx_long_long_type`` + ``long long`` type, as defined in N1811_. + + .. _N1811: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1811.pdf + +``cxx_noexcept`` + Exception specifications, as defined in N3050_. + + .. _N3050: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3050.html + +``cxx_nonstatic_member_init`` + Non-static data member initialization, as defined in N2756_. + + .. _N2756: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2756.htm + +``cxx_nullptr`` + Null pointer, as defined in N2431_. + + .. _N2431: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2431.pdf + +``cxx_override`` + Override control ``override`` keyword, as defined in N2928_, N3206_ + and N3272_. + + .. _N2928: http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2009/n2928.htm + .. _N3206: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3206.htm + .. _N3272: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2011/n3272.htm + +``cxx_range_for`` + Range-based for, as defined in N2930_. + + .. _N2930: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2009/n2930.html + +``cxx_raw_string_literals`` + Raw string literals, as defined in N2442_. + + .. _N2442: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2442.htm + +``cxx_reference_qualified_functions`` + Reference qualified functions, as defined in N2439_. + + .. _N2439: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2439.htm + +``cxx_right_angle_brackets`` + Right angle bracket parsing, as defined in N1757_. + + .. _N1757: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1757.html + +``cxx_rvalue_references`` + R-value references, as defined in N2118_. + + .. _N2118: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2118.html + +``cxx_sizeof_member`` + Size of non-static data members, as defined in N2253_. + + .. _N2253: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2253.html + +``cxx_static_assert`` + Static assert, as defined in N1720_. + + .. _N1720: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2004/n1720.html + +``cxx_strong_enums`` + Strongly typed enums, as defined in N2347_. + + .. _N2347: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2347.pdf + +``cxx_thread_local`` + Thread-local variables, as defined in N2659_. + + .. _N2659: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2659.htm + +``cxx_trailing_return_types`` + Automatic function return type, as defined in N2541_. + + .. _N2541: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2541.htm + +``cxx_unicode_literals`` + Unicode string literals, as defined in N2442_. + + .. _N2442: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2442.htm + +``cxx_uniform_initialization`` + Uniform initialization, as defined in N2640_. + + .. _N2640: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2640.pdf + +``cxx_unrestricted_unions`` + Unrestricted unions, as defined in N2544_. + + .. _N2544: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2544.pdf + +``cxx_user_literals`` + User-defined literals, as defined in N2765_. + + .. _N2765: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2765.pdf + +``cxx_variadic_macros`` + Variadic macros, as defined in N1653_. + + .. _N1653: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2004/n1653.htm + +``cxx_variadic_templates`` + Variadic templates, as defined in N2242_. + + .. _N2242: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2242.pdf + + +Individual features from C++ 14 +""""""""""""""""""""""""""""""" + +``cxx_aggregate_default_initializers`` + Aggregate default initializers, as defined in N3605_. + + .. _N3605: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3605.html + +``cxx_attribute_deprecated`` + ``[[deprecated]]`` attribute, as defined in N3760_. + + .. _N3760: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3760.html + +``cxx_binary_literals`` + Binary literals, as defined in N3472_. + + .. _N3472: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3472.pdf + +``cxx_contextual_conversions`` + Contextual conversions, as defined in N3323_. + + .. _N3323: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3323.pdf + +``cxx_decltype_auto`` + ``decltype(auto)`` semantics, as defined in N3638_. + + .. _N3638: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3638.html + +``cxx_digit_separators`` + Digit separators, as defined in N3781_. + + .. _N3781: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3781.pdf + +``cxx_generic_lambdas`` + Generic lambdas, as defined in N3649_. + + .. _N3649: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3649.html + +``cxx_lambda_init_captures`` + Initialized lambda captures, as defined in N3648_. + + .. _N3648: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3648.html + +``cxx_relaxed_constexpr`` + Relaxed constexpr, as defined in N3652_. + + .. _N3652: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3652.html + +``cxx_return_type_deduction`` + Return type deduction on normal functions, as defined in N3386_. + + .. _N3386: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3386.html + +``cxx_variable_templates`` + Variable templates, as defined in N3651_. + + .. _N3651: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3651.pdf diff --git a/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst new file mode 100644 index 0000000..2bd0feb --- /dev/null +++ b/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst @@ -0,0 +1,43 @@ +CMAKE_C_KNOWN_FEATURES +---------------------- + +.. versionadded:: 3.1 + +List of C features known to this version of CMake. + +The features listed in this global property may be known to be available to the +C compiler. If the feature is available with the C compiler, it will +be listed in the :variable:`CMAKE_C_COMPILE_FEATURES` variable. + +The features listed here may be used with the :command:`target_compile_features` +command. See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. + +The features known to this version of CMake are: + +``c_std_90`` + Compiler mode is at least C 90. + +``c_std_99`` + Compiler mode is at least C 99. + +``c_std_11`` + Compiler mode is at least C 11. + +``c_std_17`` + Compiler mode is at least C 17. + +``c_std_23`` + Compiler mode is at least C 23. + +``c_function_prototypes`` + Function prototypes, as defined in ``ISO/IEC 9899:1990``. + +``c_restrict`` + ``restrict`` keyword, as defined in ``ISO/IEC 9899:1999``. + +``c_static_assert`` + Static assert, as defined in ``ISO/IEC 9899:2011``. + +``c_variadic_macros`` + Variadic macros, as defined in ``ISO/IEC 9899:1999``. diff --git a/Help/prop_gbl/CMAKE_ROLE.rst b/Help/prop_gbl/CMAKE_ROLE.rst new file mode 100644 index 0000000..3f4492f --- /dev/null +++ b/Help/prop_gbl/CMAKE_ROLE.rst @@ -0,0 +1,22 @@ +CMAKE_ROLE +---------- + +.. versionadded:: 3.14 + +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 new file mode 100644 index 0000000..fec6fda --- /dev/null +++ b/Help/prop_gbl/DEBUG_CONFIGURATIONS.rst @@ -0,0 +1,13 @@ +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 :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 :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 new file mode 100644 index 0000000..882bbfa --- /dev/null +++ b/Help/prop_gbl/DISABLED_FEATURES.rst @@ -0,0 +1,11 @@ +DISABLED_FEATURES +----------------- + +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 +this list. This property is used by the macros in +``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 0000000..2f110a7 --- /dev/null +++ b/Help/prop_gbl/ECLIPSE_EXTRA_CPROJECT_CONTENTS.rst @@ -0,0 +1,14 @@ +ECLIPSE_EXTRA_CPROJECT_CONTENTS +------------------------------- + +.. versionadded:: 3.12 + +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 new file mode 100644 index 0000000..a46575f --- /dev/null +++ b/Help/prop_gbl/ECLIPSE_EXTRA_NATURES.rst @@ -0,0 +1,10 @@ +ECLIPSE_EXTRA_NATURES +--------------------- + +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 new file mode 100644 index 0000000..acbb3d0 --- /dev/null +++ b/Help/prop_gbl/ENABLED_FEATURES.rst @@ -0,0 +1,11 @@ +ENABLED_FEATURES +---------------- + +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 +this list. This property is used by the macros in +``FeatureSummary.cmake``. diff --git a/Help/prop_gbl/ENABLED_LANGUAGES.rst b/Help/prop_gbl/ENABLED_LANGUAGES.rst new file mode 100644 index 0000000..43e3c09 --- /dev/null +++ b/Help/prop_gbl/ENABLED_LANGUAGES.rst @@ -0,0 +1,6 @@ +ENABLED_LANGUAGES +----------------- + +Read-only property that contains the list of currently enabled languages + +Set to list of currently enabled languages. diff --git a/Help/prop_gbl/FIND_LIBRARY_USE_LIB32_PATHS.rst b/Help/prop_gbl/FIND_LIBRARY_USE_LIB32_PATHS.rst new file mode 100644 index 0000000..f6cad66 --- /dev/null +++ b/Help/prop_gbl/FIND_LIBRARY_USE_LIB32_PATHS.rst @@ -0,0 +1,14 @@ +FIND_LIBRARY_USE_LIB32_PATHS +---------------------------- + +.. versionadded:: 3.7 + +Whether the :command:`find_library` command should automatically search +``lib32`` directories. + +``FIND_LIBRARY_USE_LIB32_PATHS`` is a boolean specifying whether the +:command:`find_library` command should automatically search the ``lib32`` +variant of directories called ``lib`` in the search path when building 32-bit +binaries. + +See also the :variable:`CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX` variable. diff --git a/Help/prop_gbl/FIND_LIBRARY_USE_LIB64_PATHS.rst b/Help/prop_gbl/FIND_LIBRARY_USE_LIB64_PATHS.rst new file mode 100644 index 0000000..ed343ba --- /dev/null +++ b/Help/prop_gbl/FIND_LIBRARY_USE_LIB64_PATHS.rst @@ -0,0 +1,12 @@ +FIND_LIBRARY_USE_LIB64_PATHS +---------------------------- + +Whether :command:`find_library` should automatically search lib64 +directories. + +FIND_LIBRARY_USE_LIB64_PATHS is a boolean specifying whether the +:command:`find_library` command should automatically search the lib64 +variant of directories called lib in the search path when building +64-bit binaries. + +See also the :variable:`CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX` variable. diff --git a/Help/prop_gbl/FIND_LIBRARY_USE_LIBX32_PATHS.rst b/Help/prop_gbl/FIND_LIBRARY_USE_LIBX32_PATHS.rst new file mode 100644 index 0000000..851f859 --- /dev/null +++ b/Help/prop_gbl/FIND_LIBRARY_USE_LIBX32_PATHS.rst @@ -0,0 +1,14 @@ +FIND_LIBRARY_USE_LIBX32_PATHS +----------------------------- + +.. versionadded:: 3.9 + +Whether the :command:`find_library` command should automatically search +``libx32`` directories. + +``FIND_LIBRARY_USE_LIBX32_PATHS`` is a boolean specifying whether the +:command:`find_library` command should automatically search the ``libx32`` +variant of directories called ``lib`` in the search path when building +x32-abi binaries. + +See also the :variable:`CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX` variable. diff --git a/Help/prop_gbl/FIND_LIBRARY_USE_OPENBSD_VERSIONING.rst b/Help/prop_gbl/FIND_LIBRARY_USE_OPENBSD_VERSIONING.rst new file mode 100644 index 0000000..beb94ac --- /dev/null +++ b/Help/prop_gbl/FIND_LIBRARY_USE_OPENBSD_VERSIONING.rst @@ -0,0 +1,10 @@ +FIND_LIBRARY_USE_OPENBSD_VERSIONING +----------------------------------- + +Whether :command:`find_library` should find OpenBSD-style shared +libraries. + +This property is a boolean specifying whether the +:command:`find_library` command should find shared libraries with +OpenBSD-style versioned extension: ".so.<major>.<minor>". The +property is set to true on OpenBSD and false on other platforms. diff --git a/Help/prop_gbl/GENERATOR_IS_MULTI_CONFIG.rst b/Help/prop_gbl/GENERATOR_IS_MULTI_CONFIG.rst new file mode 100644 index 0000000..761a1dd --- /dev/null +++ b/Help/prop_gbl/GENERATOR_IS_MULTI_CONFIG.rst @@ -0,0 +1,15 @@ +GENERATOR_IS_MULTI_CONFIG +------------------------- + +.. versionadded:: 3.9 + +Read-only property that is true on multi-configuration generators. + +True when using a multi-configuration generator such as: + +* :generator:`Ninja Multi-Config` +* :ref:`Visual Studio Generators` +* :generator:`Xcode` + +Multi-config generators use :variable:`CMAKE_CONFIGURATION_TYPES` +as the set of configurations and ignore :variable:`CMAKE_BUILD_TYPE`. diff --git a/Help/prop_gbl/GLOBAL_DEPENDS_DEBUG_MODE.rst b/Help/prop_gbl/GLOBAL_DEPENDS_DEBUG_MODE.rst new file mode 100644 index 0000000..832503b --- /dev/null +++ b/Help/prop_gbl/GLOBAL_DEPENDS_DEBUG_MODE.rst @@ -0,0 +1,8 @@ +GLOBAL_DEPENDS_DEBUG_MODE +------------------------- + +Enable global target dependency graph debug mode. + +CMake automatically analyzes the global inter-target dependency graph +at the beginning of native build system generation. This property +causes it to display details of its analysis to stderr. diff --git a/Help/prop_gbl/GLOBAL_DEPENDS_NO_CYCLES.rst b/Help/prop_gbl/GLOBAL_DEPENDS_NO_CYCLES.rst new file mode 100644 index 0000000..d10661e --- /dev/null +++ b/Help/prop_gbl/GLOBAL_DEPENDS_NO_CYCLES.rst @@ -0,0 +1,10 @@ +GLOBAL_DEPENDS_NO_CYCLES +------------------------ + +Disallow global target dependency graph cycles. + +CMake automatically analyzes the global inter-target dependency graph +at the beginning of native build system generation. It reports an +error if the dependency graph contains a cycle that does not consist +of all STATIC library targets. This property tells CMake to disallow +all cycles completely, even among static libraries. diff --git a/Help/prop_gbl/IN_TRY_COMPILE.rst b/Help/prop_gbl/IN_TRY_COMPILE.rst new file mode 100644 index 0000000..fd2d2e1 --- /dev/null +++ b/Help/prop_gbl/IN_TRY_COMPILE.rst @@ -0,0 +1,7 @@ +IN_TRY_COMPILE +-------------- + +Read-only property that is true during a try-compile configuration. + +True when building a project inside a :command:`try_compile` or +:command:`try_run` command. diff --git a/Help/prop_gbl/JOB_POOLS.rst b/Help/prop_gbl/JOB_POOLS.rst new file mode 100644 index 0000000..21da4662 --- /dev/null +++ b/Help/prop_gbl/JOB_POOLS.rst @@ -0,0 +1,31 @@ +JOB_POOLS +--------- + +Ninja only: List of available pools. + +A pool is a named integer property and defines the maximum number +of concurrent jobs which can be started by a rule assigned to the pool. +The :prop_gbl:`JOB_POOLS` property is a semicolon-separated list of +pairs using the syntax NAME=integer (without a space after the equality sign). + +For instance: + +.. code-block:: cmake + + set_property(GLOBAL PROPERTY JOB_POOLS two_jobs=2 ten_jobs=10) + +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/PACKAGES_FOUND.rst b/Help/prop_gbl/PACKAGES_FOUND.rst new file mode 100644 index 0000000..61cce1f --- /dev/null +++ b/Help/prop_gbl/PACKAGES_FOUND.rst @@ -0,0 +1,7 @@ +PACKAGES_FOUND +-------------- + +List of packages which were found during the CMake run. + +List of packages which were found during the CMake run. Whether a +package has been found is determined using the <NAME>_FOUND variables. diff --git a/Help/prop_gbl/PACKAGES_NOT_FOUND.rst b/Help/prop_gbl/PACKAGES_NOT_FOUND.rst new file mode 100644 index 0000000..ca3c5ba --- /dev/null +++ b/Help/prop_gbl/PACKAGES_NOT_FOUND.rst @@ -0,0 +1,7 @@ +PACKAGES_NOT_FOUND +------------------ + +List of packages which were not found during the CMake run. + +List of packages which were not found during the CMake run. Whether a +package has been found is determined using the <NAME>_FOUND variables. diff --git a/Help/prop_gbl/PREDEFINED_TARGETS_FOLDER.rst b/Help/prop_gbl/PREDEFINED_TARGETS_FOLDER.rst new file mode 100644 index 0000000..bf8c9a3 --- /dev/null +++ b/Help/prop_gbl/PREDEFINED_TARGETS_FOLDER.rst @@ -0,0 +1,9 @@ +PREDEFINED_TARGETS_FOLDER +------------------------- + +Name of FOLDER for targets that are added automatically by CMake. + +If not set, CMake uses "CMakePredefinedTargets" as a default value for +this property. Targets such as INSTALL, PACKAGE and RUN_TESTS will be +organized into this FOLDER. See also the documentation for the +:prop_tgt:`FOLDER` target property. diff --git a/Help/prop_gbl/REPORT_UNDEFINED_PROPERTIES.rst b/Help/prop_gbl/REPORT_UNDEFINED_PROPERTIES.rst new file mode 100644 index 0000000..29ba365 --- /dev/null +++ b/Help/prop_gbl/REPORT_UNDEFINED_PROPERTIES.rst @@ -0,0 +1,8 @@ +REPORT_UNDEFINED_PROPERTIES +--------------------------- + +If set, report any undefined properties to this file. + +If this property is set to a filename then when CMake runs it will +report any properties or variables that were accessed but not defined +into the filename specified in this property. diff --git a/Help/prop_gbl/RULE_LAUNCH_COMPILE.rst b/Help/prop_gbl/RULE_LAUNCH_COMPILE.rst new file mode 100644 index 0000000..e0df878 --- /dev/null +++ b/Help/prop_gbl/RULE_LAUNCH_COMPILE.rst @@ -0,0 +1,11 @@ +RULE_LAUNCH_COMPILE +------------------- + +Specify a launcher for compile rules. + +:ref:`Makefile Generators` and the :generator:`Ninja` generator prefix +compiler commands with the given launcher command line. +This is intended to allow launchers to intercept build problems +with high granularity. Other generators ignore this property +because their underlying build systems provide no hook to wrap +individual commands with a launcher. diff --git a/Help/prop_gbl/RULE_LAUNCH_CUSTOM.rst b/Help/prop_gbl/RULE_LAUNCH_CUSTOM.rst new file mode 100644 index 0000000..b20c59b --- /dev/null +++ b/Help/prop_gbl/RULE_LAUNCH_CUSTOM.rst @@ -0,0 +1,11 @@ +RULE_LAUNCH_CUSTOM +------------------ + +Specify a launcher for custom rules. + +:ref:`Makefile Generators` and the :generator:`Ninja` generator prefix +custom commands with the given launcher command line. +This is intended to allow launchers to intercept build problems +with high granularity. Other generators ignore this property +because their underlying build systems provide no hook to wrap +individual commands with a launcher. diff --git a/Help/prop_gbl/RULE_LAUNCH_LINK.rst b/Help/prop_gbl/RULE_LAUNCH_LINK.rst new file mode 100644 index 0000000..567bb68 --- /dev/null +++ b/Help/prop_gbl/RULE_LAUNCH_LINK.rst @@ -0,0 +1,11 @@ +RULE_LAUNCH_LINK +---------------- + +Specify a launcher for link rules. + +:ref:`Makefile Generators` and the :generator:`Ninja` generator prefix +link and archive commands with the given launcher command line. +This is intended to allow launchers to intercept build problems +with high granularity. Other generators ignore this property +because their underlying build systems provide no hook to wrap +individual commands with a launcher. diff --git a/Help/prop_gbl/RULE_MESSAGES.rst b/Help/prop_gbl/RULE_MESSAGES.rst new file mode 100644 index 0000000..a9734a7 --- /dev/null +++ b/Help/prop_gbl/RULE_MESSAGES.rst @@ -0,0 +1,13 @@ +RULE_MESSAGES +------------- + +Specify whether to report a message for each make rule. + +This property specifies whether Makefile generators should add a +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 :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/TARGET_ARCHIVES_MAY_BE_SHARED_LIBS.rst b/Help/prop_gbl/TARGET_ARCHIVES_MAY_BE_SHARED_LIBS.rst new file mode 100644 index 0000000..930feba --- /dev/null +++ b/Help/prop_gbl/TARGET_ARCHIVES_MAY_BE_SHARED_LIBS.rst @@ -0,0 +1,7 @@ +TARGET_ARCHIVES_MAY_BE_SHARED_LIBS +---------------------------------- + +Set if shared libraries may be named like archives. + +On AIX shared libraries may be named "lib<name>.a". This property is +set to true on such platforms. diff --git a/Help/prop_gbl/TARGET_MESSAGES.rst b/Help/prop_gbl/TARGET_MESSAGES.rst new file mode 100644 index 0000000..bb91772 --- /dev/null +++ b/Help/prop_gbl/TARGET_MESSAGES.rst @@ -0,0 +1,22 @@ +TARGET_MESSAGES +--------------- + +.. versionadded:: 3.4 + +Specify whether to report the completion of each target. + +This property specifies whether :ref:`Makefile Generators` should +add a progress message describing that each target has been completed. +If the property is not set the default is ``ON``. Set the property +to ``OFF`` to disable target completion messages. + +This option is intended to reduce build output when little or no +work needs to be done to bring the build tree up to date. + +If a ``CMAKE_TARGET_MESSAGES`` cache entry exists its value +initializes the value of this property. + +Non-Makefile generators currently ignore this property. + +See the counterpart property :prop_gbl:`RULE_MESSAGES` to disable +everything except for target completion messages. diff --git a/Help/prop_gbl/TARGET_SUPPORTS_SHARED_LIBS.rst b/Help/prop_gbl/TARGET_SUPPORTS_SHARED_LIBS.rst new file mode 100644 index 0000000..f6e89fb --- /dev/null +++ b/Help/prop_gbl/TARGET_SUPPORTS_SHARED_LIBS.rst @@ -0,0 +1,9 @@ +TARGET_SUPPORTS_SHARED_LIBS +--------------------------- + +Does the target platform support shared libraries. + +TARGET_SUPPORTS_SHARED_LIBS is a boolean specifying whether the target +platform supports shared libraries. Basically all current general +general purpose OS do so, the exception are usually embedded systems +with no or special OSs. diff --git a/Help/prop_gbl/USE_FOLDERS.rst b/Help/prop_gbl/USE_FOLDERS.rst new file mode 100644 index 0000000..5919723 --- /dev/null +++ b/Help/prop_gbl/USE_FOLDERS.rst @@ -0,0 +1,10 @@ +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 +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 :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 new file mode 100644 index 0000000..392b704 --- /dev/null +++ b/Help/prop_gbl/XCODE_EMIT_EFFECTIVE_PLATFORM_NAME.rst @@ -0,0 +1,27 @@ +XCODE_EMIT_EFFECTIVE_PLATFORM_NAME +---------------------------------- + +.. versionadded:: 3.8 + +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 :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 +- If unset (the default) it will only be emitted when the project was + configured for an embedded Xcode SDK like iOS, tvOS, watchOS or any + of the simulators. + +.. note:: + + When this behavior is enable for generated Xcode projects, the + ``EFFECTIVE_PLATFORM_NAME`` variable will leak into + :manual:`Generator expressions <cmake-generator-expressions(7)>` + like ``TARGET_FILE`` and will render those mostly unusable. diff --git a/Help/prop_inst/CPACK_DESKTOP_SHORTCUTS.rst b/Help/prop_inst/CPACK_DESKTOP_SHORTCUTS.rst new file mode 100644 index 0000000..55e9a20 --- /dev/null +++ b/Help/prop_inst/CPACK_DESKTOP_SHORTCUTS.rst @@ -0,0 +1,9 @@ +CPACK_DESKTOP_SHORTCUTS +----------------------- + +.. versionadded:: 3.3 + +Species a list of shortcut names that should be created on the `Desktop` +for this file. + +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 new file mode 100644 index 0000000..12eef9e --- /dev/null +++ b/Help/prop_inst/CPACK_NEVER_OVERWRITE.rst @@ -0,0 +1,8 @@ +CPACK_NEVER_OVERWRITE +--------------------- + +.. versionadded:: 3.1 + +Request that this file not be overwritten on install or reinstall. + +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 new file mode 100644 index 0000000..e89c552 --- /dev/null +++ b/Help/prop_inst/CPACK_PERMANENT.rst @@ -0,0 +1,8 @@ +CPACK_PERMANENT +--------------- + +.. versionadded:: 3.1 + +Request that this file not be removed on uninstall. + +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 new file mode 100644 index 0000000..e896acd --- /dev/null +++ b/Help/prop_inst/CPACK_STARTUP_SHORTCUTS.rst @@ -0,0 +1,9 @@ +CPACK_STARTUP_SHORTCUTS +----------------------- + +.. versionadded:: 3.3 + +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 :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 new file mode 100644 index 0000000..fb8807f --- /dev/null +++ b/Help/prop_inst/CPACK_START_MENU_SHORTCUTS.rst @@ -0,0 +1,9 @@ +CPACK_START_MENU_SHORTCUTS +-------------------------- + +.. versionadded:: 3.3 + +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 :cpack_gen:`CPack WIX Generator`. diff --git a/Help/prop_inst/CPACK_WIX_ACL.rst b/Help/prop_inst/CPACK_WIX_ACL.rst new file mode 100644 index 0000000..8b4fb5c --- /dev/null +++ b/Help/prop_inst/CPACK_WIX_ACL.rst @@ -0,0 +1,23 @@ +CPACK_WIX_ACL +------------- + +.. versionadded:: 3.1 + +Specifies access permissions for files or directories +installed by a WiX installer. + +The property can contain multiple list entries, +each of which has to match the following format. + +:: + + <user>[@<domain>]=<permission>[,<permission>] + +``<user>`` and ``<domain>`` specify the windows user and domain for which the +``<Permission>`` element should be generated. + +``<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/ABSTRACT.rst b/Help/prop_sf/ABSTRACT.rst new file mode 100644 index 0000000..339d115 --- /dev/null +++ b/Help/prop_sf/ABSTRACT.rst @@ -0,0 +1,9 @@ +ABSTRACT +-------- + +Is this source file an abstract class. + +A property on a source file that indicates if the source file +represents a class that is abstract. This only makes sense for +languages that have a notion of an abstract class and it is only used +by some tools that wrap classes into other languages. diff --git a/Help/prop_sf/AUTORCC_OPTIONS.rst b/Help/prop_sf/AUTORCC_OPTIONS.rst new file mode 100644 index 0000000..2bec033 --- /dev/null +++ b/Help/prop_sf/AUTORCC_OPTIONS.rst @@ -0,0 +1,22 @@ +AUTORCC_OPTIONS +--------------- + +Additional options for ``rcc`` when using :prop_tgt:`AUTORCC` + +This property holds additional command line options which will be used when +``rcc`` is executed during the build via :prop_tgt:`AUTORCC`, i.e. it is equivalent to the +optional ``OPTIONS`` argument of the :module:`qt4_add_resources() <FindQt4>` macro. + +By default it is empty. + +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 new file mode 100644 index 0000000..e2f47ec --- /dev/null +++ b/Help/prop_sf/AUTOUIC_OPTIONS.rst @@ -0,0 +1,23 @@ +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. + +By default it is empty. + +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 new file mode 100644 index 0000000..6317690 --- /dev/null +++ b/Help/prop_sf/COMPILE_DEFINITIONS.rst @@ -0,0 +1,29 @@ +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``. +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``). + +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 new file mode 100644 index 0000000..ec867b6 --- /dev/null +++ b/Help/prop_sf/COMPILE_DEFINITIONS_CONFIG.rst @@ -0,0 +1,10 @@ +COMPILE_DEFINITIONS_<CONFIG> +---------------------------- + +Ignored. See CMake Policy :policy:`CMP0043`. + +Per-configuration preprocessor definitions on a source file. + +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 new file mode 100644 index 0000000..c211b89 --- /dev/null +++ b/Help/prop_sf/COMPILE_FLAGS.rst @@ -0,0 +1,19 @@ +COMPILE_FLAGS +------------- + +Additional flags to be added when compiling this source file. + +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" +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 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 0000000..a694c3e --- /dev/null +++ b/Help/prop_sf/COMPILE_OPTIONS.rst @@ -0,0 +1,34 @@ +COMPILE_OPTIONS +--------------- + +.. versionadded:: 3.11 + +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. + +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. + +Usage example: + +.. code-block:: cmake + + set_source_files_properties(foo.cpp PROPERTIES COMPILE_OPTIONS "-Wno-unused-parameter;-Wno-missing-field-initializer") + +Related properties: + +* Prefer this property over :prop_sf:`COMPILE_FLAGS`. +* Use :prop_sf:`COMPILE_DEFINITIONS` to pass additional preprocessor definitions. +* Use :prop_sf:`INCLUDE_DIRECTORIES` to pass additional include directories. + +Related commands: + +* :command:`add_compile_options` for directory-wide settings +* :command:`target_compile_options` for target-specific settings diff --git a/Help/prop_sf/EXTERNAL_OBJECT.rst b/Help/prop_sf/EXTERNAL_OBJECT.rst new file mode 100644 index 0000000..351c04d --- /dev/null +++ b/Help/prop_sf/EXTERNAL_OBJECT.rst @@ -0,0 +1,8 @@ +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 +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 new file mode 100644 index 0000000..ef33926 --- /dev/null +++ b/Help/prop_sf/Fortran_FORMAT.rst @@ -0,0 +1,12 @@ +Fortran_FORMAT +-------------- + +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 :prop_tgt:`Fortran_FORMAT` +property if all source files in a target share the same format. + +.. note:: For some compilers, ``NAG``, ``PGI`` and ``Solaris Studio``, + setting this to ``OFF`` will have no effect. diff --git a/Help/prop_sf/Fortran_PREPROCESS.rst b/Help/prop_sf/Fortran_PREPROCESS.rst new file mode 100644 index 0000000..548a97b --- /dev/null +++ b/Help/prop_sf/Fortran_PREPROCESS.rst @@ -0,0 +1,19 @@ +Fortran_PREPROCESS +------------------ + +.. versionadded:: 3.18 + +Control whether the Fortran source file should be unconditionally preprocessed. + +If unset or empty, rely on the compiler to determine whether the file +should be preprocessed. If explicitly set to ``OFF`` then the file +does not need to be preprocessed. If explicitly set to ``ON``, then +the file does need to be preprocessed as part of the compilation step. + +When using the :generator:`Ninja` generator, all source files are +first preprocessed in order to generate module dependency +information. Setting this property to ``OFF`` will make ``Ninja`` +skip this step. + +Consider using the target-wide :prop_tgt:`Fortran_PREPROCESS` property +if all source files in a target need to be preprocessed. diff --git a/Help/prop_sf/GENERATED.rst b/Help/prop_sf/GENERATED.rst new file mode 100644 index 0000000..216dfe8 --- /dev/null +++ b/Help/prop_sf/GENERATED.rst @@ -0,0 +1,48 @@ +GENERATED +--------- + +Is this source file generated as part of the build or CMake process. + +.. versionchanged:: 3.20 + The GENERATED source file property is now visible in all directories. + +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. + +Any file that is + +- created by the execution of commands such as + :command:`add_custom_command` and :command:`file(GENERATE)` +- listed as one of the ``BYPRODUCTS`` of an :command:`add_custom_command` + or :command:`add_custom_target` command, or +- created by a CMake ``AUTOGEN`` operation such as :prop_tgt:`AUTOMOC`, + :prop_tgt:`AUTORCC`, or :prop_tgt:`AUTOUIC` + +will be marked with the ``GENERATED`` property. + +When a generated file created as the ``OUTPUT`` of 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. + +The :ref:`Makefile Generators` will remove ``GENERATED`` files during +``make clean``. + +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`, +:prop_tgt:`AUTORCC` or :prop_tgt:`AUTOUIC` functionality, the +:prop_gbl:`AUTOGEN_SOURCE_GROUP`, :prop_gbl:`AUTOMOC_SOURCE_GROUP`, +:prop_gbl:`AUTORCC_SOURCE_GROUP` and :prop_gbl:`AUTOUIC_SOURCE_GROUP` target +properties may influence where the generated sources are grouped in the project's +file lists. + +.. note:: + + Starting with CMake 3.20 the ``GENERATED`` source file property can be set + and retrieved from any directory scope. It is an all-or-nothing property. + It also can no longer be removed or unset if it was set to ``TRUE``. Policy + :policy:`CMP0118` was introduced to allow supporting the ``OLD`` behavior + for some time. diff --git a/Help/prop_sf/HEADER_FILE_ONLY.rst b/Help/prop_sf/HEADER_FILE_ONLY.rst new file mode 100644 index 0000000..71d62ae --- /dev/null +++ b/Help/prop_sf/HEADER_FILE_ONLY.rst @@ -0,0 +1,24 @@ +HEADER_FILE_ONLY +---------------- + +Is this source file only a header file. + +A property on a source file that indicates if the source file is a +header file with no associated implementation. This is set +automatically based on the file extension and is used by CMake to +determine if certain dependency information should be computed. + +By setting this property to ``ON``, you can disable compilation of +the given source file, even if it should be compiled because it is +part of the library's/executable's sources. + +This is useful if you have some source files which you somehow +pre-process, and then add these pre-processed sources via +:command:`add_library` or :command:`add_executable`. Normally, in IDE, +there would be no reference of the original sources, only of these +pre-processed sources. So by setting this property for all the original +source files to ``ON``, and then either calling :command:`add_library` +or :command:`add_executable` while passing both the pre-processed +sources and the original sources, or by using :command:`target_sources` +to add original source files will do exactly what would one expect, i.e. +the original source files would be visible in IDE, and will not be built. diff --git a/Help/prop_sf/INCLUDE_DIRECTORIES.rst b/Help/prop_sf/INCLUDE_DIRECTORIES.rst new file mode 100644 index 0000000..89ffd15 --- /dev/null +++ b/Help/prop_sf/INCLUDE_DIRECTORIES.rst @@ -0,0 +1,20 @@ +INCLUDE_DIRECTORIES +------------------- + +.. versionadded:: 3.11 + +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 new file mode 100644 index 0000000..a32f968 --- /dev/null +++ b/Help/prop_sf/KEEP_EXTENSION.rst @@ -0,0 +1,9 @@ +KEEP_EXTENSION +-------------- + +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. diff --git a/Help/prop_sf/LABELS.rst b/Help/prop_sf/LABELS.rst new file mode 100644 index 0000000..d0d2a0a --- /dev/null +++ b/Help/prop_sf/LABELS.rst @@ -0,0 +1,8 @@ +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 +currently specified. diff --git a/Help/prop_sf/LANGUAGE.rst b/Help/prop_sf/LANGUAGE.rst new file mode 100644 index 0000000..f14c176 --- /dev/null +++ b/Help/prop_sf/LANGUAGE.rst @@ -0,0 +1,17 @@ +LANGUAGE +-------- + +Specify the programming language in which a source file is written. + +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`` (i.e. C++), ``C``, +``CSharp``, ``CUDA``, ``Fortran``, ``ISPC``, 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. + +.. versionchanged:: 3.20 + Setting this property causes the source file to be compiled as the + specified language, using explicit flags if possible. Previously it + only caused the specified language's compiler to be used. + See policy :policy:`CMP0119`. diff --git a/Help/prop_sf/LOCATION.rst b/Help/prop_sf/LOCATION.rst new file mode 100644 index 0000000..252d680 --- /dev/null +++ b/Help/prop_sf/LOCATION.rst @@ -0,0 +1,7 @@ +LOCATION +-------- + +The full path to a source file. + +A read only property on a SOURCE FILE that contains the full path to +the source file. diff --git a/Help/prop_sf/MACOSX_PACKAGE_LOCATION.rst b/Help/prop_sf/MACOSX_PACKAGE_LOCATION.rst new file mode 100644 index 0000000..d185d91 --- /dev/null +++ b/Help/prop_sf/MACOSX_PACKAGE_LOCATION.rst @@ -0,0 +1,30 @@ +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 macOS +and iOS. + +Executable targets with the :prop_tgt:`MACOSX_BUNDLE` property set are +built as macOS or iOS application bundles on Apple platforms. Shared +library targets with the :prop_tgt:`FRAMEWORK` property set are built as +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 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 +specifying files meant for ``Headers``, ``PrivateHeaders``, or +``Resources`` directories. + +If the specified location is equal to ``Resources``, the resulting location +will be the same as if the :prop_tgt:`RESOURCE` property had been used. If +the specified location is a sub-folder of ``Resources``, it will be placed +into the respective sub-folder. Note: For iOS Apple uses a flat bundle layout +where no ``Resources`` folder exist. Therefore CMake strips the ``Resources`` +folder name from the specified location. diff --git a/Help/prop_sf/OBJECT_DEPENDS.rst b/Help/prop_sf/OBJECT_DEPENDS.rst new file mode 100644 index 0000000..aaff956 --- /dev/null +++ b/Help/prop_sf/OBJECT_DEPENDS.rst @@ -0,0 +1,21 @@ +OBJECT_DEPENDS +-------------- + +Additional files on which a compiled object file depends. + +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. +:ref:`Visual Studio Generators` and the :generator:`Xcode` generator +cannot implement such compilation dependencies. + +This property need not be used to specify the dependency of a source +file on a generated header file that it includes. Although the +property was originally introduced for this purpose, it is no longer +necessary. If the generated header file is created by a custom +command in the same target as the source file, the automatic +dependency scanning process will recognize the dependency. If the +generated header file is created by another target, an inter-target +dependency should be created with the :command:`add_dependencies` +command (if one does not already exist due to linking relationships). diff --git a/Help/prop_sf/OBJECT_OUTPUTS.rst b/Help/prop_sf/OBJECT_OUTPUTS.rst new file mode 100644 index 0000000..3e799ed --- /dev/null +++ b/Help/prop_sf/OBJECT_OUTPUTS.rst @@ -0,0 +1,12 @@ +OBJECT_OUTPUTS +-------------- + +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 the :generator:`Ninja` and :ref:`Makefile Generators` +and will be ignored on other generators. + +This property supports +:manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/prop_sf/SKIP_AUTOGEN.rst b/Help/prop_sf/SKIP_AUTOGEN.rst new file mode 100644 index 0000000..2173f59 --- /dev/null +++ b/Help/prop_sf/SKIP_AUTOGEN.rst @@ -0,0 +1,19 @@ +SKIP_AUTOGEN +------------ + +.. versionadded:: 3.8 + +Exclude the source file from :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTOUIC` and +:prop_tgt:`AUTORCC` processing (for Qt projects). + +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 new file mode 100644 index 0000000..e92cfe0 --- /dev/null +++ b/Help/prop_sf/SKIP_AUTOMOC.rst @@ -0,0 +1,17 @@ +SKIP_AUTOMOC +------------ + +.. versionadded:: 3.8 + +Exclude the source file from :prop_tgt:`AUTOMOC` processing (for Qt projects). + +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 new file mode 100644 index 0000000..2829c25 --- /dev/null +++ b/Help/prop_sf/SKIP_AUTORCC.rst @@ -0,0 +1,17 @@ +SKIP_AUTORCC +------------ + +.. versionadded:: 3.8 + +Exclude the source file from :prop_tgt:`AUTORCC` processing (for Qt projects). + +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 new file mode 100644 index 0000000..ae9725a --- /dev/null +++ b/Help/prop_sf/SKIP_AUTOUIC.rst @@ -0,0 +1,22 @@ +SKIP_AUTOUIC +------------ + +.. versionadded:: 3.8 + +Exclude the source file from :prop_tgt:`AUTOUIC` processing (for Qt projects). + +: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 0000000..660de3f --- /dev/null +++ b/Help/prop_sf/SKIP_PRECOMPILE_HEADERS.rst @@ -0,0 +1,15 @@ +SKIP_PRECOMPILE_HEADERS +----------------------- + +.. versionadded:: 3.16 + +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 0000000..ae526ac --- /dev/null +++ b/Help/prop_sf/SKIP_UNITY_BUILD_INCLUSION.rst @@ -0,0 +1,13 @@ +SKIP_UNITY_BUILD_INCLUSION +-------------------------- + +.. versionadded:: 3.16 + +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 new file mode 100644 index 0000000..8bebe30 --- /dev/null +++ b/Help/prop_sf/SYMBOLIC.rst @@ -0,0 +1,8 @@ +SYMBOLIC +-------- + +Is this just a name for a rule. + +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 0000000..a90c7eb --- /dev/null +++ b/Help/prop_sf/Swift_DEPENDENCIES_FILE.rst @@ -0,0 +1,7 @@ +Swift_DEPENDENCIES_FILE +----------------------- + +.. versionadded:: 3.15 + +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 0000000..47d5ac3 --- /dev/null +++ b/Help/prop_sf/Swift_DIAGNOSTICS_FILE.rst @@ -0,0 +1,6 @@ +Swift_DIAGNOSTICS_FILE +---------------------- + +.. versionadded:: 3.15 + +This property controls where the Swift diagnostics are serialized. diff --git a/Help/prop_sf/UNITY_GROUP.rst b/Help/prop_sf/UNITY_GROUP.rst new file mode 100644 index 0000000..9c18b70 --- /dev/null +++ b/Help/prop_sf/UNITY_GROUP.rst @@ -0,0 +1,7 @@ +UNITY_GROUP +----------- + +.. versionadded:: 3.18 + +This property controls which *bucket* the source will be part of when +the :prop_tgt:`UNITY_BUILD_MODE` is set to ``GROUP``. diff --git a/Help/prop_sf/VS_COPY_TO_OUT_DIR.rst b/Help/prop_sf/VS_COPY_TO_OUT_DIR.rst new file mode 100644 index 0000000..ebc3061 --- /dev/null +++ b/Help/prop_sf/VS_COPY_TO_OUT_DIR.rst @@ -0,0 +1,8 @@ +VS_COPY_TO_OUT_DIR +------------------ + +.. versionadded:: 3.8 + +Sets the ``<CopyToOutputDirectory>`` tag for a source file in a +Visual Studio project file. Valid values are ``Never``, ``Always`` +and ``PreserveNewest``. diff --git a/Help/prop_sf/VS_CSHARP_tagname.rst b/Help/prop_sf/VS_CSHARP_tagname.rst new file mode 100644 index 0000000..75720f8 --- /dev/null +++ b/Help/prop_sf/VS_CSHARP_tagname.rst @@ -0,0 +1,22 @@ +VS_CSHARP_<tagname> +------------------- + +.. versionadded:: 3.8 + +Visual Studio and CSharp source-file-specific configuration. + +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. + +Example usage: + +.. code-block:: cmake + + set_source_files_property(<filename> + PROPERTIES + VS_CSHARP_DependentUpon <other file> + VS_CSHARP_SubType "Form") diff --git a/Help/prop_sf/VS_DEPLOYMENT_CONTENT.rst b/Help/prop_sf/VS_DEPLOYMENT_CONTENT.rst new file mode 100644 index 0000000..ee49b27 --- /dev/null +++ b/Help/prop_sf/VS_DEPLOYMENT_CONTENT.rst @@ -0,0 +1,14 @@ +VS_DEPLOYMENT_CONTENT +--------------------- + +.. versionadded:: 3.1 + +Mark a source file as content for deployment with a Windows Phone or +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. +The ``.vcxproj`` file entry for the source file will be +marked either ``DeploymentContent`` or ``ExcludedFromBuild`` +for values ``1`` and ``0``, respectively. diff --git a/Help/prop_sf/VS_DEPLOYMENT_LOCATION.rst b/Help/prop_sf/VS_DEPLOYMENT_LOCATION.rst new file mode 100644 index 0000000..b170544 --- /dev/null +++ b/Help/prop_sf/VS_DEPLOYMENT_LOCATION.rst @@ -0,0 +1,11 @@ +VS_DEPLOYMENT_LOCATION +---------------------- + +.. versionadded:: 3.1 + +Specifies the deployment location for a content source file with a Windows +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 new file mode 100644 index 0000000..16c56bf --- /dev/null +++ b/Help/prop_sf/VS_INCLUDE_IN_VSIX.rst @@ -0,0 +1,8 @@ +VS_INCLUDE_IN_VSIX +------------------ + +.. versionadded:: 3.8 + +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_RESOURCE_GENERATOR.rst b/Help/prop_sf/VS_RESOURCE_GENERATOR.rst new file mode 100644 index 0000000..c5bb4f6 --- /dev/null +++ b/Help/prop_sf/VS_RESOURCE_GENERATOR.rst @@ -0,0 +1,10 @@ +VS_RESOURCE_GENERATOR +--------------------- + +.. versionadded:: 3.8 + +This property allows to specify the resource generator to be used +on this file. It defaults to ``PublicResXFileCodeGenerator`` if +not set. + +This property only applies to C# projects. diff --git a/Help/prop_sf/VS_SETTINGS.rst b/Help/prop_sf/VS_SETTINGS.rst new file mode 100644 index 0000000..322f5a6 --- /dev/null +++ b/Help/prop_sf/VS_SETTINGS.rst @@ -0,0 +1,20 @@ +VS_SETTINGS +----------- + +.. versionadded:: 3.18 + +Set any item metadata on a non-built file. + +Takes a list of ``Key=Value`` pairs. Tells the Visual Studio generator to set +``Key`` to ``Value`` as item metadata on the file. + +For example: + +.. code-block:: cmake + + set_property(SOURCE file.hlsl PROPERTY VS_SETTINGS "Key=Value" "Key2=Value2") + +will set ``Key`` to ``Value`` and ``Key2`` to ``Value2`` on the +``file.hlsl`` item as metadata. + +:manual:`Generator expressions <cmake-generator-expressions(7)>` are supported. 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 0000000..6fb6778 --- /dev/null +++ b/Help/prop_sf/VS_SHADER_DISABLE_OPTIMIZATIONS.rst @@ -0,0 +1,8 @@ +VS_SHADER_DISABLE_OPTIMIZATIONS +------------------------------- + +.. versionadded:: 3.11 + +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 0000000..9c8f9d7 --- /dev/null +++ b/Help/prop_sf/VS_SHADER_ENABLE_DEBUG.rst @@ -0,0 +1,8 @@ +VS_SHADER_ENABLE_DEBUG +---------------------- + +.. versionadded:: 3.11 + +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_ENTRYPOINT.rst b/Help/prop_sf/VS_SHADER_ENTRYPOINT.rst new file mode 100644 index 0000000..4b311ba --- /dev/null +++ b/Help/prop_sf/VS_SHADER_ENTRYPOINT.rst @@ -0,0 +1,7 @@ +VS_SHADER_ENTRYPOINT +-------------------- + +.. versionadded:: 3.1 + +Specifies the name of the entry point for the shader of a ``.hlsl`` source +file. diff --git a/Help/prop_sf/VS_SHADER_FLAGS.rst b/Help/prop_sf/VS_SHADER_FLAGS.rst new file mode 100644 index 0000000..07f8497 --- /dev/null +++ b/Help/prop_sf/VS_SHADER_FLAGS.rst @@ -0,0 +1,6 @@ +VS_SHADER_FLAGS +--------------- + +.. versionadded:: 3.2 + +Set additional Visual Studio shader flags of a ``.hlsl`` source file. diff --git a/Help/prop_sf/VS_SHADER_MODEL.rst b/Help/prop_sf/VS_SHADER_MODEL.rst new file mode 100644 index 0000000..072df89 --- /dev/null +++ b/Help/prop_sf/VS_SHADER_MODEL.rst @@ -0,0 +1,7 @@ +VS_SHADER_MODEL +--------------- + +.. versionadded:: 3.1 + +Specifies the shader model of a ``.hlsl`` source file. Some shader types can +only be used with recent shader models 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 0000000..3647a5e --- /dev/null +++ b/Help/prop_sf/VS_SHADER_OBJECT_FILE_NAME.rst @@ -0,0 +1,8 @@ +VS_SHADER_OBJECT_FILE_NAME +-------------------------- + +.. versionadded:: 3.12 + +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 0000000..4113a16 --- /dev/null +++ b/Help/prop_sf/VS_SHADER_OUTPUT_HEADER_FILE.rst @@ -0,0 +1,7 @@ +VS_SHADER_OUTPUT_HEADER_FILE +---------------------------- + +.. versionadded:: 3.10 + +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 new file mode 100644 index 0000000..3fb7e60 --- /dev/null +++ b/Help/prop_sf/VS_SHADER_TYPE.rst @@ -0,0 +1,6 @@ +VS_SHADER_TYPE +-------------- + +.. versionadded:: 3.1 + +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 0000000..3361b40 --- /dev/null +++ b/Help/prop_sf/VS_SHADER_VARIABLE_NAME.rst @@ -0,0 +1,7 @@ +VS_SHADER_VARIABLE_NAME +----------------------- + +.. versionadded:: 3.10 + +Set name of variable in header file containing object code of a ``.hlsl`` +source file. diff --git a/Help/prop_sf/VS_TOOL_OVERRIDE.rst b/Help/prop_sf/VS_TOOL_OVERRIDE.rst new file mode 100644 index 0000000..b2f4112 --- /dev/null +++ b/Help/prop_sf/VS_TOOL_OVERRIDE.rst @@ -0,0 +1,7 @@ +VS_TOOL_OVERRIDE +---------------- + +.. versionadded:: 3.7 + +Override the default Visual Studio tool that will be applied to the source file +with a new tool not based on the extension of the file. diff --git a/Help/prop_sf/VS_XAML_TYPE.rst b/Help/prop_sf/VS_XAML_TYPE.rst new file mode 100644 index 0000000..612b07b --- /dev/null +++ b/Help/prop_sf/VS_XAML_TYPE.rst @@ -0,0 +1,9 @@ +VS_XAML_TYPE +------------ + +.. versionadded:: 3.3 + +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 new file mode 100644 index 0000000..638ff03 --- /dev/null +++ b/Help/prop_sf/WRAP_EXCLUDE.rst @@ -0,0 +1,11 @@ +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, 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 new file mode 100644 index 0000000..5a50d7d --- /dev/null +++ b/Help/prop_sf/XCODE_EXPLICIT_FILE_TYPE.rst @@ -0,0 +1,10 @@ +XCODE_EXPLICIT_FILE_TYPE +------------------------ + +.. versionadded:: 3.1 + +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. + +See also :prop_sf:`XCODE_LAST_KNOWN_FILE_TYPE`. diff --git a/Help/prop_sf/XCODE_FILE_ATTRIBUTES.rst b/Help/prop_sf/XCODE_FILE_ATTRIBUTES.rst new file mode 100644 index 0000000..ba51e00 --- /dev/null +++ b/Help/prop_sf/XCODE_FILE_ATTRIBUTES.rst @@ -0,0 +1,13 @@ +XCODE_FILE_ATTRIBUTES +--------------------- + +.. versionadded:: 3.7 + +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:: + + set_source_files_properties(defs.mig + PROPERTIES + XCODE_FILE_ATTRIBUTES "Client;Server" + ) diff --git a/Help/prop_sf/XCODE_LAST_KNOWN_FILE_TYPE.rst b/Help/prop_sf/XCODE_LAST_KNOWN_FILE_TYPE.rst new file mode 100644 index 0000000..0b84e31 --- /dev/null +++ b/Help/prop_sf/XCODE_LAST_KNOWN_FILE_TYPE.rst @@ -0,0 +1,11 @@ +XCODE_LAST_KNOWN_FILE_TYPE +-------------------------- + +.. versionadded:: 3.1 + +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 +over this property if set. diff --git a/Help/prop_test/ATTACHED_FILES.rst b/Help/prop_test/ATTACHED_FILES.rst new file mode 100644 index 0000000..496d800 --- /dev/null +++ b/Help/prop_test/ATTACHED_FILES.rst @@ -0,0 +1,7 @@ +ATTACHED_FILES +-------------- + +Attach a list of files to a dashboard submission. + +Set this property to a list of files that will be encoded and +submitted to the dashboard as an addition to the test result. diff --git a/Help/prop_test/ATTACHED_FILES_ON_FAIL.rst b/Help/prop_test/ATTACHED_FILES_ON_FAIL.rst new file mode 100644 index 0000000..add54b2 --- /dev/null +++ b/Help/prop_test/ATTACHED_FILES_ON_FAIL.rst @@ -0,0 +1,7 @@ +ATTACHED_FILES_ON_FAIL +---------------------- + +Attach a list of files to a dashboard submission if the test fails. + +Same as :prop_test:`ATTACHED_FILES`, but these files will only be +included if the test does not pass. diff --git a/Help/prop_test/COST.rst b/Help/prop_test/COST.rst new file mode 100644 index 0000000..9300d7b --- /dev/null +++ b/Help/prop_test/COST.rst @@ -0,0 +1,14 @@ +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. + +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/DEPENDS.rst b/Help/prop_test/DEPENDS.rst new file mode 100644 index 0000000..5aa36b4 --- /dev/null +++ b/Help/prop_test/DEPENDS.rst @@ -0,0 +1,22 @@ +DEPENDS +------- + +Specifies that this test should only be run after the specified list of tests. + +Set this to a list of tests that must finish before this test is run. The +results of those tests are not considered, the dependency relationship is +purely for order of execution (i.e. it is really just a *run after* +relationship). Consider using test fixtures with setup tests if a dependency +with successful completion is required (see :prop_test:`FIXTURES_REQUIRED`). + +Examples +~~~~~~~~ + +.. code-block:: cmake + + add_test(NAME baseTest1 ...) + add_test(NAME baseTest2 ...) + add_test(NAME dependsTest12 ...) + + set_tests_properties(dependsTest12 PROPERTIES DEPENDS "baseTest1;baseTest2") + # dependsTest12 runs after baseTest1 and baseTest2, even if they fail diff --git a/Help/prop_test/DISABLED.rst b/Help/prop_test/DISABLED.rst new file mode 100644 index 0000000..cbf07a5 --- /dev/null +++ b/Help/prop_test/DISABLED.rst @@ -0,0 +1,17 @@ +DISABLED +-------- + +.. versionadded:: 3.9 + +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 +: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 +case requiring that fixture will still run. diff --git a/Help/prop_test/ENVIRONMENT.rst b/Help/prop_test/ENVIRONMENT.rst new file mode 100644 index 0000000..102c792 --- /dev/null +++ b/Help/prop_test/ENVIRONMENT.rst @@ -0,0 +1,9 @@ +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 +the test. The environment is restored to its previous state after the +test is done. diff --git a/Help/prop_test/FAIL_REGULAR_EXPRESSION.rst b/Help/prop_test/FAIL_REGULAR_EXPRESSION.rst new file mode 100644 index 0000000..facf902 --- /dev/null +++ b/Help/prop_test/FAIL_REGULAR_EXPRESSION.rst @@ -0,0 +1,15 @@ +FAIL_REGULAR_EXPRESSION +----------------------- + +If the output matches this regular expression the test will fail. + +If set, if the output matches one of specified regular expressions, +the test will fail. Example: + +.. code-block:: cmake + + set_tests_properties(mytest PROPERTIES + FAIL_REGULAR_EXPRESSION "[^a-z]Error;ERROR;Failed" + ) + +``FAIL_REGULAR_EXPRESSION`` expects a list of regular expressions. diff --git a/Help/prop_test/FIXTURES_CLEANUP.rst b/Help/prop_test/FIXTURES_CLEANUP.rst new file mode 100644 index 0000000..aa043da --- /dev/null +++ b/Help/prop_test/FIXTURES_CLEANUP.rst @@ -0,0 +1,49 @@ +FIXTURES_CLEANUP +---------------- + +.. versionadded:: 3.7 + +Specifies a list of fixtures for which the test is to be treated as a cleanup +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 +primary effects: + +- CTest will ensure the test executes after all other tests which list any of + the fixtures 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 cleanup test is not in + the set of tests to run, it will automatically be added if any tests in the + set require any fixture listed in ``FIXTURES_CLEANUP``. + +A cleanup test can have multiple fixtures listed in its ``FIXTURES_CLEANUP`` +property. It will execute only once for the whole CTest run, not once for each +fixture. A fixture can also have more than one cleanup test defined. If there +are multiple cleanup tests for a fixture, projects can control their order with +the usual :prop_test:`DEPENDS` test property if necessary. + +A cleanup test is allowed to require other fixtures, but not any fixture listed +in its ``FIXTURES_CLEANUP`` property. For example: + +.. code-block:: cmake + + # Ok: Dependent fixture is different to cleanup + set_tests_properties(cleanupFoo PROPERTIES + FIXTURES_CLEANUP Foo + FIXTURES_REQUIRED Bar + ) + + # Error: cannot require same fixture as cleanup + set_tests_properties(cleanupFoo PROPERTIES + FIXTURES_CLEANUP Foo + FIXTURES_REQUIRED Foo + ) + +Cleanup tests will execute even if setup or regular tests for that fixture fail +or are skipped. + +See :prop_test:`FIXTURES_REQUIRED` for a more complete discussion of how to use +test fixtures. diff --git a/Help/prop_test/FIXTURES_REQUIRED.rst b/Help/prop_test/FIXTURES_REQUIRED.rst new file mode 100644 index 0000000..d92808a --- /dev/null +++ b/Help/prop_test/FIXTURES_REQUIRED.rst @@ -0,0 +1,98 @@ +FIXTURES_REQUIRED +----------------- + +.. versionadded:: 3.7 + +Specifies a list of fixtures the test requires. Fixture names are case +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 +fixture will be executed first (once for the whole set of tests, not once per +test requiring the fixture). After all tests requiring a particular fixture +have completed, CTest will ensure all tests marked as cleanup tasks for that +fixture are then executed. Tests are marked as setup tasks with the +:prop_test:`FIXTURES_SETUP` property and as cleanup tasks with the +:prop_test:`FIXTURES_CLEANUP` property. If any of a fixture's setup tests fail, +all tests listing that fixture in their ``FIXTURES_REQUIRED`` property will not +be executed. The cleanup tests for the fixture will always be executed, even if +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. 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. +This can be exploited to implement setup or cleanup using multiple tests for a +single fixture to modularise setup or cleanup logic. + +The concept of a fixture is different to that of a resource specified by +:prop_test:`RESOURCE_LOCK`, but they may be used together. A fixture defines a +set of tests which share setup and cleanup requirements, whereas a resource +lock has the effect of ensuring a particular set of tests do not run in +parallel. Some situations may need both, such as setting up a database, +serialising test access to that database and deleting the database again at the +end. For such cases, tests would populate both ``FIXTURES_REQUIRED`` and +:prop_test:`RESOURCE_LOCK` to combine the two behaviours. Names used for +:prop_test:`RESOURCE_LOCK` have no relationship with names of fixtures, so note +that a resource lock does not imply a fixture and vice versa. + +Consider the following example which represents a database test scenario +similar to that mentioned above: + +.. code-block:: cmake + + add_test(NAME testsDone COMMAND emailResults) + add_test(NAME fooOnly COMMAND testFoo) + add_test(NAME dbOnly COMMAND testDb) + add_test(NAME dbWithFoo COMMAND testDbWithFoo) + add_test(NAME createDB COMMAND initDB) + add_test(NAME setupUsers COMMAND userCreation) + add_test(NAME cleanupDB COMMAND deleteDB) + add_test(NAME cleanupFoo COMMAND removeFoos) + + set_tests_properties(setupUsers PROPERTIES DEPENDS createDB) + + set_tests_properties(createDB PROPERTIES FIXTURES_SETUP DB) + set_tests_properties(setupUsers PROPERTIES FIXTURES_SETUP DB) + set_tests_properties(cleanupDB PROPERTIES FIXTURES_CLEANUP DB) + set_tests_properties(cleanupFoo PROPERTIES FIXTURES_CLEANUP Foo) + set_tests_properties(testsDone PROPERTIES FIXTURES_CLEANUP "DB;Foo") + + set_tests_properties(fooOnly PROPERTIES FIXTURES_REQUIRED Foo) + set_tests_properties(dbOnly PROPERTIES FIXTURES_REQUIRED DB) + set_tests_properties(dbWithFoo PROPERTIES FIXTURES_REQUIRED "DB;Foo") + + set_tests_properties(dbOnly dbWithFoo createDB setupUsers cleanupDB + PROPERTIES RESOURCE_LOCK DbAccess) + +Key points from this example: + +- Two fixtures are defined: ``DB`` and ``Foo``. Tests can require a single + fixture as ``fooOnly`` and ``dbOnly`` do, or they can depend on multiple + fixtures like ``dbWithFoo`` does. + +- A ``DEPENDS`` relationship is set up to ensure ``setupUsers`` happens after + ``createDB``, both of which are setup tests for the ``DB`` fixture and will + therefore be executed before the ``dbOnly`` and ``dbWithFoo`` tests + automatically. + +- No explicit ``DEPENDS`` relationships were needed to make the setup tests run + before or the cleanup tests run after the regular tests. + +- The ``Foo`` fixture has no setup tests defined, only a single cleanup test. + +- ``testsDone`` is a cleanup test for both the ``DB`` and ``Foo`` fixtures. + Therefore, it will only execute once regular tests for both fixtures have + finished (i.e. after ``fooOnly``, ``dbOnly`` and ``dbWithFoo``). No + ``DEPENDS`` relationship was specified for ``testsDone``, so it is free to + run before, after or concurrently with other cleanup tests for either + fixture. + +- The setup and cleanup tests never list the fixtures they are for in their own + ``FIXTURES_REQUIRED`` property, as that would result in a dependency on + themselves and be considered an error. diff --git a/Help/prop_test/FIXTURES_SETUP.rst b/Help/prop_test/FIXTURES_SETUP.rst new file mode 100644 index 0000000..04a09d8 --- /dev/null +++ b/Help/prop_test/FIXTURES_SETUP.rst @@ -0,0 +1,50 @@ +FIXTURES_SETUP +-------------- + +.. versionadded:: 3.7 + +Specifies a list of fixtures for which the test is to be treated as a setup +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 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 + the set of tests to run, it will automatically be added if any tests in the + set require any fixture listed in ``FIXTURES_SETUP``. + +A setup test can have multiple fixtures listed in its ``FIXTURES_SETUP`` +property. It will execute only once for the whole CTest run, not once for each +fixture. A fixture can also have more than one setup test defined. If there are +multiple setup tests for a fixture, projects can control their order with the +usual :prop_test:`DEPENDS` test property if necessary. + +A setup test is allowed to require other fixtures, but not any fixture listed +in its ``FIXTURES_SETUP`` property. For example: + +.. code-block:: cmake + + # Ok: dependent fixture is different to setup + set_tests_properties(setupFoo PROPERTIES + FIXTURES_SETUP Foo + FIXTURES_REQUIRED Bar + ) + + # Error: cannot require same fixture as setup + set_tests_properties(setupFoo PROPERTIES + FIXTURES_SETUP Foo + FIXTURES_REQUIRED Foo + ) + +If any of a fixture's setup tests fail, none of the tests listing that fixture +in its :prop_test:`FIXTURES_REQUIRED` property will be run. Cleanup tests will, +however, still be executed. + +See :prop_test:`FIXTURES_REQUIRED` for a more complete discussion of how to use +test fixtures. diff --git a/Help/prop_test/LABELS.rst b/Help/prop_test/LABELS.rst new file mode 100644 index 0000000..8d75570 --- /dev/null +++ b/Help/prop_test/LABELS.rst @@ -0,0 +1,6 @@ +LABELS +------ + +Specify a list of text labels associated with a test. + +The list is reported in dashboard submissions. diff --git a/Help/prop_test/MEASUREMENT.rst b/Help/prop_test/MEASUREMENT.rst new file mode 100644 index 0000000..de459ed --- /dev/null +++ b/Help/prop_test/MEASUREMENT.rst @@ -0,0 +1,8 @@ +MEASUREMENT +----------- + +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``. diff --git a/Help/prop_test/PASS_REGULAR_EXPRESSION.rst b/Help/prop_test/PASS_REGULAR_EXPRESSION.rst new file mode 100644 index 0000000..0cd6215 --- /dev/null +++ b/Help/prop_test/PASS_REGULAR_EXPRESSION.rst @@ -0,0 +1,16 @@ +PASS_REGULAR_EXPRESSION +----------------------- + +The output must match this regular expression for the test to pass. + +If set, the test output will be checked against the specified regular +expressions and at least one of the regular expressions has to match, +otherwise the test will fail. Example: + +.. code-block:: cmake + + set_tests_properties(mytest PROPERTIES + PASS_REGULAR_EXPRESSION "TestPassed;All ok" + ) + +``PASS_REGULAR_EXPRESSION`` expects a list of regular expressions. diff --git a/Help/prop_test/PROCESSORS.rst b/Help/prop_test/PROCESSORS.rst new file mode 100644 index 0000000..a927c10 --- /dev/null +++ b/Help/prop_test/PROCESSORS.rst @@ -0,0 +1,16 @@ +PROCESSORS +---------- + +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 :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 0000000..f48a69c --- /dev/null +++ b/Help/prop_test/PROCESSOR_AFFINITY.rst @@ -0,0 +1,13 @@ +PROCESSOR_AFFINITY +------------------ + +.. versionadded:: 3.12 + +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/REQUIRED_FILES.rst b/Help/prop_test/REQUIRED_FILES.rst new file mode 100644 index 0000000..baf209c --- /dev/null +++ b/Help/prop_test/REQUIRED_FILES.rst @@ -0,0 +1,38 @@ +REQUIRED_FILES +-------------- + +List of files required to run the test. The filenames are relative to the +test :prop_test:`WORKING_DIRECTORY` unless an absolute path is specified. + +If set to a list of files, the test will not be run unless all of the +files exist. + +Examples +~~~~~~~~ + +Suppose that ``test.txt`` is created by test ``baseTest`` and ``none.txt`` +does not exist: + +.. code-block:: cmake + + add_test(NAME baseTest ...) # Assumed to create test.txt + add_test(NAME fileTest ...) + + # The following ensures that if baseTest is successful, test.txt will + # have been created before fileTest is run + set_tests_properties(fileTest PROPERTIES + DEPENDS baseTest + REQUIRED_FILES test.txt + ) + + add_test(NAME notRunTest ...) + + # The following makes notRunTest depend on two files. Nothing creates + # the none.txt file, so notRunTest will fail with status "Not Run". + set_tests_properties(notRunTest PROPERTIES + REQUIRED_FILES "test.txt;none.txt" + ) + +The above example demonstrates how ``REQUIRED_FILES`` works, but it is not the +most robust way to implement test ordering with failure detection. For that, +test fixtures are a better alternative (see :prop_test:`FIXTURES_REQUIRED`). diff --git a/Help/prop_test/RESOURCE_GROUPS.rst b/Help/prop_test/RESOURCE_GROUPS.rst new file mode 100644 index 0000000..26c8fa2 --- /dev/null +++ b/Help/prop_test/RESOURCE_GROUPS.rst @@ -0,0 +1,72 @@ +RESOURCE_GROUPS +--------------- + +.. versionadded:: 3.16 + +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 new file mode 100644 index 0000000..8b13a01 --- /dev/null +++ b/Help/prop_test/RESOURCE_LOCK.rst @@ -0,0 +1,18 @@ +RESOURCE_LOCK +------------- + +Specify a list of resources that are locked by this test. + +If multiple tests specify the same resource lock, they are guaranteed +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 new file mode 100644 index 0000000..ab4c542 --- /dev/null +++ b/Help/prop_test/RUN_SERIAL.rst @@ -0,0 +1,8 @@ +RUN_SERIAL +---------- + +Do not run this test in parallel with any other test. + +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 0000000..46c4363 --- /dev/null +++ b/Help/prop_test/SKIP_REGULAR_EXPRESSION.rst @@ -0,0 +1,19 @@ +SKIP_REGULAR_EXPRESSION +----------------------- + +.. versionadded:: 3.16 + +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 new file mode 100644 index 0000000..23c4c62 --- /dev/null +++ b/Help/prop_test/SKIP_RETURN_CODE.rst @@ -0,0 +1,12 @@ +SKIP_RETURN_CODE +---------------- + +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. 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/TIMEOUT.rst b/Help/prop_test/TIMEOUT.rst new file mode 100644 index 0000000..d1cb90d --- /dev/null +++ b/Help/prop_test/TIMEOUT.rst @@ -0,0 +1,9 @@ +TIMEOUT +------- + +How many seconds to allow for this test. + +This property if set will limit a test to not take more than the +specified number of seconds to run. If it exceeds that the test +process will be killed and ctest will move to the next test. This +setting takes precedence over :variable:`CTEST_TEST_TIMEOUT`. diff --git a/Help/prop_test/TIMEOUT_AFTER_MATCH.rst b/Help/prop_test/TIMEOUT_AFTER_MATCH.rst new file mode 100644 index 0000000..726dcab --- /dev/null +++ b/Help/prop_test/TIMEOUT_AFTER_MATCH.rst @@ -0,0 +1,41 @@ +TIMEOUT_AFTER_MATCH +------------------- + +.. versionadded:: 3.6 + +Change a test's timeout duration after a matching line is encountered +in its output. + +Usage +^^^^^ + +.. code-block:: cmake + + add_test(mytest ...) + set_property(TEST mytest PROPERTY TIMEOUT_AFTER_MATCH "${seconds}" "${regex}") + +Description +^^^^^^^^^^^ + +Allow a test ``seconds`` to complete after ``regex`` is encountered in +its output. + +When the test outputs a line that matches ``regex`` its start time is +reset to the current time and its timeout duration is changed to +``seconds``. Prior to this, the timeout duration is determined by the +:prop_test:`TIMEOUT` property or the :variable:`CTEST_TEST_TIMEOUT` +variable if either of these are set. Because the test's start time is +reset, its execution time will not include any time that was spent +waiting for the matching output. + +:prop_test:`TIMEOUT_AFTER_MATCH` is useful for avoiding spurious +timeouts when your test must wait for some system resource to become +available before it can execute. Set :prop_test:`TIMEOUT` to a longer +duration that accounts for resource acquisition and use +:prop_test:`TIMEOUT_AFTER_MATCH` to control how long the actual test +is allowed to run. + +If the required resource can be controlled by CTest you should use +:prop_test:`RESOURCE_LOCK` instead of :prop_test:`TIMEOUT_AFTER_MATCH`. +This property should be used when only the test itself can determine +when its required resources are available. diff --git a/Help/prop_test/WILL_FAIL.rst b/Help/prop_test/WILL_FAIL.rst new file mode 100644 index 0000000..f1f94a4 --- /dev/null +++ b/Help/prop_test/WILL_FAIL.rst @@ -0,0 +1,7 @@ +WILL_FAIL +--------- + +If set to true, this will invert the pass/fail flag of the test. + +This property can be used for tests that are expected to fail and +return a non zero return code. diff --git a/Help/prop_test/WORKING_DIRECTORY.rst b/Help/prop_test/WORKING_DIRECTORY.rst new file mode 100644 index 0000000..92a0409 --- /dev/null +++ b/Help/prop_test/WORKING_DIRECTORY.rst @@ -0,0 +1,9 @@ +WORKING_DIRECTORY +----------------- + +The directory from which the test executable will be called. + +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 0000000..dc87d23 --- /dev/null +++ b/Help/prop_tgt/ADDITIONAL_CLEAN_FILES.rst @@ -0,0 +1,25 @@ +ADDITIONAL_CLEAN_FILES +---------------------- + +.. versionadded:: 3.15 + +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/AIX_EXPORT_ALL_SYMBOLS.rst b/Help/prop_tgt/AIX_EXPORT_ALL_SYMBOLS.rst new file mode 100644 index 0000000..de98fdf --- /dev/null +++ b/Help/prop_tgt/AIX_EXPORT_ALL_SYMBOLS.rst @@ -0,0 +1,14 @@ +AIX_EXPORT_ALL_SYMBOLS +---------------------- + +.. versionadded:: 3.17 + +On AIX, CMake automatically exports all symbols from shared libraries, and +from executables with the :prop_tgt:`ENABLE_EXPORTS` target property set. +Explicitly disable this boolean property to suppress the behavior and +export no symbols by default. In this case it is expected that the project +will use other means to export some symbols. + +This property is initialized by the value of +the :variable:`CMAKE_AIX_EXPORT_ALL_SYMBOLS` variable if it is set +when a target is created. diff --git a/Help/prop_tgt/ALIASED_TARGET.rst b/Help/prop_tgt/ALIASED_TARGET.rst new file mode 100644 index 0000000..f9e6034 --- /dev/null +++ b/Help/prop_tgt/ALIASED_TARGET.rst @@ -0,0 +1,7 @@ +ALIASED_TARGET +-------------- + +Name of target aliased by this target. + +If this is an :ref:`Alias Target <Alias Targets>`, this property contains +the name of the target aliased. diff --git a/Help/prop_tgt/ALIAS_GLOBAL.rst b/Help/prop_tgt/ALIAS_GLOBAL.rst new file mode 100644 index 0000000..a8859c6 --- /dev/null +++ b/Help/prop_tgt/ALIAS_GLOBAL.rst @@ -0,0 +1,19 @@ +ALIAS_GLOBAL +------------ + +.. versionadded:: 3.18 + +Read-only property indicating of whether an :ref:`ALIAS target <Alias Targets>` +is globally visible. + +The boolean value of this property is ``TRUE`` for aliases to +:ref:`IMPORTED targets <Imported Targets>` created +with the ``GLOBAL`` options to :command:`add_executable()` or +:command:`add_library()`, ``FALSE`` otherwise. It is undefined for +targets built within the project. + +.. note:: + + Promoting an :ref:`IMPORTED target <Imported Targets>` from ``LOCAL`` + to ``GLOBAL`` scope by changing the value or :prop_tgt:`IMPORTED_GLOBAL` + target property do not change the scope of local aliases. diff --git a/Help/prop_tgt/ANDROID_ANT_ADDITIONAL_OPTIONS.rst b/Help/prop_tgt/ANDROID_ANT_ADDITIONAL_OPTIONS.rst new file mode 100644 index 0000000..eceb17d --- /dev/null +++ b/Help/prop_tgt/ANDROID_ANT_ADDITIONAL_OPTIONS.rst @@ -0,0 +1,10 @@ +ANDROID_ANT_ADDITIONAL_OPTIONS +------------------------------ + +.. versionadded:: 3.4 + +Set the additional options for Android Ant build system. This is +a string value containing all command line options for the Ant build. +This property is initialized by the value of the +:variable:`CMAKE_ANDROID_ANT_ADDITIONAL_OPTIONS` variable if it is +set when a target is created. diff --git a/Help/prop_tgt/ANDROID_API.rst b/Help/prop_tgt/ANDROID_API.rst new file mode 100644 index 0000000..7664f18 --- /dev/null +++ b/Help/prop_tgt/ANDROID_API.rst @@ -0,0 +1,10 @@ +ANDROID_API +----------- + +.. versionadded:: 3.1 + +When :ref:`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio +Edition`, this property sets the Android target API version (e.g. ``15``). +The version number must be a positive decimal integer. This property is +initialized by the value of the :variable:`CMAKE_ANDROID_API` variable if +it is set when a target is created. diff --git a/Help/prop_tgt/ANDROID_API_MIN.rst b/Help/prop_tgt/ANDROID_API_MIN.rst new file mode 100644 index 0000000..7ca2455 --- /dev/null +++ b/Help/prop_tgt/ANDROID_API_MIN.rst @@ -0,0 +1,9 @@ +ANDROID_API_MIN +--------------- + +.. versionadded:: 3.2 + +Set the Android MIN API version (e.g. ``9``). The version number +must be a positive decimal integer. This property is initialized by +the value of the :variable:`CMAKE_ANDROID_API_MIN` variable if it is set +when a target is created. Native code builds using this API version. diff --git a/Help/prop_tgt/ANDROID_ARCH.rst b/Help/prop_tgt/ANDROID_ARCH.rst new file mode 100644 index 0000000..94b76dd --- /dev/null +++ b/Help/prop_tgt/ANDROID_ARCH.rst @@ -0,0 +1,20 @@ +ANDROID_ARCH +------------ + +.. versionadded:: 3.4 + +When :ref:`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio +Edition`, this property sets the Android target architecture. + +This is a string property that could be set to the one of +the following values: + +* ``armv7-a``: "ARMv7-A (armv7-a)" +* ``armv7-a-hard``: "ARMv7-A, hard-float ABI (armv7-a)" +* ``arm64-v8a``: "ARMv8-A, 64bit (arm64-v8a)" +* ``x86``: "x86 (x86)" +* ``x86_64``: "x86_64 (x86_64)" + +This property is initialized by the value of the +:variable:`CMAKE_ANDROID_ARCH` variable if it is set +when a target is created. diff --git a/Help/prop_tgt/ANDROID_ASSETS_DIRECTORIES.rst b/Help/prop_tgt/ANDROID_ASSETS_DIRECTORIES.rst new file mode 100644 index 0000000..b09a8b7 --- /dev/null +++ b/Help/prop_tgt/ANDROID_ASSETS_DIRECTORIES.rst @@ -0,0 +1,11 @@ +ANDROID_ASSETS_DIRECTORIES +-------------------------- + +.. versionadded:: 3.4 + +Set the Android assets directories to copy into the main assets +folder before build. This a string property that contains the +directory paths separated by semicolon. +This property is initialized by the value of the +:variable:`CMAKE_ANDROID_ASSETS_DIRECTORIES` variable if it is set when +a target is created. diff --git a/Help/prop_tgt/ANDROID_GUI.rst b/Help/prop_tgt/ANDROID_GUI.rst new file mode 100644 index 0000000..cc022db --- /dev/null +++ b/Help/prop_tgt/ANDROID_GUI.rst @@ -0,0 +1,17 @@ +ANDROID_GUI +----------- + +.. versionadded:: 3.1 + +When :ref:`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio +Edition`, this property specifies whether to build an executable as an +application package on Android. + +When this property is set to true the executable when built for Android +will be created as an application package. This property is initialized +by the value of the :variable:`CMAKE_ANDROID_GUI` variable if it is set +when a target is created. + +Add the ``AndroidManifest.xml`` source file explicitly to the +target :command:`add_executable` command invocation to specify the +root directory of the application package source. diff --git a/Help/prop_tgt/ANDROID_JAR_DEPENDENCIES.rst b/Help/prop_tgt/ANDROID_JAR_DEPENDENCIES.rst new file mode 100644 index 0000000..9880daf --- /dev/null +++ b/Help/prop_tgt/ANDROID_JAR_DEPENDENCIES.rst @@ -0,0 +1,9 @@ +ANDROID_JAR_DEPENDENCIES +------------------------ + +.. versionadded:: 3.4 + +Set the Android property that specifies JAR dependencies. +This is a string value property. This property is initialized +by the value of the :variable:`CMAKE_ANDROID_JAR_DEPENDENCIES` +variable if it is set when a target is created. diff --git a/Help/prop_tgt/ANDROID_JAR_DIRECTORIES.rst b/Help/prop_tgt/ANDROID_JAR_DIRECTORIES.rst new file mode 100644 index 0000000..6fef50b --- /dev/null +++ b/Help/prop_tgt/ANDROID_JAR_DIRECTORIES.rst @@ -0,0 +1,16 @@ +ANDROID_JAR_DIRECTORIES +----------------------- + +.. versionadded:: 3.4 + +Set the Android property that specifies directories to search for +the JAR libraries. + +This a string property that contains the directory paths separated by +semicolons. This property is initialized by the value of the +:variable:`CMAKE_ANDROID_JAR_DIRECTORIES` variable if it is set when +a target is created. + +Contents of ``ANDROID_JAR_DIRECTORIES`` may use "generator expressions" +with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` +manual for available expressions. diff --git a/Help/prop_tgt/ANDROID_JAVA_SOURCE_DIR.rst b/Help/prop_tgt/ANDROID_JAVA_SOURCE_DIR.rst new file mode 100644 index 0000000..9ea9884 --- /dev/null +++ b/Help/prop_tgt/ANDROID_JAVA_SOURCE_DIR.rst @@ -0,0 +1,10 @@ +ANDROID_JAVA_SOURCE_DIR +----------------------- + +.. versionadded:: 3.4 + +Set the Android property that defines the Java source code root directories. +This a string property that contains the directory paths separated by semicolon. +This property is initialized by the value of the +:variable:`CMAKE_ANDROID_JAVA_SOURCE_DIR` variable if it is set +when a target is created. diff --git a/Help/prop_tgt/ANDROID_NATIVE_LIB_DEPENDENCIES.rst b/Help/prop_tgt/ANDROID_NATIVE_LIB_DEPENDENCIES.rst new file mode 100644 index 0000000..3aa741f --- /dev/null +++ b/Help/prop_tgt/ANDROID_NATIVE_LIB_DEPENDENCIES.rst @@ -0,0 +1,16 @@ +ANDROID_NATIVE_LIB_DEPENDENCIES +------------------------------- + +.. versionadded:: 3.4 + +Set the Android property that specifies the .so dependencies. +This is a string property. + +This property is initialized by the value of the +:variable:`CMAKE_ANDROID_NATIVE_LIB_DEPENDENCIES` variable if it is set +when a target is created. + +Contents of ``ANDROID_NATIVE_LIB_DEPENDENCIES`` may use +"generator expressions" with the syntax ``$<...>``. See the +:manual:`cmake-generator-expressions(7)` manual for +available expressions. diff --git a/Help/prop_tgt/ANDROID_NATIVE_LIB_DIRECTORIES.rst b/Help/prop_tgt/ANDROID_NATIVE_LIB_DIRECTORIES.rst new file mode 100644 index 0000000..98200d9 --- /dev/null +++ b/Help/prop_tgt/ANDROID_NATIVE_LIB_DIRECTORIES.rst @@ -0,0 +1,18 @@ +ANDROID_NATIVE_LIB_DIRECTORIES +------------------------------ + +.. versionadded:: 3.4 + +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. + +This property is initialized by the value of the +:variable:`CMAKE_ANDROID_NATIVE_LIB_DIRECTORIES` variable if it is set when a +target is created. + +Contents of ``ANDROID_NATIVE_LIB_DIRECTORIES`` may use "generator expressions" +with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` +manual for available expressions. diff --git a/Help/prop_tgt/ANDROID_PROCESS_MAX.rst b/Help/prop_tgt/ANDROID_PROCESS_MAX.rst new file mode 100644 index 0000000..0b6aba7 --- /dev/null +++ b/Help/prop_tgt/ANDROID_PROCESS_MAX.rst @@ -0,0 +1,10 @@ +ANDROID_PROCESS_MAX +------------------- + +.. versionadded:: 3.4 + +Set the Android property that defines the maximum number of a +parallel Android NDK compiler processes (e.g. ``4``). +This property is initialized by the value of the +:variable:`CMAKE_ANDROID_PROCESS_MAX` variable if it is set +when a target is created. diff --git a/Help/prop_tgt/ANDROID_PROGUARD.rst b/Help/prop_tgt/ANDROID_PROGUARD.rst new file mode 100644 index 0000000..b5ce166 --- /dev/null +++ b/Help/prop_tgt/ANDROID_PROGUARD.rst @@ -0,0 +1,11 @@ +ANDROID_PROGUARD +---------------- + +.. versionadded:: 3.4 + +When this property is set to true that enables the ProGuard tool to shrink, +optimize, and obfuscate the code by removing unused code and renaming +classes, fields, and methods with semantically obscure names. +This property is initialized by the value of the +:variable:`CMAKE_ANDROID_PROGUARD` variable if it is set +when a target is created. diff --git a/Help/prop_tgt/ANDROID_PROGUARD_CONFIG_PATH.rst b/Help/prop_tgt/ANDROID_PROGUARD_CONFIG_PATH.rst new file mode 100644 index 0000000..6ac59d8 --- /dev/null +++ b/Help/prop_tgt/ANDROID_PROGUARD_CONFIG_PATH.rst @@ -0,0 +1,11 @@ +ANDROID_PROGUARD_CONFIG_PATH +---------------------------- + +.. versionadded:: 3.4 + +Set the Android property that specifies the location of the ProGuard +config file. Leave empty to use the default one. +This a string property that contains the path to ProGuard config file. +This property is initialized by the value of the +:variable:`CMAKE_ANDROID_PROGUARD_CONFIG_PATH` variable if it is set +when a target is created. diff --git a/Help/prop_tgt/ANDROID_SECURE_PROPS_PATH.rst b/Help/prop_tgt/ANDROID_SECURE_PROPS_PATH.rst new file mode 100644 index 0000000..f2ffa2e --- /dev/null +++ b/Help/prop_tgt/ANDROID_SECURE_PROPS_PATH.rst @@ -0,0 +1,10 @@ +ANDROID_SECURE_PROPS_PATH +------------------------- + +.. versionadded:: 3.4 + +Set the Android property that states the location of the secure properties file. +This is a string property that contains the file path. +This property is initialized by the value of the +:variable:`CMAKE_ANDROID_SECURE_PROPS_PATH` variable +if it is set when a target is created. diff --git a/Help/prop_tgt/ANDROID_SKIP_ANT_STEP.rst b/Help/prop_tgt/ANDROID_SKIP_ANT_STEP.rst new file mode 100644 index 0000000..1a54bce --- /dev/null +++ b/Help/prop_tgt/ANDROID_SKIP_ANT_STEP.rst @@ -0,0 +1,8 @@ +ANDROID_SKIP_ANT_STEP +--------------------- + +.. versionadded:: 3.4 + +Set the Android property that defines whether or not to skip the Ant build step. +This is a boolean property initialized by the value of the +:variable:`CMAKE_ANDROID_SKIP_ANT_STEP` variable if it is set when a target is created. diff --git a/Help/prop_tgt/ANDROID_STL_TYPE.rst b/Help/prop_tgt/ANDROID_STL_TYPE.rst new file mode 100644 index 0000000..c83712b --- /dev/null +++ b/Help/prop_tgt/ANDROID_STL_TYPE.rst @@ -0,0 +1,29 @@ +ANDROID_STL_TYPE +---------------- + +.. versionadded:: 3.4 + +When :ref:`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio +Edition`, this property specifies the type of STL support for the project. +This is a string property that could set to the one of the following values: + +``none`` + No C++ Support +``system`` + Minimal C++ without STL +``gabi++_static`` + GAbi++ Static +``gabi++_shared`` + GAbi++ Shared +``gnustl_static`` + GNU libstdc++ Static +``gnustl_shared`` + GNU libstdc++ Shared +``stlport_static`` + STLport Static +``stlport_shared`` + STLport Shared + +This property is initialized by the value of the +:variable:`CMAKE_ANDROID_STL_TYPE` variable if it is set when a target is +created. diff --git a/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY.rst b/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY.rst new file mode 100644 index 0000000..677e06d --- /dev/null +++ b/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY.rst @@ -0,0 +1,9 @@ +ARCHIVE_OUTPUT_DIRECTORY +------------------------ + +.. |XXX| replace:: :ref:`ARCHIVE <Archive Output Artifacts>` +.. |xxx| replace:: archive +.. |CMAKE_XXX_OUTPUT_DIRECTORY| replace:: :variable:`CMAKE_ARCHIVE_OUTPUT_DIRECTORY` +.. include:: XXX_OUTPUT_DIRECTORY.txt + +See also the :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY_<CONFIG>` target property. diff --git a/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY_CONFIG.rst b/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY_CONFIG.rst new file mode 100644 index 0000000..12f8bb7 --- /dev/null +++ b/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY_CONFIG.rst @@ -0,0 +1,16 @@ +ARCHIVE_OUTPUT_DIRECTORY_<CONFIG> +--------------------------------- + +Per-configuration output directory for +:ref:`ARCHIVE <Archive Output Artifacts>` target files. + +This is a per-configuration version of the +:prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY` target property, but +multi-configuration generators (VS, Xcode) do NOT append a +per-configuration subdirectory to the specified directory. This +property is initialized by the value of the +:variable:`CMAKE_ARCHIVE_OUTPUT_DIRECTORY_<CONFIG>` variable if +it is set when a target is created. + +Contents of ``ARCHIVE_OUTPUT_DIRECTORY_<CONFIG>`` may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/prop_tgt/ARCHIVE_OUTPUT_NAME.rst b/Help/prop_tgt/ARCHIVE_OUTPUT_NAME.rst new file mode 100644 index 0000000..6150193 --- /dev/null +++ b/Help/prop_tgt/ARCHIVE_OUTPUT_NAME.rst @@ -0,0 +1,8 @@ +ARCHIVE_OUTPUT_NAME +------------------- + +.. |XXX| replace:: :ref:`ARCHIVE <Archive Output Artifacts>` +.. |xxx| replace:: archive +.. include:: XXX_OUTPUT_NAME.txt + +See also the :prop_tgt:`ARCHIVE_OUTPUT_NAME_<CONFIG>` target property. diff --git a/Help/prop_tgt/ARCHIVE_OUTPUT_NAME_CONFIG.rst b/Help/prop_tgt/ARCHIVE_OUTPUT_NAME_CONFIG.rst new file mode 100644 index 0000000..4f62eb9 --- /dev/null +++ b/Help/prop_tgt/ARCHIVE_OUTPUT_NAME_CONFIG.rst @@ -0,0 +1,8 @@ +ARCHIVE_OUTPUT_NAME_<CONFIG> +---------------------------- + +Per-configuration output name for +:ref:`ARCHIVE <Archive Output Artifacts>` target files. + +This is the configuration-specific version of the +:prop_tgt:`ARCHIVE_OUTPUT_NAME` target property. diff --git a/Help/prop_tgt/AUTOGEN_BUILD_DIR.rst b/Help/prop_tgt/AUTOGEN_BUILD_DIR.rst new file mode 100644 index 0000000..ff42ae8 --- /dev/null +++ b/Help/prop_tgt/AUTOGEN_BUILD_DIR.rst @@ -0,0 +1,19 @@ +AUTOGEN_BUILD_DIR +----------------- + +.. versionadded:: 3.9 + +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_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>`` +is :prop_tgt:`NAME`. + +By default :prop_tgt:`AUTOGEN_BUILD_DIR` is unset. + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. diff --git a/Help/prop_tgt/AUTOGEN_ORIGIN_DEPENDS.rst b/Help/prop_tgt/AUTOGEN_ORIGIN_DEPENDS.rst new file mode 100644 index 0000000..563190a --- /dev/null +++ b/Help/prop_tgt/AUTOGEN_ORIGIN_DEPENDS.rst @@ -0,0 +1,40 @@ +AUTOGEN_ORIGIN_DEPENDS +---------------------- + +.. versionadded:: 3.14 + +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 0000000..663b54e --- /dev/null +++ b/Help/prop_tgt/AUTOGEN_PARALLEL.rst @@ -0,0 +1,23 @@ +AUTOGEN_PARALLEL +---------------- + +.. versionadded:: 3.11 + +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. ``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 ``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 new file mode 100644 index 0000000..92b52a3 --- /dev/null +++ b/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst @@ -0,0 +1,36 @@ +AUTOGEN_TARGET_DEPENDS +---------------------- + +Additional target dependencies of 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_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. + +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 be added to :prop_tgt:`AUTOGEN_TARGET_DEPENDS`. diff --git a/Help/prop_tgt/AUTOMOC.rst b/Help/prop_tgt/AUTOMOC.rst new file mode 100644 index 0000000..52d96e0 --- /dev/null +++ b/Help/prop_tgt/AUTOMOC.rst @@ -0,0 +1,248 @@ +AUTOMOC +------- + +Should the target be processed with auto-moc (for Qt projects). + +: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. + + +Header file processing +^^^^^^^^^^^^^^^^^^^^^^ + +At configuration time, a list of header files that should be scanned by +:prop_tgt:`AUTOMOC` is computed from the target's sources. + +- 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 + + - 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>``) + + and adds these to the scan list. + +At build time, CMake scans each unknown or modified header file from the +list and searches for + +- 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`. + +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`_. + +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``, or +- ``<AUTOGEN_BUILD_DIR>/mocs_compilation_$<CONFIG>.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. + +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. + +.. code-block:: cmake + + 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) + + +Modifiers +^^^^^^^^^ + +: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 0000000..8998284 --- /dev/null +++ b/Help/prop_tgt/AUTOMOC_COMPILER_PREDEFINES.rst @@ -0,0 +1,26 @@ +AUTOMOC_COMPILER_PREDEFINES +--------------------------- + +.. versionadded:: 3.10 + +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 new file mode 100644 index 0000000..1f31700 --- /dev/null +++ b/Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst @@ -0,0 +1,109 @@ +AUTOMOC_DEPEND_FILTERS +---------------------- + +.. versionadded:: 3.9 + +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. + +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. + +From Qt 5.15.0 on this variable is ignored as moc is able to output the correct +dependencies. + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. + + +Example 1 +^^^^^^^^^ + +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 + 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() {} \ + }; + ... + +:: + + // complex_class.hpp + #pragma once + JSON_BASED_CLASS(Complex_Class, "meta.json") + // end of file + +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 0000000..f4b8396 --- /dev/null +++ b/Help/prop_tgt/AUTOMOC_EXECUTABLE.rst @@ -0,0 +1,17 @@ +AUTOMOC_EXECUTABLE +------------------ + +.. versionadded:: 3.14 + +: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 0000000..a53810d --- /dev/null +++ b/Help/prop_tgt/AUTOMOC_MACRO_NAMES.rst @@ -0,0 +1,34 @@ +AUTOMOC_MACRO_NAMES +------------------- + +.. versionadded:: 3.10 + +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_MOC_OPTIONS.rst b/Help/prop_tgt/AUTOMOC_MOC_OPTIONS.rst new file mode 100644 index 0000000..330849b --- /dev/null +++ b/Help/prop_tgt/AUTOMOC_MOC_OPTIONS.rst @@ -0,0 +1,17 @@ +AUTOMOC_MOC_OPTIONS +------------------- + +Additional options for ``moc`` when using :prop_tgt:`AUTOMOC` + +This property is only used if the :prop_tgt:`AUTOMOC` property is ``ON`` +for this target. In this case, it holds additional command line +options which will be used when ``moc`` is executed during the build, i.e. +it is equivalent to the optional ``OPTIONS`` argument of the +:module:`qt4_wrap_cpp() <FindQt4>` macro. + +This property is initialized by the value of the +:variable:`CMAKE_AUTOMOC_MOC_OPTIONS` variable if it is set when a target +is created, or an empty string otherwise. + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. diff --git a/Help/prop_tgt/AUTOMOC_PATH_PREFIX.rst b/Help/prop_tgt/AUTOMOC_PATH_PREFIX.rst new file mode 100644 index 0000000..836d953 --- /dev/null +++ b/Help/prop_tgt/AUTOMOC_PATH_PREFIX.rst @@ -0,0 +1,33 @@ +AUTOMOC_PATH_PREFIX +------------------- + +.. versionadded:: 3.16 + +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 ``OFF`` by default. + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. + +Reproducible builds +^^^^^^^^^^^^^^^^^^^ + +For reproducible builds it 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``. 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 new file mode 100644 index 0000000..9a98f44 --- /dev/null +++ b/Help/prop_tgt/AUTORCC.rst @@ -0,0 +1,62 @@ +AUTORCC +------- + +Should the target be processed with auto-rcc (for Qt projects). + +: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. + +When this property is ``ON``, CMake will handle ``.qrc`` files added +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. + +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 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. + + +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_tgt:`AUTORCC_OPTIONS`: +Additional command line options for ``rcc`` can be set via this target +property. The corresponding :prop_sf:`AUTORCC_OPTIONS` source file property +can be used to specify options to be applied only to a specific ``.qrc`` file. + +: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 0000000..4f85fba --- /dev/null +++ b/Help/prop_tgt/AUTORCC_EXECUTABLE.rst @@ -0,0 +1,17 @@ +AUTORCC_EXECUTABLE +------------------ + +.. versionadded:: 3.14 + +: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 new file mode 100644 index 0000000..5261aff --- /dev/null +++ b/Help/prop_tgt/AUTORCC_OPTIONS.rst @@ -0,0 +1,28 @@ +AUTORCC_OPTIONS +--------------- + +Additional options for ``rcc`` when using :prop_tgt:`AUTORCC` + +This property holds additional command line options which will be used +when ``rcc`` is executed during the build via :prop_tgt:`AUTORCC`, +i.e. it is equivalent to the optional ``OPTIONS`` argument of the +:module:`qt4_add_resources() <FindQt4>` macro. + +This property is initialized by the value of the +:variable:`CMAKE_AUTORCC_OPTIONS` variable if it is set when a target is +created, or an empty string otherwise. + +The options set on the target may be overridden by :prop_sf:`AUTORCC_OPTIONS` +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 new file mode 100644 index 0000000..cd24f5e --- /dev/null +++ b/Help/prop_tgt/AUTOUIC.rst @@ -0,0 +1,85 @@ +AUTOUIC +------- + +Should the target be processed with auto-uic (for Qt projects). + +: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. + +This property is initialized by the value of the :variable:`CMAKE_AUTOUIC` +variable if it is set when a target is created. + +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_tgt:`AUTOUIC_OPTIONS`: +Additional command line options for ``uic`` can be set via this target +property. The corresponding :prop_sf:`AUTOUIC_OPTIONS` source file property +can be used to specify options to be applied only to a specific +``<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``. + +: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 0000000..5966326 --- /dev/null +++ b/Help/prop_tgt/AUTOUIC_EXECUTABLE.rst @@ -0,0 +1,17 @@ +AUTOUIC_EXECUTABLE +------------------ + +.. versionadded:: 3.14 + +: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 new file mode 100644 index 0000000..425ea1c --- /dev/null +++ b/Help/prop_tgt/AUTOUIC_OPTIONS.rst @@ -0,0 +1,32 @@ +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. + +This property is initialized by the value of the +:variable:`CMAKE_AUTOUIC_OPTIONS` variable if it is set when a target is +created, or an empty string otherwise. + +The options set on the target may be overridden by :prop_sf:`AUTOUIC_OPTIONS` +set on the ``.ui`` source file. + +This property may use "generator expressions" with the syntax ``$<...>``. +See the :manual:`cmake-generator-expressions(7)` manual for available +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/AUTOUIC_SEARCH_PATHS.rst b/Help/prop_tgt/AUTOUIC_SEARCH_PATHS.rst new file mode 100644 index 0000000..87fea48 --- /dev/null +++ b/Help/prop_tgt/AUTOUIC_SEARCH_PATHS.rst @@ -0,0 +1,14 @@ +AUTOUIC_SEARCH_PATHS +-------------------- + +.. versionadded:: 3.9 + +Search path list used by :prop_tgt:`AUTOUIC` to find included +``.ui`` files. + +This property is initialized by the value of the +:variable:`CMAKE_AUTOUIC_SEARCH_PATHS` variable if it is set +when a target is created. Otherwise it is empty. + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. diff --git a/Help/prop_tgt/BINARY_DIR.rst b/Help/prop_tgt/BINARY_DIR.rst new file mode 100644 index 0000000..beab12c --- /dev/null +++ b/Help/prop_tgt/BINARY_DIR.rst @@ -0,0 +1,8 @@ +BINARY_DIR +---------- + +.. versionadded:: 3.4 + +This read-only property reports the value of the +:variable:`CMAKE_CURRENT_BINARY_DIR` variable in the directory in which +the target was defined. diff --git a/Help/prop_tgt/BUILD_RPATH.rst b/Help/prop_tgt/BUILD_RPATH.rst new file mode 100644 index 0000000..1f917a5 --- /dev/null +++ b/Help/prop_tgt/BUILD_RPATH.rst @@ -0,0 +1,15 @@ +BUILD_RPATH +----------- + +.. versionadded:: 3.8 + +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 0000000..2cdfa0d --- /dev/null +++ b/Help/prop_tgt/BUILD_RPATH_USE_ORIGIN.rst @@ -0,0 +1,26 @@ +BUILD_RPATH_USE_ORIGIN +---------------------- + +.. versionadded:: 3.14 + +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/BUILD_WITH_INSTALL_NAME_DIR.rst b/Help/prop_tgt/BUILD_WITH_INSTALL_NAME_DIR.rst new file mode 100644 index 0000000..073dce5 --- /dev/null +++ b/Help/prop_tgt/BUILD_WITH_INSTALL_NAME_DIR.rst @@ -0,0 +1,15 @@ +BUILD_WITH_INSTALL_NAME_DIR +--------------------------- + +.. versionadded:: 3.9 + +``BUILD_WITH_INSTALL_NAME_DIR`` is a boolean specifying whether the macOS +``install_name`` of a target in the build tree uses the directory given by +:prop_tgt:`INSTALL_NAME_DIR`. This setting only applies to targets on macOS. + +This property is initialized by the value of the variable +:variable:`CMAKE_BUILD_WITH_INSTALL_NAME_DIR` if it is set when a target is +created. + +If this property is not set and policy :policy:`CMP0068` is not ``NEW``, the +value of :prop_tgt:`BUILD_WITH_INSTALL_RPATH` is used in its place. diff --git a/Help/prop_tgt/BUILD_WITH_INSTALL_RPATH.rst b/Help/prop_tgt/BUILD_WITH_INSTALL_RPATH.rst new file mode 100644 index 0000000..0244351 --- /dev/null +++ b/Help/prop_tgt/BUILD_WITH_INSTALL_RPATH.rst @@ -0,0 +1,15 @@ +BUILD_WITH_INSTALL_RPATH +------------------------ + +``BUILD_WITH_INSTALL_RPATH`` is a boolean specifying whether to link the target +in the build tree with the :prop_tgt:`INSTALL_RPATH`. This takes precedence +over :prop_tgt:`SKIP_BUILD_RPATH` and avoids the need for relinking before +installation. + +This property is initialized by the value of the +:variable:`CMAKE_BUILD_WITH_INSTALL_RPATH` variable if it is set when a target +is created. + +If policy :policy:`CMP0068` is not ``NEW``, this property also controls use of +:prop_tgt:`INSTALL_NAME_DIR` in the build tree on macOS. Either way, the +:prop_tgt:`BUILD_WITH_INSTALL_NAME_DIR` target property takes precedence. diff --git a/Help/prop_tgt/BUNDLE.rst b/Help/prop_tgt/BUNDLE.rst new file mode 100644 index 0000000..c556ac3 --- /dev/null +++ b/Help/prop_tgt/BUNDLE.rst @@ -0,0 +1,9 @@ +BUNDLE +------ + +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 +structure required for a ``CFBundle`` and will be suitable to be used for +creating Browser Plugins or other application resources. diff --git a/Help/prop_tgt/BUNDLE_EXTENSION.rst b/Help/prop_tgt/BUNDLE_EXTENSION.rst new file mode 100644 index 0000000..70de11c --- /dev/null +++ b/Help/prop_tgt/BUNDLE_EXTENSION.rst @@ -0,0 +1,8 @@ +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 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 0000000..adfa6f7 --- /dev/null +++ b/Help/prop_tgt/COMMON_LANGUAGE_RUNTIME.rst @@ -0,0 +1,24 @@ +COMMON_LANGUAGE_RUNTIME +----------------------- + +.. versionadded:: 3.12 + +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/COMPATIBLE_INTERFACE_BOOL.rst b/Help/prop_tgt/COMPATIBLE_INTERFACE_BOOL.rst new file mode 100644 index 0000000..6910367 --- /dev/null +++ b/Help/prop_tgt/COMPATIBLE_INTERFACE_BOOL.rst @@ -0,0 +1,20 @@ +COMPATIBLE_INTERFACE_BOOL +------------------------- + +Properties which must be compatible with their link interface + +The ``COMPATIBLE_INTERFACE_BOOL`` property may contain a list of +properties for this target which must be consistent when evaluated as a +boolean with the ``INTERFACE`` variant of the property in all linked +dependees. For example, if a property ``FOO`` appears in the list, then +for each dependee, the ``INTERFACE_FOO`` property content in all of its +dependencies must be consistent with each other, and with the ``FOO`` +property in the depender. + +Consistency in this sense has the meaning that if the property is set, +then it must have the same boolean value as all others, and if the +property is not set, then it is ignored. + +Note that for each dependee, the set of properties specified in this +property must not intersect with the set specified in any of the other +:ref:`Compatible Interface Properties`. diff --git a/Help/prop_tgt/COMPATIBLE_INTERFACE_NUMBER_MAX.rst b/Help/prop_tgt/COMPATIBLE_INTERFACE_NUMBER_MAX.rst new file mode 100644 index 0000000..298acf1 --- /dev/null +++ b/Help/prop_tgt/COMPATIBLE_INTERFACE_NUMBER_MAX.rst @@ -0,0 +1,18 @@ +COMPATIBLE_INTERFACE_NUMBER_MAX +------------------------------- + +Properties whose maximum value from the link interface will be used. + +The ``COMPATIBLE_INTERFACE_NUMBER_MAX`` property may contain a list of +properties for this target whose maximum value may be read at generate +time when evaluated in the ``INTERFACE`` variant of the property in all +linked dependees. For example, if a property ``FOO`` appears in the list, +then for each dependee, the ``INTERFACE_FOO`` property content in all of +its dependencies will be compared with each other and with the ``FOO`` +property in the depender. When reading the ``FOO`` property at generate +time, the maximum value will be returned. If the property is not set, +then it is ignored. + +Note that for each dependee, the set of properties specified in this +property must not intersect with the set specified in any of the other +:ref:`Compatible Interface Properties`. diff --git a/Help/prop_tgt/COMPATIBLE_INTERFACE_NUMBER_MIN.rst b/Help/prop_tgt/COMPATIBLE_INTERFACE_NUMBER_MIN.rst new file mode 100644 index 0000000..d5fd825 --- /dev/null +++ b/Help/prop_tgt/COMPATIBLE_INTERFACE_NUMBER_MIN.rst @@ -0,0 +1,18 @@ +COMPATIBLE_INTERFACE_NUMBER_MIN +------------------------------- + +Properties whose maximum value from the link interface will be used. + +The ``COMPATIBLE_INTERFACE_NUMBER_MIN`` property may contain a list of +properties for this target whose minimum value may be read at generate +time when evaluated in the ``INTERFACE`` variant of the property of all +linked dependees. For example, if a +property ``FOO`` appears in the list, then for each dependee, the +``INTERFACE_FOO`` property content in all of its dependencies will be +compared with each other and with the ``FOO`` property in the depender. +When reading the ``FOO`` property at generate time, the minimum value +will be returned. If the property is not set, then it is ignored. + +Note that for each dependee, the set of properties specified in this +property must not intersect with the set specified in any of the other +:ref:`Compatible Interface Properties`. diff --git a/Help/prop_tgt/COMPATIBLE_INTERFACE_STRING.rst b/Help/prop_tgt/COMPATIBLE_INTERFACE_STRING.rst new file mode 100644 index 0000000..a0050b9 --- /dev/null +++ b/Help/prop_tgt/COMPATIBLE_INTERFACE_STRING.rst @@ -0,0 +1,16 @@ +COMPATIBLE_INTERFACE_STRING +--------------------------- + +Properties which must be string-compatible with their link interface + +The ``COMPATIBLE_INTERFACE_STRING`` property may contain a list of +properties for this target which must be the same when evaluated as a +string in the ``INTERFACE`` variant of the property all linked dependees. +For example, if a property ``FOO`` appears in the list, then for each +dependee, the ``INTERFACE_FOO`` property content in all of its +dependencies must be equal with each other, and with the ``FOO`` property +in the depender. If the property is not set, then it is ignored. + +Note that for each dependee, the set of properties specified in this +property must not intersect with the set specified in any of the other +:ref:`Compatible Interface Properties`. diff --git a/Help/prop_tgt/COMPILE_DEFINITIONS.rst b/Help/prop_tgt/COMPILE_DEFINITIONS.rst new file mode 100644 index 0000000..059f913 --- /dev/null +++ b/Help/prop_tgt/COMPILE_DEFINITIONS.rst @@ -0,0 +1,25 @@ +COMPILE_DEFINITIONS +------------------- + +Preprocessor definitions for compiling a target's sources. + +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). + +CMake will automatically drop some definitions that are not supported +by the native build tool. + +.. include:: /include/COMPILE_DEFINITIONS_DISCLAIMER.txt + +Contents of ``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. + +The corresponding :prop_tgt:`COMPILE_DEFINITIONS_<CONFIG>` property may +be set to specify per-configuration definitions. Generator expressions +should be preferred instead of setting the alternative property. diff --git a/Help/prop_tgt/COMPILE_DEFINITIONS_CONFIG.rst b/Help/prop_tgt/COMPILE_DEFINITIONS_CONFIG.rst new file mode 100644 index 0000000..84bd5e4 --- /dev/null +++ b/Help/prop_tgt/COMPILE_DEFINITIONS_CONFIG.rst @@ -0,0 +1,16 @@ +COMPILE_DEFINITIONS_<CONFIG> +---------------------------- + +Ignored. See CMake Policy :policy:`CMP0043`. + +Per-configuration preprocessor definitions on a target. + +This is the configuration-specific version of :prop_tgt:`COMPILE_DEFINITIONS` +where ``<CONFIG>`` is an upper-case name (ex. ``COMPILE_DEFINITIONS_DEBUG``). + +Contents of ``COMPILE_DEFINITIONS_<CONFIG>`` 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. + +Generator expressions should be preferred instead of setting this property. diff --git a/Help/prop_tgt/COMPILE_FEATURES.rst b/Help/prop_tgt/COMPILE_FEATURES.rst new file mode 100644 index 0000000..9b937ed --- /dev/null +++ b/Help/prop_tgt/COMPILE_FEATURES.rst @@ -0,0 +1,15 @@ +COMPILE_FEATURES +---------------- + +.. versionadded:: 3.1 + +Compiler features enabled for this target. + +The list of features in this property are a subset of the features listed +in the :variable:`CMAKE_C_COMPILE_FEATURES`, :variable:`CMAKE_CUDA_COMPILE_FEATURES`, and +:variable:`CMAKE_CXX_COMPILE_FEATURES` variables. + +Contents of ``COMPILE_FEATURES`` 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. diff --git a/Help/prop_tgt/COMPILE_FLAGS.rst b/Help/prop_tgt/COMPILE_FLAGS.rst new file mode 100644 index 0000000..8fe651b --- /dev/null +++ b/Help/prop_tgt/COMPILE_FLAGS.rst @@ -0,0 +1,11 @@ +COMPILE_FLAGS +------------- + +Additional flags to use when compiling this target's sources. + +The ``COMPILE_FLAGS`` property sets additional compiler flags used to +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. diff --git a/Help/prop_tgt/COMPILE_OPTIONS.rst b/Help/prop_tgt/COMPILE_OPTIONS.rst new file mode 100644 index 0000000..0cd6836 --- /dev/null +++ b/Help/prop_tgt/COMPILE_OPTIONS.rst @@ -0,0 +1,17 @@ +COMPILE_OPTIONS +--------------- + +List of options to pass to the compiler. + +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. + +This property is initialized by the :prop_dir:`COMPILE_OPTIONS` directory +property when a target is created, and is used by the generators to set +the options for the compiler. + +Contents of ``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. diff --git a/Help/prop_tgt/COMPILE_PDB_NAME.rst b/Help/prop_tgt/COMPILE_PDB_NAME.rst new file mode 100644 index 0000000..b76afeb --- /dev/null +++ b/Help/prop_tgt/COMPILE_PDB_NAME.rst @@ -0,0 +1,13 @@ +COMPILE_PDB_NAME +---------------- + +.. versionadded:: 3.1 + +Output name for the MS debug symbol ``.pdb`` file generated by the +compiler while building source files. + +This property specifies the base name for the debug symbols file. +If not set, the default is unspecified. + +.. |PDB_XXX| replace:: :prop_tgt:`PDB_NAME` +.. include:: COMPILE_PDB_NOTE.txt diff --git a/Help/prop_tgt/COMPILE_PDB_NAME_CONFIG.rst b/Help/prop_tgt/COMPILE_PDB_NAME_CONFIG.rst new file mode 100644 index 0000000..4c9825d --- /dev/null +++ b/Help/prop_tgt/COMPILE_PDB_NAME_CONFIG.rst @@ -0,0 +1,12 @@ +COMPILE_PDB_NAME_<CONFIG> +------------------------- + +.. versionadded:: 3.1 + +Per-configuration output name for the MS debug symbol ``.pdb`` file +generated by the compiler while building source files. + +This is the configuration-specific version of :prop_tgt:`COMPILE_PDB_NAME`. + +.. |PDB_XXX| replace:: :prop_tgt:`PDB_NAME_<CONFIG>` +.. include:: COMPILE_PDB_NOTE.txt diff --git a/Help/prop_tgt/COMPILE_PDB_NOTE.txt b/Help/prop_tgt/COMPILE_PDB_NOTE.txt new file mode 100644 index 0000000..43003d9 --- /dev/null +++ b/Help/prop_tgt/COMPILE_PDB_NOTE.txt @@ -0,0 +1,5 @@ +.. note:: + The compiler-generated program database files are specified by the + ``/Fd`` compiler flag and are not the same as linker-generated + program database files specified by the ``/pdb`` linker flag. + Use the |PDB_XXX| property to specify the latter. diff --git a/Help/prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY.rst b/Help/prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY.rst new file mode 100644 index 0000000..3f3df66 --- /dev/null +++ b/Help/prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY.rst @@ -0,0 +1,15 @@ +COMPILE_PDB_OUTPUT_DIRECTORY +---------------------------- + +.. versionadded:: 3.1 + +Output directory for the MS debug symbol ``.pdb`` file +generated by the compiler while building source files. + +This property specifies the directory into which the MS debug symbols +will be placed by the compiler. This property is initialized by the +value of the :variable:`CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY` variable +if it is set when a target is created. + +.. |PDB_XXX| replace:: :prop_tgt:`PDB_OUTPUT_DIRECTORY` +.. include:: COMPILE_PDB_NOTE.txt diff --git a/Help/prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG.rst b/Help/prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG.rst new file mode 100644 index 0000000..c25c2fc --- /dev/null +++ b/Help/prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG.rst @@ -0,0 +1,18 @@ +COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG> +------------------------------------- + +.. versionadded:: 3.1 + +Per-configuration output directory for the MS debug symbol ``.pdb`` file +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 (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 +if it is set when a target is created. + +.. |PDB_XXX| replace:: :prop_tgt:`PDB_OUTPUT_DIRECTORY_<CONFIG>` +.. include:: COMPILE_PDB_NOTE.txt diff --git a/Help/prop_tgt/CONFIG_OUTPUT_NAME.rst b/Help/prop_tgt/CONFIG_OUTPUT_NAME.rst new file mode 100644 index 0000000..a61c702 --- /dev/null +++ b/Help/prop_tgt/CONFIG_OUTPUT_NAME.rst @@ -0,0 +1,8 @@ +<CONFIG>_OUTPUT_NAME +-------------------- + +Old per-configuration target file base name. +Use :prop_tgt:`OUTPUT_NAME_<CONFIG>` instead. + +This is a configuration-specific version of the :prop_tgt:`OUTPUT_NAME` +target property. diff --git a/Help/prop_tgt/CONFIG_POSTFIX.rst b/Help/prop_tgt/CONFIG_POSTFIX.rst new file mode 100644 index 0000000..5c2fbd7 --- /dev/null +++ b/Help/prop_tgt/CONFIG_POSTFIX.rst @@ -0,0 +1,13 @@ +<CONFIG>_POSTFIX +---------------- + +Postfix to append to the target file name for configuration <CONFIG>. + +When building with configuration <CONFIG> the value of this property +is appended to the target file name built on disk. For non-executable +targets, this property is initialized by the value of the variable +CMAKE_<CONFIG>_POSTFIX if it is set when a target is created. This +property is ignored on the Mac for Frameworks and App Bundles. + +For macOS see also the :prop_tgt:`FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>` +target property. diff --git a/Help/prop_tgt/CROSSCOMPILING_EMULATOR.rst b/Help/prop_tgt/CROSSCOMPILING_EMULATOR.rst new file mode 100644 index 0000000..d7fb9b1 --- /dev/null +++ b/Help/prop_tgt/CROSSCOMPILING_EMULATOR.rst @@ -0,0 +1,17 @@ +CROSSCOMPILING_EMULATOR +----------------------- + +.. versionadded:: 3.3 + +Use the given emulator to run executables created when crosscompiling. +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_ARCHITECTURES.rst b/Help/prop_tgt/CUDA_ARCHITECTURES.rst new file mode 100644 index 0000000..a3191e8 --- /dev/null +++ b/Help/prop_tgt/CUDA_ARCHITECTURES.rst @@ -0,0 +1,42 @@ +CUDA_ARCHITECTURES +------------------ + +.. versionadded:: 3.18 + +List of architectures to generate device code for. + +An architecture can be suffixed by either ``-real`` or ``-virtual`` to specify +the kind of architecture to generate code for. +If no suffix is given then code is generated for both real and virtual +architectures. + +A non-empty false value (e.g. ``OFF``) disables adding architectures. +This is intended to support packagers and rare cases where full control +over the passed flags is required. + +This property is initialized by the value of the :variable:`CMAKE_CUDA_ARCHITECTURES` +variable if it is set when a target is created. + +The ``CUDA_ARCHITECTURES`` target property must be set to a non-empty value on targets +that compile CUDA sources, or it is an error. See policy :policy:`CMP0104`. + +Examples +^^^^^^^^ + +.. code-block:: cmake + + set_target_properties(tgt PROPERTIES CUDA_ARCHITECTURES "35;50;72") + +Generates code for real and virtual architectures ``30``, ``50`` and ``72``. + +.. code-block:: cmake + + set_property(TARGET tgt PROPERTY CUDA_ARCHITECTURES 70-real 72-virtual) + +Generates code for real architecture ``70`` and virtual architecture ``72``. + +.. code-block:: cmake + + set_property(TARGET tgt PROPERTY CUDA_ARCHITECTURES OFF) + +CMake will not pass any architecture flags to the compiler. diff --git a/Help/prop_tgt/CUDA_EXTENSIONS.rst b/Help/prop_tgt/CUDA_EXTENSIONS.rst new file mode 100644 index 0000000..2ddba0b --- /dev/null +++ b/Help/prop_tgt/CUDA_EXTENSIONS.rst @@ -0,0 +1,19 @@ +CUDA_EXTENSIONS +--------------- + +.. versionadded:: 3.8 + +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 CUDA/C++ standard level is +controlled by the :prop_tgt:`CUDA_STANDARD` target property. + +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_CUDA_EXTENSIONS` variable if it is set when a target +is created. diff --git a/Help/prop_tgt/CUDA_PTX_COMPILATION.rst b/Help/prop_tgt/CUDA_PTX_COMPILATION.rst new file mode 100644 index 0000000..4e90afe --- /dev/null +++ b/Help/prop_tgt/CUDA_PTX_COMPILATION.rst @@ -0,0 +1,14 @@ +CUDA_PTX_COMPILATION +-------------------- + +.. versionadded:: 3.9 + +Compile CUDA sources to ``.ptx`` files instead of ``.obj`` files +within :ref:`Object Libraries`. + +For example: + +.. code-block:: cmake + + add_library(myptx OBJECT a.cu b.cu) + set_property(TARGET myptx PROPERTY CUDA_PTX_COMPILATION ON) diff --git a/Help/prop_tgt/CUDA_RESOLVE_DEVICE_SYMBOLS.rst b/Help/prop_tgt/CUDA_RESOLVE_DEVICE_SYMBOLS.rst new file mode 100644 index 0000000..819ce3e --- /dev/null +++ b/Help/prop_tgt/CUDA_RESOLVE_DEVICE_SYMBOLS.rst @@ -0,0 +1,27 @@ +CUDA_RESOLVE_DEVICE_SYMBOLS +--------------------------- + +.. versionadded:: 3.9 + +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`. + + +For instance: + +.. code-block:: cmake + + set_property(TARGET mystaticlib PROPERTY CUDA_RESOLVE_DEVICE_SYMBOLS ON) diff --git a/Help/prop_tgt/CUDA_RUNTIME_LIBRARY-VALUES.txt b/Help/prop_tgt/CUDA_RUNTIME_LIBRARY-VALUES.txt new file mode 100644 index 0000000..a6d7050 --- /dev/null +++ b/Help/prop_tgt/CUDA_RUNTIME_LIBRARY-VALUES.txt @@ -0,0 +1,9 @@ +``None`` + Link with ``-cudart=none`` or equivalent flag(s) to use no CUDA + runtime library. +``Shared`` + Link with ``-cudart=shared`` or equivalent flag(s) to use a + dynamically-linked CUDA runtime library. +``Static`` + Link with ``-cudart=static`` or equivalent flag(s) to use a + statically-linked CUDA runtime library. diff --git a/Help/prop_tgt/CUDA_RUNTIME_LIBRARY.rst b/Help/prop_tgt/CUDA_RUNTIME_LIBRARY.rst new file mode 100644 index 0000000..e937fc6 --- /dev/null +++ b/Help/prop_tgt/CUDA_RUNTIME_LIBRARY.rst @@ -0,0 +1,23 @@ +CUDA_RUNTIME_LIBRARY +-------------------- + +.. versionadded:: 3.17 + +Select the CUDA runtime library for use by compilers targeting the CUDA language. + +The allowed case insensitive values are: + +.. include:: CUDA_RUNTIME_LIBRARY-VALUES.txt + +Contents of ``CUDA_RUNTIME_LIBRARY`` may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. + +If that property is not set then CMake uses an appropriate default +value based on the compiler to select the CUDA runtime library. + +.. note:: + + This property has effect only when the ``CUDA`` language is enabled. To + control the CUDA runtime linking when only using the CUDA SDK with the + ``C`` or ``C++`` language we recommend using the :module:`FindCUDAToolkit` + module. diff --git a/Help/prop_tgt/CUDA_SEPARABLE_COMPILATION.rst b/Help/prop_tgt/CUDA_SEPARABLE_COMPILATION.rst new file mode 100644 index 0000000..32222f9 --- /dev/null +++ b/Help/prop_tgt/CUDA_SEPARABLE_COMPILATION.rst @@ -0,0 +1,19 @@ +CUDA_SEPARABLE_COMPILATION +-------------------------- + +.. versionadded:: 3.8 + +CUDA only: Enables separate compilation of device code + +If set this will enable separable compilation for all CUDA files for +the given target. + +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 new file mode 100644 index 0000000..6517035 --- /dev/null +++ b/Help/prop_tgt/CUDA_STANDARD.rst @@ -0,0 +1,34 @@ +CUDA_STANDARD +------------- + +.. versionadded:: 3.8 + +The CUDA/C++ standard whose features are requested to build this target. + +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``, ``03``, ``11``, ``14``, ``17``, ``20``, ``23``. + +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 CUDA_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:`CUDA_STANDARD_REQUIRED` target property. +Additionally, the :prop_tgt:`CUDA_EXTENSIONS` target property may be used to +control whether compiler-specific extensions are enabled on a per-target basis. + +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_CUDA_STANDARD` variable if it is set when a target +is created. diff --git a/Help/prop_tgt/CUDA_STANDARD_REQUIRED.rst b/Help/prop_tgt/CUDA_STANDARD_REQUIRED.rst new file mode 100644 index 0000000..c9301b5 --- /dev/null +++ b/Help/prop_tgt/CUDA_STANDARD_REQUIRED.rst @@ -0,0 +1,20 @@ +CUDA_STANDARD_REQUIRED +---------------------- + +.. versionadded:: 3.8 + +Boolean describing whether the value of :prop_tgt:`CUDA_STANDARD` is a requirement. + +If this property is set to ``ON``, then the value of the +:prop_tgt:`CUDA_STANDARD` target property is treated as a requirement. If this +property is ``OFF`` or unset, the :prop_tgt:`CUDA_STANDARD` target property is +treated as optional and may "decay" to a previous standard if the requested is +not available. For compilers that have no notion of a standard level, such as +MSVC 1800 (Visual Studio 2013) and lower, this has no effect. + +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_CUDA_STANDARD_REQUIRED` variable if it is set when a +target is created. diff --git a/Help/prop_tgt/CXX_EXTENSIONS.rst b/Help/prop_tgt/CXX_EXTENSIONS.rst new file mode 100644 index 0000000..bda531e --- /dev/null +++ b/Help/prop_tgt/CXX_EXTENSIONS.rst @@ -0,0 +1,19 @@ +CXX_EXTENSIONS +-------------- + +.. versionadded:: 3.1 + +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 C++ standard level is +controlled by the :prop_tgt:`CXX_STANDARD` target property. + +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_CXX_EXTENSIONS` variable if it is set when a target +is created. diff --git a/Help/prop_tgt/CXX_STANDARD.rst b/Help/prop_tgt/CXX_STANDARD.rst new file mode 100644 index 0000000..be0dab5 --- /dev/null +++ b/Help/prop_tgt/CXX_STANDARD.rst @@ -0,0 +1,36 @@ +CXX_STANDARD +------------ + +.. versionadded:: 3.1 + +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 Microsoft Visual C++ before +2015 Update 3, this has no effect. + +Supported values are ``98``, ``11``, ``14``, ``17``, ``20``, ``23``. + +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 CXX_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:`CXX_STANDARD_REQUIRED` target property. +Additionally, the :prop_tgt:`CXX_EXTENSIONS` target property may be used to +control whether compiler-specific extensions are enabled on a per-target basis. + +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_CXX_STANDARD` variable if it is set when a target +is created. diff --git a/Help/prop_tgt/CXX_STANDARD_REQUIRED.rst b/Help/prop_tgt/CXX_STANDARD_REQUIRED.rst new file mode 100644 index 0000000..8b17490 --- /dev/null +++ b/Help/prop_tgt/CXX_STANDARD_REQUIRED.rst @@ -0,0 +1,20 @@ +CXX_STANDARD_REQUIRED +--------------------- + +.. versionadded:: 3.1 + +Boolean describing whether the value of :prop_tgt:`CXX_STANDARD` is a requirement. + +If this property is set to ``ON``, then the value of the +:prop_tgt:`CXX_STANDARD` target property is treated as a requirement. If this +property is ``OFF`` or unset, the :prop_tgt:`CXX_STANDARD` target property is +treated as optional and may "decay" to a previous standard if the requested is +not available. For compilers that have no notion of a standard level, such as +MSVC 1800 (Visual Studio 2013) and lower, this has no effect. + +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_CXX_STANDARD_REQUIRED` variable if it is set when a +target is created. diff --git a/Help/prop_tgt/C_EXTENSIONS.rst b/Help/prop_tgt/C_EXTENSIONS.rst new file mode 100644 index 0000000..b2abb46 --- /dev/null +++ b/Help/prop_tgt/C_EXTENSIONS.rst @@ -0,0 +1,19 @@ +C_EXTENSIONS +------------ + +.. versionadded:: 3.1 + +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 C standard level is +controlled by the :prop_tgt:`C_STANDARD` target property. + +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_C_EXTENSIONS` variable if it is set when a target +is created. diff --git a/Help/prop_tgt/C_STANDARD.rst b/Help/prop_tgt/C_STANDARD.rst new file mode 100644 index 0000000..e22b775 --- /dev/null +++ b/Help/prop_tgt/C_STANDARD.rst @@ -0,0 +1,36 @@ +C_STANDARD +---------- + +.. versionadded:: 3.1 + +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 C standard level, such as Microsoft Visual C++ before +VS 16.7, this property has no effect. + +Supported values are ``90``, ``99``, ``11``, ``17``, ``23``. + +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 C_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:`C_STANDARD_REQUIRED` target property. +Additionally, the :prop_tgt:`C_EXTENSIONS` target property may be used to +control whether compiler-specific extensions are enabled on a per-target basis. + +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_C_STANDARD` variable if it is set when a target +is created. diff --git a/Help/prop_tgt/C_STANDARD_REQUIRED.rst b/Help/prop_tgt/C_STANDARD_REQUIRED.rst new file mode 100644 index 0000000..8059e3a --- /dev/null +++ b/Help/prop_tgt/C_STANDARD_REQUIRED.rst @@ -0,0 +1,20 @@ +C_STANDARD_REQUIRED +------------------- + +.. versionadded:: 3.1 + +Boolean describing whether the value of :prop_tgt:`C_STANDARD` is a requirement. + +If this property is set to ``ON``, then the value of the +:prop_tgt:`C_STANDARD` target property is treated as a requirement. If this +property is ``OFF`` or unset, the :prop_tgt:`C_STANDARD` target property is +treated as optional and may "decay" to a previous standard if the requested is +not available. For compilers that have no notion of a C standard level, such +as Microsoft Visual C++ before VS 16.7, this property has no effect. + +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_C_STANDARD_REQUIRED` variable if it is set when a +target is created. diff --git a/Help/prop_tgt/DEBUG_POSTFIX.rst b/Help/prop_tgt/DEBUG_POSTFIX.rst new file mode 100644 index 0000000..eca7cb0 --- /dev/null +++ b/Help/prop_tgt/DEBUG_POSTFIX.rst @@ -0,0 +1,7 @@ +DEBUG_POSTFIX +------------- + +See target property :prop_tgt:`<CONFIG>_POSTFIX`. + +This property is a special case of the more-general :prop_tgt:`<CONFIG>_POSTFIX` +property for the ``DEBUG`` configuration. diff --git a/Help/prop_tgt/DEFINE_SYMBOL.rst b/Help/prop_tgt/DEFINE_SYMBOL.rst new file mode 100644 index 0000000..eb7f937 --- /dev/null +++ b/Help/prop_tgt/DEFINE_SYMBOL.rst @@ -0,0 +1,11 @@ +DEFINE_SYMBOL +------------- + +Define a symbol when compiling this target's sources. + +``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 +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 0000000..f11fe7c --- /dev/null +++ b/Help/prop_tgt/DEPLOYMENT_ADDITIONAL_FILES.rst @@ -0,0 +1,20 @@ +DEPLOYMENT_ADDITIONAL_FILES +--------------------------- + +.. versionadded:: 3.13 + +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 new file mode 100644 index 0000000..0680238 --- /dev/null +++ b/Help/prop_tgt/DEPLOYMENT_REMOTE_DIRECTORY.rst @@ -0,0 +1,20 @@ +DEPLOYMENT_REMOTE_DIRECTORY +--------------------------- + +.. versionadded:: 3.6 + +Set the WinCE project ``RemoteDirectory`` in ``DeploymentTool`` and +``RemoteExecutable`` in ``DebuggerTool`` in ``.vcproj`` files generated +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 + + set_property(TARGET ${TARGET} PROPERTY + DEPLOYMENT_REMOTE_DIRECTORY "\\FlashStorage") + +produces:: + + <DeploymentTool RemoteDirectory="\FlashStorage" ... /> + <DebuggerTool RemoteExecutable="\FlashStorage\target_file" ... /> diff --git a/Help/prop_tgt/DEPRECATION.rst b/Help/prop_tgt/DEPRECATION.rst new file mode 100644 index 0000000..45ca848 --- /dev/null +++ b/Help/prop_tgt/DEPRECATION.rst @@ -0,0 +1,9 @@ +DEPRECATION +----------- + +.. versionadded:: 3.17 + +Deprecation message from imported target's developer. + +``DEPRECATION`` is the message regarding a deprecation status to be displayed +to downstream users of a target. diff --git a/Help/prop_tgt/DISABLE_PRECOMPILE_HEADERS.rst b/Help/prop_tgt/DISABLE_PRECOMPILE_HEADERS.rst new file mode 100644 index 0000000..7b3826b --- /dev/null +++ b/Help/prop_tgt/DISABLE_PRECOMPILE_HEADERS.rst @@ -0,0 +1,10 @@ +DISABLE_PRECOMPILE_HEADERS +-------------------------- + +.. versionadded:: 3.16 + +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.rst b/Help/prop_tgt/DOTNET_TARGET_FRAMEWORK.rst new file mode 100644 index 0000000..3ba4e25 --- /dev/null +++ b/Help/prop_tgt/DOTNET_TARGET_FRAMEWORK.rst @@ -0,0 +1,15 @@ +DOTNET_TARGET_FRAMEWORK +----------------------- + +.. versionadded:: 3.17 + +Specify the .NET target framework. + +Used to specify the .NET target framework for C++/CLI and C#. For +example: ``netcoreapp2.1``. + +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`. 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 0000000..fbd1aab --- /dev/null +++ b/Help/prop_tgt/DOTNET_TARGET_FRAMEWORK_VERSION.rst @@ -0,0 +1,17 @@ +DOTNET_TARGET_FRAMEWORK_VERSION +------------------------------- + +.. versionadded:: 3.12 + +Specify the .NET target framework version. + +Used to specify the .NET target framework version for C++/CLI and C#. +For example: ``v4.5``. + +This property is only evaluated for :ref:`Visual Studio Generators` +VS 2010 and above. + +To initialize this variable for all targets set +:variable:`CMAKE_DOTNET_TARGET_FRAMEWORK` or +:variable:`CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION`. If both are set, +the latter is ignored. diff --git a/Help/prop_tgt/ENABLE_EXPORTS.rst b/Help/prop_tgt/ENABLE_EXPORTS.rst new file mode 100644 index 0000000..0b1064a --- /dev/null +++ b/Help/prop_tgt/ENABLE_EXPORTS.rst @@ -0,0 +1,31 @@ +ENABLE_EXPORTS +-------------- + +Specify whether an executable exports 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. +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 new file mode 100644 index 0000000..f0200f3 --- /dev/null +++ b/Help/prop_tgt/EXCLUDE_FROM_ALL.rst @@ -0,0 +1,28 @@ +EXCLUDE_FROM_ALL +---------------- + +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. + +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, it may still be listed +in an :command:`install(TARGETS)` command, but the user is responsible for +ensuring that the target's build artifacts are not missing or outdated when +an install is performed. + +This property may use "generator expressions" with the syntax ``$<...>``. See +the :manual:`cmake-generator-expressions(7)` manual for available expressions. + +Only the "Ninja Multi-Config" generator supports a property value that varies by +configuration. For all other generators the value of this property must be the +same for all configurations. diff --git a/Help/prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD.rst b/Help/prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD.rst new file mode 100644 index 0000000..664704b --- /dev/null +++ b/Help/prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD.rst @@ -0,0 +1,8 @@ +EXCLUDE_FROM_DEFAULT_BUILD +-------------------------- + +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``. diff --git a/Help/prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD_CONFIG.rst b/Help/prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD_CONFIG.rst new file mode 100644 index 0000000..ad1021a --- /dev/null +++ b/Help/prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD_CONFIG.rst @@ -0,0 +1,10 @@ +EXCLUDE_FROM_DEFAULT_BUILD_<CONFIG> +----------------------------------- + +Per-configuration version of target exclusion from ``Build Solution``. + +This is the configuration-specific version of +: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_COMPILE_COMMANDS.rst b/Help/prop_tgt/EXPORT_COMPILE_COMMANDS.rst new file mode 100644 index 0000000..0b1145c --- /dev/null +++ b/Help/prop_tgt/EXPORT_COMPILE_COMMANDS.rst @@ -0,0 +1,9 @@ +EXPORT_COMPILE_COMMANDS +----------------------- + +.. versionadded:: 3.20 + +Enable/Disable output of compile commands during generation for a target. + +This property is initialized by the value of the variable +:variable:`CMAKE_EXPORT_COMPILE_COMMANDS` if it is set when a target is created. diff --git a/Help/prop_tgt/EXPORT_NAME.rst b/Help/prop_tgt/EXPORT_NAME.rst new file mode 100644 index 0000000..0e021d0 --- /dev/null +++ b/Help/prop_tgt/EXPORT_NAME.rst @@ -0,0 +1,8 @@ +EXPORT_NAME +----------- + +Exported name for target files. + +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 0000000..2d54f8b --- /dev/null +++ b/Help/prop_tgt/EXPORT_PROPERTIES.rst @@ -0,0 +1,24 @@ +EXPORT_PROPERTIES +----------------- + +.. versionadded:: 3.12 + +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. + +.. note:: + + Since CMake 3.19, :ref:`Interface Libraries` may have arbitrary + target properties. If a project exports an interface library + with custom properties, the resulting package may not work with + dependents configured by older versions of CMake that reject the + custom properties. diff --git a/Help/prop_tgt/EchoString.rst b/Help/prop_tgt/EchoString.rst new file mode 100644 index 0000000..352d062 --- /dev/null +++ b/Help/prop_tgt/EchoString.rst @@ -0,0 +1,7 @@ +EchoString +---------- + +A message to be displayed 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 new file mode 100644 index 0000000..f6be9e6 --- /dev/null +++ b/Help/prop_tgt/FOLDER.rst @@ -0,0 +1,13 @@ +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 +will appear next to each other in a folder of that name. To nest +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 new file mode 100644 index 0000000..3dff1be --- /dev/null +++ b/Help/prop_tgt/FRAMEWORK.rst @@ -0,0 +1,37 @@ +FRAMEWORK +--------- + +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 macOS and iOS. It will have the +directory structure required for a framework and will be suitable to +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 macOS see also the :prop_tgt:`FRAMEWORK_VERSION` target property. + +Example of creation ``dynamicFramework``: + +.. code-block:: cmake + + add_library(dynamicFramework SHARED + dynamicFramework.c + dynamicFramework.h + ) + set_target_properties(dynamicFramework PROPERTIES + FRAMEWORK TRUE + FRAMEWORK_VERSION C + MACOSX_FRAMEWORK_IDENTIFIER com.cmake.dynamicFramework + MACOSX_FRAMEWORK_INFO_PLIST Info.plist + # "current version" in semantic format in Mach-O binary file + VERSION 16.4.0 + # "compatibility version" in semantic format in Mach-O binary file + SOVERSION 1.0.0 + PUBLIC_HEADER dynamicFramework.h + XCODE_ATTRIBUTE_CODE_SIGN_IDENTITY "iPhone Developer" + ) diff --git a/Help/prop_tgt/FRAMEWORK_MULTI_CONFIG_POSTFIX_CONFIG.rst b/Help/prop_tgt/FRAMEWORK_MULTI_CONFIG_POSTFIX_CONFIG.rst new file mode 100644 index 0000000..84d0c1e --- /dev/null +++ b/Help/prop_tgt/FRAMEWORK_MULTI_CONFIG_POSTFIX_CONFIG.rst @@ -0,0 +1,28 @@ +FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG> +--------------------------------------- + +.. versionadded:: 3.18 + +Postfix to append to the framework file name for configuration ``<CONFIG>``, +when using a multi-config generator (like Xcode and Ninja Multi-Config). + +When building with configuration ``<CONFIG>`` the value of this property +is appended to the framework file name built on disk. + +For example, given a framework called ``my_fw``, a value of ``_debug`` +for the ``FRAMEWORK_MULTI_CONFIG_POSTFIX_DEBUG`` property, and +``Debug;Release`` in :variable:`CMAKE_CONFIGURATION_TYPES`, the following +relevant files would be created for the ``Debug`` and ``Release`` +configurations: + +- ``Release/my_fw.framework/my_fw`` +- ``Release/my_fw.framework/Versions/A/my_fw`` +- ``Debug/my_fw.framework/my_fw_debug`` +- ``Debug/my_fw.framework/Versions/A/my_fw_debug`` + +For framework targets, this property is initialized by the value of the +:variable:`CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>` variable if it +is set when a target is created. + +This property is ignored for non-framework targets, and when using single +config generators. diff --git a/Help/prop_tgt/FRAMEWORK_VERSION.rst b/Help/prop_tgt/FRAMEWORK_VERSION.rst new file mode 100644 index 0000000..38b8137 --- /dev/null +++ b/Help/prop_tgt/FRAMEWORK_VERSION.rst @@ -0,0 +1,10 @@ +FRAMEWORK_VERSION +----------------- + +.. versionadded:: 3.4 + +Version of a framework created using the :prop_tgt:`FRAMEWORK` target +property (e.g. ``A``). + +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 new file mode 100644 index 0000000..8704e5f --- /dev/null +++ b/Help/prop_tgt/Fortran_FORMAT.rst @@ -0,0 +1,11 @@ +Fortran_FORMAT +-------------- + +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`` +property to change the format of a specific source file. If the +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 new file mode 100644 index 0000000..84029e4 --- /dev/null +++ b/Help/prop_tgt/Fortran_MODULE_DIRECTORY.rst @@ -0,0 +1,25 @@ +Fortran_MODULE_DIRECTORY +------------------------ + +Specify output directory for Fortran modules provided by the target. + +If the target contains Fortran source files that provide modules and +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 +:variable:`CMAKE_Fortran_MODULE_DIRECTORY` is set when a target is created its +value is used to initialize this property. + +When using one of the :ref:`Visual Studio Generators` with the Intel Fortran +plugin installed in Visual Studio, a subdirectory named after the +configuration will be appended to the path where modules are created. +For example, if ``Fortran_MODULE_DIRECTORY`` is set to ``C:/some/path``, +modules will end up in ``C:/some/path/Debug`` (or +``C:/some/path/Release`` etc.) when an Intel Fortran ``.vfproj`` file is +generated, and in ``C:/some/path`` when any other generator is used. + +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 +:prop_tgt:`INCLUDE_DIRECTORIES` regardless of this property. diff --git a/Help/prop_tgt/Fortran_PREPROCESS.rst b/Help/prop_tgt/Fortran_PREPROCESS.rst new file mode 100644 index 0000000..e7e2fba --- /dev/null +++ b/Help/prop_tgt/Fortran_PREPROCESS.rst @@ -0,0 +1,25 @@ +Fortran_PREPROCESS +------------------ + +.. versionadded:: 3.18 + +Control whether the Fortran source file should be unconditionally +preprocessed. + +If unset or empty, rely on the compiler to determine whether the file +should be preprocessed. If explicitly set to ``OFF`` then the file does not +need to be preprocessed. If explicitly set to ``ON``, then the file does +need to be preprocessed as part of the compilation step. + +When using the :generator:`Ninja` generator, all source files are +first preprocessed in order to generate module dependency +information. Setting this property to ``OFF`` will make ``Ninja`` +skip this step. + +Use the source-specific :prop_sf:`Fortran_PREPROCESS` property if a single +file needs to be preprocessed. If the variable +:variable:`CMAKE_Fortran_PREPROCESS` is set when a target is created its +value is used to initialize this property. + +.. note:: For some compilers, ``NAG``, ``PGI`` and ``Solaris Studio``, + setting this to ``OFF`` will have no effect. diff --git a/Help/prop_tgt/GENERATOR_FILE_NAME.rst b/Help/prop_tgt/GENERATOR_FILE_NAME.rst new file mode 100644 index 0000000..a486105 --- /dev/null +++ b/Help/prop_tgt/GENERATOR_FILE_NAME.rst @@ -0,0 +1,9 @@ +GENERATOR_FILE_NAME +------------------- + +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 +: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 0000000..cccd087 --- /dev/null +++ b/Help/prop_tgt/GHS_INTEGRITY_APP.rst @@ -0,0 +1,12 @@ +GHS_INTEGRITY_APP +----------------- + +.. versionadded:: 3.14 + +``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 0000000..fe6b8e6 --- /dev/null +++ b/Help/prop_tgt/GHS_NO_SOURCE_GROUP_FILE.rst @@ -0,0 +1,15 @@ +GHS_NO_SOURCE_GROUP_FILE +------------------------ + +.. versionadded:: 3.14 + +``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 new file mode 100644 index 0000000..a09ebbf --- /dev/null +++ b/Help/prop_tgt/GNUtoMS.rst @@ -0,0 +1,17 @@ +GNUtoMS +------- + +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 :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 +value is used to initialize this property. The variable must be set +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 new file mode 100644 index 0000000..15199b1 --- /dev/null +++ b/Help/prop_tgt/HAS_CXX.rst @@ -0,0 +1,7 @@ +HAS_CXX +------- + +Link the target using the C++ linker tool (obsolete). + +This is equivalent to setting the :prop_tgt:`LINKER_LANGUAGE` +property to ``CXX``. diff --git a/Help/prop_tgt/IMPLICIT_DEPENDS_INCLUDE_TRANSFORM.rst b/Help/prop_tgt/IMPLICIT_DEPENDS_INCLUDE_TRANSFORM.rst new file mode 100644 index 0000000..f7e366a --- /dev/null +++ b/Help/prop_tgt/IMPLICIT_DEPENDS_INCLUDE_TRANSFORM.rst @@ -0,0 +1,32 @@ +IMPLICIT_DEPENDS_INCLUDE_TRANSFORM +---------------------------------- + +Specify ``#include`` line transforms for dependencies in a target. + +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 +replaced by the value given with the macro argument substituted for +``%``. For example, the entry + +:: + + MYDIR(%)=<mydir/%> + +will convert lines of the form + +:: + + #include MYDIR(myheader.h) + +to + +:: + + #include <mydir/myheader.h> + +allowing the dependency to be followed. + +This property applies to sources in the target on which it is set. diff --git a/Help/prop_tgt/IMPORTED.rst b/Help/prop_tgt/IMPORTED.rst new file mode 100644 index 0000000..22d28aa --- /dev/null +++ b/Help/prop_tgt/IMPORTED.rst @@ -0,0 +1,8 @@ +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`. +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 0000000..8c20e07 --- /dev/null +++ b/Help/prop_tgt/IMPORTED_COMMON_LANGUAGE_RUNTIME.rst @@ -0,0 +1,10 @@ +IMPORTED_COMMON_LANGUAGE_RUNTIME +-------------------------------- + +.. versionadded:: 3.12 + +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_CONFIGURATIONS.rst b/Help/prop_tgt/IMPORTED_CONFIGURATIONS.rst new file mode 100644 index 0000000..6de1baa --- /dev/null +++ b/Help/prop_tgt/IMPORTED_CONFIGURATIONS.rst @@ -0,0 +1,11 @@ +IMPORTED_CONFIGURATIONS +----------------------- + +Configurations provided for an IMPORTED target. + +Set this to the list of configuration names available for an IMPORTED +target. The names correspond to configurations defined in the project +from which the target is imported. If the importing project uses a +different set of configurations the names may be mapped using the +MAP_IMPORTED_CONFIG_<CONFIG> property. Ignored for non-imported +targets. diff --git a/Help/prop_tgt/IMPORTED_GLOBAL.rst b/Help/prop_tgt/IMPORTED_GLOBAL.rst new file mode 100644 index 0000000..176127f --- /dev/null +++ b/Help/prop_tgt/IMPORTED_GLOBAL.rst @@ -0,0 +1,32 @@ +IMPORTED_GLOBAL +--------------- + +.. versionadded:: 3.11 + +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. + +.. note:: + + 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. + +.. note:: + + Local :ref:`ALIAS targets <Alias Targets>` created before promoting an + :ref:`IMPORTED target <Imported Targets>` from ``LOCAL`` to ``GLOBAL``, keep + their initial scope (see :prop_tgt:`ALIAS_GLOBAL` target property). diff --git a/Help/prop_tgt/IMPORTED_IMPLIB.rst b/Help/prop_tgt/IMPORTED_IMPLIB.rst new file mode 100644 index 0000000..c8b6fde --- /dev/null +++ b/Help/prop_tgt/IMPORTED_IMPLIB.rst @@ -0,0 +1,9 @@ +IMPORTED_IMPLIB +--------------- + +Full path to the import library for an ``IMPORTED`` target. + +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 new file mode 100644 index 0000000..5debabc --- /dev/null +++ b/Help/prop_tgt/IMPORTED_IMPLIB_CONFIG.rst @@ -0,0 +1,7 @@ +IMPORTED_IMPLIB_<CONFIG> +------------------------ + +<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_LIBNAME.rst b/Help/prop_tgt/IMPORTED_LIBNAME.rst new file mode 100644 index 0000000..7a83906 --- /dev/null +++ b/Help/prop_tgt/IMPORTED_LIBNAME.rst @@ -0,0 +1,25 @@ +IMPORTED_LIBNAME +---------------- + +.. versionadded:: 3.8 + +Specify the link library name for an :ref:`imported <Imported Targets>` +:ref:`Interface Library <Interface Libraries>`. + +An interface library builds no library file itself but does specify +usage requirements for its consumers. The ``IMPORTED_LIBNAME`` +property may be set to specify a single library name to be placed +on the link line in place of the interface library target name as +a requirement for using the interface. + +This property is intended for use in naming libraries provided by +a platform SDK for which the full path to a library file may not +be known. The value may be a plain library name such as ``foo`` +but may *not* be a path (e.g. ``/usr/lib/libfoo.so``) or a flag +(e.g. ``-Wl,...``). The name is never treated as a library target +name even if it happens to name one. + +The ``IMPORTED_LIBNAME`` property is allowed only on +:ref:`imported <Imported Targets>` :ref:`Interface Libraries` +and is rejected on targets of other types (for which +the :prop_tgt:`IMPORTED_LOCATION` target property may be used). diff --git a/Help/prop_tgt/IMPORTED_LIBNAME_CONFIG.rst b/Help/prop_tgt/IMPORTED_LIBNAME_CONFIG.rst new file mode 100644 index 0000000..df64769 --- /dev/null +++ b/Help/prop_tgt/IMPORTED_LIBNAME_CONFIG.rst @@ -0,0 +1,9 @@ +IMPORTED_LIBNAME_<CONFIG> +------------------------- + +.. versionadded:: 3.8 + +<CONFIG>-specific version of :prop_tgt:`IMPORTED_LIBNAME` 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 new file mode 100644 index 0000000..f7e2165 --- /dev/null +++ b/Help/prop_tgt/IMPORTED_LINK_DEPENDENT_LIBRARIES.rst @@ -0,0 +1,14 @@ +IMPORTED_LINK_DEPENDENT_LIBRARIES +--------------------------------- + +Dependent shared libraries of an imported shared library. + +Shared libraries may be linked to other shared libraries as part of +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 :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 new file mode 100644 index 0000000..5b9c513 --- /dev/null +++ b/Help/prop_tgt/IMPORTED_LINK_DEPENDENT_LIBRARIES_CONFIG.rst @@ -0,0 +1,8 @@ +IMPORTED_LINK_DEPENDENT_LIBRARIES_<CONFIG> +------------------------------------------ + +<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 +overrides the generic property for the named configuration. diff --git a/Help/prop_tgt/IMPORTED_LINK_INTERFACE_LANGUAGES.rst b/Help/prop_tgt/IMPORTED_LINK_INTERFACE_LANGUAGES.rst new file mode 100644 index 0000000..4ed4281 --- /dev/null +++ b/Help/prop_tgt/IMPORTED_LINK_INTERFACE_LANGUAGES.rst @@ -0,0 +1,14 @@ +IMPORTED_LINK_INTERFACE_LANGUAGES +--------------------------------- + +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 +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 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 new file mode 100644 index 0000000..40fcf7f --- /dev/null +++ b/Help/prop_tgt/IMPORTED_LINK_INTERFACE_LANGUAGES_CONFIG.rst @@ -0,0 +1,8 @@ +IMPORTED_LINK_INTERFACE_LANGUAGES_<CONFIG> +------------------------------------------ + +<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 +overrides the generic property for the named configuration. diff --git a/Help/prop_tgt/IMPORTED_LINK_INTERFACE_LIBRARIES.rst b/Help/prop_tgt/IMPORTED_LINK_INTERFACE_LIBRARIES.rst new file mode 100644 index 0000000..527cf2e --- /dev/null +++ b/Help/prop_tgt/IMPORTED_LINK_INTERFACE_LIBRARIES.rst @@ -0,0 +1,16 @@ +IMPORTED_LINK_INTERFACE_LIBRARIES +--------------------------------- + +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 +will be included on the link line for the target. Unlike the +: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 +:prop_tgt:`INTERFACE_LINK_LIBRARIES` property. + +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 new file mode 100644 index 0000000..050fb1d --- /dev/null +++ b/Help/prop_tgt/IMPORTED_LINK_INTERFACE_LIBRARIES_CONFIG.rst @@ -0,0 +1,13 @@ +IMPORTED_LINK_INTERFACE_LIBRARIES_<CONFIG> +------------------------------------------ + +<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 +:prop_tgt:`INTERFACE_LINK_LIBRARIES` property. + +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 new file mode 100644 index 0000000..7a92d96 --- /dev/null +++ b/Help/prop_tgt/IMPORTED_LINK_INTERFACE_MULTIPLICITY.rst @@ -0,0 +1,6 @@ +IMPORTED_LINK_INTERFACE_MULTIPLICITY +------------------------------------ + +Repetition count for cycles of ``IMPORTED`` static libraries. + +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 new file mode 100644 index 0000000..758237b --- /dev/null +++ b/Help/prop_tgt/IMPORTED_LINK_INTERFACE_MULTIPLICITY_CONFIG.rst @@ -0,0 +1,7 @@ +IMPORTED_LINK_INTERFACE_MULTIPLICITY_<CONFIG> +--------------------------------------------- + +<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 new file mode 100644 index 0000000..ddd910a --- /dev/null +++ b/Help/prop_tgt/IMPORTED_LOCATION.rst @@ -0,0 +1,31 @@ +IMPORTED_LOCATION +----------------- + +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 +executables this is the location of the executable file. 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 application bundles on macOS this is the location of +the executable file inside ``Contents/MacOS`` within the bundle folder. +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`` +libraries this is the location of the file to be linked. Ignored for +non-imported targets. + +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 new file mode 100644 index 0000000..c5f5f04 --- /dev/null +++ b/Help/prop_tgt/IMPORTED_LOCATION_CONFIG.rst @@ -0,0 +1,7 @@ +IMPORTED_LOCATION_<CONFIG> +-------------------------- + +<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 new file mode 100644 index 0000000..cbb7642 --- /dev/null +++ b/Help/prop_tgt/IMPORTED_NO_SONAME.rst @@ -0,0 +1,9 @@ +IMPORTED_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 +platforms to prevent the linker from using the path to the library in +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 new file mode 100644 index 0000000..76fe471 --- /dev/null +++ b/Help/prop_tgt/IMPORTED_NO_SONAME_CONFIG.rst @@ -0,0 +1,7 @@ +IMPORTED_NO_SONAME_<CONFIG> +--------------------------- + +<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 new file mode 100644 index 0000000..f3577eb --- /dev/null +++ b/Help/prop_tgt/IMPORTED_OBJECTS.rst @@ -0,0 +1,93 @@ +IMPORTED_OBJECTS +---------------- + +.. versionadded:: 3.9 + +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>`. + +Ignored for non-imported targets. + +Projects may skip ``IMPORTED_OBJECTS`` if the configuration-specific +property :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>` is set instead, except in +situations as noted in the section below. + + +Xcode Generator Considerations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 3.20 + +For Apple platforms, a project may be built for more than one architecture. +This is controlled by the :variable:`CMAKE_OSX_ARCHITECTURES` variable. +For all but the :generator:`Xcode` generator, CMake invokes compilers once +per source file and passes multiple ``-arch`` flags, leading to a single +object file which will be a universal binary. Such object files work well +when listed in the ``IMPORTED_OBJECTS`` of a separate CMake build, even for +the :generator:`Xcode` generator. But producing such object files with the +:generator:`Xcode` generator is more difficult, since it invokes the compiler +once per architecture for each source file. Unlike the other generators, +it does not generate universal object file binaries. + +A further complication with the :generator:`Xcode` generator is that when +targeting device platforms (iOS, tvOS or watchOS), the :generator:`Xcode` +generator has the ability to use either the device or simulator SDK without +needing CMake to be re-run. The SDK can be selected at build time. +But since some architectures can be supported by both the device and the +simulator SDKs (e.g. ``arm64`` with Xcode 12 or later), not all combinations +can be represented in a single universal binary. The only solution in this +case is to have multiple object files. + +``IMPORTED_OBJECTS`` doesn't support generator expressions, so every file +it lists needs to be valid for every architecture and SDK. If incorporating +object files that are not universal binaries, the path and/or file name of +each object file has to somehow encapsulate the different architectures and +SDKs. With the :generator:`Xcode` generator, Xcode variables of the form +``$(...)`` can be used to represent these aspects and Xcode will substitute +the appropriate values at build time. CMake doesn't interpret these +variables and embeds them unchanged in the Xcode project file. +``$(CURRENT_ARCH)`` can be used to represent the architecture, while +``$(EFFECTIVE_PLATFORM_NAME)`` can be used to differentiate between SDKs. + +The following shows one example of how these two variables can be used to +refer to an object file whose location depends on both the SDK and the +architecture: + +.. code-block:: cmake + + add_library(someObjs OBJECT IMPORTED) + + set_property(TARGET someObjs PROPERTY IMPORTED_OBJECTS + # Quotes are required because of the () + "/path/to/somewhere/objects$(EFFECTIVE_PLATFORM_NAME)/$(CURRENT_ARCH)/func.o" + ) + + # Example paths: + # /path/to/somewhere/objects-iphoneos/arm64/func.o + # /path/to/somewhere/objects-iphonesimulator/x86_64/func.o + +In some cases, you may want to have configuration-specific object files +as well. The :variable:`CMAKE_CFG_INTDIR` variable can be a convenient +way of capturing this in combination with the SDK: + +.. code-block:: cmake + + add_library(someObjs OBJECT IMPORTED) + set_property(TARGET someObjs PROPERTY IMPORTED_OBJECTS + "/path/to/somewhere/${CMAKE_CFG_INTDIR}/$(CURRENT_ARCH)/func.o" + ) + + # Example paths: + # /path/to/somewhere/Release-iphoneos/arm64/func.o + # /path/to/somewhere/Debug-iphonesimulator/x86_64/func.o + +When any Xcode variable or :variable:`CMAKE_CFG_INTDIR` is used, CMake is +not able to fully evaluate the path(s) at configure time. One consequence +of this is that the configuration-specific +:prop_tgt:`IMPORTED_OBJECTS_<CONFIG>` properties cannot be used, since +CMake cannot determine whether an object file exists at a particular +``<CONFIG>`` location. The ``IMPORTED_OBJECTS`` property must be used for +these situations and the configuration-specific aspects of the path must be +handled by using :variable:`CMAKE_CFG_INTDIR` or with another Xcode variable +``$(CONFIGURATION)``. diff --git a/Help/prop_tgt/IMPORTED_OBJECTS_CONFIG.rst b/Help/prop_tgt/IMPORTED_OBJECTS_CONFIG.rst new file mode 100644 index 0000000..238395a --- /dev/null +++ b/Help/prop_tgt/IMPORTED_OBJECTS_CONFIG.rst @@ -0,0 +1,20 @@ +IMPORTED_OBJECTS_<CONFIG> +------------------------- + +.. versionadded:: 3.9 + +``<CONFIG>``-specific version of :prop_tgt:`IMPORTED_OBJECTS` property. + +Configuration names correspond to those provided by the project from +which the target is imported. + + +Xcode Generator Considerations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Do not use this ``<CONFIG>``-specific property if you need to use Xcode +variables like ``$(CURRENT_ARCH)`` or ``$(EFFECTIVE_PLATFORM_NAME)`` in +the value. The ``<CONFIG>``-specific properties will be ignored in such +cases because CMake cannot determine whether a file exists at the +configuration-specific path at configuration time. For such cases, use +:prop_tgt:`IMPORTED_OBJECTS` instead. diff --git a/Help/prop_tgt/IMPORTED_SONAME.rst b/Help/prop_tgt/IMPORTED_SONAME.rst new file mode 100644 index 0000000..bf0c3cb --- /dev/null +++ b/Help/prop_tgt/IMPORTED_SONAME.rst @@ -0,0 +1,8 @@ +IMPORTED_SONAME +--------------- + +The ``soname`` of an ``IMPORTED`` target of shared library type. + +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 new file mode 100644 index 0000000..59a9d1a --- /dev/null +++ b/Help/prop_tgt/IMPORTED_SONAME_CONFIG.rst @@ -0,0 +1,7 @@ +IMPORTED_SONAME_<CONFIG> +------------------------ + +<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 new file mode 100644 index 0000000..17e381b --- /dev/null +++ b/Help/prop_tgt/IMPORT_PREFIX.rst @@ -0,0 +1,9 @@ +IMPORT_PREFIX +------------- + +What comes before the import library name. + +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 new file mode 100644 index 0000000..9307115 --- /dev/null +++ b/Help/prop_tgt/IMPORT_SUFFIX.rst @@ -0,0 +1,9 @@ +IMPORT_SUFFIX +------------- + +What comes after the 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 new file mode 100644 index 0000000..b381d1d --- /dev/null +++ b/Help/prop_tgt/INCLUDE_DIRECTORIES.rst @@ -0,0 +1,24 @@ +INCLUDE_DIRECTORIES +------------------- + +List of preprocessor include file search directories. + +This property specifies the list of directories given so far to the +:command:`target_include_directories` command. In addition to accepting +values from that command, values may be set directly on any +target using the :command:`set_property` command. A target gets its +initial value for this property from the value of the +:prop_dir:`INCLUDE_DIRECTORIES` directory property. Both directory and +target property values are adjusted by calls to the +:command:`include_directories` command. + +The value of this property is used by the generators to set the include +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 :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 new file mode 100644 index 0000000..47a0037 --- /dev/null +++ b/Help/prop_tgt/INSTALL_NAME_DIR.rst @@ -0,0 +1,18 @@ +INSTALL_NAME_DIR +---------------- + +Directory name for installed targets on Apple platforms. + +``INSTALL_NAME_DIR`` is a string specifying the directory portion of the +"install_name" field of shared libraries on Apple platforms for +installed targets. When not set, the default directory used is determined +by :prop_tgt:`MACOSX_RPATH`. Policies :policy:`CMP0068` and :policy:`CMP0042` +are also relevant. + +This property is initialized by the value of the variable +:variable:`CMAKE_INSTALL_NAME_DIR` if it is set when a target is +created. + +This property supports :manual:`generator expressions <cmake-generator-expressions(7)>`. +In particular, the :genex:`$<INSTALL_PREFIX>` generator expression can be +used to set the directory relative to the install-time prefix. 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 0000000..f41e41c --- /dev/null +++ b/Help/prop_tgt/INSTALL_REMOVE_ENVIRONMENT_RPATH.rst @@ -0,0 +1,18 @@ +INSTALL_REMOVE_ENVIRONMENT_RPATH +-------------------------------- + +.. versionadded:: 3.16 + +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 new file mode 100644 index 0000000..4549b92 --- /dev/null +++ b/Help/prop_tgt/INSTALL_RPATH.rst @@ -0,0 +1,16 @@ +INSTALL_RPATH +------------- + +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 :variable:`CMAKE_INSTALL_RPATH` if it is set when +a target is created. + +Because the rpath may contain ``${ORIGIN}``, which coincides with CMake syntax, +the contents of ``INSTALL_RPATH`` are properly escaped in the +``cmake_install.cmake`` script (see policy :policy:`CMP0095`.) + +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 new file mode 100644 index 0000000..d16a7a1 --- /dev/null +++ b/Help/prop_tgt/INSTALL_RPATH_USE_LINK_PATH.rst @@ -0,0 +1,14 @@ +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 append to the runtime search path (rpath) of installed binaries +any directories outside the project that are in the linker search path or +contain linked library files. The directories are appended after the +value of the :prop_tgt:`INSTALL_RPATH` target property. + +This property is initialized by the value of the variable +:variable:`CMAKE_INSTALL_RPATH_USE_LINK_PATH` if it is set when a target is +created. diff --git a/Help/prop_tgt/INTERFACE_AUTOUIC_OPTIONS.rst b/Help/prop_tgt/INTERFACE_AUTOUIC_OPTIONS.rst new file mode 100644 index 0000000..e97d293 --- /dev/null +++ b/Help/prop_tgt/INTERFACE_AUTOUIC_OPTIONS.rst @@ -0,0 +1,14 @@ +INTERFACE_AUTOUIC_OPTIONS +------------------------- + +List of interface options to pass to uic. + +Targets may populate this property to publish the options +required to use when invoking ``uic``. Consuming targets can add entries to their +own :prop_tgt:`AUTOUIC_OPTIONS` property such as +``$<TARGET_PROPERTY:foo,INTERFACE_AUTOUIC_OPTIONS>`` to use the uic options +specified in the interface of ``foo``. This is done automatically by +the :command:`target_link_libraries` command. + +This property supports generator expressions. See the +:manual:`cmake-generator-expressions(7)` manual for available expressions. diff --git a/Help/prop_tgt/INTERFACE_BUILD_PROPERTY.txt b/Help/prop_tgt/INTERFACE_BUILD_PROPERTY.txt new file mode 100644 index 0000000..4188b8d --- /dev/null +++ b/Help/prop_tgt/INTERFACE_BUILD_PROPERTY.txt @@ -0,0 +1,16 @@ + +List of public |property_name| requirements for a library. + +Targets may populate this property to publish the |property_name| +required to compile against the headers for the target. The |command_name| +command populates this property with values given to the ``PUBLIC`` and +``INTERFACE`` keywords. Projects may also get and set the property directly. + +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 |PROPERTY_INTERFACE_NAME| 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_COMPILE_DEFINITIONS.rst b/Help/prop_tgt/INTERFACE_COMPILE_DEFINITIONS.rst new file mode 100644 index 0000000..c74a319 --- /dev/null +++ b/Help/prop_tgt/INTERFACE_COMPILE_DEFINITIONS.rst @@ -0,0 +1,9 @@ +INTERFACE_COMPILE_DEFINITIONS +----------------------------- + +.. |property_name| replace:: compile definitions +.. |command_name| replace:: :command:`target_compile_definitions` +.. |PROPERTY_INTERFACE_NAME| replace:: ``INTERFACE_COMPILE_DEFINITIONS`` +.. |PROPERTY_LINK| replace:: :prop_tgt:`COMPILE_DEFINITIONS` +.. |PROPERTY_GENEX| replace:: ``$<TARGET_PROPERTY:foo,INTERFACE_COMPILE_DEFINITIONS>`` +.. include:: INTERFACE_BUILD_PROPERTY.txt diff --git a/Help/prop_tgt/INTERFACE_COMPILE_FEATURES.rst b/Help/prop_tgt/INTERFACE_COMPILE_FEATURES.rst new file mode 100644 index 0000000..0db3b0c --- /dev/null +++ b/Help/prop_tgt/INTERFACE_COMPILE_FEATURES.rst @@ -0,0 +1,14 @@ +INTERFACE_COMPILE_FEATURES +-------------------------- + +.. versionadded:: 3.1 + +.. |property_name| replace:: compile features +.. |command_name| replace:: :command:`target_compile_features` +.. |PROPERTY_INTERFACE_NAME| replace:: ``INTERFACE_COMPILE_FEATURES`` +.. |PROPERTY_LINK| replace:: :prop_tgt:`COMPILE_FEATURES` +.. |PROPERTY_GENEX| replace:: ``$<TARGET_PROPERTY:foo,INTERFACE_COMPILE_FEATURES>`` +.. include:: INTERFACE_BUILD_PROPERTY.txt + +See the :manual:`cmake-compile-features(7)` manual for information on compile +features and a list of supported compilers. diff --git a/Help/prop_tgt/INTERFACE_COMPILE_OPTIONS.rst b/Help/prop_tgt/INTERFACE_COMPILE_OPTIONS.rst new file mode 100644 index 0000000..7f0b385 --- /dev/null +++ b/Help/prop_tgt/INTERFACE_COMPILE_OPTIONS.rst @@ -0,0 +1,9 @@ +INTERFACE_COMPILE_OPTIONS +------------------------- + +.. |property_name| replace:: compile options +.. |command_name| replace:: :command:`target_compile_options` +.. |PROPERTY_INTERFACE_NAME| replace:: ``INTERFACE_COMPILE_OPTIONS`` +.. |PROPERTY_LINK| replace:: :prop_tgt:`COMPILE_OPTIONS` +.. |PROPERTY_GENEX| replace:: ``$<TARGET_PROPERTY:foo,INTERFACE_COMPILE_OPTIONS>`` +.. include:: INTERFACE_BUILD_PROPERTY.txt diff --git a/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst b/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst new file mode 100644 index 0000000..b1c40b2 --- /dev/null +++ b/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst @@ -0,0 +1,29 @@ +INTERFACE_INCLUDE_DIRECTORIES +----------------------------- + +.. |property_name| replace:: include directories +.. |command_name| replace:: :command:`target_include_directories` +.. |PROPERTY_INTERFACE_NAME| replace:: ``INTERFACE_INCLUDE_DIRECTORIES`` +.. |PROPERTY_LINK| replace:: :prop_tgt:`INCLUDE_DIRECTORIES` +.. |PROPERTY_GENEX| replace:: ``$<TARGET_PROPERTY:foo,INTERFACE_INCLUDE_DIRECTORIES>`` +.. include:: INTERFACE_BUILD_PROPERTY.txt + +Include directories 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 + + target_include_directories(mylib INTERFACE + $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib> + $<INSTALL_INTERFACE:include/mylib> # <prefix>/include/mylib + ) + +Creating Relocatable Packages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. |INTERFACE_PROPERTY_LINK| replace:: ``INTERFACE_INCLUDE_DIRECTORIES`` +.. include:: /include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt diff --git a/Help/prop_tgt/INTERFACE_LINK_DEPENDS.rst b/Help/prop_tgt/INTERFACE_LINK_DEPENDS.rst new file mode 100644 index 0000000..9c8275d --- /dev/null +++ b/Help/prop_tgt/INTERFACE_LINK_DEPENDS.rst @@ -0,0 +1,34 @@ +INTERFACE_LINK_DEPENDS +---------------------- + +.. versionadded:: 3.13 + +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 0000000..de1dabb --- /dev/null +++ b/Help/prop_tgt/INTERFACE_LINK_DIRECTORIES.rst @@ -0,0 +1,11 @@ +INTERFACE_LINK_DIRECTORIES +-------------------------- + +.. versionadded:: 3.13 + +.. |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 new file mode 100644 index 0000000..bf7f72f --- /dev/null +++ b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst @@ -0,0 +1,26 @@ +INTERFACE_LINK_LIBRARIES +------------------------ + +List public interface libraries for a library. + +This property contains the list of transitive link dependencies. When +the target is linked into another target using the +:command:`target_link_libraries` command, the libraries listed (and +recursively their link interface libraries) will be provided to the +other target also. This property is overridden by the +:prop_tgt:`LINK_INTERFACE_LIBRARIES` or +:prop_tgt:`LINK_INTERFACE_LIBRARIES_<CONFIG>` property if policy +:policy:`CMP0022` is ``OLD`` or unset. + +Contents of ``INTERFACE_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 + +Creating Relocatable Packages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. |INTERFACE_PROPERTY_LINK| replace:: ``INTERFACE_LINK_LIBRARIES`` +.. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt diff --git a/Help/prop_tgt/INTERFACE_LINK_OPTIONS.rst b/Help/prop_tgt/INTERFACE_LINK_OPTIONS.rst new file mode 100644 index 0000000..4245fe9 --- /dev/null +++ b/Help/prop_tgt/INTERFACE_LINK_OPTIONS.rst @@ -0,0 +1,11 @@ +INTERFACE_LINK_OPTIONS +---------------------- + +.. versionadded:: 3.13 + +.. |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 new file mode 100644 index 0000000..4336d71 --- /dev/null +++ b/Help/prop_tgt/INTERFACE_POSITION_INDEPENDENT_CODE.rst @@ -0,0 +1,22 @@ +INTERFACE_POSITION_INDEPENDENT_CODE +----------------------------------- + +Whether consumers need to create a position-independent target + +The ``INTERFACE_POSITION_INDEPENDENT_CODE`` property informs consumers of +this target whether they must set their +:prop_tgt:`POSITION_INDEPENDENT_CODE` property to ``ON``. If this +property is set to ``ON``, then the :prop_tgt:`POSITION_INDEPENDENT_CODE` +property on all consumers will be set to ``ON``. Similarly, if this +property is set to ``OFF``, then the :prop_tgt:`POSITION_INDEPENDENT_CODE` +property on all consumers will be set to ``OFF``. If this property is +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 0000000..2299264 --- /dev/null +++ b/Help/prop_tgt/INTERFACE_PRECOMPILE_HEADERS.rst @@ -0,0 +1,18 @@ +INTERFACE_PRECOMPILE_HEADERS +---------------------------- + +.. versionadded:: 3.16 + +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/INTERFACE_SOURCES.rst b/Help/prop_tgt/INTERFACE_SOURCES.rst new file mode 100644 index 0000000..759c482 --- /dev/null +++ b/Help/prop_tgt/INTERFACE_SOURCES.rst @@ -0,0 +1,20 @@ +INTERFACE_SOURCES +----------------- + +.. versionadded:: 3.1 + +List of interface sources to compile into consuming targets. + +Targets may populate this property to publish the sources +for consuming targets to compile. The :command:`target_sources` command +populates this property with values given to the ``PUBLIC`` and +``INTERFACE`` keywords. Projects may also get and set the property directly. + +When target dependencies are specified using :command:`target_link_libraries`, +CMake will read this property from all target dependencies to determine the +sources of the consumer. + +Contents of ``INTERFACE_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. diff --git a/Help/prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES.rst b/Help/prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES.rst new file mode 100644 index 0000000..a0a97ad --- /dev/null +++ b/Help/prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES.rst @@ -0,0 +1,28 @@ +INTERFACE_SYSTEM_INCLUDE_DIRECTORIES +------------------------------------ + +List of public system include directories for a library. + +Targets may populate this property to publish the include directories +which contain system headers, and therefore should not result in +compiler warnings. The :command:`target_include_directories(SYSTEM)` +command signature populates this property with values given to the +``PUBLIC`` and ``INTERFACE`` keywords. + +Projects may also get and set the property directly, but must be aware that +adding directories to this property does not make those directories used +during compilation. Adding directories to this property marks directories +as ``SYSTEM`` which otherwise would be used in a non-``SYSTEM`` manner. This +can appear similar to 'duplication', so prefer the +high-level :command:`target_include_directories(SYSTEM)` command and avoid +setting the property by low-level means. + +When target dependencies are specified using :command:`target_link_libraries`, +CMake will read this property from all target dependencies to mark the +same include directories as containing system headers. + +Contents of ``INTERFACE_SYSTEM_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. diff --git a/Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION.rst b/Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION.rst new file mode 100644 index 0000000..d3a5e94 --- /dev/null +++ b/Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION.rst @@ -0,0 +1,13 @@ +INTERPROCEDURAL_OPTIMIZATION +---------------------------- + +Enable interprocedural optimization for a target. + +If set to true, enables interprocedural optimizations if they are +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 +target is created. diff --git a/Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst b/Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst new file mode 100644 index 0000000..79d4604 --- /dev/null +++ b/Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst @@ -0,0 +1,12 @@ +INTERPROCEDURAL_OPTIMIZATION_<CONFIG> +------------------------------------- + +Per-configuration interprocedural optimization for a target. + +This is a per-configuration version of :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION`. +If set, this property overrides the generic property for the named +configuration. + +This property is initialized by the +:variable:`CMAKE_INTERPROCEDURAL_OPTIMIZATION_<CONFIG>` variable if it is set +when a target is created. diff --git a/Help/prop_tgt/IOS_INSTALL_COMBINED.rst b/Help/prop_tgt/IOS_INSTALL_COMBINED.rst new file mode 100644 index 0000000..92d60dc --- /dev/null +++ b/Help/prop_tgt/IOS_INSTALL_COMBINED.rst @@ -0,0 +1,19 @@ +IOS_INSTALL_COMBINED +-------------------- + +.. versionadded:: 3.5 + +Build a combined (device and simulator) target when installing. + +When this property is set to set to false (which is the default) then it will +either be built with the device SDK or the simulator SDK depending on the SDK +set. But if this property is set to true then the target will at install time +also be built for the corresponding SDK and combined into one library. + +.. note:: + + If a selected architecture is available for both: device SDK and simulator + SDK it will be built for the SDK selected by :variable:`CMAKE_OSX_SYSROOT` + and removed from the corresponding SDK. + +This feature requires at least Xcode version 6. diff --git a/Help/prop_tgt/ISPC_HEADER_DIRECTORY.rst b/Help/prop_tgt/ISPC_HEADER_DIRECTORY.rst new file mode 100644 index 0000000..2a3a8bc --- /dev/null +++ b/Help/prop_tgt/ISPC_HEADER_DIRECTORY.rst @@ -0,0 +1,13 @@ +ISPC_HEADER_DIRECTORY +--------------------- + +.. versionadded:: 3.19 + +Specify relative output directory for ISPC headers provided by the target. + +If the target contains ISPC source files, this specifies the directory in which +the generated headers will be placed. Relative paths are treated with respect to +the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. When this property is not set, the +headers will be placed a generator defined build directory. If the variable +:variable:`CMAKE_ISPC_HEADER_DIRECTORY` is set when a target is created +its value is used to initialize this property. diff --git a/Help/prop_tgt/ISPC_HEADER_SUFFIX.rst b/Help/prop_tgt/ISPC_HEADER_SUFFIX.rst new file mode 100644 index 0000000..6397e55 --- /dev/null +++ b/Help/prop_tgt/ISPC_HEADER_SUFFIX.rst @@ -0,0 +1,14 @@ +ISPC_HEADER_SUFFIX +------------------ + +.. versionadded:: 3.19.2 + +Specify output suffix to be used for ISPC generated headers provided by the target. + +This property is initialized by the value of the :variable:`CMAKE_ISPC_HEADER_SUFFIX` +variable if it is set when a target is created. + +If the target contains ISPC source files, this specifies the header suffix to +be used for the generated headers. + +The default value is ``_ispc.h``. diff --git a/Help/prop_tgt/ISPC_INSTRUCTION_SETS.rst b/Help/prop_tgt/ISPC_INSTRUCTION_SETS.rst new file mode 100644 index 0000000..cad116f --- /dev/null +++ b/Help/prop_tgt/ISPC_INSTRUCTION_SETS.rst @@ -0,0 +1,21 @@ +ISPC_INSTRUCTION_SETS +--------------------- + +.. versionadded:: 3.19 + +List of instruction set architectures to generate code for. + +This property is initialized by the value of the :variable:`CMAKE_ISPC_INSTRUCTION_SETS` +variable if it is set when a target is created. + +The ``ISPC_INSTRUCTION_SETS`` target property must be used when generating for multiple +instruction sets so that CMake can track what object files will be generated. + +Examples +^^^^^^^^ + +.. code-block:: cmake + + set_property(TARGET tgt PROPERTY ISPC_INSTRUCTION_SETS avx2-i32x4 avx512skx-i32x835) + +Generates code for avx2 and avx512skx target architectures. diff --git a/Help/prop_tgt/JOB_POOL_COMPILE.rst b/Help/prop_tgt/JOB_POOL_COMPILE.rst new file mode 100644 index 0000000..5d8e940 --- /dev/null +++ b/Help/prop_tgt/JOB_POOL_COMPILE.rst @@ -0,0 +1,17 @@ +JOB_POOL_COMPILE +---------------- + +Ninja only: Pool used for compiling. + +The number of parallel compile processes could be limited by defining +pools with the global :prop_gbl:`JOB_POOLS` +property and then specifying here the pool name. + +For instance: + +.. code-block:: cmake + + set_property(TARGET myexe PROPERTY JOB_POOL_COMPILE ten_jobs) + +This property is initialized by the value of +:variable:`CMAKE_JOB_POOL_COMPILE`. diff --git a/Help/prop_tgt/JOB_POOL_LINK.rst b/Help/prop_tgt/JOB_POOL_LINK.rst new file mode 100644 index 0000000..6535333 --- /dev/null +++ b/Help/prop_tgt/JOB_POOL_LINK.rst @@ -0,0 +1,16 @@ +JOB_POOL_LINK +------------- + +Ninja only: Pool used for linking. + +The number of parallel link processes could be limited by defining +pools with the global :prop_gbl:`JOB_POOLS` +property and then specifying here the pool name. + +For instance: + +.. code-block:: cmake + + set_property(TARGET myexe PROPERTY JOB_POOL_LINK two_jobs) + +This property is initialized by the value of :variable:`CMAKE_JOB_POOL_LINK`. diff --git a/Help/prop_tgt/JOB_POOL_PRECOMPILE_HEADER.rst b/Help/prop_tgt/JOB_POOL_PRECOMPILE_HEADER.rst new file mode 100644 index 0000000..42cace0 --- /dev/null +++ b/Help/prop_tgt/JOB_POOL_PRECOMPILE_HEADER.rst @@ -0,0 +1,23 @@ +JOB_POOL_PRECOMPILE_HEADER +-------------------------- + +.. versionadded:: 3.17 + +Ninja only: Pool used for generating pre-compiled headers. + +The number of parallel compile processes could be limited by defining +pools with the global :prop_gbl:`JOB_POOLS` +property and then specifying here the pool name. + +For instance: + +.. code-block:: cmake + + set_property(TARGET myexe PROPERTY JOB_POOL_PRECOMPILE_HEADER two_jobs) + +This property is initialized by the value of +:variable:`CMAKE_JOB_POOL_PRECOMPILE_HEADER`. + +If neither :prop_tgt:`JOB_POOL_PRECOMPILE_HEADER` nor +:variable:`CMAKE_JOB_POOL_PRECOMPILE_HEADER` are set then +:prop_tgt:`JOB_POOL_COMPILE` will be used for this task. diff --git a/Help/prop_tgt/LABELS.rst b/Help/prop_tgt/LABELS.rst new file mode 100644 index 0000000..5e46469 --- /dev/null +++ b/Help/prop_tgt/LABELS.rst @@ -0,0 +1,6 @@ +LABELS +------ + +Specify a list of text labels associated with a target. + +Target label semantics are currently unspecified. diff --git a/Help/prop_tgt/LANG_CLANG_TIDY.rst b/Help/prop_tgt/LANG_CLANG_TIDY.rst new file mode 100644 index 0000000..af16d3c --- /dev/null +++ b/Help/prop_tgt/LANG_CLANG_TIDY.rst @@ -0,0 +1,15 @@ +<LANG>_CLANG_TIDY +----------------- + +.. versionadded:: 3.6 + +This property is implemented only when ``<LANG>`` is ``C``, ``CXX``, ``OBJC`` or ``OBJCXX``. + +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. + +This property is initialized by the value of +the :variable:`CMAKE_<LANG>_CLANG_TIDY` variable if it is set +when a target is created. diff --git a/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst b/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst new file mode 100644 index 0000000..16be3cd --- /dev/null +++ b/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst @@ -0,0 +1,16 @@ +<LANG>_COMPILER_LAUNCHER +------------------------ + +.. versionadded:: 3.4 + +This property is implemented only when ``<LANG>`` is ``C``, ``CXX``, +``Fortran``, ``ISPC``, ``OBJC``, ``OBJCXX``, or ``CUDA``. + +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. + +This property is initialized by the value of +the :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER` variable if it is set +when a target is created. diff --git a/Help/prop_tgt/LANG_CPPCHECK.rst b/Help/prop_tgt/LANG_CPPCHECK.rst new file mode 100644 index 0000000..80acbc0 --- /dev/null +++ b/Help/prop_tgt/LANG_CPPCHECK.rst @@ -0,0 +1,17 @@ +<LANG>_CPPCHECK +--------------- + +.. versionadded:: 3.10 + +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 new file mode 100644 index 0000000..be6db46 --- /dev/null +++ b/Help/prop_tgt/LANG_CPPLINT.rst @@ -0,0 +1,15 @@ +<LANG>_CPPLINT +-------------- + +.. versionadded:: 3.8 + +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 ``cpplint`` style checker. The :ref:`Makefile Generators` and the +:generator:`Ninja` generator will run ``cpplint`` along with the compiler +and report any problems. + +This property is initialized by the value of the +:variable:`CMAKE_<LANG>_CPPLINT` variable if it is set when a target is +created. diff --git a/Help/prop_tgt/LANG_INCLUDE_WHAT_YOU_USE.rst b/Help/prop_tgt/LANG_INCLUDE_WHAT_YOU_USE.rst new file mode 100644 index 0000000..eebef56 --- /dev/null +++ b/Help/prop_tgt/LANG_INCLUDE_WHAT_YOU_USE.rst @@ -0,0 +1,15 @@ +<LANG>_INCLUDE_WHAT_YOU_USE +--------------------------- + +.. versionadded:: 3.3 + +This property is implemented only when ``<LANG>`` is ``C`` or ``CXX``. + +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. + +This property is initialized by the value of +the :variable:`CMAKE_<LANG>_INCLUDE_WHAT_YOU_USE` variable if it is set +when a target is created. diff --git a/Help/prop_tgt/LANG_VISIBILITY_PRESET.rst b/Help/prop_tgt/LANG_VISIBILITY_PRESET.rst new file mode 100644 index 0000000..5d34e20 --- /dev/null +++ b/Help/prop_tgt/LANG_VISIBILITY_PRESET.rst @@ -0,0 +1,13 @@ +<LANG>_VISIBILITY_PRESET +------------------------ + +Value for symbol visibility compile flags + +The ``<LANG>_VISIBILITY_PRESET`` property determines the value passed in a +visibility related compile option, such as ``-fvisibility=`` for ``<LANG>``. +This property affects compilation in sources of all types of targets +(subject to policy :policy:`CMP0063`). + +This property is initialized by the value of the +:variable:`CMAKE_<LANG>_VISIBILITY_PRESET` variable if it is set when a +target is created. diff --git a/Help/prop_tgt/LIBRARY_OUTPUT_DIRECTORY.rst b/Help/prop_tgt/LIBRARY_OUTPUT_DIRECTORY.rst new file mode 100644 index 0000000..9fbe904 --- /dev/null +++ b/Help/prop_tgt/LIBRARY_OUTPUT_DIRECTORY.rst @@ -0,0 +1,9 @@ +LIBRARY_OUTPUT_DIRECTORY +------------------------ + +.. |XXX| replace:: :ref:`LIBRARY <Library Output Artifacts>` +.. |xxx| replace:: library +.. |CMAKE_XXX_OUTPUT_DIRECTORY| replace:: :variable:`CMAKE_LIBRARY_OUTPUT_DIRECTORY` +.. include:: XXX_OUTPUT_DIRECTORY.txt + +See also the :prop_tgt:`LIBRARY_OUTPUT_DIRECTORY_<CONFIG>` target property. diff --git a/Help/prop_tgt/LIBRARY_OUTPUT_DIRECTORY_CONFIG.rst b/Help/prop_tgt/LIBRARY_OUTPUT_DIRECTORY_CONFIG.rst new file mode 100644 index 0000000..5cefc38 --- /dev/null +++ b/Help/prop_tgt/LIBRARY_OUTPUT_DIRECTORY_CONFIG.rst @@ -0,0 +1,17 @@ +LIBRARY_OUTPUT_DIRECTORY_<CONFIG> +--------------------------------- + +Per-configuration output directory for +:ref:`LIBRARY <Library Output Artifacts>` target files. + +This is a per-configuration version of the +:prop_tgt:`LIBRARY_OUTPUT_DIRECTORY` target property, 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_LIBRARY_OUTPUT_DIRECTORY_<CONFIG>` variable if +it is set when a target is created. + +Contents of ``LIBRARY_OUTPUT_DIRECTORY_<CONFIG>`` may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/prop_tgt/LIBRARY_OUTPUT_NAME.rst b/Help/prop_tgt/LIBRARY_OUTPUT_NAME.rst new file mode 100644 index 0000000..6027f7f --- /dev/null +++ b/Help/prop_tgt/LIBRARY_OUTPUT_NAME.rst @@ -0,0 +1,8 @@ +LIBRARY_OUTPUT_NAME +------------------- + +.. |XXX| replace:: :ref:`LIBRARY <Library Output Artifacts>` +.. |xxx| replace:: library +.. include:: XXX_OUTPUT_NAME.txt + +See also the :prop_tgt:`LIBRARY_OUTPUT_NAME_<CONFIG>` target property. diff --git a/Help/prop_tgt/LIBRARY_OUTPUT_NAME_CONFIG.rst b/Help/prop_tgt/LIBRARY_OUTPUT_NAME_CONFIG.rst new file mode 100644 index 0000000..1994c7b --- /dev/null +++ b/Help/prop_tgt/LIBRARY_OUTPUT_NAME_CONFIG.rst @@ -0,0 +1,8 @@ +LIBRARY_OUTPUT_NAME_<CONFIG> +---------------------------- + +Per-configuration output name for +:ref:`LIBRARY <Library Output Artifacts>` target files. + +This is the configuration-specific version of the +:prop_tgt:`LIBRARY_OUTPUT_NAME` target property. diff --git a/Help/prop_tgt/LINKER_LANGUAGE.rst b/Help/prop_tgt/LINKER_LANGUAGE.rst new file mode 100644 index 0000000..b0a572b --- /dev/null +++ b/Help/prop_tgt/LINKER_LANGUAGE.rst @@ -0,0 +1,14 @@ +LINKER_LANGUAGE +--------------- + +Specifies language whose compiler will invoke the linker. + +For executables, shared libraries, and modules, this sets the language +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 :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 new file mode 100644 index 0000000..e59d4c0 --- /dev/null +++ b/Help/prop_tgt/LINK_DEPENDS.rst @@ -0,0 +1,18 @@ +LINK_DEPENDS +------------ + +Additional files on which a target binary depends for linking. + +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 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_DEPENDS_NO_SHARED.rst b/Help/prop_tgt/LINK_DEPENDS_NO_SHARED.rst new file mode 100644 index 0000000..5c6778d --- /dev/null +++ b/Help/prop_tgt/LINK_DEPENDS_NO_SHARED.rst @@ -0,0 +1,14 @@ +LINK_DEPENDS_NO_SHARED +---------------------- + +Do not depend on linked shared library files. + +Set this property to true to tell CMake generators not to add +file-level dependencies on the shared library files linked by this +target. Modification to the shared libraries will not be sufficient +to re-link this target. Logical target-level dependencies will not be +affected so the linked shared libraries will still be brought up to +date before this target is built. + +This property is initialized by the value of the variable +CMAKE_LINK_DEPENDS_NO_SHARED if it is set when a target is created. diff --git a/Help/prop_tgt/LINK_DIRECTORIES.rst b/Help/prop_tgt/LINK_DIRECTORIES.rst new file mode 100644 index 0000000..67be494 --- /dev/null +++ b/Help/prop_tgt/LINK_DIRECTORIES.rst @@ -0,0 +1,20 @@ +LINK_DIRECTORIES +---------------- + +.. versionadded:: 3.13 + +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 new file mode 100644 index 0000000..92cd3c0 --- /dev/null +++ b/Help/prop_tgt/LINK_FLAGS.rst @@ -0,0 +1,16 @@ +LINK_FLAGS +---------- + +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, 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 new file mode 100644 index 0000000..68c3129 --- /dev/null +++ b/Help/prop_tgt/LINK_FLAGS_CONFIG.rst @@ -0,0 +1,11 @@ +LINK_FLAGS_<CONFIG> +------------------- + +Per-configuration linker flags for a ``SHARED`` library, ``MODULE`` or +``EXECUTABLE`` target. + +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_LIBRARIES.rst b/Help/prop_tgt/LINK_INTERFACE_LIBRARIES.rst new file mode 100644 index 0000000..2dcf45c --- /dev/null +++ b/Help/prop_tgt/LINK_INTERFACE_LIBRARIES.rst @@ -0,0 +1,31 @@ +LINK_INTERFACE_LIBRARIES +------------------------ + +List public interface libraries for a shared library or executable. + +By default linking to a shared library target transitively links to +targets with which the library itself was linked. For an executable +with exports (see the :prop_tgt:`ENABLE_EXPORTS` target property) no +default transitive link dependencies are used. This property replaces the default +transitive link dependencies with an explicit list. When the target +is linked into another target using the :command:`target_link_libraries` +command, the libraries listed (and recursively +their link interface libraries) will be provided to the other target +also. If the list is empty then no transitive link dependencies will +be incorporated when this target is linked into another target even if +the default set is non-empty. This property is initialized by the +value of the :variable:`CMAKE_LINK_INTERFACE_LIBRARIES` variable if it is +set when a target is created. This property is ignored for ``STATIC`` +libraries. + +This property is overridden by the :prop_tgt:`INTERFACE_LINK_LIBRARIES` +property if policy :policy:`CMP0022` is ``NEW``. + +This property is deprecated. Use :prop_tgt:`INTERFACE_LINK_LIBRARIES` +instead. + +Creating Relocatable Packages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. |INTERFACE_PROPERTY_LINK| replace:: ``LINK_INTERFACE_LIBRARIES`` +.. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt diff --git a/Help/prop_tgt/LINK_INTERFACE_LIBRARIES_CONFIG.rst b/Help/prop_tgt/LINK_INTERFACE_LIBRARIES_CONFIG.rst new file mode 100644 index 0000000..22ee5a6 --- /dev/null +++ b/Help/prop_tgt/LINK_INTERFACE_LIBRARIES_CONFIG.rst @@ -0,0 +1,20 @@ +LINK_INTERFACE_LIBRARIES_<CONFIG> +--------------------------------- + +Per-configuration list of public interface libraries for a target. + +This is the configuration-specific version of +:prop_tgt:`LINK_INTERFACE_LIBRARIES`. If set, this property completely +overrides the generic property for the named configuration. + +This property is overridden by the :prop_tgt:`INTERFACE_LINK_LIBRARIES` +property if policy :policy:`CMP0022` is ``NEW``. + +This property is deprecated. Use :prop_tgt:`INTERFACE_LINK_LIBRARIES` +instead. + +Creating Relocatable Packages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. |INTERFACE_PROPERTY_LINK| replace:: ``LINK_INTERFACE_LIBRARIES_<CONFIG>`` +.. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt diff --git a/Help/prop_tgt/LINK_INTERFACE_MULTIPLICITY.rst b/Help/prop_tgt/LINK_INTERFACE_MULTIPLICITY.rst new file mode 100644 index 0000000..b798af9 --- /dev/null +++ b/Help/prop_tgt/LINK_INTERFACE_MULTIPLICITY.rst @@ -0,0 +1,12 @@ +LINK_INTERFACE_MULTIPLICITY +--------------------------- + +Repetition count for ``STATIC`` libraries with cyclic dependencies. + +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 +the component at least twice. This property specifies the minimum +number of scans if it is larger than the default. CMake uses the +largest value specified by any target in a component. diff --git a/Help/prop_tgt/LINK_INTERFACE_MULTIPLICITY_CONFIG.rst b/Help/prop_tgt/LINK_INTERFACE_MULTIPLICITY_CONFIG.rst new file mode 100644 index 0000000..7c9461f --- /dev/null +++ b/Help/prop_tgt/LINK_INTERFACE_MULTIPLICITY_CONFIG.rst @@ -0,0 +1,8 @@ +LINK_INTERFACE_MULTIPLICITY_<CONFIG> +------------------------------------ + +Per-configuration repetition count for cycles of ``STATIC`` libraries. + +This is the configuration-specific version of +: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 new file mode 100644 index 0000000..d88e798 --- /dev/null +++ b/Help/prop_tgt/LINK_LIBRARIES.rst @@ -0,0 +1,19 @@ +LINK_LIBRARIES +-------------- + +List of direct link dependencies. + +This property specifies the list of libraries or targets which will be +used for linking. In addition to accepting values from the +:command:`target_link_libraries` command, values may be set directly on +any target using the :command:`set_property` command. + +The value of this property is used by the generators to set the link +libraries for the compiler. + +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 0000000..476e4a6 --- /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 wrap each + entry with the form ``::@(directory-id);...;::@``, where the ``::@`` is + literal 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 0000000..8c0dfc4 --- /dev/null +++ b/Help/prop_tgt/LINK_OPTIONS.rst @@ -0,0 +1,30 @@ +LINK_OPTIONS +------------ + +.. versionadded:: 3.13 + +List of options to use for the link step of shared library, module +and executable targets as well as the device link step. Targets that are static +libraries need to use the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property. + +These options are used for both normal linking and device linking +(see policy :policy:`CMP0105`). To control link options for normal and device +link steps, ``$<HOST_LINK>`` and ``$<DEVICE_LINK>`` +:manual:`generator expressions <cmake-generator-expressions(7)>` can be used. + +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 new file mode 100644 index 0000000..fecbb14 --- /dev/null +++ b/Help/prop_tgt/LINK_SEARCH_END_STATIC.rst @@ -0,0 +1,19 @@ +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. +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. + +This property is initialized by the value of the variable +:variable:`CMAKE_LINK_SEARCH_END_STATIC` if it is set +when a target is created. + +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 new file mode 100644 index 0000000..83cf231 --- /dev/null +++ b/Help/prop_tgt/LINK_SEARCH_START_STATIC.rst @@ -0,0 +1,20 @@ +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. +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`` +option). + +This property is initialized by the value of the variable + :variable:`CMAKE_LINK_SEARCH_START_STATIC` if it is set + when a target is created. + +See also :prop_tgt:`LINK_SEARCH_END_STATIC`. diff --git a/Help/prop_tgt/LINK_WHAT_YOU_USE.rst b/Help/prop_tgt/LINK_WHAT_YOU_USE.rst new file mode 100644 index 0000000..2ed93ad --- /dev/null +++ b/Help/prop_tgt/LINK_WHAT_YOU_USE.rst @@ -0,0 +1,17 @@ +LINK_WHAT_YOU_USE +--------------------------- + +.. versionadded:: 3.7 + +This is a boolean option that when set to ``TRUE`` will automatically run +``ldd -r -u`` on the target after it is linked. In addition, the linker flag +``-Wl,--no-as-needed`` will be passed to the target with the link command so +that all libraries specified on the command line will be linked into the +target. This will result in the link producing a list of libraries that +provide no symbols used by this target but are being linked to it. +This is only applicable to executable and shared library targets and +will only work when ld and ldd accept the flags used. + +This property is initialized by the value of +the :variable:`CMAKE_LINK_WHAT_YOU_USE` variable if it is set +when a target is created. diff --git a/Help/prop_tgt/LOCATION.rst b/Help/prop_tgt/LOCATION.rst new file mode 100644 index 0000000..d058064 --- /dev/null +++ b/Help/prop_tgt/LOCATION.rst @@ -0,0 +1,28 @@ +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. + +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 :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 +: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>)?``, +``(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 new file mode 100644 index 0000000..67de8ed --- /dev/null +++ b/Help/prop_tgt/LOCATION_CONFIG.rst @@ -0,0 +1,20 @@ +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 +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 +: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 :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/MACHO_COMPATIBILITY_VERSION.rst b/Help/prop_tgt/MACHO_COMPATIBILITY_VERSION.rst new file mode 100644 index 0000000..a24b255 --- /dev/null +++ b/Help/prop_tgt/MACHO_COMPATIBILITY_VERSION.rst @@ -0,0 +1,27 @@ +MACHO_COMPATIBILITY_VERSION +--------------------------- + +.. versionadded:: 3.17 + +What compatibility version number is this target for Mach-O binaries. + +For shared libraries on Mach-O systems (e.g. macOS, iOS) +the ``MACHO_COMPATIBILITY_VERSION`` property corresponds to the +*compatibility version* and :prop_tgt:`MACHO_CURRENT_VERSION` corresponds to +the *current version*. These are both embedded in the shared library binary +and can be checked with the ``otool -L <binary>`` command. + +It should be noted that the :prop_tgt:`MACHO_CURRENT_VERSION` and +``MACHO_COMPATIBILITY_VERSION`` properties do not affect the file +names or version-related symlinks that CMake generates for the library. +The :prop_tgt:`VERSION` and :prop_tgt:`SOVERSION` target properties still +control the file and symlink names. The ``install_name`` is also still +controlled by :prop_tgt:`SOVERSION`. + +When :prop_tgt:`MACHO_CURRENT_VERSION` and ``MACHO_COMPATIBILITY_VERSION`` +are not given, :prop_tgt:`VERSION` and :prop_tgt:`SOVERSION` are used for +the version details to be embedded in the binaries respectively. +The :prop_tgt:`MACHO_CURRENT_VERSION` and ``MACHO_COMPATIBILITY_VERSION`` +properties only need to be given if the project needs to decouple the file +and symlink naming from the version details embedded in the binaries +(e.g. to match libtool conventions). diff --git a/Help/prop_tgt/MACHO_CURRENT_VERSION.rst b/Help/prop_tgt/MACHO_CURRENT_VERSION.rst new file mode 100644 index 0000000..530f79b --- /dev/null +++ b/Help/prop_tgt/MACHO_CURRENT_VERSION.rst @@ -0,0 +1,27 @@ +MACHO_CURRENT_VERSION +--------------------- + +.. versionadded:: 3.17 + +What current version number is this target for Mach-O binaries. + +For shared libraries on Mach-O systems (e.g. macOS, iOS) +the :prop_tgt:`MACHO_COMPATIBILITY_VERSION` property corresponds to the +*compatibility version* and ``MACHO_CURRENT_VERSION`` corresponds to the +*current version*. These are both embedded in the shared library binary +and can be checked with the ``otool -L <binary>`` command. + +It should be noted that the ``MACHO_CURRENT_VERSION`` and +:prop_tgt:`MACHO_COMPATIBILITY_VERSION` properties do not affect the file +names or version-related symlinks that CMake generates for the library. +The :prop_tgt:`VERSION` and :prop_tgt:`SOVERSION` target properties still +control the file and symlink names. The ``install_name`` is also still +controlled by :prop_tgt:`SOVERSION`. + +When ``MACHO_CURRENT_VERSION`` and :prop_tgt:`MACHO_COMPATIBILITY_VERSION` +are not given, :prop_tgt:`VERSION` and :prop_tgt:`SOVERSION` are used for +the version details to be embedded in the binaries respectively. +The ``MACHO_CURRENT_VERSION`` and :prop_tgt:`MACHO_COMPATIBILITY_VERSION` +properties only need to be given if the project needs to decouple the file +and symlink naming from the version details embedded in the binaries +(e.g. to match libtool conventions). diff --git a/Help/prop_tgt/MACOSX_BUNDLE.rst b/Help/prop_tgt/MACOSX_BUNDLE.rst new file mode 100644 index 0000000..92bce53 --- /dev/null +++ b/Help/prop_tgt/MACOSX_BUNDLE.rst @@ -0,0 +1,12 @@ +MACOSX_BUNDLE +------------- + +Build an executable as an Application Bundle on macOS or iOS. + +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_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 new file mode 100644 index 0000000..443a645 --- /dev/null +++ b/Help/prop_tgt/MACOSX_BUNDLE_INFO_PLIST.rst @@ -0,0 +1,35 @@ +MACOSX_BUNDLE_INFO_PLIST +------------------------ + +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 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. + +The following target properties may be set to specify content to be +configured into the file: + +``MACOSX_BUNDLE_BUNDLE_NAME`` + Sets ``CFBundleName``. +``MACOSX_BUNDLE_BUNDLE_VERSION`` + Sets ``CFBundleVersion``. +``MACOSX_BUNDLE_COPYRIGHT`` + Sets ``NSHumanReadableCopyright``. +``MACOSX_BUNDLE_GUI_IDENTIFIER`` + Sets ``CFBundleIdentifier``. +``MACOSX_BUNDLE_ICON_FILE`` + Sets ``CFBundleIconFile``. +``MACOSX_BUNDLE_INFO_STRING`` + Sets ``CFBundleGetInfoString``. +``MACOSX_BUNDLE_LONG_VERSION_STRING`` + Sets ``CFBundleLongVersionString``. +``MACOSX_BUNDLE_SHORT_VERSION_STRING`` + Sets ``CFBundleShortVersionString``. + +CMake variables of the same name may be set to affect all targets in a +directory that do not have each specific property set. If a custom +``Info.plist`` is specified by this property it may of course hard-code +all the settings instead of using the target properties. diff --git a/Help/prop_tgt/MACOSX_FRAMEWORK_INFO_PLIST.rst b/Help/prop_tgt/MACOSX_FRAMEWORK_INFO_PLIST.rst new file mode 100644 index 0000000..82fdcc0 --- /dev/null +++ b/Help/prop_tgt/MACOSX_FRAMEWORK_INFO_PLIST.rst @@ -0,0 +1,27 @@ +MACOSX_FRAMEWORK_INFO_PLIST +--------------------------- + +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 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. + +The following target properties may be set to specify content to be +configured into the file: + +``MACOSX_FRAMEWORK_BUNDLE_VERSION`` + Sets ``CFBundleVersion``. +``MACOSX_FRAMEWORK_ICON_FILE`` + Sets ``CFBundleIconFile``. +``MACOSX_FRAMEWORK_IDENTIFIER`` + Sets ``CFBundleIdentifier``. +``MACOSX_FRAMEWORK_SHORT_VERSION_STRING`` + Sets ``CFBundleShortVersionString``. + +CMake variables of the same name may be set to affect all targets in a +directory that do not have each specific property set. If a custom +``Info.plist`` is specified by this property it may of course hard-code +all the settings instead of using the target properties. diff --git a/Help/prop_tgt/MACOSX_RPATH.rst b/Help/prop_tgt/MACOSX_RPATH.rst new file mode 100644 index 0000000..acd5a7a --- /dev/null +++ b/Help/prop_tgt/MACOSX_RPATH.rst @@ -0,0 +1,23 @@ +MACOSX_RPATH +------------ + +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`` +unless overridden by :prop_tgt:`INSTALL_NAME_DIR`. This indicates +the shared library is to be found at runtime using runtime +paths (rpaths). + +This property is initialized by the value of the variable +:variable:`CMAKE_MACOSX_RPATH` if it is set when a target is +created. + +Runtime paths will also be embedded in binaries using this target and +can be controlled by the :prop_tgt:`INSTALL_RPATH` target property on +the target linking to this target. + +Policy :policy:`CMP0042` was introduced to change the default value of +``MACOSX_RPATH`` to ``TRUE``. This is because use of ``@rpath`` is a +more flexible and powerful alternative to ``@executable_path`` and +``@loader_path``. diff --git a/Help/prop_tgt/MANUALLY_ADDED_DEPENDENCIES.rst b/Help/prop_tgt/MANUALLY_ADDED_DEPENDENCIES.rst new file mode 100644 index 0000000..72871b3 --- /dev/null +++ b/Help/prop_tgt/MANUALLY_ADDED_DEPENDENCIES.rst @@ -0,0 +1,10 @@ +MANUALLY_ADDED_DEPENDENCIES +--------------------------- + +.. versionadded:: 3.8 + +Get manually added dependencies to other top-level targets. + +This read-only property can be used to query all dependencies that +were added for this target with the :command:`add_dependencies` +command. diff --git a/Help/prop_tgt/MAP_IMPORTED_CONFIG_CONFIG.rst b/Help/prop_tgt/MAP_IMPORTED_CONFIG_CONFIG.rst new file mode 100644 index 0000000..266ccf0 --- /dev/null +++ b/Help/prop_tgt/MAP_IMPORTED_CONFIG_CONFIG.rst @@ -0,0 +1,70 @@ +MAP_IMPORTED_CONFIG_<CONFIG> +---------------------------- + +Map from project configuration to +:ref:`imported target <IMPORTED targets>`'s configuration. + +Set this to the list of configurations of an imported target that may +be used for the current project's ``<CONFIG>`` configuration. Targets +imported from another project may not provide the same set of +configuration names available in the current project. Setting this +property tells CMake what imported configurations are suitable for use +when building the ``<CONFIG>`` configuration. The first configuration in +the list found to be provided by the imported target (i.e. via +:prop_tgt:`IMPORTED_LOCATION_<CONFIG>` for the mapped-to ``<CONFIG>``) +is selected. As a special case, an empty list element refers to the +configuration-less imported target location +(i.e. :prop_tgt:`IMPORTED_LOCATION`). + +If this property is set and no matching configurations are available, +then the imported target is considered to be not found. This property +is ignored for non-imported targets. + +This property is initialized by the value of the +:variable:`CMAKE_MAP_IMPORTED_CONFIG_<CONFIG>` variable if it is set when a +target is created. + +Example +^^^^^^^ + +For example creating imported C++ library ``foo``: + +.. code-block:: cmake + + add_library(foo STATIC IMPORTED) + +Use ``foo_debug`` path for ``Debug`` build type: + +.. code-block:: cmake + + set_property( + TARGET foo APPEND PROPERTY IMPORTED_CONFIGURATIONS DEBUG + ) + + set_target_properties(foo PROPERTIES + IMPORTED_LINK_INTERFACE_LANGUAGES_DEBUG "CXX" + IMPORTED_LOCATION_DEBUG "${foo_debug}" + ) + +Use ``foo_release`` path for ``Release`` build type: + +.. code-block:: cmake + + set_property( + TARGET foo APPEND PROPERTY IMPORTED_CONFIGURATIONS RELEASE + ) + + set_target_properties(foo PROPERTIES + IMPORTED_LINK_INTERFACE_LANGUAGES_RELEASE "CXX" + IMPORTED_LOCATION_RELEASE "${foo_release}" + ) + +Use ``Release`` version of library for ``MinSizeRel`` and ``RelWithDebInfo`` +build types: + +.. code-block:: cmake + + set_target_properties(foo PROPERTIES + MAP_IMPORTED_CONFIG_MINSIZEREL Release + MAP_IMPORTED_CONFIG_RELWITHDEBINFO Release + ) 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 0000000..6c61341 --- /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 0000000..9b978b2 --- /dev/null +++ b/Help/prop_tgt/MSVC_RUNTIME_LIBRARY.rst @@ -0,0 +1,31 @@ +MSVC_RUNTIME_LIBRARY +-------------------- + +.. versionadded:: 3.15 + +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/NAME.rst b/Help/prop_tgt/NAME.rst new file mode 100644 index 0000000..ddd84f2 --- /dev/null +++ b/Help/prop_tgt/NAME.rst @@ -0,0 +1,6 @@ +NAME +---- + +Logical name for the target. + +Read-only logical name for the target as used by CMake. diff --git a/Help/prop_tgt/NO_SONAME.rst b/Help/prop_tgt/NO_SONAME.rst new file mode 100644 index 0000000..d381a9c --- /dev/null +++ b/Help/prop_tgt/NO_SONAME.rst @@ -0,0 +1,14 @@ +NO_SONAME +--------- + +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 +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 +link against, on some platforms a linker will insert a full path to +the library (as specified at link time) into the dynamic section of +the dependent binary. Therefore, once installed, dynamic loader may +eventually fail to locate the library for the binary. diff --git a/Help/prop_tgt/NO_SYSTEM_FROM_IMPORTED.rst b/Help/prop_tgt/NO_SYSTEM_FROM_IMPORTED.rst new file mode 100644 index 0000000..880343d --- /dev/null +++ b/Help/prop_tgt/NO_SYSTEM_FROM_IMPORTED.rst @@ -0,0 +1,15 @@ +NO_SYSTEM_FROM_IMPORTED +----------------------- + +Do not treat include directories from the interfaces of consumed +:ref:`imported targets` as ``SYSTEM``. + +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 0000000..8a254f2 --- /dev/null +++ b/Help/prop_tgt/OBJCXX_EXTENSIONS.rst @@ -0,0 +1,22 @@ +OBJCXX_EXTENSIONS +----------------- + +.. versionadded:: 3.16 + +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 0000000..96088af --- /dev/null +++ b/Help/prop_tgt/OBJCXX_STANDARD.rst @@ -0,0 +1,37 @@ +OBJCXX_STANDARD +--------------- + +.. versionadded:: 3.16 + +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``, ``20``, ``23``. + +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 0000000..3cee740 --- /dev/null +++ b/Help/prop_tgt/OBJCXX_STANDARD_REQUIRED.rst @@ -0,0 +1,22 @@ +OBJCXX_STANDARD_REQUIRED +------------------------ + +.. versionadded:: 3.16 + +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 0000000..ef1c754 --- /dev/null +++ b/Help/prop_tgt/OBJC_EXTENSIONS.rst @@ -0,0 +1,22 @@ +OBJC_EXTENSIONS +--------------- + +.. versionadded:: 3.16 + +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 0000000..2143ff9 --- /dev/null +++ b/Help/prop_tgt/OBJC_STANDARD.rst @@ -0,0 +1,37 @@ +OBJC_STANDARD +------------- + +.. versionadded:: 3.16 + +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 0000000..11547c8 --- /dev/null +++ b/Help/prop_tgt/OBJC_STANDARD_REQUIRED.rst @@ -0,0 +1,22 @@ +OBJC_STANDARD_REQUIRED +---------------------- + +.. versionadded:: 3.16 + +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/OPTIMIZE_DEPENDENCIES.rst b/Help/prop_tgt/OPTIMIZE_DEPENDENCIES.rst new file mode 100644 index 0000000..d17251f --- /dev/null +++ b/Help/prop_tgt/OPTIMIZE_DEPENDENCIES.rst @@ -0,0 +1,43 @@ +OPTIMIZE_DEPENDENCIES +--------------------- + +.. versionadded:: 3.19 + +Activates dependency optimization of static and object libraries. + +When this property is set to true, some dependencies for a static or object +library may be removed at generation time if they are not necessary to build +the library, since static and object libraries don't actually link against +anything. + +If a static or object library has dependency optimization enabled, it first +discards all dependencies. Then, it looks through all of the direct and +indirect dependencies that it initially had, and adds them back if they meet +any of the following criteria: + +* The dependency was added to the library by :command:`add_dependencies`. +* The dependency was added to the library through a source file in the library + generated by a custom command that uses the dependency. +* The dependency has any ``PRE_BUILD``, ``PRE_LINK``, or ``POST_BUILD`` custom + commands associated with it. +* The dependency contains any source files that were generated by a custom + command. +* The dependency contains any languages which produce side effects that are + relevant to the library. Currently, all languages except C, C++, Objective-C, + Objective-C++, assembly, and CUDA are assumed to produce side effects. + However, side effects from one language are assumed not to be relevant to + another (for example, a Fortran library is assumed to not have any side + effects that are relevant for a Swift library.) + +As an example, assume you have a static Fortran library which depends on a +static C library, which in turn depends on a static Fortran library. The +top-level Fortran library has optimization enabled, but the middle C library +does not. If you build the top Fortran library, the bottom Fortran library will +also build, but not the middle C library, since the C library does not have any +side effects that are relevant for the Fortran library. However, if you build +the middle C library, the bottom Fortran library will also build, even though +it does not have any side effects that are relevant to the C library, since the +C library does not have optimization enabled. + +This property is initialized by the value of the +:variable:`CMAKE_OPTIMIZE_DEPENDENCIES` variable when the target is created. diff --git a/Help/prop_tgt/OSX_ARCHITECTURES.rst b/Help/prop_tgt/OSX_ARCHITECTURES.rst new file mode 100644 index 0000000..996a4be --- /dev/null +++ b/Help/prop_tgt/OSX_ARCHITECTURES.rst @@ -0,0 +1,11 @@ +OSX_ARCHITECTURES +----------------- + +Target specific architectures for macOS. + +The ``OSX_ARCHITECTURES`` property sets the target binary architecture for +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 +upper-case name (e.g. ``OSX_ARCHITECTURES_DEBUG``). diff --git a/Help/prop_tgt/OSX_ARCHITECTURES_CONFIG.rst b/Help/prop_tgt/OSX_ARCHITECTURES_CONFIG.rst new file mode 100644 index 0000000..06da4fb --- /dev/null +++ b/Help/prop_tgt/OSX_ARCHITECTURES_CONFIG.rst @@ -0,0 +1,7 @@ +OSX_ARCHITECTURES_<CONFIG> +-------------------------- + +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 new file mode 100644 index 0000000..4b33b38 --- /dev/null +++ b/Help/prop_tgt/OUTPUT_NAME.rst @@ -0,0 +1,22 @@ +OUTPUT_NAME +----------- + +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 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)>`. + +See also the variants: + +* :prop_tgt:`OUTPUT_NAME_<CONFIG>` +* :prop_tgt:`ARCHIVE_OUTPUT_NAME_<CONFIG>` +* :prop_tgt:`ARCHIVE_OUTPUT_NAME` +* :prop_tgt:`LIBRARY_OUTPUT_NAME_<CONFIG>` +* :prop_tgt:`LIBRARY_OUTPUT_NAME` +* :prop_tgt:`RUNTIME_OUTPUT_NAME_<CONFIG>` +* :prop_tgt:`RUNTIME_OUTPUT_NAME` diff --git a/Help/prop_tgt/OUTPUT_NAME_CONFIG.rst b/Help/prop_tgt/OUTPUT_NAME_CONFIG.rst new file mode 100644 index 0000000..41b782f --- /dev/null +++ b/Help/prop_tgt/OUTPUT_NAME_CONFIG.rst @@ -0,0 +1,7 @@ +OUTPUT_NAME_<CONFIG> +-------------------- + +Per-configuration target file base name. + +This is the configuration-specific version of the :prop_tgt:`OUTPUT_NAME` +target property. diff --git a/Help/prop_tgt/PCH_INSTANTIATE_TEMPLATES.rst b/Help/prop_tgt/PCH_INSTANTIATE_TEMPLATES.rst new file mode 100644 index 0000000..7c1af2a --- /dev/null +++ b/Help/prop_tgt/PCH_INSTANTIATE_TEMPLATES.rst @@ -0,0 +1,13 @@ +PCH_INSTANTIATE_TEMPLATES +------------------------- + +.. versionadded:: 3.19 + +When this property is set to true, the precompiled header compiler options +will contain a flag to instantiate templates during the generation of the PCH +if supported. This can significantly improve compile times. Supported in Clang +since version 11. + +This property is initialized by the value of the +:variable:`CMAKE_PCH_INSTANTIATE_TEMPLATES` variable if it is set when a target +is created. If that variable is not set, the property defaults to ``ON``. diff --git a/Help/prop_tgt/PCH_WARN_INVALID.rst b/Help/prop_tgt/PCH_WARN_INVALID.rst new file mode 100644 index 0000000..2d5ec55 --- /dev/null +++ b/Help/prop_tgt/PCH_WARN_INVALID.rst @@ -0,0 +1,12 @@ +PCH_WARN_INVALID +---------------- + +.. versionadded:: 3.18 + +When this property is set to true, the precompile header compiler options +will contain a compiler flag which should warn about invalid precompiled +headers e.g. ``-Winvalid-pch`` for GNU compiler. + +This property is initialized by the value of the +:variable:`CMAKE_PCH_WARN_INVALID` variable if it is set when a target is +created. If that variable is not set, the property defaults to ``ON``. diff --git a/Help/prop_tgt/PDB_NAME.rst b/Help/prop_tgt/PDB_NAME.rst new file mode 100644 index 0000000..3a65796 --- /dev/null +++ b/Help/prop_tgt/PDB_NAME.rst @@ -0,0 +1,12 @@ +PDB_NAME +-------- + +Output name for the MS debug symbol ``.pdb`` file generated by the +linker for an executable or shared library target. + +This property specifies the base name for the debug symbols file. +If not set, the :prop_tgt:`OUTPUT_NAME` target property value or +logical target name is used by default. + +.. |COMPILE_PDB_XXX| replace:: :prop_tgt:`COMPILE_PDB_NAME` +.. include:: PDB_NOTE.txt diff --git a/Help/prop_tgt/PDB_NAME_CONFIG.rst b/Help/prop_tgt/PDB_NAME_CONFIG.rst new file mode 100644 index 0000000..cb3121c --- /dev/null +++ b/Help/prop_tgt/PDB_NAME_CONFIG.rst @@ -0,0 +1,10 @@ +PDB_NAME_<CONFIG> +----------------- + +Per-configuration output name for the MS debug symbol ``.pdb`` file +generated by the linker for an executable or shared library target. + +This is the configuration-specific version of :prop_tgt:`PDB_NAME`. + +.. |COMPILE_PDB_XXX| replace:: :prop_tgt:`COMPILE_PDB_NAME_<CONFIG>` +.. include:: PDB_NOTE.txt diff --git a/Help/prop_tgt/PDB_NOTE.txt b/Help/prop_tgt/PDB_NOTE.txt new file mode 100644 index 0000000..b5ada07 --- /dev/null +++ b/Help/prop_tgt/PDB_NOTE.txt @@ -0,0 +1,9 @@ +.. note:: + This property does not apply to STATIC library targets because no linker + is invoked to produce them so they have no linker-generated ``.pdb`` file + containing debug symbols. + + The linker-generated program database files are specified by the + ``/pdb`` linker flag and are not the same as compiler-generated + program database files specified by the ``/Fd`` compiler flag. + Use the |COMPILE_PDB_XXX| property to specify the latter. diff --git a/Help/prop_tgt/PDB_OUTPUT_DIRECTORY.rst b/Help/prop_tgt/PDB_OUTPUT_DIRECTORY.rst new file mode 100644 index 0000000..2f667f3 --- /dev/null +++ b/Help/prop_tgt/PDB_OUTPUT_DIRECTORY.rst @@ -0,0 +1,19 @@ +PDB_OUTPUT_DIRECTORY +-------------------- + +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. 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` +.. include:: PDB_NOTE.txt diff --git a/Help/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG.rst b/Help/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG.rst new file mode 100644 index 0000000..6c55083 --- /dev/null +++ b/Help/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG.rst @@ -0,0 +1,19 @@ +PDB_OUTPUT_DIRECTORY_<CONFIG> +----------------------------- + +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 (: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 new file mode 100644 index 0000000..0aaf66b --- /dev/null +++ b/Help/prop_tgt/POSITION_INDEPENDENT_CODE.rst @@ -0,0 +1,16 @@ +POSITION_INDEPENDENT_CODE +------------------------- + +Whether to create a position-independent target + +The ``POSITION_INDEPENDENT_CODE`` property determines whether position +independent executables or shared libraries will be created. This +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 new file mode 100644 index 0000000..23935bc --- /dev/null +++ b/Help/prop_tgt/POST_INSTALL_SCRIPT.rst @@ -0,0 +1,9 @@ +POST_INSTALL_SCRIPT +------------------- + +Deprecated install support. + +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 0000000..af27947 --- /dev/null +++ b/Help/prop_tgt/PRECOMPILE_HEADERS.rst @@ -0,0 +1,14 @@ +PRECOMPILE_HEADERS +------------------ + +.. versionadded:: 3.16 + +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 0000000..6f5635b --- /dev/null +++ b/Help/prop_tgt/PRECOMPILE_HEADERS_REUSE_FROM.rst @@ -0,0 +1,9 @@ +PRECOMPILE_HEADERS_REUSE_FROM +----------------------------- + +.. versionadded:: 3.16 + +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 new file mode 100644 index 0000000..a401292 --- /dev/null +++ b/Help/prop_tgt/PREFIX.rst @@ -0,0 +1,7 @@ +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. diff --git a/Help/prop_tgt/PRE_INSTALL_SCRIPT.rst b/Help/prop_tgt/PRE_INSTALL_SCRIPT.rst new file mode 100644 index 0000000..43432f4 --- /dev/null +++ b/Help/prop_tgt/PRE_INSTALL_SCRIPT.rst @@ -0,0 +1,9 @@ +PRE_INSTALL_SCRIPT +------------------ + +Deprecated install support. + +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 new file mode 100644 index 0000000..23e1f8e --- /dev/null +++ b/Help/prop_tgt/PRIVATE_HEADER.rst @@ -0,0 +1,11 @@ +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 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 :command:`install(TARGETS)` command. diff --git a/Help/prop_tgt/PROJECT_LABEL.rst b/Help/prop_tgt/PROJECT_LABEL.rst new file mode 100644 index 0000000..a1491ee --- /dev/null +++ b/Help/prop_tgt/PROJECT_LABEL.rst @@ -0,0 +1,7 @@ +PROJECT_LABEL +------------- + +Change the name of a target in an IDE. + +Can be used to change the name of the target in an IDE like Visual +Studio. diff --git a/Help/prop_tgt/PUBLIC_HEADER.rst b/Help/prop_tgt/PUBLIC_HEADER.rst new file mode 100644 index 0000000..915e39c --- /dev/null +++ b/Help/prop_tgt/PUBLIC_HEADER.rst @@ -0,0 +1,11 @@ +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 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 +:command:`install(TARGETS)` command. diff --git a/Help/prop_tgt/RESOURCE.rst b/Help/prop_tgt/RESOURCE.rst new file mode 100644 index 0000000..e5a1cb6 --- /dev/null +++ b/Help/prop_tgt/RESOURCE.rst @@ -0,0 +1,58 @@ +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 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 macOS) inside the bundle. +On non-Apple platforms these files may be installed using the ``RESOURCE`` +option to the :command:`install(TARGETS)` command. + +Following example of Application Bundle: + +.. code-block:: cmake + + add_executable(ExecutableTarget + addDemo.c + resourcefile.txt + appresourcedir/appres.txt) + + target_link_libraries(ExecutableTarget heymath mul) + + set(RESOURCE_FILES + resourcefile.txt + appresourcedir/appres.txt) + + set_target_properties(ExecutableTarget PROPERTIES + MACOSX_BUNDLE TRUE + MACOSX_FRAMEWORK_IDENTIFIER org.cmake.ExecutableTarget + RESOURCE "${RESOURCE_FILES}") + +will produce flat structure for iOS systems:: + + ExecutableTarget.app + appres.txt + ExecutableTarget + Info.plist + resourcefile.txt + +For macOS systems it will produce following directory structure:: + + ExecutableTarget.app/ + Contents + Info.plist + MacOS + ExecutableTarget + Resources + appres.txt + resourcefile.txt + +For Linux, such CMake script produce following files:: + + ExecutableTarget + Resources + appres.txt + resourcefile.txt diff --git a/Help/prop_tgt/RULE_LAUNCH_COMPILE.rst b/Help/prop_tgt/RULE_LAUNCH_COMPILE.rst new file mode 100644 index 0000000..e92ab86 --- /dev/null +++ b/Help/prop_tgt/RULE_LAUNCH_COMPILE.rst @@ -0,0 +1,7 @@ +RULE_LAUNCH_COMPILE +------------------- + +Specify a launcher for compile rules. + +See the global property of the same name for details. This overrides +the global and directory property for a target. diff --git a/Help/prop_tgt/RULE_LAUNCH_CUSTOM.rst b/Help/prop_tgt/RULE_LAUNCH_CUSTOM.rst new file mode 100644 index 0000000..2db0317 --- /dev/null +++ b/Help/prop_tgt/RULE_LAUNCH_CUSTOM.rst @@ -0,0 +1,7 @@ +RULE_LAUNCH_CUSTOM +------------------ + +Specify a launcher for custom rules. + +See the global property of the same name for details. This overrides +the global and directory property for a target. diff --git a/Help/prop_tgt/RULE_LAUNCH_LINK.rst b/Help/prop_tgt/RULE_LAUNCH_LINK.rst new file mode 100644 index 0000000..f330033 --- /dev/null +++ b/Help/prop_tgt/RULE_LAUNCH_LINK.rst @@ -0,0 +1,7 @@ +RULE_LAUNCH_LINK +---------------- + +Specify a launcher for link rules. + +See the global property of the same name for details. This overrides +the global and directory property for a target. diff --git a/Help/prop_tgt/RUNTIME_OUTPUT_DIRECTORY.rst b/Help/prop_tgt/RUNTIME_OUTPUT_DIRECTORY.rst new file mode 100644 index 0000000..3c37546 --- /dev/null +++ b/Help/prop_tgt/RUNTIME_OUTPUT_DIRECTORY.rst @@ -0,0 +1,9 @@ +RUNTIME_OUTPUT_DIRECTORY +------------------------ + +.. |XXX| replace:: :ref:`RUNTIME <Runtime Output Artifacts>` +.. |xxx| replace:: runtime +.. |CMAKE_XXX_OUTPUT_DIRECTORY| replace:: :variable:`CMAKE_RUNTIME_OUTPUT_DIRECTORY` +.. include:: XXX_OUTPUT_DIRECTORY.txt + +See also the :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY_<CONFIG>` target property. diff --git a/Help/prop_tgt/RUNTIME_OUTPUT_DIRECTORY_CONFIG.rst b/Help/prop_tgt/RUNTIME_OUTPUT_DIRECTORY_CONFIG.rst new file mode 100644 index 0000000..6727754 --- /dev/null +++ b/Help/prop_tgt/RUNTIME_OUTPUT_DIRECTORY_CONFIG.rst @@ -0,0 +1,17 @@ +RUNTIME_OUTPUT_DIRECTORY_<CONFIG> +--------------------------------- + +Per-configuration output directory for +:ref:`RUNTIME <Runtime Output Artifacts>` target files. + +This is a per-configuration version of the +:prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` target property, 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_RUNTIME_OUTPUT_DIRECTORY_<CONFIG>` variable if +it is set when a target is created. + +Contents of ``RUNTIME_OUTPUT_DIRECTORY_<CONFIG>`` may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/prop_tgt/RUNTIME_OUTPUT_NAME.rst b/Help/prop_tgt/RUNTIME_OUTPUT_NAME.rst new file mode 100644 index 0000000..11729c3 --- /dev/null +++ b/Help/prop_tgt/RUNTIME_OUTPUT_NAME.rst @@ -0,0 +1,8 @@ +RUNTIME_OUTPUT_NAME +------------------- + +.. |XXX| replace:: :ref:`RUNTIME <Runtime Output Artifacts>` +.. |xxx| replace:: runtime +.. include:: XXX_OUTPUT_NAME.txt + +See also the :prop_tgt:`RUNTIME_OUTPUT_NAME_<CONFIG>` target property. diff --git a/Help/prop_tgt/RUNTIME_OUTPUT_NAME_CONFIG.rst b/Help/prop_tgt/RUNTIME_OUTPUT_NAME_CONFIG.rst new file mode 100644 index 0000000..b6a31bf --- /dev/null +++ b/Help/prop_tgt/RUNTIME_OUTPUT_NAME_CONFIG.rst @@ -0,0 +1,8 @@ +RUNTIME_OUTPUT_NAME_<CONFIG> +---------------------------- + +Per-configuration output name for +:ref:`RUNTIME <Runtime Output Artifacts>` target files. + +This is the configuration-specific version of the +:prop_tgt:`RUNTIME_OUTPUT_NAME` target property. diff --git a/Help/prop_tgt/SKIP_BUILD_RPATH.rst b/Help/prop_tgt/SKIP_BUILD_RPATH.rst new file mode 100644 index 0000000..7086b1b --- /dev/null +++ b/Help/prop_tgt/SKIP_BUILD_RPATH.rst @@ -0,0 +1,9 @@ +SKIP_BUILD_RPATH +---------------- + +Should rpaths be used for the build tree. + +``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 +:variable:`CMAKE_SKIP_BUILD_RPATH` if it is set when a target is created. diff --git a/Help/prop_tgt/SOURCES.rst b/Help/prop_tgt/SOURCES.rst new file mode 100644 index 0000000..493643e --- /dev/null +++ b/Help/prop_tgt/SOURCES.rst @@ -0,0 +1,6 @@ +SOURCES +------- + +Source names specified for a target. + +List of sources specified for a target. diff --git a/Help/prop_tgt/SOURCE_DIR.rst b/Help/prop_tgt/SOURCE_DIR.rst new file mode 100644 index 0000000..78ce220 --- /dev/null +++ b/Help/prop_tgt/SOURCE_DIR.rst @@ -0,0 +1,8 @@ +SOURCE_DIR +---------- + +.. versionadded:: 3.4 + +This read-only property reports the value of the +:variable:`CMAKE_CURRENT_SOURCE_DIR` variable in the directory in which +the target was defined. diff --git a/Help/prop_tgt/SOVERSION.rst b/Help/prop_tgt/SOVERSION.rst new file mode 100644 index 0000000..b377f22 --- /dev/null +++ b/Help/prop_tgt/SOVERSION.rst @@ -0,0 +1,37 @@ +SOVERSION +--------- + +What version number is this target. + +For shared libraries :prop_tgt:`VERSION` and ``SOVERSION`` can be used to +specify the build version and API version respectively. When building or +installing appropriate symlinks are created if the platform supports +symlinks and the linker supports so-names. If only one of both is +specified the missing is assumed to have the same version number. +``SOVERSION`` is ignored if :prop_tgt:`NO_SONAME` property is set. + +Windows Versions +^^^^^^^^^^^^^^^^ + +For shared libraries and executables on Windows the :prop_tgt:`VERSION` +attribute is parsed to extract a ``<major>.<minor>`` version number. +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. macOS, iOS), +the ``SOVERSION`` property corresponds to the *compatibility version* and +:prop_tgt:`VERSION` corresponds to the *current version* (unless Mach-O +specific overrides are provided, as discussed below). +See the :prop_tgt:`FRAMEWORK` target property for an example. + +For shared libraries, the :prop_tgt:`MACHO_COMPATIBILITY_VERSION` and +:prop_tgt:`MACHO_CURRENT_VERSION` properties can be used to +override the *compatibility version* and *current version* respectively. +Note that ``SOVERSION`` will still be used to form the ``install_name`` +and both ``SOVERSION`` and :prop_tgt:`VERSION` may also affect the file +and symlink names. + +Versions of Mach-O binaries may be checked with the ``otool -L <binary>`` +command. diff --git a/Help/prop_tgt/STATIC_LIBRARY_FLAGS.rst b/Help/prop_tgt/STATIC_LIBRARY_FLAGS.rst new file mode 100644 index 0000000..66e0e8b --- /dev/null +++ b/Help/prop_tgt/STATIC_LIBRARY_FLAGS.rst @@ -0,0 +1,17 @@ +STATIC_LIBRARY_FLAGS +-------------------- + +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. + +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 new file mode 100644 index 0000000..5b97941 --- /dev/null +++ b/Help/prop_tgt/STATIC_LIBRARY_FLAGS_CONFIG.rst @@ -0,0 +1,12 @@ +STATIC_LIBRARY_FLAGS_<CONFIG> +----------------------------- + +Per-configuration archiver (or MSVC librarian) flags for a static library +target. + +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 0000000..2f4a3ba --- /dev/null +++ b/Help/prop_tgt/STATIC_LIBRARY_OPTIONS.rst @@ -0,0 +1,22 @@ +STATIC_LIBRARY_OPTIONS +---------------------- + +.. versionadded:: 3.13 + +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 new file mode 100644 index 0000000..32ec429 --- /dev/null +++ b/Help/prop_tgt/SUFFIX.rst @@ -0,0 +1,7 @@ +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. diff --git a/Help/prop_tgt/Swift_DEPENDENCIES_FILE.rst b/Help/prop_tgt/Swift_DEPENDENCIES_FILE.rst new file mode 100644 index 0000000..0f944b6 --- /dev/null +++ b/Help/prop_tgt/Swift_DEPENDENCIES_FILE.rst @@ -0,0 +1,7 @@ +Swift_DEPENDENCIES_FILE +----------------------- + +.. versionadded:: 3.15 + +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 0000000..afc6b31 --- /dev/null +++ b/Help/prop_tgt/Swift_LANGUAGE_VERSION.rst @@ -0,0 +1,8 @@ +Swift_LANGUAGE_VERSION +---------------------- + +.. versionadded:: 3.16 + +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 0000000..a6484f2 --- /dev/null +++ b/Help/prop_tgt/Swift_MODULE_DIRECTORY.rst @@ -0,0 +1,12 @@ +Swift_MODULE_DIRECTORY +---------------------- + +.. versionadded:: 3.15 + +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 0000000..d941b54 --- /dev/null +++ b/Help/prop_tgt/Swift_MODULE_NAME.rst @@ -0,0 +1,7 @@ +Swift_MODULE_NAME +----------------- + +.. versionadded:: 3.15 + +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 new file mode 100644 index 0000000..3136d11 --- /dev/null +++ b/Help/prop_tgt/TYPE.rst @@ -0,0 +1,9 @@ +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``, ``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 0000000..f827a20 --- /dev/null +++ b/Help/prop_tgt/UNITY_BUILD.rst @@ -0,0 +1,87 @@ +UNITY_BUILD +----------- + +.. versionadded:: 3.16 + +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. + +CMake provides different algorithms for selecting which sources are grouped +together into a *bucket*. Algorithm selection is decided by the +:prop_tgt:`UNITY_BUILD_MODE` target property, which has the following acceptable +values: + +* ``BATCH`` + When in this mode CMake determines which files are grouped together. + The :prop_tgt:`UNITY_BUILD_BATCH_SIZE` property controls the upper limit on + how many sources can be combined per unity source file. + +* ``GROUP`` + When in this mode each target explicitly specifies how to group + source files. Each source file that has the same + :prop_sf:`UNITY_GROUP` value will be grouped together. Any sources + that don't have this property will be compiled individually. The + :prop_tgt:`UNITY_BUILD_BATCH_SIZE` property is ignored when using + this mode. + +If no explicit :prop_tgt:`UNITY_BUILD_MODE` has been specified, CMake will +default to ``BATCH``. + +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. + +* Projects can set :prop_tgt:`UNITY_BUILD_UNIQUE_ID` to cause a valid + C-identifier to be generated which is unique per file in a unity + build. This can be used to avoid problems with anonymous namespaces + in unity builds. + +* 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 0000000..3886ec9 --- /dev/null +++ b/Help/prop_tgt/UNITY_BUILD_BATCH_SIZE.rst @@ -0,0 +1,25 @@ +UNITY_BUILD_BATCH_SIZE +---------------------- + +.. versionadded:: 3.16 + +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 0000000..ac2b19c --- /dev/null +++ b/Help/prop_tgt/UNITY_BUILD_CODE_AFTER_INCLUDE.rst @@ -0,0 +1,21 @@ +UNITY_BUILD_CODE_AFTER_INCLUDE +------------------------------ + +.. versionadded:: 3.16 + +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 0000000..6f0d56b --- /dev/null +++ b/Help/prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE.rst @@ -0,0 +1,21 @@ +UNITY_BUILD_CODE_BEFORE_INCLUDE +------------------------------- + +.. versionadded:: 3.16 + +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/UNITY_BUILD_MODE.rst b/Help/prop_tgt/UNITY_BUILD_MODE.rst new file mode 100644 index 0000000..003451e --- /dev/null +++ b/Help/prop_tgt/UNITY_BUILD_MODE.rst @@ -0,0 +1,60 @@ +UNITY_BUILD_MODE +---------------- + +.. versionadded:: 3.18 + +CMake provides different algorithms for selecting which sources are grouped +together into a *bucket*. Selection is decided by this property, +which has the following acceptable values: + +``BATCH`` + When in this mode CMake determines which files are grouped together. + The :prop_tgt:`UNITY_BUILD_BATCH_SIZE` property controls the upper limit on + how many sources can be combined per unity source file. + + Example usage: + + .. code-block:: cmake + + add_library(example_library + source1.cxx + source2.cxx + source3.cxx + source4.cxx) + + set_target_properties(example_library PROPERTIES + UNITY_BUILD_MODE BATCH + UNITY_BUILD_BATCH_SIZE 2 + ) + +``GROUP`` + When in this mode each target explicitly specifies how to group + source files. Each source file that has the same + :prop_sf:`UNITY_GROUP` value will be grouped together. Any sources + that don't have this property will be compiled individually. The + :prop_tgt:`UNITY_BUILD_BATCH_SIZE` property is ignored when using + this mode. + + Example usage: + + .. code-block:: cmake + + add_library(example_library + source1.cxx + source2.cxx + source3.cxx + source4.cxx) + + set_target_properties(example_library PROPERTIES + UNITY_BUILD_MODE GROUP + ) + + set_source_files_properties(source1.cxx source2.cxx source3.cxx + PROPERTIES UNITY_GROUP "bucket1" + ) + set_source_files_properties(source4.cxx + PROPERTIES UNITY_GROUP "bucket2" + ) + +If no explicit :prop_tgt:`UNITY_BUILD_MODE` has been specified, CMake will +default to ``BATCH``. diff --git a/Help/prop_tgt/UNITY_BUILD_UNIQUE_ID.rst b/Help/prop_tgt/UNITY_BUILD_UNIQUE_ID.rst new file mode 100644 index 0000000..2c95e02 --- /dev/null +++ b/Help/prop_tgt/UNITY_BUILD_UNIQUE_ID.rst @@ -0,0 +1,55 @@ +UNITY_BUILD_UNIQUE_ID +--------------------- + +.. versionadded:: 3.20 + +The name of a valid C-identifier which is set to a unique per-file +value during unity builds. + +When this property is populated and when :prop_tgt:`UNITY_BUILD` +is true, the property value is used to define a compiler definition +of the specified name. The value of the defined symbol is unspecified, +but it is unique per file path. + +Given: + +.. code-block:: cmake + + set_target_properties(myTarget PROPERTIES + UNITY_BUILD "ON" + UNITY_BUILD_UNIQUE_ID "MY_UNITY_ID" + ) + +the ``MY_UNITY_ID`` symbol is defined to a unique per-file value. + +One known use case for this identifier is to disambiguate the +variables in an anonymous namespace in a limited scope. +Anonymous namespaces present a problem for unity builds because +they are used to ensure that certain variables and declarations +are scoped to a translation unit which is approximated by a +single source file. When source files are combined in a unity +build file, those variables in different files are combined in +a single translation unit and the names clash. This property can +be used to avoid that with code like the following: + +.. code-block:: cpp + + // Needed for when unity builds are disabled + #ifndef MY_UNITY_ID + #define MY_UNITY_ID + #endif + + namespace { namespace MY_UNITY_ID { + // The name 'i' clashes (or could clash) with other + // variables in other anonymous namespaces + int i = 42; + }} + + int use_var() + { + return MY_UNITY_ID::i; + } + +The pseudononymous namespace is used within a truly anonymous namespace. +On many platforms, this maintains the invariant that the symbols within +do not get external linkage when performing a unity build. diff --git a/Help/prop_tgt/VERSION.rst b/Help/prop_tgt/VERSION.rst new file mode 100644 index 0000000..95db483 --- /dev/null +++ b/Help/prop_tgt/VERSION.rst @@ -0,0 +1,39 @@ +VERSION +------- + +What version number is this target. + +For shared libraries ``VERSION`` and :prop_tgt:`SOVERSION` can be used +to specify the build version and API version respectively. When building or +installing appropriate symlinks are created if the platform supports +symlinks and the linker supports so-names. If only one of both is +specified the missing is assumed to have the same version number. For +executables ``VERSION`` can be used to specify the build version. When +building or installing appropriate symlinks are created if the +platform supports symlinks. + +Windows Versions +^^^^^^^^^^^^^^^^ + +For shared libraries and executables on Windows the ``VERSION`` +attribute is parsed to extract a ``<major>.<minor>`` version number. +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. macOS, iOS), +the :prop_tgt:`SOVERSION` property corresponds to the *compatibility version* +and ``VERSION`` corresponds to the *current version* (unless Mach-O specific +overrides are provided, as discussed below). +See the :prop_tgt:`FRAMEWORK` target property for an example. + +For shared libraries, the :prop_tgt:`MACHO_COMPATIBILITY_VERSION` and +:prop_tgt:`MACHO_CURRENT_VERSION` properties can be used to +override the *compatibility version* and *current version* respectively. +Note that :prop_tgt:`SOVERSION` will still be used to form the +``install_name`` and both :prop_tgt:`SOVERSION` and ``VERSION`` may also +affect the file and symlink names. + +Versions of Mach-O binaries may be checked with the ``otool -L <binary>`` +command. diff --git a/Help/prop_tgt/VISIBILITY_INLINES_HIDDEN.rst b/Help/prop_tgt/VISIBILITY_INLINES_HIDDEN.rst new file mode 100644 index 0000000..adbbc71 --- /dev/null +++ b/Help/prop_tgt/VISIBILITY_INLINES_HIDDEN.rst @@ -0,0 +1,13 @@ +VISIBILITY_INLINES_HIDDEN +------------------------- + +Whether to add a compile flag to hide symbols of inline functions + +The ``VISIBILITY_INLINES_HIDDEN`` property determines whether a flag for +hiding symbols for inline functions, such as ``-fvisibility-inlines-hidden``, +should be used when invoking the compiler. This property affects compilation +in sources of all types of targets (subject to policy :policy:`CMP0063`). + +This property is initialized by +the value of the :variable:`CMAKE_VISIBILITY_INLINES_HIDDEN` variable if it +is set when a target is created. diff --git a/Help/prop_tgt/VS_CONFIGURATION_TYPE.rst b/Help/prop_tgt/VS_CONFIGURATION_TYPE.rst new file mode 100644 index 0000000..4adffd4 --- /dev/null +++ b/Help/prop_tgt/VS_CONFIGURATION_TYPE.rst @@ -0,0 +1,14 @@ +VS_CONFIGURATION_TYPE +--------------------- + +.. versionadded:: 3.6 + +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``, ...). + +Supported on :ref:`Visual Studio Generators` for VS 2010 and higher. diff --git a/Help/prop_tgt/VS_DEBUGGER_COMMAND.rst b/Help/prop_tgt/VS_DEBUGGER_COMMAND.rst new file mode 100644 index 0000000..58476d6 --- /dev/null +++ b/Help/prop_tgt/VS_DEBUGGER_COMMAND.rst @@ -0,0 +1,13 @@ +VS_DEBUGGER_COMMAND +------------------- + +.. versionadded:: 3.12 + +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 0000000..6c26601 --- /dev/null +++ b/Help/prop_tgt/VS_DEBUGGER_COMMAND_ARGUMENTS.rst @@ -0,0 +1,13 @@ +VS_DEBUGGER_COMMAND_ARGUMENTS +----------------------------- + +.. versionadded:: 3.13 + +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 0000000..2f59a82 --- /dev/null +++ b/Help/prop_tgt/VS_DEBUGGER_ENVIRONMENT.rst @@ -0,0 +1,13 @@ +VS_DEBUGGER_ENVIRONMENT +----------------------- + +.. versionadded:: 3.13 + +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 new file mode 100644 index 0000000..c163abf --- /dev/null +++ b/Help/prop_tgt/VS_DEBUGGER_WORKING_DIRECTORY.rst @@ -0,0 +1,13 @@ +VS_DEBUGGER_WORKING_DIRECTORY +----------------------------- + +.. versionadded:: 3.8 + +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_DESKTOP_EXTENSIONS_VERSION.rst b/Help/prop_tgt/VS_DESKTOP_EXTENSIONS_VERSION.rst new file mode 100644 index 0000000..5fd23e1 --- /dev/null +++ b/Help/prop_tgt/VS_DESKTOP_EXTENSIONS_VERSION.rst @@ -0,0 +1,12 @@ +VS_DESKTOP_EXTENSIONS_VERSION +----------------------------- + +.. versionadded:: 3.4 + +Visual Studio Windows 10 Desktop Extensions Version + +Specifies the version of the Desktop Extensions that should be included in the +target. For example ``10.0.10240.0``. If the value is not specified, the Desktop +Extensions will not be included. To use the same version of the extensions as +the Windows 10 SDK that is being used, you can use the +:variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION` variable. diff --git a/Help/prop_tgt/VS_DOTNET_DOCUMENTATION_FILE.rst b/Help/prop_tgt/VS_DOTNET_DOCUMENTATION_FILE.rst new file mode 100644 index 0000000..a388256 --- /dev/null +++ b/Help/prop_tgt/VS_DOTNET_DOCUMENTATION_FILE.rst @@ -0,0 +1,8 @@ +VS_DOTNET_DOCUMENTATION_FILE +---------------------------- + +.. versionadded:: 3.17 + +Visual Studio managed project .NET documentation output + +Sets the target XML documentation file output. 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 0000000..5b9caee --- /dev/null +++ b/Help/prop_tgt/VS_DOTNET_REFERENCEPROP_refname_TAG_tagname.rst @@ -0,0 +1,16 @@ +VS_DOTNET_REFERENCEPROP_<refname>_TAG_<tagname> +----------------------------------------------- + +.. versionadded:: 3.10 + +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_REFERENCES.rst b/Help/prop_tgt/VS_DOTNET_REFERENCES.rst new file mode 100644 index 0000000..a661ad9 --- /dev/null +++ b/Help/prop_tgt/VS_DOTNET_REFERENCES.rst @@ -0,0 +1,7 @@ +VS_DOTNET_REFERENCES +-------------------- + +Visual Studio managed project .NET references + +Adds one or more semicolon-delimited .NET references to a generated +Visual Studio project. For example, "System;System.Windows.Forms". diff --git a/Help/prop_tgt/VS_DOTNET_REFERENCES_COPY_LOCAL.rst b/Help/prop_tgt/VS_DOTNET_REFERENCES_COPY_LOCAL.rst new file mode 100644 index 0000000..556fa8a --- /dev/null +++ b/Help/prop_tgt/VS_DOTNET_REFERENCES_COPY_LOCAL.rst @@ -0,0 +1,9 @@ +VS_DOTNET_REFERENCES_COPY_LOCAL +------------------------------- + +.. versionadded:: 3.8 + +Sets the **Copy Local** property for all .NET hint references in the target + +Boolean property to enable/disable copying of .NET hint references to +output directory. The default is ``ON``. diff --git a/Help/prop_tgt/VS_DOTNET_REFERENCE_refname.rst b/Help/prop_tgt/VS_DOTNET_REFERENCE_refname.rst new file mode 100644 index 0000000..9c4d34a --- /dev/null +++ b/Help/prop_tgt/VS_DOTNET_REFERENCE_refname.rst @@ -0,0 +1,14 @@ +VS_DOTNET_REFERENCE_<refname> +----------------------------- + +.. versionadded:: 3.8 + +Visual Studio managed project .NET reference with name ``<refname>`` +and hint path. + +Adds one .NET reference to generated Visual Studio project. The +reference will have the name ``<refname>`` and will point to the +assembly given as value of the property. + +See also :prop_tgt:`VS_DOTNET_REFERENCES` and +:prop_tgt:`VS_DOTNET_REFERENCES_COPY_LOCAL` diff --git a/Help/prop_tgt/VS_DOTNET_TARGET_FRAMEWORK_VERSION.rst b/Help/prop_tgt/VS_DOTNET_TARGET_FRAMEWORK_VERSION.rst new file mode 100644 index 0000000..6cb8f86 --- /dev/null +++ b/Help/prop_tgt/VS_DOTNET_TARGET_FRAMEWORK_VERSION.rst @@ -0,0 +1,11 @@ +VS_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 deprecated and should not be used anymore. Use +:prop_tgt:`DOTNET_TARGET_FRAMEWORK` or +: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 0000000..47ce1ce --- /dev/null +++ b/Help/prop_tgt/VS_DPI_AWARE.rst @@ -0,0 +1,16 @@ +VS_DPI_AWARE +------------ + +.. versionadded:: 3.16 + +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_GLOBAL_KEYWORD.rst b/Help/prop_tgt/VS_GLOBAL_KEYWORD.rst new file mode 100644 index 0000000..ce49316 --- /dev/null +++ b/Help/prop_tgt/VS_GLOBAL_KEYWORD.rst @@ -0,0 +1,12 @@ +VS_GLOBAL_KEYWORD +----------------- + +Visual Studio project keyword for VS 10 (2010) and newer. + +Sets the "keyword" attribute for a generated Visual Studio project. +Defaults to "Win32Proj". You may wish to override this value with +"ManagedCProj", for example, in a Visual Studio managed C++ unit test +project. + +Use the :prop_tgt:`VS_KEYWORD` target property to set the +keyword for Visual Studio 9 (2008) and older. diff --git a/Help/prop_tgt/VS_GLOBAL_PROJECT_TYPES.rst b/Help/prop_tgt/VS_GLOBAL_PROJECT_TYPES.rst new file mode 100644 index 0000000..f4d9efc --- /dev/null +++ b/Help/prop_tgt/VS_GLOBAL_PROJECT_TYPES.rst @@ -0,0 +1,15 @@ +VS_GLOBAL_PROJECT_TYPES +----------------------- + +Visual Studio project type(s). + +Can be set to one or more UUIDs recognized by Visual Studio to +indicate the type of project. This value is copied verbatim into the +generated project file. Example for a managed C++ unit testing +project: + +:: + + {3AC096D0-A1C2-E12C-1390-A8335801FDAB};{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942} + +UUIDs are semicolon-delimited. diff --git a/Help/prop_tgt/VS_GLOBAL_ROOTNAMESPACE.rst b/Help/prop_tgt/VS_GLOBAL_ROOTNAMESPACE.rst new file mode 100644 index 0000000..a23c540 --- /dev/null +++ b/Help/prop_tgt/VS_GLOBAL_ROOTNAMESPACE.rst @@ -0,0 +1,7 @@ +VS_GLOBAL_ROOTNAMESPACE +----------------------- + +Visual Studio project root namespace. + +Sets the "RootNamespace" attribute for a generated Visual Studio +project. The attribute will be generated only if this is set. diff --git a/Help/prop_tgt/VS_GLOBAL_variable.rst b/Help/prop_tgt/VS_GLOBAL_variable.rst new file mode 100644 index 0000000..56b8021 --- /dev/null +++ b/Help/prop_tgt/VS_GLOBAL_variable.rst @@ -0,0 +1,10 @@ +VS_GLOBAL_<variable> +-------------------- + +Visual Studio project-specific global variable. + +Tell the Visual Studio generator to set the global variable +'<variable>' to a given value in the generated Visual Studio project. +Ignored on other generators. Qt integration works better if +VS_GLOBAL_QtVersion is set to the version FindQt4.cmake found. For +example, "4.7.3" diff --git a/Help/prop_tgt/VS_IOT_EXTENSIONS_VERSION.rst b/Help/prop_tgt/VS_IOT_EXTENSIONS_VERSION.rst new file mode 100644 index 0000000..ca6a3ca --- /dev/null +++ b/Help/prop_tgt/VS_IOT_EXTENSIONS_VERSION.rst @@ -0,0 +1,12 @@ +VS_IOT_EXTENSIONS_VERSION +------------------------- + +.. versionadded:: 3.4 + +Visual Studio Windows 10 IoT Extensions Version + +Specifies the version of the IoT Extensions that should be included in the +target. For example ``10.0.10240.0``. If the value is not specified, the IoT +Extensions will not be included. To use the same version of the extensions as +the Windows 10 SDK that is being used, you can use the +:variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION` variable. diff --git a/Help/prop_tgt/VS_IOT_STARTUP_TASK.rst b/Help/prop_tgt/VS_IOT_STARTUP_TASK.rst new file mode 100644 index 0000000..259055d --- /dev/null +++ b/Help/prop_tgt/VS_IOT_STARTUP_TASK.rst @@ -0,0 +1,8 @@ +VS_IOT_STARTUP_TASK +------------------- + +.. versionadded:: 3.4 + +Visual Studio Windows 10 IoT Continuous Background Task + +Specifies that the target should be compiled as a Continuous Background Task library. 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 0000000..724bd2f --- /dev/null +++ b/Help/prop_tgt/VS_JUST_MY_CODE_DEBUGGING.rst @@ -0,0 +1,12 @@ +VS_JUST_MY_CODE_DEBUGGING +------------------------- + +.. versionadded:: 3.15 + +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_KEYWORD.rst b/Help/prop_tgt/VS_KEYWORD.rst new file mode 100644 index 0000000..6c2e042 --- /dev/null +++ b/Help/prop_tgt/VS_KEYWORD.rst @@ -0,0 +1,10 @@ +VS_KEYWORD +---------- + +Visual Studio project keyword for VS 9 (2008) and older. + +Can be set to change the visual studio keyword, for example Qt +integration works better if this is set to Qt4VSv1.0. + +Use the :prop_tgt:`VS_GLOBAL_KEYWORD` target property to set the +keyword for Visual Studio 10 (2010) and newer. diff --git a/Help/prop_tgt/VS_MOBILE_EXTENSIONS_VERSION.rst b/Help/prop_tgt/VS_MOBILE_EXTENSIONS_VERSION.rst new file mode 100644 index 0000000..b307e84 --- /dev/null +++ b/Help/prop_tgt/VS_MOBILE_EXTENSIONS_VERSION.rst @@ -0,0 +1,12 @@ +VS_MOBILE_EXTENSIONS_VERSION +---------------------------- + +.. versionadded:: 3.4 + +Visual Studio Windows 10 Mobile Extensions Version + +Specifies the version of the Mobile Extensions that should be included in the +target. For example ``10.0.10240.0``. If the value is not specified, the Mobile +Extensions will not be included. To use the same version of the extensions as +the Windows 10 SDK that is being used, you can use the +:variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION` variable. 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 0000000..bf6ac10 --- /dev/null +++ b/Help/prop_tgt/VS_NO_SOLUTION_DEPLOY.rst @@ -0,0 +1,48 @@ +VS_NO_SOLUTION_DEPLOY +--------------------- + +.. versionadded:: 3.15 + +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 0000000..ec17567 --- /dev/null +++ b/Help/prop_tgt/VS_PACKAGE_REFERENCES.rst @@ -0,0 +1,15 @@ +VS_PACKAGE_REFERENCES +--------------------- + +.. versionadded:: 3.15 + +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_PLATFORM_TOOLSET.rst b/Help/prop_tgt/VS_PLATFORM_TOOLSET.rst new file mode 100644 index 0000000..27a92d6 --- /dev/null +++ b/Help/prop_tgt/VS_PLATFORM_TOOLSET.rst @@ -0,0 +1,12 @@ +VS_PLATFORM_TOOLSET +------------------- + +.. versionadded:: 3.18 + +Overrides the platform toolset used to build a target. + +Only supported when the compiler used by the given toolset is the +same as the compiler used to build the whole source tree. + +This is especially useful to create driver projects with the toolsets +"WindowsUserModeDriver10.0" or "WindowsKernelModeDriver10.0". diff --git a/Help/prop_tgt/VS_PROJECT_IMPORT.rst b/Help/prop_tgt/VS_PROJECT_IMPORT.rst new file mode 100644 index 0000000..f5e9698 --- /dev/null +++ b/Help/prop_tgt/VS_PROJECT_IMPORT.rst @@ -0,0 +1,10 @@ +VS_PROJECT_IMPORT +----------------- + +.. versionadded:: 3.15 + +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_SCC_AUXPATH.rst b/Help/prop_tgt/VS_SCC_AUXPATH.rst new file mode 100644 index 0000000..054f59e --- /dev/null +++ b/Help/prop_tgt/VS_SCC_AUXPATH.rst @@ -0,0 +1,7 @@ +VS_SCC_AUXPATH +-------------- + +Visual Studio Source Code Control Aux Path. + +Can be set to change the visual studio source code control auxpath +property. diff --git a/Help/prop_tgt/VS_SCC_LOCALPATH.rst b/Help/prop_tgt/VS_SCC_LOCALPATH.rst new file mode 100644 index 0000000..b5b7721 --- /dev/null +++ b/Help/prop_tgt/VS_SCC_LOCALPATH.rst @@ -0,0 +1,7 @@ +VS_SCC_LOCALPATH +---------------- + +Visual Studio Source Code Control Local Path. + +Can be set to change the visual studio source code control local path +property. diff --git a/Help/prop_tgt/VS_SCC_PROJECTNAME.rst b/Help/prop_tgt/VS_SCC_PROJECTNAME.rst new file mode 100644 index 0000000..6d7f628 --- /dev/null +++ b/Help/prop_tgt/VS_SCC_PROJECTNAME.rst @@ -0,0 +1,7 @@ +VS_SCC_PROJECTNAME +------------------ + +Visual Studio Source Code Control Project. + +Can be set to change the visual studio source code control project +name property. diff --git a/Help/prop_tgt/VS_SCC_PROVIDER.rst b/Help/prop_tgt/VS_SCC_PROVIDER.rst new file mode 100644 index 0000000..80475af --- /dev/null +++ b/Help/prop_tgt/VS_SCC_PROVIDER.rst @@ -0,0 +1,7 @@ +VS_SCC_PROVIDER +--------------- + +Visual Studio Source Code Control Provider. + +Can be set to change the visual studio source code control provider +property. diff --git a/Help/prop_tgt/VS_SDK_REFERENCES.rst b/Help/prop_tgt/VS_SDK_REFERENCES.rst new file mode 100644 index 0000000..9a082e7 --- /dev/null +++ b/Help/prop_tgt/VS_SDK_REFERENCES.rst @@ -0,0 +1,9 @@ +VS_SDK_REFERENCES +----------------- + +.. versionadded:: 3.7 + +Visual Studio project 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/VS_SOLUTION_DEPLOY.rst b/Help/prop_tgt/VS_SOLUTION_DEPLOY.rst new file mode 100644 index 0000000..e56f411 --- /dev/null +++ b/Help/prop_tgt/VS_SOLUTION_DEPLOY.rst @@ -0,0 +1,29 @@ +VS_SOLUTION_DEPLOY +------------------ + +.. versionadded:: 3.18 + +Specify that the target should be marked for deployment when not targeting +Windows CE, Windows Phone or a Windows Store application. + +If the target platform doesn't support deployment, this property won't have +any effect. + +:manual:`Generator expressions <cmake-generator-expressions(7)>` are supported. + +Examples +^^^^^^^^ + +Always deploy target ``foo``: + +.. code-block:: cmake + + add_executable(foo SHARED foo.cpp) + set_property(TARGET foo PROPERTY VS_SOLUTION_DEPLOY ON) + +Deploy target ``foo`` for all configurations except ``Release``: + +.. code-block:: cmake + + add_executable(foo SHARED foo.cpp) + set_property(TARGET foo PROPERTY VS_SOLUTION_DEPLOY "$<NOT:$<CONFIG:Release>>") diff --git a/Help/prop_tgt/VS_SOURCE_SETTINGS_tool.rst b/Help/prop_tgt/VS_SOURCE_SETTINGS_tool.rst new file mode 100644 index 0000000..b5a76fc --- /dev/null +++ b/Help/prop_tgt/VS_SOURCE_SETTINGS_tool.rst @@ -0,0 +1,21 @@ +VS_SOURCE_SETTINGS_<tool> +------------------------- + +.. versionadded:: 3.18 + +Set any item metadata on all non-built files that use <tool>. + +Takes a list of ``Key=Value`` pairs. Tells the Visual Studio generator +to set ``Key`` to ``Value`` as item metadata on all non-built files +that use ``<tool>``. + +For example: + +.. code-block:: cmake + + set_property(TARGET main PROPERTY VS_SOURCE_SETTINGS_FXCompile "Key=Value" "Key2=Value2") + +will set ``Key`` to ``Value`` and ``Key2`` to ``Value2`` for all +non-built files that use ``FXCompile``. + +:manual:`Generator expressions <cmake-generator-expressions(7)>` are supported. diff --git a/Help/prop_tgt/VS_USER_PROPS.rst b/Help/prop_tgt/VS_USER_PROPS.rst new file mode 100644 index 0000000..8f2a105 --- /dev/null +++ b/Help/prop_tgt/VS_USER_PROPS.rst @@ -0,0 +1,14 @@ +VS_USER_PROPS +------------- + +.. versionadded:: 3.8 + +Sets the user props file to be included in the visual studio +C++ project file. The standard path is +``$(UserRootDir)\\Microsoft.Cpp.$(Platform).user.props``, which is +in most cases the same as +``%LOCALAPPDATA%\\Microsoft\\MSBuild\\v4.0\\Microsoft.Cpp.Win32.user.props`` +or ``%LOCALAPPDATA%\\Microsoft\\MSBuild\\v4.0\\Microsoft.Cpp.x64.user.props``. + +The ``*.user.props`` files can be used for Visual Studio wide +configuration which is independent from cmake. diff --git a/Help/prop_tgt/VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION.rst b/Help/prop_tgt/VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION.rst new file mode 100644 index 0000000..50cf203 --- /dev/null +++ b/Help/prop_tgt/VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION.rst @@ -0,0 +1,12 @@ +VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION +-------------------------------------- + +.. versionadded:: 3.4 + +Visual Studio Windows Target Platform Minimum Version + +For Windows 10. Specifies the minimum version of the OS that is being +targeted. For example ``10.0.10240.0``. If the value is not specified, the +value of :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION` will be used on +WindowsStore projects otherwise the target platform minimum version will not +be specified for the project. diff --git a/Help/prop_tgt/VS_WINRT_COMPONENT.rst b/Help/prop_tgt/VS_WINRT_COMPONENT.rst new file mode 100644 index 0000000..8b4aaf7 --- /dev/null +++ b/Help/prop_tgt/VS_WINRT_COMPONENT.rst @@ -0,0 +1,13 @@ +VS_WINRT_COMPONENT +------------------ + +.. versionadded:: 3.1 + +Mark a target as a Windows Runtime component for the Visual Studio generator. +Compile the target with ``C++/CX`` language extensions for Windows Runtime. +For ``SHARED`` and ``MODULE`` libraries, this also defines the +``_WINRT_DLL`` preprocessor macro. + +.. note:: + Currently this is implemented only by Visual Studio generators. + Support may be added to other generators in the future. diff --git a/Help/prop_tgt/VS_WINRT_EXTENSIONS.rst b/Help/prop_tgt/VS_WINRT_EXTENSIONS.rst new file mode 100644 index 0000000..d1cba34 --- /dev/null +++ b/Help/prop_tgt/VS_WINRT_EXTENSIONS.rst @@ -0,0 +1,5 @@ +VS_WINRT_EXTENSIONS +------------------- + +Deprecated. Use :prop_tgt:`VS_WINRT_COMPONENT` instead. +This property was an experimental partial implementation of that one. diff --git a/Help/prop_tgt/VS_WINRT_REFERENCES.rst b/Help/prop_tgt/VS_WINRT_REFERENCES.rst new file mode 100644 index 0000000..af98b2f --- /dev/null +++ b/Help/prop_tgt/VS_WINRT_REFERENCES.rst @@ -0,0 +1,7 @@ +VS_WINRT_REFERENCES +------------------- + +Visual Studio project Windows Runtime Metadata references + +Adds one or more semicolon-delimited WinRT references to a generated +Visual Studio project. For example, "Windows;Windows.UI.Core". diff --git a/Help/prop_tgt/WIN32_EXECUTABLE.rst b/Help/prop_tgt/WIN32_EXECUTABLE.rst new file mode 100644 index 0000000..eac28ae --- /dev/null +++ b/Help/prop_tgt/WIN32_EXECUTABLE.rst @@ -0,0 +1,17 @@ +WIN32_EXECUTABLE +---------------- + +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 :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. + +This property supports +:manual:`generator expressions <cmake-generator-expressions(7)>`, except if the +target is managed (contains C# code.) diff --git a/Help/prop_tgt/WINDOWS_EXPORT_ALL_SYMBOLS.rst b/Help/prop_tgt/WINDOWS_EXPORT_ALL_SYMBOLS.rst new file mode 100644 index 0000000..00f32f6 --- /dev/null +++ b/Help/prop_tgt/WINDOWS_EXPORT_ALL_SYMBOLS.rst @@ -0,0 +1,28 @@ +WINDOWS_EXPORT_ALL_SYMBOLS +-------------------------- + +.. versionadded:: 3.4 + +This property is implemented only for MS-compatible tools on Windows. + +Enable this boolean property to automatically create a module definition +(``.def``) file with all global symbols found in the input ``.obj`` files +for a ``SHARED`` library (or executable with :prop_tgt:`ENABLE_EXPORTS`) +on Windows. The module definition file will be passed to the linker +causing all symbols to be exported from the ``.dll``. +For global *data* symbols, ``__declspec(dllimport)`` must still be used when +compiling against the code in the ``.dll``. All other function symbols will +be automatically exported and imported by callers. This simplifies porting +projects to Windows by reducing the need for explicit ``dllexport`` markup, +even in ``C++`` classes. + +When this property is enabled, zero or more ``.def`` files may also be +specified as source files of the target. The exports named by these files +will be merged with those detected from the object files to generate a +single module definition file to be passed to the linker. This can be +used to export symbols from a ``.dll`` that are not in any of its object +files but are added by the linker from dependencies (e.g. ``msvcrt.lib``). + +This property is initialized by the value of +the :variable:`CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS` 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 new file mode 100644 index 0000000..fbe7608 --- /dev/null +++ b/Help/prop_tgt/XCODE_ATTRIBUTE_an-attribute.rst @@ -0,0 +1,22 @@ +XCODE_ATTRIBUTE_<an-attribute> +------------------------------ + +Set Xcode target attributes directly. + +Tell the :generator:`Xcode` generator to set ``<an-attribute>`` to a given +value in the generated Xcode project. Ignored on other generators. + +This offers low-level control over the generated Xcode project file. +It is meant as a last resort for specifying settings that CMake does +not otherwise have a way to control. Although this can override a +setting CMake normally produces on its own, doing so bypasses CMake's +model of the project and can break things. + +See the :variable:`CMAKE_XCODE_ATTRIBUTE_<an-attribute>` variable +to set attributes on all targets in a directory tree. + +Contents of ``XCODE_ATTRIBUTE_<an-attribute>`` 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/XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY.rst b/Help/prop_tgt/XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY.rst new file mode 100644 index 0000000..7b68126 --- /dev/null +++ b/Help/prop_tgt/XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY.rst @@ -0,0 +1,8 @@ +XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY +---------------------------------------- + +.. versionadded:: 3.20 + +Tell the :generator:`Xcode` generator to perform code signing for all the +frameworks and libraries that are embedded using the +:prop_tgt:`XCODE_EMBED_FRAMEWORKS <XCODE_EMBED_<type>>` property. diff --git a/Help/prop_tgt/XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY.rst b/Help/prop_tgt/XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY.rst new file mode 100644 index 0000000..29f8c5c --- /dev/null +++ b/Help/prop_tgt/XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY.rst @@ -0,0 +1,8 @@ +XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY +--------------------------------------------- + +.. versionadded:: 3.20 + +Tell the :generator:`Xcode` generator to remove headers from all the +frameworks that are embedded using the +:prop_tgt:`XCODE_EMBED_FRAMEWORKS <XCODE_EMBED_<type>>` property. diff --git a/Help/prop_tgt/XCODE_EMBED_type.rst b/Help/prop_tgt/XCODE_EMBED_type.rst new file mode 100644 index 0000000..90c5bc7 --- /dev/null +++ b/Help/prop_tgt/XCODE_EMBED_type.rst @@ -0,0 +1,14 @@ +XCODE_EMBED_<type> +------------------ + +.. versionadded:: 3.20 + +Tell the :generator:`Xcode` generator to embed the specified list of items into +the target bundle. ``<type>`` specifies the embed build phase to use. + +Currently, the only supported value for ``<type>`` is ``FRAMEWORKS``. +The specified items will be added to the ``Embed Frameworks`` build phase. +The items can be CMake target names or paths to frameworks or libraries. +See also :prop_tgt:`XCODE_EMBED_<type>_PATH`, +:prop_tgt:`XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY` and +:prop_tgt:`XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY`. diff --git a/Help/prop_tgt/XCODE_EMBED_type_PATH.rst b/Help/prop_tgt/XCODE_EMBED_type_PATH.rst new file mode 100644 index 0000000..887cf57 --- /dev/null +++ b/Help/prop_tgt/XCODE_EMBED_type_PATH.rst @@ -0,0 +1,9 @@ +XCODE_EMBED_<type>_PATH +----------------------- + +.. versionadded:: 3.20 + +Tell the :generator:`Xcode` generator the relative path to use when embedding +the items specified by :prop_tgt:`XCODE_EMBED_<type>`. The path is relative +to the base location of the ``Embed XXX`` build phase associated with +``<type>``. diff --git a/Help/prop_tgt/XCODE_EXPLICIT_FILE_TYPE.rst b/Help/prop_tgt/XCODE_EXPLICIT_FILE_TYPE.rst new file mode 100644 index 0000000..e01a034 --- /dev/null +++ b/Help/prop_tgt/XCODE_EXPLICIT_FILE_TYPE.rst @@ -0,0 +1,10 @@ +XCODE_EXPLICIT_FILE_TYPE +------------------------ + +.. versionadded:: 3.8 + +Set the Xcode ``explicitFileType`` attribute on its reference to a +target. CMake computes a default based on target type but +can be told explicitly with this property. + +See also :prop_tgt:`XCODE_PRODUCT_TYPE`. diff --git a/Help/prop_tgt/XCODE_GENERATE_SCHEME.rst b/Help/prop_tgt/XCODE_GENERATE_SCHEME.rst new file mode 100644 index 0000000..06a3cf9 --- /dev/null +++ b/Help/prop_tgt/XCODE_GENERATE_SCHEME.rst @@ -0,0 +1,43 @@ +XCODE_GENERATE_SCHEME +--------------------- + +.. versionadded:: 3.15 + +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` +- :prop_tgt:`XCODE_SCHEME_WORKING_DIRECTORY` diff --git a/Help/prop_tgt/XCODE_LINK_BUILD_PHASE_MODE.rst b/Help/prop_tgt/XCODE_LINK_BUILD_PHASE_MODE.rst new file mode 100644 index 0000000..836cc6b --- /dev/null +++ b/Help/prop_tgt/XCODE_LINK_BUILD_PHASE_MODE.rst @@ -0,0 +1,55 @@ +XCODE_LINK_BUILD_PHASE_MODE +--------------------------- + +.. versionadded:: 3.19 + +When using the :generator:`Xcode` generator, libraries to be linked will be +specified in the Xcode project file using either the "Link Binary With +Libraries" build phase or directly as linker flags. The former allows Xcode +to manage build paths, which may be necessary when creating Xcode archives +because it may use different build paths to a regular build. + +This property controls usage of "Link Binary With Libraries" build phase for +a target that is an app bundle, executable, shared library, shared framework +or a module library. + +Possible values are: + +* ``NONE`` + The libraries will be linked by specifying the linker flags directly. + +* ``BUILT_ONLY`` + The "Link Binary With Libraries" build phase will be used to link to another + target under the following conditions: + + - The target to be linked to is a regular non-imported, non-interface library + target. + - The output directory of the target being built has not been changed from + its default (see :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` and + :prop_tgt:`LIBRARY_OUTPUT_DIRECTORY`). + +* ``KNOWN_LOCATION`` + The "Link Binary With Libraries" build phase will be used to link to another + target under the same conditions as with ``BUILT_ONLY`` and also: + + - Imported library targets except those of type ``UNKNOWN``. + - Any non-target library specified directly with a path. + +For all other cases, the libraries will be linked by specifying the linker +flags directly. + +.. warning:: + Libraries linked using "Link Binary With Libraries" are linked after the + ones linked through regular linker flags. This order should be taken into + account when different static libraries contain symbols with the same name, + as the former ones will take precedence over the latter. + +.. warning:: + If two or more directories contain libraries with identical file names and + some libraries are linked from those directories, the library search path + lookup will end up linking libraries from the first directory. This is a + known limitation of Xcode. + +This property is initialized by the value of the +:variable:`CMAKE_XCODE_LINK_BUILD_PHASE_MODE` variable if it is set when a +target is created. diff --git a/Help/prop_tgt/XCODE_PRODUCT_TYPE.rst b/Help/prop_tgt/XCODE_PRODUCT_TYPE.rst new file mode 100644 index 0000000..17a9c3f --- /dev/null +++ b/Help/prop_tgt/XCODE_PRODUCT_TYPE.rst @@ -0,0 +1,10 @@ +XCODE_PRODUCT_TYPE +------------------ + +.. versionadded:: 3.8 + +Set the Xcode ``productType`` attribute on its reference to a +target. CMake computes a default based on target type but +can be told explicitly with this property. + +See also :prop_tgt:`XCODE_EXPLICIT_FILE_TYPE`. 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 0000000..c72ec06 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER.rst @@ -0,0 +1,14 @@ +XCODE_SCHEME_ADDRESS_SANITIZER +------------------------------ + +.. versionadded:: 3.13 + +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 0000000..293b5d4 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN.rst @@ -0,0 +1,14 @@ +XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN +----------------------------------------------- + +.. versionadded:: 3.13 + +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 0000000..2bfcb41 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_ARGUMENTS.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_ARGUMENTS +---------------------- + +.. versionadded:: 3.13 + +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 0000000..2523deb --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_DEBUG_AS_ROOT.rst @@ -0,0 +1,9 @@ +XCODE_SCHEME_DEBUG_AS_ROOT +-------------------------- + +.. versionadded:: 3.15 + +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 0000000..bbcae35 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING.rst @@ -0,0 +1,15 @@ +XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING +-------------------------------------- + +.. versionadded:: 3.16 + +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 0000000..3d315a2 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER.rst @@ -0,0 +1,14 @@ +XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER +---------------------------------------- + +.. versionadded:: 3.13 + +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 0000000..2ca20f7 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS.rst @@ -0,0 +1,14 @@ +XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS +---------------------------------- + +.. versionadded:: 3.13 + +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 0000000..278c9ef --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE.rst @@ -0,0 +1,14 @@ +XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE +------------------------------------- + +.. versionadded:: 3.13 + +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 0000000..16542f8 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_ENVIRONMENT.rst @@ -0,0 +1,14 @@ +XCODE_SCHEME_ENVIRONMENT +------------------------ + +.. versionadded:: 3.13 + +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 0000000..b453f10 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_EXECUTABLE.rst @@ -0,0 +1,11 @@ +XCODE_SCHEME_EXECUTABLE +----------------------- + +.. versionadded:: 3.13 + +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 0000000..4b242a2 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_GUARD_MALLOC.rst @@ -0,0 +1,14 @@ +XCODE_SCHEME_GUARD_MALLOC +------------------------------ + +.. versionadded:: 3.13 + +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 0000000..2a813aa --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP.rst @@ -0,0 +1,15 @@ +XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP +------------------------------------- + +.. versionadded:: 3.13 + +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 0000000..750da74 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_MALLOC_GUARD_EDGES.rst @@ -0,0 +1,14 @@ +XCODE_SCHEME_MALLOC_GUARD_EDGES +------------------------------- + +.. versionadded:: 3.13 + +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 0000000..4ebd21b --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_MALLOC_SCRIBBLE.rst @@ -0,0 +1,14 @@ +XCODE_SCHEME_MALLOC_SCRIBBLE +------------------------------ + +.. versionadded:: 3.13 + +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 0000000..5afe34e --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_MALLOC_STACK.rst @@ -0,0 +1,14 @@ +XCODE_SCHEME_MALLOC_STACK +------------------------- + +.. versionadded:: 3.13 + +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 0000000..cc774c4 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_THREAD_SANITIZER.rst @@ -0,0 +1,14 @@ +XCODE_SCHEME_THREAD_SANITIZER +----------------------------- + +.. versionadded:: 3.13 + +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 0000000..3bb2596 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_THREAD_SANITIZER_STOP.rst @@ -0,0 +1,14 @@ +XCODE_SCHEME_THREAD_SANITIZER_STOP +---------------------------------- + +.. versionadded:: 3.13 + +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 0000000..1146130 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER.rst @@ -0,0 +1,14 @@ +XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER +------------------------------------------ + +.. versionadded:: 3.13 + +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 0000000..358f298 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP.rst @@ -0,0 +1,15 @@ +XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP +----------------------------------------------- + +.. versionadded:: 3.13 + +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_WORKING_DIRECTORY.rst b/Help/prop_tgt/XCODE_SCHEME_WORKING_DIRECTORY.rst new file mode 100644 index 0000000..d8d56fc --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_WORKING_DIRECTORY.rst @@ -0,0 +1,15 @@ +XCODE_SCHEME_WORKING_DIRECTORY +------------------------------ + +.. versionadded:: 3.17 + +Specify the ``Working Directory`` of the *Run* and *Profile* +actions in the generated Xcode scheme. In case the value contains +generator expressions those are evaluated. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_WORKING_DIRECTORY` 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 0000000..6030109 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_ZOMBIE_OBJECTS.rst @@ -0,0 +1,14 @@ +XCODE_SCHEME_ZOMBIE_OBJECTS +------------------------------ + +.. versionadded:: 3.13 + +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/prop_tgt/XCTEST.rst b/Help/prop_tgt/XCTEST.rst new file mode 100644 index 0000000..67e9a70 --- /dev/null +++ b/Help/prop_tgt/XCTEST.rst @@ -0,0 +1,15 @@ +XCTEST +------ + +.. versionadded:: 3.3 + +This target is a XCTest CFBundle on the Mac. + +This property will usually get set via the :command:`xctest_add_bundle` +macro in :module:`FindXCTest` module. + +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 +structure required for a CFBundle. + +This property depends on :prop_tgt:`BUNDLE` to be effective. diff --git a/Help/prop_tgt/XXX_OUTPUT_DIRECTORY.txt b/Help/prop_tgt/XXX_OUTPUT_DIRECTORY.txt new file mode 100644 index 0000000..d38a96e --- /dev/null +++ b/Help/prop_tgt/XXX_OUTPUT_DIRECTORY.txt @@ -0,0 +1,12 @@ +Output directory in which to build |XXX| target files. + +This property specifies the directory into which |xxx| target files +should be built. The property value may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. +Multi-configuration generators (:ref:`Visual Studio <Visual Studio Generators>`, +:generator:`Xcode`, :generator:`Ninja Multi-Config`) append a +per-configuration subdirectory to the specified directory unless a generator +expression is used. + +This property is initialized by the value of the +|CMAKE_XXX_OUTPUT_DIRECTORY| variable if it is set when a target is created. diff --git a/Help/prop_tgt/XXX_OUTPUT_NAME.txt b/Help/prop_tgt/XXX_OUTPUT_NAME.txt new file mode 100644 index 0000000..126f391 --- /dev/null +++ b/Help/prop_tgt/XXX_OUTPUT_NAME.txt @@ -0,0 +1,5 @@ +Output name for |XXX| target files. + +This property specifies the base name for |xxx| target files. It +overrides :prop_tgt:`OUTPUT_NAME` and :prop_tgt:`OUTPUT_NAME_<CONFIG>` +properties. diff --git a/Help/release/3.0.rst b/Help/release/3.0.rst new file mode 100644 index 0000000..64491e3 --- /dev/null +++ b/Help/release/3.0.rst @@ -0,0 +1,473 @@ +CMake 3.0 Release Notes +*********************** + +.. only:: html + + .. contents:: + +Changes made since CMake 2.8.12 include the following. + +Documentation Changes +===================== + +* The CMake documentation has been converted to reStructuredText and + now transforms via Sphinx (`<http://sphinx-doc.org>`__) into man and + html pages. This allows the documentation to be properly indexed + and to contain cross-references. + + Conversion from the old internal documentation format was done by + an automatic process so some documents may still contain artifacts. + They will be updated incrementally over time. + + A basic reStructuredText processor has been implemented to support + ``cmake --help-command`` and similar command-line options. + +* New manuals were added: + + - :manual:`cmake-buildsystem(7)` + - :manual:`cmake-commands(7)`, replacing ``cmakecommands(1)`` + and ``cmakecompat(1)`` + - :manual:`cmake-developer(7)` + - :manual:`cmake-generator-expressions(7)` + - :manual:`cmake-generators(7)` + - :manual:`cmake-language(7)` + - :manual:`cmake-modules(7)`, replacing ``cmakemodules(1)`` + - :manual:`cmake-packages(7)` + - :manual:`cmake-policies(7)`, replacing ``cmakepolicies(1)`` + - :manual:`cmake-properties(7)`, replacing ``cmakeprops(1)`` + - :manual:`cmake-qt(7)` + - :manual:`cmake-toolchains(7)` + - :manual:`cmake-variables(7)`, replacing ``cmakevars(1)`` + +* Release notes for CMake 3.0.0 and above will now be included with + the html documentation. + +New Features +============ + +Syntax +------ + +* The CMake language has been extended with + :ref:`Bracket Argument` and :ref:`Bracket Comment` + syntax inspired by Lua long brackets:: + + set(x [===[bracket argument]===] #[[bracket comment]]) + + Content between equal-length open- and close-brackets is taken + literally with no variable replacements. + + .. warning:: + This syntax change could not be made in a fully compatible + way. No policy is possible because syntax parsing occurs before + any chance to set a policy. Existing code using an unquoted + argument that starts with an open bracket will be interpreted + differently without any diagnostic. Fortunately the syntax is + obscure enough that this problem is unlikely in practice. + +Generators +---------- + +* A new :generator:`CodeLite` extra generator is available + for use with the Makefile or Ninja generators. + +* A new :generator:`Kate` extra generator is available + for use with the Makefile or Ninja generators. + +* The :generator:`Ninja` generator learned to use ``ninja`` job pools + when specified by a new :prop_gbl:`JOB_POOLS` global property. + +Commands +-------- + +* The :command:`add_library` command learned a new ``INTERFACE`` + library type. Interface libraries have no build rules but may + have properties defining + :manual:`usage requirements <cmake-buildsystem(7)>` + and may be installed, exported, and imported. This is useful to + create header-only libraries that have concrete link dependencies + on other libraries. + +* The :command:`export()` command learned a new ``EXPORT`` mode that + retrieves the list of targets to export from an export set configured + by the :command:`install(TARGETS)` command ``EXPORT`` option. This + makes it easy to export from the build tree the same targets that + are exported from the install tree. + +* The :command:`export` command learned to work with multiple dependent + export sets, thus allowing multiple packages to be built and exported + from a single tree. The feature requires CMake to wait until the + generation step to write the output file. This means one should not + :command:`include` the generated targets file later during project + configuration because it will not be available. + Use :ref:`Alias Targets` instead. See policy :policy:`CMP0024`. + +* The :command:`install(FILES)` command learned to support + :manual:`generator expressions <cmake-generator-expressions(7)>` + in the list of files. + +* The :command:`project` command learned to set some version variables + to values specified by the new ``VERSION`` option or to empty strings. + See policy :policy:`CMP0048`. + +* The :command:`string` command learned a new ``CONCAT`` mode. + It is particularly useful in combination with the new + :ref:`Bracket Argument` syntax. + +* The :command:`unset` command learned a ``PARENT_SCOPE`` option + matching that of the :command:`set` command. + +* The :command:`include_external_msproject` command learned + to handle non-C++ projects like ``.vbproj`` or ``.csproj``. + +* The :command:`ctest_update` command learned to update work trees + managed by the Perforce (p4) version control tool. + +* The :command:`message` command learned a ``DEPRECATION`` mode. Such + messages are not issued by default, but may be issued as a warning if + :variable:`CMAKE_WARN_DEPRECATED` is enabled, or as an error if + :variable:`CMAKE_ERROR_DEPRECATED` is enabled. + +* The :command:`target_link_libraries` command now allows repeated use of + the ``LINK_PUBLIC`` and ``LINK_PRIVATE`` keywords. + +Variables +--------- + +* Variable :variable:`CMAKE_FIND_NO_INSTALL_PREFIX` has been + introduced to tell CMake not to add the value of + :variable:`CMAKE_INSTALL_PREFIX` to the + :variable:`CMAKE_SYSTEM_PREFIX_PATH` variable by default. + This is useful when building a project that installs some + of its own dependencies to avoid finding files it is about + to replace. + +* Variable :variable:`CMAKE_STAGING_PREFIX` was introduced for use + when cross-compiling to specify an installation prefix on the + host system that differs from a :variable:`CMAKE_INSTALL_PREFIX` + value meant for the target system. + +* Variable :variable:`CMAKE_SYSROOT` was introduced to specify the + toolchain SDK installation prefix, typically for cross-compiling. + This is used to pass a ``--sysroot`` option to the compiler and + as a prefix searched by ``find_*`` commands. + +* Variable :variable:`CMAKE_<LANG>_COMPILER_TARGET` was introduced + for use when cross-compiling to specify the target platform in the + :ref:`toolchain file <Cross Compiling Toolchain>` specified by the + :variable:`CMAKE_TOOLCHAIN_FILE` variable. + This is used to pass an option such as ``--target=<triple>`` to some + cross-compiling compiler drivers. + +* Variable :variable:`CMAKE_MAP_IMPORTED_CONFIG_<CONFIG>` has been + introduced to optionally initialize the + :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` target property. + +Properties +---------- + +* The :prop_dir:`ADDITIONAL_MAKE_CLEAN_FILES` directory property + learned to support + :manual:`generator expressions <cmake-generator-expressions(7)>`. + +* A new directory property :prop_dir:`CMAKE_CONFIGURE_DEPENDS` + was introduced to allow projects to specify additional + files on which the configuration process depends. CMake will + re-run at build time when one of these files is modified. + Previously this was only possible to achieve by specifying + such files as the input to a :command:`configure_file` command. + +* A new :ref:`Qt AUTORCC` feature replaces the need to + invoke ``qt4_add_resources()`` by allowing ``.qrc`` files to + be listed as target sources. + +* A new :ref:`Qt AUTOUIC` feature replaces the need to + invoke ``qt4_wrap_ui()``. + +* Test properties learned to support + :manual:`generator expressions <cmake-generator-expressions(7)>`. + This is useful to specify per-configuration values for test + properties like :prop_test:`REQUIRED_FILES` and + :prop_test:`WORKING_DIRECTORY`. + +* A new :prop_test:`SKIP_RETURN_CODE` test property was introduced + to tell :manual:`ctest(1)` to treat a particular test return code as + if the test were not run. This is useful for test drivers to report + that certain test requirements were not available. + +* New types of :ref:`Compatible Interface Properties` were introduced, + namely the :prop_tgt:`COMPATIBLE_INTERFACE_NUMBER_MAX` and + :prop_tgt:`COMPATIBLE_INTERFACE_NUMBER_MIN` for calculating numeric + maximum and minimum values respectively. + +Modules +------- + +* The :module:`CheckTypeSize` module ``check_type_size`` macro and + the :module:`CheckStructHasMember` module ``check_struct_has_member`` + macro learned a new ``LANGUAGE`` option to optionally check C++ types. + +* The :module:`ExternalData` module learned to work with no + URL templates if a local store is available. + +* The :module:`ExternalProject` function ``ExternalProject_Add`` + learned a new ``GIT_SUBMODULES`` option to specify a subset + of available submodules to checkout. + +* A new :module:`FindBacktrace` module has been added to support + :command:`find_package(Backtrace)` calls. + +* A new :module:`FindLua` module has been added to support + :command:`find_package(Lua)` calls. + +* The :module:`FindBoost` module learned a new ``Boost_NAMESPACE`` + option to change the ``boost`` prefix on library names. + +* The :module:`FindBoost` module learned to control search + 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. + +* The :module:`FindJava` and :module:`FindJNI` modules learned + to use a ``JAVA_HOME`` CMake variable or environment variable, + and then try ``/usr/libexec/java_home`` on OS X. + +* The :module:`UseJava` module ``add_jar`` function learned a new + ``MANIFEST`` option to pass the ``-m`` option to ``jar``. + +* A new :module:`CMakeFindDependencyMacro` module was introduced with + a ``find_dependency`` macro to find transitive dependencies in + a :manual:`package configuration file <cmake-packages(7)>`. Such + dependencies are omitted by the listing of the :module:`FeatureSummary` + module. + +* The :module:`FindQt4` module learned to create :ref:`Imported Targets` + for Qt executables. This helps disambiguate when using multiple + :manual:`Qt versions <cmake-qt(7)>` in the same buildsystem. + +* The :module:`FindRuby` module learned to search for Ruby 2.0 and 2.1. + +Generator Expressions +--------------------- + +* New ``$<PLATFORM_ID>`` and ``$<PLATFORM_ID:...>`` + :manual:`generator expressions <cmake-generator-expressions(7)>` + have been added. + +* The ``$<CONFIG>`` + :manual:`generator expression <cmake-generator-expressions(7)>` now has + a variant which takes no argument. This is equivalent to the + ``$<CONFIGURATION>`` expression. + +* New ``$<UPPER_CASE:...>`` and ``$<LOWER_CASE:...>`` + :manual:`generator expressions <cmake-generator-expressions(7)>` + generator expressions have been added. + +* A new ``$<MAKE_C_IDENTIFIER:...>`` + :manual:`generator expression <cmake-generator-expressions(7)>` has + been added. + +Other +----- + +* The :manual:`cmake(1)` ``-E`` option learned a new ``sleep`` command. + +* The :manual:`ccmake(1)` dialog learned to honor the + :prop_cache:`STRINGS` cache entry property to cycle through + the enumerated list of possible values. + +* The :manual:`cmake-gui(1)` dialog learned to remember window + settings between sessions. + +* The :manual:`cmake-gui(1)` dialog learned to remember the type + of a cache entry for completion in the ``Add Entry`` dialog. + +New Diagnostics +=============== + +* Directories named in the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` + target property of imported targets linked conditionally by a + :manual:`generator expression <cmake-generator-expressions(7)>` + were not checked for existence. Now they are checked. + See policy :policy:`CMP0027`. + +* Build target names must now match a validity pattern and may no longer + conflict with CMake-defined targets. See policy :policy:`CMP0037`. + +* Build targets that specify themselves as a link dependency were + silently accepted but are now diagnosed. See :policy:`CMP0038`. + +* The :command:`target_link_libraries` command used to silently ignore + calls specifying as their first argument build targets created by + :command:`add_custom_target` but now diagnoses this mistake. + See policy :policy:`CMP0039`. + +* The :command:`add_custom_command` command used to silently ignore + calls specifying the ``TARGET`` option with a non-existent target + but now diagnoses this mistake. See policy :policy:`CMP0040`. + +* Relative paths in the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` + target property used to be silently accepted if they contained a + :manual:`generator expression <cmake-generator-expressions(7)>` + but are now rejected. See policy :policy:`CMP0041`. + +* The :command:`get_target_property` command learned to reject calls + specifying a non-existent target. See policy :policy:`CMP0045`. + +* The :command:`add_dependencies` command learned to reject calls + specifying a dependency on a non-existent target. + See policy :policy:`CMP0046`. + +* Link dependency analysis learned to assume names containing ``::`` + refer to :ref:`Alias Targets` or :ref:`Imported Targets`. It will + now produce an error if such a linked target is missing. Previously + in this case CMake generated a link line that failed at build time. + See policy :policy:`CMP0028`. + +* When the :command:`project` or :command:`enable_language` commands + initialize support for a language, it is now an error if the full + path to the compiler cannot be found and stored in the corresponding + :variable:`CMAKE_<LANG>_COMPILER` variable. This produces nicer error + messages up front and stops processing when no working compiler + is known to be available. + +* Target sources specified with the :command:`add_library` or + :command:`add_executable` command learned to reject items which + require an undocumented extra layer of variable expansion. + See policy :policy:`CMP0049`. + +* Use of :command:`add_custom_command` undocumented ``SOURCE`` + signatures now results in an error. See policy :policy:`CMP0050`. + +Deprecated and Removed Features +=============================== + +* Compatibility options supporting code written for CMake versions + prior to 2.4 have been removed. + +* Several long-outdated commands that should no longer be called + have been disallowed in new code by policies: + + - Policy :policy:`CMP0029` disallows :command:`subdir_depends` + - Policy :policy:`CMP0030` disallows :command:`use_mangled_mesa` + - Policy :policy:`CMP0031` disallows :command:`load_command` + - Policy :policy:`CMP0032` disallows :command:`output_required_files` + - Policy :policy:`CMP0033` disallows :command:`export_library_dependencies` + - Policy :policy:`CMP0034` disallows :command:`utility_source` + - Policy :policy:`CMP0035` disallows :command:`variable_requires` + - Policy :policy:`CMP0036` disallows :command:`build_name` + +* The :manual:`cmake(1)` ``-i`` wizard mode has been removed. + Instead use an interactive dialog such as :manual:`ccmake(1)` + or use the ``-D`` option to set cache values from the command line. + +* The builtin documentation formatters that supported command-line + options such as ``--help-man`` and ``--help-html`` have been removed + in favor of the above-mentioned new documentation system. These and + other command-line options that used to generate man- and html- + formatted pages no longer work. The :manual:`cmake(1)` + ``--help-custom-modules`` option now produces a warning at runtime + and generates a minimal document that reports the limitation. + +* The :prop_dir:`COMPILE_DEFINITIONS_<CONFIG>` directory properties and the + :prop_tgt:`COMPILE_DEFINITIONS_<CONFIG>` target properties have been + deprecated. Instead set the corresponding :prop_dir:`COMPILE_DEFINITIONS` + directory property or :prop_tgt:`COMPILE_DEFINITIONS` target property and + use :manual:`generator expressions <cmake-generator-expressions(7)>` like + ``$<CONFIG:...>`` to specify per-configuration definitions. + See policy :policy:`CMP0043`. + +* The :prop_tgt:`LOCATION` target property should no longer be read from + non-IMPORTED targets. It does not make sense in multi-configuration + generators since the build configuration is not known while configuring + the project. It has been superseded by the ``$<TARGET_FILE>`` generator + expression. See policy :policy:`CMP0026`. + +* The :prop_tgt:`COMPILE_FLAGS` target property is now documented + as deprecated, though no warning is issued. Use the + :prop_tgt:`COMPILE_OPTIONS` target property or the + :command:`target_compile_options` command instead. + +* The :module:`GenerateExportHeader` module ``add_compiler_export_flags`` + function is now deprecated. It has been superseded by the + :prop_tgt:`<LANG>_VISIBILITY_PRESET` and + :prop_tgt:`VISIBILITY_INLINES_HIDDEN` target properties. + +Other Changes +============= + +* The version scheme was changed to use only two components for + the feature level instead of three. The third component will + now be used for bug-fix releases or the date of development versions. + See the :variable:`CMAKE_VERSION` variable documentation for details. + +* The default install locations of CMake itself on Windows and + OS X no longer contain the CMake version number. This allows + for easy replacement without re-generating local build trees + manually. + +* Generators for Visual Studio 10 (2010) and later were renamed to + include the product year like generators for older VS versions: + + - ``Visual Studio 10`` -> :generator:`Visual Studio 10 2010` + - ``Visual Studio 11`` -> :generator:`Visual Studio 11 2012` + - ``Visual Studio 12`` -> :generator:`Visual Studio 12 2013` + + This clarifies which generator goes with each Visual Studio + version. The old names are recognized for compatibility. + +* The :variable:`CMAKE_<LANG>_COMPILER_ID` value for Apple-provided + Clang is now ``AppleClang``. It must be distinct from upstream + Clang because the version numbers differ. + See policy :policy:`CMP0025`. + +* The :variable:`CMAKE_<LANG>_COMPILER_ID` value for ``qcc`` on QNX + is now ``QCC``. It must be distinct from ``GNU`` because the + command-line options differ. See policy :policy:`CMP0047`. + +* On 64-bit OS X the :variable:`CMAKE_HOST_SYSTEM_PROCESSOR` value + is now correctly detected as ``x86_64`` instead of ``i386``. + +* On OS X, CMake learned to enable behavior specified by the + :prop_tgt:`MACOSX_RPATH` target property by default. This activates + use of ``@rpath`` for runtime shared library searches. + See policy :policy:`CMP0042`. + +* The :command:`build_command` command now returns a :manual:`cmake(1)` + ``--build`` command line instead of a direct invocation of the native + build tool. When using ``Visual Studio`` generators, CMake and CTest + no longer require :variable:`CMAKE_MAKE_PROGRAM` to be located up front. + Selection of the proper msbuild or devenv tool is now performed as + late as possible when the solution (``.sln``) file is available so + it can depend on project content. + +* The :manual:`cmake(1)` ``--build`` command now shares its own stdout + and stderr pipes with the native build tool by default. + The ``--use-stderr`` option that once activated this is now ignored. + +* The ``$<C_COMPILER_ID:...>`` and ``$<CXX_COMPILER_ID:...>`` + :manual:`generator expressions <cmake-generator-expressions(7)>` + used to perform case-insensitive comparison but have now been + corrected to perform case-sensitive comparison. + See policy :policy:`CMP0044`. + +* The builtin ``edit_cache`` target will no longer select + :manual:`ccmake(1)` by default when no interactive terminal will + be available (e.g. with :generator:`Ninja` or an IDE generator). + Instead :manual:`cmake-gui(1)` will be preferred if available. + +* The :module:`ExternalProject` download step learned to + re-attempt download in certain cases to be more robust to + temporary network failure. + +* The :module:`FeatureSummary` no longer lists transitive + dependencies since they were not directly requested by the + current project. + +* The ``cmake-mode.el`` major Emacs editing mode has been cleaned + up and enhanced in several ways. + +* Include directories specified in the + :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of :ref:`Imported Targets` + are treated as ``SYSTEM`` includes by default when handled as + :ref:`usage requirements <Include Directories and Usage Requirements>`. diff --git a/Help/release/3.1.rst b/Help/release/3.1.rst new file mode 100644 index 0000000..3f4712b --- /dev/null +++ b/Help/release/3.1.rst @@ -0,0 +1,425 @@ +CMake 3.1 Release Notes +*********************** + +.. only:: html + + .. contents:: + +Changes made since CMake 3.0 include the following. + +Documentation Changes +===================== + +* A new :manual:`cmake-compile-features(7)` manual was added. + +New Features +============ + +Generators +---------- + +* The :generator:`Visual Studio 14 2015` generator was added. + +Windows Phone and Windows Store +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* Generators for Visual Studio 11 (2012) and above learned to generate + projects for Windows Phone and Windows Store. One may set the + :variable:`CMAKE_SYSTEM_NAME` variable to ``WindowsPhone`` + or ``WindowsStore`` on the :manual:`cmake(1)` command-line + or in a :variable:`CMAKE_TOOLCHAIN_FILE` to activate these platforms. + Also set :variable:`CMAKE_SYSTEM_VERSION` to ``8.0`` or ``8.1`` to + specify the version of Windows to be targeted. + +NVIDIA Nsight Tegra +^^^^^^^^^^^^^^^^^^^ + +* Generators for Visual Studio 10 (2010) and above learned to generate + projects for NVIDIA Nsight Tegra Visual Studio Edition. One may set + the :variable:`CMAKE_SYSTEM_NAME` variable to ``Android`` on the + :manual:`cmake(1)` command-line or in a :variable:`CMAKE_TOOLCHAIN_FILE` + to activate this platform. + +Syntax +------ + +* The :manual:`cmake-language(7)` syntax for :ref:`Variable References` and + :ref:`Escape Sequences` was simplified in order to allow a much faster + implementation. See policy :policy:`CMP0053`. + +* The :command:`if` command no longer automatically dereferences + variables named in quoted or bracket arguments. See policy + :policy:`CMP0054`. + +Commands +-------- + +* The :command:`add_custom_command` command learned to interpret + :manual:`cmake-generator-expressions(7)` in arguments to ``DEPENDS``. + +* The :command:`export(PACKAGE)` command learned to check the + :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` variable to skip + exporting the package. + +* The :command:`file(STRINGS)` command gained a new ``ENCODING`` + option to enable extraction of ``UTF-8`` strings. + +* The :command:`find_package` command learned to check the + :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` and + :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` + variables to skip searching the package registries. + +* The :command:`get_property` command learned a new ``INSTALL`` scope + for properties. + +* The :command:`install` command learned a ``MESSAGE_NEVER`` option + to avoid output during installation. + +* The :command:`set_property` command learned a new ``INSTALL`` scope + for properties. + +* The :command:`string` command learned a new ``GENEX_STRIP`` subcommand + which removes + :manual:`generator expression <cmake-generator-expressions(7)>`. + +* The :command:`string` command learned a new ``UUID`` subcommand + to generate a universally unique identifier. + +* New :command:`target_compile_features` command allows populating the + :prop_tgt:`COMPILE_FEATURES` target property, just like any other + build variable. + +* The :command:`target_sources` command was added to add to the + :prop_tgt:`SOURCES` target property. + +Variables +--------- + +* The Visual Studio generators for versions 8 (2005) and above + learned to read the target platform name from a new + :variable:`CMAKE_GENERATOR_PLATFORM` variable when it is + not specified as part of the generator name. The platform + name may be specified on the :manual:`cmake(1)` command line + with the ``-A`` option, e.g. ``-G "Visual Studio 12 2013" -A x64``. + +* The :variable:`CMAKE_GENERATOR_TOOLSET` variable may now be + initialized in a toolchain file specified by the + :variable:`CMAKE_TOOLCHAIN_FILE` variable. This is useful + when cross-compiling with the Xcode or Visual Studio + generators. + +* The :variable:`CMAKE_INSTALL_MESSAGE` variable was introduced to + optionally reduce output installation. + +Properties +---------- + +* New :prop_tgt:`CXX_STANDARD` and :prop_tgt:`CXX_EXTENSIONS` target + properties may specify values which CMake uses to compute required + compile options such as ``-std=c++11`` or ``-std=gnu++11``. The + :variable:`CMAKE_CXX_STANDARD` and :variable:`CMAKE_CXX_EXTENSIONS` + variables may be set to initialize the target properties. + +* New :prop_tgt:`C_STANDARD` and :prop_tgt:`C_EXTENSIONS` target + properties may specify values which CMake uses to compute required + compile options such as ``-std=c11`` or ``-std=gnu11``. The + :variable:`CMAKE_C_STANDARD` and :variable:`CMAKE_C_EXTENSIONS` + variables may be set to initialize the target properties. + +* New :prop_tgt:`COMPILE_FEATURES` target property may contain a list + of features required to compile a target. CMake uses this + information to ensure that the compiler in use is capable of building + the target, and to add any necessary compile flags to support language + features. + +* New :prop_tgt:`COMPILE_PDB_NAME` and + :prop_tgt:`COMPILE_PDB_OUTPUT_DIRECTORY` target properties + were introduced to specify the MSVC compiler program database + file location (``cl /Fd``). This complements the existing + :prop_tgt:`PDB_NAME` and :prop_tgt:`PDB_OUTPUT_DIRECTORY` + target properties that specify the linker program database + file location (``link /pdb``). + +* The :prop_tgt:`INTERFACE_LINK_LIBRARIES` target property now supports + a ``$<LINK_ONLY:...>`` + :manual:`generator expression <cmake-generator-expressions(7)>`. + +* A new :prop_tgt:`INTERFACE_SOURCES` target property was introduced. This is + consumed by dependent targets, which compile and link the listed sources. + +* The :prop_tgt:`SOURCES` target property now contains + :manual:`generator expression <cmake-generator-expressions(7)>` + such as ``TARGET_OBJECTS`` when read at configure time, if + policy :policy:`CMP0051` is ``NEW``. + +* The :prop_tgt:`SOURCES` target property now generally supports + :manual:`generator expression <cmake-generator-expressions(7)>`. The + generator expressions may be used in the :command:`add_library` and + :command:`add_executable` commands. + +* It is now possible to write and append to the :prop_tgt:`SOURCES` target + property. The :variable:`CMAKE_DEBUG_TARGET_PROPERTIES` variable may be + used to trace the origin of sources. + +* A :prop_sf:`VS_DEPLOYMENT_CONTENT` source file property was added + to tell the Visual Studio generators to mark content for deployment + in Windows Phone and Windows Store projects. + +* A :prop_sf:`VS_DEPLOYMENT_LOCATION` source file property was added + to tell the Visual Studio generators the relative location of content + marked for deployment in Windows Phone and Windows Store projects. + +* The :prop_tgt:`VS_WINRT_COMPONENT` target property was created to + tell Visual Studio generators to compile a shared library as a + Windows Runtime (WinRT) component. + +* The :generator:`Xcode` generator learned to check source + file properties :prop_sf:`XCODE_EXPLICIT_FILE_TYPE` and + :prop_sf:`XCODE_LAST_KNOWN_FILE_TYPE` for a custom Xcode + file reference type. + +Modules +------- + +* The :module:`BundleUtilities` module learned to resolve and replace + ``@rpath`` placeholders on OS X to correctly bundle applications + using them. + +* The :module:`CMakePackageConfigHelpers` module + :command:`configure_package_config_file` command learned a new + ``INSTALL_PREFIX`` option to generate package configuration files + meant for a prefix other than :variable:`CMAKE_INSTALL_PREFIX`. + +* The :module:`CheckFortranSourceCompiles` module was added to + provide a ``CHECK_Fortran_SOURCE_COMPILES`` macro. + +* The :module:`ExternalData` module learned to tolerate a ``DATA{}`` + reference to a missing source file with a warning instead of + rejecting it with an error. This helps developers write new + ``DATA{}`` references to test reference outputs that have not + yet been created. + +* The :module:`ExternalProject` module learned to support lzma-compressed + source tarballs with ``.7z``, ``.tar.xz``, and ``.txz`` extensions. + +* The :module:`ExternalProject` module ``ExternalProject_Add`` command + learned a new ``BUILD_ALWAYS`` option to cause the external project + build step to run every time the host project is built. + +* The :module:`ExternalProject` module ``ExternalProject_Add`` command + learned a new ``EXCLUDE_FROM_ALL`` option to cause the external + project target to have the :prop_tgt:`EXCLUDE_FROM_ALL` target + property set. + +* The :module:`ExternalProject` module ``ExternalProject_Add_Step`` command + learned a new ``EXCLUDE_FROM_MAIN`` option to cause the step to not be + a direct dependency of the main external project target. + +* The :module:`ExternalProject` module ``ExternalProject_Add`` command + learned a new ``DOWNLOAD_NO_PROGRESS`` option to disable progress + output while downloading the source tarball. + +* The :module:`FeatureSummary` module ``feature_summary`` API + learned to accept multiple values for the ``WHAT`` option and + combine them appropriately. + +* The :module:`FindCUDA` module learned to support ``fatbin`` and ``cubin`` + modules. + +* The :module:`FindGTest` module ``gtest_add_tests`` macro learned + a new ``AUTO`` option to automatically read the :prop_tgt:`SOURCES` + target property of the test executable and scan the source files + for tests to be added. + +* The :module:`FindGLEW` module now provides imported targets. + +* The :module:`FindGLUT` module now provides imported targets. + +* The :module:`FindHg` module gained a new ``Hg_WC_INFO`` macro to + help run ``hg`` to extract information about a Mercurial work copy. + +* The :module:`FindOpenCL` module was introduced. + +* The :module:`FindOpenMP` module learned to support Fortran. + +* The :module:`FindPkgConfig` module learned to use the ``PKG_CONFIG`` + environment variable value as the ``pkg-config`` executable, if set. + +* The :module:`FindXercesC` module was introduced. + +* The :module:`FindZLIB` module now provides imported targets. + +* The :module:`GenerateExportHeader` module ``generate_export_header`` + function learned to allow use with :ref:`Object Libraries`. + +* The :module:`InstallRequiredSystemLibraries` module gained a new + ``CMAKE_INSTALL_OPENMP_LIBRARIES`` option to install MSVC OpenMP + runtime libraries. + +* The :module:`UseSWIG` module learned to detect the module name + from ``.i`` source files if possible to avoid the need to set + the ``SWIG_MODULE_NAME`` source file property explicitly. + +* The :module:`WriteCompilerDetectionHeader` module was added to allow + creation of a portable header file for compiler optional feature detection. + +Generator Expressions +--------------------- + +* New ``COMPILE_FEATURES`` + :manual:`generator expression <cmake-generator-expressions(7)>` allows + setting build properties based on available compiler features. + +CTest +----- + +* The :command:`ctest_coverage` command learned to read variable + ``CTEST_COVERAGE_EXTRA_FLAGS`` to set ``CoverageExtraFlags``. + +* The :command:`ctest_coverage` command learned to support + Intel coverage files with the ``codecov`` tool. + +* The :command:`ctest_memcheck` command learned to support sanitizer + modes, including ``AddressSanitizer``, ``MemorySanitizer``, + ``ThreadSanitizer``, and ``UndefinedBehaviorSanitizer``. + Options may be set using the new + :variable:`CTEST_MEMORYCHECK_SANITIZER_OPTIONS` variable. + +CPack +----- + +* :manual:`cpack(1)` gained an ``IFW`` generator to package using + Qt Framework Installer tools. See the :cpack_gen:`CPack IFW Generator`. + +* :manual:`cpack(1)` gained ``7Z`` and ``TXZ`` generators supporting + lzma-compressed archives. + +* The :cpack_gen:`CPack DEB Generator` learned a new + :variable:`CPACK_DEBIAN_COMPRESSION_TYPE` variable to set the + tarball compression type. + +* The :cpack_gen:`CPack WIX Generator` learned to support + a :prop_inst:`CPACK_WIX_ACL` installed file property to + specify an Access Control List. + +Other +----- + +* The :manual:`cmake(1)` ``-E`` option learned a new ``env`` command. + +* The :manual:`cmake(1)` ``-E tar`` command learned to support + lzma-compressed files. + +* :ref:`Object Libraries` may now have extra sources that do not + compile to object files so long as they would not affect linking + of a normal library (e.g. ``.dat`` is okay but not ``.def``). + +* Visual Studio generators for VS 8 and later learned to support + the ``ASM_MASM`` language. + +* The Visual Studio generators learned to treat ``.hlsl`` source + files as High Level Shading Language sources (using ``FXCompile`` + in ``.vcxproj`` files). Source file properties + :prop_sf:`VS_SHADER_TYPE`, :prop_sf:`VS_SHADER_MODEL`, and + :prop_sf:`VS_SHADER_ENTRYPOINT` were added added to specify the + shader type, model, and entry point name. + +New Diagnostics +=============== + +* Policy :policy:`CMP0052` introduced to control directories in the + :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of exported targets. + +Deprecated and Removed Features +=============================== + +* In CMake 3.0 the :command:`target_link_libraries` command + accidentally began allowing unquoted arguments to use + :manual:`generator expressions <cmake-generator-expressions(7)>` + containing a (``;`` separated) list within them. For example:: + + set(libs B C) + target_link_libraries(A PUBLIC $<BUILD_INTERFACE:${libs}>) + + This is equivalent to writing:: + + target_link_libraries(A PUBLIC $<BUILD_INTERFACE:B C>) + + and was never intended to work. It did not work in CMake 2.8.12. + Such generator expressions should be in quoted arguments:: + + set(libs B C) + target_link_libraries(A PUBLIC "$<BUILD_INTERFACE:${libs}>") + + CMake 3.1 again requires the quotes for this to work correctly. + +* Prior to CMake 3.1 the Makefile generators did not escape ``#`` + correctly inside make variable assignments used in generated + makefiles, causing them to be treated as comments. This made + code like:: + + add_compile_options(-Wno-#pragma-messages) + + not work in Makefile generators, but work in other generators. + Now it is escaped correctly, making the behavior consistent + across generators. However, some projects may have tried to + workaround the original bug with code like:: + + set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -Wno-\\#pragma-messages") + + This added the needed escape for Makefile generators but also + caused other generators to pass ``-Wno-\#pragma-messages`` to + the shell, which would work only in POSIX shells. + Unfortunately the escaping fix could not be made in a compatible + way so this platform- and generator-specific workaround no + longer works. Project code may test the :variable:`CMAKE_VERSION` + variable value to make the workaround version-specific too. + +* Callbacks established by the :command:`variable_watch` command will no + longer receive the ``ALLOWED_UNKNOWN_READ_ACCESS`` access type when + the undocumented ``CMAKE_ALLOW_UNKNOWN_VARIABLE_READ_ACCESS`` variable is + set. Uninitialized variable accesses will always be reported as + ``UNKNOWN_READ_ACCESS``. + +* The :module:`CMakeDetermineVSServicePack` module now warns that + it is deprecated and should not longer be used. Use the + :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable instead. + +* The :module:`FindITK` module has been removed altogether. + It was a thin-wrapper around ``find_package(ITK ... NO_MODULE)``. + This produces much clearer error messages when ITK is not found. + +* The :module:`FindVTK` module has been removed altogether. + It was a thin-wrapper around ``find_package(VTK ... NO_MODULE)``. + This produces much clearer error messages when VTK is not found. + + The module also provided compatibility support for finding VTK 4.0. + This capability has been dropped. + +Other Changes +============= + +* The :manual:`cmake-gui(1)` learned to capture output from child + processes started by the :command:`execute_process` command + and display it in the output window. + +* The :manual:`cmake-language(7)` internal implementation of generator + expression and list expansion parsers have been optimized and shows + non-trivial speedup on large projects. + +* The Makefile generators learned to use response files with GNU tools + on Windows to pass library directories and names to the linker. + +* When generating linker command-lines, CMake now avoids repeating + items corresponding to SHARED library targets. + +* Support for the Open Watcom compiler has been overhauled. + The :variable:`CMAKE_<LANG>_COMPILER_ID` is now ``OpenWatcom``, + and the :variable:`CMAKE_<LANG>_COMPILER_VERSION` now uses + the Open Watcom external version numbering. The external + version numbers are lower than the internal version number + by 11. + +* The ``cmake-mode.el`` major Emacs editing mode no longer + treats ``_`` as part of words, making it more consistent + with other major modes. diff --git a/Help/release/3.10.rst b/Help/release/3.10.rst new file mode 100644 index 0000000..117415b --- /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 0000000..a80657d --- /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 0000000..481027e --- /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 0000000..a8dd0ba --- /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 0000000..8a9738c --- /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 0000000..e68e7d3 --- /dev/null +++ b/Help/release/3.15.rst @@ -0,0 +1,396 @@ +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 +============= + +* If a feature specified by :command:`target_compile_features` is available + in the compiler's default standard level, CMake 3.14 and below incorrectly + added unnecessary ``-std=`` flags that could lower the standard level. + This bug has been fixed in CMake 3.15. This behavior change may expose + bugs in existing projects that were relying on undocumented implementation + details. Specifying compile features only ensures that the compiler runs + in a mode that has those features, not that any specific standard level is + used or explicit ``-std=`` flag passed. + +* 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 0000000..84d96cd --- /dev/null +++ b/Help/release/3.16.rst @@ -0,0 +1,324 @@ +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`, the new :variable:`CMAKE_AUTOMOC_PATH_PREFIX` + variable or :prop_tgt:`AUTOMOC_PATH_PREFIX` target property may be enabled + to generate 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. + +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. + +Updates +======= + +Changes made since CMake 3.16.0 include the following. + +3.16.2 +------ + +* CMake 3.16.0 and 3.16.1 processed ``.hh`` files with :prop_tgt:`AUTOMOC`. + This was a behavior change from CMake 3.15 and below that can break + existing projects, so it has been reverted as of 3.16.2. + +3.16.5 +------ + +* The :module:`FindPython`, :module:`FindPython2`, and :module:`FindPython3` + modules no longer create cache entries for ``Python{,2,3}_LIBRARY_RELEASE`` + and ``Python{,2,3}_LIBRARY_DEBUG``. Those values are always computed from + other results and so should not be cached. The entries were created by + CMake 3.16.0 through 3.16.4 but were always ``FORCE``-set and could not + be meaningfully edited by users. + + Additionally, the modules no longer expose their internal ``_Python*`` + cache entries publicly. CMake 3.16.0 through 3.16.4 accidentally + made them visible as advanced cache entries. + +3.16.7 +------ + +* Selection of the Objective C or C++ compiler now considers the + :envvar:`CC` or :envvar:`CXX` environment variable if the + :envvar:`OBJC` or :envvar:`OBJCXX` environment variable is not set. + +* The :module:`FindPkgConfig` module now extracts include directories + prefixed with ``-isystem`` into the ``*_INCLUDE_DIRS`` variables and + :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target properties. + Previously they would be places in ``*_CFLAGS_OTHER`` variables and + :prop_tgt:`INTERFACE_COMPILE_OPTIONS` target properties. + +3.16.9 +------ + +* The default value of :variable:`CMAKE_AUTOMOC_PATH_PREFIX` was changed to + ``OFF`` because this feature can break existing projects that have + identically named header files in different include directories. + This restores compatibility with behavior of CMake 3.15 and below. diff --git a/Help/release/3.17.rst b/Help/release/3.17.rst new file mode 100644 index 0000000..abd7463 --- /dev/null +++ b/Help/release/3.17.rst @@ -0,0 +1,357 @@ +CMake 3.17 Release Notes +************************ + +.. only:: html + + .. contents:: + +Changes made since CMake 3.16 include the following. + +New Features +============ + +Generators +---------- + +* :manual:`cmake(1)` gained a :generator:`Ninja Multi-Config` generator, + which is similar to the :generator:`Ninja` generator but can be used to build + multiple configurations at once. + +* :ref:`Visual Studio Generators` learned to support per-config sources. + Previously only :ref:`Command-Line Build Tool Generators` supported them. + +* :ref:`Visual Studio Generators` for VS 2010 and above now support + specifying the ``VCTargetsPath`` value for project files in + :variable:`CMAKE_GENERATOR_TOOLSET` setting. + +* :ref:`Visual Studio Generators` for VS 2010 and above learned to + support .NET Standard and .NET Core. See the + :prop_tgt:`DOTNET_TARGET_FRAMEWORK` target property and + associated :variable:`CMAKE_DOTNET_TARGET_FRAMEWORK` variable. + +Languages +--------- + +* The :manual:`Compile Features <cmake-compile-features(7)>` functionality + now offers meta-features for the CUDA language standard levels + (e.g. ``cuda_std_03``, ``cuda_std_14``). See + :prop_gbl:`CMAKE_CUDA_KNOWN_FEATURES`. + +Compilers +--------- + +* The IBM XL Fortran compiler is now supported by the :generator:`Ninja` + generator. + +Command-Line +------------ + +* :manual:`cmake(1)` gained a ``--debug-find`` command-line option to + enable additional human-readable output on where ``find_*`` commands search. + +* :manual:`cmake(1)` gained a ``--trace-format`` command-line option that + can be used to set the ``--trace`` output format. Currently, the old + human readable and the new JSON format are supported. The new JSON format + is easier to parse automatically than the existing format. + +* :manual:`cmake(1)` gained a ``-E rm`` command-line tool that can be + used to remove directories and files. This supersedes the existing + ``-E remove`` and ``-E remove_directory`` tools and has better semantics. + +Commands +-------- + +* The :command:`add_custom_command` command learned to interpret paths in + ``DEPENDS`` arguments that are specified relative to the current + binary directory. + +* The :command:`foreach` command learned a new ``ZIP_LISTS`` option to iterate + over multiple lists simultaneously. + +* The :command:`load_cache(READ_WITH_PREFIX)` command mode is now allowed + when using ``cmake -P`` to :ref:`Run a Script <Script Processing Mode>`. + +* The :command:`message` command learned to output context provided in + the :variable:`CMAKE_MESSAGE_CONTEXT` variable for log levels + ``NOTICE`` and below. Enable this output with the new ``--log-context`` + command-line option or :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` variable. + +* The :command:`message` command gained new keywords ``CHECK_START``, + ``CHECK_PASS`` and ``CHECK_FAIL``. + +* The :command:`target_compile_options` command now honors the ``BEFORE`` + keyword more consistently. See policy :policy:`CMP0101`. + +Variables +--------- + +* A :variable:`CMAKE_CTEST_ARGUMENTS` variable was added to specify a list + of command-line arguments passed to CTest when running through the + ``test`` (or ``RUN_TESTS``) target of the generated build system. + +* The following variables are now defined inside a :command:`function`: + + - :variable:`CMAKE_CURRENT_FUNCTION` + - :variable:`CMAKE_CURRENT_FUNCTION_LIST_DIR` + - :variable:`CMAKE_CURRENT_FUNCTION_LIST_FILE` + - :variable:`CMAKE_CURRENT_FUNCTION_LIST_LINE` + +* The :variable:`CMAKE_CUDA_RUNTIME_LIBRARY` variable and + :prop_tgt:`CUDA_RUNTIME_LIBRARY` target property were introduced to + select the CUDA runtime library used when linking targets that + use CUDA. + +* The :variable:`CMAKE_FIND_DEBUG_MODE` variable was introduced to + print extra ``find_*`` call information during the cmake run to standard + error. Output is designed for human consumption and not for parsing. + +* The :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` variable now takes its + initial value from the :envvar:`CMAKE_EXPORT_COMPILE_COMMANDS` environment + variable if no explicit configuration is given. + +* The :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER` variable, if not set + explicitly, now takes its initial value from the + :envvar:`CMAKE_<LANG>_COMPILER_LAUNCHER` environment variable. + +* The :variable:`CMAKE_MESSAGE_LOG_LEVEL` variable can now be used + to persist a log level between CMake runs, unlike the ``--log-level`` + command line option which only applies to that particular run. + +* The :variable:`CMAKE_XCODE_SCHEME_ENVIRONMENT` variable was added + to initialize the :prop_tgt:`XCODE_SCHEME_ENVIRONMENT` target property. + +* The :variable:`CMAKE_XCODE_SCHEME_WORKING_DIRECTORY` variable and + associated :prop_tgt:`XCODE_SCHEME_WORKING_DIRECTORY` target property + were added to tell the :generator:`Xcode` generator to set the value of + the ``Custom Working Directory`` schema option. + +Properties +---------- + +* The :prop_tgt:`AIX_EXPORT_ALL_SYMBOLS` target property and associated + :variable:`CMAKE_AIX_EXPORT_ALL_SYMBOLS` variable were created to + optionally explicitly disable automatic export of symbols from shared + libraries on AIX. + +* The :prop_tgt:`DEPRECATION` target property was added to mark + a target as deprecated. If a linked target is marked as + deprecated, a warning with the deprecation message is issued + at generate time. + +* The :prop_tgt:`INSTALL_NAME_DIR` target property now supports + :manual:`generator expressions <cmake-generator-expressions(7)>`. + In particular, the ``$<INSTALL_PREFIX>`` generator expression can + be used to set the directory relative to the install-time prefix. + +* Target properties :prop_tgt:`MACHO_COMPATIBILITY_VERSION` and + :prop_tgt:`MACHO_CURRENT_VERSION` were added to set the + ``compatibility_version`` and ``curent_version``, respectively, + for Mach-O binaries. For backwards compatibility, if these properties + are not set, :prop_tgt:`SOVERSION` and :prop_tgt:`VERSION` + are used respectively as fallbacks. + +* The :prop_tgt:`VS_DOTNET_DOCUMENTATION_FILE` target property was added + to tell :ref:`Visual Studio Generators` to generate a ``DocumentationFile`` + reference in ``.csproj`` files. + +Modules +------- + +* The :module:`ExternalProject` module :command:`ExternalProject_Add` + command gained a ``GIT_SUBMODULES_RECURSE`` option to specify whether + Git submodules should be updated recursively. The default is on to + preserve existing behavior. + +* The :module:`FindCUDAToolkit` module was added to find the + CUDA Toolkit without enabling CUDA as a language. + +* The :module:`FindCURL` module learned to find CURL using + the ``CURLConfig.cmake`` package configuration file generated by + CURL's cmake buildsystem. It also gained a new ``CURL_NO_CURL_CMAKE`` + option to disable this behavior. + +* The :module:`FindFLEX` module's ``FLEX_TARGET`` command now runs ``flex`` + with :variable:`CMAKE_CURRENT_BINARY_DIR` as the working directory. + See policy :policy:`CMP0098`. + +* The :module:`FindLibArchive` module now provides an imported target + for libarchive. + +* The :module:`FindPython` module has learned to find Python components + in active virtual environments managed by ``conda``. + +* The :module:`FindPython3` and :module:`FindPython` modules gained, + respectively, variable ``Python3_SOABI`` and ``Python_SOABI`` giving + the standard extension suffix for modules. Moreover, commands + ``Python3_add_library()`` and ``Python_add_library()`` gained the option + ``WITH_SOABI`` to prefix the library suffix with the value of ``SOABI``. + +* The :module:`FindLibXml2` module now provides an imported target for the + ``xmllint`` executable. + +Autogen +------- + +* :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` learned to process headers + with a ``.hh`` extension. See policy :policy:`CMP0100`. + +CTest +----- + +* The :variable:`CTEST_CONFIGURATION_TYPE` variable is now set from the + command line when :manual:`ctest(1)` is invoked with ``-C <cfg>``. + +* The :manual:`ctest(1)` tool gained support for Dr. Memory to run + memcheck runs. + +* The :manual:`ctest(1)` tool gained a ``--no-tests=<[error|ignore]>`` option + to explicitly set and unify the behavior between direct invocation and + script mode if no tests were found. + +* The :manual:`ctest(1)` tool gained a ``--repeat <mode>:<n>`` option + to specify conditions in which to repeat tests. This generalizes + the existing ``--repeat-until-fail <n>`` option to add modes for + ``until-pass`` and ``after-timeout``. + +* The :command:`ctest_test` command gained a ``REPEAT <mode>:<n>`` option + to specify conditions in which to repeat tests. + +CPack +----- + +* The :cpack_gen:`CPack DragNDrop Generator` learned to use + the :variable:`CPACK_DMG_<component>_FILE_NAME` variable + to set a custom filename when packaging components into + their own DMGs. + +* The :cpack_gen:`CPack DragNDrop Generator` learned to handle + RTF formatted license files. When :variable:`CPACK_DMG_SLA_DIR` + variable is set, ``<language>.license.rtf`` is considered, but + only as a fallback when the plaintext (``.txt``) file is not found + in order to maintain backwards compatibility. + +* The :cpack_gen:`CPack NSIS Generator` gained a new variable + :variable:`CPACK_NSIS_MUI_HEADERIMAGE` to set the header image. + To not break existing setups, it still defaults to + :variable:`CPACK_PACKAGE_ICON` if the new variable is not set. + +* The :cpack_gen:`CPack NSIS Generator` now supports + :variable:`CPACK_NSIS_UNINSTALL_NAME`. + This can be used to specify the name of the Uninstall program. + +* The :cpack_gen:`CPack NSIS Generator` now supports + :variable:`CPACK_NSIS_WELCOME_TITLE` and + :variable:`CPACK_NSIS_WELCOME_TITLE_3LINES`. + These can be used to specify the welcome page title and display it in 3 lines. + +* The :cpack_gen:`CPack NSIS Generator` now supports + :variable:`CPACK_NSIS_FINISH_TITLE` and + :variable:`CPACK_NSIS_FINISH_TITLE_3LINES`. + These can be used to specify the finish page title and display it in 3 lines. + +* The :cpack_gen:`CPack productbuild Generator` gained support for a + :variable:`CPACK_PRODUCTBUILD_BACKGROUND` variable to specify a background + image for the macOS installer. + +Other +----- + +* :manual:`ccmake(1)` now displays cache values using colors + based on the entry type if the terminal supports color. + +* :manual:`ccmake(1)` now displays messages and a progress bar during + configure and generate. It will keep the output displayed if any + errors or warnings occurred. + +Deprecated and Removed Features +=============================== + +* An explicit deprecation diagnostic was added for policy ``CMP0068`` + and policy ``CMP0069`` (``CMP0067`` 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 :cpack_gen:`CPack PackageMaker Generator` generator has been + deprecated because Xcode no longer distributes the PackageMaker tools. + The undocumented ``OSXX11`` generator has also been deprecated. + +* The :manual:`cmake(1)` command-line ``-E remove`` and ``-E remove_directory`` + tools are deprecated in favor of the new ``-E rm`` tool. The older tools + always returned 0 if a named path did not exist even without the force + option and cannot be fixed without breaking compatibility, and so have + been superseded. + +* The :cpack_gen:`CPack NSIS Generator` now requires NSIS 3.0 or later. + +Other Changes +============= + +* The :manual:`file API <cmake-file-api(7)>` index file now emits a + ``multiConfig`` flag specifying whether or not the generator supports + multiple output configurations. + +* Target link properties :prop_tgt:`INTERFACE_LINK_OPTIONS`, + :prop_tgt:`INTERFACE_LINK_DIRECTORIES` and + :prop_tgt:`INTERFACE_LINK_DEPENDS` are now transitive over private + dependencies on static libraries. + See policy :policy:`CMP0099`. + +* When using MinGW tools, the :command:`find_library` command no longer + finds ``.dll`` files by default. Instead, it expects ``.dll.a`` import + libraries to be available. + +* The :generator:`MinGW Makefiles` generator no longer issues an error if + ``sh.exe`` is present in the environment's ``PATH``. + +* The :generator:`Ninja` generator now prefers the first ninja build + tool to appear in the ``PATH`` no matter whether it is called + ``ninja-build``, ``ninja``, or ``samu``. Previously the first + of those names to appear anywhere in the ``PATH`` would be preferred. + +* With SDCC the ``sdar`` tool is now preferred over ``sdcclib`` as librarian. + The latter was deprecated by SDCC 3.2.0 and removed in SDCC 3.8.6. + +* With SDCC the default flags no longer include any target-specific flags. + Previously the default flags were hard-coded for 8051. + +* The :variable:`CMAKE_VS_GLOBALS` variable value now applies during + compiler identification and in targets created by the + :command:`add_custom_target` command. + +* The :generator:`Xcode` generator no longer hard-codes ``-Wmost``, + ``-Wno-four-char-constants``, and ``-Wno-unknown-pragmas`` warning flags. + +Updates +======= + +Changes made since CMake 3.17.0 include the following. + +3.17.1 +------ + +* CMake 3.17.0 updated the :cpack_gen:`CPack NSIS Generator` with changes + that require NSIS 3.0 or later. CMake 3.17.1 now enforces the use + of a sufficiently new version. + +3.17.3 +------ + +* Selection of the Objective C or C++ compiler now considers the + :envvar:`CC` or :envvar:`CXX` environment variable if the + :envvar:`OBJC` or :envvar:`OBJCXX` environment variable is not set. + +* The :module:`FindPkgConfig` module now extracts include directories + prefixed with ``-isystem`` into the ``*_INCLUDE_DIRS`` variables and + :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target properties. + Previously they would be places in ``*_CFLAGS_OTHER`` variables and + :prop_tgt:`INTERFACE_COMPILE_OPTIONS` target properties. + +3.17.5 +------ + +* The default value of :variable:`CMAKE_AUTOMOC_PATH_PREFIX` was changed to + ``OFF`` because this feature can break existing projects that have + identically named header files in different include directories. + This restores compatibility with behavior of CMake 3.15 and below. + The default was also changed to ``OFF`` in 3.16.9. diff --git a/Help/release/3.18.rst b/Help/release/3.18.rst new file mode 100644 index 0000000..f97e4df --- /dev/null +++ b/Help/release/3.18.rst @@ -0,0 +1,364 @@ +CMake 3.18 Release Notes +************************ + +.. only:: html + + .. contents:: + +Changes made since CMake 3.17 include the following. + +New Features +============ + +Languages +--------- + +* The ``CUDA`` language can now be compiled using Clang on non-Windows + platforms. Separable compilation is not yet supported on any platform. + +Command-Line +------------ + +* :manual:`cmake(1)` gained support for profiling of CMake scripts through + the parameters ``--profiling-output`` and ``--profiling-format``. + +* :manual:`cmake(1)` gained a ``cat`` command line + option that can be used to concatenate files and print them + on standard output. + +Commands +-------- + +* The :command:`add_library` and :command:`add_executable` commands + learned to create :ref:`Alias Targets` referencing non-``GLOBAL`` + :ref:`Imported Targets`. + +* The :command:`cmake_language()` command was added for meta-operations on + scripted or built-in commands, starting with a mode to ``CALL`` other + commands, and ``EVAL CODE`` to inplace evaluate a CMake script. + +* The :command:`execute_process` command gained the ``ECHO_OUTPUT_VARIABLE`` + and ``ECHO_ERROR_VARIABLE`` options. + +* The :command:`export` command now raise an error if used multiple times with + same ``FILE`` without ``APPEND``. See policy :policy:`CMP0103`. + +* The :command:`file` command gained the ``ARCHIVE_CREATE`` and + ``ARCHIVE_EXTRACT`` subcommands to expose the :manual:`cmake(1)` ``-E tar`` + functionality to CMake scripting code. + +* The :command:`file(CONFIGURE)` subcommand was created in order to replicate + the :command:`configure_file` functionality without resorting to a + pre-existing file on disk as input. The content is instead passed as a + string. + +* The :command:`file(UPLOAD)` command gained ``TLS_VERIFY`` and ``TLS_CAINFO`` + options to control server certificate verification. + +* The :command:`find_program`, :command:`find_library`, :command:`find_path` + and :command:`find_file` commands gained a new ``REQUIRED`` option that will + stop processing with an error message if nothing is found. + +* The :command:`get_property` command with ``SOURCE`` scope gained the + ``DIRECTORY`` and ``TARGET_DIRECTORY`` options to get a property + from the provided directory scope. + +* The :command:`get_source_file_property` command gained the ``DIRECTORY`` + and ``TARGET_DIRECTORY`` options to get a property from the + provided directory scope. + +* The :command:`list` operation ``SORT`` gained the ``NATURAL`` sort + option to sort using natural order (see ``strverscmp(3)`` manual). + +* The :command:`set_property` command with the ``SOURCE`` scope gained the + ``DIRECTORY`` and ``TARGET_DIRECTORY`` options to set properties + in the provided directory scopes. + +* The :command:`set_source_files_properties` command gained the ``DIRECTORY`` + and ``TARGET_DIRECTORY`` options to set properties in the provided + directory scopes. + +* The :command:`string` command learned a new ``HEX`` sub-command, which + converts strings into their hexadecimal representation. + +Variables +--------- + +* A :variable:`CMAKE_CUDA_ARCHITECTURES` variable was added to specify + CUDA output architectures. Users are encouraged to use this instead of + specifying options manually, as this approach is compiler-agnostic. + The variable is initialized automatically when + :variable:`CMAKE_CUDA_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` is ``NVIDIA``. + The variable is used to initialize the new :prop_tgt:`CUDA_ARCHITECTURES` + target property. See policy :policy:`CMP0104`. + +* The :variable:`CMAKE_PCH_WARN_INVALID` variable was added to initialize the + :prop_tgt:`PCH_WARN_INVALID` target property to allow the removal of the + precompiled header invalid warning. + +Properties +---------- + +* The :prop_tgt:`CUDA_ARCHITECTURES` target property was added to specify + CUDA output architectures. Users are encouraged to use this instead of + specifying options manually, as this approach is compiler-agnostic. + The property is initialized by the new :variable:`CMAKE_CUDA_ARCHITECTURES` + variable. See policy :policy:`CMP0104`. + +* The :prop_tgt:`Fortran_PREPROCESS` target property and + :prop_sf:`Fortran_PREPROCESS` source-file property were added to + control preprocessing of Fortran source files. + +* The :prop_tgt:`FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>` target property + and associated :variable:`CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>` + variable were created to allow adding a postfix to the name of a + framework file name when using a multi-config generator. + +* The :prop_sf:`OBJECT_OUTPUTS` source file property now supports + :manual:`generator expressions <cmake-generator-expressions(7)>`. + +* The :prop_tgt:`PCH_WARN_INVALID` target property was added to allow the + removal of the precompiled header invalid warning. + +* The :prop_tgt:`UNITY_BUILD_MODE` target property was added to tell + generators which algorithm to use for grouping included source + files. + +* The :prop_tgt:`VS_SOURCE_SETTINGS_<tool>` target property was added + to tell :ref:`Visual Studio Generators` for VS 2010 and above to add + metadata to non-built source files using ``<tool>``. + +* The :prop_sf:`VS_SETTINGS` source file property was added to tell + :ref:`Visual Studio Generators` for VS 2010 and above to add + metadata to a non-built source file. + +* The :prop_tgt:`VS_PLATFORM_TOOLSET` target property was added to tell + :ref:`Visual Studio Generators` for VS 2010 and above to override + the platform toolset. + +* The :prop_tgt:`VS_SOLUTION_DEPLOY` target property was added to tell + :ref:`Visual Studio Generators` for VS 2010 and above to mark a + target for deployment even when not building for Windows Phone/Store/CE. + +Modules +------- + +* The :module:`CheckLinkerFlag` module has been added to provide a + facility to check validity of link flags. + +* The :module:`ExternalProject` module :command:`ExternalProject_Add` command + gained a new ``GIT_REMOTE_UPDATE_STRATEGY`` keyword. This can be used to + specify how failed rebase operations during a git update should be handled. + The ``CMAKE_EP_GIT_REMOTE_UPDATE_STRATEGY`` variable was also added as a + global default and is honored by both the :module:`ExternalProject` and + :module:`FetchContent` modules. + +* The :module:`FetchContent` module :command:`FetchContent_Declare` command + now supports a ``SOURCE_SUBDIR`` option. It can be used to direct + :command:`FetchContent_MakeAvailable` to look in a different location + for the ``CMakeLists.txt`` file. + +* The :module:`FindBLAS` module now provides an imported target. + +* The :module:`FindCUDAToolkit` module: + + * gained the variable + ``CUDAToolkit_LIBRARY_ROOT``, which is the directory containing the + ``nvvm`` directory and ``version.txt``. + + * uses toolkit and library root found during ``CUDA`` compiler detection. + +* The :module:`FindLAPACK` module now provides an imported target. + +* The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython` + modules: + + * gained the possibility to create per-artifact cache variables for + interactive editing in :manual:`cmake-gui(1)` and :manual:`ccmake(1)`. + + * gained sub-components ``Development.Module`` and + ``Development.Embed`` under the ``Development`` component. + + * gained the capability to specify which Python implementations to find, + including ``IronPython`` and ``PyPy``. + +* The :module:`FindRuby` module input and output variables were all renamed + from ``RUBY_`` to ``Ruby_`` for consistency with other find modules. + Input variables of the old case will be honored if provided, and output + variables of the old case are always provided. + +* The :module:`FindSWIG` module now accepts target languages as ``COMPONENTS`` + and ``OPTIONAL_COMPONENTS`` arguments to ``find_package``. + +* The :module:`GoogleTest` module :command:`gtest_discover_tests` command: + + * gained a new ``DISCOVERY_MODE`` option to control when the test + discovery step is run. It offers a new ``PRE_TEST`` setting to + run the discovery at test time instead of build time. A new + ``CMAKE_GTEST_DISCOVER_TESTS_DISCOVERY_MODE`` variable can be used + to change the default globally. + + * gained a new optional parameter ``XML_OUTPUT_DIR``. When set the + JUnit XML test results are stored in that directory. + +* The :module:`FindLibXslt` module now provides imported targets. + +* The :module:`UseSWIG` module now supports Fortran as a target language if + the ``SWIG_EXECUTABLE`` is SWIG-Fortran_. + +.. _`SWIG-Fortran`: https://github.com/swig-fortran/swig + +Generator Expressions +--------------------- + +* The ``$<DEVICE_LINK:...>`` and ``$<HOST_LINK:...>`` + :manual:`generator expressions <cmake-generator-expressions(7)>` were added + to manage device and host link steps. + +* The ``$<LINK_LANGUAGE:...>`` and ``$<LINK_LANG_AND_ID:...>`` + :manual:`generator expressions <cmake-generator-expressions(7)>` were added. + +CTest +----- + +* :manual:`ctest(1)` gained a new :variable:`CTEST_RESOURCE_SPEC_FILE` + variable, which can be used to specify a + :ref:`resource specification file <ctest-resource-specification-file>`. + +* :manual:`ctest(1)` gained a ``--stop-on-failure`` option, + which can be used to stop running the tests once one has failed. + +* The :command:`ctest_test` command gained a ``STOP_ON_FAILURE`` option + which can be used to stop running the tests once one has failed. + +* The :module:`CTestCoverageCollectGCOV` module + :command:`ctest_coverage_collect_gcov` command gained a + ``TARBALL_COMPRESSION`` option to control compression of the + tarball of collected results. + +CPack +----- + +* The :cpack_gen:`CPack Archive Generator`'s ``TXZ`` format learned the + :variable:`CPACK_ARCHIVE_THREADS` variable to enable parallel compression. + Requires support in the ``liblzma`` used by CMake. + +* The :cpack_gen:`CPack NSIS Generator` gained a new variable + :variable:`CPACK_NSIS_MANIFEST_DPI_AWARE` to declare that the + installer is DPI-aware. + +* The :cpack_gen:`CPack RPM Generator` gained + :variable:`CPACK_RPM_PRE_TRANS_SCRIPT_FILE` and + :variable:`CPACK_RPM_POST_TRANS_SCRIPT_FILE` + variables to specify pre- and post-transaction scripts. + +Other +----- + +* :manual:`cmake-gui(1)` now populates its generator selection + widget default value from the :envvar:`CMAKE_GENERATOR` environment + variable. Additionally, environment variables + :envvar:`CMAKE_GENERATOR_PLATFORM` and :envvar:`CMAKE_GENERATOR_TOOLSET` + are used to populate their respective widget defaults. + +* :manual:`ccmake(1)` learned to read a :envvar:`CCMAKE_COLORS` + environment variable to customize colors. + +* The :manual:`Compile Features <cmake-compile-features(7)>` functionality + is now aware of the availability of C11 features in MSVC 19.27 and 19.28, + including support for the ``c_restrict``, ``c_static_assert`` features and + the ``-std:c11`` flag. + +Deprecated and Removed Features +=============================== + +* The :module:`Documentation` module has been deprecated via + :policy:`CMP0106`. This module was essentially VTK code that CMake should + not be shipping anymore. + +* An explicit deprecation diagnostic was added for policy ``CMP0070`` + and policy ``CMP0071`` (``CMP0069`` 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 +============= + +* On Windows, the :generator:`Ninja` and :generator:`Ninja Multi-Config` + generators, when a compiler is not explicitly specified, now select + the first compiler (of any name) found in directories listed by the + ``PATH`` environment variable. + +* The :prop_tgt:`LINK_OPTIONS` and :prop_tgt:`INTERFACE_LINK_OPTIONS` target + properties are now used for the device link step. + See policy :policy:`CMP0105`. + +* Creation of an ``ALIAS`` target overwriting an existing target now raises an + error. See policy :policy:`CMP0107`. + +* Linking a target to itself through an alias now raises an error. + See policy :policy:`CMP0108`. + +* The :module:`FindPackageHandleStandardArgs` module option ``REQUIRED_VARS`` + is now optional if ``HANDLE_COMPONENTS`` is specified. + +* The :command:`source_group` command now also recognizes forward slashes + as subgroup delimiters, not just backslashes. + +* :manual:`ctest(1)` now logs environment variables that it sets for each test, + either due to the :prop_test:`ENVIRONMENT` property or the + :ref:`resource allocation <ctest-resource-allocation>` feature, and submits + this log to CDash. It does not log environment variables that were set + outside of CTest. + +* When building CMake itself from source and not using a system-provided + libcurl, HTTP/2 support is now enabled for commands supporting + network communication via ``http(s)``, such as :command:`file(DOWNLOAD)`, + :command:`file(UPLOAD)`, and :command:`ctest_submit`. + The precompiled binaries provided on ``cmake.org`` now support HTTP/2. + +* The :manual:`cmake-file-api(7)` "codemodel" version 2 ``version`` field has + been updated to 2.1. + +* The :manual:`cmake-file-api(7)` "codemodel" version 2 "target" object gained + a new ``precompileHeaders`` field in the ``compileGroups`` objects. + +Updates +======= + +Changes made since CMake 3.18.0 include the following. + +3.18.1 +------ + +* The :generator:`Xcode` generator, when :variable:`CMAKE_OSX_ARCHITECTURES` + is not defined, now selects ``$(NATIVE_ARCH_ACTUAL)`` as the default + architecture (the Xcode ``ARCHS`` setting). This is needed for Xcode 12 + to select the host's architecture, which older versions of Xcode did + by default. + +* In CMake 3.18.0 the :command:`add_test` command learned to support + special characters in test names. This was accidentally left out of + its release notes. Unfortunately the fix breaks existing projects + that were using manual quoting or escaping to work around the prior + limitation. This fix has been reverted in 3.18.1, but may be + re-introduced in future versions of CMake with a policy for compatibility. + +3.18.2 +------ + +* The default value of :variable:`CMAKE_AUTOMOC_PATH_PREFIX` was changed to + ``OFF`` because this feature can break existing projects that have + identically named header files in different include directories. + This restores compatibility with behavior of CMake 3.15 and below. + The default was also changed to ``OFF`` in 3.16.9 and 3.17.5. + +* The :manual:`Compile Features <cmake-compile-features(7)>` functionality + was updated for MSVC 19.27 as mentioned above (``c_restrict``). + +3.18.3 +------ + +* The :manual:`Compile Features <cmake-compile-features(7)>` functionality + was updated for MSVC 19.28 as mentioned above (``c_static_assert``). diff --git a/Help/release/3.19.rst b/Help/release/3.19.rst new file mode 100644 index 0000000..49c6793 --- /dev/null +++ b/Help/release/3.19.rst @@ -0,0 +1,442 @@ +CMake 3.19 Release Notes +************************ + +.. only:: html + + .. contents:: + +Changes made since CMake 3.18 include the following. + +New Features +============ + +Presets +------- + +* :manual:`cmake(1)` and :manual:`cmake-gui(1)` now recognize + ``CMakePresets.json`` and ``CMakeUserPresets.json`` files (see + :manual:`cmake-presets(7)`). + +Generators +---------- + +* The :generator:`Xcode` generator now uses the Xcode "new build system" + when generating for Xcode 12.0 or higher. + See the :variable:`CMAKE_XCODE_BUILD_SYSTEM` variable. + One may use ``-T buildsystem=1`` to switch to the legacy build system. + +* The :generator:`Xcode` generator gained support for linking libraries and + frameworks via the *Link Binaries With Libraries* build phase instead of + always by embedding linker flags directly. This behavior is controlled by + a new :prop_tgt:`XCODE_LINK_BUILD_PHASE_MODE` target property, which is + initialized by a new :variable:`CMAKE_XCODE_LINK_BUILD_PHASE_MODE` + variable. + +* The :ref:`Visual Studio Generators` for VS 2015 and above gained support + for the Visual Studio Tools for Android. One may now set + :variable:`CMAKE_SYSTEM_NAME` to ``Android`` to generate ``.vcxproj`` files + for the Android tools. + +Languages +--------- + +* CMake learned to support ``ISPC`` as a first-class language that can be + enabled via the :command:`project` and :command:`enable_language` commands. + ``ISPC`` is currently supported by the :ref:`Makefile Generators` + and the :generator:`Ninja` generator on Linux, macOS, and Windows + using the Intel ISPC compiler. + +* ``CUDA`` language support for Clang now includes: + + - separable compilation (:prop_tgt:`CUDA_SEPARABLE_COMPILATION`), and + - finding scattered toolkit installations when cross-compiling. + +* ``CUDA`` language support now works on QNX. + +Platforms +--------- + +* Apple Silicon is now supported (since CMake 3.19.2): + + * The :variable:`CMAKE_HOST_SYSTEM_PROCESSOR` is selected using ``uname -m``. + Since this may vary based on CMake's own architecture and that of + the invoking process tree, the :variable:`CMAKE_APPLE_SILICON_PROCESSOR` + variable or :envvar:`CMAKE_APPLE_SILICON_PROCESSOR` environment + variable may be set to specify a host architecture explicitly. + + * If :variable:`CMAKE_OSX_ARCHITECTURES` is not set, CMake adds explicit + flags to tell the compiler to build for the + :variable:`CMAKE_HOST_SYSTEM_PROCESSOR` so the toolchain does not + have to guess based on the process tree's architecture. + +File-Based API +-------------- + +* The :manual:`cmake-file-api(7)` "codemodel" version 2 ``version`` field has + been updated to 2.2. + +* The :manual:`cmake-file-api(7)` "codemodel" version 2 "target" object + gained a new ``languageStandard`` field in the ``compileGroups`` objects. + +Command-Line +------------ + +* The :manual:`cmake(1)` command-line tool's ``--install`` mode gained a + ``--default-directory-permissions`` option. + +* :manual:`cmake(1)` gained a ``-E create_hardlink`` command-line tool + that can be used to create hardlinks between files. + +GUI +--- + +* The :manual:`CMake GUI <cmake-gui(1)>` now has an environment variable + editor. + +Commands +-------- + +* The :command:`add_test` command now (officially) supports whitespace and + other special characters in the name for the test it creates. + See policy :policy:`CMP0110`. + +* The :command:`cmake_language` command gained a ``DEFER`` mode to + schedule command calls to occur at the end of processing a directory. + +* The :command:`configure_file` command gained a ``NO_SOURCE_PERMISSIONS`` + option to suppress copying the input file's permissions to the output file. + +* The :command:`execute_process` command gained a ``COMMAND_ERROR_IS_FATAL`` + option to specify a fatal error. + +* The :command:`file(ARCHIVE_CREATE)` command gained a ``COMPRESSION_LEVEL`` + option to specify the compression level. + +* The :command:`file(CHMOD)` and :command:`file(CHMOD_RECURSE)` subcommands + were added to set permissions of files and directories. + +* The :command:`file(DOWNLOAD)` command ``<file>`` argument is now + optional. If it is not specified, the file is not saved. + +* The :command:`file(GENERATE)` command gained a new ``TARGET`` keyword to + support resolving target-dependent generator expressions. + +* The :command:`file` command gained a new ``REAL_PATH`` sub-command to + compute a path with symlinks resolved. + +* The :command:`find_package` command learned to handle a version range. + +* The :command:`separate_arguments` command gained a new ``PROGRAM`` option. + It allows the arguments to be treated as a program invocation and will + resolve the executable to a full path if it can be found. + +* The ``DIRECTORY`` option of the :command:`set_property`, + :command:`get_property`, and :command:`get_directory_property` commands + now accepts references to binary directory paths, such as the value of + :variable:`CMAKE_CURRENT_BINARY_DIR`. + +* The :command:`string` command gained a set of new ``JSON`` sub commands + that provide JSON parsing capabilities. + +Variables +--------- + +* The :variable:`CMAKE_CLANG_VFS_OVERLAY` variable was added to tell + Clang to use a VFS overlay to support the Windows SDK when + cross-compiling from hosts with case-sensitive filesystems. + +* The :variable:`CMAKE_MFC_FLAG` variable now supports generator expressions. + +* The :variable:`CMAKE_OPTIMIZE_DEPENDENCIES` variable was added to + initialize the new :prop_tgt:`OPTIMIZE_DEPENDENCIES` target property and + avoid unnecessarily building dependencies for a static library. + +* The :variable:`CMAKE_PCH_INSTANTIATE_TEMPLATES` variable was added to + initialize the new :prop_tgt:`PCH_INSTANTIATE_TEMPLATES` target property. + +* The :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM` variable + was added to tell the :ref:`Visual Studio Generators` what maximum + version of the Windows SDK to choose. + +Properties +---------- + +* The :prop_tgt:`EXCLUDE_FROM_ALL` target property now supports + :manual:`generator expressions <cmake-generator-expressions(7)>`. + +* The :prop_tgt:`OPTIMIZE_DEPENDENCIES` target property was added to + avoid unnecessarily building dependencies for a static library. + +* The :prop_tgt:`PCH_INSTANTIATE_TEMPLATES` target property was added to enable + template instantiation in the precompiled header. This is enabled by default + and may significantly improve compile times. Currently only supported for + Clang (version 11 or later). + +* The :prop_tgt:`WIN32_EXECUTABLE` target property now supports + :manual:`generator expressions <cmake-generator-expressions(7)>`. + +Modules +------- + +* The :module:`CheckCompilerFlag` module has been added to + generalize :module:`CheckCCompilerFlag` and + :module:`CheckCXXCompilerFlag` to more languages. + It also supports the ``CUDA`` and ``ISPC`` languages. + +* The :module:`CheckLinkerFlag` module now supports the ``CUDA`` language. + +* The :module:`CheckSourceCompiles` module has been added to + generalize :module:`CheckCSourceCompiles` and + :module:`CheckCXXSourceCompiles` to more languages. + It also supports the ``CUDA`` and ``ISPC`` languages. + +* The :module:`CheckSourceRuns` module has been added to + generalize :module:`CheckCSourceRuns` and + :module:`CheckCXXSourceRuns` to more languages. + It also supports the ``CUDA`` language. + +* The :module:`CMakePackageConfigHelpers` module gained support for version + ranges. + +* The :module:`FindCUDAToolkit` module gained support for finding CUDA + toolkits that do not contain ``nvcc``, as well as for finding scattered + toolkit installations when cross-compiling. + +* The :module:`FindPackageHandleStandardArgs` module learned to handle + version ranges. It also gained the ``find_package_check_version()`` command + to check the validity of a version against version-related arguments of + :command:`find_package` command. + +* The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython` + modules gained the ability to handle a version range. + +* The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython` + modules provide, respectively, the variable ``Python3_LINK_OPTIONS``, + ``Python2_LINK_OPTIONS`` and ``Python_LINK_OPTIONS`` for link options. + +* The :module:`FindSDL` module now provides: + + * An imported target ``SDL::SDL``. + + * Result variables ``SDL_LIBRARIES`` and ``SDL_INCLUDE_DIRS``. + + * Version variables ``SDL_VERSION``, ``SDL_VERSION_MAJOR``, + ``SDL_VERSION_MINOR``, and ``SDL_VERSION_PATCH``. + +* The :module:`FindSWIG` module gained the ability to handle a version range. + +* The :module:`FindTIFF` module gained a ``CXX`` component to + find the ``tiffxx`` library containing C++ bindings. + +* The :module:`FindVulkan` module now provides a ``Vulkan::glslc`` imported + target and associated ``Vulkan_GLSLC_EXECUTABLE`` variable which contain + the path to the GLSL SPIR-V compiler. + +* The :module:`UseSWIG` module gained support for new source file properties + ``OUTPUT_DIR`` and ``OUTFILE_DIR`` to manage output directories on a + per-source basis. + +CTest +----- + +* :manual:`ctest(1)` now supports the CUDA ``compute-sanitizer`` checker + (previously known as ``cuda-memcheck``) as the ``CTEST_MEMORYCHECK_COMMAND``. + The different tools (``memcheck``, ``racecheck``, ``synccheck`` and + ``initcheck``) supported by ``compute-sanitizer`` can be selected by + adding appropriate flags to the ``CTEST_MEMORYCHECK_COMMAND_OPTIONS`` + variable. The default flags are ``--tool memcheck --leak-check full``. + +CPack +----- + +* CPack gained the :variable:`CPACK_PRE_BUILD_SCRIPTS`, + :variable:`CPACK_POST_BUILD_SCRIPTS`, and :variable:`CPACK_PACKAGE_FILES` + variables. + +* The :cpack_gen:`CPack External Generator` gained the + :variable:`CPACK_EXTERNAL_BUILT_PACKAGES` variable. + +* The :cpack_gen:`CPack WIX Generator` gained a + :variable:`CPACK_WIX_CUSTOM_XMLNS` option to specify custom XML namespaces. + +Other +----- + +* :ref:`Interface Libraries` may now have source files added via + :command:`add_library` or :command:`target_sources`. Those + with sources will be generated as part of the build system. + +Deprecated and Removed Features +=============================== + +* Compatibility with versions of CMake older than 2.8.12 is now deprecated + and will be removed from a future version. Calls to + :command:`cmake_minimum_required` or :command:`cmake_policy` that set + the policy version to an older value now issue a deprecation diagnostic. + +* An explicit deprecation diagnostic was added for policy ``CMP0071`` + (``CMP0071`` 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. + +* macOS SDKs older than 10.5 are no longer supported. + +* :manual:`cmake-gui(1)` now requires Qt5. + Support for compiling with Qt4 has been removed. + +* The :manual:`cmake(1)` command-line option ``--warn-unused-vars`` has + been removed and is now silently ignored. The option has not worked + correctly since CMake 3.3. + +Documentation +============= + +The following guides have been added: + +* :guide:`IDE Integration Guide` +* :guide:`Importing and Exporting Guide` + +Other Changes +============= + +* Building for macOS will now use the latest SDK available on the system, + unless the user has explicitly chosen a SDK using + :variable:`CMAKE_OSX_SYSROOT`. The deployment target or system macOS + version will not affect the choice of SDK. + +* The :variable:`CMAKE_<LANG>_COMPILER` variable may now be used to + store "mandatory" compiler flags like the :envvar:`CC` and other environment + variables. + +* The :variable:`CMAKE_<LANG>_FLAGS_INIT` variable will now be considered + during the compiler identification check if other sources like + :variable:`CMAKE_<LANG>_FLAGS` or :envvar:`CFLAGS` are not set. + +* The :command:`find_program` command now requires permission to execute + but not to read the file found. See policy :policy:`CMP0109`. + +* An imported target missing its location property fails during generation + if the location is used. See policy :policy:`CMP0111`. + +* The following target-based generator expressions that query for directory or + file name components no longer add a dependency on the evaluated target. + See policy :policy:`CMP0112`. + + - ``TARGET_FILE_DIR`` + - ``TARGET_LINKER_FILE_BASE_NAME`` + - ``TARGET_LINKER_FILE_NAME`` + - ``TARGET_LINKER_FILE_DIR`` + - ``TARGET_SONAME_FILE_NAME`` + - ``TARGET_SONAME_FILE_DIR`` + - ``TARGET_PDB_FILE_NAME`` + - ``TARGET_PDB_FILE_DIR`` + - ``TARGET_BUNDLE_DIR`` + - ``TARGET_BUNDLE_CONTENT_DIR`` + +* :ref:`Makefile Generators` no longer repeat custom commands from target + dependencies. See policy :policy:`CMP0113`. + +* The :module:`ExternalProject` module handling of step target dependencies + has been revised. See policy :policy:`CMP0114`. + +* The :prop_tgt:`OSX_ARCHITECTURES` target property is now respected + for the ``ASM`` language. + +* If ``CUDA`` compiler detection fails with user-specified + :variable:`CMAKE_CUDA_ARCHITECTURES` or + :variable:`CMAKE_CUDA_HOST_COMPILER`, an error is raised. + +Updates +======= + +Changes made since CMake 3.19.0 include the following. + +3.19.1 +------ + +* CMake 3.19.0 compiles source files with the :prop_sf:`LANGUAGE` + property by passing an explicit language flag such as ``-x c``. + This is consistent with the property's documented meaning that + the source file is written in the specified language. However, + it can break projects that were using the property only to + cause the specified language's compiler to be used. This has + been reverted to restore behavior from CMake 3.18 and below. + +* CUDA 11.1 support for Clang. + +3.19.2 +------ + +* The precompiled macOS binary provided on ``cmake.org`` is now a + universal binary with ``x86_64`` and ``arm64`` architectures. + It requires macOS 10.10 or newer. + The package file naming pattern has been changed from + ``cmake-$ver-Darwin-x86_64`` to ``cmake-$ver-macos-universal``. + +* Apple Silicon host architecture selection support was updated. + CMake 3.19.0 and 3.19.1 always chose ``arm64`` as the host architecture. + CMake 3.19.2 returns to using ``uname -m`` as CMake 3.18 and below did. + Since this may vary based on CMake's own architecture and that of + the invoking process tree, the :variable:`CMAKE_APPLE_SILICON_PROCESSOR` + variable or :envvar:`CMAKE_APPLE_SILICON_PROCESSOR` environment + variable may be set to specify a host architecture explicitly. + +* The :variable:`CMAKE_ISPC_HEADER_SUFFIX` variable and corresponding + :prop_tgt:`ISPC_HEADER_SUFFIX` target property were added to control + the header suffix used by ``ISPC`` compiler generated headers. + +3.19.3 +------ + +* A precompiled Linux ``aarch64`` binary is now provided on ``cmake.org``. + +* Two precompiled macOS binaries are now provided on ``cmake.org``: + + * The naming pattern ``cmake-$ver-macos-universal`` is a universal + binary with ``x86_64`` and ``arm64`` architectures. It requires + macOS 10.13 or newer. + + * The naming pattern ``cmake-$ver-macos10.10-universal`` is a universal + binary with ``x86_64`` and ``arm64`` architectures. It requires + macOS 10.10 or newer. + +3.19.4 +------ + +* The :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM` + variable introduced in 3.19.0 previously worked only with the + :generator:`Visual Studio 14 2015` generator. It has now been fixed to + work with :ref:`Visual Studio Generators` for later VS versions too. + +3.19.5 +------ + +* When :prop_tgt:`IOS_INSTALL_COMBINED` is enabled and the :generator:`Xcode` + generator is used, it is now possible to initiate an install or package + creation by running ``cmake --install`` or ``cpack`` from the command line. + When using the Xcode new build system, these are the only supported methods + due to a limitation of Xcode. Initiating these operations by building the + ``install`` or ``package`` targets in Xcode is only supported when using + the legacy build system. + +* The framework handling introduced in 3.19.0 as part of supporting Xcode's + *Link Binaries With Libraries* build phase broke the ability to switch + between device and simulator builds without reconfiguring. That capability + has now been restored. + +3.19.6 +------ + +* The :manual:`cmake-presets(7)` feature no longer allows comments in + ``CMakePresets.json`` or ``CMakeUserPresets.json`` files. + This was mistakenly allowed by the implementation in CMake 3.19.0 through + CMake 3.19.5, and was not documented. + +3.19.7 +------ + +* With :ref:`Visual Studio Generators` for VS 2017 and higher, the + :variable:`CMAKE_GENERATOR_TOOLSET` field ``version=`` now accepts + three-component MSVC toolset versions such as ``14.28.29910``. + See the :variable:`CMAKE_VS_PLATFORM_TOOLSET_VERSION` variable. diff --git a/Help/release/3.2.rst b/Help/release/3.2.rst new file mode 100644 index 0000000..992d44b --- /dev/null +++ b/Help/release/3.2.rst @@ -0,0 +1,277 @@ +CMake 3.2 Release Notes +*********************** + +.. only:: html + + .. contents:: + +Changes made since CMake 3.1 include the following. + +New Features +============ + +Syntax +------ + +* CMake learned to support unicode characters + :ref:`encoded as UTF-8 <CMake Language Encoding>` + on Windows. This was already supported on platforms whose + system APIs accept UTF-8 encoded strings. + Unicode characters may now be used in CMake code, paths to + source files, configured files such as ``.h.in`` files, and + other files read and written by CMake. Note that because CMake + interoperates with many other tools, there may still be some + limitations when using certain unicode characters. + +Commands +-------- + +* The :command:`add_custom_command` and :command:`add_custom_target` + commands learned a new ``BYPRODUCTS`` option to specify files + produced as side effects of the custom commands. These are not + outputs because they do not always have to be newer than inputs. + +* The :command:`add_custom_command` and :command:`add_custom_target` + commands learned a new ``USES_TERMINAL`` option to request that + the command be given direct access to the terminal if possible. + The :generator:`Ninja` generator will places such commands in the + ``console`` :prop_gbl:`pool <JOB_POOLS>`. Build targets provided by CMake + that are meant for individual interactive use, such as ``install``, are now + placed in this pool. + +* A new :command:`continue` command was added that can be called inside loop + contexts to end the current iteration and start the next one at the top of + the loop block. + +* The :command:`file(LOCK)` subcommand was created to allow CMake + processes to synchronize through file and directory locks. + +* The :command:`file(STRINGS)` now supports UTF-16LE, UTF-16BE, + UTF-32LE, UTF-32BE as ``ENCODING`` options. + +* The :command:`install(EXPORT)` command now works with an absolute + ``DESTINATION`` even if targets in the export set are installed + with a destination or :ref:`usage requirements <Target Usage Requirements>` + specified relative to the install prefix. The value of the + :variable:`CMAKE_INSTALL_PREFIX` variable is hard-coded into the installed + export file as the base for relative references. + +* The :command:`try_compile` command source file signature now honors + link flags (e.g. :variable:`CMAKE_EXE_LINKER_FLAGS`) in the generated + test project. See policy :policy:`CMP0056`. + +* The :command:`try_run` command learned to honor the ``LINK_LIBRARIES`` + option just as :command:`try_compile` already does. + +* The :command:`file(GENERATE)` command now generates the output file with + the same permissions as the input file if set. + +* The :command:`file(GENERATE)` command can now generate files which are + used as source files for buildsystem targets. Generated files + automatically get their :prop_sf:`GENERATED` property set to ``TRUE``. + +Variables +--------- + +* The :variable:`CMAKE_MATCH_COUNT` variable was introduced to record the + number of matches made in the last regular expression matched in an + :command:`if` command or a :command:`string` command. + +Properties +---------- + +* An :prop_tgt:`ANDROID_API_MIN` target property was introduced to + specify the minimum version to be targeted by the toolchain. + +* A :prop_sf:`VS_SHADER_FLAGS` source file property was added to specify + additional shader flags to ``.hlsl`` files, for the Visual Studio + generators. + +Modules +------- + +* The :module:`ExternalData` module learned to support + :ref:`Custom Fetch Scripts <ExternalData Custom Fetch Scripts>`. + This allows projects to specify custom ``.cmake`` scripts for + fetching data objects during the build. + +* The :module:`ExternalProject` module learned options to create + independent external project step targets that do not depend + on the builtin steps. + +* The :module:`ExternalProject` module :command:`ExternalProject_Add` + command learned a new ``CMAKE_CACHE_DEFAULT_ARGS`` option to + initialize cache values in the external project without setting + them on future builds. + +* The :module:`ExternalProject` module :command:`ExternalProject_Add` + command learned a new ``TEST_EXCLUDE_FROM_MAIN`` option to exclude + tests from the main build. + +* The :module:`ExternalProject` module :command:`ExternalProject_Add` + command learned a new ``UPDATE_DISCONNECTED`` option to avoid + automatically updating the source tree checkout from version control. + +* The :module:`FindCUDA` module learned about the ``cusolver`` + library in CUDA 7.0. + +* The :module:`FindGit` module learned to find the ``git`` command-line tool + that comes with GitHub for Windows installed in user home directories. + +* A :module:`FindGSL` module was introduced to find the + GNU Scientific Library. + +* A :module:`FindIntl` module was introduced to find the + Gettext ``libintl`` library. + +* The :module:`FindLATEX` module learned to support components. + +* The :module:`FindMPI` module learned to find MS-MPI on Windows. + +* The :module:`FindOpenSSL` module now reports ``crypto`` and ``ssl`` + libraries separately in ``OPENSSL_CRYPTO_LIBRARY`` and + ``OPENSSL_SSL_LIBRARY``, respectively, to allow applications to + link to one without the other. + +* The :module:`WriteCompilerDetectionHeader` module learned to + create a define for portability of the ``cxx_thread_local`` feature. + The define expands to either the C++11 ``thread_local`` keyword, or a + pre-standardization compiler-specific equivalent, as appropriate. + +* The :module:`WriteCompilerDetectionHeader` module learned to create + multiple output files per compiler and per language, instead of creating + one large file. + +CTest +----- + +* The :command:`ctest_coverage` command learned to support Delphi coverage. + +* The :command:`ctest_coverage` command learned to support Javascript coverage. + +* The :module:`CTestCoverageCollectGCOV` module was introduced as an + alternative to the :command:`ctest_coverage` command for collecting + ``gcov`` results for submission to CDash. + +CPack +----- + +* 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 :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 :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 :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 :cpack_gen:`CPack RPM Generator` learned a new + :variable:`CPACK_RPM_RELOCATION_PATHS` variable to + specify multiple relocation prefixes for a single rpm package. + +Other +----- + +* The :manual:`cmake(1)` ``-E tar`` command now supports creating + ``.xz``-compressed archives with the ``J`` flag. + +* The :manual:`cmake(1)` ``-E tar`` command learned a new + ``--files-from=<file>`` option to specify file names using + lines in a file to overcome command-line length limits. + +* The :manual:`cmake(1)` ``-E tar`` command learned a new + ``--mtime=<date>`` option to specify the modification time + recorded in tarball entries. + +* The :manual:`Compile Features <cmake-compile-features(7)>` functionality + is now aware of features supported by more compilers, including: + + * Apple Clang (``AppleClang``) for Xcode versions 4.4 though 6.1. + * GNU compiler versions 4.4 through 5.0 on UNIX and Apple (``GNU``). + * Microsoft Visual Studio (``MSVC``) for versions 2010 through 2015. + * Oracle SolarisStudio (``SunPro``) version 12.4. + +* The :ref:`Qt AUTORCC` feature now tracks files listed in ``.qrc`` files + as dependencies. If an input file to the ``rcc`` tool is changed, the tool + is automatically re-run. + +New Diagnostics +=============== + +* The :command:`break` command now rejects calls outside of a loop + context or that pass arguments to the command. + See policy :policy:`CMP0055`. + +Deprecated and Removed Features +=============================== + +* Files written in the :manual:`cmake-language(7)`, such as + ``CMakeLists.txt`` or ``*.cmake`` files, are now expected to be + encoded as UTF-8. If files are already ASCII, they will be + compatible. If files were in a different encoding, including + Latin 1, they will need to be converted. + +* The :module:`FindOpenGL` module no longer explicitly searches + for any dependency on X11 libraries with the :module:`FindX11` + module. Such dependencies should not need to be explicit. + Applications using X11 APIs themselves should find and link + to X11 libraries explicitly. + +* The implementation of CMake now relies on some C++ compiler features which + are not supported by some older compilers. As a result, those old compilers + can no longer be used to build CMake itself. CMake continues to be able to + generate Makefiles and project files for users of those old compilers + however. Compilers known to no longer be capable of building CMake are: + + * Visual Studio 6 and 7.0 -- superseded by VisualStudio 7.1 and newer. + * GCC 2.95 -- superseded by GCC 3 and newer compilers. + * Borland compilers -- superseded by other Windows compilers. + * Compaq compilers -- superseded by other compilers. + * SGI compilers -- IRIX was dropped as a host platform. + +Other Changes +============= + +* On Windows and OS X, commands supporting network communication + via ``https``, such as :command:`file(DOWNLOAD)`, + :command:`file(UPLOAD)`, and :command:`ctest_submit`, now support + SSL/TLS even when CMake is not built against OpenSSL. + The Windows or OS X native SSL/TLS implementation is used by default. + OS-configured certificate authorities will be trusted automatically. + + On other platforms, when CMake is built with OpenSSL, these + commands now search for OS-configured certificate authorities + in a few ``/etc`` paths to be trusted automatically. + +* On OS X with Makefile and Ninja generators, when a compiler is found + in ``/usr/bin`` it is now mapped to the corresponding compiler inside + the Xcode application folder, if any. This allows such build + trees to continue to work with their original compiler even when + ``xcode-select`` switches to a different Xcode installation. + +* The Visual Studio generators now write solution and project + files in UTF-8 instead of Windows-1252. Windows-1252 supported + Latin 1 languages such as those found in North and South America + and Western Europe. With UTF-8, additional languages are now + supported. + +* The :generator:`Xcode` generator no longer requires a value for + the :variable:`CMAKE_MAKE_PROGRAM` variable to be located up front. + It now locates ``xcodebuild`` when needed at build time. + +* When building CMake itself using SolarisStudio 12, the default ``libCStd`` + standard library is not sufficient to build CMake. The SolarisStudio + distribution supports compiler options to use ``STLPort4`` or ``libstdc++``. + An appropriate option to select the standard library is now added + automatically when building CMake with SolarisStudio compilers. diff --git a/Help/release/3.20.rst b/Help/release/3.20.rst new file mode 100644 index 0000000..86c6a86 --- /dev/null +++ b/Help/release/3.20.rst @@ -0,0 +1,353 @@ +CMake 3.20 Release Notes +************************ + +.. only:: html + + .. contents:: + +Changes made since CMake 3.19 include the following. + +New Features +============ + +Presets +------- + +* :manual:`cmake-presets(7)` gained support for build and test presets. + +Generators +---------- + +* :ref:`Makefile Generators`, for some toolchains, now use the compiler + to extract implicit dependencies while compiling source files. + +Languages +--------- + +* C++23 compiler modes may now be specified via the :prop_tgt:`CXX_STANDARD`, + :prop_tgt:`CUDA_STANDARD`, or :prop_tgt:`OBJCXX_STANDARD` target properties, + or via the :manual:`Compile Features <cmake-compile-features(7)>` + functionality's ``cxx_std_23`` meta-feature. + +* ``CUDA`` language support now works when ``nvcc`` is a symbolic link, + for example due to a ``ccache`` or ``colornvcc`` wrapper script. + +* The :envvar:`CUDAARCHS` environment variable was added for initializing + :variable:`CMAKE_CUDA_ARCHITECTURES`. Useful in cases where the compiler + default is unsuitable for the machine's GPU. + +Compilers +--------- + +* The NVIDIA HPC SDK compilers are now supported with compiler id ``NVHPC``. + +* The Intel oneAPI NextGen LLVM compilers are now supported with + compiler id ``IntelLLVM``: + + * The ``icx``/``icpx`` C/C++ compilers on Linux, and the ``icx`` + C/C++ compiler on Windows, are fully supported as of oneAPI 2021.1. + + * The ``ifx`` Fortran compiler on Linux is partially supported. + As of oneAPI 2021.1, ``ifx`` does not define several identification + macros, so CMake identifies it as the classic ``Intel`` compiler. + This works in many cases because ``ifx`` accepts the same command line + parameters as ``ifort``. A future version of oneAPI may fix this. + + * The ``ifx`` Fortran compiler on Windows is not yet supported. + + The Intel oneAPI Classic compilers (``icc``, ``icpc``, and ``ifort``) + continue to be supported with compiler id ``Intel``. + +* Support was added for the IAR STM8 compiler. + +Platforms +--------- + +* CMake's support for :ref:`Cross Compiling for Android` + is now merged with the Android NDK's toolchain file. + They now have similar behavior, though some variable names differ. + User-facing changes include: + + - ``find_*`` functions will search NDK ABI / API specific paths by default. + + - The default :variable:`CMAKE_BUILD_TYPE` for Android is + now ``RelWithDebInfo``. + + - The :variable:`CMAKE_ANDROID_NDK_VERSION` variable was added to + report the version of the NDK. + +File-Based API +-------------- + +* The :manual:`cmake-file-api(7)` gained a new "toolchains" object + kind that describes the compiler used for each enabled language. + +Commands +-------- + +* :command:`add_custom_command` and :command:`add_custom_target` now + support :manual:`generator expressions <cmake-generator-expressions(7)>` + in their ``OUTPUT`` and ``BYPRODUCTS`` options. + + Their ``COMMAND``, ``WORKING_DIRECTORY``, and ``DEPENDS`` options gained + support for new generator expressions ``$<COMMAND_CONFIG:...>`` and + ``$<OUTPUT_CONFIG:...>`` that control cross-config handling when using + the :generator:`Ninja Multi-Config` generator. + +* The :command:`add_custom_command` command gained ``DEPFILE`` support on + :ref:`Makefile Generators`. + +* The :command:`add_library` command previously prohibited imported object + libraries when using potentially multi-architecture configurations. + This mostly affected the :generator:`Xcode` generator, e.g. when targeting + iOS or one of the other device platforms. This restriction has now been + removed. + +* The :command:`cmake_path` command was added for operations on + filesystem paths. + +* The :command:`configure_file` command gained ``USE_SOURCE_PERMISSIONS`` + and ``FILE_PERMISSIONS`` options to support copying of permissions of the + source file and using specified permissions respectively. + +* The :command:`file(GENERATE)` command gained a ``NEWLINE_STYLE`` option to + specify how newlines are handled for the generated file. + +* The :command:`file(GENERATE)` command gained ``NO_SOURCE_PERMISSIONS``, + ``USE_SOURCE_PERMISSIONS``, and ``FILE_PERMISSIONS`` options for controlling + the permissions of the generated file. + +* The :command:`install(FILES)` command ``RENAME`` option learned to + support :manual:`generator expressions <cmake-generator-expressions(7)>`. + +* The :command:`target_include_directories` command gained a new option + ``AFTER``. + +* The :command:`target_sources` command now supports targets created + by the :command:`add_custom_target` command. + +* The :command:`try_run` command gained a ``WORKING_DIRECTORY`` option to + set the working directory in which to run the compiled check executable. + +Variables +--------- + +* The :variable:`CMAKE_<LANG>_BYTE_ORDER` variable was added to provide the + target architecture byte order detected from the toolchain. + +* The :variable:`CMAKE_RUNTIME_OUTPUT_DIRECTORY`, + :variable:`CMAKE_LIBRARY_OUTPUT_DIRECTORY`, and + :variable:`CMAKE_ARCHIVE_OUTPUT_DIRECTORY` variables now support + target-dependent generator expressions. + +Properties +---------- + +* The :prop_tgt:`<LANG>_CLANG_TIDY` target property and the associated + :variable:`CMAKE_<LANG>_CLANG_TIDY` variable learned to support + the ``OBJC`` and ``OBJCXX`` languages. + +* The :prop_tgt:`EXPORT_COMPILE_COMMANDS` target property was added + for the associated :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` variable + to allow for configuration of exporting compile commands per target. + +* The :prop_sf:`GENERATED` source-file property is now visible + from any directory scope, regardless of the scope in which it is set. + See policy :policy:`CMP0118`. + +* The :prop_tgt:`UNITY_BUILD_UNIQUE_ID` target property + was added to support generation of an identifier that is + unique per source file in unity builds. It can help to + resolve duplicate symbol problems with anonymous namespaces. + +* The :prop_tgt:`WIN32_EXECUTABLE` target property now works with Clang + on Windows. + +* The :prop_tgt:`XCODE_EMBED_FRAMEWORKS <XCODE_EMBED_<type>>` target property + was added to tell the :generator:`Xcode` generator to embed frameworks. + Aspects of the embedding can be customized with the + :prop_tgt:`XCODE_EMBED_FRAMEWORKS_PATH <XCODE_EMBED_<type>>`, + :prop_tgt:`XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY`, and + :prop_tgt:`XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY` target properties. + +Modules +------- + +* The :module:`ExternalData` module :command:`ExternalData_Add_Target` + function gained a ``SHOW_PROGRESS <bool>`` option for controlling whether + or not to show progress output during the build. + +* The :module:`ExternalProject` module :command:`ExternalProject_Add` function + gained a ``CONFIGURE_HANDLED_BY_BUILD`` option. This can be used to make + subsequent runs of the configure step be triggered by the build step when + an external project dependency rebuilds instead of always re-running the + configure step in such cases. + +* The :module:`FindBoost` module gained a ``Boost_NO_WARN_NEW_VERSIONS`` + option to silence the warning about unknown dependencies for new + Boost versions. + +* The :module:`FindCUDAToolkit` module gained support for finding CUDA + toolkits when ``nvcc`` is a symbolic link, + for example due to a ``ccache`` or ``colornvcc`` wrapper script. + +* The :module:`FindGDAL` module has been improved to document and mark as + advanced its cache variables. There is a new ``FindGDAL_SKIP_GDAL_CONFIG`` + variable which may be used to skip over the ``gdal-config``-based search. + Users may also set ``GDAL_ADDITIONAL_LIBRARY_VERSIONS`` to add additional + versions to the library name search strategy. + +* The :module:`FindIntl` module now provides an imported target. + +* The :module:`FindOpenSSL` module learned to support a version range. + +* The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython` + modules gained options controlling how unversioned interpreter names are + searched. + +* The :module:`UseJava` module ``add_jar()`` command's + ``GENERATE_NATIVE_HEADERS`` feature gained options to export the + generated target. + +* The :module:`UseSWIG` module gained the capability, for + :ref:`Makefile <Makefile Generators>` and :ref:`Ninja <Ninja Generators>` + generators, to use the ``swig`` tool to generate implicit dependencies. + +Autogen +------- + +* The :ref:`Qt AUTOMOC` feature now works with per-config sources. + +CTest +----- + +* :manual:`ctest(1)` gained a ``--test-dir`` option to specify the directory + in which to look for tests. + +CPack +----- + +* :module:`CPack` gained the :variable:`CPACK_THREADS` variable to + control the number of threads used for parallelized operations, + such as compressing the installer package. + +* The :cpack_gen:`CPack DEB Generator` learned a new + :variable:`CPACK_DEBIAN_PACKAGE_SHLIBDEPS_PRIVATE_DIRS` + variable to specify additional search directories for + resolving private library dependencies when using + ``dpkg-shlibdeps``. + +* The :cpack_gen:`CPack IFW Generator` gained a new + :variable:`CPACK_IFW_PACKAGE_WIZARD_SHOW_PAGE_LIST` variable to + control visibility of the widget listing installer pages on the left side + of the wizard. This feature available only since QtIFW 4.0. + +* The :cpack_gen:`CPack NSIS Generator` gained new + :variable:`CPACK_NSIS_BRANDING_TEXT` and + :variable:`CPACK_NSIS_BRANDING_TEXT_TRIM_POSITION` variables to change + the text at the bottom of the install window and change its trim position + +* The :cpack_gen:`CPack NSIS Generator` now correctly handles Unicode + characters. If you want to have a :variable:`CPACK_RESOURCE_FILE_LICENSE` + with UTF-8 characters, it needs to be encoded in UTF-8 BOM. + +* The :cpack_gen:`CPack NuGet Generator` gained options: + + - :variable:`CPACK_NUGET_PACKAGE_ICON` and + :variable:`CPACK_NUGET_<compName>_PACKAGE_ICON` + allow package icons to be specified by local files. + - :variable:`CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION` and + :variable:`CPACK_NUGET_<compName>_PACKAGE_LICENSE_EXPRESSION` add + support for specifying licenses recognized by the + `Software Package Data Exchange`_ (SPDX). + - :variable:`CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME` and + :variable:`CPACK_NUGET_<compName>_PACKAGE_LICENSE_FILE_NAME` allow + licenses to be specified by local files. + - :variable:`CPACK_NUGET_PACKAGE_LANGUAGE` and + :variable:`CPACK_NUGET_<compName>_PACKAGE_LANGUAGE` allow the locale + for a package to be specified, for example ``en_CA``. + +.. _Software Package Data Exchange: https://spdx.org/ + +Deprecated and Removed Features +=============================== + +* The :manual:`cmake-server(7)` mode has been removed. + Clients should use the :manual:`cmake-file-api(7)` instead. + +* The :module:`WriteCompilerDetectionHeader` module has been deprecated + via policy :policy:`CMP0120`. Projects should be ported away from it. + +* The :module:`TestBigEndian` module has been deprecated in favor + of the :variable:`CMAKE_<LANG>_BYTE_ORDER` variable. + +* The :module:`AddFileDependencies` module is deprecated. + Port projects to use :command:`set_property` directly. + +* The :cpack_gen:`CPack NuGet Generator` deprecated some variables to reflect + changes in the NuGet specification: + + - :variable:`CPACK_NUGET_PACKAGE_ICONURL` and + :variable:`CPACK_NUGET_<compName>_PACKAGE_ICONURL` have been deprecated; + replace with a reference to a local icon file. + - :variable:`CPACK_NUGET_PACKAGE_LICENSEURL` and + :variable:`CPACK_NUGET_<compName>_PACKAGE_LICENSEURL` have been deprecated; + replace with a reference to the project's license file or SPDX + license expression. + +Other Changes +============= + +* When running :manual:`cmake(1)` to :ref:`Generate a Project Buildsystem`, + unknown command-line arguments starting with a hyphen (``-``) are now + rejected with an error. Previously they were silently ignored. + +* Source file extensions must now be explicit. + See policy :policy:`CMP0115` for details. + +* The :prop_sf:`LANGUAGE` source file property now forces compilation + as the specified language. See policy :policy:`CMP0119`. + +* On AIX, installation of XCOFF executables and shared libraries + no longer requires relinking to change the runtime search path + from the build-tree RPATH to the install-tree RPATH. CMake now + edits the XCOFF binaries directly during installation, as has + long been done on ELF platforms. + +* With MSVC-like compilers the value of + :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>` no longer contains + the ``/GR`` flag for runtime type information by default. + See policy :policy:`CMP0117`. + +* Ninja generators now transform the ``DEPFILE`` generated by an + :command:`add_custom_command`. See policy :policy:`CMP0116` for details. + +* The precompiled Linux binaries provided on + `cmake.org <https://cmake.org/download/>`_ have changed their naming pattern + to ``cmake-$ver-linux-$arch``, where ``$arch`` is either ``x86_64`` or + ``aarch64``. + +* The precompiled Windows binaries provided on + `cmake.org <https://cmake.org/download/>`_ have changed their naming pattern + to ``cmake-$ver-windows-$arch``, where ``$arch`` is either ``x86_64`` or + ``i386``. + +Updates +======= + +Changes made since CMake 3.20.0 include the following. + +3.20.1 +------ + +* The :module:`FindIntl` module in CMake 3.20.0 added checks + ``Intl_HAVE_GETTEXT_BUILTIN``, ``Intl_HAVE_DCGETTEXT_BUILTIN``, + and ``Intl_IS_BUILTIN``, but they were not implemented correctly. + These have been removed and replaced with a single ``Intl_IS_BUILT_IN`` + check, whose name is consistent with the :module:`FindIconv` module. + +* The ``-rpath`` linker flag is now specified as supported on all Apple + platforms, not just macOS. The ``install_name_dir`` used for + iOS, tvOS and watchOS should now default to ``@rpath`` instead of using + a full absolute path and failing at runtime when the library or framework + is embedded in an application bundle (see :prop_tgt:`XCODE_EMBED_<type>`). diff --git a/Help/release/3.3.rst b/Help/release/3.3.rst new file mode 100644 index 0000000..44f4e19 --- /dev/null +++ b/Help/release/3.3.rst @@ -0,0 +1,287 @@ +CMake 3.3 Release Notes +*********************** + +.. only:: html + + .. contents:: + +Changes made since CMake 3.2 include the following. + +New Features +============ + +Generators +---------- + +* The :ref:`Makefile Generators` now add ``.DELETE_ON_ERROR`` to the + makefiles that contain the actual build rules for files on disk. + This tells GNU make to remove rule outputs when their recipe + modifies an output but fails. + +* The :ref:`Visual Studio Generators` learned to support ``.xaml`` + source files and automatically associate them with corresponding + ``.h`` and ``.cpp`` sources. + +* A new experimental :generator:`Green Hills MULTI` generator was + added on Windows. `Green Hills MULTI`_ is an IDE for embedded + real-time systems. + +.. _`Green Hills MULTI`: http://www.ghs.com/products/MULTI_IDE.html + +Commands +-------- + +* The :command:`add_dependencies` command learned to allow dependencies + to be added to :ref:`interface libraries <Interface Libraries>`. + Dependencies added to an interface library are followed transitively + in its place since the target itself does not build. + +* The :command:`execute_process` command learned to support specifying + the same file for ``OUTPUT_FILE`` and ``ERROR_FILE``. + +* The :command:`file(GLOB)` and :command:`file(GLOB_RECURSE)` commands + learned a new ``LIST_DIRECTORIES <bool>`` option to specify whether + the glob result should include directories. + +* The :command:`find_library`, :command:`find_path`, and :command:`find_file` + commands now search in installation prefixes derived from the ``PATH`` + environment variable. + +* The :command:`if` command learned a new ``IN_LIST`` operator that + evaluates to true if a given element is contained in a named list. + +* The :command:`install(EXPORT)` and :command:`export()` commands + learned to export targets that populate the :prop_tgt:`INTERFACE_SOURCES` + target property. + +* The :command:`install(TARGETS)` command learned to support + generator expressions in the ``DESTINATION`` value. + +Variables +--------- + +* The version of some Fortran compilers is now detected and stored in the + :variable:`CMAKE_Fortran_COMPILER_VERSION <CMAKE_<LANG>_COMPILER_VERSION>` + variable. + +* The :ref:`Visual Studio Generators` learned a new + :variable:`CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD` option + to put the ``INSTALL`` target in the default build of a + solution (``.sln``) file. + +Properties +---------- + +* A :prop_tgt:`CROSSCOMPILING_EMULATOR` target property and supporting + :variable:`CMAKE_CROSSCOMPILING_EMULATOR` variable were introduced + to allow target platform binaries to run on the host during cross + compiling. + +* A :prop_tgt:`<LANG>_INCLUDE_WHAT_YOU_USE` target property and supporting + :variable:`CMAKE_<LANG>_INCLUDE_WHAT_YOU_USE` variable were introduced + to tell the :ref:`Makefile Generators` and the :generator:`Ninja` generator + to run ``include-what-you-use`` along with the compiler for ``C`` and + ``CXX`` languages. + +* The :prop_tgt:`<LANG>_VISIBILITY_PRESET` and + :prop_tgt:`VISIBILITY_INLINES_HIDDEN` target properties now + affect compilation in sources of all target types. See + policy :policy:`CMP0063`. + +* The :prop_tgt:`XCODE_ATTRIBUTE_<an-attribute>` target property learned + to support generator expressions. + +Modules +------- + +* The :module:`CheckFortranCompilerFlag` module was introduced + to check ``Fortran`` compiler flags, much like the + :module:`CheckCCompilerFlag` module already does for ``C``. + +* The :module:`ExternalData` module learned a new + :variable:`ExternalData_NO_SYMLINKS` option to disable use of + symbolic links to populate the real data files and use copies + instead. + +* The :module:`ExternalData` module learned a new ``RECURSE:`` + option in ``DATA{}`` references specifying directories. + This allows an entire directory tree of associated files + to be matched. + +* The :module:`ExternalData` module learned a new URL template + placeholder ``%(algo:<key>)`` to allow custom mapping from + algorithm name to URL component through configuration of new + :variable:`ExternalData_URL_ALGO_<algo>_<key>` variables. + This allows more flexibility in remote URLs. + +* The :module:`ExternalProject` module learned to replace tokens + like ``<BINARY_DIR>`` in the ``BYPRODUCTS`` of each step. + +* The :module:`ExternalProject` module APIs learned to support + :manual:`generator expressions <cmake-generator-expressions(7)>` + when using ``LOG_*`` options and in CMake initial cache options. + +* The :module:`FindBoost` module now tracks the directories containing + libraries separately for RELEASE and DEBUG configurations. + +* The :module:`FindCUDA` module now defaults to using the static + CUDA runtime library if it is available. A new + ``CUDA_USE_STATIC_CUDA_RUNTIME`` option is offered to control + this behavior. + +* The :module:`FindMatlab` module was completely rewritten. It learned + about versions and components and to find Matlab in a more precise and + multiplatform way. The module now offers APIs to create mex extensions, + documentation, and unit tests. + +* The :module:`FindPackageHandleStandardArgs` module + ``FIND_PACKAGE_HANDLE_STANDARD_ARGS`` function now + always populates both the ``<PackageName>_FOUND`` + and ``<UPPERCASE_NAME>_FOUND`` variables (the latter + for backwards compatibility). The ``FOUND_VAR`` + option is now ignored except to enforce its allowed + values. + +* The :module:`InstallRequiredSystemLibraries` module learned a new + ``CMAKE_INSTALL_SYSTEM_RUNTIME_COMPONENT`` option to specify the + installation component. + +Generator Expressions +--------------------- + +* A new ``COMPILE_LANGUAGE`` generator expression was introduced to + allow specification of compile options for target files based on the + :prop_sf:`LANGUAGE` of each source file. Due to limitations of the + underlying native build tools, this feature has varying support across + generators. See the :manual:`cmake-generator-expressions(7)` manual + for details. + +CTest +----- + +* The :manual:`ctest(1)` tool learned a new ``--repeat-until-fail <n>`` + option to help find sporadic test failures. + +* The :module:`CTestCoverageCollectGCOV` module learned to support + the same ``CTEST_CUSTOM_COVERAGE_EXCLUDE`` option as the + :command:`ctest_coverage` command. + +CPack +----- + +* The :cpack_gen:`CPack IFW Generator` learned to support + Qt Framework Installer 2.0 tools. + +* 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 :cpack_gen:`CPack DEB Generator` learned a new + :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS` + option to specify per-component dependencies. + +* The :cpack_gen:`CPack RPM Generator` learned to package symbolic links + more cleanly and now supports directory symlinks with recent + ``rpmbuild`` versions. + +* 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 :cpack_gen:`CPack RPM Generator` learned a new + :variable:`CPACK_RPM_<component>_PACKAGE_ARCHITECTURE` variable + to specify a component-specific package architecture. + +* The CPack WIX generator learned the new + :prop_inst:`CPACK_START_MENU_SHORTCUTS`, + :prop_inst:`CPACK_DESKTOP_SHORTCUTS` and + :prop_inst:`CPACK_STARTUP_SHORTCUTS` installed file properties which can + be used to install shortcuts in the Start Menu, on the Desktop and + in the Startup Folder respectively. + +Other +----- + +* The :manual:`Compile Features <cmake-compile-features(7)>` functionality + is now aware of features supported by GNU compilers on Windows, versions + 4.4 through 5.0. + +* The :manual:`cmake(1)` ``-E tar`` command learned a new + ``--format<format>`` option to specify the archive format to + be written. + +* On OS X, CMake learned to create XCTest bundles to test Frameworks + and App Bundles within Xcode. The :module:`FindXCTest` module + provides convenience functions to handle :prop_tgt:`XCTEST` bundles. + +Deprecated and Removed Features +=============================== + +* On OS X the :manual:`cmake-gui(1)` no longer has the + ``Install For Command Line Use`` menu item. Instead there + is a ``How to Install For Command Line Use`` menu item + that shows an informational dialog box explaining how to + make the command line tools available. For example:: + + /Applications/CMake.app/Contents/bin/cmake-gui --install + +* The :command:`ctest_build` and :command:`build_command` commands + no longer tell ``make`` tools to ignore errors with the ``-i`` option. + Previously this was done for :ref:`Makefile Generators` but not others. + See policy :policy:`CMP0061`. + +* The :generator:`Visual Studio 10 2010` generator no longer checks + for running VS IDEs with the project open or asks them to reload. + This was originally done for VS 10 because it had been done for + VS 7 through 9 to avoid prompting for every project in a solution. + Since VS >= 10 allow the whole solution to reload at once they + do not need CMake to help them. + +* The :generator:`Visual Studio 7` generator (.NET 2002) is now + deprecated and will be removed in a future version of CMake. + +* The :generator:`Visual Studio 6` generator is now deprecated + and will be removed in a future version of CMake. + +* The :command:`find_package` command no longer considers project + build trees recently configured in a :manual:`cmake-gui(1)`. + This was previously done only on Windows and is now never done. + The ``NO_CMAKE_BUILDS_PATH`` option is now ignored if given + and effectively always on. + Projects may populate the :ref:`User Package Registry` to aid + users building multiple dependent projects one after another. + +* The :command:`add_definitions()` command no longer causes a + :prop_dir:`DEFINITIONS` directory property to be populated. See policy + :policy:`CMP0059`. + +* With Visual Studio 7, 8, and 9 generators the value of the ``$(OutDir)`` + placeholder no longer evaluates to the configuration name. Projects + should use ``$(ConfigurationName)`` for that instead. + +* Using the output of :command:`export()` with the :command:`install(FILES)` + command is no longer allowed. See policy :policy:`CMP0062` for details. + +Other Changes +============= + +* The :generator:`Ninja` generator now requires that calls to the + :command:`add_custom_command` and :command:`add_custom_target` + commands use the ``BYPRODUCTS`` option to explicitly specify any + files generated by the custom commands that are not listed as + outputs (perhaps because their timestamps are allowed to be older + than the inputs). See policy :policy:`CMP0058`. + +* Build-time progress output of :ref:`Makefile Generators` has been improved. + It no longer mixes progress and build rule messages during parallel builds. + The link rule messages now have progress and are displayed as bold green + instead of bold red (since red is often associated with an error message). + +* The :variable:`CMAKE_CFG_INTDIR` variable value for Visual Studio + 7, 8, and 9 is now ``$(ConfigurationName)`` instead of ``$(OutDir)``. + This should have no effect on the intended use cases of the variable. + +* Linking to library files by a full path in an implicit linker search + directory (e.g. ``/usr/lib/libfoo.a``) no longer asks the linker to + search for the library (e.g. ``-lfoo``) and now links by full path. + See policy :policy:`CMP0060`. diff --git a/Help/release/3.4.rst b/Help/release/3.4.rst new file mode 100644 index 0000000..943d267 --- /dev/null +++ b/Help/release/3.4.rst @@ -0,0 +1,273 @@ +CMake 3.4 Release Notes +*********************** + +.. only:: html + + .. contents:: + +Changes made since CMake 3.3 include the following. + +New Features +============ + +Generators +---------- + +* The :generator:`Visual Studio 14 2015` generator learned to select + a Windows 10 SDK based on the value of the :variable:`CMAKE_SYSTEM_VERSION` + variable and the SDKs available on the host. + +* CMake learned rudimentary support for the Apple Swift language. When using + the :generator:`Xcode` generator with Xcode 6.1 or higher, one may enable + the ``Swift`` language with the :command:`enable_language` command or the + :command:`project` command (this is an error with other generators or when + Xcode is too old). Then one may list ``.swift`` source files in targets + for compilation. + +Commands +-------- + +* The :command:`find_program` command learned a ``NAMES_PER_DIR`` + option to consider all given ``NAMES`` in each directory before + moving on to the next directory. + +* The :command:`get_filename_component` command learned a new ``BASE_DIR`` + subcommand. This is used to specify a base directory when calculating an + absolute path from a relative path. + +* The :command:`if` command learned a new ``TEST`` operator that evaluates + to true if a given test name has been defined by the :command:`add_test` + command. See policy :policy:`CMP0064`. + +* The :command:`install(DIRECTORY)` command ``DESTINATION`` option learned to + support :manual:`generator expressions <cmake-generator-expressions(7)>`. + +* The :command:`install(FILES)` command ``DESTINATION`` option learned to + support :manual:`generator expressions <cmake-generator-expressions(7)>`. + +* The :command:`string` command learned a new ``APPEND`` subcommand. + +Variables +--------- + +* The :ref:`Makefile Generators` and the :generator:`Ninja` generator + learned to add compiler launcher tools like distcc and ccache along + with the compiler for ``C`` and ``CXX`` languages. See the + :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER` variable and + :prop_tgt:`<LANG>_COMPILER_LAUNCHER` target property for details. + +* New :variable:`CMAKE_LINK_SEARCH_START_STATIC` and + :variable:`CMAKE_LINK_SEARCH_END_STATIC` variables were + introduced to initialize the + :prop_tgt:`LINK_SEARCH_START_STATIC` and + :prop_tgt:`LINK_SEARCH_END_STATIC` target properties, + respectively. + +Properties +---------- + +* :ref:`Visual Studio Generators` learned to support additional + target properties to customize projects for NVIDIA Nsight + Tegra Visual Studio Edition: + + * :prop_tgt:`ANDROID_ANT_ADDITIONAL_OPTIONS` + * :prop_tgt:`ANDROID_ARCH` + * :prop_tgt:`ANDROID_ASSETS_DIRECTORIES` + * :prop_tgt:`ANDROID_JAR_DEPENDENCIES` + * :prop_tgt:`ANDROID_JAR_DIRECTORIES` + * :prop_tgt:`ANDROID_JAVA_SOURCE_DIR` + * :prop_tgt:`ANDROID_NATIVE_LIB_DEPENDENCIES` + * :prop_tgt:`ANDROID_NATIVE_LIB_DIRECTORIES` + * :prop_tgt:`ANDROID_PROCESS_MAX` + * :prop_tgt:`ANDROID_PROGUARD` + * :prop_tgt:`ANDROID_PROGUARD_CONFIG_PATH` + * :prop_tgt:`ANDROID_SECURE_PROPS_PATH` + * :prop_tgt:`ANDROID_SKIP_ANT_STEP` + * :prop_tgt:`ANDROID_STL_TYPE` + +* The :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY`, + :prop_tgt:`LIBRARY_OUTPUT_DIRECTORY`, and + :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` target properties learned to + support :manual:`generator expressions <cmake-generator-expressions(7)>`. + +* The :prop_tgt:`SOURCE_DIR` and :prop_tgt:`BINARY_DIR` target properties + were introduced to allow project code to query where a target is defined. + +* The :prop_tgt:`OUTPUT_NAME` target property and its variants learned to + support :manual:`generator expressions <cmake-generator-expressions(7)>`. + +* A :prop_gbl:`TARGET_MESSAGES` global property was added to tell the + :ref:`Makefile Generators` whether to generate commands to print output + after each target is completed. + +* On Windows with MS-compatible tools, CMake learned to optionally + generate a module definition (``.def``) file for ``SHARED`` libraries. + See the :prop_tgt:`WINDOWS_EXPORT_ALL_SYMBOLS` target property. + +Modules +------- + +* The :module:`ExternalProject` module :command:`ExternalProject_Add` + function ``GIT_SUBMODULES`` option now also limits the set of + submodules that are initialized in addition to the prior behavior + of limiting the set of submodules that are updated. + +* The :module:`ExternalProject` module learned new ``USES_TERMINAL`` + arguments for giving steps exclusive terminal access. This is + useful with the :generator:`Ninja` generator to monitor CMake + superbuild progress and prevent CPU oversubscription. + +* The :module:`FindBISON` module ``BISON_TARGET`` macro learned a + new ``DEFINES_FILE`` option to specify a custom output header + to be generated. + +* The :module:`FindHDF5` module learend a new ``HDF5_PREFER_PARALLEL`` + option allowing users to specify that a parallel HDF5 tool is + preferred if both are available. + +* The :module:`FindIce` module now provides imported targets. + +* The :module:`FindJava` module learned to optionally find + the ``idlj`` and ``jarsigner`` tools. + +* The :module:`FindOpenSSL` module now provides imported targets. + +* The :module:`FindOpenSSL` module learned a new ``OPENSSL_USE_STATIC_LIBS`` + option to search only for static libraries. + +* The :module:`FindPkgConfig` learned a new :command:`pkg_get_variable` + command which may be used to query for arbitrary variables from a package + (such as for related tools or data and plugin install paths). + +* The :module:`FindProtobuf` module gained a new + :command:`protobuf_generate_python` function to generate python + sources from ``.proto`` files. + +* The :module:`FindTIFF` module learned to search separately for + debug and release variants. + +* The :module:`FindwxWidgets` module learned to support version requests. + +* The :module:`FindXercesC` module learned to search separately for + debug and release variants. + +* The :module:`FindZLIB` module learned to search separately for + debug and release variants. + +* The :module:`GNUInstallDirs` module learned special default values + for certain installation prefixes according to the `GNU Coding + Standards`_ and the `Filesystem Hierarchy Standard`_. + +* The :module:`UseJava` module ``add_jar`` function learned + to support response files (e.g. ``@srcs.txt``) for source + specification. + +* The :module:`UseJava` module ``install_jar`` function learned + new ``DESTINATION`` and ``COMPONENT`` options to specify + the corresponding :command:`install` command options. + +* The :module:`UseJava` module gained a new ``create_javah`` + function to create C headers from Java classes. + +.. _`GNU Coding Standards`: https://www.gnu.org/prep/standards/html_node/Directory-Variables.html +.. _`Filesystem Hierarchy Standard`: https://refspecs.linuxfoundation.org/FHS_3.0/fhs/index.html + +Generator Expressions +--------------------- + +* A new ``$<SHELL_PATH:...>`` + :manual:`generator expression <cmake-generator-expressions(7)>` + has been added. + +CTest +----- + +* CTest learned to optionally measure the CPU load during parallel + testing and avoid starting tests that may cause the load to exceed + a given threshold. See the :manual:`ctest(1)` command ``--test-load`` + option, the ``TestLoad`` setting of the :ref:`CTest Test Step`, + the :variable:`CTEST_TEST_LOAD` variable, and the ``TEST_LOAD`` + option of the :command:`ctest_test` command. + +* :manual:`ctest(1)` learned options + ``--test-output-size-passed`` and ``--test-output-size-failed`` + to customize the limit on test output size submitted when + running as a :ref:`Dashboard Client`. + +CPack +----- + +* The :cpack_gen:`CPack DEB Generator` learned to set package dependencies + per component. See variables: + + * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_BREAKS` + * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONFLICTS` + * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_ENHANCES` + * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_PREDEPENDS` + * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_PROVIDES` + * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_RECOMMENDS` + * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_REPLACES` + * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_SUGGESTS` + +* The :module:`CPack` module learned to package empty directories. + +* The :module:`CPack` module gained a new setting, ``CPACK_VERBATIM_VARIABLES``, + which can be used to ensure the cpack program receives the settings' values + exactly as they were set, even if they contain CMake-special characters. + For compatibility, it's off by default. + +Other +----- + +* The :manual:`Compile Features <cmake-compile-features(7)>` functionality + is now aware of features supported by GNU C compilers on Windows. + +* CMake learned to honor ``*.manifest`` source files with MSVC tools. + Manifest files named as sources of ``.exe`` and ``.dll`` targets + will be merged with linker-generated manifests and embedded in the + binary. + +* The `Concurrent Fortran 77 <https://ccur.com>`__ compiler is now supported. + Its :variable:`compiler id <CMAKE_<LANG>_COMPILER_ID>` is ``CCur``. + +* :manual:`cmake(1)` gained a new ``--trace-expand`` command line option + that is like ``--trace`` but expands variable references in the output. + +Deprecated and Removed Features +=============================== + +* The :module:`CMakeExpandImportedTargets` module is now documented + as deprecated. See module documentation for an explanation. + +* The :variable:`CMAKE_USE_RELATIVE_PATHS` variable no longer has any + effect. Previously it was partially implemented and unreliable. + +Other Changes +============= + +* The :module:`CheckFunctionExists`, :module:`CheckLibraryExists`, + :module:`CheckSymbolExists`, and :module:`FindThreads` modules learned to + work in environments where only CXX is enabled. + +* The :cpack_gen:`CPack DEB Generator` now correctly excludes symlinks + during package checksum calculation. + +* 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 + ``cpack_set_if_not_set``, which was responsible for this, is now deprecated. + +* CMake no longer links executables with flags to export symbols + unless the :prop_tgt:`ENABLE_EXPORTS` target property is set. + See policy :policy:`CMP0065`. + +* The ``SONAME`` field is no longer set for ``MODULE`` libraries + created with the :command:`add_library` command. ``MODULE`` + libraries are meant for explicit dynamic loading at runtime. + They cannot be linked so ``SONAME`` is not useful. + +* The internal :variable:`CMAKE_<LANG>_COMPILE_OBJECT` rule variable now + substitutes compiler include flags in a separate ``<INCLUDES>`` placeholder + instead of the main ``<FLAGS>`` placeholder. diff --git a/Help/release/3.5.rst b/Help/release/3.5.rst new file mode 100644 index 0000000..58a5d4e --- /dev/null +++ b/Help/release/3.5.rst @@ -0,0 +1,187 @@ +CMake 3.5 Release Notes +*********************** + +.. only:: html + + .. contents:: + +Changes made since CMake 3.4 include the following. + +New Features +============ + +GUI +--- + +* The :manual:`cmake-gui(1)` gained options to control warnings about + deprecated functionality. + +* The :manual:`cmake-gui(1)` learned an option to set the toolset + to be used with VS IDE and Xcode generators, much like the + existing ``-T`` option to :manual:`cmake(1)`. + +* The :manual:`cmake-gui(1)` gained a Regular Expression Explorer which + may be used to create and evaluate regular expressions in real-time. + The explorer window is available via the ``Tools`` menu. + +Command-Line +------------ + +* The ``-Wdev`` and ``-Wno-dev`` :manual:`cmake(1)` options now also enable + and suppress the deprecated warnings output by default. + +* The suppression of developer warnings as errors can now be controlled with + the new ``-Werror=dev`` and ``-Wno-error=dev`` :manual:`cmake(1)` options. + +* The :manual:`cmake(1)` ``-E`` command-line tools ``copy``, + ``copy_if_different``, ``copy_directory``, and ``make_directory`` + learned to support multiple input files or directories. + +Commands +-------- + +* The :command:`cmake_parse_arguments` command is now implemented natively. + The :module:`CMakeParseArguments` module remains as an empty placeholder + for compatibility. + +* The :command:`install(DIRECTORY)` command learned to support + :manual:`generator expressions <cmake-generator-expressions(7)>` + in the list of directories. + +Variables +--------- + +* The :variable:`CMAKE_ERROR_DEPRECATED` variable can now be set using the + ``-Werror=deprecated`` and ``-Wno-error=deprecated`` :manual:`cmake(1)` + options. + +* The :variable:`CMAKE_WARN_DEPRECATED` variable can now be set using the + ``-Wdeprecated`` and ``-Wno-deprecated`` :manual:`cmake(1)` options. + +Properties +---------- + +* The :prop_tgt:`VS_GLOBAL_<variable>` target property is now implemented + for VS 2010 and above. Previously it worked only in VS 2008 and below. + +Modules +------- + +* The :module:`ExternalProject` module learned a new ``GIT_REMOTE_NAME`` + option to control the ``git clone --origin`` value. + +* The :module:`FindBoost` module now provides imported targets + such as ``Boost::boost`` and ``Boost::filesystem``. + +* The :module:`FindFLEX` module ``FLEX_TARGET`` macro learned a + new ``DEFINES_FILE`` option to specify a custom output header + to be generated. + +* The :module:`FindGTest` module now provides imported targets. + +* The :module:`FindGTK2` module, when ``GTK2_USE_IMPORTED_TARGETS`` is + enabled, now sets ``GTK2_LIBRARIES`` to contain the list of imported + targets instead of the paths to the libraries. Moreover it now sets + a new ``GTK2_TARGETS`` variable containing all the targets imported. + +* The :module:`FindOpenMP` module learned to support Clang. + +* The :module:`FindOpenSSL` module gained a new + ``OPENSSL_MSVC_STATIC_RT`` option to search for libraries using + the MSVC static runtime. + +* The :module:`FindPNG` module now provides imported targets. + +* The :module:`FindTIFF` module now provides imported targets. + +* A :module:`FindXalanC` module was introduced to find the + Apache Xalan-C++ XSL transform processing library. + +* The :module:`FindXercesC` module now provides imported targets. + +Platforms +--------- + +* Support was added for the ARM Compiler (arm.com) with compiler id ``ARMCC``. + +* A new platform file for cross-compiling in the Cray Linux Environment to + target compute nodes was added. See + :ref:`Cross Compiling for the Cray Linux Environment <Cray Cross-Compile>` + for usage details. + +* The :manual:`Compile Features <cmake-compile-features(7)>` functionality + is now aware of features supported by Clang compilers on Windows (MinGW). + +* When building for embedded Apple platforms like iOS CMake learned to build and + install combined targets which contain both a device and a simulator build. + This behavior can be enabled by setting the :prop_tgt:`IOS_INSTALL_COMBINED` + target property. + +CPack +----- + +* 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 :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 :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 :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 :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 :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`. + +Other +----- + +* Warnings about deprecated functionality are now enabled by default. + They may be suppressed with ``-Wno-deprecated`` or by setting the + :variable:`CMAKE_WARN_DEPRECATED` variable to false. + +Deprecated and Removed Features +=============================== + +* The :manual:`cmake(1)` ``-E time`` command now properly passes arguments + with spaces or special characters through to the child process. This + may break scripts that worked around the bug with their own extra + quoting or escaping. + +* The :generator:`Xcode` generator was fixed to escape backslashes in + strings consistently with other generators. Projects that previously + worked around the inconsistecy with an extra level of backslashes + conditioned on the Xcode generator must be updated to remove the + workaround for CMake 3.5 and greater. + +Other Changes +============= + +* The :generator:`Visual Studio 14 2015` generator learned to map the + ``/debug:fastlink`` linker flag to the ``.vcxproj`` file property. + +* The :module:`FindGTK2` module now configures the ``GTK2::sigc++`` imported + target to enable c++11 on its dependents when using sigc++ 2.5.1 or higher. + +* The precompiled Windows binary provided on ``cmake.org`` is now a + ``.msi`` package instead of an installer executable. One may need + to manually uninstall CMake versions lower than 3.5 before installing + the new package. diff --git a/Help/release/3.6.rst b/Help/release/3.6.rst new file mode 100644 index 0000000..f0add07 --- /dev/null +++ b/Help/release/3.6.rst @@ -0,0 +1,318 @@ +CMake 3.6 Release Notes +*********************** + +.. only:: html + + .. contents:: + +Changes made since CMake 3.5 include the following. + +New Features +============ + +Generators +---------- + +* The :generator:`Ninja` generator learned to produce phony targets + of the form ``sub/dir/all`` to drive the build of a subdirectory. + This is equivalent to ``cd sub/dir; make all`` with + :ref:`Makefile Generators`. + +* The :generator:`Ninja` generator now includes system header files in build + dependencies to ensure correct re-builds when system packages are updated. + +* The :generator:`Visual Studio 14 2015` generator learned to support the + Clang/C2 toolsets, e.g. with the ``-T v140_clang_3_7`` option. + This feature is experimental. + +Commands +-------- + +* The :command:`add_custom_command` and :command:`add_custom_target` commands + learned how to use the :prop_tgt:`CROSSCOMPILING_EMULATOR` executable + target property. + +* The :command:`install` command learned a new ``EXCLUDE_FROM_ALL`` option + to leave installation rules out of the default installation. + +* The :command:`list` command gained a ``FILTER`` sub-command to filter + list elements by regular expression. + +* The :command:`string(TIMESTAMP)` and :command:`file(TIMESTAMP)` + commands gained support for the ``%s`` placeholder. This is + the number of seconds since the UNIX Epoch. + +Variables +--------- + +* A :variable:`CMAKE_DEPENDS_IN_PROJECT_ONLY` variable was introduced + to tell :ref:`Makefile Generators` to limit dependency scanning only + to files in the project source and build trees. + +* A new :variable:`CMAKE_HOST_SOLARIS` variable was introduced to + indicate when CMake is running on an Oracle Solaris host. + +* A :variable:`CMAKE_<LANG>_STANDARD_INCLUDE_DIRECTORIES` variable was + added for use by toolchain files to specify system include directories + to be appended to all compiler command lines. + +* The :variable:`CMAKE_<LANG>_STANDARD_LIBRARIES` variable is now documented. + It is intended for use by toolchain files to specify system libraries to be + added to all linker command lines. + +* A :variable:`CMAKE_NINJA_OUTPUT_PATH_PREFIX` variable was introduced + to tell the :generator:`Ninja` generator to configure the generated + ``build.ninja`` file for use as a ``subninja``. + +* A :variable:`CMAKE_TRY_COMPILE_PLATFORM_VARIABLES` variable was + added for use by toolchain files to specify platform-specific + variables that must be propagated by the :command:`try_compile` + command into test projects. + +* A :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable was added + to optionally tell the :command:`try_compile` command to build + a static library instead of an executable. This is useful for + cross-compiling toolchains that cannot link binaries without + custom flags or scripts. + +Properties +---------- + +* A :prop_tgt:`DEPLOYMENT_REMOTE_DIRECTORY` target property was introduced + to tell the :generator:`Visual Studio 9 2008` and + :generator:`Visual Studio 8 2005` generators to generate the "remote + directory" for WinCE project deployment and debugger settings. + +* A :prop_tgt:`<LANG>_CLANG_TIDY` target property and supporting + :variable:`CMAKE_<LANG>_CLANG_TIDY` variable were introduced to tell the + :ref:`Makefile Generators` and the :generator:`Ninja` generator to run + ``clang-tidy`` along with the compiler for ``C`` and ``CXX`` languages. + +* A :prop_test:`TIMEOUT_AFTER_MATCH` test property was introduced to + optionally tell CTest to enforce a secondary timeout after matching + certain output from a test. + +* A :prop_tgt:`VS_CONFIGURATION_TYPE` target property was introduced + to specify a custom project file type for :ref:`Visual Studio Generators` + supporting VS 2010 and above. + +* A :prop_dir:`VS_STARTUP_PROJECT` directory property was introduced + to specify for :ref:`Visual Studio Generators` the default startup + project for generated solutions (``.sln`` files). + +Modules +------- + +* The :module:`CMakePushCheckState` module now pushes/pops/resets the variable + ``CMAKE_EXTRA_INCLUDE_FILE`` used in :module:`CheckTypeSize`. + +* The :module:`ExternalProject` module leared the ``GIT_SHALLOW 1`` + option to perform a shallow clone of a Git repository. + +* 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 initialized and + updated. + +* The :module:`ExternalProject` module leared the ``DOWNLOAD_NO_EXTRACT 1`` + argument to skip extracting the file that is downloaded (e.g., for + self-extracting shell installers or ``.msi`` files). + +* The :module:`ExternalProject` module now uses ``TLS_VERIFY`` when fetching + from git repositories. + +* The :module:`FindBLAS` and :module:`FindLAPACK` modules learned to + support `OpenBLAS <http://www.openblas.net>`__. + +* The :module:`FindCUDA` module learned to find the ``cublas_device`` library. + +* The :module:`FindGTest` module ``gtest_add_tests`` function now causes + CMake to automatically re-run when test sources change so that they + can be re-scanned. + +* The :module:`FindLTTngUST` module was introduced to find the LTTng-UST + library. + +* The :module:`FindPkgConfig` module learned to optionally create imported + targets for the libraries it has found. + +* The :module:`FindProtobuf` module learned to provide a ``Protobuf_VERSION`` + variable and check the version number requested in a :command:`find_package` + call. + +* The :module:`InstallRequiredSystemLibraries` module learned a new + ``CMAKE_INSTALL_UCRT_LIBRARIES`` option to enable app-local deployment + of the Windows Universal CRT libraries with Visual Studio 2015. + +Platforms +--------- + +* The Clang compiler is now supported on CYGWIN. + +* Support was added for the Bruce C Compiler with compiler id ``Bruce``. + +CTest +----- + +* The :command:`ctest_update` command now looks at the + :variable:`CTEST_GIT_INIT_SUBMODULES` variable to determine whether + submodules should be updated or not before updating. + +* The :command:`ctest_update` command will now synchronize submodules on an + update. Updates which add submodules or change a submodule's URL will now be + pulled properly. + +CPack +----- + +* 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 :cpack_gen:`CPack DEB Generator` learned how to generate + ``DEBIAN/shlibs`` contorl file when package contains shared libraries. + +* 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 :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 :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 + + For backward compatibility this feature is disabled by default. See + :variable:`CPACK_DEBIAN_FILE_NAME` and + :variable:`CPACK_DEBIAN_<COMPONENT>_FILE_NAME`. + +* 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 :cpack_gen:`CPack DEB Generator` learned how to set the package + architecture per-component. + See :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_ARCHITECTURE`. + +* 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 :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 :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 :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 :cpack_gen:`CPack RPM Generator` learned how to correctly handle symlinks + that are pointing outside generated packages. + +Other +----- + +* The :manual:`Compile Features <cmake-compile-features(7)>` functionality + is now aware of features supported by Intel C++ compilers versions 12.1 + through 16.0 on UNIX platforms. + +Deprecated and Removed Features +=============================== + +* The :module:`CMakeForceCompiler` module and its macros are now deprecated. + See module documentation for an explanation. + +* The :command:`find_library`, :command:`find_path`, and :command:`find_file` + commands no longer search in installation prefixes derived from the ``PATH`` + environment variable on non-Windows platforms. This behavior was added in + CMake 3.3 to support Windows hosts but has proven problematic on UNIX hosts. + 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:`semicolon-separated list <CMake Language Lists>` of prefixes that are + to be searched. + +* The :generator:`Visual Studio 7 .NET 2003` generator is now + deprecated and will be removed in a future version of CMake. + +* The :generator:`Visual Studio 7` generator (for VS .NET 2002) has been + removed. It had been deprecated since CMake 3.3. + +* The :generator:`Visual Studio 6` generator has been removed. + It had been deprecated since CMake 3.3. + +Other Changes +============= + +* The precompiled OS X binary provided on ``cmake.org`` now requires + OS X 10.7 or newer. + +* On Linux and FreeBSD platforms, when building CMake itself from source and + not using a system-provided libcurl, OpenSSL is now used by default if it is + found on the system. This enables SSL/TLS support for commands supporting + network communication via ``https``, such as :command:`file(DOWNLOAD)`, + :command:`file(UPLOAD)`, and :command:`ctest_submit`. + +* The :manual:`cmake(1)` ``--build`` command-line tool now rejects multiple + ``--target`` options with an error instead of silently ignoring all but the + last one. + +* :prop_tgt:`AUTOMOC` now diagnoses name collisions when multiple source + files in different directories use ``#include <moc_foo.cpp>`` with the + same name (because the generated ``moc_foo.cpp`` files would collide). + +* The :module:`FindBISON` module ``BISON_TARGET`` macro now supports + special characters by passing the ``VERBATIM`` option to internal + :command:`add_custom_command` calls. This may break clients that + added escaping manually to work around the bug. + +* The :module:`FindFLEX` module ``FLEX_TARGET`` macro now supports + special characters by passing the ``VERBATIM`` option to internal + :command:`add_custom_command` calls. This may break clients that + added escaping manually to work around the bug. + +* The :module:`FindProtobuf` module input and output variables were all renamed + from ``PROTOBUF_`` to ``Protobuf_`` for consistency with other find modules. + Input variables of the old case will be honored if provided, and output + variables of the old case are always provided. + +* 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 + it expected ``CPACK_RPM_foo_PACKAGE_NAME``. + Upper cased component name part in variables is compatible + with convention used for other CPack variables. + For back compatibility old format of variables is still valid + and preferred if both versions of variable are set, but the + preferred future use is upper cased component names in variables. + New variables that will be added to CPackRPM in later versions + will only support upper cased component variable format. + +* The CPack NSIS generator's configuration file template was fixed to + quote the path to the uninstaller tool used by the + :variable:`CPACK_NSIS_ENABLE_UNINSTALL_BEFORE_INSTALL` option. + This avoids depending on an insecure Windows feature to run an + uninstaller tool with a space in the path. diff --git a/Help/release/3.7.rst b/Help/release/3.7.rst new file mode 100644 index 0000000..345c056 --- /dev/null +++ b/Help/release/3.7.rst @@ -0,0 +1,319 @@ +CMake 3.7 Release Notes +*********************** + +.. only:: html + + .. contents:: + +Changes made since CMake 3.6 include the following. + +New Features +============ + +Platforms +--------- + +* CMake now supports :ref:`Cross Compiling for Android` with simple + toolchain files. + +* The Clang compiler is now supported on AIX. + +Generators +---------- + +* The :generator:`Ninja` generator learned to conditionally support + Fortran when using a ``ninja`` tool that has the necessary features. + See generator documentation for details. + +* The :generator:`Ninja` generator learned to produce phony targets + of the form ``sub/dir/{test,install,package}`` to drive the build + of a subdirectory installation, test or packaging target. + This is equivalent to ``cd sub/dir; make {test,install,package}`` + with :ref:`Makefile Generators`. + +* The :generator:`Visual Studio 15 2017` generator was added. This is + experimental and based on "Visual Studio 2017 RC" because this version + of VS has not been released. + +* :ref:`Visual Studio Generators` for VS 2010 and above learned to + place ``.natvis`` source files into VS project files properly. + +* The :generator:`Xcode` generator's rudimentary Swift language support + learned to honor a new :variable:`CMAKE_Swift_LANGUAGE_VERSION` variable + to tell Xcode what version of Swift is used by the source. + +* The :generator:`CodeLite` generator gained a new + :variable:`CMAKE_CODELITE_USE_TARGETS` option + to change project creation from projects to targets. + +Commands +-------- + +* The :command:`add_custom_command` command gained a new ``DEPFILE`` + option that works with the :generator:`Ninja` generator to provide + implicit dependency information to the build tool. + +* The :command:`cmake_parse_arguments` command gained a new ``PARSE_ARGV`` + mode to read arguments directly from ``ARGC`` and ``ARGV#`` + variables inside a :command:`function` body. + +* The :command:`export` command gained an ``ANDROID_MK`` option + to generate ``Android.mk`` files referencing CMake-built + libraries as prebuilts for the Android NDK build system. + +* The :command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands gained + ``HTTPHEADER <HTTP-header>`` and ``USERPWD <username>:<password>`` options. + +* The :command:`find_library` and :command:`find_package` commands learned + to search in ``lib32/`` directories when the build targets a 32-bit + architecture. See the :prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS` global + property. + +* The :command:`find_package` command gained the possibility of + sorting compatible libraries by ``NAME`` or by ``NATURAL`` sorting by + setting the two new variables :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` + and :variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION`. + +* The :command:`if` command gained new boolean comparison operations + ``LESS_EQUAL``, ``GREATER_EQUAL``, ``STRLESS_EQUAL``, ``STRGREATER_EQUAL``, + ``VERSION_LESS_EQUAL``, and ``VERSION_GREATER_EQUAL``. + +* The :command:`install` command gained an ``EXPORT_ANDROID_MK`` + subcommand to install ``Android.mk`` files referencing installed + libraries as prebuilts for the Android NDK build system. + +* The :command:`string(TIMESTAMP)` and :command:`file(TIMESTAMP)` + commands gained support for the ``%a`` and ``%b`` placeholders. + These are the abbreviated weekday and month names. + +* The :command:`try_compile` command source file signature now honors + configuration-specific flags (e.g. :variable:`CMAKE_<LANG>_FLAGS_DEBUG`) + in the generated test project. Previously only the default such flags + for the current toolchain were used. See policy :policy:`CMP0066`. + +Variables +--------- + +* Variable :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` was added to control + the sorting mode of the :command:`find_package` command. + +* Variable :variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION` was added to control + the sorting direction the :command:`find_package` command. + +* :variable:`Toolchain files <CMAKE_TOOLCHAIN_FILE>` may now set a + :variable:`CMAKE_<LANG>_FLAGS_INIT` variable to initialize the + :variable:`CMAKE_<LANG>_FLAGS` cache entry the first time a language is + enabled in a build tree. + +* :variable:`Toolchain files <CMAKE_TOOLCHAIN_FILE>` may now set + :variable:`CMAKE_EXE_LINKER_FLAGS_INIT`, + :variable:`CMAKE_SHARED_LINKER_FLAGS_INIT`, and + :variable:`CMAKE_MODULE_LINKER_FLAGS_INIT` variables to initialize the + :variable:`CMAKE_EXE_LINKER_FLAGS`, + :variable:`CMAKE_SHARED_LINKER_FLAGS`, and + :variable:`CMAKE_MODULE_LINKER_FLAGS` cache entries the first time + a language is enabled in a build tree. + +Properties +---------- + +* On Apple platforms the :prop_tgt:`BUNDLE_EXTENSION` target property + now also applies to Frameworks and App Bundles. + +* A :prop_dir:`BINARY_DIR` directory property was added to get the + absolute path to the binary directory corresponding to the source + directory on which the property is read. + +* A :prop_dir:`BUILDSYSTEM_TARGETS` directory property was added to + get the list of logical buildsystem target names added by the + project in a directory. + +* A :prop_tgt:`LINK_WHAT_YOU_USE` target property and supporting + :variable:`CMAKE_LINK_WHAT_YOU_USE` variable were introduced + to detect (on UNIX) shared libraries that are linked but not + needed by running ``ldd -r -u``. + +* A :prop_dir:`SOURCE_DIR` directory property was added to get the + absolute path to the source directory associated with a directory. + +* A :prop_dir:`SUBDIRECTORIES` directory property was added to + get the list of subdirectories added by a project in a directory. + +* A :prop_tgt:`VS_SDK_REFERENCES` target property was added to tell + :ref:`Visual Studio Generators` to reference the named SDKs. + +* A :prop_sf:`VS_TOOL_OVERRIDE` source file property was created to tell + :ref:`Visual Studio Generators` what tool to use for a source file. + +* The :prop_tgt:`WINDOWS_EXPORT_ALL_SYMBOLS` target property now applies + to executable targets with the :prop_tgt:`ENABLE_EXPORTS` property set. + +* A :prop_sf:`XCODE_FILE_ATTRIBUTES` source file property was + added to tell the :generator:`Xcode` generator to generate + custom content in the Xcode project attributes for the file. + +Modules +------- + +* An :module:`AndroidTestUtilities` module was added to manage transfer + of test data to an Android device. + +* The :module:`CheckFortranSourceCompiles` module macro + ``CHECK_Fortran_SOURCE_COMPILES`` gained a ``SRC_EXT`` option + to specify a custom test Fortran source file extension. + +* The :module:`ExternalProject` module gained ``HTTP_USERNAME`` and + ``HTTP_PASSWORD`` options to set http download credentials. + +* The :module:`ExternalProject` module gained a ``HTTP_HEADER`` + option to add http download headers. + +* The :module:`FindBISON` module ``BISON_TARGET`` macro learned a new + ``REPORT_FILE`` option to specify the bison ``--report-file=`` option. + +* The :module:`FindBZip2` module now provides imported targets. + +* A :module:`FindICU` module was introduced to find the International + Components for Unicode (ICU) libraries and programs. + +* The :module:`FindMatlab` module learned to find the SIMULINK and MAT + components. + +* The :module:`FindMatlab` module :command:`matlab_add_mex` command learned + to add executables and modules. + +* The :module:`FindMatlab` module :command:`matlab_add_unit_test` command + learned to support inline Matlab test code. + +* The :module:`FindOpenCL` module now provides imported targets. + +* The :module:`FindOpenMP` module learned to detect the OpenMP + version (specification date) from the compiler. + +* A :module:`FindVulkan` module was added. + +* The :module:`GenerateExportHeader` module learned a new + ``CUSTOM_CONTENT_FROM_VARIABLE`` option to specify a variable + containing custom content for inclusion in the generated header. + +* The :module:`GNUInstallDirs` module gained a new + :command:`GNUInstallDirs_get_absolute_install_dir` command. + +* The :module:`UseJava` module gained APIs to "export" jar targets + for use by external CMake projects. See the ``install_jar_exports`` + and ``export_jars`` functions. + +CTest +----- + +* CTest now supports test fixtures through the new :prop_test:`FIXTURES_SETUP`, + :prop_test:`FIXTURES_CLEANUP` and :prop_test:`FIXTURES_REQUIRED` test + properties. When using regular expressions or ``--rerun-failed`` to limit + the tests to be run, a fixture's setup and cleanup tests will automatically + be added to the execution set if any test requires that fixture. + +* The :command:`ctest_configure`, :command:`ctest_build`, + :command:`ctest_test`, :command:`ctest_coverage`, and :command:`ctest_upload` + commands gained a new ``CAPTURE_CMAKE_ERROR`` option to capture any errors + that occur as the commands run into a variable and avoid affecting the return + code of the :manual:`ctest(1)` process. + +CPack +----- + +* 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 :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` + +* The :module:`CPackIFW` module gained a new + :command:`cpack_ifw_add_package_resources` command to include additional + resources in the installer binary. + +* 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 additional pages to the IFW + installer. + +* 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 :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_gen:`CPack NSIS Generator` now supports + :variable:`CPACK_NSIS_<compName>_INSTALL_DIRECTORY`. + This can be used to set component specific installation directories. + +* 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_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_gen:`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_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. + +Other +----- + +* :manual:`cmake(1)` gained a ``-E capabilities`` option to provide a + machine-readable (JSON) description of the capabilities of the + cmake tool (available generators, etc.). + +* A new :manual:`cmake-server(7)` mode was added to provide semantic + information about a CMake-generated buildsystem to clients through + a JSON protocol. Currently all protocols are experimental and subject + to change. + +* The :manual:`cmake(1)` command learned a ``--trace-source=<file>`` option. + +* :manual:`ccmake(1)` learned to support vim-like navigation bindings. + +* :manual:`cmake-gui(1)` gained a button to open the generated project file + for :ref:`Visual Studio Generators` and the :generator:`Xcode` generator. + +Deprecated and Removed Features +=============================== + +* We no longer provide Linux i386 binaries for download from ``cmake.org`` + for new versions of CMake. + +* Vim support files ``cmake-indent.vim``, ``cmake-syntax.vim``, and + ``cmake-help.vim`` have been removed in favor of the files now provided + from the `vim-cmake-syntax`_ project. + +* Support for building CMake itself with some compilers was dropped: + + * Visual Studio 7.1 and 2005 -- superseded by VS 2008 and above + * MinGW.org mingw32 -- superseded by MSYS2 mingw32 and mingw64 + + CMake still supports generating build systems for other projects using + these compilers. + +Other Changes +============= + +* The Fortran dependency scanner learned to support the syntax of + `Fortran Submodules`_. + +* Vim support files ``indent/cmake.vim`` and ``syntax/cmake.vim`` + from the `vim-cmake-syntax`_ project are now distributed with CMake. + +.. _`Fortran Submodules`: http://fortranwiki.org/fortran/show/Submodules +.. _`vim-cmake-syntax`: https://github.com/pboettch/vim-cmake-syntax diff --git a/Help/release/3.8.rst b/Help/release/3.8.rst new file mode 100644 index 0000000..de51a7b --- /dev/null +++ b/Help/release/3.8.rst @@ -0,0 +1,417 @@ +CMake 3.8 Release Notes +*********************** + +.. only:: html + + .. contents:: + +Changes made since CMake 3.7 include the following. + +New Features +============ + +Languages +--------- + +C# +^^ + +* CMake learned to support ``CSharp`` (C#) as a first-class language that + can be enabled via the :command:`project` and :command:`enable_language` + commands. It is currently supported by the :ref:`Visual Studio Generators` + for VS 2010 and above. + + C# assemblies and programs can be added just like common C++ targets using + the :command:`add_library` and :command:`add_executable` commands. + References between C# targets in the same source tree may be specified by + :command:`target_link_libraries` like for C++. References to system or + 3rd-party assemblies may be specified by the target properties + :prop_tgt:`VS_DOTNET_REFERENCE_<refname>` and + :prop_tgt:`VS_DOTNET_REFERENCES`. + +* More fine tuning of C# targets may be done using target and source + file properties. Specifically the target properties related to + Visual Studio (``VS_*``) are worth a look (for setting toolset + versions, root namespaces, assembly icons, ...). + +CUDA +^^^^ + +* CMake learned to support ``CUDA`` as a first-class language that can be + enabled via the :command:`project` and :command:`enable_language` commands. + +* ``CUDA`` is currently supported by the :ref:`Makefile Generators` + and the :generator:`Ninja` generator on Linux, macOS, and Windows. + Support for the Visual Studio IDE is under development but not + included in this release. + +* The NVIDIA CUDA Toolkit compiler (``nvcc``) is supported. + +C & C++ +^^^^^^^ + +* The :manual:`Compile Features <cmake-compile-features(7)>` functionality + now offers meta-features that request compiler modes for specific language + standard levels (e.g. ``cxx_std_11``). See + :prop_gbl:`CMAKE_C_KNOWN_FEATURES` and :prop_gbl:`CMAKE_CXX_KNOWN_FEATURES`. + +* The :manual:`Compile Features <cmake-compile-features(7)>` functionality + is now aware of C++ 17. No specific features are yet enumerated besides + the ``cxx_std_17`` meta-feature. + +* The :manual:`Compile Features <cmake-compile-features(7)>` functionality + is now aware of the availability of C99 in gcc since version 3.4. + +Platforms +--------- + +* A new minimal platform file for ``Fuchsia`` was added. + +Generators +---------- + +* The :generator:`CodeBlocks` extra generator may now be used to + generate with :generator:`NMake Makefiles JOM`. + +* The :ref:`Visual Studio Generators` for VS 2013 and above learned to + support a ``host=x64`` option in the :variable:`CMAKE_GENERATOR_TOOLSET` + value (e.g. via the :manual:`cmake(1)` ``-T`` option) to request use + of a VS 64-bit toolchain on 64-bit hosts. + +* The :ref:`Visual Studio Generators` learned to treat files passed to + :command:`target_link_libraries` whose names end in ``.targets`` + as MSBuild "targets" files to be imported into generated project files. + +Commands +-------- + +* The :command:`add_custom_command` and :command:`add_custom_target` commands + learned the option ``COMMAND_EXPAND_LISTS`` which causes lists in the + ``COMMAND`` argument to be expanded, including lists created by generator + expressions. + +* The :command:`execute_process` command gained an ``ENCODING`` option to + specify on Windows which encoding is used for output from child process. + +* The :command:`math(EXPR)` command gained support for unary + ``+`` and ``-`` operators. + +* The :command:`source_group` command gained ``TREE`` and ``PREFIX`` + options to add groups following source tree directory structure. + +* The :command:`string(TIMESTAMP)` command learned to treat ``%%`` + as a way to encode plain ``%``. + +* The :command:`string(TIMESTAMP)` command will now honor the + ``SOURCE_DATE_EPOCH`` environment variable and use its value + instead of the current time. + +* The :command:`try_compile` command source file signature gained new options + to specify the language standard to use in the generated test project. + +* The :command:`try_compile` command source file signature now honors + language standard variables like :variable:`CMAKE_CXX_STANDARD`. + See policy :policy:`CMP0067`. + +Variables +--------- + +* A :variable:`CMAKE_CODELITE_USE_TARGETS` variable was added to tell the + :generator:`CodeLite` extra generator to change the generated project + to have target-centric organization. + The ``build``, ``rebuild``, and ``clean`` operations within ``CodeLite`` + then work on a selected target rather than the whole workspace. + (Note that the :generator:`Ninja` clean operation on a target + includes its dependencies, though.) + +* The :variable:`CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS` variable was added to + tell the :generator:`Sublime Text 2` extra generator to place specified + environment variables in the generated ``.sublime-project``. + +* The :variable:`CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE` variable was added + to tell the :generator:`Sublime Text 2` extra generator whether to exclude + the build tree from the ``.sublime-project`` when it is inside the source + tree. + +* A :variable:`CMAKE_VS_INCLUDE_PACKAGE_TO_DEFAULT_BUILD` variable was + added to tell :ref:`Visual Studio Generators` for VS 2010 and above + to include the ``PACKAGE`` target in the default build, similar to + the existing :variable:`CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD` + variable for the ``INSTALL`` target. + +Properties +---------- + +* A :prop_tgt:`BUILD_RPATH` target property and corresponding + :variable:`CMAKE_BUILD_RPATH` variable were added to support custom + ``RPATH`` locations to be added to binaries in the build tree. + +* The :prop_sf:`COMPILE_FLAGS` source file property learned to support + :manual:`generator expressions <cmake-generator-expressions(7)>`. + +* The :prop_tgt:`FRAMEWORK` target property may now also be applied to + static libraries on Apple targets. It will result in a proper + Framework but with a static library inside. + +* :ref:`Imported <Imported Targets>` :ref:`Interface Libraries` learned new + :prop_tgt:`IMPORTED_LIBNAME` and :prop_tgt:`IMPORTED_LIBNAME_<CONFIG>` + target properties to specify a link library name since interface libraries + do not build their own library files. + +* A :prop_tgt:`<LANG>_CPPLINT` target property and supporting + :variable:`CMAKE_<LANG>_CPPLINT` variable were introduced to tell + the :ref:`Makefile Generators` and the :generator:`Ninja` generator to + run the ``cpplint`` style checker along with the compiler for ``C`` and + ``CXX`` languages. + +* A :prop_tgt:`MANUALLY_ADDED_DEPENDENCIES` target property has been added. + It provides a read-only list of dependencies that have been added with + the :command:`add_dependencies` command. + +* The :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` target property learned + to interpret empty list elements as referring to the configuration-less + imported location specified by :prop_tgt:`IMPORTED_LOCATION`. + +* The :prop_tgt:`NO_SYSTEM_FROM_IMPORTED` target property is now supported + on :ref:`Imported <Imported Targets>` :ref:`Interface Libraries`. + +* New source file properties :prop_sf:`SKIP_AUTOMOC`, :prop_sf:`SKIP_AUTOUIC`, + :prop_sf:`SKIP_AUTORCC`, and :prop_sf:`SKIP_AUTOGEN` were added to allow + source files to be excluded from processing by :prop_tgt:`AUTOMOC`, + :prop_tgt:`AUTOUIC`, and :prop_tgt:`AUTORCC` target properties. + +* A :prop_sf:`VS_COPY_TO_OUT_DIR` source file property was added to + tell :ref:`Visual Studio Generators` for VS 2010 and above whether + or not a file should e copied to the output directory. + +* A :prop_tgt:`VS_DEBUGGER_WORKING_DIRECTORY` target property was added + to tell :ref:`Visual Studio Generators` for VS 2010 and above what + debugger working directory should be set for the target. + +* A :prop_tgt:`VS_DOTNET_REFERENCES_COPY_LOCAL` target property was added + to specify whether to copy referenced assemblies to the output directory. + +* A :prop_tgt:`VS_DOTNET_REFERENCE_<refname>` target property was added + to tell :ref:`Visual Studio Generators` for VS 2010 and above to add + a .NET reference with a given hint path. + +* A :prop_sf:`VS_INCLUDE_IN_VSIX` source file property was added to + tell :ref:`Visual Studio Generators` for VS 2010 and above whether + to include the file in a Visual Studio extension package. + +* A :prop_sf:`VS_RESOURCE_GENERATOR` source file property was added to + give :ref:`Visual Studio Generators` for VS 2010 and above a setting + for the resource generator (``C#`` only). + +* A :prop_tgt:`VS_USER_PROPS` target property was added to tell + :ref:`Visual Studio Generators` for VS 2010 and above to use a + custom MSBuild user ``.props`` file. + +* A :prop_gbl:`XCODE_EMIT_EFFECTIVE_PLATFORM_NAME` global property was + added to tell the :generator:`Xcode` generator whether to emit the + ``EFFECTIVE_PLATFORM_NAME`` variable. This is useful when building + with multiple SDKs like ``macosx`` and ``iphoneos`` in parallel. + +* New :prop_tgt:`XCODE_PRODUCT_TYPE` and :prop_tgt:`XCODE_EXPLICIT_FILE_TYPE` + target properties were created to tell the :generator:`Xcode` generator + to use custom values of the corresponding attributes for a target in the + generated Xcode project. + +Modules +------- + +* A :module:`CSharpUtilities` module was added to aid parameterization of + Visual Studio C# targets. It provides functions to allow automated + setting of source file properties to support Windows Forms, WPF/XAML or + other technologies as needed. + +* The :module:`ExternalData` module learned to support multiple + content links for one data file using different hashes, e.g. + ``img.png.sha256`` and ``img.png.sha1``. This allows objects + to be fetched from sources indexed by different hash algorithms. + +* The :module:`ExternalProject` module gained the ``GIT_PROGRESS`` option to + force Git to show progress when cloning repositories. + +* The :module:`ExternalProject` module gained a ``GIT_CONFIG`` option + to pass ``--config`` options to Git when cloning repositories. + +* The :module:`FeatureSummary` module :command:`feature_summary` command now + accepts a new ``QUIET_ON_EMPTY`` option that suppresses the output when + the list of packages that belong to the selected category is empty. + +* The :module:`FeatureSummary` module :command:`add_feature_info` command + now accepts lists of dependencies for deciding whether a feature is enabled + or not. + +* The package types accepted by the :module:`FeatureSummary` module can now + be tweaked by changing the :variable:`FeatureSummary_PKG_TYPES`, + :variable:`FeatureSummary_REQUIRED_PKG_TYPES` and + :variable:`FeatureSummary_DEFAULT_PKG_TYPE` global properties. + +* The :module:`FindOpenGL` module now provides imported targets + ``OpenGL::GL`` and ``OpenGL::GLU`` when the libraries are found. + +* The :module:`UseSWIG` module gained a ``swig_add_library`` command + to give more flexibility over the old ``swig_add_module`` command. + +* The :module:`UseSWIG` module ``swig_add_source_to_module`` command + learned a new ``SWIG_OUTFILE_DIR`` option to control the output + file location (``swig -o``). + +* The :module:`WriteCompilerDetectionHeader` module gained the + ``ALLOW_UNKNOWN_COMPILERS`` and ``ALLOW_UNKNOWN_COMPILER_VERSIONS`` options + that allow creation of headers that will work also with unknown or old + compilers by simply assuming they do not support any of the requested + features. + +CTest +----- + +* The :command:`ctest_memcheck` command gained a ``DEFECT_COUNT <var>`` + option to capture the number of memory defects detected. + +* The :command:`ctest_memcheck` command learned to read the location of + suppressions files for sanitizers from the + :variable:`CTEST_MEMORYCHECK_SUPPRESSIONS_FILE` variable. + +* The :command:`ctest_memcheck` command learned to support ``LeakSanitizer`` + independently from ``AddressSanitizer``. + +* The :command:`ctest_update` command ``CDASH_UPLOAD`` signature was taught + to honor the ``RETRY_COUNT``, ``RETRY_DELAY``, and ``QUIET`` options. + +CPack +----- + +* The :module:`CPackIFWConfigureFile` module was added to define a new + :command:`cpack_ifw_configure_file` command to configure file templates + prepared in QtIFW/SDK/Creator style. + +* The :module:`CPackIFW` module :command:`cpack_ifw_configure_component` and + :command:`cpack_ifw_configure_component_group` commands gained a new + ``DEFAULT``, ``VIRTUAL``, ``FORCED_INSTALLATION``, ``REQUIRES_ADMIN_RIGHTS``, + ``DISPLAY_NAME``, ``UPDATE_TEXT``, ``DESCRIPTION``, ``RELEASE_DATE``, + ``AUTO_DEPEND_ON`` and ``TRANSLATIONS`` options to more specific + configuration. + +* The :module:`CPackIFW` module :command:`cpack_ifw_configure_component` + command gained a new ``DEPENDENCIES`` alias for ``DEPENDS`` option. + +* The :module:`CPackIFW` module :command:`cpack_ifw_configure_component_group` + command gained a new ``DEPENDS`` option. The ``DEPENDENCIES`` alias also + added. + +* The :module:`CPackIFW` module :command:`cpack_ifw_configure_component` and + :command:`cpack_ifw_configure_component_group` commands ``PRIORITY`` + option now is deprecated and will be removed in a future version of CMake. + Please use new ``SORTING_PRIORITY`` option instead. + +* The :cpack_gen:`CPack IFW Generator` gained new + :variable:`CPACK_IFW_PACKAGE_WATERMARK`, + :variable:`CPACK_IFW_PACKAGE_BANNER`, + :variable:`CPACK_IFW_PACKAGE_BACKGROUND`, + :variable:`CPACK_IFW_PACKAGE_WIZARD_STYLE`, + :variable:`CPACK_IFW_PACKAGE_WIZARD_DEFAULT_WIDTH`, + :variable:`CPACK_IFW_PACKAGE_WIZARD_DEFAULT_HEIGHT`, and + :variable:`CPACK_IFW_PACKAGE_TITLE_COLOR` + variables to customize a QtIFW installer look. + +* 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 :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 :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 :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 :cpack_gen:`CPack RPM Generator` learned to support + multiple directives per file when using + :variable:`CPACK_RPM_USER_FILELIST` variable. + +Other +----- + +* CMake functionality using cryptographic hashes now supports SHA-3 algorithms. + +* A new generator expression ``$<IF:cond,true-value,false-value>`` was added. + It resolves to the true-value if the condition is ``1`` and resolves to + the false-value if the condition is ``0``. + +Deprecated and Removed Features +=============================== + +* The :module:`FeatureSummary` module commands :command:`set_package_info`, + :command:`set_feature_info`, :command:`print_enabled_features`, and + :command:`print_disabled_features` are now deprecated. + +* The :module:`UseSWIG` module ``swig_add_module`` command is now + deprecated in favor of ``swig_add_library``. + +Other Changes +============= + +* If a command specified by the :prop_tgt:`<LANG>_CLANG_TIDY` target property + returns non-zero at build time this is now treated as an error instead of + silently ignored. + +* The :command:`ctest_memcheck` command no longer automatically adds + ``leak_check=1`` to the options used by ``AddressSanitizer``. The default + behavior of ``AddressSanitizer`` is to run `LeakSanitizer` to check leaks + unless ``leak_check=0``. + +* The :command:`ctest_memcheck` command was fixed to correctly append extra + sanitizer options read from the + :variable:`CTEST_MEMORYCHECK_SANITIZER_OPTIONS` variable to the environment + variables used internally by the sanitizers. + +* The :module:`FeatureSummary` module :command:`set_package_properties` + command no longer forces the package type to ``OPTIONAL`` when the type + is not explicitly set. + +* The :manual:`Compile Features <cmake-compile-features(7)>` functionality + is now aware of features supported by Intel C++ compilers versions 12.1 + through 17.0 on UNIX and Windows platforms. + +* Calls to the :module:`FindPkgConfig` module :command:`pkg_check_modules` + command following a successful call learned to re-evaluate the cached values + for a given prefix after changes to the parameters to the command for that + prefix. + +* When using :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC`, generated + ``moc_*``, ``*.moc`` and ``ui_*`` are placed in the + ``<CMAKE_CURRENT_BINARY_DIR>/<TARGETNAME>_autogen/include`` directory which + is automatically added to the target's :prop_tgt:`INCLUDE_DIRECTORIES`. + It is therefore not necessary anymore to have + :variable:`CMAKE_CURRENT_BINARY_DIR` in the target's + :prop_tgt:`INCLUDE_DIRECTORIES`. + +* The :generator:`Sublime Text 2` generator no longer runs the native + build command (e.g. ``ninja`` or ``make``) with verbose build output + enabled. + +* The :command:`try_compile` command source file signature now + honors the :variable:`CMAKE_WARN_DEPRECATED` variable value + in the generated test project. + +* The :ref:`Visual Studio Generators` for VS 2010 and above now place + per-source file flags after target-wide flags when they are classified + as raw flags with no project file setting (``AdditionalOptions``). + This behavior is more consistent with the ordering of flags produced + by other generators, and allows flags on more-specific properties + (per-source) to override those on more general ones (per-target). + +* The precompiled Windows binary MSI package provided on ``cmake.org`` now + records the installation directory in the Windows Registry under the key + ``HKLM\Software\Kitware\CMake`` with a value named ``InstallDir``. diff --git a/Help/release/3.9.rst b/Help/release/3.9.rst new file mode 100644 index 0000000..89da627 --- /dev/null +++ b/Help/release/3.9.rst @@ -0,0 +1,343 @@ +CMake 3.9 Release Notes +*********************** + +.. only:: html + + .. contents:: + +Changes made since CMake 3.8 include the following. + +New Features +============ + +Languages +--------- + +* ``CUDA`` is now supported by the :ref:`Visual Studio Generators` + for VS 2010 and above. This complements the existing support by the + :ref:`Makefile Generators` and the :generator:`Ninja` generator. + CUDA 8.0.61 or higher is recommended due to known bugs in the VS + integration by earlier versions. + +* CMake is now aware of the :prop_tgt:`C++ standards <CXX_STANDARD>` and + :prop_tgt:`C standards <C_STANDARD>` and their associated meta-features for + the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>`: ``Cray``, + ``PGI``, and ``XL``. + +Generators +---------- + +* :ref:`Visual Studio Generators` for VS 2010 and above learned to support + the ``ASM_NASM`` language when ``nasm`` is installed. + +* The :generator:`Xcode` generator learned to create Xcode schema files. + This is an experimental feature and can be activated by setting the + :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable to a ``TRUE`` value. + +Commands +-------- + +* The :command:`add_library` command ``IMPORTED`` option learned to support + :ref:`Object Libraries`. + +* The :command:`find_library` command learned to search ``libx32`` paths + when the build targets the ``x32`` ABI. See the + :prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS` global property. + +* The :command:`include_external_msproject` command learned to use + the :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` target property + to map current configurations to the external configurations. + +* The :command:`install(TARGETS)` command learned a new ``OBJECTS`` option to + specify where to install :ref:`Object Libraries`. + +* The :command:`install(EXPORT)` command learned how to export + :ref:`Object Libraries`. + +* The :command:`project` command learned an optional ``DESCRIPTION`` + parameter to set the :variable:`PROJECT_DESCRIPTION` variable. + +* The :command:`separate_arguments` command gained a ``NATIVE_COMMAND`` mode + that performs argument separation depending on the host operating system. + +Variables +--------- + +* A :variable:`CMAKE_ANDROID_NDK_DEPRECATED_HEADERS` variable was added + for use when :ref:`Cross Compiling for Android with the NDK` to request + use of the deprecated headers even when unified headers are available. + The default is now to use unified headers if available. + +* A :variable:`CMAKE_AUTOMOC_DEPEND_FILTERS` variable was introduced to + allow :variable:`CMAKE_AUTOMOC` to extract additional dependency file names + for ``moc`` from the contents of source files. + +* A :variable:`CMAKE_AUTOUIC_SEARCH_PATHS` variable was introduced to + allow :variable:`CMAKE_AUTOUIC` to search for ``foo.ui`` in more + places than the vicinity of the file including ``ui_foo.h``. + +* A :variable:`CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX` variable was added to + tell the :command:`find_library` command to search in a ``lib<suffix>`` + directory before each ``lib`` directory that would normally be searched. + +* A :variable:`CMAKE_INTERPROCEDURAL_OPTIMIZATION` variable was added to + initialize the :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` property on all + targets. + +* A :variable:`CMAKE_<LANG>_COMPILER_AR` variable was added to hold + the path to the GCC/Clang wrapper of ``ar``. + +* A :variable:`CMAKE_<LANG>_COMPILER_RANLIB` variable was added to hold + the path to the GCC/Clang wrapper of ``ranlib``. + +* The :variable:`CMAKE_SYSROOT_COMPILE` and :variable:`CMAKE_SYSROOT_LINK` + variables were added to use separate sysroots for compiling and linking. + +Properties +---------- + +* A new :prop_tgt:`AUTOGEN_BUILD_DIR` target property was introduced to set + a custom output directory for :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTOUIC`, + and :prop_tgt:`AUTORCC`. + +* A new :prop_tgt:`AUTOMOC_DEPEND_FILTERS` target property was introduced to + allow :prop_tgt:`AUTOMOC` to extract additional dependency file names + for ``moc`` from the contents of source files. + +* A new :prop_tgt:`AUTOUIC_SEARCH_PATHS` target property was introduced to + allow :prop_tgt:`AUTOUIC` to search for ``foo.ui`` in more + places than the vicinity of the file including ``ui_foo.h``. + +* Global properties :prop_gbl:`AUTOGEN_SOURCE_GROUP`, + :prop_gbl:`AUTOMOC_SOURCE_GROUP` and + :prop_gbl:`AUTORCC_SOURCE_GROUP` were + introduced to allow files generated by :prop_tgt:`AUTOMOC` or + :prop_tgt:`AUTORCC` to be placed in a :command:`source_group`. + +* A :prop_tgt:`BUILD_WITH_INSTALL_NAME_DIR` target property and corresponding + :variable:`CMAKE_BUILD_WITH_INSTALL_NAME_DIR` variable were added to + control whether to use the :prop_tgt:`INSTALL_NAME_DIR` target property + value for binaries in the build tree. This is for macOS ``install_name`` + as :prop_tgt:`BUILD_WITH_INSTALL_RPATH` is for ``RPATH``. + +* A :prop_tgt:`CUDA_PTX_COMPILATION` target property was added to + :ref:`Object Libraries` to support compiling to ``.ptx`` files + instead of host object files. + +* A :prop_gbl:`GENERATOR_IS_MULTI_CONFIG` global property was + added to determine whether the current generator is a multi-configuration + generator (such as :ref:`Visual Studio Generators` or :generator:`Xcode`). + +* The :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property is now enforced + when enabled. CMake will add IPO flags unconditionally or produce an error + if it does not know the flags for the current compiler. The project is now + responsible to use the :module:`CheckIPOSupported` module to check for IPO + support before enabling the target property. See policy :policy:`CMP0069`. + +* The :prop_tgt:`WINDOWS_EXPORT_ALL_SYMBOLS` target property may now + be used in combination with explicit ``.def`` files in order to + export all symbols from the object files within a target plus + an explicit list of symbols that the linker finds in dependencies + (e.g. ``msvcrt.lib``). + +Modules +------- + +* A :module:`CheckIPOSupported` module was added to help projects + check whether interprocedural optimization (IPO) is supported by + the current toolchain and CMake version. + +* 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 :command:`find_package` accepts. + +* The :module:`FeatureSummary` module :command:`feature_summary` command now + accepts the new ``DEFAULT_DESCRIPTION`` option that will print the default + title for the selected package type. + +* The :module:`FeatureSummary` module gained a new + :variable:`FeatureSummary_<TYPE>_DESCRIPTION` variable that can be defined + for each ``<TYPE>`` to replace the type name with the specified string + whenever the package type is used in an output string by the module. + +* The :module:`FindDoxygen` module learned to control Doxygen behavior using + CMake variables and generate documentation via the newly added + :command:`doxygen_add_docs` function. The Doxygen input file (``Doxyfile``) + is automatically generated and doxygen is run as part of a custom target. + Additional components can be specified to find optional tools: ``dot``, + ``mscgen`` and ``dia``. + +* The :module:`FindMPI` module now provides imported targets. + +* The :module:`FindProtobuf` module :command:`protobuf_generate_cpp` + command gained an ``EXPORT_MACRO`` option to specify the name of + a DLL export markup macro. + +* The :module:`FindProtobuf` module now supports usage of static libraries + for Unix via a new ``Protobuf_USE_STATIC_LIBS`` input variable. + +* The :module:`FindProtobuf` module now provides imported targets + when the libraries are found. + +* A new :module:`GoogleTest` module was added to provide the + :command:`gtest_add_tests` function independently of the :module:`FindGTest` + module. The function was also updated to support keyword arguments, with + functionality expanded to allow a test name prefix and suffix to be + specified, the dependency on the source files to be optional and the list of + discovered test cases to be returned to the caller. + +CTest +----- + +* The :command:`ctest_submit` command gained a ``HTTPHEADER`` option + to specify custom headers to send during submission. + +* The :manual:`ctest(1)` executable gained new options which allow the + developer to disable automatically adding tests to the test set to satisfy + fixture dependencies. ``-FS`` prevents adding setup tests for fixtures + matching the provided regular expression, ``-FC`` prevents adding cleanup + tests for matching fixtures and ``-FA`` prevents adding any test for matching + fixtures. + +* A :prop_test:`DISABLED` test property was added to mark tests that + are configured but explicitly disabled so they do not run. + +CPack +----- + +* 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`. + +* The :module:`CPackComponent` module :command:`cpack_add_component` command + gained a new ``PLIST <filename>`` option to specify the ``pkgbuild`` + ``--component-plist`` argument when using the + :module:`productbuild <CPackProductBuild>` generator. + +* The :module:`CPackIFW` module :command:`cpack_ifw_configure_component` and + :command:`cpack_ifw_configure_component_group` commands gained + internationalization support for ``DISPLAY_NAME`` and ``DESCRIPTION`` + options. + +* 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 :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 :cpack_gen:`CPack RPM Generator` learned to modify the ``debuginfo`` + package name. See the :variable:`CPACK_RPM_DEBUGINFO_FILE_NAME` variable. + +* 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_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``. + +Other +----- + +* Interprocedural optimization (IPO) is now supported for GNU and Clang + compilers using link time optimization (LTO) flags. See the + :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property and + :module:`CheckIPOSupported` module. + +* The ``TARGET_OBJECTS`` + :manual:`generator expression <cmake-generator-expressions(7)>` + is now supported by the :command:`add_custom_command` and + :command:`file(GENERATE)` commands. + +* Two new informational generator expressions to retrieve Apple Bundle + directories have been added. The first one ``$<TARGET_BUNDLE_DIR:tgt>`` + outputs the full path to the Bundle directory, the other one + ``$<TARGET_BUNDLE_CONTENT_DIR:tgt>`` outputs the full path to the + ``Contents`` directory of macOS Bundles and App Bundles. For all other + bundle types and SDKs it is identical with ``$<TARGET_BUNDLE_DIR:tgt>``. + The new expressions are helpful to query Bundle locations independent of + the different Bundle types and layouts on macOS and iOS. + +Deprecated and Removed Features +=============================== + +* An explicit deprecation diagnostic was added for policies ``CMP0036`` + and below. The :manual:`cmake-policies(7)` manual explains that the + OLD behaviors of all policies are deprecated and that projects should + always port to the NEW behaviors as soon as possible. + +* The :generator:`Visual Studio 8 2005` generator is now deprecated + and will be removed in a future version of CMake. + +* The :generator:`Visual Studio 7 .NET 2003` generator has been removed. + +* The :generator:`Xcode` generator dropped support for Xcode versions + older than 3. + +* The :module:`FindDoxygen` module has deprecated several variables. + +* The version of curl bundled with CMake no longer accepts URLs of the form + ``file://c:/...`` on Windows due to a change in upstream curl 7.52. Use + the form ``file:///c:/...`` instead to work on all versions. + +Other Changes +============= + +* When using :prop_tgt:`AUTOMOC`, CMake now scans for the presence of the + ``Q_PLUGIN_METADATA`` macro and reruns moc when the file from the + macro's ``FILE`` argument changes. + +* When :prop_tgt:`AUTOMOC` detects an include statement of the form + ``#include "moc_<basename>.cpp"`` the search for the respective header file + now looks in the :prop_tgt:`INCLUDE_DIRECTORIES` of the target as well. + +* When running tests, CTest learned to treat skipped tests (using the + :prop_test:`SKIP_RETURN_CODE` property) the same as tests with the new + :prop_test:`DISABLED` property. Due to this change, CTest will not indicate + failure when all tests are either skipped or pass. + +* The :generator:`Ninja` generator has loosened the dependencies of object + compilation. Object compilation now depends only on custom targets + and custom commands associated with libraries on which the object's target + depends and no longer depends on the libraries themselves. Source files + in dependent targets may now compile without waiting for their targets' + dependencies to link. + +* On macOS, ``RPATH`` settings such as :prop_tgt:`BUILD_WITH_INSTALL_RPATH` + no longer affect the ``install_name`` field. See policy :policy:`CMP0068`. + +* The :generator:`Visual Studio 14 2015` generator has been taught about + a change to the ``v140`` toolset made by a VS 2015 update. VS changed + the set of values it understands for the ``GenerateDebugInformation`` + linker setting that produces the ``-DEBUG`` linker flag variants. + +Updates +======= + +Changes made since CMake 3.9.0 include the following. + +3.9.1 +----- + +* The ``find_`` command ``PACKAGE_ROOT`` search path group added by + CMake 3.9.0 has been removed for the 3.9 series due to regressions + caused by new use of ``<PackageName>_ROOT`` variables. The behavior + may be re-introduced in the future in a more-compatible way. + +3.9.2 +----- + +* On macOS, the default application bundle ``Info.plist`` file no longer + enables Hi-DPI support as it did in 3.9.0 and 3.9.1. The change had + to be reverted because it broke iOS applications. + +* The Xcode generator no longer adds "outputPaths" to custom script + build phases as it did in 3.9.0 and 3.9.1. This was added in an + attempt to support Xcode 9's new build system, but broke incremental + rebuilds for both the old and new Xcode build systems. diff --git a/Help/release/dev.txt b/Help/release/dev.txt new file mode 100644 index 0000000..2cf9193 --- /dev/null +++ b/Help/release/dev.txt @@ -0,0 +1,16 @@ +.. + This file should be included by the adjacent "index.rst" + in development versions but not in release versions. + +Changes Since Release +===================== + +The following noteworthy changes have been made in this development +version since the preceding release but have not yet been consolidated +into notes for a specific release version: + +.. toctree:: + :maxdepth: 1 + :glob: + + dev/* diff --git a/Help/release/dev/0-sample-topic.rst b/Help/release/dev/0-sample-topic.rst new file mode 100644 index 0000000..e4cc01e --- /dev/null +++ b/Help/release/dev/0-sample-topic.rst @@ -0,0 +1,7 @@ +0-sample-topic +-------------- + +* This is a sample release note for the change in a topic. + Developers should add similar notes for each topic branch + making a noteworthy change. Each document should be named + and titled to match the topic name to avoid merge conflicts. diff --git a/Help/release/dev/FindDevIL-imported-targets.rst b/Help/release/dev/FindDevIL-imported-targets.rst new file mode 100644 index 0000000..aa0929e --- /dev/null +++ b/Help/release/dev/FindDevIL-imported-targets.rst @@ -0,0 +1,4 @@ +FindDevIL +--------- + +* The :module:`FindDevIL` module now provides imported targets. diff --git a/Help/release/dev/FindIconv-version.rst b/Help/release/dev/FindIconv-version.rst new file mode 100644 index 0000000..3546d86 --- /dev/null +++ b/Help/release/dev/FindIconv-version.rst @@ -0,0 +1,4 @@ +FindIconv-version +----------------- + +* The :module:`FindIconv` module now has version support. diff --git a/Help/release/dev/FindIntl-version.rst b/Help/release/dev/FindIntl-version.rst new file mode 100644 index 0000000..5365cf1 --- /dev/null +++ b/Help/release/dev/FindIntl-version.rst @@ -0,0 +1,4 @@ +FindIntl-version +---------------- + +* The :module:`FindIntl` module now has version support. diff --git a/Help/release/dev/UseSWIG-csharp.rst b/Help/release/dev/UseSWIG-csharp.rst new file mode 100644 index 0000000..dbbeaf1 --- /dev/null +++ b/Help/release/dev/UseSWIG-csharp.rst @@ -0,0 +1,5 @@ +UseSWIG-csharp +-------------- + +* The :module:`UseSWIG` module use now standard library name conventions for + ``CSharp`` language. See policy :policy:`CMP0122`. diff --git a/Help/release/dev/Xcode-add_custom_command-DEPFILE.rst b/Help/release/dev/Xcode-add_custom_command-DEPFILE.rst new file mode 100644 index 0000000..4c4d48c --- /dev/null +++ b/Help/release/dev/Xcode-add_custom_command-DEPFILE.rst @@ -0,0 +1,5 @@ +Xcode-add_custom_command-DEPFILE +-------------------------------- + +* The :command:`add_custom_command` command gained ``DEPFILE`` support on + :generator:`Xcode` generator. diff --git a/Help/release/dev/add_custom_command-DEPFILE-genex.rst b/Help/release/dev/add_custom_command-DEPFILE-genex.rst new file mode 100644 index 0000000..52e5e9f --- /dev/null +++ b/Help/release/dev/add_custom_command-DEPFILE-genex.rst @@ -0,0 +1,5 @@ +add_custom_command-DEPFILE-genex +-------------------------------- + +* The :command:`add_custom_command` command ``DEPFILE`` option learned to + support :manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/release/dev/c-std.rst b/Help/release/dev/c-std.rst new file mode 100644 index 0000000..44daa85 --- /dev/null +++ b/Help/release/dev/c-std.rst @@ -0,0 +1,6 @@ +c-std +----- + +* :prop_tgt:`C_STANDARD` and the + :manual:`Compile Features <cmake-compile-features(7)>` functionality gained + support for C17 and C23. diff --git a/Help/release/dev/cmake-install-prefix-command.rst b/Help/release/dev/cmake-install-prefix-command.rst new file mode 100644 index 0000000..2de5d91 --- /dev/null +++ b/Help/release/dev/cmake-install-prefix-command.rst @@ -0,0 +1,8 @@ +cmake-install-prefix-command +---------------------------- + +* The :manual:`cmake(1)` command gained the ``--install-prefix <dir>`` + command line option to specify the location of the install prefix. + +* :manual:`cmake-presets(7)` configure preset gained support for specifying + the install prefix. diff --git a/Help/release/dev/cmake-presets-condition.rst b/Help/release/dev/cmake-presets-condition.rst new file mode 100644 index 0000000..aa01bc1 --- /dev/null +++ b/Help/release/dev/cmake-presets-condition.rst @@ -0,0 +1,4 @@ +cmake-presets-condition +----------------------- + +* :manual:`cmake-presets(7)` now support conditional enabling of presets. diff --git a/Help/release/dev/cmake-presets-host-system-name.rst b/Help/release/dev/cmake-presets-host-system-name.rst new file mode 100644 index 0000000..8036939 --- /dev/null +++ b/Help/release/dev/cmake-presets-host-system-name.rst @@ -0,0 +1,5 @@ +cmake-presets-host-system-name +------------------------------ + +* :manual:`cmake-presets(7)` gained support for a new ``${hostSystemName}`` + macro. diff --git a/Help/release/dev/cmake-presets-optional-generator-and-binarydir.rst b/Help/release/dev/cmake-presets-optional-generator-and-binarydir.rst new file mode 100644 index 0000000..7973489 --- /dev/null +++ b/Help/release/dev/cmake-presets-optional-generator-and-binarydir.rst @@ -0,0 +1,5 @@ +cmake-presets-optional-generator-and-binarydir +---------------------------------------------- + +* :manual:`cmake-presets(7)` now support omitting the ``generator`` and + ``binaryDir`` fields. diff --git a/Help/release/dev/cmake-system-name-version.rst b/Help/release/dev/cmake-system-name-version.rst new file mode 100644 index 0000000..9cfe401 --- /dev/null +++ b/Help/release/dev/cmake-system-name-version.rst @@ -0,0 +1,10 @@ +cmake-system-name-version +------------------------- + +* :variable:`CMAKE_HOST_SYSTEM_NAME`'s undocumented version-stripping behavior + has been moved earlier, before :command:`project` or + :command:`enable_language` is called. +* :variable:`CMAKE_SYSTEM_NAME`'s undocumented version-stripping behavior has + been removed entirely. If it is set by a ``-D`` flag or by a + :manual:`toolchain file <cmake-toolchains(7)>`, it is left unaltered, even if + it still contains a version number. diff --git a/Help/release/dev/cmake-toolchain-command.rst b/Help/release/dev/cmake-toolchain-command.rst new file mode 100644 index 0000000..111ca49 --- /dev/null +++ b/Help/release/dev/cmake-toolchain-command.rst @@ -0,0 +1,5 @@ +cmake-toolchain-command +---------------------------- + +* The :manual:`cmake(1)` command gained the ``--toolchain <path/to/file>`` + command line option to specify a toolchain file. diff --git a/Help/release/dev/cpack-dmg-filesystem.rst b/Help/release/dev/cpack-dmg-filesystem.rst new file mode 100644 index 0000000..e2a4742 --- /dev/null +++ b/Help/release/dev/cpack-dmg-filesystem.rst @@ -0,0 +1,5 @@ +cpack-dmg-filesystem +-------------------- + +* The :cpack_gen:`CPack DragNDrop Generator` gained option + :variable:`CPACK_DMG_FILESYSTEM` to control the ``.dmg`` filesystem. diff --git a/Help/release/dev/cpack-nsis-executable-name.rst b/Help/release/dev/cpack-nsis-executable-name.rst new file mode 100644 index 0000000..a3818db --- /dev/null +++ b/Help/release/dev/cpack-nsis-executable-name.rst @@ -0,0 +1,6 @@ +cpack-nsis-executable-name +-------------------------- + +* The :cpack_gen:`CPack NSIS Generator` gained a new variable + :variable:`CPACK_NSIS_EXECUTABLE` to specify the makensis + executable to use instead of the default one. diff --git a/Help/release/dev/cxx-module-extensions.rst b/Help/release/dev/cxx-module-extensions.rst new file mode 100644 index 0000000..b9d0a8a --- /dev/null +++ b/Help/release/dev/cxx-module-extensions.rst @@ -0,0 +1,4 @@ +cxx-module-extensions +--------------------- + +* Source file extensions ``.ixx`` and ``.cppm`` are now treated as C++. diff --git a/Help/release/dev/file-COPY_FILE.rst b/Help/release/dev/file-COPY_FILE.rst new file mode 100644 index 0000000..2f0cdf0 --- /dev/null +++ b/Help/release/dev/file-COPY_FILE.rst @@ -0,0 +1,4 @@ +file-COPY_ONLY +-------------- + +* The :command:`file(COPY_FILE)` command was added to copy a file to another. diff --git a/Help/release/dev/file-RENAME.rst b/Help/release/dev/file-RENAME.rst new file mode 100644 index 0000000..6c1314d --- /dev/null +++ b/Help/release/dev/file-RENAME.rst @@ -0,0 +1,6 @@ +file-RENAME +----------- + +* The :command:`file(RENAME)` command learned to optionally capture + failure in a result variable. It also gained a ``NO_REPLACE`` + option to fail if the destination exists. diff --git a/Help/release/dev/fileapi-codemodel-directory.rst b/Help/release/dev/fileapi-codemodel-directory.rst new file mode 100644 index 0000000..f6515fd --- /dev/null +++ b/Help/release/dev/fileapi-codemodel-directory.rst @@ -0,0 +1,10 @@ +fileapi-codemodel-directory +--------------------------- + +* The :manual:`cmake-file-api(7)` "codemodel" version 2 ``version`` field has + component been updated to 2.3. + +* The :manual:`cmake-file-api(7)` "codemodel" version 2 gained a + new "directory" object containing directory-level information. + This includes a list of installers generated by the :command:`install` + command. diff --git a/Help/release/dev/fujitsu-compiler-support.rst b/Help/release/dev/fujitsu-compiler-support.rst new file mode 100644 index 0000000..c6f8cfb --- /dev/null +++ b/Help/release/dev/fujitsu-compiler-support.rst @@ -0,0 +1,11 @@ +fujitsu-compiler-support +------------------------ + +* Addition of the ``Fujitsu`` compiler ID operating in traditional ``Trad`` + mode and ``FujitsuClang`` operating in ``Clang`` mode. +* The :module:`FindOpenMP` module learned to support ``Fujitsu`` and + ``FujitsuClang``. +* The :module:`FindMPI` module learned to support ``Fujitsu`` and + ``FujitsuClang`` in both host and cross compiling modes. +* The :module:`FindBLAS` and :module:`FindLAPACK` modules learned to support + the serial ``Fujitsu SSL2`` and parallel ``Fujitsu SSL2BLAMP`` libraries. diff --git a/Help/release/dev/ifw-default-version-operator.rst b/Help/release/dev/ifw-default-version-operator.rst new file mode 100644 index 0000000..4aeace2 --- /dev/null +++ b/Help/release/dev/ifw-default-version-operator.rst @@ -0,0 +1,7 @@ +ifw-default-version-operator +---------------------------- + +* Names given as ``DEPENDS`` or ``DEPENDENCIES`` arguments to + :command:`cpack_ifw_configure_component` or + :command:`cpack_ifw_configure_component_group` may now contain hyphens. + This requires QtIFW 3.1 or later. diff --git a/Help/release/dev/list-index-arg-parsing.rst b/Help/release/dev/list-index-arg-parsing.rst new file mode 100644 index 0000000..2ea525b --- /dev/null +++ b/Help/release/dev/list-index-arg-parsing.rst @@ -0,0 +1,7 @@ +list-index-arg-parsing +---------------------- + +* The :command:`list` command's ``GET``, ``INSERT``, ``SUBLIST``, and + ``REMOVE_AT`` subcommands now error with invalid (i.e., non-integer) values + are given as any of their index arguments based on the setting of policy + :policy:`CMP0121`. diff --git a/Help/release/dev/project-is-top-level.rst b/Help/release/dev/project-is-top-level.rst new file mode 100644 index 0000000..568afe0 --- /dev/null +++ b/Help/release/dev/project-is-top-level.rst @@ -0,0 +1,6 @@ +project-is-top-level +-------------------- + +* :command:`project` now sets variables :variable:`PROJECT_IS_TOP_LEVEL` and + :variable:`<PROJECT-NAME>_IS_TOP_LEVEL` to indicate whether it was called + in a top level ``CMakeLists.txt`` file. diff --git a/Help/release/dev/runtime-dll-deps.rst b/Help/release/dev/runtime-dll-deps.rst new file mode 100644 index 0000000..831410f --- /dev/null +++ b/Help/release/dev/runtime-dll-deps.rst @@ -0,0 +1,4 @@ +runtime-dll-deps +---------------- + +* A new :genex:`TARGET_RUNTIME_DLLS` generator expression was added. diff --git a/Help/release/index.rst b/Help/release/index.rst new file mode 100644 index 0000000..5dfca05 --- /dev/null +++ b/Help/release/index.rst @@ -0,0 +1,38 @@ +:orphan: + +CMake Release Notes +******************* + +.. + This file should include the adjacent "dev.txt" file + in development versions but not in release versions. + +.. include:: dev.txt + +Releases +======== + +.. toctree:: + :maxdepth: 1 + + 3.20 <3.20> + 3.19 <3.19> + 3.18 <3.18> + 3.17 <3.17> + 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> + 3.6 <3.6> + 3.5 <3.5> + 3.4 <3.4> + 3.3 <3.3> + 3.2 <3.2> + 3.1 <3.1> + 3.0 <3.0> diff --git a/Help/variable/ANDROID.rst b/Help/variable/ANDROID.rst new file mode 100644 index 0000000..68dccf2 --- /dev/null +++ b/Help/variable/ANDROID.rst @@ -0,0 +1,7 @@ +ANDROID +------- + +.. versionadded:: 3.7 + +Set to ``1`` when the target system (:variable:`CMAKE_SYSTEM_NAME`) is +``Android``. diff --git a/Help/variable/APPLE.rst b/Help/variable/APPLE.rst new file mode 100644 index 0000000..810d5fc --- /dev/null +++ b/Help/variable/APPLE.rst @@ -0,0 +1,5 @@ +APPLE +----- + +Set to ``True`` when the target system is an Apple platform +(macOS, iOS, tvOS or watchOS). diff --git a/Help/variable/BORLAND.rst b/Help/variable/BORLAND.rst new file mode 100644 index 0000000..badb733 --- /dev/null +++ b/Help/variable/BORLAND.rst @@ -0,0 +1,6 @@ +BORLAND +------- + +``True`` if the Borland compiler is being used. + +This is set to ``true`` if the Borland compiler is being used. diff --git a/Help/variable/BUILD_SHARED_LIBS.rst b/Help/variable/BUILD_SHARED_LIBS.rst new file mode 100644 index 0000000..53087b2 --- /dev/null +++ b/Help/variable/BUILD_SHARED_LIBS.rst @@ -0,0 +1,10 @@ +BUILD_SHARED_LIBS +----------------- + +Global flag to cause :command:`add_library` to create shared libraries if on. + +If present and true, this will cause all libraries to be built shared +unless the library was explicitly added as a static library. This +variable is often added to projects as an :command:`option` so that each user +of a project can decide if they want to build the project using shared or +static libraries. diff --git a/Help/variable/CACHE.rst b/Help/variable/CACHE.rst new file mode 100644 index 0000000..d5489c8 --- /dev/null +++ b/Help/variable/CACHE.rst @@ -0,0 +1,20 @@ +CACHE +----- + +.. versionadded:: 3.13 + +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_ABSOLUTE_DESTINATION_FILES.rst b/Help/variable/CMAKE_ABSOLUTE_DESTINATION_FILES.rst new file mode 100644 index 0000000..b6d0054 --- /dev/null +++ b/Help/variable/CMAKE_ABSOLUTE_DESTINATION_FILES.rst @@ -0,0 +1,9 @@ +CMAKE_ABSOLUTE_DESTINATION_FILES +-------------------------------- + +List of files which have been installed using an ``ABSOLUTE DESTINATION`` path. + +This variable is defined by CMake-generated ``cmake_install.cmake`` +scripts. It can be used (read-only) by programs or scripts that +source those install scripts. This is used by some CPack generators +(e.g. RPM). diff --git a/Help/variable/CMAKE_AIX_EXPORT_ALL_SYMBOLS.rst b/Help/variable/CMAKE_AIX_EXPORT_ALL_SYMBOLS.rst new file mode 100644 index 0000000..699fe0f --- /dev/null +++ b/Help/variable/CMAKE_AIX_EXPORT_ALL_SYMBOLS.rst @@ -0,0 +1,8 @@ +CMAKE_AIX_EXPORT_ALL_SYMBOLS +---------------------------- + +.. versionadded:: 3.17 + +Default value for :prop_tgt:`AIX_EXPORT_ALL_SYMBOLS` target property. +This variable is used to initialize the property on each target as it is +created. diff --git a/Help/variable/CMAKE_ANDROID_ANT_ADDITIONAL_OPTIONS.rst b/Help/variable/CMAKE_ANDROID_ANT_ADDITIONAL_OPTIONS.rst new file mode 100644 index 0000000..2d6b4b9 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_ANT_ADDITIONAL_OPTIONS.rst @@ -0,0 +1,7 @@ +CMAKE_ANDROID_ANT_ADDITIONAL_OPTIONS +------------------------------------ + +.. versionadded:: 3.4 + +Default value for the :prop_tgt:`ANDROID_ANT_ADDITIONAL_OPTIONS` target property. +See that target property for additional information. diff --git a/Help/variable/CMAKE_ANDROID_API.rst b/Help/variable/CMAKE_ANDROID_API.rst new file mode 100644 index 0000000..4388bf2 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_API.rst @@ -0,0 +1,13 @@ +CMAKE_ANDROID_API +----------------- + +.. versionadded:: 3.1 + +When :ref:`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio +Edition`, this variable may be set to specify the default value for the +:prop_tgt:`ANDROID_API` target property. See that target property for +additional information. + +Otherwise, when :ref:`Cross Compiling for Android`, this variable provides +the Android API version number targeted. This will be the same value as +the :variable:`CMAKE_SYSTEM_VERSION` variable for ``Android`` platforms. diff --git a/Help/variable/CMAKE_ANDROID_API_MIN.rst b/Help/variable/CMAKE_ANDROID_API_MIN.rst new file mode 100644 index 0000000..a0d2ab4 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_API_MIN.rst @@ -0,0 +1,7 @@ +CMAKE_ANDROID_API_MIN +--------------------- + +.. versionadded:: 3.2 + +Default value for the :prop_tgt:`ANDROID_API_MIN` target property. +See that target property for additional information. diff --git a/Help/variable/CMAKE_ANDROID_ARCH.rst b/Help/variable/CMAKE_ANDROID_ARCH.rst new file mode 100644 index 0000000..9f12742 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_ARCH.rst @@ -0,0 +1,21 @@ +CMAKE_ANDROID_ARCH +------------------ + +.. versionadded:: 3.4 + +When :ref:`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio +Edition`, this variable may be set to specify the default value for the +:prop_tgt:`ANDROID_ARCH` target property. See that target property for +additional information. + +Otherwise, when :ref:`Cross Compiling for Android`, this variable provides +the name of the Android architecture corresponding to the value of the +:variable:`CMAKE_ANDROID_ARCH_ABI` variable. The architecture name +may be one of: + +* ``arm`` +* ``arm64`` +* ``mips`` +* ``mips64`` +* ``x86`` +* ``x86_64`` diff --git a/Help/variable/CMAKE_ANDROID_ARCH_ABI.rst b/Help/variable/CMAKE_ANDROID_ARCH_ABI.rst new file mode 100644 index 0000000..5a2e3ec --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_ARCH_ABI.rst @@ -0,0 +1,19 @@ +CMAKE_ANDROID_ARCH_ABI +---------------------- + +.. versionadded:: 3.7 + +When :ref:`Cross Compiling for Android`, this variable specifies the +target architecture and ABI to be used. Valid values are: + +* ``arm64-v8a`` +* ``armeabi-v7a`` +* ``armeabi-v6`` +* ``armeabi`` +* ``mips`` +* ``mips64`` +* ``x86`` +* ``x86_64`` + +See also the :variable:`CMAKE_ANDROID_ARM_MODE` and +:variable:`CMAKE_ANDROID_ARM_NEON` variables. diff --git a/Help/variable/CMAKE_ANDROID_ARM_MODE.rst b/Help/variable/CMAKE_ANDROID_ARM_MODE.rst new file mode 100644 index 0000000..973ff7e --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_ARM_MODE.rst @@ -0,0 +1,9 @@ +CMAKE_ANDROID_ARM_MODE +---------------------- + +.. versionadded:: 3.7 + +When :ref:`Cross Compiling for Android` and :variable:`CMAKE_ANDROID_ARCH_ABI` +is set to one of the ``armeabi`` architectures, set ``CMAKE_ANDROID_ARM_MODE`` +to ``ON`` to target 32-bit ARM processors (``-marm``). Otherwise, the +default is to target the 16-bit Thumb processors (``-mthumb``). diff --git a/Help/variable/CMAKE_ANDROID_ARM_NEON.rst b/Help/variable/CMAKE_ANDROID_ARM_NEON.rst new file mode 100644 index 0000000..6b9cf08 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_ARM_NEON.rst @@ -0,0 +1,8 @@ +CMAKE_ANDROID_ARM_NEON +---------------------- + +.. versionadded:: 3.7 + +When :ref:`Cross Compiling for Android` and :variable:`CMAKE_ANDROID_ARCH_ABI` +is set to ``armeabi-v7a`` set ``CMAKE_ANDROID_ARM_NEON`` to ``ON`` to target +ARM NEON devices. diff --git a/Help/variable/CMAKE_ANDROID_ASSETS_DIRECTORIES.rst b/Help/variable/CMAKE_ANDROID_ASSETS_DIRECTORIES.rst new file mode 100644 index 0000000..3de2be4 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_ASSETS_DIRECTORIES.rst @@ -0,0 +1,7 @@ +CMAKE_ANDROID_ASSETS_DIRECTORIES +-------------------------------- + +.. versionadded:: 3.4 + +Default value for the :prop_tgt:`ANDROID_ASSETS_DIRECTORIES` target property. +See that target property for additional information. diff --git a/Help/variable/CMAKE_ANDROID_EXCEPTIONS.rst b/Help/variable/CMAKE_ANDROID_EXCEPTIONS.rst new file mode 100644 index 0000000..6dd44f8 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_EXCEPTIONS.rst @@ -0,0 +1,7 @@ +CMAKE_ANDROID_EXCEPTIONS +------------------------ + +.. versionadded:: 3.20 + +When :ref:`Cross Compiling for Android with the NDK`, this variable may be set +to specify whether exceptions are enabled. diff --git a/Help/variable/CMAKE_ANDROID_GUI.rst b/Help/variable/CMAKE_ANDROID_GUI.rst new file mode 100644 index 0000000..821bbee --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_GUI.rst @@ -0,0 +1,7 @@ +CMAKE_ANDROID_GUI +----------------- + +.. versionadded:: 3.1 + +Default value for the :prop_tgt:`ANDROID_GUI` target property of +executables. See that target property for additional information. diff --git a/Help/variable/CMAKE_ANDROID_JAR_DEPENDENCIES.rst b/Help/variable/CMAKE_ANDROID_JAR_DEPENDENCIES.rst new file mode 100644 index 0000000..80ab842 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_JAR_DEPENDENCIES.rst @@ -0,0 +1,7 @@ +CMAKE_ANDROID_JAR_DEPENDENCIES +------------------------------ + +.. versionadded:: 3.4 + +Default value for the :prop_tgt:`ANDROID_JAR_DEPENDENCIES` target property. +See that target property for additional information. diff --git a/Help/variable/CMAKE_ANDROID_JAR_DIRECTORIES.rst b/Help/variable/CMAKE_ANDROID_JAR_DIRECTORIES.rst new file mode 100644 index 0000000..4d148d8 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_JAR_DIRECTORIES.rst @@ -0,0 +1,7 @@ +CMAKE_ANDROID_JAR_DIRECTORIES +----------------------------- + +.. versionadded:: 3.4 + +Default value for the :prop_tgt:`ANDROID_JAR_DIRECTORIES` target property. +See that target property for additional information. diff --git a/Help/variable/CMAKE_ANDROID_JAVA_SOURCE_DIR.rst b/Help/variable/CMAKE_ANDROID_JAVA_SOURCE_DIR.rst new file mode 100644 index 0000000..021baa0 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_JAVA_SOURCE_DIR.rst @@ -0,0 +1,7 @@ +CMAKE_ANDROID_JAVA_SOURCE_DIR +----------------------------- + +.. versionadded:: 3.4 + +Default value for the :prop_tgt:`ANDROID_JAVA_SOURCE_DIR` target property. +See that target property for additional information. diff --git a/Help/variable/CMAKE_ANDROID_NATIVE_LIB_DEPENDENCIES.rst b/Help/variable/CMAKE_ANDROID_NATIVE_LIB_DEPENDENCIES.rst new file mode 100644 index 0000000..41d4cc3 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_NATIVE_LIB_DEPENDENCIES.rst @@ -0,0 +1,7 @@ +CMAKE_ANDROID_NATIVE_LIB_DEPENDENCIES +------------------------------------- + +.. versionadded:: 3.4 + +Default value for the :prop_tgt:`ANDROID_NATIVE_LIB_DEPENDENCIES` target +property. See that target property for additional information. diff --git a/Help/variable/CMAKE_ANDROID_NATIVE_LIB_DIRECTORIES.rst b/Help/variable/CMAKE_ANDROID_NATIVE_LIB_DIRECTORIES.rst new file mode 100644 index 0000000..e87547d --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_NATIVE_LIB_DIRECTORIES.rst @@ -0,0 +1,7 @@ +CMAKE_ANDROID_NATIVE_LIB_DIRECTORIES +------------------------------------ + +.. versionadded:: 3.4 + +Default value for the :prop_tgt:`ANDROID_NATIVE_LIB_DIRECTORIES` target +property. See that target property for additional information. diff --git a/Help/variable/CMAKE_ANDROID_NDK.rst b/Help/variable/CMAKE_ANDROID_NDK.rst new file mode 100644 index 0000000..72ac99e --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_NDK.rst @@ -0,0 +1,9 @@ +CMAKE_ANDROID_NDK +----------------- + +.. versionadded:: 3.7 + +When :ref:`Cross Compiling for Android with the NDK`, this variable holds +the absolute path to the root directory of the NDK. The directory must +contain a ``platforms`` subdirectory holding the ``android-<api>`` +directories. diff --git a/Help/variable/CMAKE_ANDROID_NDK_DEPRECATED_HEADERS.rst b/Help/variable/CMAKE_ANDROID_NDK_DEPRECATED_HEADERS.rst new file mode 100644 index 0000000..40a5c1a --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_NDK_DEPRECATED_HEADERS.rst @@ -0,0 +1,11 @@ +CMAKE_ANDROID_NDK_DEPRECATED_HEADERS +------------------------------------ + +.. versionadded:: 3.9 + +When :ref:`Cross Compiling for Android with the NDK`, this variable +may be set to specify whether to use the deprecated per-api-level +headers instead of the unified headers. + +If not specified, the default will be *false* if using a NDK version +that provides the unified headers and *true* otherwise. diff --git a/Help/variable/CMAKE_ANDROID_NDK_TOOLCHAIN_HOST_TAG.rst b/Help/variable/CMAKE_ANDROID_NDK_TOOLCHAIN_HOST_TAG.rst new file mode 100644 index 0000000..9d61fa4 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_NDK_TOOLCHAIN_HOST_TAG.rst @@ -0,0 +1,8 @@ +CMAKE_ANDROID_NDK_TOOLCHAIN_HOST_TAG +------------------------------------ + +.. versionadded:: 3.7.1 + +When :ref:`Cross Compiling for Android with the NDK`, this variable +provides the NDK's "host tag" used to construct the path to prebuilt +toolchains that run on the host. diff --git a/Help/variable/CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION.rst b/Help/variable/CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION.rst new file mode 100644 index 0000000..15fe18f --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION.rst @@ -0,0 +1,22 @@ +CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION +----------------------------------- + +.. versionadded:: 3.7 + +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. + +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 +* ``clang``: Clang of most recent available version + +A toolchain of the requested version will be selected automatically to +match the ABI named in the :variable:`CMAKE_ANDROID_ARCH_ABI` variable. + +If not specified, the default will be a value that selects the latest +available GCC toolchain. diff --git a/Help/variable/CMAKE_ANDROID_NDK_VERSION.rst b/Help/variable/CMAKE_ANDROID_NDK_VERSION.rst new file mode 100644 index 0000000..5428d52 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_NDK_VERSION.rst @@ -0,0 +1,8 @@ +CMAKE_ANDROID_NDK_VERSION +------------------------- + +.. versionadded:: 3.20 + +When :ref:`Cross Compiling for Android with the NDK` and using an +Android NDK version 11 or higher, this variable is provided by +CMake to report the NDK version number. diff --git a/Help/variable/CMAKE_ANDROID_PROCESS_MAX.rst b/Help/variable/CMAKE_ANDROID_PROCESS_MAX.rst new file mode 100644 index 0000000..be241c2 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_PROCESS_MAX.rst @@ -0,0 +1,7 @@ +CMAKE_ANDROID_PROCESS_MAX +------------------------- + +.. versionadded:: 3.4 + +Default value for the :prop_tgt:`ANDROID_PROCESS_MAX` target property. +See that target property for additional information. diff --git a/Help/variable/CMAKE_ANDROID_PROGUARD.rst b/Help/variable/CMAKE_ANDROID_PROGUARD.rst new file mode 100644 index 0000000..bb001d3 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_PROGUARD.rst @@ -0,0 +1,7 @@ +CMAKE_ANDROID_PROGUARD +---------------------- + +.. versionadded:: 3.4 + +Default value for the :prop_tgt:`ANDROID_PROGUARD` target property. +See that target property for additional information. diff --git a/Help/variable/CMAKE_ANDROID_PROGUARD_CONFIG_PATH.rst b/Help/variable/CMAKE_ANDROID_PROGUARD_CONFIG_PATH.rst new file mode 100644 index 0000000..6fd4067 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_PROGUARD_CONFIG_PATH.rst @@ -0,0 +1,7 @@ +CMAKE_ANDROID_PROGUARD_CONFIG_PATH +---------------------------------- + +.. versionadded:: 3.4 + +Default value for the :prop_tgt:`ANDROID_PROGUARD_CONFIG_PATH` target property. +See that target property for additional information. diff --git a/Help/variable/CMAKE_ANDROID_RTTI.rst b/Help/variable/CMAKE_ANDROID_RTTI.rst new file mode 100644 index 0000000..0e98206 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_RTTI.rst @@ -0,0 +1,7 @@ +CMAKE_ANDROID_RTTI +------------------ + +.. versionadded:: 3.20 + +When :ref:`Cross Compiling for Android with the NDK`, this variable may be set +to specify whether RTTI is enabled. diff --git a/Help/variable/CMAKE_ANDROID_SECURE_PROPS_PATH.rst b/Help/variable/CMAKE_ANDROID_SECURE_PROPS_PATH.rst new file mode 100644 index 0000000..9f5743e --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_SECURE_PROPS_PATH.rst @@ -0,0 +1,7 @@ +CMAKE_ANDROID_SECURE_PROPS_PATH +------------------------------- + +.. versionadded:: 3.4 + +Default value for the :prop_tgt:`ANDROID_SECURE_PROPS_PATH` target property. +See that target property for additional information. diff --git a/Help/variable/CMAKE_ANDROID_SKIP_ANT_STEP.rst b/Help/variable/CMAKE_ANDROID_SKIP_ANT_STEP.rst new file mode 100644 index 0000000..588769b --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_SKIP_ANT_STEP.rst @@ -0,0 +1,7 @@ +CMAKE_ANDROID_SKIP_ANT_STEP +--------------------------- + +.. versionadded:: 3.4 + +Default value for the :prop_tgt:`ANDROID_SKIP_ANT_STEP` target property. +See that target property for additional information. diff --git a/Help/variable/CMAKE_ANDROID_STANDALONE_TOOLCHAIN.rst b/Help/variable/CMAKE_ANDROID_STANDALONE_TOOLCHAIN.rst new file mode 100644 index 0000000..3ca89f5 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_STANDALONE_TOOLCHAIN.rst @@ -0,0 +1,8 @@ +CMAKE_ANDROID_STANDALONE_TOOLCHAIN +---------------------------------- + +.. versionadded:: 3.7 + +When :ref:`Cross Compiling for Android with a Standalone Toolchain`, this +variable holds the absolute path to the root directory of the toolchain. +The specified directory must contain a ``sysroot`` subdirectory. diff --git a/Help/variable/CMAKE_ANDROID_STL_TYPE.rst b/Help/variable/CMAKE_ANDROID_STL_TYPE.rst new file mode 100644 index 0000000..3778181 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_STL_TYPE.rst @@ -0,0 +1,39 @@ +CMAKE_ANDROID_STL_TYPE +---------------------- + +.. versionadded:: 3.4 + +When :ref:`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio +Edition`, this variable may be set to specify the default value for the +:prop_tgt:`ANDROID_STL_TYPE` target property. See that target property +for additional information. + +When :ref:`Cross Compiling for Android with the NDK`, this variable may be +set to specify the STL variant to be used. The value may be one of: + +``none`` + No C++ Support +``system`` + Minimal C++ without STL +``gabi++_static`` + GAbi++ Static +``gabi++_shared`` + GAbi++ Shared +``gnustl_static`` + GNU libstdc++ Static +``gnustl_shared`` + GNU libstdc++ Shared +``c++_static`` + LLVM libc++ Static +``c++_shared`` + LLVM libc++ Shared +``stlport_static`` + STLport Static +``stlport_shared`` + STLport Shared + +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 new file mode 100644 index 0000000..1c7ca51 --- /dev/null +++ b/Help/variable/CMAKE_APPBUNDLE_PATH.rst @@ -0,0 +1,6 @@ +CMAKE_APPBUNDLE_PATH +-------------------- + +: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_APPLE_SILICON_PROCESSOR.rst b/Help/variable/CMAKE_APPLE_SILICON_PROCESSOR.rst new file mode 100644 index 0000000..0d5ccd1 --- /dev/null +++ b/Help/variable/CMAKE_APPLE_SILICON_PROCESSOR.rst @@ -0,0 +1,14 @@ +CMAKE_APPLE_SILICON_PROCESSOR +----------------------------- + +.. versionadded:: 3.19.2 + +On Apple Silicon hosts running macOS, set this variable to tell +CMake what architecture to use for :variable:`CMAKE_HOST_SYSTEM_PROCESSOR`. +The value must be either ``arm64`` or ``x86_64``. + +The value of this variable should never be modified by project code. +It is meant to be set as a cache entry provided by the user, +e.g. via ``-DCMAKE_APPLE_SILICON_PROCESSOR=...``. + +See also the :envvar:`CMAKE_APPLE_SILICON_PROCESSOR` environment variable. diff --git a/Help/variable/CMAKE_AR.rst b/Help/variable/CMAKE_AR.rst new file mode 100644 index 0000000..5893677 --- /dev/null +++ b/Help/variable/CMAKE_AR.rst @@ -0,0 +1,7 @@ +CMAKE_AR +-------- + +Name of archiving tool for static libraries. + +This specifies the name of the program that creates archive or static +libraries. diff --git a/Help/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY.rst b/Help/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY.rst new file mode 100644 index 0000000..c889321 --- /dev/null +++ b/Help/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY.rst @@ -0,0 +1,9 @@ +CMAKE_ARCHIVE_OUTPUT_DIRECTORY +------------------------------ + +Where to put all the :ref:`ARCHIVE <Archive Output Artifacts>` +target files when built. + +This variable is used to initialize the :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY` +property on all the targets. See that target property for additional +information. diff --git a/Help/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG.rst b/Help/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG.rst new file mode 100644 index 0000000..d8bd82c --- /dev/null +++ b/Help/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG.rst @@ -0,0 +1,11 @@ +CMAKE_ARCHIVE_OUTPUT_DIRECTORY_<CONFIG> +--------------------------------------- + +.. versionadded:: 3.3 + +Where to put all the :ref:`ARCHIVE <Archive Output Artifacts>` +target files when built for a specific configuration. + +This variable is used to initialize the +:prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY_<CONFIG>` property on all the targets. +See that target property for additional information. diff --git a/Help/variable/CMAKE_ARGC.rst b/Help/variable/CMAKE_ARGC.rst new file mode 100644 index 0000000..30db2a2 --- /dev/null +++ b/Help/variable/CMAKE_ARGC.rst @@ -0,0 +1,8 @@ +CMAKE_ARGC +---------- + +Number of command line arguments passed to CMake in script mode. + +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 new file mode 100644 index 0000000..c4d1c21 --- /dev/null +++ b/Help/variable/CMAKE_ARGV0.rst @@ -0,0 +1,9 @@ +CMAKE_ARGV0 +----------- + +Command line argument passed to CMake in script mode. + +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 0000000..c24e462 --- /dev/null +++ b/Help/variable/CMAKE_AUTOGEN_ORIGIN_DEPENDS.rst @@ -0,0 +1,13 @@ +CMAKE_AUTOGEN_ORIGIN_DEPENDS +---------------------------- + +.. versionadded:: 3.14 + +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 0000000..2ada012 --- /dev/null +++ b/Help/variable/CMAKE_AUTOGEN_PARALLEL.rst @@ -0,0 +1,12 @@ +CMAKE_AUTOGEN_PARALLEL +---------------------- + +.. versionadded:: 3.11 + +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 0000000..f77ed6a --- /dev/null +++ b/Help/variable/CMAKE_AUTOGEN_VERBOSE.rst @@ -0,0 +1,15 @@ +CMAKE_AUTOGEN_VERBOSE +--------------------- + +.. versionadded:: 3.13 + +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.rst b/Help/variable/CMAKE_AUTOMOC.rst new file mode 100644 index 0000000..02e5eb5 --- /dev/null +++ b/Help/variable/CMAKE_AUTOMOC.rst @@ -0,0 +1,7 @@ +CMAKE_AUTOMOC +------------- + +Whether to handle ``moc`` automatically for Qt targets. + +This variable is used to initialize the :prop_tgt:`AUTOMOC` property on all the +targets. See that target property for additional information. diff --git a/Help/variable/CMAKE_AUTOMOC_COMPILER_PREDEFINES.rst b/Help/variable/CMAKE_AUTOMOC_COMPILER_PREDEFINES.rst new file mode 100644 index 0000000..f1b03a0 --- /dev/null +++ b/Help/variable/CMAKE_AUTOMOC_COMPILER_PREDEFINES.rst @@ -0,0 +1,10 @@ +CMAKE_AUTOMOC_COMPILER_PREDEFINES +--------------------------------- + +.. versionadded:: 3.10 + +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_DEPEND_FILTERS.rst b/Help/variable/CMAKE_AUTOMOC_DEPEND_FILTERS.rst new file mode 100644 index 0000000..2c1551a --- /dev/null +++ b/Help/variable/CMAKE_AUTOMOC_DEPEND_FILTERS.rst @@ -0,0 +1,14 @@ +CMAKE_AUTOMOC_DEPEND_FILTERS +---------------------------- + +.. versionadded:: 3.9 + +Filter definitions used by :variable:`CMAKE_AUTOMOC` +to extract file names from source code as additional dependencies +for the ``moc`` file. + +This variable is used to initialize the :prop_tgt:`AUTOMOC_DEPEND_FILTERS` +property on all the targets. See that target property for additional +information. + +By default it is empty. diff --git a/Help/variable/CMAKE_AUTOMOC_MACRO_NAMES.rst b/Help/variable/CMAKE_AUTOMOC_MACRO_NAMES.rst new file mode 100644 index 0000000..1153cb2 --- /dev/null +++ b/Help/variable/CMAKE_AUTOMOC_MACRO_NAMES.rst @@ -0,0 +1,22 @@ +CMAKE_AUTOMOC_MACRO_NAMES +---------------------------- + +.. versionadded:: 3.10 + +: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;Q_NAMESPACE_EXPORT``. + +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_MOC_OPTIONS.rst b/Help/variable/CMAKE_AUTOMOC_MOC_OPTIONS.rst new file mode 100644 index 0000000..09bf5cd --- /dev/null +++ b/Help/variable/CMAKE_AUTOMOC_MOC_OPTIONS.rst @@ -0,0 +1,7 @@ +CMAKE_AUTOMOC_MOC_OPTIONS +------------------------- + +Additional options for ``moc`` when using :variable:`CMAKE_AUTOMOC`. + +This variable is used to initialize the :prop_tgt:`AUTOMOC_MOC_OPTIONS` property +on all the targets. See that target property for additional information. diff --git a/Help/variable/CMAKE_AUTOMOC_PATH_PREFIX.rst b/Help/variable/CMAKE_AUTOMOC_PATH_PREFIX.rst new file mode 100644 index 0000000..42f48b4 --- /dev/null +++ b/Help/variable/CMAKE_AUTOMOC_PATH_PREFIX.rst @@ -0,0 +1,13 @@ +CMAKE_AUTOMOC_PATH_PREFIX +------------------------- + +.. versionadded:: 3.16 + +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 ``OFF``. diff --git a/Help/variable/CMAKE_AUTOMOC_RELAXED_MODE.rst b/Help/variable/CMAKE_AUTOMOC_RELAXED_MODE.rst new file mode 100644 index 0000000..6c0c61b --- /dev/null +++ b/Help/variable/CMAKE_AUTOMOC_RELAXED_MODE.rst @@ -0,0 +1,15 @@ +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 +documentation of the :prop_tgt:`AUTOMOC` target property. When set to +``TRUE``, it accepts more input and tries to find the correct input file for +``moc`` even if it differs from the documented behaviour. In this mode it +e.g. also checks whether a header file is intended to be processed by moc +when a ``"foo.moc"`` file has been included. + +Relaxed mode has to be enabled for KDE4 compatibility. diff --git a/Help/variable/CMAKE_AUTORCC.rst b/Help/variable/CMAKE_AUTORCC.rst new file mode 100644 index 0000000..7426105 --- /dev/null +++ b/Help/variable/CMAKE_AUTORCC.rst @@ -0,0 +1,7 @@ +CMAKE_AUTORCC +------------- + +Whether to handle ``rcc`` automatically for Qt targets. + +This variable is used to initialize the :prop_tgt:`AUTORCC` property on all +the targets. See that target property for additional information. diff --git a/Help/variable/CMAKE_AUTORCC_OPTIONS.rst b/Help/variable/CMAKE_AUTORCC_OPTIONS.rst new file mode 100644 index 0000000..815d39d --- /dev/null +++ b/Help/variable/CMAKE_AUTORCC_OPTIONS.rst @@ -0,0 +1,16 @@ +CMAKE_AUTORCC_OPTIONS +--------------------- + +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.rst b/Help/variable/CMAKE_AUTOUIC.rst new file mode 100644 index 0000000..5abefaa --- /dev/null +++ b/Help/variable/CMAKE_AUTOUIC.rst @@ -0,0 +1,7 @@ +CMAKE_AUTOUIC +------------- + +Whether to handle ``uic`` automatically for Qt targets. + +This variable is used to initialize the :prop_tgt:`AUTOUIC` property on all +the targets. See that target property for additional information. diff --git a/Help/variable/CMAKE_AUTOUIC_OPTIONS.rst b/Help/variable/CMAKE_AUTOUIC_OPTIONS.rst new file mode 100644 index 0000000..28fa92f --- /dev/null +++ b/Help/variable/CMAKE_AUTOUIC_OPTIONS.rst @@ -0,0 +1,16 @@ +CMAKE_AUTOUIC_OPTIONS +--------------------- + +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_AUTOUIC_SEARCH_PATHS.rst b/Help/variable/CMAKE_AUTOUIC_SEARCH_PATHS.rst new file mode 100644 index 0000000..0262368 --- /dev/null +++ b/Help/variable/CMAKE_AUTOUIC_SEARCH_PATHS.rst @@ -0,0 +1,13 @@ +CMAKE_AUTOUIC_SEARCH_PATHS +-------------------------- + +.. versionadded:: 3.9 + +Search path list used by :variable:`CMAKE_AUTOUIC` to find included +``.ui`` files. + +This variable is used to initialize the :prop_tgt:`AUTOUIC_SEARCH_PATHS` +property on all the targets. See that target property for additional +information. + +By default it is empty. diff --git a/Help/variable/CMAKE_BACKWARDS_COMPATIBILITY.rst b/Help/variable/CMAKE_BACKWARDS_COMPATIBILITY.rst new file mode 100644 index 0000000..05c366a --- /dev/null +++ b/Help/variable/CMAKE_BACKWARDS_COMPATIBILITY.rst @@ -0,0 +1,4 @@ +CMAKE_BACKWARDS_COMPATIBILITY +----------------------------- + +Deprecated. See CMake Policy :policy:`CMP0001` documentation. diff --git a/Help/variable/CMAKE_BINARY_DIR.rst b/Help/variable/CMAKE_BINARY_DIR.rst new file mode 100644 index 0000000..3b323b7 --- /dev/null +++ b/Help/variable/CMAKE_BINARY_DIR.rst @@ -0,0 +1,13 @@ +CMAKE_BINARY_DIR +---------------- + +The path to the top level of the build tree. + +This is the full path to the top level of the current CMake build +tree. For an in-source build, this would be the same as +:variable:`CMAKE_SOURCE_DIR`. + +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_BUILD_RPATH.rst b/Help/variable/CMAKE_BUILD_RPATH.rst new file mode 100644 index 0000000..7a8ace7 --- /dev/null +++ b/Help/variable/CMAKE_BUILD_RPATH.rst @@ -0,0 +1,12 @@ +CMAKE_BUILD_RPATH +----------------- + +.. versionadded:: 3.8 + +: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. + +This is used to initialize the :prop_tgt:`BUILD_RPATH` target property +for all targets. 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 0000000..ecd9278 --- /dev/null +++ b/Help/variable/CMAKE_BUILD_RPATH_USE_ORIGIN.rst @@ -0,0 +1,9 @@ +CMAKE_BUILD_RPATH_USE_ORIGIN +---------------------------- + +.. versionadded:: 3.14 + +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_TOOL.rst b/Help/variable/CMAKE_BUILD_TOOL.rst new file mode 100644 index 0000000..6133491 --- /dev/null +++ b/Help/variable/CMAKE_BUILD_TOOL.rst @@ -0,0 +1,6 @@ +CMAKE_BUILD_TOOL +---------------- + +This variable exists only for backwards compatibility. +It contains the same value as :variable:`CMAKE_MAKE_PROGRAM`. +Use that variable instead. diff --git a/Help/variable/CMAKE_BUILD_TYPE.rst b/Help/variable/CMAKE_BUILD_TYPE.rst new file mode 100644 index 0000000..405f7d5 --- /dev/null +++ b/Help/variable/CMAKE_BUILD_TYPE.rst @@ -0,0 +1,25 @@ +CMAKE_BUILD_TYPE +---------------- + +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``, ``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 +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, +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 +also :variable:`CMAKE_CONFIGURATION_TYPES`. + +Note that configuration names are case-insensitive. The value of this +variable will be the same as it is specified when invoking CMake. +For instance, if ``-DCMAKE_BUILD_TYPE=ReLeAsE`` is specified, then the +value of ``CMAKE_BUILD_TYPE`` will be ``ReLeAsE``. diff --git a/Help/variable/CMAKE_BUILD_WITH_INSTALL_NAME_DIR.rst b/Help/variable/CMAKE_BUILD_WITH_INSTALL_NAME_DIR.rst new file mode 100644 index 0000000..5ba775c --- /dev/null +++ b/Help/variable/CMAKE_BUILD_WITH_INSTALL_NAME_DIR.rst @@ -0,0 +1,9 @@ +CMAKE_BUILD_WITH_INSTALL_NAME_DIR +--------------------------------- + +.. versionadded:: 3.9 + +Whether to use :prop_tgt:`INSTALL_NAME_DIR` on targets in the build tree. + +This variable is used to initialize the :prop_tgt:`BUILD_WITH_INSTALL_NAME_DIR` +property on all targets. diff --git a/Help/variable/CMAKE_BUILD_WITH_INSTALL_RPATH.rst b/Help/variable/CMAKE_BUILD_WITH_INSTALL_RPATH.rst new file mode 100644 index 0000000..5b59a6e --- /dev/null +++ b/Help/variable/CMAKE_BUILD_WITH_INSTALL_RPATH.rst @@ -0,0 +1,11 @@ +CMAKE_BUILD_WITH_INSTALL_RPATH +------------------------------ + +Use the install path for the ``RPATH``. + +Normally CMake uses the build tree for the ``RPATH`` when building +executables etc on systems that use ``RPATH``. When the software is +installed the executables etc are relinked by CMake to have the +install ``RPATH``. If this variable is set to true then the software is +always built with the install path for the ``RPATH`` and does not need to +be relinked when installed. diff --git a/Help/variable/CMAKE_CACHEFILE_DIR.rst b/Help/variable/CMAKE_CACHEFILE_DIR.rst new file mode 100644 index 0000000..8604d0e --- /dev/null +++ b/Help/variable/CMAKE_CACHEFILE_DIR.rst @@ -0,0 +1,7 @@ +CMAKE_CACHEFILE_DIR +------------------- + +The directory with the ``CMakeCache.txt`` file. + +This is the full path to the directory that has the ``CMakeCache.txt`` +file in it. This is the same as :variable:`CMAKE_BINARY_DIR`. diff --git a/Help/variable/CMAKE_CACHE_MAJOR_VERSION.rst b/Help/variable/CMAKE_CACHE_MAJOR_VERSION.rst new file mode 100644 index 0000000..1e53ed6 --- /dev/null +++ b/Help/variable/CMAKE_CACHE_MAJOR_VERSION.rst @@ -0,0 +1,8 @@ +CMAKE_CACHE_MAJOR_VERSION +------------------------- + +Major version of CMake used to create the ``CMakeCache.txt`` file + +This stores the major version of CMake used to write a CMake cache +file. It is only different when a different version of CMake is run +on a previously created cache file. diff --git a/Help/variable/CMAKE_CACHE_MINOR_VERSION.rst b/Help/variable/CMAKE_CACHE_MINOR_VERSION.rst new file mode 100644 index 0000000..5d174a3 --- /dev/null +++ b/Help/variable/CMAKE_CACHE_MINOR_VERSION.rst @@ -0,0 +1,8 @@ +CMAKE_CACHE_MINOR_VERSION +------------------------- + +Minor version of CMake used to create the ``CMakeCache.txt`` file + +This stores the minor version of CMake used to write a CMake cache +file. It is only different when a different version of CMake is run +on a previously created cache file. diff --git a/Help/variable/CMAKE_CACHE_PATCH_VERSION.rst b/Help/variable/CMAKE_CACHE_PATCH_VERSION.rst new file mode 100644 index 0000000..22d267c --- /dev/null +++ b/Help/variable/CMAKE_CACHE_PATCH_VERSION.rst @@ -0,0 +1,8 @@ +CMAKE_CACHE_PATCH_VERSION +------------------------- + +Patch version of CMake used to create the ``CMakeCache.txt`` file + +This stores the patch version of CMake used to write a CMake cache +file. It is only different when a different version of CMake is run +on a previously created cache file. diff --git a/Help/variable/CMAKE_CFG_INTDIR.rst b/Help/variable/CMAKE_CFG_INTDIR.rst new file mode 100644 index 0000000..842654e --- /dev/null +++ b/Help/variable/CMAKE_CFG_INTDIR.rst @@ -0,0 +1,52 @@ +CMAKE_CFG_INTDIR +---------------- + +Build-time reference to per-configuration output subdirectory. + +For native build systems supporting multiple configurations in the +build tree (such as :ref:`Visual Studio Generators` and :generator:`Xcode`), +the value is a reference to a build-time variable specifying the name +of the per-configuration output subdirectory. On :ref:`Makefile Generators` +this evaluates to `.` because there is only one configuration in a build tree. +Example values: + +:: + + $(ConfigurationName) = Visual Studio 9 + $(Configuration) = Visual Studio 10 + $(CONFIGURATION) = Xcode + . = Make-based tools + . = Ninja + ${CONFIGURATION} = Ninja Multi-Config + +Note that this variable only has limited support on +:generator:`Ninja Multi-Config`. It is recommended that you use the +``$<CONFIG>`` :manual:`generator expression <cmake-generator-expressions(7)>` +instead. + +Since these values are evaluated by the native build system, this +variable is suitable only for use in command lines that will be +evaluated at build time. Example of intended usage: + +:: + + add_executable(mytool mytool.c) + add_custom_command( + OUTPUT out.txt + COMMAND ${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_CFG_INTDIR}/mytool + ${CMAKE_CURRENT_SOURCE_DIR}/in.txt out.txt + DEPENDS mytool in.txt + ) + add_custom_target(drive ALL DEPENDS out.txt) + +Note that ``CMAKE_CFG_INTDIR`` is no longer necessary for this purpose but +has been left for compatibility with existing projects. Instead +:command:`add_custom_command` recognizes executable target names in its +``COMMAND`` option, so +``${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_CFG_INTDIR}/mytool`` can be replaced +by just ``mytool``. + +This variable is read-only. Setting it is undefined behavior. In +multi-configuration build systems the value of this variable is passed +as the value of preprocessor symbol ``CMAKE_INTDIR`` to the compilation +of all source files. diff --git a/Help/variable/CMAKE_CLANG_VFS_OVERLAY.rst b/Help/variable/CMAKE_CLANG_VFS_OVERLAY.rst new file mode 100644 index 0000000..56ac328 --- /dev/null +++ b/Help/variable/CMAKE_CLANG_VFS_OVERLAY.rst @@ -0,0 +1,9 @@ +CMAKE_CLANG_VFS_OVERLAY +----------------------- + +.. versionadded:: 3.19 + +When cross compiling for windows with clang-cl, this variable can be an +absolute path pointing to a clang virtual file system yaml file, which +will enable clang-cl to resolve windows header names on a case sensitive +file system. diff --git a/Help/variable/CMAKE_CL_64.rst b/Help/variable/CMAKE_CL_64.rst new file mode 100644 index 0000000..4e80d1f --- /dev/null +++ b/Help/variable/CMAKE_CL_64.rst @@ -0,0 +1,7 @@ +CMAKE_CL_64 +----------- + +Discouraged. Use :variable:`CMAKE_SIZEOF_VOID_P` instead. + +Set to a true value when using a Microsoft Visual Studio ``cl`` compiler that +*targets* a 64-bit architecture. diff --git a/Help/variable/CMAKE_CODEBLOCKS_COMPILER_ID.rst b/Help/variable/CMAKE_CODEBLOCKS_COMPILER_ID.rst new file mode 100644 index 0000000..0b2b0a0 --- /dev/null +++ b/Help/variable/CMAKE_CODEBLOCKS_COMPILER_ID.rst @@ -0,0 +1,15 @@ +CMAKE_CODEBLOCKS_COMPILER_ID +---------------------------- + +.. versionadded:: 3.11 + +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 0000000..dbb8606 --- /dev/null +++ b/Help/variable/CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES.rst @@ -0,0 +1,9 @@ +CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES +--------------------------------------- + +.. versionadded:: 3.10 + +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_CODELITE_USE_TARGETS.rst b/Help/variable/CMAKE_CODELITE_USE_TARGETS.rst new file mode 100644 index 0000000..21af5f7 --- /dev/null +++ b/Help/variable/CMAKE_CODELITE_USE_TARGETS.rst @@ -0,0 +1,10 @@ +CMAKE_CODELITE_USE_TARGETS +-------------------------- + +.. versionadded:: 3.7 + +Change the way the CodeLite generator creates projectfiles. + +If this variable evaluates to ``ON`` at the end of the top-level +``CMakeLists.txt`` file, the generator creates projectfiles based on targets +rather than projects. diff --git a/Help/variable/CMAKE_COLOR_MAKEFILE.rst b/Help/variable/CMAKE_COLOR_MAKEFILE.rst new file mode 100644 index 0000000..bb86ecc --- /dev/null +++ b/Help/variable/CMAKE_COLOR_MAKEFILE.rst @@ -0,0 +1,7 @@ +CMAKE_COLOR_MAKEFILE +-------------------- + +Enables color output when using the :ref:`Makefile Generators`. + +When enabled, the generated Makefiles will produce colored output. +Default is ``ON``. diff --git a/Help/variable/CMAKE_COMMAND.rst b/Help/variable/CMAKE_COMMAND.rst new file mode 100644 index 0000000..f80b46c --- /dev/null +++ b/Help/variable/CMAKE_COMMAND.rst @@ -0,0 +1,8 @@ +CMAKE_COMMAND +------------- + +The full path to the :manual:`cmake(1)` executable. + +This is the full path to the CMake executable :manual:`cmake(1)` which is +useful from custom commands that want to use the ``cmake -E`` option for +portable system commands. (e.g. ``/usr/local/bin/cmake``) diff --git a/Help/variable/CMAKE_COMPILER_2005.rst b/Help/variable/CMAKE_COMPILER_2005.rst new file mode 100644 index 0000000..134559b --- /dev/null +++ b/Help/variable/CMAKE_COMPILER_2005.rst @@ -0,0 +1,6 @@ +CMAKE_COMPILER_2005 +------------------- + +Using the Visual Studio 2005 compiler from Microsoft + +Set to true when using the Visual Studio 2005 compiler from Microsoft. diff --git a/Help/variable/CMAKE_COMPILER_IS_GNUCC.rst b/Help/variable/CMAKE_COMPILER_IS_GNUCC.rst new file mode 100644 index 0000000..91cf848 --- /dev/null +++ b/Help/variable/CMAKE_COMPILER_IS_GNUCC.rst @@ -0,0 +1,7 @@ +CMAKE_COMPILER_IS_GNUCC +----------------------- + +.. versionadded:: 3.7 + +True if the ``C`` compiler is GNU. +Use :variable:`CMAKE_C_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` instead. diff --git a/Help/variable/CMAKE_COMPILER_IS_GNUCXX.rst b/Help/variable/CMAKE_COMPILER_IS_GNUCXX.rst new file mode 100644 index 0000000..e67718a --- /dev/null +++ b/Help/variable/CMAKE_COMPILER_IS_GNUCXX.rst @@ -0,0 +1,7 @@ +CMAKE_COMPILER_IS_GNUCXX +------------------------ + +.. versionadded:: 3.7 + +True if the C++ (``CXX``) compiler is GNU. +Use :variable:`CMAKE_CXX_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` instead. diff --git a/Help/variable/CMAKE_COMPILER_IS_GNUG77.rst b/Help/variable/CMAKE_COMPILER_IS_GNUG77.rst new file mode 100644 index 0000000..f69c01a --- /dev/null +++ b/Help/variable/CMAKE_COMPILER_IS_GNUG77.rst @@ -0,0 +1,7 @@ +CMAKE_COMPILER_IS_GNUG77 +------------------------ + +.. versionadded:: 3.7 + +True if the ``Fortran`` compiler is GNU. +Use :variable:`CMAKE_Fortran_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` instead. diff --git a/Help/variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY.rst b/Help/variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY.rst new file mode 100644 index 0000000..11f52c7 --- /dev/null +++ b/Help/variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY.rst @@ -0,0 +1,10 @@ +CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY +---------------------------------- + +.. versionadded:: 3.1 + +Output directory for MS debug symbol ``.pdb`` files +generated by the compiler while building source files. + +This variable is used to initialize the +:prop_tgt:`COMPILE_PDB_OUTPUT_DIRECTORY` property on all the targets. diff --git a/Help/variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG.rst b/Help/variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG.rst new file mode 100644 index 0000000..99d0bdc --- /dev/null +++ b/Help/variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG.rst @@ -0,0 +1,13 @@ +CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG> +------------------------------------------- + +.. versionadded:: 3.1 + +Per-configuration output directory for MS debug symbol ``.pdb`` files +generated by the compiler while building source files. + +This is a per-configuration version of +:variable:`CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY`. +This variable is used to initialize the +:prop_tgt:`COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG>` +property on all the targets. diff --git a/Help/variable/CMAKE_CONFIGURATION_TYPES.rst b/Help/variable/CMAKE_CONFIGURATION_TYPES.rst new file mode 100644 index 0000000..34e99eb --- /dev/null +++ b/Help/variable/CMAKE_CONFIGURATION_TYPES.rst @@ -0,0 +1,10 @@ +CMAKE_CONFIGURATION_TYPES +------------------------- + +Specifies the available build types on multi-config generators. + +This specifies what build types (configurations) will be available +such as ``Debug``, ``Release``, ``RelWithDebInfo`` etc. This has reasonable +defaults on most platforms, but can be extended to provide other build +types. See also :variable:`CMAKE_BUILD_TYPE` for details of managing +configuration data, and :variable:`CMAKE_CFG_INTDIR`. diff --git a/Help/variable/CMAKE_CONFIG_POSTFIX.rst b/Help/variable/CMAKE_CONFIG_POSTFIX.rst new file mode 100644 index 0000000..e686a43 --- /dev/null +++ b/Help/variable/CMAKE_CONFIG_POSTFIX.rst @@ -0,0 +1,7 @@ +CMAKE_<CONFIG>_POSTFIX +---------------------- + +Default filename postfix for libraries under configuration ``<CONFIG>``. + +When a non-executable target is created its :prop_tgt:`<CONFIG>_POSTFIX` +target property is initialized with the value of this variable if it is set. diff --git a/Help/variable/CMAKE_CPACK_COMMAND.rst b/Help/variable/CMAKE_CPACK_COMMAND.rst new file mode 100644 index 0000000..3a81d68 --- /dev/null +++ b/Help/variable/CMAKE_CPACK_COMMAND.rst @@ -0,0 +1,10 @@ +CMAKE_CPACK_COMMAND +------------------- + +.. versionadded:: 3.13 + +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 new file mode 100644 index 0000000..7e6ec33 --- /dev/null +++ b/Help/variable/CMAKE_CROSSCOMPILING.rst @@ -0,0 +1,27 @@ +CMAKE_CROSSCOMPILING +-------------------- + +Intended to indicate whether CMake is cross compiling, but note limitations +discussed below. + +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 new file mode 100644 index 0000000..815da00 --- /dev/null +++ b/Help/variable/CMAKE_CROSSCOMPILING_EMULATOR.rst @@ -0,0 +1,18 @@ +CMAKE_CROSSCOMPILING_EMULATOR +----------------------------- + +.. versionadded:: 3.3 + +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. + +It is also used as the default value for the +:prop_tgt:`CROSSCOMPILING_EMULATOR` target property of executables. diff --git a/Help/variable/CMAKE_CROSS_CONFIGS.rst b/Help/variable/CMAKE_CROSS_CONFIGS.rst new file mode 100644 index 0000000..be921d6 --- /dev/null +++ b/Help/variable/CMAKE_CROSS_CONFIGS.rst @@ -0,0 +1,17 @@ +CMAKE_CROSS_CONFIGS +------------------- + +.. versionadded:: 3.17 + +Specifies a :ref:`semicolon-separated list <CMake Language Lists>` of +configurations available from all ``build-<Config>.ninja`` files in the +:generator:`Ninja Multi-Config` generator. This variable activates +cross-config mode. Targets from each config specified in this variable can be +built from any ``build-<Config>.ninja`` file. Custom commands will use the +configuration native to ``build-<Config>.ninja``. If it is set to ``all``, all +configurations from :variable:`CMAKE_CONFIGURATION_TYPES` are cross-configs. If +it is not specified, or empty, each ``build-<Config>.ninja`` file will only +contain build rules for its own configuration. + +The value of this variable must be a subset of +:variable:`CMAKE_CONFIGURATION_TYPES`. diff --git a/Help/variable/CMAKE_CTEST_ARGUMENTS.rst b/Help/variable/CMAKE_CTEST_ARGUMENTS.rst new file mode 100644 index 0000000..4dfc8fe --- /dev/null +++ b/Help/variable/CMAKE_CTEST_ARGUMENTS.rst @@ -0,0 +1,8 @@ +CMAKE_CTEST_ARGUMENTS +--------------------- + +.. versionadded:: 3.17 + +Set this to a :ref:`semicolon-separated list <CMake Language Lists>` of +command-line arguments to pass to :manual:`ctest(1)` when running tests +through the ``test`` (or ``RUN_TESTS``) target of the generated build system. diff --git a/Help/variable/CMAKE_CTEST_COMMAND.rst b/Help/variable/CMAKE_CTEST_COMMAND.rst new file mode 100644 index 0000000..b2942e2 --- /dev/null +++ b/Help/variable/CMAKE_CTEST_COMMAND.rst @@ -0,0 +1,8 @@ +CMAKE_CTEST_COMMAND +------------------- + +Full path to :manual:`ctest(1)` command installed with CMake. + +This is the full path to the CTest executable :manual:`ctest(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_CUDA_ARCHITECTURES.rst b/Help/variable/CMAKE_CUDA_ARCHITECTURES.rst new file mode 100644 index 0000000..d885516 --- /dev/null +++ b/Help/variable/CMAKE_CUDA_ARCHITECTURES.rst @@ -0,0 +1,35 @@ +CMAKE_CUDA_ARCHITECTURES +------------------------ + +.. versionadded:: 3.18 + +Default value for :prop_tgt:`CUDA_ARCHITECTURES` property of targets. + +Initialized by the :envvar:`CUDAARCHS` environment variable if set. +Otherwise as follows depending on :variable:`CMAKE_CUDA_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>`: + +- For ``Clang``: the oldest architecture that works. + +- For ``NVIDIA``: the default architecture chosen by the compiler. + See policy :policy:`CMP0104`. + +Users are encouraged to override this, as the default varies across compilers +and compiler versions. + +This variable is used to initialize the :prop_tgt:`CUDA_ARCHITECTURES` property +on all targets. See the target property for additional information. + +Examples +^^^^^^^^ + +.. code-block:: cmake + + cmake_minimum_required(VERSION) + + if(NOT DEFINED CMAKE_CUDA_ARCHITECTURES) + set(CMAKE_CUDA_ARCHITECTURES 75) + endif() + + project(example LANGUAGES CUDA) + +``CMAKE_CUDA_ARCHITECTURES`` will default to ``75`` unless overridden by the user. diff --git a/Help/variable/CMAKE_CUDA_COMPILE_FEATURES.rst b/Help/variable/CMAKE_CUDA_COMPILE_FEATURES.rst new file mode 100644 index 0000000..c1c270c --- /dev/null +++ b/Help/variable/CMAKE_CUDA_COMPILE_FEATURES.rst @@ -0,0 +1,13 @@ +CMAKE_CUDA_COMPILE_FEATURES +--------------------------- + +.. versionadded:: 3.17 + +List of features known to the CUDA compiler + +These features are known to be available for use with the CUDA compiler. This +list is a subset of the features listed in the +:prop_gbl:`CMAKE_CUDA_KNOWN_FEATURES` global property. + +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_CUDA_EXTENSIONS.rst b/Help/variable/CMAKE_CUDA_EXTENSIONS.rst new file mode 100644 index 0000000..b86c0ea --- /dev/null +++ b/Help/variable/CMAKE_CUDA_EXTENSIONS.rst @@ -0,0 +1,13 @@ +CMAKE_CUDA_EXTENSIONS +--------------------- + +.. versionadded:: 3.8 + +Default value for :prop_tgt:`CUDA_EXTENSIONS` property of targets. + +This variable is used to initialize the :prop_tgt:`CUDA_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_CUDA_HOST_COMPILER.rst b/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst new file mode 100644 index 0000000..d5fcb7d --- /dev/null +++ b/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst @@ -0,0 +1,25 @@ +CMAKE_CUDA_HOST_COMPILER +------------------------ + +.. versionadded:: 3.10 + +When :variable:`CMAKE_CUDA_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` is +``NVIDIA``, ``CMAKE_CUDA_HOST_COMPILER`` selects the compiler executable to use +when compiling host code for ``CUDA`` language files. +This maps to the ``nvcc -ccbin`` option. + +The ``CMAKE_CUDA_HOST_COMPILER`` variable may be set explicitly before CUDA is +first enabled by a :command:`project` or :command:`enable_language` command. +This can be done via ``-DCMAKE_CUDA_HOST_COMPILER=...`` on the command line +or in a :ref:`toolchain file <Cross Compiling Toolchain>`. Or, one may set +the :envvar:`CUDAHOSTCXX` environment variable to provide a default value. + +Once the CUDA language is enabled, the ``CMAKE_CUDA_HOST_COMPILER`` variable +is read-only and changes to it are undefined behavior. + +.. note:: + + Since ``CMAKE_CUDA_HOST_COMPILER`` is meaningful only when the + :variable:`CMAKE_CUDA_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` is ``NVIDIA``, + it does not make sense to set ``CMAKE_CUDA_HOST_COMPILER`` without also + setting ``CMAKE_CUDA_COMPILER`` to NVCC. 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 0000000..474baee --- /dev/null +++ b/Help/variable/CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS.rst @@ -0,0 +1,8 @@ +CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS +--------------------------------- + +.. versionadded:: 3.16 + +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_RUNTIME_LIBRARY.rst b/Help/variable/CMAKE_CUDA_RUNTIME_LIBRARY.rst new file mode 100644 index 0000000..69b9d93 --- /dev/null +++ b/Help/variable/CMAKE_CUDA_RUNTIME_LIBRARY.rst @@ -0,0 +1,27 @@ +CMAKE_CUDA_RUNTIME_LIBRARY +-------------------------- + +.. versionadded:: 3.17 + +Select the CUDA runtime library for use when compiling and linking CUDA. +This variable is used to initialize the :prop_tgt:`CUDA_RUNTIME_LIBRARY` +property on all targets as they are created. + +The allowed case insensitive values are: + +.. include:: ../prop_tgt/CUDA_RUNTIME_LIBRARY-VALUES.txt + +Contents of ``CMAKE_CUDA_RUNTIME_LIBRARY`` may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. + +If this variable is not set then the :prop_tgt:`CUDA_RUNTIME_LIBRARY` target +property will not be set automatically. If that property is not set then +CMake uses an appropriate default value based on the compiler to select the +CUDA runtime library. + +.. note:: + + This property has effect only when the ``CUDA`` language is enabled. To + control the CUDA runtime linking when only using the CUDA SDK with the + ``C`` or ``C++`` language we recommend using the :module:`FindCUDAToolkit` + module. diff --git a/Help/variable/CMAKE_CUDA_SEPARABLE_COMPILATION.rst b/Help/variable/CMAKE_CUDA_SEPARABLE_COMPILATION.rst new file mode 100644 index 0000000..3dbaef9 --- /dev/null +++ b/Help/variable/CMAKE_CUDA_SEPARABLE_COMPILATION.rst @@ -0,0 +1,8 @@ +CMAKE_CUDA_SEPARABLE_COMPILATION +-------------------------------- + +.. versionadded:: 3.11 + +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_STANDARD.rst b/Help/variable/CMAKE_CUDA_STANDARD.rst new file mode 100644 index 0000000..798ab1e --- /dev/null +++ b/Help/variable/CMAKE_CUDA_STANDARD.rst @@ -0,0 +1,13 @@ +CMAKE_CUDA_STANDARD +------------------- + +.. versionadded:: 3.8 + +Default value for :prop_tgt:`CUDA_STANDARD` property of targets. + +This variable is used to initialize the :prop_tgt:`CUDA_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_CUDA_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_CUDA_STANDARD_REQUIRED.rst new file mode 100644 index 0000000..ae2f52f --- /dev/null +++ b/Help/variable/CMAKE_CUDA_STANDARD_REQUIRED.rst @@ -0,0 +1,13 @@ +CMAKE_CUDA_STANDARD_REQUIRED +---------------------------- + +.. versionadded:: 3.8 + +Default value for :prop_tgt:`CUDA_STANDARD_REQUIRED` property of targets. + +This variable is used to initialize the :prop_tgt:`CUDA_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_CUDA_TOOLKIT_INCLUDE_DIRECTORIES.rst b/Help/variable/CMAKE_CUDA_TOOLKIT_INCLUDE_DIRECTORIES.rst new file mode 100644 index 0000000..e586dab --- /dev/null +++ b/Help/variable/CMAKE_CUDA_TOOLKIT_INCLUDE_DIRECTORIES.rst @@ -0,0 +1,9 @@ +CMAKE_CUDA_TOOLKIT_INCLUDE_DIRECTORIES +-------------------------------------- + +.. versionadded:: 3.8 + +When the ``CUDA`` language has been enabled, this provides a +: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_CURRENT_BINARY_DIR.rst b/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst new file mode 100644 index 0000000..40496b5 --- /dev/null +++ b/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst @@ -0,0 +1,15 @@ +CMAKE_CURRENT_BINARY_DIR +------------------------ + +The path to the binary directory currently being processed. + +This the full path to the build directory that is currently being +processed by cmake. Each directory added by :command:`add_subdirectory` will +create a binary directory in the build tree, and as it is being +processed this variable will be set. For in-source builds this is the +current source directory being processed. + +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_CURRENT_FUNCTION.rst b/Help/variable/CMAKE_CURRENT_FUNCTION.rst new file mode 100644 index 0000000..5d1a4e9 --- /dev/null +++ b/Help/variable/CMAKE_CURRENT_FUNCTION.rst @@ -0,0 +1,12 @@ +CMAKE_CURRENT_FUNCTION +---------------------- + +.. versionadded:: 3.17 + +When executing code inside a :command:`function`, this variable +contains the name of the current function. It can be useful for +diagnostic or debug messages. + +See also :variable:`CMAKE_CURRENT_FUNCTION_LIST_DIR`, +:variable:`CMAKE_CURRENT_FUNCTION_LIST_FILE` and +:variable:`CMAKE_CURRENT_FUNCTION_LIST_LINE`. diff --git a/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_DIR.rst b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_DIR.rst new file mode 100644 index 0000000..f8f553d --- /dev/null +++ b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_DIR.rst @@ -0,0 +1,43 @@ +CMAKE_CURRENT_FUNCTION_LIST_DIR +------------------------------- + +.. versionadded:: 3.17 + +When executing code inside a :command:`function`, this variable +contains the full directory of the listfile that defined the current function. + +It is quite common practice in CMake for modules to use some additional files, +such as templates to be copied in after substituting CMake variables. +In such cases, a function needs to know where to locate those files in a way +that doesn't depend on where the function is called. Without +``CMAKE_CURRENT_FUNCTION_LIST_DIR``, the code to do that would typically use +the following pattern: + +.. code-block:: cmake + + set(_THIS_MODULE_BASE_DIR "${CMAKE_CURRENT_LIST_DIR}") + + function(foo) + configure_file( + "${_THIS_MODULE_BASE_DIR}/some.template.in" + some.output + ) + endfunction() + +Using ``CMAKE_CURRENT_FUNCTION_LIST_DIR`` inside the function instead +eliminates the need for the extra variable which would otherwise be visible +outside the function's scope. +The above example can be written in the more concise and more robust form: + +.. code-block:: cmake + + function(foo) + configure_file( + "${CMAKE_CURRENT_FUNCTION_LIST_DIR}/some.template.in" + some.output + ) + endfunction() + +See also :variable:`CMAKE_CURRENT_FUNCTION`, +:variable:`CMAKE_CURRENT_FUNCTION_LIST_FILE` and +:variable:`CMAKE_CURRENT_FUNCTION_LIST_LINE`. diff --git a/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_FILE.rst b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_FILE.rst new file mode 100644 index 0000000..437dfec --- /dev/null +++ b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_FILE.rst @@ -0,0 +1,11 @@ +CMAKE_CURRENT_FUNCTION_LIST_FILE +-------------------------------- + +.. versionadded:: 3.17 + +When executing code inside a :command:`function`, this variable +contains the full path to the listfile that defined the current function. + +See also :variable:`CMAKE_CURRENT_FUNCTION`, +:variable:`CMAKE_CURRENT_FUNCTION_LIST_DIR` and +:variable:`CMAKE_CURRENT_FUNCTION_LIST_LINE`. diff --git a/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_LINE.rst b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_LINE.rst new file mode 100644 index 0000000..2fc7012 --- /dev/null +++ b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_LINE.rst @@ -0,0 +1,12 @@ +CMAKE_CURRENT_FUNCTION_LIST_LINE +-------------------------------- + +.. versionadded:: 3.17 + +When executing code inside a :command:`function`, this variable +contains the line number in the listfile where the current function +was defined. + +See also :variable:`CMAKE_CURRENT_FUNCTION`, +:variable:`CMAKE_CURRENT_FUNCTION_LIST_DIR` and +:variable:`CMAKE_CURRENT_FUNCTION_LIST_FILE`. diff --git a/Help/variable/CMAKE_CURRENT_LIST_DIR.rst b/Help/variable/CMAKE_CURRENT_LIST_DIR.rst new file mode 100644 index 0000000..ebc3ab9 --- /dev/null +++ b/Help/variable/CMAKE_CURRENT_LIST_DIR.rst @@ -0,0 +1,17 @@ +CMAKE_CURRENT_LIST_DIR +---------------------- + +Full directory of the listfile currently being processed. + +As CMake processes the listfiles in your project this variable will +always be set to the directory where the listfile which is currently +being processed (:variable:`CMAKE_CURRENT_LIST_FILE`) is located. The value +has dynamic scope. When CMake starts processing commands in a source file +it sets this variable to the directory where this file is located. +When CMake finishes processing commands from the file it restores the +previous value. Therefore the value of the variable inside a macro or +function is the directory of the file invoking the bottom-most entry +on the call stack, not the directory of the file containing the macro +or function definition. + +See also :variable:`CMAKE_CURRENT_LIST_FILE`. diff --git a/Help/variable/CMAKE_CURRENT_LIST_FILE.rst b/Help/variable/CMAKE_CURRENT_LIST_FILE.rst new file mode 100644 index 0000000..84b0eee --- /dev/null +++ b/Help/variable/CMAKE_CURRENT_LIST_FILE.rst @@ -0,0 +1,15 @@ +CMAKE_CURRENT_LIST_FILE +----------------------- + +Full path to the listfile currently being processed. + +As CMake processes the listfiles in your project this variable will +always be set to the one currently being processed. The value has +dynamic scope. When CMake starts processing commands in a source file +it sets this variable to the location of the file. When CMake +finishes processing commands from the file it restores the previous +value. Therefore the value of the variable inside a macro or function +is the file invoking the bottom-most entry on the call stack, not the +file containing the macro or function definition. + +See also :variable:`CMAKE_PARENT_LIST_FILE`. diff --git a/Help/variable/CMAKE_CURRENT_LIST_LINE.rst b/Help/variable/CMAKE_CURRENT_LIST_LINE.rst new file mode 100644 index 0000000..7f839c2 --- /dev/null +++ b/Help/variable/CMAKE_CURRENT_LIST_LINE.rst @@ -0,0 +1,11 @@ +CMAKE_CURRENT_LIST_LINE +----------------------- + +The line number of the current file being processed. + +This is the line number of the file currently being processed by +cmake. + +If CMake is currently processing deferred calls scheduled by +the :command:`cmake_language(DEFER)` command, this variable +evaluates to ``DEFERRED`` instead of a specific line number. diff --git a/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst b/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst new file mode 100644 index 0000000..c1b755a --- /dev/null +++ b/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst @@ -0,0 +1,12 @@ +CMAKE_CURRENT_SOURCE_DIR +------------------------ + +The path to the source directory currently being processed. + +This the full path to the source directory that is currently being +processed by cmake. + +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_CXX_COMPILE_FEATURES.rst b/Help/variable/CMAKE_CXX_COMPILE_FEATURES.rst new file mode 100644 index 0000000..8fcfbae --- /dev/null +++ b/Help/variable/CMAKE_CXX_COMPILE_FEATURES.rst @@ -0,0 +1,13 @@ +CMAKE_CXX_COMPILE_FEATURES +-------------------------- + +.. versionadded:: 3.1 + +List of features known to the C++ compiler + +These features are known to be available for use with the C++ compiler. This +list is a subset of the features listed in the +:prop_gbl:`CMAKE_CXX_KNOWN_FEATURES` global property. + +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_CXX_EXTENSIONS.rst b/Help/variable/CMAKE_CXX_EXTENSIONS.rst new file mode 100644 index 0000000..ea8c4be --- /dev/null +++ b/Help/variable/CMAKE_CXX_EXTENSIONS.rst @@ -0,0 +1,13 @@ +CMAKE_CXX_EXTENSIONS +-------------------- + +.. versionadded:: 3.1 + +Default value for :prop_tgt:`CXX_EXTENSIONS` property of targets. + +This variable is used to initialize the :prop_tgt:`CXX_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_CXX_STANDARD.rst b/Help/variable/CMAKE_CXX_STANDARD.rst new file mode 100644 index 0000000..8ef8c80 --- /dev/null +++ b/Help/variable/CMAKE_CXX_STANDARD.rst @@ -0,0 +1,13 @@ +CMAKE_CXX_STANDARD +------------------ + +.. versionadded:: 3.1 + +Default value for :prop_tgt:`CXX_STANDARD` property of targets. + +This variable is used to initialize the :prop_tgt:`CXX_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_CXX_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_CXX_STANDARD_REQUIRED.rst new file mode 100644 index 0000000..f7b2ae9 --- /dev/null +++ b/Help/variable/CMAKE_CXX_STANDARD_REQUIRED.rst @@ -0,0 +1,13 @@ +CMAKE_CXX_STANDARD_REQUIRED +--------------------------- + +.. versionadded:: 3.1 + +Default value for :prop_tgt:`CXX_STANDARD_REQUIRED` property of targets. + +This variable is used to initialize the :prop_tgt:`CXX_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_C_COMPILE_FEATURES.rst b/Help/variable/CMAKE_C_COMPILE_FEATURES.rst new file mode 100644 index 0000000..2b306a3 --- /dev/null +++ b/Help/variable/CMAKE_C_COMPILE_FEATURES.rst @@ -0,0 +1,13 @@ +CMAKE_C_COMPILE_FEATURES +------------------------ + +.. versionadded:: 3.1 + +List of features known to the C compiler + +These features are known to be available for use with the C compiler. This +list is a subset of the features listed in the +:prop_gbl:`CMAKE_C_KNOWN_FEATURES` global property. + +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_C_EXTENSIONS.rst b/Help/variable/CMAKE_C_EXTENSIONS.rst new file mode 100644 index 0000000..fce8fc7 --- /dev/null +++ b/Help/variable/CMAKE_C_EXTENSIONS.rst @@ -0,0 +1,13 @@ +CMAKE_C_EXTENSIONS +------------------ + +.. versionadded:: 3.1 + +Default value for :prop_tgt:`C_EXTENSIONS` property of targets. + +This variable is used to initialize the :prop_tgt:`C_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_C_STANDARD.rst b/Help/variable/CMAKE_C_STANDARD.rst new file mode 100644 index 0000000..64ef8ce --- /dev/null +++ b/Help/variable/CMAKE_C_STANDARD.rst @@ -0,0 +1,13 @@ +CMAKE_C_STANDARD +---------------- + +.. versionadded:: 3.1 + +Default value for :prop_tgt:`C_STANDARD` property of targets. + +This variable is used to initialize the :prop_tgt:`C_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_C_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_C_STANDARD_REQUIRED.rst new file mode 100644 index 0000000..e70b6bd --- /dev/null +++ b/Help/variable/CMAKE_C_STANDARD_REQUIRED.rst @@ -0,0 +1,13 @@ +CMAKE_C_STANDARD_REQUIRED +------------------------- + +.. versionadded:: 3.1 + +Default value for :prop_tgt:`C_STANDARD_REQUIRED` property of targets. + +This variable is used to initialize the :prop_tgt:`C_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_DEBUG_POSTFIX.rst b/Help/variable/CMAKE_DEBUG_POSTFIX.rst new file mode 100644 index 0000000..08577a5 --- /dev/null +++ b/Help/variable/CMAKE_DEBUG_POSTFIX.rst @@ -0,0 +1,7 @@ +CMAKE_DEBUG_POSTFIX +------------------- + +See variable :variable:`CMAKE_<CONFIG>_POSTFIX`. + +This variable is a special case of the more-general +:variable:`CMAKE_<CONFIG>_POSTFIX` variable for the `DEBUG` configuration. diff --git a/Help/variable/CMAKE_DEBUG_TARGET_PROPERTIES.rst b/Help/variable/CMAKE_DEBUG_TARGET_PROPERTIES.rst new file mode 100644 index 0000000..a1fa1ff --- /dev/null +++ b/Help/variable/CMAKE_DEBUG_TARGET_PROPERTIES.rst @@ -0,0 +1,23 @@ +CMAKE_DEBUG_TARGET_PROPERTIES +----------------------------- + +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: + +* :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_DEFAULT_BUILD_TYPE.rst b/Help/variable/CMAKE_DEFAULT_BUILD_TYPE.rst new file mode 100644 index 0000000..cadbf3a --- /dev/null +++ b/Help/variable/CMAKE_DEFAULT_BUILD_TYPE.rst @@ -0,0 +1,14 @@ +CMAKE_DEFAULT_BUILD_TYPE +------------------------ + +.. versionadded:: 3.17 + +Specifies the configuration to use by default in a ``build.ninja`` file in the +:generator:`Ninja Multi-Config` generator. If this variable is specified, +``build.ninja`` uses build rules from ``build-<Config>.ninja`` by default. All +custom commands are executed with this configuration. If the variable is not +specified, the first item from :variable:`CMAKE_CONFIGURATION_TYPES` is used +instead. + +The value of this variable must be one of the items from +:variable:`CMAKE_CONFIGURATION_TYPES`. diff --git a/Help/variable/CMAKE_DEFAULT_CONFIGS.rst b/Help/variable/CMAKE_DEFAULT_CONFIGS.rst new file mode 100644 index 0000000..65a5f0d --- /dev/null +++ b/Help/variable/CMAKE_DEFAULT_CONFIGS.rst @@ -0,0 +1,21 @@ +CMAKE_DEFAULT_CONFIGS +--------------------- + +.. versionadded:: 3.17 + +Specifies a :ref:`semicolon-separated list <CMake Language Lists>` of configurations +to build for a target in ``build.ninja`` if no ``:<Config>`` suffix is specified in +the :generator:`Ninja Multi-Config` generator. If it is set to ``all``, all +configurations from :variable:`CMAKE_CROSS_CONFIGS` are used. If it is not +specified, it defaults to :variable:`CMAKE_DEFAULT_BUILD_TYPE`. + +For example, if you set :variable:`CMAKE_DEFAULT_BUILD_TYPE` to ``Release``, +but set :variable:`CMAKE_DEFAULT_CONFIGS` to ``Debug`` or ``all``, all +``<target>`` aliases in ``build.ninja`` will resolve to ``<target>:Debug`` or +``<target>:all``, but custom commands will still use the ``Release`` +configuration. + +The value of this variable must be a subset of :variable:`CMAKE_CROSS_CONFIGS` +or be the same as :variable:`CMAKE_DEFAULT_BUILD_TYPE`. It must not be +specified if :variable:`CMAKE_DEFAULT_BUILD_TYPE` or +:variable:`CMAKE_CROSS_CONFIGS` is not used. diff --git a/Help/variable/CMAKE_DEPENDS_IN_PROJECT_ONLY.rst b/Help/variable/CMAKE_DEPENDS_IN_PROJECT_ONLY.rst new file mode 100644 index 0000000..bfe9402 --- /dev/null +++ b/Help/variable/CMAKE_DEPENDS_IN_PROJECT_ONLY.rst @@ -0,0 +1,12 @@ +CMAKE_DEPENDS_IN_PROJECT_ONLY +----------------------------- + +.. versionadded:: 3.6 + +When set to ``TRUE`` in a directory, the build system produced by the +:ref:`Makefile Generators` is set up to only consider dependencies on source +files that appear either in the source or in the binary directories. Changes +to source files outside of these directories will not cause rebuilds. + +This should be used carefully in cases where some source files are picked up +through external headers during the build. diff --git a/Help/variable/CMAKE_DEPENDS_USE_COMPILER.rst b/Help/variable/CMAKE_DEPENDS_USE_COMPILER.rst new file mode 100644 index 0000000..bdad59e --- /dev/null +++ b/Help/variable/CMAKE_DEPENDS_USE_COMPILER.rst @@ -0,0 +1,9 @@ +CMAKE_DEPENDS_USE_COMPILER +-------------------------- + +.. versionadded:: 3.20 + +For the :ref:`Makefile Generators`, source dependencies are now, for a +selection of compilers, generated by the compiler itself. By defining this +variable with value ``FALSE``, you can restore the legacy behavior (i.e. using +``CMake`` for dependencies discovery). diff --git a/Help/variable/CMAKE_DIRECTORY_LABELS.rst b/Help/variable/CMAKE_DIRECTORY_LABELS.rst new file mode 100644 index 0000000..81d6dd1 --- /dev/null +++ b/Help/variable/CMAKE_DIRECTORY_LABELS.rst @@ -0,0 +1,8 @@ +CMAKE_DIRECTORY_LABELS +----------------------- + +.. versionadded:: 3.10 + +Specify labels for the current directory. + +This is used to initialize the :prop_dir:`LABELS` directory property. diff --git a/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst b/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst new file mode 100644 index 0000000..ed60020 --- /dev/null +++ b/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst @@ -0,0 +1,16 @@ +CMAKE_DISABLE_FIND_PACKAGE_<PackageName> +---------------------------------------- + +Variable for disabling :command:`find_package` calls. + +Every non-``REQUIRED`` :command:`find_package` call in a project can be +disabled by setting the variable +``CMAKE_DISABLE_FIND_PACKAGE_<PackageName>`` to ``TRUE``. +This can be used to build a project without an optional package, +although that package is installed. + +This switch should be used during the initial CMake run. Otherwise if +the package has already been found in a previous CMake run, the +variables which have been stored in the cache will still be there. In +that case it is recommended to remove the cache variables for this +package from the cache using the cache editor or :manual:`cmake(1)` ``-U`` diff --git a/Help/variable/CMAKE_DISABLE_PRECOMPILE_HEADERS.rst b/Help/variable/CMAKE_DISABLE_PRECOMPILE_HEADERS.rst new file mode 100644 index 0000000..cf52776 --- /dev/null +++ b/Help/variable/CMAKE_DISABLE_PRECOMPILE_HEADERS.rst @@ -0,0 +1,8 @@ +CMAKE_DISABLE_PRECOMPILE_HEADERS +-------------------------------- + +.. versionadded:: 3.16 + +Default value for :prop_tgt:`DISABLE_PRECOMPILE_HEADERS` of targets. + +By default ``CMAKE_DISABLE_PRECOMPILE_HEADERS`` is ``OFF``. diff --git a/Help/variable/CMAKE_DL_LIBS.rst b/Help/variable/CMAKE_DL_LIBS.rst new file mode 100644 index 0000000..50d313d --- /dev/null +++ b/Help/variable/CMAKE_DL_LIBS.rst @@ -0,0 +1,7 @@ +CMAKE_DL_LIBS +------------- + +Name of library containing ``dlopen`` and ``dlclose``. + +The name of the library that has ``dlopen`` and ``dlclose`` in it, usually +``-ldl`` on most UNIX machines. diff --git a/Help/variable/CMAKE_DOTNET_TARGET_FRAMEWORK.rst b/Help/variable/CMAKE_DOTNET_TARGET_FRAMEWORK.rst new file mode 100644 index 0000000..29249d6 --- /dev/null +++ b/Help/variable/CMAKE_DOTNET_TARGET_FRAMEWORK.rst @@ -0,0 +1,18 @@ +CMAKE_DOTNET_TARGET_FRAMEWORK +----------------------------- + +.. versionadded:: 3.17 + +Default value for :prop_tgt:`DOTNET_TARGET_FRAMEWORK` property of +targets. + +This variable is used to initialize the +:prop_tgt:`DOTNET_TARGET_FRAMEWORK` property on all targets. See that +target property for additional information. + +Setting ``CMAKE_DOTNET_TARGET_FRAMEWORK`` 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_DOTNET_TARGET_FRAMEWORK_VERSION.rst b/Help/variable/CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION.rst new file mode 100644 index 0000000..fc3c360 --- /dev/null +++ b/Help/variable/CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION.rst @@ -0,0 +1,22 @@ +CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION +------------------------------------- + +.. versionadded:: 3.12 + +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. When set, +:variable:`CMAKE_DOTNET_TARGET_FRAMEWORK` takes precednece over this +variable. See that variable or the associated target property +:prop_tgt:`DOTNET_TARGET_FRAMEWORK` 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_GENERATE_LINKED_RESOURCES.rst b/Help/variable/CMAKE_ECLIPSE_GENERATE_LINKED_RESOURCES.rst new file mode 100644 index 0000000..548c563 --- /dev/null +++ b/Help/variable/CMAKE_ECLIPSE_GENERATE_LINKED_RESOURCES.rst @@ -0,0 +1,12 @@ +CMAKE_ECLIPSE_GENERATE_LINKED_RESOURCES +--------------------------------------- + +.. versionadded:: 3.6 + +This cache variable is used by the Eclipse project generator. See +:manual:`cmake-generators(7)`. + +The Eclipse project generator generates so-called linked resources +e.g. to the subproject root dirs in the source tree or to the source files +of targets. +This can be disabled by setting this variable to FALSE. diff --git a/Help/variable/CMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT.rst b/Help/variable/CMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT.rst new file mode 100644 index 0000000..fc28ebb --- /dev/null +++ b/Help/variable/CMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT.rst @@ -0,0 +1,13 @@ +CMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT +------------------------------------- + +.. versionadded:: 3.6 + +This cache variable is used by the Eclipse project generator. See +:manual:`cmake-generators(7)`. + +If this variable is set to TRUE, the Eclipse project generator will generate +an Eclipse project in :variable:`CMAKE_SOURCE_DIR` . This project can then +be used in Eclipse e.g. for the version control functionality. +:variable:`CMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT` defaults to FALSE; so +nothing is written into the source directory. diff --git a/Help/variable/CMAKE_ECLIPSE_MAKE_ARGUMENTS.rst b/Help/variable/CMAKE_ECLIPSE_MAKE_ARGUMENTS.rst new file mode 100644 index 0000000..90e36f5 --- /dev/null +++ b/Help/variable/CMAKE_ECLIPSE_MAKE_ARGUMENTS.rst @@ -0,0 +1,11 @@ +CMAKE_ECLIPSE_MAKE_ARGUMENTS +---------------------------- + +.. versionadded:: 3.6 + +This cache variable is used by the Eclipse project generator. See +:manual:`cmake-generators(7)`. + +This variable holds arguments which are used when Eclipse invokes the make +tool. By default it is initialized to hold flags to enable parallel builds +(using -j typically). diff --git a/Help/variable/CMAKE_ECLIPSE_RESOURCE_ENCODING.rst b/Help/variable/CMAKE_ECLIPSE_RESOURCE_ENCODING.rst new file mode 100644 index 0000000..492acd8 --- /dev/null +++ b/Help/variable/CMAKE_ECLIPSE_RESOURCE_ENCODING.rst @@ -0,0 +1,8 @@ +CMAKE_ECLIPSE_RESOURCE_ENCODING +------------------------------- + +.. versionadded:: 3.16 + +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_ECLIPSE_VERSION.rst b/Help/variable/CMAKE_ECLIPSE_VERSION.rst new file mode 100644 index 0000000..db65d89 --- /dev/null +++ b/Help/variable/CMAKE_ECLIPSE_VERSION.rst @@ -0,0 +1,12 @@ +CMAKE_ECLIPSE_VERSION +--------------------- + +.. versionadded:: 3.6 + +This cache variable is used by the Eclipse project generator. See +:manual:`cmake-generators(7)`. + +When using the Eclipse project generator, CMake tries to find the Eclipse +executable and detect the version of it. Depending on the version it finds, +some features are enabled or disabled. If CMake doesn't find +Eclipse, it assumes the oldest supported version, Eclipse Callisto (3.2). diff --git a/Help/variable/CMAKE_EDIT_COMMAND.rst b/Help/variable/CMAKE_EDIT_COMMAND.rst new file mode 100644 index 0000000..2f4ab1f --- /dev/null +++ b/Help/variable/CMAKE_EDIT_COMMAND.rst @@ -0,0 +1,8 @@ +CMAKE_EDIT_COMMAND +------------------ + +Full path to :manual:`cmake-gui(1)` or :manual:`ccmake(1)`. Defined only for +:ref:`Makefile Generators` when not using an "extra" generator for an IDE. + +This is the full path to the CMake executable that can graphically +edit the cache. For example, :manual:`cmake-gui(1)` or :manual:`ccmake(1)`. diff --git a/Help/variable/CMAKE_ENABLE_EXPORTS.rst b/Help/variable/CMAKE_ENABLE_EXPORTS.rst new file mode 100644 index 0000000..9f43de3 --- /dev/null +++ b/Help/variable/CMAKE_ENABLE_EXPORTS.rst @@ -0,0 +1,10 @@ +CMAKE_ENABLE_EXPORTS +-------------------- + +.. versionadded:: 3.4 + +Specify whether executables export symbols for loadable modules. + +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_ERROR_DEPRECATED.rst b/Help/variable/CMAKE_ERROR_DEPRECATED.rst new file mode 100644 index 0000000..f3a6738 --- /dev/null +++ b/Help/variable/CMAKE_ERROR_DEPRECATED.rst @@ -0,0 +1,7 @@ +CMAKE_ERROR_DEPRECATED +---------------------- + +Whether to issue errors for deprecated functionality. + +If ``TRUE``, use of deprecated functionality will issue fatal errors. +If this variable is not set, CMake behaves as if it were set to ``FALSE``. diff --git a/Help/variable/CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION.rst b/Help/variable/CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION.rst new file mode 100644 index 0000000..38e9b7b --- /dev/null +++ b/Help/variable/CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION.rst @@ -0,0 +1,10 @@ +CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION +------------------------------------------- + +Ask ``cmake_install.cmake`` script 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. This variable is used by CMake-generated +``cmake_install.cmake`` scripts. If one sets this variable to ``ON`` while +running the script, it may get fatal error messages from the script. diff --git a/Help/variable/CMAKE_EXECUTABLE_SUFFIX.rst b/Help/variable/CMAKE_EXECUTABLE_SUFFIX.rst new file mode 100644 index 0000000..356590f --- /dev/null +++ b/Help/variable/CMAKE_EXECUTABLE_SUFFIX.rst @@ -0,0 +1,9 @@ +CMAKE_EXECUTABLE_SUFFIX +----------------------- + +The suffix for executables on this platform. + +The suffix to use for the end of an executable filename if any, ``.exe`` +on Windows. + +``CMAKE_EXECUTABLE_SUFFIX_<LANG>`` overrides this for language ``<LANG>``. 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 0000000..90a16c3 --- /dev/null +++ b/Help/variable/CMAKE_EXECUTE_PROCESS_COMMAND_ECHO.rst @@ -0,0 +1,8 @@ +CMAKE_EXECUTE_PROCESS_COMMAND_ECHO +---------------------------------- + +.. versionadded:: 3.15 + +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_EXE_LINKER_FLAGS.rst b/Help/variable/CMAKE_EXE_LINKER_FLAGS.rst new file mode 100644 index 0000000..9e108f8 --- /dev/null +++ b/Help/variable/CMAKE_EXE_LINKER_FLAGS.rst @@ -0,0 +1,6 @@ +CMAKE_EXE_LINKER_FLAGS +---------------------- + +Linker flags to be used to create executables. + +These flags will be used by the linker when creating an executable. diff --git a/Help/variable/CMAKE_EXE_LINKER_FLAGS_CONFIG.rst b/Help/variable/CMAKE_EXE_LINKER_FLAGS_CONFIG.rst new file mode 100644 index 0000000..0cd8113 --- /dev/null +++ b/Help/variable/CMAKE_EXE_LINKER_FLAGS_CONFIG.rst @@ -0,0 +1,7 @@ +CMAKE_EXE_LINKER_FLAGS_<CONFIG> +------------------------------- + +Flags to be used when linking an executable. + +Same as ``CMAKE_C_FLAGS_*`` but used by the linker when creating +executables. diff --git a/Help/variable/CMAKE_EXE_LINKER_FLAGS_CONFIG_INIT.rst b/Help/variable/CMAKE_EXE_LINKER_FLAGS_CONFIG_INIT.rst new file mode 100644 index 0000000..4d2718a --- /dev/null +++ b/Help/variable/CMAKE_EXE_LINKER_FLAGS_CONFIG_INIT.rst @@ -0,0 +1,12 @@ +CMAKE_EXE_LINKER_FLAGS_<CONFIG>_INIT +------------------------------------ + +.. versionadded:: 3.7 + +Value used to initialize the :variable:`CMAKE_EXE_LINKER_FLAGS_<CONFIG>` +cache entry the first time a build tree is configured. +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_EXE_LINKER_FLAGS_INIT`. diff --git a/Help/variable/CMAKE_EXE_LINKER_FLAGS_INIT.rst b/Help/variable/CMAKE_EXE_LINKER_FLAGS_INIT.rst new file mode 100644 index 0000000..6e3927c --- /dev/null +++ b/Help/variable/CMAKE_EXE_LINKER_FLAGS_INIT.rst @@ -0,0 +1,13 @@ +CMAKE_EXE_LINKER_FLAGS_INIT +--------------------------- + +.. versionadded:: 3.7 + +Value used to initialize the :variable:`CMAKE_EXE_LINKER_FLAGS` +cache entry the first time a build tree is configured. +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 variable +:variable:`CMAKE_EXE_LINKER_FLAGS_<CONFIG>_INIT`. diff --git a/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst b/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst new file mode 100644 index 0000000..53a19dc --- /dev/null +++ b/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst @@ -0,0 +1,40 @@ +CMAKE_EXPORT_COMPILE_COMMANDS +----------------------------- + +.. versionadded:: 3.5 + +Enable/Disable output of compile commands during generation. + +If enabled, generates a ``compile_commands.json`` file containing the exact +compiler calls for all translation units of the project in machine-readable +form. The format of the JSON file looks like: + +.. code-block:: javascript + + [ + { + "directory": "/home/user/development/project", + "command": "/usr/bin/c++ ... -c ../foo/foo.cc", + "file": "../foo/foo.cc" + }, + + ... + + { + "directory": "/home/user/development/project", + "command": "/usr/bin/c++ ... -c ../foo/bar.cc", + "file": "../foo/bar.cc" + } + ] + +This is initialized by the :envvar:`CMAKE_EXPORT_COMPILE_COMMANDS` environment +variable, and initializes the :prop_tgt:`EXPORT_COMPILE_COMMANDS` target +property for all targets. + +.. 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 new file mode 100644 index 0000000..5772490 --- /dev/null +++ b/Help/variable/CMAKE_EXPORT_NO_PACKAGE_REGISTRY.rst @@ -0,0 +1,18 @@ +CMAKE_EXPORT_NO_PACKAGE_REGISTRY +-------------------------------- + +.. versionadded:: 3.1 + +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 ``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 0000000..663639b --- /dev/null +++ b/Help/variable/CMAKE_EXPORT_PACKAGE_REGISTRY.rst @@ -0,0 +1,17 @@ +CMAKE_EXPORT_PACKAGE_REGISTRY +----------------------------- + +.. versionadded:: 3.15 + +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 new file mode 100644 index 0000000..2c92323 --- /dev/null +++ b/Help/variable/CMAKE_EXTRA_GENERATOR.rst @@ -0,0 +1,10 @@ +CMAKE_EXTRA_GENERATOR +--------------------- + +The extra generator used to build the project. See +:manual:`cmake-generators(7)`. + +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_EXTRA_SHARED_LIBRARY_SUFFIXES.rst b/Help/variable/CMAKE_EXTRA_SHARED_LIBRARY_SUFFIXES.rst new file mode 100644 index 0000000..a130adb --- /dev/null +++ b/Help/variable/CMAKE_EXTRA_SHARED_LIBRARY_SUFFIXES.rst @@ -0,0 +1,9 @@ +CMAKE_EXTRA_SHARED_LIBRARY_SUFFIXES +----------------------------------- + +Additional suffixes for shared libraries. + +Extensions for shared libraries other than that specified by +:variable:`CMAKE_SHARED_LIBRARY_SUFFIX`, if any. CMake uses this to recognize +external shared library files during analysis of libraries linked by a +target. diff --git a/Help/variable/CMAKE_FIND_APPBUNDLE.rst b/Help/variable/CMAKE_FIND_APPBUNDLE.rst new file mode 100644 index 0000000..17563f3 --- /dev/null +++ b/Help/variable/CMAKE_FIND_APPBUNDLE.rst @@ -0,0 +1,24 @@ +CMAKE_FIND_APPBUNDLE +-------------------- + +.. versionadded:: 3.4 + +This variable affects how ``find_*`` commands choose between +macOS Application Bundles and unix-style package components. + +On Darwin or systems supporting macOS Application Bundles, the +``CMAKE_FIND_APPBUNDLE`` variable can be set to empty or +one of the following: + +``FIRST`` + Try to find application bundles before standard programs. + This is the default on Darwin. + +``LAST`` + Try to find application bundles after standard programs. + +``ONLY`` + Only try to find application bundles. + +``NEVER`` + Never try to find application bundles. diff --git a/Help/variable/CMAKE_FIND_DEBUG_MODE.rst b/Help/variable/CMAKE_FIND_DEBUG_MODE.rst new file mode 100644 index 0000000..8f2a82f --- /dev/null +++ b/Help/variable/CMAKE_FIND_DEBUG_MODE.rst @@ -0,0 +1,25 @@ +CMAKE_FIND_DEBUG_MODE +--------------------- + +.. versionadded:: 3.17 + +Print extra find call information for the following commands to standard +error: + +* :command:`find_program` +* :command:`find_library` +* :command:`find_file` +* :command:`find_path` +* :command:`find_package` + +Output is designed for human consumption and not for parsing. +Enabling this variable is equivalent to using :manual:`cmake <cmake(1)>` ``--debug-find`` +with the added ability to enable debugging for a subset of find calls. + +.. code-block:: cmake + + set(CMAKE_FIND_DEBUG_MODE TRUE) + find_program(...) + set(CMAKE_FIND_DEBUG_MODE FALSE) + +Default is unset. diff --git a/Help/variable/CMAKE_FIND_FRAMEWORK.rst b/Help/variable/CMAKE_FIND_FRAMEWORK.rst new file mode 100644 index 0000000..3b62cda --- /dev/null +++ b/Help/variable/CMAKE_FIND_FRAMEWORK.rst @@ -0,0 +1,24 @@ +CMAKE_FIND_FRAMEWORK +-------------------- + +.. versionadded:: 3.4 + +This variable affects how ``find_*`` commands choose between +macOS Frameworks and unix-style package components. + +On Darwin or systems supporting macOS Frameworks, the +``CMAKE_FIND_FRAMEWORK`` variable can be set to empty or +one of the following: + +``FIRST`` + Try to find frameworks before standard libraries or headers. + This is the default on Darwin. + +``LAST`` + Try to find frameworks after standard libraries or headers. + +``ONLY`` + Only try to find frameworks. + +``NEVER`` + Never try to find frameworks. diff --git a/Help/variable/CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX.rst b/Help/variable/CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX.rst new file mode 100644 index 0000000..ca2ad7f --- /dev/null +++ b/Help/variable/CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX.rst @@ -0,0 +1,14 @@ +CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX +------------------------------------ + +.. versionadded:: 3.9 + +Specify a ``<suffix>`` to tell the :command:`find_library` command to +search in a ``lib<suffix>`` directory before each ``lib`` directory that +would normally be searched. + +This overrides the behavior of related global properties: + +* :prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS` +* :prop_gbl:`FIND_LIBRARY_USE_LIB64_PATHS` +* :prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS` diff --git a/Help/variable/CMAKE_FIND_LIBRARY_PREFIXES.rst b/Help/variable/CMAKE_FIND_LIBRARY_PREFIXES.rst new file mode 100644 index 0000000..58354b2 --- /dev/null +++ b/Help/variable/CMAKE_FIND_LIBRARY_PREFIXES.rst @@ -0,0 +1,9 @@ +CMAKE_FIND_LIBRARY_PREFIXES +--------------------------- + +Prefixes to prepend when looking for libraries. + +This specifies what prefixes to add to library names when the +:command:`find_library` command looks for libraries. On UNIX systems this is +typically ``lib``, meaning that when trying to find the ``foo`` library it +will look for ``libfoo``. diff --git a/Help/variable/CMAKE_FIND_LIBRARY_SUFFIXES.rst b/Help/variable/CMAKE_FIND_LIBRARY_SUFFIXES.rst new file mode 100644 index 0000000..4a64e33 --- /dev/null +++ b/Help/variable/CMAKE_FIND_LIBRARY_SUFFIXES.rst @@ -0,0 +1,9 @@ +CMAKE_FIND_LIBRARY_SUFFIXES +--------------------------- + +Suffixes to append when looking for libraries. + +This specifies what suffixes to add to library names when the +:command:`find_library` command looks for libraries. On Windows systems this +is typically ``.lib`` and ``.dll``, meaning that when trying to find the +``foo`` library it will look for ``foo.dll`` etc. diff --git a/Help/variable/CMAKE_FIND_NO_INSTALL_PREFIX.rst b/Help/variable/CMAKE_FIND_NO_INSTALL_PREFIX.rst new file mode 100644 index 0000000..789dc99 --- /dev/null +++ b/Help/variable/CMAKE_FIND_NO_INSTALL_PREFIX.rst @@ -0,0 +1,19 @@ +CMAKE_FIND_NO_INSTALL_PREFIX +---------------------------- + +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. + +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. + +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_NAME.rst b/Help/variable/CMAKE_FIND_PACKAGE_NAME.rst new file mode 100644 index 0000000..fc1fd43 --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_NAME.rst @@ -0,0 +1,8 @@ +CMAKE_FIND_PACKAGE_NAME +----------------------- + +.. versionadded:: 3.1.1 + +Defined by the :command:`find_package` command while loading +a find module to record the caller-specified package name. +See command documentation for details. diff --git a/Help/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY.rst new file mode 100644 index 0000000..8d86a94 --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY.rst @@ -0,0 +1,26 @@ +CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY +-------------------------------------- + +.. versionadded:: 3.1 + +.. 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 ``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. + +See also :ref:`Disabling the Package Registry`. diff --git a/Help/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY.rst new file mode 100644 index 0000000..cc67f08 --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY.rst @@ -0,0 +1,26 @@ +CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY +--------------------------------------------- + +.. versionadded:: 3.1 + +.. 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 +``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. + +See also :ref:`Disabling the Package Registry`. 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 0000000..ba81529 --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_PREFER_CONFIG.rst @@ -0,0 +1,29 @@ +CMAKE_FIND_PACKAGE_PREFER_CONFIG +--------------------------------- + +.. versionadded:: 3.15 + +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 0000000..86d75e7 --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS.rst @@ -0,0 +1,12 @@ +CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS +----------------------------------- + +.. versionadded:: 3.14 + +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_SORT_DIRECTION.rst b/Help/variable/CMAKE_FIND_PACKAGE_SORT_DIRECTION.rst new file mode 100644 index 0000000..98c2a8f --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_SORT_DIRECTION.rst @@ -0,0 +1,18 @@ +CMAKE_FIND_PACKAGE_SORT_DIRECTION +--------------------------------- + +.. versionadded:: 3.7 + +The sorting direction used by :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER`. +It can assume one of the following values: + +``DEC`` + Default. Ordering is done in descending mode. + The highest folder found will be tested first. + +``ASC`` + Ordering is done in ascending mode. + The lowest folder found will be tested first. + +If :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` is not set or is set to ``NONE`` +this variable has no effect. diff --git a/Help/variable/CMAKE_FIND_PACKAGE_SORT_ORDER.rst b/Help/variable/CMAKE_FIND_PACKAGE_SORT_ORDER.rst new file mode 100644 index 0000000..1725ba1 --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_SORT_ORDER.rst @@ -0,0 +1,38 @@ +CMAKE_FIND_PACKAGE_SORT_ORDER +----------------------------- + +.. versionadded:: 3.7 + +The default order for sorting packages found using :command:`find_package`. +It can assume one of the following values: + +``NONE`` + Default. No attempt is done to sort packages. + The first valid package found will be selected. + +``NAME`` + Sort packages lexicographically before selecting one. + +``NATURAL`` + Sort packages using natural order (see ``strverscmp(3)`` manual), + i.e. such that contiguous digits are compared as whole numbers. + +Natural sorting can be employed to return the highest version when multiple +versions of the same library are found by :command:`find_package`. For +example suppose that the following libraries have been found: + +* libX-1.1.0 +* libX-1.2.9 +* libX-1.2.10 + +By setting ``NATURAL`` order we can select the one with the highest +version number ``libX-1.2.10``. + +.. code-block:: cmake + + set(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL) + find_package(libX CONFIG) + +The sort direction can be controlled using the +:variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION` variable +(by default decrescent, e.g. lib-B will be tested before lib-A). diff --git a/Help/variable/CMAKE_FIND_PACKAGE_WARN_NO_MODULE.rst b/Help/variable/CMAKE_FIND_PACKAGE_WARN_NO_MODULE.rst new file mode 100644 index 0000000..5c4f23a --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_WARN_NO_MODULE.rst @@ -0,0 +1,22 @@ +CMAKE_FIND_PACKAGE_WARN_NO_MODULE +--------------------------------- + +Tell :command:`find_package` to warn if called without an explicit mode. + +If :command:`find_package` is called without an explicit mode option +(``MODULE``, ``CONFIG``, or ``NO_MODULE``) and no ``Find<pkg>.cmake`` module +is in :variable:`CMAKE_MODULE_PATH` then CMake implicitly assumes that the +caller intends to search for a package configuration file. If no package +configuration file is found then the wording of the failure message +must account for both the case that the package is really missing and +the case that the project has a bug and failed to provide the intended +Find module. If instead the caller specifies an explicit mode option +then the failure message can be more specific. + +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 new file mode 100644 index 0000000..6172c56 --- /dev/null +++ b/Help/variable/CMAKE_FIND_ROOT_PATH.rst @@ -0,0 +1,8 @@ +CMAKE_FIND_ROOT_PATH +-------------------- + +: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 +:command:`find_package`, :command:`find_library` etc. diff --git a/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_INCLUDE.rst b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_INCLUDE.rst new file mode 100644 index 0000000..df1af5a --- /dev/null +++ b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_INCLUDE.rst @@ -0,0 +1,6 @@ +CMAKE_FIND_ROOT_PATH_MODE_INCLUDE +--------------------------------- + +.. |FIND_XXX| replace:: :command:`find_file` and :command:`find_path` + +.. include:: CMAKE_FIND_ROOT_PATH_MODE_XXX.txt diff --git a/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_LIBRARY.rst b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_LIBRARY.rst new file mode 100644 index 0000000..52ab89d --- /dev/null +++ b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_LIBRARY.rst @@ -0,0 +1,6 @@ +CMAKE_FIND_ROOT_PATH_MODE_LIBRARY +--------------------------------- + +.. |FIND_XXX| replace:: :command:`find_library` + +.. include:: CMAKE_FIND_ROOT_PATH_MODE_XXX.txt diff --git a/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_PACKAGE.rst b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_PACKAGE.rst new file mode 100644 index 0000000..3872947 --- /dev/null +++ b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_PACKAGE.rst @@ -0,0 +1,6 @@ +CMAKE_FIND_ROOT_PATH_MODE_PACKAGE +--------------------------------- + +.. |FIND_XXX| replace:: :command:`find_package` + +.. include:: CMAKE_FIND_ROOT_PATH_MODE_XXX.txt diff --git a/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_PROGRAM.rst b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_PROGRAM.rst new file mode 100644 index 0000000..d24a78a --- /dev/null +++ b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_PROGRAM.rst @@ -0,0 +1,6 @@ +CMAKE_FIND_ROOT_PATH_MODE_PROGRAM +--------------------------------- + +.. |FIND_XXX| replace:: :command:`find_program` + +.. include:: CMAKE_FIND_ROOT_PATH_MODE_XXX.txt diff --git a/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_XXX.txt b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_XXX.txt new file mode 100644 index 0000000..ab65e09 --- /dev/null +++ b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_XXX.txt @@ -0,0 +1,8 @@ +This variable controls whether the :variable:`CMAKE_FIND_ROOT_PATH` and +:variable:`CMAKE_SYSROOT` are used by |FIND_XXX|. + +If set to ``ONLY``, then only the roots in :variable:`CMAKE_FIND_ROOT_PATH` +will be searched. If set to ``NEVER``, then the roots in +:variable:`CMAKE_FIND_ROOT_PATH` will be ignored and only the host system +root will be used. If set to ``BOTH``, then the host system paths and the +paths in :variable:`CMAKE_FIND_ROOT_PATH` will be searched. 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 0000000..de1bad7 --- /dev/null +++ b/Help/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.rst @@ -0,0 +1,26 @@ +CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH +------------------------------------- + +.. versionadded:: 3.16 + +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 0000000..47ce3a3 --- /dev/null +++ b/Help/variable/CMAKE_FIND_USE_CMAKE_PATH.rst @@ -0,0 +1,26 @@ +CMAKE_FIND_USE_CMAKE_PATH +------------------------- + +.. versionadded:: 3.16 + +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 0000000..2fd00df --- /dev/null +++ b/Help/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.rst @@ -0,0 +1,26 @@ +CMAKE_FIND_USE_CMAKE_SYSTEM_PATH +-------------------------------- + +.. versionadded:: 3.16 + +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 0000000..3127206 --- /dev/null +++ b/Help/variable/CMAKE_FIND_USE_PACKAGE_REGISTRY.rst @@ -0,0 +1,32 @@ +CMAKE_FIND_USE_PACKAGE_REGISTRY +------------------------------- + +.. versionadded:: 3.16 + +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 0000000..64e5c6d --- /dev/null +++ b/Help/variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH.rst @@ -0,0 +1,24 @@ +CMAKE_FIND_USE_PACKAGE_ROOT_PATH +-------------------------------- + +.. versionadded:: 3.16 + +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 0000000..a0a86e4 --- /dev/null +++ b/Help/variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.rst @@ -0,0 +1,26 @@ +CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH +-------------------------------------- + +.. versionadded:: 3.16 + +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 0000000..504b7e8 --- /dev/null +++ b/Help/variable/CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY.rst @@ -0,0 +1,33 @@ +CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY +-------------------------------------- + +.. versionadded:: 3.16 + +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 0000000..37f137c --- /dev/null +++ b/Help/variable/CMAKE_FOLDER.rst @@ -0,0 +1,9 @@ +CMAKE_FOLDER +------------ + +.. versionadded:: 3.12 + +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 0000000..37385bf --- /dev/null +++ b/Help/variable/CMAKE_FRAMEWORK.rst @@ -0,0 +1,9 @@ +CMAKE_FRAMEWORK +--------------- + +.. versionadded:: 3.15 + +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_MULTI_CONFIG_POSTFIX_CONFIG.rst b/Help/variable/CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_CONFIG.rst new file mode 100644 index 0000000..47fb66e --- /dev/null +++ b/Help/variable/CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_CONFIG.rst @@ -0,0 +1,10 @@ +CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG> +--------------------------------------------- + +.. versionadded:: 3.18 + +Default framework filename postfix under configuration ``<CONFIG>`` when +using a multi-config generator. + +When a framework target is created its :prop_tgt:`FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>` +target property is initialized with the value of this variable if it is set. diff --git a/Help/variable/CMAKE_FRAMEWORK_PATH.rst b/Help/variable/CMAKE_FRAMEWORK_PATH.rst new file mode 100644 index 0000000..13ade4e --- /dev/null +++ b/Help/variable/CMAKE_FRAMEWORK_PATH.rst @@ -0,0 +1,7 @@ +CMAKE_FRAMEWORK_PATH +-------------------- + +: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_Fortran_FORMAT.rst b/Help/variable/CMAKE_Fortran_FORMAT.rst new file mode 100644 index 0000000..1406e59 --- /dev/null +++ b/Help/variable/CMAKE_Fortran_FORMAT.rst @@ -0,0 +1,7 @@ +CMAKE_Fortran_FORMAT +-------------------- + +Set to ``FIXED`` or ``FREE`` to indicate the Fortran source layout. + +This variable is used to initialize the :prop_tgt:`Fortran_FORMAT` property on +all the targets. See that target property for additional information. diff --git a/Help/variable/CMAKE_Fortran_MODDIR_DEFAULT.rst b/Help/variable/CMAKE_Fortran_MODDIR_DEFAULT.rst new file mode 100644 index 0000000..5aeab07 --- /dev/null +++ b/Help/variable/CMAKE_Fortran_MODDIR_DEFAULT.rst @@ -0,0 +1,8 @@ +CMAKE_Fortran_MODDIR_DEFAULT +---------------------------- + +Fortran default module output directory. + +Most Fortran compilers write ``.mod`` files to the current working +directory. For those that do not, this is set to ``.`` and used when +the :prop_tgt:`Fortran_MODULE_DIRECTORY` target property is not set. diff --git a/Help/variable/CMAKE_Fortran_MODDIR_FLAG.rst b/Help/variable/CMAKE_Fortran_MODDIR_FLAG.rst new file mode 100644 index 0000000..1da55ca --- /dev/null +++ b/Help/variable/CMAKE_Fortran_MODDIR_FLAG.rst @@ -0,0 +1,7 @@ +CMAKE_Fortran_MODDIR_FLAG +------------------------- + +Fortran flag for module output directory. + +This stores the flag needed to pass the value of the +:prop_tgt:`Fortran_MODULE_DIRECTORY` target property to the compiler. diff --git a/Help/variable/CMAKE_Fortran_MODOUT_FLAG.rst b/Help/variable/CMAKE_Fortran_MODOUT_FLAG.rst new file mode 100644 index 0000000..2f83880 --- /dev/null +++ b/Help/variable/CMAKE_Fortran_MODOUT_FLAG.rst @@ -0,0 +1,7 @@ +CMAKE_Fortran_MODOUT_FLAG +------------------------- + +Fortran flag to enable module output. + +Most Fortran compilers write ``.mod`` files out by default. For others, +this stores the flag needed to enable module output. diff --git a/Help/variable/CMAKE_Fortran_MODULE_DIRECTORY.rst b/Help/variable/CMAKE_Fortran_MODULE_DIRECTORY.rst new file mode 100644 index 0000000..3c7edc1 --- /dev/null +++ b/Help/variable/CMAKE_Fortran_MODULE_DIRECTORY.rst @@ -0,0 +1,8 @@ +CMAKE_Fortran_MODULE_DIRECTORY +------------------------------ + +Fortran module output directory. + +This variable is used to initialize the :prop_tgt:`Fortran_MODULE_DIRECTORY` +property on all the targets. See that target property for additional +information. diff --git a/Help/variable/CMAKE_Fortran_PREPROCESS.rst b/Help/variable/CMAKE_Fortran_PREPROCESS.rst new file mode 100644 index 0000000..7d405f3 --- /dev/null +++ b/Help/variable/CMAKE_Fortran_PREPROCESS.rst @@ -0,0 +1,10 @@ +CMAKE_Fortran_PREPROCESS +------------------------ + +.. versionadded:: 3.18 + +Default value for :prop_tgt:`Fortran_PREPROCESS` of targets. + +This variable is used to initialize the :prop_tgt:`Fortran_PREPROCESS` +property on all the targets. See that target property for additional +information. diff --git a/Help/variable/CMAKE_GENERATOR.rst b/Help/variable/CMAKE_GENERATOR.rst new file mode 100644 index 0000000..ec52cd4 --- /dev/null +++ b/Help/variable/CMAKE_GENERATOR.rst @@ -0,0 +1,12 @@ +CMAKE_GENERATOR +--------------- + +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 0000000..5858d7a --- /dev/null +++ b/Help/variable/CMAKE_GENERATOR_INSTANCE.rst @@ -0,0 +1,27 @@ +CMAKE_GENERATOR_INSTANCE +------------------------ + +.. versionadded:: 3.11 + +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 new file mode 100644 index 0000000..b17d83a --- /dev/null +++ b/Help/variable/CMAKE_GENERATOR_PLATFORM.rst @@ -0,0 +1,33 @@ +CMAKE_GENERATOR_PLATFORM +------------------------ + +.. versionadded:: 3.1 + +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 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` +variable may initialize ``CMAKE_GENERATOR_PLATFORM``. Once a given +build tree has been initialized with a particular value for this +variable, changing the value has undefined behavior. + +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 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +On :ref:`Visual Studio Generators` the selected platform name +is provided in the :variable:`CMAKE_VS_PLATFORM_NAME` variable. diff --git a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst new file mode 100644 index 0000000..45f2d32 --- /dev/null +++ b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst @@ -0,0 +1,89 @@ +CMAKE_GENERATOR_TOOLSET +----------------------- + +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 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. +A toolchain file specified by the :variable:`CMAKE_TOOLCHAIN_FILE` +variable may initialize ``CMAKE_GENERATOR_TOOLSET``. Once a given +build tree has been initialized with a particular value for this +variable, changing the value has undefined behavior. + +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. + +Visual Studio Toolset Selection +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The :ref:`Visual Studio Generators` support toolset specification +using one of these forms: + +* ``toolset`` +* ``toolset[,key=value]*`` +* ``key=value[,key=value]*`` + +The ``toolset`` specifies the toolset name. The selected toolset name +is provided in the :variable:`CMAKE_VS_PLATFORM_TOOLSET` variable. + +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>|<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=<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. + +``VCTargetsPath=<path>`` + Specify an alternative ``VCTargetsPath`` value for Visual Studio + project files. This allows use of VS platform extension configuration + files (``.props`` and ``.targets``) that are not installed with VS. + +Visual Studio Toolset Customization +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +**These are unstable interfaces with no compatibility guarantees** +because they hook into undocumented internal CMake implementation details. +Institutions may use these to internally maintain support for non-public +Visual Studio platforms and toolsets, but must accept responsibility to +make updates as changes are made to CMake. + +Additional ``key=value`` pairs are available: + +``customFlagTableDir=<path>`` + .. versionadded:: 3.21 + + Specify the absolute path to a directory from which to load custom + flag tables stored as JSON documents with file names of the form + ``<platform>_<toolset>_<tool>.json`` or ``<platform>_<tool>.json``, + where ``<platform>`` is the :variable:`CMAKE_VS_PLATFORM_NAME`, + ``<toolset>`` is the :variable:`CMAKE_VS_PLATFORM_TOOLSET`, + and ``<tool>`` is the tool for which the flag table is meant. + **This naming pattern is an internal CMake implementation detail.** + The ``<tool>`` names are undocumented. The format of the ``.json`` + flag table files is undocumented. 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 0000000..0e8ae5e --- /dev/null +++ b/Help/variable/CMAKE_GHS_NO_SOURCE_GROUP_FILE.rst @@ -0,0 +1,8 @@ +CMAKE_GHS_NO_SOURCE_GROUP_FILE +------------------------------ + +.. versionadded:: 3.14 + +``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 0000000..96e9907 --- /dev/null +++ b/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET.rst @@ -0,0 +1,28 @@ +CMAKE_GLOBAL_AUTOGEN_TARGET +--------------------------- + +.. versionadded:: 3.14 + +Switch to enable generation of a global ``autogen`` target. + +When :variable:`CMAKE_GLOBAL_AUTOGEN_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 0000000..4af4bc3 --- /dev/null +++ b/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET_NAME.rst @@ -0,0 +1,15 @@ +CMAKE_GLOBAL_AUTOGEN_TARGET_NAME +-------------------------------- + +.. versionadded:: 3.14 + +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 0000000..efea5be --- /dev/null +++ b/Help/variable/CMAKE_GLOBAL_AUTORCC_TARGET.rst @@ -0,0 +1,20 @@ +CMAKE_GLOBAL_AUTORCC_TARGET +--------------------------- + +.. versionadded:: 3.14 + +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 0000000..4d2e313 --- /dev/null +++ b/Help/variable/CMAKE_GLOBAL_AUTORCC_TARGET_NAME.rst @@ -0,0 +1,15 @@ +CMAKE_GLOBAL_AUTORCC_TARGET_NAME +-------------------------------- + +.. versionadded:: 3.14 + +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_GNUtoMS.rst b/Help/variable/CMAKE_GNUtoMS.rst new file mode 100644 index 0000000..9c0f59e --- /dev/null +++ b/Help/variable/CMAKE_GNUtoMS.rst @@ -0,0 +1,8 @@ +CMAKE_GNUtoMS +------------- + +Convert GNU import libraries (``.dll.a``) to MS format (``.lib``). + +This variable is used to initialize the :prop_tgt:`GNUtoMS` property on +targets when they are created. See that target property for additional +information. diff --git a/Help/variable/CMAKE_HOME_DIRECTORY.rst b/Help/variable/CMAKE_HOME_DIRECTORY.rst new file mode 100644 index 0000000..b03d956 --- /dev/null +++ b/Help/variable/CMAKE_HOME_DIRECTORY.rst @@ -0,0 +1,9 @@ +CMAKE_HOME_DIRECTORY +-------------------- + +Path to top of source tree. Same as :variable:`CMAKE_SOURCE_DIR`. + +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 new file mode 100644 index 0000000..9c205ec --- /dev/null +++ b/Help/variable/CMAKE_HOST_APPLE.rst @@ -0,0 +1,6 @@ +CMAKE_HOST_APPLE +---------------- + +``True`` for Apple macOS operating systems. + +Set to ``true`` when the host system is Apple macOS. diff --git a/Help/variable/CMAKE_HOST_SOLARIS.rst b/Help/variable/CMAKE_HOST_SOLARIS.rst new file mode 100644 index 0000000..7054acd --- /dev/null +++ b/Help/variable/CMAKE_HOST_SOLARIS.rst @@ -0,0 +1,8 @@ +CMAKE_HOST_SOLARIS +------------------ + +.. versionadded:: 3.6 + +``True`` for Oracle Solaris operating systems. + +Set to ``true`` when the host system is Oracle Solaris. diff --git a/Help/variable/CMAKE_HOST_SYSTEM.rst b/Help/variable/CMAKE_HOST_SYSTEM.rst new file mode 100644 index 0000000..12d11d1 --- /dev/null +++ b/Help/variable/CMAKE_HOST_SYSTEM.rst @@ -0,0 +1,10 @@ +CMAKE_HOST_SYSTEM +----------------- + +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. +``${CMAKE_HOST_SYSTEM_NAME}-${CMAKE_HOST_SYSTEM_VERSION}``. If +:variable:`CMAKE_HOST_SYSTEM_VERSION` is not set, then this variable is +the same as :variable:`CMAKE_HOST_SYSTEM_NAME`. diff --git a/Help/variable/CMAKE_HOST_SYSTEM_NAME.rst b/Help/variable/CMAKE_HOST_SYSTEM_NAME.rst new file mode 100644 index 0000000..e892677 --- /dev/null +++ b/Help/variable/CMAKE_HOST_SYSTEM_NAME.rst @@ -0,0 +1,8 @@ +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 macOS +are the values found on the big three operating systems. diff --git a/Help/variable/CMAKE_HOST_SYSTEM_PROCESSOR.rst b/Help/variable/CMAKE_HOST_SYSTEM_PROCESSOR.rst new file mode 100644 index 0000000..c305779 --- /dev/null +++ b/Help/variable/CMAKE_HOST_SYSTEM_PROCESSOR.rst @@ -0,0 +1,42 @@ +CMAKE_HOST_SYSTEM_PROCESSOR +--------------------------- + +The name of the CPU CMake is running on. + +Windows Platforms +^^^^^^^^^^^^^^^^^ + +On Windows, this variable is set to the value of the environment variable +``PROCESSOR_ARCHITECTURE``. + +Unix Platforms +^^^^^^^^^^^^^^ + +On systems that support ``uname``, this variable is set to the output of: + +- ``uname -m`` on GNU, Linux, Cygwin, Android, or +- ``arch`` on OpenBSD, or +- on other systems, + + * ``uname -p`` if its exit code is nonzero, or + * ``uname -m`` otherwise. + +macOS Platforms +^^^^^^^^^^^^^^^ + +The value of ``uname -m`` is used by default. + +On Apple Silicon hosts, the architecture printed by ``uname -m`` may vary +based on CMake's own architecture and that of the invoking process tree. + +.. versionadded:: 3.19.2 + + On Apple Silicon hosts: + + * The :variable:`CMAKE_APPLE_SILICON_PROCESSOR` variable or + the :envvar:`CMAKE_APPLE_SILICON_PROCESSOR` environment variable + may be set to specify the host architecture explicitly. + + * If :variable:`CMAKE_OSX_ARCHITECTURES` is not set, CMake adds explicit + flags to tell the compiler to build for the host architecture so the + toolchain does not have to guess based on the process tree's architecture. diff --git a/Help/variable/CMAKE_HOST_SYSTEM_VERSION.rst b/Help/variable/CMAKE_HOST_SYSTEM_VERSION.rst new file mode 100644 index 0000000..ed23070 --- /dev/null +++ b/Help/variable/CMAKE_HOST_SYSTEM_VERSION.rst @@ -0,0 +1,8 @@ +CMAKE_HOST_SYSTEM_VERSION +------------------------- + +The OS version CMake is running on. + +A numeric version string for the system. On systems that support +``uname``, this variable is set to the output of ``uname -r``. On other +systems this is set to major-minor version numbers. diff --git a/Help/variable/CMAKE_HOST_UNIX.rst b/Help/variable/CMAKE_HOST_UNIX.rst new file mode 100644 index 0000000..817a957 --- /dev/null +++ b/Help/variable/CMAKE_HOST_UNIX.rst @@ -0,0 +1,7 @@ +CMAKE_HOST_UNIX +--------------- + +``True`` for UNIX and UNIX like operating systems. + +Set to ``true`` when the host system is UNIX or UNIX like (i.e. APPLE and +CYGWIN). diff --git a/Help/variable/CMAKE_HOST_WIN32.rst b/Help/variable/CMAKE_HOST_WIN32.rst new file mode 100644 index 0000000..876b34c --- /dev/null +++ b/Help/variable/CMAKE_HOST_WIN32.rst @@ -0,0 +1,6 @@ +CMAKE_HOST_WIN32 +---------------- + +``True`` if the host system is running Windows, including Windows 64-bit and MSYS. + +Set to ``false`` on Cygwin. diff --git a/Help/variable/CMAKE_IGNORE_PATH.rst b/Help/variable/CMAKE_IGNORE_PATH.rst new file mode 100644 index 0000000..4bca34b --- /dev/null +++ b/Help/variable/CMAKE_IGNORE_PATH.rst @@ -0,0 +1,18 @@ +CMAKE_IGNORE_PATH +----------------- + +: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 +possibly linkable libraries. For example, on cross-compiled cluster +environments, this allows a user to ignore directories containing +libraries meant for the front-end machine. + +By default this is empty; it is intended to be set by the project. +Note that ``CMAKE_IGNORE_PATH`` takes a list of directory names, *not* +a list of prefixes. To ignore paths under prefixes (``bin``, ``include``, +``lib``, etc.), specify them explicitly. + +See also the :variable:`CMAKE_PREFIX_PATH`, :variable:`CMAKE_LIBRARY_PATH`, +:variable:`CMAKE_INCLUDE_PATH`, and :variable:`CMAKE_PROGRAM_PATH` variables. diff --git a/Help/variable/CMAKE_IMPORT_LIBRARY_PREFIX.rst b/Help/variable/CMAKE_IMPORT_LIBRARY_PREFIX.rst new file mode 100644 index 0000000..1561a1d --- /dev/null +++ b/Help/variable/CMAKE_IMPORT_LIBRARY_PREFIX.rst @@ -0,0 +1,9 @@ +CMAKE_IMPORT_LIBRARY_PREFIX +--------------------------- + +The prefix for import libraries that you link to. + +The prefix to use for the name of an import library if used on this +platform. + +``CMAKE_IMPORT_LIBRARY_PREFIX_<LANG>`` overrides this for language ``<LANG>``. diff --git a/Help/variable/CMAKE_IMPORT_LIBRARY_SUFFIX.rst b/Help/variable/CMAKE_IMPORT_LIBRARY_SUFFIX.rst new file mode 100644 index 0000000..11aeab7 --- /dev/null +++ b/Help/variable/CMAKE_IMPORT_LIBRARY_SUFFIX.rst @@ -0,0 +1,9 @@ +CMAKE_IMPORT_LIBRARY_SUFFIX +--------------------------- + +The suffix for import libraries that you link to. + +The suffix to use for the end of an import library filename if used on +this platform. + +``CMAKE_IMPORT_LIBRARY_SUFFIX_<LANG>`` overrides this for language ``<LANG>``. diff --git a/Help/variable/CMAKE_INCLUDE_CURRENT_DIR.rst b/Help/variable/CMAKE_INCLUDE_CURRENT_DIR.rst new file mode 100644 index 0000000..98d99eb --- /dev/null +++ b/Help/variable/CMAKE_INCLUDE_CURRENT_DIR.rst @@ -0,0 +1,13 @@ +CMAKE_INCLUDE_CURRENT_DIR +------------------------- + +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` +to the include path for each directory. These additional include +directories do not propagate down to subdirectories. This is useful +mainly for out-of-source builds, where files generated into the build +tree are included by files located in the source tree. + +By default ``CMAKE_INCLUDE_CURRENT_DIR`` is ``OFF``. diff --git a/Help/variable/CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE.rst b/Help/variable/CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE.rst new file mode 100644 index 0000000..697682b --- /dev/null +++ b/Help/variable/CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE.rst @@ -0,0 +1,12 @@ +CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE +-------------------------------------- + +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 +library target, static library target, module target and executable +target, :variable:`CMAKE_CURRENT_SOURCE_DIR` and +:variable:`CMAKE_CURRENT_BINARY_DIR` to +the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property. By default +``CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE`` is ``OFF``. diff --git a/Help/variable/CMAKE_INCLUDE_DIRECTORIES_BEFORE.rst b/Help/variable/CMAKE_INCLUDE_DIRECTORIES_BEFORE.rst new file mode 100644 index 0000000..e0f2a2e --- /dev/null +++ b/Help/variable/CMAKE_INCLUDE_DIRECTORIES_BEFORE.rst @@ -0,0 +1,9 @@ +CMAKE_INCLUDE_DIRECTORIES_BEFORE +-------------------------------- + +Whether to append or prepend directories by default in +:command:`include_directories`. + +This variable affects the default behavior of the :command:`include_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_INCLUDE_DIRECTORIES_PROJECT_BEFORE.rst b/Help/variable/CMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE.rst new file mode 100644 index 0000000..37d0a3d --- /dev/null +++ b/Help/variable/CMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE.rst @@ -0,0 +1,8 @@ +CMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE +---------------------------------------- + +Whether to force prepending of project include directories. + +This variable affects the order of include directories generated in compiler +command lines. If set to ``ON``, it causes the :variable:`CMAKE_SOURCE_DIR` +and the :variable:`CMAKE_BINARY_DIR` to appear first. diff --git a/Help/variable/CMAKE_INCLUDE_PATH.rst b/Help/variable/CMAKE_INCLUDE_PATH.rst new file mode 100644 index 0000000..4918e99 --- /dev/null +++ b/Help/variable/CMAKE_INCLUDE_PATH.rst @@ -0,0 +1,7 @@ +CMAKE_INCLUDE_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_COMPONENT_NAME.rst b/Help/variable/CMAKE_INSTALL_DEFAULT_COMPONENT_NAME.rst new file mode 100644 index 0000000..57160f1 --- /dev/null +++ b/Help/variable/CMAKE_INSTALL_DEFAULT_COMPONENT_NAME.rst @@ -0,0 +1,9 @@ +CMAKE_INSTALL_DEFAULT_COMPONENT_NAME +------------------------------------ + +Default component used in :command:`install` commands. + +If an :command:`install` command is used without the ``COMPONENT`` argument, +these files will be grouped into a default component. The name of this +default install component will be taken from this variable. It +defaults to ``Unspecified``. 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 0000000..aad99e4 --- /dev/null +++ b/Help/variable/CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS.rst @@ -0,0 +1,31 @@ +CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS +------------------------------------------- + +.. versionadded:: 3.11 + +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_MESSAGE.rst b/Help/variable/CMAKE_INSTALL_MESSAGE.rst new file mode 100644 index 0000000..4f39cfe --- /dev/null +++ b/Help/variable/CMAKE_INSTALL_MESSAGE.rst @@ -0,0 +1,32 @@ +CMAKE_INSTALL_MESSAGE +--------------------- + +.. versionadded:: 3.1 + +Specify verbosity of installation script code generated by the +:command:`install` command (using the :command:`file(INSTALL)` command). +For paths that are newly installed or updated, installation +may print lines like:: + + -- Installing: /some/destination/path + +For paths that are already up to date, installation may print +lines like:: + + -- Up-to-date: /some/destination/path + +The ``CMAKE_INSTALL_MESSAGE`` variable may be set to control +which messages are printed: + +``ALWAYS`` + Print both ``Installing`` and ``Up-to-date`` messages. + +``LAZY`` + Print ``Installing`` but not ``Up-to-date`` messages. + +``NEVER`` + Print neither ``Installing`` nor ``Up-to-date`` messages. + +Other values have undefined behavior and may not be diagnosed. + +If this variable is not set, the default behavior is ``ALWAYS``. diff --git a/Help/variable/CMAKE_INSTALL_NAME_DIR.rst b/Help/variable/CMAKE_INSTALL_NAME_DIR.rst new file mode 100644 index 0000000..b07d44f --- /dev/null +++ b/Help/variable/CMAKE_INSTALL_NAME_DIR.rst @@ -0,0 +1,8 @@ +CMAKE_INSTALL_NAME_DIR +---------------------- + +Directory name for installed targets on Apple platforms. + +``CMAKE_INSTALL_NAME_DIR`` is used to initialize the +:prop_tgt:`INSTALL_NAME_DIR` property on all targets. See that target +property for more information. diff --git a/Help/variable/CMAKE_INSTALL_PREFIX.rst b/Help/variable/CMAKE_INSTALL_PREFIX.rst new file mode 100644 index 0000000..02ba645 --- /dev/null +++ b/Help/variable/CMAKE_INSTALL_PREFIX.rst @@ -0,0 +1,23 @@ +CMAKE_INSTALL_PREFIX +-------------------- + +Install directory used by :command:`install`. + +If ``make install`` is invoked or ``INSTALL`` is built, this directory is +prepended onto all install directories. This variable defaults to +``/usr/local`` on UNIX and ``c:/Program Files/${PROJECT_NAME}`` on Windows. +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. 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`, +:command:`find_library`, :command:`find_path`, and :command:`find_file` +will search the prefix for other software. + +.. note:: + + Use the :module:`GNUInstallDirs` module to provide GNU-style + options for the layout of directories within the installation. diff --git a/Help/variable/CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT.rst b/Help/variable/CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT.rst new file mode 100644 index 0000000..93cc319 --- /dev/null +++ b/Help/variable/CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT.rst @@ -0,0 +1,16 @@ +CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT +------------------------------------------- + +.. versionadded:: 3.7.1 + +CMake sets this variable to a ``TRUE`` value when the +:variable:`CMAKE_INSTALL_PREFIX` has just been initialized to +its default value, typically on the first run of CMake within +a new build tree. This can be used by project code to change +the default without overriding a user-provided value: + +.. code-block:: cmake + + if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT) + set(CMAKE_INSTALL_PREFIX "/my/default" CACHE PATH "..." FORCE) + endif() 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 0000000..c86e433 --- /dev/null +++ b/Help/variable/CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH.rst @@ -0,0 +1,11 @@ +CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH +-------------------------------------- + +.. versionadded:: 3.16 + +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_INSTALL_RPATH.rst b/Help/variable/CMAKE_INSTALL_RPATH.rst new file mode 100644 index 0000000..813d1e0 --- /dev/null +++ b/Help/variable/CMAKE_INSTALL_RPATH.rst @@ -0,0 +1,8 @@ +CMAKE_INSTALL_RPATH +------------------- + +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 is used to initialize +the target property :prop_tgt:`INSTALL_RPATH` for all targets. diff --git a/Help/variable/CMAKE_INSTALL_RPATH_USE_LINK_PATH.rst b/Help/variable/CMAKE_INSTALL_RPATH_USE_LINK_PATH.rst new file mode 100644 index 0000000..34524d1 --- /dev/null +++ b/Help/variable/CMAKE_INSTALL_RPATH_USE_LINK_PATH.rst @@ -0,0 +1,13 @@ +CMAKE_INSTALL_RPATH_USE_LINK_PATH +--------------------------------- + +Add paths to linker search and installed rpath. + +``CMAKE_INSTALL_RPATH_USE_LINK_PATH`` is a boolean that if set to ``True`` +will append to the runtime search path (rpath) of installed binaries +any directories outside the project that are in the linker search path or +contain linked library files. The directories are appended after the +value of the :prop_tgt:`INSTALL_RPATH` target property. + +This variable is used to initialize the target property +:prop_tgt:`INSTALL_RPATH_USE_LINK_PATH` for all targets. diff --git a/Help/variable/CMAKE_INTERNAL_PLATFORM_ABI.rst b/Help/variable/CMAKE_INTERNAL_PLATFORM_ABI.rst new file mode 100644 index 0000000..9693bf6 --- /dev/null +++ b/Help/variable/CMAKE_INTERNAL_PLATFORM_ABI.rst @@ -0,0 +1,6 @@ +CMAKE_INTERNAL_PLATFORM_ABI +--------------------------- + +An internal variable subject to change. + +This is used in determining the compiler ABI and is subject to change. diff --git a/Help/variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION.rst b/Help/variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION.rst new file mode 100644 index 0000000..cf7da76 --- /dev/null +++ b/Help/variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION.rst @@ -0,0 +1,10 @@ +CMAKE_INTERPROCEDURAL_OPTIMIZATION +---------------------------------- + +.. versionadded:: 3.9 + +Default value for :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` of targets. + +This variable is used to initialize the :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` +property on all the targets. See that target property for additional +information. diff --git a/Help/variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst b/Help/variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst new file mode 100644 index 0000000..5b3ee77 --- /dev/null +++ b/Help/variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst @@ -0,0 +1,10 @@ +CMAKE_INTERPROCEDURAL_OPTIMIZATION_<CONFIG> +------------------------------------------- + +.. versionadded:: 3.9 + +Default value for :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION_<CONFIG>` of targets. + +This variable is used to initialize the :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION_<CONFIG>` +property on all the targets. See that target property for additional +information. diff --git a/Help/variable/CMAKE_IOS_INSTALL_COMBINED.rst b/Help/variable/CMAKE_IOS_INSTALL_COMBINED.rst new file mode 100644 index 0000000..cd7fd8d --- /dev/null +++ b/Help/variable/CMAKE_IOS_INSTALL_COMBINED.rst @@ -0,0 +1,10 @@ +CMAKE_IOS_INSTALL_COMBINED +-------------------------- + +.. versionadded:: 3.5 + +Default value for :prop_tgt:`IOS_INSTALL_COMBINED` of targets. + +This variable is used to initialize the :prop_tgt:`IOS_INSTALL_COMBINED` +property on all the targets. See that target property for additional +information. diff --git a/Help/variable/CMAKE_ISPC_HEADER_DIRECTORY.rst b/Help/variable/CMAKE_ISPC_HEADER_DIRECTORY.rst new file mode 100644 index 0000000..a7c9cf6 --- /dev/null +++ b/Help/variable/CMAKE_ISPC_HEADER_DIRECTORY.rst @@ -0,0 +1,10 @@ +CMAKE_ISPC_HEADER_DIRECTORY +---------------------------- + +.. versionadded:: 3.19 + +ISPC generated header output directory. + +This variable is used to initialize the :prop_tgt:`ISPC_HEADER_DIRECTORY` +property on all the targets. See the target property for additional +information. diff --git a/Help/variable/CMAKE_ISPC_HEADER_SUFFIX.rst b/Help/variable/CMAKE_ISPC_HEADER_SUFFIX.rst new file mode 100644 index 0000000..c9fb709 --- /dev/null +++ b/Help/variable/CMAKE_ISPC_HEADER_SUFFIX.rst @@ -0,0 +1,10 @@ +CMAKE_ISPC_HEADER_SUFFIX +------------------------ + +.. versionadded:: 3.19.2 + +Output suffix to be used for ISPC generated headers. + +This variable is used to initialize the :prop_tgt:`ISPC_HEADER_SUFFIX` +property on all the targets. See the target property for additional +information. diff --git a/Help/variable/CMAKE_ISPC_INSTRUCTION_SETS.rst b/Help/variable/CMAKE_ISPC_INSTRUCTION_SETS.rst new file mode 100644 index 0000000..8a6005e --- /dev/null +++ b/Help/variable/CMAKE_ISPC_INSTRUCTION_SETS.rst @@ -0,0 +1,9 @@ +CMAKE_ISPC_INSTRUCTION_SETS +--------------------------- + +.. versionadded:: 3.19 + +Default value for :prop_tgt:`ISPC_INSTRUCTION_SETS` property of targets. + +This variable is used to initialize the :prop_tgt:`ISPC_INSTRUCTION_SETS` property +on all targets. See the target property for additional information. diff --git a/Help/variable/CMAKE_JOB_POOLS.rst b/Help/variable/CMAKE_JOB_POOLS.rst new file mode 100644 index 0000000..43d3c84 --- /dev/null +++ b/Help/variable/CMAKE_JOB_POOLS.rst @@ -0,0 +1,8 @@ +CMAKE_JOB_POOLS +--------------- + +.. versionadded:: 3.11 + +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_COMPILE.rst b/Help/variable/CMAKE_JOB_POOL_COMPILE.rst new file mode 100644 index 0000000..e5c2d9a --- /dev/null +++ b/Help/variable/CMAKE_JOB_POOL_COMPILE.rst @@ -0,0 +1,6 @@ +CMAKE_JOB_POOL_COMPILE +---------------------- + +This variable is used to initialize the :prop_tgt:`JOB_POOL_COMPILE` +property on all the targets. See :prop_tgt:`JOB_POOL_COMPILE` +for additional information. diff --git a/Help/variable/CMAKE_JOB_POOL_LINK.rst b/Help/variable/CMAKE_JOB_POOL_LINK.rst new file mode 100644 index 0000000..eeee6e0 --- /dev/null +++ b/Help/variable/CMAKE_JOB_POOL_LINK.rst @@ -0,0 +1,6 @@ +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` +for additional information. diff --git a/Help/variable/CMAKE_JOB_POOL_PRECOMPILE_HEADER.rst b/Help/variable/CMAKE_JOB_POOL_PRECOMPILE_HEADER.rst new file mode 100644 index 0000000..1a6f66a --- /dev/null +++ b/Help/variable/CMAKE_JOB_POOL_PRECOMPILE_HEADER.rst @@ -0,0 +1,8 @@ +CMAKE_JOB_POOL_PRECOMPILE_HEADER +-------------------------------- + +.. versionadded:: 3.17 + +This variable is used to initialize the :prop_tgt:`JOB_POOL_PRECOMPILE_HEADER` +property on all the targets. See :prop_tgt:`JOB_POOL_PRECOMPILE_HEADER` +for additional information. diff --git a/Help/variable/CMAKE_LANG_ANDROID_TOOLCHAIN_MACHINE.rst b/Help/variable/CMAKE_LANG_ANDROID_TOOLCHAIN_MACHINE.rst new file mode 100644 index 0000000..f539277 --- /dev/null +++ b/Help/variable/CMAKE_LANG_ANDROID_TOOLCHAIN_MACHINE.rst @@ -0,0 +1,11 @@ +CMAKE_<LANG>_ANDROID_TOOLCHAIN_MACHINE +-------------------------------------- + +.. versionadded:: 3.7.1 + +When :ref:`Cross Compiling for Android` this variable contains the +toolchain binutils machine name (e.g. ``gcc -dumpmachine``). The +binutils typically have a ``<machine>-`` prefix on their name. + +See also :variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX` +and :variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX`. diff --git a/Help/variable/CMAKE_LANG_ANDROID_TOOLCHAIN_PREFIX.rst b/Help/variable/CMAKE_LANG_ANDROID_TOOLCHAIN_PREFIX.rst new file mode 100644 index 0000000..ff072ca --- /dev/null +++ b/Help/variable/CMAKE_LANG_ANDROID_TOOLCHAIN_PREFIX.rst @@ -0,0 +1,14 @@ +CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX +------------------------------------- + +.. versionadded:: 3.7 + +When :ref:`Cross Compiling for Android` this variable contains the absolute +path prefixing the toolchain GNU compiler and its binutils. + +See also :variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX` +and :variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_MACHINE`. + +For example, the path to the linker is:: + + ${CMAKE_CXX_ANDROID_TOOLCHAIN_PREFIX}ld${CMAKE_CXX_ANDROID_TOOLCHAIN_SUFFIX} diff --git a/Help/variable/CMAKE_LANG_ANDROID_TOOLCHAIN_SUFFIX.rst b/Help/variable/CMAKE_LANG_ANDROID_TOOLCHAIN_SUFFIX.rst new file mode 100644 index 0000000..d595280 --- /dev/null +++ b/Help/variable/CMAKE_LANG_ANDROID_TOOLCHAIN_SUFFIX.rst @@ -0,0 +1,10 @@ +CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX +------------------------------------- + +.. versionadded:: 3.7 + +When :ref:`Cross Compiling for Android` this variable contains the +host platform suffix of the toolchain GNU compiler and its binutils. + +See also :variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX` +and :variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_MACHINE`. diff --git a/Help/variable/CMAKE_LANG_ARCHIVE_APPEND.rst b/Help/variable/CMAKE_LANG_ARCHIVE_APPEND.rst new file mode 100644 index 0000000..ab4ad71 --- /dev/null +++ b/Help/variable/CMAKE_LANG_ARCHIVE_APPEND.rst @@ -0,0 +1,10 @@ +CMAKE_<LANG>_ARCHIVE_APPEND +--------------------------- + +Rule variable to append to a static archive. + +This is a rule variable that tells CMake how to append to a static +archive. It is used in place of :variable:`CMAKE_<LANG>_CREATE_STATIC_LIBRARY` +on some platforms in order to support large object counts. See also +:variable:`CMAKE_<LANG>_ARCHIVE_CREATE` and +:variable:`CMAKE_<LANG>_ARCHIVE_FINISH`. diff --git a/Help/variable/CMAKE_LANG_ARCHIVE_CREATE.rst b/Help/variable/CMAKE_LANG_ARCHIVE_CREATE.rst new file mode 100644 index 0000000..fc295af --- /dev/null +++ b/Help/variable/CMAKE_LANG_ARCHIVE_CREATE.rst @@ -0,0 +1,10 @@ +CMAKE_<LANG>_ARCHIVE_CREATE +--------------------------- + +Rule variable to create a new static archive. + +This is a rule variable that tells CMake how to create a static +archive. It is used in place of :variable:`CMAKE_<LANG>_CREATE_STATIC_LIBRARY` +on some platforms in order to support large object counts. See also +:variable:`CMAKE_<LANG>_ARCHIVE_APPEND` and +:variable:`CMAKE_<LANG>_ARCHIVE_FINISH`. diff --git a/Help/variable/CMAKE_LANG_ARCHIVE_FINISH.rst b/Help/variable/CMAKE_LANG_ARCHIVE_FINISH.rst new file mode 100644 index 0000000..1bb5d65 --- /dev/null +++ b/Help/variable/CMAKE_LANG_ARCHIVE_FINISH.rst @@ -0,0 +1,10 @@ +CMAKE_<LANG>_ARCHIVE_FINISH +--------------------------- + +Rule variable to finish an existing static archive. + +This is a rule variable that tells CMake how to finish a static +archive. It is used in place of :variable:`CMAKE_<LANG>_CREATE_STATIC_LIBRARY` +on some platforms in order to support large object counts. See also +:variable:`CMAKE_<LANG>_ARCHIVE_CREATE` and +:variable:`CMAKE_<LANG>_ARCHIVE_APPEND`. diff --git a/Help/variable/CMAKE_LANG_BYTE_ORDER.rst b/Help/variable/CMAKE_LANG_BYTE_ORDER.rst new file mode 100644 index 0000000..78f0ae6 --- /dev/null +++ b/Help/variable/CMAKE_LANG_BYTE_ORDER.rst @@ -0,0 +1,20 @@ +CMAKE_<LANG>_BYTE_ORDER +----------------------- + +.. versionadded:: 3.20 + +Byte order of ``<LANG>`` compiler target architecture, if known. +If defined and not empty, the value is one of: + +``BIG_ENDIAN`` + The target architecture is Big Endian. + +``LITTLE_ENDIAN`` + The target architecture is Little Endian. + +This is defined for languages ``C``, ``CXX``, ``OBJC``, ``OBJCXX``, +and ``CUDA``. + +If :variable:`CMAKE_OSX_ARCHITECTURES` specifies multiple architectures, the +value of ``CMAKE_<LANG>_BYTE_ORDER`` is non-empty only if all architectures +share the same byte order. diff --git a/Help/variable/CMAKE_LANG_CLANG_TIDY.rst b/Help/variable/CMAKE_LANG_CLANG_TIDY.rst new file mode 100644 index 0000000..32e27b0 --- /dev/null +++ b/Help/variable/CMAKE_LANG_CLANG_TIDY.rst @@ -0,0 +1,15 @@ +CMAKE_<LANG>_CLANG_TIDY +----------------------- + +.. versionadded:: 3.6 + +Default value for :prop_tgt:`<LANG>_CLANG_TIDY` target property +when ``<LANG>`` is ``C``, ``CXX``, ``OBJC`` or ``OBJCXX``. + +This variable is used to initialize the property on each target as it is +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.rst b/Help/variable/CMAKE_LANG_COMPILER.rst new file mode 100644 index 0000000..e694b33 --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER.rst @@ -0,0 +1,32 @@ +CMAKE_<LANG>_COMPILER +--------------------- + +The full path to the compiler for ``LANG``. + +This is the command that will be used as the ``<LANG>`` compiler. Once +set, you can not change this variable. + +Usage +^^^^^ + +This variable can be set by the user during the first time a build tree is configured. + +If a non-full path value is supplied then CMake will resolve the full path of +the compiler. + +The variable could be set in a user supplied toolchain file or via `-D` on the command line. + +.. note:: + Options that are required to make the compiler work correctly can be included + as items in a list; they can not be changed. + +.. code-block:: cmake + + #set within user supplied toolchain file + set(CMAKE_C_COMPILER /full/path/to/qcc --arg1 --arg2) + +or + +.. code-block:: console + + $ cmake ... -DCMAKE_C_COMPILER='qcc;--arg1;--arg2' diff --git a/Help/variable/CMAKE_LANG_COMPILER_ABI.rst b/Help/variable/CMAKE_LANG_COMPILER_ABI.rst new file mode 100644 index 0000000..be946c0 --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_ABI.rst @@ -0,0 +1,6 @@ +CMAKE_<LANG>_COMPILER_ABI +------------------------- + +An internal variable subject to change. + +This is used in determining the compiler ABI and is subject to change. diff --git a/Help/variable/CMAKE_LANG_COMPILER_AR.rst b/Help/variable/CMAKE_LANG_COMPILER_AR.rst new file mode 100644 index 0000000..74f2758 --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_AR.rst @@ -0,0 +1,9 @@ +CMAKE_<LANG>_COMPILER_AR +------------------------ + +.. versionadded:: 3.9 + +A wrapper around ``ar`` adding the appropriate ``--plugin`` option for the +compiler. + +See also :variable:`CMAKE_AR`. 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 0000000..8057566 --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_ARCHITECTURE_ID.rst @@ -0,0 +1,10 @@ +CMAKE_<LANG>_COMPILER_ARCHITECTURE_ID +------------------------------------- + +.. versionadded:: 3.10 + +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 new file mode 100644 index 0000000..cbe3544 --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN.rst @@ -0,0 +1,13 @@ +CMAKE_<LANG>_COMPILER_EXTERNAL_TOOLCHAIN +---------------------------------------- + +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 +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 +the :variable:`CMAKE_TOOLCHAIN_FILE` variable. diff --git a/Help/variable/CMAKE_LANG_COMPILER_ID.rst b/Help/variable/CMAKE_LANG_COMPILER_ID.rst new file mode 100644 index 0000000..0abedde --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_ID.rst @@ -0,0 +1,45 @@ +CMAKE_<LANG>_COMPILER_ID +------------------------ + +Compiler identification string. + +A short string unique to the compiler vendor. Possible values +include: + +:: + + Absoft = Absoft Fortran (absoft.com) + 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 + Fujitsu = Fujitsu HPC compiler (Trad mode) + FujitsuClang = Fujitsu HPC compiler (Clang mode) + 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) + IntelLLVM = Intel LLVM-Based Compiler (intel.com) + MSVC = Microsoft Visual Studio (microsoft.com) + NVHPC = NVIDIA HPC SDK Compiler (nvidia.com) + NVIDIA = NVIDIA CUDA Compiler (nvidia.com) + OpenWatcom = Open Watcom (openwatcom.org) + PGI = The Portland Group (pgroup.com) + PathScale = PathScale (pathscale.com) + SDCC = Small Device C Compiler (sdcc.sourceforge.net) + SunPro = Oracle Solaris Studio (oracle.com) + 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 new file mode 100644 index 0000000..89fd7bc --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst @@ -0,0 +1,12 @@ +CMAKE_<LANG>_COMPILER_LAUNCHER +------------------------------ + +.. versionadded:: 3.4 + +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``, ``CXX``, ``Fortran``, +``ISPC``, ``OBJC``, ``OBJCXX``, or ``CUDA``. + +This variable is initialized to the :envvar:`CMAKE_<LANG>_COMPILER_LAUNCHER` +environment variable if it is set. diff --git a/Help/variable/CMAKE_LANG_COMPILER_LOADED.rst b/Help/variable/CMAKE_LANG_COMPILER_LOADED.rst new file mode 100644 index 0000000..9308878 --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_LOADED.rst @@ -0,0 +1,7 @@ +CMAKE_<LANG>_COMPILER_LOADED +---------------------------- + +Defined to true if the language is enabled. + +When language ``<LANG>`` is enabled by :command:`project` or +:command:`enable_language` this variable is defined to ``1``. 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 0000000..935329a --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_PREDEFINES_COMMAND.rst @@ -0,0 +1,10 @@ +CMAKE_<LANG>_COMPILER_PREDEFINES_COMMAND +---------------------------------------- + +.. versionadded:: 3.10 + +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_RANLIB.rst b/Help/variable/CMAKE_LANG_COMPILER_RANLIB.rst new file mode 100644 index 0000000..1d10b55 --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_RANLIB.rst @@ -0,0 +1,9 @@ +CMAKE_<LANG>_COMPILER_RANLIB +---------------------------- + +.. versionadded:: 3.9 + +A wrapper around ``ranlib`` adding the appropriate ``--plugin`` option for the +compiler. + +See also :variable:`CMAKE_RANLIB`. diff --git a/Help/variable/CMAKE_LANG_COMPILER_TARGET.rst b/Help/variable/CMAKE_LANG_COMPILER_TARGET.rst new file mode 100644 index 0000000..656c57d --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_TARGET.rst @@ -0,0 +1,11 @@ +CMAKE_<LANG>_COMPILER_TARGET +---------------------------- + +The target for cross-compiling, if supported. + +Some compiler drivers are inherently cross-compilers, such as clang and +QNX qcc. These compiler drivers support a command-line argument to specify +the target to cross-compile for. + +This variable may only be set in a toolchain file specified by +the :variable:`CMAKE_TOOLCHAIN_FILE` variable. diff --git a/Help/variable/CMAKE_LANG_COMPILER_VERSION.rst b/Help/variable/CMAKE_LANG_COMPILER_VERSION.rst new file mode 100644 index 0000000..27b0cad --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_VERSION.rst @@ -0,0 +1,12 @@ +CMAKE_<LANG>_COMPILER_VERSION +----------------------------- + +Compiler version string. + +Compiler version in major[.minor[.patch[.tweak]]] format. This +variable is not guaranteed to be defined for all compilers or +languages. + +For example ``CMAKE_C_COMPILER_VERSION`` and +``CMAKE_CXX_COMPILER_VERSION`` might indicate the respective C and C++ +compiler version. 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 0000000..596a989 --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_VERSION_INTERNAL.rst @@ -0,0 +1,10 @@ +CMAKE_<LANG>_COMPILER_VERSION_INTERNAL +-------------------------------------- + +.. versionadded:: 3.10 + +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_COMPILE_OBJECT.rst b/Help/variable/CMAKE_LANG_COMPILE_OBJECT.rst new file mode 100644 index 0000000..ba59cad --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILE_OBJECT.rst @@ -0,0 +1,7 @@ +CMAKE_<LANG>_COMPILE_OBJECT +--------------------------- + +Rule variable to compile a single object file. + +This is a rule variable that tells CMake how to compile a single +object file for the language ``<LANG>``. diff --git a/Help/variable/CMAKE_LANG_CPPCHECK.rst b/Help/variable/CMAKE_LANG_CPPCHECK.rst new file mode 100644 index 0000000..5ae5faf --- /dev/null +++ b/Help/variable/CMAKE_LANG_CPPCHECK.rst @@ -0,0 +1,8 @@ +CMAKE_<LANG>_CPPCHECK +--------------------- + +.. versionadded:: 3.10 + +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_CPPLINT.rst b/Help/variable/CMAKE_LANG_CPPLINT.rst new file mode 100644 index 0000000..ab7b0fc --- /dev/null +++ b/Help/variable/CMAKE_LANG_CPPLINT.rst @@ -0,0 +1,8 @@ +CMAKE_<LANG>_CPPLINT +-------------------- + +.. versionadded:: 3.8 + +Default value for :prop_tgt:`<LANG>_CPPLINT` 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 new file mode 100644 index 0000000..16fcc03 --- /dev/null +++ b/Help/variable/CMAKE_LANG_CREATE_SHARED_LIBRARY.rst @@ -0,0 +1,8 @@ +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>``. 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 new file mode 100644 index 0000000..807229d --- /dev/null +++ b/Help/variable/CMAKE_LANG_CREATE_SHARED_MODULE.rst @@ -0,0 +1,8 @@ +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>``. This rule variable is a ``;`` delimited +list of commands to run. diff --git a/Help/variable/CMAKE_LANG_CREATE_STATIC_LIBRARY.rst b/Help/variable/CMAKE_LANG_CREATE_STATIC_LIBRARY.rst new file mode 100644 index 0000000..0cff200 --- /dev/null +++ b/Help/variable/CMAKE_LANG_CREATE_STATIC_LIBRARY.rst @@ -0,0 +1,7 @@ +CMAKE_<LANG>_CREATE_STATIC_LIBRARY +---------------------------------- + +Rule variable to create a static library. + +This is a rule variable that tells CMake how to create a static +library for the language ``<LANG>``. diff --git a/Help/variable/CMAKE_LANG_FLAGS.rst b/Help/variable/CMAKE_LANG_FLAGS.rst new file mode 100644 index 0000000..11864f8 --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS.rst @@ -0,0 +1,20 @@ +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. + +This value is a command-line string fragment. Therefore, multiple options +should be separated by spaces, and options with spaces should be quoted. diff --git a/Help/variable/CMAKE_LANG_FLAGS_CONFIG.rst b/Help/variable/CMAKE_LANG_FLAGS_CONFIG.rst new file mode 100644 index 0000000..628b62b --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_CONFIG.rst @@ -0,0 +1,6 @@ +CMAKE_<LANG>_FLAGS_<CONFIG> +--------------------------- + +.. versionadded:: 3.11 + +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 0000000..17669a2 --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_CONFIG_INIT.rst @@ -0,0 +1,12 @@ +CMAKE_<LANG>_FLAGS_<CONFIG>_INIT +-------------------------------- + +.. versionadded:: 3.11 + +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 new file mode 100644 index 0000000..6be424a --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_DEBUG.rst @@ -0,0 +1,5 @@ +CMAKE_<LANG>_FLAGS_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 new file mode 100644 index 0000000..49c9e99 --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_DEBUG_INIT.rst @@ -0,0 +1,7 @@ +CMAKE_<LANG>_FLAGS_DEBUG_INIT +----------------------------- + +.. versionadded:: 3.7 + +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 new file mode 100644 index 0000000..ca13a29 --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_INIT.rst @@ -0,0 +1,19 @@ +CMAKE_<LANG>_FLAGS_INIT +----------------------- + +.. versionadded:: 3.7 + +Value used to initialize the :variable:`CMAKE_<LANG>_FLAGS` 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. For example, +the contents of a ``xxxFLAGS`` environment variable will be prepended, +where ``xxx`` will be language-specific but not necessarily the same as +``<LANG>`` (e.g. :envvar:`CXXFLAGS` for ``CXX``, :envvar:`FFLAGS` for +``Fortran``, and so on). +This value is a command-line string fragment. Therefore, multiple options +should be separated by spaces, and options with spaces should be quoted. + +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 new file mode 100644 index 0000000..634fab9 --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL.rst @@ -0,0 +1,5 @@ +CMAKE_<LANG>_FLAGS_MINSIZEREL +----------------------------- + +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 new file mode 100644 index 0000000..3600909 --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL_INIT.rst @@ -0,0 +1,7 @@ +CMAKE_<LANG>_FLAGS_MINSIZEREL_INIT +---------------------------------- + +.. versionadded:: 3.7 + +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 new file mode 100644 index 0000000..3baeab0 --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_RELEASE.rst @@ -0,0 +1,5 @@ +CMAKE_<LANG>_FLAGS_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 new file mode 100644 index 0000000..e889852 --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_RELEASE_INIT.rst @@ -0,0 +1,7 @@ +CMAKE_<LANG>_FLAGS_RELEASE_INIT +------------------------------- + +.. versionadded:: 3.7 + +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 new file mode 100644 index 0000000..67a5073 --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO.rst @@ -0,0 +1,5 @@ +CMAKE_<LANG>_FLAGS_RELWITHDEBINFO +--------------------------------- + +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 new file mode 100644 index 0000000..b42caee --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT.rst @@ -0,0 +1,7 @@ +CMAKE_<LANG>_FLAGS_RELWITHDEBINFO_INIT +-------------------------------------- + +.. versionadded:: 3.7 + +This variable is the ``RelWithDebInfo`` variant of the +:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>_INIT` variable. diff --git a/Help/variable/CMAKE_LANG_IGNORE_EXTENSIONS.rst b/Help/variable/CMAKE_LANG_IGNORE_EXTENSIONS.rst new file mode 100644 index 0000000..3d07e91 --- /dev/null +++ b/Help/variable/CMAKE_LANG_IGNORE_EXTENSIONS.rst @@ -0,0 +1,7 @@ +CMAKE_<LANG>_IGNORE_EXTENSIONS +------------------------------ + +File extensions that should be ignored by the build. + +This is a list of file extensions that may be part of a project for a +given language but are not compiled. diff --git a/Help/variable/CMAKE_LANG_IMPLICIT_INCLUDE_DIRECTORIES.rst b/Help/variable/CMAKE_LANG_IMPLICIT_INCLUDE_DIRECTORIES.rst new file mode 100644 index 0000000..e361fd9 --- /dev/null +++ b/Help/variable/CMAKE_LANG_IMPLICIT_INCLUDE_DIRECTORIES.rst @@ -0,0 +1,14 @@ +CMAKE_<LANG>_IMPLICIT_INCLUDE_DIRECTORIES +----------------------------------------- + +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, 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 new file mode 100644 index 0000000..e9e04be --- /dev/null +++ b/Help/variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES.rst @@ -0,0 +1,20 @@ +CMAKE_<LANG>_IMPLICIT_LINK_DIRECTORIES +-------------------------------------- + +Implicit linker search path detected for language ``<LANG>``. + +Compilers typically pass directories containing language runtime +libraries and default library search paths when they invoke a linker. +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. + +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_IMPLICIT_LINK_FRAMEWORK_DIRECTORIES.rst b/Help/variable/CMAKE_LANG_IMPLICIT_LINK_FRAMEWORK_DIRECTORIES.rst new file mode 100644 index 0000000..61ccc5a --- /dev/null +++ b/Help/variable/CMAKE_LANG_IMPLICIT_LINK_FRAMEWORK_DIRECTORIES.rst @@ -0,0 +1,8 @@ +CMAKE_<LANG>_IMPLICIT_LINK_FRAMEWORK_DIRECTORIES +------------------------------------------------ + +Implicit linker framework search path detected for language ``<LANG>``. + +These paths are implicit linker framework search directories for the +compiler's language. CMake automatically detects these directories +for each language and reports the results in this variable. diff --git a/Help/variable/CMAKE_LANG_IMPLICIT_LINK_LIBRARIES.rst b/Help/variable/CMAKE_LANG_IMPLICIT_LINK_LIBRARIES.rst new file mode 100644 index 0000000..ec16477 --- /dev/null +++ b/Help/variable/CMAKE_LANG_IMPLICIT_LINK_LIBRARIES.rst @@ -0,0 +1,10 @@ +CMAKE_<LANG>_IMPLICIT_LINK_LIBRARIES +------------------------------------ + +Implicit link libraries and flags detected for language ``<LANG>``. + +Compilers typically pass language runtime library names and other +flags when they invoke a linker. These flags are implicit link +options for the compiler's language. CMake automatically detects +these libraries and flags for each language and reports the results in +this variable. diff --git a/Help/variable/CMAKE_LANG_INCLUDE_WHAT_YOU_USE.rst b/Help/variable/CMAKE_LANG_INCLUDE_WHAT_YOU_USE.rst new file mode 100644 index 0000000..be6c210 --- /dev/null +++ b/Help/variable/CMAKE_LANG_INCLUDE_WHAT_YOU_USE.rst @@ -0,0 +1,8 @@ +CMAKE_<LANG>_INCLUDE_WHAT_YOU_USE +--------------------------------- + +.. versionadded:: 3.3 + +Default value for :prop_tgt:`<LANG>_INCLUDE_WHAT_YOU_USE` 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_LIBRARY_ARCHITECTURE.rst b/Help/variable/CMAKE_LANG_LIBRARY_ARCHITECTURE.rst new file mode 100644 index 0000000..7f888ee --- /dev/null +++ b/Help/variable/CMAKE_LANG_LIBRARY_ARCHITECTURE.rst @@ -0,0 +1,8 @@ +CMAKE_<LANG>_LIBRARY_ARCHITECTURE +--------------------------------- + +Target architecture library directory name detected for ``<LANG>``. + +If the ``<LANG>`` compiler passes to the linker an architecture-specific +system library search directory such as ``<prefix>/lib/<arch>`` this +variable contains the ``<arch>`` name if/as detected by CMake. diff --git a/Help/variable/CMAKE_LANG_LINKER_PREFERENCE.rst b/Help/variable/CMAKE_LANG_LINKER_PREFERENCE.rst new file mode 100644 index 0000000..ff82f8b --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINKER_PREFERENCE.rst @@ -0,0 +1,11 @@ +CMAKE_<LANG>_LINKER_PREFERENCE +------------------------------ + +Preference value for linker language selection. + +The "linker language" for executable, shared library, and module +targets is the language whose compiler will invoke the linker. The +:prop_tgt:`LINKER_LANGUAGE` target property sets the language explicitly. +Otherwise, the linker language is that whose linker preference value +is highest among languages compiled and linked into the target. See +also the :variable:`CMAKE_<LANG>_LINKER_PREFERENCE_PROPAGATES` variable. diff --git a/Help/variable/CMAKE_LANG_LINKER_PREFERENCE_PROPAGATES.rst b/Help/variable/CMAKE_LANG_LINKER_PREFERENCE_PROPAGATES.rst new file mode 100644 index 0000000..dbbeb0a --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINKER_PREFERENCE_PROPAGATES.rst @@ -0,0 +1,9 @@ +CMAKE_<LANG>_LINKER_PREFERENCE_PROPAGATES +----------------------------------------- + +True if :variable:`CMAKE_<LANG>_LINKER_PREFERENCE` propagates across targets. + +This is used when CMake selects a linker language for a target. +Languages compiled directly into the target are always considered. A +language compiled into static libraries linked by the target is +considered if this variable is true. 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 0000000..471c351 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINKER_WRAPPER_FLAG.rst @@ -0,0 +1,41 @@ +CMAKE_<LANG>_LINKER_WRAPPER_FLAG +-------------------------------- + +.. versionadded:: 3.13 + +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 0000000..a3895af --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINKER_WRAPPER_FLAG_SEP.rst @@ -0,0 +1,11 @@ +CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP +------------------------------------ + +.. versionadded:: 3.13 + +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_EXECUTABLE.rst b/Help/variable/CMAKE_LANG_LINK_EXECUTABLE.rst new file mode 100644 index 0000000..abd5891 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_EXECUTABLE.rst @@ -0,0 +1,6 @@ +CMAKE_<LANG>_LINK_EXECUTABLE +---------------------------- + +Rule variable to link an executable. + +Rule variable to link an executable for the given language. 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 0000000..23ece88 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_LIBRARY_FILE_FLAG.rst @@ -0,0 +1,10 @@ +CMAKE_<LANG>_LINK_LIBRARY_FILE_FLAG +----------------------------------- + +.. versionadded:: 3.16 + +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 0000000..0f528db --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_LIBRARY_FLAG.rst @@ -0,0 +1,9 @@ +CMAKE_<LANG>_LINK_LIBRARY_FLAG +------------------------------ + +.. versionadded:: 3.16 + +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 0000000..359e29f --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_LIBRARY_SUFFIX.rst @@ -0,0 +1,8 @@ +CMAKE_<LANG>_LINK_LIBRARY_SUFFIX +-------------------------------- + +.. versionadded:: 3.16 + +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_LANG_OUTPUT_EXTENSION.rst b/Help/variable/CMAKE_LANG_OUTPUT_EXTENSION.rst new file mode 100644 index 0000000..0fbc566 --- /dev/null +++ b/Help/variable/CMAKE_LANG_OUTPUT_EXTENSION.rst @@ -0,0 +1,7 @@ +CMAKE_<LANG>_OUTPUT_EXTENSION +----------------------------- + +Extension for the output of a compile for a single file. + +This is the extension for an object file for the given ``<LANG>``. For +example ``.obj`` for C on Windows. diff --git a/Help/variable/CMAKE_LANG_PLATFORM_ID.rst b/Help/variable/CMAKE_LANG_PLATFORM_ID.rst new file mode 100644 index 0000000..1b243e3 --- /dev/null +++ b/Help/variable/CMAKE_LANG_PLATFORM_ID.rst @@ -0,0 +1,6 @@ +CMAKE_<LANG>_PLATFORM_ID +------------------------ + +An internal variable subject to change. + +This is used in determining the platform and is subject to change. diff --git a/Help/variable/CMAKE_LANG_SIMULATE_ID.rst b/Help/variable/CMAKE_LANG_SIMULATE_ID.rst new file mode 100644 index 0000000..15c87a1 --- /dev/null +++ b/Help/variable/CMAKE_LANG_SIMULATE_ID.rst @@ -0,0 +1,9 @@ +CMAKE_<LANG>_SIMULATE_ID +------------------------ + +Identification string of "simulated" compiler. + +Some compilers simulate other compilers to serve as drop-in +replacements. When CMake detects such a compiler it sets this +variable to what would have been the :variable:`CMAKE_<LANG>_COMPILER_ID` for +the simulated compiler. diff --git a/Help/variable/CMAKE_LANG_SIMULATE_VERSION.rst b/Help/variable/CMAKE_LANG_SIMULATE_VERSION.rst new file mode 100644 index 0000000..d6325e0 --- /dev/null +++ b/Help/variable/CMAKE_LANG_SIMULATE_VERSION.rst @@ -0,0 +1,9 @@ +CMAKE_<LANG>_SIMULATE_VERSION +----------------------------- + +Version string of "simulated" compiler. + +Some compilers simulate other compilers to serve as drop-in +replacements. When CMake detects such a compiler it sets this +variable to what would have been the :variable:`CMAKE_<LANG>_COMPILER_VERSION` +for the simulated compiler. diff --git a/Help/variable/CMAKE_LANG_SIZEOF_DATA_PTR.rst b/Help/variable/CMAKE_LANG_SIZEOF_DATA_PTR.rst new file mode 100644 index 0000000..7465923 --- /dev/null +++ b/Help/variable/CMAKE_LANG_SIZEOF_DATA_PTR.rst @@ -0,0 +1,7 @@ +CMAKE_<LANG>_SIZEOF_DATA_PTR +---------------------------- + +Size of pointer-to-data types for language ``<LANG>``. + +This holds the size (in bytes) of pointer-to-data types in the target +platform ABI. It is defined for languages ``C`` and ``CXX`` (C++). diff --git a/Help/variable/CMAKE_LANG_SOURCE_FILE_EXTENSIONS.rst b/Help/variable/CMAKE_LANG_SOURCE_FILE_EXTENSIONS.rst new file mode 100644 index 0000000..e085fee --- /dev/null +++ b/Help/variable/CMAKE_LANG_SOURCE_FILE_EXTENSIONS.rst @@ -0,0 +1,6 @@ +CMAKE_<LANG>_SOURCE_FILE_EXTENSIONS +----------------------------------- + +Extensions of source files for the given language. + +This is the list of extensions for a given language's source files. diff --git a/Help/variable/CMAKE_LANG_STANDARD_INCLUDE_DIRECTORIES.rst b/Help/variable/CMAKE_LANG_STANDARD_INCLUDE_DIRECTORIES.rst new file mode 100644 index 0000000..24aca8b --- /dev/null +++ b/Help/variable/CMAKE_LANG_STANDARD_INCLUDE_DIRECTORIES.rst @@ -0,0 +1,16 @@ +CMAKE_<LANG>_STANDARD_INCLUDE_DIRECTORIES +----------------------------------------- + +.. versionadded:: 3.6 + +Include directories to be used for every source file compiled with +the ``<LANG>`` compiler. This is meant for specification of system +include directories needed by the language for the current platform. +The directories always appear at the end of the include path passed +to the compiler. + +This variable should not be set by project code. It is meant to be set by +CMake's platform information modules for the current toolchain, or by a +toolchain file when used with :variable:`CMAKE_TOOLCHAIN_FILE`. + +See also :variable:`CMAKE_<LANG>_STANDARD_LIBRARIES`. diff --git a/Help/variable/CMAKE_LANG_STANDARD_LIBRARIES.rst b/Help/variable/CMAKE_LANG_STANDARD_LIBRARIES.rst new file mode 100644 index 0000000..d5f3351 --- /dev/null +++ b/Help/variable/CMAKE_LANG_STANDARD_LIBRARIES.rst @@ -0,0 +1,14 @@ +CMAKE_<LANG>_STANDARD_LIBRARIES +------------------------------- + +.. versionadded:: 3.6 + +Libraries linked into every executable and shared library linked +for language ``<LANG>``. This is meant for specification of system +libraries needed by the language for the current platform. + +This variable should not be set by project code. It is meant to be set by +CMake's platform information modules for the current toolchain, or by a +toolchain file when used with :variable:`CMAKE_TOOLCHAIN_FILE`. + +See also :variable:`CMAKE_<LANG>_STANDARD_INCLUDE_DIRECTORIES`. diff --git a/Help/variable/CMAKE_LANG_VISIBILITY_PRESET.rst b/Help/variable/CMAKE_LANG_VISIBILITY_PRESET.rst new file mode 100644 index 0000000..1961ea0 --- /dev/null +++ b/Help/variable/CMAKE_LANG_VISIBILITY_PRESET.rst @@ -0,0 +1,5 @@ +CMAKE_<LANG>_VISIBILITY_PRESET +------------------------------ + +Default value for the :prop_tgt:`<LANG>_VISIBILITY_PRESET` target +property when a target is created. diff --git a/Help/variable/CMAKE_LIBRARY_ARCHITECTURE.rst b/Help/variable/CMAKE_LIBRARY_ARCHITECTURE.rst new file mode 100644 index 0000000..8a7dcbd --- /dev/null +++ b/Help/variable/CMAKE_LIBRARY_ARCHITECTURE.rst @@ -0,0 +1,7 @@ +CMAKE_LIBRARY_ARCHITECTURE +-------------------------- + +Target architecture library directory name, if detected. + +This is the value of :variable:`CMAKE_<LANG>_LIBRARY_ARCHITECTURE` as detected +for one of the enabled languages. diff --git a/Help/variable/CMAKE_LIBRARY_ARCHITECTURE_REGEX.rst b/Help/variable/CMAKE_LIBRARY_ARCHITECTURE_REGEX.rst new file mode 100644 index 0000000..1eb2ac2 --- /dev/null +++ b/Help/variable/CMAKE_LIBRARY_ARCHITECTURE_REGEX.rst @@ -0,0 +1,7 @@ +CMAKE_LIBRARY_ARCHITECTURE_REGEX +-------------------------------- + +Regex matching possible target architecture library directory names. + +This is used to detect :variable:`CMAKE_<LANG>_LIBRARY_ARCHITECTURE` from the +implicit linker search path by matching the ``<arch>`` name. diff --git a/Help/variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY.rst b/Help/variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY.rst new file mode 100644 index 0000000..e97296d --- /dev/null +++ b/Help/variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY.rst @@ -0,0 +1,9 @@ +CMAKE_LIBRARY_OUTPUT_DIRECTORY +------------------------------ + +Where to put all the :ref:`LIBRARY <Library Output Artifacts>` +target files when built. + +This variable is used to initialize the :prop_tgt:`LIBRARY_OUTPUT_DIRECTORY` +property on all the targets. See that target property for additional +information. diff --git a/Help/variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY_CONFIG.rst b/Help/variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY_CONFIG.rst new file mode 100644 index 0000000..08f95c4 --- /dev/null +++ b/Help/variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY_CONFIG.rst @@ -0,0 +1,11 @@ +CMAKE_LIBRARY_OUTPUT_DIRECTORY_<CONFIG> +--------------------------------------- + +.. versionadded:: 3.3 + +Where to put all the :ref:`LIBRARY <Library Output Artifacts>` +target files when built for a specific configuration. + +This variable is used to initialize the +:prop_tgt:`LIBRARY_OUTPUT_DIRECTORY_<CONFIG>` property on all the targets. +See that target property for additional information. diff --git a/Help/variable/CMAKE_LIBRARY_PATH.rst b/Help/variable/CMAKE_LIBRARY_PATH.rst new file mode 100644 index 0000000..8135b65 --- /dev/null +++ b/Help/variable/CMAKE_LIBRARY_PATH.rst @@ -0,0 +1,7 @@ +CMAKE_LIBRARY_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_LIBRARY_PATH_FLAG.rst b/Help/variable/CMAKE_LIBRARY_PATH_FLAG.rst new file mode 100644 index 0000000..ebe5fda --- /dev/null +++ b/Help/variable/CMAKE_LIBRARY_PATH_FLAG.rst @@ -0,0 +1,7 @@ +CMAKE_LIBRARY_PATH_FLAG +----------------------- + +The flag to be used to add a library search path to a compiler. + +The flag will be used to specify a library directory to the compiler. +On most compilers this is ``-L``. diff --git a/Help/variable/CMAKE_LINK_DEF_FILE_FLAG.rst b/Help/variable/CMAKE_LINK_DEF_FILE_FLAG.rst new file mode 100644 index 0000000..fa09f9f --- /dev/null +++ b/Help/variable/CMAKE_LINK_DEF_FILE_FLAG.rst @@ -0,0 +1,7 @@ +CMAKE_LINK_DEF_FILE_FLAG +------------------------ + +Linker flag to be used to specify a ``.def`` file for dll creation. + +The flag will be used to add a ``.def`` file when creating a dll on +Windows; this is only defined on Windows. diff --git a/Help/variable/CMAKE_LINK_DEPENDS_NO_SHARED.rst b/Help/variable/CMAKE_LINK_DEPENDS_NO_SHARED.rst new file mode 100644 index 0000000..cec7906 --- /dev/null +++ b/Help/variable/CMAKE_LINK_DEPENDS_NO_SHARED.rst @@ -0,0 +1,8 @@ +CMAKE_LINK_DEPENDS_NO_SHARED +---------------------------- + +Whether to skip link dependencies on shared library files. + +This variable initializes the :prop_tgt:`LINK_DEPENDS_NO_SHARED` property on +targets when they are created. See that target property for +additional information. diff --git a/Help/variable/CMAKE_LINK_DIRECTORIES_BEFORE.rst b/Help/variable/CMAKE_LINK_DIRECTORIES_BEFORE.rst new file mode 100644 index 0000000..f120866 --- /dev/null +++ b/Help/variable/CMAKE_LINK_DIRECTORIES_BEFORE.rst @@ -0,0 +1,11 @@ +CMAKE_LINK_DIRECTORIES_BEFORE +----------------------------- + +.. versionadded:: 3.13 + +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_LINK_INTERFACE_LIBRARIES.rst b/Help/variable/CMAKE_LINK_INTERFACE_LIBRARIES.rst new file mode 100644 index 0000000..33865da --- /dev/null +++ b/Help/variable/CMAKE_LINK_INTERFACE_LIBRARIES.rst @@ -0,0 +1,8 @@ +CMAKE_LINK_INTERFACE_LIBRARIES +------------------------------ + +Default value for :prop_tgt:`LINK_INTERFACE_LIBRARIES` of targets. + +This variable is used to initialize the :prop_tgt:`LINK_INTERFACE_LIBRARIES` +property on all the targets. See that target property for additional +information. diff --git a/Help/variable/CMAKE_LINK_LIBRARY_FILE_FLAG.rst b/Help/variable/CMAKE_LINK_LIBRARY_FILE_FLAG.rst new file mode 100644 index 0000000..6858e2c --- /dev/null +++ b/Help/variable/CMAKE_LINK_LIBRARY_FILE_FLAG.rst @@ -0,0 +1,7 @@ +CMAKE_LINK_LIBRARY_FILE_FLAG +---------------------------- + +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_LINK_LIBRARY_FLAG.rst b/Help/variable/CMAKE_LINK_LIBRARY_FLAG.rst new file mode 100644 index 0000000..b5197e4 --- /dev/null +++ b/Help/variable/CMAKE_LINK_LIBRARY_FLAG.rst @@ -0,0 +1,7 @@ +CMAKE_LINK_LIBRARY_FLAG +----------------------- + +Flag to be used to link a library into an executable. + +The flag will be used to specify a library to link to an executable. +On most compilers this is ``-l``. diff --git a/Help/variable/CMAKE_LINK_LIBRARY_SUFFIX.rst b/Help/variable/CMAKE_LINK_LIBRARY_SUFFIX.rst new file mode 100644 index 0000000..0ddafe8 --- /dev/null +++ b/Help/variable/CMAKE_LINK_LIBRARY_SUFFIX.rst @@ -0,0 +1,6 @@ +CMAKE_LINK_LIBRARY_SUFFIX +------------------------- + +The 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_LINK_SEARCH_END_STATIC.rst b/Help/variable/CMAKE_LINK_SEARCH_END_STATIC.rst new file mode 100644 index 0000000..e86f639 --- /dev/null +++ b/Help/variable/CMAKE_LINK_SEARCH_END_STATIC.rst @@ -0,0 +1,21 @@ +CMAKE_LINK_SEARCH_END_STATIC +---------------------------- + +.. versionadded:: 3.4 + +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. +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. + +This variable is used to initialize the target property +:prop_tgt:`LINK_SEARCH_END_STATIC` for all targets. If set, its +value is also used by the :command:`try_compile` command. + +See also :variable:`CMAKE_LINK_SEARCH_START_STATIC`. diff --git a/Help/variable/CMAKE_LINK_SEARCH_START_STATIC.rst b/Help/variable/CMAKE_LINK_SEARCH_START_STATIC.rst new file mode 100644 index 0000000..ab1837c --- /dev/null +++ b/Help/variable/CMAKE_LINK_SEARCH_START_STATIC.rst @@ -0,0 +1,22 @@ +CMAKE_LINK_SEARCH_START_STATIC +------------------------------ + +.. versionadded:: 3.4 + +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. +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`` +option). + +This variable is used to initialize the target property +:prop_tgt:`LINK_SEARCH_START_STATIC` for all targets. If set, its +value is also used by the :command:`try_compile` command. + +See also :variable:`CMAKE_LINK_SEARCH_END_STATIC`. diff --git a/Help/variable/CMAKE_LINK_WHAT_YOU_USE.rst b/Help/variable/CMAKE_LINK_WHAT_YOU_USE.rst new file mode 100644 index 0000000..06b3aa8 --- /dev/null +++ b/Help/variable/CMAKE_LINK_WHAT_YOU_USE.rst @@ -0,0 +1,8 @@ +CMAKE_LINK_WHAT_YOU_USE +--------------------------------- + +.. versionadded:: 3.7 + +Default value for :prop_tgt:`LINK_WHAT_YOU_USE` target property. +This variable is used to initialize the property on each target as it is +created. diff --git a/Help/variable/CMAKE_MACOSX_BUNDLE.rst b/Help/variable/CMAKE_MACOSX_BUNDLE.rst new file mode 100644 index 0000000..43ddff5 --- /dev/null +++ b/Help/variable/CMAKE_MACOSX_BUNDLE.rst @@ -0,0 +1,10 @@ +CMAKE_MACOSX_BUNDLE +------------------- + +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 new file mode 100644 index 0000000..2fc648d --- /dev/null +++ b/Help/variable/CMAKE_MACOSX_RPATH.rst @@ -0,0 +1,7 @@ +CMAKE_MACOSX_RPATH +------------------- + +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_MAJOR_VERSION.rst b/Help/variable/CMAKE_MAJOR_VERSION.rst new file mode 100644 index 0000000..079ad70 --- /dev/null +++ b/Help/variable/CMAKE_MAJOR_VERSION.rst @@ -0,0 +1,5 @@ +CMAKE_MAJOR_VERSION +------------------- + +First version number component of the :variable:`CMAKE_VERSION` +variable. diff --git a/Help/variable/CMAKE_MAKE_PROGRAM.rst b/Help/variable/CMAKE_MAKE_PROGRAM.rst new file mode 100644 index 0000000..a3c8b7c --- /dev/null +++ b/Help/variable/CMAKE_MAKE_PROGRAM.rst @@ -0,0 +1,64 @@ +CMAKE_MAKE_PROGRAM +------------------ + +Tool that can launch the native build system. +The value may be the full path to an executable or just the tool +name if it is expected to be in the ``PATH``. + +The tool selected depends on the :variable:`CMAKE_GENERATOR` used +to configure the project: + +* The :ref:`Makefile Generators` set this to ``make``, ``gmake``, or + a generator-specific tool (e.g. ``nmake`` for :generator:`NMake Makefiles`). + + These generators store ``CMAKE_MAKE_PROGRAM`` in the CMake cache + so that it may be edited by the user. + +* The :generator:`Ninja` generator sets this to ``ninja``. + + 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``. + + 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. + + For compatibility with versions of CMake prior to 3.2, if + a user or project explicitly adds ``CMAKE_MAKE_PROGRAM`` to + the CMake cache then CMake will use the specified value. + +* The :ref:`Visual Studio Generators` set this to the full path to + ``MSBuild.exe`` (VS >= 10), ``devenv.com`` (VS 7,8,9), or + ``VCExpress.exe`` (VS Express 8,9). + (See also variables + :variable:`CMAKE_VS_MSBUILD_COMMAND` and + :variable:`CMAKE_VS_DEVENV_COMMAND`. + + These generators prefer 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 the tools are version-specific + and can be located using the Windows Registry. It is also + necessary because the proper build tool may depend on the + project content (e.g. the Intel Fortran plugin to VS 10 and 11 + requires ``devenv.com`` to build its ``.vfproj`` project files + even though ``MSBuild.exe`` is normally preferred to support + the :variable:`CMAKE_GENERATOR_TOOLSET`). + + For compatibility with versions of CMake prior to 3.0, if + a user or project explicitly adds ``CMAKE_MAKE_PROGRAM`` to + the CMake cache then CMake will use the specified value if + possible. + +* 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 +:manual:`ctest(1)` ``--build-and-test`` tools to launch the native +build process. diff --git a/Help/variable/CMAKE_MAP_IMPORTED_CONFIG_CONFIG.rst b/Help/variable/CMAKE_MAP_IMPORTED_CONFIG_CONFIG.rst new file mode 100644 index 0000000..ed29afe --- /dev/null +++ b/Help/variable/CMAKE_MAP_IMPORTED_CONFIG_CONFIG.rst @@ -0,0 +1,8 @@ +CMAKE_MAP_IMPORTED_CONFIG_<CONFIG> +---------------------------------- + +Default value for :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` of targets. + +This variable is used to initialize the +:prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` property on all the targets. See +that target property for additional information. diff --git a/Help/variable/CMAKE_MATCH_COUNT.rst b/Help/variable/CMAKE_MATCH_COUNT.rst new file mode 100644 index 0000000..deeec8b --- /dev/null +++ b/Help/variable/CMAKE_MATCH_COUNT.rst @@ -0,0 +1,11 @@ +CMAKE_MATCH_COUNT +----------------- + +.. versionadded:: 3.2 + +The number of matches with the last regular expression. + +When a regular expression match is used, CMake fills in +:variable:`CMAKE_MATCH_<n>` variables with the match contents. +The ``CMAKE_MATCH_COUNT`` variable holds the number of match +expressions when these are filled. diff --git a/Help/variable/CMAKE_MATCH_n.rst b/Help/variable/CMAKE_MATCH_n.rst new file mode 100644 index 0000000..a92788e --- /dev/null +++ b/Help/variable/CMAKE_MATCH_n.rst @@ -0,0 +1,12 @@ +CMAKE_MATCH_<n> +--------------- + +.. versionadded:: 3.9 + +Capture group ``<n>`` matched by the last regular expression, for groups +0 through 9. Group 0 is the entire match. Groups 1 through 9 are the +subexpressions captured by ``()`` syntax. + +When a regular expression match is used, CMake fills in ``CMAKE_MATCH_<n>`` +variables with the match contents. The :variable:`CMAKE_MATCH_COUNT` +variable holds the number of match expressions when these are filled. diff --git a/Help/variable/CMAKE_MAXIMUM_RECURSION_DEPTH.rst b/Help/variable/CMAKE_MAXIMUM_RECURSION_DEPTH.rst new file mode 100644 index 0000000..59c60d3 --- /dev/null +++ b/Help/variable/CMAKE_MAXIMUM_RECURSION_DEPTH.rst @@ -0,0 +1,35 @@ +CMAKE_MAXIMUM_RECURSION_DEPTH +----------------------------- + +.. versionadded:: 3.14 + +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_CONTEXT.rst b/Help/variable/CMAKE_MESSAGE_CONTEXT.rst new file mode 100644 index 0000000..41ace43 --- /dev/null +++ b/Help/variable/CMAKE_MESSAGE_CONTEXT.rst @@ -0,0 +1,64 @@ +CMAKE_MESSAGE_CONTEXT +--------------------- + +.. versionadded:: 3.17 + +When enabled by the :manual:`cmake <cmake(1)>` ``--log-context`` command line +option or the :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` variable, the +:command:`message` command converts the ``CMAKE_MESSAGE_CONTEXT`` list into a +dot-separated string surrounded by square brackets and prepends it to each line +for messages of log levels ``NOTICE`` and below. + +For logging contexts to work effectively, projects should generally +``APPEND`` and ``POP_BACK`` an item to the current value of +``CMAKE_MESSAGE_CONTEXT`` rather than replace it. +Projects should not assume the message context at the top of the source tree +is empty, as there are scenarios where the context might have already been set +(e.g. hierarchical projects). + +.. warning:: + + Valid context names are restricted to anything that could be used + as a CMake variable name. All names that begin with an underscore + or the string ``cmake_`` are also reserved for use by CMake and + should not be used by projects. + +Example: + +.. code-block:: cmake + + function(bar) + list(APPEND CMAKE_MESSAGE_CONTEXT "bar") + message(VERBOSE "bar VERBOSE message") + endfunction() + + function(baz) + list(APPEND CMAKE_MESSAGE_CONTEXT "baz") + message(DEBUG "baz DEBUG message") + endfunction() + + function(foo) + list(APPEND CMAKE_MESSAGE_CONTEXT "foo") + bar() + message(TRACE "foo TRACE message") + baz() + endfunction() + + list(APPEND CMAKE_MESSAGE_CONTEXT "top") + + message(VERBOSE "Before `foo`") + foo() + message(VERBOSE "After `foo`") + + list(POP_BACK CMAKE_MESSAGE_CONTEXT) + + +Which results in the following output: + +.. code-block:: none + + -- [top] Before `foo` + -- [top.foo.bar] bar VERBOSE message + -- [top.foo] foo TRACE message + -- [top.foo.baz] baz DEBUG message + -- [top] After `foo` diff --git a/Help/variable/CMAKE_MESSAGE_CONTEXT_SHOW.rst b/Help/variable/CMAKE_MESSAGE_CONTEXT_SHOW.rst new file mode 100644 index 0000000..382e9ff --- /dev/null +++ b/Help/variable/CMAKE_MESSAGE_CONTEXT_SHOW.rst @@ -0,0 +1,17 @@ +CMAKE_MESSAGE_CONTEXT_SHOW +-------------------------- + +.. versionadded:: 3.17 + +Setting this variable to true enables showing a context with each line +logged by the :command:`message` command (see :variable:`CMAKE_MESSAGE_CONTEXT` +for how the context itself is specified). + +This variable is an alternative to providing the ``--log-context`` option +on the :manual:`cmake <cmake(1)>` command line. Whereas the command line +option will apply only to that one CMake run, setting +``CMAKE_MESSAGE_CONTEXT_SHOW`` to true as a cache variable will ensure that +subsequent CMake runs will continue to show the message context. + +Projects should not set ``CMAKE_MESSAGE_CONTEXT_SHOW``. It is intended for +users so that they may control whether or not to include context with messages. diff --git a/Help/variable/CMAKE_MESSAGE_INDENT.rst b/Help/variable/CMAKE_MESSAGE_INDENT.rst new file mode 100644 index 0000000..c6263d2 --- /dev/null +++ b/Help/variable/CMAKE_MESSAGE_INDENT.rst @@ -0,0 +1,34 @@ +CMAKE_MESSAGE_INDENT +-------------------- + +.. versionadded:: 3.16 + +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_MESSAGE_LOG_LEVEL.rst b/Help/variable/CMAKE_MESSAGE_LOG_LEVEL.rst new file mode 100644 index 0000000..3b45d1d --- /dev/null +++ b/Help/variable/CMAKE_MESSAGE_LOG_LEVEL.rst @@ -0,0 +1,17 @@ +CMAKE_MESSAGE_LOG_LEVEL +----------------------- + +.. versionadded:: 3.17 + +When set, this variable specifies the logging level used by the +:command:`message` command. Valid values are the same as those for the +``--log-level`` command line option of the :manual:`cmake(1)` program. +If this variable is set and the ``--log-level`` command line option is +given, the command line option takes precedence. + +The main advantage to using this variable is to make a log level persist +between CMake runs. Setting it as a cache variable will ensure that +subsequent CMake runs will continue to use the chosen log level. + +Projects should not set this variable, it is intended for users so that +they may control the log level according to their own needs. diff --git a/Help/variable/CMAKE_MFC_FLAG.rst b/Help/variable/CMAKE_MFC_FLAG.rst new file mode 100644 index 0000000..118e9c6 --- /dev/null +++ b/Help/variable/CMAKE_MFC_FLAG.rst @@ -0,0 +1,20 @@ +CMAKE_MFC_FLAG +-------------- + +Use the MFC library for an executable or dll. + +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) + add_executable(CMakeSetup WIN32 ${SRCS}) + +Contents of ``CMAKE_MFC_FLAG`` may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/variable/CMAKE_MINIMUM_REQUIRED_VERSION.rst b/Help/variable/CMAKE_MINIMUM_REQUIRED_VERSION.rst new file mode 100644 index 0000000..f466468 --- /dev/null +++ b/Help/variable/CMAKE_MINIMUM_REQUIRED_VERSION.rst @@ -0,0 +1,5 @@ +CMAKE_MINIMUM_REQUIRED_VERSION +------------------------------ + +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_MINOR_VERSION.rst b/Help/variable/CMAKE_MINOR_VERSION.rst new file mode 100644 index 0000000..f67cfb9 --- /dev/null +++ b/Help/variable/CMAKE_MINOR_VERSION.rst @@ -0,0 +1,5 @@ +CMAKE_MINOR_VERSION +------------------- + +Second version number component of the :variable:`CMAKE_VERSION` +variable. diff --git a/Help/variable/CMAKE_MODULE_LINKER_FLAGS.rst b/Help/variable/CMAKE_MODULE_LINKER_FLAGS.rst new file mode 100644 index 0000000..6372bbd --- /dev/null +++ b/Help/variable/CMAKE_MODULE_LINKER_FLAGS.rst @@ -0,0 +1,6 @@ +CMAKE_MODULE_LINKER_FLAGS +------------------------- + +Linker flags to be used to create modules. + +These flags will be used by the linker when creating a module. diff --git a/Help/variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG.rst b/Help/variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG.rst new file mode 100644 index 0000000..393263e --- /dev/null +++ b/Help/variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG.rst @@ -0,0 +1,6 @@ +CMAKE_MODULE_LINKER_FLAGS_<CONFIG> +---------------------------------- + +Flags to be used when linking a module. + +Same as ``CMAKE_C_FLAGS_*`` but used by the linker when creating modules. diff --git a/Help/variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG_INIT.rst b/Help/variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG_INIT.rst new file mode 100644 index 0000000..e8a6401 --- /dev/null +++ b/Help/variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG_INIT.rst @@ -0,0 +1,12 @@ +CMAKE_MODULE_LINKER_FLAGS_<CONFIG>_INIT +--------------------------------------- + +.. versionadded:: 3.7 + +Value used to initialize the :variable:`CMAKE_MODULE_LINKER_FLAGS_<CONFIG>` +cache entry the first time a build tree is configured. +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_MODULE_LINKER_FLAGS_INIT`. diff --git a/Help/variable/CMAKE_MODULE_LINKER_FLAGS_INIT.rst b/Help/variable/CMAKE_MODULE_LINKER_FLAGS_INIT.rst new file mode 100644 index 0000000..d59e9bf --- /dev/null +++ b/Help/variable/CMAKE_MODULE_LINKER_FLAGS_INIT.rst @@ -0,0 +1,13 @@ +CMAKE_MODULE_LINKER_FLAGS_INIT +------------------------------ + +.. versionadded:: 3.7 + +Value used to initialize the :variable:`CMAKE_MODULE_LINKER_FLAGS` +cache entry the first time a build tree is configured. +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 variable +:variable:`CMAKE_MODULE_LINKER_FLAGS_<CONFIG>_INIT`. diff --git a/Help/variable/CMAKE_MODULE_PATH.rst b/Help/variable/CMAKE_MODULE_PATH.rst new file mode 100644 index 0000000..4dcf6b5 --- /dev/null +++ b/Help/variable/CMAKE_MODULE_PATH.rst @@ -0,0 +1,7 @@ +CMAKE_MODULE_PATH +----------------- + +: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 0000000..721ceaa --- /dev/null +++ b/Help/variable/CMAKE_MSVCIDE_RUN_PATH.rst @@ -0,0 +1,12 @@ +CMAKE_MSVCIDE_RUN_PATH +---------------------- + +.. versionadded:: 3.10 + +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 0000000..14806e6 --- /dev/null +++ b/Help/variable/CMAKE_MSVC_RUNTIME_LIBRARY.rst @@ -0,0 +1,34 @@ +CMAKE_MSVC_RUNTIME_LIBRARY +-------------------------- + +.. versionadded:: 3.15 + +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 0000000..2c64a81 --- /dev/null +++ b/Help/variable/CMAKE_NETRC.rst @@ -0,0 +1,11 @@ +CMAKE_NETRC +----------- + +.. versionadded:: 3.11 + +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 0000000..97a645e --- /dev/null +++ b/Help/variable/CMAKE_NETRC_FILE.rst @@ -0,0 +1,11 @@ +CMAKE_NETRC_FILE +---------------- + +.. versionadded:: 3.11 + +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_NINJA_OUTPUT_PATH_PREFIX.rst b/Help/variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX.rst new file mode 100644 index 0000000..a8c4035 --- /dev/null +++ b/Help/variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX.rst @@ -0,0 +1,29 @@ +CMAKE_NINJA_OUTPUT_PATH_PREFIX +------------------------------ + +.. versionadded:: 3.6 + +Set output files path prefix for the :generator:`Ninja` generator. + +Every output files listed in the generated ``build.ninja`` will be +prefixed by the contents of this variable (a trailing slash is +appended if missing). This is useful when the generated ninja file is +meant to be embedded as a ``subninja`` file into a *super* ninja +project. For example, a ninja build file generated with a command +like:: + + cd top-build-dir/sub && + cmake -G Ninja -DCMAKE_NINJA_OUTPUT_PATH_PREFIX=sub/ path/to/source + +can be embedded in ``top-build-dir/build.ninja`` with a directive like +this:: + + subninja sub/build.ninja + +The ``auto-regeneration`` rule in ``top-build-dir/build.ninja`` must have an +order-only dependency on ``sub/build.ninja``. + +.. note:: + When ``CMAKE_NINJA_OUTPUT_PATH_PREFIX`` is set, the project generated + by CMake cannot be used as a standalone project. No default targets + are specified. diff --git a/Help/variable/CMAKE_NOT_USING_CONFIG_FLAGS.rst b/Help/variable/CMAKE_NOT_USING_CONFIG_FLAGS.rst new file mode 100644 index 0000000..98960c5 --- /dev/null +++ b/Help/variable/CMAKE_NOT_USING_CONFIG_FLAGS.rst @@ -0,0 +1,7 @@ +CMAKE_NOT_USING_CONFIG_FLAGS +---------------------------- + +Skip ``_BUILD_TYPE`` flags if true. + +This is an internal flag used by the generators in CMake to tell CMake +to skip the ``_BUILD_TYPE`` flags. diff --git a/Help/variable/CMAKE_NO_BUILTIN_CHRPATH.rst b/Help/variable/CMAKE_NO_BUILTIN_CHRPATH.rst new file mode 100644 index 0000000..b9b045e --- /dev/null +++ b/Help/variable/CMAKE_NO_BUILTIN_CHRPATH.rst @@ -0,0 +1,17 @@ +CMAKE_NO_BUILTIN_CHRPATH +------------------------ + +Do not use the builtin binary editor to fix runtime library search +paths on installation. + +When an ELF or XCOFF binary needs to have a different runtime library +search path after installation than it does in the build tree, CMake uses +a builtin editor to change the runtime search path in the installed copy. +If this variable is set to true then CMake will relink the binary before +installation instead of using its builtin editor. + +.. versionadded:: 3.20 + + This variable also applies to XCOFF binaries' LIBPATH. Prior to the + addition of the XCOFF editor in CMake 3.20, this variable applied only + to ELF binaries' RPATH/RUNPATH. diff --git a/Help/variable/CMAKE_NO_SYSTEM_FROM_IMPORTED.rst b/Help/variable/CMAKE_NO_SYSTEM_FROM_IMPORTED.rst new file mode 100644 index 0000000..61e04b4 --- /dev/null +++ b/Help/variable/CMAKE_NO_SYSTEM_FROM_IMPORTED.rst @@ -0,0 +1,8 @@ +CMAKE_NO_SYSTEM_FROM_IMPORTED +----------------------------- + +Default value for :prop_tgt:`NO_SYSTEM_FROM_IMPORTED` of targets. + +This variable is used to initialize the :prop_tgt:`NO_SYSTEM_FROM_IMPORTED` +property on all the targets. See that target property for additional +information. diff --git a/Help/variable/CMAKE_OBJCXX_EXTENSIONS.rst b/Help/variable/CMAKE_OBJCXX_EXTENSIONS.rst new file mode 100644 index 0000000..b5225ea --- /dev/null +++ b/Help/variable/CMAKE_OBJCXX_EXTENSIONS.rst @@ -0,0 +1,13 @@ +CMAKE_OBJCXX_EXTENSIONS +----------------------- + +.. versionadded:: 3.16 + +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 0000000..98e4624 --- /dev/null +++ b/Help/variable/CMAKE_OBJCXX_STANDARD.rst @@ -0,0 +1,13 @@ +CMAKE_OBJCXX_STANDARD +--------------------- + +.. versionadded:: 3.16 + +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 0000000..4b5e77c --- /dev/null +++ b/Help/variable/CMAKE_OBJCXX_STANDARD_REQUIRED.rst @@ -0,0 +1,13 @@ +CMAKE_OBJCXX_STANDARD_REQUIRED +------------------------------ + +.. versionadded:: 3.16 + +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 0000000..d6e3c7d --- /dev/null +++ b/Help/variable/CMAKE_OBJC_EXTENSIONS.rst @@ -0,0 +1,13 @@ +CMAKE_OBJC_EXTENSIONS +--------------------- + +.. versionadded:: 3.16 + +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 0000000..fde367d --- /dev/null +++ b/Help/variable/CMAKE_OBJC_STANDARD.rst @@ -0,0 +1,13 @@ +CMAKE_OBJC_STANDARD +------------------- + +.. versionadded:: 3.16 + +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 0000000..8d26d95 --- /dev/null +++ b/Help/variable/CMAKE_OBJC_STANDARD_REQUIRED.rst @@ -0,0 +1,13 @@ +CMAKE_OBJC_STANDARD_REQUIRED +---------------------------- + +.. versionadded:: 3.16 + +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_OBJECT_PATH_MAX.rst b/Help/variable/CMAKE_OBJECT_PATH_MAX.rst new file mode 100644 index 0000000..9e30cbb --- /dev/null +++ b/Help/variable/CMAKE_OBJECT_PATH_MAX.rst @@ -0,0 +1,16 @@ +CMAKE_OBJECT_PATH_MAX +--------------------- + +Maximum object file full-path length allowed by native build tools. + +CMake computes for every source file an object file name that is +unique to the source file and deterministic with respect to the full +path to the source file. This allows multiple source files in a +target to share the same name if they lie in different directories +without rebuilding when one is added or removed. However, it can +produce long full paths in a few cases, so CMake shortens the path +using a hashing scheme when the full path to an object file exceeds a +limit. CMake has a built-in limit for each platform that is +sufficient for common tools, but some native tools may have a lower +limit. This variable may be set to specify the limit explicitly. The +value must be an integer no less than 128. diff --git a/Help/variable/CMAKE_OPTIMIZE_DEPENDENCIES.rst b/Help/variable/CMAKE_OPTIMIZE_DEPENDENCIES.rst new file mode 100644 index 0000000..0ffb902 --- /dev/null +++ b/Help/variable/CMAKE_OPTIMIZE_DEPENDENCIES.rst @@ -0,0 +1,6 @@ +CMAKE_OPTIMIZE_DEPENDENCIES +--------------------------- + +.. versionadded:: 3.19 + +Initializes the :prop_tgt:`OPTIMIZE_DEPENDENCIES` target property. diff --git a/Help/variable/CMAKE_OSX_ARCHITECTURES.rst b/Help/variable/CMAKE_OSX_ARCHITECTURES.rst new file mode 100644 index 0000000..fdaca28 --- /dev/null +++ b/Help/variable/CMAKE_OSX_ARCHITECTURES.rst @@ -0,0 +1,10 @@ +CMAKE_OSX_ARCHITECTURES +----------------------- + +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 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 new file mode 100644 index 0000000..9df5edd --- /dev/null +++ b/Help/variable/CMAKE_OSX_DEPLOYMENT_TARGET.rst @@ -0,0 +1,15 @@ +CMAKE_OSX_DEPLOYMENT_TARGET +--------------------------- + +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, +and otherwise computed based on the host platform. + +.. include:: CMAKE_OSX_VARIABLE.txt diff --git a/Help/variable/CMAKE_OSX_SYSROOT.rst b/Help/variable/CMAKE_OSX_SYSROOT.rst new file mode 100644 index 0000000..db9fccd --- /dev/null +++ b/Help/variable/CMAKE_OSX_SYSROOT.rst @@ -0,0 +1,13 @@ +CMAKE_OSX_SYSROOT +----------------- + +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. + +If not set explicitly the value is initialized by the ``SDKROOT`` +environment variable, if set, and otherwise computed based on the +:variable:`CMAKE_OSX_DEPLOYMENT_TARGET` or the host platform. + +.. include:: CMAKE_OSX_VARIABLE.txt diff --git a/Help/variable/CMAKE_OSX_VARIABLE.txt b/Help/variable/CMAKE_OSX_VARIABLE.txt new file mode 100644 index 0000000..16f3c1a --- /dev/null +++ b/Help/variable/CMAKE_OSX_VARIABLE.txt @@ -0,0 +1,11 @@ +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). + +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_PARENT_LIST_FILE.rst b/Help/variable/CMAKE_PARENT_LIST_FILE.rst new file mode 100644 index 0000000..cfd8608 --- /dev/null +++ b/Help/variable/CMAKE_PARENT_LIST_FILE.rst @@ -0,0 +1,9 @@ +CMAKE_PARENT_LIST_FILE +---------------------- + +Full path to the CMake file that included the current one. + +While processing a CMake file loaded by :command:`include` or +:command:`find_package` this variable contains the full path to the file +including it. The top of the include stack is always the ``CMakeLists.txt`` +for the current directory. See also :variable:`CMAKE_CURRENT_LIST_FILE`. diff --git a/Help/variable/CMAKE_PATCH_VERSION.rst b/Help/variable/CMAKE_PATCH_VERSION.rst new file mode 100644 index 0000000..991ae76 --- /dev/null +++ b/Help/variable/CMAKE_PATCH_VERSION.rst @@ -0,0 +1,5 @@ +CMAKE_PATCH_VERSION +------------------- + +Third version number component of the :variable:`CMAKE_VERSION` +variable. diff --git a/Help/variable/CMAKE_PCH_INSTANTIATE_TEMPLATES.rst b/Help/variable/CMAKE_PCH_INSTANTIATE_TEMPLATES.rst new file mode 100644 index 0000000..9867f17 --- /dev/null +++ b/Help/variable/CMAKE_PCH_INSTANTIATE_TEMPLATES.rst @@ -0,0 +1,7 @@ +CMAKE_PCH_INSTANTIATE_TEMPLATES +------------------------------- + +.. versionadded:: 3.19 + +This variable is used to initialize the :prop_tgt:`PCH_INSTANTIATE_TEMPLATES` +property of targets when they are created. diff --git a/Help/variable/CMAKE_PCH_WARN_INVALID.rst b/Help/variable/CMAKE_PCH_WARN_INVALID.rst new file mode 100644 index 0000000..457a428 --- /dev/null +++ b/Help/variable/CMAKE_PCH_WARN_INVALID.rst @@ -0,0 +1,7 @@ +CMAKE_PCH_WARN_INVALID +---------------------- + +.. versionadded:: 3.18 + +This variable is used to initialize the :prop_tgt:`PCH_WARN_INVALID` +property of targets when they are created. diff --git a/Help/variable/CMAKE_PDB_OUTPUT_DIRECTORY.rst b/Help/variable/CMAKE_PDB_OUTPUT_DIRECTORY.rst new file mode 100644 index 0000000..763bcb3 --- /dev/null +++ b/Help/variable/CMAKE_PDB_OUTPUT_DIRECTORY.rst @@ -0,0 +1,9 @@ +CMAKE_PDB_OUTPUT_DIRECTORY +-------------------------- + +Output directory for MS debug symbol ``.pdb`` files generated by the +linker for executable and shared library targets. + +This variable is used to initialize the :prop_tgt:`PDB_OUTPUT_DIRECTORY` +property on all the targets. See that target property for additional +information. diff --git a/Help/variable/CMAKE_PDB_OUTPUT_DIRECTORY_CONFIG.rst b/Help/variable/CMAKE_PDB_OUTPUT_DIRECTORY_CONFIG.rst new file mode 100644 index 0000000..4d18eec --- /dev/null +++ b/Help/variable/CMAKE_PDB_OUTPUT_DIRECTORY_CONFIG.rst @@ -0,0 +1,11 @@ +CMAKE_PDB_OUTPUT_DIRECTORY_<CONFIG> +----------------------------------- + +Per-configuration output directory for MS debug symbol ``.pdb`` files +generated by the linker for executable and shared library targets. + +This is a per-configuration version of :variable:`CMAKE_PDB_OUTPUT_DIRECTORY`. +This variable is used to initialize the +:prop_tgt:`PDB_OUTPUT_DIRECTORY_<CONFIG>` +property on all the targets. See that target property for additional +information. diff --git a/Help/variable/CMAKE_POLICY_DEFAULT_CMPNNNN.rst b/Help/variable/CMAKE_POLICY_DEFAULT_CMPNNNN.rst new file mode 100644 index 0000000..43582be --- /dev/null +++ b/Help/variable/CMAKE_POLICY_DEFAULT_CMPNNNN.rst @@ -0,0 +1,17 @@ +CMAKE_POLICY_DEFAULT_CMP<NNNN> +------------------------------ + +Default for CMake Policy ``CMP<NNNN>`` when it is otherwise left unset. + +Commands :command:`cmake_minimum_required(VERSION)` and +:command:`cmake_policy(VERSION)` by default leave policies introduced after +the given version unset. Set ``CMAKE_POLICY_DEFAULT_CMP<NNNN>`` to ``OLD`` +or ``NEW`` to specify the default for policy ``CMP<NNNN>``, where ``<NNNN>`` +is the policy number. + +This variable should not be set by a project in CMake code; use +:command:`cmake_policy(SET)` instead. Users running CMake may set this +variable in the cache (e.g. ``-DCMAKE_POLICY_DEFAULT_CMP<NNNN>=<OLD|NEW>``) +to set a policy not otherwise set by the project. Set to ``OLD`` to quiet a +policy warning while using old behavior or to ``NEW`` to try building the +project with new behavior. diff --git a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst new file mode 100644 index 0000000..9f68741 --- /dev/null +++ b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst @@ -0,0 +1,37 @@ +CMAKE_POLICY_WARNING_CMP<NNNN> +------------------------------ + +Explicitly enable or disable the warning when CMake Policy ``CMP<NNNN>`` +is not set. This is meaningful only for the few policies that do not +warn by default: + +* ``CMAKE_POLICY_WARNING_CMP0025`` controls the warning for + policy :policy:`CMP0025`. +* ``CMAKE_POLICY_WARNING_CMP0047`` controls the warning for + policy :policy:`CMP0047`. +* ``CMAKE_POLICY_WARNING_CMP0056`` controls the warning for + policy :policy:`CMP0056`. +* ``CMAKE_POLICY_WARNING_CMP0060`` controls the warning for + policy :policy:`CMP0060`. +* ``CMAKE_POLICY_WARNING_CMP0065`` controls the warning for + policy :policy:`CMP0065`. +* ``CMAKE_POLICY_WARNING_CMP0066`` controls the warning for + 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`. +* ``CMAKE_POLICY_WARNING_CMP0102`` controls the warning for + policy :policy:`CMP0102`. +* ``CMAKE_POLICY_WARNING_CMP0112`` controls the warning for + policy :policy:`CMP0112`. +* ``CMAKE_POLICY_WARNING_CMP0116`` controls the warning for + policy :policy:`CMP0116`. + +This variable should not be set by a project in CMake code. Project +developers running CMake may set this variable in their cache to +enable the warning (e.g. ``-DCMAKE_POLICY_WARNING_CMP<NNNN>=ON``). +Alternatively, running :manual:`cmake(1)` with the ``--debug-output``, +``--trace``, or ``--trace-expand`` option will also enable the warning. diff --git a/Help/variable/CMAKE_POSITION_INDEPENDENT_CODE.rst b/Help/variable/CMAKE_POSITION_INDEPENDENT_CODE.rst new file mode 100644 index 0000000..b010317 --- /dev/null +++ b/Help/variable/CMAKE_POSITION_INDEPENDENT_CODE.rst @@ -0,0 +1,9 @@ +CMAKE_POSITION_INDEPENDENT_CODE +------------------------------- + +Default value for :prop_tgt:`POSITION_INDEPENDENT_CODE` of targets. + +This variable is used to initialize the +:prop_tgt:`POSITION_INDEPENDENT_CODE` property on all the targets. +See that target property for additional information. If set, its +value is also used by the :command:`try_compile` command. diff --git a/Help/variable/CMAKE_PREFIX_PATH.rst b/Help/variable/CMAKE_PREFIX_PATH.rst new file mode 100644 index 0000000..1d4fd0b --- /dev/null +++ b/Help/variable/CMAKE_PREFIX_PATH.rst @@ -0,0 +1,15 @@ +CMAKE_PREFIX_PATH +----------------- + +: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 +subdirectories (like ``bin``, ``lib``, or ``include``) as specified in its own +documentation. + +By default this is empty. It is intended to be set by the project. + +See also :variable:`CMAKE_SYSTEM_PREFIX_PATH`, :variable:`CMAKE_INCLUDE_PATH`, +:variable:`CMAKE_LIBRARY_PATH`, :variable:`CMAKE_PROGRAM_PATH`, and +:variable:`CMAKE_IGNORE_PATH`. diff --git a/Help/variable/CMAKE_PROGRAM_PATH.rst b/Help/variable/CMAKE_PROGRAM_PATH.rst new file mode 100644 index 0000000..2d0c090 --- /dev/null +++ b/Help/variable/CMAKE_PROGRAM_PATH.rst @@ -0,0 +1,7 @@ +CMAKE_PROGRAM_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 new file mode 100644 index 0000000..95cbe40 --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_DESCRIPTION.rst @@ -0,0 +1,37 @@ +CMAKE_PROJECT_DESCRIPTION +------------------------- + +.. versionadded:: 3.9 + +The description of the top level project. + +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 0000000..4c5debe --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_HOMEPAGE_URL.rst @@ -0,0 +1,37 @@ +CMAKE_PROJECT_HOMEPAGE_URL +-------------------------- + +.. versionadded:: 3.12 + +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 0000000..41d9e5d --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_INCLUDE.rst @@ -0,0 +1,12 @@ +CMAKE_PROJECT_INCLUDE +--------------------- + +.. versionadded:: 3.15 + +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`, +:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE` 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 0000000..c2fd0f8 --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst @@ -0,0 +1,12 @@ +CMAKE_PROJECT_INCLUDE_BEFORE +---------------------------- + +.. versionadded:: 3.15 + +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`, +:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE` and +:variable:`CMAKE_PROJECT_INCLUDE` variables. diff --git a/Help/variable/CMAKE_PROJECT_NAME.rst b/Help/variable/CMAKE_PROJECT_NAME.rst new file mode 100644 index 0000000..94b8dba --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_NAME.rst @@ -0,0 +1,35 @@ +CMAKE_PROJECT_NAME +------------------ + +The name of the top level project. + +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 new file mode 100644 index 0000000..74247f1 --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst @@ -0,0 +1,11 @@ +CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE +------------------------------------ + +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_<PROJECT-NAME>_INCLUDE_BEFORE`, +:variable:`CMAKE_PROJECT_INCLUDE` and +:variable:`CMAKE_PROJECT_INCLUDE_BEFORE` variables. diff --git a/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE.rst b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE.rst new file mode 100644 index 0000000..39abb12 --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE.rst @@ -0,0 +1,13 @@ +CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE +------------------------------------------- + +.. versionadded:: 3.17 + +A CMake language file or module to be included as the first 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_<PROJECT-NAME>_INCLUDE`, +: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 0000000..450c136 --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_VERSION.rst @@ -0,0 +1,37 @@ +CMAKE_PROJECT_VERSION +--------------------- + +.. versionadded:: 3.12 + +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 0000000..c7511e7 --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_VERSION_MAJOR.rst @@ -0,0 +1,11 @@ +CMAKE_PROJECT_VERSION_MAJOR +--------------------------- + +.. versionadded:: 3.12 + +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 0000000..dd91dcf --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_VERSION_MINOR.rst @@ -0,0 +1,11 @@ +CMAKE_PROJECT_VERSION_MINOR +--------------------------- + +.. versionadded:: 3.12 + +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 0000000..61fd1f3 --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_VERSION_PATCH.rst @@ -0,0 +1,11 @@ +CMAKE_PROJECT_VERSION_PATCH +--------------------------- + +.. versionadded:: 3.12 + +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 0000000..0deae8b --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_VERSION_TWEAK.rst @@ -0,0 +1,11 @@ +CMAKE_PROJECT_VERSION_TWEAK +--------------------------- + +.. versionadded:: 3.12 + +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_RANLIB.rst b/Help/variable/CMAKE_RANLIB.rst new file mode 100644 index 0000000..82672e9 --- /dev/null +++ b/Help/variable/CMAKE_RANLIB.rst @@ -0,0 +1,7 @@ +CMAKE_RANLIB +------------ + +Name of randomizing tool for static libraries. + +This specifies name of the program that randomizes libraries on UNIX, +not used on Windows, but may be present. diff --git a/Help/variable/CMAKE_ROOT.rst b/Help/variable/CMAKE_ROOT.rst new file mode 100644 index 0000000..1d0a8af --- /dev/null +++ b/Help/variable/CMAKE_ROOT.rst @@ -0,0 +1,8 @@ +CMAKE_ROOT +---------- + +Install directory for running cmake. + +This is the install root for the running CMake and the ``Modules`` +directory can be found here. This is commonly used in this format: +``${CMAKE_ROOT}/Modules`` diff --git a/Help/variable/CMAKE_RULE_MESSAGES.rst b/Help/variable/CMAKE_RULE_MESSAGES.rst new file mode 100644 index 0000000..39be2e9 --- /dev/null +++ b/Help/variable/CMAKE_RULE_MESSAGES.rst @@ -0,0 +1,10 @@ +CMAKE_RULE_MESSAGES +------------------- + +.. versionadded:: 3.13 + +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_RUNTIME_OUTPUT_DIRECTORY.rst b/Help/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY.rst new file mode 100644 index 0000000..6253d4a --- /dev/null +++ b/Help/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY.rst @@ -0,0 +1,9 @@ +CMAKE_RUNTIME_OUTPUT_DIRECTORY +------------------------------ + +Where to put all the :ref:`RUNTIME <Runtime Output Artifacts>` +target files when built. + +This variable is used to initialize the :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` +property on all the targets. See that target property for additional +information. diff --git a/Help/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY_CONFIG.rst b/Help/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY_CONFIG.rst new file mode 100644 index 0000000..c9c55c5 --- /dev/null +++ b/Help/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY_CONFIG.rst @@ -0,0 +1,11 @@ +CMAKE_RUNTIME_OUTPUT_DIRECTORY_<CONFIG> +--------------------------------------- + +.. versionadded:: 3.3 + +Where to put all the :ref:`RUNTIME <Runtime Output Artifacts>` +target files when built for a specific configuration. + +This variable is used to initialize the +:prop_tgt:`RUNTIME_OUTPUT_DIRECTORY_<CONFIG>` property on all the targets. +See that target property for additional information. diff --git a/Help/variable/CMAKE_SCRIPT_MODE_FILE.rst b/Help/variable/CMAKE_SCRIPT_MODE_FILE.rst new file mode 100644 index 0000000..981af60 --- /dev/null +++ b/Help/variable/CMAKE_SCRIPT_MODE_FILE.rst @@ -0,0 +1,9 @@ +CMAKE_SCRIPT_MODE_FILE +---------------------- + +Full path to the :manual:`cmake(1)` ``-P`` script file currently being +processed. + +When run in :manual:`cmake(1)` ``-P`` script mode, CMake sets this variable to +the full path of the script file. When run to configure a ``CMakeLists.txt`` +file, this variable is not set. diff --git a/Help/variable/CMAKE_SHARED_LIBRARY_PREFIX.rst b/Help/variable/CMAKE_SHARED_LIBRARY_PREFIX.rst new file mode 100644 index 0000000..8afabaf --- /dev/null +++ b/Help/variable/CMAKE_SHARED_LIBRARY_PREFIX.rst @@ -0,0 +1,8 @@ +CMAKE_SHARED_LIBRARY_PREFIX +--------------------------- + +The prefix for shared libraries that you link to. + +The prefix to use for the name of a shared library, ``lib`` on UNIX. + +``CMAKE_SHARED_LIBRARY_PREFIX_<LANG>`` overrides this for language ``<LANG>``. diff --git a/Help/variable/CMAKE_SHARED_LIBRARY_SUFFIX.rst b/Help/variable/CMAKE_SHARED_LIBRARY_SUFFIX.rst new file mode 100644 index 0000000..1f96a32 --- /dev/null +++ b/Help/variable/CMAKE_SHARED_LIBRARY_SUFFIX.rst @@ -0,0 +1,9 @@ +CMAKE_SHARED_LIBRARY_SUFFIX +--------------------------- + +The suffix for shared libraries that you link to. + +The suffix to use for the end of a shared library filename, ``.dll`` on +Windows. + +``CMAKE_SHARED_LIBRARY_SUFFIX_<LANG>`` overrides this for language ``<LANG>``. diff --git a/Help/variable/CMAKE_SHARED_LINKER_FLAGS.rst b/Help/variable/CMAKE_SHARED_LINKER_FLAGS.rst new file mode 100644 index 0000000..fce950c --- /dev/null +++ b/Help/variable/CMAKE_SHARED_LINKER_FLAGS.rst @@ -0,0 +1,6 @@ +CMAKE_SHARED_LINKER_FLAGS +------------------------- + +Linker flags to be used to create shared libraries. + +These flags will be used by the linker when creating a shared library. diff --git a/Help/variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG.rst b/Help/variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG.rst new file mode 100644 index 0000000..4bf87a0 --- /dev/null +++ b/Help/variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG.rst @@ -0,0 +1,7 @@ +CMAKE_SHARED_LINKER_FLAGS_<CONFIG> +---------------------------------- + +Flags to be used when linking a shared library. + +Same as ``CMAKE_C_FLAGS_*`` but used by the linker when creating shared +libraries. diff --git a/Help/variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG_INIT.rst b/Help/variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG_INIT.rst new file mode 100644 index 0000000..7f3dec7 --- /dev/null +++ b/Help/variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG_INIT.rst @@ -0,0 +1,12 @@ +CMAKE_SHARED_LINKER_FLAGS_<CONFIG>_INIT +--------------------------------------- + +.. versionadded:: 3.7 + +Value used to initialize the :variable:`CMAKE_SHARED_LINKER_FLAGS_<CONFIG>` +cache entry the first time a build tree is configured. +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_SHARED_LINKER_FLAGS_INIT`. diff --git a/Help/variable/CMAKE_SHARED_LINKER_FLAGS_INIT.rst b/Help/variable/CMAKE_SHARED_LINKER_FLAGS_INIT.rst new file mode 100644 index 0000000..6d51afe --- /dev/null +++ b/Help/variable/CMAKE_SHARED_LINKER_FLAGS_INIT.rst @@ -0,0 +1,13 @@ +CMAKE_SHARED_LINKER_FLAGS_INIT +------------------------------ + +.. versionadded:: 3.7 + +Value used to initialize the :variable:`CMAKE_SHARED_LINKER_FLAGS` +cache entry the first time a build tree is configured. +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 variable +:variable:`CMAKE_SHARED_LINKER_FLAGS_<CONFIG>_INIT`. diff --git a/Help/variable/CMAKE_SHARED_MODULE_PREFIX.rst b/Help/variable/CMAKE_SHARED_MODULE_PREFIX.rst new file mode 100644 index 0000000..d6eef98 --- /dev/null +++ b/Help/variable/CMAKE_SHARED_MODULE_PREFIX.rst @@ -0,0 +1,8 @@ +CMAKE_SHARED_MODULE_PREFIX +-------------------------- + +The prefix for loadable modules that you link to. + +The prefix to use for the name of a loadable module on this platform. + +``CMAKE_SHARED_MODULE_PREFIX_<LANG>`` overrides this for language ``<LANG>``. diff --git a/Help/variable/CMAKE_SHARED_MODULE_SUFFIX.rst b/Help/variable/CMAKE_SHARED_MODULE_SUFFIX.rst new file mode 100644 index 0000000..81515c3 --- /dev/null +++ b/Help/variable/CMAKE_SHARED_MODULE_SUFFIX.rst @@ -0,0 +1,9 @@ +CMAKE_SHARED_MODULE_SUFFIX +-------------------------- + +The suffix for shared libraries that you link to. + +The suffix to use for the end of a loadable module filename on this +platform + +``CMAKE_SHARED_MODULE_SUFFIX_<LANG>`` overrides this for language ``<LANG>``. diff --git a/Help/variable/CMAKE_SIZEOF_VOID_P.rst b/Help/variable/CMAKE_SIZEOF_VOID_P.rst new file mode 100644 index 0000000..f5464d1 --- /dev/null +++ b/Help/variable/CMAKE_SIZEOF_VOID_P.rst @@ -0,0 +1,8 @@ +CMAKE_SIZEOF_VOID_P +------------------- + +Size of a ``void`` pointer. + +This is set to the size of a pointer on the target machine, and is determined +by a try compile. If a 64-bit size is found, then the library search +path is modified to look for 64-bit libraries first. diff --git a/Help/variable/CMAKE_SKIP_BUILD_RPATH.rst b/Help/variable/CMAKE_SKIP_BUILD_RPATH.rst new file mode 100644 index 0000000..8da6100 --- /dev/null +++ b/Help/variable/CMAKE_SKIP_BUILD_RPATH.rst @@ -0,0 +1,10 @@ +CMAKE_SKIP_BUILD_RPATH +---------------------- + +Do not include RPATHs in the build tree. + +Normally CMake uses the build tree for the RPATH when building +executables etc on systems that use RPATH. When the software is +installed the executables etc are relinked by CMake to have the +install RPATH. If this variable is set to true then the software is +always built with no RPATH. diff --git a/Help/variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY.rst b/Help/variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY.rst new file mode 100644 index 0000000..80a68c9 --- /dev/null +++ b/Help/variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY.rst @@ -0,0 +1,11 @@ +CMAKE_SKIP_INSTALL_ALL_DEPENDENCY +--------------------------------- + +Don't make the ``install`` target depend on the ``all`` target. + +By default, the ``install`` target depends on the ``all`` target. This +has the effect, that when ``make install`` is invoked or ``INSTALL`` is +built, first the ``all`` target is built, then the installation starts. +If :variable:`CMAKE_SKIP_INSTALL_ALL_DEPENDENCY` is set to ``TRUE``, this +dependency is not created, so the installation process will start immediately, +independent from whether the project has been completely built or not. diff --git a/Help/variable/CMAKE_SKIP_INSTALL_RPATH.rst b/Help/variable/CMAKE_SKIP_INSTALL_RPATH.rst new file mode 100644 index 0000000..cc0ac21 --- /dev/null +++ b/Help/variable/CMAKE_SKIP_INSTALL_RPATH.rst @@ -0,0 +1,14 @@ +CMAKE_SKIP_INSTALL_RPATH +------------------------ + +Do not include RPATHs in the install tree. + +Normally CMake uses the build tree for the RPATH when building +executables etc on systems that use RPATH. When the software is +installed the executables etc are relinked by CMake to have the +install RPATH. If this variable is set to true then the software is +always installed without RPATH, even if RPATH is enabled when +building. This can be useful for example to allow running tests from +the build directory with RPATH enabled before the installation step. +To omit RPATH in both the build and install steps, use +:variable:`CMAKE_SKIP_RPATH` instead. diff --git a/Help/variable/CMAKE_SKIP_INSTALL_RULES.rst b/Help/variable/CMAKE_SKIP_INSTALL_RULES.rst new file mode 100644 index 0000000..b77bb68 --- /dev/null +++ b/Help/variable/CMAKE_SKIP_INSTALL_RULES.rst @@ -0,0 +1,8 @@ +CMAKE_SKIP_INSTALL_RULES +------------------------ + +Whether to disable generation of installation rules. + +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_SKIP_RPATH.rst b/Help/variable/CMAKE_SKIP_RPATH.rst new file mode 100644 index 0000000..d7ce8e4 --- /dev/null +++ b/Help/variable/CMAKE_SKIP_RPATH.rst @@ -0,0 +1,10 @@ +CMAKE_SKIP_RPATH +---------------- + +If true, do not add run time path information. + +If this is set to ``TRUE``, then the rpath information is not added to +compiled executables. The default is to add rpath information if the +platform supports it. This allows for easy running from the build +tree. To omit RPATH in the install step, but not the build step, use +:variable:`CMAKE_SKIP_INSTALL_RPATH` instead. diff --git a/Help/variable/CMAKE_SOURCE_DIR.rst b/Help/variable/CMAKE_SOURCE_DIR.rst new file mode 100644 index 0000000..d1f1798 --- /dev/null +++ b/Help/variable/CMAKE_SOURCE_DIR.rst @@ -0,0 +1,13 @@ +CMAKE_SOURCE_DIR +---------------- + +The path to the top level of the source tree. + +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 +: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 new file mode 100644 index 0000000..bdb97fa --- /dev/null +++ b/Help/variable/CMAKE_STAGING_PREFIX.rst @@ -0,0 +1,14 @@ +CMAKE_STAGING_PREFIX +-------------------- + +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 :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 +:variable:`CMAKE_STAGING_PREFIX`, the matching path fragments are replaced +with the :variable:`CMAKE_INSTALL_PREFIX`. diff --git a/Help/variable/CMAKE_STATIC_LIBRARY_PREFIX.rst b/Help/variable/CMAKE_STATIC_LIBRARY_PREFIX.rst new file mode 100644 index 0000000..714b5cc --- /dev/null +++ b/Help/variable/CMAKE_STATIC_LIBRARY_PREFIX.rst @@ -0,0 +1,8 @@ +CMAKE_STATIC_LIBRARY_PREFIX +--------------------------- + +The prefix for static libraries that you link to. + +The prefix to use for the name of a static library, ``lib`` on UNIX. + +``CMAKE_STATIC_LIBRARY_PREFIX_<LANG>`` overrides this for language ``<LANG>``. diff --git a/Help/variable/CMAKE_STATIC_LIBRARY_SUFFIX.rst b/Help/variable/CMAKE_STATIC_LIBRARY_SUFFIX.rst new file mode 100644 index 0000000..28dc09d --- /dev/null +++ b/Help/variable/CMAKE_STATIC_LIBRARY_SUFFIX.rst @@ -0,0 +1,9 @@ +CMAKE_STATIC_LIBRARY_SUFFIX +--------------------------- + +The suffix for static libraries that you link to. + +The suffix to use for the end of a static library filename, ``.lib`` on +Windows. + +``CMAKE_STATIC_LIBRARY_SUFFIX_<LANG>`` overrides this for language ``<LANG>``. diff --git a/Help/variable/CMAKE_STATIC_LINKER_FLAGS.rst b/Help/variable/CMAKE_STATIC_LINKER_FLAGS.rst new file mode 100644 index 0000000..1a810ce --- /dev/null +++ b/Help/variable/CMAKE_STATIC_LINKER_FLAGS.rst @@ -0,0 +1,12 @@ +CMAKE_STATIC_LINKER_FLAGS +------------------------- + +Flags to be used to create static libraries. These flags will be passed +to the archiver 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 new file mode 100644 index 0000000..e561dc6 --- /dev/null +++ b/Help/variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG.rst @@ -0,0 +1,13 @@ +CMAKE_STATIC_LINKER_FLAGS_<CONFIG> +---------------------------------- + +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. + +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_STATIC_LINKER_FLAGS_CONFIG_INIT.rst b/Help/variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG_INIT.rst new file mode 100644 index 0000000..5e65ef2 --- /dev/null +++ b/Help/variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG_INIT.rst @@ -0,0 +1,12 @@ +CMAKE_STATIC_LINKER_FLAGS_<CONFIG>_INIT +--------------------------------------- + +.. versionadded:: 3.7 + +Value used to initialize the :variable:`CMAKE_STATIC_LINKER_FLAGS_<CONFIG>` +cache entry the first time a build tree is configured. +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_STATIC_LINKER_FLAGS_INIT`. diff --git a/Help/variable/CMAKE_STATIC_LINKER_FLAGS_INIT.rst b/Help/variable/CMAKE_STATIC_LINKER_FLAGS_INIT.rst new file mode 100644 index 0000000..cbf681c --- /dev/null +++ b/Help/variable/CMAKE_STATIC_LINKER_FLAGS_INIT.rst @@ -0,0 +1,13 @@ +CMAKE_STATIC_LINKER_FLAGS_INIT +------------------------------ + +.. versionadded:: 3.7 + +Value used to initialize the :variable:`CMAKE_STATIC_LINKER_FLAGS` +cache entry the first time a build tree is configured. +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 variable +:variable:`CMAKE_STATIC_LINKER_FLAGS_<CONFIG>_INIT`. diff --git a/Help/variable/CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS.rst b/Help/variable/CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS.rst new file mode 100644 index 0000000..5c1c8d1 --- /dev/null +++ b/Help/variable/CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS.rst @@ -0,0 +1,27 @@ +CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS +--------------------------------- + +.. versionadded:: 3.8 + +This variable contains a list of env vars as a list of tokens with the +syntax ``var=value``. + +Example: + +.. code-block:: cmake + + set(CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS + "FOO=FOO1\;FOO2\;FOON" + "BAR=BAR1\;BAR2\;BARN" + "BAZ=BAZ1\;BAZ2\;BAZN" + "FOOBAR=FOOBAR1\;FOOBAR2\;FOOBARN" + "VALID=" + ) + +In case of malformed variables CMake will fail: + +.. code-block:: cmake + + set(CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS + "THIS_IS_NOT_VALID" + ) diff --git a/Help/variable/CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE.rst b/Help/variable/CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE.rst new file mode 100644 index 0000000..28b0dbd --- /dev/null +++ b/Help/variable/CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE.rst @@ -0,0 +1,9 @@ +CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE +--------------------------------------- + +.. versionadded:: 3.8 + +If this variable evaluates to ``ON`` at the end of the top-level +``CMakeLists.txt`` file, the :generator:`Sublime Text 2` extra generator +excludes the build tree from the ``.sublime-project`` if it is inside the +source tree. diff --git a/Help/variable/CMAKE_SUPPRESS_REGENERATION.rst b/Help/variable/CMAKE_SUPPRESS_REGENERATION.rst new file mode 100644 index 0000000..48490ff --- /dev/null +++ b/Help/variable/CMAKE_SUPPRESS_REGENERATION.rst @@ -0,0 +1,13 @@ +CMAKE_SUPPRESS_REGENERATION +--------------------------- + +.. versionadded:: 3.12 + +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 new file mode 100644 index 0000000..35b944f --- /dev/null +++ b/Help/variable/CMAKE_SYSROOT.rst @@ -0,0 +1,15 @@ +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 +paths searched by the ``find_*`` commands. + +This variable may only be set in a toolchain file specified by +the :variable:`CMAKE_TOOLCHAIN_FILE` variable. + +See also the :variable:`CMAKE_SYSROOT_COMPILE` and +:variable:`CMAKE_SYSROOT_LINK` variables. diff --git a/Help/variable/CMAKE_SYSROOT_COMPILE.rst b/Help/variable/CMAKE_SYSROOT_COMPILE.rst new file mode 100644 index 0000000..4aea48e --- /dev/null +++ b/Help/variable/CMAKE_SYSROOT_COMPILE.rst @@ -0,0 +1,11 @@ +CMAKE_SYSROOT_COMPILE +--------------------- + +.. versionadded:: 3.9 + +Path to pass to the compiler in the ``--sysroot`` flag when compiling source +files. This is the same as :variable:`CMAKE_SYSROOT` but is used only for +compiling sources and not linking. + +This variable may only be set in a toolchain file specified by +the :variable:`CMAKE_TOOLCHAIN_FILE` variable. diff --git a/Help/variable/CMAKE_SYSROOT_LINK.rst b/Help/variable/CMAKE_SYSROOT_LINK.rst new file mode 100644 index 0000000..9749b7b --- /dev/null +++ b/Help/variable/CMAKE_SYSROOT_LINK.rst @@ -0,0 +1,11 @@ +CMAKE_SYSROOT_LINK +------------------ + +.. versionadded:: 3.9 + +Path to pass to the compiler in the ``--sysroot`` flag when linking. This is +the same as :variable:`CMAKE_SYSROOT` but is used only for linking and not +compiling sources. + +This variable may only be set in a toolchain file specified by +the :variable:`CMAKE_TOOLCHAIN_FILE` variable. diff --git a/Help/variable/CMAKE_SYSTEM.rst b/Help/variable/CMAKE_SYSTEM.rst new file mode 100644 index 0000000..c7d0d8a --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM.rst @@ -0,0 +1,10 @@ +CMAKE_SYSTEM +------------ + +Composite name of operating system CMake is compiling for. + +This variable is the composite of :variable:`CMAKE_SYSTEM_NAME` and +:variable:`CMAKE_SYSTEM_VERSION`, e.g. +``${CMAKE_SYSTEM_NAME}-${CMAKE_SYSTEM_VERSION}``. If +:variable:`CMAKE_SYSTEM_VERSION` is not set, then this variable is +the same as :variable:`CMAKE_SYSTEM_NAME`. diff --git a/Help/variable/CMAKE_SYSTEM_APPBUNDLE_PATH.rst b/Help/variable/CMAKE_SYSTEM_APPBUNDLE_PATH.rst new file mode 100644 index 0000000..06a99a8 --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_APPBUNDLE_PATH.rst @@ -0,0 +1,9 @@ +CMAKE_SYSTEM_APPBUNDLE_PATH +--------------------------- + +.. versionadded:: 3.4 + +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 new file mode 100644 index 0000000..1a402c1 --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_FRAMEWORK_PATH.rst @@ -0,0 +1,10 @@ +CMAKE_SYSTEM_FRAMEWORK_PATH +--------------------------- + +.. versionadded:: 3.4 + +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, +use :variable:`CMAKE_FRAMEWORK_PATH` for this. diff --git a/Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst b/Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst new file mode 100644 index 0000000..6afbd33 --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst @@ -0,0 +1,18 @@ +CMAKE_SYSTEM_IGNORE_PATH +------------------------ + +: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 +possibly linkable libraries. For example, on cross-compiled cluster +environments, this allows a user to ignore directories containing +libraries meant for the front-end machine. + +By default this contains a list of directories containing incompatible +binaries for the host system. See the :variable:`CMAKE_IGNORE_PATH` variable +that is intended to be set by the project. + +See also the :variable:`CMAKE_SYSTEM_PREFIX_PATH`, +:variable:`CMAKE_SYSTEM_LIBRARY_PATH`, :variable:`CMAKE_SYSTEM_INCLUDE_PATH`, +and :variable:`CMAKE_SYSTEM_PROGRAM_PATH` variables. diff --git a/Help/variable/CMAKE_SYSTEM_INCLUDE_PATH.rst b/Help/variable/CMAKE_SYSTEM_INCLUDE_PATH.rst new file mode 100644 index 0000000..680404e --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_INCLUDE_PATH.rst @@ -0,0 +1,8 @@ +CMAKE_SYSTEM_INCLUDE_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 +this. See also :variable:`CMAKE_SYSTEM_PREFIX_PATH`. diff --git a/Help/variable/CMAKE_SYSTEM_LIBRARY_PATH.rst b/Help/variable/CMAKE_SYSTEM_LIBRARY_PATH.rst new file mode 100644 index 0000000..116832b --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_LIBRARY_PATH.rst @@ -0,0 +1,8 @@ +CMAKE_SYSTEM_LIBRARY_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. +See also :variable:`CMAKE_SYSTEM_PREFIX_PATH`. diff --git a/Help/variable/CMAKE_SYSTEM_NAME.rst b/Help/variable/CMAKE_SYSTEM_NAME.rst new file mode 100644 index 0000000..fef53ee --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_NAME.rst @@ -0,0 +1,23 @@ +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 +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``CMAKE_SYSTEM_NAME`` is by default set to the same value as the +:variable:`CMAKE_HOST_SYSTEM_NAME` variable so that the build +targets the host system. + +System Name for Cross Compiling +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``CMAKE_SYSTEM_NAME`` may be set explicitly when first configuring a new build +tree in order to enable :ref:`cross compiling <Cross Compiling Toolchain>`. +In this case the :variable:`CMAKE_SYSTEM_VERSION` variable must also be +set explicitly. diff --git a/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst b/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst new file mode 100644 index 0000000..81a7a0b --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst @@ -0,0 +1,53 @@ +CMAKE_SYSTEM_PREFIX_PATH +------------------------ + +: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 +subdirectories (like ``bin``, ``lib``, or ``include``) as specified in its own +documentation. + +By default this contains the system directories for the current system, the +:variable:`CMAKE_INSTALL_PREFIX`, and the :variable:`CMAKE_STAGING_PREFIX`. +The installation and staging prefixes may be excluded by setting +the :variable:`CMAKE_FIND_NO_INSTALL_PREFIX` variable. + +The system directories that are contained in ``CMAKE_SYSTEM_PREFIX_PATH`` are +locations that typically include installed software. An example being +``/usr/local`` for UNIX based platforms. In addition to standard platform +locations, CMake will also add values to ``CMAKE_SYSTEM_PREFIX_PATH`` based on +environment variables. The environment variables and search locations that +CMake uses may evolve over time, as platforms and their conventions also +evolve. The following provides an indicative list of environment variables +and locations that CMake searches, but they are subject to change: + + +CrayLinuxEnvironment: + * ``ENV{SYSROOT_DIR}/`` + * ``ENV{SYSROOT_DIR}/usr`` + * ``ENV{SYSROOT_DIR}/usr/local`` + +Darwin: + * ``ENV{SDKROOT}/usr`` When ``CMAKE_OSX_SYSROOT`` is not explicitly specified. + +OpenBSD: + * ``ENV{LOCALBASE}`` + +Unix: + * ``ENV{CONDA_PREFIX}`` when using a conda compiler + +Windows: + * ``ENV{ProgramW6432}`` + * ``ENV{ProgramFiles}`` + * ``ENV{ProgramFiles(x86)}`` + * ``ENV{SystemDrive}/Program Files`` + * ``ENV{SystemDrive}/Program Files (x86)`` + + +``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`, +and :variable:`CMAKE_SYSTEM_IGNORE_PATH`. diff --git a/Help/variable/CMAKE_SYSTEM_PROCESSOR.rst b/Help/variable/CMAKE_SYSTEM_PROCESSOR.rst new file mode 100644 index 0000000..ce16215 --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_PROCESSOR.rst @@ -0,0 +1,13 @@ +CMAKE_SYSTEM_PROCESSOR +---------------------- + +When not cross-compiling, this variable has the same value as the +:variable:`CMAKE_HOST_SYSTEM_PROCESSOR` variable. In many cases, +this will correspond to the target architecture for the build, but +this is not guaranteed. (E.g. on Windows, the host may be ``AMD64`` +even when using a MSVC ``cl`` compiler with a 32-bit target.) + +When cross-compiling, a :variable:`CMAKE_TOOLCHAIN_FILE` should set +the ``CMAKE_SYSTEM_PROCESSOR`` variable to match target architecture +that it specifies (via :variable:`CMAKE_<LANG>_COMPILER` and perhaps +:variable:`CMAKE_<LANG>_COMPILER_TARGET`). diff --git a/Help/variable/CMAKE_SYSTEM_PROGRAM_PATH.rst b/Help/variable/CMAKE_SYSTEM_PROGRAM_PATH.rst new file mode 100644 index 0000000..9b70361 --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_PROGRAM_PATH.rst @@ -0,0 +1,8 @@ +CMAKE_SYSTEM_PROGRAM_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. +See also :variable:`CMAKE_SYSTEM_PREFIX_PATH`. diff --git a/Help/variable/CMAKE_SYSTEM_VERSION.rst b/Help/variable/CMAKE_SYSTEM_VERSION.rst new file mode 100644 index 0000000..aba8ca3 --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_VERSION.rst @@ -0,0 +1,28 @@ +CMAKE_SYSTEM_VERSION +-------------------- + +The version of the operating system for which CMake is to build. +See the :variable:`CMAKE_SYSTEM_NAME` variable for the OS name. + +System Version for Host Builds +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When the :variable:`CMAKE_SYSTEM_NAME` variable takes its default value +then ``CMAKE_SYSTEM_VERSION`` is by default set to the same value as the +:variable:`CMAKE_HOST_SYSTEM_VERSION` variable so that the build targets +the host system version. + +In the case of a host build then ``CMAKE_SYSTEM_VERSION`` may be set +explicitly when first configuring a new build tree in order to enable +targeting the build for a different version of the host operating system +than is actually running on the host. This is allowed and not considered +cross compiling so long as the binaries built for the specified OS version +can still run on the host. + +System Version for Cross Compiling +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When the :variable:`CMAKE_SYSTEM_NAME` variable is set explicitly to +enable :ref:`cross compiling <Cross Compiling Toolchain>` then the +value of ``CMAKE_SYSTEM_VERSION`` must also be set explicitly to specify +the target system version. diff --git a/Help/variable/CMAKE_Swift_LANGUAGE_VERSION.rst b/Help/variable/CMAKE_Swift_LANGUAGE_VERSION.rst new file mode 100644 index 0000000..fce6fa7 --- /dev/null +++ b/Help/variable/CMAKE_Swift_LANGUAGE_VERSION.rst @@ -0,0 +1,11 @@ +CMAKE_Swift_LANGUAGE_VERSION +---------------------------- + +.. versionadded:: 3.7 + +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 0000000..3694973 --- /dev/null +++ b/Help/variable/CMAKE_Swift_MODULE_DIRECTORY.rst @@ -0,0 +1,10 @@ +CMAKE_Swift_MODULE_DIRECTORY +---------------------------- + +.. versionadded:: 3.15 + +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 0000000..e1dafb0 --- /dev/null +++ b/Help/variable/CMAKE_Swift_NUM_THREADS.rst @@ -0,0 +1,10 @@ +CMAKE_Swift_NUM_THREADS +----------------------- + +.. versionadded:: 3.15.1 + +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_TOOLCHAIN_FILE.rst b/Help/variable/CMAKE_TOOLCHAIN_FILE.rst new file mode 100644 index 0000000..e462c5e --- /dev/null +++ b/Help/variable/CMAKE_TOOLCHAIN_FILE.rst @@ -0,0 +1,12 @@ +CMAKE_TOOLCHAIN_FILE +-------------------- + +Path to toolchain file supplied to :manual:`cmake(1)`. + +This variable is specified on the command line when cross-compiling with CMake. +It is the path to a file which is read early in the CMake run and which +specifies locations for compilers and toolchain utilities, and other target +platform and compiler related information. + +Relative paths are allowed and are interpreted first as relative to the +build directory, and if not found, relative to the source directory. diff --git a/Help/variable/CMAKE_TRY_COMPILE_CONFIGURATION.rst b/Help/variable/CMAKE_TRY_COMPILE_CONFIGURATION.rst new file mode 100644 index 0000000..d731f02 --- /dev/null +++ b/Help/variable/CMAKE_TRY_COMPILE_CONFIGURATION.rst @@ -0,0 +1,10 @@ +CMAKE_TRY_COMPILE_CONFIGURATION +------------------------------- + +Build configuration used for :command:`try_compile` and :command:`try_run` +projects. + +Projects built by :command:`try_compile` and :command:`try_run` are built +synchronously during the CMake configuration step. Therefore a specific build +configuration must be chosen even if the generated build system +supports multiple configurations. diff --git a/Help/variable/CMAKE_TRY_COMPILE_PLATFORM_VARIABLES.rst b/Help/variable/CMAKE_TRY_COMPILE_PLATFORM_VARIABLES.rst new file mode 100644 index 0000000..d178513 --- /dev/null +++ b/Help/variable/CMAKE_TRY_COMPILE_PLATFORM_VARIABLES.rst @@ -0,0 +1,28 @@ +CMAKE_TRY_COMPILE_PLATFORM_VARIABLES +------------------------------------ + +.. versionadded:: 3.6 + +List of variables that the :command:`try_compile` command source file signature +must propagate into the test project in order to target the same platform as +the host project. + +This variable should not be set by project code. It is meant to be set by +CMake's platform information modules for the current toolchain, or by a +toolchain file when used with :variable:`CMAKE_TOOLCHAIN_FILE`. + +Variables meaningful to CMake, such as :variable:`CMAKE_<LANG>_FLAGS`, are +propagated automatically. The ``CMAKE_TRY_COMPILE_PLATFORM_VARIABLES`` +variable may be set to pass custom variables meaningful to a toolchain file. +For example, a toolchain file may contain: + +.. code-block:: cmake + + set(CMAKE_SYSTEM_NAME ...) + set(CMAKE_TRY_COMPILE_PLATFORM_VARIABLES MY_CUSTOM_VARIABLE) + # ... use MY_CUSTOM_VARIABLE ... + +If a user passes ``-DMY_CUSTOM_VARIABLE=SomeValue`` to CMake then this +setting will be made visible to the toolchain file both for the main +project and for test projects generated by the :command:`try_compile` +command source file signature. diff --git a/Help/variable/CMAKE_TRY_COMPILE_TARGET_TYPE.rst b/Help/variable/CMAKE_TRY_COMPILE_TARGET_TYPE.rst new file mode 100644 index 0000000..b60539f --- /dev/null +++ b/Help/variable/CMAKE_TRY_COMPILE_TARGET_TYPE.rst @@ -0,0 +1,17 @@ +CMAKE_TRY_COMPILE_TARGET_TYPE +----------------------------- + +.. versionadded:: 3.6 + +Type of target generated for :command:`try_compile` calls using the +source file signature. Valid values are: + +``EXECUTABLE`` + Use :command:`add_executable` to name the source file in the + generated project. This is the default if no value is given. + +``STATIC_LIBRARY`` + Use :command:`add_library` with the ``STATIC`` option to name the + source file in the generated project. This avoids running the + linker and is intended for use with cross-compiling toolchains + that cannot link without custom flags or linker scripts. diff --git a/Help/variable/CMAKE_TWEAK_VERSION.rst b/Help/variable/CMAKE_TWEAK_VERSION.rst new file mode 100644 index 0000000..be2e050 --- /dev/null +++ b/Help/variable/CMAKE_TWEAK_VERSION.rst @@ -0,0 +1,11 @@ +CMAKE_TWEAK_VERSION +------------------- + +Defined to ``0`` for compatibility with code written for older +CMake versions that may have defined higher values. + +.. note:: + + In CMake versions 2.8.2 through 2.8.12, this variable holds + the fourth version number component of the + :variable:`CMAKE_VERSION` variable. diff --git a/Help/variable/CMAKE_UNITY_BUILD.rst b/Help/variable/CMAKE_UNITY_BUILD.rst new file mode 100644 index 0000000..54a781a --- /dev/null +++ b/Help/variable/CMAKE_UNITY_BUILD.rst @@ -0,0 +1,22 @@ +CMAKE_UNITY_BUILD +----------------- + +.. versionadded:: 3.16 + +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 0000000..7733fe8 --- /dev/null +++ b/Help/variable/CMAKE_UNITY_BUILD_BATCH_SIZE.rst @@ -0,0 +1,9 @@ +CMAKE_UNITY_BUILD_BATCH_SIZE +---------------------------- + +.. versionadded:: 3.16 + +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_UNITY_BUILD_UNIQUE_ID.rst b/Help/variable/CMAKE_UNITY_BUILD_UNIQUE_ID.rst new file mode 100644 index 0000000..64ef18a --- /dev/null +++ b/Help/variable/CMAKE_UNITY_BUILD_UNIQUE_ID.rst @@ -0,0 +1,8 @@ +CMAKE_UNITY_BUILD_UNIQUE_ID +--------------------------- + +.. versionadded:: 3.20 + +This variable is used to initialize the :prop_tgt:`UNITY_BUILD_UNIQUE_ID` +property of targets when they are created. It specifies the name of the +unique identifier generated per file in a unity build. diff --git a/Help/variable/CMAKE_USER_MAKE_RULES_OVERRIDE.rst b/Help/variable/CMAKE_USER_MAKE_RULES_OVERRIDE.rst new file mode 100644 index 0000000..622278e --- /dev/null +++ b/Help/variable/CMAKE_USER_MAKE_RULES_OVERRIDE.rst @@ -0,0 +1,25 @@ +CMAKE_USER_MAKE_RULES_OVERRIDE +------------------------------ + +Specify a CMake file that overrides platform information. + +CMake loads the specified file while enabling support for each +language from either the :command:`project` or :command:`enable_language` +commands. It is loaded after CMake's builtin compiler and platform information +modules have been loaded but before the information is used. The file +may set platform information variables to override CMake's defaults. + +This feature is intended for use only in overriding information +variables that must be set before CMake builds its first test project +to check that the compiler for a language works. It should not be +used to load a file in cases that a normal :command:`include` will work. Use +it only as a last resort for behavior that cannot be achieved any +other way. For example, one may set the +:variable:`CMAKE_C_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>` variable +to change the default value used to initialize the +:variable:`CMAKE_C_FLAGS <CMAKE_<LANG>_FLAGS>` variable +before it is cached. The override file should NOT be used to set anything +that could be set after languages are enabled, such as variables like +:variable:`CMAKE_RUNTIME_OUTPUT_DIRECTORY` that affect the placement of +binaries. Information set in the file will be used for :command:`try_compile` +and :command:`try_run` builds too. diff --git a/Help/variable/CMAKE_USER_MAKE_RULES_OVERRIDE_LANG.rst b/Help/variable/CMAKE_USER_MAKE_RULES_OVERRIDE_LANG.rst new file mode 100644 index 0000000..e7139ac --- /dev/null +++ b/Help/variable/CMAKE_USER_MAKE_RULES_OVERRIDE_LANG.rst @@ -0,0 +1,8 @@ +CMAKE_USER_MAKE_RULES_OVERRIDE_<LANG> +------------------------------------- + +Specify a CMake file that overrides platform information for ``<LANG>``. + +This is a language-specific version of +:variable:`CMAKE_USER_MAKE_RULES_OVERRIDE` loaded only when enabling language +``<LANG>``. diff --git a/Help/variable/CMAKE_USE_RELATIVE_PATHS.rst b/Help/variable/CMAKE_USE_RELATIVE_PATHS.rst new file mode 100644 index 0000000..06fe0fb --- /dev/null +++ b/Help/variable/CMAKE_USE_RELATIVE_PATHS.rst @@ -0,0 +1,5 @@ +CMAKE_USE_RELATIVE_PATHS +------------------------ + +This variable has no effect. The partially implemented effect it +had in previous releases was removed in CMake 3.4. diff --git a/Help/variable/CMAKE_VERBOSE_MAKEFILE.rst b/Help/variable/CMAKE_VERBOSE_MAKEFILE.rst new file mode 100644 index 0000000..232a2fd --- /dev/null +++ b/Help/variable/CMAKE_VERBOSE_MAKEFILE.rst @@ -0,0 +1,9 @@ +CMAKE_VERBOSE_MAKEFILE +---------------------- + +Enable verbose output from Makefile builds. + +This variable is a cache entry initialized (to ``FALSE``) by +the :command:`project` command. Users may enable the option +in their local build tree to get more verbose output from +Makefile builds and show each command line as it is launched. diff --git a/Help/variable/CMAKE_VERSION.rst b/Help/variable/CMAKE_VERSION.rst new file mode 100644 index 0000000..872e2fa --- /dev/null +++ b/Help/variable/CMAKE_VERSION.rst @@ -0,0 +1,51 @@ +CMAKE_VERSION +------------- + +The CMake version string as three non-negative integer components +separated by ``.`` and possibly followed by ``-`` and other information. +The first two components represent the feature level and the third +component represents either a bug-fix level or development date. + +Release versions and release candidate versions of CMake use the format:: + + <major>.<minor>.<patch>[-rc<n>] + +where the ``<patch>`` component is less than ``20000000``. Development +versions of CMake use the format:: + + <major>.<minor>.<date>[-<id>] + +where the ``<date>`` component is of format ``CCYYMMDD`` and ``<id>`` +may contain arbitrary text. This represents development as of a +particular date following the ``<major>.<minor>`` feature release. + +Individual component values are also available in variables: + +* :variable:`CMAKE_MAJOR_VERSION` +* :variable:`CMAKE_MINOR_VERSION` +* :variable:`CMAKE_PATCH_VERSION` +* :variable:`CMAKE_TWEAK_VERSION` + +Use the :command:`if` command ``VERSION_LESS``, ``VERSION_GREATER``, +``VERSION_EQUAL``, ``VERSION_LESS_EQUAL``, or ``VERSION_GREATER_EQUAL`` +operators to compare version string values against ``CMAKE_VERSION`` using a +component-wise test. Version component values may be 10 or larger so do not +attempt to compare version strings as floating-point numbers. + +.. note:: + + CMake versions 2.8.2 through 2.8.12 used three components for the + feature level. Release versions represented the bug-fix level in a + fourth component, i.e. ``<major>.<minor>.<patch>[.<tweak>][-rc<n>]``. + Development versions represented the development date in the fourth + component, i.e. ``<major>.<minor>.<patch>.<date>[-<id>]``. + + CMake versions prior to 2.8.2 used three components for the + feature level and had no bug-fix component. Release versions + used an even-valued second component, i.e. + ``<major>.<even-minor>.<patch>[-rc<n>]``. Development versions + used an odd-valued second component with the development date as + the third component, i.e. ``<major>.<odd-minor>.<date>``. + + The ``CMAKE_VERSION`` variable is defined by CMake 2.6.3 and higher. + Earlier versions defined only the individual component variables. diff --git a/Help/variable/CMAKE_VISIBILITY_INLINES_HIDDEN.rst b/Help/variable/CMAKE_VISIBILITY_INLINES_HIDDEN.rst new file mode 100644 index 0000000..150bacc --- /dev/null +++ b/Help/variable/CMAKE_VISIBILITY_INLINES_HIDDEN.rst @@ -0,0 +1,5 @@ +CMAKE_VISIBILITY_INLINES_HIDDEN +------------------------------- + +Default value for the :prop_tgt:`VISIBILITY_INLINES_HIDDEN` target +property when a target is created. diff --git a/Help/variable/CMAKE_VS_DEVENV_COMMAND.rst b/Help/variable/CMAKE_VS_DEVENV_COMMAND.rst new file mode 100644 index 0000000..f109a9e --- /dev/null +++ b/Help/variable/CMAKE_VS_DEVENV_COMMAND.rst @@ -0,0 +1,14 @@ +CMAKE_VS_DEVENV_COMMAND +----------------------- + +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. + +This variable is not defined by other generators even if ``devenv.com`` +is installed on the computer. + +The :variable:`CMAKE_VS_MSBUILD_COMMAND` is also provided for +:generator:`Visual Studio 10 2010` and above. +See also the :variable:`CMAKE_MAKE_PROGRAM` variable. diff --git a/Help/variable/CMAKE_VS_GLOBALS.rst b/Help/variable/CMAKE_VS_GLOBALS.rst new file mode 100644 index 0000000..d4514fe --- /dev/null +++ b/Help/variable/CMAKE_VS_GLOBALS.rst @@ -0,0 +1,23 @@ +CMAKE_VS_GLOBALS +---------------- + +.. versionadded:: 3.13 + +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_INCLUDE_INSTALL_TO_DEFAULT_BUILD.rst b/Help/variable/CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD.rst new file mode 100644 index 0000000..ace94e4 --- /dev/null +++ b/Help/variable/CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD.rst @@ -0,0 +1,10 @@ +CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD +----------------------------------------- + +.. versionadded:: 3.3 + +Include ``INSTALL`` target to default build. + +In Visual Studio solution, by default the ``INSTALL`` target will not be part +of the default build. Setting this variable will enable the ``INSTALL`` target +to be part of the default build. diff --git a/Help/variable/CMAKE_VS_INCLUDE_PACKAGE_TO_DEFAULT_BUILD.rst b/Help/variable/CMAKE_VS_INCLUDE_PACKAGE_TO_DEFAULT_BUILD.rst new file mode 100644 index 0000000..ab4d0fa --- /dev/null +++ b/Help/variable/CMAKE_VS_INCLUDE_PACKAGE_TO_DEFAULT_BUILD.rst @@ -0,0 +1,10 @@ +CMAKE_VS_INCLUDE_PACKAGE_TO_DEFAULT_BUILD +----------------------------------------- + +.. versionadded:: 3.8 + +Include ``PACKAGE`` target to default build. + +In Visual Studio solution, by default the ``PACKAGE`` target will not be part +of the default build. Setting this variable will enable the ``PACKAGE`` target +to be part of the default build. diff --git a/Help/variable/CMAKE_VS_INTEL_Fortran_PROJECT_VERSION.rst b/Help/variable/CMAKE_VS_INTEL_Fortran_PROJECT_VERSION.rst new file mode 100644 index 0000000..ceedf28 --- /dev/null +++ b/Help/variable/CMAKE_VS_INTEL_Fortran_PROJECT_VERSION.rst @@ -0,0 +1,7 @@ +CMAKE_VS_INTEL_Fortran_PROJECT_VERSION +-------------------------------------- + +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 0000000..0a02a32 --- /dev/null +++ b/Help/variable/CMAKE_VS_JUST_MY_CODE_DEBUGGING.rst @@ -0,0 +1,10 @@ +CMAKE_VS_JUST_MY_CODE_DEBUGGING +------------------------------- + +.. versionadded:: 3.15 + +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_MSBUILD_COMMAND.rst b/Help/variable/CMAKE_VS_MSBUILD_COMMAND.rst new file mode 100644 index 0000000..58f2bef --- /dev/null +++ b/Help/variable/CMAKE_VS_MSBUILD_COMMAND.rst @@ -0,0 +1,13 @@ +CMAKE_VS_MSBUILD_COMMAND +------------------------ + +The generators for :generator:`Visual Studio 10 2010` and above set this +variable to the ``MSBuild.exe`` command installed with the corresponding +Visual Studio version. + +This variable is not defined by other generators even if ``MSBuild.exe`` +is installed on the computer. + +The :variable:`CMAKE_VS_DEVENV_COMMAND` is also provided for the +non-Express editions of Visual Studio. +See also the :variable:`CMAKE_MAKE_PROGRAM` variable. diff --git a/Help/variable/CMAKE_VS_NsightTegra_VERSION.rst b/Help/variable/CMAKE_VS_NsightTegra_VERSION.rst new file mode 100644 index 0000000..2982b39 --- /dev/null +++ b/Help/variable/CMAKE_VS_NsightTegra_VERSION.rst @@ -0,0 +1,9 @@ +CMAKE_VS_NsightTegra_VERSION +---------------------------- + +.. versionadded:: 3.1 + +When using a Visual Studio generator with the +:variable:`CMAKE_SYSTEM_NAME` variable set to ``Android``, +this variable contains the version number of the +installed NVIDIA Nsight Tegra Visual Studio Edition. diff --git a/Help/variable/CMAKE_VS_PLATFORM_NAME.rst b/Help/variable/CMAKE_VS_PLATFORM_NAME.rst new file mode 100644 index 0000000..7d08add --- /dev/null +++ b/Help/variable/CMAKE_VS_PLATFORM_NAME.rst @@ -0,0 +1,12 @@ +CMAKE_VS_PLATFORM_NAME +---------------------- + +.. versionadded:: 3.1 + +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 0000000..6440174 --- /dev/null +++ b/Help/variable/CMAKE_VS_PLATFORM_NAME_DEFAULT.rst @@ -0,0 +1,11 @@ +CMAKE_VS_PLATFORM_NAME_DEFAULT +------------------------------ + +.. versionadded:: 3.14.3 + +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.rst b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET.rst new file mode 100644 index 0000000..ed2d3f3 --- /dev/null +++ b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET.rst @@ -0,0 +1,12 @@ +CMAKE_VS_PLATFORM_TOOLSET +------------------------- + +Visual Studio Platform Toolset name. + +VS 10 and above use MSBuild under the hood and support multiple +compiler toolchains. CMake may specify a toolset explicitly, such as +``v110`` for VS 11 or ``Windows7.1SDK`` for 64-bit support in VS 10 +Express. CMake provides the name of the chosen toolset in this +variable. + +See the :variable:`CMAKE_GENERATOR_TOOLSET` variable for details. diff --git a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA.rst b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA.rst new file mode 100644 index 0000000..e66378d --- /dev/null +++ b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA.rst @@ -0,0 +1,16 @@ +CMAKE_VS_PLATFORM_TOOLSET_CUDA +------------------------------ + +.. versionadded:: 3.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``. 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 0000000..a19e7e1 --- /dev/null +++ b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR.rst @@ -0,0 +1,17 @@ +CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR +----------------------------------------- + +.. versionadded:: 3.16 + +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 the nvcc compiler in path ``.\bin`` and must provide Visual Studio +integration files in path ``.\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 new file mode 100644 index 0000000..84d7212 --- /dev/null +++ b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE.rst @@ -0,0 +1,12 @@ +CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE +------------------------------------------- + +.. versionadded:: 3.8 + +Visual Studio preferred tool architecture. + +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 0000000..c4369ee --- /dev/null +++ b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_VERSION.rst @@ -0,0 +1,33 @@ +CMAKE_VS_PLATFORM_TOOLSET_VERSION +--------------------------------- + +.. versionadded:: 3.12 + +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. + +If the value is not empty, it is the version number that MSBuild uses in +its ``Microsoft.VCToolsVersion.*.props`` file names. + +.. versionadded:: 3.19.7 + + VS 16.9's toolset may also be specified as ``14.28.16.9`` because + VS 16.10 uses the file name ``Microsoft.VCToolsVersion.14.28.16.9.props``. + +Three-Component MSVC Toolset Versions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 3.19.7 + +The ``version=`` field may be given a three-component toolset version +such as ``14.28.29910``, and CMake will convert it to the name used by +MSBuild ``Microsoft.VCToolsVersion.*.props`` files. This is useful +to distinguish between VS 16.8's ``14.28.29333`` toolset and VS 16.9's +``14.28.29910`` toolset. It also matches ``vcvarsall``'s ``-vcvars_ver=`` +behavior. 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 0000000..969f328 --- /dev/null +++ b/Help/variable/CMAKE_VS_SDK_EXCLUDE_DIRECTORIES.rst @@ -0,0 +1,6 @@ +CMAKE_VS_SDK_EXCLUDE_DIRECTORIES +-------------------------------- + +.. versionadded:: 3.12 + +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 0000000..7455e10 --- /dev/null +++ b/Help/variable/CMAKE_VS_SDK_EXECUTABLE_DIRECTORIES.rst @@ -0,0 +1,6 @@ +CMAKE_VS_SDK_EXECUTABLE_DIRECTORIES +----------------------------------- + +.. versionadded:: 3.12 + +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 0000000..3f27aea --- /dev/null +++ b/Help/variable/CMAKE_VS_SDK_INCLUDE_DIRECTORIES.rst @@ -0,0 +1,6 @@ +CMAKE_VS_SDK_INCLUDE_DIRECTORIES +-------------------------------- + +.. versionadded:: 3.12 + +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 0000000..35e45a3 --- /dev/null +++ b/Help/variable/CMAKE_VS_SDK_LIBRARY_DIRECTORIES.rst @@ -0,0 +1,6 @@ +CMAKE_VS_SDK_LIBRARY_DIRECTORIES +-------------------------------- + +.. versionadded:: 3.12 + +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 0000000..24b90b6 --- /dev/null +++ b/Help/variable/CMAKE_VS_SDK_LIBRARY_WINRT_DIRECTORIES.rst @@ -0,0 +1,7 @@ +CMAKE_VS_SDK_LIBRARY_WINRT_DIRECTORIES +-------------------------------------- + +.. versionadded:: 3.12 + +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 0000000..00382fe --- /dev/null +++ b/Help/variable/CMAKE_VS_SDK_REFERENCE_DIRECTORIES.rst @@ -0,0 +1,6 @@ +CMAKE_VS_SDK_REFERENCE_DIRECTORIES +---------------------------------- + +.. versionadded:: 3.12 + +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 0000000..b98c999 --- /dev/null +++ b/Help/variable/CMAKE_VS_SDK_SOURCE_DIRECTORIES.rst @@ -0,0 +1,6 @@ +CMAKE_VS_SDK_SOURCE_DIRECTORIES +------------------------------- + +.. versionadded:: 3.12 + +This variable allows to override Visual Studio default Source Directories. diff --git a/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst b/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst new file mode 100644 index 0000000..eb71049 --- /dev/null +++ b/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst @@ -0,0 +1,21 @@ +CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION +---------------------------------------- + +.. versionadded:: 3.4 + +Visual Studio Windows Target Platform Version. + +When targeting Windows 10 and above Visual Studio 2015 and above support +specification of a target Windows version to select a corresponding SDK. +The :variable:`CMAKE_SYSTEM_VERSION` variable may be set to specify a +version. Otherwise CMake computes a default version based on the Windows +SDK versions available. The chosen Windows target version number is provided +in ``CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION``. If no Windows 10 SDK +is available this value will be empty. + +One may set a ``CMAKE_WINDOWS_KITS_10_DIR`` *environment variable* +to an absolute path to tell CMake to look for Windows 10 SDKs in +a custom location. The specified directory is expected to contain +``Include/10.0.*`` directories. + +See also :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM`. diff --git a/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM.rst b/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM.rst new file mode 100644 index 0000000..d9f136c --- /dev/null +++ b/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM.rst @@ -0,0 +1,14 @@ +CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM +------------------------------------------------ + +.. versionadded:: 3.19 + +Override the :ref:`Windows 10 SDK Maximum Version for VS 2015` and beyond. + +The :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM` variable may +be set to a false value (e.g. ``OFF``, ``FALSE``, or ``0``) or the SDK version +to use as the maximum (e.g. ``10.0.14393.0``). If unset, the default depends +on which version of Visual Studio is targeted by the current generator. + +This can be used in conjunction with :variable:`CMAKE_SYSTEM_VERSION`, which +CMake uses to select :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION`. 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 0000000..9ded85f --- /dev/null +++ b/Help/variable/CMAKE_VS_WINRT_BY_DEFAULT.rst @@ -0,0 +1,20 @@ +CMAKE_VS_WINRT_BY_DEFAULT +------------------------- + +.. versionadded:: 3.13 + +Inform :ref:`Visual Studio Generators` for VS 2010 and above that the +target platform enables WinRT compilation by default and it needs to +be explicitly disabled if ``/ZW`` or :prop_tgt:`VS_WINRT_COMPONENT` is +omitted (as opposed to enabling it when either of those options is +present) + +This makes cmake configuration consistent in terms of WinRT among +platforms - if you did not enable the WinRT compilation explicitly, it +will be disabled (by either not enabling it or explicitly disabling it) + +Note: WinRT compilation is always explicitly disabled for C language +source files, even if it is expliclty enabled for a project + +This variable is meant to be set by a +:variable:`toolchain file <CMAKE_TOOLCHAIN_FILE>` for such platforms. diff --git a/Help/variable/CMAKE_WARN_DEPRECATED.rst b/Help/variable/CMAKE_WARN_DEPRECATED.rst new file mode 100644 index 0000000..4a224fa --- /dev/null +++ b/Help/variable/CMAKE_WARN_DEPRECATED.rst @@ -0,0 +1,10 @@ +CMAKE_WARN_DEPRECATED +--------------------- + +Whether to issue warnings for deprecated functionality. + +If not ``FALSE``, use of deprecated functionality will issue warnings. +If this variable is not set, CMake behaves as if it were set to ``TRUE``. + +When running :manual:`cmake(1)`, this option can be enabled with the +``-Wdeprecated`` option, or disabled with the ``-Wno-deprecated`` option. diff --git a/Help/variable/CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION.rst b/Help/variable/CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION.rst new file mode 100644 index 0000000..81c1158 --- /dev/null +++ b/Help/variable/CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION.rst @@ -0,0 +1,9 @@ +CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION +------------------------------------------ + +Ask ``cmake_install.cmake`` script to warn each time a file with absolute +``INSTALL DESTINATION`` is encountered. + +This variable is used by CMake-generated ``cmake_install.cmake`` scripts. +If one sets this variable to ``ON`` while running the script, it may get +warning messages from the script. diff --git a/Help/variable/CMAKE_WIN32_EXECUTABLE.rst b/Help/variable/CMAKE_WIN32_EXECUTABLE.rst new file mode 100644 index 0000000..b96abba --- /dev/null +++ b/Help/variable/CMAKE_WIN32_EXECUTABLE.rst @@ -0,0 +1,7 @@ +CMAKE_WIN32_EXECUTABLE +---------------------- + +Default value for :prop_tgt:`WIN32_EXECUTABLE` of targets. + +This variable is used to initialize the :prop_tgt:`WIN32_EXECUTABLE` property +on all the targets. See that target property for additional information. diff --git a/Help/variable/CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS.rst b/Help/variable/CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS.rst new file mode 100644 index 0000000..7b01185 --- /dev/null +++ b/Help/variable/CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS.rst @@ -0,0 +1,8 @@ +CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS +-------------------------------- + +.. versionadded:: 3.4 + +Default value for :prop_tgt:`WINDOWS_EXPORT_ALL_SYMBOLS` target property. +This variable is used to initialize the property on each target as it is +created. diff --git a/Help/variable/CMAKE_XCODE_ATTRIBUTE_an-attribute.rst b/Help/variable/CMAKE_XCODE_ATTRIBUTE_an-attribute.rst new file mode 100644 index 0000000..ffa0a4c --- /dev/null +++ b/Help/variable/CMAKE_XCODE_ATTRIBUTE_an-attribute.rst @@ -0,0 +1,24 @@ +CMAKE_XCODE_ATTRIBUTE_<an-attribute> +------------------------------------ + +.. versionadded:: 3.1 + +Set Xcode target attributes directly. + +Tell the :generator:`Xcode` generator to set ``<an-attribute>`` to a given +value in the generated Xcode project. Ignored on other generators. + +This offers low-level control over the generated Xcode project file. +It is meant as a last resort for specifying settings that CMake does +not otherwise have a way to control. Although this can override a +setting CMake normally produces on its own, doing so bypasses CMake's +model of the project and can break things. + +See the :prop_tgt:`XCODE_ATTRIBUTE_<an-attribute>` target property +to set attributes on a specific target. + +Contents of ``CMAKE_XCODE_ATTRIBUTE_<an-attribute>`` 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/variable/CMAKE_XCODE_BUILD_SYSTEM.rst b/Help/variable/CMAKE_XCODE_BUILD_SYSTEM.rst new file mode 100644 index 0000000..d153061 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_BUILD_SYSTEM.rst @@ -0,0 +1,24 @@ +CMAKE_XCODE_BUILD_SYSTEM +------------------------ + +.. versionadded:: 3.19 + +Xcode build system selection. + +The :generator:`Xcode` generator defines this variable to indicate which +variant of the Xcode build system will be used. The value is the +version of Xcode in which the corresponding build system first became +mature enough for use by CMake. The possible values are: + +``1`` + The original Xcode build system. + This is the default when using Xcode 11.x or below. + +``12`` + The Xcode "new build system" introduced by Xcode 10. + It became mature enough for use by CMake in Xcode 12. + This is the default when using Xcode 12.x or above. + +The ``CMAKE_XCODE_BUILD_SYSTEM`` variable is informational and should not +be modified by project code. See the :ref:`Xcode Build System Selection` +documentation section to select the Xcode build system. diff --git a/Help/variable/CMAKE_XCODE_GENERATE_SCHEME.rst b/Help/variable/CMAKE_XCODE_GENERATE_SCHEME.rst new file mode 100644 index 0000000..40070e1 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_GENERATE_SCHEME.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_GENERATE_SCHEME +--------------------------- + +.. versionadded:: 3.9 + +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 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 0000000..38d043c --- /dev/null +++ b/Help/variable/CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY.rst @@ -0,0 +1,11 @@ +CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY +------------------------------------------- + +.. versionadded:: 3.11 + +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_LINK_BUILD_PHASE_MODE.rst b/Help/variable/CMAKE_XCODE_LINK_BUILD_PHASE_MODE.rst new file mode 100644 index 0000000..17189c0 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_LINK_BUILD_PHASE_MODE.rst @@ -0,0 +1,9 @@ +CMAKE_XCODE_LINK_BUILD_PHASE_MODE +--------------------------------- + +.. versionadded:: 3.19 + +This variable is used to initialize the +:prop_tgt:`XCODE_LINK_BUILD_PHASE_MODE` property on targets. +It affects the methods that the :generator:`Xcode` generator uses to link +different kinds of libraries. Its default value is ``NONE``. diff --git a/Help/variable/CMAKE_XCODE_PLATFORM_TOOLSET.rst b/Help/variable/CMAKE_XCODE_PLATFORM_TOOLSET.rst new file mode 100644 index 0000000..210da52 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_PLATFORM_TOOLSET.rst @@ -0,0 +1,9 @@ +CMAKE_XCODE_PLATFORM_TOOLSET +---------------------------- + +Xcode compiler selection. + +:generator:`Xcode` supports selection of a compiler from one of the installed +toolsets. CMake provides the name of the chosen toolset in this +variable, if any is explicitly selected (e.g. via the :manual:`cmake(1)` +``-T`` option). 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 0000000..b3fa93b --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER.rst @@ -0,0 +1,14 @@ +CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER +------------------------------------ + +.. versionadded:: 3.13 + +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 0000000..1a0a17a --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN.rst @@ -0,0 +1,14 @@ +CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN +----------------------------------------------------- + +.. versionadded:: 3.13 + +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 0000000..917fc7f --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING.rst @@ -0,0 +1,15 @@ +CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING +-------------------------------------------- + +.. versionadded:: 3.16 + +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 0000000..b604598 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER.rst @@ -0,0 +1,14 @@ +CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER +---------------------------------------------- + +.. versionadded:: 3.13 + +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 0000000..070ddfc --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS.rst @@ -0,0 +1,14 @@ +CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS +---------------------------------------- + +.. versionadded:: 3.13 + +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 0000000..4291816 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE.rst @@ -0,0 +1,14 @@ +CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE +------------------------------------------- + +.. versionadded:: 3.13 + +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_ENVIRONMENT.rst b/Help/variable/CMAKE_XCODE_SCHEME_ENVIRONMENT.rst new file mode 100644 index 0000000..62b698d --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_ENVIRONMENT.rst @@ -0,0 +1,17 @@ +CMAKE_XCODE_SCHEME_ENVIRONMENT +------------------------------ + +.. versionadded:: 3.17 + +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. + +This variable initializes the :prop_tgt:`XCODE_SCHEME_ENVIRONMENT` +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 0000000..48b481e --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_GUARD_MALLOC.rst @@ -0,0 +1,14 @@ +CMAKE_XCODE_SCHEME_GUARD_MALLOC +------------------------------- + +.. versionadded:: 3.13 + +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 0000000..ef8ed9b --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP.rst @@ -0,0 +1,15 @@ +CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP +------------------------------------------- + +.. versionadded:: 3.13 + +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 0000000..d4ae9eb --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES.rst @@ -0,0 +1,14 @@ +CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES +------------------------------------- + +.. versionadded:: 3.13 + +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 0000000..e28f6a1 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE.rst @@ -0,0 +1,14 @@ +CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE +---------------------------------- + +.. versionadded:: 3.13 + +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 0000000..59fcfd3 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_MALLOC_STACK.rst @@ -0,0 +1,14 @@ +CMAKE_XCODE_SCHEME_MALLOC_STACK +------------------------------- + +.. versionadded:: 3.13 + +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 0000000..511eb04 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER.rst @@ -0,0 +1,14 @@ +CMAKE_XCODE_SCHEME_THREAD_SANITIZER +----------------------------------- + +.. versionadded:: 3.13 + +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 0000000..6f3b8ce --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP.rst @@ -0,0 +1,14 @@ +CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP +---------------------------------------- + +.. versionadded:: 3.13 + +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 0000000..46d3ccf --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER.rst @@ -0,0 +1,14 @@ +CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER +------------------------------------------------ + +.. versionadded:: 3.13 + +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 0000000..8fa5ece --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP.rst @@ -0,0 +1,15 @@ +CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP +----------------------------------------------------- + +.. versionadded:: 3.13 + +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_WORKING_DIRECTORY.rst b/Help/variable/CMAKE_XCODE_SCHEME_WORKING_DIRECTORY.rst new file mode 100644 index 0000000..4221e48 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_WORKING_DIRECTORY.rst @@ -0,0 +1,14 @@ +CMAKE_XCODE_SCHEME_WORKING_DIRECTORY +------------------------------------ + +.. versionadded:: 3.17 + +Specify the ``Working Directory`` of the *Run* and *Profile* +actions in the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_WORKING_DIRECTORY` +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 0000000..fd9488e --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS.rst @@ -0,0 +1,14 @@ +CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS +--------------------------------- + +.. versionadded:: 3.13 + +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_ABSOLUTE_DESTINATION_FILES.rst b/Help/variable/CPACK_ABSOLUTE_DESTINATION_FILES.rst new file mode 100644 index 0000000..928fe45 --- /dev/null +++ b/Help/variable/CPACK_ABSOLUTE_DESTINATION_FILES.rst @@ -0,0 +1,10 @@ +CPACK_ABSOLUTE_DESTINATION_FILES +-------------------------------- + +List of files which have been installed using an ``ABSOLUTE DESTINATION`` path. + +This variable is a Read-Only variable which is set internally by CPack +during installation and before packaging using +:variable:`CMAKE_ABSOLUTE_DESTINATION_FILES` defined in ``cmake_install.cmake`` +scripts. The value can be used within CPack project configuration +file and/or ``CPack<GEN>.cmake`` file of ``<GEN>`` generator. diff --git a/Help/variable/CPACK_COMPONENT_INCLUDE_TOPLEVEL_DIRECTORY.rst b/Help/variable/CPACK_COMPONENT_INCLUDE_TOPLEVEL_DIRECTORY.rst new file mode 100644 index 0000000..6cf75e4 --- /dev/null +++ b/Help/variable/CPACK_COMPONENT_INCLUDE_TOPLEVEL_DIRECTORY.rst @@ -0,0 +1,8 @@ +CPACK_COMPONENT_INCLUDE_TOPLEVEL_DIRECTORY +------------------------------------------ + +Boolean toggle to include/exclude top level directory (component case). + +Similar usage as :variable:`CPACK_INCLUDE_TOPLEVEL_DIRECTORY` but for the +component case. See :variable:`CPACK_INCLUDE_TOPLEVEL_DIRECTORY` +documentation for the detail. diff --git a/Help/variable/CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION.rst b/Help/variable/CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION.rst new file mode 100644 index 0000000..30ae236 --- /dev/null +++ b/Help/variable/CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION.rst @@ -0,0 +1,11 @@ +CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION +------------------------------------------- + +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 +internally. This variable triggers the definition +of :variable:`CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION` when CPack +runs. diff --git a/Help/variable/CPACK_INCLUDE_TOPLEVEL_DIRECTORY.rst b/Help/variable/CPACK_INCLUDE_TOPLEVEL_DIRECTORY.rst new file mode 100644 index 0000000..b8e9105 --- /dev/null +++ b/Help/variable/CPACK_INCLUDE_TOPLEVEL_DIRECTORY.rst @@ -0,0 +1,20 @@ +CPACK_INCLUDE_TOPLEVEL_DIRECTORY +-------------------------------- + +Boolean toggle to include/exclude top level directory. + +When preparing a package CPack installs the item under the so-called +top level directory. The purpose of is to include (set to ``1`` or ``ON`` or +``TRUE``) the top level directory in the package or not (set to ``0`` or +``OFF`` or ``FALSE``). + +Each CPack generator has a built-in default value for this variable. +E.g. Archive generators (ZIP, TGZ, ...) includes the top level +whereas RPM or DEB don't. The user may override the default value by +setting this variable. + +There is a similar variable +:variable:`CPACK_COMPONENT_INCLUDE_TOPLEVEL_DIRECTORY` which may be used +to override the behavior for the component packaging +case which may have different default value for historical (now +backward compatibility) reason. 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 0000000..01fb189 --- /dev/null +++ b/Help/variable/CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS.rst @@ -0,0 +1,13 @@ +CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS +------------------------------------------- + +.. versionadded:: 3.11 + +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_PACKAGING_INSTALL_PREFIX.rst b/Help/variable/CPACK_PACKAGING_INSTALL_PREFIX.rst new file mode 100644 index 0000000..f423e2e --- /dev/null +++ b/Help/variable/CPACK_PACKAGING_INSTALL_PREFIX.rst @@ -0,0 +1,15 @@ +CPACK_PACKAGING_INSTALL_PREFIX +------------------------------ + +The prefix used in the built package. + +Each CPack generator has a default value (like ``/usr``). This default +value may be overwritten from the ``CMakeLists.txt`` or the :manual:`cpack(1)` +command line by setting an alternative value. Example: + +:: + + set(CPACK_PACKAGING_INSTALL_PREFIX "/opt") + +This is not the same purpose as :variable:`CMAKE_INSTALL_PREFIX` which is used +when installing from the build tree without building a package. diff --git a/Help/variable/CPACK_SET_DESTDIR.rst b/Help/variable/CPACK_SET_DESTDIR.rst new file mode 100644 index 0000000..27fd355 --- /dev/null +++ b/Help/variable/CPACK_SET_DESTDIR.rst @@ -0,0 +1,31 @@ +CPACK_SET_DESTDIR +----------------- + +Boolean toggle to make CPack use ``DESTDIR`` mechanism when packaging. + +``DESTDIR`` means DESTination DIRectory. It is commonly used by makefile +users in order to install software at non-default location. It is a +basic relocation mechanism that should not be used on Windows (see +:variable:`CMAKE_INSTALL_PREFIX` documentation). 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``. When preparing a package, CPack +first installs the items to be packaged in a local (to the build tree) +directory by using the same ``DESTDIR`` mechanism. Nevertheless, if +``CPACK_SET_DESTDIR`` is set then CPack will set ``DESTDIR`` before doing the +local install. The most noticeable difference is that without +``CPACK_SET_DESTDIR``, CPack uses :variable:`CPACK_PACKAGING_INSTALL_PREFIX` +as a prefix whereas with ``CPACK_SET_DESTDIR`` set, CPack will use +:variable:`CMAKE_INSTALL_PREFIX` as a prefix. + +Manually setting ``CPACK_SET_DESTDIR`` may help (or simply be necessary) +if some install rules uses absolute ``DESTINATION`` (see CMake +:command:`install` command). However, starting with CPack/CMake 2.8.3 RPM +and DEB installers tries to handle ``DESTDIR`` automatically so that it is +seldom necessary for the user to set it. diff --git a/Help/variable/CPACK_WARN_ON_ABSOLUTE_INSTALL_DESTINATION.rst b/Help/variable/CPACK_WARN_ON_ABSOLUTE_INSTALL_DESTINATION.rst new file mode 100644 index 0000000..3fc5cca --- /dev/null +++ b/Help/variable/CPACK_WARN_ON_ABSOLUTE_INSTALL_DESTINATION.rst @@ -0,0 +1,9 @@ +CPACK_WARN_ON_ABSOLUTE_INSTALL_DESTINATION +------------------------------------------ + +Ask CPack to warn each time a file with absolute ``INSTALL DESTINATION`` is +encountered. + +This variable triggers the definition of +:variable:`CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION` when CPack runs +``cmake_install.cmake`` scripts. diff --git a/Help/variable/CTEST_BINARY_DIRECTORY.rst b/Help/variable/CTEST_BINARY_DIRECTORY.rst new file mode 100644 index 0000000..8413e37 --- /dev/null +++ b/Help/variable/CTEST_BINARY_DIRECTORY.rst @@ -0,0 +1,7 @@ +CTEST_BINARY_DIRECTORY +---------------------- + +.. versionadded:: 3.1 + +Specify the CTest ``BuildDirectory`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_BUILD_COMMAND.rst b/Help/variable/CTEST_BUILD_COMMAND.rst new file mode 100644 index 0000000..31c44e2 --- /dev/null +++ b/Help/variable/CTEST_BUILD_COMMAND.rst @@ -0,0 +1,7 @@ +CTEST_BUILD_COMMAND +------------------- + +.. versionadded:: 3.1 + +Specify the CTest ``MakeCommand`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_BUILD_NAME.rst b/Help/variable/CTEST_BUILD_NAME.rst new file mode 100644 index 0000000..3d08397 --- /dev/null +++ b/Help/variable/CTEST_BUILD_NAME.rst @@ -0,0 +1,7 @@ +CTEST_BUILD_NAME +---------------- + +.. versionadded:: 3.1 + +Specify the CTest ``BuildName`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_BZR_COMMAND.rst b/Help/variable/CTEST_BZR_COMMAND.rst new file mode 100644 index 0000000..0c05d1a --- /dev/null +++ b/Help/variable/CTEST_BZR_COMMAND.rst @@ -0,0 +1,7 @@ +CTEST_BZR_COMMAND +----------------- + +.. versionadded:: 3.1 + +Specify the CTest ``BZRCommand`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_BZR_UPDATE_OPTIONS.rst b/Help/variable/CTEST_BZR_UPDATE_OPTIONS.rst new file mode 100644 index 0000000..4dd5e5b --- /dev/null +++ b/Help/variable/CTEST_BZR_UPDATE_OPTIONS.rst @@ -0,0 +1,7 @@ +CTEST_BZR_UPDATE_OPTIONS +------------------------ + +.. versionadded:: 3.1 + +Specify the CTest ``BZRUpdateOptions`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_CHANGE_ID.rst b/Help/variable/CTEST_CHANGE_ID.rst new file mode 100644 index 0000000..a6d15f7 --- /dev/null +++ b/Help/variable/CTEST_CHANGE_ID.rst @@ -0,0 +1,11 @@ +CTEST_CHANGE_ID +--------------- + +.. versionadded:: 3.4 + +Specify the CTest ``ChangeId`` setting +in a :manual:`ctest(1)` dashboard client script. + +This setting allows CTest to pass arbitrary information about this +build up to CDash. One use of this feature is to allow CDash to +post comments on your pull request if anything goes wrong with your build. diff --git a/Help/variable/CTEST_CHECKOUT_COMMAND.rst b/Help/variable/CTEST_CHECKOUT_COMMAND.rst new file mode 100644 index 0000000..852c28e --- /dev/null +++ b/Help/variable/CTEST_CHECKOUT_COMMAND.rst @@ -0,0 +1,7 @@ +CTEST_CHECKOUT_COMMAND +---------------------- + +.. versionadded:: 3.1 + +Tell the :command:`ctest_start` command how to checkout or initialize +the source directory in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_CONFIGURATION_TYPE.rst b/Help/variable/CTEST_CONFIGURATION_TYPE.rst new file mode 100644 index 0000000..392845e --- /dev/null +++ b/Help/variable/CTEST_CONFIGURATION_TYPE.rst @@ -0,0 +1,10 @@ +CTEST_CONFIGURATION_TYPE +------------------------ + +.. versionadded:: 3.1 + +Specify the CTest ``DefaultCTestConfigurationType`` setting +in a :manual:`ctest(1)` dashboard client script. + +If the configuration type is set via ``-C <cfg>`` from the command line +then this variable is populated accordingly. diff --git a/Help/variable/CTEST_CONFIGURE_COMMAND.rst b/Help/variable/CTEST_CONFIGURE_COMMAND.rst new file mode 100644 index 0000000..992ef47 --- /dev/null +++ b/Help/variable/CTEST_CONFIGURE_COMMAND.rst @@ -0,0 +1,7 @@ +CTEST_CONFIGURE_COMMAND +----------------------- + +.. versionadded:: 3.1 + +Specify the CTest ``ConfigureCommand`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_COVERAGE_COMMAND.rst b/Help/variable/CTEST_COVERAGE_COMMAND.rst new file mode 100644 index 0000000..f5425cb --- /dev/null +++ b/Help/variable/CTEST_COVERAGE_COMMAND.rst @@ -0,0 +1,62 @@ +CTEST_COVERAGE_COMMAND +---------------------- + +.. versionadded:: 3.1 + +Specify the CTest ``CoverageCommand`` setting +in a :manual:`ctest(1)` dashboard client script. + +Cobertura +''''''''' + +Using `Cobertura`_ as the coverage generation within your multi-module +Java project can generate a series of XML files. + +The Cobertura Coverage parser expects to read the coverage data from a +single XML file which contains the coverage data for all modules. +Cobertura has a program with the ability to merge given ``cobertura.ser`` files +and then another program to generate a combined XML file from the previous +merged file. For command line testing, this can be done by hand prior to +CTest looking for the coverage files. For script builds, +set the ``CTEST_COVERAGE_COMMAND`` variable to point to a file which will +perform these same steps, such as a ``.sh`` or ``.bat`` file. + +.. code-block:: cmake + + set(CTEST_COVERAGE_COMMAND .../run-coverage-and-consolidate.sh) + +where the ``run-coverage-and-consolidate.sh`` script is perhaps created by +the :command:`configure_file` command and might contain the following code: + +.. code-block:: bash + + #!/usr/bin/env bash + CoberturaFiles="$(find "/path/to/source" -name "cobertura.ser")" + SourceDirs="$(find "/path/to/source" -name "java" -type d)" + cobertura-merge --datafile coberturamerge.ser $CoberturaFiles + cobertura-report --datafile coberturamerge.ser --destination . \ + --format xml $SourceDirs + +The script uses ``find`` to capture the paths to all of the ``cobertura.ser`` +files found below the project's source directory. It keeps the list of files +and supplies it as an argument to the ``cobertura-merge`` program. The +``--datafile`` argument signifies where the result of the merge will be kept. + +The combined ``coberturamerge.ser`` file is then used to generate the XML report +using the ``cobertura-report`` program. The call to the cobertura-report +program requires some named arguments. + +``--datafila`` + path to the merged ``.ser`` file + +``--destination`` + path to put the output files(s) + +``--format`` + file format to write output in: xml or html + +The rest of the supplied arguments consist of the full paths to the +``/src/main/java`` directories of each module within the source tree. These +directories are needed and should not be forgotten. + +.. _`Cobertura`: http://cobertura.github.io/cobertura/ diff --git a/Help/variable/CTEST_COVERAGE_EXTRA_FLAGS.rst b/Help/variable/CTEST_COVERAGE_EXTRA_FLAGS.rst new file mode 100644 index 0000000..39d9b5d --- /dev/null +++ b/Help/variable/CTEST_COVERAGE_EXTRA_FLAGS.rst @@ -0,0 +1,7 @@ +CTEST_COVERAGE_EXTRA_FLAGS +-------------------------- + +.. versionadded:: 3.1 + +Specify the CTest ``CoverageExtraFlags`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_CURL_OPTIONS.rst b/Help/variable/CTEST_CURL_OPTIONS.rst new file mode 100644 index 0000000..14af4e4 --- /dev/null +++ b/Help/variable/CTEST_CURL_OPTIONS.rst @@ -0,0 +1,7 @@ +CTEST_CURL_OPTIONS +------------------ + +.. versionadded:: 3.1 + +Specify the CTest ``CurlOptions`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_CUSTOM_COVERAGE_EXCLUDE.rst b/Help/variable/CTEST_CUSTOM_COVERAGE_EXCLUDE.rst new file mode 100644 index 0000000..d5893c9 --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_COVERAGE_EXCLUDE.rst @@ -0,0 +1,7 @@ +CTEST_CUSTOM_COVERAGE_EXCLUDE +----------------------------- + +A list of regular expressions which will be used to exclude files by their +path from coverage output by the :command:`ctest_coverage` command. + +.. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_CUSTOM_ERROR_EXCEPTION.rst b/Help/variable/CTEST_CUSTOM_ERROR_EXCEPTION.rst new file mode 100644 index 0000000..cd65ae3 --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_ERROR_EXCEPTION.rst @@ -0,0 +1,7 @@ +CTEST_CUSTOM_ERROR_EXCEPTION +---------------------------- + +A list of regular expressions which will be used to exclude when detecting +error messages in build outputs by the :command:`ctest_test` command. + +.. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_CUSTOM_ERROR_MATCH.rst b/Help/variable/CTEST_CUSTOM_ERROR_MATCH.rst new file mode 100644 index 0000000..558f5e5 --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_ERROR_MATCH.rst @@ -0,0 +1,7 @@ +CTEST_CUSTOM_ERROR_MATCH +------------------------ + +A list of regular expressions which will be used to detect error messages in +build outputs by the :command:`ctest_test` command. + +.. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_CUSTOM_ERROR_POST_CONTEXT.rst b/Help/variable/CTEST_CUSTOM_ERROR_POST_CONTEXT.rst new file mode 100644 index 0000000..614859b --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_ERROR_POST_CONTEXT.rst @@ -0,0 +1,7 @@ +CTEST_CUSTOM_ERROR_POST_CONTEXT +------------------------------- + +The number of lines to include as context which follow an error message by the +:command:`ctest_test` command. The default is 10. + +.. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_CUSTOM_ERROR_PRE_CONTEXT.rst b/Help/variable/CTEST_CUSTOM_ERROR_PRE_CONTEXT.rst new file mode 100644 index 0000000..74dc47a --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_ERROR_PRE_CONTEXT.rst @@ -0,0 +1,7 @@ +CTEST_CUSTOM_ERROR_PRE_CONTEXT +------------------------------ + +The number of lines to include as context which precede an error message by +the :command:`ctest_test` command. The default is 10. + +.. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE.rst b/Help/variable/CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE.rst new file mode 100644 index 0000000..5aeae88 --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE.rst @@ -0,0 +1,8 @@ +CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE +-------------------------------------------- + +When saving a failing test's output, this is the maximum size, in bytes, that +will be collected by the :command:`ctest_test` command. Defaults to 307200 +(300 KiB). + +.. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_CUSTOM_MAXIMUM_NUMBER_OF_ERRORS.rst b/Help/variable/CTEST_CUSTOM_MAXIMUM_NUMBER_OF_ERRORS.rst new file mode 100644 index 0000000..920cb04 --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_MAXIMUM_NUMBER_OF_ERRORS.rst @@ -0,0 +1,8 @@ +CTEST_CUSTOM_MAXIMUM_NUMBER_OF_ERRORS +------------------------------------- + +The maximum number of errors in a single build step which will be detected. +After this, the :command:`ctest_test` command will truncate the output. +Defaults to 50. + +.. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_CUSTOM_MAXIMUM_NUMBER_OF_WARNINGS.rst b/Help/variable/CTEST_CUSTOM_MAXIMUM_NUMBER_OF_WARNINGS.rst new file mode 100644 index 0000000..a1f1cc1 --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_MAXIMUM_NUMBER_OF_WARNINGS.rst @@ -0,0 +1,8 @@ +CTEST_CUSTOM_MAXIMUM_NUMBER_OF_WARNINGS +--------------------------------------- + +The maximum number of warnings in a single build step which will be detected. +After this, the :command:`ctest_test` command will truncate the output. +Defaults to 50. + +.. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE.rst b/Help/variable/CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE.rst new file mode 100644 index 0000000..1fbb8c5 --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE.rst @@ -0,0 +1,8 @@ +CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE +-------------------------------------------- + +When saving a passing test's output, this is the maximum size, in bytes, that +will be collected by the :command:`ctest_test` command. Defaults to 1024 +(1 KiB). + +.. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_CUSTOM_MEMCHECK_IGNORE.rst b/Help/variable/CTEST_CUSTOM_MEMCHECK_IGNORE.rst new file mode 100644 index 0000000..578576c --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_MEMCHECK_IGNORE.rst @@ -0,0 +1,7 @@ +CTEST_CUSTOM_MEMCHECK_IGNORE +---------------------------- + +A list of regular expressions to use to exclude tests during the +:command:`ctest_memcheck` command. + +.. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_CUSTOM_POST_MEMCHECK.rst b/Help/variable/CTEST_CUSTOM_POST_MEMCHECK.rst new file mode 100644 index 0000000..40291fe --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_POST_MEMCHECK.rst @@ -0,0 +1,6 @@ +CTEST_CUSTOM_POST_MEMCHECK +-------------------------- + +A list of commands to run at the end of the :command:`ctest_memcheck` command. + +.. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_CUSTOM_POST_TEST.rst b/Help/variable/CTEST_CUSTOM_POST_TEST.rst new file mode 100644 index 0000000..791292c --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_POST_TEST.rst @@ -0,0 +1,6 @@ +CTEST_CUSTOM_POST_TEST +---------------------- + +A list of commands to run at the end of the :command:`ctest_test` command. + +.. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_CUSTOM_PRE_MEMCHECK.rst b/Help/variable/CTEST_CUSTOM_PRE_MEMCHECK.rst new file mode 100644 index 0000000..00de8aa --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_PRE_MEMCHECK.rst @@ -0,0 +1,7 @@ +CTEST_CUSTOM_PRE_MEMCHECK +------------------------- + +A list of commands to run at the start of the :command:`ctest_memcheck` +command. + +.. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_CUSTOM_PRE_TEST.rst b/Help/variable/CTEST_CUSTOM_PRE_TEST.rst new file mode 100644 index 0000000..6af7152 --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_PRE_TEST.rst @@ -0,0 +1,6 @@ +CTEST_CUSTOM_PRE_TEST +---------------------- + +A list of commands to run at the start of the :command:`ctest_test` command. + +.. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_CUSTOM_TESTS_IGNORE.rst b/Help/variable/CTEST_CUSTOM_TESTS_IGNORE.rst new file mode 100644 index 0000000..57222ca --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_TESTS_IGNORE.rst @@ -0,0 +1,7 @@ +CTEST_CUSTOM_TESTS_IGNORE +------------------------- + +A list of regular expressions to use to exclude tests during the +:command:`ctest_test` command. + +.. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_CUSTOM_WARNING_EXCEPTION.rst b/Help/variable/CTEST_CUSTOM_WARNING_EXCEPTION.rst new file mode 100644 index 0000000..a03d473 --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_WARNING_EXCEPTION.rst @@ -0,0 +1,7 @@ +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_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 new file mode 100644 index 0000000..18aa6b3 --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_WARNING_MATCH.rst @@ -0,0 +1,7 @@ +CTEST_CUSTOM_WARNING_MATCH +-------------------------- + +A list of regular expressions which will be used to detect warning messages in +build outputs by the :command:`ctest_build` command. + +.. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_CUSTOM_XXX.txt b/Help/variable/CTEST_CUSTOM_XXX.txt new file mode 100644 index 0000000..02d1547 --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_XXX.txt @@ -0,0 +1,2 @@ +It is initialized by :manual:`ctest(1)`, but may be edited in a ``CTestCustom`` +file. See :command:`ctest_read_custom_files` documentation. diff --git a/Help/variable/CTEST_CVS_CHECKOUT.rst b/Help/variable/CTEST_CVS_CHECKOUT.rst new file mode 100644 index 0000000..32cf9eb --- /dev/null +++ b/Help/variable/CTEST_CVS_CHECKOUT.rst @@ -0,0 +1,6 @@ +CTEST_CVS_CHECKOUT +------------------ + +.. versionadded:: 3.1 + +Deprecated. Use :variable:`CTEST_CHECKOUT_COMMAND` instead. diff --git a/Help/variable/CTEST_CVS_COMMAND.rst b/Help/variable/CTEST_CVS_COMMAND.rst new file mode 100644 index 0000000..7932070 --- /dev/null +++ b/Help/variable/CTEST_CVS_COMMAND.rst @@ -0,0 +1,7 @@ +CTEST_CVS_COMMAND +----------------- + +.. versionadded:: 3.1 + +Specify the CTest ``CVSCommand`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_CVS_UPDATE_OPTIONS.rst b/Help/variable/CTEST_CVS_UPDATE_OPTIONS.rst new file mode 100644 index 0000000..359e708 --- /dev/null +++ b/Help/variable/CTEST_CVS_UPDATE_OPTIONS.rst @@ -0,0 +1,7 @@ +CTEST_CVS_UPDATE_OPTIONS +------------------------ + +.. versionadded:: 3.1 + +Specify the CTest ``CVSUpdateOptions`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_DROP_LOCATION.rst b/Help/variable/CTEST_DROP_LOCATION.rst new file mode 100644 index 0000000..f66793b --- /dev/null +++ b/Help/variable/CTEST_DROP_LOCATION.rst @@ -0,0 +1,7 @@ +CTEST_DROP_LOCATION +------------------- + +.. versionadded:: 3.1 + +Specify the CTest ``DropLocation`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_DROP_METHOD.rst b/Help/variable/CTEST_DROP_METHOD.rst new file mode 100644 index 0000000..3a84658 --- /dev/null +++ b/Help/variable/CTEST_DROP_METHOD.rst @@ -0,0 +1,7 @@ +CTEST_DROP_METHOD +----------------- + +.. versionadded:: 3.1 + +Specify the CTest ``DropMethod`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_DROP_SITE.rst b/Help/variable/CTEST_DROP_SITE.rst new file mode 100644 index 0000000..9c871e3 --- /dev/null +++ b/Help/variable/CTEST_DROP_SITE.rst @@ -0,0 +1,7 @@ +CTEST_DROP_SITE +--------------- + +.. versionadded:: 3.1 + +Specify the CTest ``DropSite`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_DROP_SITE_CDASH.rst b/Help/variable/CTEST_DROP_SITE_CDASH.rst new file mode 100644 index 0000000..dcdb286 --- /dev/null +++ b/Help/variable/CTEST_DROP_SITE_CDASH.rst @@ -0,0 +1,7 @@ +CTEST_DROP_SITE_CDASH +--------------------- + +.. versionadded:: 3.1 + +Specify the CTest ``IsCDash`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_DROP_SITE_PASSWORD.rst b/Help/variable/CTEST_DROP_SITE_PASSWORD.rst new file mode 100644 index 0000000..8259651 --- /dev/null +++ b/Help/variable/CTEST_DROP_SITE_PASSWORD.rst @@ -0,0 +1,7 @@ +CTEST_DROP_SITE_PASSWORD +------------------------ + +.. versionadded:: 3.1 + +Specify the CTest ``DropSitePassword`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_DROP_SITE_USER.rst b/Help/variable/CTEST_DROP_SITE_USER.rst new file mode 100644 index 0000000..8d2e3a3 --- /dev/null +++ b/Help/variable/CTEST_DROP_SITE_USER.rst @@ -0,0 +1,7 @@ +CTEST_DROP_SITE_USER +-------------------- + +.. versionadded:: 3.1 + +Specify the CTest ``DropSiteUser`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_EXTRA_COVERAGE_GLOB.rst b/Help/variable/CTEST_EXTRA_COVERAGE_GLOB.rst new file mode 100644 index 0000000..1d7e8d4 --- /dev/null +++ b/Help/variable/CTEST_EXTRA_COVERAGE_GLOB.rst @@ -0,0 +1,9 @@ +CTEST_EXTRA_COVERAGE_GLOB +------------------------- + +.. versionadded:: 3.4 + +A list of regular expressions which will be used to find files which should be +covered by the :command:`ctest_coverage` command. + +.. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_GIT_COMMAND.rst b/Help/variable/CTEST_GIT_COMMAND.rst new file mode 100644 index 0000000..eb9b440 --- /dev/null +++ b/Help/variable/CTEST_GIT_COMMAND.rst @@ -0,0 +1,7 @@ +CTEST_GIT_COMMAND +----------------- + +.. versionadded:: 3.1 + +Specify the CTest ``GITCommand`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_GIT_INIT_SUBMODULES.rst b/Help/variable/CTEST_GIT_INIT_SUBMODULES.rst new file mode 100644 index 0000000..529bfc7 --- /dev/null +++ b/Help/variable/CTEST_GIT_INIT_SUBMODULES.rst @@ -0,0 +1,7 @@ +CTEST_GIT_INIT_SUBMODULES +------------------------- + +.. versionadded:: 3.6 + +Specify the CTest ``GITInitSubmodules`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_GIT_UPDATE_CUSTOM.rst b/Help/variable/CTEST_GIT_UPDATE_CUSTOM.rst new file mode 100644 index 0000000..82a8a6a --- /dev/null +++ b/Help/variable/CTEST_GIT_UPDATE_CUSTOM.rst @@ -0,0 +1,7 @@ +CTEST_GIT_UPDATE_CUSTOM +----------------------- + +.. versionadded:: 3.1 + +Specify the CTest ``GITUpdateCustom`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_GIT_UPDATE_OPTIONS.rst b/Help/variable/CTEST_GIT_UPDATE_OPTIONS.rst new file mode 100644 index 0000000..1568239 --- /dev/null +++ b/Help/variable/CTEST_GIT_UPDATE_OPTIONS.rst @@ -0,0 +1,7 @@ +CTEST_GIT_UPDATE_OPTIONS +------------------------ + +.. versionadded:: 3.1 + +Specify the CTest ``GITUpdateOptions`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_HG_COMMAND.rst b/Help/variable/CTEST_HG_COMMAND.rst new file mode 100644 index 0000000..3372fe4 --- /dev/null +++ b/Help/variable/CTEST_HG_COMMAND.rst @@ -0,0 +1,7 @@ +CTEST_HG_COMMAND +---------------- + +.. versionadded:: 3.1 + +Specify the CTest ``HGCommand`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_HG_UPDATE_OPTIONS.rst b/Help/variable/CTEST_HG_UPDATE_OPTIONS.rst new file mode 100644 index 0000000..85c6b03 --- /dev/null +++ b/Help/variable/CTEST_HG_UPDATE_OPTIONS.rst @@ -0,0 +1,7 @@ +CTEST_HG_UPDATE_OPTIONS +----------------------- + +.. versionadded:: 3.1 + +Specify the CTest ``HGUpdateOptions`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_LABELS_FOR_SUBPROJECTS.rst b/Help/variable/CTEST_LABELS_FOR_SUBPROJECTS.rst new file mode 100644 index 0000000..dd6d125 --- /dev/null +++ b/Help/variable/CTEST_LABELS_FOR_SUBPROJECTS.rst @@ -0,0 +1,7 @@ +CTEST_LABELS_FOR_SUBPROJECTS +---------------------------- + +.. versionadded:: 3.10 + +Specify the CTest ``LabelsForSubprojects`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_MEMORYCHECK_COMMAND.rst b/Help/variable/CTEST_MEMORYCHECK_COMMAND.rst new file mode 100644 index 0000000..25f1bd9 --- /dev/null +++ b/Help/variable/CTEST_MEMORYCHECK_COMMAND.rst @@ -0,0 +1,7 @@ +CTEST_MEMORYCHECK_COMMAND +------------------------- + +.. versionadded:: 3.1 + +Specify the CTest ``MemoryCheckCommand`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_MEMORYCHECK_COMMAND_OPTIONS.rst b/Help/variable/CTEST_MEMORYCHECK_COMMAND_OPTIONS.rst new file mode 100644 index 0000000..51830d5 --- /dev/null +++ b/Help/variable/CTEST_MEMORYCHECK_COMMAND_OPTIONS.rst @@ -0,0 +1,7 @@ +CTEST_MEMORYCHECK_COMMAND_OPTIONS +--------------------------------- + +.. versionadded:: 3.1 + +Specify the CTest ``MemoryCheckCommandOptions`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_MEMORYCHECK_SANITIZER_OPTIONS.rst b/Help/variable/CTEST_MEMORYCHECK_SANITIZER_OPTIONS.rst new file mode 100644 index 0000000..b6fee2e --- /dev/null +++ b/Help/variable/CTEST_MEMORYCHECK_SANITIZER_OPTIONS.rst @@ -0,0 +1,12 @@ +CTEST_MEMORYCHECK_SANITIZER_OPTIONS +----------------------------------- + +.. versionadded:: 3.1 + +Specify the CTest ``MemoryCheckSanitizerOptions`` setting +in a :manual:`ctest(1)` dashboard client script. + +CTest prepends correct sanitizer options ``*_OPTIONS`` +environment variable to executed command. CTests adds +its own ``log_path`` to sanitizer options, don't provide your +own ``log_path``. diff --git a/Help/variable/CTEST_MEMORYCHECK_SUPPRESSIONS_FILE.rst b/Help/variable/CTEST_MEMORYCHECK_SUPPRESSIONS_FILE.rst new file mode 100644 index 0000000..a61a3ef --- /dev/null +++ b/Help/variable/CTEST_MEMORYCHECK_SUPPRESSIONS_FILE.rst @@ -0,0 +1,7 @@ +CTEST_MEMORYCHECK_SUPPRESSIONS_FILE +----------------------------------- + +.. versionadded:: 3.1 + +Specify the CTest ``MemoryCheckSuppressionFile`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_MEMORYCHECK_TYPE.rst b/Help/variable/CTEST_MEMORYCHECK_TYPE.rst new file mode 100644 index 0000000..80353a4 --- /dev/null +++ b/Help/variable/CTEST_MEMORYCHECK_TYPE.rst @@ -0,0 +1,10 @@ +CTEST_MEMORYCHECK_TYPE +---------------------- + +.. versionadded:: 3.1 + +Specify the CTest ``MemoryCheckType`` setting +in a :manual:`ctest(1)` dashboard client script. +Valid values are ``Valgrind``, ``Purify``, ``BoundsChecker``, ``DrMemory``, +``CudaSanitizer``, ``ThreadSanitizer``, ``AddressSanitizer``, ``LeakSanitizer``, +``MemorySanitizer`` and ``UndefinedBehaviorSanitizer``. diff --git a/Help/variable/CTEST_NIGHTLY_START_TIME.rst b/Help/variable/CTEST_NIGHTLY_START_TIME.rst new file mode 100644 index 0000000..2d707d5 --- /dev/null +++ b/Help/variable/CTEST_NIGHTLY_START_TIME.rst @@ -0,0 +1,11 @@ +CTEST_NIGHTLY_START_TIME +------------------------ + +.. versionadded:: 3.1 + +Specify the CTest ``NightlyStartTime`` setting in a :manual:`ctest(1)` +dashboard client script. + +Note that this variable must always be set for a nightly build in a +dashboard script. It is needed so that nightly builds can be properly grouped +together in CDash. diff --git a/Help/variable/CTEST_P4_CLIENT.rst b/Help/variable/CTEST_P4_CLIENT.rst new file mode 100644 index 0000000..0778c5b --- /dev/null +++ b/Help/variable/CTEST_P4_CLIENT.rst @@ -0,0 +1,7 @@ +CTEST_P4_CLIENT +--------------- + +.. versionadded:: 3.1 + +Specify the CTest ``P4Client`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_P4_COMMAND.rst b/Help/variable/CTEST_P4_COMMAND.rst new file mode 100644 index 0000000..5cc2a81 --- /dev/null +++ b/Help/variable/CTEST_P4_COMMAND.rst @@ -0,0 +1,7 @@ +CTEST_P4_COMMAND +---------------- + +.. versionadded:: 3.1 + +Specify the CTest ``P4Command`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_P4_OPTIONS.rst b/Help/variable/CTEST_P4_OPTIONS.rst new file mode 100644 index 0000000..01b6534 --- /dev/null +++ b/Help/variable/CTEST_P4_OPTIONS.rst @@ -0,0 +1,7 @@ +CTEST_P4_OPTIONS +---------------- + +.. versionadded:: 3.1 + +Specify the CTest ``P4Options`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_P4_UPDATE_OPTIONS.rst b/Help/variable/CTEST_P4_UPDATE_OPTIONS.rst new file mode 100644 index 0000000..365aa3f --- /dev/null +++ b/Help/variable/CTEST_P4_UPDATE_OPTIONS.rst @@ -0,0 +1,7 @@ +CTEST_P4_UPDATE_OPTIONS +----------------------- + +.. versionadded:: 3.1 + +Specify the CTest ``P4UpdateOptions`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_RESOURCE_SPEC_FILE.rst b/Help/variable/CTEST_RESOURCE_SPEC_FILE.rst new file mode 100644 index 0000000..8e9bf01 --- /dev/null +++ b/Help/variable/CTEST_RESOURCE_SPEC_FILE.rst @@ -0,0 +1,12 @@ +CTEST_RESOURCE_SPEC_FILE +------------------------ + +.. versionadded:: 3.18 + +Specify the CTest ``ResourceSpecFile`` setting in a :manual:`ctest(1)` +dashboard client script. + +This can also be used to specify the resource spec file from a CMake build. If +no ``RESOURCE_SPEC_FILE`` is passed to :command:`ctest_test`, and +``CTEST_RESOURCE_SPEC_FILE`` is not specified in the dashboard script, the +value of this variable from the build is used. diff --git a/Help/variable/CTEST_RUN_CURRENT_SCRIPT.rst b/Help/variable/CTEST_RUN_CURRENT_SCRIPT.rst new file mode 100644 index 0000000..32c85ad --- /dev/null +++ b/Help/variable/CTEST_RUN_CURRENT_SCRIPT.rst @@ -0,0 +1,7 @@ +CTEST_RUN_CURRENT_SCRIPT +------------------------ + +.. versionadded:: 3.11 + +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 new file mode 100644 index 0000000..155b058 --- /dev/null +++ b/Help/variable/CTEST_SCP_COMMAND.rst @@ -0,0 +1,6 @@ +CTEST_SCP_COMMAND +----------------- + +.. versionadded:: 3.1 + +Legacy option. Not used. diff --git a/Help/variable/CTEST_SITE.rst b/Help/variable/CTEST_SITE.rst new file mode 100644 index 0000000..526e6ed --- /dev/null +++ b/Help/variable/CTEST_SITE.rst @@ -0,0 +1,7 @@ +CTEST_SITE +---------- + +.. versionadded:: 3.1 + +Specify the CTest ``Site`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_SOURCE_DIRECTORY.rst b/Help/variable/CTEST_SOURCE_DIRECTORY.rst new file mode 100644 index 0000000..4c6ac54 --- /dev/null +++ b/Help/variable/CTEST_SOURCE_DIRECTORY.rst @@ -0,0 +1,7 @@ +CTEST_SOURCE_DIRECTORY +---------------------- + +.. versionadded:: 3.1 + +Specify the CTest ``SourceDirectory`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_SUBMIT_URL.rst b/Help/variable/CTEST_SUBMIT_URL.rst new file mode 100644 index 0000000..b6e7f68 --- /dev/null +++ b/Help/variable/CTEST_SUBMIT_URL.rst @@ -0,0 +1,7 @@ +CTEST_SUBMIT_URL +---------------- + +.. versionadded:: 3.14 + +Specify the CTest ``SubmitURL`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_SVN_COMMAND.rst b/Help/variable/CTEST_SVN_COMMAND.rst new file mode 100644 index 0000000..e97acd0 --- /dev/null +++ b/Help/variable/CTEST_SVN_COMMAND.rst @@ -0,0 +1,7 @@ +CTEST_SVN_COMMAND +----------------- + +.. versionadded:: 3.1 + +Specify the CTest ``SVNCommand`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_SVN_OPTIONS.rst b/Help/variable/CTEST_SVN_OPTIONS.rst new file mode 100644 index 0000000..5326e20 --- /dev/null +++ b/Help/variable/CTEST_SVN_OPTIONS.rst @@ -0,0 +1,7 @@ +CTEST_SVN_OPTIONS +----------------- + +.. versionadded:: 3.1 + +Specify the CTest ``SVNOptions`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_SVN_UPDATE_OPTIONS.rst b/Help/variable/CTEST_SVN_UPDATE_OPTIONS.rst new file mode 100644 index 0000000..24e0bbf --- /dev/null +++ b/Help/variable/CTEST_SVN_UPDATE_OPTIONS.rst @@ -0,0 +1,7 @@ +CTEST_SVN_UPDATE_OPTIONS +------------------------ + +.. versionadded:: 3.1 + +Specify the CTest ``SVNUpdateOptions`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_TEST_LOAD.rst b/Help/variable/CTEST_TEST_LOAD.rst new file mode 100644 index 0000000..b6a9d62 --- /dev/null +++ b/Help/variable/CTEST_TEST_LOAD.rst @@ -0,0 +1,9 @@ +CTEST_TEST_LOAD +--------------- + +.. versionadded:: 3.4 + +Specify the ``TestLoad`` setting in the :ref:`CTest Test Step` +of a :manual:`ctest(1)` dashboard client script. This sets the +default value for the ``TEST_LOAD`` option of the :command:`ctest_test` +command. diff --git a/Help/variable/CTEST_TEST_TIMEOUT.rst b/Help/variable/CTEST_TEST_TIMEOUT.rst new file mode 100644 index 0000000..61d9191 --- /dev/null +++ b/Help/variable/CTEST_TEST_TIMEOUT.rst @@ -0,0 +1,7 @@ +CTEST_TEST_TIMEOUT +------------------ + +.. versionadded:: 3.1 + +Specify the CTest ``TimeOut`` 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 new file mode 100644 index 0000000..6abb852 --- /dev/null +++ b/Help/variable/CTEST_TRIGGER_SITE.rst @@ -0,0 +1,6 @@ +CTEST_TRIGGER_SITE +------------------ + +.. versionadded:: 3.1 + +Legacy option. Not used. diff --git a/Help/variable/CTEST_UPDATE_COMMAND.rst b/Help/variable/CTEST_UPDATE_COMMAND.rst new file mode 100644 index 0000000..c4ed645 --- /dev/null +++ b/Help/variable/CTEST_UPDATE_COMMAND.rst @@ -0,0 +1,7 @@ +CTEST_UPDATE_COMMAND +-------------------- + +.. versionadded:: 3.1 + +Specify the CTest ``UpdateCommand`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_UPDATE_OPTIONS.rst b/Help/variable/CTEST_UPDATE_OPTIONS.rst new file mode 100644 index 0000000..96c4b6c --- /dev/null +++ b/Help/variable/CTEST_UPDATE_OPTIONS.rst @@ -0,0 +1,7 @@ +CTEST_UPDATE_OPTIONS +-------------------- + +.. versionadded:: 3.1 + +Specify the CTest ``UpdateOptions`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_UPDATE_VERSION_ONLY.rst b/Help/variable/CTEST_UPDATE_VERSION_ONLY.rst new file mode 100644 index 0000000..f7c863c --- /dev/null +++ b/Help/variable/CTEST_UPDATE_VERSION_ONLY.rst @@ -0,0 +1,7 @@ +CTEST_UPDATE_VERSION_ONLY +------------------------- + +.. versionadded:: 3.1 + +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 0000000..87918cb --- /dev/null +++ b/Help/variable/CTEST_UPDATE_VERSION_OVERRIDE.rst @@ -0,0 +1,7 @@ +CTEST_UPDATE_VERSION_OVERRIDE +----------------------------- + +.. versionadded:: 3.15 + +Specify the CTest :ref:`UpdateVersionOverride <UpdateVersionOverride>` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_USE_LAUNCHERS.rst b/Help/variable/CTEST_USE_LAUNCHERS.rst new file mode 100644 index 0000000..728cdc5 --- /dev/null +++ b/Help/variable/CTEST_USE_LAUNCHERS.rst @@ -0,0 +1,7 @@ +CTEST_USE_LAUNCHERS +------------------- + +.. versionadded:: 3.1 + +Specify the CTest ``UseLaunchers`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CYGWIN.rst b/Help/variable/CYGWIN.rst new file mode 100644 index 0000000..0039e07 --- /dev/null +++ b/Help/variable/CYGWIN.rst @@ -0,0 +1,6 @@ +CYGWIN +------ + +``True`` for Cygwin. + +Set to ``true`` when using Cygwin. diff --git a/Help/variable/ENV.rst b/Help/variable/ENV.rst new file mode 100644 index 0000000..2b43934 --- /dev/null +++ b/Help/variable/ENV.rst @@ -0,0 +1,12 @@ +ENV +--- + +Operator to read environment variables. + +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/EXECUTABLE_OUTPUT_PATH.rst b/Help/variable/EXECUTABLE_OUTPUT_PATH.rst new file mode 100644 index 0000000..26d3e92 --- /dev/null +++ b/Help/variable/EXECUTABLE_OUTPUT_PATH.rst @@ -0,0 +1,8 @@ +EXECUTABLE_OUTPUT_PATH +---------------------- + +Old executable location variable. + +The target property :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` supercedes this +variable for a target if it is set. Executable targets are otherwise placed in +this directory. diff --git a/Help/variable/GHS-MULTI.rst b/Help/variable/GHS-MULTI.rst new file mode 100644 index 0000000..bb139af --- /dev/null +++ b/Help/variable/GHS-MULTI.rst @@ -0,0 +1,6 @@ +GHS-MULTI +--------- + +.. versionadded:: 3.3 + +``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 0000000..b27be55 --- /dev/null +++ b/Help/variable/IOS.rst @@ -0,0 +1,6 @@ +IOS +--- + +.. versionadded:: 3.14 + +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 new file mode 100644 index 0000000..bb4328f --- /dev/null +++ b/Help/variable/LIBRARY_OUTPUT_PATH.rst @@ -0,0 +1,9 @@ +LIBRARY_OUTPUT_PATH +------------------- + +Old library location variable. + +The target properties :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY`, +:prop_tgt:`LIBRARY_OUTPUT_DIRECTORY`, and :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` +supersede this variable for a target if they are set. Library targets are +otherwise placed in this directory. diff --git a/Help/variable/MINGW.rst b/Help/variable/MINGW.rst new file mode 100644 index 0000000..27c56ea --- /dev/null +++ b/Help/variable/MINGW.rst @@ -0,0 +1,8 @@ +MINGW +----- + +.. versionadded:: 3.2 + +``True`` when using MinGW + +Set to ``true`` when the compiler is some version of MinGW. diff --git a/Help/variable/MSVC.rst b/Help/variable/MSVC.rst new file mode 100644 index 0000000..a2dbc2e --- /dev/null +++ b/Help/variable/MSVC.rst @@ -0,0 +1,7 @@ +MSVC +---- + +Set to ``true`` when the compiler is some version of Microsoft Visual C++ +or another compiler simulating the Visual C++ ``cl`` command-line syntax. + +See also the :variable:`MSVC_VERSION` variable. diff --git a/Help/variable/MSVC10.rst b/Help/variable/MSVC10.rst new file mode 100644 index 0000000..55c6337 --- /dev/null +++ b/Help/variable/MSVC10.rst @@ -0,0 +1,7 @@ +MSVC10 +------ + +Discouraged. Use the :variable:`MSVC_VERSION` variable instead. + +``True`` when using the Microsoft Visual Studio ``v100`` toolset +(``cl`` version 16) or another compiler that simulates it. diff --git a/Help/variable/MSVC11.rst b/Help/variable/MSVC11.rst new file mode 100644 index 0000000..17943dc --- /dev/null +++ b/Help/variable/MSVC11.rst @@ -0,0 +1,7 @@ +MSVC11 +------ + +Discouraged. Use the :variable:`MSVC_VERSION` variable instead. + +``True`` when using the Microsoft Visual Studio ``v110`` toolset +(``cl`` version 17) or another compiler that simulates it. diff --git a/Help/variable/MSVC12.rst b/Help/variable/MSVC12.rst new file mode 100644 index 0000000..a524fab --- /dev/null +++ b/Help/variable/MSVC12.rst @@ -0,0 +1,7 @@ +MSVC12 +------ + +Discouraged. Use the :variable:`MSVC_VERSION` variable instead. + +``True`` when using the Microsoft Visual Studio ``v120`` toolset +(``cl`` version 18) or another compiler that simulates it. diff --git a/Help/variable/MSVC14.rst b/Help/variable/MSVC14.rst new file mode 100644 index 0000000..1eb5183 --- /dev/null +++ b/Help/variable/MSVC14.rst @@ -0,0 +1,9 @@ +MSVC14 +------ + +.. versionadded:: 3.1 + +Discouraged. Use the :variable:`MSVC_VERSION` variable instead. + +``True`` when using the Microsoft Visual Studio ``v140`` or ``v141`` +toolset (``cl`` version 19) or another compiler that simulates it. diff --git a/Help/variable/MSVC60.rst b/Help/variable/MSVC60.rst new file mode 100644 index 0000000..14164bf --- /dev/null +++ b/Help/variable/MSVC60.rst @@ -0,0 +1,8 @@ +MSVC60 +------ + +Discouraged. Use the :variable:`MSVC_VERSION` variable instead. + +``True`` when using Microsoft Visual C++ 6.0. + +Set to ``true`` when the compiler is version 6.0 of Microsoft Visual C++. diff --git a/Help/variable/MSVC70.rst b/Help/variable/MSVC70.rst new file mode 100644 index 0000000..ed3b0bb --- /dev/null +++ b/Help/variable/MSVC70.rst @@ -0,0 +1,8 @@ +MSVC70 +------ + +Discouraged. Use the :variable:`MSVC_VERSION` variable instead. + +``True`` when using Microsoft Visual C++ 7.0. + +Set to ``true`` when the compiler is version 7.0 of Microsoft Visual C++. diff --git a/Help/variable/MSVC71.rst b/Help/variable/MSVC71.rst new file mode 100644 index 0000000..0237592 --- /dev/null +++ b/Help/variable/MSVC71.rst @@ -0,0 +1,8 @@ +MSVC71 +------ + +Discouraged. Use the :variable:`MSVC_VERSION` variable instead. + +``True`` when using Microsoft Visual C++ 7.1. + +Set to ``true`` when the compiler is version 7.1 of Microsoft Visual C++. diff --git a/Help/variable/MSVC80.rst b/Help/variable/MSVC80.rst new file mode 100644 index 0000000..1533218 --- /dev/null +++ b/Help/variable/MSVC80.rst @@ -0,0 +1,7 @@ +MSVC80 +------ + +Discouraged. Use the :variable:`MSVC_VERSION` variable instead. + +``True`` when using the Microsoft Visual Studio ``v80`` toolset +(``cl`` version 14) or another compiler that simulates it. diff --git a/Help/variable/MSVC90.rst b/Help/variable/MSVC90.rst new file mode 100644 index 0000000..4981ecf --- /dev/null +++ b/Help/variable/MSVC90.rst @@ -0,0 +1,7 @@ +MSVC90 +------ + +Discouraged. Use the :variable:`MSVC_VERSION` variable instead. + +``True`` when using the Microsoft Visual Studio ``v90`` toolset +(``cl`` version 15) or another compiler that simulates it. diff --git a/Help/variable/MSVC_IDE.rst b/Help/variable/MSVC_IDE.rst new file mode 100644 index 0000000..18e9983 --- /dev/null +++ b/Help/variable/MSVC_IDE.rst @@ -0,0 +1,14 @@ +MSVC_IDE +-------- + +``True`` when using the Microsoft Visual C++ IDE. + +Set to ``true`` when the target platform is the Microsoft Visual C++ IDE, as +opposed to the command line compiler. + +.. note:: + + This variable is only available after compiler detection has been performed, + so it is not available to toolchain files or before the first + :command:`project` or :command:`enable_language` call which uses an + MSVC-like compiler. diff --git a/Help/variable/MSVC_TOOLSET_VERSION.rst b/Help/variable/MSVC_TOOLSET_VERSION.rst new file mode 100644 index 0000000..c642a9f --- /dev/null +++ b/Help/variable/MSVC_TOOLSET_VERSION.rst @@ -0,0 +1,24 @@ +MSVC_TOOLSET_VERSION +-------------------- + +.. versionadded:: 3.12 + +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 new file mode 100644 index 0000000..45df37f --- /dev/null +++ b/Help/variable/MSVC_VERSION.rst @@ -0,0 +1,24 @@ +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 (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 0000000..6be7681 --- /dev/null +++ b/Help/variable/MSYS.rst @@ -0,0 +1,6 @@ +MSYS +---- + +.. versionadded:: 3.14 + +``True`` when using the :generator:`MSYS Makefiles` generator. diff --git a/Help/variable/PROJECT-NAME_BINARY_DIR.rst b/Help/variable/PROJECT-NAME_BINARY_DIR.rst new file mode 100644 index 0000000..49bc558 --- /dev/null +++ b/Help/variable/PROJECT-NAME_BINARY_DIR.rst @@ -0,0 +1,8 @@ +<PROJECT-NAME>_BINARY_DIR +------------------------- + +Top level binary directory for the named project. + +A variable is created with the name used in the :command:`project` command, +and is the binary directory for the project. This can be useful when +:command:`add_subdirectory` is used to connect several projects. diff --git a/Help/variable/PROJECT-NAME_DESCRIPTION.rst b/Help/variable/PROJECT-NAME_DESCRIPTION.rst new file mode 100644 index 0000000..f372f5c --- /dev/null +++ b/Help/variable/PROJECT-NAME_DESCRIPTION.rst @@ -0,0 +1,7 @@ +<PROJECT-NAME>_DESCRIPTION +-------------------------- + +.. versionadded:: 3.12 + +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 0000000..4800b13 --- /dev/null +++ b/Help/variable/PROJECT-NAME_HOMEPAGE_URL.rst @@ -0,0 +1,7 @@ +<PROJECT-NAME>_HOMEPAGE_URL +--------------------------- + +.. versionadded:: 3.12 + +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-NAME_IS_TOP_LEVEL.rst b/Help/variable/PROJECT-NAME_IS_TOP_LEVEL.rst new file mode 100644 index 0000000..953e978 --- /dev/null +++ b/Help/variable/PROJECT-NAME_IS_TOP_LEVEL.rst @@ -0,0 +1,11 @@ +<PROJECT-NAME>_IS_TOP_LEVEL +--------------------------- + +.. versionadded:: 3.21 + +A boolean variable indicating whether the named project was called in a top +level ``CMakeLists.txt`` file. + +To obtain the value from the most recent call to :command:`project` in +the current directory scope or above, see the +:variable:`PROJECT_IS_TOP_LEVEL` variable. diff --git a/Help/variable/PROJECT-NAME_SOURCE_DIR.rst b/Help/variable/PROJECT-NAME_SOURCE_DIR.rst new file mode 100644 index 0000000..4df3e22 --- /dev/null +++ b/Help/variable/PROJECT-NAME_SOURCE_DIR.rst @@ -0,0 +1,8 @@ +<PROJECT-NAME>_SOURCE_DIR +------------------------- + +Top level source directory for the named project. + +A variable is created with the name used in the :command:`project` command, +and is the source directory for the project. This can be useful when +:command:`add_subdirectory` is used to connect several projects. diff --git a/Help/variable/PROJECT-NAME_VERSION.rst b/Help/variable/PROJECT-NAME_VERSION.rst new file mode 100644 index 0000000..0f6ed51 --- /dev/null +++ b/Help/variable/PROJECT-NAME_VERSION.rst @@ -0,0 +1,11 @@ +<PROJECT-NAME>_VERSION +---------------------- + +Value given to the ``VERSION`` option of the most recent call to the +:command:`project` command with project name ``<PROJECT-NAME>``, if any. + +See also the component-wise version variables +:variable:`<PROJECT-NAME>_VERSION_MAJOR`, +:variable:`<PROJECT-NAME>_VERSION_MINOR`, +:variable:`<PROJECT-NAME>_VERSION_PATCH`, and +:variable:`<PROJECT-NAME>_VERSION_TWEAK`. diff --git a/Help/variable/PROJECT-NAME_VERSION_MAJOR.rst b/Help/variable/PROJECT-NAME_VERSION_MAJOR.rst new file mode 100644 index 0000000..9e2d755 --- /dev/null +++ b/Help/variable/PROJECT-NAME_VERSION_MAJOR.rst @@ -0,0 +1,5 @@ +<PROJECT-NAME>_VERSION_MAJOR +---------------------------- + +First version number component of the :variable:`<PROJECT-NAME>_VERSION` +variable as set by the :command:`project` command. diff --git a/Help/variable/PROJECT-NAME_VERSION_MINOR.rst b/Help/variable/PROJECT-NAME_VERSION_MINOR.rst new file mode 100644 index 0000000..fa2cdab --- /dev/null +++ b/Help/variable/PROJECT-NAME_VERSION_MINOR.rst @@ -0,0 +1,5 @@ +<PROJECT-NAME>_VERSION_MINOR +---------------------------- + +Second version number component of the :variable:`<PROJECT-NAME>_VERSION` +variable as set by the :command:`project` command. diff --git a/Help/variable/PROJECT-NAME_VERSION_PATCH.rst b/Help/variable/PROJECT-NAME_VERSION_PATCH.rst new file mode 100644 index 0000000..85b5e6b --- /dev/null +++ b/Help/variable/PROJECT-NAME_VERSION_PATCH.rst @@ -0,0 +1,5 @@ +<PROJECT-NAME>_VERSION_PATCH +---------------------------- + +Third version number component of the :variable:`<PROJECT-NAME>_VERSION` +variable as set by the :command:`project` command. diff --git a/Help/variable/PROJECT-NAME_VERSION_TWEAK.rst b/Help/variable/PROJECT-NAME_VERSION_TWEAK.rst new file mode 100644 index 0000000..65c4044 --- /dev/null +++ b/Help/variable/PROJECT-NAME_VERSION_TWEAK.rst @@ -0,0 +1,5 @@ +<PROJECT-NAME>_VERSION_TWEAK +---------------------------- + +Fourth version number component of the :variable:`<PROJECT-NAME>_VERSION` +variable as set by the :command:`project` command. diff --git a/Help/variable/PROJECT_BINARY_DIR.rst b/Help/variable/PROJECT_BINARY_DIR.rst new file mode 100644 index 0000000..09e9ef2 --- /dev/null +++ b/Help/variable/PROJECT_BINARY_DIR.rst @@ -0,0 +1,6 @@ +PROJECT_BINARY_DIR +------------------ + +Full path to build directory for project. + +This is the binary directory of the most recent :command:`project` command. diff --git a/Help/variable/PROJECT_DESCRIPTION.rst b/Help/variable/PROJECT_DESCRIPTION.rst new file mode 100644 index 0000000..1fefcdc --- /dev/null +++ b/Help/variable/PROJECT_DESCRIPTION.rst @@ -0,0 +1,11 @@ +PROJECT_DESCRIPTION +------------------- + +.. versionadded:: 3.9 + +Short project description given to the 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 0000000..0d2c937 --- /dev/null +++ b/Help/variable/PROJECT_HOMEPAGE_URL.rst @@ -0,0 +1,11 @@ +PROJECT_HOMEPAGE_URL +-------------------- + +.. versionadded:: 3.12 + +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_IS_TOP_LEVEL.rst b/Help/variable/PROJECT_IS_TOP_LEVEL.rst new file mode 100644 index 0000000..e5eb6c1 --- /dev/null +++ b/Help/variable/PROJECT_IS_TOP_LEVEL.rst @@ -0,0 +1,21 @@ +PROJECT_IS_TOP_LEVEL +-------------------- + +.. versionadded:: 3.21 + +A boolean variable indicating whether :command:`project` was called in a top +level ``CMakeLists.txt`` file. + +Some modules should only be included as part of the top level +``CMakeLists.txt`` file to not cause unintended side effects in the build +tree, and this variable can be used to conditionally execute such code. For +example, consider the :module:`CTest` module, which creates targets and +options: + +.. code-block:: cmake + + project(MyProject) + ... + if(PROJECT_IS_TOP_LEVEL) + include(CTest) + endif() diff --git a/Help/variable/PROJECT_NAME.rst b/Help/variable/PROJECT_NAME.rst new file mode 100644 index 0000000..672680a --- /dev/null +++ b/Help/variable/PROJECT_NAME.rst @@ -0,0 +1,8 @@ +PROJECT_NAME +------------ + +Name of the project given to the 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/PROJECT_SOURCE_DIR.rst b/Help/variable/PROJECT_SOURCE_DIR.rst new file mode 100644 index 0000000..b4601c2 --- /dev/null +++ b/Help/variable/PROJECT_SOURCE_DIR.rst @@ -0,0 +1,8 @@ +PROJECT_SOURCE_DIR +------------------ + +This is the source directory of the last call to the +:command:`project` command made in the current directory scope or one +of its parents. Note, it is not affected by calls to +:command:`project` made within a child directory scope (i.e. from +within a call to :command:`add_subdirectory` from the current scope). diff --git a/Help/variable/PROJECT_VERSION.rst b/Help/variable/PROJECT_VERSION.rst new file mode 100644 index 0000000..234558d --- /dev/null +++ b/Help/variable/PROJECT_VERSION.rst @@ -0,0 +1,11 @@ +PROJECT_VERSION +--------------- + +Value given to the ``VERSION`` option of the most recent call to the +:command:`project` command, if any. + +See also the component-wise version variables +:variable:`PROJECT_VERSION_MAJOR`, +:variable:`PROJECT_VERSION_MINOR`, +:variable:`PROJECT_VERSION_PATCH`, and +:variable:`PROJECT_VERSION_TWEAK`. diff --git a/Help/variable/PROJECT_VERSION_MAJOR.rst b/Help/variable/PROJECT_VERSION_MAJOR.rst new file mode 100644 index 0000000..4b6072c --- /dev/null +++ b/Help/variable/PROJECT_VERSION_MAJOR.rst @@ -0,0 +1,5 @@ +PROJECT_VERSION_MAJOR +--------------------- + +First version number component of the :variable:`PROJECT_VERSION` +variable as set by the :command:`project` command. diff --git a/Help/variable/PROJECT_VERSION_MINOR.rst b/Help/variable/PROJECT_VERSION_MINOR.rst new file mode 100644 index 0000000..5f31220 --- /dev/null +++ b/Help/variable/PROJECT_VERSION_MINOR.rst @@ -0,0 +1,5 @@ +PROJECT_VERSION_MINOR +--------------------- + +Second version number component of the :variable:`PROJECT_VERSION` +variable as set by the :command:`project` command. diff --git a/Help/variable/PROJECT_VERSION_PATCH.rst b/Help/variable/PROJECT_VERSION_PATCH.rst new file mode 100644 index 0000000..ac72ec0 --- /dev/null +++ b/Help/variable/PROJECT_VERSION_PATCH.rst @@ -0,0 +1,5 @@ +PROJECT_VERSION_PATCH +--------------------- + +Third version number component of the :variable:`PROJECT_VERSION` +variable as set by the :command:`project` command. diff --git a/Help/variable/PROJECT_VERSION_TWEAK.rst b/Help/variable/PROJECT_VERSION_TWEAK.rst new file mode 100644 index 0000000..d7f96d6 --- /dev/null +++ b/Help/variable/PROJECT_VERSION_TWEAK.rst @@ -0,0 +1,5 @@ +PROJECT_VERSION_TWEAK +--------------------- + +Fourth version number component of the :variable:`PROJECT_VERSION` +variable as set by the :command:`project` command. diff --git a/Help/variable/PackageName_ROOT.rst b/Help/variable/PackageName_ROOT.rst new file mode 100644 index 0000000..98ba20e --- /dev/null +++ b/Help/variable/PackageName_ROOT.rst @@ -0,0 +1,16 @@ +<PackageName>_ROOT +------------------ + +.. versionadded:: 3.12 + +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 new file mode 100644 index 0000000..49d8668 --- /dev/null +++ b/Help/variable/UNIX.rst @@ -0,0 +1,7 @@ +UNIX +---- + +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 new file mode 100644 index 0000000..78ab772 --- /dev/null +++ b/Help/variable/WIN32.rst @@ -0,0 +1,4 @@ +WIN32 +----- + +Set to ``True`` when the target system is Windows, including Win64. diff --git a/Help/variable/WINCE.rst b/Help/variable/WINCE.rst new file mode 100644 index 0000000..4dca297 --- /dev/null +++ b/Help/variable/WINCE.rst @@ -0,0 +1,7 @@ +WINCE +----- + +.. versionadded:: 3.1 + +True when the :variable:`CMAKE_SYSTEM_NAME` variable is set +to ``WindowsCE``. diff --git a/Help/variable/WINDOWS_PHONE.rst b/Help/variable/WINDOWS_PHONE.rst new file mode 100644 index 0000000..bf7099d --- /dev/null +++ b/Help/variable/WINDOWS_PHONE.rst @@ -0,0 +1,7 @@ +WINDOWS_PHONE +------------- + +.. versionadded:: 3.1 + +True when the :variable:`CMAKE_SYSTEM_NAME` variable is set +to ``WindowsPhone``. diff --git a/Help/variable/WINDOWS_STORE.rst b/Help/variable/WINDOWS_STORE.rst new file mode 100644 index 0000000..13831c2 --- /dev/null +++ b/Help/variable/WINDOWS_STORE.rst @@ -0,0 +1,7 @@ +WINDOWS_STORE +------------- + +.. versionadded:: 3.1 + +True when the :variable:`CMAKE_SYSTEM_NAME` variable is set +to ``WindowsStore``. diff --git a/Help/variable/XCODE.rst b/Help/variable/XCODE.rst new file mode 100644 index 0000000..167ca86 --- /dev/null +++ b/Help/variable/XCODE.rst @@ -0,0 +1,6 @@ +XCODE +----- + +.. versionadded:: 3.7 + +``True`` when using :generator:`Xcode` generator. diff --git a/Help/variable/XCODE_VERSION.rst b/Help/variable/XCODE_VERSION.rst new file mode 100644 index 0000000..9caf19a --- /dev/null +++ b/Help/variable/XCODE_VERSION.rst @@ -0,0 +1,7 @@ +XCODE_VERSION +------------- + +Version of Xcode (:generator:`Xcode` generator only). + +Under the :generator:`Xcode` generator, this is the version of Xcode +as specified in ``Xcode.app/Contents/version.plist`` (such as ``3.1.2``). |
