Directives For the %files list

The %doc Directive

The %doc 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 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 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 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

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 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 (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 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:

part of the path, can be created, and sed can be used at build-time to update the path appropriately.

%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.