Configuring Rez

• Overview
• Configuration Settings
  • all_parent_variables
  • all_resetting_variables
  • bind_module_path
  • browser
  • build_directory
  • build_thread_count
  • cache_listdir
  • cache_package_files
  • catch_rex_errors
  • color_enabled
  • context_tmpdir
  • debug_all
  • debug_bind_modules
  • debug_file_loads
  • debug_memcache
  • debug_none
  • debug_old_commands
  • debug_package_exclusions
  • debug_package_release
  • debug_plugins
  • debug_resolve_memcache
  • debug_resources
  • default_shell
  • difftool
  • disable_rez_1_compatibility
  • documentation_url
  • dot_image_format
  • editor
  • env_var_separators
  • error_commands2
  • error_nonstring_version
  • error_old_commands
  • error_package_name_mismatch
  • error_version_mismatch
  • image_viewer
  • implicit_packages
  • local_packages_path
  • max_package_changelog_chars
  • memcached_context_file_min_compress_len
  • memcached_listdir_min_compress_len
  • memcached_package_file_min_compress_len
  • memcached_resolve_min_compress_len
  • memcached_uri
  • new_session_popen_args
  • package_commands_sourced_first
  • package_filter
  • packages_path
  • parent_variables
  • plugin_path
  • prefix_prompt
  • prune_failed_graph
  • quiet
  • release_hooks
  • release_packages_path
  • resetting_variables
  • resolve_caching
  • resource_caching_maxsize
  • rez_1_cmake_variables
  • rez_1_environment_variables
  • rez_tools_visibility
  • rxt_as_yaml
  • set_prompt
  • show_progress
  • suite_alias_prefix_char
  • suite_visibility
  • terminal_emulator_command
  • tmpdir
  • variant_select_mode
  • warn_all
  • warn_commands2
  • warn_none
  • warn_nonstring_version
  • warn_old_commands
  • warn_package_name_mismatch
  • warn_shell_startup
  • warn_untimestamped
  • warn_version_mismatch

Overview

Rez has a good number of configurable settings. The default settings, and documentation for every setting, can be found here.

Settings are determined in the following way:

• The setting is first read from the file rezconfig.py in the rez installation;
• The setting is then overridden if it is present in another settings file pointed at by the REZ_CONFIG_FILE environment variable;
• The setting is further overriden if it is present in $HOME/.rezconfig;
• The setting is overridden again if the environment variable REZ_XXX is present, where XXX is the uppercase version of the setting key. For example, "image_viewer" will be overriden by REZ_IMAGE_VIEWER.
• This is a special case applied only during a package build or release. In this case, if the package definition file contains a "config" section, settings in this section will override all others.

It is fairly typical to provide your site-specific rez settings in a file that the environment variable REZ_CONFIG_FILE is then set to for all your users. Note that you do not need to provide a copy of all settings in this file - just provide those that are changed from the defaults.

You can use the rez-config command line tool to see what the current configured settings are. Called with no arguments, it prints all settings; if you specify an argument, it prints out just that setting:

]$ rez-config packages_path
- /home/sclaus/packages
- /home/sclaus/.rez/packages/int
- /home/sclaus/.rez/packages/ext

Configuration Settings

Following is an alphabetical list of rez settings. Note that this has been generated automatically from the rezconfig.py file in the rez source, so you can also refer to that file for the same information.

all_parent_variables

all_parent_variables = False

Rez's default behaviour is to overwrite variables on first reference. This prevents unconfigured software from being used within the resolved environment. For example, if PYTHONPATH were to be appended to and not overwritten, then python modules from the parent environment would be (incorrectly) accessible within the Rez environment.

"Parent variables" override this behaviour - they are appended/prepended to, rather than being overwritten. If you set "all_parent_variables" to true, then all variables are considered parent variables, and the value of "parent_variables" is ignored. Be aware that if you make variables such as PATH, PYTHONPATH or app plugin paths parent variables, you are exposing yourself to potentially incorrect behaviour within a resolved environment.

all_resetting_variables

all_resetting_variables = False

When two or more packages in a resolve attempt to set the same environment variable, Rez's default behaviour is to flag this as a conflict and abort the resolve. You can overcome this in a package's commands section by using the Rex command "resetenv" instead of "setenv". However, you can also turn off this behaviour globally - for certain variables, by adding them to "resetting_variables", and for all variables, by setting "all_resetting_variables" to true.

