rez-suites-bundles

Rez suites and context bundles — rez-suite to expose tools from several contexts behind one PATH entry, suite tool aliasing, prefixing, hiding, bumping and control arguments (++help, ++about, ++patch, ++peek), and rez-bundle / bundle_context() to package a resolve with its packages into a relocatable directory. Use when the user wants to ship a resolved environment to artists, a render farm, a container or another machine. Covers Rez 3.4.0.

Rez suites and context bundles

One-sentence summary: a suite is a directory of contexts plus wrapper scripts that makes tools from different resolves look like one PATH entry; a context bundle is a directory that carries the context and its packages, so the whole thing can be moved somewhere else.

Skill scope: delivering a resolve to somewhere other than your own shell. For the resolve itself see rez-resolve; for the objects these commands are built on see rez-python-api; for the command reference see rez-cli.

Which one do I want?

	Suite	Context bundle
Holds	contexts + wrapper scripts	one context + its packages
Packages stay where they are	yes — absolute refs to shared repos	no — copied into the bundle, refs become relative
Relocatable	no	yes
Typical use	artist workstations, PATH entry	farm, container, server, air-gapped copy
Built by	rez-suite	rez-bundle

Suites

A suite is a directory containing a set of contexts and wrapper scripts that run tools within those contexts. Put its bin directory on PATH and foo resolves to the wrapper, which resolves to the right context — the artist never has to know.

Building one

bash

rez-env foo -o foo.rxt
rez-suite --create mysuite
rez-suite --add foo.rxt --context fooCtx mysuite
export PATH=$PWD/mysuite/bin:$PATH

--add copies the context into mysuite/contexts/<name>.rxt, and --context is the label it gets inside the suite. The label is what every other context-scoped option refers to, so name it after what the context is for, not after the file you happened to save it as.

rez-suite flags

Flag	Effect
--create	create an empty suite at DIR
-a, --add RXT	add a context to the suite (needs --context)
-c, --context NAME	which context a context-scoped option applies to
-r, --remove NAME	remove a context
-d, --description DESC	set a context's description
-p, --prefix PREFIX / -s, --suffix SUFFIX	prefix/suffix every tool in the context
--hide TOOL / --unhide TOOL	hide or expose one tool
--alias TOOL ALIAS / --unalias TOOL	give one tool a different name
-b, --bump NAME	raise a context's priority so its tools win
-P, --prefix-char CHAR	change the control-argument prefix (default +; "" disables)
-t, --tools	list the tools the suite exposes
--which TOOL	print the path of a suite wrapper
-l, --list	list visible suites
--validate	check the suite is internally consistent
--find-request PKG / --find-resolve PKG	which contexts contain PKG in the request / the resolve
-i, --interactive	open a shell in a suite context (needs --context)

Which tools get exposed

A suite exposes the tools attribute of the packages in a context's requests. Three rules follow from that, and they explain most "my tool is missing" reports:

• Packages pulled in as dependencies do not expose their tools.
• Weak references (~foo-1) and conflict requests (!foo) do not expose their tools.
• If two contexts expose the same tool name, one is a conflict; --bump, aliasing or prefixing resolves it.

Prefixing and suffixing are the cheap way to offer the same tool from two contexts at once:

bash

rez-suite --add foo2017.rxt --context foo2017 mysuite
rez-suite --suffix _beta --context foo2017 mysuite
rez-suite --tools mysuite

That gives you foo from the stable context and foo_beta from the new one.

Control arguments

Suite wrappers pass their arguments through to the real tool, except for rez's own control arguments, which use + instead of -:

bash

foo ++help
foo ++about
foo ++versions
foo +i
foo +p bar-2
foo ++peek
foo ++command 'printenv FOO_VERSION'
foo ++no-rez-args --not-a-rez-flag

