Chapter 4. Packaging software
In the following sections, learn the basics of the packaging process with the RPM package manager.
4.1. Setting up RPM packaging workspace
To build RPM packages, you must first create a special workspace that consists of directories used for different packaging purposes.
4.1.1. Configuring RPM packaging workspace
To configure the RPM packaging workspace, you can set up a directory layout by using the rpmdev-setuptree
utility.
Prerequisites
You installed the
rpmdevtools
package, which provides utilities for packaging RPMs:# dnf install rpmdevtools
Procedure
Run the
rpmdev-setuptree
utility:$ rpmdev-setuptree $ tree ~/rpmbuild/ /home/user/rpmbuild/ |-- BUILD |-- RPMS |-- SOURCES |-- SPECS `-- SRPMS 5 directories, 0 files
Additional resources
4.1.2. RPM packaging workspace directories
The following are the RPM packaging workspace directories created by using the rpmdev-setuptree
utility:
Directory | Purpose |
---|---|
|
Contains build artifacts compiled from the source files from the |
|
Binary RPMs are created under the |
|
Contains compressed source code archives and patches. The |
|
Contains |
|
When you use the |
4.2. About spec files
A spec
file is a file with instructions that the rpmbuild
utility uses to build an RPM package. This file provides necessary information to the build system by defining instructions in a series of sections. These sections are defined in the Preamble and the Body part of the spec
file:
- The Preamble section contains a series of metadata items that are used in the Body section.
- The Body section represents the main part of the instructions.
4.2.1. Preamble items
The following are some of the directives that you can use in the Preamble section of the RPM spec
file.
Directive | Definition |
---|---|
|
A base name of the package that must match the |
| An upstream version number of the software. |
| The number of times the version of the package was released.
Set the initial value to |
| A brief one-line summary of the package. |
| A license of the software being packaged.
The exact format for how to label the |
| A full URL for more information about the software, for example, an upstream project website for the software being packaged. |
| A path or URL to the compressed archive of the unpatched upstream source code. This link must point to an accessible and reliable storage of the archive, for example, the upstream page, not the packager’s local storage.
You can apply the |
| A name of the first patch to apply to the source code, if necessary.
You can apply the
You can apply the patches individually by using the |
| An architecture that the software will be built for.
If the software is not architecture-dependent, for example, if you wrote the software entirely in an interpreted programming language, set the value to |
|
A comma- or whitespace-separated list of packages required to build the program written in a compiled language. There can be multiple entries of |
|
A comma- or whitespace-separated list of packages required by the software to run once installed. There can be multiple entries of |
|
If a piece of software cannot operate on a specific processor architecture, you can exclude this architecture in the |
|
A comma- or whitespace-separated list of packages that must not be installed on the system in order for your software to function properly when installed. There can be multiple entries of |
|
The
|
|
If you add the |
The Name
, Version
, and Release
(NVR) directives comprise the file name of the RPM package in the name-version-release
format.
You can display the NVR information for a specific package by querying RPM database by using the rpm
command, for example:
# rpm -q bash
bash-4.4.19-7.el8.x86_64
Here, bash
is the package name, 4.4.19
is the version, and 7.el8
is the release. The x86_64
marker is the package architecture. Unlike NVR, the architecture marker is not under direct control of the RPM packager, but is defined by the rpmbuild
build environment. The exception to this is the architecture-independent noarch
package.
4.2.2. Body items
The following are the items used in the Body section of the RPM spec
file.
Directive | Definition |
---|---|
| A full description of the software packaged in the RPM. This description can span multiple lines and can be broken into paragraphs. |
|
A command or series of commands to prepare the software for building, for example, for unpacking the archive in the |
| A command or series of commands for building the software into machine code (for compiled languages) or bytecode (for some interpreted languages). |
|
A command or series of commands that the
The
Note that |
| A command or series of commands for testing the software, for example, unit tests. |
| A list of files, provided by the RPM package, to be installed in the user’s system and their full path location on the system.
During the build, if there are files in the
Within the |
|
A record of changes that happened to the package between different |
4.2.3. Advanced items
A spec
file can contain advanced items, such as Scriptlets or Triggers. Scriptlets and Triggers take effect at different points during the installation process on the end user’s system, not the build process.
4.3. BuildRoots
In the context of RPM packaging, buildroot
is a chroot
environment. The build artifacts are placed here by using the same file system hierarchy as the future hierarchy in the end user’s system, with buildroot
acting as the root directory. The placement of build artifacts must comply with the file system hierarchy standard of the end user’s system.
The files in buildroot
are later put into a cpio
archive, which becomes the main part of the RPM. When RPM is installed on the end user’s system, these files are extracted in the root
directory, preserving the correct hierarchy.
The rpmbuild
program has its own defaults. Overriding these defaults can cause certain issues. Therefore, avoid defining your own value of the buildroot
macro. Use the default %{buildroot}
macro instead.
4.4. RPM macros
An rpm macro is a straight text substitution that can be conditionally assigned based on the optional evaluation of a statement when certain built-in functionality is used. Therefore, RPM can perform text substitutions for you.
For example, you can define Version of the packaged software only once in the %{version}
macro, and use this macro throughout the spec
file. Every occurrence is automatically substituted by Version that you defined in the macro.
If you see an unfamiliar macro, you can evaluate it with the following command:
$ rpm --eval %{MACRO}
For example, to evaluate the %{_bindir}
and %{_libexecdir}
macros, enter:
$ rpm --eval %{_bindir} /usr/bin $ rpm --eval %{_libexecdir} /usr/libexec
4.5. Working with spec files
To package new software, you must create a spec
file. You can create the spec
file either of the following ways:
-
Write the new
spec
file manually from scratch. -
Use the
rpmdev-newspec
utility. This utility creates an unpopulatedspec
file, where you fill the necessary directives and fields.
Some programmer-focused text editors pre-populate a new spec
file with their own spec
template. The rpmdev-newspec
utility provides an editor-agnostic method.
4.5.1. Creating a new spec file for sample Bash, Python, and C programs
You can create a spec
file for each of the three implementations of the Hello World!
program by using the rpmdev-newspec
utility.
Prerequisites
The following
Hello World!
program implementations were placed into the~/rpmbuild/SOURCES
directory:
Procedure
Navigate to the
~/rpmbuild/SPECS
directory:$ cd ~/rpmbuild/SPECS
Create a
spec
file for each of the three implementations of theHello World!
program:$ rpmdev-newspec bello bello.spec created; type minimal, rpm version >= 4.11. $ rpmdev-newspec cello cello.spec created; type minimal, rpm version >= 4.11. $ rpmdev-newspec pello pello.spec created; type minimal, rpm version >= 4.11.
The
~/rpmbuild/SPECS/
directory now contains threespec
files namedbello.spec
,cello.spec
, andpello.spec
.Examine the created files.
The directives in the files represent those described in About spec files. In the following sections, you will populate a particular section in the output files of
rpmdev-newspec
.
4.5.2. Modifying an original spec file
The original output spec
file generated by the rpmdev-newspec
utility represents a template that you must modify to provide necessary instructions for the rpmbuild
utility. rpmbuild
then uses these instructions to build an RPM package.
Prerequisites
-
The unpopulated
~/rpmbuild/SPECS/<name>.spec
spec
file was created by using therpmdev-newspec
utility. For more information, see Creating a new spec file for sample Bash, Python, and C programs.
Procedure
-
Open the
~/rpmbuild/SPECS/<name>.spec
file provided by therpmdev-newspec
utility. Populate the following directives of the
spec
file Preamble section:Name
-
Name
was already specified as an argument torpmdev-newspec
. Version
-
Set
Version
to match the upstream release version of the source code. Release
-
Release
is automatically set to1%{?dist}
, which is initially1
. Summary
- Enter a one-line explanation of the package.
License
- Enter the software license associated with the source code.
URL
-
Enter the URL to the upstream software website. For consistency, utilize the
%{name}
RPM macro variable and use thehttps://example.com/%{name}
format. Source
Enter the URL to the upstream software source code. Link directly to the software version being packaged.
NoteThe example URLs in this documentation include hard-coded values that could possibly change in the future. Similarly, the release version can change as well. To simplify these potential future changes, use the
%{name}
and%{version}
macros. By using these macros, you need to update only one field in thespec
file.BuildRequires
- Specify build-time dependencies for the package.
Requires
- Specify run-time dependencies for the package.
BuildArch
- Specify the software architecture.
Populate the following directives of the
spec
file Body section. You can think of these directives as section headings, because these directives can define multi-line, multi-instruction, or scripted tasks to occur.%description
- Enter the full description of the software.
%prep
- Enter a command or series of commands to prepare software for building.
%build
- Enter a command or series of commands for building software.
%install
-
Enter a command or series of commands that instruct the
rpmbuild
command on how to install the software into theBUILDROOT
directory. %files
- Specify the list of files, provided by the RPM package, to be installed on your system.
%changelog
Enter the list of datestamped entries for each
Version-Release
of the package.Start the first line of the
%changelog
section with an asterisk (*
) character followed byDay-of-Week Month Day Year Name Surname <email> - Version-Release
.For the actual change entry, follow these rules:
- Each change entry can contain multiple items, one for each change.
- Each item starts on a new line.
-
Each item begins with a hyphen (
-
) character.
You have now written an entire spec
file for the required program.
Additional resources
4.5.3. An example spec file for a sample Bash program
You can use the following example spec
file for the bello program written in bash for your reference.
An example spec file for the bello program written in bash
Name: bello Version: 0.1 Release: 1%{?dist} Summary: Hello World example implemented in bash script License: GPLv3+ URL: https://www.example.com/%{name} Source0: https://www.example.com/%{name}/releases/%{name}-%{version}.tar.gz Requires: bash BuildArch: noarch %description The long-tail description for our Hello World Example implemented in bash script. %prep %setup -q %build %install mkdir -p %{buildroot}/%{_bindir} install -m 0755 %{name} %{buildroot}/%{_bindir}/%{name} %files %license LICENSE %{_bindir}/%{name} %changelog * Tue May 31 2016 Adam Miller <maxamillion@fedoraproject.org> - 0.1-1 - First bello package - Example second item in the changelog for version-release 0.1-1
-
The
BuildRequires
directive, which specifies build-time dependencies for the package, was deleted because there is no building step forbello
. Bash is a raw interpreted programming language, and the files are just installed to their location on the system. -
The
Requires
directive, which specifies run-time dependencies for the package, includes onlybash
, because thebello
script requires only thebash
shell environment to execute. -
The
%build
section, which specifies how to build the software, is blank, because thebash
script does not need to be built.
To install bello
, you must create the destination directory and install the executable bash
script file there. Therefore, you can use the install
command in the %install
section. You can use RPM macros to do this without hardcoding paths.
Additional resources
4.5.4. An example spec file for a sample Python program
You can use the following example spec
file for the pello program written in the Python programming language for your reference.
An example spec file for the pello program written in Python
Name: pello Version: 0.1.1 Release: 1%{?dist} Summary: Hello World example implemented in Python License: GPLv3+ URL: https://www.example.com/%{name} Source0: https://www.example.com/%{name}/releases/%{name}-%{version}.tar.gz BuildRequires: python Requires: python Requires: bash BuildArch: noarch %description The long-tail description for our Hello World Example implemented in Python. %prep %setup -q %build python -m compileall %{name}.py %install mkdir -p %{buildroot}/%{_bindir} mkdir -p %{buildroot}/usr/lib/%{name} cat > %{buildroot}/%{_bindir}/%{name} <<EOF #!/bin/bash /usr/bin/python /usr/lib/%{name}/%{name}.pyc EOF chmod 0755 %{buildroot}/%{_bindir}/%{name} install -m 0644 %{name}.py* %{buildroot}/usr/lib/%{name}/ %files %license LICENSE %dir /usr/lib/%{name}/ %{_bindir}/%{name} /usr/lib/%{name}/%{name}.py* %changelog * Tue May 31 2016 Adam Miller <maxamillion@fedoraproject.org> - 0.1.1-1 - First pello package
The
Requires
directive, which specifies run-time dependencies for the package, includes two packages:-
The
python
package required to execute the byte-compiled code at runtime. -
The
bash
package required to execute the small entry-point script.
-
The
-
The
BuildRequires
directive, which specifies build-time dependencies for the package, includes only thepython
package. Thepello
program requirespython
to perform the byte-compile build process. -
The
%build
section, which specifies how to build the software, creates a byte-compiled version of the script. Note that in real-world packaging, it is usually done automatically, depending on the distribution used. -
The
%install
section corresponds to the fact that you must install the byte-compiled file into a library directory on the system so that it can be accessed.
This example of creating a wrapper script in-line in the spec
file shows that the spec
file itself is scriptable. This wrapper script executes the Python byte-compiled code by using the here document
.
Additional resources
4.5.5. An example spec file for a sample C program
You can use the following example spec
file for the cello program that was written in the C programming language for your reference.
An example spec file for the cello program written in C
Name: cello Version: 1.0 Release: 1%{?dist} Summary: Hello World example implemented in C License: GPLv3+ URL: https://www.example.com/%{name} Source0: https://www.example.com/%{name}/releases/%{name}-%{version}.tar.gz Patch0: cello-output-first-patch.patch BuildRequires: gcc BuildRequires: make %description The long-tail description for our Hello World Example implemented in C. %prep %setup -q %patch0 %build make %{?_smp_mflags} %install %make_install %files %license LICENSE %{_bindir}/%{name} %changelog * Tue May 31 2016 Adam Miller <maxamillion@fedoraproject.org> - 1.0-1 - First cello package
The
BuildRequires
directive, which specifies build-time dependencies for the package, includes the following packages required to perform the compilation build process:-
gcc
-
make
-
-
The
Requires
directive, which specifies run-time dependencies for the package, is omitted in this example. All runtime requirements are handled byrpmbuild
, and thecello
program does not require anything outside of the core C standard libraries. -
The
%build
section reflects the fact that in this example theMakefile
file for the cello program was written. Therefore, you can use the GNU make command. However, you must remove the call to%configure
because you did not provide a configure script.
You can install the cello program by using the %make_install
macro. This is possible because the Makefile
file for the cello program is available.
Additional resources
4.6. Building RPMs
You can build RPM packages by using the rpmbuild
command. When using this command, a certain directory and file structure is expected, which is the same as the structure that was set up by the rpmdev-setuptree
utility.
Different use cases and desired outcomes require different combinations of arguments to the rpmbuild
command. The following are the main use cases:
- Building source RPMs.
Building binary RPMs:
- Rebuilding a binary RPM from a source RPM.
-
Building a binary RPM from the
spec
file.
4.6.1. Building a source RPM
Building a Source RPM (SRPM) has the following advantages:
-
You can preserve the exact source of a certain
Name-Version-Release
of an RPM file that was deployed to an environment. This includes the exactspec
file, the source code, and all relevant patches. This is useful for tracking and debugging purposes. - You can build a binary RPM on a different hardware platform or architecture.
Prerequisites
You have installed the
rpmbuild
utility on your system:# dnf install rpm-build
The following
Hello World!
implementations were placed into the~/rpmbuild/SOURCES/
directory:-
A
spec
file for the program that you want to package exists.
Procedure
Navigate to the
~/rpmbuild/SPECS/
directive, which contains the createdspec
file:$ cd ~/rpmbuild/SPECS/
Build the source RPM by entering the
rpmbuild
command with the specifiedspec
file:$ rpmbuild -bs <specfile>
The
-bs
option stands for the build source.For example, to build source RPMs for the
bello
,pello
, andcello
programs, enter:$ rpmbuild -bs bello.spec Wrote: /home/admiller/rpmbuild/SRPMS/bello-0.1-1.el8.src.rpm $ rpmbuild -bs pello.spec Wrote: /home/admiller/rpmbuild/SRPMS/pello-0.1.2-1.el8.src.rpm $ rpmbuild -bs cello.spec Wrote: /home/admiller/rpmbuild/SRPMS/cello-1.0-1.el8.src.rpm
Verification
-
Verify that the
rpmbuild/SRPMS
directory includes the resulting source RPMs. The directory is a part of the structure expected byrpmbuild
.
Additional resources
4.6.2. Rebuilding a binary RPM from a source RPM
To rebuild a binary RPM from a source RPM (SRPM), use the rpmbuild
command with the --rebuild
option.
The output generated when creating the binary RPM is verbose, which is helpful for debugging. The output varies for different examples and corresponds to their spec
files.
The resulting binary RPMs are located in either of the following directories:
-
~/rpmbuild/RPMS/YOURARCH
, whereYOURARCH
is your architecture. -
~/rpmbuild/RPMS/noarch/
, if the package is not architecture-specific.
Prerequisites
You have installed the
rpmbuild
utility on your system:# dnf install rpm-build
Procedure
Navigate to the
~/rpmbuild/SRPMS/
directive, which contains the SRPM:$ cd ~/rpmbuild/SRPMS/
Rebuild the binary RPM from the SRPM:
$ rpmbuild --rebuild <srpm>
For example, to rebuild
bello
,pello
, andcello
from their SRPMs, enter:$ rpmbuild --rebuild bello-0.1-1.el8.src.rpm [output truncated] $ rpmbuild --rebuild pello-0.1.2-1.el8.src.rpm [output truncated] $ rpmbuild --rebuild cello-1.0-1.el8.src.rpm [output truncated]
Invoking rpmbuild --rebuild
involves the following processes:
-
Installing the contents of the SRPM (the
spec
file and the source code) into the~/rpmbuild/
directory. - Building an RPM by using the installed contents.
-
Removing the
spec
file and the source code.
You can retain the spec
file and the source code after building either of the following ways:
-
When building the RPM, use the
rpmbuild
command with the--recompile
option instead of the--rebuild
option. Install SRPMs for
bello
,pello
, andcello
:$ rpm -Uvh ~/rpmbuild/SRPMS/bello-0.1-1.el8.src.rpm Updating / installing… 1:bello-0.1-1.el8 [100%] $ rpm -Uvh ~/rpmbuild/SRPMS/pello-0.1.2-1.el8.src.rpm Updating / installing… …1:pello-0.1.2-1.el8 [100%] $ rpm -Uvh ~/rpmbuild/SRPMS/cello-1.0-1.el8.src.rpm Updating / installing… …1:cello-1.0-1.el8 [100%]
4.6.3. Building a binary RPM from a spec file
To build a binary RPM from its spec
file, use the rpmbuild
command with the -bb
option.
Prerequisites
You have installed the
rpmbuild
utility on your system:# dnf install rpm-build
Procedure
Navigate to the
~/rpmbuild/SPECS/
directive, which containsspec
files:$ cd ~/rpmbuild/SPECS/
Build the binary RPM from its
spec
:$ rpmbuild -bb <spec_file>
For example, to build
bello
,pello
, andcello
binary RPMs from theirspec
files, enter:$ rpmbuild -bb bello.spec $ rpmbuild -bb pello.spec $ rpmbuild -bb cello.spec
4.7. Logging RPM activity to syslog
You can log any RPM activity or transaction by using the System Logging protocol (syslog
).
Prerequisites
The
syslog
plug-in is installed on the system:# dnf install rpm-plugin-syslog
NoteThe default location for the
syslog
messages is the/var/log/messages
file. However, you can configuresyslog
to use another location to store the messages.
Procedure
Open the file that you configured to store the
syslog
messages.Alternatively, if you use the default
syslog
configuration, open the/var/log/messages
file.-
Search for new lines including the
[RPM]
string.
4.8. Extracting RPM content
In some cases, for example, if a package required by RPM is damaged, you might need to extract the content of the package. In such cases, if an RPM installation is still working despite the damage, you can use the rpm2archive
utility to convert an .rpm
file to a tar archive to use the content of the package.
If the RPM installation is severely damaged, you can use the rpm2cpio
utility to convert the RPM package file to a cpio
archive.
Procedure
Convert the RPM file to the tar archive:
$ rpm2archive <filename>.rpm
The resulting file has the
.tgz
suffix. For example, to create an archive from thebash
package, enter:$ rpm2archive bash-4.4.19-6.el8.x86_64.rpm $ ls bash-4.4.19-6.el8.x86_64.rpm.tgz bash-4.4.19-6.el8.x86_64.rpm.tgz