Rez configuration and plugins

> One-sentence summary: configuration is layered (each source overrides, not replaces, the
> previous), and everything extensible — shells, build systems, repositories, release hooks — is a
> plugin discovered either by rezplugins directory layout or by Python entry points.

Skill scope: configuration and plugins. For resolve behavior see rez-resolve; for the CLI see
rez-cli.

Configuration precedence

Lowest to highest. Later sources win.

1. rezconfig.py shipped in the rez installation (defaults + documentation for every setting)
2. File pointed at by REZ_CONFIG_FILE — can be a path-like list to read several files
3. $HOME/.rezconfig or $HOME/.rezconfig.py
4. REZ_<SETTING>_JSON environment variable — value must be JSON-encoded
5. REZ_<SETTING> environment variable — e.g. REZ_PACKAGES_PATH overrides packages_path.
   Takes precedence over the _JSON form when both are present.
6. (build/release only) the package's own config section via scope("config")

Related: REZ_DISABLE_HOME_CONFIG skips the home config.

Verify what actually took effect:

rez-config                 # dump all settings
rez-config packages_path   # one setting

Merge rules

Sources merge; they do not replace wholesale.

• Dicts are merged recursively.
• Non-dicts override the previous value.

To append/prepend to a list setting instead of replacing it, use ModifyList:

release_hooks = ModifyList(append=["custom_release_notify"])

prepend=[...] is also supported.

File formats

Both YAML (.rezconfig) and Python (.rezconfig.py) are supported. Choose Python when settings
must vary by platform. You only need to list settings that differ from the defaults.

String expansion

Applied to all configuration settings:

• Environment variables: ${HOME}
• system object properties: {system.platform}, {system.arch}, {system.os}

DelayLoad

Keep a large setting out of the main config and load it only when referenced (YAML or JSON):

default_relocatable_per_package = DelayLoad('/svr/configs/rez_relocs.yaml')

Settings that matter most

The full, authoritative list with documentation lives in src/rez/rezconfig.py in the rez source.

Plugins

Plugin types and their base classes:

Built-ins live in src/rezplugins. New plugins are encouraged out-of-tree.

List what is installed and its load status:

rez -i

Example output — note release vcs / svn / FAILED: No module named 'pysvn', i.e. rez -i is the
quickest way to see a plugin that failed to import.

Configuring plugins

plugins = {
    "package_repository": {
        "filesystem": {}
    }
}

Discovery mechanism 1 — rezplugins directory layout

Point plugin_path (or REZ_PLUGIN_PATH) at the directory above your rezplugins dir:

rezplugins/
├── __init__.py
└── <plugin_type>/
    ├── __init__.py
    └── <plugin name>.py

> The rezplugins directory name is not optional, and your sparse copy must be on
> REZ_PLUGIN_PATH only — not on PYTHONPATH. That ordering guarantees rez's own copy of
> rezplugins is found first.

Discovery mechanism 2 — entry points (rez 3.3.0+)

One entry point per plugin type:

• rez.plugins.build_process
• rez.plugins.build_system
• rez.plugins.command
• rez.plugins.package_repository
• rez.plugins.release_hook
• rez.plugins.release_vcs
• rez.plugins.shell

This is the more flexible option: no special file layout, and one package can ship several plugins
of different types.

Default settings for a plugin

Ship a rezconfig.py or rezconfig.yml beside the plugin module; rez loads it automatically.

top_level_setting = "value"

plugin_name = {
    "setting_1": "value1"
}

plugin_name settings arrive as self.settings; top_level_setting as
self.type_settings.top_level_setting. Only the types marked "Yes" in the table above support
top-level settings.

Overriding built-ins

Install a plugin with the same name and type as a built-in and rez prefers yours. This is the
supported way to modify built-in behavior without patching rez source.

Troubleshooting

Agent workflow

1. Confirm the effective value with rez-config <setting> before changing anything.
2. Prefer environment variables for one-off overrides, REZ_CONFIG_FILE for site-wide policy.
3. Use ModifyList whenever you mean "add to" rather than "replace".
4. Check rez -i before debugging a plugin by hand.
5. Put new plugins in entry-point packages unless you specifically need the directory layout.