rez-package-authoring

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.

Rez package authoring rules

One-sentence summary: package.py is a declaration of what a package needs and provides — decide the version/variant split first, then keep requirement ranges as wide as the truth allows and as narrow as reality demands.

Skill scope: how to decide and structure a package. For the attribute reference and @early/@late mechanics see rez-package-definition; for the commands() body and rex API see rez-package-commands; for build/release command flags see rez-cli; for what rez does to the module scope of package.py — serialization, build-time freezing and the errors that follow — see rez-package-pitfalls.

The three decisions, in order

Get these right and the file writes itself.

1. Is this a new version or a new variant? — something about the package changed vs. something about its dependencies changed.
2. How wide is each dependency range? — what the package genuinely works with, not what it happened to be built against.
3. What is build-time vs. runtime? — which requirements survive into the installed package.

Decision 1 — new version or new variant?

The change	Do this
Your own source code changed	new version
A dependency version it must build against changed (maya 2016 → 2017, python 2 → 3)	new variant
Need to support a second platform/arch/os	new variant
Fixing a bug in the payload	new version

The rule that catches people out: variants cannot be added to a package that has none without bumping the version. A package released with no variants at all can never gain them. So if a compiled package plausibly needs variants later — a second python, a second DCC — declare the single variant now:

python

name = "my_utils"

variants = [
    ["python-2.7"],
]

This is the "future proofing" reason for single-variant packages. The second common reason is cosmetic but real: variant requirements appear in the install path, so my_utils/1.0.0/python-2.7/<payload> tells a user what they are getting, where my_utils/1.0.0/<payload> does not.

Variants are per-version, not per-package. Adding a variant means re-releasing that version; it does not retroactively change already-released versions.

Decision 2 — how wide should a range be?

Start from the truth about compatibility, then express it with the narrowest syntax that still says it.

You mean	Write
any version	foo
any 1.x	foo-1
1.0.0 or newer	foo-1+
at least 1.2, below 2	foo-1.2+<2
exactly 2.0.0, nothing else	foo==2.0.0
1.3 or 5+, but not between	foo-1.3|5+
if present it must be in range, but don't require it	~foo-2.7.3
this version is unacceptable	!foo-2015.6

Three rules for sound ranges:

• Do not pin what you do not have to pin. python==2.7.11 forces every environment that uses your package onto that exact build; python-2.7 lets rez co-exist with everything else. Pin only when there is a concrete incompatibility.

• Do not widen past what you tested. A range is a promise. foo-1+ claims you work with every future foo-1.

• Build time can be wider than runtime. This is what requirements expansion is for. A C++ package may build against any boost-1 but must link at runtime against the minor version it was built with. Write the loose range and let rez expand it:

  python

  requires = [
      "boost-1.*",      # expands to the version actually built against, e.g. boost-1.55
  ]
  

  ** expands to the full version (boost-1.** → boost-1.55.1). The equivalent done by hand:

  python

  @early()
  def requires():
      from rez.package_py_utils import expand_requires
      return expand_requires(["boost-1.*"])
  

• Use ~ (weak reference) when you constrain but do not require. DCCs that ship an embedded python should declare requires = ["~python-2.7.3"]: python is not pulled into the environment, but if something else brings python in, it has to be the compatible one. This is how a studio keeps python libraries usable both inside and outside the DCC.

Decision 3 — runtime vs. build time

Attribute	Puts into the environment at	Transitive?
requires	runtime and build	yes
build_requires	build only	yes — collects from every package in the build env
private_build_requires	build only	no — only from the package being built
variants	build (one variant at a time) and runtime (the selected variant)	n/a

Choose build_requires when other packages also need the dependency to build against your headers — a header-only C++ library is the canonical case: if your public headers include its headers, anyone compiling against you needs it too. Choose private_build_requires for things nobody downstream needs: doc generators (doxygen, sphinx), build utilities, statically linked libraries.

The build environment is assembled in a fixed order — requires, then transitive build_requires, then private_build_requires, then the current variant's requirements.

A subtle trap with building: early-bound functions are evaluated more than once per build — once pre-build, and once per variant — and the pre-build value (where building is False) is the one baked into the installed package. So to add a requirement at runtime only:

python

@early()
def requires():
    if building:
        return ["python-2"]
    else:
        return ["runtimeonly-1.2", "python-2"]

