From 52cec69a57598511a8aa4ff2789137a4f17c643a Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 20 2021 20:13:02 +0000 Subject: SemBr for Alternatives guidelines --- diff --git a/guidelines/modules/ROOT/pages/Alternatives.adoc b/guidelines/modules/ROOT/pages/Alternatives.adoc index 4f268ff..68fb0a1 100644 --- a/guidelines/modules/ROOT/pages/Alternatives.adoc +++ b/guidelines/modules/ROOT/pages/Alternatives.adoc @@ -3,7 +3,9 @@ :last-reviewed: 2019-04-04 :toc: -Alternatives provide means for parallel installation of packages which provide the same functionality by maintaining sets of symlinks (one per package) pointing to alternativized files like this: +Alternatives provide means for parallel installation of packages +which provide the same functionality by maintaining sets of symlinks +(one per package) pointing to alternativized files like this: `+/path/original-file -> /etc/alternatives/packagename-original-file -> /path/original-file.suffix+` For more information, see `+update-alternatives(8)+` manpage. @@ -11,40 +13,72 @@ For more information, see `+update-alternatives(8)+` manpage. Alternatives *MAY* be used to allow parallel installation of software when: -* the software can be used as a drop-in replacement and functions with sufficient similarity that users and other programs would, within reason, not need to know which variant is currently installed +* the software can be used as a drop-in replacement +and functions with sufficient similarity +that users and other programs would, within reason, +not need to know which variant is currently installed *AND* -* the selection of the software is only performed system-wide by the system administrator and end users do not have a need to switch between the variants. +* the selection of the software is only performed system-wide +by the system administrator +and end users do not have a need to switch between the variants. Inversely, alternatives *MUST NOT* be used when: -* The software is not a drop-in replacement. For instance, if common command line arguments are different between the two variants, alternatives *MUST NOT* be used. +* The software is not a drop-in replacement. +For instance, if common command line arguments are different +between the two variants, +alternatives *MUST NOT* be used. *OR* -* End users will care which variant they are using. If a non-root user would gain value by switching between the variants then alternatives *MUST NOT* be used. +* End users will care which variant they are using. +If a non-root user would gain value by switching between the variants +then alternatives *MUST NOT* be used. -A good example of using alternatives are the various MTAs which all provide `+/usr/sbin/sendmail+` with similar command line arguments. +A good example of using alternatives are the various MTAs +which all provide `+/usr/sbin/sendmail+` with similar command line arguments. Bad examples of using alternatives include: -* the various MPI environments where users care both about which MPI environment they compile against and which one they run against -* choice of editor when the user invokes "vi" where the user will care about feature availability, compatibility with plugins, etc +* the various MPI environments where users care +both about which MPI environment they compile against +and which one they run against -Cases where parallel installation is desirable but alternatives is unsuitable may be scenarios where link:../EnvironmentModules/[Environment Modules] are appropriate. MPI and python-sphinx (until Fedora 31) are example packages using environment-modules for this purpose. +* choice of editor when the user invokes "vi" +where the user will care about feature availability, +compatibility with plugins, etc + +Cases where parallel installation is desirable but alternatives is unsuitable +may be scenarios where +link:../EnvironmentModules/[Environment Modules] +are appropriate. +MPI and python-sphinx (until Fedora 31) +are example packages using environment-modules for this purpose. == How to use alternatives -If a package is using alternatives, the files which would otherwise conflict MUST be installed with an appropriate suffix (for example: `+%{_sbindir}/sendmail.postfix+` instead of `+%{_sbindir}/sendmail+`), the original locations MUST be touched (for example: `+touch %{_sbindir}/sendmail+`), the links set up by alternatives MUST be listed as %ghost in the file list and proper Requires: MUST be added, like in the examples below. +If a package is using alternatives, +the files which would otherwise conflict MUST be installed +with an appropriate suffix +(for example: `+%{_sbindir}/sendmail.postfix+` +instead of `+%{_sbindir}/sendmail+`), +the original locations MUST be touched +(for example: `+touch %{_sbindir}/sendmail+`), +the links set up by alternatives MUST be listed as %ghost in the file list +and proper Requires: MUST be added, like in the examples below. -Putting the alternativized files in the file list ensures that they are owned by respective packages, which means that commands like: +Putting the alternativized files in the file list +ensures that they are owned by respective packages, +which means that commands like: * rpm -qf /usr/bin/foo * dnf install /usr/bin/foo * repoquery --whatprovides /usr/bin/foo -all work properly. Using %ghost for this purpose allows using globs and generated file lists. +all work properly. +Using %ghost for this purpose allows using globs and generated file lists. == Examples @@ -73,7 +107,8 @@ fi %{_bindir}/antlr-java .... -And a more complex example of alternatives invocation from sendmail.spec, slightly edited: +And a more complex example of alternatives invocation from sendmail.spec, +slightly edited: .... Requires(post): %{_sbindir}/update-alternatives