mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-01-05 21:31:08 -06:00
Code Issues Packages Projects Releases Wiki Activity

Tutorial: Rewrite using conventions enabled by CMake 3.23

Browse Source 
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
This commit is contained in:
Vito Gamberini
2025-08-20 12:42:42 -04:00
committed by Brad King
parent 9e89400d13
commit b2e3e3e30e
361 changed files with 10167 additions and 4863 deletions
Download Patch File Download Diff File Expand all files Collapse all files

127
Help/guide/tutorial/Complete/CMakeLists.txt
View File

@@ -1,127 +0,0 @@
cmake_minimum_required(VERSION 3.15)
# set the project name and version
project(Tutorial VERSION 1.0)
set(CMAKE_DEBUG_POSTFIX d)
add_library(tutorial_compiler_flags INTERFACE)
target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11)
# add compiler warning flags just when building this project via
# the BUILD_INTERFACE genex
set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU,LCC>")
set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>")
target_compile_options(tutorial_compiler_flags INTERFACE
"$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>"
"$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>"
)
# control where the static and shared libraries are built so that on windows
# we don't need to tinker with the path to run the executable
set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
option(BUILD_SHARED_LIBS "Build using shared libraries" ON)
if(APPLE)
set(CMAKE_INSTALL_RPATH "@executable_path/../lib")
elseif(UNIX)
set(CMAKE_INSTALL_RPATH "$ORIGIN/../lib")
endif()
# configure a header file to pass the version number only
configure_file(TutorialConfig.h.in TutorialConfig.h)
# add the MathFunctions library
add_subdirectory(MathFunctions)
# add the executable
add_executable(Tutorial tutorial.cxx)
set_target_properties(Tutorial PROPERTIES DEBUG_POSTFIX ${CMAKE_DEBUG_POSTFIX})
target_link_libraries(Tutorial PUBLIC MathFunctions tutorial_compiler_flags)
# add the binary tree to the search path for include files
# so that we will find TutorialConfig.h
target_include_directories(Tutorial PUBLIC
"${PROJECT_BINARY_DIR}"
)
# add the install targets
install(TARGETS Tutorial DESTINATION bin)
install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h"
DESTINATION include
)
# enable testing
enable_testing()
# does the application run
add_test(NAME Runs COMMAND Tutorial 25)
# does the usage message work?
add_test(NAME Usage COMMAND Tutorial)
set_tests_properties(Usage
PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number"
)
# define a function to simplify adding tests
function(do_test target arg result)
add_test(NAME Comp${arg} COMMAND ${target} ${arg})
set_tests_properties(Comp${arg}
PROPERTIES PASS_REGULAR_EXPRESSION ${result}
)
endfunction()
# do a bunch of result based tests
do_test(Tutorial 4 "4 is 2")
do_test(Tutorial 9 "9 is 3")
do_test(Tutorial 5 "5 is 2.236")
do_test(Tutorial 7 "7 is 2.645")
do_test(Tutorial 25 "25 is 5")
do_test(Tutorial -25 "-25 is (-nan|nan|0)")
do_test(Tutorial 0.0001 "0.0001 is 0.01")
# setup installer
include(InstallRequiredSystemLibraries)
set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt")
set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}")
set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}")
set(CPACK_GENERATOR "TGZ")
set(CPACK_SOURCE_GENERATOR "TGZ")
include(CPack)
# install the configuration targets
install(EXPORT MathFunctionsTargets
FILE MathFunctionsTargets.cmake
DESTINATION lib/cmake/MathFunctions
)
include(CMakePackageConfigHelpers)
# generate the config file that is includes the exports
configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in
"${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake"
INSTALL_DESTINATION "lib/cmake/example"
NO_SET_AND_CHECK_MACRO
NO_CHECK_REQUIRED_COMPONENTS_MACRO
)
# generate the version file for the config file
write_basic_package_version_file(
"${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfigVersion.cmake"
VERSION "${Tutorial_VERSION_MAJOR}.${Tutorial_VERSION_MINOR}"
COMPATIBILITY AnyNewerVersion
)
# install the configuration file
install(FILES
${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake
DESTINATION lib/cmake/MathFunctions
)
# generate the export targets for the build tree
# needs to be after the install(TARGETS) command
export(EXPORT MathFunctionsTargets
FILE "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsTargets.cmake"
)

3
Help/guide/tutorial/Complete/CTestConfig.cmake
View File

@@ -1,3 +0,0 @@
set(CTEST_NIGHTLY_START_TIME "00:00:00 EST")
set(CTEST_SUBMIT_URL "https://my.cdash.org/submit.php?project=CMakeTutorial")

4
Help/guide/tutorial/Complete/Config.cmake.in
View File

@@ -1,4 +0,0 @@
@PACKAGE_INIT@
include ( "${CMAKE_CURRENT_LIST_DIR}/MathFunctionsTargets.cmake" )

2
Help/guide/tutorial/Complete/License.txt
View File

@@ -1,2 +0,0 @@
This is the open source License.txt file introduced in
CMake/Tutorial/Step9...

62
Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt
View File

@@ -1,62 +0,0 @@
# add the library that runs
add_library(MathFunctions MathFunctions.cxx)
# state that anybody linking to us needs to include the current source dir
# to find MathFunctions.h, while we don't.
target_include_directories(MathFunctions
INTERFACE
$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>
$<INSTALL_INTERFACE:include>
)
# should we use our own math functions
option(USE_MYMATH "Use tutorial provided math implementation" ON)
if(USE_MYMATH)
target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH")
include(MakeTable.cmake) # generates Table.h
# library that just does sqrt
add_library(SqrtLibrary STATIC
mysqrt.cxx
${CMAKE_CURRENT_BINARY_DIR}/Table.h
)
# state that we depend on our binary dir to find Table.h
target_include_directories(SqrtLibrary PRIVATE
${CMAKE_CURRENT_BINARY_DIR}
)
# state that SqrtLibrary need PIC when the default is shared libraries
set_target_properties(SqrtLibrary PROPERTIES
POSITION_INDEPENDENT_CODE ${BUILD_SHARED_LIBS}
)
# link SqrtLibrary to tutorial_compiler_flags
target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags)
target_link_libraries(MathFunctions PRIVATE SqrtLibrary)
endif()
# link MathFunctions to tutorial_compiler_flags
target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags)
# define the symbol stating we are using the declspec(dllexport) when
# building on windows
target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH")
# setup the version numbering
set_property(TARGET MathFunctions PROPERTY VERSION "1.0.0")
set_property(TARGET MathFunctions PROPERTY SOVERSION "1")
# install libs
set(installable_libs MathFunctions tutorial_compiler_flags)
if(TARGET SqrtLibrary)
list(APPEND installable_libs SqrtLibrary)
endif()
install(TARGETS ${installable_libs}
EXPORT MathFunctionsTargets
DESTINATION lib)
# install include headers
install(FILES MathFunctions.h DESTINATION include)

