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?

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

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

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:

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 -:

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

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

The Suite object

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.

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

The result:

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

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

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

rez-bundle flags

-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

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

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.