[gndoc] Update GN build arguments documentation

Test: CQ

Change-Id: I0b8a33851af712c41c0bcf84d05a150a29e99730

zircon/docs/gen/build_arguments.md

@@ -2,23 +2,39 @@
 
 ## All builds
 
-### assert_level
-* 0 means no assertions, not even standard C `assert()`.
-* 1 means `ZX_ASSERT` but not `ZX_DEBUG_ASSERT`.
-* 2 means both `ZX_ASSERT` and  `ZX_DEBUG_ASSERT`.
+### use_goma
+Set to true to enable distributed compilation using Goma.
 
-**Current value (from the default):** `2`
+**Current value (from the default):** `false`
 
-From //public/gn/config/levels.gni:9
+From //public/gn/toolchain/goma.gni:9
 
-### 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.
+### 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):** `""`
+**Current value (from the default):** `true`
 
-From //kernel/lib/version/BUILD.gn:9
+From //public/gn/toolchain/gcc.gni:9
+
+### enable_kernel_debugging_features
+Whether to include various features (non-shipping, insecure, etc.) in the
+kernel or netsvc builds.
+
+**Current value (from the default):** `false`
+
+From //public/gn/config/product_parameters.gni:12
+
+### 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
 
 ### thinlto_jobs
 Number of parallel ThinLTO jobs.
@@ -27,40 +43,34 @@ Number of parallel ThinLTO jobs.
 
 From //public/gn/config/lto/BUILD.gn:19
 
-### 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/".
-
-**Current value (from the default):** `"/"`
+### use_ccache
+Set to true to enable compiling with ccache.
 
-From //public/gn/BUILDCONFIG.gn:13
+**Current value (from the default):** `false`
 
-### detailed_scheduler_tracing
-Enable detailed scheduler traces.
+From //public/gn/toolchain/ccache.gni:9
 
-**Current value (from the default):** `false`
+### host_os
 
-From //kernel/params.gni:39
+**Current value (from the default):** `"linux"`
 
-### enable_acpi_debug
-Enable debug output in the ACPI library (used by the ACPI bus driver).
+### kernel_extra_defines
+Extra macro definitions for kernel code, e.g. "DISABLE_KASLR",
+"ENABLE_KERNEL_LL_DEBUG".
 
-**Current value (from the default):** `false`
+**Current value (from the default):** `[]`
 
-From //third_party/lib/acpica/BUILD.gn:9
+From //kernel/params.gni:46
 
-### enable_fair_scheduler
-Disable fair scheduler by default on all architectures.
-ZX-3959: Disable by default until E2E tests stabilize.
+### tests_in_image
+Whether to include all the Zircon tests in the main standalone ZBI.
+TODO(mcgrathr): This will be replaced by a more sophisticated plan for
+what images to build rather than a single "everything" image that needs
+to be pared down.
 
-**Current value (from the default):** `false`
+**Current value (from the default):** `true`
 
-From //kernel/params.gni:36
+From //BUILD.gn:16
 
 ### use_prebuilt_clang
 If $clang_tool_dir is "", then this controls how the Clang toolchain
@@ -71,14 +81,83 @@ Otherwise the tools are just expected to be found by the shell via `PATH`.
 
 From //public/gn/toolchain/clang.gni:9
 
-### 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.
+### 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_lock_dep_tests
+Enable kernel lock dependency tracking tests.  By default this is
+enabled when tracking is enabled, but can also be eanbled independently
+to assess whether the tests build and *fail correctly* when lockdep is
+disabled.
+
+**Current value (from the default):** `false`
+
+From //kernel/params.gni:54
+
+### 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
+
+### 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
+
+### assert_level
+* 0 means no assertions, not even standard C `assert()`.
+* 1 means `ZX_ASSERT` but not `ZX_DEBUG_ASSERT`.
+* 2 means both `ZX_ASSERT` and  `ZX_DEBUG_ASSERT`.
 
 **Current value (from the default):** `2`
 