10
Help/guide/tutorial/Complete/MathFunctions/MakeTable.cmake
View File

@@ -1,10 +0,0 @@
# first we add the executable that generates the table
add_executable(MakeTable MakeTable.cxx)
target_link_libraries(MakeTable PRIVATE tutorial_compiler_flags)
# add the command to generate the source code
add_custom_command(
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h
COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h
DEPENDS MakeTable
)

20
Help/guide/tutorial/Complete/MathFunctions/MathFunctions.cxx
View File

@@ -1,20 +0,0 @@
#include "MathFunctions.h"
#include <cmath>
#ifdef USE_MYMATH
# include "mysqrt.h"
#endif
namespace mathfunctions {
double sqrt(double x)
{
// which square root function should we use?
#ifdef USE_MYMATH
return detail::mysqrt(x);
#else
return std::sqrt(x);
#endif
}
}

14
Help/guide/tutorial/Complete/MathFunctions/MathFunctions.h
View File

@@ -1,14 +0,0 @@
#if defined(_WIN32)
# if defined(EXPORTING_MYMATH)
# define DECLSPEC __declspec(dllexport)
# else
# define DECLSPEC __declspec(dllimport)
# endif
#else // non windows
# define DECLSPEC
#endif
namespace mathfunctions {
double DECLSPEC sqrt(double x);
}

37
Help/guide/tutorial/Complete/MathFunctions/mysqrt.cxx
View File

