1 // Copyright (c) 2013 The Chromium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
5 #include "tools/gn/variables.h"
9 // Built-in variables ----------------------------------------------------------
11 const char kComponentMode[] = "component_mode";
12 const char kComponentMode_HelpShort[] =
13 "component_mode: [string] Specifies the meaning of the component() call.";
14 const char kComponentMode_Help[] =
15 "component_mode: Specifies the meaning of the component() call.\n"
17 " This value is looked up whenever a \"component\" target type is\n"
18 " encountered. The value controls whether the given target is a shared\n"
19 " or a static library.\n"
21 " The initial value will be empty, which will cause a call to\n"
22 " component() to throw an error. Typically this value will be set in the\n"
23 " build config script.\n"
26 " - \"shared_library\"\n"
28 " - \"static_library\"\n";
30 const char kCpuArch[] = "cpu_arch";
31 const char kCpuArch_HelpShort[] =
32 "cpu_arch: [string] Current processor architecture.";
33 const char kCpuArch_Help[] =
34 "cpu_arch: Current processor architecture.\n"
36 " The initial value is based on the current architecture of the host\n"
37 " system. However, the build configuration can set this to any value.\n"
39 " This value is not used internally by GN for any purpose, so you can\n"
40 " set it to whatever value is relevant to your build.\n"
42 "Possible initial values set by GN:\n"
48 const char kCurrentToolchain[] = "current_toolchain";
49 const char kCurrentToolchain_HelpShort[] =
50 "current_toolchain: [string] Label of the current toolchain.";
51 const char kCurrentToolchain_Help[] =
52 "current_toolchain: Label of the current toolchain.\n"
54 " A fully-qualified label representing the current toolchain. You can\n"
55 " use this to make toolchain-related decisions in the build. See also\n"
56 " \"default_toolchain\".\n"
60 " if (current_toolchain == \"//build:64_bit_toolchain\") {\n"
61 " executable(\"output_thats_64_bit_only\") {\n"
64 const char kBuildCpuArch[] = "build_cpu_arch";
65 const char kBuildCpuArch_HelpShort[] =
66 "build_cpu_arch: [string] The default value for the \"cpu_arch\" "
68 const char kBuildCpuArch_Help[] =
69 "build_cpu_arch: The default value for the \"cpu_arch\" variable.\n"
71 " This value has the same definition as \"cpu_arch\" (see\n"
72 " \"gn help cpu_arch\") but should be treated as read-only. This is so\n"
73 " the build can override the \"cpu_arch\" variable for doing\n"
74 " cross-compiles, but can still access the host build system's CPU\n"
77 const char kBuildOs[] = "build_os";
78 const char kBuildOs_HelpShort[] =
79 "build_os: [string] The default value for the \"os\" variable.";
80 const char kBuildOs_Help[] =
81 "build_os: [string] The default value for the \"os\" variable.\n"
83 " This value has the same definition as \"os\" (see \"gn help os\") but\n"
84 " should be treated as read-only. This is so the build can override\n"
85 " the \"os\" variable for doing cross-compiles, but can still access\n"
86 " the host build system's operating system type.\n";
88 const char kDefaultToolchain[] = "default_toolchain";
89 const char kDefaultToolchain_HelpShort[] =
90 "default_toolchain: [string] Label of the default toolchain.";
91 const char kDefaultToolchain_Help[] =
92 "default_toolchain: [string] Label of the default toolchain.\n"
94 " A fully-qualified label representing the default toolchain, which may\n"
95 " not necessarily be the current one (see \"current_toolchain\").\n";
97 const char kOs[] = "os";
98 const char kOs_HelpShort[] =
99 "os: [string] Indicates the operating system of the current build.";
100 const char kOs_Help[] =
101 "os: Indicates the operating system of the current build."
103 " This value is set by default based on the current host operating\n"
104 " system. The build configuration can override the value to anything\n"
105 " it wants, or it can be set via the build arguments on the command\n"
108 " If you want to know the default value without any overrides, you can\n"
109 " use \"default_os\" (see \"gn help default_os\").\n"
111 " Note that this returns the most specific value. So even though\n"
112 " Android and ChromeOS are both Linux, the more specific value will\n"
115 "Some possible values:\n"
124 const char kPythonPath[] = "python_path";
125 const char kPythonPath_HelpShort[] =
126 "python_path: [string] Absolute path of Python.";
127 const char kPythonPath_Help[] =
128 "python_path: Absolute path of Python.\n"
130 " Normally used in toolchain definitions if running some command\n"
131 " requires Python. You will normally not need this when invoking scripts\n"
132 " since GN automatically finds it for you.\n";
134 const char kRootBuildDir[] = "root_build_dir";
135 const char kRootBuildDir_HelpShort[] =
136 "root_build_dir: [string] Directory where build commands are run.";
137 const char kRootBuildDir_Help[] =
138 "root_build_dir: [string] Directory where build commands are run.\n"
140 " This is the root build output directory which will be the current\n"
141 " directory when executing all compilers and scripts.\n"
143 " Most often this is used with rebase_path (see \"gn help rebase_path\")\n"
144 " to convert arguments to be relative to a script's current directory.\n";
146 const char kRootGenDir[] = "root_gen_dir";
147 const char kRootGenDir_HelpShort[] =
148 "root_gen_dir: [string] Directory for the toolchain's generated files.";
149 const char kRootGenDir_Help[] =
150 "root_gen_dir: Directory for the toolchain's generated files.\n"
152 " Absolute path to the root of the generated output directory tree for\n"
153 " the current toolchain. An example value might be \"//out/Debug/gen\".\n"
154 " It will not have a trailing slash.\n"
156 " This is primarily useful for setting up include paths for generated\n"
157 " files. If you are passing this to a script, you will want to pass it\n"
158 " through rebase_path() (see \"gn help rebase_path\") to convert it\n"
159 " to be relative to the build directory.\n"
161 " See also \"target_gen_dir\" which is usually a better location for\n"
162 " generated files. It will be inside the root generated dir.\n";
164 const char kRootOutDir[] = "root_out_dir";
165 const char kRootOutDir_HelpShort[] =
166 "root_out_dir: [string] Root directory for toolchain output files.";
167 const char kRootOutDir_Help[] =
168 "root_out_dir: [string] Root directory for toolchain output files.\n"
170 " Absolute path to the root of the output directory tree for the current\n"
171 " toolchain. An example value might be \"//out/Debug/gen\". It will not\n"
172 " have a trailing slash.\n"
174 " This is primarily useful for setting up script calls. If you are\n"
175 " passing this to a script, you will want to pass it through\n"
176 " rebase_path() (see \"gn help rebase_path\") to convert it\n"
177 " to be relative to the build directory.\n"
179 " See also \"target_out_dir\" which is usually a better location for\n"
180 " output files. It will be inside the root output dir.\n"
184 " action(\"myscript\") {\n"
185 " # Pass the output dir to the script.\n"
186 " args = [ \"-o\", rebase_path(root_out_dir, root_build_dir) ]\n"
189 const char kTargetGenDir[] = "target_gen_dir";
190 const char kTargetGenDir_HelpShort[] =
191 "target_gen_dir: [string] Directory for a target's generated files.";
192 const char kTargetGenDir_Help[] =
193 "target_gen_dir: Directory for a target's generated files.\n"
195 " Absolute path to the target's generated file directory. If your\n"
196 " current target is in \"//tools/doom_melon\" then this value might be\n"
197 " \"//out/Debug/gen/tools/doom_melon\". It will not have a trailing\n"
200 " This is primarily useful for setting up include paths for generated\n"
201 " files. If you are passing this to a script, you will want to pass it\n"
202 " through rebase_path() (see \"gn help rebase_path\") to convert it\n"
203 " to be relative to the build directory.\n"
205 " See also \"gn help root_gen_dir\".\n"
209 " action(\"myscript\") {\n"
210 " # Pass the generated output dir to the script.\n"
211 " args = [ \"-o\", rebase_path(target_gen_dir, root_build_dir) ]"
215 const char kTargetOutDir[] = "target_out_dir";
216 const char kTargetOutDir_HelpShort[] =
217 "target_out_dir: [string] Directory for target output files.";
218 const char kTargetOutDir_Help[] =
219 "target_out_dir: [string] Directory for target output files."
221 " Absolute path to the target's generated file directory. If your\n"
222 " current target is in \"//tools/doom_melon\" then this value might be\n"
223 " \"//out/Debug/obj/tools/doom_melon\". It will not have a trailing\n"
226 " This is primarily useful for setting up arguments for calling\n"
227 " scripts. If you are passing this to a script, you will want to pass it\n"
228 " through rebase_path() (see \"gn help rebase_path\") to convert it\n"
229 " to be relative to the build directory.\n"
231 " See also \"gn help root_out_dir\".\n"
235 " action(\"myscript\") {\n"
236 " # Pass the output dir to the script.\n"
237 " args = [ \"-o\", rebase_path(target_out_dir, root_build_dir) ]"
241 // Target variables ------------------------------------------------------------
243 #define COMMON_ORDERING_HELP \
245 "Ordering of flags and values:\n" \
247 " 1. Those set on the current target (not in a config).\n" \
248 " 2. Those set on the \"configs\" on the target in order that the\n" \
249 " configs appear in the list.\n" \
250 " 3. Those set on the \"all_dependent_configs\" on the target in order\n" \
251 " that the configs appear in the list.\n" \
252 " 4. Those set on the \"direct_dependent_configs\" on the target in\n" \
253 " order that those configs appear in the list.\n" \
254 " 5. all_dependent_configs pulled from dependencies, in the order of\n" \
255 " the \"deps\" list. This is done recursively. If a config appears\n" \
256 " more than once, only the first occurance will be used.\n" \
257 " 6. direct_dependent_configs pulled from dependencies, in the order\n" \
258 " of the \"deps\" list. If a dependency has\n" \
259 " \"forward_dependent_configs_from\", they will be applied\n" \
262 const char kAllDependentConfigs[] = "all_dependent_configs";
263 const char kAllDependentConfigs_HelpShort[] =
264 "all_dependent_configs: [label list] Configs to be forced on dependents.";
265 const char kAllDependentConfigs_Help[] =
266 "all_dependent_configs: Configs to be forced on dependents.\n"
268 " A list of config labels.\n"
270 " All targets depending on this one, and recursively, all targets\n"
271 " depending on those, will have the configs listed in this variable\n"
272 " added to them. These configs will also apply to the current target.\n"
274 " This addition happens in a second phase once a target and all of its\n"
275 " dependencies have been resolved. Therefore, a target will not see\n"
276 " these force-added configs in their \"configs\" variable while the\n"
277 " script is running, and then can not be removed. As a result, this\n"
278 " capability should generally only be used to add defines and include\n"
279 " directories necessary to compile a target's headers.\n"
281 " See also \"direct_dependent_configs\".\n"
282 COMMON_ORDERING_HELP;
284 const char kArgs[] = "args";
285 const char kArgs_HelpShort[] =
286 "args: [string list] Arguments passed to an action.";
287 const char kArgs_Help[] =
288 "args: Arguments passed to an action.\n"
290 " For action and action_foreach targets, args is the list of arguments\n"
291 " to pass to the script. Typically you would use source expansion (see\n"
292 " \"gn help source_expansion\") to insert the source file names.\n"
294 " See also \"gn help action\" and \"gn help action_foreach\".\n";
296 const char kCflags[] = "cflags";
297 const char kCflags_HelpShort[] =
298 "cflags: [string list] Flags passed to all C compiler variants.";
299 // Avoid writing long help for each variant.
300 #define COMMON_FLAGS_HELP \
302 " Flags are never quoted. If your flag includes a string that must be\n"\
303 " quoted, you must do it yourself. This also means that you can\n"\
304 " specify more than one flag in a string if necessary (\"--foo --bar\")\n"\
305 " and have them be seen as separate by the tool.\n"
306 const char kCommonCflagsHelp[] =
307 "cflags*: Flags passed to the C compiler.\n"
309 " A list of strings.\n"
311 " \"cflags\" are passed to all invocations of the C, C++, Objective C,\n"
312 " and Objective C++ compilers.\n"
314 " To target one of these variants individually, use \"cflags_c\",\n"
315 " \"cflags_cc\", \"cflags_objc\", and \"cflags_objcc\", respectively.\n"
316 " These variant-specific versions will be appended to the \"cflags\".\n"
318 COMMON_ORDERING_HELP;
319 const char* kCflags_Help = kCommonCflagsHelp;
321 const char kCflagsC[] = "cflags_c";
322 const char kCflagsC_HelpShort[] =
323 "cflags_c: [string list] Flags passed to the C compiler.";
324 const char* kCflagsC_Help = kCommonCflagsHelp;
326 const char kCflagsCC[] = "cflags_cc";
327 const char kCflagsCC_HelpShort[] =
328 "cflags_cc: [string list] Flags passed to the C++ compiler.";
329 const char* kCflagsCC_Help = kCommonCflagsHelp;
331 const char kCflagsObjC[] = "cflags_objc";
332 const char kCflagsObjC_HelpShort[] =
333 "cflags_objc: [string list] Flags passed to the Objective C compiler.";
334 const char* kCflagsObjC_Help = kCommonCflagsHelp;
336 const char kCflagsObjCC[] = "cflags_objcc";
337 const char kCflagsObjCC_HelpShort[] =
338 "cflags_objcc: [string list] Flags passed to the Objective C++ compiler.";
339 const char* kCflagsObjCC_Help = kCommonCflagsHelp;
341 const char kConfigs[] = "configs";
342 const char kConfigs_HelpShort[] =
343 "configs: [label list] Configs applying to this target.";
344 const char kConfigs_Help[] =
345 "configs: Configs applying to this target.\n"
347 " A list of config labels.\n"
349 " The include_dirs, defines, etc. in each config are appended in the\n"
350 " order they appear to the compile command for each file in the target.\n"
351 " They will appear after the include_dirs, defines, etc. that the target\n"
354 " The build configuration script will generally set up the default\n"
355 " configs applying to a given target type (see \"set_defaults\").\n"
356 " When a target is being defined, it can add to or remove from this\n"
361 " static_library(\"foo\") {\n"
362 " configs -= \"//build:no_rtti\" # Don't use the default RTTI config.\n"
363 " configs += \":mysettings\" # Add some of our own settings.\n"
366 const char kData[] = "data";
367 const char kData_HelpShort[] =
368 "data: [file list] Runtime data file dependencies.";
369 const char kData_Help[] =
370 "data: Runtime data file dependencies.\n"
372 " Lists files required to run the given target. These are typically\n"
375 " Appearing in the \"data\" section does not imply any special handling\n"
376 " such as copying them to the output directory. This is just used for\n"
377 " declaring runtime dependencies. There currently isn't a good use for\n"
378 " these but it is envisioned that test data can be listed here for use\n"
379 " running automated tests.\n"
381 " See also \"gn help source_prereqs\" and \"gn help datadeps\", both of\n"
382 " which actually affect the build in concrete ways.\n";
384 const char kDatadeps[] = "datadeps";
385 const char kDatadeps_HelpShort[] =
386 "datadeps: [label list] Non-linked dependencies.";
387 const char kDatadeps_Help[] =
388 "datadeps: Non-linked dependencies.\n"
390 " A list of target labels.\n"
392 " Specifies dependencies of a target that are not actually linked into\n"
393 " the current target. Such dependencies will built and will be available\n"
396 " This is normally used for things like plugins or helper programs that\n"
397 " a target needs at runtime.\n"
399 " See also \"gn help deps\" and \"gn help data\".\n"
402 " executable(\"foo\") {\n"
403 " deps = [ \"//base\" ]\n"
404 " datadeps = [ \"//plugins:my_runtime_plugin\" ]\n"
407 const char kDefines[] = "defines";
408 const char kDefines_HelpShort[] =
409 "defines: [string list] C preprocessor defines.";
410 const char kDefines_Help[] =
411 "defines: C preprocessor defines.\n"
413 " A list of strings\n"
415 " These strings will be passed to the C/C++ compiler as #defines. The\n"
416 " strings may or may not include an \"=\" to assign a value.\n"
420 " defines = [ \"AWESOME_FEATURE\", \"LOG_LEVEL=3\" ]\n";
422 const char kDepfile[] = "depfile";
423 const char kDepfile_HelpShort[] =
424 "depfile: [string] File name for input dependencies for actions.";
425 const char kDepfile_Help[] =
426 "depfile: [string] File name for input dependencies for actions.\n"
428 " If nonempty, this string specifies that the current action or\n"
429 " action_foreach target will generate the given \".d\" file containing\n"
430 " the dependencies of the input. Empty or unset means that the script\n"
431 " doesn't generate the files.\n"
433 " The .d file should go in the target output directory. If you have more\n"
434 " than one source file that the script is being run over, you can use\n"
435 " the output file expansions described in \"gn help action_foreach\" to\n"
436 " name the .d file according to the input."
438 " The format is that of a Makefile, and all of the paths should be\n"
439 " relative to the root build directory.\n"
442 " action_foreach(\"myscript_target\") {\n"
443 " script = \"myscript.py\"\n"
444 " sources = [ ... ]\n"
446 " # Locate the depfile in the output directory named like the\n"
447 " # inputs but with a \".d\" appended.\n"
448 " depfile = \"$relative_target_output_dir/{{source_name}}.d\"\n"
450 " # Say our script uses \"-o <d file>\" to indicate the depfile.\n"
451 " args = [ \"{{source}}\", \"-o\", depfile ]\n"
454 const char kDeps[] = "deps";
455 const char kDeps_HelpShort[] =
456 "deps: [label list] Linked dependencies.";
457 const char kDeps_Help[] =
458 "deps: Linked dependencies.\n"
460 " A list of target labels.\n"
462 " Specifies dependencies of a target. Shared and dynamic libraries will\n"
463 " be linked into the current target. Other target types that can't be\n"
464 " linked (like actions and groups) listed in \"deps\" will be treated\n"
465 " as \"datadeps\". Likewise, if the current target isn't linkable, then\n"
466 " all deps will be treated as \"datadeps\".\n"
468 " See also \"datadeps\".\n";
470 const char kDirectDependentConfigs[] = "direct_dependent_configs";
471 const char kDirectDependentConfigs_HelpShort[] =
472 "direct_dependent_configs: [label list] Configs to be forced on "
474 const char kDirectDependentConfigs_Help[] =
475 "direct_dependent_configs: Configs to be forced on dependents.\n"
477 " A list of config labels.\n"
479 " Targets directly referencing this one will have the configs listed in\n"
480 " this variable added to them. These configs will also apply to the\n"
483 " This addition happens in a second phase once a target and all of its\n"
484 " dependencies have been resolved. Therefore, a target will not see\n"
485 " these force-added configs in their \"configs\" variable while the\n"
486 " script is running, and then can not be removed. As a result, this\n"
487 " capability should generally only be used to add defines and include\n"
488 " directories necessary to compile a target's headers.\n"
490 " See also \"all_dependent_configs\".\n"
491 COMMON_ORDERING_HELP;
493 const char kForwardDependentConfigsFrom[] = "forward_dependent_configs_from";
494 const char kForwardDependentConfigsFrom_HelpShort[] =
495 "forward_dependent_configs_from: [label list] Forward dependent's configs.";
496 const char kForwardDependentConfigsFrom_Help[] =
497 "forward_dependent_configs_from\n"
499 " A list of target labels.\n"
501 " Exposes the direct_dependent_configs from a dependent target as\n"
502 " direct_dependent_configs of the current one. Each label in this list\n"
503 " must also be in the deps.\n"
505 " Sometimes you depend on a child library that exports some necessary\n"
506 " configuration via direct_dependent_configs. If your target in turn\n"
507 " exposes the child library's headers in its public headers, it might\n"
508 " mean that targets that depend on you won't work: they'll be seeing the\n"
509 " child library's code but not the necessary configuration. This list\n"
510 " specifies which of your deps' direct dependent configs to expose as\n"
515 " If we use a given library \"a\" from our public headers:\n"
517 " deps = [ \":a\", \":b\", ... ]\n"
518 " forward_dependent_configs_from = [ \":a\" ]\n"
520 " This example makes a \"transparent\" target that forwards a dependency\n"
523 " group(\"frob\") {\n"
524 " if (use_system_frob) {\n"
525 " deps = \":system_frob\"\n"
527 " deps = \"//third_party/fallback_frob\"\n"
529 " forward_dependent_configs_from = deps\n"
532 const char kIncludeDirs[] = "include_dirs";
533 const char kIncludeDirs_HelpShort[] =
534 "include_dirs: [directory list] Additional include directories.";
535 const char kIncludeDirs_Help[] =
536 "include_dirs: Additional include directories.\n"
538 " A list of source directories.\n"
540 " The directories in this list will be added to the include path for\n"
541 " the files in the affected target.\n"
545 " include_dirs = [ \"src/include\", \"//third_party/foo\" ]\n";
547 const char kLdflags[] = "ldflags";
548 const char kLdflags_HelpShort[] =
549 "ldflags: [string list] Flags passed to the linker.";
550 const char kLdflags_Help[] =
551 "ldflags: Flags passed to the linker.\n"
553 " A list of strings.\n"
555 " These flags are passed on the command-line to the linker and generally\n"
556 " specify various linking options. Most targets will not need these and\n"
557 " will use \"libs\" and \"lib_dirs\" instead.\n"
559 " ldflags are NOT pushed to dependents, so applying ldflags to source\n"
560 " sets or static libraries will be a no-op. If you want to apply ldflags\n"
561 " to dependent targets, put them in a config and set it in the\n"
562 " all_dependent_configs or direct_dependent_configs.\n"
565 #define COMMON_LIB_INHERITANCE_HELP \
567 " libs and lib_dirs work differently than other flags in two respects.\n" \
568 " First, then are inherited across static library boundaries until a\n" \
569 " shared library or executable target is reached. Second, they are\n" \
570 " uniquified so each one is only passed once (the first instance of it\n" \
571 " will be the one used).\n"
573 const char kLibDirs[] = "lib_dirs";
574 const char kLibDirs_HelpShort[] =
575 "lib_dirs: [directory list] Additional library directories.";
576 const char kLibDirs_Help[] =
577 "lib_dirs: Additional library directories.\n"
579 " A list of directories.\n"
581 " Specifies additional directories passed to the linker for searching\n"
582 " for the required libraries. If an item is not an absolute path, it\n"
583 " will be treated as being relative to the current build file.\n"
584 COMMON_LIB_INHERITANCE_HELP
588 " lib_dirs = [ \"/usr/lib/foo\", \"lib/doom_melon\" ]\n";
590 const char kLibs[] = "libs";
591 const char kLibs_HelpShort[] =
592 "libs: [string list] Additional libraries to link.";
593 const char kLibs_Help[] =
594 "libs: Additional libraries to link.\n"
596 " A list of strings.\n"
598 " These files will be passed to the linker, which will generally search\n"
599 " the library include path. Unlike a normal list of files, they will be\n"
600 " passed to the linker unmodified rather than being treated as file\n"
601 " names relative to the current build file. Generally you would set\n"
602 " the \"lib_dirs\" so your library is found. If you need to specify\n"
603 " a path, you can use \"rebase_path\" to convert a path to be relative\n"
604 " to the build directory.\n"
606 " When constructing the linker command, the \"lib_prefix\" attribute of\n"
607 " the linker tool in the current toolchain will be prepended to each\n"
608 " library. So your BUILD file should not specify the switch prefix\n"
609 " (like \"-l\"). On Mac, libraries ending in \".framework\" will be\n"
610 " special-cased: the switch \"-framework\" will be prepended instead of\n"
611 " the lib_prefix, and the \".framework\" suffix will be trimmed.\n"
612 COMMON_LIB_INHERITANCE_HELP
617 " libs = [ \"ctl3d.lib\" ]\n"
619 " libs = [ \"ld\" ]\n";
621 const char kOutputExtension[] = "output_extension";
622 const char kOutputExtension_HelpShort[] =
623 "output_extension: [string] Value to use for the output's file extension.";
624 const char kOutputExtension_Help[] =
625 "output_extension: Value to use for the output's file extension.\n"
627 " Normally the file extension for a target is based on the target\n"
628 " type and the operating system, but in rare cases you will need to\n"
629 " override the name (for example to use \"libfreetype.so.6\" instead\n"
630 " of libfreetype.so on Linux).";
632 const char kOutputName[] = "output_name";
633 const char kOutputName_HelpShort[] =
634 "output_name: [string] Name for the output file other than the default.";
635 const char kOutputName_Help[] =
636 "output_name: Define a name for the output file other than the default.\n"
638 " Normally the output name of a target will be based on the target name,\n"
639 " so the target \"//foo/bar:bar_unittests\" will generate an output\n"
640 " file such as \"bar_unittests.exe\" (using Windows as an example).\n"
642 " Sometimes you will want an alternate name to avoid collisions or\n"
643 " if the internal name isn't appropriate for public distribution.\n"
645 " The output name should have no extension or prefixes, these will be\n"
646 " added using the default system rules. For example, on Linux an output\n"
647 " name of \"foo\" will produce a shared library \"libfoo.so\".\n"
649 " This variable is valid for all binary output target types.\n"
652 " static_library(\"doom_melon\") {\n"
653 " output_name = \"fluffy_bunny\"\n"
656 const char kOutputs[] = "outputs";
657 const char kOutputs_HelpShort[] =
658 "outputs: [file list] Output files for actions and copy targets.";
659 const char kOutputs_Help[] =
660 "outputs: Output files for actions and copy targets.\n"
662 " Outputs is valid for \"copy\", \"action\", and \"action_foreach\"\n"
663 " target types and indicates the resulting files. The values may contain\n"
664 " source expansions to generate the output names from the sources (see\n"
665 " \"gn help source_expansion\").\n"
667 " For copy targets, the outputs is the destination for the copied\n"
668 " file(s). For actions, the outputs should be the list of files\n"
669 " generated by the script.\n";
671 const char kPublic[] = "public";
672 const char kPublic_HelpShort[] =
673 "public: [file list] Declare public header files for a target.";
674 const char kPublic_Help[] =
675 "public: Declare public header files for a target.\n"
677 " A list of files that other targets can include. These permissions are\n"
678 " checked via the \"check\" command (see \"gn help check\").\n"
680 " If no public files are declared, other targets (assuming they have\n"
681 " visibility to depend on this target can include any file in the\n"
682 " sources list. If this variable is defined on a target, dependent\n"
683 " targets may only include files on this whitelist.\n"
685 " Header file permissions are also subject to visibility. A target\n"
686 " must be visible to another target to include any files from it at all\n"
687 " and the public headers indicate which subset of those files are\n"
688 " permitted. See \"gn help visibility\" for more.\n"
690 " Public files are inherited through the dependency tree. So if there is\n"
691 " a dependency A -> B -> C, then A can include C's public headers.\n"
692 " However, the same is NOT true of visibility, so unless A is in C's\n"
693 " visibility list, the include will be rejected.\n"
695 " GN only knows about files declared in the \"sources\" and \"public\"\n"
696 " sections of targets. If a file is included that is now known to the\n"
697 " build, it will be allowed.\n"
700 " These exact files are public:\n"
701 " public = [ \"foo.h\", \"bar.h\" ]\n"
703 " No files are public (no targets may include headers from this one):\n"
706 const char kScript[] = "script";
707 const char kScript_HelpShort[] =
708 "script: [file name] Script file for actions.";
709 const char kScript_Help[] =
710 "script: Script file for actions.\n"
712 " An absolute or buildfile-relative file name of a Python script to run\n"
713 " for a action and action_foreach targets (see \"gn help action\" and\n"
714 " \"gn help action_foreach\").\n";
716 const char kSourcePrereqs[] = "source_prereqs";
717 const char kSourcePrereqs_HelpShort[] =
718 "source_prereqs: [file list] Additional compile-time dependencies.";
719 const char kSourcePrereqs_Help[] =
720 "source_prereqs: Additional compile-time dependencies.\n"
722 " Inputs are compile-time dependencies of the current target. This means\n"
723 " that all source prerequisites must be available before compiling any\n"
726 " If one of your sources #includes a generated file, that file must be\n"
727 " available before that source file is compiled. For subsequent builds,\n"
728 " the \".d\" files will list the include dependencies of each source\n"
729 " and Ninja can know about that dependency to make sure it's generated\n"
730 " before compiling your source file. However, for the first run it's\n"
731 " not possible for Ninja to know about this dependency.\n"
733 " Source prerequisites solves this problem by declaring such\n"
734 " dependencies. It will introduce a Ninja \"implicit\" dependency for\n"
735 " each source file in the target on the listed files.\n"
737 " For binary targets, the files in the \"source_prereqs\" should all be\n"
738 " listed in the \"outputs\" section of another target. There is no\n"
739 " reason to declare static source files as source prerequisites since\n"
740 " the normal include file dependency management will handle them more\n"
741 " efficiently anyway.\n"
743 " For action targets that don't generate \".d\" files, the\n"
744 " \"source_prereqs\" section is how you can list known compile-time\n"
745 " dependencies your script may have.\n"
747 " See also \"gn help data\" and \"gn help datadeps\" (which declare\n"
748 " run-time rather than compile-time dependencies).\n"
751 " executable(\"foo\") {\n"
752 " sources = [ \"foo.cc\" ]\n"
753 " source_prereqs = [ \"$root_gen_dir/something/generated_data.h\" ]\n"
756 " action(\"myscript\") {\n"
757 " script = \"domything.py\"\n"
758 " source_prereqs = [ \"input.data\" ]\n"
761 const char kSources[] = "sources";
762 const char kSources_HelpShort[] =
763 "sources: [file list] Source files for a target.";
764 const char kSources_Help[] =
765 "sources: Source files for a target\n"
767 " A list of files relative to the current buildfile.\n";
769 const char kVisibility[] = "visibility";
770 const char kVisibility_HelpShort[] =
771 "visibility: [label list] A list of labels that can depend on a target.";
772 const char kVisibility_Help[] =
773 "visibility: A list of labels that can depend on a target.\n"
775 " A label or a list of labels and label patterns that define which\n"
776 " targets can depend on the current one. These permissions are checked\n"
777 " via then \"check\" command (see \"gn help check\").\n"
779 " If visibility is not defined, it defaults to public (\"*\").\n"
781 " If visibility is defined, only the targets with labels that match it\n"
782 " can depend on the current target. The empty list means no targets\n"
783 " can depend on the current target.\n"
785 " Tip: Often you will want the same visibility for all targets in a\n"
786 " BUILD file. In this case you can just put the definition at the top,\n"
787 " outside of any target, and the targets will inherit that scope and see\n"
792 " You can specify \"*\" but the inputs aren't general patterns. The\n"
793 " following classes of patterns are supported:\n"
795 " - Explicit (no wildcard):\n"
796 " \"//foo/bar:baz\"\n"
798 " - Wildcard target names:\n"
799 " \"//foo/bar:*\" (any target in the //foo/bar/BUILD.gn file)\n"
800 " \":*\" (any target in the current build file)\n"
801 " - Wildcard directory names (\"*\" is only supported at the end)\n"
802 " \"*\" (any target anywhere)\n"
803 " \"//foo/bar/*\" (any target in any subdir of //foo/bar)\n"
804 " \"./*\" (any target in the current build file or sub dirs)\n"
806 " The toolchain (normally an implicit part of a label) is ignored when\n"
807 " checking visibility.\n"
811 " Only targets in the current buildfile (\"private\", the default):\n"
812 " visibility = \":*\"\n"
814 " No targets (used for targets that should be leaf nodes):\n"
817 " Any target (\"public\"):\n"
818 " visibility = \"*\"\n"
820 " All targets in the current directory and any subdirectory:\n"
821 " visibility = \"./*\"\n"
823 " Any target in \"//bar/BUILD.gn\":\n"
824 " visibility = \"//bar:*\"\n"
826 " Any target in \"//bar/\" or any subdirectory thereof:\n"
827 " visibility = \"//bar/*\"\n"
829 " Just these specific targets:\n"
830 " visibility = [ \":mything\", \"//foo:something_else\" ]\n"
832 " Any target in the current directory and any subdirectory thereof, plus\n"
833 " any targets in \"//bar/\" and any subdirectory thereof.\n"
834 " visibility = [ \"./*\", \"//bar/*\" ]\n";
836 // -----------------------------------------------------------------------------
838 VariableInfo::VariableInfo()
843 VariableInfo::VariableInfo(const char* in_help_short, const char* in_help)
844 : help_short(in_help_short),
848 #define INSERT_VARIABLE(var) \
849 info_map[k##var] = VariableInfo(k##var##_HelpShort, k##var##_Help);
851 const VariableInfoMap& GetBuiltinVariables() {
852 static VariableInfoMap info_map;
853 if (info_map.empty()) {
854 INSERT_VARIABLE(BuildCpuArch)
855 INSERT_VARIABLE(BuildOs)
856 INSERT_VARIABLE(CpuArch)
857 INSERT_VARIABLE(ComponentMode)
858 INSERT_VARIABLE(CurrentToolchain)
859 INSERT_VARIABLE(DefaultToolchain)
861 INSERT_VARIABLE(PythonPath)
862 INSERT_VARIABLE(RootBuildDir)
863 INSERT_VARIABLE(RootGenDir)
864 INSERT_VARIABLE(RootOutDir)
865 INSERT_VARIABLE(TargetGenDir)
866 INSERT_VARIABLE(TargetOutDir)
871 const VariableInfoMap& GetTargetVariables() {
872 static VariableInfoMap info_map;
873 if (info_map.empty()) {
874 INSERT_VARIABLE(AllDependentConfigs)
875 INSERT_VARIABLE(Args)
876 INSERT_VARIABLE(Cflags)
877 INSERT_VARIABLE(CflagsC)
878 INSERT_VARIABLE(CflagsCC)
879 INSERT_VARIABLE(CflagsObjC)
880 INSERT_VARIABLE(CflagsObjCC)
881 INSERT_VARIABLE(Configs)
882 INSERT_VARIABLE(Data)
883 INSERT_VARIABLE(Datadeps)
884 INSERT_VARIABLE(Depfile)
885 INSERT_VARIABLE(Deps)
886 INSERT_VARIABLE(DirectDependentConfigs)
887 INSERT_VARIABLE(ForwardDependentConfigsFrom)
888 INSERT_VARIABLE(IncludeDirs)
889 INSERT_VARIABLE(Ldflags)
890 INSERT_VARIABLE(Libs)
891 INSERT_VARIABLE(LibDirs)
892 INSERT_VARIABLE(OutputExtension)
893 INSERT_VARIABLE(OutputName)
894 INSERT_VARIABLE(Outputs)
895 INSERT_VARIABLE(Public)
896 INSERT_VARIABLE(Script)
897 INSERT_VARIABLE(SourcePrereqs)
898 INSERT_VARIABLE(Sources)
899 INSERT_VARIABLE(Visibility)
904 #undef INSERT_VARIABLE
906 } // namespace variables