Tutorial: Rewrite using conventions enabled by CMake 3.23

This is a full re-write of the CMake Tutorial for CMake 3.23, both
the functionality it provides, as well as the modern workflows that
developers use when interfacing with CMake.

Issue: #22663, #23086, #23799, #26053, #26105, #26153, #26914

Help/guide/tutorial/Complete/TutorialProject/MathFunctions/CMakeLists.txt

@@ -0,0 +1,55 @@
+add_library(MathFunctions)
+add_library(Tutorial::MathFunctions ALIAS MathFunctions)
+
+target_sources(MathFunctions
+  PRIVATE
+    MathFunctions.cxx
+
+  PUBLIC
+    FILE_SET HEADERS
+    FILES
+      MathFunctions.h
+)
+
+target_link_libraries(MathFunctions
+  PRIVATE
+    MathLogger
+    SqrtTable
+
+  PUBLIC
+    OpAdd
+    OpMul
+    OpSub
+)
+
+target_compile_features(MathFunctions PRIVATE cxx_std_20)
+
+if(TUTORIAL_USE_STD_SQRT)
+  target_compile_definitions(MathFunctions PRIVATE TUTORIAL_USE_STD_SQRT)
+endif()
+
+include(CheckIncludeFiles)
+check_include_files(emmintrin.h HAS_EMMINTRIN LANGUAGE CXX)
+
+if(HAS_EMMINTRIN)
+  target_compile_definitions(MathFunctions PRIVATE TUTORIAL_USE_SSE2)
+endif()
+
+include(CheckSourceCompiles)
+check_source_compiles(CXX
+  [=[
+    typedef double v2df __attribute__((vector_size(16)));
+    int main() {
+      __builtin_ia32_sqrtsd(v2df{});
+    }
+  ]=]
+  HAS_GNU_BUILTIN
+)
+
+if(HAS_GNU_BUILTIN)
+  target_compile_definitions(MathFunctions PRIVATE TUTORIAL_USE_GNU_BUILTIN)
+endif()
+
+add_subdirectory(MathLogger)
+add_subdirectory(MathExtensions)
+add_subdirectory(MakeTable)

Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MakeTable/CMakeLists.txt

@@ -0,0 +1,28 @@
+add_executable(MakeTable)
+
+target_sources(MakeTable
+  PRIVATE
+    MakeTable.cxx
+)
+
+add_custom_command(
+  OUTPUT SqrtTable.h
+  COMMAND MakeTable SqrtTable.h
+  DEPENDS MakeTable
+  VERBATIM
+)
+
+add_custom_target(RunMakeTable DEPENDS SqrtTable.h)
+
+add_library(SqrtTable INTERFACE)
+
+target_sources(SqrtTable
+  INTERFACE
+    FILE_SET HEADERS
+    BASE_DIRS
+      ${CMAKE_CURRENT_BINARY_DIR}
+    FILES
+      ${CMAKE_CURRENT_BINARY_DIR}/SqrtTable.h
+)
+
+add_dependencies(SqrtTable RunMakeTable)

Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MakeTable/MakeTable.cxx

@@ -0,0 +1,25 @@
+// A simple program that builds a sqrt table
+#include <cmath>
+#include <fstream>
+#include <iostream>
+
+int main(int argc, char* argv[])
+{
+  // make sure we have enough arguments
+  if (argc < 2) {
+    return 1;
+  }
+
+  std::ofstream fout(argv[1], std::ios_base::out);
+  bool const fileOpen = fout.is_open();
+  if (fileOpen) {
+    fout << "double sqrtTable[] = {" << std::endl;
+    for (int i = 0; i < 10; ++i) {
+      fout << sqrt(static_cast<double>(i)) << "," << std::endl;
+    }
+    // close the table with a zero
+    fout << "0};" << std::endl;
+    fout.close();
+  }
+  return fileOpen ? 0 : 1; // return 0 if wrote the file
+}

Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/CMakeLists.txt

@@ -0,0 +1,3 @@
+add_subdirectory(OpAdd)
+add_subdirectory(OpMul)
+add_subdirectory(OpSub)

Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpAdd/CMakeLists.txt

@@ -0,0 +1,11 @@
+add_library(OpAdd OBJECT)
+
+target_sources(OpAdd
+  PRIVATE
+    OpAdd.cxx
+
+  INTERFACE
+    FILE_SET HEADERS
+    FILES
+      OpAdd.h
+)

Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpAdd/OpAdd.cxx

@@ -0,0 +1,6 @@
+namespace mathfunctions {
+double OpAdd(double a, double b)
+{
+  return a + b;
+}
+}

Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpAdd/OpAdd.h

@@ -0,0 +1,5 @@
+#pragma once
+
+namespace mathfunctions {
+double OpAdd(double a, double b);
+}

Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpMul/CMakeLists.txt

@@ -0,0 +1,11 @@
+add_library(OpMul OBJECT)
+
+target_sources(OpMul
+  PRIVATE
+    OpMul.cxx
+
+  INTERFACE
+    FILE_SET HEADERS
+    FILES
+      OpMul.h
+)

Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpMul/OpMul.cxx

@@ -0,0 +1,6 @@
+namespace mathfunctions {
+double OpMul(double a, double b)
+{
+  return a * b;
+}
+}

Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpMul/OpMul.h

@@ -0,0 +1,5 @@
+#pragma once
+
+namespace mathfunctions {
+double OpMul(double a, double b);
+}

Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpSub/CMakeLists.txt

