Navigation

  • index
  • next |
  • previous |
  • CMake »
  • 3.24.0-rc1 Documentation »
  • cmake-variables(7) »
  • CMAKE_LINK_GROUP_USING_<FEATURE>

CMAKE_LINK_GROUP_USING_<FEATURE>¶

New in version 3.24.

This variable defines, for the specified <FEATURE>, 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_LINK_GROUP_USING_<FEATURE>_SUPPORTED and CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE> variable for the definition of features dependent from the link language.

This variable will be used by LINK_GROUP generator expression if, for the linker language, the variable CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED is not defined and the variable CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED is TRUE..

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 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 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, 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.

Table of Contents

  • CMAKE_LINK_GROUP_USING_<FEATURE>
    • Examples
      • Solving cross-references between two static libraries
    • Predefined Features

Previous topic

CMAKE_LINK_DEPENDS_NO_SHARED

Next topic

CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED

This Page

  • Show Source

Quick search

Navigation

  • index
  • next |
  • previous |
  • CMake »
  • 3.24.0-rc1 Documentation »
  • cmake-variables(7) »
  • CMAKE_LINK_GROUP_USING_<FEATURE>
© Copyright 2000-2022 Kitware, Inc. and Contributors. Created using Sphinx 4.4.0.