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:
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.
v“v” is the application's version label.
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).
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.
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.
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
%endif
%package
...
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.
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.
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.
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.
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):
The URL given by the
“Repository” line gets included in every
package file produced by this
specfile.
The entire contents of the “filename” gets included in each package file, together with everything else.
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.
In the similar fashion, this specfile's repository
URLs and GPG keys will be retrieved
when building software that dependens on these packages.
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.