• Vendor—The vendor line identifies the organization that distributes the software. Maintaining our fictional motif, we've invented a fictional company, White Socks Software, to add to our spec file. Individuals will probably omit this as well.
• Packager—The packager line is used to identify the organization that actually packaged the software, as opposed to the author of the software. In our example, we've chosen the greatest packager of them all, Santa Claus, to work at White Socks Software. Note that we've included contact information, in the form of an e-mail address.
• Description—The description line is a bit different, in that it starts with a percent sign. It is also different because the information can take up more than one line. It is used to provide a more detailed description of the packaged software than the summary line.
• A comment on comments—At the top of the spec file are three lines, each starting with a pound sign. These are comments and can be sprinkled throughout the spec file to make it more easily understood.

11.3.2. The %prep Section

With the preamble, we provided a wealth of information. The majority of this information is meant for human consumption. Only the name, version, release, and source lines have a direct bearing on the package building process. However, in the %prep section, the focus is entirely on directing RPM through the process of preparing the software for building.

It is in the %prep section that the build environment for the software is created, starting with removing the remnants of any previous builds. Following this, the source archive is expanded. Here is what the %prep section looks like in our sample spec file:

%prep

rm -rf $RPM_BUILD_DIR/cdplayer-1.0

zcat $RPM_SOURCE_DIR/cdplayer-1.0.tgz | tar -xvf -

If the %prep section looks like a script, that's because it is. Any sh constructs can be used here, including expansion of environment variables (such as the $RPM BUILD DIR variable defined by RPM), and piping the output of zcat through tar. (For more information on the environment variables used in the build-time scripts, see section 13.3.1 in Chapter 13, "Inside the Spec File.")

In this case, we perform a recursive delete in the build directory to remove any old builds. We then uncompress the gzipped tar file and extract its contents into the build directory.

Quite often, the sources may require patching in order to build properly. The %prep section is the appropriate place to patch the sources, but in this example, no patching is required. Fear not, however, because we'll explore patching in all its glory in Chapter 20, "Real-World Package Building," when we build a more complex package.

11.3.2.1. Making Life Easier with Macros

While the %prep section as we've described it isn't that difficult to understand, RPM provides macros to make life even easier. In this simple example, there's precious little that can be made easier, but macros will prevent many headaches when it's time to build more complex packages. The macro we'll introduce here is the %setup macro.

The average gzipped tar file is %setup's stock in trade. Like the hand-crafted %prep section described earlier, it cleans up old build trees and then uncompresses and extracts the files from the original source. While %setup has a number of options that we'll cover in later chapters, for now all we need for a %prep section is this:

%prep

%setup

That is simpler than our %prep section, so let's use the %setup macro instead. The %setup macro has a number of options to handle many different situations. For more information on this and other macros, see section 13.4 in Chapter 13.

In this example, the %prep section is complete. Next comes the actual build.

11.3.3. The %build Section

Not surprisingly, the part of the spec file that is responsible for performing the build is the %build section. Like the %prep section, the %build section is an ordinary sh script. Unlike the %prep section, there are no macros. The reason for this is that the process of building software is going to be either very easy or highly complicated. In either case, macros won't help much. In our example, the build process is simple:

%build

make

Thanks to the make utility, only one command is necessary to build the cdplayer application. In the case of an application with more esoteric build requirements, the %build section could get a bit more interesting.

11.3.4. The %install Section

The %install section is executed as a sh script, just like %prep and %build. If the application is built with make and the makefile has an install target, the %install section will also be straightforward. The cdplayer application is a good example of this:

%install

make install

If the application doesn't have a means of automatically installing itself, you must create a script to do so and place it in the %install section.

11.3.5. The %files Section

The %files section is different from the others in that it contains a list of the files that are part of the package. Always remember that if it isn't in the %files list, it won't be put in the package! Here's the %files section for cdplayer:

%files

%doc README

/usr/local/bin/cdp

/usr/local/bin/cdplay

/usr/local/man/man1/cdp.1

The line starting with %doc is an example of RPM's handling of different file types. As you might guess, %doc stands for documentation. The %doc directive is used to mark files as being documentation. In this example, the README file will be placed in a package-specific directory, located in /usr/doc, and called cdplayer-1.0-1. It's also possible to mark files as documentation and have them installed in other directories. This is covered in more detail in section 13.6.1 in Chapter 13.

The rest of the files in the example are shown with complete paths. This is necessary because the files will actually be installed in those directories by the application's makefile. Since RPM needs to be able to find the files prior to packaging them, complete paths are required.

11.3.5.1. How Do You Create the File List?

Since RPM automates so many aspects of software installation, it's easy to fall into the trap of assuming that RPM does everything for you. Not so! One task that is still a manual process is creating the file list. While it may seem at first glance that it could be automated somehow, it's actually a more difficult problem than it seems.

Since the majority of an application's files are installed by its makefile, RPM has no control over that part of the build process and therefore cannot automatically determine which files should be part of the package. Some people have attempted to use a modified version of install that logs the name of every file it installs. But not every makefile uses install, or if it does, uses it sporadically.

Another attempted approach was to obtain a list of every file on the build system, immediately before and after a build, and use the differences as the file list. While this approach will certainly find every file that the application installed, it can also pick up extraneous files, such as system logs, files in /tmp, and the like. The only way to begin to make this approach workable would be to do nothing else on the build system, which is highly inconvenient. This approach also precludes building more than one package on the system at any given time.

At present, the best way to create the file list is to read the makefile to see what files it installs, verify this list against the files installed on the build system, and create the list.