From 29ac8e4cd7cd0106093f9dc986c76c2bc30e750b Mon Sep 17 00:00:00 2001
From: Igor Raits <ignatenkobrain@fedoraproject.org>
Date: Jul 18 2020 18:40:26 +0000
Subject: Update CMake guidelines


References: https://fedoraproject.org/wiki/Changes/CMake_to_do_out-of-source_builds
Signed-off-by: Igor Raits <ignatenkobrain@fedoraproject.org>

---

diff --git a/guidelines/modules/ROOT/nav.adoc b/guidelines/modules/ROOT/nav.adoc
index 8c0bfd7..4ff4325 100644
--- a/guidelines/modules/ROOT/nav.adoc
+++ b/guidelines/modules/ROOT/nav.adoc
@@ -3,18 +3,17 @@
 * xref:Alternatives.adoc[Alternatives]
 * xref:AppData.adoc[AppData]
 * xref:AutoProvidesAndRequiresFiltering.adoc[Dependency Filtering]
-* xref:CMake.adoc[CMake]
 * xref:Conflicts.adoc[Conflicts]
 * xref:CryptoPolicies.adoc[Crypto Policies]
 * xref:Debuginfo.adoc[Debuginfo]
 * xref:DefaultServices.adoc[Default Services]
+* xref:vpath.adoc[Defining source and build directories]
 * xref:deprecating-packages.adoc[Deprecating Packages]
 * xref:Directory_Replacement.adoc[Directory Replacement]
 * xref:DistTag.adoc[Dist Tag]
 * xref:Initial_Service_Setup.adoc[Initial Service Setup]
 * xref:Langpacks.adoc[Language Packs]
 * xref:LicensingGuidelines.adoc[Licensing]
-* xref:Meson.adoc[Meson]
 * xref:Naming.adoc[Naming]
 * xref:PatchUpstreamStatus.adoc[Patch Status]
 * xref:Per-Product_Configuration.adoc[Per-Product Configuration]
@@ -34,6 +33,10 @@
 * xref:WeakDependencies.adoc[Weak Dependencies]
 * xref:what-can-be-packaged.adoc[What Can Be Packaged]
 
+* Build Systems
+** xref:CMake.adoc[CMake]
+** xref:Meson.adoc[Meson]
+
 * Programming Languages
 ** xref:Ada.adoc[Ada]
 ** xref:C_and_C++.adoc[C and {cpp}]
diff --git a/guidelines/modules/ROOT/pages/CMake.adoc b/guidelines/modules/ROOT/pages/CMake.adoc
index b84a838..d212d2d 100644
--- a/guidelines/modules/ROOT/pages/CMake.adoc
+++ b/guidelines/modules/ROOT/pages/CMake.adoc
@@ -1,30 +1,61 @@
-= Guidelines for CMake
+:last-reviewed: 2020-07-18
 
-This document provides CMake best-practices for generating Fedora RPMS using CMake
+= CMake Packaging Guidelines
+:toc:
 
-== RPM Macros
+This document provides best practices for the usage of https://cmake.org/[the CMake build system] in Fedora packages.
 
-If CMake is installed, see `+/usr/lib/rpm/macros.d/macros.cmake+`.
+== Build Dependencies
 
-If kde-filesystem is installed, see `+/usr/lib/rpm/macros.d/macros.kde4+`
+You *MUST* add following BuildRequires:
 
-== Specfile Usage
+....
+BuildRequires: cmake
+....
+
+== Available Macros
+
+You will generally make use of these in your specs:
+
+`+%cmake+`::
+  Defines CFLAGS, LDFLAGS, etc. and calls `+%__cmake+` with appropriate parameters (`+-DCMAKE_INSTALL_PREFIX:PATH=/usr+` and such). You can pass `+-Doption=value+` to this macro in order to set options for the buildsystem.
+`+%cmake_build+`::
+  Builds the project (using `+%__cmake --build+`).
+`+%cmake_install+`::
+  Installs the built project (using `+%__cmake --install+`).
+`+%ctest+`::
+  Runs the tests that are defined with `+add_test()+` in project (using `+%__ctest+`).
+
+When packaging KDE software, you most likely would replace `+%cmake+` with `+%cmake_kf5+` that defines multiple KDE-related variables (shipped in `+kf5+` package).
+
+It is rarely necessary (but permissible) to use or alter these:
+
+`+%__cmake+`::
+  The path to the cmake executable.
+`+%__ctest+`::
+  The path to the ctest executable.
+`+%__cmake_in_source_build+`::
+  Controls whether builds are done in-source (when defined) or out-of-source (when undefined).
+  See the xref:vpath.adoc[Defining source and build directories] for more information.
+
+== Example usage in the spec file
 
 ....
 %build