@@ -0,0 +1,11 @@
+add_library(OpSub OBJECT)
+
+target_sources(OpSub
+  PRIVATE
+    OpSub.cxx
+
+  INTERFACE
+    FILE_SET HEADERS
+    FILES
+      OpSub.h
+)

Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpSub/OpSub.cxx

@@ -0,0 +1,6 @@
+namespace mathfunctions {
+double OpSub(double a, double b)
+{
+  return a - b;
+}
+}

Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpSub/OpSub.h

@@ -0,0 +1,5 @@
+#pragma once
+
+namespace mathfunctions {
+double OpSub(double a, double b);
+}

Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathFunctions.cxx

@@ -0,0 +1,101 @@
+#include <cmath>
+#include <format>
+
+#include <MathLogger.h>
+
+#ifdef TUTORIAL_USE_SSE2
+#  include <emmintrin.h>
+#endif
+
+namespace {
+
+mathlogger::Logger Logger;
+
+#if defined(TUTORIAL_USE_GNU_BUILTIN)
+typedef double v2df __attribute__((vector_size(16)));
+
+double gnu_mysqrt(double x)
+{
+  v2df root = __builtin_ia32_sqrtsd(v2df{ x, 0.0 });
+  double result = root[0];
+  Logger.Log(std::format("Computed sqrt of {} to be {} with GNU-builtins\n", x,
+                         result));
+  return result;
+}
+#elif defined(TUTORIAL_USE_SSE2)
+double sse2_mysqrt(double x)
+{
+  __m128d root = _mm_sqrt_sd(_mm_setzero_pd(), _mm_set_sd(x));
+  double result = _mm_cvtsd_f64(root);
+  Logger.Log(
+    std::format("Computed sqrt of {} to be {} with SSE2\n", x, result));
+  return result;
+}
+#endif
+
+// a hack square root calculation using simple operations
+double fallback_mysqrt(double x)
+{
+  if (x <= 0) {
+    return 0;
+  }
+
+  double result = x;
+
+  // do ten iterations
+  for (int i = 0; i < 10; ++i) {
+    if (result <= 0) {
+      result = 0.1;
+    }
+    double delta = x - (result * result);
+    result = result + 0.5 * delta / result;
+
+    Logger.Log(std::format("Computing sqrt of {} to be {}\n", x, result));
+  }
+  return result;
+}
+
+#include <SqrtTable.h>
+
+double table_sqrt(double x)
+{
+  double result = sqrtTable[static_cast<int>(x)];
+  // do ten iterations
+  for (int i = 0; i < 10; ++i) {
+    if (result <= 0) {
+      result = 0.1;
+    }
+    double delta = x - (result * result);
+    result = result + 0.5 * delta / result;
+  }
+  Logger.Log(
+    std::format("Computed sqrt of {} to be {} with TableSqrt\n", x, result));
+  return result;
+}
+
+double mysqrt(double x)
+{
+  if (x >= 1 && x < 10) {
+    return table_sqrt(x);
+  }
+
+#if defined(TUTORIAL_USE_GNU_BUILTIN)
+  return gnu_mysqrt(x);
+#elif defined(TUTORIAL_USE_SSE2)
+  return sse2_mysqrt(x);
+#else
+  return fallback_mysqrt(x);
+#endif
+}
+}
+
+namespace mathfunctions {
+double sqrt(double x)
+{
+#ifdef TUTORIAL_USE_STD_SQRT
+  return std::sqrt(x);
+#else
+  return mysqrt(x);
+#endif
+}
+}

Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathFunctions.h

@@ -0,0 +1,9 @@
+#pragma once
+
+#include <OpAdd.h>
+#include <OpMul.h>
+#include <OpSub.h>
+
+namespace mathfunctions {
+double sqrt(double x);
+}

Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathLogger/CMakeLists.txt

@@ -0,0 +1,6 @@
+add_library(MathLogger INTERFACE)
+
+target_sources(MathLogger
+  INTERFACE
+    FILE_SET HEADERS
+)

Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathLogger/MathFormatting.h

@@ -0,0 +1,27 @@
+#pragma once
+
+#include <string>
+
+namespace mathlogger {
+
+enum LogLevel
+{
+  INFO,
+  WARN,
+  ERROR,
+};
+
+inline std::string FormatLog(LogLevel level, std::string const& message)
+{
+  switch (level) {
+    case INFO:
+      return "INFO: " + message;
+    case WARN:
+      return "WARN: " + message;
+    case ERROR:
+      return "ERROR: " + message;
+  }
+  return "UNKNOWN: " + message;
+}
+
+}

Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathLogger/MathLogger.h

@@ -0,0 +1,22 @@
+#pragma once
+
+#include <string>
+
+#include "MathFormatting.h"
+#include "MathOutput.h"
+
+namespace mathlogger {
+
+struct Logger
+{
+  LogLevel level = INFO;
+
+  void SetLevel(LogLevel new_level) { level = new_level; }
+  void Log(std::string const& message)
+  {
+    std::string formatted = FormatLog(level, message);
+    WriteLog(formatted);
+  }
+};
+
+}

Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathLogger/MathOutput.h

@@ -0,0 +1,11 @@
+#pragma once
+
+#include <iostream>
+#include <string>
+
+namespace mathlogger {
+inline void WriteLog(std::string const& msg)
+{
+  std::cout << msg;
+}
+}