[gndoc] Update GN build arguments documentation

Test: CQ Change-Id: Iec3c3e3c83bab280fc73ca4c5d2e87305d1a1666

[gndoc] Update GN build arguments documentation
Test: CQ Change-Id: Iec3c3e3c83bab280fc73ca4c5d2e87305d1a1666
341bc253 · docs-roller · 15160334 · 341bc253 · 341bc253
Commit 341bc253 authored 5 years ago by docs-roller
--- a/docs/gen/build_arguments.md
+++ b/docs/gen/build_arguments.md
--- a/zircon/docs/gen/build_arguments.md
+++ b/zircon/docs/gen/build_arguments.md
@@ -2,22 +2,30 @@

 ## All builds

-### enable_kernel_debugging_features
-Whether to include various features (non-shipping, insecure, etc.) in the
-kernel or netsvc 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`.

-**Current value (from the default):** `false`
+**Current value (from the default):** `2`

-From //public/gn/config/product_parameters.gni:12
+From //public/gn/config/levels.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.
+### 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):** `2`
+**Current value (from the default):** `""`

-From //public/gn/config/levels.gni:20
+From //kernel/lib/version/BUILD.gn:9
+
+### thinlto_jobs
+Number of parallel ThinLTO jobs.
+
+**Current value (from the default):** `8`
+
+From //public/gn/config/lto/BUILD.gn:19

 ### zx
 *This must never be set as a build argument*.
@@ -32,42 +40,27 @@ file that uses `default_args` to set "$zx/" to "//zircon/".

 From //public/gn/BUILDCONFIG.gn:13

-### enable_acpi_debug
-Enable debug output in the ACPI library (used by the ACPI bus driver).
+### detailed_scheduler_tracing
+Enable detailed scheduler traces.

 **Current value (from the default):** `false`

-From //third_party/lib/acpica/BUILD.gn:9
-
-### 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
-
-### host_os
-
-**Current value (from the default):** `"linux"`
+From //kernel/params.gni:39

-### 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.
+### enable_acpi_debug
+Enable debug output in the ACPI library (used by the ACPI bus driver).

-**Current value (from the default):** `""`
+**Current value (from the default):** `false`

-From //kernel/lib/version/BUILD.gn:9
+From //third_party/lib/acpica/BUILD.gn:9

-### 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_fair_scheduler
+Disable fair scheduler by default on all architectures.
+ZX-3959: Disable by default until E2E tests stabilize.

-**Current value (from the default):** `2`
+**Current value (from the default):** `false`

-From //public/gn/config/levels.gni:15
+From //kernel/params.gni:36

 ### use_prebuilt_clang
 If $clang_tool_dir is "", then this controls how the Clang toolchain
@@ -78,56 +71,56 @@ Otherwise the tools are just expected to be found by the shell via `PATH`.

 From //public/gn/toolchain/clang.gni: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
-
-### crash_diagnostics_dir
-Clang crash reports directory path. Use empty path to disable altogether.
+### 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):** `"/b/s/w/ir/k/out/build-zircon/clang-crashreports"`
+**Current value (from the default):** `2`

-From //public/gn/config/BUILD.gn:11
+From //public/gn/config/levels.gni:20

-### 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.
+### 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/toolchain/clang.gni:14
+From //public/gn/config/instrumentation/BUILD.gn:15

-### detailed_scheduler_tracing
-Enable detailed scheduler traces.
+### 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 //kernel/params.gni:39
-
-### goma_dir
-Absolute directory containing the Goma source code.
+From //public/gn/config/product_parameters.gni:12

-**Current value (from the default):** `"/home/swarming/goma"`
+### enable_lock_dep
+Enable kernel lock dependency tracking.

-From //public/gn/toolchain/goma.gni:12
+**Current value (from the default):** `false`

-### kernel_base
+From //kernel/params.gni:32

-**Current value (from the default):** `"0xffffffff00000000"`
+### 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.

-From //kernel/params.gni:18
+**Current value (from the default):** `2`

-### malloc
+From //public/gn/config/levels.gni:15

-**Current value (from the default):** `"scudo"`
+### target_os

-From //third_party/ulib/musl/BUILD.gn:6
+**Current value (from the default):** `""`

 ### use_ccache
 Set to true to enable compiling with ccache.
@@ -136,28 +129,10 @@ Set to true to enable compiling with ccache.

 From //public/gn/toolchain/ccache.gni:9

-### 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_cpu

 **Current value (from the default):** `""`

-From //public/gn/config/instrumentation/BUILD.gn:15
-
-### 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:9
-
 ### enable_user_pci
 Enable userspace PCI and disable kernel PCI.

@@ -165,21 +140,33 @@ Enable userspace PCI and disable kernel PCI.

 From //kernel/params.gni:42

-### kernel_aspace_base
+### gcc_tool_dir
+Directory where the GCC toolchain binaries ("gcc", "nm", etc.) are
+found.  If this is "", then the behavior depends on $use_prebuilt_gcc.
+This directory is expected to contain `aarch64-elf-*` and `x86_64-elf-*`
+tools used to build for the Fuchsia targets.  This directory will not
+be used for host tools; if GCC is selected for host builds, only the
+system-installed tools found by the shell via `PATH` will be used.

-**Current value (from the default):** `"0xffff000000000000"`
+**Current value (from the default):** `""`

-From //kernel/params.gni:26
+From //public/gn/toolchain/gcc.gni:17

-### smp_max_cpus
+### malloc
+
+**Current value (from the default):** `"scudo"`

-**Current value (from the default):** `16`
+From //third_party/ulib/musl/BUILD.gn:6

-From //kernel/params.gni:10
+### 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.

-### target_cpu
+**Current value (from the default):** `true`

-**Current value (from the default):** `""`
+From //BUILD.gn:16

 ### toolchain
 *This must never be set as a build argument.*
@@ -198,60 +185,16 @@ See environment() for more information.

 From //public/gn/BUILDCONFIG.gn:20

-### use_goma
-Set to true to enable distributed compilation using Goma.
-
-**Current value (from the default):** `false`
-
-From //public/gn/toolchain/goma.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_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
-
-### 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
-
-### target_os
+### current_os

 **Current value (from the default):** `""`

-### thinlto_cache_dir
-ThinLTO cache directory path.
-
-**Current value (from the default):** `"host-arm64-linux-lto/thinlto-cache"`
-
-From //public/gn/config/lto/BUILD.gn:22
-
-### current_cpu
-
-**Current value (from the default):** `""`
+### default_deps
+Defines the `//:default` target: what `ninja` with no arguments does.