bind_module_path

bind_module_path = []

Search path for bind modules

browser

browser = None

The browser used to view documentation; the rez-help tool uses this On osx, set this to "open -a " if you want to use a specific app.

build_directory

build_directory = "build"

The default working directory for a package build, relative to the package source directory (this is typically where temporary build files are written).

build_thread_count

build_thread_count = "physical_cores"

The number of threads a build system should use, eg the make '-j' option. If the string values "logical_cores" or "physical_cores", it is set to the detected number of logical / physical cores on the host system. (Logical cores are the number of cores reported to the OS, physical are the number of actual hardware processor cores. They may differ if, ie, the CPUs support hyperthreading, in which case logical_cores == 2 * physical_cores). This setting is exposed as the environment variable $REZ_BUILD_THREAD_COUNT during builds.

cache_listdir

cache_listdir = True

Cache directory traversals

cache_package_files

cache_package_files = True

Cache package file reads

catch_rex_errors

catch_rex_errors = True

When an error is encountered in rex code, rez catches the error and processes it, removing internal info (such as the stacktrace inside rez itself) that is generally not interesting to the package author. If set to False, rex errors are left uncaught, which can be useful for debugging purposes.

color_enabled

color_enabled = (os.name == "posix")

Enables/disables colorization globally. Note: Turned off for Windows currently as there seems to be a problem with the Colorama module.

context_tmpdir

context_tmpdir = None

Where temporary files for contexts go. Defaults to appropriate path depending on your system - for example, *nix distributions will probably set this to "/tmp". This is separate to 'tmpdir' because you sometimes might want to set this to an NFS location - for example, perhaps rez is used during a render and you'd like to store these tempfiles in the farm queuer's designated tempdir so they're cleaned up when the render completes.

debug_all

debug_all = False

Turn on all debugging messages

debug_bind_modules

debug_bind_modules = False

Print debugging info in binding modules. Binding modules should print using the bind_utils.log() function - it is controlled with this setting

debug_file_loads

debug_file_loads = False

Print info whenever a file is loaded from disk.

debug_memcache

debug_memcache = False

Debug memcache usage. As well as printing debugging info to stdout,it also sends human-readable strings as memcached keys (that you can read by running "memcached -vv" as the server)

debug_none

debug_none = False

Turn off all debugging messages. This overrides debug_all.

debug_old_commands

debug_old_commands = False

Print old commands and their converted rex equivalent. Note that this can cause very verbose output.

debug_package_exclusions

debug_package_exclusions = False

Print packages that are excluded from the resolve, and the filter rule responsible.

debug_package_release

debug_package_release = False

Print debugging info such as VCS commands during package release

debug_plugins

debug_plugins = False

Print debugging info when loading plugins

debug_resolve_memcache

debug_resolve_memcache = False

Print debugging info related to use of memcached during a resolve

debug_resources

debug_resources = False

Print debugging info when searching and loading resources.

default_shell

default_shell = ""

The default shell type to use when creating resolved environments (eg when using rez-env, or calling ResolvedContext.execute_shell). If empty or null, the current shell is used (for eg, "bash").

difftool

difftool = None

The viewer used to view file diffs. On osx, set this to "open -a " if you want to use a specific app.

disable_rez_1_compatibility

disable_rez_1_compatibility = False

If True, override all compatibility-related settings so that Rez-1 support is deprecated. This means that:

• All warn/error settings in this section of the config will be set to warn=False, error=True;
• rez_1_environment_variables will be set to False.
• rez_1_cmake_variables will be set to False. You should aim to do this - it will mean your packages are more strictly validated, and you can more easily use future versions of Rez.

documentation_url

documentation_url = " http://nerdvegas.github.io/rez/"

Where Rez's own documentation is hosted

dot_image_format

dot_image_format = "png"

The default image format that dot-graphs are rendered to.

editor

editor = None

The editor used to get user input in some cases. On osx, set this to "open -a " if you want to use a specific app.

env_var_separators

env_var_separators = {
    "CMAKE_MODULE_PATH": ";",
    "DOXYGEN_TAGFILES": " ",
}

