PackagingDrafts/ScriptletSnippets


 * 1) !html
 * Changelog for Revision: 0.2
 * StartDate: June 25, 2006
 * Description:

[1]  Add areas that need to be filled in [2]  Update GConf to recommend using the configure flag --disable-schemas-install = 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:

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
Installing shared libraries requires running /sbin/ldconfig to update the dynamic linker's cache files. These can be invoked like: %post /sbin/ldconfig %postun /sbin/ldconfig 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).

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:

starts the service stops the service
 * start
 * stop

initscripts in almost all cases should support:

restarts the service. Can be implemented as stop/start. restarts the service if it is already running. displays status on the service
 * restart
 * condrestart
 * status

initscripts may implement

reloads the service's configuration without restarting it
 * reload

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.

Initscripts in spec file scriptlets
Requires(post): /sbin/chkconfig Requires(preun): /sbin/chkconfig Requires(preun): /sbin/service ... %post /sbin/chkconfig --add

%preun if [ $1 = 0 ] ; then /sbin/service stop >/dev/null 2>&1 || : /sbin/chkconfig --del fi

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

Requires(postun): /sbin/service ... %postun if [ "$1" -ge "1" ] ; then /sbin/service condrestart >/dev/null 2>&1 || : fi

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

%install rm -rf $RPM_BUILD_ROOT export GCONF_DISABLE_MAKEFILE_SCHEMA_INSTALL=1 make install DESTDIR=$RPM_BUILD_ROOT ... Here we suppress the installation of the schema during the building of the package so that we can subsequently handle it when the package is actually installed or uninstalled.

Here's the second part: Requires(pre): GConf2 Requires(post): GConf2 Requires(preun): GConf2 ... %pre if [ "$1" -gt 1 ] ; then export GCONF_CONFIG_SOURCE=$(gconftool-2 --get-default-source) gconftool-2 --makefile-uninstall-rule \ %{_sysconfdir}/gconf/schemas/%{name}.schemas >/dev/null || : killall -HUP gconfd-2 || : fi 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.

The next section is for installing the new schema: %post export GCONF_CONFIG_SOURCE=$(gconftool-2 --get-default-source) gconftool-2 --makefile-install-rule \ %{_sysconfdir}/gconf/schemas/%{name}.schemas > /dev/null || : killall -HUP gconfd-2 || : 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.

The last section deals with deleting the schemas on package removal: %preun if [ "$1" -eq 0 ] ; then export GCONF_CONFIG_SOURCE=$(gconftool-2 --get-default-source) gconftool-2 --makefile-uninstall-rule \ %{_sysconfdir}/gconf/schemas/%{name}.schemas > /dev/null || : killall -HUP gconfd-2 || : fi 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  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.

Requires(post): /sbin/install-info Requires(preun): /sbin/install-info ... %post /sbin/install-info %{_infodir}/%{name}.info %{_infodir}/dir || :

%preun if [ $1 = 0 ] ; then /sbin/install-info --delete %{_infodir}/%{name}.info %{_infodir}/dir || : fi

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. BuildRequires: scrollkeeper Requires(post): scrollkeeper Requires(postun): scrollkeeper ... %post scrollkeeper-update -q -o %{_datadir}/omf/%{name} || :

%postun scrollkeeper-update -q || : These two scriptlets tell scrollkeeper to update its indexes to account for the new scrollkeeper files.

desktop-database (Needs description)
Use this when a desktop entry has a MimeType key. %post update-desktop-database &> /dev/null ||:

%postun update-desktop-database &> /dev/null ||: Note: For FC5+, this scriptlet follows the same convention as mimeinfo files and gtk-icon-cache. Namely, the spec file should not Require desktop-file-utils for this. For older releases, one should Requires(post): desktop-file-utils Requires(postun): desktop-file-utils (See http://bugzilla.redhat.com/180898 and http://bugzilla.redhat.com/180899)

mimeinfo (Needs description)
Use this when a package drops an XML file in %{_datadir}/mime/packages. %post update-mime-database %{_datadir}/mime &> /dev/null || :

%postun update-mime-database %{_datadir}/mime &> /dev/null || : 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  (such as   in the following examples),   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.

%post touch --no-create %{_datadir}/icons/hicolor || : if [ -x %{_bindir}/gtk-update-icon-cache ] ; then %{_bindir}/gtk-update-icon-cache --quiet %{_datadir}/icons/hicolor || : fi

%postun touch --no-create %{_datadir}/icons/hicolor || : if [ -x %{_bindir}/gtk-update-icon-cache ] ; then %{_bindir}/gtk-update-icon-cache --quiet %{_datadir}/icons/hicolor || : fi

Fonts (Needs description)
Use this when your package installs new fonts. %post if [ -x /usr/bin/fc-cache ] ; then /usr/bin/fc-cache /usr/share/fonts fi %postun if [ "$1" = "0" ] ; then if [ -x /usr/bin/fc-cache ] ; then /usr/bin/fc-cache /usr/share/fonts fi fi

XML Catalogs (Needs entry)
[Toshio has examples in the qa-assistant package]

= Tips for writing new recipes = 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.
 * As you may have noticed, most commands in snippets need to have a "|| :" on the end of them. This little piece of code causes