Enhance GN documentation.

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 147 matching lines @@
 const char kCurrentToolchain[] = "current_toolchain";
 const char kCurrentToolchain_HelpShort[] =
     "current_toolchain: [string] Label of the current toolchain.";
 const char kCurrentToolchain_Help[] =
     "current_toolchain: Label of the current toolchain.\n"
     "\n"
     "  A fully-qualified label representing the current toolchain. You can\n"
     "  use this to make toolchain-related decisions in the build. See also\n"
     "  \"default_toolchain\".\n"
     "\n"
-    "Example:\n"
+    "Example\n"
     "\n"
     "  if (current_toolchain == \"//build:64_bit_toolchain\") {\n"
     "    executable(\"output_thats_64_bit_only\") {\n"
     "      ...\n";
 
 const char kDefaultToolchain[] = "default_toolchain";
 const char kDefaultToolchain_HelpShort[] =
     "default_toolchain: [string] Label of the default toolchain.";
 const char kDefaultToolchain_Help[] =
     "default_toolchain: [string] Label of the default toolchain.\n"
@@ skipping 56 matching lines @@
     "  \"//out/Debug/arm\" for the \"arm\" toolchain.\n"
     "\n"
     "  This is primarily useful for setting up script calls. If you are\n"
     "  passing this to a script, you will want to pass it through\n"
     "  rebase_path() (see \"gn help rebase_path\") to convert it\n"
     "  to be relative to the build directory.\n"
     "\n"
     "  See also \"target_out_dir\" which is usually a better location for\n"
     "  output files. It will be inside the root output dir.\n"
     "\n"
-    "Example:\n"
+    "Example\n"
     "\n"
     "  action(\"myscript\") {\n"
     "    # Pass the output dir to the script.\n"
     "    args = [ \"-o\", rebase_path(root_out_dir, root_build_dir) ]\n"
     "  }\n";
 
 const char kTargetGenDir[] = "target_gen_dir";
 const char kTargetGenDir_HelpShort[] =
     "target_gen_dir: [string] Directory for a target's generated files.";
 const char kTargetGenDir_Help[] =
     "target_gen_dir: Directory for a target's generated files.\n"
     "\n"
     "  Absolute path to the target's generated file directory. This will be\n"
     "  the \"root_gen_dir\" followed by the relative path to the current\n"
     "  build file. If your file is in \"//tools/doom_melon\" then\n"
     "  target_gen_dir would be \"//out/Debug/gen/tools/doom_melon\". It will\n"
     "  not have a trailing slash.\n"
     "\n"
     "  This is primarily useful for setting up include paths for generated\n"
     "  files. If you are passing this to a script, you will want to pass it\n"
     "  through rebase_path() (see \"gn help rebase_path\") to convert it\n"
     "  to be relative to the build directory.\n"
     "\n"
     "  See also \"gn help root_gen_dir\".\n"
     "\n"
-    "Example:\n"
+    "Example\n"
     "\n"
     "  action(\"myscript\") {\n"
     "    # Pass the generated output dir to the script.\n"
     "    args = [ \"-o\", rebase_path(target_gen_dir, root_build_dir) ]"
     "\n"
     "  }\n";
 
 const char kTargetOutDir[] = "target_out_dir";
 const char kTargetOutDir_HelpShort[] =
     "target_out_dir: [string] Directory for target output files.";
 const char kTargetOutDir_Help[] =
     "target_out_dir: [string] Directory for target output files.\n"
     "\n"
     "  Absolute path to the target's generated file directory. If your\n"
     "  current target is in \"//tools/doom_melon\" then this value might be\n"
     "  \"//out/Debug/obj/tools/doom_melon\". It will not have a trailing\n"
     "  slash.\n"
     "\n"
     "  This is primarily useful for setting up arguments for calling\n"
     "  scripts. If you are passing this to a script, you will want to pass it\n"
     "  through rebase_path() (see \"gn help rebase_path\") to convert it\n"
     "  to be relative to the build directory.\n"
     "\n"
     "  See also \"gn help root_out_dir\".\n"
     "\n"
-    "Example:\n"
+    "Example\n"
     "\n"
     "  action(\"myscript\") {\n"
     "    # Pass the output dir to the script.\n"
     "    args = [ \"-o\", rebase_path(target_out_dir, root_build_dir) ]"
     "\n"
     "  }\n";
 
 // Target variables ------------------------------------------------------------
 
 #define COMMON_ORDERING_HELP \
