diff options
Diffstat (limited to 'Help')
1534 files changed, 40753 insertions, 0 deletions
diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt new file mode 100644 index 0000000..73dbd57 --- /dev/null +++ b/Help/command/FIND_XXX.txt @@ -0,0 +1,145 @@ +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 path1 [path2 ... ENV var]] + [PATHS path1 [path2 ... ENV var]] + [PATH_SUFFIXES suffix1 [suffix2 ...]] + [DOC "cache documentation string"] + [NO_DEFAULT_PATH] + [NO_PACKAGE_ROOT_PATH] + [NO_CMAKE_PATH] + [NO_CMAKE_ENVIRONMENT_PATH] + [NO_SYSTEM_ENVIRONMENT_PATH] + [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``, and the search will be attempted again the +next time |FIND_XXX| is invoked with the same variable. + +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. + +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. If called from within a find module loaded by + :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, root paths from the parent's find module will be + searched after paths from the current module, + i.e. ``<CurrentPackage>_ROOT``, ``ENV{<CurrentPackage>_ROOT}``, + ``<ParentPackage>_ROOT``, ``ENV{<ParentPackage>_ROOT}``, etc. + This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed. + See policy :policy:`CMP0074`. + + * |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| + +2. Search paths specified in cmake-specific cache variables. + These are intended to be used on the command line with a ``-DVAR=value``. + The values are interpreted as :ref:`;-lists <CMake Language Lists>`. + This can be skipped if ``NO_CMAKE_PATH`` is passed. + + * |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. + + * |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 an argument. + + * |SYSTEM_ENVIRONMENT_PATH_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. + + * |CMAKE_SYSTEM_PREFIX_PATH_XXX| + * |CMAKE_SYSTEM_XXX_PATH| + * |CMAKE_SYSTEM_XXX_MAC_PATH| + +7. Search the paths specified by the PATHS option + or in the short-hand version of the command. + These are typically hard-coded guesses. + +.. |FIND_ARGS_XXX| replace:: <VAR> NAMES name + +On 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..76927be --- /dev/null +++ b/Help/command/LINK_OPTIONS_LINKER.txt @@ -0,0 +1,10 @@ +To pass options to the linker tool, each compiler driver has is own syntax. +The ``LINKER:`` prefix can be used to specify, in a portable way, options +to pass to the linker tool. The ``LINKER:`` prefix is replaced by the required +driver option and the rest of the option string defines linker arguments using +``,`` as separator. These arguments will be formatted according to the +:variable:`CMAKE_<LANG>_LINKER_WRAPPER_FLAG` and +:variable:`CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP` variables. + +For example, ``"LINKER:-z,defs"`` becomes ``-Xlinker -z -Xlinker defs`` for +``Clang`` and ``-Wl,-z,defs`` for ``GNU GCC``. diff --git a/Help/command/OPTIONS_SHELL.txt b/Help/command/OPTIONS_SHELL.txt new file mode 100644 index 0000000..530c012 --- /dev/null +++ b/Help/command/OPTIONS_SHELL.txt @@ -0,0 +1,9 @@ +The final set of compile or link options used for a target is constructed by +accumulating options from the current target and the usage requirements of +it dependencies. The set of options is de-duplicated to avoid repetition. +While beneficial for individual options, the de-duplication step can break +up option groups. For example, ``-D A -D B`` becomes ``-D A B``. One may +specify a group of options using shell-like quoting along with a ``SHELL:`` +prefix. The ``SHELL:`` prefix is dropped and the rest of the option string +is parsed using the :command:`separate_arguments` ``UNIX_COMMAND`` mode. +For example, ``"SHELL:-D A" "SHELL:-D B"`` becomes ``-D A -D B``. diff --git a/Help/command/add_compile_definitions.rst b/Help/command/add_compile_definitions.rst new file mode 100644 index 0000000..48815d4 --- /dev/null +++ b/Help/command/add_compile_definitions.rst @@ -0,0 +1,23 @@ +add_compile_definitions +----------------------- + +Adds preprocessor definitions to the compilation of source files. + +:: + + add_compile_definitions(<definition> ...) + +Adds preprocessor definitions to the compiler command line for targets in the +current directory and below (whether added before or after this command is +invoked). See documentation of the :prop_dir:`directory <COMPILE_DEFINITIONS>` +and :prop_tgt:`target <COMPILE_DEFINITIONS>` ``COMPILE_DEFINITIONS`` properties. + +Definitions are specified using the syntax ``VAR`` or ``VAR=value``. +Function-style definitions are not supported. CMake will automatically +escape the value correctly for the native build system (note that CMake +language syntax may require escapes to specify some values). + +Arguments to ``add_compile_definitions`` may use "generator expressions" with +the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` +manual for available expressions. See the :manual:`cmake-buildsystem(7)` +manual for more on defining buildsystem properties. diff --git a/Help/command/add_compile_options.rst b/Help/command/add_compile_options.rst new file mode 100644 index 0000000..350a1c0 --- /dev/null +++ b/Help/command/add_compile_options.rst @@ -0,0 +1,25 @@ +add_compile_options +------------------- + +Adds options to the compilation of source files. + +:: + + add_compile_options(<option> ...) + +Adds options to the compiler command line for targets in the current +directory and below that are added after this command is invoked. +See documentation of the :prop_dir:`directory <COMPILE_OPTIONS>` and +:prop_tgt:`target <COMPILE_OPTIONS>` ``COMPILE_OPTIONS`` properties. + +This command can be used to add any options, but alternative commands +exist to add preprocessor definitions (:command:`target_compile_definitions` +and :command:`add_compile_definitions`) or include directories +(:command:`target_include_directories` and :command:`include_directories`). + +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 diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst new file mode 100644 index 0000000..71fe494 --- /dev/null +++ b/Help/command/add_custom_command.rst @@ -0,0 +1,241 @@ +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:: + + 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] + [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. + The ``COMMENT``, ``MAIN_DEPENDENCY``, and ``WORKING_DIRECTORY`` + options are currently ignored when APPEND is given, but may be + used in the future. + +``BYPRODUCTS`` + 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 ``BYPRODUCTS`` option is ignored on non-Ninja generators + except to mark byproducts ``GENERATED``. + +``COMMAND`` + Specify the command-line(s) to execute at build time. + If more than one ``COMMAND`` is specified they will be executed in order, + 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 set, the + :prop_tgt:`CROSSCOMPILING_EMULATOR` executable target property will + also be prepended to the command to allow the executable to run on + the host. + (Use the ``TARGET_FILE`` + :manual:`generator expression <cmake-generator-expressions(7)>` to + reference an executable later in the command line.) + Additionally a target-level dependency will be added so that the + executable target will be built before any target using this custom + command. However this does NOT add a file-level dependency that + would cause the custom command to re-run whenever the executable is + recompiled. + + Arguments to ``COMMAND`` may use + :manual:`generator expressions <cmake-generator-expressions(7)>`. + References to target names in generator expressions imply target-level + dependencies, but NOT file-level dependencies. List target names with + the ``DEPENDS`` option to add file-level dependencies. + +``COMMENT`` + Display the given message before the commands are executed at + build time. + +``DEPENDS`` + Specify files on which the command depends. 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. + If ``DEPENDS`` is not specified the command will run whenever + the ``OUTPUT`` is missing; if the command does not actually + create the ``OUTPUT`` then the rule will always run. + If ``DEPENDS`` specifies any 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. + + Arguments to ``DEPENDS`` may use + :manual:`generator expressions <cmake-generator-expressions(7)>`. + +``COMMAND_EXPAND_LISTS`` + 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. + +``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. + +``USES_TERMINAL`` + 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. + + Arguments to ``WORKING_DIRECTORY`` may use + :manual:`generator expressions <cmake-generator-expressions(7)>`. + +``DEPFILE`` + Specify a ``.d`` depfile for the :generator:`Ninja` generator. + A ``.d`` file holds dependencies usually emitted by the custom + command itself. + Using ``DEPFILE`` with other generators than Ninja is an error. + +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. + +:: + + 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]) + +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. diff --git a/Help/command/add_custom_target.rst b/Help/command/add_custom_target.rst new file mode 100644 index 0000000..a6b2f77 --- /dev/null +++ b/Help/command/add_custom_target.rst @@ -0,0 +1,126 @@ +add_custom_target +----------------- + +Add a target with no output so it will always be built. + +:: + + add_custom_target(Name [ALL] [command1 [args1...]] + [COMMAND command2 [args2...] ...] + [DEPENDS depend depend depend ... ] + [BYPRODUCTS [files...]] + [WORKING_DIRECTORY dir] + [COMMENT comment] + [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`` + 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 ``BYPRODUCTS`` option is ignored on non-Ninja generators + except to mark byproducts ``GENERATED``. + +``COMMAND`` + Specify the command-line(s) to execute at build time. + If more than one ``COMMAND`` is specified they will be executed in order, + 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 set, the + :prop_tgt:`CROSSCOMPILING_EMULATOR` executable target property will + also be prepended to the command to allow the executable to run on + the host. + Additionally a target-level dependency will be added so that the + executable target will be built before this custom target. + + Arguments to ``COMMAND`` may use + :manual:`generator expressions <cmake-generator-expressions(7)>`. + References to target names in generator expressions imply target-level + dependencies. + + 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. + + Use the :command:`add_dependencies` command to add dependencies + on other targets. + +``COMMAND_EXPAND_LISTS`` + 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. + +``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`` + 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. + + Arguments to ``WORKING_DIRECTORY`` may use + :manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/command/add_definitions.rst b/Help/command/add_definitions.rst new file mode 100644 index 0000000..1da15a6 --- /dev/null +++ b/Help/command/add_definitions.rst @@ -0,0 +1,35 @@ +add_definitions +--------------- + +Adds -D define flags to the compilation of source files. + +:: + + add_definitions(-DFOO -DBAR ...) + +Adds definitions to the compiler command line for targets in the current +directory and below (whether added before or after this command is invoked). +This command can be used to add any flags, but it is intended to add +preprocessor definitions. + +.. 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..7a66143 --- /dev/null +++ b/Help/command/add_dependencies.rst @@ -0,0 +1,23 @@ +add_dependencies +---------------- + +Add a dependency between top-level targets. + +:: + + add_dependencies(<target> [<target-dependency>]...) + +Make 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. + +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..c7a30d7 --- /dev/null +++ b/Help/command/add_executable.rst @@ -0,0 +1,85 @@ +add_executable +-------------- + +Add an executable to the project using the specified source files. + +:: + + 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 source files can be omitted +here if they are added later using :command:`target_sources`.) The +``<name>`` corresponds to the logical target name and must be globally +unique within a project. The actual file name of the executable built is +constructed based on conventions of the native platform (such as +``<name>.exe`` or just ``<name>``). + +By default the executable file will be created in the build tree +directory corresponding to the source tree directory in which the +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. + +Source arguments to ``add_executable`` may use "generator expressions" with +the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` +manual for available expressions. See the :manual:`cmake-buildsystem(7)` +manual for more on defining buildsystem properties. + +See also :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. + +-------------------------------------------------------------------------- + +:: + + 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. + +-------------------------------------------------------------------------- + +:: + + 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 a non-``GLOBAL`` +:ref:`Imported Target <Imported Targets>` or an ``ALIAS``. +``ALIAS`` targets can be used as targets to read properties +from, executables for custom commands and custom targets. They can also be +tested for existence with the regular :command:`if(TARGET)` subcommand. +The ``<name>`` may not be used to modify properties of ``<target>``, that +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..c4c512c --- /dev/null +++ b/Help/command/add_library.rst @@ -0,0 +1,171 @@ +add_library +----------- + +.. only:: html + + .. contents:: + +Add a library to the project using the specified source files. + +Normal Libraries +^^^^^^^^^^^^^^^^ + +:: + + add_library(<name> [STATIC | SHARED | MODULE] + [EXCLUDE_FROM_ALL] + [source1] [source2 ...]) + +Adds a library target called ``<name>`` to be built from the source files +listed in the command invocation. (The source files can be omitted here +if they are added later using :command:`target_sources`.) The ``<name>`` +corresponds to the logical target name and must be globally unique within +a project. The actual file name of the library built is constructed based +on conventions of the native platform (such as ``lib<name>.a`` or +``<name>.lib``). + +``STATIC``, ``SHARED``, or ``MODULE`` may be given to specify the type of +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`` or ``STATIC`` library may be marked with the :prop_tgt:`FRAMEWORK` +target property to create an macOS Framework. + +If a library does not export any symbols, it must not be declared as a +``SHARED`` library. For example, a Windows resource DLL or a managed C++/CLI +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. + +Source arguments to ``add_library`` may use "generator expressions" with +the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` +manual for available expressions. See the :manual:`cmake-buildsystem(7)` +manual for more on defining buildsystem properties. + +See also :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 Libraries +^^^^^^^^^^^^^^^^^^ + +:: + + add_library(<name> <SHARED|STATIC|MODULE|OBJECT|UNKNOWN> IMPORTED + [GLOBAL]) + +An :ref:`IMPORTED library target <Imported Targets>` references a library +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`` libraries are useful for convenient +reference from commands like :command:`target_link_libraries`. Details +about the imported library are specified by setting properties whose names +begin in ``IMPORTED_`` and ``INTERFACE_``. The most important such +property is :prop_tgt:`IMPORTED_LOCATION` (and its per-configuration +variant :prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) which specifies the +location of the main library file on disk. Or, for object libraries, +:prop_tgt:`IMPORTED_OBJECTS` (and :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>`) +specifies the locations of object files on disk. +See documentation of the ``IMPORTED_*`` and ``INTERFACE_*`` properties +for more information. + +Object Libraries +^^^^^^^^^^^^^^^^ + +:: + + add_library(<name> OBJECT <src>...) + +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>``. + +Alias Libraries +^^^^^^^^^^^^^^^ + +:: + + 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 a non-``GLOBAL`` :ref:`Imported Target <Imported Targets>` or an +``ALIAS``. +``ALIAS`` targets can be used as linkable targets and as targets to +read properties from. They can also be tested for existence with the +regular :command:`if(TARGET)` subcommand. The ``<name>`` may not be used +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. + +Interface Libraries +^^^^^^^^^^^^^^^^^^^ + +:: + + add_library(<name> INTERFACE [IMPORTED [GLOBAL]]) + +Creates an :ref:`Interface Library <Interface Libraries>`. An ``INTERFACE`` +library target does not directly create build output, though it may +have properties set on it and it may be installed, exported and +imported. Typically the ``INTERFACE_*`` properties are populated on +the interface target using the commands: + +* :command:`set_property`, +* :command:`target_link_libraries(INTERFACE)`, +* :command:`target_link_options(INTERFACE)`, +* :command:`target_include_directories(INTERFACE)`, +* :command:`target_compile_options(INTERFACE)`, +* :command:`target_compile_definitions(INTERFACE)`, and +* :command:`target_sources(INTERFACE)`, + +and then it is used as an argument to :command:`target_link_libraries` +like any other target. + +An ``INTERFACE`` :ref:`Imported Target <Imported Targets>` may also be +created with this signature. An ``IMPORTED`` library target references a +library defined outside the project. 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`. diff --git a/Help/command/add_link_options.rst b/Help/command/add_link_options.rst new file mode 100644 index 0000000..551d440 --- /dev/null +++ b/Help/command/add_link_options.rst @@ -0,0 +1,26 @@ +add_link_options +---------------- + +Adds options to the link of shared library, module and executable targets. + +:: + + add_link_options(<option> ...) + +Adds options to the link step for targets in the current directory and below +that are added after this command is invoked. See documentation of the +:prop_dir:`directory <LINK_OPTIONS>` and +:prop_tgt:`target <LINK_OPTIONS>` ``LINK_OPTIONS`` properties. + +This command can be used to add any options, but alternative commands +exist to add libraries (:command:`target_link_libraries` or +:command:`link_libraries`). + +Arguments to ``add_link_options`` may use "generator expressions" with +the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` +manual for available expressions. See the :manual:`cmake-buildsystem(7)` +manual for more on defining buildsystem properties. + +.. include:: LINK_OPTIONS_LINKER.txt + +.. include:: OPTIONS_SHELL.txt diff --git a/Help/command/add_subdirectory.rst b/Help/command/add_subdirectory.rst new file mode 100644 index 0000000..012ded4 --- /dev/null +++ b/Help/command/add_subdirectory.rst @@ -0,0 +1,36 @@ +add_subdirectory +---------------- + +Add a subdirectory to the build. + +:: + + add_subdirectory(source_dir [binary_dir] + [EXCLUDE_FROM_ALL]) + +Add 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..d8a96e9 --- /dev/null +++ b/Help/command/add_test.rst @@ -0,0 +1,66 @@ +add_test +-------- + +Add a test to the project to be run by :manual:`ctest(1)`. + +:: + + add_test(NAME <name> COMMAND <command> [<arg>...] + [CONFIGURATIONS <config>...] + [WORKING_DIRECTORY <dir>]) + +Add a test called ``<name>``. The test name may not contain spaces, +quotes, or other characters special in CMake syntax. 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. + +The given test command is expected to exit with code ``0`` to pass and +non-zero to fail, or vice-versa if the :prop_test:`WILL_FAIL` test +property is set. Any output written to stdout or stderr will be +captured by :manual:`ctest(1)` but does not affect the pass/fail status +unless the :prop_test:`PASS_REGULAR_EXPRESSION` or +:prop_test:`FAIL_REGULAR_EXPRESSION` test property is used. + +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:: + + add_test(NAME mytest + COMMAND testDriver --config $<CONFIGURATION> + --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 when the ``BUILD_TESTING`` option is ``ON``. + +--------------------------------------------------------------------- + +:: + + 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..dcd1cdf --- /dev/null +++ b/Help/command/aux_source_directory.rst @@ -0,0 +1,24 @@ +aux_source_directory +-------------------- + +Find all source files in a directory. + +:: + + 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..fc2cd3c --- /dev/null +++ b/Help/command/break.rst @@ -0,0 +1,12 @@ +break +----- + +Break from an enclosing foreach or while loop. + +:: + + break() + +Breaks from an enclosing foreach loop or 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..b83edaf --- /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..f717db1 --- /dev/null +++ b/Help/command/build_name.rst @@ -0,0 +1,15 @@ +build_name +---------- + +Disallowed. 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..2dee93a --- /dev/null +++ b/Help/command/cmake_host_system_information.rst @@ -0,0 +1,50 @@ +cmake_host_system_information +----------------------------- + +Query host system specific information. + +:: + + 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]_ +``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_minimum_required.rst b/Help/command/cmake_minimum_required.rst new file mode 100644 index 0000000..2f1ab60 --- /dev/null +++ b/Help/command/cmake_minimum_required.rst @@ -0,0 +1,60 @@ +cmake_minimum_required +---------------------- + +Set the minimum required version of cmake for a project and +update `Policy Settings`_ to match the version given:: + + cmake_minimum_required(VERSION <min>[...<max>] [FATAL_ERROR]) + +``<min>`` and the optional ``<max>`` are each CMake versions of the form +``major.minor[.patch[.tweak]]``, and the ``...`` is literal. + +If the running version of CMake is lower than the ``<min>`` required +version it will stop processing the project and report an error. +The optional ``<max>`` version, if specified, must be at least the +``<min>`` version and affects policy settings as described below. +If the running version of CMake is older than 3.12, the extra ``...`` +dots will be seen as version component separators, resulting in the +``...<max>`` part being ignored and preserving the pre-3.12 behavior +of basing policies on ``<min>``. + +The ``FATAL_ERROR`` option is accepted but ignored by CMake 2.6 and +higher. It should be specified so CMake versions 2.4 and lower fail +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 +^^^^^^^^^^^^^^^ + +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:: + + 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:: + + 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..efbef54 --- /dev/null +++ b/Help/command/cmake_parse_arguments.rst @@ -0,0 +1,99 @@ +cmake_parse_arguments +--------------------- + +``cmake_parse_arguments`` is intended to be used in macros or functions for +parsing the arguments given to that macro or function. It processes the +arguments and defines a set of variables which hold the values of the +respective options. + +:: + + 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>) + +The first signature reads processes arguments passed in the ``args...``. +This may be used in either a :command:`macro` or a :command:`function`. + +The ``PARSE_ARGV`` signature is only for use in a :command:`function` +body. In this case the arguments that are parsed come from the +``ARGV#`` variables of the calling function. The parsing starts with +the Nth argument, where ``N`` is an unsigned integer. This allows for +the 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. + +.. note:: + + 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 argument +where recognized. This can be checked afterwards to see +whether your macro was called with unrecognized parameters. + +As an example here a ``my_install()`` macro, which takes similar arguments +as the real :command:`install` command: + +.. 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) + +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" + +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 and +``MY_INSTALL_OPTIONAL`` will therefore be set to ``TRUE``. diff --git a/Help/command/cmake_policy.rst b/Help/command/cmake_policy.rst new file mode 100644 index 0000000..c3f7cfb --- /dev/null +++ b/Help/command/cmake_policy.rst @@ -0,0 +1,104 @@ +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:: + + cmake_policy(VERSION <min>[...<max>]) + +``<min>`` and the optional ``<max>`` are each CMake versions of the form +``major.minor[.patch[.tweak]]``, and the ``...`` is literal. The ``<min>`` +version must be at least ``2.4`` and at most the running version of CMake. +The ``<max>`` version, if specified, must be at least the ``<min>`` version +but may exceed the running version of CMake. If the running version of +CMake is older than 3.12, the extra ``...`` dots will be seen as version +component separators, resulting in the ``...<max>`` part being ignored and +preserving the pre-3.12 behavior of basing policies on ``<min>``. + +This specifies that the current CMake code is written for the given +range of CMake versions. All policies known to the running version of CMake +and introduced in the ``<min>`` (or ``<max>``, if specified) version +or earlier will be set to use ``NEW`` behavior. All policies +introduced in later versions will be unset (unless the +:variable:`CMAKE_POLICY_DEFAULT_CMP<NNNN>` variable sets a default). +This effectively requests behavior preferred as of a given CMake +version and tells newer CMake versions to warn about their new policies. + +Note that the :command:`cmake_minimum_required(VERSION)` +command implicitly calls ``cmake_policy(VERSION)`` too. + +Setting Policies Explicitly +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + 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 +^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + 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:: + + 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..e08c573 --- /dev/null +++ b/Help/command/configure_file.rst @@ -0,0 +1,125 @@ +configure_file +-------------- + +Copy a file to another location and modify its contents. + +:: + + configure_file(<input> <output> + [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:: + + #cmakedefine VAR ... + +will be replaced with either:: + + #define VAR ... + +or:: + + /* #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. +Input file lines of the form ``#cmakedefine01 VAR`` will be replaced with +either ``#define VAR 1`` or ``#define VAR 0`` similarly. +The result lines (with the exception of the ``#undef`` comments) can be +indented using spaces and/or tabs between the ``#`` character +and the ``cmakedefine`` or ``cmakedefine01`` words. This whitespace +indentation will be preserved in the output lines:: + + # cmakedefine VAR + # cmakedefine01 VAR + +will be replaced, if ``VAR`` is defined, with:: + + # 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. + +``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..1c7d673 --- /dev/null +++ b/Help/command/continue.rst @@ -0,0 +1,12 @@ +continue +-------- + +Continue to the top of enclosing foreach or while loop. + +:: + + 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..dde6812 --- /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. + +:: + + 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..55bb4a3 --- /dev/null +++ b/Help/command/ctest_build.rst @@ -0,0 +1,80 @@ +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>`` + Set the name of the project to build. This should correspond + to the top-level call to the :command:`project` command. + If not specified the ``CTEST_PROJECT_NAME`` variable will be checked. + +``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>`` + Store in the ``<result-var>`` variable -1 if there are any errors running + the command and prevent ctest from returning non-zero if an error occurs. + +``QUIET`` + Suppress 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..2dea07b --- /dev/null +++ b/Help/command/ctest_configure.rst @@ -0,0 +1,46 @@ +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>`` + Store in the ``<result-var>`` variable -1 if there are any errors running + the command and prevent ctest from returning non-zero if an error occurs. + +``QUIET`` + Suppress 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..8d27b9c --- /dev/null +++ b/Help/command/ctest_coverage.rst @@ -0,0 +1,46 @@ +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>`` + Store in the ``<result-var>`` variable -1 if there are any errors running + the command and prevent ctest from returning non-zero if an error occurs. + +``QUIET`` + Suppress 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..288b65a --- /dev/null +++ b/Help/command/ctest_memcheck.rst @@ -0,0 +1,38 @@ +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>`` + 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..6db9a48 --- /dev/null +++ b/Help/command/ctest_start.rst @@ -0,0 +1,82 @@ +ctest_start +----------- + +Starts the testing for a given model + +:: + + ctest_start(<model> [<source> [<binary>]] [TRACK <track>] [QUIET]) + + ctest_start([<model> [<source> [<binary>]]] [TRACK <track>] 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. + +``TRACK <track>`` + If ``TRACK`` is used, the submissions will go to the specified track on the + CDash server. If no ``TRACK`` is specified, the name of the model is used by + default. + +``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 ``TRACK <track>`` parameters, because they will be read from + the generated ``TAG`` file. For example: + + .. code-block:: cmake + + ctest_start(Experimental TRACK TrackExperimental) + + 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 ``TrackExperimental`` track 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 track than + in the first ``ctest_start()`` command, a warning will be issued, and the + new model and track will be used. + +``QUIET`` + If ``QUIET`` is used, CTest will suppress any non-error messages that it + otherwise would have printed to the console. + +The parameters for ``ctest_start()`` can be issued in any order, with the +exception that ``<model>``, ``<source>``, and ``<binary>`` have to appear +in that order with respect to each other. The following are all valid and +equivalent: + +.. code-block:: cmake + + ctest_start(Experimental path/to/source path/to/binary TRACK SomeTrack QUIET APPEND) + + ctest_start(TRACK SomeTrack Experimental QUIET path/to/source APPEND path/to/binary) + + ctest_start(APPEND QUIET Experimental path/to/source TRACK SomeTrack 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..2ba6bef --- /dev/null +++ b/Help/command/ctest_submit.rst @@ -0,0 +1,83 @@ +ctest_submit +------------ + +Perform the :ref:`CTest Submit Step` as a :ref:`Dashboard Client`. + +:: + + ctest_submit([PARTS <part>...] [FILES <file>...] + [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 + +``FILES <file>...`` + Specify an explicit list of specific files to be submitted. + Each individual file must exist at the time of the call. + +``HTTPHEADER <HTTP-header>`` + Specify HTTP header to be included in the request to CDash during submission. + This suboption can be repeated several times. + +``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>`` + Store in the ``<result-var>`` variable -1 if there are any errors running + the command and prevent ctest from returning non-zero if an error occurs. + +``QUIET`` + Suppress all non-error messages that would have otherwise been + printed to the console. + +Submit to CDash Upload API +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + ctest_submit(CDASH_UPLOAD <file> [CDASH_UPLOAD_TYPE <type>] + [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 accepts the ``HTTPHEADER``, ``RETRY_COUNT``, ``RETRY_DELAY``, +``RETURN_VALUE`` and ``QUIET`` options as described above. diff --git a/Help/command/ctest_test.rst b/Help/command/ctest_test.rst new file mode 100644 index 0000000..4a69491 --- /dev/null +++ b/Help/command/ctest_test.rst @@ -0,0 +1,114 @@ +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>] + [TEST_LOAD <threshold>] + [SCHEDULE_RANDOM <ON|OFF>] + [STOP_TIME <time-of-day>] + [RETURN_VALUE <result-var>] + [CAPTURE_CMAKE_ERROR <result-var>] + [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>`` + 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>`` + Same as ``EXCLUDE_FIXTURE`` except only matching setup tests are excluded. + +``EXCLUDE_FIXTURE_CLEANUP <regex>`` + 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. + +``TEST_LOAD <threshold>`` + While running tests in parallel, try not to start tests when they + may cause the CPU load to pass above a given threshold. If not + 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`. + +``SCHEDULE_RANDOM <ON|OFF>`` + Launch tests in a random order. This may be useful for detecting + implicit test dependencies. + +``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>`` + Store in the ``<result-var>`` variable -1 if there are any errors running + the command and prevent ctest from returning non-zero if an error occurs. + +``QUIET`` + Suppress 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..df1a4e5 --- /dev/null +++ b/Help/command/ctest_update.rst @@ -0,0 +1,38 @@ +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>`` + Store in the ``<result-var>`` variable -1 if there are any errors running + the command and prevent ctest from returning non-zero if an error occurs. + +``QUIET`` + Tell CTest to suppress most non-error messages that it would + have otherwise printed to the console. CTest will still report + 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 more information. diff --git a/Help/command/ctest_upload.rst b/Help/command/ctest_upload.rst new file mode 100644 index 0000000..39d9de1 --- /dev/null +++ b/Help/command/ctest_upload.rst @@ -0,0 +1,22 @@ +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`` + Suppress any CTest-specific non-error output that would have been + printed to the console otherwise. + +``CAPTURE_CMAKE_ERROR <result-var>`` + Store in the ``<result-var>`` variable -1 if there are any errors running + the command and prevent ctest from returning non-zero if an error occurs. diff --git a/Help/command/define_property.rst b/Help/command/define_property.rst new file mode 100644 index 0000000..da2631c --- /dev/null +++ b/Help/command/define_property.rst @@ -0,0 +1,59 @@ +define_property +--------------- + +Define and document custom properties. + +:: + + define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE | + TEST | VARIABLE | CACHED_VARIABLE> + PROPERTY <name> [INHERITED] + BRIEF_DOCS <brief-doc> [docs...] + FULL_DOCS <full-doc> [docs...]) + +Define 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..0e5a198 --- /dev/null +++ b/Help/command/else.rst @@ -0,0 +1,10 @@ +else +---- + +Starts the else portion of an if block. + +:: + + else(expression) + +See the :command:`if` command. diff --git a/Help/command/elseif.rst b/Help/command/elseif.rst new file mode 100644 index 0000000..9a8dfed --- /dev/null +++ b/Help/command/elseif.rst @@ -0,0 +1,10 @@ +elseif +------ + +Starts the elseif portion of an if block. + +:: + + elseif(expression) + +See the :command:`if` command. diff --git a/Help/command/enable_language.rst b/Help/command/enable_language.rst new file mode 100644 index 0000000..61dfc03 --- /dev/null +++ b/Help/command/enable_language.rst @@ -0,0 +1,26 @@ +enable_language +--------------- + +Enable a language (CXX/C/Fortran/etc) + +:: + + enable_language(<lang> [OPTIONAL] ) + +This command enables support for the named language in CMake. This is +the same as the project command but does not create any of the extra +variables that are created by the project command. Example languages +are ``CXX``, ``C``, ``CUDA``, ``Fortran``, and ``ASM``. + +If enabling ``ASM``, enable it last so that CMake can check whether +compilers for other languages like ``C`` work for assembly too. + +This command must be called in file scope, not in a function call. +Furthermore, it must be called in the highest directory common to all +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..1e3e279 --- /dev/null +++ b/Help/command/enable_testing.rst @@ -0,0 +1,13 @@ +enable_testing +-------------- + +Enable testing for current directory and below. + +:: + + enable_testing() + +Enables testing for this directory and below. See also the +:command:`add_test` command. Note that ctest expects to find a test file +in the build directory root. Therefore, this command should be in the +source directory root. diff --git a/Help/command/endforeach.rst b/Help/command/endforeach.rst new file mode 100644 index 0000000..9af972b --- /dev/null +++ b/Help/command/endforeach.rst @@ -0,0 +1,10 @@ +endforeach +---------- + +Ends a list of commands in a foreach block. + +:: + + endforeach(expression) + +See the :command:`foreach` command. diff --git a/Help/command/endfunction.rst b/Help/command/endfunction.rst new file mode 100644 index 0000000..6cc196c --- /dev/null +++ b/Help/command/endfunction.rst @@ -0,0 +1,10 @@ +endfunction +----------- + +Ends a list of commands in a function block. + +:: + + endfunction(expression) + +See the :command:`function` command. diff --git a/Help/command/endif.rst b/Help/command/endif.rst new file mode 100644 index 0000000..a0163bf --- /dev/null +++ b/Help/command/endif.rst @@ -0,0 +1,10 @@ +endif +----- + +Ends a list of commands in an if block. + +:: + + endif(expression) + +See the :command:`if` command. diff --git a/Help/command/endmacro.rst b/Help/command/endmacro.rst new file mode 100644 index 0000000..47327a7 --- /dev/null +++ b/Help/command/endmacro.rst @@ -0,0 +1,10 @@ +endmacro +-------- + +Ends a list of commands in a macro block. + +:: + + endmacro(expression) + +See the :command:`macro` command. diff --git a/Help/command/endwhile.rst b/Help/command/endwhile.rst new file mode 100644 index 0000000..798c20e --- /dev/null +++ b/Help/command/endwhile.rst @@ -0,0 +1,10 @@ +endwhile +-------- + +Ends a list of commands in a while block. + +:: + + endwhile(expression) + +See the :command:`while` command. diff --git a/Help/command/exec_program.rst b/Help/command/exec_program.rst new file mode 100644 index 0000000..6dfdad3 --- /dev/null +++ b/Help/command/exec_program.rst @@ -0,0 +1,24 @@ +exec_program +------------ + +Deprecated. 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..716f457 --- /dev/null +++ b/Help/command/execute_process.rst @@ -0,0 +1,108 @@ +execute_process +--------------- + +Execute one or more child processes. + +.. code-block:: cmake + + execute_process(COMMAND <cmd1> [args1...]] + [COMMAND <cmd2> [args2...] [...]] + [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] + [OUTPUT_STRIP_TRAILING_WHITESPACE] + [ERROR_STRIP_TRAILING_WHITESPACE] + [ENCODING <name>]) + +Runs the given sequence of one or more commands in parallel 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`` + The child processes will be terminated if they do not finish in the + specified number of seconds (fractions are allowed). + +``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>`` + The variable will be set to contain the result of all processes as a + :ref:`;-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. 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. + +``ENCODING <name>`` + 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. Prior to CMake 3.11.0, only ``UTF8`` was accepted + for this encoding. In CMake 3.11.0, ``UTF-8`` was added for consistency with + the `UTF-8 RFC <https://www.ietf.org/rfc/rfc3629>`_ naming convention. + +If more than one ``OUTPUT_*`` or ``ERROR_*`` option is given for the +same pipe the precedence is not specified. +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..8c49328 --- /dev/null +++ b/Help/command/export.rst @@ -0,0 +1,81 @@ +export +------ + +Export targets from the build tree for use by outside projects. + +:: + + export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>]) + +Create 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. + +:: + + 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. + +:: + + export(PACKAGE <PackageName>) + +Store the current build directory in the CMake user package registry +for package ``<PackageName>``. The find_package command may consider the +directory while searching for package ``<PackageName>``. This helps dependent +projects find and use a package from the current project's build tree +without help from the user. Note that the entry in the package +registry that this command creates works only in conjunction with a +package configuration file (``<PackageName>Config.cmake``) that works with the +build tree. In some cases, for example for packaging and for system +wide installations, it is not desirable to write the user package +registry. If the :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` variable +is enabled, the ``export(PACKAGE)`` command will do nothing. + +:: + + export(TARGETS [target1 [target2 [...]]] [ANDROID_MK <filename>]) + +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..2cb437e --- /dev/null +++ b/Help/command/export_library_dependencies.rst @@ -0,0 +1,28 @@ +export_library_dependencies +--------------------------- + +Disallowed. 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..d4a6006 --- /dev/null +++ b/Help/command/file.rst @@ -0,0 +1,489 @@ +file +---- + +File manipulation 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> [...]) + + `Writing`_ + file({`WRITE`_ | `APPEND`_} <filename> <content>...) + file({`TOUCH`_ | `TOUCH_NOCREATE`_} [<file>...]) + file(`GENERATE`_ OUTPUT <output-file> [...]) + + `Filesystem`_ + file({`GLOB`_ | `GLOB_RECURSE`_} <out-var> [...] [<globbing-expr>...]) + file(`RENAME`_ <oldname> <newname>) + file({`REMOVE`_ | `REMOVE_RECURSE`_ } [<files>...]) + file(`MAKE_DIRECTORY`_ [<dir>...]) + file({`COPY`_ | `INSTALL`_} <file>... DESTINATION <dir> [...]) + + `Path Conversion`_ + file(`RELATIVE_PATH`_ <out-var> <directory> <file>) + file({`TO_CMAKE_PATH`_ | `TO_NATIVE_PATH`_} <path> <out-var>) + + `Transfer`_ + file(`DOWNLOAD`_ <url> <file> [...]) + file(`UPLOAD`_ <file> <url> [...]) + + `Locking`_ + file(`LOCK`_ <path> [...]) + +Reading +^^^^^^^ + +.. _READ: + +:: + + 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). + +.. _STRINGS: + +:: + + 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>`` + 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. + +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: + +:: + + 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: + +:: + + 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. + +Writing +^^^^^^^ + +.. _WRITE: +.. _APPEND: + +:: + + 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: + +:: + + file(TOUCH [<files>...]) + file(TOUCH_NOCREATE [<files>...]) + +Create a file with no content if it does not yet exist. If the file already +exists, its access and/or modification will be updated to the time when the +function call is executed. + +Use TOUCH_NOCREATE to touch a file if it exists but not create it. If a file +does not exist it will be silently ignored. + +With TOUCH and TOUCH_NOCREATE the contents of an existing file will not be +modified. + +.. _GENERATE: + +:: + + file(GENERATE OUTPUT output-file + <INPUT input-file|CONTENT content> + [CONDITION expression]) + +Generate an output file for each build configuration supported by the current +:manual:`CMake Generator <cmake-generators(7)>`. Evaluate +:manual:`generator expressions <cmake-generator-expressions(7)>` +from the input content to produce the output content. The options are: + +``CONDITION <condition>`` + Generate the output file for a particular configuration only if + the condition is true. The condition must be either ``0`` or ``1`` + after evaluating generator expressions. + +``CONTENT <content>`` + Use the content given explicitly as input. + +``INPUT <input-file>`` + Use the content from a given file as input. + A relative path is treated with respect to the value of + :variable:`CMAKE_CURRENT_SOURCE_DIR`. See policy :policy:`CMP0070`. + +``OUTPUT <output-file>`` + Specify the output file name to generate. Use generator expressions + such as ``$<CONFIG>`` to specify a configuration-specific output file + name. Multiple configurations may generate the same output file only + if the generated content is identical. Otherwise, the ``<output-file>`` + must evaluate to an unique name for each configuration. + A relative path (after evaluating generator expressions) is treated + with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. + See policy :policy:`CMP0070`. + +Exactly one ``CONTENT`` or ``INPUT`` option must be given. A specific +``OUTPUT`` file may be named by at most one invocation of ``file(GENERATE)``. +Generated files are modified and their timestamp updated on subsequent cmake +runs only if their content is changed. + +Note also that ``file(GENERATE)`` does not create the output file until the +generation phase. The output file will not yet have been written when the +``file(GENERATE)`` command returns, it is written only after processing all +of a project's ``CMakeLists.txt`` files. + +Filesystem +^^^^^^^^^^ + +.. _GLOB: +.. _GLOB_RECURSE: + +:: + + 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. The results will be ordered lexicographically. + +If the ``CONFIGURE_DEPENDS`` flag is specified, CMake will add logic +to the main build system check target to rerun the flagged ``GLOB`` commands +at build time. If any of the outputs change, CMake will regenerate the build +system. + +By default ``GLOB`` lists directories - directories are omitted in result if +``LIST_DIRECTORIES`` is set to false. + +.. note:: + 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``. + +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 +``OLD`` then ``LIST_DIRECTORIES`` treats symlinks as directories. + +Examples of recursive globbing include:: + + /dir/*.py - match all python files in /dir and subdirectories + +.. _RENAME: + +:: + + file(RENAME <oldname> <newname>) + +Move a file or directory within a filesystem from ``<oldname>`` to +``<newname>``, replacing the destination atomically. + +.. _REMOVE: +.. _REMOVE_RECURSE: + +:: + + 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. + +.. _MAKE_DIRECTORY: + +:: + + file(MAKE_DIRECTORY [<directories>...]) + +Create the given directories and their parents as needed. + +.. _COPY: +.. _INSTALL: + +:: + + file(<COPY|INSTALL> <files>... DESTINATION <dir> + [FILE_PERMISSIONS <permissions>...] + [DIRECTORY_PERMISSIONS <permissions>...] + [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS] + [FILES_MATCHING] + [[PATTERN <pattern> | REGEX <regex>] + [EXCLUDE] [PERMISSIONS <permissions>...]] [...]) + +The ``COPY`` signature copies files, directories, and symlinks to a +destination folder. Relative input paths are evaluated with respect +to the current source directory, and a relative destination is +evaluated with respect to the current build directory. Copying +preserves input file timestamps, and optimizes out a file if it exists +at the destination with the same timestamp. Copying preserves input +permissions unless explicit permissions or ``NO_SOURCE_PERMISSIONS`` +are given (default is ``USE_SOURCE_PERMISSIONS``). + +See the :command:`install(DIRECTORY)` command for documentation of +permissions, ``FILES_MATCHING``, ``PATTERN``, ``REGEX``, and +``EXCLUDE`` options. Copying directories preserves the structure +of their content even if options are used to select a subset of +files. + +The ``INSTALL`` signature differs slightly from ``COPY``: it prints +status messages (subject to the :variable:`CMAKE_INSTALL_MESSAGE` variable), +and ``NO_SOURCE_PERMISSIONS`` is default. +Installation scripts generated by the :command:`install` command +use this signature (with some undocumented options for internal use). + +Path Conversion +^^^^^^^^^^^^^^^ + +.. _RELATIVE_PATH: + +:: + + 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: + +:: + + 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 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: + +:: + + file(DOWNLOAD <url> <file> [<options>...]) + file(UPLOAD <file> <url> [<options>...]) + +The ``DOWNLOAD`` mode downloads the given ``<url>`` to a local ``<file>``. +The ``UPLOAD`` mode uploads a local ``<file>`` to a given ``<url>``. + +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>`` + Set username and password for operation. + +``HTTPHEADER <HTTP-header>`` + HTTP header for operation. Suboption can be repeated several times. + +``NETRC <level>`` + Specify whether the .netrc file is to be used for operation. If this + option is not specified, the value of the ``CMAKE_NETRC`` variable + will be used instead. + Valid levels are: + + ``IGNORED`` + The .netrc file is ignored. + This is the default. + ``OPTIONAL`` + The .netrc file is optional, and information in the URL is preferred. + The file will be scanned to find which ever information is not specified + in the URL. + ``REQUIRED`` + The .netrc file is required, and information in the URL is ignored. + +``NETRC_FILE <file>`` + Specify an alternative .netrc file to the one in your home directory, + if the ``NETRC`` level is ``OPTIONAL`` or ``REQUIRED``. If this option + is not specified, the value of the ``CMAKE_NETRC_FILE`` variable will + be used instead. + +If neither ``NETRC`` option is given CMake will check variables +``CMAKE_NETRC`` and ``CMAKE_NETRC_FILE``, respectively. + +Additional options to ``DOWNLOAD`` are: + +``EXPECTED_HASH ALGO=<value>`` + + 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. + +``EXPECTED_MD5 <value>`` + Historical short-hand for ``EXPECTED_HASH MD5=<value>``. + +``TLS_VERIFY <ON|OFF>`` + Specify whether to verify the server certificate for ``https://`` URLs. + The default is to *not* verify. + +``TLS_CAINFO <file>`` + Specify a custom Certificate Authority file for ``https://`` URLs. + +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 and/or use ``EXPECTED_HASH`` to verify downloaded content. +If neither ``TLS`` option is given CMake will check variables +``CMAKE_TLS_VERIFY`` and ``CMAKE_TLS_CAINFO``, respectively. + +Locking +^^^^^^^ + +.. _LOCK: + +:: + + file(LOCK <path> [DIRECTORY] [RELEASE] + [GUARD <FUNCTION|FILE|PROCESS>] + [RESULT_VARIABLE <variable>] + [TIMEOUT <seconds>]) + +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. diff --git a/Help/command/find_file.rst b/Help/command/find_file.rst new file mode 100644 index 0000000..2a14ad7 --- /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:: Directories in ``INCLUDE``. + On Windows hosts: + ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` + is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|, and the + directories in ``PATH`` itself. + +.. |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..0861d67 --- /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:: Directories in ``LIB``. + On Windows hosts: + ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set, + and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|, + and the directories in ``PATH`` itself. + +.. |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..b486b79 --- /dev/null +++ b/Help/command/find_package.rst @@ -0,0 +1,382 @@ +find_package +------------ + +Load settings for an external project. + +:: + + 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 messages if the package cannot be found. The +``MODULE`` option disables the second signature documented below. The +``REQUIRED`` option stops processing with an error message if the package +cannot be found. + +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. + +The ``[version]`` argument requests a version with which the package found +should be compatible (format is ``major[.minor[.patch[.tweak]]]``). The +``EXACT`` option requests that the version be matched exactly. 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 (details below). + +User code should generally look for packages using the above simple +signature. The remainder of this command documentation specifies the +full command signature and details of the search process. Project +maintainers wishing to provide a package to be found by this command +are encouraged to read on. + +The command has two modes by which it searches for packages: "Module" +mode and "Config" mode. Module mode is available when the command is +invoked with the above reduced signature. CMake searches for a file +called ``Find<PackageName>.cmake`` in the :variable:`CMAKE_MODULE_PATH` +followed by the CMake installation. If the file is found, it is read +and processed by CMake. It is responsible for finding the package, +checking the version, and producing any needed messages. Many +find-modules provide limited or no support for versioning; check +the module documentation. If no module is found and the ``MODULE`` +option is not given the command proceeds to Config mode. + +The complete Config mode command signature is:: + + find_package(<PackageName> [version] [EXACT] [QUIET] + [REQUIRED] [[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 may be used to skip Module mode explicitly and +switch to Config mode. It is synonymous to using ``NO_MODULE``. Config +mode is also implied by use of options not specified in the reduced +signature. + +Config mode 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. + +When the ``[version]`` argument is given Config mode will only find a +version of the package that claims compatibility with the requested +version (format is ``major[.minor[.patch[.tweak]]]``). If the ``EXACT`` +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 + +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:: + + SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL) + SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC) + +before calling ``find_package``. + +Config mode provides an elaborate interface and search procedure. +Much of the interface is provided for completeness and for use +internally by find-modules loaded by Module mode. Most user code +should simply call:: + + find_package(<PackageName> [major[.minor]] [EXACT] [REQUIRED|QUIET]) + +in order to find a package. Package maintainers providing CMake +package configuration files are encouraged to name and install them +such that the procedure outlined below will find them without +requiring use of additional options. + +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 Frameworks and Application Bundles the +following directories are searched for frameworks or 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. 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. + See policy :policy:`CMP0074`. + +2. Search paths specified in cmake-specific cache variables. These + are intended to be used on the command line with a ``-DVAR=value``. + The values are interpreted as :ref:`;-lists <CMake Language Lists>`. + This can be skipped if ``NO_CMAKE_PATH`` is passed:: + + CMAKE_PREFIX_PATH + CMAKE_FRAMEWORK_PATH + 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:: + + <PackageName>_DIR + 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. 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:`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:: + + CMAKE_SYSTEM_PREFIX_PATH + CMAKE_SYSTEM_FRAMEWORK_PATH + CMAKE_SYSTEM_APPBUNDLE_PATH + +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_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. + +.. |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 + +Every non-REQUIRED ``find_package`` call can be disabled by setting the +:variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable to ``TRUE``. + +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 + +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. + +See the :command:`cmake_policy` command documentation for discussion +of the ``NO_POLICY_SCOPE`` option. diff --git a/Help/command/find_path.rst b/Help/command/find_path.rst new file mode 100644 index 0000000..988a3fa --- /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:: Directories in ``INCLUDE``. + On Windows hosts: + ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` + is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|, and the + directories in ``PATH`` itself. + +.. |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..4f00773 --- /dev/null +++ b/Help/command/find_program.rst @@ -0,0 +1,35 @@ +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:: ``PATH`` + +.. |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..041e5a7 --- /dev/null +++ b/Help/command/fltk_wrap_ui.rst @@ -0,0 +1,14 @@ +fltk_wrap_ui +------------ + +Create FLTK user interfaces Wrappers. + +:: + + 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..106ba73 --- /dev/null +++ b/Help/command/foreach.rst @@ -0,0 +1,47 @@ +foreach +------- + +Evaluate a group of commands for each value in a list. + +:: + + foreach(loop_var arg1 arg2 ...) + COMMAND1(ARGS ...) + COMMAND2(ARGS ...) + ... + endforeach(loop_var) + +All commands between foreach and the matching endforeach are recorded +without being invoked. Once the endforeach is evaluated, the recorded +list of commands is invoked once for each argument listed in the +original foreach command. Before each iteration of the loop +``${loop_var}`` will be set as a variable with the current value in the +list. + +:: + + foreach(loop_var RANGE total) + foreach(loop_var RANGE start stop [step]) + +Foreach can also iterate over a generated range of numbers. There are +three types of this iteration: + +* When specifying single number, the range will have elements [0, ... to + "total"] (inclusive). + +* When specifying two numbers, the range will have elements from the + first number to the second number (inclusive). + +* The third optional number is the increment used to iterate from the + first number to the second number (inclusive). + +:: + + foreach(loop_var IN [LISTS [list1 [...]]] + [ITEMS [item1 [...]]]) + +Iterates over a precise list of items. The ``LISTS`` option names +list-valued variables to be traversed, including empty elements (an +empty string is a zero-length list). (Note macro +arguments are not variables.) The ``ITEMS`` option ends argument +parsing and includes all arguments following it in the iteration. diff --git a/Help/command/function.rst b/Help/command/function.rst new file mode 100644 index 0000000..7ffdfee --- /dev/null +++ b/Help/command/function.rst @@ -0,0 +1,36 @@ +function +-------- + +Start recording a function for later invocation as a command:: + + function(<name> [arg1 [arg2 [arg3 ...]]]) + COMMAND1(ARGS ...) + COMMAND2(ARGS ...) + ... + endfunction(<name>) + +Define a function named ``<name>`` that takes arguments named ``arg1``, +``arg2``, ``arg3``, (...). +Commands listed after function, but before the matching +:command:`endfunction()`, are not invoked until the function is invoked. +When it is invoked, the commands recorded in the function are first +modified by replacing formal parameters (``${arg1}``) with the arguments +passed, and then invoked as normal commands. +In addition to referencing the formal parameters you can reference the +``ARGC`` variable which will be set to the number of arguments passed +into the function as well as ``ARGV0``, ``ARGV1``, ``ARGV2``, ... which +will have the actual values of the arguments passed in. +This facilitates creating functions with optional arguments. +Additionally ``ARGV`` holds the list of all arguments given to the +function and ``ARGN`` holds the list of arguments past the last expected +argument. +Referencing to ``ARGV#`` arguments beyond ``ARGC`` have undefined +behavior. Checking that ``ARGC`` is greater than ``#`` is the only way +to ensure that ``ARGV#`` was passed to the function as an extra +argument. + +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. diff --git a/Help/command/get_cmake_property.rst b/Help/command/get_cmake_property.rst new file mode 100644 index 0000000..497ab4e --- /dev/null +++ b/Help/command/get_cmake_property.rst @@ -0,0 +1,20 @@ +get_cmake_property +------------------ + +Get a global property of the CMake instance. + +:: + + get_cmake_property(VAR property) + +Get a global property from the CMake instance. The value of the property is +stored in the variable ``VAR``. If the property is not found, ``VAR`` +will be set to "NOTFOUND". See the :manual:`cmake-properties(7)` manual +for available properties. + +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..bf8349c --- /dev/null +++ b/Help/command/get_directory_property.rst @@ -0,0 +1,29 @@ +get_directory_property +---------------------- + +Get a property of ``DIRECTORY`` scope. + +:: + + get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>) + +Store a property of directory scope in the named ``<variable>``. +The ``DIRECTORY`` argument specifies another directory from which +to retrieve the property value instead of the current directory. +The specified directory must have already been traversed by CMake. + +If the property is not defined for the nominated directory scope, +an empty string is returned. In the case of ``INHERITED`` properties, +if the property is not found for the nominated directory scope, +the search will chain to a parent scope as described for the +:command:`define_property` command. + +:: + + 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..f11c0fc --- /dev/null +++ b/Help/command/get_filename_component.rst @@ -0,0 +1,64 @@ +get_filename_component +---------------------- + +Get a specific component of a full filename. + +------------------------------------------------------------------------------ + +:: + + get_filename_component(<VAR> <FileName> <COMP> [CACHE]) + +Set ``<VAR>`` to a component of ``<FileName>``, where ``<COMP>`` 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 without directory or longest extension + PATH = Legacy alias for DIRECTORY (use for CMake <= 2.8.11) + +Paths are returned with forward slashes and have no trailing slashes. +The longest file extension is always considered. If the optional +``CACHE`` argument is specified, the result variable is added to the +cache. + +------------------------------------------------------------------------------ + +:: + + get_filename_component(<VAR> <FileName> + <COMP> [BASE_DIR <BASE_DIR>] + [CACHE]) + +Set ``<VAR>`` to the absolute path of ``<FileName>``, where ``<COMP>`` 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 ``<BASE_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. + +------------------------------------------------------------------------------ + +:: + + 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..8b85f7d --- /dev/null +++ b/Help/command/get_property.rst @@ -0,0 +1,64 @@ +get_property +------------ + +Get a property. + +:: + + get_property(<variable> + <GLOBAL | + DIRECTORY [dir] | + TARGET <target> | + SOURCE <source> | + INSTALL <file> | + TEST <test> | + CACHE <entry> | + VARIABLE> + PROPERTY <name> + [SET | DEFINED | BRIEF_DOCS | FULL_DOCS]) + +Get one property from one object in a scope. The first argument +specifies the variable in which to store the result. The second +argument determines the scope from which to get the property. It must +be one of the following: + +``GLOBAL`` + Scope is unique and does not accept a name. + +``DIRECTORY`` + Scope defaults to the current directory but another + directory (already processed by CMake) may be named by full or + relative path. + +``TARGET`` + Scope must name one existing target. + +``SOURCE`` + Scope must name one source file. + +``INSTALL`` + Scope must name one installed file path. + +``TEST`` + Scope must name one existing test. + +``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. diff --git a/Help/command/get_source_file_property.rst b/Help/command/get_source_file_property.rst new file mode 100644 index 0000000..51fbd33 --- /dev/null +++ b/Help/command/get_source_file_property.rst @@ -0,0 +1,22 @@ +get_source_file_property +------------------------ + +Get a property for a source file. + +:: + + get_source_file_property(VAR file property) + +Get a property from a source file. The value of the property is +stored in the variable ``VAR``. If the source property is not found, the +behavior depends on whether it has been defined to be an ``INHERITED`` property +or not (see :command:`define_property`). Non-inherited properties will set +``VAR`` to "NOTFOUND", whereas inherited properties will search the relevant +parent scope as described for the :command:`define_property` command and +if still unable to find the property, ``VAR`` will be set to an empty string. + +Use :command:`set_source_files_properties` to set property values. Source +file properties usually control how the file is built. One property that is +always there is :prop_sf:`LOCATION`. + +See also the more general :command:`get_property` command. diff --git a/Help/command/get_target_property.rst b/Help/command/get_target_property.rst new file mode 100644 index 0000000..98e9db3 --- /dev/null +++ b/Help/command/get_target_property.rst @@ -0,0 +1,25 @@ +get_target_property +------------------- + +Get a property from a target. + +:: + + 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 "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. diff --git a/Help/command/get_test_property.rst b/Help/command/get_test_property.rst new file mode 100644 index 0000000..555c3b2 --- /dev/null +++ b/Help/command/get_test_property.rst @@ -0,0 +1,21 @@ +get_test_property +----------------- + +Get a property of the test. + +:: + + 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..5294ce8 --- /dev/null +++ b/Help/command/if.rst @@ -0,0 +1,254 @@ +if +-- + +Conditionally execute a group of commands. + +.. code-block:: cmake + + if(expression) + # then section. + COMMAND1(ARGS ...) + COMMAND2(ARGS ...) + #... + elseif(expression2) + # elseif section. + COMMAND1(ARGS ...) + COMMAND2(ARGS ...) + #... + else(expression) + # else section. + COMMAND1(ARGS ...) + COMMAND2(ARGS ...) + #... + endif(expression) + +Evaluates the given expression. If the result is true, the commands +in the THEN section are invoked. Otherwise, the commands in the else +section are invoked. The elseif and else sections are optional. You +may have multiple elseif clauses. Note that the expression in the +else and endif clause is optional. Long expressions can be used and +there is a traditional order of precedence. Parenthetical expressions +are evaluated first followed by unary tests such as ``EXISTS``, +``COMMAND``, and ``DEFINED``. Then any binary tests such as +``EQUAL``, ``LESS``, ``LESS_EQUAL``, ``GREATER``, ``GREATER_EQUAL``, +``STREQUAL``, ``STRLESS``, ``STRLESS_EQUAL``, ``STRGREATER``, +``STRGREATER_EQUAL``, ``VERSION_EQUAL``, ``VERSION_LESS``, +``VERSION_LESS_EQUAL``, ``VERSION_GREATER``, ``VERSION_GREATER_EQUAL``, +and ``MATCHES`` will be evaluated. Then boolean ``NOT`` operators and +finally boolean ``AND`` and then ``OR`` operators will be evaluated. + +Possible expressions are: + +``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.) + +``if(NOT <expression>)`` + True if the expression is not true. + +``if(<expr1> AND <expr2>)`` + True if both expressions would be considered true individually. + +``if(<expr1> OR <expr2>)`` + True if either expression would be considered true individually. + +``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)`` + True if the given name is an existing test name created by the + :command:`add_test` command. + +``if(EXISTS path-to-file-or-directory)`` + True if the named file or directory exists. Behavior is well-defined + only for full paths. + +``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. + +``if(<variable|string> MATCHES regex)`` + True if the given string or variable's value matches the given regular + expression. See :ref:`Regex Specification` for regex format. + ``()`` groups are captured in :variable:`CMAKE_MATCH_<n>` variables. + +``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. + +``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. + +``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. + +``if(<variable|string> LESS_EQUAL <variable|string>)`` + True if the given string or variable's value is a valid number and less + than or equal to that on the right. + +``if(<variable|string> GREATER_EQUAL <variable|string>)`` + True if the given string or variable's value is a valid number and greater + than or equal to that on the right. + +``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. + +``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. + +``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. + +``if(<variable|string> STRLESS_EQUAL <variable|string>)`` + True if the given string or variable's value is lexicographically less + than or equal to the string or variable on the right. + +``if(<variable|string> STRGREATER_EQUAL <variable|string>)`` + True if the given string or variable's value is lexicographically greater + than or equal to the string or variable on the right. + +``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. + +``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. + +``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. + +``if(<variable|string> VERSION_LESS_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. + +``if(<variable|string> VERSION_GREATER_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. + +``if(<variable|string> IN_LIST <variable>)`` + True if the given element is contained in the named list variable. + +``if(DEFINED <variable>)`` + True if the given variable is defined. It does not matter if the + variable is true or false just if it has been set. (Note macro + arguments are not variables.) + +``if((expression) AND (expression OR (expression)))`` + The expressions inside the parenthesis are evaluated first and then + the remaining expression is evaluated as in the previous examples. + Where there are nested parenthesis the innermost are evaluated as part + of evaluating the expression that contains them. + +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:: + + set(var1 OFF) + set(var2 "var1") + if(${var2}) + +appears to the if command as:: + + 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:: + + if(var2) + +which is true because ``var2`` is defined to "var1" which is not a false +constant. + +Automatic evaluation applies in the other cases whenever the +above-documented signature accepts ``<variable|string>``: + +* 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. + +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`. diff --git a/Help/command/include.rst b/Help/command/include.rst new file mode 100644 index 0000000..eeca4c6 --- /dev/null +++ b/Help/command/include.rst @@ -0,0 +1,25 @@ +include +------- + +Load and run CMake code from a file or module. + +:: + + include(<file|module> [OPTIONAL] [RESULT_VARIABLE <VAR>] + [NO_POLICY_SCOPE]) + +Load and run CMake code from the file given. Variable reads and +writes access the scope of the caller (dynamic scoping). If ``OPTIONAL`` +is present, then no error is raised if the file does not exist. If +``RESULT_VARIABLE`` is given the variable will be set to the full filename +which has been included or NOTFOUND if it failed. + +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..e797b5d --- /dev/null +++ b/Help/command/include_directories.rst @@ -0,0 +1,41 @@ +include_directories +------------------- + +Add include directories to the build. + +:: + + 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..335282a --- /dev/null +++ b/Help/command/include_external_msproject.rst @@ -0,0 +1,26 @@ +include_external_msproject +-------------------------- + +Include an external Microsoft project file in a workspace. + +:: + + 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). + +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..62cce22 --- /dev/null +++ b/Help/command/include_guard.rst @@ -0,0 +1,46 @@ +include_guard +------------- + +Provides an include guard for the file currently being processed by CMake. + +:: + + 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..ab5a563 --- /dev/null +++ b/Help/command/include_regular_expression.rst @@ -0,0 +1,18 @@ +include_regular_expression +-------------------------- + +Set the regular expression used for dependency checking. + +:: + + include_regular_expression(regex_match [regex_complain]) + +Set 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..08c5718 --- /dev/null +++ b/Help/command/install.rst @@ -0,0 +1,554 @@ +install +------- + +Specify rules to run at install time. + +Synopsis +^^^^^^^^ + +.. parsed-literal:: + + install(`TARGETS`_ <target>... [...]) + install({`FILES`_ | `PROGRAMS`_} <file>... DESTINATION <dir> [...]) + install(`DIRECTORY`_ <dir>... DESTINATION <dir> [...]) + install(`SCRIPT`_ <file> [...]) + install(`CODE`_ <code> [...]) + install(`EXPORT`_ <export-name> DESTINATION <dir> [...]) + +Introduction +^^^^^^^^^^^^ + +This command generates installation rules for a project. Rules +specified by calls to this command within a source directory are +executed in order during installation. The order across directories +is not defined. + +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. + If a full path (with a leading slash or drive letter) is given + it is used directly. 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. + +``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`` + 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. + +Command signatures that install files may print messages during +installation. Use the :variable:`CMAKE_INSTALL_MESSAGE` variable +to control which messages are printed. + +Many of the ``install()`` variants implicitly create the directories +containing the installed files. If +:variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` is set, these +directories will be created with the permissions specified. Otherwise, +they will be created according to the uname rules on Unix-like platforms. +Windows platforms are unaffected. + +Installing Targets +^^^^^^^^^^^^^^^^^^ + +.. _TARGETS: + +:: + + 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 files that may be installed: + +``ARCHIVE`` + Static libraries are treated as ``ARCHIVE`` targets, except those + marked with the ``FRAMEWORK`` property on macOS (see ``FRAMEWORK`` + below.) For DLL platforms (all Windows-based systems including + Cygwin), the DLL import library is treated as an ``ARCHIVE`` target. + +``LIBRARY`` + Module libraries are always treated as ``LIBRARY`` targets. For non- + DLL platforms shared libraries are treated as ``LIBRARY`` targets, + except those marked with the ``FRAMEWORK`` property on macOS (see + ``FRAMEWORK`` below.) + +``RUNTIME`` + Executables are treated as ``RUNTIME`` objects, except those marked + with the ``MACOSX_BUNDLE`` property on macOS (see ``BUNDLE`` below.) + For DLL platforms (all Windows-based systems including Cygwin), the + DLL part of a shared library is treated as a ``RUNTIME`` target. + +``OBJECTS`` + Object libraries (a simple group of object files) are always treated + as ``OBJECTS`` targets. + +``FRAMEWORK`` + Both static and shared libraries marked with the ``FRAMEWORK`` + property are treated as ``FRAMEWORK`` targets on macOS. + +``BUNDLE`` + Executables marked with the ``MACOSX_BUNDLE`` property are treated as + ``BUNDLE`` targets on macOS. + +``PUBLIC_HEADER`` + Any ``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 ``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.) + +In addition to the common options listed above, each target can accept +the following additional arguments: + +``NAMELINK_COMPONENT`` + On some platforms a versioned shared library has a symbolic link such + as:: + + lib<name>.so -> lib<name>.so.1 + + where ``lib<name>.so.1`` is the soname of the library and ``lib<name>.so`` + is a "namelink" allowing linkers to find the library when given + ``-l<name>``. The ``NAMELINK_COMPONENT`` option is similar to the + ``COMPONENT`` option, but it changes the installation component of a shared + library namelink if one is generated. If not specified, this defaults to the + value of ``COMPONENT``. It is an error to use this parameter outside of a + ``LIBRARY`` block. + + Consider the following example: + + .. code-block:: cmake + + install(TARGETS mylib + LIBRARY + DESTINATION lib + COMPONENT Libraries + NAMELINK_COMPONENT Development + PUBLIC_HEADER + DESTINATION include + 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. + +``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 :command:`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. + +:command:`install(TARGETS)` can install targets that were created in +other directories. When using such cross-directory install rules, running +``make install`` (or similar) from a subdirectory will not guarantee that +targets from other directories are up-to-date. You can use +:command:`target_link_libraries` or :command:`add_dependencies` +to ensure that such out-of-directory targets are built before the +subdirectory-specific install rules are run. + +The install destination given to the target install ``DESTINATION`` may +use "generator expressions" with the syntax ``$<...>``. See the +:manual:`cmake-generator-expressions(7)` manual for available expressions. + +Installing Files +^^^^^^^^^^^^^^^^ + +.. _FILES: +.. _PROGRAMS: + +:: + + install(<FILES|PROGRAMS> files... 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. + +The install destination given to the files install ``DESTINATION`` may +use "generator expressions" with the syntax ``$<...>``. See the +:manual:`cmake-generator-expressions(7)` manual for available expressions. + +Installing Directories +^^^^^^^^^^^^^^^^^^^^^^ + +.. _DIRECTORY: + +:: + + install(DIRECTORY dirs... 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. + +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. + +The list of ``dirs...`` given to ``DIRECTORY`` and the install destination +given to the directory install ``DESTINATION`` may use "generator expressions" +with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` +manual for available expressions. + +Custom Installation Logic +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. _CODE: +.. _SCRIPT: + +:: + + 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. + +The contents of ``SCRIPT`` or ``CODE`` may use "generator expressions" with +the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` +manual for available expressions. + +Installing Exports +^^^^^^^^^^^^^^^^^^ + +.. _EXPORT: + +:: + + 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``. + +When a ``COMPONENT`` option is given, the listed ``<component>`` implicitly +depends on all components mentioned in the export set. The exported +``<name>.cmake`` file will require each of the exported components to be +present in order for dependent projects to build properly. For example, a +project may define components ``Runtime`` and ``Development``, with shared +libraries going into the ``Runtime`` component and static libraries and +headers going into the ``Development`` component. The export set would also +typically be part of the ``Development`` component, but it would export +targets from both the ``Runtime`` and ``Development`` components. Therefore, +the ``Runtime`` component would need to be installed if the ``Development`` +component was installed, but not vice versa. If the ``Development`` component +was installed without the ``Runtime`` component, dependent projects that try +to link against it would have build errors. Package managers, such as APT and +RPM, typically handle this by listing the ``Runtime`` component as a dependency +of the ``Development`` component in the package metadata, ensuring that the +library is always installed if the headers and CMake export file are present. + +In addition to cmake language files, the ``EXPORT_ANDROID_MK`` mode maybe +used to specify an export to the android ndk build system. This mode +accepts the same options as the normal export mode. The Android +NDK supports the use of prebuilt libraries, both static and shared. This +allows cmake to build the libraries of a project and make them available +to an ndk build system complete with transitive dependencies, include flags +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 myexp 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 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +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..1850be6 --- /dev/null +++ b/Help/command/install_files.rst @@ -0,0 +1,39 @@ +install_files +------------- + +Deprecated. 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..79aa486 --- /dev/null +++ b/Help/command/install_programs.rst @@ -0,0 +1,34 @@ +install_programs +---------------- + +Deprecated. 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..49ca696 --- /dev/null +++ b/Help/command/install_targets.rst @@ -0,0 +1,17 @@ +install_targets +--------------- + +Deprecated. 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..1dce9a0 --- /dev/null +++ b/Help/command/link_directories.rst @@ -0,0 +1,51 @@ +link_directories +---------------- + +Add directories in which the linker will look for libraries. + +:: + + link_directories([AFTER|BEFORE] directory1 [directory2 ...]) + +Add the paths in which the linker should search for libraries. +Relative paths given to this command are interpreted as relative to +the current source directory, see :policy:`CMP0015`. + +The directories are added to the :prop_dir:`LINK_DIRECTORIES` directory +property for the current ``CMakeLists.txt`` file, converting relative +paths to absolute as needed. +The command will apply only to targets created after it is called. + +By default the directories specified are appended onto the current list of +directories. This default behavior can be changed by setting +:variable:`CMAKE_LINK_DIRECTORIES_BEFORE` to ``ON``. By using +``AFTER`` or ``BEFORE`` explicitly, you can select between appending and +prepending, independent of the default. + +Arguments to ``link_directories`` may use "generator expressions" with +the syntax "$<...>". See the :manual:`cmake-generator-expressions(7)` +manual for available expressions. See the :manual:`cmake-buildsystem(7)` +manual for more on defining buildsystem properties. + +.. note:: + + This command is rarely necessary and should be avoided where there are + other choices. Prefer to pass full absolute paths to libraries where + possible, since this ensures the correct library will always be linked. + The :command:`find_library` command provides the full path, which can + generally be used directly in calls to :command:`target_link_libraries`. + Situations where a library search path may be needed include: + + - Project generators like Xcode where the user can switch target + architecture at build time, but a full path to a library cannot + be used because it only provides one architecture (i.e. it is not + a universal binary). + - Libraries may themselves have other private library dependencies + that expect to be found via ``RPATH`` mechanisms, but some linkers + are not able to fully decode those paths (e.g. due to the presence + of things like ``$ORIGIN``). + + If a library search path must be provided, prefer to localize the effect + where possible by using the :command:`target_link_directories` command + rather than ``link_directories()``. The target-specific command can also + control how the search directories propagate to other dependent targets. diff --git a/Help/command/link_libraries.rst b/Help/command/link_libraries.rst new file mode 100644 index 0000000..fd5dc37 --- /dev/null +++ b/Help/command/link_libraries.rst @@ -0,0 +1,19 @@ +link_libraries +-------------- + +Link libraries to all targets added later. + +:: + + 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..ad2c428 --- /dev/null +++ b/Help/command/list.rst @@ -0,0 +1,275 @@ +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(`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``, ``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: + +:: + + list(LENGTH <list> <output variable>) + +Returns the list's length. + +.. _GET: + +:: + + list(GET <list> <element index> [<element index> ...] <output variable>) + +Returns the list of elements specified by indices from the list. + +.. _JOIN: + +:: + + list(JOIN <list> <glue> <output variable>) + +Returns a string joining all list's elements using the glue string. +To join multiple strings, which are not part of a list, use ``JOIN`` operator +from :command:`string` command. + +.. _SUBLIST: + +:: + + list(SUBLIST <list> <begin> <length> <output variable>) + +Returns a sublist of the given list. +If ``<length>`` is 0, an empty list will be returned. +If ``<length>`` is -1 or the list is smaller than ``<begin>+<length>`` then +the remaining elements of the list starting at ``<begin>`` will be returned. + +Search +^^^^^^ + +.. _FIND: + +:: + + 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: + +:: + + list(APPEND <list> [<element> ...]) + +Appends elements to the list. + +.. _FILTER: + +:: + + list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>) + +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: + +:: + + list(INSERT <list> <element_index> <element> [<element> ...]) + +Inserts elements to the list to the specified location. + +.. _REMOVE_ITEM: + +:: + + list(REMOVE_ITEM <list> <value> [<value> ...]) + +Removes the given items from the list. + +.. _REMOVE_AT: + +:: + + list(REMOVE_AT <list> <index> [<index> ...]) + +Removes items at given indices from the list. + +.. _REMOVE_DUPLICATES: + +:: + + list(REMOVE_DUPLICATES <list>) + +Removes duplicated items in the list. + +.. _TRANSFORM: + +:: + + list(TRANSFORM <list> <ACTION> [<SELECTOR>] + [OUTPUT_VARIABLE <output variable>]) + +Transforms the list by applying an action to all or, by specifying a +``<SELECTOR>``, to the selected elements of the list, storing result in-place +or in the specified output variable. + +.. note:: + + ``TRANSFORM`` sub-command does not change the number of elements of the + list. If a ``<SELECTOR>`` is specified, only some elements will be changed, + the other ones will remain same as before the transformation. + +``<ACTION>`` specify the action to apply to the elements of list. +The actions have exactly the same semantics as sub-commands of +:command:`string` command. + +The ``<ACTION>`` may be one of: + +``APPEND``, ``PREPEND``: Append, prepend specified value to each element of +the list. :: + + list(TRANSFORM <list> <APPEND|PREPEND> <value> ...) + +``TOUPPER``, ``TOLOWER``: Convert each element of the list to upper, lower +characters. :: + + list(TRANSFORM <list> <TOLOWER|TOUPPER> ...) + +``STRIP``: Remove leading and trailing spaces from each element of the +list. :: + + list(TRANSFORM <list> STRIP ...) + +``GENEX_STRIP``: Strip any +:manual:`generator expressions <cmake-generator-expressions(7)>` from each +element of the list. :: + + 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). :: + + list(TRANSFORM <list> REPLACE <regular_expression> + <replace_expression> ...) + +``<SELECTOR>`` select which elements of the list will be transformed. Only one +type of selector can be specified at a time. + +The ``<SELECTOR>`` may be one of: + +``AT``: Specify a list of indexes. :: + + list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...) + +``FOR``: Specify a range with, optionally, an increment used to iterate over +the range. :: + + list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...) + +``REGEX``: Specify a regular expression. Only elements matching the regular +expression will be transformed. :: + + list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...) + + +Ordering +^^^^^^^^ + +.. _REVERSE: + +:: + + list(REVERSE <list>) + +Reverses the contents of the list in-place. + +.. _SORT: + +:: + + list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>]) + +Sorts the list in-place alphabetically. +Use the option ``<compare>`` to select the compare type for sorting. +The ``<compare>`` option may be one of: + +* ``STRING``: Sorts a list of strings alphabetically. +* ``FILE_BASENAME``: Sort a list of pathnames of files by their basenames. + +Use the option ``<case>`` to select a case sensitive or case insensitive sort mode. +The ``<case>`` option may be one of: + +* ``SENSITIVE``: Sorts the list alphabetically. +* ``INSENSITIVE``: Sorts the list alphabetically in descending order. + +Use the option ``<order>`` to select a case sensitive or case insensitive sort mode. +The ``<order>`` option may be one of: + +* ``ASCENDING``: Sorts the list in ascending order. +* ``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..f113447 --- /dev/null +++ b/Help/command/load_cache.rst @@ -0,0 +1,27 @@ +load_cache +---------- + +Load in the values from another project's CMake cache. + +:: + + load_cache(pathToCacheFile READ_WITH_PREFIX + prefix entry1...) + +Read 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. + +:: + + load_cache(pathToCacheFile [EXCLUDE entry1...] + [INCLUDE_INTERNALS entry1...]) + +Load 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..a1576e8 --- /dev/null +++ b/Help/command/load_command.rst @@ -0,0 +1,23 @@ +load_command +------------ + +Disallowed. 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..6bee69c --- /dev/null +++ b/Help/command/macro.rst @@ -0,0 +1,76 @@ +macro +----- + +Start recording a macro for later invocation as a command:: + + macro(<name> [arg1 [arg2 [arg3 ...]]]) + COMMAND1(ARGS ...) + COMMAND2(ARGS ...) + ... + endmacro(<name>) + +Define a macro named ``<name>`` that takes arguments named ``arg1``, +``arg2``, ``arg3``, (...). +Commands listed after macro, but before the matching +:command:`endmacro()`, are not invoked until the macro is invoked. +When it is invoked, the commands recorded in the macro are first +modified by replacing formal parameters (``${arg1}``) with the arguments +passed, and then invoked as normal commands. +In addition to referencing the formal parameters you can reference the +values ``${ARGC}`` which will be set to the number of arguments passed +into the function as well as ``${ARGV0}``, ``${ARGV1}``, ``${ARGV2}``, +... which will have the actual values of the arguments passed in. +This facilitates creating macros with optional arguments. +Additionally ``${ARGV}`` holds the list of all arguments given to the +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. + +See the :command:`cmake_policy()` command documentation for the behavior +of policies inside macros. + +Macro Argument Caveats +^^^^^^^^^^^^^^^^^^^^^^ + +Note that the parameters to a macro and values such as ``ARGN`` are +not variables in the usual CMake sense. They are string +replacements much like the C preprocessor would do with a macro. +Therefore you will NOT be able to use commands like:: + + 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:: + + 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:: + + macro(_BAR) + foreach(arg IN LISTS ARGN) + [...] + 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 be expecting. +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..27ecf51 --- /dev/null +++ b/Help/command/make_directory.rst @@ -0,0 +1,12 @@ +make_directory +-------------- + +Deprecated. 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..c3f94fc --- /dev/null +++ b/Help/command/mark_as_advanced.rst @@ -0,0 +1,19 @@ +mark_as_advanced +---------------- + +Mark cmake cached variables as advanced. + +:: + + mark_as_advanced([CLEAR|FORCE] VAR [VAR2 ...]) + +Mark the named cached variables as advanced. An advanced variable +will not be displayed in any of the cmake GUIs unless the show +advanced option is on. If ``CLEAR`` is the first argument advanced +variables are changed back to unadvanced. If ``FORCE`` is the first +argument, then the variable is made advanced. If neither ``FORCE`` nor +``CLEAR`` is specified, new values will be marked as advanced, but if the +variable already has an advanced/non-advanced state, it will not be +changed. + +It does nothing in script mode. diff --git a/Help/command/math.rst b/Help/command/math.rst new file mode 100644 index 0000000..63af931 --- /dev/null +++ b/Help/command/math.rst @@ -0,0 +1,30 @@ +math +---- + +Mathematical expressions. + +:: + + math(EXPR <output-variable> <math-expression> [OUTPUT_FORMAT <format>]) + +``EXPR`` evaluates mathematical expression and returns result in the +output variable. Example mathematical expression is ``5 * (10 + 13)``. +Supported operators are ``+``, ``-``, ``*``, ``/``, ``%``, ``|``, ``&``, +``^``, ``~``, ``<<``, ``>>``, and ``(...)``. They have the same meaning +as they do in C code. + +Numeric constants are evaluated in decimal or hexadecimal representation. + +The result is formatted according to the option "OUTPUT_FORMAT" , +where ``<format>`` is one of: +:: + + HEXADECIMAL = Result in output variable will be formatted in C code + Hexadecimal notation. + DECIMAL = Result in output variable will be formatted in decimal notation. + + +For example:: + + math(EXPR value "100 * 0xA" DECIMAL) results in value is set to "1000" + math(EXPR value "100 * 0xA" HEXADECIMAL) results in value is set to "0x3e8" diff --git a/Help/command/message.rst b/Help/command/message.rst new file mode 100644 index 0000000..04c62fd --- /dev/null +++ b/Help/command/message.rst @@ -0,0 +1,33 @@ +message +------- + +Display a message to the user. + +:: + + message([<mode>] "message to display" ...) + +The optional ``<mode>`` keyword determines the type of message: + +:: + + (none) = Important information + STATUS = Incidental information + WARNING = CMake Warning, continue processing + AUTHOR_WARNING = CMake Warning (dev), continue processing + SEND_ERROR = CMake Error, continue processing, + but skip generation + FATAL_ERROR = CMake Error, stop processing and generation + DEPRECATION = CMake Deprecation Error or Warning if variable + CMAKE_ERROR_DEPRECATED or CMAKE_WARN_DEPRECATED + is enabled, respectively, else no message. + +The CMake command-line tool displays STATUS messages on stdout and all +other message types on stderr. The CMake GUI displays all messages in +its log area. The interactive dialogs (ccmake and CMakeSetup) show +STATUS messages one at a time on a status line and other messages in +interactive pop-up boxes. + +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. diff --git a/Help/command/option.rst b/Help/command/option.rst new file mode 100644 index 0000000..4fabb87 --- /dev/null +++ b/Help/command/option.rst @@ -0,0 +1,17 @@ +option +------ + +Provides an option that the user can optionally select. + +:: + + option(<option_variable> "help string describing option" + [initial value]) + +Provide an option for the user to select as ``ON`` or ``OFF``. If no +initial value is provided, ``OFF`` is used. If the option is already +set as a normal variable then the command does nothing +(see policy :policy:`CMP0077`). + +If you have options that depend on the values of other options, see +the module help for :module:`CMakeDependentOption`. diff --git a/Help/command/output_required_files.rst b/Help/command/output_required_files.rst new file mode 100644 index 0000000..5e13557 --- /dev/null +++ b/Help/command/output_required_files.rst @@ -0,0 +1,19 @@ +output_required_files +--------------------- + +Disallowed. 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..c1de057 --- /dev/null +++ b/Help/command/project.rst @@ -0,0 +1,88 @@ +project +------- + +Sets project details such as name, version, etc. and enables languages. + +.. code-block:: cmake + + project(<PROJECT-NAME> [LANGUAGES] [<language-name>...]) + project(<PROJECT-NAME> + [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]] + [DESCRIPTION <project-description-string>] + [HOMEPAGE_URL <url-string>] + [LANGUAGES <language-name>...]) + +Sets the name of the project and stores the name in the +:variable:`PROJECT_NAME` variable. Additionally this sets variables + +* :variable:`PROJECT_SOURCE_DIR`, + :variable:`<PROJECT-NAME>_SOURCE_DIR` +* :variable:`PROJECT_BINARY_DIR`, + :variable:`<PROJECT-NAME>_BINARY_DIR` + +If ``VERSION`` is specified, given components must be non-negative integers. +If ``VERSION`` is not specified, the default version is the empty string. +The ``VERSION`` option may not be used unless policy :policy:`CMP0048` is +set to ``NEW``. + +The :command:`project()` command stores the version number and its components +in variables + +* :variable:`PROJECT_VERSION`, + :variable:`<PROJECT-NAME>_VERSION` +* :variable:`PROJECT_VERSION_MAJOR`, + :variable:`<PROJECT-NAME>_VERSION_MAJOR` +* :variable:`PROJECT_VERSION_MINOR`, + :variable:`<PROJECT-NAME>_VERSION_MINOR` +* :variable:`PROJECT_VERSION_PATCH`, + :variable:`<PROJECT-NAME>_VERSION_PATCH` +* :variable:`PROJECT_VERSION_TWEAK`, + :variable:`<PROJECT-NAME>_VERSION_TWEAK` + +Variables corresponding to unspecified versions are set to the empty string +(if policy :policy:`CMP0048` is set to ``NEW``). + +If the optional ``DESCRIPTION`` is given, then :variable:`PROJECT_DESCRIPTION` +and :variable:`<PROJECT-NAME>_DESCRIPTION` will be set to its argument. +The description is expected to be a relatively short string, usually no more +than a few words. + +The optional ``HOMEPAGE_URL`` sets the analogous variables +:variable:`PROJECT_HOMEPAGE_URL` and :variable:`<PROJECT-NAME>_HOMEPAGE_URL`. +When this option is given, the URL provided should be the canonical home for +the project. + +Note that the description and homepage URL may be used as defaults for +things like packaging meta-data, documentation, etc. + +Optionally you can specify which languages your project supports. +Example languages include ``C``, ``CXX`` (i.e. C++), ``CUDA``, +``Fortran``, and ``ASM``. +By default ``C`` and ``CXX`` are enabled if no language options are +given. Specify language ``NONE``, or use the ``LANGUAGES`` keyword +and list no languages, to skip enabling any languages. + +If enabling ``ASM``, list it last so that CMake can check whether +compilers for other languages like ``C`` work for assembly too. + +If a variable exists called :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, +the file pointed to by that variable will be included as the last step of the +project command. + +The top-level ``CMakeLists.txt`` file for a project must contain a +literal, direct call to the :command:`project` command; loading one +through the :command:`include` command is not sufficient. If no such +call exists CMake will implicitly add one to the top that enables the +default languages (``C`` and ``CXX``). The name of the project set in +the top level ``CMakeLists.txt`` file is available from the +:variable:`CMAKE_PROJECT_NAME` variable, its description from +:variable:`CMAKE_PROJECT_DESCRIPTION`, its homepage URL from +:variable:`CMAKE_PROJECT_HOMEPAGE_URL` and its version from +:variable:`CMAKE_PROJECT_VERSION`. + +.. note:: + Call the :command:`cmake_minimum_required` command at the beginning + of the top-level ``CMakeLists.txt`` file even before calling the + ``project()`` command. It is important to establish version and + policy settings before invoking other commands whose behavior they + may affect. See also policy :policy:`CMP0000`. diff --git a/Help/command/qt_wrap_cpp.rst b/Help/command/qt_wrap_cpp.rst new file mode 100644 index 0000000..3843bf5 --- /dev/null +++ b/Help/command/qt_wrap_cpp.rst @@ -0,0 +1,12 @@ +qt_wrap_cpp +----------- + +Create Qt Wrappers. + +:: + + qt_wrap_cpp(resultingLibraryName DestName + SourceLists ...) + +Produce 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. diff --git a/Help/command/qt_wrap_ui.rst b/Help/command/qt_wrap_ui.rst new file mode 100644 index 0000000..f731ed9 --- /dev/null +++ b/Help/command/qt_wrap_ui.rst @@ -0,0 +1,14 @@ +qt_wrap_ui +---------- + +Create Qt user interfaces Wrappers. + +:: + + qt_wrap_ui(resultingLibraryName HeadersDestName + SourcesDestName SourceLists ...) + +Produce .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. diff --git a/Help/command/remove.rst b/Help/command/remove.rst new file mode 100644 index 0000000..4628277 --- /dev/null +++ b/Help/command/remove.rst @@ -0,0 +1,12 @@ +remove +------ + +Deprecated. 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..ea18918 --- /dev/null +++ b/Help/command/remove_definitions.rst @@ -0,0 +1,11 @@ +remove_definitions +------------------ + +Removes -D define flags added by :command:`add_definitions`. + +:: + + 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..e49fb3c --- /dev/null +++ b/Help/command/return.rst @@ -0,0 +1,18 @@ +return +------ + +Return from a file, directory or function. + +:: + + 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``, +control is returned to the parent directory if there is one. If return is +called in a function, control is returned to the caller of the function. +Note that a macro is not a function and does not handle return like a +function does. diff --git a/Help/command/separate_arguments.rst b/Help/command/separate_arguments.rst new file mode 100644 index 0000000..47982a5 --- /dev/null +++ b/Help/command/separate_arguments.rst @@ -0,0 +1,36 @@ +separate_arguments +------------------ + +Parse space-separated arguments into a semicolon-separated list. + +:: + + separate_arguments(<var> <NATIVE|UNIX|WINDOWS>_COMMAND "<args>") + +Parses a UNIX- or Windows-style command-line string "<args>" and +stores a semicolon-separated list of the arguments in ``<var>``. The +entire command line must be given in one "<args>" argument. + +The ``UNIX_COMMAND`` mode separates arguments by unquoted whitespace. It +recognizes both single-quote and double-quote pairs. A backslash +escapes the next literal character (``\"`` is ``"``); there are no special +escapes (``\n`` is just ``n``). + +The ``WINDOWS_COMMAND`` mode parses a Windows command-line using the same +syntax the runtime library uses to construct argv at startup. It +separates arguments by whitespace that is not double-quoted. +Backslashes are literal unless they precede double-quotes. See the +MSDN article `Parsing C Command-Line Arguments`_ for details. + +The ``NATIVE_COMMAND`` mode parses a Windows command-line if the host +system is Windows, and a UNIX command-line otherwise. + +.. _`Parsing C Command-Line Arguments`: https://msdn.microsoft.com/library/a1y7w461.aspx + +:: + + 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..b24ebef --- /dev/null +++ b/Help/command/set.rst @@ -0,0 +1,91 @@ +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:`;-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 +^^^^^^^^^^^^^^^^^^^ + +:: + + set(<variable> <value>... [PARENT_SCOPE]) + +Set 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 +^^^^^^^^^^^^^^^ + +:: + + set(<variable> <value>... CACHE <type> <docstring> [FORCE]) + +Set 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 +^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + set(ENV{<variable>} <value>...) + +Set the current process environment ``<variable>`` to the given value. diff --git a/Help/command/set_directory_properties.rst b/Help/command/set_directory_properties.rst new file mode 100644 index 0000000..42e7fd7 --- /dev/null +++ b/Help/command/set_directory_properties.rst @@ -0,0 +1,11 @@ +set_directory_properties +------------------------ + +Set properties of the current directory and subdirectories in key-value pairs. + +:: + + set_directory_properties(PROPERTIES prop1 value1 prop2 value2) + +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..c89e1ce --- /dev/null +++ b/Help/command/set_property.rst @@ -0,0 +1,75 @@ +set_property +------------ + +Set a named property in a given scope. + +:: + + set_property(<GLOBAL | + DIRECTORY [dir] | + TARGET [target1 [target2 ...]] | + SOURCE [src1 [src2 ...]] | + INSTALL [file1 [file2 ...]] | + TEST [test1 [test2 ...]] | + CACHE [entry1 [entry2 ...]]> + [APPEND] [APPEND_STRING] + PROPERTY <name> [value1 [value2 ...]]) + +Set one property on zero or more objects of a scope. The first +argument determines the scope in which the property is set. It must +be one of the following: + +``GLOBAL`` + Scope is unique and does not accept a name. + +``DIRECTORY`` + Scope defaults to the current directory but another + directory (already processed by CMake) may be named by full or + relative path. + +``TARGET`` + Scope may name zero or more existing targets. + +``SOURCE`` + Scope may name zero or more source files. Note that source + file properties are visible only to targets added in the same + directory (CMakeLists.txt). + +``INSTALL`` + 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. + +``CACHE`` + Scope must name zero or more cache existing entries. + +The required ``PROPERTY`` option is immediately followed by the name of +the property to set. Remaining arguments are used to compose the +property value in the form of a semicolon-separated list. + +If the ``APPEND`` option is given the list is appended to any existing +property value. If the ``APPEND_STRING`` option is given the string is +appended to any existing property value as string, i.e. it results in a +longer string and not a list of strings. When using ``APPEND`` or +``APPEND_STRING`` with a property defined to support ``INHERITED`` +behavior (see :command:`define_property`), no inheriting occurs when +finding the initial value to append to. If the property is not already +directly set in the nominated scope, the command will behave as though +``APPEND`` or ``APPEND_STRING`` had not been given. + +See the :manual:`cmake-properties(7)` manual for a list of properties +in each scope. diff --git a/Help/command/set_source_files_properties.rst b/Help/command/set_source_files_properties.rst new file mode 100644 index 0000000..b4904e8 --- /dev/null +++ b/Help/command/set_source_files_properties.rst @@ -0,0 +1,15 @@ +set_source_files_properties +--------------------------- + +Source files can have properties that affect how they are built. + +:: + + set_source_files_properties([file1 [file2 [...]]] + PROPERTIES prop1 value1 + [prop2 value2 [...]]) + +Set properties associated with source files using a key/value paired +list. See :ref:`Source File Properties` for the list of properties known +to CMake. Source file properties are visible only to targets added +in the same directory (CMakeLists.txt). diff --git a/Help/command/set_target_properties.rst b/Help/command/set_target_properties.rst new file mode 100644 index 0000000..7db952d --- /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. + +:: + + set_target_properties(target1 target2 ... + PROPERTIES prop1 value1 + prop2 value2 ...) + +Set 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..3efb165 --- /dev/null +++ b/Help/command/set_tests_properties.rst @@ -0,0 +1,14 @@ +set_tests_properties +-------------------- + +Set a property of the tests. + +:: + + set_tests_properties(test1 [test2...] PROPERTIES prop1 value1 prop2 value2) + +Set a property for the tests. If the test is not found, CMake +will report an error. +:manual:`Generator expressions <cmake-generator-expressions(7)>` will be +expanded the same as supported by the test's :command:`add_test` call. See +:ref:`Test Properties` for the list of properties known to CMake. diff --git a/Help/command/site_name.rst b/Help/command/site_name.rst new file mode 100644 index 0000000..e17c1ee --- /dev/null +++ b/Help/command/site_name.rst @@ -0,0 +1,8 @@ +site_name +--------- + +Set the given variable to the name of the computer. + +:: + + site_name(variable) diff --git a/Help/command/source_group.rst b/Help/command/source_group.rst new file mode 100644 index 0000000..938ca40 --- /dev/null +++ b/Help/command/source_group.rst @@ -0,0 +1,58 @@ +source_group +------------ + +Define a grouping for source files in IDE project generation. +There are two different signatures to create source groups. + +:: + + 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`` + 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`` + 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 backslashes +to specify subgroups: + +.. code-block:: cmake + + source_group(outer\\inner ...) + source_group(TREE <root> PREFIX sources\\inc ...) + +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..29a153a --- /dev/null +++ b/Help/command/string.rst @@ -0,0 +1,430 @@ +string +------ + +String operations. + +Synopsis +^^^^^^^^ + +.. parsed-literal:: + + `Search and Replace`_ + string(`FIND`_ <string> <substring> <out-var> [...]) + string(`REPLACE`_ <match-string> <replace-string> <out-var> <input>...) + + `Regular Expressions`_ + string(`REGEX MATCH`_ <match-regex> <out-var> <input>...) + string(`REGEX MATCHALL`_ <match-regex> <out-var> <input>...) + string(`REGEX REPLACE`_ <match-regex> <replace-expr> <out-var> <input>...) + + `Manipulation`_ + string(`APPEND`_ <string-var> [<input>...]) + string(`PREPEND`_ <string-var> [<input>...]) + string(`CONCAT`_ <out-var> [<input>...]) + string(`JOIN`_ <glue> <out-var> [<input>...]) + string(`TOLOWER`_ <string1> <out-var>) + string(`TOUPPER`_ <string1> <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>) + + `Comparison`_ + string(`COMPARE`_ <op> <string1> <string2> <out-var>) + + `Hashing`_ + string(`\<HASH\> <HASH_>`_ <out-var> <input>) + + `Generation`_ + string(`ASCII`_ <number>... <out-var>) + string(`CONFIGURE`_ <string1> <out-var> [...]) + string(`MAKE_C_IDENTIFIER`_ <string> <out-var>) + string(`RANDOM`_ [<option>...] <out-var>) + string(`TIMESTAMP`_ <out-var> [<format string>] [UTC]) + string(`UUID`_ <out-var> ...) + +Search and Replace +^^^^^^^^^^^^^^^^^^ + +.. _FIND: + +:: + + 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. + +.. _REPLACE: + +:: + + 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. + +Regular Expressions +^^^^^^^^^^^^^^^^^^^ + +.. _`REGEX MATCH`: + +:: + + 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. + +.. _`REGEX MATCHALL`: + +:: + + 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`: + +:: + + string(REGEX REPLACE <regular_expression> + <replace_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 replace expression may refer to paren-delimited subexpressions of the +match using ``\1``, ``\2``, ..., ``\9``. Note that two backslashes (``\\1``) +are required in CMake code to get a backslash through argument parsing. + +.. _`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 +``[ ]`` + 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. Additionally it is saved + by all regular expression-related commands, including + e.g. :command:`if(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``. + +Backslash (``\``) characters in regular expressions are interpreted +literally and do not escape anything or represent placeholders. +However, 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. + +Manipulation +^^^^^^^^^^^^ + +.. _APPEND: + +:: + + string(APPEND <string variable> [<input>...]) + +Append all the input arguments to the string. + +.. _PREPEND: + +:: + + string(PREPEND <string variable> [<input>...]) + +Prepend all the input arguments to the string. + +.. _CONCAT: + +:: + + string(CONCAT <output variable> [<input>...]) + +Concatenate all the input arguments together and store +the result in the named output variable. + +.. _JOIN: + +:: + + string(JOIN <glue> <output variable> [<input>...]) + +Join all the input arguments together using the glue +string and store the result in the named output variable. + +To join list's elements, use preferably the ``JOIN`` operator +from :command:`list` command. This allows for the elements to have +special characters like ``;`` in them. + +.. _TOLOWER: + +:: + + string(TOLOWER <string1> <output variable>) + +Convert string to lower characters. + +.. _TOUPPER: + +:: + + string(TOUPPER <string1> <output variable>) + +Convert string to upper characters. + +.. _LENGTH: + +:: + + string(LENGTH <string> <output variable>) + +Store in an output variable a given string's length. + +.. _SUBSTRING: + +:: + + string(SUBSTRING <string> <begin> <length> <output variable>) + +Store in an output variable a substring of a given string. If length is +``-1`` the remainder of the string starting at begin will be returned. +If string is shorter than length then end of string is used instead. + +.. note:: + CMake 3.1 and below reported an error if length pointed past + the end of string. + +.. _STRIP: + +:: + + string(STRIP <string> <output variable>) + +Store in an output variable a substring of a given string with leading and +trailing spaces removed. + +.. _GENEX_STRIP: + +:: + + string(GENEX_STRIP <input string> <output variable>) + +Strip any :manual:`generator expressions <cmake-generator-expressions(7)>` +from the ``input string`` and store the result in the ``output variable``. + +Comparison +^^^^^^^^^^ + +.. _COMPARE: + +:: + + 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. + +.. _`Supported Hash Algorithms`: + +Hashing +^^^^^^^ + +.. _`HASH`: + +:: + + 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. + +Generation +^^^^^^^^^^ + +.. _ASCII: + +:: + + string(ASCII <number> [<number> ...] <output variable>) + +Convert all numbers into corresponding ASCII characters. + +.. _CONFIGURE: + +:: + + string(CONFIGURE <string1> <output variable> + [@ONLY] [ESCAPE_QUOTES]) + +Transform a string like :command:`configure_file` transforms a file. + +.. _MAKE_C_IDENTIFIER: + +:: + + string(MAKE_C_IDENTIFIER <input 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: + +:: + + 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: + +:: + + string(TIMESTAMP <output variable> [<format string>] [UTC]) + +Write a string representation of the current date +and/or time to the output variable. + +Should the command be unable to obtain a timestamp the output variable +will be set to the empty string "". + +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. + +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. + +.. note:: + + If the ``SOURCE_DATE_EPOCH`` environment variable is set, + its value will be used instead of the current time. + See https://reproducible-builds.org/specs/source-date-epoch/ for details. + +.. _UUID: + +:: + + string(UUID <output variable> NAMESPACE <namespace> NAME <name> + TYPE <MD5|SHA1> [UPPER]) + +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. diff --git a/Help/command/subdir_depends.rst b/Help/command/subdir_depends.rst new file mode 100644 index 0000000..5676c8f --- /dev/null +++ b/Help/command/subdir_depends.rst @@ -0,0 +1,13 @@ +subdir_depends +-------------- + +Disallowed. 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..43b87d4 --- /dev/null +++ b/Help/command/subdirs.rst @@ -0,0 +1,24 @@ +subdirs +------- + +Deprecated. 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..a740117 --- /dev/null +++ b/Help/command/target_compile_definitions.rst @@ -0,0 +1,39 @@ +target_compile_definitions +-------------------------- + +Add compile definitions to a target. + +:: + + target_compile_definitions(<target> + <INTERFACE|PUBLIC|PRIVATE> [items1...] + [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) + +Specify 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>``. +(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items.) +The following arguments specify compile definitions. Repeated calls for the +same ``<target>`` append items in the order called. + +Arguments to ``target_compile_definitions`` may use "generator expressions" +with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` +manual for available expressions. See the :manual:`cmake-buildsystem(7)` +manual for more on defining buildsystem properties. + +Any leading ``-D`` on an item will be removed. Empty items are ignored. +For example, the following are all equivalent: + +.. code-block:: cmake + + target_compile_definitions(foo PUBLIC FOO) + target_compile_definitions(foo PUBLIC -DFOO) # -D removed + target_compile_definitions(foo PUBLIC "" FOO) # "" ignored + target_compile_definitions(foo PUBLIC -D FOO) # -D becomes "", then ignored diff --git a/Help/command/target_compile_features.rst b/Help/command/target_compile_features.rst new file mode 100644 index 0000000..bf413bf --- /dev/null +++ b/Help/command/target_compile_features.rst @@ -0,0 +1,33 @@ +target_compile_features +----------------------- + +Add expected compiler features to a target. + +:: + + target_compile_features(<target> <PRIVATE|PUBLIC|INTERFACE> <feature> [...]) + +Specify compiler features required when compiling a given target. If the +feature is not listed in the :variable:`CMAKE_C_COMPILE_FEATURES` variable +or :variable:`CMAKE_CXX_COMPILE_FEATURES` variable, +then an error will be reported by CMake. If the use of the feature requires +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>``. +(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items.) +Repeated calls for the same ``<target>`` append items. + +The named ``<target>`` must have been created by a command such as +:command:`add_executable` or :command:`add_library` and must not be an +: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..88b7f15 --- /dev/null +++ b/Help/command/target_compile_options.rst @@ -0,0 +1,42 @@ +target_compile_options +---------------------- + +Add compile options to a target. + +:: + + target_compile_options(<target> [BEFORE] + <INTERFACE|PUBLIC|PRIVATE> [items1...] + [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) + +Specify compile options to use when compiling a given target. The +named ``<target>`` must have been created by a command such as +:command:`add_executable` or :command:`add_library` and must not be an +:ref:`ALIAS target <Alias Targets>`. + +If ``BEFORE`` is specified, the content will be prepended to the property +instead of being appended. + +This command can be used to add any options, but +alternative commands exist to add preprocessor definitions +(:command:`target_compile_definitions` and :command:`add_compile_definitions`) +or include directories (:command:`target_include_directories` and +:command:`include_directories`). See documentation of the +:prop_dir:`directory <COMPILE_OPTIONS>` and +:prop_tgt:`target <COMPILE_OPTIONS>` ``COMPILE_OPTIONS`` properties. + +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>``. +(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items.) +The following arguments specify compile options. Repeated calls for the same +``<target>`` append items in the order called. + +Arguments to ``target_compile_options`` may use "generator expressions" +with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` +manual for available expressions. See the :manual:`cmake-buildsystem(7)` +manual for more on defining buildsystem properties. + +.. include:: OPTIONS_SHELL.txt diff --git a/Help/command/target_include_directories.rst b/Help/command/target_include_directories.rst new file mode 100644 index 0000000..e71be64 --- /dev/null +++ b/Help/command/target_include_directories.rst @@ -0,0 +1,62 @@ +target_include_directories +-------------------------- + +Add include directories to a target. + +:: + + target_include_directories(<target> [SYSTEM] [BEFORE] + <INTERFACE|PUBLIC|PRIVATE> [items1...] + [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) + +Specify 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>`. + +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:`INCLUDE_DIRECTORIES` property of ``<target>``. +``PUBLIC`` and ``INTERFACE`` items will populate the +:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` property of ``<target>``. +(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items.) +The following arguments specify include directories. + +Specified include directories may be absolute paths or relative paths. +Repeated calls for the same <target> append items in the order called. If +``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..b46aac0 --- /dev/null +++ b/Help/command/target_link_directories.rst @@ -0,0 +1,55 @@ +target_link_directories +----------------------- + +Add link directories to a target. + +:: + + target_link_directories(<target> [BEFORE] + <INTERFACE|PUBLIC|PRIVATE> [items1...] + [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) + +Specify the paths in which the linker should search for libraries when +linking a given target. Each item can be an absolute or relative path, +with the latter being interpreted as relative to the current source +directory. These items will be added to the link command. + +The named ``<target>`` must have been created by a command such as +:command:`add_executable` or :command:`add_library` and must not be an +:ref:`ALIAS target <Alias Targets>`. + +The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to +specify the scope of the items that follow them. ``PRIVATE`` and +``PUBLIC`` items will populate the :prop_tgt:`LINK_DIRECTORIES` property +of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the +:prop_tgt:`INTERFACE_LINK_DIRECTORIES` property of ``<target>`` +(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items). +Each item specifies a link directory and will be converted to an absolute +path if necessary before adding it to the relevant property. Repeated +calls for the same ``<target>`` append items in the order called. + +If ``BEFORE`` is specified, the content will be prepended to the relevant +property instead of being appended. + +Arguments to ``target_link_directories`` may use "generator expressions" +with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` +manual for available expressions. See the :manual:`cmake-buildsystem(7)` +manual for more on defining buildsystem properties. + +.. note:: + + This command is rarely necessary and should be avoided where there are + other choices. Prefer to pass full absolute paths to libraries where + possible, since this ensures the correct library will always be linked. + The :command:`find_library` command provides the full path, which can + generally be used directly in calls to :command:`target_link_libraries`. + Situations where a library search path may be needed include: + + - Project generators like Xcode where the user can switch target + architecture at build time, but a full path to a library cannot + be used because it only provides one architecture (i.e. it is not + a universal binary). + - Libraries may themselves have other private library dependencies + that expect to be found via ``RPATH`` mechanisms, but some linkers + are not able to fully decode those paths (e.g. due to the presence + of things like ``$ORIGIN``). diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst new file mode 100644 index 0000000..e1c374e --- /dev/null +++ b/Help/command/target_link_libraries.rst @@ -0,0 +1,284 @@ +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:: + + 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. + +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``). + +* **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 Mac OSX 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. + + 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. + +* **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``). + +* **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. + +* 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>`. + +Items containing ``::``, such as ``Foo::Bar``, are assumed to be +:ref:`IMPORTED <Imported Targets>` or :ref:`ALIAS <Alias Targets>` library +target names and will cause an error if no such target exists. +See policy :policy:`CMP0028`. + +Arguments to ``target_link_libraries`` may use "generator expressions" +with the syntax ``$<...>``. Note however, that generator expressions +will not be used in OLD handling of :policy:`CMP0003` or :policy:`CMP0004`. +See the :manual:`cmake-generator-expressions(7)` manual for available +expressions. See the :manual:`cmake-buildsystem(7)` manual for more on +defining buildsystem properties. + +Libraries for a Target and/or its Dependents +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + 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 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + 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) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + 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) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + 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 +^^^^^^^^^^^^^^^^^^^^^^^^ + +: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..8f47180 --- /dev/null +++ b/Help/command/target_link_options.rst @@ -0,0 +1,42 @@ +target_link_options +------------------- + +Add link options to a target. + +:: + + target_link_options(<target> [BEFORE] + <INTERFACE|PUBLIC|PRIVATE> [items1...] + [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) + +Specify link options to use when linking a given target. The +named ``<target>`` must have been created by a command such as +:command:`add_executable` or :command:`add_library` and must not be an +:ref:`ALIAS target <Alias Targets>`. + +If ``BEFORE`` is specified, the content will be prepended to the property +instead of being appended. + +This command can be used to add any options, but +alternative commands exist to add libraries +(:command:`target_link_libraries` and :command:`link_libraries`). +See documentation of the :prop_dir:`directory <LINK_OPTIONS>` and +:prop_tgt:`target <LINK_OPTIONS>` ``LINK_OPTIONS`` properties. + +The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to +specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC`` +items will populate the :prop_tgt:`LINK_OPTIONS` property of +``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the +:prop_tgt:`INTERFACE_LINK_OPTIONS` property of ``<target>``. +(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items.) +The following arguments specify link options. Repeated calls for the same +``<target>`` append items in the order called. + +Arguments to ``target_link_options`` may use "generator expressions" +with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` +manual for available expressions. See the :manual:`cmake-buildsystem(7)` +manual for more on defining buildsystem properties. + +.. include:: LINK_OPTIONS_LINKER.txt + +.. include:: OPTIONS_SHELL.txt diff --git a/Help/command/target_sources.rst b/Help/command/target_sources.rst new file mode 100644 index 0000000..5dd8d86 --- /dev/null +++ b/Help/command/target_sources.rst @@ -0,0 +1,34 @@ +target_sources +-------------- + +Add sources to a target. + +:: + + target_sources(<target> + <INTERFACE|PUBLIC|PRIVATE> [items1...] + [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) + +Specify sources to use when compiling a given target. Relative +source file paths are interpreted as being relative to the current +source directory (i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`). The +named ``<target>`` must have been created by a command such as +:command:`add_executable` or :command:`add_library` and must not be an +:ref:`ALIAS target <Alias Targets>`. + +The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to +specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC`` +items will populate the :prop_tgt:`SOURCES` property of +``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the +:prop_tgt:`INTERFACE_SOURCES` property of ``<target>``. +(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items.) +The following arguments specify sources. Repeated calls for the same +``<target>`` append items in the order called. + +Arguments to ``target_sources`` may use "generator expressions" +with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` +manual for available expressions. See the :manual:`cmake-buildsystem(7)` +manual for more on defining buildsystem properties. + +See also the :policy:`CMP0076` policy for older behavior related to the +handling of relative source file paths. diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst new file mode 100644 index 0000000..66ea3d7 --- /dev/null +++ b/Help/command/try_compile.rst @@ -0,0 +1,155 @@ +try_compile +----------- + +.. only:: html + + .. contents:: + +Try building some code. + +Try Compiling Whole Projects +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + try_compile(RESULT_VAR <bindir> <srcdir> + <projectName> [<targetName>] [CMAKE_FLAGS <flags>...] + [OUTPUT_VARIABLE <var>]) + +Try building a project. The success or failure of the ``try_compile``, +i.e. ``TRUE`` or ``FALSE`` respectively, is returned in ``RESULT_VAR``. + +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 +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + try_compile(RESULT_VAR <bindir> <srcfile|SOURCES srcfile...> + [CMAKE_FLAGS <flags>...] + [COMPILE_DEFINITIONS <defs>...] + [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 from one or more source files. The success or +failure of the ``try_compile``, i.e. ``TRUE`` or ``FALSE`` respectively, is +returned in ``RESULT_VAR``. + +In this form the user need only supply one or more source files that include a +definition for ``main``. CMake will create a ``CMakeLists.txt`` file to build +the source(s) as an executable that looks something like this:: + + add_definitions(<expanded COMPILE_DEFINITIONS from caller>) + include_directories(${INCLUDE_DIRECTORIES}) + link_directories(${LINK_DIRECTORIES}) + add_executable(cmTryCompileExec <srcfile>...) + 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 ``add_definitions`` + in the generated test project. + +``COPY_FILE <fileName>`` + Copy the linked executable 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. + +``OUTPUT_VARIABLE <var>`` + Store the output from the build process the given variable. + +``<LANG>_STANDARD <std>`` + Specify the :prop_tgt:`C_STANDARD`, :prop_tgt:`CXX_STANDARD`, + or :prop_tgt:`CUDA_STANDARD` target property of the generated project. + +``<LANG>_STANDARD_REQUIRED <bool>`` + Specify the :prop_tgt:`C_STANDARD_REQUIRED`, + :prop_tgt:`CXX_STANDARD_REQUIRED`, or :prop_tgt:`CUDA_STANDARD_REQUIRED` + target property of the generated project. + +``<LANG>_EXTENSIONS <bool>`` + Specify the :prop_tgt:`C_EXTENSIONS`, :prop_tgt:`CXX_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 RESULT_VAR)`` 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 +^^^^^^^^^^^^^^^^^^^^^^^ + +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_ENABLE_EXPORTS` +* :variable:`CMAKE_LINK_SEARCH_START_STATIC` +* :variable:`CMAKE_LINK_SEARCH_END_STATIC` +* :variable:`CMAKE_POSITION_INDEPENDENT_CODE` + +If :policy:`CMP0056` is set to ``NEW``, then +:variable:`CMAKE_EXE_LINKER_FLAGS` is passed in as well. + +The current setting of :policy:`CMP0065` is set in the generated project. + +Set the :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` variable to choose +a build configuration. + +Set the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable to specify +the type of target used for the source file signature. + +Set the :variable:`CMAKE_TRY_COMPILE_PLATFORM_VARIABLES` variable to specify +variables that must be propagated into the test project. This variable is +meant for use only in toolchain files. + +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_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). diff --git a/Help/command/try_run.rst b/Help/command/try_run.rst new file mode 100644 index 0000000..e3bd57d --- /dev/null +++ b/Help/command/try_run.rst @@ -0,0 +1,98 @@ +try_run +------- + +.. only:: html + + .. contents:: + +Try compiling and then running some code. + +Try Compiling and Running Source Files +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + try_run(RUN_RESULT_VAR COMPILE_RESULT_VAR + bindir srcfile [CMAKE_FLAGS <flags>...] + [COMPILE_DEFINITIONS <defs>...] + [LINK_LIBRARIES <libs>...] + [COMPILE_OUTPUT_VARIABLE <var>] + [RUN_OUTPUT_VARIABLE <var>] + [OUTPUT_VARIABLE <var>] + [ARGS <args>...]) + +Try compiling a ``<srcfile>``. Returns ``TRUE`` or ``FALSE`` for success +or failure in ``COMPILE_RESULT_VAR``. If the compile succeeded, runs the +executable and returns its exit code in ``RUN_RESULT_VAR``. If the +executable was built, but failed to run, then ``RUN_RESULT_VAR`` will be +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. + +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 ``add_definitions`` + in the generated test project. + +``COMPILE_OUTPUT_VARIABLE <var>`` + Report the compile step build output in a given variable. + +``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. + +``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. + +Other Behavior Settings +^^^^^^^^^^^^^^^^^^^^^^^ + +Set the :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` variable to choose +a build configuration. + +Behavior when Cross Compiling +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +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: + +``<RUN_RESULT_VAR>`` + Exit code if the executable were to be run on the target platform. + +``<RUN_RESULT_VAR>__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..c19dd31 --- /dev/null +++ b/Help/command/unset.rst @@ -0,0 +1,32 @@ +unset +----- + +Unset a variable, cache variable, or environment variable. + +:: + + 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. + +``<variable>`` can be an environment variable such as: + +:: + + unset(ENV{LD_LIBRARY_PATH}) + +in which case the variable will be removed from the current +environment. diff --git a/Help/command/use_mangled_mesa.rst b/Help/command/use_mangled_mesa.rst new file mode 100644 index 0000000..6f4d7ac --- /dev/null +++ b/Help/command/use_mangled_mesa.rst @@ -0,0 +1,15 @@ +use_mangled_mesa +---------------- + +Disallowed. 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..ee34492 --- /dev/null +++ b/Help/command/utility_source.rst @@ -0,0 +1,24 @@ +utility_source +-------------- + +Disallowed. 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..9cf9f3f --- /dev/null +++ b/Help/command/variable_requires.rst @@ -0,0 +1,22 @@ +variable_requires +----------------- + +Disallowed. 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..a2df058 --- /dev/null +++ b/Help/command/variable_watch.rst @@ -0,0 +1,13 @@ +variable_watch +-------------- + +Watch the CMake variable for change. + +:: + + variable_watch(<variable name> [<command to execute>]) + +If the specified variable changes, the message will be printed about +the variable being changed. If the command is specified, the command +will be executed. The command will receive the following arguments: +COMMAND(<variable> <access> <value> <current list file> <stack>) diff --git a/Help/command/while.rst b/Help/command/while.rst new file mode 100644 index 0000000..7509da3 --- /dev/null +++ b/Help/command/while.rst @@ -0,0 +1,17 @@ +while +----- + +Evaluate a group of commands while a condition is true + +:: + + while(condition) + COMMAND1(ARGS ...) + COMMAND2(ARGS ...) + ... + endwhile(condition) + +All commands between while and the matching :command:`endwhile` are recorded +without being invoked. Once the :command:`endwhile` is evaluated, the +recorded list of commands is invoked as long as the condition is true. The +condition is evaluated using the same logic as the :command:`if` command. diff --git a/Help/command/write_file.rst b/Help/command/write_file.rst new file mode 100644 index 0000000..40e7557 --- /dev/null +++ b/Help/command/write_file.rst @@ -0,0 +1,20 @@ +write_file +---------- + +Deprecated. 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..b288aad --- /dev/null +++ b/Help/cpack_gen/archive.rst @@ -0,0 +1,35 @@ +CPack Archive Generator +----------------------- + +Archive CPack generator that supports packaging of sources and binaries in +different formats: + + - 7Z - 7zip - (.7z) + - TBZ2 (.tar.bz2) + - TGZ (.tar.gz) + - TXZ (.tar.xz) + - TZ (.tar.Z) + - ZIP (.zip) + +Variables specific to CPack Archive generator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. variable:: CPACK_ARCHIVE_FILE_NAME + CPACK_ARCHIVE_<component>_FILE_NAME + + Package file name without extension which is added automatically depending + on the archive format. + + * Mandatory : YES + * Default : ``<CPACK_PACKAGE_FILE_NAME>[-<component>].<extension>`` with + spaces replaced by '-' + +.. variable:: CPACK_ARCHIVE_COMPONENT_INSTALL + + Enable component packaging for CPackArchive + + * Mandatory : NO + * Default : OFF + + If enabled (ON) multiple packages are generated. By default a single package + containing files of all components is generated. diff --git a/Help/cpack_gen/bundle.rst b/Help/cpack_gen/bundle.rst new file mode 100644 index 0000000..29727e2 --- /dev/null +++ b/Help/cpack_gen/bundle.rst @@ -0,0 +1,64 @@ +CPack Bundle Generator +---------------------- + +CPack Bundle generator (macOS) specific options + +Variables specific to CPack Bundle generator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Installers built on macOS using the Bundle generator use the +aforementioned DragNDrop (``CPACK_DMG_xxx``) variables, plus the following +Bundle-specific parameters (``CPACK_BUNDLE_xxx``). + +.. variable:: CPACK_BUNDLE_NAME + + The name of the generated bundle. This appears in the OSX finder as the + bundle name. Required. + +.. variable:: CPACK_BUNDLE_PLIST + + Path to an OSX plist file that will be used for the generated bundle. This + assumes that the caller has generated or specified their own Info.plist + file. Required. + +.. variable:: CPACK_BUNDLE_ICON + + Path to an OSX icon file that will be used as the icon for the generated + bundle. This is the icon that appears in the OSX finder for the bundle, and + in the OSX dock when the bundle is opened. Required. + +.. variable:: CPACK_BUNDLE_STARTUP_COMMAND + + Path to a startup script. This is a path to an executable or script that + will be run whenever an end-user double-clicks the generated bundle in the + OSX Finder. Optional. + +.. variable:: CPACK_BUNDLE_APPLE_CERT_APP + + The name of your Apple supplied code signing certificate for the application. + The name usually takes the form ``Developer ID Application: [Name]`` or + ``3rd Party Mac Developer Application: [Name]``. If this variable is not set + the application will not be signed. + +.. variable:: CPACK_BUNDLE_APPLE_ENTITLEMENTS + + The name of the ``Plist`` file that contains your apple entitlements for sandboxing + your application. This file is required for submission to the Mac App Store. + +.. variable:: CPACK_BUNDLE_APPLE_CODESIGN_FILES + + A list of additional files that you wish to be signed. You do not need to + list the main application folder, or the main executable. You should + list any frameworks and plugins that are included in your app bundle. + +.. variable:: CPACK_BUNDLE_APPLE_CODESIGN_PARAMETER + + Additional parameter that will passed to ``codesign``. + Default value: ``--deep -f`` + +.. variable:: CPACK_COMMAND_CODESIGN + + Path to the ``codesign(1)`` command used to sign applications with an + Apple cert. This variable can be used to override the automatically + detected command (or specify its location if the auto-detection fails + to find it). diff --git a/Help/cpack_gen/cygwin.rst b/Help/cpack_gen/cygwin.rst new file mode 100644 index 0000000..1c5f7af --- /dev/null +++ b/Help/cpack_gen/cygwin.rst @@ -0,0 +1,23 @@ +CPack Cygwin Generator +---------------------- + +Cygwin CPack generator (Cygwin). + +Variables specific to CPack Cygwin generator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The +following variable is specific to installers build on and/or for +Cygwin: + +.. variable:: CPACK_CYGWIN_PATCH_NUMBER + + The Cygwin patch number. FIXME: This documentation is incomplete. + +.. variable:: CPACK_CYGWIN_PATCH_FILE + + The Cygwin patch file. FIXME: This documentation is incomplete. + +.. variable:: CPACK_CYGWIN_BUILD_SCRIPT + + The Cygwin build script. FIXME: This documentation is incomplete. diff --git a/Help/cpack_gen/deb.rst b/Help/cpack_gen/deb.rst new file mode 100644 index 0000000..26021cc --- /dev/null +++ b/Help/cpack_gen/deb.rst @@ -0,0 +1,557 @@ +CPack Deb Generator +------------------- + +The built in (binary) CPack Deb generator (Unix only) + +Variables specific to CPack Debian (DEB) generator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The CPack Deb generator may be used to create Deb package using :module:`CPack`. +The CPack Deb generator is a :module:`CPack` generator thus it uses the +``CPACK_XXX`` variables used by :module:`CPack`. + +The CPack Deb generator should work on any Linux host but it will produce +better deb package when Debian specific tools ``dpkg-xxx`` are usable on +the build system. + +The CPack Deb generator has specific features which are controlled by the +specifics :code:`CPACK_DEBIAN_XXX` variables. + +:code:`CPACK_DEBIAN_<COMPONENT>_XXXX` variables may be used in order to have +**component** specific values. Note however that ``<COMPONENT>`` refers to +the **grouping name** written in upper case. It may be either a component name +or a component GROUP name. + +Here are some CPack Deb generator wiki resources that are here for historic +reasons and are no longer maintained but may still prove useful: + + - https://gitlab.kitware.com/cmake/community/wikis/doc/cpack/Configuration + - https://gitlab.kitware.com/cmake/community/wikis/doc/cpack/PackageGenerators#deb-unix-only + +List of CPack Deb generator specific variables: + +.. variable:: CPACK_DEB_COMPONENT_INSTALL + + Enable component packaging for CPackDEB + + * Mandatory : NO + * Default : OFF + + If enabled (ON) multiple packages are generated. By default a single package + containing files of all components is generated. + +.. variable:: CPACK_DEBIAN_PACKAGE_NAME + CPACK_DEBIAN_<COMPONENT>_PACKAGE_NAME + + Set Package control field (variable is automatically transformed to lower + case). + + * Mandatory : YES + * Default : + + - :variable:`CPACK_PACKAGE_NAME` for non-component based + installations + - :variable:`CPACK_DEBIAN_PACKAGE_NAME` suffixed with -<COMPONENT> + for component-based installations. + + See https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Source + +.. variable:: CPACK_DEBIAN_FILE_NAME + CPACK_DEBIAN_<COMPONENT>_FILE_NAME + + Package file name. + + * Mandatory : YES + * Default : ``<CPACK_PACKAGE_FILE_NAME>[-<component>].deb`` + + This may be set to ``DEB-DEFAULT`` to allow the CPack Deb generator to generate + package file name by itself in deb format:: + + <PackageName>_<VersionNumber>-<DebianRevisionNumber>_<DebianArchitecture>.deb + + Alternatively provided package file name must end + with either ``.deb`` or ``.ipk`` suffix. + + .. note:: + + Preferred setting of this variable is ``DEB-DEFAULT`` but for backward + compatibility with the CPack Deb generator in CMake prior to version 3.6 this + feature is disabled by default. + + .. note:: + + By using non default filenames duplicate names may occur. Duplicate files + get overwritten and it is up to the packager to set the variables in a + manner that will prevent such errors. + +.. variable:: CPACK_DEBIAN_PACKAGE_EPOCH + + The Debian package epoch + + * Mandatory : No + * Default : - + + Optional number that should be incremented when changing versioning schemas + or fixing mistakes in the version numbers of older packages. + +.. variable:: CPACK_DEBIAN_PACKAGE_VERSION + + The Debian package version + + * Mandatory : YES + * Default : :variable:`CPACK_PACKAGE_VERSION` + + This variable may contain only alphanumerics (A-Za-z0-9) and the characters + . + - ~ (full stop, plus, hyphen, tilde) and should start with a digit. If + :variable:`CPACK_DEBIAN_PACKAGE_RELEASE` is not set then hyphens are not + allowed. + + .. note:: + + For backward compatibility with CMake 3.9 and lower a failed test of this + variable's content is not a hard error when both + :variable:`CPACK_DEBIAN_PACKAGE_RELEASE` and + :variable:`CPACK_DEBIAN_PACKAGE_EPOCH` variables are not set. An author + warning is reported instead. + +.. variable:: CPACK_DEBIAN_PACKAGE_RELEASE + + The Debian package release - Debian revision number. + + * Mandatory : No + * Default : - + + This is the numbering of the DEB package itself, i.e. the version of the + packaging and not the version of the content (see + :variable:`CPACK_DEBIAN_PACKAGE_VERSION`). One may change the default value + if the previous packaging was buggy and/or you want to put here a fancy Linux + distro specific numbering. + +.. variable:: CPACK_DEBIAN_PACKAGE_ARCHITECTURE + CPACK_DEBIAN_<COMPONENT>_PACKAGE_ARCHITECTURE + + The Debian package architecture + + * Mandatory : YES + * Default : Output of :code:`dpkg --print-architecture` (or :code:`i386` + if :code:`dpkg` is not found) + +.. variable:: CPACK_DEBIAN_PACKAGE_DEPENDS + CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS + + Sets the Debian dependencies of this package. + + * Mandatory : NO + * Default : + + - An empty string for non-component based installations + - :variable:`CPACK_DEBIAN_PACKAGE_DEPENDS` for component-based + installations. + + .. note:: + + If :variable:`CPACK_DEBIAN_PACKAGE_SHLIBDEPS` or + more specifically :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS` + is set for this component, the discovered dependencies will be appended + to :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS` instead of + :variable:`CPACK_DEBIAN_PACKAGE_DEPENDS`. If + :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS` is an empty string, + only the automatically discovered dependencies will be set for this + component. + + Example:: + + set(CPACK_DEBIAN_PACKAGE_DEPENDS "libc6 (>= 2.3.1-6), libc6 (< 2.4)") + +.. variable:: CPACK_DEBIAN_ENABLE_COMPONENT_DEPENDS + + Sets inter component dependencies if listed with + :variable:`CPACK_COMPONENT_<compName>_DEPENDS` variables. + + * Mandatory : NO + * Default : - + +.. variable:: CPACK_DEBIAN_PACKAGE_MAINTAINER + + The Debian package maintainer + + * Mandatory : YES + * Default : :code:`CPACK_PACKAGE_CONTACT` + +.. variable:: CPACK_DEBIAN_PACKAGE_DESCRIPTION + CPACK_COMPONENT_<COMPONENT>_DESCRIPTION + + The Debian package description + + * Mandatory : YES + * Default : + + - :variable:`CPACK_DEBIAN_PACKAGE_DESCRIPTION` if set or + - :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY` + + +.. variable:: CPACK_DEBIAN_PACKAGE_SECTION + CPACK_DEBIAN_<COMPONENT>_PACKAGE_SECTION + + Set Section control field e.g. admin, devel, doc, ... + + * Mandatory : YES + * Default : "devel" + + See https://www.debian.org/doc/debian-policy/ch-archive.html#s-subsections + +.. variable:: CPACK_DEBIAN_ARCHIVE_TYPE + + The archive format used for creating the Debian package. + + * Mandatory : YES + * Default : "paxr" + + Possible values are: + + - paxr + - gnutar + + .. note:: + + Default pax archive format is the most portable format and generates + packages that do not treat sparse files specially. + GNU tar format on the other hand supports longer filenames. + +.. variable:: CPACK_DEBIAN_COMPRESSION_TYPE + + The compression used for creating the Debian package. + + * Mandatory : YES + * Default : "gzip" + + Possible values are: + + - lzma + - xz + - bzip2 + - gzip + +.. variable:: CPACK_DEBIAN_PACKAGE_PRIORITY + CPACK_DEBIAN_<COMPONENT>_PACKAGE_PRIORITY + + Set Priority control field e.g. required, important, standard, optional, + extra + + * Mandatory : YES + * Default : "optional" + + See https://www.debian.org/doc/debian-policy/ch-archive.html#s-priorities + +.. variable:: CPACK_DEBIAN_PACKAGE_HOMEPAGE + + The URL of the web site for this package, preferably (when applicable) the + site from which the original source can be obtained and any additional + upstream documentation or information may be found. + + * Mandatory : NO + * Default : :variable:`CMAKE_PROJECT_HOMEPAGE_URL` + + .. note:: + + The content of this field is a simple URL without any surrounding + characters such as <>. + +.. variable:: CPACK_DEBIAN_PACKAGE_SHLIBDEPS + CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS + + May be set to ON in order to use :code:`dpkg-shlibdeps` to generate + better package dependency list. + + * Mandatory : NO + * Default : + + - :variable:`CPACK_DEBIAN_PACKAGE_SHLIBDEPS` if set or + - OFF + + .. note:: + + You may need set :variable:`CMAKE_INSTALL_RPATH` to an appropriate value + if you use this feature, because if you don't :code:`dpkg-shlibdeps` + may fail to find your own shared libs. + See https://gitlab.kitware.com/cmake/community/wikis/doc/cmake/RPATH-handling + +.. variable:: CPACK_DEBIAN_PACKAGE_DEBUG + + May be set when invoking cpack in order to trace debug information + during the CPack Deb generator run. + + * Mandatory : NO + * Default : - + +.. variable:: CPACK_DEBIAN_PACKAGE_PREDEPENDS + CPACK_DEBIAN_<COMPONENT>_PACKAGE_PREDEPENDS + + Sets the `Pre-Depends` field of the Debian package. + Like :variable:`Depends <CPACK_DEBIAN_PACKAGE_DEPENDS>`, except that it + also forces :code:`dpkg` to complete installation of the packages named + before even starting the installation of the package which declares the + pre-dependency. + + * Mandatory : NO + * Default : + + - An empty string for non-component based installations + - :variable:`CPACK_DEBIAN_PACKAGE_PREDEPENDS` for component-based + installations. + + See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps + +.. variable:: CPACK_DEBIAN_PACKAGE_ENHANCES + CPACK_DEBIAN_<COMPONENT>_PACKAGE_ENHANCES + + Sets the `Enhances` field of the Debian package. + Similar to :variable:`Suggests <CPACK_DEBIAN_PACKAGE_SUGGESTS>` but works + in the opposite direction: declares that a package can enhance the + functionality of another package. + + * Mandatory : NO + * Default : + + - An empty string for non-component based installations + - :variable:`CPACK_DEBIAN_PACKAGE_ENHANCES` for component-based + installations. + + See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps + +.. variable:: CPACK_DEBIAN_PACKAGE_BREAKS + CPACK_DEBIAN_<COMPONENT>_PACKAGE_BREAKS + + Sets the `Breaks` field of the Debian package. + When a binary package (P) declares that it breaks other packages (B), + :code:`dpkg` will not allow the package (P) which declares `Breaks` be + **unpacked** unless the packages that will be broken (B) are deconfigured + first. + As long as the package (P) is configured, the previously deconfigured + packages (B) cannot be reconfigured again. + + * Mandatory : NO + * Default : + + - An empty string for non-component based installations + - :variable:`CPACK_DEBIAN_PACKAGE_BREAKS` for component-based + installations. + + See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-breaks + +.. variable:: CPACK_DEBIAN_PACKAGE_CONFLICTS + CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONFLICTS + + Sets the `Conflicts` field of the Debian package. + When one binary package declares a conflict with another using a `Conflicts` + field, :code:`dpkg` will not allow them to be unpacked on the system at + the same time. + + * Mandatory : NO + * Default : + + - An empty string for non-component based installations + - :variable:`CPACK_DEBIAN_PACKAGE_CONFLICTS` for component-based + installations. + + See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-conflicts + + .. note:: + + This is a stronger restriction than + :variable:`Breaks <CPACK_DEBIAN_PACKAGE_BREAKS>`, which prevents the + broken package from being configured while the breaking package is in + the "Unpacked" state but allows both packages to be unpacked at the same + time. + +.. variable:: CPACK_DEBIAN_PACKAGE_PROVIDES + CPACK_DEBIAN_<COMPONENT>_PACKAGE_PROVIDES + + Sets the `Provides` field of the Debian package. + A virtual package is one which appears in the `Provides` control field of + another package. + + * Mandatory : NO + * Default : + + - An empty string for non-component based installations + - :variable:`CPACK_DEBIAN_PACKAGE_PROVIDES` for component-based + installations. + + See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-virtual + +.. variable:: CPACK_DEBIAN_PACKAGE_REPLACES + CPACK_DEBIAN_<COMPONENT>_PACKAGE_REPLACES + + Sets the `Replaces` field of the Debian package. + Packages can declare in their control file that they should overwrite + files in certain other packages, or completely replace other packages. + + * Mandatory : NO + * Default : + + - An empty string for non-component based installations + - :variable:`CPACK_DEBIAN_PACKAGE_REPLACES` for component-based + installations. + + See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps + +.. variable:: CPACK_DEBIAN_PACKAGE_RECOMMENDS + CPACK_DEBIAN_<COMPONENT>_PACKAGE_RECOMMENDS + + Sets the `Recommends` field of the Debian package. + Allows packages to declare a strong, but not absolute, dependency on other + packages. + + * Mandatory : NO + * Default : + + - An empty string for non-component based installations + - :variable:`CPACK_DEBIAN_PACKAGE_RECOMMENDS` for component-based + installations. + + See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps + +.. variable:: CPACK_DEBIAN_PACKAGE_SUGGESTS + CPACK_DEBIAN_<COMPONENT>_PACKAGE_SUGGESTS + + Sets the `Suggests` field of the Debian package. + Allows packages to declare a suggested package install grouping. + + * Mandatory : NO + * Default : + + - An empty string for non-component based installations + - :variable:`CPACK_DEBIAN_PACKAGE_SUGGESTS` for component-based + installations. + + See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps + +.. variable:: CPACK_DEBIAN_PACKAGE_GENERATE_SHLIBS + + * Mandatory : NO + * Default : OFF + + Allows to generate shlibs control file automatically. Compatibility is defined by + :variable:`CPACK_DEBIAN_PACKAGE_GENERATE_SHLIBS_POLICY` variable value. + + .. note:: + + Libraries are only considered if they have both library name and version + set. This can be done by setting SOVERSION property with + :command:`set_target_properties` command. + +.. variable:: CPACK_DEBIAN_PACKAGE_GENERATE_SHLIBS_POLICY + + Compatibility policy for auto-generated shlibs control file. + + * Mandatory : NO + * Default : "=" + + Defines compatibility policy for auto-generated shlibs control file. + Possible values: "=", ">=" + + See https://www.debian.org/doc/debian-policy/ch-sharedlibs.html#s-sharedlibs-shlibdeps + +.. variable:: CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA + CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONTROL_EXTRA + + This variable allow advanced user to add custom script to the + control.tar.gz. + Typical usage is for conffiles, postinst, postrm, prerm. + + * Mandatory : NO + * Default : - + + Usage:: + + set(CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA + "${CMAKE_CURRENT_SOURCE_DIR}/prerm;${CMAKE_CURRENT_SOURCE_DIR}/postrm") + + .. note:: + + The original permissions of the files will be used in the final + package unless the variable + :variable:`CPACK_DEBIAN_PACKAGE_CONTROL_STRICT_PERMISSION` is set. + In particular, the scripts should have the proper executable + flag prior to the generation of the package. + +.. variable:: CPACK_DEBIAN_PACKAGE_CONTROL_STRICT_PERMISSION + CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONTROL_STRICT_PERMISSION + + This variable indicates if the Debian policy on control files should be + strictly followed. + + * Mandatory : NO + * Default : FALSE + + Usage:: + + set(CPACK_DEBIAN_PACKAGE_CONTROL_STRICT_PERMISSION TRUE) + + .. note:: + + This overrides the permissions on the original files, following the rules + set by Debian policy + https://www.debian.org/doc/debian-policy/ch-files.html#s-permissions-owners + +.. variable:: CPACK_DEBIAN_PACKAGE_SOURCE + CPACK_DEBIAN_<COMPONENT>_PACKAGE_SOURCE + + Sets the ``Source`` field of the binary Debian package. + When the binary package name is not the same as the source package name + (in particular when several components/binaries are generated from one + source) the source from which the binary has been generated should be + indicated with the field ``Source``. + + * Mandatory : NO + * Default : + + - An empty string for non-component based installations + - :variable:`CPACK_DEBIAN_PACKAGE_SOURCE` for component-based + installations. + + See https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Source + + .. note:: + + This value is not interpreted. It is possible to pass an optional + revision number of the referenced source package as well. + +Packaging of debug information +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Dbgsym packages contain debug symbols for debugging packaged binaries. + +Dbgsym packaging has its own set of variables: + +.. variable:: CPACK_DEBIAN_DEBUGINFO_PACKAGE + CPACK_DEBIAN_<component>_DEBUGINFO_PACKAGE + + Enable generation of dbgsym .ddeb package(s). + + * Mandatory : NO + * Default : OFF + +.. note:: + + Binaries must contain debug symbols before packaging so use either ``Debug`` + or ``RelWithDebInfo`` for :variable:`CMAKE_BUILD_TYPE` variable value. + +Building Debian packages on Windows +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To communicate UNIX file permissions from the install stage +to the CPack DEB generator the "cmake_mode_t" NTFS +alternate data stream (ADT) is used. + +When a filesystem without ADT support is used only owner read/write +permissions can be preserved. + +Reproducible packages +^^^^^^^^^^^^^^^^^^^^^ + +The environment variable ``SOURCE_DATE_EPOCH`` may be set to a UNIX +timestamp, defined as the number of seconds, excluding leap seconds, +since 01 Jan 1970 00:00:00 UTC. If set, the CPack Deb generator will +use its value for timestamps in the package. diff --git a/Help/cpack_gen/dmg.rst b/Help/cpack_gen/dmg.rst new file mode 100644 index 0000000..b7b3a0a --- /dev/null +++ b/Help/cpack_gen/dmg.rst @@ -0,0 +1,101 @@ +CPack DMG Generator +------------------- + +DragNDrop CPack generator (macOS). + +Variables specific to CPack DragNDrop generator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following variables are specific to the DragNDrop installers built +on macOS: + +.. variable:: CPACK_DMG_VOLUME_NAME + + The volume name of the generated disk image. Defaults to + CPACK_PACKAGE_FILE_NAME. + +.. variable:: CPACK_DMG_FORMAT + + The disk image format. Common values are ``UDRO`` (UDIF read-only), ``UDZO`` (UDIF + zlib-compressed) or ``UDBZ`` (UDIF bzip2-compressed). Refer to ``hdiutil(1)`` for + more information on other available formats. Defaults to ``UDZO``. + +.. variable:: CPACK_DMG_DS_STORE + + Path to a custom ``.DS_Store`` file. This ``.DS_Store`` file can be used to + specify the Finder window position/geometry and layout (such as hidden + toolbars, placement of the icons etc.). This file has to be generated by + the Finder (either manually or through AppleScript) using a normal folder + from which the ``.DS_Store`` file can then be extracted. + +.. variable:: CPACK_DMG_DS_STORE_SETUP_SCRIPT + + Path to a custom AppleScript file. This AppleScript is used to generate + a ``.DS_Store`` file which specifies the Finder window position/geometry and + layout (such as hidden toolbars, placement of the icons etc.). + By specifying a custom AppleScript there is no need to use + ``CPACK_DMG_DS_STORE``, as the ``.DS_Store`` that is generated by the AppleScript + will be packaged. + +.. variable:: CPACK_DMG_BACKGROUND_IMAGE + + Path to an image file to be used as the background. This file will be + copied to ``.background``/``background.<ext>``, where ``<ext>`` is the original image file + extension. The background image is installed into the image before + ``CPACK_DMG_DS_STORE_SETUP_SCRIPT`` is executed or ``CPACK_DMG_DS_STORE`` is + installed. By default no background image is set. + +.. variable:: CPACK_DMG_DISABLE_APPLICATIONS_SYMLINK + + Default behaviour is to include a symlink to ``/Applications`` in the DMG. + Set this option to ``ON`` to avoid adding the symlink. + +.. variable:: CPACK_DMG_SLA_DIR + + Directory where license and menu files for different languages are stored. + Setting this causes CPack to look for a ``<language>.menu.txt`` and + ``<language>.license.txt`` file for every language defined in + ``CPACK_DMG_SLA_LANGUAGES``. If both this variable and + ``CPACK_RESOURCE_FILE_LICENSE`` are set, CPack will only look for the menu + files and use the same license file for all languages. + +.. variable:: CPACK_DMG_SLA_LANGUAGES + + Languages for which a license agreement is provided when mounting the + generated DMG. A menu file consists of 9 lines of text. The first line is + is the name of the language itself, uppercase, in English (e.g. German). + The other lines are translations of the following strings: + + - Agree + - Disagree + - Print + - Save... + - You agree to the terms of the License Agreement when you click the + "Agree" button. + - Software License Agreement + - This text cannot be saved. The disk may be full or locked, or the file + may be locked. + - Unable to print. Make sure you have selected a printer. + + For every language in this list, CPack will try to find files + ``<language>.menu.txt`` and ``<language>.license.txt`` in the directory + specified by the :variable:`CPACK_DMG_SLA_DIR` variable. + +.. variable:: CPACK_COMMAND_HDIUTIL + + Path to the ``hdiutil(1)`` command used to operate on disk image files on + macOS. This variable can be used to override the automatically detected + command (or specify its location if the auto-detection fails to find it). + +.. variable:: CPACK_COMMAND_SETFILE + + Path to the ``SetFile(1)`` command used to set extended attributes on files and + directories on macOS. This variable can be used to override the + automatically detected command (or specify its location if the + auto-detection fails to find it). + +.. variable:: CPACK_COMMAND_REZ + + Path to the ``Rez(1)`` command used to compile resources on macOS. This + variable can be used to override the automatically detected command (or + specify its location if the auto-detection fails to find it). diff --git a/Help/cpack_gen/external.rst b/Help/cpack_gen/external.rst new file mode 100644 index 0000000..f98e1c9 --- /dev/null +++ b/Help/cpack_gen/external.rst @@ -0,0 +1,283 @@ +CPack External Generator +------------------------ + +CPack provides many generators to create packages for a variety of platforms +and packaging systems. The intention is for CMake/CPack to be a complete +end-to-end solution for building and packaging a software project. However, it +may not always be possible to use CPack for the entire packaging process, due +to either technical limitations or policies that require the use of certain +tools. For this reason, CPack provides the "External" generator, which allows +external packaging software to take advantage of some of the functionality +provided by CPack, such as component installation and the dependency graph. + +Integration with External Packaging Tools +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The CPack External generator generates a .json file containing the +CPack internal metadata, which gives external software information +on how to package the software. External packaging software may itself +invoke CPack, consume the generated metadata, +install and package files as required. + +Alternatively CPack can invoke an external packaging software +through an optional custom CMake script in +:variable:`CPACK_EXT_PACKAGE_SCRIPT` instead. + +Staging of installation files may also optionally be +taken care of by the generator when enabled through the +:variable:`CPACK_EXT_ENABLE_STAGING` variable. + +JSON Format +^^^^^^^^^^^ + +The JSON metadata file contains a list of CPack components and component groups, +the various options passed to :command:`cpack_add_component` and +:command:`cpack_add_component_group`, the dependencies between the components +and component groups, and various other options passed to CPack. + +The JSON's root object will always provide two fields: +``formatVersionMajor`` and ``formatVersionMinor``, which are always integers +that describe the output format of the generator. Backwards-compatible changes +to the output format (for example, adding a new field that didn't exist before) +cause the minor version to be incremented, and backwards-incompatible changes +(for example, deleting a field or changing its meaning) cause the major version +to be incremented and the minor version reset to 0. The format version is +always of the format ``major.minor``. In other words, it always has exactly two +parts, separated by a period. + +You can request one or more specific versions of the output format as described +below with :variable:`CPACK_EXT_REQUESTED_VERSIONS`. The output format will +have a major version that exactly matches the requested major version, and a +minor version that is greater than or equal to the requested minor version. If +no version is requested with :variable:`CPACK_EXT_REQUESTED_VERSIONS`, the +latest known major version is used by default. Currently, the only supported +format is 1.0, which is described below. + +Version 1.0 +*********** + +In addition to the standard format fields, format version 1.0 provides the +following fields in the root: + +``components`` + The ``components`` field is an object with component names as the keys and + objects describing the components as the values. The component objects have + the following fields: + + ``name`` + The name of the component. This is always the same as the key in the + ``components`` object. + + ``displayName`` + The value of the ``DISPLAY_NAME`` field passed to + :command:`cpack_add_component`. + + ``description`` + The value of the ``DESCRIPTION`` field passed to + :command:`cpack_add_component`. + + ``isHidden`` + True if ``HIDDEN`` was passed to :command:`cpack_add_component`, false if + it was not. + + ``isRequired`` + True if ``REQUIRED`` was passed to :command:`cpack_add_component`, false if + it was not. + + ``isDisabledByDefault`` + True if ``DISABLED`` was passed to :command:`cpack_add_component`, false if + it was not. + + ``group`` + Only present if ``GROUP`` was passed to :command:`cpack_add_component`. If + so, this field is a string value containing the component's group. + + ``dependencies`` + An array of components the component depends on. This contains the values + in the ``DEPENDS`` argument passed to :command:`cpack_add_component`. If no + ``DEPENDS`` argument was passed, this is an empty list. + + ``installationTypes`` + An array of installation types the component is part of. This contains the + values in the ``INSTALL_TYPES`` argument passed to + :command:`cpack_add_component`. If no ``INSTALL_TYPES`` argument was + passed, this is an empty list. + + ``isDownloaded`` + True if ``DOWNLOADED`` was passed to :command:`cpack_add_component`, false + if it was not. + + ``archiveFile`` + The name of the archive file passed with the ``ARCHIVE_FILE`` argument to + :command:`cpack_add_component`. If no ``ARCHIVE_FILE`` argument was passed, + this is an empty string. + +``componentGroups`` + The ``componentGroups`` field is an object with component group names as the + keys and objects describing the component groups as the values. The component + group objects have the following fields: + + ``name`` + The name of the component group. This is always the same as the key in the + ``componentGroups`` object. + + ``displayName`` + The value of the ``DISPLAY_NAME`` field passed to + :command:`cpack_add_component_group`. + + ``description`` + The value of the ``DESCRIPTION`` field passed to + :command:`cpack_add_component_group`. + + ``parentGroup`` + Only present if ``PARENT_GROUP`` was passed to + :command:`cpack_add_component_group`. If so, this field is a string value + containing the component group's parent group. + + ``isExpandedByDefault`` + True if ``EXPANDED`` was passed to :command:`cpack_add_component_group`, + false if it was not. + + ``isBold`` + True if ``BOLD_TITLE`` was passed to :command:`cpack_add_component_group`, + false if it was not. + + ``components`` + An array of names of components that are direct members of the group + (components that have this group as their ``GROUP``). Components of + subgroups are not included. + + ``subgroups`` + An array of names of component groups that are subgroups of the group + (groups that have this group as their ``PARENT_GROUP``). + +``installationTypes`` + The ``installationTypes`` field is an object with installation type names as + the keys and objects describing the installation types as the values. The + installation type objects have the following fields: + + ``name`` + The name of the installation type. This is always the same as the key in + the ``installationTypes`` object. + + ``displayName`` + The value of the ``DISPLAY_NAME`` field passed to + :command:`cpack_add_install_type`. + + ``index`` + The integer index of the installation type in the list. + +``projects`` + The ``projects`` field is an array of objects describing CMake projects which + comprise the CPack project. The values in this field are derived from + :variable:`CPACK_INSTALL_CMAKE_PROJECTS`. In most cases, this will be only a + single project. The project objects have the following fields: + + ``projectName`` + The project name passed to :variable:`CPACK_INSTALL_CMAKE_PROJECTS`. + + ``component`` + The name of the component or component set which comprises the project. + + ``directory`` + The build directory of the CMake project. This is the directory which + contains the ``cmake_install.cmake`` script. + + ``subDirectory`` + The subdirectory to install the project into inside the CPack package. + +``packageName`` + The package name given in :variable:`CPACK_PACKAGE_NAME`. Only present if + this option is set. + +``packageVersion`` + The package version given in :variable:`CPACK_PACKAGE_VERSION`. Only present + if this option is set. + +``packageDescriptionFile`` + The package description file given in + :variable:`CPACK_PACKAGE_DESCRIPTION_FILE`. Only present if this option is + set. + +``packageDescriptionSummary`` + The package description summary given in + :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY`. Only present if this option is + set. + +``buildConfig`` + The build configuration given to CPack with the ``-C`` option. Only present + if this option is set. + +``defaultDirectoryPermissions`` + The default directory permissions given in + :variable:`CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS`. Only present if this + option is set. + +``setDestdir`` + True if :variable:`CPACK_SET_DESTDIR` is true, false if it is not. + +``packagingInstallPrefix`` + The install prefix given in :variable:`CPACK_PACKAGING_INSTALL_PREFIX`. Only + present if :variable:`CPACK_SET_DESTDIR` is true. + +``stripFiles`` + True if :variable:`CPACK_STRIP_FILES` is true, false if it is not. + +``warnOnAbsoluteInstallDestination`` + True if :variable:`CPACK_WARN_ON_ABSOLUTE_INSTALL_DESTINATION` is true, false + if it is not. + +``errorOnAbsoluteInstallDestination`` + True if :variable:`CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION` is true, + false if it is not. + +Variables specific to CPack External generator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. variable:: CPACK_EXT_REQUESTED_VERSIONS + + This variable is used to request a specific version of the CPack External + generator. It is a list of ``major.minor`` values, separated by semicolons. + + If this variable is set to a non-empty value, the CPack External generator + will iterate through each item in the list to search for a version that it + knows how to generate. Requested versions should be listed in order of + descending preference by the client software, as the first matching version + in the list will be generated. + + The generator knows how to generate the version if it has a versioned + generator whose major version exactly matches the requested major version, + and whose minor version is greater than or equal to the requested minor + version. For example, if ``CPACK_EXT_REQUESTED_VERSIONS`` contains 1.0, and + the CPack External generator knows how to generate 1.1, it will generate 1.1. + If the generator doesn't know how to generate a version in the list, it skips + the version and looks at the next one. If it doesn't know how to generate any + of the requested versions, an error is thrown. + + If this variable is not set, or is empty, the CPack External generator will + generate the highest major and minor version that it knows how to generate. + + If an invalid version is encountered in ``CPACK_EXT_REQUESTED_VERSIONS`` (one + that doesn't match ``major.minor``, where ``major`` and ``minor`` are + integers), it is ignored. + +.. variable:: CPACK_EXT_ENABLE_STAGING + + This variable can be set to true to enable optional installation + into a temporary staging area which can then be picked up + and packaged by an external packaging tool. + The top level directory used by CPack for the current packaging + task is contained in ``CPACK_TOPLEVEL_DIRECTORY``. + It is automatically cleaned up on each run before packaging is initiated + and can be used for custom temporary files required by + the external packaging tool. + It also contains the staging area ``CPACK_TEMPORARY_DIRECTORY`` + into which CPack performs the installation when staging is enabled. + +.. variable:: CPACK_EXT_PACKAGE_SCRIPT + + This variable can optionally specify the full path to + a CMake script file to be run as part of the CPack invocation. + It is invoked after (optional) staging took place and may + run an external packaging tool. The script has access to + the variables defined by the CPack config file. diff --git a/Help/cpack_gen/freebsd.rst b/Help/cpack_gen/freebsd.rst new file mode 100644 index 0000000..2419057 --- /dev/null +++ b/Help/cpack_gen/freebsd.rst @@ -0,0 +1,138 @@ +CPack FreeBSD Generator +----------------------- + +The built in (binary) CPack FreeBSD (pkg) generator (Unix only) + +Variables specific to CPack FreeBSD (pkg) generator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The CPack FreeBSD generator may be used to create pkg(8) packages -- these may +be used on FreeBSD, DragonflyBSD, NetBSD, OpenBSD, but also on Linux or OSX, +depending on the installed package-management tools -- using :module:`CPack`. + +The CPack FreeBSD generator is a :module:`CPack` generator and uses the +``CPACK_XXX`` variables used by :module:`CPack`. It tries to re-use packaging +information that may already be specified for Debian packages for the +:cpack_gen:`CPack Deb Generator`. It also tries to re-use RPM packaging +information when Debian does not specify. + +The CPack FreeBSD generator should work on any host with libpkg installed. The +packages it produces are specific to the host architecture and ABI. + +The CPack FreeBSD generator sets package-metadata through +:code:`CPACK_FREEBSD_XXX` variables. The CPack FreeBSD generator, unlike the +CPack Deb generator, does not specially support componentized packages; a +single package is created from all the software artifacts created through +CMake. + +All of the variables can be set specifically for FreeBSD packaging in +the CPackConfig file or in CMakeLists.txt, but most of them have defaults +that use general settings (e.g. CMAKE_PROJECT_NAME) or Debian-specific +variables when those make sense (e.g. the homepage of an upstream project +is usually unchanged by the flavor of packaging). When there is no Debian +information to fall back on, but the RPM packaging has it, fall back to +the RPM information (e.g. package license). + +.. variable:: CPACK_FREEBSD_PACKAGE_NAME + + Sets the package name (in the package manifest, but also affects the + output filename). + + * Mandatory: YES + * Default: + + - :variable:`CPACK_PACKAGE_NAME` (this is always set by CPack itself, + based on CMAKE_PROJECT_NAME). + +.. variable:: CPACK_FREEBSD_PACKAGE_COMMENT + + Sets the package comment. This is the short description displayed by + pkg(8) in standard "pkg info" output. + + * Mandatory: YES + * Default: + + - :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY` (this is always set + by CPack itself, if nothing else sets it explicitly). + - :variable:`PROJECT_DESCRIPTION` (this can be set with the DESCRIPTION + parameter for :command:`project`). + +.. variable:: CPACK_FREEBSD_PACKAGE_DESCRIPTION + + Sets the package description. This is the long description of the package, + given by "pkg info" with a specific package as argument. + + * Mandatory: YES + * Default: + + - :variable:`CPACK_DEBIAN_PACKAGE_DESCRIPTION` (this may be set already + for Debian packaging, so we may as well re-use it). + +.. variable:: CPACK_FREEBSD_PACKAGE_WWW + + The URL of the web site for this package, preferably (when applicable) the + site from which the original source can be obtained and any additional + upstream documentation or information may be found. + + * Mandatory: YES + * Default: + + - :variable:`CMAKE_PROJECT_HOMEPAGE_URL`, or if that is not set, + :variable:`CPACK_DEBIAN_PACKAGE_HOMEPAGE` (this may be set already + for Debian packaging, so we may as well re-use it). + +.. variable:: CPACK_FREEBSD_PACKAGE_LICENSE + + The license, or licenses, which apply to this software package. This must + be one or more license-identifiers that pkg recognizes as acceptable license + identifiers (e.g. "GPLv2"). + + * Mandatory: YES + * Default: + + - :variable:`CPACK_RPM_PACKAGE_LICENSE` + +.. variable:: CPACK_FREEBSD_PACKAGE_LICENSE_LOGIC + + This variable is only of importance if there is more than one license. + The default is "single", which is only applicable to a single license. + Other acceptable values are determined by pkg -- those are "dual" or "multi" -- + meaning choice (OR) or simultaneous (AND) application of the licenses. + + * Mandatory: NO + * Default: single + +.. variable:: CPACK_FREEBSD_PACKAGE_MAINTAINER + + The FreeBSD maintainer (e.g. kde@freebsd.org) of this package. + + * Mandatory: YES + * Default: none + +.. variable:: CPACK_FREEBSD_PACKAGE_ORIGIN + + The origin (ports label) of this package; for packages built by CPack + outside of the ports system this is of less importance. The default + puts the package somewhere under misc/, as a stopgap. + + * Mandatory: YES + * Default: misc/<package name> + +.. variable:: CPACK_FREEBSD_PACKAGE_CATEGORIES + + The ports categories where this package lives (if it were to be built + from ports). If none is set a single category is determined based on + the package origin. + + * Mandatory: YES + * Default: derived from ORIGIN + +.. variable:: CPACK_FREEBSD_PACKAGE_DEPS + + A list of package origins that should be added as package dependencies. + These are in the form <category>/<packagename>, e.g. x11/libkonq. + No version information needs to be provided (this is not included + in the manifest). + + * Mandatory: NO + * Default: empty diff --git a/Help/cpack_gen/ifw.rst b/Help/cpack_gen/ifw.rst new file mode 100644 index 0000000..e43b1d6 --- /dev/null +++ b/Help/cpack_gen/ifw.rst @@ -0,0 +1,335 @@ +CPack IFW Generator +------------------- + +See :module:`CPackIFW` for details on the CPackIFW module. + +.. _QtIFW: http://doc.qt.io/qtinstallerframework/index.html + + +Overview +^^^^^^^^ + +CPack ``IFW`` generator helps you to create online and offline +binary cross-platform installers with a graphical user interface. + +CPack IFW generator prepares project installation and generates configuration +and meta information for QtIFW_ tools. + +The QtIFW_ provides a set of tools and utilities to create +installers for the supported desktop Qt platforms: Linux, Microsoft Windows, +and macOS. + +You should also install QtIFW_ to use CPack ``IFW`` generator. + +Hints +^^^^^ + +Generally, the CPack ``IFW`` generator automatically finds QtIFW_ tools, +but if you don't use a default path for installation of the QtIFW_ tools, +the path may be specified in either a CMake or an environment variable: + +.. variable:: CPACK_IFW_ROOT + + An CMake variable which specifies the location of the QtIFW_ tool suite. + + The variable will be cached in the ``CPackConfig.cmake`` file and used at + CPack runtime. + +.. variable:: QTIFWDIR + + An environment variable which specifies the location of the QtIFW_ tool + suite. + +.. note:: + The specified path should not contain "bin" at the end + (for example: "D:\\DevTools\\QtIFW2.0.5"). + +The :variable:`CPACK_IFW_ROOT` variable has a higher priority and overrides +the value of the :variable:`QTIFWDIR` variable. + +Internationalization +^^^^^^^^^^^^^^^^^^^^ + +Some variables and command arguments support internationalization via +CMake script. This is an optional feature. + +Installers created by QtIFW_ tools have built-in support for +internationalization and many phrases are localized to many languages, +but this does not apply to the description of the your components and groups +that will be distributed. + +Localization of the description of your components and groups is useful for +users of your installers. + +A localized variable or argument can contain a single default value, and a +set of pairs the name of the locale and the localized value. + +For example: + +.. code-block:: cmake + + set(LOCALIZABLE_VARIABLE "Default value" + en "English value" + en_US "American value" + en_GB "Great Britain value" + ) + +Variables +^^^^^^^^^ + +You can use the following variables to change behavior of CPack ``IFW`` +generator. + +Debug +""""" + +.. variable:: CPACK_IFW_VERBOSE + + Set to ``ON`` to enable addition debug output. + By default is ``OFF``. + +Package +""""""" + +.. variable:: CPACK_IFW_PACKAGE_TITLE + + Name of the installer as displayed on the title bar. + By default used :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY`. + +.. variable:: CPACK_IFW_PACKAGE_PUBLISHER + + Publisher of the software (as shown in the Windows Control Panel). + By default used :variable:`CPACK_PACKAGE_VENDOR`. + +.. variable:: CPACK_IFW_PRODUCT_URL + + URL to a page that contains product information on your web site. + +.. variable:: CPACK_IFW_PACKAGE_ICON + + Filename for a custom installer icon. The actual file is '.icns' (macOS), + '.ico' (Windows). No functionality on Unix. + +.. variable:: CPACK_IFW_PACKAGE_WINDOW_ICON + + Filename for a custom window icon in PNG format for the Installer + application. + +.. variable:: CPACK_IFW_PACKAGE_LOGO + + Filename for a logo is used as QWizard::LogoPixmap. + +.. variable:: CPACK_IFW_PACKAGE_WATERMARK + + Filename for a watermark is used as QWizard::WatermarkPixmap. + +.. variable:: CPACK_IFW_PACKAGE_BANNER + + Filename for a banner is used as QWizard::BannerPixmap. + +.. variable:: CPACK_IFW_PACKAGE_BACKGROUND + + Filename for an image used as QWizard::BackgroundPixmap (only used by MacStyle). + +.. variable:: CPACK_IFW_PACKAGE_WIZARD_STYLE + + Wizard style to be used ("Modern", "Mac", "Aero" or "Classic"). + +.. variable:: CPACK_IFW_PACKAGE_WIZARD_DEFAULT_WIDTH + + Default width of the wizard in pixels. Setting a banner image will override this. + +.. variable:: CPACK_IFW_PACKAGE_WIZARD_DEFAULT_HEIGHT + + Default height of the wizard in pixels. Setting a watermark image will override this. + +.. variable:: CPACK_IFW_PACKAGE_TITLE_COLOR + + Color of the titles and subtitles (takes an HTML color code, such as "#88FF33"). + +.. variable:: CPACK_IFW_PACKAGE_START_MENU_DIRECTORY + + Name of the default program group for the product in the Windows Start menu. + + By default used :variable:`CPACK_IFW_PACKAGE_NAME`. + +.. variable:: CPACK_IFW_TARGET_DIRECTORY + + Default target directory for installation. + By default used + "@ApplicationsDir@/:variable:`CPACK_PACKAGE_INSTALL_DIRECTORY`" + + You can use predefined variables. + +.. variable:: CPACK_IFW_ADMIN_TARGET_DIRECTORY + + Default target directory for installation with administrator rights. + + You can use predefined variables. + +.. variable:: CPACK_IFW_PACKAGE_GROUP + + The group, which will be used to configure the root package + +.. variable:: CPACK_IFW_PACKAGE_NAME + + The root package name, which will be used if configuration group is not + specified + +.. variable:: CPACK_IFW_PACKAGE_MAINTENANCE_TOOL_NAME + + Filename of the generated maintenance tool. + The platform-specific executable file extension is appended. + + By default used QtIFW_ defaults (``maintenancetool``). + +.. variable:: CPACK_IFW_PACKAGE_REMOVE_TARGET_DIR + + Set to ``OFF`` if the target directory should not be deleted when uninstalling. + + Is ``ON`` by default + +.. variable:: CPACK_IFW_PACKAGE_MAINTENANCE_TOOL_INI_FILE + + Filename for the configuration of the generated maintenance tool. + + By default used QtIFW_ defaults (``maintenancetool.ini``). + +.. variable:: CPACK_IFW_PACKAGE_ALLOW_NON_ASCII_CHARACTERS + + Set to ``ON`` if the installation path can contain non-ASCII characters. + + Is ``ON`` for QtIFW_ less 2.0 tools. + +.. variable:: CPACK_IFW_PACKAGE_ALLOW_SPACE_IN_PATH + + Set to ``OFF`` if the installation path cannot contain space characters. + + Is ``ON`` for QtIFW_ less 2.0 tools. + +.. variable:: CPACK_IFW_PACKAGE_CONTROL_SCRIPT + + Filename for a custom installer control script. + +.. variable:: CPACK_IFW_PACKAGE_RESOURCES + + List of additional resources ('.qrc' files) to include in the installer + binary. + + You can use :command:`cpack_ifw_add_package_resources` command to resolve + relative paths. + +.. variable:: CPACK_IFW_PACKAGE_FILE_EXTENSION + + The target binary extension. + + On Linux, the name of the target binary is automatically extended with + '.run', if you do not specify the extension. + + On Windows, the target is created as an application with the extension + '.exe', which is automatically added, if not supplied. + + On Mac, the target is created as an DMG disk image with the extension + '.dmg', which is automatically added, if not supplied. + +.. variable:: CPACK_IFW_REPOSITORIES_ALL + + The list of remote repositories. + + The default value of this variable is computed by CPack and contains + all repositories added with command :command:`cpack_ifw_add_repository` + or updated with command :command:`cpack_ifw_update_repository`. + +.. variable:: CPACK_IFW_DOWNLOAD_ALL + + If this is ``ON`` all components will be downloaded. + By default is ``OFF`` or used value + from ``CPACK_DOWNLOAD_ALL`` if set + +Components +"""""""""" + +.. variable:: CPACK_IFW_RESOLVE_DUPLICATE_NAMES + + Resolve duplicate names when installing components with groups. + +.. variable:: CPACK_IFW_PACKAGES_DIRECTORIES + + Additional prepared packages dirs that will be used to resolve + dependent components. + +.. variable:: CPACK_IFW_REPOSITORIES_DIRECTORIES + + Additional prepared repository dirs that will be used to resolve and + repack dependent components. This feature available only + since QtIFW_ 3.1. + +Tools +""""" + +.. variable:: CPACK_IFW_FRAMEWORK_VERSION + + The version of used QtIFW_ tools. + +.. variable:: CPACK_IFW_BINARYCREATOR_EXECUTABLE + + The path to "binarycreator" command line client. + + This variable is cached and may be configured if needed. + +.. variable:: CPACK_IFW_REPOGEN_EXECUTABLE + + The path to "repogen" command line client. + + This variable is cached and may be configured if needed. + +.. variable:: CPACK_IFW_INSTALLERBASE_EXECUTABLE + + The path to "installerbase" installer executable base. + + This variable is cached and may be configured if needed. + +.. variable:: CPACK_IFW_DEVTOOL_EXECUTABLE + + The path to "devtool" command line client. + + This variable is cached and may be configured if needed. + + +Online installer +^^^^^^^^^^^^^^^^ + +By default CPack IFW generator makes offline installer. This means that all +components will be packaged into a binary file. + +To make a component downloaded, you must set the ``DOWNLOADED`` option in +:command:`cpack_add_component`. + +Then you would use the command :command:`cpack_configure_downloads`. +If you set ``ALL`` option all components will be downloaded. + +You also can use command :command:`cpack_ifw_add_repository` and +variable :variable:`CPACK_IFW_DOWNLOAD_ALL` for more specific configuration. + +CPack IFW generator creates "repository" dir in current binary dir. You +would copy content of this dir to specified ``site`` (``url``). + +See Also +^^^^^^^^ + +Qt Installer Framework Manual: + +* Index page: + http://doc.qt.io/qtinstallerframework/index.html + +* Component Scripting: + http://doc.qt.io/qtinstallerframework/scripting.html + +* Predefined Variables: + http://doc.qt.io/qtinstallerframework/scripting.html#predefined-variables + +* Promoting Updates: + http://doc.qt.io/qtinstallerframework/ifw-updates.html + +Download Qt Installer Framework for you platform from Qt site: + http://download.qt.io/official_releases/qt-installer-framework diff --git a/Help/cpack_gen/nsis.rst b/Help/cpack_gen/nsis.rst new file mode 100644 index 0000000..9f82a04 --- /dev/null +++ b/Help/cpack_gen/nsis.rst @@ -0,0 +1,130 @@ +CPack NSIS Generator +-------------------- + +CPack NSIS generator specific options + +Variables specific to CPack NSIS generator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following variables are specific to the graphical installers built +on Windows using the Nullsoft Installation System. + +.. variable:: CPACK_NSIS_INSTALL_ROOT + + The default installation directory presented to the end user by the NSIS + installer is under this root dir. The full directory presented to the end + user is: ${CPACK_NSIS_INSTALL_ROOT}/${CPACK_PACKAGE_INSTALL_DIRECTORY} + +.. variable:: CPACK_NSIS_MUI_ICON + + An icon filename. The name of a ``*.ico`` file used as the main icon for the + generated install program. + +.. variable:: CPACK_NSIS_MUI_UNIICON + + An icon filename. The name of a ``*.ico`` file used as the main icon for the + generated uninstall program. + +.. variable:: CPACK_NSIS_INSTALLER_MUI_ICON_CODE + + undocumented. + +.. variable:: CPACK_NSIS_MUI_WELCOMEFINISHPAGE_BITMAP + + The filename of a bitmap to use as the NSIS MUI_WELCOMEFINISHPAGE_BITMAP. + +.. variable:: CPACK_NSIS_MUI_UNWELCOMEFINISHPAGE_BITMAP + + The filename of a bitmap to use as the NSIS MUI_UNWELCOMEFINISHPAGE_BITMAP. + +.. variable:: CPACK_NSIS_EXTRA_PREINSTALL_COMMANDS + + Extra NSIS commands that will be added to the beginning of the install + Section, before your install tree is available on the target system. + +.. variable:: CPACK_NSIS_EXTRA_INSTALL_COMMANDS + + Extra NSIS commands that will be added to the end of the install Section, + after your install tree is available on the target system. + +.. variable:: CPACK_NSIS_EXTRA_UNINSTALL_COMMANDS + + Extra NSIS commands that will be added to the uninstall Section, before + your install tree is removed from the target system. + +.. variable:: CPACK_NSIS_COMPRESSOR + + The arguments that will be passed to the NSIS SetCompressor command. + +.. variable:: CPACK_NSIS_ENABLE_UNINSTALL_BEFORE_INSTALL + + Ask about uninstalling previous versions first. If this is set to "ON", + then an installer will look for previous installed versions and if one is + found, ask the user whether to uninstall it before proceeding with the + install. + +.. variable:: CPACK_NSIS_MODIFY_PATH + + Modify PATH toggle. If this is set to "ON", then an extra page will appear + in the installer that will allow the user to choose whether the program + directory should be added to the system PATH variable. + +.. variable:: CPACK_NSIS_DISPLAY_NAME + + The display name string that appears in the Windows Add/Remove Program + control panel + +.. variable:: CPACK_NSIS_PACKAGE_NAME + + The title displayed at the top of the installer. + +.. variable:: CPACK_NSIS_INSTALLED_ICON_NAME + + A path to the executable that contains the installer icon. + +.. variable:: CPACK_NSIS_HELP_LINK + + URL to a web site providing assistance in installing your application. + +.. variable:: CPACK_NSIS_URL_INFO_ABOUT + + URL to a web site providing more information about your application. + +.. variable:: CPACK_NSIS_CONTACT + + Contact information for questions and comments about the installation + process. + +.. variable:: CPACK_NSIS_<compName>_INSTALL_DIRECTORY + + Custom install directory for the specified component <compName> instead + of $INSTDIR. + +.. variable:: CPACK_NSIS_CREATE_ICONS_EXTRA + + Additional NSIS commands for creating start menu shortcuts. + +.. variable:: CPACK_NSIS_DELETE_ICONS_EXTRA + + Additional NSIS commands to uninstall start menu shortcuts. + +.. variable:: CPACK_NSIS_EXECUTABLES_DIRECTORY + + Creating NSIS start menu links assumes that they are in 'bin' unless this + variable is set. For example, you would set this to 'exec' if your + executables are in an exec directory. + +.. variable:: CPACK_NSIS_MUI_FINISHPAGE_RUN + + Specify an executable to add an option to run on the finish page of the + NSIS installer. + +.. variable:: CPACK_NSIS_MENU_LINKS + + Specify links in [application] menu. This should contain a list of pair + "link" "link name". The link may be a URL or a path relative to + installation prefix. Like:: + + set(CPACK_NSIS_MENU_LINKS + "doc/cmake-@CMake_VERSION_MAJOR@.@CMake_VERSION_MINOR@/cmake.html" + "CMake Help" "https://cmake.org" "CMake Web Site") diff --git a/Help/cpack_gen/nuget.rst b/Help/cpack_gen/nuget.rst new file mode 100644 index 0000000..c8c481f --- /dev/null +++ b/Help/cpack_gen/nuget.rst @@ -0,0 +1,189 @@ +CPack NuGet Generator +--------------------- + +When build a NuGet package there is no direct way to control an output +filename due a lack of the corresponding CLI option of NuGet, so there +is no ``CPACK_NUGET_PACKAGE_FILENAME`` variable. To form the output filename +NuGet uses the package name and the version according to its built-in rules. + +Also, be aware that including a top level directory +(``CPACK_INCLUDE_TOPLEVEL_DIRECTORY``) is ignored by this generator. + + +Variables specific to CPack NuGet generator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The CPack NuGet generator may be used to create NuGet packages using +:module:`CPack`. The CPack NuGet generator is a :module:`CPack` generator thus +it uses the ``CPACK_XXX`` variables used by :module:`CPack`. + +The CPack NuGet generator has specific features which are controlled by the +specifics :code:`CPACK_NUGET_XXX` variables. In the "one per group" mode +(see :variable:`CPACK_COMPONENTS_GROUPING`), ``<compName>`` placeholder +in the variables below would contain a group name (uppercased and turned into +a "C" identifier). + +List of CPack NuGet generator specific variables: + +.. variable:: CPACK_NUGET_COMPONENT_INSTALL + + Enable component packaging for CPack NuGet generator + + * Mandatory : NO + * Default : OFF + +.. variable:: CPACK_NUGET_PACKAGE_NAME + CPACK_NUGET_<compName>_PACKAGE_NAME + + The NUGET package name. + + * Mandatory : YES + * Default : :variable:`CPACK_PACKAGE_NAME` + +.. variable:: CPACK_NUGET_PACKAGE_VERSION + CPACK_NUGET_<compName>_PACKAGE_VERSION + + The NuGet package version. + + * Mandatory : YES + * Default : :variable:`CPACK_PACKAGE_VERSION` + +.. variable:: CPACK_NUGET_PACKAGE_DESCRIPTION + CPACK_NUGET_<compName>_PACKAGE_DESCRIPTION + + A long description of the package for UI display. + + * Mandatory : YES + * Default : + - :variable:`CPACK_COMPONENT_<compName>_DESCRIPTION`, + - ``CPACK_COMPONENT_GROUP_<groupName>_DESCRIPTION``, + - :variable:`CPACK_PACKAGE_DESCRIPTION` + +.. variable:: CPACK_NUGET_PACKAGE_AUTHORS + CPACK_NUGET_<compName>_PACKAGE_AUTHORS + + A comma-separated list of packages authors, matching the profile names + on nuget.org_. These are displayed in the NuGet Gallery on + nuget.org_ and are used to cross-reference packages by the same + authors. + + * Mandatory : YES + * Default : :variable:`CPACK_PACKAGE_VENDOR` + +.. variable:: CPACK_NUGET_PACKAGE_TITLE + CPACK_NUGET_<compName>_PACKAGE_TITLE + + A human-friendly title of the package, typically used in UI displays + as on nuget.org_ and the Package Manager in Visual Studio. If not + specified, the package ID is used. + + * Mandatory : NO + * Default : + - :variable:`CPACK_COMPONENT_<compName>_DISPLAY_NAME`, + - ``CPACK_COMPONENT_GROUP_<groupName>_DISPLAY_NAME`` + +.. variable:: CPACK_NUGET_PACKAGE_OWNERS + CPACK_NUGET_<compName>_PACKAGE_OWNERS + + A comma-separated list of the package creators using profile names + on nuget.org_. This is often the same list as in authors, + and is ignored when uploading the package to nuget.org_. + + * Mandatory : NO + * Default : - + +.. variable:: CPACK_NUGET_PACKAGE_HOMEPAGE_URL + CPACK_NUGET_<compName>_PACKAGE_HOMEPAGE_URL + + A URL for the package's home page, often shown in UI displays as well + as nuget.org_. + + * Mandatory : NO + * Default : :variable:`CPACK_PACKAGE_HOMEPAGE_URL` + +.. variable:: CPACK_NUGET_PACKAGE_LICENSEURL + CPACK_NUGET_<compName>_PACKAGE_LICENSEURL + + A URL for the package's license, often shown in UI displays as well + as nuget.org_. + + * Mandatory : NO + * Default : - + +.. variable:: CPACK_NUGET_PACKAGE_ICONURL + CPACK_NUGET_<compName>_PACKAGE_ICONURL + + A URL for a 64x64 image with transparency background to use as the + icon for the package in UI display. + + * Mandatory : NO + * Default : - + +.. variable:: CPACK_NUGET_PACKAGE_DESCRIPTION_SUMMARY + CPACK_NUGET_<compName>_PACKAGE_DESCRIPTION_SUMMARY + + A short description of the package for UI display. If omitted, a + truncated version of description is used. + + * Mandatory : NO + * Default : :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY` + +.. variable:: CPACK_NUGET_PACKAGE_RELEASE_NOTES + CPACK_NUGET_<compName>_PACKAGE_RELEASE_NOTES + + A description of the changes made in this release of the package, + often used in UI like the Updates tab of the Visual Studio Package + Manager in place of the package description. + + * Mandatory : NO + * Default : - + +.. variable:: CPACK_NUGET_PACKAGE_COPYRIGHT + CPACK_NUGET_<compName>_PACKAGE_COPYRIGHT + + Copyright details for the package. + + * Mandatory : NO + * Default : - + +.. variable:: CPACK_NUGET_PACKAGE_TAGS + CPACK_NUGET_<compName>_PACKAGE_TAGS + + A space-delimited list of tags and keywords that describe the + package and aid discoverability of packages through search and + filtering. + + * Mandatory : NO + * Default : - + +.. variable:: CPACK_NUGET_PACKAGE_DEPENDENCIES + CPACK_NUGET_<compName>_PACKAGE_DEPENDENCIES + + A list of package dependencies. + + * Mandatory : NO + * Default : - + +.. variable:: CPACK_NUGET_PACKAGE_DEPENDENCIES_<dependency>_VERSION + CPACK_NUGET_<compName>_PACKAGE_DEPENDENCIES_<dependency>_VERSION + + A `version specification`_ for the particular dependency, where + ``<dependency>`` is an item of the dependency list (see above) + transformed with ``MAKE_C_IDENTIFIER`` function of :command:`string` + command. + + * Mandatory : NO + * Default : - + +.. variable:: CPACK_NUGET_PACKAGE_DEBUG + + Enable debug messages while executing CPack NuGet generator. + + * Mandatory : NO + * Default : OFF + + +.. _nuget.org: http://nuget.org +.. _version specification: https://docs.microsoft.com/en-us/nuget/reference/package-versioning#version-ranges-and-wildcards + +.. NuGet spec docs https://docs.microsoft.com/en-us/nuget/reference/nuspec diff --git a/Help/cpack_gen/packagemaker.rst b/Help/cpack_gen/packagemaker.rst new file mode 100644 index 0000000..e9464b7 --- /dev/null +++ b/Help/cpack_gen/packagemaker.rst @@ -0,0 +1,23 @@ +CPack PackageMaker Generator +---------------------------- + +PackageMaker CPack generator (macOS). + +Variables specific to CPack PackageMaker generator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following variable is specific to installers built on Mac +macOS using PackageMaker: + +.. variable:: CPACK_OSX_PACKAGE_VERSION + + The version of macOS that the resulting PackageMaker archive should be + compatible with. Different versions of macOS support different + features. For example, CPack can only build component-based installers for + macOS 10.4 or newer, and can only build installers that download + component son-the-fly for macOS 10.5 or newer. If left blank, this value + will be set to the minimum version of macOS that supports the requested + features. Set this variable to some value (e.g., 10.4) only if you want to + guarantee that your installer will work on that version of macOS, and + don't mind missing extra features available in the installer shipping with + later versions of macOS. diff --git a/Help/cpack_gen/productbuild.rst b/Help/cpack_gen/productbuild.rst new file mode 100644 index 0000000..d22fcd4 --- /dev/null +++ b/Help/cpack_gen/productbuild.rst @@ -0,0 +1,68 @@ +CPack productbuild Generator +---------------------------- + +productbuild CPack generator (macOS). + +Variables specific to CPack productbuild generator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following variable is specific to installers built on Mac +macOS using ProductBuild: + +.. variable:: CPACK_COMMAND_PRODUCTBUILD + + Path to the ``productbuild(1)`` command used to generate a product archive for + the macOS Installer or Mac App Store. This variable can be used to override + the automatically detected command (or specify its location if the + auto-detection fails to find it). + +.. variable:: CPACK_PRODUCTBUILD_IDENTITY_NAME + + Adds a digital signature to the resulting package. + + +.. variable:: CPACK_PRODUCTBUILD_KEYCHAIN_PATH + + Specify a specific keychain to search for the signing identity. + + +.. variable:: CPACK_COMMAND_PKGBUILD + + Path to the ``pkgbuild(1)`` command used to generate an macOS component package + on macOS. This variable can be used to override the automatically detected + command (or specify its location if the auto-detection fails to find it). + + +.. variable:: CPACK_PKGBUILD_IDENTITY_NAME + + Adds a digital signature to the resulting package. + + +.. variable:: CPACK_PKGBUILD_KEYCHAIN_PATH + + Specify a specific keychain to search for the signing identity. + + +.. variable:: CPACK_PREFLIGHT_<COMP>_SCRIPT + + Full path to a file that will be used as the ``preinstall`` script for the + named ``<COMP>`` component's package, where ``<COMP>`` is the uppercased + component name. No ``preinstall`` script is added if this variable is not + defined for a given component. + + +.. variable:: CPACK_POSTFLIGHT_<COMP>_SCRIPT + + Full path to a file that will be used as the ``postinstall`` script for the + named ``<COMP>`` component's package, where ``<COMP>`` is the uppercased + component name. No ``postinstall`` script is added if this variable is not + defined for a given component. + + +.. variable:: CPACK_PRODUCTBUILD_RESOURCES_DIR + + If specified the productbuild generator copies files from this directory + (including subdirectories) to the ``Resources`` directory. This is done + before the :variable:`CPACK_RESOURCE_FILE_WELCOME`, + :variable:`CPACK_RESOURCE_FILE_README`, and + :variable:`CPACK_RESOURCE_FILE_LICENSE` files are copied. diff --git a/Help/cpack_gen/rpm.rst b/Help/cpack_gen/rpm.rst new file mode 100644 index 0000000..5c543ff --- /dev/null +++ b/Help/cpack_gen/rpm.rst @@ -0,0 +1,955 @@ +CPack RPM Generator +------------------- + +The built in (binary) CPack RPM generator (Unix only) + +Variables specific to CPack RPM generator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The CPack RPM generator may be used to create RPM packages using :module:`CPack`. +The CPack RPM generator is a :module:`CPack` generator thus it uses the +``CPACK_XXX`` variables used by :module:`CPack`. + +The CPack RPM generator has specific features which are controlled by the specifics +:code:`CPACK_RPM_XXX` variables. + +:code:`CPACK_RPM_<COMPONENT>_XXXX` variables may be used in order to have +**component** specific values. Note however that ``<COMPONENT>`` refers to the +**grouping name** written in upper case. It may be either a component name or +a component GROUP name. Usually those variables correspond to RPM spec file +entities. One may find information about spec files here +http://www.rpm.org/wiki/Docs + +.. note:: + + `<COMPONENT>` part of variables is preferred to be in upper case (for e.g. if + component is named `foo` then use `CPACK_RPM_FOO_XXXX` variable name format) + as is with other `CPACK_<COMPONENT>_XXXX` variables. + For the purposes of back compatibility (CMake/CPack version 3.5 and lower) + support for same cased component (e.g. `fOo` would be used as + `CPACK_RPM_fOo_XXXX`) is still supported for variables defined in older + versions of CMake/CPack but is not guaranteed for variables that + will be added in the future. For the sake of back compatibility same cased + component variables also override upper cased versions where both are + present. + +Here are some CPack RPM generator wiki resources that are here for historic reasons and +are no longer maintained but may still prove useful: + + - https://gitlab.kitware.com/cmake/community/wikis/doc/cpack/Configuration + - https://gitlab.kitware.com/cmake/community/wikis/doc/cpack/PackageGenerators#rpm-unix-only + +List of CPack RPM generator specific variables: + +.. variable:: CPACK_RPM_COMPONENT_INSTALL + + Enable component packaging for CPack RPM generator + + * Mandatory : NO + * Default : OFF + + If enabled (ON) multiple packages are generated. By default a single package + containing files of all components is generated. + +.. variable:: CPACK_RPM_PACKAGE_SUMMARY + CPACK_RPM_<component>_PACKAGE_SUMMARY + + The RPM package summary. + + * Mandatory : YES + * Default : :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY` + +.. variable:: CPACK_RPM_PACKAGE_NAME + CPACK_RPM_<component>_PACKAGE_NAME + + The RPM package name. + + * Mandatory : YES + * Default : :variable:`CPACK_PACKAGE_NAME` + +.. variable:: CPACK_RPM_FILE_NAME + CPACK_RPM_<component>_FILE_NAME + + Package file name. + + * Mandatory : YES + * Default : ``<CPACK_PACKAGE_FILE_NAME>[-<component>].rpm`` with spaces + replaced by '-' + + This may be set to ``RPM-DEFAULT`` to allow rpmbuild tool to generate package + file name by itself. + Alternatively provided package file name must end with ``.rpm`` suffix. + + .. note:: + + By using user provided spec file, rpm macro extensions such as for + generating debuginfo packages or by simply using multiple components more + than one rpm file may be generated, either from a single spec file or from + multiple spec files (each component execution produces its own spec file). + In such cases duplicate file names may occur as a result of this variable + setting or spec file content structure. Duplicate files get overwritten + and it is up to the packager to set the variables in a manner that will + prevent such errors. + +.. variable:: CPACK_RPM_MAIN_COMPONENT + + Main component that is packaged without component suffix. + + * Mandatory : NO + * Default : - + + This variable can be set to any component or group name so that component or + group rpm package is generated without component suffix in filename and + package name. + +.. variable:: CPACK_RPM_PACKAGE_EPOCH + + The RPM package epoch + + * Mandatory : No + * Default : - + + Optional number that should be incremented when changing versioning schemas + or fixing mistakes in the version numbers of older packages. + +.. variable:: CPACK_RPM_PACKAGE_VERSION + + The RPM package version. + + * Mandatory : YES + * Default : :variable:`CPACK_PACKAGE_VERSION` + +.. variable:: CPACK_RPM_PACKAGE_ARCHITECTURE + CPACK_RPM_<component>_PACKAGE_ARCHITECTURE + + The RPM package architecture. + + * Mandatory : YES + * Default : Native architecture output by ``uname -m`` + + This may be set to ``noarch`` if you know you are building a noarch package. + +.. variable:: CPACK_RPM_PACKAGE_RELEASE + + The RPM package release. + + * Mandatory : YES + * Default : 1 + + This is the numbering of the RPM package itself, i.e. the version of the + packaging and not the version of the content (see + :variable:`CPACK_RPM_PACKAGE_VERSION`). One may change the default value if + the previous packaging was buggy and/or you want to put here a fancy Linux + distro specific numbering. + +.. note:: + + This is the string that goes into the RPM ``Release:`` field. Some distros + (e.g. Fedora, CentOS) require ``1%{?dist}`` format and not just a number. + ``%{?dist}`` part can be added by setting :variable:`CPACK_RPM_PACKAGE_RELEASE_DIST`. + +.. variable:: CPACK_RPM_PACKAGE_RELEASE_DIST + + The dist tag that is added RPM ``Release:`` field. + + * Mandatory : NO + * Default : OFF + + This is the reported ``%{dist}`` tag from the current distribution or empty + ``%{dist}`` if RPM macro is not set. If this variable is set then RPM + ``Release:`` field value is set to ``${CPACK_RPM_PACKAGE_RELEASE}%{?dist}``. + +.. variable:: CPACK_RPM_PACKAGE_LICENSE + + The RPM package license policy. + + * Mandatory : YES + * Default : "unknown" + +.. variable:: CPACK_RPM_PACKAGE_GROUP + CPACK_RPM_<component>_PACKAGE_GROUP + + The RPM package group. + + * Mandatory : YES + * Default : "unknown" + +.. variable:: CPACK_RPM_PACKAGE_VENDOR + + The RPM package vendor. + + * Mandatory : YES + * Default : CPACK_PACKAGE_VENDOR if set or "unknown" + +.. variable:: CPACK_RPM_PACKAGE_URL + CPACK_RPM_<component>_PACKAGE_URL + + The projects URL. + + * Mandatory : NO + * Default : :variable:`CMAKE_PROJECT_HOMEPAGE_URL` + +.. variable:: CPACK_RPM_PACKAGE_DESCRIPTION + CPACK_RPM_<component>_PACKAGE_DESCRIPTION + + RPM package description. + + * Mandatory : YES + * Default : :variable:`CPACK_COMPONENT_<compName>_DESCRIPTION` (component + based installers only) if set, :variable:`CPACK_PACKAGE_DESCRIPTION_FILE` + if set or "no package description available" + +.. variable:: CPACK_RPM_COMPRESSION_TYPE + + RPM compression type. + + * Mandatory : NO + * Default : - + + May be used to override RPM compression type to be used to build the + RPM. For example some Linux distribution now default to lzma or xz + compression whereas older cannot use such RPM. Using this one can enforce + compression type to be used. + + Possible values are: + + - lzma + - xz + - bzip2 + - gzip + +.. variable:: CPACK_RPM_PACKAGE_AUTOREQ + CPACK_RPM_<component>_PACKAGE_AUTOREQ + + RPM spec autoreq field. + + * Mandatory : NO + * Default : - + + May be used to enable (1, yes) or disable (0, no) automatic shared libraries + dependency detection. Dependencies are added to requires list. + + .. note:: + + By default automatic dependency detection is enabled by rpm generator. + +.. variable:: CPACK_RPM_PACKAGE_AUTOPROV + CPACK_RPM_<component>_PACKAGE_AUTOPROV + + RPM spec autoprov field. + + * Mandatory : NO + * Default : - + + May be used to enable (1, yes) or disable (0, no) automatic listing of shared + libraries that are provided by the package. Shared libraries are added to + provides list. + + .. note:: + + By default automatic provides detection is enabled by rpm generator. + +.. variable:: CPACK_RPM_PACKAGE_AUTOREQPROV + CPACK_RPM_<component>_PACKAGE_AUTOREQPROV + + RPM spec autoreqprov field. + + * Mandatory : NO + * Default : - + + Variable enables/disables autoreq and autoprov at the same time. + See :variable:`CPACK_RPM_PACKAGE_AUTOREQ` and :variable:`CPACK_RPM_PACKAGE_AUTOPROV` + for more details. + + .. note:: + + By default automatic detection feature is enabled by rpm. + +.. variable:: CPACK_RPM_PACKAGE_REQUIRES + CPACK_RPM_<component>_PACKAGE_REQUIRES + + RPM spec requires field. + + * Mandatory : NO + * Default : - + + May be used to set RPM dependencies (requires). Note that you must enclose + the complete requires string between quotes, for example:: + + set(CPACK_RPM_PACKAGE_REQUIRES "python >= 2.5.0, cmake >= 2.8") + + The required package list of an RPM file could be printed with:: + + rpm -qp --requires file.rpm + +.. variable:: CPACK_RPM_PACKAGE_CONFLICTS + CPACK_RPM_<component>_PACKAGE_CONFLICTS + + RPM spec conflicts field. + + * Mandatory : NO + * Default : - + + May be used to set negative RPM dependencies (conflicts). Note that you must + enclose the complete requires string between quotes, for example:: + + set(CPACK_RPM_PACKAGE_CONFLICTS "libxml2") + + The conflicting package list of an RPM file could be printed with:: + + rpm -qp --conflicts file.rpm + +.. variable:: CPACK_RPM_PACKAGE_REQUIRES_PRE + CPACK_RPM_<component>_PACKAGE_REQUIRES_PRE + + RPM spec requires(pre) field. + + * Mandatory : NO + * Default : - + + May be used to set RPM preinstall dependencies (requires(pre)). Note that + you must enclose the complete requires string between quotes, for example:: + + set(CPACK_RPM_PACKAGE_REQUIRES_PRE "shadow-utils, initscripts") + +.. variable:: CPACK_RPM_PACKAGE_REQUIRES_POST + CPACK_RPM_<component>_PACKAGE_REQUIRES_POST + + RPM spec requires(post) field. + + * Mandatory : NO + * Default : - + + May be used to set RPM postinstall dependencies (requires(post)). Note that + you must enclose the complete requires string between quotes, for example:: + + set(CPACK_RPM_PACKAGE_REQUIRES_POST "shadow-utils, initscripts") + +.. variable:: CPACK_RPM_PACKAGE_REQUIRES_POSTUN + CPACK_RPM_<component>_PACKAGE_REQUIRES_POSTUN + + RPM spec requires(postun) field. + + * Mandatory : NO + * Default : - + + May be used to set RPM postuninstall dependencies (requires(postun)). Note + that you must enclose the complete requires string between quotes, for + example:: + + set(CPACK_RPM_PACKAGE_REQUIRES_POSTUN "shadow-utils, initscripts") + +.. variable:: CPACK_RPM_PACKAGE_REQUIRES_PREUN + CPACK_RPM_<component>_PACKAGE_REQUIRES_PREUN + + RPM spec requires(preun) field. + + * Mandatory : NO + * Default : - + + May be used to set RPM preuninstall dependencies (requires(preun)). Note that + you must enclose the complete requires string between quotes, for example:: + + set(CPACK_RPM_PACKAGE_REQUIRES_PREUN "shadow-utils, initscripts") + +.. variable:: CPACK_RPM_PACKAGE_SUGGESTS + CPACK_RPM_<component>_PACKAGE_SUGGESTS + + RPM spec suggest field. + + * Mandatory : NO + * Default : - + + May be used to set weak RPM dependencies (suggests). Note that you must + enclose the complete requires string between quotes. + +.. variable:: CPACK_RPM_PACKAGE_PROVIDES + CPACK_RPM_<component>_PACKAGE_PROVIDES + + RPM spec provides field. + + * Mandatory : NO + * Default : - + + May be used to set RPM dependencies (provides). The provided package list + of an RPM file could be printed with:: + + rpm -qp --provides file.rpm + +.. variable:: CPACK_RPM_PACKAGE_OBSOLETES + CPACK_RPM_<component>_PACKAGE_OBSOLETES + + RPM spec obsoletes field. + + * Mandatory : NO + * Default : - + + May be used to set RPM packages that are obsoleted by this one. + +.. variable:: CPACK_RPM_PACKAGE_RELOCATABLE + + build a relocatable RPM. + + * Mandatory : NO + * Default : CPACK_PACKAGE_RELOCATABLE + + If this variable is set to TRUE or ON, the CPack RPM generator will try + to build a relocatable RPM package. A relocatable RPM may + be installed using:: + + rpm --prefix or --relocate + + in order to install it at an alternate place see rpm(8). Note that + currently this may fail if :variable:`CPACK_SET_DESTDIR` is set to ``ON``. If + :variable:`CPACK_SET_DESTDIR` is set then you will get a warning message but + if there is file installed with absolute path you'll get unexpected behavior. + +.. variable:: CPACK_RPM_SPEC_INSTALL_POST + + Deprecated - use :variable:`CPACK_RPM_SPEC_MORE_DEFINE` instead. + + * Mandatory : NO + * Default : - + * Deprecated: YES + + May be used to override the ``__spec_install_post`` section within the + generated spec file. This affects the install step during package creation, + not during package installation. For adding operations to be performed + during package installation, use + :variable:`CPACK_RPM_POST_INSTALL_SCRIPT_FILE` instead. + +.. variable:: CPACK_RPM_SPEC_MORE_DEFINE + + RPM extended spec definitions lines. + + * Mandatory : NO + * Default : - + + May be used to add any ``%define`` lines to the generated spec file. An + example of its use is to prevent stripping of executables (but note that + this may also disable other default post install processing):: + + set(CPACK_RPM_SPEC_MORE_DEFINE "%define __spec_install_post /bin/true") + +.. variable:: CPACK_RPM_PACKAGE_DEBUG + + Toggle CPack RPM generator debug output. + + * Mandatory : NO + * Default : - + + May be set when invoking cpack in order to trace debug information + during CPack RPM run. For example you may launch CPack like this:: + + cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -G RPM + +.. variable:: CPACK_RPM_USER_BINARY_SPECFILE + CPACK_RPM_<componentName>_USER_BINARY_SPECFILE + + A user provided spec file. + + * Mandatory : NO + * Default : - + + May be set by the user in order to specify a USER binary spec file + to be used by the CPack RPM generator instead of generating the file. + The specified file will be processed by configure_file( @ONLY). + +.. variable:: CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE + + Spec file template. + + * Mandatory : NO + * Default : - + + If set CPack will generate a template for USER specified binary + spec file and stop with an error. For example launch CPack like this:: + + cpack -D CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE=1 -G RPM + + The user may then use this file in order to hand-craft is own + binary spec file which may be used with + :variable:`CPACK_RPM_USER_BINARY_SPECFILE`. + +.. variable:: CPACK_RPM_PRE_INSTALL_SCRIPT_FILE + CPACK_RPM_PRE_UNINSTALL_SCRIPT_FILE + + Path to file containing pre (un)install script. + + * Mandatory : NO + * Default : - + + May be used to embed a pre (un)installation script in the spec file. + The referred script file (or both) will be read and directly + put after the ``%pre`` or ``%preun`` section + If :variable:`CPACK_RPM_COMPONENT_INSTALL` is set to ON the (un)install + script for each component can be overridden with + ``CPACK_RPM_<COMPONENT>_PRE_INSTALL_SCRIPT_FILE`` and + ``CPACK_RPM_<COMPONENT>_PRE_UNINSTALL_SCRIPT_FILE``. + One may verify which scriptlet has been included with:: + + rpm -qp --scripts package.rpm + +.. variable:: CPACK_RPM_POST_INSTALL_SCRIPT_FILE + CPACK_RPM_POST_UNINSTALL_SCRIPT_FILE + + Path to file containing post (un)install script. + + * Mandatory : NO + * Default : - + + May be used to embed a post (un)installation script in the spec file. + The referred script file (or both) will be read and directly + put after the ``%post`` or ``%postun`` section. + If :variable:`CPACK_RPM_COMPONENT_INSTALL` is set to ON the (un)install + script for each component can be overridden with + ``CPACK_RPM_<COMPONENT>_POST_INSTALL_SCRIPT_FILE`` and + ``CPACK_RPM_<COMPONENT>_POST_UNINSTALL_SCRIPT_FILE``. + One may verify which scriptlet has been included with:: + + rpm -qp --scripts package.rpm + +.. variable:: CPACK_RPM_USER_FILELIST + CPACK_RPM_<COMPONENT>_USER_FILELIST + + * Mandatory : NO + * Default : - + + May be used to explicitly specify ``%(<directive>)`` file line + in the spec file. Like ``%config(noreplace)`` or any other directive + that be found in the ``%files`` section. You can have multiple directives + per line, as in ``%attr(600,root,root) %config(noreplace)``. Since + the CPack RPM generator is generating the list of files (and directories) the + user specified files of the ``CPACK_RPM_<COMPONENT>_USER_FILELIST`` list will + be removed from the generated list. If referring to directories do + not add a trailing slash. + +.. variable:: CPACK_RPM_CHANGELOG_FILE + + RPM changelog file. + + * Mandatory : NO + * Default : - + + May be used to embed a changelog in the spec file. + The referred file will be read and directly put after the ``%changelog`` + section. + +.. variable:: CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST + + list of path to be excluded. + + * Mandatory : NO + * Default : /etc /etc/init.d /usr /usr/bin /usr/include /usr/lib + /usr/libx32 /usr/lib64 /usr/share /usr/share/aclocal + /usr/share/doc + + May be used to exclude path (directories or files) from the auto-generated + list of paths discovered by CPack RPM. The default value contains a + reasonable set of values if the variable is not defined by the user. If the + variable is defined by the user then the CPack RPM generator will NOT any of + the default path. If you want to add some path to the default list then you + can use :variable:`CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST_ADDITION` variable. + +.. variable:: CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST_ADDITION + + additional list of path to be excluded. + + * Mandatory : NO + * Default : - + + May be used to add more exclude path (directories or files) from the initial + default list of excluded paths. See + :variable:`CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST`. + +.. variable:: CPACK_RPM_RELOCATION_PATHS + + Packages relocation paths list. + + * Mandatory : NO + * Default : - + + May be used to specify more than one relocation path per relocatable RPM. + Variable contains a list of relocation paths that if relative are prefixed + by the value of :variable:`CPACK_RPM_<COMPONENT>_PACKAGE_PREFIX` or by the + value of :variable:`CPACK_PACKAGING_INSTALL_PREFIX` if the component version + is not provided. + Variable is not component based as its content can be used to set a different + path prefix for e.g. binary dir and documentation dir at the same time. + Only prefixes that are required by a certain component are added to that + component - component must contain at least one file/directory/symbolic link + with :variable:`CPACK_RPM_RELOCATION_PATHS` prefix for a certain relocation + path to be added. Package will not contain any relocation paths if there are + no files/directories/symbolic links on any of the provided prefix locations. + Packages that either do not contain any relocation paths or contain + files/directories/symbolic links that are outside relocation paths print + out an ``AUTHOR_WARNING`` that RPM will be partially relocatable. + +.. variable:: CPACK_RPM_<COMPONENT>_PACKAGE_PREFIX + + Per component relocation path install prefix. + + * Mandatory : NO + * Default : CPACK_PACKAGING_INSTALL_PREFIX + + May be used to set per component :variable:`CPACK_PACKAGING_INSTALL_PREFIX` + for relocatable RPM packages. + +.. variable:: CPACK_RPM_NO_INSTALL_PREFIX_RELOCATION + CPACK_RPM_NO_<COMPONENT>_INSTALL_PREFIX_RELOCATION + + Removal of default install prefix from relocation paths list. + + * Mandatory : NO + * Default : CPACK_PACKAGING_INSTALL_PREFIX or CPACK_RPM_<COMPONENT>_PACKAGE_PREFIX + are treated as one of relocation paths + + May be used to remove CPACK_PACKAGING_INSTALL_PREFIX and CPACK_RPM_<COMPONENT>_PACKAGE_PREFIX + from relocatable RPM prefix paths. + +.. variable:: CPACK_RPM_ADDITIONAL_MAN_DIRS + + * Mandatory : NO + * Default : - + + May be used to set additional man dirs that could potentially be compressed + by brp-compress RPM macro. Variable content must be a list of regular + expressions that point to directories containing man files or to man files + directly. Note that in order to compress man pages a path must also be + present in brp-compress RPM script and that brp-compress script must be + added to RPM configuration by the operating system. + + Regular expressions that are added by default were taken from brp-compress + RPM macro: + + - /usr/man/man.* + - /usr/man/.*/man.* + - /usr/info.* + - /usr/share/man/man.* + - /usr/share/man/.*/man.* + - /usr/share/info.* + - /usr/kerberos/man.* + - /usr/X11R6/man/man.* + - /usr/lib/perl5/man/man.* + - /usr/share/doc/.*/man/man.* + - /usr/lib/.*/man/man.* + +.. variable:: CPACK_RPM_DEFAULT_USER + CPACK_RPM_<compName>_DEFAULT_USER + + default user ownership of RPM content + + * Mandatory : NO + * Default : root + + Value should be user name and not UID. + Note that <compName> must be in upper-case. + +.. variable:: CPACK_RPM_DEFAULT_GROUP + CPACK_RPM_<compName>_DEFAULT_GROUP + + default group ownership of RPM content + + * Mandatory : NO + * Default : root + + Value should be group name and not GID. + Note that <compName> must be in upper-case. + +.. variable:: CPACK_RPM_DEFAULT_FILE_PERMISSIONS + CPACK_RPM_<compName>_DEFAULT_FILE_PERMISSIONS + + default permissions used for packaged files + + * Mandatory : NO + * Default : - (system default) + + Accepted values are lists with ``PERMISSIONS``. Valid permissions + are: + + - OWNER_READ + - OWNER_WRITE + - OWNER_EXECUTE + - GROUP_READ + - GROUP_WRITE + - GROUP_EXECUTE + - WORLD_READ + - WORLD_WRITE + - WORLD_EXECUTE + + Note that <compName> must be in upper-case. + +.. variable:: CPACK_RPM_DEFAULT_DIR_PERMISSIONS + CPACK_RPM_<compName>_DEFAULT_DIR_PERMISSIONS + + default permissions used for packaged directories + + * Mandatory : NO + * Default : - (system default) + + Accepted values are lists with PERMISSIONS. Valid permissions + are the same as for :variable:`CPACK_RPM_DEFAULT_FILE_PERMISSIONS`. + Note that <compName> must be in upper-case. + +.. variable:: CPACK_RPM_INSTALL_WITH_EXEC + + force execute permissions on programs and shared libraries + + * Mandatory : NO + * Default : - (system default) + + Force set owner, group and world execute permissions on programs and shared + libraries. This can be used for creating valid rpm packages on systems such + as Debian where shared libraries do not have execute permissions set. + +.. note:: + + Programs and shared libraries without execute permissions are ignored during + separation of debug symbols from the binary for debuginfo packages. + +Packaging of Symbolic Links +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The CPack RPM generator supports packaging of symbolic links:: + + execute_process(COMMAND ${CMAKE_COMMAND} + -E create_symlink <relative_path_location> <symlink_name>) + install(FILES ${CMAKE_CURRENT_BINARY_DIR}/<symlink_name> + DESTINATION <symlink_location> COMPONENT libraries) + +Symbolic links will be optimized (paths will be shortened if possible) +before being added to the package or if multiple relocation paths are +detected, a post install symlink relocation script will be generated. + +Symbolic links may point to locations that are not packaged by the same +package (either a different component or even not packaged at all) but +those locations will be treated as if they were a part of the package +while determining if symlink should be either created or present in a +post install script - depending on relocation paths. + +Symbolic links that point to locations outside packaging path produce a +warning and are treated as non relocatable permanent symbolic links. + +Currently there are a few limitations though: + +* For component based packaging component interdependency is not checked + when processing symbolic links. Symbolic links pointing to content of + a different component are treated the same way as if pointing to location + that will not be packaged. + +* Symbolic links pointing to a location through one or more intermediate + symbolic links will not be handled differently - if the intermediate + symbolic link(s) is also on a relocatable path, relocating it during + package installation may cause initial symbolic link to point to an + invalid location. + +Packaging of debug information +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Debuginfo packages contain debug symbols and sources for debugging packaged +binaries. + +Debuginfo RPM packaging has its own set of variables: + +.. variable:: CPACK_RPM_DEBUGINFO_PACKAGE + CPACK_RPM_<component>_DEBUGINFO_PACKAGE + + Enable generation of debuginfo RPM package(s). + + * Mandatory : NO + * Default : OFF + +.. note:: + + Binaries must contain debug symbols before packaging so use either ``Debug`` + or ``RelWithDebInfo`` for :variable:`CMAKE_BUILD_TYPE` variable value. + +.. note:: + + Packages generated from packages without binary files, with binary files but + without execute permissions or without debug symbols will cause packaging + termination. + +.. variable:: CPACK_BUILD_SOURCE_DIRS + + Provides locations of root directories of source files from which binaries + were built. + + * Mandatory : YES if :variable:`CPACK_RPM_DEBUGINFO_PACKAGE` is set + * Default : - + +.. note:: + + For CMake project :variable:`CPACK_BUILD_SOURCE_DIRS` is set by default to + point to :variable:`CMAKE_SOURCE_DIR` and :variable:`CMAKE_BINARY_DIR` paths. + +.. note:: + + Sources with path prefixes that do not fall under any location provided with + :variable:`CPACK_BUILD_SOURCE_DIRS` will not be present in debuginfo package. + +.. variable:: CPACK_RPM_BUILD_SOURCE_DIRS_PREFIX + CPACK_RPM_<component>_BUILD_SOURCE_DIRS_PREFIX + + Prefix of location where sources will be placed during package installation. + + * Mandatory : YES if :variable:`CPACK_RPM_DEBUGINFO_PACKAGE` is set + * Default : "/usr/src/debug/<CPACK_PACKAGE_FILE_NAME>" and + for component packaging "/usr/src/debug/<CPACK_PACKAGE_FILE_NAME>-<component>" + +.. note:: + + Each source path prefix is additionally suffixed by ``src_<index>`` where + index is index of the path used from :variable:`CPACK_BUILD_SOURCE_DIRS` + variable. This produces ``<CPACK_RPM_BUILD_SOURCE_DIRS_PREFIX>/src_<index>`` + replacement path. + Limitation is that replaced path part must be shorter or of equal + length than the length of its replacement. If that is not the case either + :variable:`CPACK_RPM_BUILD_SOURCE_DIRS_PREFIX` variable has to be set to + a shorter path or source directories must be placed on a longer path. + +.. variable:: CPACK_RPM_DEBUGINFO_EXCLUDE_DIRS + + Directories containing sources that should be excluded from debuginfo packages. + + * Mandatory : NO + * Default : "/usr /usr/src /usr/src/debug" + + Listed paths are owned by other RPM packages and should therefore not be + deleted on debuginfo package uninstallation. + +.. variable:: CPACK_RPM_DEBUGINFO_EXCLUDE_DIRS_ADDITION + + Paths that should be appended to :variable:`CPACK_RPM_DEBUGINFO_EXCLUDE_DIRS` + for exclusion. + + * Mandatory : NO + * Default : - + +.. variable:: CPACK_RPM_DEBUGINFO_SINGLE_PACKAGE + + Create a single debuginfo package even if components packaging is set. + + * Mandatory : NO + * Default : OFF + + When this variable is enabled it produces a single debuginfo package even if + component packaging is enabled. + + When using this feature in combination with components packaging and there is + more than one component this variable requires :variable:`CPACK_RPM_MAIN_COMPONENT` + to be set. + +.. note:: + + If none of the :variable:`CPACK_RPM_<component>_DEBUGINFO_PACKAGE` variables + is set then :variable:`CPACK_RPM_DEBUGINFO_PACKAGE` is automatically set to + ``ON`` when :variable:`CPACK_RPM_DEBUGINFO_SINGLE_PACKAGE` is set. + +.. variable:: CPACK_RPM_DEBUGINFO_FILE_NAME + CPACK_RPM_<component>_DEBUGINFO_FILE_NAME + + Debuginfo package file name. + + * Mandatory : NO + * Default : rpmbuild tool generated package file name + + Alternatively provided debuginfo package file name must end with ``.rpm`` + suffix and should differ from file names of other generated packages. + + Variable may contain ``@cpack_component@`` placeholder which will be + replaced by component name if component packaging is enabled otherwise it + deletes the placeholder. + + Setting the variable to ``RPM-DEFAULT`` may be used to explicitly set + filename generation to default. + +.. note:: + + :variable:`CPACK_RPM_FILE_NAME` also supports rpmbuild tool generated package + file name - disabled by default but can be enabled by setting the variable to + ``RPM-DEFAULT``. + +Packaging of sources (SRPM) +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +SRPM packaging is enabled by setting :variable:`CPACK_RPM_PACKAGE_SOURCES` +variable while usually using :variable:`CPACK_INSTALLED_DIRECTORIES` variable +to provide directory containing CMakeLists.txt and source files. + +For CMake projects SRPM package would be produced by executing:: + + cpack -G RPM --config ./CPackSourceConfig.cmake + +.. note:: + + Produced SRPM package is expected to be built with :manual:`cmake(1)` executable + and packaged with :manual:`cpack(1)` executable so CMakeLists.txt has to be + located in root source directory and must be able to generate binary rpm + packages by executing ``cpack -G`` command. The two executables as well as + rpmbuild must also be present when generating binary rpm packages from the + produced SRPM package. + +Once the SRPM package is generated it can be used to generate binary packages +by creating a directory structure for rpm generation and executing rpmbuild +tool:: + + mkdir -p build_dir/{BUILD,BUILDROOT,RPMS,SOURCES,SPECS,SRPMS} + rpmbuild --define "_topdir <path_to_build_dir>" --rebuild <SRPM_file_name> + +Generated packages will be located in build_dir/RPMS directory or its sub +directories. + +.. note:: + + SRPM package internally uses CPack/RPM generator to generate binary packages + so CMakeScripts.txt can decide during the SRPM to binary rpm generation step + what content the package(s) should have as well as how they should be packaged + (monolithic or components). CMake can decide this for e.g. by reading environment + variables set by the package manager before starting the process of generating + binary rpm packages. This way a single SRPM package can be used to produce + different binary rpm packages on different platforms depending on the platform's + packaging rules. + +Source RPM packaging has its own set of variables: + +.. variable:: CPACK_RPM_PACKAGE_SOURCES + + Should the content be packaged as a source rpm (default is binary rpm). + + * Mandatory : NO + * Default : OFF + +.. note:: + + For cmake projects :variable:`CPACK_RPM_PACKAGE_SOURCES` variable is set + to ``OFF`` in CPackConfig.cmake and ``ON`` in CPackSourceConfig.cmake + generated files. + +.. variable:: CPACK_RPM_SOURCE_PKG_BUILD_PARAMS + + Additional command-line parameters provided to :manual:`cmake(1)` executable. + + * Mandatory : NO + * Default : - + +.. variable:: CPACK_RPM_SOURCE_PKG_PACKAGING_INSTALL_PREFIX + + Packaging install prefix that would be provided in :variable:`CPACK_PACKAGING_INSTALL_PREFIX` + variable for producing binary RPM packages. + + * Mandatory : YES + * Default : "/" + +.. VARIABLE:: CPACK_RPM_BUILDREQUIRES + + List of source rpm build dependencies. + + * Mandatory : NO + * Default : - + + May be used to set source RPM build dependencies (BuildRequires). Note that + you must enclose the complete build requirements string between quotes, for + example:: + + set(CPACK_RPM_BUILDREQUIRES "python >= 2.5.0, cmake >= 2.8") diff --git a/Help/cpack_gen/wix.rst b/Help/cpack_gen/wix.rst new file mode 100644 index 0000000..fc8a098 --- /dev/null +++ b/Help/cpack_gen/wix.rst @@ -0,0 +1,284 @@ +CPack WiX Generator +------------------- + +CPack WiX generator specific options + +Variables specific to CPack WiX generator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following variables are specific to the installers built on +Windows using WiX. + +.. variable:: CPACK_WIX_UPGRADE_GUID + + Upgrade GUID (``Product/@UpgradeCode``) + + Will be automatically generated unless explicitly provided. + + It should be explicitly set to a constant generated globally unique + identifier (GUID) to allow your installers to replace existing + installations that use the same GUID. + + You may for example explicitly set this variable in your + CMakeLists.txt to the value that has been generated per default. You + should not use GUIDs that you did not generate yourself or which may + belong to other projects. + + A GUID shall have the following fixed length syntax:: + + XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX + + (each X represents an uppercase hexadecimal digit) + +.. variable:: CPACK_WIX_PRODUCT_GUID + + Product GUID (``Product/@Id``) + + Will be automatically generated unless explicitly provided. + + If explicitly provided this will set the Product Id of your installer. + + The installer will abort if it detects a pre-existing installation that + uses the same GUID. + + The GUID shall use the syntax described for CPACK_WIX_UPGRADE_GUID. + +.. variable:: CPACK_WIX_LICENSE_RTF + + RTF License File + + If CPACK_RESOURCE_FILE_LICENSE has an .rtf extension it is used as-is. + + If CPACK_RESOURCE_FILE_LICENSE has an .txt extension it is implicitly + converted to RTF by the WiX Generator. + The expected encoding of the .txt file is UTF-8. + + With CPACK_WIX_LICENSE_RTF you can override the license file used by the + WiX Generator in case CPACK_RESOURCE_FILE_LICENSE is in an unsupported + format or the .txt -> .rtf conversion does not work as expected. + +.. variable:: CPACK_WIX_PRODUCT_ICON + + The Icon shown next to the program name in Add/Remove programs. + + If set, this icon is used in place of the default icon. + +.. variable:: CPACK_WIX_UI_REF + + This variable allows you to override the Id of the ``<UIRef>`` element + in the WiX template. + + The default is ``WixUI_InstallDir`` in case no CPack components have + been defined and ``WixUI_FeatureTree`` otherwise. + +.. variable:: CPACK_WIX_UI_BANNER + + The bitmap will appear at the top of all installer pages other than the + welcome and completion dialogs. + + If set, this image will replace the default banner image. + + This image must be 493 by 58 pixels. + +.. variable:: CPACK_WIX_UI_DIALOG + + Background bitmap used on the welcome and completion dialogs. + + If this variable is set, the installer will replace the default dialog + image. + + This image must be 493 by 312 pixels. + +.. variable:: CPACK_WIX_PROGRAM_MENU_FOLDER + + Start menu folder name for launcher. + + If this variable is not set, it will be initialized with CPACK_PACKAGE_NAME + +.. variable:: CPACK_WIX_CULTURES + + Language(s) of the installer + + Languages are compiled into the WixUI extension library. To use them, + simply provide the name of the culture. If you specify more than one + culture identifier in a comma or semicolon delimited list, the first one + that is found will be used. You can find a list of supported languages at: + http://wix.sourceforge.net/manual-wix3/WixUI_localization.htm + +.. variable:: CPACK_WIX_TEMPLATE + + Template file for WiX generation + + If this variable is set, the specified template will be used to generate + the WiX wxs file. This should be used if further customization of the + output is required. + + If this variable is not set, the default MSI template included with CMake + will be used. + +.. variable:: CPACK_WIX_PATCH_FILE + + Optional list of XML files with fragments to be inserted into + generated WiX sources + + This optional variable can be used to specify an XML file that the + WiX generator will use to inject fragments into its generated + source files. + + Patch files understood by the CPack WiX generator + roughly follow this RELAX NG compact schema: + + .. code-block:: none + + start = CPackWiXPatch + + CPackWiXPatch = element CPackWiXPatch { CPackWiXFragment* } + + CPackWiXFragment = element CPackWiXFragment + { + attribute Id { string }, + fragmentContent* + } + + fragmentContent = element * - CPackWiXFragment + { + (attribute * { text } | text | fragmentContent)* + } + + Currently fragments can be injected into most + Component, File, Directory and Feature elements. + + The following additional special Ids can be used: + + * ``#PRODUCT`` for the ``<Product>`` element. + * ``#PRODUCTFEATURE`` for the root ``<Feature>`` element. + + The following example illustrates how this works. + + Given that the WiX generator creates the following XML element: + + .. code-block:: xml + + <Component Id="CM_CP_applications.bin.my_libapp.exe" Guid="*"/> + + The following XML patch file may be used to inject an Environment element + into it: + + .. code-block:: xml + + <CPackWiXPatch> + <CPackWiXFragment Id="CM_CP_applications.bin.my_libapp.exe"> + <Environment Id="MyEnvironment" Action="set" + Name="MyVariableName" Value="MyVariableValue"/> + </CPackWiXFragment> + </CPackWiXPatch> + +.. variable:: CPACK_WIX_EXTRA_SOURCES + + Extra WiX source files + + This variable provides an optional list of extra WiX source files (.wxs) + that should be compiled and linked. The full path to source files is + required. + +.. variable:: CPACK_WIX_EXTRA_OBJECTS + + Extra WiX object files or libraries + + This variable provides an optional list of extra WiX object (.wixobj) + and/or WiX library (.wixlib) files. The full path to objects and libraries + is required. + +.. variable:: CPACK_WIX_EXTENSIONS + + This variable provides a list of additional extensions for the WiX + tools light and candle. + +.. variable:: CPACK_WIX_<TOOL>_EXTENSIONS + + This is the tool specific version of CPACK_WIX_EXTENSIONS. + ``<TOOL>`` can be either LIGHT or CANDLE. + +.. variable:: CPACK_WIX_<TOOL>_EXTRA_FLAGS + + This list variable allows you to pass additional + flags to the WiX tool ``<TOOL>``. + + Use it at your own risk. + Future versions of CPack may generate flags which may be in conflict + with your own flags. + + ``<TOOL>`` can be either LIGHT or CANDLE. + +.. variable:: CPACK_WIX_CMAKE_PACKAGE_REGISTRY + + If this variable is set the generated installer will create + an entry in the windows registry key + ``HKEY_LOCAL_MACHINE\Software\Kitware\CMake\Packages\<PackageName>`` + The value for ``<PackageName>`` is provided by this variable. + + Assuming you also install a CMake configuration file this will + allow other CMake projects to find your package with + the :command:`find_package` command. + +.. variable:: CPACK_WIX_PROPERTY_<PROPERTY> + + This variable can be used to provide a value for + the Windows Installer property ``<PROPERTY>`` + + The following list contains some example properties that can be used to + customize information under + "Programs and Features" (also known as "Add or Remove Programs") + + * ARPCOMMENTS - Comments + * ARPHELPLINK - Help and support information URL + * ARPURLINFOABOUT - General information URL + * ARPURLUPDATEINFO - Update information URL + * ARPHELPTELEPHONE - Help and support telephone number + * ARPSIZE - Size (in kilobytes) of the application + +.. variable:: CPACK_WIX_ROOT_FEATURE_TITLE + + Sets the name of the root install feature in the WIX installer. Same as + CPACK_COMPONENT_<compName>_DISPLAY_NAME for components. + +.. variable:: CPACK_WIX_ROOT_FEATURE_DESCRIPTION + + Sets the description of the root install feature in the WIX installer. Same as + CPACK_COMPONENT_<compName>_DESCRIPTION for components. + +.. variable:: CPACK_WIX_SKIP_PROGRAM_FOLDER + + If this variable is set to true, the default install location + of the generated package will be CPACK_PACKAGE_INSTALL_DIRECTORY directly. + The install location will not be located relatively below + ProgramFiles or ProgramFiles64. + + .. note:: + Installers created with this feature do not take differences + between the system on which the installer is created + and the system on which the installer might be used into account. + + It is therefore possible that the installer e.g. might try to install + onto a drive that is unavailable or unintended or a path that does not + follow the localization or convention of the system on which the + installation is performed. + +.. variable:: CPACK_WIX_ROOT_FOLDER_ID + + This variable allows specification of a custom root folder ID. + The generator specific ``<64>`` token can be used for + folder IDs that come in 32-bit and 64-bit variants. + In 32-bit builds the token will expand empty while in 64-bit builds + it will expand to ``64``. + + When unset generated installers will default installing to + ``ProgramFiles<64>Folder``. + +.. variable:: CPACK_WIX_ROOT + + This variable can optionally be set to the root directory + of a custom WiX Toolset installation. + + When unspecified CPack will try to locate a WiX Toolset + installation via the ``WIX`` environment variable instead. diff --git a/Help/dev/README.rst b/Help/dev/README.rst new file mode 100644 index 0000000..ce62abc --- /dev/null +++ b/Help/dev/README.rst @@ -0,0 +1,49 @@ +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`_. + +.. _`CMake Source Code Guide`: source.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/maint.rst b/Help/dev/maint.rst new file mode 100644 index 0000000..a8942cd --- /dev/null +++ b/Help/dev/maint.rst @@ -0,0 +1,255 @@ +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 is not named well for the change it makes + (e.g. it is just ``master`` or the patch changed during review), + add a ``Topic-rename: <topic>`` trailing line to the MR description + to provide a better topic name. + +* If the MR introduces a new feature or a user-facing behavior change, + such as a policy, ensure that a ``Help/release/dev/$topic.rst`` file + is added with a release note. + +* If a commit changes a specific area, such as a module, its commit + message should have an ``area:`` prefix on its first line. + +* If a commit fixes a tracked issue, its commit message should have + a trailing line such as ``Fixes: #00000``. + +* Ensure that the MR adds sufficient documentation and test cases. + +* Ensure that the MR has been tested sufficiently. Typically it should + be staged for nightly testing with ``Do: stage``. Then manually + review the `CMake CDash Page`_ to verify that no regressions were + introduced. (Learn to tolerate spurious failures due to idiosyncrasies + of various nightly builders.) + +* Ensure that the MR targets the ``master`` branch. A MR intended for + the ``release`` branch should be based on ``release`` but still merged + to ``master`` first (via ``Do: merge``). A maintainer may then merge + the MR topic to ``release`` manually. + +Maintain Current Release +======================== + +The ``release`` branch is used to maintain the current release or release +candidate. The branch is published with no version number but maintained +using a local branch named ``release-$ver``, where ``$ver`` is the version +number of the current release in the form ``$major.$minor``. It is always +merged into ``master`` before publishing. + +Before merging a ``$topic`` branch into ``release``, verify that the +``$topic`` branch has already been merged to ``master`` via the usual +``Do: merge`` process. Then, to merge the ``$topic`` branch into +``release``, start by creating the local branch: + +.. code-block:: shell + + git fetch origin + git checkout -b release-$ver origin/release + +Merge the ``$topic`` branch into the local ``release-$ver`` branch, making +sure to include a ``Merge-request: !xxxx`` footer in the commit message: + +.. code-block:: shell + + git merge --no-ff $topic + +Merge the ``release-$ver`` branch to ``master``: + +.. code-block:: shell + + git checkout master + git pull + git merge --no-ff release-$ver + +Review new ancestry to ensure nothing unexpected was merged to either branch: + +.. code-block:: shell + + git log --graph --boundary origin/master..master + git log --graph --boundary origin/release..release-$ver + +Publish both ``master`` and ``release`` simultaneously: + +.. code-block:: shell + + git push --atomic origin master release-$ver:release + +.. _`CMake Review Process`: review.rst +.. _`CMake CDash Page`: https://open.cdash.org/index.php?project=CMake + +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. + +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 ``Source/CMakeVersion.cmake`` to set the version to +``$major.$minor.0-rc1``: + +.. 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 1) + +Update ``Utilities/Release/upload_release.cmake``: + +.. code-block:: cmake + + set(VERSION $ver) + +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:: + + CMake $major.$minor.0-rc1 version update + +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 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 + +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 1) + +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 +------------------------- + +Send email to the ``cmake-developers@cmake.org`` mailing list (perhaps +in reply to a release preparation thread) announcing that post-release +development is open:: + + 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. diff --git a/Help/dev/review.rst b/Help/dev/review.rst new file mode 100644 index 0000000..a524115 --- /dev/null +++ b/Help/dev/review.rst @@ -0,0 +1,430 @@ +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. + +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 <commit> (<subject>, <date>)``, where: + +* ``<commit>``: + If available, a tag-relative name of the commit produced by + ``git describe --contains <commit-ish>``. Otherwise, the first + 8-10 characters of the commit ``<hash>``. + +* ``<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. + +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 has a `buildbot`_ instance watching for merge requests to test. +`CMake GitLab Project Developers`_ may activate buildbot on a MR 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 inform buildbot about the request. The buildbot +user (``@buildbot``) will schedule builds and respond with a comment +linking to the `CMake CDash Page`_ with a filter for results associated +with the topic test request. If the MR topic branch is updated by a +push a new ``Do: test`` command is needed to activate testing again. + +The ``Do: test`` command accepts the following arguments: + +* ``--stop``: clear the list of commands for the merge request +* ``--clear``: clear previous commands before adding this command +* ``--regex-include <arg>`` or ``-i <arg>``: only build on builders + matching ``<arg>`` (a Python regular expression) +* ``--regex-exclude <arg>`` or ``-e <arg>``: exclude builds on builders + matching ``<arg>`` (a Python regular expression) + +Builder names follow the pattern ``project-host-os-buildtype-generator``: + +* ``project``: always ``cmake`` for CMake builds +* ``host``: the buildbot host +* ``os``: one of ``windows``, ``osx``, or ``linux`` +* ``buildtype``: ``release`` or ``debug`` +* ``generator``: ``ninja``, ``makefiles``, ``vs<year>``, + or ``lint-iwyu-tidy`` + +The special ``lint-<tools>`` generator name is a builder that builds +CMake using lint tools but does not run the test suite (so the actual +generator does not matter). + +.. _`buildbot`: http://buildbot.net +.. _`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. + +`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 +======= + +A MR may be resolved in one of the following ways. + +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): + +* ``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 + +Close +----- + +If review has concluded that the MR should not be integrated then it +may be closed through GitLab. + +Expire +------ + +If progress on a MR has stalled for a while, it may be closed with a +``workflow:expired`` label and a comment indicating that the MR has +been closed due to inactivity. + +Contributors are welcome to re-open an expired MR when they are ready +to continue work. Please re-open *before* pushing an update to the +MR topic branch to ensure GitLab will still act on the association. diff --git a/Help/dev/source.rst b/Help/dev/source.rst new file mode 100644 index 0000000..57de818 --- /dev/null +++ b/Help/dev/source.rst @@ -0,0 +1,95 @@ +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 or above. However, in order to support +building on older toolchains some constructs need to be handled with care: + +* Do not use ``std::auto_ptr``. + + The ``std::auto_ptr`` template is deprecated in C++11. Use ``std::unique_ptr``. + +* Use ``CM_DISABLE_COPY(Class)`` to mark classes as non-copyable. + + The ``CM_DISABLE_COPY`` macro should be used in the private section of a + class to make sure that attempts to copy or assign an instance of the class + lead to compiler errors even if the compiler does not support *deleted* + functions. As a guideline, all polymorphic classes should be made + non-copyable in order to avoid slicing. Classes that are composed of or + derived from non-copyable classes must also be made non-copyable explicitly + with ``CM_DISABLE_COPY``. + +* Use ``size_t`` instead of ``std::size_t``. + + Various implementations have differing implementation of ``size_t``. + When assigning the result of ``.size()`` on a container for example, + the result should be assigned to ``size_t`` not to ``std::size_t``, + ``unsigned int`` or similar types. + +Source Tree Layout +================== + +The CMake source tree is organized as follows. + +* ``Auxiliary/``: + Shell and editor integration files. + +* ``Help/``: + Documentation. + + * ``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/Sphinx/``: + Sphinx configuration to build CMake user documentation. + + * ``Utilities/Release/``: + Scripts used to package CMake itself for distribution on ``cmake.org``. + +.. _`Tests/README.rst`: ../../Tests/README.rst diff --git a/Help/dev/testing.rst b/Help/dev/testing.rst new file mode 100644 index 0000000..23d0ca3 --- /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..ec48f71 --- /dev/null +++ b/Help/envvar/ASM_DIALECT.rst @@ -0,0 +1,11 @@ +ASM<DIALECT> +------------ + +Preferred executable for compiling a specific dialect of assembly language +files. ``ASM<DIALECT>`` can be ``ASM``, ``ASM_NASM``, ``ASM_MASM`` or +``ASM-ATT``. Will only be used by CMake on the first configuration to determine +``ASM<DIALECT>`` compiler, after which the value for ``ASM<DIALECT>`` is stored +in the cache as +:variable:`CMAKE_ASM<DIALECT>_COMPILER <CMAKE_<LANG>_COMPILER>`. For subsequent +configuration runs, the environment variable will be ignored in favor of +:variable:`CMAKE_ASM<DIALECT>_COMPILER <CMAKE_<LANG>_COMPILER>`. diff --git a/Help/envvar/ASM_DIALECTFLAGS.rst b/Help/envvar/ASM_DIALECTFLAGS.rst new file mode 100644 index 0000000..4ed02fe --- /dev/null +++ b/Help/envvar/ASM_DIALECTFLAGS.rst @@ -0,0 +1,11 @@ +ASM<DIALECT>FLAGS +----------------- + +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 +:variable:`CMAKE_ASM<DIALECT>_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration +run (including the first), the environment variable will be ignored if the +:variable:`CMAKE_ASM<DIALECT>_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined. diff --git a/Help/envvar/CC.rst b/Help/envvar/CC.rst new file mode 100644 index 0000000..7e68110 --- /dev/null +++ b/Help/envvar/CC.rst @@ -0,0 +1,9 @@ +CC +-- + +Preferred executable for compiling ``C`` language files. Will only be used by +CMake on the first configuration to determine ``C`` compiler, after which the +value for ``CC`` is stored in the cache as +:variable:`CMAKE_C_COMPILER <CMAKE_<LANG>_COMPILER>`. For any configuration run +(including the first), the environment variable will be ignored if the +:variable:`CMAKE_C_COMPILER <CMAKE_<LANG>_COMPILER>` variable is defined. diff --git a/Help/envvar/CFLAGS.rst b/Help/envvar/CFLAGS.rst new file mode 100644 index 0000000..60b2cd3 --- /dev/null +++ b/Help/envvar/CFLAGS.rst @@ -0,0 +1,9 @@ +CFLAGS +------ + +Default compilation flags to be used when compiling ``C`` files. Will only be +used by CMake on the first configuration to determine ``CC`` default compilation +flags, after which the value for ``CFLAGS`` is stored in the cache +as :variable:`CMAKE_C_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration run +(including the first), the environment variable will be ignored if the +:variable:`CMAKE_C_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined. diff --git a/Help/envvar/CMAKE_BUILD_PARALLEL_LEVEL.rst b/Help/envvar/CMAKE_BUILD_PARALLEL_LEVEL.rst new file mode 100644 index 0000000..198dc51 --- /dev/null +++ b/Help/envvar/CMAKE_BUILD_PARALLEL_LEVEL.rst @@ -0,0 +1,9 @@ +CMAKE_BUILD_PARALLEL_LEVEL +-------------------------- + +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..1306b47 --- /dev/null +++ b/Help/envvar/CMAKE_CONFIG_TYPE.rst @@ -0,0 +1,5 @@ +CMAKE_CONFIG_TYPE +----------------- + +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_MSVCIDE_RUN_PATH.rst b/Help/envvar/CMAKE_MSVCIDE_RUN_PATH.rst new file mode 100644 index 0000000..54d5f9e --- /dev/null +++ b/Help/envvar/CMAKE_MSVCIDE_RUN_PATH.rst @@ -0,0 +1,8 @@ +CMAKE_MSVCIDE_RUN_PATH +---------------------- + +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_OSX_ARCHITECTURES.rst b/Help/envvar/CMAKE_OSX_ARCHITECTURES.rst new file mode 100644 index 0000000..5fd6e52 --- /dev/null +++ b/Help/envvar/CMAKE_OSX_ARCHITECTURES.rst @@ -0,0 +1,8 @@ +CMAKE_OSX_ARCHITECTURES +----------------------- + +Target specific architectures for macOS. + +The ``CMAKE_OSX_ARCHITECTURES`` environment variable sets the default value for +the :variable:`CMAKE_OSX_ARCHITECTURES` variable. See +:prop_tgt:`OSX_ARCHITECTURES` for more information. diff --git a/Help/envvar/CSFLAGS.rst b/Help/envvar/CSFLAGS.rst new file mode 100644 index 0000000..251ddc5 --- /dev/null +++ b/Help/envvar/CSFLAGS.rst @@ -0,0 +1,9 @@ +CSFLAGS +------- + +Preferred executable for compiling ``CSharp`` language files. Will only be +used by CMake on the first configuration to determine ``CSharp`` default +compilation flags, after which the value for ``CSFLAGS`` is stored in the cache +as :variable:`CMAKE_CSharp_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration +run (including the first), the environment variable will be ignored if the +:variable:`CMAKE_CSharp_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined. diff --git a/Help/envvar/CTEST_INTERACTIVE_DEBUG_MODE.rst b/Help/envvar/CTEST_INTERACTIVE_DEBUG_MODE.rst new file mode 100644 index 0000000..25ed14f --- /dev/null +++ b/Help/envvar/CTEST_INTERACTIVE_DEBUG_MODE.rst @@ -0,0 +1,5 @@ +CTEST_INTERACTIVE_DEBUG_MODE +---------------------------- + +Environment variable that will exist and be set to ``1`` when a test executed +by CTest 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..1fcf42b --- /dev/null +++ b/Help/envvar/CTEST_OUTPUT_ON_FAILURE.rst @@ -0,0 +1,7 @@ +CTEST_OUTPUT_ON_FAILURE +----------------------- + +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..c767a01 --- /dev/null +++ b/Help/envvar/CTEST_PARALLEL_LEVEL.rst @@ -0,0 +1,5 @@ +CTEST_PARALLEL_LEVEL +-------------------- + +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_USE_LAUNCHERS_DEFAULT.rst b/Help/envvar/CTEST_USE_LAUNCHERS_DEFAULT.rst new file mode 100644 index 0000000..8d8eea5 --- /dev/null +++ b/Help/envvar/CTEST_USE_LAUNCHERS_DEFAULT.rst @@ -0,0 +1,4 @@ +CTEST_USE_LAUNCHERS_DEFAULT +--------------------------- + +Initializes the :variable:`CTEST_USE_LAUNCHERS` variable if not already defined. diff --git a/Help/envvar/CUDACXX.rst b/Help/envvar/CUDACXX.rst new file mode 100644 index 0000000..8a5fd4b --- /dev/null +++ b/Help/envvar/CUDACXX.rst @@ -0,0 +1,9 @@ +CUDACXX +------- + +Preferred executable for compiling ``CUDA`` language files. Will only be used by +CMake on the first configuration to determine ``CUDA`` compiler, after which the +value for ``CUDA`` is stored in the cache as +:variable:`CMAKE_CUDA_COMPILER <CMAKE_<LANG>_COMPILER>`. For any configuration +run (including the first), the environment variable will be ignored if the +:variable:`CMAKE_CUDA_COMPILER <CMAKE_<LANG>_COMPILER>` variable is defined. diff --git a/Help/envvar/CUDAFLAGS.rst b/Help/envvar/CUDAFLAGS.rst new file mode 100644 index 0000000..3dff49f --- /dev/null +++ b/Help/envvar/CUDAFLAGS.rst @@ -0,0 +1,9 @@ +CUDAFLAGS +--------- + +Default compilation flags to be used when compiling ``CUDA`` files. Will only be +used by CMake on the first configuration to determine ``CUDA`` default +compilation flags, after which the value for ``CUDAFLAGS`` is stored in the +cache as :variable:`CMAKE_CUDA_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration +run (including the first), the environment variable will be ignored if +the :variable:`CMAKE_CUDA_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined. diff --git a/Help/envvar/CUDAHOSTCXX.rst b/Help/envvar/CUDAHOSTCXX.rst new file mode 100644 index 0000000..bb786ca --- /dev/null +++ b/Help/envvar/CUDAHOSTCXX.rst @@ -0,0 +1,13 @@ +CUDAHOSTCXX +----------- + +Preferred executable for compiling host code when compiling ``CUDA`` +language files. Will only be used by CMake on the first configuration to +determine ``CUDA`` host compiler, after which the value for ``CUDAHOSTCXX`` is +stored in the cache as :variable:`CMAKE_CUDA_HOST_COMPILER`. For any +configuration run (including the first), the environment variable will be +ignored if the :variable:`CMAKE_CUDA_HOST_COMPILER` variable is defined. + +This environment variable is primarily meant for use with projects that +enable ``CUDA`` as a first-class language. The :module:`FindCUDA` +module will also use it to initialize its ``CUDA_HOST_COMPILER`` setting. diff --git a/Help/envvar/CXX.rst b/Help/envvar/CXX.rst new file mode 100644 index 0000000..3b1e445 --- /dev/null +++ b/Help/envvar/CXX.rst @@ -0,0 +1,9 @@ +CXX +--- + +Preferred executable for compiling ``CXX`` language files. Will only be used by +CMake on the first configuration to determine ``CXX`` compiler, after which the +value for ``CXX`` is stored in the cache as +:variable:`CMAKE_CXX_COMPILER <CMAKE_<LANG>_COMPILER>`. For any configuration +run (including the first), the environment variable will be ignored if the +:variable:`CMAKE_CXX_COMPILER <CMAKE_<LANG>_COMPILER>` variable is defined. diff --git a/Help/envvar/CXXFLAGS.rst b/Help/envvar/CXXFLAGS.rst new file mode 100644 index 0000000..8b58abd --- /dev/null +++ b/Help/envvar/CXXFLAGS.rst @@ -0,0 +1,9 @@ +CXXFLAGS +-------- + +Default compilation flags to be used when compiling ``CXX`` (C++) files. Will +only be used by CMake on the first configuration to determine ``CXX`` default +compilation flags, after which the value for ``CXXFLAGS`` is stored in the cache +as :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration run ( +including the first), the environment variable will be ignored if +the :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined. diff --git a/Help/envvar/DASHBOARD_TEST_FROM_CTEST.rst b/Help/envvar/DASHBOARD_TEST_FROM_CTEST.rst new file mode 100644 index 0000000..fab1c0c --- /dev/null +++ b/Help/envvar/DASHBOARD_TEST_FROM_CTEST.rst @@ -0,0 +1,5 @@ +DASHBOARD_TEST_FROM_CTEST +------------------------- + +Environment variable that will exist when a test executed by CTest 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..87f1115 --- /dev/null +++ b/Help/envvar/DESTDIR.rst @@ -0,0 +1,19 @@ +DESTDIR +------- + +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/FC.rst b/Help/envvar/FC.rst new file mode 100644 index 0000000..7d293fd --- /dev/null +++ b/Help/envvar/FC.rst @@ -0,0 +1,10 @@ +FC +-- + +Preferred executable for compiling ``Fortran`` language files. Will only be used +by CMake on the first configuration to determine ``Fortran`` compiler, after +which the value for ``Fortran`` is stored in the cache as +:variable:`CMAKE_Fortran_COMPILER <CMAKE_<LANG>_COMPILER>`. For any +configuration run (including the first), the environment variable will be +ignored if the :variable:`CMAKE_Fortran_COMPILER <CMAKE_<LANG>_COMPILER>` +variable is defined. diff --git a/Help/envvar/FFLAGS.rst b/Help/envvar/FFLAGS.rst new file mode 100644 index 0000000..19d6169 --- /dev/null +++ b/Help/envvar/FFLAGS.rst @@ -0,0 +1,9 @@ +FFLAGS +------ + +Default compilation flags to be used when compiling ``Fortran`` files. Will only +be used by CMake on the first configuration to determine ``Fortran`` default +compilation flags, after which the value for ``FFLAGS`` is stored in the cache +as :variable:`CMAKE_Fortran_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration +run (including the first), the environment variable will be ignored if +the :variable:`CMAKE_Fortran_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined. diff --git a/Help/envvar/LDFLAGS.rst b/Help/envvar/LDFLAGS.rst new file mode 100644 index 0000000..52da99c --- /dev/null +++ b/Help/envvar/LDFLAGS.rst @@ -0,0 +1,10 @@ +LDFLAGS +------- + +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..9dafa32 --- /dev/null +++ b/Help/envvar/MACOSX_DEPLOYMENT_TARGET.rst @@ -0,0 +1,8 @@ +MACOSX_DEPLOYMENT_TARGET +------------------------ + +Specify the minimum version of macOS on which the target binaries are +to be deployed. + +The ``MACOSX_DEPLOYMENT_TARGET`` environment variable sets the default value for +the :variable:`CMAKE_OSX_DEPLOYMENT_TARGET` variable. diff --git a/Help/envvar/PackageName_ROOT.rst b/Help/envvar/PackageName_ROOT.rst new file mode 100644 index 0000000..e01009b --- /dev/null +++ b/Help/envvar/PackageName_ROOT.rst @@ -0,0 +1,15 @@ +<PackageName>_ROOT +------------------ + +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 ``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..6c2db19 --- /dev/null +++ b/Help/envvar/RC.rst @@ -0,0 +1,9 @@ +RC +-- + +Preferred executable for compiling ``resource`` files. Will only be used by CMake +on the first configuration to determine ``resource`` compiler, after which the +value for ``RC`` is stored in the cache as +:variable:`CMAKE_RC_COMPILER <CMAKE_<LANG>_COMPILER>`. For any configuration run +(including the first), the environment variable will be ignored if the +:variable:`CMAKE_RC_COMPILER <CMAKE_<LANG>_COMPILER>` variable is defined. diff --git a/Help/envvar/RCFLAGS.rst b/Help/envvar/RCFLAGS.rst new file mode 100644 index 0000000..4f2f31c --- /dev/null +++ b/Help/envvar/RCFLAGS.rst @@ -0,0 +1,9 @@ +RCFLAGS +------- + +Default compilation flags to be used when compiling ``resource`` files. Will +only be used by CMake on the first configuration to determine ``resource`` +default compilation flags, after which the value for ``RCFLAGS`` is stored in +the cache as :variable:`CMAKE_RC_FLAGS <CMAKE_<LANG>_FLAGS>`. For any +configuration run (including the first), the environment variable will be ignored +if the :variable:`CMAKE_RC_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined. diff --git a/Help/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..06cc746 --- /dev/null +++ b/Help/generator/CodeBlocks.rst @@ -0,0 +1,32 @@ +CodeBlocks +---------- + +Generates CodeBlocks project files. + +Project files for CodeBlocks will be created in the top directory and +in every subdirectory which features a CMakeLists.txt file containing +a PROJECT() call. Additionally a hierarchy of makefiles is generated +into the build tree. +The :variable:`CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES` variable may +be set to ``ON`` to exclude any files which are located outside of +the project root directory. +The appropriate make program can build the +project through the default make target. A "make install" target is +also provided. + +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`` + 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..3e60aa6 --- /dev/null +++ b/Help/generator/CodeLite.rst @@ -0,0 +1,28 @@ +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 :variable:`CMAKE_CODELITE_USE_TARGETS` variable may be set to ``ON`` +to change the default behaviour from projects to targets as the basis +for project files. +The appropriate make program can build the +project through the default make target. A "make install" target is +also provided. + +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..eb68bf0 --- /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 make target. A "make 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..1b4960d --- /dev/null +++ b/Help/generator/Green Hills MULTI.rst @@ -0,0 +1,52 @@ +Green Hills MULTI +----------------- + +Generates Green Hills MULTI project files (experimental, work-in-progress). + +Customizations that are used to pick toolset and target system: + +The ``-A <arch>`` can be supplied for setting the target architecture. +``<arch>`` usually is one of "arm", "ppc", "86", etcetera. If the target architecture +is not specified then the default architecture of "arm" will be used. + +The ``-T <toolset>`` can be supplied for setting the toolset to be used. +All toolsets are expected to be located at ``GHS_TOOLSET_ROOT``. +If the toolset is not specified then the latest toolset will be used. + +* ``GHS_TARGET_PLATFORM`` + +Default to ``integrity``. +Usual values are ``integrity``, ``threadx``, ``uvelosity``, +``velosity``, ``vxworks``, ``standalone``. + +* ``GHS_PRIMARY_TARGET`` + +Sets ``primaryTarget`` field in project file. +Defaults to ``<arch>_<GHS_TARGET_PLATFORM>.tgt``. + +* ``GHS_TOOLSET_ROOT`` + +Default to ``C:/ghs``. Root path for ``toolset``. + +* ``GHS_OS_ROOT`` + +Default to ``C:/ghs``. Root path for RTOS searches. + +* ``GHS_OS_DIR`` + +Default to latest platform OS installation at ``GHS_OS_ROOT``. Set this value if +a specific RTOS is to be used. + +* ``GHS_BSP_NAME`` + +Defaults to ``sim<arch>`` if not set by user. + +Customizations are available through the following cache variables: + +* ``GHS_CUSTOMIZATION`` +* ``GHS_GPJ_MACROS`` + +.. 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..9b61a93 --- /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 simply 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..f7cfa44 --- /dev/null +++ b/Help/generator/MSYS Makefiles.rst @@ -0,0 +1,11 @@ +MSYS Makefiles +-------------- + +Generates makefiles for use with MSYS ``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..9fe5fe3 --- /dev/null +++ b/Help/generator/MinGW Makefiles.rst @@ -0,0 +1,12 @@ +MinGW Makefiles +--------------- + +Generates makefiles for use with ``mingw32-make`` under a Windows command +prompt. + +Use this generator under a Windows command prompt with MinGW in the ``PATH`` +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..3a8744c --- /dev/null +++ b/Help/generator/NMake Makefiles JOM.rst @@ -0,0 +1,4 @@ +NMake Makefiles JOM +------------------- + +Generates JOM makefiles. 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.rst b/Help/generator/Ninja.rst new file mode 100644 index 0000000..3bbd9dc --- /dev/null +++ b/Help/generator/Ninja.rst @@ -0,0 +1,33 @@ +Ninja +----- + +Generates build.ninja files. + +A build.ninja file is generated into the build tree. Recent versions +of the ninja program can build the project through the "all" target. +An "install" target is also provided. + +For each subdirectory ``sub/dir`` of the project, additional targets +are generated: + +``sub/dir/all`` + Depends on all targets required by the subdirectory. + +``sub/dir/install`` + Runs the install step in the subdirectory, if any. + +``sub/dir/test`` + Runs the test step in the subdirectory, if any. + +``sub/dir/package`` + Runs the package step in the subdirectory, if any. + +Fortran Support +^^^^^^^^^^^^^^^ + +The ``Ninja`` generator conditionally supports Fortran when the ``ninja`` +tool has the required features. As of this version of CMake the needed +features have not been integrated into upstream Ninja. Kitware maintains +a branch of Ninja with the required features on `github.com/Kitware/ninja`_. + +.. _`github.com/Kitware/ninja`: https://github.com/Kitware/ninja/tree/features-for-fortran#readme diff --git a/Help/generator/Sublime Text 2.rst b/Help/generator/Sublime Text 2.rst new file mode 100644 index 0000000..0597a95 --- /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 PROJECT() call. Additionally Makefiles (or build.ninja +files) are generated into the build tree. The appropriate make +program can build the project through the default make target. A +"make install" target is also provided. + +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..97d74a8 --- /dev/null +++ b/Help/generator/Unix Makefiles.rst @@ -0,0 +1,8 @@ +Unix Makefiles +-------------- + +Generates standard UNIX makefiles. + +A hierarchy of UNIX makefiles is generated into the build tree. Any +standard UNIX-style make program can build the project through the +default make target. A "make install" target is also provided. diff --git a/Help/generator/VS_TOOLSET_HOST_ARCH.txt b/Help/generator/VS_TOOLSET_HOST_ARCH.txt new file mode 100644 index 0000000..5d13e77 --- /dev/null +++ b/Help/generator/VS_TOOLSET_HOST_ARCH.txt @@ -0,0 +1,6 @@ +For each toolset that comes with this version of Visual Studio, there are +variants that are themselves compiled for 32-bit (x86) and 64-bit (x64) hosts +(independent of the architecture they target). By default Visual Studio +chooses the 32-bit variant even on a 64-bit host. One may request use of the +64-bit host tools by adding a ``host=x64`` option to the toolset specification. +See the :variable:`CMAKE_GENERATOR_TOOLSET` variable for details. diff --git a/Help/generator/Visual Studio 10 2010.rst b/Help/generator/Visual Studio 10 2010.rst new file mode 100644 index 0000000..0446b8c --- /dev/null +++ b/Help/generator/Visual Studio 10 2010.rst @@ -0,0 +1,41 @@ +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 :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..8fddbb3 --- /dev/null +++ b/Help/generator/Visual Studio 11 2012.rst @@ -0,0 +1,46 @@ +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 :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..8b4c162 --- /dev/null +++ b/Help/generator/Visual Studio 12 2013.rst @@ -0,0 +1,43 @@ +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 :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. + +.. 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..917d8e5 --- /dev/null +++ b/Help/generator/Visual Studio 14 2015.rst @@ -0,0 +1,40 @@ +Visual Studio 14 2015 +--------------------- + +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 :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. + +.. include:: VS_TOOLSET_HOST_ARCH.txt diff --git a/Help/generator/Visual Studio 15 2017.rst b/Help/generator/Visual Studio 15 2017.rst new file mode 100644 index 0000000..42a3bb6 --- /dev/null +++ b/Help/generator/Visual Studio 15 2017.rst @@ -0,0 +1,57 @@ +Visual Studio 15 2017 +--------------------- + +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 +^^^^^^^^^^^^^^^^^^ + +VS 2017 supports multiple installations on the same machine. +The :variable:`CMAKE_GENERATOR_INSTANCE` variable may be set as a +cache entry containing the absolute path to a Visual Studio instance. +If the value is not specified explicitly by the user or a toolchain file, +CMake queries the Visual Studio Installer to locate VS instances, chooses +one, and sets the variable as a cache entry to hold the value persistently. + +When CMake first chooses an instance, if the ``VS150COMNTOOLS`` environment +variable is set and points to the ``Common7/Tools`` directory within +one of the instances, that instance will be used. Otherwise, if more +than one instance is installed we do not define which one is chosen +by default. + +Platform Selection +^^^^^^^^^^^^^^^^^^ + +The :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. + +.. 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..a29033f --- /dev/null +++ b/Help/generator/Visual Studio 9 2008.rst @@ -0,0 +1,30 @@ +Visual Studio 9 2008 +-------------------- + +Generates Visual Studio 9 2008 project files. + +Platform Selection +^^^^^^^^^^^^^^^^^^ + +The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps +via the :manual:`cmake(1)` ``-A`` option, to specify a target platform +name (architecture). For example: + +* ``cmake -G "Visual Studio 9 2008" -A Win32`` +* ``cmake -G "Visual Studio 9 2008" -A x64`` +* ``cmake -G "Visual Studio 9 2008" -A Itanium`` +* ``cmake -G "Visual Studio 9 2008" -A <WinCE-SDK>`` + (Specify a target platform matching a Windows CE SDK name.) + +For compatibility with CMake versions prior to 3.1, one may specify +a target platform name optionally at the end of 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..968c26a --- /dev/null +++ b/Help/generator/Xcode.rst @@ -0,0 +1,13 @@ +Xcode +----- + +Generate Xcode project files. + +This supports Xcode 3.0 and above. + +Toolset 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. 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..fe1b73c --- /dev/null +++ b/Help/index.rst @@ -0,0 +1,62 @@ +.. title:: CMake Reference Documentation + +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-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-properties.7 + /manual/cmake-qt.7 + /manual/cmake-server.7 + /manual/cmake-toolchains.7 + /manual/cmake-variables.7 + /manual/cpack-generators.7 + +.. 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/LINKS.txt b/Help/manual/LINKS.txt new file mode 100644 index 0000000..8e53c0c --- /dev/null +++ b/Help/manual/LINKS.txt @@ -0,0 +1,21 @@ +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. + +Mailing List + https://cmake.org/mailing-lists + + For help and discussion about using cmake, a mailing list is + provided at cmake@cmake.org. The list is member-post-only but one + may sign up on the CMake web page. Please first read the full + documentation at https://cmake.org before posting questions to + the list. diff --git a/Help/manual/OPTIONS_BUILD.txt b/Help/manual/OPTIONS_BUILD.txt new file mode 100644 index 0000000..baa73d5 --- /dev/null +++ b/Help/manual/OPTIONS_BUILD.txt @@ -0,0 +1,120 @@ +``-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 SET commands that use the CACHE option, not a + cache-format file. + +``-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. + +``-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. + +``-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..cc3ceec --- /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..4fc484b --- /dev/null +++ b/Help/manual/cmake-buildsystem.7.rst @@ -0,0 +1,1005 @@ +.. 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 prefixes, suffixes 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. +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 + 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: + +.. 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 ``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 diagnostic is +issued. + +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 ``Makefile`` based and ``Ninja`` generators, but is not +portable to IDE generators. Additionally, the :prop_tgt:`IMPORTED` +configuration-mappings are not accounted for with code like this, so it should +be avoided. + +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 Mac OX 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 a diagnostic in this case. + +.. _`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. + +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`` target has no :prop_tgt:`LOCATION` and is mutable, but is +otherwise similar to an :prop_tgt:`IMPORTED` target. + +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. + +A primary use-case for ``INTERFACE`` libraries is header-only libraries. + +.. code-block:: cmake + + add_library(Eigen INTERFACE) + 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. + +The properties permitted to be set on or read from an ``INTERFACE`` library +are: + +* Properties matching ``INTERFACE_*`` +* Built-in properties matching ``COMPATIBLE_INTERFACE_*`` +* ``EXPORT_NAME`` +* ``IMPORTED`` +* ``NAME`` +* Properties matching ``IMPORTED_LIBNAME_*`` +* Properties matching ``MAP_IMPORTED_CONFIG_*`` + +``INTERFACE`` libraries may be installed and exported. Any content they refer +to must be installed separately: + +.. code-block:: cmake + + add_library(Eigen INTERFACE) + 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 + ${CMAKE_CURRENT_SOURCE_DIR}/src/eigen.h + ${CMAKE_CURRENT_SOURCE_DIR}/src/vector.h + ${CMAKE_CURRENT_SOURCE_DIR}/src/matrix.h + 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..0cc5fca --- /dev/null +++ b/Help/manual/cmake-commands.7.rst @@ -0,0 +1,169 @@ +.. 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_minimum_required + /command/cmake_parse_arguments + /command/cmake_policy + /command/configure_file + /command/continue + /command/elseif + /command/else + /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_directory_properties + /command/set_property + /command/set + /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/qt_wrap_cpp + /command/qt_wrap_ui + /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_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 available only for compatibility with older +versions of CMake. Do not use them 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/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..658694a --- /dev/null +++ b/Help/manual/cmake-compile-features.7.rst @@ -0,0 +1,370 @@ +.. 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` 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` 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. The are some exceptions, such as +CMake using ``cxx_final`` and ``cxx_override`` instead of the single +``cxx_override_control`` used by Clang. + +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 +---------------------------- + +In projects that use a large number of commonly available features from +a particular language standard (e.g. C++ 11) one may specify a +meta-feature (e.g. ``cxx_std_11``) that requires use of a compiler mode +aware of that standard. This is simpler than specifying all the +features individually, but does not guarantee the existence of any +particular feature. Diagnosis of use of unsupported features will be +delayed until compile time. + +For example, if C++ 11 features are used extensively in a project's +header files, then clients must use a compiler mode aware of C++ 11 +or above. This can be requested with the code: + +.. code-block:: cmake + + target_compile_features(mylib PUBLIC cxx_std_11) + +In this example, CMake will ensure the compiler is invoked in a mode +that is aware of C++ 11 (or above), adding flags such as +``-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 though 9.2. +* ``Clang``: Clang compiler versions 2.9 through 6.0. +* ``GNU``: GNU compiler versions 4.4 through 8.0. +* ``MSVC``: Microsoft Visual Studio versions 2010 through 2017. +* ``SunPro``: Oracle SolarisStudio versions 12.4 through 12.6. +* ``Intel``: Intel compiler versions 12.1 through 17.0. + +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 through 8.0. + +CMake is currently aware of the :prop_tgt:`C++ standards <CXX_STANDARD>` and +their associated meta-features (e.g. ``cxx_std_11``) available from the +following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the +versions specified for each: + +* ``Cray``: Cray Compiler Environment version 8.1 through 8.5.8. +* ``PGI``: PGI version 12.10 through 17.5. +* ``XL``: IBM XL version 10.1 through 13.1.5. + +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++. +* ``TI``: Texas Instruments compiler. + +CMake is currently aware of the :prop_tgt:`CUDA standards <CUDA_STANDARD>` +from the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the +versions specified for each: + +* ``NVIDIA``: NVIDIA nvcc compiler 7.5 though 9.1. diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst new file mode 100644 index 0000000..f05c4b1 --- /dev/null +++ b/Help/manual/cmake-developer.7.rst @@ -0,0 +1,967 @@ +.. cmake-manual-description: CMake Developer Reference + +cmake-developer(7) +****************** + +.. only:: html + + .. contents:: + +Introduction +============ + +This manual is intended for reference by developers modifying the CMake +source tree itself, and by those authoring externally-maintained modules. + +Adding Compile Features +======================= + +CMake reports an error if a compiler whose features are known does not report +support for a particular requested feature. A compiler is considered to have +known features if it reports support for at least one feature. + +When adding a new compile feature to CMake, it is therefore necessary to list +support for the feature for all CompilerIds which already have one or more +feature supported, if the new feature is available for any version of the +compiler. + +When adding the first supported feature to a particular CompilerId, it is +necessary to list support for all features known to cmake (See +:variable:`CMAKE_C_COMPILE_FEATURES` and +:variable:`CMAKE_CXX_COMPILE_FEATURES` as appropriate), where available for +the compiler. Ensure that the ``CMAKE_<LANG>_STANDARD_DEFAULT`` is set to +the computed internal variable ``CMAKE_<LANG>_STANDARD_COMPUTED_DEFAULT`` +for compiler versions which should be supported. + +It is sensible to record the features for the most recent version of a +particular CompilerId first, and then work backwards. It is sensible to +try to create a continuous range of versions of feature releases of the +compiler. Gaps in the range indicate incorrect features recorded for +intermediate releases. + +Generally, features are made available for a particular version if the +compiler vendor documents availability of the feature with that +version. Note that sometimes partially implemented features appear to +be functional in previous releases (such as ``cxx_constexpr`` in GNU 4.6, +though availability is documented in GNU 4.7), and sometimes compiler vendors +document availability of features, though supporting infrastructure is +not available (such as ``__has_feature(cxx_generic_lambdas)`` indicating +non-availability in Clang 3.4, though it is documented as available, and +fixed in Clang 3.5). Similar cases for other compilers and versions +need to be investigated when extending CMake to support them. + +When a vendor releases a new version of a known compiler which supports +a previously unsupported feature, and there are already known features for +that compiler, the feature should be listed as supported in CMake for +that version of the compiler as soon as reasonably possible. + +Standard-specific/compiler-specific variables such +``CMAKE_CXX98_COMPILE_FEATURES`` are deliberately not documented. They +only exist for the compiler-specific implementation of adding the ``-std`` +compile flag for compilers which need that. + +Help +==== + +The ``Help`` directory contains CMake help manual source files. +They are written using the `reStructuredText`_ markup syntax and +processed by `Sphinx`_ to generate the CMake help manuals. + +.. _`reStructuredText`: http://docutils.sourceforge.net/docs/ref/rst/introduction.html +.. _`Sphinx`: http://sphinx-doc.org + +Markup Constructs +----------------- + +In addition to using Sphinx to generate the CMake help manuals, we +also use a C++-implemented document processor to print documents for +the ``--help-*`` command-line help options. It supports a subset of +reStructuredText markup. When authoring or modifying documents, +please verify that the command-line help looks good in addition to the +Sphinx-generated html and man pages. + +The command-line help processor supports the following constructs +defined by reStructuredText, Sphinx, and a CMake extension to Sphinx. + +.. + Note: This list must be kept consistent with the cmRST implementation. + +CMake Domain directives + Directives defined in the `CMake Domain`_ for defining CMake + documentation objects are printed in command-line help output as + if the lines were normal paragraph text with interpretation. + +CMake Domain interpreted text roles + Interpreted text roles defined in the `CMake Domain`_ for + cross-referencing CMake documentation objects are replaced by their + link text in command-line help output. Other roles are printed + literally and not processed. + +``code-block`` directive + Add a literal code block without interpretation. The command-line + help processor prints the block content without the leading directive + line and with common indentation replaced by one space. + +``include`` directive + Include another document source file. The command-line help + processor prints the included document inline with the referencing + document. + +literal block after ``::`` + A paragraph ending in ``::`` followed by a blank line treats + the following indented block as literal text without interpretation. + The command-line help processor prints the ``::`` literally and + prints the block content with common indentation replaced by one + space. + +``note`` directive + Call out a side note. The command-line help processor prints the + block content as if the lines were normal paragraph text with + interpretation. + +``parsed-literal`` directive + Add a literal block with markup interpretation. The command-line + help processor prints the block content without the leading + directive line and with common indentation replaced by one space. + +``productionlist`` directive + Render context-free grammar productions. The command-line help + processor prints the block content as if the lines were normal + paragraph text with interpretation. + +``replace`` directive + Define a ``|substitution|`` replacement. + The command-line help processor requires a substitution replacement + to be defined before it is referenced. + +``|substitution|`` reference + Reference a substitution replacement previously defined by + the ``replace`` directive. The command-line help processor + performs the substitution and replaces all newlines in the + replacement text with spaces. + +``toctree`` directive + Include other document sources in the Table-of-Contents + document tree. The command-line help processor prints + the referenced documents inline as part of the referencing + document. + +Inline markup constructs not listed above are printed literally in the +command-line help output. We prefer to use inline markup constructs that +look correct in source form, so avoid use of \\-escapes in favor of inline +literals when possible. + +Explicit markup blocks not matching directives listed above are removed from +command-line help output. Do not use them, except for plain ``..`` comments +that are removed by Sphinx too. + +Note that nested indentation of blocks is not recognized by the +command-line help processor. Therefore: + +* Explicit markup blocks are recognized only when not indented + inside other blocks. + +* Literal blocks after paragraphs ending in ``::`` but not + at the top indentation level may consume all indented lines + following them. + +Try to avoid these cases in practice. + +CMake Domain +------------ + +CMake adds a `Sphinx Domain`_ called ``cmake``, also called the +"CMake Domain". It defines several "object" types for CMake +documentation: + +``command`` + A CMake language command. + +``generator`` + A CMake native build system generator. + See the :manual:`cmake(1)` command-line tool's ``-G`` option. + +``manual`` + A CMake manual page, like this :manual:`cmake-developer(7)` manual. + +``module`` + A CMake module. + See the :manual:`cmake-modules(7)` manual + and the :command:`include` command. + +``policy`` + A CMake policy. + See the :manual:`cmake-policies(7)` manual + and the :command:`cmake_policy` command. + +``prop_cache, prop_dir, prop_gbl, prop_sf, prop_inst, prop_test, prop_tgt`` + A CMake cache, directory, global, source file, installed file, test, + or target property, respectively. See the :manual:`cmake-properties(7)` + manual and the :command:`set_property` command. + +``variable`` + A CMake language variable. + See the :manual:`cmake-variables(7)` manual + and the :command:`set` command. + +Documentation objects in the CMake Domain come from two sources. +First, the CMake extension to Sphinx transforms every document named +with the form ``Help/<type>/<file-name>.rst`` to a domain object with +type ``<type>``. The object name is extracted from the document title, +which is expected to be of the form:: + + <object-name> + ------------- + +and to appear at or near the top of the ``.rst`` file before any other +lines starting in a letter, digit, or ``<``. If no such title appears +literally in the ``.rst`` file, the object name is the ``<file-name>``. +If a title does appear, it is expected that ``<file-name>`` is equal +to ``<object-name>`` with any ``<`` and ``>`` characters removed. + +Second, the CMake Domain provides directives to define objects inside +other documents: + +.. code-block:: rst + + .. command:: <command-name> + + This indented block documents <command-name>. + + .. variable:: <variable-name> + + This indented block documents <variable-name>. + +Object types for which no directive is available must be defined using +the first approach above. + +.. _`Sphinx Domain`: http://sphinx-doc.org/domains.html + +Cross-References +---------------- + +Sphinx uses reStructuredText interpreted text roles to provide +cross-reference syntax. The `CMake Domain`_ provides for each +domain object type a role of the same name to cross-reference it. +CMake Domain roles are inline markup of the forms:: + + :type:`name` + :type:`text <name>` + +where ``type`` is the domain object type and ``name`` is the +domain object name. In the first form the link text will be +``name`` (or ``name()`` if the type is ``command``) and in +the second form the link text will be the explicit ``text``. +For example, the code: + +.. code-block:: rst + + * The :command:`list` command. + * The :command:`list(APPEND)` sub-command. + * The :command:`list() command <list>`. + * The :command:`list(APPEND) sub-command <list>`. + * The :variable:`CMAKE_VERSION` variable. + * The :prop_tgt:`OUTPUT_NAME_<CONFIG>` target property. + +produces: + +* The :command:`list` command. +* The :command:`list(APPEND)` sub-command. +* The :command:`list() command <list>`. +* The :command:`list(APPEND) sub-command <list>`. +* The :variable:`CMAKE_VERSION` variable. +* The :prop_tgt:`OUTPUT_NAME_<CONFIG>` target property. + +Note that CMake Domain roles differ from Sphinx and reStructuredText +convention in that the form ``a<b>``, without a space preceding ``<``, +is interpreted as a name instead of link text with an explicit target. +This is necessary because we use ``<placeholders>`` frequently in +object names like ``OUTPUT_NAME_<CONFIG>``. The form ``a <b>``, +with a space preceding ``<``, is still interpreted as a link text +with an explicit target. + +Style +----- + +Style: Section Headers +^^^^^^^^^^^^^^^^^^^^^^ + +When marking section titles, make the section decoration line as long as +the title text. Use only a line below the title, not above. For +example: + +.. code-block:: rst + + Title Text + ---------- + +Capitalize the first letter of each non-minor word in the title. + +The section header underline character hierarchy is + +* ``#``: Manual group (part) in the master document +* ``*``: Manual (chapter) title +* ``=``: Section within a manual +* ``-``: Subsection or `CMake Domain`_ object document title +* ``^``: Subsubsection or `CMake Domain`_ object document section +* ``"``: Paragraph or `CMake Domain`_ object document subsection + +Style: Whitespace +^^^^^^^^^^^^^^^^^ + +Use two spaces for indentation. Use two spaces between sentences in +prose. + +Style: Line Length +^^^^^^^^^^^^^^^^^^ + +Prefer to restrict the width of lines to 75-80 columns. This is not a +hard restriction, but writing new paragraphs wrapped at 75 columns +allows space for adding minor content without significant re-wrapping of +content. + +Style: Prose +^^^^^^^^^^^^ + +Use American English spellings in prose. + +Style: Starting Literal Blocks +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Prefer to mark the start of literal blocks with ``::`` at the end of +the preceding paragraph. In cases where the following block gets +a ``code-block`` marker, put a single ``:`` at the end of the preceding +paragraph. + +Style: CMake Command Signatures +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Command signatures should be marked up as plain literal blocks, not as +cmake ``code-blocks``. + +Signatures are separated from preceding content by a section header. +That is, use: + +.. code-block:: rst + + ... preceding paragraph. + + Normal Libraries + ^^^^^^^^^^^^^^^^ + + :: + + add_library(<lib> ...) + + This signature is used for ... + +Signatures of commands should wrap optional parts with square brackets, +and should mark list of optional arguments with an ellipsis (``...``). +Elements of the signature which are specified by the user should be +specified with angle brackets, and may be referred to in prose using +``inline-literal`` syntax. + +Style: Boolean Constants +^^^^^^^^^^^^^^^^^^^^^^^^ + +Use "``OFF``" and "``ON``" for boolean values which can be modified by +the user, such as :prop_tgt:`POSITION_INDEPENDENT_CODE`. Such properties +may be "enabled" and "disabled". Use "``True``" and "``False``" for +inherent values which can't be modified after being set, such as the +:prop_tgt:`IMPORTED` property of a build target. + +Style: Inline Literals +^^^^^^^^^^^^^^^^^^^^^^ + +Mark up references to keywords in signatures, file names, and other +technical terms with ``inline-literal`` syntax, for example: + +.. code-block:: rst + + If ``WIN32`` is used with :command:`add_executable`, the + :prop_tgt:`WIN32_EXECUTABLE` target property is enabled. That command + creates the file ``<name>.exe`` on Windows. + +Style: Cross-References +^^^^^^^^^^^^^^^^^^^^^^^ + +Mark up linkable references as links, including repeats. +An alternative, which is used by wikipedia +(`<http://en.wikipedia.org/wiki/WP:REPEATLINK>`_), +is to link to a reference only once per article. That style is not used +in CMake documentation. + +Style: Referencing CMake Concepts +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If referring to a concept which corresponds to a property, and that +concept is described in a high-level manual, prefer to link to the +manual section instead of the property. For example: + +.. code-block:: rst + + This command creates an :ref:`Imported Target <Imported Targets>`. + +instead of: + +.. code-block:: rst + + This command creates an :prop_tgt:`IMPORTED` target. + +The latter should be used only when referring specifically to the +property. + +References to manual sections are not automatically created by creating +a section, but code such as: + +.. code-block:: rst + + .. _`Imported Targets`: + +creates a suitable anchor. Use an anchor name which matches the name +of the corresponding section. Refer to the anchor using a +cross-reference with specified text. + +Imported Targets need the ``IMPORTED`` term marked up with care in +particular because the term may refer to a command keyword +(``IMPORTED``), a target property (:prop_tgt:`IMPORTED`), or a +concept (:ref:`Imported Targets`). + +Where a property, command or variable is related conceptually to others, +by for example, being related to the buildsystem description, generator +expressions or Qt, each relevant property, command or variable should +link to the primary manual, which provides high-level information. Only +particular information relating to the command should be in the +documentation of the command. + +Style: Referencing CMake Domain Objects +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When referring to `CMake Domain`_ objects such as properties, variables, +commands etc, prefer to link to the target object and follow that with +the type of object it is. For example: + +.. code-block:: rst + + Set the :prop_tgt:`AUTOMOC` target property to ``ON``. + +Instead of + +.. code-block:: rst + + Set the target property :prop_tgt:`AUTOMOC` to ``ON``. + +The ``policy`` directive is an exception, and the type us usually +referred to before the link: + +.. code-block:: rst + + If policy :prop_tgt:`CMP0022` is set to ``NEW`` the behavior is ... + +However, markup self-references with ``inline-literal`` syntax. +For example, within the :command:`add_executable` command +documentation, use + +.. code-block:: rst + + ``add_executable`` + +not + +.. code-block:: rst + + :command:`add_executable` + +which is used elsewhere. + +Modules +======= + +The ``Modules`` directory contains CMake-language ``.cmake`` module files. + +Module Documentation +-------------------- + +To document CMake module ``Modules/<module-name>.cmake``, modify +``Help/manual/cmake-modules.7.rst`` to reference the module in the +``toctree`` directive, in sorted order, as:: + + /module/<module-name> + +Then add the module document file ``Help/module/<module-name>.rst`` +containing just the line:: + + .. cmake-module:: ../../Modules/<module-name>.cmake + +The ``cmake-module`` directive will scan the module file to extract +reStructuredText markup from comment blocks that start in ``.rst:``. +At the top of ``Modules/<module-name>.cmake``, begin with the following +license notice: + +.. code-block:: cmake + + # Distributed under the OSI-approved BSD 3-Clause License. See accompanying + # file Copyright.txt or https://cmake.org/licensing for details. + +After this notice, add a *BLANK* line. Then, add documentation using +a :ref:`Line Comment` block of the form: + +.. code-block:: cmake + + #.rst: + # <module-name> + # ------------- + # + # <reStructuredText documentation of module> + +or a :ref:`Bracket Comment` of the form: + +:: + + #[[.rst: + <module-name> + ------------- + + <reStructuredText documentation of module> + #]] + +Any number of ``=`` may be used in the opening and closing brackets +as long as they match. Content on the line containing the closing +bracket is excluded if and only if the line starts in ``#``. + +Additional such ``.rst:`` comments may appear anywhere in the module file. +All such comments must start with ``#`` in the first column. + +For example, a ``Modules/Findxxx.cmake`` module may contain: + +:: + + # Distributed under the OSI-approved BSD 3-Clause License. See accompanying + # file Copyright.txt or https://cmake.org/licensing for details. + + #.rst: + # FindXxx + # ------- + # + # This is a cool module. + # This module does really cool stuff. + # It can do even more than you think. + # + # It even needs two paragraphs to tell you about it. + # And it defines the following variables: + # + # * VAR_COOL: this is great isn't it? + # * VAR_REALLY_COOL: cool right? + + <code> + + #[========================================[.rst: + .. command:: xxx_do_something + + This command does something for Xxx:: + + xxx_do_something(some arguments) + #]========================================] + macro(xxx_do_something) + <code> + endmacro() + +Test the documentation formatting by running +``cmake --help-module <module-name>``, and also by enabling the +``SPHINX_HTML`` and ``SPHINX_MAN`` options to build the documentation. +Edit the comments until generated documentation looks satisfactory. To +have a .cmake file in this directory NOT show up in the modules +documentation, simply leave out the ``Help/module/<module-name>.rst`` +file and the ``Help/manual/cmake-modules.7.rst`` toctree entry. + +.. _`Find Modules`: + +Find Modules +------------ + +A "find module" is a ``Modules/Find<PackageName>.cmake`` file to be loaded +by the :command:`find_package` command when invoked for ``<PackageName>``. + +The primary task of a find module is to determine whether a package +exists on the system, set the ``<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. + +Like all modules, find modules should be properly documented. To add a +module to the CMake documentation, follow the steps in the `Module +Documentation`_ section above. + + + +.. _`CMake Developer Standard Variable Names`: + +Standard Variable Names +^^^^^^^^^^^^^^^^^^^^^^^ + +For a ``FindXxx.cmake`` module that takes the approach of setting +variables (either instead of or in addition to creating imported +targets), the following variable names should be used to keep things +consistent between find modules. Note that all variables start with +``Xxx_`` to make sure they do not interfere with other find modules; the +same consideration applies to macros, functions and imported targets. + +``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. + +``Xxx_LIBRARIES`` + The libraries to link against to use Xxx. These should include full + paths. This should not be a cache entry. + +``Xxx_DEFINITIONS`` + Definitions to use when compiling code that uses Xxx. 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`` + Where to find the Xxx tool. + +``Xxx_Yyy_EXECUTABLE`` + Where to find the Yyy tool that comes with Xxx. + +``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 Xxx. + +``Xxx_VERSION_Yy`` + Expect Version Yy if true. Make sure at most one of these is ever true. + +``Xxx_WRAP_Yy`` + If False, do not try to use the relevant CMake wrapping command. + +``Xxx_Yy_FOUND`` + If False, optional Yy part of Xxx system is not available. + +``Xxx_FOUND`` + Set to false, or undefined, if we haven't found, or don't want to use + Xxx. + +``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 + ``find_package_handle_standard_args()`` to inform the user about the + problem. + +``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, but +are typically cache variables for users to edit and control the +behaviour of find modules (like entering the path to a library manually) + +``Xxx_LIBRARY`` + The path of the Xxx library (as used with :command:`find_library`, for + example). + +``Xxx_Yy_LIBRARY`` + The path of the Yy library that is part of the Xxx system. It may or + may not be required to use Xxx. + +``Xxx_INCLUDE_DIR`` + Where to find headers for using the Xxx library. + +``Xxx_Yy_INCLUDE_DIR`` + Where to find headers for using the Yy library of the Xxx system. + +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``. + +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 first thing that is needed is a license notice. + +.. code-block:: cmake + + # Distributed under the OSI-approved BSD 3-Clause License. See accompanying + # file Copyright.txt or https://cmake.org/licensing for details. + +Next we need module documentation. CMake's documentation system requires you +to follow the license notice with a blank line and then with a documentation +marker and the name of the module. You should follow this with a simple +statement of what the module does. + +.. code-block:: cmake + + #.rst: + # FindFoo + # ------- + # + # Finds the Foo library + # + +More description may be required for some packages. If there are +caveats or other details users of the module should be aware of, you can +add further paragraphs below this. Then you need to document what +variables and imported targets are set by the module, such as + +.. code-block:: cmake + + # This will define the following variables:: + # + # Foo_FOUND - True if the system has the Foo library + # Foo_VERSION - The version of the Foo library which was found + # + # and the following imported targets:: + # + # Foo::Foo - The Foo library + +If the package provides any macros, they should be listed here, but can +be documented where they are defined. See the `Module +Documentation`_ section above for more details. + +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} + ) + +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..42aeabc --- /dev/null +++ b/Help/manual/cmake-env-variables.7.rst @@ -0,0 +1,57 @@ +.. cmake-manual-description: CMake Environment Variables Reference + +cmake-env-variables(7) +********************** + +.. only:: html + + .. contents:: + +Environment Variables that Control the Build +============================================ + +.. toctree:: + :maxdepth: 1 + + /envvar/CMAKE_BUILD_PARALLEL_LEVEL + /envvar/CMAKE_CONFIG_TYPE + /envvar/CMAKE_MSVCIDE_RUN_PATH + /envvar/CMAKE_OSX_ARCHITECTURES + /envvar/DESTDIR + /envvar/LDFLAGS + /envvar/MACOSX_DEPLOYMENT_TARGET + /envvar/PackageName_ROOT + +Environment Variables for Languages +=================================== + +.. toctree:: + :maxdepth: 1 + + /envvar/ASM_DIALECT + /envvar/ASM_DIALECTFLAGS + /envvar/CC + /envvar/CFLAGS + /envvar/CSFLAGS + /envvar/CUDACXX + /envvar/CUDAFLAGS + /envvar/CUDAHOSTCXX + /envvar/CXX + /envvar/CXXFLAGS + /envvar/FC + /envvar/FFLAGS + /envvar/RC + /envvar/RCFLAGS + +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_USE_LAUNCHERS_DEFAULT + /envvar/DASHBOARD_TEST_FROM_CTEST diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst new file mode 100644 index 0000000..76fd3d9 --- /dev/null +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -0,0 +1,351 @@ +.. 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. + +This means that they enable conditional linking, conditional +definitions used when compiling, and conditional include directories and +more. The conditions may be based on the build configuration, target +properties, platform information or any other queryable information. + +Logical Expressions +=================== + +Logical expressions are used to create conditional output. The basic +expressions are the ``0`` and ``1`` expressions. Because other logical +expressions evaluate to either ``0`` or ``1``, they can be composed to +create conditional output:: + + $<$<CONFIG:Debug>:DEBUG_MODE> + +expands to ``DEBUG_MODE`` when the ``Debug`` configuration is used, and +otherwise expands to nothing. + +Available logical expressions are: + +``$<BOOL:...>`` + ``1`` if the ``...`` is true, else ``0`` +``$<AND:?[,?]...>`` + ``1`` if all ``?`` are ``1``, else ``0`` + + The ``?`` must always be either ``0`` or ``1`` in boolean expressions. + +``$<OR:?[,?]...>`` + ``0`` if all ``?`` are ``0``, else ``1`` +``$<NOT:?>`` + ``0`` if ``?`` is ``1``, else ``1`` +``$<IF:?,true-value...,false-value...>`` + ``true-value...`` if ``?`` is ``1``, ``false-value...`` if ``?`` is ``0`` +``$<STREQUAL:a,b>`` + ``1`` if ``a`` is STREQUAL ``b``, else ``0`` +``$<EQUAL:a,b>`` + ``1`` if ``a`` is EQUAL ``b`` in a numeric comparison, else ``0`` +``$<IN_LIST:a,b>`` + ``1`` if ``a`` is IN_LIST ``b``, else ``0`` +``$<TARGET_EXISTS:tgt>`` + ``1`` if ``tgt`` is an existed target name, else ``0``. +``$<CONFIG:cfg>`` + ``1`` if config is ``cfg``, else ``0``. This is a case-insensitive comparison. + The mapping in :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` is also considered by + this expression when it is evaluated on a property on an :prop_tgt:`IMPORTED` + target. +``$<PLATFORM_ID:comp>`` + ``1`` if the CMake-id of the platform matches ``comp``, otherwise ``0``. + See also the :variable:`CMAKE_SYSTEM_NAME` variable. +``$<C_COMPILER_ID:comp>`` + ``1`` if the CMake-id of the C compiler matches ``comp``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<CXX_COMPILER_ID:comp>`` + ``1`` if the CMake-id of the CXX compiler matches ``comp``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<VERSION_LESS:v1,v2>`` + ``1`` if ``v1`` is a version less than ``v2``, else ``0``. +``$<VERSION_GREATER:v1,v2>`` + ``1`` if ``v1`` is a version greater than ``v2``, else ``0``. +``$<VERSION_EQUAL:v1,v2>`` + ``1`` if ``v1`` is the same version as ``v2``, else ``0``. +``$<VERSION_LESS_EQUAL:v1,v2>`` + ``1`` if ``v1`` is a version less than or equal to ``v2``, else ``0``. +``$<VERSION_GREATER_EQUAL:v1,v2>`` + ``1`` if ``v1`` is a version greater than or equal to ``v2``, else ``0``. +``$<C_COMPILER_VERSION:ver>`` + ``1`` if the version of the C compiler matches ``ver``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<CXX_COMPILER_VERSION:ver>`` + ``1`` if the version of the CXX compiler matches ``ver``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<TARGET_POLICY:pol>`` + ``1`` if the policy ``pol`` was NEW when the 'head' target was created, + else ``0``. If the policy was not set, the warning message for the policy + will be emitted. This generator expression only works for a subset of + policies. +``$<COMPILE_FEATURES:feature[,feature]...>`` + ``1`` if all of the ``feature`` features are available for the 'head' + target, and ``0`` otherwise. If this expression is used while evaluating + the link implementation of a target and if any dependency transitively + increases the required :prop_tgt:`C_STANDARD` or :prop_tgt:`CXX_STANDARD` + for the 'head' target, an error is reported. See the + :manual:`cmake-compile-features(7)` manual for information on + compile features and a list of supported compilers. +``$<COMPILE_LANGUAGE:lang>`` + ``1`` when the language used for compilation unit matches ``lang``, + otherwise ``0``. This expression 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>:/opt/foo/cxx_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) + +Informational Expressions +========================= + +These expressions expand to some information. The information may be used +directly, eg:: + + include_directories(/usr/include/$<CXX_COMPILER_ID>/) + +expands to ``/usr/include/GNU/`` or ``/usr/include/Clang/`` etc, depending on +the Id of the compiler. + +These expressions may also may be combined with logical expressions:: + + $<$<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. + +Available informational expressions are: + +``$<CONFIGURATION>`` + Configuration name. Deprecated. Use ``CONFIG`` instead. +``$<CONFIG>`` + Configuration name +``$<PLATFORM_ID>`` + The CMake-id of the platform. + See also the :variable:`CMAKE_SYSTEM_NAME` variable. +``$<C_COMPILER_ID>`` + The CMake-id of the C compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<CXX_COMPILER_ID>`` + The CMake-id of the CXX compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<C_COMPILER_VERSION>`` + The version of the C compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<CXX_COMPILER_VERSION>`` + The version of the CXX compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<TARGET_FILE:tgt>`` + Full path to main file (.exe, .so.1.2, .a) where ``tgt`` is the name of a target. +``$<TARGET_FILE_NAME:tgt>`` + Name of main file (.exe, .so.1.2, .a). +``$<TARGET_FILE_DIR:tgt>`` + Directory of main file (.exe, .so.1.2, .a). +``$<TARGET_LINKER_FILE:tgt>`` + File used to link (.a, .lib, .so) where ``tgt`` is the name of a target. +``$<TARGET_LINKER_FILE_NAME:tgt>`` + Name of file used to link (.a, .lib, .so). +``$<TARGET_LINKER_FILE_DIR:tgt>`` + Directory of file used to link (.a, .lib, .so). +``$<TARGET_SONAME_FILE:tgt>`` + File with soname (.so.3) where ``tgt`` is the name of a target. +``$<TARGET_SONAME_FILE_NAME:tgt>`` + Name of file with soname (.so.3). +``$<TARGET_SONAME_FILE_DIR:tgt>`` + Directory of with soname (.so.3). +``$<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>`. +``$<TARGET_PDB_FILE_NAME:tgt>`` + Name of the linker generated program database file (.pdb). +``$<TARGET_PDB_FILE_DIR:tgt>`` + Directory of the linker generated program database file (.pdb). +``$<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. +``$<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. +``$<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. +``$<TARGET_PROPERTY:prop>`` + Value of the property ``prop`` on the target on which the generator + expression is evaluated. +``$<INSTALL_PREFIX>`` + Content of the install prefix when the target is exported via + :command:`install(EXPORT)` and empty otherwise. +``$<COMPILE_LANGUAGE>`` + The compile language of source files when evaluating compile options. See + the unary version for notes about portability of this generator + expression. + +Output Expressions +================== + +These expressions generate output, in some cases depending on an input. These +expressions may be combined with other expressions for information or logical +comparison:: + + -I$<JOIN:$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>, -I> + +generates a string of the entries in the :prop_tgt:`INCLUDE_DIRECTORIES` target +property with each entry preceded by ``-I``. Note that a more-complete use +in this situation would require first checking if the INCLUDE_DIRECTORIES +property is non-empty:: + + $<$<BOOL:${prop}>:-I$<JOIN:${prop}, -I>> + +where ``${prop}`` refers to a helper variable:: + + set(prop "$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>") + +Available output expressions are: + +``$<0:...>`` + Empty string (ignores ``...``) +``$<1:...>`` + Content of ``...`` +``$<JOIN:list,...>`` + Joins the list with the content of ``...`` +``$<ANGLE-R>`` + A literal ``>``. Used to compare strings which contain a ``>`` for example. +``$<COMMA>`` + A literal ``,``. Used to compare strings which contain a ``,`` for example. +``$<SEMICOLON>`` + A literal ``;``. Used to prevent list expansion on an argument with ``;``. +``$<TARGET_NAME:...>`` + Marks ``...`` as being the name of a target. This is required if exporting + targets to multiple dependent export sets. The ``...`` must be a literal + name of a target- it may not contain generator expressions. +``$<TARGET_NAME_IF_EXISTS:...>`` + Expands to the ``...`` if the given target exists, an empty string + otherwise. +``$<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. +``$<INSTALL_INTERFACE:...>`` + Content of ``...`` when the property is exported using :command:`install(EXPORT)`, + and empty otherwise. +``$<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. +``$<LOWER_CASE:...>`` + Content of ``...`` converted to lower case. +``$<UPPER_CASE:...>`` + Content of ``...`` converted to upper case. +``$<MAKE_C_IDENTIFIER:...>`` + Content of ``...`` converted to a C identifier. The conversion follows the + same behavior as :command:`string(MAKE_C_IDENTIFIER)`. +``$<TARGET_OBJECTS:objLib>`` + List of objects resulting from build of ``objLib``. ``objLib`` must be an + object of type ``OBJECT_LIBRARY``. +``$<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. +``$<GENEX_EVAL:...>`` + Content of ``...`` evaluated as a generator expression in the current + context. This enables consumption of generator expressions + whose evaluation results itself in generator expressions. +``$<TARGET_GENEX_EVAL:tgt,...>`` + Content of ``...`` 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>> + ) diff --git a/Help/manual/cmake-generators.7.rst b/Help/manual/cmake-generators.7.rst new file mode 100644 index 0000000..0287767 --- /dev/null +++ b/Help/manual/cmake-generators.7.rst @@ -0,0 +1,112 @@ +.. 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 +---------------------------------- + +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 Generator +^^^^^^^^^^^^^^^ + +.. toctree:: + :maxdepth: 1 + + /generator/Ninja + +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 + +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..57a9850 --- /dev/null +++ b/Help/manual/cmake-gui.1.rst @@ -0,0 +1,35 @@ +.. 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>} + +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 +======= + +.. 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..591f73d --- /dev/null +++ b/Help/manual/cmake-language.7.rst @@ -0,0 +1,587 @@ +.. 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. + +For example: + +.. code-block:: cmake + + 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. + +For example: + +:: + + 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. + ") + +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_name}`` 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.) + +The `Variables`_ section documents the scope of variable names +and how their values are set. + +An *environment variable reference* has the form ``$ENV{VAR}`` and +is evaluated in the same contexts as a normal variable reference. +See :variable:`ENV` for more information. + +A *cache variable reference* has the form ``$CACHE{VAR}`` and +is evaluated in the same contexts as a normal variable reference. +See :variable:`CACHE` for more information. + +Comments +-------- + +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 `Bracket Argument`_ 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 `Bracket Argument`_ 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_argument` + : 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 many variables +that are provided by CMake or have meaning to CMake when set +by project code. + +.. _`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..b7276b6 --- /dev/null +++ b/Help/manual/cmake-modules.7.rst @@ -0,0 +1,276 @@ +.. cmake-manual-description: CMake Modules Reference + +cmake-modules(7) +**************** + +.. only:: html + + .. contents:: + +All Modules +=========== + +.. toctree:: + :maxdepth: 1 + + /module/AddFileDependencies + /module/AndroidTestUtilities + /module/BundleUtilities + /module/CheckCCompilerFlag + /module/CheckCSourceCompiles + /module/CheckCSourceRuns + /module/CheckCXXCompilerFlag + /module/CheckCXXSourceCompiles + /module/CheckCXXSourceRuns + /module/CheckCXXSymbolExists + /module/CheckFortranCompilerFlag + /module/CheckFortranFunctionExists + /module/CheckFortranSourceCompiles + /module/CheckFunctionExists + /module/CheckIPOSupported + /module/CheckIncludeFileCXX + /module/CheckIncludeFile + /module/CheckIncludeFiles + /module/CheckLanguage + /module/CheckLibraryExists + /module/CheckPrototypeDefinition + /module/CheckStructHasMember + /module/CheckSymbolExists + /module/CheckTypeSize + /module/CheckVariableExists + /module/CMakeAddFortranSubdirectory + /module/CMakeBackwardCompatibilityCXX + /module/CMakeDependentOption + /module/CMakeDetermineVSServicePack + /module/CMakeExpandImportedTargets + /module/CMakeFindDependencyMacro + /module/CMakeFindFrameworks + /module/CMakeFindPackageMode + /module/CMakeForceCompiler + /module/CMakeGraphVizOptions + /module/CMakePackageConfigHelpers + /module/CMakeParseArguments + /module/CMakePrintHelpers + /module/CMakePrintSystemInformation + /module/CMakePushCheckState + /module/CMakeVerifyManifest + /module/CPackComponent + /module/CPackIFW + /module/CPackIFWConfigureFile + /module/CPack + /module/CSharpUtilities + /module/CTest + /module/CTestCoverageCollectGCOV + /module/CTestScriptMode + /module/CTestUseLaunchers + /module/Dart + /module/DeployQt4 + /module/Documentation + /module/ExternalData + /module/ExternalProject + /module/FeatureSummary + /module/FetchContent + /module/FindALSA + /module/FindArmadillo + /module/FindASPELL + /module/FindAVIFile + /module/FindBISON + /module/FindBLAS + /module/FindBacktrace + /module/FindBoost + /module/FindBullet + /module/FindBZip2 + /module/FindCABLE + /module/FindCoin3D + /module/FindCUDA + /module/FindCups + /module/FindCURL + /module/FindCurses + /module/FindCVS + /module/FindCxxTest + /module/FindCygwin + /module/FindDart + /module/FindDCMTK + /module/FindDevIL + /module/FindDoxygen + /module/FindEXPAT + /module/FindFLEX + /module/FindFLTK2 + /module/FindFLTK + /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/FindGTK2 + /module/FindGTK + /module/FindHDF5 + /module/FindHg + /module/FindHSPELL + /module/FindHTMLHelp + /module/FindIce + /module/FindIcotool + /module/FindICU + /module/FindImageMagick + /module/FindIconv + /module/FindIntl + /module/FindITK + /module/FindJasper + /module/FindJava + /module/FindJNI + /module/FindJPEG + /module/FindKDE3 + /module/FindKDE4 + /module/FindLAPACK + /module/FindLATEX + /module/FindLibArchive + /module/FindLibLZMA + /module/FindLibXml2 + /module/FindLibXslt + /module/FindLTTngUST + /module/FindLua50 + /module/FindLua51 + /module/FindLua + /module/FindMatlab + /module/FindMFC + /module/FindMotif + /module/FindMPEG2 + /module/FindMPEG + /module/FindMPI + /module/FindODBC + /module/FindOpenACC + /module/FindOpenAL + /module/FindOpenCL + /module/FindOpenGL + /module/FindOpenMP + /module/FindOpenSceneGraph + /module/FindOpenSSL + /module/FindOpenThreads + /module/FindosgAnimation + /module/FindosgDB + /module/Findosg_functions + /module/FindosgFX + /module/FindosgGA + /module/FindosgIntrospection + /module/FindosgManipulator + /module/FindosgParticle + /module/FindosgPresentation + /module/FindosgProducer + /module/FindosgQt + /module/Findosg + /module/FindosgShadow + /module/FindosgSim + /module/FindosgTerrain + /module/FindosgText + /module/FindosgUtil + /module/FindosgViewer + /module/FindosgVolume + /module/FindosgWidget + /module/FindPackageHandleStandardArgs + /module/FindPackageMessage + /module/FindPatch + /module/FindPerlLibs + /module/FindPerl + /module/FindPHP4 + /module/FindPhysFS + /module/FindPike + /module/FindPkgConfig + /module/FindPNG + /module/FindPostgreSQL + /module/FindProducer + /module/FindProtobuf + /module/FindPython + /module/FindPython2 + /module/FindPython3 + /module/FindPythonInterp + /module/FindPythonLibs + /module/FindQt3 + /module/FindQt4 + /module/FindQt + /module/FindQuickTime + /module/FindRTI + /module/FindRuby + /module/FindSDL_image + /module/FindSDL_mixer + /module/FindSDL_net + /module/FindSDL + /module/FindSDL_sound + /module/FindSDL_ttf + /module/FindSelfPackers + /module/FindSquish + /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/FindwxWindows + /module/FindXCTest + /module/FindXalanC + /module/FindXercesC + /module/FindX11 + /module/FindXMLRPC + /module/FindZLIB + /module/FortranCInterface + /module/GenerateExportHeader + /module/GetPrerequisites + /module/GNUInstallDirs + /module/GoogleTest + /module/InstallRequiredSystemLibraries + /module/MacroAddFileDependencies + /module/ProcessorCount + /module/SelectLibraryConfigurations + /module/SquishTestScript + /module/TestBigEndian + /module/TestCXXAcceptsFlag + /module/TestForANSIForScope + /module/TestForANSIStreamHeaders + /module/TestForSSTREAM + /module/TestForSTDNamespace + /module/UseEcos + /module/UseJavaClassFilelist + /module/UseJava + /module/UseJavaSymlinks + /module/UsePkgConfig + /module/UseSWIG + /module/UsewxWidgets + /module/Use_wxWindows + /module/WriteBasicConfigVersionFile + /module/WriteCompilerDetectionHeader + +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..876ca84 --- /dev/null +++ b/Help/manual/cmake-packages.7.rst @@ -0,0 +1,709 @@ +.. 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 ``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: + + * :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` disables the + :command:`export(PACKAGE)` command. + * :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` disables the + User Package Registry in all the :command:`find_package` calls. + * :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` disables + the System Package Registry in all the :command:`find_package` calls. + +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..2cc52fe --- /dev/null +++ b/Help/manual/cmake-policies.7.rst @@ -0,0 +1,232 @@ +.. 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.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-properties.7.rst b/Help/manual/cmake-properties.7.rst new file mode 100644 index 0000000..5c3eb81 --- /dev/null +++ b/Help/manual/cmake-properties.7.rst @@ -0,0 +1,508 @@ +.. 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/CMAKE_C_KNOWN_FEATURES + /prop_gbl/CMAKE_CXX_KNOWN_FEATURES + /prop_gbl/DEBUG_CONFIGURATIONS + /prop_gbl/DISABLED_FEATURES + /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/PACKAGES_FOUND + /prop_gbl/PACKAGES_NOT_FOUND + /prop_gbl/JOB_POOLS + /prop_gbl/PREDEFINED_TARGETS_FOLDER + /prop_gbl/ECLIPSE_EXTRA_NATURES + /prop_gbl/ECLIPSE_EXTRA_CPROJECT_CONTENTS + /prop_gbl/REPORT_UNDEFINED_PROPERTIES + /prop_gbl/RULE_LAUNCH_COMPILE + /prop_gbl/RULE_LAUNCH_CUSTOM + /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_MAKE_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_CONFIG + /prop_dir/INTERPROCEDURAL_OPTIMIZATION + /prop_dir/LABELS + /prop_dir/LINK_DIRECTORIES + /prop_dir/LINK_OPTIONS + /prop_dir/LISTFILE_STACK + /prop_dir/MACROS + /prop_dir/PARENT_DIRECTORY + /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/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_CONFIG + /prop_tgt/ARCHIVE_OUTPUT_DIRECTORY + /prop_tgt/ARCHIVE_OUTPUT_NAME_CONFIG + /prop_tgt/ARCHIVE_OUTPUT_NAME + /prop_tgt/AUTOGEN_BUILD_DIR + /prop_tgt/AUTOGEN_PARALLEL + /prop_tgt/AUTOGEN_TARGET_DEPENDS + /prop_tgt/AUTOMOC_COMPILER_PREDEFINES + /prop_tgt/AUTOMOC_DEPEND_FILTERS + /prop_tgt/AUTOMOC_MACRO_NAMES + /prop_tgt/AUTOMOC_MOC_OPTIONS + /prop_tgt/AUTOMOC + /prop_tgt/AUTOUIC + /prop_tgt/AUTOUIC_OPTIONS + /prop_tgt/AUTOUIC_SEARCH_PATHS + /prop_tgt/AUTORCC + /prop_tgt/AUTORCC_OPTIONS + /prop_tgt/BINARY_DIR + /prop_tgt/BUILD_RPATH + /prop_tgt/BUILD_WITH_INSTALL_NAME_DIR + /prop_tgt/BUILD_WITH_INSTALL_RPATH + /prop_tgt/BUNDLE_EXTENSION + /prop_tgt/BUNDLE + /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_PTX_COMPILATION + /prop_tgt/CUDA_SEPARABLE_COMPILATION + /prop_tgt/CUDA_RESOLVE_DEVICE_SYMBOLS + /prop_tgt/CUDA_EXTENSIONS + /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_REMOTE_DIRECTORY + /prop_tgt/DEPLOYMENT_ADDITIONAL_FILES + /prop_tgt/DOTNET_TARGET_FRAMEWORK_VERSION + /prop_tgt/EchoString + /prop_tgt/ENABLE_EXPORTS + /prop_tgt/EXCLUDE_FROM_ALL + /prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD_CONFIG + /prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD + /prop_tgt/EXPORT_NAME + /prop_tgt/EXPORT_PROPERTIES + /prop_tgt/FOLDER + /prop_tgt/Fortran_FORMAT + /prop_tgt/Fortran_MODULE_DIRECTORY + /prop_tgt/FRAMEWORK + /prop_tgt/FRAMEWORK_VERSION + /prop_tgt/GENERATOR_FILE_NAME + /prop_tgt/GNUtoMS + /prop_tgt/HAS_CXX + /prop_tgt/IMPLICIT_DEPENDS_INCLUDE_TRANSFORM + /prop_tgt/IMPORTED_COMMON_LANGUAGE_RUNTIME + /prop_tgt/IMPORTED_CONFIGURATIONS + /prop_tgt/IMPORTED_GLOBAL + /prop_tgt/IMPORTED_IMPLIB_CONFIG + /prop_tgt/IMPORTED_IMPLIB + /prop_tgt/IMPORTED_LIBNAME_CONFIG + /prop_tgt/IMPORTED_LIBNAME + /prop_tgt/IMPORTED_LINK_DEPENDENT_LIBRARIES_CONFIG + /prop_tgt/IMPORTED_LINK_DEPENDENT_LIBRARIES_CONFIG + /prop_tgt/IMPORTED_LINK_DEPENDENT_LIBRARIES + /prop_tgt/IMPORTED_LINK_INTERFACE_LANGUAGES_CONFIG + /prop_tgt/IMPORTED_LINK_INTERFACE_LANGUAGES + /prop_tgt/IMPORTED_LINK_INTERFACE_LIBRARIES_CONFIG + /prop_tgt/IMPORTED_LINK_INTERFACE_LIBRARIES + /prop_tgt/IMPORTED_LINK_INTERFACE_MULTIPLICITY_CONFIG + /prop_tgt/IMPORTED_LINK_INTERFACE_MULTIPLICITY + /prop_tgt/IMPORTED_LOCATION_CONFIG + /prop_tgt/IMPORTED_LOCATION + /prop_tgt/IMPORTED_NO_SONAME_CONFIG + /prop_tgt/IMPORTED_NO_SONAME + /prop_tgt/IMPORTED_OBJECTS_CONFIG + /prop_tgt/IMPORTED_OBJECTS + /prop_tgt/IMPORTED + /prop_tgt/IMPORTED_SONAME_CONFIG + /prop_tgt/IMPORTED_SONAME + /prop_tgt/IMPORT_PREFIX + /prop_tgt/IMPORT_SUFFIX + /prop_tgt/INCLUDE_DIRECTORIES + /prop_tgt/INSTALL_NAME_DIR + /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_SOURCES + /prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES + /prop_tgt/INTERPROCEDURAL_OPTIMIZATION_CONFIG + /prop_tgt/INTERPROCEDURAL_OPTIMIZATION + /prop_tgt/IOS_INSTALL_COMBINED + /prop_tgt/JOB_POOL_COMPILE + /prop_tgt/JOB_POOL_LINK + /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_CONFIG + /prop_tgt/LIBRARY_OUTPUT_DIRECTORY + /prop_tgt/LIBRARY_OUTPUT_NAME_CONFIG + /prop_tgt/LIBRARY_OUTPUT_NAME + /prop_tgt/LINK_DEPENDS_NO_SHARED + /prop_tgt/LINK_DEPENDS + /prop_tgt/LINKER_LANGUAGE + /prop_tgt/LINK_DIRECTORIES + /prop_tgt/LINK_FLAGS_CONFIG + /prop_tgt/LINK_FLAGS + /prop_tgt/LINK_INTERFACE_LIBRARIES_CONFIG + /prop_tgt/LINK_INTERFACE_LIBRARIES + /prop_tgt/LINK_INTERFACE_MULTIPLICITY_CONFIG + /prop_tgt/LINK_INTERFACE_MULTIPLICITY + /prop_tgt/LINK_LIBRARIES + /prop_tgt/LINK_OPTIONS + /prop_tgt/LINK_SEARCH_END_STATIC + /prop_tgt/LINK_SEARCH_START_STATIC + /prop_tgt/LINK_WHAT_YOU_USE + /prop_tgt/LOCATION_CONFIG + /prop_tgt/LOCATION + /prop_tgt/MACOSX_BUNDLE_INFO_PLIST + /prop_tgt/MACOSX_BUNDLE + /prop_tgt/MACOSX_FRAMEWORK_INFO_PLIST + /prop_tgt/MACOSX_RPATH + /prop_tgt/MANUALLY_ADDED_DEPENDENCIES + /prop_tgt/MAP_IMPORTED_CONFIG_CONFIG + /prop_tgt/NAME + /prop_tgt/NO_SONAME + /prop_tgt/NO_SYSTEM_FROM_IMPORTED + /prop_tgt/OSX_ARCHITECTURES_CONFIG + /prop_tgt/OSX_ARCHITECTURES + /prop_tgt/OUTPUT_NAME_CONFIG + /prop_tgt/OUTPUT_NAME + /prop_tgt/PDB_NAME_CONFIG + /prop_tgt/PDB_NAME + /prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG + /prop_tgt/PDB_OUTPUT_DIRECTORY + /prop_tgt/POSITION_INDEPENDENT_CODE + /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_CONFIG + /prop_tgt/RUNTIME_OUTPUT_DIRECTORY + /prop_tgt/RUNTIME_OUTPUT_NAME_CONFIG + /prop_tgt/RUNTIME_OUTPUT_NAME + /prop_tgt/SKIP_BUILD_RPATH + /prop_tgt/SOURCE_DIR + /prop_tgt/SOURCES + /prop_tgt/SOVERSION + /prop_tgt/STATIC_LIBRARY_FLAGS_CONFIG + /prop_tgt/STATIC_LIBRARY_FLAGS + /prop_tgt/STATIC_LIBRARY_OPTIONS + /prop_tgt/SUFFIX + /prop_tgt/TYPE + /prop_tgt/VERSION + /prop_tgt/VISIBILITY_INLINES_HIDDEN + /prop_tgt/VS_CONFIGURATION_TYPE + /prop_tgt/VS_DEBUGGER_COMMAND + /prop_tgt/VS_DEBUGGER_COMMAND_ARGUMENTS + /prop_tgt/VS_DEBUGGER_ENVIRONMENT + /prop_tgt/VS_DEBUGGER_WORKING_DIRECTORY + /prop_tgt/VS_DESKTOP_EXTENSIONS_VERSION + /prop_tgt/VS_DOTNET_REFERENCE_refname + /prop_tgt/VS_DOTNET_REFERENCEPROP_refname_TAG_tagname + /prop_tgt/VS_DOTNET_REFERENCES + /prop_tgt/VS_DOTNET_REFERENCES_COPY_LOCAL + /prop_tgt/VS_DOTNET_TARGET_FRAMEWORK_VERSION + /prop_tgt/VS_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_KEYWORD + /prop_tgt/VS_MOBILE_EXTENSIONS_VERSION + /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_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_EXPLICIT_FILE_TYPE + /prop_tgt/XCODE_PRODUCT_TYPE + /prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER + /prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN + /prop_tgt/XCODE_SCHEME_THREAD_SANITIZER + /prop_tgt/XCODE_SCHEME_THREAD_SANITIZER_STOP + /prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER + /prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP + /prop_tgt/XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER + /prop_tgt/XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP + /prop_tgt/XCODE_SCHEME_MALLOC_SCRIBBLE + /prop_tgt/XCODE_SCHEME_MALLOC_GUARD_EDGES + /prop_tgt/XCODE_SCHEME_GUARD_MALLOC + /prop_tgt/XCODE_SCHEME_ZOMBIE_OBJECTS + /prop_tgt/XCODE_SCHEME_MALLOC_STACK + /prop_tgt/XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE + /prop_tgt/XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS + /prop_tgt/XCODE_SCHEME_EXECUTABLE + /prop_tgt/XCODE_SCHEME_ARGUMENTS + /prop_tgt/XCODE_SCHEME_ENVIRONMENT + /prop_tgt/XCTEST + +.. _`Test Properties`: + +Properties on Tests +=================== + +.. toctree:: + :maxdepth: 1 + + /prop_test/ATTACHED_FILES_ON_FAIL + /prop_test/ATTACHED_FILES + /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_LOCK + /prop_test/RUN_SERIAL + /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/AUTOUIC_OPTIONS + /prop_sf/AUTORCC_OPTIONS + /prop_sf/COMPILE_DEFINITIONS + /prop_sf/COMPILE_FLAGS + /prop_sf/COMPILE_OPTIONS + /prop_sf/EXTERNAL_OBJECT + /prop_sf/Fortran_FORMAT + /prop_sf/GENERATED + /prop_sf/HEADER_FILE_ONLY + /prop_sf/INCLUDE_DIRECTORIES + /prop_sf/KEEP_EXTENSION + /prop_sf/LABELS + /prop_sf/LANGUAGE + /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/SYMBOLIC + /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_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/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..724d8ec --- /dev/null +++ b/Help/manual/cmake-qt.7.rst @@ -0,0 +1,250 @@ +.. 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 filesystem content generation. These tools may be +automatically invoked by :manual:`cmake(1)` if the appropriate conditions +are met. The automatic tool invocation may be used with both Qt 4 and Qt 5. + +The tools are executed as part of a synthesized custom target generated by +CMake. Target dependencies may be added to that custom target by adding them +to the :prop_tgt:`AUTOGEN_TARGET_DEPENDS` target property. + +AUTOMOC +^^^^^^^ + +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 +``<AUTOGEN_BUILD_DIR>/mocs_compilation.cpp`` file which is compiled +into the target. + +* 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`. + +Visual Studio Generators +======================== + +When using the :manual:`Visual Studio generators <cmake-generators(7)>`, +CMake uses a ``PRE_BUILD`` :command:`custom command <add_custom_command>` for +:prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`. +If the :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` processing depends on files, +a :command:`custom target <add_custom_target>` is used instead. +This happens when + +- 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 + +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..b4c1436 --- /dev/null +++ b/Help/manual/cmake-server.7.rst @@ -0,0 +1,746 @@ +.. cmake-manual-description: CMake Server + +cmake-server(7) +*************** + +.. only:: html + + .. contents:: + +Introduction +============ + +:manual:`cmake(1)` is capable of providing semantic information about +CMake code it executes to generate a buildsystem. If executed with +the ``-E server`` command line options, it starts in a long running mode +and allows a client to request the available information via a JSON protocol. + +The protocol is designed to be useful to IDEs, refactoring tools, and +other tools which have a need to understand the buildsystem in entirety. + +A single :manual:`cmake-buildsystem(7)` may describe buildsystem contents +and build properties which differ based on +:manual:`generation-time context <cmake-generator-expressions(7)>` +including: + +* The Platform (eg, Windows, APPLE, Linux). +* The build configuration (eg, Debug, Release, Coverage). +* The Compiler (eg, MSVC, GCC, Clang) and compiler version. +* The language of the source files compiled. +* Available compile features (eg CXX variadic templates). +* CMake policies. + +The protocol aims to provide information to tooling to satisfy several +needs: + +#. Provide a complete and easily parsed source of all information relevant + to the tooling as it relates to the source code. There should be no need + for tooling to parse generated buildsystems to access include directories + or compile definitions for example. +#. Semantic information about the CMake buildsystem itself. +#. Provide a stable interface for reading the information in the CMake cache. +#. Information for determining when cmake needs to be re-run as a result of + file changes. + + +Operation +========= + +Start :manual:`cmake(1)` in the server command mode, supplying the path to +the build directory to process:: + + cmake -E server (--debug|--pipe=<NAMED_PIPE>) + +The server will communicate using stdin/stdout (with the ``--debug`` parameter) +or using a named pipe (with the ``--pipe=<NAMED_PIPE>`` parameter). Note +that "named pipe" refers to a local domain socket on Unix and to a named pipe +on Windows. + +When connecting to the server (via named pipe or by starting it in ``--debug`` +mode), the server will reply with a hello message:: + + [== "CMake Server" ==[ + {"supportedProtocolVersions":[{"major":1,"minor":0}],"type":"hello"} + ]== "CMake Server" ==] + +Messages sent to and from the process are wrapped in magic strings:: + + [== "CMake Server" ==[ + { + ... some JSON message ... + } + ]== "CMake Server" ==] + +The server is now ready to accept further requests via the named pipe +or stdin. + + +Debugging +========= + +CMake server mode can be asked to provide statistics on execution times, etc. +or to dump a copy of the response into a file. This is done passing a "debug" +JSON object as a child of the request. + +The debug object supports the "showStats" key, which takes a boolean and makes +the server mode return a "zzzDebug" object with stats as part of its response. +"dumpToFile" takes a string value and will cause the cmake server to copy +the response into the given filename. + +This is a response from the cmake server with "showStats" set to true:: + + [== "CMake Server" ==[ + { + "cookie":"", + "errorMessage":"Waiting for type \"handshake\".", + "inReplyTo":"unknown", + "type":"error", + "zzzDebug": { + "dumpFile":"/tmp/error.txt", + "jsonSerialization":0.011016, + "size":111, + "totalTime":0.025995 + } + } + ]== "CMake Server" ==] + +The server has made a copy of this response into the file /tmp/error.txt and +took 0.011 seconds to turn the JSON response into a string, and it took 0.025 +seconds to process the request in total. The reply has a size of 111 bytes. + + +Protocol API +============ + + +General Message Layout +---------------------- + +All messages need to have a "type" value, which identifies the type of +message that is passed back or forth. E.g. the initial message sent by the +server is of type "hello". Messages without a type will generate an response +of type "error". + +All requests sent to the server may contain a "cookie" value. This value +will he handed back unchanged in all responses triggered by the request. + +All responses will contain a value "inReplyTo", which may be empty in +case of parse errors, but will contain the type of the request message +in all other cases. + + +Type "reply" +^^^^^^^^^^^^ + +This type is used by the server to reply to requests. + +The message may -- depending on the type of the original request -- +contain values. + +Example:: + + [== "CMake Server" ==[ + {"cookie":"zimtstern","inReplyTo":"handshake","type":"reply"} + ]== "CMake Server" ==] + + +Type "error" +^^^^^^^^^^^^ + +This type is used to return an error condition to the client. It will +contain an "errorMessage". + +Example:: + + [== "CMake Server" ==[ + {"cookie":"","errorMessage":"Protocol version not supported.","inReplyTo":"handshake","type":"error"} + ]== "CMake Server" ==] + + +Type "progress" +^^^^^^^^^^^^^^^ + +When the server is busy for a long time, it is polite to send back replies of +type "progress" to the client. These will contain a "progressMessage" with a +string describing the action currently taking place as well as +"progressMinimum", "progressMaximum" and "progressCurrent" with integer values +describing the range of progress. + +Messages of type "progress" will be followed by more "progress" messages or with +a message of type "reply" or "error" that complete the request. + +"progress" messages may not be emitted after the "reply" or "error" message for +the request that triggered the responses was delivered. + + +Type "message" +^^^^^^^^^^^^^^ + +A message is triggered when the server processes a request and produces some +form of output that should be displayed to the user. A Message has a "message" +with the actual text to display as well as a "title" with a suggested dialog +box title. + +Example:: + + [== "CMake Server" ==[ + {"cookie":"","message":"Something happened.","title":"Title Text","inReplyTo":"handshake","type":"message"} + ]== "CMake Server" ==] + + +Type "signal" +^^^^^^^^^^^^^ + +The server can send signals when it detects changes in the system state. Signals +are of type "signal", have an empty "cookie" and "inReplyTo" field and always +have a "name" set to show which signal was sent. + + +Specific Signals +---------------- + +The cmake server may sent signals with the following names: + +"dirty" Signal +^^^^^^^^^^^^^^ + +The "dirty" signal is sent whenever the server determines that the configuration +of the project is no longer up-to-date. This happens when any of the files that have +an influence on the build system is changed. + +The "dirty" signal may look like this:: + + [== "CMake Server" ==[ + { + "cookie":"", + "inReplyTo":"", + "name":"dirty", + "type":"signal"} + ]== "CMake Server" ==] + + +"fileChange" Signal +^^^^^^^^^^^^^^^^^^^ + +The "fileChange" signal is sent whenever a watched file is changed. It contains +the "path" that has changed and a list of "properties" with the kind of change +that was detected. Possible changes are "change" and "rename". + +The "fileChange" signal looks like this:: + + [== "CMake Server" ==[ + { + "cookie":"", + "inReplyTo":"", + "name":"fileChange", + "path":"/absolute/CMakeLists.txt", + "properties":["change"], + "type":"signal"} + ]== "CMake Server" ==] + + +Specific Message Types +---------------------- + + +Type "hello" +^^^^^^^^^^^^ + +The initial message send by the cmake server on startup is of type "hello". +This is the only message ever sent by the server that is not of type "reply", +"progress" or "error". + +It will contain "supportedProtocolVersions" with an array of server protocol +versions supported by the cmake server. These are JSON objects with "major" and +"minor" keys containing non-negative integer values. Some versions may be marked +as experimental. These will contain the "isExperimental" key set to true. Enabling +these requires a special command line argument when starting the cmake server mode. + +Within a "major" version all "minor" versions are fully backwards compatible. +New "minor" versions may introduce functionality in such a way that existing +clients of the same "major" version will continue to work, provided they +ignore keys in the output that they do not know about. + +Example:: + + [== "CMake Server" ==[ + {"supportedProtocolVersions":[{"major":0,"minor":1}],"type":"hello"} + ]== "CMake Server" ==] + + +Type "handshake" +^^^^^^^^^^^^^^^^ + +The first request that the client may send to the server is of type "handshake". + +This request needs to pass one of the "supportedProtocolVersions" of the "hello" +type response received earlier back to the server in the "protocolVersion" field. +Giving the "major" version of the requested protocol version will make the server +use the latest minor version of that protocol. Use this if you do not explicitly +need to depend on a specific minor version. + +Protocol version 1.0 requires the following attributes to be set: + + * "sourceDirectory" with a path to the sources + * "buildDirectory" with a path to the build directory + * "generator" with the generator name + * "extraGenerator" (optional!) with the extra generator to be used + * "platform" with the generator platform (if supported by the generator) + * "toolset" with the generator toolset (if supported by the generator) + +Protocol version 1.2 makes all but the build directory optional, provided +there is a valid cache in the build directory that contains all the other +information already. + +Example:: + + [== "CMake Server" ==[ + {"cookie":"zimtstern","type":"handshake","protocolVersion":{"major":0}, + "sourceDirectory":"/home/code/cmake", "buildDirectory":"/tmp/testbuild", + "generator":"Ninja"} + ]== "CMake Server" ==] + +which will result in a response type "reply":: + + [== "CMake Server" ==[ + {"cookie":"zimtstern","inReplyTo":"handshake","type":"reply"} + ]== "CMake Server" ==] + +indicating that the server is ready for action. + +Protocol version 1.3 introduces an optional flag on the target filegroup +that indicates if the filegroup represents :prop_tgt:`INTERFACE_SOURCES`. + + +Type "globalSettings" +^^^^^^^^^^^^^^^^^^^^^ + +This request can be sent after the initial handshake. It will return a +JSON structure with information on cmake state. + +Example:: + + [== "CMake Server" ==[ + {"type":"globalSettings"} + ]== "CMake Server" ==] + +which will result in a response type "reply":: + + [== "CMake Server" ==[ + { + "buildDirectory": "/tmp/test-build", + "capabilities": { + "generators": [ + { + "extraGenerators": [], + "name": "Watcom WMake", + "platformSupport": false, + "toolsetSupport": false + }, + <...> + ], + "serverMode": false, + "version": { + "isDirty": false, + "major": 3, + "minor": 6, + "patch": 20160830, + "string": "3.6.20160830-gd6abad", + "suffix": "gd6abad" + } + }, + "checkSystemVars": false, + "cookie": "", + "extraGenerator": "", + "generator": "Ninja", + "debugOutput": false, + "inReplyTo": "globalSettings", + "sourceDirectory": "/home/code/cmake", + "trace": false, + "traceExpand": false, + "type": "reply", + "warnUninitialized": false, + "warnUnused": false, + "warnUnusedCli": true + } + ]== "CMake Server" ==] + + +Type "setGlobalSettings" +^^^^^^^^^^^^^^^^^^^^^^^^ + +This request can be sent to change the global settings attributes. Unknown +attributes are going to be ignored. Read-only attributes reported by +"globalSettings" are all capabilities, buildDirectory, generator, +extraGenerator and sourceDirectory. Any attempt to set these will be ignored, +too. + +All other settings will be changed. + +The server will respond with an empty reply message or an error. + +Example:: + + [== "CMake Server" ==[ + {"type":"setGlobalSettings","debugOutput":true} + ]== "CMake Server" ==] + +CMake will reply to this with:: + + [== "CMake Server" ==[ + {"inReplyTo":"setGlobalSettings","type":"reply"} + ]== "CMake Server" ==] + + +Type "configure" +^^^^^^^^^^^^^^^^ + +This request will configure a project for build. + +To configure a build directory already containing cmake files, it is enough to +set "buildDirectory" via "setGlobalSettings". To create a fresh build directory +you also need to set "currentGenerator" and "sourceDirectory" via "setGlobalSettings" +in addition to "buildDirectory". + +You may a list of strings to "configure" via the "cacheArguments" key. These +strings will be interpreted similar to command line arguments related to +cache handling that are passed to the cmake command line client. + +Example:: + + [== "CMake Server" ==[ + {"type":"configure", "cacheArguments":["-Dsomething=else"]} + ]== "CMake Server" ==] + +CMake will reply like this (after reporting progress for some time):: + + [== "CMake Server" ==[ + {"cookie":"","inReplyTo":"configure","type":"reply"} + ]== "CMake Server" ==] + + +Type "compute" +^^^^^^^^^^^^^^ + +This request will generate build system files in the build directory and +is only available after a project was successfully "configure"d. + +Example:: + + [== "CMake Server" ==[ + {"type":"compute"} + ]== "CMake Server" ==] + +CMake will reply (after reporting progress information):: + + [== "CMake Server" ==[ + {"cookie":"","inReplyTo":"compute","type":"reply"} + ]== "CMake Server" ==] + + +Type "codemodel" +^^^^^^^^^^^^^^^^ + +The "codemodel" request can be used after a project was "compute"d successfully. + +It will list the complete project structure as it is known to cmake. + +The reply will contain a key "configurations", which will contain a list of +configuration objects. Configuration objects are used to destinquish between +different configurations the build directory might have enabled. While most +generators only support one configuration, others might support several. + +Each configuration object can have the following keys: + +"name" + contains the name of the configuration. The name may be empty. +"projects" + contains a list of project objects, one for each build project. + +Project objects define one (sub-)project defined in the cmake build system. + +Each project object can have the following keys: + +"name" + contains the (sub-)projects name. +"minimumCMakeVersion" + contains the minimum cmake version allowed for this project, null if the + project doesn't specify one. +"hasInstallRule" + true if the project contains any install rules, false otherwise. +"sourceDirectory" + contains the current source directory +"buildDirectory" + contains the current build directory. +"targets" + contains a list of build system target objects. + +Target objects define individual build targets for a certain configuration. + +Each target object can have the following keys: + +"name" + contains the name of the target. +"type" + defines the type of build of the target. Possible values are + "STATIC_LIBRARY", "MODULE_LIBRARY", "SHARED_LIBRARY", "OBJECT_LIBRARY", + "EXECUTABLE", "UTILITY" and "INTERFACE_LIBRARY". +"fullName" + contains the full name of the build result (incl. extensions, etc.). +"sourceDirectory" + contains the current source directory. +"buildDirectory" + contains the current build directory. +"isGeneratorProvided" + true if the target is auto-created by a generator, false otherwise +"hasInstallRule" + true if the target contains any install rules, false otherwise. +"installPaths" + full path to the destination directories defined by target install rules. +"artifacts" + with a list of build artifacts. The list is sorted with the most + important artifacts first (e.g. a .DLL file is listed before a + .PDB file on windows). +"linkerLanguage" + contains the language of the linker used to produce the artifact. +"linkLibraries" + with a list of libraries to link to. This value is encoded in the + system's native shell format. +"linkFlags" + with a list of flags to pass to the linker. This value is encoded in + the system's native shell format. +"linkLanguageFlags" + with the flags for a compiler using the linkerLanguage. This value is + encoded in the system's native shell format. +"frameworkPath" + with the framework path (on Apple computers). This value is encoded + in the system's native shell format. +"linkPath" + with the link path. This value is encoded in the system's native shell + format. +"sysroot" + with the sysroot path. +"fileGroups" + contains the source files making up the target. + +FileGroups are used to group sources using similar settings together. + +Each fileGroup object may contain the following keys: + +"isInterfaceSources" + true if the fileGroup represents :prop_tgt:`INTERFACE_SOURCES`. +"language" + contains the programming language used by all files in the group. +"compileFlags" + with a string containing all the flags passed to the compiler + when building any of the files in this group. This value is encoded in + the system's native shell format. +"includePath" + with a list of include paths. Each include path is an object + containing a "path" with the actual include path and "isSystem" with a bool + value informing whether this is a normal include or a system include. This + value is encoded in the system's native shell format. +"defines" + with a list of defines in the form "SOMEVALUE" or "SOMEVALUE=42". This + value is encoded in the system's native shell format. +"isGenerated" + true if the files were generated. +"sources" + with a list of source files. + +All file paths in the fileGroup are either absolute or relative to the +sourceDirectory of the target. + +Example:: + + [== "CMake Server" ==[ + {"type":"codemodel"} + ]== "CMake Server" ==] + +CMake will reply:: + + [== "CMake Server" ==[ + { + "configurations": [ + { + "name": "", + "projects": [ + { + "buildDirectory": "/tmp/build/Source/CursesDialog/form", + "name": "CMAKE_FORM", + "sourceDirectory": "/home/code/src/cmake/Source/CursesDialog/form", + "targets": [ + { + "artifacts": [ "/tmp/build/Source/CursesDialog/form/libcmForm.a" ], + "buildDirectory": "/tmp/build/Source/CursesDialog/form", + "fileGroups": [ + { + "compileFlags": " -std=gnu11", + "defines": [ "CURL_STATICLIB", "LIBARCHIVE_STATIC" ], + "includePath": [ { "path": "/tmp/build/Utilities" }, <...> ], + "isGenerated": false, + "language": "C", + "sources": [ "fld_arg.c", <...> ] + } + ], + "fullName": "libcmForm.a", + "linkerLanguage": "C", + "name": "cmForm", + "sourceDirectory": "/home/code/src/cmake/Source/CursesDialog/form", + "type": "STATIC_LIBRARY" + } + ] + }, + <...> + ] + } + ], + "cookie": "", + "inReplyTo": "codemodel", + "type": "reply" + } + ]== "CMake Server" ==] + + +Type "ctestInfo" +^^^^^^^^^^^^^^^^ + +The "ctestInfo" request can be used after a project was "compute"d successfully. + +It will list the complete project test structure as it is known to cmake. + +The reply will contain a key "configurations", which will contain a list of +configuration objects. Configuration objects are used to destinquish between +different configurations the build directory might have enabled. While most +generators only support one configuration, others might support several. + +Each configuration object can have the following keys: + +"name" + contains the name of the configuration. The name may be empty. +"projects" + contains a list of project objects, one for each build project. + +Project objects define one (sub-)project defined in the cmake build system. + +Each project object can have the following keys: + +"name" + contains the (sub-)projects name. +"ctestInfo" + contains a list of test objects. + +Each test object can have the following keys: + +"ctestName" + contains the name of the test. +"ctestCommand" + contains the test command. +"properties" + contains a list of test property objects. + +Each test property object can have the following keys: + +"key" + contains the test property key. +"value" + contains the test property value. + + +Type "cmakeInputs" +^^^^^^^^^^^^^^^^^^ + +The "cmakeInputs" requests will report files used by CMake as part +of the build system itself. + +This request is only available after a project was successfully +"configure"d. + +Example:: + + [== "CMake Server" ==[ + {"type":"cmakeInputs"} + ]== "CMake Server" ==] + +CMake will reply with the following information:: + + [== "CMake Server" ==[ + {"buildFiles": + [ + {"isCMake":true,"isTemporary":false,"sources":["/usr/lib/cmake/...", ... ]}, + {"isCMake":false,"isTemporary":false,"sources":["CMakeLists.txt", ...]}, + {"isCMake":false,"isTemporary":true,"sources":["/tmp/build/CMakeFiles/...", ...]} + ], + "cmakeRootDirectory":"/usr/lib/cmake", + "sourceDirectory":"/home/code/src/cmake", + "cookie":"", + "inReplyTo":"cmakeInputs", + "type":"reply" + } + ]== "CMake Server" ==] + +All file names are either relative to the top level source directory or +absolute. + +The list of files which "isCMake" set to true are part of the cmake installation. + +The list of files witch "isTemporary" set to true are part of the build directory +and will not survive the build directory getting cleaned out. + + +Type "cache" +^^^^^^^^^^^^ + +The "cache" request will list the cached configuration values. + +Example:: + + [== "CMake Server" ==[ + {"type":"cache"} + ]== "CMake Server" ==] + +CMake will respond with the following output:: + + [== "CMake Server" ==[ + { + "cookie":"","inReplyTo":"cache","type":"reply", + "cache": + [ + { + "key":"SOMEVALUE", + "properties": + { + "ADVANCED":"1", + "HELPSTRING":"This is not helpful" + } + "type":"STRING", + "value":"TEST"} + ] + } + ]== "CMake Server" ==] + +The output can be limited to a list of keys by passing an array of key names +to the "keys" optional field of the "cache" request. + + +Type "fileSystemWatchers" +^^^^^^^^^^^^^^^^^^^^^^^^^ + +The server can watch the filesystem for changes. The "fileSystemWatchers" +command will report on the files and directories watched. + +Example:: + + [== "CMake Server" ==[ + {"type":"fileSystemWatchers"} + ]== "CMake Server" ==] + +CMake will respond with the following output:: + + [== "CMake Server" ==[ + { + "cookie":"","inReplyTo":"fileSystemWatchers","type":"reply", + "watchedFiles": [ "/absolute/path" ], + "watchedDirectories": [ "/absolute" ] + } + ]== "CMake Server" ==] diff --git a/Help/manual/cmake-toolchains.7.rst b/Help/manual/cmake-toolchains.7.rst new file mode 100644 index 0000000..8554e87 --- /dev/null +++ b/Help/manual/cmake-toolchains.7.rst @@ -0,0 +1,524 @@ +.. 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 +``-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. + +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}) + +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>` to be installed. See that section 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. + +.. _`Cross Compiling for Android with the NDK`: + +Cross Compiling for Android with the NDK +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A toolchain file may configure :ref:`Makefile Generators` or the +:generator:`Ninja` generator 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 ``armeabi``. + 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. + A ``${CMAKE_ANDROID_NDK}/platforms`` 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_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` + Set to the version of the NDK toolchain to be selected as the compiler. + If not specified, the default will be the latest available GCC toolchain. + +: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` diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst new file mode 100644 index 0000000..9dd36ed --- /dev/null +++ b/Help/manual/cmake-variables.7.rst @@ -0,0 +1,591 @@ +.. cmake-manual-description: CMake Variables Reference + +cmake-variables(7) +****************** + +.. only:: html + + .. contents:: + +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_CACHEFILE_DIR + /variable/CMAKE_CACHE_MAJOR_VERSION + /variable/CMAKE_CACHE_MINOR_VERSION + /variable/CMAKE_CACHE_PATCH_VERSION + /variable/CMAKE_CFG_INTDIR + /variable/CMAKE_COMMAND + /variable/CMAKE_CPACK_COMMAND + /variable/CMAKE_CROSSCOMPILING + /variable/CMAKE_CROSSCOMPILING_EMULATOR + /variable/CMAKE_CTEST_COMMAND + /variable/CMAKE_CURRENT_BINARY_DIR + /variable/CMAKE_CURRENT_LIST_DIR + /variable/CMAKE_CURRENT_LIST_FILE + /variable/CMAKE_CURRENT_LIST_LINE + /variable/CMAKE_CURRENT_SOURCE_DIR + /variable/CMAKE_DIRECTORY_LABELS + /variable/CMAKE_DL_LIBS + /variable/CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION + /variable/CMAKE_EDIT_COMMAND + /variable/CMAKE_EXECUTABLE_SUFFIX + /variable/CMAKE_EXTRA_GENERATOR + /variable/CMAKE_EXTRA_SHARED_LIBRARY_SUFFIXES + /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_HOME_DIRECTORY + /variable/CMAKE_IMPORT_LIBRARY_PREFIX + /variable/CMAKE_IMPORT_LIBRARY_SUFFIX + /variable/CMAKE_JOB_POOL_COMPILE + /variable/CMAKE_JOB_POOL_LINK + /variable/CMAKE_JOB_POOLS + /variable/CMAKE_LANG_COMPILER_AR + /variable/CMAKE_LANG_COMPILER_RANLIB + /variable/CMAKE_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_TOOLCHAIN_FILE + /variable/CMAKE_TWEAK_VERSION + /variable/CMAKE_VERBOSE_MAKEFILE + /variable/CMAKE_VERSION + /variable/CMAKE_VS_DEVENV_COMMAND + /variable/CMAKE_VS_INTEL_Fortran_PROJECT_VERSION + /variable/CMAKE_VS_MSBUILD_COMMAND + /variable/CMAKE_VS_NsightTegra_VERSION + /variable/CMAKE_VS_PLATFORM_NAME + /variable/CMAKE_VS_PLATFORM_TOOLSET + /variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA + /variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE + /variable/CMAKE_VS_PLATFORM_TOOLSET_VERSION + /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION + /variable/CMAKE_XCODE_GENERATE_SCHEME + /variable/CMAKE_XCODE_PLATFORM_TOOLSET + /variable/PROJECT-NAME_BINARY_DIR + /variable/PROJECT-NAME_DESCRIPTION + /variable/PROJECT-NAME_HOMEPAGE_URL + /variable/PROJECT-NAME_SOURCE_DIR + /variable/PROJECT-NAME_VERSION + /variable/PROJECT-NAME_VERSION_MAJOR + /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_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_CODEBLOCKS_COMPILER_ID + /variable/CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES + /variable/CMAKE_CODELITE_USE_TARGETS + /variable/CMAKE_COLOR_MAKEFILE + /variable/CMAKE_CONFIGURATION_TYPES + /variable/CMAKE_DEBUG_TARGET_PROPERTIES + /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_VERSION + /variable/CMAKE_ERROR_DEPRECATED + /variable/CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION + /variable/CMAKE_EXPORT_COMPILE_COMMANDS + /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_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_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_MODULE_PATH + /variable/CMAKE_NOT_USING_CONFIG_FLAGS + /variable/CMAKE_POLICY_DEFAULT_CMPNNNN + /variable/CMAKE_POLICY_WARNING_CMPNNNN + /variable/CMAKE_PREFIX_PATH + /variable/CMAKE_PROGRAM_PATH + /variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE + /variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY + /variable/CMAKE_STAGING_PREFIX + /variable/CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS + /variable/CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE + /variable/CMAKE_SUPPRESS_REGENERATION + /variable/CMAKE_SYSROOT + /variable/CMAKE_SYSROOT_COMPILE + /variable/CMAKE_SYSROOT_LINK + /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_TOP_LEVEL_PROJECT_ONLY + /variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER + /variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN + /variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER + /variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP + /variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER + /variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP + /variable/CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER + /variable/CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP + /variable/CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE + /variable/CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES + /variable/CMAKE_XCODE_SCHEME_GUARD_MALLOC + /variable/CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS + /variable/CMAKE_XCODE_SCHEME_MALLOC_STACK + /variable/CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE + /variable/CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS + /variable/PackageName_ROOT + +Variables that Describe the System +================================== + +.. toctree:: + :maxdepth: 1 + + /variable/ANDROID + /variable/APPLE + /variable/BORLAND + /variable/CACHE + /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/ENV + /variable/GHS-MULTI + /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/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_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_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_SECURE_PROPS_PATH + /variable/CMAKE_ANDROID_SKIP_ANT_STEP + /variable/CMAKE_ANDROID_STANDALONE_TOOLCHAIN + /variable/CMAKE_ANDROID_STL_TYPE + /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY + /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG + /variable/CMAKE_AUTOGEN_PARALLEL + /variable/CMAKE_AUTOGEN_VERBOSE + /variable/CMAKE_AUTOMOC + /variable/CMAKE_AUTOMOC_COMPILER_PREDEFINES + /variable/CMAKE_AUTOMOC_DEPEND_FILTERS + /variable/CMAKE_AUTOMOC_MACRO_NAMES + /variable/CMAKE_AUTOMOC_MOC_OPTIONS + /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_WITH_INSTALL_NAME_DIR + /variable/CMAKE_BUILD_WITH_INSTALL_RPATH + /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY + /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG + /variable/CMAKE_CONFIG_POSTFIX + /variable/CMAKE_CUDA_SEPARABLE_COMPILATION + /variable/CMAKE_DEBUG_POSTFIX + /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_Fortran_FORMAT + /variable/CMAKE_Fortran_MODULE_DIRECTORY + /variable/CMAKE_GNUtoMS + /variable/CMAKE_INCLUDE_CURRENT_DIR + /variable/CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE + /variable/CMAKE_INSTALL_NAME_DIR + /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_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_NINJA_OUTPUT_PATH_PREFIX + /variable/CMAKE_NO_BUILTIN_CHRPATH + /variable/CMAKE_NO_SYSTEM_FROM_IMPORTED + /variable/CMAKE_OSX_ARCHITECTURES + /variable/CMAKE_OSX_DEPLOYMENT_TARGET + /variable/CMAKE_OSX_SYSROOT + /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_USE_RELATIVE_PATHS + /variable/CMAKE_VISIBILITY_INLINES_HIDDEN + /variable/CMAKE_VS_GLOBALS + /variable/CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD + /variable/CMAKE_VS_INCLUDE_PACKAGE_TO_DEFAULT_BUILD + /variable/CMAKE_VS_SDK_EXCLUDE_DIRECTORIES + /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_HOST_COMPILER + /variable/CMAKE_CUDA_EXTENSIONS + /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_INTERNAL_PLATFORM_ABI + /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_COMPILER + /variable/CMAKE_LANG_COMPILER_ABI + /variable/CMAKE_LANG_COMPILER_ARCHITECTURE_ID + /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_COMPILER_VERSION_INTERNAL + /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_GHS_KERNEL_FLAGS_CONFIG + /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_DEBUG + /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_MINSIZEREL + /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELEASE + /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELWITHDEBINFO + /variable/CMAKE_LANG_IGNORE_EXTENSIONS + /variable/CMAKE_LANG_IMPLICIT_INCLUDE_DIRECTORIES + /variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES + /variable/CMAKE_LANG_IMPLICIT_LINK_FRAMEWORK_DIRECTORIES + /variable/CMAKE_LANG_IMPLICIT_LINK_LIBRARIES + /variable/CMAKE_LANG_LIBRARY_ARCHITECTURE + /variable/CMAKE_LANG_LINKER_PREFERENCE + /variable/CMAKE_LANG_LINKER_PREFERENCE_PROPAGATES + /variable/CMAKE_LANG_LINKER_WRAPPER_FLAG + /variable/CMAKE_LANG_LINKER_WRAPPER_FLAG_SEP + /variable/CMAKE_LANG_LINK_EXECUTABLE + /variable/CMAKE_LANG_OUTPUT_EXTENSION + /variable/CMAKE_LANG_PLATFORM_ID + /variable/CMAKE_LANG_SIMULATE_ID + /variable/CMAKE_LANG_SIMULATE_VERSION + /variable/CMAKE_LANG_SIZEOF_DATA_PTR + /variable/CMAKE_LANG_SOURCE_FILE_EXTENSIONS + /variable/CMAKE_LANG_STANDARD_INCLUDE_DIRECTORIES + /variable/CMAKE_LANG_STANDARD_LIBRARIES + /variable/CMAKE_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_TEST_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_RUN_CURRENT_SCRIPT + /variable/CTEST_SCP_COMMAND + /variable/CTEST_SITE + /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_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_INSTALL_SCRIPT + /variable/CPACK_PACKAGING_INSTALL_PREFIX + /variable/CPACK_SET_DESTDIR + /variable/CPACK_WARN_ON_ABSOLUTE_INSTALL_DESTINATION diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst new file mode 100644 index 0000000..b11526c --- /dev/null +++ b/Help/manual/cmake.1.rst @@ -0,0 +1,403 @@ +.. cmake-manual-description: CMake Command-Line Reference + +cmake(1) +******** + +Synopsis +======== + +.. parsed-literal:: + + cmake [<options>] {<path-to-source> | <path-to-existing-build>} + cmake [<options>] -S <path-to-source> -B <path-to-build> + cmake [{-D <var>=<value>}...] -P <cmake-script-file> + cmake --build <dir> [<options>...] [-- <build-tool-options>...] + cmake --open <dir> + cmake -E <command> [<options>...] + cmake --find-package <options>... + +Description +=========== + +The "cmake" executable is the CMake command-line interface. It may be +used to configure projects in scripts. Project configuration settings +may be specified on the command line with the -D option. + +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. + +.. _`CMake Options`: + +Options +======= + +.. include:: OPTIONS_BUILD.txt + +``-E <command> [<options>...]`` + See `Command-Line Tool Mode`_. + +``-L[A][H]`` + List non-advanced cached variables. + + List cache variables will run CMake and list all the variables from + the CMake cache that are not marked as INTERNAL or ADVANCED. This + will effectively display current CMake settings, which can then be + changed with -D option. Changing some of the variables may result + in more variables being created. If A is specified, then it will + display also advanced variables. If H is specified, it will also + display help for each variable. + +``--build <dir>`` + See `Build Tool Mode`_. + +``--open <dir>`` + Open the generated project in the associated application. This is + only supported by some generators. + +``-N`` + View mode only. + + Only load the cache. Do not actually run configure and generate + steps. + +``-P <file>`` + Process script mode. + + Process the given cmake file as a script written in the CMake + language. No configure or generate step is performed and the cache + is not modified. If variables are defined using -D, this must be + done before the -P argument. + +``--find-package`` + See `Find-Package Tool Mode`_. + +``--graphviz=[file]`` + Generate graphviz of dependencies, see :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. + +``--debug-trycompile`` + Do not delete the try_compile build tree. Only useful on one try_compile at a time. + + Do not delete the files and directories created for 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 + message(send_error ) calls. + +``--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-source=<file>`` + Put cmake in trace mode, but output only lines of a specified file. + + Multiple options are allowed. + +``--warn-uninitialized`` + Warn about uninitialized values. + + Print a warning when an uninitialized variable is used. + +``--warn-unused-vars`` + Warn about unused variables. + + Find variables that are declared or set, but not used. + +``--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 CMAKE_SOURCE_DIR and CMAKE_BINARY_DIR. This flag tells CMake to + warn about other files as well. + +.. include:: OPTIONS_HELP.txt + +.. _`Build Tool Mode`: + +Build Tool Mode +=============== + +CMake provides a command-line signature to build an already-generated +project binary tree:: + + cmake --build <dir> [<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 and must be first. + +``-j [<jobs>], --parallel [<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. + +``--target <tgt>`` + Build ``<tgt>`` instead of default targets. May only be specified once. + +``--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. + +``--`` + Pass remaining options to the native tool. + +Run ``cmake --build`` with no options for quick help. + +Command-Line Tool Mode +====================== + +CMake provides builtin command-line tools through the signature:: + + 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. + + ``serverMode`` + ``true`` if cmake supports server-mode and ``false`` otherwise. + +``chdir <dir> <cmd> [<arg>...]`` + Change the current working directory and run a command. + +``compare_files <file1> <file2>`` + Check if ``<file1>`` is same as ``<file2>``. If files are the same, + then returns 0, if not it returns 1. + +``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_directory <dir>... <destination>`` + Copy directories to ``<destination>`` directory. + If ``<destination>`` directory does not exist it will be created. + +``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. + +``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. + +``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>...`` + Remove the file(s). If any of the listed files already do not + exist, the command returns a non-zero exit code, but no message + is logged. The ``-f`` option changes the behavior to return a + zero exit code (i.e. success) in such situations instead. + +``remove_directory <dir>`` + Remove a directory and its contents. If a directory does + not exist it will be silently ignored. + +``rename <oldname> <newname>`` + Rename a file or directory (on one volume). + +``server`` + Launch :manual:`cmake-server(7)` mode. + +``sleep <number>...`` + Sleep for given number of seconds. + +``tar [cxt][vf][zjJ] file.tar [<options>...] [--] [<file>...]`` + Create or extract a tar or zip archive. Options are: + + ``--`` + Stop interpreting options and treat all remaining arguments + as file names even if they start in ``-``. + ``--files-from=<file>`` + Read file names from the given file, one per line. + Blank lines are ignored. Lines may not start in ``-`` + except for ``--add-file=<name>`` to add files whose + names start in ``-``. + ``--mtime=<date>`` + Specify modification time recorded in tarball entries. + ``--format=<format>`` + Specify the format of the archive to be created. + Supported formats are: ``7zip``, ``gnutar``, ``pax``, + ``paxr`` (restricted pax, default), and ``zip``. + +``time <command> [<args>...]`` + Run command and display elapsed time. + +``touch <file>`` + Touch a file. + +``touch_nocreate <file>`` + Touch a file if it exists but do not create it. If a file does + not exist it will be silently ignored. + +``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. + +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. + +Find-Package Tool Mode +====================== + +CMake provides a helper for Makefile-based projects with the signature:: + + cmake --find-package <options>... + +This runs in a pkg-config like mode. + +Search a package using :command:`find_package()` and print the resulting flags +to stdout. This can be used to use cmake instead of pkg-config to find +installed libraries in plain Makefile-based projects or in autoconf-based +projects (via ``share/aclocal/cmake.m4``). + +.. 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. + +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..87aa38d --- /dev/null +++ b/Help/manual/cpack.1.rst @@ -0,0 +1,96 @@ +.. cmake-manual-description: CPack Command-Line Reference + +cpack(1) +******** + +Synopsis +======== + +.. parsed-literal:: + + cpack [<options>] + +Description +=========== + +The ``cpack`` executable is the CMake packaging program. +CMake projects use :command:`install` commands to define the contents of +packages which can be generated in various formats by this tool. +The :module:`CPack` module greatly simplifies the creation of the input file +used by ``cpack``, allowing most aspects of the packaging configuration to be +controlled directly from the CMake project's own ``CMakeLists.txt`` files. + +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. A generator is responsible for + generating the required inputs for a particular package system and invoking + that system's package creation tools. Possible generator names are specified + in the :manual:`Generators <cmake-generators(7)>` section of the manual and + the ``--help`` option lists the generators supported for the target platform. + If this option is not given, the :variable:`CPACK_GENERATOR` variable + determines the default set of generators that will be used. + +``-C <Configuration>`` + Specify the project configuration to be packaged (e.g. ``Debug``, + ``Release``, etc.). 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. + +``-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..9553d15 --- /dev/null +++ b/Help/manual/ctest.1.rst @@ -0,0 +1,1162 @@ +.. cmake-manual-description: CTest Command-Line Reference + +ctest(1) +******** + +.. contents:: + +Synopsis +======== + +.. parsed-literal:: + + ctest [<options>] + ctest <path-to-source> <path-to-build> --build-generator <generator> + [<options>...] [-- <build-options>...] [--test-command <test>] + 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 +ENABLE_TESTING and ADD_TEST commands have testing support. This +program will run the tests and report results. + +Options +======= + +``-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". + +``-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 environment variable + ``CTEST_OUTPUT_ON_FAILURE``. + +``-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 + environment variable ``CTEST_PARALLEL_LEVEL``. + + This option can be used with the :prop_test:`PROCESSORS` test property. + + See `Label and Subproject Summary`_. + +``--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 log file. + +``-N,--show-only`` + 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. + +``-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. + +``-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. + +``-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-until-fail <n>`` + Require each test to run ``<n>`` times without failing in order to pass. + + This is useful in finding sporadic failures in test cases. + +``--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-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 a global timeout on all tests. + + This option will set a global timeout on all tests that do not + already have a timeout set on them. + +``--stop-time <time>`` + Set a time at which all tests should stop running. + + Set a real time of day at which all tests should timeout. Example: + ``7:00:00 -0400``. Any time format understood by the curl date parser + is accepted. Local time is assumed if no timezone is specified. + +``--print-labels`` + Print all available test labels. + + This option will not run any tests, it will simply print the list of + all labels associated with the test set. + +.. include:: OPTIONS_HELP.txt + +.. _`Label and Subproject Summary`: + +Label and Subproject Summary +============================ + +CTest prints timing summary information for each label and subproject +associated with the tests run. The label time summary will not include labels +that are mapped to subprojects. + +When the :prop_test:`PROCESSORS` test property is set, CTest will display a +weighted test timing result in label and subproject summaries. The time is +reported with `sec*proc` instead of just `sec`. + +The weighted time summary reported for each label or subproject j is computed +as:: + + Weighted Time Summary for Label/Subproject j = + sum(raw_test_time[j,i] * num_processors[j,i], i=1...num_tests[j]) + + for labels/subprojects j=1...total + +where: + +* raw_test_time[j,i]: Wall-clock time for the ith test for the jth label or + subproject +* num_processors[j,i]: Value of the CTest PROCESSORS property for the ith test + for the jth label or subproject +* num_tests[j]: Number of tests associated with the jth 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`` + Override the make program chosen by CTest with a given one. + +``--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: + +``--track <track>`` + Specify the track to submit dashboard to + + Submit dashboard to specified track instead of default one. By + default, the dashboard is submitted to Nightly, Experimental, or + Continuous track, but by specifying this option, the track can be + arbitrary. + +``-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 moficiations 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`` + 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` + + +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 ``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: + +``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`` + +.. _`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`` + Specify the version of `CDash`_ on the server. + + * `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`` + The path on the dashboard server to send the submission. + + * `CTest Script`_ variable: :variable:`CTEST_DROP_LOCATION` + * :module:`CTest` module variable: ``DROP_LOCATION`` if set, + else ``CTEST_DROP_LOCATION`` + +``DropMethod`` + Specify the method by which results should be submitted to the + dashboard server. The value may be ``cp``, ``ftp``, ``http``, + ``https``, ``scp``, or ``xmlrpc`` (if CMake was built with + support for it). + + * `CTest Script`_ variable: :variable:`CTEST_DROP_METHOD` + * :module:`CTest` module variable: ``DROP_METHOD`` if set, + else ``CTEST_DROP_METHOD`` + +``DropSite`` + The dashboard server name + (for ``ftp``, ``http``, and ``https``, ``scp``, and ``xmlrpc``). + + * `CTest Script`_ variable: :variable:`CTEST_DROP_SITE` + * :module:`CTest` module variable: ``DROP_SITE`` if set, + else ``CTEST_DROP_SITE`` + +``DropSitePassword`` + The dashboard server login password, if any + (for ``ftp``, ``http``, and ``https``). + + * `CTest Script`_ variable: :variable:`CTEST_DROP_SITE_PASSWORD` + * :module:`CTest` module variable: ``DROP_SITE_PASSWORD`` if set, + else ``CTEST_DROP_SITE_PASWORD`` + +``DropSiteUser`` + The dashboard server login user name, if any + (for ``ftp``, ``http``, and ``https``). + + * `CTest Script`_ variable: :variable:`CTEST_DROP_SITE_USER` + * :module:`CTest` module variable: ``DROP_SITE_USER`` if set, + else ``CTEST_DROP_SITE_USER`` + +``IsCDash`` + Specify whether the dashboard server is `CDash`_ or an older + dashboard server implementation requiring ``TriggerSite``. + + * `CTest Script`_ variable: :variable:`CTEST_DROP_SITE_CDASH` + * :module:`CTest` module variable: ``CTEST_DROP_SITE_CDASH`` + +``ScpCommand`` + ``scp`` command-line tool to use when ``DropMethod`` is ``scp``. + + * `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 + +``TriggerSite`` + Legacy option to support older dashboard server implementations. + Not used when ``IsCDash`` is true. + + * `CTest Script`_ variable: :variable:`CTEST_TRIGGER_SITE` + * :module:`CTest` module variable: ``TRIGGER_SITE`` if set, + else ``CTEST_TRIGGER_SITE`` + +See Also +======== + +.. include:: LINKS.txt + +.. _`CDash`: http://cdash.org/ 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..8616098 --- /dev/null +++ b/Help/module/CPackArchive.rst @@ -0,0 +1,4 @@ +CPackArchive +------------ + +The documentation for the CPack Archive generator has moved here: :cpack_gen:`CPack Archive Generator` diff --git a/Help/module/CPackBundle.rst b/Help/module/CPackBundle.rst 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..a597002 --- /dev/null +++ b/Help/module/CPackDMG.rst @@ -0,0 +1,4 @@ +CPackDMG +-------- + +The documentation for the CPack DMG generator has moved here: :cpack_gen:`CPack DMG Generator` diff --git a/Help/module/CPackDeb.rst b/Help/module/CPackDeb.rst new file mode 100644 index 0000000..73e59a2 --- /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..69701b8 --- /dev/null +++ b/Help/module/CPackFreeBSD.rst @@ -0,0 +1,4 @@ +CPackFreeBSD +------------ + +The documentation for the CPack FreeBSD generator has moved here: :cpack_gen:`CPack FreeBSD Generator` diff --git a/Help/module/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..4f39b3a --- /dev/null +++ b/Help/module/CPackNuGet.rst @@ -0,0 +1,4 @@ +CPackNuGet +---------- + +The documentation for the CPack NuGet generator has moved here: :cpack_gen:`CPack NuGet Generator` diff --git a/Help/module/CPackPackageMaker.rst b/Help/module/CPackPackageMaker.rst 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..8cd9198 --- /dev/null +++ b/Help/module/CPackProductBuild.rst @@ -0,0 +1,4 @@ +CPackProductBuild +----------------- + +The documentation for the CPack productbuild generator has moved here: :cpack_gen:`CPack productbuild Generator` diff --git a/Help/module/CPackRPM.rst b/Help/module/CPackRPM.rst 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..e1d4a03 --- /dev/null +++ b/Help/module/CPackWIX.rst @@ -0,0 +1,4 @@ +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/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/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/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/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/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/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/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/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/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..23e7d6b39 --- /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..b9cd476 --- /dev/null +++ b/Help/module/UseJavaClassFilelist.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/UseJavaClassFilelist.cmake diff --git a/Help/module/UseJavaSymlinks.rst b/Help/module/UseJavaSymlinks.rst new file mode 100644 index 0000000..2fab8e8 --- /dev/null +++ b/Help/module/UseJavaSymlinks.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/UseJavaSymlinks.cmake 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..97ea633 --- /dev/null +++ b/Help/policy/CMP0000.rst @@ -0,0 +1,32 @@ +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 cmake_minimum_required +command at the top of your main CMakeLists.txt file: + +:: + + cmake_minimum_required(VERSION <major>.<minor>) + +where "<major>.<minor>" is the version of CMake you want to support +(such as "2.6"). The command will ensure that at least the given +version of CMake is running and help newer versions be compatible with +the project. See documentation of 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 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..09ad387 --- /dev/null +++ b/Help/policy/CMP0001.rst @@ -0,0 +1,21 @@ +CMP0001 +------- + +CMAKE_BACKWARDS_COMPATIBILITY should no longer be used. + +The OLD behavior is to check CMAKE_BACKWARDS_COMPATIBILITY and present +it to the user. The NEW behavior is to ignore +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 cmake_policy command. However, CMake must still check +CMAKE_BACKWARDS_COMPATIBILITY for projects written for CMake 2.4 and +below. + +This policy was introduced in CMake version 2.6.0. CMake version +|release| warns when the policy is not set and uses OLD behavior. Use +the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0002.rst b/Help/policy/CMP0002.rst new file mode 100644 index 0000000..7cc53ef --- /dev/null +++ b/Help/policy/CMP0002.rst @@ -0,0 +1,28 @@ +CMP0002 +------- + +Logical target names must be globally unique. + +Targets names created with add_executable, add_library, or +add_custom_target are logical build target names. Logical target +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 +OUTPUT_NAME target property to create two targets with the same +physical name while keeping logical names distinct. Custom targets +must simply have globally unique names (unless one uses the global +property ALLOW_DUPLICATE_CUSTOM_TARGETS with a Makefiles generator). + +This policy was introduced in CMake version 2.6.0. CMake version +|release| warns when the policy is not set and uses OLD behavior. Use +the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0003.rst b/Help/policy/CMP0003.rst new file mode 100644 index 0000000..16b0451 --- /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 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..55da4d2 --- /dev/null +++ b/Help/policy/CMP0004.rst @@ -0,0 +1,25 @@ +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 add_executable or add_library command. + +This policy was introduced in CMake version 2.6.0. CMake version +|release| warns when the policy is not set and uses OLD behavior. Use +the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0005.rst b/Help/policy/CMP0005.rst new file mode 100644 index 0000000..66d125f --- /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 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..d1b9ece --- /dev/null +++ b/Help/policy/CMP0006.rst @@ -0,0 +1,24 @@ +CMP0006 +------- + +Installing MACOSX_BUNDLE targets requires a BUNDLE DESTINATION. + +This policy determines whether the install(TARGETS) command must be +given a BUNDLE DESTINATION when asked to install a target with the +MACOSX_BUNDLE property set. CMake 2.4 and below did not distinguish +application bundles from normal executables when installing targets. +CMake 2.6 provides a BUNDLE option to the install(TARGETS) command +that specifies rules specific to application bundles on the Mac. +Projects should use this option when installing a target with the +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 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..3927645 --- /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 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..f1e2ddd --- /dev/null +++ b/Help/policy/CMP0008.rst @@ -0,0 +1,34 @@ +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 VS IDE and Xcode generators this used to +work by accident because CMake would always split off the library +directory and ask the linker to search for the library by name +(-lsomelib or somelib.lib). Despite the failure with Makefiles, some +projects have code like this and build only with VS and/or Xcode. +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 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..44baeb4 --- /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, FILE GLOB_RECURSE calls would follow through +symlinks, sometimes coming up with unexpectedly large result sets +because of symlinks to top level directories that contain hundreds of +thousands of files. + +This policy determines whether or not to follow symlinks encountered +during a FILE GLOB_RECURSE call. The OLD behavior for this policy is +to follow the symlinks. The NEW behavior for this policy is not to +follow the symlinks by default, but only if FOLLOW_SYMLINKS is given +as an additional argument to the FILE command. + +This policy was introduced in CMake version 2.6.2. CMake version +|release| warns when the policy is not set and uses OLD behavior. Use +the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0010.rst b/Help/policy/CMP0010.rst new file mode 100644 index 0000000..344d704 --- /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 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..d281e0e --- /dev/null +++ b/Help/policy/CMP0011.rst @@ -0,0 +1,24 @@ +CMP0011 +------- + +Included scripts do automatic cmake_policy PUSH and POP. + +In CMake 2.6.2 and below, CMake Policy settings in scripts loaded by +the include() and find_package() commands would affect the includer. +Explicit invocations of cmake_policy(PUSH) and cmake_policy(POP) were +required to isolate policy changes and protect the includer. While +some scripts intend to affect the policies of their includer, most do +not. In CMake 2.6.3 and above, include() and find_package() by +default PUSH and POP an entry on the policy stack around an included +script, but provide a NO_POLICY_SCOPE option to disable it. This +policy determines whether or not to imply NO_POLICY_SCOPE for +compatibility. The OLD behavior for this policy is to imply +NO_POLICY_SCOPE for include() and find_package() commands. The NEW +behavior for this policy is to allow the commands to do their default +cmake_policy PUSH and POP. + +This policy was introduced in CMake version 2.6.3. CMake version +|release| warns when the policy is not set and uses OLD behavior. Use +the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0012.rst b/Help/policy/CMP0012.rst new file mode 100644 index 0000000..85d64f4 --- /dev/null +++ b/Help/policy/CMP0012.rst @@ -0,0 +1,27 @@ +CMP0012 +------- + +if() recognizes numbers and boolean constants. + +In CMake versions 2.6.4 and lower the 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 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..2fabb89 --- /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 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..f1f7b77 --- /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 add_subdirectory() or subdirs(), +treating them as if present but empty. In CMake 2.8.0 and above this +policy determines whether or not the case is an error. The OLD +behavior for this policy is to silently ignore the problem. The NEW +behavior for this policy is to report an error. + +This policy was introduced in CMake version 2.8.0. CMake version +|release| warns when the policy is not set and uses OLD behavior. Use +the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0015.rst b/Help/policy/CMP0015.rst new file mode 100644 index 0000000..9a48e3d --- /dev/null +++ b/Help/policy/CMP0015.rst @@ -0,0 +1,19 @@ +CMP0015 +------- + +link_directories() treats paths relative to the source dir. + +In CMake 2.8.0 and lower the link_directories() command passed +relative paths unchanged to the linker. In CMake 2.8.1 and above the +link_directories() command prefers to interpret relative paths with +respect to CMAKE_CURRENT_SOURCE_DIR, which is consistent with +include_directories() and other commands. The OLD behavior for this +policy is to use relative paths verbatim in the linker command. The +NEW behavior for this policy is to convert relative paths to absolute +paths by appending the relative path to CMAKE_CURRENT_SOURCE_DIR. + +This policy was introduced in CMake version 2.8.1. CMake version +|release| warns when the policy is not set and uses OLD behavior. Use +the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0016.rst b/Help/policy/CMP0016.rst new file mode 100644 index 0000000..cc898c8 --- /dev/null +++ b/Help/policy/CMP0016.rst @@ -0,0 +1,15 @@ +CMP0016 +------- + +target_link_libraries() reports error if its only argument is not a target. + +In CMake 2.8.2 and lower the target_link_libraries() command silently +ignored if it was called with only one argument, and this argument +wasn't a valid target. In CMake 2.8.3 and above it reports an error +in this case. + +This policy was introduced in CMake version 2.8.3. CMake version +|release| warns when the policy is not set and uses OLD behavior. Use +the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0017.rst b/Help/policy/CMP0017.rst new file mode 100644 index 0000000..9f0f038 --- /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 include() or +find_package(), the files located in the CMake module directory are +preferred over the files in CMAKE_MODULE_PATH. This makes sure that +the modules belonging to CMake always get those files included which +they expect, and against which they were developed and tested. In all +other cases, the files found in CMAKE_MODULE_PATH still take +precedence over the ones in the CMake module directory. The OLD +behavior is to always prefer files from CMAKE_MODULE_PATH over files +from the CMake modules directory. + +This policy was introduced in CMake version 2.8.4. CMake version +|release| warns when the policy is not set and uses OLD behavior. Use +the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0018.rst b/Help/policy/CMP0018.rst new file mode 100644 index 0000000..a3a7a12 --- /dev/null +++ b/Help/policy/CMP0018.rst @@ -0,0 +1,34 @@ +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 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 +POSITION_INDEPENDENT_CODE property for all targets and use the +modified value of CMAKE_SHARED_LIBRARY_<Lang>_FLAGS for SHARED and +MODULE libraries. + +The NEW behavior for this policy is to ignore +CMAKE_SHARED_LIBRARY_<Lang>_FLAGS whether it is modified or not and +honor the POSITION_INDEPENDENT_CODE target property. + +This policy was introduced in CMake version 2.8.9. CMake version +|release| warns when the policy is not set and uses OLD behavior. Use +the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0019.rst b/Help/policy/CMP0019.rst new file mode 100644 index 0000000..2e3557d --- /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 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..75ca9de --- /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 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..3a792ca --- /dev/null +++ b/Help/policy/CMP0021.rst @@ -0,0 +1,20 @@ +CMP0021 +------- + +Fatal error on relative paths in INCLUDE_DIRECTORIES target property. + +CMake 2.8.10.2 and lower allowed the INCLUDE_DIRECTORIES target +property to contain relative paths. The base path for such relative +entries is not well defined. CMake 2.8.12 issues a FATAL_ERROR if the +INCLUDE_DIRECTORIES property contains a relative path. + +The OLD behavior for this policy is not to warn about relative paths +in the INCLUDE_DIRECTORIES target property. The NEW behavior for this +policy is to issue a FATAL_ERROR if INCLUDE_DIRECTORIES contains a +relative path. + +This policy was introduced in CMake version 2.8.12. CMake version +|release| warns when the policy is not set and uses OLD behavior. Use +the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0022.rst b/Help/policy/CMP0022.rst new file mode 100644 index 0000000..579d09a --- /dev/null +++ b/Help/policy/CMP0022.rst @@ -0,0 +1,39 @@ +CMP0022 +------- + +INTERFACE_LINK_LIBRARIES defines the link interface. + +CMake 2.8.11 constructed the 'link interface' of a target from +properties matching ``(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?``. +The modern way to specify config-sensitive content is to use generator +expressions and the ``IMPORTED_`` prefix makes uniform processing of the +link interface with generator expressions impossible. The +INTERFACE_LINK_LIBRARIES target property was introduced as a +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 INTERFACE_LINK_LIBRARIES +property will be processed and generated for the IMPORTED target by +default. A new option to the install(EXPORT) and export commands +allows export of the old-style properties for compatibility with +downstream users of CMake versions older than 2.8.12. The +target_link_libraries command will no longer populate the properties +matching LINK_INTERFACE_LIBRARIES(_<CONFIG>)? if this policy is NEW. + +Warning-free future-compatible code which works with CMake 2.8.7 onwards +can be written by using the ``LINK_PRIVATE`` and ``LINK_PUBLIC`` keywords +of :command:`target_link_libraries`. + +The OLD behavior for this policy is to ignore the +INTERFACE_LINK_LIBRARIES property for in-build targets. The NEW +behavior for this policy is to use the INTERFACE_LINK_LIBRARIES +property for in-build targets, and ignore the old properties matching +``(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?``. + +This policy was introduced in CMake version 2.8.12. CMake version +|release| warns when the policy is not set and uses OLD behavior. Use +the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0023.rst b/Help/policy/CMP0023.rst new file mode 100644 index 0000000..76a4900 --- /dev/null +++ b/Help/policy/CMP0023.rst @@ -0,0 +1,35 @@ +CMP0023 +------- + +Plain and keyword target_link_libraries signatures cannot be mixed. + +CMake 2.8.12 introduced the target_link_libraries signature using the +PUBLIC, PRIVATE, and INTERFACE keywords to generalize the LINK_PUBLIC +and LINK_PRIVATE keywords introduced in CMake 2.8.7. Use of +signatures with any of these keywords sets the link interface of a +target explicitly, even if empty. This produces confusing behavior +when used in combination with the historical behavior of the plain +target_link_libraries signature. For example, consider the code: + +:: + + 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 target_link_libraries for a single +target. + +The OLD behavior for this policy is to allow keyword and plain +target_link_libraries signatures to be mixed. The NEW behavior for +this policy is to not to allow mixing of the keyword and plain +signatures. + +This policy was introduced in CMake version 2.8.12. CMake version +|release| warns when the policy is not set and uses OLD behavior. Use +the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0024.rst b/Help/policy/CMP0024.rst new file mode 100644 index 0000000..272a56c --- /dev/null +++ b/Help/policy/CMP0024.rst @@ -0,0 +1,24 @@ +CMP0024 +------- + +Disallow include export result. + +CMake 2.8.12 and lower allowed use of the include() command with the +result of the export() command. This relies on the assumption that +the export() command has an immediate effect at configure-time during +a cmake run. Certain properties of targets are not fully determined +until later at generate-time, such as the link language and complete +list of link libraries. Future refactoring will change the effect of +the export() command to be executed at generate-time. Use ALIAS +targets instead in cases where the goal is to refer to targets by +another name. + +The OLD behavior for this policy is to allow including the result of +an export() command. The NEW behavior for this policy is not to +allow including the result of an export() command. + +This policy was introduced in CMake version 3.0. CMake version +|release| warns when the policy is not set and uses OLD behavior. Use +the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0025.rst b/Help/policy/CMP0025.rst new file mode 100644 index 0000000..62dd509 --- /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..3fe1374 --- /dev/null +++ b/Help/policy/CMP0026.rst @@ -0,0 +1,28 @@ +CMP0026 +------- + +Disallow use of the LOCATION property for build targets. + +CMake 2.8.12 and lower allowed reading the LOCATION target +property (and configuration-specific variants) to +determine the eventual location of build targets. This relies on the +assumption that all necessary information is available at +configure-time to determine the final location and filename of the +target. However, this property is not fully determined until later at +generate-time. At generate time, the $<TARGET_FILE> generator +expression can be used to determine the eventual LOCATION of a target +output. + +Code which reads the LOCATION target property can be ported to use the +$<TARGET_FILE> generator expression together with the file(GENERATE) +subcommand to generate a file containing the target location. + +The OLD behavior for this policy is to allow reading the LOCATION +properties from build-targets. The NEW behavior for this policy is to +not to allow reading the LOCATION properties from build-targets. + +This policy was introduced in CMake version 3.0. CMake version +|release| warns when the policy is not set and uses OLD behavior. Use +the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0027.rst b/Help/policy/CMP0027.rst new file mode 100644 index 0000000..28913ce --- /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 +INTERFACE_INCLUDE_DIRECTORIES, and a check at cmake time that the +entries in the INTERFACE_INCLUDE_DIRECTORIES of an IMPORTED target +actually exist. CMake 2.8.11 also introduced generator expression +support in the target_link_libraries command. However, if an imported +target is linked as a result of a generator expression evaluation, the +entries in the INTERFACE_INCLUDE_DIRECTORIES of that target were not +checked for existence as they should be. + +The OLD behavior of this policy is to report a warning if an entry in +the INTERFACE_INCLUDE_DIRECTORIES of a generator-expression +conditionally linked IMPORTED target does not exist. + +The NEW behavior of this policy is to report an error if an entry in +the INTERFACE_INCLUDE_DIRECTORIES of a generator-expression +conditionally linked IMPORTED target does not exist. + +This policy was introduced in CMake version 3.0. CMake version +|release| warns when the policy is not set and uses OLD behavior. Use +the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0028.rst b/Help/policy/CMP0028.rst new file mode 100644 index 0000000..be57125 --- /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 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 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..d1afeb7 --- /dev/null +++ b/Help/policy/CMP0037.rst @@ -0,0 +1,33 @@ +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 +targets 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 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..a306d90 --- /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 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..97d78ae --- /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 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..f027d5d --- /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 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..31314b2 --- /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 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..9e427c3 --- /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 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..02afa9f --- /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 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..c7e1a90f6 --- /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 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..576d1b1 --- /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 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..882dd78 --- /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..0e7e606 --- /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 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..a3ce4b1 --- /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 and extra layer of variable expansion +when evaluating source file names: + +.. code-block:: cmake + + set(a_source foo.c) + add_executable(foo \${a_source}) + +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 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..39e40b6 --- /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 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..6b679e5 --- /dev/null +++ b/Help/policy/CMP0051.rst @@ -0,0 +1,26 @@ +CMP0051 +------- + +List 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..0ea5ace --- /dev/null +++ b/Help/policy/CMP0052.rst @@ -0,0 +1,26 @@ +CMP0052 +------- + +Reject source and build dirs in installed 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..2620a60 --- /dev/null +++ b/Help/policy/CMP0053.rst @@ -0,0 +1,46 @@ +CMP0053 +------- + +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 ``+``. + 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..1e000a6 --- /dev/null +++ b/Help/policy/CMP0054.rst @@ -0,0 +1,52 @@ +CMP0054 +------- + +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..b3df758 --- /dev/null +++ b/Help/policy/CMP0055.rst @@ -0,0 +1,19 @@ +CMP0055 +------- + +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 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..3ba89d5 --- /dev/null +++ b/Help/policy/CMP0056.rst @@ -0,0 +1,34 @@ +CMP0056 +------- + +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..83db186 --- /dev/null +++ b/Help/policy/CMP0057.rst @@ -0,0 +1,16 @@ +CMP0057 +------- + +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..05efd48 --- /dev/null +++ b/Help/policy/CMP0058.rst @@ -0,0 +1,110 @@ +CMP0058 +------- + +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..bce982e --- /dev/null +++ b/Help/policy/CMP0059.rst @@ -0,0 +1,19 @@ +CMP0059 +------- + +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..8611aff --- /dev/null +++ b/Help/policy/CMP0060.rst @@ -0,0 +1,65 @@ +CMP0060 +------- + +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..cb2ac28 --- /dev/null +++ b/Help/policy/CMP0061.rst @@ -0,0 +1,26 @@ +CMP0061 +------- + +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..9047fff --- /dev/null +++ b/Help/policy/CMP0062.rst @@ -0,0 +1,29 @@ +CMP0062 +------- + +Disallow install() of 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..d736d06 --- /dev/null +++ b/Help/policy/CMP0063.rst @@ -0,0 +1,28 @@ +CMP0063 +------- + +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..e9a061b --- /dev/null +++ b/Help/policy/CMP0064.rst @@ -0,0 +1,17 @@ +CMP0064 +------- + +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..2ed775d --- /dev/null +++ b/Help/policy/CMP0065.rst @@ -0,0 +1,27 @@ +CMP0065 +------- + +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..d1dcb0e --- /dev/null +++ b/Help/policy/CMP0066.rst @@ -0,0 +1,27 @@ +CMP0066 +------- + +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..e6dda80 --- /dev/null +++ b/Help/policy/CMP0067.rst @@ -0,0 +1,37 @@ +CMP0067 +------- + +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..978a6e3 --- /dev/null +++ b/Help/policy/CMP0068.rst @@ -0,0 +1,35 @@ +CMP0068 +------- + +``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..0d5ddfd --- /dev/null +++ b/Help/policy/CMP0069.rst @@ -0,0 +1,92 @@ +CMP0069 +------- + +: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..0fb3617 --- /dev/null +++ b/Help/policy/CMP0070.rst @@ -0,0 +1,25 @@ +CMP0070 +------- + +Define :command:`file(GENERATE)` behavior for relative paths. + +CMake 3.10 and newer define that relative paths given to ``INPUT`` and +``OUTPUT`` arguments of ``file(GENERATE)`` are interpreted relative to the +current source and binary directories, respectively. CMake 3.9 and lower did +not define any behavior for relative paths but did not diagnose them either +and accidentally treated them relative to the process working directory. +Policy ``CMP0070`` provides compatibility with projects that used the old +undefined behavior. + +This policy affects behavior of relative paths given to ``file(GENERATE)``. +The ``OLD`` behavior for this policy is to treat the paths relative to the +working directory of CMake. The ``NEW`` behavior for this policy is to +interpret relative paths with respect to the current source or binary +directory of the caller. + +This policy was introduced in CMake version 3.10. CMake version +|release| warns when the policy is not set and uses ``OLD`` behavior. +Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` +explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0071.rst b/Help/policy/CMP0071.rst new file mode 100644 index 0000000..ee33aa1 --- /dev/null +++ b/Help/policy/CMP0071.rst @@ -0,0 +1,42 @@ +CMP0071 +------- + +Let :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` process +:prop_sf:`GENERATED` files. + +Since version 3.10, CMake processes **regular** and :prop_sf:`GENERATED` +source files in :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`. +In earlier CMake versions, only **regular** source files were processed. +:prop_sf:`GENERATED` source files were ignored silently. + +This policy affects how source files that are :prop_sf:`GENERATED` +get treated in :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`. + +The ``OLD`` behavior for this policy is to ignore :prop_sf:`GENERATED` +source files in :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`. + +The ``NEW`` behavior for this policy is to process :prop_sf:`GENERATED` +source files in :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` just like regular +source files. + +.. note:: + + To silence the CMP0071 warning source files can be excluded from + :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` processing by setting the + source file properties :prop_sf:`SKIP_AUTOMOC`, :prop_sf:`SKIP_AUTOUIC` or + :prop_sf:`SKIP_AUTOGEN`. + +Source skip example:: + + # ... + set_property(SOURCE /path/to/file1.h PROPERTY SKIP_AUTOMOC ON) + set_property(SOURCE /path/to/file2.h PROPERTY SKIP_AUTOUIC ON) + set_property(SOURCE /path/to/file3.h PROPERTY SKIP_AUTOGEN ON) + # ... + +This policy was introduced in CMake version 3.10. CMake version +|release| warns when the policy is not set and uses ``OLD`` behavior. +Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` +explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0072.rst b/Help/policy/CMP0072.rst new file mode 100644 index 0000000..3abbad7 --- /dev/null +++ b/Help/policy/CMP0072.rst @@ -0,0 +1,26 @@ +CMP0072 +------- + +:module:`FindOpenGL` prefers GLVND by default when available. + +The :module:`FindOpenGL` module provides an ``OpenGL::GL`` target and an +``OPENGL_LIBRARIES`` variable for projects to use for legacy GL interfaces. +When both a legacy GL library (e.g. ``libGL.so``) and GLVND libraries +for OpenGL and GLX (e.g. ``libOpenGL.so`` and ``libGLX.so``) are available, +the module must choose between them. It documents an ``OpenGL_GL_PREFERENCE`` +variable that can be used to specify an explicit preference. When no such +preference is set, the module must choose a default preference. + +CMake 3.11 and above prefer to choose GLVND libraries. This policy provides +compatibility with projects that expect the legacy GL library to be used. + +The ``OLD`` behavior for this policy is to set ``OpenGL_GL_PREFERENCE`` to +``LEGACY``. The ``NEW`` behavior for this policy is to set +``OpenGL_GL_PREFERENCE`` to ``GLVND``. + +This policy was introduced in CMake version 3.11. CMake version +|release| warns when the policy is not set and uses ``OLD`` behavior. +Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` +explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0073.rst b/Help/policy/CMP0073.rst new file mode 100644 index 0000000..9bfa0e9 --- /dev/null +++ b/Help/policy/CMP0073.rst @@ -0,0 +1,25 @@ +CMP0073 +------- + +Do not produce legacy ``_LIB_DEPENDS`` cache entries. + +Ancient CMake versions once used ``<tgt>_LIB_DEPENDS`` cache entries to +propagate library link dependencies. This has long been done by other +means, leaving the :command:`export_library_dependencies` command as the +only user of these values. That command has long been disallowed by +policy :policy:`CMP0033`, but the ``<tgt>_LIB_DEPENDS`` cache entries +were left for compatibility with possible non-standard uses by projects. + +CMake 3.12 and above now prefer to not produce these cache entries +at all. This policy provides compatibility with projects that have +not been updated to avoid using them. + +The ``OLD`` behavior for this policy is to set ``<tgt>_LIB_DEPENDS`` cache +entries. The ``NEW`` behavior for this policy is to not set them. + +This policy was introduced in CMake version 3.12. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +Unlike most policies, CMake version |release| does *not* warn +when this policy is not set and simply uses ``OLD`` behavior. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0074.rst b/Help/policy/CMP0074.rst new file mode 100644 index 0000000..896936b --- /dev/null +++ b/Help/policy/CMP0074.rst @@ -0,0 +1,23 @@ +CMP0074 +------- + +:command:`find_package` uses ``<PackageName>_ROOT`` variables. + +In CMake 3.12 and above the :command:`find_package(<PackageName>)` command now +searches prefixes specified by the :variable:`<PackageName>_ROOT` CMake +variable and the :envvar:`<PackageName>_ROOT` environment variable. +Package roots are maintained as a stack so nested calls to all ``find_*`` +commands inside find modules 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..aa5c3f7 --- /dev/null +++ b/Help/policy/CMP0075.rst @@ -0,0 +1,26 @@ +CMP0075 +------- + +Include file check macros honor ``CMAKE_REQUIRED_LIBRARIES``. + +In CMake 3.12 and above, the + +* ``check_include_file`` macro in the :module:`CheckIncludeFile` module, the +* ``check_include_file_cxx`` macro in the + :module:`CheckIncludeFileCXX` module, and the +* ``check_include_files`` macro in the :module:`CheckIncludeFiles` module + +now prefer to link the check executable to the libraries listed in the +``CMAKE_REQUIRED_LIBRARIES`` variable. This policy provides compatibility +with projects that have not been updated to expect this behavior. + +The ``OLD`` behavior for this policy is to ignore ``CMAKE_REQUIRED_LIBRARIES`` +in the include file check macros. The ``NEW`` behavior of this policy is to +honor ``CMAKE_REQUIRED_LIBRARIES`` in the include file check macros. + +This policy was introduced in CMake version 3.12. CMake version +|release| warns when the policy is not set and uses ``OLD`` behavior. +Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` +explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0076.rst b/Help/policy/CMP0076.rst new file mode 100644 index 0000000..dd25f80 --- /dev/null +++ b/Help/policy/CMP0076.rst @@ -0,0 +1,26 @@ +CMP0076 +------- + +The :command:`target_sources` command converts relative paths to absolute. + +In CMake 3.13 and above, the :command:`target_sources` command now converts +relative source file paths to absolute paths in the following cases: + +* Source files are added to the target's :prop_tgt:`INTERFACE_SOURCES` + property. +* The target's :prop_tgt:`SOURCE_DIR` property differs from + :variable:`CMAKE_CURRENT_SOURCE_DIR`. + +A path that begins with a generator expression is always left unmodified. + +This policy provides compatibility with projects that have not been updated +to expect this behavior. The ``OLD`` behavior for this policy is to leave +all relative source file paths unmodified. The ``NEW`` behavior of this +policy is to convert relative paths to absolute according to above rules. + +This policy was introduced in CMake version 3.13. CMake version +|release| warns when the policy is not set and uses ``OLD`` behavior. +Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` +explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0077.rst b/Help/policy/CMP0077.rst new file mode 100644 index 0000000..8efe198 --- /dev/null +++ b/Help/policy/CMP0077.rst @@ -0,0 +1,16 @@ +CMP0077 +------- + +:command:`option` honors normal variables. + +The ``OLD`` behavior for this policy is to clear any existing normal variables +with the same name. The ``NEW`` behavior for this policy is to not create +a cache entry or modify any existing normal variables if a normal variable +with the same name already 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..54cdc9c --- /dev/null +++ b/Help/policy/CMP0078.rst @@ -0,0 +1,22 @@ +CMP0078 +------- + +Starting with CMake 3.13, :module:`UseSWIG` generates now standard target +names. This policy provides compatibility with projects that expect the legacy +behavior. + +The ``OLD`` behavior for this policy relies on +``UseSWIG_TARGET_NAME_PREFERENCE`` variable that can be used to specify an +explicit preference. The value may be one of: + +* ``LEGACY``: legacy strategy is applied. Variable + ``SWIG_MODULE_<name>_REAL_NAME`` must be used to get real target name. + This is the default if not specified. +* ``STANDARD``: target name matches specified name. + +This policy was introduced in CMake version 3.13. CMake version +|release| warns when the policy is not set and uses ``OLD`` behavior. +Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` +explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0079.rst b/Help/policy/CMP0079.rst new file mode 100644 index 0000000..0244d6c --- /dev/null +++ b/Help/policy/CMP0079.rst @@ -0,0 +1,40 @@ +CMP0079 +------- + +:command:`target_link_libraries` allows use with targets in other directories. + +Prior to CMake 3.13 the :command:`target_link_libraries` command did not +accept targets not created in the calling directory as its first argument +for calls that update the :prop_tgt:`LINK_LIBRARIES` of the target itself. +It did accidentally accept targets from other directories on calls that +only update the :prop_tgt:`INTERFACE_LINK_LIBRARIES`, but would simply +add entries to the property as if the call were made in the original +directory. Thus link interface libraries specified this way were always +looked up by generators in the scope of the original target rather than +in the scope that called :command:`target_link_libraries`. + +CMake 3.13 now allows the :command:`target_link_libraries` command to +be called from any directory to add link dependencies and link interface +libraries to targets created in other directories. The entries are added +to :prop_tgt:`LINK_LIBRARIES` and :prop_tgt:`INTERFACE_LINK_LIBRARIES` +using a special (internal) suffix to tell the generators to look up the +names in the calling scope rather than the scope that created the target. + +This policy provides compatibility with projects that already use +:command:`target_link_libraries` with the ``INTERFACE`` keyword +on a target in another directory to add :prop_tgt:`INTERFACE_LINK_LIBRARIES` +entries to be looked up in the target's directory. Such projects should +be updated to be aware of the new scoping rules in that case. + +The ``OLD`` behavior of this policy is to disallow +:command:`target_link_libraries` calls naming targets from another directory +except in the previously accidentally allowed case of using the ``INTERFACE`` +keyword only. The ``NEW`` behavior of this policy is to allow all such +calls but use the new scoping rules. + +This policy was introduced in CMake version 3.13. CMake version +|release| warns when the policy is not set and uses ``OLD`` behavior. +Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` +explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0080.rst b/Help/policy/CMP0080.rst new file mode 100644 index 0000000..5ce9591 --- /dev/null +++ b/Help/policy/CMP0080.rst @@ -0,0 +1,25 @@ +CMP0080 +------- + +:module:`BundleUtilities` cannot be included at configure time. + +The macros provided by :module:`BundleUtilities` are intended to be invoked +at install time rather than at configure time, because they depend on the +listed targets already existing at the time they are invoked. If they are +invoked at configure time, the targets haven't been built yet, and the +commands will fail. + +This policy restricts the inclusion of :module:`BundleUtilities` to +``cmake -P`` style scripts and install rules. Specifically, it looks for the +presence of :variable:`CMAKE_GENERATOR` and throws a fatal error if it exists. + +The ``OLD`` behavior of this policy is to allow :module:`BundleUtilities` to +be included at configure time. The ``NEW`` behavior of this policy is to +disallow such inclusion. + +This policy was introduced in CMake version 3.13. CMake version +|release| warns when the policy is not set and uses ``OLD`` behavior. +Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` +explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0081.rst b/Help/policy/CMP0081.rst new file mode 100644 index 0000000..d3b2872 --- /dev/null +++ b/Help/policy/CMP0081.rst @@ -0,0 +1,22 @@ +CMP0081 +------- + +Relative paths not allowed in :prop_tgt:`LINK_DIRECTORIES` target property. + +CMake 3.12 and lower allowed the :prop_dir:`LINK_DIRECTORIES` directory +property to contain relative paths. The base path for such relative +entries is not well defined. CMake 3.13 and later will issue a +``FATAL_ERROR`` if the :prop_tgt:`LINK_DIRECTORIES` target property +(which is initialized by the :prop_dir:`LINK_DIRECTORIES` directory property) +contains a relative path. + +The ``OLD`` behavior for this policy is not to warn about relative paths +in the :prop_tgt:`LINK_DIRECTORIES` target property. The ``NEW`` behavior for +this policy is to issue a ``FATAL_ERROR`` if :prop_tgt:`LINK_DIRECTORIES` +contains a relative path. + +This policy was introduced in CMake version 3.13. CMake version +|release| warns when the policy is not set and uses ``OLD`` behavior. Use +the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/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..36280d2 --- /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 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..a0a4f73 --- /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 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..2f8e32e --- /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..eb75c2a --- /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 (set, option, 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_MAKE_CLEAN_FILES.rst b/Help/prop_dir/ADDITIONAL_MAKE_CLEAN_FILES.rst new file mode 100644 index 0000000..e32eed3 --- /dev/null +++ b/Help/prop_dir/ADDITIONAL_MAKE_CLEAN_FILES.rst @@ -0,0 +1,7 @@ +ADDITIONAL_MAKE_CLEAN_FILES +--------------------------- + +Additional files to clean during the make clean stage. + +A list of files that will be cleaned as a part of the "make clean" +stage. diff --git a/Help/prop_dir/BINARY_DIR.rst b/Help/prop_dir/BINARY_DIR.rst new file mode 100644 index 0000000..597c79a --- /dev/null +++ b/Help/prop_dir/BINARY_DIR.rst @@ -0,0 +1,5 @@ +BINARY_DIR +---------- + +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..da907cb --- /dev/null +++ b/Help/prop_dir/BUILDSYSTEM_TARGETS.rst @@ -0,0 +1,11 @@ +BUILDSYSTEM_TARGETS +------------------- + +This read-only directory property contains a +:ref:`;-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..877deb0 --- /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:`;-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..1aa24e4 --- /dev/null +++ b/Help/prop_dir/EXCLUDE_FROM_ALL.rst @@ -0,0 +1,9 @@ +EXCLUDE_FROM_ALL +---------------- + +Exclude the directory from the all target of its parent. + +A property on a directory that indicates if its targets are excluded +from the default build target. If it is not, then with a Makefile for +example typing make will cause the targets to be built. The same +concept applies to the default build of other generators. 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..993f620 --- /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..32520865 --- /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..de27d90 --- /dev/null +++ b/Help/prop_dir/LABELS.rst @@ -0,0 +1,13 @@ +LABELS +------ + +Specify a list of text labels associated with a directory and all of its +subdirectories. This is equivalent to setting the :prop_tgt:`LABELS` target +property and the :prop_test:`LABELS` test property on all targets and tests in +the current directory and subdirectories. Note: Launchers must enabled to +propagate labels to targets. + +The :variable:`CMAKE_DIRECTORY_LABELS` variable can be used to initialize this +property. + +The list is reported in dashboard submissions. diff --git a/Help/prop_dir/LINK_DIRECTORIES.rst b/Help/prop_dir/LINK_DIRECTORIES.rst new file mode 100644 index 0000000..f9fb815 --- /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:`;-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..15c555f --- /dev/null +++ b/Help/prop_dir/LINK_OPTIONS.rst @@ -0,0 +1,17 @@ +LINK_OPTIONS +------------ + +List of options to use for the link step of shared library, module +and executable targets. + +This property holds a :ref:`;-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..e4feada --- /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 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..ac98c3b --- /dev/null +++ b/Help/prop_dir/SOURCE_DIR.rst @@ -0,0 +1,5 @@ +SOURCE_DIR +---------- + +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..2c2ea77 --- /dev/null +++ b/Help/prop_dir/SUBDIRECTORIES.rst @@ -0,0 +1,15 @@ +SUBDIRECTORIES +-------------- + +This read-only directory property contains a +:ref:`;-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..91acd3e --- /dev/null +++ b/Help/prop_dir/TESTS.rst @@ -0,0 +1,7 @@ +TESTS +----- + +List of tests. + +This read-only property holds a :ref:`;-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..c3e4602 --- /dev/null +++ b/Help/prop_dir/TEST_INCLUDE_FILES.rst @@ -0,0 +1,7 @@ +TEST_INCLUDE_FILES +------------------ + +A list of cmake files that will be included when ctest is run. + +If you specify ``TEST_INCLUDE_FILES``, those files will be included and +processed when ctest is run on the directory. diff --git a/Help/prop_dir/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..814bd5f --- /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 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..f70e9f1 --- /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 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..04441b6 --- /dev/null +++ b/Help/prop_dir/VS_STARTUP_PROJECT.rst @@ -0,0 +1,18 @@ +VS_STARTUP_PROJECT +------------------ + +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 correpsonding 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..8fab503 --- /dev/null +++ b/Help/prop_gbl/ALLOW_DUPLICATE_CUSTOM_TARGETS.rst @@ -0,0 +1,19 @@ +ALLOW_DUPLICATE_CUSTOM_TARGETS +------------------------------ + +Allow duplicate custom targets to be created. + +Normally CMake requires that all targets built in a project have +globally unique logical names (see policy CMP0002). This is necessary +to generate meaningful project file names in Xcode and VS IDE +generators. It also allows the target names to be referenced +unambiguously. + +Makefile generators are capable of supporting duplicate custom target +names. For projects that care only about Makefile generators and do +not wish to support Xcode or VS IDE generators, one may set this +property to true to allow duplicate custom targets. The property +allows multiple add_custom_target command calls in different +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..d294eb1 --- /dev/null +++ b/Help/prop_gbl/AUTOGEN_SOURCE_GROUP.rst @@ -0,0 +1,15 @@ +AUTOGEN_SOURCE_GROUP +-------------------- + +Name of the :command:`source_group` for :prop_tgt:`AUTOMOC` and +:prop_tgt:`AUTORCC` generated files. + +Files generated by :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTORCC` are not always +known at configure time and therefore can't be passed to +:command:`source_group`. +:prop_gbl:`AUTOGEN_SOURCE_GROUP` an be used instead to generate or select +a source group for :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTORCC` generated files. + +For :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTORCC` specific overrides see +:prop_gbl:`AUTOMOC_SOURCE_GROUP` and :prop_gbl:`AUTORCC_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..2455dc7 --- /dev/null +++ b/Help/prop_gbl/AUTOMOC_SOURCE_GROUP.rst @@ -0,0 +1,7 @@ +AUTOMOC_SOURCE_GROUP +-------------------- + +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..65ea95b --- /dev/null +++ b/Help/prop_gbl/AUTORCC_SOURCE_GROUP.rst @@ -0,0 +1,7 @@ +AUTORCC_SOURCE_GROUP +-------------------- + +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/CMAKE_CXX_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst new file mode 100644 index 0000000..262a67c --- /dev/null +++ b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst @@ -0,0 +1,318 @@ +CMAKE_CXX_KNOWN_FEATURES +------------------------ + +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: + +``cxx_std_98`` + Compiler mode is aware of C++ 98. + +``cxx_std_11`` + Compiler mode is aware of C++ 11. + +``cxx_std_14`` + Compiler mode is aware of C++ 14. + +``cxx_std_17`` + Compiler mode is aware of C++ 17. + +``cxx_std_20`` + Compiler mode is aware of C++ 20. + +``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_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_attribute_deprecated`` + ``[[deprecated]]`` attribute, as defined in N3760_. + + .. _N3760: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3760.html + +``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_binary_literals`` + Binary literals, as defined in N3472_. + + .. _N3472: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3472.pdf + +``cxx_constexpr`` + Constant expressions, as defined in N2235_. + + .. _N2235: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2235.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_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_decltype_auto`` + ``decltype(auto)`` semantics, as defined in N3638_. + + .. _N3638: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3638.html + +``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_digit_separators`` + Digit separators, as defined in N3781_. + + .. _N3781: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3781.pdf + +``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_generic_lambdas`` + Generic lambdas, as defined in N3649_. + + .. _N3649: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3649.html + +``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_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_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_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_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_variable_templates`` + Variable templates, as defined in N3651_. + + .. _N3651: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3651.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 + +``cxx_template_template_parameters`` + Template template parameters, as defined in ``ISO/IEC 14882:1998``. 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..3707fef --- /dev/null +++ b/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst @@ -0,0 +1,35 @@ +CMAKE_C_KNOWN_FEATURES +---------------------- + +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 aware of C 90. + +``c_std_99`` + Compiler mode is aware of C 99. + +``c_std_11`` + Compiler mode is aware of C 11. + +``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/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..111cdf6 --- /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..50c41a9 --- /dev/null +++ b/Help/prop_gbl/ECLIPSE_EXTRA_CPROJECT_CONTENTS.rst @@ -0,0 +1,12 @@ +ECLIPSE_EXTRA_CPROJECT_CONTENTS +------------------------------- + +Additional contents to be inserted into the generated Eclipse cproject file. + +The cproject file defines the CDT specific information. Some third party IDE's +are based on Eclipse with the addition of other information specific to that IDE. +Through this property, it is possible to add this additional contents to +the generated project. +It is expected to contain valid XML. + +Also see the :prop_gbl:`ECLIPSE_EXTRA_NATURES` property. diff --git a/Help/prop_gbl/ECLIPSE_EXTRA_NATURES.rst b/Help/prop_gbl/ECLIPSE_EXTRA_NATURES.rst 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..b03da5a --- /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..8396026 --- /dev/null +++ b/Help/prop_gbl/FIND_LIBRARY_USE_LIB32_PATHS.rst @@ -0,0 +1,12 @@ +FIND_LIBRARY_USE_LIB32_PATHS +---------------------------- + +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..b87b09b --- /dev/null +++ b/Help/prop_gbl/FIND_LIBRARY_USE_LIBX32_PATHS.rst @@ -0,0 +1,12 @@ +FIND_LIBRARY_USE_LIBX32_PATHS +----------------------------- + +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..b8ec8a6 --- /dev/null +++ b/Help/prop_gbl/GENERATOR_IS_MULTI_CONFIG.rst @@ -0,0 +1,9 @@ +GENERATOR_IS_MULTI_CONFIG +------------------------- + +Read-only property that is true on multi-configuration generators. + +True when using a multi-configuration generator +(such as :ref:`Visual Studio Generators` or :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..b904f7a --- /dev/null +++ b/Help/prop_gbl/JOB_POOLS.rst @@ -0,0 +1,26 @@ +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`. + +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..275b074 --- /dev/null +++ b/Help/prop_gbl/TARGET_MESSAGES.rst @@ -0,0 +1,20 @@ +TARGET_MESSAGES +--------------- + +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..a1b4ccb --- /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 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..9a6086e --- /dev/null +++ b/Help/prop_gbl/XCODE_EMIT_EFFECTIVE_PLATFORM_NAME.rst @@ -0,0 +1,24 @@ +XCODE_EMIT_EFFECTIVE_PLATFORM_NAME +---------------------------------- + +Control emission of ``EFFECTIVE_PLATFORM_NAME`` by the Xcode generator. + +It is required for building the same target with multiple SDKs. A +common use case is the parallel use of ``iphoneos`` and +``iphonesimulator`` SDKs. + +Three different states possible that control when the Xcode generator +emits the ``EFFECTIVE_PLATFORM_NAME`` variable: + +- 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..11f2c03 --- /dev/null +++ b/Help/prop_inst/CPACK_DESKTOP_SHORTCUTS.rst @@ -0,0 +1,7 @@ +CPACK_DESKTOP_SHORTCUTS +----------------------- + +Species a list of shortcut names that should be created on the Desktop +for this file. + +The property is currently only supported by the WIX generator. diff --git a/Help/prop_inst/CPACK_NEVER_OVERWRITE.rst b/Help/prop_inst/CPACK_NEVER_OVERWRITE.rst new file mode 100644 index 0000000..11f44d0 --- /dev/null +++ b/Help/prop_inst/CPACK_NEVER_OVERWRITE.rst @@ -0,0 +1,6 @@ +CPACK_NEVER_OVERWRITE +--------------------- + +Request that this file not be overwritten on install or reinstall. + +The property is currently only supported by the WIX generator. diff --git a/Help/prop_inst/CPACK_PERMANENT.rst b/Help/prop_inst/CPACK_PERMANENT.rst new file mode 100644 index 0000000..5e191d0 --- /dev/null +++ b/Help/prop_inst/CPACK_PERMANENT.rst @@ -0,0 +1,6 @@ +CPACK_PERMANENT +--------------- + +Request that this file not be removed on uninstall. + +The property is currently only supported by the 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..8a16022 --- /dev/null +++ b/Help/prop_inst/CPACK_STARTUP_SHORTCUTS.rst @@ -0,0 +1,7 @@ +CPACK_STARTUP_SHORTCUTS +----------------------- + +Species a list of shortcut names that should be created in the Startup folder +for this file. + +The property is currently only supported by the WIX generator. 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..d30ea39 --- /dev/null +++ b/Help/prop_inst/CPACK_START_MENU_SHORTCUTS.rst @@ -0,0 +1,7 @@ +CPACK_START_MENU_SHORTCUTS +-------------------------- + +Species a list of shortcut names that should be created in the Start Menu +for this file. + +The property is currently only supported by the WIX generator. diff --git a/Help/prop_inst/CPACK_WIX_ACL.rst b/Help/prop_inst/CPACK_WIX_ACL.rst new file mode 100644 index 0000000..4e13ec4 --- /dev/null +++ b/Help/prop_inst/CPACK_WIX_ACL.rst @@ -0,0 +1,19 @@ +CPACK_WIX_ACL +------------- + +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 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..8d2108c --- /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 "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. + +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..8487076 --- /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 COMPILE_DEFINITIONS. +Note that Xcode does not support per-configuration source file flags +so this property will be ignored by the 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..3b2bc8d --- /dev/null +++ b/Help/prop_sf/COMPILE_OPTIONS.rst @@ -0,0 +1,21 @@ +COMPILE_OPTIONS +--------------- + +List of additional options to pass to the compiler. + +This property holds a :ref:`;-list <CMake Language Lists>` of options +and will be added to the list of compile flags when this +source file builds. Use :prop_sf:`COMPILE_DEFINITIONS` to pass +additional preprocessor definitions and :prop_sf:`INCLUDE_DIRECTORIES` to pass +additional include directories. + +Contents of ``COMPILE_OPTIONS`` may use "generator expressions" with the +syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual +for available expressions. However, :generator:`Xcode` +does not support per-config per-source settings, so expressions +that depend on the build configuration are not allowed with that +generator. + +.. note:: + + This property should be preferred over the :prop_sf:`COMPILE_FLAGS` property. diff --git a/Help/prop_sf/EXTERNAL_OBJECT.rst b/Help/prop_sf/EXTERNAL_OBJECT.rst new file mode 100644 index 0000000..efa0e9b --- /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..69e34aa --- /dev/null +++ b/Help/prop_sf/Fortran_FORMAT.rst @@ -0,0 +1,9 @@ +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 Fortran_FORMAT +property if all source files in a target share the same format. diff --git a/Help/prop_sf/GENERATED.rst b/Help/prop_sf/GENERATED.rst new file mode 100644 index 0000000..d430ee2 --- /dev/null +++ b/Help/prop_sf/GENERATED.rst @@ -0,0 +1,23 @@ +GENERATED +--------- + +Is this source file generated as part of the build or CMake process. + +Tells the internal CMake engine that a source file is generated by an outside +process such as another build step, or the execution of CMake itself. This +information is then used to exempt the file from any existence or validity +checks. Generated files are created by the execution of commands such as +:command:`add_custom_command` and :command:`file(GENERATE)`. + +When a generated file created by an :command:`add_custom_command` command +is explicitly listed as a source file for any target in the same +directory scope (which usually means the same ``CMakeLists.txt`` file), +CMake will automatically create a dependency to make sure the file is +generated before building that target. + +Generated sources may be hidden in some IDE tools, while in others they might +be shown. For the special case of sources generated by CMake's :prop_tgt:`AUTOMOC` +or :prop_tgt:`AUTORCC` functionality, the :prop_gbl:`AUTOGEN_SOURCE_GROUP`, +:prop_gbl:`AUTOMOC_SOURCE_GROUP` and :prop_gbl:`AUTORCC_SOURCE_GROUP` target +properties may influence where the generated sources are grouped in the project's +file lists. diff --git a/Help/prop_sf/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..55780e5 --- /dev/null +++ b/Help/prop_sf/INCLUDE_DIRECTORIES.rst @@ -0,0 +1,18 @@ +INCLUDE_DIRECTORIES +------------------- + +List of preprocessor include file search directories. + +This property holds a :ref:`;-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..d6167e5 --- /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..e1c1069 --- /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..97bfa20 --- /dev/null +++ b/Help/prop_sf/LANGUAGE.rst @@ -0,0 +1,10 @@ +LANGUAGE +-------- + +What programming language is the file. + +A property that can be set to indicate what programming language the +source file is. If it is not set the language is determined based on +the file extension. Typical values are CXX C etc. Setting this +property for a file means this file will be compiled. Do not set this +for headers or files that should not be compiled. diff --git a/Help/prop_sf/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..1d24960 --- /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:`;-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..6a28553 --- /dev/null +++ b/Help/prop_sf/OBJECT_OUTPUTS.rst @@ -0,0 +1,9 @@ +OBJECT_OUTPUTS +-------------- + +Additional outputs for a Makefile rule. + +Additional outputs created by compilation of this source file. If any +of these outputs is missing the object will be recompiled. This is +supported only on Makefile generators and will be ignored on other +generators. diff --git a/Help/prop_sf/SKIP_AUTOGEN.rst b/Help/prop_sf/SKIP_AUTOGEN.rst new file mode 100644 index 0000000..f31185a --- /dev/null +++ b/Help/prop_sf/SKIP_AUTOGEN.rst @@ -0,0 +1,17 @@ +SKIP_AUTOGEN +------------ + +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..a929448 --- /dev/null +++ b/Help/prop_sf/SKIP_AUTOMOC.rst @@ -0,0 +1,15 @@ +SKIP_AUTOMOC +------------ + +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..bccccfc --- /dev/null +++ b/Help/prop_sf/SKIP_AUTORCC.rst @@ -0,0 +1,15 @@ +SKIP_AUTORCC +------------ + +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..8c962db --- /dev/null +++ b/Help/prop_sf/SKIP_AUTOUIC.rst @@ -0,0 +1,20 @@ +SKIP_AUTOUIC +------------ + +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/SYMBOLIC.rst b/Help/prop_sf/SYMBOLIC.rst new file mode 100644 index 0000000..c7d0b26 --- /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/VS_COPY_TO_OUT_DIR.rst b/Help/prop_sf/VS_COPY_TO_OUT_DIR.rst new file mode 100644 index 0000000..16c8d83 --- /dev/null +++ b/Help/prop_sf/VS_COPY_TO_OUT_DIR.rst @@ -0,0 +1,6 @@ +VS_COPY_TO_OUT_DIR +------------------ + +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..d42159f --- /dev/null +++ b/Help/prop_sf/VS_CSHARP_tagname.rst @@ -0,0 +1,19 @@ +VS_CSHARP_<tagname> +------------------- + +Visual Studio and CSharp source-file-specific configuration. + +Tell the Visual Studio generator to set the source file tag +``<tagname>`` to a given value in the generated Visual Studio CSharp +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..9fb3ba3 --- /dev/null +++ b/Help/prop_sf/VS_DEPLOYMENT_CONTENT.rst @@ -0,0 +1,11 @@ +VS_DEPLOYMENT_CONTENT +--------------------- + +Mark a source file as content for deployment with a Windows Phone or +Windows Store application when built with a Visual Studio generator. +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..303db95 --- /dev/null +++ b/Help/prop_sf/VS_DEPLOYMENT_LOCATION.rst @@ -0,0 +1,8 @@ +VS_DEPLOYMENT_LOCATION +---------------------- + +Specifies the deployment location for a content source file with a Windows +Phone or Windows Store application when built with a Visual Studio generator. +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..30f471d --- /dev/null +++ b/Help/prop_sf/VS_INCLUDE_IN_VSIX.rst @@ -0,0 +1,6 @@ +VS_INCLUDE_IN_VSIX +------------------ + +Boolean property to specify if the file should be included within a VSIX +extension package. This is needed for development of Visual Studio +extensions. diff --git a/Help/prop_sf/VS_RESOURCE_GENERATOR.rst b/Help/prop_sf/VS_RESOURCE_GENERATOR.rst new file mode 100644 index 0000000..97e5aac --- /dev/null +++ b/Help/prop_sf/VS_RESOURCE_GENERATOR.rst @@ -0,0 +1,8 @@ +VS_RESOURCE_GENERATOR +--------------------- + +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_SHADER_DISABLE_OPTIMIZATIONS.rst b/Help/prop_sf/VS_SHADER_DISABLE_OPTIMIZATIONS.rst new file mode 100644 index 0000000..446dd26 --- /dev/null +++ b/Help/prop_sf/VS_SHADER_DISABLE_OPTIMIZATIONS.rst @@ -0,0 +1,6 @@ +VS_SHADER_DISABLE_OPTIMIZATIONS +------------------------------- + +Disable compiler optimizations for an ``.hlsl`` source file. This adds the +``-Od`` flag to the command line for the FxCompiler tool. Specify the value +``true`` for this property to disable compiler optimizations. diff --git a/Help/prop_sf/VS_SHADER_ENABLE_DEBUG.rst b/Help/prop_sf/VS_SHADER_ENABLE_DEBUG.rst new file mode 100644 index 0000000..c0e60a3 --- /dev/null +++ b/Help/prop_sf/VS_SHADER_ENABLE_DEBUG.rst @@ -0,0 +1,6 @@ +VS_SHADER_ENABLE_DEBUG +---------------------- + +Enable debugging information for an ``.hlsl`` source file. This adds the +``-Zi`` flag to the command line for the FxCompiler tool. Specify the value +``true`` to generate debugging information for the compiled shader. diff --git a/Help/prop_sf/VS_SHADER_ENTRYPOINT.rst b/Help/prop_sf/VS_SHADER_ENTRYPOINT.rst new file mode 100644 index 0000000..fe3471f --- /dev/null +++ b/Help/prop_sf/VS_SHADER_ENTRYPOINT.rst @@ -0,0 +1,5 @@ +VS_SHADER_ENTRYPOINT +-------------------- + +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..0901123 --- /dev/null +++ b/Help/prop_sf/VS_SHADER_FLAGS.rst @@ -0,0 +1,4 @@ +VS_SHADER_FLAGS +--------------- + +Set additional VS 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..b1cf0df --- /dev/null +++ b/Help/prop_sf/VS_SHADER_MODEL.rst @@ -0,0 +1,5 @@ +VS_SHADER_MODEL +--------------- + +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..093bcc6 --- /dev/null +++ b/Help/prop_sf/VS_SHADER_OBJECT_FILE_NAME.rst @@ -0,0 +1,6 @@ +VS_SHADER_OBJECT_FILE_NAME +-------------------------- + +Specifies a file name for the compiled shader object file for an ``.hlsl`` +source file. This adds the ``-Fo`` flag to the command line for the FxCompiler +tool. diff --git a/Help/prop_sf/VS_SHADER_OUTPUT_HEADER_FILE.rst b/Help/prop_sf/VS_SHADER_OUTPUT_HEADER_FILE.rst new file mode 100644 index 0000000..e6763d3 --- /dev/null +++ b/Help/prop_sf/VS_SHADER_OUTPUT_HEADER_FILE.rst @@ -0,0 +1,5 @@ +VS_SHADER_OUTPUT_HEADER_FILE +---------------------------- + +Set filename for output header file containing object code of a ``.hlsl`` +source file. diff --git a/Help/prop_sf/VS_SHADER_TYPE.rst b/Help/prop_sf/VS_SHADER_TYPE.rst new file mode 100644 index 0000000..6880256 --- /dev/null +++ b/Help/prop_sf/VS_SHADER_TYPE.rst @@ -0,0 +1,4 @@ +VS_SHADER_TYPE +-------------- + +Set the VS 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..1a5e369 --- /dev/null +++ b/Help/prop_sf/VS_SHADER_VARIABLE_NAME.rst @@ -0,0 +1,5 @@ +VS_SHADER_VARIABLE_NAME +----------------------- + +Set name of variable in header file containing object code of a ``.hlsl`` +source file. diff --git a/Help/prop_sf/VS_TOOL_OVERRIDE.rst b/Help/prop_sf/VS_TOOL_OVERRIDE.rst new file mode 100644 index 0000000..8bdc5ca --- /dev/null +++ b/Help/prop_sf/VS_TOOL_OVERRIDE.rst @@ -0,0 +1,5 @@ +VS_TOOL_OVERRIDE +---------------- + +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..e92191d --- /dev/null +++ b/Help/prop_sf/VS_XAML_TYPE.rst @@ -0,0 +1,6 @@ +VS_XAML_TYPE +------------ + +Mark a XAML source file as a different type than the default ``Page``. +The most common usage would be to set the default App.xaml file as +ApplicationDefinition. diff --git a/Help/prop_sf/WRAP_EXCLUDE.rst b/Help/prop_sf/WRAP_EXCLUDE.rst new file mode 100644 index 0000000..2c79f72 --- /dev/null +++ b/Help/prop_sf/WRAP_EXCLUDE.rst @@ -0,0 +1,10 @@ +WRAP_EXCLUDE +------------ + +Exclude this source file from any code wrapping techniques. + +Some packages can wrap source files into alternate languages to +provide additional functionality. For example, C++ code can be +wrapped into Java or Python etc using SWIG etc. If WRAP_EXCLUDE is +set to true (1 etc) that indicates that this source file should not be +wrapped. 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..1b24701 --- /dev/null +++ b/Help/prop_sf/XCODE_EXPLICIT_FILE_TYPE.rst @@ -0,0 +1,8 @@ +XCODE_EXPLICIT_FILE_TYPE +------------------------ + +Set the 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..39e6966 --- /dev/null +++ b/Help/prop_sf/XCODE_FILE_ATTRIBUTES.rst @@ -0,0 +1,11 @@ +XCODE_FILE_ATTRIBUTES +--------------------- + +Add values to the 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..42e3757 --- /dev/null +++ b/Help/prop_sf/XCODE_LAST_KNOWN_FILE_TYPE.rst @@ -0,0 +1,9 @@ +XCODE_LAST_KNOWN_FILE_TYPE +-------------------------- + +Set the Xcode ``lastKnownFileType`` attribute on its reference to a +source file. CMake computes a default based on file extension but +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..3236a02 --- /dev/null +++ b/Help/prop_test/COST.rst @@ -0,0 +1,7 @@ +COST +---- + +Set this to a floating point value. Tests in a test set will be run in descending order of cost. + +This property describes the cost of a test. You can explicitly set +this value; tests with higher COST values will run first. diff --git a/Help/prop_test/DEPENDS.rst b/Help/prop_test/DEPENDS.rst new file mode 100644 index 0000000..89c7553 --- /dev/null +++ b/Help/prop_test/DEPENDS.rst @@ -0,0 +1,10 @@ +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`). diff --git a/Help/prop_test/DISABLED.rst b/Help/prop_test/DISABLED.rst new file mode 100644 index 0000000..c18ae7f --- /dev/null +++ b/Help/prop_test/DISABLED.rst @@ -0,0 +1,15 @@ +DISABLED +-------- + +If set to true, the test will be skipped and its status will be 'Not Run'. A +DISABLED test will not be counted in the total number of tests and its +completion status will be reported to CDash as 'Disabled'. + +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..df9bc9e --- /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..3075b4d --- /dev/null +++ b/Help/prop_test/FIXTURES_CLEANUP.rst @@ -0,0 +1,47 @@ +FIXTURES_CLEANUP +---------------- + +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..e3f60c4 --- /dev/null +++ b/Help/prop_test/FIXTURES_REQUIRED.rst @@ -0,0 +1,96 @@ +FIXTURES_REQUIRED +----------------- + +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..fdb21cc --- /dev/null +++ b/Help/prop_test/FIXTURES_SETUP.rst @@ -0,0 +1,48 @@ +FIXTURES_SETUP +-------------- + +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..bc4936e --- /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..38ec179 --- /dev/null +++ b/Help/prop_test/PROCESSOR_AFFINITY.rst @@ -0,0 +1,11 @@ +PROCESSOR_AFFINITY +------------------ + +Set to a true value to ask CTest to launch the test process with CPU affinity +for a fixed set of processors. If enabled and supported for the current +platform, CTest will choose a set of processors to place in the CPU affinity +mask when launching the test process. The number of processors in the set is +determined by the :prop_test:`PROCESSORS` test property or the number of +processors available to CTest, whichever is smaller. The set of processors +chosen will be disjoint from the processors assigned to other concurrently +running tests that also have the ``PROCESSOR_AFFINITY`` property enabled. diff --git a/Help/prop_test/REQUIRED_FILES.rst b/Help/prop_test/REQUIRED_FILES.rst new file mode 100644 index 0000000..fac357c --- /dev/null +++ b/Help/prop_test/REQUIRED_FILES.rst @@ -0,0 +1,7 @@ +REQUIRED_FILES +-------------- + +List of files required to run the test. + +If set to a list of files, the test will not be run unless all of the +files exist. diff --git a/Help/prop_test/RESOURCE_LOCK.rst b/Help/prop_test/RESOURCE_LOCK.rst new file mode 100644 index 0000000..755e0aa --- /dev/null +++ b/Help/prop_test/RESOURCE_LOCK.rst @@ -0,0 +1,10 @@ +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. diff --git a/Help/prop_test/RUN_SERIAL.rst b/Help/prop_test/RUN_SERIAL.rst new file mode 100644 index 0000000..8f65ae1 --- /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_RETURN_CODE.rst b/Help/prop_test/SKIP_RETURN_CODE.rst new file mode 100644 index 0000000..c61273c --- /dev/null +++ b/Help/prop_test/SKIP_RETURN_CODE.rst @@ -0,0 +1,9 @@ +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. 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..d607992 --- /dev/null +++ b/Help/prop_test/TIMEOUT_AFTER_MATCH.rst @@ -0,0 +1,39 @@ +TIMEOUT_AFTER_MATCH +------------------- + +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/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/ANDROID_ANT_ADDITIONAL_OPTIONS.rst b/Help/prop_tgt/ANDROID_ANT_ADDITIONAL_OPTIONS.rst new file mode 100644 index 0000000..af6b405 --- /dev/null +++ b/Help/prop_tgt/ANDROID_ANT_ADDITIONAL_OPTIONS.rst @@ -0,0 +1,8 @@ +ANDROID_ANT_ADDITIONAL_OPTIONS +------------------------------ + +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..63464d7 --- /dev/null +++ b/Help/prop_tgt/ANDROID_API.rst @@ -0,0 +1,8 @@ +ANDROID_API +----------- + +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..773ab3f --- /dev/null +++ b/Help/prop_tgt/ANDROID_API_MIN.rst @@ -0,0 +1,7 @@ +ANDROID_API_MIN +--------------- + +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..3e07e5a --- /dev/null +++ b/Help/prop_tgt/ANDROID_ARCH.rst @@ -0,0 +1,18 @@ +ANDROID_ARCH +------------ + +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..764a582 --- /dev/null +++ b/Help/prop_tgt/ANDROID_ASSETS_DIRECTORIES.rst @@ -0,0 +1,9 @@ +ANDROID_ASSETS_DIRECTORIES +-------------------------- + +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..92e2041 --- /dev/null +++ b/Help/prop_tgt/ANDROID_GUI.rst @@ -0,0 +1,15 @@ +ANDROID_GUI +----------- + +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..42937c1 --- /dev/null +++ b/Help/prop_tgt/ANDROID_JAR_DEPENDENCIES.rst @@ -0,0 +1,7 @@ +ANDROID_JAR_DEPENDENCIES +------------------------ + +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..54f0a8f --- /dev/null +++ b/Help/prop_tgt/ANDROID_JAR_DIRECTORIES.rst @@ -0,0 +1,14 @@ +ANDROID_JAR_DIRECTORIES +----------------------- + +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..90ef1ce --- /dev/null +++ b/Help/prop_tgt/ANDROID_JAVA_SOURCE_DIR.rst @@ -0,0 +1,8 @@ +ANDROID_JAVA_SOURCE_DIR +----------------------- + +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..759a37b --- /dev/null +++ b/Help/prop_tgt/ANDROID_NATIVE_LIB_DEPENDENCIES.rst @@ -0,0 +1,14 @@ +ANDROID_NATIVE_LIB_DEPENDENCIES +------------------------------- + +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..bc67380 --- /dev/null +++ b/Help/prop_tgt/ANDROID_NATIVE_LIB_DIRECTORIES.rst @@ -0,0 +1,16 @@ +ANDROID_NATIVE_LIB_DIRECTORIES +------------------------------ + +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..847acae --- /dev/null +++ b/Help/prop_tgt/ANDROID_PROCESS_MAX.rst @@ -0,0 +1,8 @@ +ANDROID_PROCESS_MAX +------------------- + +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..dafc51e --- /dev/null +++ b/Help/prop_tgt/ANDROID_PROGUARD.rst @@ -0,0 +1,9 @@ +ANDROID_PROGUARD +---------------- + +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..0e929d1 --- /dev/null +++ b/Help/prop_tgt/ANDROID_PROGUARD_CONFIG_PATH.rst @@ -0,0 +1,9 @@ +ANDROID_PROGUARD_CONFIG_PATH +---------------------------- + +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..9533f1a --- /dev/null +++ b/Help/prop_tgt/ANDROID_SECURE_PROPS_PATH.rst @@ -0,0 +1,8 @@ +ANDROID_SECURE_PROPS_PATH +------------------------- + +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..6361896 --- /dev/null +++ b/Help/prop_tgt/ANDROID_SKIP_ANT_STEP.rst @@ -0,0 +1,6 @@ +ANDROID_SKIP_ANT_STEP +--------------------- + +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..386e96e --- /dev/null +++ b/Help/prop_tgt/ANDROID_STL_TYPE.rst @@ -0,0 +1,27 @@ +ANDROID_STL_TYPE +---------------- + +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..4221069 --- /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:: 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..8db6ede --- /dev/null +++ b/Help/prop_tgt/AUTOGEN_BUILD_DIR.rst @@ -0,0 +1,17 @@ +AUTOGEN_BUILD_DIR +----------------- + +Directory where :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTOUIC` and :prop_tgt:`AUTORCC` +generate files for the target. + +The directory is created on demand and automatically added to the +:prop_dir:`ADDITIONAL_MAKE_CLEAN_FILES`. + +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_PARALLEL.rst b/Help/prop_tgt/AUTOGEN_PARALLEL.rst new file mode 100644 index 0000000..07fbc5a --- /dev/null +++ b/Help/prop_tgt/AUTOGEN_PARALLEL.rst @@ -0,0 +1,21 @@ +AUTOGEN_PARALLEL +---------------- + +Number of parallel ``moc`` or ``uic`` processes to start when using +:prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`. + +The custom `<origin>_autogen` target starts a number of threads of which +each one parses a source file and on demand starts a ``moc`` or ``uic`` +process. :prop_tgt:`AUTOGEN_PARALLEL` controls how many parallel threads +(and therefore ``moc`` or ``uic`` processes) are started. + +- An empty (or unset) value or the string ``AUTO`` sets the number of + threads/processes to the number of physical CPUs on the host system. +- A positive non zero integer value sets the exact thread/process count. +- Otherwise a single thread/process is started. + +By default :prop_tgt:`AUTOGEN_PARALLEL` is initialized from +:variable:`CMAKE_AUTOGEN_PARALLEL`. + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. diff --git a/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst b/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst new file mode 100644 index 0000000..7d3dfd1 --- /dev/null +++ b/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst @@ -0,0 +1,31 @@ +AUTOGEN_TARGET_DEPENDS +---------------------- + +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 is used to auto generate +``moc`` and ``uic`` files. As this ``_autogen`` target is created at +generate-time, it is not possible to define dependencies of it, +such as to create inputs for the ``moc`` or ``uic`` executable. + +The :prop_tgt:`AUTOGEN_TARGET_DEPENDS` target property can be set instead to a +list of dependencies of the ``_autogen`` target. Dependencies can be target +names or file names. + +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 target's sources + +it must added to :prop_tgt:`AUTOGEN_TARGET_DEPENDS`. diff --git a/Help/prop_tgt/AUTOMOC.rst b/Help/prop_tgt/AUTOMOC.rst new file mode 100644 index 0000000..3bd693a --- /dev/null +++ b/Help/prop_tgt/AUTOMOC.rst @@ -0,0 +1,90 @@ +AUTOMOC +------- + +Should the target be processed with automoc (for Qt projects). + +AUTOMOC is a boolean specifying whether CMake will handle the Qt ``moc`` +preprocessor automatically, i.e. without having to use the +:module:`QT4_WRAP_CPP() <FindQt4>` or QT5_WRAP_CPP() macro. +Currently Qt4 and Qt5 are supported. + +When this property is set ``ON``, CMake will scan the header and +source files at build time and invoke moc accordingly. + +* If an ``#include`` statement like ``#include "moc_<basename>.cpp"`` is found, + a macro from :prop_tgt:`AUTOMOC_MACRO_NAMES` is expected to appear in the + ``<basename>.h(xx)`` header file. ``moc`` is run on the header + file to generate ``moc_<basename>.cpp`` in the + ``<AUTOGEN_BUILD_DIR>/include`` directory which is automatically added + to the target's :prop_tgt:`INCLUDE_DIRECTORIES`. + This allows the compiler to find the included ``moc_<basename>.cpp`` file + regardless of the location the original source. + + * 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`. + +* If an ``#include`` statement like ``#include "<basename>.moc"`` is found, + a macro from :prop_tgt:`AUTOMOC_MACRO_NAMES` is expected to appear in the + source file and ``moc`` is run on the source file itself. + +* Header files that are not included by an ``#include "moc_<basename>.cpp"`` + statement are nonetheless scanned for a macro out of + :prop_tgt:`AUTOMOC_MACRO_NAMES`. + The resulting ``moc_<basename>.cpp`` files are generated in custom + directories and automatically included in a generated + ``<AUTOGEN_BUILD_DIR>/mocs_compilation.cpp`` file, + which is compiled as part of the target. + + * The custom directories with checksum + based names help to avoid name collisions for ``moc`` files with the same + ``<basename>``. + + * See :prop_tgt:`AUTOGEN_BUILD_DIR`. + +* Additionally, header files with the same base name as a source file, + (like ``<basename>.h``) or ``_p`` appended to the base name (like + ``<basename>_p.h``), are scanned for a macro out of + :prop_tgt:`AUTOMOC_MACRO_NAMES`, and if found, ``moc`` + is also executed on those files. + +* ``AUTOMOC`` always checks multiple header alternative extensions, + such as ``hpp``, ``hxx``, etc. when searching for headers. + +* ``AUTOMOC`` looks for the ``Q_PLUGIN_METADATA`` macro and reruns the + ``moc`` when the file addressed by the ``FILE`` argument of the macro changes. + +This property is initialized by the value of the :variable:`CMAKE_AUTOMOC` +variable if it is set when a target is created. + +Additional command line options for ``moc`` can be set via the +:prop_tgt:`AUTOMOC_MOC_OPTIONS` property. + +By enabling the :variable:`CMAKE_AUTOMOC_RELAXED_MODE` variable the +rules for searching the files which will be processed by ``moc`` can be relaxed. +See the documentation for this variable for more details. + +The global property :prop_gbl:`AUTOGEN_TARGETS_FOLDER` can be used to group the +automoc targets together in an IDE, e.g. in MSVS. + +The global property :prop_gbl:`AUTOGEN_SOURCE_GROUP` can be used to group +files generated by :prop_tgt:`AUTOMOC` together in an IDE, e.g. in MSVS. + +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`. + +Compiler pre definitions for ``moc`` are written to a ``moc_predefs.h`` file +which is controlled by :prop_tgt:`AUTOMOC_COMPILER_PREDEFINES`. + +Source C++ files can be excluded from :prop_tgt:`AUTOMOC` processing by +enabling :prop_sf:`SKIP_AUTOMOC` or the broader :prop_sf:`SKIP_AUTOGEN`. + +The number of parallel ``moc`` processes to start can be modified by +setting :prop_tgt:`AUTOGEN_PARALLEL`. + +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..57a647f --- /dev/null +++ b/Help/prop_tgt/AUTOMOC_COMPILER_PREDEFINES.rst @@ -0,0 +1,24 @@ +AUTOMOC_COMPILER_PREDEFINES +--------------------------- + +Boolean value used by :prop_tgt:`AUTOMOC` to determine if the +compiler pre definitions file ``moc_predefs.h`` should be generated. + +CMake generates a ``moc_predefs.h`` file with compiler pre definitions +from the output of the command defined in +:variable:`CMAKE_CXX_COMPILER_PREDEFINES_COMMAND <CMAKE_<LANG>_COMPILER_PREDEFINES_COMMAND>` +when + +- :prop_tgt:`AUTOMOC` is enabled, +- :prop_tgt:`AUTOMOC_COMPILER_PREDEFINES` is enabled, +- :variable:`CMAKE_CXX_COMPILER_PREDEFINES_COMMAND <CMAKE_<LANG>_COMPILER_PREDEFINES_COMMAND>` isn't empty and +- the Qt version is greater or equal 5.8. + +The ``moc_predefs.h`` file, which is generated in :prop_tgt:`AUTOGEN_BUILD_DIR`, +is passed to ``moc`` as the argument to the ``--include`` option. + +By default :prop_tgt:`AUTOMOC_COMPILER_PREDEFINES` is initialized from +:variable:`CMAKE_AUTOMOC_COMPILER_PREDEFINES`, which is ON by default. + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. diff --git a/Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst b/Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst new file mode 100644 index 0000000..69957bf --- /dev/null +++ b/Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst @@ -0,0 +1,104 @@ +AUTOMOC_DEPEND_FILTERS +---------------------- + +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. + +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_MACRO_NAMES.rst b/Help/prop_tgt/AUTOMOC_MACRO_NAMES.rst new file mode 100644 index 0000000..a9a0ecf --- /dev/null +++ b/Help/prop_tgt/AUTOMOC_MACRO_NAMES.rst @@ -0,0 +1,32 @@ +AUTOMOC_MACRO_NAMES +------------------- + +A :ref:`;-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..ebd5c49 --- /dev/null +++ b/Help/prop_tgt/AUTOMOC_MOC_OPTIONS.rst @@ -0,0 +1,15 @@ +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. + +By default it is empty. + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. diff --git a/Help/prop_tgt/AUTORCC.rst b/Help/prop_tgt/AUTORCC.rst new file mode 100644 index 0000000..3cc5990 --- /dev/null +++ b/Help/prop_tgt/AUTORCC.rst @@ -0,0 +1,39 @@ +AUTORCC +------- + +Should the target be processed with autorcc (for Qt projects). + +``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 inside a +:command:`custom command <add_custom_command>`. +If the ``.qrc`` file is :prop_sf:`GENERATED` though, a +:command:`custom target <add_custom_target>` is used instead. + +Additional command line options for rcc can be set via the +:prop_sf:`AUTORCC_OPTIONS` source file property on the ``.qrc`` file. + +The global property :prop_gbl:`AUTOGEN_TARGETS_FOLDER` can be used to group +the autorcc targets together in an IDE, e.g. in MSVS. + +The global property :prop_gbl:`AUTOGEN_SOURCE_GROUP` can be used to group +files generated by :prop_tgt:`AUTORCC` together in an IDE, e.g. in MSVS. + +When there are multiple ``.qrc`` files with the same name, CMake will +generate unspecified unique names for ``rcc``. Therefore if +``Q_INIT_RESOURCE()`` or ``Q_CLEANUP_RESOURCE()`` need to be used the +``.qrc`` file name must be unique. + +Source files can be excluded from :prop_tgt:`AUTORCC` processing by +enabling :prop_sf:`SKIP_AUTORCC` or the broader :prop_sf:`SKIP_AUTOGEN`. + +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..d6ade5a --- /dev/null +++ b/Help/prop_tgt/AUTORCC_OPTIONS.rst @@ -0,0 +1,30 @@ +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. + +This property is initialized by the value of the +:variable:`CMAKE_AUTORCC_OPTIONS` variable if it is set when a target is +created. + +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..4fc603f --- /dev/null +++ b/Help/prop_tgt/AUTOUIC.rst @@ -0,0 +1,40 @@ +AUTOUIC +------- + +Should the target be processed with autouic (for Qt projects). + +``AUTOUIC`` is a boolean specifying whether CMake will handle +the Qt ``uic`` code generator automatically, i.e. without having to use +the :module:`QT4_WRAP_UI() <FindQt4>` or ``QT5_WRAP_UI()`` macro. Currently +Qt4 and Qt5 are supported. + +When this property is ``ON``, CMake will scan the source files at build time +and invoke ``uic`` accordingly. If an ``#include`` statement like +``#include "ui_foo.h"`` is found in ``source.cpp``, a ``foo.ui`` file is +searched for first in the vicinity of ``source.cpp`` and afterwards in the +optional :prop_tgt:`AUTOUIC_SEARCH_PATHS` of the target. +``uic`` is run on the ``foo.ui`` file to generate ``ui_foo.h`` in the directory +``<AUTOGEN_BUILD_DIR>/include``, +which is automatically added to the target's :prop_tgt:`INCLUDE_DIRECTORIES`. + +* 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`. + +This property is initialized by the value of the :variable:`CMAKE_AUTOUIC` +variable if it is set when a target is created. + +Additional command line options for ``uic`` can be set via the +:prop_sf:`AUTOUIC_OPTIONS` source file property on the ``foo.ui`` file. +The global property :prop_gbl:`AUTOGEN_TARGETS_FOLDER` can be used to group the +autouic targets together in an IDE, e.g. in MSVS. + +Source files can be excluded from :prop_tgt:`AUTOUIC` processing by +enabling :prop_sf:`SKIP_AUTOUIC` or the broader :prop_sf:`SKIP_AUTOGEN`. + +The number of parallel ``uic`` processes to start can be modified by +setting :prop_tgt:`AUTOGEN_PARALLEL`. + +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..3f613b9 --- /dev/null +++ b/Help/prop_tgt/AUTOUIC_OPTIONS.rst @@ -0,0 +1,34 @@ +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. + +This property is initialized by the value of the +:variable:`CMAKE_AUTOUIC_OPTIONS` variable if it is set when a target is +created. + +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..96d9f89 --- /dev/null +++ b/Help/prop_tgt/AUTOUIC_SEARCH_PATHS.rst @@ -0,0 +1,12 @@ +AUTOUIC_SEARCH_PATHS +-------------------- + +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..246f7e6 --- /dev/null +++ b/Help/prop_tgt/BINARY_DIR.rst @@ -0,0 +1,6 @@ +BINARY_DIR +---------- + +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..27393f5 --- /dev/null +++ b/Help/prop_tgt/BUILD_RPATH.rst @@ -0,0 +1,10 @@ +BUILD_RPATH +----------- + +A :ref:`;-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. 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..bbb9a24 --- /dev/null +++ b/Help/prop_tgt/BUILD_WITH_INSTALL_NAME_DIR.rst @@ -0,0 +1,13 @@ +BUILD_WITH_INSTALL_NAME_DIR +--------------------------- + +``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..052ac6d --- /dev/null +++ b/Help/prop_tgt/COMMON_LANGUAGE_RUNTIME.rst @@ -0,0 +1,22 @@ +COMMON_LANGUAGE_RUNTIME +----------------------- + +By setting this target property, the target is configured to build with +``C++/CLI`` support. + +The Visual Studio generator defines the ``clr`` parameter depending on +the value of ``COMMON_LANGUAGE_RUNTIME``: + +* property not set: native C++ (i.e. default) +* property set but empty: mixed unmanaged/managed C++ +* property set to any non empty value: managed C++ + +Supported values: ``""``, ``"pure"``, ``"safe"`` + +This property is only evaluated :ref:`Visual Studio Generators` for +VS 2010 and above. + +To be able to build managed C++ targets with VS 2017 and above the component +``C++/CLI support`` must be installed, which may not be done by default. + +See also :prop_tgt:`IMPORTED_COMMON_LANGUAGE_RUNTIME` diff --git a/Help/prop_tgt/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..195215e --- /dev/null +++ b/Help/prop_tgt/COMPILE_FEATURES.rst @@ -0,0 +1,12 @@ +COMPILE_FEATURES +---------------- + +Compiler features enabled for this target. + +The list of features in this property are a subset of the features listed +in the :variable:`CMAKE_CXX_COMPILE_FEATURES` variable. + +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..892ac23 --- /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:`;-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..24a9f62 --- /dev/null +++ b/Help/prop_tgt/COMPILE_PDB_NAME.rst @@ -0,0 +1,11 @@ +COMPILE_PDB_NAME +---------------- + +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..e4077f5 --- /dev/null +++ b/Help/prop_tgt/COMPILE_PDB_NAME_CONFIG.rst @@ -0,0 +1,10 @@ +COMPILE_PDB_NAME_<CONFIG> +------------------------- + +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..34f49be --- /dev/null +++ b/Help/prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY.rst @@ -0,0 +1,13 @@ +COMPILE_PDB_OUTPUT_DIRECTORY +---------------------------- + +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..52ef013 --- /dev/null +++ b/Help/prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG.rst @@ -0,0 +1,16 @@ +COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG> +------------------------------------- + +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 (VS, 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..11b50b9 --- /dev/null +++ b/Help/prop_tgt/CONFIG_POSTFIX.rst @@ -0,0 +1,10 @@ +<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. diff --git a/Help/prop_tgt/CROSSCOMPILING_EMULATOR.rst b/Help/prop_tgt/CROSSCOMPILING_EMULATOR.rst new file mode 100644 index 0000000..a0811bc --- /dev/null +++ b/Help/prop_tgt/CROSSCOMPILING_EMULATOR.rst @@ -0,0 +1,11 @@ +CROSSCOMPILING_EMULATOR +----------------------- + +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. + +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_EXTENSIONS.rst b/Help/prop_tgt/CUDA_EXTENSIONS.rst new file mode 100644 index 0000000..098ca3c --- /dev/null +++ b/Help/prop_tgt/CUDA_EXTENSIONS.rst @@ -0,0 +1,17 @@ +CUDA_EXTENSIONS +--------------- + +Boolean specifying whether compiler specific extensions are requested. + +This property specifies whether compiler specific extensions should be +used. For some compilers, this results in adding a flag such +as ``-std=gnu++11`` instead of ``-std=c++11`` to the compile line. This +property is ``ON`` by default. The basic 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..0ee372b --- /dev/null +++ b/Help/prop_tgt/CUDA_PTX_COMPILATION.rst @@ -0,0 +1,12 @@ +CUDA_PTX_COMPILATION +-------------------- + +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..127d79f --- /dev/null +++ b/Help/prop_tgt/CUDA_RESOLVE_DEVICE_SYMBOLS.rst @@ -0,0 +1,15 @@ +CUDA_RESOLVE_DEVICE_SYMBOLS +--------------------------- + +CUDA only: Enables device linking for the specific static library target + +If set this will enable device linking on this static library target. Normally +device linking is deferred until a shared library or executable is generated, +allowing for multiple static libraries to resolve device symbols at the same +time. + +For instance: + +.. code-block:: cmake + + set_property(TARGET mystaticlib PROPERTY CUDA_RESOLVE_DEVICE_SYMBOLS ON) diff --git a/Help/prop_tgt/CUDA_SEPARABLE_COMPILATION.rst b/Help/prop_tgt/CUDA_SEPARABLE_COMPILATION.rst new file mode 100644 index 0000000..d306d7f --- /dev/null +++ b/Help/prop_tgt/CUDA_SEPARABLE_COMPILATION.rst @@ -0,0 +1,17 @@ +CUDA_SEPARABLE_COMPILATION +-------------------------- + +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..a3a2f56 --- /dev/null +++ b/Help/prop_tgt/CUDA_STANDARD.rst @@ -0,0 +1,32 @@ +CUDA_STANDARD +------------- + +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``, ``11``, ``14``. + +If the value requested does not result in a compile flag being added for +the compiler in use, a previous standard flag will be added instead. This +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..b2d5b28 --- /dev/null +++ b/Help/prop_tgt/CUDA_STANDARD_REQUIRED.rst @@ -0,0 +1,18 @@ +CUDA_STANDARD_REQUIRED +---------------------- + +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, 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..280bb3a --- /dev/null +++ b/Help/prop_tgt/CXX_EXTENSIONS.rst @@ -0,0 +1,17 @@ +CXX_EXTENSIONS +-------------- + +Boolean specifying whether compiler specific extensions are requested. + +This property specifies whether compiler specific extensions should be +used. For some compilers, this results in adding a flag such +as ``-std=gnu++11`` instead of ``-std=c++11`` to the compile line. This +property is ``ON`` by default. The basic 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..ccc0147 --- /dev/null +++ b/Help/prop_tgt/CXX_STANDARD.rst @@ -0,0 +1,34 @@ +CXX_STANDARD +------------ + +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``, and ``20``. + +If the value requested does not result in a compile flag being added for +the compiler in use, a previous standard flag will be added instead. This +means that using: + +.. code-block:: cmake + + set_property(TARGET tgt PROPERTY 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..697d7f6 --- /dev/null +++ b/Help/prop_tgt/CXX_STANDARD_REQUIRED.rst @@ -0,0 +1,18 @@ +CXX_STANDARD_REQUIRED +--------------------- + +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, 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..05b14ce --- /dev/null +++ b/Help/prop_tgt/C_EXTENSIONS.rst @@ -0,0 +1,17 @@ +C_EXTENSIONS +------------ + +Boolean specifying whether compiler specific extensions are requested. + +This property specifies whether compiler specific extensions should be +used. For some compilers, this results in adding a flag such +as ``-std=gnu11`` instead of ``-std=c11`` to the compile line. This +property is ``ON`` by default. The basic 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..e7f7904 --- /dev/null +++ b/Help/prop_tgt/C_STANDARD.rst @@ -0,0 +1,34 @@ +C_STANDARD +---------- + +The C standard whose features are requested to build this target. + +This property specifies the C standard whose features are requested +to build this target. For some compilers, this results in adding a +flag such as ``-std=gnu11`` to the compile line. For compilers that +have no notion of a standard level, such as Microsoft Visual C++ before +2015 Update 3, this has no effect. + +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 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..acfad98 --- /dev/null +++ b/Help/prop_tgt/C_STANDARD_REQUIRED.rst @@ -0,0 +1,18 @@ +C_STANDARD_REQUIRED +------------------- + +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 standard level, such as +MSVC, 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_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..1487656 --- /dev/null +++ b/Help/prop_tgt/DEBUG_POSTFIX.rst @@ -0,0 +1,7 @@ +DEBUG_POSTFIX +------------- + +See target property <CONFIG>_POSTFIX. + +This property is a special case of the more-general <CONFIG>_POSTFIX +property for the DEBUG configuration. diff --git a/Help/prop_tgt/DEFINE_SYMBOL.rst b/Help/prop_tgt/DEFINE_SYMBOL.rst new file mode 100644 index 0000000..f47f135 --- /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..5e9c191 --- /dev/null +++ b/Help/prop_tgt/DEPLOYMENT_ADDITIONAL_FILES.rst @@ -0,0 +1,18 @@ +DEPLOYMENT_ADDITIONAL_FILES +--------------------------- + +Set the WinCE project ``AdditionalFiles`` in ``DeploymentTool`` in ``.vcproj`` +files generated by the :generator:`Visual Studio 9 2008` generator. +This is useful when you want to debug on remote WinCE device. +Specify additional files that will be copied to the device. +For example: + +.. code-block:: cmake + + set_property(TARGET ${TARGET} PROPERTY + DEPLOYMENT_ADDITIONAL_FILES "english.lng|local_folder|remote_folder|0" + "german.lng|local_folder|remote_folder|0") + +produces:: + + <DeploymentTool AdditionalFiles="english.lng|local_folder|remote_folder|0;german.lng|local_folder|remote_folder|0" ... /> diff --git a/Help/prop_tgt/DEPLOYMENT_REMOTE_DIRECTORY.rst b/Help/prop_tgt/DEPLOYMENT_REMOTE_DIRECTORY.rst new file mode 100644 index 0000000..368768a --- /dev/null +++ b/Help/prop_tgt/DEPLOYMENT_REMOTE_DIRECTORY.rst @@ -0,0 +1,18 @@ +DEPLOYMENT_REMOTE_DIRECTORY +--------------------------- + +Set the WinCE project ``RemoteDirectory`` in ``DeploymentTool`` and +``RemoteExecutable`` in ``DebuggerTool`` in ``.vcproj`` files generated +by the :generator:`Visual Studio 9 2008` 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/DOTNET_TARGET_FRAMEWORK_VERSION.rst b/Help/prop_tgt/DOTNET_TARGET_FRAMEWORK_VERSION.rst new file mode 100644 index 0000000..a2f7d7d --- /dev/null +++ b/Help/prop_tgt/DOTNET_TARGET_FRAMEWORK_VERSION.rst @@ -0,0 +1,13 @@ +DOTNET_TARGET_FRAMEWORK_VERSION +------------------------------- + +Specify the .NET target framework version. + +Used to specify the .NET target framework version for C++/CLI. For +example, "v4.5". + +This property is only evaluated for :ref:`Visual Studio Generators` +VS 2010 and above. + +Can be initialized for all targets using the variable +:variable:`CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION`. diff --git a/Help/prop_tgt/ENABLE_EXPORTS.rst b/Help/prop_tgt/ENABLE_EXPORTS.rst new file mode 100644 index 0000000..581c2b9 --- /dev/null +++ b/Help/prop_tgt/ENABLE_EXPORTS.rst @@ -0,0 +1,22 @@ +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. +For DLL platforms an import library will be created for the exported +symbols and then used for linking. All Windows-based systems +including Cygwin are DLL platforms. For non-DLL platforms that +require all symbols to be resolved at link time, such as macOS, the +module will "link" to the executable using a flag like +``-bundle_loader``. For other non-DLL platforms the link rule is simply +ignored since the dynamic loader will automatically bind symbols when +the module is loaded. + +This 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..caa5741 --- /dev/null +++ b/Help/prop_tgt/EXCLUDE_FROM_ALL.rst @@ -0,0 +1,10 @@ +EXCLUDE_FROM_ALL +---------------- + +Exclude the target from the all target. + +A property on a target that indicates if the target is excluded from +the default build target. If it is not, then with a Makefile for +example typing make will cause this target to be built. The same +concept applies to the default build of other generators. Installing +a target with EXCLUDE_FROM_ALL set to true has undefined behavior. 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..a14e48c --- /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..655a9de --- /dev/null +++ b/Help/prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD_CONFIG.rst @@ -0,0 +1,9 @@ +EXCLUDE_FROM_DEFAULT_BUILD_<CONFIG> +----------------------------------- + +Per-configuration version of target exclusion from "Build Solution". + +This is the configuration-specific version of +EXCLUDE_FROM_DEFAULT_BUILD. If the generic EXCLUDE_FROM_DEFAULT_BUILD +is also set on a target, EXCLUDE_FROM_DEFAULT_BUILD_<CONFIG> takes +precedence in configurations for which it has a value. diff --git a/Help/prop_tgt/EXPORT_NAME.rst b/Help/prop_tgt/EXPORT_NAME.rst new file mode 100644 index 0000000..1b4247c --- /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 when it this +target is is exported. 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..bcf47a6 --- /dev/null +++ b/Help/prop_tgt/EXPORT_PROPERTIES.rst @@ -0,0 +1,14 @@ +EXPORT_PROPERTIES +----------------- + +List additional properties to export for a target. + +This property contains a list of property names that should be exported by +the :command:`install(EXPORT)` and :command:`export` commands. By default +only a limited number of properties are exported. This property can be used +to additionally export other properties as well. + +Properties starting with ``INTERFACE_`` or ``IMPORTED_`` are not allowed as +they are reserved for internal CMake use. + +Properties containing generator expressions are also not allowed. diff --git a/Help/prop_tgt/EchoString.rst b/Help/prop_tgt/EchoString.rst new file mode 100644 index 0000000..32ae2aa --- /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 makefiles) 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..0121125 --- /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..9dad060 --- /dev/null +++ b/Help/prop_tgt/FRAMEWORK.rst @@ -0,0 +1,35 @@ +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 + +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_VERSION.rst b/Help/prop_tgt/FRAMEWORK_VERSION.rst new file mode 100644 index 0000000..c2ae7b9 --- /dev/null +++ b/Help/prop_tgt/FRAMEWORK_VERSION.rst @@ -0,0 +1,8 @@ +FRAMEWORK_VERSION +----------------- + +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..0a11d91 --- /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 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..9c86437 --- /dev/null +++ b/Help/prop_tgt/Fortran_MODULE_DIRECTORY.rst @@ -0,0 +1,17 @@ +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 +CMAKE_Fortran_MODULE_DIRECTORY is set when a target is created its +value is used to initialize this property. + +Note that some compilers will automatically search the module output +directory for modules USEd during compilation but others will not. If +your sources USE modules their location must be specified by +INCLUDE_DIRECTORIES regardless of this property. diff --git a/Help/prop_tgt/GENERATOR_FILE_NAME.rst b/Help/prop_tgt/GENERATOR_FILE_NAME.rst new file mode 100644 index 0000000..032b22a --- /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 +include_external_msproject(). diff --git a/Help/prop_tgt/GNUtoMS.rst b/Help/prop_tgt/GNUtoMS.rst new file mode 100644 index 0000000..cf34da9 --- /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 install(TARGETS) and exported by +install(EXPORT) and 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 project() +or 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..7790932 --- /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 LINKER_LANGUAGE property to CXX. +See that property's documentation for details. 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..dc73807 --- /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..605c1ce --- /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..99e3bc4 --- /dev/null +++ b/Help/prop_tgt/IMPORTED_COMMON_LANGUAGE_RUNTIME.rst @@ -0,0 +1,8 @@ +IMPORTED_COMMON_LANGUAGE_RUNTIME +-------------------------------- + +Property to define if the target uses ``C++/CLI``. + +Ignored for non-imported targets. + +See also the :prop_tgt:`COMMON_LANGUAGE_RUNTIME` target property. diff --git a/Help/prop_tgt/IMPORTED_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..1feca04 --- /dev/null +++ b/Help/prop_tgt/IMPORTED_GLOBAL.rst @@ -0,0 +1,22 @@ +IMPORTED_GLOBAL +--------------- + +Indication of whether an :ref:`IMPORTED target <Imported Targets>` is +globally visible. + +The boolean value of this property is True for targets created with the +``IMPORTED`` ``GLOBAL`` options to :command:`add_executable()` or +:command:`add_library()`. It is always False for targets built within the +project. + +For targets created with the ``IMPORTED`` option to +:command:`add_executable()` or :command:`add_library()` but without the +additional option ``GLOBAL`` this is False, too. However, setting this +property for such a locally ``IMPORTED`` target to True promotes that +target to global scope. This promotion can only be done in the same +directory where that ``IMPORTED`` target was created in the first place. + +Once an imported target has been made global, it cannot be changed back to +non-global. Therefore, if a project sets this property, it may only +provide a value of True. CMake will issue an error if the project tries to +set the property to a non-True value, even if the value was already False. diff --git a/Help/prop_tgt/IMPORTED_IMPLIB.rst b/Help/prop_tgt/IMPORTED_IMPLIB.rst new file mode 100644 index 0000000..acf4b32 --- /dev/null +++ b/Help/prop_tgt/IMPORTED_IMPLIB.rst @@ -0,0 +1,7 @@ +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. 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..b4b3f02 --- /dev/null +++ b/Help/prop_tgt/IMPORTED_IMPLIB_CONFIG.rst @@ -0,0 +1,7 @@ +IMPORTED_IMPLIB_<CONFIG> +------------------------ + +<CONFIG>-specific version of 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..1943dba --- /dev/null +++ b/Help/prop_tgt/IMPORTED_LIBNAME.rst @@ -0,0 +1,23 @@ +IMPORTED_LIBNAME +---------------- + +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..a28b838 --- /dev/null +++ b/Help/prop_tgt/IMPORTED_LIBNAME_CONFIG.rst @@ -0,0 +1,7 @@ +IMPORTED_LIBNAME_<CONFIG> +------------------------- + +<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..2db2b0e --- /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 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..ee243c7 --- /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 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..5ca9c8b --- /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..d4a10fb --- /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 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..61134a4 --- /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 +LINK_INTERFACE_LIBRARIES property, this property applies to all +imported target types, including STATIC libraries. This property is +ignored for non-imported targets. + +This property is ignored if the target also has a non-empty +INTERFACE_LINK_LIBRARIES property. + +This property is deprecated. Use 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..13b93ba --- /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 IMPORTED_LINK_INTERFACE_LIBRARIES. + +Configuration names correspond to those provided by the project from +which the target is imported. If set, this property completely +overrides the generic property for the named configuration. + +This property is ignored if the target also has a non-empty +INTERFACE_LINK_LIBRARIES property. + +This property is deprecated. Use 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..3a86b99 --- /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 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..33b9b84 --- /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 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..2d07aad --- /dev/null +++ b/Help/prop_tgt/IMPORTED_LOCATION.rst @@ -0,0 +1,21 @@ +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 bundles +on macOS this is the location of the executable file inside +Contents/MacOS under the application bundle folder. For static +libraries and modules this is the location of the library or module. +For shared libraries on non-DLL platforms this is the location of the +shared library. For frameworks on 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. + +Projects may skip IMPORTED_LOCATION if the configuration-specific +property IMPORTED_LOCATION_<CONFIG> is set. To get the location of an +imported target read one of the LOCATION or LOCATION_<CONFIG> +properties. diff --git a/Help/prop_tgt/IMPORTED_LOCATION_CONFIG.rst b/Help/prop_tgt/IMPORTED_LOCATION_CONFIG.rst new file mode 100644 index 0000000..f85bb19 --- /dev/null +++ b/Help/prop_tgt/IMPORTED_LOCATION_CONFIG.rst @@ -0,0 +1,7 @@ +IMPORTED_LOCATION_<CONFIG> +-------------------------- + +<CONFIG>-specific version of 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..4a1bb44 --- /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..22d6822 --- /dev/null +++ b/Help/prop_tgt/IMPORTED_NO_SONAME_CONFIG.rst @@ -0,0 +1,7 @@ +IMPORTED_NO_SONAME_<CONFIG> +--------------------------- + +<CONFIG>-specific version of 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..222e6cc --- /dev/null +++ b/Help/prop_tgt/IMPORTED_OBJECTS.rst @@ -0,0 +1,11 @@ +IMPORTED_OBJECTS +---------------- + +:ref:`;-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. diff --git a/Help/prop_tgt/IMPORTED_OBJECTS_CONFIG.rst b/Help/prop_tgt/IMPORTED_OBJECTS_CONFIG.rst new file mode 100644 index 0000000..4419ed1 --- /dev/null +++ b/Help/prop_tgt/IMPORTED_OBJECTS_CONFIG.rst @@ -0,0 +1,7 @@ +IMPORTED_OBJECTS_<CONFIG> +------------------------- + +<CONFIG>-specific version of :prop_tgt:`IMPORTED_OBJECTS` property. + +Configuration names correspond to those provided by the project from +which the target is imported. diff --git a/Help/prop_tgt/IMPORTED_SONAME.rst b/Help/prop_tgt/IMPORTED_SONAME.rst new file mode 100644 index 0000000..d80907e --- /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..6ec9af3 --- /dev/null +++ b/Help/prop_tgt/IMPORTED_SONAME_CONFIG.rst @@ -0,0 +1,7 @@ +IMPORTED_SONAME_<CONFIG> +------------------------ + +<CONFIG>-specific version of 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..deede97 --- /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 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..bd01250 --- /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 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..8b40d9c --- /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 "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/INSTALL_NAME_DIR.rst b/Help/prop_tgt/INSTALL_NAME_DIR.rst new file mode 100644 index 0000000..34348bb --- /dev/null +++ b/Help/prop_tgt/INSTALL_NAME_DIR.rst @@ -0,0 +1,12 @@ +INSTALL_NAME_DIR +---------------- + +Mac OSX directory name for installed targets. + +INSTALL_NAME_DIR is a string specifying the directory portion of the +"install_name" field of shared libraries on Mac OSX to use in the +installed targets. + +This property is initialized by the value of the variable +:variable:`CMAKE_INSTALL_NAME_DIR` if it is set when a target is +created. diff --git a/Help/prop_tgt/INSTALL_RPATH.rst b/Help/prop_tgt/INSTALL_RPATH.rst new file mode 100644 index 0000000..6206b68 --- /dev/null +++ b/Help/prop_tgt/INSTALL_RPATH.rst @@ -0,0 +1,9 @@ +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 CMAKE_INSTALL_RPATH if it is set when a +target is created. 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..f0006f8 --- /dev/null +++ b/Help/prop_tgt/INSTALL_RPATH_USE_LINK_PATH.rst @@ -0,0 +1,10 @@ +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 directories in the linker search path and outside the project +to the INSTALL_RPATH. This property is initialized by the value of +the variable CMAKE_INSTALL_RPATH_USE_LINK_PATH if it is set when a +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..31b594f --- /dev/null +++ b/Help/prop_tgt/INTERFACE_COMPILE_FEATURES.rst @@ -0,0 +1,12 @@ +INTERFACE_COMPILE_FEATURES +-------------------------- + +.. |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..d07f8ea --- /dev/null +++ b/Help/prop_tgt/INTERFACE_LINK_DEPENDS.rst @@ -0,0 +1,31 @@ +INTERFACE_LINK_DEPENDS +---------------------- + +Additional public interface files on which a target binary depends for linking. + +This property is supported only by Makefile and Ninja 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..56a4ec0 --- /dev/null +++ b/Help/prop_tgt/INTERFACE_LINK_DIRECTORIES.rst @@ -0,0 +1,9 @@ +INTERFACE_LINK_DIRECTORIES +-------------------------- + +.. |property_name| replace:: link directories +.. |command_name| replace:: :command:`target_link_directories` +.. |PROPERTY_INTERFACE_NAME| replace:: ``INTERFACE_LINK_DIRECTORIES`` +.. |PROPERTY_LINK| replace:: :prop_tgt:`LINK_DIRECTORIES` +.. |PROPERTY_GENEX| replace:: ``$<TARGET_PROPERTY:foo,INTERFACE_LINK_DIRECTORIES>`` +.. include:: INTERFACE_BUILD_PROPERTY.txt diff --git a/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst 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..c293b98 --- /dev/null +++ b/Help/prop_tgt/INTERFACE_LINK_OPTIONS.rst @@ -0,0 +1,9 @@ +INTERFACE_LINK_OPTIONS +---------------------- + +.. |property_name| replace:: link options +.. |command_name| replace:: :command:`target_link_options` +.. |PROPERTY_INTERFACE_NAME| replace:: ``INTERFACE_LINK_OPTIONS`` +.. |PROPERTY_LINK| replace:: :prop_tgt:`LINK_OPTIONS` +.. |PROPERTY_GENEX| replace:: ``$<TARGET_PROPERTY:foo,INTERFACE_LINK_OPTIONS>`` +.. include:: INTERFACE_BUILD_PROPERTY.txt diff --git a/Help/prop_tgt/INTERFACE_POSITION_INDEPENDENT_CODE.rst b/Help/prop_tgt/INTERFACE_POSITION_INDEPENDENT_CODE.rst new file mode 100644 index 0000000..ea700df --- /dev/null +++ b/Help/prop_tgt/INTERFACE_POSITION_INDEPENDENT_CODE.rst @@ -0,0 +1,16 @@ +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. diff --git a/Help/prop_tgt/INTERFACE_SOURCES.rst b/Help/prop_tgt/INTERFACE_SOURCES.rst new file mode 100644 index 0000000..a224b68 --- /dev/null +++ b/Help/prop_tgt/INTERFACE_SOURCES.rst @@ -0,0 +1,18 @@ +INTERFACE_SOURCES +----------------- + +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..3f68c31 --- /dev/null +++ b/Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION.rst @@ -0,0 +1,11 @@ +INTERPROCEDURAL_OPTIMIZATION +---------------------------- + +Enable interprocedural optimization for a target. + +If set to true, enables interprocedural optimizations if they are +known to be supported by the compiler. + +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..782b0f0 --- /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 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..59f67a7 --- /dev/null +++ b/Help/prop_tgt/IOS_INSTALL_COMBINED.rst @@ -0,0 +1,11 @@ +IOS_INSTALL_COMBINED +-------------------- + +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. + +This feature requires at least Xcode version 6. 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/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..2887e23 --- /dev/null +++ b/Help/prop_tgt/LANG_CLANG_TIDY.rst @@ -0,0 +1,13 @@ +<LANG>_CLANG_TIDY +----------------- + +This property is implemented only when ``<LANG>`` is ``C`` or ``CXX``. + +Specify a :ref:`;-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..b63d6d7 --- /dev/null +++ b/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst @@ -0,0 +1,14 @@ +<LANG>_COMPILER_LAUNCHER +------------------------ + +This property is implemented only when ``<LANG>`` is ``C``, ``CXX``, +``Fortran``, or ``CUDA``. + +Specify a :ref:`;-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..5f8be00 --- /dev/null +++ b/Help/prop_tgt/LANG_CPPCHECK.rst @@ -0,0 +1,13 @@ +<LANG>_CPPCHECK +--------------- + +This property is supported only when ``<LANG>`` is ``C`` or ``CXX``. + +Specify a :ref:`;-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. + +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..14f47d4 --- /dev/null +++ b/Help/prop_tgt/LANG_CPPLINT.rst @@ -0,0 +1,13 @@ +<LANG>_CPPLINT +-------------- + +This property is supported only when ``<LANG>`` is ``C`` or ``CXX``. + +Specify a :ref:`;-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..26f6d16 --- /dev/null +++ b/Help/prop_tgt/LANG_INCLUDE_WHAT_YOU_USE.rst @@ -0,0 +1,13 @@ +<LANG>_INCLUDE_WHAT_YOU_USE +--------------------------- + +This property is implemented only when ``<LANG>`` is ``C`` or ``CXX``. + +Specify a :ref:`;-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..785a57b --- /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:: 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..28dd404 --- /dev/null +++ b/Help/prop_tgt/LIBRARY_OUTPUT_DIRECTORY_CONFIG.rst @@ -0,0 +1,16 @@ +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 (VS, 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..b1ca867 --- /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 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..3ab8658 --- /dev/null +++ b/Help/prop_tgt/LINK_DEPENDS.rst @@ -0,0 +1,17 @@ +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 Makefile and Ninja 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..085a701 --- /dev/null +++ b/Help/prop_tgt/LINK_DIRECTORIES.rst @@ -0,0 +1,18 @@ +LINK_DIRECTORIES +---------------- + +List of directories to use for the link step of shared library, module +and executable targets. + +This property holds a :ref:`;-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..e3918ca --- /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..4e26388 --- /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..5ea4a45 --- /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 +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..1fdb6ad --- /dev/null +++ b/Help/prop_tgt/LINK_LIBRARIES_INDIRECTION.txt @@ -0,0 +1,10 @@ +.. note:: + A call to :command:`target_link_libraries(<target> ...)` may update this + property on ``<target>``. If ``<target>`` was not created in the same + directory as the call then :command:`target_link_libraries` will add a + suffix of the form ``::@<directory-id>`` to each entry, where the + ``::@`` is a separator and the ``<directory-id>`` is unspecified. + This tells the generators that the named libraries must be looked up in + the scope of the caller rather than in the scope in which the + ``<target>`` was created. Valid directory ids are stripped on export + by the :command:`install(EXPORT)` and :command:`export` commands. diff --git a/Help/prop_tgt/LINK_OPTIONS.rst b/Help/prop_tgt/LINK_OPTIONS.rst new file mode 100644 index 0000000..bd5e937 --- /dev/null +++ b/Help/prop_tgt/LINK_OPTIONS.rst @@ -0,0 +1,24 @@ +LINK_OPTIONS +------------ + +List of options to use for the link step of shared library, module +and executable targets. Targets that are static libraries need to use +the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property. + + +This property holds a :ref:`;-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..cf9c871 --- /dev/null +++ b/Help/prop_tgt/LINK_SEARCH_END_STATIC.rst @@ -0,0 +1,18 @@ +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 +CMAKE_LINK_SEARCH_END_STATIC if it is set when a target is created. + +See also 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..2e0f9bd --- /dev/null +++ b/Help/prop_tgt/LINK_SEARCH_START_STATIC.rst @@ -0,0 +1,19 @@ +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 +CMAKE_LINK_SEARCH_START_STATIC if it is set when a target is created. + +See also 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..32d6edb --- /dev/null +++ b/Help/prop_tgt/LINK_WHAT_YOU_USE.rst @@ -0,0 +1,15 @@ +LINK_WHAT_YOU_USE +--------------------------- + +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..16d5696 --- /dev/null +++ b/Help/prop_tgt/LOCATION.rst @@ -0,0 +1,27 @@ +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 add_custom_command. The +path may contain a build-system-specific portion that is replaced at +build time with the configuration getting built (such as +"$(ConfigurationName)" in VS). In CMake 2.6 and above +add_custom_command automatically recognizes a target name in its +COMMAND and DEPENDS options and computes the target location. In +CMake 2.8.4 and above add_custom_command recognizes generator +expressions to refer to target locations anywhere in the command. +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..ac6bdb7 --- /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 +MAP_IMPORTED_CONFIG_<CONFIG> property to map imported configurations +explicitly. + +Do not set properties that affect the location of a target after +reading this property. These include properties whose names match +"(RUNTIME|LIBRARY|ARCHIVE)_OUTPUT_(NAME|DIRECTORY)(_<CONFIG>)?", +``(IMPLIB_)?(PREFIX|SUFFIX)``, or "LINKER_LANGUAGE". Failure to follow +this rule is not diagnosed and leaves the location of the target +undefined. 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..c12ea14 --- /dev/null +++ b/Help/prop_tgt/MANUALLY_ADDED_DEPENDENCIES.rst @@ -0,0 +1,8 @@ +MANUALLY_ADDED_DEPENDENCIES +--------------------------- + +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/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..ee45ed8 --- /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/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/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..77fda90 --- /dev/null +++ b/Help/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG.rst @@ -0,0 +1,18 @@ +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 (VS, 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..54af8c6 --- /dev/null +++ b/Help/prop_tgt/POSITION_INDEPENDENT_CODE.rst @@ -0,0 +1,11 @@ +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. diff --git a/Help/prop_tgt/POST_INSTALL_SCRIPT.rst b/Help/prop_tgt/POST_INSTALL_SCRIPT.rst new file mode 100644 index 0000000..f1adb40 --- /dev/null +++ b/Help/prop_tgt/POST_INSTALL_SCRIPT.rst @@ -0,0 +1,9 @@ +POST_INSTALL_SCRIPT +------------------- + +Deprecated install support. + +The PRE_INSTALL_SCRIPT and POST_INSTALL_SCRIPT properties are the old +way to specify CMake scripts to run before and after installing a +target. They are used only when the old INSTALL_TARGETS command is +used to install the target. Use the INSTALL command instead. diff --git a/Help/prop_tgt/PREFIX.rst b/Help/prop_tgt/PREFIX.rst new file mode 100644 index 0000000..a165104 --- /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..113d7c5 --- /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 POST_INSTALL_SCRIPT properties are the old +way to specify CMake scripts to run before and after installing a +target. They are used only when the old INSTALL_TARGETS command is +used to install the target. Use the INSTALL command instead. diff --git a/Help/prop_tgt/PRIVATE_HEADER.rst b/Help/prop_tgt/PRIVATE_HEADER.rst new file mode 100644 index 0000000..2bd4079 --- /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 ``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..549ac7c --- /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 +``install(TARGETS)`` command. diff --git a/Help/prop_tgt/RESOURCE.rst b/Help/prop_tgt/RESOURCE.rst new file mode 100644 index 0000000..55ae774 --- /dev/null +++ b/Help/prop_tgt/RESOURCE.rst @@ -0,0 +1,61 @@ +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 ``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..12390f5 --- /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:: 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..94fb277 --- /dev/null +++ b/Help/prop_tgt/RUNTIME_OUTPUT_DIRECTORY_CONFIG.rst @@ -0,0 +1,16 @@ +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 (VS, 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..a91fa9c --- /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 +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..b25813b --- /dev/null +++ b/Help/prop_tgt/SOURCE_DIR.rst @@ -0,0 +1,6 @@ +SOURCE_DIR +---------- + +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..b07c17c --- /dev/null +++ b/Help/prop_tgt/SOVERSION.rst @@ -0,0 +1,27 @@ +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 *compatibility version* and +:prop_tgt:`VERSION` to *current version*. See the :prop_tgt:`FRAMEWORK` target +property for an example. Versions of Mach-O binaries may be checked with the +``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..6e03185 --- /dev/null +++ b/Help/prop_tgt/STATIC_LIBRARY_OPTIONS.rst @@ -0,0 +1,20 @@ +STATIC_LIBRARY_OPTIONS +---------------------- + +Archiver (or MSVC librarian) flags for a static library target. +Targets that are shared libraries, modules, or executables need to use +the :prop_tgt:`LINK_OPTIONS` target property. + +This property holds a :ref:`;-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..70844be --- /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/TYPE.rst b/Help/prop_tgt/TYPE.rst new file mode 100644 index 0000000..1cd9db4 --- /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/VERSION.rst b/Help/prop_tgt/VERSION.rst new file mode 100644 index 0000000..ff3b303 --- /dev/null +++ b/Help/prop_tgt/VERSION.rst @@ -0,0 +1,29 @@ +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 correspond to *compatibility version* and +``VERSION`` to *current version*. See the :prop_tgt:`FRAMEWORK` target +property for an example. Versions of Mach-O binaries may be checked with the +``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..ff987ff --- /dev/null +++ b/Help/prop_tgt/VS_CONFIGURATION_TYPE.rst @@ -0,0 +1,10 @@ +VS_CONFIGURATION_TYPE +--------------------- + +Visual Studio project configuration type. + +Sets the ``ConfigurationType`` attribute for a generated Visual Studio project. +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..ba5fd0a --- /dev/null +++ b/Help/prop_tgt/VS_DEBUGGER_COMMAND.rst @@ -0,0 +1,11 @@ +VS_DEBUGGER_COMMAND +------------------- + +Sets the local debugger command for Visual Studio C++ targets. +The property value may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. +This is defined in ``<LocalDebuggerCommand>`` in the Visual Studio +project file. + +This property only works for Visual Studio 2010 and above; +it is ignored on other generators. diff --git a/Help/prop_tgt/VS_DEBUGGER_COMMAND_ARGUMENTS.rst b/Help/prop_tgt/VS_DEBUGGER_COMMAND_ARGUMENTS.rst new file mode 100644 index 0000000..06ef5d5 --- /dev/null +++ b/Help/prop_tgt/VS_DEBUGGER_COMMAND_ARGUMENTS.rst @@ -0,0 +1,11 @@ +VS_DEBUGGER_COMMAND_ARGUMENTS +----------------------------- + +Sets the local debugger command line arguments for Visual Studio C++ targets. +The property value may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. +This is defined in ``<LocalDebuggerCommandArguments>`` in the Visual Studio +project file. + +This property only works for Visual Studio 2010 and above; +it is ignored on other generators. diff --git a/Help/prop_tgt/VS_DEBUGGER_ENVIRONMENT.rst b/Help/prop_tgt/VS_DEBUGGER_ENVIRONMENT.rst new file mode 100644 index 0000000..f55ac7b --- /dev/null +++ b/Help/prop_tgt/VS_DEBUGGER_ENVIRONMENT.rst @@ -0,0 +1,11 @@ +VS_DEBUGGER_ENVIRONMENT +----------------------- + +Sets the local debugger environment for Visual Studio C++ targets. +The property value may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. +This is defined in ``<LocalDebuggerEnvironment>`` in the Visual Studio +project file. + +This property only works for Visual Studio 2010 and above; +it is ignored on other generators. diff --git a/Help/prop_tgt/VS_DEBUGGER_WORKING_DIRECTORY.rst b/Help/prop_tgt/VS_DEBUGGER_WORKING_DIRECTORY.rst new file mode 100644 index 0000000..008bbf6 --- /dev/null +++ b/Help/prop_tgt/VS_DEBUGGER_WORKING_DIRECTORY.rst @@ -0,0 +1,11 @@ +VS_DEBUGGER_WORKING_DIRECTORY +----------------------------- + +Sets the local debugger working directory for Visual Studio C++ targets. +The property value may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. +This is defined in ``<LocalDebuggerWorkingDirectory>`` in the Visual Studio +project file. + +This property only works for Visual Studio 2010 and above; +it is ignored on other generators. diff --git a/Help/prop_tgt/VS_DESKTOP_EXTENSIONS_VERSION.rst b/Help/prop_tgt/VS_DESKTOP_EXTENSIONS_VERSION.rst new file mode 100644 index 0000000..19d1620 --- /dev/null +++ b/Help/prop_tgt/VS_DESKTOP_EXTENSIONS_VERSION.rst @@ -0,0 +1,10 @@ +VS_DESKTOP_EXTENSIONS_VERSION +----------------------------- + +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_REFERENCEPROP_refname_TAG_tagname.rst b/Help/prop_tgt/VS_DOTNET_REFERENCEPROP_refname_TAG_tagname.rst new file mode 100644 index 0000000..ab311ea --- /dev/null +++ b/Help/prop_tgt/VS_DOTNET_REFERENCEPROP_refname_TAG_tagname.rst @@ -0,0 +1,14 @@ +VS_DOTNET_REFERENCEPROP_<refname>_TAG_<tagname> +----------------------------------------------- + +Defines an XML property ``<tagname>`` for a .NET reference +``<refname>``. + +Reference properties can be set for .NET references which are +defined by the target properties :prop_tgt:`VS_DOTNET_REFERENCES`, +:prop_tgt:`VS_DOTNET_REFERENCE_<refname>` +and also for project references to other C# targets which are +established by :command:`target_link_libraries()`. + +This property is only applicable to C# targets and Visual Studio +generators 2010 and later. diff --git a/Help/prop_tgt/VS_DOTNET_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..7641ba5 --- /dev/null +++ b/Help/prop_tgt/VS_DOTNET_REFERENCES_COPY_LOCAL.rst @@ -0,0 +1,7 @@ +VS_DOTNET_REFERENCES_COPY_LOCAL +------------------------------- + +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..5814005 --- /dev/null +++ b/Help/prop_tgt/VS_DOTNET_REFERENCE_refname.rst @@ -0,0 +1,12 @@ +VS_DOTNET_REFERENCE_<refname> +----------------------------- + +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..9f5a313 --- /dev/null +++ b/Help/prop_tgt/VS_DOTNET_TARGET_FRAMEWORK_VERSION.rst @@ -0,0 +1,10 @@ +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_VERSION` instead. 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..27c8a3d --- /dev/null +++ b/Help/prop_tgt/VS_IOT_EXTENSIONS_VERSION.rst @@ -0,0 +1,10 @@ +VS_IOT_EXTENSIONS_VERSION +------------------------- + +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..add50cb --- /dev/null +++ b/Help/prop_tgt/VS_IOT_STARTUP_TASK.rst @@ -0,0 +1,6 @@ +VS_IOT_STARTUP_TASK +------------------- + +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_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..be3c9a0 --- /dev/null +++ b/Help/prop_tgt/VS_MOBILE_EXTENSIONS_VERSION.rst @@ -0,0 +1,10 @@ +VS_MOBILE_EXTENSIONS_VERSION +---------------------------- + +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_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..769a0d1 --- /dev/null +++ b/Help/prop_tgt/VS_SDK_REFERENCES.rst @@ -0,0 +1,7 @@ +VS_SDK_REFERENCES +----------------- + +Visual Studio project SDK references. +Specify a :ref:`;-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_USER_PROPS.rst b/Help/prop_tgt/VS_USER_PROPS.rst new file mode 100644 index 0000000..1be222b --- /dev/null +++ b/Help/prop_tgt/VS_USER_PROPS.rst @@ -0,0 +1,12 @@ +VS_USER_PROPS +------------- + +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..1ad7a71 --- /dev/null +++ b/Help/prop_tgt/VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION.rst @@ -0,0 +1,10 @@ +VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION +-------------------------------------- + +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..e160bd6 --- /dev/null +++ b/Help/prop_tgt/VS_WINRT_COMPONENT.rst @@ -0,0 +1,11 @@ +VS_WINRT_COMPONENT +------------------ + +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..336d5f7 --- /dev/null +++ b/Help/prop_tgt/WIN32_EXECUTABLE.rst @@ -0,0 +1,12 @@ +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 CMAKE_MFC_FLAG variable documentation to +configure use of MFC for WinMain executables. This property is +initialized by the value of the variable CMAKE_WIN32_EXECUTABLE if it +is set when a target is created. 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..86711bf --- /dev/null +++ b/Help/prop_tgt/WINDOWS_EXPORT_ALL_SYMBOLS.rst @@ -0,0 +1,26 @@ +WINDOWS_EXPORT_ALL_SYMBOLS +-------------------------- + +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..7e00ac4 --- /dev/null +++ b/Help/prop_tgt/XCODE_ATTRIBUTE_an-attribute.rst @@ -0,0 +1,16 @@ +XCODE_ATTRIBUTE_<an-attribute> +------------------------------ + +Set Xcode target attributes directly. + +Tell the Xcode generator to set '<an-attribute>' to a given value in +the generated Xcode project. Ignored on other generators. + +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_EXPLICIT_FILE_TYPE.rst b/Help/prop_tgt/XCODE_EXPLICIT_FILE_TYPE.rst new file mode 100644 index 0000000..dc92902 --- /dev/null +++ b/Help/prop_tgt/XCODE_EXPLICIT_FILE_TYPE.rst @@ -0,0 +1,8 @@ +XCODE_EXPLICIT_FILE_TYPE +------------------------ + +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_PRODUCT_TYPE.rst b/Help/prop_tgt/XCODE_PRODUCT_TYPE.rst new file mode 100644 index 0000000..f4ef5c0 --- /dev/null +++ b/Help/prop_tgt/XCODE_PRODUCT_TYPE.rst @@ -0,0 +1,8 @@ +XCODE_PRODUCT_TYPE +------------------ + +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..694cd77 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_ADDRESS_SANITIZER +------------------------------ + +Whether to enable ``Address Sanitizer`` in the Diagnostics +section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER` if it is set +when a target is created. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +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..2803da0 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN +----------------------------------------------- + +Whether to enable ``Detect use of stack after return`` +in the Diagnostics section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN` +if it is set when a target is created. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +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..2eac4a9 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_ARGUMENTS.rst @@ -0,0 +1,10 @@ +XCODE_SCHEME_ARGUMENTS +---------------------- + +Specify command line arguments that should be added to the Arguments +section of the generated Xcode scheme. + +If set to a list of arguments those will be added to the scheme. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +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..75fc326 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER +---------------------------------------- + +Whether to disable the ``Main Thread Checker`` +in the Diagnostics section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER` +if it is set when a target is created. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +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..a7fab66 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS +---------------------------------- + +Whether to enable ``Dynamic Library Loads`` +in the Diagnostics section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS` if it is set +when a target is created. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +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..162fc45 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE +------------------------------------- + +Whether to enable ``Dynamic Linker API usage`` +in the Diagnostics section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE` if it is set +when a target is created. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +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..1dbd6c4 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_ENVIRONMENT.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_ENVIRONMENT +------------------------ + +Specify environment variables that should be added to the Arguments +section of the generated Xcode scheme. + +If set to a list of environment variables and values of the form +``MYVAR=value`` those environment variables will be added to the +scheme. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +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..d0427e2 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_EXECUTABLE.rst @@ -0,0 +1,9 @@ +XCODE_SCHEME_EXECUTABLE +----------------------- + +Specify path to executable in the Info section of the generated +Xcode scheme. If not set the schema generator will select the +current target if it is actually executable. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +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..64e1990 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_GUARD_MALLOC.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_GUARD_MALLOC +------------------------------ + +Whether to enable ``Guard Malloc`` +in the Diagnostics section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_GUARD_MALLOC` if it is set +when a target is created. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +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..99c112f --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP.rst @@ -0,0 +1,13 @@ +XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP +------------------------------------- + +Whether to enable the ``Main Thread Checker`` option +``Pause on issues`` +in the Diagnostics section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP` if it is set +when a target is created. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +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..ef3852a --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_MALLOC_GUARD_EDGES.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_MALLOC_GUARD_EDGES +------------------------------- + +Whether to enable ``Malloc Guard Edges`` +in the Diagnostics section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES` if it is set +when a target is created. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +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..75baba2 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_MALLOC_SCRIBBLE.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_MALLOC_SCRIBBLE +------------------------------ + +Whether to enable ``Malloc Scribble`` +in the Diagnostics section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE` if it is set +when a target is created. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +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..984022c --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_MALLOC_STACK.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_MALLOC_STACK +------------------------- + +Whether to enable ``Malloc Stack`` in the Diagnostics +section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_MALLOC_STACK` if it is set +when a target is created. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +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..825ac5b --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_THREAD_SANITIZER.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_THREAD_SANITIZER +----------------------------- + +Whether to enable ``Thread Sanitizer`` in the Diagnostics +section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_THREAD_SANITIZER` if it is set +when a target is created. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +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..86f894e --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_THREAD_SANITIZER_STOP.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_THREAD_SANITIZER_STOP +---------------------------------- + +Whether to enable ``Thread Sanitizer - Pause on issues`` +in the Diagnostics section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP` if it is set +when a target is created. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +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..829a62e --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER +------------------------------------------ + +Whether to enable ``Undefined Behavior Sanitizer`` +in the Diagnostics section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER` +if it is set when a target is created. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +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..5e382ca --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP.rst @@ -0,0 +1,13 @@ +XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP +----------------------------------------------- + +Whether to enable ``Undefined Behavior Sanitizer`` option +``Pause on issues`` +in the Diagnostics section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP` +if it is set when a target is created. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +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..80b954a --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_ZOMBIE_OBJECTS.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_ZOMBIE_OBJECTS +------------------------------ + +Whether to enable ``Zombie Objects`` +in the Diagnostics section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS` if it is set +when a target is created. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +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..eb47e60 --- /dev/null +++ b/Help/prop_tgt/XCTEST.rst @@ -0,0 +1,13 @@ +XCTEST +------ + +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..3ae5448 --- /dev/null +++ b/Help/prop_tgt/XXX_OUTPUT_DIRECTORY.txt @@ -0,0 +1,11 @@ +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 (VS, Xcode) 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_XXX_OUTPUT_DIRECTORY| 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..8278353 --- /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 univerally 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 :manual:`cpack(1)` ``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..66a1d09 --- /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..b08f21d --- /dev/null +++ b/Help/release/3.13.rst @@ -0,0 +1,232 @@ +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 udpated: + + - 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(CODE)` and :command:`install(SCRIPT)` commands + learned to support generator expressions. + +* 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:`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. + +* 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 :command:`option` command now honors existing normal variables instead + of replacing them with a cache entry. 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. 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.3.rst b/Help/release/3.3.rst new file mode 100644 index 0000000..11f0c60 --- /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 shorcuts 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..0a0e6df --- /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..f988908 --- /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 DMG 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 DMG 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..c796d70 --- /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 DMG 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:`;-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..fae10f5 --- /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..5001e90 --- /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 ``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/index.rst b/Help/release/index.rst new file mode 100644 index 0000000..7ef3a8e --- /dev/null +++ b/Help/release/index.rst @@ -0,0 +1,31 @@ +: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.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..fede4ca --- /dev/null +++ b/Help/variable/ANDROID.rst @@ -0,0 +1,5 @@ +ANDROID +------- + +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..230739a --- /dev/null +++ b/Help/variable/CACHE.rst @@ -0,0 +1,17 @@ +CACHE +----- + +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` command to see how to write 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_ANDROID_ANT_ADDITIONAL_OPTIONS.rst b/Help/variable/CMAKE_ANDROID_ANT_ADDITIONAL_OPTIONS.rst new file mode 100644 index 0000000..8862ba9 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_ANT_ADDITIONAL_OPTIONS.rst @@ -0,0 +1,5 @@ +CMAKE_ANDROID_ANT_ADDITIONAL_OPTIONS +------------------------------------ + +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..c07a05a --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_API.rst @@ -0,0 +1,11 @@ +CMAKE_ANDROID_API +----------------- + +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..0246c75 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_API_MIN.rst @@ -0,0 +1,5 @@ +CMAKE_ANDROID_API_MIN +--------------------- + +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..b91ca57 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_ARCH.rst @@ -0,0 +1,19 @@ +CMAKE_ANDROID_ARCH +------------------ + +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..0a3ed3c --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_ARCH_ABI.rst @@ -0,0 +1,17 @@ +CMAKE_ANDROID_ARCH_ABI +---------------------- + +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..ad3c37c --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_ARM_MODE.rst @@ -0,0 +1,7 @@ +CMAKE_ANDROID_ARM_MODE +---------------------- + +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..4b7ae03 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_ARM_NEON.rst @@ -0,0 +1,6 @@ +CMAKE_ANDROID_ARM_NEON +---------------------- + +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..c372fe4 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_ASSETS_DIRECTORIES.rst @@ -0,0 +1,5 @@ +CMAKE_ANDROID_ASSETS_DIRECTORIES +-------------------------------- + +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_GUI.rst b/Help/variable/CMAKE_ANDROID_GUI.rst new file mode 100644 index 0000000..1755375 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_GUI.rst @@ -0,0 +1,5 @@ +CMAKE_ANDROID_GUI +----------------- + +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..451a929 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_JAR_DEPENDENCIES.rst @@ -0,0 +1,5 @@ +CMAKE_ANDROID_JAR_DEPENDENCIES +------------------------------ + +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..af83e34 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_JAR_DIRECTORIES.rst @@ -0,0 +1,5 @@ +CMAKE_ANDROID_JAR_DIRECTORIES +----------------------------- + +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..3dc05e0 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_JAVA_SOURCE_DIR.rst @@ -0,0 +1,5 @@ +CMAKE_ANDROID_JAVA_SOURCE_DIR +----------------------------- + +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..4191907 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_NATIVE_LIB_DEPENDENCIES.rst @@ -0,0 +1,5 @@ +CMAKE_ANDROID_NATIVE_LIB_DEPENDENCIES +------------------------------------- + +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..7cb9527 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_NATIVE_LIB_DIRECTORIES.rst @@ -0,0 +1,5 @@ +CMAKE_ANDROID_NATIVE_LIB_DIRECTORIES +------------------------------------ + +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..d241dd0 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_NDK.rst @@ -0,0 +1,7 @@ +CMAKE_ANDROID_NDK +----------------- + +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..8ea1257 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_NDK_DEPRECATED_HEADERS.rst @@ -0,0 +1,9 @@ +CMAKE_ANDROID_NDK_DEPRECATED_HEADERS +------------------------------------ + +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..207019a --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_NDK_TOOLCHAIN_HOST_TAG.rst @@ -0,0 +1,6 @@ +CMAKE_ANDROID_NDK_TOOLCHAIN_HOST_TAG +------------------------------------ + +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..5ae55d1 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION.rst @@ -0,0 +1,16 @@ +CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION +----------------------------------- + +When :ref:`Cross Compiling for Android with the NDK`, this variable +may be set to specify the version of the toolchain to be used +as the compiler. The variable must be set to one of these forms: + +* ``<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_PROCESS_MAX.rst b/Help/variable/CMAKE_ANDROID_PROCESS_MAX.rst new file mode 100644 index 0000000..19fb527 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_PROCESS_MAX.rst @@ -0,0 +1,5 @@ +CMAKE_ANDROID_PROCESS_MAX +------------------------- + +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..b8fdd46 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_PROGUARD.rst @@ -0,0 +1,5 @@ +CMAKE_ANDROID_PROGUARD +---------------------- + +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..8dea009 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_PROGUARD_CONFIG_PATH.rst @@ -0,0 +1,5 @@ +CMAKE_ANDROID_PROGUARD_CONFIG_PATH +---------------------------------- + +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_SECURE_PROPS_PATH.rst b/Help/variable/CMAKE_ANDROID_SECURE_PROPS_PATH.rst new file mode 100644 index 0000000..69a4d0b --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_SECURE_PROPS_PATH.rst @@ -0,0 +1,5 @@ +CMAKE_ANDROID_SECURE_PROPS_PATH +------------------------------- + +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..0a96df9 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_SKIP_ANT_STEP.rst @@ -0,0 +1,5 @@ +CMAKE_ANDROID_SKIP_ANT_STEP +--------------------------- + +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..ea62cab --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_STANDALONE_TOOLCHAIN.rst @@ -0,0 +1,6 @@ +CMAKE_ANDROID_STANDALONE_TOOLCHAIN +---------------------------------- + +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..d174575 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_STL_TYPE.rst @@ -0,0 +1,37 @@ +CMAKE_ANDROID_STL_TYPE +---------------------- + +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..c1f0951 --- /dev/null +++ b/Help/variable/CMAKE_APPBUNDLE_PATH.rst @@ -0,0 +1,6 @@ +CMAKE_APPBUNDLE_PATH +-------------------- + +:ref:`;-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_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..94c2b6e --- /dev/null +++ b/Help/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG.rst @@ -0,0 +1,9 @@ +CMAKE_ARCHIVE_OUTPUT_DIRECTORY_<CONFIG> +--------------------------------------- + +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..aec9711 --- /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 <CMake Options>` 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..8b1ecb7 --- /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 <CMake Options>` 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_PARALLEL.rst b/Help/variable/CMAKE_AUTOGEN_PARALLEL.rst new file mode 100644 index 0000000..dd9499a --- /dev/null +++ b/Help/variable/CMAKE_AUTOGEN_PARALLEL.rst @@ -0,0 +1,10 @@ +CMAKE_AUTOGEN_PARALLEL +---------------------- + +Number of parallel ``moc`` or ``uic`` processes to start when using +:prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`. + +This variable is used to initialize the :prop_tgt:`AUTOGEN_PARALLEL` property +on all the targets. See that target property for additional information. + +By default :variable:`CMAKE_AUTOGEN_PARALLEL` is unset. diff --git a/Help/variable/CMAKE_AUTOGEN_VERBOSE.rst b/Help/variable/CMAKE_AUTOGEN_VERBOSE.rst new file mode 100644 index 0000000..bad9cf2 --- /dev/null +++ b/Help/variable/CMAKE_AUTOGEN_VERBOSE.rst @@ -0,0 +1,13 @@ +CMAKE_AUTOGEN_VERBOSE +--------------------- + +Sets the verbosity of :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTOUIC` and +:prop_tgt:`AUTORCC`. A positive integer value or a true boolean value +lets the ``AUTO*`` generators output additional processing information. + +Setting :variable:`CMAKE_AUTOGEN_VERBOSE` has the same effect +as setting the ``VERBOSE`` environment variable during +generation (e.g. by calling ``make VERBOSE=1``). +The extra verbosity is limited to the ``AUTO*`` generators though. + +By default :variable:`CMAKE_AUTOGEN_VERBOSE` is unset. diff --git a/Help/variable/CMAKE_AUTOMOC.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..7e1c53d --- /dev/null +++ b/Help/variable/CMAKE_AUTOMOC_COMPILER_PREDEFINES.rst @@ -0,0 +1,8 @@ +CMAKE_AUTOMOC_COMPILER_PREDEFINES +--------------------------------- + +This variable is used to initialize the :prop_tgt:`AUTOMOC_COMPILER_PREDEFINES` +property on all the targets. See that target property for additional +information. + +By default it is ON. diff --git a/Help/variable/CMAKE_AUTOMOC_DEPEND_FILTERS.rst b/Help/variable/CMAKE_AUTOMOC_DEPEND_FILTERS.rst new file mode 100644 index 0000000..5c3662d --- /dev/null +++ b/Help/variable/CMAKE_AUTOMOC_DEPEND_FILTERS.rst @@ -0,0 +1,12 @@ +CMAKE_AUTOMOC_DEPEND_FILTERS +---------------------------- + +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..2c8997b --- /dev/null +++ b/Help/variable/CMAKE_AUTOMOC_MACRO_NAMES.rst @@ -0,0 +1,20 @@ +CMAKE_AUTOMOC_MACRO_NAMES +---------------------------- + +A :ref:`;-list <CMake Language Lists>` list of macro names used by +:variable:`CMAKE_AUTOMOC` to determine if a C++ file needs to be +processed by ``moc``. + +This variable is used to initialize the :prop_tgt:`AUTOMOC_MACRO_NAMES` +property on all the targets. See that target property for additional +information. + +The default value is ``Q_OBJECT;Q_GADGET;Q_NAMESPACE``. + +Example +^^^^^^^ +Let CMake know that source files that contain ``CUSTOM_MACRO`` must be ``moc`` +processed as well:: + + set(CMAKE_AUTOMOC ON) + list(APPEND CMAKE_AUTOMOC_MACRO_NAMES "CUSTOM_MACRO") diff --git a/Help/variable/CMAKE_AUTOMOC_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_RELAXED_MODE.rst b/Help/variable/CMAKE_AUTOMOC_RELAXED_MODE.rst new file mode 100644 index 0000000..addc62d --- /dev/null +++ b/Help/variable/CMAKE_AUTOMOC_RELAXED_MODE.rst @@ -0,0 +1,13 @@ +CMAKE_AUTOMOC_RELAXED_MODE +-------------------------- + +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..aa132bf --- /dev/null +++ b/Help/variable/CMAKE_AUTOUIC_SEARCH_PATHS.rst @@ -0,0 +1,11 @@ +CMAKE_AUTOUIC_SEARCH_PATHS +-------------------------- + +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..f20eb41 --- /dev/null +++ b/Help/variable/CMAKE_BUILD_RPATH.rst @@ -0,0 +1,10 @@ +CMAKE_BUILD_RPATH +----------------- + +A :ref:`;-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_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..2d35635 --- /dev/null +++ b/Help/variable/CMAKE_BUILD_TYPE.rst @@ -0,0 +1,20 @@ +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`. 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..30d5d3b --- /dev/null +++ b/Help/variable/CMAKE_BUILD_WITH_INSTALL_NAME_DIR.rst @@ -0,0 +1,7 @@ +CMAKE_BUILD_WITH_INSTALL_NAME_DIR +--------------------------------- + +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..af82f75 --- /dev/null +++ b/Help/variable/CMAKE_CFG_INTDIR.rst @@ -0,0 +1,45 @@ +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 + +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_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..ad2709d --- /dev/null +++ b/Help/variable/CMAKE_CODEBLOCKS_COMPILER_ID.rst @@ -0,0 +1,13 @@ +CMAKE_CODEBLOCKS_COMPILER_ID +---------------------------- + +Change the compiler id in the generated CodeBlocks project files. + +CodeBlocks uses its own compiler id string which differs from +:variable:`CMAKE_<LANG>_COMPILER_ID`. If this variable is left empty, +CMake tries to recognize the CodeBlocks compiler id automatically. +Otherwise the specified string is used in the CodeBlocks project file. +See the CodeBlocks documentation for valid compiler id strings. + +Other IDEs like QtCreator that also use the CodeBlocks generator may ignore +this setting. diff --git a/Help/variable/CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES.rst b/Help/variable/CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES.rst new file mode 100644 index 0000000..80ffce3 --- /dev/null +++ b/Help/variable/CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES.rst @@ -0,0 +1,7 @@ +CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES +--------------------------------------- + +Change the way the CodeBlocks generator creates project files. + +If this variable evaluates to ``ON`` the generator excludes from +the project file any files that are located outside the project root. diff --git a/Help/variable/CMAKE_CODELITE_USE_TARGETS.rst b/Help/variable/CMAKE_CODELITE_USE_TARGETS.rst new file mode 100644 index 0000000..33cdf6c --- /dev/null +++ b/Help/variable/CMAKE_CODELITE_USE_TARGETS.rst @@ -0,0 +1,8 @@ +CMAKE_CODELITE_USE_TARGETS +-------------------------- + +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..a40667e --- /dev/null +++ b/Help/variable/CMAKE_COMPILER_IS_GNUCC.rst @@ -0,0 +1,5 @@ +CMAKE_COMPILER_IS_GNUCC +----------------------- + +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..f1f5cf7 --- /dev/null +++ b/Help/variable/CMAKE_COMPILER_IS_GNUCXX.rst @@ -0,0 +1,5 @@ +CMAKE_COMPILER_IS_GNUCXX +------------------------ + +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..3d6dab4 --- /dev/null +++ b/Help/variable/CMAKE_COMPILER_IS_GNUG77.rst @@ -0,0 +1,5 @@ +CMAKE_COMPILER_IS_GNUG77 +------------------------ + +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..ea33c7d --- /dev/null +++ b/Help/variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY.rst @@ -0,0 +1,8 @@ +CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY +---------------------------------- + +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..fdeb9ab --- /dev/null +++ b/Help/variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG.rst @@ -0,0 +1,11 @@ +CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG> +------------------------------------------- + +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..559108a --- /dev/null +++ b/Help/variable/CMAKE_CPACK_COMMAND.rst @@ -0,0 +1,8 @@ +CMAKE_CPACK_COMMAND +------------------- + +Full path to :manual:`cpack(1)` command installed with CMake. + +This is the full path to the CPack executable :manual:`cpack(1)` which is +useful from custom commands that want to use the :manual:`cmake(1)` ``-E`` +option for portable system commands. diff --git a/Help/variable/CMAKE_CROSSCOMPILING.rst b/Help/variable/CMAKE_CROSSCOMPILING.rst new file mode 100644 index 0000000..9e96769 --- /dev/null +++ b/Help/variable/CMAKE_CROSSCOMPILING.rst @@ -0,0 +1,26 @@ +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 +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..95d2c7f --- /dev/null +++ b/Help/variable/CMAKE_CROSSCOMPILING_EMULATOR.rst @@ -0,0 +1,12 @@ +CMAKE_CROSSCOMPILING_EMULATOR +----------------------------- + +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. + +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_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_EXTENSIONS.rst b/Help/variable/CMAKE_CUDA_EXTENSIONS.rst new file mode 100644 index 0000000..4fe758e --- /dev/null +++ b/Help/variable/CMAKE_CUDA_EXTENSIONS.rst @@ -0,0 +1,11 @@ +CMAKE_CUDA_EXTENSIONS +--------------------- + +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..72e8e66 --- /dev/null +++ b/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst @@ -0,0 +1,7 @@ +CMAKE_CUDA_HOST_COMPILER +------------------------ + +Executable to use when compiling host code when compiling ``CUDA`` language +files. Maps to the nvcc -ccbin option. Will only be used by CMake on the first +configuration to determine a valid host compiler for ``CUDA``. After a valid +host compiler has been found, this value is read-only. diff --git a/Help/variable/CMAKE_CUDA_SEPARABLE_COMPILATION.rst b/Help/variable/CMAKE_CUDA_SEPARABLE_COMPILATION.rst new file mode 100644 index 0000000..eef92fb --- /dev/null +++ b/Help/variable/CMAKE_CUDA_SEPARABLE_COMPILATION.rst @@ -0,0 +1,6 @@ +CMAKE_CUDA_SEPARABLE_COMPILATION +-------------------------------- + +Default value for :prop_tgt:`CUDA_SEPARABLE_COMPILATION` target property. +This variable is used to initialize the property on each target as it is +created. diff --git a/Help/variable/CMAKE_CUDA_STANDARD.rst b/Help/variable/CMAKE_CUDA_STANDARD.rst new file mode 100644 index 0000000..6c23031 --- /dev/null +++ b/Help/variable/CMAKE_CUDA_STANDARD.rst @@ -0,0 +1,11 @@ +CMAKE_CUDA_STANDARD +------------------- + +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..935d605 --- /dev/null +++ b/Help/variable/CMAKE_CUDA_STANDARD_REQUIRED.rst @@ -0,0 +1,11 @@ +CMAKE_CUDA_STANDARD_REQUIRED +---------------------------- + +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..768f571 --- /dev/null +++ b/Help/variable/CMAKE_CUDA_TOOLKIT_INCLUDE_DIRECTORIES.rst @@ -0,0 +1,7 @@ +CMAKE_CUDA_TOOLKIT_INCLUDE_DIRECTORIES +-------------------------------------- + +When the ``CUDA`` language has been enabled, this provides a +:ref:`;-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_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..60e8e26 --- /dev/null +++ b/Help/variable/CMAKE_CURRENT_LIST_LINE.rst @@ -0,0 +1,7 @@ +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. 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..5c59f95 --- /dev/null +++ b/Help/variable/CMAKE_CXX_COMPILE_FEATURES.rst @@ -0,0 +1,11 @@ +CMAKE_CXX_COMPILE_FEATURES +-------------------------- + +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..4a92425 --- /dev/null +++ b/Help/variable/CMAKE_CXX_EXTENSIONS.rst @@ -0,0 +1,11 @@ +CMAKE_CXX_EXTENSIONS +-------------------- + +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..8a8bdff --- /dev/null +++ b/Help/variable/CMAKE_CXX_STANDARD.rst @@ -0,0 +1,11 @@ +CMAKE_CXX_STANDARD +------------------ + +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..4c71058 --- /dev/null +++ b/Help/variable/CMAKE_CXX_STANDARD_REQUIRED.rst @@ -0,0 +1,11 @@ +CMAKE_CXX_STANDARD_REQUIRED +--------------------------- + +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..8d1eca0 --- /dev/null +++ b/Help/variable/CMAKE_C_COMPILE_FEATURES.rst @@ -0,0 +1,11 @@ +CMAKE_C_COMPILE_FEATURES +------------------------ + +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..fa510d4 --- /dev/null +++ b/Help/variable/CMAKE_C_EXTENSIONS.rst @@ -0,0 +1,11 @@ +CMAKE_C_EXTENSIONS +------------------ + +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..b55e00c --- /dev/null +++ b/Help/variable/CMAKE_C_STANDARD.rst @@ -0,0 +1,11 @@ +CMAKE_C_STANDARD +---------------- + +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..7f70f6e --- /dev/null +++ b/Help/variable/CMAKE_C_STANDARD_REQUIRED.rst @@ -0,0 +1,11 @@ +CMAKE_C_STANDARD_REQUIRED +------------------------- + +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..513276e --- /dev/null +++ b/Help/variable/CMAKE_DEBUG_TARGET_PROPERTIES.rst @@ -0,0 +1,14 @@ +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 the :prop_tgt:`INCLUDE_DIRECTORIES`, +:prop_tgt:`COMPILE_DEFINITIONS`, :prop_tgt:`COMPILE_OPTIONS`, +:prop_tgt:`AUTOUIC_OPTIONS`, :prop_tgt:`SOURCES`, :prop_tgt:`COMPILE_FEATURES`, +:prop_tgt:`POSITION_INDEPENDENT_CODE` target properties and any other property +listed in :prop_tgt:`COMPATIBLE_INTERFACE_STRING` and other +``COMPATIBLE_INTERFACE_`` properties. It outputs an origin for each entry in +the target property. Default is unset. 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..7179071 --- /dev/null +++ b/Help/variable/CMAKE_DEPENDS_IN_PROJECT_ONLY.rst @@ -0,0 +1,10 @@ +CMAKE_DEPENDS_IN_PROJECT_ONLY +----------------------------- + +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_DIRECTORY_LABELS.rst b/Help/variable/CMAKE_DIRECTORY_LABELS.rst new file mode 100644 index 0000000..2a6c410 --- /dev/null +++ b/Help/variable/CMAKE_DIRECTORY_LABELS.rst @@ -0,0 +1,6 @@ +CMAKE_DIRECTORY_LABELS +----------------------- + +Specify labels for the current directory. + +This is used to initialize the :prop_dir:`LABELS` directory property. diff --git a/Help/variable/CMAKE_DISABLE_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_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_VERSION.rst b/Help/variable/CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION.rst new file mode 100644 index 0000000..124fefe --- /dev/null +++ b/Help/variable/CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION.rst @@ -0,0 +1,16 @@ +CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION +------------------------------------- + +Default value for :prop_tgt:`DOTNET_TARGET_FRAMEWORK_VERSION` +property of targets. + +This variable is used to initialize the +:prop_tgt:`DOTNET_TARGET_FRAMEWORK_VERSION` property on all +targets. See that target property for additional information. + +Setting ``CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION`` may be necessary +when working with ``C#`` and newer .NET framework versions to +avoid referencing errors with the ``ALL_BUILD`` CMake target. + +This variable is only evaluated for :ref:`Visual Studio Generators` +VS 2010 and above. diff --git a/Help/variable/CMAKE_ECLIPSE_GENERATE_LINKED_RESOURCES.rst b/Help/variable/CMAKE_ECLIPSE_GENERATE_LINKED_RESOURCES.rst new file mode 100644 index 0000000..331aae8 --- /dev/null +++ b/Help/variable/CMAKE_ECLIPSE_GENERATE_LINKED_RESOURCES.rst @@ -0,0 +1,10 @@ +CMAKE_ECLIPSE_GENERATE_LINKED_RESOURCES +--------------------------------------- + +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..7b4367d --- /dev/null +++ b/Help/variable/CMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT.rst @@ -0,0 +1,11 @@ +CMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT +------------------------------------- + +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..6e8a408 --- /dev/null +++ b/Help/variable/CMAKE_ECLIPSE_MAKE_ARGUMENTS.rst @@ -0,0 +1,9 @@ +CMAKE_ECLIPSE_MAKE_ARGUMENTS +---------------------------- + +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_VERSION.rst b/Help/variable/CMAKE_ECLIPSE_VERSION.rst new file mode 100644 index 0000000..8cc7882 --- /dev/null +++ b/Help/variable/CMAKE_ECLIPSE_VERSION.rst @@ -0,0 +1,10 @@ +CMAKE_ECLIPSE_VERSION +--------------------- + +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..7ec4d63 --- /dev/null +++ b/Help/variable/CMAKE_ENABLE_EXPORTS.rst @@ -0,0 +1,22 @@ +CMAKE_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. +For DLL platforms an import library will be created for the exported +symbols and then used for linking. All Windows-based systems +including Cygwin are DLL platforms. For non-DLL platforms that +require all symbols to be resolved at link time, such as macOS, the +module will ``link`` to the executable using a flag like +``-bundle_loader``. For other non-DLL platforms the link rule is simply +ignored since the dynamic loader will automatically bind symbols when +the module is loaded. + +This variable is used to initialize the target property +:prop_tgt:`ENABLE_EXPORTS` for executable targets. 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_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..592a369 --- /dev/null +++ b/Help/variable/CMAKE_EXE_LINKER_FLAGS_CONFIG_INIT.rst @@ -0,0 +1,10 @@ +CMAKE_EXE_LINKER_FLAGS_<CONFIG>_INIT +------------------------------------ + +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..0b8afe4 --- /dev/null +++ b/Help/variable/CMAKE_EXE_LINKER_FLAGS_INIT.rst @@ -0,0 +1,11 @@ +CMAKE_EXE_LINKER_FLAGS_INIT +--------------------------- + +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..8776279 --- /dev/null +++ b/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst @@ -0,0 +1,30 @@ +CMAKE_EXPORT_COMPILE_COMMANDS +----------------------------- + +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" + } + ] + +.. note:: + This option is implemented only by :ref:`Makefile Generators` + and the :generator:`Ninja`. It is ignored on other generators. 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..ee109ba --- /dev/null +++ b/Help/variable/CMAKE_EXPORT_NO_PACKAGE_REGISTRY.rst @@ -0,0 +1,11 @@ +CMAKE_EXPORT_NO_PACKAGE_REGISTRY +-------------------------------- + +Disable the :command:`export(PACKAGE)` command. + +In some cases, for example for packaging and for system wide +installations, it is not desirable to write the user package registry. +If the :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` variable is enabled, +the :command:`export(PACKAGE)` command will do nothing. + +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..7a05fac --- /dev/null +++ b/Help/variable/CMAKE_FIND_APPBUNDLE.rst @@ -0,0 +1,22 @@ +CMAKE_FIND_APPBUNDLE +-------------------- + +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_FRAMEWORK.rst b/Help/variable/CMAKE_FIND_FRAMEWORK.rst new file mode 100644 index 0000000..4d5078f --- /dev/null +++ b/Help/variable/CMAKE_FIND_FRAMEWORK.rst @@ -0,0 +1,22 @@ +CMAKE_FIND_FRAMEWORK +-------------------- + +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..ada8955 --- /dev/null +++ b/Help/variable/CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX.rst @@ -0,0 +1,12 @@ +CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX +------------------------------------ + +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..bd1a30f --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_NAME.rst @@ -0,0 +1,6 @@ +CMAKE_FIND_PACKAGE_NAME +----------------------- + +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..9058471 --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY.rst @@ -0,0 +1,13 @@ +CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY +-------------------------------------- + +Skip :ref:`User Package Registry` in :command:`find_package` calls. + +In some cases, for example to locate only system wide installations, it +is not desirable to use the :ref:`User Package Registry` when searching +for packages. If the :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` +variable is enabled, all the :command:`find_package` commands will skip +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..44588b1 --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY.rst @@ -0,0 +1,13 @@ +CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY +--------------------------------------------- + +Skip :ref:`System Package Registry` in :command:`find_package` calls. + +In some cases, it is not desirable to use the +:ref:`System Package Registry` when searching for packages. If the +:variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` variable is +enabled, all the :command:`find_package` commands will skip +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_SORT_DIRECTION.rst b/Help/variable/CMAKE_FIND_PACKAGE_SORT_DIRECTION.rst new file mode 100644 index 0000000..99e4ec1 --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_SORT_DIRECTION.rst @@ -0,0 +1,16 @@ +CMAKE_FIND_PACKAGE_SORT_DIRECTION +--------------------------------- + +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..ba5f3a8 --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_SORT_ORDER.rst @@ -0,0 +1,36 @@ +CMAKE_FIND_PACKAGE_SORT_ORDER +----------------------------- + +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..f1116bb --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_WARN_NO_MODULE.rst @@ -0,0 +1,19 @@ +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. diff --git a/Help/variable/CMAKE_FIND_ROOT_PATH.rst b/Help/variable/CMAKE_FIND_ROOT_PATH.rst new file mode 100644 index 0000000..ba2cf31 --- /dev/null +++ b/Help/variable/CMAKE_FIND_ROOT_PATH.rst @@ -0,0 +1,8 @@ +CMAKE_FIND_ROOT_PATH +-------------------- + +:ref:`;-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_FOLDER.rst b/Help/variable/CMAKE_FOLDER.rst new file mode 100644 index 0000000..50a2b88 --- /dev/null +++ b/Help/variable/CMAKE_FOLDER.rst @@ -0,0 +1,7 @@ +CMAKE_FOLDER +------------ + +Set the folder name. Use to organize targets in an IDE. + +This variable is used to initialize the :prop_tgt:`FOLDER` property on all the +targets. See that target property for additional information. diff --git a/Help/variable/CMAKE_FRAMEWORK_PATH.rst b/Help/variable/CMAKE_FRAMEWORK_PATH.rst new file mode 100644 index 0000000..04751f8 --- /dev/null +++ b/Help/variable/CMAKE_FRAMEWORK_PATH.rst @@ -0,0 +1,7 @@ +CMAKE_FRAMEWORK_PATH +-------------------- + +:ref:`;-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_GENERATOR.rst b/Help/variable/CMAKE_GENERATOR.rst new file mode 100644 index 0000000..cce04c1 --- /dev/null +++ b/Help/variable/CMAKE_GENERATOR.rst @@ -0,0 +1,7 @@ +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.) diff --git a/Help/variable/CMAKE_GENERATOR_INSTANCE.rst b/Help/variable/CMAKE_GENERATOR_INSTANCE.rst new file mode 100644 index 0000000..78c81b1 --- /dev/null +++ b/Help/variable/CMAKE_GENERATOR_INSTANCE.rst @@ -0,0 +1,24 @@ +CMAKE_GENERATOR_INSTANCE +------------------------ + +Generator-specific instance specification provided by user. + +Some CMake generators support selection of an instance of the native build +system when multiple instances are available. If the user specifies an +instance (e.g. by setting this cache entry), or 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..963f0a4 --- /dev/null +++ b/Help/variable/CMAKE_GENERATOR_PLATFORM.rst @@ -0,0 +1,30 @@ +CMAKE_GENERATOR_PLATFORM +------------------------ + +Generator-specific target platform specification provided by user. + +Some CMake generators support a target platform name to be given +to the native build system to choose a compiler toolchain. +If the user specifies a platform name (e.g. via the :manual:`cmake(1)` ``-A`` +option) the value will be available in this variable. + +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..e9bc28b --- /dev/null +++ b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst @@ -0,0 +1,56 @@ +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) 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>`` + Specify the CUDA toolkit version to use. Supported by VS 2010 + and above with the CUDA toolkit VS integration installed. + See the :variable:`CMAKE_VS_PLATFORM_TOOLSET_CUDA` variable. + +``host=x64`` + Request use of the native ``x64`` toolchain on ``x64`` hosts. + Supported by VS 2013 and above. + See the :variable:`CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE` + variable. + +``version=<version>`` + Specify the toolset version to use. Supported by VS 2017 + and above with the specified toolset installed. + See the :variable:`CMAKE_VS_PLATFORM_TOOLSET_VERSION` variable. diff --git a/Help/variable/CMAKE_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..fdc5d81 --- /dev/null +++ b/Help/variable/CMAKE_HOME_DIRECTORY.rst @@ -0,0 +1,6 @@ +CMAKE_HOME_DIRECTORY +-------------------- + +Path to top of source tree. + +This is the path to the top level of the source tree. 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..82b5d69 --- /dev/null +++ b/Help/variable/CMAKE_HOST_SOLARIS.rst @@ -0,0 +1,6 @@ +CMAKE_HOST_SOLARIS +------------------ + +``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..ba8a850 --- /dev/null +++ b/Help/variable/CMAKE_HOST_SYSTEM_PROCESSOR.rst @@ -0,0 +1,8 @@ +CMAKE_HOST_SYSTEM_PROCESSOR +--------------------------- + +The name of the CPU CMake is running on. + +On systems that support ``uname``, this variable is set to the output of +``uname -p``. On Windows it is set to the value of the environment variable +``PROCESSOR_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..92f3770 --- /dev/null +++ b/Help/variable/CMAKE_IGNORE_PATH.rst @@ -0,0 +1,18 @@ +CMAKE_IGNORE_PATH +----------------- + +:ref:`;-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..e4e7f2c --- /dev/null +++ b/Help/variable/CMAKE_INCLUDE_PATH.rst @@ -0,0 +1,7 @@ +CMAKE_INCLUDE_PATH +------------------ + +:ref:`;-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..f994fbe --- /dev/null +++ b/Help/variable/CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS.rst @@ -0,0 +1,29 @@ +CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS +------------------------------------------- + +Default permissions for directories created implicitly during installation +of files by :command:`install` and :command:`file(INSTALL)`. + +If ``make install`` is invoked and directories are implicitly created they +get permissions set by :variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` +variable or platform specific default permissions if the variable is not set. + +Implicitly created directories are created if they are not explicitly installed +by :command:`install` command but are needed to install a file on a certain +path. Example of such locations are directories created due to the setting of +:variable:`CMAKE_INSTALL_PREFIX`. + +Expected content of the :variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` +variable is a list of permissions that can be used by :command:`install` command +`PERMISSIONS` section. + +Example usage: + +:: + + set(CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS + OWNER_READ + OWNER_WRITE + OWNER_EXECUTE + GROUP_READ + ) diff --git a/Help/variable/CMAKE_INSTALL_MESSAGE.rst b/Help/variable/CMAKE_INSTALL_MESSAGE.rst new file mode 100644 index 0000000..304df26 --- /dev/null +++ b/Help/variable/CMAKE_INSTALL_MESSAGE.rst @@ -0,0 +1,30 @@ +CMAKE_INSTALL_MESSAGE +--------------------- + +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..5ba4c04 --- /dev/null +++ b/Help/variable/CMAKE_INSTALL_NAME_DIR.rst @@ -0,0 +1,8 @@ +CMAKE_INSTALL_NAME_DIR +---------------------- + +macOS directory name for installed targets. + +``CMAKE_INSTALL_NAME_DIR`` is used to initialize the +:prop_tgt:`INSTALL_NAME_DIR` property on all targets. See that target +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..2a5842d --- /dev/null +++ b/Help/variable/CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT.rst @@ -0,0 +1,14 @@ +CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT +------------------------------------------- + +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_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..78148d5 --- /dev/null +++ b/Help/variable/CMAKE_INSTALL_RPATH_USE_LINK_PATH.rst @@ -0,0 +1,9 @@ +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 directories in the linker search path and outside the +project to the :prop_tgt:`INSTALL_RPATH`. This 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..b0cbb62 --- /dev/null +++ b/Help/variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION.rst @@ -0,0 +1,8 @@ +CMAKE_INTERPROCEDURAL_OPTIMIZATION +---------------------------------- + +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..b291102 --- /dev/null +++ b/Help/variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst @@ -0,0 +1,8 @@ +CMAKE_INTERPROCEDURAL_OPTIMIZATION_<CONFIG> +------------------------------------------- + +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..c5cb9b6 --- /dev/null +++ b/Help/variable/CMAKE_IOS_INSTALL_COMBINED.rst @@ -0,0 +1,8 @@ +CMAKE_IOS_INSTALL_COMBINED +-------------------------- + +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_JOB_POOLS.rst b/Help/variable/CMAKE_JOB_POOLS.rst new file mode 100644 index 0000000..72b50b4 --- /dev/null +++ b/Help/variable/CMAKE_JOB_POOLS.rst @@ -0,0 +1,6 @@ +CMAKE_JOB_POOLS +--------------- + +If the :prop_gbl:`JOB_POOLS` global property is not set, the value +of this variable is used in its place. See :prop_gbl:`JOB_POOLS` +for additional information. diff --git a/Help/variable/CMAKE_JOB_POOL_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..338f771 --- /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_LANG_ANDROID_TOOLCHAIN_MACHINE.rst b/Help/variable/CMAKE_LANG_ANDROID_TOOLCHAIN_MACHINE.rst new file mode 100644 index 0000000..d336364 --- /dev/null +++ b/Help/variable/CMAKE_LANG_ANDROID_TOOLCHAIN_MACHINE.rst @@ -0,0 +1,9 @@ +CMAKE_<LANG>_ANDROID_TOOLCHAIN_MACHINE +-------------------------------------- + +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..db04af3 --- /dev/null +++ b/Help/variable/CMAKE_LANG_ANDROID_TOOLCHAIN_PREFIX.rst @@ -0,0 +1,12 @@ +CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX +------------------------------------- + +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..159eb22 --- /dev/null +++ b/Help/variable/CMAKE_LANG_ANDROID_TOOLCHAIN_SUFFIX.rst @@ -0,0 +1,8 @@ +CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX +------------------------------------- + +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_CLANG_TIDY.rst b/Help/variable/CMAKE_LANG_CLANG_TIDY.rst new file mode 100644 index 0000000..bd49de3 --- /dev/null +++ b/Help/variable/CMAKE_LANG_CLANG_TIDY.rst @@ -0,0 +1,13 @@ +CMAKE_<LANG>_CLANG_TIDY +----------------------- + +Default value for :prop_tgt:`<LANG>_CLANG_TIDY` target property +when ``<LANG>`` is ``C`` or ``CXX``. + +This variable is used to initialize the property on each target as it is +created. 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..89df495 --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER.rst @@ -0,0 +1,7 @@ +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. 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..b83a1d4 --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_AR.rst @@ -0,0 +1,7 @@ +CMAKE_<LANG>_COMPILER_AR +------------------------ + +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..054c648 --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_ARCHITECTURE_ID.rst @@ -0,0 +1,8 @@ +CMAKE_<LANG>_COMPILER_ARCHITECTURE_ID +------------------------------------- + +An internal variable subject to change. + +This is used to identify the variant of a compiler based on its target +architecture. For some compilers this is needed to determine the correct +usage. diff --git a/Help/variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN.rst b/Help/variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN.rst 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..2264269 --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_ID.rst @@ -0,0 +1,39 @@ +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) + 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) + G95 = G95 Fortran (g95.org) + GNU = GNU Compiler Collection (gcc.gnu.org) + HP = Hewlett-Packard Compiler (hp.com) + IAR = IAR Systems (iar.com) + Intel = Intel Compiler (intel.com) + MIPSpro = SGI MIPSpro (sgi.com) + MSVC = Microsoft Visual Studio (microsoft.com) + NVIDIA = NVIDIA CUDA Compiler (nvidia.com) + OpenWatcom = Open Watcom (openwatcom.org) + PGI = The Portland Group (pgroup.com) + Flang = Flang Fortran Compiler + 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) + +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..e6c8bb5 --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst @@ -0,0 +1,7 @@ +CMAKE_<LANG>_COMPILER_LAUNCHER +------------------------------ + +Default value for :prop_tgt:`<LANG>_COMPILER_LAUNCHER` target property. +This variable is used to initialize the property on each target as it is +created. This is done only when ``<LANG>`` is ``C``, ``CXX``, ``Fortran``, +or ``CUDA``. 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..e050f43 --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_PREDEFINES_COMMAND.rst @@ -0,0 +1,8 @@ +CMAKE_<LANG>_COMPILER_PREDEFINES_COMMAND +---------------------------------------- + +Command that outputs the compiler pre definitions. + +See :prop_tgt:`AUTOMOC` which uses +:variable:`CMAKE_CXX_COMPILER_PREDEFINES_COMMAND <CMAKE_<LANG>_COMPILER_PREDEFINES_COMMAND>` +to generate the :prop_tgt:`AUTOMOC_COMPILER_PREDEFINES`. diff --git a/Help/variable/CMAKE_LANG_COMPILER_RANLIB.rst b/Help/variable/CMAKE_LANG_COMPILER_RANLIB.rst new file mode 100644 index 0000000..945160b --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_RANLIB.rst @@ -0,0 +1,7 @@ +CMAKE_<LANG>_COMPILER_RANLIB +---------------------------- + +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..c3cd980 --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_VERSION_INTERNAL.rst @@ -0,0 +1,8 @@ +CMAKE_<LANG>_COMPILER_VERSION_INTERNAL +-------------------------------------- + +An internal variable subject to change. + +This is used to identify the variant of a compiler based on an internal +version number. For some compilers this is needed to determine the +correct usage. diff --git a/Help/variable/CMAKE_LANG_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..50b478f --- /dev/null +++ b/Help/variable/CMAKE_LANG_CPPCHECK.rst @@ -0,0 +1,6 @@ +CMAKE_<LANG>_CPPCHECK +--------------------- + +Default value for :prop_tgt:`<LANG>_CPPCHECK` target property. This variable +is used to initialize the property on each target as it is created. This +is done only when ``<LANG>`` is ``C`` or ``CXX``. diff --git a/Help/variable/CMAKE_LANG_CPPLINT.rst b/Help/variable/CMAKE_LANG_CPPLINT.rst new file mode 100644 index 0000000..3b6f452 --- /dev/null +++ b/Help/variable/CMAKE_LANG_CPPLINT.rst @@ -0,0 +1,6 @@ +CMAKE_<LANG>_CPPLINT +-------------------- + +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..be89f85 --- /dev/null +++ b/Help/variable/CMAKE_LANG_CREATE_SHARED_LIBRARY.rst @@ -0,0 +1,7 @@ +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>``. 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..ae5f69d --- /dev/null +++ b/Help/variable/CMAKE_LANG_CREATE_SHARED_MODULE.rst @@ -0,0 +1,7 @@ +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>``. 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..14b2694 --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS.rst @@ -0,0 +1,17 @@ +CMAKE_<LANG>_FLAGS +------------------ + +Flags for all build types. + +``<LANG>`` flags used regardless of the value of :variable:`CMAKE_BUILD_TYPE`. + +This is initialized for each language from environment variables: + +* ``CMAKE_C_FLAGS``: + Initialized by the :envvar:`CFLAGS` environment variable. +* ``CMAKE_CXX_FLAGS``: + Initialized by the :envvar:`CXXFLAGS` environment variable. +* ``CMAKE_CUDA_FLAGS``: + Initialized by the :envvar:`CUDAFLAGS` environment variable. +* ``CMAKE_Fortran_FLAGS``: + Initialized by the :envvar:`FFLAGS` environment variable. diff --git a/Help/variable/CMAKE_LANG_FLAGS_CONFIG.rst b/Help/variable/CMAKE_LANG_FLAGS_CONFIG.rst new file mode 100644 index 0000000..1dbd036 --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_CONFIG.rst @@ -0,0 +1,4 @@ +CMAKE_<LANG>_FLAGS_<CONFIG> +--------------------------- + +Flags for language ``<LANG>`` when building for the ``<CONFIG>`` configuration. diff --git a/Help/variable/CMAKE_LANG_FLAGS_CONFIG_INIT.rst b/Help/variable/CMAKE_LANG_FLAGS_CONFIG_INIT.rst new file mode 100644 index 0000000..1eb5b3f --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_CONFIG_INIT.rst @@ -0,0 +1,10 @@ +CMAKE_<LANG>_FLAGS_<CONFIG>_INIT +-------------------------------- + +Value used to initialize the :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` cache +entry the first time a build tree is configured for language ``<LANG>``. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also :variable:`CMAKE_<LANG>_FLAGS_INIT`. diff --git a/Help/variable/CMAKE_LANG_FLAGS_DEBUG.rst b/Help/variable/CMAKE_LANG_FLAGS_DEBUG.rst 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..de7fcfc --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_DEBUG_INIT.rst @@ -0,0 +1,5 @@ +CMAKE_<LANG>_FLAGS_DEBUG_INIT +----------------------------- + +This variable is the ``Debug`` variant of the +:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>_INIT` variable. diff --git a/Help/variable/CMAKE_LANG_FLAGS_INIT.rst b/Help/variable/CMAKE_LANG_FLAGS_INIT.rst new file mode 100644 index 0000000..a88d122 --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_INIT.rst @@ -0,0 +1,11 @@ +CMAKE_<LANG>_FLAGS_INIT +----------------------- + +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. + +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..1e7003c --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL_INIT.rst @@ -0,0 +1,5 @@ +CMAKE_<LANG>_FLAGS_MINSIZEREL_INIT +---------------------------------- + +This variable is the ``MinSizeRel`` variant of the +:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>_INIT` variable. diff --git a/Help/variable/CMAKE_LANG_FLAGS_RELEASE.rst b/Help/variable/CMAKE_LANG_FLAGS_RELEASE.rst 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..e7c73fe --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_RELEASE_INIT.rst @@ -0,0 +1,5 @@ +CMAKE_<LANG>_FLAGS_RELEASE_INIT +------------------------------- + +This variable is the ``Release`` variant of the +:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>_INIT` variable. diff --git a/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO.rst b/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO.rst 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..3ab3975 --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT.rst @@ -0,0 +1,5 @@ +CMAKE_<LANG>_FLAGS_RELWITHDEBINFO_INIT +-------------------------------------- + +This variable is the ``RelWithDebInfo`` variant of the +:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>_INIT` variable. diff --git a/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_CONFIG.rst b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_CONFIG.rst new file mode 100644 index 0000000..8ed1c02 --- /dev/null +++ b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_CONFIG.rst @@ -0,0 +1,5 @@ +CMAKE_<LANG>_GHS_KERNEL_FLAGS_<CONFIG> +-------------------------------------- + +GHS kernel flags for language ``<LANG>`` when building for the ``<CONFIG>`` +configuration. diff --git a/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_DEBUG.rst b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_DEBUG.rst new file mode 100644 index 0000000..4fea67a --- /dev/null +++ b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_DEBUG.rst @@ -0,0 +1,5 @@ +CMAKE_<LANG>_GHS_KERNEL_FLAGS_DEBUG +----------------------------------- + +This variable is the ``Debug`` variant of the +:variable:`CMAKE_<LANG>_GHS_KERNEL_FLAGS_<CONFIG>` variable. diff --git a/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_MINSIZEREL.rst b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_MINSIZEREL.rst new file mode 100644 index 0000000..31f87f2 --- /dev/null +++ b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_MINSIZEREL.rst @@ -0,0 +1,5 @@ +CMAKE_<LANG>_GHS_KERNEL_FLAGS_MINSIZEREL +---------------------------------------- + +This variable is the ``MinSizeRel`` variant of the +:variable:`CMAKE_<LANG>_GHS_KERNEL_FLAGS_<CONFIG>` variable. diff --git a/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELEASE.rst b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELEASE.rst new file mode 100644 index 0000000..1acd198 --- /dev/null +++ b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELEASE.rst @@ -0,0 +1,5 @@ +CMAKE_<LANG>_GHS_KERNEL_FLAGS_RELEASE +------------------------------------- + +This variable is the ``Release`` variant of the +:variable:`CMAKE_<LANG>_GHS_KERNEL_FLAGS_<CONFIG>` variable. diff --git a/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELWITHDEBINFO.rst b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELWITHDEBINFO.rst new file mode 100644 index 0000000..ac1b6bc --- /dev/null +++ b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELWITHDEBINFO.rst @@ -0,0 +1,5 @@ +CMAKE_<LANG>_GHS_KERNEL_FLAGS_RELWITHDEBINFO +-------------------------------------------- + +This variable is the ``RelWithDebInfo`` variant of the +:variable:`CMAKE_<LANG>_GHS_KERNEL_FLAGS_<CONFIG>` 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..cc80851 --- /dev/null +++ b/Help/variable/CMAKE_LANG_IMPLICIT_INCLUDE_DIRECTORIES.rst @@ -0,0 +1,9 @@ +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. 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..2c8028a --- /dev/null +++ b/Help/variable/CMAKE_LANG_INCLUDE_WHAT_YOU_USE.rst @@ -0,0 +1,6 @@ +CMAKE_<LANG>_INCLUDE_WHAT_YOU_USE +--------------------------------- + +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..0e52282 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINKER_WRAPPER_FLAG.rst @@ -0,0 +1,39 @@ +CMAKE_<LANG>_LINKER_WRAPPER_FLAG +-------------------------------- + +Defines the syntax of compiler driver option to pass options to the linker +tool. It will be used to translate the ``LINKER:`` prefix in the link options +(see :command:`add_link_options` and :command:`target_link_options`). + +This variable holds a :ref:`;-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..faf1481 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINKER_WRAPPER_FLAG_SEP.rst @@ -0,0 +1,9 @@ +CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP +------------------------------------ + +This variable is used with :variable:`CMAKE_<LANG>_LINKER_WRAPPER_FLAG` +variable to format ``LINKER:`` prefix in the link options +(see :command:`add_link_options` and :command:`target_link_options`). + +When specified, arguments of the ``LINKER:`` prefix will be concatenated using +this value as separator. diff --git a/Help/variable/CMAKE_LANG_LINK_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_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..c8e3d57 --- /dev/null +++ b/Help/variable/CMAKE_LANG_STANDARD_INCLUDE_DIRECTORIES.rst @@ -0,0 +1,14 @@ +CMAKE_<LANG>_STANDARD_INCLUDE_DIRECTORIES +----------------------------------------- + +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..ba6df93 --- /dev/null +++ b/Help/variable/CMAKE_LANG_STANDARD_LIBRARIES.rst @@ -0,0 +1,12 @@ +CMAKE_<LANG>_STANDARD_LIBRARIES +------------------------------- + +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..e069cdd --- /dev/null +++ b/Help/variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY_CONFIG.rst @@ -0,0 +1,9 @@ +CMAKE_LIBRARY_OUTPUT_DIRECTORY_<CONFIG> +--------------------------------------- + +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..b1770dc --- /dev/null +++ b/Help/variable/CMAKE_LIBRARY_PATH.rst @@ -0,0 +1,7 @@ +CMAKE_LIBRARY_PATH +------------------ + +:ref:`;-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..026ca35 --- /dev/null +++ b/Help/variable/CMAKE_LINK_DIRECTORIES_BEFORE.rst @@ -0,0 +1,9 @@ +CMAKE_LINK_DIRECTORIES_BEFORE +----------------------------- + +Whether to append or prepend directories by default in +:command:`link_directories`. + +This variable affects the default behavior of the :command:`link_directories` +command. Setting this variable to ``ON`` is equivalent to using the ``BEFORE`` +option in all uses of that command. diff --git a/Help/variable/CMAKE_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..54cdaaa --- /dev/null +++ b/Help/variable/CMAKE_LINK_SEARCH_END_STATIC.rst @@ -0,0 +1,19 @@ +CMAKE_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 variable is used to initialize the target property +:prop_tgt:`LINK_SEARCH_END_STATIC` for all targets. If set, it's +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..0d52a31 --- /dev/null +++ b/Help/variable/CMAKE_LINK_SEARCH_START_STATIC.rst @@ -0,0 +1,20 @@ +CMAKE_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 variable is used to initialize the target property +:prop_tgt:`LINK_SEARCH_START_STATIC` for all targets. If set, it's +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..90c4d3f --- /dev/null +++ b/Help/variable/CMAKE_LINK_WHAT_YOU_USE.rst @@ -0,0 +1,6 @@ +CMAKE_LINK_WHAT_YOU_USE +--------------------------------- + +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..0badaf0 --- /dev/null +++ b/Help/variable/CMAKE_MACOSX_BUNDLE.rst @@ -0,0 +1,7 @@ +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. 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..4f5a50f --- /dev/null +++ b/Help/variable/CMAKE_MAKE_PROGRAM.rst @@ -0,0 +1,67 @@ +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`` (or possibly an + otherwise undocumented ``cmakexbuild`` wrapper implementing some + workarounds). + + This generator prefers to lookup the build tool at build time + rather than to store ``CMAKE_MAKE_PROGRAM`` in the CMake cache + ahead of time. This is because ``xcodebuild`` is easy to find, + the ``cmakexbuild`` wrapper is needed only for older Xcode versions, + and the path to ``cmakexbuild`` may be outdated if CMake itself moves. + + 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`` 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..355e834 --- /dev/null +++ b/Help/variable/CMAKE_MATCH_COUNT.rst @@ -0,0 +1,9 @@ +CMAKE_MATCH_COUNT +----------------- + +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..c7dd623 --- /dev/null +++ b/Help/variable/CMAKE_MATCH_n.rst @@ -0,0 +1,10 @@ +CMAKE_MATCH_<n> +--------------- + +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_MFC_FLAG.rst b/Help/variable/CMAKE_MFC_FLAG.rst new file mode 100644 index 0000000..5a392bf --- /dev/null +++ b/Help/variable/CMAKE_MFC_FLAG.rst @@ -0,0 +1,16 @@ +CMAKE_MFC_FLAG +-------------- + +Tell cmake to use MFC for an executable or dll. + +This can be set in a ``CMakeLists.txt`` file and will enable MFC in the +application. It should be set to ``1`` for the static MFC library, and ``2`` +for the shared MFC library. This is used in Visual Studio +project files. The CMakeSetup dialog used MFC and the ``CMakeLists.txt`` +looks like this: + +:: + + add_definitions(-D_AFXDLL) + set(CMAKE_MFC_FLAG 2) + add_executable(CMakeSetup WIN32 ${SRCS}) 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..3279014 --- /dev/null +++ b/Help/variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG_INIT.rst @@ -0,0 +1,10 @@ +CMAKE_MODULE_LINKER_FLAGS_<CONFIG>_INIT +--------------------------------------- + +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..91b39f6 --- /dev/null +++ b/Help/variable/CMAKE_MODULE_LINKER_FLAGS_INIT.rst @@ -0,0 +1,11 @@ +CMAKE_MODULE_LINKER_FLAGS_INIT +------------------------------ + +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..6490054 --- /dev/null +++ b/Help/variable/CMAKE_MODULE_PATH.rst @@ -0,0 +1,7 @@ +CMAKE_MODULE_PATH +----------------- + +:ref:`;-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..22e727f --- /dev/null +++ b/Help/variable/CMAKE_MSVCIDE_RUN_PATH.rst @@ -0,0 +1,10 @@ +CMAKE_MSVCIDE_RUN_PATH +---------------------- + +Extra PATH locations that should be used when executing +:command:`add_custom_command` or :command:`add_custom_target` when using the +:generator:`Visual Studio 9 2008` (or above) generator. This allows +for running commands and using dll's that the IDE environment is not aware of. + +If not set explicitly the value is initialized by the ``CMAKE_MSVCIDE_RUN_PATH`` +environment variable, if set, and otherwise left empty. diff --git a/Help/variable/CMAKE_NETRC.rst b/Help/variable/CMAKE_NETRC.rst new file mode 100644 index 0000000..903ec31 --- /dev/null +++ b/Help/variable/CMAKE_NETRC.rst @@ -0,0 +1,9 @@ +CMAKE_NETRC +----------- + +This variable is used to initialize the ``NETRC`` option for +:command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands and the +module :module:`ExternalProject`. See those commands for additional +information. + +The local option takes precedence over this variable. diff --git a/Help/variable/CMAKE_NETRC_FILE.rst b/Help/variable/CMAKE_NETRC_FILE.rst new file mode 100644 index 0000000..0f09afe --- /dev/null +++ b/Help/variable/CMAKE_NETRC_FILE.rst @@ -0,0 +1,9 @@ +CMAKE_NETRC_FILE +---------------- + +This variable is used to initialize the ``NETRC_FILE`` option for +:command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands and the +module :module:`ExternalProject`. See those commands for additional +information. + +The local option takes precedence over this variable. diff --git a/Help/variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX.rst b/Help/variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX.rst new file mode 100644 index 0000000..64091aa --- /dev/null +++ b/Help/variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX.rst @@ -0,0 +1,27 @@ +CMAKE_NINJA_OUTPUT_PATH_PREFIX +------------------------------ + +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..189f59f --- /dev/null +++ b/Help/variable/CMAKE_NO_BUILTIN_CHRPATH.rst @@ -0,0 +1,10 @@ +CMAKE_NO_BUILTIN_CHRPATH +------------------------ + +Do not use the builtin ELF editor to fix RPATHs on installation. + +When an ELF binary needs to have a different RPATH after installation +than it does in the build tree, CMake uses a builtin editor to change +the RPATH 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. 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_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_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..5b84726 --- /dev/null +++ b/Help/variable/CMAKE_OSX_VARIABLE.txt @@ -0,0 +1,9 @@ +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. + +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_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..aa23b65 --- /dev/null +++ b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst @@ -0,0 +1,27 @@ +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`. + +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..43b1397 --- /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, it's +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..c2a4a60 --- /dev/null +++ b/Help/variable/CMAKE_PREFIX_PATH.rst @@ -0,0 +1,15 @@ +CMAKE_PREFIX_PATH +----------------- + +:ref:`;-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..799e119 --- /dev/null +++ b/Help/variable/CMAKE_PROGRAM_PATH.rst @@ -0,0 +1,7 @@ +CMAKE_PROGRAM_PATH +------------------ + +:ref:`;-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..51b0592 --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_DESCRIPTION.rst @@ -0,0 +1,35 @@ +CMAKE_PROJECT_DESCRIPTION +------------------------- + +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..ee0bf7c --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_HOMEPAGE_URL.rst @@ -0,0 +1,35 @@ +CMAKE_PROJECT_HOMEPAGE_URL +-------------------------- + +The homepage URL of the top level project. + +This variable holds the homepage URL of the project as specified in the top +level CMakeLists.txt file by a :command:`project` command. In the event that +the top level CMakeLists.txt contains multiple :command:`project` calls, +the most recently called one from that top level CMakeLists.txt will determine +the value that ``CMAKE_PROJECT_HOMEPAGE_URL`` contains. For example, consider +the following top level CMakeLists.txt: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.0) + project(First HOMEPAGE_URL "http://first.example.com") + project(Second HOMEPAGE_URL "http://second.example.com") + add_subdirectory(sub) + project(Third HOMEPAGE_URL "http://third.example.com") + +And ``sub/CMakeLists.txt`` with the following contents: + +.. code-block:: cmake + + project(SubProj HOMEPAGE_URL "http://subproj.example.com") + message("CMAKE_PROJECT_HOMEPAGE_URL = ${CMAKE_PROJECT_HOMEPAGE_URL}") + +The most recently seen :command:`project` command from the top level +CMakeLists.txt would be ``project(Second ...)``, so this will print:: + + CMAKE_PROJECT_HOMEPAGE_URL = http://second.example.com + +To obtain the homepage URL from the most recent call to :command:`project` in +the current directory scope or above, see the :variable:`PROJECT_HOMEPAGE_URL` +variable. diff --git a/Help/variable/CMAKE_PROJECT_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..5ca40a3 --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst @@ -0,0 +1,6 @@ +CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE +------------------------------------ + +A CMake language file or module to be included by the :command:`project` +command. This is intended for injecting custom code into project +builds without modifying their source. diff --git a/Help/variable/CMAKE_PROJECT_VERSION.rst b/Help/variable/CMAKE_PROJECT_VERSION.rst new file mode 100644 index 0000000..4f8f556 --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_VERSION.rst @@ -0,0 +1,35 @@ +CMAKE_PROJECT_VERSION +--------------------- + +The version of the top level project. + +This variable holds the version of the project as specified in the top +level CMakeLists.txt file by a :command:`project` command. In the event that +the top level CMakeLists.txt contains multiple :command:`project` calls, +the most recently called one from that top level CMakeLists.txt will determine +the value that ``CMAKE_PROJECT_VERSION`` contains. For example, consider +the following top level CMakeLists.txt: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.0) + project(First VERSION 1.2.3) + project(Second VERSION 3.4.5) + add_subdirectory(sub) + project(Third VERSION 6.7.8) + +And ``sub/CMakeLists.txt`` with the following contents: + +.. code-block:: cmake + + project(SubProj VERSION 1) + message("CMAKE_PROJECT_VERSION = ${CMAKE_PROJECT_VERSION}") + +The most recently seen :command:`project` command from the top level +CMakeLists.txt would be ``project(Second ...)``, so this will print:: + + CMAKE_PROJECT_VERSION = 3.4.5 + +To obtain the version from the most recent call to :command:`project` in +the current directory scope or above, see the :variable:`PROJECT_VERSION` +variable. diff --git a/Help/variable/CMAKE_PROJECT_VERSION_MAJOR.rst b/Help/variable/CMAKE_PROJECT_VERSION_MAJOR.rst new file mode 100644 index 0000000..f1001ac --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_VERSION_MAJOR.rst @@ -0,0 +1,9 @@ +CMAKE_PROJECT_VERSION_MAJOR +--------------------------- + +The major version of the top level project. + +This variable holds the major version of the project as specified in the top +level CMakeLists.txt file by a :command:`project` command. Please see +:variable:`CMAKE_PROJECT_VERSION` documentation for the behavior when +multiple :command:`project` commands are used in the sources. diff --git a/Help/variable/CMAKE_PROJECT_VERSION_MINOR.rst b/Help/variable/CMAKE_PROJECT_VERSION_MINOR.rst new file mode 100644 index 0000000..13202be --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_VERSION_MINOR.rst @@ -0,0 +1,9 @@ +CMAKE_PROJECT_VERSION_MINOR +--------------------------- + +The minor version of the top level project. + +This variable holds the minor version of the project as specified in the top +level CMakeLists.txt file by a :command:`project` command. Please see +:variable:`CMAKE_PROJECT_VERSION` documentation for the behavior when +multiple :command:`project` commands are used in the sources. diff --git a/Help/variable/CMAKE_PROJECT_VERSION_PATCH.rst b/Help/variable/CMAKE_PROJECT_VERSION_PATCH.rst new file mode 100644 index 0000000..b8570d9 --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_VERSION_PATCH.rst @@ -0,0 +1,9 @@ +CMAKE_PROJECT_VERSION_PATCH +--------------------------- + +The patch version of the top level project. + +This variable holds the patch version of the project as specified in the top +level CMakeLists.txt file by a :command:`project` command. Please see +:variable:`CMAKE_PROJECT_VERSION` documentation for the behavior when +multiple :command:`project` commands are used in the sources. diff --git a/Help/variable/CMAKE_PROJECT_VERSION_TWEAK.rst b/Help/variable/CMAKE_PROJECT_VERSION_TWEAK.rst new file mode 100644 index 0000000..e1ad4be --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_VERSION_TWEAK.rst @@ -0,0 +1,9 @@ +CMAKE_PROJECT_VERSION_TWEAK +--------------------------- + +The tweak version of the top level project. + +This variable holds the tweak version of the project as specified in the top +level CMakeLists.txt file by a :command:`project` command. Please see +:variable:`CMAKE_PROJECT_VERSION` documentation for the behavior when +multiple :command:`project` commands are used in the sources. diff --git a/Help/variable/CMAKE_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..7460a81 --- /dev/null +++ b/Help/variable/CMAKE_RULE_MESSAGES.rst @@ -0,0 +1,8 @@ +CMAKE_RULE_MESSAGES +------------------- + +Specify whether to report a message for each make rule. + +If set in the cache it is used to initialize the value of the :prop_gbl:`RULE_MESSAGES` property. +Users may disable the option in their local build tree to disable granular messages +and report only as each target completes in Makefile builds. diff --git a/Help/variable/CMAKE_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..080dea6 --- /dev/null +++ b/Help/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY_CONFIG.rst @@ -0,0 +1,9 @@ +CMAKE_RUNTIME_OUTPUT_DIRECTORY_<CONFIG> +--------------------------------------- + +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..185df38 --- /dev/null +++ b/Help/variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG_INIT.rst @@ -0,0 +1,10 @@ +CMAKE_SHARED_LINKER_FLAGS_<CONFIG>_INIT +--------------------------------------- + +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..cb819a7 --- /dev/null +++ b/Help/variable/CMAKE_SHARED_LINKER_FLAGS_INIT.rst @@ -0,0 +1,11 @@ +CMAKE_SHARED_LINKER_FLAGS_INIT +------------------------------ + +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..44966f3 --- /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 installaton 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..416fbe1 --- /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..1310e94 --- /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 ``CMAKE_STAGING_PREFIX`` location is also used as a search prefix by the +``find_*`` commands. This can be controlled by setting the +:variable:`CMAKE_FIND_NO_INSTALL_PREFIX` variable. + +If any RPATH/RUNPATH entries passed to the linker contain the +``CMAKE_STAGING_PREFIX``, the matching path fragments are replaced with the +:variable:`CMAKE_INSTALL_PREFIX`. 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..9c38673 --- /dev/null +++ b/Help/variable/CMAKE_STATIC_LINKER_FLAGS.rst @@ -0,0 +1,6 @@ +CMAKE_STATIC_LINKER_FLAGS +------------------------- + +Linker flags to be used to create static libraries. + +These flags will be used by the linker when creating a static library. 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..b9f8003 --- /dev/null +++ b/Help/variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG.rst @@ -0,0 +1,7 @@ +CMAKE_STATIC_LINKER_FLAGS_<CONFIG> +---------------------------------- + +Flags to be used when linking a static library. + +Same as ``CMAKE_C_FLAGS_*`` but used by the linker when creating static +libraries. 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..a49d1cb --- /dev/null +++ b/Help/variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG_INIT.rst @@ -0,0 +1,10 @@ +CMAKE_STATIC_LINKER_FLAGS_<CONFIG>_INIT +--------------------------------------- + +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..113ca71 --- /dev/null +++ b/Help/variable/CMAKE_STATIC_LINKER_FLAGS_INIT.rst @@ -0,0 +1,11 @@ +CMAKE_STATIC_LINKER_FLAGS_INIT +------------------------------ + +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..02c8663 --- /dev/null +++ b/Help/variable/CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS.rst @@ -0,0 +1,25 @@ +CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS +--------------------------------- + +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..d654425 --- /dev/null +++ b/Help/variable/CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE.rst @@ -0,0 +1,7 @@ +CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE +--------------------------------------- + +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..ed47e1a --- /dev/null +++ b/Help/variable/CMAKE_SUPPRESS_REGENERATION.rst @@ -0,0 +1,11 @@ +CMAKE_SUPPRESS_REGENERATION +--------------------------- + +If CMAKE_SUPPRESS_REGENERATION is ``OFF``, which is default, then CMake adds a +special target on which all other targets depend that checks the build system +and optionally re-runs CMake to regenerate the build system when the target +specification source changes. + +If this variable evaluates to ``ON`` at the end of the top-level +``CMakeLists.txt`` file, CMake will not add the regeneration target to the +build system or perform any build system checks. diff --git a/Help/variable/CMAKE_SYSROOT.rst b/Help/variable/CMAKE_SYSROOT.rst new file mode 100644 index 0000000..64f81bb --- /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..e96c62b --- /dev/null +++ b/Help/variable/CMAKE_SYSROOT_COMPILE.rst @@ -0,0 +1,9 @@ +CMAKE_SYSROOT_COMPILE +--------------------- + +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..88b48ef --- /dev/null +++ b/Help/variable/CMAKE_SYSROOT_LINK.rst @@ -0,0 +1,9 @@ +CMAKE_SYSROOT_LINK +------------------ + +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..666af46 --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_APPBUNDLE_PATH.rst @@ -0,0 +1,7 @@ +CMAKE_SYSTEM_APPBUNDLE_PATH +--------------------------- + +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..14ba18e --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_FRAMEWORK_PATH.rst @@ -0,0 +1,8 @@ +CMAKE_SYSTEM_FRAMEWORK_PATH +--------------------------- + +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..4ad7e33 --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst @@ -0,0 +1,18 @@ +CMAKE_SYSTEM_IGNORE_PATH +------------------------ + +:ref:`;-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..2c14345 --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_INCLUDE_PATH.rst @@ -0,0 +1,8 @@ +CMAKE_SYSTEM_INCLUDE_PATH +------------------------- + +:ref:`;-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..3969cb9 --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_LIBRARY_PATH.rst @@ -0,0 +1,8 @@ +CMAKE_SYSTEM_LIBRARY_PATH +------------------------- + +:ref:`;-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..38b2f8d --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst @@ -0,0 +1,21 @@ +CMAKE_SYSTEM_PREFIX_PATH +------------------------ + +:ref:`;-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 standard 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. + +``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..8ad89f1 --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_PROCESSOR.rst @@ -0,0 +1,8 @@ +CMAKE_SYSTEM_PROCESSOR +---------------------- + +The name of the CPU CMake is building for. + +This variable is the same as :variable:`CMAKE_HOST_SYSTEM_PROCESSOR` if +you build for the host system instead of the target system when +cross compiling. diff --git a/Help/variable/CMAKE_SYSTEM_PROGRAM_PATH.rst b/Help/variable/CMAKE_SYSTEM_PROGRAM_PATH.rst new file mode 100644 index 0000000..cf1b83e --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_PROGRAM_PATH.rst @@ -0,0 +1,8 @@ +CMAKE_SYSTEM_PROGRAM_PATH +------------------------- + +:ref:`;-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..50121e2 --- /dev/null +++ b/Help/variable/CMAKE_Swift_LANGUAGE_VERSION.rst @@ -0,0 +1,5 @@ +CMAKE_Swift_LANGUAGE_VERSION +---------------------------- + +Set to the Swift language version number. If not set, the legacy "2.3" +version is assumed. diff --git a/Help/variable/CMAKE_TOOLCHAIN_FILE.rst b/Help/variable/CMAKE_TOOLCHAIN_FILE.rst new file mode 100644 index 0000000..168ee74 --- /dev/null +++ b/Help/variable/CMAKE_TOOLCHAIN_FILE.rst @@ -0,0 +1,9 @@ +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. 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..0f96787 --- /dev/null +++ b/Help/variable/CMAKE_TRY_COMPILE_PLATFORM_VARIABLES.rst @@ -0,0 +1,26 @@ +CMAKE_TRY_COMPILE_PLATFORM_VARIABLES +------------------------------------ + +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..5fa8dfc --- /dev/null +++ b/Help/variable/CMAKE_TRY_COMPILE_TARGET_TYPE.rst @@ -0,0 +1,15 @@ +CMAKE_TRY_COMPILE_TARGET_TYPE +----------------------------- + +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_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..83777b6 --- /dev/null +++ b/Help/variable/CMAKE_VS_GLOBALS.rst @@ -0,0 +1,21 @@ +CMAKE_VS_GLOBALS +---------------- + +List of ``Key=Value`` records to be set per target as target properties +:prop_tgt:`VS_GLOBAL_<variable>` with ``variable=Key`` and value ``Value``. + +For example: + +.. code-block:: cmake + + set(CMAKE_VS_GLOBALS + "DefaultLanguage=en-US" + "MinimumVisualStudioVersion=14.0" + ) + +will set properties ``VS_GLOBAL_DefaultLanguage`` to ``en-US`` and +``VS_GLOBAL_MinimumVisualStudioVersion`` to ``14.0`` for all targets +(except for ``INTERFACE`` libraries). + +This variable is meant to be set by a +:variable:`toolchain file <CMAKE_TOOLCHAIN_FILE>`. diff --git a/Help/variable/CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD.rst b/Help/variable/CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD.rst new file mode 100644 index 0000000..f54472a --- /dev/null +++ b/Help/variable/CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD.rst @@ -0,0 +1,8 @@ +CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD +----------------------------------------- + +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..693ba45 --- /dev/null +++ b/Help/variable/CMAKE_VS_INCLUDE_PACKAGE_TO_DEFAULT_BUILD.rst @@ -0,0 +1,8 @@ +CMAKE_VS_INCLUDE_PACKAGE_TO_DEFAULT_BUILD +----------------------------------------- + +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_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..386c3a9 --- /dev/null +++ b/Help/variable/CMAKE_VS_NsightTegra_VERSION.rst @@ -0,0 +1,7 @@ +CMAKE_VS_NsightTegra_VERSION +---------------------------- + +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..a532743 --- /dev/null +++ b/Help/variable/CMAKE_VS_PLATFORM_NAME.rst @@ -0,0 +1,8 @@ +CMAKE_VS_PLATFORM_NAME +---------------------- + +Visual Studio target platform name. + +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. 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..1604a76 --- /dev/null +++ b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA.rst @@ -0,0 +1,12 @@ +CMAKE_VS_PLATFORM_TOOLSET_CUDA +------------------------------ + +NVIDIA CUDA Toolkit version whose Visual Studio toolset to use. + +The :ref:`Visual Studio Generators` for VS 2010 and above support using +a CUDA toolset provided by a CUDA Toolkit. The toolset version number +may be specified by a field in :variable:`CMAKE_GENERATOR_TOOLSET` of +the form ``cuda=8.0``. If none is specified CMake will choose a default +version. CMake provides the selected CUDA toolset version in this variable. +The value may be empty if no CUDA Toolkit with Visual Studio integration +is installed. 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..9b59c52 --- /dev/null +++ b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE.rst @@ -0,0 +1,10 @@ +CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE +------------------------------------------- + +Visual Studio preferred tool architecture. + +The :ref:`Visual Studio Generators` for VS 2013 and above support optional +selection of a 64-bit toolchain on 64-bit hosts by specifying a ``host=x64`` +value in the :variable:`CMAKE_GENERATOR_TOOLSET` option. CMake provides +the selected toolchain architecture preference in this variable (either +``x64`` or empty). 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..4d9b978 --- /dev/null +++ b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_VERSION.rst @@ -0,0 +1,11 @@ +CMAKE_VS_PLATFORM_TOOLSET_VERSION +--------------------------------- + +Visual Studio Platform Toolset version. + +The :ref:`Visual Studio Generators` for VS 2017 and above allow to +select minor versions of the same toolset. The toolset version number +may be specified by a field in :variable:`CMAKE_GENERATOR_TOOLSET` of +the form ``version=14.11``. If none is specified CMake will choose a default +toolset. The value may be empty if no minor version was selected and the +default is used. diff --git a/Help/variable/CMAKE_VS_SDK_EXCLUDE_DIRECTORIES.rst b/Help/variable/CMAKE_VS_SDK_EXCLUDE_DIRECTORIES.rst new file mode 100644 index 0000000..36c4dcc --- /dev/null +++ b/Help/variable/CMAKE_VS_SDK_EXCLUDE_DIRECTORIES.rst @@ -0,0 +1,4 @@ +CMAKE_VS_SDK_EXCLUDE_DIRECTORIES +-------------------------------- + +This variable allows to override Visual Studio default Exclude Directories. diff --git a/Help/variable/CMAKE_VS_SDK_EXECUTABLE_DIRECTORIES.rst b/Help/variable/CMAKE_VS_SDK_EXECUTABLE_DIRECTORIES.rst new file mode 100644 index 0000000..3ec755b --- /dev/null +++ b/Help/variable/CMAKE_VS_SDK_EXECUTABLE_DIRECTORIES.rst @@ -0,0 +1,4 @@ +CMAKE_VS_SDK_EXECUTABLE_DIRECTORIES +----------------------------------- + +This variable allows to override Visual Studio default Executable Directories. diff --git a/Help/variable/CMAKE_VS_SDK_INCLUDE_DIRECTORIES.rst b/Help/variable/CMAKE_VS_SDK_INCLUDE_DIRECTORIES.rst new file mode 100644 index 0000000..da10bde --- /dev/null +++ b/Help/variable/CMAKE_VS_SDK_INCLUDE_DIRECTORIES.rst @@ -0,0 +1,4 @@ +CMAKE_VS_SDK_INCLUDE_DIRECTORIES +-------------------------------- + +This variable allows to override Visual Studio default Include Directories. diff --git a/Help/variable/CMAKE_VS_SDK_LIBRARY_DIRECTORIES.rst b/Help/variable/CMAKE_VS_SDK_LIBRARY_DIRECTORIES.rst new file mode 100644 index 0000000..b33754a --- /dev/null +++ b/Help/variable/CMAKE_VS_SDK_LIBRARY_DIRECTORIES.rst @@ -0,0 +1,4 @@ +CMAKE_VS_SDK_LIBRARY_DIRECTORIES +-------------------------------- + +This variable allows to override Visual Studio default Library Directories. diff --git a/Help/variable/CMAKE_VS_SDK_LIBRARY_WINRT_DIRECTORIES.rst b/Help/variable/CMAKE_VS_SDK_LIBRARY_WINRT_DIRECTORIES.rst new file mode 100644 index 0000000..b022215 --- /dev/null +++ b/Help/variable/CMAKE_VS_SDK_LIBRARY_WINRT_DIRECTORIES.rst @@ -0,0 +1,5 @@ +CMAKE_VS_SDK_LIBRARY_WINRT_DIRECTORIES +-------------------------------------- + +This variable allows to override Visual Studio default Library WinRT +Directories. diff --git a/Help/variable/CMAKE_VS_SDK_REFERENCE_DIRECTORIES.rst b/Help/variable/CMAKE_VS_SDK_REFERENCE_DIRECTORIES.rst new file mode 100644 index 0000000..c03f0ae --- /dev/null +++ b/Help/variable/CMAKE_VS_SDK_REFERENCE_DIRECTORIES.rst @@ -0,0 +1,4 @@ +CMAKE_VS_SDK_REFERENCE_DIRECTORIES +---------------------------------- + +This variable allows to override Visual Studio default Reference Directories. diff --git a/Help/variable/CMAKE_VS_SDK_SOURCE_DIRECTORIES.rst b/Help/variable/CMAKE_VS_SDK_SOURCE_DIRECTORIES.rst new file mode 100644 index 0000000..0c73f06 --- /dev/null +++ b/Help/variable/CMAKE_VS_SDK_SOURCE_DIRECTORIES.rst @@ -0,0 +1,4 @@ +CMAKE_VS_SDK_SOURCE_DIRECTORIES +------------------------------- + +This variable allows to override Visual Studio default Source Directories. diff --git a/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst b/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst new file mode 100644 index 0000000..83b9bc1 --- /dev/null +++ b/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst @@ -0,0 +1,17 @@ +CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION +---------------------------------------- + +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. 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..2ba8fe2 --- /dev/null +++ b/Help/variable/CMAKE_VS_WINRT_BY_DEFAULT.rst @@ -0,0 +1,8 @@ +CMAKE_VS_WINRT_BY_DEFAULT +------------------------- + +Tell :ref:`Visual Studio Generators` for VS 2010 and above that the +target platform compiles as WinRT by default (compiles with ``/ZW``). + +This variable is meant to be set by a +:variable:`toolchain file <CMAKE_TOOLCHAIN_FILE>` for such platforms. diff --git a/Help/variable/CMAKE_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..1636842 --- /dev/null +++ b/Help/variable/CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS.rst @@ -0,0 +1,6 @@ +CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS +-------------------------------- + +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..be683d6 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_ATTRIBUTE_an-attribute.rst @@ -0,0 +1,16 @@ +CMAKE_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. + +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_GENERATE_SCHEME.rst b/Help/variable/CMAKE_XCODE_GENERATE_SCHEME.rst new file mode 100644 index 0000000..ed20bbe --- /dev/null +++ b/Help/variable/CMAKE_XCODE_GENERATE_SCHEME.rst @@ -0,0 +1,39 @@ +CMAKE_XCODE_GENERATE_SCHEME +--------------------------- + +If enabled, the Xcode generator will generate schema files. Those are +are useful to invoke analyze, archive, build-for-testing and test +actions from the command line. + +.. note:: + + The Xcode Schema Generator is still experimental and subject to + change. + +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_THREAD_SANITIZER` +- :prop_tgt:`XCODE_SCHEME_THREAD_SANITIZER_STOP` +- :prop_tgt:`XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER` +- :prop_tgt:`XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP` +- :prop_tgt:`XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER` +- :prop_tgt:`XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP` +- :prop_tgt:`XCODE_SCHEME_MALLOC_SCRIBBLE` +- :prop_tgt:`XCODE_SCHEME_MALLOC_GUARD_EDGES` +- :prop_tgt:`XCODE_SCHEME_GUARD_MALLOC` +- :prop_tgt:`XCODE_SCHEME_ZOMBIE_OBJECTS` +- :prop_tgt:`XCODE_SCHEME_MALLOC_STACK` +- :prop_tgt:`XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE` +- :prop_tgt:`XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS` + +The following target properties will be applied on the +"Info" and "Arguments" tab: + +- :prop_tgt:`XCODE_SCHEME_EXECUTABLE` +- :prop_tgt:`XCODE_SCHEME_ARGUMENTS` +- :prop_tgt:`XCODE_SCHEME_ENVIRONMENT` 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..ea3e240 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY.rst @@ -0,0 +1,9 @@ +CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY +------------------------------------------- + +If enabled, the :generator:`Xcode` generator will generate only a +single Xcode project file for the topmost :command:`project()` command +instead of generating one for every ``project()`` command. + +This could be useful to speed up the CMake generation step for +large projects and to work-around a bug in the ``ZERO_CHECK`` logic. diff --git a/Help/variable/CMAKE_XCODE_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..37dc0ce --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER +------------------------------------ + +Whether to enable ``Address Sanitizer`` in the Diagnostics +section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_ADDRESS_SANITIZER` +property on all targets. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +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..05949c3 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN +----------------------------------------------------- + +Whether to enable ``Detect use of stack after return`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN` +property on all targets. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +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..81f4974 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER +---------------------------------------------- + +Whether to disable the ``Main Thread Checker`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER` +property on all targets. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +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..5e133ac --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS +---------------------------------------- + +Whether to enable ``Dynamic Library Loads`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS` +property on all targets. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +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..33162d9 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE +------------------------------------------- + +Whether to enable ``Dynamic Linker API usage`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE` +property on all targets. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +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..03d88c2 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_GUARD_MALLOC.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_GUARD_MALLOC +------------------------------- + +Whether to enable ``Guard Malloc`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_GUARD_MALLOC` +property on all targets. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +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..fd6135f --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP.rst @@ -0,0 +1,13 @@ +CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP +------------------------------------------- + +Whether to enable the ``Main Thread Checker`` option +``Pause on issues`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP` +property on all targets. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +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..8fedc20 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES +------------------------------------- + +Whether to enable ``Malloc Guard Edges`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_MALLOC_GUARD_EDGES` +property on all targets. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +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..cddca7c --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE +---------------------------------- + +Whether to enable ``Malloc Scribble`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_MALLOC_SCRIBBLE` +property on all targets. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +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..9c83698 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_MALLOC_STACK.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_MALLOC_STACK +------------------------------- + +Whether to enable ``Malloc Stack`` in the Diagnostics +section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_MALLOC_STACK` +property on all targets. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +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..c937369 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_THREAD_SANITIZER +----------------------------------- + +Whether to enable ``Thread Sanitizer`` in the Diagnostics +section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_THREAD_SANITIZER` +property on all targets. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +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..eed796c --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP +---------------------------------------- + +Whether to enable ``Thread Sanitizer - Pause on issues`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_THREAD_SANITIZER_STOP` +property on all targets. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +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..d14ba3f --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER +------------------------------------------------ + +Whether to enable ``Undefined Behavior Sanitizer`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER` +property on all targets. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +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..f8df304 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP.rst @@ -0,0 +1,13 @@ +CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP +----------------------------------------------------- + +Whether to enable ``Undefined Behavior Sanitizer`` option +``Pause on issues`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP` +property on all targets. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +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..efc331a --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS +--------------------------------- + +Whether to enable ``Zombie Objects`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_ZOMBIE_OBJECTS` +property on all targets. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +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..5dad6bd --- /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..83d5ce7 --- /dev/null +++ b/Help/variable/CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS.rst @@ -0,0 +1,11 @@ +CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS +------------------------------------------- + +Default permissions for implicitly created directories during packaging. + +This variable serves the same purpose during packaging as the +:variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` variable +serves during installation (e.g. ``make install``). + +If `include(CPack)` is used then by default this variable is set to the content +of :variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS`. diff --git a/Help/variable/CPACK_INSTALL_SCRIPT.rst b/Help/variable/CPACK_INSTALL_SCRIPT.rst new file mode 100644 index 0000000..12a48a4 --- /dev/null +++ b/Help/variable/CPACK_INSTALL_SCRIPT.rst @@ -0,0 +1,8 @@ +CPACK_INSTALL_SCRIPT +-------------------- + +Extra CMake script provided by the user. + +If set this CMake script will be executed by CPack during its local +[CPack-private] installation which is done right before packaging the +files. The script is not called by e.g.: ``make install``. diff --git a/Help/variable/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..fd8461f --- /dev/null +++ b/Help/variable/CTEST_BINARY_DIRECTORY.rst @@ -0,0 +1,5 @@ +CTEST_BINARY_DIRECTORY +---------------------- + +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..7b13ba0 --- /dev/null +++ b/Help/variable/CTEST_BUILD_COMMAND.rst @@ -0,0 +1,5 @@ +CTEST_BUILD_COMMAND +------------------- + +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..d25d84c --- /dev/null +++ b/Help/variable/CTEST_BUILD_NAME.rst @@ -0,0 +1,5 @@ +CTEST_BUILD_NAME +---------------- + +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..474d621 --- /dev/null +++ b/Help/variable/CTEST_BZR_COMMAND.rst @@ -0,0 +1,5 @@ +CTEST_BZR_COMMAND +----------------- + +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..d0f9579 --- /dev/null +++ b/Help/variable/CTEST_BZR_UPDATE_OPTIONS.rst @@ -0,0 +1,5 @@ +CTEST_BZR_UPDATE_OPTIONS +------------------------ + +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..a423f49 --- /dev/null +++ b/Help/variable/CTEST_CHANGE_ID.rst @@ -0,0 +1,9 @@ +CTEST_CHANGE_ID +--------------- + +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..da256f2 --- /dev/null +++ b/Help/variable/CTEST_CHECKOUT_COMMAND.rst @@ -0,0 +1,5 @@ +CTEST_CHECKOUT_COMMAND +---------------------- + +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..c905480 --- /dev/null +++ b/Help/variable/CTEST_CONFIGURATION_TYPE.rst @@ -0,0 +1,5 @@ +CTEST_CONFIGURATION_TYPE +------------------------ + +Specify the CTest ``DefaultCTestConfigurationType`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_CONFIGURE_COMMAND.rst b/Help/variable/CTEST_CONFIGURE_COMMAND.rst new file mode 100644 index 0000000..5561b6d --- /dev/null +++ b/Help/variable/CTEST_CONFIGURE_COMMAND.rst @@ -0,0 +1,5 @@ +CTEST_CONFIGURE_COMMAND +----------------------- + +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..a78792e --- /dev/null +++ b/Help/variable/CTEST_COVERAGE_COMMAND.rst @@ -0,0 +1,60 @@ +CTEST_COVERAGE_COMMAND +---------------------- + +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..2981955 --- /dev/null +++ b/Help/variable/CTEST_COVERAGE_EXTRA_FLAGS.rst @@ -0,0 +1,5 @@ +CTEST_COVERAGE_EXTRA_FLAGS +-------------------------- + +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..fc5dfc4 --- /dev/null +++ b/Help/variable/CTEST_CURL_OPTIONS.rst @@ -0,0 +1,5 @@ +CTEST_CURL_OPTIONS +------------------ + +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_TEST_IGNORE.rst b/Help/variable/CTEST_CUSTOM_TEST_IGNORE.rst new file mode 100644 index 0000000..6114e60 --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_TEST_IGNORE.rst @@ -0,0 +1,7 @@ +CTEST_CUSTOM_TEST_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..36fa37d --- /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_test` 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..a35be96 --- /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_test` 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..6431c02 --- /dev/null +++ b/Help/variable/CTEST_CVS_CHECKOUT.rst @@ -0,0 +1,4 @@ +CTEST_CVS_CHECKOUT +------------------ + +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..049700b --- /dev/null +++ b/Help/variable/CTEST_CVS_COMMAND.rst @@ -0,0 +1,5 @@ +CTEST_CVS_COMMAND +----------------- + +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..d7f2f7c --- /dev/null +++ b/Help/variable/CTEST_CVS_UPDATE_OPTIONS.rst @@ -0,0 +1,5 @@ +CTEST_CVS_UPDATE_OPTIONS +------------------------ + +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..c0f2215 --- /dev/null +++ b/Help/variable/CTEST_DROP_LOCATION.rst @@ -0,0 +1,5 @@ +CTEST_DROP_LOCATION +------------------- + +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..50fbd4d --- /dev/null +++ b/Help/variable/CTEST_DROP_METHOD.rst @@ -0,0 +1,5 @@ +CTEST_DROP_METHOD +----------------- + +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..d15d99b --- /dev/null +++ b/Help/variable/CTEST_DROP_SITE.rst @@ -0,0 +1,5 @@ +CTEST_DROP_SITE +--------------- + +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..22b9776 --- /dev/null +++ b/Help/variable/CTEST_DROP_SITE_CDASH.rst @@ -0,0 +1,5 @@ +CTEST_DROP_SITE_CDASH +--------------------- + +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..904d2c8 --- /dev/null +++ b/Help/variable/CTEST_DROP_SITE_PASSWORD.rst @@ -0,0 +1,5 @@ +CTEST_DROP_SITE_PASSWORD +------------------------ + +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..a860a03 --- /dev/null +++ b/Help/variable/CTEST_DROP_SITE_USER.rst @@ -0,0 +1,5 @@ +CTEST_DROP_SITE_USER +-------------------- + +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..286f7df --- /dev/null +++ b/Help/variable/CTEST_EXTRA_COVERAGE_GLOB.rst @@ -0,0 +1,7 @@ +CTEST_EXTRA_COVERAGE_GLOB +------------------------- + +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..eb83792 --- /dev/null +++ b/Help/variable/CTEST_GIT_COMMAND.rst @@ -0,0 +1,5 @@ +CTEST_GIT_COMMAND +----------------- + +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..fd27003 --- /dev/null +++ b/Help/variable/CTEST_GIT_INIT_SUBMODULES.rst @@ -0,0 +1,5 @@ +CTEST_GIT_INIT_SUBMODULES +------------------------- + +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..0c479e6 --- /dev/null +++ b/Help/variable/CTEST_GIT_UPDATE_CUSTOM.rst @@ -0,0 +1,5 @@ +CTEST_GIT_UPDATE_CUSTOM +----------------------- + +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..4590a78 --- /dev/null +++ b/Help/variable/CTEST_GIT_UPDATE_OPTIONS.rst @@ -0,0 +1,5 @@ +CTEST_GIT_UPDATE_OPTIONS +------------------------ + +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..3854950 --- /dev/null +++ b/Help/variable/CTEST_HG_COMMAND.rst @@ -0,0 +1,5 @@ +CTEST_HG_COMMAND +---------------- + +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..9049c1f --- /dev/null +++ b/Help/variable/CTEST_HG_UPDATE_OPTIONS.rst @@ -0,0 +1,5 @@ +CTEST_HG_UPDATE_OPTIONS +----------------------- + +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..959596b --- /dev/null +++ b/Help/variable/CTEST_LABELS_FOR_SUBPROJECTS.rst @@ -0,0 +1,5 @@ +CTEST_LABELS_FOR_SUBPROJECTS +---------------------------- + +Specify the CTest ``LabelsForSubprojects`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_MEMORYCHECK_COMMAND.rst b/Help/variable/CTEST_MEMORYCHECK_COMMAND.rst new file mode 100644 index 0000000..8c199ba --- /dev/null +++ b/Help/variable/CTEST_MEMORYCHECK_COMMAND.rst @@ -0,0 +1,5 @@ +CTEST_MEMORYCHECK_COMMAND +------------------------- + +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..3e26ab5 --- /dev/null +++ b/Help/variable/CTEST_MEMORYCHECK_COMMAND_OPTIONS.rst @@ -0,0 +1,5 @@ +CTEST_MEMORYCHECK_COMMAND_OPTIONS +--------------------------------- + +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..2de5fb6 --- /dev/null +++ b/Help/variable/CTEST_MEMORYCHECK_SANITIZER_OPTIONS.rst @@ -0,0 +1,5 @@ +CTEST_MEMORYCHECK_SANITIZER_OPTIONS +----------------------------------- + +Specify the CTest ``MemoryCheckSanitizerOptions`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_MEMORYCHECK_SUPPRESSIONS_FILE.rst b/Help/variable/CTEST_MEMORYCHECK_SUPPRESSIONS_FILE.rst new file mode 100644 index 0000000..1147ee8 --- /dev/null +++ b/Help/variable/CTEST_MEMORYCHECK_SUPPRESSIONS_FILE.rst @@ -0,0 +1,5 @@ +CTEST_MEMORYCHECK_SUPPRESSIONS_FILE +----------------------------------- + +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..b8b4c30 --- /dev/null +++ b/Help/variable/CTEST_MEMORYCHECK_TYPE.rst @@ -0,0 +1,8 @@ +CTEST_MEMORYCHECK_TYPE +---------------------- + +Specify the CTest ``MemoryCheckType`` setting +in a :manual:`ctest(1)` dashboard client script. +Valid values are ``Valgrind``, ``Purify``, ``BoundsChecker``, and +``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..bc80276 --- /dev/null +++ b/Help/variable/CTEST_NIGHTLY_START_TIME.rst @@ -0,0 +1,5 @@ +CTEST_NIGHTLY_START_TIME +------------------------ + +Specify the CTest ``NightlyStartTime`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_P4_CLIENT.rst b/Help/variable/CTEST_P4_CLIENT.rst new file mode 100644 index 0000000..347ea54 --- /dev/null +++ b/Help/variable/CTEST_P4_CLIENT.rst @@ -0,0 +1,5 @@ +CTEST_P4_CLIENT +--------------- + +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..defab12 --- /dev/null +++ b/Help/variable/CTEST_P4_COMMAND.rst @@ -0,0 +1,5 @@ +CTEST_P4_COMMAND +---------------- + +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..fee4ce2 --- /dev/null +++ b/Help/variable/CTEST_P4_OPTIONS.rst @@ -0,0 +1,5 @@ +CTEST_P4_OPTIONS +---------------- + +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..0e2790f --- /dev/null +++ b/Help/variable/CTEST_P4_UPDATE_OPTIONS.rst @@ -0,0 +1,5 @@ +CTEST_P4_UPDATE_OPTIONS +----------------------- + +Specify the CTest ``P4UpdateOptions`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_RUN_CURRENT_SCRIPT.rst b/Help/variable/CTEST_RUN_CURRENT_SCRIPT.rst new file mode 100644 index 0000000..abc123c --- /dev/null +++ b/Help/variable/CTEST_RUN_CURRENT_SCRIPT.rst @@ -0,0 +1,5 @@ +CTEST_RUN_CURRENT_SCRIPT +------------------------ + +Setting this to 0 prevents :manual:`ctest(1)` from being run again when it +reaches the end of a script run by calling ``ctest -S``. diff --git a/Help/variable/CTEST_SCP_COMMAND.rst b/Help/variable/CTEST_SCP_COMMAND.rst new file mode 100644 index 0000000..0f128b1 --- /dev/null +++ b/Help/variable/CTEST_SCP_COMMAND.rst @@ -0,0 +1,5 @@ +CTEST_SCP_COMMAND +----------------- + +Specify the CTest ``SCPCommand`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_SITE.rst b/Help/variable/CTEST_SITE.rst new file mode 100644 index 0000000..8a5ec25 --- /dev/null +++ b/Help/variable/CTEST_SITE.rst @@ -0,0 +1,5 @@ +CTEST_SITE +---------- + +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..b6837d1 --- /dev/null +++ b/Help/variable/CTEST_SOURCE_DIRECTORY.rst @@ -0,0 +1,5 @@ +CTEST_SOURCE_DIRECTORY +---------------------- + +Specify the CTest ``SourceDirectory`` 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..af90143 --- /dev/null +++ b/Help/variable/CTEST_SVN_COMMAND.rst @@ -0,0 +1,5 @@ +CTEST_SVN_COMMAND +----------------- + +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..76551dc --- /dev/null +++ b/Help/variable/CTEST_SVN_OPTIONS.rst @@ -0,0 +1,5 @@ +CTEST_SVN_OPTIONS +----------------- + +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..5f01a19 --- /dev/null +++ b/Help/variable/CTEST_SVN_UPDATE_OPTIONS.rst @@ -0,0 +1,5 @@ +CTEST_SVN_UPDATE_OPTIONS +------------------------ + +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..80823fe --- /dev/null +++ b/Help/variable/CTEST_TEST_LOAD.rst @@ -0,0 +1,7 @@ +CTEST_TEST_LOAD +--------------- + +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..c031437 --- /dev/null +++ b/Help/variable/CTEST_TEST_TIMEOUT.rst @@ -0,0 +1,5 @@ +CTEST_TEST_TIMEOUT +------------------ + +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..de92428 --- /dev/null +++ b/Help/variable/CTEST_TRIGGER_SITE.rst @@ -0,0 +1,5 @@ +CTEST_TRIGGER_SITE +------------------ + +Specify the CTest ``TriggerSite`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_UPDATE_COMMAND.rst b/Help/variable/CTEST_UPDATE_COMMAND.rst new file mode 100644 index 0000000..90155d0 --- /dev/null +++ b/Help/variable/CTEST_UPDATE_COMMAND.rst @@ -0,0 +1,5 @@ +CTEST_UPDATE_COMMAND +-------------------- + +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..e43d61d --- /dev/null +++ b/Help/variable/CTEST_UPDATE_OPTIONS.rst @@ -0,0 +1,5 @@ +CTEST_UPDATE_OPTIONS +-------------------- + +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..e646e6e --- /dev/null +++ b/Help/variable/CTEST_UPDATE_VERSION_ONLY.rst @@ -0,0 +1,5 @@ +CTEST_UPDATE_VERSION_ONLY +------------------------- + +Specify the CTest ``UpdateVersionOnly`` 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..9f48a2e --- /dev/null +++ b/Help/variable/CTEST_USE_LAUNCHERS.rst @@ -0,0 +1,5 @@ +CTEST_USE_LAUNCHERS +------------------- + +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..98677dd --- /dev/null +++ b/Help/variable/ENV.rst @@ -0,0 +1,8 @@ +ENV +--- + +Read environment variables. + +Use the syntax ``$ENV{VAR}`` to read environment variable ``VAR``. + +See the :command:`set` command to see how to write 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..0f91be8 --- /dev/null +++ b/Help/variable/GHS-MULTI.rst @@ -0,0 +1,4 @@ +GHS-MULTI +--------- + +True when using Green Hills MULTI 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..6d29be4 --- /dev/null +++ b/Help/variable/MINGW.rst @@ -0,0 +1,6 @@ +MINGW +----- + +``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..ca8775c --- /dev/null +++ b/Help/variable/MSVC.rst @@ -0,0 +1,8 @@ +MSVC +---- + +Set to ``true`` when the compiler is some version of Microsoft Visual +C++ or another compiler simulating Visual C++. Any compiler defining +``_MSC_VER`` is considered simulating Visual C++. + +See also the :variable:`MSVC_VERSION` variable. diff --git a/Help/variable/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..79e0c10 --- /dev/null +++ b/Help/variable/MSVC14.rst @@ -0,0 +1,7 @@ +MSVC14 +------ + +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..027d1bc --- /dev/null +++ b/Help/variable/MSVC_IDE.rst @@ -0,0 +1,7 @@ +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. diff --git a/Help/variable/MSVC_TOOLSET_VERSION.rst b/Help/variable/MSVC_TOOLSET_VERSION.rst new file mode 100644 index 0000000..77e1ea9 --- /dev/null +++ b/Help/variable/MSVC_TOOLSET_VERSION.rst @@ -0,0 +1,21 @@ +MSVC_TOOLSET_VERSION +-------------------- + +The toolset version of Microsoft Visual C/C++ being used if any. +If MSVC-like is being used, this variable is set based on the version +of the compiler as given by the :variable:`MSVC_VERSION` variable. + +Known toolset version numbers are:: + + 80 = VS 2005 (8.0) + 90 = VS 2008 (9.0) + 100 = VS 2010 (10.0) + 110 = VS 2012 (11.0) + 120 = VS 2013 (12.0) + 140 = VS 2015 (14.0) + 141 = VS 2017 (15.0) + +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..4ef43d8 --- /dev/null +++ b/Help/variable/MSVC_VERSION.rst @@ -0,0 +1,23 @@ +MSVC_VERSION +------------ + +The version of Microsoft Visual C/C++ being used if any. +If a compiler simulating Visual C++ is being used, this variable is set +to the toolset version simulated as given by the ``_MSC_VER`` +preprocessor definition. + +Known version numbers are:: + + 1200 = VS 6.0 + 1300 = VS 7.0 + 1310 = VS 7.1 + 1400 = VS 8.0 (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) + +See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` and +:variable:`MSVC_TOOLSET_VERSION` variable. 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..2b88b1a --- /dev/null +++ b/Help/variable/PROJECT-NAME_DESCRIPTION.rst @@ -0,0 +1,5 @@ +<PROJECT-NAME>_DESCRIPTION +-------------------------- + +Value given to the ``DESCRIPTION`` option of the most recent call to the +:command:`project` command with project name ``<PROJECT-NAME>``, if any. diff --git a/Help/variable/PROJECT-NAME_HOMEPAGE_URL.rst b/Help/variable/PROJECT-NAME_HOMEPAGE_URL.rst new file mode 100644 index 0000000..22cc304 --- /dev/null +++ b/Help/variable/PROJECT-NAME_HOMEPAGE_URL.rst @@ -0,0 +1,5 @@ +<PROJECT-NAME>_HOMEPAGE_URL +--------------------------- + +Value given to the ``HOMEPAGE_URL`` option of the most recent call to the +:command:`project` command with project name ``<PROJECT-NAME>``, if any. diff --git a/Help/variable/PROJECT-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..2833e11 --- /dev/null +++ b/Help/variable/PROJECT_DESCRIPTION.rst @@ -0,0 +1,9 @@ +PROJECT_DESCRIPTION +------------------- + +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..754c9e8 --- /dev/null +++ b/Help/variable/PROJECT_HOMEPAGE_URL.rst @@ -0,0 +1,9 @@ +PROJECT_HOMEPAGE_URL +-------------------- + +The homepage URL of the project. + +This is the homepage URL given to the most recently called :command:`project` +command in the current directory scope or above. To obtain the homepage URL +of the top level project, see the :variable:`CMAKE_PROJECT_HOMEPAGE_URL` +variable. diff --git a/Help/variable/PROJECT_NAME.rst b/Help/variable/PROJECT_NAME.rst 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..27f2838 --- /dev/null +++ b/Help/variable/PROJECT_SOURCE_DIR.rst @@ -0,0 +1,6 @@ +PROJECT_SOURCE_DIR +------------------ + +Top level source directory for the current project. + +This is the source directory of the most recent :command:`project` command. 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..4f6c25b --- /dev/null +++ b/Help/variable/PackageName_ROOT.rst @@ -0,0 +1,14 @@ +<PackageName>_ROOT +------------------ + +Calls to :command:`find_package(<PackageName>)` will search in prefixes +specified by the ``<PackageName>_ROOT`` CMake variable, where +``<PackageName>`` is the name given to the ``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:`;-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..54ff7de --- /dev/null +++ b/Help/variable/WINCE.rst @@ -0,0 +1,5 @@ +WINCE +----- + +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..61d91b0 --- /dev/null +++ b/Help/variable/WINDOWS_PHONE.rst @@ -0,0 +1,5 @@ +WINDOWS_PHONE +------------- + +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..dae3b53 --- /dev/null +++ b/Help/variable/WINDOWS_STORE.rst @@ -0,0 +1,5 @@ +WINDOWS_STORE +------------- + +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..99f20fb --- /dev/null +++ b/Help/variable/XCODE.rst @@ -0,0 +1,4 @@ +XCODE +----- + +``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..b85d41e --- /dev/null +++ b/Help/variable/XCODE_VERSION.rst @@ -0,0 +1,7 @@ +XCODE_VERSION +------------- + +Version of Xcode (:generator:`Xcode` generator only). + +Under the Xcode generator, this is the version of Xcode as specified +in ``Xcode.app/Contents/version.plist`` (such as ``3.1.2``). |