diff options
Diffstat (limited to 'Help')
1335 files changed, 31734 insertions, 0 deletions
diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt new file mode 100644 index 000000000..7db221cb8 --- /dev/null +++ b/Help/command/FIND_XXX.txt @@ -0,0 +1,122 @@ +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_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: + +.. |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. 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| + +2. 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| + +3. Search the paths specified by the ``HINTS`` option. + These should be paths computed by system introspection, such as a + hint provided by the location of another item already found. + Hard-coded guesses should be specified with the ``PATHS`` option. + +4. Search the standard system environment variables. + This can be skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is an argument. + + * |SYSTEM_ENVIRONMENT_PATH_XXX| + +5. 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| + +6. Search the paths specified by the PATHS option + or in the short-hand version of the command. + These are typically hard-coded guesses. + +.. |FIND_ARGS_XXX| replace:: <VAR> NAMES name + +On OS X the :variable:`CMAKE_FIND_FRAMEWORK` and +: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 000000000..bac241964 --- /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 000000000..fab23037c --- /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/add_compile_options.rst b/Help/command/add_compile_options.rst new file mode 100644 index 000000000..3fe2a3330 --- /dev/null +++ b/Help/command/add_compile_options.rst @@ -0,0 +1,23 @@ +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_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. diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst new file mode 100644 index 000000000..d03840633 --- /dev/null +++ b/Help/command/add_custom_command.rst @@ -0,0 +1,227 @@ +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. At most one custom command may specify a + given source file as its main dependency. + +``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. + +``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`` + Run before any other rules are executed within the target. + This is supported only on Visual Studio 8 or later. + For all other generators ``PRE_BUILD`` will be treated as + ``PRE_LINK``. +``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. diff --git a/Help/command/add_custom_target.rst b/Help/command/add_custom_target.rst new file mode 100644 index 000000000..bd61c8b96 --- /dev/null +++ b/Help/command/add_custom_target.rst @@ -0,0 +1,123 @@ +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. diff --git a/Help/command/add_definitions.rst b/Help/command/add_definitions.rst new file mode 100644 index 000000000..a04faf591 --- /dev/null +++ b/Help/command/add_definitions.rst @@ -0,0 +1,27 @@ +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 (see the :command:`add_compile_options` command +to add other flags). +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 000000000..7a6614328 --- /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 000000000..c088796e4 --- /dev/null +++ b/Help/command/add_executable.rst @@ -0,0 +1,83 @@ +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 ``<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 an :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 000000000..de5335eff --- /dev/null +++ b/Help/command/add_library.rst @@ -0,0 +1,165 @@ +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 ``<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 OS X 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. 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. Object libraries +cannot be linked. Some native build systems may not like targets that +have only object files, so consider adding at least one real source file +to any target that references ``$<TARGET_OBJECTS:objlib>``. + +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 an :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_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_subdirectory.rst b/Help/command/add_subdirectory.rst new file mode 100644 index 000000000..e97925302 --- /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 supercede 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 000000000..d8a96e9b9 --- /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 000000000..dcd1cdfc3 --- /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 000000000..fc2cd3c7b --- /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 000000000..b83edaf57 --- /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 000000000..f717db1dd --- /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 000000000..9402d57e9 --- /dev/null +++ b/Help/command/cmake_host_system_information.rst @@ -0,0 +1,25 @@ +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: + +:: + + NUMBER_OF_LOGICAL_CORES = Number of logical cores. + NUMBER_OF_PHYSICAL_CORES = Number of physical cores. + HOSTNAME = Hostname. + FQDN = Fully qualified domain name. + TOTAL_VIRTUAL_MEMORY = Total virtual memory in megabytes. + AVAILABLE_VIRTUAL_MEMORY = Available virtual memory in megabytes. + TOTAL_PHYSICAL_MEMORY = Total physical memory in megabytes. + AVAILABLE_PHYSICAL_MEMORY = Available physical memory in megabytes. diff --git a/Help/command/cmake_minimum_required.rst b/Help/command/cmake_minimum_required.rst new file mode 100644 index 000000000..9535bf34f --- /dev/null +++ b/Help/command/cmake_minimum_required.rst @@ -0,0 +1,50 @@ +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 major.minor[.patch[.tweak]] + [FATAL_ERROR]) + +If the current version of CMake is lower than that required it will +stop processing the project and report an error. + +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 version of CMake. +All policies introduced in the specified version or earlier will be +set to use NEW behavior. All policies introduced after the specified +version will be unset. This effectively requests behavior preferred +as of a given CMake version and tells newer CMake versions to warn +about their new policies. + +When a version higher than 2.4 is specified the command implicitly +invokes:: + + cmake_policy(VERSION major[.minor[.patch[.tweak]]]) + +which sets the cmake policy version level to the version specified. +When version 2.4 or lower is given the command implicitly invokes:: + + cmake_policy(VERSION 2.4) + +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 000000000..ec4ffed3a --- /dev/null +++ b/Help/command/cmake_parse_arguments.rst @@ -0,0 +1,96 @@ +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 have defined for each of the +keywords listed in ``<options>``, ``<one_value_keywords>`` and +``<multi_value_keywords>`` a variable composed of the given ``<prefix>`` +followed by ``"_"`` and the name of the respective keyword. These +variables will then hold the respective value from the argument list. +For the ``<options>`` keywords this will be ``TRUE`` or ``FALSE``. + +All remaining arguments are collected in a variable +``<prefix>_UNPARSED_ARGUMENTS``, 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 + + function(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 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 = "" (was not used) + MY_INSTALL_TARGETS = "foo;bar" + MY_INSTALL_CONFIGURATIONS = "" (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 000000000..b51b9512c --- /dev/null +++ b/Help/command/cmake_policy.rst @@ -0,0 +1,96 @@ +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 major.minor[.patch[.tweak]]) + +Specify that the current CMake code is written for the given +version of CMake. All policies introduced in the specified version or +earlier will be set to use ``NEW`` behavior. All policies introduced +after the specified version will be unset (unless the +:variable:`CMAKE_POLICY_DEFAULT_CMP<NNNN>` variable sets a default). +This effectively requests behavior preferred as of a given CMake +version and tells newer CMake versions to warn about their new policies. +The policy version specified must be at least 2.4 or the command will +report an error. + +Note that the :command:`cmake_minimum_required(VERSION)` +command implicitly calls ``cmake_policy(VERSION)`` too. + +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 000000000..4304f095b --- /dev/null +++ b/Help/command/configure_file.rst @@ -0,0 +1,111 @@ +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. + +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 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 000000000..1c7d6730c --- /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 000000000..dde6812e1 --- /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 000000000..55bb4a317 --- /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 000000000..2dea07b16 --- /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 000000000..8d27b9c1b --- /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 000000000..77536673c --- /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 000000000..288b65a25 --- /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 000000000..cf8e17a9c --- /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 000000000..5ec543ed1 --- /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 000000000..16a914c0b --- /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 000000000..63db32f4e --- /dev/null +++ b/Help/command/ctest_start.rst @@ -0,0 +1,25 @@ +ctest_start +----------- + +Starts the testing for a given model + +:: + + ctest_start(Model [TRACK <track>] [APPEND] [source [binary]] [QUIET]) + +Starts the testing for a given model. The command should be called +after the binary directory is initialized. If the 'source' and +'binary' directory are not specified, it reads the +:variable:`CTEST_SOURCE_DIRECTORY` and :variable:`CTEST_BINARY_DIRECTORY`. +If the track is +specified, the submissions will go to the specified track. If APPEND +is used, the existing TAG is used rather than creating a new one based +on the current time stamp. If ``QUIET`` is used, CTest will suppress any +non-error messages that it otherwise would have printed to the console. + +If the :variable:`CTEST_CHECKOUT_COMMAND` variable +(or the :variable:`CTEST_CVS_CHECKOUT` variable) +is set, its content is treated as command-line. The command is +invoked with the current working directory set to the parent of the source +directory, even if the source directory already exists. This can be used +to create the source tree from a version control repository. diff --git a/Help/command/ctest_submit.rst b/Help/command/ctest_submit.rst new file mode 100644 index 000000000..6b49da392 --- /dev/null +++ b/Help/command/ctest_submit.rst @@ -0,0 +1,77 @@ +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>] + [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. + +``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>] + [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``, 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 000000000..4a69491d5 --- /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 000000000..b205bca93 --- /dev/null +++ b/Help/command/ctest_update.rst @@ -0,0 +1,31 @@ +ctest_update +------------ + +Perform the :ref:`CTest Update Step` as a :ref:`Dashboard Client`. + +:: + + ctest_update([SOURCE <source-dir>] [RETURN_VALUE <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. + +``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 000000000..39d9de1a3 --- /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 000000000..873c6cabb --- /dev/null +++ b/Help/command/define_property.rst @@ -0,0 +1,45 @@ +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 then the :command:`get_property` command will +chain up to the next higher scope when the requested property is not set +in the scope given to the command. ``DIRECTORY`` scope chains to +``GLOBAL``. ``TARGET``, ``SOURCE``, and ``TEST`` chain to ``DIRECTORY``. + +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 000000000..0e5a19810 --- /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 000000000..9a8dfed1d --- /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 000000000..444556151 --- /dev/null +++ b/Help/command/enable_language.rst @@ -0,0 +1,22 @@ +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, Fortran. + +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. diff --git a/Help/command/enable_testing.rst b/Help/command/enable_testing.rst new file mode 100644 index 000000000..1e3e2799c --- /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 000000000..9af972bee --- /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 000000000..6cc196cde --- /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 000000000..a0163bf33 --- /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 000000000..47327a783 --- /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 000000000..798c20e71 --- /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 000000000..6dfdad394 --- /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 000000000..d617243d1 --- /dev/null +++ b/Help/command/execute_process.rst @@ -0,0 +1,99 @@ +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>] + [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 running the processes. + This will be an integer return code from the last 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`` + Use the UTF-8 codepage. + +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 000000000..53675a756 --- /dev/null +++ b/Help/command/export.rst @@ -0,0 +1,72 @@ +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. + +:: + + export(PACKAGE <name>) + +Store the current build directory in the CMake user package registry +for package ``<name>``. The find_package command may consider the +directory while searching for package ``<name>``. This helps dependent +projects find and use a package from the current project's build tree +without help from the user. Note that the entry in the package +registry that this command creates works only in conjunction with a +package configuration file (``<name>Config.cmake``) that works with the +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 000000000..2cb437e77 --- /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 000000000..b2e4eea44 --- /dev/null +++ b/Help/command/file.rst @@ -0,0 +1,373 @@ +file +---- + +File manipulation command. + +------------------------------------------------------------------------------ + +:: + + 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. +(If the file is a build input, use the :command:`configure_file` command +to update the file only when its content changes.) + +------------------------------------------------------------------------------ + +:: + + 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). + +------------------------------------------------------------------------------ + +:: + + 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. + +------------------------------------------------------------------------------ + +:: + + 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. + +------------------------------------------------------------------------------ + +:: + + file(GLOB <variable> + [LIST_DIRECTORIES true|false] [RELATIVE <path>] + [<globbing-expressions>...]) + file(GLOB_RECURSE <variable> [FOLLOW_SYMLINKS] + [LIST_DIRECTORIES true|false] [RELATIVE <path>] + [<globbing-expressions>...]) + +Generate a list of files that match the ``<globbing-expressions>`` and +store it into the ``<variable>``. Globbing expressions are similar to +regular expressions, but much simpler. If ``RELATIVE`` flag is +specified, the results will be returned as relative paths to the given +path. No specific order of results is defined other than that it is +deterministic. If order is important then sort the list explicitly +(e.g. using the :command:`list(SORT)` command). + +By default ``GLOB`` lists directories - directories are omited 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. + +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 + +------------------------------------------------------------------------------ + +:: + + file(RENAME <oldname> <newname>) + +Move a file or directory within a filesystem from ``<oldname>`` to +``<newname>``, replacing the destination atomically. + +------------------------------------------------------------------------------ + +:: + + 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. + +------------------------------------------------------------------------------ + +:: + + file(MAKE_DIRECTORY [<directories>...]) + +Create the given directories and their parents as needed. + +------------------------------------------------------------------------------ + +:: + + file(RELATIVE_PATH <variable> <directory> <file>) + +Compute the relative path from a ``<directory>`` to a ``<file>`` and +store it in the ``<variable>``. + +------------------------------------------------------------------------------ + +:: + + 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. + +------------------------------------------------------------------------------ + +:: + + 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. + +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. + +------------------------------------------------------------------------------ + +:: + + file(TIMESTAMP <filename> <variable> [<format>] [UTC]) + +Compute a string representation of the modification time of ``<filename>`` +and store it in ``<variable>``. Should the command be unable to obtain a +timestamp variable will be set to the empty string (""). + +See the :command:`string(TIMESTAMP)` command for documentation of +the ``<format>`` and ``UTC`` options. + +------------------------------------------------------------------------------ + +:: + + file(GENERATE OUTPUT output-file + <INPUT input-file|CONTENT content> + [CONDITION expression]) + +Generate an output file for each build configuration supported by the current +:manual:`CMake Generator <cmake-generators(7)>`. Evaluate +:manual:`generator expressions <cmake-generator-expressions(7)>` +from the input content to produce the output content. The options are: + +``CONDITION <condition>`` + Generate the output file for a particular configuration only if + the condition is true. The condition must be either ``0`` or ``1`` + after evaluating generator expressions. + +``CONTENT <content>`` + Use the content given explicitly as input. + +``INPUT <input-file>`` + Use the content from a given file as input. + +``OUTPUT <output-file>`` + Specify the output file name to generate. Use generator expressions + such as ``$<CONFIG>`` to specify a configuration-specific output file + name. Multiple configurations may generate the same output file only + if the generated content is identical. Otherwise, the ``<output-file>`` + must evaluate to an unique name for each configuration. + +Exactly one ``CONTENT`` or ``INPUT`` option must be given. A specific +``OUTPUT`` file may be named by at most one invocation of ``file(GENERATE)``. +Generated files are modified on subsequent cmake runs only if their content +is changed. + +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. + +------------------------------------------------------------------------------ + +:: + + 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). + +------------------------------------------------------------------------------ + +:: + + 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 000000000..e56097bea --- /dev/null +++ b/Help/command/find_file.rst @@ -0,0 +1,34 @@ +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`` + +.. |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 000000000..f774f17ec --- /dev/null +++ b/Help/command/find_library.rst @@ -0,0 +1,79 @@ +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`` + +.. |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 000000000..83f471619 --- /dev/null +++ b/Help/command/find_package.rst @@ -0,0 +1,360 @@ +find_package +------------ + +Load settings for an external project. + +:: + + find_package(<package> [version] [EXACT] [QUIET] [MODULE] + [REQUIRED] [[COMPONENTS] [components...]] + [OPTIONAL_COMPONENTS components...] + [NO_POLICY_SCOPE]) + +Finds and loads settings from an external project. ``<package>_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<package>.cmake`` in the :variable:`CMAKE_MODULE_PATH` +followed by the CMake installation. If the file is found, it is read +and processed by CMake. It is responsible for finding the package, +checking the version, and producing any needed messages. Many +find-modules provide limited or no support for versioning; check +the module documentation. If no module is found and the ``MODULE`` +option is not given the command proceeds to Config mode. + +The complete Config mode command signature is:: + + find_package(<package> [version] [EXACT] [QUIET] + [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_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 ``<package>_DIR`` is created to +hold the directory containing the file. By default the command +searches for a package with the name ``<package>``. If the ``NAMES`` option +is given the names following it are used instead of ``<package>``. The +command searches for a file called ``<name>Config.cmake`` or +``<lower-case-name>-config.cmake`` for each name specified. A +replacement set of possible configuration file names may be given +using the ``CONFIGS`` option. The search procedure is specified below. +Once found, the configuration file is read and processed by CMake. +Since the file is provided by the package it already knows the +location of package contents. The full path to the configuration file +is stored in the cmake variable ``<package>_CONFIG``. + +All configuration files which have been considered by CMake while +searching for an installation of the package with an appropriate +version are stored in the cmake variable ``<package>_CONSIDERED_CONFIGS``, +the associated versions in ``<package>_CONSIDERED_VERSIONS``. + +If the package configuration file cannot be found CMake will generate +an error describing the problem unless the ``QUIET`` argument is +specified. If ``REQUIRED`` is specified and the package is not found a +fatal error is generated and the configure step stops executing. If +``<package>_DIR`` has been set to a directory not containing a +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 ``<package>`` name +``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: + +``<package>_VERSION`` + full provided version string +``<package>_VERSION_MAJOR`` + major version if provided, else 0 +``<package>_VERSION_MINOR`` + minor version if provided, else 0 +``<package>_VERSION_PATCH`` + patch version if provided, else 0 +``<package>_VERSION_TWEAK`` + tweak version if provided, else 0 +``<package>_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 compatibiliy 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(<package> [major[.minor]] [EXACT] [REQUIRED|QUIET]) + +in order to find a package. Package maintainers providing CMake +package configuration files are encouraged to name and install them +such that the procedure outlined below will find them without +requiring use of additional options. + +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 OS X 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 (``<package>`` or names given by ``NAMES``). +Paths with ``lib/<arch>`` are enabled if the +:variable:`CMAKE_LIBRARY_ARCHITECTURE` variable is set. If ``PATH_SUFFIXES`` +is specified the suffixes are appended to each (W) or (U) directory entry +one-by-one. + +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 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 + +2. 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:: + + <package>_DIR + CMAKE_PREFIX_PATH + CMAKE_FRAMEWORK_PATH + CMAKE_APPBUNDLE_PATH + +3. Search paths specified by the ``HINTS`` option. These should be paths + computed by system introspection, such as a hint provided by the + location of another item already found. Hard-coded guesses should + be specified with the ``PATHS`` option. + +4. Search the standard system environment variables. This can be + skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is passed. Path entries + ending in ``/bin`` or ``/sbin`` are automatically converted to their + parent directories:: + + PATH + +5. 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. + +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 + CMAKE_SYSTEM_FRAMEWORK_PATH + CMAKE_SYSTEM_APPBUNDLE_PATH + +7. 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. + +8. Search paths specified by the ``PATHS`` option. These are typically + hard-coded guesses. + +.. |FIND_XXX| replace:: find_package +.. |FIND_ARGS_XXX| replace:: <package> +.. |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 ``<package>`` name which is searched for +``<package>_FIND_REQUIRED`` + true if ``REQUIRED`` option was given +``<package>_FIND_QUIETLY`` + true if ``QUIET`` option was given +``<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 +``<package>_FIND_VERSION_EXACT`` + true if ``EXACT`` option was given +``<package>_FIND_COMPONENTS`` + list of requested components +``<package>_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 +``<package>_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 000000000..76342d020 --- /dev/null +++ b/Help/command/find_path.rst @@ -0,0 +1,39 @@ +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`` + +.. |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 000000000..d3430c054 --- /dev/null +++ b/Help/command/find_program.rst @@ -0,0 +1,33 @@ +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`` + +.. |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 000000000..041e5a7e3 --- /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 000000000..c0f3679d9 --- /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". + +* When specifying two numbers, the range will have elements from the + first number to the second number. + +* The third optional number is the increment used to iterate from the + first number to the second number. + +:: + + 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 000000000..7ffdfee65 --- /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 000000000..497ab4eeb --- /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 000000000..e50abe0e9 --- /dev/null +++ b/Help/command/get_directory_property.rst @@ -0,0 +1,24 @@ +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. If the +property is not defined the empty-string is returned. The ``DIRECTORY`` +argument specifies another directory from which to retrieve the +property value. The specified directory must have already been +traversed by CMake. + +:: + + 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 000000000..14c8cf279 --- /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 slahes. 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 000000000..632ece65c --- /dev/null +++ b/Help/command/get_property.rst @@ -0,0 +1,61 @@ +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. 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 000000000..3e975c2f9 --- /dev/null +++ b/Help/command/get_source_file_property.rst @@ -0,0 +1,16 @@ +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 property is not found, ``VAR`` +will be set to "NOTFOUND". Use :command:`set_source_files_properties` +to set property values. Source file properties usually control how the +file is built. One property that is always there is :prop_sf:`LOCATION` + +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 000000000..2a72c3af7 --- /dev/null +++ b/Help/command/get_target_property.rst @@ -0,0 +1,18 @@ +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 property is not found, ``VAR`` will be set to +"NOTFOUND". Use :command:`set_target_properties` to set 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 000000000..e359f4b3d --- /dev/null +++ b/Help/command/get_test_property.rst @@ -0,0 +1,15 @@ +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 or property is not found, ``VAR`` will +be set to "NOTFOUND". 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 000000000..edd343de2 --- /dev/null +++ b/Help/command/if.rst @@ -0,0 +1,244 @@ +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]]]``). + +``if(<variable|string> VERSION_GREATER <variable|string>)`` + Component-wise integer version number comparison (version format is + ``major[.minor[.patch[.tweak]]]``). + +``if(<variable|string> VERSION_EQUAL <variable|string>)`` + Component-wise integer version number comparison (version format is + ``major[.minor[.patch[.tweak]]]``). + +``if(<variable|string> VERSION_LESS_EQUAL <variable|string>)`` + Component-wise integer version number comparison (version format is + ``major[.minor[.patch[.tweak]]]``). + +``if(<variable|string> VERSION_GREATER_EQUAL <variable|string>)`` + Component-wise integer version number comparison (version format is + ``major[.minor[.patch[.tweak]]]``). + +``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 000000000..eeca4c6e3 --- /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 000000000..f69493460 --- /dev/null +++ b/Help/command/include_directories.rst @@ -0,0 +1,35 @@ +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. diff --git a/Help/command/include_external_msproject.rst b/Help/command/include_external_msproject.rst new file mode 100644 index 000000000..335282a30 --- /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_regular_expression.rst b/Help/command/include_regular_expression.rst new file mode 100644 index 000000000..ab5a56325 --- /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 000000000..58438b763 --- /dev/null +++ b/Help/command/install.rst @@ -0,0 +1,380 @@ +install +------- + +.. only:: html + + .. contents:: + +Specify rules to run at install time. + +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.). + +``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. + +Installing 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>] + [OPTIONAL] [EXCLUDE_FROM_ALL] + [NAMELINK_ONLY|NAMELINK_SKIP] + ] [...] + [INCLUDES DESTINATION [<dir> ...]] + ) + +The ``TARGETS`` form specifies rules for installing targets from a +project. There are six kinds of target files that may be installed: +``ARCHIVE``, ``LIBRARY``, ``RUNTIME``, ``OBJECTS``, ``FRAMEWORK``, and +``BUNDLE``. Executables are treated as ``RUNTIME`` targets, except that +those marked with the ``MACOSX_BUNDLE`` property are treated as ``BUNDLE`` +targets on OS X. Static libraries are treated as ``ARCHIVE`` targets, +except that those marked with the ``FRAMEWORK`` property are treated +as ``FRAMEWORK`` targets on OS X. +Module libraries are always treated as ``LIBRARY`` targets. +For non-DLL platforms shared libraries are treated as ``LIBRARY`` +targets, except that those marked with the ``FRAMEWORK`` property are +treated as ``FRAMEWORK`` targets on OS X. For DLL platforms the DLL +part of a shared library is treated as a ``RUNTIME`` target and the +corresponding import library is treated as an ``ARCHIVE`` target. +All Windows-based systems including Cygwin are DLL platforms. Object +libraries are always treated as ``OBJECTS`` targets. +The ``ARCHIVE``, ``LIBRARY``, ``RUNTIME``, ``OBJECTS``, and ``FRAMEWORK`` +arguments change the type of target to which the subsequent properties +apply. If none is given the installation properties apply to all target +types. If only one is given then only targets of that type will be +installed (which can be used to install just a DLL or just an import +library). + +The ``PRIVATE_HEADER``, ``PUBLIC_HEADER``, and ``RESOURCE`` arguments +cause subsequent properties to be applied to installing a ``FRAMEWORK`` +shared library target's associated files on non-Apple platforms. Rules +defined by these arguments are ignored on Apple platforms because the +associated files are installed into the appropriate locations inside +the framework folder. See documentation of the +:prop_tgt:`PRIVATE_HEADER`, :prop_tgt:`PUBLIC_HEADER`, and +:prop_tgt:`RESOURCE` target properties for details. + +Either ``NAMELINK_ONLY`` or ``NAMELINK_SKIP`` may be specified as a +``LIBRARY`` option. On some platforms a versioned shared library +has a symbolic link such as:: + + lib<name>.so -> lib<name>.so.1 + +where ``lib<name>.so.1`` is the soname of the library and ``lib<name>.so`` +is a "namelink" allowing linkers to find the library when given +``-l<name>``. The ``NAMELINK_ONLY`` option causes installation of only the +namelink when a library target is installed. The ``NAMELINK_SKIP`` option +causes installation of library files other than the namelink when a +library target is installed. When neither option is given both +portions are installed. On platforms where versioned shared libraries +do not have namelinks or when a library is not versioned the +``NAMELINK_SKIP`` option installs the library and the ``NAMELINK_ONLY`` +option installs nothing. See the :prop_tgt:`VERSION` and +:prop_tgt:`SOVERSION` target properties for details on creating versioned +shared libraries. + +The ``INCLUDES DESTINATION`` specifies a list of directories +which will be added to the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` +target property of the ``<targets>`` when exported by the +:command:`install(EXPORT)` command. If a relative path is +specified, it is treated as relative to the ``$<INSTALL_PREFIX>``. +This is independent of the rest of the argument groups and does +not actually install anything. + +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``. + +The ``EXPORT`` option associates the installed target files with an +export called ``<export-name>``. It must appear before any ``RUNTIME``, +``LIBRARY``, ``ARCHIVE``, or ``OBJECTS`` options. To actually install the +export file itself, call ``install(EXPORT)``, documented below. + +Installing a target with the :prop_tgt:`EXCLUDE_FROM_ALL` target property +set to ``TRUE`` has undefined behavior. + +The install destination given to the target install ``DESTINATION`` may +use "generator expressions" with the syntax ``$<...>``. See the +:manual:`cmake-generator-expressions(7)` manual for available expressions. + +Installing Files +^^^^^^^^^^^^^^^^ + +:: + + 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 +^^^^^^^^^^^^^^^^^^^^^^ + +:: + + 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 +^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + 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. + +Installing Exports +^^^^^^^^^^^^^^^^^^ + +:: + + install(EXPORT <export-name> DESTINATION <dir> + [NAMESPACE <namespace>] [[FILE <name>.cmake]| + [EXPORT_ANDROID_MK <name>.mk]] + [PERMISSIONS permissions...] + [CONFIGURATIONS [Debug|Release|...]] + [EXPORT_LINK_INTERFACE_LIBRARIES] + [COMPONENT <component>] + [EXCLUDE_FROM_ALL]) + +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``. If a ``COMPONENT`` option is +specified that does not match that given to the targets associated with +``<export-name>`` the behavior is undefined. If a library target is +included in the export but a target to which it links is not included +the behavior is unspecified. + +In additon to cmake language files, the ``EXPORT_ANDROID_MK`` option maybe +used to specifiy an export to the android ndk build system. The Android +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>/lib/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. diff --git a/Help/command/install_files.rst b/Help/command/install_files.rst new file mode 100644 index 000000000..1850be6e1 --- /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 000000000..79aa486a3 --- /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 000000000..49ca69694 --- /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 000000000..5c64bc609 --- /dev/null +++ b/Help/command/link_directories.rst @@ -0,0 +1,19 @@ +link_directories +---------------- + +Specify directories in which the linker will look for libraries. + +:: + + link_directories(directory1 directory2 ...) + +Specify the paths in which the linker should search for libraries. +The command will apply only to targets created after it is called. +Relative paths given to this command are interpreted as relative to +the current source directory, see :policy:`CMP0015`. + +Note that this command is rarely necessary. Library locations +returned by :command:`find_package` and :command:`find_library` are +absolute paths. Pass these absolute library file paths directly to the +:command:`target_link_libraries` command. CMake will ensure the linker finds +them. diff --git a/Help/command/link_libraries.rst b/Help/command/link_libraries.rst new file mode 100644 index 000000000..fd5dc3723 --- /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 000000000..f6b75bc19 --- /dev/null +++ b/Help/command/list.rst @@ -0,0 +1,68 @@ +list +---- + +List operations. + +:: + + list(LENGTH <list> <output variable>) + list(GET <list> <element index> [<element index> ...] + <output variable>) + list(APPEND <list> [<element> ...]) + list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>) + list(FIND <list> <value> <output variable>) + list(INSERT <list> <element_index> <element> [<element> ...]) + list(REMOVE_ITEM <list> <value> [<value> ...]) + list(REMOVE_AT <list> <index> [<index> ...]) + list(REMOVE_DUPLICATES <list>) + list(REVERSE <list>) + list(SORT <list>) + +``LENGTH`` will return a given list's length. + +``GET`` will return list of elements specified by indices from the list. + +``APPEND`` will append elements to the list. + +``FILTER`` will include or remove items from the list that match the +mode's pattern. +In ``REGEX`` mode, items will be matched against the given regular expression. +For more information on regular expressions see also the :command:`string` +command. + +``FIND`` will return the index of the element specified in the list or -1 +if it wasn't found. + +``INSERT`` will insert elements to the list to the specified location. + +``REMOVE_AT`` and ``REMOVE_ITEM`` will remove items from the list. The +difference is that ``REMOVE_ITEM`` will remove the given items, while +``REMOVE_AT`` will remove the items at the given indices. + +``REMOVE_DUPLICATES`` will remove duplicated items in the list. + +``REVERSE`` reverses the contents of the list in-place. + +``SORT`` sorts the list in-place alphabetically. + +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. + +NOTES: A list in cmake is a ``;`` separated group of strings. To create a +list the set command can be used. For example, ``set(var a b c d e)`` +creates a list with ``a;b;c;d;e``, and ``set(var "a b c d e")`` creates a +string or a list with one item in it. (Note macro arguments are not +variables, and therefore cannot be used in LIST commands.) + +When specifying index values, if ``<element index>`` is 0 or greater, it +is indexed from the beginning of the list, with 0 representing the +first list element. If ``<element index>`` is -1 or lesser, it is indexed +from the end of the list, with -1 representing the last list element. +Be careful when counting with negative indices: they do not start from +0. -0 is equivalent to 0, the first list element. diff --git a/Help/command/load_cache.rst b/Help/command/load_cache.rst new file mode 100644 index 000000000..f1134472d --- /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 000000000..a1576e8b5 --- /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 000000000..6bee69c73 --- /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 000000000..27ecf5194 --- /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 000000000..c3f94fc48 --- /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 000000000..f99dc3db3 --- /dev/null +++ b/Help/command/math.rst @@ -0,0 +1,14 @@ +math +---- + +Mathematical expressions. + +:: + + math(EXPR <output-variable> <math-expression>) + +``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. diff --git a/Help/command/message.rst b/Help/command/message.rst new file mode 100644 index 000000000..04c62fdff --- /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 000000000..91cd0a778 --- /dev/null +++ b/Help/command/option.rst @@ -0,0 +1,15 @@ +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 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 000000000..5e1355763 --- /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 000000000..139f69c9b --- /dev/null +++ b/Help/command/project.rst @@ -0,0 +1,69 @@ +project +------- + +Set a name, version, and enable languages for the entire project. + +.. code-block:: cmake + + project(<PROJECT-NAME> [LANGUAGES] [<language-name>...]) + project(<PROJECT-NAME> + [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]] + [DESCRIPTION <project-description-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 optional ``DESCRIPTION`` is given, then additional :variable:`PROJECT_DESCRIPTION` +variable will be set to its argument. The argument must be a string with short +description of the project (only a few words). + +Optionally you can specify which languages your project supports. +Example languages are ``C``, ``CXX`` (i.e. C++), ``Fortran``, etc. +By default ``C`` and ``CXX`` are enabled if no language options are +given. Specify language ``NONE``, or use the ``LANGUAGES`` keyword +and list no languages, to skip enabling any languages. + +If a variable exists called :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, +the file pointed to by that variable will be included as the last step of the +project command. + +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``). + +.. 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 000000000..3843bf5e9 --- /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 000000000..f731ed9a8 --- /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 000000000..462827796 --- /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 000000000..ea189181c --- /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 000000000..e49fb3c8d --- /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 000000000..47982a503 --- /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 000000000..b24ebefeb --- /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 000000000..e485fce0a --- /dev/null +++ b/Help/command/set_directory_properties.rst @@ -0,0 +1,12 @@ +set_directory_properties +------------------------ + +Set a property of the directory. + +:: + + set_directory_properties(PROPERTIES prop1 value1 prop2 value2) + +Set a property for the current directory and subdirectories. See +:ref:`Directory Properties` for the list of properties known +to CMake. diff --git a/Help/command/set_property.rst b/Help/command/set_property.rst new file mode 100644 index 000000000..5ed788e4a --- /dev/null +++ b/Help/command/set_property.rst @@ -0,0 +1,69 @@ +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 append to any +existing property value as string, i.e. it results in a longer string +and not a list of strings. + +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 000000000..b4904e8d0 --- /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 000000000..b894eace3 --- /dev/null +++ b/Help/command/set_target_properties.rst @@ -0,0 +1,18 @@ +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 a target. The syntax for the command is to list all +the files you want to change, and then provide the values you want to +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 :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 000000000..3efb1653e --- /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 000000000..e17c1ee68 --- /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 000000000..938ca40f2 --- /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 000000000..4f0c45c29 --- /dev/null +++ b/Help/command/string.rst @@ -0,0 +1,367 @@ +string +------ + +.. only:: html + + .. contents:: + +String operations. + +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``. + +Manipulation +^^^^^^^^^^^^ + +APPEND +"""""" + +:: + + string(APPEND <string variable> [<input>...]) + +Append 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. + +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 +^^^^^^^^^^ + +:: + + 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 +^^^^^^^ + +:: + + 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. + +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). + %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). + %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. + + +:: + + string(MAKE_C_IDENTIFIER <input string> <output variable>) + +Write a string which can be used as an identifier in C. + +.. note:: + + If the ``SOURCE_DATE_EPOCH`` environment variable is set, + its value will be used instead of the current time. + See https://reproducible-builds.org/specs/source-date-epoch/ for details. + +UUID +"""" + +:: + + string(UUID <output variable> NAMESPACE <namespace> NAME <name> + TYPE <MD5|SHA1> [UPPER]) + +Create a univerally 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 000000000..5676c8f40 --- /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 000000000..43b87d4d7 --- /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 000000000..8bd323375 --- /dev/null +++ b/Help/command/target_compile_definitions.rst @@ -0,0 +1,28 @@ +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:`Imported Target <Imported Targets>`. + +The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to +specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC`` +items will populate the :prop_tgt:`COMPILE_DEFINITIONS` property of +``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the +:prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` property of ``<target>``. The +following arguments specify compile definitions. Repeated calls for the +same ``<target>`` append items in the order called. + +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. diff --git a/Help/command/target_compile_features.rst b/Help/command/target_compile_features.rst new file mode 100644 index 000000000..b66a4ec16 --- /dev/null +++ b/Help/command/target_compile_features.rst @@ -0,0 +1,32 @@ +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>``. Repeated +calls for the same ``<target>`` append items. + +The named ``<target>`` must have been created by a command such as +:command:`add_executable` or :command:`add_library` and must not be +an ``IMPORTED`` target. + +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 000000000..73e01e7f8 --- /dev/null +++ b/Help/command/target_compile_options.rst @@ -0,0 +1,37 @@ +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:`IMPORTED Target <Imported 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_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>``. 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. diff --git a/Help/command/target_include_directories.rst b/Help/command/target_include_directories.rst new file mode 100644 index 000000000..30ec2cb27 --- /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 +:prop_tgt:`IMPORTED` target. + +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>``. 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_libraries.rst b/Help/command/target_link_libraries.rst new file mode 100644 index 000000000..30d69f266 --- /dev/null +++ b/Help/command/target_link_libraries.rst @@ -0,0 +1,215 @@ +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 in the current directory by +a command such as :command:`add_executable` or :command:`add_library`. +Repeated calls for the same ``<target>`` append items in the order called. +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_FLAGS` target property 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``. + +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_sources.rst b/Help/command/target_sources.rst new file mode 100644 index 000000000..d6f148d23 --- /dev/null +++ b/Help/command/target_sources.rst @@ -0,0 +1,28 @@ +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. The +named ``<target>`` must have been created by a command such as +:command:`add_executable` or :command:`add_library` and must not be an +:ref:`IMPORTED Target <Imported Targets>`. + +The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to +specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC`` +items will populate the :prop_tgt:`SOURCES` property of +``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the +:prop_tgt:`INTERFACE_SOURCES` property of ``<target>``. The +following arguments specify sources. Repeated calls for the same +``<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. diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst new file mode 100644 index 000000000..66ea3d7f2 --- /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 000000000..e3bd57d50 --- /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 000000000..a1fc95cc6 --- /dev/null +++ b/Help/command/unset.rst @@ -0,0 +1,25 @@ +unset +----- + +Unset a variable, cache variable, or environment variable. + +:: + + unset(<variable> [CACHE | PARENT_SCOPE]) + +Removes the specified variable causing it to become undefined. If +``CACHE`` is present then the variable is removed from the cache instead +of the current scope. + +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 000000000..6f4d7aca6 --- /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 000000000..ee34492c3 --- /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 000000000..9cf9f3ffd --- /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 000000000..a2df058eb --- /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 000000000..7509da309 --- /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 000000000..40e755763 --- /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/dev/README.rst b/Help/dev/README.rst new file mode 100644 index 000000000..ce62abc4b --- /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 000000000..78c06df65 --- /dev/null +++ b/Help/dev/maint.rst @@ -0,0 +1,171 @@ +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: + +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 000000000..9450bf081 --- /dev/null +++ b/Help/dev/review.rst @@ -0,0 +1,350 @@ +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. + +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: + +* ``Topic-rename: <topic>``: substitute ``<topic>`` for the name of + the MR topic branch in the constructed merge commit message. + The ``-t`` option overrides this. + +.. _`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 000000000..7e4499559 --- /dev/null +++ b/Help/dev/source.rst @@ -0,0 +1,60 @@ +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 **3.8** 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 supports compiling as C++98 in addition to C++11 and C++14. +In order to support building on older toolchains some constructs +need to be handled with care: + +* Use ``CM_AUTO_PTR`` instead of ``std::auto_ptr``. + + The ``std::auto_ptr`` template is deprecated in C++11. We want to use it + so we can build on C++98 compilers but we do not want to turn off compiler + warnings about deprecated interfaces in general. Use the ``CM_AUTO_PTR`` + macro instead. + +* Use ``CM_EQ_DELETE;`` instead of ``= delete;``. + + Defining functions as *deleted* is not supported in C++98. Using + ``CM_EQ_DELETE`` will delete the functions if the compiler supports it and + give them no implementation otherwise. Calling such a function will lead + to compiler errors if the compiler supports *deleted* functions and linker + errors otherwise. + +* 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. diff --git a/Help/dev/testing.rst b/Help/dev/testing.rst new file mode 100644 index 000000000..731930c8f --- /dev/null +++ b/Help/dev/testing.rst @@ -0,0 +1,42 @@ +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, continous, 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 + +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/generator/Borland Makefiles.rst b/Help/generator/Borland Makefiles.rst new file mode 100644 index 000000000..c00d00a86 --- /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 000000000..d03cb0ce6 --- /dev/null +++ b/Help/generator/CodeBlocks.rst @@ -0,0 +1,28 @@ +CodeBlocks +---------- + +Generates CodeBlocks project files. + +Project files for CodeBlocks will be created in the top directory and +in every subdirectory which features a CMakeLists.txt file containing +a PROJECT() call. Additionally a hierarchy of makefiles is generated +into the build tree. The appropriate make program can build the +project through the default make target. A "make install" target is +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 000000000..3e60aa6d6 --- /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 000000000..eb68bf094 --- /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 000000000..4d3169026 --- /dev/null +++ b/Help/generator/Green Hills MULTI.rst @@ -0,0 +1,16 @@ +Green Hills MULTI +----------------- + +Generates Green Hills MULTI project files (experimental, work-in-progress). + +Customizations are available through the following cache variables: + +* ``GHS_BSP_NAME`` +* ``GHS_CUSTOMIZATION`` +* ``GHS_GPJ_MACROS`` +* ``GHS_OS_DIR`` + +.. 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/KDevelop3.rst b/Help/generator/KDevelop3.rst new file mode 100644 index 000000000..eaa218bc8 --- /dev/null +++ b/Help/generator/KDevelop3.rst @@ -0,0 +1,25 @@ +KDevelop3 +--------- + +Generates KDevelop 3 project files. + +Project files for KDevelop 3 will be created in the top directory and +in every subdirectory which features a CMakeLists.txt file containing +a PROJECT() call. If you change the settings using KDevelop cmake +will try its best to keep your changes when regenerating the project +files. Additionally a hierarchy of UNIX makefiles is generated into +the build tree. Any standard UNIX-style make program can build the +project through the default make target. A "make install" target is +also provided. + +This "extra" generator may be specified as: + +``KDevelop3 - Unix Makefiles`` + Generate with :generator:`Unix Makefiles`. + +``KDevelop3`` + Generate with :generator:`Unix Makefiles`. + + For historical reasons this extra generator may be specified + directly as the main generator and it will be used as the + extra generator with :generator:`Unix Makefiles` automatically. diff --git a/Help/generator/Kate.rst b/Help/generator/Kate.rst new file mode 100644 index 000000000..9b61a93b3 --- /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 000000000..f7cfa4461 --- /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 000000000..9fe5fe3e5 --- /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 000000000..3a8744c1e --- /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 000000000..89f2479b7 --- /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 000000000..3bbd9dcbe --- /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 000000000..0597a9528 --- /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 000000000..97d74a853 --- /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 000000000..5d13e7741 --- /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 000000000..04eef1039 --- /dev/null +++ b/Help/generator/Visual Studio 10 2010.rst @@ -0,0 +1,26 @@ +Visual Studio 10 2010 +--------------------- + +Generates Visual Studio 10 (VS 2010) project files. + +The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set +to specify a target platform name (architecture). + +For compatibility with CMake versions prior to 3.1, one may specify +a target platform name optionally at the end of this generator name: + +``Visual Studio 10 2010 Win64`` + Specify target platform ``x64``. + +``Visual Studio 10 2010 IA64`` + Specify target platform ``Itanium``. + +For compatibility with CMake versions prior to 3.0, one may specify this +generator using the name ``Visual Studio 10`` without the year component. + +Toolset Selection +^^^^^^^^^^^^^^^^^ + +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 000000000..347a153b9 --- /dev/null +++ b/Help/generator/Visual Studio 11 2012.rst @@ -0,0 +1,29 @@ +Visual Studio 11 2012 +--------------------- + +Generates Visual Studio 11 (VS 2012) project files. + +The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set +to specify a target platform name (architecture). + +For compatibility with CMake versions prior to 3.1, one may specify +a target platform name optionally at the end of this generator name: + +``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. + +For compatibility with CMake versions prior to 3.0, one may specify this +generator using the name "Visual Studio 11" without the year component. + +Toolset Selection +^^^^^^^^^^^^^^^^^ + +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 000000000..5071b20ce --- /dev/null +++ b/Help/generator/Visual Studio 12 2013.rst @@ -0,0 +1,28 @@ +Visual Studio 12 2013 +--------------------- + +Generates Visual Studio 12 (VS 2013) project files. + +The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set +to specify a target platform name (architecture). + +For compatibility with CMake versions prior to 3.1, one may specify +a target platform name optionally at the end of this generator name: + +``Visual Studio 12 2013 Win64`` + Specify target platform ``x64``. + +``Visual Studio 12 2013 ARM`` + Specify target platform ``ARM``. + +For compatibility with CMake versions prior to 3.0, one may specify this +generator using the name "Visual Studio 12" without the year component. + +Toolset Selection +^^^^^^^^^^^^^^^^^ + +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 000000000..64254b579 --- /dev/null +++ b/Help/generator/Visual Studio 14 2015.rst @@ -0,0 +1,25 @@ +Visual Studio 14 2015 +--------------------- + +Generates Visual Studio 14 (VS 2015) project files. + +The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set +to specify a target platform name (architecture). + +For compatibility with CMake versions prior to 3.1, one may specify +a target platform name optionally at the end of this generator name: + +``Visual Studio 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 000000000..2ac044968 --- /dev/null +++ b/Help/generator/Visual Studio 15 2017.rst @@ -0,0 +1,37 @@ +Visual Studio 15 2017 +--------------------- + +Generates Visual Studio 15 (VS 2017) project files. + +The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set +to specify a target platform name (architecture). + +For compatibility with CMake versions prior to 3.1, one may specify +a target platform name optionally at the end of this generator name: + +``Visual Studio 15 2017 Win64`` + Specify target platform ``x64``. + +``Visual Studio 15 2017 ARM`` + Specify target platform ``ARM``. + +Instance Selection +^^^^^^^^^^^^^^^^^^ + +VS 2017 supports multiple installations on the same machine. +CMake queries the Visual Studio Installer to locate VS instances. +If more than one instance is installed we do not define which one +is chosen by default. If the ``VS150COMNTOOLS`` environment variable +is set and points to the ``Common7/Tools`` directory within one of +the instances, that instance will be used. The environment variable +must remain consistently set whenever CMake is re-run within a given +build tree. + +Toolset Selection +^^^^^^^^^^^^^^^^^ + +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 000000000..2dd07e02f --- /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 000000000..d4c78693f --- /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 000000000..54d29df26 --- /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 000000000..acbbf01ae --- /dev/null +++ b/Help/generator/Visual Studio 8 2005.rst @@ -0,0 +1,23 @@ +Visual Studio 8 2005 +-------------------- + +Deprecated. Generates Visual Studio 8 2005 project files. + +.. note:: + This generator is deprecated and will be removed in a future version + of CMake. It will still be possible to build with VS 8 2005 tools + using the :generator:`Visual Studio 10 2010` (or above) generator + with :variable:`CMAKE_GENERATOR_TOOLSET` set to ``v80``, or by + using the :generator:`NMake Makefiles` generator. + +The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set +to specify a target platform name. + +For compatibility with CMake versions prior to 3.1, one may specify +a target platform name optionally at the end of this generator name: + +``Visual Studio 8 2005 Win64`` + Specify target platform ``x64``. + +``Visual Studio 8 2005 <WinCE-SDK>`` + Specify target platform matching a Windows CE SDK name. diff --git a/Help/generator/Visual Studio 9 2008.rst b/Help/generator/Visual Studio 9 2008.rst new file mode 100644 index 000000000..40471b92e --- /dev/null +++ b/Help/generator/Visual Studio 9 2008.rst @@ -0,0 +1,19 @@ +Visual Studio 9 2008 +-------------------- + +Generates Visual Studio 9 2008 project files. + +The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set +to specify a target platform name. + +For compatibility with CMake versions prior to 3.1, one may specify +a target platform name optionally at the end of this generator name: + +``Visual Studio 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 000000000..09bdc3d9f --- /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 000000000..968c26a70 --- /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 000000000..6797d0e2b --- /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 000000000..a54d7280d --- /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 000000000..46e84ac22 --- /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 000000000..97cd1073b --- /dev/null +++ b/Help/index.rst @@ -0,0 +1,60 @@ +.. 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-generator-expressions.7 + /manual/cmake-generators.7 + /manual/cmake-language.7 + /manual/cmake-server.7 + /manual/cmake-modules.7 + /manual/cmake-packages.7 + /manual/cmake-policies.7 + /manual/cmake-properties.7 + /manual/cmake-qt.7 + /manual/cmake-toolchains.7 + /manual/cmake-variables.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 000000000..3993ff83d --- /dev/null +++ b/Help/manual/LINKS.txt @@ -0,0 +1,25 @@ +The following resources are available to get help using CMake: + +Home Page + https://cmake.org + + The primary starting point for learning about CMake. + +Frequently Asked Questions + https://cmake.org/Wiki/CMake_FAQ + + A Wiki is provided containing answers to frequently asked questions. + +Online Documentation + https://cmake.org/documentation + + Links to available documentation 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 000000000..e8b87c923 --- /dev/null +++ b/Help/manual/OPTIONS_BUILD.txt @@ -0,0 +1,112 @@ +``-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 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 000000000..feeca7dc3 --- /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 000000000..a5fe19168 --- /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 000000000..95f5b8735 --- /dev/null +++ b/Help/manual/cmake-buildsystem.7.rst @@ -0,0 +1,997 @@ +.. 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 OS X 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 is also not linked to. It defines a non-archival +collection of object files resulting from compiling the given source files. +The object files collection can be used as source inputs to other targets: + +.. 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) + +``OBJECT`` libraries may not be used in the right hand side of +:command:`target_link_libraries`. They also may not be used as the ``TARGET`` +in a use of the :command:`add_custom_command(TARGET)` command signature. They +may be installed, and will be exported as an INTERFACE library. + +Although object libraries may not be named directly in calls to +the :command:`target_link_libraries` command, they can be "linked" +indirectly by using an :ref:`Interface Library <Interface Libraries>` +whose :prop_tgt:`INTERFACE_SOURCES` target property is set to name +``$<TARGET_OBJECTS:objlib>``. + +Although object libraries may not be used as the ``TARGET`` +in a use of the :command:`add_custom_command(TARGET)` command signature, +the list of objects can be used by :command:`add_custom_command(OUTPUT)` or +:command:`file(GENERATE)` by using ``$<TARGET_OBJECTS:objlib>``. + + +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 ``archive``, 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 with the :prop_tgt:`NO_SYSTEM_FROM_IMPORTED` target property. + +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 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_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. It is not possible to use an :prop_tgt:`IMPORTED` target in the +left-hand-side of the :command:`target_compile_definitions`, +:command:`target_include_directories`, :command:`target_compile_options` or +:command:`target_link_libraries` commands, as that would be an attempt to +modify it. :prop_tgt:`IMPORTED` targets are designed to be used only in the +right-hand-side of those commands. + +: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`` +* ``NO_SYSTEM_FROM_IMPORTED`` +* 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 000000000..611c989a0 --- /dev/null +++ b/Help/manual/cmake-commands.7.rst @@ -0,0 +1,164 @@ +.. 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/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_options + /command/add_custom_command + /command/add_custom_target + /command/add_definitions + /command/add_dependencies + /command/add_executable + /command/add_library + /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_libraries + /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 000000000..012439500 --- /dev/null +++ b/Help/manual/cmake-compile-features.7.rst @@ -0,0 +1,369 @@ +.. 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 6.2. +* ``Clang``: Clang compiler versions 2.9 through 3.4. +* ``GNU``: GNU compiler versions 4.4 through 5.0. +* ``MSVC``: Microsoft Visual Studio versions 2010 through 2017. +* ``SunPro``: Oracle SolarisStudio versions 12.4 through 12.5. +* ``Intel``: Intel compiler versions 12.1 through 17.0. + +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 5.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++. + +CMake is currently aware of the :prop_tgt:`CUDA standards <CUDA_STANDARD>` +from the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the +versions specified for each: + +* ``NVIDIA``: NVIDIA nvcc compiler 7.5 though 8.0. diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst new file mode 100644 index 000000000..cd509ac20 --- /dev/null +++ b/Help/manual/cmake-developer.7.rst @@ -0,0 +1,965 @@ +.. 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<package>.cmake`` file to be loaded +by the :command:`find_package` command when invoked for ``<package>``. + +The primary task of a find module is to determine whether a package +exists on the system, set the ``<package>_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. + + + +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 that 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-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst new file mode 100644 index 000000000..bddb17477 --- /dev/null +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -0,0 +1,297 @@ +.. 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`` +``$<CONFIG:cfg>`` + ``1`` if config is ``cfg``, else ``0``. This is a case-insensitive comparison. + The mapping in :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` is also considered by + this expression when it is evaluated on a property on an :prop_tgt:`IMPORTED` + target. +``$<PLATFORM_ID:comp>`` + ``1`` if the CMake-id of the platform matches ``comp``, otherwise ``0``. +``$<C_COMPILER_ID:comp>`` + ``1`` if the CMake-id of the C compiler matches ``comp``, otherwise ``0``. +``$<CXX_COMPILER_ID:comp>`` + ``1`` if the CMake-id of the CXX compiler matches ``comp``, otherwise ``0``. +``$<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``. +``$<CXX_COMPILER_VERSION:ver>`` + ``1`` if the version of the CXX compiler matches ``ver``, otherwise ``0``. +``$<TARGET_POLICY:pol>`` + ``1`` if the policy ``pol`` was NEW when the 'head' target was created, + else ``0``. If the policy was not set, the warning message for the policy + 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 used to specify compile options for + source files of a particular language in a target. For example, to specify + the use of the ``-fno-exceptions`` compile option (compiler id checks + elided): + + .. code-block:: cmake + + add_executable(myapp main.cpp foo.c bar.cpp) + target_compile_options(myapp + PRIVATE $<$<COMPILE_LANGUAGE:CXX>:-fno-exceptions> + ) + + This generator expression has limited use because it is not possible to + use it with the Visual Studio generators. Portable buildsystems would + not use this expression, and would create separate libraries for each + source file language instead: + + .. 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) + + The ``Makefile`` and ``Ninja`` based generators can also use this + expression to specify compile-language specific compile definitions + and include directories: + + .. code-block:: cmake + + add_executable(myapp main.cpp foo.c bar.cpp) + target_compile_definitions(myapp + PRIVATE $<$<COMPILE_LANGUAGE:CXX>:COMPILING_CXX> + ) + target_include_directories(myapp + PRIVATE $<$<COMPILE_LANGUAGE:CXX>:/opt/foo/cxx_headers> + ) + +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. +``$<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. +``$<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. diff --git a/Help/manual/cmake-generators.7.rst b/Help/manual/cmake-generators.7.rst new file mode 100644 index 000000000..a37c65b39 --- /dev/null +++ b/Help/manual/cmake-generators.7.rst @@ -0,0 +1,113 @@ +.. 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/KDevelop3 + /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 000000000..032b51fda --- /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 000000000..27b5d30b4 --- /dev/null +++ b/Help/manual/cmake-language.7.rst @@ -0,0 +1,578 @@ +.. 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: '[' '='{len} '[' + bracket_content: <any text not containing a `bracket_close` + : of the same {len} as the `bracket_open`> + bracket_close: ']' '='{len} ']' + +.. raw:: latex + + \end{small} + +An opening bracket of length *len >= 0* is written ``[`` followed +by *len* ``=`` followed by ``[`` and the corresponding closing +bracket is written ``]`` followed by *len* ``=`` followed by ``]``. +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. + + 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. + +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, 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 :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 000000000..4a03b7a80 --- /dev/null +++ b/Help/manual/cmake-modules.7.rst @@ -0,0 +1,255 @@ +.. 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/CPackArchive + /module/CPackBundle + /module/CPackComponent + /module/CPackCygwin + /module/CPackDeb + /module/CPackDMG + /module/CPackIFW + /module/CPackIFWConfigureFile + /module/CPackNSIS + /module/CPackPackageMaker + /module/CPackProductBuild + /module/CPackRPM + /module/CPack + /module/CPackWIX + /module/CSharpUtilities + /module/CTest + /module/CTestCoverageCollectGCOV + /module/CTestScriptMode + /module/CTestUseLaunchers + /module/Dart + /module/DeployQt4 + /module/Documentation + /module/ExternalData + /module/ExternalProject + /module/FeatureSummary + /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/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/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/FindPerlLibs + /module/FindPerl + /module/FindPHP4 + /module/FindPhysFS + /module/FindPike + /module/FindPkgConfig + /module/FindPNG + /module/FindPostgreSQL + /module/FindProducer + /module/FindProtobuf + /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 diff --git a/Help/manual/cmake-packages.7.rst b/Help/manual/cmake-packages.7.rst new file mode 100644 index 000000000..c9442bc19 --- /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 ``<Package>_FOUND`` +variable is set to true or false, depending on whether the package was +found. The ``<Package>_DIR`` cache variable is set to the location of the +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 ``<Package>_FOUND`` +variable is not automatically set by the :command:`find_package` command. It +can still be expected to be set by convention however and should be set by +the author of the Find-module. Similarly there is no ``<Package>_DIR`` variable, +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 <package> name + +``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: + +``<package>_VERSION`` + Full provided version string + +``<package>_VERSION_MAJOR`` + Major version if provided, else 0 + +``<package>_VERSION_MINOR`` + Minor version if provided, else 0 + +``<package>_VERSION_PATCH`` + Patch version if provided, else 0 + +``<package>_VERSION_TWEAK`` + Tweak version if provided, else 0 + +``<package>_VERSION_COUNT`` + Number of version components, 0 to 4 + +The variables report the version of the package that was actually found. +The ``<package>`` part of their name matches the argument given to the +: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 ``<Package>_VERSION``, ``<Package>_VERSION_MAJOR``, +``<Package>_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 ``<Package>_FIND_COMPONENTS`` variable. If a particular +component is non-optional, then the ``<Package>_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`_ (``<package>Config.cmake``) and optionally a +`Package Version File`_ (``<package>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 ``<package>`` may appear under registry key:: + + HKEY_CURRENT_USER\Software\Kitware\CMake\Packages\<package> + +as a ``REG_SZ`` value, with arbitrary name, that specifies the directory +containing the package configuration file. + +On UNIX platforms the user package registry is stored in the user home +directory under ``~/.cmake/packages``. A ``<package>`` may appear under +the directory:: + + ~/.cmake/packages/<package> + +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 ``<package>`` may appear under +registry key:: + + HKEY_LOCAL_MACHINE\Software\Kitware\CMake\Packages\<package> + +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 000000000..7b858176f --- /dev/null +++ b/Help/manual/cmake-policies.7.rst @@ -0,0 +1,192 @@ +.. 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.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 000000000..ec25596f3 --- /dev/null +++ b/Help/manual/cmake-properties.7.rst @@ -0,0 +1,456 @@ +.. 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/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/LINK_DIRECTORIES + /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/TEST_INCLUDE_FILE + /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_TARGET_DEPENDS + /prop_tgt/AUTOMOC_DEPEND_FILTERS + /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/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/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/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_CONFIGURATIONS + /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 + /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_LIBRARIES + /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_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_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_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/SUFFIX + /prop_tgt/TYPE + /prop_tgt/VERSION + /prop_tgt/VISIBILITY_INLINES_HIDDEN + /prop_tgt/VS_CONFIGURATION_TYPE + /prop_tgt/VS_DEBUGGER_WORKING_DIRECTORY + /prop_tgt/VS_DESKTOP_EXTENSIONS_VERSION + /prop_tgt/VS_DOTNET_REFERENCE_refname + /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/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/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/EXTERNAL_OBJECT + /prop_sf/Fortran_FORMAT + /prop_sf/GENERATED + /prop_sf/HEADER_FILE_ONLY + /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_ENTRYPOINT + /prop_sf/VS_SHADER_FLAGS + /prop_sf/VS_SHADER_MODEL + /prop_sf/VS_SHADER_TYPE + /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 + + +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 000000000..b7f16b9ea --- /dev/null +++ b/Help/manual/cmake-qt.7.rst @@ -0,0 +1,223 @@ +.. 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 ``Q_OBJECT`` or ``Q_GADGET`` macro is found in a header file, ``moc`` +will be run on the file. The result will be put into a file named according +to ``moc_<basename>.cpp``. If the macro is found in a C++ implementation +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. +* 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 ``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. +* 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`. + +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 000000000..9520cc140 --- /dev/null +++ b/Help/manual/cmake-server.7.rst @@ -0,0 +1,672 @@ +.. 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). + +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 progess. + +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. + +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. + +Each protocol version may request additional attributes to be present. + +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) + +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. + + +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. +"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. +"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: + +"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. +"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 "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 can be used once a project is configured and 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 000000000..8554e87f9 --- /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 000000000..1a2726dd3 --- /dev/null +++ b/Help/manual/cmake-variables.7.rst @@ -0,0 +1,520 @@ +.. 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_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_DL_LIBS + /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_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_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_PARENT_LIST_FILE + /variable/CMAKE_PATCH_VERSION + /variable/CMAKE_PROJECT_DESCRIPTION + /variable/CMAKE_PROJECT_NAME + /variable/CMAKE_RANLIB + /variable/CMAKE_ROOT + /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_WINDOWS_TARGET_PLATFORM_VERSION + /variable/CMAKE_XCODE_GENERATE_SCHEME + /variable/CMAKE_XCODE_PLATFORM_TOOLSET + /variable/PROJECT-NAME_BINARY_DIR + /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_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_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_MESSAGE + /variable/CMAKE_INSTALL_PREFIX + /variable/CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT + /variable/CMAKE_LIBRARY_PATH + /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_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 + +Variables that Describe the System +================================== + +.. toctree:: + :maxdepth: 1 + + /variable/ANDROID + /variable/APPLE + /variable/BORLAND + /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_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_AUTOMOC + /variable/CMAKE_AUTOMOC_DEPEND_FILTERS + /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_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_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_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_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_INCLUDE_INSTALL_TO_DEFAULT_BUILD + /variable/CMAKE_VS_INCLUDE_PACKAGE_TO_DEFAULT_BUILD + /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_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_EXTERNAL_TOOLCHAIN + /variable/CMAKE_LANG_COMPILER_ID + /variable/CMAKE_LANG_COMPILER_LOADED + /variable/CMAKE_LANG_COMPILER_TARGET + /variable/CMAKE_LANG_COMPILER_VERSION + /variable/CMAKE_LANG_COMPILE_OBJECT + /variable/CMAKE_LANG_CREATE_SHARED_LIBRARY + /variable/CMAKE_LANG_CREATE_SHARED_MODULE + /variable/CMAKE_LANG_CREATE_STATIC_LIBRARY + /variable/CMAKE_LANG_FLAGS + /variable/CMAKE_LANG_FLAGS_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_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_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_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_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_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 000000000..ba925e8ec --- /dev/null +++ b/Help/manual/cmake.1.rst @@ -0,0 +1,363 @@ +.. cmake-manual-description: CMake Command-Line Reference + +cmake(1) +******** + +Synopsis +======== + +.. parsed-literal:: + + cmake [<options>] (<path-to-source> | <path-to-existing-build>) + cmake [(-D <var>=<value>)...] -P <cmake-script-file> + cmake --build <dir> [<options>...] [-- <build-tool-options>...] + cmake -E <command> [<options>...] + cmake --find-package <options>... + +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`_. + +``-N`` + View mode only. + + Only load the cache. Do not actually run configure and generate + steps. + +``-P <file>`` + Process script mode. + + Process the given cmake file as a script written in the CMake + language. No configure or generate step is performed and the cache + is not modified. If variables are defined using -D, this must be + done before the -P argument. + +``--find-package`` + See `Find-Package Tool Mode`_. + +``--graphviz=[file]`` + Generate graphviz of dependencies, see CMakeGraphVizOptions.cmake for more. + + Generate a graphviz input file that will contain all the library and + executable dependencies in the project. See the documentation for + CMakeGraphVizOptions.cmake for more details. + +``--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 +=============== + +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. + +``--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 + +``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 return 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. + +UNIX-specific Command-Line Tools +-------------------------------- + +The following ``cmake -E`` commands are available only on UNIX: + +``create_symlink <old> <new>`` + Create a symbolic link ``<new>`` naming ``<old>``. + +.. note:: + Path to where ``<new>`` symbolic link will be created has to exist beforehand. + +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.1.rst b/Help/manual/cpack.1.rst new file mode 100644 index 000000000..4f9f28d4e --- /dev/null +++ b/Help/manual/cpack.1.rst @@ -0,0 +1,97 @@ +.. cmake-manual-description: CPack Command-Line Reference + +cpack(1) +******** + +Synopsis +======== + +.. parsed-literal:: + + cpack -G <generator> [<options>] + +Description +=========== + +The "cpack" executable is the CMake packaging program. +CMake-generated build trees created for projects that use the +INSTALL_* commands have packaging support. This program will generate +the package. + +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 +======= + +``-G <generator>`` + Use the specified generator to generate package. + + CPack may support multiple native packaging systems on certain + platforms. A generator is responsible for generating input files + for particular system and invoking that systems. Possible generator + names are specified in the Generators section. + +``-C <Configuration>`` + Specify the project configuration + + This option specifies the configuration that the project was build + with, for example 'Debug', 'Release'. + +``-D <var>=<value>`` + Set a CPack variable. + + Set a variable that can be used by the generator. + +``--config <config file>`` + Specify the config file. + + Specify the config file to use to create the package. By default + CPackConfig.cmake in the current directory will be used. + +``--verbose,-V`` + enable verbose output + + Run cpack with verbose output. + +``--debug`` + enable debug output (for CPack developers) + + Run cpack with debug output (for CPack developers). + +``-P <package name>`` + override/define CPACK_PACKAGE_NAME + + If the package name is not specified on cpack command line + thenCPack.cmake defines it as CMAKE_PROJECT_NAME + +``-R <package version>`` + override/define CPACK_PACKAGE_VERSION + + If version is not specified on cpack command line thenCPack.cmake + defines it from CPACK_PACKAGE_VERSION_[MAJOR|MINOR|PATCH]look into + CPack.cmake for detail + +``-B <package directory>`` + override/define CPACK_PACKAGE_DIRECTORY + + The directory where CPack will be doing its packaging work.The + resulting package will be found there. Inside this directoryCPack + creates '_CPack_Packages' sub-directory which is theCPack temporary + directory. + +``--vendor <vendor name>`` + override/define CPACK_PACKAGE_VENDOR + + If vendor is not specified on cpack command line (or inside + CMakeLists.txt) thenCPack.cmake defines it with a default value + +.. 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 000000000..a89c4e9bb --- /dev/null +++ b/Help/manual/ctest.1.rst @@ -0,0 +1,1049 @@ +.. cmake-manual-description: CTest Command-Line Reference + +ctest(1) +******** + +Synopsis +======== + +.. parsed-literal:: + + ctest [<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``. + +``--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. + +``-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``. + +``-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``. + +``--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. + +``-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. + +``-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. + +``-A <file>, --add-notes <file>`` + Add a notes file with submission. + + This option tells ctest to include a notes file when submitting + dashboard. + +``-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. + +``--build-and-test <path-to-source> <path-to-build>`` + Configure, build and run a test. + + This option tells ctest to configure (i.e. run cmake on), build, + and or execute a test. The configure and test steps are optional. + The arguments to this command line are the source and binary + directories. + The ``--build-generator`` option *must* be provided to use + ``--build-and-test``. If ``--test-command`` is specified then that will be + run after the build is complete. Other options that affect this + mode are ``--build-target``, ``--build-nocmake``, ``--build-run-dir``, + ``--build-two-config``, ``--build-exe-dir``, + ``--build-project``, ``--build-noclean`` and ``--build-options``. + +``--build-target`` + Specify a specific target to build. + + This option goes with the ``--build-and-test`` option, if left out the + ``all`` target is built. + +``--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`` + Add extra options to the build step. + + This option must be the last option with the exception of + ``--test-command`` + +``--test-command`` + The test to run with the ``--build-and-test`` option. + +``--test-output-size-passed <size>`` + Limit the output for passed tests to ``<size>`` bytes. + +``--test-output-size-failed <size>`` + Limit the output for failed tests to ``<size>`` bytes. + +``--test-timeout`` + The time limit in seconds, internal use only. + +``--tomorrow-tag`` + Nightly or experimental starts with next day tag. + + This is useful if the build will not finish in one day. + +``--ctest-config`` + The configuration file used to initialize CTest state when submitting dashboards. + + This option tells CTest to use different initialization file instead + of CTestConfiguration.tcl. This way multiple initialization files + can be used for example to submit to multiple dashboards. + +``--overwrite`` + Overwrite CTest configuration option. + + By default ctest uses configuration options from configuration file. + This option will overwrite the configuration option. + +``--extra-submit <file>[;<file>]`` + Submit extra files to the dashboard. + + This option will submit extra files to the dashboard. + +``--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. + +``--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. + +``--print-labels`` + Print all available test labels. + + This option will not run any tests, it will simply print the list of + all labels associated with the test set. + +.. include:: OPTIONS_HELP.txt + +.. _`Dashboard Client`: + +Dashboard Client +================ + +CTest can operate as a client for the `CDash`_ software quality dashboard +application. As a dashboard client, CTest performs a sequence of steps +to configure, build, and test software, and then submits the results to +a `CDash`_ server. + +.. _`CDash`: http://cdash.org/ + +Dashboard Client Steps +---------------------- + +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` + +.. _`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 + +``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: + +``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`` + +.. _`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 diff --git a/Help/module/AddFileDependencies.rst b/Help/module/AddFileDependencies.rst new file mode 100644 index 000000000..3cbce33ac --- /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 000000000..e7ec864c7 --- /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 000000000..5d9c84017 --- /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 000000000..9abf571af --- /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 000000000..05e5f4abe --- /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 000000000..fd071b55b --- /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 000000000..176853372 --- /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 000000000..108428034 --- /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 000000000..5b5b550a3 --- /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 000000000..c2c219b3e --- /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 000000000..d099d19e3 --- /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 000000000..327742694 --- /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 000000000..2cd97b3c4 --- /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 000000000..a291aff0c --- /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 000000000..810a9dd3c --- /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 000000000..a75a34f0a --- /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 000000000..0b5d8489a --- /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 000000000..e89792959 --- /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 000000000..eeff1bf49 --- /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 000000000..bfbda1f89 --- /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 000000000..eb8d9d244 --- /dev/null +++ b/Help/module/CPackArchive.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CPackArchive.cmake diff --git a/Help/module/CPackBundle.rst b/Help/module/CPackBundle.rst new file mode 100644 index 000000000..651e87426 --- /dev/null +++ b/Help/module/CPackBundle.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CPackBundle.cmake diff --git a/Help/module/CPackComponent.rst b/Help/module/CPackComponent.rst new file mode 100644 index 000000000..df82836ca --- /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 000000000..21f447348 --- /dev/null +++ b/Help/module/CPackCygwin.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CPackCygwin.cmake diff --git a/Help/module/CPackDMG.rst b/Help/module/CPackDMG.rst new file mode 100644 index 000000000..784262c5e --- /dev/null +++ b/Help/module/CPackDMG.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CPackDMG.cmake diff --git a/Help/module/CPackDeb.rst b/Help/module/CPackDeb.rst new file mode 100644 index 000000000..d1526ee49 --- /dev/null +++ b/Help/module/CPackDeb.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CPackDeb.cmake diff --git a/Help/module/CPackIFW.rst b/Help/module/CPackIFW.rst new file mode 100644 index 000000000..ea05796ad --- /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 000000000..e88517cec --- /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 000000000..bb35ed60a --- /dev/null +++ b/Help/module/CPackNSIS.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CPackNSIS.cmake diff --git a/Help/module/CPackPackageMaker.rst b/Help/module/CPackPackageMaker.rst new file mode 100644 index 000000000..de5544869 --- /dev/null +++ b/Help/module/CPackPackageMaker.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CPackPackageMaker.cmake diff --git a/Help/module/CPackProductBuild.rst b/Help/module/CPackProductBuild.rst new file mode 100644 index 000000000..6081fe48a --- /dev/null +++ b/Help/module/CPackProductBuild.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CPackProductBuild.cmake diff --git a/Help/module/CPackRPM.rst b/Help/module/CPackRPM.rst new file mode 100644 index 000000000..28d0e6912 --- /dev/null +++ b/Help/module/CPackRPM.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CPackRPM.cmake diff --git a/Help/module/CPackWIX.rst b/Help/module/CPackWIX.rst new file mode 100644 index 000000000..1f5e451e9 --- /dev/null +++ b/Help/module/CPackWIX.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CPackWIX.cmake diff --git a/Help/module/CSharpUtilities.rst b/Help/module/CSharpUtilities.rst new file mode 100644 index 000000000..3621bbc25 --- /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 000000000..11a6af7d7 --- /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 000000000..4c5deca4d --- /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 000000000..be1b0447e --- /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 000000000..688da0870 --- /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 000000000..1be1491cc --- /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 000000000..1fa02f9b1 --- /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 000000000..16b47e66d --- /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 000000000..cfd1f457b --- /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 000000000..d701c4e54 --- /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 000000000..caab97589 --- /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 000000000..fc192e819 --- /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 000000000..58bf6ec35 --- /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 000000000..3395d05c4 --- /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 000000000..b749a2a30 --- /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 000000000..ed89dc407 --- /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 000000000..9c8a77b05 --- /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 000000000..6b831089e --- /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 000000000..fdbf39fd1 --- /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 000000000..b56f14565 --- /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 000000000..16f1a3f79 --- /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 000000000..7512f46c5 --- /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 000000000..073fcb59f --- /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 000000000..5277ad2f6 --- /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 000000000..68ae70009 --- /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 000000000..6ad03456f --- /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 000000000..07f077792 --- /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 000000000..524ac33df --- /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 000000000..3c0ef444a --- /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 000000000..08e2ffb6d --- /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 000000000..f0f8f1d07 --- /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 000000000..fce70567e --- /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 000000000..6fd8f3805 --- /dev/null +++ b/Help/module/FeatureSummary.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FeatureSummary.cmake diff --git a/Help/module/FindALSA.rst b/Help/module/FindALSA.rst new file mode 100644 index 000000000..2a73786b4 --- /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 000000000..56dedc428 --- /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 000000000..71282a684 --- /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 000000000..f0ac933d1 --- /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 000000000..c6e5791be --- /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 000000000..41f67711c --- /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 000000000..281b1d10d --- /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 000000000..e1ca48c77 --- /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 000000000..139254055 --- /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 000000000..4ed2b855b --- /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 000000000..716d5abd5 --- /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 000000000..46ffa9fc2 --- /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 000000000..e2acc4987 --- /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 000000000..c891c07d7 --- /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 000000000..fc70a74d6 --- /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 000000000..10d0646fd --- /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 000000000..73dd01171 --- /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 000000000..4f17c39bc --- /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 000000000..2e529dd03 --- /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 000000000..8437d5557 --- /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 000000000..6f21ad4be --- /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 000000000..91a28ddc4 --- /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 000000000..cffe73453 --- /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 000000000..5063680bb --- /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 000000000..cc90791d9 --- /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 000000000..cc1964cc4 --- /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 000000000..5c2acc4ae --- /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 000000000..424c3fcb3 --- /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 000000000..15fd4d0d6 --- /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 000000000..81fcb3a20 --- /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 000000000..03d3a7538 --- /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 000000000..77755da1f --- /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 000000000..40263eeb9 --- /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 000000000..baf221368 --- /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 000000000..1ce6a8675 --- /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 000000000..67c1ba9e2 --- /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 000000000..0e3b4d770 --- /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 000000000..e880dc038 --- /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 000000000..dd540ef2f --- /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 000000000..de0c1d4f8 --- /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 000000000..93a18b608 --- /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 000000000..8ac1b8be9 --- /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 000000000..c1905a2e3 --- /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 000000000..47d9c8c49 --- /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 000000000..94aba6f7e --- /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 000000000..ee3f4a9cc --- /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 000000000..21a922f61 --- /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 000000000..3af9405e0 --- /dev/null +++ b/Help/module/FindIce.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindIce.cmake diff --git a/Help/module/FindIcotool.rst b/Help/module/FindIcotool.rst new file mode 100644 index 000000000..c139f58cc --- /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 000000000..3a3596e5e --- /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 000000000..813e2df9a --- /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 000000000..b753cf891 --- /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 000000000..80363529a --- /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 000000000..725a87fc4 --- /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 000000000..39e6b6b21 --- /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 000000000..13ac15c8c --- /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 000000000..8b22f7fc8 --- /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 000000000..6e9909016 --- /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 000000000..4b14c7136 --- /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 000000000..a775462b7 --- /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 000000000..c46b1d004 --- /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 000000000..88801580c --- /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 000000000..bbb322590 --- /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 000000000..4107170cf --- /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 000000000..977e5bfce --- /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 000000000..0353fc35e --- /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 000000000..672ff357b --- /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 000000000..a3226a690 --- /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 000000000..c9ce48142 --- /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 000000000..f843c8971 --- /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 000000000..fad10c732 --- /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 000000000..43f861adc --- /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 000000000..e602a501c --- /dev/null +++ b/Help/module/FindMotif.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindMotif.cmake diff --git a/Help/module/FindOpenAL.rst b/Help/module/FindOpenAL.rst new file mode 100644 index 000000000..f0865569d --- /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 000000000..e87e289bd --- /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 000000000..85e89bcb3 --- /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 000000000..01362abfb --- /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 000000000..f622bb14e --- /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 000000000..434649257 --- /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 000000000..bb3f0f97b --- /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 000000000..1de62e8d4 --- /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 000000000..e6d161875 --- /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 000000000..feda7ef61 --- /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 000000000..b682d8c0f --- /dev/null +++ b/Help/module/FindPackageMessage.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindPackageMessage.cmake diff --git a/Help/module/FindPerl.rst b/Help/module/FindPerl.rst new file mode 100644 index 000000000..098f4b545 --- /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 000000000..8d8bbab7b --- /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 000000000..21d928bab --- /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 000000000..b096ca4da --- /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 000000000..b8caf7442 --- /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 000000000..b45c07e7f --- /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 000000000..1c0c575ff --- /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 000000000..b978e010f --- /dev/null +++ b/Help/module/FindProtobuf.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindProtobuf.cmake diff --git a/Help/module/FindPythonInterp.rst b/Help/module/FindPythonInterp.rst new file mode 100644 index 000000000..3be230692 --- /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 000000000..8f0015d33 --- /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 000000000..3aa8a26de --- /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 000000000..b93305909 --- /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 000000000..28036b2fd --- /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 000000000..735f7d29f --- /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 000000000..a93ad1658 --- /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 000000000..a1e792241 --- /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 000000000..79893c03c --- /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 000000000..dc69d7070 --- /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 000000000..1c9c44674 --- /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 000000000..079d0bbe3 --- /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 000000000..077edf700 --- /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 000000000..40c5ec4c4 --- /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 000000000..9b25b94b3 --- /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 000000000..5f2c689ca --- /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 000000000..dc2c86d53 --- /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 000000000..aa15857d1 --- /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 000000000..cbd203589 --- /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 000000000..69f8ca585 --- /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 000000000..6cc5b2df2 --- /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 000000000..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 000000000..91967a7a3 --- /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 000000000..9ad05ad2d --- /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 000000000..3bc67c5c9 --- /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 000000000..adf824ebe --- /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 000000000..06affd4eb --- /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 000000000..76be4cf54 --- /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 000000000..906efd738 --- /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 000000000..ff6273c47 --- /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 000000000..5d11a0ca8 --- /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 000000000..b99d21256 --- /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 000000000..4818071c3 --- /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 000000000..ded863463 --- /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 000000000..6b407aca5 --- /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 000000000..f14a1e7f3 --- /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 000000000..9f72bc794 --- /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 000000000..0e1edfba1 --- /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 000000000..562d73fd5 --- /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 000000000..53621a71e --- /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 000000000..b9d615d37 --- /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 000000000..9cf191c37 --- /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 000000000..cb47841bd --- /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 000000000..c502851b4 --- /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 000000000..08c870453 --- /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 000000000..fbb22e108 --- /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 000000000..9e47b6567 --- /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 000000000..dd401d8b2 --- /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 000000000..bb028fb15 --- /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 000000000..bb11bdf4d --- /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 000000000..5def37544 --- /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 000000000..d836906e3 --- /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 000000000..bdd11355d --- /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 000000000..522e1ac16 --- /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 000000000..519beb725 --- /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 000000000..35c972813 --- /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 000000000..7afcf154b --- /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 000000000..79d357040 --- /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 000000000..115713ecd --- /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 000000000..84b20c876 --- /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 000000000..3d4cc975d --- /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 000000000..5ea9af33e --- /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 000000000..5f0bf6bbf --- /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 000000000..0149d0924 --- /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 000000000..14fd6f88a --- /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 000000000..47da404f1 --- /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 000000000..f9e4d2f10 --- /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 000000000..ee3d70a71 --- /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 000000000..00d923803 --- /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 000000000..212a30b79 --- /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 000000000..d1547519e --- /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 000000000..ad989e367 --- /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 000000000..0e578685a --- /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 000000000..fa2f1bd6f --- /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 000000000..b9cd4769e --- /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 000000000..2fab8e8dd --- /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 000000000..668f7662b --- /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 000000000..0007c355c --- /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 000000000..a489e9849 --- /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 000000000..6829c2d2b --- /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 000000000..c637d5dc2 --- /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 000000000..4c81b4883 --- /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 000000000..97ea633b2 --- /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 000000000..09ad38702 --- /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 000000000..7cc53efa1 --- /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 000000000..16b045165 --- /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 000000000..55da4d293 --- /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 000000000..66d125fb7 --- /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 000000000..d1b9ece7f --- /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 000000000..39276457a --- /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 000000000..f1e2ddde5 --- /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 000000000..44baeb449 --- /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 000000000..344d70475 --- /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 000000000..d281e0ef7 --- /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 000000000..85d64f4d4 --- /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 000000000..2fabb8920 --- /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 000000000..f1f7b77b8 --- /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 000000000..9a48e3dac --- /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 000000000..cc898c8ca --- /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 000000000..9f0f0380f --- /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 000000000..a3a7a12bd --- /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 000000000..2e3557d32 --- /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 000000000..75ca9deb2 --- /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 000000000..3a792ca14 --- /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 000000000..579d09ac0 --- /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 000000000..76a4900b6 --- /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 000000000..272a56c8d --- /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 000000000..62dd50985 --- /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 000000000..3fe1374c8 --- /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 000000000..28913cee4 --- /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 000000000..be57125d4 --- /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 000000000..aa10b97a9 --- /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 000000000..81bbb84e8 --- /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 000000000..8c3eef62a --- /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 000000000..5c1fa4be2 --- /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 000000000..4a6cc591d --- /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 000000000..0f3934aae --- /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 000000000..58199a45f --- /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 000000000..4bcfc54d9 --- /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 000000000..9f8457c62 --- /dev/null +++ b/Help/policy/CMP0037.rst @@ -0,0 +1,28 @@ +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 consequtive colons. + +Target names reserved by one or more CMake generators are not allowed. +Among others these include "all", "help" and "test". + +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 000000000..a306d90a9 --- /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 000000000..97d78ae2a --- /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 000000000..d46baf647 --- /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 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 000000000..f027d5de9 --- /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 000000000..31314b2cd --- /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 000000000..9e427c377 --- /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 000000000..02afa9f1a --- /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 000000000..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 000000000..576d1b1cc --- /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 000000000..882dd7828 --- /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 000000000..0e7e60681 --- /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 000000000..a3ce4b1fa --- /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 000000000..39e40b698 --- /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 000000000..6b679e5b4 --- /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 000000000..0ea5ace77 --- /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 000000000..2620a60e0 --- /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 000000000..1e000a662 --- /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 000000000..b3df758fe --- /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 000000000..3ba89d576 --- /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 000000000..83db1863d --- /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 000000000..05efd48fb --- /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 000000000..bce982e10 --- /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 000000000..8611affac --- /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 000000000..cb2ac2840 --- /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 000000000..9047fffbe --- /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 000000000..d736d0634 --- /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 000000000..e9a061ba1 --- /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 000000000..2ed775dee --- /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 000000000..d1dcb0ec6 --- /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 000000000..e6dda8018 --- /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 000000000..978a6e34f --- /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 000000000..0d5ddfde9 --- /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/DEPRECATED.txt b/Help/policy/DEPRECATED.txt new file mode 100644 index 000000000..f66de55ae --- /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 000000000..36280d2b6 --- /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 000000000..a0a4f73bb --- /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 000000000..71a86d055 --- /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 000000000..3ad70354d --- /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 000000000..2f8e32e3f --- /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 000000000..eb75c2ab2 --- /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 000000000..59aabd431 --- /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 000000000..e32eed3ed --- /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 000000000..597c79aa8 --- /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 000000000..da907cb93 --- /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 000000000..2c66f939e --- /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 000000000..5ae78bf75 --- /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 000000000..b1aef1966 --- /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 000000000..85adcb58a --- /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_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 000000000..a6af45f35 --- /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 000000000..877deb000 --- /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 000000000..79ac3f346 --- /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 000000000..1aa24e44b --- /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 000000000..993f6200e --- /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 000000000..6789a5644 --- /dev/null +++ b/Help/prop_dir/INCLUDE_DIRECTORIES.rst @@ -0,0 +1,26 @@ +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. 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. + +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 000000000..bb90c61a7 --- /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 000000000..0c78dfbe7 --- /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 000000000..325208656 --- /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/LINK_DIRECTORIES.rst b/Help/prop_dir/LINK_DIRECTORIES.rst new file mode 100644 index 000000000..fa375766d --- /dev/null +++ b/Help/prop_dir/LINK_DIRECTORIES.rst @@ -0,0 +1,8 @@ +LINK_DIRECTORIES +---------------- + +List of linker search directories. + +This read-only property specifies the list of directories given so far +to the link_directories command. It is intended for debugging +purposes. diff --git a/Help/prop_dir/LISTFILE_STACK.rst b/Help/prop_dir/LISTFILE_STACK.rst new file mode 100644 index 000000000..22ec4b68a --- /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 000000000..e4feadaa5 --- /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 000000000..3bc5824c9 --- /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 000000000..342d0ae79 --- /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 000000000..93d1e0111 --- /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 000000000..3cfb2369b --- /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 000000000..ac98c3b28 --- /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 000000000..2c2ea773e --- /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/TEST_INCLUDE_FILE.rst b/Help/prop_dir/TEST_INCLUDE_FILE.rst new file mode 100644 index 000000000..e47795191 --- /dev/null +++ b/Help/prop_dir/TEST_INCLUDE_FILE.rst @@ -0,0 +1,7 @@ +TEST_INCLUDE_FILE +----------------- + +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/VARIABLES.rst b/Help/prop_dir/VARIABLES.rst new file mode 100644 index 000000000..0328295c3 --- /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 000000000..a316abec9 --- /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 8 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 000000000..200e8e62f --- /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 8 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 000000000..04441b621 --- /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 000000000..8fab50345 --- /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 000000000..d294eb170 --- /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 000000000..0b747b207 --- /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 000000000..2455dc763 --- /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 000000000..17666e45a --- /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 000000000..65ea95b17 --- /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 000000000..2ad81574f --- /dev/null +++ b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst @@ -0,0 +1,315 @@ +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_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 000000000..3707fef1e --- /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 000000000..690143f82 --- /dev/null +++ b/Help/prop_gbl/DEBUG_CONFIGURATIONS.rst @@ -0,0 +1,14 @@ +DEBUG_CONFIGURATIONS +-------------------- + +Specify which configurations are for debugging. + +The value must be a semi-colon separated list of configuration names. +Currently this property is used only by the target_link_libraries +command (see its documentation for details). Additional uses may be +defined in the future. + +This property must be set at the top level of the project and before +the first target_link_libraries command invocation. If any entry in +the 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 000000000..111cdf67e --- /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_NATURES.rst b/Help/prop_gbl/ECLIPSE_EXTRA_NATURES.rst new file mode 100644 index 000000000..6d1529d3a --- /dev/null +++ b/Help/prop_gbl/ECLIPSE_EXTRA_NATURES.rst @@ -0,0 +1,8 @@ +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). diff --git a/Help/prop_gbl/ENABLED_FEATURES.rst b/Help/prop_gbl/ENABLED_FEATURES.rst new file mode 100644 index 000000000..b03da5a45 --- /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 000000000..43e3c09f7 --- /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 000000000..839602674 --- /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 000000000..ed343ba41 --- /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 000000000..b87b09be1 --- /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 000000000..beb94ac41 --- /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 000000000..b8ec8a62c --- /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 000000000..832503b51 --- /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 000000000..d10661e62 --- /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 000000000..fd2d2e196 --- /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 000000000..2ce74b81c --- /dev/null +++ b/Help/prop_gbl/JOB_POOLS.rst @@ -0,0 +1,23 @@ +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`. + +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 000000000..61cce1fd8 --- /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 000000000..ca3c5bac6 --- /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 000000000..bf8c9a354 --- /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 000000000..29ba36557 --- /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 000000000..e0df8784a --- /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 000000000..b20c59bcc --- /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 000000000..567bb6864 --- /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 000000000..87a5ca613 --- /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 ``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 000000000..930febae7 --- /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 000000000..275b0741d --- /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 000000000..f6e89fb83 --- /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 000000000..a1b4ccb5b --- /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 000000000..9a6086ed8 --- /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 000000000..11f2c036c --- /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 000000000..11f44d0df --- /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 000000000..5e191d08e --- /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 000000000..8a160223d --- /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 000000000..d30ea39fd --- /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 000000000..4e13ec48c --- /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 000000000..339d11528 --- /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 000000000..d9dc4d33e --- /dev/null +++ b/Help/prop_sf/AUTORCC_OPTIONS.rst @@ -0,0 +1,13 @@ +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. diff --git a/Help/prop_sf/AUTOUIC_OPTIONS.rst b/Help/prop_sf/AUTOUIC_OPTIONS.rst new file mode 100644 index 000000000..bb48da90f --- /dev/null +++ b/Help/prop_sf/AUTOUIC_OPTIONS.rst @@ -0,0 +1,14 @@ +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. diff --git a/Help/prop_sf/COMPILE_DEFINITIONS.rst b/Help/prop_sf/COMPILE_DEFINITIONS.rst new file mode 100644 index 000000000..1626825f1 --- /dev/null +++ b/Help/prop_sf/COMPILE_DEFINITIONS.rst @@ -0,0 +1,19 @@ +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 diff --git a/Help/prop_sf/COMPILE_DEFINITIONS_CONFIG.rst b/Help/prop_sf/COMPILE_DEFINITIONS_CONFIG.rst new file mode 100644 index 000000000..848707647 --- /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 000000000..10121644e --- /dev/null +++ b/Help/prop_sf/COMPILE_FLAGS.rst @@ -0,0 +1,15 @@ +COMPILE_FLAGS +------------- + +Additional flags to be added when compiling this source file. + +These flags will be added to the list of compile flags when this +source file builds. Use :prop_sf:`COMPILE_DEFINITIONS` to pass +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. diff --git a/Help/prop_sf/EXTERNAL_OBJECT.rst b/Help/prop_sf/EXTERNAL_OBJECT.rst new file mode 100644 index 000000000..efa0e9bea --- /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 000000000..69e34aafd --- /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 000000000..a3aa12747 --- /dev/null +++ b/Help/prop_sf/GENERATED.rst @@ -0,0 +1,8 @@ +GENERATED +--------- + +Is this source file generated as part of the build process. + +If a source file is generated by the build process CMake will handle +it differently in terms of dependency checking etc. Otherwise having +a non-existent source file could create problems. diff --git a/Help/prop_sf/HEADER_FILE_ONLY.rst b/Help/prop_sf/HEADER_FILE_ONLY.rst new file mode 100644 index 000000000..71d62ae80 --- /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/KEEP_EXTENSION.rst b/Help/prop_sf/KEEP_EXTENSION.rst new file mode 100644 index 000000000..d6167e5a9 --- /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 000000000..e1c10696a --- /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 000000000..97bfa20f4 --- /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 000000000..252d68024 --- /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 000000000..a064afa63 --- /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 OS X +and iOS. + +Executable targets with the :prop_tgt:`MACOSX_BUNDLE` property set are +built as OS X or iOS application bundles on Apple platforms. Shared +library targets with the :prop_tgt:`FRAMEWORK` property set are built as +OS X or iOS frameworks on Apple platforms. Module library targets with +the :prop_tgt:`BUNDLE` property set are built as OS X ``CFBundle`` bundles +on Apple platforms. Source files listed in the target with this property +set will be copied to a directory inside the bundle or framework content +folder specified by the property value. For OS X Application Bundles the +content folder is ``<name>.app/Contents``. For OS X Frameworks the +content folder is ``<name>.framework/Versions/<version>``. For OS X +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 000000000..1d24960b5 --- /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 000000000..6a2855374 --- /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 000000000..6bf2409b2 --- /dev/null +++ b/Help/prop_sf/SKIP_AUTOGEN.rst @@ -0,0 +1,8 @@ +SKIP_AUTOGEN +------------ + +Exclude the source file from :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTOUIC` and +:prop_tgt:`AUTORCC` processing (for Qt projects). + +For finer control see :prop_sf:`SKIP_AUTOMOC`, :prop_sf:`SKIP_AUTOUIC` and +:prop_sf:`SKIP_AUTORCC`. diff --git a/Help/prop_sf/SKIP_AUTOMOC.rst b/Help/prop_sf/SKIP_AUTOMOC.rst new file mode 100644 index 000000000..2245ca639 --- /dev/null +++ b/Help/prop_sf/SKIP_AUTOMOC.rst @@ -0,0 +1,6 @@ +SKIP_AUTOMOC +------------ + +Exclude the source file from :prop_tgt:`AUTOMOC` processing (for Qt projects). + +For broader control see :prop_sf:`SKIP_AUTOGEN` diff --git a/Help/prop_sf/SKIP_AUTORCC.rst b/Help/prop_sf/SKIP_AUTORCC.rst new file mode 100644 index 000000000..394d8f8cf --- /dev/null +++ b/Help/prop_sf/SKIP_AUTORCC.rst @@ -0,0 +1,6 @@ +SKIP_AUTORCC +------------ + +Exclude the source file from :prop_tgt:`AUTORCC` processing (for Qt projects). + +For broader control see :prop_sf:`SKIP_AUTOGEN` diff --git a/Help/prop_sf/SKIP_AUTOUIC.rst b/Help/prop_sf/SKIP_AUTOUIC.rst new file mode 100644 index 000000000..50f78ef66 --- /dev/null +++ b/Help/prop_sf/SKIP_AUTOUIC.rst @@ -0,0 +1,6 @@ +SKIP_AUTOUIC +------------ + +Exclude the source file from :prop_tgt:`AUTOUIC` processing (for Qt projects). + +For broader control see :prop_sf:`SKIP_AUTOGEN` diff --git a/Help/prop_sf/SYMBOLIC.rst b/Help/prop_sf/SYMBOLIC.rst new file mode 100644 index 000000000..c7d0b2603 --- /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 000000000..16c8d8307 --- /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 000000000..d42159f6d --- /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 000000000..9fb3ba3d0 --- /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 000000000..303db952b --- /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 000000000..30f471d30 --- /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 000000000..97e5aac7a --- /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_ENTRYPOINT.rst b/Help/prop_sf/VS_SHADER_ENTRYPOINT.rst new file mode 100644 index 000000000..fe3471f25 --- /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 000000000..09011231b --- /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 000000000..b1cf0df55 --- /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_TYPE.rst b/Help/prop_sf/VS_SHADER_TYPE.rst new file mode 100644 index 000000000..688025608 --- /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_TOOL_OVERRIDE.rst b/Help/prop_sf/VS_TOOL_OVERRIDE.rst new file mode 100644 index 000000000..8bdc5ca50 --- /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 000000000..e92191dcb --- /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 000000000..2c79f72a2 --- /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 000000000..1b24701a3 --- /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 000000000..39e69665a --- /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 000000000..42e37574d --- /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 000000000..496d80071 --- /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 000000000..add54b2b1 --- /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 000000000..3236a0295 --- /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 000000000..89c755325 --- /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 000000000..c18ae7ffa --- /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 000000000..df9bc9e14 --- /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 000000000..facf90255 --- /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 000000000..f0a4be0ec --- /dev/null +++ b/Help/prop_test/FIXTURES_CLEANUP.rst @@ -0,0 +1,46 @@ +FIXTURES_CLEANUP +---------------- + +Specifies a list of fixtures for which the test is to be treated as a cleanup +test. + +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 000000000..e37dfb57d --- /dev/null +++ b/Help/prop_test/FIXTURES_REQUIRED.rst @@ -0,0 +1,94 @@ +FIXTURES_REQUIRED +----------------- + +Specifies a list of fixtures the test requires. Fixture names are case +sensitive. + +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. + +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 000000000..a22021592 --- /dev/null +++ b/Help/prop_test/FIXTURES_SETUP.rst @@ -0,0 +1,47 @@ +FIXTURES_SETUP +-------------- + +Specifies a list of fixtures for which the test is to be treated as a setup +test. + +Fixture setup tests are ordinary tests with all of the usual test +functionality. Setting the ``FIXTURES_SETUP`` property for a test has two +primary effects: + +- CTest will ensure the test executes before any other test which lists the + fixture(s) in its :prop_test:`FIXTURES_REQUIRED` property. + +- 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 000000000..8d7557095 --- /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 000000000..bc4936e97 --- /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 000000000..0cd621526 --- /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 000000000..763b6d003 --- /dev/null +++ b/Help/prop_test/PROCESSORS.rst @@ -0,0 +1,8 @@ +PROCESSORS +---------- + +How many process slots this test requires + +Denotes the number of processors that this test will require. This is +typically used for MPI tests, and should be used in conjunction with +the ctest_test PARALLEL_LEVEL option. diff --git a/Help/prop_test/REQUIRED_FILES.rst b/Help/prop_test/REQUIRED_FILES.rst new file mode 100644 index 000000000..fac357c1e --- /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 000000000..755e0aaa3 --- /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 000000000..8f65ae18a --- /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 000000000..c61273c56 --- /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 000000000..d1cb90d0a --- /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 000000000..d607992e1 --- /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 000000000..f1f94a43a --- /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 000000000..5222a197b --- /dev/null +++ b/Help/prop_test/WORKING_DIRECTORY.rst @@ -0,0 +1,7 @@ +WORKING_DIRECTORY +----------------- + +The directory from which the test executable will be called. + +If this is not set it is called from the directory the test executable +is located in. diff --git a/Help/prop_tgt/ALIASED_TARGET.rst b/Help/prop_tgt/ALIASED_TARGET.rst new file mode 100644 index 000000000..f9e60348d --- /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 000000000..af6b40587 --- /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 000000000..63464d7a1 --- /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 000000000..773ab3feb --- /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 000000000..3e07e5a9f --- /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 000000000..764a58244 --- /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 000000000..92e2041af --- /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 000000000..42937c1b4 --- /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 000000000..54f0a8ff7 --- /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 000000000..90ef1ce93 --- /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 000000000..759a37b06 --- /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 000000000..bc673804d --- /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 000000000..847acae5b --- /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 000000000..dafc51ee5 --- /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 000000000..0e929d16a --- /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 000000000..9533f1a70 --- /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 000000000..636189656 --- /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 000000000..386e96e6c --- /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 000000000..42210696b --- /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 000000000..12f8bb7ef --- /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 000000000..615019373 --- /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 000000000..4f62eb995 --- /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 000000000..8db6ede91 --- /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_TARGET_DEPENDS.rst b/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst new file mode 100644 index 000000000..f522c6bf2 --- /dev/null +++ b/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst @@ -0,0 +1,17 @@ +AUTOGEN_TARGET_DEPENDS +---------------------- + +Target dependencies of the corresponding ``_autogen`` target. + +Targets which have their :prop_tgt:`AUTOMOC` target ``ON`` have a +corresponding ``_autogen`` target which is used to autogenerate generate moc +files. As this ``_autogen`` target is created at generate-time, it is not +possible to define dependencies of it, such as to create inputs for the ``moc`` +executable. + +The ``AUTOGEN_TARGET_DEPENDS`` target property can be set instead to a list of +dependencies for the ``_autogen`` target. The buildsystem will be generated to +depend on its contents. + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. diff --git a/Help/prop_tgt/AUTOMOC.rst b/Help/prop_tgt/AUTOMOC.rst new file mode 100644 index 000000000..0171d20e7 --- /dev/null +++ b/Help/prop_tgt/AUTOMOC.rst @@ -0,0 +1,76 @@ +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, + the ``Q_OBJECT`` or ``Q_GADGET`` macros are expected in an otherwise empty + line of the ``<basename>.h(xx)`` header file. ``moc`` is run on the header + file to generate ``moc_<basename>.cpp`` in the + ``<AUTOGEN_BUILD_DIR>/include`` directory which is automatically added + to the target's :prop_tgt:`INCLUDE_DIRECTORIES`. + This allows the compiler to find the included ``moc_<basename>.cpp`` file + regardless of the location the original source. + + * See :prop_tgt:`AUTOGEN_BUILD_DIR`. + +* If an ``#include`` statement like ``#include "<basename>.moc"`` is found, + then ``Q_OBJECT`` or ``Q_GADGET`` macros are expected in the current source + file and ``moc`` is run on the source file itself. + +* Header files that are not included by an ``#include "moc_<basename>.cpp"`` + statement are nonetheless scanned for ``Q_OBJECT`` or ``Q_GADGET`` macros. + The resulting ``moc_<basename>.cpp`` files are generated in custom + directories and automatically included in a generated + ``<AUTOGEN_BUILD_DIR>/mocs_compilation.cpp`` file, + which is compiled as part of the target. + + * 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 parsed for ``Q_OBJECT`` or ``Q_GADGET`` macros, + 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 ``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`. + +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 000000000..810cbf4ae --- /dev/null +++ b/Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst @@ -0,0 +1,45 @@ +AUTOMOC_DEPEND_FILTERS +---------------------- + +Filter definitions used by :prop_tgt:`AUTOMOC` to extract file names from +source code as additional dependencies for the ``moc`` file. + +This property is only used if the :prop_tgt:`AUTOMOC` property is ``ON`` +for this target. + +Filters are defined as ``KEYWORD;REGULAR_EXPRESSION`` pairs. First the file +content is searched for ``KEYWORD``. If it is found at least once, then file +names are extracted by successively searching for ``REGULAR_EXPRESSION`` and +taking the first match group. + +Consider a filter extracts the file name ``DEP`` from the content of a file +``FOO``. If ``DEP`` changes, then the ``moc`` file for ``FOO`` gets rebuilt. +The file ``DEP`` is searched for first in the vicinity +of ``FOO`` and afterwards in the target's :prop_tgt:`INCLUDE_DIRECTORIES`. + +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 +------- + +Consider a file ``FOO.hpp`` holds a custom macro ``OBJ_JSON_FILE`` and we +want the ``moc`` file to depend on the macro`s file name argument:: + + class My_Class : public QObject + { + Q_OBJECT + OBJ_JSON_FILE ( "DEP.json" ) + ... + }; + +Then we might use :variable:`CMAKE_AUTOMOC_DEPEND_FILTERS` to +define a filter like this:: + + set(CMAKE_AUTOMOC_DEPEND_FILTERS + "OBJ_JSON_FILE" "[\n][ \t]*OBJ_JSON_FILE[ \t]*\\([ \t]*\"([^\"]+)\"" + ) diff --git a/Help/prop_tgt/AUTOMOC_MOC_OPTIONS.rst b/Help/prop_tgt/AUTOMOC_MOC_OPTIONS.rst new file mode 100644 index 000000000..ebd5c4951 --- /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 000000000..c0f6a26b2 --- /dev/null +++ b/Help/prop_tgt/AUTORCC.rst @@ -0,0 +1,34 @@ +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. + +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 000000000..8a0f632c2 --- /dev/null +++ b/Help/prop_tgt/AUTORCC_OPTIONS.rst @@ -0,0 +1,21 @@ +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. diff --git a/Help/prop_tgt/AUTOUIC.rst b/Help/prop_tgt/AUTOUIC.rst new file mode 100644 index 000000000..6493bbc78 --- /dev/null +++ b/Help/prop_tgt/AUTOUIC.rst @@ -0,0 +1,34 @@ +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`. + +* 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`. + +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 000000000..9fb042ea6 --- /dev/null +++ b/Help/prop_tgt/AUTOUIC_OPTIONS.rst @@ -0,0 +1,25 @@ +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. diff --git a/Help/prop_tgt/AUTOUIC_SEARCH_PATHS.rst b/Help/prop_tgt/AUTOUIC_SEARCH_PATHS.rst new file mode 100644 index 000000000..96d9f8977 --- /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 000000000..246f7e605 --- /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 000000000..27393f5d7 --- /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 000000000..bbb9a24ba --- /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 000000000..024435104 --- /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 000000000..075f017df --- /dev/null +++ b/Help/prop_tgt/BUNDLE.rst @@ -0,0 +1,9 @@ +BUNDLE +------ + +This target is a ``CFBundle`` on the OS X. + +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 000000000..6b3d58023 --- /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 OS X and iOS. + +The default value is ``bundle``, ``framework``, or ``app`` for the respective +target types. diff --git a/Help/prop_tgt/COMPATIBLE_INTERFACE_BOOL.rst b/Help/prop_tgt/COMPATIBLE_INTERFACE_BOOL.rst new file mode 100644 index 000000000..6910367e4 --- /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 000000000..298acf1ba --- /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 000000000..d5fd8252a --- /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 000000000..a0050b941 --- /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 000000000..059f9137f --- /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 000000000..84bd5e483 --- /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 000000000..195215e3c --- /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 000000000..1a5389e48 --- /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 000000000..892ac23e1 --- /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 000000000..24a9f62d6 --- /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 000000000..e4077f559 --- /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 000000000..43003d94a --- /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 000000000..34f49bebe --- /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 000000000..52ef013da --- /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 000000000..a61c70295 --- /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 000000000..11b50b900 --- /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 000000000..a0811bcaa --- /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 000000000..098ca3c46 --- /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 000000000..0ee372b8b --- /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 000000000..127d79fb3 --- /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 000000000..1c7dd8083 --- /dev/null +++ b/Help/prop_tgt/CUDA_SEPARABLE_COMPILATION.rst @@ -0,0 +1,13 @@ +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) diff --git a/Help/prop_tgt/CUDA_STANDARD.rst b/Help/prop_tgt/CUDA_STANDARD.rst new file mode 100644 index 000000000..b26281471 --- /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``. + +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 000000000..b2d5b28f3 --- /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 000000000..280bb3a7a --- /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 000000000..30a612db6 --- /dev/null +++ b/Help/prop_tgt/CXX_STANDARD.rst @@ -0,0 +1,33 @@ +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 MSVC, this has no effect. + +Supported values are ``98``, ``11``, ``14``, and ``17``. + +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 000000000..697d7f60d --- /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 000000000..05b14ce70 --- /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 000000000..815a68676 --- /dev/null +++ b/Help/prop_tgt/C_STANDARD.rst @@ -0,0 +1,33 @@ +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 MSVC, 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 000000000..acfad986b --- /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 000000000..1487656d9 --- /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 000000000..f47f135ea --- /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_REMOTE_DIRECTORY.rst b/Help/prop_tgt/DEPLOYMENT_REMOTE_DIRECTORY.rst new file mode 100644 index 000000000..1ff5bf01e --- /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` and :generator:`Visual Studio 8 2005` +generators. 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/ENABLE_EXPORTS.rst b/Help/prop_tgt/ENABLE_EXPORTS.rst new file mode 100644 index 000000000..9e2230971 --- /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 OS X, the +module will "link" to the executable using a flag like +``-bundle_loader``. For other non-DLL platforms the link rule is simply +ignored since the dynamic loader will automatically bind symbols when +the module is loaded. + +This 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 000000000..caa5741f8 --- /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 000000000..a14e48c19 --- /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 000000000..655a9dee0 --- /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 000000000..1b4247cc5 --- /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/EchoString.rst b/Help/prop_tgt/EchoString.rst new file mode 100644 index 000000000..32ae2aa8f --- /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 000000000..bfe4e8e16 --- /dev/null +++ b/Help/prop_tgt/FOLDER.rst @@ -0,0 +1,10 @@ +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. diff --git a/Help/prop_tgt/FRAMEWORK.rst b/Help/prop_tgt/FRAMEWORK.rst new file mode 100644 index 000000000..495d30e95 --- /dev/null +++ b/Help/prop_tgt/FRAMEWORK.rst @@ -0,0 +1,35 @@ +FRAMEWORK +--------- + +Build ``SHARED`` or ``STATIC`` library as Framework Bundle on the OS X and iOS. + +If such a library target has this property set to ``TRUE`` it will be +built as a framework when built on the OS X and iOS. It will have the +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 OS X 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 000000000..6aa30268a --- /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 OS X, 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 000000000..0a11d91ca --- /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 000000000..9c8643764 --- /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 000000000..032b22acf --- /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 000000000..cf34da9c3 --- /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 000000000..7790932ae --- /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 000000000..dc738071d --- /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 000000000..605c1ce6c --- /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_CONFIGURATIONS.rst b/Help/prop_tgt/IMPORTED_CONFIGURATIONS.rst new file mode 100644 index 000000000..6de1baa23 --- /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_IMPLIB.rst b/Help/prop_tgt/IMPORTED_IMPLIB.rst new file mode 100644 index 000000000..acf4b321f --- /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 000000000..b4b3f0228 --- /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 000000000..1943dbaaa --- /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 000000000..a28b83882 --- /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 000000000..2db2b0e58 --- /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 000000000..ee243c75d --- /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 000000000..5ca9c8b6f --- /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 000000000..d4a10fbdd --- /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 000000000..61134a401 --- /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 000000000..13b93ba98 --- /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 000000000..3a86b9985 --- /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 000000000..33b9b8419 --- /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 000000000..8cfef7343 --- /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 OS X this is the location of the executable file inside +Contents/MacOS under the application bundle folder. For static +libraries and modules this is the location of the library or module. +For shared libraries on non-DLL platforms this is the location of the +shared library. For frameworks on OS X this is the location of the +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 000000000..f85bb19c9 --- /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 000000000..4a1bb447a --- /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 000000000..22d68220c --- /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 000000000..222e6cc02 --- /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 000000000..4419ed1d1 --- /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 000000000..d80907e3e --- /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 000000000..6ec9af3f8 --- /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 000000000..deede9788 --- /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 000000000..bd0125037 --- /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 000000000..8b40d9c34 --- /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 000000000..a67ec1584 --- /dev/null +++ b/Help/prop_tgt/INSTALL_NAME_DIR.rst @@ -0,0 +1,8 @@ +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. diff --git a/Help/prop_tgt/INSTALL_RPATH.rst b/Help/prop_tgt/INSTALL_RPATH.rst new file mode 100644 index 000000000..6206b6889 --- /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 000000000..f0006f85b --- /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 000000000..e97d29318 --- /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 000000000..4188b8dae --- /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 000000000..c74a31901 --- /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 000000000..31b594f82 --- /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 000000000..7f0b38534 --- /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 000000000..b1c40b224 --- /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_LIBRARIES.rst b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst new file mode 100644 index 000000000..832d12bbc --- /dev/null +++ b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst @@ -0,0 +1,24 @@ +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. + +Creating Relocatable Packages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. |INTERFACE_PROPERTY_LINK| replace:: ``INTERFACE_LINK_LIBRARIES`` +.. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.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 000000000..ea700dfe9 --- /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 000000000..a224b6859 --- /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 000000000..a0a97ada7 --- /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 000000000..3f68c3128 --- /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 000000000..782b0f0a6 --- /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 000000000..59f67a7eb --- /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 000000000..5d8e94038 --- /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 000000000..653533371 --- /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 000000000..5e464696d --- /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 000000000..2887e235d --- /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 000000000..0fe0b31e5 --- /dev/null +++ b/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst @@ -0,0 +1,13 @@ +<LANG>_COMPILER_LAUNCHER +------------------------ + +This property is implemented only when ``<LANG>`` is ``C`` or ``CXX``. + +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_CPPLINT.rst b/Help/prop_tgt/LANG_CPPLINT.rst new file mode 100644 index 000000000..14f47d465 --- /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 000000000..26f6d1671 --- /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 000000000..5d34e207e --- /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 000000000..785a57bbf --- /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 000000000..28dd404df --- /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 000000000..6027f7f73 --- /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 000000000..1994c7b16 --- /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 000000000..b1ca86710 --- /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 000000000..5576b85fa --- /dev/null +++ b/Help/prop_tgt/LINK_DEPENDS.rst @@ -0,0 +1,12 @@ +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 ignored by non-Makefile generators. It is intended +to specify dependencies on "linker scripts" for custom Makefile link +rules. 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 000000000..5c6778d24 --- /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_FLAGS.rst b/Help/prop_tgt/LINK_FLAGS.rst new file mode 100644 index 000000000..409d00a29 --- /dev/null +++ b/Help/prop_tgt/LINK_FLAGS.rst @@ -0,0 +1,8 @@ +LINK_FLAGS +---------- + +Additional flags to use when linking this target. + +The LINK_FLAGS property can be used to add extra flags to the link +step of a target. LINK_FLAGS_<CONFIG> will add to the configuration +<CONFIG>, for example, DEBUG, RELEASE, MINSIZEREL, RELWITHDEBINFO. diff --git a/Help/prop_tgt/LINK_FLAGS_CONFIG.rst b/Help/prop_tgt/LINK_FLAGS_CONFIG.rst new file mode 100644 index 000000000..ba7adc84f --- /dev/null +++ b/Help/prop_tgt/LINK_FLAGS_CONFIG.rst @@ -0,0 +1,6 @@ +LINK_FLAGS_<CONFIG> +------------------- + +Per-configuration linker flags for a target. + +This is the configuration-specific version of LINK_FLAGS. diff --git a/Help/prop_tgt/LINK_INTERFACE_LIBRARIES.rst b/Help/prop_tgt/LINK_INTERFACE_LIBRARIES.rst new file mode 100644 index 000000000..2dcf45cbd --- /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 000000000..22ee5a68b --- /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 000000000..4e26388a9 --- /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 000000000..5ea4a45cf --- /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 000000000..aa4b9f55f --- /dev/null +++ b/Help/prop_tgt/LINK_LIBRARIES.rst @@ -0,0 +1,17 @@ +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. 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 000000000..cf9c87147 --- /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 000000000..2e0f9bd33 --- /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 000000000..32d6edb07 --- /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 000000000..16d5696e5 --- /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 000000000..ac6bdb786 --- /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 000000000..7cd80462a --- /dev/null +++ b/Help/prop_tgt/MACOSX_BUNDLE.rst @@ -0,0 +1,12 @@ +MACOSX_BUNDLE +------------- + +Build an executable as an Application Bundle on OS X or iOS. + +When this property is set to ``TRUE`` the executable when built on OS X +or iOS will be created as an application bundle. This makes it +a GUI executable that can be launched from the Finder. See the +:prop_tgt:`MACOSX_FRAMEWORK_INFO_PLIST` target property for information about +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 000000000..8515accc2 --- /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 OS X and iOS Application Bundle. + +An executable target with :prop_tgt:`MACOSX_BUNDLE` enabled will be built as an +application bundle on OS X. By default its ``Info.plist`` file is created +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 000000000..58f31d495 --- /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 OS X and iOS Framework. + +A library target with :prop_tgt:`FRAMEWORK` enabled will be built as a +framework on OS X. By default its ``Info.plist`` file is created by +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 000000000..1f9a036bf --- /dev/null +++ b/Help/prop_tgt/MACOSX_RPATH.rst @@ -0,0 +1,23 @@ +MACOSX_RPATH +------------ + +Whether this target on OS X 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 000000000..c12ea147c --- /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 000000000..266ccf078 --- /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 000000000..ddd84f23c --- /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 000000000..ee45ed849 --- /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 000000000..070dd3018 --- /dev/null +++ b/Help/prop_tgt/NO_SYSTEM_FROM_IMPORTED.rst @@ -0,0 +1,11 @@ +NO_SYSTEM_FROM_IMPORTED +----------------------- + +Do not treat includes from IMPORTED target interfaces as SYSTEM. + +The contents of the INTERFACE_INCLUDE_DIRECTORIES of IMPORTED targets +are treated as SYSTEM includes by default. If this property is +enabled, the contents of the INTERFACE_INCLUDE_DIRECTORIES of IMPORTED +targets are not treated as system includes. This property is +initialized by the value of the variable CMAKE_NO_SYSTEM_FROM_IMPORTED +if it is set when a target is created. diff --git a/Help/prop_tgt/OSX_ARCHITECTURES.rst b/Help/prop_tgt/OSX_ARCHITECTURES.rst new file mode 100644 index 000000000..cefe03f5b --- /dev/null +++ b/Help/prop_tgt/OSX_ARCHITECTURES.rst @@ -0,0 +1,11 @@ +OSX_ARCHITECTURES +----------------- + +Target specific architectures for OS X. + +The ``OSX_ARCHITECTURES`` property sets the target binary architecture for +targets on OS X (``-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 000000000..fb78177fb --- /dev/null +++ b/Help/prop_tgt/OSX_ARCHITECTURES_CONFIG.rst @@ -0,0 +1,7 @@ +OSX_ARCHITECTURES_<CONFIG> +-------------------------- + +Per-configuration OS X 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 000000000..f1bdb7c88 --- /dev/null +++ b/Help/prop_tgt/OUTPUT_NAME.rst @@ -0,0 +1,21 @@ +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. + +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 000000000..41b782f98 --- /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 000000000..3a6579669 --- /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 000000000..cb3121c2f --- /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 000000000..b5ada07c9 --- /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 000000000..730cf5776 --- /dev/null +++ b/Help/prop_tgt/PDB_OUTPUT_DIRECTORY.rst @@ -0,0 +1,13 @@ +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. 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 000000000..6037fa0c7 --- /dev/null +++ b/Help/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG.rst @@ -0,0 +1,15 @@ +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. + +.. |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 000000000..54af8c6de --- /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 000000000..f1adb40b7 --- /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 000000000..a16510461 --- /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 000000000..113d7c56a --- /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 000000000..c4412ed25 --- /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 OS X, 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 000000000..a1491ee13 --- /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 000000000..d4a636caf --- /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 OS X, 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 000000000..d837f7b33 --- /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 OS X and iOS is supported) +or normal shared libraries on other platforms. +This property may be set to a list of files to be placed in the corresponding +directory (eg. ``Resources`` directory for OS X) inside the bundle. +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 OS X 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 000000000..e92ab86af --- /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 000000000..2db03177f --- /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 000000000..f33003367 --- /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 000000000..12390f50a --- /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 000000000..94fb2776a --- /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 000000000..11729c3a5 --- /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 000000000..b6a31bfdf --- /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 000000000..a91fa9ca3 --- /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 000000000..493643e84 --- /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 000000000..b25813bff --- /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 000000000..82b6b976a --- /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. OS X, 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 000000000..d3b2cd478 --- /dev/null +++ b/Help/prop_tgt/STATIC_LIBRARY_FLAGS.rst @@ -0,0 +1,6 @@ +STATIC_LIBRARY_FLAGS +-------------------- + +Extra flags to use when linking static libraries. + +Extra flags to use when linking a static library. 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 000000000..cca353ddc --- /dev/null +++ b/Help/prop_tgt/STATIC_LIBRARY_FLAGS_CONFIG.rst @@ -0,0 +1,6 @@ +STATIC_LIBRARY_FLAGS_<CONFIG> +----------------------------- + +Per-configuration flags for creating a static library. + +This is the configuration-specific version of STATIC_LIBRARY_FLAGS. diff --git a/Help/prop_tgt/SUFFIX.rst b/Help/prop_tgt/SUFFIX.rst new file mode 100644 index 000000000..70844be5c --- /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 000000000..5ac63cc37 --- /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, 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 000000000..66e7bde71 --- /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. OS X, 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 000000000..adbbc7103 --- /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 000000000..ff987ffb8 --- /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_WORKING_DIRECTORY.rst b/Help/prop_tgt/VS_DEBUGGER_WORKING_DIRECTORY.rst new file mode 100644 index 000000000..0af85cbdc --- /dev/null +++ b/Help/prop_tgt/VS_DEBUGGER_WORKING_DIRECTORY.rst @@ -0,0 +1,6 @@ +VS_DEBUGGER_WORKING_DIRECTORY +----------------------------- + +Sets the local debugger working directory for Visual Studio C++ targets. +This is defined in ``<LocalDebuggerWorkingDirectory>`` in the Visual Studio +project file. 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 000000000..19d162049 --- /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_REFERENCES.rst b/Help/prop_tgt/VS_DOTNET_REFERENCES.rst new file mode 100644 index 000000000..a661ad926 --- /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 000000000..7641ba5ff --- /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 000000000..581400532 --- /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 000000000..829d696d5 --- /dev/null +++ b/Help/prop_tgt/VS_DOTNET_TARGET_FRAMEWORK_VERSION.rst @@ -0,0 +1,7 @@ +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". diff --git a/Help/prop_tgt/VS_GLOBAL_KEYWORD.rst b/Help/prop_tgt/VS_GLOBAL_KEYWORD.rst new file mode 100644 index 000000000..ce49316d8 --- /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 000000000..f4d9efc8e --- /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 000000000..a23c54005 --- /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 000000000..56b8021be --- /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 000000000..27c8a3df3 --- /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 000000000..add50cb24 --- /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 000000000..6c2e0420e --- /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 000000000..be3c9a018 --- /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 000000000..054f59e3a --- /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 000000000..b5b7721c5 --- /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 000000000..6d7f628d9 --- /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 000000000..80475af1f --- /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 000000000..769a0d1d5 --- /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 000000000..1be222ba6 --- /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 000000000..1ad7a7164 --- /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 000000000..e160bd64b --- /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 000000000..d1cba3471 --- /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 000000000..af98b2f7b --- /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 000000000..336d5f7f3 --- /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 000000000..86711bf29 --- /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 000000000..7e00ac430 --- /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 000000000..dc9290217 --- /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 000000000..f4ef5c0ce --- /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/XCTEST.rst b/Help/prop_tgt/XCTEST.rst new file mode 100644 index 000000000..eb47e606f --- /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 000000000..3ae54484a --- /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 000000000..126f39198 --- /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 000000000..d02f94093 --- /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 libraies 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 000000000..dca42cdcd --- /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 :module:`CPackIFW` module. + +* :manual:`cpack(1)` gained ``7Z`` and ``TXZ`` generators supporting + lzma-compressed archives. + +* The :module:`CPackDeb` module 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.2.rst b/Help/release/3.2.rst new file mode 100644 index 000000000..8abb1ca62 --- /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 :module:`CPackRPM` module learned options to set per-component + descriptions and summaries. See the + :variable:`CPACK_RPM_<component>_PACKAGE_DESCRIPTION` and + :variable:`CPACK_RPM_<component>_PACKAGE_SUMMARY` variables. + +* The :module:`CPackRPM` module learned options to specify + requirements for pre- and post-install scripts. See the + :variable:`CPACK_RPM_PACKAGE_REQUIRES_PRE` and + :variable:`CPACK_RPM_PACKAGE_REQUIRES_POST` variables. + +* The :module:`CPackRPM` module learned options to specify + requirements for pre- and post-uninstall scripts. See the + :variable:`CPACK_RPM_PACKAGE_REQUIRES_PREUN` and + :variable:`CPACK_RPM_PACKAGE_REQUIRES_POSTUN` variables. + +* The :module:`CPackRPM` module learned a new + :variable:`CPACK_RPM_<COMPONENT>_PACKAGE_PREFIX` variable to + specify a component-specific value to use instead of + :variable:`CPACK_PACKAGING_INSTALL_PREFIX`. + +* The :module:`CPackRPM` module learned a new + :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 000000000..0beb354ac --- /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 :manual:`cpack(1)` ``IFW`` generator and the :module:`CPackIFW` + module learned to support Qt Framework Installer 2.0 tools. + +* The :module:`CPackDeb` module learned a new + :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS` + variable to specify per-component use of ``dpkg-shlibdeps``. + +* The :module:`CPackDeb` module learned a new + :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS` + option to specify per-component dependencies. + +* The :module:`CPackRPM` module learned to package symbolic links + more cleanly and now supports directory symlinks with recent + ``rpmbuild`` versions. + +* The :module:`CPackRPM` module learned a new + :variable:`CPACK_RPM_ADDITIONAL_MAN_DIRS` variable to specify + directories containing man pages for the brp-compress RPM macro. + +* The :module:`CPackRPM` module learned a new + :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 000000000..89c5561d3 --- /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 additonal + 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 :module:`CPackDeb` module 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 :module:`CPackDeb` module now correctly excludes symlinks during package + checksum calculation. + +* The :module:`CPackDeb` 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 000000000..009eb3c7c --- /dev/null +++ b/Help/release/3.5.rst @@ -0,0 +1,185 @@ +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 :module:`CPackDMG` module learned new variable to specify AppleScript + file run to customize appearance of ``DragNDrop`` installer folder, + including background image setting using supplied PNG or multi-resolution + TIFF file. See the :variable:`CPACK_DMG_DS_STORE_SETUP_SCRIPT` and + :variable:`CPACK_DMG_BACKGROUND_IMAGE` variables. + +* The :module:`CPackDeb` module learned to set the optional config + file ``Source`` field using a monolithic or per-component variable. + See :variable:`CPACK_DEBIAN_PACKAGE_SOURCE`. + +* The :module:`CPackDeb` module learned to set Package, Section + and Priority control fields per-component. + See variables :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_SECTION` and + :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_PRIORITY`. + +* The :module:`CPack DragNDrop generator <CPackDMG>` learned to add + multi-lingual SLAs to a DMG which is presented to the user when they try to + mount the DMG. See the :variable:`CPACK_DMG_SLA_LANGUAGES` and + :variable:`CPACK_DMG_SLA_DIR` variables for details. + +* The :module:`CPackNSIS` module learned new variables to add bitmaps to the + installer. See the :variable:`CPACK_NSIS_MUI_WELCOMEFINISHPAGE_BITMAP` + and :variable:`CPACK_NSIS_MUI_UNWELCOMEFINISHPAGE_BITMAP` variables. + +* The :module:`CPackRPM` module 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 000000000..144537de0 --- /dev/null +++ b/Help/release/3.6.rst @@ -0,0 +1,316 @@ +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 initalized 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 :module:`CPackDeb` module learned how to handle ``$ORIGIN`` + in ``CMAKE_INSTALL_RPATH`` when :variable:`CPACK_DEBIAN_PACKAGE_SHLIBDEPS` + is used for dependency auto detection. + +* The :module:`CPackDeb` module learned how to generate ``DEBIAN/shlibs`` + contorl file when package contains shared libraries. + +* The :module:`CPackDeb` module learned how to generate ``DEBIAN/postinst`` and + ``DEBIAN/postrm`` files if the package installs libraries in + ldconfig-controlled locations (e.g. ``/lib/``, ``/usr/lib/``). + +* The :module:`CPackDeb` module learned how to generate dependencies between + Debian packages if multi-component setup is used and + :variable:`CPACK_COMPONENT_<compName>_DEPENDS` variables are set. + For backward compatibility this feature is disabled by default. + See :variable:`CPACK_DEBIAN_ENABLE_COMPONENT_DEPENDS`. + +* The :module:`CPackDeb` module learned how to set custom package file names + including how to generate properly-named Debian packages:: + + <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 :module:`CPackDeb` module learned how to set the package release number + (``DebianRevisionNumber`` in package file name when used in combination with + ``DEB-DEFAULT`` value set by :variable:`CPACK_DEBIAN_FILE_NAME`). See + :variable:`CPACK_DEBIAN_PACKAGE_RELEASE`. + +* The :module:`CPackDeb` module learned how to set the package architecture + per-component. See :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_ARCHITECTURE`. + +* The :module:`CPackDMG` module learned a new option to tell the CPack + ``DragNDrop`` generaor to skip the ``/Applications`` symlink. + See the :variable:`CPACK_DMG_DISABLE_APPLICATIONS_SYMLINK` variable. + +* The :module:`CPackIFW` module gained a new + :command:`cpack_ifw_update_repository` command to update a QtIFW-specific + repository from a remote repository. + +* The :module:`CPackRPM` module learned how to set RPM ``dist`` tag as part of + RPM ``Release:`` tag when enabled (mandatory on some Linux distributions for + e.g. on Fedora). + See :variable:`CPACK_RPM_PACKAGE_RELEASE_DIST`. + +* The :module:`CPackRPM` module learned how to set default values for owning + user/group and file/directory permissions of package content. + See :variable:`CPACK_RPM_DEFAULT_USER`, :variable:`CPACK_RPM_DEFAULT_GROUP`, + :variable:`CPACK_RPM_DEFAULT_FILE_PERMISSIONS`, + :variable:`CPACK_RPM_DEFAULT_DIR_PERMISSIONS` and their per component + counterparts. + +* The :module:`CPackRPM` module learned how to set user defined package file + names, how to specify that rpmbuild should decide on file name format as + well as handling of multiple rpm packages generated by a single user defined + spec file. + See :variable:`CPACK_RPM_PACKAGE_NAME` and + :variable:`CPACK_RPM_<component>_PACKAGE_NAME`. + +* The :module:`CPackRPM` module 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 :module:`CPackRPM` module 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 000000000..4c51af43e --- /dev/null +++ b/Help/release/3.7.rst @@ -0,0 +1,320 @@ +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 ``productbuild`` generator on OS X, configured by + the :module:`CPackProductBuild` module. + +* CPack gained a new :variable:`CPACK_PACKAGE_CHECKSUM` variable to + enable generation of a checksum file for each package file. + +* The :module:`CPackDeb` module learned to support long file names + 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 additonal pages to the IFW + installer. + +* The :module:`CPackRPM` module learned to generate debuginfo + packages on demand. See :variable:`CPACK_RPM_DEBUGINFO_PACKAGE` + and its per component version. + +* The :module:`CPackRPM` module learned to generate source rpm + (SRPM) packages on demand. See :variable:`CPACK_RPM_PACKAGE_SOURCES`, + :variable:`CPACK_RPM_SOURCE_PKG_BUILD_PARAMS` and + :variable:`CPACK_RPM_SOURCE_PKG_PACKAGING_INSTALL_PREFIX`. + +* The CPack NSIS generator now supports + :variable:`CPACK_NSIS_<compName>_INSTALL_DIRECTORY`. + This can be used to set component specific installation directories. + +* The CPack WIX generator now supports + :variable:`CPACK_WIX_SKIP_PROGRAM_FOLDER` to allow specification + of a custom absolute installation prefix outside + of the ProgramFiles folders. + +* The CPack WIX generator now supports + :variable:`CPACK_COMPONENT_<compName>_DISABLED`. + This can be used to deselect a component from being installed by default. + +* The CPack WIX generator now supports :variable:`CPACK_WIX_PATCH_FILE` + fragments for Feature elements. + +* The CPack 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 000000000..efb2aa5a7 --- /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 :module:`CPackIFW` module 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 :module:`CPackProductBuild` module gained options to sign packages. + See the variables :variable:`CPACK_PRODUCTBUILD_IDENTITY_NAME`, + :variable:`CPACK_PRODUCTBUILD_KEYCHAIN_PATH`, + :variable:`CPACK_PKGBUILD_IDENTITY_NAME`, and + :variable:`CPACK_PKGBUILD_KEYCHAIN_PATH`. + +* The :module:`CPackRPM` module learned to omit tags that are not supported by + provided ``rpmbuild`` tool. If unsupported tags are set they are ignored + and a developer warning is printed out. + +* The :module:`CPackRPM` module learned to generate main component package + which forces generation of a rpm for defined component without component + suffix in filename and package name. + See :variable:`CPACK_RPM_MAIN_COMPONENT` variable. + +* The :module:`CPackRPM` module learned to generate a single ``debuginfo`` + package on demand even if components packaging is used. + See :variable:`CPACK_RPM_DEBUGINFO_SINGLE_PACKAGE` variable. + +* The :module:`CPackRPM` module 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 000000000..897e268b5 --- /dev/null +++ b/Help/release/3.9.rst @@ -0,0 +1,342 @@ +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 :module:`CPackArchive` module 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 :module:`CPackIFW` module learned the new hint :variable:`CPACK_IFW_ROOT` + variable for finding the QtIFW tool suite installed in a non-standard place. + +* The :module:`CPackProductBuild` module gained a new + :variable:`CPACK_PRODUCTBUILD_RESOURCES_DIR` variable to + specify resources to be copied into the ``Resources`` + directory. + +* The :module:`CPackRPM` module learned to modify the ``debuginfo`` package + name. See the :variable:`CPACK_RPM_DEBUGINFO_FILE_NAME` variable. + +* The :module:`CPackWIX` module patching system now has the ability to set + additional attributes. This can be done by specifying attributes with + the ``CPackWiXFragment`` XML tag after the ``Id`` attribute. + See the :variable:`CPACK_WIX_PATCH_FILE` variable. + +* The 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 000000000..2cf9193e1 --- /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/index.rst b/Help/release/index.rst new file mode 100644 index 000000000..6af282cff --- /dev/null +++ b/Help/release/index.rst @@ -0,0 +1,25 @@ +:orphan: + +CMake Release Notes +******************* + +.. + This file should include the adjacent "dev.txt" file + in development versions but not in release versions. + +Releases +======== + +.. toctree:: + :maxdepth: 1 + + 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 000000000..fede4caf3 --- /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 000000000..75eecf183 --- /dev/null +++ b/Help/variable/APPLE.rst @@ -0,0 +1,6 @@ +APPLE +----- + +``True`` if running on OS X. + +Set to ``true`` on OS X. diff --git a/Help/variable/BORLAND.rst b/Help/variable/BORLAND.rst new file mode 100644 index 000000000..badb7338e --- /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 000000000..53087b23b --- /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/CMAKE_ABSOLUTE_DESTINATION_FILES.rst b/Help/variable/CMAKE_ABSOLUTE_DESTINATION_FILES.rst new file mode 100644 index 000000000..b6d00543a --- /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 000000000..8862ba91d --- /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 000000000..c07a05a64 --- /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 000000000..0246c75b9 --- /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 000000000..b91ca57a3 --- /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 000000000..0a3ed3c16 --- /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 000000000..ad3c37c86 --- /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 000000000..4b7ae0397 --- /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 000000000..c372fe449 --- /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 000000000..175537527 --- /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 000000000..451a92960 --- /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 000000000..af83e3430 --- /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 000000000..3dc05e05e --- /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 000000000..4191907d4 --- /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 000000000..7cb95274e --- /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 000000000..d241dd000 --- /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 000000000..8ea12578c --- /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 000000000..207019a7f --- /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 000000000..5ae55d15b --- /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 000000000..19fb527f7 --- /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 000000000..b8fdd46cc --- /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 000000000..8dea00907 --- /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 000000000..69a4d0b56 --- /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 000000000..0a96df9fa --- /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 000000000..ea62cabf6 --- /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 000000000..cfb76aa04 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_STL_TYPE.rst @@ -0,0 +1,36 @@ +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``. 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 000000000..2bc79ac3a --- /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 OS X 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 000000000..5893677ff --- /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 000000000..c88932164 --- /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 000000000..94c2b6efa --- /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 000000000..aec97119a --- /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 000000000..8b1ecb79e --- /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_AUTOMOC.rst b/Help/variable/CMAKE_AUTOMOC.rst new file mode 100644 index 000000000..02e5eb57a --- /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_DEPEND_FILTERS.rst b/Help/variable/CMAKE_AUTOMOC_DEPEND_FILTERS.rst new file mode 100644 index 000000000..5c3662d9a --- /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_MOC_OPTIONS.rst b/Help/variable/CMAKE_AUTOMOC_MOC_OPTIONS.rst new file mode 100644 index 000000000..09bf5cd2f --- /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 000000000..addc62de4 --- /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 000000000..742610541 --- /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 000000000..298cb6be7 --- /dev/null +++ b/Help/variable/CMAKE_AUTORCC_OPTIONS.rst @@ -0,0 +1,7 @@ +CMAKE_AUTORCC_OPTIONS +--------------------- + +Whether to handle ``rcc`` automatically for Qt targets. + +This variable is used to initialize the :prop_tgt:`AUTORCC_OPTIONS` property on +all the targets. See that target property for additional information. diff --git a/Help/variable/CMAKE_AUTOUIC.rst b/Help/variable/CMAKE_AUTOUIC.rst new file mode 100644 index 000000000..5abefaab8 --- /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 000000000..3c9b8c4f5 --- /dev/null +++ b/Help/variable/CMAKE_AUTOUIC_OPTIONS.rst @@ -0,0 +1,7 @@ +CMAKE_AUTOUIC_OPTIONS +--------------------- + +Whether to handle ``uic`` automatically for Qt targets. + +This variable is used to initialize the :prop_tgt:`AUTOUIC_OPTIONS` property on +all the targets. See that target property for additional information. diff --git a/Help/variable/CMAKE_AUTOUIC_SEARCH_PATHS.rst b/Help/variable/CMAKE_AUTOUIC_SEARCH_PATHS.rst new file mode 100644 index 000000000..aa132bf77 --- /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 000000000..05c366a95 --- /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 000000000..3b323b7ae --- /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 000000000..f20eb418f --- /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 000000000..61334917b --- /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 000000000..2d54d6049 --- /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`` and ``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 000000000..30d5d3bd6 --- /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 000000000..5b59a6ef2 --- /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 000000000..8604d0e8c --- /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 000000000..1e53ed62d --- /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 000000000..5d174a3c9 --- /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 000000000..22d267c98 --- /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 000000000..c36599adf --- /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 8, 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 000000000..4e80d1fe2 --- /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_CODELITE_USE_TARGETS.rst b/Help/variable/CMAKE_CODELITE_USE_TARGETS.rst new file mode 100644 index 000000000..33cdf6ca6 --- /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 000000000..bb86eccc5 --- /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 000000000..f80b46cb5 --- /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 000000000..134559b6c --- /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 000000000..a40667e80 --- /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 000000000..f1f5cf797 --- /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 000000000..3d6dab44c --- /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 000000000..ea33c7d64 --- /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 000000000..fdeb9abdd --- /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 000000000..34e99ebf7 --- /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 000000000..e686a4338 --- /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_CROSSCOMPILING.rst b/Help/variable/CMAKE_CROSSCOMPILING.rst new file mode 100644 index 000000000..cf9865b61 --- /dev/null +++ b/Help/variable/CMAKE_CROSSCOMPILING.rst @@ -0,0 +1,8 @@ +CMAKE_CROSSCOMPILING +-------------------- + +Is CMake currently cross compiling. + +This variable will be set to true by CMake if CMake is cross +compiling. Specifically if the build platform is different from the +target platform. diff --git a/Help/variable/CMAKE_CROSSCOMPILING_EMULATOR.rst b/Help/variable/CMAKE_CROSSCOMPILING_EMULATOR.rst new file mode 100644 index 000000000..95d2c7ffc --- /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 000000000..b2942e2a8 --- /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 000000000..4fe758e90 --- /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_STANDARD.rst b/Help/variable/CMAKE_CUDA_STANDARD.rst new file mode 100644 index 000000000..6c23031ce --- /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 000000000..935d60583 --- /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 000000000..768f571c0 --- /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 000000000..40496b5d9 --- /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 000000000..ebc3ab9c9 --- /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 000000000..84b0eeeba --- /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 000000000..60e8e26ce --- /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 000000000..c1b755a0e --- /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 000000000..5c59f9503 --- /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 000000000..4a92425e6 --- /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 000000000..8a8bdff29 --- /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 000000000..4c710580a --- /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 000000000..8d1eca06a --- /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 000000000..fa510d4a8 --- /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 000000000..b55e00cd9 --- /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 000000000..7f70f6edb --- /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 000000000..08577a5c8 --- /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 000000000..513276e57 --- /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 000000000..717907145 --- /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_DISABLE_FIND_PACKAGE_PackageName.rst b/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst new file mode 100644 index 000000000..ed600202c --- /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 000000000..50d313d8d --- /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_ECLIPSE_GENERATE_LINKED_RESOURCES.rst b/Help/variable/CMAKE_ECLIPSE_GENERATE_LINKED_RESOURCES.rst new file mode 100644 index 000000000..331aae877 --- /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 000000000..7b4367d19 --- /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 000000000..6e8a40887 --- /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 000000000..8cc7882d9 --- /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 000000000..2f4ab1f62 --- /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 000000000..9a877e7e6 --- /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 OS X, the +module will ``link`` to the executable using a flag like +``-bundle_loader``. For other non-DLL platforms the link rule is simply +ignored since the dynamic loader will automatically bind symbols when +the module is loaded. + +This variable is used to initialize the target property +:prop_tgt:`ENABLE_EXPORTS` for executable targets. diff --git a/Help/variable/CMAKE_ERROR_DEPRECATED.rst b/Help/variable/CMAKE_ERROR_DEPRECATED.rst new file mode 100644 index 000000000..f3a673827 --- /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 000000000..38e9b7b36 --- /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 000000000..356590f6f --- /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 000000000..9e108f83f --- /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 000000000..0cd8113aa --- /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 000000000..592a36973 --- /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 000000000..0b8afe4fe --- /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 000000000..8776279e8 --- /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 000000000..ee109ba1a --- /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 000000000..4d513e474 --- /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 or KDevelop 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 000000000..a130adbee --- /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 000000000..e0727b547 --- /dev/null +++ b/Help/variable/CMAKE_FIND_APPBUNDLE.rst @@ -0,0 +1,22 @@ +CMAKE_FIND_APPBUNDLE +-------------------- + +This variable affects how ``find_*`` commands choose between +OS X Application Bundles and unix-style package components. + +On Darwin or systems supporting OS X 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 000000000..790694ac5 --- /dev/null +++ b/Help/variable/CMAKE_FIND_FRAMEWORK.rst @@ -0,0 +1,22 @@ +CMAKE_FIND_FRAMEWORK +-------------------- + +This variable affects how ``find_*`` commands choose between +OS X Frameworks and unix-style package components. + +On Darwin or systems supporting OS X 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 000000000..ada89559f --- /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 000000000..58354b2b2 --- /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 000000000..4a64e33e9 --- /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 000000000..c49d2641b --- /dev/null +++ b/Help/variable/CMAKE_FIND_NO_INSTALL_PREFIX.rst @@ -0,0 +1,15 @@ +CMAKE_FIND_NO_INSTALL_PREFIX +---------------------------- + +Ignore the :variable:`CMAKE_INSTALL_PREFIX` when searching for assets. + +CMake adds the :variable:`CMAKE_INSTALL_PREFIX` and the +:variable:`CMAKE_STAGING_PREFIX` variable to the +:variable:`CMAKE_SYSTEM_PREFIX_PATH` by default. This variable may be set +on the command line to control that behavior. + +Set ``CMAKE_FIND_NO_INSTALL_PREFIX`` to ``TRUE`` to tell +:command:`find_package` not to search in the :variable:`CMAKE_INSTALL_PREFIX` +or :variable:`CMAKE_STAGING_PREFIX` by default. Note that the +prefix may still be searched for other reasons, such as being the same prefix +as the CMake installation, or for being a built-in system prefix. diff --git a/Help/variable/CMAKE_FIND_PACKAGE_NAME.rst b/Help/variable/CMAKE_FIND_PACKAGE_NAME.rst new file mode 100644 index 000000000..bd1a30f52 --- /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 000000000..90584710e --- /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 000000000..44588b17a --- /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 000000000..99e4ec125 --- /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 000000000..ba5f3a8c7 --- /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 000000000..f1116bb62 --- /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 000000000..ba2cf313e --- /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 000000000..df1af5a88 --- /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 000000000..52ab89dc5 --- /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 000000000..387294797 --- /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 000000000..d24a78a3f --- /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 000000000..ab65e090e --- /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_FRAMEWORK_PATH.rst b/Help/variable/CMAKE_FRAMEWORK_PATH.rst new file mode 100644 index 000000000..5ff08e679 --- /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 OS X 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 000000000..1406e59b1 --- /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 000000000..5aeab0757 --- /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 000000000..1da55cade --- /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 000000000..2f8388017 --- /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 000000000..3c7edc1cf --- /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 000000000..cce04c136 --- /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_PLATFORM.rst b/Help/variable/CMAKE_GENERATOR_PLATFORM.rst new file mode 100644 index 000000000..50412ffff --- /dev/null +++ b/Help/variable/CMAKE_GENERATOR_PLATFORM.rst @@ -0,0 +1,28 @@ +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. + +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 000000000..11c37d746 --- /dev/null +++ b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst @@ -0,0 +1,50 @@ +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 + +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. diff --git a/Help/variable/CMAKE_GNUtoMS.rst b/Help/variable/CMAKE_GNUtoMS.rst new file mode 100644 index 000000000..9c0f59e22 --- /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 000000000..fdc5d8190 --- /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 000000000..ac7b03004 --- /dev/null +++ b/Help/variable/CMAKE_HOST_APPLE.rst @@ -0,0 +1,6 @@ +CMAKE_HOST_APPLE +---------------- + +``True`` for Apple OS X operating systems. + +Set to ``true`` when the host system is Apple OS X. diff --git a/Help/variable/CMAKE_HOST_SOLARIS.rst b/Help/variable/CMAKE_HOST_SOLARIS.rst new file mode 100644 index 000000000..82b5d69cd --- /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 000000000..c2a8f1a5f --- /dev/null +++ b/Help/variable/CMAKE_HOST_SYSTEM.rst @@ -0,0 +1,10 @@ +CMAKE_HOST_SYSTEM +----------------- + +Composit 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 000000000..c67359272 --- /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 OS X +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 000000000..ba8a850cd --- /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 000000000..ed230704c --- /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 000000000..817a957e9 --- /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 000000000..876b34c3a --- /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 000000000..92f377086 --- /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 000000000..1561a1db9 --- /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 000000000..11aeab7e6 --- /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 000000000..6eea322f8 --- /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 000000000..5fc95f00b --- /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 000000000..e0f2a2e55 --- /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 000000000..37d0a3d48 --- /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 000000000..e4e7f2cfc --- /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 000000000..57160f1d9 --- /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_MESSAGE.rst b/Help/variable/CMAKE_INSTALL_MESSAGE.rst new file mode 100644 index 000000000..304df268c --- /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 000000000..1f2d62bf6 --- /dev/null +++ b/Help/variable/CMAKE_INSTALL_NAME_DIR.rst @@ -0,0 +1,8 @@ +CMAKE_INSTALL_NAME_DIR +---------------------- + +OS X 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 000000000..7bd87d6aa --- /dev/null +++ b/Help/variable/CMAKE_INSTALL_PREFIX.rst @@ -0,0 +1,37 @@ +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. ``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. + +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 000000000..2a5842d4c --- /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 000000000..813d1e0a7 --- /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 000000000..78148d5f5 --- /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 000000000..9693bf658 --- /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 000000000..b0cbb62b9 --- /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 000000000..b291102de --- /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 000000000..c5cb9b647 --- /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_POOL_COMPILE.rst b/Help/variable/CMAKE_JOB_POOL_COMPILE.rst new file mode 100644 index 000000000..e5c2d9a81 --- /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 000000000..338f7714e --- /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 000000000..d33636481 --- /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 000000000..db04af35b --- /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 000000000..159eb22fa --- /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 000000000..ab4ad7164 --- /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 000000000..fc295af2c --- /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 000000000..1bb5d651d --- /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 000000000..492c12c6d --- /dev/null +++ b/Help/variable/CMAKE_LANG_CLANG_TIDY.rst @@ -0,0 +1,6 @@ +CMAKE_<LANG>_CLANG_TIDY +----------------------- + +Default value for :prop_tgt:`<LANG>_CLANG_TIDY` 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_COMPILER.rst b/Help/variable/CMAKE_LANG_COMPILER.rst new file mode 100644 index 000000000..89df4954e --- /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 000000000..be946c01b --- /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 000000000..b83a1d40c --- /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_EXTERNAL_TOOLCHAIN.rst b/Help/variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN.rst new file mode 100644 index 000000000..5be935bad --- /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 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 000000000..0fab10ca8 --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_ID.rst @@ -0,0 +1,37 @@ +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) + 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) + 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 000000000..7961f609e --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst @@ -0,0 +1,6 @@ +CMAKE_<LANG>_COMPILER_LAUNCHER +------------------------------ + +Default value for :prop_tgt:`<LANG>_COMPILER_LAUNCHER` target property. +This variable is used to initialize the property on each target as it is +created. This is done only when ``<LANG>`` is ``C`` or ``CXX``. diff --git a/Help/variable/CMAKE_LANG_COMPILER_LOADED.rst b/Help/variable/CMAKE_LANG_COMPILER_LOADED.rst new file mode 100644 index 000000000..9308878df --- /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_RANLIB.rst b/Help/variable/CMAKE_LANG_COMPILER_RANLIB.rst new file mode 100644 index 000000000..945160b58 --- /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 000000000..656c57d2b --- /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 000000000..27b0cad0d --- /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_COMPILE_OBJECT.rst b/Help/variable/CMAKE_LANG_COMPILE_OBJECT.rst new file mode 100644 index 000000000..ba59cad03 --- /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_CPPLINT.rst b/Help/variable/CMAKE_LANG_CPPLINT.rst new file mode 100644 index 000000000..3b6f45206 --- /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 000000000..be89f8529 --- /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 000000000..ae5f69d56 --- /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 000000000..0cff200d5 --- /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 000000000..c57d92cbf --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS.rst @@ -0,0 +1,6 @@ +CMAKE_<LANG>_FLAGS +------------------ + +Flags for all build types. + +``<LANG>`` flags used regardless of the value of :variable:`CMAKE_BUILD_TYPE`. diff --git a/Help/variable/CMAKE_LANG_FLAGS_DEBUG.rst b/Help/variable/CMAKE_LANG_FLAGS_DEBUG.rst new file mode 100644 index 000000000..a233d4ad7 --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_DEBUG.rst @@ -0,0 +1,6 @@ +CMAKE_<LANG>_FLAGS_DEBUG +------------------------ + +Flags for ``Debug`` build type or configuration. + +``<LANG>`` flags used when :variable:`CMAKE_BUILD_TYPE` is ``Debug``. 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 000000000..dcddb2e26 --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_DEBUG_INIT.rst @@ -0,0 +1,10 @@ +CMAKE_<LANG>_FLAGS_DEBUG_INIT +----------------------------- + +Value used to initialize the :variable:`CMAKE_<LANG>_FLAGS_DEBUG` cache +entry the first time a build tree is configured for language ``<LANG>``. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also :variable:`CMAKE_<LANG>_FLAGS_INIT`. diff --git a/Help/variable/CMAKE_LANG_FLAGS_INIT.rst b/Help/variable/CMAKE_LANG_FLAGS_INIT.rst new file mode 100644 index 000000000..1d32cc3fd --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_INIT.rst @@ -0,0 +1,15 @@ +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 variables: + +* :variable:`CMAKE_<LANG>_FLAGS_DEBUG_INIT` +* :variable:`CMAKE_<LANG>_FLAGS_RELEASE_INIT` +* :variable:`CMAKE_<LANG>_FLAGS_MINSIZEREL_INIT` +* :variable:`CMAKE_<LANG>_FLAGS_RELWITHDEBINFO_INIT` diff --git a/Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL.rst b/Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL.rst new file mode 100644 index 000000000..a9436c184 --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL.rst @@ -0,0 +1,7 @@ +CMAKE_<LANG>_FLAGS_MINSIZEREL +----------------------------- + +Flags for ``MinSizeRel`` build type or configuration. + +``<LANG>`` flags used when :variable:`CMAKE_BUILD_TYPE` is ``MinSizeRel`` +(short for minimum size release). 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 000000000..c0aedf403 --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL_INIT.rst @@ -0,0 +1,10 @@ +CMAKE_<LANG>_FLAGS_MINSIZEREL_INIT +---------------------------------- + +Value used to initialize the :variable:`CMAKE_<LANG>_FLAGS_MINSIZEREL` +cache entry the first time a build tree is configured for language ``<LANG>``. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also :variable:`CMAKE_<LANG>_FLAGS_INIT`. diff --git a/Help/variable/CMAKE_LANG_FLAGS_RELEASE.rst b/Help/variable/CMAKE_LANG_FLAGS_RELEASE.rst new file mode 100644 index 000000000..ffc5d795d --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_RELEASE.rst @@ -0,0 +1,6 @@ +CMAKE_<LANG>_FLAGS_RELEASE +-------------------------- + +Flags for ``Release`` build type or configuration. + +``<LANG>`` flags used when :variable:`CMAKE_BUILD_TYPE` is ``Release``. 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 000000000..59f92ff6f --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_RELEASE_INIT.rst @@ -0,0 +1,10 @@ +CMAKE_<LANG>_FLAGS_RELEASE_INIT +------------------------------- + +Value used to initialize the :variable:`CMAKE_<LANG>_FLAGS_RELEASE` +cache entry the first time a build tree is configured for language ``<LANG>``. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also :variable:`CMAKE_<LANG>_FLAGS_INIT`. diff --git a/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO.rst b/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO.rst new file mode 100644 index 000000000..962768e44 --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO.rst @@ -0,0 +1,7 @@ +CMAKE_<LANG>_FLAGS_RELWITHDEBINFO +--------------------------------- + +Flags for ``RelWithDebInfo`` type or configuration. + +``<LANG>`` flags used when :variable:`CMAKE_BUILD_TYPE` is ``RelWithDebInfo`` +(short for Release With Debug Information). 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 000000000..915f02305 --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT.rst @@ -0,0 +1,10 @@ +CMAKE_<LANG>_FLAGS_RELWITHDEBINFO_INIT +-------------------------------------- + +Value used to initialize the :variable:`CMAKE_<LANG>_FLAGS_RELWITHDEBINFO` +cache entry the first time a build tree is configured for language ``<LANG>``. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also :variable:`CMAKE_<LANG>_FLAGS_INIT`. 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 000000000..1f639a3ba --- /dev/null +++ b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_DEBUG.rst @@ -0,0 +1,6 @@ +CMAKE_<LANG>_GHS_KERNEL_FLAGS_DEBUG +----------------------------------- + +GHS kernel flags for ``Debug`` build type or configuration. + +``<LANG>`` flags used when :variable:`CMAKE_BUILD_TYPE` is ``Debug``. diff --git a/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_MINSIZEREL.rst b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_MINSIZEREL.rst new file mode 100644 index 000000000..94e21150a --- /dev/null +++ b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_MINSIZEREL.rst @@ -0,0 +1,7 @@ +CMAKE_<LANG>_GHS_KERNEL_FLAGS_MINSIZEREL +---------------------------------------- + +GHS kernel flags for ``MinSizeRel`` build type or configuration. + +``<LANG>`` flags used when :variable:`CMAKE_BUILD_TYPE` is ``MinSizeRel`` +(short for minimum size release). diff --git a/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELEASE.rst b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELEASE.rst new file mode 100644 index 000000000..74566efca --- /dev/null +++ b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELEASE.rst @@ -0,0 +1,6 @@ +CMAKE_<LANG>_GHS_KERNEL_FLAGS_RELEASE +------------------------------------- + +GHS kernel flags for ``Release`` build type or configuration. + +``<LANG>`` flags used when :variable:`CMAKE_BUILD_TYPE` is ``Release``. diff --git a/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELWITHDEBINFO.rst b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELWITHDEBINFO.rst new file mode 100644 index 000000000..d148193d8 --- /dev/null +++ b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELWITHDEBINFO.rst @@ -0,0 +1,7 @@ +CMAKE_<LANG>_GHS_KERNEL_FLAGS_RELWITHDEBINFO +-------------------------------------------- + +GHS kernel flags for ``RelWithDebInfo`` type or configuration. + +``<LANG>`` flags used when :variable:`CMAKE_BUILD_TYPE` is ``RelWithDebInfo`` +(short for Release With Debug Information). diff --git a/Help/variable/CMAKE_LANG_IGNORE_EXTENSIONS.rst b/Help/variable/CMAKE_LANG_IGNORE_EXTENSIONS.rst new file mode 100644 index 000000000..3d07e912b --- /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 000000000..cc8085107 --- /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 000000000..a0bd8303c --- /dev/null +++ b/Help/variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES.rst @@ -0,0 +1,17 @@ +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. + +When a library in one of these directories is given by full path to +:command:`target_link_libraries` CMake will generate the ``-l<name>`` form on +link lines to ensure the linker searches its implicit directories for the +library. Note that some toolchains read implicit directories from an +environment variable such as ``LIBRARY_PATH`` so keep its value consistent +when operating in a given build tree. 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 000000000..61ccc5a16 --- /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 000000000..ec164774b --- /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 000000000..2c8028a60 --- /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 000000000..7f888eed7 --- /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 000000000..ff82f8b4c --- /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 000000000..dbbeb0afb --- /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_LINK_EXECUTABLE.rst b/Help/variable/CMAKE_LANG_LINK_EXECUTABLE.rst new file mode 100644 index 000000000..abd589147 --- /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 000000000..0fbc566c1 --- /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 000000000..1b243e39a --- /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 000000000..15c87a186 --- /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 000000000..d6325e06d --- /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 000000000..746592324 --- /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 000000000..e085fee67 --- /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 000000000..c8e3d578c --- /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 000000000..ba6df933a --- /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 000000000..1961ea085 --- /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 000000000..8a7dcbd6d --- /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 000000000..1eb2ac2c8 --- /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 000000000..e97296d5e --- /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 000000000..e069cdd8b --- /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 000000000..b1770dc26 --- /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 000000000..ebe5fda9a --- /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 000000000..fa09f9f9c --- /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 000000000..cec7906a1 --- /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_INTERFACE_LIBRARIES.rst b/Help/variable/CMAKE_LINK_INTERFACE_LIBRARIES.rst new file mode 100644 index 000000000..33865dae3 --- /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 000000000..6858e2c15 --- /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 000000000..b5197e45a --- /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 000000000..0ddafe853 --- /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 000000000..54cdaaa8e --- /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 000000000..0d52a3143 --- /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 000000000..90c4d3ff2 --- /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 000000000..0badaf0da --- /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 000000000..042e807f5 --- /dev/null +++ b/Help/variable/CMAKE_MACOSX_RPATH.rst @@ -0,0 +1,7 @@ +CMAKE_MACOSX_RPATH +------------------- + +Whether to use rpaths on OS X 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 000000000..079ad7068 --- /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 000000000..a3b997af2 --- /dev/null +++ b/Help/variable/CMAKE_MAKE_PROGRAM.rst @@ -0,0 +1,65 @@ +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 ``gbuild``. + If a user or project explicitly adds ``CMAKE_MAKE_PROGRAM`` to + the CMake cache then CMake will use the specified value. + +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 000000000..ed29afe33 --- /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 000000000..355e83405 --- /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 000000000..c7dd62339 --- /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 000000000..5a392bfbb --- /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 000000000..5a51634db --- /dev/null +++ b/Help/variable/CMAKE_MINIMUM_REQUIRED_VERSION.rst @@ -0,0 +1,7 @@ +CMAKE_MINIMUM_REQUIRED_VERSION +------------------------------ + +Version specified to :command:`cmake_minimum_required` command + +Variable containing the ``VERSION`` component specified in the +:command:`cmake_minimum_required` command. diff --git a/Help/variable/CMAKE_MINOR_VERSION.rst b/Help/variable/CMAKE_MINOR_VERSION.rst new file mode 100644 index 000000000..f67cfb955 --- /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 000000000..6372bbdb9 --- /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 000000000..393263ec8 --- /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 000000000..327901409 --- /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 000000000..91b39f6dd --- /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 000000000..5ea7cbbc0 --- /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 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_NINJA_OUTPUT_PATH_PREFIX.rst b/Help/variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX.rst new file mode 100644 index 000000000..64091aaaf --- /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 000000000..98960c520 --- /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 000000000..189f59fa3 --- /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 000000000..61e04b4ca --- /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 000000000..9e30cbbdb --- /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 000000000..93916dd62 --- /dev/null +++ b/Help/variable/CMAKE_OSX_ARCHITECTURES.rst @@ -0,0 +1,10 @@ +CMAKE_OSX_ARCHITECTURES +----------------------- + +Target specific architectures for OS X and iOS. + +This variable is used to initialize the :prop_tgt:`OSX_ARCHITECTURES` +property on each target as it is creaed. See that target property +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 000000000..4fb2caa4f --- /dev/null +++ b/Help/variable/CMAKE_OSX_DEPLOYMENT_TARGET.rst @@ -0,0 +1,13 @@ +CMAKE_OSX_DEPLOYMENT_TARGET +--------------------------- + +Specify the minimum version of OS X on which the target binaries are +to be deployed. CMake uses this value for the ``-mmacosx-version-min`` +flag and to help choose the default SDK +(see :variable:`CMAKE_OSX_SYSROOT`). + +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 000000000..f1d58c6b5 --- /dev/null +++ b/Help/variable/CMAKE_OSX_SYSROOT.rst @@ -0,0 +1,13 @@ +CMAKE_OSX_SYSROOT +----------------- + +Specify the location or name of the OS X 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 000000000..385f871f3 --- /dev/null +++ b/Help/variable/CMAKE_OSX_VARIABLE.txt @@ -0,0 +1,6 @@ +The value of this variable should be set prior to the first +:command:`project` or :command:`enable_language` command invocation +because it may influence configuration of the toolchain and flags. +It is intended to be set locally by the user creating a build tree. + +This variable is ignored on platforms other than OS X. diff --git a/Help/variable/CMAKE_PARENT_LIST_FILE.rst b/Help/variable/CMAKE_PARENT_LIST_FILE.rst new file mode 100644 index 000000000..cfd8608c3 --- /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 000000000..991ae7618 --- /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 000000000..763bcb34f --- /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 000000000..4d18eec5d --- /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 000000000..43582be94 --- /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 000000000..aa23b65f9 --- /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 000000000..43b1397eb --- /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 000000000..c2a4a6038 --- /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 000000000..799e1192c --- /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 000000000..f1911eced --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_DESCRIPTION.rst @@ -0,0 +1,7 @@ +CMAKE_PROJECT_DESCRIPTION +------------------------- + +The description of the current project. + +This specifies description of the current project from the closest inherited +:command:`project` command. diff --git a/Help/variable/CMAKE_PROJECT_NAME.rst b/Help/variable/CMAKE_PROJECT_NAME.rst new file mode 100644 index 000000000..431e9f302 --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_NAME.rst @@ -0,0 +1,7 @@ +CMAKE_PROJECT_NAME +------------------ + +The name of the current project. + +This specifies name of the current project from the closest inherited +:command:`project` command. 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 000000000..ba9df5a34 --- /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 is intended for injecting custom code into project +builds without modifying their source. diff --git a/Help/variable/CMAKE_RANLIB.rst b/Help/variable/CMAKE_RANLIB.rst new file mode 100644 index 000000000..82672e9ae --- /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 000000000..1d0a8af80 --- /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_RUNTIME_OUTPUT_DIRECTORY.rst b/Help/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY.rst new file mode 100644 index 000000000..6253d4a34 --- /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 000000000..080dea667 --- /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 000000000..981af60cf --- /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 000000000..8afabafe5 --- /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 000000000..1f96a328e --- /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 000000000..fce950c75 --- /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 000000000..4bf87a0b6 --- /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 000000000..185df387d --- /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 000000000..cb819a7d9 --- /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 000000000..d6eef9866 --- /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 000000000..81515c3cf --- /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 000000000..f5464d1d4 --- /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 000000000..8da610030 --- /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 000000000..80a68c972 --- /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 000000000..cc0ac21ee --- /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 000000000..44966f32f --- /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 000000000..d7ce8e43d --- /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 000000000..416fbe1a8 --- /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 000000000..1310e9471 --- /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 000000000..714b5cc3b --- /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 000000000..28dc09dd3 --- /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 000000000..9c38673aa --- /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 000000000..b9f8003c7 --- /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 000000000..a49d1cb74 --- /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 000000000..113ca710f --- /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 000000000..02c8663b4 --- /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 000000000..d65442512 --- /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_SYSROOT.rst b/Help/variable/CMAKE_SYSROOT.rst new file mode 100644 index 000000000..64f81bbc2 --- /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 000000000..e96c62b71 --- /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 000000000..88b48eff0 --- /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 000000000..c7d0d8a5d --- /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 000000000..3c6687c6e --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_APPBUNDLE_PATH.rst @@ -0,0 +1,7 @@ +CMAKE_SYSTEM_APPBUNDLE_PATH +--------------------------- + +Search path for OS X 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 000000000..1e8b0d947 --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_FRAMEWORK_PATH.rst @@ -0,0 +1,8 @@ +CMAKE_SYSTEM_FRAMEWORK_PATH +--------------------------- + +Search path for OS X 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 000000000..4ad7e33ce --- /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 000000000..2c14345c0 --- /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 000000000..3969cb94c --- /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 000000000..c3a42e5b4 --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_NAME.rst @@ -0,0 +1,20 @@ +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. + +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 000000000..e74dfad18 --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst @@ -0,0 +1,18 @@ +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`. +It 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 000000000..09280dee6 --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_PROCESSOR.rst @@ -0,0 +1,10 @@ +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. + +* The :generator:`Green Hills MULTI` generator sets this to ``ARM`` by default. diff --git a/Help/variable/CMAKE_SYSTEM_PROGRAM_PATH.rst b/Help/variable/CMAKE_SYSTEM_PROGRAM_PATH.rst new file mode 100644 index 000000000..cf1b83e80 --- /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 000000000..aba8ca32b --- /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 000000000..50121e286 --- /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 000000000..168ee74c7 --- /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 000000000..d731f02c0 --- /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 000000000..0f967876b --- /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 000000000..5fa8dfcb6 --- /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 000000000..be2e0500f --- /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 000000000..622278ee9 --- /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 000000000..e7139ac3c --- /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 000000000..06fe0fbc6 --- /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 000000000..232a2fd0f --- /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 000000000..872e2face --- /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 000000000..150baccc1 --- /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 000000000..51b42dd4b --- /dev/null +++ b/Help/variable/CMAKE_VS_DEVENV_COMMAND.rst @@ -0,0 +1,14 @@ +CMAKE_VS_DEVENV_COMMAND +----------------------- + +The generators for :generator:`Visual Studio 8 2005` 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_INCLUDE_INSTALL_TO_DEFAULT_BUILD.rst b/Help/variable/CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD.rst new file mode 100644 index 000000000..f54472ad1 --- /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 000000000..693ba45d3 --- /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 000000000..6d196f917 --- /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 8 2005` 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 000000000..58f2bef4c --- /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 000000000..386c3a9de --- /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 000000000..a532743fb --- /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 000000000..ed2d3f352 --- /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 000000000..1604a7667 --- /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 000000000..9b59c52a6 --- /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_WINDOWS_TARGET_PLATFORM_VERSION.rst b/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst new file mode 100644 index 000000000..83b9bc1fd --- /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_WARN_DEPRECATED.rst b/Help/variable/CMAKE_WARN_DEPRECATED.rst new file mode 100644 index 000000000..4a224fa5c --- /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 000000000..81c1158c2 --- /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 000000000..b96abba7b --- /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 000000000..1636842d9 --- /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 000000000..be683d668 --- /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 000000000..c9fcc92e0 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_GENERATE_SCHEME.rst @@ -0,0 +1,11 @@ +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. diff --git a/Help/variable/CMAKE_XCODE_PLATFORM_TOOLSET.rst b/Help/variable/CMAKE_XCODE_PLATFORM_TOOLSET.rst new file mode 100644 index 000000000..210da52d5 --- /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/CPACK_ABSOLUTE_DESTINATION_FILES.rst b/Help/variable/CPACK_ABSOLUTE_DESTINATION_FILES.rst new file mode 100644 index 000000000..928fe4589 --- /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 000000000..6cf75e443 --- /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 000000000..5dad6bd68 --- /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 000000000..b8e9105a4 --- /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_SCRIPT.rst b/Help/variable/CPACK_INSTALL_SCRIPT.rst new file mode 100644 index 000000000..12a48a40d --- /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 000000000..f423e2e7f --- /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 000000000..27fd355ce --- /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 000000000..3fc5cca0e --- /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 000000000..fd8461fd6 --- /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 000000000..7b13ba06b --- /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 000000000..d25d84c0a --- /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 000000000..474d6213e --- /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 000000000..d0f957980 --- /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 000000000..a423f4900 --- /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 000000000..da256f24f --- /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 000000000..c905480c0 --- /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 000000000..5561b6dcf --- /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 000000000..a78792ea5 --- /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 000000000..298195508 --- /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 000000000..fc5dfc488 --- /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 000000000..d5893c9f8 --- /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 000000000..cd65ae327 --- /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 000000000..558f5e580 --- /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 000000000..614859bc8 --- /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 000000000..74dc47ad2 --- /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 000000000..5aeae88a4 --- /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 000000000..920cb0476 --- /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 000000000..a1f1cc14b --- /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 000000000..1fbb8c53f --- /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 000000000..578576cd6 --- /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 000000000..40291febd --- /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 000000000..791292cd0 --- /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 000000000..00de8aa2b --- /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 000000000..6af7152ef --- /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 000000000..6114e608c --- /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 000000000..36fa37d92 --- /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 000000000..a35be96b5 --- /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 000000000..02d15474a --- /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 000000000..6431c0266 --- /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 000000000..049700b3a --- /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 000000000..d7f2f7c2c --- /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 000000000..c0f22158d --- /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 000000000..50fbd4de9 --- /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 000000000..d15d99be2 --- /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 000000000..22b977632 --- /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 000000000..904d2c8a8 --- /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 000000000..a860a03fe --- /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 000000000..286f7dfed --- /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 000000000..eb83792ec --- /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 000000000..fd270030d --- /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 000000000..0c479e604 --- /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 000000000..4590a786d --- /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 000000000..3854950af --- /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 000000000..9049c1f45 --- /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_MEMORYCHECK_COMMAND.rst b/Help/variable/CTEST_MEMORYCHECK_COMMAND.rst new file mode 100644 index 000000000..8c199bac2 --- /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 000000000..3e26ab515 --- /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 000000000..2de5fb6b8 --- /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 000000000..1147ee8e8 --- /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 000000000..b8b4c30be --- /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 000000000..bc802764e --- /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 000000000..347ea549e --- /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 000000000..defab12be --- /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 000000000..fee4ce2d8 --- /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 000000000..0e2790fb5 --- /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_SCP_COMMAND.rst b/Help/variable/CTEST_SCP_COMMAND.rst new file mode 100644 index 000000000..0f128b14a --- /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 000000000..8a5ec253d --- /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 000000000..b6837d1a0 --- /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 000000000..af9014361 --- /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 000000000..76551dc11 --- /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 000000000..5f01a193a --- /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 000000000..80823fe4e --- /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 000000000..c031437f0 --- /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 000000000..de9242807 --- /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 000000000..90155d07f --- /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 000000000..e43d61d1c --- /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 000000000..e646e6eea --- /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 000000000..9f48a2e42 --- /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 000000000..0039e071f --- /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 000000000..368152aeb --- /dev/null +++ b/Help/variable/ENV.rst @@ -0,0 +1,7 @@ +ENV +--- + +Access environment variables. + +Use the syntax ``$ENV{VAR}`` to read environment variable ``VAR``. See also +the :command:`set` command to set ``ENV{VAR}``. diff --git a/Help/variable/EXECUTABLE_OUTPUT_PATH.rst b/Help/variable/EXECUTABLE_OUTPUT_PATH.rst new file mode 100644 index 000000000..26d3e92a1 --- /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 000000000..0f91be8ad --- /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 000000000..ba02911e6 --- /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` +supercede 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 000000000..6d29be462 --- /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 000000000..22a087a77 --- /dev/null +++ b/Help/variable/MSVC.rst @@ -0,0 +1,8 @@ +MSVC +---- + +``True`` when using Microsoft Visual C++. + +Set to ``true`` when the compiler is some version of Microsoft 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 000000000..55c63371f --- /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 000000000..17943dcc4 --- /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 000000000..a524fab3b --- /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 000000000..79e0c10b5 --- /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 000000000..14164bf76 --- /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 000000000..ed3b0bbdf --- /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 000000000..0237592c6 --- /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 000000000..1533218a9 --- /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 000000000..4981ecff0 --- /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 000000000..027d1bc8c --- /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_VERSION.rst b/Help/variable/MSVC_VERSION.rst new file mode 100644 index 000000000..8932147c6 --- /dev/null +++ b/Help/variable/MSVC_VERSION.rst @@ -0,0 +1,17 @@ +MSVC_VERSION +------------ + +The version of Microsoft Visual C/C++ being used if any. + +Known version numbers are:: + + 1200 = VS 6.0 + 1300 = VS 7.0 + 1310 = VS 7.1 + 1400 = VS 8.0 + 1500 = VS 9.0 + 1600 = VS 10.0 + 1700 = VS 11.0 + 1800 = VS 12.0 + 1900 = VS 14.0 + 1910 = VS 15.0 diff --git a/Help/variable/PROJECT-NAME_BINARY_DIR.rst b/Help/variable/PROJECT-NAME_BINARY_DIR.rst new file mode 100644 index 000000000..49bc55878 --- /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_SOURCE_DIR.rst b/Help/variable/PROJECT-NAME_SOURCE_DIR.rst new file mode 100644 index 000000000..4df3e223c --- /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 000000000..0f6ed514b --- /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 000000000..9e2d755a6 --- /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 000000000..fa2cdab58 --- /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 000000000..85b5e6bdb --- /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 000000000..65c404482 --- /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 000000000..09e9ef218 --- /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 000000000..05ede8fcc --- /dev/null +++ b/Help/variable/PROJECT_DESCRIPTION.rst @@ -0,0 +1,6 @@ +PROJECT_DESCRIPTION +------------------- + +Short project description given to the project command. + +This is the description given to the most recent :command:`project` command. diff --git a/Help/variable/PROJECT_NAME.rst b/Help/variable/PROJECT_NAME.rst new file mode 100644 index 000000000..61aa8bc00 --- /dev/null +++ b/Help/variable/PROJECT_NAME.rst @@ -0,0 +1,6 @@ +PROJECT_NAME +------------ + +Name of the project given to the project command. + +This is the name given to the most recent :command:`project` command. diff --git a/Help/variable/PROJECT_SOURCE_DIR.rst b/Help/variable/PROJECT_SOURCE_DIR.rst new file mode 100644 index 000000000..27f2838ee --- /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 000000000..234558dbd --- /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 000000000..4b6072c54 --- /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 000000000..5f31220f4 --- /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 000000000..ac72ec051 --- /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 000000000..d7f96d6ce --- /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/UNIX.rst b/Help/variable/UNIX.rst new file mode 100644 index 000000000..0877b7c07 --- /dev/null +++ b/Help/variable/UNIX.rst @@ -0,0 +1,7 @@ +UNIX +---- + +``True`` for UNIX and UNIX like operating systems. + +Set to ``true`` when the target system is UNIX or UNIX like (i.e. +:variable:`APPLE` and :variable:`CYGWIN`). diff --git a/Help/variable/WIN32.rst b/Help/variable/WIN32.rst new file mode 100644 index 000000000..218906955 --- /dev/null +++ b/Help/variable/WIN32.rst @@ -0,0 +1,6 @@ +WIN32 +----- + +``True`` on Windows systems, including Win64. + +Set to ``true`` when the target system is Windows. diff --git a/Help/variable/WINCE.rst b/Help/variable/WINCE.rst new file mode 100644 index 000000000..54ff7dee2 --- /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 000000000..61d91b00a --- /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 000000000..dae3b539b --- /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 000000000..99f20fb7a --- /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 000000000..b85d41e91 --- /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``). |