@@ -1,37 +0,0 @@
#include <iostream>
#include "MathFunctions.h"
// include the generated table
#include "Table.h"
namespace mathfunctions {
namespace detail {
// a hack square root calculation using simple operations
double mysqrt(double x)
{
if (x <= 0) {
return 0;
}
// use the table to help find an initial value
double result = x;
if (x >= 1 && x < 10) {
std::cout << "Use the table to help find an initial value " << std::endl;
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;
std::cout << "Computing sqrt of " << x << " to be " << result << std::endl;
}
return result;
}
}
}

6
Help/guide/tutorial/Complete/MathFunctions/mysqrt.h
View File

@@ -1,6 +0,0 @@
namespace mathfunctions {
namespace detail {
double mysqrt(double x);
}
}

6
Help/guide/tutorial/Complete/MultiCPackConfig.cmake
View File

@@ -1,6 +0,0 @@
include("release/CPackConfig.cmake")
set(CPACK_INSTALL_CMAKE_PROJECTS
"debug;Tutorial;ALL;/"
"release;Tutorial;ALL;/"
)

53
Help/guide/tutorial/Complete/SimpleTest/CMakeLists.txt Normal file
View File

@@ -0,0 +1,53 @@
# A very simple test framework for demonstrating how dependencies work
cmake_minimum_required(VERSION 3.23)
project(SimpleTest
VERSION 0.0.1
)
add_library(SimpleTest INTERFACE)
target_sources(SimpleTest
INTERFACE
FILE_SET HEADERS
FILES
SimpleTest.h
)
target_compile_features(SimpleTest INTERFACE cxx_std_20)
target_compile_definitions(SimpleTest INTERFACE "SIMPLETEST_CONFIG=$<CONFIG>")
find_package(TransitiveDep REQUIRED)
target_link_libraries(SimpleTest
INTERFACE
TransitiveDep::TransitiveDep
)
include(GNUInstallDirs)
include(CMakePackageConfigHelpers)
install(
TARGETS SimpleTest
EXPORT SimpleTestTargets
FILE_SET HEADERS
)
install(
EXPORT SimpleTestTargets
DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/SimpleTest
NAMESPACE SimpleTest::
)
write_basic_package_version_file(
${CMAKE_CURRENT_BINARY_DIR}/SimpleTestConfigVersion.cmake
COMPATIBILITY ExactVersion
ARCH_INDEPENDENT
)
install(
FILES
cmake/simpletest_discover_impl.cmake
cmake/simpletest_discover_tests.cmake
cmake/SimpleTestConfig.cmake
${CMAKE_CURRENT_BINARY_DIR}/SimpleTestConfigVersion.cmake
DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/SimpleTest
)

16
Help/guide/tutorial/Complete/SimpleTest/CMakePresets.json Normal file
View File

@@ -0,0 +1,16 @@
{
"version": 4,
"configurePresets": [
{
"name": "tutorial",
"displayName": "SimpleTest Preset",
"description": "Preset to use with the tutorial's SimpleTest library",
"binaryDir": "${sourceDir}/build",
"installDir": "${sourceParentDir}/install",
"cacheVariables": {
"CMAKE_CXX_STANDARD": "20",
"CMAKE_PREFIX_PATH": "${sourceParentDir}/install"
}
}
]
}

155
Help/guide/tutorial/Complete/SimpleTest/SimpleTest.h Normal file
View File

