1CMP0003
2-------
3
4Libraries linked via full path no longer produce linker search paths.
5
6This policy affects how libraries whose full paths are NOT known are
7found at link time, but was created due to a change in how CMake deals
8with libraries whose full paths are known.  Consider the code
9
10::
11
12  target_link_libraries(myexe /path/to/libA.so)
13
14CMake 2.4 and below implemented linking to libraries whose full paths
15are known by splitting them on the link line into separate components
16consisting of the linker search path and the library name.  The
17example code might have produced something like
18
19::
20
21  ... -L/path/to -lA ...
22
23in order to link to library A.  An analysis was performed to order
24multiple link directories such that the linker would find library A in
25the desired location, but there are cases in which this does not work.
26CMake versions 2.6 and above use the more reliable approach of passing
27the full path to libraries directly to the linker in most cases.  The
28example code now produces something like
29
30::
31
32  ... /path/to/libA.so ....
33
34Unfortunately this change can break code like
35
36::
37
38  target_link_libraries(myexe /path/to/libA.so B)
39
40where ``B`` is meant to find ``/path/to/libB.so``.  This code is wrong
41because the user is asking the linker to find library B but has not
42provided a linker search path (which may be added with the
43link_directories command).  However, with the old linking
44implementation the code would work accidentally because the linker
45search path added for library A allowed library B to be found.
46
47In order to support projects depending on linker search paths added by
48linking to libraries with known full paths, the ``OLD`` behavior for this
49policy will add the linker search paths even though they are not
50needed for their own libraries.  When this policy is set to ``OLD``, CMake
51will produce a link line such as
52
53::
54
55  ... -L/path/to /path/to/libA.so -lB ...
56
57which will allow library B to be found as it was previously.  When
58this policy is set to NEW, CMake will produce a link line such as
59
60::
61
62  ... /path/to/libA.so -lB ...
63
64which more accurately matches what the project specified.
65
66The setting for this policy used when generating the link line is that
67in effect when the target is created by an add_executable or
68add_library command.  For the example described above, the code
69
70::
71
72  cmake_policy(SET CMP0003 OLD) # or cmake_policy(VERSION 2.4)
73  add_executable(myexe myexe.c)
74  target_link_libraries(myexe /path/to/libA.so B)
75
76will work and suppress the warning for this policy.  It may also be
77updated to work with the corrected linking approach:
78
79::
80
81  cmake_policy(SET CMP0003 NEW) # or cmake_policy(VERSION 2.6)
82  link_directories(/path/to) # needed to find library B
83  add_executable(myexe myexe.c)
84  target_link_libraries(myexe /path/to/libA.so B)
85
86Even better, library B may be specified with a full path:
87
88::
89
90  add_executable(myexe myexe.c)
91  target_link_libraries(myexe /path/to/libA.so /path/to/libB.so)
92
93When all items on the link line have known paths CMake does not check
94this policy so it has no effect.
95
96Note that the warning for this policy will be issued for at most one
97target.  This avoids flooding users with messages for every target
98when setting the policy once will probably fix all targets.
99
100This policy was introduced in CMake version 2.6.0.  CMake version
101|release| warns when the policy is not set and uses ``OLD`` behavior.  Use
102the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
103
104.. include:: DEPRECATED.txt
105