-%cmake .
-%make_build
-
+%cmake
+%cmake_build
 
 %install
-%make_install
+%cmake_install
 
 %check
-ctest -V %{?_smp_mflags}
+%ctest
 ....
 
 == Notes
 
+NOTE: Since Fedora 33, `+%__cmake_in_source_build+` is not defined so if you want to have consistent behavior across different releases, make sure to `+%define+` or `+%undefine+` it accordingly.
+
 *NOTE*: `+-DCMAKE_SKIP_RPATH:BOOL=ON+`.
 With recent cmake-2.4, it should not be used.
 This CMake version should handle RPATHs issues correctly (set them in build-dir, remove them during installation).
@@ -37,5 +68,5 @@ in this case `+INSTALL(TARGETS ...)+` must be used in combination with changing 
 
 *NOTE*: CMake has good documentation in two places:
 
-* https://www.cmake.org/documentation/
+* https://cmake.org/documentation/
 * https://gitlab.kitware.com/cmake/community/wikis/Home
diff --git a/guidelines/modules/ROOT/pages/Meson.adoc b/guidelines/modules/ROOT/pages/Meson.adoc
index 343d3a2..363b4a2 100644
--- a/guidelines/modules/ROOT/pages/Meson.adoc
+++ b/guidelines/modules/ROOT/pages/Meson.adoc
@@ -16,23 +16,22 @@ BuildRequires: meson
 You will generally make use of these in your specs:
 
 `+%meson+`::
-  Defines CFLAGS, LDFLAGS, etc. and calls %__meson with appropriate parameters (`+--libdir=%{_libdir}+` and such). You can pass `+-Doption=value+` to this macro in order to set options for the buildsystem.
+  Defines CFLAGS, LDFLAGS, etc. and calls `+%__meson+` with appropriate parameters (`+--libdir=%{_libdir}+` and such).
+  You can pass `+-Doption=value+` to this macro in order to set options for the buildsystem.
 `+%meson_build+`::
-  An alias for `+%ninja_build -C %{_vpath_builddir}+`
+  An alias for `+%ninja_build -C %{_vpath_builddir}+`.
 `+%meson_install+`::
-  An alias for `+%ninja_install -C %{_vpath_builddir}+`
+  An alias for `+%ninja_install -C %{_vpath_builddir}+`.
 `+%meson_test+`::
-  An alias for `+%ninja_test -C %{_vpath_builddir}+`
+  An alias for `+%ninja_test -C %{_vpath_builddir}+`.
 
 It is rarely necessary (but permissible) to use or alter these:
 
-`+%_vpath_srcdir+`::
-  Path (relative to the RPM build directory) where the sources to be built are located (default: `+.+`)
-`+%_vpath_builddir+`::
-  Path (relative to the RPM build directory) where the built objects are located (default: `+%{_target_platform}+`)
 `+%__meson+`::
   The path to the meson executable
 
+Also see xref:vpath.adoc[Defining source and build directories].
+
 == Example RPM spec file
 
 ....
diff --git a/guidelines/modules/ROOT/pages/vpath.adoc b/guidelines/modules/ROOT/pages/vpath.adoc
new file mode 100644
index 0000000..0df660c
--- /dev/null
+++ b/guidelines/modules/ROOT/pages/vpath.adoc
@@ -0,0 +1,13 @@
+= Defining source and build directories
+
+Build systems that support defining source/build directories via RPM macros:
+
+* xref:CMake.adoc[CMake]
+* xref:Meson.adoc[Meson]
+
+Macros:
+
+`+%_vpath_srcdir+`::
+  Path (relative to the RPM build directory) where the sources to be built are located (default: `+.+`).
+`+%_vpath_builddir+`::
+  Path (relative to the RPM build directory) where the built objects are located (default: `+%{_target_platform}+`).