docs/gen/zircon_build_arguments.md

# GN Build Arguments

## All builds

### asan_default_options
Default [AddressSanitizer](https://clang.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

### assert_level
Controls which asserts are enabled.

`ZX_ASSERT` is always enabled.

* 0 disables standard C `assert()` and `ZX_DEBUG_ASSERT`.
* 1 disables `ZX_DEBUG_ASSERT`. Standard C `assert()` remains enabled.
* 2 enables all asserts.

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

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

### 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/root_build_dir.zircon/.build-id"`

From //public/gn/toolchain/c_toolchain.gni:18

### 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:16

### crash_diagnostics_dir
Clang crash reports directory path. Use empty path to disable altogether.

**Current value (from the default):** `"/b/s/w/ir/k/root_build_dir.zircon/clang-crashreports"`

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

### current_cpu

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

### current_os

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

### default_deps
Defines the `//:default` target: what `ninja` with no arguments does.
TODO(BLD-353): This must be set by the controlling Fuchsia GN build.

**Current value for `target_cpu = `:** `["//:legacy-x64", "//:legacy_host_targets-linux-x64", "//:legacy_unification-x64", "//tools:all-hosts"]`

From /b/s/w/ir/k/root_build_dir.zircon/args.gn:5

**Overridden from the default:** `false`

From //BUILD.gn:17

### driver_unittest_log_flags
Log levels to be printed when logs are enabled. Default is ERROR, WARNING, & INFO.
Refer to zircon/system/public/zircon/syscalls/log.h for levels.

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

From //system/dev/lib/fake_ddk/BUILD.gn:11

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

### enable_driver_unittest_logs
Enable printing of in driver logs in unittests.

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

From //system/dev/lib/fake_ddk/BUILD.gn:7

### enable_lock_dep
Enable kernel lock dependency tracking.

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

From //kernel/params.gni:26

### 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:62

### enable_netsvc_debugging_features
Whether to include various features (non-shipping, insecure, etc.) in the
netsvc build.

**Current value for `target_cpu = `:** `false`

From /b/s/w/ir/k/root_build_dir.zircon/args.gn:11

**Overridden from the default:** `false`

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

### enable_user_pci
Enable userspace PCI and disable kernel PCI.

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

From //kernel/params.gni:42

### environment_args
List of clauses to apply other GN build arguments to specific compilation
environments.  Each clause specifies matching criteria and arguments to
set in such environments.  Each matching clause is applied in order; each
argument it sets overrides any setting of that same argument in an earlier
matching clause or in the environment() declaration.  Note that if the
variant selected for a target via [`variants`](#variants) (which see) has
a `toolchain_args` setting, each argument therein will override the
settings here in `environment_args` clauses (within that variant
toolchain).

Each clause is a scope.  The several parameters listed below are the
matching criteria.  All other parameters in a clause are the build
arguments set when that clause matches.  Note that these form a subset of
the matching criteria supported by [`variants`](#variants) selectors,
except for `tags` and `exclude_tags`.  The semantics of each criterion are
exactly the same here and there.

For example:
```
  environment_args = [ { kernel = true assert_level = 0 } ]
```
sets `assert_level = 0` everywhere where `is_kernel == true`, while:
```
  environment_args = [
    {
      kernel = false
      assert_level = 0
    },
    {
      kernel = true
      assert_level = 1
    },
    {
      environment = [ "efi" ]
      assert_level = 2
      opt_level = 0
    },
  ]
```
sets `assert_level = 0` everywhere where `is_kernel == false`,
sets `assert_level = 1` most places where `is_kernel == true`,
but sets `assert_level = 2` and `opt_level = 0` in the "efi"
environment (where `is_kernel == true` also holds, but the later
clause overrides the preceding `assert_level = 1`).

Clause scope parameters

  * cpu
    - Optional: If nonempty, match only when $current_cpu is one in the
    - list.
    - Type: list(string)

  * os
    - Optional: If nonempty, match only when $current_os is one in the
    - list.
    - Type: list(string)

  * host
    - Optional: If present, match only in host environments if true or
    non-host environments if false.  This means a context in which
    $is_host is true, not specifically the build host.  For example, it
    would be true when cross-compiling host tools for an SDK build but
    would be false when compiling code for a hypervisor guest system
    that happens to be the same CPU and OS as the build host.
    - Type: bool

  * kernel
    - Optional: If present, match only in kernel environments if true or
    non-kernel environments if false.  This means a context in which
    $is_kernel is true, not just the "kernel" environment itself.
    For different machine architectures there may be multiple different
    specialized environments that set $is_kernel, e.g. for boot loaders
    and for special circumstances used within the kernel.  See also the
    $tags field in $variant, described below.
    - Type: bool

  * environment
    - Optional: If nonempty, a list of environment names that match.  This
    looks at ${toolchain.environment}, which is the simple name (no
    directories) in an environment label defined by environment().  Each
    element can match either the whole environment name, or just the
    "base" environment, which is the part of the name before a `.` if it
    has one.  For example, "host" would match both "host" and "host.fuzz".
    - Type: list(string)

  * tags
    - Optional: If nonempty, a list of tags which must be present in the
    `tags` parameter to environment() for that environment to match.
    - Type: list(string)
    - Default: []

  * exclude_tags
    - Optional: If nonempty, a list of tags which must *not* be present in
    the `tags` parameter to environment() for that environment to match.
    - Type: list(string)
    - Default: []


**Current value (from the default):** `[]`

From //public/gn/toolchain/environment.gni:108

### exclude_testonly_syscalls
If true, excludes syscalls with the [testonly] attribute.

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

From //vdso/BUILD.gn:10

### fidl_write_v1_wireformat

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

From //system/ulib/fidl/BUILD.gn:6

### fidlc_deprecate_c_unions

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

From //tools/fidl/BUILD.gn:7

### fidlc_union_not_simple

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

From //tools/fidl/BUILD.gn:6

### 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):** `""`

From //public/gn/toolchain/gcc.gni:19

### goma_dir
Directory containing the Goma source code.  This can be a GN
source-absolute path ("//...") or a system absolute path.

**Current value for `target_cpu = `:** `"/home/swarming/goma"`

From /b/s/w/ir/k/root_build_dir.zircon/args.gn:12

**Overridden from the default:** `"/home/swarming/goma"`

From //public/gn/toolchain/goma.gni:13

### host_cpu

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

### host_os

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

### kernel_base

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

From //kernel/params.gni:20

### kernel_debug_level
Enables various kernel debugging and diagnostic features.  Valid
values are between 0-3.  The higher the value, the more that are
enabled.  A value of 0 disables all of them.

TODO(41790): This value is derived from assert_level.  Decouple
the two and set kernel_debug_level independently.

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

From //kernel/params.gni:54

### kernel_extra_defines
Extra macro definitions for kernel code, e.g. "DISABLE_KASLR",
"ENABLE_KERNEL_LL_DEBUG".

**Current value (from the default):** `[]`

From //kernel/params.gni:46

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

### malloc

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

From //third_party/ulib/musl/BUILD.gn:6

### 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:19

### output_breakpad_syms
"$output_breakpad_syms" gates whether or not breakpad symbols are produced.

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

From //public/gn/config/standard.gni:9

### scheduler_tracing_level
The level of detail for scheduler traces when enabled. Values greater than
zero add increasing details at the cost of increased trace buffer use.

0 = Default kernel:sched tracing.
1 = Adds duration traces for key scheduler operations.
2 = Adds flow events from wakeup to running state.
3 = Adds detailed internal durations and probes.

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

From //kernel/params.gni:39

### select_scheduler
Select an available scheduler.
Valid values are: "legacy", "fair", "unified"

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

From //kernel/params.gni:30

### smp_max_cpus

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

From //kernel/params.gni:12

### 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):** `2`

From //public/gn/config/levels.gni:24

### 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/third_party/sysroot/linux"
}, {
  cpu = "x64"
  os = "linux"
  sysroot = "//../prebuilt/third_party/sysroot/linux"
}]
```

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

### target_cpu

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

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

### thinlto_jobs
Number of parallel ThinLTO jobs.

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

From //public/gn/config/lto/BUILD.gn:19

### 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:24

### ubsan_default_options
Default [UndefinedBehaviorSanitizer](https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html)
options (before the `UBSAN_OPTIONS` environment variable is read at
runtime).  This can be set as a build argument to affect most "ubsan"
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 `__ubsan_default_options` C
function.

**Current value (from the default):** `"print_stacktrace=1:halt_on_error=1"`

From //public/gn/config/instrumentation/BUILD.gn:29

### use_ccache
Set to true to enable compiling with ccache.

**Current value for `target_cpu = `:** `false`

From /b/s/w/ir/k/root_build_dir.zircon/args.gn:13

**Overridden from the default:** `false`

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

### use_goma
Set to true to enable distributed compilation using Goma.

**Current value for `target_cpu = `:** `false`

From /b/s/w/ir/k/root_build_dir.zircon/args.gn:14

**Overridden from the default:** `false`

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

### 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):** `true`

From //public/gn/toolchain/clang.gni:11

### 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:11

### variants
List of "selectors" to request variant builds of certain targets.  Each
selector specifies matching criteria and a chosen variant.  The first
selector in the list to match a given target determines which variant is
used for that target.

The $default_variants list is appended to the list set here.  So if no
selector set in $variants matches (e.g. if the list is empty, as is the
default), then the first match in $default_variants chooses the variant.

Each selector is either a string or a scope.  A selector that's a string
is a shorthand that gets expanded to a full selector (a scope); the full
selector form is described below.

If a string selector contains a slash, then it's "shorthand/filename".
This is like the plain "shorthand" selector, but further constrained to
apply only to a binary whose `output_name` exactly matches "filename".

The "shorthand" string (a whole string selector or the part before slash)
is first looked up in $variant_shorthands, which see.  If it doesn't match
a name defined there, then it must be the name of a variant.  In that case,
it's equivalent to `{ variant = "..." host = false }`, meaning it applies
to every binary not built to be a host tool.

A full selector is a scope with the following fields.  All the fields
other than `.variant` are matching criteria.  A selector matches if all of
its matching criteria match.  Hence, a selector with no criteria defined
always matches and is referred to as a "catch-all".  The $default_variants
list ends with a catch-all, so each target always chooses some variant.

Selector scope parameters

  * variant
    - Required: The variant to use when this selector matches.  If this
    is a string then it must match a fully-defined variant elsewhere in
    the list (or in $default_variants + $standard_variants, which is
    appended implicitly to the $variants list).  If it's a scope then
    it defines a new variant (see details below).
    - Type: string or scope, described below

  * cpu
    - Optional: If nonempty, match only when $current_cpu is one in the
    - list.
    - Type: list(string)

  * os
    - Optional: If nonempty, match only when $current_os is one in the
    - list.
    - Type: list(string)

  * host
    - Optional: If present, match only in host environments if true or
    non-host environments if false.  This means a context in which
    $is_host is true, not specifically the build host.  For example, it
    would be true when cross-compiling host tools for an SDK build but
    would be false when compiling code for a hypervisor guest system
    that happens to be the same CPU and OS as the build host.
    - Type: bool

  * kernel
    - Optional: If present, match only in kernel environments if true or
    non-kernel environments if false.  This means a context in which
    $is_kernel is true, not just the "kernel" environment itself.
    For different machine architectures there may be multiple different
    specialized environments that set $is_kernel, e.g. for boot loaders
    and for special circumstances used within the kernel.  See also the
    $tags field in $variant, described below.
    - Type: bool

  * environment
    - Optional: If nonempty, a list of environment names that match.  This
    looks at ${toolchain.environment}, which is the simple name (no
    directories) in an environment label defined by environment().  Each
    element can match either the whole environment name, or just the
    "base" environment, which is the part of the name before a `.` if it
    has one.  For example, "host" would match both "host" and "host.fuzz".
    - Type: list(string)

  * target_type
    - Optional: If nonempty, a list of target types to match.  This is
    one of "executable", "host_tool", "loadable_module", "driver", or
    "test".
    Note, test_driver() matches as "driver".
    - Type: list(string)

  * label
    - Optional: If nonempty, match only when the canonicalized target label
    (as returned by `get_label_info(..., "label_no_toolchain")`) is one in
    the list.
    - Type: list(label_no_toolchain)

  * dir
    - Optional: If nonempty, match only when the directory part of the
    target label (as returned by `get_label_info(..., "dir")`) is one in
    the list.
    - Type: list(label_no_toolchain)

  * name
    - Optional: If nonempty, match only when the name part of the target
    label (as returned by `get_label_info(..., "name")`) is one in the
    list.
    - Type: list(label_no_toolchain)

  * output_name
    - Optional: If nonempty, match only when the `output_name` of the
    target is one in the list.  Note `output_name` defaults to
    `target_name`, and does not include prefixes or suffixes like ".so"
    or ".exe".
    - Type: list(string)

An element with a scope for `.variant` defines a new variant.  Each
variant name used in a selector must be defined exactly once.  Other
selectors can refer to the same variant by using the name string in the
`.variant` field.  Definitions in $variants take precedence over the same
name defined in $standard_variants, but it would probably cause confusion
to use the name of a standard variant with a non-standard definition.

Variant scope parameters

  * name
    - Required: Name for the variant.  This must be unique among all
    variants used with the same environment.  It becomes part of the GN
    toolchain names defined for the environment, which in turn forms part
    of directory names used in $root_build_dir; so it must meet Ninja's
    constraints on file names (sticking to `[a-z0-9_-]` is a good idea).

  * globals
    - Optional: Variables in this scope are introduced as globals visible
    to all GN code in the toolchain.  For example, the standard "gcc"
    variant sets `is_gcc = true` in $globals.  This should be used
    sparingly and is safest when restricted to variables that
    $zx/public/gn/BUILDCONFIG.gn sets defaults for.
    - Type: scope

  * toolchain_args
    - Optional: See toolchain().  Variables in this scope must match GN
    build arguments defined somewhere in the build with declare_args().
    Use this when the variant should change something that otherwise is a
    manual tuning variable to set via `gn args`.  *Do not* define
    variables in declare_args() just for the purpose of setting them here,
    i.e. if they should not *also* be available to set via `gn args` to
    affect other variants that don't override them here.  Instead, use
    either $globals (above) or $toolchain_vars (below).
    - Type: scope

  * toolchain_vars
    - Optional: Variables in this scope are visible in the scope-typed
    $toolchain global variable seen in toolchains for this variant.
    Use this to pass along interesting information without cluttering
    the global scope via $globals.
    - Type: scope

  * configs
    - Optional: List of changes to the pre-set $configs variable in targets
    being defined in toolchains for this variant.  This is the same as in
    the $configs parameter to environment().  Each element is either a
    string or a scope.  A string element is simply appended to the default
    $configs list: it's equivalent to a scope element of `{add=["..."]}`.
    The string is the GN label (without toolchain) for a config() target.
    A scope element can be more selective, as described below.
    - Type: list(label_no_toolchain or scope)
      * shlib
        - Optional: If present, this element applies only when
        `current_toolchain == toolchain.shlib` (if true) or
        `current_toolchain != toolchain.shlib` (if false).  That is, it
        applies only in (not ni) the companion toolchain used to compile
        shared_library() and loadable_module() (including driver()) code.
        - Type: bool

      * types
        - Optional: If present, this element applies only to a target whose
        type is one in this list (same as `target_type` in a selector,
        described above).
        - Type: list(string)

      * add
        - Optional: List of labels to append to $configs.
        - Type: list(label_no_toolchain)

      * remove
        - Optional: List of labels to remove from $configs.  This does
        exactly `configs -= remove` so it has the normal GN semantics that
        it's an error if any element in the $remove list is not present in
        the $configs list beforehand.
        - Type: list(label_no_toolchain)

  * implicit_deps
    - Optional: List of changes to the list added to $deps of all linking
    targets in toolchains for this variant.  This is the same as in the
    $implicit_deps parameter to environment().
    - Type: See $configs

  * tags
    - Optional: List of tags that describe this variant.  This list will be
    visible within the variant's toolchains as ${toolchain.tags}.  Its main
    purpose is to match the $exclude_variant_tags list in an environment()
    definition.  For example, several of the standard variants listed in
    $standard_variants use the "useronly" tag.  The environment() defining
    the kernel toolchains uses `exclude_variant_tags = [ "useronly" ]`.
    Then $variants selectors that choose variants that are incompatible
    with the kernel are automatically ignored in the kernel toolchains,
    so there's no need to add `kernel = false` to every such selector.
    - Type: list(string)

  * bases
    - Optional: A list of other variant names that this one inherits from.
    This is a very primitive mechanism for deriving a new variant from an
    existing variant.  All of fields from all the bases except for `name`
    and `bases` are combined with the fields defined explicitly for the
    new variant.  The fields of list type are just concatenated in order
    (each $bases variant in the order listed, then this variant).  The
    fields of scope type are merged in the same order, with a variant
    later in the list overriding values set earlier (so this variant's
    values override all the bases).  There is *only one* level of
    inheritance: a base variant listed in $bases cannot have $bases itself.
    - Type: list(string)


**Current value for `target_cpu = `:** `[]`

From /b/s/w/ir/k/root_build_dir.zircon/args.gn:15

**Overridden from the default:** `[]`

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

### zbi_compression
This can be either "lz4f" or "zstd", optionally followed by ".LEVEL"
where `LEVEL` can be an integer or "max".  It can also be just "LEVEL"
to to use the default algorithm with a non-default setting.

The default level for each algorithm is tuned to balance compression
speed with compression ratio.  Higher levels make image builds slower.
So using the default during rapid development (quick builds, pretty
good compression) and "max' for production builds (slow builds, best
compression available) probably makes sense.

**Current value for `target_cpu = `:** `"zstd"`

From /b/s/w/ir/k/root_build_dir.zircon/args.gn:16

**Overridden from the default:** `"zstd"`

From //public/gn/zbi.gni:19

### zx
"$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):** `"/"`

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

### zx_build
"$zx_build/" is the prefix for GN "source-absolute" paths in the Zircon
build for build infrastructure.

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

From //public/gn/BUILDCONFIG.gn:17