Enhance GN documentation. This patch updates various GN documentation. BUG= Review URL: https://codereview.chromium.org/1367923006 Cr-Original-Commit-Position: refs/heads/master@{#350980} Cr-Mirrored-From: https://chromium.googlesource.com/chromium/src Cr-Mirrored-Commit: 1c3192f7e36fedcaaa02f262df58e246a3114972
diff --git a/tools/gn/docs/reference.md b/tools/gn/docs/reference.md index cf3ab28..c837037 100644 --- a/tools/gn/docs/reference.md +++ b/tools/gn/docs/reference.md
@@ -862,7 +862,7 @@ ### **Variables** ``` - args, data, data_deps, depfile, deps, outputs*, script*, + args, console, data, data_deps, depfile, deps, outputs*, script*, inputs, sources * = required @@ -949,7 +949,7 @@ ### **Variables** ``` - args, data, data_deps, depfile, deps, outputs*, script*, + args, console, data, data_deps, depfile, deps, outputs*, script*, inputs, sources* * = required @@ -2865,7 +2865,7 @@ ``` -### **Example**: +### **Example** ``` if (current_toolchain == "//build:64_bit_toolchain") { @@ -2980,7 +2980,7 @@ ``` -### **Example**: +### **Example** ``` action("myscript") { @@ -3042,7 +3042,7 @@ ``` -### **Example**: +### **Example** ``` action("myscript") { @@ -3115,7 +3115,7 @@ ``` -### **Example**: +### **Example** ``` action("myscript") { @@ -3559,6 +3559,31 @@ ``` +## **console**: Run this action in the console pool. + +``` + Boolean. Defaults to false. + + Actions marked "console = true" will be run in the built-in ninja + "console" pool. They will have access to real stdin and stdout, and + output will not be buffered by ninja. This can be useful for + long-running actions with progress logs, or actions that require user + input. + + Only one console pool target can run at any one time in Ninja. Refer + to the Ninja documentation on the console pool for more info. + +``` + +### **Example** + +``` + action("long_action_with_progress_logs") { + console = true + } + + +``` ## **data**: Runtime data file dependencies. ``` @@ -3604,7 +3629,8 @@ ``` -### **Example**: +### **Example** + ``` executable("foo") { deps = [ "//base" ] @@ -3642,7 +3668,8 @@ ``` -### **Example**: +### **Example** + ``` defines = [ "AWESOME_FEATURE", "LOG_LEVEL=3" ] @@ -3665,7 +3692,8 @@ ``` -### **Example**: +### **Example** + ``` action_foreach("myscript_target") { script = "myscript.py" @@ -3778,7 +3806,8 @@ ``` -### **Example**: +### **Example** + ``` include_dirs = [ "src/include", "//third_party/foo" ] @@ -3803,10 +3832,10 @@ uses via imports (the main script itself will be an implcit dependency of the action so need not be listed). - For action targets, inputs should be the entire set of inputs the - script needs. For action_foreach targets, inputs should be the set of - dependencies that don't change. These will be applied to each script - invocation over the sources. + For action targets, inputs and sources are treated the same, but from + a style perspective, it's recommended to follow the same rule as + action_foreach and put helper files in the inputs, and the data used + by the script (if any) in sources. Note that another way to declare input dependencies from an action is to have the action write a depfile (see "gn help depfile"). This @@ -3817,6 +3846,26 @@ ``` +### **Script input gotchas** + +``` + It may be tempting to write a script that enumerates all files in a + directory as inputs. Don't do this! Even if you specify all the files + in the inputs or sources in the GN target (or worse, enumerate the + files in an exec_script call when running GN, which will be slow), the + dependencies will be broken. + + The problem happens if a file is ever removed because the inputs are + not listed on the command line to the script. Because the script + hasn't changed and all inputs are up-to-date, the script will not + re-run and you will get a stale build. Instead, either list all + inputs on the command line to the script, or if there are many, create + a separate list file that the script reads. As long as this file is + listed in the inputs, the build will detect when it has changed in any + way and the action will re-run. + +``` + ### **Inputs for binary targets** ``` @@ -3825,6 +3874,14 @@ files in a target are compiled. So if you depend on generated headers, you do not typically need to list them in the inputs section. + Inputs for binary targets will be treated as order-only dependencies, + meaning that they will be forced up-to-date before compiling or + any files in the target, but changes in the inputs will not + necessarily force the target to compile. This is because it is + expected that the compiler will report the precise list of input + dependencies required to recompile each file once the initial build + is done. + ``` ### **Example** @@ -3908,7 +3965,8 @@ ``` -### **Example**: +### **Example** + ``` lib_dirs = [ "/usr/lib/foo", "lib/doom_melon" ] @@ -3961,7 +4019,8 @@ ``` -### **Examples**: +### **Examples** + ``` On Windows: libs = [ "ctl3d.lib" ] @@ -3978,6 +4037,35 @@ override the name (for example to use "libfreetype.so.6" instead of libfreetype.so on Linux). + This value should not include a leading dot. If undefined or empty, + the default_output_extension specified on the tool will be used. + The output_extension will be used in the "{{output_extension}}" + expansion which the linker tool will generally use to specify the + output file name. See "gn help tool". + +``` + +### **Example** + +``` + shared_library("freetype") { + if (is_linux) { + # Call the output "libfreetype.so.6" + output_extension = "so.6" + } + ... + } + + # On Windows, generate a "mysettings.cpl" control panel applet. + # Control panel applets are actually special shared libraries. + if (is_win) { + shared_library("mysettings") { + output_extension = "cpl" + ... + } + } + + ``` ## **output_name**: Define a name for the output file other than the default. @@ -3991,13 +4079,17 @@ The output name should have no extension or prefixes, these will be added using the default system rules. For example, on Linux an output - name of "foo" will produce a shared library "libfoo.so". + name of "foo" will produce a shared library "libfoo.so". There + is no way to override the output prefix of a linker tool on a per- + target basis. If you need more flexibility, create a copy target + to produce the file you want. This variable is valid for all binary output target types. ``` -### **Example**: +### **Example** + ``` static_library("doom_melon") { output_name = "fluffy_bunny" @@ -4009,13 +4101,26 @@ ``` Outputs is valid for "copy", "action", and "action_foreach" - target types and indicates the resulting files. The values may contain - source expansions to generate the output names from the sources (see - "gn help source_expansion"). + target types and indicates the resulting files. Outputs must always + refer to files in the build directory. - For copy targets, the outputs is the destination for the copied - file(s). For actions, the outputs should be the list of files - generated by the script. + copy + Copy targets should have exactly one entry in the outputs list. If + there is exactly one source, this can be a literal file name or a + source expansion. If there is more than one source, this must + contain a source expansion to map a single input name to a single + output name. See "gn help copy". + + action_foreach + Action_foreach targets must always use source expansions to map + input files to output files. There can be more than one output, + which means that each invocation of the script will produce a set of + files (presumably based on the name of the input file). See + "gn help action_foreach". + + action + Action targets (excluding action_foreach) must list literal output + file(s) with no source expansions. See "gn help action". ``` @@ -4117,7 +4222,8 @@ ``` -### **Examples**: +### **Examples** + ``` These exact files are public: public = [ "foo.h", "bar.h" ] @@ -4234,7 +4340,42 @@ ## **sources**: Source files for a target ``` - A list of files relative to the current buildfile. + A list of files. Non-absolute paths will be resolved relative to the + current build file. + +``` + +### **Sources for binary targets** + +``` + For binary targets (source sets, executables, and libraries), the + known file types will be compiled with the associated tools. Unknown + file types and headers will be skipped. However, you should still + list all C/C+ header files so GN knows about the existance of those + files for the purposes of include checking. + + As a special case, a file ending in ".def" will be treated as a + Windows module definition file. It will be appended to the link + line with a preceeding "/DEF:" string. There must be at most one + .def file in a target and they do not cross dependency boundaries + (so specifying a .def file in a static library or source set will have + no effect on the executable or shared library they're linked into). + +``` + +### **Sources for non-binary targets** + +``` + action_foreach + The sources are the set of files that the script will be executed + over. The script will run once per file. + + action + The sources will be treated the same as inputs. See "gn help inputs" + for more information and usage advice. + + copy + The source are the source files to copy. ```
diff --git a/tools/gn/variables.cc b/tools/gn/variables.cc index 0b7ac7a..6f9c848 100644 --- a/tools/gn/variables.cc +++ b/tools/gn/variables.cc
@@ -165,7 +165,7 @@ " 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" @@ -242,7 +242,7 @@ " 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" @@ -268,7 +268,7 @@ "\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" @@ -294,7 +294,7 @@ "\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" @@ -658,7 +658,8 @@ "\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" @@ -676,7 +677,8 @@ " 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"; @@ -698,7 +700,8 @@ " 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" @@ -788,7 +791,8 @@ " 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"; @@ -810,10 +814,10 @@ " 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" @@ -822,6 +826,23 @@ " 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" @@ -829,6 +850,14 @@ " 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" @@ -876,7 +905,8 @@ 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"; @@ -904,7 +934,8 @@ COMMON_LIB_INHERITANCE_HELP COMMON_ORDERING_HELP "\n" - "Examples:\n" + "Examples\n" + "\n" " On Windows:\n" " libs = [ \"ctl3d.lib\" ]\n" " On Linux:\n" @@ -919,7 +950,32 @@ " 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[] = @@ -936,11 +992,15 @@ "\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"; @@ -952,13 +1012,26 @@ "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[] = @@ -1058,7 +1131,8 @@ " 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" @@ -1154,7 +1228,37 @@ 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[] =