diff options
Diffstat (limited to 'Help/variable')
50 files changed, 852 insertions, 34 deletions
diff --git a/Help/variable/CMAKE_ADSP_ROOT.rst b/Help/variable/CMAKE_ADSP_ROOT.rst new file mode 100644 index 0000000..f6f3927 --- /dev/null +++ b/Help/variable/CMAKE_ADSP_ROOT.rst @@ -0,0 +1,11 @@ +CMAKE_ADSP_ROOT +--------------- + +.. versionadded:: 3.24 + +When :ref:`Cross Compiling for ADSP SHARC/Blackfin`, +this variable holds the absolute path to the latest CCES or VDSP++ install. +The directory is expected to contain the ``cc21k.exe`` and ``ccblkfn.exe`` compilers. +This will be set automatically if a default install of CCES or VDSP++ can be found. + +See also the :envvar:`ADSP_ROOT` environment variable. diff --git a/Help/variable/CMAKE_COLOR_DIAGNOSTICS.rst b/Help/variable/CMAKE_COLOR_DIAGNOSTICS.rst new file mode 100644 index 0000000..a72c9e1 --- /dev/null +++ b/Help/variable/CMAKE_COLOR_DIAGNOSTICS.rst @@ -0,0 +1,37 @@ +CMAKE_COLOR_DIAGNOSTICS +----------------------- + +.. versionadded:: 3.24 + +Enable color diagnostics throughout. + +This variable uses three states: ``ON``, ``OFF`` and not defined. + +When not defined: + +* :ref:`Makefile Generators` initialize the :variable:`CMAKE_COLOR_MAKEFILE` + variable to ``ON``. It controls color buildsystem messages. + +* GNU/Clang compilers are not invoked with any color diagnostics flag. + +When ``ON``: + +* :ref:`Makefile Generators` produce color buildsystem messages by default. + :variable:`CMAKE_COLOR_MAKEFILE` is not initialized, but may be + explicitly set to ``OFF`` to disable color buildsystem messages. + +* GNU/Clang compilers are invoked with a flag enabling color diagnostics + (``-fcolor-diagnostics``). + +When ``OFF``: + +* :ref:`Makefile Generators` do not produce color buildsystem messages by + default. :variable:`CMAKE_COLOR_MAKEFILE` is not initialized, but may be + explicitly set to ``ON`` to enable color buildsystem messages. + +* GNU/Clang compilers are invoked with a flag disabling color diagnostics + (``-fno-color-diagnostics``). + +If the :envvar:`CMAKE_COLOR_DIAGNOSTICS` environment variable is set, its +value is used. Otherwise, ``CMAKE_COLOR_DIAGNOSTICS`` is not defined by +default. diff --git a/Help/variable/CMAKE_COMPILER_IS_GNUCC.rst b/Help/variable/CMAKE_COMPILER_IS_GNUCC.rst index 91cf848..4b799c0 100644 --- a/Help/variable/CMAKE_COMPILER_IS_GNUCC.rst +++ b/Help/variable/CMAKE_COMPILER_IS_GNUCC.rst @@ -1,7 +1,7 @@ CMAKE_COMPILER_IS_GNUCC ----------------------- -.. versionadded:: 3.7 - True if the ``C`` compiler is GNU. -Use :variable:`CMAKE_C_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` instead. + +This variable is deprecated. Use +:variable:`CMAKE_C_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` instead. diff --git a/Help/variable/CMAKE_COMPILER_IS_GNUCXX.rst b/Help/variable/CMAKE_COMPILER_IS_GNUCXX.rst index e67718a..29069d2 100644 --- a/Help/variable/CMAKE_COMPILER_IS_GNUCXX.rst +++ b/Help/variable/CMAKE_COMPILER_IS_GNUCXX.rst @@ -1,7 +1,7 @@ CMAKE_COMPILER_IS_GNUCXX ------------------------ -.. versionadded:: 3.7 - True if the C++ (``CXX``) compiler is GNU. -Use :variable:`CMAKE_CXX_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` instead. + +This variable is deprecated. Use +:variable:`CMAKE_CXX_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` instead. diff --git a/Help/variable/CMAKE_COMPILER_IS_GNUG77.rst b/Help/variable/CMAKE_COMPILER_IS_GNUG77.rst index f69c01a..05303dc 100644 --- a/Help/variable/CMAKE_COMPILER_IS_GNUG77.rst +++ b/Help/variable/CMAKE_COMPILER_IS_GNUG77.rst @@ -1,7 +1,7 @@ CMAKE_COMPILER_IS_GNUG77 ------------------------ -.. versionadded:: 3.7 - True if the ``Fortran`` compiler is GNU. -Use :variable:`CMAKE_Fortran_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` instead. + +This variable is deprecated. Use +:variable:`CMAKE_Fortran_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` instead. diff --git a/Help/variable/CMAKE_COMPILE_WARNING_AS_ERROR.rst b/Help/variable/CMAKE_COMPILE_WARNING_AS_ERROR.rst new file mode 100644 index 0000000..56dc6a6 --- /dev/null +++ b/Help/variable/CMAKE_COMPILE_WARNING_AS_ERROR.rst @@ -0,0 +1,9 @@ +CMAKE_COMPILE_WARNING_AS_ERROR +------------------------------ + +.. versionadded:: 3.24 + +Specify whether to treat warnings on compile as errors. + +This variable is used to initialize the +:prop_tgt:`COMPILE_WARNING_AS_ERROR` property on all the targets. diff --git a/Help/variable/CMAKE_FIND_PACKAGE_REDIRECTS_DIR.rst b/Help/variable/CMAKE_FIND_PACKAGE_REDIRECTS_DIR.rst new file mode 100644 index 0000000..5d45fb0 --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_REDIRECTS_DIR.rst @@ -0,0 +1,28 @@ +CMAKE_FIND_PACKAGE_REDIRECTS_DIR +-------------------------------- + +.. versionadded:: 3.24 + +This read-only variable specifies a directory that the :command:`find_package` +command will check first before searching anywhere else for a module or config +package file. A config package file in this directory will always be found in +preference to any other Find module file or config package file. + +The primary purpose of this variable is to facilitate integration between +:command:`find_package` and :command:`FetchContent_MakeAvailable`. The latter +command may create files in the ``CMAKE_FIND_PACKAGE_REDIRECTS_DIR`` directory +when it populates a dependency. This allows subsequent calls to +:command:`find_package` for the same dependency to re-use the populated +contents instead of trying to satisfy the dependency from somewhere external +to the build. Projects may also want to write files into this directory in +some situations (see :ref:`FetchContent-find_package-integration-examples` +for examples). + +The directory that ``CMAKE_FIND_PACKAGE_REDIRECTS_DIR`` points to will always +be erased and recreated empty at the start of every CMake run. Any files +written into this directory during the CMake run will be lost the next time +CMake configures the project. + +``CMAKE_FIND_PACKAGE_REDIRECTS_DIR`` is only set in CMake project mode. +It is not set when CMake is run in script mode +(i.e. :manual:`cmake -P ... <cmake(1)>`). diff --git a/Help/variable/CMAKE_FIND_PACKAGE_TARGETS_GLOBAL.rst b/Help/variable/CMAKE_FIND_PACKAGE_TARGETS_GLOBAL.rst new file mode 100644 index 0000000..fc9b315 --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_TARGETS_GLOBAL.rst @@ -0,0 +1,12 @@ +CMAKE_FIND_PACKAGE_TARGETS_GLOBAL +--------------------------------- + +.. versionadded:: 3.24 + +Setting to ``TRUE`` promotes all :prop_tgt:`IMPORTED` targets discoverd +by :command:`find_package` to a ``GLOBAL`` scope. + + +Setting this to ``TRUE`` is akin to specifying ``GLOBAL`` +as an argument to :command:`find_package`. +Default value is ``OFF``. diff --git a/Help/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.rst b/Help/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.rst index de1bad7..f72fd65 100644 --- a/Help/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.rst +++ b/Help/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.rst @@ -20,6 +20,7 @@ take precedence over this variable. See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, +:variable:`CMAKE_FIND_USE_INSTALL_PREFIX`, :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, :variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`, :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`, diff --git a/Help/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.rst b/Help/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.rst index 2fd00df..2c1d237 100644 --- a/Help/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.rst +++ b/Help/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.rst @@ -20,6 +20,7 @@ take precedence over this variable. See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_INSTALL_PREFIX`, :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, :variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`, :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`, diff --git a/Help/variable/CMAKE_FIND_USE_INSTALL_PREFIX.rst b/Help/variable/CMAKE_FIND_USE_INSTALL_PREFIX.rst new file mode 100644 index 0000000..d577a8a --- /dev/null +++ b/Help/variable/CMAKE_FIND_USE_INSTALL_PREFIX.rst @@ -0,0 +1,40 @@ +CMAKE_FIND_USE_INSTALL_PREFIX +----------------------------------- + +.. versionadded:: 3.24 + +Controls the default behavior of the following commands for whether or not to +search the locations in the :variable:`CMAKE_INSTALL_PREFIX` and +:variable:`CMAKE_STAGING_PREFIX` variables. + +* :command:`find_program` +* :command:`find_library` +* :command:`find_file` +* :command:`find_path` +* :command:`find_package` + +This is useful in cross-compiling environments. + +Due to backwards compatibility with :variable:`CMAKE_FIND_NO_INSTALL_PREFIX`, +the behavior of the find command change based on if this variable exists. + +============================== ============================ =========== + CMAKE_FIND_USE_INSTALL_PREFIX CMAKE_FIND_NO_INSTALL_PREFIX Search +============================== ============================ =========== + Not Defined On NO + Not Defined Off || Not Defined YES + Off On NO + Off Off || Not Defined NO + On On YES + On Off || Not Defined YES +============================== ============================ =========== + +By default this variable is not defined. Explicit options given to the above +commands take precedence over this variable. + +See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`, +:variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`, +and :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` variables. diff --git a/Help/variable/CMAKE_FIND_USE_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_FIND_USE_PACKAGE_REGISTRY.rst index 3127206..a5eec7a 100644 --- a/Help/variable/CMAKE_FIND_USE_PACKAGE_REGISTRY.rst +++ b/Help/variable/CMAKE_FIND_USE_PACKAGE_REGISTRY.rst @@ -26,6 +26,7 @@ the :ref:`User Package Registry` as if they were called with the See also :ref:`Disabling the Package Registry` and the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_INSTALL_PREFIX`, :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, :variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`, diff --git a/Help/variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH.rst b/Help/variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH.rst index 64e5c6d..1f876a9 100644 --- a/Help/variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH.rst +++ b/Help/variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH.rst @@ -18,6 +18,7 @@ take precedence over this variable. See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_INSTALL_PREFIX`, :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, :variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`, diff --git a/Help/variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.rst b/Help/variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.rst index a0a86e4..65edd10 100644 --- a/Help/variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.rst +++ b/Help/variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.rst @@ -20,6 +20,7 @@ take precedence over this variable. See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_INSTALL_PREFIX`, :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`, :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH`, diff --git a/Help/variable/CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY.rst index 504b7e8..2527904 100644 --- a/Help/variable/CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY.rst +++ b/Help/variable/CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY.rst @@ -27,6 +27,7 @@ See also :ref:`Disabling the Package Registry`. See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_INSTALL_PREFIX`, :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`, diff --git a/Help/variable/CMAKE_LANG_COMPILER_ID.rst b/Help/variable/CMAKE_LANG_COMPILER_ID.rst index cd7d5cd..6a0a1d9 100644 --- a/Help/variable/CMAKE_LANG_COMPILER_ID.rst +++ b/Help/variable/CMAKE_LANG_COMPILER_ID.rst @@ -18,7 +18,8 @@ include: Clang = LLVM Clang (clang.llvm.org) Cray = Cray Compiler (cray.com) Embarcadero, Borland = Embarcadero (embarcadero.com) - Flang = Flang LLVM Fortran Compiler + Flang = Classic Flang Fortran Compiler (https://github.com/flang-compiler/flang) + LLVMFlang = LLVM Flang Fortran Compiler (https://github.com/llvm/llvm-project/tree/main/flang) Fujitsu = Fujitsu HPC compiler (Trad mode) FujitsuClang = Fujitsu HPC compiler (Clang mode) G95 = G95 Fortran (g95.org) diff --git a/Help/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE.rst b/Help/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE.rst new file mode 100644 index 0000000..7c929d0 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE.rst @@ -0,0 +1,16 @@ +CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE> +--------------------------------------- + +.. versionadded:: 3.24 + +This variable defines how to link a group of libraries for the specified +``<FEATURE>`` when a :genex:`LINK_GROUP` generator expression is used and +the link language for the target is ``<LANG>``. +For this variable to have any effect, the associated +:variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED` variable +must be set to true. + +The :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>` variable should be defined +instead for features that are independent of the link language. + +.. include:: CMAKE_LINK_GROUP_USING_FEATURE.txt diff --git a/Help/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE_SUPPORTED.rst b/Help/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE_SUPPORTED.rst new file mode 100644 index 0000000..b314c5a --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE_SUPPORTED.rst @@ -0,0 +1,14 @@ +CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED +------------------------------------------------- + +.. versionadded:: 3.24 + +This variable specifies whether the ``<FEATURE>`` is supported for the link +language ``<LANG>``. If this variable is true, then the ``<FEATURE>`` must +be defined by :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>`, and the +more generic :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED` and +:variable:`CMAKE_LINK_GROUP_USING_<FEATURE>` variables are not used. + +If ``CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED`` is false or is not +set, then the :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED` variable +will determine whether ``<FEATURE>`` is deemed to be supported. diff --git a/Help/variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE.rst b/Help/variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE.rst new file mode 100644 index 0000000..39fcff8 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE.rst @@ -0,0 +1,16 @@ +CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE> +----------------------------------------- + +.. versionadded:: 3.24 + +This variable defines how to link a library or framework for the specified +``<FEATURE>`` when a :genex:`LINK_LIBRARY` generator expression is used and +the link language for the target is ``<LANG>``. +For this variable to have any effect, the associated +:variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` variable +must be set to true. + +The :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variable should be defined +instead for features that are independent of the link language. + +.. include:: CMAKE_LINK_LIBRARY_USING_FEATURE.txt diff --git a/Help/variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE_SUPPORTED.rst b/Help/variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE_SUPPORTED.rst new file mode 100644 index 0000000..e595bc7 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE_SUPPORTED.rst @@ -0,0 +1,13 @@ +CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED +--------------------------------------------------- + +.. versionadded:: 3.24 + +Set to ``TRUE`` if the ``<FEATURE>``, as defined by variable +:variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>`, is supported for the +linker language ``<LANG>``. + +.. note:: + + This variable is evaluated before the more generic variable + :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED`. diff --git a/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE.rst b/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE.rst new file mode 100644 index 0000000..90b7f8b --- /dev/null +++ b/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE.rst @@ -0,0 +1,22 @@ +CMAKE_LINK_GROUP_USING_<FEATURE> +-------------------------------- + +.. versionadded:: 3.24 + +This variable defines how to link a group of libraries for the specified +``<FEATURE>`` when a :genex:`LINK_GROUP` generator expression is used. +Both of the following conditions must be met for this variable to have any +effect: + +* The associated :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED` + variable must be set to true. + +* There is no language-specific definition for the same ``<FEATURE>``. + This means :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED` + cannot be true for the link language used by the target for which the + :genex:`LINK_GROUP` generator expression is evaluated. + +The :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>` variable should be +defined instead for features that are dependent on the link language. + +.. include:: CMAKE_LINK_GROUP_USING_FEATURE.txt diff --git a/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE.txt b/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE.txt new file mode 100644 index 0000000..23ea157 --- /dev/null +++ b/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE.txt @@ -0,0 +1,78 @@ +Feature names are case-sensitive and may only contain letters, numbers +and underscores. Feature names defined in all uppercase are reserved for +CMake's own built-in features (see `Predefined Features`_ further below). + + +Feature Definitions +^^^^^^^^^^^^^^^^^^^ + +A group feature definition is a list that contains exactly two elements: + +:: + + <PREFIX> <SUFFIX> + +On the linker command line, ``<PREFIX>`` will precede the list of libraries +in the group and ``<SUFFIX>`` will follow after. + +For the elements of this variable, the ``LINKER:`` prefix can be used. + +.. include:: ../command/LINK_OPTIONS_LINKER.txt + :start-line: 3 + +Examples +^^^^^^^^ + +Solving cross-references between two static libraries +""""""""""""""""""""""""""""""""""""""""""""""""""""" + +A project may define two or more static libraries which have circular +dependencies between them. In order for the linker to resolve all symbols +at link time, it may need to search repeatedly among the libraries until no +new undefined references are created. Different linkers use different syntax +for achieving this. The following example shows how this may be implemented +for some linkers. Note that this is for illustration purposes only. +Projects should use the built-in ``RESCAN`` group feature instead +(see `Predefined Features`_), which provides a more complete and more robust +implementation of this functionality. + +.. code-block:: cmake + + set(CMAKE_C_LINK_GROUP_USING_cross_refs_SUPPORTED TRUE) + if(CMAKE_C_COMPILER_ID STREQUAL "GNU" AND CMAKE_SYSTEM_NAME STREQUAL "Linux") + set(CMAKE_C_LINK_GROUP_USING_cross_refs + "LINKER:--start-group" + "LINKER:--end-group" + ) + elseif(CMAKE_C_COMPILER_ID STREQUAL "SunPro" AND CMAKE_SYSTEM_NAME STREQUAL "SunOS") + set(CMAKE_C_LINK_GROUP_USING_cross_refs + "LINKER:-z,rescan-start" + "LINKER:-z,rescan-end" + ) + else() + # feature not yet supported for the other environments + set(CMAKE_C_LINK_GROUP_USING_cross_refs_SUPPORTED FALSE) + endif() + + add_library(lib1 STATIC ...) + add_library(lib2 SHARED ...) + + if(CMAKE_C_LINK_GROUP_USING_cross_refs_SUPPORTED) + target_link_libraries(lib2 PRIVATE "$<LINK_GROUP:cross_refs,lib1,external>") + else() + target_link_libraries(lib2 PRIVATE lib1 external) + endif() + +CMake will generate the following linker command line fragments when linking +``lib2``: + +* ``GNU``: ``-Wl,--start-group /path/to/lib1.a -lexternal -Wl,--end-group`` +* ``SunPro``: ``-Wl,-z,rescan-start /path/to/lib1.a -lexternal -Wl,-z,rescan-end`` + + +Predefined Features +^^^^^^^^^^^^^^^^^^^ + +The following built-in group features are pre-defined by CMake: + +.. include:: LINK_GROUP_PREDEFINED_FEATURES.txt diff --git a/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE_SUPPORTED.rst b/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE_SUPPORTED.rst new file mode 100644 index 0000000..8b4ee6e --- /dev/null +++ b/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE_SUPPORTED.rst @@ -0,0 +1,12 @@ +CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED +------------------------------------------ + +.. versionadded:: 3.24 + +This variable specifies whether the ``<FEATURE>`` is supported regardless of +the link language. If this variable is true, then the ``<FEATURE>`` must +be defined by :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>`. + +Note that this variable has no effect if +:variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED` is true for +the link language of the target. diff --git a/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.rst b/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.rst new file mode 100644 index 0000000..c652733 --- /dev/null +++ b/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.rst @@ -0,0 +1,19 @@ +CMAKE_LINK_LIBRARY_USING_<FEATURE> +---------------------------------- + +.. versionadded:: 3.24 + +This variable defines how to link a library or framework for the specified +``<FEATURE>`` when a :genex:`LINK_LIBRARY` generator expression is used. +Both of the following conditions must be met for this variable to have any +effect: + +* The associated :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` + variable must be set to true. + +* There is no language-specific definition for the same ``<FEATURE>``. + This means :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` + cannot be true for the link language used by the target for which the + :genex:`LINK_LIBRARY` generator expression is evaluated. + +.. include:: CMAKE_LINK_LIBRARY_USING_FEATURE.txt diff --git a/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.txt b/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.txt new file mode 100644 index 0000000..4b13b7c --- /dev/null +++ b/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.txt @@ -0,0 +1,150 @@ +Feature names are case-sensitive and may only contain letters, numbers +and underscores. Feature names defined in all uppercase are reserved for +CMake's own built-in features (see `Predefined Features`_ further below). + + +Feature Definitions +^^^^^^^^^^^^^^^^^^^ + +A library feature definition is a list that contains one or three elements: + +:: + + [<PREFIX>] <LIBRARY_EXPRESSION> [<SUFFIX>] + +When ``<PREFIX>`` and ``<SUFFIX>`` are specified, they precede and follow +respectively the whole list of libraries specified in the +:genex:`LINK_LIBRARY` expression, not each library item individually. +There is no guarantee that the list of specified libraries will be kept +grouped together though, so the ``<PREFIX>`` and ``<SUFFIX>`` may appear +more than once if the library list is reorganized by CMake to satisfy other +constraints. This means constructs like ``--start-group`` and ``--end-group``, +as supported by the GNU ``ld`` linker, cannot be used in this way. The +:genex:`LINK_GROUP` generator expression should be used instead for such +constructs. + +``<LIBRARY_EXPRESSION>`` is used to specify the pattern for constructing the +corresponding fragment on the linker command line for each library. +The following placeholders can be used in the expression: + +* ``<LIBRARY>`` is expanded to the full path to the library for CMake targets, + or to a platform-specific value based on the item otherwise (the same as + ``<LINK_ITEM>`` on Windows, or the library base name for other platforms). +* ``<LINK_ITEM>`` is expanded to how the library would normally be linked on + the linker command line. +* ``<LIB_ITEM>`` is expanded to the full path to the library for CMake targets, + or the item itself exactly as specified in the ``<LIBRARY_EXPRESSION>`` + otherwise. + +In addition to the above, it is possible to have one pattern for paths +(CMake targets and external libraries specified with file paths) and another +for other items specified by name only. The ``PATH{}`` and ``NAME{}`` wrappers +can be used to provide the expansion for those two cases, respectively. +When wrappers are used, both must be present. For example: + +.. code-block:: cmake + + set(CMAKE_LINK_LIBRARY_USING_weak_library + "PATH{-weak_library <LIBRARY>}NAME{LINKER:-weak-l<LIB_ITEM>}" + ) + +For all three elements of this variable (``<PREFIX>``, ``<LIBRARY_EXPRESSION>``, +and ``<SUFFIX>``), the ``LINKER:`` prefix can be used. + +.. include:: ../command/LINK_OPTIONS_LINKER.txt + :start-line: 3 + +Examples +^^^^^^^^ + +Loading a whole static library +"""""""""""""""""""""""""""""" + +A common need is to prevent the linker from discarding any symbols from a +static library. Different linkers use different syntax for achieving this. +The following example shows how this may be implemented for some linkers. +Note that this is for illustration purposes only. Projects should use the +built-in ``WHOLE_ARCHIVE`` feature instead (see `Predefined Features`_), which +provides a more complete and more robust implementation of this functionality. + +.. code-block:: cmake + + set(CMAKE_C_LINK_LIBRARY_USING_load_archive_SUPPORTED TRUE) + if(CMAKE_C_COMPILER_ID STREQUAL "AppleClang") + set(CMAKE_C_LINK_LIBRARY_USING_load_archive "-force_load <LIB_ITEM>") + elseif(CMAKE_C_COMPILER_ID STREQUAL "GNU" AND CMAKE_SYSTEM_NAME STREQUAL "Linux") + set(CMAKE_C_LINK_LIBRARY_USING_load_archive + "LINKER:--push-state,--whole-archive" + "<LINK_ITEM>" + "LINKER:--pop-state" + ) + elseif(CMAKE_C_COMPILER_ID STREQUAL "MSVC") + set(CMAKE_C_LINK_LIBRARY_USING_load_archive "/WHOLEARCHIVE:<LIBRARY>") + else() + # feature not yet supported for the other environments + set(CMAKE_C_LINK_LIBRARY_USING_load_archive_SUPPORTED FALSE) + endif() + + add_library(lib1 STATIC ...) + add_library(lib2 SHARED ...) + + if(CMAKE_C_LINK_LIBRARY_USING_load_archive_SUPPORTED) + # The -force_load Apple linker option requires a file name + set(external_lib + "$<IF:$<LINK_LANG_AND_ID:C,AppleClang>,libexternal.a,external>" + ) + target_link_libraries(lib2 PRIVATE + "$<LINK_LIBRARY:load_archive,lib1,${external_lib}>" + ) + else() + target_link_libraries(lib2 PRIVATE lib1 external) + endif() + +CMake will generate the following link expressions: + +* ``AppleClang``: ``-force_load /path/to/lib1.a -force_load libexternal.a`` +* ``GNU``: ``-Wl,--push-state,--whole-archive /path/to/lib1.a -lexternal -Wl,--pop-state`` +* ``MSVC``: ``/WHOLEARCHIVE:/path/to/lib1.lib /WHOLEARCHIVE:external.lib`` + +Linking a library as weak +""""""""""""""""""""""""" + +On macOS, it is possible to link a library in weak mode (the library and all +references are marked as weak imports). Different flags must be used for a +library specified by file path compared to one specified by name. +This constraint can be solved using ``PATH{}`` and ``NAME{}`` wrappers. +Again, the following example shows how this may be implemented for some +linkers, but it is for illustration purposes only. Projects should use the +built-in ``WEAK_FRAMEWORK`` or ``WEAK_LIBRARY`` features instead (see +`Predefined Features`_), which provide more complete and more robust +implementations of this functionality. + +.. code-block:: cmake + + if (CMAKE_C_COMPILER_ID STREQUAL "AppleClang") + set(CMAKE_LINK_LIBRARY_USING_weak_library + "PATH{-weak_library <LIBRARY>}NAME{LINKER:-weak-l<LIB_ITEM>}" + ) + set(CMAKE_LINK_LIBRARY_USING_weak_library_SUPPORTED TRUE) + endif() + + add_library(lib SHARED ...) + add_executable(main ...) + if(CMAKE_LINK_LIBRARY_USING_weak_library_SUPPORTED) + target_link_libraries(main PRIVATE "$<LINK_LIBRARY:weak_library,lib,external>") + else() + target_link_libraries(main PRIVATE lib external) + endif() + +CMake will generate the following linker command line fragment when linking +``main`` using the ``AppleClang`` toolchain: + +``-weak_library /path/to/lib -Xlinker -weak-lexternal``. + + +Predefined Features +^^^^^^^^^^^^^^^^^^^ + +The following built-in library features are pre-defined by CMake: + +.. include:: LINK_LIBRARY_PREDEFINED_FEATURES.txt diff --git a/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE_SUPPORTED.rst b/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE_SUPPORTED.rst new file mode 100644 index 0000000..417724b --- /dev/null +++ b/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE_SUPPORTED.rst @@ -0,0 +1,14 @@ +CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED +-------------------------------------------- + +.. versionadded:: 3.24 + +Set to ``TRUE`` if the ``<FEATURE>``, as defined by variable +:variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>`, is supported regardless the +linker language. + +.. note:: + + This variable is evaluated if, and only if, the variable + :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` is not + defined. diff --git a/Help/variable/CMAKE_OSX_VARIABLE.txt b/Help/variable/CMAKE_OSX_VARIABLE.txt index 16f3c1a..5670980 100644 --- a/Help/variable/CMAKE_OSX_VARIABLE.txt +++ b/Help/variable/CMAKE_OSX_VARIABLE.txt @@ -3,7 +3,8 @@ 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 should be set as a ``CACHE`` entry (or else CMake may -remove it while initializing a cache entry of the same name). +remove it while initializing a cache entry of the same name) unless +policy :policy:`CMP0126` is set to ``NEW``. Despite the ``OSX`` part in the variable name(s) they apply also to other SDKs than macOS like iOS, tvOS, or watchOS. diff --git a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst index 8c84f91..9dce760 100644 --- a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst +++ b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst @@ -36,6 +36,8 @@ only for the policies that do not warn by default: policy :policy:`CMP0128`. * ``CMAKE_POLICY_WARNING_CMP0129`` controls the warning for policy :policy:`CMP0129`. +* ``CMAKE_POLICY_WARNING_CMP0133`` controls the warning for + policy :policy:`CMP0133`. This variable should not be set by a project in CMake code. Project developers running CMake may set this variable in their cache to diff --git a/Help/variable/CMAKE_PROJECT_INCLUDE.rst b/Help/variable/CMAKE_PROJECT_INCLUDE.rst index 41d9e5d..76b9d92 100644 --- a/Help/variable/CMAKE_PROJECT_INCLUDE.rst +++ b/Help/variable/CMAKE_PROJECT_INCLUDE.rst @@ -5,8 +5,11 @@ CMAKE_PROJECT_INCLUDE A CMake language file or module to be included as the last step of all :command:`project` command calls. This is intended for injecting custom code -into project builds without modifying their source. +into project builds without modifying their source. See :ref:`Code Injection` +for a more detailed discussion of files potentially included during a +:command:`project` call. See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, -:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE` and -:variable:`CMAKE_PROJECT_INCLUDE_BEFORE` variables. +:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`, +:variable:`CMAKE_PROJECT_INCLUDE_BEFORE`, and +:variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variables. diff --git a/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst b/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst index c2fd0f8..9a8c4b5 100644 --- a/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst +++ b/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst @@ -5,8 +5,11 @@ CMAKE_PROJECT_INCLUDE_BEFORE A CMake language file or module to be included as the first step of all :command:`project` command calls. This is intended for injecting custom code -into project builds without modifying their source. +into project builds without modifying their source. See :ref:`Code Injection` +for a more detailed discussion of files potentially included during a +:command:`project` call. See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, -:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE` and -:variable:`CMAKE_PROJECT_INCLUDE` variables. +:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`, +:variable:`CMAKE_PROJECT_INCLUDE`, and +:variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variables. diff --git a/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst index 74247f1..3bb5cd8 100644 --- a/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst +++ b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst @@ -4,8 +4,9 @@ CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE A CMake language file or module to be included as the last step of any :command:`project` command calls that specify ``<PROJECT-NAME>`` as the project name. This is intended for injecting custom code into project builds without -modifying their source. +modifying their source. See :ref:`Code Injection` for a more detailed +discussion of files potentially included during a :command:`project` call. See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`, -:variable:`CMAKE_PROJECT_INCLUDE` and -:variable:`CMAKE_PROJECT_INCLUDE_BEFORE` variables. +:variable:`CMAKE_PROJECT_INCLUDE`, :variable:`CMAKE_PROJECT_INCLUDE_BEFORE`, +and :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variables. diff --git a/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE.rst b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE.rst index 39abb12..ca584c1 100644 --- a/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE.rst +++ b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE.rst @@ -6,8 +6,9 @@ CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE A CMake language file or module to be included as the first step of any :command:`project` command calls that specify ``<PROJECT-NAME>`` as the project name. This is intended for injecting custom code into project builds without -modifying their source. +modifying their source. See :ref:`Code Injection` for a more detailed +discussion of files potentially included during a :command:`project` call. See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, -:variable:`CMAKE_PROJECT_INCLUDE` and -:variable:`CMAKE_PROJECT_INCLUDE_BEFORE` variables. +:variable:`CMAKE_PROJECT_INCLUDE`, :variable:`CMAKE_PROJECT_INCLUDE_BEFORE`, +and :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variables. diff --git a/Help/variable/CMAKE_PROJECT_TOP_LEVEL_INCLUDES.rst b/Help/variable/CMAKE_PROJECT_TOP_LEVEL_INCLUDES.rst new file mode 100644 index 0000000..2010b08 --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_TOP_LEVEL_INCLUDES.rst @@ -0,0 +1,27 @@ +CMAKE_PROJECT_TOP_LEVEL_INCLUDES +-------------------------------- + +.. versionadded:: 3.24 + +:ref:`Semicolon-separated list <CMake Language Lists>` of CMake language +files to include as part of the very first :command:`project` call. +The files will be included immediately after the toolchain file has been read +(if one is specified) and platform variables have been set, but before any +languages have been enabled. Therefore, language-specific variables, +including things like :variable:`CMAKE_<LANG>_COMPILER`, might not be set. +See :ref:`Code Injection` for a more detailed discussion of files potentially +included during a :command:`project` call. + +This variable is intended for specifying files that perform one-time setup +for the build. It provides an injection point for things like configuring +package managers, adding logic the user shares between projects (e.g. defining +their own custom build types), and so on. It is primarily for users to add +things specific to their environment, but not for specifying the toolchain +details (use :variable:`CMAKE_TOOLCHAIN_FILE` for that). + +By default, this variable is empty. It is intended to be set by the user. + +See also the :variable:`CMAKE_PROJECT_INCLUDE`, +:variable:`CMAKE_PROJECT_INCLUDE_BEFORE`, +:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, and +:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE` variables. diff --git a/Help/variable/CMAKE_TOOLCHAIN_FILE.rst b/Help/variable/CMAKE_TOOLCHAIN_FILE.rst index ff8d59a..1117c1f 100644 --- a/Help/variable/CMAKE_TOOLCHAIN_FILE.rst +++ b/Help/variable/CMAKE_TOOLCHAIN_FILE.rst @@ -13,3 +13,6 @@ build directory, and if not found, relative to the source directory. This is initialized by the :envvar:`CMAKE_TOOLCHAIN_FILE` environment variable if it is set when a new build tree is first created. + +See the :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable for setting +other things not directly related to the toolchain. diff --git a/Help/variable/CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES.rst b/Help/variable/CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES.rst new file mode 100644 index 0000000..c68a36c --- /dev/null +++ b/Help/variable/CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES.rst @@ -0,0 +1,12 @@ +CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES +--------------------------------------- + +.. versionadded:: 3.24 + +Set to a true value to tell the :command:`try_compile` command not +to propagate any platform variables into the test project. + +The :command:`try_compile` command normally passes some CMake variables +that configure the platform and toolchain behavior into test projects. +See policy :policy:`CMP0137`. This variable may be set to disable +that behavior. diff --git a/Help/variable/CMAKE_TRY_COMPILE_PLATFORM_VARIABLES.rst b/Help/variable/CMAKE_TRY_COMPILE_PLATFORM_VARIABLES.rst index d178513..6b26d14 100644 --- a/Help/variable/CMAKE_TRY_COMPILE_PLATFORM_VARIABLES.rst +++ b/Help/variable/CMAKE_TRY_COMPILE_PLATFORM_VARIABLES.rst @@ -26,3 +26,12 @@ If a user passes ``-DMY_CUSTOM_VARIABLE=SomeValue`` to CMake then this setting will be made visible to the toolchain file both for the main project and for test projects generated by the :command:`try_compile` command source file signature. + +.. versionchanged:: 3.24 + Listed variables are propagated to the :command:`try_compile` + :ref:`whole-project <Try Compiling Whole Projects>` signature too. + See :policy:`CMP0137`. + +.. versionadded:: 3.24 + The :variable:`CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES` variable may be + set to disable passing platform variables into the test project. diff --git a/Help/variable/CMAKE_USER_MAKE_RULES_OVERRIDE.rst b/Help/variable/CMAKE_USER_MAKE_RULES_OVERRIDE.rst index 622278e..71c06cf 100644 --- a/Help/variable/CMAKE_USER_MAKE_RULES_OVERRIDE.rst +++ b/Help/variable/CMAKE_USER_MAKE_RULES_OVERRIDE.rst @@ -8,6 +8,8 @@ language from either the :command:`project` or :command:`enable_language` commands. It is loaded after CMake's builtin compiler and platform information modules have been loaded but before the information is used. The file may set platform information variables to override CMake's defaults. +See :variable:`CMAKE_USER_MAKE_RULES_OVERRIDE_<LANG>` for the language-specific +version of this variable. This feature is intended for use only in overriding information variables that must be set before CMake builds its first test project diff --git a/Help/variable/CMAKE_VERIFY_INTERFACE_HEADER_SETS.rst b/Help/variable/CMAKE_VERIFY_INTERFACE_HEADER_SETS.rst new file mode 100644 index 0000000..3fb8817 --- /dev/null +++ b/Help/variable/CMAKE_VERIFY_INTERFACE_HEADER_SETS.rst @@ -0,0 +1,39 @@ +CMAKE_VERIFY_INTERFACE_HEADER_SETS +---------------------------------- + +.. versionadded:: 3.24 + +This variable is used to initialize the +:prop_tgt:`VERIFY_INTERFACE_HEADER_SETS` property of targets when they are +created. Setting it to true enables header set verification. + +Projects should not normally set this variable, it is intended as a developer +control to be set on the :manual:`cmake(1)` command line or other +equivalent methods. The developer must have the ability to enable or +disable header set verification according to the capabilities of their own +machine and compiler. + +Verification of a dependency's header sets is not typically of interest +to developers. Therefore, :command:`FetchContent_MakeAvailable` explicitly +sets ``CMAKE_VERIFY_INTERFACE_HEADER_SETS`` to false for the duration of its +call, but restores its original value before returning. If a project brings +a dependency directly into the main build (e.g. calling +:command:`add_subdirectory` on a vendored project from a git submodule), it +should also do likewise. For example: + +.. code:: cmake + + # Save original setting so we can restore it later + set(want_header_set_verification ${CMAKE_VERIFY_INTERFACE_HEADER_SETS}) + + # Include the vendored dependency with header set verification disabled + set(CMAKE_VERIFY_INTERFACE_HEADER_SETS OFF) + add_subdirectory(...) # Vendored sources, e.g. from git submodules + + # Add the project's own sources. Restore the developer's original choice + # for whether to enable header set verification. + set(CMAKE_VERIFY_INTERFACE_HEADER_SETS ${want_header_set_verification}) + add_subdirectory(src) + +By default, this variable is not set, which will result in header set +verification being disabled. diff --git a/Help/variable/CMAKE_VS_NO_COMPILE_BATCHING.rst b/Help/variable/CMAKE_VS_NO_COMPILE_BATCHING.rst new file mode 100644 index 0000000..2fb163e --- /dev/null +++ b/Help/variable/CMAKE_VS_NO_COMPILE_BATCHING.rst @@ -0,0 +1,20 @@ +CMAKE_VS_NO_COMPILE_BATCHING +---------------------------- + +.. versionadded:: 3.24 + +Turn off compile batching when using :ref:`Visual Studio Generators`. + +This variable is used to initialize the :prop_tgt:`VS_NO_COMPILE_BATCHING` +property on all targets when they are created. See that target property for +additional information. + +Example +^^^^^^^ + +This shows setting the property for the target ``foo`` using the variable. + +.. code-block:: cmake + + set(CMAKE_VS_NO_COMPILE_BATCHING ON) + add_library(foo SHARED foo.cpp) diff --git a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE.rst b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE.rst index 84d7212..5c13bb7 100644 --- a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE.rst +++ b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE.rst @@ -9,4 +9,4 @@ The :ref:`Visual Studio Generators` for VS 2013 and above support using either the 32-bit or 64-bit host toolchains by specifying a ``host=x86`` or ``host=x64`` value in the :variable:`CMAKE_GENERATOR_TOOLSET` option. CMake provides the selected toolchain architecture preference in this -variable (``x86``, ``x64``, or empty). +variable (``x86``, ``x64``, ``ARM64`` or empty). diff --git a/Help/variable/CMAKE_WATCOM_RUNTIME_LIBRARY.rst b/Help/variable/CMAKE_WATCOM_RUNTIME_LIBRARY.rst new file mode 100644 index 0000000..feb2a60 --- /dev/null +++ b/Help/variable/CMAKE_WATCOM_RUNTIME_LIBRARY.rst @@ -0,0 +1,36 @@ +CMAKE_WATCOM_RUNTIME_LIBRARY +---------------------------- + +.. versionadded:: 3.24 + +Select the Watcom runtime library for use by compilers targeting the Watcom ABI. +This variable is used to initialize the :prop_tgt:`WATCOM_RUNTIME_LIBRARY` +property on all targets as they are created. It is also propagated by +calls to the :command:`try_compile` command into the test project. + +The allowed values are: + +.. include:: ../prop_tgt/WATCOM_RUNTIME_LIBRARY-VALUES.txt + +Use :manual:`generator expressions <cmake-generator-expressions(7)>` to +support per-configuration specification. + +For example, the code: + +.. code-block:: cmake + + set(CMAKE_WATCOM_RUNTIME_LIBRARY "MultiThreaded") + +selects for all following targets a multi-threaded statically-linked runtime +library. + +If this variable is not set then the :prop_tgt:`WATCOM_RUNTIME_LIBRARY` target +property will not be set automatically. If that property is not set then +CMake uses the default value ``MultiThreadedDLL`` on Windows and +``SingleThreaded`` on other platforms to select a Watcom runtime library. + +.. note:: + + This variable has effect only when policy :policy:`CMP0136` is set to ``NEW`` + prior to the first :command:`project` or :command:`enable_language` command + that enables a language using a compiler targeting the Watcom ABI. diff --git a/Help/variable/CMAKE_XCODE_XCCONFIG.rst b/Help/variable/CMAKE_XCODE_XCCONFIG.rst new file mode 100644 index 0000000..6b1ef30 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_XCCONFIG.rst @@ -0,0 +1,14 @@ +CMAKE_XCODE_XCCONFIG +-------------------- + +.. versionadded:: 3.24 + +If set, the :generator:`Xcode` generator will register the specified +file as a global XCConfig file. For target-level XCConfig files see +the :prop_tgt:`XCODE_XCCONFIG` target property. + +This feature is intended to ease migration from native Xcode projects +to CMake projects. + +Contents of ``CMAKE_XCODE_XCCONFIG`` may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/variable/CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE.rst b/Help/variable/CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE.rst index 7e7d431..007cfe0 100644 --- a/Help/variable/CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE.rst +++ b/Help/variable/CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE.rst @@ -3,7 +3,8 @@ CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE When saving a failing test's output, this is the maximum size, in bytes, that will be collected by the :command:`ctest_test` command. Defaults to 307200 -(300 KiB). +(300 KiB). See :variable:`CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION` for possible +truncation modes. If a test's output contains the literal string "CTEST_FULL_OUTPUT", the output will not be truncated and may exceed the maximum size. diff --git a/Help/variable/CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE.rst b/Help/variable/CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE.rst index 64367f9..8545fc4 100644 --- a/Help/variable/CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE.rst +++ b/Help/variable/CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE.rst @@ -3,7 +3,8 @@ CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE When saving a passing test's output, this is the maximum size, in bytes, that will be collected by the :command:`ctest_test` command. Defaults to 1024 -(1 KiB). +(1 KiB). See :variable:`CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION` for possible +truncation modes. If a test's output contains the literal string "CTEST_FULL_OUTPUT", the output will not be truncated and may exceed the maximum size. diff --git a/Help/variable/CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION.rst b/Help/variable/CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION.rst new file mode 100644 index 0000000..2d4219e --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION.rst @@ -0,0 +1,12 @@ +CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION +----------------------------------- + +.. versionadded:: 3.24 + +Set the test output truncation mode in case a maximum size is configured +via the :variable:`CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE` or +:variable:`CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE` variables. +By default the ``tail`` of the output will be truncated. Other possible +values are ``middle`` and ``head``. + +.. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/ENV.rst b/Help/variable/ENV.rst index 2b43934..6791853 100644 --- a/Help/variable/ENV.rst +++ b/Help/variable/ENV.rst @@ -8,5 +8,6 @@ Use the syntax ``$ENV{VAR}`` to read environment variable ``VAR``. To test whether an environment variable is defined, use the signature ``if(DEFINED ENV{<name>})`` of the :command:`if` command. -See the :command:`set` and :command:`unset` commands to see how to -write or remove environment variables. +For general information on environment variables, see the +:ref:`Environment Variables <CMake Language Environment Variables>` +section in the :manual:`cmake-language(7)` manual. diff --git a/Help/variable/LINK_GROUP_PREDEFINED_FEATURES.txt b/Help/variable/LINK_GROUP_PREDEFINED_FEATURES.txt new file mode 100644 index 0000000..557886e --- /dev/null +++ b/Help/variable/LINK_GROUP_PREDEFINED_FEATURES.txt @@ -0,0 +1,22 @@ +``RESCAN`` + Some linkers are single-pass only. For such linkers, circular references + between libraries typically result in unresolved symbols. This feature + instructs the linker to search the specified static libraries repeatedly + until no new undefined references are created. + + Normally, a static library is searched only once in the order that it is + specified on the command line. If a symbol in that library is needed to + resolve an undefined symbol referred to by an object in a library that + appears later on the command line, the linker would not be able to resolve + that reference. By grouping the static libraries with the ``RESCAN`` + feature, they will all be searched repeatedly until all possible references + are resolved. This will use linker options like ``--start-group`` and + ``--end-group``, or on SunOS, ``-z rescan-start`` and ``-z rescan-end``. + + Using this feature has a significant performance cost. It is best to use it + only when there are unavoidable circular references between two or more + static libraries. + + This feature is available when using toolchains that target Linux, BSD, and + SunOS. It can also be used when targeting Windows platforms if the GNU + toolchain is used. diff --git a/Help/variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt b/Help/variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt new file mode 100644 index 0000000..8ae6c57 --- /dev/null +++ b/Help/variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt @@ -0,0 +1,96 @@ +``DEFAULT`` + This feature corresponds to standard linking, essentially equivalent to + using no feature at all. It is typically only used with the + :prop_tgt:`LINK_LIBRARY_OVERRIDE` and + :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target properties. + +``WHOLE_ARCHIVE`` + Force inclusion of all members of a static library. This feature is only + supported for the following platforms, with limitations as noted: + + * Linux. + * All BSD variants. + * SunOS. + * All Apple variants. The library must be specified as a CMake target name, + a library file name (such as ``libfoo.a``), or a library file path (such as + ``/path/to/libfoo.a``). Due to a limitation of the Apple linker, it + cannot be specified as a plain library name like ``foo``, where ``foo`` + is not a CMake target. + * Windows. When using a MSVC or MSVC-like toolchain, the MSVC version must + be greater than 1900. + * Cygwin. + * MSYS. + +``FRAMEWORK`` + This option tells the linker to search for the specified framework using + the ``-framework`` linker option. It can only be used on Apple platforms, + and only with a linker that understands the option used (i.e. the linker + provided with Xcode, or one compatible with it). + + The framework can be specified as a CMake framework target, a bare framework + name, or a file path. If a target is given, that target must have the + :prop_tgt:`FRAMEWORK` target property set to true. For a file path, if it + contains a directory part, that directory will be added as a framework + search path. + + .. code-block:: cmake + + add_library(lib SHARED ...) + target_link_libraries(lib PRIVATE "$<LINK_LIBRARY:FRAMEWORK,/path/to/my_framework>") + + # The constructed linker command line will contain: + # -F/path/to -framework my_framework + + File paths must conform to one of the following patterns (``*`` is a + wildcard, and optional parts are shown as ``[...]``): + + * ``[/path/to/]FwName[.framework]`` + * ``[/path/to/]FwName.framework/FwName`` + * ``[/path/to/]FwName.framework/Versions/*/FwName`` + + Note that CMake recognizes and automatically handles framework targets, + even without using the ``$<LINK_LIBRARY:FRAMEWORK,...>`` expression. + The generator expression can still be used with a CMake target if the + project wants to be explicit about it, but it is not required to do so. + The linker command line may have some differences between using the + generator expression or not, but the final result should be the same. + On the other hand, if a file path is given, CMake will recognize some paths + automatically, but not all cases. The project may want to use + ``$<LINK_LIBRARY:FRAMEWORK,...>`` for file paths so that the expected + behavior is clear. + +``NEEDED_FRAMEWORK`` + This is similar to the ``FRAMEWORK`` feature, except it forces the linker + to link with the framework even if no symbols are used from it. It uses + the ``-needed_framework`` option and has the same linker constraints as + ``FRAMEWORK``. + +``REEXPORT_FRAMEWORK`` + This is similar to the ``FRAMEWORK`` feature, except it tells the linker + that the framework should be available to clients linking to the library + being created. It uses the ``-reexport_framework`` option and has the + same linker constraints as ``FRAMEWORK``. + +``WEAK_FRAMEWORK`` + This is similar to the ``FRAMEWORK`` feature, except it forces the linker + to mark the framework and all references to it as weak imports. It uses + the ``-weak_framework`` option and has the same linker constraints as + ``FRAMEWORK``. + +``NEEDED_LIBRARY`` + This is similar to the ``NEEDED_FRAMEWORK`` feature, except it is for use + with non-framework targets or libraries (Apple platforms only). + It uses the ``-needed_library`` or ``-needed-l`` option as appropriate, + and has the same linker constraints as ``NEEDED_FRAMEWORK``. + +``REEXPORT_LIBRARY`` + This is similar to the ``REEXPORT_FRAMEWORK`` feature, except it is for use + with non-framework targets or libraries (Apple platforms only). + It uses the ``-reexport_library`` or ``-reexport-l`` option as appropriate, + and has the same linker constraints as ``REEXPORT_FRAMEWORK``. + +``WEAK_LIBRARY`` + This is similar to the ``WEAK_FRAMEWORK`` feature, except it is for use + with non-framework targets or libraries (Apple platforms only). + It uses the ``-weak_library`` or ``-weak-l`` option as appropriate, + and has the same linker constraints as ``WEAK_FRAMEWORK``. diff --git a/Help/variable/PROJECT-NAME_IS_TOP_LEVEL.rst b/Help/variable/PROJECT-NAME_IS_TOP_LEVEL.rst index 6718ecf..ca3a769 100644 --- a/Help/variable/PROJECT-NAME_IS_TOP_LEVEL.rst +++ b/Help/variable/PROJECT-NAME_IS_TOP_LEVEL.rst @@ -13,9 +13,16 @@ the current directory scope or above, see the The variable value will be true in: * the top-level directory of the project -* the top-level directory of an external project added by :module:`ExternalProject` +* the top-level directory of an external project added by + :module:`ExternalProject` +* a directory added by :command:`add_subdirectory` that does not also contain + a :command:`project` call +* a directory added by :command:`FetchContent_MakeAvailable`, + if the fetched content does not contain a :command:`project` call The variable value will be false in: -* a directory added by :command:`add_subdirectory` -* a directory added by :module:`FetchContent` +* a directory added by :command:`add_subdirectory` that also contains + a :command:`project` call +* a directory added by :command:`FetchContent_MakeAvailable`, + if the fetched content contains a :command:`project` call diff --git a/Help/variable/PROJECT_IS_TOP_LEVEL.rst b/Help/variable/PROJECT_IS_TOP_LEVEL.rst index 7e40704..871dfdb 100644 --- a/Help/variable/PROJECT_IS_TOP_LEVEL.rst +++ b/Help/variable/PROJECT_IS_TOP_LEVEL.rst @@ -24,9 +24,16 @@ options: The variable value will be true in: * the top-level directory of the project -* the top-level directory of an external project added by :module:`ExternalProject` +* the top-level directory of an external project added by + :module:`ExternalProject` +* a directory added by :command:`add_subdirectory` that does not also contain + a :command:`project` call +* a directory added by :command:`FetchContent_MakeAvailable`, + if the fetched content does not contain a :command:`project` call The variable value will be false in: -* a directory added by :command:`add_subdirectory` -* a directory added by :module:`FetchContent` +* a directory added by :command:`add_subdirectory` that also contains + a :command:`project` call +* a directory added by :command:`FetchContent_MakeAvailable`, + if the fetched content contains a :command:`project` call |