Directives For the %files list

The %doc Directive

The %doc directive flags the filename(s) that follow, as being documentation. RPM keeps track of documentation files in its database, so that a user can easily find information about an installed package. In addition, RPM can create a package-specific documentation directory during installation and copy documentation into it. Whether or not this additional step is taken, is dependent on how a file is specified. Here is an example:

%doc README %doc /usr/local/foonly/README

The file README exists in the software's top-level directory during the build, and is included in the package file. When the package is installed, RPM creates a directory in the documentation directory named the same as the package (ie, <software>-<version>-<release>), and copies the README file there. The newly created directory and the README file are marked in the RPM database as being documentation. The default documentation directory is /usr/doc, and can be changed by setting the defaultdocdir rpmrc file entry. For more information on rpmrc files, please see Appendix B.

The file /usr/local/foonly/README was installed into that directory during the build and is included in the package file. When the package is installed, the README file is copied into /usr/local/foonly and marked in the RPM database as being documentation.

The %config Directive

The %config directive is used to flag the specified file as being a configuration file. RPM performs additional processing for config files when packages are erased, and during installations and upgrades. This is due to the nature of config files: They are often changed by the system administrator, and those changes should not be lost.

There is a restriction to the %config directive, and that restriction is that no more than one filename may follow the %config. This means that the following example is the only allowable way to specify config files:

%config /etc/foonly

Note that the full path to the file, as it is installed at build time, is required.

The %attr Directive

The %attr directive permits finer control over three key file attributes:

1. The file's permissions, or "mode".

2. The file's user ID.

3. The file's group ID.

The %attr directive has the following format:

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

The mode is specified in the traditional numeric format, while the user and group are specifed as a string, such as "root". Here's a sample %attr directive:

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

This would set foo.bar's permissions to 755. The file would be owned by user root, group root. If a particular attribute does not need to be specified (usually because the file is installed with that attribute set properly), then that attribute may be replaced with a dash:

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

The main reason to use the %attr directive is to permit users without root access to build packages. The techniques for doing this (and a more in-depth discussion of the %attr directive) can be found in Chapter 16.

The %verify Directive

RPM's ability to verify the integrity of the software it has installed is impressive. But sometimes it's a bit too impressive. After all, RPM can verify as many as nine different aspects of every file. The %verify directive can control which of these file attributes are to be checked when an RPM verification is done. Here are the attributes, along with the names used by the %verify directive:

1. Owner (owner)

2. Group (group)

3. Mode (mode)

4. MD5 Checksum (md5)

5. Size (size)

6. Major Number (maj)

7. Minor Number (min)

8. Symbolic Link String (symlink)

9. Modification Time (mtime)

How is %verify used? Say, for instance, that a package installs device files. Since the owner of a device will change, it doesn't make sense to have RPM verify the device file's owner/group and give out a false alarm. Instead, the following %verify directive could be used:

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

We've left out owner and group, since we'd rather RPM not verify those. [1]

However, if all you want to do is prevent RPM from verifying one or two attributes, you can use %verify's alternate syntax:

%verify(not owner group) /dev/ttyS0

This use of %verify produces identical results to the previous example.

The %docdir Directive

The %docdir directive is used to add a directory to the list of directories that will contain documentation. RPM includes the directories /usr/doc, /usr/info, and /usr/man in the %docdir list by default.

For example, if the following line is part of the %files list:

%docdir /usr/blather

any files in the %files list that RPM packages from /usr/blather will be included in the package as usual, but will also be automatically flagged as documentation. This directive is handy when a package creates its own documentation directory and contains a large number of files. Let's give it a try by adding the following line to our spec file:

%docdir /usr/blather

Our %files list contains no references to the several files the package installs in the /usr/blather directory. After building the package, looking at the package's file list shows:

# rpm -qlp ../RPMS/i386/blather-1.0-1.i386.rpm … #

Wait a minute: There's nothing there, not even /usr/blather! What happened?

The problem is that %docdir only directs RPM to mark the specified directory as holding documentation. It doesn't direct RPM to package any files in the directory. To do that, we need to clue RPM in to the fact that there are files in the directory that must be packaged.

One way to do this is to simply add the files to the %files list:

%docdir /usr/blather /usr/blather/INSTALL

Looking at the package, we see that INSTALL was packaged:

# rpm -qlp ../RPMS/i386/blather-1.0-1.i386.rpm … /usr/blather/INSTALL #

Directing RPM to only show the documentation files, we see that INSTALL has indeed been marked as documentation, even though the %doc directive had not been used:

# rpm -qdp ../RPMS/i386/blather-1.0-1.i386.rpm … /usr/blather/INSTALL #

Of course, if you go to the trouble of adding each file to the %files list, it wouldn't be that much more work to add %doc to each one. So the way to get the most benefit from %docdir is to add another line to the %files list:

%docdir /usr/blather /usr/blather

Since the first line directs RPM to flag any file in /usr/blather as being documentation, and the second line tells RPM to automatically package any files found in /usr/blather, every single file in there will be packaged and marked as documentation:

# rpm -qdp ../RPMS/i386/blather-1.0-1.i386.rpm /usr/blather /usr/blather/COPYING /usr/blather/INSTALL /usr/blather/README … #

The %docdir directive can save quite a bit of effort in creating the %files list. The only caveat is that you must be sure the directory will only contain files you want marked as documentation. Keep in mind, also, that all subdirectories of the %docdir'ed directory will be marked as documentation directories, too.

The %dir Directive

As we mentioned in the section called The %files List, if a directory is specified in the %files list, the contents of that directory, and the contents of every directory under it, will automatically be included in the package. While this feature can be handy (assuming you are sure that every file under the directory should be packaged) there are times when this could be a problem.

The way to get around this, is to use the %dir directive. By adding this directive to the line containing the directory, RPM will package only the directory itself, regardless of what files are in the directory at the time the package is created. Here's an example of %dir in action.

The blather-1.0 package creates the directory /usr/blather as part of its build. It also puts several files in that directory. In the spec file, the /usr/blather directory is included in the %files list:

%files … /usr/blather …

There are no other entries in the %files list that have /usr/blather as part of their path. After building the package, we use RPM to look at the files in the package:

# rpm -qlp ../RPMS/i386/blather-1.0-1.i386.rpm … /usr/blather /usr/blather/COPYING /usr/blather/INSTALL /usr/blather/README … #

The files present in /usr/blather at the time the package was built were included in the package automatically, without entering their names in the %files list.

However, after changing the /usr/blather line in the %files list to:

%dir /usr/blather

and rebuilding the package, a listing of the package's files now includes only the /usr/blather directory:

# rpm -qlp ../RPMS/i386/blather-1.0-1.i386.rpm … /usr/blather … #

-f <file> — Read the %files List From <file>

The -f option is used to direct RPM to read the %files list from the named file. Like the %files list in a spec file, the file named using the -f option should contain one filename per line and also include any of the directives named in this section.

Why is it necessary to read filenames from a file rather than have the filenames in the spec file? Here's a possible reason:

The filenames' paths may contain a directory name that can only be determined at build-time, such as an architecture specification. The list of files, minus the variable part of the path, can be created, and sed can be used at build-time to update the path appropriately.

It's not necessary that every filename to be packaged reside in the file. If there are any filenames present in the spec file, they will be packaged as well:

%files latex -f tetex-latex-skel /usr/bin/latex /usr/bin/pslatex …

Here, the filenames present in the file tetex-latex-skel would be packaged, followed by every filename following the %files line.