@@ skipping 343 matching lines @@
     "\n"
     "  Specifies dependencies of a target that are not actually linked into\n"
     "  the current target. Such dependencies will be built and will be\n"
     "  available at runtime.\n"
     "\n"
     "  This is normally used for things like plugins or helper programs that\n"
     "  a target needs at runtime.\n"
     "\n"
     "  See also \"gn help deps\" and \"gn help data\".\n"
     "\n"
-    "Example:\n"
+    "Example\n"
+    "\n"
     "  executable(\"foo\") {\n"
     "    deps = [ \"//base\" ]\n"
     "    data_deps = [ \"//plugins:my_runtime_plugin\" ]\n"
     "  }\n";
 
 const char kDefines[] = "defines";
 const char kDefines_HelpShort[] =
     "defines: [string list] C preprocessor defines.";
 const char kDefines_Help[] =
     "defines: C preprocessor defines.\n"
     "\n"
     "  A list of strings\n"
     "\n"
     "  These strings will be passed to the C/C++ compiler as #defines. The\n"
     "  strings may or may not include an \"=\" to assign a value.\n"
     COMMON_ORDERING_HELP
     "\n"
-    "Example:\n"
+    "Example\n"
+    "\n"
     "  defines = [ \"AWESOME_FEATURE\", \"LOG_LEVEL=3\" ]\n";
 
 const char kDepfile[] = "depfile";
 const char kDepfile_HelpShort[] =
     "depfile: [string] File name for input dependencies for actions.";
 const char kDepfile_Help[] =
     "depfile: [string] File name for input dependencies for actions.\n"
     "\n"
     "  If nonempty, this string specifies that the current action or\n"
     "  action_foreach target will generate the given \".d\" file containing\n"
     "  the dependencies of the input. Empty or unset means that the script\n"
     "  doesn't generate the files.\n"
     "\n"
     "  The .d file should go in the target output directory. If you have more\n"
     "  than one source file that the script is being run over, you can use\n"
     "  the output file expansions described in \"gn help action_foreach\" to\n"
     "  name the .d file according to the input."
     "\n"
     "  The format is that of a Makefile, and all of the paths should be\n"
     "  relative to the root build directory.\n"
     "\n"
-    "Example:\n"
+    "Example\n"
+    "\n"
     "  action_foreach(\"myscript_target\") {\n"
     "    script = \"myscript.py\"\n"
     "    sources = [ ... ]\n"
     "\n"
     "    # Locate the depfile in the output directory named like the\n"
     "    # inputs but with a \".d\" appended.\n"
     "    depfile = \"$relative_target_output_dir/{{source_name}}.d\"\n"
     "\n"
     "    # Say our script uses \"-o <d file>\" to indicate the depfile.\n"
     "    args = [ \"{{source}}\", \"-o\", depfile ]\n"
@@ skipping 69 matching lines @@
     "include_dirs: [directory list] Additional include directories.";
 const char kIncludeDirs_Help[] =
     "include_dirs: Additional include directories.\n"
     "\n"
     "  A list of source directories.\n"
     "\n"
     "  The directories in this list will be added to the include path for\n"
     "  the files in the affected target.\n"
     COMMON_ORDERING_HELP
     "\n"
-    "Example:\n"
+    "Example\n"
+    "\n"
     "  include_dirs = [ \"src/include\", \"//third_party/foo\" ]\n";
 
 const char kInputs[] = "inputs";
 const char kInputs_HelpShort[] =
     "inputs: [file list] Additional compile-time dependencies.";
 const char kInputs_Help[] =
     "inputs: Additional compile-time dependencies.\n"
     "\n"
     "  Inputs are compile-time dependencies of the current target. This means\n"
     "  that all inputs must be available before compiling any of the sources\n"
     "  or executing any actions.\n"
     "\n"
     "  Inputs are typically only used for action and action_foreach targets.\n"
     "\n"
     "Inputs for actions\n"
     "\n"
     "  For action and action_foreach targets, inputs should be the inputs to\n"
     "  script that don't vary. These should be all .py files that the script\n"
     "  uses via imports (the main script itself will be an implcit dependency\n"
     "  of the action so need not be listed).\n"
     "\n"
