GN: Refine 'complete' static library handling

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 646 matching lines @@
     "  A static library normally doesn't include code from dependencies, but\n"
     "  instead forwards the static libraries and source sets in its deps up\n"
     "  the dependency chain until a linkable target (an executable or shared\n"
     "  library) is reached. The final linkable target only links each static\n"
     "  library once, even if it appears more than once in its dependency\n"
     "  graph.\n"
     "\n"
     "  In some cases the static library might be the final desired output.\n"
     "  For example, you may be producing a static library for distribution to\n"
     "  third parties. In this case, the static library should include code\n"
-    "  for all dependencies in one complete package. Since GN does not unpack\n"
-    "  static libraries to forward their contents up the dependency chain,\n"
-    "  it is an error for complete static libraries to depend on other static\n"
+    "  for all dependencies in one complete package. However, complete static\n"
+    "  libraries themselves are never linked into other complete static\n"
+    "  libraries. All complete static libraries are for distribution and\n"
+    "  linking them in would cause code duplication in this case. If the\n"
+    "  static library is not for distribution, it should not be complete.\n"
+    "\n"
+    "  GN treats non-complete static libraries as source sets when they are\n"
+    "  linked into complete static libraries. This is done because some tools\n"
+    "  like AR do not handle dependent static libraries properly. This makes\n"
+    "  it easier to write \"alink\" rules.\n"
     "\n"
     "  In rare cases it makes sense to list a header in more than one\n"
     "  target if it could be considered conceptually a member of both.\n"
     "  libraries.\n"
     "\n"
     "Example\n"
     "\n"
     "  static_library(\"foo\") {\n"
     "    complete_static_lib = true\n"
     "    deps = [ \"bar\" ]\n"
@@ skipping 69 matching lines @@
     "  config(\"default_optimization\") {\n"
     "    if (optimize_everything) {\n"
     "      configs = [ \":super_optimization\" ]\n"
     "    } else {\n"
     "      configs = [ \":no_optimization\" ]\n"
     "    }\n"
     "  }\n";
 
 const char kConsole[] = "console";
 const char kConsole_HelpShort[] =
-    "console [boolean]: Run this action in the console pool.";
+    "console: [boolean] Run this action in the console pool.";
 const char kConsole_Help[] =
     "console: Run this action in the console pool.\n"
     "\n"
     "  Boolean. Defaults to false.\n"
     "\n"
     "  Actions marked \"console = true\" will be run in the built-in ninja\n"
     "  \"console\" pool. They will have access to real stdin and stdout, and\n"
     "  output will not be buffered by ninja. This can be useful for\n"
     "  long-running actions with progress logs, or actions that require user \n"
     "  input.\n"
@@ skipping 930 matching lines @@
     INSERT_VARIABLE(Testonly)
     INSERT_VARIABLE(Visibility)
     INSERT_VARIABLE(WriteRuntimeDeps)
   }
   return info_map;
 }
 
 #undef INSERT_VARIABLE
 
 }  // namespace variables