Always check the function returns what you want when building is False.

Writing commands()

Rez is not a build system and does not know how your package is consumed. commands() is where you say it. Keep it declarative — remember it is interpreted into shell code, not executed as Python.

python

def commands():
    env.PATH.append("{root}/bin")
    env.PYTHONPATH.append("{root}/python")

    if building:
        env.CMAKE_MODULE_PATH.append("{root}/cmake")

Rules:

• Put build information behind if building: so consumers find headers and CMake config at build time without polluting the runtime environment.
• commands() never runs for the package being built. Use pre_build_commands() for that.
• Expose tools with tools, not by hand-managing PATH, so rez-context --tools and the tool conflict detection work.
• Keep it cheap. Anything that can be computed once should be an @early() attribute; use @late() only for values that genuinely depend on runtime state (env vars, user role).

The build/release loop

bash

rez-build --install                    # build all variants, install to ~/packages
rez-env mypackage                      # resolve and test in a separate shell
rez-test mypackage                     # run the package's tests
rez-release                            # build + release_hooks + VCS plugins + tag

Conventions worth following:

• Local first, release when ready. rez-build --install goes to local_packages_path (typically ~/packages), which sits at the front of packages_path, so your local package shadows the released one. That is the intended test loop — and also the reason --no-local exists when a local build is masking a released one.
• Use --prefix to install somewhere else, for example rez-build -i --prefix /path/to/repo. rez-release is the managed alternative: it targets release_packages_path, runs release_hooks, runs tests, does sanity checks and VCS tagging, and adds the release package attributes automatically.
• Inspect before you build. rez-build --view-pre prints the preprocessed package and exits — the fastest way to see what preprocess() and @early() actually produced.
• Build one variant while iterating: rez-build --variants 0.
• Pass build-system args after --: rez-build -- -DMYVAR=YES.
• Do not re-resolve a test shell unnecessarily — if requirements have not changed, the existing environment is still valid.

Pitfalls and anti-patterns

Anti-pattern	Why it breaks	Do instead
foo==1.2.3 on every dependency	over-constrains every downstream resolve	range it: foo-1.2+<2, pin only real incompatibilities
No variants on a package that will need them	variants cannot be added later without a version bump	declare one variant now
Non-mutually-exclusive variants, relying on the pick	rez cannot compare versions across packages; the choice is a preference, and a transitive dep can overrule it	put the discriminator in the request, e.g. rez-env pkg maya
Heavy work in @late()	runs at resolve/runtime, on every use	compute at build time in @early(), keep @late() for genuine runtime state
Imports at the top of package.py for @late()	late functions must import inside the function	import inside the function body
Referencing other @early()/@late() attributes from an @early() function	raises an error	reference plain attributes only, via this
Expecting commands() to run during your own build	it never runs for the package being built	use pre_build_commands()
Referencing files by relative path in commands()	cwd during a build is the build path, not the package root	use {root}
Editing a released package in place	breaks timestamped resolves and returns stale cached resolves	release a new version
Setting env vars for build consumers unconditionally	pollutes runtime	guard with if building:
Skipping tools and appending to PATH by hand	loses tool tracking and conflict detection	use the tools attribute

For the ones that produce a rez error rather than a bad decision — top-level imports that make the installed package.py unparseable, values frozen on the build machine — see rez-package-pitfalls, which carries the verbatim error text.

Review checklist

Before releasing, check in this order:

1. Does every range say what the package actually supports — not wider, not narrower?
2. Does the package need variants now, so it can gain more later without a version bump?
3. Are build-only dependencies in build_requires / private_build_requires, and is the transitive one the right choice?
4. Does every @early() function return the right value when building is False?
5. Is build information in commands() guarded by if building:?
6. Does rez-build --view-pre show the package you intended?
7. Did rez-test pass before rez-release?

Agent workflow

1. Read the existing package.py and rez-build --view-pre output before editing anything.
2. Classify the requested change against decision 1 — version or variant — before touching requires.
3. Widen or narrow each range deliberately; never copy a range from another package without checking it means the same thing.
4. Prefer ~ and ! over hard requirements when you are constraining rather than requiring.
5. Validate with rez-build --view-pre, then rez-build --install, then rez-env in a separate shell — cheapest check first.
6. Run rez-test before rez-release.