Rework handling of os and cpu_arch in GN.

NaCl and V8 have more complicated requirements for handling architectures
than GN could previously handle. This CL reworks things to meet their
needs.

NaCl occasionally has the need to be able to override build_cpu_arch. This
comes up when they want to use a 32-bit host toolchain (i.e., build
32-bit "host" objects) on a 64-bit kernel. In addition, it is conceivable
that other projects will need this functionality on systems capable of
building for running programs for multiple architectures (any system
that can run both 32-bit and 64-bit binaries), and there is no way that
GN can always correctly guess which arch to use by default.

V8 has the need to be able to run a host toolchain that knows what the
requested target cpu_arch is; we can not use the existing "cpu_arch" for
this because that needs to be the cpu_arch of the current toolchain.
The concrete example is running a host binary on Linux x86 that needs to
get specific flags to target arm (rather than x86), for example. We could
solve this in the build configs by passing custom variables across the
toolchain, but this suggests that we should have a general solution to
track these things, which is what this CL does.

This CL introduces two new predefined variables -- target_cpu and
target_os -- and renames cpu_arch and os to to 'current_cpu' and
'current_os', and renames build_cpu_arch and build_os to
host_cpu and host_os for consistency.

current_cpu and target_cpu default to the same value as
host_cpu, and current_os and target_os default to the same value
as host_os.

Any of these variables is (and should be) overridable on the command line
or in a build config file. We want them to be overridable because (a) it's conceivable
that some projects might always want fixed values for target_os and
target_cpu_arch regardless of what platform GN is running on, and (b) we might
want to set the values based on other values (i.e., have target_cpu_arch
default to "arm" if target_os == "android").

Due to the renaming of "os" and "cpu_arch", this CL is likely to break any and
all existing project builds; projects will need to update their build configs when
rolling in the new binary.

R=brettw@chromium.org
BUG=344767

Review URL: https://codereview.chromium.org/914873002

