RPM scriptlet recipes

Rpm spec files have several sections which allow packages to run code on installation and removal. These scriptlets are mostly used to update the running system with information from the package. This page offers a quick overview of the RPM scriptlets and a number of common recipes for scriptlets in packages. For a more complete treatment of scriptlets, please see the Maximum RPM book .

Contents:

Syntax

The basic syntax is similar to the %build, %install, and other sections of the rpm spec file. The scripts support a special flag, -p which allows the scriptlet to invoke a single program directly rather than having to spawn a shell to invoke the programs. (ie: %post -p /sbin/ldconfig)

The scriptlets also take an argument, passed into them by the controlling rpmbuild process. This argument, accessed via $1 is the number of packages of this name which will be left on the system when the action completes.
So for the common case of install, upgrade, and uninstall we have:

install

upgrade

uninstall

%pre

$1 == 1

$1 == 2

--

%post

$1 == 1

$1 == 2

--

%preun

--

$1 == 1

$1 == 0

%postun

--

$1 == 1

$1 == 0

Note that these values will vary if there are multiple versions of the same package installed (This mostly occurs with parallel installable packages such as the kernel. However, it can also occur when errors prevent a package upgrade form completing.) So it is a good idea to use this construct:

%pre
if [ $1 -gt 1 ] ; then
fi

For %pre and %post scripts rather than checking that it equals 2.

Scriptlet Ordering

The scriptlets in %pre and %post are respectively run before and after a package is installed. The scriptlets %preun and %postun are run before and after a package is uninstalled. On upgrade, the scripts are run in the following order:

1. %pre of new package
2. package install
3. %post of new package
4. %preun of old package
5. removal of old package
6. %postun of old package

Snippets

Shared libraries

It is also common to invoke these with the '-p' option as they are often the only program invoked in a scriptlet:

%post -p /sbin/ldconfig
%postun -p /sbin/ldconfig

If applicable, the latter way is recommended because doing so will automatically add appropriate dependencies on /sbin/ldconfig to the package (and FWIW, will prevent unnecessarily launching a shell process in the scriptlets).

Services

Initscripts Conventions

These are the general conventions in use in Fedora Core scriptlets. As always, there are exceptions, or places where
we haven't fully implemented this.

Initscripts conventions in the scripts themselves

initscripts need to definitely support the following arguments:

start

starts the service

stop

stops the service

initscripts in almost all cases should support:

restart

restarts the service. Can be implemented as stop/start.

condrestart

restarts the service if it is already running.

status

displays status on the service

initscripts may implement

reload

reloads the service's configuration without restarting it

For more information, see:

/usr/share/doc/initscripts-*/sysvinitfiles

If you don't have this on your system you'll need to install the initscripts rpm.

'if [ $1 = 0 ] ' checks that this is the actual deinstallation of
the package, as opposed to just removing the old package on upgrade.
These statements stop the service, and remove the /etc/rc*.d links.

'if [ "$1" -ge "1" ] checks that this is an upgrade of the package.
If so, restart the service if it's running. (This may not be appropriate
for all services.)

Why don't we....

run 'chkconfig <service> on'?

If a service should be enabled by default, make this the default
in the init script. Doing otherwise will cause the service to be
turned on on upgrades if the user explicitly disabled it.

Note that the default for most network-listening scripts is
off. This is done for better security. We have multiple tools
that can enable services, including GUIs.

start the service after installation?

Installations can be in changeroots, in an installer context, or
in other situations where you don't want the services started.

GConf

GConf is a configuration scheme currently used by the GNOME desktop. Programs which use it setup default values in a [NAME] .schemas file which is installed under %{_sysconfdir}/gconf/schemas/[NAME] .schemas. These defaults are then registered with the gconf daemon which monitors the configuration values and alerts applications when values the applications are interested in change. The schema files also provide documentation about what each value in the configuration system means (which gets displayed when you browse the database in the gconf-editor program).

For packaging purposes, we have to disable schema installation during build, and also register the values in the [NAME] .schemas file with the gconf daemon on installation and unregister them on removal. Due to the ordering of the scriptlets, this is a four step process.

