Skip to main content
Grapher is a dependency graph generation tool that creates a directed acyclic graph (DAG) representing the build dependencies between packages in Azure Linux. It processes SRPM metadata and generates a DOT format graph file that is used by the scheduler to determine build order.

​
Usage

grapher --input <packages.json> --output <graph.dot> [options]

​
Parameters

​
input
string
required
Input JSON file listing all local SRPMs
​
output
string
required
Output DOT graph file path
​
rpm-dir
string
required
Directory containing already built RPMs. Should contain top-level directories for each architecture.
​
toolchain-rpms-dir
string
required
Directory containing already built toolchain RPMs. Should contain top-level directories for each architecture.
​
tdnf-worker
string
required
Full path to worker_chroot.tar.gz
​
repo-file
string
required
Full path to a repo file (can be specified multiple times)
​
strict-goals
boolean
Don’t allow missing goal packages
​
strict-unresolved
boolean
Don’t allow missing unresolved packages
​
resolve-cycles-from-upstream
boolean
Let grapher resolve cycles by marking RPMs available in upstream repos as remote
​
out-dir
string
Directory to download packages into
​
tmp-dir
string
Directory to store temporary files while downloading
​
use-preview-repo
boolean
Pull packages from the upstream preview repo
​
disable-default-repos
boolean
Disable pulling packages from PMC repos
​
ignore-version-to-resolve-selfdep
boolean
Ignore package version while downloading package from upstream when resolving cycles
​
repo-snapshot-time
string
Optional: Repo time limit for tdnf virtual snapshot
​
tls-cert
string
TLS client certificate to use when downloading files
​
tls-key
string
TLS client key to use when downloading files
​
timestamp-file
string
File that stores timestamps for this program
​
log-file
string
Path to the log file
​
log-level
string
Log level (panic, fatal, error, warn, info, debug, trace)

​
How It Works

  1. Parse Input: Reads the package JSON file containing metadata for all local SRPMs
  2. Build Graph: Creates nodes for each package with run, build, and test dependencies
  3. Add Dependencies: Connects nodes based on their runtime, build-time, and test-time requirements
  4. Resolve Cycles: Optionally resolves circular dependencies by marking packages available in upstream repos as remote
  5. Output: Writes the final dependency graph in DOT format

​
Graph Node Types

  • Run Node: Represents the runtime requirements of a package
  • Build Node: Represents the build-time requirements
  • Test Node: Represents the test-time requirements (optional)
  • Remote/Unresolved Node: Packages that will be pulled from upstream repositories

​
Example

grapher \
  --input build/pkg_artifacts/graph_external_deps.json \
  --output build/pkg_artifacts/graph.dot \
  --rpm-dir build/rpms \
  --toolchain-rpms-dir build/toolchain_rpms \
  --tdnf-worker toolkit/worker_chroot.tar.gz \
  --repo-file build/local.repo \
  --resolve-cycles-from-upstream \
  --log-level info

​
Notes

  • The output graph is used as input to the scheduler tool for building packages
  • Use --strict-goals and --strict-unresolved flags during development to catch missing dependencies early
  • The --resolve-cycles-from-upstream flag is useful when dealing with circular dependencies by pulling some packages from upstream repos
  • Graph cycles must be resolved before the scheduler can process the build

Build docs developers (and LLMs) love

Get started for freeTalk to us