This variable defines how to link a group of libraries for the specified
<FEATURE> when a
LINK_GROUP generator expression is used and
the link language for the target is
For this variable to have any effect, the associated
must be set to true.
CMAKE_LINK_GROUP_USING_<FEATURE> variable should be defined
instead for features that are independent of 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).
A group feature definition is a list that contains exactly two elements:
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.
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
-Xlinker -z -Xlinker defs for
LINKER: prefix can be specified as part of a
LINKER: prefix supports, as an alternative syntax, specification of
arguments using the
SHELL: prefix and space as separator. The previous
example then becomes
SHELL: prefix anywhere other than at the beginning of the
LINKER: prefix is not supported.
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.
if(CMAKE_C_COMPILER_ID STREQUAL "GNU" AND CMAKE_SYSTEM_NAME STREQUAL "Linux")
elseif(CMAKE_C_COMPILER_ID STREQUAL "SunPro" AND CMAKE_SYSTEM_NAME STREQUAL "SunOS")
# feature not yet supported for the other environments
add_library(lib1 STATIC ...)
add_library(lib2 SHARED ...)
target_link_libraries(lib2 PRIVATE "$<LINK_GROUP:cross_refs,lib1,external>")
target_link_libraries(lib2 PRIVATE lib1 external)
CMake will generate the following linker command line fragments when linking
-Wl,--start-group /path/to/lib1.a -lexternal -Wl,--end-group
-Wl,-z,rescan-start /path/to/lib1.a -lexternal -Wl,-z,rescan-end
The following built-in group features are pre-defined by CMake:
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
feature, they will all be searched repeatedly until all possible references
are resolved. This will use linker options like
--end-group, or on SunOS,
-z rescan-start and
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
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.