gn: Tweak precompiled_header docs.

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 1433 matching lines @@
 const char kPrecompiledHeader[] = "precompiled_header";
 const char kPrecompiledHeader_HelpShort[] =
     "precompiled_header: [string] Header file to precompile.";
 const char kPrecompiledHeader_Help[] =
     R"(precompiled_header: [string] Header file to precompile.
 
   Precompiled headers will be used when a target specifies this value, or a
   config applying to this target specifies this value. In addition, the tool
   corresponding to the source files must also specify precompiled headers (see
   "gn help tool"). The tool will also specify what type of precompiled headers
-  to use.
+  to use, by setting precompiled_header_type to either "gcc" or "msvc".
 
   The precompiled header/source variables can be specified on a target or a
   config, but must be the same for all configs applying to a given target since
   a target can only have one precompiled header.
 
+  If you use both C and C++ sources, the precompiled header and source file
+  will be compiled once per language. You will want to make sure to wrap C++
+  includes in __cplusplus #ifdefs so the file will compile in C mode.
+
+GCC precompiled headers
+
+  When using GCC-style precompiled headers, "precompiled_source" contains the
+  path of a .h file that is precompiled and then included by all source files
+  in targets that set "precompiled_source".
+
+  The value of "precompiled_header" is not used with GCC-style precompiled
+  headers.

[Nico, 2017/03/03 20:24:34]

Fairly inconsistent with how MSVC-stype PCH works in GN, but that's today's
behavior from what I can tell. Chromium's .gn files do set precompiled_header
for GCC-style PCHs, but from what I can tell it has no effect. (Maybe GN should
warn if precompiled_header is set for gcc-style PCHs?)

+
 MSVC precompiled headers
 
   When using MSVC-style precompiled headers, the "precompiled_header" value is
   a string corresponding to the header. This is NOT a path to a file that GN
-  recognises, but rather the exact string that appears in quotes after an
-  #include line in source code. The compiler will match this string against
+  recognises, but rather the exact string that appears in quotes after
+  an #include line in source code. The compiler will match this string against

[Nico, 2017/03/03 20:24:34]

The motivation behind this CL was that the #include at the start of the line got
formatted as a comment in `gn help` output.

   includes or forced includes (/FI).
 
   MSVC also requires a source file to compile the header with. This must be
   specified by the "precompiled_source" value. In contrast to the header value,
   this IS a GN-style file name, and tells GN which source file to compile to
   make the .pch file used for subsequent compiles.
 
-  If you use both C and C++ sources, the precompiled header and source file
-  will be compiled using both tools. You will want to make sure to wrap C++
-  includes in __cplusplus #ifdefs so the file will compile in C mode.
-
   For example, if the toolchain specifies MSVC headers:
 
     toolchain("vc_x64") {
       ...
       tool("cxx") {
         precompiled_header_type = "msvc"
         ...
 
   You might make a config like this:
 
     config("use_precompiled_headers") {
       precompiled_header = "build/precompile.h"
       precompiled_source = "//build/precompile.cc"
 
       # Either your source files should #include "build/precompile.h"
       # first, or you can do this to force-include the header.
       cflags = [ "/FI$precompiled_header" ]
     }
 
   And then define a target that uses the config:
 
     executable("doom_melon") {
       configs += [ ":use_precompiled_headers" ]
       ...
 )";
 
+const char kPrecompiledHeaderType[] = "precompiled_header_type";
+const char kPrecompiledHeaderType_HelpShort[] =
+    "precompiled_header_type: [string] \"gcc\" or \"msvc\".";
+const char kPrecompiledHeaderType_Help[] =
+    R"(precompiled_header_type: [string] "gcc" or "msvc".
+
+  See "gn help precompiled_header".
+)";
+
 const char kPrecompiledSource[] = "precompiled_source";
 const char kPrecompiledSource_HelpShort[] =
     "precompiled_source: [file name] Source file to precompile.";
 const char kPrecompiledSource_Help[] =
     R"(precompiled_source: [file name] Source file to precompile.
 
   The source file that goes along with the precompiled_header when using
   "msvc"-style precompiled headers. It will be implicitly added to the sources
   of the target. See "gn help precompiled_header".
 )";
@@ skipping 384 matching lines @@
     INSERT_VARIABLE(Inputs)
     INSERT_VARIABLE(Ldflags)
     INSERT_VARIABLE(Libs)
     INSERT_VARIABLE(LibDirs)
     INSERT_VARIABLE(OutputDir)
     INSERT_VARIABLE(OutputExtension)
     INSERT_VARIABLE(OutputName)
     INSERT_VARIABLE(OutputPrefixOverride)
     INSERT_VARIABLE(Outputs)
     INSERT_VARIABLE(PrecompiledHeader)
+    INSERT_VARIABLE(PrecompiledHeaderType)
     INSERT_VARIABLE(PrecompiledSource)
     INSERT_VARIABLE(ProductType)
     INSERT_VARIABLE(Public)
     INSERT_VARIABLE(PublicConfigs)
     INSERT_VARIABLE(PublicDeps)
     INSERT_VARIABLE(ResponseFileContents)
     INSERT_VARIABLE(Script)
     INSERT_VARIABLE(Sources)
     INSERT_VARIABLE(Testonly)
     INSERT_VARIABLE(Visibility)
     INSERT_VARIABLE(WriteRuntimeDeps)
   }
   return info_map;
 }
 
 #undef INSERT_VARIABLE
 
 }  // namespace variables