diff options
Diffstat (limited to 'Help')
59 files changed, 616 insertions, 210 deletions
diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index e8b7cc8..9fbad4b 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, @@ -114,10 +137,17 @@ The options are: 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`` pool. + ``VERBATIM`` All arguments to the commands will be escaped properly for the build tool so that the invoked command receives each argument @@ -148,8 +178,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..996d08e 100644 --- a/Help/command/add_custom_target.rst +++ b/Help/command/add_custom_target.rst @@ -8,38 +8,101 @@ 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. + +``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`` pool. + +``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/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/file.rst b/Help/command/file.rst index dbc4149..600464e 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -305,3 +305,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/get_property.rst b/Help/command/get_property.rst index c2937be..632ece6 100644 --- a/Help/command/get_property.rst +++ b/Help/command/get_property.rst @@ -10,6 +10,7 @@ Get a property. DIRECTORY [dir] | TARGET <target> | SOURCE <source> | + INSTALL <file> | TEST <test> | CACHE <entry> | VARIABLE> @@ -21,29 +22,40 @@ specifies the variable in which to store the result. The second argument determines the scope from which to get the property. It must be one of the following: -GLOBAL scope is unique and does not accept a name. +``GLOBAL`` + Scope is unique and does not accept a name. -DIRECTORY scope defaults to the current directory but another -directory (already processed by CMake) may be named by full or -relative path. +``DIRECTORY`` + Scope defaults to the current directory but another + directory (already processed by CMake) may be named by full or + relative path. -TARGET scope must name one existing target. +``TARGET`` + Scope must name one existing target. -SOURCE scope must name one source file. +``SOURCE`` + Scope must name one source file. -TEST scope must name one existing test. +``INSTALL`` + Scope must name one installed file path. -CACHE scope must name one cache entry. +``TEST`` + Scope must name one existing test. -VARIABLE scope is unique and does not accept a name. +``CACHE`` + Scope must name one cache entry. -The required PROPERTY option is immediately followed by the name of +``VARIABLE`` + Scope is unique and does not accept a name. + +The required ``PROPERTY`` option is immediately followed by the name of the property to get. If the property is not set an empty value is -returned. If the SET option is given the variable is set to a boolean -value indicating whether the property has been set. If the DEFINED +returned. If the ``SET`` option is given the variable is set to a boolean +value indicating whether the property has been set. If the ``DEFINED`` option is given the variable is set to a boolean value indicating -whether the property has been defined such as with define_property. -If BRIEF_DOCS or FULL_DOCS is given then the variable is set to a +whether the property has been defined such as with the +:command:`define_property` command. +If ``BRIEF_DOCS`` or ``FULL_DOCS`` is given then the variable is set to a string containing documentation for the requested property. If documentation is requested for a property that has not been defined -NOTFOUND is returned. +``NOTFOUND`` is returned. diff --git a/Help/command/install.rst b/Help/command/install.rst index 4c52abf..5dd5aaa 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -268,7 +268,8 @@ Custom Installation Logic :: - install([[SCRIPT <file>] [CODE <code>]] [...]) + install([[SCRIPT <file>] [CODE <code>]] + [COMPONENT <component>] [...]) The ``SCRIPT`` form will invoke the given CMake script files during installation. If the script file name is a relative path it will be diff --git a/Help/command/set_property.rst b/Help/command/set_property.rst index 8cb963e..6200230 100644 --- a/Help/command/set_property.rst +++ b/Help/command/set_property.rst @@ -9,6 +9,7 @@ Set a named property in a given scope. DIRECTORY [dir] | TARGET [target1 [target2 ...]] | SOURCE [src1 [src2 ...]] | + INSTALL [file1 [file2 ...]] | TEST [test1 [test2 ...]] | CACHE [entry1 [entry2 ...]]> [APPEND] [APPEND_STRING] @@ -18,26 +19,48 @@ Set one property on zero or more objects of a scope. The first argument determines the scope in which the property is set. It must be one of the following: -GLOBAL scope is unique and does not accept a name. +``GLOBAL`` + Scope is unique and does not accept a name. -DIRECTORY scope defaults to the current directory but another -directory (already processed by CMake) may be named by full or -relative path. +``DIRECTORY`` + Scope defaults to the current directory but another + directory (already processed by CMake) may be named by full or + relative path. -TARGET scope may name zero or more existing targets. +``TARGET`` + Scope may name zero or more existing targets. -SOURCE scope may name zero or more source files. Note that source -file properties are visible only to targets added in the same -directory (CMakeLists.txt). +``SOURCE`` + Scope may name zero or more source files. Note that source + file properties are visible only to targets added in the same + directory (CMakeLists.txt). -TEST scope may name zero or more existing tests. +``INSTALL`` + Scope may name zero or more installed file paths. + These are made available to CPack to influence deployment. -CACHE scope must name zero or more cache existing entries. + Both the property key and value may use generator expressions. + Specific properties may apply to installed files and/or directories. -The required PROPERTY option is immediately followed by the name of + Path components have to be separated by forward slashes, + must be normalized and are case sensitive. + + To reference the installation prefix itself with a relative path use ".". + + Currently installed file properties are only defined for + the WIX generator where the given paths are relative + to the installation prefix. + +``TEST`` + Scope may name zero or more existing tests. + +``CACHE`` + Scope must name zero or more cache existing entries. + +The required ``PROPERTY`` option is immediately followed by the name of the property to set. Remaining arguments are used to compose the property value in the form of a semicolon-separated list. If the -APPEND option is given the list is appended to any existing property -value.If the APPEND_STRING option is given the string is append to any +``APPEND`` option is given the list is appended to any existing property +value. If the ``APPEND_STRING`` option is given the string is append to any existing property value as string, i.e. it results in a longer string and not a list of strings. diff --git a/Help/command/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 581bace..1d236ce 100644 --- a/Help/command/target_include_directories.rst +++ b/Help/command/target_include_directories.rst @@ -9,8 +9,8 @@ Add include directories to a target. <INTERFACE|PUBLIC|PRIVATE> [items1...] [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) -Specify include directories or targets to use when compiling a given -target. The named ``<target>`` must have been created by a command such +Specify include directories to use when compiling a given target. +The named ``<target>`` must have been created by a command such as :command:`add_executable` or :command:`add_library` and must not be an :prop_tgt:`IMPORTED` target. @@ -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/target_sources.rst b/Help/command/target_sources.rst index d6f148d..832240a 100644 --- a/Help/command/target_sources.rst +++ b/Help/command/target_sources.rst @@ -22,6 +22,10 @@ items will populate the :prop_tgt:`SOURCES` property of following arguments specify sources. Repeated calls for the same ``<target>`` append items in the order called. +Targets with :prop_tgt:`INTERFACE_SOURCES` may not be exported with the +:command:`export` or :command:`install(EXPORT)` commands. This limitation may be +lifted in a future version of CMake. + Arguments to ``target_sources`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. See the :manual:`cmake-buildsystem(7)` diff --git a/Help/generator/Visual Studio 14.rst b/Help/generator/Visual Studio 14 2015.rst index d621b7e..b35997a 100644 --- a/Help/generator/Visual Studio 14.rst +++ b/Help/generator/Visual Studio 14 2015.rst @@ -1,7 +1,7 @@ -Visual Studio 14 ----------------- +Visual Studio 14 2015 +--------------------- -Generates Visual Studio 14 project files. +Generates Visual Studio 14 (VS 2015) project files. The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set to specify a target platform name. @@ -9,8 +9,8 @@ to specify a target platform name. For compatibility with CMake versions prior to 3.1, one may specify a target platform name optionally at the end of this generator name: -``Visual Studio 14 Win64`` +``Visual Studio 14 2015 Win64`` Specify target platform ``x64``. -``Visual Studio 14 ARM`` +``Visual Studio 14 2015 ARM`` Specify target platform ``ARM``. 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..4616dd1 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 diff --git a/Help/manual/cmake-compile-features.7.rst b/Help/manual/cmake-compile-features.7.rst index 4259224..7a6c249 100644 --- a/Help/manual/cmake-compile-features.7.rst +++ b/Help/manual/cmake-compile-features.7.rst @@ -28,7 +28,7 @@ CMake knows are known to the compiler, regardless of language standard or compile flags needed to use them. Features known to CMake are named mostly following the same convention -as the Clang feature test macros. The are some execptions, such as +as the Clang feature test macros. The are some exceptions, such as CMake using ``cxx_final`` and ``cxx_override`` instead of the single ``cxx_override_control`` used by Clang. diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst index 0884a59..672c9b7 100644 --- a/Help/manual/cmake-developer.7.rst +++ b/Help/manual/cmake-developer.7.rst @@ -21,32 +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 ------------------------ @@ -73,28 +47,6 @@ The return value of ``find()`` must be assigned to an intermediate // ... } -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 ------------- @@ -147,7 +99,7 @@ A loop must be used instead: theSet.insert(*it); } -.. MSVC6, SunCC 5.9 +.. SunCC 5.9 Template Parameter Defaults --------------------------- @@ -177,12 +129,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 ------ diff --git a/Help/manual/cmake-generators.7.rst b/Help/manual/cmake-generators.7.rst index 4bc8c5f..bda7eef 100644 --- a/Help/manual/cmake-generators.7.rst +++ b/Help/manual/cmake-generators.7.rst @@ -64,7 +64,7 @@ one may launch CMake from any environment. /generator/Visual Studio 10 2010 /generator/Visual Studio 11 2012 /generator/Visual Studio 12 2013 - /generator/Visual Studio 14 + /generator/Visual Studio 14 2015 /generator/Xcode Extra Generators diff --git a/Help/manual/cmake-language.7.rst b/Help/manual/cmake-language.7.rst index 9c511ca..15c101f 100644 --- a/Help/manual/cmake-language.7.rst +++ b/Help/manual/cmake-language.7.rst @@ -469,8 +469,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 f5a35b3..083ed7a 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -118,6 +118,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..0d18fd7 100644 --- a/Help/manual/cmake-packages.7.rst +++ b/Help/manual/cmake-packages.7.rst @@ -260,6 +260,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 ================= @@ -369,6 +371,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..742fd63 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,4 @@ All Policies /policy/CMP0052 /policy/CMP0053 /policy/CMP0054 + /policy/CMP0055 diff --git a/Help/manual/cmake-toolchains.7.rst b/Help/manual/cmake-toolchains.7.rst index afc8ba2..44ffb3b 100644 --- a/Help/manual/cmake-toolchains.7.rst +++ b/Help/manual/cmake-toolchains.7.rst @@ -241,3 +241,20 @@ Windows Store may look like this: set(CMAKE_SYSTEM_NAME WindowsStore) set(CMAKE_SYSTEM_VERSION 8.1) + +Cross Compiling using NVIDIA Nsight Tegra +----------------------------------------- + +A toolchain file to configure a Visual Studio generator to +build using NVIDIA Nsight Tegra targeting Android may look +like this: + +.. code-block:: cmake + + set(CMAKE_SYSTEM_NAME Android) + +The :variable:`CMAKE_GENERATOR_TOOLSET` may be set to select +the Nsight Tegra "Toolchain Version" value. + +See the :prop_tgt:`ANDROID_API` and :prop_tgt:`ANDROID_GUI` +target properties to configure targets within the project. diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index 03e86af..cc132c2 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -58,7 +58,7 @@ Options will have no effect. ``-j <jobs>, --parallel <jobs>`` - Run the tests in parallel using thegiven number of jobs. + Run the tests in parallel using the given number of jobs. This option tells ctest to run the tests in parallel using given number of jobs. This option can also be set by setting the 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/CMP0053.rst b/Help/policy/CMP0053.rst index fac430e..bb0ff8b 100644 --- a/Help/policy/CMP0053.rst +++ b/Help/policy/CMP0053.rst @@ -28,7 +28,7 @@ cleaned up to simplify the behavior. Specifically: so improper variable reference syntax is always an error. * More characters are allowed to be escaped in variable names. - Previously, only ``()#" \#@^`` were valid characters to + Previously, only ``()#" \@^`` were valid characters to escape. Now any non-alphanumeric, non-semicolon, non-NUL character may be escaped following the ``escape_identity`` production in the :ref:`Escape Sequences` section of the 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/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst index bdeabdb..e24822c 100644 --- a/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst +++ b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst @@ -145,7 +145,7 @@ The features known to this version of CMake are: .. _N2672: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2672.htm ``cxx_generic_lambdas`` - Generic lambdas, ss defined in N3649_. + Generic lambdas, as defined in N3649_. .. _N3649: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3649.html diff --git a/Help/prop_tgt/ANDROID_GUI.rst b/Help/prop_tgt/ANDROID_GUI.rst index 90d2428..abdba7a 100644 --- a/Help/prop_tgt/ANDROID_GUI.rst +++ b/Help/prop_tgt/ANDROID_GUI.rst @@ -7,3 +7,7 @@ When this property is set to true the executable when built for Android will be created as an application package. This property is initialized by the value of the :variable:`CMAKE_ANDROID_GUI` variable if it is set when a target is created. + +Add the ``AndroidManifest.xml`` source file explicitly to the +target :command:`add_executable` command invocation to specify the +root directory of the application package source. diff --git a/Help/prop_tgt/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 fb28231..696ee95 100644 --- a/Help/prop_tgt/INTERFACE_SOURCES.rst +++ b/Help/prop_tgt/INTERFACE_SOURCES.rst @@ -1,13 +1,20 @@ 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 +lifted in a future version of CMake. Contents of ``INTERFACE_SOURCES`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` diff --git a/Help/prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES.rst b/Help/prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES.rst index 9e603ee..b54b6c1 100644 --- a/Help/prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES.rst +++ b/Help/prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES.rst @@ -5,8 +5,14 @@ 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. + +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.1.0.rst b/Help/release/3.1.0.rst index 1ede02b..96717c6 100644 --- a/Help/release/3.1.0.rst +++ b/Help/release/3.1.0.rst @@ -18,7 +18,7 @@ New Features Generators ---------- -* A :generator:`Visual Studio 14` generator was added. +* The :generator:`Visual Studio 14 2015` generator was added. Windows Phone and Windows Store ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -69,9 +69,15 @@ Commands :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` variables to skip searching the package registries. +* The :command:`get_property` command learned a new ``INSTALL`` scope + for properties. + * The :command:`install` command learned a ``MESSAGE_NEVER`` option to avoid output during installation. +* The :command:`set_property` command learned a new ``INSTALL`` scope + for properties. + * The :command:`string` command learned a new ``GENEX_STRIP`` subcommand which removes :manual:`generator expression <cmake-generator-expressions(7)>`. @@ -234,9 +240,6 @@ Modules * The :module:`FindOpenCL` module was introduced. -* The :module:`FindOpenGL` module now provides imported targets - ``OpenGL::GL`` and ``OpenGL::GLU`` when the libraries are found. - * The :module:`FindOpenMP` module learned to support Fortran. * The :module:`FindPkgConfig` module learned to use the ``PKG_CONFIG`` diff --git a/Help/release/dev/0-sample-topic.rst b/Help/release/dev/0-sample-topic.rst new file mode 100644 index 0000000..e4cc01e --- /dev/null +++ b/Help/release/dev/0-sample-topic.rst @@ -0,0 +1,7 @@ +0-sample-topic +-------------- + +* This is a sample release note for the change in a topic. + Developers should add similar notes for each topic branch + making a noteworthy change. Each document should be named + and titled to match the topic name to avoid merge conflicts. diff --git a/Help/release/dev/ExternalProject_CMAKE_CACHE_DEFAULT_ARGS.rst b/Help/release/dev/ExternalProject_CMAKE_CACHE_DEFAULT_ARGS.rst new file mode 100644 index 0000000..1838ab6 --- /dev/null +++ b/Help/release/dev/ExternalProject_CMAKE_CACHE_DEFAULT_ARGS.rst @@ -0,0 +1,6 @@ +ExternalProject_CMAKE_CACHE_DEFAULT_ARGS +---------------------------------------- + +* The :module:`ExternalProject` module ``ExternalProject_Add`` function + learned a new ``CMAKE_CACHE_DEFAULT_ARGS`` option to initialize cache + values in the external project without setting them on future builds. diff --git a/Help/release/dev/ExternalProject_UPDATE_DISCONNECTED.rst b/Help/release/dev/ExternalProject_UPDATE_DISCONNECTED.rst new file mode 100644 index 0000000..bed4a89 --- /dev/null +++ b/Help/release/dev/ExternalProject_UPDATE_DISCONNECTED.rst @@ -0,0 +1,6 @@ +ExternalProject_UPDATE_DISCONNECTED +----------------------------------- + +* The :module:`ExternalProject` module ``ExternalProject_Add`` command + learned an ``UPDATE_DISCONNECTED`` option to avoid automatically + updating the source tree checkout from version control. diff --git a/Help/release/dev/ExternalProject_independent-step-targets.rst b/Help/release/dev/ExternalProject_independent-step-targets.rst new file mode 100644 index 0000000..02e8db8 --- /dev/null +++ b/Help/release/dev/ExternalProject_independent-step-targets.rst @@ -0,0 +1,6 @@ +ExternalProject_independent-step-targets +---------------------------------------- + +* The :module:`ExternalProject` module learned options to create + independent external project step targets that do not depend + on the builtin steps. diff --git a/Help/release/dev/FindOpenGL-no-X11.rst b/Help/release/dev/FindOpenGL-no-X11.rst new file mode 100644 index 0000000..dacf165 --- /dev/null +++ b/Help/release/dev/FindOpenGL-no-X11.rst @@ -0,0 +1,8 @@ +FindOpenGL-no-X11 +----------------- + +* 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. diff --git a/Help/release/dev/FindOpenSSL-separate-libs.rst b/Help/release/dev/FindOpenSSL-separate-libs.rst new file mode 100644 index 0000000..96e3961 --- /dev/null +++ b/Help/release/dev/FindOpenSSL-separate-libs.rst @@ -0,0 +1,7 @@ +FindOpenSSL-separate-libs +------------------------- + +* 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. diff --git a/Help/release/dev/add-FindIntl.rst b/Help/release/dev/add-FindIntl.rst new file mode 100644 index 0000000..ac048c9 --- /dev/null +++ b/Help/release/dev/add-FindIntl.rst @@ -0,0 +1,5 @@ +add-FindIntl +------------ + +* The :module:`FindIntl` module was added to find the Gettext ``libintl`` + library. diff --git a/Help/release/dev/add-continue-command.rst b/Help/release/dev/add-continue-command.rst new file mode 100644 index 0000000..4995a8e --- /dev/null +++ b/Help/release/dev/add-continue-command.rst @@ -0,0 +1,6 @@ +add-continue-command +-------------------- + +* 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. diff --git a/Help/release/dev/add_javascript_coverage_parser.rst b/Help/release/dev/add_javascript_coverage_parser.rst new file mode 100644 index 0000000..0d068ee --- /dev/null +++ b/Help/release/dev/add_javascript_coverage_parser.rst @@ -0,0 +1,4 @@ +add_javascript_coverage_parser +------------------------------ + +* The :command:`ctest_coverage` learned to support Javascript coverage. diff --git a/Help/release/dev/break-command-strictness.rst b/Help/release/dev/break-command-strictness.rst new file mode 100644 index 0000000..0723774 --- /dev/null +++ b/Help/release/dev/break-command-strictness.rst @@ -0,0 +1,6 @@ +break-command-strictness +------------------------ + +* The :command:`break` command now rejects calls outside of a loop + context or that pass arguments to the command. + See policy :policy:`CMP0055`. diff --git a/Help/release/dev/console-pool.rst b/Help/release/dev/console-pool.rst new file mode 100644 index 0000000..19c2f19 --- /dev/null +++ b/Help/release/dev/console-pool.rst @@ -0,0 +1,8 @@ +console-pool +------------ + +* 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`` pool. diff --git a/Help/release/dev/cpack-rpm-component-descriptions.rst b/Help/release/dev/cpack-rpm-component-descriptions.rst new file mode 100644 index 0000000..769a912 --- /dev/null +++ b/Help/release/dev/cpack-rpm-component-descriptions.rst @@ -0,0 +1,7 @@ +cpack-rpm-component-descriptions +-------------------------------- + +* 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. diff --git a/Help/release/dev/cpack-rpm-pre-post-install.rst b/Help/release/dev/cpack-rpm-pre-post-install.rst new file mode 100644 index 0000000..0909d94 --- /dev/null +++ b/Help/release/dev/cpack-rpm-pre-post-install.rst @@ -0,0 +1,12 @@ +cpack-rpm-pre-post-install +-------------------------- + +* 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. diff --git a/Help/release/dev/ctest-delphi-coverage.rst b/Help/release/dev/ctest-delphi-coverage.rst new file mode 100644 index 0000000..efa97c9 --- /dev/null +++ b/Help/release/dev/ctest-delphi-coverage.rst @@ -0,0 +1,4 @@ +ctest-delphi-coverage +--------------------- + +* The :command:`ctest_coverage` learned to support Delphi coverage. diff --git a/Help/release/dev/custom-command-byproducts.rst b/Help/release/dev/custom-command-byproducts.rst new file mode 100644 index 0000000..dc85fdb --- /dev/null +++ b/Help/release/dev/custom-command-byproducts.rst @@ -0,0 +1,7 @@ +custom-command-byproducts +------------------------- + +* 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. diff --git a/Help/release/dev/file-LOCK-command.rst b/Help/release/dev/file-LOCK-command.rst new file mode 100644 index 0000000..4b11e9e --- /dev/null +++ b/Help/release/dev/file-LOCK-command.rst @@ -0,0 +1,5 @@ +file-LOCK-command +----------------- + +* The :command:`file(LOCK)` subcommand was created to allow CMake + processes to synchronize through file and directory locks. diff --git a/Help/release/index.rst b/Help/release/index.rst index 616a582..abc19b8 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -5,6 +5,8 @@ CMake Release Notes This file should include the adjacent "dev.txt" file in development versions but not in release versions. +.. include:: dev.txt + Releases ======== |