rez-package-definition

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.

Rez package definition (package.py)

One-sentence summary: every variable in package.py becomes an attribute of the package; requires declares dependencies and commands() configures the runtime environment.

Skill scope: the definition file itself. For the commands() body see rez-package-commands; for requests/version syntax see rez-core-concepts; for builds see rez-cli. For the decisions behind versions, variants, range width and the build/release loop see rez-package-authoring.

Minimal package

python

name = "sequence"

version = "2.1.2"

description = "Sequence detection library."

authors = ["ajohns"]

tools = ["lsq", "cpq"]

requires = ["python-2.6+<3", "argparse"]

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

uuid = "6c43d533-92bb-4f8b-b812-7020bf54d3f1"

The file lives at the root of each package install: /packages/inhouse/foo/1.0.0/package.py.

What becomes a package attribute

Every module-level variable becomes an attribute — including custom ones. These do not:

• Python modules (import sys does not create a sys attribute);
• plain functions (except commands, @early and @late functions);
• names with a leading double underscore;
• any build-only attribute.

That list is exactly as wide as it reads, and no wider. A class is not a module and not a function, so from pathlib import Path at module scope does create a Path attribute — and it is serialized into the installed package.py as Path = <class 'pathlib.Path'>, which no longer parses. Same for a class defined in the file and for any object instance. Values derived from a stripped module survive too: sys_path = sys.prefix is kept, frozen on the build machine. See rez-package-pitfalls for the errors and the correct form.

Standard attributes

Attribute	Type	Purpose
name	str	package name (required)
version	str	version (required)
description	str	general description, no version details
authors	list[str]	ordered, major contributor first
requires	list[str]	runtime dependencies
build_requires	list[str]	build-time deps, transitive
private_build_requires	list[str]	build-time deps, not transitive
tools	list[str]	entry points exposed into the environment
variants	list[list[str]]	variant definitions (see rez-core-concepts)
hashed_variants	bool	install variants under a hash
commands()	function	runtime environment configuration
uuid	str	stable identity across renames
has_plugins / plugin_for	bool / str	plugin discovery via rez-plugins
cachable	bool	allow package caching
config	dict	override rez settings during build/release

Arbitrary custom attributes are allowed and are often the cleanest way to pass build-computed data to commands().

requires vs build_requires vs private_build_requires

The build environment requirement list is assembled in this order:

1. requires
2. build_requires — transitive: build requirements of all packages in the env are included
3. private_build_requires — not transitive
4. the current variant's requirements

Use private_build_requires for doc generators (doxygen, sphinx), build utilities and statically linked libraries. Use build_requires for header-only C++ libraries, where consumers of your headers also need the header at build time.

Early binding functions (@early)

Evaluated at build time; the returned value is baked into the installed package.py.

python

@early()
def authors():
    import subprocess
    p = subprocess.Popen("git shortlog -sn | cut -f2",
                         shell=True, stdout=subprocess.PIPE)
    out, _ = p.communicate()
    return out.strip().split("\n")

Rules and gotchas:

• Only package attributes are visible — the implicit this object exposes package attributes only.
• No rez environment variables are accessible.
• Do not reference other @early or @late attributes — an error is raised.
• CWD during evaluation is the directory containing your package.py.
• @early functions are evaluated multiple times: once pre-build and once per variant. The pre-build value (with building == False) is what lands in the installed package.
• Therefore: make sure the function returns the runtime value when building is False.

python

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

Objects available during early evaluation: this, building, build_variant_index, build_variant_requires.

Late binding functions (@late)

Remain as functions in the installed package; evaluated lazily on first access and then cached. Allowed for: requires, build_requires, private_build_requires, tools, help, and any arbitrary attribute.

python

@late()
def tools():
    import os                      # imports MUST be inside the function
    result = this._tools
    if os.getenv("_USER_ROLE") != "superuser":
        result = set(result) - set(["delete-all", "mod-things"])
    return list(result)

@early()
def _tools():
    import os
    return os.listdir("./bin")     # relative: not installed yet at build time

• Split the work: compute what you can at build time into an @early custom attribute, then do only the runtime-dependent part in @late. This keeps resolves cheap.
• in_context() returns True when the package is part of a resolved context (e.g. iterating a ResolvedContext) and False when merely iterating packages (e.g. rez-search). Guard context-dependent logic with it.

commands() is late bound but is never decorated with @early/@late.

String expansion

{root} expands to the install location of the package; {this.root} is equivalent. Available in commands() and in rex calls. See rez-package-commands for literal(), expandable() and expandvars().

Package config overrides

A package can override rez settings during its own build/release:

python

with scope("config") as c:
    c.release_packages_path = "/software/packages/apps"

Overrides only apply while the package is being built or released, so only these are useful: packages_path, local_packages_path, release_packages_path, the build_system / release_hook / release_vcs plugin settings, package_definition_python_path, and package_filter.

Useful for routing internally- and externally-developed packages to different release paths.

Preprocessing

package.py can be preprocessed before evaluation — for example to add a version timestamp or to generate attributes from an external source. See the "Package Preprocessing" section of the Rez package-definition docs: the package_preprocess_function setting installs a global preprocessor, and rez-build --view-pre prints the preprocessed result. Prefer the simplest thing that works: an @early() function usually covers the same ground with far less machinery.

Review checklist for a package.py

• requires uses ranges (python-2.7+<3) rather than unpinned names when pinning matters.
• Build-only deps are in private_build_requires, not requires.
• @early() returns the correct value when building is False.
• @late() performs imports inside the function body.
• variants entries that must be discriminated are pinned in the request, not left ambiguous.
• commands() uses POSIX forward slashes, even on Windows.
• No os.pathsep or hardcoded a:b path lists.

Validate before release

bash

rez-build --install          # build + install locally
rez-env mypackage            # resolve in a fresh shell
rez-search --validate mypackage

Narrow the output — read the specific resolve, not the whole build log:

bash

rez-context --so             # source order of the resolve