Skip to main content
Package Generator (pkgworker) is the core build worker that compiles individual RPM packages from SRPM source packages. It creates isolated chroot environments for each package build, ensuring clean and reproducible builds. This tool is typically invoked by the scheduler rather than run directly.

​
Usage

pkgworker \
  --srpm-file <package.src.rpm> \
  --work-dir <work-dir> \
  --worker-tar <worker_chroot.tar.gz> \
  --repo-file <local.repo> \
  --rpm-dir <output-rpms> \
  --srpm-dir <output-srpms> \
  --toolchain-rpms-dir <toolchain-rpms> \
  --cache-dir <cache-dir> \
  --base-package-name <spec-name> \
  --dist-tag <dist-tag> \
  --distro-release-version <version> \
  --distro-build-number <build-number> \
  --timeout <duration> \
  [options]

​
Parameters

​
srpm-file
string
required
Full path to the SRPM to build
​
work-dir
string
required
The directory to create the build folder in
​
worker-tar
string
required
Full path to worker_chroot.tar.gz containing the build environment
​
repo-file
string
required
Full path to local.repo file for RPM dependencies
​
rpm-dir
string
required
The directory to use as the local repo and to submit RPM packages to
​
srpm-dir
string
required
The output directory for source RPM packages
​
toolchain-rpms-dir
string
required
Directory that contains already built toolchain RPMs. Should contain a top level directory for each architecture.
​
cache-dir
string
required
The cache directory containing downloaded dependency RPMS from Azure Linux Base
​
base-package-name
string
required
The name of the spec file used to build this package without the extension
​
dist-tag
string
required
The distribution tag the SPEC will be built with (e.g., .azl3)
​
distro-release-version
string
required
The distro release version that the SRPM will be built with
​
distro-build-number
string
required
The distro build number that the SRPM will be built with
​
timeout
duration
required
Timeout for package building (e.g., 2h, 30m)
​
run-check
boolean
Run the %check section during package build (runs package tests)
​
rpmmacros-file
string
Optional file path to an rpmmacros file for rpmbuild to use
​
install-package
string
Filepaths to RPM packages that should be installed before building (can be specified multiple times)
​
out-arch
string
Architecture of resulting package
​
no-cleanup
boolean
Whether or not to delete the chroot folder after the build is done
​
use-ccache
boolean
Automatically install and use ccache during package builds
​
ccache-root-dir
string
The directory used to store ccache outputs
​
ccache-config
string
The configuration file for ccache
​
max-cpu
string
Max number of CPUs used for package building
​
log-file
string
Path to the log file
​
log-level
string
Log level (panic, fatal, error, warn, info, debug, trace)

​
How It Works

  1. Create Chroot: Extracts worker_chroot.tar.gz to create an isolated build environment
  2. Mount Dependencies: Mounts local RPM repositories and toolchain directories into chroot
  3. Install Build Dependencies: Uses tdnf to install packages listed in BuildRequires
  4. Build Package: Runs rpmbuild to compile the package from source
  5. Run Tests: Optionally runs %check section if --run-check is specified
  6. Extract Results: Copies built RPMs to the output directory
  7. Cleanup: Removes chroot unless --no-cleanup is specified

​
Build Environment

The worker chroot contains:
  • Build Tools: gcc, make, cmake, autotools, etc.
  • Package Manager: tdnf for installing dependencies
  • RPM Tools: rpmbuild, rpm, rpmspec
  • Standard Libraries: glibc, system headers, etc.

​
Ccache Support

Pkgworker supports ccache to speed up rebuilds: 
pkgworker \
  --srpm-file mypackage.src.rpm \
  --use-ccache \
  --ccache-root-dir /var/cache/ccache \
  --ccache-config ccache.conf \
  [other options...]
Ccache is especially useful for:
  • Incremental builds during development
  • CI/CD pipelines with frequent rebuilds
  • Large C/C++ packages with long compile times

​
Example

​
Standard Package Build

pkgworker \
  --srpm-file nginx-1.20.1-1.src.rpm \
  --work-dir ./build/workers \
  --worker-tar toolkit/worker_chroot.tar.gz \
  --repo-file build/local.repo \
  --rpm-dir build/rpms/x86_64 \
  --srpm-dir build/srpms \
  --toolchain-rpms-dir build/toolchain_rpms \
  --cache-dir build/cached_rpms \
  --base-package-name nginx \
  --dist-tag .azl3 \
  --distro-release-version 3.0 \
  --distro-build-number 20240101 \
  --timeout 2h \
  --log-level info

​
Build with Tests

pkgworker \
  --srpm-file python3-1.0-1.src.rpm \
  --run-check \
  --work-dir ./build/workers \
  [other required options...]

​
Development Build (No Cleanup)

pkgworker \
  --srpm-file mypackage-1.0-1.src.rpm \
  --no-cleanup \
  --work-dir ./build/workers \
  [other required options...]
After the build, you can examine the chroot at ./build/workers/mypackage-1.0-1/ to debug build issues.

​
Output

On successful build, pkgworker prints a comma-separated list of built RPM files to stdout: 
mypackage-1.0-1.x86_64.rpm,mypackage-devel-1.0-1.x86_64.rpm,mypackage-debuginfo-1.0-1.x86_64.rpm
This output is used by the scheduler to track which packages were built.

​
Notes

  • This tool is typically invoked by the scheduler, not run directly by users
  • Requires root privileges for chroot operations
  • Each package builds in a clean, isolated environment
  • Build dependencies are automatically installed from available repositories
  • The --timeout parameter prevents runaway builds
  • Use --no-cleanup during development to inspect build artifacts
  • The --run-check flag runs package test suites, which may significantly increase build time

​
See Also

  • Scheduler - Orchestrates pkgworker invocations
  • Grapher - Generates dependency graphs for the scheduler

Build docs developers (and LLMs) love

Get started for freeTalk to us