OLD | NEW |
---|---|
1 // Copyright (c) 2013 The Chromium Authors. All rights reserved. | 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 | 2 // Use of this source code is governed by a BSD-style license that can be |
3 // found in the LICENSE file. | 3 // found in the LICENSE file. |
4 | 4 |
5 #include "tools/gn/variables.h" | 5 #include "tools/gn/variables.h" |
6 | 6 |
7 namespace variables { | 7 namespace variables { |
8 | 8 |
9 // Built-in variables ---------------------------------------------------------- | 9 // Built-in variables ---------------------------------------------------------- |
10 | 10 |
(...skipping 336 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
347 const char kAllowCircularIncludesFrom[] = "allow_circular_includes_from"; | 347 const char kAllowCircularIncludesFrom[] = "allow_circular_includes_from"; |
348 const char kAllowCircularIncludesFrom_HelpShort[] = | 348 const char kAllowCircularIncludesFrom_HelpShort[] = |
349 "allow_circular_includes_from: [label list] Permit includes from deps."; | 349 "allow_circular_includes_from: [label list] Permit includes from deps."; |
350 const char kAllowCircularIncludesFrom_Help[] = | 350 const char kAllowCircularIncludesFrom_Help[] = |
351 "allow_circular_includes_from: Permit includes from deps.\n" | 351 "allow_circular_includes_from: Permit includes from deps.\n" |
352 "\n" | 352 "\n" |
353 " A list of target labels. Must be a subset of the target's \"deps\".\n" | 353 " A list of target labels. Must be a subset of the target's \"deps\".\n" |
354 " These targets will be permitted to include headers from the current\n" | 354 " These targets will be permitted to include headers from the current\n" |
355 " target despite the dependency going in the opposite direction.\n" | 355 " target despite the dependency going in the opposite direction.\n" |
356 "\n" | 356 "\n" |
357 "Tedious exposition\n" | 357 " When you use this, both targets must be included in a final binary\n" |
358 " for it to link. To keep linker errors from happening, it is good\n" | |
359 " practice to have all external dependencies depend only on one of\n" | |
360 " the two targets, and to set the visibility on the other to enforce\n" | |
361 " this. Thus the targets will always be linked together in any output.\n" | |
362 "\n" | |
363 "Details\n" | |
358 "\n" | 364 "\n" |
359 " Normally, for a file in target A to include a file from target B,\n" | 365 " Normally, for a file in target A to include a file from target B,\n" |
360 " A must list B as a dependency. This invariant is enforced by the\n" | 366 " A must list B as a dependency. This invariant is enforced by the\n" |
361 " \"gn check\" command (and the --check flag to \"gn gen\").\n" | 367 " \"gn check\" command (and the --check flag to \"gn gen\" -- see\n" |
368 " \"gn help check\").\n" | |
362 "\n" | 369 "\n" |
363 " Sometimes, two targets might be the same unit for linking purposes\n" | 370 " Sometimes, two targets might be the same unit for linking purposes\n" |
364 " (two source sets or static libraries that would always be linked\n" | 371 " (two source sets or static libraries that would always be linked\n" |
365 " together in a final executable or shared library). In this case,\n" | 372 " together in a final executable or shared library) and they each\n" |
366 " you want A to be able to include B's headers, and B to include A's\n" | 373 " include headers from the other: you want A to be able to include B's\n" |
367 " headers.\n" | 374 " headers, and B to include A's headers. This is not an ideal situation\n" |
375 " but is sometimes unavoidable.\n" | |
368 "\n" | 376 "\n" |
369 " This list, if specified, lists which of the dependencies of the\n" | 377 " This list, if specified, lists which of the dependencies of the\n" |
370 " current target can include header files from the current target.\n" | 378 " current target can include header files from the current target.\n" |
371 " That is, if A depends on B, B can only include headers from A if it is\n" | 379 " That is, if A depends on B, B can only include headers from A if it is\n" |
372 " in A's allow_circular_includes_from list.\n" | 380 " in A's allow_circular_includes_from list. Normally includes must\n" |
381 " follow the direction of dependencies, this flag allows them to go\n" | |
382 " in the opposite direction.\n" | |
383 "\n" | |
384 "Danger\n" | |
385 "\n" | |
386 " In the above example, A's headers are likely to include headers from\n" | |
387 " A's dependencies. Those dependencies may have public_configs that\n" | |
388 " apply flags, defines, and include paths that make those headers work\n" | |
389 " properly.\n" | |
390 "\n" | |
391 " With allow_circular_includes_from, B can include A's headers, and\n" | |
392 " transitively from A's dependencies, without having the dependencies\n" | |
393 " that would bring in the public_configs those headers need. The result\n" | |
394 " may be errors or inconsistent builds.\n" | |
395 "\n" | |
396 " So when you use allow_circular_includes_from, make sure that any\n" | |
397 " compiler settings, flags, and include directories are the same between\n" | |
398 " both targets (consider putting such things in a shared config they can\n" | |
399 " both reference). Make sure the dependencies are also the same (you\n" | |
400 " might consider a group to collect such dependencies they both\n" | |
401 " depend on).\n" | |
373 "\n" | 402 "\n" |
374 "Example\n" | 403 "Example\n" |
375 "\n" | 404 "\n" |
376 " source_set(\"a\") {\n" | 405 " source_set(\"a\") {\n" |
377 " deps = [ \":b\", \":c\" ]\n" | 406 " deps = [ \":b\", \":a_b_shared_deps\" ]\n" |
378 " allow_circular_includes_from = [ \":b\" ]\n" | 407 " allow_circular_includes_from = [ \":b\" ]\n" |
379 " ...\n" | 408 " ...\n" |
409 " }\n" | |
410 "\n" | |
411 " source_set(\"b\") {\n" | |
412 " deps = [ \":a_b_shared_deps\" ]\n" | |
413 " # Sources here can include headers from a despite lack of deps.\n" | |
414 " ...\n" | |
415 " }\n" | |
416 "\n" | |
417 " group(\"a_b_shared_deps\") {\n" | |
418 " public_deps = [ \":c\" ]\n" | |
380 " }\n"; | 419 " }\n"; |
381 | 420 |
382 const char kArgs[] = "args"; | 421 const char kArgs[] = "args"; |
383 const char kArgs_HelpShort[] = | 422 const char kArgs_HelpShort[] = |
384 "args: [string list] Arguments passed to an action."; | 423 "args: [string list] Arguments passed to an action."; |
385 const char kArgs_Help[] = | 424 const char kArgs_Help[] = |
386 "args: Arguments passed to an action.\n" | 425 "args: Arguments passed to an action.\n" |
387 "\n" | 426 "\n" |
388 " For action and action_foreach targets, args is the list of arguments\n" | 427 " For action and action_foreach targets, args is the list of arguments\n" |
389 " to pass to the script. Typically you would use source expansion (see\n" | 428 " to pass to the script. Typically you would use source expansion (see\n" |
(...skipping 83 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
473 "\n" | 512 "\n" |
474 " This string is used by the \"create_bundle\" target to expand the\n" | 513 " This string is used by the \"create_bundle\" target to expand the\n" |
475 " {{bundle_resources_dir}} of the \"bundle_data\" target it depends on.\n" | 514 " {{bundle_resources_dir}} of the \"bundle_data\" target it depends on.\n" |
476 " This must correspond to a path under \"bundle_root_dir\".\n" | 515 " This must correspond to a path under \"bundle_root_dir\".\n" |
477 "\n" | 516 "\n" |
478 " See \"gn help bundle_root_dir\" for examples.\n"; | 517 " See \"gn help bundle_root_dir\" for examples.\n"; |
479 | 518 |
480 const char kBundleExecutableDir[] = "bundle_executable_dir"; | 519 const char kBundleExecutableDir[] = "bundle_executable_dir"; |
481 const char kBundleExecutableDir_HelpShort[] = | 520 const char kBundleExecutableDir_HelpShort[] = |
482 "bundle_executable_dir: " | 521 "bundle_executable_dir: " |
483 "Expansion of {{bundle_executable_dir}} in create_bundle."; | 522 "Expansion of {{bundle_executable_dir}} in create_bundle"; |
brettw
2016/03/18 20:15:05
This was on purpose, this line was 81 cols and wra
| |
484 const char kBundleExecutableDir_Help[] = | 523 const char kBundleExecutableDir_Help[] = |
485 "bundle_executable_dir: " | 524 "bundle_executable_dir: " |
486 "Expansion of {{bundle_executable_dir}} in create_bundle.\n" | 525 "Expansion of {{bundle_executable_dir}} in create_bundle.\n" |
487 "\n" | 526 "\n" |
488 " A string corresponding to a path in $root_build_dir.\n" | 527 " A string corresponding to a path in $root_build_dir.\n" |
489 "\n" | 528 "\n" |
490 " This string is used by the \"create_bundle\" target to expand the\n" | 529 " This string is used by the \"create_bundle\" target to expand the\n" |
491 " {{bundle_executable_dir}} of the \"bundle_data\" target it depends on.\n" | 530 " {{bundle_executable_dir}} of the \"bundle_data\" target it depends on.\n" |
492 " This must correspond to a path under \"bundle_root_dir\".\n" | 531 " This must correspond to a path under \"bundle_root_dir\".\n" |
493 "\n" | 532 "\n" |
(...skipping 74 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
568 "check_includes: [boolean] Controls whether a target's files are checked.\n" | 607 "check_includes: [boolean] Controls whether a target's files are checked.\n" |
569 "\n" | 608 "\n" |
570 " When true (the default), the \"gn check\" command (as well as\n" | 609 " When true (the default), the \"gn check\" command (as well as\n" |
571 " \"gn gen\" with the --check flag) will check this target's sources\n" | 610 " \"gn gen\" with the --check flag) will check this target's sources\n" |
572 " and headers for proper dependencies.\n" | 611 " and headers for proper dependencies.\n" |
573 "\n" | 612 "\n" |
574 " When false, the files in this target will be skipped by default.\n" | 613 " When false, the files in this target will be skipped by default.\n" |
575 " This does not affect other targets that depend on the current target,\n" | 614 " This does not affect other targets that depend on the current target,\n" |
576 " it just skips checking the includes of the current target's files.\n" | 615 " it just skips checking the includes of the current target's files.\n" |
577 "\n" | 616 "\n" |
578 "Controlling includes individually\n" | 617 " If there are a few conditionally included headers that trip up\n" |
618 " checking, you can exclude headers individually by annotating them with\n" | |
619 " \"nogncheck\" (see \"gn help nogncheck\").\n" | |
579 "\n" | 620 "\n" |
580 " If only certain includes are problematic, you can annotate them\n" | 621 " The topic \"gn help check\" has general information on how checking\n" |
581 " individually rather than disabling header checking on an entire\n" | 622 " works and advice on how to pass a check in problematic cases.\n" |
582 " target. Add the string \"nogncheck\" to the include line:\n" | |
583 "\n" | |
584 " #include \"foo/something_weird.h\" // nogncheck (bug 12345)\n" | |
585 "\n" | |
586 " It is good form to include a reference to a bug (if the include is\n" | |
587 " improper, or some other comment expressing why the header checker\n" | |
588 " doesn't work for this particular case.\n" | |
589 "\n" | |
590 " The most common reason to need \"nogncheck\" is conditional includes.\n" | |
591 " The header checker does not understand the preprocessor, so may flag\n" | |
592 " some includes as improper even if the dependencies and #defines are\n" | |
593 " always matched correctly:\n" | |
594 "\n" | |
595 " #if defined(ENABLE_DOOM_MELON)\n" | |
596 " #include \"doom_melon/beam_controller.h\" // nogncheck\n" | |
597 " #endif\n" | |
598 "\n" | 623 "\n" |
599 "Example\n" | 624 "Example\n" |
600 "\n" | 625 "\n" |
601 " source_set(\"busted_includes\") {\n" | 626 " source_set(\"busted_includes\") {\n" |
602 " # This target's includes are messed up, exclude it from checking.\n" | 627 " # This target's includes are messed up, exclude it from checking.\n" |
603 " check_includes = false\n" | 628 " check_includes = false\n" |
604 " ...\n" | 629 " ...\n" |
605 " }\n"; | 630 " }\n"; |
606 | 631 |
607 const char kCompleteStaticLib[] = "complete_static_lib"; | 632 const char kCompleteStaticLib[] = "complete_static_lib"; |
608 const char kCompleteStaticLib_HelpShort[] = | 633 const char kCompleteStaticLib_HelpShort[] = |
609 "complete_static_lib: [boolean] Links all deps into a static library."; | 634 "complete_static_lib: [boolean] Links all deps into a static library."; |
610 const char kCompleteStaticLib_Help[] = | 635 const char kCompleteStaticLib_Help[] = |
611 "complete_static_lib: [boolean] Links all deps into a static library.\n" | 636 "complete_static_lib: [boolean] Links all deps into a static library.\n" |
612 "\n" | 637 "\n" |
613 " A static library normally doesn't include code from dependencies, but\n" | 638 " A static library normally doesn't include code from dependencies, but\n" |
614 " instead forwards the static libraries and source sets in its deps up\n" | 639 " instead forwards the static libraries and source sets in its deps up\n" |
615 " the dependency chain until a linkable target (an executable or shared\n" | 640 " the dependency chain until a linkable target (an executable or shared\n" |
616 " library) is reached. The final linkable target only links each static\n" | 641 " library) is reached. The final linkable target only links each static\n" |
617 " library once, even if it appears more than once in its dependency\n" | 642 " library once, even if it appears more than once in its dependency\n" |
618 " graph.\n" | 643 " graph.\n" |
619 "\n" | 644 "\n" |
620 " In some cases the static library might be the final desired output.\n" | 645 " In some cases the static library might be the final desired output.\n" |
621 " For example, you may be producing a static library for distribution to\n" | 646 " For example, you may be producing a static library for distribution to\n" |
622 " third parties. In this case, the static library should include code\n" | 647 " third parties. In this case, the static library should include code\n" |
623 " for all dependencies in one complete package. Since GN does not unpack\n" | 648 " for all dependencies in one complete package. Since GN does not unpack\n" |
624 " static libraries to forward their contents up the dependency chain,\n" | 649 " static libraries to forward their contents up the dependency chain,\n" |
625 " it is an error for complete static libraries to depend on other static\n" | 650 " it is an error for complete static libraries to depend on other static\n" |
651 "\n" | |
652 " In rare cases it makes sense to list a header in more than one\n" | |
653 " target if it could be considered conceptually a member of both.\n" | |
626 " libraries.\n" | 654 " libraries.\n" |
627 "\n" | 655 "\n" |
628 "Example\n" | 656 "Example\n" |
629 "\n" | 657 "\n" |
630 " static_library(\"foo\") {\n" | 658 " static_library(\"foo\") {\n" |
631 " complete_static_lib = true\n" | 659 " complete_static_lib = true\n" |
632 " deps = [ \"bar\" ]\n" | 660 " deps = [ \"bar\" ]\n" |
633 " }\n"; | 661 " }\n"; |
634 | 662 |
635 const char kConfigs[] = "configs"; | 663 const char kConfigs[] = "configs"; |
(...skipping 932 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
1568 INSERT_VARIABLE(Sources) | 1596 INSERT_VARIABLE(Sources) |
1569 INSERT_VARIABLE(Testonly) | 1597 INSERT_VARIABLE(Testonly) |
1570 INSERT_VARIABLE(Visibility) | 1598 INSERT_VARIABLE(Visibility) |
1571 } | 1599 } |
1572 return info_map; | 1600 return info_map; |
1573 } | 1601 } |
1574 | 1602 |
1575 #undef INSERT_VARIABLE | 1603 #undef INSERT_VARIABLE |
1576 | 1604 |
1577 } // namespace variables | 1605 } // namespace variables |
OLD | NEW |