Batch configs¶
Batch configs define groups of related packages for building together — PHP extensions, OCaml libraries sharing a common toolchain version, and similar situations where all packages share settings and should land in one task.
Used by zoryn task batch.
Location¶
Config files are stored in ~/.config/zoryn/batch/ with .conf extension. Reference them by name (without extension) or full path:
zoryn task batch php-8.4 # ~/.config/zoryn/batch/php-8.4.conf
zoryn task batch ~/configs/mypackages.conf # explicit path
Format¶
TOML: a [batch] table for global settings, one table per package.
[batch]
name = "PHP 8.4 extensions"
basedir = "~/packages/php8.4"
specsubst = "phpver=8.4"
main = "php"
main_branch = "8.4"
[php]
# Main package, version/tag derived from here
[php-memcached]
# Uses default settings
[pecl-imagick]
path = "~/packages/imagick"
# Custom path, not basedir/pecl-imagick
[php-unit]
mode = "rebuild"
# Rebuild instead of build from source
[php-xdebug]
skip = true
# Temporarily disabled
[php-pgsql]
exclude = ["p10", "c10f2"]
# Don't build for p10 and c10f2
[php-redis]
only = ["sisyphus", "p11"]
# Build only for sisyphus and p11
[php-sodium]
specsubst = "none"
# Disable specsubst for this package
[batch] section options¶
| Option | Description |
|---|---|
name | Display name for the batch (default: config filename) |
basedir | Base directory for packages, supports ~ expansion |
specsubst | Required. Default specsubst for gear-create-tag (e.g. phpver=8.4); use none to disable substitution |
mode | Default mode for every package: build (default), rebuild, or auto (see Auto mode) |
main | Main package name for version/tag derivation |
main_branch | Git branch to read main package spec from |
tag_format | Tag name template (default: {main_name}-{main_version}-{main_release}) |
tag_message | Tag message template (default: same as tag_format) |
Tag format placeholders¶
{main_name}— main package name (e.g.php8.4).{main_version}— main package version (e.g.8.4.17).{main_release}— main package release (e.g.alt1).{name}— current package name (e.g.php8.4-apcu).
Package section options¶
| Option | Description |
|---|---|
path | Custom repo path instead of basedir/name; supports ~. An absolute or ~-path is used as-is; a relative path is resolved under basedir (so specsubst variants can share one repo, e.g. path = "dune") |
mode | build (default), rebuild, or auto; overrides the [batch]-level mode |
exclude | TOML array or comma-separated string of repos where package is excluded |
only | TOML array or comma-separated string of repos where package is included (exclusive) |
skip | true to temporarily disable |
specsubst | Override specsubst, or none to disable |
Auto mode¶
With mode = "auto" — set globally in [batch] or per package — zoryn decides what to do per package and per target repository, comparing the version-release from the package's own spec with what the repository already has (via the RDB API):
- the repository has the same version-release — the package is added to the task as a plain rebuild;
- the repository has an older version, none at all, or RDB could not be reached — the package gets its own
<version>-<release>tag and is built from source; - the repository is newer than the spec — the package is skipped for that repository with a warning: the local checkout is behind.
A package listed in the config with no local checkout at all (its directory does not exist) is added as a plain rebuild — there is nothing to compare or build from source.
Tags in auto mode always use the package's own <version>-<release>; tag_format and tag_message apply only to linked batches driven by the main package. If nothing needs a source build but the working tree has uncommitted changes, zoryn warns that the release probably needs a bump.
Auto mode resolves packages against RDB by the spec's own Name:; specsubst renames are not applied — for specsubst-renamed variants the decision may be wrong, so prefer explicit mode = "build"/"rebuild" for those.
Validation¶
Batch config files are validated when loaded: an unknown key (e.g. a typo like excludes) or an unrecognized option in the [batch] section produces a warning on stderr, prefixed with the file path. The build still proceeds — the warning just helps catch mistakes. An invalid mode value (anywhere) is an error, not a warning.
specsubst values are also checked: the variable name must be an ASCII letter followed by ASCII letters and digits (it becomes the git config key gear.specsubst.<name>, which git accepts nothing else in), and the value must be printable ASCII. The error names the offending character with its codepoint and Unicode name — so a Cyrillic lookalike letter, invisible to the eye, is called out explicitly (e.g. 'с' (U+0441 CYRILLIC SMALL LETTER ES)).
Generating from an existing task¶
To bootstrap a batch config from a task you already have, use zoryn task genbatch: