diff options
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/command/target_link_libraries.rst | 16 | ||||
| -rw-r--r-- | Help/manual/cmake-policies.7.rst | 1 | ||||
| -rw-r--r-- | Help/policy/CMP0060.rst | 63 | ||||
| -rw-r--r-- | Help/release/dev/link-implicit-libs-full-path.rst | 6 | ||||
| -rw-r--r-- | Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst | 2 |
5 files changed, 83 insertions, 5 deletions
diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst index 393c8b4..d903d05 100644 --- a/Help/command/target_link_libraries.rst +++ b/Help/command/target_link_libraries.rst @@ -34,14 +34,20 @@ Each ``<item>`` may be: automatically be added in the build system to make sure the named library target is up-to-date before the ``<target>`` links. + If an imported library has the :prop_tgt:`IMPORTED_NO_SONAME` + target property set, CMake may ask the linker to search for + the library instead of using the full path + (e.g. ``/usr/lib/libfoo.so`` becomes ``-lfoo``). + * **A full path to a library file**: The generated link line will - normally preserve the full path to the file. However, there are - some cases where CMake must ask the linker to search for the library - (e.g. ``/usr/lib/libfoo.so`` becomes ``-lfoo``), such as when it - appears in a system library directory that the compiler front-end - may replace with an alternative. Either way, the buildsystem will + normally preserve the full path to the file. The buildsystem will have a dependency to re-link ``<target>`` if the library file changes. + There are some cases where CMake may ask the linker to search for + the library (e.g. ``/usr/lib/libfoo.so`` becomes ``-lfoo``), such + as when a shared library is detected to have no ``SONAME`` field. + See policy :policy:`CMP0060` for discussion of another case. + If the library file is in a Mac OSX framework, the ``Headers`` directory of the framework will also be processed as a :ref:`usage requirement <Target Usage Requirements>`. This has the same diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index d2960de..aff696d 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -117,3 +117,4 @@ All Policies /policy/CMP0057 /policy/CMP0058 /policy/CMP0059 + /policy/CMP0060 diff --git a/Help/policy/CMP0060.rst b/Help/policy/CMP0060.rst new file mode 100644 index 0000000..cc37b1b --- /dev/null +++ b/Help/policy/CMP0060.rst @@ -0,0 +1,63 @@ +CMP0060 +------- + +Link libraries by full path even in implicit directories. + +Policy :policy:`CMP0003` was introduced with the intention of always +linking library files by full path when a full path is given to the +:command:`target_link_libraries` command. However, on some platforms +(e.g. HP-UX) the compiler front-end adds alternative library search paths +for the current architecture (e.g. ``/usr/lib/<arch>`` has alternatives +to libraries in ``/usr/lib`` for the current architecture). +On such platforms the :command:`find_library` may find a library such as +``/usr/lib/libfoo.so`` that does not belong to the current architecture. + +Prior to policy :policy:`CMP0003` projects would still build in such +cases because the incorrect library path would be converted to ``-lfoo`` +on the link line and the linker would find the proper library in the +arch-specific search path provided by the compiler front-end implicitly. +At the time we chose to remain compatible with such projects by always +converting library files found in implicit link directories to ``-lfoo`` +flags to ask the linker to search for them. This approach allowed existing +projects to continue to build while still linking to libraries outside +implicit link directories via full path (such as those in the build tree). + +CMake does allow projects to override this behavior by using an +:ref:`IMPORTED library target <Imported Targets>` with its +:prop_tgt:`IMPORTED_LOCATION` property set to the desired full path to +a library file. In fact, many :ref:`Find Modules` are learning to provide +:ref:`Imported Targets` instead of just the traditional ``Foo_LIBRARIES`` +variable listing library files. However, this makes the link line +generated for a library found by a Find Module depend on whether it +is linked through an imported target or not, which is inconsistent. +Furthermore, this behavior has been a source of confusion because the +generated link line for a library file depends on its location. It is +also problematic for projects trying to link statically because flags +like ``-Wl,-Bstatic -lfoo -Wl,-Bdynamic`` may be used to help the linker +select ``libfoo.a`` instead of ``libfoo.so`` but then leak dynamic linking +to following libraries. (See the :prop_tgt:`LINK_SEARCH_END_STATIC` +target property for a solution typically used for that problem.) + +When the special case for libraries in implicit link directories was first +introduced the list of implicit link directories was simply hard-coded +(e.g. ``/lib``, ``/usr/lib``, and a few others). Since that time, CMake +has learned to detect the implicit link directories used by the compiler +front-end. If necessary, the :command:`find_library` command could be +taught to use this information to help find libraries of the proper +architecture. + +For these reasons, CMake 3.3 and above prefer to drop the special case +and link libraries by full path even when they are in implicit link +directories. Policy ``CMP0060`` provides compatibility for existing +projects. + +The OLD behavior for this policy is to ask the linker to search for +libraries whose full paths are known to be in implicit link directories. +The NEW behavior for this policy is to link libraries by full path even +if they are in implicit link directories. + +This policy was introduced in CMake version 3.3. Unlike most policies, +CMake version |release| does *not* warn by default when this policy +is not set and simply uses OLD behavior. See documentation of the +:variable:`CMAKE_POLICY_WARNING_CMP0060 <CMAKE_POLICY_WARNING_CMP<NNNN>>` +variable to control the warning. diff --git a/Help/release/dev/link-implicit-libs-full-path.rst b/Help/release/dev/link-implicit-libs-full-path.rst new file mode 100644 index 0000000..7ed7245 --- /dev/null +++ b/Help/release/dev/link-implicit-libs-full-path.rst @@ -0,0 +1,6 @@ +link-implicit-libs-full-path +---------------------------- + +* Linking to library files by a full path in an implicit linker search + directory (e.g. ``/usr/lib/libfoo.a``) no longer asks the linker to + search for the library (e.g. ``-lfoo``). See policy :policy:`CMP0060`. diff --git a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst index a83c807..092fe3e 100644 --- a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst +++ b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst @@ -11,6 +11,8 @@ warn by default: policy :policy:`CMP0047`. * ``CMAKE_POLICY_WARNING_CMP0056`` controls the warning for policy :policy:`CMP0056`. +* ``CMAKE_POLICY_WARNING_CMP0060`` controls the warning for + policy :policy:`CMP0060`. This variable should not be set by a project in CMake code. Project developers running CMake may set this variable in their cache to |