diff options
Diffstat (limited to 'Help/manual')
| -rw-r--r-- | Help/manual/cmake-buildsystem.7.rst | 6 | ||||
| -rw-r--r-- | Help/manual/cmake-commands.7.rst | 1 | ||||
| -rw-r--r-- | Help/manual/cmake-developer.7.rst | 126 | ||||
| -rw-r--r-- | Help/manual/cmake-language.7.rst | 6 | ||||
| -rw-r--r-- | Help/manual/cmake-modules.7.rst | 1 | ||||
| -rw-r--r-- | Help/manual/cmake-packages.7.rst | 36 | ||||
| -rw-r--r-- | Help/manual/cmake-policies.7.rst | 8 | ||||
| -rw-r--r-- | Help/manual/cmake-properties.7.rst | 1 | ||||
| -rw-r--r-- | Help/manual/cmake-toolchains.7.rst | 5 | ||||
| -rw-r--r-- | Help/manual/cmake-variables.7.rst | 2 |
10 files changed, 113 insertions, 79 deletions
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-developer.7.rst b/Help/manual/cmake-developer.7.rst index 097d8fc..682ce47 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 ------ @@ -774,7 +720,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 +730,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 +876,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 +946,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 +1052,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..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 201c95f..8337118 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..fba1d61 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 ================= @@ -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..68954c5 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 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 99088e0..4d54075 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -47,6 +47,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 @@ -205,6 +206,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 |