%build
%configure --disable-schemas-install
...

In the cases where the package doesn't use autotools or doesnt support the --disable-schemas-install configure flag we instuct gconftool to ignore schema installation commands by setting the GCONF_DISABLE_MAKEFILE_SCHEMA_INSTALL environment variable.

The AM_GCONF_SOURCE_2 autoconf macro supplies this simple command line flag. Since nearly all packages that use gconf use this macro, this flag can be used to turn off installation in nearly all cases.

In this section we uninstall the old schemas when we upgrade. The way we do this is first to get information about where gconf stores its values via the gconftool-2 --get-default-source line. Then we uninstall the schema from that source. If the package could be upgrading a package which had another name for the schema at one time, then we uncomment the lines to uninstall those as well. Finally, we send a SIGHUP to the gconf daemon so it notices the changes to the database.

Here we do the same things as in the %pre section for upgrading except the gconftool-2 switch used is --makefile-install-rule to install the new schemas instead of the uninstall-rule to remove the old schemas.

This snippet is nearly the same as the one for upgrading. Why can't we just combine this portion with the %pre portion? The answer is that we want to delete any old versions of the schema during an upgrade. But this has to happen before we install the new version (in the %post script) otherwise we end up removing the schema that the upgrading package installs. However, if it really is a removal that will leave no other instances of this package on the system, we have to clean up the schema before deleting it.

Note: When Bug #173869 is resolved, gconftool-2 will contain code to signal gconfd to reload its schemas. Therefore, the killall -HUP gconfd-2 || : lines in all the scriptlets will be optional.

Texinfo

The GNU project and many other programs use the texinfo file format for much of its documentation. These info files are usually located in /usr/share/info/.
When installing or removing a package, install-info from the info package takes care of adding the newly installed files to the main info index and removing them again on deinstallation.

Sometimes it's necessary to remove the directory ../dir in the %build section but this depends.

rm -f %{buildroot}%{_infodir}/dir

These two scriptlets tell install-info to add entries for the info pages to the main indexfile on installation and remove them at deinstall time.

Scrollkeeper

Gnome and KDE use the scrollkeeper cataloging system to keep track of documentation installed on the system. Scrollkeeper allows the help system to sort and search documentation metadata stored in .omf files. When you add documentation in these systems you need to make scrollkeeper aware that the documentation has been changed.

Note that we BuildRequires scrollkeeper as most Makefile's are setup to install the necessary scrollkeeper files only if scrollkeeper is present at install time.

mimeinfo (Needs description)

Note that similarly to the gtk-update-icon-cache code, these scriptlets should be run only if the user has update-mime-info installed and without a specific Requires: shared-mime-info. If shared-mime-info is not installed, update-mime-database won't be run when this package is installed. This does not matter because it will be run when the shared-mime-info package is installed.

GTK+ icon cache

If an application installs icons into one of the subdirectories in %{_datadir}/icons/ (such as hicolor in the following examples), gtk-update-icon-cache should be run after the package is installed/uninstalled on FC4 and later. This is required so that the installed icons show up in GNOME menus right after package installation, and speeds up GTK+ applications' access to the icons. For KDE, just 'touch'ing the top-level icon directory is enough.

Note that no dependencies should be added for this. If gtk-update-icon-cache is not available, there's nothing that would be needing the cache update. Not adding the dependency on gtk-update-icon-cache (ie. gtk2 >= 2.6.0) makes it easier to use the package (or the same specfile) on systems where it's not available nor needed, such as older distro versions or (very) trimmed down installations.

XML Catalogs (Needs entry)

Tips for writing new recipes

As you may have noticed, most commands in snippets need to have a "|| :" on the end of them. This little piece of code causes

each command to exit with a successful exit status whether or not the command worked. This is important because the scriptlet
as a whole will error the moment it tries to execute a command that has a non-zero exit status. Because a normal scriptlet
has many distinct commands that need to execute independently of each other, the ability to run as many of the commands within
a scriptlet as possible is generally what you want.