diff options
Diffstat (limited to 'Help')
222 files changed, 3629 insertions, 966 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..38c231a 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,13 @@ 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 the + :variable:`<PackageName>_ROOT` CMake variable and the + :envvar:`<PackageName>_ROOT` environment variable if + called from within a find module loaded by + :command:`find_package(<PackageName>)` + .. |CMAKE_PREFIX_PATH_XXX_SUBDIR| replace:: |prefix_XXX_SUBDIR| for each ``<prefix>`` in :variable:`CMAKE_PREFIX_PATH` @@ -71,7 +79,22 @@ 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 loaded by + :command:`find_package(<PackageName>)`, search prefixes unique to the + current package being found. Specifically look in the + :variable:`<PackageName>_ROOT` CMake variable and the + :envvar:`<PackageName>_ROOT` environment variable. + 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 + searched after paths from the current module, + i.e. ``<CurrentPackage>_ROOT``, ``ENV{<CurrentPackage>_ROOT}``, + ``<ParentPackage>_ROOT``, ``ENV{<ParentPackage>_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 +103,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 +113,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 +131,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_definitions.rst b/Help/command/add_compile_definitions.rst new file mode 100644 index 0000000..48815d4 --- /dev/null +++ b/Help/command/add_compile_definitions.rst @@ -0,0 +1,23 @@ +add_compile_definitions +----------------------- + +Adds preprocessor definitions to the compilation of source files. + +:: + + add_compile_definitions(<definition> ...) + +Adds preprocessor definitions to the compiler command line for targets in the +current directory and below (whether added before or after this command is +invoked). See documentation of the :prop_dir:`directory <COMPILE_DEFINITIONS>` +and :prop_tgt:`target <COMPILE_DEFINITIONS>` ``COMPILE_DEFINITIONS`` properties. + +Definitions are specified using the syntax ``VAR`` or ``VAR=value``. +Function-style definitions are not supported. CMake will automatically +escape the value correctly for the native build system (note that CMake +language syntax may require escapes to specify some values). + +Arguments to ``add_compile_definitions`` may use "generator expressions" with +the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` +manual for available expressions. See the :manual:`cmake-buildsystem(7)` +manual for more on defining buildsystem properties. diff --git a/Help/command/add_compile_options.rst b/Help/command/add_compile_options.rst index 3fe2a33..c445608 100644 --- a/Help/command/add_compile_options.rst +++ b/Help/command/add_compile_options.rst @@ -14,10 +14,12 @@ See documentation of the :prop_dir:`directory <COMPILE_OPTIONS>` and This command can be used to add any options, but alternative commands exist to add preprocessor definitions (:command:`target_compile_definitions` -and :command:`add_definitions`) or include directories +and :command:`add_compile_definitions`) or include directories (:command:`target_include_directories` and :command:`include_directories`). 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 1b0aa14..5f74c54 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -146,8 +146,10 @@ The options are: Specify the primary input source file to the command. This is treated just like any value given to the ``DEPENDS`` option but also suggests to Visual Studio generators where to hang - the custom command. At most one custom command may specify a - given source file as its main dependency. + the custom command. Each source file may have at most one command + specifying it as its main dependency. A compile command (i.e. for a + library or an executable) counts as an implicit main dependency which + gets silently overwritten by a custom command specification. ``OUTPUT`` Specify the output files the command is expected to produce. @@ -214,10 +216,9 @@ When the command will happen is determined by which of the following is specified: ``PRE_BUILD`` - Run before any other rules are executed within the target. - This is supported only on Visual Studio 8 or later. - For all other generators ``PRE_BUILD`` will be treated as - ``PRE_LINK``. + On :ref:`Visual Studio Generators`, run before any other rules are + executed within the target. + On other generators, run just before ``PRE_LINK`` commands. ``PRE_LINK`` Run after sources have been compiled but before linking the binary or running the librarian or archiver tool of a static library. diff --git a/Help/command/add_definitions.rst b/Help/command/add_definitions.rst index a04faf5..1da15a6 100644 --- a/Help/command/add_definitions.rst +++ b/Help/command/add_definitions.rst @@ -10,8 +10,16 @@ Adds -D define flags to the compilation of source files. Adds definitions to the compiler command line for targets in the current directory and below (whether added before or after this command is invoked). This command can be used to add any flags, but it is intended to add -preprocessor definitions (see the :command:`add_compile_options` command -to add other flags). +preprocessor definitions. + +.. note:: + + This command has been superseded by alternatives: + + * Use :command:`add_compile_definitions` to add preprocessor definitions. + * Use :command:`include_directories` to add include directories. + * Use :command:`add_compile_options` to add other options. + Flags beginning in -D or /D that look like preprocessor definitions are automatically added to the :prop_dir:`COMPILE_DEFINITIONS` directory property for the current directory. Definitions with non-trivial values diff --git a/Help/command/add_executable.rst b/Help/command/add_executable.rst index c088796..c7a30d7 100644 --- a/Help/command/add_executable.rst +++ b/Help/command/add_executable.rst @@ -7,14 +7,15 @@ Add an executable to the project using the specified source files. add_executable(<name> [WIN32] [MACOSX_BUNDLE] [EXCLUDE_FROM_ALL] - source1 [source2 ...]) + [source1] [source2 ...]) Adds an executable target called ``<name>`` to be built from the source -files listed in the command invocation. The ``<name>`` corresponds to the -logical target name and must be globally unique within a project. The -actual file name of the executable built is constructed based on -conventions of the native platform (such as ``<name>.exe`` or just -``<name>``). +files listed in the command invocation. (The source files can be omitted +here if they are added later using :command:`target_sources`.) The +``<name>`` corresponds to the logical target name and must be globally +unique within a project. The actual file name of the executable built is +constructed based on conventions of the native platform (such as +``<name>.exe`` or just ``<name>``). By default the executable file will be created in the build tree directory corresponding to the source tree directory in which the @@ -73,8 +74,9 @@ properties for more information. Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can be used to refer to ``<target>`` in subsequent commands. The ``<name>`` does not appear in the generated buildsystem as a make target. The -``<target>`` may not be an :ref:`Imported Target <Imported Targets>` or an -``ALIAS``. ``ALIAS`` targets can be used as targets to read properties +``<target>`` may not be a non-``GLOBAL`` +:ref:`Imported Target <Imported Targets>` or an ``ALIAS``. +``ALIAS`` targets can be used as targets to read properties from, executables for custom commands and custom targets. They can also be tested for existence with the regular :command:`if(TARGET)` subcommand. The ``<name>`` may not be used to modify properties of ``<target>``, that diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst index de5335e..f20b274 100644 --- a/Help/command/add_library.rst +++ b/Help/command/add_library.rst @@ -14,13 +14,14 @@ Normal Libraries add_library(<name> [STATIC | SHARED | MODULE] [EXCLUDE_FROM_ALL] - source1 [source2 ...]) + [source1] [source2 ...]) Adds a library target called ``<name>`` to be built from the source files -listed in the command invocation. The ``<name>`` corresponds to the -logical target name and must be globally unique within a project. The -actual file name of the library built is constructed based on -conventions of the native platform (such as ``lib<name>.a`` or +listed in the command invocation. (The source files can be omitted here +if they are added later using :command:`target_sources`.) The ``<name>`` +corresponds to the logical target name and must be globally unique within +a project. The actual file name of the library built is constructed based +on conventions of the native platform (such as ``lib<name>.a`` or ``<name>.lib``). ``STATIC``, ``SHARED``, or ``MODULE`` may be given to specify the type of @@ -82,8 +83,11 @@ about the imported library are specified by setting properties whose names begin in ``IMPORTED_`` and ``INTERFACE_``. The most important such property is :prop_tgt:`IMPORTED_LOCATION` (and its per-configuration variant :prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) which specifies the -location of the main library file on disk. See documentation of the -``IMPORTED_*`` and ``INTERFACE_*`` properties for more information. +location of the main library file on disk. Or, for object libraries, +:prop_tgt:`IMPORTED_OBJECTS` (and :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>`) +specifies the locations of object files on disk. +See documentation of the ``IMPORTED_*`` and ``INTERFACE_*`` properties +for more information. Object Libraries ^^^^^^^^^^^^^^^^ @@ -109,10 +113,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 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 ^^^^^^^^^^^^^^^ @@ -124,7 +128,8 @@ Alias Libraries Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can be used to refer to ``<target>`` in subsequent commands. The ``<name>`` does not appear in the generated buildsystem as a make target. The ``<target>`` -may not be an :ref:`Imported Target <Imported Targets>` or an ``ALIAS``. +may not be a non-``GLOBAL`` :ref:`Imported Target <Imported Targets>` or an +``ALIAS``. ``ALIAS`` targets can be used as linkable targets and as targets to read properties from. They can also be tested for existence with the regular :command:`if(TARGET)` subcommand. The ``<name>`` may not be used diff --git a/Help/command/add_subdirectory.rst b/Help/command/add_subdirectory.rst index e979253..012ded4 100644 --- a/Help/command/add_subdirectory.rst +++ b/Help/command/add_subdirectory.rst @@ -30,7 +30,7 @@ project that is useful but not necessary, such as a set of examples. Typically the subdirectory should contain its own :command:`project` command invocation so that a full build system will be generated in the subdirectory (such as a VS IDE solution file). Note that inter-target -dependencies supercede this exclusion. If a target built by the +dependencies supersede this exclusion. If a target built by the parent project depends on a target in the subdirectory, the dependee target will be included in the parent project build system to satisfy the dependency. diff --git a/Help/command/cmake_host_system_information.rst b/Help/command/cmake_host_system_information.rst index 7199874..9893151 100644 --- a/Help/command/cmake_host_system_information.rst +++ b/Help/command/cmake_host_system_information.rst @@ -27,13 +27,13 @@ Key Description ``IS_64BIT`` One if processor is 64Bit ``HAS_FPU`` One if processor has floating point unit ``HAS_MMX`` One if processor supports MMX instructions -``HAS_MMX_PLUS`` One if porcessor supports Ext. MMX instructions -``HAS_SSE`` One if porcessor supports SSE instructions -``HAS_SSE2`` One if porcessor supports SSE2 instructions -``HAS_SSE_FP`` One if porcessor supports SSE FP instructions -``HAS_SSE_MMX`` One if porcessor supports SSE MMX instructions -``HAS_AMD_3DNOW`` One if porcessor supports 3DNow instructions -``HAS_AMD_3DNOW_PLUS`` One if porcessor supports 3DNow+ instructions +``HAS_MMX_PLUS`` One if processor supports Ext. MMX instructions +``HAS_SSE`` One if processor supports SSE instructions +``HAS_SSE2`` One if processor supports SSE2 instructions +``HAS_SSE_FP`` One if processor supports SSE FP instructions +``HAS_SSE_MMX`` One if processor supports SSE MMX instructions +``HAS_AMD_3DNOW`` One if processor supports 3DNow instructions +``HAS_AMD_3DNOW_PLUS`` One if processor supports 3DNow+ instructions ``HAS_IA64`` One if IA64 processor emulating x86 ``HAS_SERIAL_NUMBER`` One if processor has serial number ``PROCESSOR_SERIAL_NUMBER`` Processor serial number diff --git a/Help/command/cmake_minimum_required.rst b/Help/command/cmake_minimum_required.rst index 9535bf3..2f1ab60 100644 --- a/Help/command/cmake_minimum_required.rst +++ b/Help/command/cmake_minimum_required.rst @@ -4,11 +4,19 @@ 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. +If the running version of CMake is older than 3.12, the extra ``...`` +dots will be seen as version component separators, resulting in the +``...<max>`` part being ignored and preserving the pre-3.12 behavior +of basing policies on ``<min>``. 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 +38,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_parse_arguments.rst b/Help/command/cmake_parse_arguments.rst index b334a89..efbef54 100644 --- a/Help/command/cmake_parse_arguments.rst +++ b/Help/command/cmake_parse_arguments.rst @@ -62,7 +62,7 @@ as the real :command:`install` command: .. code-block:: cmake - function(MY_INSTALL) + macro(my_install) set(options OPTIONAL FAST) set(oneValueArgs DESTINATION RENAME) set(multiValueArgs TARGETS CONFIGURATIONS) diff --git a/Help/command/cmake_policy.rst b/Help/command/cmake_policy.rst index b51b951..c3f7cfb 100644 --- a/Help/command/cmake_policy.rst +++ b/Help/command/cmake_policy.rst @@ -24,17 +24,25 @@ 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. If the running version of +CMake is older than 3.12, the extra ``...`` dots will be seen as version +component separators, resulting in the ``...<max>`` part being ignored and +preserving the pre-3.12 behavior of basing policies on ``<min>``. + +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/ctest_start.rst b/Help/command/ctest_start.rst index 63db32f..6db9a48 100644 --- a/Help/command/ctest_start.rst +++ b/Help/command/ctest_start.rst @@ -5,21 +5,78 @@ Starts the testing for a given model :: - ctest_start(Model [TRACK <track>] [APPEND] [source [binary]] [QUIET]) + ctest_start(<model> [<source> [<binary>]] [TRACK <track>] [QUIET]) + + ctest_start([<model> [<source> [<binary>]]] [TRACK <track>] APPEND [QUIET]) Starts the testing for a given model. The command should be called -after the binary directory is initialized. If the 'source' and -'binary' directory are not specified, it reads the -:variable:`CTEST_SOURCE_DIRECTORY` and :variable:`CTEST_BINARY_DIRECTORY`. -If the track is -specified, the submissions will go to the specified track. If APPEND -is used, the existing TAG is used rather than creating a new one based -on the current time stamp. If ``QUIET`` is used, CTest will suppress any -non-error messages that it otherwise would have printed to the console. - -If the :variable:`CTEST_CHECKOUT_COMMAND` variable -(or the :variable:`CTEST_CVS_CHECKOUT` variable) -is set, its content is treated as command-line. The command is -invoked with the current working directory set to the parent of the source -directory, even if the source directory already exists. This can be used -to create the source tree from a version control repository. +after the binary directory is initialized. + +The parameters are as follows: + +``<model>`` + Set the dashboard model. Must be one of ``Experimental``, ``Continuous``, or + ``Nightly``. This parameter is required unless ``APPEND`` is specified. + +``<source>`` + Set the source directory. If not specified, the value of + :variable:`CTEST_SOURCE_DIRECTORY` is used instead. + +``<binary>`` + Set the binary directory. If not specified, the value of + :variable:`CTEST_BINARY_DIRECTORY` is used instead. + +``TRACK <track>`` + If ``TRACK`` is used, the submissions will go to the specified track on the + CDash server. If no ``TRACK`` is specified, the name of the model is used by + default. + +``APPEND`` + If ``APPEND`` is used, the existing ``TAG`` is used rather than creating a new + one based on the current time stamp. If you use ``APPEND``, you can omit the + ``<model>`` and ``TRACK <track>`` parameters, because they will be read from + the generated ``TAG`` file. For example: + + .. code-block:: cmake + + ctest_start(Experimental TRACK TrackExperimental) + + Later, in another ``ctest -S`` script: + + .. code-block:: cmake + + ctest_start(APPEND) + + When the second script runs ``ctest_start(APPEND)``, it will read the + ``Experimental`` model and ``TrackExperimental`` track from the ``TAG`` file + generated by the first ``ctest_start()`` command. Please note that if you + call ``ctest_start(APPEND)`` and specify a different model or track than + in the first ``ctest_start()`` command, a warning will be issued, and the + new model and track will be used. + +``QUIET`` + If ``QUIET`` is used, CTest will suppress any non-error messages that it + otherwise would have printed to the console. + +The parameters for ``ctest_start()`` can be issued in any order, with the +exception that ``<model>``, ``<source>``, and ``<binary>`` have to appear +in that order with respect to each other. The following are all valid and +equivalent: + +.. code-block:: cmake + + ctest_start(Experimental path/to/source path/to/binary TRACK SomeTrack QUIET APPEND) + + ctest_start(TRACK SomeTrack Experimental QUIET path/to/source APPEND path/to/binary) + + ctest_start(APPEND QUIET Experimental path/to/source TRACK SomeTrack path/to/binary) + +However, for the sake of readability, it is recommended that you order your +parameters in the order listed at the top of this page. + +If the :variable:`CTEST_CHECKOUT_COMMAND` variable (or the +:variable:`CTEST_CVS_CHECKOUT` variable) is set, its content is treated as +command-line. The command is invoked with the current working directory set +to the parent of the source directory, even if the source directory already +exists. This can be used to create the source tree from a version control +repository. diff --git a/Help/command/ctest_submit.rst b/Help/command/ctest_submit.rst index 6b49da3..cc9612b 100644 --- a/Help/command/ctest_submit.rst +++ b/Help/command/ctest_submit.rst @@ -68,7 +68,7 @@ Submit to CDash Upload API [QUIET]) This second signature is used to upload files to CDash via the CDash -file upload API. The api first sends a request to upload to CDash along +file upload API. The API first sends a request to upload to CDash along with a content hash of the file. If CDash does not already have the file, then it is uploaded. Along with the file, a CDash type string is specified to tell CDash which handler to use to process the data. diff --git a/Help/command/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/enable_language.rst b/Help/command/enable_language.rst index 4445561..61dfc03 100644 --- a/Help/command/enable_language.rst +++ b/Help/command/enable_language.rst @@ -10,7 +10,10 @@ Enable a language (CXX/C/Fortran/etc) This command enables support for the named language in CMake. This is the same as the project command but does not create any of the extra variables that are created by the project command. Example languages -are CXX, C, Fortran. +are ``CXX``, ``C``, ``CUDA``, ``Fortran``, and ``ASM``. + +If enabling ``ASM``, enable it last so that CMake can check whether +compilers for other languages like ``C`` work for assembly too. This command must be called in file scope, not in a function call. Furthermore, it must be called in the highest directory common to all @@ -19,4 +22,5 @@ indirectly through link dependencies. It is simplest to enable all needed languages in the top-level directory of a project. The ``OPTIONAL`` keyword is a placeholder for future implementation and -does not currently work. +does not currently work. Instead you can use the :module:`CheckLanguage` +module to verify support before enabling. diff --git a/Help/command/execute_process.rst b/Help/command/execute_process.rst index 799493f..716f457 100644 --- a/Help/command/execute_process.rst +++ b/Help/command/execute_process.rst @@ -90,8 +90,10 @@ Options: Use the ANSI codepage. ``OEM`` Use the original equipment manufacturer (OEM) code page. - ``UTF8`` - Use the UTF-8 codepage. + ``UTF8`` or ``UTF-8`` + Use the UTF-8 codepage. Prior to CMake 3.11.0, only ``UTF8`` was accepted + for this encoding. In CMake 3.11.0, ``UTF-8`` was added for consistency with + the `UTF-8 RFC <https://www.ietf.org/rfc/rfc3629>`_ naming convention. If more than one ``OUTPUT_*`` or ``ERROR_*`` option is given for the same pipe the precedence is not specified. 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 edccac5..d4a6006 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -3,23 +3,44 @@ file File manipulation command. ------------------------------------------------------------------------------- +Synopsis +^^^^^^^^ -:: +.. parsed-literal:: - file(WRITE <filename> <content>...) - file(APPEND <filename> <content>...) + `Reading`_ + file(`READ`_ <filename> <out-var> [...]) + file(`STRINGS`_ <filename> <out-var> [...]) + file(`\<HASH\> <HASH_>`_ <filename> <out-var>) + file(`TIMESTAMP`_ <filename> <out-var> [...]) -Write ``<content>`` into a file called ``<filename>``. If the file does -not exist, it will be created. If the file already exists, ``WRITE`` -mode will overwrite it and ``APPEND`` mode will append to the end. -Any directories in the path specified by ``<filename>`` that do not -exist will be created. + `Writing`_ + file({`WRITE`_ | `APPEND`_} <filename> <content>...) + file({`TOUCH`_ | `TOUCH_NOCREATE`_} [<file>...]) + file(`GENERATE`_ OUTPUT <output-file> [...]) -If the file is a build input, use the :command:`configure_file` command -to update the file only when its content changes. + `Filesystem`_ + file({`GLOB`_ | `GLOB_RECURSE`_} <out-var> [...] [<globbing-expr>...]) + file(`RENAME`_ <oldname> <newname>) + file({`REMOVE`_ | `REMOVE_RECURSE`_ } [<files>...]) + file(`MAKE_DIRECTORY`_ [<dir>...]) + file({`COPY`_ | `INSTALL`_} <file>... DESTINATION <dir> [...]) + + `Path Conversion`_ + file(`RELATIVE_PATH`_ <out-var> <directory> <file>) + file({`TO_CMAKE_PATH`_ | `TO_NATIVE_PATH`_} <path> <out-var>) + + `Transfer`_ + file(`DOWNLOAD`_ <url> <file> [...]) + file(`UPLOAD`_ <file> <url> [...]) + + `Locking`_ + file(`LOCK`_ <path> [...]) + +Reading +^^^^^^^ ------------------------------------------------------------------------------- +.. _READ: :: @@ -31,7 +52,7 @@ Read content from a file called ``<filename>`` and store it in a read at most ``<max-in>`` bytes. The ``HEX`` option causes data to be converted to a hexadecimal representation (useful for binary data). ------------------------------------------------------------------------------- +.. _STRINGS: :: @@ -82,7 +103,7 @@ For example, the code stores a list in the variable ``myfile`` in which each item is a line from the input file. ------------------------------------------------------------------------------- +.. _HASH: :: @@ -93,15 +114,116 @@ store it in a ``<variable>``. The supported ``<HASH>`` algorithm names are those listed by the :ref:`string(\<HASH\>) <Supported Hash Algorithms>` command. ------------------------------------------------------------------------------- +.. _TIMESTAMP: + +:: + + file(TIMESTAMP <filename> <variable> [<format>] [UTC]) + +Compute a string representation of the modification time of ``<filename>`` +and store it in ``<variable>``. Should the command be unable to obtain a +timestamp variable will be set to the empty string (""). + +See the :command:`string(TIMESTAMP)` command for documentation of +the ``<format>`` and ``UTC`` options. + +Writing +^^^^^^^ + +.. _WRITE: +.. _APPEND: + +:: + + file(WRITE <filename> <content>...) + file(APPEND <filename> <content>...) + +Write ``<content>`` into a file called ``<filename>``. If the file does +not exist, it will be created. If the file already exists, ``WRITE`` +mode will overwrite it and ``APPEND`` mode will append to the end. +Any directories in the path specified by ``<filename>`` that do not +exist will be created. + +If the file is a build input, use the :command:`configure_file` command +to update the file only when its content changes. + +.. _TOUCH: +.. _TOUCH_NOCREATE: + +:: + + 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. + +.. _GENERATE: + +:: + + file(GENERATE OUTPUT output-file + <INPUT input-file|CONTENT content> + [CONDITION expression]) + +Generate an output file for each build configuration supported by the current +:manual:`CMake Generator <cmake-generators(7)>`. Evaluate +:manual:`generator expressions <cmake-generator-expressions(7)>` +from the input content to produce the output content. The options are: + +``CONDITION <condition>`` + Generate the output file for a particular configuration only if + the condition is true. The condition must be either ``0`` or ``1`` + after evaluating generator expressions. + +``CONTENT <content>`` + Use the content given explicitly as input. + +``INPUT <input-file>`` + Use the content from a given file as input. + A relative path is treated with respect to the value of + :variable:`CMAKE_CURRENT_SOURCE_DIR`. See policy :policy:`CMP0070`. + +``OUTPUT <output-file>`` + Specify the output file name to generate. Use generator expressions + such as ``$<CONFIG>`` to specify a configuration-specific output file + name. Multiple configurations may generate the same output file only + if the generated content is identical. Otherwise, the ``<output-file>`` + must evaluate to an unique name for each configuration. + A relative path (after evaluating generator expressions) is treated + with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. + See policy :policy:`CMP0070`. + +Exactly one ``CONTENT`` or ``INPUT`` option must be given. A specific +``OUTPUT`` file may be named by at most one invocation of ``file(GENERATE)``. +Generated files are modified and their timestamp updated on subsequent cmake +runs only if their content is changed. + +Note also that ``file(GENERATE)`` does not create the output file until the +generation phase. The output file will not yet have been written when the +``file(GENERATE)`` command returns, it is written only after processing all +of a project's ``CMakeLists.txt`` files. + +Filesystem +^^^^^^^^^^ + +.. _GLOB: +.. _GLOB_RECURSE: :: 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,7 +232,12 @@ 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. -By default ``GLOB`` lists directories - directories are omited in result if +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. .. note:: @@ -118,6 +245,10 @@ By default ``GLOB`` lists directories - directories are omited 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:: @@ -139,7 +270,7 @@ Examples of recursive globbing include:: /dir/*.py - match all python files in /dir and subdirectories ------------------------------------------------------------------------------- +.. _RENAME: :: @@ -148,7 +279,8 @@ Examples of recursive globbing include:: Move a file or directory within a filesystem from ``<oldname>`` to ``<newname>``, replacing the destination atomically. ------------------------------------------------------------------------------- +.. _REMOVE: +.. _REMOVE_RECURSE: :: @@ -159,7 +291,7 @@ Remove the given files. The ``REMOVE_RECURSE`` mode will remove the given files and directories, also non-empty directories. No error is emitted if a given file does not exist. ------------------------------------------------------------------------------- +.. _MAKE_DIRECTORY: :: @@ -167,7 +299,44 @@ given file does not exist. Create the given directories and their parents as needed. ------------------------------------------------------------------------------- +.. _COPY: +.. _INSTALL: + +:: + + file(<COPY|INSTALL> <files>... DESTINATION <dir> + [FILE_PERMISSIONS <permissions>...] + [DIRECTORY_PERMISSIONS <permissions>...] + [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS] + [FILES_MATCHING] + [[PATTERN <pattern> | REGEX <regex>] + [EXCLUDE] [PERMISSIONS <permissions>...]] [...]) + +The ``COPY`` signature copies files, directories, and symlinks to a +destination folder. Relative input paths are evaluated with respect +to the current source directory, and a relative destination is +evaluated with respect to the current build directory. Copying +preserves input file timestamps, and optimizes out a file if it exists +at the destination with the same timestamp. Copying preserves input +permissions unless explicit permissions or ``NO_SOURCE_PERMISSIONS`` +are given (default is ``USE_SOURCE_PERMISSIONS``). + +See the :command:`install(DIRECTORY)` command for documentation of +permissions, ``FILES_MATCHING``, ``PATTERN``, ``REGEX``, and +``EXCLUDE`` options. Copying directories preserves the structure +of their content even if options are used to select a subset of +files. + +The ``INSTALL`` signature differs slightly from ``COPY``: it prints +status messages (subject to the :variable:`CMAKE_INSTALL_MESSAGE` variable), +and ``NO_SOURCE_PERMISSIONS`` is default. +Installation scripts generated by the :command:`install` command +use this signature (with some undocumented options for internal use). + +Path Conversion +^^^^^^^^^^^^^^^ + +.. _RELATIVE_PATH: :: @@ -176,7 +345,8 @@ Create the given directories and their parents as needed. Compute the relative path from a ``<directory>`` to a ``<file>`` and store it in the ``<variable>``. ------------------------------------------------------------------------------- +.. _TO_CMAKE_PATH: +.. _TO_NATIVE_PATH: :: @@ -194,7 +364,11 @@ path with platform-specific slashes (``\`` on Windows and ``/`` elsewhere). Always use double quotes around the ``<path>`` to be sure it is treated as a single argument to this command. ------------------------------------------------------------------------------- +Transfer +^^^^^^^^ + +.. _DOWNLOAD: +.. _UPLOAD: :: @@ -232,6 +406,31 @@ Options to both ``DOWNLOAD`` and ``UPLOAD`` are: ``HTTPHEADER <HTTP-header>`` HTTP header for operation. Suboption can be repeated several times. +``NETRC <level>`` + Specify whether the .netrc file is to be used for operation. If this + option is not specified, the value of the ``CMAKE_NETRC`` variable + will be used instead. + Valid levels are: + + ``IGNORED`` + The .netrc file is ignored. + This is the default. + ``OPTIONAL`` + The .netrc file is optional, and information in the URL is preferred. + The file will be scanned to find which ever information is not specified + in the URL. + ``REQUIRED`` + The .netrc file is required, and information in the URL is ignored. + +``NETRC_FILE <file>`` + Specify an alternative .netrc file to the one in your home directory, + if the ``NETRC`` level is ``OPTIONAL`` or ``REQUIRED``. If this option + is not specified, the value of the ``CMAKE_NETRC_FILE`` variable will + be used instead. + +If neither ``NETRC`` option is given CMake will check variables +``CMAKE_NETRC`` and ``CMAKE_NETRC_FILE``, respectively. + Additional options to ``DOWNLOAD`` are: ``EXPECTED_HASH ALGO=<value>`` @@ -256,99 +455,10 @@ check certificates and/or use ``EXPECTED_HASH`` to verify downloaded content. If neither ``TLS`` option is given CMake will check variables ``CMAKE_TLS_VERIFY`` and ``CMAKE_TLS_CAINFO``, respectively. ------------------------------------------------------------------------------- - -:: - - file(TIMESTAMP <filename> <variable> [<format>] [UTC]) - -Compute a string representation of the modification time of ``<filename>`` -and store it in ``<variable>``. Should the command be unable to obtain a -timestamp variable will be set to the empty string (""). - -See the :command:`string(TIMESTAMP)` command for documentation of -the ``<format>`` and ``UTC`` options. - ------------------------------------------------------------------------------- - -:: - - file(GENERATE OUTPUT output-file - <INPUT input-file|CONTENT content> - [CONDITION expression]) - -Generate an output file for each build configuration supported by the current -:manual:`CMake Generator <cmake-generators(7)>`. Evaluate -:manual:`generator expressions <cmake-generator-expressions(7)>` -from the input content to produce the output content. The options are: - -``CONDITION <condition>`` - Generate the output file for a particular configuration only if - the condition is true. The condition must be either ``0`` or ``1`` - after evaluating generator expressions. - -``CONTENT <content>`` - Use the content given explicitly as input. - -``INPUT <input-file>`` - Use the content from a given file as input. - A relative path is treated with respect to the value of - :variable:`CMAKE_CURRENT_SOURCE_DIR`. See policy :policy:`CMP0070`. - -``OUTPUT <output-file>`` - Specify the output file name to generate. Use generator expressions - such as ``$<CONFIG>`` to specify a configuration-specific output file - name. Multiple configurations may generate the same output file only - if the generated content is identical. Otherwise, the ``<output-file>`` - must evaluate to an unique name for each configuration. - A relative path (after evaluating generator expressions) is treated - with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. - See policy :policy:`CMP0070`. - -Exactly one ``CONTENT`` or ``INPUT`` option must be given. A specific -``OUTPUT`` file may be named by at most one invocation of ``file(GENERATE)``. -Generated files are modified and their timestamp updated on subsequent cmake -runs only if their content is changed. - -Note also that ``file(GENERATE)`` does not create the output file until the -generation phase. The output file will not yet have been written when the -``file(GENERATE)`` command returns, it is written only after processing all -of a project's ``CMakeLists.txt`` files. - ------------------------------------------------------------------------------- - -:: - - file(<COPY|INSTALL> <files>... DESTINATION <dir> - [FILE_PERMISSIONS <permissions>...] - [DIRECTORY_PERMISSIONS <permissions>...] - [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS] - [FILES_MATCHING] - [[PATTERN <pattern> | REGEX <regex>] - [EXCLUDE] [PERMISSIONS <permissions>...]] [...]) - -The ``COPY`` signature copies files, directories, and symlinks to a -destination folder. Relative input paths are evaluated with respect -to the current source directory, and a relative destination is -evaluated with respect to the current build directory. Copying -preserves input file timestamps, and optimizes out a file if it exists -at the destination with the same timestamp. Copying preserves input -permissions unless explicit permissions or ``NO_SOURCE_PERMISSIONS`` -are given (default is ``USE_SOURCE_PERMISSIONS``). - -See the :command:`install(DIRECTORY)` command for documentation of -permissions, ``FILES_MATCHING``, ``PATTERN``, ``REGEX``, and -``EXCLUDE`` options. Copying directories preserves the structure -of their content even if options are used to select a subset of -files. - -The ``INSTALL`` signature differs slightly from ``COPY``: it prints -status messages (subject to the :variable:`CMAKE_INSTALL_MESSAGE` variable), -and ``NO_SOURCE_PERMISSIONS`` is default. -Installation scripts generated by the :command:`install` command -use this signature (with some undocumented options for internal use). +Locking +^^^^^^^ ------------------------------------------------------------------------------- +.. _LOCK: :: 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 83f4716..a4416ab 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] @@ -176,7 +177,7 @@ claim compatibility with the version requested it is unspecified which one is chosen: unless the variable :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` is set no attempt is made to choose a highest or closest version number. -To control the order in which ``find_package`` checks for compatibiliy use +To control the order in which ``find_package`` checks for compatibility use the two variables :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` and :variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION`. For instance in order to select the highest version one can set:: @@ -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,16 @@ 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 :variable:`<PackageName>_ROOT` CMake + variable and the :envvar:`<PackageName>_ROOT` environment variable, + where ``<PackageName>`` is the package to be found. + 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 +280,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 +291,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 +318,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/foreach.rst b/Help/command/foreach.rst index c0f3679..106ba73 100644 --- a/Help/command/foreach.rst +++ b/Help/command/foreach.rst @@ -26,14 +26,14 @@ list. Foreach can also iterate over a generated range of numbers. There are three types of this iteration: -* When specifying single number, the range will have elements 0 to - "total". +* When specifying single number, the range will have elements [0, ... to + "total"] (inclusive). * When specifying two numbers, the range will have elements from the - first number to the second number. + first number to the second number (inclusive). * The third optional number is the increment used to iterate from the - first number to the second number. + first number to the second number (inclusive). :: 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_filename_component.rst b/Help/command/get_filename_component.rst index 14c8cf2..f11c0fc 100644 --- a/Help/command/get_filename_component.rst +++ b/Help/command/get_filename_component.rst @@ -45,7 +45,7 @@ to the given base directory ``<BASE_DIR>``. If no base directory is provided, the default base directory will be :variable:`CMAKE_CURRENT_SOURCE_DIR`. -Paths are returned with forward slashes and have no trailing slahes. If the +Paths are returned with forward slashes and have no trailing slashes. If the optional ``CACHE`` argument is specified, the result variable is added to the cache. 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..51fbd33 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 inherited properties will search the relevant +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..98e9db3 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 inherited properties will search the +relevant 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..555c3b2 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 inherited properties will search the +relevant 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 58438b7..6cea996 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -1,11 +1,19 @@ install ------- -.. only:: html +Specify rules to run at install time. - .. contents:: +Synopsis +^^^^^^^^ -Specify rules to run at install time. +.. parsed-literal:: + + install(`TARGETS`_ <target>... [...]) + install({`FILES`_ | `PROGRAMS`_} <file>... DESTINATION <dir> [...]) + install(`DIRECTORY`_ <dir>... DESTINATION <dir> [...]) + install(`SCRIPT`_ <file> [...]) + install(`CODE`_ <code> [...]) + install(`EXPORT`_ <export-name> DESTINATION <dir> [...]) Introduction ^^^^^^^^^^^^ @@ -38,7 +46,21 @@ signatures that specify them. The common options are: ``CONFIGURATIONS`` Specify a list of build configurations for which the install rule - applies (Debug, Release, etc.). + applies (Debug, Release, etc.). Note that the values specified for + this option only apply to options listed AFTER the ``CONFIGURATIONS`` + option. For example, to set separate install paths for the Debug and + Release configurations, do the following: + + .. code-block:: cmake + + install(TARGETS target + CONFIGURATIONS Debug + RUNTIME DESTINATION Debug/bin) + install(TARGETS target + CONFIGURATIONS Release + RUNTIME DESTINATION Release/bin) + + Note that ``CONFIGURATIONS`` appears BEFORE ``RUNTIME DESTINATION``. ``COMPONENT`` Specify an installation component name with which the install rule @@ -70,6 +92,8 @@ to control which messages are printed. Installing Targets ^^^^^^^^^^^^^^^^^^ +.. _TARGETS: + :: install(TARGETS targets... [EXPORT <export-name>] @@ -79,6 +103,7 @@ Installing Targets [PERMISSIONS permissions...] [CONFIGURATIONS [Debug|Release|...]] [COMPONENT <component>] + [NAMELINK_COMPONENT <component>] [OPTIONAL] [EXCLUDE_FROM_ALL] [NAMELINK_ONLY|NAMELINK_SKIP] ] [...] @@ -86,63 +111,144 @@ Installing Targets ) The ``TARGETS`` form specifies rules for installing targets from a -project. There are six kinds of target files that may be installed: -``ARCHIVE``, ``LIBRARY``, ``RUNTIME``, ``OBJECTS``, ``FRAMEWORK``, and -``BUNDLE``. Executables are treated as ``RUNTIME`` targets, except that -those marked with the ``MACOSX_BUNDLE`` property are treated as ``BUNDLE`` -targets on OS X. Static libraries are treated as ``ARCHIVE`` targets, -except that those marked with the ``FRAMEWORK`` property are treated -as ``FRAMEWORK`` targets on OS X. -Module libraries are always treated as ``LIBRARY`` targets. -For non-DLL platforms shared libraries are treated as ``LIBRARY`` -targets, except that those marked with the ``FRAMEWORK`` property are -treated as ``FRAMEWORK`` targets on OS X. For DLL platforms the DLL -part of a shared library is treated as a ``RUNTIME`` target and the -corresponding import library is treated as an ``ARCHIVE`` target. -All Windows-based systems including Cygwin are DLL platforms. Object -libraries are always treated as ``OBJECTS`` targets. -The ``ARCHIVE``, ``LIBRARY``, ``RUNTIME``, ``OBJECTS``, and ``FRAMEWORK`` -arguments change the type of target to which the subsequent properties -apply. If none is given the installation properties apply to all target -types. If only one is given then only targets of that type will be -installed (which can be used to install just a DLL or just an import -library). - -The ``PRIVATE_HEADER``, ``PUBLIC_HEADER``, and ``RESOURCE`` arguments -cause subsequent properties to be applied to installing a ``FRAMEWORK`` -shared library target's associated files on non-Apple platforms. Rules -defined by these arguments are ignored on Apple platforms because the -associated files are installed into the appropriate locations inside -the framework folder. See documentation of the -:prop_tgt:`PRIVATE_HEADER`, :prop_tgt:`PUBLIC_HEADER`, and -:prop_tgt:`RESOURCE` target properties for details. - -Either ``NAMELINK_ONLY`` or ``NAMELINK_SKIP`` may be specified as a -``LIBRARY`` option. On some platforms a versioned shared library -has a symbolic link such as:: - - lib<name>.so -> lib<name>.so.1 - -where ``lib<name>.so.1`` is the soname of the library and ``lib<name>.so`` -is a "namelink" allowing linkers to find the library when given -``-l<name>``. The ``NAMELINK_ONLY`` option causes installation of only the -namelink when a library target is installed. The ``NAMELINK_SKIP`` option -causes installation of library files other than the namelink when a -library target is installed. When neither option is given both -portions are installed. On platforms where versioned shared libraries -do not have namelinks or when a library is not versioned the -``NAMELINK_SKIP`` option installs the library and the ``NAMELINK_ONLY`` -option installs nothing. See the :prop_tgt:`VERSION` and -:prop_tgt:`SOVERSION` target properties for details on creating versioned -shared libraries. - -The ``INCLUDES DESTINATION`` specifies a list of directories -which will be added to the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` -target property of the ``<targets>`` when exported by the -:command:`install(EXPORT)` command. If a relative path is -specified, it is treated as relative to the ``$<INSTALL_PREFIX>``. -This is independent of the rest of the argument groups and does -not actually install anything. +project. There are several kinds of target files that may be installed: + +``ARCHIVE`` + Static libraries are treated as ``ARCHIVE`` targets, except those + marked with the ``FRAMEWORK`` property on OS X (see ``FRAMEWORK`` + below.) For DLL platforms (all Windows-based systems including + Cygwin), the DLL import library is treated as an ``ARCHIVE`` target. + +``LIBRARY`` + Module libraries are always treated as ``LIBRARY`` targets. For non- + DLL platforms shared libraries are treated as ``LIBRARY`` targets, + except those marked with the ``FRAMEWORK`` property on OS X (see + ``FRAMEWORK`` below.) + +``RUNTIME`` + Executables are treated as ``RUNTIME`` objects, except those marked + with the ``MACOSX_BUNDLE`` property on OS X (see ``BUNDLE`` below.) + For DLL platforms (all Windows-based systems including Cygwin), the + DLL part of a shared library is treated as a ``RUNTIME`` target. + +``OBJECTS`` + Object libraries (a simple group of object files) are always treated + as ``OBJECTS`` targets. + +``FRAMEWORK`` + Both static and shared libraries marked with the ``FRAMEWORK`` + property are treated as ``FRAMEWORK`` targets on OS X. + +``BUNDLE`` + Executables marked with the ``MACOSX_BUNDLE`` property are treated as + ``BUNDLE`` targets on OS X. + +``PUBLIC_HEADER`` + Any ``PUBLIC_HEADER`` files associated with a library are installed in + the destination specified by the ``PUBLIC_HEADER`` argument on non-Apple + platforms. Rules defined by this argument are ignored for ``FRAMEWORK`` + libraries on Apple platforms because the associated files are installed + into the appropriate locations inside the framework folder. See + :prop_tgt:`PUBLIC_HEADER` for details. + +``PRIVATE_HEADER`` + Similar to ``PUBLIC_HEADER``, but for ``PRIVATE_HEADER`` files. See + :prop_tgt:`PRIVATE_HEADER` for details. + +``RESOURCE`` + Similar to ``PUBLIC_HEADER`` and ``PRIVATE_HEADER``, but for + ``RESOURCE`` files. See :prop_tgt:`RESOURCE` for details. + +For each of these arguments given, the arguments following them only apply +to the target or file type specified in the argument. If none is given, the +installation properties apply to all target types. If only one is given then +only targets of that type will be installed (which can be used to install +just a DLL or just an import library.) + +In addition to the common options listed above, each target can accept +the following additional arguments: + +``NAMELINK_COMPONENT`` + On some platforms a versioned shared library has a symbolic link such + as:: + + lib<name>.so -> lib<name>.so.1 + + where ``lib<name>.so.1`` is the soname of the library and ``lib<name>.so`` + is a "namelink" allowing linkers to find the library when given + ``-l<name>``. The ``NAMELINK_COMPONENT`` option is similar to the + ``COMPONENT`` option, but it changes the installation component of a shared + library namelink if one is generated. If not specified, this defaults to the + value of ``COMPONENT``. It is an error to use this parameter outside of a + ``LIBRARY`` block. + + Consider the following example: + + .. code-block:: cmake + + install(TARGETS mylib + LIBRARY + DESTINATION lib + COMPONENT Libraries + NAMELINK_COMPONENT Development + PUBLIC_HEADER + DESTINATION include + COMPONENT Development + ) + + In this scenario, if you choose to install only the ``Development`` + component, both the headers and namelink will be installed without the + library. (If you don't also install the ``Libraries`` component, the + namelink will be a dangling symlink, and projects that link to the library + will have build errors.) If you install only the ``Libraries`` component, + only the library will be installed, without the headers and namelink. + + This option is typically used for package managers that have separate + runtime and development packages. For example, on Debian systems, the + library is expected to be in the runtime package, and the headers and + namelink are expected to be in the development package. + + See the :prop_tgt:`VERSION` and :prop_tgt:`SOVERSION` target properties for + details on creating versioned shared libraries. + +``NAMELINK_ONLY`` + This option causes the installation of only the namelink when a library + target is installed. On platforms where versioned shared libraries do not + have namelinks or when a library is not versioned, the ``NAMELINK_ONLY`` + option installs nothing. It is an error to use this parameter outside of a + ``LIBRARY`` block. + + When ``NAMELINK_ONLY`` is given, either ``NAMELINK_COMPONENT`` or + ``COMPONENT`` may be used to specify the installation component of the + namelink, but ``COMPONENT`` should generally be preferred. + +``NAMELINK_SKIP`` + Similar to ``NAMELINK_ONLY``, but it has the opposite effect: it causes the + installation of library files other than the namelink when a library target + is installed. When neither ``NAMELINK_ONLY`` or ``NAMELINK_SKIP`` are given, + both portions are installed. On platforms where versioned shared libraries + do not have symlinks or when a library is not versioned, ``NAMELINK_SKIP`` + installs the library. It is an error to use this parameter outside of a + ``LIBRARY`` block. + + If ``NAMELINK_SKIP`` is specified, ``NAMELINK_COMPONENT`` has no effect. It + is not recommended to use ``NAMELINK_SKIP`` in conjunction with + ``NAMELINK_COMPONENT``. + +The ``install(TARGETS)`` command can also accept the following options at the +top level: + +``EXPORT`` + This option associates the installed target files with an export called + ``<export-name>``. It must appear before any target options. To actually + install the export file itself, call ``install(EXPORT)``, documented below. + +``INCLUDES DESTINATION`` + This option specifies a list of directories which will be added to the + :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property of the + ``<targets>`` when exported by the :command:`install(EXPORT)` command. If a + relative path is specified, it is treated as relative to the + ``$<INSTALL_PREFIX>``. One or more groups of properties may be specified in a single call to the ``TARGETS`` form of this command. A target may be installed more than @@ -164,10 +270,12 @@ the ``mySharedLib`` DLL will be installed to ``<prefix>/bin`` and ``/some/full/path`` and its import library will be installed to ``<prefix>/lib/static`` and ``/some/full/path``. -The ``EXPORT`` option associates the installed target files with an -export called ``<export-name>``. It must appear before any ``RUNTIME``, -``LIBRARY``, ``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. @@ -179,6 +287,9 @@ use "generator expressions" with the syntax ``$<...>``. See the Installing Files ^^^^^^^^^^^^^^^^ +.. _FILES: +.. _PROGRAMS: + :: install(<FILES|PROGRAMS> files... DESTINATION <dir> @@ -212,6 +323,8 @@ use "generator expressions" with the syntax ``$<...>``. See the Installing Directories ^^^^^^^^^^^^^^^^^^^^^^ +.. _DIRECTORY: + :: install(DIRECTORY dirs... DESTINATION <dir> @@ -293,6 +406,9 @@ manual for available expressions. Custom Installation Logic ^^^^^^^^^^^^^^^^^^^^^^^^^ +.. _CODE: +.. _SCRIPT: + :: install([[SCRIPT <file>] [CODE <code>]] @@ -314,16 +430,18 @@ will print a message during installation. Installing Exports ^^^^^^^^^^^^^^^^^^ +.. _EXPORT: + :: 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. @@ -340,14 +458,28 @@ generated import file will reference only the matching target configurations. The ``EXPORT_LINK_INTERFACE_LIBRARIES`` keyword, if present, causes the contents of the properties matching ``(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?`` to be exported, when -policy :policy:`CMP0022` is ``NEW``. If a ``COMPONENT`` option is -specified that does not match that given to the targets associated with -``<export-name>`` the behavior is undefined. If a library target is -included in the export but a target to which it links is not included -the behavior is unspecified. - -In additon to cmake language files, the ``EXPORT_ANDROID_MK`` option maybe -used to specifiy an export to the android ndk build system. The Android +policy :policy:`CMP0022` is ``NEW``. + +When a ``COMPONENT`` option is given, the listed ``<component>`` implicitly +depends on all components mentioned in the export set. The exported +``<name>.cmake`` file will require each of the exported components to be +present in order for dependent projects to build properly. For example, a +project may define components ``Runtime`` and ``Development``, with shared +libraries going into the ``Runtime`` component and static libraries and +headers going into the ``Development`` component. The export set would also +typically be part of the ``Development`` component, but it would export +targets from both the ``Runtime`` and ``Development`` components. Therefore, +the ``Runtime`` component would need to be installed if the ``Development`` +component was installed, but not vice versa. If the ``Development`` component +was installed without the ``Runtime`` component, dependent projects that try +to link against it would have build errors. Package managers, such as APT and +RPM, typically handle this by listing the ``Runtime`` component as a dependency +of the ``Development`` component in the package metadata, ensuring that the +library is always installed if the headers and CMake export file are present. + +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 @@ -364,7 +496,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. @@ -378,3 +510,26 @@ executable from the installation tree using the imported target name those generated by :command:`install_targets`, :command:`install_files`, and :command:`install_programs` commands is not defined. + +Generated Installation Script +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``install()`` command generates a file, ``cmake_install.cmake``, inside +the build directory, which is used internally by the generated install target +and by CPack. You can also invoke this script manually with ``cmake -P``. This +script accepts several variables: + +``COMPONENT`` + Set this variable to install only a single CPack component as opposed to all + of them. For example, if you only want to install the ``Development`` + component, run ``cmake -DCOMPONENT=Development -P cmake_install.cmake``. + +``BUILD_TYPE`` + Set this variable to change the build type if you are using a multi-config + generator. For example, to install with the ``Debug`` configuration, run + ``cmake -DBUILD_TYPE=Debug -P cmake_install.cmake``. + +``DESTDIR`` + This is an environment variable rather than a CMake variable. It allows you + to change the installation prefix on UNIX systems. See :envvar:`DESTDIR` for + details. diff --git a/Help/command/list.rst b/Help/command/list.rst index f6b75bc..589e572 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst @@ -3,66 +3,257 @@ list List operations. +Synopsis +^^^^^^^^ + +.. parsed-literal:: + + `Reading`_ + list(`LENGTH`_ <list> <out-var>) + list(`GET`_ <list> <element index> [<index> ...] <out-var>) + list(`JOIN`_ <list> <glue> <out-var>) + list(`SUBLIST`_ <list> <begin> <length> <out-var>) + + `Search`_ + list(`FIND`_ <list> <value> <out-var>) + + `Modification`_ + list(`APPEND`_ <list> [<element>...]) + list(`FILTER`_ <list> {INCLUDE | EXCLUDE} REGEX <regex>) + list(`INSERT`_ <list> <index> [<element>...]) + list(`REMOVE_ITEM`_ <list> <value>...) + list(`REMOVE_AT`_ <list> <index>...) + list(`REMOVE_DUPLICATES`_ <list>) + list(`TRANSFORM`_ <list> <ACTION> [...]) + + `Ordering`_ + list(`REVERSE`_ <list>) + list(`SORT`_ <list>) + +Introduction +^^^^^^^^^^^^ + +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. + +Reading +^^^^^^^ + +.. _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> ...]) + +Removes items at given indices from the list. + +.. _REMOVE_DUPLICATES: + +:: + list(REMOVE_DUPLICATES <list>) - list(REVERSE <list>) - list(SORT <list>) -``LENGTH`` will return a given list's length. +Removes duplicated items in the list. -``GET`` will return list of elements specified by indices from the list. +.. _TRANSFORM: -``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(TRANSFORM <list> <ACTION> [<SELECTOR>] + [OUTPUT_VARIABLE <output variable>]) -``FIND`` will return the index of the element specified in the list or -1 -if it wasn't found. +Transforms the list by applying an action to all or, by specifying a +``<SELECTOR>``, to the selected elements of the list, storing result in-place +or in the specified output variable. -``INSERT`` will insert elements to the list to the specified location. +.. note:: -``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. + ``TRANSFORM`` sub-command does not change the number of elements of the + list. If a ``<SELECTOR>`` is specified, only some elements will be changed, + the other ones will remain same as before the transformation. -``REMOVE_DUPLICATES`` will remove duplicated items in the list. +``<ACTION>`` specify the action to apply to the elements of list. +The actions have exactly the same semantics as sub-commands of +:command:`string` command. -``REVERSE`` reverses the contents of the list in-place. +The ``<ACTION>`` may be one of: -``SORT`` sorts the list in-place alphabetically. +``APPEND``, ``PREPEND``: Append, prepend specified value to each element of +the list. :: + + list(TRANSFORM <list> <APPEND|PREPEND> <value> ...) + +``TOUPPER``, ``TOLOWER``: Convert each element of the list to upper, lower +characters. :: + + list(TRANSFORM <list> <TOLOWER|TOUPPER> ...) + +``STRIP``: Remove leading and trailing spaces from each element of the +list. :: + + list(TRANSFORM <list> STRIP ...) + +``GENEX_STRIP``: Strip any +:manual:`generator expressions <cmake-generator-expressions(7)>` from each +element of the list. :: + + list(TRANSFORM <list> GENEX_STRIP ...) + +``REPLACE``: Match the regular expression as many times as possible and +substitute the replacement expression for the match for each element +of the list +(Same semantic as ``REGEX REPLACE`` from :command:`string` command). :: + + list(TRANSFORM <list> REPLACE <regular_expression> + <replace_expression> ...) + +``<SELECTOR>`` select which elements of the list will be transformed. Only one +type of selector can be specified at a time. + +The ``<SELECTOR>`` may be one of: + +``AT``: Specify a list of indexes. :: + + list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...) + +``FOR``: Specify a range with, optionally, an increment used to iterate over +the range. :: + + list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...) + +``REGEX``: Specify a regular expression. Only elements matching the regular +expression will be transformed. :: + + list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...) + + +Ordering +^^^^^^^^ + +.. _REVERSE: + +:: + + list(REVERSE <list>) + +Reverses the contents of the list in-place. + +.. _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 139f69c..c1de057 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,16 +42,29 @@ 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 are ``C``, ``CXX`` (i.e. C++), ``Fortran``, etc. +Example languages include ``C``, ``CXX`` (i.e. C++), ``CUDA``, +``Fortran``, and ``ASM``. By default ``C`` and ``CXX`` are enabled if no language options are given. Specify language ``NONE``, or use the ``LANGUAGES`` keyword and list no languages, to skip enabling any languages. +If enabling ``ASM``, list it last so that CMake can check whether +compilers for other languages like ``C`` work for assembly too. + If a variable exists called :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, the file pointed to by that variable will be included as the last step of the project command. @@ -59,7 +73,12 @@ 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`, its homepage URL from +:variable:`CMAKE_PROJECT_HOMEPAGE_URL` and its version from +:variable:`CMAKE_PROJECT_VERSION`. .. 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..efa923b 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -1,17 +1,52 @@ string ------ -.. only:: html - - .. contents:: - String operations. +Synopsis +^^^^^^^^ + +.. parsed-literal:: + + `Search and Replace`_ + string(`FIND`_ <string> <substring> <out-var> [...]) + string(`REPLACE`_ <match-string> <replace-string> <out-var> <input>...) + + `Regular Expressions`_ + string(`REGEX MATCH`_ <match-regex> <out-var> <input>...) + string(`REGEX MATCHALL`_ <match-regex> <out-var> <input>...) + string(`REGEX REPLACE`_ <match-regex> <replace-expr> <out-var> <input>...) + + `Manipulation`_ + string(`APPEND`_ <string-var> [<input>...]) + string(`PREPEND`_ <string-var> [<input>...]) + string(`CONCAT`_ <out-var> [<input>...]) + string(`JOIN`_ <glue> <out-var> [<input>...]) + string(`TOLOWER`_ <string1> <out-var>) + string(`TOUPPER`_ <string1> <out-var>) + string(`LENGTH`_ <string> <out-var>) + string(`SUBSTRING`_ <string> <begin> <length> <out-var>) + string(`STRIP`_ <string> <out-var>) + string(`GENEX_STRIP`_ <string> <out-var>) + + `Comparison`_ + string(`COMPARE`_ <op> <string1> <string2> <out-var>) + + `Hashing`_ + string(`\<HASH\> <HASH_>`_ <out-var> <input>) + + `Generation`_ + string(`ASCII`_ <number>... <out-var>) + string(`CONFIGURE`_ <string1> <out-var> [...]) + string(`MAKE_C_IDENTIFIER`_ <string> <out-var>) + string(`RANDOM`_ [<option>...] <out-var>) + string(`TIMESTAMP`_ <out-var> [<format string>] [UTC]) + string(`UUID`_ <out-var> ...) + Search and Replace ^^^^^^^^^^^^^^^^^^ -FIND -"""" +.. _FIND: :: @@ -22,8 +57,7 @@ the supplied string. If the ``REVERSE`` flag was used, the command will search for the position of the last occurrence of the specified substring. If the substring is not found, a position of -1 is returned. -REPLACE -""""""" +.. _REPLACE: :: @@ -37,8 +71,7 @@ with ``replace_string`` and store the result in the output. Regular Expressions ^^^^^^^^^^^^^^^^^^^ -REGEX MATCH -""""""""""" +.. _`REGEX MATCH`: :: @@ -48,8 +81,7 @@ REGEX MATCH Match the regular expression once and store the match in the output variable. All ``<input>`` arguments are concatenated before matching. -REGEX MATCHALL -"""""""""""""" +.. _`REGEX MATCHALL`: :: @@ -60,8 +92,7 @@ Match the regular expression as many times as possible and store the matches in the output variable as a list. All ``<input>`` arguments are concatenated before matching. -REGEX REPLACE -""""""""""""" +.. _`REGEX REPLACE`: :: @@ -123,8 +154,7 @@ expression ``^(ab|cd)$`` matches ``ab`` but not ``abd``. Manipulation ^^^^^^^^^^^^ -APPEND -"""""" +.. _APPEND: :: @@ -132,8 +162,7 @@ APPEND Append all the input arguments to the string. -PREPEND -""""""" +.. _PREPEND: :: @@ -141,8 +170,7 @@ PREPEND Prepend all the input arguments to the string. -CONCAT -"""""" +.. _CONCAT: :: @@ -151,8 +179,20 @@ CONCAT Concatenate all the input arguments together and store the result in the named output variable. -TOLOWER -""""""" +.. _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: :: @@ -160,8 +200,7 @@ TOLOWER Convert string to lower characters. -TOUPPER -""""""" +.. _TOUPPER: :: @@ -169,8 +208,7 @@ TOUPPER Convert string to upper characters. -LENGTH -"""""" +.. _LENGTH: :: @@ -178,8 +216,7 @@ LENGTH Store in an output variable a given string's length. -SUBSTRING -""""""""" +.. _SUBSTRING: :: @@ -193,8 +230,7 @@ If string is shorter than length then end of string is used instead. CMake 3.1 and below reported an error if length pointed past the end of string. -STRIP -""""" +.. _STRIP: :: @@ -203,8 +239,7 @@ STRIP Store in an output variable a substring of a given string with leading and trailing spaces removed. -GENEX_STRIP -""""""""""" +.. _GENEX_STRIP: :: @@ -216,6 +251,8 @@ from the ``input string`` and store the result in the ``output variable``. Comparison ^^^^^^^^^^ +.. _COMPARE: + :: string(COMPARE LESS <string1> <string2> <output variable>) @@ -232,6 +269,8 @@ Compare the strings and store true or false in the output variable. Hashing ^^^^^^^ +.. _`HASH`: + :: string(<HASH> <output variable> <input>) @@ -263,8 +302,7 @@ The supported ``<HASH>`` algorithm names are: Generation ^^^^^^^^^^ -ASCII -""""" +.. _ASCII: :: @@ -272,8 +310,7 @@ ASCII Convert all numbers into corresponding ASCII characters. -CONFIGURE -""""""""" +.. _CONFIGURE: :: @@ -282,8 +319,18 @@ CONFIGURE Transform a string like :command:`configure_file` transforms a file. -RANDOM -"""""" +.. _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: :: @@ -296,8 +343,7 @@ and default alphabet is all numbers and upper and lower case letters. If an integer ``RANDOM_SEED`` is given, its value will be used to seed the random number generator. -TIMESTAMP -""""""""" +.. _TIMESTAMP: :: @@ -346,28 +392,20 @@ 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, its value will be used instead of the current time. See https://reproducible-builds.org/specs/source-date-epoch/ for details. -UUID -"""" +.. _UUID: :: string(UUID <output variable> NAMESPACE <namespace> NAME <name> TYPE <MD5|SHA1> [UPPER]) -Create a univerally unique identifier (aka GUID) as per RFC4122 +Create a universally unique identifier (aka GUID) as per RFC4122 based on the hash of the combined values of ``<namespace>`` (which itself has to be a valid UUID) and ``<name>``. The hash algorithm can be either ``MD5`` (Version 3 UUID) or diff --git a/Help/command/target_compile_definitions.rst b/Help/command/target_compile_definitions.rst index 8bd3233..a740117 100644 --- a/Help/command/target_compile_definitions.rst +++ b/Help/command/target_compile_definitions.rst @@ -12,17 +12,28 @@ Add compile definitions to a target. Specify compile definitions to use when compiling a given ``<target>``. The named ``<target>`` must have been created by a command such as :command:`add_executable` or :command:`add_library` and must not be an -:ref:`Imported Target <Imported Targets>`. +:ref:`ALIAS target <Alias Targets>`. The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`COMPILE_DEFINITIONS` property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the -:prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` property of ``<target>``. The -following arguments specify compile definitions. Repeated calls for the +:prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` property of ``<target>``. +(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items.) +The following arguments specify compile definitions. Repeated calls for the same ``<target>`` append items in the order called. Arguments to ``target_compile_definitions`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. See the :manual:`cmake-buildsystem(7)` manual for more on defining buildsystem properties. + +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_features.rst b/Help/command/target_compile_features.rst index b66a4ec..bf413bf 100644 --- a/Help/command/target_compile_features.rst +++ b/Help/command/target_compile_features.rst @@ -18,12 +18,13 @@ The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to specify the scope of the features. ``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`COMPILE_FEATURES` property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the -:prop_tgt:`INTERFACE_COMPILE_FEATURES` property of ``<target>``. Repeated -calls for the same ``<target>`` append items. +:prop_tgt:`INTERFACE_COMPILE_FEATURES` property of ``<target>``. +(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items.) +Repeated calls for the same ``<target>`` append items. The named ``<target>`` must have been created by a command such as -:command:`add_executable` or :command:`add_library` and must not be -an ``IMPORTED`` target. +:command:`add_executable` or :command:`add_library` and must not be an +:ref:`ALIAS target <Alias Targets>`. Arguments to ``target_compile_features`` may use "generator expressions" with the syntax ``$<...>``. diff --git a/Help/command/target_compile_options.rst b/Help/command/target_compile_options.rst index 73e01e7..194d008 100644 --- a/Help/command/target_compile_options.rst +++ b/Help/command/target_compile_options.rst @@ -12,13 +12,15 @@ Add compile options to a target. Specify compile options to use when compiling a given target. The named ``<target>`` must have been created by a command such as :command:`add_executable` or :command:`add_library` and must not be an -:ref:`IMPORTED Target <Imported Targets>`. If ``BEFORE`` is specified, -the content will be prepended to the property instead of being appended. +:ref:`ALIAS target <Alias Targets>`. + +If ``BEFORE`` is specified, the content will be prepended to the property +instead of being appended. This command can be used to add any options, but alternative commands exist to add preprocessor definitions -(:command:`target_compile_definitions` and :command:`add_definitions`) or -include directories (:command:`target_include_directories` and +(:command:`target_compile_definitions` and :command:`add_compile_definitions`) +or include directories (:command:`target_include_directories` and :command:`include_directories`). See documentation of the :prop_dir:`directory <COMPILE_OPTIONS>` and :prop_tgt:`target <COMPILE_OPTIONS>` ``COMPILE_OPTIONS`` properties. @@ -27,11 +29,14 @@ The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`COMPILE_OPTIONS` property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the -:prop_tgt:`INTERFACE_COMPILE_OPTIONS` property of ``<target>``. The -following arguments specify compile options. Repeated calls for the same +:prop_tgt:`INTERFACE_COMPILE_OPTIONS` property of ``<target>``. +(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items.) +The following arguments specify compile options. Repeated calls for the same ``<target>`` append items in the order called. Arguments to ``target_compile_options`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. See the :manual:`cmake-buildsystem(7)` manual for more on defining buildsystem properties. + +.. include:: COMPILE_OPTIONS_SHELL.txt diff --git a/Help/command/target_include_directories.rst b/Help/command/target_include_directories.rst index 30ec2cb..e71be64 100644 --- a/Help/command/target_include_directories.rst +++ b/Help/command/target_include_directories.rst @@ -12,7 +12,7 @@ Add include directories to a target. Specify include directories to use when compiling a given target. The named ``<target>`` must have been created by a command such as :command:`add_executable` or :command:`add_library` and must not be an -:prop_tgt:`IMPORTED` target. +:ref:`ALIAS target <Alias Targets>`. If ``BEFORE`` is specified, the content will be prepended to the property instead of being appended. @@ -21,9 +21,9 @@ The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`INCLUDE_DIRECTORIES` property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the -:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` -property of ``<target>``. The following arguments specify include -directories. +:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` property of ``<target>``. +(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items.) +The following arguments specify include directories. Specified include directories may be absolute paths or relative paths. Repeated calls for the same <target> append items in the order called. If diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst index 30d69f2..fcc2c07 100644 --- a/Help/command/target_link_libraries.rst +++ b/Help/command/target_link_libraries.rst @@ -19,7 +19,8 @@ All of them have the general form:: target_link_libraries(<target> ... <item>... ...) The named ``<target>`` must have been created in the current directory by -a command such as :command:`add_executable` or :command:`add_library`. +a command such as :command:`add_executable` or :command:`add_library` and +must not be an :ref:`ALIAS target <Alias Targets>`. Repeated calls for the same ``<target>`` append items in the order called. Each ``<item>`` may be: @@ -182,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/command/target_sources.rst b/Help/command/target_sources.rst index d6f148d..a4f5196 100644 --- a/Help/command/target_sources.rst +++ b/Help/command/target_sources.rst @@ -12,14 +12,15 @@ Add sources to a target. Specify sources to use when compiling a given target. The named ``<target>`` must have been created by a command such as :command:`add_executable` or :command:`add_library` and must not be an -:ref:`IMPORTED Target <Imported Targets>`. +:ref:`ALIAS target <Alias Targets>`. The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`SOURCES` property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the -:prop_tgt:`INTERFACE_SOURCES` property of ``<target>``. The -following arguments specify sources. Repeated calls for the same +:prop_tgt:`INTERFACE_SOURCES` property of ``<target>``. +(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items.) +The following arguments specify sources. Repeated calls for the same ``<target>`` append items in the order called. Arguments to ``target_sources`` may use "generator expressions" diff --git a/Help/dev/maint.rst b/Help/dev/maint.rst index bdfb3d0..ec76479 100644 --- a/Help/dev/maint.rst +++ b/Help/dev/maint.rst @@ -73,6 +73,13 @@ Merge the ``release-$ver`` branch to ``master``: git pull git merge --no-ff release-$ver +Review new ancestry to ensure nothing unexpected was merged to either branch: + +.. code-block:: shell + + git log --graph --boundary origin/master..master + git log --graph --boundary origin/release..release-$ver + Publish both ``master`` and ``release`` simultaneously: .. code-block:: shell diff --git a/Help/dev/review.rst b/Help/dev/review.rst index be02a1a..a524115 100644 --- a/Help/dev/review.rst +++ b/Help/dev/review.rst @@ -401,11 +401,14 @@ The ``Do: merge`` command accepts the following arguments: branch in the constructed merge commit message. Additionally, ``Do: merge`` extracts configuration from trailing lines -in the MR description: +in the MR description (the following have no effect if used in a MR +comment instead): * ``Topic-rename: <topic>``: substitute ``<topic>`` for the name of the MR topic branch in the constructed merge commit message. - The ``-t`` option overrides this. + It is also used in merge commits constructed by ``Do: stage``. + The ``-t`` option to a ``Do: merge`` command overrides any topic + rename set in the MR description. .. _`CMake GitLab Project Masters`: https://gitlab.kitware.com/cmake/cmake/settings/members diff --git a/Help/dev/source.rst b/Help/dev/source.rst index d0c19eb..57de818 100644 --- a/Help/dev/source.rst +++ b/Help/dev/source.rst @@ -9,7 +9,7 @@ See documentation on `CMake Development`_ for more information. C++ Code Style ============== -We use `clang-format`_ version **3.8** to define our style for C++ code in +We use `clang-format`_ version **6.0** to define our style for C++ code in the CMake source tree. See the `.clang-format`_ configuration file for our style settings. Use the `Utilities/Scripts/clang-format.bash`_ script to format source code. It automatically runs ``clang-format`` on the set of diff --git a/Help/dev/testing.rst b/Help/dev/testing.rst index 731930c..1b29acf 100644 --- a/Help/dev/testing.rst +++ b/Help/dev/testing.rst @@ -16,7 +16,7 @@ welcome to provide testing machines in order to help keep support for their platforms working. The `CMake Dashboard Scripts Repository`_ provides CTest scripts to drive -nightly, continous, and experimental testing of CMake. Use the following +nightly, continuous, and experimental testing of CMake. Use the following commands to set up a new integration testing client: .. code-block:: console diff --git a/Help/envvar/CMAKE_BUILD_PARALLEL_LEVEL.rst b/Help/envvar/CMAKE_BUILD_PARALLEL_LEVEL.rst new file mode 100644 index 0000000..198dc51 --- /dev/null +++ b/Help/envvar/CMAKE_BUILD_PARALLEL_LEVEL.rst @@ -0,0 +1,9 @@ +CMAKE_BUILD_PARALLEL_LEVEL +-------------------------- + +Specifies the maximum number of concurrent processes to use when building +using the ``cmake --build`` command line +:ref:`Build Tool Mode <Build Tool Mode>`. + +If this variable is defined empty the native build tool's default number is +used. diff --git a/Help/envvar/DESTDIR.rst b/Help/envvar/DESTDIR.rst new file mode 100644 index 0000000..87f1115 --- /dev/null +++ b/Help/envvar/DESTDIR.rst @@ -0,0 +1,19 @@ +DESTDIR +------- + +On UNIX one can use the ``DESTDIR`` mechanism in order to relocate the +whole installation. ``DESTDIR`` means DESTination DIRectory. It is +commonly used by makefile users in order to install software at +non-default location. It is usually invoked like this: + +:: + + make DESTDIR=/home/john install + +which will install the concerned software using the installation +prefix, e.g. ``/usr/local`` prepended with the ``DESTDIR`` value which +finally gives ``/home/john/usr/local``. + +WARNING: ``DESTDIR`` may not be used on Windows because installation +prefix usually contains a drive letter like in ``C:/Program Files`` +which cannot be prepended with some other prefix. diff --git a/Help/envvar/PackageName_ROOT.rst b/Help/envvar/PackageName_ROOT.rst new file mode 100644 index 0000000..e01009b --- /dev/null +++ b/Help/envvar/PackageName_ROOT.rst @@ -0,0 +1,15 @@ +<PackageName>_ROOT +------------------ + +Calls to :command:`find_package(<PackageName>)` will search in prefixes +specified by the ``<PackageName>_ROOT`` environment variable, where +``<PackageName>`` is the name given to the ``find_package`` call +and ``_ROOT`` is literal. For example, ``find_package(Foo)`` will search +prefixes specified in the ``Foo_ROOT`` environment variable (if set). +See policy :policy:`CMP0074`. + +This variable may hold a single prefix or a list of prefixes separated +by ``:`` on UNIX or ``;`` on Windows (the same as the ``PATH`` environment +variable convention on those platforms). + +See also the :variable:`<PackageName>_ROOT` CMake variable. diff --git a/Help/generator/KDevelop3.rst b/Help/generator/KDevelop3.rst deleted file mode 100644 index eaa218b..0000000 --- a/Help/generator/KDevelop3.rst +++ /dev/null @@ -1,25 +0,0 @@ -KDevelop3 ---------- - -Generates KDevelop 3 project files. - -Project files for KDevelop 3 will be created in the top directory and -in every subdirectory which features a CMakeLists.txt file containing -a PROJECT() call. If you change the settings using KDevelop cmake -will try its best to keep your changes when regenerating the project -files. Additionally a hierarchy of UNIX makefiles is generated into -the build tree. Any standard UNIX-style make program can build the -project through the default make target. A "make install" target is -also provided. - -This "extra" generator may be specified as: - -``KDevelop3 - Unix Makefiles`` - Generate with :generator:`Unix Makefiles`. - -``KDevelop3`` - Generate with :generator:`Unix Makefiles`. - - For historical reasons this extra generator may be specified - directly as the main generator and it will be used as the - extra generator with :generator:`Unix Makefiles` automatically. diff --git a/Help/generator/Visual Studio 15 2017.rst b/Help/generator/Visual Studio 15 2017.rst index 2ac0449..2cf1aa0 100644 --- a/Help/generator/Visual Studio 15 2017.rst +++ b/Help/generator/Visual Studio 15 2017.rst @@ -19,13 +19,17 @@ Instance Selection ^^^^^^^^^^^^^^^^^^ VS 2017 supports multiple installations on the same machine. -CMake queries the Visual Studio Installer to locate VS instances. -If more than one instance is installed we do not define which one -is chosen by default. If the ``VS150COMNTOOLS`` environment variable -is set and points to the ``Common7/Tools`` directory within one of -the instances, that instance will be used. The environment variable -must remain consistently set whenever CMake is re-run within a given -build tree. +The :variable:`CMAKE_GENERATOR_INSTANCE` variable may be set as a +cache entry containing the absolute path to a Visual Studio instance. +If the value is not specified explicitly by the user or a toolchain file, +CMake queries the Visual Studio Installer to locate VS instances, chooses +one, and sets the variable as a cache entry to hold the value persistently. + +When CMake first chooses an instance, if the ``VS150COMNTOOLS`` environment +variable is set and points to the ``Common7/Tools`` directory within +one of the instances, that instance will be used. Otherwise, if more +than one instance is installed we do not define which one is chosen +by default. Toolset Selection ^^^^^^^^^^^^^^^^^ 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/index.rst b/Help/index.rst index 3dccdda..fa5273c 100644 --- a/Help/index.rst +++ b/Help/index.rst @@ -29,18 +29,18 @@ Reference Manuals /manual/cmake-commands.7 /manual/cmake-compile-features.7 /manual/cmake-developer.7 + /manual/cmake-env-variables.7 /manual/cmake-generator-expressions.7 /manual/cmake-generators.7 /manual/cmake-language.7 - /manual/cmake-server.7 /manual/cmake-modules.7 /manual/cmake-packages.7 /manual/cmake-policies.7 /manual/cmake-properties.7 /manual/cmake-qt.7 + /manual/cmake-server.7 /manual/cmake-toolchains.7 /manual/cmake-variables.7 - /manual/cmake-env-variables.7 .. only:: html or text diff --git a/Help/manual/LINKS.txt b/Help/manual/LINKS.txt index 3993ff8..8e53c0c 100644 --- a/Help/manual/LINKS.txt +++ b/Help/manual/LINKS.txt @@ -5,15 +5,11 @@ Home Page The primary starting point for learning about CMake. -Frequently Asked Questions - https://cmake.org/Wiki/CMake_FAQ - - A Wiki is provided containing answers to frequently asked questions. - -Online Documentation +Online Documentation and Community Resources https://cmake.org/documentation - Links to available documentation may be found on this web page. + Links to available documentation and community resources may be + found on this web page. Mailing List https://cmake.org/mailing-lists diff --git a/Help/manual/OPTIONS_BUILD.txt b/Help/manual/OPTIONS_BUILD.txt index e8b87c9..33d27af 100644 --- a/Help/manual/OPTIONS_BUILD.txt +++ b/Help/manual/OPTIONS_BUILD.txt @@ -11,7 +11,7 @@ cache-format file. ``-D <var>:<type>=<value>, -D <var>=<value>`` - Create a cmake cache entry. + Create or update a cmake cache entry. When cmake is first run in an empty build tree, it creates a CMakeCache.txt file and populates it with customizable settings for diff --git a/Help/manual/ccmake.1.rst b/Help/manual/ccmake.1.rst index a5fe191..cc3ceec 100644 --- a/Help/manual/ccmake.1.rst +++ b/Help/manual/ccmake.1.rst @@ -8,7 +8,7 @@ Synopsis .. parsed-literal:: - ccmake [<options>] (<path-to-source> | <path-to-existing-build>) + ccmake [<options>] {<path-to-source> | <path-to-existing-build>} Description =========== diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index ae538ed..49375e9 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 ========================================== @@ -812,7 +821,7 @@ Directory-Scoped Commands The :command:`target_include_directories`, :command:`target_compile_definitions` and :command:`target_compile_options` commands have an effect on only one -target at a time. The commands :command:`add_definitions`, +target at a time. The commands :command:`add_compile_definitions`, :command:`add_compile_options` and :command:`include_directories` have a similar function, but operate at directory scope instead of target scope for convenience. @@ -831,12 +840,11 @@ Imported Targets An :prop_tgt:`IMPORTED` target represents a pre-existing dependency. Usually such targets are defined by an upstream package and should be treated as -immutable. It is not possible to use an :prop_tgt:`IMPORTED` target in the -left-hand-side of the :command:`target_compile_definitions`, -:command:`target_include_directories`, :command:`target_compile_options` or -:command:`target_link_libraries` commands, as that would be an attempt to -modify it. :prop_tgt:`IMPORTED` targets are designed to be used only in the -right-hand-side of those commands. +immutable. After declaring an :prop_tgt:`IMPORTED` target one can adjust its +target properties by using the customary commands such as +:command:`target_compile_definitions`, :command:`target_include_directories`, +:command:`target_compile_options` or :command:`target_link_libraries` just like +with any other regular target. :prop_tgt:`IMPORTED` targets may have the same usage requirement properties populated as binary targets, such as diff --git a/Help/manual/cmake-commands.7.rst b/Help/manual/cmake-commands.7.rst index f8bfb32..408a3a0 100644 --- a/Help/manual/cmake-commands.7.rst +++ b/Help/manual/cmake-commands.7.rst @@ -70,6 +70,7 @@ These commands are available only in CMake projects. .. toctree:: :maxdepth: 1 + /command/add_compile_definitions /command/add_compile_options /command/add_custom_command /command/add_custom_target diff --git a/Help/manual/cmake-compile-features.7.rst b/Help/manual/cmake-compile-features.7.rst index 0124395..658694a 100644 --- a/Help/manual/cmake-compile-features.7.rst +++ b/Help/manual/cmake-compile-features.7.rst @@ -331,11 +331,11 @@ 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.5. +* ``SunPro``: Oracle SolarisStudio versions 12.4 through 12.6. * ``Intel``: Intel compiler versions 12.1 through 17.0. CMake is currently aware of the :prop_tgt:`C standards <C_STANDARD>` @@ -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 @@ -361,9 +361,10 @@ following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the versions specified for each: * all compilers and versions listed above with only meta-features for C++. +* ``TI``: Texas Instruments compiler. 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-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst index fed129e..42aeabc 100644 --- a/Help/manual/cmake-env-variables.7.rst +++ b/Help/manual/cmake-env-variables.7.rst @@ -13,11 +13,14 @@ Environment Variables that Control the Build .. toctree:: :maxdepth: 1 + /envvar/CMAKE_BUILD_PARALLEL_LEVEL /envvar/CMAKE_CONFIG_TYPE /envvar/CMAKE_MSVCIDE_RUN_PATH /envvar/CMAKE_OSX_ARCHITECTURES + /envvar/DESTDIR /envvar/LDFLAGS /envvar/MACOSX_DEPLOYMENT_TARGET + /envvar/PackageName_ROOT Environment Variables for Languages =================================== diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index bddb174..8fd07d7 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 @@ -97,22 +101,38 @@ Available logical expressions are: compile features and a list of supported compilers. ``$<COMPILE_LANGUAGE:lang>`` ``1`` when the language used for compilation unit matches ``lang``, - otherwise ``0``. This expression used to specify compile options for - source files of a particular language in a target. For example, to specify - the use of the ``-fno-exceptions`` compile option (compiler id checks - elided): + otherwise ``0``. This expression may be used to specify compile options, + compile definitions, and include directories for source files of a + particular language in a target. For example: .. code-block:: cmake - add_executable(myapp main.cpp foo.c bar.cpp) + add_executable(myapp main.cpp foo.c bar.cpp zot.cu) target_compile_options(myapp PRIVATE $<$<COMPILE_LANGUAGE:CXX>:-fno-exceptions> ) + target_compile_definitions(myapp + PRIVATE $<$<COMPILE_LANGUAGE:CXX>:COMPILING_CXX> + $<$<COMPILE_LANGUAGE:CUDA>:COMPILING_CUDA> + ) + target_include_directories(myapp + PRIVATE $<$<COMPILE_LANGUAGE:CXX>:/opt/foo/cxx_headers> + ) - This generator expression has limited use because it is not possible to - use it with the Visual Studio generators. Portable buildsystems would - not use this expression, and would create separate libraries for each - source file language instead: + This specifies the use of the ``-fno-exceptions`` compile option, + ``COMPILING_CXX`` compile definition, and ``cxx_headers`` include + directory for C++ only (compiler id checks elided). It also specifies + a ``COMPILING_CUDA`` compile definition for CUDA. + + Note that with :ref:`Visual Studio Generators` and :generator:`Xcode` there + is no way to represent target-wide compile definitions or include directories + separately for ``C`` and ``CXX`` languages. + Also, with :ref:`Visual Studio Generators` there is no way to represent + target-wide flags separately for ``C`` and ``CXX`` languages. Under these + generators, expressions for both C and C++ sources will be evaluated + using ``CXX`` if there are any C++ sources and otherwise using ``C``. + A workaround is to create separate libraries for each source file language + instead: .. code-block:: cmake @@ -122,20 +142,6 @@ Available logical expressions are: add_executable(myapp main.cpp) target_link_libraries(myapp myapp_c myapp_cxx) - The ``Makefile`` and ``Ninja`` based generators can also use this - expression to specify compile-language specific compile definitions - and include directories: - - .. code-block:: cmake - - add_executable(myapp main.cpp foo.c bar.cpp) - target_compile_definitions(myapp - PRIVATE $<$<COMPILE_LANGUAGE:CXX>:COMPILING_CXX> - ) - target_include_directories(myapp - PRIVATE $<$<COMPILE_LANGUAGE:CXX>:/opt/foo/cxx_headers> - ) - Informational Expressions ========================= @@ -268,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 @@ -287,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``. @@ -295,3 +305,42 @@ Available output expressions are: Content of ``...`` converted to shell path style. For example, slashes are converted to backslashes in Windows shells and drive letters are converted to posix paths in MSYS shells. The ``...`` must be an absolute path. +``$<GENEX_EVAL:...>`` + Content of ``...`` evaluated as a generator expression in the current + context. This enables consumption of generator expressions + whose evaluation results itself in generator expressions. +``$<TARGET_GENEX_EVAL:tgt,...>`` + Content of ``...`` evaluated as a generator expression in the context of + ``tgt`` target. This enables consumption of custom target properties that + themselves contain generator expressions. + + Having the capability to evaluate generator expressions is very useful when + you want to manage custom properties supporting generator expressions. + For example: + + .. code-block:: cmake + + add_library(foo ...) + + set_property(TARGET foo PROPERTY + CUSTOM_KEYS $<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS> + ) + + add_custom_target(printFooKeys + COMMAND ${CMAKE_COMMAND} -E echo $<TARGET_PROPERTY:foo,CUSTOM_KEYS> + ) + + This naive implementation of the ``printFooKeys`` custom command is wrong + because ``CUSTOM_KEYS`` target property is not evaluated and the content + is passed as is (i.e. ``$<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS>``). + + To have the expected result (i.e. ``FOO_EXTRA_THINGS`` if config is + ``Debug``), it is required to evaluate the output of + ``$<TARGET_PROPERTY:foo,CUSTOM_KEYS>``: + + .. code-block:: cmake + + add_custom_target(printFooKeys + COMMAND ${CMAKE_COMMAND} -E + echo $<TARGET_GENEX_EVAL:foo,$<TARGET_PROPERTY:foo,CUSTOM_KEYS>> + ) diff --git a/Help/manual/cmake-generators.7.rst b/Help/manual/cmake-generators.7.rst index a37c65b..0287767 100644 --- a/Help/manual/cmake-generators.7.rst +++ b/Help/manual/cmake-generators.7.rst @@ -108,6 +108,5 @@ The following extra generators are known to CMake. /generator/CodeBlocks /generator/CodeLite /generator/Eclipse CDT4 - /generator/KDevelop3 /generator/Kate /generator/Sublime Text 2 diff --git a/Help/manual/cmake-gui.1.rst b/Help/manual/cmake-gui.1.rst index 032b51f..57a9850 100644 --- a/Help/manual/cmake-gui.1.rst +++ b/Help/manual/cmake-gui.1.rst @@ -9,7 +9,7 @@ Synopsis .. parsed-literal:: cmake-gui [<options>] - cmake-gui [<options>] (<path-to-source> | <path-to-existing-build>) + cmake-gui [<options>] {<path-to-source> | <path-to-existing-build>} Description =========== diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index 8f4b252..8ef4d7d 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -64,6 +64,7 @@ All Modules /module/CPackIFW /module/CPackIFWConfigureFile /module/CPackNSIS + /module/CPackNuGet /module/CPackPackageMaker /module/CPackProductBuild /module/CPackRPM @@ -80,6 +81,7 @@ All Modules /module/ExternalData /module/ExternalProject /module/FeatureSummary + /module/FetchContent /module/FindALSA /module/FindArmadillo /module/FindASPELL @@ -129,6 +131,7 @@ All Modules /module/FindIcotool /module/FindICU /module/FindImageMagick + /module/FindIconv /module/FindIntl /module/FindITK /module/FindJasper @@ -153,6 +156,7 @@ All Modules /module/FindMPEG2 /module/FindMPEG /module/FindMPI + /module/FindODBC /module/FindOpenACC /module/FindOpenAL /module/FindOpenCL @@ -194,6 +198,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 c81ba59..631f75b 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -51,6 +51,24 @@ 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 + + CMP0075: Include file check macros honor CMAKE_REQUIRED_LIBRARIES. </policy/CMP0075> + 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 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0072: FindOpenGL prefers GLVND by default when available. </policy/CMP0072> + Policies Introduced by CMake 3.10 ================================= diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index dd59a00..9f9c53f 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -40,6 +40,7 @@ Properties of Global Scope /prop_gbl/JOB_POOLS /prop_gbl/PREDEFINED_TARGETS_FOLDER /prop_gbl/ECLIPSE_EXTRA_NATURES + /prop_gbl/ECLIPSE_EXTRA_CPROJECT_CONTENTS /prop_gbl/REPORT_UNDEFINED_PROPERTIES /prop_gbl/RULE_LAUNCH_COMPILE /prop_gbl/RULE_LAUNCH_CUSTOM @@ -84,6 +85,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 @@ -121,6 +123,7 @@ Properties on Targets /prop_tgt/ARCHIVE_OUTPUT_NAME_CONFIG /prop_tgt/ARCHIVE_OUTPUT_NAME /prop_tgt/AUTOGEN_BUILD_DIR + /prop_tgt/AUTOGEN_PARALLEL /prop_tgt/AUTOGEN_TARGET_DEPENDS /prop_tgt/AUTOMOC_COMPILER_PREDEFINES /prop_tgt/AUTOMOC_DEPEND_FILTERS @@ -141,6 +144,7 @@ Properties on Targets /prop_tgt/C_EXTENSIONS /prop_tgt/C_STANDARD /prop_tgt/C_STANDARD_REQUIRED + /prop_tgt/COMMON_LANGUAGE_RUNTIME /prop_tgt/COMPATIBLE_INTERFACE_BOOL /prop_tgt/COMPATIBLE_INTERFACE_NUMBER_MAX /prop_tgt/COMPATIBLE_INTERFACE_NUMBER_MIN @@ -168,12 +172,14 @@ Properties on Targets /prop_tgt/DEBUG_POSTFIX /prop_tgt/DEFINE_SYMBOL /prop_tgt/DEPLOYMENT_REMOTE_DIRECTORY + /prop_tgt/DOTNET_TARGET_FRAMEWORK_VERSION /prop_tgt/EchoString /prop_tgt/ENABLE_EXPORTS /prop_tgt/EXCLUDE_FROM_ALL /prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD_CONFIG /prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD /prop_tgt/EXPORT_NAME + /prop_tgt/EXPORT_PROPERTIES /prop_tgt/FOLDER /prop_tgt/Fortran_FORMAT /prop_tgt/Fortran_MODULE_DIRECTORY @@ -183,7 +189,9 @@ Properties on Targets /prop_tgt/GNUtoMS /prop_tgt/HAS_CXX /prop_tgt/IMPLICIT_DEPENDS_INCLUDE_TRANSFORM + /prop_tgt/IMPORTED_COMMON_LANGUAGE_RUNTIME /prop_tgt/IMPORTED_CONFIGURATIONS + /prop_tgt/IMPORTED_GLOBAL /prop_tgt/IMPORTED_IMPLIB_CONFIG /prop_tgt/IMPORTED_IMPLIB /prop_tgt/IMPORTED_LIBNAME_CONFIG @@ -293,6 +301,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 @@ -345,6 +354,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 @@ -368,10 +378,12 @@ Properties on Source Files /prop_sf/AUTORCC_OPTIONS /prop_sf/COMPILE_DEFINITIONS /prop_sf/COMPILE_FLAGS + /prop_sf/COMPILE_OPTIONS /prop_sf/EXTERNAL_OBJECT /prop_sf/Fortran_FORMAT /prop_sf/GENERATED /prop_sf/HEADER_FILE_ONLY + /prop_sf/INCLUDE_DIRECTORIES /prop_sf/KEEP_EXTENSION /prop_sf/LABELS /prop_sf/LANGUAGE @@ -390,9 +402,12 @@ Properties on Source Files /prop_sf/VS_DEPLOYMENT_LOCATION /prop_sf/VS_INCLUDE_IN_VSIX /prop_sf/VS_RESOURCE_GENERATOR + /prop_sf/VS_SHADER_DISABLE_OPTIMIZATIONS + /prop_sf/VS_SHADER_ENABLE_DEBUG /prop_sf/VS_SHADER_ENTRYPOINT /prop_sf/VS_SHADER_FLAGS /prop_sf/VS_SHADER_MODEL + /prop_sf/VS_SHADER_OBJECT_FILE_NAME /prop_sf/VS_SHADER_OUTPUT_HEADER_FILE /prop_sf/VS_SHADER_TYPE /prop_sf/VS_SHADER_VARIABLE_NAME diff --git a/Help/manual/cmake-qt.7.rst b/Help/manual/cmake-qt.7.rst index cafeae1..724d8ec 100644 --- a/Help/manual/cmake-qt.7.rst +++ b/Help/manual/cmake-qt.7.rst @@ -96,7 +96,8 @@ following targets by setting the :variable:`CMAKE_AUTOMOC` variable. The options to pass to ``moc``. The :variable:`CMAKE_AUTOMOC_MOC_OPTIONS` variable may be populated to pre-set the options for all following targets. -Additional macro names to search for can be added to :prop_tgt:`AUTOMOC_MACRO_NAMES`. +Additional macro names to search for can be added to +:prop_tgt:`AUTOMOC_MACRO_NAMES`. Additional ``moc`` dependency file names can be extracted from source code by using :prop_tgt:`AUTOMOC_DEPEND_FILTERS`. @@ -216,19 +217,16 @@ enabling :prop_sf:`SKIP_AUTORCC` or the broader :prop_sf:`SKIP_AUTOGEN`. Visual Studio Generators ======================== -When using the :manual:`Visual Studio generators <cmake-generators(7)>` -CMake tries to use a ``PRE_BUILD`` -:command:`custom command <add_custom_command>` instead -of a :command:`custom target <add_custom_target>` for autogen. -``PRE_BUILD`` can't be used when the autogen target depends on files. +When using the :manual:`Visual Studio generators <cmake-generators(7)>`, +CMake uses a ``PRE_BUILD`` :command:`custom command <add_custom_command>` for +:prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`. +If the :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` processing depends on files, +a :command:`custom target <add_custom_target>` is used instead. This happens when -- :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC` is enabled and the origin target - depends on :prop_sf:`GENERATED` files which aren't excluded from autogen by - :prop_sf:`SKIP_AUTOMOC`, :prop_sf:`SKIP_AUTOUIC`, :prop_sf:`SKIP_AUTOGEN` - or :policy:`CMP0071` -- :prop_tgt:`AUTORCC` is enabled and a ``.qrc`` file is listed in - the origin target sources +- The origin target depends on :prop_sf:`GENERATED` files which aren't excluded + from :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` by :prop_sf:`SKIP_AUTOMOC`, + :prop_sf:`SKIP_AUTOUIC`, :prop_sf:`SKIP_AUTOGEN` or :policy:`CMP0071` - :prop_tgt:`AUTOGEN_TARGET_DEPENDS` lists a source file qtmain.lib on Windows diff --git a/Help/manual/cmake-server.7.rst b/Help/manual/cmake-server.7.rst index 50a90ee..25d364c 100644 --- a/Help/manual/cmake-server.7.rst +++ b/Help/manual/cmake-server.7.rst @@ -49,10 +49,12 @@ Operation Start :manual:`cmake(1)` in the server command mode, supplying the path to the build directory to process:: - cmake -E server (--debug|--pipe <NAMED_PIPE>) + cmake -E server (--debug|--pipe=<NAMED_PIPE>) The server will communicate using stdin/stdout (with the ``--debug`` parameter) -or using a named pipe (with the ``--pipe <NAMED_PIPE>`` parameter). +or using a named pipe (with the ``--pipe=<NAMED_PIPE>`` parameter). Note +that "named pipe" refers to a local domain socket on Unix and to a named pipe +on Windows. When connecting to the server (via named pipe or by starting it in ``--debug`` mode), the server will reply with a hello message:: @@ -162,7 +164,7 @@ When the server is busy for a long time, it is polite to send back replies of type "progress" to the client. These will contain a "progressMessage" with a string describing the action currently taking place as well as "progressMinimum", "progressMaximum" and "progressCurrent" with integer values -describing the range of progess. +describing the range of progress. Messages of type "progress" will be followed by more "progress" messages or with a message of type "reply" or "error" that complete the request. @@ -277,10 +279,6 @@ Giving the "major" version of the requested protocol version will make the serve use the latest minor version of that protocol. Use this if you do not explicitly need to depend on a specific minor version. -If the build directory already contains a CMake cache, it is sufficient to set -the "buildDirectory" attribute. To create a fresh build directory, additional -attributes are required depending on the protocol version. - Protocol version 1.0 requires the following attributes to be set: * "sourceDirectory" with a path to the sources @@ -290,6 +288,10 @@ Protocol version 1.0 requires the following attributes to be set: * "platform" with the generator platform (if supported by the generator) * "toolset" with the generator toolset (if supported by the generator) +Protocol version 1.2 makes all but the build directory optional, provided +there is a valid cache in the build directory that contains all the other +information already. + Example:: [== "CMake Server" ==[ @@ -458,6 +460,11 @@ Each project object can have the following keys: "name" contains the (sub-)projects name. +"minimumCMakeVersion" + contains the minimum cmake version allowed for this project, null if the + project doesn't specify one. +"hasInstallRule" + true if the project contains any install rules, false otherwise. "sourceDirectory" contains the current source directory "buildDirectory" @@ -481,6 +488,12 @@ Each target object can have the following keys: contains the current source directory. "buildDirectory" contains the current build directory. +"isGeneratorProvided" + true if the target is auto-created by a generator, false otherwise +"hasInstallRule" + true if the target contains any install rules, false otherwise. +"installPaths" + full path to the destination directories defined by target install rules. "artifacts" with a list of build artifacts. The list is sorted with the most important artifacts first (e.g. a .DLL file is listed before a @@ -582,6 +595,51 @@ CMake will reply:: ]== "CMake Server" ==] +Type "ctestInfo" +^^^^^^^^^^^^^^^^ + +The "ctestInfo" request can be used after a project was "compute"d successfully. + +It will list the complete project test structure as it is known to cmake. + +The reply will contain a key "configurations", which will contain a list of +configuration objects. Configuration objects are used to destinquish between +different configurations the build directory might have enabled. While most +generators only support one configuration, others might support several. + +Each configuration object can have the following keys: + +"name" + contains the name of the configuration. The name may be empty. +"projects" + contains a list of project objects, one for each build project. + +Project objects define one (sub-)project defined in the cmake build system. + +Each project object can have the following keys: + +"name" + contains the (sub-)projects name. +"ctestInfo" + contains a list of test objects. + +Each test object can have the following keys: + +"ctestName" + contains the name of the test. +"ctestCommand" + contains the test command. +"properties" + contains a list of test property objects. + +Each test property object can have the following keys: + +"key" + contains the test property key. +"value" + contains the test property value. + + Type "cmakeInputs" ^^^^^^^^^^^^^^^^^^ diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 2e369e3..f6bf0bd 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -34,6 +34,7 @@ Variables that Provide Information /variable/CMAKE_CURRENT_SOURCE_DIR /variable/CMAKE_DIRECTORY_LABELS /variable/CMAKE_DL_LIBS + /variable/CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION /variable/CMAKE_EDIT_COMMAND /variable/CMAKE_EXECUTABLE_SUFFIX /variable/CMAKE_EXTRA_GENERATOR @@ -42,6 +43,7 @@ Variables that Provide Information /variable/CMAKE_FIND_PACKAGE_SORT_DIRECTION /variable/CMAKE_FIND_PACKAGE_SORT_ORDER /variable/CMAKE_GENERATOR + /variable/CMAKE_GENERATOR_INSTANCE /variable/CMAKE_GENERATOR_PLATFORM /variable/CMAKE_GENERATOR_TOOLSET /variable/CMAKE_HOME_DIRECTORY @@ -49,6 +51,7 @@ Variables that Provide Information /variable/CMAKE_IMPORT_LIBRARY_SUFFIX /variable/CMAKE_JOB_POOL_COMPILE /variable/CMAKE_JOB_POOL_LINK + /variable/CMAKE_JOB_POOLS /variable/CMAKE_LANG_COMPILER_AR /variable/CMAKE_LANG_COMPILER_RANLIB /variable/CMAKE_LINK_LIBRARY_SUFFIX @@ -60,10 +63,18 @@ Variables that Provide Information /variable/CMAKE_MATCH_n /variable/CMAKE_MINIMUM_REQUIRED_VERSION /variable/CMAKE_MINOR_VERSION + /variable/CMAKE_NETRC + /variable/CMAKE_NETRC_FILE /variable/CMAKE_PARENT_LIST_FILE /variable/CMAKE_PATCH_VERSION /variable/CMAKE_PROJECT_DESCRIPTION + /variable/CMAKE_PROJECT_HOMEPAGE_URL /variable/CMAKE_PROJECT_NAME + /variable/CMAKE_PROJECT_VERSION + /variable/CMAKE_PROJECT_VERSION_MAJOR + /variable/CMAKE_PROJECT_VERSION_MINOR + /variable/CMAKE_PROJECT_VERSION_PATCH + /variable/CMAKE_PROJECT_VERSION_TWEAK /variable/CMAKE_RANLIB /variable/CMAKE_ROOT /variable/CMAKE_SCRIPT_MODE_FILE @@ -89,10 +100,13 @@ Variables that Provide Information /variable/CMAKE_VS_PLATFORM_TOOLSET /variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA /variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE + /variable/CMAKE_VS_PLATFORM_TOOLSET_VERSION /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION /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 @@ -101,6 +115,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 @@ -121,6 +136,7 @@ Variables that Change Behavior /variable/CMAKE_AUTOMOC_RELAXED_MODE /variable/CMAKE_BACKWARDS_COMPATIBILITY /variable/CMAKE_BUILD_TYPE + /variable/CMAKE_CODEBLOCKS_COMPILER_ID /variable/CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES /variable/CMAKE_CODELITE_USE_TARGETS /variable/CMAKE_COLOR_MAKEFILE @@ -156,6 +172,7 @@ Variables that Change Behavior /variable/CMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE /variable/CMAKE_INCLUDE_PATH /variable/CMAKE_INSTALL_DEFAULT_COMPONENT_NAME + /variable/CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS /variable/CMAKE_INSTALL_MESSAGE /variable/CMAKE_INSTALL_PREFIX /variable/CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT @@ -172,6 +189,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 @@ -185,6 +203,8 @@ Variables that Change Behavior /variable/CMAKE_USER_MAKE_RULES_OVERRIDE /variable/CMAKE_WARN_DEPRECATED /variable/CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION + /variable/CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY + /variable/PackageName_ROOT Variables that Describe the System ================================== @@ -227,6 +247,7 @@ Variables that Describe the System /variable/MSVC80 /variable/MSVC90 /variable/MSVC_IDE + /variable/MSVC_TOOLSET_VERSION /variable/MSVC_VERSION /variable/UNIX /variable/WIN32 @@ -269,6 +290,7 @@ Variables that Control the Build /variable/CMAKE_ANDROID_STL_TYPE /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG + /variable/CMAKE_AUTOGEN_PARALLEL /variable/CMAKE_AUTOMOC /variable/CMAKE_AUTOMOC_COMPILER_PREDEFINES /variable/CMAKE_AUTOMOC_DEPEND_FILTERS @@ -285,12 +307,14 @@ Variables that Control the Build /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG /variable/CMAKE_CONFIG_POSTFIX + /variable/CMAKE_CUDA_SEPARABLE_COMPILATION /variable/CMAKE_DEBUG_POSTFIX /variable/CMAKE_ENABLE_EXPORTS /variable/CMAKE_EXE_LINKER_FLAGS /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 @@ -353,6 +377,13 @@ Variables that Control the Build /variable/CMAKE_VISIBILITY_INLINES_HIDDEN /variable/CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD /variable/CMAKE_VS_INCLUDE_PACKAGE_TO_DEFAULT_BUILD + /variable/CMAKE_VS_SDK_EXCLUDE_DIRECTORIES + /variable/CMAKE_VS_SDK_EXECUTABLE_DIRECTORIES + /variable/CMAKE_VS_SDK_INCLUDE_DIRECTORIES + /variable/CMAKE_VS_SDK_LIBRARY_DIRECTORIES + /variable/CMAKE_VS_SDK_LIBRARY_WINRT_DIRECTORIES + /variable/CMAKE_VS_SDK_REFERENCE_DIRECTORIES + /variable/CMAKE_VS_SDK_SOURCE_DIRECTORIES /variable/CMAKE_WIN32_EXECUTABLE /variable/CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS /variable/CMAKE_XCODE_ATTRIBUTE_an-attribute @@ -406,6 +437,8 @@ Variables for Languages /variable/CMAKE_LANG_CREATE_SHARED_MODULE /variable/CMAKE_LANG_CREATE_STATIC_LIBRARY /variable/CMAKE_LANG_FLAGS + /variable/CMAKE_LANG_FLAGS_CONFIG + /variable/CMAKE_LANG_FLAGS_CONFIG_INIT /variable/CMAKE_LANG_FLAGS_DEBUG /variable/CMAKE_LANG_FLAGS_DEBUG_INIT /variable/CMAKE_LANG_FLAGS_INIT @@ -415,6 +448,7 @@ Variables for Languages /variable/CMAKE_LANG_FLAGS_RELEASE_INIT /variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO /variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT + /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_CONFIG /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_DEBUG /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_MINSIZEREL /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELEASE @@ -501,6 +535,7 @@ Variables for CTest /variable/CTEST_P4_COMMAND /variable/CTEST_P4_OPTIONS /variable/CTEST_P4_UPDATE_OPTIONS + /variable/CTEST_RUN_CURRENT_SCRIPT /variable/CTEST_SCP_COMMAND /variable/CTEST_SITE /variable/CTEST_SOURCE_DIRECTORY @@ -525,6 +560,7 @@ Variables for CPack /variable/CPACK_COMPONENT_INCLUDE_TOPLEVEL_DIRECTORY /variable/CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION /variable/CPACK_INCLUDE_TOPLEVEL_DIRECTORY + /variable/CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS /variable/CPACK_INSTALL_SCRIPT /variable/CPACK_PACKAGING_INSTALL_PREFIX /variable/CPACK_SET_DESTDIR diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 6a21683..177acd4 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -8,9 +8,10 @@ Synopsis .. parsed-literal:: - cmake [<options>] (<path-to-source> | <path-to-existing-build>) - cmake [(-D <var>=<value>)...] -P <cmake-script-file> + cmake [<options>] {<path-to-source> | <path-to-existing-build>} + cmake [{-D <var>=<value>}...] -P <cmake-script-file> cmake --build <dir> [<options>...] [-- <build-tool-options>...] + cmake --open <dir> cmake -E <command> [<options>...] cmake --find-package <options>... @@ -51,6 +52,10 @@ Options ``--build <dir>`` See `Build Tool Mode`_. +``--open <dir>`` + Open the generated project in the associated application. This is + only supported by some generators. + ``-N`` View mode only. @@ -154,6 +159,13 @@ following options: ``--build <dir>`` Project binary directory to be built. This is required and must be first. +``-j [<jobs>], --parallel [<jobs>]`` + The maximum number of concurrent processes to use when building. + If ``<jobs>`` is omitted the native build tool's default number is used. + + The :envvar:`CMAKE_BUILD_PARALLEL_LEVEL` environment variable, if set, + specifies a default parallel level when this option is not given. + ``--target <tgt>`` Build ``<tgt>`` instead of default targets. May only be specified once. @@ -332,7 +344,7 @@ Available commands are: ``paxr`` (restricted pax, default), and ``zip``. ``time <command> [<args>...]`` - Run command and return elapsed time. + Run command and display elapsed time. ``touch <file>`` Touch a file. diff --git a/Help/manual/cpack.1.rst b/Help/manual/cpack.1.rst index 4f9f28d..87aa38d 100644 --- a/Help/manual/cpack.1.rst +++ b/Help/manual/cpack.1.rst @@ -8,86 +8,85 @@ Synopsis .. parsed-literal:: - cpack -G <generator> [<options>] + cpack [<options>] Description =========== -The "cpack" executable is the CMake packaging program. -CMake-generated build trees created for projects that use the -INSTALL_* commands have packaging support. This program will generate -the package. - -CMake is a cross-platform build system generator. Projects specify -their build process with platform-independent CMake listfiles included -in each directory of a source tree with the name CMakeLists.txt. -Users build a project by using CMake to generate a build system for a -native tool on their platform. +The ``cpack`` executable is the CMake packaging program. +CMake projects use :command:`install` commands to define the contents of +packages which can be generated in various formats by this tool. +The :module:`CPack` module greatly simplifies the creation of the input file +used by ``cpack``, allowing most aspects of the packaging configuration to be +controlled directly from the CMake project's own ``CMakeLists.txt`` files. Options ======= -``-G <generator>`` - Use the specified generator to generate package. - - CPack may support multiple native packaging systems on certain - platforms. A generator is responsible for generating input files - for particular system and invoking that systems. Possible generator - names are specified in the Generators section. +``-G <generators>`` + ``<generators>`` is a :ref:`semicolon-separated list <CMake Language Lists>` + of generator names. ``cpack`` will iterate through this list and produce + package(s) in that generator's format according to the details provided in + the ``CPackConfig.cmake`` configuration file. A generator is responsible for + generating the required inputs for a particular package system and invoking + that system's package creation tools. Possible generator names are specified + in the :manual:`Generators <cmake-generators(7)>` section of the manual and + the ``--help`` option lists the generators supported for the target platform. + If this option is not given, the :variable:`CPACK_GENERATOR` variable + determines the default set of generators that will be used. ``-C <Configuration>`` - Specify the project configuration - - This option specifies the configuration that the project was build - with, for example 'Debug', 'Release'. + Specify the project configuration to be packaged (e.g. ``Debug``, + ``Release``, etc.). When the CMake project uses a multi-configuration + generator such as Xcode or Visual Studio, this option is needed to tell + ``cpack`` which built executables to include in the package. ``-D <var>=<value>`` - Set a CPack variable. - - Set a variable that can be used by the generator. + Set a CPack variable. This will override any value set for ``<var>`` in the + input file read by ``cpack``. -``--config <config file>`` - Specify the config file. - - Specify the config file to use to create the package. By default - CPackConfig.cmake in the current directory will be used. +``--config <configFile>`` + Specify the configuration file read by ``cpack`` to provide the packaging + details. By default, ``CPackConfig.cmake`` in the current directory will + be used. ``--verbose,-V`` - enable verbose output - - Run cpack with verbose output. + Run ``cpack`` with verbose output. This can be used to show more details + from the package generation tools and is suitable for project developers. ``--debug`` - enable debug output (for CPack developers) - - Run cpack with debug output (for CPack developers). - -``-P <package name>`` - override/define CPACK_PACKAGE_NAME - - If the package name is not specified on cpack command line - thenCPack.cmake defines it as CMAKE_PROJECT_NAME - -``-R <package version>`` - override/define CPACK_PACKAGE_VERSION - - If version is not specified on cpack command line thenCPack.cmake - defines it from CPACK_PACKAGE_VERSION_[MAJOR|MINOR|PATCH]look into - CPack.cmake for detail - -``-B <package directory>`` - override/define CPACK_PACKAGE_DIRECTORY - - The directory where CPack will be doing its packaging work.The - resulting package will be found there. Inside this directoryCPack - creates '_CPack_Packages' sub-directory which is theCPack temporary - directory. - -``--vendor <vendor name>`` - override/define CPACK_PACKAGE_VENDOR - - If vendor is not specified on cpack command line (or inside - CMakeLists.txt) thenCPack.cmake defines it with a default value + Run ``cpack`` with debug output. This option is intended mainly for the + developers of ``cpack`` itself and is not normally needed by project + developers. + +``--trace`` + Put the underlying cmake scripts in trace mode. + +``--trace-expand`` + Put the underlying cmake scripts in expanded trace mode. + +``-P <packageName>`` + Override/define the value of the :variable:`CPACK_PACKAGE_NAME` variable used + for packaging. Any value set for this variable in the ``CPackConfig.cmake`` + file will then be ignored. + +``-R <packageVersion>`` + Override/define the value of the :variable:`CPACK_PACKAGE_VERSION` + variable used for packaging. It will override a value set in the + ``CPackConfig.cmake`` file or one automatically computed from + :variable:`CPACK_PACKAGE_VERSION_MAJOR`, + :variable:`CPACK_PACKAGE_VERSION_MINOR` and + :variable:`CPACK_PACKAGE_VERSION_PATCH`. + +``-B <packageDirectory>`` + Override/define :variable:`CPACK_PACKAGE_DIRECTORY`, which controls the + directory where CPack will perform its packaging work. The resultant + package(s) will be created at this location by default and a + ``_CPack_Packages`` subdirectory will also be created below this directory to + use as a working area during package creation. + +``--vendor <vendorName>`` + Override/define :variable:`CPACK_PACKAGE_VENDOR`. .. include:: OPTIONS_HELP.txt diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index 423f1ca..9553d15 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -3,12 +3,18 @@ ctest(1) ******** +.. contents:: + Synopsis ======== .. parsed-literal:: ctest [<options>] + ctest <path-to-source> <path-to-build> --build-generator <generator> + [<options>...] [-- <build-options>...] [--test-command <test>] + ctest {-D <dashboard> | -M <model> -T <action> | -S <script> | -SP <script>} + [-- <dashboard-options>...] Description =========== @@ -55,17 +61,21 @@ Options ``-F`` Enable failover. - This option allows ctest to resume a test set execution that was + This option allows CTest to resume a test set execution that was previously interrupted. If no interruption occurred, the ``-F`` option will have no effect. ``-j <jobs>, --parallel <jobs>`` Run the tests in parallel using the given number of jobs. - This option tells ctest to run the tests in parallel using given - number of jobs. This option can also be set by setting the + This option tells CTest to run the tests in parallel using given + number of jobs. This option can also be set by setting the environment variable ``CTEST_PARALLEL_LEVEL``. + This option can be used with the :prop_test:`PROCESSORS` test property. + + See `Label and Subproject Summary`_. + ``--test-load <level>`` While running tests in parallel (e.g. with ``-j``), try not to start tests when they may cause the CPU load to pass above a given threshold. @@ -74,7 +84,7 @@ Options ``TestLoad`` option of the `CTest Test Step`_. ``-Q,--quiet`` - Make ctest quiet. + Make CTest quiet. This option will suppress all the output. The output log file will still be generated if the ``--output-log`` is specified. Options such @@ -84,37 +94,37 @@ Options ``-O <file>, --output-log <file>`` Output to log file. - This option tells ctest to write all its output to a log file. + This option tells CTest to write all its output to a log file. ``-N,--show-only`` Disable actual execution of tests. - This option tells ctest to list the tests that would be run but not + This option tells CTest to list the tests that would be run but not actually run them. Useful in conjunction with the ``-R`` and ``-E`` options. ``-L <regex>, --label-regex <regex>`` Run tests with labels matching regular expression. - This option tells ctest to run only the tests whose labels match the + This option tells CTest to run only the tests whose labels match the given regular expression. ``-R <regex>, --tests-regex <regex>`` Run tests matching regular expression. - This option tells ctest to run only the tests whose names match the + This option tells CTest to run only the tests whose names match the given regular expression. ``-E <regex>, --exclude-regex <regex>`` Exclude tests matching regular expression. - This option tells ctest to NOT run the tests whose names match the + This option tells CTest to NOT run the tests whose names match the given regular expression. ``-LE <regex>, --label-exclude <regex>`` Exclude tests with labels matching regular expression. - This option tells ctest to NOT run the tests whose labels match the + This option tells CTest to NOT run the tests whose labels match the given regular expression. ``-FA <regex>, --fixture-exclude-any <regex>`` @@ -137,11 +147,13 @@ Options ``-D <dashboard>, --dashboard <dashboard>`` Execute dashboard test. - This option tells ctest to act as a CDash client and perform a + This option tells CTest to act as a CDash client and perform a dashboard test. All tests are <Mode><Test>, where Mode can be Experimental, Nightly, and Continuous, and Test can be Start, Update, Configure, Build, Test, Coverage, and Submit. + See `Dashboard Client`_. + ``-D <var>:<type>=<value>`` Define a variable for script mode. @@ -153,35 +165,33 @@ Options ``-M <model>, --test-model <model>`` Sets the model for a dashboard. - This option tells ctest to act as a CDash client where the ``<model>`` + This option tells CTest to act as a CDash client where the ``<model>`` can be ``Experimental``, ``Nightly``, and ``Continuous``. Combining ``-M`` and ``-T`` is similar to ``-D``. + See `Dashboard Client`_. + ``-T <action>, --test-action <action>`` Sets the dashboard action to perform. - This option tells ctest to act as a CDash client and perform some + This option tells CTest to act as a CDash client and perform some action such as ``start``, ``build``, ``test`` etc. See `Dashboard Client Steps`_ for the full list of actions. Combining ``-M`` and ``-T`` is similar to ``-D``. -``--track <track>`` - Specify the track to submit dashboard to - - Submit dashboard to specified track instead of default one. By - default, the dashboard is submitted to Nightly, Experimental, or - Continuous track, but by specifying this option, the track can be - arbitrary. + See `Dashboard Client`_. ``-S <script>, --script <script>`` Execute a dashboard for a configuration. - This option tells ctest to load in a configuration script which sets + This option tells CTest to load in a configuration script which sets a number of parameters such as the binary and source directories. - Then ctest will do what is required to create and run a dashboard. + Then CTest will do what is required to create and run a dashboard. This option basically sets up a dashboard and then runs ``ctest -D`` with the appropriate options. + See `Dashboard Client`_. + ``-SP <script>, --script-new-process <script>`` Execute a dashboard for a configuration. @@ -190,16 +200,12 @@ Options script may modify the environment and you do not want the modified environment to impact other ``-S`` scripts. -``-A <file>, --add-notes <file>`` - Add a notes file with submission. - - This option tells ctest to include a notes file when submitting - dashboard. + See `Dashboard Client`_. ``-I [Start,End,Stride,test#,test#|Test file], --tests-information`` Run a specific number of tests by number. - This option causes ctest to run tests starting at number Start, + This option causes CTest to run tests starting at number Start, ending at number End, and incrementing by Stride. Any additional numbers after Stride are considered individual test numbers. Start, End,or stride can be empty. Optionally a file can be given that @@ -214,11 +220,11 @@ Options ``--rerun-failed`` Run only the tests that failed previously. - This option tells ctest to perform only the tests that failed during - its previous run. When this option is specified, ctest ignores all + This option tells CTest to perform only the tests that failed during + its previous run. When this option is specified, CTest ignores all other options intended to modify the list of tests to run (``-L``, ``-R``, ``-E``, ``-LE``, ``-I``, etc). In the event that CTest runs and no tests - fail, subsequent calls to ctest with the ``--rerun-failed`` option will run + fail, subsequent calls to CTest with the ``--rerun-failed`` option will run the set of tests that most recently failed (if any). ``--repeat-until-fail <n>`` @@ -236,7 +242,7 @@ Options ``--interactive-debug-mode [0|1]`` Set the interactive mode to 0 or 1. - This option causes ctest to run tests in either an interactive mode + This option causes CTest to run tests in either an interactive mode or a non-interactive mode. On Windows this means that in non-interactive mode, all system debug pop up windows are blocked. In dashboard mode (Experimental, Nightly, Continuous), the default @@ -246,36 +252,141 @@ Options ``--no-label-summary`` Disable timing summary information for labels. - This option tells ctest not to print summary information for each + This option tells CTest not to print summary information for each label associated with the tests run. If there are no labels on the tests, nothing extra is printed. - ``--no-subproject-summary`` + See `Label and Subproject Summary`_. + +``--no-subproject-summary`` Disable timing summary information for subprojects. - This option tells ctest not to print summary information for each + This option tells CTest not to print summary information for each subproject associated with the tests run. If there are no subprojects on the tests, nothing extra is printed. -``--build-and-test <path-to-source> <path-to-build>`` - Configure, build and run a test. + See `Label and Subproject Summary`_. + +``--build-and-test`` +See `Build and Test Mode`_. + +``--test-output-size-passed <size>`` + Limit the output for passed tests to ``<size>`` bytes. + +``--test-output-size-failed <size>`` + Limit the output for failed tests to ``<size>`` bytes. + +``--overwrite`` + Overwrite CTest configuration option. + + By default CTest uses configuration options from configuration file. + This option will overwrite the configuration option. + +``--force-new-ctest-process`` + Run child CTest instances as new processes. + + By default CTest will run child CTest instances within the same + process. If this behavior is not desired, this argument will + enforce new processes for child CTest processes. + +``--schedule-random`` + Use a random order for scheduling tests. + + This option will run the tests in a random order. It is commonly + used to detect implicit dependencies in a test suite. + +``--submit-index`` + Legacy option for old Dart2 dashboard server feature. + Do not use. + +``--timeout <seconds>`` + Set a global timeout on all tests. + + This option will set a global timeout on all tests that do not + already have a timeout set on them. + +``--stop-time <time>`` + Set a time at which all tests should stop running. + + Set a real time of day at which all tests should timeout. Example: + ``7:00:00 -0400``. Any time format understood by the curl date parser + is accepted. Local time is assumed if no timezone is specified. + +``--print-labels`` + Print all available test labels. + + This option will not run any tests, it will simply print the list of + all labels associated with the test set. + +.. include:: OPTIONS_HELP.txt + +.. _`Label and Subproject Summary`: + +Label and Subproject Summary +============================ + +CTest prints timing summary information for each label and subproject +associated with the tests run. The label time summary will not include labels +that are mapped to subprojects. + +When the :prop_test:`PROCESSORS` test property is set, CTest will display a +weighted test timing result in label and subproject summaries. The time is +reported with `sec*proc` instead of just `sec`. + +The weighted time summary reported for each label or subproject j is computed +as:: + + Weighted Time Summary for Label/Subproject j = + sum(raw_test_time[j,i] * num_processors[j,i], i=1...num_tests[j]) - This option tells ctest to configure (i.e. run cmake on), build, - and or execute a test. The configure and test steps are optional. - The arguments to this command line are the source and binary - directories. - The ``--build-generator`` option *must* be provided to use - ``--build-and-test``. If ``--test-command`` is specified then that will be - run after the build is complete. Other options that affect this - mode are ``--build-target``, ``--build-nocmake``, ``--build-run-dir``, - ``--build-two-config``, ``--build-exe-dir``, - ``--build-project``, ``--build-noclean`` and ``--build-options``. + for labels/subprojects j=1...total + +where: + +* raw_test_time[j,i]: Wall-clock time for the ith test for the jth label or + subproject +* num_processors[j,i]: Value of the CTest PROCESSORS property for the ith test + for the jth label or subproject +* num_tests[j]: Number of tests associated with the jth label or subproject +* total: Total number of labels or subprojects that have at least one test run + +Therefore, the weighted time summary for each label or subproject represents +the amount of time that CTest gave to run the tests for each label or +subproject and gives a good representation of the total expense of the tests +for each label or subproject when compared to other labels or subprojects. + +For example, if "SubprojectA" showed "100 sec*proc" and "SubprojectB" showed +"10 sec*proc", then CTest allocated approximately 10 times the CPU/core time +to run the tests for "SubprojectA" than for "SubprojectB" (e.g. so if effort +is going to be expended to reduce the cost of the test suite for the whole +project, then reducing the cost of the test suite for "SubprojectA" would +likely have a larger impact than effort to reduce the cost of the test suite +for "SubprojectB"). + +.. _`Build and Test Mode`: + +Build and Test Mode +=================== + +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 <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* +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: ``--build-target`` Specify a specific target to build. - This option goes with the ``--build-and-test`` option, if left out the - ``all`` target is built. + If left out the ``all`` target is built. ``--build-nocmake`` Run the build without running cmake first. @@ -316,75 +427,57 @@ Options 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. - -``--test-output-size-passed <size>`` - Limit the output for passed tests to ``<size>`` bytes. - -``--test-output-size-failed <size>`` - Limit the output for failed tests to ``<size>`` bytes. + 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, internal use only. - -``--tomorrow-tag`` - Nightly or experimental starts with next day tag. - - This is useful if the build will not finish in one day. + The time limit in seconds -``--ctest-config`` - The configuration file used to initialize CTest state when submitting dashboards. - - This option tells CTest to use different initialization file instead - of CTestConfiguration.tcl. This way multiple initialization files - can be used for example to submit to multiple dashboards. - -``--overwrite`` - Overwrite CTest configuration option. +.. _`Dashboard Client`: - By default ctest uses configuration options from configuration file. - This option will overwrite the configuration option. +Dashboard Client +================ -``--extra-submit <file>[;<file>]`` - Submit extra files to the dashboard. +CTest can operate as a client for the `CDash`_ software quality dashboard +application. As a dashboard client, CTest performs a sequence of steps +to configure, build, and test software, and then submits the results to +a `CDash`_ server. The command-line signature used to submit to `CDash`_ is:: - This option will submit extra files to the dashboard. + ctest (-D <dashboard> | -M <model> -T <action> | -S <script> | -SP <script>) + [-- <dashboard-options>...] -``--force-new-ctest-process`` - Run child CTest instances as new processes. +Options for Dashboard Client include: - By default CTest will run child CTest instances within the same - process. If this behavior is not desired, this argument will - enforce new processes for child CTest processes. +``--track <track>`` + Specify the track to submit dashboard to -``--schedule-random`` - Use a random order for scheduling tests. + Submit dashboard to specified track instead of default one. By + default, the dashboard is submitted to Nightly, Experimental, or + Continuous track, but by specifying this option, the track can be + arbitrary. - This option will run the tests in a random order. It is commonly - used to detect implicit dependencies in a test suite. +``-A <file>, --add-notes <file>`` + Add a notes file with submission. -``--submit-index`` - Legacy option for old Dart2 dashboard server feature. - Do not use. + This option tells CTest to include a notes file when submitting + dashboard. -``--timeout <seconds>`` - Set a global timeout on all tests. +``--tomorrow-tag`` + Nightly or experimental starts with next day tag. - This option will set a global timeout on all tests that do not - already have a timeout set on them. + This is useful if the build will not finish in one day. -``--stop-time <time>`` - Set a time at which all tests should stop running. +``--extra-submit <file>[;<file>]`` + Submit extra files to the dashboard. - Set a real time of day at which all tests should timeout. Example: - ``7:00:00 -0400``. Any time format understood by the curl date parser - is accepted. Local time is assumed if no timezone is specified. + This option will submit extra files to the dashboard. ``--http1.0`` Submit using HTTP 1.0. @@ -399,26 +492,6 @@ Options this to maintain compatibility with an older version of CDash which doesn't support compressed test output. -``--print-labels`` - Print all available test labels. - - This option will not run any tests, it will simply print the list of - all labels associated with the test set. - -.. include:: OPTIONS_HELP.txt - -.. _`Dashboard Client`: - -Dashboard Client -================ - -CTest can operate as a client for the `CDash`_ software quality dashboard -application. As a dashboard client, CTest performs a sequence of steps -to configure, build, and test software, and then submits the results to -a `CDash`_ server. - -.. _`CDash`: http://cdash.org/ - Dashboard Client Steps ---------------------- @@ -731,7 +804,6 @@ Configuration settings to specify the version control tool include: * `CTest Script`_ variable: :variable:`CTEST_UPDATE_VERSION_ONLY` - Additional configuration settings include: ``NightlyStartTime`` @@ -773,6 +845,7 @@ Configuration settings include: * `CTest Script`_ variable: :variable:`CTEST_LABELS_FOR_SUBPROJECTS` * :module:`CTest` module variable: ``CTEST_LABELS_FOR_SUBPROJECTS`` + See `Label and Subproject Summary`_. .. _`CTest Build Step`: @@ -804,6 +877,8 @@ Configuration settings include: * `CTest Script`_ variable: :variable:`CTEST_LABELS_FOR_SUBPROJECTS` * :module:`CTest` module variable: ``CTEST_LABELS_FOR_SUBPROJECTS`` + See `Label and Subproject Summary`_. + ``MakeCommand`` Command-line to launch the software build process. It will be executed in the location specified by the @@ -847,6 +922,7 @@ Configuration settings include: * `CTest Script`_ variable: :variable:`CTEST_LABELS_FOR_SUBPROJECTS` * :module:`CTest` module variable: ``CTEST_LABELS_FOR_SUBPROJECTS`` + See `Label and Subproject Summary`_. ``TestLoad`` While running tests in parallel (e.g. with ``-j``), try not to start @@ -1082,3 +1158,5 @@ See Also ======== .. include:: LINKS.txt + +.. _`CDash`: http://cdash.org/ diff --git a/Help/module/CPackNuGet.rst b/Help/module/CPackNuGet.rst new file mode 100644 index 0000000..a4cbb59 --- /dev/null +++ b/Help/module/CPackNuGet.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CPackNuGet.cmake diff --git a/Help/module/FetchContent.rst b/Help/module/FetchContent.rst new file mode 100644 index 0000000..c130a6d --- /dev/null +++ b/Help/module/FetchContent.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FetchContent.cmake diff --git a/Help/module/FindIconv.rst b/Help/module/FindIconv.rst new file mode 100644 index 0000000..c1f3ed0 --- /dev/null +++ b/Help/module/FindIconv.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindIconv.cmake diff --git a/Help/module/FindODBC.rst b/Help/module/FindODBC.rst new file mode 100644 index 0000000..8558334 --- /dev/null +++ b/Help/module/FindODBC.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindODBC.cmake 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/CMP0037.rst b/Help/policy/CMP0037.rst index 9f8457c..d1afeb7 100644 --- a/Help/policy/CMP0037.rst +++ b/Help/policy/CMP0037.rst @@ -11,10 +11,15 @@ diagnostics expect target names to match a restricted pattern. Target names may contain upper and lower case letters, numbers, the underscore character (_), dot(.), plus(+) and minus(-). As a special case, ALIAS -targets and IMPORTED targets may contain two consequtive colons. +targets and IMPORTED targets may contain two consecutive colons. Target names reserved by one or more CMake generators are not allowed. -Among others these include "all", "help" and "test". +Among others these include "all", "clean", "help", and "install". + +Target names associated with optional features, such as "test" and "package", +may also be reserved. CMake 3.10 and below always reserve them. CMake 3.11 +and above reserve them only when the corresponding feature is enabled +(e.g. by including the :module:`CTest` or :module:`CPack` modules). The OLD behavior for this policy is to allow creating targets with reserved names or which do not match the validity pattern. diff --git a/Help/policy/CMP0072.rst b/Help/policy/CMP0072.rst new file mode 100644 index 0000000..3abbad7 --- /dev/null +++ b/Help/policy/CMP0072.rst @@ -0,0 +1,26 @@ +CMP0072 +------- + +:module:`FindOpenGL` prefers GLVND by default when available. + +The :module:`FindOpenGL` module provides an ``OpenGL::GL`` target and an +``OPENGL_LIBRARIES`` variable for projects to use for legacy GL interfaces. +When both a legacy GL library (e.g. ``libGL.so``) and GLVND libraries +for OpenGL and GLX (e.g. ``libOpenGL.so`` and ``libGLX.so``) are available, +the module must choose between them. It documents an ``OpenGL_GL_PREFERENCE`` +variable that can be used to specify an explicit preference. When no such +preference is set, the module must choose a default preference. + +CMake 3.11 and above prefer to choose GLVND libraries. This policy provides +compatibility with projects that expect the legacy GL library to be used. + +The ``OLD`` behavior for this policy is to set ``OpenGL_GL_PREFERENCE`` to +``LEGACY``. The ``NEW`` behavior for this policy is to set +``OpenGL_GL_PREFERENCE`` to ``GLVND``. + +This policy was introduced in CMake version 3.11. 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/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..896936b --- /dev/null +++ b/Help/policy/CMP0074.rst @@ -0,0 +1,23 @@ +CMP0074 +------- + +:command:`find_package` uses ``<PackageName>_ROOT`` variables. + +In CMake 3.12 and above the :command:`find_package(<PackageName>)` command now +searches prefixes specified by the :variable:`<PackageName>_ROOT` CMake +variable and the :envvar:`<PackageName>_ROOT` 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/policy/CMP0075.rst b/Help/policy/CMP0075.rst new file mode 100644 index 0000000..aa5c3f7 --- /dev/null +++ b/Help/policy/CMP0075.rst @@ -0,0 +1,26 @@ +CMP0075 +------- + +Include file check macros honor ``CMAKE_REQUIRED_LIBRARIES``. + +In CMake 3.12 and above, the + +* ``check_include_file`` macro in the :module:`CheckIncludeFile` module, the +* ``check_include_file_cxx`` macro in the + :module:`CheckIncludeFileCXX` module, and the +* ``check_include_files`` macro in the :module:`CheckIncludeFiles` module + +now prefer to link the check executable to the libraries listed in the +``CMAKE_REQUIRED_LIBRARIES`` variable. This policy provides compatibility +with projects that have not been updated to expect this behavior. + +The ``OLD`` behavior for this policy is to ignore ``CMAKE_REQUIRED_LIBRARIES`` +in the include file check macros. The ``NEW`` behavior of this policy is to +honor ``CMAKE_REQUIRED_LIBRARIES`` in the include file check macros. + +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/COMPILE_DEFINITIONS.rst b/Help/prop_dir/COMPILE_DEFINITIONS.rst index 85adcb5..18f4567 100644 --- a/Help/prop_dir/COMPILE_DEFINITIONS.rst +++ b/Help/prop_dir/COMPILE_DEFINITIONS.rst @@ -4,7 +4,7 @@ COMPILE_DEFINITIONS Preprocessor definitions for compiling a directory's sources. This property specifies the list of options given so far to the -:command:`add_definitions` command. +:command:`add_compile_definitions` (or :command:`add_definitions`) command. The ``COMPILE_DEFINITIONS`` property may be set to a semicolon-separated list of preprocessor definitions using the syntax ``VAR`` or ``VAR=value``. diff --git a/Help/prop_dir/TESTS.rst b/Help/prop_dir/TESTS.rst new file mode 100644 index 0000000..91acd3e --- /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, in the current directory, 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_gbl/DEBUG_CONFIGURATIONS.rst b/Help/prop_gbl/DEBUG_CONFIGURATIONS.rst index 690143f..fec6fda 100644 --- a/Help/prop_gbl/DEBUG_CONFIGURATIONS.rst +++ b/Help/prop_gbl/DEBUG_CONFIGURATIONS.rst @@ -4,11 +4,10 @@ DEBUG_CONFIGURATIONS Specify which configurations are for debugging. The value must be a semi-colon separated list of configuration names. -Currently this property is used only by the target_link_libraries -command (see its documentation for details). Additional uses may be -defined in the future. +Currently this property is used only by the :command:`target_link_libraries` +command. Additional uses may be defined in the future. This property must be set at the top level of the project and before -the first target_link_libraries command invocation. If any entry in +the first :command:`target_link_libraries` command invocation. If any entry in the list does not match a valid configuration for the project the behavior is undefined. diff --git a/Help/prop_gbl/ECLIPSE_EXTRA_CPROJECT_CONTENTS.rst b/Help/prop_gbl/ECLIPSE_EXTRA_CPROJECT_CONTENTS.rst new file mode 100644 index 0000000..50c41a9 --- /dev/null +++ b/Help/prop_gbl/ECLIPSE_EXTRA_CPROJECT_CONTENTS.rst @@ -0,0 +1,12 @@ +ECLIPSE_EXTRA_CPROJECT_CONTENTS +------------------------------- + +Additional contents to be inserted into the generated Eclipse cproject file. + +The cproject file defines the CDT specific information. Some third party IDE's +are based on Eclipse with the addition of other information specific to that IDE. +Through this property, it is possible to add this additional contents to +the generated project. +It is expected to contain valid XML. + +Also see the :prop_gbl:`ECLIPSE_EXTRA_NATURES` property. diff --git a/Help/prop_gbl/ECLIPSE_EXTRA_NATURES.rst b/Help/prop_gbl/ECLIPSE_EXTRA_NATURES.rst index 6d1529d..a46575f 100644 --- a/Help/prop_gbl/ECLIPSE_EXTRA_NATURES.rst +++ b/Help/prop_gbl/ECLIPSE_EXTRA_NATURES.rst @@ -6,3 +6,5 @@ List of natures to add to the generated Eclipse project file. Eclipse projects specify language plugins by using natures. This property should be set to the unique identifier for a nature (which looks like a Java package name). + +Also see the :prop_gbl:`ECLIPSE_EXTRA_CPROJECT_CONTENTS` property. diff --git a/Help/prop_gbl/JOB_POOLS.rst b/Help/prop_gbl/JOB_POOLS.rst index 2ce74b8..b904f7a 100644 --- a/Help/prop_gbl/JOB_POOLS.rst +++ b/Help/prop_gbl/JOB_POOLS.rst @@ -19,5 +19,8 @@ Defined pools could be used globally by setting or per target by setting the target properties :prop_tgt:`JOB_POOL_COMPILE` and :prop_tgt:`JOB_POOL_LINK`. +If not set, this property uses the value of the :variable:`CMAKE_JOB_POOLS` +variable. + Build targets provided by CMake that are meant for individual interactive use, such as ``install``, are placed in the ``console`` pool automatically. diff --git a/Help/prop_sf/COMPILE_DEFINITIONS.rst b/Help/prop_sf/COMPILE_DEFINITIONS.rst index 1626825..8d2108c 100644 --- a/Help/prop_sf/COMPILE_DEFINITIONS.rst +++ b/Help/prop_sf/COMPILE_DEFINITIONS.rst @@ -17,3 +17,13 @@ by the native build tool. Xcode does not support per-configuration definitions on source files. .. include:: /include/COMPILE_DEFINITIONS_DISCLAIMER.txt + +Contents of ``COMPILE_DEFINITIONS`` may use "generator expressions" +with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` +manual for available expressions. However, :generator:`Xcode` +does not support per-config per-source settings, so expressions +that depend on the build configuration are not allowed with that +generator. + +Generator expressions should be preferred instead of setting the alternative per-configuration +property. diff --git a/Help/prop_sf/COMPILE_FLAGS.rst b/Help/prop_sf/COMPILE_FLAGS.rst index 1012164..c211b89 100644 --- a/Help/prop_sf/COMPILE_FLAGS.rst +++ b/Help/prop_sf/COMPILE_FLAGS.rst @@ -3,8 +3,8 @@ COMPILE_FLAGS Additional flags to be added when compiling this source file. -These flags will be added to the list of compile flags when this -source file builds. Use :prop_sf:`COMPILE_DEFINITIONS` to pass +The ``COMPILE_FLAGS`` property, managed as a string, sets additional compiler +flags used to build source files. Use :prop_sf:`COMPILE_DEFINITIONS` to pass additional preprocessor definitions. Contents of ``COMPILE_FLAGS`` may use "generator expressions" @@ -13,3 +13,7 @@ manual for available expressions. However, :generator:`Xcode` does not support per-config per-source settings, so expressions that depend on the build configuration are not allowed with that generator. + +.. note:: + + This property has been superseded by the :prop_sf:`COMPILE_OPTIONS` property. diff --git a/Help/prop_sf/COMPILE_OPTIONS.rst b/Help/prop_sf/COMPILE_OPTIONS.rst new file mode 100644 index 0000000..3b2bc8d --- /dev/null +++ b/Help/prop_sf/COMPILE_OPTIONS.rst @@ -0,0 +1,21 @@ +COMPILE_OPTIONS +--------------- + +List of additional options to pass to the compiler. + +This property holds a :ref:`;-list <CMake Language Lists>` of options +and will be added to the list of compile flags when this +source file builds. Use :prop_sf:`COMPILE_DEFINITIONS` to pass +additional preprocessor definitions and :prop_sf:`INCLUDE_DIRECTORIES` to pass +additional include directories. + +Contents of ``COMPILE_OPTIONS`` may use "generator expressions" with the +syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual +for available expressions. However, :generator:`Xcode` +does not support per-config per-source settings, so expressions +that depend on the build configuration are not allowed with that +generator. + +.. note:: + + This property should be preferred over the :prop_sf:`COMPILE_FLAGS` property. diff --git a/Help/prop_sf/GENERATED.rst b/Help/prop_sf/GENERATED.rst index a3aa127..d430ee2 100644 --- a/Help/prop_sf/GENERATED.rst +++ b/Help/prop_sf/GENERATED.rst @@ -1,8 +1,23 @@ GENERATED --------- -Is this source file generated as part of the build process. +Is this source file generated as part of the build or CMake process. -If a source file is generated by the build process CMake will handle -it differently in terms of dependency checking etc. Otherwise having -a non-existent source file could create problems. +Tells the internal CMake engine that a source file is generated by an outside +process such as another build step, or the execution of CMake itself. This +information is then used to exempt the file from any existence or validity +checks. Generated files are created by the execution of commands such as +:command:`add_custom_command` and :command:`file(GENERATE)`. + +When a generated file created by an :command:`add_custom_command` command +is explicitly listed as a source file for any target in the same +directory scope (which usually means the same ``CMakeLists.txt`` file), +CMake will automatically create a dependency to make sure the file is +generated before building that target. + +Generated sources may be hidden in some IDE tools, while in others they might +be shown. For the special case of sources generated by CMake's :prop_tgt:`AUTOMOC` +or :prop_tgt:`AUTORCC` functionality, the :prop_gbl:`AUTOGEN_SOURCE_GROUP`, +:prop_gbl:`AUTOMOC_SOURCE_GROUP` and :prop_gbl:`AUTORCC_SOURCE_GROUP` target +properties may influence where the generated sources are grouped in the project's +file lists. diff --git a/Help/prop_sf/INCLUDE_DIRECTORIES.rst b/Help/prop_sf/INCLUDE_DIRECTORIES.rst new file mode 100644 index 0000000..55780e5 --- /dev/null +++ b/Help/prop_sf/INCLUDE_DIRECTORIES.rst @@ -0,0 +1,18 @@ +INCLUDE_DIRECTORIES +------------------- + +List of preprocessor include file search directories. + +This property holds a :ref:`;-list <CMake Language Lists>` of paths +and will be added to the list of include directories when this +source file builds. These directories will take precedence over directories +defined at target level except for :generator:`Xcode` generator due to technical +limitations. + +Relative paths should not be added to this property directly. + +Contents of ``INCLUDE_DIRECTORIES`` may use "generator expressions" with +the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual +for available expressions. However, :generator:`Xcode` does not support +per-config per-source settings, so expressions that depend on the build +configuration are not allowed with that generator. diff --git a/Help/prop_sf/VS_SHADER_DISABLE_OPTIMIZATIONS.rst b/Help/prop_sf/VS_SHADER_DISABLE_OPTIMIZATIONS.rst new file mode 100644 index 0000000..446dd26 --- /dev/null +++ b/Help/prop_sf/VS_SHADER_DISABLE_OPTIMIZATIONS.rst @@ -0,0 +1,6 @@ +VS_SHADER_DISABLE_OPTIMIZATIONS +------------------------------- + +Disable compiler optimizations for an ``.hlsl`` source file. This adds the +``-Od`` flag to the command line for the FxCompiler tool. Specify the value +``true`` for this property to disable compiler optimizations. diff --git a/Help/prop_sf/VS_SHADER_ENABLE_DEBUG.rst b/Help/prop_sf/VS_SHADER_ENABLE_DEBUG.rst new file mode 100644 index 0000000..c0e60a3 --- /dev/null +++ b/Help/prop_sf/VS_SHADER_ENABLE_DEBUG.rst @@ -0,0 +1,6 @@ +VS_SHADER_ENABLE_DEBUG +---------------------- + +Enable debugging information for an ``.hlsl`` source file. This adds the +``-Zi`` flag to the command line for the FxCompiler tool. Specify the value +``true`` to generate debugging information for the compiled shader. diff --git a/Help/prop_sf/VS_SHADER_OBJECT_FILE_NAME.rst b/Help/prop_sf/VS_SHADER_OBJECT_FILE_NAME.rst new file mode 100644 index 0000000..093bcc6 --- /dev/null +++ b/Help/prop_sf/VS_SHADER_OBJECT_FILE_NAME.rst @@ -0,0 +1,6 @@ +VS_SHADER_OBJECT_FILE_NAME +-------------------------- + +Specifies a file name for the compiled shader object file for an ``.hlsl`` +source file. This adds the ``-Fo`` flag to the command line for the FxCompiler +tool. 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/AUTOGEN_PARALLEL.rst b/Help/prop_tgt/AUTOGEN_PARALLEL.rst new file mode 100644 index 0000000..07fbc5a --- /dev/null +++ b/Help/prop_tgt/AUTOGEN_PARALLEL.rst @@ -0,0 +1,21 @@ +AUTOGEN_PARALLEL +---------------- + +Number of parallel ``moc`` or ``uic`` processes to start when using +:prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`. + +The custom `<origin>_autogen` target starts a number of threads of which +each one parses a source file and on demand starts a ``moc`` or ``uic`` +process. :prop_tgt:`AUTOGEN_PARALLEL` controls how many parallel threads +(and therefore ``moc`` or ``uic`` processes) are started. + +- An empty (or unset) value or the string ``AUTO`` sets the number of + threads/processes to the number of physical CPUs on the host system. +- A positive non zero integer value sets the exact thread/process count. +- Otherwise a single thread/process is started. + +By default :prop_tgt:`AUTOGEN_PARALLEL` is initialized from +:variable:`CMAKE_AUTOGEN_PARALLEL`. + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. diff --git a/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst b/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst index f522c6b..7d3dfd1 100644 --- a/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst +++ b/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst @@ -3,15 +3,29 @@ AUTOGEN_TARGET_DEPENDS Target dependencies of the corresponding ``_autogen`` target. -Targets which have their :prop_tgt:`AUTOMOC` target ``ON`` have a -corresponding ``_autogen`` target which is used to autogenerate generate moc -files. As this ``_autogen`` target is created at generate-time, it is not -possible to define dependencies of it, such as to create inputs for the ``moc`` -executable. +Targets which have their :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC` property +``ON`` have a corresponding ``_autogen`` target which is used to auto generate +``moc`` and ``uic`` files. As this ``_autogen`` target is created at +generate-time, it is not possible to define dependencies of it, +such as to create inputs for the ``moc`` or ``uic`` executable. -The ``AUTOGEN_TARGET_DEPENDS`` target property can be set instead to a list of -dependencies for the ``_autogen`` target. The buildsystem will be generated to -depend on its contents. +The :prop_tgt:`AUTOGEN_TARGET_DEPENDS` target property can be set instead to a +list of dependencies of the ``_autogen`` target. Dependencies can be target +names or file names. See the :manual:`cmake-qt(7)` manual for more information on using CMake with Qt. + +Use cases +^^^^^^^^^ + +If :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC` depends on a file that is either + +- a :prop_sf:`GENERATED` non C++ file (e.g. a :prop_sf:`GENERATED` ``.json`` + or ``.ui`` file) or +- a :prop_sf:`GENERATED` C++ file that isn't recognized by :prop_tgt:`AUTOMOC` + and :prop_tgt:`AUTOUIC` because it's skipped by :prop_sf:`SKIP_AUTOMOC`, + :prop_sf:`SKIP_AUTOUIC`, :prop_sf:`SKIP_AUTOGEN` or :policy:`CMP0071` or +- a file that isn't in the target's sources + +it must added to :prop_tgt:`AUTOGEN_TARGET_DEPENDS`. diff --git a/Help/prop_tgt/AUTOMOC.rst b/Help/prop_tgt/AUTOMOC.rst index 9e5261f..3bd693a 100644 --- a/Help/prop_tgt/AUTOMOC.rst +++ b/Help/prop_tgt/AUTOMOC.rst @@ -71,7 +71,8 @@ automoc targets together in an IDE, e.g. in MSVS. The global property :prop_gbl:`AUTOGEN_SOURCE_GROUP` can be used to group files generated by :prop_tgt:`AUTOMOC` together in an IDE, e.g. in MSVS. -Additional macro names to search for can be added to :prop_tgt:`AUTOMOC_MACRO_NAMES`. +Additional macro names to search for can be added to +:prop_tgt:`AUTOMOC_MACRO_NAMES`. Additional ``moc`` dependency file names can be extracted from source code by using :prop_tgt:`AUTOMOC_DEPEND_FILTERS`. @@ -82,5 +83,8 @@ which is controlled by :prop_tgt:`AUTOMOC_COMPILER_PREDEFINES`. Source C++ files can be excluded from :prop_tgt:`AUTOMOC` processing by enabling :prop_sf:`SKIP_AUTOMOC` or the broader :prop_sf:`SKIP_AUTOGEN`. +The number of parallel ``moc`` processes to start can be modified by +setting :prop_tgt:`AUTOGEN_PARALLEL`. + See the :manual:`cmake-qt(7)` manual for more information on using CMake with Qt. diff --git a/Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst b/Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst index b738ecf..69957bf 100644 --- a/Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst +++ b/Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst @@ -1,21 +1,27 @@ AUTOMOC_DEPEND_FILTERS ---------------------- -Filter definitions used by :prop_tgt:`AUTOMOC` to extract file names from -source code as additional dependencies for the ``moc`` file. - -This property is only used if the :prop_tgt:`AUTOMOC` property is ``ON`` -for this target. +Filter definitions used by :prop_tgt:`AUTOMOC` to extract file names from a +source file that are registered as additional dependencies for the +``moc`` file of the source file. Filters are defined as ``KEYWORD;REGULAR_EXPRESSION`` pairs. First the file content is searched for ``KEYWORD``. If it is found at least once, then file names are extracted by successively searching for ``REGULAR_EXPRESSION`` and taking the first match group. -Consider a filter extracts the file name ``DEP`` from the content of a file -``FOO``. If ``DEP`` changes, then the ``moc`` file for ``FOO`` gets rebuilt. -The file ``DEP`` is searched for first in the vicinity -of ``FOO`` and afterwards in the target's :prop_tgt:`INCLUDE_DIRECTORIES`. +The file name found in the first match group is searched for + +- first in the vicinity of the source file +- and afterwards in the target's :prop_tgt:`INCLUDE_DIRECTORIES`. + +If any of the extracted files changes, then the ``moc`` file for the source +file gets rebuilt even when the source file itself doesn't change. + +If any of the extracted files is :prop_sf:`GENERATED` or if it is not in the +target's sources, then it might be necessary to add it to the +``_autogen`` target dependencies. +See :prop_tgt:`AUTOGEN_TARGET_DEPENDS` for reference. By default :prop_tgt:`AUTOMOC_DEPEND_FILTERS` is initialized from :variable:`CMAKE_AUTOMOC_DEPEND_FILTERS`, which is empty by default. @@ -24,22 +30,75 @@ See the :manual:`cmake-qt(7)` manual for more information on using CMake with Qt. -Example -^^^^^^^ +Example 1 +^^^^^^^^^ -Consider a file ``FOO.hpp`` holds a custom macro ``OBJ_JSON_FILE`` and we -want the ``moc`` file to depend on the macro`s file name argument:: +A header file ``my_class.hpp`` uses a custom macro ``JSON_FILE_MACRO`` which +is defined in an other header ``macros.hpp``. +We want the ``moc`` file of ``my_class.hpp`` to depend on the file name +argument of ``JSON_FILE_MACRO``:: + // my_class.hpp class My_Class : public QObject { Q_OBJECT - OBJ_JSON_FILE ( "DEP.json" ) + JSON_FILE_MACRO ( "info.json" ) + ... + }; + +In ``CMakeLists.txt`` we add a filter to +:variable:`CMAKE_AUTOMOC_DEPEND_FILTERS` like this:: + + list( APPEND CMAKE_AUTOMOC_DEPEND_FILTERS + "JSON_FILE_MACRO" + "[\n][ \t]*JSON_FILE_MACRO[ \t]*\\([ \t]*\"([^\"]+)\"" + ) + +We assume ``info.json`` is a plain (not :prop_sf:`GENERATED`) file that is +listed in the target's source. Therefore we do not need to add it to +:prop_tgt:`AUTOGEN_TARGET_DEPENDS`. + +Example 2 +^^^^^^^^^ + +In the target ``my_target`` a header file ``complex_class.hpp`` uses a +custom macro ``JSON_BASED_CLASS`` which is defined in an other header +``macros.hpp``:: + + // macros.hpp ... + #define JSON_BASED_CLASS(name, json) \ + class name : public QObject \ + { \ + Q_OBJECT \ + Q_PLUGIN_METADATA(IID "demo" FILE json) \ + name() {} \ }; + ... + +:: -Then we might use :variable:`CMAKE_AUTOMOC_DEPEND_FILTERS` to -define a filter like this:: + // complex_class.hpp + #pragma once + JSON_BASED_CLASS(Complex_Class, "meta.json") + // end of file - set(CMAKE_AUTOMOC_DEPEND_FILTERS - "OBJ_JSON_FILE" "[\n][ \t]*OBJ_JSON_FILE[ \t]*\\([ \t]*\"([^\"]+)\"" +Since ``complex_class.hpp`` doesn't contain a ``Q_OBJECT`` macro it would be +ignored by :prop_tgt:`AUTOMOC`. We change this by adding ``JSON_BASED_CLASS`` +to :variable:`CMAKE_AUTOMOC_MACRO_NAMES`:: + + list(APPEND CMAKE_AUTOMOC_MACRO_NAMES "JSON_BASED_CLASS") + +We want the ``moc`` file of ``complex_class.hpp`` to depend on +``meta.json``. So we add a filter to +:variable:`CMAKE_AUTOMOC_DEPEND_FILTERS`:: + + list(APPEND CMAKE_AUTOMOC_DEPEND_FILTERS + "JSON_BASED_CLASS" + "[\n^][ \t]*JSON_BASED_CLASS[ \t]*\\([^,]*,[ \t]*\"([^\"]+)\"" ) + +Additionally we assume ``meta.json`` is :prop_sf:`GENERATED` which is +why we have to add it to :prop_tgt:`AUTOGEN_TARGET_DEPENDS`:: + + set_property(TARGET my_target APPEND PROPERTY AUTOGEN_TARGET_DEPENDS "meta.json") diff --git a/Help/prop_tgt/AUTOMOC_MACRO_NAMES.rst b/Help/prop_tgt/AUTOMOC_MACRO_NAMES.rst index a5ad9d5..a9a0ecf 100644 --- a/Help/prop_tgt/AUTOMOC_MACRO_NAMES.rst +++ b/Help/prop_tgt/AUTOMOC_MACRO_NAMES.rst @@ -25,8 +25,8 @@ with Qt. Example ^^^^^^^ -In this case the the ``Q_OBJECT`` macro is hidden inside an other macro -called ``CUSTOM_MACRO``. To let CMake know that source files, that contain -``CUSTOM_MACRO``, need to be ``moc`` processed, we call:: +In this case the ``Q_OBJECT`` macro is hidden inside another macro +called ``CUSTOM_MACRO``. To let CMake know that source files that contain +``CUSTOM_MACRO`` need to be ``moc`` processed, we call:: set_property(TARGET tgt APPEND PROPERTY AUTOMOC_MACRO_NAMES "CUSTOM_MACRO") diff --git a/Help/prop_tgt/AUTORCC.rst b/Help/prop_tgt/AUTORCC.rst index c0f6a26..3cc5990 100644 --- a/Help/prop_tgt/AUTORCC.rst +++ b/Help/prop_tgt/AUTORCC.rst @@ -13,6 +13,11 @@ as target sources at build time and invoke ``rcc`` accordingly. This property is initialized by the value of the :variable:`CMAKE_AUTORCC` variable if it is set when a target is created. +By default :prop_tgt:`AUTORCC` is processed inside a +:command:`custom command <add_custom_command>`. +If the ``.qrc`` file is :prop_sf:`GENERATED` though, a +:command:`custom target <add_custom_target>` is used instead. + Additional command line options for rcc can be set via the :prop_sf:`AUTORCC_OPTIONS` source file property on the ``.qrc`` file. diff --git a/Help/prop_tgt/AUTOUIC.rst b/Help/prop_tgt/AUTOUIC.rst index 1791384..4fc603f 100644 --- a/Help/prop_tgt/AUTOUIC.rst +++ b/Help/prop_tgt/AUTOUIC.rst @@ -33,5 +33,8 @@ autouic targets together in an IDE, e.g. in MSVS. Source files can be excluded from :prop_tgt:`AUTOUIC` processing by enabling :prop_sf:`SKIP_AUTOUIC` or the broader :prop_sf:`SKIP_AUTOGEN`. +The number of parallel ``uic`` processes to start can be modified by +setting :prop_tgt:`AUTOGEN_PARALLEL`. + See the :manual:`cmake-qt(7)` manual for more information on using CMake with Qt. diff --git a/Help/prop_tgt/COMMON_LANGUAGE_RUNTIME.rst b/Help/prop_tgt/COMMON_LANGUAGE_RUNTIME.rst new file mode 100644 index 0000000..052ac6d --- /dev/null +++ b/Help/prop_tgt/COMMON_LANGUAGE_RUNTIME.rst @@ -0,0 +1,22 @@ +COMMON_LANGUAGE_RUNTIME +----------------------- + +By setting this target property, the target is configured to build with +``C++/CLI`` support. + +The Visual Studio generator defines the ``clr`` parameter depending on +the value of ``COMMON_LANGUAGE_RUNTIME``: + +* property not set: native C++ (i.e. default) +* property set but empty: mixed unmanaged/managed C++ +* property set to any non empty value: managed C++ + +Supported values: ``""``, ``"pure"``, ``"safe"`` + +This property is only evaluated :ref:`Visual Studio Generators` for +VS 2010 and above. + +To be able to build managed C++ targets with VS 2017 and above the component +``C++/CLI support`` must be installed, which may not be done by default. + +See also :prop_tgt:`IMPORTED_COMMON_LANGUAGE_RUNTIME` diff --git a/Help/prop_tgt/COMPILE_FLAGS.rst b/Help/prop_tgt/COMPILE_FLAGS.rst index 1a5389e..8fe651b 100644 --- a/Help/prop_tgt/COMPILE_FLAGS.rst +++ b/Help/prop_tgt/COMPILE_FLAGS.rst @@ -8,4 +8,4 @@ build sources within the target. Use :prop_tgt:`COMPILE_DEFINITIONS` to pass additional preprocessor definitions. This property is deprecated. Use the :prop_tgt:`COMPILE_OPTIONS` -property or the command:`target_compile_options` command instead. +property or the :command:`target_compile_options` command instead. diff --git a/Help/prop_tgt/CUDA_SEPARABLE_COMPILATION.rst b/Help/prop_tgt/CUDA_SEPARABLE_COMPILATION.rst index 1c7dd80..d306d7f 100644 --- a/Help/prop_tgt/CUDA_SEPARABLE_COMPILATION.rst +++ b/Help/prop_tgt/CUDA_SEPARABLE_COMPILATION.rst @@ -11,3 +11,7 @@ For instance: .. code-block:: cmake set_property(TARGET myexe PROPERTY CUDA_SEPARABLE_COMPILATION ON) + +This property is initialized by the value of the +:variable:`CMAKE_CUDA_SEPARABLE_COMPILATION` variable if it is set when a +target is created. diff --git a/Help/prop_tgt/CXX_STANDARD.rst b/Help/prop_tgt/CXX_STANDARD.rst 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/DOTNET_TARGET_FRAMEWORK_VERSION.rst b/Help/prop_tgt/DOTNET_TARGET_FRAMEWORK_VERSION.rst new file mode 100644 index 0000000..a2f7d7d --- /dev/null +++ b/Help/prop_tgt/DOTNET_TARGET_FRAMEWORK_VERSION.rst @@ -0,0 +1,13 @@ +DOTNET_TARGET_FRAMEWORK_VERSION +------------------------------- + +Specify the .NET target framework version. + +Used to specify the .NET target framework version for C++/CLI. For +example, "v4.5". + +This property is only evaluated for :ref:`Visual Studio Generators` +VS 2010 and above. + +Can be initialized for all targets using the variable +:variable:`CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION`. 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/IMPORTED_COMMON_LANGUAGE_RUNTIME.rst b/Help/prop_tgt/IMPORTED_COMMON_LANGUAGE_RUNTIME.rst new file mode 100644 index 0000000..99e3bc4 --- /dev/null +++ b/Help/prop_tgt/IMPORTED_COMMON_LANGUAGE_RUNTIME.rst @@ -0,0 +1,8 @@ +IMPORTED_COMMON_LANGUAGE_RUNTIME +-------------------------------- + +Property to define if the target uses ``C++/CLI``. + +Ignored for non-imported targets. + +See also the :prop_tgt:`COMMON_LANGUAGE_RUNTIME` target property. diff --git a/Help/prop_tgt/IMPORTED_GLOBAL.rst b/Help/prop_tgt/IMPORTED_GLOBAL.rst new file mode 100644 index 0000000..1feca04 --- /dev/null +++ b/Help/prop_tgt/IMPORTED_GLOBAL.rst @@ -0,0 +1,22 @@ +IMPORTED_GLOBAL +--------------- + +Indication of whether an :ref:`IMPORTED target <Imported Targets>` is +globally visible. + +The boolean value of this property is True for targets created with the +``IMPORTED`` ``GLOBAL`` options to :command:`add_executable()` or +:command:`add_library()`. It is always False for targets built within the +project. + +For targets created with the ``IMPORTED`` option to +:command:`add_executable()` or :command:`add_library()` but without the +additional option ``GLOBAL`` this is False, too. However, setting this +property for such a locally ``IMPORTED`` target to True promotes that +target to global scope. This promotion can only be done in the same +directory where that ``IMPORTED`` target was created in the first place. + +Once an imported target has been made global, it cannot be changed back to +non-global. Therefore, if a project sets this property, it may only +provide a value of True. CMake will issue an error if the project tries to +set the property to a non-True value, even if the value was already False. 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/LANG_COMPILER_LAUNCHER.rst b/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst index 28925fc..b63d6d7 100644 --- a/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst +++ b/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst @@ -2,7 +2,7 @@ ------------------------ This property is implemented only when ``<LANG>`` is ``C``, ``CXX``, -or ``CUDA``. +``Fortran``, or ``CUDA``. Specify a :ref:`;-list <CMake Language Lists>` containing a command line for a compiler launching tool. The :ref:`Makefile Generators` and the diff --git a/Help/prop_tgt/LINK_FLAGS.rst b/Help/prop_tgt/LINK_FLAGS.rst index 409d00a..b09e7c1 100644 --- a/Help/prop_tgt/LINK_FLAGS.rst +++ b/Help/prop_tgt/LINK_FLAGS.rst @@ -4,5 +4,6 @@ LINK_FLAGS Additional flags to use when linking this target. The LINK_FLAGS property can be used to add extra flags to the link -step of a target. LINK_FLAGS_<CONFIG> will add to the configuration -<CONFIG>, for example, DEBUG, RELEASE, MINSIZEREL, RELWITHDEBINFO. +step of a target. :prop_tgt:`LINK_FLAGS_<CONFIG>` will add to the +configuration ``<CONFIG>``, for example, ``DEBUG``, ``RELEASE``, +``MINSIZEREL``, ``RELWITHDEBINFO``, ... diff --git a/Help/prop_tgt/OUTPUT_NAME.rst b/Help/prop_tgt/OUTPUT_NAME.rst index f1bdb7c..4b33b38 100644 --- a/Help/prop_tgt/OUTPUT_NAME.rst +++ b/Help/prop_tgt/OUTPUT_NAME.rst @@ -5,7 +5,8 @@ Output name for target files. This sets the base name for output files created for an executable or library target. If not set, the logical target name is used by -default. +default during generation. The value is not set by default during +configuration. Contents of ``OUTPUT_NAME`` and the variants listed below may use :manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/prop_tgt/PDB_OUTPUT_DIRECTORY.rst b/Help/prop_tgt/PDB_OUTPUT_DIRECTORY.rst index 730cf57..2f667f3 100644 --- a/Help/prop_tgt/PDB_OUTPUT_DIRECTORY.rst +++ b/Help/prop_tgt/PDB_OUTPUT_DIRECTORY.rst @@ -5,8 +5,14 @@ Output directory for the MS debug symbols ``.pdb`` file generated by the linker for an executable or shared library target. This property specifies the directory into which the MS debug symbols -will be placed by the linker. This property is initialized by the -value of the :variable:`CMAKE_PDB_OUTPUT_DIRECTORY` variable if it is +will be placed by the linker. The property value may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. +Multi-configuration generators append a per-configuration +subdirectory to the specified directory unless a generator expression +is used. + +This property is initialized by the value of the +:variable:`CMAKE_PDB_OUTPUT_DIRECTORY` variable if it is set when a target is created. .. |COMPILE_PDB_XXX| replace:: :prop_tgt:`COMPILE_PDB_OUTPUT_DIRECTORY` diff --git a/Help/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG.rst b/Help/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG.rst index 6037fa0..77fda90 100644 --- a/Help/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG.rst +++ b/Help/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG.rst @@ -11,5 +11,8 @@ property is initialized by the value of the :variable:`CMAKE_PDB_OUTPUT_DIRECTORY_<CONFIG>` variable if it is set when a target is created. +Contents of ``PDB_OUTPUT_DIRECTORY_<CONFIG>`` may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. + .. |COMPILE_PDB_XXX| replace:: :prop_tgt:`COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG>` .. include:: PDB_NOTE.txt diff --git a/Help/prop_tgt/TYPE.rst b/Help/prop_tgt/TYPE.rst index 5ac63cc..1cd9db4 100644 --- a/Help/prop_tgt/TYPE.rst +++ b/Help/prop_tgt/TYPE.rst @@ -5,5 +5,5 @@ The type of the target. This read-only property can be used to test the type of the given target. It will be one of STATIC_LIBRARY, MODULE_LIBRARY, -SHARED_LIBRARY, INTERFACE_LIBRARY, EXECUTABLE or one of the internal -target types. +SHARED_LIBRARY, OBJECT_LIBRARY, INTERFACE_LIBRARY, EXECUTABLE or one +of the internal target types. 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/prop_tgt/VS_DOTNET_TARGET_FRAMEWORK_VERSION.rst b/Help/prop_tgt/VS_DOTNET_TARGET_FRAMEWORK_VERSION.rst index 829d696..9f5a313 100644 --- a/Help/prop_tgt/VS_DOTNET_TARGET_FRAMEWORK_VERSION.rst +++ b/Help/prop_tgt/VS_DOTNET_TARGET_FRAMEWORK_VERSION.rst @@ -5,3 +5,6 @@ Specify the .NET target framework version. Used to specify the .NET target framework version for C++/CLI. For example, "v4.5". + +This property is deprecated and should not be used anymore. Use +:prop_tgt:`DOTNET_TARGET_FRAMEWORK_VERSION` instead. diff --git a/Help/release/3.0.rst b/Help/release/3.0.rst index d02f940..64491e3 100644 --- a/Help/release/3.0.rst +++ b/Help/release/3.0.rst @@ -224,7 +224,7 @@ Modules option to change the ``boost`` prefix on library names. * The :module:`FindBoost` module learned to control search - for libraies with the ``g`` tag (for MS debug runtime) with + for libraries with the ``g`` tag (for MS debug runtime) with a new ``Boost_USE_DEBUG_RUNTIME`` option. It is ``ON`` by default to preserve existing behavior. diff --git a/Help/release/3.11.rst b/Help/release/3.11.rst new file mode 100644 index 0000000..214da0d --- /dev/null +++ b/Help/release/3.11.rst @@ -0,0 +1,307 @@ +CMake 3.11 Release Notes +************************ + +.. only:: html + + .. contents:: + +Changes made since CMake 3.10 include the following. + +New Features +============ + +Platforms +--------- + +* TI C/C++ compilers are now supported by the :generator:`Ninja` generator. + +Generators +---------- + +* The :generator:`CodeBlocks` extra generator learned to check a + :variable:`CMAKE_CODEBLOCKS_COMPILER_ID` variable for a custom + compiler identification value to place in the project file. + +* The :ref:`Makefile Generators` and the :generator:`Ninja` generator learned + to add compiler launcher tools along with the compiler for the ``Fortran`` + language (``C``, ``CXX``, and ``CUDA`` were supported previously). + See the :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER` variable and + :prop_tgt:`<LANG>_COMPILER_LAUNCHER` target property for details. + +* :ref:`Visual Studio Generators` learned to support the ``COMPILE_LANGUAGE`` + :manual:`generator expression <cmake-generator-expressions(7)>` in + target-wide :prop_tgt:`COMPILE_DEFINITIONS`, + :prop_tgt:`INCLUDE_DIRECTORIES`, :prop_tgt:`COMPILE_OPTIONS`, and + :command:`file(GENERATE)`. See generator expression documentation + for caveats. + +* The :generator:`Xcode` generator learned to support the ``COMPILE_LANGUAGE`` + :manual:`generator expression <cmake-generator-expressions(7)>` in + target-wide :prop_tgt:`COMPILE_DEFINITIONS` and + :prop_tgt:`INCLUDE_DIRECTORIES`. It previously supported only + :prop_tgt:`COMPILE_OPTIONS` and :command:`file(GENERATE)`. + See generator expression documentation for caveats. + +Commands +-------- + +* :command:`add_library` and :command:`add_executable` commands can now be + called without any sources and will not complain as long as sources are + added later via the :command:`target_sources` command. + +* The :command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands + gained ``NETRC`` and ``NETRC_FILE`` options to specify use of a + ``.netrc`` file. + +* The :command:`target_compile_definitions` command learned to set the + :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` property on + :ref:`Imported Targets`. + +* The :command:`target_compile_features` command learned to set the + :prop_tgt:`INTERFACE_COMPILE_FEATURES` property on :ref:`Imported Targets`. + +* The :command:`target_compile_options` command learned to set the + :prop_tgt:`INTERFACE_COMPILE_OPTIONS` property on :ref:`Imported Targets`. + +* The :command:`target_include_directories` command learned to set the + :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` property on + :ref:`Imported Targets`. + +* The :command:`target_sources` command learned to set the + :prop_tgt:`INTERFACE_SOURCES` property on :ref:`Imported Targets`. + +* The :command:`target_link_libraries` command learned to set the + :prop_tgt:`INTERFACE_LINK_LIBRARIES` property on :ref:`Imported Targets`. + +Variables +--------- + +* A :variable:`CMAKE_GENERATOR_INSTANCE` variable was introduced + to hold the selected instance of the generator's corresponding + native tools if multiple are available. This is used by the + :generator:`Visual Studio 15 2017` generator to hold the + selected instance of Visual Studio persistently. + +* A :variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` variable was added + to enable setting of default permissions for directories created implicitly + during installation of files by :command:`install` and + :command:`file(INSTALL)`, e.g. during ``make install``. + +* A :variable:`CMAKE_JOB_POOLS` variable was added specify a value to use for + the :prop_gbl:`JOB_POOLS` property. This enables control over build + parallelism with command line configuration parameters when using the Ninja + generator. + +* The :variable:`CMAKE_NETRC` and :variable:`CMAKE_NETRC_FILE` variables + were added to specify use of a ``.netrc`` file by the + :command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands and + the :module:`ExternalProject` module. + +* A :variable:`CMAKE_CUDA_SEPARABLE_COMPILATION` variable was added to + initialize the :prop_tgt:`CUDA_SEPARABLE_COMPILATION` target property + on targets when they are created. + +Properties +---------- + +* The :prop_sf:`COMPILE_DEFINITIONS` source file property learned to support + :manual:`generator expressions <cmake-generator-expressions(7)>`. + +* A :prop_sf:`COMPILE_OPTIONS` source file property was added to manage list + of options to pass to the compiler. + +* An :prop_tgt:`IMPORTED_GLOBAL` target property was added to indicate + whether an :ref:`IMPORTED target <Imported Targets>` is globally visible. + It is automatically set to a true value for targets created with the + ``GLOBAL`` option to :command:`add_library` or :command:`add_executable`. + Additionally, project code may now *promote* a local imported target + to be globally visible by setting this property to ``TRUE``. + +* An :prop_sf:`INCLUDE_DIRECTORIES` source file property was added to specify + list of preprocessor include file search directories. + +* Source file properties :prop_sf:`VS_SHADER_DISABLE_OPTIMIZATIONS` and + :prop_sf:`VS_SHADER_ENABLE_DEBUG` have been added to specify more + details of ``.hlsl`` sources with :ref:`Visual Studio Generators`. + +Modules +------- + +* The :module:`CheckIncludeFiles` module :command:`CHECK_INCLUDE_FILES` + command gained a ``LANGUAGE`` option to specify whether to check using the + ``C`` or ``CXX`` compiler. + +* The :module:`CMakePackageConfigHelpers` module + :command:`write_basic_package_version_file` command learned a new + ``SameMinorVersion`` mode for the ``COMPATIBILITY`` argument. + +* The :module:`ExternalProject` module learned to substitute ``<DOWNLOAD_DIR>`` + in comments, commands, working directory and byproducts. + +* The :module:`ExternalProject` module gained ``NETRC`` and ``NETRC_FILE`` + options to specify use of a ``.netrc`` file. + +* A new :module:`FetchContent` module was added which supports populating + content at configure time using any of the download/update methods + supported by :command:`ExternalProject_Add`. This allows the content + to be used immediately during the configure stage, such as with + :command:`add_subdirectory`, etc. Hierarchical project structures are + well supported, allowing parent projects to override the content details + of child projects and ensuring content is not populated multiple times + throughout the whole project tree. + +* The :module:`FindBLAS` and :module:`FindLAPACK` modules learned to support + `FLAME`_ ``blis`` and ``libflame``. + +* The :module:`FindDoxygen` module :command:`doxygen_add_docs` function + now supports a new ``DOXYGEN_VERBATIM_VARS`` list variable. Any + ``DOXYGEN_...`` variable contained in that list will bypass the automatic + quoting logic, leaving its contents untouched when transferring them to the + output ``Doxyfile``. + +* A :module:`FindIconv` module was added to locate iconv support. + +* The :module:`GenerateExportHeader` module ``GENERATE_EXPORT_HEADER`` command + gained an ``INCLUDE_GUARD_NAME`` option to change the name of the include + guard symbol written to the generated export header. + Additionally, it now adds a comment after the closing ``#endif`` on the + generated export header's include guard. + +* The :module:`UseJava` module ``add_jar`` command gained a + ``GENERATE_NATIVE_HEADERS`` option to generate native header files + using ``javac -h`` for ``javac`` 1.8 or above. This supersedes + ``create_javah``, which no longer works with JDK 1.10 and above due + to removal of the ``javah`` tool by `JEP 313`_. + +.. _`FLAME`: https://github.com/flame +.. _`JEP 313`: http://openjdk.java.net/jeps/313 + +Autogen +------- + +* When using :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC`, CMake now starts + multiple parallel ``moc`` or ``uic`` processes to reduce the build time. + A new :variable:`CMAKE_AUTOGEN_PARALLEL` variable and + :prop_tgt:`AUTOGEN_PARALLEL` target property may be set to specify the + number of parallel ``moc`` or ``uic`` processes to start. The default + is derived from the number of CPUs on the host. + +CTest +----- + +* The :command:`ctest_start` command no longer sets + :variable:`CTEST_RUN_CURRENT_SCRIPT` due to issues with scoping if it is + called from inside a function. Instead, it sets an internal variable in + CTest. However, setting :variable:`CTEST_RUN_CURRENT_SCRIPT` to 0 at the + global scope still prevents the script from being re-run at the end. + +CPack +----- + +* :manual:`cpack(1)` gained ``--trace`` and ``--trace-expand`` options. + +* The :module:`CPackIFW` module gained new + :variable:`CPACK_IFW_PACKAGE_REMOVE_TARGET_DIR` variable to control + if the target directory should not be deleted when uninstalling. + +* The :module:`CPackRPM` module learned to enable enforcing of execute + privileges on programs and shared libraries. + See :variable:`CPACK_RPM_INSTALL_WITH_EXEC` variable. + +* A :variable:`CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` variable was added + which serves the same purpose during packaging (e.g. ``make package``) as the + :variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` variable serves during + installation (e.g. ``make install``). + +Other +----- + +* :ref:`Alias Targets` may now alias :ref:`Imported Targets` that are + created with the ``GLOBAL`` option to :command:`add_library`. + +* :ref:`Interface Libraries` may now have custom properties set on them if + they start with either an underscore (``_``) or a lowercase ASCII character. + The original intention was to only allow properties which made sense for + ``INTERFACE`` libraries, but it also blocked usage of custom properties. + +* The :manual:`cmake(1)` ``--open <dir>`` command-line option was added + to open generated IDE projects like Visual Studio solutions or Xcode + projects. + +Deprecated and Removed Features +=============================== + +* An explicit deprecation diagnostic was added for policies ``CMP0037`` + through ``CMP0054`` (``CMP0036`` and below were already deprecated). + The :manual:`cmake-policies(7)` manual explains that the OLD behaviors + of all policies are deprecated and that projects should port to the + NEW behaviors. + +* The ``KDevelop3`` generator has been removed. + +Other Changes +============= + +* Policy :policy:`CMP0037` no longer reserves target names associated + with optional features, such as ``test`` and ``package``, unless + the corresponding feature is enabled. + +* The :module:`FindOpenGL` module now prefers GLVND libraries if available. + See policy :policy:`CMP0072`. + +* The minimum deployment target set in the + :variable:`CMAKE_OSX_DEPLOYMENT_TARGET` variable used to be only + applied for macOS regardless of the selected SDK. It is now properly + set for the target platform selected by :variable:`CMAKE_OSX_SYSROOT`. + For example, if the sysroot variable specifies an iOS SDK then the + value in ``CMAKE_OSX_DEPLOYMENT_TARGET`` is interpreted as minimum + iOS version. + +* The :generator:`Xcode` generator behavior of generating one project + file per :command:`project()` command may now be controlled with the + :variable:`CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY` variable. + This could be useful to speed up the CMake generation step for + large projects and to work-around a bug in the ``ZERO_CHECK`` logic. + +* Since the ``CMakeCache.txt`` format does not support newlines in values, + values containing newlines are now truncated before writing to the file. + In addition, a warning comment is written to the cache file, and a warning + message is displayed to the user on the console. + +Updates +======= + +Changes made since CMake 3.11.0 include the following. + +3.11.1 +------ + +* The :module:`CheckIncludeFile` module ``check_include_file`` macro, + :module:`CheckIncludeFileCXX` module ``check_include_file_cxx`` macro, + and :module:`CheckIncludeFiles` module ``check_include_files`` macro + were taught to honor the ``CMAKE_REQUIRED_LIBRARIES`` variable in + CMake 3.11.0. This has been reverted due to changing behavior of + checks for existing projects. It may be restored in the future + with a policy for compatibility. + +3.11.2 +------ + +* Calling :command:`add_library` to create an alias of an imported + target that is not globally visible now causes an error again as + it did prior to 3.11.0. This diagnostic was accidentally dropped + from CMake 3.11.0 and 3.11.1 by the change to allow globally visible + imported targets to be aliased. + +* The :module:`FindQt4` module ``qt4_wrap_cpp``, ``qt4_wrap_ui`` and + ``qt4_add_resources`` macros now set :prop_sf:`SKIP_AUTOMOC` and + :prop_sf:`SKIP_AUTOUIC` on their generated files. These files never + need to be processed by moc or uic, and we must say so explicitly to + account for policy :policy:`CMP0071`. + +3.11.3 +------ + +* CMake 3.11.0 introduced support for resolving symbolic links on + Windows in code paths that typically do so on UNIX. This has been + reverted due to breakage on ``subst`` drives. diff --git a/Help/release/3.12.rst b/Help/release/3.12.rst new file mode 100644 index 0000000..f00be3e --- /dev/null +++ b/Help/release/3.12.rst @@ -0,0 +1,305 @@ +CMake 3.12 Release Notes +************************ + +.. only:: html + + .. contents:: + +Changes made since CMake 3.11 include the following. + +New Features +============ + +Generators +---------- + +* The :ref:`Visual Studio Generators` for VS 2017 learned to support a + ``version=14.##`` option in the :variable:`CMAKE_GENERATOR_TOOLSET` + value (e.g. via the :manual:`cmake(1)` ``-T`` option) to specify a + toolset version number. + +Command-Line +------------ + +* The :manual:`cmake(1)` :ref:`Build Tool Mode` (``cmake --build``) gained + ``--parallel [<jobs>]`` and ``-j [<jobs>]`` options to specify a parallel + build level. They map to corresponding options of the native build tool. + +Commands +-------- + +* The :command:`add_compile_definitions` command was added to set preprocessor + definitions at directory level. This supersedes :command:`add_definitions`. + +* 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 + older of the running CMake version and the version specified by + ``<max>``. This allows projects to specify a range of versions + for which they have been updated and avoid explicit policy settings. + +* 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. + +* 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`. + +* The :command:`find_package` command now searches prefixes specified by + the :variable:`<PackageName>_ROOT` CMake variable and the + :envvar:`<PackageName>_ROOT` 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`. + +* The :command:`install` command learned an optional ``NAMELINK_COMPONENT`` + parameter, which allows you to change the component for a shared library's + namelink. If none is specified, the value of ``COMPONENT`` is used by + default. + +* The :command:`list` command learned a ``JOIN`` sub-command + to concatenate list's elements separated by a glue string. + +* The :command:`list` command learned a ``SUBLIST`` sub-command + to get a sublist of the list. + +* The :command:`list` command learned a ``TRANSFORM`` sub-command + to apply various string transformation to list's elements. + +* 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`. + +* The :command:`string` command learned a ``JOIN`` sub-command + to concatenate input strings separated by a glue string. + +* :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. + +* 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. + +Variables +--------- + +* The :variable:`CMAKE_FOLDER` variable was added to initialize the + :prop_tgt:`FOLDER` property on all targets. + +* The :variable:`CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION` variable + was defined to initialize all + :prop_tgt:`DOTNET_TARGET_FRAMEWORK_VERSION` target properties. + +* ``CMAKE_PROJECT_VERSION*`` variables have been introduced: + + - :variable:`CMAKE_PROJECT_VERSION` + - :variable:`CMAKE_PROJECT_VERSION_MAJOR` + - :variable:`CMAKE_PROJECT_VERSION_MINOR` + - :variable:`CMAKE_PROJECT_VERSION_PATCH` + - :variable:`CMAKE_PROJECT_VERSION_TWEAK` + +* The :variable:`CMAKE_SUPPRESS_REGENERATION` variable was extended to + support the :generator:`Ninja` and :ref:`Makefile Generators`. + It is also now documented. + +* ``CMAKE_VS_SDK_*_DIRECTORIES`` variables were defined to tell + :ref:`Visual Studio Generators` for VS 2010 and above how to populate + fields in ``.vcxproj`` files that specify SDK directories. The + variables are: + + - :variable:`CMAKE_VS_SDK_EXCLUDE_DIRECTORIES` + - :variable:`CMAKE_VS_SDK_EXECUTABLE_DIRECTORIES` + - :variable:`CMAKE_VS_SDK_INCLUDE_DIRECTORIES` + - :variable:`CMAKE_VS_SDK_LIBRARY_DIRECTORIES` + - :variable:`CMAKE_VS_SDK_LIBRARY_WINRT_DIRECTORIES` + - :variable:`CMAKE_VS_SDK_REFERENCE_DIRECTORIES` + - :variable:`CMAKE_VS_SDK_SOURCE_DIRECTORIES` + +* 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`. + +Properties +---------- + +* The :prop_tgt:`COMMON_LANGUAGE_RUNTIME` target property was introduced + to configure the use of managed C++ for :ref:`Visual Studio Generators` + for VS 2010 and above. + A corresponding :prop_tgt:`IMPORTED_COMMON_LANGUAGE_RUNTIME` target + property was added to support ``C++/CLI`` for imported targets. + +* The :prop_tgt:`DOTNET_TARGET_FRAMEWORK_VERSION` target property + was introduced as replacement for + :prop_tgt:`VS_DOTNET_TARGET_FRAMEWORK_VERSION`, which is considered + deprecated now. + +* 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. + +* The :prop_tgt:`PDB_OUTPUT_DIRECTORY` property learned to support + :manual:`generator expressions <cmake-generator-expressions(7)>`. + +* A :prop_dir:`TESTS` directory property was added to hold the list of + tests defined by the :command:`add_test` command. + +* A :prop_tgt:`VS_DEBUGGER_COMMAND` target property was created to set the + debugging command line with :ref:`Visual Studio Generators` for VS 2010 + and above. + +* HLSL source file properties :prop_sf:`VS_SHADER_DISABLE_OPTIMIZATIONS` + and :prop_sf:`VS_SHADER_ENABLE_DEBUG` gained support for generator + expressions. + +* HLSL source file property :prop_sf:`VS_SHADER_OBJECT_FILE_NAME` has been + added to the :ref:`Visual Studio Generators` for VS 2010 and above. + The property specifies the file name of the compiled shader object. + +Modules +------- + +* The :module:`FindALSA` module now provides imported targets. + +* The :module:`FindCURL` module now provides imported targets. + +* The :module:`FindJPEG` module now provides imported targets. + +* The :module:`FindLibXml2` module now provides imported targets. + +* The :module:`FindMatlab` module now supports the Matlab Runtime + Compiler (MCR) for compiling and linking matlab extensions. + +* A :module:`FindODBC` module was added to find an Open Database Connectivity + (ODBC) library. + +* The :module:`FindPkgConfig` module has learned to export the found + libraries with full path for direct consumption with the + :command:`target_link_libraries` command. + +* New :module:`FindPython3` and :module:`FindPython2` modules, as well as + a new :module:`FindPython` module, have been added to provide a new way + to locate python environments. + +* The :module:`UseSWIG` module gained a whole refresh and is now more + consistent with standard CMake commands to generate libraries and is + fully configurable through properties. + +* 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``). + +* The :module:`UseSWIG` module learned to support CSHARP variant + wrapper files. + +* The :module:`WriteCompilerDetectionHeader` module gained a ``BARE_FEATURES`` + option to add a compatibility define for the exact keyword of a new language + feature. + +Generator Expressions +--------------------- + +* A new ``$<GENEX_EVAL:...>`` and ``$<TARGET_GENEX_EVAL:target,...>`` + :manual:`generator expression <cmake-generator-expressions(7)>` + has been added to enable consumption of generator expressions whose + evaluation results itself in generator expressions. + +* A new ``$<IN_LIST:...>`` + :manual:`generator expression <cmake-generator-expressions(7)>` + has been added. + +* A new ``$<TARGET_EXISTS:...>`` + :manual:`generator expression <cmake-generator-expressions(7)>` + has been added. + +* A new ``$<TARGET_NAME_IF_EXISTS:...>`` + :manual:`generator expression <cmake-generator-expressions(7)>` + has been added. + +CTest +----- + +* The :command:`ctest_start` command has been reworked so that you can simply + call ``ctest_start(APPEND)`` and it will read all the needed information from + the TAG file. The argument parsing has also been relaxed so that the order of + the arguments is less significant. + +* 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. + +CPack +----- + +* The :module:`CPack` module now uses variables + :variable:`CMAKE_PROJECT_VERSION_MAJOR`, + :variable:`CMAKE_PROJECT_VERSION_MINOR` and + :variable:`CMAKE_PROJECT_VERSION_PATCH` + to initialize corresponding CPack variables. + +* :manual:`cpack(1)` gained basic support for `NuGet`_. + See the :module:`CPackNuGet` module. + +.. _NuGet: https://docs.microsoft.com/en-us/nuget/what-is-nuget + +Other +----- + +* 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. + +* The :manual:`Compile Features <cmake-compile-features(7)>` functionality + is now aware of the availability of C features in MSVC since VS 2010. + +* The :manual:`Compile Features <cmake-compile-features(7)>` functionality + is now aware of C language standards supported by Texas Instruments C + compilers. + +Deprecated and Removed Features +=============================== + +* The :generator:`Visual Studio 8 2005` generator has been removed. + +* CMake no longer produces ``<tgt>_LIB_DEPENDS`` cache entries + for library targets. See policy :policy:`CMP0073`. + +Other Changes +============= + +* Include flags for directories marked as ``SYSTEM`` are now moved after + non-system directories. The ``-isystem`` flag does this automatically, + so moving them explicitly to the end makes the behavior consistent on + compilers that do not have any ``-isystem`` flag. + +* Fortran dependency scanning now supports dependencies implied by + `Fortran Submodules`_. + +* The existence and functionality of the file + ``${CMAKE_BINARY_DIR}/cmake_install.cmake`` has now been documented in the + :command:`install` documentation so that external packaging software can take + advantage of CPack-style component installs. + +* The :module:`CheckIncludeFile` module ``check_include_file`` macro + learned to honor the ``CMAKE_REQUIRED_LIBRARIES`` variable. + See policy :policy:`CMP0075`. + +* The :module:`CheckIncludeFileCXX` module ``check_include_file_cxx`` macro + learned to honor the ``CMAKE_REQUIRED_LIBRARIES`` variable. + See policy :policy:`CMP0075`. + +* The :module:`CheckIncludeFiles` module ``check_include_files`` macro + learned to honor the ``CMAKE_REQUIRED_LIBRARIES`` variable. + See policy :policy:`CMP0075`. + +* The :manual:`cmake(1)` ``-E copy_directory`` tool now fails when the + source directory does not exist. Previously it succeeded by creating + an empty destination directory. + +* 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. + +.. _`Fortran Submodules`: http://fortranwiki.org/fortran/show/Submodules diff --git a/Help/release/3.4.rst b/Help/release/3.4.rst index 89c5561..468627e 100644 --- a/Help/release/3.4.rst +++ b/Help/release/3.4.rst @@ -66,7 +66,7 @@ Variables Properties ---------- -* :ref:`Visual Studio Generators` learned to support additonal +* :ref:`Visual Studio Generators` learned to support additional target properties to customize projects for NVIDIA Nsight Tegra Visual Studio Edition: diff --git a/Help/release/3.6.rst b/Help/release/3.6.rst index 144537d..a542b77 100644 --- a/Help/release/3.6.rst +++ b/Help/release/3.6.rst @@ -111,7 +111,7 @@ Modules * The :module:`ExternalProject` module learned to initialize Git submodules recursively and also to initialize new submodules on updates. Use the - ``GIT_SUBMODULES`` option to restrict which submodules are initalized and + ``GIT_SUBMODULES`` option to restrict which submodules are initialized and updated. * The :module:`ExternalProject` module leared the ``DOWNLOAD_NO_EXTRACT 1`` diff --git a/Help/release/3.7.rst b/Help/release/3.7.rst index 4c51af4..d4d374b 100644 --- a/Help/release/3.7.rst +++ b/Help/release/3.7.rst @@ -237,7 +237,7 @@ CPack * The :module:`CPackIFW` module :command:`cpack_ifw_configure_component` and :command:`cpack_ifw_configure_component_group` commands gained a new - ``USER_INTERFACES`` option to add a list of additonal pages to the IFW + ``USER_INTERFACES`` option to add a list of additional pages to the IFW installer. * The :module:`CPackRPM` module learned to generate debuginfo diff --git a/Help/release/index.rst b/Help/release/index.rst index 0c7572f..4b32eab 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -13,6 +13,8 @@ Releases .. toctree:: :maxdepth: 1 + 3.12 <3.12> + 3.11 <3.11> 3.10 <3.10> 3.9 <3.9> 3.8 <3.8> diff --git a/Help/variable/CMAKE_ANDROID_STL_TYPE.rst b/Help/variable/CMAKE_ANDROID_STL_TYPE.rst index cfb76aa..d174575 100644 --- a/Help/variable/CMAKE_ANDROID_STL_TYPE.rst +++ b/Help/variable/CMAKE_ANDROID_STL_TYPE.rst @@ -30,7 +30,8 @@ set to specify the STL variant to be used. The value may be one of: ``stlport_shared`` STLport Shared -The default value is ``gnustl_static``. Note that this default differs from +The default value is ``gnustl_static`` on NDK versions that provide it +and otherwise ``c++_static``. Note that this default differs from the native NDK build system because CMake may be used to build projects for Android that are not natively implemented for it and use the C++ standard library. diff --git a/Help/variable/CMAKE_AUTOGEN_PARALLEL.rst b/Help/variable/CMAKE_AUTOGEN_PARALLEL.rst new file mode 100644 index 0000000..dd9499a --- /dev/null +++ b/Help/variable/CMAKE_AUTOGEN_PARALLEL.rst @@ -0,0 +1,10 @@ +CMAKE_AUTOGEN_PARALLEL +---------------------- + +Number of parallel ``moc`` or ``uic`` processes to start when using +:prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`. + +This variable is used to initialize the :prop_tgt:`AUTOGEN_PARALLEL` property +on all the targets. See that target property for additional information. + +By default :variable:`CMAKE_AUTOGEN_PARALLEL` is unset. diff --git a/Help/variable/CMAKE_AUTOMOC_MACRO_NAMES.rst b/Help/variable/CMAKE_AUTOMOC_MACRO_NAMES.rst index 5b79c40..2c8997b 100644 --- a/Help/variable/CMAKE_AUTOMOC_MACRO_NAMES.rst +++ b/Help/variable/CMAKE_AUTOMOC_MACRO_NAMES.rst @@ -12,7 +12,7 @@ information. The default value is ``Q_OBJECT;Q_GADGET;Q_NAMESPACE``. Example -------- +^^^^^^^ Let CMake know that source files that contain ``CUSTOM_MACRO`` must be ``moc`` processed as well:: diff --git a/Help/variable/CMAKE_BUILD_TYPE.rst b/Help/variable/CMAKE_BUILD_TYPE.rst index 2d54d60..2d35635 100644 --- a/Help/variable/CMAKE_BUILD_TYPE.rst +++ b/Help/variable/CMAKE_BUILD_TYPE.rst @@ -5,7 +5,7 @@ Specifies the build type on single-configuration generators. This statically specifies what build type (configuration) will be built in this build tree. Possible values are empty, ``Debug``, ``Release``, -``RelWithDebInfo`` and ``MinSizeRel``. This variable is only meaningful to +``RelWithDebInfo``, ``MinSizeRel``, ... This variable is only meaningful to single-configuration generators (such as :ref:`Makefile Generators` and :generator:`Ninja`) i.e. those which choose a single configuration when CMake runs to generate a build tree as opposed to multi-configuration generators @@ -13,7 +13,7 @@ which offer selection of the build configuration within the generated build environment. There are many per-config properties and variables (usually following clean ``SOME_VAR_<CONFIG>`` order conventions), such as ``CMAKE_C_FLAGS_<CONFIG>``, specified as uppercase: -``CMAKE_C_FLAGS_[DEBUG|RELEASE|RELWITHDEBINFO|MINSIZEREL]``. For example, +``CMAKE_C_FLAGS_[DEBUG|RELEASE|RELWITHDEBINFO|MINSIZEREL|...]``. For example, in a build tree configured to build type ``Debug``, CMake will see to having :variable:`CMAKE_C_FLAGS_DEBUG <CMAKE_<LANG>_FLAGS_DEBUG>` settings get added to the :variable:`CMAKE_C_FLAGS <CMAKE_<LANG>_FLAGS>` settings. See 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_CODEBLOCKS_COMPILER_ID.rst b/Help/variable/CMAKE_CODEBLOCKS_COMPILER_ID.rst new file mode 100644 index 0000000..ad2709d --- /dev/null +++ b/Help/variable/CMAKE_CODEBLOCKS_COMPILER_ID.rst @@ -0,0 +1,13 @@ +CMAKE_CODEBLOCKS_COMPILER_ID +---------------------------- + +Change the compiler id in the generated CodeBlocks project files. + +CodeBlocks uses its own compiler id string which differs from +:variable:`CMAKE_<LANG>_COMPILER_ID`. If this variable is left empty, +CMake tries to recognize the CodeBlocks compiler id automatically. +Otherwise the specified string is used in the CodeBlocks project file. +See the CodeBlocks documentation for valid compiler id strings. + +Other IDEs like QtCreator that also use the CodeBlocks generator may ignore +this setting. diff --git a/Help/variable/CMAKE_CROSSCOMPILING.rst b/Help/variable/CMAKE_CROSSCOMPILING.rst index cf9865b..9e96769 100644 --- a/Help/variable/CMAKE_CROSSCOMPILING.rst +++ b/Help/variable/CMAKE_CROSSCOMPILING.rst @@ -1,8 +1,26 @@ CMAKE_CROSSCOMPILING -------------------- -Is CMake currently cross compiling. +Intended to indicate whether CMake is cross compiling, but note limitations +discussed below. -This variable will be set to true by CMake if CMake is cross -compiling. Specifically if the build platform is different from the -target platform. +This variable will be set to true by CMake if the :variable:`CMAKE_SYSTEM_NAME` +variable has been set manually (i.e. in a toolchain file or as a cache entry +from the :manual:`cmake <cmake(1)>` command line). In most cases, manually +setting :variable:`CMAKE_SYSTEM_NAME` will only be done when cross compiling, +since it will otherwise be given the same value as +:variable:`CMAKE_HOST_SYSTEM_NAME` if not manually set, which is correct for +the non-cross-compiling case. In the event that :variable:`CMAKE_SYSTEM_NAME` +is manually set to the same value as :variable:`CMAKE_HOST_SYSTEM_NAME`, then +``CMAKE_CROSSCOMPILING`` will still be set to true. + +Another case to be aware of is that builds targeting Apple platforms other than +macOS are handled differently to other cross compiling scenarios. Rather than +relying on :variable:`CMAKE_SYSTEM_NAME` to select the target platform, Apple +device builds use :variable:`CMAKE_OSX_SYSROOT` to select the appropriate SDK, +which indirectly determines the target platform. Furthermore, when using the +Xcode generator, developers can switch between device and simulator builds at +build time rather than having a single choice at configure time, so the concept +of whether the build is cross compiling or not is more complex. Therefore, the +use of ``CMAKE_CROSSCOMPILING`` is not recommended for projects targeting Apple +devices. diff --git a/Help/variable/CMAKE_CUDA_SEPARABLE_COMPILATION.rst b/Help/variable/CMAKE_CUDA_SEPARABLE_COMPILATION.rst new file mode 100644 index 0000000..eef92fb --- /dev/null +++ b/Help/variable/CMAKE_CUDA_SEPARABLE_COMPILATION.rst @@ -0,0 +1,6 @@ +CMAKE_CUDA_SEPARABLE_COMPILATION +-------------------------------- + +Default value for :prop_tgt:`CUDA_SEPARABLE_COMPILATION` target property. +This variable is used to initialize the property on each target as it is +created. diff --git a/Help/variable/CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION.rst b/Help/variable/CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION.rst new file mode 100644 index 0000000..124fefe --- /dev/null +++ b/Help/variable/CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION.rst @@ -0,0 +1,16 @@ +CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION +------------------------------------- + +Default value for :prop_tgt:`DOTNET_TARGET_FRAMEWORK_VERSION` +property of targets. + +This variable is used to initialize the +:prop_tgt:`DOTNET_TARGET_FRAMEWORK_VERSION` property on all +targets. See that target property for additional information. + +Setting ``CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION`` may be necessary +when working with ``C#`` and newer .NET framework versions to +avoid referencing errors with the ``ALL_BUILD`` CMake target. + +This variable is only evaluated for :ref:`Visual Studio Generators` +VS 2010 and above. diff --git a/Help/variable/CMAKE_EXTRA_GENERATOR.rst b/Help/variable/CMAKE_EXTRA_GENERATOR.rst index 4d513e4..2c92323 100644 --- a/Help/variable/CMAKE_EXTRA_GENERATOR.rst +++ b/Help/variable/CMAKE_EXTRA_GENERATOR.rst @@ -4,7 +4,7 @@ CMAKE_EXTRA_GENERATOR The extra generator used to build the project. See :manual:`cmake-generators(7)`. -When using the Eclipse, CodeBlocks or KDevelop generators, CMake +When using the Eclipse, CodeBlocks, CodeLite, Kate or Sublime generators, CMake generates Makefiles (:variable:`CMAKE_GENERATOR`) and additionally project files for the respective IDE. This IDE project file generator is stored in ``CMAKE_EXTRA_GENERATOR`` (e.g. ``Eclipse CDT4``). diff --git a/Help/variable/CMAKE_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_GENERATOR_INSTANCE.rst b/Help/variable/CMAKE_GENERATOR_INSTANCE.rst new file mode 100644 index 0000000..78c81b1 --- /dev/null +++ b/Help/variable/CMAKE_GENERATOR_INSTANCE.rst @@ -0,0 +1,24 @@ +CMAKE_GENERATOR_INSTANCE +------------------------ + +Generator-specific instance specification provided by user. + +Some CMake generators support selection of an instance of the native build +system when multiple instances are available. If the user specifies an +instance (e.g. by setting this cache entry), or after a default instance is +chosen when a build tree is first configured, the value will be available in +this variable. + +The value of this variable should never be modified by project code. +A toolchain file specified by the :variable:`CMAKE_TOOLCHAIN_FILE` +variable may initialize ``CMAKE_GENERATOR_INSTANCE`` as a cache entry. +Once a given build tree has been initialized with a particular value +for this variable, changing the value has undefined behavior. + +Instance specification is supported only on specific generators: + +* For the :generator:`Visual Studio 15 2017` generator (and above) + this specifies the absolute path to the VS installation directory + of the selected VS instance. + +See native build system documentation for allowed instance values. diff --git a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst index 11c37d7..3220244 100644 --- a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst +++ b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst @@ -48,3 +48,8 @@ Supported pairs are: Supported by VS 2013 and above. See the :variable:`CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE` variable. + +``version=<version>`` + Specify the toolset version to use. Supported by VS 2017 + and above with the specified toolset installed. + See the :variable:`CMAKE_VS_PLATFORM_TOOLSET_VERSION` variable. diff --git a/Help/variable/CMAKE_HOST_SYSTEM.rst b/Help/variable/CMAKE_HOST_SYSTEM.rst index c2a8f1a..12d11d1 100644 --- a/Help/variable/CMAKE_HOST_SYSTEM.rst +++ b/Help/variable/CMAKE_HOST_SYSTEM.rst @@ -1,7 +1,7 @@ CMAKE_HOST_SYSTEM ----------------- -Composit Name of OS CMake is being run on. +Composite Name of OS CMake is being run on. This variable is the composite of :variable:`CMAKE_HOST_SYSTEM_NAME` and :variable:`CMAKE_HOST_SYSTEM_VERSION`, e.g. diff --git a/Help/variable/CMAKE_INCLUDE_CURRENT_DIR.rst b/Help/variable/CMAKE_INCLUDE_CURRENT_DIR.rst index 6eea322..98d99eb 100644 --- a/Help/variable/CMAKE_INCLUDE_CURRENT_DIR.rst +++ b/Help/variable/CMAKE_INCLUDE_CURRENT_DIR.rst @@ -1,7 +1,7 @@ CMAKE_INCLUDE_CURRENT_DIR ------------------------- -Automatically add the current source- and build directories to the include path. +Automatically add the current source and build directories to the include path. If this variable is enabled, CMake automatically adds :variable:`CMAKE_CURRENT_SOURCE_DIR` and :variable:`CMAKE_CURRENT_BINARY_DIR` diff --git a/Help/variable/CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE.rst b/Help/variable/CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE.rst index 5fc95f0..697682b 100644 --- a/Help/variable/CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE.rst +++ b/Help/variable/CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE.rst @@ -1,7 +1,7 @@ CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE -------------------------------------- -Automatically add the current source- and build directories to the +Automatically add the current source and build directories to the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property. If this variable is enabled, CMake automatically adds for each shared diff --git a/Help/variable/CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS.rst b/Help/variable/CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS.rst new file mode 100644 index 0000000..f994fbe --- /dev/null +++ b/Help/variable/CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS.rst @@ -0,0 +1,29 @@ +CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS +------------------------------------------- + +Default permissions for directories created implicitly during installation +of files by :command:`install` and :command:`file(INSTALL)`. + +If ``make install`` is invoked and directories are implicitly created they +get permissions set by :variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` +variable or platform specific default permissions if the variable is not set. + +Implicitly created directories are created if they are not explicitly installed +by :command:`install` command but are needed to install a file on a certain +path. Example of such locations are directories created due to the setting of +:variable:`CMAKE_INSTALL_PREFIX`. + +Expected content of the :variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` +variable is a list of permissions that can be used by :command:`install` command +`PERMISSIONS` section. + +Example usage: + +:: + + set(CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS + OWNER_READ + OWNER_WRITE + OWNER_EXECUTE + GROUP_READ + ) diff --git a/Help/variable/CMAKE_INSTALL_PREFIX.rst b/Help/variable/CMAKE_INSTALL_PREFIX.rst index 7bd87d6..02ba645 100644 --- a/Help/variable/CMAKE_INSTALL_PREFIX.rst +++ b/Help/variable/CMAKE_INSTALL_PREFIX.rst @@ -10,21 +10,7 @@ See :variable:`CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT` for how a project might choose its own default. On UNIX one can use the ``DESTDIR`` mechanism in order to relocate the -whole installation. ``DESTDIR`` means DESTination DIRectory. It is -commonly used by makefile users in order to install software at -non-default location. It is usually invoked like this: - -:: - - make DESTDIR=/home/john install - -which will install the concerned software using the installation -prefix, e.g. ``/usr/local`` prepended with the ``DESTDIR`` value which -finally gives ``/home/john/usr/local``. - -WARNING: ``DESTDIR`` may not be used on Windows because installation -prefix usually contains a drive letter like in ``C:/Program Files`` -which cannot be prepended with some other prefix. +whole installation. See :envvar:`DESTDIR` for more information. The installation prefix is also added to :variable:`CMAKE_SYSTEM_PREFIX_PATH` so that :command:`find_package`, :command:`find_program`, diff --git a/Help/variable/CMAKE_JOB_POOLS.rst b/Help/variable/CMAKE_JOB_POOLS.rst new file mode 100644 index 0000000..72b50b4 --- /dev/null +++ b/Help/variable/CMAKE_JOB_POOLS.rst @@ -0,0 +1,6 @@ +CMAKE_JOB_POOLS +--------------- + +If the :prop_gbl:`JOB_POOLS` global property is not set, the value +of this variable is used in its place. See :prop_gbl:`JOB_POOLS` +for additional information. diff --git a/Help/variable/CMAKE_LANG_CLANG_TIDY.rst b/Help/variable/CMAKE_LANG_CLANG_TIDY.rst index 492c12c..bd49de3 100644 --- a/Help/variable/CMAKE_LANG_CLANG_TIDY.rst +++ b/Help/variable/CMAKE_LANG_CLANG_TIDY.rst @@ -1,6 +1,13 @@ CMAKE_<LANG>_CLANG_TIDY ----------------------- -Default value for :prop_tgt:`<LANG>_CLANG_TIDY` target property. +Default value for :prop_tgt:`<LANG>_CLANG_TIDY` target property +when ``<LANG>`` is ``C`` or ``CXX``. + This variable is used to initialize the property on each target as it is -created. This is done only when ``<LANG>`` is ``C`` or ``CXX``. +created. For example: + +.. code-block:: cmake + + set(CMAKE_CXX_CLANG_TIDY clang-tidy -checks=-*,readability-*) + add_executable(foo foo.cxx) diff --git a/Help/variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN.rst b/Help/variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN.rst index 5be935b..cbe3544 100644 --- a/Help/variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN.rst +++ b/Help/variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN.rst @@ -6,7 +6,7 @@ The external toolchain for cross-compiling, if supported. Some compiler toolchains do not ship their own auxiliary utilities such as archivers and linkers. The compiler driver may support a command-line argument to specify the location of such tools. -``CMAKE_<LANG>_COMPILER_EXTERNAL_TOOLCHAIN`` may be set to a path to a path to +``CMAKE_<LANG>_COMPILER_EXTERNAL_TOOLCHAIN`` may be set to a path to the external toolchain and will be passed to the compiler driver if supported. This variable may only be set in a toolchain file specified by diff --git a/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst b/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst index f4e2ba5..e6c8bb5 100644 --- a/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst +++ b/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst @@ -3,4 +3,5 @@ CMAKE_<LANG>_COMPILER_LAUNCHER Default value for :prop_tgt:`<LANG>_COMPILER_LAUNCHER` target property. This variable is used to initialize the property on each target as it is -created. This is done only when ``<LANG>`` is ``C``, ``CXX``, or ``CUDA``. +created. This is done only when ``<LANG>`` is ``C``, ``CXX``, ``Fortran``, +or ``CUDA``. diff --git a/Help/variable/CMAKE_LANG_FLAGS.rst b/Help/variable/CMAKE_LANG_FLAGS.rst index c57d92c..14b2694 100644 --- a/Help/variable/CMAKE_LANG_FLAGS.rst +++ b/Help/variable/CMAKE_LANG_FLAGS.rst @@ -4,3 +4,14 @@ CMAKE_<LANG>_FLAGS Flags for all build types. ``<LANG>`` flags used regardless of the value of :variable:`CMAKE_BUILD_TYPE`. + +This is initialized for each language from environment variables: + +* ``CMAKE_C_FLAGS``: + Initialized by the :envvar:`CFLAGS` environment variable. +* ``CMAKE_CXX_FLAGS``: + Initialized by the :envvar:`CXXFLAGS` environment variable. +* ``CMAKE_CUDA_FLAGS``: + Initialized by the :envvar:`CUDAFLAGS` environment variable. +* ``CMAKE_Fortran_FLAGS``: + Initialized by the :envvar:`FFLAGS` environment variable. diff --git a/Help/variable/CMAKE_LANG_FLAGS_CONFIG.rst b/Help/variable/CMAKE_LANG_FLAGS_CONFIG.rst new file mode 100644 index 0000000..1dbd036 --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_CONFIG.rst @@ -0,0 +1,4 @@ +CMAKE_<LANG>_FLAGS_<CONFIG> +--------------------------- + +Flags for language ``<LANG>`` when building for the ``<CONFIG>`` configuration. diff --git a/Help/variable/CMAKE_LANG_FLAGS_CONFIG_INIT.rst b/Help/variable/CMAKE_LANG_FLAGS_CONFIG_INIT.rst new file mode 100644 index 0000000..1eb5b3f --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_CONFIG_INIT.rst @@ -0,0 +1,10 @@ +CMAKE_<LANG>_FLAGS_<CONFIG>_INIT +-------------------------------- + +Value used to initialize the :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` cache +entry the first time a build tree is configured for language ``<LANG>``. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also :variable:`CMAKE_<LANG>_FLAGS_INIT`. diff --git a/Help/variable/CMAKE_LANG_FLAGS_DEBUG.rst b/Help/variable/CMAKE_LANG_FLAGS_DEBUG.rst index a233d4a..6be424a 100644 --- a/Help/variable/CMAKE_LANG_FLAGS_DEBUG.rst +++ b/Help/variable/CMAKE_LANG_FLAGS_DEBUG.rst @@ -1,6 +1,5 @@ CMAKE_<LANG>_FLAGS_DEBUG ------------------------ -Flags for ``Debug`` build type or configuration. - -``<LANG>`` flags used when :variable:`CMAKE_BUILD_TYPE` is ``Debug``. +This variable is the ``Debug`` variant of the +:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` variable. diff --git a/Help/variable/CMAKE_LANG_FLAGS_DEBUG_INIT.rst b/Help/variable/CMAKE_LANG_FLAGS_DEBUG_INIT.rst index dcddb2e..de7fcfc 100644 --- a/Help/variable/CMAKE_LANG_FLAGS_DEBUG_INIT.rst +++ b/Help/variable/CMAKE_LANG_FLAGS_DEBUG_INIT.rst @@ -1,10 +1,5 @@ CMAKE_<LANG>_FLAGS_DEBUG_INIT ----------------------------- -Value used to initialize the :variable:`CMAKE_<LANG>_FLAGS_DEBUG` cache -entry the first time a build tree is configured for language ``<LANG>``. -This variable is meant to be set by a :variable:`toolchain file -<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to -the value based on the environment and target platform. - -See also :variable:`CMAKE_<LANG>_FLAGS_INIT`. +This variable is the ``Debug`` variant of the +:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>_INIT` variable. diff --git a/Help/variable/CMAKE_LANG_FLAGS_INIT.rst b/Help/variable/CMAKE_LANG_FLAGS_INIT.rst index 1d32cc3..a88d122 100644 --- a/Help/variable/CMAKE_LANG_FLAGS_INIT.rst +++ b/Help/variable/CMAKE_LANG_FLAGS_INIT.rst @@ -7,9 +7,5 @@ This variable is meant to be set by a :variable:`toolchain file <CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to the value based on the environment and target platform. -See also the configuration-specific variables: - -* :variable:`CMAKE_<LANG>_FLAGS_DEBUG_INIT` -* :variable:`CMAKE_<LANG>_FLAGS_RELEASE_INIT` -* :variable:`CMAKE_<LANG>_FLAGS_MINSIZEREL_INIT` -* :variable:`CMAKE_<LANG>_FLAGS_RELWITHDEBINFO_INIT` +See also the configuration-specific +:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>_INIT` variable. diff --git a/Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL.rst b/Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL.rst index a9436c1..634fab9 100644 --- a/Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL.rst +++ b/Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL.rst @@ -1,7 +1,5 @@ CMAKE_<LANG>_FLAGS_MINSIZEREL ----------------------------- -Flags for ``MinSizeRel`` build type or configuration. - -``<LANG>`` flags used when :variable:`CMAKE_BUILD_TYPE` is ``MinSizeRel`` -(short for minimum size release). +This variable is the ``MinSizeRel`` variant of the +:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` variable. diff --git a/Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL_INIT.rst b/Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL_INIT.rst index c0aedf4..1e7003c 100644 --- a/Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL_INIT.rst +++ b/Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL_INIT.rst @@ -1,10 +1,5 @@ CMAKE_<LANG>_FLAGS_MINSIZEREL_INIT ---------------------------------- -Value used to initialize the :variable:`CMAKE_<LANG>_FLAGS_MINSIZEREL` -cache entry the first time a build tree is configured for language ``<LANG>``. -This variable is meant to be set by a :variable:`toolchain file -<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to -the value based on the environment and target platform. - -See also :variable:`CMAKE_<LANG>_FLAGS_INIT`. +This variable is the ``MinSizeRel`` variant of the +:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>_INIT` variable. diff --git a/Help/variable/CMAKE_LANG_FLAGS_RELEASE.rst b/Help/variable/CMAKE_LANG_FLAGS_RELEASE.rst index ffc5d79..3baeab0 100644 --- a/Help/variable/CMAKE_LANG_FLAGS_RELEASE.rst +++ b/Help/variable/CMAKE_LANG_FLAGS_RELEASE.rst @@ -1,6 +1,5 @@ CMAKE_<LANG>_FLAGS_RELEASE -------------------------- -Flags for ``Release`` build type or configuration. - -``<LANG>`` flags used when :variable:`CMAKE_BUILD_TYPE` is ``Release``. +This variable is the ``Release`` variant of the +:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` variable. diff --git a/Help/variable/CMAKE_LANG_FLAGS_RELEASE_INIT.rst b/Help/variable/CMAKE_LANG_FLAGS_RELEASE_INIT.rst index 59f92ff..e7c73fe 100644 --- a/Help/variable/CMAKE_LANG_FLAGS_RELEASE_INIT.rst +++ b/Help/variable/CMAKE_LANG_FLAGS_RELEASE_INIT.rst @@ -1,10 +1,5 @@ CMAKE_<LANG>_FLAGS_RELEASE_INIT ------------------------------- -Value used to initialize the :variable:`CMAKE_<LANG>_FLAGS_RELEASE` -cache entry the first time a build tree is configured for language ``<LANG>``. -This variable is meant to be set by a :variable:`toolchain file -<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to -the value based on the environment and target platform. - -See also :variable:`CMAKE_<LANG>_FLAGS_INIT`. +This variable is the ``Release`` variant of the +:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>_INIT` variable. diff --git a/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO.rst b/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO.rst index 962768e..67a5073 100644 --- a/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO.rst +++ b/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO.rst @@ -1,7 +1,5 @@ CMAKE_<LANG>_FLAGS_RELWITHDEBINFO --------------------------------- -Flags for ``RelWithDebInfo`` type or configuration. - -``<LANG>`` flags used when :variable:`CMAKE_BUILD_TYPE` is ``RelWithDebInfo`` -(short for Release With Debug Information). +This variable is the ``RelWithDebInfo`` variant of the +:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` variable. diff --git a/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT.rst b/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT.rst index 915f023..3ab3975 100644 --- a/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT.rst +++ b/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT.rst @@ -1,10 +1,5 @@ CMAKE_<LANG>_FLAGS_RELWITHDEBINFO_INIT -------------------------------------- -Value used to initialize the :variable:`CMAKE_<LANG>_FLAGS_RELWITHDEBINFO` -cache entry the first time a build tree is configured for language ``<LANG>``. -This variable is meant to be set by a :variable:`toolchain file -<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to -the value based on the environment and target platform. - -See also :variable:`CMAKE_<LANG>_FLAGS_INIT`. +This variable is the ``RelWithDebInfo`` variant of the +:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>_INIT` variable. diff --git a/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_CONFIG.rst b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_CONFIG.rst new file mode 100644 index 0000000..8ed1c02 --- /dev/null +++ b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_CONFIG.rst @@ -0,0 +1,5 @@ +CMAKE_<LANG>_GHS_KERNEL_FLAGS_<CONFIG> +-------------------------------------- + +GHS kernel flags for language ``<LANG>`` when building for the ``<CONFIG>`` +configuration. diff --git a/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_DEBUG.rst b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_DEBUG.rst index 1f639a3..4fea67a 100644 --- a/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_DEBUG.rst +++ b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_DEBUG.rst @@ -1,6 +1,5 @@ CMAKE_<LANG>_GHS_KERNEL_FLAGS_DEBUG ----------------------------------- -GHS kernel flags for ``Debug`` build type or configuration. - -``<LANG>`` flags used when :variable:`CMAKE_BUILD_TYPE` is ``Debug``. +This variable is the ``Debug`` variant of the +:variable:`CMAKE_<LANG>_GHS_KERNEL_FLAGS_<CONFIG>` variable. diff --git a/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_MINSIZEREL.rst b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_MINSIZEREL.rst index 94e2115..31f87f2 100644 --- a/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_MINSIZEREL.rst +++ b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_MINSIZEREL.rst @@ -1,7 +1,5 @@ CMAKE_<LANG>_GHS_KERNEL_FLAGS_MINSIZEREL ---------------------------------------- -GHS kernel flags for ``MinSizeRel`` build type or configuration. - -``<LANG>`` flags used when :variable:`CMAKE_BUILD_TYPE` is ``MinSizeRel`` -(short for minimum size release). +This variable is the ``MinSizeRel`` variant of the +:variable:`CMAKE_<LANG>_GHS_KERNEL_FLAGS_<CONFIG>` variable. diff --git a/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELEASE.rst b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELEASE.rst index 74566ef..1acd198 100644 --- a/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELEASE.rst +++ b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELEASE.rst @@ -1,6 +1,5 @@ CMAKE_<LANG>_GHS_KERNEL_FLAGS_RELEASE ------------------------------------- -GHS kernel flags for ``Release`` build type or configuration. - -``<LANG>`` flags used when :variable:`CMAKE_BUILD_TYPE` is ``Release``. +This variable is the ``Release`` variant of the +:variable:`CMAKE_<LANG>_GHS_KERNEL_FLAGS_<CONFIG>` variable. diff --git a/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELWITHDEBINFO.rst b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELWITHDEBINFO.rst index d148193..ac1b6bc 100644 --- a/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELWITHDEBINFO.rst +++ b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELWITHDEBINFO.rst @@ -1,7 +1,5 @@ CMAKE_<LANG>_GHS_KERNEL_FLAGS_RELWITHDEBINFO -------------------------------------------- -GHS kernel flags for ``RelWithDebInfo`` type or configuration. - -``<LANG>`` flags used when :variable:`CMAKE_BUILD_TYPE` is ``RelWithDebInfo`` -(short for Release With Debug Information). +This variable is the ``RelWithDebInfo`` variant of the +:variable:`CMAKE_<LANG>_GHS_KERNEL_FLAGS_<CONFIG>` variable. diff --git a/Help/variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES.rst b/Help/variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES.rst index a0bd830..e9e04be 100644 --- a/Help/variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES.rst +++ b/Help/variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES.rst @@ -9,9 +9,12 @@ These paths are implicit linker search directories for the compiler's language. CMake automatically detects these directories for each language and reports the results in this variable. -When a library in one of these directories is given by full path to -:command:`target_link_libraries` CMake will generate the ``-l<name>`` form on -link lines to ensure the linker searches its implicit directories for the -library. Note that some toolchains read implicit directories from an -environment variable such as ``LIBRARY_PATH`` so keep its value consistent -when operating in a given build tree. +Some toolchains read implicit directories from an environment variable such as +``LIBRARY_PATH``. If using such an environment variable, keep its value +consistent when operating in a given build tree because CMake saves the value +detected when first creating a build tree. + +If policy :policy:`CMP0060` is not set to ``NEW``, then when a library in one +of these directories is given by full path to :command:`target_link_libraries` +CMake will generate the ``-l<name>`` form on link lines for historical +purposes. 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_MODULE_PATH.rst b/Help/variable/CMAKE_MODULE_PATH.rst index 5ea7cbb..6490054 100644 --- a/Help/variable/CMAKE_MODULE_PATH.rst +++ b/Help/variable/CMAKE_MODULE_PATH.rst @@ -2,6 +2,6 @@ CMAKE_MODULE_PATH ----------------- :ref:`;-list <CMake Language Lists>` of directories specifying a search path -for CMake modules to be loaded by the the :command:`include` or +for CMake modules to be loaded by the :command:`include` or :command:`find_package` commands before checking the default modules that come with CMake. By default it is empty, it is intended to be set by the project. diff --git a/Help/variable/CMAKE_NETRC.rst b/Help/variable/CMAKE_NETRC.rst new file mode 100644 index 0000000..903ec31 --- /dev/null +++ b/Help/variable/CMAKE_NETRC.rst @@ -0,0 +1,9 @@ +CMAKE_NETRC +----------- + +This variable is used to initialize the ``NETRC`` option for +:command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands and the +module :module:`ExternalProject`. See those commands for additional +information. + +The local option takes precedence over this variable. diff --git a/Help/variable/CMAKE_NETRC_FILE.rst b/Help/variable/CMAKE_NETRC_FILE.rst new file mode 100644 index 0000000..0f09afe --- /dev/null +++ b/Help/variable/CMAKE_NETRC_FILE.rst @@ -0,0 +1,9 @@ +CMAKE_NETRC_FILE +---------------- + +This variable is used to initialize the ``NETRC_FILE`` option for +:command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands and the +module :module:`ExternalProject`. See those commands for additional +information. + +The local option takes precedence over this variable. diff --git a/Help/variable/CMAKE_OSX_ARCHITECTURES.rst b/Help/variable/CMAKE_OSX_ARCHITECTURES.rst index 93916dd..51b840d 100644 --- a/Help/variable/CMAKE_OSX_ARCHITECTURES.rst +++ b/Help/variable/CMAKE_OSX_ARCHITECTURES.rst @@ -4,7 +4,7 @@ CMAKE_OSX_ARCHITECTURES Target specific architectures for OS X and iOS. This variable is used to initialize the :prop_tgt:`OSX_ARCHITECTURES` -property on each target as it is creaed. See that target property +property on each target as it is created. See that target property for additional information. .. include:: CMAKE_OSX_VARIABLE.txt diff --git a/Help/variable/CMAKE_OSX_DEPLOYMENT_TARGET.rst b/Help/variable/CMAKE_OSX_DEPLOYMENT_TARGET.rst index 4fb2caa..9df5edd 100644 --- a/Help/variable/CMAKE_OSX_DEPLOYMENT_TARGET.rst +++ b/Help/variable/CMAKE_OSX_DEPLOYMENT_TARGET.rst @@ -1,10 +1,12 @@ CMAKE_OSX_DEPLOYMENT_TARGET --------------------------- -Specify the minimum version of OS X on which the target binaries are -to be deployed. CMake uses this value for the ``-mmacosx-version-min`` -flag and to help choose the default SDK -(see :variable:`CMAKE_OSX_SYSROOT`). +Specify the minimum version of the target platform (e.g. macOS or iOS) +on which the target binaries are to be deployed. CMake uses this +variable value for the ``-mmacosx-version-min`` flag or their respective +target platform equivalents. For older Xcode versions that shipped +multiple macOS SDKs this variable also helps to choose the SDK in case +:variable:`CMAKE_OSX_SYSROOT` is unset. If not set explicitly the value is initialized by the ``MACOSX_DEPLOYMENT_TARGET`` environment variable, if set, diff --git a/Help/variable/CMAKE_OSX_VARIABLE.txt b/Help/variable/CMAKE_OSX_VARIABLE.txt index 385f871..5b84726 100644 --- a/Help/variable/CMAKE_OSX_VARIABLE.txt +++ b/Help/variable/CMAKE_OSX_VARIABLE.txt @@ -3,4 +3,7 @@ The value of this variable should be set prior to the first because it may influence configuration of the toolchain and flags. It is intended to be set locally by the user creating a build tree. -This variable is ignored on platforms other than OS X. +Despite the ``OSX`` part in the variable name(s) they apply also to +other SDKs than macOS like iOS, tvOS, or watchOS. + +This variable is ignored on platforms other than Apple. 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_PROJECT_PROJECT-NAME_INCLUDE.rst b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst index ba9df5a..5ca40a3 100644 --- a/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst +++ b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst @@ -2,5 +2,5 @@ CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE ------------------------------------ A CMake language file or module to be included by the :command:`project` -command. This is is intended for injecting custom code into project +command. This is intended for injecting custom code into project builds without modifying their source. diff --git a/Help/variable/CMAKE_PROJECT_VERSION.rst b/Help/variable/CMAKE_PROJECT_VERSION.rst new file mode 100644 index 0000000..4f8f556 --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_VERSION.rst @@ -0,0 +1,35 @@ +CMAKE_PROJECT_VERSION +--------------------- + +The version of the top level project. + +This variable holds the version 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_VERSION`` contains. For example, consider +the following top level CMakeLists.txt: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.0) + project(First VERSION 1.2.3) + project(Second VERSION 3.4.5) + add_subdirectory(sub) + project(Third VERSION 6.7.8) + +And ``sub/CMakeLists.txt`` with the following contents: + +.. code-block:: cmake + + project(SubProj VERSION 1) + message("CMAKE_PROJECT_VERSION = ${CMAKE_PROJECT_VERSION}") + +The most recently seen :command:`project` command from the top level +CMakeLists.txt would be ``project(Second ...)``, so this will print:: + + CMAKE_PROJECT_VERSION = 3.4.5 + +To obtain the version from the most recent call to :command:`project` in +the current directory scope or above, see the :variable:`PROJECT_VERSION` +variable. diff --git a/Help/variable/CMAKE_PROJECT_VERSION_MAJOR.rst b/Help/variable/CMAKE_PROJECT_VERSION_MAJOR.rst new file mode 100644 index 0000000..f1001ac --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_VERSION_MAJOR.rst @@ -0,0 +1,9 @@ +CMAKE_PROJECT_VERSION_MAJOR +--------------------------- + +The major version of the top level project. + +This variable holds the major version of the project as specified in the top +level CMakeLists.txt file by a :command:`project` command. Please see +:variable:`CMAKE_PROJECT_VERSION` documentation for the behavior when +multiple :command:`project` commands are used in the sources. diff --git a/Help/variable/CMAKE_PROJECT_VERSION_MINOR.rst b/Help/variable/CMAKE_PROJECT_VERSION_MINOR.rst new file mode 100644 index 0000000..13202be --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_VERSION_MINOR.rst @@ -0,0 +1,9 @@ +CMAKE_PROJECT_VERSION_MINOR +--------------------------- + +The minor version of the top level project. + +This variable holds the minor version of the project as specified in the top +level CMakeLists.txt file by a :command:`project` command. Please see +:variable:`CMAKE_PROJECT_VERSION` documentation for the behavior when +multiple :command:`project` commands are used in the sources. diff --git a/Help/variable/CMAKE_PROJECT_VERSION_PATCH.rst b/Help/variable/CMAKE_PROJECT_VERSION_PATCH.rst new file mode 100644 index 0000000..b8570d9 --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_VERSION_PATCH.rst @@ -0,0 +1,9 @@ +CMAKE_PROJECT_VERSION_PATCH +--------------------------- + +The patch version of the top level project. + +This variable holds the patch version of the project as specified in the top +level CMakeLists.txt file by a :command:`project` command. Please see +:variable:`CMAKE_PROJECT_VERSION` documentation for the behavior when +multiple :command:`project` commands are used in the sources. diff --git a/Help/variable/CMAKE_PROJECT_VERSION_TWEAK.rst b/Help/variable/CMAKE_PROJECT_VERSION_TWEAK.rst new file mode 100644 index 0000000..e1ad4be --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_VERSION_TWEAK.rst @@ -0,0 +1,9 @@ +CMAKE_PROJECT_VERSION_TWEAK +--------------------------- + +The tweak version of the top level project. + +This variable holds the tweak version of the project as specified in the top +level CMakeLists.txt file by a :command:`project` command. Please see +:variable:`CMAKE_PROJECT_VERSION` documentation for the behavior when +multiple :command:`project` commands are used in the sources. 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_SYSTEM_NAME.rst b/Help/variable/CMAKE_SYSTEM_NAME.rst index c3a42e5..fef53ee 100644 --- a/Help/variable/CMAKE_SYSTEM_NAME.rst +++ b/Help/variable/CMAKE_SYSTEM_NAME.rst @@ -4,6 +4,9 @@ CMAKE_SYSTEM_NAME The name of the operating system for which CMake is to build. See the :variable:`CMAKE_SYSTEM_VERSION` variable for the OS version. +Note that ``CMAKE_SYSTEM_NAME`` is not set to anything by default when running +in script mode, since it's not building anything. + System Name for Host Builds ^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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/CMAKE_VS_PLATFORM_TOOLSET_VERSION.rst b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_VERSION.rst new file mode 100644 index 0000000..4d9b978 --- /dev/null +++ b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_VERSION.rst @@ -0,0 +1,11 @@ +CMAKE_VS_PLATFORM_TOOLSET_VERSION +--------------------------------- + +Visual Studio Platform Toolset version. + +The :ref:`Visual Studio Generators` for VS 2017 and above allow to +select minor versions of the same toolset. The toolset version number +may be specified by a field in :variable:`CMAKE_GENERATOR_TOOLSET` of +the form ``version=14.11``. If none is specified CMake will choose a default +toolset. The value may be empty if no minor version was selected and the +default is used. diff --git a/Help/variable/CMAKE_VS_SDK_EXCLUDE_DIRECTORIES.rst b/Help/variable/CMAKE_VS_SDK_EXCLUDE_DIRECTORIES.rst new file mode 100644 index 0000000..36c4dcc --- /dev/null +++ b/Help/variable/CMAKE_VS_SDK_EXCLUDE_DIRECTORIES.rst @@ -0,0 +1,4 @@ +CMAKE_VS_SDK_EXCLUDE_DIRECTORIES +-------------------------------- + +This variable allows to override Visual Studio default Exclude Directories. diff --git a/Help/variable/CMAKE_VS_SDK_EXECUTABLE_DIRECTORIES.rst b/Help/variable/CMAKE_VS_SDK_EXECUTABLE_DIRECTORIES.rst new file mode 100644 index 0000000..3ec755b --- /dev/null +++ b/Help/variable/CMAKE_VS_SDK_EXECUTABLE_DIRECTORIES.rst @@ -0,0 +1,4 @@ +CMAKE_VS_SDK_EXECUTABLE_DIRECTORIES +----------------------------------- + +This variable allows to override Visual Studio default Executable Directories. diff --git a/Help/variable/CMAKE_VS_SDK_INCLUDE_DIRECTORIES.rst b/Help/variable/CMAKE_VS_SDK_INCLUDE_DIRECTORIES.rst new file mode 100644 index 0000000..da10bde --- /dev/null +++ b/Help/variable/CMAKE_VS_SDK_INCLUDE_DIRECTORIES.rst @@ -0,0 +1,4 @@ +CMAKE_VS_SDK_INCLUDE_DIRECTORIES +-------------------------------- + +This variable allows to override Visual Studio default Include Directories. diff --git a/Help/variable/CMAKE_VS_SDK_LIBRARY_DIRECTORIES.rst b/Help/variable/CMAKE_VS_SDK_LIBRARY_DIRECTORIES.rst new file mode 100644 index 0000000..b33754a --- /dev/null +++ b/Help/variable/CMAKE_VS_SDK_LIBRARY_DIRECTORIES.rst @@ -0,0 +1,4 @@ +CMAKE_VS_SDK_LIBRARY_DIRECTORIES +-------------------------------- + +This variable allows to override Visual Studio default Library Directories. diff --git a/Help/variable/CMAKE_VS_SDK_LIBRARY_WINRT_DIRECTORIES.rst b/Help/variable/CMAKE_VS_SDK_LIBRARY_WINRT_DIRECTORIES.rst new file mode 100644 index 0000000..b022215 --- /dev/null +++ b/Help/variable/CMAKE_VS_SDK_LIBRARY_WINRT_DIRECTORIES.rst @@ -0,0 +1,5 @@ +CMAKE_VS_SDK_LIBRARY_WINRT_DIRECTORIES +-------------------------------------- + +This variable allows to override Visual Studio default Library WinRT +Directories. diff --git a/Help/variable/CMAKE_VS_SDK_REFERENCE_DIRECTORIES.rst b/Help/variable/CMAKE_VS_SDK_REFERENCE_DIRECTORIES.rst new file mode 100644 index 0000000..c03f0ae --- /dev/null +++ b/Help/variable/CMAKE_VS_SDK_REFERENCE_DIRECTORIES.rst @@ -0,0 +1,4 @@ +CMAKE_VS_SDK_REFERENCE_DIRECTORIES +---------------------------------- + +This variable allows to override Visual Studio default Reference Directories. diff --git a/Help/variable/CMAKE_VS_SDK_SOURCE_DIRECTORIES.rst b/Help/variable/CMAKE_VS_SDK_SOURCE_DIRECTORIES.rst new file mode 100644 index 0000000..0c73f06 --- /dev/null +++ b/Help/variable/CMAKE_VS_SDK_SOURCE_DIRECTORIES.rst @@ -0,0 +1,4 @@ +CMAKE_VS_SDK_SOURCE_DIRECTORIES +------------------------------- + +This variable allows to override Visual Studio default Source Directories. diff --git a/Help/variable/CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY.rst b/Help/variable/CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY.rst new file mode 100644 index 0000000..ea3e240 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY.rst @@ -0,0 +1,9 @@ +CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY +------------------------------------------- + +If enabled, the :generator:`Xcode` generator will generate only a +single Xcode project file for the topmost :command:`project()` command +instead of generating one for every ``project()`` command. + +This could be useful to speed up the CMake generation step for +large projects and to work-around a bug in the ``ZERO_CHECK`` logic. diff --git a/Help/variable/CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS.rst b/Help/variable/CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS.rst new file mode 100644 index 0000000..83d5ce7 --- /dev/null +++ b/Help/variable/CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS.rst @@ -0,0 +1,11 @@ +CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS +------------------------------------------- + +Default permissions for implicitly created directories during packaging. + +This variable serves the same purpose during packaging as the +:variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` variable +serves during installation (e.g. ``make install``). + +If `include(CPack)` is used then by default this variable is set to the content +of :variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS`. diff --git a/Help/variable/CTEST_RUN_CURRENT_SCRIPT.rst b/Help/variable/CTEST_RUN_CURRENT_SCRIPT.rst new file mode 100644 index 0000000..abc123c --- /dev/null +++ b/Help/variable/CTEST_RUN_CURRENT_SCRIPT.rst @@ -0,0 +1,5 @@ +CTEST_RUN_CURRENT_SCRIPT +------------------------ + +Setting this to 0 prevents :manual:`ctest(1)` from being run again when it +reaches the end of a script run by calling ``ctest -S``. diff --git a/Help/variable/LIBRARY_OUTPUT_PATH.rst b/Help/variable/LIBRARY_OUTPUT_PATH.rst index ba02911..bb4328f 100644 --- a/Help/variable/LIBRARY_OUTPUT_PATH.rst +++ b/Help/variable/LIBRARY_OUTPUT_PATH.rst @@ -5,5 +5,5 @@ Old library location variable. The target properties :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY`, :prop_tgt:`LIBRARY_OUTPUT_DIRECTORY`, and :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` -supercede this variable for a target if they are set. Library targets are +supersede this variable for a target if they are set. Library targets are otherwise placed in this directory. diff --git a/Help/variable/MSVC.rst b/Help/variable/MSVC.rst index 22a087a..ca8775c 100644 --- a/Help/variable/MSVC.rst +++ b/Help/variable/MSVC.rst @@ -1,8 +1,8 @@ MSVC ---- -``True`` when using Microsoft Visual C++. - -Set to ``true`` when the compiler is some version of Microsoft Visual C++. +Set to ``true`` when the compiler is some version of Microsoft Visual +C++ or another compiler simulating Visual C++. Any compiler defining +``_MSC_VER`` is considered simulating Visual C++. See also the :variable:`MSVC_VERSION` variable. 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 0a3a7a6..4ef43d8 100644 --- a/Help/variable/MSVC_VERSION.rst +++ b/Help/variable/MSVC_VERSION.rst @@ -2,6 +2,9 @@ MSVC_VERSION ------------ The version of Microsoft Visual C/C++ being used if any. +If a compiler simulating Visual C++ is being used, this variable is set +to the toolset version simulated as given by the ``_MSC_VER`` +preprocessor definition. Known version numbers are:: @@ -16,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. diff --git a/Help/variable/PackageName_ROOT.rst b/Help/variable/PackageName_ROOT.rst new file mode 100644 index 0000000..4f6c25b --- /dev/null +++ b/Help/variable/PackageName_ROOT.rst @@ -0,0 +1,14 @@ +<PackageName>_ROOT +------------------ + +Calls to :command:`find_package(<PackageName>)` will search in prefixes +specified by the ``<PackageName>_ROOT`` CMake variable, where +``<PackageName>`` is the name given to the ``find_package`` call +and ``_ROOT`` is literal. For example, ``find_package(Foo)`` will search +prefixes specified in the ``Foo_ROOT`` CMake variable (if set). +See policy :policy:`CMP0074`. + +This variable may hold a single prefix or a +:ref:`;-list <CMake Language Lists>` of multiple prefixes. + +See also the :envvar:`<PackageName>_ROOT` environment variable. |