@@ -0,0 +1,155 @@
#pragma once
#include <cstdio>
#include <map>
#include <string_view>
namespace SimpleTest {
using TestFunc = void (*)();
using Registry = std::map<std::string_view, TestFunc, std::less<>>;
inline Registry g_registry;
inline Registry& registry()
{
return g_registry;
}
struct failure
{
char const* file;
int line;
char const* expr;
};
struct Registrar
{
template <std::size_t N>
Registrar(char const (&name)[N], TestFunc f)
{
auto [it, inserted] =
registry().emplace(std::string_view{ name, N ? (N - 1) : 0 }, f);
if (!inserted) {
std::printf("[ WARN ] duplicate test name: %.*s\n",
int(it->first.size()), it->first.data());
}
}
};
inline Registry const& all()
{
return registry();
}
inline TestFunc find(std::string_view name)
{
auto it = registry().find(name);
return it == registry().end() ? nullptr : it->second;
}
}
#define SIMPLETEST_STRINGIFY(a) #a
#define SIMPLETEST_XSTRINGIFY(a) SIMPLETEST_STRINGIFY(a)
#define SIMPLETEST_CONCAT_(a, b) a##b
#define SIMPLETEST_CONCAT(a, b) SIMPLETEST_CONCAT_(a, b)
#define TEST(name_literal) \
static void SIMPLETEST_CONCAT(_simpletest_fn_, __LINE__)(); \
static ::SimpleTest::Registrar SIMPLETEST_CONCAT(_simpletest_reg_, \
__LINE__)( \
name_literal, &SIMPLETEST_CONCAT(_simpletest_fn_, __LINE__)); \
static void SIMPLETEST_CONCAT(_simpletest_fn_, __LINE__)()
// Minimal assertion
#define REQUIRE(expr) \
do { \
if (!(expr)) \
throw ::SimpleTest::failure{ __FILE__, __LINE__, #expr }; \
} while (0)
int main(int argc, char** argv)
{
using namespace ::SimpleTest;
std::string_view arg1 =
(argc >= 2) ? std::string_view{ argv[1] } : std::string_view{};
if (arg1 == "--list") {
bool first = true;
for (auto const& [name, _] : registry()) {
if (!first)
std::printf(",");
std::printf("%.*s", int(name.size()), name.data());
first = false;
}
std::printf("\n");
return 0;
}
if (arg1 == "--test") {
if (argc < 3) {
std::printf("usage: %s [--list] [--test <name>]\n", argv[0]);
return 2;
}
#ifdef SIMPLETEST_CONFIG
std::printf("SimpleTest built with config: " SIMPLETEST_XSTRINGIFY(
SIMPLETEST_CONFIG) "\n");
#endif
std::string_view name{ argv[2] };
auto it = registry().find(name);
if (it == registry().end()) {
std::printf("[ NOTFOUND ] %s\n", argv[2]);
return 2;
}
int failed = 0;
std::printf("[ RUN ] %.*s\n", int(it->first.size()),
it->first.data());
try {
it->second();
std::printf("[ OK] %.*s\n", int(it->first.size()),
it->first.data());
} catch (failure const& f) {
std::printf("[ FAILED ] %.*s at %s:%d : %s\n", int(it->first.size()),
it->first.data(), f.file, f.line, f.expr);
failed = 1;
} catch (...) {
std::printf("[ FAILED ] %.*s : unknown exception\n",
int(it->first.size()), it->first.data());
failed = 1;
}
return failed;
}
if (argc > 1) {
std::printf("usage: %s [--list] [--test <name>]\n", argv[0]);
return 2;
}
#ifdef SIMPLETEST_CONFIG
std::printf("SimpleTest built with config: " SIMPLETEST_XSTRINGIFY(
SIMPLETEST_CONFIG) "\n");
#endif
// Default: run all tests.
int failed = 0;
for (auto const& [name, func] : all()) {
std::printf("[ RUN ] %.*s\n", int(name.size()), name.data());
try {
func();
std::printf("[ OK ] %.*s\n", int(name.size()), name.data());
} catch (failure const& f) {
std::printf("[ FAILED ] %.*s at %s:%d : %s\n", int(name.size()),
name.data(), f.file, f.line, f.expr);
failed = 1;
} catch (...) {
std::printf("[ FAILED ] %.*s : unknown exception\n", int(name.size()),
name.data());
failed = 1;
}
}
return failed;
}

5
Help/guide/tutorial/Complete/SimpleTest/cmake/SimpleTestConfig.cmake Normal file
View File

@@ -0,0 +1,5 @@
include(CMakeFindDependencyMacro)
find_dependency(TransitiveDep)
include(${CMAKE_CURRENT_LIST_DIR}/SimpleTestTargets.cmake)
include(${CMAKE_CURRENT_LIST_DIR}/simpletest_discover_tests.cmake)

32
Help/guide/tutorial/Complete/SimpleTest/cmake/simpletest_discover_impl.cmake Normal file
View File

@@ -0,0 +1,32 @@
if(NOT DEFINED TEST_EXE OR NOT DEFINED OUT_FILE)
# noqa: spellcheck off
message(FATAL_ERROR "simpletest_discover: need -DTEST_EXE and -DOUT_FILE")
# noqa: spellcheck on
endif()
execute_process(
COMMAND ${TEST_EXE} --list
RESULT_VARIABLE _rc
OUTPUT_VARIABLE _out
ERROR_VARIABLE _err
OUTPUT_STRIP_TRAILING_WHITESPACE
)
if(NOT _rc EQUAL 0)
file(WRITE ${OUT_FILE} "# simpletest: --list failed (rc=${_rc})\n")
message(FATAL_ERROR "simpletest_discover: '${TEST_EXE} --list' failed (${_rc})\n${_err}")
endif()
if(_out STREQUAL "")
file(WRITE ${OUT_FILE} "# simpletest: no tests\n")
return()
endif()
string(REPLACE "," ";" _names "${_out}")
file(WRITE ${OUT_FILE} "# Auto-generated by simpletest_discover_impl.cmake\n")
foreach(_name IN LISTS _names)
file(APPEND ${OUT_FILE}
"add_test([=[${_name}]=] \"${TEST_EXE}\" \"--test\" \"${_name}\")\n"
)
endforeach()

27
Help/guide/tutorial/Complete/SimpleTest/cmake/simpletest_discover_tests.cmake Normal file
View File

@@ -0,0 +1,27 @@
set(_simpletest_impl_script ${CMAKE_CURRENT_LIST_DIR}/simpletest_discover_impl.cmake)
function(simpletest_discover_tests target)
if(NOT TARGET ${target})
message(FATAL_ERROR "simpletest_discover_tests: no such target '${target}'")
endif()
set(_out ${CMAKE_CURRENT_BINARY_DIR}/${target}_ctests.cmake)
if(NOT EXISTS ${_out})
file(WRITE ${_out} "# Populated after building ${target}\n")
endif()
# noqa: spellcheck off
add_custom_command(TARGET ${target} POST_BUILD
COMMAND ${CMAKE_COMMAND}
-DTEST_EXE=$<TARGET_FILE:${target}>
-DOUT_FILE=${_out}
-P ${_simpletest_impl_script}
BYPRODUCTS ${_out}
COMMENT "SimpleTest: Discovering tests in ${target}"
VERBATIM
)
# noqa: spellcheck on
set_property(DIRECTORY APPEND PROPERTY TEST_INCLUDE_FILES ${_out})
endfunction()

3
Help/guide/tutorial/Complete/TutorialConfig.h.in
View File

@@ -1,3 +0,0 @@
// the configured options and settings for Tutorial
#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@
#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@

59
Help/guide/tutorial/Complete/TutorialProject/CMakeLists.txt Normal file
View File

@@ -0,0 +1,59 @@
cmake_minimum_required(VERSION 3.23)
project(Tutorial
VERSION 1.0.0
)
option(TUTORIAL_BUILD_UTILITIES "Build the Tutorial executable" ON)
option(TUTORIAL_USE_STD_SQRT "Use std::sqrt" OFF)
option(TUTORIAL_ENABLE_IPO "Check for and use IPO support" ON)
option(BUILD_TESTING "Enable testing and build tests" ON)
if(TUTORIAL_ENABLE_IPO)
include(CheckIPOSupported)
check_ipo_supported(RESULT result OUTPUT output)
if(result)
set(CMAKE_INTERPROCEDURAL_OPTIMIZATION ON)
else()
message(WARNING "IPO is not supported ${message}")
endif()
endif()
if(TUTORIAL_BUILD_UTILITIES)
add_subdirectory(Tutorial)
endif()
if(BUILD_TESTING)
enable_testing()
add_subdirectory(Tests)
endif()
add_subdirectory(MathFunctions)
include(GNUInstallDirs)
install(
TARGETS MathFunctions OpAdd OpMul OpSub MathLogger SqrtTable
EXPORT TutorialTargets
FILE_SET HEADERS
)
install(
EXPORT TutorialTargets
DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/Tutorial
NAMESPACE Tutorial::
)
include(CMakePackageConfigHelpers)
write_basic_package_version_file(
${CMAKE_CURRENT_BINARY_DIR}/TutorialConfigVersion.cmake
COMPATIBILITY ExactVersion
)
install(
FILES
cmake/TutorialConfig.cmake
${CMAKE_CURRENT_BINARY_DIR}/TutorialConfigVersion.cmake
DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/Tutorial
)

16
Help/guide/tutorial/Complete/TutorialProject/CMakePresets.json Normal file
View File

@@ -0,0 +1,16 @@
{
"version": 4,
"configurePresets": [
{
"name": "tutorial",
"displayName": "Tutorial Preset",
"description": "Preset to use with the tutorial",
"binaryDir": "${sourceDir}/build",
"cacheVariables": {
"CMAKE_PREFIX_PATH": "${sourceParentDir}/install",
"TUTORIAL_USE_STD_SQRT": "OFF",
"TUTORIAL_ENABLE_IPO": "OFF"
}
}
]
}

55
Help/guide/tutorial/Complete/TutorialProject/MathFunctions/CMakeLists.txt Normal file
View File

@@ -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)

