CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>¶
New in version 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 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
CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED
and
CMAKE_LINK_GROUP_USING_<FEATURE>
variable for the definition of
features independent from the link language.
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:
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 theCMAKE_<LANG>_LINKER_WRAPPER_FLAG
andCMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP
variables.For example,
"LINKER:-z,defs"
becomes-Xlinker -z -Xlinker defs
forClang
and-Wl,-z,defs
forGNU GCC
.The
LINKER:
prefix can be specified as part of aSHELL:
prefix expression.The
LINKER:
prefix supports, as an alternative syntax, specification of arguments using theSHELL:
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 theLINKER:
prefix is not supported.
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:
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
Predefined Features¶
CMake pre-defines some features of general interest:
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, onSunOS
,-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
, andSunOS
target platforms as well asWindows
whenGNU
toolchain is used.