Rpm package manifest file

Both types share the file format and tooling, but have different contents and serve different purposes:. Optionally, the patches to source code are included as well. The following procedure describes how to list the utilities provided by the rpmdevtools package.

You installed the rpmdevtools package, which provides several utilities for packaging RPMs:. This section describes how to set up a directory layout that is the RPM packaging workspace by using the rpmdev-setuptree utility. This is useful for investigating a failed build if the logs output do not provide enough information. Here, the packager puts compressed source code archives and patches. The rpmbuild command looks for them here.

A SPEC file provides necessary information to the build system by defining instructions in a series of sections.

The sections are defined in the Preamble and the Body part. The Preamble part contains a series of metadata items that are used in the Body part. The Body part represents the main part of the instructions. Table 3. The number of times this version of the software was released.

Reset to 1 when a new Version of the software is built. The full URL for more information about the program. Most often this is the upstream project website for the software being packaged. Path or URL to the compressed archive of the upstream source code unpatched, patches are handled elsewhere. If needed, more SourceX directives can be added, incrementing the number each time, for example: Source1, Source2, Source3, and so on.

If no number is given, one is assigned to the entry internally. It is also possible to give the numbers explicitly using Patch0, Patch1, Patch2, Patch3, and so on. If the package is not architecture dependent, for example, if written entirely in an interpreted programming language, set this to BuildArch: noarch. A comma or whitespace-separated list of packages required for building the program written in a compiled language.

A comma- or whitespace-separated list of packages required by the software to run once installed. If a piece of software can not operate on a specific processor architecture, you can exclude that architecture here. Conflicts are inverse to Requires. If there is a package matching Conflicts , the package cannot be installed independently on whether the Conflict tag is on the package that has already been installed or on a package that is going to be installed.

This directive alters the way updates work depending on whether the rpm command is used directly on the command line or the update is performed by an updates or dependency solver. When used on a command line, RPM removes all packages matching obsoletes of packages being installed. When using an update or dependency resolver, packages containing matching Obsoletes: are added as updates and replace the matching packages. If Provides is added to a package, the package can be referred to by dependencies other than its name.

The following example shows how to obtain the NVR information for a specific package by querying the rpm command. Example 3. Querying rpm to provide the NVR information for the bash package.

Here, bash is the package name, 4. Unlike the 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. A full description of the software packaged in the RPM. This description can span multiple lines and can be broken into paragraphs. Command or series of commands to prepare the software to be built, for example, unpacking the archive in Source0. This directive can contain a shell script.

Command or series of commands for building the software into machine code for compiled languages or byte code for some interpreted languages. This is only run when creating a package, not when the end-user installs the package.

Command or series of commands to test the software. This normally includes things such as unit tests. A record of changes that have happened to the package between different Version or Release builds. In the context of RPM packaging, buildroot is a chroot environment. The files in buildroot are later put into a cpio archive, which becomes the main part of the RPM.

Starting from Red Hat Enterprise Linux 6, the rpmbuild program has its own defaults. Overriding these defaults leads to several problems; hence, Red Hat does not recommend to define your own value of this macro. 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. Hence, RPM can perform text substitutions for you. Every occurrence will be automatically substituted by Version that you defined previously.

This utility creates an unpopulated SPEC file, and you fill in the necessary directives and fields. Some programmer-focused text editors pre-populate a new. The rpmdev-newspec utility provides an editor-agnostic method.

The following sections use the three example implementations of the Hello World! A program written in a raw interpreted programming language. It demonstrates when the source code does not need to be built, but only needs to be installed. If a pre-compiled binary needs to be packaged, you can also use this method since the binary would also just be a file. A program written in a byte-compiled interpreted programming language.

It demonstrates byte-compiling the source code and installating the bytecode - the resulting pre-optimized files.

A program written in a natively compiled programming language. It demonstrates a common process of compiling the source code into machine code and installing the resulting executables. In the following sections, you will populate particular section in the output files of rpmdev-newspec. The rpmdev-newspec utility does not use guidelines or conventions specific to any particular Linux distribution.

The first section includes these directives that rpmdev-newspec grouped together:. The License field is the Software License associated with the source code from the upstream release. The Source0 field provides URL to the upstream software source code. It should link directly to the specific version of software that is being packaged. Note that the example URLs given in this documentation include hard-coded values that are possible subject to change in the future.

Similarly, the release version can change as well. By using these, you need to update only one field in the SPEC file. BuildRequires specifies build-time dependencies for the package. Ultimately the payload of the resulting Binary RPM is extracted from this environment and put into the cpio archive. A 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.

An example of how this can be extremely useful for a RPM Packager is if we wanted to reference the Version of the software we are packaging multiple times through out our SPEC file but only want to define it one time.

