diff options
Diffstat (limited to 'Help')
1058 files changed, 21329 insertions, 0 deletions
diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt new file mode 100644 index 0000000000..5889e90099 --- /dev/null +++ b/Help/command/FIND_XXX.txt @@ -0,0 +1,101 @@ +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_ENVIRONMENT_PATH] + [NO_CMAKE_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. +The name of the |SEARCH_XXX| that +is searched for is specified by the names listed +after the NAMES argument. Additional search locations +can be specified after the PATHS argument. If ENV var is +found in the HINTS or PATHS section the environment variable var +will be read and converted from a system environment variable to +a cmake style list of paths. For example ENV PATH would be a way +to list the system path variable. The argument +after DOC will be used for the documentation string in +the cache. +PATH_SUFFIXES specifies additional subdirectories to check below +each search path. + +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 CMAKE_PREFIX_PATH + +.. |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| replace:: + <prefix>/|XXX_SUBDIR| for each <prefix> in 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. + 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. + 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 + +.. include:: FIND_XXX_MAC.txt +.. include:: FIND_XXX_ROOT.txt +.. include:: FIND_XXX_ORDER.txt diff --git a/Help/command/FIND_XXX_MAC.txt b/Help/command/FIND_XXX_MAC.txt new file mode 100644 index 0000000000..eb3900cbbb --- /dev/null +++ b/Help/command/FIND_XXX_MAC.txt @@ -0,0 +1,24 @@ +On Darwin or systems supporting OS X Frameworks, the cmake variable +CMAKE_FIND_FRAMEWORK 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. + +On Darwin or systems supporting OS X Application Bundles, the cmake +variable CMAKE_FIND_APPBUNDLE 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/command/FIND_XXX_ORDER.txt b/Help/command/FIND_XXX_ORDER.txt new file mode 100644 index 0000000000..bac2419645 --- /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 0000000000..b5cab68b8a --- /dev/null +++ b/Help/command/FIND_XXX_ROOT.txt @@ -0,0 +1,23 @@ +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. By using CMAKE_FIND_ROOT_PATH_BOTH +the search order will be as described above. If +NO_CMAKE_FIND_ROOT_PATH is used then :variable:`CMAKE_FIND_ROOT_PATH` will not be +used. If ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted +directories and directories below :variable:`CMAKE_STAGING_PREFIX` will be searched. diff --git a/Help/command/add_compile_options.rst b/Help/command/add_compile_options.rst new file mode 100644 index 0000000000..214f4bef33 --- /dev/null +++ b/Help/command/add_compile_options.rst @@ -0,0 +1,22 @@ +add_compile_options +------------------- + +Adds options to the compilation of source files. + +:: + + add_compile_options(<option> ...) + +Adds options to the compiler command line for sources in the current +directory and below. This command can be used to add any options, but +alternative commands exist to add preprocessor definitions +(:command:`target_compile_definitions` and :command:`add_definitions`) or +include directories (:command:`target_include_directories` and +:command:`include_directories`). See documentation of the +:prop_tgt:`directory <COMPILE_OPTIONS>` and +:prop_tgt:`target <COMPILE_OPTIONS>` ``COMPILE_OPTIONS`` properties. + +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 0000000000..e8b7cc8f5e --- /dev/null +++ b/Help/command/add_custom_command.rst @@ -0,0 +1,169 @@ +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...]] + [IMPLICIT_DEPENDS <lang1> depend1 + [<lang2> depend2] ...] + [WORKING_DIRECTORY dir] + [COMMENT comment] [VERBATIM] [APPEND]) + +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. + +``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 (created by the + :command:`add_executable` command) it will automatically be replaced + by the location of the executable created at build time. + 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)>`. + +``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. + +``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. + 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. + +``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. + +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...] ...] + [WORKING_DIRECTORY dir] + [COMMENT comment] [VERBATIM]) + +This defines a new command that will be associated with building the +specified target. 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 7 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 0000000000..1bf70bffd9 --- /dev/null +++ b/Help/command/add_custom_target.rst @@ -0,0 +1,45 @@ +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 ... ] + [WORKING_DIRECTORY dir] + [COMMENT comment] [VERBATIM] + [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 ADD_CUSTOM_COMMAND to generate a file with dependencies. By +default nothing depends on the custom target. Use ADD_DEPENDENCIES to +add dependencies to or from other targets. If the ALL option is +specified it indicates 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). The command and arguments are optional and if not +specified an empty target will be created. If WORKING_DIRECTORY is +set, then the command will be run in that directory. If it is a +relative path it will be interpreted relative to the build tree +directory corresponding to the current source directory. If COMMENT +is set, the value will be displayed as a message before the commands +are executed at build time. Dependencies listed with the DEPENDS +argument may reference files and outputs of custom commands created +with add_custom_command() in the same directory (CMakeLists.txt file). + +If VERBATIM is given then 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. + +The SOURCES option specifies 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 not build +rules. diff --git a/Help/command/add_definitions.rst b/Help/command/add_definitions.rst new file mode 100644 index 0000000000..2965c3774a --- /dev/null +++ b/Help/command/add_definitions.rst @@ -0,0 +1,25 @@ +add_definitions +--------------- + +Adds -D define flags to the compilation of source files. + +:: + + add_definitions(-DFOO -DBAR ...) + +Adds definitions to the compiler command line for sources in the current +directory and below. This command can be used to add any flags, but +it is intended to add preprocessor definitions. 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 0000000000..10997ec206 --- /dev/null +++ b/Help/command/add_dependencies.rst @@ -0,0 +1,19 @@ +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 ADD_EXECUTABLE, ADD_LIBRARY, or ADD_CUSTOM_TARGET. +Dependencies added to an IMPORTED target are followed transitively in +its place since the target itself does not build. + +See the DEPENDS option of ADD_CUSTOM_TARGET and ADD_CUSTOM_COMMAND for +adding file-level dependencies in custom rules. See the +OBJECT_DEPENDS option in SET_SOURCE_FILES_PROPERTIES 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 0000000000..4ed10e1cff --- /dev/null +++ b/Help/command/add_executable.rst @@ -0,0 +1,80 @@ +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. + + +-------------------------------------------------------------------------- + +:: + + 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 existance 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 0000000000..f86f3c5ec3 --- /dev/null +++ b/Help/command/add_library.rst @@ -0,0 +1,151 @@ +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. + +By default the library file will be created in the build tree directory +corresponding to the source tree directory in which thecommand 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. + +Imported Libraries +^^^^^^^^^^^^^^^^^^ + +:: + + add_library(<name> <SHARED|STATIC|MODULE|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 imported, exported, installed, or 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 generatedbuildsystem 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 existance 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 :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)` commands, 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 0000000000..29b50174c6 --- /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 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 0000000000..7e7e6bddd7 --- /dev/null +++ b/Help/command/add_test.rst @@ -0,0 +1,59 @@ +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 ``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 0000000000..434d7a919e --- /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 0000000000..8f1067b1e9 --- /dev/null +++ b/Help/command/break.rst @@ -0,0 +1,10 @@ +break +----- + +Break from an enclosing foreach or while loop. + +:: + + break() + +Breaks from an enclosing foreach loop or while loop diff --git a/Help/command/build_command.rst b/Help/command/build_command.rst new file mode 100644 index 0000000000..82a9a42b9f --- /dev/null +++ b/Help/command/build_command.rst @@ -0,0 +1,44 @@ +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 Makefile generators. + +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 ``--config`` or ``--target`` options. +The ``<makecommand>`` is ignored but should be the full path to +msdev, 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 0000000000..53cd05ec1a --- /dev/null +++ b/Help/command/build_name.rst @@ -0,0 +1,14 @@ +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 +CMAKE_SYSTEM and CMAKE_CXX_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 0000000000..ba545d5e27 --- /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 0000000000..1bdffa46e3 --- /dev/null +++ b/Help/command/cmake_minimum_required.rst @@ -0,0 +1,30 @@ +cmake_minimum_required +---------------------- + +Set the minimum required version of cmake for a project. + +:: + + 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. 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. + +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. diff --git a/Help/command/cmake_policy.rst b/Help/command/cmake_policy.rst new file mode 100644 index 0000000000..2bc32870f1 --- /dev/null +++ b/Help/command/cmake_policy.rst @@ -0,0 +1,94 @@ +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``. + +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 0000000000..70357f2407 --- /dev/null +++ b/Help/command/configure_file.rst @@ -0,0 +1,46 @@ +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 a file <input> to file <output> and substitutes variable values +referenced in the file content. If <input> is a relative path it is +evaluated with respect to the current source directory. The <input> +must be a file, not a directory. If <output> is a relative path it is +evaluated with respect to the current binary directory. If <output> +names an existing directory the input file is placed in that directory +with its original name. + +If the <input> file is modified the build system will re-run CMake to +re-configure the file and generate the build system again. + +This command replaces any variables in the input file referenced as +${VAR} or @VAR@ with their values as determined by CMake. If a +variable is not defined, it will be replaced with nothing. If +COPYONLY is specified, then no variable expansion will take place. If +ESCAPE_QUOTES is specified then any substituted quotes will be C-style +escaped. The file will be configured with the current values of CMake +variables. If @ONLY is specified, only variables of the form @VAR@ +will be replaced and ${VAR} will be ignored. This is useful for +configuring scripts that use ${VAR}. + +Input file 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 if() command. (Content of "...", 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. + +With NEWLINE_STYLE the line ending could be adjusted: + +:: + + 'UNIX' or 'LF' for \n, 'DOS', 'WIN32' or 'CRLF' for \r\n. + +COPYONLY must not be used with NEWLINE_STYLE. diff --git a/Help/command/create_test_sourcelist.rst b/Help/command/create_test_sourcelist.rst new file mode 100644 index 0000000000..9addd6720c --- /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 variable +CMAKE_TESTDRIVER_BEFORE_TESTMAIN 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 0000000000..4a95cdde7f --- /dev/null +++ b/Help/command/ctest_build.rst @@ -0,0 +1,29 @@ +ctest_build +----------- + +Build the project. + +:: + + ctest_build([BUILD build_dir] [TARGET target] [RETURN_VALUE res] + [APPEND][NUMBER_ERRORS val] [NUMBER_WARNINGS val]) + +Builds the given build directory and stores results in Build.xml. If +no BUILD is given, the CTEST_BINARY_DIRECTORY variable is used. + +The TARGET variable can be used to specify a build target. If none is +specified, the "all" target will be built. + +The RETURN_VALUE option specifies a variable in which to store the +return value of the native build tool. The NUMBER_ERRORS and +NUMBER_WARNINGS options specify variables in which to store the number +of build errors and warnings detected. + +The APPEND option marks results for append to those previously +submitted to a dashboard server since the last ctest_start. Append +semantics are defined by the dashboard server in use. + +If set, the contents of the variable CTEST_BUILD_FLAGS are passed as +additional arguments to the underlying build command. This can e.g. be +used to trigger a parallel build using the -j option of make. See +:module:`ProcessorCount` for an example. diff --git a/Help/command/ctest_configure.rst b/Help/command/ctest_configure.rst new file mode 100644 index 0000000000..2c4e305ff5 --- /dev/null +++ b/Help/command/ctest_configure.rst @@ -0,0 +1,21 @@ +ctest_configure +--------------- + +Configure the project build tree. + +:: + + ctest_configure([BUILD build_dir] [SOURCE source_dir] [APPEND] + [OPTIONS options] [RETURN_VALUE res]) + +Configures the given build directory and stores results in +Configure.xml. If no BUILD is given, the CTEST_BINARY_DIRECTORY +variable is used. If no SOURCE is given, the CTEST_SOURCE_DIRECTORY +variable is used. The OPTIONS argument specifies command line +arguments to pass to the configuration tool. The RETURN_VALUE option +specifies a variable in which to store the return value of the native +build tool. + +The APPEND option marks results for append to those previously +submitted to a dashboard server since the last ctest_start. Append +semantics are defined by the dashboard server in use. diff --git a/Help/command/ctest_coverage.rst b/Help/command/ctest_coverage.rst new file mode 100644 index 0000000000..4c90f9c019 --- /dev/null +++ b/Help/command/ctest_coverage.rst @@ -0,0 +1,20 @@ +ctest_coverage +-------------- + +Collect coverage tool results. + +:: + + ctest_coverage([BUILD build_dir] [RETURN_VALUE res] [APPEND] + [LABELS label1 [label2 [...]]]) + +Perform the coverage of the given build directory and stores results +in Coverage.xml. The second argument is a variable that will hold +value. + +The LABELS option filters the coverage report to include only source +files labeled with at least one of the labels specified. + +The APPEND option marks results for append to those previously +submitted to a dashboard server since the last ctest_start. Append +semantics are defined by the dashboard server in use. diff --git a/Help/command/ctest_empty_binary_directory.rst b/Help/command/ctest_empty_binary_directory.rst new file mode 100644 index 0000000000..77536673ce --- /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 0000000000..ca47ed0472 --- /dev/null +++ b/Help/command/ctest_memcheck.rst @@ -0,0 +1,28 @@ +ctest_memcheck +-------------- + +Run tests with a dynamic analysis tool. + +:: + + ctest_memcheck([BUILD build_dir] [RETURN_VALUE res] [APPEND] + [START start number] [END end number] + [STRIDE stride number] [EXCLUDE exclude regex ] + [INCLUDE include regex] + [EXCLUDE_LABEL exclude regex] + [INCLUDE_LABEL label regex] + [PARALLEL_LEVEL level] ) + +Tests the given build directory and stores results in MemCheck.xml. +The second argument is a variable that will hold value. Optionally, +you can specify the starting test number START, the ending test number +END, the number of tests to skip between each test STRIDE, a regular +expression for tests to run INCLUDE, or a regular expression for tests +not to run EXCLUDE. EXCLUDE_LABEL and INCLUDE_LABEL are regular +expressions for tests to be included or excluded by the test property +LABEL. PARALLEL_LEVEL should be set to a positive number representing +the number of tests to be run in parallel. + +The APPEND option marks results for append to those previously +submitted to a dashboard server since the last ctest_start. Append +semantics are defined by the dashboard server in use. diff --git a/Help/command/ctest_read_custom_files.rst b/Help/command/ctest_read_custom_files.rst new file mode 100644 index 0000000000..0bc57cd935 --- /dev/null +++ b/Help/command/ctest_read_custom_files.rst @@ -0,0 +1,11 @@ +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. diff --git a/Help/command/ctest_run_script.rst b/Help/command/ctest_run_script.rst new file mode 100644 index 0000000000..0f3501928e --- /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 0000000000..16a914c0b4 --- /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 0000000000..d7472dbc7f --- /dev/null +++ b/Help/command/ctest_start.rst @@ -0,0 +1,24 @@ +ctest_start +----------- + +Starts the testing for a given model + +:: + + ctest_start(Model [TRACK <track>] [APPEND] [source [binary]]) + +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 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 0000000000..ed801bb61d --- /dev/null +++ b/Help/command/ctest_submit.rst @@ -0,0 +1,35 @@ +ctest_submit +------------ + +Submit results to a dashboard server. + +:: + + ctest_submit([PARTS ...] [FILES ...] [RETRY_COUNT count] [RETRY_DELAY delay][RETURN_VALUE res]) + +By default all available parts are submitted if no PARTS or FILES are +specified. The PARTS option lists a subset of parts to be submitted. +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 + +The FILES option explicitly lists specific files to be submitted. +Each individual file must exist at the time of the call. + +The RETRY_DELAY option specifies how long in seconds to wait after a +timed-out submission before attempting to re-submit. + +The RETRY_COUNT option specifies how many times to retry a timed-out +submission. diff --git a/Help/command/ctest_test.rst b/Help/command/ctest_test.rst new file mode 100644 index 0000000000..5f28083810 --- /dev/null +++ b/Help/command/ctest_test.rst @@ -0,0 +1,33 @@ +ctest_test +---------- + +Run tests in the project build tree. + +:: + + ctest_test([BUILD build_dir] [APPEND] + [START start number] [END end number] + [STRIDE stride number] [EXCLUDE exclude regex ] + [INCLUDE include regex] [RETURN_VALUE res] + [EXCLUDE_LABEL exclude regex] + [INCLUDE_LABEL label regex] + [PARALLEL_LEVEL level] + [SCHEDULE_RANDOM on] + [STOP_TIME time of day]) + +Tests the given build directory and stores results in Test.xml. The +second argument is a variable that will hold value. Optionally, you +can specify the starting test number START, the ending test number +END, the number of tests to skip between each test STRIDE, a regular +expression for tests to run INCLUDE, or a regular expression for tests +to not run EXCLUDE. EXCLUDE_LABEL and INCLUDE_LABEL are regular +expression for test to be included or excluded by the test property +LABEL. PARALLEL_LEVEL should be set to a positive number representing +the number of tests to be run in parallel. SCHEDULE_RANDOM will +launch tests in a random order, and is typically used to detect +implicit test dependencies. STOP_TIME is the time of day at which the +tests should all stop running. + +The APPEND option marks results for append to those previously +submitted to a dashboard server since the last ctest_start. Append +semantics are defined by the dashboard server in use. diff --git a/Help/command/ctest_update.rst b/Help/command/ctest_update.rst new file mode 100644 index 0000000000..d34e192afb --- /dev/null +++ b/Help/command/ctest_update.rst @@ -0,0 +1,13 @@ +ctest_update +------------ + +Update the work tree from version control. + +:: + + ctest_update([SOURCE source] [RETURN_VALUE res]) + +Updates the given source directory and stores results in Update.xml. +If no SOURCE is given, the CTEST_SOURCE_DIRECTORY variable is used. +The RETURN_VALUE option specifies a variable in which to store the +result, which is the number of files updated or -1 on error. diff --git a/Help/command/ctest_upload.rst b/Help/command/ctest_upload.rst new file mode 100644 index 0000000000..9156af56b9 --- /dev/null +++ b/Help/command/ctest_upload.rst @@ -0,0 +1,11 @@ +ctest_upload +------------ + +Upload files to a dashboard server. + +:: + + ctest_upload(FILES ...) + +Pass a list of files to be sent along with the build results to the +dashboard server. diff --git a/Help/command/define_property.rst b/Help/command/define_property.rst new file mode 100644 index 0000000000..62bcd1bf12 --- /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 set_property and +get_property commands. This is primarily useful to associate +documentation with property names that may be retrieved with the +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 set_property and 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 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 get_property command will retrieve the +documentation. diff --git a/Help/command/else.rst b/Help/command/else.rst new file mode 100644 index 0000000000..5eece9566a --- /dev/null +++ b/Help/command/else.rst @@ -0,0 +1,10 @@ +else +---- + +Starts the else portion of an if block. + +:: + + else(expression) + +See the if command. diff --git a/Help/command/elseif.rst b/Help/command/elseif.rst new file mode 100644 index 0000000000..96ee0e9246 --- /dev/null +++ b/Help/command/elseif.rst @@ -0,0 +1,10 @@ +elseif +------ + +Starts the elseif portion of an if block. + +:: + + elseif(expression) + +See the if command. diff --git a/Help/command/enable_language.rst b/Help/command/enable_language.rst new file mode 100644 index 0000000000..d46ff7ed1d --- /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 0000000000..41ecd5b1bd --- /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 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 0000000000..f23552d06a --- /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 FOREACH command. diff --git a/Help/command/endfunction.rst b/Help/command/endfunction.rst new file mode 100644 index 0000000000..63e70ba3cb --- /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 function command. diff --git a/Help/command/endif.rst b/Help/command/endif.rst new file mode 100644 index 0000000000..4c9955c2e0 --- /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 if command. diff --git a/Help/command/endmacro.rst b/Help/command/endmacro.rst new file mode 100644 index 0000000000..524fc80e7b --- /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 macro command. diff --git a/Help/command/endwhile.rst b/Help/command/endwhile.rst new file mode 100644 index 0000000000..11fdc1be55 --- /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 while command. diff --git a/Help/command/exec_program.rst b/Help/command/exec_program.rst new file mode 100644 index 0000000000..aaa0dacc1e --- /dev/null +++ b/Help/command/exec_program.rst @@ -0,0 +1,24 @@ +exec_program +------------ + +Deprecated. Use the 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 0000000000..478b30e11d --- /dev/null +++ b/Help/command/execute_process.rst @@ -0,0 +1,75 @@ +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]) + +Runs the given sequence of one or more commands 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.) + +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. + +OUTPUT_QUIET, ERROR_QUIET + The standard output or standard error results will be quietly ignored. + +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 0000000000..d4bab352a7 --- /dev/null +++ b/Help/command/export.rst @@ -0,0 +1,57 @@ +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 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. diff --git a/Help/command/export_library_dependencies.rst b/Help/command/export_library_dependencies.rst new file mode 100644 index 0000000000..73c0b42405 --- /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 install(EXPORT) command to help export targets from an +installation tree and the 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 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 0000000000..dbc41497d3 --- /dev/null +++ b/Help/command/file.rst @@ -0,0 +1,307 @@ +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. "UTF-8" is currently supported. + +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(<MD5|SHA1|SHA224|SHA256|SHA384|SHA512> <filename> <variable>) + +Compute a cryptographic hash of the content of ``<filename>`` and +store it in a ``<variable>``. + +------------------------------------------------------------------------------ + +:: + + file(GLOB <variable> [RELATIVE <path>] [<globbing-expressions>...]) + file(GLOB_RECURSE <variable> [RELATIVE <path>] + [FOLLOW_SYMLINKS] [<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. + +.. 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``. + +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 + +------------------------------------------------------------------------------ + +:: + + 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. + +Additional options to ``DOWNLOAD`` are: + +``EXPECTED_HASH ALGO=<value>`` + + Verify that the downloaded content hash matches the expected value, where + ``ALGO`` is one of ``MD5``, ``SHA1``, ``SHA224``, ``SHA256``, ``SHA384``, or + ``SHA512``. 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 <options>...) + +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. + +------------------------------------------------------------------------------ + +:: + + 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, ``PATTERN``, ``REGEX``, and ``EXCLUDE`` options. + +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). diff --git a/Help/command/find_file.rst b/Help/command/find_file.rst new file mode 100644 index 0000000000..db7e1518ef --- /dev/null +++ b/Help/command/find_file.rst @@ -0,0 +1,27 @@ +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 +.. |XXX_SUBDIR| replace:: include + +.. |CMAKE_PREFIX_PATH_XXX| replace:: + <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and + |CMAKE_PREFIX_PATH_XXX_SUBDIR| +.. |CMAKE_XXX_PATH| replace:: CMAKE_INCLUDE_PATH +.. |CMAKE_XXX_MAC_PATH| replace:: CMAKE_FRAMEWORK_PATH + +.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: PATH and INCLUDE + +.. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace:: + <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and + |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| +.. |CMAKE_SYSTEM_XXX_PATH| replace:: CMAKE_SYSTEM_INCLUDE_PATH +.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: 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 0000000000..91342bad3a --- /dev/null +++ b/Help/command/find_library.rst @@ -0,0 +1,44 @@ +find_library +------------ + +.. |FIND_XXX| replace:: find_library +.. |NAMES| replace:: NAMES name1 [name2 ...] [NAMES_PER_DIR] +.. |SEARCH_XXX| replace:: library +.. |SEARCH_XXX_DESC| replace:: library +.. |XXX_SUBDIR| replace:: lib + +.. |CMAKE_PREFIX_PATH_XXX| replace:: + <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and + |CMAKE_PREFIX_PATH_XXX_SUBDIR| +.. |CMAKE_XXX_PATH| replace:: CMAKE_LIBRARY_PATH +.. |CMAKE_XXX_MAC_PATH| replace:: CMAKE_FRAMEWORK_PATH + +.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: PATH and LIB + +.. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace:: + <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and + |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| +.. |CMAKE_SYSTEM_XXX_PATH| replace:: CMAKE_SYSTEM_LIBRARY_PATH +.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: 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. + +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 global property FIND_LIBRARY_USE_LIB64_PATHS 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 PROJECT command is +enabled. diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst new file mode 100644 index 0000000000..190d05cf61 --- /dev/null +++ b/Help/command/find_package.rst @@ -0,0 +1,349 @@ +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_ENVIRONMENT_PATH] + [NO_CMAKE_PATH] + [NO_SYSTEM_ENVIRONMENT_PATH] + [NO_CMAKE_PACKAGE_REGISTRY] + [NO_CMAKE_BUILDS_PATH] + [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. No attempt is made to choose a highest or closest +version number. + +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) + +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 cmake variables +``CMAKE_FIND_FRAMEWORK`` and ``CMAKE_FIND_APPBUNDLE`` +determine the order of preference as specified below. + +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``. + 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. + 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 project build trees recently configured in a :manual:`cmake-gui(1)`. + This can be skipped if ``NO_CMAKE_BUILDS_PATH`` is passed. It is intended + for the case when a user is building multiple dependent projects one + after another. + (This step is implemented only on Windows.) + +6. Search paths stored in the CMake :ref:`User Package Registry`. + This can be skipped if ``NO_CMAKE_PACKAGE_REGISTRY`` is passed or by + setting the :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` + to ``TRUE``. + See the :manual:`cmake-packages(7)` manual for details on the user + package registry. + +7. Search cmake variables defined in the Platform files for the + current system. This can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is + passed:: + + CMAKE_SYSTEM_PREFIX_PATH + CMAKE_SYSTEM_FRAMEWORK_PATH + CMAKE_SYSTEM_APPBUNDLE_PATH + +8. Search paths stored in the CMake :ref:`System Package Registry`. + This can be skipped if ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` is passed + or by setting the + :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` to ``TRUE``. + See the :manual:`cmake-packages(7)` manual for details on the system + package registry. + +9. Search paths specified by the ``PATHS`` option. These are typically + hard-coded guesses. + +.. |FIND_XXX| replace:: find_package +.. |FIND_ARGS_XXX| replace:: <package> +.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace:: + :variable:`CMAKE_FIND_ROOT_PATH_MODE_PACKAGE` + +.. include:: FIND_XXX_MAC.txt +.. 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): + +``<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 0000000000..95d49e77aa --- /dev/null +++ b/Help/command/find_path.rst @@ -0,0 +1,32 @@ +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 +.. |XXX_SUBDIR| replace:: include + +.. |CMAKE_PREFIX_PATH_XXX| replace:: + <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and + |CMAKE_PREFIX_PATH_XXX_SUBDIR| +.. |CMAKE_XXX_PATH| replace:: CMAKE_INCLUDE_PATH +.. |CMAKE_XXX_MAC_PATH| replace:: CMAKE_FRAMEWORK_PATH + +.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: PATH and INCLUDE + +.. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace:: + <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and + |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| +.. |CMAKE_SYSTEM_XXX_PATH| replace:: CMAKE_SYSTEM_INCLUDE_PATH +.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: 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 0000000000..c62a8a5d24 --- /dev/null +++ b/Help/command/find_program.rst @@ -0,0 +1,25 @@ +find_program +------------ + +.. |FIND_XXX| replace:: find_program +.. |NAMES| replace:: NAMES name1 [name2 ...] +.. |SEARCH_XXX| replace:: program +.. |SEARCH_XXX_DESC| replace:: program +.. |XXX_SUBDIR| replace:: [s]bin + +.. |CMAKE_PREFIX_PATH_XXX| replace:: + |CMAKE_PREFIX_PATH_XXX_SUBDIR| +.. |CMAKE_XXX_PATH| replace:: CMAKE_PROGRAM_PATH +.. |CMAKE_XXX_MAC_PATH| replace:: 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:: CMAKE_SYSTEM_PROGRAM_PATH +.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: CMAKE_SYSTEM_APPBUNDLE_PATH + +.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace:: + :variable:`CMAKE_FIND_ROOT_PATH_MODE_PROGRAM` + +.. include:: FIND_XXX.txt diff --git a/Help/command/fltk_wrap_ui.rst b/Help/command/fltk_wrap_ui.rst new file mode 100644 index 0000000000..448ae644db --- /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 0000000000..348ebd875c --- /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 0000000000..b18e03cfe3 --- /dev/null +++ b/Help/command/function.rst @@ -0,0 +1,31 @@ +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 +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 variable 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 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. + +A function opens a new scope: see set(var PARENT_SCOPE) for details. + +See the 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 0000000000..bcfc5e8317 --- /dev/null +++ b/Help/command/get_cmake_property.rst @@ -0,0 +1,15 @@ +get_cmake_property +------------------ + +Get a property of the CMake instance. + +:: + + get_cmake_property(VAR property) + +Get a 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". Some supported properties include: VARIABLES, +CACHE_VARIABLES, COMMANDS, MACROS, and COMPONENTS. + +See also the more general get_property() command. diff --git a/Help/command/get_directory_property.rst b/Help/command/get_directory_property.rst new file mode 100644 index 0000000000..f2a0a803ed --- /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 get_property() command. diff --git a/Help/command/get_filename_component.rst b/Help/command/get_filename_component.rst new file mode 100644 index 0000000000..5eec792293 --- /dev/null +++ b/Help/command/get_filename_component.rst @@ -0,0 +1,37 @@ +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 + ABSOLUTE = Full path to file + REALPATH = Full path to existing file with symlinks resolved + PATH = Legacy alias for DIRECTORY (use for CMake <= 2.8.11) + +Paths are returned with forward slashes and have no trailing slahes. +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 + 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 0000000000..c2937be6af --- /dev/null +++ b/Help/command/get_property.rst @@ -0,0 +1,49 @@ +get_property +------------ + +Get a property. + +:: + + get_property(<variable> + <GLOBAL | + DIRECTORY [dir] | + TARGET <target> | + SOURCE <source> | + 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. + +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 define_property. +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 0000000000..80c512b4b6 --- /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 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 LOCATION + +See also the more general get_property() command. diff --git a/Help/command/get_target_property.rst b/Help/command/get_target_property.rst new file mode 100644 index 0000000000..4017d31d4b --- /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 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 get_property() command. diff --git a/Help/command/get_test_property.rst b/Help/command/get_test_property.rst new file mode 100644 index 0000000000..2623755b36 --- /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 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 get_property() command. diff --git a/Help/command/if.rst b/Help/command/if.rst new file mode 100644 index 0000000000..79e5d21c22 --- /dev/null +++ b/Help/command/if.rst @@ -0,0 +1,207 @@ +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``, ``GREATER``, ``STRLESS``, ``STRGREATER``, +``STREQUAL``, 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 constants, it + is treated as a variable. + +``if(<variable>)`` + True if the variable 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 such as those + created by the :command:`add_executable`, :command:`add_library`, or + :command:`add_custom_target` commands. + +``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. + +``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> 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> VERSION_LESS <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_GREATER <variable|string>)`` + Component-wise integer version number comparison (version format is + ``major[.minor[.patch[.tweak]]]``). + +``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``, and + ``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``, ``STREQUAL``, and + ``STRGREATER`` 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_EQUAL``, and ``VERSION_GREATER`` 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 0000000000..a9074c1b65 --- /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 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 module directory, +then first the CMake module directory is searched and +CMAKE_MODULE_PATH afterwards. See also policy CMP0017. + +See the 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 0000000000..f69493460e --- /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 0000000000..ba9a3934aa --- /dev/null +++ b/Help/command/include_external_msproject.rst @@ -0,0 +1,23 @@ +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 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). These options are not +supported by the Visual Studio 6 generator. diff --git a/Help/command/include_regular_expression.rst b/Help/command/include_regular_expression.rst new file mode 100644 index 0000000000..dd887df5d4 --- /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 0000000000..4c52abf71d --- /dev/null +++ b/Help/command/install.rst @@ -0,0 +1,341 @@ +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. 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. + +``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|FRAMEWORK|BUNDLE| + PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE] + [DESTINATION <dir>] + [INCLUDES DESTINATION [<dir> ...]] + [PERMISSIONS permissions...] + [CONFIGURATIONS [Debug|Release|...]] + [COMPONENT <component>] + [OPTIONAL] [NAMELINK_ONLY|NAMELINK_SKIP] + ] [...]) + +The ``TARGETS`` form specifies rules for installing targets from a +project. There are five kinds of target files that may be installed: +``ARCHIVE``, ``LIBRARY``, ``RUNTIME``, ``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 always treated as ``ARCHIVE`` +targets. 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. +The ``ARCHIVE``, ``LIBRARY``, ``RUNTIME``, 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 ``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>``. + +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. + +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``, or ``ARCHIVE`` 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. + +Installing Files +^^^^^^^^^^^^^^^^ + +:: + + install(<FILES|PROGRAMS> files... DESTINATION <dir> + [PERMISSIONS permissions...] + [CONFIGURATIONS [Debug|Release|...]] + [COMPONENT <component>] + [RENAME <name>] [OPTIONAL]) + +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. + +Installing Directories +^^^^^^^^^^^^^^^^^^^^^^ + +:: + + install(DIRECTORY dirs... DESTINATION <dir> + [FILE_PERMISSIONS permissions...] + [DIRECTORY_PERMISSIONS permissions...] + [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER] + [CONFIGURATIONS [Debug|Release|...]] + [COMPONENT <component>] [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. + +Custom Installation Logic +^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + install([[SCRIPT <file>] [CODE <code>]] [...]) + +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] + [PERMISSIONS permissions...] + [CONFIGURATIONS [Debug|Release|...]] + [EXPORT_LINK_INTERFACE_LIBRARIES] + [COMPONENT <component>]) + +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. + +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) + +will install the executable myexe to ``<prefix>/bin`` and code to import +it in the file ``<prefix>/lib/myproj/myproj.cmake``. 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 0000000000..7b6bd81141 --- /dev/null +++ b/Help/command/install_files.rst @@ -0,0 +1,39 @@ +install_files +------------- + +Deprecated. Use the install(FILES ) command instead. + +This command has been superceded by the install command. It is +provided for compatibility with older CMake code. The FILES form is +directly replaced by the FILES form of the install command. The +regexp form can be expressed more clearly using the GLOB form of the +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 CMAKE_INSTALL_PREFIX. diff --git a/Help/command/install_programs.rst b/Help/command/install_programs.rst new file mode 100644 index 0000000000..26789d8db4 --- /dev/null +++ b/Help/command/install_programs.rst @@ -0,0 +1,33 @@ +install_programs +---------------- + +Deprecated. Use the install(PROGRAMS ) command instead. + +This command has been superceded by the install command. It is +provided for compatibility with older CMake code. The FILES form is +directly replaced by the PROGRAMS form of the INSTALL command. The +regexp form can be expressed more clearly using the GLOB form of the +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 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 CMAKE_INSTALL_PREFIX. diff --git a/Help/command/install_targets.rst b/Help/command/install_targets.rst new file mode 100644 index 0000000000..caa933f4bc --- /dev/null +++ b/Help/command/install_targets.rst @@ -0,0 +1,17 @@ +install_targets +--------------- + +Deprecated. Use the install(TARGETS ) command instead. + +This command has been superceded by the 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 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 0000000000..bdc94cd734 --- /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 CMP0015. + +Note that this command is rarely necessary. Library locations +returned by find_package() and find_library() are absolute paths. +Pass these absolute library file paths directly to the +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 0000000000..d690c9b2d4 --- /dev/null +++ b/Help/command/link_libraries.rst @@ -0,0 +1,16 @@ +link_libraries +-------------- + +Deprecated. Use the target_link_libraries() command instead. + +Link libraries to all targets added later. + +:: + + link_libraries(library1 <debug | optimized> library2 ...) + +Specify a list of libraries to be linked into any following targets +(typically added with the add_executable or add_library calls). This +command is passed down to all subdirectories. The debug and optimized +strings may be used to indicate that the next library listed is to be +used only for that specific type of build. diff --git a/Help/command/list.rst b/Help/command/list.rst new file mode 100644 index 0000000000..aeb1e940a3 --- /dev/null +++ b/Help/command/list.rst @@ -0,0 +1,61 @@ +list +---- + +List operations. + +:: + + list(LENGTH <list> <output variable>) + list(GET <list> <element index> [<element index> ...] + <output variable>) + list(APPEND <list> [<element> ...]) + 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. + +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, 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 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 SET with +PARENT_SCOPE, 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 0000000000..b7484cb6d9 --- /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 0000000000..fc316d4d15 --- /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, 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 0000000000..258dc50aae --- /dev/null +++ b/Help/command/macro.rst @@ -0,0 +1,67 @@ +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 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. + +See the 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 + foreach(loop_var IN LISTS ARGN) # ARGN is not a variable + +In the first case you can use ``if(${ARGV1})``, in the second 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 0000000000..44dbe970fb --- /dev/null +++ b/Help/command/make_directory.rst @@ -0,0 +1,12 @@ +make_directory +-------------- + +Deprecated. Use the 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 0000000000..30b1289f7b --- /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 0000000000..38fde1d9d0 --- /dev/null +++ b/Help/command/math.rst @@ -0,0 +1,13 @@ +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 + - * / % | & ^ ~ << >> * / %. 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 0000000000..a20325a237 --- /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 0000000000..244ed07bab --- /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 CMakeDependentOption. diff --git a/Help/command/output_required_files.rst b/Help/command/output_required_files.rst new file mode 100644 index 0000000000..5e13557632 --- /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 0000000000..c601a0109b --- /dev/null +++ b/Help/command/project.rst @@ -0,0 +1,57 @@ +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>]]]] + [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``). + +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``). diff --git a/Help/command/qt_wrap_cpp.rst b/Help/command/qt_wrap_cpp.rst new file mode 100644 index 0000000000..81bbc06474 --- /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 0000000000..4e033a8b95 --- /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 0000000000..ddf0e9a2dc --- /dev/null +++ b/Help/command/remove.rst @@ -0,0 +1,12 @@ +remove +------ + +Deprecated. Use the 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 0000000000..566da6e6b6 --- /dev/null +++ b/Help/command/remove_definitions.rst @@ -0,0 +1,11 @@ +remove_definitions +------------------ + +Removes -D define flags added by add_definitions. + +:: + + remove_definitions(-DFOO -DBAR ...) + +Removes flags (added by 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 0000000000..899470c69a --- /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 include() or 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 0000000000..a876595ee3 --- /dev/null +++ b/Help/command/separate_arguments.rst @@ -0,0 +1,31 @@ +separate_arguments +------------------ + +Parse space-separated arguments into a semicolon-separated list. + +:: + + separate_arguments(<var> <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. + +:: + + separate_arguments(VARIABLE) + +Convert the value of VARIABLE 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 0000000000..7a595505fe --- /dev/null +++ b/Help/command/set.rst @@ -0,0 +1,116 @@ +set +--- + +Set a CMake, cache or environment variable to a given value. + +:: + + set(<variable> <value> + [[CACHE <type> <docstring> [FORCE]] | PARENT_SCOPE]) + +Within CMake sets <variable> to the value <value>. <value> is +expanded before <variable> is set to it. Normally, set will set a +regular CMake variable. If CACHE is present, then the <variable> is +put in the cache instead, unless it is already in the cache. See +section 'Variable types in CMake' below for details of regular and +cache variables and their interactions. If CACHE is used, <type> and +<docstring> are required. <type> is used by the CMake GUI to choose a +widget with which the user sets a value. The value for <type> may be +one of + +:: + + FILEPATH = File chooser dialog. + PATH = Directory chooser dialog. + STRING = Arbitrary string. + BOOL = Boolean ON/OFF checkbox. + INTERNAL = No GUI entry (used for persistent variables). + +If <type> is INTERNAL, the cache variable is marked as internal, and +will not be shown to the user in tools like cmake-gui. This is +intended for values that should be persisted in the cache, but which +users should not normally change. INTERNAL implies FORCE. + +Normally, set(...CACHE...) creates cache variables, but does not +modify them. If FORCE is specified, the value of the cache variable +is set, even if the variable is already in the cache. This should +normally be avoided, as it will remove any changes to the cache +variable's value by the user. + +If PARENT_SCOPE is present, 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). PARENT_SCOPE cannot be combined with CACHE. + +If <value> is not specified then the variable is removed instead of +set. See also: the unset() command. + +:: + + set(<variable> <value1> ... <valueN>) + +In this case <variable> is set to a semicolon separated list of +values. + +<variable> can be an environment variable such as: + +:: + + set( ENV{PATH} /home/martink ) + +in which case the environment variable will be set. + +*** Variable types in CMake *** + +In CMake there are two types of variables: normal variables and cache +variables. Normal variables are meant for the internal use of the +script (just like variables in most programming languages); they are +not persisted across CMake runs. Cache variables (unless set with +INTERNAL) are mostly intended for configuration settings where the +first CMake run determines a suitable default value, which the user +can then override, by editing the cache with tools such as ccmake or +cmake-gui. Cache variables are stored in the CMake cache file, and +are persisted across CMake runs. + +Both types can exist at the same time with the same name but different +values. When ${FOO} is evaluated, CMake first looks for a normal +variable 'FOO' in scope and uses it if set. If and only if no normal +variable exists then it falls back to the cache variable 'FOO'. + +Some examples: + +The code 'set(FOO "x")' sets the normal variable 'FOO'. It does not +touch the cache, but it will hide any existing cache value 'FOO'. + +The code 'set(FOO "x" CACHE ...)' checks for 'FOO' in the cache, +ignoring any normal variable of the same name. If 'FOO' is in the +cache then nothing happens to either the normal variable or the cache +variable. If 'FOO' is not in the cache, then it is added to the +cache. + +Finally, whenever a cache variable is added or modified by a command, +CMake also *removes* the normal variable of the same name from the +current scope so that an immediately following evaluation of it will +expose the newly cached value. + +Normally projects should avoid using normal and cache variables of the +same name, as this interaction can be hard to follow. However, in +some situations it can be useful. One example (used by some +projects): + +A project has a subproject in its source tree. The child project has +its own CMakeLists.txt, which is included from the parent +CMakeLists.txt using add_subdirectory(). Now, if the parent and the +child project provide the same option (for example a compiler option), +the parent gets the first chance to add a user-editable option to the +cache. Normally, the child would then use the same value that the +parent uses. However, it may be necessary to hard-code the value for +the child project's option while still allowing the user to edit the +value used by the parent project. The parent project can achieve this +simply by setting a normal variable with the same name as the option +in a scope sufficient to hide the option's cache variable from the +child completely. The parent has already set the cache variable, so +the child's set(...CACHE...) will do nothing, and evaluating the +option variable will use the value from the normal variable, which +hides the cache variable. diff --git a/Help/command/set_directory_properties.rst b/Help/command/set_directory_properties.rst new file mode 100644 index 0000000000..834013aab3 --- /dev/null +++ b/Help/command/set_directory_properties.rst @@ -0,0 +1,15 @@ +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. If the +property is not found, CMake will report an error. The properties +include: INCLUDE_DIRECTORIES, LINK_DIRECTORIES, +INCLUDE_REGULAR_EXPRESSION, and ADDITIONAL_MAKE_CLEAN_FILES. +ADDITIONAL_MAKE_CLEAN_FILES is a list of files that will be cleaned as +a part of "make clean" stage. diff --git a/Help/command/set_property.rst b/Help/command/set_property.rst new file mode 100644 index 0000000000..8cb963edf0 --- /dev/null +++ b/Help/command/set_property.rst @@ -0,0 +1,43 @@ +set_property +------------ + +Set a named property in a given scope. + +:: + + set_property(<GLOBAL | + DIRECTORY [dir] | + TARGET [target1 [target2 ...]] | + SOURCE [src1 [src2 ...]] | + 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). + +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. diff --git a/Help/command/set_source_files_properties.rst b/Help/command/set_source_files_properties.rst new file mode 100644 index 0000000000..8ea02a375c --- /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 properties documentation for those known to CMake. +Unrecognized properties are ignored. 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 0000000000..f65ee24946 --- /dev/null +++ b/Help/command/set_target_properties.rst @@ -0,0 +1,104 @@ +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 GET_TARGET_PROPERTY command. + +Properties that affect the name of a target's output file are as +follows. The PREFIX and SUFFIX properties override the default target +name prefix (such as "lib") and suffix (such as ".so"). IMPORT_PREFIX +and IMPORT_SUFFIX are the equivalent properties for the import library +corresponding to a DLL (for SHARED library targets). OUTPUT_NAME sets +the real name of a target when it is built and can be used to help +create two targets of the same name even though CMake requires unique +logical target names. There is also a <CONFIG>_OUTPUT_NAME that can +set the output name on a per-configuration basis. <CONFIG>_POSTFIX +sets a postfix for the real name of the target when it is built under +the configuration named by <CONFIG> (in upper-case, such as +"DEBUG_POSTFIX"). The value of this property is initialized when the +target is created to the value of the variable CMAKE_<CONFIG>_POSTFIX +(except for executable targets because earlier CMake versions which +did not use this variable for executables). + +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. +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. The COMPILE_FLAGS +property sets additional compiler flags used to build sources within +the target. It may also be used to pass additional preprocessor +definitions. + +The LINKER_LANGUAGE property is used to change the tool used to link +an executable or shared library. The default is set the language to +match the files in the library. CXX and C are common values for this +property. + +For shared libraries 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. For +executables VERSION can be used to specify the build version. When +building or installing appropriate symlinks are created if the +platform supports symlinks. 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. + +There are a few properties used to specify RPATH rules. INSTALL_RPATH +is a semicolon-separated list specifying the rpath to use in installed +targets (for platforms that support it). 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. +SKIP_BUILD_RPATH is a boolean specifying whether to skip automatic +generation of an rpath allowing the target to run from the build tree. +BUILD_WITH_INSTALL_RPATH is a boolean specifying whether to link the +target in the build tree with the INSTALL_RPATH. This takes +precedence over SKIP_BUILD_RPATH and avoids the need for relinking +before installation. 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. When the target is created +the values of the variables CMAKE_INSTALL_RPATH, +CMAKE_INSTALL_RPATH_USE_LINK_PATH, CMAKE_SKIP_BUILD_RPATH, +CMAKE_BUILD_WITH_INSTALL_RPATH, and CMAKE_INSTALL_NAME_DIR are used to +initialize these properties. + +PROJECT_LABEL can be used to change the name of the target in an IDE +like visual studio. VS_KEYWORD can be set to change the visual studio +keyword, for example Qt integration works better if this is set to +Qt4VSv1.0. + +VS_SCC_PROJECTNAME, VS_SCC_LOCALPATH, VS_SCC_PROVIDER and +VS_SCC_AUXPATH can be set to add support for source control bindings +in a Visual Studio project file. + +VS_GLOBAL_<variable> can be set to add a Visual Studio +project-specific global variable. Qt integration works better if +VS_GLOBAL_QtVersion is set to the Qt version FindQt4.cmake found. For +example, "4.7.3" + +The PRE_INSTALL_SCRIPT and POST_INSTALL_SCRIPT properties are the old +way to specify CMake scripts to run before and after installing a +target. They are used only when the old INSTALL_TARGETS command is +used to install the target. Use the INSTALL command instead. + +The EXCLUDE_FROM_DEFAULT_BUILD property is used by the visual studio +generators. If it is set to 1 the target will not be part of the +default build when you select "Build Solution". This can also be set +on a per-configuration basis using +EXCLUDE_FROM_DEFAULT_BUILD_<CONFIG>. diff --git a/Help/command/set_tests_properties.rst b/Help/command/set_tests_properties.rst new file mode 100644 index 0000000000..e29d690476 --- /dev/null +++ b/Help/command/set_tests_properties.rst @@ -0,0 +1,36 @@ +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 property is not found, CMake +will report an error. Generator expressions will be expanded the same +as supported by the test's add_test call. The properties include: + +WILL_FAIL: If set to true, this will invert the pass/fail flag of the +test. + +PASS_REGULAR_EXPRESSION: 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: PASS_REGULAR_EXPRESSION "TestPassed;All ok" + +FAIL_REGULAR_EXPRESSION: If set, if the output will match to one of +specified regular expressions, the test will fail. + +:: + + Example: FAIL_REGULAR_EXPRESSION "[^a-z]Error;ERROR;Failed" + +Both PASS_REGULAR_EXPRESSION and FAIL_REGULAR_EXPRESSION expect a list +of regular expressions. + +TIMEOUT: Setting this will limit the test runtime to the number of +seconds specified. diff --git a/Help/command/site_name.rst b/Help/command/site_name.rst new file mode 100644 index 0000000000..e17c1ee682 --- /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 0000000000..6e3829c044 --- /dev/null +++ b/Help/command/source_group.rst @@ -0,0 +1,44 @@ +source_group +------------ + +Define a grouping for source files in IDE project generation. + +.. code-block:: cmake + + source_group(<name> [FILES <src>...] [REGULAR_EXPRESSION <regex>]) + +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: + +``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 may contain backslashes to specify subgroups: + +.. code-block:: cmake + + source_group(outer\\inner ...) + +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 0000000000..07d0ff3f2e --- /dev/null +++ b/Help/command/string.rst @@ -0,0 +1,173 @@ +string +------ + +String operations. + +:: + + string(REGEX MATCH <regular_expression> + <output variable> <input> [<input>...]) + string(REGEX MATCHALL <regular_expression> + <output variable> <input> [<input>...]) + string(REGEX REPLACE <regular_expression> + <replace_expression> <output variable> + <input> [<input>...]) + string(REPLACE <match_string> + <replace_string> <output variable> + <input> [<input>...]) + string(CONCAT <output variable> [<input>...]) + string(<MD5|SHA1|SHA224|SHA256|SHA384|SHA512> + <output variable> <input>) + string(COMPARE EQUAL <string1> <string2> <output variable>) + string(COMPARE NOTEQUAL <string1> <string2> <output variable>) + string(COMPARE LESS <string1> <string2> <output variable>) + string(COMPARE GREATER <string1> <string2> <output variable>) + string(ASCII <number> [<number> ...] <output variable>) + string(CONFIGURE <string1> <output variable> + [@ONLY] [ESCAPE_QUOTES]) + string(TOUPPER <string1> <output variable>) + string(TOLOWER <string1> <output variable>) + string(LENGTH <string> <output variable>) + string(SUBSTRING <string> <begin> <length> <output variable>) + string(STRIP <string> <output variable>) + string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>] + [RANDOM_SEED <seed>] <output variable>) + string(FIND <string> <substring> <output variable> [REVERSE]) + string(TIMESTAMP <output variable> [<format string>] [UTC]) + string(MAKE_C_IDENTIFIER <input string> <output variable>) + string(GENEX_STRIP <input string> <output variable>) + string(UUID <output variable> NAMESPACE <namespace> NAME <name> + TYPE <MD5|SHA1> [UPPER]) + +REGEX MATCH will match the regular expression once and store the match +in the output variable. + +REGEX MATCHALL will match the regular expression as many times as +possible and store the matches in the output variable as a list. + +REGEX REPLACE will match the regular expression as many times as +possible and substitute the replacement expression for the match in +the output. 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. + +REPLACE will replace all occurrences of match_string in the input with +replace_string and store the result in the output. + +CONCAT will concatenate all the input arguments together and store +the result in the named output variable. + +MD5, SHA1, SHA224, SHA256, SHA384, and SHA512 will compute a +cryptographic hash of the input string. + +COMPARE EQUAL/NOTEQUAL/LESS/GREATER will compare the strings and store +true or false in the output variable. + +ASCII will convert all numbers into corresponding ASCII characters. + +CONFIGURE will transform a string like CONFIGURE_FILE transforms a +file. + +TOUPPER/TOLOWER will convert string to upper/lower characters. + +LENGTH will return a given string's length. + +SUBSTRING will return a substring of a given string. If length is -1 +the remainder of the string starting at begin will be returned. + +STRIP will return a substring of a given string with leading and +trailing spaces removed. + +RANDOM will 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. + +FIND will return the position where the given substring was found in +the supplied string. If the REVERSE flag was used, the command will +search for the position of the last occurrence of the specified +substring. + +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. if( MATCHES ), in the variables CMAKE_MATCH_(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". + +TIMESTAMP will 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: + +:: + + %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). + %M The minute of the current hour (00-59). + %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) + %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. + +MAKE_C_IDENTIFIER will write a string which can be used as an +identifier in C. + +``GENEX_STRIP`` will strip any +:manual:`generator expressions <cmake-generator-expressions(7)>` from the +``input string`` and store the result in the ``output variable``. + +UUID creates 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 0000000000..5676c8f40b --- /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 0000000000..dee49f8e05 --- /dev/null +++ b/Help/command/subdirs.rst @@ -0,0 +1,24 @@ +subdirs +------- + +Deprecated. Use the 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 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 0000000000..3c9fe87585 --- /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 0000000000..29a8b413cb --- /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. diff --git a/Help/command/target_compile_options.rst b/Help/command/target_compile_options.rst new file mode 100644 index 0000000000..0fdeba6000 --- /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 +:prop_tgt:`IMPORTED Target`. 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_tgt:`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 0000000000..581bacef56 --- /dev/null +++ b/Help/command/target_include_directories.rst @@ -0,0 +1,56 @@ +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 or targets 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 + ) diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst new file mode 100644 index 0000000000..39537a7035 --- /dev/null +++ b/Help/command/target_link_libraries.rst @@ -0,0 +1,152 @@ +target_link_libraries +--------------------- + +Link a target to given libraries. + +:: + + target_link_libraries(<target> [item1 [item2 [...]]] + [[debug|optimized|general] <item>] ...) + +Specify libraries or flags to use when linking a given target. The +named ``<target>`` must have been created in the current directory by a +command such as :command:`add_executable` or :command:`add_library`. The +remaining arguments specify library names or flags. Repeated calls for +the same ``<target>`` append items in the order called. + +If a library name matches that of another target in the project a +dependency will automatically be added in the build system to make sure +the library being linked is up-to-date before the target links. 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 of ``<target>``. + +A ``debug``, ``optimized``, or ``general`` keyword indicates that the +library immediately following it is to 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 (assumed if omitted). Higher granularity may be achieved for +per-configuration rules by creating and linking to +:ref:`IMPORTED library targets <Imported Targets>`. + +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. + +CMake will also propagate :ref:`usage requirements <Target Usage Requirements>` +from linked library targets. Usage requirements of dependencies affect +compilation of sources in the ``<target>``. + +If an ``<item>`` is a library in a Mac OX 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. + +-------------------------------------------------------------------------- + +:: + + target_link_libraries(<target> + <PRIVATE|PUBLIC|INTERFACE> <lib> ... + [<PRIVATE|PUBLIC|INTERFACE> <lib> ... ] ...]) + +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>``. + +-------------------------------------------------------------------------- + +:: + + target_link_libraries(<target> LINK_INTERFACE_LIBRARIES + [[debug|optimized|general] <lib>] ...) + +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``. + +-------------------------------------------------------------------------- + +:: + + target_link_libraries(<target> + <LINK_PRIVATE|LINK_PUBLIC> + [[debug|optimized|general] <lib>] ... + [<LINK_PRIVATE|LINK_PUBLIC> + [[debug|optimized|general] <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`). + +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 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. + +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. diff --git a/Help/command/target_sources.rst b/Help/command/target_sources.rst new file mode 100644 index 0000000000..ff756b4ff6 --- /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 +:prop_tgt:`IMPORTED Target`. + +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 0000000000..224c67b45d --- /dev/null +++ b/Help/command/try_compile.rst @@ -0,0 +1,72 @@ +try_compile +----------- + +Try building some code. + +:: + + try_compile(RESULT_VAR <bindir> <srcdir> + <projectName> [targetName] [CMAKE_FLAGS flags...] + [OUTPUT_VARIABLE <var>]) + +Try building a project. 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. + +:: + + try_compile(RESULT_VAR <bindir> <srcfile|SOURCES srcfile...> + [CMAKE_FLAGS flags...] + [COMPILE_DEFINITIONS flags...] + [LINK_LIBRARIES libs...] + [OUTPUT_VARIABLE <var>] + [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]) + +Try building an executable from one or more source files. 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. Specify COPY_FILE to get a copy +of the linked executable at the given fileName and optionally +COPY_FILE_ERROR to capture any error. + +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. + +Some extra flags that can be included are, INCLUDE_DIRECTORIES, +LINK_DIRECTORIES, and LINK_LIBRARIES. COMPILE_DEFINITIONS are +-Ddefinition that will be passed to the compile line. + +The srcfile signature also accepts a LINK_LIBRARIES argument which may +contain a list of libraries or IMPORTED targets which will be linked +to in the generated project. If LINK_LIBRARIES is specified as a +parameter to try_compile, then any LINK_LIBRARIES passed as +CMAKE_FLAGS will be ignored. + +try_compile creates a CMakeList.txt file on the fly that looks like +this: + +:: + + add_definitions( <expanded COMPILE_DEFINITIONS from calling cmake>) + include_directories(${INCLUDE_DIRECTORIES}) + link_directories(${LINK_DIRECTORIES}) + add_executable(cmTryCompileExec sources) + target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES}) + +In both versions of the command, if OUTPUT_VARIABLE is specified, then +the output from the build process is stored in the given variable. +The success or failure of the try_compile, i.e. TRUE or FALSE +respectively, is returned in RESULT_VAR. CMAKE_FLAGS can be used to +pass -DVAR:TYPE=VALUE flags to the cmake that is run during the build. +Set variable CMAKE_TRY_COMPILE_CONFIGURATION to choose a build +configuration. diff --git a/Help/command/try_run.rst b/Help/command/try_run.rst new file mode 100644 index 0000000000..9a17ad9660 --- /dev/null +++ b/Help/command/try_run.rst @@ -0,0 +1,52 @@ +try_run +------- + +Try compiling and then running some code. + +:: + + try_run(RUN_RESULT_VAR COMPILE_RESULT_VAR + bindir srcfile [CMAKE_FLAGS <Flags>] + [COMPILE_DEFINITIONS <flags>] + [COMPILE_OUTPUT_VARIABLE comp] + [RUN_OUTPUT_VARIABLE run] + [OUTPUT_VARIABLE var] + [ARGS <arg1> <arg2>...]) + +Try compiling a srcfile. Return TRUE or FALSE for success or failure +in COMPILE_RESULT_VAR. Then if the compile succeeded, run the +executable and return 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. COMPILE_OUTPUT_VARIABLE specifies the variable +where the output from the compile step goes. RUN_OUTPUT_VARIABLE +specifies the variable where the output from the running executable +goes. + +For compatibility reasons OUTPUT_VARIABLE is still supported, which +gives you the output from the compile and run step combined. + +Cross compiling issues + +When cross compiling, the executable compiled in the first step +usually cannot be run on the build host. try_run() checks the +CMAKE_CROSSCOMPILING variable to detect whether CMake is in +crosscompiling mode. If that's the case, it will still try to compile +the executable, but it will not try to run the executable. 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 variables are RUN_RESULT_VAR (explanation see above) and if +RUN_OUTPUT_VARIABLE (or OUTPUT_VARIABLE) was used, an additional cache +variable RUN_RESULT_VAR__COMPILE_RESULT_VAR__TRYRUN_OUTPUT.This is +intended to hold stdout and stderr from the executable. + +In order to make cross compiling your project easier, use try_run only +if really required. If you use try_run, use RUN_OUTPUT_VARIABLE (or +OUTPUT_VARIABLE) only if really required. Using them will require +that when crosscompiling, 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 if(CMAKE_CROSSCOMPILING) and provide an +easy-to-preset alternative for this case. + +Set variable CMAKE_TRY_COMPILE_CONFIGURATION to choose a build +configuration. diff --git a/Help/command/unset.rst b/Help/command/unset.rst new file mode 100644 index 0000000000..d8f0dcdb27 --- /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 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 0000000000..6f4d7aca64 --- /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 0000000000..5122e520ac --- /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 0000000000..831dd0023c --- /dev/null +++ b/Help/command/variable_requires.rst @@ -0,0 +1,22 @@ +variable_requires +----------------- + +Disallowed. See CMake Policy :policy:`CMP0035`. + +Use the 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 0000000000..a2df058eb3 --- /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 0000000000..72c055de1d --- /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 endwhile are recorded +without being invoked. Once the 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 if command. diff --git a/Help/command/write_file.rst b/Help/command/write_file.rst new file mode 100644 index 0000000000..015514bb3c --- /dev/null +++ b/Help/command/write_file.rst @@ -0,0 +1,20 @@ +write_file +---------- + +Deprecated. Use the 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: file(WRITE ... and 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 configure_file if you want to generate input +files to CMake. diff --git a/Help/generator/Borland Makefiles.rst b/Help/generator/Borland Makefiles.rst new file mode 100644 index 0000000000..c00d00a86b --- /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 0000000000..01798c7f05 --- /dev/null +++ b/Help/generator/CodeBlocks.rst @@ -0,0 +1,25 @@ +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 - 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 0000000000..dbc46d72be --- /dev/null +++ b/Help/generator/CodeLite.rst @@ -0,0 +1,24 @@ +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 PROJECT() call. 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 0000000000..eb68bf0945 --- /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/KDevelop3.rst b/Help/generator/KDevelop3.rst new file mode 100644 index 0000000000..eaa218bc8e --- /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 0000000000..9b61a93b32 --- /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 0000000000..0b89126925 --- /dev/null +++ b/Help/generator/MSYS Makefiles.rst @@ -0,0 +1,7 @@ +MSYS Makefiles +-------------- + +Generates MSYS makefiles. + +The makefiles use /bin/sh as the shell. They require msys to be +installed on the machine. diff --git a/Help/generator/MinGW Makefiles.rst b/Help/generator/MinGW Makefiles.rst new file mode 100644 index 0000000000..ed4ccdd0f0 --- /dev/null +++ b/Help/generator/MinGW Makefiles.rst @@ -0,0 +1,7 @@ +MinGW Makefiles +--------------- + +Generates a make file for use with mingw32-make. + +The makefiles generated use cmd.exe as the shell. They do not require +msys or a unix shell. diff --git a/Help/generator/NMake Makefiles JOM.rst b/Help/generator/NMake Makefiles JOM.rst new file mode 100644 index 0000000000..3a8744c1e1 --- /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 0000000000..89f2479b76 --- /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 0000000000..08f74fbfdd --- /dev/null +++ b/Help/generator/Ninja.rst @@ -0,0 +1,8 @@ +Ninja +----- + +Generates build.ninja files (experimental). + +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. diff --git a/Help/generator/Sublime Text 2.rst b/Help/generator/Sublime Text 2.rst new file mode 100644 index 0000000000..0597a9528f --- /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 0000000000..97d74a853e --- /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/Visual Studio 10 2010.rst b/Help/generator/Visual Studio 10 2010.rst new file mode 100644 index 0000000000..77ea9df02b --- /dev/null +++ b/Help/generator/Visual Studio 10 2010.rst @@ -0,0 +1,19 @@ +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. + +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. diff --git a/Help/generator/Visual Studio 11 2012.rst b/Help/generator/Visual Studio 11 2012.rst new file mode 100644 index 0000000000..5fa7f2c76b --- /dev/null +++ b/Help/generator/Visual Studio 11 2012.rst @@ -0,0 +1,22 @@ +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. + +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. diff --git a/Help/generator/Visual Studio 12 2013.rst b/Help/generator/Visual Studio 12 2013.rst new file mode 100644 index 0000000000..2c3b119a4c --- /dev/null +++ b/Help/generator/Visual Studio 12 2013.rst @@ -0,0 +1,19 @@ +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. + +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. diff --git a/Help/generator/Visual Studio 14.rst b/Help/generator/Visual Studio 14.rst new file mode 100644 index 0000000000..d621b7e5ba --- /dev/null +++ b/Help/generator/Visual Studio 14.rst @@ -0,0 +1,16 @@ +Visual Studio 14 +---------------- + +Generates Visual Studio 14 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 14 Win64`` + Specify target platform ``x64``. + +``Visual Studio 14 ARM`` + Specify target platform ``ARM``. diff --git a/Help/generator/Visual Studio 6.rst b/Help/generator/Visual Studio 6.rst new file mode 100644 index 0000000000..d619354661 --- /dev/null +++ b/Help/generator/Visual Studio 6.rst @@ -0,0 +1,4 @@ +Visual Studio 6 +--------------- + +Generates Visual Studio 6 project files. 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 0000000000..20341402bb --- /dev/null +++ b/Help/generator/Visual Studio 7 .NET 2003.rst @@ -0,0 +1,4 @@ +Visual Studio 7 .NET 2003 +------------------------- + +Generates Visual Studio .NET 2003 project files. diff --git a/Help/generator/Visual Studio 7.rst b/Help/generator/Visual Studio 7.rst new file mode 100644 index 0000000000..d0eb719e55 --- /dev/null +++ b/Help/generator/Visual Studio 7.rst @@ -0,0 +1,4 @@ +Visual Studio 7 +--------------- + +Generates Visual Studio .NET 2002 project files. diff --git a/Help/generator/Visual Studio 8 2005.rst b/Help/generator/Visual Studio 8 2005.rst new file mode 100644 index 0000000000..29012c3715 --- /dev/null +++ b/Help/generator/Visual Studio 8 2005.rst @@ -0,0 +1,16 @@ +Visual Studio 8 2005 +-------------------- + +Generates Visual Studio 8 2005 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 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 0000000000..40471b92e6 --- /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 0000000000..09bdc3d9f6 --- /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 0000000000..d8a6790644 --- /dev/null +++ b/Help/generator/Xcode.rst @@ -0,0 +1,4 @@ +Xcode +----- + +Generate Xcode project files. diff --git a/Help/include/COMPILE_DEFINITIONS_DISCLAIMER.txt b/Help/include/COMPILE_DEFINITIONS_DISCLAIMER.txt new file mode 100644 index 0000000000..6797d0e2bc --- /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/index.rst b/Help/index.rst new file mode 100644 index 0000000000..2d3f15645a --- /dev/null +++ b/Help/index.rst @@ -0,0 +1,59 @@ +.. 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-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 0000000000..f6f707df50 --- /dev/null +++ b/Help/manual/LINKS.txt @@ -0,0 +1,25 @@ +The following resources are available to get help using CMake: + +Home Page + http://www.cmake.org + + The primary starting point for learning about CMake. + +Frequently Asked Questions + http://www.cmake.org/Wiki/CMake_FAQ + + A Wiki is provided containing answers to frequently asked questions. + +Online Documentation + http://www.cmake.org/HTML/Documentation.html + + Links to available documentation may be found on this web page. + +Mailing List + http://www.cmake.org/HTML/MailingLists.html + + 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 http://www.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 0000000000..363d0aaca4 --- /dev/null +++ b/Help/manual/OPTIONS_BUILD.txt @@ -0,0 +1,75 @@ +``-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>`` + 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. + +``-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 + Generators section. + +``-T <toolset-name>`` + Specify toolset name if supported by generator. + + Some CMake generators support a toolset name to be given to the + native build system to choose a compiler. This is supported only on + specific generators: + + :: + + Visual Studio >= 10 + Xcode >= 3.0 + + See native build system documentation for allowed toolset names. + +``-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. This is supported only on + specific generators:: + + Visual Studio >= 8 + + See native build system documentation for allowed platform names. + +``-Wno-dev`` + Suppress developer warnings. + + Suppress warnings that are meant for the author of the + CMakeLists.txt files. + +``-Wdev`` + Enable developer warnings. + + Enable warnings that are meant for the author of the CMakeLists.txt + files. diff --git a/Help/manual/OPTIONS_HELP.txt b/Help/manual/OPTIONS_HELP.txt new file mode 100644 index 0000000000..feeca7dc36 --- /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 0000000000..a5fe191683 --- /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 0000000000..1ce9a7ee69 --- /dev/null +++ b/Help/manual/cmake-buildsystem.7.rst @@ -0,0 +1,889 @@ +.. cmake-manual-description: CMake Buildsystem Reference + +cmake-buildsystem(7) +******************** + +.. only:: html or latex + + .. 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. + +.. code-block:: cmake + + add_library(archive MODULE 7z.cpp) + +.. _`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 only be used locally as sources in a buildsystem -- +they may not be installed, exported, or 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. + +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>``. + +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 repective 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. + +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:INTERFACE_INCLUDE_DIRECTORIES:lib3>) + +.. _`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 lib1Version2 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 + $<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 Files +------------ + +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. + +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 interchangably 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`, and +:prop_tgt:`INTERFACE_SOURCES`, +:prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE`. +Only the ``INTERFACE`` modes of the :command:`target_include_directories`, +:command:`target_compile_definitions`, :command:`target_compile_options`, +:command:`target_sources`, and :command:`target_link_libraries` commands +may be used with ``INTERFACE`` libraries. + +A primary use-case for ``INTERFACE`` libraries is header-only libraries. + +.. code-block:: cmake + + add_library(Eigen INTERFACE) + target_include_directories(Eigen INTERFACE + $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src> + $<INSTALL_INTERFACE:include/Eigen> + ) + + add_executable(exe1 exe1.cpp) + target_link_libraries(exe1 Eigen) + +Here, the usage requirements from the ``Eigen`` target are consumed and used +when compiling, but it has no effect on linking. + +Another use-case is to employ an entirely target-focussed design for usage +requirements: + +.. code-block:: cmake + + add_library(pic_on INTERFACE) + set_property(TARGET pic_on PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON) + add_library(pic_off INTERFACE) + set_property(TARGET pic_off PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE OFF) + + add_library(enable_rtti INTERFACE) + target_compile_options(enable_rtti INTERFACE + $<$<OR:$<COMPILER_ID:GNU>,$<COMPILER_ID:Clang>>:-rtti> + ) + + add_executable(exe1 exe1.cpp) + target_link_libraries(exe1 pic_on enable_rtti) + +This way, the build specification of ``exe1`` is expressed entirely as linked +targets, and the complexity of compiler-specific flags is encapsulated in an +``INTERFACE`` library target. + +The properties permitted to be set on or read from an ``INTERFACE`` library +are: + +* Properties matching ``INTERFACE_*`` +* Built-in properties matching ``COMPATIBLE_INTERFACE_*`` +* ``EXPORT_NAME`` +* ``IMPORTED`` +* ``NAME`` +* Properties matching ``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 0000000000..8ff73a4605 --- /dev/null +++ b/Help/manual/cmake-commands.7.rst @@ -0,0 +1,153 @@ +.. cmake-manual-description: CMake Language Command Reference + +cmake-commands(7) +***************** + +.. only:: html or latex + + .. contents:: + +Normal Commands +=============== + +These commands may be used freely 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/break + /command/build_command + /command/cmake_host_system_information + /command/cmake_minimum_required + /command/cmake_policy + /command/configure_file + /command/create_test_sourcelist + /command/define_property + /command/elseif + /command/else + /command/enable_language + /command/enable_testing + /command/endforeach + /command/endfunction + /command/endif + /command/endmacro + /command/endwhile + /command/execute_process + /command/export + /command/file + /command/find_file + /command/find_library + /command/find_package + /command/find_path + /command/find_program + /command/fltk_wrap_ui + /command/foreach + /command/function + /command/get_cmake_property + /command/get_directory_property + /command/get_filename_component + /command/get_property + /command/get_source_file_property + /command/get_target_property + /command/get_test_property + /command/if + /command/include_directories + /command/include_external_msproject + /command/include_regular_expression + /command/include + /command/install + /command/link_directories + /command/list + /command/load_cache + /command/load_command + /command/macro + /command/mark_as_advanced + /command/math + /command/message + /command/option + /command/project + /command/qt_wrap_cpp + /command/qt_wrap_ui + /command/remove_definitions + /command/return + /command/separate_arguments + /command/set_directory_properties + /command/set_property + /command/set + /command/set_source_files_properties + /command/set_target_properties + /command/set_tests_properties + /command/site_name + /command/source_group + /command/string + /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 + /command/unset + /command/variable_watch + /command/while + +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/link_libraries + /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 + +.. _`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 diff --git a/Help/manual/cmake-compile-features.7.rst b/Help/manual/cmake-compile-features.7.rst new file mode 100644 index 0000000000..8a2fe30a45 --- /dev/null +++ b/Help/manual/cmake-compile-features.7.rst @@ -0,0 +1,294 @@ +.. cmake-manual-description: CMake Compile Features Reference + +cmake-compile-features(7) +************************* + +.. only:: html or latex + + .. 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 execptions, 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. + +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) + target_link_libraries(foo + INTERFACE + "$<$<COMPILE_FEATURES:cxx_variadic_templates>:${CMAKE_CURRENT_SOURCE_DIR}/with_variadics>" + "$<$<NOT:$<COMPILE_FEATURES:cxx_variadic_templates>>:${CMAKE_CURRENT_SOURCE_DIR}/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) diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst new file mode 100644 index 0000000000..625dac06b0 --- /dev/null +++ b/Help/manual/cmake-developer.7.rst @@ -0,0 +1,1144 @@ +.. cmake-manual-description: CMake Developer Reference + +cmake-developer(7) +****************** + +.. only:: html or latex + + .. contents:: + +Introduction +============ + +This manual is intended for reference by developers modifying the CMake +source tree itself. + + +Permitted C++ Subset +==================== + +CMake is required to build with ancient C++ compilers and standard library +implementations. Some common C++ constructs may not be used in CMake in order +to build with such toolchains. + +std::vector::at +--------------- + +The ``at()`` member function of ``std::vector`` may not be used. Use +``operator[]`` instead: + +.. code-block:: c++ + + std::vector<int> someVec = getVec(); + int i1 = someVec.at(5); // Wrong + int i2 = someVec[5]; // Ok + +std::string::append and std::string::clear +------------------------------------------ + +The ``append()`` and ``clear()`` member functions of ``std::string`` may not +be used. Use ``operator+=`` and ``operator=`` instead: + +.. code-block:: c++ + + std::string stringBuilder; + stringBuilder.append("chunk"); // Wrong + stringBuilder.clear(); // Wrong + stringBuilder += "chunk"; // Ok + stringBuilder = ""; // Ok + +std::set const iterators +------------------------ + +The ``find()`` member function of a ``const`` ``std::set`` instance may not be +used in a comparison with the iterator returned by ``end()``: + +.. code-block:: c++ + + const std::set<std::string>& someSet = getSet(); + if (someSet.find("needle") == someSet.end()) // Wrong + { + // ... + } + +The return value of ``find()`` must be assigned to an intermediate +``const_iterator`` for comparison: + +.. code-block:: c++ + + const std::set<std::string>& someSet; + const std::set<std::string>::const_iterator i = someSet.find("needle"); + if (i != propSet.end()) // Ok + { + // ... + } + +Char Array to ``string`` Conversions with Algorithms +---------------------------------------------------- + +In some implementations, algorithms operating on iterators to a container of +``std::string`` can not accept a ``const char*`` value: + +.. code-block:: c++ + + const char* dir = /*...*/; + std::vector<std::string> vec; + // ... + std::binary_search(vec.begin(), vec.end(), dir); // Wrong + +The ``std::string`` may need to be explicitly constructed: + +.. code-block:: c++ + + const char* dir = /*...*/; + std::vector<std::string> vec; + // ... + std::binary_search(vec.begin(), vec.end(), std::string(dir)); // Ok + +std::auto_ptr +------------- + +Some implementations have a ``std::auto_ptr`` which can not be used as a +return value from a function. ``std::auto_ptr`` may not be used. Use +``cmsys::auto_ptr`` instead. + +std::vector::insert and std::set +-------------------------------- + +Use of ``std::vector::insert`` with an iterator whose ``element_type`` requires +conversion is not allowed: + +.. code-block:: c++ + + std::set<const char*> theSet; + std::vector<std::string> theVector; + theVector.insert(theVector.end(), theSet.begin(), theSet.end()); // Wrong + +A loop must be used instead: + +.. code-block:: c++ + + std::set<const char*> theSet; + std::vector<std::string> theVector; + for(std::set<const char*>::iterator li = theSet.begin(); + li != theSet.end(); ++li) + { + theVector.push_back(*li); + } + +std::set::insert +---------------- + +Use of ``std::set::insert`` is not allowed with any source container: + +.. code-block:: c++ + + std::set<cmTarget*> theSet; + theSet.insert(targets.begin(), targets.end()); // Wrong + +A loop must be used instead: + +.. code-block:: c++ + + ConstIterator it = targets.begin(); + const ConstIterator end = targets.end(); + for ( ; it != end; ++it) + { + theSet.insert(*it); + } + +.. MSVC6, SunCC 5.9 + +Template Parameter Defaults +--------------------------- + +On ancient compilers, C++ template must use template parameters in function +arguments. If no parameter of that type is needed, the common workaround is +to add a defaulted pointer to the type to the templated function. However, +this does not work with other ancient compilers: + +.. code-block:: c++ + + template<typename PropertyType> + PropertyType getTypedProperty(cmTarget* tgt, const char* prop, + PropertyType* = 0) // Wrong + { + + } + +.. code-block:: c++ + + template<typename PropertyType> + PropertyType getTypedProperty(cmTarget* tgt, const char* prop, + PropertyType*) // Ok + { + + } + +and invoke it with the value ``0`` explicitly in all cases. + +std::min and std::max +--------------------- + +``min`` and ``max`` are defined as macros on some systems. ``std::min`` and +``std::max`` may not be used. Use ``cmMinimum`` and ``cmMaximum`` instead. + +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. + +Templates +--------- + +Some template code is permitted, but with some limitations. Member templates +may not be used, and template friends may not be used. + +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. + +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:``. +Add to the top of ``Modules/<module-name>.cmake`` 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: + +.. code-block:: cmake + + #[[.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: + +.. code-block:: cmake + + #.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() + +After the top documentation block, leave a *BLANK* line, and then add a +copyright and licence notice block like this one (change only the year +range and name) + +.. code-block:: cmake + + #============================================================================= + # Copyright 2009-2011 Your Name + # + # Distributed under the OSI-approved BSD License (the "License"); + # see accompanying file Copyright.txt for details. + # + # This software is distributed WITHOUT ANY WARRANTY; without even the + # implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + # See the License for more information. + #============================================================================= + # (To distribute this file outside of CMake, substitute the full + # License text for the above reference.) + +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 +------------ + +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. + +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 +``<package>Config.cmake`` files as possible, by providing imported +targets. As well as matching how ``*Config.cmake`` files work, the +libraries, include directories and compile definitions are all set just +by using the target in a :command:`target_link_libraries` call. The +disadvantage is that ``*Config.cmake`` files of projects that use +imported targets from find modules may require more work to make sure +those imported targets that are in the link interface are available. + +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 sytem 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. + +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 documentation. CMake's documentation +system requires you to start the file 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. + +After the documentation, leave a blank line, and then add a copyright and +licence notice block + +.. code-block:: cmake + + #============================================================================= + # Copyright 2009-2011 Your Name + # + # Distributed under the OSI-approved BSD License (the "License"); + # see accompanying file Copyright.txt for details. + # + # This software is distributed WITHOUT ANY WARRANTY; without even the + # implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + # See the License for more information. + #============================================================================= + # (To distribute this file outside of CMake, substitute the full + # License text for the above reference.) + +If the module is new to CMake, you may want to provide a warning for +projects that do not require a high enough CMake version. + +.. code-block:: cmake + + if(CMAKE_MINIMUM_REQUIRED_VERSION VERSION_LESS 3.0.0) + message(AUTHOR_WARNING "Your project should require at least CMake 3.0.0 to use FindFoo.cmake") + endif() + +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} + # if you need to put #include <Foo/foo.h> in your code, add: + 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. + +We should also provide some information about the package, such as where to +download it. + +.. code-block:: cmake + + include(FeatureSummary) + set_package_properties(Foo PROPERTIES + URL "http://www.foo.example.com/" + DESCRIPTION "A library for doing useful things" + ) + +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 0000000000..77259a0f37 --- /dev/null +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -0,0 +1,226 @@ +.. cmake-manual-description: CMake Generator Expressions + +cmake-generator-expressions(7) +****************************** + +.. only:: html or latex + + .. 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. + +``$<0:...>`` + Empty string (ignores ``...``) +``$<1:...>`` + Content of ``...`` +``$<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`` +``$<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_GREATER:v1,v2>`` + ``1`` if ``v1`` is a version greater than ``v2``, else ``0``. +``$<VERSION_LESS:v1,v2>`` + ``1`` if ``v1`` is a version less than ``v2``, else ``0``. +``$<VERSION_EQUAL:v1,v2>`` + ``1`` if ``v1`` is the same version as ``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. + +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. + +``$<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_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. + +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 preceeded by ``-I``. Note that a more-complete use +in this situation would require first checking if the INCLUDE_DIRECTORIES +property is non-empty:: + + $<$<BOOL:$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>>:-I$<JOIN:$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>, -I>> + +``$<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``. This expression may only be used in + the sources of :command:`add_library` and :command:`add_executable` + commands. diff --git a/Help/manual/cmake-generators.7.rst b/Help/manual/cmake-generators.7.rst new file mode 100644 index 0000000000..7f5093f0c8 --- /dev/null +++ b/Help/manual/cmake-generators.7.rst @@ -0,0 +1,87 @@ +.. cmake-manual-description: CMake Generators Reference + +cmake-generators(7) +******************* + +.. only:: html or latex + + .. 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. + +.. toctree:: + :maxdepth: 1 + + /generator/Borland Makefiles + /generator/MSYS Makefiles + /generator/MinGW Makefiles + /generator/NMake Makefiles + /generator/NMake Makefiles JOM + /generator/Ninja + /generator/Unix Makefiles + /generator/Watcom WMake + +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. + +.. 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 + /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 0000000000..032b51fda8 --- /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 0000000000..b83dcad4b3 --- /dev/null +++ b/Help/manual/cmake-language.7.rst @@ -0,0 +1,490 @@ +.. cmake-manual-description: CMake Language Reference + +cmake-language(7) +***************** + +.. only:: html or latex + + .. 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 +====== + +Encoding +-------- + +A CMake Language source file must be written in 7-bit ASCII text +to be portable 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. 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`_: + +.. 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'> + +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: + +.. 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` + +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`_: + +.. productionlist:: + argument: `bracket_argument` | `quoted_argument` | `unquoted_argument` + +.. _`Bracket Argument`: + +Bracket Argument +^^^^^^^^^^^^^^^^ + +A *bracket argument*, inspired by `Lua`_ long bracket syntax, +encloses content between opening and closing "brackets" of the +same length: + +.. productionlist:: + bracket_argument: `bracket_open` `bracket_content` `bracket_close` + bracket_open: '[' '='{len} '[' + bracket_content: <any text not containing a `bracket_close` + : of the same {len} as the `bracket_open`> + bracket_close: ']' '='{len} ']' + +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: + +.. productionlist:: + quoted_argument: '"' `quoted_element`* '"' + quoted_element: <any character except '\' or '"'> | + : `escape_sequence` | + : `quoted_continuation` + quoted_continuation: '\' `newline` + +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: + +.. code-block:: cmake + + message("This is a quoted argument containing multiple lines. + This is always one argument even though it contains a ; character. + Both \\-escape sequences and ${variable} references are evaluated. + The text does not end on an escaped double-quote like \". + It does end in an unescaped double quote. + ") + +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: + +.. productionlist:: + unquoted_argument: `unquoted_element`+ | `unquoted_legacy` + unquoted_element: <any character except whitespace or one of '()#"\'> | + : `escape_sequence` + unquoted_legacy: <see note in text> + +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. + + 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: + +.. productionlist:: + escape_sequence: `escape_identity` | `escape_encoded` | `escape_semicolon` + escape_identity: '\' <match '[^A-Za-z0-9;]'> + escape_encoded: '\t' | '\r' | '\n' + escape_semicolon: '\;' + +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: + +.. productionlist:: + bracket_comment: '#' `bracket_argument` + +For example: + +.. code-block:: cmake + + #[[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: + +.. productionlist:: + line_comment: '#' <any text not starting in a `bracket_argument` + : and not containing a `newline`> + +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. The :command:`break` command +may be used inside such blocks to terminate the loop early. + +Command Definitions +------------------- + +The :command:`macro`/:command:`endmacro`, and +:command:`function`/:command:`endfunction` commands delimit +code blocks to be recorded for later invocation as commands. + +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. + +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 0000000000..61e4bb490e --- /dev/null +++ b/Help/manual/cmake-modules.7.rst @@ -0,0 +1,239 @@ +.. cmake-manual-description: CMake Modules Reference + +cmake-modules(7) +**************** + +.. only:: html or latex + + .. contents:: + +All Modules +=========== + +.. toctree:: + :maxdepth: 1 + + /module/AddFileDependencies + /module/BundleUtilities + /module/CheckCCompilerFlag + /module/CheckCSourceCompiles + /module/CheckCSourceRuns + /module/CheckCXXCompilerFlag + /module/CheckCXXSourceCompiles + /module/CheckCXXSourceRuns + /module/CheckCXXSymbolExists + /module/CheckFortranFunctionExists + /module/CheckFortranSourceCompiles + /module/CheckFunctionExists + /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/CPackBundle + /module/CPackComponent + /module/CPackCygwin + /module/CPackDeb + /module/CPackDMG + /module/CPackIFW + /module/CPackNSIS + /module/CPackPackageMaker + /module/CPackRPM + /module/CPack + /module/CPackWIX + /module/CTest + /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/FindGTest + /module/FindGTK2 + /module/FindGTK + /module/FindHDF5 + /module/FindHg + /module/FindHSPELL + /module/FindHTMLHelp + /module/FindIce + /module/FindIcotool + /module/FindImageMagick + /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/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/FindWget + /module/FindWish + /module/FindwxWidgets + /module/FindwxWindows + /module/FindXerces + /module/FindX11 + /module/FindXMLRPC + /module/FindZLIB + /module/FortranCInterface + /module/GenerateExportHeader + /module/GetPrerequisites + /module/GNUInstallDirs + /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 0000000000..c4cca6d053 --- /dev/null +++ b/Help/manual/cmake-packages.7.rst @@ -0,0 +1,634 @@ +.. cmake-manual-description: CMake Packages Reference + +cmake-packages(7) +***************** + +.. only:: html or latex + + .. 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 +-------------------- + +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 downsteams 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 +================= + +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" + COPY_ONLY + ) + + 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 downsteams 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 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 downsteam, it automatically consumes the entries from +that property. + +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. + +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>> + ) + +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 similiarly 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. + +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``, +downsteams 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_NOTFOUND_MESSAGE "Specified unsupported component: ${_comp}") + endif() + include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStats${_comp}Targets.cmake") + endforeach() + +Here, the ``ClimbingStats_NOTFOUND_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. + +.. _`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 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 0000000000..f1717a08cc --- /dev/null +++ b/Help/manual/cmake-policies.7.rst @@ -0,0 +1,108 @@ +.. cmake-manual-description: CMake Policies Reference + +cmake-policies(7) +***************** + +.. only:: html or latex + + .. 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. + +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. + +All Policies +============ + +.. toctree:: + :maxdepth: 1 + + /policy/CMP0000 + /policy/CMP0001 + /policy/CMP0002 + /policy/CMP0003 + /policy/CMP0004 + /policy/CMP0005 + /policy/CMP0006 + /policy/CMP0007 + /policy/CMP0008 + /policy/CMP0009 + /policy/CMP0010 + /policy/CMP0011 + /policy/CMP0012 + /policy/CMP0013 + /policy/CMP0014 + /policy/CMP0015 + /policy/CMP0016 + /policy/CMP0017 + /policy/CMP0018 + /policy/CMP0019 + /policy/CMP0020 + /policy/CMP0021 + /policy/CMP0022 + /policy/CMP0023 + /policy/CMP0024 + /policy/CMP0025 + /policy/CMP0026 + /policy/CMP0027 + /policy/CMP0028 + /policy/CMP0029 + /policy/CMP0030 + /policy/CMP0031 + /policy/CMP0032 + /policy/CMP0033 + /policy/CMP0034 + /policy/CMP0035 + /policy/CMP0036 + /policy/CMP0037 + /policy/CMP0038 + /policy/CMP0039 + /policy/CMP0040 + /policy/CMP0041 + /policy/CMP0042 + /policy/CMP0043 + /policy/CMP0044 + /policy/CMP0045 + /policy/CMP0046 + /policy/CMP0047 + /policy/CMP0048 + /policy/CMP0049 + /policy/CMP0050 + /policy/CMP0051 + /policy/CMP0052 + /policy/CMP0053 + /policy/CMP0054 diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst new file mode 100644 index 0000000000..38bcd042d1 --- /dev/null +++ b/Help/manual/cmake-properties.7.rst @@ -0,0 +1,349 @@ +.. cmake-manual-description: CMake Properties Reference + +cmake-properties(7) +******************* + +.. only:: html or latex + + .. contents:: + +Properties of Global Scope +========================== + +.. toctree:: + :maxdepth: 1 + + /prop_gbl/ALLOW_DUPLICATE_CUSTOM_TARGETS + /prop_gbl/AUTOGEN_TARGETS_FOLDER + /prop_gbl/AUTOMOC_TARGETS_FOLDER + /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_LIB64_PATHS + /prop_gbl/FIND_LIBRARY_USE_OPENBSD_VERSIONING + /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_SUPPORTS_SHARED_LIBS + /prop_gbl/USE_FOLDERS + +Properties on Directories +========================= + +.. toctree:: + :maxdepth: 1 + + /prop_dir/ADDITIONAL_MAKE_CLEAN_FILES + /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/TEST_INCLUDE_FILE + /prop_dir/VARIABLES + /prop_dir/VS_GLOBAL_SECTION_POST_section + /prop_dir/VS_GLOBAL_SECTION_PRE_section + +Properties on Targets +===================== + +.. toctree:: + :maxdepth: 1 + + /prop_tgt/ALIASED_TARGET + /prop_tgt/ANDROID_API + /prop_tgt/ANDROID_GUI + /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_TARGET_DEPENDS + /prop_tgt/AUTOMOC_MOC_OPTIONS + /prop_tgt/AUTOMOC + /prop_tgt/AUTOUIC + /prop_tgt/AUTOUIC_OPTIONS + /prop_tgt/AUTORCC + /prop_tgt/AUTORCC_OPTIONS + /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/CXX_EXTENSIONS + /prop_tgt/CXX_STANDARD + /prop_tgt/CXX_STANDARD_REQUIRED + /prop_tgt/DEBUG_POSTFIX + /prop_tgt/DEFINE_SYMBOL + /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/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_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 + /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/JOB_POOL_COMPILE + /prop_tgt/JOB_POOL_LINK + /prop_tgt/LABELS + /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/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/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/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_DOTNET_REFERENCES + /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_KEYWORD + /prop_tgt/VS_SCC_AUXPATH + /prop_tgt/VS_SCC_LOCALPATH + /prop_tgt/VS_SCC_PROJECTNAME + /prop_tgt/VS_SCC_PROVIDER + /prop_tgt/VS_WINRT_COMPONENT + /prop_tgt/VS_WINRT_EXTENSIONS + /prop_tgt/VS_WINRT_REFERENCES + /prop_tgt/WIN32_EXECUTABLE + /prop_tgt/XCODE_ATTRIBUTE_an-attribute + +Properties on Tests +=================== + +.. toctree:: + :maxdepth: 1 + + /prop_test/ATTACHED_FILES_ON_FAIL + /prop_test/ATTACHED_FILES + /prop_test/COST + /prop_test/DEPENDS + /prop_test/ENVIRONMENT + /prop_test/FAIL_REGULAR_EXPRESSION + /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/WILL_FAIL + /prop_test/WORKING_DIRECTORY + +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/SYMBOLIC + /prop_sf/VS_DEPLOYMENT_CONTENT + /prop_sf/VS_SHADER_TYPE + /prop_sf/WRAP_EXCLUDE + /prop_sf/XCODE_EXPLICIT_FILE_TYPE + /prop_sf/XCODE_LAST_KNOWN_FILE_TYPE + +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 + +Properties on Installed Files +============================= + +.. toctree:: + :maxdepth: 1 + + /prop_inst/CPACK_NEVER_OVERWRITE.rst + /prop_inst/CPACK_PERMANENT.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 0000000000..fe8d62db51 --- /dev/null +++ b/Help/manual/cmake-qt.7.rst @@ -0,0 +1,187 @@ +.. cmake-manual-description: CMake Qt Features Reference + +cmake-qt(7) +*********** + +.. only:: html or latex + + .. 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.0.0 FATAL_ERROR) + + project(Qt4And5) + + set(CMAKE_AUTOMOC ON) + set(CMAKE_INCLUDE_CURRENT_DIR ON) + + find_package(Qt5Widgets 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 ``moc file`` may be +included by the user in the C++ implementation file with a preprocessor +``#include``. If it is not so included, it will be added to a separate file +which is compiled into the target. + +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. + +Generated ``moc_*.cpp`` and ``*.moc`` files are placed in the build directory +so it is convenient to set the :variable:`CMAKE_INCLUDE_CURRENT_DIR` +variable. 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. + +.. _`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 +``ui_<basename>.h``, and a ``<basename>.ui`` file exists, then ``uic`` will +be executed to generate the appropriate file. + +Generated ``ui_*.h`` files are placed in the build directory so it is +convenient to set the :variable:`CMAKE_INCLUDE_CURRENT_DIR` variable. 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 + ) + +.. _`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. + +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-toolchains.7.rst b/Help/manual/cmake-toolchains.7.rst new file mode 100644 index 0000000000..1621b5ffd6 --- /dev/null +++ b/Help/manual/cmake-toolchains.7.rst @@ -0,0 +1,242 @@ +.. cmake-manual-description: CMake Toolchains Reference + +cmake-toolchains(7) +******************* + +.. only:: html or latex + + .. 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(CMAKE_C_COMPILER /home/devel/gcc-4.7-linaro-rpi-gnueabihf/bin/arm-linux-gnueabihf-gcc) + set(CMAKE_CXX_COMPILER /home/devel/gcc-4.7-linaro-rpi-gnueabihf/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. In cases where CMake does +not have enough information to extract information from the compiler, the +:module:`CMakeForceCompiler` module can be used to bypass some of the 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. + +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 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) diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst new file mode 100644 index 0000000000..864ea6eca2 --- /dev/null +++ b/Help/manual/cmake-variables.7.rst @@ -0,0 +1,388 @@ +.. cmake-manual-description: CMake Variables Reference + +cmake-variables(7) +****************** + +.. only:: html or latex + + .. contents:: + +Variables that Provide Information +================================== + +.. toctree:: + :maxdepth: 1 + + /variable/CMAKE_ARGC + /variable/CMAKE_ARGV0 + /variable/CMAKE_AR + /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_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_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_LINK_LIBRARY_SUFFIX + /variable/CMAKE_MAJOR_VERSION + /variable/CMAKE_MAKE_PROGRAM + /variable/CMAKE_MINIMUM_REQUIRED_VERSION + /variable/CMAKE_MINOR_VERSION + /variable/CMAKE_PARENT_LIST_FILE + /variable/CMAKE_PATCH_VERSION + /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_STANDARD_LIBRARIES + /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_MSDEV_COMMAND + /variable/CMAKE_VS_NsightTegra_VERSION + /variable/CMAKE_VS_PLATFORM_NAME + /variable/CMAKE_VS_PLATFORM_TOOLSET + /variable/CMAKE_XCODE_PLATFORM_TOOLSET + /variable/PROJECT_BINARY_DIR + /variable/PROJECT-NAME_BINARY_DIR + /variable/PROJECT_NAME + /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_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_COLOR_MAKEFILE + /variable/CMAKE_CONFIGURATION_TYPES + /variable/CMAKE_DEBUG_TARGET_PROPERTIES + /variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName + /variable/CMAKE_ERROR_DEPRECATED + /variable/CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION + /variable/CMAKE_EXPORT_NO_PACKAGE_REGISTRY + /variable/CMAKE_SYSROOT + /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_PATH + /variable/CMAKE_INCLUDE_DIRECTORIES_BEFORE + /variable/CMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE + /variable/CMAKE_INSTALL_DEFAULT_COMPONENT_NAME + /variable/CMAKE_INSTALL_MESSAGE + /variable/CMAKE_INSTALL_PREFIX + /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_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/APPLE + /variable/BORLAND + /variable/CMAKE_CL_64 + /variable/CMAKE_COMPILER_2005 + /variable/CMAKE_HOST_APPLE + /variable/CMAKE_HOST_SYSTEM_NAME + /variable/CMAKE_HOST_SYSTEM_PROCESSOR + /variable/CMAKE_HOST_SYSTEM + /variable/CMAKE_HOST_SYSTEM_VERSION + /variable/CMAKE_HOST_UNIX + /variable/CMAKE_HOST_WIN32 + /variable/CMAKE_LIBRARY_ARCHITECTURE_REGEX + /variable/CMAKE_LIBRARY_ARCHITECTURE + /variable/CMAKE_OBJECT_PATH_MAX + /variable/CMAKE_SYSTEM_NAME + /variable/CMAKE_SYSTEM_PROCESSOR + /variable/CMAKE_SYSTEM + /variable/CMAKE_SYSTEM_VERSION + /variable/CYGWIN + /variable/ENV + /variable/MSVC10 + /variable/MSVC11 + /variable/MSVC12 + /variable/MSVC14 + /variable/MSVC60 + /variable/MSVC70 + /variable/MSVC71 + /variable/MSVC80 + /variable/MSVC90 + /variable/MSVC_IDE + /variable/MSVC + /variable/MSVC_VERSION + /variable/UNIX + /variable/WIN32 + /variable/WINCE + /variable/WINDOWS_PHONE + /variable/WINDOWS_STORE + /variable/XCODE_VERSION + +Variables that Control the Build +================================ + +.. toctree:: + :maxdepth: 1 + + /variable/CMAKE_ANDROID_API + /variable/CMAKE_ANDROID_GUI + /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY + /variable/CMAKE_AUTOMOC_MOC_OPTIONS + /variable/CMAKE_AUTOMOC + /variable/CMAKE_AUTORCC + /variable/CMAKE_AUTORCC_OPTIONS + /variable/CMAKE_AUTOUIC + /variable/CMAKE_AUTOUIC_OPTIONS + /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_EXE_LINKER_FLAGS_CONFIG + /variable/CMAKE_EXE_LINKER_FLAGS + /variable/CMAKE_Fortran_FORMAT + /variable/CMAKE_Fortran_MODULE_DIRECTORY + /variable/CMAKE_GNUtoMS + /variable/CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE + /variable/CMAKE_INCLUDE_CURRENT_DIR + /variable/CMAKE_INSTALL_NAME_DIR + /variable/CMAKE_INSTALL_RPATH + /variable/CMAKE_INSTALL_RPATH_USE_LINK_PATH + /variable/CMAKE_LANG_VISIBILITY_PRESET + /variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY + /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_MACOSX_BUNDLE + /variable/CMAKE_MACOSX_RPATH + /variable/CMAKE_MAP_IMPORTED_CONFIG_CONFIG + /variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG + /variable/CMAKE_MODULE_LINKER_FLAGS + /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_SHARED_LINKER_FLAGS_CONFIG + /variable/CMAKE_SHARED_LINKER_FLAGS + /variable/CMAKE_SKIP_BUILD_RPATH + /variable/CMAKE_SKIP_INSTALL_RPATH + /variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG + /variable/CMAKE_STATIC_LINKER_FLAGS + /variable/CMAKE_TRY_COMPILE_CONFIGURATION + /variable/CMAKE_USE_RELATIVE_PATHS + /variable/CMAKE_VISIBILITY_INLINES_HIDDEN + /variable/CMAKE_WIN32_EXECUTABLE + /variable/EXECUTABLE_OUTPUT_PATH + /variable/LIBRARY_OUTPUT_PATH + +Variables for Languages +======================= + +.. toctree:: + :maxdepth: 1 + + /variable/CMAKE_COMPILER_IS_GNULANG + /variable/CMAKE_C_COMPILE_FEATURES + /variable/CMAKE_C_EXTENSIONS + /variable/CMAKE_C_STANDARD + /variable/CMAKE_C_STANDARD_REQUIRED + /variable/CMAKE_CXX_COMPILE_FEATURES + /variable/CMAKE_CXX_EXTENSIONS + /variable/CMAKE_CXX_STANDARD + /variable/CMAKE_CXX_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_ARCHIVE_APPEND + /variable/CMAKE_LANG_ARCHIVE_CREATE + /variable/CMAKE_LANG_ARCHIVE_FINISH + /variable/CMAKE_LANG_COMPILE_OBJECT + /variable/CMAKE_LANG_COMPILER_ABI + /variable/CMAKE_LANG_COMPILER_ID + /variable/CMAKE_LANG_COMPILER_LOADED + /variable/CMAKE_LANG_COMPILER + /variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN + /variable/CMAKE_LANG_COMPILER_TARGET + /variable/CMAKE_LANG_COMPILER_VERSION + /variable/CMAKE_LANG_CREATE_SHARED_LIBRARY + /variable/CMAKE_LANG_CREATE_SHARED_MODULE + /variable/CMAKE_LANG_CREATE_STATIC_LIBRARY + /variable/CMAKE_LANG_FLAGS_DEBUG + /variable/CMAKE_LANG_FLAGS_MINSIZEREL + /variable/CMAKE_LANG_FLAGS_RELEASE + /variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO + /variable/CMAKE_LANG_FLAGS + /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_PROPAGATES + /variable/CMAKE_LANG_LINKER_PREFERENCE + /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_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_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_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_GIT_COMMAND + /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_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 0000000000..8dfc16ac6c --- /dev/null +++ b/Help/manual/cmake.1.rst @@ -0,0 +1,162 @@ +.. 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. + +Options +======= + +.. include:: OPTIONS_BUILD.txt + +``-E`` + CMake command mode. + + For true platform independence, CMake provides a list of commands + that can be used on all systems. Run with -E help for the usage + information. Commands available are: chdir, compare_files, copy, + copy_directory, copy_if_different, echo, echo_append, env, environment, + make_directory, md5sum, remove, remove_directory, rename, sleep, tar, time, + touch, touch_nocreate. In addition, some platform specific commands + are available. On Windows: delete_regv, write_regv. On + UNIX: create_symlink. + +``-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>`` + Build a CMake-generated project binary tree. + + This abstracts a native build tool's command-line interface with the + following options: + + :: + + <dir> = Project binary directory to be built. + --target <tgt> = Build <tgt> instead of default targets. + --config <cfg> = For multi-configuration tools, choose <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. + +``-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`` + Run in pkg-config like mode. + + Search a package using 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). + +``--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 stuff 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 with + message(send_error ) calls. + +``--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 + +See Also +======== + +.. include:: LINKS.txt diff --git a/Help/manual/cpack.1.rst b/Help/manual/cpack.1.rst new file mode 100644 index 0000000000..ba2086e98a --- /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 commmand 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 0000000000..03e86af4f6 --- /dev/null +++ b/Help/manual/ctest.1.rst @@ -0,0 +1,993 @@ +.. 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 thegiven 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. + +``-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. + +``-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 TestModel + 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. 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). + +``--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`` + 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. By default this will run CMake on the Source/Bin + directories specified unless --build-nocmake is specified. + 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, --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. + +``--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 + + 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-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 +================ + +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`` + +``GITUpdateCustom`` + Specify a semicolon-separated list of custom command lines 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 semicolon-separated list of custom command lines 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 a Makefile generator + 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: + +``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 0000000000..3cbce33ac7 --- /dev/null +++ b/Help/module/AddFileDependencies.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/AddFileDependencies.cmake diff --git a/Help/module/BundleUtilities.rst b/Help/module/BundleUtilities.rst new file mode 100644 index 0000000000..5d9c840178 --- /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 0000000000..9abf571af2 --- /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 0000000000..05e5f4abe2 --- /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 0000000000..fd071b55b1 --- /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 0000000000..176853372c --- /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 0000000000..1084280342 --- /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 0000000000..5b5b550a35 --- /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 0000000000..c2c219b3e1 --- /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 0000000000..d099d19e37 --- /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 0000000000..3277426944 --- /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 0000000000..2cd97b3c46 --- /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 0000000000..a291aff0c3 --- /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 0000000000..810a9dd3ce --- /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 0000000000..a75a34f0a1 --- /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 0000000000..0b5d8489a1 --- /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 0000000000..e897929592 --- /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 0000000000..eeff1bf493 --- /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 0000000000..bfbda1f890 --- /dev/null +++ b/Help/module/CPack.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CPack.cmake diff --git a/Help/module/CPackBundle.rst b/Help/module/CPackBundle.rst new file mode 100644 index 0000000000..651e874267 --- /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 0000000000..df82836ca6 --- /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 0000000000..21f4473482 --- /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 0000000000..784262c5e1 --- /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 0000000000..d1526ee49c --- /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 0000000000..ea05796ada --- /dev/null +++ b/Help/module/CPackIFW.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CPackIFW.cmake diff --git a/Help/module/CPackNSIS.rst b/Help/module/CPackNSIS.rst new file mode 100644 index 0000000000..bb35ed60a3 --- /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 0000000000..de5544869d --- /dev/null +++ b/Help/module/CPackPackageMaker.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CPackPackageMaker.cmake diff --git a/Help/module/CPackRPM.rst b/Help/module/CPackRPM.rst new file mode 100644 index 0000000000..28d0e69129 --- /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 0000000000..1f5e451e9b --- /dev/null +++ b/Help/module/CPackWIX.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CPackWIX.cmake diff --git a/Help/module/CTest.rst b/Help/module/CTest.rst new file mode 100644 index 0000000000..11a6af7d7d --- /dev/null +++ b/Help/module/CTest.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CTest.cmake diff --git a/Help/module/CTestScriptMode.rst b/Help/module/CTestScriptMode.rst new file mode 100644 index 0000000000..be1b0447e2 --- /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 0000000000..688da0870f --- /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 0000000000..1be1491ccb --- /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 0000000000..1fa02f9b1e --- /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 0000000000..16b47e66da --- /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 0000000000..cfd1f457bb --- /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 0000000000..d701c4e541 --- /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 0000000000..caab975893 --- /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 0000000000..fc192e8197 --- /dev/null +++ b/Help/module/CheckCXXSymbolExists.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckCXXSymbolExists.cmake diff --git a/Help/module/CheckFortranFunctionExists.rst b/Help/module/CheckFortranFunctionExists.rst new file mode 100644 index 0000000000..3395d05c48 --- /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 0000000000..b749a2a30c --- /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 0000000000..ed89dc407f --- /dev/null +++ b/Help/module/CheckFunctionExists.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckFunctionExists.cmake diff --git a/Help/module/CheckIncludeFile.rst b/Help/module/CheckIncludeFile.rst new file mode 100644 index 0000000000..6b831089e3 --- /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 0000000000..fdbf39fd16 --- /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 0000000000..b56f14565f --- /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 0000000000..16f1a3f79b --- /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 0000000000..7512f46c59 --- /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 0000000000..073fcb59f7 --- /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 0000000000..5277ad2f6f --- /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 0000000000..68ae70009f --- /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 0000000000..6ad03456fc --- /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 0000000000..07f0777927 --- /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 0000000000..524ac33df5 --- /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 0000000000..3c0ef444a0 --- /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 0000000000..08e2ffb6d5 --- /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 0000000000..f0f8f1d075 --- /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 0000000000..fce70567eb --- /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 0000000000..6fd8f3805e --- /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 0000000000..2a73786b48 --- /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 0000000000..56dedc4280 --- /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 0000000000..71282a684d --- /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 0000000000..f0ac933d17 --- /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 0000000000..c6e5791be2 --- /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 0000000000..41f67711cc --- /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 0000000000..281b1d10dc --- /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 0000000000..e1ca48c775 --- /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 0000000000..139254055f --- /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 0000000000..4ed2b855b8 --- /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 0000000000..716d5abd55 --- /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 0000000000..46ffa9fc27 --- /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 0000000000..e2acc49878 --- /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 0000000000..c891c07d70 --- /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 0000000000..fc70a74d6d --- /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 0000000000..10d0646fd4 --- /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 0000000000..73dd01171c --- /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 0000000000..4f17c39bcf --- /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 0000000000..2e529dd03a --- /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 0000000000..8437d5557f --- /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 0000000000..6f21ad4bec --- /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 0000000000..91a28ddc45 --- /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 0000000000..cffe734534 --- /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 0000000000..5063680bb1 --- /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 0000000000..cc90791d90 --- /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 0000000000..cc1964cc47 --- /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 0000000000..5c2acc4aec --- /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 0000000000..424c3fcb3f --- /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 0000000000..15fd4d0d68 --- /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 0000000000..81fcb3a20b --- /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 0000000000..03d3a75389 --- /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 0000000000..77755da1f1 --- /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 0000000000..40263eeb96 --- /dev/null +++ b/Help/module/FindGLUT.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindGLUT.cmake diff --git a/Help/module/FindGTK.rst b/Help/module/FindGTK.rst new file mode 100644 index 0000000000..1ce6a86750 --- /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 0000000000..67c1ba9e23 --- /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 0000000000..0e3b4d770a --- /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 0000000000..e880dc038d --- /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 0000000000..dd540ef2f5 --- /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 0000000000..de0c1d4f8d --- /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 0000000000..93a18b6084 --- /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 0000000000..8ac1b8be9d --- /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 0000000000..c1905a2e32 --- /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 0000000000..47d9c8c497 --- /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 0000000000..94aba6f7e6 --- /dev/null +++ b/Help/module/FindHg.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindHg.cmake diff --git a/Help/module/FindITK.rst b/Help/module/FindITK.rst new file mode 100644 index 0000000000..21a922f617 --- /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 0000000000..3af9405e00 --- /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 0000000000..c139f58cc2 --- /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 0000000000..3a3596e5ec --- /dev/null +++ b/Help/module/FindImageMagick.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindImageMagick.cmake diff --git a/Help/module/FindJNI.rst b/Help/module/FindJNI.rst new file mode 100644 index 0000000000..b753cf8914 --- /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 0000000000..80363529af --- /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 0000000000..725a87fc43 --- /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 0000000000..39e6b6b215 --- /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 0000000000..13ac15c8c7 --- /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 0000000000..8b22f7fc82 --- /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 0000000000..6e9909016f --- /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 0000000000..4b14c7136e --- /dev/null +++ b/Help/module/FindLATEX.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindLATEX.cmake diff --git a/Help/module/FindLibArchive.rst b/Help/module/FindLibArchive.rst new file mode 100644 index 0000000000..c46b1d0043 --- /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 0000000000..88801580cb --- /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 0000000000..bbb3225909 --- /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 0000000000..4107170cf5 --- /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 0000000000..977e5bfce2 --- /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 0000000000..0353fc35e2 --- /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 0000000000..672ff357b5 --- /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 0000000000..a3226a690d --- /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 0000000000..c9ce48142c --- /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 0000000000..f843c8971c --- /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 0000000000..fad10c7325 --- /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 0000000000..43f861adc0 --- /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 0000000000..e602a501c2 --- /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 0000000000..f0865569d8 --- /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 0000000000..e87e289bda --- /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 0000000000..85e89bcb32 --- /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 0000000000..01362abfba --- /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 0000000000..f622bb14e5 --- /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 0000000000..434649257f --- /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 0000000000..bb3f0f97b0 --- /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 0000000000..1de62e8d4b --- /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 0000000000..e6d161875f --- /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 0000000000..feda7ef612 --- /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 0000000000..b682d8c0f2 --- /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 0000000000..098f4b5456 --- /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 0000000000..8d8bbab7b3 --- /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 0000000000..21d928baba --- /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 0000000000..b096ca4da2 --- /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 0000000000..b8caf7442a --- /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 0000000000..b45c07e7f5 --- /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 0000000000..1c0c575ff6 --- /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 0000000000..b978e010fe --- /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 0000000000..3be2306922 --- /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 0000000000..8f0015d33a --- /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 0000000000..3aa8a26de0 --- /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 0000000000..b933059096 --- /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 0000000000..28036b2fd9 --- /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 0000000000..735f7d29fd --- /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 0000000000..a93ad1658e --- /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 0000000000..a1e7922410 --- /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 0000000000..79893c03ce --- /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 0000000000..dc69d7070b --- /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 0000000000..1c9c446742 --- /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 0000000000..079d0bbe3a --- /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 0000000000..077edf7005 --- /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 0000000000..40c5ec4c4a --- /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 0000000000..9b25b94b3e --- /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 0000000000..5f2c689ca8 --- /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 0000000000..dc2c86d53e --- /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 0000000000..aa15857d1e --- /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 0000000000..cbd203589e --- /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 0000000000..69f8ca585a --- /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 0000000000..6cc5b2df20 --- /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 0000000000..23e7d6b397 --- /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 0000000000..91967a7a3b --- /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 0000000000..9ad05ad2d8 --- /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 0000000000..3bc67c5c9e --- /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/FindWget.rst b/Help/module/FindWget.rst new file mode 100644 index 0000000000..06affd4eb4 --- /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 0000000000..76be4cf548 --- /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 0000000000..906efd7389 --- /dev/null +++ b/Help/module/FindX11.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindX11.cmake diff --git a/Help/module/FindXMLRPC.rst b/Help/module/FindXMLRPC.rst new file mode 100644 index 0000000000..5d11a0ca8a --- /dev/null +++ b/Help/module/FindXMLRPC.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindXMLRPC.cmake diff --git a/Help/module/FindXerces.rst b/Help/module/FindXerces.rst new file mode 100644 index 0000000000..166d8dd1a9 --- /dev/null +++ b/Help/module/FindXerces.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindXerces.cmake diff --git a/Help/module/FindZLIB.rst b/Help/module/FindZLIB.rst new file mode 100644 index 0000000000..ded863463a --- /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 0000000000..6b407aca5c --- /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 0000000000..f14a1e7f39 --- /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 0000000000..9f72bc7943 --- /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 0000000000..0e1edfba19 --- /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 0000000000..562d73fd56 --- /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 0000000000..53621a71ee --- /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 0000000000..b9d615d379 --- /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 0000000000..9cf191c37b --- /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 0000000000..cb47841bd7 --- /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 0000000000..c502851b47 --- /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 0000000000..08c870453f --- /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 0000000000..fbb22e1087 --- /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 0000000000..9e47b65676 --- /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 0000000000..dd401d8b24 --- /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 0000000000..bb028fb157 --- /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 0000000000..bb11bdf4dd --- /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 0000000000..5def375445 --- /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 0000000000..d836906e35 --- /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 0000000000..bdd11355dc --- /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 0000000000..522e1ac164 --- /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 0000000000..519beb725d --- /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 0000000000..35c9728135 --- /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 0000000000..7afcf154b3 --- /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 0000000000..79d357040f --- /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 0000000000..115713ecdd --- /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 0000000000..84b20c8761 --- /dev/null +++ b/Help/module/GetPrerequisites.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/GetPrerequisites.cmake diff --git a/Help/module/InstallRequiredSystemLibraries.rst b/Help/module/InstallRequiredSystemLibraries.rst new file mode 100644 index 0000000000..5ea9af33e7 --- /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 0000000000..5f0bf6bbfa --- /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 0000000000..0149d0924b --- /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 0000000000..14fd6f88ae --- /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 0000000000..47da404f1f --- /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 0000000000..f9e4d2f106 --- /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 0000000000..ee3d70a714 --- /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 0000000000..00d923803a --- /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 0000000000..212a30b79b --- /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 0000000000..d1547519e6 --- /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 0000000000..ad989e3670 --- /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 0000000000..0e578685a0 --- /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 0000000000..fa2f1bd6ff --- /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 0000000000..b9cd4769e4 --- /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 0000000000..2fab8e8dd3 --- /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 0000000000..668f7662b3 --- /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 0000000000..0007c355c1 --- /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 0000000000..a489e9849e --- /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 0000000000..6829c2d2b3 --- /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 0000000000..c637d5dc21 --- /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 0000000000..4c81b48838 --- /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 0000000000..9fbf842be1 --- /dev/null +++ b/Help/policy/CMP0000.rst @@ -0,0 +1,30 @@ +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. diff --git a/Help/policy/CMP0001.rst b/Help/policy/CMP0001.rst new file mode 100644 index 0000000000..344f1e2ae3 --- /dev/null +++ b/Help/policy/CMP0001.rst @@ -0,0 +1,19 @@ +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. diff --git a/Help/policy/CMP0002.rst b/Help/policy/CMP0002.rst new file mode 100644 index 0000000000..2c15bd44cc --- /dev/null +++ b/Help/policy/CMP0002.rst @@ -0,0 +1,26 @@ +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. diff --git a/Help/policy/CMP0003.rst b/Help/policy/CMP0003.rst new file mode 100644 index 0000000000..27b83f8ad1 --- /dev/null +++ b/Help/policy/CMP0003.rst @@ -0,0 +1,102 @@ +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. diff --git a/Help/policy/CMP0004.rst b/Help/policy/CMP0004.rst new file mode 100644 index 0000000000..80045f5a1a --- /dev/null +++ b/Help/policy/CMP0004.rst @@ -0,0 +1,23 @@ +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. diff --git a/Help/policy/CMP0005.rst b/Help/policy/CMP0005.rst new file mode 100644 index 0000000000..c11a9e6eff --- /dev/null +++ b/Help/policy/CMP0005.rst @@ -0,0 +1,24 @@ +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. diff --git a/Help/policy/CMP0006.rst b/Help/policy/CMP0006.rst new file mode 100644 index 0000000000..8d1e5bdd3d --- /dev/null +++ b/Help/policy/CMP0006.rst @@ -0,0 +1,22 @@ +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. diff --git a/Help/policy/CMP0007.rst b/Help/policy/CMP0007.rst new file mode 100644 index 0000000000..f0d8c1603f --- /dev/null +++ b/Help/policy/CMP0007.rst @@ -0,0 +1,15 @@ +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. diff --git a/Help/policy/CMP0008.rst b/Help/policy/CMP0008.rst new file mode 100644 index 0000000000..b118ece143 --- /dev/null +++ b/Help/policy/CMP0008.rst @@ -0,0 +1,32 @@ +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. diff --git a/Help/policy/CMP0009.rst b/Help/policy/CMP0009.rst new file mode 100644 index 0000000000..481af1a54c --- /dev/null +++ b/Help/policy/CMP0009.rst @@ -0,0 +1,19 @@ +CMP0009 +------- + +FILE GLOB_RECURSE calls should not follow symlinks by default. + +In CMake 2.6.1 and below, FILE GLOB_RECURSE calls would follow through +symlinks, sometimes coming up with unexpectedly large result sets +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. diff --git a/Help/policy/CMP0010.rst b/Help/policy/CMP0010.rst new file mode 100644 index 0000000000..9d2eb7636c --- /dev/null +++ b/Help/policy/CMP0010.rst @@ -0,0 +1,18 @@ +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. diff --git a/Help/policy/CMP0011.rst b/Help/policy/CMP0011.rst new file mode 100644 index 0000000000..0f41fffad3 --- /dev/null +++ b/Help/policy/CMP0011.rst @@ -0,0 +1,22 @@ +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. diff --git a/Help/policy/CMP0012.rst b/Help/policy/CMP0012.rst new file mode 100644 index 0000000000..7a749bf0d7 --- /dev/null +++ b/Help/policy/CMP0012.rst @@ -0,0 +1,25 @@ +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. diff --git a/Help/policy/CMP0013.rst b/Help/policy/CMP0013.rst new file mode 100644 index 0000000000..e99997b6b1 --- /dev/null +++ b/Help/policy/CMP0013.rst @@ -0,0 +1,19 @@ +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. diff --git a/Help/policy/CMP0014.rst b/Help/policy/CMP0014.rst new file mode 100644 index 0000000000..37178d12de --- /dev/null +++ b/Help/policy/CMP0014.rst @@ -0,0 +1,15 @@ +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. diff --git a/Help/policy/CMP0015.rst b/Help/policy/CMP0015.rst new file mode 100644 index 0000000000..1b549790a6 --- /dev/null +++ b/Help/policy/CMP0015.rst @@ -0,0 +1,17 @@ +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. diff --git a/Help/policy/CMP0016.rst b/Help/policy/CMP0016.rst new file mode 100644 index 0000000000..743b1a9c55 --- /dev/null +++ b/Help/policy/CMP0016.rst @@ -0,0 +1,13 @@ +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. diff --git a/Help/policy/CMP0017.rst b/Help/policy/CMP0017.rst new file mode 100644 index 0000000000..f74e6f0cfb --- /dev/null +++ b/Help/policy/CMP0017.rst @@ -0,0 +1,19 @@ +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. diff --git a/Help/policy/CMP0018.rst b/Help/policy/CMP0018.rst new file mode 100644 index 0000000000..0f6826771c --- /dev/null +++ b/Help/policy/CMP0018.rst @@ -0,0 +1,32 @@ +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. diff --git a/Help/policy/CMP0019.rst b/Help/policy/CMP0019.rst new file mode 100644 index 0000000000..2b37fa1d7c --- /dev/null +++ b/Help/policy/CMP0019.rst @@ -0,0 +1,20 @@ +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. diff --git a/Help/policy/CMP0020.rst b/Help/policy/CMP0020.rst new file mode 100644 index 0000000000..6767d08bb6 --- /dev/null +++ b/Help/policy/CMP0020.rst @@ -0,0 +1,25 @@ +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. diff --git a/Help/policy/CMP0021.rst b/Help/policy/CMP0021.rst new file mode 100644 index 0000000000..3f5bd03168 --- /dev/null +++ b/Help/policy/CMP0021.rst @@ -0,0 +1,18 @@ +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. diff --git a/Help/policy/CMP0022.rst b/Help/policy/CMP0022.rst new file mode 100644 index 0000000000..22c7c4fdc1 --- /dev/null +++ b/Help/policy/CMP0022.rst @@ -0,0 +1,37 @@ +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. diff --git a/Help/policy/CMP0023.rst b/Help/policy/CMP0023.rst new file mode 100644 index 0000000000..962b624cf5 --- /dev/null +++ b/Help/policy/CMP0023.rst @@ -0,0 +1,33 @@ +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. diff --git a/Help/policy/CMP0024.rst b/Help/policy/CMP0024.rst new file mode 100644 index 0000000000..ee53d5f5ee --- /dev/null +++ b/Help/policy/CMP0024.rst @@ -0,0 +1,22 @@ +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. diff --git a/Help/policy/CMP0025.rst b/Help/policy/CMP0025.rst new file mode 100644 index 0000000000..8d19edfa68 --- /dev/null +++ b/Help/policy/CMP0025.rst @@ -0,0 +1,27 @@ +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. diff --git a/Help/policy/CMP0026.rst b/Help/policy/CMP0026.rst new file mode 100644 index 0000000000..177b6555d8 --- /dev/null +++ b/Help/policy/CMP0026.rst @@ -0,0 +1,26 @@ +CMP0026 +------- + +Disallow use of the LOCATION target property. + +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. diff --git a/Help/policy/CMP0027.rst b/Help/policy/CMP0027.rst new file mode 100644 index 0000000000..bedaffeecd --- /dev/null +++ b/Help/policy/CMP0027.rst @@ -0,0 +1,25 @@ +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. diff --git a/Help/policy/CMP0028.rst b/Help/policy/CMP0028.rst new file mode 100644 index 0000000000..24889ec081 --- /dev/null +++ b/Help/policy/CMP0028.rst @@ -0,0 +1,23 @@ +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. diff --git a/Help/policy/CMP0029.rst b/Help/policy/CMP0029.rst new file mode 100644 index 0000000000..8f58a12209 --- /dev/null +++ b/Help/policy/CMP0029.rst @@ -0,0 +1,10 @@ +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 diff --git a/Help/policy/CMP0030.rst b/Help/policy/CMP0030.rst new file mode 100644 index 0000000000..9e31b3854c --- /dev/null +++ b/Help/policy/CMP0030.rst @@ -0,0 +1,11 @@ +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 diff --git a/Help/policy/CMP0031.rst b/Help/policy/CMP0031.rst new file mode 100644 index 0000000000..6b89558f59 --- /dev/null +++ b/Help/policy/CMP0031.rst @@ -0,0 +1,13 @@ +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 diff --git a/Help/policy/CMP0032.rst b/Help/policy/CMP0032.rst new file mode 100644 index 0000000000..f394a064ee --- /dev/null +++ b/Help/policy/CMP0032.rst @@ -0,0 +1,13 @@ +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 diff --git a/Help/policy/CMP0033.rst b/Help/policy/CMP0033.rst new file mode 100644 index 0000000000..b420065074 --- /dev/null +++ b/Help/policy/CMP0033.rst @@ -0,0 +1,14 @@ +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 diff --git a/Help/policy/CMP0034.rst b/Help/policy/CMP0034.rst new file mode 100644 index 0000000000..21339974bb --- /dev/null +++ b/Help/policy/CMP0034.rst @@ -0,0 +1,11 @@ +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 diff --git a/Help/policy/CMP0035.rst b/Help/policy/CMP0035.rst new file mode 100644 index 0000000000..7335b221ad --- /dev/null +++ b/Help/policy/CMP0035.rst @@ -0,0 +1,10 @@ +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 diff --git a/Help/policy/CMP0036.rst b/Help/policy/CMP0036.rst new file mode 100644 index 0000000000..817f156e45 --- /dev/null +++ b/Help/policy/CMP0036.rst @@ -0,0 +1,12 @@ +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 diff --git a/Help/policy/CMP0037.rst b/Help/policy/CMP0037.rst new file mode 100644 index 0000000000..4d485bf262 --- /dev/null +++ b/Help/policy/CMP0037.rst @@ -0,0 +1,26 @@ +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. diff --git a/Help/policy/CMP0038.rst b/Help/policy/CMP0038.rst new file mode 100644 index 0000000000..df5af6aec2 --- /dev/null +++ b/Help/policy/CMP0038.rst @@ -0,0 +1,16 @@ +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. diff --git a/Help/policy/CMP0039.rst b/Help/policy/CMP0039.rst new file mode 100644 index 0000000000..58ccc4186a --- /dev/null +++ b/Help/policy/CMP0039.rst @@ -0,0 +1,17 @@ +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. diff --git a/Help/policy/CMP0040.rst b/Help/policy/CMP0040.rst new file mode 100644 index 0000000000..77a3c81631 --- /dev/null +++ b/Help/policy/CMP0040.rst @@ -0,0 +1,16 @@ +CMP0040 +------- + +The target in the TARGET signature of add_custom_command() must exist. + +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. + +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. + +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. diff --git a/Help/policy/CMP0041.rst b/Help/policy/CMP0041.rst new file mode 100644 index 0000000000..5a47de0a16 --- /dev/null +++ b/Help/policy/CMP0041.rst @@ -0,0 +1,25 @@ +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. diff --git a/Help/policy/CMP0042.rst b/Help/policy/CMP0042.rst new file mode 100644 index 0000000000..fce870c7ca --- /dev/null +++ b/Help/policy/CMP0042.rst @@ -0,0 +1,19 @@ +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. diff --git a/Help/policy/CMP0043.rst b/Help/policy/CMP0043.rst new file mode 100644 index 0000000000..629e5022a4 --- /dev/null +++ b/Help/policy/CMP0043.rst @@ -0,0 +1,45 @@ +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. diff --git a/Help/policy/CMP0044.rst b/Help/policy/CMP0044.rst new file mode 100644 index 0000000000..4a3e21527e --- /dev/null +++ b/Help/policy/CMP0044.rst @@ -0,0 +1,19 @@ +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. diff --git a/Help/policy/CMP0045.rst b/Help/policy/CMP0045.rst new file mode 100644 index 0000000000..58c422fad1 --- /dev/null +++ b/Help/policy/CMP0045.rst @@ -0,0 +1,17 @@ +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. diff --git a/Help/policy/CMP0046.rst b/Help/policy/CMP0046.rst new file mode 100644 index 0000000000..1a3bc65ec4 --- /dev/null +++ b/Help/policy/CMP0046.rst @@ -0,0 +1,17 @@ +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. diff --git a/Help/policy/CMP0047.rst b/Help/policy/CMP0047.rst new file mode 100644 index 0000000000..26ae439392 --- /dev/null +++ b/Help/policy/CMP0047.rst @@ -0,0 +1,28 @@ +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. diff --git a/Help/policy/CMP0048.rst b/Help/policy/CMP0048.rst new file mode 100644 index 0000000000..a54205ee8f --- /dev/null +++ b/Help/policy/CMP0048.rst @@ -0,0 +1,22 @@ +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. diff --git a/Help/policy/CMP0049.rst b/Help/policy/CMP0049.rst new file mode 100644 index 0000000000..5c8d4a8af4 --- /dev/null +++ b/Help/policy/CMP0049.rst @@ -0,0 +1,23 @@ +CMP0049 +------- + +Do not expand variables in target source entries. + +CMake 2.8.12 and lower performed and extra layer of variable expansion +when evaluating source file names: + +.. code-block:: cmake + + 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. diff --git a/Help/policy/CMP0050.rst b/Help/policy/CMP0050.rst new file mode 100644 index 0000000000..76ae0aa75b --- /dev/null +++ b/Help/policy/CMP0050.rst @@ -0,0 +1,18 @@ +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. diff --git a/Help/policy/CMP0051.rst b/Help/policy/CMP0051.rst new file mode 100644 index 0000000000..1b56cb0a71 --- /dev/null +++ b/Help/policy/CMP0051.rst @@ -0,0 +1,24 @@ +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. diff --git a/Help/policy/CMP0052.rst b/Help/policy/CMP0052.rst new file mode 100644 index 0000000000..48cfc9c70e --- /dev/null +++ b/Help/policy/CMP0052.rst @@ -0,0 +1,24 @@ +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. diff --git a/Help/policy/CMP0053.rst b/Help/policy/CMP0053.rst new file mode 100644 index 0000000000..fac430e6e4 --- /dev/null +++ b/Help/policy/CMP0053.rst @@ -0,0 +1,44 @@ +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. diff --git a/Help/policy/CMP0054.rst b/Help/policy/CMP0054.rst new file mode 100644 index 0000000000..dffee5e81a --- /dev/null +++ b/Help/policy/CMP0054.rst @@ -0,0 +1,18 @@ +CMP0054 +------- + +Only interpret :command:`if` arguments as variables or keywords when unquoted. + +CMake 3.1 and above no longer 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. + +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. diff --git a/Help/policy/DISALLOWED_COMMAND.txt b/Help/policy/DISALLOWED_COMMAND.txt new file mode 100644 index 0000000000..36280d2b63 --- /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 0000000000..a0a4f73bb2 --- /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 0000000000..71a86d0551 --- /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 0000000000..3ad70354da --- /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 0000000000..2f8e32e3fc --- /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 0000000000..eb75c2ab2f --- /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 0000000000..59aabd431a --- /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 0000000000..e32eed3ed5 --- /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/CACHE_VARIABLES.rst b/Help/prop_dir/CACHE_VARIABLES.rst new file mode 100644 index 0000000000..2c66f939e5 --- /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 0000000000..9a4173e81e --- /dev/null +++ b/Help/prop_dir/CLEAN_NO_CUSTOM.rst @@ -0,0 +1,7 @@ +CLEAN_NO_CUSTOM +--------------- + +Should the output of custom commands be left. + +If this is true then the outputs of custom commands for this directory +will not be removed during the "make clean" stage. diff --git a/Help/prop_dir/CMAKE_CONFIGURE_DEPENDS.rst b/Help/prop_dir/CMAKE_CONFIGURE_DEPENDS.rst new file mode 100644 index 0000000000..b1aef1966c --- /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 0000000000..ab7e7f0581 --- /dev/null +++ b/Help/prop_dir/COMPILE_DEFINITIONS.rst @@ -0,0 +1,32 @@ +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. The VS6 IDE does not support definition +values with spaces (but NMake does). + +.. 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 0000000000..a6af45f35b --- /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 0000000000..59530597dc --- /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 specifies the list of options given so far to the +:command:`add_compile_options` command. + +This property is used to populate the :prop_tgt:`COMPILE_OPTIONS` target +property, 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 0000000000..22f7c1542b --- /dev/null +++ b/Help/prop_dir/DEFINITIONS.rst @@ -0,0 +1,8 @@ +DEFINITIONS +----------- + +For CMake 2.4 compatibility only. Use COMPILE_DEFINITIONS instead. + +This read-only property specifies the list of flags given so far to +the add_definitions command. It is intended for debugging purposes. +Use the COMPILE_DEFINITIONS instead. diff --git a/Help/prop_dir/EXCLUDE_FROM_ALL.rst b/Help/prop_dir/EXCLUDE_FROM_ALL.rst new file mode 100644 index 0000000000..1aa24e44bf --- /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 0000000000..993f6200ef --- /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 0000000000..baba49bf35 --- /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 intial 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 0000000000..befafa58c5 --- /dev/null +++ b/Help/prop_dir/INCLUDE_REGULAR_EXPRESSION.rst @@ -0,0 +1,8 @@ +INCLUDE_REGULAR_EXPRESSION +-------------------------- + +Include file scanning regular expression. + +This read-only property specifies the regular expression used during +dependency scanning to match include files that should be followed. +See the include_regular_expression command. diff --git a/Help/prop_dir/INTERPROCEDURAL_OPTIMIZATION.rst b/Help/prop_dir/INTERPROCEDURAL_OPTIMIZATION.rst new file mode 100644 index 0000000000..0c78dfbe7f --- /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 0000000000..325208656a --- /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 0000000000..fa375766d6 --- /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 0000000000..f729c1e784 --- /dev/null +++ b/Help/prop_dir/LISTFILE_STACK.rst @@ -0,0 +1,9 @@ +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 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 0000000000..e4feadaa57 --- /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 0000000000..3bc5824c94 --- /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 0000000000..342d0ae79a --- /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 0000000000..93d1e0111e --- /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 0000000000..3cfb2369bc --- /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/TEST_INCLUDE_FILE.rst b/Help/prop_dir/TEST_INCLUDE_FILE.rst new file mode 100644 index 0000000000..e47795191a --- /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 0000000000..0328295c3f --- /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 0000000000..eb91832887 --- /dev/null +++ b/Help/prop_dir/VS_GLOBAL_SECTION_POST_section.rst @@ -0,0 +1,29 @@ +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 7 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. 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 0000000000..fbcd9e6f3d --- /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 7 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_gbl/ALLOW_DUPLICATE_CUSTOM_TARGETS.rst b/Help/prop_gbl/ALLOW_DUPLICATE_CUSTOM_TARGETS.rst new file mode 100644 index 0000000000..8fab503455 --- /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_TARGETS_FOLDER.rst b/Help/prop_gbl/AUTOGEN_TARGETS_FOLDER.rst new file mode 100644 index 0000000000..5a69ef31d8 --- /dev/null +++ b/Help/prop_gbl/AUTOGEN_TARGETS_FOLDER.rst @@ -0,0 +1,9 @@ +AUTOGEN_TARGETS_FOLDER +---------------------- + +Name of :prop_tgt:`FOLDER` for ``*_automoc`` 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_TARGETS_FOLDER.rst b/Help/prop_gbl/AUTOMOC_TARGETS_FOLDER.rst new file mode 100644 index 0000000000..671f86a855 --- /dev/null +++ b/Help/prop_gbl/AUTOMOC_TARGETS_FOLDER.rst @@ -0,0 +1,11 @@ +AUTOMOC_TARGETS_FOLDER +---------------------- + +Name of :prop_tgt:`FOLDER` for ``*_automoc`` 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/CMAKE_CXX_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst new file mode 100644 index 0000000000..bdeabdb2c6 --- /dev/null +++ b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst @@ -0,0 +1,298 @@ +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. + + +The features known to this version of CMake are: + +``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_. + + .. _N2928: http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2009/n2928.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, ss 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_. + + .. _N2928: http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2009/n2928.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 intialization, 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 0000000000..18cd030556 --- /dev/null +++ b/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst @@ -0,0 +1,26 @@ +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. + +The features known to this version of CMake are: + +``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 0000000000..690143f826 --- /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 0000000000..111cdf67e9 --- /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 0000000000..6d1529d3aa --- /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 0000000000..b03da5a458 --- /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 0000000000..43e3c09f7f --- /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_LIB64_PATHS.rst b/Help/prop_gbl/FIND_LIBRARY_USE_LIB64_PATHS.rst new file mode 100644 index 0000000000..185246cda0 --- /dev/null +++ b/Help/prop_gbl/FIND_LIBRARY_USE_LIB64_PATHS.rst @@ -0,0 +1,9 @@ +FIND_LIBRARY_USE_LIB64_PATHS +---------------------------- + +Whether FIND_LIBRARY should automatically search lib64 directories. + +FIND_LIBRARY_USE_LIB64_PATHS is a boolean specifying whether the +FIND_LIBRARY command should automatically search the lib64 variant of +directories called lib in the search path when building 64-bit +binaries. 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 0000000000..9a3edd869c --- /dev/null +++ b/Help/prop_gbl/FIND_LIBRARY_USE_OPENBSD_VERSIONING.rst @@ -0,0 +1,9 @@ +FIND_LIBRARY_USE_OPENBSD_VERSIONING +----------------------------------- + +Whether FIND_LIBRARY should find OpenBSD-style shared libraries. + +This property is a boolean specifying whether the 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/GLOBAL_DEPENDS_DEBUG_MODE.rst b/Help/prop_gbl/GLOBAL_DEPENDS_DEBUG_MODE.rst new file mode 100644 index 0000000000..832503b512 --- /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 0000000000..d10661e629 --- /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 0000000000..3a2ef5b652 --- /dev/null +++ b/Help/prop_gbl/IN_TRY_COMPILE.rst @@ -0,0 +1,6 @@ +IN_TRY_COMPILE +-------------- + +Read-only property that is true during a try-compile configuration. + +True when building a project inside a TRY_COMPILE or TRY_RUN command. diff --git a/Help/prop_gbl/JOB_POOLS.rst b/Help/prop_gbl/JOB_POOLS.rst new file mode 100644 index 0000000000..98b9f7eaef --- /dev/null +++ b/Help/prop_gbl/JOB_POOLS.rst @@ -0,0 +1,20 @@ +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`. diff --git a/Help/prop_gbl/PACKAGES_FOUND.rst b/Help/prop_gbl/PACKAGES_FOUND.rst new file mode 100644 index 0000000000..61cce1fd8d --- /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 0000000000..ca3c5bac6f --- /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 0000000000..e85b823b18 --- /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 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 0000000000..29ba36557f --- /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 0000000000..980843bf89 --- /dev/null +++ b/Help/prop_gbl/RULE_LAUNCH_COMPILE.rst @@ -0,0 +1,9 @@ +RULE_LAUNCH_COMPILE +------------------- + +Specify a launcher for compile rules. + +Makefile generators prefix compiler commands with the given launcher +command line. This is intended to allow launchers to intercept build +problems with high granularity. Non-Makefile generators currently +ignore this property. diff --git a/Help/prop_gbl/RULE_LAUNCH_CUSTOM.rst b/Help/prop_gbl/RULE_LAUNCH_CUSTOM.rst new file mode 100644 index 0000000000..9d4a25ce77 --- /dev/null +++ b/Help/prop_gbl/RULE_LAUNCH_CUSTOM.rst @@ -0,0 +1,9 @@ +RULE_LAUNCH_CUSTOM +------------------ + +Specify a launcher for custom rules. + +Makefile generators prefix custom commands with the given launcher +command line. This is intended to allow launchers to intercept build +problems with high granularity. Non-Makefile generators currently +ignore this property. diff --git a/Help/prop_gbl/RULE_LAUNCH_LINK.rst b/Help/prop_gbl/RULE_LAUNCH_LINK.rst new file mode 100644 index 0000000000..191f1d504a --- /dev/null +++ b/Help/prop_gbl/RULE_LAUNCH_LINK.rst @@ -0,0 +1,9 @@ +RULE_LAUNCH_LINK +---------------- + +Specify a launcher for link rules. + +Makefile generators prefix link and archive commands with the given +launcher command line. This is intended to allow launchers to +intercept build problems with high granularity. Non-Makefile +generators currently ignore this property. diff --git a/Help/prop_gbl/RULE_MESSAGES.rst b/Help/prop_gbl/RULE_MESSAGES.rst new file mode 100644 index 0000000000..38d83a36b3 --- /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 0000000000..930febae71 --- /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_SUPPORTS_SHARED_LIBS.rst b/Help/prop_gbl/TARGET_SUPPORTS_SHARED_LIBS.rst new file mode 100644 index 0000000000..f6e89fb833 --- /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 0000000000..fdbca9f4ad --- /dev/null +++ b/Help/prop_gbl/USE_FOLDERS.rst @@ -0,0 +1,9 @@ +USE_FOLDERS +----------- + +Use the 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 FOLDER target property to name those folders. +See also the documentation for the FOLDER target property. diff --git a/Help/prop_inst/CPACK_NEVER_OVERWRITE.rst b/Help/prop_inst/CPACK_NEVER_OVERWRITE.rst new file mode 100644 index 0000000000..11f44d0df5 --- /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 0000000000..5e191d08e5 --- /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_WIX_ACL.rst b/Help/prop_inst/CPACK_WIX_ACL.rst new file mode 100644 index 0000000000..ee42666dab --- /dev/null +++ b/Help/prop_inst/CPACK_WIX_ACL.rst @@ -0,0 +1,18 @@ +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 0000000000..339d115287 --- /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 0000000000..d9dc4d33ed --- /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 0000000000..6dfabb0782 --- /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 0000000000..7f7e7c7954 --- /dev/null +++ b/Help/prop_sf/COMPILE_DEFINITIONS.rst @@ -0,0 +1,20 @@ +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. The VS6 IDE does not support definition +values with spaces (but NMake does). 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 0000000000..8487076478 --- /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 0000000000..daba50231f --- /dev/null +++ b/Help/prop_sf/COMPILE_FLAGS.rst @@ -0,0 +1,8 @@ +COMPILE_FLAGS +------------- + +Additional flags to be added when compiling this source file. + +These flags will be added to the list of compile flags when this +source file builds. Use COMPILE_DEFINITIONS to pass additional +preprocessor definitions. diff --git a/Help/prop_sf/EXTERNAL_OBJECT.rst b/Help/prop_sf/EXTERNAL_OBJECT.rst new file mode 100644 index 0000000000..efa0e9bea1 --- /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 0000000000..69e34aafd7 --- /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 0000000000..a3aa127471 --- /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 0000000000..b4fb2db22e --- /dev/null +++ b/Help/prop_sf/HEADER_FILE_ONLY.rst @@ -0,0 +1,9 @@ +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. diff --git a/Help/prop_sf/KEEP_EXTENSION.rst b/Help/prop_sf/KEEP_EXTENSION.rst new file mode 100644 index 0000000000..d6167e5a9a --- /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 0000000000..e1c10696a5 --- /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 0000000000..97bfa20f46 --- /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 0000000000..252d680240 --- /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 0000000000..27f292961f --- /dev/null +++ b/Help/prop_sf/MACOSX_PACKAGE_LOCATION.rst @@ -0,0 +1,19 @@ +MACOSX_PACKAGE_LOCATION +----------------------- + +Place a source file inside a Mac OS X bundle, CFBundle, or framework. + +Executable targets with the MACOSX_BUNDLE property set are built as +Mac OS X application bundles on Apple platforms. Shared library +targets with the FRAMEWORK property set are built as Mac OS X +frameworks on Apple platforms. Module library targets with the BUNDLE +property set are built as Mac 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 bundles the content +folder is "<name>.app/Contents". For frameworks the content folder is +"<name>.framework/Versions/<version>". For cfbundles the content +folder is "<name>.bundle/Contents" (unless the extension is changed). +See the PUBLIC_HEADER, PRIVATE_HEADER, and RESOURCE target properties +for specifying files meant for Headers, PrivateHeaders, or Resources +directories. diff --git a/Help/prop_sf/OBJECT_DEPENDS.rst b/Help/prop_sf/OBJECT_DEPENDS.rst new file mode 100644 index 0000000000..18022de23b --- /dev/null +++ b/Help/prop_sf/OBJECT_DEPENDS.rst @@ -0,0 +1,18 @@ +OBJECT_DEPENDS +-------------- + +Additional files on which a compiled object file depends. + +Specifies a semicolon-separated list of full-paths to files on which +any object files compiled from this source file depend. An object +file will be recompiled if any of the named files is newer than it. + +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 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 0000000000..6a28553740 --- /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/SYMBOLIC.rst b/Help/prop_sf/SYMBOLIC.rst new file mode 100644 index 0000000000..c7d0b2603c --- /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_DEPLOYMENT_CONTENT.rst b/Help/prop_sf/VS_DEPLOYMENT_CONTENT.rst new file mode 100644 index 0000000000..9fb3ba3d03 --- /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_SHADER_TYPE.rst b/Help/prop_sf/VS_SHADER_TYPE.rst new file mode 100644 index 0000000000..6880256080 --- /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/WRAP_EXCLUDE.rst b/Help/prop_sf/WRAP_EXCLUDE.rst new file mode 100644 index 0000000000..2c79f72a2e --- /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 0000000000..1b24701a3a --- /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_LAST_KNOWN_FILE_TYPE.rst b/Help/prop_sf/XCODE_LAST_KNOWN_FILE_TYPE.rst new file mode 100644 index 0000000000..42e37574db --- /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 0000000000..496d800710 --- /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 0000000000..6819143340 --- /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 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 0000000000..3236a02958 --- /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 0000000000..ee946d938b --- /dev/null +++ b/Help/prop_test/DEPENDS.rst @@ -0,0 +1,6 @@ +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. diff --git a/Help/prop_test/ENVIRONMENT.rst b/Help/prop_test/ENVIRONMENT.rst new file mode 100644 index 0000000000..df9bc9e14e --- /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 0000000000..b02d17dbbf --- /dev/null +++ b/Help/prop_test/FAIL_REGULAR_EXPRESSION.rst @@ -0,0 +1,8 @@ +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.For example: FAIL_REGULAR_EXPRESSION +"[^a-z]Error;ERROR;Failed" diff --git a/Help/prop_test/LABELS.rst b/Help/prop_test/LABELS.rst new file mode 100644 index 0000000000..8d75570959 --- /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 0000000000..bc4936e97c --- /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 0000000000..bb35f77345 --- /dev/null +++ b/Help/prop_test/PASS_REGULAR_EXPRESSION.rst @@ -0,0 +1,8 @@ +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. diff --git a/Help/prop_test/PROCESSORS.rst b/Help/prop_test/PROCESSORS.rst new file mode 100644 index 0000000000..763b6d0036 --- /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 0000000000..fac357c1e0 --- /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 0000000000..8c30f0177c --- /dev/null +++ b/Help/prop_test/RESOURCE_LOCK.rst @@ -0,0 +1,7 @@ +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. diff --git a/Help/prop_test/RUN_SERIAL.rst b/Help/prop_test/RUN_SERIAL.rst new file mode 100644 index 0000000000..8f65ae18a7 --- /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 0000000000..c61273c56c --- /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 0000000000..0b247b8601 --- /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 CTEST_TESTING_TIMEOUT. diff --git a/Help/prop_test/WILL_FAIL.rst b/Help/prop_test/WILL_FAIL.rst new file mode 100644 index 0000000000..f1f94a43a7 --- /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 0000000000..5222a197bd --- /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 0000000000..f9e60348db --- /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_API.rst b/Help/prop_tgt/ANDROID_API.rst new file mode 100644 index 0000000000..714ad584af --- /dev/null +++ b/Help/prop_tgt/ANDROID_API.rst @@ -0,0 +1,7 @@ +ANDROID_API +----------- + +Set 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_GUI.rst b/Help/prop_tgt/ANDROID_GUI.rst new file mode 100644 index 0000000000..90d2428b1f --- /dev/null +++ b/Help/prop_tgt/ANDROID_GUI.rst @@ -0,0 +1,9 @@ +ANDROID_GUI +----------- + +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. diff --git a/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY.rst b/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY.rst new file mode 100644 index 0000000000..df57dbaafe --- /dev/null +++ b/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY.rst @@ -0,0 +1,7 @@ +ARCHIVE_OUTPUT_DIRECTORY +------------------------ + +.. |XXX| replace:: ARCHIVE +.. |xxx| replace:: archive +.. |CMAKE_XXX_OUTPUT_DIRECTORY| replace:: CMAKE_ARCHIVE_OUTPUT_DIRECTORY +.. include:: XXX_OUTPUT_DIRECTORY.txt 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 0000000000..3c0c4fdffe --- /dev/null +++ b/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY_CONFIG.rst @@ -0,0 +1,11 @@ +ARCHIVE_OUTPUT_DIRECTORY_<CONFIG> +--------------------------------- + +Per-configuration output directory for ARCHIVE target files. + +This is a per-configuration version of ARCHIVE_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_ARCHIVE_OUTPUT_DIRECTORY_<CONFIG> if it is set when a target is +created. diff --git a/Help/prop_tgt/ARCHIVE_OUTPUT_NAME.rst b/Help/prop_tgt/ARCHIVE_OUTPUT_NAME.rst new file mode 100644 index 0000000000..a137bb8911 --- /dev/null +++ b/Help/prop_tgt/ARCHIVE_OUTPUT_NAME.rst @@ -0,0 +1,6 @@ +ARCHIVE_OUTPUT_NAME +------------------- + +.. |XXX| replace:: ARCHIVE +.. |xxx| replace:: archive +.. include:: XXX_OUTPUT_NAME.txt 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 0000000000..314fa58b6b --- /dev/null +++ b/Help/prop_tgt/ARCHIVE_OUTPUT_NAME_CONFIG.rst @@ -0,0 +1,6 @@ +ARCHIVE_OUTPUT_NAME_<CONFIG> +---------------------------- + +Per-configuration output name for ARCHIVE target files. + +This is the configuration-specific version of ARCHIVE_OUTPUT_NAME. diff --git a/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst b/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst new file mode 100644 index 0000000000..5063244b53 --- /dev/null +++ b/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst @@ -0,0 +1,17 @@ +AUTOGEN_TARGET_DEPENDS +---------------------- + +Target dependencies of the corresponding ``_automoc`` target. + +Targets which have their :prop_tgt:`AUTOMOC` target ``ON`` have a +corresponding ``_automoc`` target which is used to autogenerate generate moc +files. As this ``_automoc`` 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 ``_automoc`` 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 0000000000..045ebb275f --- /dev/null +++ b/Help/prop_tgt/AUTOMOC.rst @@ -0,0 +1,37 @@ +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 +source files at build time and invoke moc accordingly. If an ``#include`` +statement like ``#include "moc_foo.cpp"`` is found, the ``Q_OBJECT`` class +declaration is expected in the header, and ``moc`` is run on the header +file. If an ``#include`` statement like ``#include "foo.moc"`` is found, then +a ``Q_OBJECT`` is expected in the current source file and ``moc`` is run on +the file itself. Additionally, header files with the same base name (like +``foo.h``) or ``_p`` appended to the base name (like ``foo_p.h``) are parsed +for ``Q_OBJECT`` macros, and if found, ``moc`` is also executed on those files. +``AUTOMOC`` checks multiple header alternative extensions, such as +``hpp``, ``hxx`` etc when searching for headers. +The resulting moc files, which are not included as shown above in any +of the source files are included in a generated +``<targetname>_automoc.cpp`` file, which is compiled as part of the +target. 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. + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. diff --git a/Help/prop_tgt/AUTOMOC_MOC_OPTIONS.rst b/Help/prop_tgt/AUTOMOC_MOC_OPTIONS.rst new file mode 100644 index 0000000000..ebd5c4951b --- /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 0000000000..8dce6b184f --- /dev/null +++ b/Help/prop_tgt/AUTORCC.rst @@ -0,0 +1,23 @@ +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. + +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 0000000000..8a0f632c23 --- /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 0000000000..4e60ec33ab --- /dev/null +++ b/Help/prop_tgt/AUTOUIC.rst @@ -0,0 +1,24 @@ +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 ``foo.cpp``, a ``foo.ui`` file is +expected next to ``foo.cpp``, and ``uic`` is run on the ``foo.ui`` file. +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. + +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 0000000000..dc3bee55f5 --- /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/BUILD_WITH_INSTALL_RPATH.rst b/Help/prop_tgt/BUILD_WITH_INSTALL_RPATH.rst new file mode 100644 index 0000000000..abcf28ffdb --- /dev/null +++ b/Help/prop_tgt/BUILD_WITH_INSTALL_RPATH.rst @@ -0,0 +1,11 @@ +BUILD_WITH_INSTALL_RPATH +------------------------ + +Should build tree targets have install tree rpaths. + +BUILD_WITH_INSTALL_RPATH is a boolean specifying whether to link the +target in the build tree with the INSTALL_RPATH. This takes +precedence over 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 if it is set when a target is +created. diff --git a/Help/prop_tgt/BUNDLE.rst b/Help/prop_tgt/BUNDLE.rst new file mode 100644 index 0000000000..166659fb29 --- /dev/null +++ b/Help/prop_tgt/BUNDLE.rst @@ -0,0 +1,9 @@ +BUNDLE +------ + +This target is a CFBundle on the Mac. + +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 0000000000..94ac935bcf --- /dev/null +++ b/Help/prop_tgt/BUNDLE_EXTENSION.rst @@ -0,0 +1,7 @@ +BUNDLE_EXTENSION +---------------- + +The file extension used to name a BUNDLE target on the Mac. + +The default value is "bundle" - you can also use "plugin" or whatever +file extension is required by the host app for your bundle. diff --git a/Help/prop_tgt/COMPATIBLE_INTERFACE_BOOL.rst b/Help/prop_tgt/COMPATIBLE_INTERFACE_BOOL.rst new file mode 100644 index 0000000000..6910367e4e --- /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 0000000000..298acf1ba3 --- /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 0000000000..d5fd8252a8 --- /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 0000000000..a0050b9418 --- /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 0000000000..00c49c3795 --- /dev/null +++ b/Help/prop_tgt/COMPILE_DEFINITIONS.rst @@ -0,0 +1,26 @@ +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. The VS6 IDE does not support definition +values with spaces (but NMake does). + +.. 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 0000000000..84bd5e4831 --- /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 0000000000..225ffeecae --- /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. diff --git a/Help/prop_tgt/COMPILE_FLAGS.rst b/Help/prop_tgt/COMPILE_FLAGS.rst new file mode 100644 index 0000000000..6ee6c51486 --- /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 COMPILE_DEFINITIONS to pass +additional preprocessor definitions. + +This property is deprecated. Use the COMPILE_OPTIONS property or the +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 0000000000..27cbec15f2 --- /dev/null +++ b/Help/prop_tgt/COMPILE_OPTIONS.rst @@ -0,0 +1,16 @@ +COMPILE_OPTIONS +--------------- + +List of options to pass to the compiler. + +This property specifies the list of options specified so far for this +property. + +This property is intialized by the :prop_dir:`COMPILE_OPTIONS` directory +property, 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_tgt/COMPILE_PDB_NAME.rst b/Help/prop_tgt/COMPILE_PDB_NAME.rst new file mode 100644 index 0000000000..24a9f62d6e --- /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 0000000000..e4077f559a --- /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 0000000000..5941d72efe --- /dev/null +++ b/Help/prop_tgt/COMPILE_PDB_NOTE.txt @@ -0,0 +1,8 @@ +.. 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. + + This property is not implemented by the :generator:`Visual Studio 6` + generator. 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 0000000000..34f49bebef --- /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 0000000000..52ef013da1 --- /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 0000000000..f2c875ef55 --- /dev/null +++ b/Help/prop_tgt/CONFIG_OUTPUT_NAME.rst @@ -0,0 +1,7 @@ +<CONFIG>_OUTPUT_NAME +-------------------- + +Old per-configuration target file base name. + +This is a configuration-specific version of OUTPUT_NAME. Use +OUTPUT_NAME_<CONFIG> instead. diff --git a/Help/prop_tgt/CONFIG_POSTFIX.rst b/Help/prop_tgt/CONFIG_POSTFIX.rst new file mode 100644 index 0000000000..11b50b900f --- /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/CXX_EXTENSIONS.rst b/Help/prop_tgt/CXX_EXTENSIONS.rst new file mode 100644 index 0000000000..67c5cb0153 --- /dev/null +++ b/Help/prop_tgt/CXX_EXTENSIONS.rst @@ -0,0 +1,16 @@ +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. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features. + +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 0000000000..b50cdf9c75 --- /dev/null +++ b/Help/prop_tgt/CXX_STANDARD.rst @@ -0,0 +1,30 @@ +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. + +Supported values are ``98`` 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 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. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features. + +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 0000000000..ac103a46cc --- /dev/null +++ b/Help/prop_tgt/CXX_STANDARD_REQUIRED.rst @@ -0,0 +1,17 @@ +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. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features. + +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 0000000000..dc48cc6438 --- /dev/null +++ b/Help/prop_tgt/C_EXTENSIONS.rst @@ -0,0 +1,16 @@ +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. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features. + +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 0000000000..88ca9264db --- /dev/null +++ b/Help/prop_tgt/C_STANDARD.rst @@ -0,0 +1,30 @@ +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. + +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. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features. + +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 0000000000..a7304f4386 --- /dev/null +++ b/Help/prop_tgt/C_STANDARD_REQUIRED.rst @@ -0,0 +1,17 @@ +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. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features. + +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 0000000000..1487656d95 --- /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 0000000000..f47f135eaa --- /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/ENABLE_EXPORTS.rst b/Help/prop_tgt/ENABLE_EXPORTS.rst new file mode 100644 index 0000000000..283f5a8b23 --- /dev/null +++ b/Help/prop_tgt/ENABLE_EXPORTS.rst @@ -0,0 +1,19 @@ +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 +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 Mac 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. diff --git a/Help/prop_tgt/EXCLUDE_FROM_ALL.rst b/Help/prop_tgt/EXCLUDE_FROM_ALL.rst new file mode 100644 index 0000000000..caa5741f85 --- /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 0000000000..19270a59d9 --- /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 7 and above. +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 0000000000..655a9dee0c --- /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 0000000000..1b4247cc5b --- /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 0000000000..32ae2aa8ff --- /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 0000000000..bfe4e8e166 --- /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 0000000000..9f472c025a --- /dev/null +++ b/Help/prop_tgt/FRAMEWORK.rst @@ -0,0 +1,9 @@ +FRAMEWORK +--------- + +This target is a framework on the Mac. + +If a shared library target has this property set to true it will be +built as a framework when built on the mac. It will have the +directory structure required for a framework and will be suitable to +be used with the -framework option diff --git a/Help/prop_tgt/Fortran_FORMAT.rst b/Help/prop_tgt/Fortran_FORMAT.rst new file mode 100644 index 0000000000..0a11d91caa --- /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 0000000000..9c86437644 --- /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 0000000000..032b22acf4 --- /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 0000000000..cf34da9c3e --- /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 0000000000..7790932aea --- /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 0000000000..dc738071d4 --- /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 0000000000..605c1ce6cb --- /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 0000000000..6de1baa235 --- /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 0000000000..acf4b321f8 --- /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 0000000000..b4b3f0228d --- /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_LINK_DEPENDENT_LIBRARIES.rst b/Help/prop_tgt/IMPORTED_LINK_DEPENDENT_LIBRARIES.rst new file mode 100644 index 0000000000..2db2b0e58c --- /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 0000000000..ee243c75da --- /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 0000000000..5ca9c8b6f7 --- /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 0000000000..d4a10fbddc --- /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 0000000000..61134a4019 --- /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 0000000000..13b93ba98d --- /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 0000000000..3a86b9985f --- /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 0000000000..33b9b84199 --- /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 0000000000..8cfef7343b --- /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 0000000000..f85bb19c93 --- /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 0000000000..4a1bb447ac --- /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 0000000000..22d68220c8 --- /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_SONAME.rst b/Help/prop_tgt/IMPORTED_SONAME.rst new file mode 100644 index 0000000000..d80907e3e8 --- /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 0000000000..6ec9af3f83 --- /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 0000000000..deede97880 --- /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 0000000000..bd01250378 --- /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 0000000000..8b40d9c346 --- /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 0000000000..a67ec15849 --- /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 0000000000..6206b6889b --- /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 0000000000..f0006f85b3 --- /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 0000000000..e97d293180 --- /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_COMPILE_DEFINITIONS.rst b/Help/prop_tgt/INTERFACE_COMPILE_DEFINITIONS.rst new file mode 100644 index 0000000000..910b661fed --- /dev/null +++ b/Help/prop_tgt/INTERFACE_COMPILE_DEFINITIONS.rst @@ -0,0 +1,15 @@ +INTERFACE_COMPILE_DEFINITIONS +----------------------------- + +List of public compile definitions for a library. + +Targets may populate this property to publish the compile definitions +required to compile against the headers for the target. Consuming +targets can add entries to their own :prop_tgt:`COMPILE_DEFINITIONS` +property such as ``$<TARGET_PROPERTY:foo,INTERFACE_COMPILE_DEFINITIONS>`` +to use the compile definitions specified in the interface of ``foo``. + +Contents of ``INTERFACE_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/prop_tgt/INTERFACE_COMPILE_FEATURES.rst b/Help/prop_tgt/INTERFACE_COMPILE_FEATURES.rst new file mode 100644 index 0000000000..7abdecbdbd --- /dev/null +++ b/Help/prop_tgt/INTERFACE_COMPILE_FEATURES.rst @@ -0,0 +1,16 @@ +INTERFACE_COMPILE_FEATURES +-------------------------- + +List of public compile requirements for a library. + +Targets may populate this property to publish the compiler features +required to compile against the headers for the target. Consuming +targets can add entries to their own :prop_tgt:`COMPILE_FEATURES` +property such as ``$<TARGET_PROPERTY:foo,INTERFACE_COMPILE_FEATURES>`` +to require the features specified in the interface of ``foo``. + +Contents of ``INTERFACE_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. diff --git a/Help/prop_tgt/INTERFACE_COMPILE_OPTIONS.rst b/Help/prop_tgt/INTERFACE_COMPILE_OPTIONS.rst new file mode 100644 index 0000000000..d0a38d6a26 --- /dev/null +++ b/Help/prop_tgt/INTERFACE_COMPILE_OPTIONS.rst @@ -0,0 +1,15 @@ +INTERFACE_COMPILE_OPTIONS +------------------------- + +List of interface options to pass to the compiler. + +Targets may populate this property to publish the compile options +required to compile against the headers for the target. Consuming +targets can add entries to their own :prop_tgt:`COMPILE_OPTIONS` property +such as ``$<TARGET_PROPERTY:foo,INTERFACE_COMPILE_OPTIONS>`` to use the +compile options specified in the interface of ``foo``. + +Contents of ``INTERFACE_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/INTERFACE_INCLUDE_DIRECTORIES.rst b/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst new file mode 100644 index 0000000000..899e821f7c --- /dev/null +++ b/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst @@ -0,0 +1,33 @@ +INTERFACE_INCLUDE_DIRECTORIES +----------------------------- + +List of public include directories for a library. + +The :command:`target_include_directories` command populates this property +with values given to the ``PUBLIC`` and ``INTERFACE`` keywords. Projects +may also get and set the property directly. + +Targets may populate this property to publish the include directories +required to compile against the headers for the target. Consuming +targets can add entries to their own :prop_tgt:`INCLUDE_DIRECTORIES` +property such as ``$<TARGET_PROPERTY:foo,INTERFACE_INCLUDE_DIRECTORIES>`` +to use the include directories specified in the interface of ``foo``. + +Contents of ``INTERFACE_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 + + set_property(TARGET mylib APPEND PROPERTY INTERFACE_INCLUDE_DIRECTORIES + $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib> + $<INSTALL_INTERFACE:include/mylib> # <prefix>/include/mylib + ) diff --git a/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst new file mode 100644 index 0000000000..8e4843b481 --- /dev/null +++ b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst @@ -0,0 +1,17 @@ +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 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. 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 0000000000..ea700dfe98 --- /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 0000000000..fb28231a31 --- /dev/null +++ b/Help/prop_tgt/INTERFACE_SOURCES.rst @@ -0,0 +1,15 @@ +INTERFACE_SOURCES +----------------- + +List of interface sources to pass to the compiler. + +Targets may populate this property to publish the sources +for consuming targets to compile. Consuming +targets can add entries to their own :prop_tgt:`SOURCES` property +such as ``$<TARGET_PROPERTY:foo,INTERFACE_SOURCES>`` to use the +sources specified in the interface of ``foo``. + +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 0000000000..9e603ee5ac --- /dev/null +++ b/Help/prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES.rst @@ -0,0 +1,15 @@ +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. Consuming targets will then mark the same include +directories as 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 0000000000..effa3b01f8 --- /dev/null +++ b/Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION.rst @@ -0,0 +1,7 @@ +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. diff --git a/Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst b/Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst new file mode 100644 index 0000000000..492fee0789 --- /dev/null +++ b/Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst @@ -0,0 +1,8 @@ +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. diff --git a/Help/prop_tgt/JOB_POOL_COMPILE.rst b/Help/prop_tgt/JOB_POOL_COMPILE.rst new file mode 100644 index 0000000000..5d8e940387 --- /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 0000000000..716f53f71a --- /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 specifing 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 0000000000..5e464696dc --- /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_VISIBILITY_PRESET.rst b/Help/prop_tgt/LANG_VISIBILITY_PRESET.rst new file mode 100644 index 0000000000..d4bde179b7 --- /dev/null +++ b/Help/prop_tgt/LANG_VISIBILITY_PRESET.rst @@ -0,0 +1,10 @@ +<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 only has an affect for libraries and executables with +exports. This property is initialized by the value of the variable +CMAKE_<LANG>_VISIBILITY_PRESET 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 0000000000..e1d3a82ad8 --- /dev/null +++ b/Help/prop_tgt/LIBRARY_OUTPUT_DIRECTORY.rst @@ -0,0 +1,7 @@ +LIBRARY_OUTPUT_DIRECTORY +------------------------ + +.. |XXX| replace:: LIBRARY +.. |xxx| replace:: library +.. |CMAKE_XXX_OUTPUT_DIRECTORY| replace:: CMAKE_LIBRARY_OUTPUT_DIRECTORY +.. include:: XXX_OUTPUT_DIRECTORY.txt 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 0000000000..2a38373054 --- /dev/null +++ b/Help/prop_tgt/LIBRARY_OUTPUT_DIRECTORY_CONFIG.rst @@ -0,0 +1,11 @@ +LIBRARY_OUTPUT_DIRECTORY_<CONFIG> +--------------------------------- + +Per-configuration output directory for LIBRARY target files. + +This is a per-configuration version of LIBRARY_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_LIBRARY_OUTPUT_DIRECTORY_<CONFIG> if it is set when a target is +created. diff --git a/Help/prop_tgt/LIBRARY_OUTPUT_NAME.rst b/Help/prop_tgt/LIBRARY_OUTPUT_NAME.rst new file mode 100644 index 0000000000..9e9d4018c1 --- /dev/null +++ b/Help/prop_tgt/LIBRARY_OUTPUT_NAME.rst @@ -0,0 +1,6 @@ +LIBRARY_OUTPUT_NAME +------------------- + +.. |XXX| replace:: LIBRARY +.. |xxx| replace:: library +.. include:: XXX_OUTPUT_NAME.txt 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 0000000000..785d1b2dc3 --- /dev/null +++ b/Help/prop_tgt/LIBRARY_OUTPUT_NAME_CONFIG.rst @@ -0,0 +1,6 @@ +LIBRARY_OUTPUT_NAME_<CONFIG> +---------------------------- + +Per-configuration output name for LIBRARY target files. + +This is the configuration-specific version of LIBRARY_OUTPUT_NAME. diff --git a/Help/prop_tgt/LINKER_LANGUAGE.rst b/Help/prop_tgt/LINKER_LANGUAGE.rst new file mode 100644 index 0000000000..b1ca86710e --- /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 0000000000..5576b85fa6 --- /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 0000000000..5c6778d245 --- /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 0000000000..409d00a291 --- /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 0000000000..ba7adc84f6 --- /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 0000000000..435e25e2fb --- /dev/null +++ b/Help/prop_tgt/LINK_INTERFACE_LIBRARIES.rst @@ -0,0 +1,22 @@ +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 ENABLE_EXPORTS 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 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 if it is set when +a target is created. This property is ignored for STATIC libraries. + +This property is overridden by the INTERFACE_LINK_LIBRARIES property if +policy CMP0022 is NEW. + +This property is deprecated. Use INTERFACE_LINK_LIBRARIES instead. 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 0000000000..08bd6501b3 --- /dev/null +++ b/Help/prop_tgt/LINK_INTERFACE_LIBRARIES_CONFIG.rst @@ -0,0 +1,13 @@ +LINK_INTERFACE_LIBRARIES_<CONFIG> +--------------------------------- + +Per-configuration list of public interface libraries for a target. + +This is the configuration-specific version of +LINK_INTERFACE_LIBRARIES. If set, this property completely overrides +the generic property for the named configuration. + +This property is overridden by the INTERFACE_LINK_LIBRARIES property if +policy CMP0022 is NEW. + +This property is deprecated. Use INTERFACE_LINK_LIBRARIES instead. diff --git a/Help/prop_tgt/LINK_INTERFACE_MULTIPLICITY.rst b/Help/prop_tgt/LINK_INTERFACE_MULTIPLICITY.rst new file mode 100644 index 0000000000..4e26388a93 --- /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 0000000000..5ea4a45cf6 --- /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 0000000000..aa4b9f55f4 --- /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 0000000000..fe105bd6c4 --- /dev/null +++ b/Help/prop_tgt/LINK_SEARCH_END_STATIC.rst @@ -0,0 +1,14 @@ +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. 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 0000000000..ca899feaa0 --- /dev/null +++ b/Help/prop_tgt/LINK_SEARCH_START_STATIC.rst @@ -0,0 +1,14 @@ +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). See also LINK_SEARCH_END_STATIC. diff --git a/Help/prop_tgt/LOCATION.rst b/Help/prop_tgt/LOCATION.rst new file mode 100644 index 0000000000..16d5696e59 --- /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 0000000000..ac6bdb7867 --- /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 0000000000..ff21e61473 --- /dev/null +++ b/Help/prop_tgt/MACOSX_BUNDLE.rst @@ -0,0 +1,12 @@ +MACOSX_BUNDLE +------------- + +Build an executable as an application bundle on Mac OS X. + +When this property is set to true the executable when built on Mac OS +X will be created as an application bundle. This makes it a GUI +executable that can be launched from the Finder. See the +MACOSX_BUNDLE_INFO_PLIST target property for information about +creation of the Info.plist file for the application bundle. This +property is initialized by the value of the variable +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 0000000000..097cce1869 --- /dev/null +++ b/Help/prop_tgt/MACOSX_BUNDLE_INFO_PLIST.rst @@ -0,0 +1,29 @@ +MACOSX_BUNDLE_INFO_PLIST +------------------------ + +Specify a custom Info.plist template for a Mac OS X App Bundle. + +An executable target with MACOSX_BUNDLE enabled will be built as an +application bundle on Mac OS X. By default its Info.plist file is +created by configuring a template called MacOSXBundleInfo.plist.in +located in the 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_INFO_STRING + MACOSX_BUNDLE_ICON_FILE + MACOSX_BUNDLE_GUI_IDENTIFIER + MACOSX_BUNDLE_LONG_VERSION_STRING + MACOSX_BUNDLE_BUNDLE_NAME + MACOSX_BUNDLE_SHORT_VERSION_STRING + MACOSX_BUNDLE_BUNDLE_VERSION + MACOSX_BUNDLE_COPYRIGHT + +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 0000000000..729d929022 --- /dev/null +++ b/Help/prop_tgt/MACOSX_FRAMEWORK_INFO_PLIST.rst @@ -0,0 +1,25 @@ +MACOSX_FRAMEWORK_INFO_PLIST +--------------------------- + +Specify a custom Info.plist template for a Mac OS X Framework. + +A library target with FRAMEWORK enabled will be built as a framework +on Mac OS X. By default its Info.plist file is created by configuring +a template called MacOSXFrameworkInfo.plist.in located in the +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_ICON_FILE + MACOSX_FRAMEWORK_IDENTIFIER + MACOSX_FRAMEWORK_SHORT_VERSION_STRING + MACOSX_FRAMEWORK_BUNDLE_VERSION + +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 0000000000..d3934bae28 --- /dev/null +++ b/Help/prop_tgt/MACOSX_RPATH.rst @@ -0,0 +1,18 @@ +MACOSX_RPATH +------------ + +Whether to use rpaths on Mac OS X. + +When this property is set to true, the directory portion of +the "install_name" field of shared libraries will be ``@rpath`` +unless overridden by :prop_tgt:`INSTALL_NAME_DIR`. Runtime +paths will also be embedded in binaries using this target and +can be controlled by the :prop_tgt:`INSTALL_RPATH` target property. +This property is initialized by the value of the variable +:variable:`CMAKE_MACOSX_RPATH` if it is set when a target is +created. + +Policy CMP0042 was introduced to change the default value of +MACOSX_RPATH to ON. 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/MAP_IMPORTED_CONFIG_CONFIG.rst b/Help/prop_tgt/MAP_IMPORTED_CONFIG_CONFIG.rst new file mode 100644 index 0000000000..09ff0cee65 --- /dev/null +++ b/Help/prop_tgt/MAP_IMPORTED_CONFIG_CONFIG.rst @@ -0,0 +1,19 @@ +MAP_IMPORTED_CONFIG_<CONFIG> +---------------------------- + +Map from project configuration to IMPORTED target'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 is selected. 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> if it is set when a target is +created. diff --git a/Help/prop_tgt/NAME.rst b/Help/prop_tgt/NAME.rst new file mode 100644 index 0000000000..ddd84f23c5 --- /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 0000000000..fc668b588e --- /dev/null +++ b/Help/prop_tgt/NO_SONAME.rst @@ -0,0 +1,14 @@ +NO_SONAME +--------- + +Whether to set "soname" when linking a shared library or module. + +Enable this boolean property if a generated shared library or module +should not have "soname" set. Default is to set "soname" on all +shared libraries and modules 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 0000000000..070dd3018b --- /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 0000000000..cefe03f5b5 --- /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 0000000000..f8fdcff6fa --- /dev/null +++ b/Help/prop_tgt/OSX_ARCHITECTURES_CONFIG.rst @@ -0,0 +1,7 @@ +OSX_ARCHITECTURES_<CONFIG> +-------------------------- + +Per-configuration OS X 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 0000000000..97bf01094e --- /dev/null +++ b/Help/prop_tgt/OUTPUT_NAME.rst @@ -0,0 +1,8 @@ +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. diff --git a/Help/prop_tgt/OUTPUT_NAME_CONFIG.rst b/Help/prop_tgt/OUTPUT_NAME_CONFIG.rst new file mode 100644 index 0000000000..7bfbcbccfe --- /dev/null +++ b/Help/prop_tgt/OUTPUT_NAME_CONFIG.rst @@ -0,0 +1,6 @@ +OUTPUT_NAME_<CONFIG> +-------------------- + +Per-configuration target file base name. + +This is the configuration-specific version of OUTPUT_NAME. diff --git a/Help/prop_tgt/PDB_NAME.rst b/Help/prop_tgt/PDB_NAME.rst new file mode 100644 index 0000000000..479dec3f93 --- /dev/null +++ b/Help/prop_tgt/PDB_NAME.rst @@ -0,0 +1,11 @@ +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 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 0000000000..cb3121c2f3 --- /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 0000000000..f90ea81175 --- /dev/null +++ b/Help/prop_tgt/PDB_NOTE.txt @@ -0,0 +1,12 @@ +.. 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. + + This property is not implemented by the :generator:`Visual Studio 6` + generator. diff --git a/Help/prop_tgt/PDB_OUTPUT_DIRECTORY.rst b/Help/prop_tgt/PDB_OUTPUT_DIRECTORY.rst new file mode 100644 index 0000000000..730cf57767 --- /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 0000000000..6037fa0c7b --- /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 0000000000..54af8c6ded --- /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 0000000000..f1adb40b7d --- /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 0000000000..a16510461d --- /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 0000000000..113d7c56ae --- /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 0000000000..da2127b180 --- /dev/null +++ b/Help/prop_tgt/PRIVATE_HEADER.rst @@ -0,0 +1,11 @@ +PRIVATE_HEADER +-------------- + +Specify private header files in a FRAMEWORK shared library target. + +Shared library targets marked with the FRAMEWORK property generate +frameworks on OS X 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 0000000000..a1491ee139 --- /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 0000000000..6e25d94d53 --- /dev/null +++ b/Help/prop_tgt/PUBLIC_HEADER.rst @@ -0,0 +1,11 @@ +PUBLIC_HEADER +------------- + +Specify public header files in a FRAMEWORK shared library target. + +Shared library targets marked with the FRAMEWORK property generate +frameworks on OS X 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 0000000000..1e9921de3b --- /dev/null +++ b/Help/prop_tgt/RESOURCE.rst @@ -0,0 +1,11 @@ +RESOURCE +-------- + +Specify resource files in a FRAMEWORK shared library target. + +Shared library targets marked with the FRAMEWORK property generate +frameworks on OS X and normal shared libraries on other platforms. +This property may be set to a list of files to be placed in the +Resources directory inside the framework folder. On non-Apple +platforms these files may be installed using the RESOURCE option to +the install(TARGETS) command. diff --git a/Help/prop_tgt/RULE_LAUNCH_COMPILE.rst b/Help/prop_tgt/RULE_LAUNCH_COMPILE.rst new file mode 100644 index 0000000000..e92ab86aff --- /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 0000000000..2db03177f8 --- /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 0000000000..f330033678 --- /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 0000000000..af5ef447e6 --- /dev/null +++ b/Help/prop_tgt/RUNTIME_OUTPUT_DIRECTORY.rst @@ -0,0 +1,7 @@ +RUNTIME_OUTPUT_DIRECTORY +------------------------ + +.. |XXX| replace:: RUNTIME +.. |xxx| replace:: runtime +.. |CMAKE_XXX_OUTPUT_DIRECTORY| replace:: CMAKE_RUNTIME_OUTPUT_DIRECTORY +.. include:: XXX_OUTPUT_DIRECTORY.txt 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 0000000000..10be6cf0cd --- /dev/null +++ b/Help/prop_tgt/RUNTIME_OUTPUT_DIRECTORY_CONFIG.rst @@ -0,0 +1,11 @@ +RUNTIME_OUTPUT_DIRECTORY_<CONFIG> +--------------------------------- + +Per-configuration output directory for RUNTIME target files. + +This is a per-configuration version of RUNTIME_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_RUNTIME_OUTPUT_DIRECTORY_<CONFIG> if it is set when a target is +created. diff --git a/Help/prop_tgt/RUNTIME_OUTPUT_NAME.rst b/Help/prop_tgt/RUNTIME_OUTPUT_NAME.rst new file mode 100644 index 0000000000..dc7dba412b --- /dev/null +++ b/Help/prop_tgt/RUNTIME_OUTPUT_NAME.rst @@ -0,0 +1,6 @@ +RUNTIME_OUTPUT_NAME +------------------- + +.. |XXX| replace:: RUNTIME +.. |xxx| replace:: runtime +.. include:: XXX_OUTPUT_NAME.txt 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 0000000000..f9029e5d4e --- /dev/null +++ b/Help/prop_tgt/RUNTIME_OUTPUT_NAME_CONFIG.rst @@ -0,0 +1,6 @@ +RUNTIME_OUTPUT_NAME_<CONFIG> +---------------------------- + +Per-configuration output name for RUNTIME target files. + +This is the configuration-specific version of RUNTIME_OUTPUT_NAME. diff --git a/Help/prop_tgt/SKIP_BUILD_RPATH.rst b/Help/prop_tgt/SKIP_BUILD_RPATH.rst new file mode 100644 index 0000000000..a91fa9ca39 --- /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 0000000000..493643e841 --- /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/SOVERSION.rst b/Help/prop_tgt/SOVERSION.rst new file mode 100644 index 0000000000..672ff23a8d --- /dev/null +++ b/Help/prop_tgt/SOVERSION.rst @@ -0,0 +1,14 @@ +SOVERSION +--------- + +What version number is this target. + +For shared libraries 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 NO_SONAME property is set. 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. diff --git a/Help/prop_tgt/STATIC_LIBRARY_FLAGS.rst b/Help/prop_tgt/STATIC_LIBRARY_FLAGS.rst new file mode 100644 index 0000000000..d3b2cd4788 --- /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 0000000000..cca353ddce --- /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 0000000000..70844be5cc --- /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/TARGET_FILE_TYPES.txt b/Help/prop_tgt/TARGET_FILE_TYPES.txt new file mode 100644 index 0000000000..18489c7dc5 --- /dev/null +++ b/Help/prop_tgt/TARGET_FILE_TYPES.txt @@ -0,0 +1,9 @@ +There are three kinds of target files that may be built: archive, +library, and runtime. Executables are always treated as runtime +targets. Static libraries are always treated as archive targets. +Module libraries are always treated as library targets. For +non-DLL platforms shared libraries are treated as library +targets. 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. diff --git a/Help/prop_tgt/TYPE.rst b/Help/prop_tgt/TYPE.rst new file mode 100644 index 0000000000..1951d46bed --- /dev/null +++ b/Help/prop_tgt/TYPE.rst @@ -0,0 +1,8 @@ +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, 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 0000000000..87f6c49766 --- /dev/null +++ b/Help/prop_tgt/VERSION.rst @@ -0,0 +1,16 @@ +VERSION +------- + +What version number is this target. + +For shared libraries 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. For +executables VERSION can be used to specify the build version. When +building or installing appropriate symlinks are created if the +platform supports symlinks. 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. diff --git a/Help/prop_tgt/VISIBILITY_INLINES_HIDDEN.rst b/Help/prop_tgt/VISIBILITY_INLINES_HIDDEN.rst new file mode 100644 index 0000000000..e06d35c5fa --- /dev/null +++ b/Help/prop_tgt/VISIBILITY_INLINES_HIDDEN.rst @@ -0,0 +1,11 @@ +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 only has an affect +for libraries and executables with exports. This property is initialized by +the value of the :variable:`CMAKE_VISIBILITY_INLINES_HIDDEN` if it is set +when a target is created. diff --git a/Help/prop_tgt/VS_DOTNET_REFERENCES.rst b/Help/prop_tgt/VS_DOTNET_REFERENCES.rst new file mode 100644 index 0000000000..a661ad926a --- /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_TARGET_FRAMEWORK_VERSION.rst b/Help/prop_tgt/VS_DOTNET_TARGET_FRAMEWORK_VERSION.rst new file mode 100644 index 0000000000..829d696d57 --- /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 0000000000..ce49316d8b --- /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 0000000000..f4d9efc8eb --- /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 0000000000..a23c54005e --- /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 0000000000..56b8021bef --- /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_KEYWORD.rst b/Help/prop_tgt/VS_KEYWORD.rst new file mode 100644 index 0000000000..6c2e0420e3 --- /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_SCC_AUXPATH.rst b/Help/prop_tgt/VS_SCC_AUXPATH.rst new file mode 100644 index 0000000000..054f59e3ad --- /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 0000000000..b5b7721c5e --- /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 0000000000..6d7f628d92 --- /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 0000000000..80475af1f0 --- /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_WINRT_COMPONENT.rst b/Help/prop_tgt/VS_WINRT_COMPONENT.rst new file mode 100644 index 0000000000..e160bd64be --- /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 0000000000..d1cba3471f --- /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 0000000000..af98b2f7b7 --- /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 0000000000..336d5f7f38 --- /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/XCODE_ATTRIBUTE_an-attribute.rst b/Help/prop_tgt/XCODE_ATTRIBUTE_an-attribute.rst new file mode 100644 index 0000000000..0be313c866 --- /dev/null +++ b/Help/prop_tgt/XCODE_ATTRIBUTE_an-attribute.rst @@ -0,0 +1,7 @@ +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. diff --git a/Help/prop_tgt/XXX_OUTPUT_DIRECTORY.txt b/Help/prop_tgt/XXX_OUTPUT_DIRECTORY.txt new file mode 100644 index 0000000000..65abbceae5 --- /dev/null +++ b/Help/prop_tgt/XXX_OUTPUT_DIRECTORY.txt @@ -0,0 +1,10 @@ +Output directory in which to build |XXX| target files. + +This property specifies the directory into which |xxx| target files +should be built. Multi-configuration generators (VS, Xcode) append a +per-configuration subdirectory to the specified directory. + +.. include:: TARGET_FILE_TYPES.txt + +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 0000000000..9c4fc7c4ae --- /dev/null +++ b/Help/prop_tgt/XXX_OUTPUT_NAME.txt @@ -0,0 +1,6 @@ +Output name for |XXX| target files. + +This property specifies the base name for |xxx| target files. It +overrides OUTPUT_NAME and OUTPUT_NAME_<CONFIG> properties. + +.. include:: TARGET_FILE_TYPES.txt diff --git a/Help/release/3.0.0.rst b/Help/release/3.0.0.rst new file mode 100644 index 0000000000..e92c293289 --- /dev/null +++ b/Help/release/3.0.0.rst @@ -0,0 +1,473 @@ +CMake 3.0.0 Release Notes +************************* + +.. only:: html + + .. contents:: + +Changes made since CMake 2.8.12.2 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.0.rst b/Help/release/3.1.0.rst new file mode 100644 index 0000000000..652bcd3769 --- /dev/null +++ b/Help/release/3.1.0.rst @@ -0,0 +1,381 @@ +CMake 3.1.0 Release Notes +************************* + +.. only:: html + + .. contents:: + +Changes made since CMake 3.0.0 include the following. + +Documentation Changes +===================== + +* A new :manual:`cmake-compile-features(7)` manual was added. + +New Features +============ + +Generators +---------- + +* A :generator:`Visual Studio 14` 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:`install` command learned a ``MESSAGE_NEVER`` option + to avoid output during installation. + +* 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. + +* 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:`FindOpenGL` module now provides imported targets + ``OpenGL::GL`` and ``OpenGL::GLU`` when the libraries are found. + +* 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:`FindVTK` module dropped support for finding VTK 4.0. + It is now a thin-wrapper around ``find_package(VTK ... NO_MODULE)``. + This produces much clearer error messages when VTK is not found. + +* 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). A :prop_sf:`VS_SHADER_TYPE` source file + property was added to specify the Shader Type. + +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. + +* 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. + +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. diff --git a/Help/release/dev.txt b/Help/release/dev.txt new file mode 100644 index 0000000000..2cf9193e1c --- /dev/null +++ b/Help/release/dev.txt @@ -0,0 +1,16 @@ +.. + This file should be included by the adjacent "index.rst" + in development versions but not in release versions. + +Changes Since Release +===================== + +The following noteworthy changes have been made in this development +version since the preceding release but have not yet been consolidated +into notes for a specific release version: + +.. toctree:: + :maxdepth: 1 + :glob: + + dev/* diff --git a/Help/release/dev/0-sample-topic.rst b/Help/release/dev/0-sample-topic.rst new file mode 100644 index 0000000000..e4cc01e23f --- /dev/null +++ b/Help/release/dev/0-sample-topic.rst @@ -0,0 +1,7 @@ +0-sample-topic +-------------- + +* This is a sample release note for the change in a topic. + Developers should add similar notes for each topic branch + making a noteworthy change. Each document should be named + and titled to match the topic name to avoid merge conflicts. diff --git a/Help/release/index.rst b/Help/release/index.rst new file mode 100644 index 0000000000..abc19b8e8f --- /dev/null +++ b/Help/release/index.rst @@ -0,0 +1,17 @@ +CMake Release Notes +******************* + +.. + This file should include the adjacent "dev.txt" file + in development versions but not in release versions. + +.. include:: dev.txt + +Releases +======== + +.. toctree:: + :maxdepth: 1 + + 3.1.0 <3.1.0> + 3.0.0 <3.0.0> diff --git a/Help/variable/APPLE.rst b/Help/variable/APPLE.rst new file mode 100644 index 0000000000..3afdee867d --- /dev/null +++ b/Help/variable/APPLE.rst @@ -0,0 +1,6 @@ +APPLE +----- + +True if running on Mac OS X. + +Set to true on Mac OS X. diff --git a/Help/variable/BORLAND.rst b/Help/variable/BORLAND.rst new file mode 100644 index 0000000000..4af6085bf9 --- /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 0000000000..6f30efba14 --- /dev/null +++ b/Help/variable/BUILD_SHARED_LIBS.rst @@ -0,0 +1,10 @@ +BUILD_SHARED_LIBS +----------------- + +Global flag to cause 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 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 0000000000..36914536c2 --- /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_API.rst b/Help/variable/CMAKE_ANDROID_API.rst new file mode 100644 index 0000000000..c8264e0f8e --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_API.rst @@ -0,0 +1,5 @@ +CMAKE_ANDROID_API +----------------- + +Default value for the :prop_tgt:`ANDROID_API` 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 0000000000..175537527d --- /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_APPBUNDLE_PATH.rst b/Help/variable/CMAKE_APPBUNDLE_PATH.rst new file mode 100644 index 0000000000..469b3162ba --- /dev/null +++ b/Help/variable/CMAKE_APPBUNDLE_PATH.rst @@ -0,0 +1,5 @@ +CMAKE_APPBUNDLE_PATH +-------------------- + +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 0000000000..5893677ff8 --- /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 0000000000..6a22f73528 --- /dev/null +++ b/Help/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY.rst @@ -0,0 +1,8 @@ +CMAKE_ARCHIVE_OUTPUT_DIRECTORY +------------------------------ + +Where to put all the ARCHIVE targets when built. + +This variable is used to initialize the ARCHIVE_OUTPUT_DIRECTORY +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 0000000000..be120b8fed --- /dev/null +++ b/Help/variable/CMAKE_ARGC.rst @@ -0,0 +1,7 @@ +CMAKE_ARGC +---------- + +Number of command line arguments passed to CMake in script mode. + +When run in -P script mode, CMake sets this variable to the number of +command line arguments. See also CMAKE_ARGV0, 1, 2 ... diff --git a/Help/variable/CMAKE_ARGV0.rst b/Help/variable/CMAKE_ARGV0.rst new file mode 100644 index 0000000000..e5ed419637 --- /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 -P 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 CMAKE_ARGC. diff --git a/Help/variable/CMAKE_AUTOMOC.rst b/Help/variable/CMAKE_AUTOMOC.rst new file mode 100644 index 0000000000..02e5eb57aa --- /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_MOC_OPTIONS.rst b/Help/variable/CMAKE_AUTOMOC_MOC_OPTIONS.rst new file mode 100644 index 0000000000..09bf5cd2fc --- /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 0000000000..a814d408b3 --- /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 0000000000..067f766115 --- /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 0000000000..298cb6be70 --- /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 0000000000..0beb55590e --- /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 0000000000..3c9b8c4f5d --- /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_BACKWARDS_COMPATIBILITY.rst b/Help/variable/CMAKE_BACKWARDS_COMPATIBILITY.rst new file mode 100644 index 0000000000..05c366a950 --- /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 0000000000..703bb58c7f --- /dev/null +++ b/Help/variable/CMAKE_BINARY_DIR.rst @@ -0,0 +1,8 @@ +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 +CMAKE_SOURCE_DIR. diff --git a/Help/variable/CMAKE_BUILD_TOOL.rst b/Help/variable/CMAKE_BUILD_TOOL.rst new file mode 100644 index 0000000000..61334917bb --- /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 0000000000..68f08baba0 --- /dev/null +++ b/Help/variable/CMAKE_BUILD_TYPE.rst @@ -0,0 +1,19 @@ +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 make and 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 CMAKE_C_FLAGS_DEBUG settings get added to the CMAKE_C_FLAGS +settings. See also CMAKE_CONFIGURATION_TYPES. 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 0000000000..6875da6aa8 --- /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 0000000000..78c7d93d12 --- /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 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 0000000000..e6887d9ed1 --- /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 0000000000..799f0a98a0 --- /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 0000000000..e67d5444ec --- /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 0000000000..20435e590b --- /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 Visual Studio and Xcode), the value is a reference +to a build-time variable specifying the name of the per-configuration +output subdirectory. On Makefile generators this evaluates to "." +because there is only one configuration in a build tree. Example +values: + +:: + + $(IntDir) = Visual Studio 6 + $(OutDir) = Visual Studio 7, 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 +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 0000000000..5096829618 --- /dev/null +++ b/Help/variable/CMAKE_CL_64.rst @@ -0,0 +1,6 @@ +CMAKE_CL_64 +----------- + +Using the 64 bit compiler from Microsoft + +Set to true when using the 64 bit cl compiler from Microsoft. diff --git a/Help/variable/CMAKE_COLOR_MAKEFILE.rst b/Help/variable/CMAKE_COLOR_MAKEFILE.rst new file mode 100644 index 0000000000..170baf3b2e --- /dev/null +++ b/Help/variable/CMAKE_COLOR_MAKEFILE.rst @@ -0,0 +1,7 @@ +CMAKE_COLOR_MAKEFILE +-------------------- + +Enables color output when using the Makefile generator. + +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 0000000000..f4e5f1e441 --- /dev/null +++ b/Help/variable/CMAKE_COMMAND.rst @@ -0,0 +1,8 @@ +CMAKE_COMMAND +------------- + +The full path to the cmake executable. + +This is the full path to the CMake executable cmake 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 0000000000..134559b6cd --- /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_GNULANG.rst b/Help/variable/CMAKE_COMPILER_IS_GNULANG.rst new file mode 100644 index 0000000000..bc5652f008 --- /dev/null +++ b/Help/variable/CMAKE_COMPILER_IS_GNULANG.rst @@ -0,0 +1,15 @@ +CMAKE_COMPILER_IS_GNU<LANG> +--------------------------- + +True if the compiler is GNU. + +If the selected <LANG> compiler is the GNU compiler then this is TRUE, +if not it is FALSE. Unlike the other per-language variables, this +uses the GNU syntax for identifying languages instead of the CMake +syntax. Recognized values of the <LANG> suffix are: + +:: + + CC = C compiler + CXX = C++ compiler + G77 = Fortran compiler 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 0000000000..ea33c7d646 --- /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 0000000000..fdeb9abdd3 --- /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 0000000000..986b969ee3 --- /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 CMAKE_BUILD_TYPE for details of managing +configuration data, and CMAKE_CFG_INTDIR. diff --git a/Help/variable/CMAKE_CONFIG_POSTFIX.rst b/Help/variable/CMAKE_CONFIG_POSTFIX.rst new file mode 100644 index 0000000000..af38bed4b2 --- /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 <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 0000000000..cf9865b619 --- /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_CTEST_COMMAND.rst b/Help/variable/CMAKE_CTEST_COMMAND.rst new file mode 100644 index 0000000000..d5dd2c3bb8 --- /dev/null +++ b/Help/variable/CMAKE_CTEST_COMMAND.rst @@ -0,0 +1,8 @@ +CMAKE_CTEST_COMMAND +------------------- + +Full path to ctest command installed with cmake. + +This is the full path to the CTest executable ctest which is useful +from custom commands that want to use the cmake -E option for portable +system commands. diff --git a/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst b/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst new file mode 100644 index 0000000000..fb55a11c66 --- /dev/null +++ b/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst @@ -0,0 +1,10 @@ +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 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. diff --git a/Help/variable/CMAKE_CURRENT_LIST_DIR.rst b/Help/variable/CMAKE_CURRENT_LIST_DIR.rst new file mode 100644 index 0000000000..b8168211cc --- /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 (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 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 0000000000..910d7b4557 --- /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 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 0000000000..60e8e26ce6 --- /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 0000000000..db063a4b7d --- /dev/null +++ b/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst @@ -0,0 +1,7 @@ +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. diff --git a/Help/variable/CMAKE_CXX_COMPILE_FEATURES.rst b/Help/variable/CMAKE_CXX_COMPILE_FEATURES.rst new file mode 100644 index 0000000000..460c78ccc5 --- /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. diff --git a/Help/variable/CMAKE_CXX_EXTENSIONS.rst b/Help/variable/CMAKE_CXX_EXTENSIONS.rst new file mode 100644 index 0000000000..64483713e4 --- /dev/null +++ b/Help/variable/CMAKE_CXX_EXTENSIONS.rst @@ -0,0 +1,11 @@ +CMAKE_CXX_EXTENSIONS +-------------------- + +Default value for ``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. diff --git a/Help/variable/CMAKE_CXX_STANDARD.rst b/Help/variable/CMAKE_CXX_STANDARD.rst new file mode 100644 index 0000000000..963a42a409 --- /dev/null +++ b/Help/variable/CMAKE_CXX_STANDARD.rst @@ -0,0 +1,11 @@ +CMAKE_CXX_STANDARD +------------------ + +Default value for ``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. diff --git a/Help/variable/CMAKE_CXX_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_CXX_STANDARD_REQUIRED.rst new file mode 100644 index 0000000000..f7750fa0ec --- /dev/null +++ b/Help/variable/CMAKE_CXX_STANDARD_REQUIRED.rst @@ -0,0 +1,11 @@ +CMAKE_CXX_STANDARD_REQUIRED +--------------------------- + +Default value for ``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. diff --git a/Help/variable/CMAKE_C_COMPILE_FEATURES.rst b/Help/variable/CMAKE_C_COMPILE_FEATURES.rst new file mode 100644 index 0000000000..1106246878 --- /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. diff --git a/Help/variable/CMAKE_C_EXTENSIONS.rst b/Help/variable/CMAKE_C_EXTENSIONS.rst new file mode 100644 index 0000000000..5e935fcc39 --- /dev/null +++ b/Help/variable/CMAKE_C_EXTENSIONS.rst @@ -0,0 +1,11 @@ +CMAKE_C_EXTENSIONS +------------------ + +Default value for ``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. diff --git a/Help/variable/CMAKE_C_STANDARD.rst b/Help/variable/CMAKE_C_STANDARD.rst new file mode 100644 index 0000000000..3098ce5d4a --- /dev/null +++ b/Help/variable/CMAKE_C_STANDARD.rst @@ -0,0 +1,11 @@ +CMAKE_C_STANDARD +---------------- + +Default value for ``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. diff --git a/Help/variable/CMAKE_C_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_C_STANDARD_REQUIRED.rst new file mode 100644 index 0000000000..c24eea4304 --- /dev/null +++ b/Help/variable/CMAKE_C_STANDARD_REQUIRED.rst @@ -0,0 +1,11 @@ +CMAKE_C_STANDARD_REQUIRED +------------------------- + +Default value for ``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. diff --git a/Help/variable/CMAKE_DEBUG_POSTFIX.rst b/Help/variable/CMAKE_DEBUG_POSTFIX.rst new file mode 100644 index 0000000000..fde24b2b5a --- /dev/null +++ b/Help/variable/CMAKE_DEBUG_POSTFIX.rst @@ -0,0 +1,7 @@ +CMAKE_DEBUG_POSTFIX +------------------- + +See variable CMAKE_<CONFIG>_POSTFIX. + +This variable is a special case of the more-general +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 0000000000..e200b8680f --- /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_DISABLE_FIND_PACKAGE_PackageName.rst b/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst new file mode 100644 index 0000000000..bcb277c999 --- /dev/null +++ b/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst @@ -0,0 +1,15 @@ +CMAKE_DISABLE_FIND_PACKAGE_<PackageName> +---------------------------------------- + +Variable for disabling find_package() calls. + +Every non-REQUIRED 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 cmake -U diff --git a/Help/variable/CMAKE_DL_LIBS.rst b/Help/variable/CMAKE_DL_LIBS.rst new file mode 100644 index 0000000000..cae4565b8d --- /dev/null +++ b/Help/variable/CMAKE_DL_LIBS.rst @@ -0,0 +1,7 @@ +CMAKE_DL_LIBS +------------- + +Name of library containing dlopen and dlcose. + +The name of the library that has dlopen and dlclose in it, usually +-ldl on most UNIX machines. diff --git a/Help/variable/CMAKE_EDIT_COMMAND.rst b/Help/variable/CMAKE_EDIT_COMMAND.rst new file mode 100644 index 0000000000..562aa0bc62 --- /dev/null +++ b/Help/variable/CMAKE_EDIT_COMMAND.rst @@ -0,0 +1,8 @@ +CMAKE_EDIT_COMMAND +------------------ + +Full path to cmake-gui or ccmake. Defined only for 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, cmake-gui or ccmake. diff --git a/Help/variable/CMAKE_ERROR_DEPRECATED.rst b/Help/variable/CMAKE_ERROR_DEPRECATED.rst new file mode 100644 index 0000000000..43ab282a3d --- /dev/null +++ b/Help/variable/CMAKE_ERROR_DEPRECATED.rst @@ -0,0 +1,8 @@ +CMAKE_ERROR_DEPRECATED +---------------------- + +Whether to issue deprecation errors for macros and functions. + +If TRUE, this can be used by macros and functions to issue fatal +errors when deprecated macros or functions are used. This variable is +FALSE by default. 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 0000000000..651d68d1f8 --- /dev/null +++ b/Help/variable/CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION.rst @@ -0,0 +1,9 @@ +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 0000000000..45c313c047 --- /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 0000000000..9e108f83f0 --- /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 0000000000..dcaf300626 --- /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_EXPORT_NO_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_EXPORT_NO_PACKAGE_REGISTRY.rst new file mode 100644 index 0000000000..ee109ba1a8 --- /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 0000000000..71aec92c56 --- /dev/null +++ b/Help/variable/CMAKE_EXTRA_GENERATOR.rst @@ -0,0 +1,9 @@ +CMAKE_EXTRA_GENERATOR +--------------------- + +The extra generator used to build the project. + +When using the Eclipse, CodeBlocks or KDevelop generators, CMake +generates Makefiles (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 0000000000..6187a7ac84 --- /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 +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_LIBRARY_PREFIXES.rst b/Help/variable/CMAKE_FIND_LIBRARY_PREFIXES.rst new file mode 100644 index 0000000000..1a9e7ce914 --- /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 +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 0000000000..c533909f43 --- /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 +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 0000000000..70d920bcea --- /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 :variable:`CMAKE_FIND_NO_INSTALL_PREFIX` to TRUE to tell 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_NO_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY.rst new file mode 100644 index 0000000000..90584710ed --- /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 0000000000..44588b17ab --- /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_WARN_NO_MODULE.rst b/Help/variable/CMAKE_FIND_PACKAGE_WARN_NO_MODULE.rst new file mode 100644 index 0000000000..5d7599c0cd --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_WARN_NO_MODULE.rst @@ -0,0 +1,19 @@ +CMAKE_FIND_PACKAGE_WARN_NO_MODULE +--------------------------------- + +Tell find_package to warn if called without an explicit mode. + +If find_package is called without an explicit mode option (MODULE, +CONFIG or NO_MODULE) and no Find<pkg>.cmake module is in +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 find_package to +warn when it implicitly assumes Config mode. This helps developers +enforce use of an explicit mode in all calls to 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 0000000000..67948f7cee --- /dev/null +++ b/Help/variable/CMAKE_FIND_ROOT_PATH.rst @@ -0,0 +1,8 @@ +CMAKE_FIND_ROOT_PATH +-------------------- + +List 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 0000000000..df1af5a88e --- /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 0000000000..52ab89dc52 --- /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 0000000000..387294797d --- /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 0000000000..d24a78a3fc --- /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 0000000000..ab65e090e7 --- /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 0000000000..f1bc75e908 --- /dev/null +++ b/Help/variable/CMAKE_FRAMEWORK_PATH.rst @@ -0,0 +1,6 @@ +CMAKE_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. diff --git a/Help/variable/CMAKE_Fortran_FORMAT.rst b/Help/variable/CMAKE_Fortran_FORMAT.rst new file mode 100644 index 0000000000..c0e971ce96 --- /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 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 0000000000..a8dfcdf343 --- /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 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 0000000000..4b32df328c --- /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 +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 0000000000..a232213a15 --- /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 0000000000..b1d49d8767 --- /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 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 0000000000..a4e70a590d --- /dev/null +++ b/Help/variable/CMAKE_GENERATOR.rst @@ -0,0 +1,7 @@ +CMAKE_GENERATOR +--------------- + +The generator used to build the project. + +The name of the generator that is being used to generate the build +files. (e.g. "Unix Makefiles", "Visual Studio 6", etc.) diff --git a/Help/variable/CMAKE_GENERATOR_PLATFORM.rst b/Help/variable/CMAKE_GENERATOR_PLATFORM.rst new file mode 100644 index 0000000000..5809b6af8d --- /dev/null +++ b/Help/variable/CMAKE_GENERATOR_PLATFORM.rst @@ -0,0 +1,15 @@ +CMAKE_GENERATOR_PLATFORM +------------------------ + +Generator-specific target platform name specified 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 toolset name (e.g. via the cmake -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. diff --git a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst new file mode 100644 index 0000000000..9ccc8b312e --- /dev/null +++ b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst @@ -0,0 +1,15 @@ +CMAKE_GENERATOR_TOOLSET +----------------------- + +Native build system toolset name specified by user. + +Some CMake generators support a toolset name to be given to the native +build system to choose a compiler. If the user specifies a toolset +name (e.g. via the cmake -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. diff --git a/Help/variable/CMAKE_GNUtoMS.rst b/Help/variable/CMAKE_GNUtoMS.rst new file mode 100644 index 0000000000..e253f59d19 --- /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 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 0000000000..fdc5d81901 --- /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 0000000000..d4b848344d --- /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_SYSTEM.rst b/Help/variable/CMAKE_HOST_SYSTEM.rst new file mode 100644 index 0000000000..c2a8f1a5f3 --- /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 0000000000..a221de9c06 --- /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 Mac 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 0000000000..790565a845 --- /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 0000000000..e7e00529a5 --- /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 0000000000..bbefba7d9a --- /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 0000000000..92ee45658f --- /dev/null +++ b/Help/variable/CMAKE_HOST_WIN32.rst @@ -0,0 +1,6 @@ +CMAKE_HOST_WIN32 +---------------- + +True on windows systems, including win64. + +Set to true when the host system is Windows and on Cygwin. diff --git a/Help/variable/CMAKE_IGNORE_PATH.rst b/Help/variable/CMAKE_IGNORE_PATH.rst new file mode 100644 index 0000000000..a818f74c69 --- /dev/null +++ b/Help/variable/CMAKE_IGNORE_PATH.rst @@ -0,0 +1,17 @@ +CMAKE_IGNORE_PATH +----------------- + +Path to be ignored by FIND_XXX() commands. + +Specifies directories to be ignored by searches in FIND_XXX() +commands. This is useful in cross-compiled 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 that modules like FindX11 (and others) would +normally search. 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. If you want to ignore paths under +prefixes (bin, include, lib, etc.), you'll need to specify them +explicitly. See also CMAKE_PREFIX_PATH, CMAKE_LIBRARY_PATH, +CMAKE_INCLUDE_PATH, CMAKE_PROGRAM_PATH. diff --git a/Help/variable/CMAKE_IMPORT_LIBRARY_PREFIX.rst b/Help/variable/CMAKE_IMPORT_LIBRARY_PREFIX.rst new file mode 100644 index 0000000000..1d16a3764f --- /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 0000000000..c16825eb99 --- /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 0000000000..79f3952fc1 --- /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 in each +directory ${CMAKE_CURRENT_SOURCE_DIR} and ${CMAKE_CURRENT_BINARY_DIR} +to the include path for this 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 0000000000..948db50d5d --- /dev/null +++ b/Help/variable/CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE.rst @@ -0,0 +1,10 @@ +CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE +-------------------------------------- + +Automatically add the current source- and build directories to the INTERFACE_INCLUDE_DIRECTORIES. + +If this variable is enabled, CMake automatically adds for each shared +library target, static library target, module target and executable +target, ${CMAKE_CURRENT_SOURCE_DIR} and ${CMAKE_CURRENT_BINARY_DIR} to +the INTERFACE_INCLUDE_DIRECTORIES.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 0000000000..3c1fbcfb4d --- /dev/null +++ b/Help/variable/CMAKE_INCLUDE_DIRECTORIES_BEFORE.rst @@ -0,0 +1,8 @@ +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 0000000000..cbd04d7d2a --- /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 0000000000..360b403fee --- /dev/null +++ b/Help/variable/CMAKE_INCLUDE_PATH.rst @@ -0,0 +1,10 @@ +CMAKE_INCLUDE_PATH +------------------ + +Path used for searching by FIND_FILE() and FIND_PATH(). + +Specifies a path which will be used both by FIND_FILE() and +FIND_PATH(). Both commands will check each of the contained +directories for the existence of the file which is currently searched. +By default it is empty, it is intended to be set by the project. See +also CMAKE_SYSTEM_INCLUDE_PATH, 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 0000000000..2ad0689aa8 --- /dev/null +++ b/Help/variable/CMAKE_INSTALL_DEFAULT_COMPONENT_NAME.rst @@ -0,0 +1,9 @@ +CMAKE_INSTALL_DEFAULT_COMPONENT_NAME +------------------------------------ + +Default component used in install() commands. + +If an 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 0000000000..304df268c7 --- /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 0000000000..540df6b731 --- /dev/null +++ b/Help/variable/CMAKE_INSTALL_NAME_DIR.rst @@ -0,0 +1,8 @@ +CMAKE_INSTALL_NAME_DIR +---------------------- + +Mac OS X directory name for installed targets. + +CMAKE_INSTALL_NAME_DIR is used to initialize the 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 0000000000..72c8d4167b --- /dev/null +++ b/Help/variable/CMAKE_INSTALL_PREFIX.rst @@ -0,0 +1,29 @@ +CMAKE_INSTALL_PREFIX +-------------------- + +Install directory used by 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 on Windows. + +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 CMAKE_SYSTEM_PREFIX_PATH so +that find_package, find_program, find_library, find_path, and +find_file will search the prefix for other software. diff --git a/Help/variable/CMAKE_INSTALL_RPATH.rst b/Help/variable/CMAKE_INSTALL_RPATH.rst new file mode 100644 index 0000000000..0992d57ebd --- /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 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 0000000000..9277a3ba40 --- /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 INSTALL_RPATH. This is used to initialize the target +property 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 0000000000..9693bf658a --- /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_JOB_POOL_COMPILE.rst b/Help/variable/CMAKE_JOB_POOL_COMPILE.rst new file mode 100644 index 0000000000..e5c2d9a819 --- /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 0000000000..338f7714e2 --- /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_ARCHIVE_APPEND.rst b/Help/variable/CMAKE_LANG_ARCHIVE_APPEND.rst new file mode 100644 index 0000000000..2c3abaebaa --- /dev/null +++ b/Help/variable/CMAKE_LANG_ARCHIVE_APPEND.rst @@ -0,0 +1,9 @@ +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 CMAKE_<LANG>_CREATE_STATIC_LIBRARY on +some platforms in order to support large object counts. See also +CMAKE_<LANG>_ARCHIVE_CREATE and 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 0000000000..f93dd1119f --- /dev/null +++ b/Help/variable/CMAKE_LANG_ARCHIVE_CREATE.rst @@ -0,0 +1,9 @@ +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 CMAKE_<LANG>_CREATE_STATIC_LIBRARY on +some platforms in order to support large object counts. See also +CMAKE_<LANG>_ARCHIVE_APPEND and 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 0000000000..fff4128a46 --- /dev/null +++ b/Help/variable/CMAKE_LANG_ARCHIVE_FINISH.rst @@ -0,0 +1,9 @@ +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 CMAKE_<LANG>_CREATE_STATIC_LIBRARY on +some platforms in order to support large object counts. See also +CMAKE_<LANG>_ARCHIVE_CREATE and CMAKE_<LANG>_ARCHIVE_APPEND. diff --git a/Help/variable/CMAKE_LANG_COMPILER.rst b/Help/variable/CMAKE_LANG_COMPILER.rst new file mode 100644 index 0000000000..fffc347bd0 --- /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 0000000000..be946c01b2 --- /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_EXTERNAL_TOOLCHAIN.rst b/Help/variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN.rst new file mode 100644 index 0000000000..033998d0c3 --- /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 auxilliary 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 0000000000..f554f4ec49 --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_ID.rst @@ -0,0 +1,33 @@ +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) + 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) + 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_LOADED.rst b/Help/variable/CMAKE_LANG_COMPILER_LOADED.rst new file mode 100644 index 0000000000..3b8e9aac62 --- /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 project() or enable_language() this +variable is defined to 1. diff --git a/Help/variable/CMAKE_LANG_COMPILER_TARGET.rst b/Help/variable/CMAKE_LANG_COMPILER_TARGET.rst new file mode 100644 index 0000000000..656c57d2b2 --- /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 0000000000..50e77eba0f --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_VERSION.rst @@ -0,0 +1,8 @@ +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. diff --git a/Help/variable/CMAKE_LANG_COMPILE_OBJECT.rst b/Help/variable/CMAKE_LANG_COMPILE_OBJECT.rst new file mode 100644 index 0000000000..f43ed6df8a --- /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_CREATE_SHARED_LIBRARY.rst b/Help/variable/CMAKE_LANG_CREATE_SHARED_LIBRARY.rst new file mode 100644 index 0000000000..adf1624e53 --- /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 0000000000..406b4daba0 --- /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 0000000000..8114432933 --- /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 0000000000..6aa0a3e186 --- /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 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 0000000000..a727641874 --- /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 CMAKE_BUILD_TYPE is Debug. diff --git a/Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL.rst b/Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL.rst new file mode 100644 index 0000000000..fbb851697a --- /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 CMAKE_BUILD_TYPE is MinSizeRel.Short for +minimum size release. diff --git a/Help/variable/CMAKE_LANG_FLAGS_RELEASE.rst b/Help/variable/CMAKE_LANG_FLAGS_RELEASE.rst new file mode 100644 index 0000000000..4b2c926d5f --- /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 CMAKE_BUILD_TYPE is Release diff --git a/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO.rst b/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO.rst new file mode 100644 index 0000000000..16bd4e9014 --- /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 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 0000000000..3d07e912be --- /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 0000000000..c60e18c04f --- /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 0000000000..568950c0f0 --- /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 +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 0000000000..05e6ddbd04 --- /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 0000000000..fddfed8bc1 --- /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_LIBRARY_ARCHITECTURE.rst b/Help/variable/CMAKE_LANG_LIBRARY_ARCHITECTURE.rst new file mode 100644 index 0000000000..4f3149464e --- /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 0000000000..af7ee60f71 --- /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 +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 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 0000000000..d513767f77 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINKER_PREFERENCE_PROPAGATES.rst @@ -0,0 +1,9 @@ +CMAKE_<LANG>_LINKER_PREFERENCE_PROPAGATES +----------------------------------------- + +True if 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 0000000000..abd5891479 --- /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 0000000000..22fac2900a --- /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 0000000000..1b243e39a3 --- /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 0000000000..646c0db7e7 --- /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 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 0000000000..982053df2d --- /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 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 0000000000..c85b5e078e --- /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 0000000000..e085fee675 --- /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_VISIBILITY_PRESET.rst b/Help/variable/CMAKE_LANG_VISIBILITY_PRESET.rst new file mode 100644 index 0000000000..bef670fd1d --- /dev/null +++ b/Help/variable/CMAKE_LANG_VISIBILITY_PRESET.rst @@ -0,0 +1,8 @@ +CMAKE_<LANG>_VISIBILITY_PRESET +------------------------------ + +Default value for <LANG>_VISIBILITY_PRESET of targets. + +This variable is used to initialize the <LANG>_VISIBILITY_PRESET +property on all the targets. See that target property for additional +information. diff --git a/Help/variable/CMAKE_LIBRARY_ARCHITECTURE.rst b/Help/variable/CMAKE_LIBRARY_ARCHITECTURE.rst new file mode 100644 index 0000000000..c9a15f3155 --- /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 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 0000000000..6c41269033 --- /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 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 0000000000..3bdd3484a5 --- /dev/null +++ b/Help/variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY.rst @@ -0,0 +1,8 @@ +CMAKE_LIBRARY_OUTPUT_DIRECTORY +------------------------------ + +Where to put all the LIBRARY targets when built. + +This variable is used to initialize the LIBRARY_OUTPUT_DIRECTORY +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 0000000000..e77dd348c1 --- /dev/null +++ b/Help/variable/CMAKE_LIBRARY_PATH.rst @@ -0,0 +1,10 @@ +CMAKE_LIBRARY_PATH +------------------ + +Path used for searching by FIND_LIBRARY(). + +Specifies a path which will be used by FIND_LIBRARY(). FIND_LIBRARY() +will check each of the contained directories for the existence of the +library which is currently searched. By default it is empty, it is +intended to be set by the project. See also +CMAKE_SYSTEM_LIBRARY_PATH, 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 0000000000..ede39e9d64 --- /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 0000000000..382447c983 --- /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 0000000000..6ae7df68d0 --- /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 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 0000000000..efe6fd74c6 --- /dev/null +++ b/Help/variable/CMAKE_LINK_INTERFACE_LIBRARIES.rst @@ -0,0 +1,8 @@ +CMAKE_LINK_INTERFACE_LIBRARIES +------------------------------ + +Default value for LINK_INTERFACE_LIBRARIES of targets. + +This variable is used to initialize the 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 0000000000..6858e2c15d --- /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 0000000000..c3e02d7366 --- /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 0000000000..390298d85a --- /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_MACOSX_BUNDLE.rst b/Help/variable/CMAKE_MACOSX_BUNDLE.rst new file mode 100644 index 0000000000..e4768f3694 --- /dev/null +++ b/Help/variable/CMAKE_MACOSX_BUNDLE.rst @@ -0,0 +1,7 @@ +CMAKE_MACOSX_BUNDLE +------------------- + +Default value for MACOSX_BUNDLE of targets. + +This variable is used to initialize the 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 0000000000..ac897c0f72 --- /dev/null +++ b/Help/variable/CMAKE_MACOSX_RPATH.rst @@ -0,0 +1,7 @@ +CMAKE_MACOSX_RPATH +------------------- + +Whether to use rpaths on Mac OS X. + +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 0000000000..079ad70680 --- /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 0000000000..97caa8a647 --- /dev/null +++ b/Help/variable/CMAKE_MAKE_PROGRAM.rst @@ -0,0 +1,55 @@ +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 Makefile generators set this to ``make``, ``gmake``, or + a generator-specific tool (e.g. ``nmake`` for "NMake Makefiles"). + + These generators store ``CMAKE_MAKE_PROGRAM`` in the CMake cache + so that it may be edited by the user. + +* The 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 Xcode generator sets this to ``xcodebuild`` (or possibly an + otherwise undocumented ``cmakexbuild`` wrapper implementing some + workarounds). + + This generator stores ``CMAKE_MAKE_PROGRAM`` in the CMake cache + so that it may be edited by the user. + +* The Visual Studio generators set this to the full path to + ``MSBuild.exe`` (VS >= 10), ``devenv.com`` (VS 7,8,9), + ``VCExpress.exe`` (VS Express 8,9), or ``msdev.exe`` (VS 6). + (See also variables + :variable:`CMAKE_VS_MSBUILD_COMMAND`, + :variable:`CMAKE_VS_DEVENV_COMMAND`, and + :variable:`CMAKE_VS_MSDEV_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 ``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 0000000000..41ccde1c58 --- /dev/null +++ b/Help/variable/CMAKE_MAP_IMPORTED_CONFIG_CONFIG.rst @@ -0,0 +1,8 @@ +CMAKE_MAP_IMPORTED_CONFIG_<CONFIG> +---------------------------------- + +Default value for MAP_IMPORTED_CONFIG_<CONFIG> of targets. + +This variable is used to initialize the MAP_IMPORTED_CONFIG_<CONFIG> +property on all the targets. See that target property for additional +information. diff --git a/Help/variable/CMAKE_MFC_FLAG.rst b/Help/variable/CMAKE_MFC_FLAG.rst new file mode 100644 index 0000000000..221d26e4fa --- /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 6 and 7 +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 0000000000..351de442c7 --- /dev/null +++ b/Help/variable/CMAKE_MINIMUM_REQUIRED_VERSION.rst @@ -0,0 +1,7 @@ +CMAKE_MINIMUM_REQUIRED_VERSION +------------------------------ + +Version specified to cmake_minimum_required command + +Variable containing the VERSION component specified in the +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 0000000000..f67cfb9557 --- /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 0000000000..6372bbdb99 --- /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 0000000000..87a19011f0 --- /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_PATH.rst b/Help/variable/CMAKE_MODULE_PATH.rst new file mode 100644 index 0000000000..a2dde4537b --- /dev/null +++ b/Help/variable/CMAKE_MODULE_PATH.rst @@ -0,0 +1,8 @@ +CMAKE_MODULE_PATH +----------------- + +List of directories to search for CMake modules. + +Commands like include() and find_package() search for files in +directories listed by this variable before checking the default +modules that come with CMake. 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 0000000000..cbe035022a --- /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 0000000000..189f59fa3b --- /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 0000000000..c1919afd2e --- /dev/null +++ b/Help/variable/CMAKE_NO_SYSTEM_FROM_IMPORTED.rst @@ -0,0 +1,8 @@ +CMAKE_NO_SYSTEM_FROM_IMPORTED +----------------------------- + +Default value for NO_SYSTEM_FROM_IMPORTED of targets. + +This variable is used to initialize the 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 0000000000..9e30cbbdb4 --- /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 0000000000..b9de518627 --- /dev/null +++ b/Help/variable/CMAKE_OSX_ARCHITECTURES.rst @@ -0,0 +1,10 @@ +CMAKE_OSX_ARCHITECTURES +----------------------- + +Target specific architectures for OS X. + +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 0000000000..4fb2caa4f2 --- /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 0000000000..f1d58c6b52 --- /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 0000000000..385f871f3e --- /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 0000000000..5566a7222a --- /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 include() or 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 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 0000000000..991ae76187 --- /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 0000000000..763bcb34f0 --- /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 0000000000..4d18eec5dc --- /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 0000000000..e401aa5000 --- /dev/null +++ b/Help/variable/CMAKE_POLICY_DEFAULT_CMPNNNN.rst @@ -0,0 +1,16 @@ +CMAKE_POLICY_DEFAULT_CMP<NNNN> +------------------------------ + +Default for CMake Policy CMP<NNNN> when it is otherwise left unset. + +Commands cmake_minimum_required(VERSION) and 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 +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 0000000000..b563aeaec0 --- /dev/null +++ b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst @@ -0,0 +1,17 @@ +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`. + +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`` +or ``--trace`` 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 0000000000..5e71665670 --- /dev/null +++ b/Help/variable/CMAKE_POSITION_INDEPENDENT_CODE.rst @@ -0,0 +1,8 @@ +CMAKE_POSITION_INDEPENDENT_CODE +------------------------------- + +Default value for POSITION_INDEPENDENT_CODE of targets. + +This variable is used to initialize the POSITION_INDEPENDENT_CODE +property on all the targets. See that target property for additional +information. diff --git a/Help/variable/CMAKE_PREFIX_PATH.rst b/Help/variable/CMAKE_PREFIX_PATH.rst new file mode 100644 index 0000000000..4c21d5e11d --- /dev/null +++ b/Help/variable/CMAKE_PREFIX_PATH.rst @@ -0,0 +1,13 @@ +CMAKE_PREFIX_PATH +----------------- + +Path used for searching by FIND_XXX(), with appropriate suffixes added. + +Specifies a path which will be used by the FIND_XXX() commands. It +contains the "base" directories, the FIND_XXX() commands append +appropriate subdirectories to the base directories. So FIND_PROGRAM() +adds /bin to each of the directories in the path, FIND_LIBRARY() +appends /lib to each of the directories, and FIND_PATH() and +FIND_FILE() append /include . By default it is empty, it is intended +to be set by the project. See also CMAKE_SYSTEM_PREFIX_PATH, +CMAKE_INCLUDE_PATH, CMAKE_LIBRARY_PATH, CMAKE_PROGRAM_PATH. diff --git a/Help/variable/CMAKE_PROGRAM_PATH.rst b/Help/variable/CMAKE_PROGRAM_PATH.rst new file mode 100644 index 0000000000..02c5e028d8 --- /dev/null +++ b/Help/variable/CMAKE_PROGRAM_PATH.rst @@ -0,0 +1,10 @@ +CMAKE_PROGRAM_PATH +------------------ + +Path used for searching by FIND_PROGRAM(). + +Specifies a path which will be used by FIND_PROGRAM(). FIND_PROGRAM() +will check each of the contained directories for the existence of the +program which is currently searched. By default it is empty, it is +intended to be set by the project. See also +CMAKE_SYSTEM_PROGRAM_PATH, CMAKE_PREFIX_PATH. diff --git a/Help/variable/CMAKE_PROJECT_NAME.rst b/Help/variable/CMAKE_PROJECT_NAME.rst new file mode 100644 index 0000000000..47347051ad --- /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 +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 0000000000..ba9df5a342 --- /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 0000000000..82672e9ae6 --- /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 0000000000..f963a7f835 --- /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 0000000000..366ca6679b --- /dev/null +++ b/Help/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY.rst @@ -0,0 +1,8 @@ +CMAKE_RUNTIME_OUTPUT_DIRECTORY +------------------------------ + +Where to put all the RUNTIME targets when built. + +This variable is used to initialize the RUNTIME_OUTPUT_DIRECTORY +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 0000000000..ad73cc0275 --- /dev/null +++ b/Help/variable/CMAKE_SCRIPT_MODE_FILE.rst @@ -0,0 +1,8 @@ +CMAKE_SCRIPT_MODE_FILE +---------------------- + +Full path to the -P script file currently being processed. + +When run in -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 0000000000..a863e2a6ce --- /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 0000000000..c296ecd816 --- /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 0000000000..fce950c75d --- /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 0000000000..fedc6264a3 --- /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_MODULE_PREFIX.rst b/Help/variable/CMAKE_SHARED_MODULE_PREFIX.rst new file mode 100644 index 0000000000..a5a2428b1b --- /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 0000000000..32a3c3460a --- /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 0000000000..2697fad6a5 --- /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 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 0000000000..8da6100300 --- /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 0000000000..33ee8a892f --- /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 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 0000000000..f16b2120f4 --- /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 +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 0000000000..5eda254425 --- /dev/null +++ b/Help/variable/CMAKE_SKIP_INSTALL_RULES.rst @@ -0,0 +1,7 @@ +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 0000000000..c93f67f53a --- /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 +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 0000000000..088fa8361c --- /dev/null +++ b/Help/variable/CMAKE_SOURCE_DIR.rst @@ -0,0 +1,8 @@ +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 +CMAKE_BINARY_DIR. diff --git a/Help/variable/CMAKE_STAGING_PREFIX.rst b/Help/variable/CMAKE_STAGING_PREFIX.rst new file mode 100644 index 0000000000..c4de7da859 --- /dev/null +++ b/Help/variable/CMAKE_STAGING_PREFIX.rst @@ -0,0 +1,13 @@ +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_STANDARD_LIBRARIES.rst b/Help/variable/CMAKE_STANDARD_LIBRARIES.rst new file mode 100644 index 0000000000..9c728cdbc1 --- /dev/null +++ b/Help/variable/CMAKE_STANDARD_LIBRARIES.rst @@ -0,0 +1,7 @@ +CMAKE_STANDARD_LIBRARIES +------------------------ + +Libraries linked into every executable and shared library. + +This is the list of libraries that are linked into all executables and +libraries. diff --git a/Help/variable/CMAKE_STATIC_LIBRARY_PREFIX.rst b/Help/variable/CMAKE_STATIC_LIBRARY_PREFIX.rst new file mode 100644 index 0000000000..0a3095d0b2 --- /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 0000000000..4d07671e1d --- /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 0000000000..9c38673aa4 --- /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 0000000000..6cde24ddda --- /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_SYSROOT.rst b/Help/variable/CMAKE_SYSROOT.rst new file mode 100644 index 0000000000..7aa04506cd --- /dev/null +++ b/Help/variable/CMAKE_SYSROOT.rst @@ -0,0 +1,12 @@ +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. diff --git a/Help/variable/CMAKE_SYSTEM.rst b/Help/variable/CMAKE_SYSTEM.rst new file mode 100644 index 0000000000..23f5980874 --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM.rst @@ -0,0 +1,10 @@ +CMAKE_SYSTEM +------------ + +Composit Name of OS 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_IGNORE_PATH.rst b/Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst new file mode 100644 index 0000000000..9e6b19564c --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst @@ -0,0 +1,15 @@ +CMAKE_SYSTEM_IGNORE_PATH +------------------------ + +Path to be ignored by FIND_XXX() commands. + +Specifies directories to be ignored by searches in FIND_XXX() +commands. This is useful in cross-compiled 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 that modules like FindX11 (and others) would +normally search. By default this contains a list of directories +containing incompatible binaries for the host system. See also +CMAKE_SYSTEM_PREFIX_PATH, CMAKE_SYSTEM_LIBRARY_PATH, +CMAKE_SYSTEM_INCLUDE_PATH, and CMAKE_SYSTEM_PROGRAM_PATH. diff --git a/Help/variable/CMAKE_SYSTEM_INCLUDE_PATH.rst b/Help/variable/CMAKE_SYSTEM_INCLUDE_PATH.rst new file mode 100644 index 0000000000..1734185ffe --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_INCLUDE_PATH.rst @@ -0,0 +1,11 @@ +CMAKE_SYSTEM_INCLUDE_PATH +------------------------- + +Path used for searching by FIND_FILE() and FIND_PATH(). + +Specifies a path which will be used both by FIND_FILE() and +FIND_PATH(). Both commands will check each of the contained +directories for the existence of the file which is currently searched. +By default it contains the standard directories for the current +system. It is NOT intended to be modified by the project, use +CMAKE_INCLUDE_PATH for this. See also 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 0000000000..4778646cc7 --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_LIBRARY_PATH.rst @@ -0,0 +1,11 @@ +CMAKE_SYSTEM_LIBRARY_PATH +------------------------- + +Path used for searching by FIND_LIBRARY(). + +Specifies a path which will be used by FIND_LIBRARY(). FIND_LIBRARY() +will check each of the contained directories for the existence of the +library which is currently searched. By default it contains the +standard directories for the current system. It is NOT intended to be +modified by the project, use CMAKE_LIBRARY_PATH for this. See also +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 0000000000..189dc18fcd --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_NAME.rst @@ -0,0 +1,8 @@ +CMAKE_SYSTEM_NAME +----------------- + +Name of the OS CMake is building for. + +This is the name of the OS on which CMake is targeting. This variable +is the same as :variable:`CMAKE_HOST_SYSTEM_NAME` if you build for the +host system instead of the target system when cross compiling. diff --git a/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst b/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst new file mode 100644 index 0000000000..537eaba304 --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst @@ -0,0 +1,16 @@ +CMAKE_SYSTEM_PREFIX_PATH +------------------------ + +Path used for searching by FIND_XXX(), with appropriate suffixes added. + +Specifies a path which will be used by the FIND_XXX() commands. It +contains the "base" directories, the FIND_XXX() commands append +appropriate subdirectories to the base directories. So FIND_PROGRAM() +adds /bin to each of the directories in the path, FIND_LIBRARY() +appends /lib to each of the directories, and FIND_PATH() and +FIND_FILE() append /include . By default this contains the standard +directories for the current system, the CMAKE_INSTALL_PREFIX and +the :variable:`CMAKE_STAGING_PREFIX`. It is NOT intended to be modified by +the project, use CMAKE_PREFIX_PATH for this. See also CMAKE_SYSTEM_INCLUDE_PATH, +CMAKE_SYSTEM_LIBRARY_PATH, CMAKE_SYSTEM_PROGRAM_PATH, and +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 0000000000..8ad89f128c --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_PROCESSOR.rst @@ -0,0 +1,8 @@ +CMAKE_SYSTEM_PROCESSOR +---------------------- + +The name of the CPU CMake is building for. + +This variable is the same as :variable:`CMAKE_HOST_SYSTEM_PROCESSOR` if +you build for the host system instead of the target system when +cross compiling. diff --git a/Help/variable/CMAKE_SYSTEM_PROGRAM_PATH.rst b/Help/variable/CMAKE_SYSTEM_PROGRAM_PATH.rst new file mode 100644 index 0000000000..e1fad632a9 --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_PROGRAM_PATH.rst @@ -0,0 +1,11 @@ +CMAKE_SYSTEM_PROGRAM_PATH +------------------------- + +Path used for searching by FIND_PROGRAM(). + +Specifies a path which will be used by FIND_PROGRAM(). FIND_PROGRAM() +will check each of the contained directories for the existence of the +program which is currently searched. By default it contains the +standard directories for the current system. It is NOT intended to be +modified by the project, use CMAKE_PROGRAM_PATH for this. See also +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 0000000000..33510bbf99 --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_VERSION.rst @@ -0,0 +1,8 @@ +CMAKE_SYSTEM_VERSION +-------------------- + +The OS version CMake is building for. + +This variable is the same as :variable:`CMAKE_HOST_SYSTEM_VERSION` if +you build for the host system instead of the target system when +cross compiling. diff --git a/Help/variable/CMAKE_TOOLCHAIN_FILE.rst b/Help/variable/CMAKE_TOOLCHAIN_FILE.rst new file mode 100644 index 0000000000..e1a65e12b7 --- /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 0000000000..a92feab5eb --- /dev/null +++ b/Help/variable/CMAKE_TRY_COMPILE_CONFIGURATION.rst @@ -0,0 +1,9 @@ +CMAKE_TRY_COMPILE_CONFIGURATION +------------------------------- + +Build configuration used for try_compile and try_run projects. + +Projects built by try_compile and 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_TWEAK_VERSION.rst b/Help/variable/CMAKE_TWEAK_VERSION.rst new file mode 100644 index 0000000000..be2e0500f8 --- /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 0000000000..5a4c86bd10 --- /dev/null +++ b/Help/variable/CMAKE_USER_MAKE_RULES_OVERRIDE.rst @@ -0,0 +1,23 @@ +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 project() or 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 include() will work. Use +it only as a last resort for behavior that cannot be achieved any +other way. For example, one may set CMAKE_C_FLAGS_INIT to change the +default value used to initialize CMAKE_C_FLAGS 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 +CMAKE_RUNTIME_OUTPUT_DIRECTORY that affect the placement of binaries. +Information set in the file will be used for try_compile and 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 0000000000..e6d2c68c64 --- /dev/null +++ b/Help/variable/CMAKE_USER_MAKE_RULES_OVERRIDE_LANG.rst @@ -0,0 +1,7 @@ +CMAKE_USER_MAKE_RULES_OVERRIDE_<LANG> +------------------------------------- + +Specify a CMake file that overrides platform information for <LANG>. + +This is a language-specific version of 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 0000000000..af6f08c54c --- /dev/null +++ b/Help/variable/CMAKE_USE_RELATIVE_PATHS.rst @@ -0,0 +1,10 @@ +CMAKE_USE_RELATIVE_PATHS +------------------------ + +Use relative paths (May not work!). + +If this is set to TRUE, then CMake will use relative paths between the +source and binary tree. This option does not work for more +complicated projects, and relative paths are used when possible. In +general, it is not possible to move CMake generated makefiles to a +different location regardless of the value of this variable. diff --git a/Help/variable/CMAKE_VERBOSE_MAKEFILE.rst b/Help/variable/CMAKE_VERBOSE_MAKEFILE.rst new file mode 100644 index 0000000000..2420a25e1e --- /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 0000000000..bbb1d91beb --- /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_EQUAL``, or +``VERSION_GREATER`` 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 0000000000..f55c7b177b --- /dev/null +++ b/Help/variable/CMAKE_VISIBILITY_INLINES_HIDDEN.rst @@ -0,0 +1,8 @@ +CMAKE_VISIBILITY_INLINES_HIDDEN +------------------------------- + +Default value for VISIBILITY_INLINES_HIDDEN of targets. + +This variable is used to initialize the VISIBILITY_INLINES_HIDDEN +property on all the targets. See that target property for additional +information. diff --git a/Help/variable/CMAKE_VS_DEVENV_COMMAND.rst b/Help/variable/CMAKE_VS_DEVENV_COMMAND.rst new file mode 100644 index 0000000000..14cc50ac61 --- /dev/null +++ b/Help/variable/CMAKE_VS_DEVENV_COMMAND.rst @@ -0,0 +1,14 @@ +CMAKE_VS_DEVENV_COMMAND +----------------------- + +The generators for :generator:`Visual Studio 7` 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_INTEL_Fortran_PROJECT_VERSION.rst b/Help/variable/CMAKE_VS_INTEL_Fortran_PROJECT_VERSION.rst new file mode 100644 index 0000000000..7e9d317f1f --- /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 Visual Studio 7 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 0000000000..58f2bef4c3 --- /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_MSDEV_COMMAND.rst b/Help/variable/CMAKE_VS_MSDEV_COMMAND.rst new file mode 100644 index 0000000000..718baaf825 --- /dev/null +++ b/Help/variable/CMAKE_VS_MSDEV_COMMAND.rst @@ -0,0 +1,10 @@ +CMAKE_VS_MSDEV_COMMAND +---------------------- + +The :generator:`Visual Studio 6` generator sets this variable to the +``msdev.exe`` command installed with Visual Studio 6. + +This variable is not defined by other generators even if ``msdev.exe`` +is installed on the computer. + +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 0000000000..386c3a9de6 --- /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 0000000000..c6f8d411cc --- /dev/null +++ b/Help/variable/CMAKE_VS_PLATFORM_NAME.rst @@ -0,0 +1,7 @@ +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. diff --git a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET.rst b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET.rst new file mode 100644 index 0000000000..08c6061725 --- /dev/null +++ b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET.rst @@ -0,0 +1,10 @@ +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. diff --git a/Help/variable/CMAKE_WARN_DEPRECATED.rst b/Help/variable/CMAKE_WARN_DEPRECATED.rst new file mode 100644 index 0000000000..7b2510b667 --- /dev/null +++ b/Help/variable/CMAKE_WARN_DEPRECATED.rst @@ -0,0 +1,7 @@ +CMAKE_WARN_DEPRECATED +--------------------- + +Whether to issue deprecation warnings for macros and functions. + +If TRUE, this can be used by macros and functions to issue deprecation +warnings. This variable is FALSE by default. 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 0000000000..f6a188d1c9 --- /dev/null +++ b/Help/variable/CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION.rst @@ -0,0 +1,8 @@ +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 0000000000..3e1e0dd71e --- /dev/null +++ b/Help/variable/CMAKE_WIN32_EXECUTABLE.rst @@ -0,0 +1,7 @@ +CMAKE_WIN32_EXECUTABLE +---------------------- + +Default value for WIN32_EXECUTABLE of targets. + +This variable is used to initialize the WIN32_EXECUTABLE property on +all the targets. See that target property for additional information. diff --git a/Help/variable/CMAKE_XCODE_PLATFORM_TOOLSET.rst b/Help/variable/CMAKE_XCODE_PLATFORM_TOOLSET.rst new file mode 100644 index 0000000000..f0a4841f7f --- /dev/null +++ b/Help/variable/CMAKE_XCODE_PLATFORM_TOOLSET.rst @@ -0,0 +1,9 @@ +CMAKE_XCODE_PLATFORM_TOOLSET +---------------------------- + +Xcode compiler selection. + +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 cmake -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 0000000000..d83662937f --- /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 +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 0000000000..e938978040 --- /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 CPACK_INCLUDE_TOPLEVEL_DIRECTORY but for the +component case. See 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 0000000000..4d96385342 --- /dev/null +++ b/Help/variable/CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION.rst @@ -0,0 +1,10 @@ +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 +ofCMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION when CPack runsVariables +common to all CPack generators diff --git a/Help/variable/CPACK_INCLUDE_TOPLEVEL_DIRECTORY.rst b/Help/variable/CPACK_INCLUDE_TOPLEVEL_DIRECTORY.rst new file mode 100644 index 0000000000..4f96bff57c --- /dev/null +++ b/Help/variable/CPACK_INCLUDE_TOPLEVEL_DIRECTORY.rst @@ -0,0 +1,19 @@ +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 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 0000000000..59b8cd724f --- /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 0000000000..f9cfa1b88f --- /dev/null +++ b/Help/variable/CPACK_PACKAGING_INSTALL_PREFIX.rst @@ -0,0 +1,13 @@ +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 cpack command +line by setting an alternative value. + +e.g. set(CPACK_PACKAGING_INSTALL_PREFIX "/opt") + +This is not the same purpose as 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 0000000000..69d82e6dcf --- /dev/null +++ b/Help/variable/CPACK_SET_DESTDIR.rst @@ -0,0 +1,30 @@ +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 +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 CPACK_PACKAGING_INSTALL_PREFIX as a +prefix whereas with CPACK_SET_DESTDIR set, CPack will use +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 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 0000000000..8d6f54fc1c --- /dev/null +++ b/Help/variable/CPACK_WARN_ON_ABSOLUTE_INSTALL_DESTINATION.rst @@ -0,0 +1,8 @@ +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 +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 0000000000..fd8461fd6a --- /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 0000000000..7b13ba06bb --- /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 0000000000..d25d84c0a8 --- /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 0000000000..474d6213e2 --- /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 0000000000..d0f9579804 --- /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_CHECKOUT_COMMAND.rst b/Help/variable/CTEST_CHECKOUT_COMMAND.rst new file mode 100644 index 0000000000..da256f24f5 --- /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 0000000000..c905480c0f --- /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 0000000000..5561b6dcfe --- /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 0000000000..a669dd78de --- /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 souce 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 0000000000..298195508b --- /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 0000000000..fc5dfc488d --- /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_CVS_CHECKOUT.rst b/Help/variable/CTEST_CVS_CHECKOUT.rst new file mode 100644 index 0000000000..6431c0266e --- /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 0000000000..049700b3a1 --- /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 0000000000..d7f2f7c2c9 --- /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 0000000000..c0f22158dc --- /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 0000000000..50fbd4de9e --- /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 0000000000..d15d99be24 --- /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 0000000000..22b9776325 --- /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 0000000000..904d2c8a82 --- /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 0000000000..a860a03fe5 --- /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_GIT_COMMAND.rst b/Help/variable/CTEST_GIT_COMMAND.rst new file mode 100644 index 0000000000..eb83792ecf --- /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_UPDATE_CUSTOM.rst b/Help/variable/CTEST_GIT_UPDATE_CUSTOM.rst new file mode 100644 index 0000000000..0c479e604a --- /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 0000000000..4590a786de --- /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 0000000000..3854950af8 --- /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 0000000000..9049c1f45e --- /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 0000000000..8c199bac20 --- /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 0000000000..3e26ab5151 --- /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 0000000000..2de5fb6b83 --- /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 0000000000..1147ee8e84 --- /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 0000000000..f1087c0a13 --- /dev/null +++ b/Help/variable/CTEST_MEMORYCHECK_TYPE.rst @@ -0,0 +1,7 @@ +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, 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 0000000000..bc802764e4 --- /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 0000000000..347ea549e5 --- /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 0000000000..defab12be9 --- /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 0000000000..fee4ce2d80 --- /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 0000000000..0e2790fb56 --- /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 0000000000..0f128b14af --- /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 0000000000..8a5ec253d6 --- /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 0000000000..b6837d1a0d --- /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 0000000000..af9014361f --- /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 0000000000..76551dc110 --- /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 0000000000..5f01a193a0 --- /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_TIMEOUT.rst b/Help/variable/CTEST_TEST_TIMEOUT.rst new file mode 100644 index 0000000000..c031437f0c --- /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 0000000000..de9242807b --- /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 0000000000..90155d07f2 --- /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 0000000000..e43d61d1cd --- /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 0000000000..e646e6eeab --- /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 0000000000..9f48a2e426 --- /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 0000000000..c16887855a --- /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 0000000000..977afc3c2a --- /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 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 0000000000..7079230566 --- /dev/null +++ b/Help/variable/EXECUTABLE_OUTPUT_PATH.rst @@ -0,0 +1,8 @@ +EXECUTABLE_OUTPUT_PATH +---------------------- + +Old executable location variable. + +The target property 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/LIBRARY_OUTPUT_PATH.rst b/Help/variable/LIBRARY_OUTPUT_PATH.rst new file mode 100644 index 0000000000..1c1f8ae9a7 --- /dev/null +++ b/Help/variable/LIBRARY_OUTPUT_PATH.rst @@ -0,0 +1,9 @@ +LIBRARY_OUTPUT_PATH +------------------- + +Old library location variable. + +The target properties ARCHIVE_OUTPUT_DIRECTORY, +LIBRARY_OUTPUT_DIRECTORY, and 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/MSVC.rst b/Help/variable/MSVC.rst new file mode 100644 index 0000000000..e9f931b508 --- /dev/null +++ b/Help/variable/MSVC.rst @@ -0,0 +1,6 @@ +MSVC +---- + +True when using Microsoft Visual C + +Set to true when the compiler is some version of Microsoft Visual C. diff --git a/Help/variable/MSVC10.rst b/Help/variable/MSVC10.rst new file mode 100644 index 0000000000..894c5aab08 --- /dev/null +++ b/Help/variable/MSVC10.rst @@ -0,0 +1,6 @@ +MSVC10 +------ + +True when using Microsoft Visual C 10.0 + +Set to true when the compiler is version 10.0 of Microsoft Visual C. diff --git a/Help/variable/MSVC11.rst b/Help/variable/MSVC11.rst new file mode 100644 index 0000000000..fe25297535 --- /dev/null +++ b/Help/variable/MSVC11.rst @@ -0,0 +1,6 @@ +MSVC11 +------ + +True when using Microsoft Visual C 11.0 + +Set to true when the compiler is version 11.0 of Microsoft Visual C. diff --git a/Help/variable/MSVC12.rst b/Help/variable/MSVC12.rst new file mode 100644 index 0000000000..216d3d3222 --- /dev/null +++ b/Help/variable/MSVC12.rst @@ -0,0 +1,6 @@ +MSVC12 +------ + +True when using Microsoft Visual C 12.0 + +Set to true when the compiler is version 12.0 of Microsoft Visual C. diff --git a/Help/variable/MSVC14.rst b/Help/variable/MSVC14.rst new file mode 100644 index 0000000000..33c782b746 --- /dev/null +++ b/Help/variable/MSVC14.rst @@ -0,0 +1,6 @@ +MSVC14 +------ + +True when using Microsoft Visual C 14.0 + +Set to true when the compiler is version 14.0 of Microsoft Visual C. diff --git a/Help/variable/MSVC60.rst b/Help/variable/MSVC60.rst new file mode 100644 index 0000000000..572e9f47fb --- /dev/null +++ b/Help/variable/MSVC60.rst @@ -0,0 +1,6 @@ +MSVC60 +------ + +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 0000000000..b1b7a8817d --- /dev/null +++ b/Help/variable/MSVC70.rst @@ -0,0 +1,6 @@ +MSVC70 +------ + +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 0000000000..af309a6a67 --- /dev/null +++ b/Help/variable/MSVC71.rst @@ -0,0 +1,6 @@ +MSVC71 +------ + +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 0000000000..306c67f5e8 --- /dev/null +++ b/Help/variable/MSVC80.rst @@ -0,0 +1,6 @@ +MSVC80 +------ + +True when using Microsoft Visual C 8.0 + +Set to true when the compiler is version 8.0 of Microsoft Visual C. diff --git a/Help/variable/MSVC90.rst b/Help/variable/MSVC90.rst new file mode 100644 index 0000000000..3cfcc672d4 --- /dev/null +++ b/Help/variable/MSVC90.rst @@ -0,0 +1,6 @@ +MSVC90 +------ + +True when using Microsoft Visual C 9.0 + +Set to true when the compiler is version 9.0 of Microsoft Visual C. diff --git a/Help/variable/MSVC_IDE.rst b/Help/variable/MSVC_IDE.rst new file mode 100644 index 0000000000..055f876be1 --- /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 0000000000..ef3b0b5582 --- /dev/null +++ b/Help/variable/MSVC_VERSION.rst @@ -0,0 +1,16 @@ +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 diff --git a/Help/variable/PROJECT-NAME_BINARY_DIR.rst b/Help/variable/PROJECT-NAME_BINARY_DIR.rst new file mode 100644 index 0000000000..49bc55878d --- /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 0000000000..4df3e223c1 --- /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 0000000000..0f6ed514b5 --- /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 0000000000..9e2d755a6d --- /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 0000000000..fa2cdab580 --- /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 0000000000..85b5e6bdb1 --- /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 0000000000..65c404482a --- /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 0000000000..09e9ef2185 --- /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_NAME.rst b/Help/variable/PROJECT_NAME.rst new file mode 100644 index 0000000000..61aa8bc003 --- /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 0000000000..27f2838eed --- /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 0000000000..234558dbd6 --- /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 0000000000..4b6072c549 --- /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 0000000000..5f31220f46 --- /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 0000000000..ac72ec051e --- /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 0000000000..d7f96d6ce9 --- /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 0000000000..82e3454273 --- /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. APPLE +and CYGWIN). diff --git a/Help/variable/WIN32.rst b/Help/variable/WIN32.rst new file mode 100644 index 0000000000..8cf7bf35e2 --- /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 0000000000..54ff7dee27 --- /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 0000000000..61d91b00aa --- /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 0000000000..dae3b539b7 --- /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_VERSION.rst b/Help/variable/XCODE_VERSION.rst new file mode 100644 index 0000000000..b6f04037d1 --- /dev/null +++ b/Help/variable/XCODE_VERSION.rst @@ -0,0 +1,7 @@ +XCODE_VERSION +------------- + +Version of Xcode (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"). |