Configuration Reference¶

When running the zb command-line interface, zb will gather configuration data from files in the local filesystem. Command-line flags or environment variables will override any settings in the configuration files.

Format¶

zb reads its configuration in JSON With Commas and Comments format. This is a strict superset of JSON that permits:

trailing commas in arrays and objects
C++ style /* block comments */ and // line comments

Location¶

Linux and macOS¶

On Linux and macOS systems, zb follows the XDG Base Directory Specification to find its configuration files. The files used are (in decreasing order of precedence):

$XDG_CONFIG_HOME/zb/config.jwcc. If $XDG_CONFIG_HOME is not set, it defaults to $HOME/.config.
$XDG_CONFIG_HOME/zb/config.json. If $XDG_CONFIG_HOME is not set, it defaults to $HOME/.config.
For each directory in $XDG_CONFIG_DIRS separated by colons (defaulting to /etc/xdg): a. zb/config.jwcc underneath the directory b. zb/config.json underneath the directory

Windows¶

On Windows systems, zb will find configuration files at (in decreasing order of precedence):

%AppData%\zb\config.jwcc
%AppData%\zb\config.json

Properties¶

debug¶

Type:: boolean
Default:: false

Whether to include logging useful for debugging zb itself. This is generally very verbose and should only be enabled if you are reporting an issue with zb. Equivalent to the --debug command-line flag.

storeDirectory¶

Type:: string
Default:: /opt/zb/store on Linux and macOS, C:\zb\store on Windows

Absolute path to the store directory.

Will be overridden by ZB_STORE_DIR.

storeSocket¶

Type:: string
Default:: /opt/zb/var/zb/server.sock on Linux and macOS, C:\zb\var\zb\server.sock on Windows

Absolute path of the store server Unix socket to use or, in the case of zb serve, to create.

Will be overridden by ZB_STORE_SOCKET.

cacheDB¶

Type:: string
Default:: $XDG_CACHE_HOME/zb/cache.db on Linux and macOS. ($XDG_CACHE_HOME defaults to $HOME/.cache.) %LocalAppData%\zb\cache.db on Windows.

Absolute path to a SQLite database that contains cache data for speeding up zb. This database can be deleted at any time: it exists purely to speed up builds.

Equivalent to the --cache command-line flag.

allowEnvironment¶

Type:: boolean or array of string
Default:: false

The allowEnvironment setting configures the behavior of os.getenv().

If true, then os.getenv() can retrieve any environment variable in the zb process’s environment. Equivalent to passing --allow-all-env on the command line.
If false, then os.getenv() will always return nil.
If the setting is an array, then it is interpreted as a set of environment variable names that os.getenv() will retrieve from the zb process’s environment. os.getenv() will return nil for any environment variable whose name is not in the array. Equivalent to passing --allow-env with each name on the command line.

allowEnvironment settings are not merged: the setting from the file with the highest precedence will be used.

trustedPublicKeys¶

Type:: array of objects
Default:: []

The trustedPublicKeys setting is an array of public keys that zb will trust for existing build results when building a derivation. trustedPublicKeys settings are merged across all configuration files. Each public key is a JSON object with the following properties:

Name	Type	Description
`format`	string	Only `"ed25519"` is defined at the moment
`publicKey`	string	Base64-encoded public key data

For more details on the content of these properties, see realization signature specification.

If the configuration files do not include any trusted public keys, then any previous build result can be reused unless the --clean command-line option is passed.

server¶

Type:: object
Default:: {}

See Server Configuration.

Store locator¶

A store locator is a JSON object that specifies how to access a store. The JSON object’s properties are interpreted based on the value of its type property, which can be one of the following strings:

null

Represents an empty store. Same as using a JSON null instead of the JSON object. No additional properties.

http

A store using the Binary Cache protocol.

http store locators have the following properties:

Name	Type	Required	Description
`url`	string	Yes	URL to the binary cache’s discovery document.

Example:

{
  "server": {
    "download": {
      "type": "http",
      "url": "https://www.example.com/zb/cache.json"
    }
  }
}