Add documentation for exec_script and gypi_to_gn

.gn

 # This file is used by the GN meta build system to find the root of the source
 # tree and to set startup options. For documentation on the values set in this
 # file, run "gn help dotfile" at the command line.
 
 # The location of the build configuration file.
 buildconfig = "//build/config/BUILDCONFIG.gn"
 
 # The secondary source root is a parallel directory tree where
 # GN build files are placed when they can not be placed directly
 # in the source tree, e.g. for third party source trees.
@@ skipping 121 matching lines @@
   "//ui/web_dialogs/*",
   "//ui/webui/*",
   "//ui/wm/*",
   "//url/*",
   "//v8/*",
   "//win8/*",
 ]
 
 # These are the list of GN files that run exec_script. This whitelist exists
 # to force additional review for new uses of exec_script, which is strongly
-# discouraged except for gypi_to_gn calls.
+# discouraged.
+#
+# GYPI_TO_GN
+#
+# Most of these entries are for gypi_to_gn calls. We should not be adding new
+# calls to this script in the build (see //build/gypi_to_gn.py for detailed
+# advice). The only time you should be editing this list for gypi_to_gn
+# purposes is when moving an existing call to a different place.
+#
+# PLEASE READ
+#
+# You should almost never need to add new exec_script calls. exec_script is
+# slow, especially on Windows, and can cause confusing effects. Although
+# individually each call isn't slow or necessarily very confusing, at the scale
+# of our repo things get out of hand quickly. By strongly pushing back on all
+# additions, we keep the build fast and clean. If you think you need to add a
+# new call, please consider:
+#
+# - Do not use a script to check for the existance of a file or directory to
+#   enable a different mode. Instead, use GN build args to enable or disable
+#   functionality and set options. An example is checking for a file in the
+#   src-internal repo to see if the corresponding src-internal feature should
+#   be enabled. There are several things that can go wrong with this:
+#
+#    - It's myserious what causes some things to happen. Although in many cases

[Dirk Pranke, 2016/04/19 21:36:06]

s/myserious/mysterious

+#      such behavior can be conveniently automatic, GN optimizes for explicit
+#      and obvious behavior so people can more easily diagnose problems.
+#
+#    - The user can't enable a mode for one build and not another. With GN build
+#      args, the user can choose the exact configuration of multiple builds
+#      using one checkout. But implicitly basing flags on the state of the
+#      checkout, this functionality is broken.
+#
+#    - It's easy to get stale files. If for example the user edits the gclient
+#      to stop checking out src-internal (or any other optional thing), it's
+#      easy to end up with stale files still mysteriously triggering build
+#      conditions that are no longer appropriate (yes, this happens in real
+#      life).
+#
+# - Do not use a script to iterate files in a directory (glob):
+#
+#    - This has the same "stale file" problem as the above discussion. Various
+#      operations can leave untracked files in the source tree which can cause
+#      surprising effects.
+#
+#    - It becomes impossible to use "git grep" to find where a certain file is
+#      referenced. This operation is very common and people really do get
+#      confused when things aren't listed.
+#
+#    - It's easy to screw up. One common case is a build-time script that packs
+#      up a directory. The author notices that the script isn't re-run when the
+#      directory is updated, so adds a glob so all the files are listed as
+#      inputs. This seems to work great... until a file is deleted. When a
+#      file is deleted, all the inputs the glob lists will still be up-to-date
+#      and no command-lines will have been changed. The action will not be
+#      re-run and the build will be broken. It is possible to get this correct
+#      using glob, and it's possible to mess it up without glob, but globs make
+#      this situation much easier to create. if the build always lists the
+#      files and passes them to a script, it will always be correct.
 exec_script_whitelist = [
   "//android_webview/BUILD.gn",
   "//ash/BUILD.gn",
   "//build/config/BUILD.gn",
   "//build/config/android/config.gni",
   "//build/config/android/internal_rules.gni",
   "//build/config/android/rules.gni",
   "//build/config/compiler/BUILD.gn",
   "//build/config/gcc/gcc_version.gni",
   "//build/config/ios/ios_sdk.gni",
@@ skipping 89 matching lines @@
   "//tools/gn/format_test_data/055.golden",
   "//tools/gn/function_exec_script.cc",
   "//tools/gn/gn.gyp",
   "//tools/gn/input_conversion.cc",
   "//tools/gn/misc/emacs/gn.el",
   "//tools/gn/misc/vim/syntax/gn.vim",
   "//tools/gn/setup.cc",
   "//ui/accessibility/BUILD.gn",
   "//ui/views/BUILD.gn",
 ]