targetLinkLibrariesWithDynamicLookup

Public Functions

The following functions are defined:

target_link_libraries_with_dynamic_lookup(<Target> [<Libraries>])

Useful to “weakly” link a loadable module. For example, it should be used when compiling a loadable module when the symbols should be resolve from the run-time environment where the module is loaded, and not a specific system library.

Like proper linking, except that the given <Libraries> are not necessarily linked. Instead, the <Target> is produced in a manner that allows for symbols unresolved within it to be resolved at runtime, presumably by the given <Libraries>. If such a target can be produced, the provided <Libraries> are not actually linked.

It links a library to a target such that the symbols are resolved at run-time not link-time.

The linker is checked to see if it supports undefined symbols when linking a shared library. If it does then the library is not linked when specified with this function.

On platforms that do not support weak-linking, this function works just like target_link_libraries.

Note

For OSX it uses undefined dynamic_lookup. This is similar to using -shared on Linux where undefined symbols are ignored.

For more details, see blog from Tim D. Smith.

check_dynamic_lookup

Check if the linker requires a command line flag to allow leaving symbols unresolved when producing a target of type <TargetType> that is weakly-linked against a dependency of type <LibType>.

<TargetType>
can be one of “STATIC”, “SHARED”, “MODULE”, or “EXE”.
<LibType>
can be one of “STATIC”, “SHARED”, or “MODULE”.

Long signature:

check_dynamic_lookup(<TargetType>
                     <LibType>
                     <ResultVar>
                     [<LinkFlagsVar>])

Short signature:

check_dynamic_lookup(<ResultVar>) # <TargetType> set to "MODULE"
                                  # <LibType> set to "SHARED"

The result is cached between invocations and recomputed only when the value of CMake’s linker flag list changes; CMAKE_STATIC_LINKER_FLAGS if <TargetType> is “STATIC”, and CMAKE_SHARED_LINKER_FLAGS otherwise.

Defined variables:

<ResultVar>
Whether the current C toolchain supports weak-linking for target binaries of type <TargetType> that are weakly-linked against a dependency target of type <LibType>.
<LinkFlagsVar>
List of flags to add to the linker command to produce a working target binary of type <TargetType> that is weakly-linked against a dependency target of type <LibType>.
HAS_DYNAMIC_LOOKUP_<TargetType>_<LibType>
Cached, global alias for <ResultVar>
DYNAMIC_LOOKUP_FLAGS_<TargetType>_<LibType>
Cached, global alias for <LinkFlagsVar>

Private Functions

The following private functions are defined:

Warning

These functions are not part of the scikit-build API. They exist purely as an implementation detail and may change from version to version without notice, or even be removed.

We mean it.

_get_target_type
_get_target_type(<ResultVar> <Target>)

Shorthand for querying an abbreviated version of the target type of the given <Target>.

<ResultVar> is set to:

  • “STATIC” for a STATIC_LIBRARY,
  • “SHARED” for a SHARED_LIBRARY,
  • “MODULE” for a MODULE_LIBRARY,
  • and “EXE” for an EXECUTABLE.

Defined variables:

<ResultVar>
The abbreviated version of the <Target>’s type.
_test_weak_link_project(<TargetType>
                        <LibType>
                        <ResultVar>
                        <LinkFlagsVar>)

Attempt to compile and run a test project where a target of type <TargetType> is weakly-linked against a dependency of type <LibType>:

  • <TargetType> can be one of “STATIC”, “SHARED”, “MODULE”, or “EXE”.
  • <LibType> can be one of “STATIC”, “SHARED”, or “MODULE”.

Defined variables:

<ResultVar>
Whether the current C toolchain can produce a working target binary of type <TargetType> that is weakly-linked against a dependency target of type <LibType>.
<LinkFlagsVar>
List of flags to add to the linker command to produce a working target binary of type <TargetType> that is weakly-linked against a dependency target of type <LibType>.