Add public deps to GN

tools/gn/variables.cc

 // Copyright (c) 2013 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #include "tools/gn/variables.h"
 
 namespace variables {
 
 // Built-in variables ----------------------------------------------------------
 
@@ skipping 212 matching lines @@
 
 #define COMMON_ORDERING_HELP \
     "\n" \
     "Ordering of flags and values:\n" \
     "\n" \
     "  1. Those set on the current target (not in a config).\n" \
     "  2. Those set on the \"configs\" on the target in order that the\n" \
     "     configs appear in the list.\n" \
     "  3. Those set on the \"all_dependent_configs\" on the target in order\n" \
     "     that the configs appear in the list.\n" \
-    "  4. Those set on the \"direct_dependent_configs\" on the target in\n" \
-    "     order that those configs appear in the list.\n" \
+    "  4. Those set on the \"public_configs\" on the target in order that\n" \
+    "     those configs appear in the list.\n" \
     "  5. all_dependent_configs pulled from dependencies, in the order of\n" \
     "     the \"deps\" list. This is done recursively. If a config appears\n" \
     "     more than once, only the first occurance will be used.\n" \
-    "  6. direct_dependent_configs pulled from dependencies, in the order\n" \
-    "     of the \"deps\" list. If a dependency has\n" \
-    "     \"forward_dependent_configs_from\", they will be applied\n" \
-    "     recursively.\n"
+    "  6. public_configs pulled from dependencies, in the order of the\n" \
+    "     \"deps\" list. If a dependency has " \
+              "\"forward_dependent_configs_from\",\n" \
+    "     or are public dependencies, they will be applied recursively.\n"
 
 const char kAllDependentConfigs[] = "all_dependent_configs";
 const char kAllDependentConfigs_HelpShort[] =
     "all_dependent_configs: [label list] Configs to be forced on dependents.";
 const char kAllDependentConfigs_Help[] =
     "all_dependent_configs: Configs to be forced on dependents.\n"
     "\n"
     "  A list of config labels.\n"
     "\n"
     "  All targets depending on this one, and recursively, all targets\n"
     "  depending on those, will have the configs listed in this variable\n"
     "  added to them. These configs will also apply to the current target.\n"
     "\n"
     "  This addition happens in a second phase once a target and all of its\n"
     "  dependencies have been resolved. Therefore, a target will not see\n"
     "  these force-added configs in their \"configs\" variable while the\n"
     "  script is running, and then can not be removed. As a result, this\n"
     "  capability should generally only be used to add defines and include\n"
     "  directories necessary to compile a target's headers.\n"
     "\n"
-    "  See also \"direct_dependent_configs\".\n"
+    "  See also \"public_configs\".\n"
     COMMON_ORDERING_HELP;
 
 const char kAllowCircularIncludesFrom[] = "allow_circular_includes_from";
 const char kAllowCircularIncludesFrom_HelpShort[] =
     "allow_circular_includes_from: [label list] Permit includes from deps.";
 const char kAllowCircularIncludesFrom_Help[] =
     "allow_circular_includes_from: Permit includes from deps.\n"
     "\n"
     "  A list of target labels. Must be a subset of the target's \"deps\".\n"
     "  These targets will be permitted to include headers from the current\n"
@@ skipping 153 matching lines @@
     "\n"
     "  Lists files required to run the given target. These are typically\n"
     "  data files.\n"
     "\n"
     "  Appearing in the \"data\" section does not imply any special handling\n"
     "  such as copying them to the output directory. This is just used for\n"
     "  declaring runtime dependencies. There currently isn't a good use for\n"
     "  these but it is envisioned that test data can be listed here for use\n"
     "  running automated tests.\n"
     "\n"
-    "  See also \"gn help inputs\" and \"gn help datadeps\", both of\n"
+    "  See also \"gn help inputs\" and \"gn help data_deps\", both of\n"
     "  which actually affect the build in concrete ways.\n";
 
-const char kDatadeps[] = "datadeps";
-const char kDatadeps_HelpShort[] =
-    "datadeps: [label list] Non-linked dependencies.";
-const char kDatadeps_Help[] =
-    "datadeps: Non-linked dependencies.\n"
+const char kDataDeps[] = "data_deps";
+const char kDataDeps_HelpShort[] =
+    "data_deps: [label list] Non-linked dependencies.";
+const char kDataDeps_Help[] =
+    "data_deps: Non-linked dependencies.\n"
     "\n"
     "  A list of target labels.\n"
     "\n"
     "  Specifies dependencies of a target that are not actually linked into\n"
     "  the current target. Such dependencies will built and will be available\n"
     "  at runtime.\n"
     "\n"
     "  This is normally used for things like plugins or helper programs that\n"
     "  a target needs at runtime.\n"
     "\n"
     "  See also \"gn help deps\" and \"gn help data\".\n"
     "\n"
     "Example:\n"
     "  executable(\"foo\") {\n"
     "    deps = [ \"//base\" ]\n"
-    "    datadeps = [ \"//plugins:my_runtime_plugin\" ]\n"
+    "    data_deps = [ \"//plugins:my_runtime_plugin\" ]\n"
     "  }\n";
 
 const char kDefines[] = "defines";
 const char kDefines_HelpShort[] =
     "defines: [string list] C preprocessor defines.";
 const char kDefines_Help[] =
     "defines: C preprocessor defines.\n"
     "\n"
     "  A list of strings\n"
     "\n"
@@ skipping 31 matching lines @@
     "    # Locate the depfile in the output directory named like the\n"
     "    # inputs but with a \".d\" appended.\n"
     "    depfile = \"$relative_target_output_dir/{{source_name}}.d\"\n"
     "\n"
     "    # Say our script uses \"-o <d file>\" to indicate the depfile.\n"
     "    args = [ \"{{source}}\", \"-o\", depfile ]\n"
     "  }\n";
 
 const char kDeps[] = "deps";
 const char kDeps_HelpShort[] =
-    "deps: [label list] Linked dependencies.";
+    "deps: [label list] Private linked dependencies.";
 const char kDeps_Help[] =
-    "deps: Linked dependencies.\n"
+    "deps: Private linked dependencies.\n"
     "\n"
     "  A list of target labels.\n"
     "\n"
-    "  Specifies dependencies of a target. Shared and dynamic libraries will\n"
-    "  be linked into the current target. Other target types that can't be\n"
-    "  linked (like actions and groups) listed in \"deps\" will be treated\n"
-    "  as \"datadeps\". Likewise, if the current target isn't linkable, then\n"
-    "  all deps will be treated as \"datadeps\".\n"
+    "  Specifies private dependencies of a target. Shared and dynamic\n"
+    "  libraries will be linked into the current target. Other target types\n"
+    "  that can't be linked (like actions and groups) listed in \"deps\" will\n"
+    "  be treated as \"data_deps\". Likewise, if the current target isn't\n"
+    "  linkable, then all deps will be treated as \"data_deps\".\n"
     "\n"
-    "  See also \"datadeps\".\n";
-
-const char kDirectDependentConfigs[] = "direct_dependent_configs";
-const char kDirectDependentConfigs_HelpShort[] =
-    "direct_dependent_configs: [label list] Configs to be forced on "
-    "dependents.";
-const char kDirectDependentConfigs_Help[] =
-    "direct_dependent_configs: Configs to be forced on dependents.\n"
+    "  These dependencies are private in that it does not grant dependent\n"
+    "  targets the ability to include headers from the dependency, and direct\n"
+    "  dependent configs are not forwarded.\n"
     "\n"
-    "  A list of config labels.\n"
-    "\n"
-    "  Targets directly referencing this one will have the configs listed in\n"
-    "  this variable added to them. These configs will also apply to the\n"
-    "  current target.\n"
-    "\n"
-    "  This addition happens in a second phase once a target and all of its\n"
-    "  dependencies have been resolved. Therefore, a target will not see\n"
-    "  these force-added configs in their \"configs\" variable while the\n"
-    "  script is running, and then can not be removed. As a result, this\n"
-    "  capability should generally only be used to add defines and include\n"
-    "  directories necessary to compile a target's headers.\n"
-    "\n"
-    "  See also \"all_dependent_configs\".\n"
-    COMMON_ORDERING_HELP;
+    "  See also \"public_deps\" and \"data_deps\".\n";
 
 const char kForwardDependentConfigsFrom[] = "forward_dependent_configs_from";
 const char kForwardDependentConfigsFrom_HelpShort[] =
     "forward_dependent_configs_from: [label list] Forward dependent's configs.";
 const char kForwardDependentConfigsFrom_Help[] =
     "forward_dependent_configs_from\n"
     "\n"
     "  A list of target labels.\n"
     "\n"
-    "  Exposes the direct_dependent_configs from a dependent target as\n"
-    "  direct_dependent_configs of the current one. Each label in this list\n"
+    "  Exposes the public_configs from a private dependent target as\n"
+    "  public_configs of the current one. Each label in this list\n"
     "  must also be in the deps.\n"
     "\n"
+    "  Generally you should use public_deps instead of this variable to\n"
+    "  express the concept of exposing a dependency as part of a target's\n"
+    "  public API. We're considering removing this variable.\n"
+    "\n"
+    "Discussion\n"
+    "\n"
     "  Sometimes you depend on a child library that exports some necessary\n"
-    "  configuration via direct_dependent_configs. If your target in turn\n"
-    "  exposes the child library's headers in its public headers, it might\n"
-    "  mean that targets that depend on you won't work: they'll be seeing the\n"
-    "  child library's code but not the necessary configuration. This list\n"
+    "  configuration via public_configs. If your target in turn exposes the\n"
+    "  child library's headers in its public headers, it might mean that\n"
+    "  targets that depend on you won't work: they'll be seeing the child\n"
+    "  library's code but not the necessary configuration. This list\n"
     "  specifies which of your deps' direct dependent configs to expose as\n"
     "  your own.\n"
     "\n"
-    "Examples:\n"
+    "Examples\n"
     "\n"
     "  If we use a given library \"a\" from our public headers:\n"
     "\n"
     "    deps = [ \":a\", \":b\", ... ]\n"
     "    forward_dependent_configs_from = [ \":a\" ]\n"
     "\n"
     "  This example makes a \"transparent\" target that forwards a dependency\n"
     "  to another:\n"
     "\n"
     "    group(\"frob\") {\n"
@@ skipping 73 matching lines @@
     "\n"
     "  A list of strings.\n"
     "\n"
     "  These flags are passed on the command-line to the linker and generally\n"
     "  specify various linking options. Most targets will not need these and\n"
     "  will use \"libs\" and \"lib_dirs\" instead.\n"
     "\n"
     "  ldflags are NOT pushed to dependents, so applying ldflags to source\n"
     "  sets or static libraries will be a no-op. If you want to apply ldflags\n"
     "  to dependent targets, put them in a config and set it in the\n"
-    "  all_dependent_configs or direct_dependent_configs.\n";
+    "  all_dependent_configs or public_configs.\n";
 
 #define COMMON_LIB_INHERITANCE_HELP \
     "\n" \
     "  libs and lib_dirs work differently than other flags in two respects.\n" \
     "  First, then are inherited across static library boundaries until a\n" \
     "  shared library or executable target is reached. Second, they are\n" \
     "  uniquified so each one is only passed once (the first instance of it\n" \
     "  will be the one used).\n"
 
 const char kLibDirs[] = "lib_dirs";
@@ skipping 122 matching lines @@
     "  sections of targets. If a file is included that is not known to the\n"
     "  build, it will be allowed.\n"
     "\n"
     "Examples:\n"
     "  These exact files are public:\n"
     "    public = [ \"foo.h\", \"bar.h\" ]\n"
     "\n"
     "  No files are public (no targets may include headers from this one):\n"
     "    public = []\n";
 
+const char kPublicConfigs[] = "public_configs";
+const char kPublicConfigs_HelpShort[] =
+    "public_configs: [label list] Configs applied to dependents.";
+const char kPublicConfigs_Help[] =
+    "public_configs: Configs to be applied on dependents.\n"
+    "\n"
+    "  A list of config labels.\n"
+    "\n"
+    "  Targets directly referencing this one will have the configs listed in\n"

[jamesr, 2014/09/16 20:09:25]

'directly referencing this' -> 'directly depending on', perhaps?

+    "  this variable added to them. These configs will also apply to the\n"
+    "  current target.\n"

[jamesr, 2014/09/16 20:09:25]

we have some cases where we want things to apply to dependents and not the
target itself. i guess this could be accomplished with an intermediate group

[brettw, 2014/09/16 21:01:33]

Yes, my original design had this separate (like GYP does) but in 99% of the
cases you want to apply to yourself and dependents which made things
unnecessarily verbose and I changed it. Calling it "public configs" I think
makes it even more natural that it work this way. You do need an extra group for
the case you mentioned, though. I think this is an acceptable tradeoff.

+    "\n"
+    "  This addition happens in a second phase once a target and all of its\n"
+    "  dependencies have been resolved. Therefore, a target will not see\n"
+    "  these force-added configs in their \"configs\" variable while the\n"
+    "  script is running, and then can not be removed. As a result, this\n"
+    "  capability should generally only be used to add defines and include\n"
+    "  directories necessary to compile a target's headers.\n"
+    "\n"
+    "  See also \"all_dependent_configs\".\n"
+    COMMON_ORDERING_HELP;
+
+const char kPublicDeps[] = "public_deps";
+const char kPublicDeps_HelpShort[] =
+    "public: [label list] Declare public dependencies.";
+const char kPublicDeps_Help[] =
+    "public_deps: Declare public dependencies.\n"
+    "\n"
+    "  Public dependencies are like private dependencies (\"deps\") but\n"
+    "  additionally express that the current target exposes the listed deps\n"
+    "  as part of its public API.\n"
+    "\n"
+    "  This has two ramifications:\n"
+    "\n"
+    "    - public_configs that are part of the dependency are forwarded\n"
+    "      to dependents (this is the same as using\n"

[jamesr, 2014/09/16 20:09:25]

direct dependents

+    "      forward_dependent_configs_from).\n"
+    "\n"
+    "    - public headers in the dependency are usable by dependents\n"
+    "      (includes do not require a direct dependency or visibility).\n"
+    "\n"
+    "Discussion\n"
+    "\n"
+    "  Say you have three targets: A -> B -> C. C's visibility may allow\n"
+    "  B to depend on it but not A. Normally, this would prevent A from\n"
+    "  including any headers from C, and C's public_configs would apply\n"
+    "  only to B.\n"
+    "\n"
+    "  If B lists C in its public_deps instead of regular deps, A will now\n"
+    "  inherit C's public_configs and the ability to include C's public\n"
+    "  headers.\n"
+    "\n"
+    "  Generally if you are writing a target B and you include C's headers\n"
+    "  as part of B's public headers, or targets depending on B should\n"
+    "  consider B and C to be part of a unit, you should use public_deps\n"
+    "  instead of deps.\n"
+    "\n"
+    "Example\n"
+    "\n"
+    "  shared_library(\"b\") {\n"

[jamesr, 2014/09/16 20:09:25]

this example seems a little bit too terse

+    "    deps = [ \":super_secret_implementation_details\" ]\n"
+    "    public_deps = [ \":c\" ]\n"
+    "  }\n";
+
 const char kScript[] = "script";
 const char kScript_HelpShort[] =
     "script: [file name] Script file for actions.";
 const char kScript_Help[] =
     "script: Script file for actions.\n"
     "\n"
     "  An absolute or buildfile-relative file name of a Python script to run\n"
     "  for a action and action_foreach targets (see \"gn help action\" and\n"
     "  \"gn help action_foreach\").\n";
 
@@ skipping 124 matching lines @@
     INSERT_VARIABLE(Args)
     INSERT_VARIABLE(Cflags)
     INSERT_VARIABLE(CflagsC)
     INSERT_VARIABLE(CflagsCC)
     INSERT_VARIABLE(CflagsObjC)
     INSERT_VARIABLE(CflagsObjCC)
     INSERT_VARIABLE(CheckIncludes)
     INSERT_VARIABLE(CompleteStaticLib)
     INSERT_VARIABLE(Configs)
     INSERT_VARIABLE(Data)
-    INSERT_VARIABLE(Datadeps)
+    INSERT_VARIABLE(DataDeps)
     INSERT_VARIABLE(Defines)
     INSERT_VARIABLE(Depfile)
     INSERT_VARIABLE(Deps)
-    INSERT_VARIABLE(DirectDependentConfigs)
     INSERT_VARIABLE(ForwardDependentConfigsFrom)
     INSERT_VARIABLE(IncludeDirs)
     INSERT_VARIABLE(Inputs)
     INSERT_VARIABLE(Ldflags)
     INSERT_VARIABLE(Libs)
     INSERT_VARIABLE(LibDirs)
     INSERT_VARIABLE(OutputExtension)
     INSERT_VARIABLE(OutputName)
     INSERT_VARIABLE(Outputs)
     INSERT_VARIABLE(Public)
+    INSERT_VARIABLE(PublicConfigs)
+    INSERT_VARIABLE(PublicDeps)
     INSERT_VARIABLE(Script)
     INSERT_VARIABLE(Sources)
     INSERT_VARIABLE(Testonly)
     INSERT_VARIABLE(Visibility)
   }
   return info_map;
 }
 
 #undef INSERT_VARIABLE
 
 }  // namespace variables