-    "  For action targets, inputs should be the entire set of inputs the\n"
-    "  script needs. For action_foreach targets, inputs should be the set of\n"
-    "  dependencies that don't change. These will be applied to each script\n"
-    "  invocation over the sources.\n"
+    "  For action targets, inputs and sources are treated the same, but from\n"
+    "  a style perspective, it's recommended to follow the same rule as\n"
+    "  action_foreach and put helper files in the inputs, and the data used\n"
+    "  by the script (if any) in sources.\n"
     "\n"
     "  Note that another way to declare input dependencies from an action\n"
     "  is to have the action write a depfile (see \"gn help depfile\"). This\n"
     "  allows the script to dynamically write input dependencies, that might\n"
     "  not be known until actually executing the script. This is more\n"
     "  efficient than doing processing while running GN to determine the\n"
     "  inputs, and is easier to keep in-sync than hardcoding the list.\n"
     "\n"
+    "Script input gotchas\n"
+    "\n"
+    "  It may be tempting to write a script that enumerates all files in a\n"
+    "  directory as inputs. Don't do this! Even if you specify all the files\n"
+    "  in the inputs or sources in the GN target (or worse, enumerate the\n"
+    "  files in an exec_script call when running GN, which will be slow), the\n"
+    "  dependencies will be broken.\n"
+    "\n"
+    "  The problem happens if a file is ever removed because the inputs are\n"
+    "  not listed on the command line to the script. Because the script\n"
+    "  hasn't changed and all inputs are up-to-date, the script will not\n"
+    "  re-run and you will get a stale build. Instead, either list all\n"
+    "  inputs on the command line to the script, or if there are many, create\n"
+    "  a separate list file that the script reads. As long as this file is\n"
+    "  listed in the inputs, the build will detect when it has changed in any\n"
+    "  way and the action will re-run.\n"
+    "\n"
     "Inputs for binary targets\n"
     "\n"
     "  Any input dependencies will be resolved before compiling any sources.\n"
     "  Normally, all actions that a target depends on will be run before any\n"
     "  files in a target are compiled. So if you depend on generated headers,\n"
     "  you do not typically need to list them in the inputs section.\n"
     "\n"
+    "  Inputs for binary targets will be treated as order-only dependencies,\n"
+    "  meaning that they will be forced up-to-date before compiling or\n"
+    "  any files in the target, but changes in the inputs will not\n"
+    "  necessarily force the target to compile. This is because it is\n"
+    "  expected that the compiler will report the precise list of input\n"
+    "  dependencies required to recompile each file once the initial build\n"
+    "  is done.\n"
+    "\n"
     "Example\n"
     "\n"
     "  action(\"myscript\") {\n"
     "    script = \"domything.py\"\n"
     "    inputs = [ \"input.data\" ]\n"
     "  }\n";
 
 const char kLdflags[] = "ldflags";
 const char kLdflags_HelpShort[] =
     "ldflags: [string list] Flags passed to the linker.";
@@ skipping 27 matching lines @@
     "lib_dirs: Additional library directories.\n"
     "\n"
     "  A list of directories.\n"
     "\n"
     "  Specifies additional directories passed to the linker for searching\n"
     "  for the required libraries. If an item is not an absolute path, it\n"
     "  will be treated as being relative to the current build file.\n"
     COMMON_LIB_INHERITANCE_HELP
     COMMON_ORDERING_HELP
     "\n"
-    "Example:\n"
+    "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"
     "\n"
     "  These files 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\"). On Mac, libraries ending in \".framework\" will be\n"
     "  special-cased: the switch \"-framework\" will be prepended instead of\n"
     "  the lib_prefix, and the \".framework\" suffix will be trimmed.\n"
     COMMON_LIB_INHERITANCE_HELP
     COMMON_ORDERING_HELP
     "\n"
-    "Examples:\n"
+    "Examples\n"
+    "\n"
     "  On Windows:\n"
     "    libs = [ \"ctl3d.lib\" ]\n"
     "  On Linux:\n"
     "    libs = [ \"ld\" ]\n";
 
 const char kOutputExtension[] = "output_extension";
 const char kOutputExtension_HelpShort[] =
     "output_extension: [string] Value to use for the output's file extension.";
 const char kOutputExtension_Help[] =
     "output_extension: Value to use for the output's file extension.\n"
     "\n"
     "  Normally the file extension for a target is based on the target\n"
     "  type and the operating system, but in rare cases you will need to\n"
     "  override the name (for example to use \"libfreetype.so.6\" instead\n"
