From 8d0cec97aedc9b34658d004e3a28123f36404324 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Feb 18 2019 18:38:38 +0000 Subject: Partially convert to semantic line breaks. --- diff --git a/guidelines/modules/ROOT/pages/Scriptlets.adoc b/guidelines/modules/ROOT/pages/Scriptlets.adoc index 12fdc8d..f28bdb8 100644 --- a/guidelines/modules/ROOT/pages/Scriptlets.adoc +++ b/guidelines/modules/ROOT/pages/Scriptlets.adoc @@ -1,19 +1,43 @@ = Scriptlets :toc: -RPM spec files have several sections which allow packages to run code on installation and removal. These bits of code are called scriptlets and are mostly used to update the running system with information from the package. This page offers a quick overview of RPM scriptlets and a number of common recipes for scriptlets in packages. For a more complete treatment of scriptlets, please see the http://www.rpm.org/max-rpm-snapshot/[Maximum RPM book]. - -The version of RPM in Fedora also has functionality to automatically run scripts when files are placed in certain locations. (See http://www.rpm.org/wiki/FileTriggers[1].) This potentially obviates the need for most of the scriptlets on this page, but is not currently implemented in all cases where it could be. +RPM spec files have several sections +which allow packages to run code on installation and removal. +These bits of code are called scriptlets +and are mostly used to update the running system +with information from the package. +This page offers a quick overview of RPM scriptlets +and a number of common recipes for scriptlets in packages. +For a more complete treatment of scriptlets, +please see the http://www.rpm.org/max-rpm-snapshot/[Maximum RPM book]. + +The version of RPM in Fedora also has functionality +to automatically run scripts when files are placed in certain locations. +(See http://www.rpm.org/wiki/FileTriggers[1].) +This potentially obviates the need for most of the scriptlets on this page, +but is not currently implemented in all cases where it could be. == Default Shell -In Fedora, all scriptlets can safely assume they are running under the bash shell unless a different language has been specified. +In Fedora, all scriptlets can safely assume they are running under the bash shell +unless a different language has been specified. == 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) - -When scriptlets are called, they will be supplied aith an argument. This argument, accessed via $1 (for shell scripts) is the number of packages of this name which will be left on the system when the action completes, except for %pretrans and %posttrans which are always run with $1 as 0.. So for the common case of install, upgrade, and uninstall we have: +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) + +When scriptlets are called, +they will be supplied aith an argument. +This argument, accessed via $1 (for shell scripts) +is the number of packages of this name +which will be left on the system when the action completes, +except for %pretrans and %posttrans which are always run with $1 as 0.. +So for the common case of install, upgrade, and uninstall we have: [cols=",,,",] |=================================== @@ -26,7 +50,12 @@ When scriptlets are called, they will be supplied aith an argument. This argumen |%posttrans |$1 == 0 |$1 == 0 |(N/A) |=================================== -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 and multilib packages. However, it can also occur when errors prevent a package upgrade from completing.) So it is a good idea to use this construct: +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 and multilib packages. +owever, it can also occur when errors prevent a package upgrade from completing.) +So it is a good idea to use this construct: .... %pre @@ -36,9 +65,37 @@ fi ...for %pre and %post scripts rather than checking that it equals 2. -All scriptlets MUST exit with the zero exit status. Because RPM in its default configuration does not execute shell scriptlets with the `+-e+` argument to the shell, excluding explicit `+exit+` calls (frowned upon with a non-zero argument!), the exit status of the last command in a scriptlet determines its exit status. Most commands in the snippets in this document have a "`+|| :+`" appended to them, which is a generic trick to force the zero exit status for those commands whether they worked or not. Usually the most important bit is to apply this to the last command executed in a scriptlet, or to add a separate command such as plain "`+:+`" or "`+exit 0+`" as the last one in a scriptlet. Note that depending on the case, other error checking/prevention measures may be more appropriate. - -Non-zero exit codes from scriptlets can break installs/upgrades/erases such that no further actions will be taken for that package in a transaction (see link:#Scriptlet_Ordering[#Scriptlet Ordering] below), which may for example prevent an old version of a package from being erased on upgrades, leaving behind duplicate rpmdb entries and possibly stale, unowned files on the filesystem. There are some cases where letting the transaction to proceed when some things in scriptlets failed may result in partially broken setup. It is however often limited to that package only whereas letting a transaction to proceed with some packages dropped out on the fly is more likely to result in broader system wide problems. +All scriptlets MUST exit with the zero exit status. +Because RPM in its default configuration does not execute +shell scriptlets with the `+-e+` argument to the shell, +excluding explicit `+exit+` calls +(frowned upon with a non-zero argument!), +the exit status of the last command in a scriptlet determines its exit status. +Most commands in the snippets in this document +have a "`+|| :+`" appended to them, +which is a generic trick to force the zero exit status +for those commands whether they worked or not. +Usually the most important bit is to apply this +to the last command executed in a scriptlet, +or to add a separate command such as plain "`+:+`" or "`+exit 0+`" +as the last one in a scriptlet. +Note that depending on the case, +other error checking/prevention measures may be more appropriate. + +Non-zero exit codes from scriptlets can break installs/upgrades/erases +such that no further actions will be taken for that package in a transaction +(see link:#Scriptlet_Ordering[#Scriptlet Ordering] below), +which may for example prevent an old version of a package +from being erased on upgrades, +leaving behind duplicate rpmdb entries +and possibly stale, unowned files on the filesystem. +There are some cases where letting the transaction to proceed +when some things in scriptlets failed +may result in partially broken setup. +It is however often limited to that package only +whereas letting a transaction to proceed +with some packages dropped out on the fly +is more likely to result in broader system wide problems. == Ordering