The Fuchsia build system uses a combination of platform, product, and board
configurations to create a final product bundle. While these configurations
define the canonical version of a product, you may need to make temporary
modifications for testing or debugging. For more conceptual information about
software assembly, see [Software Assembly](https://fuchsia.dev/docs/concepts/software_assembly/overview).

Developer overrides provide a mechanism to make local-only modifications to a
product's configuration without changing the source files in the Fuchsia tree.

This document explains how you can use developer overrides to modify a product's
configuration.

## Using assembly overrides

To use developer overrides for assembly, you need to:

1. **Define the overrides** in a GN target, typically in `//local/BUILD.gn`.
2. **Apply the overrides** to your build configuration.

For example, to enable a kernel argument, first define the override in
`//local/BUILD.gn`:

    import("//build/assembly/developer_overrides.gni")

    assembly_developer_overrides("enable_kernel_debug") {
      kernel = {
        command_line_args = [ "foo" ]
      }
    }

Then, apply this override to your build configuration using one of the following
methods:

- [Using `fx set`](https://fuchsia.dev/fuchsia-src/development/build/software_assembly/developer_overrides#fx-set)
- [Using `fx args` or `args.gn`\`](https://fuchsia.dev/fuchsia-src/development/build/software_assembly/developer_overrides#args-gn)

### Using `fx set`

The `fx set` command includes the `--assembly-override` option to specify an
override for the main product assembly (not the test assembly, recovery, etc...).
For example:

> [!NOTE]
> **Note:** The value used for `--assembly-override` is the identifier that you used in your `//local/BUILD.gn` file.

    fx set core.x64 --assembly-override //local:enable_kernel_debug

The `--assembly-override` option supports two formats:

> [!NOTE]
> **Note:** You can provide this option multiple times, but each instance must apply to a different assembly target. An error is generated if more than one override target matches the same assembly target.

- `--assembly-override <overrides_target>`: Applies the overrides to the main
  product assembly.

  For example, the following command applies the `//local:enable_kernel_debug`
  override to the `core.x64` product:

      fx set core.x64 --assembly-override //local:enable_kernel_debug

- `--assembly-override <assembly_target_pattern>=<overrides_target>`: Applies
  the overrides to a specific assembly target pattern.

  For example, to apply overrides defined in `//local:zedboot_overrides` only
  to the `zedboot` assembly, you would run the following:

      fx set core.x64 --assembly-override '//products/zedboot/*=//local:zedboot_overrides'

For more information, see the following sections:

- To learn how to specify the assembly target, see [Product Label Patterns](https://fuchsia.dev/fuchsia-src/development/build/software_assembly/developer_overrides#product-label-patterns).
- To learn how to define the override target, see [Defining an `assembly_developer_overrides`
  target](https://fuchsia.dev/fuchsia-src/development/build/software_assembly/developer_overrides#defining-an-assembly-developer-overrides-target).

### Using `fx args` or `args.gn`

You can apply overrides by editing your `args.gn` file or using
[`fx args`](https://fuchsia.dev/reference/tools/fx/cmd/args). The following GN arguments are available:

- [`product_assembly_overrides_label`](https://fuchsia.dev/fuchsia-src/development/build/software_assembly/developer_overrides#product-assembly-overrides-labe): Specifies a single override target for the main product assembly.
- [`product_assembly_overrides_contents`](https://fuchsia.dev/fuchsia-src/development/build/software_assembly/developer_overrides#product-assembly-overrides-contents): Defines the overrides inline within `args.gn` for the main product assembly.
- [`product_assembly_overrides`](https://fuchsia.dev/fuchsia-src/development/build/software_assembly/developer_overrides#product-assembly-overrides-contents): A list that explicitly maps override targets to the assembly targets they apply to.

#### `product_assembly_overrides_label`

The `product_assembly_overrides_label` argument applies the specified overrides
to the main assembly of the selected product. It does not affect other
product assemblies like recovery, zedboot, or tests.

Example `args.gn`:

    import("//products/...")
    import("//boards/...")

    product_assembly_overrides_label = "//local:my_overrides"

#### `product_assembly_overrides_contents`

The `product_assembly_overrides_contents` argument allows you to define
overrides directly in your `args.gn`. These overrides only apply to the main
product assembly.

Example `args.gn`:

    import("//products/...")
    import("//boards/...")

    product_assembly_overrides_contents = {
      kernel = {
        command_line_args = [ "kernel.enable-debugging-syscalls=true" ]
      }
    }

The value uses the same syntax as the `assembly_developer_overrides()` GN
template, see [Defining an `assembly_developer_overrides`
target](https://fuchsia.dev/fuchsia-src/development/build/software_assembly/developer_overrides#defining-an-assembly-developer-overrides-target).

#### `product_assembly_overrides`

The `product_assembly_overrides` argument is used to specify overrides for
multiple or non-main assemblies. It uses [GN label patterns](https://gn.googlesource.com/gn/+/master/docs/reference.md#label_pattern)
to match override targets to their corresponding assembly targets.

Example `args.gn`:

> [!NOTE]
> **Note:** You can also place this configuration in `//local/args.gn`, and `fx set` automatically appends it to the `args.gn` in your build directory.

    import("//products/....")
    import("//boards/....")

    product_assembly_overrides = [
      {
        # zedboot
        assembly = "//products/zedboot/*"
        overrides = "//local:zedboot_overrides"
      },
      {
        # For assemblies in Bazel, use their product label
        assembly = "//products/minimal/*"
        overrides = "//local:minimal_overrides"
      },
      {
        assembly = "//products/core/*"
        overrides = "//local:enable_kernel_debug"
      },
    ]

## Defining an `assembly_developer_overrides` target

To define a set of developer overrides, use the `assembly_developer_overrides()`
template in a `BUILD.gn` file. It is recommended to place these definitions in
the `//local` directory of your Fuchsia checkout, as this directory is ignored
by git.

Example `//local/BUILD.gn`:

> [!NOTE]
> **Note:** To see available override options, see [Available override options](https://fuchsia.dev/fuchsia-src/development/build/software_assembly/developer_overrides#available-override-options).

    import("//build/assembly/developer_overrides.gni")

    assembly_developer_overrides("enable_kernel_debug") {
      kernel = {
        command_line_args = [
          "foo",
        ]
      }
    }

    # Multiple override sets can be defined in the same file.
    assembly_developer_overrides("bar_debug") {
      kernel = {
        command_line_args = [ "bar" ]
      }
    }

## Available override options

The following sections describe the available options that can be configured
within an `assembly_developer_overrides` target:

- [Developer-only assembly options](https://fuchsia.dev/fuchsia-src/development/build/software_assembly/developer_overrides#developer-only-assembly-options)
- [Platform configuration](https://fuchsia.dev/fuchsia-src/development/build/software_assembly/developer_overrides#platform-configuration)
- [Kernel command-line arguments](https://fuchsia.dev/fuchsia-src/development/build/software_assembly/developer_overrides#kernel-command-line-arguments)
- [Additional packages](https://fuchsia.dev/fuchsia-src/development/build/software_assembly/developer_overrides#additional-packages)
- [Shell commands](https://fuchsia.dev/fuchsia-src/development/build/software_assembly/developer_overrides#shell-commands)
- [Board configuration](https://fuchsia.dev/fuchsia-src/development/build/software_assembly/developer_overrides#board-configuration)
- [Compiled packages and components](https://fuchsia.dev/fuchsia-src/development/build/software_assembly/developer_overrides#compiled-packages-and-components)
- [Appending to lists](https://fuchsia.dev/fuchsia-src/development/build/software_assembly/developer_overrides#appending-to-lists-with-append-to-key)

### Developer-only assembly options

These assembly options can only be enabled through developer overrides, and are
not normally allowed in product or board configs.

Example `//local/BUILD.gn`:

    import("//build/assembly/developer_overrides.gni")

    assembly_developer_overrides("netboot_with_all_packages") {
      developer_only_options = {
        all_packages_in_base = true
        netboot_mode = true
      }
    }

- `all_packages_in_base`: Redirects all `cache` and `on_demand` packages into the `base` package set. This is useful for making debugging tools available on a device when networking is non-functional.
- `netboot_mode`: Creates a Zircon Boot Image (ZBI) that includes the FVM/Fxfs image inside a ramdisk, allowing the product to be netbooted.

### Platform configuration

You can override the `platform` configuration of a product assembly
configuration. For more information, see the
[`PlatformSettings` reference](https://fuchsia.dev/reference/assembly/PlatformSettings).

The values that you specify are merged with the product's platform configuration
on a field-by-field basis.

Example `//local/BUILD.gn`:

    import("//build/assembly/developer_overrides.gni")

    assembly_developer_overrides("enable_sl4f") {
      platform = {
        development_support = {
          include_sl4f = true
          include_netsvc = true
        }
      }
    }

If you want to append to a list instead of replacing it, see
[Appending to lists with
`__append_to_<key>`](https://fuchsia.dev/fuchsia-src/development/build/software_assembly/developer_overrides#appending-to-lists-with-append-to-key).

### Kernel command line arguments

You can add kernel command line arguments. The order of the kernel command
line arguments are not preserved. For a list of available options, see the
[Zircon Kernel Commandline Options](https://fuchsia.dev/docs/gen/boot-options) documentation.

Example `//local/BUILD.gn`:

    import("//build/assembly/developer_overrides.gni")

    assembly_developer_overrides("bar_debug") {
      kernel = {
        command_line_args = [ "bar" ]
      }
    }

### Additional packages

You can add developer-specified packages to the `base`, `cache`, `bootfs`, and
`flexible` package sets. The `flexible` package set is placed in `cache` for
`eng` build types and in `base` for `user` and `userdebug` build types.

The template requires specific GN labels for packages and does not use GN
metadata to traverse package groups.

Example `//local/BUILD.gn`:

    import("//build/assembly/developer_overrides.gni")

    assembly_developer_overrides("my_custom_base_packages") {
      base_packages = [
        "//some/gn/target/for/a:package",
        "//some/other/target/for/a:package",
        "//third_party/sbase",
      ]
    }

### Shell commands

To add command-line tools to the Fuchsia shell, you must both add the package
containing the tool and instruct assembly to create the launcher stub for the
component.

Example `//local/BUILD.gn`:

    import("//build/assembly/developer_overrides.gni")

    assembly_developer_overrides("my_custom_shell_commands") {
      shell_commands = [
        {
          package = "cp"
          components = [ "cp" ]
        }
      ]
    }

If making the package available through package discovery isn't sufficient, you
can also add the package to a package set.

Example `//local/BUILD.gn`:

    import("//build/assembly/developer_overrides.gni")
    assembly_developer_overrides("my_custom_shell_commands") {
      shell_commands = [
        {
          package = "cp"
          components = [ "cp" ]
        }
      ]

      # This GN target should define a package named "cp".
      base_packages = [
        "//some/gn/target/for/my/package:cp"
      ]
    }

### Board configuration

You can override board-specific configuration to test changes or new features.

Example `//local/BUILD.gn`:

    import("//build/assembly/developer_overrides.gni")

    assembly_developer_overrides("add_new_feature") {
      board = {
        provided_features = [ "fuchsia::new_feature" ]
        filesystems = {
          gpt_all = true
        }
      }
    }

To append to a list instead of replacing it, see
[Appending to lists with
`__append_to_<key>`](https://fuchsia.dev/fuchsia-src/development/build/software_assembly/developer_overrides#appending-to-lists-with-append-to-key).

### Compiled packages and components

You can add developer-specified contents and CML shards to packages and
components that are compiled by assembly.

Example `//local/BUILD.gn`:

    import("//build/assembly/developer_overrides.gni")

    assembly_developer_overrides("add_core_shard") {
      compiled_packages = [
        {
          name = "core"
          components = [
            {
              component_name = "core"
              // Paths to _files_, not targets.
              shards = [ "//local/testing.core_shard.cml" ]
            },
          ]
        }
      ]
    }

### Appending to lists with `__append_to_<key>`

By default, developer overrides replace a list with the new contents that you
specify. To append to a list instead, use the `__append_to_<key>` syntax, where
`<key>` is the name of the list.

For example, given the following board configuration:

    board_configuration("bar") {
      provided_features = [ "fuchsia::feature1", "fuchsia::feature2"]
    }

You can append a new feature using this override:

    import("//build/assembly/developer_overrides.gni")

    assembly_developer_overrides("foo") {
      board = {
        __append_to_provided_features = [ "fuchsia::new_feature" ]
      }
    }

The resulting configuration will be:

    board: {
      provided_features: [
        "fuchsia::feature1",
        "fuchsia::feature2",
        "fuchsia::new_feature",
      ]
    }

## Important details

### Assembly warning text

Assembly operations with overrides always produce a warning that details the
overrides being applied. For example:

    WARNING!:  Adding the following via developer overrides from: //local:enable_kernel_debug

      Additional kernel command line arguments:
        foo

### Product label patterns

The mapping between an override target and a product bundle is done through
label pattern matching.

> [!IMPORTANT]
> **Important:** Do not use `//*` as a pattern. It will match every assembly in the build, including all tests, zedboot, and recovery images.

- `//some/label/with/wildcard/*`: Matches all assemblies in and under that path.
- `//some/label/with/wildcard:*`: Matches all assemblies in that folder only.

Different assemblies are located at different paths in the build graph. Common
locations include the following:

- **GN-assembled products** :
  - `guest`: `//build/images/guest/*`
- **Bazel-assembled products** (`bringup`, `core`, `minimal`, `terminal`, `workbench`, etc.):
  - Boards in `fuchsia.git`: `//products/<name>/*`
  - Vendor boards: `//vendor/<vendor>/products/<name>/*`

[](https://issues.fuchsia.dev/issues/new?component=1439230&template=1881640&description=Issue+on:+https://fuchsia.dev/docs/development/build/software_assembly/developer_overrides.md "Report a bug or suggest improvements on this page") [](https://cs.opensource.google/fuchsia/fuchsia/+/main:docs/development/build/software_assembly/developer_overrides.md "View the source code of this page") [](https://ci.android.com/edit?repo=fuchsia/fuchsia/main&file=docs/development/build/software_assembly/developer_overrides.md&cloneRepo=fuchsia/fuchsia:refs/heads/main&fullPath=fuchsia/docs/development/build/software_assembly/developer_overrides.md "Edit the source code of this page")