-From //public/gn/config/levels.gni:20
+From //public/gn/config/levels.gni:9
+
+### enable_acpi_debug
+Enable debug output in the ACPI library (used by the ACPI bus driver).
+
+**Current value (from the default):** `false`
+
+From //third_party/lib/acpica/BUILD.gn:9
+
+### goma_dir
+Absolute directory containing the Goma source code.
+
+**Current value (from the default):** `"/home/swarming/goma"`
+
+From //public/gn/toolchain/goma.gni:12
+
+### target_os
+
+**Current value (from the default):** `""`
+
+### malloc
+
+**Current value (from the default):** `"scudo"`
+
+From //third_party/ulib/musl/BUILD.gn:6
 
 ### asan_default_options
 Default [AddressSanitizer](https://llvm.org/docs/AddressSanitizer.html)
@@ -93,52 +172,42 @@ function.
 
 From //public/gn/config/instrumentation/BUILD.gn:15
 
-### enable_kernel_debugging_features
-Whether to include various features (non-shipping, insecure, etc.) in the
-kernel or netsvc builds.
+### 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):** `false`
+**Current value (from the default):** `""`
 
-From //public/gn/config/product_parameters.gni:12
+From //public/gn/toolchain/clang.gni:14
 
-### enable_lock_dep
-Enable kernel lock dependency tracking.
+### default_deps
+Defines the `//:default` target: what `ninja` with no arguments does.
 
-**Current value (from the default):** `false`
+**Current value (from the default):** `[":build-tests", ":ids", ":images", ":tools"]`
 
-From //kernel/params.gni:32
+From //BUILD.gn:19
 
-### 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.
+### kernel_aspace_base
 
-**Current value (from the default):** `2`
+**Current value (from the default):** `"0xffffff8000000000UL"`
 
-From //public/gn/config/levels.gni:15
+From //kernel/params.gni:28
 
-### target_os
+### current_cpu
 
 **Current value (from the default):** `""`
 
-### use_ccache
-Set to true to enable compiling with ccache.
-
-**Current value (from the default):** `false`
-
-From //public/gn/toolchain/ccache.gni:9
-
-### current_cpu
+### current_os
 
 **Current value (from the default):** `""`
 
-### enable_user_pci
-Enable userspace PCI and disable kernel PCI.
+### enable_lock_dep
+Enable kernel lock dependency tracking.
 
 **Current value (from the default):** `false`
 
-From //kernel/params.gni:42
+From //kernel/params.gni:32
 
 ### gcc_tool_dir
 Directory where the GCC toolchain binaries ("gcc", "nm", etc.) are
@@ -152,57 +221,62 @@ system-installed tools found by the shell via `PATH` will be used.
 
 From //public/gn/toolchain/gcc.gni:17
 
-### malloc
+### 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.
 
-**Current value (from the default):** `"scudo"`
+**Current value (from the default):** `2`
 
-From //third_party/ulib/musl/BUILD.gn:6
+From //public/gn/config/levels.gni:20
 
-### tests_in_image
-Whether to include all the Zircon tests in the main standalone ZBI.
-TODO(mcgrathr): This will be replaced by a more sophisticated plan for
-what images to build rather than a single "everything" image that needs
-to be pared down.
+### zx
+*This must never be set as a build argument*.
 
-**Current value (from the default):** `true`
+"$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/".
 
-From //BUILD.gn:16
+**Current value (from the default):** `"/"`
 
-### toolchain
-*This must never be set as a build argument.*
-It exists only to be set via c_toolchain().
-See environment() for more information.
+From //public/gn/BUILDCONFIG.gn:13
 
-**Current value (from the default):**
-```
-{
-  configs = []
-  environment = "stub"
-  globals = { }
-  label = "//public/gn/toolchain:stub"
-}
-```
+### crash_diagnostics_dir
+Clang crash reports directory path. Use empty path to disable altogether.
 
-From //public/gn/BUILDCONFIG.gn:20
+**Current value (from the default):** `"/b/s/w/ir/k/out/build-zircon/clang-crashreports"`
 
-### current_os
+From //public/gn/config/BUILD.gn:11
 
-**Current value (from the default):** `""`
+### enable_netsvc_debugging_features
 
-### default_deps
-Defines the `//:default` target: what `ninja` with no arguments does.
+**Current value (from the default):** `false`
 
-**Current value (from the default):** `[":build-tests", ":ids", ":images", ":tools"]`
+From //public/gn/config/product_parameters.gni:13
 
-From //BUILD.gn:19
+### kernel_base
 
-### kernel_extra_defines
-Extra macro definitions for kernel code, e.g. "DISABLE_KASLR",
-"ENABLE_KERNEL_LL_DEBUG".
+**Current value (from the default):** `"0xffffffff80100000"`
 
-**Current value (from the default):** `[]`
+From //kernel/params.gni:20
 
-From //kernel/params.gni:46
+### 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
+
+### 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
 
 ### sysroot
 The `--sysroot` directory for host compilations.
@@ -225,85 +299,9 @@ The empty list (or empty string) means don't use `--sysroot` at all.
 
 From //public/gn/config/BUILD.gn:17
 
-### thinlto_cache_dir
-ThinLTO cache directory path.
-
-**Current value (from the default):** `"user-x64-thinlto/thinlto-cache"`
-
-From //public/gn/config/lto/BUILD.gn:22
-
-### 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
-
-### 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_lock_dep_tests
-Enable kernel lock dependency tracking tests.  By default this is
-enabled when tracking is enabled, but can also be eanbled independently
-to assess whether the tests build and *fail correctly* when lockdep is
-disabled.
-
-**Current value (from the default):** `false`
-
-From //kernel/params.gni:54
-
-### enable_netsvc_debugging_features
-
-**Current value (from the default):** `false`
-
-From //public/gn/config/product_parameters.gni:13
-
-### host_os
-
-**Current value (from the default):** `"linux"`
-
-### use_goma
-Set to true to enable distributed compilation using Goma.
-
-**Current value (from the default):** `false`
-
-From //public/gn/toolchain/goma.gni:9
-
-### crash_diagnostics_dir
-Clang crash reports directory path. Use empty path to disable altogether.
-
-**Current value (from the default):** `"/b/s/w/ir/k/out/build-zircon/clang-crashreports"`
-
-From //public/gn/config/BUILD.gn:11
-
-### goma_dir
-Absolute directory containing the Goma source code.
-
-**Current value (from the default):** `"/home/swarming/goma"`
-
-From //public/gn/toolchain/goma.gni:12
-
-### kernel_aspace_base
-
-**Current value (from the default):** `"0xffffff8000000000UL"`
-
-From //kernel/params.gni:28
-
-### kernel_base
-
-**Current value (from the default):** `"0xffffffff80100000"`
+### target_cpu
 
-From //kernel/params.gni:20
+**Current value (from the default):** `""`
 
 ### variants
 List of "selectors" to request variant builds of certain targets.  Each
@@ -527,27 +525,29 @@ Variant scope parameters
 
 From //public/gn/toolchain/variants.gni:222
 
-### 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.
+### detailed_scheduler_tracing
+Enable detailed scheduler traces.
 
-**Current value (from the default):** `""`
+**Current value (from the default):** `false`
 
-From //public/gn/toolchain/clang.gni:14
+From //kernel/params.gni:39
 
-### host_cpu
+### 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):** `"x64"`
+**Current value (from the default):** `false`
 
-### smp_max_cpus
-Maximum number of CPUs the kernel will run on (others will be ignored).
+From //kernel/params.gni:36
 
-**Current value (from the default):** `32`
+### enable_user_pci
+Enable userspace PCI and disable kernel PCI.
 
-From //kernel/params.gni:7
+**Current value (from the default):** `false`
 
-### target_cpu
+From //kernel/params.gni:42
 
-**Current value (from the default):** `""`
+### host_cpu
+
+**Current value (from the default):** `"x64"`