Special-case paths that appear in libs by not prefixing them with -l.

tools/gn/variables.cc

 // Copyright (c) 2013 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #include "tools/gn/variables.h"
 
 namespace variables {
 
 // Built-in variables ----------------------------------------------------------
 
@@ skipping 874 matching lines @@
     "Example\n"
     "\n"
     "  lib_dirs = [ \"/usr/lib/foo\", \"lib/doom_melon\" ]\n";
 
 const char kLibs[] = "libs";
 const char kLibs_HelpShort[] =
     "libs: [string list] Additional libraries to link.";
 const char kLibs_Help[] =
     "libs: Additional libraries to link.\n"
     "\n"
-    "  A list of strings.\n"
+    "  A list of library names or library paths.\n"
     "\n"
-    "  These files will be passed to the linker, which will generally search\n"
+    "  Values containing '/' will be treated as paths, and those without will\n"
+    "  be treated as library names."
+    "\n"
+    "  Names will be passed to the linker, which will generally search\n"
     "  the library include path. Unlike a normal list of files, they will be\n"
     "  passed to the linker unmodified rather than being treated as file\n"
     "  names relative to the current build file. Generally you would set\n"
     "  the \"lib_dirs\" so your library is found. If you need to specify\n"
     "  a path, you can use \"rebase_path\" to convert a path to be relative\n"
     "  to the build directory.\n"
     "\n"
     "  When constructing the linker command, the \"lib_prefix\" attribute of\n"
     "  the linker tool in the current toolchain will be prepended to each\n"
-    "  library. So your BUILD file should not specify the switch prefix\n"
-    "  (like \"-l\").\n"
+    "  library name (but not library paths). Your BUILD file should not\n"

[brettw, 2015/12/18 00:04:55]

How about replacing the existing docs with:

Values containing '/' will be treated as references to files in the build. They
will be rebased to be relative to the build directory and specified in the
\"libs\" for linker tools. This facility should be used for libraries that are
checked in to the build. For libraries that are generated by the build, use
normal GN deps to link them.

Values not containing '/' will be treated as system library names. These will be
passed unmodified to the linker and prefixed with the \"lib_prefix\" attribute
of the linker tool. Generally you would set the \"lib_dirs\" so the given
library is found. Your BUILD.gn file should not specify the switch prefix (like
\"-l\"): this will be encoded in the \"lib_prefix\" of the tool.

...framework exception paragraph...

[agrieve, 2015/12/18 15:39:08]

Sounds great! Done.

+    "  specify the switch prefix (like \"-l\").\n"
     "\n"
     "  Libraries ending in \".framework\" will be special-cased: the switch\n"
     "  \"-framework\" will be prepended instead of the lib_prefix, and the\n"
     "  \".framework\" suffix will be trimmed. This is to support the way Mac\n"
     "  links framework dependencies.\n"
     COMMON_LIB_INHERITANCE_HELP
     COMMON_ORDERING_HELP
     LIBS_AND_LIB_DIRS_ORDERING_HELP
     "\n"
     "Examples\n"
@@ skipping 513 matching lines @@
     INSERT_VARIABLE(Sources)
     INSERT_VARIABLE(Testonly)
     INSERT_VARIABLE(Visibility)
   }
   return info_map;
 }
 
 #undef INSERT_VARIABLE
 
 }  // namespace variables