Skip to main content
Local packages are the foundation of an Azure Linux build. This page explains how spec files are organized, how source files are managed, and how they’re packaged into source RPMs (SRPMs) with cryptographic verification.

​
Repository Structure

An Azure Linux repository typically consists of:

SPECS Directory

Root directory ($(SPEC_DIR)) with subdirectories for each package

Image Configs

Configuration files ($(CONFIG_FILE)) defining target images

Toolkit

Build system tools and makefiles

​
SPECS Directory Layout

Each package has its own subdirectory within the SPECS folder to avoid name collisions: 
SPECS/
├── bash/
│   ├── bash.spec
│   ├── bash.signatures.json
│   └── bash-patches-*.patch
├── kernel/
│   ├── kernel.spec
│   ├── kernel.signatures.json
│   └── config-*
└── systemd/
    ├── systemd.spec
    ├── systemd.signatures.json
    └── systemd-*.patch
Each spec file is accompanied by a *.signatures.json file that records expected cryptographic hashes for every source file used in the package.

​
SPEC Files

SPEC files define how packages are built. They contain:
  • Package metadata (name, version, summary, license)
  • Build and runtime dependencies
  • Source file locations
  • Build instructions
  • Installation procedures
  • File lists for each package/subpackage
The build system monitors $(SPEC_DIR) for changes. When spec files or sources change, all dependent files are automatically rebuilt.

​
Creating SRPMs

The build system operates on Source RPMs (SRPMs). An SRPM includes both:
  • The spec file defining the package
  • All associated source files (archives, patches, configs, etc.)

​
SRPM Creation Process

​
The srpmpacker Tool

The srpmpacker tool converts spec files into SRPMs by:
1

Parse Spec File

Runs inside the chroot worker to support RPM macros
2

Identify Sources

Determines which source files are needed
3

Verify Local Sources

Checks if sources exist locally and match the signature hash
4

Download Missing Sources

Fetches from source server if not found locally or hash mismatch
5

Build SRPM

Calls rpmbuild -bs to create the source RPM
srpmpacker will only accept source files that match the hash in the *.signatures.json file. If a local file’s hash doesn’t match, the tool attempts to download a matching file from the source server.

​
File Signature Handling

Hash checking behavior is controlled by $(SRPM_FILE_SIGNATURE_HANDLING):
Most secure - Only packages source files matching the listed hash
  • Validates all source files against signatures
  • Downloads missing files from online package server
  • Build fails if hashes don’t match
make input-srpms SRPM_FILE_SIGNATURE_HANDLING=enforce

​
Intermediate Build Artifacts

​
Intermediate SRPMs

Once srpmpacker determines a spec needs re-packaging, it generates an SRPM in: 
./../build/INTERMEDIATE_SRPMS/<arch>/
Build these manually with: 
make input-srpms

​
Intermediate SPECs

Canonical copies of spec files are extracted from SRPMs for dependency analysis: 
./../build/INTERMEDIATE_SPECS/<package>-<version>/
Extract these manually with: 
make expand-specs
These intermediate specs are used by the specreader tool to calculate dependency information without reparsing the original files.

​
Build Optimization

The scheduler will skip rebuilding a package if it determines the package is up-to-date. This check includes:
  • Spec file modification time
  • Source file modification times
  • Signature file changes
  • Dependency changes
When iterating on a single package, you may need to force a rebuild even when the build system thinks it’s up-to-date. See the Package Stage guide for tips on:
  • Forcing rebuilds of specific packages
  • Clearing cached build state
  • Bypassing up-to-date checks during development

​
Source Server Integration

When local sources are missing or have mismatched hashes, srpmpacker queries the source server to download matching files.

​
Source Server Behavior

  • Downloads are verified against the signature hash
  • Only sources with matching hashes are accepted
  • If no matching source is found, build fails with 404 error
  • Downloaded sources are cached for future builds
# Example error when source is not found
ERROR: Failed to download source file 'example-1.0.0.tar.gz'
ERROR: No matching hash found on source server
ERROR: Expected hash: sha256:abc123...

​
Signature File Format

The *.signatures.json file contains hashes for all sources: 
{
  "Signatures": {
    "example-1.0.0.tar.gz": "sha256:abc123...",
    "fix-build.patch": "sha256:def456...",
    "config-file.conf": "sha256:ghi789..."
  }
}
Use SRPM_FILE_SIGNATURE_HANDLING=update to automatically generate or update signature files when adding new sources to your spec files.

​
Next Steps

Package Building

Learn how SRPMs are built into RPMs with dependency resolution

Initial Preparation

Return to the initial preparation phase

Build docs developers (and LLMs) love

Get started for freeTalk to us