Configuration

The config.toml file stores settings and extends Orbit's functionality. It is written in the TOML format. It is maintained by the developer and can be shared across teams for consistent development environments.

Note: The configuration's file name is "config.toml", with respect to case-sensitivity.

Paths

When a field is expected to be a file system path, Orbit has the ability to resolve relative paths. The path is determined in relation to the currently processed config.toml's parent directory.

This design choice was implemented to allow path definitions to be valid across file systems when sharing configurations. It is recommended to use relative paths when setting a field's value as a path in a config.toml.

Hierarchical structure

Orbit supports multiple levels of configuration. Each level has its own order of precedence. The order of precedence is the following:

Local configuration file (current ip's .orbit/conifg.toml)
Regional configuration files (parent directories of the current working directory)
Global configuration file (Orbit's $ORBIT_HOME/config.toml)
Included configuration files (order-preserving list found for the global configuration's include field)

The configuration files are processed in the order defined above. When a configuration file defines a field, no other configuration files later in the process will be able to override its value. If a field is never provided an explicit value, then Orbit's default will be used.

Tip: You can modify some values in the configuration file through the command-line by using the orbit config command.

Configuration format

Every configuration file consists of the following sections:

include - Lists other config.toml files to process. This field is only allowed for the global configuration file.
[general] - The general settings.
- require-public - Assume source files to be private by default.
- target-dir - Default target directory.
[test] - The test settings.
- default-target - Set the default target for tests.
[build] - The build settings.
- default-target - Set the default target for builds.
[publish] - The publish settings.
- default-channels - Set the default channels to publish an ip to.
[install] - The install settings.
- default-protocol - Set the default protocol for installing ip.
[vhdl-format] - VHDL code formatting.
[verilog-format] - SystemVerilog/Verilog code formatting.
[env] - The runtime environment variables.
[[target]] - Define a target.
- name - The name of the target.
- description - A short description of the target.
- command - The command to execute the target.
- args - Arguments to pass to the command.
- plans - The list of supported blueprint file formats.
- build - Enable or disable target invocation for the build subcommand.
- test - Enable or disable target invocation for the test subcommand.
- [fileset] - Filesets to collect for the target.
[[protocol]] - Define a protocol.
- name - The name of the protocol.
- description - A short description of the protocol.
- patterns - String patterns to match an ip's URL.
- command - The command to execute the protocol.
- args - Arguments to pass to the command.
[[channel]] - Define a channel.
- name - The name of the channel.
- description - A short description of the channel.
- root - The directory where the channel exists.
- sync.command - The command to execute when synchronizing the channel.
- sync.args - Arguments to pass to the command during synchronization.
- pre.command - The command to execute immediately before launch.
- pre.args - Arguments to pass to the command immediately before launch.
- post.command - The command to execute immediately after launch.
- post.args - Arguments to pass to the command immediately after launch.

The `include` field

The include entry is an array of strings that are file paths to other Orbit configuration files. Relative paths are resolved relative to the directory where the configuration file that defines them exists. Only the global configuration file is allowed to have this key.

include = [
    "profiles/p1/config.toml",
    "profiles/p2/config.toml",
    "channels/c1/config.toml"
]

The `[general]` section

The `require-public` field

The require-public key determines if to assume source files are private by default. When true, all source files are private to their respective ip unless their file path is found in their ip manifest's public entry. When false, all source files are treated as public when their ip manifest's public entry is omitted.

[general]
require-public = true
# ...

By default, this key is set true. This means all source files are assumed private by default, unless explicitly specified in their ip manifest's public entry. See the ip manifest's reference on the public entry for more information about specifying public source files.

The `target-dir` field

The target-dir key defines the default output directory to create for the planning and building phases. This value can be overridden on the command-line when the --target-dir option is specified.

[general]
# ...
target-dir = "target"

When this key is not defined, the default value for the build directory is "target".

The `[test]` section

The `default-target` field

The optional default-target key sets the default target when starting the build process through the test entry point (orbit test).

[test]
default-target = "modelsim"

If the default target is set to be used and its name cannot be found among the known targets, the build process will error.

The `[build]` section

The `default-target` field

The optional default-target key sets the default target when starting the build process through the build entry point (orbit build).

[build]
default-target = "vivado"

If the default target is set to be used and its name cannot be found among the known targets, the build process will error.

The `[publish]` section

The `default-channels` field

The optional default-channels field is an array of strings that represent the names of known channels. When this field is provided and the current ip omits the channels field from its manifest, the ip will be published to the list of channels defined here. If the current ip's manifest does have the channels field defined, then the default-channels field is not applied.

[publish]
default-channels = ["hyperspace-labs"]

If the default-channels field is set and at least one of the names cannot be found among the known channels, the publishing process will error.

The `[install]` section

The `default-protocol` field

The optional default-protocol field can be used to specify which protocol should have priority when trying to access an ip from the internet.

[install]
default-protocol = "git"

If the default protocol has patterns configured and none of the patterns match the given ip's source URL, then it is not used. If the default protocol is set to be used and its name cannot be found among the known protocols, the installation process will error.

The `[vhdl-format]` section

The currently supported entries are demonstrated in the following code snippet. Entries not present will be set to their default values.

[vhdl-format]
# Enable colored output for VHDL code snippets
highlight-syntax = true
# Number of whitespace characters per tab/indentation
tab-size = 2
# Insert a tab before 'generic' and 'port' interface declarations
indent-interface = true
# Automatically align a signal or constant's subtype with its other identifiers
type-auto-alignment = true
# Number of whitespace characters after alignment (before the `:` character)
type-offset = 1
# Automatically align an instantiation's mapping along its port connections
mapping-auto-alignment = true
# Number of whitespace characters before port connection (before the `=>` character)
mapping-offset = 1
# Place a space between generic/port keyword and its opening parenthesis
space-interface-parenthesis = true
# The default instance name
instance-name = "ux"

The `[verilog-format]` section

The currently supported entries are demonstrated in the following code snippet. Entries not present will be set to their default values. This section currently applies its settings to SystemVerilog and Verilog source code.

[verilog-format]
# Enable colored output for code snippets
highlight-syntax = true
# Number of whitespace characters per tab/indentation
tab-size = 2
# Automatically align a port or parameter's name with the module's other names
name-auto-alignment = true
# Number of additional whitespace characters after alignment
name-offset = 0
# Number of whitespaces before a range specifier
range-offset = 1
# Automatically align an instantiation's mapping along its port connections
mapping-auto-alignment = true
# Number of whitespace characters before port connection (before the `(` character)
mapping-offset = 0
# The default instance name
instance-name = "ux"

The `[env]` section

The [env] section allows for an arbitrary number of user-defined key/value pairs. Each key's value is expected to be a string. Orbit exposes these key/value pairs as variables for string swapping in permissible strings as well as environment variables during the execution stage of the build process.

[env]
# Accessible as environment variable: ORBIT_ENV_FOO, string variable: orbit.env.foo
FOO = "bar" 
# Accessible as environment variable: ORBIT_ENV_LICENSE_FILE, string variable: orbit.env.license.file
LICENSE_FILE = "3000@server"

The `[[target]]` array

The [[target]] array lists user-defined targets for implementing the execution stage of the build process. Each target must exist under its own [[target]] header.

The `name` field

The target name is an identifier used to refer to the target. It is used at the start of the build process to specify how the execution stage should behave.

[[target]]
name = "dump-blueprint"

This field is required when configuring a target.

The `description` field

The description is an optional short blurb about the target. This should be plain text (not Markdown).

[[target]]
# ...
description = "Print the blueprint contents to the screen"

The `command` field

The command entry for a target is used to specify what program to run for the execution stage of the build process.

[[target]]
# ...
command = "cat"

This field is required when configuring a target.

The `args` field

The optional args entry is an array of strings that are passed to the program when it runs during the execution stage of the build process. Relative file paths included in this value are considered relative to the configuration file that defines this entry.

[[target]]
# ...
args = ["blueprint.tsv"]

This field supports string swapping.

The `plans` field

The optional plans entry is an array of strings that specify which blueprint file types are supported by the target.

[[target]]
# ...
plans = ["tsv"]

If more than one value is listed, then the default plan for the target is the first item in the list.

A plan can be provided on the command-line at the start of a build process to override the default plan. If a plan is provided on the command-line, then it must first be a supported plan as well as one found within the target's defined plans entry.

If this field is left blank or not defined, then the default plan is "tsv".

The `build` field

The optional build key explicitly allows or disallows the build entry point to the build process (orbit build) to use this target.

By setting this field to true, then the given target will be made available to the build entry point. By setting this field to false, then the given target is hidden and unusable for the build entry point.

[[target]]
# ...
build = true

If this field is not defined, then the default is true.

The `test` field

The optional test key explicitly allows or disallows the test entry point to the build process (orbit test) to use this target.

By setting this field to true, then the given target will be made available to the test entry point. By setting this field to false, then the given target is hidden and unusable for the test entry point.

[[target]]
# ...
test = true

If this field is not defined, then the default is true.

The `[fileset]` section

The [fileset] section allows user-defined key/value pairs, where the key corresponds to a fileset name and the value is a string that corresponds to the glob-style pattern. The fileset name will be normalized to COBOL-CASE.

If a string is the immediate value of a custom key in the fileset section, then it becomes the fileset's only pattern and will only be applied to the current ip's directory.

[[target]]
# ...
fileset.TEXT = "*.txt"
fileset.CPPF = "{{ orbit.tb.name }}.cpp"

If an inline table is the value of a custom key in the fileset section, then it requires the patterns field to be an array of strings that represent the different file patterns for this fileset. The optional recursive field accepts a boolean that when enabled, will apply the fileset patterns to all ips in the dependency graph.

[[target]]
# ...
fileset.PYF = { patterns = ["*.py", "*.py3"], recursive = true }

The patterns for user-defined filesets support string swapping (as shown in the pattern for the CPPF fileset).

The `[[protocol]]` array

The [[protocol]] array lists user-defined protocols to access ips from the internet. Each protocol must exist under its own [[protocol]] header.

The `name` field

See [target]'s definition of name.

The `description` field

See [target]'s definition of description.

The `patterns` filed

The optional patterns field is an array of strings that represent different URL patterns for the given protocol. If no patterns are provided, then the protocol will accept any URL from a given ip. If a list of patterns is provided, then the protocol will only try an ip if it's URL is a match with one or more of the patterns for that protocol.

[[protocol]]
# ...
patterns = ["*.git"]

[[channel]]
# ...
root = "./index"

If this entry is not defined, the default root directory for a channel is ., the directory where the configuration file exists.

The Book of Orbit