Rework handling of os and cpu_arch in GN.

tools/gn/variables.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/variables.h"
 
 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[] =
     "current_toolchain: [string] Label of the current toolchain.";
 const char kCurrentToolchain_Help[] =
     "current_toolchain: Label of the current toolchain.\n"
     "\n"
     "  A fully-qualified label representing the current toolchain. You can\n"
     "  use this to make toolchain-related decisions in the build. See also\n"
     "  \"default_toolchain\".\n"
     "\n"
     "Example:\n"
     "\n"
     "  if (current_toolchain == \"//build:64_bit_toolchain\") {\n"
     "    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.";
 const char kDefaultToolchain_Help[] =
     "default_toolchain: [string] Label of the default toolchain.\n"
     "\n"
     "  A fully-qualified label representing the default toolchain, which may\n"
     "  not necessarily be the current one (see \"current_toolchain\").\n";
 
 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."
+    "os: Indicates the operating system of the current toolchain.\n"
     "\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"
+    "  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"
-    "  If you want to know the default value without any overrides, you can\n"
-    "  use \"default_os\" (see \"gn help default_os\").\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[] =
     "python_path: [string] Absolute path of Python.";
 const char kPythonPath_Help[] =
     "python_path: Absolute path of Python.\n"
     "\n"
     "  Normally used in toolchain definitions if running some command\n"
     "  requires Python. You will normally not need this when invoking scripts\n"
     "  since GN automatically finds it for you.\n";
@@ skipping 46 matching lines @@
     "  See also \"target_out_dir\" which is usually a better location for\n"
     "  output files. It will be inside the root output dir.\n"
     "\n"
     "Example:\n"
     "\n"
     "  action(\"myscript\") {\n"
     "    # Pass the output dir to the script.\n"
     "    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.";
 const char kTargetGenDir_Help[] =
     "target_gen_dir: Directory for a target's generated files.\n"
     "\n"
     "  Absolute path to the target's generated file directory. If your\n"
     "  current target is in \"//tools/doom_melon\" then this value might be\n"
     "  \"//out/Debug/gen/tools/doom_melon\". It will not have a trailing\n"
     "  slash.\n"
@@ skipping 798 matching lines @@
     INSERT_VARIABLE(BuildCpuArch)
     INSERT_VARIABLE(BuildOs)
     INSERT_VARIABLE(CpuArch)
     INSERT_VARIABLE(CurrentToolchain)
     INSERT_VARIABLE(DefaultToolchain)
     INSERT_VARIABLE(Os)
     INSERT_VARIABLE(PythonPath)
     INSERT_VARIABLE(RootBuildDir)
     INSERT_VARIABLE(RootGenDir)
     INSERT_VARIABLE(RootOutDir)
+    INSERT_VARIABLE(TargetCpuArch)
+    INSERT_VARIABLE(TargetOs)
     INSERT_VARIABLE(TargetGenDir)
     INSERT_VARIABLE(TargetOutDir)
   }
   return info_map;
 }
 
 const VariableInfoMap& GetTargetVariables() {
   static VariableInfoMap info_map;
   if (info_map.empty()) {
     INSERT_VARIABLE(AllDependentConfigs)
@@ skipping 28 matching lines @@
     INSERT_VARIABLE(Sources)
     INSERT_VARIABLE(Testonly)
     INSERT_VARIABLE(Visibility)
   }
   return info_map;
 }
 
 #undef INSERT_VARIABLE
 
 }  // namespace variables