Control arg	Meaning
+h, ++help	wrapper usage
+a, ++about	which suite, context and package the wrapper comes from
++versions	versions of the package providing the tool
+i, ++interactive	interactive shell in the tool's environment
+p, ++patch PKG...	run the tool in a patched environment
++strict	strict patching (ignored without ++patch)
++nl, ++no-local	do not load local packages when patching
++command, ++stdin	run commands instead of the tool
++peek	diff the tool's context against a re-resolve — how stale it is
++verbose, ++quiet	output control
++no-rez-args	pass everything through, even + args

If a target tool uses + for its own arguments, change rez's prefix with --prefix-char.

The Suite object

python

from rez.suite import Suite
from rez.resolved_context import ResolvedContext

suite = Suite()
suite.add_context(name="fooCtx", context=ResolvedContext.load("foo.rxt"))
suite.save("mysuite")

reloaded = Suite.load("mysuite")
reloaded.context_names                 # ['fooCtx']
reloaded.set_context_suffix("fooCtx", "_beta")
reloaded.validate()                    # raises rez.exceptions.SuiteError when broken

context_names lists the labels, tools_path is the bin directory to put on PATH, get_tools() is the alias-to-tool mapping, and Suite.print_info() dumps the whole thing.

Context bundles

A context bundle is a directory holding a context and a package repository containing every package the context uses. Package references in the .rxt become relative, which is what makes the bundle relocatable — copy it to a server, a container or a USB stick and nothing points back at your shared storage.

bash

rez-env foo -o foo.rxt
rez-bundle foo.rxt ./mybundle

The result:

text

.../mybundle/
   ./context.rxt
   ./packages/
      <standard package repository layout>

Run something out of it by pointing rez-env at the bundled context:

bash

rez-env -i ./mybundle/context.rxt -- foo-tool

rez-bundle flags

Flag	Effect
-s, --skip-non-relocatable	leave non-relocatable packages where they are instead of failing
-f, --force	bundle anyway, even when a package says it cannot be relocated
-n, --no-lib-patch	skip the library-patching step
-v, --verbose	verbose mode

-s, -f and -n all sit in one mutually exclusive group: pass at most one of them.

Library patching

A compiled library inside a package can carry an absolute rpath/runpath to a library in another package, which would silently resolve outside the bundle. Bundling rewrites those references to $ORIGIN-relative paths pointing at the copy inside the bundle, and the step is platform-specific (linux rewrites ELF headers with patchelf). References that have no equivalent inside the bundle — a system library, say — are left alone, which is why a bundle is rarely completely hermetic.

The bundle API

python

from rez.bundle_context import bundle_context
from rez.resolved_context import ResolvedContext

context = ResolvedContext(["foo-1"])
bundle_context(context, "./mybundle", force=True)

bundle_context(context, dest_dir, force=False, skip_non_relocatable=False, quiet=False, patch_libs=False, verbose=False) is the same operation as rez-bundle; note that the CLI passes patch_libs=True unless you give it --no-lib-patch, while the API default is off.

Troubleshooting

Symptom	Check
A tool is missing from the suite	was it in the request? dependencies and weak refs expose nothing
Two tools fight	rez-suite --tools; fix with --bump, --alias or --prefix/--suffix
Wrappers ignore your suite after an edit	re-run rez-suite --validate; wrappers are regenerated on save
The tool uses + itself	rez-suite --prefix-char
rez-bundle refuses a package	relocatable is off; decide between -s (skip it) and -f (force it)
A bundled tool loads a library from outside	library patching; check the platform and drop -n
Bundle works here, not there	the bundle is only as portable as its payloads; check --validate and --peek

Agent workflow

1. Decide first: shared disk and many tools means a suite; anywhere-but-here means a bundle.
2. For a suite, build the contexts with rez-env ... -o, then add them one at a time with rez-suite --add ... --context <name>.
3. Confirm exposure with rez-suite --tools before telling anyone to put bin on PATH.
4. For a bundle, resolve, bundle, then run the bundled context — a bundle you have not executed is a guess.
5. Re-check both with rez-suite --validate and rez-context context.rxt --so after a package changes.