CMAKE_LINK_GROUP_USING_<FEATURE>

New in version 3.24.

This variable defines how to link a group of libraries for the specified <FEATURE> when a LINK_GROUP generator expression is used. Both of the following conditions must be met for this variable to have any effect:

• The associated CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED variable must be set to true.

• There is no language-specific definition for the same <FEATURE>. This means CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED cannot be true for the link language used by the target for which the LINK_GROUP generator expression is evaluated.

The CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE> variable should be defined instead for features that are dependent on the link language.

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.

To pass options to the linker tool, each compiler driver has its own syntax. The LINKER: prefix and , separator can be used to specify, in a portable way, options to pass to the linker tool. LINKER: is replaced by the appropriate driver option and , by the appropriate driver separator. The driver prefix and driver separator are given by the values of the CMAKE_<LANG>_LINKER_WRAPPER_FLAG and CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP variables.

For example, "LINKER:-z,defs" becomes -Xlinker -z -Xlinker defs for Clang and -Wl,-z,defs for GNU GCC.

The LINKER: prefix can be specified as part of a SHELL: prefix expression.

The LINKER: prefix supports, as an alternative syntax, specification of arguments using the SHELL: prefix and space as separator. The previous example then becomes "LINKER:SHELL:-z defs".

Note

Specifying the SHELL: prefix anywhere other than at the beginning of the LINKER: prefix is not supported.

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.

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:

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.