[gndoc] Update GN build arguments documentation

Test: CQ

Change-Id: I6ae5d995f2e9c824b82aff9c9c985d604e7a6cbf

zircon/docs/gen/build_arguments.md

@@ -2,16 +2,71 @@
 
 ## All builds
 
-### current_os
+### asan_default_options
+Default [AddressSanitizer](https://llvm.org/docs/AddressSanitizer.html)
+options (before the `ASAN_OPTIONS` environment variable is read at
+runtime).  This can be set as a build argument to affect most "asan"
+variants in $variants (which see), or overridden in $toolchain_args in
+one of those variants.  Note that setting this nonempty may conflict
+with programs that define their own `__asan_default_options` C
+function.
 
 **Current value (from the default):** `""`
 
-### enable_acpi_debug
-Enable debug output in the ACPI library (used by the ACPI bus driver).
+From //public/gn/config/instrumentation/BUILD.gn:15
 
-**Current value (from the default):** `false`
+### symbol_level
+* 0 means no debugging information.
+* 1 means minimal debugging information sufficient to symbolize backtraces.
+* 2 means full debugging information for use with a symbolic debugger.
 
-From //third_party/lib/acpica/BUILD.gn:9
+**Current value (from the default):** `2`
+
+From //public/gn/config/levels.gni:20
+
+### thinlto_cache_dir
+ThinLTO cache directory path.
+
+**Current value (from the default):** `"user-arm64-thinlto.shlib/thinlto-cache"`
+
+From //public/gn/config/lto/BUILD.gn:22
+
+### build_id_dir
+Directory to populate with `xx/yyy` and `xx/yyy.debug` links to ELF
+files.  For every ELF binary built, with build ID `xxyyy` (lowercase
+hexadecimal of any length), `xx/yyy` is a hard link to the stripped
+file and `xx/yyy.debug` is a hard link to the unstripped file.
+Symbolization tools and debuggers find symbolic information this way.
+
+**Current value (from the default):** `"/b/s/w/ir/k/out/build-zircon/.build-id"`
+
+From //public/gn/toolchain/c_toolchain.gni:17
+
+### kernel_version_string
+Version string embedded in the kernel for `zx_system_get_version`.
+If set to the default "", a string is generated based on the
+Zircon git revision of the checkout.
+
+**Current value (from the default):** `""`
+
+From //kernel/lib/version/BUILD.gn:9
+
+### use_prebuilt_gcc
+If $gcc_tool_dir is "", then this controls how the GCC toolchain
+binaries are found.  If true, the standard prebuilt is used.  If false,
+the tools are just expected to be found in PATH.
+
+**Current value (from the default):** `true`
+
+From //public/gn/toolchain/gcc.gni:9
+
+### current_cpu
+
+**Current value (from the default):** `""`
+
+### current_os
+
+**Current value (from the default):** `""`
 
 ### enable_kernel_debugging_features
 Whether to include various features (non-shipping, insecure, etc.) in the
@@ -25,48 +80,52 @@ From //public/gn/config/product_parameters.gni:12
 
 **Current value (from the default):** `"x64"`
 
-### kernel_extra_defines
-Extra macro definitions for kernel code, e.g. "DISABLE_KASLR",
-"ENABLE_KERNEL_LL_DEBUG".
+### clang_tool_dir
+Directory where the Clang toolchain binaries ("clang", "llvm-nm", etc.) are
+found.  If this is "", then the behavior depends on $use_prebuilt_clang.
+This toolchain is expected to support both Fuchsia targets and the host.
 
-**Current value (from the default):** `[]`
+**Current value (from the default):** `""`
 
-From //kernel/params.gni:46
+From //public/gn/toolchain/clang.gni:14
 
-### opt_level
-* -1 means really unoptimized (-O0), usually only build-tested and not run.
-* 0 means "optimized for debugging" (-Og), light enough to avoid confusion.
-  1, 2, and 3 are increasing levels of optimization.
-* 4 is optimized for space rather than purely for speed.
+### enable_netsvc_debugging_features
 
-**Current value (from the default):** `2`
+**Current value (from the default):** `false`
 
-From //public/gn/config/levels.gni:15
+From //public/gn/config/product_parameters.gni:13
 
-### use_prebuilt_gcc
-If $gcc_tool_dir is "", then this controls how the GCC toolchain
-binaries are found.  If true, the standard prebuilt is used.  If false,
-the tools are just expected to be found in PATH.
+### enable_user_pci
+Enable userspace PCI and disable kernel PCI.
 
-**Current value (from the default):** `true`
+**Current value (from the default):** `false`
 
-From //public/gn/toolchain/gcc.gni:9
+From //kernel/params.gni:42
 
-### thinlto_jobs
-Number of parallel ThinLTO jobs.
+### target_os
 
-**Current value (from the default):** `8`
+**Current value (from the default):** `""`
 
-From //public/gn/config/lto/BUILD.gn:19
+### kernel_extra_defines
+Extra macro definitions for kernel code, e.g. "DISABLE_KASLR",
+"ENABLE_KERNEL_LL_DEBUG".
 
-### use_prebuilt_clang
-If $clang_tool_dir is "", then this controls how the Clang toolchain
-binaries are found.  If true, then the standard prebuilt is used.
-Otherwise the tools are just expected to be found by the shell via `PATH`.
+**Current value (from the default):** `[]`
 
-**Current value (from the default):** `true`
+From //kernel/params.gni:46
 
-From //public/gn/toolchain/clang.gni:9
+### malloc
+
+**Current value (from the default):** `"scudo"`
+
+From //third_party/ulib/musl/BUILD.gn:6
+
+### smp_max_cpus
+Maximum number of CPUs the kernel will run on (others will be ignored).
+
+**Current value (from the default):** `32`
+
+From //kernel/params.gni:7
 
 ### assert_level
 * 0 means no assertions, not even standard C `assert()`.
@@ -77,18 +136,35 @@ From //public/gn/toolchain/clang.gni:9
 
 From //public/gn/config/levels.gni:9
 
-### crash_diagnostics_dir
-Clang crash reports directory path. Use empty path to disable altogether.
+### enable_acpi_debug
+Enable debug output in the ACPI library (used by the ACPI bus driver).
 
-**Current value (from the default):** `"/b/s/w/ir/k/out/build-zircon/clang-crashreports"`
+**Current value (from the default):** `false`
 
-From //public/gn/config/BUILD.gn:11
+From //third_party/lib/acpica/BUILD.gn:9
 
-### target_cpu
+### enable_lock_dep
+Enable kernel lock dependency tracking.
 
-**Current value (from the default):** `""`
+**Current value (from the default):** `false`
 
-### target_os
+From //kernel/params.gni:32
+
+### host_os
+
+**Current value (from the default):** `"linux"`
+
+### opt_level
+* -1 means really unoptimized (-O0), usually only build-tested and not run.
+* 0 means "optimized for debugging" (-Og), light enough to avoid confusion.
+  1, 2, and 3 are increasing levels of optimization.
+* 4 is optimized for space rather than purely for speed.
+
+**Current value (from the default):** `2`
+
+From //public/gn/config/levels.gni:15
+
+### target_cpu
 
 **Current value (from the default):** `""`
 
@@ -102,12 +178,50 @@ to be pared down.
 
 From //BUILD.gn:16
 
-### thinlto_cache_dir
-ThinLTO cache directory path.
+### toolchain
+*This must never be set as a build argument.*
+It exists only to be set via c_toolchain().
+See environment() for more information.
+
+**Current value (from the default):**
+```
+{
+  configs = []
+  environment = "stub"
+  globals = { }
+  label = "//public/gn/toolchain:stub"
+}
+```
 
-**Current value (from the default):** `"user-arm64-thinlto/thinlto-cache"`
+From //public/gn/BUILDCONFIG.gn:20
 
-From //public/gn/config/lto/BUILD.gn:22
+### default_deps
+Defines the `//:default` target: what `ninja` with no arguments does.
+
+**Current value (from the default):** `[":build-tests", ":ids", ":images", ":tools"]`
+
+From //BUILD.gn:19
+
+### detailed_scheduler_tracing
+Enable detailed scheduler traces.
+
+**Current value (from the default):** `false`
+
+From //kernel/params.gni:39
+
+### enable_fair_scheduler
+Disable fair scheduler by default on all architectures.
+ZX-3959: Disable by default until E2E tests stabilize.
+
+**Current value (from the default):** `false`
+
+From //kernel/params.gni:36
+
+### kernel_base
+
+**Current value (from the default):** `"0xffffffff80100000"`
+
+From //kernel/params.gni:20
 
 ### variants
 List of "selectors" to request variant builds of certain targets.  Each
@@ -331,53 +445,18 @@ Variant scope parameters
 
 From //public/gn/toolchain/variants.gni:222
 
-### enable_user_pci
-Enable userspace PCI and disable kernel PCI.
-
-**Current value (from the default):** `false`
-
-From //kernel/params.gni:42
-
-### kernel_aspace_base
-
-**Current value (from the default):** `"0xffffff8000000000UL"`
-
-From //kernel/params.gni:28
-
-### kernel_version_string
-Version string embedded in the kernel for `zx_system_get_version`.
-If set to the default "", a string is generated based on the
-Zircon git revision of the checkout.
-
-**Current value (from the default):** `""`
-
-From //kernel/lib/version/BUILD.gn:9
-
-### build_id_dir
-Directory to populate with `xx/yyy` and `xx/yyy.debug` links to ELF
-files.  For every ELF binary built, with build ID `xxyyy` (lowercase
-hexadecimal of any length), `xx/yyy` is a hard link to the stripped
-file and `xx/yyy.debug` is a hard link to the unstripped file.
-Symbolization tools and debuggers find symbolic information this way.
-
-**Current value (from the default):** `"/b/s/w/ir/k/out/build-zircon/.build-id"`
-
-From //public/gn/toolchain/c_toolchain.gni:17
-
-### enable_fair_scheduler
-Disable fair scheduler by default on all architectures.
-ZX-3959: Disable by default until E2E tests stabilize.
-
-**Current value (from the default):** `false`
-
-From //kernel/params.gni:36
+### zx
+*This must never be set as a build argument*.
 
-### enable_lock_dep
-Enable kernel lock dependency tracking.
+"$zx/" is the prefix for GN "source-absolute" paths in the Zircon
+build.  When Zircon is built standalone, the Zircon repository is the
+root of the build (where `.gn` is found) so "$zx/" becomes "//".  When
+Zircon is part of a larger unified build, there is a higher-level `.gn`
+file that uses `default_args` to set "$zx/" to "//zircon/".
 
-**Current value (from the default):** `false`
+**Current value (from the default):** `"/"`
 
-From //kernel/params.gni:32
+From //public/gn/BUILDCONFIG.gn:13
 
 ### gcc_tool_dir
 Directory where the GCC toolchain binaries ("gcc", "nm", etc.) are
@@ -391,11 +470,32 @@ system-installed tools found by the shell via `PATH` will be used.
 
 From //public/gn/toolchain/gcc.gni:17
 
-### kernel_base
+### kernel_aspace_base
 
-**Current value (from the default):** `"0xffffffff80100000"`
+**Current value (from the default):** `"0xffffff8000000000UL"`
 
-From //kernel/params.gni:20
+From //kernel/params.gni:28
+
+### sysroot
+The `--sysroot` directory for host compilations.
+This can be a string, which only applies to $host_os-$host_cpu.
+Or it can be a list of scopes containing `cpu`, `os`, and `sysroot`.
+The empty list (or empty string) means don't use `--sysroot` at all.
+
+**Current value (from the default):**
+```
+[{
+  cpu = "arm64"
+  os = "linux"
+  sysroot = "//prebuilt/downloads/sysroot/linux-arm64"
+}, {
+  cpu = "x64"
+  os = "linux"
+  sysroot = "//prebuilt/downloads/sysroot/linux-x64"
+}]
+```
+
+From //public/gn/config/BUILD.gn:17
 
 ### use_ccache
 Set to true to enable compiling with ccache.
@@ -411,25 +511,21 @@ Set to true to enable distributed compilation using Goma.
 
 From //public/gn/toolchain/goma.gni:9
 
-### zx
-*This must never be set as a build argument*.
-
-"$zx/" is the prefix for GN "source-absolute" paths in the Zircon
-build.  When Zircon is built standalone, the Zircon repository is the
-root of the build (where `.gn` is found) so "$zx/" becomes "//".  When
-Zircon is part of a larger unified build, there is a higher-level `.gn`
-file that uses `default_args` to set "$zx/" to "//zircon/".
+### use_prebuilt_clang
+If $clang_tool_dir is "", then this controls how the Clang toolchain
+binaries are found.  If true, then the standard prebuilt is used.
+Otherwise the tools are just expected to be found by the shell via `PATH`.
 
-**Current value (from the default):** `"/"`
+**Current value (from the default):** `true`
 
-From //public/gn/BUILDCONFIG.gn:13
+From //public/gn/toolchain/clang.gni:9
 
-### detailed_scheduler_tracing
-Enable detailed scheduler traces.
+### crash_diagnostics_dir
+Clang crash reports directory path. Use empty path to disable altogether.
 
-**Current value (from the default):** `false`
+**Current value (from the default):** `"/b/s/w/ir/k/out/build-zircon/clang-crashreports"`
 
-From //kernel/params.gni:39
+From //public/gn/config/BUILD.gn:11
 
 ### enable_lock_dep_tests
 Enable kernel lock dependency tracking tests.  By default this is
@@ -441,12 +537,6 @@ disabled.
 
 From //kernel/params.gni:54
 
-### enable_netsvc_debugging_features
-
-**Current value (from the default):** `false`
-
-From //public/gn/config/product_parameters.gni:13
-
 ### goma_dir
 Absolute directory containing the Goma source code.
 
@@ -454,100 +544,10 @@ Absolute directory containing the Goma source code.
 
 From //public/gn/toolchain/goma.gni:12
 
-### smp_max_cpus
-Maximum number of CPUs the kernel will run on (others will be ignored).
-
-**Current value (from the default):** `32`
-
-From //kernel/params.gni:7
-
-### toolchain
-*This must never be set as a build argument.*
-It exists only to be set via c_toolchain().
-See environment() for more information.
-
-**Current value (from the default):**
-```
-{
-  configs = []
-  environment = "stub"
-  globals = { }
-  label = "//public/gn/toolchain:stub"
-}
-```
-
-From //public/gn/BUILDCONFIG.gn:20
-
-### asan_default_options
-Default [AddressSanitizer](https://llvm.org/docs/AddressSanitizer.html)
-options (before the `ASAN_OPTIONS` environment variable is read at
-runtime).  This can be set as a build argument to affect most "asan"
-variants in $variants (which see), or overridden in $toolchain_args in
-one of those variants.  Note that setting this nonempty may conflict
-with programs that define their own `__asan_default_options` C
-function.
-
-**Current value (from the default):** `""`
-
-From //public/gn/config/instrumentation/BUILD.gn:15
-
-### host_os
-
-**Current value (from the default):** `"linux"`
-
-### sysroot
-The `--sysroot` directory for host compilations.
-This can be a string, which only applies to $host_os-$host_cpu.
-Or it can be a list of scopes containing `cpu`, `os`, and `sysroot`.
-The empty list (or empty string) means don't use `--sysroot` at all.
-
-**Current value (from the default):**
-```
-[{
-  cpu = "arm64"
-  os = "linux"
-  sysroot = "//prebuilt/downloads/sysroot/linux-arm64"
-}, {
-  cpu = "x64"
-  os = "linux"
-  sysroot = "//prebuilt/downloads/sysroot/linux-x64"
-}]
-```
-
-From //public/gn/config/BUILD.gn:17
-
-### clang_tool_dir
-Directory where the Clang toolchain binaries ("clang", "llvm-nm", etc.) are
-found.  If this is "", then the behavior depends on $use_prebuilt_clang.
-This toolchain is expected to support both Fuchsia targets and the host.
-
-**Current value (from the default):** `""`
-
-From //public/gn/toolchain/clang.gni:14
-
-### current_cpu
-
-**Current value (from the default):** `""`
-
-### default_deps
-Defines the `//:default` target: what `ninja` with no arguments does.
-
-**Current value (from the default):** `[":build-tests", ":ids", ":images", ":tools"]`
-
-From //BUILD.gn:19
-
-### malloc
-
-**Current value (from the default):** `"scudo"`
-
-From //third_party/ulib/musl/BUILD.gn:6
-
-### symbol_level
-* 0 means no debugging information.
-* 1 means minimal debugging information sufficient to symbolize backtraces.
-* 2 means full debugging information for use with a symbolic debugger.
+### thinlto_jobs
+Number of parallel ThinLTO jobs.
 
-**Current value (from the default):** `2`
+**Current value (from the default):** `8`
 
-From //public/gn/config/levels.gni:20
+From //public/gn/config/lto/BUILD.gn:19