Package Settings

Fromager uses a layered settings system to configure how each package is resolved, downloaded, patched, and built. Settings flow from YAML files on disk through a merge pipeline into a single facade object used by the build pipeline.

See also

Configuration Reference documents every configuration field. Architecture Overview maps the major subsystems.

Settings Loading Flow

CLI flags
(--settings-file, --settings-dir, --patches-dir)
      │
      ▼
Settings.from_files()
├── Load settings.yaml ──► SettingsFile (global config)
└── Glob settings/*.yaml ──► PackageSettings (one per package)
      │
      ▼
Settings object (held by WorkContext)
      │
      │  package_build_info("torch")  (on demand, cached)
      ▼
PackageBuildInfo
(single facade used by the build pipeline)

PackageBuildInfo objects are created lazily the first time a package is queried and cached for the rest of the run.

Directory Structure

overrides/
├── settings.yaml              # Global settings
├── settings/                  # Per-package settings
│   ├── torch.yaml
│   ├── flash-attn.yaml
│   └── ...
└── patches/                   # Patches
    ├── torch/                 # Unversioned (all versions)
    │   ├── 001-fix.patch
    │   └── cpu/               # Variant-specific
    │       └── 002-cpu.patch
    └── torch-2.4.0/           # Version-specific
        └── 001-ver.patch

Package YAML filenames use the canonicalized package name (lowercase, hyphens). All three directories are configurable via CLI flags.

Merge Order

Settings are merged from least-specific to most-specific. Later layers override earlier ones:

┌──────────────────────────────────────────────────┐
│  1. Pydantic field defaults                      │
│     (empty env, default build options, etc.)     │
│                                                  │
│  2. Global settings.yaml                         │
│     (SBOM config, global changelog)              │
│                                                  │
│  3. Per-package YAML file                        │
│     (env, resolver, build options, patches, ...) │
│                                                  │
│  4. Variant overrides (within package YAML)      │
│     (env vars, pre_built, wheel_server_url)      │
│                                                  │
│  5. Version-specific patches and changelog       │
│     (patches/<pkg>-<version>/, changelog entries)│
│                                                  │
│  6. Override plugin hooks (runtime)              │
│     (update_extra_environ can mutate env vars)   │
└──────────────────────────────────────────────────┘

For environment variables specifically, the merge order within a single get_extra_environ() call is: parallel-jobs settings, build environment paths, package-level env, then variant-level env. Entries can reference earlier values using $VAR template syntax.

PackageBuildInfo Facade

PackageBuildInfo is the single interface the build pipeline uses to query all package configuration. It wraps a PackageSettings and adds variant awareness, patch discovery, and template resolution.

Category	What it provides
Identity	Package name, variant, whether a config file exists, override plugin module
Resolution	Sdist server URL, include wheels/sdists flags, platform filtering, per-package cooldown override
Build config	Environment variables, parallel jobs, exclusive build flag, PEP 517 config settings, build directory
Source	Download URL and filename templates with ${version} substitution, git submodule options
Patches	Merged list of unversioned + version-specific + variant-specific patch files, sorted by filename
Metadata	Build tag (from changelog length), annotations, PURL config, pyproject.toml overrides

See Configuration Reference for the full field reference.