As you can see, the script starts with the usual invocation of a shell (in this case, the Bourne shell). There are no arguments passed to the script. Next, a number of environment variables are set. Here's a brief description of each one:

• RPM_SOURCE_DIR—This environment variable gets its value from the rpmrc file entry sourcedir, which in turn can get part of its value from the topdir entry. It is the path RPM will prepend to the file, specified in the source tag line.
• RPM_BUILD_DIR—This variable is based on the builddir rpmrc file entry, which in turn can get part of its value from the topdir entry. This environment variable translates to the path of RPM's build directory, where most software will be unpacked and built.
• RPM_DOC_DIR—The value of this environment variable is based on the defaultdocdir rpmrc file entry. Files marked with the %doc directive can be installed in a subdirectory of defaultdocdir. For more information on the %doc directive, refer to section 13.6.1.
• RPM_OPT_FLAGS—This environment variable gets its value from the optflags rpmrc file entry. It contains options that can be passed on to the build procedures of the software being packaged. Normally this means either a configuration script or the make command itself.
• RPM_ARCH—As you might infer from the preceding example, this environment variable contains a string describing the build system's architecture.
• RPM_OS—This one contains the name of the build system's operating system.
• RPM_BUILD_ROOT—This environment variable is used to hold the build root, into which the newly built software will be installed. If no explicit build root has been specified (either by command-line option, spec file tag line, or rpmrc file entry), this variable will be null.
• RPM_PACKAGE_NAME—This environment variable gets its value from the name tag line in the package's spec file. It contains the name of the software being packaged.
• RPM_PACKAGE_VERSION—The version tag line is the source of this variable's translation. Predictably, this environment variable contains the software's version number.
• RPM_PACKAGE_RELEASE—This environment variable contains the package's release number. Its value is obtained from the release tag line in the spec file.

All these environment variables are set for your use to make it easier to write scripts that will do the right thing even if the build environment changes.

The script also sets an option that causes the shell to print out each command, complete with expanded arguments. Finally, the default permissions are set. Past this point, the scripts differ. Let's look at the scripts in the order in which they are executed.

The %prep script is the first one RPM executes during a build. Prior to the %prep script, RPM has performed preliminary consistency checks, such as whether the spec file's source tag points

to files that actually exist. Just prior to passing control over to the %prep script's contents, RPM changes directory into RPM's build area, which, by default, is /usr/src/redhat/BUILD.

At that point, it is the responsibility of the %prep script to do the following:

• Create the top-level build directory.
• Unpack the original sources into the build directory.
• Apply patches to the sources, if necessary.
• Perform any other actions required to get the sources into a ready-to-build state.

The first three items on this list are common to the vast majority of all software being packaged. Therefore, RPM has two macros that greatly simplify these routine functions.

You can find more information on RPM's %setup and %patch macros in section 13.4.

The last item on the list can include creating directories or anything else required to get the sources into a ready-to-build state. As a result, a %prep script can range from one line invoking a single %setup macro to many lines of tricky shell programming.

The %build script picks up where the %prep script left off. Once the %prep script has gotten everything ready for the build, the %build script is usually somewhat anticlimactic—normally invoking make, maybe a configuration script, and little else.

Like %prep before it, the %build script has the same assortment of environment variables to draw on. Also, like %prep, %build changes directory into the software's top-level build directory (located in RPM_BUILD_DIR, or usually called <name>-<version>).

Unlike %prep, there are no macros available for use in the %build script. The reason is simple: Either the commands required to build the software are simple (such as a single make command) or they are so unique that a macro wouldn't make it easier to write the script.

The environment in which the %install script executes is identical to those of the other scripts. Like the other scripts, the %install script's working directory is set to the software's top-level directory.

As the name implies, it is this script's responsibility to do whatever is necessary to actually install the newly built software. In most cases, this means a single make install command or a few commands to copy files and create directories.

The %clean script, as the name implies, is used to clean up the software's build directory tree. RPM normally does 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.

As usual, the %clean script has the same set of environment variables as the other scripts we've covered here. Since a %clean script is normally used when the package is built in a build root, the RPM_BUILD_ROOT environment variable is particularly useful. In many cases, a simple

rm -rf $RPM_BUILD_ROOT

will suffice. Keep in mind that this command in a %clean script can wreak havoc if used, say, with a build root of /. Section 12.1.13 in Chapter 12, "rpm -b Command Reference," discusses this in more detail.

13.3.2. Install/Erase-Time Scripts

The other type of scripts that are present in the spec file are those that are only used when the package is either installed or erased. There are four scripts, each one meant to be executed at different times during the life of a package:

• Before installation
• After installation
• Before erasure
• After erasure

Unlike the build-time scripts, there is little in the way of environment variables for these scripts. The only environment variable available is RPM_INSTALL_PREFIX, and that is only set if the package uses an installation prefix.

Unlike with the build-time scripts, there is an argument defined. The sole argument to these scripts is a number representing the number of instances of the package currently installed on the system, after the current package has been installed or erased. Sound tricky? It really isn't. Here's an example: Assume that a package, called blather-1.0, is being installed. No previous versions of blather have been installed. Because the software is being installed, only the %pre and %post scripts are executed. The argument passed to these scripts will be 1 since the number of blather packages installed is 1. (Or it will be 1 once the package is completely installed. Remember that the number is based on the number of packages installed after the current package's install or erase has completed.)

Continuing our example, a new version of the blather package, version 1.3, is now available. Clearly it's time to upgrade. What will the scripts' values be during the upgrade? As blather-1.3 is installing, its %pre and %post scripts will have an argument equal to 2 (1 for version 1.0 already installed, plus 1 for version 1.3 being installed). As the final part of the upgrade, it's then time to erase blather version 1.0. As the package is being removed, its %preun and %postun scripts are executed. Since there will be only one blather package (version 1.3) installed after version 1.0 is erased, the argument passed to version 1.0's scripts is 1.

To bring an end to this example, we've decided to erase blather 1.3. We just don't need it anymore. As the package is being erased, its %preun and %postun scripts will be executed.