Changes between Version 64 and Version 65 of RpmHowToPackagers

Timestamp:

Nov 18, 2019, 4:14:50 PM (5 years ago)

Author:

dmik

Comment:

Add info about secondary expansion of OS/2-specific RPM macros

RpmHowToPackagers

@@ -502 +502 @@
 Adding vendor and packagename is optional. In case they are not provided, they will be replaced with fixed values of wpi4rpm.
 
+=== Using macros at install time ===
+
+There is a group of OS/2-specific RPM macros that provide access to various aspects of the configuration of the OS/2 machine RPM is being run on. All these macros have names starting with `os2_`.
+
+They are normal RPM macros and may be used wherever any other RPM macro does. There is, however, one important detail that should be taken into account when using OS/2-specific macros in `.spec` files — some of these macros depend on user-specific aspects of configuration.
+
+A common case of such a dependency is the OS/2 boot drive letter. It may differ on a machine where the RPM package is being created and on a machine where it is later installed. The latter is up to the user and out of control of the RPM package creator. Normally all RPM macros are expanded at RPM creation time. For `.spec` sections that are run on the RPM creator's machine (such as `%prep`, `%build`, `%install`) it's not a problem as macro expansion happens at the same time the macro is used in the relevant section. However, for sections run on the user's machine at install time (`%post`, `%postun` etc) it is possible that the value of a macro expanded at package creation time will not match the value of the same macro when the package is later installed. Note that it may happen even if it's the same machine (e.g. the RPM creator changes its boot drive later).
+
+A solution RPM provides to overcome this issue is secondary macro expansion. For this solution to work two prerequisites are necessary: a) the relevant `%post`, `%postun` or similar section must contain the `-e` option (to enable an extra expansion at install/uninstall time); b) the macro which is subject to secondary expansion should be prefixed with double `%` sign (to prevent it from being expanded at package creation time).
+
+Here is the list of all OS/2-specific macros that depend on user-specific install-time configuration properties:
+
+||= **Macro** =||= **Dependency** =||
+||os2_boot_drive||Refers to boot drive||
+||os2_config_sys||Refers to `%{os2_boot_drive}`||
+||os2_expand_unixroot||Refers to `%UNIXROOT%` env.var||
+||os2_expand_dos_vars||Refers to `%UNIXROOT%` env.var||
+||os2_unixroot_path||Refers to `%{os2_expand_unixroot}`
+
+Also, all other macros which refer to one of the above macros in their definitions must be subject to double expansion.
+
+A good example of how to use such macros is provided in the next section.
+
 === CONFIG.SYS changes ===
 It is sometimes necessary to modify the CONFIG.SYS file during installation, even when using RPM. One of the examples is when your package installs a device driver that needs to be loaded at boot time or when a global environment variable needs to be set. This can be done from the {{{%post}}} section using the special macro {{{%cube}}} which is based on the CUBE tool.
 
 For example, this snippet will add a DEVICE= line to CONFIG.SYS after the first DEVICE= line (or to the bottom if there are no DEVICE= statements), add an environment variable (using the similar logic).
-{{{
-%post 
-%cube {ADDLINE "DEVICE=%UNIXROOT%\usr\%{_lib}\mydrv.sys" (AFTER "DEVICE="} %{os2_config_sys} >nul
-%cube {ADDLINE "SET MYENVVAR=myvalue" (AFTER "SET "} %{os2_config_sys} >nul
+
+**NOTE**: Using `%{os2_config_sys}` below requires secondary macro expansion. See the previous section for more info.
+{{{
+%post -e
+%cube {ADDLINE "DEVICE=%UNIXROOT%\usr\%{_lib}\mydrv.sys" (AFTER "DEVICE="} %%{os2_config_sys} >nul
+%cube {ADDLINE "SET MYENVVAR=myvalue" (AFTER "SET "} %%{os2_config_sys} >nul
 echo; echo "NOTE:"
-echo; echo "The file '%{os2_config_sys}' has been changed. You need to reboot your"
+echo; echo "The file '%%{os2_config_sys}' has been changed. You need to reboot your"
 echo "computer in order to activate these changes."
 echo
@@ -518 +543 @@
 Here is the corresponding uninstallation snippet that will undo changes made by the above code. You should always perform symmetric uninstallation steps to make sure that all changes your package does to CONFIG.SYS are rolled back when the package is uninstalled from the system.
 {{{
-%postun 
-%cube {DELLINE "SET MYENVVAR="} %{os2_config_sys} >nul
-%cube {DELLINE "DEVICE=%UNIXROOT%\usr\%{_lib}\mydrv.sys"} %{os2_config_sys} >nul
+%postun -e
+%cube {DELLINE "SET MYENVVAR="} %%{os2_config_sys} >nul
+%cube {DELLINE "DEVICE=%UNIXROOT%\usr\%{_lib}\mydrv.sys"} %%{os2_config_sys} >nul
 echo; echo "NOTE:"
-echo; echo "The file '%{os2_config_sys}' has been changed. You need to reboot your"
+echo; echo "The file '%%{os2_config_sys}' has been changed. You need to reboot your"
 echo "computer in order to activate these changes."
 echo