-    "  of libfreetype.so on Linux).";
+    "  of libfreetype.so on Linux).\n"
+    "\n"
+    "  This value should not include a leading dot. If undefined or empty,\n"
+    "  the default_output_extension specified on the tool will be used.\n"
+    "  The output_extension will be used in the \"{{output_extension}}\"\n"
+    "  expansion which the linker tool will generally use to specify the\n"
+    "  output file name. See \"gn help tool\".\n"
+    "\n"
+    "Example\n"
+    "\n"
+    "  shared_library(\"freetype\") {\n"
+    "    if (is_linux) {\n"
+    "      # Call the output \"libfreetype.so.6\"\n"
+    "      output_extension = \"so.6\"\n"
+    "    }\n"
+    "    ...\n"
+    "  }\n"
+    "\n"
+    "  # On Windows, generate a \"mysettings.cpl\" control panel applet.\n"
+    "  # Control panel applets are actually special shared libraries.\n"
+    "  if (is_win) {\n"
+    "    shared_library(\"mysettings\") {\n"
+    "      output_extension = \"cpl\"\n"
+    "      ...\n"
+    "    }\n"
+    "  }\n";
 
 const char kOutputName[] = "output_name";
 const char kOutputName_HelpShort[] =
     "output_name: [string] Name for the output file other than the default.";
 const char kOutputName_Help[] =
     "output_name: Define a name for the output file other than the default.\n"
     "\n"
     "  Normally the output name of a target will be based on the target name,\n"
     "  so the target \"//foo/bar:bar_unittests\" will generate an output\n"
     "  file such as \"bar_unittests.exe\" (using Windows as an example).\n"
     "\n"
     "  Sometimes you will want an alternate name to avoid collisions or\n"
     "  if the internal name isn't appropriate for public distribution.\n"
     "\n"
     "  The output name should have no extension or prefixes, these will be\n"
     "  added using the default system rules. For example, on Linux an output\n"
-    "  name of \"foo\" will produce a shared library \"libfoo.so\".\n"
+    "  name of \"foo\" will produce a shared library \"libfoo.so\". There\n"
+    "  is no way to override the output prefix of a linker tool on a per-\n"
+    "  target basis. If you need more flexibility, create a copy target\n"
+    "  to produce the file you want.\n"
     "\n"
     "  This variable is valid for all binary output target types.\n"
     "\n"
-    "Example:\n"
+    "Example\n"
+    "\n"
     "  static_library(\"doom_melon\") {\n"
     "    output_name = \"fluffy_bunny\"\n"
     "  }\n";
 
 const char kOutputs[] = "outputs";
 const char kOutputs_HelpShort[] =
     "outputs: [file list] Output files for actions and copy targets.";
 const char kOutputs_Help[] =
     "outputs: Output files for actions and copy targets.\n"
     "\n"
     "  Outputs is valid for \"copy\", \"action\", and \"action_foreach\"\n"
-    "  target types and indicates the resulting files. The values may contain\n"
-    "  source expansions to generate the output names from the sources (see\n"
-    "  \"gn help source_expansion\").\n"
+    "  target types and indicates the resulting files. Outputs must always\n"
+    "  refer to files in the build directory.\n"
     "\n"
-    "  For copy targets, the outputs is the destination for the copied\n"
-    "  file(s). For actions, the outputs should be the list of files\n"
-    "  generated by the script.\n";
+    "  copy\n"
+    "    Copy targets should have exactly one entry in the outputs list. If\n"
+    "    there is exactly one source, this can be a literal file name or a\n"
+    "    source expansion. If there is more than one source, this must\n"
+    "    contain a source expansion to map a single input name to a single\n"
+    "    output name. See \"gn help copy\".\n"
+    "\n"
+    "  action_foreach\n"
+    "    Action_foreach targets must always use source expansions to map\n"
+    "    input files to output files. There can be more than one output,\n"
+    "    which means that each invocation of the script will produce a set of\n"
+    "    files (presumably based on the name of the input file). See\n"
+    "    \"gn help action_foreach\".\n"
+    "\n"
+    "  action\n"
+    "    Action targets (excluding action_foreach) must list literal output\n"
+    "    file(s) with no source expansions. See \"gn help action\".\n";
 
 const char kPrecompiledHeader[] = "precompiled_header";
 const char kPrecompiledHeader_HelpShort[] =
     "precompiled_header: [string] Header file to precompile.";
 const char kPrecompiledHeader_Help[] =
     "precompiled_header: [string] Header file to precompile.\n"
     "\n"
     "  Precompiled headers will be used when a target specifies this\n"
     "  value, or a config applying to this target specifies this value.\n"
     "  In addition, the tool corresponding to the source files must also\n"
