From 1ab2cdd009528b38d24aa12a352109c034028b5e Mon Sep 17 00:00:00 2001 From: FeRD (Frank Dana) Date: Sep 17 2025 13:43:00 +0000 Subject: [PATCH 1/2] Scriptlets: Relocate GConf to separate page And place a big "OUTDATED" caution box at the top. --- diff --git a/guidelines/modules/ROOT/pages/Scriptlets.adoc b/guidelines/modules/ROOT/pages/Scriptlets.adoc index 83d7642..59ff925 100644 --- a/guidelines/modules/ROOT/pages/Scriptlets.adoc +++ b/guidelines/modules/ROOT/pages/Scriptlets.adoc @@ -262,119 +262,9 @@ These are discussed on a xref:UsersAndGroups.adoc[separate page]. === GConf -GConf is a configuration scheme currently used by the GNOME desktop. -Programs which use it setup default values in a `+.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. - -Disabling the GConf installation during the package creation can be done like so: - -.... -%install -export GCONF_DISABLE_MAKEFILE_SCHEMA_INSTALL=1 -make install DESTDIR=$RPM_BUILD_ROOT -... -.... - -The `+GCONF_DISABLE_MAKEFILE_SCHEMA_INSTALL+` environment variable -suppresses the installation of the schema during the building of the package. -An alternative for some packages is to pass a configure flag: - -.... -%build -%configure --disable-schemas -... -.... - -Unfortunately, this configure switch only works -if the upstream packager has adapted their `+Makefile.am+` file to handle it. -If the `+Makefile.am+` file is not configured, -this switch won't do anything -and you'll need to use the environment variable instead. - -Here's the second part: - -.... -BuildRequires: GConf2 -Requires(pre): GConf2 -Requires(post): GConf2 -Requires(preun): GConf2 -... -%pre -%gconf_schema_prepare schema1 schema2 -%gconf_schema_obsolete schema3 -.... - -In this section we uninstall old schemas during upgrade using one of two macros. - -`+%gconf_schema_prepare+` is used for any current GConf schemas. -It takes care of uninstalling previous versions of schemas -that this package currently installs. -It takes a space separated list of schema names without path or suffix -that the package installs. -Note that behind the scenes, this macro works with the `+%post+` scriptlet -to only process GConf schemas if changes have occurred. - -`+%gconf_schema_obsolete+` is used for schemas -that this package previously provided but no longer does. -It will deregister the old schema if it is present on the system. -Nothing will happen if the old schema is not present. -This macro takes a space separated list of schemas to uninstall. -One example of using this might be if the package changed names. -If the old schema was named `+foo.schemas+` -and the new schema is named `+foobar.schemas+` you'd use: - -.... -%gconf_schema_prepare foobar -%gconf_schema_obsolete foo -.... - -The next section does the processing of the newly installed schemas: - -.... -%post -%gconf_schema_upgrade schema1 schema2 -.... - -`+%gconf_schema_upgrade+` takes a space separated list of schemas -that the package currently installs just like `+%gconf_schema_prepare+`. -Behind the scenes, it does the actual work of registering the new version -of the schema and deregistering the old version. - -The last section is for unregistering schemas when a package is removed: - -.... -%preun -%gconf_schema_remove schema1 schema2 -.... - -When a package is upgraded rpm invokes the `+%pre+` scriptlet -to register and deregister the schemas. -When a package is uninstalled, the `+%preun+` scriptlet is used. -`+%gconf_schema_remove+` takes the list of schemas -that this package currently provides and removes them for us. - -==== Rebuilds for changes to macros - -When macros change, packages that make use of them have to be rebuilt -to pick up the changes. -This repoquery command can be used to find the schema -including packages to rebuild: - -.... -repoquery --whatprovides "/etc/gconf/schemas/*" |sort |uniq |wc -l -.... +The legacy GNOME 2 configuration system +(still used by only a handful of packages) +is documented for posterity on xref:ScriptletsGConf.adoc[another page]. === Systemd diff --git a/guidelines/modules/ROOT/pages/ScriptletsGConf.adoc b/guidelines/modules/ROOT/pages/ScriptletsGConf.adoc new file mode 100644 index 0000000..b7e6c10 --- /dev/null +++ b/guidelines/modules/ROOT/pages/ScriptletsGConf.adoc @@ -0,0 +1,135 @@ += GConf Scriptlets Guidelines + +[CAUTION] +.⚠️ Outdated information +==== +GConf is the previous configuration scheme used by the GNOME 2.x desktop. +It was replaced in GNOME 3 by DConf. +GConf is still used by a half-dozen or so legacy Fedora packages. +You will not need to deal with GConf +unless you are maintaining one of those packages. + +The remainder of this document is preserved for historical reference. +==== + +== Writing GConf Scriptlets + +Programs which use GConf setup default values in a `+.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. + +Disabling the GConf installation during the package creation can be done like so: + +[source,rpm-spec] +---- +%install +export GCONF_DISABLE_MAKEFILE_SCHEMA_INSTALL=1 +make install DESTDIR=$RPM_BUILD_ROOT +... +---- + +The `+GCONF_DISABLE_MAKEFILE_SCHEMA_INSTALL+` environment variable +suppresses the installation of the schema during the building of the package. +An alternative for some packages is to pass a configure flag: + +[source,rpm-spec] +---- +%build +%configure --disable-schemas +... +---- + +Unfortunately, this configure switch only works +if the upstream packager has adapted their `+Makefile.am+` file to handle it. +If the `+Makefile.am+` file is not configured, +this switch won't do anything +and you'll need to use the environment variable instead. + +Here's the second part: + +[source,rpm-spec] +---- +BuildRequires: GConf2 +Requires(pre): GConf2 +Requires(post): GConf2 +Requires(preun): GConf2 +... +%pre +%gconf_schema_prepare schema1 schema2 +%gconf_schema_obsolete schema3 +---- + +In this section we uninstall old schemas during upgrade using one of two macros. + +`+%gconf_schema_prepare+` is used for any current GConf schemas. +It takes care of uninstalling previous versions of schemas +that this package currently installs. +It takes a space separated list of schema names without path or suffix +that the package installs. +Note that behind the scenes, this macro works with the `+%post+` scriptlet +to only process GConf schemas if changes have occurred. + +`+%gconf_schema_obsolete+` is used for schemas +that this package previously provided but no longer does. +It will deregister the old schema if it is present on the system. +Nothing will happen if the old schema is not present. +This macro takes a space separated list of schemas to uninstall. +One example of using this might be if the package changed names. +If the old schema was named `+foo.schemas+` +and the new schema is named `+foobar.schemas+` you'd use: + +[source,rpm-spec] +---- +%gconf_schema_prepare foobar +%gconf_schema_obsolete foo +---- + +The next section does the processing of the newly installed schemas: + +[source,rpm-spec] +---- +%post +%gconf_schema_upgrade schema1 schema2 +---- + +`+%gconf_schema_upgrade+` takes a space separated list of schemas +that the package currently installs just like `+%gconf_schema_prepare+`. +Behind the scenes, it does the actual work of registering the new version +of the schema and deregistering the old version. + +The last section is for unregistering schemas when a package is removed: + +[source,rpm-spec] +---- +%preun +%gconf_schema_remove schema1 schema2 +---- + +When a package is upgraded rpm invokes the `+%pre+` scriptlet +to register and deregister the schemas. +When a package is uninstalled, the `+%preun+` scriptlet is used. +`+%gconf_schema_remove+` takes the list of schemas +that this package currently provides and removes them for us. + +=== Rebuilds for changes to macros + +When macros change, packages that make use of them have to be rebuilt +to pick up the changes. +This repoquery command can be used to find the schema +including packages to rebuild: + +[source,sh] +---- +repoquery --whatprovides "/etc/gconf/schemas/*" |sort |uniq |wc -l +---- From fda638662a1577454125935e2e84df5bcac968ae Mon Sep 17 00:00:00 2001 From: FeRD (Frank Dana) Date: Sep 17 2025 13:47:04 +0000 Subject: [PATCH 2/2] Scriptlets: Tag all source blocks --- diff --git a/guidelines/modules/ROOT/pages/Scriptlets.adoc b/guidelines/modules/ROOT/pages/Scriptlets.adoc index 59ff925..e915691 100644 --- a/guidelines/modules/ROOT/pages/Scriptlets.adoc +++ b/guidelines/modules/ROOT/pages/Scriptlets.adoc @@ -55,11 +55,12 @@ 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: -.... +[source,rpm-spec] +---- %pre if [ $1 -gt 1 ] ; then fi -.... +---- for `+%pre+` and `+%post+` scripts rather than checking that it equals 2. @@ -215,14 +216,16 @@ Instead simply call `+ldconfig+` directly in both `+%post+` and `+%postun+` as well as adding the necessary dependencies when necessary: -.... +[source,rpm-spec] +---- %post -p /usr/bin/ldconfig %postun -p /usr/bin/ldconfig -.... +---- or, as part of existing `+%post+` or `+%postun+` scriptlets: -.... +[source,rpm-spec] +---- Requires(post): /usr/bin/ldconfig Requires(postun): /usr/bin/ldconfig [...] @@ -234,7 +237,7 @@ ldconfig [...] ldconfig [...] -.... +---- If the configuration file added to `+/etc/ld.so.conf.d+` specifies a directory into which other packages may install files, @@ -244,13 +247,14 @@ then the package adding the configuration file MUST also include the following file triggers which cause ldconfig to be run automatically when necessary: -.... +[source,rpm-spec] +---- %transfiletriggerin -P 2000000 -- DIRECTORIES ldconfig %transfiletriggerpostun -P 2000000 -- DIRECTORIES ldconfig -.... +---- Replace `+DIRECTORIES+` with the space-separated list of directories which the package adds to the library search path @@ -285,7 +289,8 @@ to handle systemd scriptlet operations. These macros support systemd "presets", as documented in https://www.freedesktop.org/software/systemd/man/systemd.preset.html[systemd.preset(5)]. -.... +[source,rpm-spec] +---- BuildRequires: systemd-rpm-macros [...] @@ -297,7 +302,7 @@ BuildRequires: systemd-rpm-macros %postun %systemd_postun_with_restart apache-httpd.service -.... +---- Some services do not support being restarted (e.g. D-Bus and various storage daemons). @@ -305,18 +310,20 @@ If your service should not be restarted upon upgrade, but should be reloaded instead, then use the following `+%postun+` scriptlet instead of the one shown above: -.... +[source,rpm-spec] +---- %postun %systemd_postun_with_reload apache-httpd.service -.... +---- If your service should not be restarted or reloaded, then use the following `+%postun+` scriptlet instead: -.... +[source,rpm-spec] +---- %postun %systemd_postun apache-httpd.service -.... +---- Those macros accept multiple unit name arguments. It is better to use a single invocation to reduce the number of calls. @@ -334,7 +341,8 @@ These enable and disable user units according to presets, and are `+%systemd_user_post+` (to be used in `+%post+`) and `+%systemd_user_preun+` (to be used in `+%preun+`). -.... +[source,rpm-spec] +---- BuildRequires: systemd-rpm-macros [...] @@ -348,7 +356,7 @@ BuildRequires: systemd-rpm-macros %systemd_user_postun_with_restart %{name}.service %systemd_user_postun_with_reload %{name}.service %systemd_user_postun %{name}.service -.... +---- Macros `+%systemd_user_postun_with_restart+` and `+%systemd_user_postun_with_reload+` iterate over the running user manager instances @@ -399,7 +407,8 @@ Since the UsrMove Feature in Fedora 17 made `+/bin+` a symlink to `+/usr/bin+` we need to place both paths into the `+/etc/shells+` file. Here is an example of the scriptlet to package with shell named "foo": -.... +[source,rpm-spec] +---- %post if [ "$1" = 1 ]; then if [ ! -f %{_sysconfdir}/shells ] ; then @@ -415,4 +424,4 @@ if [ "$1" = 0 ] && [ -f %{_sysconfdir}/shells ] ; then sed -i '\!^%{_bindir}/foo$!d' %{_sysconfdir}/shells sed -i '\!^/bin/foo$!d' %{_sysconfdir}/shells fi -.... +----