diff options
| author | Brad King <brad.king@kitware.com> | 2021-04-02 15:57:41 (GMT) |
|---|---|---|
| committer | Brad King <brad.king@kitware.com> | 2021-04-02 16:12:28 (GMT) |
| commit | 4d6e899578a9bb13635b0b46a37b7e9ab4cdf5e0 (patch) | |
| tree | 085bedf7da10b19211901f367b84dadf687c7a5a | |
| parent | 31a31edc21c7305b1099366381a0172849605fba (diff) | |
| download | CMake-4d6e899578a9bb13635b0b46a37b7e9ab4cdf5e0.zip CMake-4d6e899578a9bb13635b0b46a37b7e9ab4cdf5e0.tar.gz CMake-4d6e899578a9bb13635b0b46a37b7e9ab4cdf5e0.tar.bz2 | |
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
| -rw-r--r-- | Help/command/add_library.rst | 24 |
1 files 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 ``<type>`` 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_<CONFIG>`) 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_<CONFIG>`) - 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_<CONFIG>`) 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 |