Packaging Tutorial: GNU Hello

Follow Installing Packager Tools.

We need the source code of the project we are packaging, often referred to as the upstream source. We will download it from the project’s website into a directory we create for packaging GNU Hello. We are getting the compressed tarball archive, which happens to be the preferred distribution form for most FOSS projects.

The RPM package is configured by .spec files. We will create a template file hello.spec:

The fields in our .spec file need slight editing. Please follow RPM Reference Manual’s section Spec file format for these fields. In our case, the file might start as follows:

The Version should mirror the upstream, while Release numbers our work within Fedora.

The first letter of the Summary should be uppercase to avoid rpmlint complaints.

Often, Summary and %description can be copied from the upstream README.

It is your responsibility to check the License status of the software. Inspect the source files and their LICENSE files, and talk to the authors as needed.

The %changelog should document the work on preparing the RPM, especially if there are security and bug patches included on top of the base upstream source. Changelog data can be displayed by rpm --query --changelog PACKAGE_NAME, which is very useful, for instance, to find out if specific bug and security patches were included in the installed software, thanks to the diligent Fedora packagers who include this info with the relevant CVE numbers.

The %changelog entry should include the version string to avoid rpmlint complaints.

Multi-line sections like %changelog or %description start on a line under the directive, and end when the next section starts or the file ends.

Lines which are not needed (e.g. BuildRequires and Requires) can be commented out with the hash # for now.

In many cases, many lines in the template do not need to be changed at all, at least for the initial attempt.

We are ready for the first run to build source, binary and debugging packages. This, and many other tasks, are done with the fedpkg tool. The production builds for Fedora are built in the Koji build system, which in turn uses Mock to manage isolated build environments. To get as close to a production build as is locally possible, we use the fedpkg mockbuild command which also invokes Mock:

The build environment created by Mock is very basic. It does not include a C compiler by default, so the build will fail. The reason is explained in the output:

Additional build tools are defined by adding BuildRequires: rows to the specfile. In Fedora, GCC is the standard compiler, so we need to add a row for gcc. GNU Hello also uses make, so a row should be added for it, too. Add these lines after Source:

Run a mockbuild again. The earlier error should be gone.

The next thing rpm will complain about are unpackaged files, i.e. the files that would be installed in the system, but were not declared as belonging to the package. We need to declare them in the %files section. Fixing these errors is an iterative process. After declaring a missing file in the .spec file, run fedpkg again, then declare the next missing file and so on.

We will go through the file list one by one.

GNU Hello, like many other projects, includes an automated test suite in the sources. If at all possible, the test suite should be run during the rpm build. This helps ensuring that a working build was produced. This is done by adding the test suite invocation to specfile %check% section, which comes after %install in order. In GNU Hello’s case:

Run a mockbuild again and check the output to ensure that the tests were actually run. Something like this should be somewhere in the output:

Next you should check them for conformance with RPM design rules, by running rpmlint on specfile, source rpm and binary rpm. Command fedpkg lint does this:

If all is good, there should be no warnings or errors. In the GNU Hello case, one warning can be expected:

Descriptions of various error codes can be queried with rpmlint -e <error_code>. In this case, in order to ensure a pure utf-8 installation, the file needs to be converted in %prep. This can be done with the iconv utility:

Run fedpkg lint again and observe that the warning is fixed.

Here is the initial version of hello.spec:

With this .spec file, you should be able to successfully complete the build process, and create the source and binary RPM packages.

Having a working specfile and rpms built from it, the result can be checked. Before checking the result by installing the package, let us do some simple checks. The RPM Package Manager rpm can be used for this.

Even though the package is not part of Fedora distrubution yet, a scratch build can be performed to ensure that the package builds successfully in Fedora’s Koji build system, and that it builds successfully for all architectures supported by Fedora. Such build is started by passing a source rpm package to fedpkg scratch-build.

Note that Koji uses Kerberos for authentication. See Acquiring Kerberos Ticket for details.

You can open the task info link in a browser to view build progress, logs and results. The command line program also reports on progress as it happens. Successful execution looks something like this: