2. The build header

The build header section consists of lines of text in the Header: value format. Arbitrary comments are preceded by the # character, and are ignored, as well as blank lines.

The Name:, Version:, and Release: lines must be present, the remaining lines are optional. The following lines may appear in any order:

Name: n

n is the name of the application, which becomes the name of the package. The package name cannot contain control characters or spaces. The following punctuation characters are prohibited: /()=<>!. The name cannot begin or end with a hyphen, or contain two hyphens in a row. See Section 1, “NAVR - name, architecture, version, release” for more information on package names.

Version: v

v is the application's version label.

Release: r

r is the release label. The package version and release cannot contain control characters or spaces. The following punctuation characters are also prohibited: -/=!<>(). See Section 1, “NAVR - name, architecture, version, release” for more information on version and release labels, and how they are used.


lpbuild automatically appends the base distribution name (the %__distribution_name predefined macro).

BuildRequires: resourcelist

resourcelist must be installed in order to build this application. LPMtool verifies that the listed resources are installed, before proceeding to build the application.

ExclusiveArch: list

Specifies that this application can only be built for hardware platforms in list. Example:

ExclusiveArch: i386 x86_64

lpbuild will quietly terminate, without doing anything, if an attempt is made to build this application for any other platform. This is the desired behavior when doing a mass-build of a set of packages for multiple hardware platforms. Packages which are not meant to be built for a specific hardware platform will be quietly skipped.

When ExclusiveArch: is not present lpbuild will build the application for any hardware platform.

BuildArch: list

BuildArch: specifies the platform build list. The default platform build list contains a single platform: the lpbuild command's native platform.

lpbuild determines the build platform, or platforms, in two steps. First, if the target build platform is not listed in ExclusiveArch: nothing gets built. Otherwise, lpbuild goes through the list of platforms in BuildArch: and builds the application for each platform, in turn.

As mentioned in Section 1, “NAVR - name, architecture, version, release”, packages with contents that are not specific to any hardware platform are labeled for a dummy platform called noarch.

Normally, lpbuild builds packages for the same native platform that lpbuild runs on: running lpbuild on an Intel 32-bit platform produces i386 packages; and running lpbuild on an Opteron-based platform produces x86_64 packages. If, instead, a specfile has a BuildArch: noarch lpbuild will then produce noarch in both cases.

Consider an application that includes i686-specific optimizations when compiled on an Intel 32-bit platform:

Name: testpackage
Version: 1
Release: 1
Source: test-1.tar.gz

%if %{=__platform: i386}
BuildArch: i686


The %if (also %endif) is a macro. Macros are described in detail in Section 13.6, “Conditional text inclusion”, but what's important here is that these macros cause lpbuild to see the line with BuildArch: only when lpbuild runs on an Intel 32-bit platform (or is specifically requested to cross-compile to IA32). Normally lpbuild will produce, by default, packages labeled for the i386 platform. In this case lpbuild will be instructed to label the resulting package as an i686 package.

lpbuild should not see the BuildArch: line on any other platform (this is what the %if-%endif magic does). Otherwise, if lpbuild runs on, say, a sparc architecture, the resulting packages will be incorrectly labeled i686, when they really contain sparc code.

All packages, and subpackages, created by lpbuild will have the same architecture label. If BuildArch:'s list has more than one platform, lpbuild automatically runs the specfile multiple times, one for each platform. Example:

BuildArch: %{__platform} noarch

%{__platform} results in lpbuild seeing i386 noarch on an Intel 32-bit platform, sparc noarch on a Sparc platform, and so on.

lpbuild will now run the rest of the specfile twice, once for the target platform, and a second time for the noarch platform. This usually happens with applications that have a main platform-specific package, and a subpackage that contains only non-platform specific documentation. The first pass over the specfile generates the main platform-specific package. The platform-independent documentation subpackage is created when lpbuild runs processes the specfile for the second time.

See Section 14, “Multiple platform builds” for more information on multi-platform builds.

Source: filename

The source code for the application is in filename. Use Source2:, Source3:, etc..., when the source code comes in multiple files. Example:

Source: wordmasher-1.0.tar.gz
Source2: wordmasher-docs-1.0.tar.gz

Any directory part of filename is ignored. The source files must always be present in the current directory.

If the specified source file does not exist in the current directory, and filename is an http or an https URL, lpbuild attemps to download the file from the URL.


The file is downloaded as-is, without verifying its contents. Cross your fingers, and hope that it works.


All filenames specified Source and Patch (see below) must have unique filename components. No two filenames can have the same filename component.

NoSource: list

list is a comma/whitespace delimited list of source file numbers not to include in the .src.lp source package file. Example:

Name: foo
Version: 1
Release: 1
Source1: http://www.example.com/dist/foo.tar.gz
Source2: foo-patches.tar.gz
Source3: http://www.example.com/dist/foo-extras.tar.gz

NoSource: 1, 3


If foo.tar.gz and foo-extras.tar.gz do not exist in the current directory, lpbuild will download them automatically from the corresponding URL. Although they will subsequently be used to build this software package, they won't get included in the foo.src.lp source package files.

NoSource solves the problem of distributing packages for software whose source code cannot legally be distributed, and must be downloaded from its original distribution site. If the resulting source package file contains all the distributable software, running lpbuild --rebuild filename.tar.gz automatically downloads the encumbered source and builds the software package.

Patch: filename

filename is a file that contains patches to the applications that should be applied before the application gets actually built. Use Patch2:, Patch3:, etc..., when the multiple patches will be applied (it is not necessary to combine multiple patch files into one).


The patch file must be explicitly applied to the source code, later in the build script. This header only gives the name of the file that contains the patch.

Repository(filename): url

This line provides package repository information. Packages created by this specfile will be published in a primary package repository at url, and they are signed by GPG public keys from filename.

The lpm(1) manual page gives additional information for creating a primary repository - a web site where packages are published, and are available for downloading. Primary repositories use GPG keys to verify the security and integrity of downloaded packages. Each primary repository signs its packages with its own set of GPG keys.

The Repository: header is a key step in creating a robust mechanism for automatically downloading and installing LPMtool packages in a secure way, based on a GPG-like web of trust. Consider a package named GizmoLib, that's published on a repository hosted on its web site. Then, suppose an application called TurboApp is published on its own, different web site, but which requires and needs GizmoLib's packages. Provided that the Repository: headers are set correctly, and all GPG keys are in order, when installing TurboApp LPMtool's lpm(1) command will find and download GizmoLib even if LPMtool never knew about GizmoLib's web site before.

filename must be a copy of the pgpkeys.txt file from url. This file must be present in the default source directory (see Section 6, “Build scripts”) after the application's build script concludes. Typically the pgpkeys.txt will be included in the application's primary tarball, in the top source directory. One of the keys in filename should the default GPG secret key that will be used by lpbuild(1) to sign the new package files produced from this specfile.

Multiple Repository: headers are allowed, but each filename must be different, and this unnecessarily complicates things.

Here's how this works (a word of warning - this gets rather technical):

  1. The URL given by the Repository line gets included in every package file produced by this specfile.

  2. The entire contents of the filename gets included in each package file, together with everything else.

  3. As part of the build process, lpbuild analyzes each package's requirements. The requirements may be explicitly declared in a Requires: header, or automatically determined by LPMtool. LPMtool checks which packages contain the required resources, and those package's URLs and GPG keys are also added to this specfile's packages. In this manner, LPMtool knows where to find other required packages when installing these ones.

  4. In the similar fashion, this specfile's repository URLs and GPG keys will be retrieved when building software that dependens on these packages.

  5. Even if LPMtool has never seen a particular repository required by a package, because the package itself includes the external repository's GPG keys, LPMtool will be able to securely open the remote repository.

Although the above lines may occur in any order, sometimes a specific order is needed for other reasons. For example, when lpbuild reads Name:, Version:, and Release: lines, it sets the corresponding __name, __version, and __release macros. Consider the following example:

Name: filemasher
Version: 2.00
Release: 1

Source: %{__name}-%{__version}.tar.gz

lpbuild will read filemasher-2.00.tar.gz as the name of the application's source code tarball automatically. When release 3.00 of filemasher is available, it is only necessary to change the version label in one place, in the Version: header. lpbuild then reads filemasher-3.00.tar.gz automatically.

For this to work, Source: must appear after all the other lines, because the __name and __version macros are not available until their corresponding lines are processed.