Update all_dependent_configs docs.
The documentation for this variable was not clear that this feature
should be avoided, and seemed to endorse it for some cases where other
solutions are better. This clarifies the guidance for using this
feature.
Change-Id: I48c070f0dc8bc63103fe77f4bcd3d0442de8e87e
Reviewed-on: https://gn-review.googlesource.com/c/gn/+/17760
Reviewed-by: Dirk Pranke <dpranke@google.com>
Commit-Queue: Brett Wilson <brettw@google.com>
diff --git a/docs/reference.md b/docs/reference.md
index 0dfd861..041628c 100644
--- a/docs/reference.md
+++ b/docs/reference.md
@@ -4882,9 +4882,21 @@
This addition happens in a second phase once a target and all of its
dependencies have been resolved. Therefore, a target will not see these
force-added configs in their "configs" variable while the script is running,
- and they can not be removed. As a result, this capability should generally
- only be used to add defines and include directories necessary to compile a
- target's headers.
+ and they can not be removed.
+
+ Use of all_dependent_configs should be avoided when possible.
+
+ If your target has include_dirs and defines needed by targets that depend on
+ it, the correct solution is to add those settings to public_configs and those
+ targets choose whether to forward them up the dependency tree by whether they
+ depend on your target via public_deps or not.
+
+ There are two recommended uses of this feature:
+
+ 1. Legacy cases that can't easily be updated to use the proper public deps
+ and configs.
+ 2. Additional linker flag that need to be set on the final linked target
+ regardless of whether the dependency path is public or private.
See also "public_configs".
```
diff --git a/src/gn/variables.cc b/src/gn/variables.cc
index 710a3de..0831bf5 100644
--- a/src/gn/variables.cc
+++ b/src/gn/variables.cc
@@ -437,9 +437,21 @@
This addition happens in a second phase once a target and all of its
dependencies have been resolved. Therefore, a target will not see these
force-added configs in their "configs" variable while the script is running,
- and they can not be removed. As a result, this capability should generally
- only be used to add defines and include directories necessary to compile a
- target's headers.
+ and they can not be removed.
+
+ Use of all_dependent_configs should be avoided when possible.
+
+ If your target has include_dirs and defines needed by targets that depend on
+ it, the correct solution is to add those settings to public_configs and those
+ targets choose whether to forward them up the dependency tree by whether they
+ depend on your target via public_deps or not.
+
+ There are two recommended uses of this feature:
+
+ 1. Legacy cases that can't easily be updated to use the proper public deps
+ and configs.
+ 2. Additional linker flag that need to be set on the final linked target
+ regardless of whether the dependency path is public or private.
See also "public_configs".
)" COMMON_ORDERING_HELP;