One handy utility of the rpm command for packagers is the --eval flag which allows you to ask rpm to evaluate a macro. For more information, please reference the More on Macros section of the Appendix. The spec file is the recipe we use to tell rpmbuild how to actually perform a build.

In this section we will discuss how to create and modify a spec file. When it comes time to package new software, a new SPEC file must be created.

This utility will create a new spec file for us. We will just fill in the various directives or add new fields as needed. This provides us with a nice baseline template. Some programmer focused text editors will pre-populate a new file with the extension.

Take a moment to look at the files using your favorite text editor, the directives should look familiar from the What is a SPEC File? We will discuss the exact information we will input into these fields in the following sections that will focus specifically on each example. The rpmdev-newspec utility does not use Linux Distribution specific guidelines or conventions, however this document is targeted towards using conventions and guidelines for Fedora , CentOS , and RHEL so you will notice:.

There are three examples below, each one is meant to be self-sufficient in instruction such that you can jump to a specific one if it matches your needs for packaging. However, feel free to read them straight through for a full exploration of packaging different kinds of software.

The following is the output template we were given from rpmdev-newspec. Let us begin with the first set of directives that rpmdev-newspec has grouped together at the top of the file: Name , Version , Release , Summary. The Name is already specified because we provided that information to the command line for rpmdev-newspec. When a new upstream release happens for example, bello version 0. The Summary should be a short, one-line explanation of what this software is.

The License field is the Software License associated with the source code from the upstream release. We can simplify this by only needing to update one field in the SPEC file and allowing it to be reused. Next up we have BuildRequires and Requires , each of which define something that is required by the package.

However, BuildRequires is to tell rpmbuild what is needed by your package at build time and Requires is what is needed by your package at run time.

In this example there is no build because the bash script is a raw interpreted programming language so we will only be installing files into locations on the system, but it does require the bash shell environment in order to execute so we will need to define bash as a requirement using the Requires directive. Something we need to add here since this is software written in an interpreted programming language with no natively compiled extensions is a BuildArch entry that is set to noarch in order to tell RPM that this package does not need to be bound to the processor architecture that it is built using.

We will walk through them one by one just as we did with the previous items. Most often what happens here is the expansion of compressed archives of the source code, application of patches, and potentially parsing of information provided in the source code that is necessary in a later portion of the SPEC. However, our RPM Macros help us accomplish this task without having to hardcode paths. Also within this section, you will sometimes need a built-in macro to provide context on a file.

This can be useful for Systems Administrators and end users who might want to query the system with rpm about the resulting package. This is not meant to be a log of what changed in the software from release to release, but specifically to packaging changes. Each change entry can contain multiple items and each item should start on a new line and begin with a - character.

Below is our example entry:. From there we have a - character before the Version-Release, which is an often used convention but not a requirement. Then finally the Version-Release. In the next section we will cover how to build the RPM! Before we start down this path, we need to address something somewhat unique about byte-compiled interpreted software.

Since we we will be byte-compiling this program, the shebang is no longer applicable because the resulting file will not contain the entry.

This might seem silly for our small example but for large software projects with many thousands of lines of code, the performance increase of pre-byte-compiled code is sizeable. The creation of a script to call the byte-compiled code or having a non-byte-compiled entry point into the software is something that upstream software developers most often address before doing a release of their software to the world, however this is not always the case and this exercise is meant to help address what to do in those situations.

For more information on how Python code is normally released and distributed please reference the Software Packaging and Distribution documentation. We will make a small shell script to call our byte compiled code to be the entry point into our software. When a new upstream release happens for example, pello version 0. We should note that this example URL has hard coded values in it that are possible to change in the future and are potentially even likely to change such as the release version 0.

In this example we will need the python package in order to perform the byte-compile build process. We will also need the python package in order to execute the byte-compiled code at runtime and therefore need to define python as a requirement using the Requires directive.

We will also need the bash package in order to execute the small entry-point script we will use here. Here we will perform a byte-compilation of our software. For those who read the General Topics and Background Section, this portion of the example should look familiar.

We had previously discussed that since we will lose the context of a file with the shebang line in it when we byte compile that we will need to create a simple wrapper script in order to accomplish that task. The reason for showing the example option that we are is simply to demonstrate that the SPEC file itself is scriptable. We will also need to actually install the byte-compiled file into a library directory on the system such that it can be accessed.

Here, the packager puts compressed source code archives and patches. The rpmbuild command looks for them here. A SPEC file provides necessary information to the build system by defining instructions in a series of sections. The sections are defined in the Preamble and the Body part. The Preamble part contains a series of metadata items that are used in the Body part.

