# Assembling structured configuration

[Structured configuration][sc-docs] allows developers to package components with
different values in different contexts. Product assembly allows developers to
define structured configuration values based on high-level platform and product
configuration.

To vary your component's configuration by product or build type you must declare
a schema, identify how values will be derived from a product's configuration,
and generate your component's config.

## Define a configuration schema

Your component must have a declared configuration schema in its manifest. For
example:

```json5
    ...
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/assembly/structured_config/configured_by_assembly/meta/to_configure.cml" region_tag="config" %}
```

For more information see the [documentation for structured config][sc-docs].

## Identify product assembly configuration

Many configuration options can be represented as the difference between
[`eng` builds and non-`eng` builds][build-types].

If the configuration of your component can't be deduced solely from build type,
email the [Software Assembly list][sa-email] to discuss the schema which should
be used (note that this list is publicly viewable, please use Google-internal
lists to discuss internal-only configuration). Once a schema has been decided,
add it to the [product configuration library][config-schema].

## Configure the package

Determine your package's name and your component's manifest resource path.
Define logic to populate configuration for it in the [product assembly
tool][configure-product]. For example, to configure a value based on the build
type:

```rs
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="src/lib/assembly/platform_configuration/src/subsystems/example.rs" region_tag="example_patches" adjust_indentation="auto" %}
```

Note: A given component cannot mix [configuration values produced by GN][gn-doc]
and values produced by software assembly.

## Update size limits configuration (if any)

When producing configuration values for a package, product assembly must write
its outputs to a different location in the build directory than the path
normally produced by the build system. There are binary size checks that rely on
paths to package manifests that exist in the build directory, so it is important
that you update the package's output path in the build configuration rules.

For example, before having its configuration generated by product assembly,
the `session_manager` package was listed in [the core product's size
limits][core-limits] as:

```gn
{
  component = "Component Framework"
  src = [
    # ...

    "packages/base/session_manager",
  ]

  # ...
},
```

When using product assembly for its config, `session_manager` must now be
specified in size limits as:

```gn
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="products/common/core_size_limits.gni" region_tag="session_manager_size_limit" adjust_indentation="auto" %}
```

[sc-docs]: structured_config.md
<!-- TODO(https://fxbug.dev/42055979) update link to match proper docs -->
[build-types]: /docs/contribute/governance/rfcs/0115_build_types.md
[sa-email]: mailto:software-assembly@fuchsia.dev
[config-schema]: /src/lib/assembly/config_schema/src/product_config.rs
[configure-product]: /src/lib/assembly/platform_configuration/src/lib.rs
[gn-doc]: structured_config.md#define--package-configuration-values-using-gn
[core-limits]: /products/common/core_size_limits.gni