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. | |
.. include:: DEPRECATED.txt |