Redo GN "args" command

tools/gn/args.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/args.h"
 
 #include "build/build_config.h"
 #include "tools/gn/variables.h"
 
 #if defined(OS_WIN)
 #include "base/win/windows_version.h"
 #endif
 
 const char kBuildArgs_Help[] =
     "Build Arguments Overview\n"
     "\n"
     "  Build arguments are variables passed in from outside of the build\n"
     "  that build files can query to determine how the build works.\n"
     "\n"
     "How build arguments are set\n"
     "\n"
     "  First, system default arguments are set based on the current system.\n"
     "  The built-in arguments are:\n"
     "   - cpu_arch (by default this is the same as \"default_cpu_arch\")\n"
     "   - default_cpu_arch\n"
     "   - default_os\n"
     "   - os (by default this is the same as \"default_os\")\n"
     "\n"
-    "  Second, arguments specified on the command-line via \"--args\" are\n"
-    "  applied. These can override the system default ones, and add new ones.\n"
-    "  These are whitespace-separated. For example:\n"
+    "  If specified, arguments from the --args command line flag are used. If\n"
+    "  that flag is not specified, args from previous builds in the build\n"
+    "  directory will be used (this is in the file gn.args in the build\n"

[tfarina, 2014/05/01 18:06:46]

so does that mean the sequence of commands you be like this?

$ gn args out/Release_gn
# editor opens
# type is_debug=false
# type use_aura=true

$ gn gen out/Release_gn

if I understood this right, it seems cool, because it saves typing and time in
the subsequent calls to gn gen.

+    "  directory).\n"
     "\n"
-    "    gn --args=\"enable_doom_melon=false\" os=\\\"beos\\\"\n"
-    "\n"
-    "  Third, toolchain overrides are applied. These are specified in the\n"
+    "  Last, for targets being compiled with a non-default toolchain, the\n"
+    "  toolchain overrides are applied. These are specified in the\n"
     "  toolchain_args section of a toolchain definition. The use-case for\n"
     "  this is that a toolchain may be building code for a different\n"
     "  platform, and that it may want to always specify Posix, for example.\n"
     "  See \"gn help toolchain_args\" for more.\n"
     "\n"
-    "  It is an error to specify an override for a build argument that never\n"
-    "  appears in a \"declare_args\" call.\n"
+    "  If you specify an override for a build argument that never appears in\n"
+    "  a \"declare_args\" call, a nonfatal error will be displayed.\n"
+    "\n"
+    "Examples\n"
+    "\n"
+    "  gn args out/FooBar\n"
+    "      Create the directory out/FooBar and open an editor. You would type\n"
+    "      something like this into that file:\n"
+    "          enable_doom_melon=false\n"
+    "          os=\"android\"\n"
+    "\n"
+    "  gn gen out/FooBar --args=\"enable_doom_melon=true os=\\\"android\\\"\"\n"
+    "      This will overwrite the build directory with the given arguments.\n"
+    "      (Note that the quotes inside the args command will usually need to\n"
+    "      be escaped for your shell to pass through strings values.)\n"
     "\n"
     "How build arguments are used\n"
     "\n"
     "  If you want to use an argument, you use declare_args() and specify\n"
     "  default values. These default values will apply if none of the steps\n"
     "  listed in the \"How build arguments are set\" section above apply to\n"
     "  the given argument, but the defaults will not override any of these.\n"
     "\n"
     "  Often, the root build config file will declare global arguments that\n"
     "  will be passed to all buildfiles. Individual build files can also\n"
@@ skipping 225 matching lines @@
        i != values.end(); ++i)
     scope->SetValue(i->first, i->second, i->second.origin());
 }
 
 void Args::SaveOverrideRecordLocked(const Scope::KeyValueMap& values) const {
   lock_.AssertAcquired();
   for (Scope::KeyValueMap::const_iterator i = values.begin();
        i != values.end(); ++i)
     all_overrides_[i->first] = i->second;
 }