diff options
Diffstat (limited to 'Help')
75 files changed, 763 insertions, 180 deletions
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..3706153 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 @@ -110,9 +111,9 @@ 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>``. +cannot be linked. Some native build systems (such as Xcode) may not like +targets that have only object files, so consider adding at least one real +source file to any target that references ``$<TARGET_OBJECTS:objlib>``. Alias Libraries ^^^^^^^^^^^^^^^ @@ -124,7 +125,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/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/file.rst b/Help/command/file.rst index edccac5..5ce86e5 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -110,7 +110,7 @@ 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 +By default ``GLOB`` lists directories - directories are omitted in result if ``LIST_DIRECTORIES`` is set to false. .. note:: @@ -232,6 +232,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>`` diff --git a/Help/command/install.rst b/Help/command/install.rst index 58438b7..9f9ee13 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -346,7 +346,7 @@ specified that does not match that given to the targets associated with included in the export but a target to which it links is not included the behavior is unspecified. -In additon to cmake language files, the ``EXPORT_ANDROID_MK`` option maybe +In addition to cmake language files, the ``EXPORT_ANDROID_MK`` option maybe used to specifiy an export to the android ndk build system. 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 diff --git a/Help/command/project.rst b/Help/command/project.rst index 139f69c..eb185e4 100644 --- a/Help/command/project.rst +++ b/Help/command/project.rst @@ -46,11 +46,15 @@ variable will be set to its argument. The argument must be a string with short description of the project (only a few words). 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. diff --git a/Help/command/target_compile_definitions.rst b/Help/command/target_compile_definitions.rst index 8bd3233..3709e7a 100644 --- a/Help/command/target_compile_definitions.rst +++ b/Help/command/target_compile_definitions.rst @@ -12,14 +12,15 @@ 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" 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..3e7dc47 100644 --- a/Help/command/target_compile_options.rst +++ b/Help/command/target_compile_options.rst @@ -12,8 +12,10 @@ 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 @@ -27,8 +29,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:`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" 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..2ec8744 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: 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/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/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/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index bddb174..dc5621a 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -97,7 +97,7 @@ 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 + otherwise ``0``. This expression may be 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): @@ -109,10 +109,12 @@ Available logical expressions are: PRIVATE $<$<COMPILE_LANGUAGE:CXX>:-fno-exceptions> ) - 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: + Note that with :ref:`Visual Studio Generators` there is no way to represent + target-wide flags separately for ``C`` and ``CXX`` languages. Under these + generators, target-wide flags 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 diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index 8f4b252..694bae5 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -80,6 +80,7 @@ All Modules /module/ExternalData /module/ExternalProject /module/FeatureSummary + /module/FetchContent /module/FindALSA /module/FindArmadillo /module/FindASPELL @@ -129,6 +130,7 @@ All Modules /module/FindIcotool /module/FindICU /module/FindImageMagick + /module/FindIconv /module/FindIntl /module/FindITK /module/FindJasper diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index c81ba59..96d5c7d 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -51,6 +51,14 @@ 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.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..2c63c4b 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -184,6 +184,7 @@ Properties on Targets /prop_tgt/HAS_CXX /prop_tgt/IMPLICIT_DEPENDS_INCLUDE_TRANSFORM /prop_tgt/IMPORTED_CONFIGURATIONS + /prop_tgt/IMPORTED_GLOBAL /prop_tgt/IMPORTED_IMPLIB_CONFIG /prop_tgt/IMPORTED_IMPLIB /prop_tgt/IMPORTED_LIBNAME_CONFIG @@ -390,6 +391,8 @@ 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 diff --git a/Help/manual/cmake-server.7.rst b/Help/manual/cmake-server.7.rst index 50a90ee..28171c6 100644 --- a/Help/manual/cmake-server.7.rst +++ b/Help/manual/cmake-server.7.rst @@ -458,6 +458,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 +486,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 +593,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..735b93b 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -42,6 +42,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 +50,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,6 +62,8 @@ 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 @@ -121,6 +125,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 +161,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 @@ -185,6 +191,7 @@ 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 Variables that Describe the System ================================== @@ -285,6 +292,7 @@ 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 @@ -525,6 +533,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..ff8c6c7 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -11,6 +11,7 @@ Synopsis cmake [<options>] (<path-to-source> | <path-to-existing-build>) cmake [(-D <var>=<value>)...] -P <cmake-script-file> cmake --build <dir> [<options>...] [-- <build-tool-options>...] + cmake --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. diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index 423f1ca..d9af3bc 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,111 @@ 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 +============================ - 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``. +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 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. The time is +reported with `sec*proc` instead of just `sec`. + +.. _`Build and Test Mode`: + +Build and Test Mode +=================== + +CTest provides a command-line signature to to configure (i.e. run cmake on), +build, and or execute a test:: + + ctest --build-and-test <path-to-source> <path-to-build> + --build-generator <generator> [<options>...] [-- <build-options>...] + [--test-command <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 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. @@ -324,67 +405,47 @@ Options ``--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. - ``--test-timeout`` - The time limit in seconds, internal use only. - -``--tomorrow-tag`` - Nightly or experimental starts with next day tag. + The time limit in seconds - This is useful if the build will not finish in one day. - -``--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 +460,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 +772,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 +813,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 +845,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 +890,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 +1126,5 @@ See Also ======== .. include:: LINKS.txt + +.. _`CDash`: http://cdash.org/ 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/policy/CMP0037.rst b/Help/policy/CMP0037.rst index 9f8457c..8041960 100644 --- a/Help/policy/CMP0037.rst +++ b/Help/policy/CMP0037.rst @@ -14,7 +14,12 @@ character (_), dot(.), plus(+) and minus(-). As a special case, ALIAS targets and IMPORTED targets may contain two consequtive 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/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/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_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/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/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/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/dev/0-sample-topic.rst b/Help/release/dev/0-sample-topic.rst new file mode 100644 index 0000000..e4cc01e --- /dev/null +++ b/Help/release/dev/0-sample-topic.rst @@ -0,0 +1,7 @@ +0-sample-topic +-------------- + +* This is a sample release note for the change in a topic. + Developers should add similar notes for each topic branch + making a noteworthy change. Each document should be named + and titled to match the topic name to avoid merge conflicts. diff --git a/Help/release/dev/CheckIncludeFiles-language-CXX.rst b/Help/release/dev/CheckIncludeFiles-language-CXX.rst new file mode 100644 index 0000000..1631a5e --- /dev/null +++ b/Help/release/dev/CheckIncludeFiles-language-CXX.rst @@ -0,0 +1,6 @@ +CheckIncludeFiles-language-CXX +------------------------------ + +* The :module:`CheckIncludeFiles` module :command:`CHECK_INCLUDE_FILES` + command gained a ``LANGUAGE`` option to specify whether to check using the + ``C`` or ``CXX`` compiler. diff --git a/Help/release/dev/CodeBlocks-custom-compiler-id.rst b/Help/release/dev/CodeBlocks-custom-compiler-id.rst new file mode 100644 index 0000000..893bd5c --- /dev/null +++ b/Help/release/dev/CodeBlocks-custom-compiler-id.rst @@ -0,0 +1,6 @@ +CodeBlocks-custom-compiler-id +----------------------------- + +* 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. diff --git a/Help/release/dev/FetchContent.rst b/Help/release/dev/FetchContent.rst new file mode 100644 index 0000000..3b12977 --- /dev/null +++ b/Help/release/dev/FetchContent.rst @@ -0,0 +1,11 @@ +FetchContent +------------ + +* 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. diff --git a/Help/release/dev/FindIconv.rst b/Help/release/dev/FindIconv.rst new file mode 100644 index 0000000..98f2591 --- /dev/null +++ b/Help/release/dev/FindIconv.rst @@ -0,0 +1,4 @@ +FindIconv +--------- + +* A :module:`FindIconv` module was added to locate iconv support. diff --git a/Help/release/dev/FindOpenGL-glvnd-policy.rst b/Help/release/dev/FindOpenGL-glvnd-policy.rst new file mode 100644 index 0000000..3348acf --- /dev/null +++ b/Help/release/dev/FindOpenGL-glvnd-policy.rst @@ -0,0 +1,5 @@ +FindOpenGL-glvnd-policy +----------------------- + +* The :module:`FindOpenGL` module now prefers GLVND libraries if available. + See policy :policy:`CMP0072`. diff --git a/Help/release/dev/WriteBasicConfigVersionFile_SameMinorVersion.rst b/Help/release/dev/WriteBasicConfigVersionFile_SameMinorVersion.rst new file mode 100644 index 0000000..7f1c4d0 --- /dev/null +++ b/Help/release/dev/WriteBasicConfigVersionFile_SameMinorVersion.rst @@ -0,0 +1,5 @@ +WriteBasicConfigFile_SameMinorVersion +------------------------------------- + +* The :command:`write_basic_package_version_file` understands a new + ``SameMinorVersion`` option for the ``COMPATIBILITY`` argument. diff --git a/Help/release/dev/blas-lapack-flame.rst b/Help/release/dev/blas-lapack-flame.rst new file mode 100644 index 0000000..fdc3a69 --- /dev/null +++ b/Help/release/dev/blas-lapack-flame.rst @@ -0,0 +1,5 @@ +blas-lapack-flame +----------------- + +* The :module:`FindBLAS` and :module:`FindLAPACK` modules learned to support + `FLAME <https://github.com/flame>`__ ``blis`` and ``libflame``. diff --git a/Help/release/dev/cmake-default-dir-install-permissions.rst b/Help/release/dev/cmake-default-dir-install-permissions.rst new file mode 100644 index 0000000..8325fda --- /dev/null +++ b/Help/release/dev/cmake-default-dir-install-permissions.rst @@ -0,0 +1,12 @@ +cmake-default-dir-install-permissions +------------------------------------- + +* The :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)`. + +* The :variable:`CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` variable was added + which serves the same purpose during packaging as the + :variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` variable serves during + installation (e.g. ``make install``). diff --git a/Help/release/dev/cmake-job-pool.rst b/Help/release/dev/cmake-job-pool.rst new file mode 100644 index 0000000..836d9c1 --- /dev/null +++ b/Help/release/dev/cmake-job-pool.rst @@ -0,0 +1,7 @@ +cmake-job-pool +-------------- + +* 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. diff --git a/Help/release/dev/cmake-open.rst b/Help/release/dev/cmake-open.rst new file mode 100644 index 0000000..a8f77ae --- /dev/null +++ b/Help/release/dev/cmake-open.rst @@ -0,0 +1,6 @@ +cmake-open +---------- + +* The :manual:`cmake(1)` ``--open <dir>`` command line option can now + be used to open generated IDE projects like Visual Studio solutions + or Xcode projects. diff --git a/Help/release/dev/cuda-sep-comp-var.rst b/Help/release/dev/cuda-sep-comp-var.rst new file mode 100644 index 0000000..23536ef --- /dev/null +++ b/Help/release/dev/cuda-sep-comp-var.rst @@ -0,0 +1,6 @@ +cuda-sep-comp-var +----------------- + +* 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. diff --git a/Help/release/dev/curl_netrc_options.rst b/Help/release/dev/curl_netrc_options.rst new file mode 100644 index 0000000..850c9ce --- /dev/null +++ b/Help/release/dev/curl_netrc_options.rst @@ -0,0 +1,14 @@ +curl_netrc_options +------------------ + +* The :command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands + gained ``NETRC`` and ``NETRC_FILE`` options to specify use of a + ``.netrc`` file. + +* The :module:`ExternalProject` module gained ``NETRC`` and ``NETRC_FILE`` + options to specify use of a ``.netrc`` file. + +* 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. diff --git a/Help/release/dev/defer-target-source-check.rst b/Help/release/dev/defer-target-source-check.rst new file mode 100644 index 0000000..65f5488 --- /dev/null +++ b/Help/release/dev/defer-target-source-check.rst @@ -0,0 +1,6 @@ +defer-target-source-check +------------------------- + +* :command:`add_library` and :command:`add_executable` commands can now be + called without any sources and will not complain as long as sources will + be added later via :command:`target_sources`. diff --git a/Help/release/dev/deprecate-policy-old.rst b/Help/release/dev/deprecate-policy-old.rst new file mode 100644 index 0000000..bcfa70a --- /dev/null +++ b/Help/release/dev/deprecate-policy-old.rst @@ -0,0 +1,8 @@ +deprecate-policy-old +-------------------- + +* 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. diff --git a/Help/release/dev/extend-compile-language-genex.rst b/Help/release/dev/extend-compile-language-genex.rst new file mode 100644 index 0000000..0a0a669 --- /dev/null +++ b/Help/release/dev/extend-compile-language-genex.rst @@ -0,0 +1,7 @@ +extend-compile-language-genex +----------------------------- + +* The ``COMPILE_LANGUAGE`` :manual:`generator expression + <cmake-generator-expressions(7)>` may now be used with + :ref:`Visual Studio Generators` in :prop_tgt:`COMPILE_OPTIONS` + and :command:`file(GENERATE)`. diff --git a/Help/release/dev/fortran-compiler-launcher.rst b/Help/release/dev/fortran-compiler-launcher.rst new file mode 100644 index 0000000..ce254f1 --- /dev/null +++ b/Help/release/dev/fortran-compiler-launcher.rst @@ -0,0 +1,8 @@ +fortran-compiler-launcher +------------------------- + +* 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. diff --git a/Help/release/dev/generalize-importedtargets-behavior.rst b/Help/release/dev/generalize-importedtargets-behavior.rst new file mode 100644 index 0000000..c6f4523 --- /dev/null +++ b/Help/release/dev/generalize-importedtargets-behavior.rst @@ -0,0 +1,25 @@ +generalize-importedtargets-behavior +----------------------------------- + +* 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`. + +* :ref:`Alias Targets` may now alias :ref:`Imported Targets` that are + created with the ``GLOBAL`` option to :command:`add_library`. diff --git a/Help/release/dev/generator-instance.rst b/Help/release/dev/generator-instance.rst new file mode 100644 index 0000000..a3ff658 --- /dev/null +++ b/Help/release/dev/generator-instance.rst @@ -0,0 +1,8 @@ +generator-instance +------------------ + +* 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. diff --git a/Help/release/dev/imported-promotion.rst b/Help/release/dev/imported-promotion.rst new file mode 100644 index 0000000..d184178 --- /dev/null +++ b/Help/release/dev/imported-promotion.rst @@ -0,0 +1,15 @@ +imported-promotion +------------------ + +* Added new target-property :prop_tgt:`IMPORTED_GLOBAL` which + indicates if an :ref:`IMPORTED target <Imported Targets>` is + globally visible. + It will be set automatically if such an imported target is + created with the ``GLOBAL`` flag. + +* Additionally, it is now also possible to promote a local imported + target to become globally visible by setting its + :prop_tgt:`IMPORTED_GLOBAL` property to `TRUE`. (However, this + promotion can only succeed if it is done from within the same + directory where the imported target was created in the first + place.) Setting it to `FALSE` is not supported! diff --git a/Help/release/dev/src-COMPILE_DEFINITIONS-genex.rst b/Help/release/dev/src-COMPILE_DEFINITIONS-genex.rst new file mode 100644 index 0000000..892344f --- /dev/null +++ b/Help/release/dev/src-COMPILE_DEFINITIONS-genex.rst @@ -0,0 +1,5 @@ +src-COMPILE_DEFINITIONS-genex +----------------------------- + +* The :prop_sf:`COMPILE_DEFINITIONS` source file property learned to support + :manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/release/dev/ti-compiler-depfile-support.rst b/Help/release/dev/ti-compiler-depfile-support.rst new file mode 100644 index 0000000..f870afd --- /dev/null +++ b/Help/release/dev/ti-compiler-depfile-support.rst @@ -0,0 +1,4 @@ +ti-compiler-depfile-support +--------------------------- + +* TI C/C++ compilers are now supported by the :generator:`Ninja` generator. diff --git a/Help/release/dev/vs-hlsl-opt-dbg.rst b/Help/release/dev/vs-hlsl-opt-dbg.rst new file mode 100644 index 0000000..8f398ae --- /dev/null +++ b/Help/release/dev/vs-hlsl-opt-dbg.rst @@ -0,0 +1,6 @@ +vs-hlsl-opt-dbg +--------------- + +* 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`. diff --git a/Help/release/dev/whitelist-more-interface-properties.rst b/Help/release/dev/whitelist-more-interface-properties.rst new file mode 100644 index 0000000..793361c --- /dev/null +++ b/Help/release/dev/whitelist-more-interface-properties.rst @@ -0,0 +1,7 @@ +whitelist-more-interface-properties +----------------------------------- + +* ``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. diff --git a/Help/release/dev/write-single-xcodeproj.rst b/Help/release/dev/write-single-xcodeproj.rst new file mode 100644 index 0000000..d5e9fef --- /dev/null +++ b/Help/release/dev/write-single-xcodeproj.rst @@ -0,0 +1,8 @@ +write-single-xcodeproj +---------------------- + +* The :generator:`Xcode` generator behavior of generating one project + file per :command:`project()` command could 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. diff --git a/Help/release/index.rst b/Help/release/index.rst index 0c7572f..6472b51 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -7,6 +7,8 @@ CMake Release Notes This file should include the adjacent "dev.txt" file in development versions but not in release versions. +.. include:: dev.txt + Releases ======== diff --git a/Help/variable/CMAKE_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_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_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_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_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_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_NETRC.rst b/Help/variable/CMAKE_NETRC.rst new file mode 100644 index 0000000..52f857e --- /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(DOWNLOAD)` 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..1508f1e --- /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(DOWNLOAD)` 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_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/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. |