diff options
Diffstat (limited to 'Help/variable')
18 files changed, 529 insertions, 2 deletions
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_FIND_PACKAGE_TARGETS_GLOBAL.rst b/Help/variable/CMAKE_FIND_PACKAGE_TARGETS_GLOBAL.rst new file mode 100644 index 0000000..58efccf --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_TARGETS_GLOBAL.rst @@ -0,0 +1,10 @@ +CMAKE_FIND_PACKAGE_TARGETS_GLOBAL +--------------------------------- + +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_LANG_LINK_GROUP_USING_FEATURE.rst b/Help/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE.rst new file mode 100644 index 0000000..f2ef843 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE.rst @@ -0,0 +1,27 @@ +CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE> +--------------------------------------- + +.. versionadded:: 3.24 + +This variable defines, for the specified ``<FEATURE>`` and the linker language +``<LANG>``, the expression expected by the linker when libraries are specified +using :genex:`LINK_GROUP` generator expression. + +.. note:: + + * Feature names can contain Latin letters, digits and undercores. + * Feature names defined in all uppercase are reserved to CMake. + +See also the associated variable +:variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED` and +:variable:`CMAKE_LINK_GROUP_USING_<FEATURE>` variable for the definition of +features independent from the link language. + +.. include:: CMAKE_LINK_GROUP_USING_FEATURE.txt + +Predefined Features +^^^^^^^^^^^^^^^^^^^ + +CMake pre-defines some features of general interest: + +.. include:: LINK_GROUP_PREDEFINED_FEATURES.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..533eee7 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE_SUPPORTED.rst @@ -0,0 +1,13 @@ +CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED +------------------------------------------------- + +.. versionadded:: 3.24 + +Set to ``TRUE`` if the ``<FEATURE>``, as defined by variable +:variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>`, is supported for the +linker language ``<LANG>``. + +.. note:: + + This variable is evaluated before the more generic variable + :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>_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..220ae99 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE.rst @@ -0,0 +1,27 @@ +CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE> +----------------------------------------- + +.. versionadded:: 3.24 + +This variable defines, for the specified ``<FEATURE>`` and the linker language +``<LANG>``, the expression expected by the linker when libraries are specified +using :genex:`LINK_LIBRARY` generator expression. + +.. note:: + + * Feature names can contain Latin letters, digits and undercores. + * Feature names defined in all uppercase are reserved to CMake. + +See also the associated variable +:variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` and +:variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variable for the definition of +features independent from the link language. + +.. include:: CMAKE_LINK_LIBRARY_USING_FEATURE.txt + +Predefined Features +^^^^^^^^^^^^^^^^^^^ + +CMake pre-defines some features of general interest: + +.. include:: LINK_LIBRARY_PREDEFINED_FEATURES.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..692c099 --- /dev/null +++ b/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE.rst @@ -0,0 +1,33 @@ +CMAKE_LINK_GROUP_USING_<FEATURE> +-------------------------------- + +.. versionadded:: 3.24 + +This variable defines, for the specified ``<FEATURE>``, the expression expected +by the linker when libraries are specified using :genex:`LINK_GROUP` generator +expression. + +.. note:: + + * Feature names can contain Latin letters, digits and undercores. + * Feature names defined in all uppercase are reserved to CMake. + +See also the associated variable +:variable:`CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED` and +:variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>` variable for the definition +of features dependent from the link language. + +This variable will be used by :genex:`LINK_GROUP` generator expression if, +for the linker language, the variable +:variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED` is not defined +and the variable :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED` is +``TRUE``.. + +.. include:: CMAKE_LINK_GROUP_USING_FEATURE.txt + +Predefined Features +^^^^^^^^^^^^^^^^^^^ + +CMake pre-defines some features of general interest: + +.. include:: LINK_GROUP_PREDEFINED_FEATURES.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..ecd9cb5 --- /dev/null +++ b/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE.txt @@ -0,0 +1,54 @@ + +It must contain two elements. + +:: + + <PREFIX> <SUFFIX> + +``<PREFIX>`` and ``<SUFFIX>`` will be used to encapsulate the list of +libraries. + +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 common need is the capability to search repeatedly in a group of static +libraries until no new undefined references are created. This capability is +offered by different environments but with a specific syntax: + +.. 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(lib3 SHARED ...) + if(CMAKE_C_LINK_GROUP_USING_cross_refs_SUPPORTED) + target_link_libraries(lib3 PRIVATE "$<LINK_GROUP:cross_refs,lib1,external>") + else() + target_link_libraries(lib3 PRIVATE lib1 external) + endif() + +CMake will generate the following link expressions: + +* ``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`` 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..318892f --- /dev/null +++ b/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE_SUPPORTED.rst @@ -0,0 +1,13 @@ +CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED +------------------------------------------ + +.. versionadded:: 3.24 + +Set to ``TRUE`` if the ``<FEATURE>``, as defined by variable +:variable:`CMAKE_LINK_GROUP_USING_<FEATURE>`, is supported regardless the +linker language. + +.. note:: + + This variable is evaluated if, and only if, the variable + :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED` is not defined. 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..9f1cede --- /dev/null +++ b/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.rst @@ -0,0 +1,33 @@ +CMAKE_LINK_LIBRARY_USING_<FEATURE> +---------------------------------- + +.. versionadded:: 3.24 + +This variable defines, for the specified ``FEATURE``, the expression expected +by the linker, regardless the linker language, when libraries are specified +using :genex:`LINK_LIBRARY` generator expression. + +.. note:: + + * Feature names can contain Latin letters, digits and undercores. + * Feature names defined in all uppercase are reserved to CMake. + +See also the associated variable +:variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` and +:variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` variable for the +definition of features dependent from the link language. + +This variable will be used by :genex:`LINK_LIBRARY` generator expression if, +for the linker language, the variable +:variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` is not defined +and the variable :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` is +``TRUE``. + +.. include:: CMAKE_LINK_LIBRARY_USING_FEATURE.txt + +Predefined Features +^^^^^^^^^^^^^^^^^^^ + +CMake pre-defines some features of general interest: + +.. include:: LINK_LIBRARY_PREDEFINED_FEATURES.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..ec293d3 --- /dev/null +++ b/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.txt @@ -0,0 +1,112 @@ + +It can contain one or three elements. + +:: + + [<PREFIX>] <LIBRARY_EXPRESSION> [<SUFFIX>] + +When ``<PREFIX>`` and/or ``<SUFFIX>`` are specified, they encapsulate the list +of libraries. + +.. note:: + + Even if ``<PREFIX>`` and ``<SUFFIX>`` are specified, there is not guarantee + that the list of specified libraries, as part of :genex:`LINK_LIBRARY` + generator expression, will be kept grouped. So, constructs like + ``start-group`` and ``end-group``, as supported by ``GNU ld``, cannot be + used. + +``<LIBRARY_EXPRESSION>`` is used to specify the decoration for each +library. For that purpose, the patterns ``<LIBRARY>``, ``<LINK_ITEM>``, and +``<LIB_ITEM>`` are available: + +* ``<LIBRARY>`` is expanded to the library as computed by CMake. +* ``<LINK_ITEM>`` is expanded to the same expression as if the library was + specified in the standard way. +* ``<LIB_ITEM>`` is equivalent to ``<LIBRARY>`` for CMake targets and is + expanded to the item specified by the user for external libraries. + +Moreover, it is possible to have different decorations for paths (CMake targets +and external libraries specified with absolute paths) and other items specified +by name. For that purpose, ``PATH{}`` and ``NAME{}`` wrappers can be used. + +For all three elements of this variable, 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 the capability to load a whole static library. This capability +is offered by various environments but with a specific syntax: + +.. 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) + target_link_libraries(lib2 PRIVATE + "$<LINK_LIBRARY:load_archive,lib1,$<IF:$<LINK_LANG_AND_ID:C,Clang>,libexternal.a,external>>") + else() + target_link_libraries(lib2 PRIVATE lib1 external) + endif() + +CMake will generate the following link expressions: + +* ``Clang``: ``-force_load /path/to/lib1.a -force_load libexternal.a`` +* ``GNU``: ``-Wl,--whole-archive /path/to/lib1.a -lexternal -Wl,--no-whole-archive`` +* ``MSVC``: ``/WHOLEARCHIVE:/path/to/lib1.lib /WHOLEARCHIVE:external.lib`` + +CMake will ensure, when possible, that ``<PREFIX>`` and ``<SUFFIX>`` are +not repeated for each library. + +In case of ``Clang``, the pattern ``<LIB_ITEM>`` is used because we need to +specify the library as defined by the user, not the name computed by CMake +(in that case ``external``). + +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), but different flags must be used for a +library specified by path and by name. This constraint by be solved by using +``PATH{}`` and ``NAME{}`` wrappers: + +.. 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 link expression: +``-weak_library /path/to/lib -Xlinker -weak-lexternal`` 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_VERIFY_HEADER_SETS.rst b/Help/variable/CMAKE_VERIFY_HEADER_SETS.rst new file mode 100644 index 0000000..8bd618a --- /dev/null +++ b/Help/variable/CMAKE_VERIFY_HEADER_SETS.rst @@ -0,0 +1,17 @@ +CMAKE_VERIFY_HEADER_SETS +------------------------ + +.. versionadded:: 3.24 + +This variable is used to initialize the :prop_tgt:`VERIFY_HEADER_SETS` +property of targets when they are created. Setting it to true +enables header set verification. + +Projects should not 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. + +By default, this variable is not set, which will result in header set +verification being disabled. 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/LINK_GROUP_PREDEFINED_FEATURES.txt b/Help/variable/LINK_GROUP_PREDEFINED_FEATURES.txt new file mode 100644 index 0000000..5f1a11b --- /dev/null +++ b/Help/variable/LINK_GROUP_PREDEFINED_FEATURES.txt @@ -0,0 +1,22 @@ +**Circular references with static libraries** + +Some linkers are one-pass only so to handle circular references between +static libraries, the following feature can be used: + +``RESCAN`` + The specified static libraries are searched repeatedly until no + new undefined references are created. Normally, an 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 an library that appears later on the command line, the linker would + not be able to resolve that reference. By grouping the static libraries, they + all be searched repeatedly until all possible references are resolved (use + linker options ``--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 on ``Linux``, ``BSD``, and ``SunOS`` target + platforms as well as ``Windows`` when ``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..e4fa0ed8 --- /dev/null +++ b/Help/variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt @@ -0,0 +1,88 @@ +**Features available in all environments** + +``DEFAULT`` + This feature enables default link expression. This is mainly + useful with :prop_tgt:`LINK_LIBRARY_OVERRIDE` and + :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target properties. + +**Features available for a subset of environments** + +``WHOLE_ARCHIVE`` + Force load of all members in a static library. + + Target platforms supported: all ``Apple`` variants, ``Linux``, all ``BSD`` + variants, ``SunOS``, ``Windows``, ``CYGWIN``, and ``MSYS``. + + Platform-specific notes: + + * On Apple platforms, 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``). It cannot be specified as a plain library name + (such as ``foo``, where ``foo`` is not CMake target), due to a limitation + in the Apple linker. + * On Windows platforms, for ``MSVC`` or MSVC-like toolchains, the version + must be greater than ``1900``. + +**Features available in Apple environments** + +It is assumed that the linker used is the one provided by `XCode` or is +compatible with it. + +Framework support + +``FRAMEWORK`` + This option tells the linker to search for the specified + framework (use linker option ``-framework``). +``NEEDED_FRAMEWORK`` + This is the same as the ``FRAMEWORK`` feature but means + to really link with the framework even if no symbols are used from it (use + linker option ``-needed_framework``). +``REEXPORT_FRAMEWORK`` + This is the same as the ``FRAMEWORK`` feature but + also specifies that all symbols in that framework should be available to + clients linking to the library being created (use linker option + ``-reexport_framework``). +``WEAK_FRAMEWORK`` + This is the same as the ``FRAMEWORK`` feature but forces + the framework and all references to it to be marked as weak imports (use + linker option ``-weak_framework``). + +Features for framework linking have a special handling in CMake: the +framework can be specified as a CMake framework target or file path. In the +first case, the target must have the :prop_tgt:`FRAMEWORK` target property set +as ``TRUE`` to enable framework handling. In the later case, if the path +includes a directory part, this one will be specified as framework search path +at link step. + +.. code-block:: cmake + + add_library(lib SHARED ...) + target_link_libraries(lib PRIVATE "$<LINK_LIBRARY:NEEDED_FRAMEWORK,/path/to/my_framework>") + + # at link step we will have: + # -F/path/to -needed_framework my_framework + +.. note:: + + The expected formats for the file path, with optional parts specified as + ``()?``, are: + + * (/path/to/)?FwName(.framework)? + * (/path/to/)?FwName.framework/FwName + * (/path/to/)?FwName.framework/Versions/\*/FwName + +Library support + +``NEEDED_LIBRARY`` + This is the same as specifying a link item (target or + library) but means to really link with the item even if no symbols are used + from it (use linker option ``-needed_library`` or ``-needed-l``). +``REEXPORT_LIBRARY`` + This is the same as specifying a link item (target or + library) but also specifies that all symbols in that item should be available + to clients linking to the library being created (use linker option + ``-reexport_library`` or ``-reexport-l``). +``WEAK_LIBRARY`` + This is the same as specifying a link item (target or + library) but forces the item and all references to it to be marked as weak + imports (use linker option ``-weak_library`` or ``-weak-l``). |