loonghao/rez

Rez's two independent caches — the memcached-backed resolve cache and the on-disk package payload cache — the five settings that turn each one on, what invalidates an entry and what silently does not, rez-memcache and rez-pkg-cache for inspecting and flushing them, and the decision tree for 'I changed the package and nothing took effect'. Use when a resolve is slow, when a package change appears to be ignored, or when you need to prove a stale cache is or is not the cause. Covers Rez 3.4.0.

Rez command-line reference — rez-env, rez-build, rez-release, rez-context, rez-search, rez-depends, rez-test, rez-config, rez-bind, rez-pip and the rest, with the flags that matter. Use when the user needs the right rez command or flag, or when running a build/release/test loop. Covers Rez 3.4.0.

Rez configuration layering and the plugin system — config precedence and merge rules, string expansion, DelayLoad, key settings (packages_path, implicit_packages, caching, package_filter), and the seven plugin types with their discovery mechanisms and entry points. Use when the user asks how to configure rez, why a setting is not taking effect, or how to write or install a plugin. Covers Rez 3.4.0.

Rez core concepts — packages, versions, requests, repositories, the package search path, implicit packages and variants. Use when the user asks what Rez is, how package versions or requests work, where Rez finds packages, why a resolve picked a certain version, or when a project contains package.py files. Covers Rez 3.4.0.

Rules and decision-making for authoring Rez packages — how to split versions and variants, how to write requires/variants/build_requires/commands, how wide to make dependency ranges, the rez-build and rez-release workflow and conventions, and the recurring pitfalls and anti-patterns. Use when writing, reviewing or restructuring a package.py, or when deciding whether a change needs a new version or a new variant. Covers Rez 3.4.0.

Writing the Rez commands() section and rex environment API — env object, setenv/appendenv/prependenv/unsetenv/alias/source/error, string expansion, literal/expandable/expandvars, execution order and build-time branching. Use when a package must set, append or prepend environment variables, expose tools, source scripts, or behave differently during a build. Covers Rez 3.4.0.

Authoring Rez package.py files — standard attributes, early/late binding functions, requires/variants/build_requires, string expansion and package overrides. Use when writing, reviewing or debugging a package definition file, or when the user asks how to declare dependencies, variants, tools or build-time requirements. Covers Rez 3.4.0.

How rez decides which version of a package to pick — the package_orderers setting, the five built-in orderers sorted / version_split / per_family / soft_timestamp / no_order, how orderers apply to variants as well as packages, writing and registering a custom orderer, and how to prove an orderer is or is not what changed your resolve. Use when rez picks a version you did not expect and the resolve is not failing, or when a studio needs python-2-style version pinning to survive an upgrade. Covers Rez 3.4.0.

The package.py execution model and the errors it produces — why a top-level from x import SomeClass makes the installed package.py unparseable, why module-scope values are frozen on the build machine, why env/this/root look undefined to linters, and why a failed rez-build can leave a broken install behind. Use when a package resolves or builds with a confusing error, when reviewing a package.py for module-scope mistakes, or before releasing one. Covers Rez 3.4.0.

Converting pip packages into rez packages — rez-pip usage, install vs release vs custom prefix, choosing and pinning the python version, how rez-pip picks which pip to run, the python-MAJOR.MINOR dependency it writes, extra pip arguments, the pip_install_package API and InstallMode, and the failures that account for most broken conversions. Use when the user wants a PyPI package available as a rez package, or asks why a converted package will not resolve. Covers Rez 3.4.0.

Rez Python API — ResolvedContext construction and inspection, Package/Variant objects, programmatic resolves, .rxt context serialisation and deserialisation, running commands inside a context, and the module entry points (rez.resolved_context, rez.packages, rez.config, rez.pip, rez.suite, rez.bundle_context). Use when the user wants to drive rez from Python instead of the CLI, or asks what a context object actually holds. Covers Rez 3.4.0.

Rez resolve and solver internals — how the solver works, reading -v debug output, conflicts, cycles and total reductions, graph inspection, patching, caching and timestamps. Use when the user asks how the solver works or how to read its -v output. For a resolve that already failed and needs attributing, use rez-resolve-troubleshooting. Covers Rez 3.4.0.

Diagnosing Rez resolve failures — a command-by-command triage path for 'The context failed to resolve', package conflicts, request version conflicts, implicit package failures, variant selection failures, missing packages or versions, filtered or ignored packages, and stale resolve caches. Use when rez-env, rez-build or rez-test fails to resolve and you need to find the culprit, not just read the solver. Covers Rez 3.4.0.

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.

Declaring and running tests from a package definition — the tests attribute and its command / requires / run_on / on_variants fields, why a bare rez-test runs only tests tagged default, every rez-test flag, how the exit code is derived, and how to drive package tests from CI. Use when a package needs tests, when rez-test runs fewer tests than you declared, or when you are wiring rez package tests into a pipeline. Covers Rez 3.4.0.

Running rez on Windows — why only cmd, gitbash, powershell and pwsh are registered there and how the default is picked, the path-separator trap where cmd and pwsh join with ';' while gitbash joins with ':', backslash versus forward slash in generated shell code, the 260-character MAX_PATH limit and why variant install paths exceed it, the platform/arch/os implicit packages, using rez-interpret as a cross-shell oracle without launching a shell, install and config-file layout, and CI differences. Use when a package or resolve behaves differently on Windows, when porting a package across operating systems, when a deep path fails to read or write, or when a one-liner works in bash and fails in cmd. Covers Rez 3.4.0.