diff options
Diffstat (limited to 'Help')
58 files changed, 1248 insertions, 424 deletions
diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index e8b7cc8..e646c56 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -15,10 +15,12 @@ The first signature is for adding a custom command to produce an output:: [COMMAND command2 [ARGS] [args2...] ...] [MAIN_DEPENDENCY depend] [DEPENDS [depends...]] + [BYPRODUCTS [files...]] [IMPLICIT_DEPENDS <lang1> depend1 [<lang2> depend2] ...] [WORKING_DIRECTORY dir] - [COMMENT comment] [VERBATIM] [APPEND]) + [COMMENT comment] + [VERBATIM] [APPEND] [USES_TERMINAL]) This defines a command to generate specified ``OUTPUT`` file(s). A target created in the same directory (``CMakeLists.txt`` file) @@ -43,6 +45,27 @@ The options are: options are currently ignored when APPEND is given, but may be used in the future. +``BYPRODUCTS`` + Specify the files the command is expected to produce but whose + modification time may or may not be newer than the dependencies. + If a byproduct name is a relative path it will be interpreted + relative to the build tree directory corresponding to the + current source directory. + Each byproduct file will be marked with the :prop_sf:`GENERATED` + source file property automatically. + + Explicit specification of byproducts is supported by the + :generator:`Ninja` generator to tell the ``ninja`` build tool + how to regenerate byproducts when they are missing. It is + also useful when other build rules (e.g. custom commands) + depend on the byproducts. Ninja requires a build rule for any + generated file on which another rule depends even if there are + order-only dependencies to ensure the byproducts will be + available before their dependents build. + + The ``BYPRODUCTS`` option is ignored on non-Ninja generators + except to mark byproducts ``GENERATED``. + ``COMMAND`` Specify the command-line(s) to execute at build time. If more than one ``COMMAND`` is specified they will be executed in order, @@ -107,17 +130,25 @@ The options are: 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. + the custom command. At most one custom command may specify a + given source file as its main dependency. ``OUTPUT`` Specify the output files the command is expected to produce. If an output name is a relative path it will be interpreted relative to the build tree directory corresponding to the current source directory. + Each output file will be marked with the :prop_sf:`GENERATED` + source file property automatically. If the output of the custom command is not actually created as a file on disk it should be marked with the :prop_sf:`SYMBOLIC` source file property. +``USES_TERMINAL`` + The command will be given direct access to the terminal if possible. + With the :generator:`Ninja` generator, this places the command in + the ``console`` :prop_gbl:`pool <JOB_POOLS>`. + ``VERBATIM`` All arguments to the commands will be escaped properly for the build tool so that the invoked command receives each argument @@ -148,8 +179,10 @@ target is already built, the command will not execute. PRE_BUILD | PRE_LINK | POST_BUILD COMMAND command1 [ARGS] [args1...] [COMMAND command2 [ARGS] [args2...] ...] + [BYPRODUCTS [files...]] [WORKING_DIRECTORY dir] - [COMMENT comment] [VERBATIM]) + [COMMENT comment] + [VERBATIM] [USES_TERMINAL]) This defines a new command that will be associated with building the specified target. When the command will happen is determined by which diff --git a/Help/command/add_custom_target.rst b/Help/command/add_custom_target.rst index 1bf70bf..82d69db 100644 --- a/Help/command/add_custom_target.rst +++ b/Help/command/add_custom_target.rst @@ -8,38 +8,104 @@ Add a target with no output so it will always be built. add_custom_target(Name [ALL] [command1 [args1...]] [COMMAND command2 [args2...] ...] [DEPENDS depend depend depend ... ] + [BYPRODUCTS [files...]] [WORKING_DIRECTORY dir] - [COMMENT comment] [VERBATIM] + [COMMENT comment] + [VERBATIM] [USES_TERMINAL] [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 +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. +Use the :command:`add_custom_command` command to generate a file with +dependencies. By default nothing depends on the custom target. Use +the :command:`add_dependencies` command to add dependencies to or +from other targets. + +The options are: + +``ALL`` + Indicate that this target should be added to the default build + target so that it will be run every time (the command cannot be + called ``ALL``). + +``BYPRODUCTS`` + Specify the files the command is expected to produce but whose + modification time may or may not be updated on subsequent builds. + If a byproduct name is a relative path it will be interpreted + relative to the build tree directory corresponding to the + current source directory. + Each byproduct file will be marked with the :prop_sf:`GENERATED` + source file property automatically. + + Explicit specification of byproducts is supported by the + :generator:`Ninja` generator to tell the ``ninja`` build tool + how to regenerate byproducts when they are missing. It is + also useful when other build rules (e.g. custom commands) + depend on the byproducts. Ninja requires a build rule for any + generated file on which another rule depends even if there are + order-only dependencies to ensure the byproducts will be + available before their dependents build. + + The ``BYPRODUCTS`` option is ignored on non-Ninja generators + except to mark byproducts ``GENERATED``. + +``COMMAND`` + Specify the command-line(s) to execute at build time. + If more than one ``COMMAND`` is specified they will be executed in order, + but *not* necessarily composed into a stateful shell or batch script. + (To run a full script, use the :command:`configure_file` command or the + :command:`file(GENERATE)` command to create it, and then specify + a ``COMMAND`` to launch it.) + + If ``COMMAND`` specifies an executable target (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 this custom target. + + Arguments to ``COMMAND`` may use + :manual:`generator expressions <cmake-generator-expressions(7)>`. + References to target names in generator expressions imply target-level + dependencies. + + The command and arguments are optional and if not specified an empty + target will be created. + +``COMMENT`` + Display the given message before the commands are executed at + build time. + +``DEPENDS`` + Reference files and outputs of custom commands created with + :command:`add_custom_command` command calls in the same directory + (``CMakeLists.txt`` file). They will be brought up to date when + the target is built. + + Use the :command:`add_dependencies` command to add dependencies + on other targets. + +``SOURCES`` + Specify additional source files to be included in the custom target. + Specified source files will be added to IDE project files for + convenience in editing even if they have no build rules. + +``VERBATIM`` + All arguments to the commands will be escaped properly for the + build tool so that the invoked command receives each argument + unchanged. Note that one level of escapes is still used by the + CMake language processor before ``add_custom_target`` even sees + the arguments. Use of ``VERBATIM`` is recommended as it enables + correct behavior. When ``VERBATIM`` is not given the behavior + is platform specific because there is no protection of + tool-specific special characters. + +``USES_TERMINAL`` + The command will be given direct access to the terminal if possible. + With the :generator:`Ninja` generator, this places the command in + the ``console`` :prop_gbl:`pool <JOB_POOLS>`. + +``WORKING_DIRECTORY`` + Execute the command with the given current working directory. + If it is a relative path it will be interpreted relative to the + build tree directory corresponding to the current source directory. diff --git a/Help/command/break.rst b/Help/command/break.rst index 8f1067b..fc2cd3c 100644 --- a/Help/command/break.rst +++ b/Help/command/break.rst @@ -8,3 +8,5 @@ Break from an enclosing foreach or while loop. break() Breaks from an enclosing foreach loop or while loop + +See also the :command:`continue` command. diff --git a/Help/command/configure_file.rst b/Help/command/configure_file.rst index 70357f2..4304f09 100644 --- a/Help/command/configure_file.rst +++ b/Help/command/configure_file.rst @@ -9,38 +9,103 @@ Copy a file to another location and modify its contents. [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 +Copies an ``<input>`` file to an ``<output>`` file and substitutes +variable values referenced as ``@VAR@`` or ``${VAR}`` in the input +file content. Each variable reference will be replaced with the +current value of the variable, or the empty string if the variable +is not defined. Furthermore, input lines of the form:: + + #cmakedefine VAR ... + +will be replaced with either:: + + #define VAR ... + +or:: + + /* #undef VAR */ + +depending on whether ``VAR`` is set in CMake to any value not considered +a false constant by the :command:`if` command. The "..." content on the +line after the variable name, if any, is processed as above. +Input file lines of the form ``#cmakedefine01 VAR`` will be replaced with +either ``#define VAR 1`` or ``#define VAR 0`` similarly. + +If the input file is modified the build system will re-run CMake to re-configure the file and generate the build system again. -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: +The arguments are: -:: +``<input>`` + Path to the input file. A relative path is treated with respect to + the value of :variable:`CMAKE_CURRENT_SOURCE_DIR`. The input path + must be a file, not a directory. + +``<output>`` + Path to the output file or directory. A relative path is treated + with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. + If the path names an existing directory the output file is placed + in that directory with the same file name as the input file. + +``COPYONLY`` + Copy the file without replacing any variable references or other + content. This option may not be used with ``NEWLINE_STYLE``. + +``ESCAPE_QUOTES`` + Escape any substituted quotes with backslashes (C-style). + +``@ONLY`` + Restrict variable replacement to references of the form ``@VAR@``. + This is useful for configuring scripts that use ``${VAR}`` syntax. + +``NEWLINE_STYLE <style>`` + Specify the newline style for the output file. Specify + ``UNIX`` or ``LF`` for ``\n`` newlines, or specify + ``DOS``, ``WIN32``, or ``CRLF`` for ``\r\n`` newlines. + This option may not be used with ``COPYONLY``. + +Example +^^^^^^^ + +Consider a source tree containing a ``foo.h.in`` file: + +.. code-block:: c + + #cmakedefine FOO_ENABLE + #cmakedefine FOO_STRING "@FOO_STRING@" + +An adjacent ``CMakeLists.txt`` may use ``configure_file`` to +configure the header: + +.. code-block:: cmake + + option(FOO_ENABLE "Enable Foo" ON) + if(FOO_ENABLE) + set(FOO_STRING "foo") + endif() + configure_file(foo.h.in foo.h @ONLY) + +This creates a ``foo.h`` in the build directory corresponding to +this source directory. If the ``FOO_ENABLE`` option is on, the +configured file will contain: + +.. code-block:: c + + #define FOO_ENABLE + #define FOO_STRING "foo" + +Otherwise it will contain: + +.. code-block:: c + + /* #undef FOO_ENABLE */ + /* #undef FOO_STRING */ + +One may then use the :command:`include_directories` command to +specify the output directory as an include directory: + +.. code-block:: cmake - 'UNIX' or 'LF' for \n, 'DOS', 'WIN32' or 'CRLF' for \r\n. + include_directories(${CMAKE_CURRENT_BINARY_DIR}) -COPYONLY must not be used with NEWLINE_STYLE. +so that sources may include the header as ``#include <foo.h>``. diff --git a/Help/command/continue.rst b/Help/command/continue.rst new file mode 100644 index 0000000..1c7d673 --- /dev/null +++ b/Help/command/continue.rst @@ -0,0 +1,12 @@ +continue +-------- + +Continue to the top of enclosing foreach or while loop. + +:: + + continue() + +The ``continue`` command allows a cmake script to abort the rest of a block +in a :command:`foreach` or :command:`while` loop, and start at the top of +the next iteration. See also the :command:`break` command. diff --git a/Help/command/ctest_submit.rst b/Help/command/ctest_submit.rst index d9b0b78..2b83ed9 100644 --- a/Help/command/ctest_submit.rst +++ b/Help/command/ctest_submit.rst @@ -37,3 +37,16 @@ timed-out submission before attempting to re-submit. The RETRY_COUNT option specifies how many times to retry a timed-out submission. + +Submit to CDash Upload API +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + ctest_submit(CDASH_UPLOAD <file> [CDASH_UPLOAD_TYPE <type>]) + +This second signature is used to upload files to CDash via the CDash +file upload API. The api first sends a request to upload to CDash along +with a content hash of the file. If CDash does not already have the file, +then it is uploaded. Along with the file, a CDash type string is specified +to tell CDash which handler to use to process the data. diff --git a/Help/command/file.rst b/Help/command/file.rst index 5d3c4a9..73d4cfa 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -65,7 +65,10 @@ Parse a list of ASCII strings from ``<filename>`` and store it in Consider only strings that match the given regular expression. ``ENCODING <encoding-type>`` - Consider strings of a given encoding. "UTF-8" is currently supported. + Consider strings of a given encoding. Currently supported encodings are: + UTF-8, UTF-16LE, UTF-16BE, UTF-32LE, UTF-32BE. If the ENCODING option + is not provided and the file has a Byte Order Mark, the ENCODING option + will be defaulted to respect the Byte Order Mark. For example, the code @@ -307,3 +310,33 @@ status messages (subject to the :variable:`CMAKE_INSTALL_MESSAGE` variable), and ``NO_SOURCE_PERMISSIONS`` is default. Installation scripts generated by the :command:`install` command use this signature (with some undocumented options for internal use). + +------------------------------------------------------------------------------ + +:: + + file(LOCK <path> [DIRECTORY] [RELEASE] + [GUARD <FUNCTION|FILE|PROCESS>] + [RESULT_VARIABLE <variable>] + [TIMEOUT <seconds>]) + +Lock a file specified by ``<path>`` if no ``DIRECTORY`` option present and file +``<path>/cmake.lock`` otherwise. File will be locked for scope defined by +``GUARD`` option (default value is ``PROCESS``). ``RELEASE`` option can be used +to unlock file explicitly. If option ``TIMEOUT`` is not specified CMake will +wait until lock succeed or until fatal error occurs. If ``TIMEOUT`` is set to +``0`` lock will be tried once and result will be reported immediately. If +``TIMEOUT`` is not ``0`` CMake will try to lock file for the period specified +by ``<seconds>`` value. Any errors will be interpreted as fatal if there is no +``RESULT_VARIABLE`` option. Otherwise result will be stored in ``<variable>`` +and will be ``0`` on success or error message on failure. + +Note that lock is advisory - there is no guarantee that other processes will +respect this lock, i.e. lock synchronize two or more CMake instances sharing +some modifiable resources. Similar logic applied to ``DIRECTORY`` option - +locking parent directory doesn't prevent other ``LOCK`` commands to lock any +child directory or file. + +Trying to lock file twice is not allowed. Any intermediate directories and +file itself will be created if they not exist. ``GUARD`` and ``TIMEOUT`` +options ignored on ``RELEASE`` operation. diff --git a/Help/command/link_libraries.rst b/Help/command/link_libraries.rst index d690c9b..fd5dc37 100644 --- a/Help/command/link_libraries.rst +++ b/Help/command/link_libraries.rst @@ -1,16 +1,19 @@ link_libraries -------------- -Deprecated. Use the target_link_libraries() command instead. - Link libraries to all targets added later. :: - link_libraries(library1 <debug | optimized> library2 ...) + link_libraries([item1 [item2 [...]]] + [[debug|optimized|general] <item>] ...) + +Specify libraries or flags to use when linking any targets created later in +the current directory or below by commands such as :command:`add_executable` +or :command:`add_library`. See the :command:`target_link_libraries` command +for meaning of arguments. -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. +.. note:: + The :command:`target_link_libraries` command should be preferred whenever + possible. Library dependencies are chained automatically, so directory-wide + specification of link libraries is rarely needed. diff --git a/Help/command/string.rst b/Help/command/string.rst index 07d0ff3..351385b 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -73,8 +73,13 @@ 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 +SUBSTRING will return a substring of a given string. If length is -1 the remainder of the string starting at begin will be returned. +If string is shorter than length then end of string is used instead. + +.. note:: + CMake 3.1 and below reported an error if length pointed past + the end of string. STRIP will return a substring of a given string with leading and trailing spaces removed. diff --git a/Help/command/target_include_directories.rst b/Help/command/target_include_directories.rst index fd433a8..1d236ce 100644 --- a/Help/command/target_include_directories.rst +++ b/Help/command/target_include_directories.rst @@ -54,3 +54,6 @@ installation prefix. For example: $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib> $<INSTALL_INTERFACE:include/mylib> # <prefix>/include/mylib ) + +.. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` +.. include:: /include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst index 39537a7..e6a82b6 100644 --- a/Help/command/target_link_libraries.rst +++ b/Help/command/target_link_libraries.rst @@ -49,6 +49,9 @@ 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>``. +.. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_LINK_LIBRARIES` +.. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt + 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 diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst index 224c67b..9a70885 100644 --- a/Help/command/try_compile.rst +++ b/Help/command/try_compile.rst @@ -1,72 +1,100 @@ try_compile ----------- +.. only:: html + + .. contents:: + Try building some code. +Try Compiling Whole Projects +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + :: try_compile(RESULT_VAR <bindir> <srcdir> - <projectName> [targetName] [CMAKE_FLAGS flags...] + <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 building a project. The success or failure of the ``try_compile``, +i.e. ``TRUE`` or ``FALSE`` respectively, is returned in ``RESULT_VAR``. + +In this form, ``<srcdir>`` should contain a complete CMake project with a +``CMakeLists.txt`` file and all sources. The ``<bindir>`` and ``<srcdir>`` +will not be deleted after this command is run. Specify ``<targetName>`` to +build a specific target instead of the ``all`` or ``ALL_BUILD`` target. See +below for the meaning of other options. + +Try Compiling Source Files +^^^^^^^^^^^^^^^^^^^^^^^^^^ :: try_compile(RESULT_VAR <bindir> <srcfile|SOURCES srcfile...> - [CMAKE_FLAGS flags...] - [COMPILE_DEFINITIONS flags...] - [LINK_LIBRARIES libs...] + [CMAKE_FLAGS <flags>...] + [COMPILE_DEFINITIONS <defs>...] + [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 building an executable from one or more source files. The success or +failure of the ``try_compile``, i.e. ``TRUE`` or ``FALSE`` respectively, is +returned in ``RESULT_VAR``. -try_compile creates a CMakeList.txt file on the fly that looks like -this: +In this form the user need only supply one or more source files that include a +definition for ``main``. CMake will create a ``CMakeLists.txt`` file to build +the source(s) as an executable that looks something like this:: -:: - - add_definitions( <expanded COMPILE_DEFINITIONS from calling cmake>) + add_definitions(<expanded COMPILE_DEFINITIONS from caller>) include_directories(${INCLUDE_DIRECTORIES}) link_directories(${LINK_DIRECTORIES}) - add_executable(cmTryCompileExec sources) + add_executable(cmTryCompileExec <srcfile>...) 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. +The options are: + +``CMAKE_FLAGS <flags>...`` + Specify flags of the form ``-DVAR:TYPE=VALUE`` to be passed to + the ``cmake`` command-line used to drive the test build. + The above example shows how values for variables + ``INCLUDE_DIRECTORIES``, ``LINK_DIRECTORIES``, and ``LINK_LIBRARIES`` + are used. + +``COMPILE_DEFINITIONS <defs>...`` + Specify ``-Ddefinition`` arguments to pass to ``add_definitions`` + in the generated test project. + +``COPY_FILE <fileName>`` + Copy the linked executable to the given ``<fileName>``. + +``COPY_FILE_ERROR <var>`` + Use after ``COPY_FILE`` to capture into variable ``<var>`` any error + message encountered while trying to copy the file. + +``LINK_LIBRARIES <libs>...`` + Specify libraries to be linked in the generated project. + The list of libraries may refer to system libraries and to + :ref:`Imported Targets <Imported Targets>` from the calling project. + + If this option is specified, any ``-DLINK_LIBRARIES=...`` value + given to the ``CMAKE_FLAGS`` option will be ignored. + +``OUTPUT_VARIABLE <var>`` + Store the output from the build process the given variable. + +In this version all files in ``<bindir>/CMakeFiles/CMakeTmp`` will be +cleaned automatically. For debugging, ``--debug-trycompile`` can be +passed to ``cmake`` to avoid this clean. However, multiple sequential +``try_compile`` operations reuse this single output directory. If you use +``--debug-trycompile``, you can only debug one ``try_compile`` call at a time. +The recommended procedure is to protect all ``try_compile`` calls in your +project by ``if(NOT DEFINED RESULT_VAR)`` logic, configure with cmake +all the way through once, then delete the cache entry associated with +the try_compile call of interest, and then re-run cmake again with +``--debug-trycompile``. + +Other Behavior Settings +^^^^^^^^^^^^^^^^^^^^^^^ + +Set the :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` variable to choose +a build configuration. diff --git a/Help/command/try_run.rst b/Help/command/try_run.rst index 9a17ad9..43ee219 100644 --- a/Help/command/try_run.rst +++ b/Help/command/try_run.rst @@ -1,52 +1,97 @@ try_run ------- +.. only:: html + + .. contents:: + Try compiling and then running some code. +Try Compiling and Running Source Files +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + :: try_run(RUN_RESULT_VAR COMPILE_RESULT_VAR - bindir srcfile [CMAKE_FLAGS <Flags>] - [COMPILE_DEFINITIONS <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 + bindir srcfile [CMAKE_FLAGS <flags>...] + [COMPILE_DEFINITIONS <defs>...] + [LINK_LIBRARIES <libs>...] + [COMPILE_OUTPUT_VARIABLE <var>] + [RUN_OUTPUT_VARIABLE <var>] + [OUTPUT_VARIABLE <var>] + [ARGS <args>...]) + +Try compiling a ``<srcfile>``. Returns ``TRUE`` or ``FALSE`` for success +or failure in ``COMPILE_RESULT_VAR``. If the compile succeeded, runs the +executable and returns its exit code in ``RUN_RESULT_VAR``. If the +executable was built, but failed to run, then ``RUN_RESULT_VAR`` will be +set to ``FAILED_TO_RUN``. See the :command:`try_compile` command for +information on how the test project is constructed to build the source file. + +The options are: + +``CMAKE_FLAGS <flags>...`` + Specify flags of the form ``-DVAR:TYPE=VALUE`` to be passed to + the ``cmake`` command-line used to drive the test build. + The example in :command:`try_compile` shows how values for variables + ``INCLUDE_DIRECTORIES``, ``LINK_DIRECTORIES``, and ``LINK_LIBRARIES`` + are used. + +``COMPILE_DEFINITIONS <defs>...`` + Specify ``-Ddefinition`` arguments to pass to ``add_definitions`` + in the generated test project. + +``COMPILE_OUTPUT_VARIABLE <var>`` + Report the compile step build output in a given variable. + +``LINK_LIBRARIES <libs>...`` + Specify libraries to be linked in the generated project. + The list of libraries may refer to system libraries and to + :ref:`Imported Targets <Imported Targets>` from the calling project. + + If this option is specified, any ``-DLINK_LIBRARIES=...`` value + given to the ``CMAKE_FLAGS`` option will be ignored. + +``OUTPUT_VARIABLE <var>`` + Report the compile build output and the output from running the executable + in the given variable. This option exists for legacy reasons. Prefer + ``COMPILE_OUTPUT_VARIABLE`` and ``RUN_OUTPUT_VARIABLE`` instead. + +``RUN_OUTPUT_VARIABLE <var>`` + Report the output from running the executable in a given variable. + +Other Behavior Settings +^^^^^^^^^^^^^^^^^^^^^^^ + +Set the :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` variable to choose +a build configuration. + +Behavior when Cross Compiling +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When cross compiling, the executable compiled in the first step -usually cannot be run on the build host. 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 +usually cannot be run on the build host. The ``try_run`` command checks +the :variable:`CMAKE_CROSSCOMPILING` variable to detect whether CMake is in +cross-compiling mode. If that is the case, it will still try to compile the executable, but it will not try to run the executable. 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. +These cache entries are: + +``<RUN_RESULT_VAR>`` + Exit code if the executable were to be run on the target platform. + +``<RUN_RESULT_VAR>__TRYRUN_OUTPUT`` + Output from stdout and stderr if the executable were to be run on + the target platform. This is created only if the + ``RUN_OUTPUT_VARIABLE`` or ``OUTPUT_VARIABLE`` option was used. + +In order to make cross compiling your project easier, use ``try_run`` +only if really required. If you use ``try_run``, use the +``RUN_OUTPUT_VARIABLE`` or ``OUTPUT_VARIABLE`` options only if really +required. Using them will require that when cross-compiling, the cache +variables will have to be set manually to the output of the executable. +You can also "guard" the calls to ``try_run`` with an :command:`if` +block checking the :variable:`CMAKE_CROSSCOMPILING` variable and +provide an easy-to-preset alternative for this case. diff --git a/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt b/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt new file mode 100644 index 0000000..33f7183 --- /dev/null +++ b/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt @@ -0,0 +1,30 @@ + +Note that it is not advisable to populate the ``INSTALL_INTERFACE`` of the +|INTERFACE_PROPERTY_LINK| of a target with paths for dependencies. +That would hard-code into installed packages the include directory paths +for dependencies **as found on the machine the package was made on**. + +The ``INSTALL_INTERFACE`` of the |INTERFACE_PROPERTY_LINK| is only +suitable for specifying the required include directories of the target itself, +not its dependencies. + +That is, code like this is incorrect for targets which will be used to +generate :manual:`cmake-packages(7)`: + +.. code-block:: cmake + + target_include_directories(mylib INTERFACE + $<INSTALL_INTERFACE:${Boost_INCLUDE_DIRS};${OtherDep_INCLUDE_DIRS}> + ) + +Dependencies must provide their own :ref:`IMPORTED targets <Imported Targets>` +which have their own |INTERFACE_PROPERTY_LINK| populated +appropriately. Those :ref:`IMPORTED targets <Imported Targets>` may then be +used with the :command:`target_link_libraries` command for ``mylib``. + +That way, when a consumer uses the installed package, the +consumer will run the appropriate :command:`find_package` command to find +the dependencies on their own machine and populate the +:ref:`IMPORTED targets <Imported Targets>` with appropriate paths. See +:ref:`Creating Packages` for more. Note that many modules currently shipped +with CMake do not currently provide :ref:`IMPORTED targets <Imported Targets>`. diff --git a/Help/include/INTERFACE_LINK_LIBRARIES_WARNING.txt b/Help/include/INTERFACE_LINK_LIBRARIES_WARNING.txt new file mode 100644 index 0000000..ceefa4d --- /dev/null +++ b/Help/include/INTERFACE_LINK_LIBRARIES_WARNING.txt @@ -0,0 +1,23 @@ + +Note that it is not advisable to populate the +|INTERFACE_PROPERTY_LINK| of a target with paths for dependencies. +That would hard-code into installed packages the include directory paths +for dependencies **as found on the machine the package was made on**. + +That is, code like this is incorrect for targets which will be used to +generate :manual:`cmake-packages(7)`: + +.. code-block:: cmake + + target_link_libraries(mylib INTERFACE + ${Boost_LIBRARIES};${OtherDep_LIBRARIES} + ) + +Dependencies must provide their own :ref:`IMPORTED targets <Imported Targets>` +which have their own :prop_tgt:`IMPORTED_LOCATION` populated +appropriately. That way, when a consumer uses the installed package, the +consumer will run the appropriate :command:`find_package` command to find +the dependencies on their own machine and populate the +:ref:`IMPORTED targets <Imported Targets>` with appropriate paths. See +:ref:`Creating Packages` for more. Note that many modules currently shipped +with CMake do not currently provide :ref:`IMPORTED targets <Imported Targets>`. diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index 43f0e97..002f2c2 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -270,7 +270,11 @@ be specified in the order ``lib3`` ``lib1`` ``lib2``: target_link_libraries(myExe lib1 lib2 lib3) target_include_directories(myExe - PRIVATE $<TARGET_PROPERTY:INTERFACE_INCLUDE_DIRECTORIES:lib3>) + PRIVATE $<TARGET_PROPERTY:lib3,INTERFACE_INCLUDE_DIRECTORIES>) + +Note that care must be taken when specifying usage requirements for targets +which will be exported for installation using the :command:`install(EXPORT)` +command. See :ref:`Creating Packages` for more. .. _`Compatible Interface Properties`: diff --git a/Help/manual/cmake-commands.7.rst b/Help/manual/cmake-commands.7.rst index 9c1d3b9..c916f77 100644 --- a/Help/manual/cmake-commands.7.rst +++ b/Help/manual/cmake-commands.7.rst @@ -31,6 +31,7 @@ These commands may be used freely in CMake projects. /command/cmake_minimum_required /command/cmake_policy /command/configure_file + /command/continue /command/create_test_sourcelist /command/define_property /command/elseif @@ -67,6 +68,7 @@ These commands may be used freely in CMake projects. /command/include /command/install /command/link_directories + /command/link_libraries /command/list /command/load_cache /command/load_command @@ -117,7 +119,6 @@ versions of CMake. Do not use them in new code. /command/install_files /command/install_programs /command/install_targets - /command/link_libraries /command/make_directory /command/output_required_files /command/remove diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst index 097d8fc..e18250c 100644 --- a/Help/manual/cmake-developer.7.rst +++ b/Help/manual/cmake-developer.7.rst @@ -21,80 +21,6 @@ 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 ------------- @@ -102,53 +28,6 @@ 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 --------------------------- @@ -177,12 +56,6 @@ this does not work with other ancient compilers: 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 ------ @@ -191,12 +64,6 @@ 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 ======================= @@ -213,7 +80,9 @@ 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. +the compiler. Furthermore, set ``CMAKE_<LANG>_STANDARD_DEFAULT`` to the +default language standard level the compiler uses, or to the empty string +if the compiler has no notion of standard levels (such as ``MSVC``). 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 @@ -774,7 +643,9 @@ 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. +use the package. A find module is useful in cases where an upstream +library does not provide a +:ref:`config file package <Config File Packages>`. The traditional approach is to use variables for everything, including libraries and executables: see the `Standard Variable Names`_ section @@ -782,13 +653,9 @@ 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. +:ref:`config file packages <Config File Packages>` files as possible, by +providing :ref:`imported target <Imported targets>`. This has the advantage +of propagating :ref:`Target Usage Requirements` to consumers. In either case (or even when providing both variables and imported targets), find modules should provide backwards compatibility with old @@ -932,7 +799,10 @@ 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. +most cache options as advanced. For packages which provide both debug +and release binaries, it is common to create cache variables with a +``_LIBRARY_<CONFIG>`` suffix, such as ``Foo_LIBRARY_RELEASE`` and +``Foo_LIBRARY_DEBUG``. While these are the standard variable names, you should provide backwards compatibility for any old names that were actually in use. @@ -999,16 +869,6 @@ licence notice block # (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. @@ -1115,6 +975,47 @@ not any of its dependencies. Instead, those dependencies should also be targets, and CMake should be told that they are dependencies of this target. CMake will then combine all the necessary information automatically. +The type of the :prop_tgt:`IMPORTED` target created in the +:command:`add_library` command can always be specified as ``UNKNOWN`` +type. This simplifies the code in cases where static or shared variants may +be found, and CMake will determine the type by inspecting the files. + +If the library is available with multiple configurations, the +:prop_tgt:`IMPORTED_CONFIGURATIONS` target property should also be +populated: + +.. code-block:: cmake + + if(Foo_FOUND) + if (NOT TARGET Foo::Foo) + add_library(Foo::Foo UNKNOWN IMPORTED) + endif() + if (Foo_LIBRARY_RELEASE) + set_property(TARGET Foo::Foo APPEND PROPERTY + IMPORTED_CONFIGURATIONS RELEASE + ) + set_target_properties(Foo::Foo PROPERTIES + IMPORTED_LOCATION_RELEASE "${Foo_LIBRARY_RELEASE}" + ) + endif() + if (Foo_LIBRARY_DEBUG) + set_property(TARGET Foo::Foo APPEND PROPERTY + IMPORTED_CONFIGURATIONS DEBUG + ) + set_target_properties(Foo::Foo PROPERTIES + IMPORTED_LOCATION_DEBUG "${Foo_LIBRARY_DEBUG}" + ) + endif() + set_target_properties(Foo::Foo PROPERTIES + INTERFACE_COMPILE_OPTIONS "${PC_Foo_CFLAGS_OTHER}" + INTERFACE_INCLUDE_DIRECTORIES "${Foo_INCLUDE_DIR}" + ) + endif() + +The ``RELEASE`` variant should be listed first in the property +so that that variant is chosen if the user uses a configuration which is +not an exact match for any listed ``IMPORTED_CONFIGURATIONS``. + Most of the cache variables should be hidden in the ``ccmake`` interface unless the user explicitly asks to edit them. diff --git a/Help/manual/cmake-language.7.rst b/Help/manual/cmake-language.7.rst index 9c511ca..3e0297c 100644 --- a/Help/manual/cmake-language.7.rst +++ b/Help/manual/cmake-language.7.rst @@ -57,17 +57,21 @@ variable. Syntax ====== +.. _`CMake Language Encoding`: + Encoding -------- -A CMake Language source file must be written in 7-bit ASCII text -to be portable across all supported platforms. Newlines may be +A CMake Language source file may be written in 7-bit ASCII text for +maximum portability across all supported platforms. Newlines may be encoded as either ``\n`` or ``\r\n`` but will be converted to ``\n`` as input files are read. Note that the implementation is 8-bit clean so source files may be encoded as UTF-8 on platforms with system APIs supporting this -encoding. Furthermore, CMake 3.0 and above allow a leading UTF-8 +encoding. In addition, CMake 3.2 and above support source files +encoded in UTF-8 on Windows (using UTF-16 to call system APIs). +Furthermore, CMake 3.0 and above allow a leading UTF-8 `Byte-Order Mark`_ in source files. .. _`Byte-Order Mark`: http://en.wikipedia.org/wiki/Byte_order_mark @@ -469,8 +473,10 @@ 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. +blocks to be executed in a loop. Inside such blocks the +:command:`break` command may be used to terminate the loop +early whereas the :command:`continue` command may be used +to start with the next iteration immediately. Command Definitions ------------------- diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index 201c95f..965eede 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -63,6 +63,7 @@ All Modules /module/CPack /module/CPackWIX /module/CTest + /module/CTestCoverageCollectGCOV /module/CTestScriptMode /module/CTestUseLaunchers /module/Dart @@ -108,6 +109,7 @@ All Modules /module/FindGLUT /module/FindGnuplot /module/FindGnuTLS + /module/FindGSL /module/FindGTest /module/FindGTK2 /module/FindGTK @@ -118,6 +120,7 @@ All Modules /module/FindIce /module/FindIcotool /module/FindImageMagick + /module/FindIntl /module/FindITK /module/FindJasper /module/FindJava diff --git a/Help/manual/cmake-packages.7.rst b/Help/manual/cmake-packages.7.rst index 13e2ba0..3367ba4 100644 --- a/Help/manual/cmake-packages.7.rst +++ b/Help/manual/cmake-packages.7.rst @@ -76,6 +76,8 @@ By setting the :variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable to ``TRUE``, the ``PackageName`` package will not be searched, and will always be ``NOTFOUND``. +.. _`Config File Packages`: + Config-file Packages -------------------- @@ -260,6 +262,8 @@ The variables report the version of the package that was actually found. The ``<package>`` part of their name matches the argument given to the :command:`find_package` command. +.. _`Creating Packages`: + Creating Packages ================= @@ -354,7 +358,7 @@ 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 +to define their :ref:`usage requirements <Target Usage Requirements>`, such as :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`, :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` and other relevant built-in ``INTERFACE_`` properties. The ``INTERFACE`` variant of user-defined @@ -369,6 +373,38 @@ 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. +Note that it is not advisable to populate any properties which may contain +paths, such as :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` and +:prop_tgt:`INTERFACE_LINK_LIBRARIES`, with paths relevnt to dependencies. +That would hard-code into installed packages the include directory or library +paths for dependencies **as found on the machine the package was made on**. + +That is, code like this is incorrect for targets which will be used to +generate config file packages: + +.. code-block:: cmake + + target_link_libraries(ClimbingStats INTERFACE + ${Boost_LIBRARIES};${OtherDep_LIBRARIES}> + ) + target_include_directories(ClimbingStats INTERFACE + $<INSTALL_INTERFACE:${Boost_INCLUDE_DIRS};${OtherDep_INCLUDE_DIRS}> + ) + +Dependencies must provide their own :ref:`IMPORTED targets <Imported Targets>` +which have their own :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` and +:prop_tgt:`IMPORTED_LOCATION` populated appropriately. Those +:ref:`IMPORTED targets <Imported Targets>` may then be +used with the :command:`target_link_libraries` command for ``ClimbingStats``. + +That way, when a consumer uses the installed package, the +consumer will run the appropriate :command:`find_package` command (via the +find_dependency macro described below) to find +the dependencies on their own machine and populate the +:ref:`IMPORTED targets <Imported Targets>` with appropriate paths. Note that +many modules currently shipped with CMake do not currently provide +:ref:`IMPORTED targets <Imported Targets>`. + 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 diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index dfa423e..96f39e6 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -20,6 +20,12 @@ 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. +Note that policies are not reliable feature toggles. A policy should +almost never be set to ``OLD``, except to silence warnings in an otherwise +frozen or stable codebase, or temporarily as part of a larger migration +path. The ``OLD`` behavior of each policy is undesirable and will be +replaced with an error condition in a future release. + The :command:`cmake_minimum_required` command does more than report an error if a too-old version of CMake is used to build a project. It also sets all policies introduced in that CMake version or earlier to @@ -106,3 +112,5 @@ All Policies /policy/CMP0052 /policy/CMP0053 /policy/CMP0054 + /policy/CMP0055 + /policy/CMP0056 diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index cca6d28..25f989f 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -80,6 +80,7 @@ Properties on Targets /prop_tgt/ALIASED_TARGET /prop_tgt/ANDROID_API + /prop_tgt/ANDROID_API_MIN /prop_tgt/ANDROID_GUI /prop_tgt/ARCHIVE_OUTPUT_DIRECTORY_CONFIG /prop_tgt/ARCHIVE_OUTPUT_DIRECTORY @@ -293,6 +294,7 @@ Properties on Source Files /prop_sf/VS_DEPLOYMENT_CONTENT /prop_sf/VS_DEPLOYMENT_LOCATION /prop_sf/VS_SHADER_ENTRYPOINT + /prop_sf/VS_SHADER_FLAGS /prop_sf/VS_SHADER_MODEL /prop_sf/VS_SHADER_TYPE /prop_sf/WRAP_EXCLUDE diff --git a/Help/manual/cmake-toolchains.7.rst b/Help/manual/cmake-toolchains.7.rst index 44ffb3b..054438d 100644 --- a/Help/manual/cmake-toolchains.7.rst +++ b/Help/manual/cmake-toolchains.7.rst @@ -256,5 +256,6 @@ like this: The :variable:`CMAKE_GENERATOR_TOOLSET` may be set to select the Nsight Tegra "Toolchain Version" value. -See the :prop_tgt:`ANDROID_API` and :prop_tgt:`ANDROID_GUI` -target properties to configure targets within the project. +See the :prop_tgt:`ANDROID_API_MIN`, :prop_tgt:`ANDROID_API` +and :prop_tgt:`ANDROID_GUI` target properties to configure +targets within the project. diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 2a22f14..c342dbe 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -48,6 +48,7 @@ Variables that Provide Information /variable/CMAKE_LINK_LIBRARY_SUFFIX /variable/CMAKE_MAJOR_VERSION /variable/CMAKE_MAKE_PROGRAM + /variable/CMAKE_MATCH_COUNT /variable/CMAKE_MINIMUM_REQUIRED_VERSION /variable/CMAKE_MINOR_VERSION /variable/CMAKE_PARENT_LIST_FILE @@ -180,6 +181,7 @@ Variables that Describe the System /variable/CMAKE_SYSTEM_VERSION /variable/CYGWIN /variable/ENV + /variable/MINGW /variable/MSVC10 /variable/MSVC11 /variable/MSVC12 @@ -206,6 +208,7 @@ Variables that Control the Build :maxdepth: 1 /variable/CMAKE_ANDROID_API + /variable/CMAKE_ANDROID_API_MIN /variable/CMAKE_ANDROID_GUI /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY /variable/CMAKE_AUTOMOC_MOC_OPTIONS diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 8dfc16a..da41bbb 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -11,7 +11,7 @@ Synopsis 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 -E <command> [<options>...] cmake --find-package <options>... Description @@ -32,17 +32,8 @@ 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. +``-E <command> [<options>...]`` + See `Command-Line Tool Mode`_. ``-L[A][H]`` List non-advanced cached variables. @@ -156,6 +147,111 @@ Options .. include:: OPTIONS_HELP.txt +Command-Line Tool Mode +====================== + +CMake provides builtin command-line tools through the signature:: + + cmake -E <command> [<options>...] + +Run ``cmake -E`` or ``cmake -E help`` for a summary of commands. +Available commands are: + +``chdir <dir> <cmd> [<arg>...]`` + Change the current working directory and run a command. + +``compare_files <file1> <file2>`` + Check if file1 is same as file2. + +``copy <file> <destination>`` + Copy file to destination (either file or directory). + +``copy_directory <source> <destination>`` + Copy directory 'source' content to directory 'destination'. + +``copy_if_different <in-file> <out-file>`` + Copy file if input has changed. + +``echo [<string>...]`` + Displays arguments as text. + +``echo_append [<string>...]`` + Displays arguments as text but no new line. + +``env [--unset=NAME]... [NAME=VALUE]... COMMAND [ARG]...`` + Run command in a modified environment. + +``environment`` + Display the current environment. + +``make_directory <dir>`` + Create a directory. + +``md5sum [<file>...]`` + Compute md5sum of files. + +``remove [-f] [<file>...]`` + Remove the file(s), use ``-f`` to force it. + +``remove_directory <dir>`` + Remove a directory and its contents. + +``rename <oldname> <newname>`` + Rename a file or directory (on one volume). + +``sleep <number>...`` + Sleep for given number of seconds. + +``tar [cxt][vf][zjJ] file.tar [<options>...] [--] [<file>...]`` + Create or extract a tar or zip archive. Options are: + + ``--`` + Stop interpreting options and treat all remaining arguments + as file names even if they start in ``-``. + ``--files-from=<file>`` + Read file names from the given file, one per line. + Blank lines are ignored. Lines may not start in ``-`` + except for ``--add-file=<name>`` to add files whose + names start in ``-``. + ``--mtime=<date>`` + Specify modification time recorded in tarball entries. + +``time <command> [<args>...]`` + Run command and return elapsed time. + +``touch <file>`` + Touch a file. + +``touch_nocreate <file>`` + Touch a file if it exists but do not create it. + +UNIX-specific Command-Line Tools +-------------------------------- + +The following ``cmake -E`` commands are available only on UNIX: + +``create_symlink <old> <new>`` + Create a symbolic link ``<new>`` naming ``<old>``. + +Windows-specific Command-Line Tools +----------------------------------- + +The following ``cmake -E`` commands are available only on Windows: + +``delete_regv <key>`` + Delete Windows registry value. + +``env_vs8_wince <sdkname>`` + Displays a batch file which sets the environment for the provided + Windows CE SDK installed in VS2005. + +``env_vs9_wince <sdkname>`` + Displays a batch file which sets the environment for the provided + Windows CE SDK installed in VS2008. + +``write_regv <key> <value>`` + Write Windows registry value. + See Also ======== diff --git a/Help/module/CTestCoverageCollectGCOV.rst b/Help/module/CTestCoverageCollectGCOV.rst new file mode 100644 index 0000000..4c5deca --- /dev/null +++ b/Help/module/CTestCoverageCollectGCOV.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CTestCoverageCollectGCOV.cmake diff --git a/Help/module/FindGSL.rst b/Help/module/FindGSL.rst new file mode 100644 index 0000000..baf2213 --- /dev/null +++ b/Help/module/FindGSL.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindGSL.cmake diff --git a/Help/module/FindIntl.rst b/Help/module/FindIntl.rst new file mode 100644 index 0000000..813e2df --- /dev/null +++ b/Help/module/FindIntl.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindIntl.cmake diff --git a/Help/policy/CMP0055.rst b/Help/policy/CMP0055.rst new file mode 100644 index 0000000..fe7ab6f --- /dev/null +++ b/Help/policy/CMP0055.rst @@ -0,0 +1,17 @@ +CMP0055 +------- + +Strict checking for the :command:`break` command. + +CMake 3.1 and lower allowed calls to the :command:`break` command +outside of a loop context and also ignored any given arguments. +This was undefined behavior. + +The OLD behavior for this policy is to allow :command:`break` to be placed +outside of loop contexts and ignores any arguments. The NEW behavior for this +policy is to issue an error if a misplaced break or any arguments are found. + +This policy was introduced in CMake version 3.2. +CMake version |release| warns when the policy is not set and uses +OLD behavior. Use the cmake_policy command to set it to OLD or +NEW explicitly. diff --git a/Help/policy/CMP0056.rst b/Help/policy/CMP0056.rst new file mode 100644 index 0000000..3c75ff4 --- /dev/null +++ b/Help/policy/CMP0056.rst @@ -0,0 +1,32 @@ +CMP0056 +------- + +Honor link flags in :command:`try_compile` source-file signature. + +The :command:`try_compile` command source-file signature generates a +``CMakeLists.txt`` file to build the source file into an executable. +In order to compile the source the same way as it might be compiled +by the calling project, the generated project sets the value of the +:variable:`CMAKE_<LANG>_FLAGS` variable to that in the calling project. +The value of the :variable:`CMAKE_EXE_LINKER_FLAGS` variable may be +needed in some cases too, but CMake 3.1 and lower did not set it in +the generated project. CMake 3.2 and above prefer to set it so that +linker flags are honored as well as compiler flags. This policy +provides compatibility with the pre-3.2 behavior. + +The OLD behavior for this policy is to not set the value of the +:variable:`CMAKE_EXE_LINKER_FLAGS` variable in the generated test +project. The NEW behavior for this policy is to set the value of +the :variable:`CMAKE_EXE_LINKER_FLAGS` variable in the test project +to the same as it is in the calling project. + +If the project code does not set the policy explicitly, users may +set it on the command line by defining the +:variable:`CMAKE_POLICY_DEFAULT_CMP0056 <CMAKE_POLICY_DEFAULT_CMP<NNNN>>` +variable in the cache. + +This policy was introduced in CMake version 3.2. Unlike most policies, +CMake version |release| does *not* warn by default when this policy +is not set and simply uses OLD behavior. See documentation of the +:variable:`CMAKE_POLICY_WARNING_CMP0056 <CMAKE_POLICY_WARNING_CMP<NNNN>>` +variable to control the warning. diff --git a/Help/prop_gbl/JOB_POOLS.rst b/Help/prop_gbl/JOB_POOLS.rst index 98b9f7e..2ce74b8 100644 --- a/Help/prop_gbl/JOB_POOLS.rst +++ b/Help/prop_gbl/JOB_POOLS.rst @@ -18,3 +18,6 @@ Defined pools could be used globally by setting :variable:`CMAKE_JOB_POOL_COMPILE` and :variable:`CMAKE_JOB_POOL_LINK` or per target by setting the target properties :prop_tgt:`JOB_POOL_COMPILE` and :prop_tgt:`JOB_POOL_LINK`. + +Build targets provided by CMake that are meant for individual interactive +use, such as ``install``, are placed in the ``console`` pool automatically. diff --git a/Help/prop_sf/VS_SHADER_FLAGS.rst b/Help/prop_sf/VS_SHADER_FLAGS.rst new file mode 100644 index 0000000..0901123 --- /dev/null +++ b/Help/prop_sf/VS_SHADER_FLAGS.rst @@ -0,0 +1,4 @@ +VS_SHADER_FLAGS +--------------- + +Set additional VS shader flags of a ``.hlsl`` source file. diff --git a/Help/prop_test/TIMEOUT.rst b/Help/prop_test/TIMEOUT.rst index 0b247b8..d1cb90d 100644 --- a/Help/prop_test/TIMEOUT.rst +++ b/Help/prop_test/TIMEOUT.rst @@ -6,4 +6,4 @@ 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. +setting takes precedence over :variable:`CTEST_TEST_TIMEOUT`. diff --git a/Help/prop_tgt/ANDROID_API_MIN.rst b/Help/prop_tgt/ANDROID_API_MIN.rst new file mode 100644 index 0000000..773ab3f --- /dev/null +++ b/Help/prop_tgt/ANDROID_API_MIN.rst @@ -0,0 +1,7 @@ +ANDROID_API_MIN +--------------- + +Set the Android MIN API version (e.g. ``9``). The version number +must be a positive decimal integer. This property is initialized by +the value of the :variable:`CMAKE_ANDROID_API_MIN` variable if it is set +when a target is created. Native code builds using this API version. diff --git a/Help/prop_tgt/CXX_STANDARD.rst b/Help/prop_tgt/CXX_STANDARD.rst index 6329e34..65b30ec 100644 --- a/Help/prop_tgt/CXX_STANDARD.rst +++ b/Help/prop_tgt/CXX_STANDARD.rst @@ -5,7 +5,8 @@ The C++ standard whose features are requested to build this target. This property specifies the C++ standard whose features are requested to build this target. For some compilers, this results in adding a -flag such as ``-std=gnu++11`` to the compile line. +flag such as ``-std=gnu++11`` to the compile line. For compilers that +have no notion of a standard level, such as MSVC, this has no effect. Supported values are ``98``, ``11`` and ``14``. diff --git a/Help/prop_tgt/CXX_STANDARD_REQUIRED.rst b/Help/prop_tgt/CXX_STANDARD_REQUIRED.rst index ac103a4..4e24e5e 100644 --- a/Help/prop_tgt/CXX_STANDARD_REQUIRED.rst +++ b/Help/prop_tgt/CXX_STANDARD_REQUIRED.rst @@ -7,7 +7,8 @@ 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. +not available. For compilers that have no notion of a standard level, such as +MSVC, this has no effect. See the :manual:`cmake-compile-features(7)` manual for information on compile features. diff --git a/Help/prop_tgt/C_STANDARD.rst b/Help/prop_tgt/C_STANDARD.rst index 88ca926..3aa74af 100644 --- a/Help/prop_tgt/C_STANDARD.rst +++ b/Help/prop_tgt/C_STANDARD.rst @@ -5,7 +5,8 @@ The C standard whose features are requested to build this target. This property specifies the C standard whose features are requested to build this target. For some compilers, this results in adding a -flag such as ``-std=gnu11`` to the compile line. +flag such as ``-std=gnu11`` to the compile line. For compilers that +have no notion of a standard level, such as MSVC, this has no effect. Supported values are ``90``, ``99`` and ``11``. diff --git a/Help/prop_tgt/C_STANDARD_REQUIRED.rst b/Help/prop_tgt/C_STANDARD_REQUIRED.rst index a7304f4..743d568 100644 --- a/Help/prop_tgt/C_STANDARD_REQUIRED.rst +++ b/Help/prop_tgt/C_STANDARD_REQUIRED.rst @@ -7,7 +7,8 @@ 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. +not available. For compilers that have no notion of a standard level, such as +MSVC, this has no effect. See the :manual:`cmake-compile-features(7)` manual for information on compile features. diff --git a/Help/prop_tgt/INTERFACE_BUILD_PROPERTY.txt b/Help/prop_tgt/INTERFACE_BUILD_PROPERTY.txt new file mode 100644 index 0000000..4188b8d --- /dev/null +++ b/Help/prop_tgt/INTERFACE_BUILD_PROPERTY.txt @@ -0,0 +1,16 @@ + +List of public |property_name| requirements for a library. + +Targets may populate this property to publish the |property_name| +required to compile against the headers for the target. The |command_name| +command populates this property with values given to the ``PUBLIC`` and +``INTERFACE`` keywords. Projects may also get and set the property directly. + +When target dependencies are specified using :command:`target_link_libraries`, +CMake will read this property from all target dependencies to determine the +build properties of the consumer. + +Contents of |PROPERTY_INTERFACE_NAME| may use "generator expressions" +with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` +manual for available expressions. See the :manual:`cmake-buildsystem(7)` +-manual for more on defining buildsystem properties. diff --git a/Help/prop_tgt/INTERFACE_COMPILE_DEFINITIONS.rst b/Help/prop_tgt/INTERFACE_COMPILE_DEFINITIONS.rst index 910b661..c74a319 100644 --- a/Help/prop_tgt/INTERFACE_COMPILE_DEFINITIONS.rst +++ b/Help/prop_tgt/INTERFACE_COMPILE_DEFINITIONS.rst @@ -1,15 +1,9 @@ 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. +.. |property_name| replace:: compile definitions +.. |command_name| replace:: :command:`target_compile_definitions` +.. |PROPERTY_INTERFACE_NAME| replace:: ``INTERFACE_COMPILE_DEFINITIONS`` +.. |PROPERTY_LINK| replace:: :prop_tgt:`COMPILE_DEFINITIONS` +.. |PROPERTY_GENEX| replace:: ``$<TARGET_PROPERTY:foo,INTERFACE_COMPILE_DEFINITIONS>`` +.. include:: INTERFACE_BUILD_PROPERTY.txt diff --git a/Help/prop_tgt/INTERFACE_COMPILE_FEATURES.rst b/Help/prop_tgt/INTERFACE_COMPILE_FEATURES.rst index 7abdecb..8dfec5f 100644 --- a/Help/prop_tgt/INTERFACE_COMPILE_FEATURES.rst +++ b/Help/prop_tgt/INTERFACE_COMPILE_FEATURES.rst @@ -1,16 +1,12 @@ INTERFACE_COMPILE_FEATURES -------------------------- -List of public compile requirements for a library. +.. |property_name| replace:: compile features +.. |command_name| replace:: :command:`target_compile_features` +.. |PROPERTY_INTERFACE_NAME| replace:: ``INTERFACE_COMPILE_FEATURES`` +.. |PROPERTY_LINK| replace:: :prop_tgt:`COMPILE_FEATURES` +.. |PROPERTY_GENEX| replace:: ``$<TARGET_PROPERTY:foo,INTERFACE_COMPILE_FEATURES>`` +.. include:: INTERFACE_BUILD_PROPERTY.txt -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 +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 index d0a38d6..7f0b385 100644 --- a/Help/prop_tgt/INTERFACE_COMPILE_OPTIONS.rst +++ b/Help/prop_tgt/INTERFACE_COMPILE_OPTIONS.rst @@ -1,15 +1,9 @@ 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. +.. |property_name| replace:: compile options +.. |command_name| replace:: :command:`target_compile_options` +.. |PROPERTY_INTERFACE_NAME| replace:: ``INTERFACE_COMPILE_OPTIONS`` +.. |PROPERTY_LINK| replace:: :prop_tgt:`COMPILE_OPTIONS` +.. |PROPERTY_GENEX| replace:: ``$<TARGET_PROPERTY:foo,INTERFACE_COMPILE_OPTIONS>`` +.. include:: INTERFACE_BUILD_PROPERTY.txt diff --git a/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst b/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst index 899e821..1cfd7a8 100644 --- a/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst +++ b/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst @@ -1,22 +1,12 @@ 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. +.. |property_name| replace:: include directories +.. |command_name| replace:: :command:`target_include_directories` +.. |PROPERTY_INTERFACE_NAME| replace:: ``INTERFACE_INCLUDE_DIRECTORIES`` +.. |PROPERTY_LINK| replace:: :prop_tgt:`INCLUDE_DIRECTORIES` +.. |PROPERTY_GENEX| replace:: ``$<TARGET_PROPERTY:foo,INTERFACE_INCLUDE_DIRECTORIES>`` +.. include:: INTERFACE_BUILD_PROPERTY.txt Include directories usage requirements commonly differ between the build-tree and the install-tree. The ``BUILD_INTERFACE`` and ``INSTALL_INTERFACE`` @@ -27,7 +17,10 @@ installation prefix. For example: .. code-block:: cmake - set_property(TARGET mylib APPEND PROPERTY INTERFACE_INCLUDE_DIRECTORIES + target_include_directories(mylib INTERFACE $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib> $<INSTALL_INTERFACE:include/mylib> # <prefix>/include/mylib - ) + ) + +.. |INTERFACE_PROPERTY_LINK| replace:: ``INTERFACE_INCLUDE_DIRECTORIES`` +.. include:: /include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt diff --git a/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst index 8e4843b..55b7b8d 100644 --- a/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst +++ b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst @@ -4,7 +4,8 @@ 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 +the target is linked into another target using the +:command:`target_link_libraries` command, the libraries listed (and recursively their link interface libraries) will be provided to the other target also. This property is overridden by the :prop_tgt:`LINK_INTERFACE_LIBRARIES` or @@ -15,3 +16,6 @@ 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. + +.. |INTERFACE_PROPERTY_LINK| replace:: ``INTERFACE_LINK_LIBRARIES`` +.. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt diff --git a/Help/prop_tgt/INTERFACE_SOURCES.rst b/Help/prop_tgt/INTERFACE_SOURCES.rst index c8ca2e8..696ee95 100644 --- a/Help/prop_tgt/INTERFACE_SOURCES.rst +++ b/Help/prop_tgt/INTERFACE_SOURCES.rst @@ -1,13 +1,16 @@ INTERFACE_SOURCES ----------------- -List of interface sources to pass to the compiler. +List of interface sources to compile into consuming targets. 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``. +for consuming targets to compile. The :command:`target_sources` command +populates this property with values given to the ``PUBLIC`` and +``INTERFACE`` keywords. Projects may also get and set the property directly. + +When target dependencies are specified using :command:`target_link_libraries`, +CMake will read this property from all target dependencies to determine the +sources of the consumer. Targets with ``INTERFACE_SOURCES`` may not be exported with the :command:`export` or :command:`install(EXPORT)` commands. This limitation may be diff --git a/Help/prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES.rst b/Help/prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES.rst index 9e603ee..a0a97ad 100644 --- a/Help/prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES.rst +++ b/Help/prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES.rst @@ -5,8 +5,21 @@ 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. +compiler warnings. The :command:`target_include_directories(SYSTEM)` +command signature populates this property with values given to the +``PUBLIC`` and ``INTERFACE`` keywords. + +Projects may also get and set the property directly, but must be aware that +adding directories to this property does not make those directories used +during compilation. Adding directories to this property marks directories +as ``SYSTEM`` which otherwise would be used in a non-``SYSTEM`` manner. This +can appear similar to 'duplication', so prefer the +high-level :command:`target_include_directories(SYSTEM)` command and avoid +setting the property by low-level means. + +When target dependencies are specified using :command:`target_link_libraries`, +CMake will read this property from all target dependencies to mark the +same include directories as containing system headers. Contents of ``INTERFACE_SYSTEM_INCLUDE_DIRECTORIES`` may use "generator expressions" with the syntax ``$<...>``. See the diff --git a/Help/prop_tgt/LINK_INTERFACE_LIBRARIES.rst b/Help/prop_tgt/LINK_INTERFACE_LIBRARIES.rst index 435e25e..2e859eb 100644 --- a/Help/prop_tgt/LINK_INTERFACE_LIBRARIES.rst +++ b/Help/prop_tgt/LINK_INTERFACE_LIBRARIES.rst @@ -5,18 +5,24 @@ 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 +with exports (see the :prop_tgt:`ENABLE_EXPORTS` target property) no +default transitive link dependencies are used. This property replaces the default transitive link dependencies with an explicit list. When the target -is linked into another target the libraries listed (and recursively +is linked into another target using the :command:`target_link_libraries` +command, the libraries listed (and recursively their link interface libraries) will be provided to the other target also. If the list is empty then no transitive link dependencies will be incorporated when this target is linked into another target even if the default set is non-empty. This property is initialized by the -value of the variable CMAKE_LINK_INTERFACE_LIBRARIES if it is set when -a target is created. This property is ignored for STATIC libraries. +value of the :variable:`CMAKE_LINK_INTERFACE_LIBRARIES` variable if it is +set when a target is created. This property is ignored for ``STATIC`` +libraries. -This property is overridden by the INTERFACE_LINK_LIBRARIES property if -policy CMP0022 is NEW. +This property is overridden by the :prop_tgt:`INTERFACE_LINK_LIBRARIES` +property if policy :policy:`CMP0022` is ``NEW``. -This property is deprecated. Use INTERFACE_LINK_LIBRARIES instead. +This property is deprecated. Use :prop_tgt:`INTERFACE_LINK_LIBRARIES` +instead. + +.. |INTERFACE_PROPERTY_LINK| replace:: ``LINK_INTERFACE_LIBRARIES`` +.. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt diff --git a/Help/prop_tgt/LINK_INTERFACE_LIBRARIES_CONFIG.rst b/Help/prop_tgt/LINK_INTERFACE_LIBRARIES_CONFIG.rst index 08bd650..7f2b5dd 100644 --- a/Help/prop_tgt/LINK_INTERFACE_LIBRARIES_CONFIG.rst +++ b/Help/prop_tgt/LINK_INTERFACE_LIBRARIES_CONFIG.rst @@ -4,10 +4,14 @@ 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. +:prop_tgt:`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 overridden by the :prop_tgt:`INTERFACE_LINK_LIBRARIES` +property if policy :policy:`CMP0022` is ``NEW``. -This property is deprecated. Use INTERFACE_LINK_LIBRARIES instead. +This property is deprecated. Use :prop_tgt:`INTERFACE_LINK_LIBRARIES` +instead. + +.. |INTERFACE_PROPERTY_LINK| replace:: ``LINK_INTERFACE_LIBRARIES_<CONFIG>`` +.. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt diff --git a/Help/release/3.0.0.rst b/Help/release/3.0.rst index e92c293..d02f940 100644 --- a/Help/release/3.0.0.rst +++ b/Help/release/3.0.rst @@ -1,11 +1,11 @@ -CMake 3.0.0 Release Notes -************************* +CMake 3.0 Release Notes +*********************** .. only:: html .. contents:: -Changes made since CMake 2.8.12.2 include the following. +Changes made since CMake 2.8.12 include the following. Documentation Changes ===================== diff --git a/Help/release/3.1.0.rst b/Help/release/3.1.rst index 97a63f9..dca42cd 100644 --- a/Help/release/3.1.0.rst +++ b/Help/release/3.1.rst @@ -1,11 +1,11 @@ -CMake 3.1.0 Release Notes -************************* +CMake 3.1 Release Notes +*********************** .. only:: html .. contents:: -Changes made since CMake 3.0.0 include the following. +Changes made since CMake 3.0 include the following. Documentation Changes ===================== diff --git a/Help/release/3.2.rst b/Help/release/3.2.rst new file mode 100644 index 0000000..8abb1ca --- /dev/null +++ b/Help/release/3.2.rst @@ -0,0 +1,277 @@ +CMake 3.2 Release Notes +*********************** + +.. only:: html + + .. contents:: + +Changes made since CMake 3.1 include the following. + +New Features +============ + +Syntax +------ + +* CMake learned to support unicode characters + :ref:`encoded as UTF-8 <CMake Language Encoding>` + on Windows. This was already supported on platforms whose + system APIs accept UTF-8 encoded strings. + Unicode characters may now be used in CMake code, paths to + source files, configured files such as ``.h.in`` files, and + other files read and written by CMake. Note that because CMake + interoperates with many other tools, there may still be some + limitations when using certain unicode characters. + +Commands +-------- + +* The :command:`add_custom_command` and :command:`add_custom_target` + commands learned a new ``BYPRODUCTS`` option to specify files + produced as side effects of the custom commands. These are not + outputs because they do not always have to be newer than inputs. + +* The :command:`add_custom_command` and :command:`add_custom_target` + commands learned a new ``USES_TERMINAL`` option to request that + the command be given direct access to the terminal if possible. + The :generator:`Ninja` generator will places such commands in the + ``console`` :prop_gbl:`pool <JOB_POOLS>`. Build targets provided by CMake + that are meant for individual interactive use, such as ``install``, are now + placed in this pool. + +* A new :command:`continue` command was added that can be called inside loop + contexts to end the current iteration and start the next one at the top of + the loop block. + +* The :command:`file(LOCK)` subcommand was created to allow CMake + processes to synchronize through file and directory locks. + +* The :command:`file(STRINGS)` now supports UTF-16LE, UTF-16BE, + UTF-32LE, UTF-32BE as ``ENCODING`` options. + +* The :command:`install(EXPORT)` command now works with an absolute + ``DESTINATION`` even if targets in the export set are installed + with a destination or :ref:`usage requirements <Target Usage Requirements>` + specified relative to the install prefix. The value of the + :variable:`CMAKE_INSTALL_PREFIX` variable is hard-coded into the installed + export file as the base for relative references. + +* The :command:`try_compile` command source file signature now honors + link flags (e.g. :variable:`CMAKE_EXE_LINKER_FLAGS`) in the generated + test project. See policy :policy:`CMP0056`. + +* The :command:`try_run` command learned to honor the ``LINK_LIBRARIES`` + option just as :command:`try_compile` already does. + +* The :command:`file(GENERATE)` command now generates the output file with + the same permissions as the input file if set. + +* The :command:`file(GENERATE)` command can now generate files which are + used as source files for buildsystem targets. Generated files + automatically get their :prop_sf:`GENERATED` property set to ``TRUE``. + +Variables +--------- + +* The :variable:`CMAKE_MATCH_COUNT` variable was introduced to record the + number of matches made in the last regular expression matched in an + :command:`if` command or a :command:`string` command. + +Properties +---------- + +* An :prop_tgt:`ANDROID_API_MIN` target property was introduced to + specify the minimum version to be targeted by the toolchain. + +* A :prop_sf:`VS_SHADER_FLAGS` source file property was added to specify + additional shader flags to ``.hlsl`` files, for the Visual Studio + generators. + +Modules +------- + +* The :module:`ExternalData` module learned to support + :ref:`Custom Fetch Scripts <ExternalData Custom Fetch Scripts>`. + This allows projects to specify custom ``.cmake`` scripts for + fetching data objects during the build. + +* The :module:`ExternalProject` module learned options to create + independent external project step targets that do not depend + on the builtin steps. + +* The :module:`ExternalProject` module :command:`ExternalProject_Add` + command learned a new ``CMAKE_CACHE_DEFAULT_ARGS`` option to + initialize cache values in the external project without setting + them on future builds. + +* The :module:`ExternalProject` module :command:`ExternalProject_Add` + command learned a new ``TEST_EXCLUDE_FROM_MAIN`` option to exclude + tests from the main build. + +* The :module:`ExternalProject` module :command:`ExternalProject_Add` + command learned a new ``UPDATE_DISCONNECTED`` option to avoid + automatically updating the source tree checkout from version control. + +* The :module:`FindCUDA` module learned about the ``cusolver`` + library in CUDA 7.0. + +* The :module:`FindGit` module learned to find the ``git`` command-line tool + that comes with GitHub for Windows installed in user home directories. + +* A :module:`FindGSL` module was introduced to find the + GNU Scientific Library. + +* A :module:`FindIntl` module was introduced to find the + Gettext ``libintl`` library. + +* The :module:`FindLATEX` module learned to support components. + +* The :module:`FindMPI` module learned to find MS-MPI on Windows. + +* The :module:`FindOpenSSL` module now reports ``crypto`` and ``ssl`` + libraries separately in ``OPENSSL_CRYPTO_LIBRARY`` and + ``OPENSSL_SSL_LIBRARY``, respectively, to allow applications to + link to one without the other. + +* The :module:`WriteCompilerDetectionHeader` module learned to + create a define for portability of the ``cxx_thread_local`` feature. + The define expands to either the C++11 ``thread_local`` keyword, or a + pre-standardization compiler-specific equivalent, as appropriate. + +* The :module:`WriteCompilerDetectionHeader` module learned to create + multiple output files per compiler and per language, instead of creating + one large file. + +CTest +----- + +* The :command:`ctest_coverage` command learned to support Delphi coverage. + +* The :command:`ctest_coverage` command learned to support Javascript coverage. + +* The :module:`CTestCoverageCollectGCOV` module was introduced as an + alternative to the :command:`ctest_coverage` command for collecting + ``gcov`` results for submission to CDash. + +CPack +----- + +* The :module:`CPackRPM` module learned options to set per-component + descriptions and summaries. See the + :variable:`CPACK_RPM_<component>_PACKAGE_DESCRIPTION` and + :variable:`CPACK_RPM_<component>_PACKAGE_SUMMARY` variables. + +* The :module:`CPackRPM` module learned options to specify + requirements for pre- and post-install scripts. See the + :variable:`CPACK_RPM_PACKAGE_REQUIRES_PRE` and + :variable:`CPACK_RPM_PACKAGE_REQUIRES_POST` variables. + +* The :module:`CPackRPM` module learned options to specify + requirements for pre- and post-uninstall scripts. See the + :variable:`CPACK_RPM_PACKAGE_REQUIRES_PREUN` and + :variable:`CPACK_RPM_PACKAGE_REQUIRES_POSTUN` variables. + +* The :module:`CPackRPM` module learned a new + :variable:`CPACK_RPM_<COMPONENT>_PACKAGE_PREFIX` variable to + specify a component-specific value to use instead of + :variable:`CPACK_PACKAGING_INSTALL_PREFIX`. + +* The :module:`CPackRPM` module learned a new + :variable:`CPACK_RPM_RELOCATION_PATHS` variable to + specify multiple relocation prefixes for a single rpm package. + +Other +----- + +* The :manual:`cmake(1)` ``-E tar`` command now supports creating + ``.xz``-compressed archives with the ``J`` flag. + +* The :manual:`cmake(1)` ``-E tar`` command learned a new + ``--files-from=<file>`` option to specify file names using + lines in a file to overcome command-line length limits. + +* The :manual:`cmake(1)` ``-E tar`` command learned a new + ``--mtime=<date>`` option to specify the modification time + recorded in tarball entries. + +* The :manual:`Compile Features <cmake-compile-features(7)>` functionality + is now aware of features supported by more compilers, including: + + * Apple Clang (``AppleClang``) for Xcode versions 4.4 though 6.1. + * GNU compiler versions 4.4 through 5.0 on UNIX and Apple (``GNU``). + * Microsoft Visual Studio (``MSVC``) for versions 2010 through 2015. + * Oracle SolarisStudio (``SunPro``) version 12.4. + +* The :ref:`Qt AUTORCC` feature now tracks files listed in ``.qrc`` files + as dependencies. If an input file to the ``rcc`` tool is changed, the tool + is automatically re-run. + +New Diagnostics +=============== + +* The :command:`break` command now rejects calls outside of a loop + context or that pass arguments to the command. + See policy :policy:`CMP0055`. + +Deprecated and Removed Features +=============================== + +* Files written in the :manual:`cmake-language(7)`, such as + ``CMakeLists.txt`` or ``*.cmake`` files, are now expected to be + encoded as UTF-8. If files are already ASCII, they will be + compatible. If files were in a different encoding, including + Latin 1, they will need to be converted. + +* The :module:`FindOpenGL` module no longer explicitly searches + for any dependency on X11 libraries with the :module:`FindX11` + module. Such dependencies should not need to be explicit. + Applications using X11 APIs themselves should find and link + to X11 libraries explicitly. + +* The implementation of CMake now relies on some C++ compiler features which + are not supported by some older compilers. As a result, those old compilers + can no longer be used to build CMake itself. CMake continues to be able to + generate Makefiles and project files for users of those old compilers + however. Compilers known to no longer be capable of building CMake are: + + * Visual Studio 6 and 7.0 -- superseded by VisualStudio 7.1 and newer. + * GCC 2.95 -- superseded by GCC 3 and newer compilers. + * Borland compilers -- superseded by other Windows compilers. + * Compaq compilers -- superseded by other compilers. + * SGI compilers -- IRIX was dropped as a host platform. + +Other Changes +============= + +* On Windows and OS X, commands supporting network communication + via ``https``, such as :command:`file(DOWNLOAD)`, + :command:`file(UPLOAD)`, and :command:`ctest_submit`, now support + SSL/TLS even when CMake is not built against OpenSSL. + The Windows or OS X native SSL/TLS implementation is used by default. + OS-configured certificate authorities will be trusted automatically. + + On other platforms, when CMake is built with OpenSSL, these + commands now search for OS-configured certificate authorities + in a few ``/etc`` paths to be trusted automatically. + +* On OS X with Makefile and Ninja generators, when a compiler is found + in ``/usr/bin`` it is now mapped to the corresponding compiler inside + the Xcode application folder, if any. This allows such build + trees to continue to work with their original compiler even when + ``xcode-select`` switches to a different Xcode installation. + +* The Visual Studio generators now write solution and project + files in UTF-8 instead of Windows-1252. Windows-1252 supported + Latin 1 languages such as those found in North and South America + and Western Europe. With UTF-8, additional languages are now + supported. + +* The :generator:`Xcode` generator no longer requires a value for + the :variable:`CMAKE_MAKE_PROGRAM` variable to be located up front. + It now locates ``xcodebuild`` when needed at build time. + +* When building CMake itself using SolarisStudio 12, the default ``libCStd`` + standard library is not sufficient to build CMake. The SolarisStudio + distribution supports compiler options to use ``STLPort4`` or ``libstdc++``. + An appropriate option to select the standard library is now added + automatically when building CMake with SolarisStudio compilers. diff --git a/Help/release/index.rst b/Help/release/index.rst index 616a582..a058bc1 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -11,5 +11,6 @@ Releases .. toctree:: :maxdepth: 1 - 3.1.0 <3.1.0> - 3.0.0 <3.0.0> + 3.2 <3.2> + 3.1 <3.1> + 3.0 <3.0> diff --git a/Help/variable/CMAKE_ANDROID_API_MIN.rst b/Help/variable/CMAKE_ANDROID_API_MIN.rst new file mode 100644 index 0000000..0246c75 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_API_MIN.rst @@ -0,0 +1,5 @@ +CMAKE_ANDROID_API_MIN +--------------------- + +Default value for the :prop_tgt:`ANDROID_API_MIN` target property. +See that target property for additional information. diff --git a/Help/variable/CMAKE_MAKE_PROGRAM.rst b/Help/variable/CMAKE_MAKE_PROGRAM.rst index 97caa8a..f1d88a5 100644 --- a/Help/variable/CMAKE_MAKE_PROGRAM.rst +++ b/Help/variable/CMAKE_MAKE_PROGRAM.rst @@ -23,8 +23,15 @@ to configure the project: 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. + This generator prefers to lookup the build tool at build time + rather than to store ``CMAKE_MAKE_PROGRAM`` in the CMake cache + ahead of time. This is because ``xcodebuild`` is easy to find, + the ``cmakexbuild`` wrapper is needed only for older Xcode versions, + and the path to ``cmakexbuild`` may be outdated if CMake itself moves. + + For compatibility with versions of CMake prior to 3.2, if + a user or project explicitly adds ``CMAKE_MAKE_PROGRAM`` to + the CMake cache then CMake will use the specified value. * The Visual Studio generators set this to the full path to ``MSBuild.exe`` (VS >= 10), ``devenv.com`` (VS 7,8,9), diff --git a/Help/variable/CMAKE_MATCH_COUNT.rst b/Help/variable/CMAKE_MATCH_COUNT.rst new file mode 100644 index 0000000..8b1c036 --- /dev/null +++ b/Help/variable/CMAKE_MATCH_COUNT.rst @@ -0,0 +1,8 @@ +CMAKE_MATCH_COUNT +----------------- + +The number of matches with the last regular expression. + +When a regular expression match is used, CMake fills in ``CMAKE_MATCH_<n>`` +variables with the match contents. The ``CMAKE_MATCH_COUNT`` variable holds +the number of match expressions when these are filled. diff --git a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst index b563aea..a83c807 100644 --- a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst +++ b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst @@ -9,6 +9,8 @@ warn by default: policy :policy:`CMP0025`. * ``CMAKE_POLICY_WARNING_CMP0047`` controls the warning for policy :policy:`CMP0047`. +* ``CMAKE_POLICY_WARNING_CMP0056`` controls the warning for + policy :policy:`CMP0056`. This variable should not be set by a project in CMake code. Project developers running CMake may set this variable in their cache to diff --git a/Help/variable/MINGW.rst b/Help/variable/MINGW.rst new file mode 100644 index 0000000..521d417 --- /dev/null +++ b/Help/variable/MINGW.rst @@ -0,0 +1,6 @@ +MINGW +----- + +True when using MinGW + +Set to true when the compiler is some version of MinGW. |