Skip to main content
After the toolchain is built or populated, you can build Azure Linux packages. The package stage uses the toolchain to compile packages in parallel.

​
Package Build Strategies

The Azure Linux ecosystem provides thousands of packages, but most are not used in a typical image. You can choose to:
  • Build all packages - Complete rebuild of the entire package repository
  • Build for specific image - Only packages needed for a target image
  • Build specific packages - Targeted builds for development and testing

​
Build All Packages

To rebuild all Azure Linux packages: 
sudo make build-packages -j$(nproc) REBUILD_TOOLS=y
Building all packages can take many hours. Use parallel builds with -j$(nproc) to utilize all CPU cores.

​
Build Packages for Specific Image

Build only the packages needed for a specific image by specifying a configuration file: 
sudo make build-packages -j$(nproc) \
  CONFIG_FILE=./imageconfigs/core-legacy.json \
  REBUILD_TOOLS=y
This builds:
  • All packages included in the image
  • All packages needed to build those packages (dependencies)
  • Significantly fewer packages than a full build
Image configuration files are located in toolkit/imageconfigs/. Common configs include:
  • core-legacy.json - Basic VHD with legacy BIOS support
  • core-efi.json - Basic VHDX with UEFI support
  • core-container.json - Container image

​
Targeted Package Building

For rapid iteration on specific packages, use targeted builds:
1

Build specific package

Build one or more packages by name:
sudo make build-packages -j$(nproc) \
  REBUILD_TOOLS=y \
  SRPM_PACK_LIST="openssh"
2

Skip chroot rebuild

For subsequent builds, save time by not rebuilding the worker chroot:
sudo make build-packages -j$(nproc) \
  REBUILD_TOOLS=y \
  SRPM_PACK_LIST="at openssh" \
  REFRESH_WORKER_CHROOT=n
3

Force package rebuild

Force a package to rebuild even if it’s up-to-date:
sudo make build-packages -j$(nproc) \
  REBUILD_TOOLS=y \
  SRPM_PACK_LIST="at" \
  PACKAGE_REBUILD_LIST="at" \
  REFRESH_WORKER_CHROOT=n
Targeted building downloads dependencies from packages.microsoft.com and rebuilds only the specified SPEC files. This is ideal for developing or modifying packages.

​
Package Build Workflow

​
Step 1: SRPM Creation

The build system first creates Source RPMs (SRPMs) from SPEC files and sources: 
sudo make input-srpms
This command:
  1. Scans local *.spec files in SPECS/
  2. Locates source files for each package
  3. Creates *.src.rpm files bundling specs with sources

​
Step 2: RPM Building

The SRPMs are then built into binary RPMs: 
sudo make build-packages -j$(nproc)
This process:
  1. Resolves package dependencies
  2. Builds packages in correct dependency order
  3. Uses parallel workers to build multiple packages simultaneously
  4. Places built RPMs in ../out/RPMS/

​
Working with Package Sources

​
Download Pre-packaged Sources

Use DOWNLOAD_SRPMS=y to download pre-packaged SRPMs instead of packing from local specs: 
sudo make build-packages -j$(nproc) DOWNLOAD_SRPMS=y
When DOWNLOAD_SRPMS=y is set, local sources and spec files are not used, and your changes will not be reflected in the final packages.

​
Specify Source URL

Provide a custom source server for downloading package sources: 
sudo make build-packages -j$(nproc) \
  SOURCE_URL='https://azurelinuxsrcstorage.blob.core.windows.net/sources/core'

​
Package Build Variables

​
Key Variables

​
SRPM_PACK_LIST
string
Space-separated list of spec names to pack into SRPMs. If empty, all specs under SPECS_DIR are packed.Example: SRPM_PACK_LIST="kernel golang openssh"
​
PACKAGE_BUILD_LIST
string
Explicit list of packages to build. Skipped if already up-to-date.Example: PACKAGE_BUILD_LIST="vim nano"
​
PACKAGE_REBUILD_LIST
string
Force rebuild these packages even if up-to-date.Example: PACKAGE_REBUILD_LIST="kernel openssh"
​
PACKAGE_IGNORE_LIST
string
Pretend these packages are already built (useful when a dependency is broken).Example: PACKAGE_IGNORE_LIST="ncurses"
​
REFRESH_WORKER_CHROOT
string
default:"y"
  • y - Rebuild worker chroot if changed
  • n - Reuse existing worker chroot (faster for iterative builds)
​
REBUILD_PACKAGES
string
default:"y"
  • y - Build packages locally from specs
  • n - Download all packages from repos

​
Package Testing

Enable package tests during build: 
sudo make build-packages -j$(nproc) \
  RUN_CHECK=y \
  SRPM_PACK_LIST="openssh"
This runs the %check section of the spec file to validate the built package.

​
Advanced Package Builds

​
Build from Custom SPECS Directory

sudo make build-packages SPECS_DIR="/my/packages/SPECS" -j$(nproc)

​
Update Source Signatures

When you modify source files, update their signature hashes: 
sudo make input-srpms SRPM_FILE_SIGNATURE_HANDLING=update

​
Clean Package Builds

Remove built artifacts before rebuilding: 
sudo make clean-build-packages
sudo make build-packages -j$(nproc)

​
Build Outputs

Built packages are placed in: 
../out/RPMS/
├── x86_64/        # Architecture-specific packages
├── noarch/        # Architecture-independent packages
└── src/           # Source packages
Build logs are available in: 
../build/logs/pkggen/rpmbuilding/

​
Next Steps

After building packages, you can:

Build docs developers (and LLMs) love

Get started for freeTalk to us