diff options
Diffstat (limited to 'Help')
107 files changed, 1066 insertions, 213 deletions
diff --git a/Help/command/COMPILE_OPTIONS_SHELL.txt b/Help/command/COMPILE_OPTIONS_SHELL.txt new file mode 100644 index 0000000..a1316c8 --- /dev/null +++ b/Help/command/COMPILE_OPTIONS_SHELL.txt @@ -0,0 +1,9 @@ +The final set of compile options used for a target is constructed by +accumulating options from the current target and the usage requirements of +it dependencies. The set of options is de-duplicated to avoid repetition. +While beneficial for individual options, the de-duplication step can break +up option groups. For example, ``-D A -D B`` becomes ``-D A B``. One may +specify a group of options using shell-like quoting along with a ``SHELL:`` +prefix. The ``SHELL:`` prefix is dropped and the rest of the option string +is parsed using the :command:`separate_arguments` ``UNIX_COMMAND`` mode. +For example, ``"SHELL:-D A" "SHELL:-D B"`` becomes ``-D A -D B``. diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index 7db221c..13ea8ab 100644 --- a/Help/command/FIND_XXX.txt +++ b/Help/command/FIND_XXX.txt @@ -16,6 +16,7 @@ The general signature is: [PATH_SUFFIXES suffix1 [suffix2 ...]] [DOC "cache documentation string"] [NO_DEFAULT_PATH] + [NO_PACKAGE_ROOT_PATH] [NO_CMAKE_PATH] [NO_CMAKE_ENVIRONMENT_PATH] [NO_SYSTEM_ENVIRONMENT_PATH] @@ -60,6 +61,10 @@ If ``NO_DEFAULT_PATH`` is specified, then no additional paths are added to the search. If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: +.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR| replace:: + |prefix_XXX_SUBDIR| for each ``<prefix>`` in ``PackageName_ROOT`` if called + from within a find module + .. |CMAKE_PREFIX_PATH_XXX_SUBDIR| replace:: |prefix_XXX_SUBDIR| for each ``<prefix>`` in :variable:`CMAKE_PREFIX_PATH` @@ -71,7 +76,19 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: |prefix_XXX_SUBDIR| for each ``<prefix>`` in :variable:`CMAKE_SYSTEM_PREFIX_PATH` -1. Search paths specified in cmake-specific cache variables. +1. If called from within a find module, search prefix paths unique to the + current package being found. Specifically look in the ``PackageName_ROOT`` + CMake and environment variables. The package root variables are maintained + as a stack so if called from nested find modules, root paths from the + parent's find module will be searchd after paths from the current module, + i.e. ``CurrentPackage_ROOT``, ``ENV{CurrentPackage_ROOT}``, + ``ParentPackage_ROOT``, ``ENV{ParentPacakge_ROOT}``, etc. + This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed. + See policy :policy:`CMP0074`. + + * |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| + +2. Search paths specified in cmake-specific cache variables. These are intended to be used on the command line with a ``-DVAR=value``. The values are interpreted as :ref:`;-lists <CMake Language Lists>`. This can be skipped if ``NO_CMAKE_PATH`` is passed. @@ -80,7 +97,7 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: * |CMAKE_XXX_PATH| * |CMAKE_XXX_MAC_PATH| -2. Search paths specified in cmake-specific environment variables. +3. Search paths specified in cmake-specific environment variables. These are intended to be set in the user's shell configuration, and therefore use the host's native path separator (``;`` on Windows and ``:`` on UNIX). @@ -90,17 +107,17 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: * |CMAKE_XXX_PATH| * |CMAKE_XXX_MAC_PATH| -3. Search the paths specified by the ``HINTS`` option. +4. Search the paths specified by the ``HINTS`` option. These should be paths computed by system introspection, such as a hint provided by the location of another item already found. Hard-coded guesses should be specified with the ``PATHS`` option. -4. Search the standard system environment variables. +5. Search the standard system environment variables. This can be skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is an argument. * |SYSTEM_ENVIRONMENT_PATH_XXX| -5. Search cmake variables defined in the Platform files +6. Search cmake variables defined in the Platform files for the current system. This can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is passed. @@ -108,7 +125,7 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: * |CMAKE_SYSTEM_XXX_PATH| * |CMAKE_SYSTEM_XXX_MAC_PATH| -6. Search the paths specified by the PATHS option +7. Search the paths specified by the PATHS option or in the short-hand version of the command. These are typically hard-coded guesses. diff --git a/Help/command/add_compile_options.rst b/Help/command/add_compile_options.rst index 3fe2a33..44924e6 100644 --- a/Help/command/add_compile_options.rst +++ b/Help/command/add_compile_options.rst @@ -21,3 +21,5 @@ Arguments to ``add_compile_options`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. See the :manual:`cmake-buildsystem(7)` manual for more on defining buildsystem properties. + +.. include:: COMPILE_OPTIONS_SHELL.txt diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index d4f644a..e3fb6b6 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -217,7 +217,7 @@ of the following is specified: ``PRE_BUILD`` Run before any other rules are executed within the target. - This is supported only on Visual Studio 8 or later. + This is supported only on Visual Studio 9 or later. For all other generators ``PRE_BUILD`` will be treated as ``PRE_LINK``. ``PRE_LINK`` diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst index 3706153..8fa0df7 100644 --- a/Help/command/add_library.rst +++ b/Help/command/add_library.rst @@ -110,10 +110,10 @@ along with those compiled from their own sources. Object libraries may contain only sources that compile, header files, and other files that would not affect linking of a normal library (e.g. ``.txt``). They may contain custom commands generating such sources, but not -``PRE_BUILD``, ``PRE_LINK``, or ``POST_BUILD`` commands. Object libraries -cannot be linked. Some native build systems (such as Xcode) may not like -targets that have only object files, so consider adding at least one real -source file to any target that references ``$<TARGET_OBJECTS:objlib>``. +``PRE_BUILD``, ``PRE_LINK``, or ``POST_BUILD`` commands. Some native build +systems (such as Xcode) may not like targets that have only object files, so +consider adding at least one real source file to any target that references +``$<TARGET_OBJECTS:objlib>``. Alias Libraries ^^^^^^^^^^^^^^^ diff --git a/Help/command/cmake_minimum_required.rst b/Help/command/cmake_minimum_required.rst index 9535bf3..7c02190 100644 --- a/Help/command/cmake_minimum_required.rst +++ b/Help/command/cmake_minimum_required.rst @@ -4,11 +4,15 @@ cmake_minimum_required Set the minimum required version of cmake for a project and update `Policy Settings`_ to match the version given:: - cmake_minimum_required(VERSION major.minor[.patch[.tweak]] - [FATAL_ERROR]) + cmake_minimum_required(VERSION <min>[...<max>] [FATAL_ERROR]) -If the current version of CMake is lower than that required it will -stop processing the project and report an error. +``<min>`` and the optional ``<max>`` are each CMake versions of the form +``major.minor[.patch[.tweak]]``, and the ``...`` is literal. + +If the running version of CMake is lower than the ``<min>`` required +version it will stop processing the project and report an error. +The optional ``<max>`` version, if specified, must be at least the +``<min>`` version and affects policy settings as described below. The ``FATAL_ERROR`` option is accepted but ignored by CMake 2.6 and higher. It should be specified so CMake versions 2.4 and lower fail @@ -30,21 +34,23 @@ Policy Settings The ``cmake_minimum_required(VERSION)`` command implicitly invokes the :command:`cmake_policy(VERSION)` command to specify that the current -project code is written for the given version of CMake. -All policies introduced in the specified version or earlier will be -set to use NEW behavior. All policies introduced after the specified -version will be unset. This effectively requests behavior preferred +project code is written for the given range of CMake versions. +All policies known to the running version of CMake and introduced +in the ``<min>`` (or ``<max>``, if specified) version or earlier will +be set to use ``NEW`` behavior. All policies introduced in later +versions will be unset. This effectively requests behavior preferred as of a given CMake version and tells newer CMake versions to warn about their new policies. -When a version higher than 2.4 is specified the command implicitly -invokes:: +When a ``<min>`` version higher than 2.4 is specified the command +implicitly invokes:: - cmake_policy(VERSION major[.minor[.patch[.tweak]]]) + cmake_policy(VERSION <min>[...<max>]) -which sets the cmake policy version level to the version specified. -When version 2.4 or lower is given the command implicitly invokes:: +which sets CMake policies based on the range of versions specified. +When a ``<min>`` version 2.4 or lower is given the command implicitly +invokes:: - cmake_policy(VERSION 2.4) + cmake_policy(VERSION 2.4[...<max>]) which enables compatibility features for CMake 2.4 and lower. diff --git a/Help/command/cmake_policy.rst b/Help/command/cmake_policy.rst index b51b951..6a8dd62 100644 --- a/Help/command/cmake_policy.rst +++ b/Help/command/cmake_policy.rst @@ -24,17 +24,22 @@ The ``cmake_policy`` command is used to set policies to ``OLD`` or ``NEW`` behavior. While setting policies individually is supported, we encourage projects to set policies based on CMake versions:: - cmake_policy(VERSION major.minor[.patch[.tweak]]) - -Specify that the current CMake code is written for the given -version of CMake. All policies introduced in the specified version or -earlier will be set to use ``NEW`` behavior. All policies introduced -after the specified version will be unset (unless the + cmake_policy(VERSION <min>[...<max>]) + +``<min>`` and the optional ``<max>`` are each CMake versions of the form +``major.minor[.patch[.tweak]]``, and the ``...`` is literal. The ``<min>`` +version must be at least ``2.4`` and at most the running version of CMake. +The ``<max>`` version, if specified, must be at least the ``<min>`` version +but may exceed the running version of CMake. + +This specifies that the current CMake code is written for the given +range of CMake versions. All policies known to the running version of CMake +and introduced in the ``<min>`` (or ``<max>``, if specified) version +or earlier will be set to use ``NEW`` behavior. All policies +introduced in later versions will be unset (unless the :variable:`CMAKE_POLICY_DEFAULT_CMP<NNNN>` variable sets a default). This effectively requests behavior preferred as of a given CMake version and tells newer CMake versions to warn about their new policies. -The policy version specified must be at least 2.4 or the command will -report an error. Note that the :command:`cmake_minimum_required(VERSION)` command implicitly calls ``cmake_policy(VERSION)`` too. diff --git a/Help/command/define_property.rst b/Help/command/define_property.rst index 873c6ca..da2631c 100644 --- a/Help/command/define_property.rst +++ b/Help/command/define_property.rst @@ -34,10 +34,24 @@ actual scope needs to be given; only the kind of scope is important. The required ``PROPERTY`` option is immediately followed by the name of the property being defined. -If the ``INHERITED`` option then the :command:`get_property` command will -chain up to the next higher scope when the requested property is not set -in the scope given to the command. ``DIRECTORY`` scope chains to -``GLOBAL``. ``TARGET``, ``SOURCE``, and ``TEST`` chain to ``DIRECTORY``. +If the ``INHERITED`` option is given, then the :command:`get_property` command +will chain up to the next higher scope when the requested property is not set +in the scope given to the command. + +* ``DIRECTORY`` scope chains to its parent directory's scope, continuing the + walk up parent directories until a directory has the property set or there + are no more parents. If still not found at the top level directory, it + chains to the ``GLOBAL`` scope. +* ``TARGET``, ``SOURCE`` and ``TEST`` properties chain to ``DIRECTORY`` scope, + including further chaining up the directories, etc. as needed. + +Note that this scope chaining behavior only applies to calls to +:command:`get_property`, :command:`get_directory_property`, +:command:`get_target_property`, :command:`get_source_file_property` and +:command:`get_test_property`. There is no inheriting behavior when *setting* +properties, so using ``APPEND`` or ``APPEND_STRING`` with the +:command:`set_property` command will not consider inherited values when working +out the contents to append to. The ``BRIEF_DOCS`` and ``FULL_DOCS`` options are followed by strings to be associated with the property as its brief and full documentation. diff --git a/Help/command/export.rst b/Help/command/export.rst index 53675a7..0c676c6 100644 --- a/Help/command/export.rst +++ b/Help/command/export.rst @@ -40,6 +40,15 @@ policy CMP0022 is NEW. If a library target is included in the export but a target to which it links is not included the behavior is unspecified. +.. note:: + + :ref:`Object Libraries` under :generator:`Xcode` have special handling if + multiple architectures are listed in :variable:`CMAKE_OSX_ARCHITECTURES`. + In this case they will be exported as :ref:`Interface Libraries` with + no object files available to clients. This is sufficient to satisfy + transitive usage requirements of other targets that link to the + object libraries in their implementation. + :: export(PACKAGE <name>) diff --git a/Help/command/file.rst b/Help/command/file.rst index 5ce86e5..43ce3d9 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -98,10 +98,10 @@ command. :: file(GLOB <variable> - [LIST_DIRECTORIES true|false] [RELATIVE <path>] + [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS] [<globbing-expressions>...]) file(GLOB_RECURSE <variable> [FOLLOW_SYMLINKS] - [LIST_DIRECTORIES true|false] [RELATIVE <path>] + [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS] [<globbing-expressions>...]) Generate a list of files that match the ``<globbing-expressions>`` and @@ -110,6 +110,11 @@ regular expressions, but much simpler. If ``RELATIVE`` flag is specified, the results will be returned as relative paths to the given path. The results will be ordered lexicographically. +If the ``CONFIGURE_DEPENDS`` flag is specified, CMake will add logic +to the main build system check target to rerun the flagged ``GLOB`` commands +at build time. If any of the outputs change, CMake will regenerate the build +system. + By default ``GLOB`` lists directories - directories are omitted in result if ``LIST_DIRECTORIES`` is set to false. @@ -118,6 +123,10 @@ By default ``GLOB`` lists directories - directories are omitted in result if your source tree. If no CMakeLists.txt file changes when a source is added or removed then the generated build system cannot know when to ask CMake to regenerate. + The ``CONFIGURE_DEPENDS`` flag may not work reliably on all generators, or if + a new generator is added in the future that cannot support it, projects using + it will be stuck. Even if ``CONFIGURE_DEPENDS`` works reliably, there is + still a cost to perform the check on every rebuild. Examples of globbing expressions include:: @@ -285,6 +294,23 @@ If neither ``TLS`` option is given CMake will check variables :: + file(TOUCH [<files>...]) + file(TOUCH_NOCREATE [<files>...]) + +Create a file with no content if it does not yet exist. If the file already +exists, its access and/or modification will be updated to the time when the +function call is executed. + +Use TOUCH_NOCREATE to touch a file if it exists but not create it. If a file +does not exist it will be silently ignored. + +With TOUCH and TOUCH_NOCREATE the contents of an existing file will not be +modified. + +------------------------------------------------------------------------------ + +:: + file(TIMESTAMP <filename> <variable> [<format>] [UTC]) Compute a string representation of the modification time of ``<filename>`` diff --git a/Help/command/find_file.rst b/Help/command/find_file.rst index e56097b..2a14ad7 100644 --- a/Help/command/find_file.rst +++ b/Help/command/find_file.rst @@ -8,6 +8,9 @@ find_file .. |prefix_XXX_SUBDIR| replace:: ``<prefix>/include`` .. |entry_XXX_SUBDIR| replace:: ``<entry>/include`` +.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace:: + ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` + is set, and |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR| .. |CMAKE_PREFIX_PATH_XXX| replace:: ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set, and |CMAKE_PREFIX_PATH_XXX_SUBDIR| diff --git a/Help/command/find_library.rst b/Help/command/find_library.rst index f774f17..0861d67 100644 --- a/Help/command/find_library.rst +++ b/Help/command/find_library.rst @@ -8,6 +8,9 @@ find_library .. |prefix_XXX_SUBDIR| replace:: ``<prefix>/lib`` .. |entry_XXX_SUBDIR| replace:: ``<entry>/lib`` +.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace:: + ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set, + and |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR| .. |CMAKE_PREFIX_PATH_XXX| replace:: ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set, and |CMAKE_PREFIX_PATH_XXX_SUBDIR| diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index b2e70f2..53f3819 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -64,6 +64,7 @@ The complete Config mode command signature is:: [PATHS path1 [path2 ... ]] [PATH_SUFFIXES suffix1 [suffix2 ...]] [NO_DEFAULT_PATH] + [NO_PACKAGE_ROOT_PATH] [NO_CMAKE_PATH] [NO_CMAKE_ENVIRONMENT_PATH] [NO_SYSTEM_ENVIRONMENT_PATH] @@ -208,12 +209,12 @@ Each entry is meant for installation trees following Windows (W), UNIX <prefix>/(cmake|CMake)/ (W) <prefix>/<name>*/ (W) <prefix>/<name>*/(cmake|CMake)/ (W) - <prefix>/(lib/<arch>|lib|share)/cmake/<name>*/ (U) - <prefix>/(lib/<arch>|lib|share)/<name>*/ (U) - <prefix>/(lib/<arch>|lib|share)/<name>*/(cmake|CMake)/ (U) - <prefix>/<name>*/(lib/<arch>|lib|share)/cmake/<name>*/ (W/U) - <prefix>/<name>*/(lib/<arch>|lib|share)/<name>*/ (W/U) - <prefix>/<name>*/(lib/<arch>|lib|share)/<name>*/(cmake|CMake)/ (W/U) + <prefix>/(lib/<arch>|lib*|share)/cmake/<name>*/ (U) + <prefix>/(lib/<arch>|lib*|share)/<name>*/ (U) + <prefix>/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/ (U) + <prefix>/<name>*/(lib/<arch>|lib*|share)/cmake/<name>*/ (W/U) + <prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/ (W/U) + <prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/ (W/U) On systems supporting OS X Frameworks and Application Bundles the following directories are searched for frameworks or bundles @@ -228,10 +229,22 @@ containing a configuration file:: In all cases the ``<name>`` is treated as case-insensitive and corresponds to any of the names specified (``<package>`` or names given by ``NAMES``). + Paths with ``lib/<arch>`` are enabled if the -:variable:`CMAKE_LIBRARY_ARCHITECTURE` variable is set. If ``PATH_SUFFIXES`` -is specified the suffixes are appended to each (W) or (U) directory entry -one-by-one. +:variable:`CMAKE_LIBRARY_ARCHITECTURE` variable is set. ``lib*`` includes one +or more of the values ``lib64``, ``lib32``, ``libx32`` or ``lib`` (searched in +that order). + +* Paths with ``lib64`` are searched on 64 bit platforms if the + :prop_gbl:`FIND_LIBRARY_USE_LIB64_PATHS` property is set to ``TRUE``. +* Paths with ``lib32`` are searched on 32 bit platforms if the + :prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS` property is set to ``TRUE``. +* Paths with ``libx32`` are searched on platforms using the x32 ABI + if the :prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS` property is set to ``TRUE``. +* The ``lib`` path is always searched. + +If ``PATH_SUFFIXES`` is specified, the suffixes are appended to each +(W) or (U) directory entry one-by-one. This set of directories is intended to work in cooperation with projects that provide configuration files in their installation trees. @@ -249,7 +262,14 @@ The set of installation prefixes is constructed using the following steps. If ``NO_DEFAULT_PATH`` is specified all ``NO_*`` options are enabled. -1. Search paths specified in cmake-specific cache variables. These +1. Search paths specified in the ``PackageName_ROOT`` CMake and environment + variables. The package root variables are maintained as a stack so if + called from within a find module, root paths from the parent's find + module will also be searched after paths for the current package. + This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed. + See policy :policy:`CMP0074`. + +2. Search paths specified in cmake-specific cache variables. These are intended to be used on the command line with a ``-DVAR=value``. The values are interpreted as :ref:`;-lists <CMake Language Lists>`. This can be skipped if ``NO_CMAKE_PATH`` is passed:: @@ -258,7 +278,7 @@ enabled. CMAKE_FRAMEWORK_PATH CMAKE_APPBUNDLE_PATH -2. Search paths specified in cmake-specific environment variables. +3. Search paths specified in cmake-specific environment variables. These are intended to be set in the user's shell configuration, and therefore use the host's native path separator (``;`` on Windows and ``:`` on UNIX). @@ -269,26 +289,26 @@ enabled. CMAKE_FRAMEWORK_PATH CMAKE_APPBUNDLE_PATH -3. Search paths specified by the ``HINTS`` option. These should be paths +4. Search paths specified by the ``HINTS`` option. These should be paths computed by system introspection, such as a hint provided by the location of another item already found. Hard-coded guesses should be specified with the ``PATHS`` option. -4. Search the standard system environment variables. This can be +5. Search the standard system environment variables. This can be skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is passed. Path entries ending in ``/bin`` or ``/sbin`` are automatically converted to their parent directories:: PATH -5. Search paths stored in the CMake :ref:`User Package Registry`. +6. Search paths stored in the CMake :ref:`User Package Registry`. This can be skipped if ``NO_CMAKE_PACKAGE_REGISTRY`` is passed or by setting the :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` to ``TRUE``. See the :manual:`cmake-packages(7)` manual for details on the user package registry. -6. Search cmake variables defined in the Platform files for the +7. Search cmake variables defined in the Platform files for the current system. This can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is passed:: @@ -296,14 +316,14 @@ enabled. CMAKE_SYSTEM_FRAMEWORK_PATH CMAKE_SYSTEM_APPBUNDLE_PATH -7. Search paths stored in the CMake :ref:`System Package Registry`. +8. Search paths stored in the CMake :ref:`System Package Registry`. This can be skipped if ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` is passed or by setting the :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` to ``TRUE``. See the :manual:`cmake-packages(7)` manual for details on the system package registry. -8. Search paths specified by the ``PATHS`` option. These are typically +9. Search paths specified by the ``PATHS`` option. These are typically hard-coded guesses. .. |FIND_XXX| replace:: find_package diff --git a/Help/command/find_path.rst b/Help/command/find_path.rst index 76342d0..988a3fa 100644 --- a/Help/command/find_path.rst +++ b/Help/command/find_path.rst @@ -8,6 +8,9 @@ find_path .. |prefix_XXX_SUBDIR| replace:: ``<prefix>/include`` .. |entry_XXX_SUBDIR| replace:: ``<entry>/include`` +.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace:: + ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` + is set, and |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR| .. |CMAKE_PREFIX_PATH_XXX| replace:: ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set, and |CMAKE_PREFIX_PATH_XXX_SUBDIR| diff --git a/Help/command/find_program.rst b/Help/command/find_program.rst index d3430c0..4f00773 100644 --- a/Help/command/find_program.rst +++ b/Help/command/find_program.rst @@ -8,6 +8,8 @@ find_program .. |prefix_XXX_SUBDIR| replace:: ``<prefix>/[s]bin`` .. |entry_XXX_SUBDIR| replace:: ``<entry>/[s]bin`` +.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace:: + |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR| .. |CMAKE_PREFIX_PATH_XXX| replace:: |CMAKE_PREFIX_PATH_XXX_SUBDIR| .. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_PROGRAM_PATH` diff --git a/Help/command/get_directory_property.rst b/Help/command/get_directory_property.rst index e50abe0..bf8349c 100644 --- a/Help/command/get_directory_property.rst +++ b/Help/command/get_directory_property.rst @@ -7,11 +7,16 @@ Get a property of ``DIRECTORY`` scope. get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>) -Store a property of directory scope in the named variable. If the -property is not defined the empty-string is returned. The ``DIRECTORY`` -argument specifies another directory from which to retrieve the -property value. The specified directory must have already been -traversed by CMake. +Store a property of directory scope in the named ``<variable>``. +The ``DIRECTORY`` argument specifies another directory from which +to retrieve the property value instead of the current directory. +The specified directory must have already been traversed by CMake. + +If the property is not defined for the nominated directory scope, +an empty string is returned. In the case of ``INHERITED`` properties, +if the property is not found for the nominated directory scope, +the search will chain to a parent scope as described for the +:command:`define_property` command. :: diff --git a/Help/command/get_property.rst b/Help/command/get_property.rst index 632ece6..8b85f7d 100644 --- a/Help/command/get_property.rst +++ b/Help/command/get_property.rst @@ -50,7 +50,10 @@ be one of the following: 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 +returned, although some properties support inheriting from a parent scope +if defined to behave that way (see :command:`define_property`). + +If the ``SET`` option is given the variable is set to a boolean value indicating whether the property has been set. If the ``DEFINED`` option is given the variable is set to a boolean value indicating whether the property has been defined such as with the diff --git a/Help/command/get_source_file_property.rst b/Help/command/get_source_file_property.rst index 3e975c2..648ecbd 100644 --- a/Help/command/get_source_file_property.rst +++ b/Help/command/get_source_file_property.rst @@ -8,9 +8,15 @@ Get a property for a source file. get_source_file_property(VAR file property) Get a property from a source file. The value of the property is -stored in the variable ``VAR``. If the property is not found, ``VAR`` -will be set to "NOTFOUND". Use :command:`set_source_files_properties` -to set property values. Source file properties usually control how the -file is built. One property that is always there is :prop_sf:`LOCATION` +stored in the variable ``VAR``. If the source property is not found, the +behavior depends on whether it has been defined to be an ``INHERITED`` property +or not (see :command:`define_property`). Non-inherited properties will set +``VAR`` to "NOTFOUND", whereas inheritied properties will search the relevent +parent scope as described for the :command:`define_property` command and +if still unable to find the property, ``VAR`` will be set to an empty string. + +Use :command:`set_source_files_properties` to set property values. Source +file properties usually control how the file is built. One property that is +always there is :prop_sf:`LOCATION`. See also the more general :command:`get_property` command. diff --git a/Help/command/get_target_property.rst b/Help/command/get_target_property.rst index 2a72c3a..3d159dc 100644 --- a/Help/command/get_target_property.rst +++ b/Help/command/get_target_property.rst @@ -8,8 +8,15 @@ Get a property from a target. get_target_property(VAR target property) Get a property from a target. The value of the property is stored in -the variable ``VAR``. If the property is not found, ``VAR`` will be set to -"NOTFOUND". Use :command:`set_target_properties` to set property values. +the variable ``VAR``. If the target property is not found, the behavior +depends on whether it has been defined to be an ``INHERITED`` property +or not (see :command:`define_property`). Non-inherited properties will +set ``VAR`` to "NOTFOUND", whereas inheritied properties will search the +relevent parent scope as described for the :command:`define_property` +command and if still unable to find the property, ``VAR`` will be set to +an empty string. + +Use :command:`set_target_properties` to set target property values. Properties are usually used to control how a target is built, but some query the target instead. This command can get properties for any target so far created. The targets do not need to be in the current diff --git a/Help/command/get_test_property.rst b/Help/command/get_test_property.rst index e359f4b..703efdc 100644 --- a/Help/command/get_test_property.rst +++ b/Help/command/get_test_property.rst @@ -8,8 +8,14 @@ Get a property of the test. get_test_property(test property VAR) Get a property from the test. The value of the property is stored in -the variable ``VAR``. If the test or property is not found, ``VAR`` will -be set to "NOTFOUND". For a list of standard properties you can type -``cmake --help-property-list``. +the variable ``VAR``. If the test property is not found, the behavior +depends on whether it has been defined to be an ``INHERITED`` property +or not (see :command:`define_property`). Non-inherited properties will +set ``VAR`` to "NOTFOUND", whereas inheritied properties will search the +relevent parent scope as described for the :command:`define_property` +command and if still unable to find the property, ``VAR`` will be set to +an empty string. + +For a list of standard properties you can type ``cmake --help-property-list``. See also the more general :command:`get_property` command. diff --git a/Help/command/install.rst b/Help/command/install.rst index 2506f98..e9c185c 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -183,6 +183,13 @@ export called ``<export-name>``. It must appear before any ``RUNTIME``, ``LIBRARY``, ``ARCHIVE``, or ``OBJECTS`` options. To actually install the export file itself, call ``install(EXPORT)``, documented below. +:ref:`Interface Libraries` may be listed among the targets to install. +They install no artifacts but will be included in an associated ``EXPORT``. +If :ref:`Object Libraries` are listed but given no destination for their +object files, they will be exported as :ref:`Interface Libraries`. +This is sufficient to satisfy transitive usage requirements of other +targets that link to the object libraries in their implementation. + Installing a target with the :prop_tgt:`EXCLUDE_FROM_ALL` target property set to ``TRUE`` has undefined behavior. @@ -332,12 +339,12 @@ Installing Exports install(EXPORT <export-name> DESTINATION <dir> [NAMESPACE <namespace>] [[FILE <name>.cmake]| - [EXPORT_ANDROID_MK <name>.mk]] [PERMISSIONS permissions...] [CONFIGURATIONS [Debug|Release|...]] [EXPORT_LINK_INTERFACE_LIBRARIES] [COMPONENT <component>] [EXCLUDE_FROM_ALL]) + install(EXPORT_ANDROID_MK <export-name> DESTINATION <dir> [...]) The ``EXPORT`` form generates and installs a CMake file containing code to import targets from the installation tree into another project. @@ -360,8 +367,9 @@ specified that does not match that given to the targets associated with included in the export but a target to which it links is not included the behavior is unspecified. -In addition to cmake language files, the ``EXPORT_ANDROID_MK`` option maybe -used to specify an export to the android ndk build system. The Android +In addition to cmake language files, the ``EXPORT_ANDROID_MK`` mode maybe +used to specify an export to the android ndk build system. This mode +accepts the same options as the normal export mode. The Android NDK supports the use of prebuilt libraries, both static and shared. This allows cmake to build the libraries of a project and make them available to an ndk build system complete with transitive dependencies, include flags @@ -378,7 +386,7 @@ and installed by the current project. For example, the code will install the executable myexe to ``<prefix>/bin`` and code to import it in the file ``<prefix>/lib/myproj/myproj.cmake`` and -``<prefix>/lib/share/ndk-modules/Android.mk``. An outside project +``<prefix>/share/ndk-modules/Android.mk``. An outside project may load this file with the include command and reference the ``myexe`` executable from the installation tree using the imported target name ``mp_myexe`` as if the target were built in its own tree. diff --git a/Help/command/list.rst b/Help/command/list.rst index f6b75bc..6218a2a 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst @@ -1,68 +1,174 @@ list ---- +.. only:: html + + .. contents:: + List operations. +The list subcommands ``APPEND``, ``INSERT``, ``FILTER``, ``REMOVE_AT``, +``REMOVE_ITEM``, ``REMOVE_DUPLICATES``, ``REVERSE`` and ``SORT`` may create +new values for the list within the current CMake variable scope. Similar to +the :command:`set` command, the LIST command creates new variable values in +the current scope, even if the list itself is actually defined in a parent +scope. To propagate the results of these operations upwards, use +:command:`set` with ``PARENT_SCOPE``, :command:`set` with +``CACHE INTERNAL``, or some other means of value propagation. + +.. note:: + + A list in cmake is a ``;`` separated group of strings. To create a + list the set command can be used. For example, ``set(var a b c d e)`` + creates a list with ``a;b;c;d;e``, and ``set(var "a b c d e")`` creates a + string or a list with one item in it. (Note macro arguments are not + variables, and therefore cannot be used in LIST commands.) + +.. note:: + + When specifying index values, if ``<element index>`` is 0 or greater, it + is indexed from the beginning of the list, with 0 representing the + first list element. If ``<element index>`` is -1 or lesser, it is indexed + from the end of the list, with -1 representing the last list element. + Be careful when counting with negative indices: they do not start from + 0. -0 is equivalent to 0, the first list element. + +Capacity and Element access +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +LENGTH +"""""" + :: list(LENGTH <list> <output variable>) - list(GET <list> <element index> [<element index> ...] - <output variable>) + +Returns the list's length. + +GET +""" + +:: + + list(GET <list> <element index> [<element index> ...] <output variable>) + +Returns the list of elements specified by indices from the list. + +JOIN +"""" + +:: + + list(JOIN <list> <glue> <output variable>) + +Returns a string joining all list's elements using the glue string. +To join multiple strings, which are not part of a list, use ``JOIN`` operator +from :command:`string` command. + +SUBLIST +""""""" + +:: + + list(SUBLIST <list> <begin> <length> <output variable>) + +Returns a sublist of the given list. +If ``<length>`` is 0, an empty list will be returned. +If ``<length>`` is -1 or the list is smaller than ``<begin>+<length>`` then +the remaining elements of the list starting at ``<begin>`` will be returned. + +Search +^^^^^^ + +FIND +"""" + +:: + + list(FIND <list> <value> <output variable>) + +Returns the index of the element specified in the list or -1 +if it wasn't found. + +Modification +^^^^^^^^^^^^ + +APPEND +"""""" + +:: + list(APPEND <list> [<element> ...]) + +Appends elements to the list. + +FILTER +"""""" + +:: + list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>) - list(FIND <list> <value> <output variable>) + +Includes or removes items from the list that match the mode's pattern. +In ``REGEX`` mode, items will be matched against the given regular expression. + +For more information on regular expressions see also the +:command:`string` command. + +INSERT +"""""" + +:: + list(INSERT <list> <element_index> <element> [<element> ...]) + +Inserts elements to the list to the specified location. + +REMOVE_ITEM +""""""""""" + +:: + list(REMOVE_ITEM <list> <value> [<value> ...]) + +Removes the given items from the list. + +REMOVE_AT +""""""""" + +:: + list(REMOVE_AT <list> <index> [<index> ...]) - list(REMOVE_DUPLICATES <list>) - list(REVERSE <list>) - list(SORT <list>) -``LENGTH`` will return a given list's length. +Removes items at given indices from the list. -``GET`` will return list of elements specified by indices from the list. +REMOVE_DUPLICATES +""""""""""""""""" -``APPEND`` will append elements to the list. +:: -``FILTER`` will include or remove items from the list that match the -mode's pattern. -In ``REGEX`` mode, items will be matched against the given regular expression. -For more information on regular expressions see also the :command:`string` -command. + list(REMOVE_DUPLICATES <list>) -``FIND`` will return the index of the element specified in the list or -1 -if it wasn't found. +Removes duplicated items in the list. + +Sorting +^^^^^^^ -``INSERT`` will insert elements to the list to the specified location. +REVERSE +""""""" -``REMOVE_AT`` and ``REMOVE_ITEM`` will remove items from the list. The -difference is that ``REMOVE_ITEM`` will remove the given items, while -``REMOVE_AT`` will remove the items at the given indices. +:: -``REMOVE_DUPLICATES`` will remove duplicated items in the list. + list(REVERSE <list>) -``REVERSE`` reverses the contents of the list in-place. +Reverses the contents of the list in-place. -``SORT`` sorts the list in-place alphabetically. +SORT +"""" + +:: + + list(SORT <list>) -The list subcommands ``APPEND``, ``INSERT``, ``FILTER``, ``REMOVE_AT``, -``REMOVE_ITEM``, ``REMOVE_DUPLICATES``, ``REVERSE`` and ``SORT`` may create new -values for the list within the current CMake variable scope. Similar to the -:command:`set` command, the LIST command creates new variable values in the -current scope, even if the list itself is actually defined in a parent -scope. To propagate the results of these operations upwards, use -:command:`set` with ``PARENT_SCOPE``, :command:`set` with -``CACHE INTERNAL``, or some other means of value propagation. -NOTES: A list in cmake is a ``;`` separated group of strings. To create a -list the set command can be used. For example, ``set(var a b c d e)`` -creates a list with ``a;b;c;d;e``, and ``set(var "a b c d e")`` creates a -string or a list with one item in it. (Note macro arguments are not -variables, and therefore cannot be used in LIST commands.) - -When specifying index values, if ``<element index>`` is 0 or greater, it -is indexed from the beginning of the list, with 0 representing the -first list element. If ``<element index>`` is -1 or lesser, it is indexed -from the end of the list, with -1 representing the last list element. -Be careful when counting with negative indices: they do not start from -0. -0 is equivalent to 0, the first list element. +Sorts the list in-place alphabetically. diff --git a/Help/command/project.rst b/Help/command/project.rst index eb185e4..e46dd69 100644 --- a/Help/command/project.rst +++ b/Help/command/project.rst @@ -1,7 +1,7 @@ project ------- -Set a name, version, and enable languages for the entire project. +Sets project details such as name, version, etc. and enables languages. .. code-block:: cmake @@ -9,6 +9,7 @@ Set a name, version, and enable languages for the entire project. project(<PROJECT-NAME> [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]] [DESCRIPTION <project-description-string>] + [HOMEPAGE_URL <url-string>] [LANGUAGES <language-name>...]) Sets the name of the project and stores the name in the @@ -41,9 +42,18 @@ in variables Variables corresponding to unspecified versions are set to the empty string (if policy :policy:`CMP0048` is set to ``NEW``). -If optional ``DESCRIPTION`` is given, then additional :variable:`PROJECT_DESCRIPTION` -variable will be set to its argument. The argument must be a string with short -description of the project (only a few words). +If the optional ``DESCRIPTION`` is given, then :variable:`PROJECT_DESCRIPTION` +and :variable:`<PROJECT-NAME>_DESCRIPTION` will be set to its argument. +The description is expected to be a relatively short string, usually no more +than a few words. + +The optional ``HOMEPAGE_URL`` sets the analogous variables +:variable:`PROJECT_HOMEPAGE_URL` and :variable:`<PROJECT-NAME>_HOMEPAGE_URL`. +When this option is given, the URL provided should be the canonical home for +the project. + +Note that the description and homepage URL may be used as defaults for +things like packaging meta-data, documentation, etc. Optionally you can specify which languages your project supports. Example languages include ``C``, ``CXX`` (i.e. C++), ``CUDA``, @@ -63,7 +73,11 @@ The top-level ``CMakeLists.txt`` file for a project must contain a literal, direct call to the :command:`project` command; loading one through the :command:`include` command is not sufficient. If no such call exists CMake will implicitly add one to the top that enables the -default languages (``C`` and ``CXX``). +default languages (``C`` and ``CXX``). The name of the project set in +the top level ``CMakeLists.txt`` file is available from the +:variable:`CMAKE_PROJECT_NAME` variable, its description from +:variable:`CMAKE_PROJECT_DESCRIPTION` and its homepage URL from +:variable:`CMAKE_PROJECT_HOMEPAGE_URL`. .. note:: Call the :command:`cmake_minimum_required` command at the beginning diff --git a/Help/command/set_property.rst b/Help/command/set_property.rst index 5ed788e..c89e1ce 100644 --- a/Help/command/set_property.rst +++ b/Help/command/set_property.rst @@ -59,11 +59,17 @@ be one of the following: The required ``PROPERTY`` option is immediately followed by the name of the property to set. Remaining arguments are used to compose the -property value in the form of a semicolon-separated list. If the -``APPEND`` option is given the list is appended to any existing property -value. If the ``APPEND_STRING`` option is given the string is append to any -existing property value as string, i.e. it results in a longer string -and not a list of strings. +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 +appended to any existing property value as string, i.e. it results in a +longer string and not a list of strings. When using ``APPEND`` or +``APPEND_STRING`` with a property defined to support ``INHERITED`` +behavior (see :command:`define_property`), no inheriting occurs when +finding the initial value to append to. If the property is not already +directly set in the nominated scope, the command will behave as though +``APPEND`` or ``APPEND_STRING`` had not been given. See the :manual:`cmake-properties(7)` manual for a list of properties in each scope. diff --git a/Help/command/set_target_properties.rst b/Help/command/set_target_properties.rst index b894eac..7db952d 100644 --- a/Help/command/set_target_properties.rst +++ b/Help/command/set_target_properties.rst @@ -9,10 +9,12 @@ Targets can have properties that affect how they are built. PROPERTIES prop1 value1 prop2 value2 ...) -Set properties on a target. The syntax for the command is to list all -the files you want to change, and then provide the values you want to +Set properties on targets. The syntax for the command is to list all +the targets you want to change, and then provide the values you want to set next. You can use any prop value pair you want and extract it later with the :command:`get_property` or :command:`get_target_property` command. +See also the :command:`set_property(TARGET)` command. + See :ref:`Target Properties` for the list of properties known to CMake. diff --git a/Help/command/string.rst b/Help/command/string.rst index fb3893f..bb07d29 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -151,6 +151,20 @@ CONCAT Concatenate all the input arguments together and store the result in the named output variable. +JOIN +"""" + +:: + + string(JOIN <glue> <output variable> [<input>...]) + +Join all the input arguments together using the glue +string and store the result in the named output variable. + +To join list's elements, use preferably the ``JOIN`` operator +from :command:`list` command. This allows for the elements to have +special characters like ``;`` in them. + TOLOWER """"""" @@ -282,6 +296,18 @@ CONFIGURE Transform a string like :command:`configure_file` transforms a file. +MAKE_C_IDENTIFIER +""""""""""""""""" + +:: + + string(MAKE_C_IDENTIFIER <input string> <output variable>) + +Convert each non-alphanumeric character in the ``<input string>`` to an +underscore and store the result in the ``<output variable>``. If the first +character of the string is a digit, an underscore will also be prepended to +the result. + RANDOM """""" @@ -346,13 +372,6 @@ If no explicit ``<format string>`` is given it will default to: %Y-%m-%dT%H:%M:%S for local time. %Y-%m-%dT%H:%M:%SZ for UTC. - -:: - - string(MAKE_C_IDENTIFIER <input string> <output variable>) - -Write a string which can be used as an identifier in C. - .. note:: If the ``SOURCE_DATE_EPOCH`` environment variable is set, diff --git a/Help/command/target_compile_definitions.rst b/Help/command/target_compile_definitions.rst index 3709e7a..a740117 100644 --- a/Help/command/target_compile_definitions.rst +++ b/Help/command/target_compile_definitions.rst @@ -27,3 +27,13 @@ Arguments to ``target_compile_definitions`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. See the :manual:`cmake-buildsystem(7)` manual for more on defining buildsystem properties. + +Any leading ``-D`` on an item will be removed. Empty items are ignored. +For example, the following are all equivalent: + +.. code-block:: cmake + + target_compile_definitions(foo PUBLIC FOO) + target_compile_definitions(foo PUBLIC -DFOO) # -D removed + target_compile_definitions(foo PUBLIC "" FOO) # "" ignored + target_compile_definitions(foo PUBLIC -D FOO) # -D becomes "", then ignored diff --git a/Help/command/target_compile_options.rst b/Help/command/target_compile_options.rst index 3e7dc47..b7b4dc1 100644 --- a/Help/command/target_compile_options.rst +++ b/Help/command/target_compile_options.rst @@ -38,3 +38,5 @@ Arguments to ``target_compile_options`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. See the :manual:`cmake-buildsystem(7)` manual for more on defining buildsystem properties. + +.. include:: COMPILE_OPTIONS_SHELL.txt diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst index 2ec8744..fcc2c07 100644 --- a/Help/command/target_link_libraries.rst +++ b/Help/command/target_link_libraries.rst @@ -183,6 +183,70 @@ is not ``NEW``, they are also appended to the ``general`` (or without any keyword) are treated as if specified for both ``debug`` and ``optimized``. +Linking Object Libraries +^^^^^^^^^^^^^^^^^^^^^^^^ + +:ref:`Object Libraries` may be used as the ``<target>`` (first) argument +of ``target_link_libraries`` to specify dependencies of their sources +on other libraries. For example, the code + +.. code-block:: cmake + + add_library(A SHARED a.c) + target_compile_definitions(A PUBLIC A) + + add_library(obj OBJECT obj.c) + target_compile_definitions(obj PUBLIC OBJ) + target_link_libraries(obj PUBLIC A) + +compiles ``obj.c`` with ``-DA -DOBJ`` and establishes usage requirements +for ``obj`` that propagate to its dependents. + +Normal libraries and executables may link to :ref:`Object Libraries` +to get their objects and usage requirements. Continuing the above +example, the code + +.. code-block:: cmake + + add_library(B SHARED b.c) + target_link_libraries(B PUBLIC obj) + +compiles ``b.c`` with ``-DA -DOBJ``, creates shared library ``B`` +with object files from ``b.c`` and ``obj.c``, and links ``B`` to ``A``. +Furthermore, the code + +.. code-block:: cmake + + add_executable(main main.c) + target_link_libraries(main B) + +compiles ``main.c`` with ``-DA -DOBJ`` and links executable ``main`` +to ``B`` and ``A``. The object library's usage requirements are +propagated transitively through ``B``, but its object files are not. + +:ref:`Object Libraries` may "link" to other object libraries to get +usage requirements, but since they do not have a link step nothing +is done with their object files. Continuing from the above example, +the code: + +.. code-block:: cmake + + add_library(obj2 OBJECT obj2.c) + target_link_libraries(obj2 PUBLIC obj) + + add_executable(main2 main2.c) + target_link_libraries(main2 obj2) + +compiles ``obj2.c`` with ``-DA -DOBJ``, creates executable ``main2`` +with object files from ``main2.c`` and ``obj2.c``, and links ``main2`` +to ``A``. + +In other words, when :ref:`Object Libraries` appear in a target's +:prop_tgt:`INTERFACE_LINK_LIBRARIES` property they will be +treated as :ref:`Interface Libraries`, but when they appear in +a target's :prop_tgt:`LINK_LIBRARIES` property their object files +will be included in the link too. + Cyclic Dependencies of Static Libraries ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Help/generator/Visual Studio 8 2005.rst b/Help/generator/Visual Studio 8 2005.rst index acbbf01..947e7a5 100644 --- a/Help/generator/Visual Studio 8 2005.rst +++ b/Help/generator/Visual Studio 8 2005.rst @@ -1,23 +1,6 @@ Visual Studio 8 2005 -------------------- -Deprecated. Generates Visual Studio 8 2005 project files. - -.. note:: - This generator is deprecated and will be removed in a future version - of CMake. It will still be possible to build with VS 8 2005 tools - using the :generator:`Visual Studio 10 2010` (or above) generator - with :variable:`CMAKE_GENERATOR_TOOLSET` set to ``v80``, or by - using the :generator:`NMake Makefiles` generator. - -The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set -to specify a target platform name. - -For compatibility with CMake versions prior to 3.1, one may specify -a target platform name optionally at the end of this generator name: - -``Visual Studio 8 2005 Win64`` - Specify target platform ``x64``. - -``Visual Studio 8 2005 <WinCE-SDK>`` - Specify target platform matching a Windows CE SDK name. +Removed. This once generated Visual Studio 8 2005 project files, but +the generator has been removed since CMake 3.12. It is still possible to +build with VS 2005 tools using the :generator:`NMake Makefiles` generator. diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index b672ea6..50c4087 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -113,9 +113,9 @@ and it uniquely identifies the bundle. Object Libraries ^^^^^^^^^^^^^^^^ -The ``OBJECT`` library type is also not linked to. It defines a non-archival -collection of object files resulting from compiling the given source files. -The object files collection can be used as source inputs to other targets: +The ``OBJECT`` library type defines a non-archival collection of object files +resulting from compiling the given source files. The object files collection +may be used as source inputs to other targets: .. code-block:: cmake @@ -125,22 +125,31 @@ The object files collection can be used as source inputs to other targets: add_executable(test_exe $<TARGET_OBJECTS:archive> test.cpp) -``OBJECT`` libraries may not be used in the right hand side of -:command:`target_link_libraries`. They also may not be used as the ``TARGET`` -in a use of the :command:`add_custom_command(TARGET)` command signature. They -may be installed, and will be exported as an INTERFACE library. +The link (or archiving) step of those other targets will use the object +files collection in addition to those from their own sources. -Although object libraries may not be named directly in calls to -the :command:`target_link_libraries` command, they can be "linked" -indirectly by using an :ref:`Interface Library <Interface Libraries>` -whose :prop_tgt:`INTERFACE_SOURCES` target property is set to name -``$<TARGET_OBJECTS:objlib>``. +Alternatively, object libraries may be linked into other targets: -Although object libraries may not be used as the ``TARGET`` -in a use of the :command:`add_custom_command(TARGET)` command signature, -the list of objects can be used by :command:`add_custom_command(OUTPUT)` or -:command:`file(GENERATE)` by using ``$<TARGET_OBJECTS:objlib>``. +.. code-block:: cmake + + add_library(archive OBJECT archive.cpp zip.cpp lzma.cpp) + + add_library(archiveExtras STATIC extras.cpp) + target_link_libraries(archiveExtras PUBLIC archive) + + add_executable(test_exe test.cpp) + target_link_libraries(test_exe archive) + +The link (or archiving) step of those other targets will use the object +files from object libraries that are *directly* linked. Additionally, +usage requirements of the object libraries will be honored when compiling +sources in those other targets. Furthermore, those usage requirements +will propagate transitively to dependents of those other targets. +Object libraries may not be used as the ``TARGET`` in a use of the +:command:`add_custom_command(TARGET)` command signature. However, +the list of objects can be used by :command:`add_custom_command(OUTPUT)` +or :command:`file(GENERATE)` by using ``$<TARGET_OBJECTS:objlib>``. Build Specification and Usage Requirements ========================================== diff --git a/Help/manual/cmake-compile-features.7.rst b/Help/manual/cmake-compile-features.7.rst index e9495c6..634da10 100644 --- a/Help/manual/cmake-compile-features.7.rst +++ b/Help/manual/cmake-compile-features.7.rst @@ -331,9 +331,9 @@ and :prop_gbl:`compile features <CMAKE_CXX_KNOWN_FEATURES>` available from the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the versions specified for each: -* ``AppleClang``: Apple Clang for Xcode versions 4.4 though 6.2. -* ``Clang``: Clang compiler versions 2.9 through 3.4. -* ``GNU``: GNU compiler versions 4.4 through 5.0. +* ``AppleClang``: Apple Clang for Xcode versions 4.4 though 9.2. +* ``Clang``: Clang compiler versions 2.9 through 6.0. +* ``GNU``: GNU compiler versions 4.4 through 8.0. * ``MSVC``: Microsoft Visual Studio versions 2010 through 2017. * ``SunPro``: Oracle SolarisStudio versions 12.4 through 12.6. * ``Intel``: Intel compiler versions 12.1 through 17.0. @@ -344,7 +344,7 @@ the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the versions specified for each: * all compilers and versions listed above for C++. -* ``GNU``: GNU compiler versions 3.4 through 5.0. +* ``GNU``: GNU compiler versions 3.4 through 8.0. CMake is currently aware of the :prop_tgt:`C++ standards <CXX_STANDARD>` and their associated meta-features (e.g. ``cxx_std_11``) available from the @@ -366,4 +366,4 @@ CMake is currently aware of the :prop_tgt:`CUDA standards <CUDA_STANDARD>` from the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the versions specified for each: -* ``NVIDIA``: NVIDIA nvcc compiler 7.5 though 8.0. +* ``NVIDIA``: NVIDIA nvcc compiler 7.5 though 9.1. diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst index cd509ac..32e8cfc 100644 --- a/Help/manual/cmake-developer.7.rst +++ b/Help/manual/cmake-developer.7.rst @@ -644,6 +644,8 @@ Documentation`_ section above. +.. _`CMake Developer Standard Variable Names`: + Standard Variable Names ^^^^^^^^^^^^^^^^^^^^^^^ @@ -943,7 +945,7 @@ populated: 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 +so that the 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 diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 0f6d4cf..0e73bd2 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -57,6 +57,10 @@ Available logical expressions are: ``1`` if ``a`` is STREQUAL ``b``, else ``0`` ``$<EQUAL:a,b>`` ``1`` if ``a`` is EQUAL ``b`` in a numeric comparison, else ``0`` +``$<IN_LIST:a,b>`` + ``1`` if ``a`` is IN_LIST ``b``, else ``0`` +``$<TARGET_EXISTS:tgt>`` + ``1`` if ``tgt`` is an existed target name, else ``0``. ``$<CONFIG:cfg>`` ``1`` if config is ``cfg``, else ``0``. This is a case-insensitive comparison. The mapping in :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` is also considered by @@ -270,6 +274,9 @@ Available output expressions are: Marks ``...`` as being the name of a target. This is required if exporting targets to multiple dependent export sets. The ``...`` must be a literal name of a target- it may not contain generator expressions. +``$<TARGET_NAME_IF_EXISTS:...>`` + Expands to the ``...`` if the given target exists, an empty string + otherwise. ``$<LINK_ONLY:...>`` Content of ``...`` except when evaluated in a link interface while propagating :ref:`Target Usage Requirements`, in which case it is the @@ -289,7 +296,8 @@ Available output expressions are: ``$<UPPER_CASE:...>`` Content of ``...`` converted to upper case. ``$<MAKE_C_IDENTIFIER:...>`` - Content of ``...`` converted to a C identifier. + Content of ``...`` converted to a C identifier. The conversion follows the + same behavior as :command:`string(MAKE_C_IDENTIFIER)`. ``$<TARGET_OBJECTS:objLib>`` List of objects resulting from build of ``objLib``. ``objLib`` must be an object of type ``OBJECT_LIBRARY``. diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index 694bae5..070c6ed 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -196,6 +196,9 @@ All Modules /module/FindPostgreSQL /module/FindProducer /module/FindProtobuf + /module/FindPython + /module/FindPython2 + /module/FindPython3 /module/FindPythonInterp /module/FindPythonLibs /module/FindQt3 diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 96d5c7d..7e2255d 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -51,6 +51,15 @@ The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used to determine whether to report an error on use of deprecated macros or functions. +Policies Introduced by CMake 3.12 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0074: find_package uses PackageName_ROOT variables. </policy/CMP0074> + CMP0073: Do not produce legacy _LIB_DEPENDS cache entries. </policy/CMP0073> + Policies Introduced by CMake 3.11 ================================= diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 00a932f..7ace270 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -84,6 +84,7 @@ Properties on Directories /prop_dir/RULE_LAUNCH_LINK /prop_dir/SOURCE_DIR /prop_dir/SUBDIRECTORIES + /prop_dir/TESTS /prop_dir/TEST_INCLUDE_FILES /prop_dir/VARIABLES /prop_dir/VS_GLOBAL_SECTION_POST_section @@ -175,6 +176,7 @@ Properties on Targets /prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD_CONFIG /prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD /prop_tgt/EXPORT_NAME + /prop_tgt/EXPORT_PROPERTIES /prop_tgt/FOLDER /prop_tgt/Fortran_FORMAT /prop_tgt/Fortran_MODULE_DIRECTORY @@ -295,6 +297,7 @@ Properties on Targets /prop_tgt/VISIBILITY_INLINES_HIDDEN /prop_tgt/VS_CONFIGURATION_TYPE /prop_tgt/VS_DEBUGGER_WORKING_DIRECTORY + /prop_tgt/VS_DEBUGGER_COMMAND /prop_tgt/VS_DESKTOP_EXTENSIONS_VERSION /prop_tgt/VS_DOTNET_REFERENCE_refname /prop_tgt/VS_DOTNET_REFERENCEPROP_refname_TAG_tagname @@ -347,6 +350,7 @@ Properties on Tests /prop_test/LABELS /prop_test/MEASUREMENT /prop_test/PASS_REGULAR_EXPRESSION + /prop_test/PROCESSOR_AFFINITY /prop_test/PROCESSORS /prop_test/REQUIRED_FILES /prop_test/RESOURCE_LOCK diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 3ac5123..c1b0316 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -67,6 +67,7 @@ Variables that Provide Information /variable/CMAKE_PARENT_LIST_FILE /variable/CMAKE_PATCH_VERSION /variable/CMAKE_PROJECT_DESCRIPTION + /variable/CMAKE_PROJECT_HOMEPAGE_URL /variable/CMAKE_PROJECT_NAME /variable/CMAKE_RANLIB /variable/CMAKE_ROOT @@ -97,6 +98,8 @@ Variables that Provide Information /variable/CMAKE_XCODE_GENERATE_SCHEME /variable/CMAKE_XCODE_PLATFORM_TOOLSET /variable/PROJECT-NAME_BINARY_DIR + /variable/PROJECT-NAME_DESCRIPTION + /variable/PROJECT-NAME_HOMEPAGE_URL /variable/PROJECT-NAME_SOURCE_DIR /variable/PROJECT-NAME_VERSION /variable/PROJECT-NAME_VERSION_MAJOR @@ -105,6 +108,7 @@ Variables that Provide Information /variable/PROJECT-NAME_VERSION_TWEAK /variable/PROJECT_BINARY_DIR /variable/PROJECT_DESCRIPTION + /variable/PROJECT_HOMEPAGE_URL /variable/PROJECT_NAME /variable/PROJECT_SOURCE_DIR /variable/PROJECT_VERSION @@ -178,6 +182,7 @@ Variables that Change Behavior /variable/CMAKE_STAGING_PREFIX /variable/CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS /variable/CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE + /variable/CMAKE_SUPPRESS_REGENERATION /variable/CMAKE_SYSROOT /variable/CMAKE_SYSROOT_COMPILE /variable/CMAKE_SYSROOT_LINK @@ -234,6 +239,7 @@ Variables that Describe the System /variable/MSVC80 /variable/MSVC90 /variable/MSVC_IDE + /variable/MSVC_TOOLSET_VERSION /variable/MSVC_VERSION /variable/UNIX /variable/WIN32 @@ -300,6 +306,7 @@ Variables that Control the Build /variable/CMAKE_EXE_LINKER_FLAGS_CONFIG /variable/CMAKE_EXE_LINKER_FLAGS_CONFIG_INIT /variable/CMAKE_EXE_LINKER_FLAGS_INIT + /variable/CMAKE_FOLDER /variable/CMAKE_Fortran_FORMAT /variable/CMAKE_Fortran_MODULE_DIRECTORY /variable/CMAKE_GNUtoMS diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index a04c403..75af22e 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -368,15 +368,17 @@ for "SubprojectB"). Build and Test Mode =================== -CTest provides a command-line signature to to configure (i.e. run cmake on), -build, and or execute a test:: +CTest provides a command-line signature to configure (i.e. run cmake on), +build, and/or execute a test:: ctest --build-and-test <path-to-source> <path-to-build> - --build-generator <generator> [<options>...] [-- <build-options>...] - [--test-command <test>] + --build-generator <generator> + [<options>...] + [--build-options <opts>...] + [--test-command <command> [<args>...]] The configure and test steps are optional. The arguments to this command line -are the source and binary directories. The ``--build-generator`` option *must* +are the source and binary directories. The ``--build-generator`` option *must* be provided to use ``--build-and-test``. If ``--test-command`` is specified then that will be run after the build is complete. Other options that affect this mode include: @@ -425,13 +427,15 @@ this mode include: should be used. e.g. Debug/Release/etc. ``--build-options`` - Add extra options to the build step. - - This option must be the last option with the exception of - ``--test-command`` + Additional options for configuring the build (i.e. for CMake, not for + the build tool). Note that if this is specified, the ``--build-options`` + keyword and its arguments must be the last option given on the command + line, with the possible exception of ``--test-command``. ``--test-command`` - The test to run with the ``--build-and-test`` option. + The command to run as the test step with the ``--build-and-test`` option. + All arguments following this keyword will be assumed to be part of the + test command line, so it must be the last option given. ``--test-timeout`` The time limit in seconds diff --git a/Help/module/FindPython.rst b/Help/module/FindPython.rst new file mode 100644 index 0000000..057a350 --- /dev/null +++ b/Help/module/FindPython.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindPython.cmake diff --git a/Help/module/FindPython2.rst b/Help/module/FindPython2.rst new file mode 100644 index 0000000..1696bed --- /dev/null +++ b/Help/module/FindPython2.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindPython2.cmake diff --git a/Help/module/FindPython3.rst b/Help/module/FindPython3.rst new file mode 100644 index 0000000..e530ab8 --- /dev/null +++ b/Help/module/FindPython3.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindPython3.cmake diff --git a/Help/policy/CMP0073.rst b/Help/policy/CMP0073.rst new file mode 100644 index 0000000..9bfa0e9 --- /dev/null +++ b/Help/policy/CMP0073.rst @@ -0,0 +1,25 @@ +CMP0073 +------- + +Do not produce legacy ``_LIB_DEPENDS`` cache entries. + +Ancient CMake versions once used ``<tgt>_LIB_DEPENDS`` cache entries to +propagate library link dependencies. This has long been done by other +means, leaving the :command:`export_library_dependencies` command as the +only user of these values. That command has long been disallowed by +policy :policy:`CMP0033`, but the ``<tgt>_LIB_DEPENDS`` cache entries +were left for compatibility with possible non-standard uses by projects. + +CMake 3.12 and above now prefer to not produce these cache entries +at all. This policy provides compatibility with projects that have +not been updated to avoid using them. + +The ``OLD`` behavior for this policy is to set ``<tgt>_LIB_DEPENDS`` cache +entries. The ``NEW`` behavior for this policy is to not set them. + +This policy was introduced in CMake version 3.12. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +Unlike most policies, CMake version |release| does *not* warn +when this policy is not set and simply uses ``OLD`` behavior. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0074.rst b/Help/policy/CMP0074.rst new file mode 100644 index 0000000..ffac4a7 --- /dev/null +++ b/Help/policy/CMP0074.rst @@ -0,0 +1,22 @@ +CMP0074 +------- + +:command:`find_package` uses ``PackageName_ROOT`` variables. + +In CMake 3.12 and above the ``find_package(PackageName)`` command now searches +a prefix specified by a ``PackageName_ROOT`` CMake or environment variable. +Package roots are maintained as a stack so nested calls to all ``find_*`` +commands inside find modules also search the roots as prefixes. This policy +provides compatibility with projects that have not been updated to avoid using +``PackageName_ROOT`` variables for other purposes. + +The ``OLD`` behavior for this policy is to ignore ``PackageName_ROOT`` +variables. The ``NEW`` behavior for this policy is to use ``PackageName_ROOT`` +variables. + +This policy was introduced in CMake version 3.12. CMake version +|release| warns when the policy is not set and uses ``OLD`` behavior. +Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` +explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/prop_dir/TESTS.rst b/Help/prop_dir/TESTS.rst new file mode 100644 index 0000000..c6e1d88 --- /dev/null +++ b/Help/prop_dir/TESTS.rst @@ -0,0 +1,7 @@ +TESTS +----- + +List of tests. + +This read-only property holds a :ref:`;-list <CMake Language Lists>` of tests +defined so far by the :command:`add_test` command. diff --git a/Help/prop_dir/VS_GLOBAL_SECTION_POST_section.rst b/Help/prop_dir/VS_GLOBAL_SECTION_POST_section.rst index a316abe..814bd5f 100644 --- a/Help/prop_dir/VS_GLOBAL_SECTION_POST_section.rst +++ b/Help/prop_dir/VS_GLOBAL_SECTION_POST_section.rst @@ -17,7 +17,7 @@ pairs. Each such pair will be transformed into an entry in the solution global section. Whitespace around key and value is ignored. List elements which do not contain an equal sign are skipped. -This property only works for Visual Studio 8 and above; it is ignored +This property only works for Visual Studio 9 and above; it is ignored on other generators. The property only applies when set on a directory whose CMakeLists.txt contains a project() command. diff --git a/Help/prop_dir/VS_GLOBAL_SECTION_PRE_section.rst b/Help/prop_dir/VS_GLOBAL_SECTION_PRE_section.rst index 200e8e6..f70e9f1 100644 --- a/Help/prop_dir/VS_GLOBAL_SECTION_PRE_section.rst +++ b/Help/prop_dir/VS_GLOBAL_SECTION_PRE_section.rst @@ -17,6 +17,6 @@ pairs. Each such pair will be transformed into an entry in the solution global section. Whitespace around key and value is ignored. List elements which do not contain an equal sign are skipped. -This property only works for Visual Studio 8 and above; it is ignored +This property only works for Visual Studio 9 and above; it is ignored on other generators. The property only applies when set on a directory whose CMakeLists.txt contains a project() command. diff --git a/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst index 2ad8157..262a67c 100644 --- a/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst +++ b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst @@ -26,6 +26,9 @@ The features known to this version of CMake are: ``cxx_std_17`` Compiler mode is aware of C++ 17. +``cxx_std_20`` + Compiler mode is aware of C++ 20. + ``cxx_aggregate_default_initializers`` Aggregate default initializers, as defined in N3605_. diff --git a/Help/prop_test/PROCESSORS.rst b/Help/prop_test/PROCESSORS.rst index a1211fb..a927c10 100644 --- a/Help/prop_test/PROCESSORS.rst +++ b/Help/prop_test/PROCESSORS.rst @@ -2,6 +2,7 @@ PROCESSORS ---------- Set to specify how many process slots this test requires. +If not set, the default is ``1`` processor. Denotes the number of processors that this test will require. This is typically used for MPI tests, and should be used in conjunction with @@ -11,3 +12,5 @@ This will also be used to display a weighted test timing result in label and subproject summaries in the command line output of :manual:`ctest(1)`. The wall clock time for the test run will be multiplied by this property to give a better idea of how much cpu resource CTest allocated for the test. + +See also the :prop_test:`PROCESSOR_AFFINITY` test property. diff --git a/Help/prop_test/PROCESSOR_AFFINITY.rst b/Help/prop_test/PROCESSOR_AFFINITY.rst new file mode 100644 index 0000000..38ec179 --- /dev/null +++ b/Help/prop_test/PROCESSOR_AFFINITY.rst @@ -0,0 +1,11 @@ +PROCESSOR_AFFINITY +------------------ + +Set to a true value to ask CTest to launch the test process with CPU affinity +for a fixed set of processors. If enabled and supported for the current +platform, CTest will choose a set of processors to place in the CPU affinity +mask when launching the test process. The number of processors in the set is +determined by the :prop_test:`PROCESSORS` test property or the number of +processors available to CTest, whichever is smaller. The set of processors +chosen will be disjoint from the processors assigned to other concurrently +running tests that also have the ``PROCESSOR_AFFINITY`` property enabled. diff --git a/Help/prop_test/WORKING_DIRECTORY.rst b/Help/prop_test/WORKING_DIRECTORY.rst index 5222a19..92a0409 100644 --- a/Help/prop_test/WORKING_DIRECTORY.rst +++ b/Help/prop_test/WORKING_DIRECTORY.rst @@ -3,5 +3,7 @@ WORKING_DIRECTORY The directory from which the test executable will be called. -If this is not set it is called from the directory the test executable -is located in. +If this is not set, the test will be run with the working directory set to the +binary directory associated with where the test was created (i.e. the +:variable:`CMAKE_CURRENT_BINARY_DIR` for where :command:`add_test` was +called). diff --git a/Help/prop_tgt/CXX_STANDARD.rst b/Help/prop_tgt/CXX_STANDARD.rst index 0762033..ccc0147 100644 --- a/Help/prop_tgt/CXX_STANDARD.rst +++ b/Help/prop_tgt/CXX_STANDARD.rst @@ -9,7 +9,7 @@ flag such as ``-std=gnu++11`` to the compile line. For compilers that have no notion of a standard level, such as Microsoft Visual C++ before 2015 Update 3, this has no effect. -Supported values are ``98``, ``11``, ``14``, and ``17``. +Supported values are ``98``, ``11``, ``14``, ``17``, and ``20``. If the value requested does not result in a compile flag being added for the compiler in use, a previous standard flag will be added instead. This diff --git a/Help/prop_tgt/DEPLOYMENT_REMOTE_DIRECTORY.rst b/Help/prop_tgt/DEPLOYMENT_REMOTE_DIRECTORY.rst index 1ff5bf0..368768a 100644 --- a/Help/prop_tgt/DEPLOYMENT_REMOTE_DIRECTORY.rst +++ b/Help/prop_tgt/DEPLOYMENT_REMOTE_DIRECTORY.rst @@ -3,8 +3,8 @@ DEPLOYMENT_REMOTE_DIRECTORY Set the WinCE project ``RemoteDirectory`` in ``DeploymentTool`` and ``RemoteExecutable`` in ``DebuggerTool`` in ``.vcproj`` files generated -by the :generator:`Visual Studio 9 2008` and :generator:`Visual Studio 8 2005` -generators. This is useful when you want to debug on remote WinCE device. +by the :generator:`Visual Studio 9 2008` generator. +This is useful when you want to debug on remote WinCE device. For example: .. code-block:: cmake diff --git a/Help/prop_tgt/EXPORT_PROPERTIES.rst b/Help/prop_tgt/EXPORT_PROPERTIES.rst new file mode 100644 index 0000000..bcf47a6 --- /dev/null +++ b/Help/prop_tgt/EXPORT_PROPERTIES.rst @@ -0,0 +1,14 @@ +EXPORT_PROPERTIES +----------------- + +List additional properties to export for a target. + +This property contains a list of property names that should be exported by +the :command:`install(EXPORT)` and :command:`export` commands. By default +only a limited number of properties are exported. This property can be used +to additionally export other properties as well. + +Properties starting with ``INTERFACE_`` or ``IMPORTED_`` are not allowed as +they are reserved for internal CMake use. + +Properties containing generator expressions are also not allowed. diff --git a/Help/prop_tgt/FOLDER.rst b/Help/prop_tgt/FOLDER.rst index bfe4e8e..0121125 100644 --- a/Help/prop_tgt/FOLDER.rst +++ b/Help/prop_tgt/FOLDER.rst @@ -8,3 +8,6 @@ IDEs like Visual Studio. Targets with the same FOLDER property value will appear next to each other in a folder of that name. To nest folders, use FOLDER values such as 'GUI/Dialogs' with '/' characters separating folder levels. + +This property is initialized by the value of the variable +:variable:`CMAKE_FOLDER` if it is set when a target is created. diff --git a/Help/prop_tgt/INSTALL_NAME_DIR.rst b/Help/prop_tgt/INSTALL_NAME_DIR.rst index a67ec15..34348bb 100644 --- a/Help/prop_tgt/INSTALL_NAME_DIR.rst +++ b/Help/prop_tgt/INSTALL_NAME_DIR.rst @@ -6,3 +6,7 @@ Mac OSX directory name for installed targets. INSTALL_NAME_DIR is a string specifying the directory portion of the "install_name" field of shared libraries on Mac OSX to use in the installed targets. + +This property is initialized by the value of the variable +:variable:`CMAKE_INSTALL_NAME_DIR` if it is set when a target is +created. diff --git a/Help/prop_tgt/VS_DEBUGGER_COMMAND.rst b/Help/prop_tgt/VS_DEBUGGER_COMMAND.rst new file mode 100644 index 0000000..f898750 --- /dev/null +++ b/Help/prop_tgt/VS_DEBUGGER_COMMAND.rst @@ -0,0 +1,9 @@ +VS_DEBUGGER_COMMAND +------------------- + +Sets the local debugger command for Visual Studio C++ targets. +This is defined in ``<LocalDebuggerCommand>`` in the Visual Studio +project file. + +This property only works for Visual Studio 2010 and above; +it is ignored on other generators. diff --git a/Help/prop_tgt/VS_DEBUGGER_WORKING_DIRECTORY.rst b/Help/prop_tgt/VS_DEBUGGER_WORKING_DIRECTORY.rst index 0af85cb..fb0389e 100644 --- a/Help/prop_tgt/VS_DEBUGGER_WORKING_DIRECTORY.rst +++ b/Help/prop_tgt/VS_DEBUGGER_WORKING_DIRECTORY.rst @@ -4,3 +4,6 @@ VS_DEBUGGER_WORKING_DIRECTORY Sets the local debugger working directory for Visual Studio C++ targets. This is defined in ``<LocalDebuggerWorkingDirectory>`` in the Visual Studio project file. + +This property only works for Visual Studio 2010 and above; +it is ignored on other generators. 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/FindPython-new-implementation.rst b/Help/release/dev/FindPython-new-implementation.rst new file mode 100644 index 0000000..22051d0 --- /dev/null +++ b/Help/release/dev/FindPython-new-implementation.rst @@ -0,0 +1,5 @@ +FindPython(2|3) +--------------- + +* The new :module:`FindPython3` and :module:`FindPython2` modules, as well as + :module:`FindPython`, provide a new way to locate python environments. diff --git a/Help/release/dev/UseSWIG-Multiple-Behaviors.rst b/Help/release/dev/UseSWIG-Multiple-Behaviors.rst new file mode 100644 index 0000000..043ba50 --- /dev/null +++ b/Help/release/dev/UseSWIG-Multiple-Behaviors.rst @@ -0,0 +1,6 @@ +UseSWIG-multiple-behaviors +-------------------------- + +* The :module:`UseSWIG` module learned to manage multiple behaviors through + ``UseSWIG_MODULE_VERSION`` variable to ensure legacy support as well as more + robust handling of ``SWIG`` advanced features (like ``%template``). diff --git a/Help/release/dev/UseSWIG-fix-library-prefix.rst b/Help/release/dev/UseSWIG-fix-library-prefix.rst new file mode 100644 index 0000000..7ff0f49 --- /dev/null +++ b/Help/release/dev/UseSWIG-fix-library-prefix.rst @@ -0,0 +1,6 @@ +UseSWIG-fix-library-prefix +-------------------------- + +* The :module:`UseSWIG` module :command:`swig_add_library` command + (and legacy ``swig_add_module`` command) now set the prefix of + Java modules to ``""`` for MINGW, MSYS, and CYGWIN environments. diff --git a/Help/release/dev/UseSWIG-modernize-module.rst b/Help/release/dev/UseSWIG-modernize-module.rst new file mode 100644 index 0000000..925c119 --- /dev/null +++ b/Help/release/dev/UseSWIG-modernize-module.rst @@ -0,0 +1,6 @@ +UseSWIG-modernize-module +------------------------ + +* The :module:`UseSWIG` gained a whole refresh and is now more consistent with + standard CMake commands to generate libraries and is fully configurable through + properties. diff --git a/Help/release/dev/avoid-LIB_DEPENDS.rst b/Help/release/dev/avoid-LIB_DEPENDS.rst new file mode 100644 index 0000000..b89d8f9 --- /dev/null +++ b/Help/release/dev/avoid-LIB_DEPENDS.rst @@ -0,0 +1,5 @@ +avoid-LIB_DEPENDS +----------------- + +* CMake no longer produces ``<tgt>_LIB_DEPENDS`` cache entries + for library targets. See policy :policy:`CMP0073`. diff --git a/Help/release/dev/compile-options-shell.rst b/Help/release/dev/compile-options-shell.rst new file mode 100644 index 0000000..3f83e0c --- /dev/null +++ b/Help/release/dev/compile-options-shell.rst @@ -0,0 +1,6 @@ +compile-options-shell +--------------------- + +* :command:`target_compile_options` and :command:`add_compile_options` + commands gained a ``SHELL:`` prefix to specify a group of related + options using shell-like quoting. diff --git a/Help/release/dev/ctest-affinity.rst b/Help/release/dev/ctest-affinity.rst new file mode 100644 index 0000000..f4f72a5 --- /dev/null +++ b/Help/release/dev/ctest-affinity.rst @@ -0,0 +1,6 @@ +ctest-affinity +-------------- + +* A :prop_test:`PROCESSOR_AFFINITY` test property was added to request + that CTest run a test with CPU affinity for a set of processors + disjoint from other concurrently running tests with the property set. diff --git a/Help/release/dev/curl-target.rst b/Help/release/dev/curl-target.rst new file mode 100644 index 0000000..dc65f64 --- /dev/null +++ b/Help/release/dev/curl-target.rst @@ -0,0 +1,4 @@ +curl-target +----------- + +* The :module:`FindCURL` module now provides imported targets. diff --git a/Help/release/dev/directory-property-TESTS.rst b/Help/release/dev/directory-property-TESTS.rst new file mode 100644 index 0000000..9de2531 --- /dev/null +++ b/Help/release/dev/directory-property-TESTS.rst @@ -0,0 +1,5 @@ +directory-property-TESTS +------------------------ + +* The :prop_dir:`TESTS` directory property was added to hold the list of tests defined by + command :command:`add_test`. diff --git a/Help/release/dev/export-properties.rst b/Help/release/dev/export-properties.rst new file mode 100644 index 0000000..9b20799 --- /dev/null +++ b/Help/release/dev/export-properties.rst @@ -0,0 +1,6 @@ +EXPORT_PROPERTIES +----------------- + +* An :prop_tgt:`EXPORT_PROPERTIES` target property was added to specify a + custom list of target properties to include in targets exported by the + :command:`install(EXPORT)` and :command:`export` commands. diff --git a/Help/release/dev/features-c++20.rst b/Help/release/dev/features-c++20.rst new file mode 100644 index 0000000..f7d050b --- /dev/null +++ b/Help/release/dev/features-c++20.rst @@ -0,0 +1,6 @@ +features-c++20 +-------------- + +* The :manual:`Compile Features <cmake-compile-features(7)>` functionality + is now aware of C++ 20. No specific features are yet enumerated besides + the ``cxx_std_20`` meta-feature. diff --git a/Help/release/dev/features-msvc-c.rst b/Help/release/dev/features-msvc-c.rst new file mode 100644 index 0000000..0c55544 --- /dev/null +++ b/Help/release/dev/features-msvc-c.rst @@ -0,0 +1,5 @@ +features-msvc-c +--------------- + +* The :manual:`Compile Features <cmake-compile-features(7)>` functionality + is now aware of the availability of C features in MSVC since VS 2010. diff --git a/Help/release/dev/file_cmd_touch.rst b/Help/release/dev/file_cmd_touch.rst new file mode 100644 index 0000000..b1b1e3c --- /dev/null +++ b/Help/release/dev/file_cmd_touch.rst @@ -0,0 +1,6 @@ +file_cmd_touch +------------------ + +* The :command:`file(TOUCH)` and :command:`file(TOUCH_NOCREATE)` commands + were added to expose TOUCH functionality without having to use CMake's + command-line tool mode with :command:`execute_process`. diff --git a/Help/release/dev/find-package_root-restore.rst b/Help/release/dev/find-package_root-restore.rst new file mode 100644 index 0000000..3e6b69e --- /dev/null +++ b/Help/release/dev/find-package_root-restore.rst @@ -0,0 +1,8 @@ +find-package_root-restore +------------------------- + +* The :command:`find_package` command now searches a prefix specified by + a ``PackageName_ROOT`` CMake or environment variable. Package roots are + maintained as a stack so nested calls to all ``find_*`` commands inside + find modules also search the roots as prefixes. + See policy :policy:`CMP0074`. diff --git a/Help/release/dev/genex-IN_LIST-logical-operator.rst b/Help/release/dev/genex-IN_LIST-logical-operator.rst new file mode 100644 index 0000000..28fa7ce --- /dev/null +++ b/Help/release/dev/genex-IN_LIST-logical-operator.rst @@ -0,0 +1,5 @@ +genex-IN_LIST-logical-operator +------------------------------ + +* A new ``$<IN_LIST:...>`` :manual:`generator expression <cmake-generator-expressions(7)>` + has been added. diff --git a/Help/release/dev/genex-TARGET_EXISTS.rst b/Help/release/dev/genex-TARGET_EXISTS.rst new file mode 100644 index 0000000..f305522 --- /dev/null +++ b/Help/release/dev/genex-TARGET_EXISTS.rst @@ -0,0 +1,6 @@ +genex-TARGET_EXISTS +------------------- + +* A new ``$<TARGET_EXISTS:...>`` + :manual:`generator expression <cmake-generator-expressions(7)>` + has been added. diff --git a/Help/release/dev/genex-TARGET_NAME_IF_EXISTS.rst b/Help/release/dev/genex-TARGET_NAME_IF_EXISTS.rst new file mode 100644 index 0000000..416e812 --- /dev/null +++ b/Help/release/dev/genex-TARGET_NAME_IF_EXISTS.rst @@ -0,0 +1,6 @@ +genex-TARGET_NAME_IF_EXISTS +--------------------------- + +* A new ``$<TARGET_NAME_IF_EXISTS:...>`` + :manual:`generator expression <cmake-generator-expressions(7)>` + has been added. diff --git a/Help/release/dev/glob_configure_depends.rst b/Help/release/dev/glob_configure_depends.rst new file mode 100644 index 0000000..147e44a --- /dev/null +++ b/Help/release/dev/glob_configure_depends.rst @@ -0,0 +1,6 @@ +glob_configure_depends +---------------------- + +* The :command:`file(GLOB)` and :command:`file(GLOB_RECURSE)` commands + learned a new flag ``CONFIGURE_DEPENDS`` which enables expression of + build system dependency on globbed directory's contents. diff --git a/Help/release/dev/libxml2-target.rst b/Help/release/dev/libxml2-target.rst new file mode 100644 index 0000000..f9933d7 --- /dev/null +++ b/Help/release/dev/libxml2-target.rst @@ -0,0 +1,4 @@ +libxml2-target +-------------- + +* The :module:`FindLibXml2` module now provides imported targets. diff --git a/Help/release/dev/list-join.rst b/Help/release/dev/list-join.rst new file mode 100644 index 0000000..0756b60 --- /dev/null +++ b/Help/release/dev/list-join.rst @@ -0,0 +1,5 @@ +list-join +--------- + +* The :command:`list` command learned a ``JOIN`` sub-command + to concatenate list's elements separated by a glue string. diff --git a/Help/release/dev/list-sublist.rst b/Help/release/dev/list-sublist.rst new file mode 100644 index 0000000..7ad225b --- /dev/null +++ b/Help/release/dev/list-sublist.rst @@ -0,0 +1,5 @@ +list-sublist +------------ + +* The :command:`list` command learned a ``SUBLIST`` sub-command + to get a sublist of the list. diff --git a/Help/release/dev/msvc-toolset-version-variable.rst b/Help/release/dev/msvc-toolset-version-variable.rst new file mode 100644 index 0000000..28ba0b9 --- /dev/null +++ b/Help/release/dev/msvc-toolset-version-variable.rst @@ -0,0 +1,6 @@ +msvc-toolset-version-variable +----------------------------- + +* A :variable:`MSVC_TOOLSET_VERSION` variable was added to provide the + MSVC toolset version associated with the current MSVC compiler version + in :variable:`MSVC_VERSION`. diff --git a/Help/release/dev/object-library-linking.rst b/Help/release/dev/object-library-linking.rst new file mode 100644 index 0000000..131430f --- /dev/null +++ b/Help/release/dev/object-library-linking.rst @@ -0,0 +1,6 @@ +object-library-linking +---------------------- + +* The :command:`target_link_libraries` command now supports + :ref:`Object Libraries`. Linking to an object library uses its object + files in direct dependents and also propagates usage requirements. diff --git a/Help/release/dev/policy-version-range.rst b/Help/release/dev/policy-version-range.rst new file mode 100644 index 0000000..b2d1f17 --- /dev/null +++ b/Help/release/dev/policy-version-range.rst @@ -0,0 +1,8 @@ +policy-version-range +-------------------- + +* The :command:`cmake_minimum_required` and :command:`cmake_policy(VERSION)` + commands now accept a version range using the form ``<min>[...<max>]``. + The ``<min>`` version is required but policies are set based on the + ``<max>`` version. This allows projects to specify a range of versions + for which they have been updated and avoid explicit policy settings. diff --git a/Help/release/dev/project-homepage.rst b/Help/release/dev/project-homepage.rst new file mode 100644 index 0000000..25799a4 --- /dev/null +++ b/Help/release/dev/project-homepage.rst @@ -0,0 +1,7 @@ +project-homepage +---------------- + +* The :command:`project` command learned an optional ``HOMEPAGE_URL`` + parameter which has the effect of setting variables like + :variable:`PROJECT_HOMEPAGE_URL`, :variable:`<PROJECT-NAME>_HOMEPAGE_URL` + and :variable:`CMAKE_PROJECT_HOMEPAGE_URL`. diff --git a/Help/release/dev/remove-vs8-generator.rst b/Help/release/dev/remove-vs8-generator.rst new file mode 100644 index 0000000..c39529a --- /dev/null +++ b/Help/release/dev/remove-vs8-generator.rst @@ -0,0 +1,4 @@ +remove-vs8-generator +-------------------- + +* The :generator:`Visual Studio 8 2005` generator has been removed. diff --git a/Help/release/dev/string-join.rst b/Help/release/dev/string-join.rst new file mode 100644 index 0000000..5cca711 --- /dev/null +++ b/Help/release/dev/string-join.rst @@ -0,0 +1,5 @@ +string-join +----------- + +* The :command:`string` command learned a ``JOIN`` sub-command + to concatenate input strings separated by a glue string. diff --git a/Help/release/dev/variable-CMAKE_FOLDER.rst b/Help/release/dev/variable-CMAKE_FOLDER.rst new file mode 100644 index 0000000..8064edd --- /dev/null +++ b/Help/release/dev/variable-CMAKE_FOLDER.rst @@ -0,0 +1,5 @@ +variable-CMAKE_FOLDER +--------------------- + +* The :variable:`CMAKE_FOLDER` variable was added to initialize the + :prop_tgt:`FOLDER` property on all targets. diff --git a/Help/release/dev/variable-CMAKE_SUPPRESS_REGENERATION.rst b/Help/release/dev/variable-CMAKE_SUPPRESS_REGENERATION.rst new file mode 100644 index 0000000..dfe678c --- /dev/null +++ b/Help/release/dev/variable-CMAKE_SUPPRESS_REGENERATION.rst @@ -0,0 +1,6 @@ +variable-CMAKE_SUPPRESS_REGENERATION +------------------------------------ + +* The :variable:`CMAKE_SUPPRESS_REGENERATION` variable was extended to support the + :generator:`Ninja` and :ref:`Makefile Generators`. +* The :variable:`CMAKE_SUPPRESS_REGENERATION` variable is now documented. diff --git a/Help/release/dev/vs-debugger-config.rst b/Help/release/dev/vs-debugger-config.rst new file mode 100644 index 0000000..bddae0c --- /dev/null +++ b/Help/release/dev/vs-debugger-config.rst @@ -0,0 +1,6 @@ +vs-debugger-configuration +------------------------- + +* For the :ref:`Visual Studio Generators` for VS 2010 and above + the debugging command line can be set using a new + :prop_tgt:`VS_DEBUGGER_COMMAND` target property. diff --git a/Help/release/dev/wcdh-raw-features.rst b/Help/release/dev/wcdh-raw-features.rst new file mode 100644 index 0000000..bdc7b62 --- /dev/null +++ b/Help/release/dev/wcdh-raw-features.rst @@ -0,0 +1,6 @@ +wcdh-raw-features +----------------- + +* The :module:`WriteCompilerDetectionHeader` module now supports the + ``BARE_FEATURES`` argument which allows to add a compatibility define for + the exact keyword of a new language feature. diff --git a/Help/release/index.rst b/Help/release/index.rst index 7375faf..552922e 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -7,6 +7,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 ======== diff --git a/Help/variable/CMAKE_CFG_INTDIR.rst b/Help/variable/CMAKE_CFG_INTDIR.rst index c36599a..af82f75 100644 --- a/Help/variable/CMAKE_CFG_INTDIR.rst +++ b/Help/variable/CMAKE_CFG_INTDIR.rst @@ -12,7 +12,7 @@ Example values: :: - $(ConfigurationName) = Visual Studio 8, 9 + $(ConfigurationName) = Visual Studio 9 $(Configuration) = Visual Studio 10 $(CONFIGURATION) = Xcode . = Make-based tools diff --git a/Help/variable/CMAKE_FOLDER.rst b/Help/variable/CMAKE_FOLDER.rst new file mode 100644 index 0000000..50a2b88 --- /dev/null +++ b/Help/variable/CMAKE_FOLDER.rst @@ -0,0 +1,7 @@ +CMAKE_FOLDER +------------ + +Set the folder name. Use to organize targets in an IDE. + +This variable is used to initialize the :prop_tgt:`FOLDER` property on all the +targets. See that target property for additional information. diff --git a/Help/variable/CMAKE_MINIMUM_REQUIRED_VERSION.rst b/Help/variable/CMAKE_MINIMUM_REQUIRED_VERSION.rst index 5a51634..f466468 100644 --- a/Help/variable/CMAKE_MINIMUM_REQUIRED_VERSION.rst +++ b/Help/variable/CMAKE_MINIMUM_REQUIRED_VERSION.rst @@ -1,7 +1,5 @@ CMAKE_MINIMUM_REQUIRED_VERSION ------------------------------ -Version specified to :command:`cmake_minimum_required` command - -Variable containing the ``VERSION`` component specified in the -:command:`cmake_minimum_required` command. +The ``<min>`` version of CMake given to the most recent call to the +:command:`cmake_minimum_required(VERSION)` command. diff --git a/Help/variable/CMAKE_PROJECT_DESCRIPTION.rst b/Help/variable/CMAKE_PROJECT_DESCRIPTION.rst index f1911ec..51b0592 100644 --- a/Help/variable/CMAKE_PROJECT_DESCRIPTION.rst +++ b/Help/variable/CMAKE_PROJECT_DESCRIPTION.rst @@ -1,7 +1,35 @@ CMAKE_PROJECT_DESCRIPTION ------------------------- -The description of the current project. +The description of the top level project. -This specifies description of the current project from the closest inherited -:command:`project` command. +This variable holds the description of the project as specified in the top +level CMakeLists.txt file by a :command:`project` command. In the event that +the top level CMakeLists.txt contains multiple :command:`project` calls, +the most recently called one from that top level CMakeLists.txt will determine +the value that ``CMAKE_PROJECT_DESCRIPTION`` contains. For example, consider +the following top level CMakeLists.txt: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.0) + project(First DESCRIPTION "I am First") + project(Second DESCRIPTION "I am Second") + add_subdirectory(sub) + project(Third DESCRIPTION "I am Third") + +And ``sub/CMakeLists.txt`` with the following contents: + +.. code-block:: cmake + + project(SubProj DESCRIPTION "I am SubProj") + message("CMAKE_PROJECT_DESCRIPTION = ${CMAKE_PROJECT_DESCRIPTION}") + +The most recently seen :command:`project` command from the top level +CMakeLists.txt would be ``project(Second ...)``, so this will print:: + + CMAKE_PROJECT_DESCRIPTION = I am Second + +To obtain the description from the most recent call to :command:`project` in +the current directory scope or above, see the :variable:`PROJECT_DESCRIPTION` +variable. diff --git a/Help/variable/CMAKE_PROJECT_HOMEPAGE_URL.rst b/Help/variable/CMAKE_PROJECT_HOMEPAGE_URL.rst new file mode 100644 index 0000000..ee0bf7c --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_HOMEPAGE_URL.rst @@ -0,0 +1,35 @@ +CMAKE_PROJECT_HOMEPAGE_URL +-------------------------- + +The homepage URL of the top level project. + +This variable holds the homepage URL of the project as specified in the top +level CMakeLists.txt file by a :command:`project` command. In the event that +the top level CMakeLists.txt contains multiple :command:`project` calls, +the most recently called one from that top level CMakeLists.txt will determine +the value that ``CMAKE_PROJECT_HOMEPAGE_URL`` contains. For example, consider +the following top level CMakeLists.txt: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.0) + project(First HOMEPAGE_URL "http://first.example.com") + project(Second HOMEPAGE_URL "http://second.example.com") + add_subdirectory(sub) + project(Third HOMEPAGE_URL "http://third.example.com") + +And ``sub/CMakeLists.txt`` with the following contents: + +.. code-block:: cmake + + project(SubProj HOMEPAGE_URL "http://subproj.example.com") + message("CMAKE_PROJECT_HOMEPAGE_URL = ${CMAKE_PROJECT_HOMEPAGE_URL}") + +The most recently seen :command:`project` command from the top level +CMakeLists.txt would be ``project(Second ...)``, so this will print:: + + CMAKE_PROJECT_HOMEPAGE_URL = http://second.example.com + +To obtain the homepage URL from the most recent call to :command:`project` in +the current directory scope or above, see the :variable:`PROJECT_HOMEPAGE_URL` +variable. diff --git a/Help/variable/CMAKE_PROJECT_NAME.rst b/Help/variable/CMAKE_PROJECT_NAME.rst index 431e9f3..94b8dba 100644 --- a/Help/variable/CMAKE_PROJECT_NAME.rst +++ b/Help/variable/CMAKE_PROJECT_NAME.rst @@ -1,7 +1,35 @@ CMAKE_PROJECT_NAME ------------------ -The name of the current project. +The name of the top level project. -This specifies name of the current project from the closest inherited -:command:`project` command. +This variable holds the name of the project as specified in the top +level CMakeLists.txt file by a :command:`project` command. In the event that +the top level CMakeLists.txt contains multiple :command:`project` calls, +the most recently called one from that top level CMakeLists.txt will determine +the name that ``CMAKE_PROJECT_NAME`` contains. For example, consider +the following top level CMakeLists.txt: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.0) + project(First) + project(Second) + add_subdirectory(sub) + project(Third) + +And ``sub/CMakeLists.txt`` with the following contents: + +.. code-block:: cmake + + project(SubProj) + message("CMAKE_PROJECT_NAME = ${CMAKE_PROJECT_NAME}") + +The most recently seen :command:`project` command from the top level +CMakeLists.txt would be ``project(Second)``, so this will print:: + + CMAKE_PROJECT_NAME = Second + +To obtain the name from the most recent call to :command:`project` in +the current directory scope or above, see the :variable:`PROJECT_NAME` +variable. diff --git a/Help/variable/CMAKE_SUPPRESS_REGENERATION.rst b/Help/variable/CMAKE_SUPPRESS_REGENERATION.rst new file mode 100644 index 0000000..ed47e1a --- /dev/null +++ b/Help/variable/CMAKE_SUPPRESS_REGENERATION.rst @@ -0,0 +1,11 @@ +CMAKE_SUPPRESS_REGENERATION +--------------------------- + +If CMAKE_SUPPRESS_REGENERATION is ``OFF``, which is default, then CMake adds a +special target on which all other targets depend that checks the build system +and optionally re-runs CMake to regenerate the build system when the target +specification source changes. + +If this variable evaluates to ``ON`` at the end of the top-level +``CMakeLists.txt`` file, CMake will not add the regeneration target to the +build system or perform any build system checks. diff --git a/Help/variable/CMAKE_VS_DEVENV_COMMAND.rst b/Help/variable/CMAKE_VS_DEVENV_COMMAND.rst index 51b42dd..f109a9e 100644 --- a/Help/variable/CMAKE_VS_DEVENV_COMMAND.rst +++ b/Help/variable/CMAKE_VS_DEVENV_COMMAND.rst @@ -1,7 +1,7 @@ CMAKE_VS_DEVENV_COMMAND ----------------------- -The generators for :generator:`Visual Studio 8 2005` and above set this +The generators for :generator:`Visual Studio 9 2008` and above set this variable to the ``devenv.com`` command installed with the corresponding Visual Studio version. Note that this variable may be empty on Visual Studio Express editions because they do not provide this tool. diff --git a/Help/variable/CMAKE_VS_INTEL_Fortran_PROJECT_VERSION.rst b/Help/variable/CMAKE_VS_INTEL_Fortran_PROJECT_VERSION.rst index 6d196f9..ceedf28 100644 --- a/Help/variable/CMAKE_VS_INTEL_Fortran_PROJECT_VERSION.rst +++ b/Help/variable/CMAKE_VS_INTEL_Fortran_PROJECT_VERSION.rst @@ -1,7 +1,7 @@ CMAKE_VS_INTEL_Fortran_PROJECT_VERSION -------------------------------------- -When generating for :generator:`Visual Studio 8 2005` or greater with the Intel +When generating for :generator:`Visual Studio 9 2008` or greater with the Intel Fortran plugin installed, this specifies the ``.vfproj`` project file format version. This is intended for internal use by CMake and should not be used by project code. diff --git a/Help/variable/MSVC_TOOLSET_VERSION.rst b/Help/variable/MSVC_TOOLSET_VERSION.rst new file mode 100644 index 0000000..77e1ea9 --- /dev/null +++ b/Help/variable/MSVC_TOOLSET_VERSION.rst @@ -0,0 +1,21 @@ +MSVC_TOOLSET_VERSION +-------------------- + +The toolset version of Microsoft Visual C/C++ being used if any. +If MSVC-like is being used, this variable is set based on the version +of the compiler as given by the :variable:`MSVC_VERSION` variable. + +Known toolset version numbers are:: + + 80 = VS 2005 (8.0) + 90 = VS 2008 (9.0) + 100 = VS 2010 (10.0) + 110 = VS 2012 (11.0) + 120 = VS 2013 (12.0) + 140 = VS 2015 (14.0) + 141 = VS 2017 (15.0) + +Compiler versions newer than those known to CMake will be reported +as the latest known toolset version. + +See also the :variable:`MSVC_VERSION` variable. diff --git a/Help/variable/MSVC_VERSION.rst b/Help/variable/MSVC_VERSION.rst index 5f70c02..4ef43d8 100644 --- a/Help/variable/MSVC_VERSION.rst +++ b/Help/variable/MSVC_VERSION.rst @@ -19,4 +19,5 @@ Known version numbers are:: 1900 = VS 14.0 (v140 toolset) 1910-1919 = VS 15.0 (v141 toolset) -See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` and +:variable:`MSVC_TOOLSET_VERSION` variable. diff --git a/Help/variable/PROJECT-NAME_DESCRIPTION.rst b/Help/variable/PROJECT-NAME_DESCRIPTION.rst new file mode 100644 index 0000000..2b88b1a --- /dev/null +++ b/Help/variable/PROJECT-NAME_DESCRIPTION.rst @@ -0,0 +1,5 @@ +<PROJECT-NAME>_DESCRIPTION +-------------------------- + +Value given to the ``DESCRIPTION`` option of the most recent call to the +:command:`project` command with project name ``<PROJECT-NAME>``, if any. diff --git a/Help/variable/PROJECT-NAME_HOMEPAGE_URL.rst b/Help/variable/PROJECT-NAME_HOMEPAGE_URL.rst new file mode 100644 index 0000000..22cc304 --- /dev/null +++ b/Help/variable/PROJECT-NAME_HOMEPAGE_URL.rst @@ -0,0 +1,5 @@ +<PROJECT-NAME>_HOMEPAGE_URL +--------------------------- + +Value given to the ``HOMEPAGE_URL`` option of the most recent call to the +:command:`project` command with project name ``<PROJECT-NAME>``, if any. diff --git a/Help/variable/PROJECT_DESCRIPTION.rst b/Help/variable/PROJECT_DESCRIPTION.rst index 05ede8f..2833e11 100644 --- a/Help/variable/PROJECT_DESCRIPTION.rst +++ b/Help/variable/PROJECT_DESCRIPTION.rst @@ -3,4 +3,7 @@ PROJECT_DESCRIPTION Short project description given to the project command. -This is the description given to the most recent :command:`project` command. +This is the description given to the most recently called :command:`project` +command in the current directory scope or above. To obtain the description +of the top level project, see the :variable:`CMAKE_PROJECT_DESCRIPTION` +variable. diff --git a/Help/variable/PROJECT_HOMEPAGE_URL.rst b/Help/variable/PROJECT_HOMEPAGE_URL.rst new file mode 100644 index 0000000..754c9e8 --- /dev/null +++ b/Help/variable/PROJECT_HOMEPAGE_URL.rst @@ -0,0 +1,9 @@ +PROJECT_HOMEPAGE_URL +-------------------- + +The homepage URL of the project. + +This is the homepage URL given to the most recently called :command:`project` +command in the current directory scope or above. To obtain the homepage URL +of the top level project, see the :variable:`CMAKE_PROJECT_HOMEPAGE_URL` +variable. diff --git a/Help/variable/PROJECT_NAME.rst b/Help/variable/PROJECT_NAME.rst index 61aa8bc..672680a 100644 --- a/Help/variable/PROJECT_NAME.rst +++ b/Help/variable/PROJECT_NAME.rst @@ -3,4 +3,6 @@ PROJECT_NAME Name of the project given to the project command. -This is the name given to the most recent :command:`project` command. +This is the name given to the most recently called :command:`project` +command in the current directory scope or above. To obtain the name of +the top level project, see the :variable:`CMAKE_PROJECT_NAME` variable. |