This setting can be used to override the separator used for environment variables that represent a list of items. By default, the value of os.pathsep will be used, unless the environment variable is list here, in which case the configured separator will be used.

error_commands2

error_commands2 = False

Warn or disallow an extra commands entry called "commands2". This is provided as a temporary measure for porting packages to rez-based commands without breaking compatibility with Rez-1. If "commands2" is present, it is used instead of "commands". Unlike "commands", "commands2" only allows new rex- style commands. Once you have fully deprecated Rez-1, you should stop using "commands2". TODO DEPRECATE

error_nonstring_version

error_nonstring_version = False

Warn or disallow when a package is found to contain a non-string version. This was possible in Rez-1 but was an oversight - versions could be integer or float, as well as string. When this occurs, the directory version number is used in preference.

error_old_commands

error_old_commands = False

Warn or disallow when a package is found to contain old rez-1-style commands.

error_package_name_mismatch

error_package_name_mismatch = False

Warn or disallow when a package contains a package name that does not match the name specified in the directory structure. When this occurs, the directory package name is used in preference.

error_version_mismatch

error_version_mismatch = False

Warn or disallow when a package contains a version number that does not match the version specified in the directory structure. When this occurs, the directory version number is used in preference.

image_viewer

image_viewer = None

The program used to view images by tools such as "rez-context -g" On osx, set this to "open -a " if you want to use a specific app.

implicit_packages

implicit_packages = [
    "~platform=={system.platform}",
    "~arch=={system.arch}",
    "~os=={system.os}",
]

Packages that are implicitly added to all package resolves, unless the --no-implicit flag is used.

local_packages_path

local_packages_path = "~/packages"

The path that Rez will locally install packages to when rez-build is used

max_package_changelog_chars

max_package_changelog_chars = 65536

If not zero, truncates all package changelog entries to this maximum length. You should set this value - changelogs can theoretically be very large, and this adversely impacts package load times.

memcached_context_file_min_compress_len

memcached_context_file_min_compress_len = 1

Bytecount beyond which memcached entries are compressed, for cached context files (aka .rxt files). Zero means never compress.

memcached_listdir_min_compress_len

memcached_listdir_min_compress_len = 16384

Bytecount beyond which memcached entries are compressed, for directory listings. Zero means never compress.

memcached_package_file_min_compress_len

memcached_package_file_min_compress_len = 16384

Bytecount beyond which memcached entries are compressed, for cached package files (such as package.yaml, package.py). Zero means never compress.

memcached_resolve_min_compress_len

memcached_resolve_min_compress_len = 1

Bytecount beyond which memcached entries are compressed, for resolves. Zero means never compress.

memcached_uri

memcached_uri = []

Uris of running memcached server(s) to use as a file and resolve cache. For example, the uri "127.0.0.1:11211" points to memcached running on localhost on its default port. Must be either null, or a list of strings.

new_session_popen_args

new_session_popen_args = None

subprocess.Popen arguments to use in order to execute a shell in a new process group (see ResolvedContext.execute_shell, 'start_new_session'). Dict of (Popen argument, value).

package_commands_sourced_first

package_commands_sourced_first = True

Defines when package commands are sourced during the startup sequence of an interactive shell. If True, package commands are sourced before startup scripts (such as .bashrc). If False, package commands are sourced after.

package_filter

package_filter = None

Package filter. One or more filters can be listed, each with a list of exclusion and inclusion rules. These filters are applied to each package during a resolve, and if any filter excludes a package, that package is not included in the resolve. Here is a simple example:

package_filter:
    excludes:
    - glob(*.beta)
    includes:
    - glob(foo-*)

This is an example of a single filter with one exclusion rule and one inclusion rule. The filter will ignore all packages with versions ending in '.beta', except for package 'foo' (which it will accept all versions of). A filter will only exclude a package iff that package matches at least one exclusion rule, and does not match any inclusion rule.

Here is another example, which excludes all beta packages, and all packages except 'foo' that are released after a certain date. Note that in order to use multiple filters, you need to supply a list of dicts, rather than just a dict:

package_filter:
- excludes:
  - glob(*.beta)
- excludes:
  - after(1429830188)
  includes:
  - foo  # same as range(foo), same as glob(foo-*)

