From 4d6e899578a9bb13635b0b46a37b7e9ab4cdf5e0 Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 2 Apr 2021 11:57:41 -0400 Subject: Help: Document in add_library how to import libraries with SONAME When using `add_library` to create an `IMPORTED` library target, there are a few target properties that are essential to correctly tell CMake about the library file. We already cover `IMPORTED_LOCATION` and `IMPORTED_IMPLIB`. Add `IMPORTED_SONAME` and `IMPORTED_NO_SONAME`, which are important in certain cases. Fixes: #22016 --- Help/command/add_library.rst | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst index d3fbdcf..dfc6500 100644 --- a/Help/command/add_library.rst +++ b/Help/command/add_library.rst @@ -189,12 +189,24 @@ The ```` must be one of: References a library file located outside the project. The :prop_tgt:`IMPORTED_LOCATION` target property (or its per-configuration variant :prop_tgt:`IMPORTED_LOCATION_`) specifies the - location of the main library file on disk. In the case of a ``SHARED`` - library on Windows, the :prop_tgt:`IMPORTED_IMPLIB` target property - (or its per-configuration variant :prop_tgt:`IMPORTED_IMPLIB_`) - specifies the location of the DLL import library file (``.lib`` or - ``.dll.a``) on disk, and the ``IMPORTED_LOCATION`` is the location of - the ``.dll`` runtime library (and is optional). + location of the main library file on disk: + + * For a ``SHARED`` library on most non-Windows platforms, the main library + file is the ``.so`` or ``.dylib`` file used by both linkers and dynamic + loaders. If the referenced library file has a ``SONAME`` (or on macOS, + has a ``LC_ID_DYLIB`` starting in ``@rpath/``), the value of that field + should be set in the :prop_tgt:`IMPORTED_SONAME` target property. + If the referenced library file does not have a ``SONAME``, but the + platform supports it, then the :prop_tgt:`IMPORTED_NO_SONAME` target + property should be set. + + * For a ``SHARED`` library on Windows, the :prop_tgt:`IMPORTED_IMPLIB` + target property (or its per-configuration variant + :prop_tgt:`IMPORTED_IMPLIB_`) specifies the location of the + DLL import library file (``.lib`` or ``.dll.a``) on disk, and the + ``IMPORTED_LOCATION`` is the location of the ``.dll`` runtime + library (and is optional). + Additional usage requirements may be specified in ``INTERFACE_*`` properties. An ``UNKNOWN`` library type is typically only used in the implementation of -- cgit v0.12