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
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
Here is an example showing how to override settings using your own configuration file:
]$ echo 'packages_path = ["~/packages", "/packages"]' > myrezconfig.py
]$ export REZ_CONFIG_FILE=${PWD}/myrezconfig.py
]$ rez-config packages_path
- /home/sclaus/packages
- /packages
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 = 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 = 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 = []
Search path for bind modules
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"
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 = "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 = True
Cache directory traversals
cache_package_files = True
Cache package file reads
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 = (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 = 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 = False
Turn on all debugging messages
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 = False
Print info whenever a file is loaded from disk.
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 = False
Turn off all debugging messages. This overrides debug_all.
debug_old_commands = False
Print old commands and their converted rex equivalent. Note that this can cause very verbose output.
debug_package_exclusions = False
Print packages that are excluded from the resolve, and the filter rule responsible.
debug_package_release = False
Print debugging info such as VCS commands during package release
debug_plugins = False
Print debugging info when loading plugins
debug_resolve_memcache = False
Print debugging info related to use of memcached during a resolve
debug_resources = False
Print debugging info when searching and loading resources.
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 = 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 = 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 = " http://nerdvegas.github.io/rez/"
Where Rez's own documentation is hosted
dot_image_format = "png"
The default image format that dot-graphs are rendered to.
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 = {
"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 = 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 = 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 = False
Warn or disallow when a package is found to contain old rez-1-style commands.
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 = 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 = 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 = [
"~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 = "~/packages"
The path that Rez will locally install packages to when rez-build is used
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 = 1
Bytecount beyond which memcached entries are compressed, for cached context files (aka .rxt files). Zero means never compress.
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 = 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 = 1
Bytecount beyond which memcached entries are compressed, for resolves. Zero means never compress.
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 = 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 = 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 = 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", # 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 = []
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 = []
Search path for plugins
prefix_prompt = True
If true, prefixes the prompt, suffixes if false. Ignored if 'set_prompt' is false.
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 = False
Suppress all extraneous output - warnings, debug messages, progress indicators and so on. Overrides all warn_xxx and debug_xxx settings.
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 = "~/.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 = []
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 = True
Use available caching mechanisms to speed up resolves when applicable.
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 = 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 = 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 = "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 = 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 = 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 = True
Show progress bars where applicable
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 = "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 = 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 = 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 = "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 = False
Turn on all warnings
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 = False
Turn off all warnings. This overrides warn_all.
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 = True
error_old_commands = False
Warn or disallow when a package is found to contain old rez-1-style commands.
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 = 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 = False
If true, print a warning when an untimestamped package is found.
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.
Reproducible software environments
for Windows, Linux and MacOS, written in and for Python
Feel free to edit this wiki
Guides
Table of Contents
- Home
- Getting Started
- Basic Concepts
- Shells
- Patch
- Configuring Rez
- Package Commands
- Package Definition Guide
- Variants
- Contexts
- Suites
- Building Packages
- Environment Variables
- Releasing Packages
- Rez GUI
- Command Line Tools
- Glossary
- Misc
Todo