Appendix E

Concise Spec File
Reference

E.1. Comments

Comments are a way to make RPM ignore a line in the spec file. To create a comment, enter a pound sign (#) at the start of the line. Any text following the comment character will be ignored by RPM:

# This is the spec file for playmidi 2.3...

Comments can be placed in any section of the spec file.

For more information, see section 13.1 in Chapter 13, "Inside the Spec File."

E.2. The Preamble

The preamble contains information that will be displayed when users request information about the package.

E.2.1. Package-Naming Tags

Package-naming tags are used to define the parts of the package's label. For more information about these tags, see section 13.2.1.

E.2.1.1. The name Tag

The name tag is used to define the name of the software being packaged:

Name: cdplayer

E.2.1.2. The version Tag

The version tag defines the version of the software being packaged:

Version: 1.2

E.2.1.3. The release Tag

The release tag can be thought of as the package's version:

Release: 5

E.2.2. Descriptive Tags

Descriptive tags are used to define various types of information about the package. For more information about these tags, see section 13.2.2.

E.2.2.1. The %description Tag

The %description tag is used to define an in-depth description of the packaged software. In the descriptive text, a space in the first column indicates that that line of text should be presented to users as is, with no formatting done by RPM. Blank lines in the descriptive text denote paragraphs:

%description

 It slices!

 It dices!

 It's a CD player app that can't be beat.



By using the resonant frequency of the CD itself, it is able to simulate

20X oversampling. This leads to sound quality that cannot be equaled with

more mundane software...

You can make the %description tag specific to a particular subpackage by adding the subpackage name and, optionally, the -n option:

%description bar



%description -n bar

The subpackage name and the usage of the -n option must match those defined with the %package directive.

E.2.2.2. The summary Tag

The summary tag is used to define a one-line description of the packaged software:

Summary: A CD player app that rocks!

E.2.2.3. The copyright Tag

The copyright tag is used to define the copyright terms applicable to the software being packaged:

Copyright: GPL

E.2.2.4. The distribution Tag

The distribution tag is used to define a group of packages of which this package is a part:

Distribution: Doors '95

E.2.2.5. The icon Tag

The icon tag is used to name a file containing an icon representing the packaged software:

Icon: foo.xpm

The file may be in either GIF or XPM format, although XPM is preferred. In either case, the background of the icon should be transparent.

E.2.2.6. The vendor Tag

The vendor tag is used to define the name of the entity that is responsible for packaging the software:

Vendor: White Socks Software, Inc.

E.2.2.7. The url Tag

The url tag is used to define a uniform resource locator that can be used to obtain additional information about the packaged software:

URL: 

http://www.gnomovision.com/cdplayer.html

E.2.2.8. The group Tag

The group tag is used to group packages together by the types of functionality they provide:

Group: Applications/Editors

E.2.2.9. The packager Tag

The packager tag is used to hold the name and contact information for the person or persons who built the package:

Packager: Fred Foonly <fred@gnomovision.com>

E.2.3. Dependency Tags

Dependency tags are used to define a package's dependency-related requirements. For more information about these tags, see section 13.2.3.

E.2.3.1. The provides Tag

The provides tag is used to specify a "virtual package" that the packaged software makes available when it is installed:

Provides: module-info

E.2.3.2. The requires Tag

The requires tag is used to make RPM aware that the package needs to have certain capabilities available in order to operate properly:

Requires: playmidi

A version may be specified, following the package specification. The following comparison operators may be placed between the package and version: <, >, =, >=, and <=. Here's an example:

Requires: playmidi >= 2.3

If the requires tag needs to perform a comparison against a serial number defined with the serial tag, the proper format would be

Requires: playmidi =S 4

E.2.3.3. The serial Tag

The serial tag is used to define a serial number for a package:

Serial: 4

This is only necessary if RPM is unable to determine the ordering of a package's version numbers.

E.2.3.4. The conflicts Tag

The conflicts tag is used to make RPM aware that the package is not compatible with other packages:

Conflicts: playmidi

A version may be specified, following the package specification. The following comparison operators may be placed between the package and version: <, >, =, >=, and <=. Here's an example:

Conflicts: playmidi >= 2.3

If the conflicts tag needs to perform a comparison against a serial number defined with the serial tag, the proper format would be

Conflicts: playmidi =S 4

E.2.3.5. The autoreqprov Tag

The autoreqprov tag is used to control the automatic dependency processing performed when the package is being built. To disable automatic dependency processing, add the following line:

AutoReqProv: no

(The number 0 may be used instead of no.) Although RPM defaults to performing automatic dependency processing, the effect of the autoreqprov tag can be reversed by changing no to yes. (The number 1 may be used instead of yes.)

E.2.4. Architecture- and Operating System_Specific Tags

These tags are used to control RPM's behavior when the package is built on different platforms. For more information about these tags, see section 13.2.4.

E.2.4.1. The excludearch Tag

The excludearch tag is used to direct RPM to ensure that the package does not attempt to build on the excluded architecture(s):

ExcludeArch: sparc alpha

E.2.4.2. The exclusivearch Tag

The exclusivearch tag is used to direct RPM to ensure the package is only built on the specified architecture(s):

ExclusiveArch: sparc alpha

E.2.4.3. The excludeos Tag

The excludeos tag is used to direct RPM to ensure that the package does not attempt to build on the excluded operating system(s):

ExcludeOS: linux irix

E.2.4.4. The exclusiveos Tag

The exclusiveos tag is used to denote which operating system(s) should be exclusively permitted to build the package:

ExclusiveOS: linux

E.2.5. Directory-Related Tags

Directory-related tags are used to define certain directory-related aspects of RPM's operation. For more information about these tags, see section 13.2.5.

E.2.5.1. The prefix Tag

The prefix tag is used to define part of the path RPM will use when installing the package's files:

Prefix: /opt

The prefix can be redefined by the user when the package is installed, thereby changing where the package is installed.

E.2.5.2. The buildroot Tag

The buildroot tag is used to define an alternate build root, where the software will be installed during the build process:

BuildRoot: /tmp/cdplayer

E.2.6. Source and Patch Tags

The source and patch tags are used to define the names of the files that contain the package's source code, and patches. For more information about these tags see section 13.2.6 in Chapter 13.

E.2.6.1. The source Tag

The source tag is used to define the filename of the sources to be packaged:

Source0: ftp://ftp.gnomovision.com/pub/cdplayer-1.0.tgz

Source1: foo.tgz

When there is more than one source tag in a spec file, each one must be numbered so it is unique, starting with the number 0. When there is only one tag, it does not need to be numbered. By convention, the source filename is usually preceded by a URL pointing to the location of the original sources, but RPM does not require this.

E.2.6.2. The nosource Tag

The nosource tag is used to make RPM aware that one or more source files should be excluded from the source package file:

NoSource: 0, 3

The tag is followed by one or more numbers. The numbers correspond to the numbers following the source tags that are to be excluded from packaging.

E.2.6.3. The patch Tag

The patch tag is used to define the name of a patch file to be applied to the package's sources:

Patch: cdp-0.33-fsstnd.patch

When there is more than one patch tag in a spec file, each one must be numbered so it is unique, starting with the number 0. When there is only one tag, it does not need to be numbered.

E.2.6.4. The nopatch Tag

The nopatch tag is used to make RPM aware that one or more patch files should be excluded from the source package file:

NoPatch: 2 3

The tag is followed by one or more numbers. The numbers correspond to the numbers following the patch tags that are to be excluded from packaging.

E.3. Scripts

Scripts are used by RPM to perform processing at various times.

E.3.1. Build Time Scripts

Every build time script has the following environment variables defined:

• RPM_SOURCE_DIR
• RPM_BUILD_DIR
• RPM_DOC_DIR
• RPM_OPT_FLAGS
• RPM_ARCH
• RPM_OS
• RPM_ROOT_DIR
• RPM_BUILD_ROOT
• RPM_PACKAGE_NAME
• RPM_PACKAGE_VERSION
• RPM_PACKAGE_RELEASE

For more information on these environment variables and build time scripts, see section 13.3.1 in Chapter 13.

E.3.1.1. The %prep Script

The %prep script is the first script RPM executes during a build:

%prep

As the name implies, it is normally used to prepare the sources for building. The commands in the script can be any valid sh commands.

E.3.1.2. The %build Script

The %build script is the second script RPM executes during a build:

%build

As the name implies, it is normally used to build the software. The commands in the script can be any valid sh commands.

E.3.1.3. The %install Script

The %install script is the third script RPM executes during a build:

%install

As the name implies, it is normally used to install the software. The commands in the script can be any valid sh commands.

E.3.1.4. The %clean Script

The %clean script, as the name implies, is used to clean up the software's build directory tree:

%clean

RPM will normally do this for you, but in certain cases (most notably in those packages that use a build root) you'll need to include a %clean script. The commands in the script can be any valid sh commands.

E.3.2. Install and Erase Time Scripts

Install time and erase time scripts are executed whenever the package is installed or erased, respectively. Each script can consist of any valid sh commands.

You can make each of the following scripts specific to a particular subpackage by adding the subpackage name and, optionally, the -n option:

%post bar



%preun -n bar

The subpackage name and usage of the -n option must match those defined with the %package directive.

Each script has the following environment variable defined:

• RPM_INSTALL_PREFIX

For more information on this environment variable and the associated scripts, see section 13.3.2 in Chapter 13.

E.3.2.1. The %pre Script

The %pre script executes just before the package is to be installed:

%pre

E.3.2.2. The %post Script

The %post script executes just after the package is to be installed:

%post

E.3.2.3. The %preun Script

The %preun script executes just before the package is to be erased:

%preun

E.3.2.4. The %postun Script

The %postun script executes just after the package is to be erased:

%postun

E.3.3. Verification Scripts

Verification scripts are executed when an installed package is to be verified.

E.3.3.1. The %verifyscript Script

The %verifyscript script executes whenever the package is verified using RPM's -V option. The script can consist of any valid sh commands.

For more information, see section 13.3.3 in Chapter 13.

E.4. Macros

Macros are used to simplify certain types of repetitive operations.

E.4.1. The %setup Macro

The %setup macro is used to unpack the original sources in preparation for the build. It is used in the %prep script:

%prep

%setup

For more information about the %setup macro and the related options described in this section, see section 13.4.1 in Chapter 13.

E.4.1.1. The -n <name> Option

The -n option is used to set the name of the software's build directory:

%setup -n cd-player

This is necessary only when the source archive unpacks into a directory named other than <name>-<version>.

E.4.1.2. The -c Option

The -c option is used to direct %setup to create the top-level build directory before unpacking the sources:

%setup -c

E.4.1.3. The -D Option

The -D option is used to direct %setup to not delete the build directory prior to unpacking the sources:

%setup -D -T -b 3

This option is used when more than one source archive is to be unpacked into the build directory, normally with the -b or -a option.

E.4.1.4. The -T Option

The -T option is used to direct %setup to not perform the default unpacking of the source archive specified by the first source tag. It is used with the -a or -b options:

%setup -D -T -a 1

E.4.1.5. The -b <n> Option

The -b option is used to direct %setup to unpack the source archive specified on the nth source tag line before changing directories into the build directory:

%setup -D -T -b 2

E.4.1.6. The -a <n> Option

The -a option is used to direct %setup to unpack the source archive specified on the nth source tag line after changing directories into the build directory:

%setup -D -T -a 5

E.4.2. The %patch Macro

The %patch macro, as its name implies, is used to apply patches to the unpacked sources. With no additional options specified, it will apply the patch file specified by the patch (or patch0) tag:

%patch

When there is more than one patch tag line in a spec file, they can be specified by appending the number of the patch tag to the %patch macro name itself:

%patch2

For more information about the patch tag and the related options described in this section, see section 13.4.2 in Chapter 13.

E.4.2.1. The -P <n> Option

The -P option is another method of applying a specific patch. The number from the patch tag follows the -P option. The following %patch macros both apply the patch specified on the patch2 tag line:

%patch -P 2

%patch2

E.4.2.2. The -p<#> Option

The -p option is sent directly to the patch command. It is followed by a number that specifies the number of leading slashes (and the directories in between) to strip from any filenames present in the patch file:

%patch -p2

E.4.2.3. The -b <name> Option

When the patch command is used to apply a patch, unmodified copies of the files patched are renamed to end with the extension .orig. The -b option is used to change the extension used by patch:

%patch -b .fsstnd

E.4.2.4. The %patch -E Option

The -E option is sent directly to the patch command. It is used to direct patch to remove any empty files after the patches have been applied.

%patch -E

E.5. The %files List

The %files list indicates which files on the build system are to be packaged. The list consists of one file per line:

%files

/etc/foo.conf

/sbin/foo

/usr/bin/foocmd

If a directory is specified, by default all files and subdirectories will be packaged.

You can make the %files list specific to a particular subpackage by adding the subpackage name and, optionally, the -n option:

%files bar



%files -n bar

The subpackage name and the usage of the -n option must match those defined with the %package directive.

The %files list can also use the contents of a file as the list of files to be packaged. This is done by using the -f option, which is then followed by a filename:

%files -f files.list

For more information, see section 13.5 in Chapter 13.

E.6. Directives for the %files List

The directives outlined in the following sections are used to modify various attributes of one or more entries in the %files list.

E.6.1. File-Related Directives

The directives outlined in the following sections modify %files list entries that are files. For more information about these directives, see section 13.6.1.

E.6.1.1. The %doc Directive

The %doc directive flags the filename(s) that follow it as being documentation:

%doc README

E.6.1.2. The %config Directive

The %config directive is used to flag the specified file as being a configuration file:

%config /etc/fstab

E.6.1.3. The %attr Directive

The %attr directive is used to permit RPM to directly control a file's permissions and ownership. It is normally used when non-root users build packages. The %attr directive has the following format:

%attr(<mode>, <user>, <group>) file

The user and group identifiers must be non-numeric. Attributes that do not need to be set by %attr may be replaced with a dash:

%attr(755, root, -) foo.bar

E.6.1.4. The %verify Directive

The %verify directive is used to control which of nine different file attributes are to be verified by RPM. The attributes are

• owner—The file's owner.
• group—The file's group.
• mode—The file's mode.
• md5—The file's MD5 checksum.
• size—The file's size.
• maj—The file's major number.
• min—The file's minor number.
• symlink—The file's symbolic link string.
• mtime—The file's modification time.

One or more of these attributes may be listed in each %verify directive:

%verify(mode md5 size maj min symlink mtime) /dev/ttyS0

If the keyword not precedes the list of attributes, every attribute except those listed will be verified.

E.6.2. Directory-Related Directives

The directives outlined in the following sections modify %files list entries that are directories. For more information about these directives, see section 13.6.2 in Chapter 13.

E.6.2.1. The %docdir Directive

The %docdir directive is used to add the specified directory to RPM's internal list of directories containing documentation. When a directory is added to this list, every file packaged in this directory (and any subdirectories) will automatically be marked as documentation.

E.6.2.2. The %dir Directive

The %dir directive is used to direct RPM to package only the directory itself, regardless of what files may reside in the directory at the time the package is created:

%dir /usr/blather

E.7. The %package Directive

The %package directive is used to control the creation of subpackages. The subpackage name is derived from the first name tag in the spec file, followed by the name specified after the %package directive. Therefore, if the first name tag is

Name: foo

and a subpackage is defined with the following %package directive:

%package bar

the subpackage name will be foo-bar.

For more information on this package and its options, see section 13.7 in Chapter 13.

E.7.1. The %package -n Option

The -n option is used to change how RPM derives the subpackage name. When the -n option is used, the name following the %package directive becomes the complete subpackage name. Therefore, if a subpackage is defined with the following %package directive:

%package -n bar

the subpackage name will be bar.

E.8. Conditionals

The %ifxxx conditionals are used to begin a section of the spec file that is specific to a particular architecture or operating system. They are followed by one or more architecture or operating system specifiers, each separated by commas or whitespace.

Conditionals may be nested within other conditionals, provided that the inner conditional is completely enclosed by the outer conditional. For more information about conditionals, see section 13.8 in Chapter 13.

E.8.1. The %ifarch Conditional

If the build system's architecture is specified, the part of the spec file following the %ifarch but before an %else or %endif will be used during the build:

%ifarch i386 sparc

E.8.2. The %ifnarch Conditional

If the build system's architecture is specified, the part of the spec file following the %ifarch but before an %else or %endif will not be used during the build:

%ifnarch i386 sparc

E.8.3. The %ifos Conditional

If the build system is running one of the specified operating systems, the part of the spec file following the %ifos but before an %else or %endif will be used during the build:

%ifos linux

E.8.4. The %ifnos Conditional

If the build system is running one of the specified operating systems, the part of the spec file following the %ifnos but before an %else or %endif will not be used during the build:

%ifnos linux

E.8.5. The %else Conditional

The %else conditional is placed between an %if conditional of some persuasion and an %endif. It is used to create two blocks of spec file statements, only one of which will be used in any given case:

%ifarch alpha

make RPM_OPT_FLAGS="$RPM_OPT_FLAGS -I ."

%else

make RPM_OPT_FLAGS="$RPM_OPT_FLAGS"

%endif

E.8.6. The %endif Conditional

An %endif is used to end a conditional block of spec file statements. The %endif is always needed after a conditional; otherwise, the build will fail:

%ifarch i386

make INTELFLAG=-DINTEL

%endif