FFX Config

FFX's configuration management allows you to configure your FFX code without recompiling. From a high level, configurations can be thought of as a multi-layered, key-value map.

Value resolution process

The configuration management code searches in several locations for the value associated with a key. The search is performed in the following order and returns the first value found:

  1. Runtime configuration (set by the command line)
  2. User level configuration (set by ffx config set)
  3. Build directory level configuration (generated by the build)
  4. Global level configuration variables
  5. Default configuration (compiled into ffx)

Runtime configuration

Runtime configuration is set by the user on the command line when invoking ffx. The top-level command accepts a configuration parameter:

ffx --config "property-name=value" ...

The runtime parameter takes the format of comma separated key-value pairs ("{key}={value},{key}={value},etc...") because this is not strongly typed, any configurations set here will be assumed to be strings.

The daemon runs as its own process and currently the runtime configuration is not transferred from the CLI to the daemon if the daemon is started up. It's expected that if you want to configure the daemon using the runtime configurations, the daemon command will be run manually:

ffx --config "config-test=runtime" daemon start --background

User configuration

User configuration is configuration set in the user's home directory and applies to all invocations of ffx by that user. User configuration is only overridden by runtime configuration.

User configuration is set using the ffx config set command.

ffx config set property-name value

Build-directory configuration

Build configuration is associated with a build directory. It is intended to be used to set properties describing the output of the build. It should be generated as part of the build process, and is considered read-only by ffx.

The file format is a JSON object:

{
    "product": {
        "path": "/out/project/dir/product_bundle",
        "name": "sample_project"
    },
    "fidl": {
        "ir": "$BUILD_DIR/fidling/gen/ir_root"
    }
}

$BUILD_DIR in this example is not a shell environment variable, but an internal ffx variable placeholder. See value representations for more details.

Global configuration

Global configuration is intended to be a system-wide configuration level. It is intended to be used when installing ffx on a host system to set organizational properties that would be the same for a collection of users.

It is created outside the ffx workflow, and is considered read-only by ffx.

The file format is a JSON object:

{
    "gcs": {
        "release_bucket": "gs://project/releases",
    }
}

Default configuration

Default configurations are provided through GN build rules across all subcommands and are hard-coded and immutable.

Value representations

The values stored in the ffx configuration are encoded as JSON values.

  • Number, both integer and floating point numbers.
  • String
  • Boolean, true|false.
  • Null, represented as null
  • Arrays of values
  • Object

String interpolation

Some strings can include placeholders that are interpolated. This allows properties to be set relative to directories, or resolve values from the running process environment.

Placeholders defined by ffx are:

  • $BUILD_DIR - the build directory determined when running an ffx command. It can be empty if no build directory is located, nor configured.
  • $CACHE - the directory to use to store cached data.
  • $CONFIG - the directory to store configuration data.
  • $DATA - the directory to store persistent data.
  • $SHARED_DATA - the directory for persistent data that is shared between all isolates and instances of ffx on the current host machine. This is used for data that is used to manage global state, such as processes that are opening TCP/IP ports.
  • $FIND_WORKSPACE_ROOT - the first parent directory containing a Bazel workspace.
  • $HOME - the home directory of the current user.
  • $RUNTIME - the directory to store all runtime information. On Linux this is typically $HOME/.local/share/Fuchsia/ffx.

Additionally, any string consisting of $ followed by a name in all-capitals, digits, and other allowed characters is resolved from the process environment.

Array processing

Arrays are commonly used to provide an ordered list of possible values, and then return the first non-empty value.

For example, to attempt to use the ssh key from the environment, otherwise falling back to a standard location:

{
    "ssh_key": [ "$SSH_KEY_FROM_ENV", "$HOME/.ssh/ssh_key"]
}

Configuration environment settings

The command collection ffx config env is used to manage the configuration of how to locate the various configuration level data files.

For example, to set the path to the global configuration:

ffx config env set --level global /etc/fuchsia/ffx_global_props.json