@@ skipping 79 matching lines @@
     "\n"
     "  Public files are inherited through the dependency tree. So if there is\n"
     "  a dependency A -> B -> C, then A can include C's public headers.\n"
     "  However, the same is NOT true of visibility, so unless A is in C's\n"
     "  visibility list, the include will be rejected.\n"
     "\n"
     "  GN only knows about files declared in the \"sources\" and \"public\"\n"
     "  sections of targets. If a file is included that is not known to the\n"
     "  build, it will be allowed.\n"
     "\n"
-    "Examples:\n"
+    "Examples\n"
+    "\n"
     "  These exact files are public:\n"
     "    public = [ \"foo.h\", \"bar.h\" ]\n"
     "\n"
     "  No files are public (no targets may include headers from this one):\n"
     "    public = []\n";
 
 const char kPublicConfigs[] = "public_configs";
 const char kPublicConfigs_HelpShort[] =
     "public_configs: [label list] Configs applied to dependents.";
 const char kPublicConfigs_Help[] =
@@ skipping 75 matching lines @@
     "  An absolute or buildfile-relative file name of a Python script to run\n"
     "  for a action and action_foreach targets (see \"gn help action\" and\n"
     "  \"gn help action_foreach\").\n";
 
 const char kSources[] = "sources";
 const char kSources_HelpShort[] =
     "sources: [file list] Source files for a target.";
 const char kSources_Help[] =
     "sources: Source files for a target\n"
     "\n"
-    "  A list of files relative to the current buildfile.\n";
+    "  A list of files. Non-absolute paths will be resolved relative to the\n"
+    "  current build file.\n"
+    "\n"
+    "Sources for binary targets\n"
+    "\n"
+    "  For binary targets (source sets, executables, and libraries), the\n"
+    "  known file types will be compiled with the associated tools. Unknown\n"
+    "  file types and headers will be skipped. However, you should still\n"
+    "  list all C/C+ header files so GN knows about the existance of those\n"
+    "  files for the purposes of include checking.\n"
+    "\n"
+    "  As a special case, a file ending in \".def\" will be treated as a\n"
+    "  Windows module definition file. It will be appended to the link\n"
+    "  line with a preceeding \"/DEF:\" string. There must be at most one\n"
+    "  .def file in a target and they do not cross dependency boundaries\n"
+    "  (so specifying a .def file in a static library or source set will have\n"
+    "  no effect on the executable or shared library they're linked into).\n"
+    "\n"
+    "Sources for non-binary targets\n"
+    "\n"
+    "  action_foreach\n"
+    "    The sources are the set of files that the script will be executed\n"
+    "    over. The script will run once per file.\n"
+    "\n"
+    "  action\n"
+    "    The sources will be treated the same as inputs. See "
+         "\"gn help inputs\"\n"
+    "    for more information and usage advice.\n"
+    "\n"
+    "  copy\n"
+    "    The source are the source files to copy.\n";
 
 const char kTestonly[] = "testonly";
 const char kTestonly_HelpShort[] =
     "testonly: [boolean] Declares a target must only be used for testing.";
 const char kTestonly_Help[] =
     "testonly: Declares a target must only be used for testing.\n"
     "\n"
     "  Boolean. Defaults to false.\n"
     "\n"
     "  When a target is marked \"testonly = true\", it must only be depended\n"
@@ skipping 139 matching lines @@
     INSERT_VARIABLE(Sources)
     INSERT_VARIABLE(Testonly)
     INSERT_VARIABLE(Visibility)
   }
   return info_map;
 }
 
 #undef INSERT_VARIABLE
 
 }  // namespace variables