28
Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MakeTable/CMakeLists.txt Normal file
View File

@@ -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)

0
Help/guide/tutorial/Complete/MathFunctions/MakeTable.cxx → Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MakeTable/MakeTable.cxx
View File

3
Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/CMakeLists.txt Normal file
View File

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

11
Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpAdd/CMakeLists.txt Normal file
View File

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

6
Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpAdd/OpAdd.cxx Normal file
View File

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

5
Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpAdd/OpAdd.h Normal file
View File

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

11
Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpMul/CMakeLists.txt Normal file
View File

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

6
Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpMul/OpMul.cxx Normal file
View File

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

5
Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpMul/OpMul.h Normal file
View File

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

11
Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpSub/CMakeLists.txt Normal file
View File

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

6
Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpSub/OpSub.cxx Normal file
View File

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

5
Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpSub/OpSub.h Normal file
View File

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

101
Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathFunctions.cxx Normal file
View File

@@ -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
}
}

9
Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathFunctions.h Normal file
View File

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

6
Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathLogger/CMakeLists.txt Normal file
View File

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

27
Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathLogger/MathFormatting.h Normal file
View File

@@ -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;
}
}

22
Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathLogger/MathLogger.h Normal file
View File

@@ -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);
}
};
}

11
Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathLogger/MathOutput.h Normal file
View File

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

16
Help/guide/tutorial/Complete/TutorialProject/Tests/CMakeLists.txt Normal file
View File

