Implementation:MaterializeInc Materialize Repository Init

Knowledge Sources	misc/python/materialize/mzbuild.py (Repository class)
Domains	Build Systems, Dependency Management, Container Infrastructure
Last Updated	2026-02-08

Overview

Concrete implementation of image dependency discovery, validation, and topological resolution provided by the Repository class in Materialize's mzbuild system.

Description

The Repository class is the top-level entry point for Materialize's mzbuild build system. It performs two critical functions:

1. __init__() -- Walks the repository filesystem to discover all Docker images (directories containing mzbuild.yml) and compositions (directories containing mzcompose.py). It populates the self.images dictionary and validates that all declared dependencies reference images that actually exist in the repository.

1. resolve_dependencies() -- Given a set of target images, performs a depth-first traversal of the dependency graph to produce a topologically sorted DependencySet. This method detects circular dependencies and raises a ValueError with a human-readable cycle diagram if one is found.

During __init__, the filesystem walk skips known-irrelevant directories (.git, target, node_modules, venv, etc.) for performance. Each discovered mzbuild.yml is parsed into an Image object, and uniqueness of image names is enforced.

Usage

Use Repository when you need to:

• Initialize the mzbuild system at the start of a build or CI job.
• Discover all buildable images in the Materialize repository.
• Resolve the build order for a specific set of target images, including all transitive dependencies.
• Validate repository integrity by ensuring no duplicate image names or dangling dependency references exist.

Code Reference

Source Location

File	misc/python/materialize/mzbuild.py
Class	Repository
__init__	Lines 1324-1381
resolve_dependencies	Lines 1477-1507

Signature

class Repository:
    def __init__(
        self,
        root: Path,
        arch: Arch = Arch.host(),
        profile: Profile = (
            Profile.RELEASE if ui.env_is_truthy("CI_LTO") else Profile.OPTIMIZED
        ),
        coverage: bool = False,
        sanitizer: Sanitizer = Sanitizer.none,
        image_registry: str = image_registry(),
        image_prefix: str = "",
    ):
        ...

    def resolve_dependencies(self, targets: Iterable[Image]) -> DependencySet:
        ...

Import

from materialize.mzbuild import Repository

I/O Contract

Inputs

Parameter	Type	Description
root	Path	Path to the root of the Materialize repository. The filesystem walk begins here.
arch	Arch	CPU architecture to build for (defaults to Arch.host()).
profile	Profile	Rust build profile: RELEASE, OPTIMIZED, or DEV.
coverage	bool	Whether to enable code coverage instrumentation.
sanitizer	Sanitizer	Sanitizer mode: none, address, thread, leak, or memory.
image_registry	str	Docker registry to push/pull images (defaults to image_registry()).
image_prefix	str	Prefix to apply to all Docker image names.
targets (resolve_dependencies)	Iterable[Image]	The target images whose dependency closure should be computed.

Outputs

Output	Type	Description
self.images	dict[str, Image]	Mapping from image name to Image for every discovered mzbuild image.
self.compositions	dict[str, Path]	Mapping from composition name to its directory path.
DependencySet (from resolve_dependencies)	DependencySet	A topologically sorted set of ResolvedImage objects ready for building.

Usage Examples

Initializing a repository and resolving dependencies:

from pathlib import Path
from materialize.mzbuild import Repository

# Initialize repository -- discovers all images and validates dependencies
repo = Repository(root=Path("/path/to/materialize"))

# Inspect discovered images
for name, image in repo.images.items():
    print(f"{name}: depends on {image.depends_on}")

# Resolve the full dependency set for specific target images
targets = [repo.images["environmentd"], repo.images["clusterd"]]
dep_set = repo.resolve_dependencies(targets)

# The dependency set is topologically ordered
for resolved_image in dep_set:
    print(f"Build: {resolved_image.name}")

Using command-line arguments:

import argparse
from pathlib import Path
from materialize.mzbuild import Repository

parser = argparse.ArgumentParser()
Repository.install_arguments(parser)
args = parser.parse_args()
repo = Repository.from_arguments(Path("/path/to/materialize"), args)

How resolve_dependencies detects cycles:

# If image A depends on B, B depends on C, and C depends on A,
# resolve_dependencies raises:
#   ValueError: circular dependency in mzbuild: A -> B -> C -> A

Related Pages

Implements Principle

• Principle:MaterializeInc_Materialize_Image_Dependency_Resolution

Requires Environment

• Environment:MaterializeInc_Materialize_Docker_Compose_Runtime