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

# 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 %docdired directory will be marked as documentation directories, too.

As mentioned in section 13.5, 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 that 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 this:

%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

...

#

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 be determined only 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.

13.7. The Lone Directive: %package

While every directive we've seen so far is used in the %files list, the %package directive is different. It is used to permit the creation of more than one package per spec file and can appear at any point in the spec file. These additional packages are known as subpackages. Subpackages are named according to the contents of the line containing the %package directive. The format of the package directive is this:

%package: <string>

<string> should be a name that describes the subpackage. This string is appended to the base package name to produce the subpackage's name. For example, if a spec file contains a name tag value of foonly and a %package doc line, the subpackage name will be foonly-doc.