@@ -0,0 +1,16 @@
add_executable(TestMathFunctions)
target_sources(TestMathFunctions
PRIVATE
TestMathFunctions.cxx
)
find_package(SimpleTest REQUIRED)
target_link_libraries(TestMathFunctions
PRIVATE
MathFunctions
SimpleTest::SimpleTest
)
simpletest_discover_tests(TestMathFunctions)

22
Help/guide/tutorial/Complete/TutorialProject/Tests/TestMathFunctions.cxx Normal file
View File

@@ -0,0 +1,22 @@
#include <MathFunctions.h>
#include <SimpleTest.h>
TEST("add")
{
REQUIRE(mathfunctions::OpAdd(2.0, 2.0) == 4.0);
}
TEST("sub")
{
REQUIRE(mathfunctions::OpSub(4.0, 2.0) == 2.0);
}
TEST("mul")
{
REQUIRE(mathfunctions::OpMul(5.0, 5.0) == 25.0);
}
TEST("sqrt")
{
REQUIRE(mathfunctions::sqrt(25.0) == 5.0);
}

39
Help/guide/tutorial/Complete/TutorialProject/Tutorial/CMakeLists.txt Normal file
View File

@@ -0,0 +1,39 @@
add_executable(Tutorial)
target_sources(Tutorial
PRIVATE
Tutorial.cxx
)
target_link_libraries(Tutorial
PRIVATE
MathFunctions
)
target_compile_features(Tutorial PRIVATE cxx_std_20)
if(
(CMAKE_CXX_COMPILER_ID STREQUAL "MSVC") OR
(CMAKE_CXX_COMPILER_FRONTEND_VARIANT STREQUAL "MSVC")
)
target_compile_options(Tutorial PRIVATE /W3)
elseif(
(CMAKE_CXX_COMPILER_ID STREQUAL "GNU") OR
(CMAKE_CXX_COMPILER_ID MATCHES "Clang")
)
target_compile_options(Tutorial PRIVATE -Wall)
endif()
find_path(UnpackagedIncludeFolder Unpackaged.h REQUIRED
PATH_SUFFIXES
Unpackaged
)
target_include_directories(Tutorial
PRIVATE
${UnpackagedIncludeFolder}
)

27
Help/guide/tutorial/Complete/TutorialProject/Tutorial/Tutorial.cxx Normal file
View File

