Creating RPM SPEC Files

RPM SPEC files define how packages are built, installed, and distributed in Azure Linux. This guide covers the essential components and best practices for creating SPEC files.

SPEC File Structure

A SPEC file is divided into several sections, each serving a specific purpose:

┌─────────────────────────────┐
│ Preamble (Metadata)         │  ← Package info, dependencies
├─────────────────────────────┤
│ %description                │  ← What the package does
├─────────────────────────────┤
│ %prep                       │  ← Unpack and patch sources
├─────────────────────────────┤
│ %build                      │  ← Compile the software
├─────────────────────────────┤
│ %install                    │  ← Install into buildroot
├─────────────────────────────┤
│ %check                      │  ← Run test suite
├─────────────────────────────┤
│ %files                      │  ← List installed files
├─────────────────────────────┤
│ %changelog                  │  ← Version history
└─────────────────────────────┘

Preamble Section

The preamble contains package metadata and dependencies.

Basic Metadata

Simple Package
Complex Package
Server Package

Summary:        Access control list utilities
Name:           acl
Version:        2.3.1
Release:        2%{?dist}
License:        GPLv2+
Vendor:         Microsoft Corporation
Distribution:   Azure Linux
Group:          System Environment/Base
URL:            https://savannah.nongnu.org/projects/acl/
Source0:        https://download.savannah.nongnu.org/releases/%{name}/%{name}-%{version}.tar.gz

BuildRequires:  attr-devel
Requires:       libacl = %{version}-%{release}

%description
This package contains the getfacl and setfacl utilities needed for
manipulating access control lists.

Summary:        An URL retrieval utility and library
Name:           curl
Version:        8.11.1
Release:        5%{?dist}
License:        curl
Vendor:         Microsoft Corporation
Distribution:   Azure Linux
Group:          System Environment/NetworkingLibraries
URL:            https://curl.haxx.se
Source0:        https://curl.haxx.se/download/%{name}-%{version}.tar.gz
Patch0:         CVE-2025-0665.patch
Patch1:         CVE-2025-0167.patch
Patch2:         CVE-2025-0725.patch

BuildRequires:  cmake
BuildRequires:  krb5-devel
BuildRequires:  openssl-devel
Requires:       curl-libs = %{version}-%{release}
Requires:       krb5
Requires:       openssl

%description
The cURL package contains an utility and a library used for
transferring files with URL syntax to any of the following
protocols: FTP, FTPS, HTTP, HTTPS, SCP, SFTP, TFTP, TELNET,
DICT, LDAP, LDAPS and FILE.

%global nginx_user nginx

Summary:        High-performance HTTP server and reverse proxy
Name:           nginx
Version:        1.28.1
Release:        1%{?dist}
License:        BSD-2-Clause
Vendor:         Microsoft Corporation
Distribution:   Azure Linux
Group:          Applications/System
URL:            https://nginx.org/
Source0:        https://nginx.org/download/%{name}-%{version}.tar.gz
Source1:        nginx.service

BuildRequires:  openssl-devel
BuildRequires:  pcre2-devel
BuildRequires:  zlib-devel
Requires:       %{name}-filesystem = %{version}-%{release}
Requires:       %{name}-mimetypes

%description
NGINX is a free, open-source, high-performance HTTP server and 
reverse proxy, as well as an IMAP/POP3 proxy server.

Key Fields Explained

Summary

A one-line description of the package (max 80 characters). Should be concise and informative.

Name

The package name. Must be lowercase, no spaces. Use hyphens for multi-word names.

Version

The upstream software version. Should match the upstream release exactly.

Release

Package release number. Start at 1%{?dist} and increment for packaging changes. Reset to 1 when Version changes.

License

The software license. Use SPDX identifiers when possible (e.g., MIT, GPL-2.0-or-later, Apache-2.0).

Source0, Source1, ...

URLs or filenames of source archives. Use %{name} and %{version} macros for clarity.

Patch0, Patch1, ...

Patch files to apply to sources. Name patches descriptively (e.g., CVE-2025-0665.patch).

BuildRequires

Packages needed to compile the software. Each on a separate line for clarity.

