From 948210948b384bb218556007d2bd5f865252ff65 Mon Sep 17 00:00:00 2001 From: FeRD (Frank Dana) Date: Apr 12 2025 01:40:43 +0000 Subject: [PATCH 1/2] Update advice on creating specfile macros The guideline to use `%global` in preference to `%define` was described by an RPM developer as "bad advice that spread far and wide". This change completely reverses that advice, instructing packagers to use `%define` by default and `%global` only when needed. --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 4eb42fa..e531968 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -2148,24 +2148,57 @@ Note: If you call Perl or Python in your spec file (and it is not already a BuildRequires for the package), you need to explicitly add a BuildRequires for Perl or Python. -== `+%global+` Preferred Over `+%define+` - -Use `+%global+` instead of `+%define+`, -unless you really need only locally defined submacros -within other macro definitions (a very rare case). - -Rationale: The two macro defining statements behave the same -when they are at the top level of rpm's nesting level. - -But when they are used in nested macro expansions -(like in `+%{!?foo: ... }+` constructs, -`+%define+` theoretically only lasts until the end brace (local scope), -while `+%global+` definitions have global scope. - -Note that %define and %global differ in more ways than just scope: -the body of a %define'd macro is lazily expanded (i.e., when used), -but the body of %global is expanded at definition time. -It's possible to use %%-escaping to force lazy expansion of %global. +== Defining variables (macros) in spec files + +RPM supports two commands that can be used in `.spec` files +to define new `%`-variables. +(Called 'macros' in RPM terminology, +since every `%`-substitution is a macro expansion. +But macros can also be used for simple variable replacement.) + +Packagers **SHOULD** use `%define` to create macros in spec files. +Legacy uses of `%global` **MAY** updated to use `%define`. +Spec files **MAY** contain uses of `%global` +if immediate expansion is needed (a rare occurrence). + +A brief explanation of the two commands, +and the differences between them: + +`%define`:: +Expanded at time of use (lazy expansion). +A macro created with `%define` can use other macros in its definition, +and each expansion of the macro +will insert the current values at the time of expansion. +Each expansion of a `%define` macro can therefore produce a different value. +This makes it very easy to use `%define` macros in loops, +or to change their expansion at different points in the spec file. + +`%global`:: +Expanded at time of creation (immediate expansion). +A macro created with `%global` is expanded as soon as it is created, +so that any `%`-macros used in the definition +are immediately substituted with their value +at the time the `%global` command is processed. +Because a macro defined with `%global` +no longer contains the `%`-macros used in its definition, +only their expanded values, +it will not reflect any subsequent changes to those macros. + +// This can be removed after some time has passed +// and the knowledge has been dissemimated. +// Added 2025-04. +[CAUTION] +===== +Previous versions of these guidelines +advised using `%global` in preference to `%define`. +Due to changes in RPM, +the rationale behind that advice no longer holds, +and this section has been updated to reflect current best practices. +However, because the previous advice was in place for many years, +you will encounter `%global` macros in existing spec files, +as well as in examples provided by these guidelines, +that have not been updated to the current recommendations. +===== [#handling_locale_files] == Handling Locale Files From 59d873c5b822ede44b76e8e925a7328dcab264e5 Mon Sep 17 00:00:00 2001 From: FeRD (Frank Dana) Date: Apr 12 2025 02:45:38 +0000 Subject: [PATCH 2/2] Add missing word --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index e531968..ba42aca 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -2157,7 +2157,7 @@ since every `%`-substitution is a macro expansion. But macros can also be used for simple variable replacement.) Packagers **SHOULD** use `%define` to create macros in spec files. -Legacy uses of `%global` **MAY** updated to use `%define`. +Legacy uses of `%global` **MAY** be updated to use `%define`. Spec files **MAY** contain uses of `%global` if immediate expansion is needed (a rare occurrence).