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

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.

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:

  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:

  @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

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:

@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.

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

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

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.