Rework handling of os and cpu_arch in GN.

tools/gn/variables.cc

Index: tools/gn/variables.cc
diff --git a/tools/gn/variables.cc b/tools/gn/variables.cc
index 4b0c5142cfecc942e6bce89df3c4b65f9fae825a..35cbb41e375c3daa66b375cb344a9b55c8a9a97f 100644
--- a/tools/gn/variables.cc
+++ b/tools/gn/variables.cc
@@ -7,24 +7,56 @@
 namespace variables {
 
 // Built-in variables ----------------------------------------------------------
+const char kBuildCpuArch[] = "build_cpu_arch";
+const char kBuildCpuArch_HelpShort[] =
+    "build_cpu_arch: [string] The processor architecture that GN is "
+    "running on.";
+const char kBuildCpuArch_Help[] =
+    "build_cpu_arch: The processor architecture that GN is running on.\n"
+    "\n"
+    "  This value is used to set the initial value for \"cpu_arch\" (see\n"
+    "  \"gn help cpu_arch\") but otherwise should usually be treated as\n"
+    "  read-only. This is exposed so that cross-compile toolchains can still\n"
+    "  access the host architecture when needed, and is overridable to handle\n"
+    "  unusual cases where there might be multiple plausible values for the\n"
+    "  host architecture (e.g., if you can do either 32-bit or 64-bit builds.\n"

[scottmg, 2015/02/11 03:06:20]

) missing here

[Dirk Pranke, 2015/02/11 22:51:11]

Acknowledged.

+    "\n"
+    "Some possible values:\n"
+    "  - \"x64\"\n"
+    "  - \"x86\"\n";
+
+const char kBuildOs[] = "build_os";
+const char kBuildOs_HelpShort[] =
+    "build_os: [string] The default value for the \"os\" variable.";
+const char kBuildOs_Help[] =
+    "build_os: [string] The default value for the \"os\" variable.\n"
+    "\n"
+    "  This value has the same definition as \"os\" (see \"gn help os\") but\n"
+    "  should be treated as read-only. This is so the build can override\n"
+    "  the \"os\" variable for doing cross-compiles, but can still access\n"
+    "  the host build system's operating system type.\n"
+    "\n"
+    "Some possible values:\n"
+    "  - \"linux\"\n"
+    "  - \"mac\"\n"
+    "  - \"win\"\n";
 
 const char kCpuArch[] = "cpu_arch";
 const char kCpuArch_HelpShort[] =
-    "cpu_arch: [string] Current processor architecture.";
+    "cpu_arch: [string] The processor architecture of the current toolchain.";
 const char kCpuArch_Help[] =
-    "cpu_arch: Current processor architecture.\n"
+    "cpu_arch: The processor architecture of the current toolchain.\n"
     "\n"
-    "  The initial value is based on the current architecture of the host\n"
-    "  system. However, the build configuration can set this to any value.\n"
+    "  The build configuration usually sets this value based on\n"
+    " \"build_cpu_arch\" (see \"gn help build_cpu_arch\") and then threads\n"
+    "  this through the toolchain definitions to ensure that it always\n"
+    "  reflects the appropriate value.\n"
     "\n"
     "  This value is not used internally by GN for any purpose, so you can\n"
-    "  set it to whatever value is relevant to your build.\n"
-    "\n"
-    "Possible initial values set by GN:\n"
-    "  - \"x86\"\n"
-    "  - \"x64\"\n"
-    "  - \"arm\"\n"
-    "  - \"mipsel\"\n";
+    "  set it to whatever value is relevant to your build, but where \n"
+    "  you should stick to a list of common values for consistency. See\n"
+    "  \"gn help target_cpu_arch\" for the list.\n"
+    "\n";
 
 const char kCurrentToolchain[] = "current_toolchain";
 const char kCurrentToolchain_HelpShort[] =
@@ -42,30 +74,6 @@ const char kCurrentToolchain_Help[] =
     "    executable(\"output_thats_64_bit_only\") {\n"
     "      ...\n";
 
-const char kBuildCpuArch[] = "build_cpu_arch";
-const char kBuildCpuArch_HelpShort[] =
-    "build_cpu_arch: [string] The default value for the \"cpu_arch\" "
-    "variable.";
-const char kBuildCpuArch_Help[] =
-    "build_cpu_arch: The default value for the \"cpu_arch\" variable.\n"
-    "\n"
-    "  This value has the same definition as \"cpu_arch\" (see\n"
-    "  \"gn help cpu_arch\") but should be treated as read-only. This is so\n"
-    "  the build can override the \"cpu_arch\" variable for doing\n"
-    "  cross-compiles, but can still access the host build system's CPU\n"
-    "  architecture.\n";
-
-const char kBuildOs[] = "build_os";
-const char kBuildOs_HelpShort[] =
-    "build_os: [string] The default value for the \"os\" variable.";
-const char kBuildOs_Help[] =
-    "build_os: [string] The default value for the \"os\" variable.\n"
-    "\n"
-    "  This value has the same definition as \"os\" (see \"gn help os\") but\n"
-    "  should be treated as read-only. This is so the build can override\n"
-    "  the \"os\" variable for doing cross-compiles, but can still access\n"
-    "  the host build system's operating system type.\n";
-
 const char kDefaultToolchain[] = "default_toolchain";
 const char kDefaultToolchain_HelpShort[] =
     "default_toolchain: [string] Label of the default toolchain.";