The Body part represents the main part of the instructions. Table 3. The number of times this version of the software was released. Reset to 1 when a new Version of the software is built. The full URL for more information about the program. Most often this is the upstream project website for the software being packaged.

Path or URL to the compressed archive of the upstream source code unpatched, patches are handled elsewhere. If needed, more SourceX directives can be added, incrementing the number each time, for example: Source1, Source2, Source3, and so on. The directive can be applied in two ways: with or without numbers at the end of Patch. If no number is given, one is assigned to the entry internally.

It is also possible to give the numbers explicitly using Patch0, Patch1, Patch2, Patch3, and so on. If the package is not architecture dependent, for example, if written entirely in an interpreted programming language, set this to BuildArch: noarch. A comma or whitespace-separated list of packages required for building the program written in a compiled language.

A comma- or whitespace-separated list of packages required by the software to run once installed. If a piece of software can not operate on a specific processor architecture, you can exclude that architecture here.

Conflicts are inverse to Requires. If there is a package matching Conflicts , the package cannot be installed independently on whether the Conflict tag is on the package that has already been installed or on a package that is going to be installed. This directive alters the way updates work depending on whether the rpm command is used directly on the command line or the update is performed by an updates or dependency solver.

When used on a command line, RPM removes all packages matching obsoletes of packages being installed. When using an update or dependency resolver, packages containing matching Obsoletes: are added as updates and replace the matching packages.

If Provides is added to a package, the package can be referred to by dependencies other than its name. The following example shows how to obtain the NVR information for a specific package by querying the rpm command.

Example 3. Querying rpm to provide the NVR information for the bash package. Here, bash is the package name, 4. Unlike the 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. A full description of the software packaged in the RPM. This description can span multiple lines and can be broken into paragraphs. Command or series of commands to prepare the software to be built, for example, unpacking the archive in Source0. This directive can contain a shell script. Command or series of commands for building the software into machine code for compiled languages or byte code for some interpreted languages.

This is only run when creating a package, not when the end-user installs the package. See Section 3. Command or series of commands to test the software.

This normally includes things such as unit tests. A record of changes that have happened to the package between different Version or Release builds. In the context of RPM packaging, buildroot is a chroot environment.

The files in buildroot are later put into a cpio archive, which becomes the main part of the RPM. Starting from 6, the rpmbuild program has its own defaults. 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. Hence, RPM can perform text substitutions for you. Every occurrence will be automatically substituted by Version that you defined previously.

This section uses the three example implementations of the Hello World! A program written in a raw interpreted programming language. It demonstrates when the source code does not need to be built, but only needs to be installed.

If a pre-compiled binary needs to be packaged, you can also use this method since the binary would also just be a file. A program written in a byte-compiled interpreted programming language. It demonstrates byte-compiling the source code and installating the bytecode - the resulting pre-optimized files. A program written in a natively compiled programming language.

It demonstrates a common process of compiling the source code into machine code and installing the resulting executables. This utility creates an unpopulated SPEC file, and you fill in the necessary directives and fields. Some programmer-focused text editors pre-populate a new. The rpmdev-newspec utility provides an editor-agnostic method.

The rpmdev-newspec utility does not use guidelines or conventions specific to any particular Linux distribution. The first section includes these directives that rpmdev-newspec grouped together:. The Name was already specified as an argument to rpmdev-newspec. Set the Version to match the upstream release version of the source code. Increment the initial value whenever updating the package without a change in the upstream release Version - such as when including a patch.

Reset Release to 1 when a new upstream release happens. The Summary is a short, one-line explanation of what this software is. The License field is the Software License associated with the source code from the upstream release. The Source0 field provides URL to the upstream software source code. It should link directly to the specific version of software that is being packaged. Note that the example URLs given in this documentation include hard-coded values that are possible subject to change in the future.

Similarly, the release version can change as well. By using these, you need to update only one field in the SPEC file. BuildRequires specifies build-time dependencies for the package. Requires specifies run-time dependencies for the package. This is a software written in an interpreted programming language with no natively compiled extensions.

Hence, add the BuildArch directive with the noarch value. This tells RPM that this package does not need to be bound to the processor architecture on which it is built. These directives can be thought of as section headings, because they are directives that can define multi-line, multi-instruction, or scripted tasks to occur. This usually involves expansion of compressed archives of the source code, application of patches, and, potentially, parsing of information provided in the source code for use in a later portion of the SPEC file.

Here you can create any directories that will contain the installed files. To create such directories, you can use the RPM macros without having to hardcode the paths. Within this section, you can indicate the role of various files using built-in macros.