-### host_cpu
+**Current value (from the default):** `[":build-tests", ":ids", ":images", ":tools"]`

-**Current value (from the default):** `"x64"`
+From //BUILD.gn:19

 ### kernel_extra_defines
 Extra macro definitions for kernel code, e.g. "DISABLE_KASLR",
@@ -282,26 +225,42 @@ The empty list (or empty string) means don't use `--sysroot` at all.

 From //public/gn/config/BUILD.gn:17

-### 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.
+### 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 //BUILD.gn:16
+From //public/gn/toolchain/gcc.gni:9

-### thinlto_jobs
-Number of parallel ThinLTO jobs.
+### 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):** `8`
+**Current value (from the default):** `"/b/s/w/ir/k/out/build-zircon/.build-id"`

-From //public/gn/config/lto/BUILD.gn:19
+From //public/gn/toolchain/c_toolchain.gni:17

-### current_os
+### 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):** `""`
+**Current value (from the default):** `false`
+
+From //kernel/params.gni:54

 ### enable_netsvc_debugging_features

@@ -309,17 +268,42 @@ From //public/gn/config/lto/BUILD.gn:19

 From //public/gn/config/product_parameters.gni:13

-### gcc_tool_dir
-Directory where the GCC toolchain binaries ("gcc", "nm", etc.) are
-found.  If this is "", then the behavior depends on $use_prebuilt_gcc.
-This directory is expected to contain `aarch64-elf-*` and `x86_64-elf-*`
-tools used to build for the Fuchsia targets.  This directory will not
-be used for host tools; if GCC is selected for host builds, only the
-system-installed tools found by the shell via `PATH` will be used.
+### host_os

-**Current value (from the default):** `""`
+**Current value (from the default):** `"linux"`

-From //public/gn/toolchain/gcc.gni:17
+### 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"`
+
+From //kernel/params.gni:20

 ### variants
 List of "selectors" to request variant builds of certain targets.  Each
@@ -543,10 +527,27 @@ Variant scope parameters

 From //public/gn/toolchain/variants.gni:222

-### enable_lock_dep
-Enable kernel lock dependency tracking.
+### 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 //kernel/params.gni:32
+From //public/gn/toolchain/clang.gni:14
+
+### host_cpu
+
+**Current value (from the default):** `"x64"`
+
+### 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
+
+### target_cpu
+
+**Current value (from the default):** `""`