@@ -77,30 +85,16 @@ const char kDefaultToolchain_Help[] =
 
 const char kOs[] = "os";
 const char kOs_HelpShort[] =
-    "os: [string] Indicates the operating system of the current build.";
+    "os: [string] Indicates the operating system of the current toolchain.";
 const char kOs_Help[] =
-    "os: Indicates the operating system of the current build."
-    "\n"
-    "  This value is set by default based on the current host operating\n"
-    "  system. The build configuration can override the value to anything\n"
-    "  it wants, or it can be set via the build arguments on the command\n"
-    "  line.\n"
+    "os: Indicates the operating system of the current toolchain.\n"
     "\n"
-    "  If you want to know the default value without any overrides, you can\n"
-    "  use \"default_os\" (see \"gn help default_os\").\n"
+    "  This value is set by default to the value of \"target_os\" (see gn \n"
+    "  help target_os\"), but the build configuration can override the\n"
+    "  value to anything it wants, or it can be set via the build arguments \n"
+    "  on the command line.\n"
     "\n"
-    "  Note that this returns the most specific value. So even though\n"
-    "  Android and ChromeOS are both Linux, the more specific value will\n"
-    "  be returned.\n"
-    "\n"
-    "Some possible values:\n"
-    "  - \"amiga\"\n"
-    "  - \"android\"\n"
-    "  - \"chromeos\"\n"
-    "  - \"ios\"\n"
-    "  - \"linux\"\n"
-    "  - \"mac\"\n"
-    "  - \"win\"\n";
+    "  See \"gn help target_os\" for a list of common values returned.\n";
 
 const char kPythonPath[] = "python_path";
 const char kPythonPath_HelpShort[] =
@@ -167,6 +161,67 @@ const char kRootOutDir_Help[] =
     "    args = [ \"-o\", rebase_path(root_out_dir, root_build_dir) ]\n"
     "  }\n";
 
+const char kTargetCpuArch[] = "target_cpu_arch";
+const char kTargetCpuArch_HelpShort[] =
+    "target_cpu_arch: [string] The desired cpu architecture for your build.";
+const char kTargetCpuArch_Help[] =
+    "target_cpu_arch: The desired cpu architecture for your build.\n"
+    "\n"
+    "  This value should be used to indicate the desired architecture for\n"
+    "  the primary object of the build. In many cases, this is the same as\n"
+    "  \"build_cpu_arch\", but in the case of cross-compiles, this can be\n"
+    "  set to something different. This value is different from \"cpu_arch\"\n"
+    "  in that it can be referenced from inside any toolchain.\n"
+    "\n"
+    "  This value is usually set once at the beginning of the build\n"
+    "  configuration files and can be overridden on the command line, but\n"
+    "  should otherwise be considered read only.\n"
+    "\n"
+    "  This value is not used internally by GN for any purpose, so you can\n"
+    "  set it to whatever value is relevant to your build, but where\n"
+    "  you should stick to the following list of common values:\n"
+    "\n"
+    "Possible values:\n"
+    "  - \"x86\"\n"
+    "  - \"x64\"\n"
+    "  - \"arm\"\n"
+    "  - \"mipsel\"\n";
+
+const char kTargetOs[] = "target_os";
+const char kTargetOs_HelpShort[] =
+    "target_os: [string] The desired operating system for your build.";
+const char kTargetOs_Help[] =
+    "target_os_arch: The desired operating system for your build.\n"
+    "\n"
+    "  This value should be used to indicate the desired operating system for\n"
+    "  the primary object of the build. In many cases, this is the same as\n"
+    "  \"build_os\", but in the case of cross-compiles, this may be\n"
+    "  different. This variable differs from \"os\" in that it can be\n"
+    "  referenced from inside any toolchain and will always return the\n"
+    "  initial value.\n"
+    "\n"
+    "  This value defaults to \"build_os\" but can overridden in the\n"
+    "  configuration files or on the command line. If the configuration files\n"
+    "  do not use the default, it should be set only once, and\n"
+    "  otherwise be considered read only.\n"
+    "\n"
+    "  Note that this returns the most specific value. So even though\n"
+    "  Android and ChromeOS are both Linux, the more specific value will\n"
+    "  be returned.\n"
+    "\n"
+    "  This value is not used internally by GN for any purpose, so you can\n"
+    "  set it to whatever value is relevant to your build, but where\n"
+    "  it makes sense, use one of the following list of common values:\n"
+    "\n"
+    "Possible values:\n"
+    "  - \"android\"\n"
+    "  - \"chromeos\"\n"
+    "  - \"ios\"\n"
+    "  - \"linux\"\n"
+    "  - \"nacl\"\n"
+    "  - \"mac\"\n"
+    "  - \"win\"\n";
+
 const char kTargetGenDir[] = "target_gen_dir";
 const char kTargetGenDir_HelpShort[] =
     "target_gen_dir: [string] Directory for a target's generated files.";
@@ -985,6 +1040,8 @@ const VariableInfoMap& GetBuiltinVariables() {
     INSERT_VARIABLE(RootBuildDir)
     INSERT_VARIABLE(RootGenDir)
     INSERT_VARIABLE(RootOutDir)
+    INSERT_VARIABLE(TargetCpuArch)
+    INSERT_VARIABLE(TargetOs)
     INSERT_VARIABLE(TargetGenDir)
     INSERT_VARIABLE(TargetOutDir)
   }