This example shows why multiple filters are supported - with only one filter, it would not be possible to exclude all beta packages (including foo), but also exclude all packages after a certain date, except for foo.

Following are examples of all the possible rules:

example	description
glob(*.beta)	Matches packages matching the glob pattern.
regex(.*-\.beta)	Matches packages matching re-style regex.
requirement(foo-5+)	Matches packages within the given requirement.
before(1429830188)	Matches packages released before the given date.
after(1429830188)	Matches packages released after the given date.
*.beta	Same as glob(*.beta)
foo-5+	Same as range(foo-5+)

packages_path

packages_path = [
    "~/packages",           # locally installed pkgs, not yet deployed
    "~/.rez/packages/int",  # internally developed pkgs, deployed
    "~/.rez/packages/ext",  # external (3rd party) pkgs, such as houdini, boost
]

The package search path. Rez uses this to find packages. A package with the same name and version in an earlier path takes precedence.

parent_variables

parent_variables = []
all_parent_variables = False

Rez's default behaviour is to overwrite variables on first reference. This prevents unconfigured software from being used within the resolved environment. For example, if PYTHONPATH were to be appended to and not overwritten, then python modules from the parent environment would be (incorrectly) accessible within the Rez environment.

"Parent variables" override this behaviour - they are appended/prepended to, rather than being overwritten. If you set "all_parent_variables" to true, then all variables are considered parent variables, and the value of "parent_variables" is ignored. Be aware that if you make variables such as PATH, PYTHONPATH or app plugin paths parent variables, you are exposing yourself to potentially incorrect behaviour within a resolved environment.

plugin_path

plugin_path = []

Search path for plugins

prefix_prompt

prefix_prompt = True

If true, prefixes the prompt, suffixes if false. Ignored if 'set_prompt' is false.

prune_failed_graph

prune_failed_graph = True

If true, then when a resolve graph is generated during a failed solve, packages unrelated to the failure are pruned from the graph. An "unrelated" package is one that is not a dependency ancestor of any packages directly involved in the failure.

quiet

quiet = False

Suppress all extraneous output - warnings, debug messages, progress indicators and so on. Overrides all warn_xxx and debug_xxx settings.

release_hooks

release_hooks = []

The release hooks to run when a release occurs. Release hooks are plugins - if a plugin listed here is not present, a warning message is printed. Note that a release hook plugin being loaded does not mean it will run - it needs to be listed here as well. Several built-in release hooks are available, see rezplugins/release_hook.

release_packages_path

release_packages_path = "~/.rez/packages/int"

The path that Rez will deploy packages to when rez-release is used. For production use, you will probably want to change this to a site-wide location.

resetting_variables

resetting_variables = []
all_resetting_variables = False

When two or more packages in a resolve attempt to set the same environment variable, Rez's default behaviour is to flag this as a conflict and abort the resolve. You can overcome this in a package's commands section by using the Rex command "resetenv" instead of "setenv". However, you can also turn off this behaviour globally - for certain variables, by adding them to "resetting_variables", and for all variables, by setting "all_resetting_variables" to true.

resolve_caching

resolve_caching = True

Use available caching mechanisms to speed up resolves when applicable.

resource_caching_maxsize

resource_caching_maxsize = -1

The size of the local (in-process) resource cache. Resources include package families, packages and variants. A value of 0 disables caching; -1 sets a cache of unlimited size. The size refers to the number of entries, not byte count.

rez_1_cmake_variables

rez_1_cmake_variables = True

If True, Rez will continue to generate the given CMake variables at build and release time, even though their use has been deprecated in Rez-2. The variables in question, and their Rez-2 equivalent (if any) are: REZ-1 REZ-2

---

CENTRAL REZ_BUILD_TYPE

rez_1_environment_variables

rez_1_environment_variables = True

If True, Rez will continue to generate the given environment variables in resolved environments, even though their use has been deprecated in Rez-2. The variables in question, and their Rez-2 equivalent (if any) are: REZ-1 REZ-2

---

REZ_REQUEST REZ_USED_REQUEST REZ_RESOLVE REZ_USED_RESOLVE REZ_VERSION REZ_USED_VERSION REZ_PATH REZ_USED REZ_RESOLVE_MODE not set REZ_RAW_REQUEST not set REZ_IN_REZ_RELEASE not set