Requires

Packages needed at runtime. Often auto-detected by RPM, but specify explicitly for clarity.

Subpackages

Many packages split functionality into multiple RPMs using subpackages.

Library Subpackage
Devel Subpackage
Filesystem Subpackage

%package libs
Summary:        Libraries for curl
Group:          System Environment/Libraries
Provides:       libcurl = %{version}-%{release}

%description libs
This package contains minimal set of shared curl libraries.

# Later in the file...
%files libs
%{_libdir}/libcurl.so.*

%package devel
Summary:        Libraries and header files for curl
Requires:       %{name} = %{version}-%{release}
Provides:       libcurl-devel = %{version}-%{release}

%description devel
Static libraries and header files for the support library for curl

# Later in the file...
%files devel
%defattr(-,root,root)
%{_libdir}/*.so
%{_libdir}/pkgconfig/*
%{_includedir}/*
%{_mandir}/man3/*

%package filesystem
Summary:        The basic directory layout for the Nginx server
BuildArch:      noarch
Requires(pre):  shadow-utils

%description filesystem
The nginx-filesystem package contains the basic directory layout
for the Nginx server including the correct permissions for the
directories.

%pre filesystem
getent group %{nginx_user} > /dev/null || groupadd -r %{nginx_user}
getent passwd %{nginx_user} > /dev/null || \
    useradd -r -d %{_localstatedir}/lib/nginx -g %{nginx_user} \
    -s /sbin/nologin -c "Nginx web server" %{nginx_user}
exit 0

%files filesystem
%dir %{_sysconfdir}/%{name}

Build Sections

%prep - Prepare Sources

The %prep section unpacks sources and applies patches.

Simple Prep
Custom Prep
Multiple Sources

%prep
%autosetup

This macro automatically:

Unpacks Source0
Changes to the unpacked directory
Applies all patches in order

%prep
%autosetup -p1

The -p1 flag strips one directory level from patch paths.

%prep
%autosetup -n inspektor-gadget-%{version}
%setup -q -n inspektor-gadget-%{version} -T -D -a 1

-n: Specify the directory name after unpacking
-T: Don’t unpack Source0 again
-D: Don’t delete the directory first
-a 1: Unpack Source1

%build - Compile Software

The %build section compiles the software.

Autotools Build
CMake Build
Go Build
Python Build
Custom Build

%build
%configure \
    --disable-static \
    --enable-threaded-resolver \
    --with-ssl \
    --with-gssapi
%make_build

Common for projects using ./configure && make

%build
%cmake \
    -DCMAKE_BUILD_TYPE=Release \
    -DBUILD_SHARED_LIBS=ON \
    -DBUILD_TESTING=OFF
%cmake_build

For CMake-based projects

%build
export CGO_ENABLED=0
go build \
    -ldflags "-X main.version=v%{version}" \
    -tags "netgo" \
    -o ./bin/%{name} ./cmd/%{name}

For Go applications

%build
%py3_build

For Python packages using setuptools

%build
sh configure \
    --prefix=%{_prefix} \
    --sbin-path=%{_sbindir}/nginx \
    --with-http_ssl_module \
    --with-http_v2_module
%make_build

Custom configuration script

%install - Install Files

The %install section copies built files to the buildroot.

Standard Install
With Service File
Manual Install

%install
%make_install
find %{buildroot} -type f -name "*.la" -delete -print
%{_fixperms} %{buildroot}/*

%install
%make_install
install -vdm755 %{buildroot}%{_libdir}/systemd/system
install -p -m 0644 %{SOURCE1} %{buildroot}%{_libdir}/systemd/system/nginx.service

# Clean up
find %{buildroot} -type f -name "*.la" -delete -print

%install
mkdir -p "%{buildroot}/%{_bindir}"
install -D -m0755 bin/build/ig %{buildroot}/%{_bindir}

mkdir -p "%{buildroot}/%{_mandir}/man1"
install -m0644 docs/*.1 %{buildroot}/%{_mandir}/man1/

%check - Run Tests

The %check section runs the package test suite.

Simple Test
Conditional Tests
Skipping Tests
Complex Tests

%check
make test

%if 0%{?with_check}
%check
make test
%endif

Tests only run when RUN_CHECK=y is set

%check
# Skip test that requires network access
sed -e 's|test/network.test||' -i test/Makefile
make test

%check
export PYTHONPATH=%{buildroot}%{python3_sitelib}
pytest-3 tests/ -v

File Listings

The %files section declares which files belong to each package.

Path Macros

Use RPM macros for standard paths:

Macro	Path	Usage
`%{_bindir}`	`/usr/bin`	User executables
`%{_sbindir}`	`/usr/sbin`	System executables
`%{_libdir}`	`/usr/lib64` or `/usr/lib`	Libraries
`%{_includedir}`	`/usr/include`	Header files
`%{_datadir}`	`/usr/share`	Architecture-independent data
`%{_mandir}`	`/usr/share/man`	Man pages
`%{_sysconfdir}`	`/etc`	Configuration files
`%{_localstatedir}`	`/var`	Variable data

File Attributes

Basic Files
Config Files
Directories
Documentation

%files
%defattr(-,root,root)
%license COPYING
%{_bindir}/*
%{_mandir}/man1/*

%files
%defattr(-,root,root)
%config(noreplace) %{_sysconfdir}/%{name}/nginx.conf
%config(noreplace) %{_sysconfdir}/%{name}/fastcgi_params

noreplace preserves user changes during upgrades

%files
%defattr(-,root,root)
%dir %{_sysconfdir}/%{name}
%dir %{_var}/log/%{name}

Explicitly declare owned directories

%files
%defattr(-,root,root)
%license LICENSE
%doc README.md CHANGELOG.md
%{_docdir}/%{name}-%{version}

Changelog

The %changelog section tracks package history in reverse chronological order.

%changelog
* Fri Jan 09 2026 Azure Linux Security Servicing Account <[email protected]> - 8.11.1-5
- Patch for CVE-2025-14017

* Thu Sep 11 2025 Azure Linux Security Servicing Account <[email protected]> - 8.11.1-4
- Patch for CVE-2025-10148

* Thu Feb 13 2025 Kanishk Bansal <[email protected]> - 8.11.1-3
- Fix CVE-2025-0665, CVE-2025-0167, CVE-2025-0725

* Wed Feb 26 2025 Tobias Brick <[email protected]> - 8.11.1-2
- Add check section

* Fri Feb 07 2025 Himaja Kesari <[email protected]> - 8.11.1-1
- Bump version to 8.11.1 to address CVE-2024-11053

Changelog Format

* Day Month DD YYYY Name <email> - Version-Release
- Change description
- Another change

Date format must be: DayOfWeek MonthName DD YYYY (e.g., Fri Jan 09 2026)

Complete Examples

Simple Utility
Library with Subpackages

Summary:        Access control list utilities
Name:           acl
Version:        2.3.1
Release:        2%{?dist}
License:        GPLv2+
Vendor:         Microsoft Corporation
Distribution:   Azure Linux
Group:          System Environment/Base
URL:            https://savannah.nongnu.org/projects/acl/
Source0:        https://download.savannah.nongnu.org/releases/%{name}/%{name}-%{version}.tar.gz
BuildRequires:  attr-devel
Requires:       libacl = %{version}-%{release}

%description
This package contains the getfacl and setfacl utilities needed for
manipulating access control lists.

%prep
%autosetup

%build
%configure
%make_build LIBTOOL="libtool --tag=CC"

%install
%make_install
find %{buildroot} -type f -name "*.la" -delete -print
chmod 0755 %{buildroot}%{_libdir}/libacl.so.*.*.*
%find_lang %{name}

%check
make test

%files -f %{name}.lang
%license doc/COPYING*
%{_bindir}/chacl
%{_bindir}/getfacl
%{_bindir}/setfacl
%{_mandir}/man1/chacl.1*

%changelog
* Wed Sep 20 2023 Jon Slobodzian <[email protected]> - 2.3.1-2
- Recompile with stack-protection fixed gcc version

* Wed Nov 24 2021 Pawel Winogrodzki <[email protected]> - 2.3.1-1
- Updating to version 2.3.1

Summary:        An URL retrieval utility and library
Name:           curl
Version:        8.11.1
Release:        5%{?dist}
License:        curl
Vendor:         Microsoft Corporation
Distribution:   Azure Linux
URL:            https://curl.haxx.se
Source0:        https://curl.haxx.se/download/%{name}-%{version}.tar.gz
BuildRequires:  openssl-devel
BuildRequires:  libssh2-devel
Requires:       curl-libs = %{version}-%{release}

%description
The cURL package contains an utility and a library used for
transferring files with URL syntax.

%package devel
Summary:        Libraries and header files for curl
Requires:       %{name} = %{version}-%{release}

%description devel
Static libraries and header files for curl

%package libs
Summary:        Libraries for curl

%description libs
This package contains minimal set of shared curl libraries.

%prep
%autosetup -p1

%build
%configure \
    --disable-static \
    --enable-threaded-resolver \
    --with-ssl
%make_build

%check
make test

%install
%make_install
find %{buildroot} -type f -name "*.la" -delete -print

%ldconfig_scriptlets libs

%files
%defattr(-,root,root)
%license COPYING
%{_bindir}/*
%{_mandir}/man1/*

%files devel
%defattr(-,root,root)
%{_libdir}/*.so
%{_includedir}/*

%files libs
%{_libdir}/libcurl.so.*

%changelog
* Fri Jan 09 2026 Security Team <[email protected]> - 8.11.1-5
- Patch for CVE-2025-14017

Best Practices

Use Macros

Always use RPM macros like %{_bindir} instead of hardcoded paths

Clean Buildroot

Remove .la files and fix permissions in %install

License Files

Mark license files with %license directive

Config Files

Use %config(noreplace) for user-editable configs

Test Coverage

Always include a %check section when tests are available

Detailed Changelog

Write clear, descriptive changelog entries

Common Pitfalls

Don’t hardcode paths - Use macros like %{_bindir} instead of /usr/bin

Don’t include buildroot in files - The %{buildroot} is stripped automatically

Don’t forget %defattr - Always set default file attributes in %files

Don’t skip changelog - Every package change needs a changelog entry

Next Steps

Package Repository

Learn about repository structure and organization

SPECS vs SPECS-EXTENDED

Understand package support levels

Overview

Quick Start

Building

Architecture

Image Configuration

Security

Advanced Topics

Package Management

Contributing

Creating RPM SPEC Files

SPEC File Structure

Preamble Section

Basic Metadata

Key Fields Explained

Subpackages

Build Sections

%prep - Prepare Sources

%build - Compile Software

%install - Install Files

%check - Run Tests

File Listings

Path Macros

File Attributes

Changelog

Changelog Format

Complete Examples

Best Practices

Use Macros

Clean Buildroot

License Files

Config Files

Test Coverage

Detailed Changelog

Common Pitfalls

Next Steps

Package Repository

SPECS vs SPECS-EXTENDED

Build docs developers (and LLMs) love

Overview

Quick Start

Building

Architecture

Image Configuration

Security

Advanced Topics

Package Management

Contributing

​SPEC File Structure

​Preamble Section

​Basic Metadata

​Key Fields Explained

​Subpackages

​Build Sections

​%prep - Prepare Sources

​%build - Compile Software

​%install - Install Files

​%check - Run Tests

​File Listings

​Path Macros

​File Attributes

​Changelog

​Changelog Format

​Complete Examples

​Best Practices

Use Macros

Clean Buildroot

License Files

Config Files

Test Coverage

Detailed Changelog

​Common Pitfalls

​Next Steps

Package Repository

SPECS vs SPECS-EXTENDED

Build docs developers (and LLMs) love

SPEC File Structure

Preamble Section

Basic Metadata

Key Fields Explained

Subpackages

Build Sections

%prep - Prepare Sources

%build - Compile Software

%install - Install Files

%check - Run Tests

File Listings

Path Macros

File Attributes

Changelog

Changelog Format

Complete Examples

Best Practices

Common Pitfalls

Next Steps