Cr-Commit-Position: refs/heads/master@{#317120}

tools/gn/args.cc

@@ -18,10 +18,12 @@ const char kBuildArgs_Help[] =
     "\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"
+    "   - host_cpu\n"
+    "   - host_os\n"
+    "   - current_cpu\n"
+    "   - current_os\n"
+    "   - target_cpu\n"
+    "   - target_os\n"
     "\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"
@@ -221,9 +223,6 @@ void Args::SetSystemVarsLocked(Scope* dest) const {
 #else
   #error Unknown OS type.
 #endif
-  Value os_val(nullptr, std::string(os));
-  dest->SetValue(variables::kBuildOs, os_val, nullptr);
-  dest->SetValue(variables::kOs, os_val, nullptr);
 
   // Host architecture.
   static const char kX86[] = "x86";
@@ -231,7 +230,7 @@ void Args::SetSystemVarsLocked(Scope* dest) const {
   static const char kArm[] = "arm";
   const char* arch = nullptr;
 
-  // Set the CPU architecture based on the underlying OS, not
+  // Set the host CPU architecture based on the underlying OS, not
   // whatever the current bit-tedness of the GN binary is.
   std::string os_arch = base::SysInfo::OperatingSystemArchitecture();
   if (os_arch == "x86")
@@ -243,22 +242,36 @@ void Args::SetSystemVarsLocked(Scope* dest) const {
   else
     CHECK(false) << "OS architecture not handled.";
 
-  Value arch_val(nullptr, std::string(arch));
-  dest->SetValue(variables::kBuildCpuArch, arch_val, nullptr);
-  dest->SetValue(variables::kCpuArch, arch_val, nullptr);
-
   // Save the OS and architecture as build arguments that are implicitly
   // declared. This is so they can be overridden in a toolchain build args
   // override, and so that they will appear in the "gn args" output.
-  //
-  // Do not declare the build* variants since these shouldn't be changed.
-  //
+  Value empty_string(nullptr, std::string());
+
+  Value os_val(nullptr, std::string(os));
+  dest->SetValue(variables::kHostOs, os_val, nullptr);
+  dest->SetValue(variables::kTargetOs, empty_string, nullptr);
+  dest->SetValue(variables::kCurrentOs, empty_string, nullptr);
+
+  Value arch_val(nullptr, std::string(arch));
+  dest->SetValue(variables::kHostCpu, arch_val, nullptr);
+  dest->SetValue(variables::kTargetCpu, empty_string, nullptr);
+  dest->SetValue(variables::kCurrentCpu, empty_string, nullptr);
+
+  declared_arguments_[variables::kHostOs] = os_val;
+  declared_arguments_[variables::kCurrentOs] = empty_string;
+  declared_arguments_[variables::kTargetOs] = empty_string;
+  declared_arguments_[variables::kHostCpu] = arch_val;
+  declared_arguments_[variables::kCurrentCpu] = empty_string;
+  declared_arguments_[variables::kTargetCpu] = empty_string;
+
   // Mark these variables used so the build config file can override them
   // without geting a warning about overwriting an unused variable.
-  declared_arguments_[variables::kOs] = os_val;
-  declared_arguments_[variables::kCpuArch] = arch_val;
-  dest->MarkUsed(variables::kCpuArch);
-  dest->MarkUsed(variables::kOs);
+  dest->MarkUsed(variables::kHostCpu);
+  dest->MarkUsed(variables::kCurrentCpu);
+  dest->MarkUsed(variables::kTargetCpu);
+  dest->MarkUsed(variables::kHostOs);
+  dest->MarkUsed(variables::kCurrentOs);
+  dest->MarkUsed(variables::kTargetOs);
 }
 
 void Args::ApplyOverridesLocked(const Scope::KeyValueMap& values,

tools/gn/command_args.cc

@@ -322,8 +322,9 @@ extern const char kArgs_Help[] =
     "    Prints all arguments with their default values for the out/Debug\n"
     "    build.\n"
     "\n"
-    "  gn args out/Debug --list=cpu_arch\n"
-    "    Prints information about the \"cpu_arch\" argument for the out/Debug\n"
+    "  gn args out/Debug --list=target_cpu\n"
+    "    Prints information about the \"target_cpu\" argument for the "
+        "out/Debug\n"
     "    build.\n"
     "\n"
     "  gn args --list --args=\"os=\\\"android\\\" enable_doom_melon=true\"\n"

tools/gn/example/build/BUILD.gn

@@ -3,7 +3,7 @@
 # found in the LICENSE file.
 
 config("compiler_defaults") {
-  if (os == "linux") {
+  if (current_os == "linux") {
     cflags = [
       "-fPIC",
       "-pthread",

tools/gn/format_test_data/032.gn

 # Make sure continued conditions are aligned.
 if (something) {
   if (false) {
-  } else if (is_linux && !is_android && cpu_arch == "x64" && !disable_iterator_debugging) {
+  } else if (is_linux && !is_android && current_cpu == "x64" && !disable_iterator_debugging) {
   }
 }

tools/gn/format_test_data/032.golden

 # Make sure continued conditions are aligned.
 if (something) {
   if (false) {
-  } else if (is_linux && !is_android && cpu_arch == "x64" &&
+  } else if (is_linux && !is_android && current_cpu == "x64" &&
              !disable_iterator_debugging) {
   }
 }

tools/gn/misc/vim/syntax/gn.vim

@@ -16,10 +16,11 @@ syn keyword     gnConditional       if else
 hi def link     gnConditional       Conditional
 
 " Predefined variables
-syn keyword     gnPredefVar build_cpu_arch build_os cpu_arch current_toolchain
-syn keyword     gnPredefVar default_toolchain os python_path root_build_dir
-syn keyword     gnPredefVar root_gen_dir root_out_dir target_gen_dir
-syn keyword     gnPredefVar target_out_dir
+syn keyword     gnPredefVar current_cpu current_os current_toolchain
+syn keyword     gnPredefVar default_toolchain host_cpu host_os
+syn keyword     gnPredefVar root_build_dir root_gen_dir root_out_dir
+syn keyword     gnPredefVar target_cpu target_gen_dir target_out_dir
+syn keyword     gnPredefVar target_os
 syn keyword     gnPredefVar true false
 hi def link     gnPredefVar         Constant
 

tools/gn/variables.cc

@@ -8,24 +8,153 @@ namespace variables {
 
 // Built-in variables ----------------------------------------------------------
 
-const char kCpuArch[] = "cpu_arch";
-const char kCpuArch_HelpShort[] =
-    "cpu_arch: [string] Current processor architecture.";
-const char kCpuArch_Help[] =
-    "cpu_arch: Current processor architecture.\n"
+const char kHostCpu[] = "host_cpu";
+const char kHostCpu_HelpShort[] =
+    "host_cpu: [string] The processor architecture that GN is running on.";
+const char kHostCpu_Help[] =
+    "host_cpu: The processor architecture that GN is running on.\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"
+    "  This is value is exposed so that cross-compile toolchains can\n"
+    "  access the host architecture when needed.\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"
+    "  The value should generally be considered read-only, but it can be\n"
+    "  overriden in order to handle unusual cases where there might\n"
+    "  be multiple plausible values for the host architecture (e.g., if\n"
+    "  you can do either 32-bit or 64-bit builds). The value is not used\n"
+    "  internally by GN for any purpose.\n"
     "\n"
-    "Possible initial values set by GN:\n"
+    "Some possible values:\n"
+    "  - \"x64\"\n"
+    "  - \"x86\"\n";
+
+const char kHostOs[] = "host_os";
+const char kHostOs_HelpShort[] =
+    "host_os: [string] The operating system that GN is running on.";
+const char kHostOs_Help[] =
+    "host_os: [string] The operating system that GN is running on.\n"
+    "\n"
+    "  This value is exposed so that cross-compiles can access the host\n"
+    "  build system's settings.\n"
+    "\n"
+    "  This value should generally be treated as read-only. It, however,\n"
+    "  is not used internally by GN for any purpose.\n"
+    "\n"
+    "Some possible values:\n"
+    "  - \"linux\"\n"
+    "  - \"mac\"\n"
+    "  - \"win\"\n";
+
+const char kTargetCpu[] = "target_cpu";
+const char kTargetCpu_HelpShort[] =
+    "target_cpu: [string] The desired cpu architecture for the build.";
+const char kTargetCpu_Help[] =
+    "target_cpu: The desired cpu architecture for the build.\n"
+    "\n"
+    "  This value should be used to indicate the desired architecture for\n"
+    "  the primary objects of the build. It will match the cpu architecture\n"
+    "  of the default toolchain.\n"
+    "\n"
+    "  In many cases, this is the same as \"host_cpu\", but in the case\n"
+    "  of cross-compiles, this can be set to something different. This \n"
+    "  value is different from \"current_cpu\" in that it can be referenced\n"
+    "  from inside any toolchain. This value can also be ignored if it is\n"
+    "  not needed or meaningful for a project.\n"
+    "\n"
+    "  This value is not used internally by GN for any purpose, so it\n"
+    "  may be set to whatever value is needed for the build.\n"
+    "  GN defaults this value to the empty string (\"\") and the\n"
+    "  configuration files should set it to an appropriate value\n"
+    "  (e.g., setting it to the value of \"host_cpu\") if it is not\n"
+    "  overridden on the command line or in the args.gn file.\n"
+    "\n"
+    "  Where practical, use one of the following list of common values:\n"
+    "\n"
+    "Possible values:\n"
     "  - \"x86\"\n"
     "  - \"x64\"\n"
     "  - \"arm\"\n"
+    "  - \"arm64\"\n"
     "  - \"mipsel\"\n";
 
+const char kTargetOs[] = "target_os";
+const char kTargetOs_HelpShort[] =
+    "target_os: [string] The desired operating system for the build.";
+const char kTargetOs_Help[] =
+    "target_os: The desired operating system for the build.\n"
+    "\n"
+    "  This value should be used to indicate the desired operating system\n"
+    "  for the primary object(s) of the build. It will match the OS of\n"
+    "  the default toolchain.\n"
+    "\n"
+    "  In many cases, this is the same as \"host_os\", but in the case of\n"
+    "  cross-compiles, it may be different. This variable differs from\n"
+    "  \"current_os\" in that it can be referenced from inside any\n"
+    "  toolchain and will always return the initial value.\n"
+    "\n"
+    "  This should be set to the most specific value possible. So,\n"
+    "  \"android\" or \"chromeos\" should be used instead of \"linux\"\n"
+    "  where applicable, even though Android and ChromeOS are both Linux\n"
+    "  variants. This can mean that one needs to write\n"
+    "\n"
+    "      if (target_os == \"android\" || target_os == \"linux\") {\n"
+    "          # ...\n"
+    "      }\n"
+    "\n"
+    "  and so forth.\n"
+    "\n"
+    "  This value is not used internally by GN for any purpose, so it\n"
+    "  may be set to whatever value is needed for the build.\n"
+    "  GN defaults this value to the empty string (\"\") and the\n"
+    "  configuration files should set it to an appropriate value\n"
+    "  (e.g., setting it to the value of \"host_os\") if it is not\n"
+    "  set via the command line or in the args.gn file.\n"
+    "\n"
+    "  Where practical, 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 kCurrentCpu[] = "current_cpu";
+const char kCurrentCpu_HelpShort[] =
+    "current_cpu: [string] The processor architecture of the current "
+        "toolchain.";
+const char kCurrentCpu_Help[] =
+    "current_cpu: The processor architecture of the current toolchain.\n"
+    "\n"
+    "  The build configuration usually sets this value based on the value\n"
+    "  of \"host_cpu\" (see \"gn help host_cpu\") 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. It is\n"
+    "  set it to the empty string (\"\") by default but is declared so\n"
+    "  that it can be overridden on the command line if so desired.\n"
+    "\n"
+    "  See \"gn help target_cpu\" for a list of common values returned.\n";
+
+const char kCurrentOs[] = "current_os";
+const char kCurrentOs_HelpShort[] =
+    "current_os: [string] The operating system of the current toolchain.";
+const char kCurrentOs_Help[] =
+    "current_os: The operating system of the current toolchain.\n"
+    "\n"
+    "  The build configuration usually sets this value based on the value\n"
+    "  of \"target_os\" (see \"gn help target_os\"), and then threads this\n"
+    "  through the toolchain definitions to ensure that it always reflects\n"
+    "  the appropriate value.\n"
+    "\n"
+    "  This value is not used internally by GN for any purpose. It is\n"
+    "  set it to the empty string (\"\") by default but is declared so\n"
+    "  that it can be overridden on the command line if so desired.\n"
+    "\n"
+    "  See \"gn help target_os\" for a list of common values returned.\n";
+
 const char kCurrentToolchain[] = "current_toolchain";
 const char kCurrentToolchain_HelpShort[] =
     "current_toolchain: [string] Label of the current toolchain.";
@@ -42,30 +171,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.";
@@ -75,33 +180,6 @@ const char kDefaultToolchain_Help[] =
     "  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.";
-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"
-    "\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";
-
 const char kPythonPath[] = "python_path";
 const char kPythonPath_HelpShort[] =
     "python_path: [string] Absolute path of Python.";
@@ -975,16 +1053,18 @@ VariableInfo::VariableInfo(const char* in_help_short, const char* in_help)
 const VariableInfoMap& GetBuiltinVariables() {
   static VariableInfoMap info_map;
   if (info_map.empty()) {
-    INSERT_VARIABLE(BuildCpuArch)
-    INSERT_VARIABLE(BuildOs)
-    INSERT_VARIABLE(CpuArch)
+    INSERT_VARIABLE(CurrentCpu)
+    INSERT_VARIABLE(CurrentOs)
     INSERT_VARIABLE(CurrentToolchain)
     INSERT_VARIABLE(DefaultToolchain)
-    INSERT_VARIABLE(Os)
+    INSERT_VARIABLE(HostCpu)
+    INSERT_VARIABLE(HostOs)
     INSERT_VARIABLE(PythonPath)
     INSERT_VARIABLE(RootBuildDir)
     INSERT_VARIABLE(RootGenDir)
     INSERT_VARIABLE(RootOutDir)
+    INSERT_VARIABLE(TargetCpu)
+    INSERT_VARIABLE(TargetOs)
     INSERT_VARIABLE(TargetGenDir)
     INSERT_VARIABLE(TargetOutDir)
   }

tools/gn/variables.h

@@ -13,17 +13,21 @@ namespace variables {
 
 // Builtin vars ----------------------------------------------------------------
 
-extern const char kBuildCpuArch[];
-extern const char kBuildCpuArch_HelpShort[];
-extern const char kBuildCpuArch_Help[];
+extern const char kHostCpu[];
+extern const char kHostCpu_HelpShort[];
+extern const char kHostCpu_Help[];
 
-extern const char kBuildOs[];
-extern const char kBuildOs_HelpShort[];
-extern const char kBuildOs_Help[];
+extern const char kHostOs[];
+extern const char kHostOs_HelpShort[];
+extern const char kHostOs_Help[];
 
-extern const char kCpuArch[];
-extern const char kCpuArch_HelpShort[];
-extern const char kCpuArch_Help[];
+extern const char kCurrentCpu[];
+extern const char kCurrentCpu_HelpShort[];
+extern const char kCurrentCpu_Help[];
+
+extern const char kCurrentOs[];
+extern const char kCurrentOs_HelpShort[];
+extern const char kCurrentOs_Help[];
 
 extern const char kCurrentToolchain[];
 extern const char kCurrentToolchain_HelpShort[];
@@ -33,10 +37,6 @@ extern const char kDefaultToolchain[];
 extern const char kDefaultToolchain_HelpShort[];
 extern const char kDefaultToolchain_Help[];
 
-extern const char kOs[];
-extern const char kOs_HelpShort[];
-extern const char kOs_Help[];
-
 extern const char kPythonPath[];
 extern const char kPythonPath_HelpShort[];
 extern const char kPythonPath_Help[];
@@ -53,6 +53,14 @@ extern const char kRootOutDir[];
 extern const char kRootOutDir_HelpShort[];
 extern const char kRootOutDir_Help[];
 
+extern const char kTargetCpu[];
+extern const char kTargetCpu_HelpShort[];
+extern const char kTargetCpu_Help[];
+
+extern const char kTargetOs[];
+extern const char kTargetOs_HelpShort[];
+extern const char kTargetOs_Help[];
+
 extern const char kTargetGenDir[];
 extern const char kTargetGenDir_HelpShort[];
 extern const char kTargetGenDir_Help[];