Add forward_variables_from() and target() to GN

tools/gn/function_template.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/functions.h"
 
 #include "tools/gn/parse_tree.h"
 #include "tools/gn/scope.h"
 #include "tools/gn/template.h"
 #include "tools/gn/value.h"
@@ skipping 10 matching lines @@
     "  provides a way to add to the built-in target types.\n"
     "\n"
     "  The template() function is used to declare a template. To invoke the\n"
     "  template, just use the name of the template like any other target\n"
     "  type.\n"
     "\n"
     "  Often you will want to declare your template in a special file that\n"
     "  other files will import (see \"gn help import\") so your template\n"
     "  rule can be shared across build files.\n"
     "\n"
-    "More details:\n"
+    "Variables and templates:\n"
     "\n"
     "  When you call template() it creates a closure around all variables\n"
     "  currently in scope with the code in the template block. When the\n"
     "  template is invoked, the closure will be executed.\n"
     "\n"
     "  When the template is invoked, the code in the caller is executed and\n"
     "  passed to the template code as an implicit \"invoker\" variable. The\n"
     "  template uses this to read state out of the invoking code.\n"
     "\n"
     "  One thing explicitly excluded from the closure is the \"current\n"
     "  directory\" against which relative file names are resolved. The\n"
     "  current directory will be that of the invoking code, since typically\n"
     "  that code specifies the file names. This means all files internal\n"
     "  to the template should use absolute names.\n"
     "\n"
+    "  A template will typically forward some or all variables from the\n"
+    "  invoking scope to a target that it defines. Often, such variables\n"
+    "  might be optional. Use the pattern:\n"
+    "\n"
+    "    if (defined(invoker.deps)) {\n"
+    "      deps = invoker.deps\n"
+    "    }\n"
+    "\n"
+    "  The function forward_variables_from() provides a shortcut to forward\n"
+    "  one or more or possibly all variables in this manner:\n"
+    "\n"
+    "    forward_variables_from(invoker, [\"deps\", \"public_deps\"])\n"
+    "\n"
     "Target naming:\n"
     "\n"
     "  Your template should almost always define a built-in target with the\n"
     "  name the template invoker specified. For example, if you have an IDL\n"
     "  template and somebody does:\n"
     "    idl(\"foo\") {...\n"
     "  you will normally want this to expand to something defining a\n"
     "  source_set or static_library named \"foo\" (among other things you may\n"
     "  need). This way, when another target specifies a dependency on\n"
     "  \"foo\", the static_library or source_set will be linked.\n"
@@ skipping 111 matching lines @@
     err->AppendSubErr(Err(existing_template->GetDefinitionRange(),
                           "Previous definition."));
     return Value();
   }
 
   scope->AddTemplate(template_name, new Template(scope, function));
   return Value();
 }
 
 }  // namespace functions