1CMP0060
2-------
3
4.. versionadded:: 3.3
5
6Link libraries by full path even in implicit directories.
7
8Policy :policy:`CMP0003` was introduced with the intention of always
9linking library files by full path when a full path is given to the
10:command:`target_link_libraries` command.  However, on some platforms
11(e.g. HP-UX) the compiler front-end adds alternative library search paths
12for the current architecture (e.g. ``/usr/lib/<arch>`` has alternatives
13to libraries in ``/usr/lib`` for the current architecture).
14On such platforms the :command:`find_library` may find a library such as
15``/usr/lib/libfoo.so`` that does not belong to the current architecture.
16
17Prior to policy :policy:`CMP0003` projects would still build in such
18cases because the incorrect library path would be converted to ``-lfoo``
19on the link line and the linker would find the proper library in the
20arch-specific search path provided by the compiler front-end implicitly.
21At the time we chose to remain compatible with such projects by always
22converting library files found in implicit link directories to ``-lfoo``
23flags to ask the linker to search for them.  This approach allowed existing
24projects to continue to build while still linking to libraries outside
25implicit link directories via full path (such as those in the build tree).
26
27CMake does allow projects to override this behavior by using an
28:ref:`IMPORTED library target <Imported Targets>` with its
29:prop_tgt:`IMPORTED_LOCATION` property set to the desired full path to
30a library file.  In fact, many :ref:`Find Modules` are learning to provide
31:ref:`Imported Targets` instead of just the traditional ``Foo_LIBRARIES``
32variable listing library files.  However, this makes the link line
33generated for a library found by a Find Module depend on whether it
34is linked through an imported target or not, which is inconsistent.
35Furthermore, this behavior has been a source of confusion because the
36generated link line for a library file depends on its location.  It is
37also problematic for projects trying to link statically because flags
38like ``-Wl,-Bstatic -lfoo -Wl,-Bdynamic`` may be used to help the linker
39select ``libfoo.a`` instead of ``libfoo.so`` but then leak dynamic linking
40to following libraries.  (See the :prop_tgt:`LINK_SEARCH_END_STATIC`
41target property for a solution typically used for that problem.)
42
43When the special case for libraries in implicit link directories was first
44introduced the list of implicit link directories was simply hard-coded
45(e.g. ``/lib``, ``/usr/lib``, and a few others).  Since that time, CMake
46has learned to detect the implicit link directories used by the compiler
47front-end.  If necessary, the :command:`find_library` command could be
48taught to use this information to help find libraries of the proper
49architecture.
50
51For these reasons, CMake 3.3 and above prefer to drop the special case
52and link libraries by full path even when they are in implicit link
53directories.  Policy ``CMP0060`` provides compatibility for existing
54projects.
55
56The ``OLD`` behavior for this policy is to ask the linker to search for
57libraries whose full paths are known to be in implicit link directories.
58The ``NEW`` behavior for this policy is to link libraries by full path even
59if they are in implicit link directories.
60
61This policy was introduced in CMake version 3.3.  Unlike most policies,
62CMake version |release| does *not* warn by default when this policy
63is not set and simply uses ``OLD`` behavior.  See documentation of the
64:variable:`CMAKE_POLICY_WARNING_CMP0060 <CMAKE_POLICY_WARNING_CMP<NNNN>>`
65variable to control the warning.
66
67.. include:: DEPRECATED.txt
68