This is useful for querying the package file manifest metadata using the command[] rpm command. They log packaging changes, not software changes. This section shows an example SPEC file for the bello program that was written in bash. For more information about bello , see Section 2. An example SPEC file for the bello program written in bash. Name: bello Version: 0. The BuildRequires directive, which specifies build-time dependencies for the package, was deleted because there is no building step for bello.

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, include only bash , because the bello script requires only the bash shell environment to execute.

For installing bello you only need to create the destination directory and install the executable bash script file there. RPM macros allow to do this without hardcoding paths. This section shows an example SPEC file for the pello program written in the Python programming language. For more information about pello , see Section 2. Name: pello Version: 0. The pello program is written in a byte-compiled interpreted language. Hence, the shebang is not applicable because the resulting file does not contain the entry.

Because the shebang is not applicable, you may want to apply one of the following approaches:. These approaches are useful especially for large software projects with many thousands of lines of code, where the performance increase of pre-byte-compiled code is sizeable. The BuildRequires directive, which specifies build-time dependencies for the package, includes two packages:.

The Requires directive, which specifies run-time dependencies for the package, includes only the python package. The pello program requires the python package to execute the byte-compiled code at runtime. To install pello , you need to create a wrapper script because the shebang is not applicable in byte-compiled languages.

There are multiple options to accomplish this, such as:. This wrapper script will execute the Python byte-compiled code by using a here document. This section shows an example SPEC file for the cello program that was written in the C programming language. For more information about cello , see Section 2. Name: cello Version: 1. The BuildRequires directive, which specifies build-time dependencies for the package, includes two packages that are needed to perform the compilation build process:.

The Requires directive, which specifies run-time dependencies for the package, is omitted in this example. All runtime requirements are handled by rpmbuild , and the cello program does not require anything outside of the core C standard libraries. This is possible because the Makefile for the cello program is available. RPMs are built with the rpmbuild command. This command expects a certain directory and file structure, 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. This section describes the two main use cases:. A SPEC file for the program that we want to package must already exist. Run the rpmbuild command with the specified SPEC file:.

The -bs option stands for the build source. The following example shows building source RPMs for the bello , pello , and cello projects. To rebuild bello , pello , and cello from their SRPMs, run:. The output generated when creating a binary RPM is verbose, which is helpful for debugging. The output varies for different examples and corresponds to their SPEC files. Run the rpmbuild command with the bb option:. To do so, use the following procedure. Run the rpmbuild command with one of the below options and with the source package specified:.

The main tool for checking package quality is rpmlint. Note that rpmlint has very strict guidelines; hence it is sometimes acceptable to skip some of its errors and warnings, as shown in the following examples. In the following examples, rpmlint is run without any options, which produces a non-verbose output.

For detailed explanations of each error or warning, you can run rpmlint -i instead. Output of running the rpmlint command on the SPEC file for bello. For bello. This is expected, because the specified example. Presuming that we expect this URL to work in the future, we can ignore this warning. Output of running the rpmlint command on the SRPM for bello.

Assuming the link will be working in the future, we can ignore this warning. When checking binary RPMs, rpmlint checks for the following items:. Output of running the rpmlint command on the binary RPM for bello. The no-documentation and no-manual-page-for-binary warnings say that he RPM has no documentation or manual pages, because we did not provide any.

Apart from the above warnings, the RPM passed rpmlint checks. Output of running the rpmlint command on the SPEC file for pello. Presuming that this URL will work in the future, you can ignore this warning. For the sake of this example, you can safely ignore these errors. However, for packages going into production make sure to check all errors carefully. Output of running the rpmlint command on the SRPM for pello. Assuming that the URL will be valid in the future, you can safely ignore this error.

Output of running the rpmlint command on the binary RPM for pello. The no-documentation and no-manual-page-for-binary warnings say that the RPM has no documentation or manual pages, because you did not provide any. This directory is normally reserved for shared object files, which are binary files.

This is an example of an rpmlint check for compliance with Filesystem Hierarchy Standard. Normally, use RPM macros to ensure the correct placement of files. For the sake of this example, you can safely ignore this warning. The rpmlint tool expects the file to be executable, because the file contains the shebang.

For the purpose of this example, you can leave this file without execute permissions and ignore this error. Apart from the above warnings and errors, the RPM passed rpmlint checks. Output of running the rpmlint command on the SPEC file for cello. For cello. Output of running the rpmlint command on the SRPM for cello. Assuming the link will be working in the future, you can ignore this warning.

Output of running the rpmlint command on the binary RPM for cello. The no-documentation and no-manual-page-for-binary warnings say that he RPM has no documentation or manual pages, because you did not provide any. This section covers topics that are beyond the scope of the introductory tutorial but are useful in real-world RPM packaging.