rez_tools_visibility

rez_tools_visibility = "append"

Defines how Rez's command line tools are added back to PATH within a resolved environment. Valid values are:

• "append": Rez tools are appended to PATH (default);
• "prepend": Rez tools are prepended to PATH;
• "never": Rez tools are not added back to PATH - rez will not be available within resolved shells.

rxt_as_yaml

rxt_as_yaml = True

If this is true, rxt files are written in yaml format. If false, they are written in json, which is a LOT faster. You would only set to true for backwards compatibility reasons. Note that rez will detect either format on rxt file load.

set_prompt

set_prompt = True

If true, tools such as rez-env will update the prompt when moving into a new resolved shell. Prompt nerds might do fancy things with their prompt that Rez can't deal with (but it can deal with a lot - colors etc - so try it first). By setting this to false, Rez will not change the prompt. Instead, you will probably want to set it yourself in your startup script (.bashrc etc). You will probably want to use the environment variable $REZ_ENV_PROMPT, which contains the set of characters that are normally prefixed/suffixed to the prompt, ie '>', '>>' etc.

show_progress

show_progress = True

Show progress bars where applicable

suite_alias_prefix_char

suite_alias_prefix_char = "+"

The prefix character used to pass rez-specific commandline arguments to alias scripts in a suite. This must be a character other than "-", so that it doesn"t clash with the wrapped tools" own commandline arguments.

suite_visibility

suite_visibility = "always"

Defines what suites on $PATH stay visible when a new rez environment is resolved. Possible values are:

• "never": Don"t attempt to keep any suites visible in a new env
• "always": Keep suites visible in any new env
• "parent": Keep only the parent suite of a tool visible
• "parent_priority": Keep all suites visible and the parent takes precedence

terminal_emulator_command

terminal_emulator_command = None

The command to use to launch a new Rez environment in a separate terminal (this is enabled using rez-env's "detached" option). If None, it is detected.

tmpdir

tmpdir = None

Where temporary files go. Defaults to appropriate path depending on your system - for example, *nix distributions will probably set this to "/tmp". It is highly recommended that this be set to local storage, such as /tmp.

variant_select_mode

variant_select_mode = "version_priority"

Variant select mode. This determines which variants in a package are preferred during a solve. Valid options are:

• version_priority: Prefer variants that contain higher versions of packages present in the request;
• intersection_priority: Prefer variants that contain the most number of packages that are present in the request.

warn_all

warn_all = False

Turn on all warnings

warn_commands2

warn_commands2 = False
error_commands2 = False

Warn or disallow an extra commands entry called "commands2". This is provided as a temporary measure for porting packages to rez-based commands without breaking compatibility with Rez-1. If "commands2" is present, it is used instead of "commands". Unlike "commands", "commands2" only allows new rex- style commands. Once you have fully deprecated Rez-1, you should stop using "commands2". TODO DEPRECATE

warn_none

warn_none = False

Turn off all warnings. This overrides warn_all.

warn_nonstring_version

warn_nonstring_version = True
error_nonstring_version = False

Warn or disallow when a package is found to contain a non-string version. This was possible in Rez-1 but was an oversight - versions could be integer or float, as well as string. When this occurs, the directory version number is used in preference.

warn_old_commands

warn_old_commands = True
error_old_commands = False

Warn or disallow when a package is found to contain old rez-1-style commands.

warn_package_name_mismatch

warn_package_name_mismatch = True
error_package_name_mismatch = False

Warn or disallow when a package contains a package name that does not match the name specified in the directory structure. When this occurs, the directory package name is used in preference.

warn_shell_startup

warn_shell_startup = False

If true, print warnings associated with shell startup sequence, when using tools such as rez-env. For example, if the target shell type is "sh", and the "rcfile" param is used, you would get a warning, because the sh shell does not support rcfile.

warn_untimestamped

warn_untimestamped = False

If true, print a warning when an untimestamped package is found.

warn_version_mismatch

warn_version_mismatch = True
error_version_mismatch = False

Warn or disallow when a package contains a version number that does not match the version specified in the directory structure. When this occurs, the directory version number is used in preference.