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. 4 5 #include "tools/gn/variables.h" 6 7 namespace variables { 8 9 // Built-in variables ---------------------------------------------------------- 10 11 const char kCpuArch[] = "cpu_arch"; 12 const char kCpuArch_HelpShort[] = 13 "cpu_arch: [string] Current processor architecture."; 14 const char kCpuArch_Help[] = 15 "cpu_arch: Current processor architecture.\n" 16 "\n" 17 " The initial value is based on the current architecture of the host\n" 18 " system. However, the build configuration can set this to any value.\n" 19 "\n" 20 " This value is not used internally by GN for any purpose, so you can\n" 21 " set it to whatever value is relevant to your build.\n" 22 "\n" 23 "Possible initial values set by GN:\n" 24 " - \"x86\"\n" 25 " - \"x64\"\n" 26 " - \"arm\"\n" 27 " - \"mipsel\"\n"; 28 29 const char kCurrentToolchain[] = "current_toolchain"; 30 const char kCurrentToolchain_HelpShort[] = 31 "current_toolchain: [string] Label of the current toolchain."; 32 const char kCurrentToolchain_Help[] = 33 "current_toolchain: Label of the current toolchain.\n" 34 "\n" 35 " A fully-qualified label representing the current toolchain. You can\n" 36 " use this to make toolchain-related decisions in the build. See also\n" 37 " \"default_toolchain\".\n" 38 "\n" 39 "Example:\n" 40 "\n" 41 " if (current_toolchain == \"//build:64_bit_toolchain\") {\n" 42 " executable(\"output_thats_64_bit_only\") {\n" 43 " ...\n"; 44 45 const char kBuildCpuArch[] = "build_cpu_arch"; 46 const char kBuildCpuArch_HelpShort[] = 47 "build_cpu_arch: [string] The default value for the \"cpu_arch\" " 48 "variable."; 49 const char kBuildCpuArch_Help[] = 50 "build_cpu_arch: The default value for the \"cpu_arch\" variable.\n" 51 "\n" 52 " This value has the same definition as \"cpu_arch\" (see\n" 53 " \"gn help cpu_arch\") but should be treated as read-only. This is so\n" 54 " the build can override the \"cpu_arch\" variable for doing\n" 55 " cross-compiles, but can still access the host build system's CPU\n" 56 " architecture.\n"; 57 58 const char kBuildOs[] = "build_os"; 59 const char kBuildOs_HelpShort[] = 60 "build_os: [string] The default value for the \"os\" variable."; 61 const char kBuildOs_Help[] = 62 "build_os: [string] The default value for the \"os\" variable.\n" 63 "\n" 64 " This value has the same definition as \"os\" (see \"gn help os\") but\n" 65 " should be treated as read-only. This is so the build can override\n" 66 " the \"os\" variable for doing cross-compiles, but can still access\n" 67 " the host build system's operating system type.\n"; 68 69 const char kDefaultToolchain[] = "default_toolchain"; 70 const char kDefaultToolchain_HelpShort[] = 71 "default_toolchain: [string] Label of the default toolchain."; 72 const char kDefaultToolchain_Help[] = 73 "default_toolchain: [string] Label of the default toolchain.\n" 74 "\n" 75 " A fully-qualified label representing the default toolchain, which may\n" 76 " not necessarily be the current one (see \"current_toolchain\").\n"; 77 78 const char kOs[] = "os"; 79 const char kOs_HelpShort[] = 80 "os: [string] Indicates the operating system of the current build."; 81 const char kOs_Help[] = 82 "os: Indicates the operating system of the current build." 83 "\n" 84 " This value is set by default based on the current host operating\n" 85 " system. The build configuration can override the value to anything\n" 86 " it wants, or it can be set via the build arguments on the command\n" 87 " line.\n" 88 "\n" 89 " If you want to know the default value without any overrides, you can\n" 90 " use \"default_os\" (see \"gn help default_os\").\n" 91 "\n" 92 " Note that this returns the most specific value. So even though\n" 93 " Android and ChromeOS are both Linux, the more specific value will\n" 94 " be returned.\n" 95 "\n" 96 "Some possible values:\n" 97 " - \"amiga\"\n" 98 " - \"android\"\n" 99 " - \"chromeos\"\n" 100 " - \"ios\"\n" 101 " - \"linux\"\n" 102 " - \"mac\"\n" 103 " - \"win\"\n"; 104 105 const char kPythonPath[] = "python_path"; 106 const char kPythonPath_HelpShort[] = 107 "python_path: [string] Absolute path of Python."; 108 const char kPythonPath_Help[] = 109 "python_path: Absolute path of Python.\n" 110 "\n" 111 " Normally used in toolchain definitions if running some command\n" 112 " requires Python. You will normally not need this when invoking scripts\n" 113 " since GN automatically finds it for you.\n"; 114 115 const char kRootBuildDir[] = "root_build_dir"; 116 const char kRootBuildDir_HelpShort[] = 117 "root_build_dir: [string] Directory where build commands are run."; 118 const char kRootBuildDir_Help[] = 119 "root_build_dir: [string] Directory where build commands are run.\n" 120 "\n" 121 " This is the root build output directory which will be the current\n" 122 " directory when executing all compilers and scripts.\n" 123 "\n" 124 " Most often this is used with rebase_path (see \"gn help rebase_path\")\n" 125 " to convert arguments to be relative to a script's current directory.\n"; 126 127 const char kRootGenDir[] = "root_gen_dir"; 128 const char kRootGenDir_HelpShort[] = 129 "root_gen_dir: [string] Directory for the toolchain's generated files."; 130 const char kRootGenDir_Help[] = 131 "root_gen_dir: Directory for the toolchain's generated files.\n" 132 "\n" 133 " Absolute path to the root of the generated output directory tree for\n" 134 " the current toolchain. An example value might be \"//out/Debug/gen\".\n" 135 " It will not have a trailing slash.\n" 136 "\n" 137 " This is primarily useful for setting up include paths for generated\n" 138 " files. If you are passing this to a script, you will want to pass it\n" 139 " through rebase_path() (see \"gn help rebase_path\") to convert it\n" 140 " to be relative to the build directory.\n" 141 "\n" 142 " See also \"target_gen_dir\" which is usually a better location for\n" 143 " generated files. It will be inside the root generated dir.\n"; 144 145 const char kRootOutDir[] = "root_out_dir"; 146 const char kRootOutDir_HelpShort[] = 147 "root_out_dir: [string] Root directory for toolchain output files."; 148 const char kRootOutDir_Help[] = 149 "root_out_dir: [string] Root directory for toolchain output files.\n" 150 "\n" 151 " Absolute path to the root of the output directory tree for the current\n" 152 " toolchain. An example value might be \"//out/Debug/gen\". It will not\n" 153 " have a trailing slash.\n" 154 "\n" 155 " This is primarily useful for setting up script calls. If you are\n" 156 " passing this to a script, you will want to pass it through\n" 157 " rebase_path() (see \"gn help rebase_path\") to convert it\n" 158 " to be relative to the build directory.\n" 159 "\n" 160 " See also \"target_out_dir\" which is usually a better location for\n" 161 " output files. It will be inside the root output dir.\n" 162 "\n" 163 "Example:\n" 164 "\n" 165 " action(\"myscript\") {\n" 166 " # Pass the output dir to the script.\n" 167 " args = [ \"-o\", rebase_path(root_out_dir, root_build_dir) ]\n" 168 " }\n"; 169 170 const char kTargetGenDir[] = "target_gen_dir"; 171 const char kTargetGenDir_HelpShort[] = 172 "target_gen_dir: [string] Directory for a target's generated files."; 173 const char kTargetGenDir_Help[] = 174 "target_gen_dir: Directory for a target's generated files.\n" 175 "\n" 176 " Absolute path to the target's generated file directory. If your\n" 177 " current target is in \"//tools/doom_melon\" then this value might be\n" 178 " \"//out/Debug/gen/tools/doom_melon\". It will not have a trailing\n" 179 " slash.\n" 180 "\n" 181 " This is primarily useful for setting up include paths for generated\n" 182 " files. If you are passing this to a script, you will want to pass it\n" 183 " through rebase_path() (see \"gn help rebase_path\") to convert it\n" 184 " to be relative to the build directory.\n" 185 "\n" 186 " See also \"gn help root_gen_dir\".\n" 187 "\n" 188 "Example:\n" 189 "\n" 190 " action(\"myscript\") {\n" 191 " # Pass the generated output dir to the script.\n" 192 " args = [ \"-o\", rebase_path(target_gen_dir, root_build_dir) ]" 193 "\n" 194 " }\n"; 195 196 const char kTargetOutDir[] = "target_out_dir"; 197 const char kTargetOutDir_HelpShort[] = 198 "target_out_dir: [string] Directory for target output files."; 199 const char kTargetOutDir_Help[] = 200 "target_out_dir: [string] Directory for target output files.\n" 201 "\n" 202 " Absolute path to the target's generated file directory. If your\n" 203 " current target is in \"//tools/doom_melon\" then this value might be\n" 204 " \"//out/Debug/obj/tools/doom_melon\". It will not have a trailing\n" 205 " slash.\n" 206 "\n" 207 " This is primarily useful for setting up arguments for calling\n" 208 " scripts. If you are passing this to a script, you will want to pass it\n" 209 " through rebase_path() (see \"gn help rebase_path\") to convert it\n" 210 " to be relative to the build directory.\n" 211 "\n" 212 " See also \"gn help root_out_dir\".\n" 213 "\n" 214 "Example:\n" 215 "\n" 216 " action(\"myscript\") {\n" 217 " # Pass the output dir to the script.\n" 218 " args = [ \"-o\", rebase_path(target_out_dir, root_build_dir) ]" 219 "\n" 220 " }\n"; 221 222 // Target variables ------------------------------------------------------------ 223 224 #define COMMON_ORDERING_HELP \ 225 "\n" \ 226 "Ordering of flags and values:\n" \ 227 "\n" \ 228 " 1. Those set on the current target (not in a config).\n" \ 229 " 2. Those set on the \"configs\" on the target in order that the\n" \ 230 " configs appear in the list.\n" \ 231 " 3. Those set on the \"all_dependent_configs\" on the target in order\n" \ 232 " that the configs appear in the list.\n" \ 233 " 4. Those set on the \"public_configs\" on the target in order that\n" \ 234 " those configs appear in the list.\n" \ 235 " 5. all_dependent_configs pulled from dependencies, in the order of\n" \ 236 " the \"deps\" list. This is done recursively. If a config appears\n" \ 237 " more than once, only the first occurance will be used.\n" \ 238 " 6. public_configs pulled from dependencies, in the order of the\n" \ 239 " \"deps\" list. If a dependency has " \ 240 "\"forward_dependent_configs_from\",\n" \ 241 " or are public dependencies, they will be applied recursively.\n" 242 243 const char kAllDependentConfigs[] = "all_dependent_configs"; 244 const char kAllDependentConfigs_HelpShort[] = 245 "all_dependent_configs: [label list] Configs to be forced on dependents."; 246 const char kAllDependentConfigs_Help[] = 247 "all_dependent_configs: Configs to be forced on dependents.\n" 248 "\n" 249 " A list of config labels.\n" 250 "\n" 251 " All targets depending on this one, and recursively, all targets\n" 252 " depending on those, will have the configs listed in this variable\n" 253 " added to them. These configs will also apply to the current target.\n" 254 "\n" 255 " This addition happens in a second phase once a target and all of its\n" 256 " dependencies have been resolved. Therefore, a target will not see\n" 257 " these force-added configs in their \"configs\" variable while the\n" 258 " script is running, and then can not be removed. As a result, this\n" 259 " capability should generally only be used to add defines and include\n" 260 " directories necessary to compile a target's headers.\n" 261 "\n" 262 " See also \"public_configs\".\n" 263 COMMON_ORDERING_HELP; 264 265 const char kAllowCircularIncludesFrom[] = "allow_circular_includes_from"; 266 const char kAllowCircularIncludesFrom_HelpShort[] = 267 "allow_circular_includes_from: [label list] Permit includes from deps."; 268 const char kAllowCircularIncludesFrom_Help[] = 269 "allow_circular_includes_from: Permit includes from deps.\n" 270 "\n" 271 " A list of target labels. Must be a subset of the target's \"deps\".\n" 272 " These targets will be permitted to include headers from the current\n" 273 " target despite the dependency going in the opposite direction.\n" 274 "\n" 275 "Tedious exposition\n" 276 "\n" 277 " Normally, for a file in target A to include a file from target B,\n" 278 " A must list B as a dependency. This invariant is enforced by the\n" 279 " \"gn check\" command (and the --check flag to \"gn gen\").\n" 280 "\n" 281 " Sometimes, two targets might be the same unit for linking purposes\n" 282 " (two source sets or static libraries that would always be linked\n" 283 " together in a final executable or shared library). In this case,\n" 284 " you want A to be able to include B's headers, and B to include A's\n" 285 " headers.\n" 286 "\n" 287 " This list, if specified, lists which of the dependencies of the\n" 288 " current target can include header files from the current target.\n" 289 " That is, if A depends on B, B can only include headers from A if it is\n" 290 " in A's allow_circular_includes_from list.\n" 291 "\n" 292 "Example\n" 293 "\n" 294 " source_set(\"a\") {\n" 295 " deps = [ \":b\", \":c\" ]\n" 296 " allow_circular_includes_from = [ \":b\" ]\n" 297 " ...\n" 298 " }\n"; 299 300 const char kArgs[] = "args"; 301 const char kArgs_HelpShort[] = 302 "args: [string list] Arguments passed to an action."; 303 const char kArgs_Help[] = 304 "args: Arguments passed to an action.\n" 305 "\n" 306 " For action and action_foreach targets, args is the list of arguments\n" 307 " to pass to the script. Typically you would use source expansion (see\n" 308 " \"gn help source_expansion\") to insert the source file names.\n" 309 "\n" 310 " See also \"gn help action\" and \"gn help action_foreach\".\n"; 311 312 const char kCflags[] = "cflags"; 313 const char kCflags_HelpShort[] = 314 "cflags: [string list] Flags passed to all C compiler variants."; 315 const char kCommonCflagsHelp[] = 316 "cflags*: Flags passed to the C compiler.\n" 317 "\n" 318 " A list of strings.\n" 319 "\n" 320 " \"cflags\" are passed to all invocations of the C, C++, Objective C,\n" 321 " and Objective C++ compilers.\n" 322 "\n" 323 " To target one of these variants individually, use \"cflags_c\",\n" 324 " \"cflags_cc\", \"cflags_objc\", and \"cflags_objcc\", respectively.\n" 325 " These variant-specific versions will be appended to the \"cflags\".\n" 326 COMMON_ORDERING_HELP; 327 const char* kCflags_Help = kCommonCflagsHelp; 328 329 const char kCflagsC[] = "cflags_c"; 330 const char kCflagsC_HelpShort[] = 331 "cflags_c: [string list] Flags passed to the C compiler."; 332 const char* kCflagsC_Help = kCommonCflagsHelp; 333 334 const char kCflagsCC[] = "cflags_cc"; 335 const char kCflagsCC_HelpShort[] = 336 "cflags_cc: [string list] Flags passed to the C++ compiler."; 337 const char* kCflagsCC_Help = kCommonCflagsHelp; 338 339 const char kCflagsObjC[] = "cflags_objc"; 340 const char kCflagsObjC_HelpShort[] = 341 "cflags_objc: [string list] Flags passed to the Objective C compiler."; 342 const char* kCflagsObjC_Help = kCommonCflagsHelp; 343 344 const char kCflagsObjCC[] = "cflags_objcc"; 345 const char kCflagsObjCC_HelpShort[] = 346 "cflags_objcc: [string list] Flags passed to the Objective C++ compiler."; 347 const char* kCflagsObjCC_Help = kCommonCflagsHelp; 348 349 const char kCheckIncludes[] = "check_includes"; 350 const char kCheckIncludes_HelpShort[] = 351 "check_includes: [boolean] Controls whether a target's files are checked."; 352 const char kCheckIncludes_Help[] = 353 "check_includes: [boolean] Controls whether a target's files are checked.\n" 354 "\n" 355 " When true (the default), the \"gn check\" command (as well as\n" 356 " \"gn gen\" with the --check flag) will check this target's sources\n" 357 " and headers for proper dependencies.\n" 358 "\n" 359 " When false, the files in this target will be skipped by default.\n" 360 " This does not affect other targets that depend on the current target,\n" 361 " it just skips checking the includes of the current target's files.\n" 362 "\n" 363 "Example\n" 364 "\n" 365 " source_set(\"busted_includes\") {\n" 366 " # This target's includes are messed up, exclude it from checking.\n" 367 " check_includes = false\n" 368 " ...\n" 369 " }\n"; 370 371 const char kCompleteStaticLib[] = "complete_static_lib"; 372 const char kCompleteStaticLib_HelpShort[] = 373 "complete_static_lib: [boolean] Links all deps into a static library."; 374 const char kCompleteStaticLib_Help[] = 375 "complete_static_lib: [boolean] Links all deps into a static library.\n" 376 "\n" 377 " A static library normally doesn't include code from dependencies, but\n" 378 " instead forwards the static libraries and source sets in its deps up\n" 379 " the dependency chain until a linkable target (an executable or shared\n" 380 " library) is reached. The final linkable target only links each static\n" 381 " library once, even if it appears more than once in its dependency\n" 382 " graph.\n" 383 "\n" 384 " In some cases the static library might be the final desired output.\n" 385 " For example, you may be producing a static library for distribution to\n" 386 " third parties. In this case, the static library should include code\n" 387 " for all dependencies in one complete package. Since GN does not unpack\n" 388 " static libraries to forward their contents up the dependency chain,\n" 389 " it is an error for complete static libraries to depend on other static\n" 390 " libraries.\n" 391 "\n" 392 "Example\n" 393 "\n" 394 " static_library(\"foo\") {\n" 395 " complete_static_lib = true\n" 396 " deps = [ \"bar\" ]\n" 397 " }\n"; 398 399 const char kConfigs[] = "configs"; 400 const char kConfigs_HelpShort[] = 401 "configs: [label list] Configs applying to this target."; 402 const char kConfigs_Help[] = 403 "configs: Configs applying to this target.\n" 404 "\n" 405 " A list of config labels.\n" 406 "\n" 407 " The include_dirs, defines, etc. in each config are appended in the\n" 408 " order they appear to the compile command for each file in the target.\n" 409 " They will appear after the include_dirs, defines, etc. that the target\n" 410 " sets directly.\n" 411 "\n" 412 " The build configuration script will generally set up the default\n" 413 " configs applying to a given target type (see \"set_defaults\").\n" 414 " When a target is being defined, it can add to or remove from this\n" 415 " list.\n" 416 COMMON_ORDERING_HELP 417 "\n" 418 "Example:\n" 419 " static_library(\"foo\") {\n" 420 " configs -= \"//build:no_rtti\" # Don't use the default RTTI config.\n" 421 " configs += \":mysettings\" # Add some of our own settings.\n" 422 " }\n"; 423 424 const char kData[] = "data"; 425 const char kData_HelpShort[] = 426 "data: [file list] Runtime data file dependencies."; 427 const char kData_Help[] = 428 "data: Runtime data file dependencies.\n" 429 "\n" 430 " Lists files required to run the given target. These are typically\n" 431 " data files.\n" 432 "\n" 433 " Appearing in the \"data\" section does not imply any special handling\n" 434 " such as copying them to the output directory. This is just used for\n" 435 " declaring runtime dependencies. There currently isn't a good use for\n" 436 " these but it is envisioned that test data can be listed here for use\n" 437 " running automated tests.\n" 438 "\n" 439 " See also \"gn help inputs\" and \"gn help data_deps\", both of\n" 440 " which actually affect the build in concrete ways.\n"; 441 442 const char kDataDeps[] = "data_deps"; 443 const char kDataDeps_HelpShort[] = 444 "data_deps: [label list] Non-linked dependencies."; 445 const char kDataDeps_Help[] = 446 "data_deps: Non-linked dependencies.\n" 447 "\n" 448 " A list of target labels.\n" 449 "\n" 450 " Specifies dependencies of a target that are not actually linked into\n" 451 " the current target. Such dependencies will built and will be available\n" 452 " at runtime.\n" 453 "\n" 454 " This is normally used for things like plugins or helper programs that\n" 455 " a target needs at runtime.\n" 456 "\n" 457 " See also \"gn help deps\" and \"gn help data\".\n" 458 "\n" 459 "Example:\n" 460 " executable(\"foo\") {\n" 461 " deps = [ \"//base\" ]\n" 462 " data_deps = [ \"//plugins:my_runtime_plugin\" ]\n" 463 " }\n"; 464 465 const char kDefines[] = "defines"; 466 const char kDefines_HelpShort[] = 467 "defines: [string list] C preprocessor defines."; 468 const char kDefines_Help[] = 469 "defines: C preprocessor defines.\n" 470 "\n" 471 " A list of strings\n" 472 "\n" 473 " These strings will be passed to the C/C++ compiler as #defines. The\n" 474 " strings may or may not include an \"=\" to assign a value.\n" 475 COMMON_ORDERING_HELP 476 "\n" 477 "Example:\n" 478 " defines = [ \"AWESOME_FEATURE\", \"LOG_LEVEL=3\" ]\n"; 479 480 const char kDepfile[] = "depfile"; 481 const char kDepfile_HelpShort[] = 482 "depfile: [string] File name for input dependencies for actions."; 483 const char kDepfile_Help[] = 484 "depfile: [string] File name for input dependencies for actions.\n" 485 "\n" 486 " If nonempty, this string specifies that the current action or\n" 487 " action_foreach target will generate the given \".d\" file containing\n" 488 " the dependencies of the input. Empty or unset means that the script\n" 489 " doesn't generate the files.\n" 490 "\n" 491 " The .d file should go in the target output directory. If you have more\n" 492 " than one source file that the script is being run over, you can use\n" 493 " the output file expansions described in \"gn help action_foreach\" to\n" 494 " name the .d file according to the input." 495 "\n" 496 " The format is that of a Makefile, and all of the paths should be\n" 497 " relative to the root build directory.\n" 498 "\n" 499 "Example:\n" 500 " action_foreach(\"myscript_target\") {\n" 501 " script = \"myscript.py\"\n" 502 " sources = [ ... ]\n" 503 "\n" 504 " # Locate the depfile in the output directory named like the\n" 505 " # inputs but with a \".d\" appended.\n" 506 " depfile = \"$relative_target_output_dir/{{source_name}}.d\"\n" 507 "\n" 508 " # Say our script uses \"-o <d file>\" to indicate the depfile.\n" 509 " args = [ \"{{source}}\", \"-o\", depfile ]\n" 510 " }\n"; 511 512 const char kDeps[] = "deps"; 513 const char kDeps_HelpShort[] = 514 "deps: [label list] Private linked dependencies."; 515 const char kDeps_Help[] = 516 "deps: Private linked dependencies.\n" 517 "\n" 518 " A list of target labels.\n" 519 "\n" 520 " Specifies private dependencies of a target. Shared and dynamic\n" 521 " libraries will be linked into the current target. Other target types\n" 522 " that can't be linked (like actions and groups) listed in \"deps\" will\n" 523 " be treated as \"data_deps\". Likewise, if the current target isn't\n" 524 " linkable, then all deps will be treated as \"data_deps\".\n" 525 "\n" 526 " These dependencies are private in that it does not grant dependent\n" 527 " targets the ability to include headers from the dependency, and direct\n" 528 " dependent configs are not forwarded.\n" 529 "\n" 530 " See also \"public_deps\" and \"data_deps\".\n"; 531 532 const char kForwardDependentConfigsFrom[] = "forward_dependent_configs_from"; 533 const char kForwardDependentConfigsFrom_HelpShort[] = 534 "forward_dependent_configs_from: [label list] Forward dependent's configs."; 535 const char kForwardDependentConfigsFrom_Help[] = 536 "forward_dependent_configs_from\n" 537 "\n" 538 " A list of target labels.\n" 539 "\n" 540 " Exposes the public_configs from a private dependent target as\n" 541 " public_configs of the current one. Each label in this list\n" 542 " must also be in the deps.\n" 543 "\n" 544 " Generally you should use public_deps instead of this variable to\n" 545 " express the concept of exposing a dependency as part of a target's\n" 546 " public API. We're considering removing this variable.\n" 547 "\n" 548 "Discussion\n" 549 "\n" 550 " Sometimes you depend on a child library that exports some necessary\n" 551 " configuration via public_configs. If your target in turn exposes the\n" 552 " child library's headers in its public headers, it might mean that\n" 553 " targets that depend on you won't work: they'll be seeing the child\n" 554 " library's code but not the necessary configuration. This list\n" 555 " specifies which of your deps' direct dependent configs to expose as\n" 556 " your own.\n" 557 "\n" 558 "Examples\n" 559 "\n" 560 " If we use a given library \"a\" from our public headers:\n" 561 "\n" 562 " deps = [ \":a\", \":b\", ... ]\n" 563 " forward_dependent_configs_from = [ \":a\" ]\n" 564 "\n" 565 " This example makes a \"transparent\" target that forwards a dependency\n" 566 " to another:\n" 567 "\n" 568 " group(\"frob\") {\n" 569 " if (use_system_frob) {\n" 570 " deps = \":system_frob\"\n" 571 " } else {\n" 572 " deps = \"//third_party/fallback_frob\"\n" 573 " }\n" 574 " forward_dependent_configs_from = deps\n" 575 " }\n"; 576 577 const char kIncludeDirs[] = "include_dirs"; 578 const char kIncludeDirs_HelpShort[] = 579 "include_dirs: [directory list] Additional include directories."; 580 const char kIncludeDirs_Help[] = 581 "include_dirs: Additional include directories.\n" 582 "\n" 583 " A list of source directories.\n" 584 "\n" 585 " The directories in this list will be added to the include path for\n" 586 " the files in the affected target.\n" 587 COMMON_ORDERING_HELP 588 "\n" 589 "Example:\n" 590 " include_dirs = [ \"src/include\", \"//third_party/foo\" ]\n"; 591 592 const char kInputs[] = "inputs"; 593 const char kInputs_HelpShort[] = 594 "inputs: [file list] Additional compile-time dependencies."; 595 const char kInputs_Help[] = 596 "inputs: Additional compile-time dependencies.\n" 597 "\n" 598 " Inputs are compile-time dependencies of the current target. This means\n" 599 " that all inputs must be available before compiling any of the sources\n" 600 " or executing any actions.\n" 601 "\n" 602 " Inputs are typically only used for action and action_foreach targets.\n" 603 "\n" 604 "Inputs for actions\n" 605 "\n" 606 " For action and action_foreach targets, inputs should be the inputs to\n" 607 " script that don't vary. These should be all .py files that the script\n" 608 " uses via imports (the main script itself will be an implcit dependency\n" 609 " of the action so need not be listed).\n" 610 "\n" 611 " For action targets, inputs should be the entire set of inputs the\n" 612 " script needs. For action_foreach targets, inputs should be the set of\n" 613 " dependencies that don't change. These will be applied to each script\n" 614 " invocation over the sources.\n" 615 "\n" 616 " Note that another way to declare input dependencies from an action\n" 617 " is to have the action write a depfile (see \"gn help depfile\"). This\n" 618 " allows the script to dynamically write input dependencies, that might\n" 619 " not be known until actually executing the script. This is more\n" 620 " efficient than doing processing while running GN to determine the\n" 621 " inputs, and is easier to keep in-sync than hardcoding the list.\n" 622 "\n" 623 "Inputs for binary targets\n" 624 "\n" 625 " Any input dependencies will be resolved before compiling any sources.\n" 626 " Normally, all actions that a target depends on will be run before any\n" 627 " files in a target are compiled. So if you depend on generated headers,\n" 628 " you do not typically need to list them in the inputs section.\n" 629 "\n" 630 "Example\n" 631 "\n" 632 " action(\"myscript\") {\n" 633 " script = \"domything.py\"\n" 634 " inputs = [ \"input.data\" ]\n" 635 " }\n"; 636 637 const char kLdflags[] = "ldflags"; 638 const char kLdflags_HelpShort[] = 639 "ldflags: [string list] Flags passed to the linker."; 640 const char kLdflags_Help[] = 641 "ldflags: Flags passed to the linker.\n" 642 "\n" 643 " A list of strings.\n" 644 "\n" 645 " These flags are passed on the command-line to the linker and generally\n" 646 " specify various linking options. Most targets will not need these and\n" 647 " will use \"libs\" and \"lib_dirs\" instead.\n" 648 "\n" 649 " ldflags are NOT pushed to dependents, so applying ldflags to source\n" 650 " sets or static libraries will be a no-op. If you want to apply ldflags\n" 651 " to dependent targets, put them in a config and set it in the\n" 652 " all_dependent_configs or public_configs.\n"; 653 654 #define COMMON_LIB_INHERITANCE_HELP \ 655 "\n" \ 656 " libs and lib_dirs work differently than other flags in two respects.\n" \ 657 " First, then are inherited across static library boundaries until a\n" \ 658 " shared library or executable target is reached. Second, they are\n" \ 659 " uniquified so each one is only passed once (the first instance of it\n" \ 660 " will be the one used).\n" 661 662 const char kLibDirs[] = "lib_dirs"; 663 const char kLibDirs_HelpShort[] = 664 "lib_dirs: [directory list] Additional library directories."; 665 const char kLibDirs_Help[] = 666 "lib_dirs: Additional library directories.\n" 667 "\n" 668 " A list of directories.\n" 669 "\n" 670 " Specifies additional directories passed to the linker for searching\n" 671 " for the required libraries. If an item is not an absolute path, it\n" 672 " will be treated as being relative to the current build file.\n" 673 COMMON_LIB_INHERITANCE_HELP 674 COMMON_ORDERING_HELP 675 "\n" 676 "Example:\n" 677 " lib_dirs = [ \"/usr/lib/foo\", \"lib/doom_melon\" ]\n"; 678 679 const char kLibs[] = "libs"; 680 const char kLibs_HelpShort[] = 681 "libs: [string list] Additional libraries to link."; 682 const char kLibs_Help[] = 683 "libs: Additional libraries to link.\n" 684 "\n" 685 " A list of strings.\n" 686 "\n" 687 " These files will be passed to the linker, which will generally search\n" 688 " the library include path. Unlike a normal list of files, they will be\n" 689 " passed to the linker unmodified rather than being treated as file\n" 690 " names relative to the current build file. Generally you would set\n" 691 " the \"lib_dirs\" so your library is found. If you need to specify\n" 692 " a path, you can use \"rebase_path\" to convert a path to be relative\n" 693 " to the build directory.\n" 694 "\n" 695 " When constructing the linker command, the \"lib_prefix\" attribute of\n" 696 " the linker tool in the current toolchain will be prepended to each\n" 697 " library. So your BUILD file should not specify the switch prefix\n" 698 " (like \"-l\"). On Mac, libraries ending in \".framework\" will be\n" 699 " special-cased: the switch \"-framework\" will be prepended instead of\n" 700 " the lib_prefix, and the \".framework\" suffix will be trimmed.\n" 701 COMMON_LIB_INHERITANCE_HELP 702 COMMON_ORDERING_HELP 703 "\n" 704 "Examples:\n" 705 " On Windows:\n" 706 " libs = [ \"ctl3d.lib\" ]\n" 707 " On Linux:\n" 708 " libs = [ \"ld\" ]\n"; 709 710 const char kOutputExtension[] = "output_extension"; 711 const char kOutputExtension_HelpShort[] = 712 "output_extension: [string] Value to use for the output's file extension."; 713 const char kOutputExtension_Help[] = 714 "output_extension: Value to use for the output's file extension.\n" 715 "\n" 716 " Normally the file extension for a target is based on the target\n" 717 " type and the operating system, but in rare cases you will need to\n" 718 " override the name (for example to use \"libfreetype.so.6\" instead\n" 719 " of libfreetype.so on Linux)."; 720 721 const char kOutputName[] = "output_name"; 722 const char kOutputName_HelpShort[] = 723 "output_name: [string] Name for the output file other than the default."; 724 const char kOutputName_Help[] = 725 "output_name: Define a name for the output file other than the default.\n" 726 "\n" 727 " Normally the output name of a target will be based on the target name,\n" 728 " so the target \"//foo/bar:bar_unittests\" will generate an output\n" 729 " file such as \"bar_unittests.exe\" (using Windows as an example).\n" 730 "\n" 731 " Sometimes you will want an alternate name to avoid collisions or\n" 732 " if the internal name isn't appropriate for public distribution.\n" 733 "\n" 734 " The output name should have no extension or prefixes, these will be\n" 735 " added using the default system rules. For example, on Linux an output\n" 736 " name of \"foo\" will produce a shared library \"libfoo.so\".\n" 737 "\n" 738 " This variable is valid for all binary output target types.\n" 739 "\n" 740 "Example:\n" 741 " static_library(\"doom_melon\") {\n" 742 " output_name = \"fluffy_bunny\"\n" 743 " }\n"; 744 745 const char kOutputs[] = "outputs"; 746 const char kOutputs_HelpShort[] = 747 "outputs: [file list] Output files for actions and copy targets."; 748 const char kOutputs_Help[] = 749 "outputs: Output files for actions and copy targets.\n" 750 "\n" 751 " Outputs is valid for \"copy\", \"action\", and \"action_foreach\"\n" 752 " target types and indicates the resulting files. The values may contain\n" 753 " source expansions to generate the output names from the sources (see\n" 754 " \"gn help source_expansion\").\n" 755 "\n" 756 " For copy targets, the outputs is the destination for the copied\n" 757 " file(s). For actions, the outputs should be the list of files\n" 758 " generated by the script.\n"; 759 760 const char kPublic[] = "public"; 761 const char kPublic_HelpShort[] = 762 "public: [file list] Declare public header files for a target."; 763 const char kPublic_Help[] = 764 "public: Declare public header files for a target.\n" 765 "\n" 766 " A list of files that other targets can include. These permissions are\n" 767 " checked via the \"check\" command (see \"gn help check\").\n" 768 "\n" 769 " If no public files are declared, other targets (assuming they have\n" 770 " visibility to depend on this target can include any file in the\n" 771 " sources list. If this variable is defined on a target, dependent\n" 772 " targets may only include files on this whitelist.\n" 773 "\n" 774 " Header file permissions are also subject to visibility. A target\n" 775 " must be visible to another target to include any files from it at all\n" 776 " and the public headers indicate which subset of those files are\n" 777 " permitted. See \"gn help visibility\" for more.\n" 778 "\n" 779 " Public files are inherited through the dependency tree. So if there is\n" 780 " a dependency A -> B -> C, then A can include C's public headers.\n" 781 " However, the same is NOT true of visibility, so unless A is in C's\n" 782 " visibility list, the include will be rejected.\n" 783 "\n" 784 " GN only knows about files declared in the \"sources\" and \"public\"\n" 785 " sections of targets. If a file is included that is not known to the\n" 786 " build, it will be allowed.\n" 787 "\n" 788 "Examples:\n" 789 " These exact files are public:\n" 790 " public = [ \"foo.h\", \"bar.h\" ]\n" 791 "\n" 792 " No files are public (no targets may include headers from this one):\n" 793 " public = []\n"; 794 795 const char kPublicConfigs[] = "public_configs"; 796 const char kPublicConfigs_HelpShort[] = 797 "public_configs: [label list] Configs applied to dependents."; 798 const char kPublicConfigs_Help[] = 799 "public_configs: Configs to be applied on dependents.\n" 800 "\n" 801 " A list of config labels.\n" 802 "\n" 803 " Targets directly depending on this one will have the configs listed in\n" 804 " this variable added to them. These configs will also apply to the\n" 805 " current target.\n" 806 "\n" 807 " This addition happens in a second phase once a target and all of its\n" 808 " dependencies have been resolved. Therefore, a target will not see\n" 809 " these force-added configs in their \"configs\" variable while the\n" 810 " script is running, and then can not be removed. As a result, this\n" 811 " capability should generally only be used to add defines and include\n" 812 " directories necessary to compile a target's headers.\n" 813 "\n" 814 " See also \"all_dependent_configs\".\n" 815 COMMON_ORDERING_HELP; 816 817 const char kPublicDeps[] = "public_deps"; 818 const char kPublicDeps_HelpShort[] = 819 "public_deps: [label list] Declare public dependencies."; 820 const char kPublicDeps_Help[] = 821 "public_deps: Declare public dependencies.\n" 822 "\n" 823 " Public dependencies are like private dependencies (\"deps\") but\n" 824 " additionally express that the current target exposes the listed deps\n" 825 " as part of its public API.\n" 826 "\n" 827 " This has two ramifications:\n" 828 "\n" 829 " - public_configs that are part of the dependency are forwarded\n" 830 " to direct dependents (this is the same as using\n" 831 " forward_dependent_configs_from).\n" 832 "\n" 833 " - public headers in the dependency are usable by dependents\n" 834 " (includes do not require a direct dependency or visibility).\n" 835 "\n" 836 "Discussion\n" 837 "\n" 838 " Say you have three targets: A -> B -> C. C's visibility may allow\n" 839 " B to depend on it but not A. Normally, this would prevent A from\n" 840 " including any headers from C, and C's public_configs would apply\n" 841 " only to B.\n" 842 "\n" 843 " If B lists C in its public_deps instead of regular deps, A will now\n" 844 " inherit C's public_configs and the ability to include C's public\n" 845 " headers.\n" 846 "\n" 847 " Generally if you are writing a target B and you include C's headers\n" 848 " as part of B's public headers, or targets depending on B should\n" 849 " consider B and C to be part of a unit, you should use public_deps\n" 850 " instead of deps.\n" 851 "\n" 852 "Example\n" 853 "\n" 854 " # This target can include files from \"c\" but not from\n" 855 " # \"super_secret_implementation_details\".\n" 856 " executable(\"a\") {\n" 857 " deps = [ \":b\" ]\n" 858 " }\n" 859 "\n" 860 " shared_library(\"b\") {\n" 861 " deps = [ \":super_secret_implementation_details\" ]\n" 862 " public_deps = [ \":c\" ]\n" 863 " }\n"; 864 865 const char kScript[] = "script"; 866 const char kScript_HelpShort[] = 867 "script: [file name] Script file for actions."; 868 const char kScript_Help[] = 869 "script: Script file for actions.\n" 870 "\n" 871 " An absolute or buildfile-relative file name of a Python script to run\n" 872 " for a action and action_foreach targets (see \"gn help action\" and\n" 873 " \"gn help action_foreach\").\n"; 874 875 const char kSources[] = "sources"; 876 const char kSources_HelpShort[] = 877 "sources: [file list] Source files for a target."; 878 const char kSources_Help[] = 879 "sources: Source files for a target\n" 880 "\n" 881 " A list of files relative to the current buildfile.\n"; 882 883 const char kTestonly[] = "testonly"; 884 const char kTestonly_HelpShort[] = 885 "testonly: [boolean] Declares a target must only be used for testing."; 886 const char kTestonly_Help[] = 887 "testonly: Declares a target must only be used for testing.\n" 888 "\n" 889 " Boolean. Defaults to false.\n" 890 "\n" 891 " When a target is marked \"testonly = true\", it must only be depended\n" 892 " on by other test-only targets. Otherwise, GN will issue an error\n" 893 " that the depenedency is not allowed.\n" 894 "\n" 895 " This feature is intended to prevent accidentally shipping test code\n" 896 " in a final product.\n" 897 "\n" 898 "Example\n" 899 "\n" 900 " source_set(\"test_support\") {\n" 901 " testonly = true\n" 902 " ...\n" 903 " }\n"; 904 905 const char kVisibility[] = "visibility"; 906 const char kVisibility_HelpShort[] = 907 "visibility: [label list] A list of labels that can depend on a target."; 908 const char kVisibility_Help[] = 909 "visibility: A list of labels that can depend on a target.\n" 910 "\n" 911 " A list of labels and label patterns that define which targets can\n" 912 " depend on the current one. These permissions are checked via the\n" 913 " \"check\" command (see \"gn help check\").\n" 914 "\n" 915 " If visibility is not defined, it defaults to public (\"*\").\n" 916 "\n" 917 " If visibility is defined, only the targets with labels that match it\n" 918 " can depend on the current target. The empty list means no targets\n" 919 " can depend on the current target.\n" 920 "\n" 921 " Tip: Often you will want the same visibility for all targets in a\n" 922 " BUILD file. In this case you can just put the definition at the top,\n" 923 " outside of any target, and the targets will inherit that scope and see\n" 924 " the definition.\n" 925 "\n" 926 "Patterns\n" 927 "\n" 928 " See \"gn help label_pattern\" for more details on what types of\n" 929 " patterns are supported. If a toolchain is specified, only targets\n" 930 " in that toolchain will be matched. If a toolchain is not specified on\n" 931 " a pattern, targets in all toolchains will be matched.\n" 932 "\n" 933 "Examples\n" 934 "\n" 935 " Only targets in the current buildfile (\"private\", the default):\n" 936 " visibility = [ \":*\" ]\n" 937 "\n" 938 " No targets (used for targets that should be leaf nodes):\n" 939 " visibility = []\n" 940 "\n" 941 " Any target (\"public\"):\n" 942 " visibility = [ \"*\" ]\n" 943 "\n" 944 " All targets in the current directory and any subdirectory:\n" 945 " visibility = [ \"./*\" ]\n" 946 "\n" 947 " Any target in \"//bar/BUILD.gn\":\n" 948 " visibility = [ \"//bar:*\" ]\n" 949 "\n" 950 " Any target in \"//bar/\" or any subdirectory thereof:\n" 951 " visibility = [ \"//bar/*\"\n ]" 952 "\n" 953 " Just these specific targets:\n" 954 " visibility = [ \":mything\", \"//foo:something_else\" ]\n" 955 "\n" 956 " Any target in the current directory and any subdirectory thereof, plus\n" 957 " any targets in \"//bar/\" and any subdirectory thereof.\n" 958 " visibility = [ \"./*\", \"//bar/*\" ]\n"; 959 960 // ----------------------------------------------------------------------------- 961 962 VariableInfo::VariableInfo() 963 : help_short(NULL), 964 help(NULL) { 965 } 966 967 VariableInfo::VariableInfo(const char* in_help_short, const char* in_help) 968 : help_short(in_help_short), 969 help(in_help) { 970 } 971 972 #define INSERT_VARIABLE(var) \ 973 info_map[k##var] = VariableInfo(k##var##_HelpShort, k##var##_Help); 974 975 const VariableInfoMap& GetBuiltinVariables() { 976 static VariableInfoMap info_map; 977 if (info_map.empty()) { 978 INSERT_VARIABLE(BuildCpuArch) 979 INSERT_VARIABLE(BuildOs) 980 INSERT_VARIABLE(CpuArch) 981 INSERT_VARIABLE(CurrentToolchain) 982 INSERT_VARIABLE(DefaultToolchain) 983 INSERT_VARIABLE(Os) 984 INSERT_VARIABLE(PythonPath) 985 INSERT_VARIABLE(RootBuildDir) 986 INSERT_VARIABLE(RootGenDir) 987 INSERT_VARIABLE(RootOutDir) 988 INSERT_VARIABLE(TargetGenDir) 989 INSERT_VARIABLE(TargetOutDir) 990 } 991 return info_map; 992 } 993 994 const VariableInfoMap& GetTargetVariables() { 995 static VariableInfoMap info_map; 996 if (info_map.empty()) { 997 INSERT_VARIABLE(AllDependentConfigs) 998 INSERT_VARIABLE(AllowCircularIncludesFrom) 999 INSERT_VARIABLE(Args) 1000 INSERT_VARIABLE(Cflags) 1001 INSERT_VARIABLE(CflagsC) 1002 INSERT_VARIABLE(CflagsCC) 1003 INSERT_VARIABLE(CflagsObjC) 1004 INSERT_VARIABLE(CflagsObjCC) 1005 INSERT_VARIABLE(CheckIncludes) 1006 INSERT_VARIABLE(CompleteStaticLib) 1007 INSERT_VARIABLE(Configs) 1008 INSERT_VARIABLE(Data) 1009 INSERT_VARIABLE(DataDeps) 1010 INSERT_VARIABLE(Defines) 1011 INSERT_VARIABLE(Depfile) 1012 INSERT_VARIABLE(Deps) 1013 INSERT_VARIABLE(ForwardDependentConfigsFrom) 1014 INSERT_VARIABLE(IncludeDirs) 1015 INSERT_VARIABLE(Inputs) 1016 INSERT_VARIABLE(Ldflags) 1017 INSERT_VARIABLE(Libs) 1018 INSERT_VARIABLE(LibDirs) 1019 INSERT_VARIABLE(OutputExtension) 1020 INSERT_VARIABLE(OutputName) 1021 INSERT_VARIABLE(Outputs) 1022 INSERT_VARIABLE(Public) 1023 INSERT_VARIABLE(PublicConfigs) 1024 INSERT_VARIABLE(PublicDeps) 1025 INSERT_VARIABLE(Script) 1026 INSERT_VARIABLE(Sources) 1027 INSERT_VARIABLE(Testonly) 1028 INSERT_VARIABLE(Visibility) 1029 } 1030 return info_map; 1031 } 1032 1033 #undef INSERT_VARIABLE 1034 1035 } // namespace variables 1036