Link libraries by full path even in implicit directories

When CMP0003 was first introduced we wanted to link all libraries by
full path.  However, some projects had problems on platforms where
find_library would find /usr/lib/libfoo.so when the project really
wanted to link to /usr/lib/<arch>/libfoo.so and had been working by
accident because pre-CMP0003 behavior used -lfoo to link.

We first tried to address that in commit v2.6.0~440 (Teach find_library
to avoid returning library paths in system directories, 2008-01-23) by
returning just "foo" for libraries in implicit link directories.  This
caused problems for projects expecting find_library to always return a
full path.  We ended up using the solution in commit v2.6.0~366 (...
switch library paths found in implicit link directories to use -l,
2008-01-31).  However, the special case for libraries in implicit link
directories has also proven problematic and confusing.

Introduce policy CMP0060 to switch to linking all libraries by full path
even if they are in implicit link directories.  Explain in the policy
documentation the factors that led to the original approach and now to
this approach.

16 files changed, 95 insertions, 0 deletions

diff --git a/Tests/RunCMake/CMP0060/CMP0060-Common.cmake b/Tests/RunCMake/CMP0060/CMP0060-Common.cmake
new file mode 100644
index 0000000..e0a56e6
--- /dev/null
+++ b/Tests/RunCMake/CMP0060/CMP0060-Common.cmake
@@ -0,0 +1,35 @@
+# Always build in a predictable configuration.  For multi-config
+# generators we depend on RunCMakeTest.cmake to do this for us.
+if(NOT CMAKE_CONFIGURATION_TYPES)
+  set(CMAKE_BUILD_TYPE Debug)
+endif()
+
+# Convince CMake that it can instruct the linker to search for the
+# library of the proper linkage type, but do not really pass flags.
+set(CMAKE_EXE_LINK_STATIC_C_FLAGS " ")
+set(CMAKE_EXE_LINK_DYNAMIC_C_FLAGS " ")
+
+# Make a link line asking for the linker to search for the library
+# look like a missing object file so we will get predictable content
+# in the error message.  This also ensures that cases expected to use
+# the full path can be verified by confirming that they link.
+set(CMAKE_LINK_LIBRARY_FLAG LINKFLAG_)
+set(CMAKE_LINK_LIBRARY_SUFFIX _LINKSUFFIX${CMAKE_C_OUTPUT_EXTENSION})
+
+# Convince CMake that our library is in an implicit linker search directory.
+list(APPEND CMAKE_C_IMPLICIT_LINK_DIRECTORIES ${CMAKE_CURRENT_BINARY_DIR}/lib)
+
+# Create a simple library file.  Place it in our library directory.
+add_library(CMP0060 STATIC cmp0060.c)
+set_property(TARGET CMP0060 PROPERTY
+  ARCHIVE_OUTPUT_DIRECTORY_DEBUG ${CMAKE_CURRENT_BINARY_DIR}/lib)
+
+# Add a target to link the library file by full path.
+add_executable(main1 main.c)
+target_link_libraries(main1 $<TARGET_FILE:CMP0060>)
+add_dependencies(main1 CMP0060)
+
+# Add a second target to verify the warning only appears once.
+add_executable(main2 main.c)
+target_link_libraries(main2 $<TARGET_FILE:CMP0060>)
+add_dependencies(main2 CMP0060)
diff --git a/Tests/RunCMake/CMP0060/CMP0060-NEW.cmake b/Tests/RunCMake/CMP0060/CMP0060-NEW.cmake
new file mode 100644
index 0000000..0414e4b
--- /dev/null
+++ b/Tests/RunCMake/CMP0060/CMP0060-NEW.cmake
@@ -0,0 +1,2 @@
+cmake_policy(SET CMP0060 NEW)
+include(CMP0060-Common.cmake)
diff --git a/Tests/RunCMake/CMP0060/CMP0060-OLD-Build-result.txt b/Tests/RunCMake/CMP0060/CMP0060-OLD-Build-result.txt
new file mode 100644
index 0000000..d197c91
--- /dev/null
+++ b/Tests/RunCMake/CMP0060/CMP0060-OLD-Build-result.txt
@@ -0,0 +1 @@
+[^0]
diff --git a/Tests/RunCMake/CMP0060/CMP0060-OLD-Build-stdout.txt b/Tests/RunCMake/CMP0060/CMP0060-OLD-Build-stdout.txt
new file mode 100644
index 0000000..240764c
--- /dev/null
+++ b/Tests/RunCMake/CMP0060/CMP0060-OLD-Build-stdout.txt
@@ -0,0 +1 @@
+LINKFLAG_CMP0060_LINKSUFFIX
diff --git a/Tests/RunCMake/CMP0060/CMP0060-OLD.cmake b/Tests/RunCMake/CMP0060/CMP0060-OLD.cmake
new file mode 100644
index 0000000..a9cffef
--- /dev/null
+++ b/Tests/RunCMake/CMP0060/CMP0060-OLD.cmake
@@ -0,0 +1,2 @@
+cmake_policy(SET CMP0060 OLD)
+include(CMP0060-Common.cmake)
diff --git a/Tests/RunCMake/CMP0060/CMP0060-WARN-OFF-Build-result.txt b/Tests/RunCMake/CMP0060/CMP0060-WARN-OFF-Build-result.txt
new file mode 100644
index 0000000..d197c91
--- /dev/null
+++ b/Tests/RunCMake/CMP0060/CMP0060-WARN-OFF-Build-result.txt
@@ -0,0 +1 @@
+[^0]
diff --git a/Tests/RunCMake/CMP0060/CMP0060-WARN-OFF-Build-stdout.txt b/Tests/RunCMake/CMP0060/CMP0060-WARN-OFF-Build-stdout.txt
new file mode 100644
index 0000000..240764c
--- /dev/null
+++ b/Tests/RunCMake/CMP0060/CMP0060-WARN-OFF-Build-stdout.txt
@@ -0,0 +1 @@
+LINKFLAG_CMP0060_LINKSUFFIX
diff --git a/Tests/RunCMake/CMP0060/CMP0060-WARN-OFF.cmake b/Tests/RunCMake/CMP0060/CMP0060-WARN-OFF.cmake
new file mode 100644
index 0000000..6b84565
--- /dev/null
+++ b/Tests/RunCMake/CMP0060/CMP0060-WARN-OFF.cmake
@@ -0,0 +1 @@
+include(CMP0060-Common.cmake)
diff --git a/Tests/RunCMake/CMP0060/CMP0060-WARN-ON-Build-result.txt b/Tests/RunCMake/CMP0060/CMP0060-WARN-ON-Build-result.txt
new file mode 100644
index 0000000..d197c91
--- /dev/null
+++ b/Tests/RunCMake/CMP0060/CMP0060-WARN-ON-Build-result.txt
@@ -0,0 +1 @@
+[^0]
diff --git a/Tests/RunCMake/CMP0060/CMP0060-WARN-ON-Build-stdout.txt b/Tests/RunCMake/CMP0060/CMP0060-WARN-ON-Build-stdout.txt
new file mode 100644
index 0000000..240764c
--- /dev/null
+++ b/Tests/RunCMake/CMP0060/CMP0060-WARN-ON-Build-stdout.txt
@@ -0,0 +1 @@
+LINKFLAG_CMP0060_LINKSUFFIX
diff --git a/Tests/RunCMake/CMP0060/CMP0060-WARN-ON-stderr.txt b/Tests/RunCMake/CMP0060/CMP0060-WARN-ON-stderr.txt
new file mode 100644
index 0000000..f6cc978
--- /dev/null
+++ b/Tests/RunCMake/CMP0060/CMP0060-WARN-ON-stderr.txt
@@ -0,0 +1,16 @@
+^CMake Warning \(dev\) at CMP0060-Common.cmake:[0-9]+ \(add_executable\):
+  Policy CMP0060 is not set: Link libraries by full path even in implicit
+  directories.  Run "cmake --help-policy CMP0060" for policy details.  Use
+  the cmake_policy command to set the policy and suppress this warning.
+
+  Some library files are in directories implicitly searched by the linker
+  when invoked for C:
+
+   .*/Tests/RunCMake/CMP0060/CMP0060-WARN-ON-build/lib/(lib)?CMP0060.(a|lib)
+
+  For compatibility with older versions of CMake, the generated link line
+  will ask the linker to search for these by library name.
+Call Stack \(most recent call first\):
+  CMP0060-WARN-ON.cmake:[0-9]+ \(include\)
+  CMakeLists.txt:3 \(include\)
+This warning is for project developers.  Use -Wno-dev to suppress it.$
diff --git a/Tests/RunCMake/CMP0060/CMP0060-WARN-ON.cmake b/Tests/RunCMake/CMP0060/CMP0060-WARN-ON.cmake
new file mode 100644
index 0000000..a0a7950
--- /dev/null
+++ b/Tests/RunCMake/CMP0060/CMP0060-WARN-ON.cmake
@@ -0,0 +1,2 @@
+set(CMAKE_POLICY_WARNING_CMP0060 1)
+include(CMP0060-Common.cmake)
diff --git a/Tests/RunCMake/CMP0060/CMakeLists.txt b/Tests/RunCMake/CMP0060/CMakeLists.txt
new file mode 100644
index 0000000..db6b701
--- /dev/null
+++ b/Tests/RunCMake/CMP0060/CMakeLists.txt
@@ -0,0 +1,3 @@
+cmake_minimum_required(VERSION 3.2)
+project(${RunCMake_TEST} C)
+include(${RunCMake_TEST}.cmake)
diff --git a/Tests/RunCMake/CMP0060/RunCMakeTest.cmake b/Tests/RunCMake/CMP0060/RunCMakeTest.cmake
new file mode 100644
index 0000000..445156f
--- /dev/null
+++ b/Tests/RunCMake/CMP0060/RunCMakeTest.cmake
@@ -0,0 +1,19 @@
+include(RunCMake)
+
+function(run_cmake_CMP0060 CASE)
+  set(RunCMake_TEST_BINARY_DIR ${RunCMake_BINARY_DIR}/CMP0060-${CASE}-build)
+  set(RunCMake_TEST_NO_CLEAN 1)
+  file(REMOVE_RECURSE "${RunCMake_TEST_BINARY_DIR}")
+  file(MAKE_DIRECTORY "${RunCMake_TEST_BINARY_DIR}")
+
+  run_cmake(CMP0060-${CASE})
+  set(RunCMake_TEST_OUTPUT_MERGE 1)
+  run_cmake_command(CMP0060-${CASE}-Build
+    ${CMAKE_COMMAND} --build . --config Debug
+    )
+endfunction()
+
+run_cmake_CMP0060(OLD)
+run_cmake_CMP0060(WARN-OFF)
+run_cmake_CMP0060(WARN-ON)
+run_cmake_CMP0060(NEW)
diff --git a/Tests/RunCMake/CMP0060/cmp0060.c b/Tests/RunCMake/CMP0060/cmp0060.c
new file mode 100644
index 0000000..a2da227
--- /dev/null
+++ b/Tests/RunCMake/CMP0060/cmp0060.c
@@ -0,0 +1,4 @@
+int libCMP0060(void)
+{
+  return 0;
+}
diff --git a/Tests/RunCMake/CMP0060/main.c b/Tests/RunCMake/CMP0060/main.c
new file mode 100644
index 0000000..91848c2
--- /dev/null
+++ b/Tests/RunCMake/CMP0060/main.c
@@ -0,0 +1,5 @@
+extern int libCMP0060(void);
+int main(void)
+{
+  return libCMP0060();
+}