From 74cedb78a1b0c99c7febb71be48e32ce9e14db71 Mon Sep 17 00:00:00 2001
From: Petr Písař <ppisar@redhat.com>
Date: Apr 19 2022 11:00:16 +0000
Subject: Document RPM macros


---

diff --git a/modules/ROOT/pages/building-modules/fedora/defining-modules.adoc b/modules/ROOT/pages/building-modules/fedora/defining-modules.adoc
index 1b36682..591d41f 100644
--- a/modules/ROOT/pages/building-modules/fedora/defining-modules.adoc
+++ b/modules/ROOT/pages/building-modules/fedora/defining-modules.adoc
@@ -303,6 +303,42 @@ In this specific example, `first-package` gets built first, and `second-package`
 
 For even more complex scenarios, please study the https://github.com/fedora-modularity/libmodulemd/blob/main/yaml_specs/modulemd_packager_v3.yaml[modulemd-packager specification].
 
+=== RPM macros (optional)
+
+RPM packages while being built as part of a module have the following RPM macros available:
+
+----
+%dist .scrmod+f37+14301+76d220e4    <.>
+%modularitylabel perl-Module-Install:master:3720220414092112:dd3c6e0e <.>
+%_module_build 1    <.>
+%_module_name perl-Module-Install   <.>
+%_module_stream master  <.>
+%_module_version 3720220414092112   <.>
+%_module_context dd3c6e0e   <.>
+----
+<.> A `%dist` macro of a unique value used in `Release` RPM specification tags.
+<.> An RPM tag stored into binary RPM packages. DNF uses it to distinguish modular packages from nonmodular ones.
+<.> A macro denoting that a modular package is being built.
+<.> A name of the module being built.
+<.> A stream of the module being built.
+<.> A version of the module being built.
+<.> A context of the module being built.
+
+You can use these macros in RPM specification files of your RPM components to modify building of the packages.
+
+If you need additional RPM macros, you can define them in a `buildopts` section of your modulemd file:
+
+[source,yaml]
+----
+    buildopts:
+        rpms:
+            macros: |
+                %perl_bootstrap 1
+----
+
+This section belongs into an item of `configurations` list in case of v3 modulemd format.
+In case of v2 format it belongs directly into `data` section.
+
 === Filtered Packages (optional, defaults to no filters)
 
 The build process of a RPM packages can result in a subpackages which complement the build of the package (docs, additional build requires etc.). One source RPM package might produce multiple binary