@@ -0,0 +1,27 @@
// A simple program that computes the square root of a number
#include <format>
#include <iostream>
#include <string>
#include <MathFunctions.h>
#include <Unpackaged.h>
int main(int argc, char* argv[])
{
if (argc < 2) {
std::cout << std::format("Usage: {} number\n", argv[0]);
return 1;
}
// convert input to double
double const inputValue = std::stod(argv[1]);
// calculate square root
double const outputValue = mathfunctions::sqrt(inputValue);
std::cout << std::format("The square root of {} is {}\n", inputValue,
outputValue);
double const checkValue = mathfunctions::OpMul(outputValue, outputValue);
std::cout << std::format("The square of {} is {}\n", outputValue,
checkValue);
}

1
Help/guide/tutorial/Complete/TutorialProject/cmake/TutorialConfig.cmake Normal file
View File

@@ -0,0 +1 @@
include(${CMAKE_CURRENT_LIST_DIR}/TutorialTargets.cmake)

3
Help/guide/tutorial/Complete/install/include/Unpackaged/Unpackaged.h Normal file
View File

@@ -0,0 +1,3 @@
#pragma once
#define UNPACKAGED_HEADER_FOUND

50
Help/guide/tutorial/Complete/install/lib/cmake/TransitiveDep/TransitiveDepConfig.cmake Normal file
View File

@@ -0,0 +1,50 @@
# Abridged import written for the Tutorial
if("${CMAKE_MAJOR_VERSION}.${CMAKE_MINOR_VERSION}" LESS 2.8)
message(FATAL_ERROR "CMake >= 3.0.0 required")
endif()
if(CMAKE_VERSION VERSION_LESS "3.0.0")
message(FATAL_ERROR "CMake >= 3.0.0 required")
endif()
cmake_policy(PUSH)
cmake_policy(VERSION 3.0.0...3.30)
# Commands may need to know the format version.
set(CMAKE_IMPORT_FILE_VERSION 1)
# Protect against multiple inclusion, which would fail when already imported targets are added once more.
set(_cmake_targets_defined "")
set(_cmake_targets_not_defined "")
set(_cmake_expected_targets "")
foreach(_cmake_expected_target IN ITEMS TransitiveDep::TransitiveDep)
list(APPEND _cmake_expected_targets "${_cmake_expected_target}")
if(TARGET "${_cmake_expected_target}")
list(APPEND _cmake_targets_defined "${_cmake_expected_target}")
else()
list(APPEND _cmake_targets_not_defined "${_cmake_expected_target}")
endif()
endforeach()
unset(_cmake_expected_target)
if(_cmake_targets_defined STREQUAL _cmake_expected_targets)
unset(_cmake_targets_defined)
unset(_cmake_targets_not_defined)
unset(_cmake_expected_targets)
unset(CMAKE_IMPORT_FILE_VERSION)
cmake_policy(POP)
return()
endif()
if(NOT _cmake_targets_defined STREQUAL "")
string(REPLACE ";" ", " _cmake_targets_defined_text "${_cmake_targets_defined}")
string(REPLACE ";" ", " _cmake_targets_not_defined_text "${_cmake_targets_not_defined}")
message(FATAL_ERROR "Some (but not all) targets in this export set were already defined.\nTargets Defined: ${_cmake_targets_defined_text}\nTargets not yet defined: ${_cmake_targets_not_defined_text}\n")
endif()
unset(_cmake_targets_defined)
unset(_cmake_targets_not_defined)
unset(_cmake_expected_targets)
# Create imported target TransitiveDep::TransitiveDep
add_library(TransitiveDep::TransitiveDep INTERFACE IMPORTED)
# Commands beyond this point should not need to know the version.
set(CMAKE_IMPORT_FILE_VERSION)
cmake_policy(POP)

26
Help/guide/tutorial/Complete/tutorial.cxx
View File

@@ -1,26 +0,0 @@
// A simple program that computes the square root of a number
#include <iostream>
#include <string>
#include "MathFunctions.h"
#include "TutorialConfig.h"
int main(int argc, char* argv[])
{
if (argc < 2) {
// report version
std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
<< Tutorial_VERSION_MINOR << std::endl;
std::cout << "Usage: " << argv[0] << " number" << std::endl;
return 1;
}
// convert input to double
double const inputValue = std::stod(argv[1]);
double const outputValue = mathfunctions::sqrt(inputValue);
std::cout << "The square root of " << inputValue << " is " << outputValue
<< std::endl;
return 0;
}