From 0258cb8f2d312bf2922480273c5f16888710eb4f Mon Sep 17 00:00:00 2001
From: Mike McLean <mikem@redhat.com>
Date: Jul 29 2020 18:57:55 +0000
Subject: document setting rpm macros for build tags


Fixes https://pagure.io/koji/issue/2370

---

diff --git a/docs/source/index.rst b/docs/source/index.rst
index 3262ac8..ea429c9 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -39,6 +39,7 @@ Contents
     database_howto
     kojid_conf
     using_the_koji_build_system
+    setting_rpm_macros
     profiles
     plugins
     volumes
diff --git a/docs/source/setting_rpm_macros.rst b/docs/source/setting_rpm_macros.rst
new file mode 100644
index 0000000..85fbb2f
--- /dev/null
+++ b/docs/source/setting_rpm_macros.rst
@@ -0,0 +1,112 @@
+=============================
+Setting RPM Macros for Builds
+=============================
+
+The values of RPM macros can have significant effects on the results of RPM builds.
+Note that the subject of RPM macros is complicated and goes well beyond Koji.
+For the purposes of this document, we assume the reader is familiar with the basic concepts.
+
+Further reading:
+
+* https://rpm-guide.readthedocs.io/en/latest/rpm-guide.html#rpm-macros
+* https://rpm.org/user_doc/macros.html
+* https://rpm-packaging-guide.github.io/#more-on-macros
+
+When Koji builds RPMs, it does so by running ``rpmbuild`` in a controlled build environment.
+Inside that environment, ``rpm`` can pull macro values from multiple sources.
+
+There are two basic ways to set rpm macro values for builds in Koji:
+
+* using a build that places an rpmmacros file in the build environment
+* setting ``rpm.macro.`` values for the build tag
+
+
+Setting rpm macros with a build
+===============================
+
+Prior to Koji 1.18, this was the only way to set rpm macros in Koji.
+This method is still valid, and in some cases preferred.
+However, values set this way can be overridden my ``rpm.macro.*`` values set for the build tag.
+
+In short, this method involves:
+
+* creating an rpm build that places an rpm macros file in the buildroot
+* requiring this build to be installed in the build environment
+
+This might be a very simple build that only provides a single rpm macros file.
+Such files will be read by ``rpm`` when they are installed into ``/etc/rpm`` or
+``/usr/lib/rpm/macros.d/``.
+
+There are many examples of this.
+In Fedora, there are numerous packages like ``python-rpm-macros``, ``perl-macros``, and
+``systemd-rpm-macros``.
+Other packages might package such macro files alongside other content.
+The ``ansible`` package is currently an example of this.
+
+*In order for such a build to affect the build environment, it must be installed there.*
+First the build needs to be in the build tag, either tagged there directly or indirectly via 
+inheritance.
+Second, the package needs to be either part of the base buildroot install, or pulled in via
+build requirements.
+
+Often, you want to make sure these macros affect *all* builds for a tag.
+This means making your macros build part of the base install for the buildroot.
+This can be done by adding the rpm name to the ``build`` group for the tag.
+
+::
+
+$ koji add-group-pkg f33-build build my-custom-rpm-macros
+
+If your macro also needs to be available when building source rpms (e.g. ``%dist``), then you'll
+also want to add it to the the ``srpm-build`` group.
+
+::
+
+$ koji add-group-pkg f33-build build my-custom-rpm-macros
+
+
+Setting rpm.macro values
+========================
+
+(this feature was added in :doc:`Koji 1.18 <release_notes/release_notes_1.18>`)
+
+As a convenience, Koji will honor any ``rpm.macro.NAME`` values in the "tag extra" settings for
+a given build tag.
+These values can be set by tag administrators with the ``edit-tag`` command and viewed with
+the ``taginfo`` command.
+For example, to set the ``dist`` macro value, you could use a command like the following:
+
+::
+
+$ koji edit-tag f33-build -x rpm.macro.dist=.fc33
+
+This will cause Koji to pass this value to ``mock`` when constructing the buildroot.
+These values are placed in the mock configuration file.
+
+**Use case**
+
+This feature is best used for macros with simple values that need to be managed by tag administrators.
+The canonical example is managing the ``%dist`` macro, but other simple macros would also make sense.
+
+We do not recommend setting complicated macros in this way.
+E.g. macros that contain complex expansions, or those that are central to the rpmbuild process.
+
+
+**Inheritance**
+
+In Koji, the "tag extra" values are inherited.
+So, by default, any tag a given build tag inherits from will contribute its settings.
+The exception is if the inheritance line has the ``noconfig`` flag set.
+
+
+**Priority over macros builds**
+
+Koji places these macro values in the ``mock`` configuration file in for the buildroot.
+The ``mock`` program places them in the ``.rpmmacros`` file in the build directory, which causes
+them to take priority over other macros defined in the build environment.
+
+In short, this method for setting rpm macros "wins".
+
+This can be important when other build tags inherit from yours.
+If the child tag has its own macros build, but inherits your ``rpm.macro.*`` setting, then the
+inherited value will win.