Tell people that link_directories() is not what they are searching for

Judging from the questions I see on the #cmake IRC channel this is one
of the most common pitfalls for people coming from other build systems,
especially plain Makefiles.  Finally put this into the documentation to
stop people getting fooled into using this.

Text by Brad King.

1 files changed, 6 insertions, 1 deletions

diff --git a/Source/cmLinkDirectoriesCommand.h b/Source/cmLinkDirectoriesCommand.h
index e5ff4f0..aa13589 100644
--- a/Source/cmLinkDirectoriesCommand.h
+++ b/Source/cmLinkDirectoriesCommand.h
@@ -65,7 +65,12 @@ public:
       "For historical reasons, relative paths given to this command are "
       "passed to the linker unchanged "
       "(unlike many CMake commands which interpret them relative to the "
-      "current source directory)."
+      "current source directory).\n"
+      "Note that this command is rarely necessary.  Library locations "
+      "returned by find_package() and find_library() are absolute paths.  "
+      "Pass these absolute library file paths directly to the "
+      "target_link_libraries() command.  CMake will ensure the linker finds "
+      "them."
       ;
     }