From 77b515f3eb0494721824e7ee47e32621b947c67f Mon Sep 17 00:00:00 2001 From: Betsy McPhail Date: Wed, 8 Jan 2020 12:36:47 -0500 Subject: Tutorial: Improve "MultiPackage" example Rename to Step 12 and ensure that it follows Step 11 --- Help/guide/tutorial/Complete/CMakeLists.txt | 4 + .../guide/tutorial/Complete/MultiCPackConfig.cmake | 6 ++ Help/guide/tutorial/Complete/tutorial.cxx | 4 +- Help/guide/tutorial/MultiPackage/CMakeLists.txt | 112 ------------------- Help/guide/tutorial/MultiPackage/Config.cmake.in | 4 - Help/guide/tutorial/MultiPackage/License.txt | 2 - .../MultiPackage/MathFunctions/CMakeLists.txt | 59 ---------- .../MultiPackage/MathFunctions/MakeTable.cxx | 25 ----- .../MultiPackage/MathFunctions/MathFunctions.cxx | 19 ---- .../MultiPackage/MathFunctions/MathFunctions.h | 14 --- .../tutorial/MultiPackage/MathFunctions/mysqrt.cxx | 38 ------- .../tutorial/MultiPackage/MathFunctions/mysqrt.h | 6 -- .../tutorial/MultiPackage/MultiCPackConfig.cmake | 7 -- .../tutorial/MultiPackage/TutorialConfig.h.in | 3 - Help/guide/tutorial/MultiPackage/tutorial.cxx | 25 ----- Help/guide/tutorial/Step12/CMakeLists.txt | 120 +++++++++++++++++++++ Help/guide/tutorial/Step12/CTestConfig.cmake | 7 ++ Help/guide/tutorial/Step12/Config.cmake.in | 4 + Help/guide/tutorial/Step12/License.txt | 2 + .../tutorial/Step12/MathFunctions/CMakeLists.txt | 59 ++++++++++ .../tutorial/Step12/MathFunctions/MakeTable.cxx | 25 +++++ .../Step12/MathFunctions/MathFunctions.cxx | 19 ++++ .../tutorial/Step12/MathFunctions/MathFunctions.h | 14 +++ .../guide/tutorial/Step12/MathFunctions/mysqrt.cxx | 37 +++++++ Help/guide/tutorial/Step12/MathFunctions/mysqrt.h | 6 ++ Help/guide/tutorial/Step12/TutorialConfig.h.in | 3 + Help/guide/tutorial/Step12/tutorial.cxx | 26 +++++ Help/guide/tutorial/index.rst | 92 ++++++++++------ Tests/CMakeLists.txt | 5 +- 29 files changed, 396 insertions(+), 351 deletions(-) create mode 100644 Help/guide/tutorial/Complete/MultiCPackConfig.cmake delete mode 100644 Help/guide/tutorial/MultiPackage/CMakeLists.txt delete mode 100644 Help/guide/tutorial/MultiPackage/Config.cmake.in delete mode 100644 Help/guide/tutorial/MultiPackage/License.txt delete mode 100644 Help/guide/tutorial/MultiPackage/MathFunctions/CMakeLists.txt delete mode 100644 Help/guide/tutorial/MultiPackage/MathFunctions/MakeTable.cxx delete mode 100644 Help/guide/tutorial/MultiPackage/MathFunctions/MathFunctions.cxx delete mode 100644 Help/guide/tutorial/MultiPackage/MathFunctions/MathFunctions.h delete mode 100644 Help/guide/tutorial/MultiPackage/MathFunctions/mysqrt.cxx delete mode 100644 Help/guide/tutorial/MultiPackage/MathFunctions/mysqrt.h delete mode 100644 Help/guide/tutorial/MultiPackage/MultiCPackConfig.cmake delete mode 100644 Help/guide/tutorial/MultiPackage/TutorialConfig.h.in delete mode 100644 Help/guide/tutorial/MultiPackage/tutorial.cxx create mode 100644 Help/guide/tutorial/Step12/CMakeLists.txt create mode 100644 Help/guide/tutorial/Step12/CTestConfig.cmake create mode 100644 Help/guide/tutorial/Step12/Config.cmake.in create mode 100644 Help/guide/tutorial/Step12/License.txt create mode 100644 Help/guide/tutorial/Step12/MathFunctions/CMakeLists.txt create mode 100644 Help/guide/tutorial/Step12/MathFunctions/MakeTable.cxx create mode 100644 Help/guide/tutorial/Step12/MathFunctions/MathFunctions.cxx create mode 100644 Help/guide/tutorial/Step12/MathFunctions/MathFunctions.h create mode 100644 Help/guide/tutorial/Step12/MathFunctions/mysqrt.cxx create mode 100644 Help/guide/tutorial/Step12/MathFunctions/mysqrt.h create mode 100644 Help/guide/tutorial/Step12/TutorialConfig.h.in create mode 100644 Help/guide/tutorial/Step12/tutorial.cxx diff --git a/Help/guide/tutorial/Complete/CMakeLists.txt b/Help/guide/tutorial/Complete/CMakeLists.txt index eca79d9..4d8a3ad 100644 --- a/Help/guide/tutorial/Complete/CMakeLists.txt +++ b/Help/guide/tutorial/Complete/CMakeLists.txt @@ -3,6 +3,8 @@ 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) @@ -37,6 +39,8 @@ 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) # add the binary tree to the search path for include files diff --git a/Help/guide/tutorial/Complete/MultiCPackConfig.cmake b/Help/guide/tutorial/Complete/MultiCPackConfig.cmake new file mode 100644 index 0000000..c2583df --- /dev/null +++ b/Help/guide/tutorial/Complete/MultiCPackConfig.cmake @@ -0,0 +1,6 @@ +include("release/CPackConfig.cmake") + +set(CPACK_INSTALL_CMAKE_PROJECTS + "debug;Tutorial;ALL;/" + "release;Tutorial;ALL;/" + ) diff --git a/Help/guide/tutorial/Complete/tutorial.cxx b/Help/guide/tutorial/Complete/tutorial.cxx index 586d183..a4f44d5 100644 --- a/Help/guide/tutorial/Complete/tutorial.cxx +++ b/Help/guide/tutorial/Complete/tutorial.cxx @@ -1,6 +1,5 @@ // A simple program that computes the square root of a number #include -#include #include #include "MathFunctions.h" @@ -9,6 +8,7 @@ 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; @@ -18,8 +18,8 @@ int main(int argc, char* argv[]) // convert input to double const double inputValue = std::stod(argv[1]); - // calculate square root const double outputValue = mathfunctions::sqrt(inputValue); + std::cout << "The square root of " << inputValue << " is " << outputValue << std::endl; return 0; diff --git a/Help/guide/tutorial/MultiPackage/CMakeLists.txt b/Help/guide/tutorial/MultiPackage/CMakeLists.txt deleted file mode 100644 index 01d417a..0000000 --- a/Help/guide/tutorial/MultiPackage/CMakeLists.txt +++ /dev/null @@ -1,112 +0,0 @@ -cmake_minimum_required(VERSION 3.10) - -# set the project name and version -project(Tutorial VERSION 1.0) - -set(CMAKE_CXX_STANDARD 11) -set(CMAKE_CXX_STANDARD_REQUIRED True) - - -# 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) -target_link_libraries(Tutorial PUBLIC MathFunctions) - -# 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_test) - -# 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") - -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}") -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" -) diff --git a/Help/guide/tutorial/MultiPackage/Config.cmake.in b/Help/guide/tutorial/MultiPackage/Config.cmake.in deleted file mode 100644 index 17cbabd..0000000 --- a/Help/guide/tutorial/MultiPackage/Config.cmake.in +++ /dev/null @@ -1,4 +0,0 @@ - -@PACKAGE_INIT@ - -include ( "${CMAKE_CURRENT_LIST_DIR}/MathFunctionsTargets.cmake" ) diff --git a/Help/guide/tutorial/MultiPackage/License.txt b/Help/guide/tutorial/MultiPackage/License.txt deleted file mode 100644 index c62d00b..0000000 --- a/Help/guide/tutorial/MultiPackage/License.txt +++ /dev/null @@ -1,2 +0,0 @@ -This is the open source License.txt file introduced in -CMake/Tutorial/Step7... diff --git a/Help/guide/tutorial/MultiPackage/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/MultiPackage/MathFunctions/CMakeLists.txt deleted file mode 100644 index a2df2a7..0000000 --- a/Help/guide/tutorial/MultiPackage/MathFunctions/CMakeLists.txt +++ /dev/null @@ -1,59 +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 - $ - $ - ) - -# 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") - - # first we add the executable that generates the table - add_executable(MakeTable MakeTable.cxx) - - # 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 - ) - - # 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} - ) - - target_link_libraries(MathFunctions PRIVATE SqrtLibrary) -endif() - -# 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 rules -install(TARGETS MathFunctions - DESTINATION lib - EXPORT MathFunctionsTargets) -install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/MultiPackage/MathFunctions/MakeTable.cxx b/Help/guide/tutorial/MultiPackage/MathFunctions/MakeTable.cxx deleted file mode 100644 index ee58556..0000000 --- a/Help/guide/tutorial/MultiPackage/MathFunctions/MakeTable.cxx +++ /dev/null @@ -1,25 +0,0 @@ -// A simple program that builds a sqrt table -#include -#include -#include - -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); - const bool fileOpen = fout.is_open(); - if (fileOpen) { - fout << "double sqrtTable[] = {" << std::endl; - for (int i = 0; i < 10; ++i) { - fout << sqrt(static_cast(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 -} diff --git a/Help/guide/tutorial/MultiPackage/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/MultiPackage/MathFunctions/MathFunctions.cxx deleted file mode 100644 index 0145300..0000000 --- a/Help/guide/tutorial/MultiPackage/MathFunctions/MathFunctions.cxx +++ /dev/null @@ -1,19 +0,0 @@ - -#include "MathFunctions.h" - -#include - -#ifdef USE_MYMATH -# include "mysqrt.h" -#endif - -namespace mathfunctions { -double sqrt(double x) -{ -#ifdef USE_MYMATH - return detail::mysqrt(x); -#else - return std::sqrt(x); -#endif -} -} diff --git a/Help/guide/tutorial/MultiPackage/MathFunctions/MathFunctions.h b/Help/guide/tutorial/MultiPackage/MathFunctions/MathFunctions.h deleted file mode 100644 index 3fb547b..0000000 --- a/Help/guide/tutorial/MultiPackage/MathFunctions/MathFunctions.h +++ /dev/null @@ -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); -} diff --git a/Help/guide/tutorial/MultiPackage/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/MultiPackage/MathFunctions/mysqrt.cxx deleted file mode 100644 index 5e622be..0000000 --- a/Help/guide/tutorial/MultiPackage/MathFunctions/mysqrt.cxx +++ /dev/null @@ -1,38 +0,0 @@ -#include - -#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) { - result = sqrtTable[static_cast(x)]; - } - - // if we have both log and exp then use them - - // 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; -} -} -} diff --git a/Help/guide/tutorial/MultiPackage/MathFunctions/mysqrt.h b/Help/guide/tutorial/MultiPackage/MathFunctions/mysqrt.h deleted file mode 100644 index e1c42ef..0000000 --- a/Help/guide/tutorial/MultiPackage/MathFunctions/mysqrt.h +++ /dev/null @@ -1,6 +0,0 @@ - -namespace mathfunctions { -namespace detail { -double mysqrt(double x); -} -} diff --git a/Help/guide/tutorial/MultiPackage/MultiCPackConfig.cmake b/Help/guide/tutorial/MultiPackage/MultiCPackConfig.cmake deleted file mode 100644 index 403b633..0000000 --- a/Help/guide/tutorial/MultiPackage/MultiCPackConfig.cmake +++ /dev/null @@ -1,7 +0,0 @@ - -include("release/CPackConfig.cmake") - -set(CPACK_INSTALL_CMAKE_PROJECTS - "debug;Tutorial;ALL;/" - "release;Tutorial;ALL;/" - ) diff --git a/Help/guide/tutorial/MultiPackage/TutorialConfig.h.in b/Help/guide/tutorial/MultiPackage/TutorialConfig.h.in deleted file mode 100644 index 8cd2fc9..0000000 --- a/Help/guide/tutorial/MultiPackage/TutorialConfig.h.in +++ /dev/null @@ -1,3 +0,0 @@ -// the configured version number -#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ -#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ diff --git a/Help/guide/tutorial/MultiPackage/tutorial.cxx b/Help/guide/tutorial/MultiPackage/tutorial.cxx deleted file mode 100644 index f97805b..0000000 --- a/Help/guide/tutorial/MultiPackage/tutorial.cxx +++ /dev/null @@ -1,25 +0,0 @@ -// A simple program that computes the square root of a number -#include -#include - -#include "MathFunctions.h" -#include "TutorialConfig.h" - -int main(int argc, char* argv[]) -{ - if (argc < 2) { - 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 inputValue = std::stod(argv[1]); - - const double outputValue = mathfunctions::sqrt(inputValue); - - std::cout << "The square root of " << inputValue << " is " << outputValue - << std::endl; - return 0; -} diff --git a/Help/guide/tutorial/Step12/CMakeLists.txt b/Help/guide/tutorial/Step12/CMakeLists.txt new file mode 100644 index 0000000..eca79d9 --- /dev/null +++ b/Help/guide/tutorial/Step12/CMakeLists.txt @@ -0,0 +1,120 @@ +cmake_minimum_required(VERSION 3.15) + +# set the project name and version +project(Tutorial VERSION 1.0) + +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 "$") +set(msvc_cxx "$") +target_compile_options(tutorial_compiler_flags INTERFACE + "$<${gcc_like_cxx}:$>" + "$<${msvc_cxx}:$>" +) + +# 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) +target_link_libraries(Tutorial PUBLIC MathFunctions) + +# 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_test) + +# 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") + +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}") +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" +) diff --git a/Help/guide/tutorial/Step12/CTestConfig.cmake b/Help/guide/tutorial/Step12/CTestConfig.cmake new file mode 100644 index 0000000..73efdb1 --- /dev/null +++ b/Help/guide/tutorial/Step12/CTestConfig.cmake @@ -0,0 +1,7 @@ +set(CTEST_PROJECT_NAME "CMakeTutorial") +set(CTEST_NIGHTLY_START_TIME "00:00:00 EST") + +set(CTEST_DROP_METHOD "http") +set(CTEST_DROP_SITE "my.cdash.org") +set(CTEST_DROP_LOCATION "/submit.php?project=CMakeTutorial") +set(CTEST_DROP_SITE_CDASH TRUE) diff --git a/Help/guide/tutorial/Step12/Config.cmake.in b/Help/guide/tutorial/Step12/Config.cmake.in new file mode 100644 index 0000000..17cbabd --- /dev/null +++ b/Help/guide/tutorial/Step12/Config.cmake.in @@ -0,0 +1,4 @@ + +@PACKAGE_INIT@ + +include ( "${CMAKE_CURRENT_LIST_DIR}/MathFunctionsTargets.cmake" ) diff --git a/Help/guide/tutorial/Step12/License.txt b/Help/guide/tutorial/Step12/License.txt new file mode 100644 index 0000000..c62d00b --- /dev/null +++ b/Help/guide/tutorial/Step12/License.txt @@ -0,0 +1,2 @@ +This is the open source License.txt file introduced in +CMake/Tutorial/Step7... diff --git a/Help/guide/tutorial/Step12/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step12/MathFunctions/CMakeLists.txt new file mode 100644 index 0000000..f39f537 --- /dev/null +++ b/Help/guide/tutorial/Step12/MathFunctions/CMakeLists.txt @@ -0,0 +1,59 @@ +# 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 + $ + $ + ) + +# 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") + + # first we add the executable that generates the table + add_executable(MakeTable MakeTable.cxx) + target_link_libraries(MakeTable 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 + ) + + # 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} + ) + + target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags) + target_link_libraries(MathFunctions PRIVATE SqrtLibrary) +endif() + +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") + +# install rules +install(TARGETS MathFunctions tutorial_compiler_flags + DESTINATION lib + EXPORT MathFunctionsTargets) +install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Step12/MathFunctions/MakeTable.cxx b/Help/guide/tutorial/Step12/MathFunctions/MakeTable.cxx new file mode 100644 index 0000000..ee58556 --- /dev/null +++ b/Help/guide/tutorial/Step12/MathFunctions/MakeTable.cxx @@ -0,0 +1,25 @@ +// A simple program that builds a sqrt table +#include +#include +#include + +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); + const bool fileOpen = fout.is_open(); + if (fileOpen) { + fout << "double sqrtTable[] = {" << std::endl; + for (int i = 0; i < 10; ++i) { + fout << sqrt(static_cast(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 +} diff --git a/Help/guide/tutorial/Step12/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step12/MathFunctions/MathFunctions.cxx new file mode 100644 index 0000000..0145300 --- /dev/null +++ b/Help/guide/tutorial/Step12/MathFunctions/MathFunctions.cxx @@ -0,0 +1,19 @@ + +#include "MathFunctions.h" + +#include + +#ifdef USE_MYMATH +# include "mysqrt.h" +#endif + +namespace mathfunctions { +double sqrt(double x) +{ +#ifdef USE_MYMATH + return detail::mysqrt(x); +#else + return std::sqrt(x); +#endif +} +} diff --git a/Help/guide/tutorial/Step12/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step12/MathFunctions/MathFunctions.h new file mode 100644 index 0000000..3fb547b --- /dev/null +++ b/Help/guide/tutorial/Step12/MathFunctions/MathFunctions.h @@ -0,0 +1,14 @@ + +#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); +} diff --git a/Help/guide/tutorial/Step12/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step12/MathFunctions/mysqrt.cxx new file mode 100644 index 0000000..8153f18 --- /dev/null +++ b/Help/guide/tutorial/Step12/MathFunctions/mysqrt.cxx @@ -0,0 +1,37 @@ +#include + +#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(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; +} +} +} diff --git a/Help/guide/tutorial/Step12/MathFunctions/mysqrt.h b/Help/guide/tutorial/Step12/MathFunctions/mysqrt.h new file mode 100644 index 0000000..e1c42ef --- /dev/null +++ b/Help/guide/tutorial/Step12/MathFunctions/mysqrt.h @@ -0,0 +1,6 @@ + +namespace mathfunctions { +namespace detail { +double mysqrt(double x); +} +} diff --git a/Help/guide/tutorial/Step12/TutorialConfig.h.in b/Help/guide/tutorial/Step12/TutorialConfig.h.in new file mode 100644 index 0000000..7e4d7fa --- /dev/null +++ b/Help/guide/tutorial/Step12/TutorialConfig.h.in @@ -0,0 +1,3 @@ +// the configured options and settings for Tutorial +#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ +#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ diff --git a/Help/guide/tutorial/Step12/tutorial.cxx b/Help/guide/tutorial/Step12/tutorial.cxx new file mode 100644 index 0000000..a4f44d5 --- /dev/null +++ b/Help/guide/tutorial/Step12/tutorial.cxx @@ -0,0 +1,26 @@ +// A simple program that computes the square root of a number +#include +#include + +#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 + const double inputValue = std::stod(argv[1]); + + const double outputValue = mathfunctions::sqrt(inputValue); + + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; + return 0; +} diff --git a/Help/guide/tutorial/index.rst b/Help/guide/tutorial/index.rst index bfe6385..5da7543 100644 --- a/Help/guide/tutorial/index.rst +++ b/Help/guide/tutorial/index.rst @@ -830,7 +830,7 @@ different ``INTERFACE`` locations when being used from within the build directory and from an install / package. This means converting the :command:`target_include_directories` call for MathFunctions to look like: -.. literalinclude:: Complete/MathFunctions/CMakeLists.txt +.. literalinclude:: Step12/MathFunctions/CMakeLists.txt :language: cmake :start-after: # to find MathFunctions.h, while we don't. :end-before: # should we use our own math functions @@ -844,12 +844,12 @@ that the CMake :command:`find_package` command can find our project. So let's go ahead and add a new file to the top-level of the project called ``Config.cmake.in`` with the following contents: -.. literalinclude:: Complete/Config.cmake.in +.. literalinclude:: Step12/Config.cmake.in Then, to properly configure and install that file, add the following to the bottom of the top-level ``CMakeLists.txt``: -.. literalinclude:: Complete/CMakeLists.txt +.. literalinclude:: Step12/CMakeLists.txt :language: cmake :start-after: # install the configuration targets :end-before: # generate the export @@ -859,7 +859,7 @@ project that can be used after the project has been installed or packaged. If we want our project to also be used from a build directory we only have to add the following to the bottom of the top level ``CMakeLists.txt``: -.. literalinclude:: Complete/CMakeLists.txt +.. literalinclude:: Step12/CMakeLists.txt :language: cmake :start-after: # needs to be after the install(TARGETS ) command @@ -867,55 +867,81 @@ With this export call we now generate a ``Targets.cmake``, allowing the configured ``MathFunctionsConfig.cmake`` in the build directory to be used by other projects, without needing it to be installed. -Import a CMake Project (Consumer) -================================= +Packaging Debug and Release (Step 12) +===================================== -This example shows how a project can find other CMake packages that -generate ``Config.cmake`` files. +**Note:** This example is valid for single-configuration generators and will +not work for multi-configuration generators (e.g. Visual Studio). -It also shows how to state a project's external dependencies when generating -a ``Config.cmake``. +By default, CMake's model is that a build directory only contains a single +configuration, be it Debug, Release, MinSizeRel, or RelWithDebInfo. It is +possible, however, to setup CPack to bundle multiple build directories and +construct a package that contains multiple configurations of the same project. -Packaging Debug and Release (MultiPackage) -========================================== +First, we want to ensure that the debug and release builds use different names +for the executables and libraries that will be installed. Let's use `d` as the +postfix for the debug executable and libraries. -By default CMake's model is that a build directory only contains a single -configuration, be it Debug, Release, MinSizeRel, or RelWithDebInfo. +Set :variable:`CMAKE_DEBUG_POSTFIX` near the beginning of the top-level +``CMakeLists.txt`` file: -But it is possible to setup CPack to bundle multiple build directories at the -same time to build a package that contains multiple configurations of the -same project. +.. literalinclude:: Complete/CMakeLists.txt + :language: cmake + :start-after: project(Tutorial VERSION 1.0) + :end-before: target_compile_features(tutorial_compiler_flags -First we need to construct a directory called ``multi_config``, which -will contain all the builds that we want to package together. +And the :prop_tgt:`DEBUG_POSTFIX` property on the tutorial executable: -Second create a ``debug`` and ``release`` directory underneath -``multi_config``. At the end you should have a layout that looks like: +.. literalinclude:: Complete/CMakeLists.txt + :language: cmake + :start-after: # add the executable + :end-before: # add the binary tree to the search path for include files + +Let's also add version numbering to the MathFunctions library. In +``MathFunctions/CMakeLists.txt``, set the :prop_tgt:`VERSION` and +:prop_tgt:`SOVERSION` properties: + +.. literalinclude:: Complete/MathFunctions/CMakeLists.txt + :language: cmake + :start-after: # setup the version numbering + :end-before: # install rules + +From the ``Step12`` directory, create ``debug`` and ``release`` +subbdirectories. The layout will look like: .. code-block:: none - ─ multi_config - ├── debug - └── release + - Step12 + └── debug + └── release -Now we need to setup debug and release builds, which would roughly entail -the following: +Now we need to setup debug and release builds. We can use +:variable:`CMAKE_BUILD_TYPE` to set the configuration type: .. code-block:: console cd debug - cmake -DCMAKE_BUILD_TYPE=Debug ../../MultiPackage/ + cmake -DCMAKE_BUILD_TYPE=Debug .. cmake --build . cd ../release - cmake -DCMAKE_BUILD_TYPE=Release ../../MultiPackage/ + cmake -DCMAKE_BUILD_TYPE=Release .. cmake --build . - cd .. +Now that both the debug and release builds are complete, we can use a custom +configuration file to package both builds into a single release. In the +``Step12`` directory, create a file called ``MultiCPackConfig.cmake``. In this +file, first include the default configuration file that was created by the +:manual:`cmake ` executable. + +Next, use the ``CPACK_INSTALL_CMAKE_PROJECTS`` variable to specify which +projects to install. In this case, we want to install both debug and release. + +.. literalinclude:: Complete/MultiCPackConfig.cmake + :language: cmake -Now that both the debug and release builds are complete, we can use -a custom ``MultiCPackConfig.cmake`` file to package both builds into a single -release. +From the ``Step12`` directory, run :manual:`cpack ` specifying our +custom configuration file with the ``config`` option: .. code-block:: console - cpack --config ../../MultiPackage/MultiCPackConfig.cmake + cpack --config MultiCPackConfig.cmake diff --git a/Tests/CMakeLists.txt b/Tests/CMakeLists.txt index 90eed4f..2456a26 100644 --- a/Tests/CMakeLists.txt +++ b/Tests/CMakeLists.txt @@ -1595,6 +1595,7 @@ ${CMake_SOURCE_DIR}/Utilities/Release/push.bash --dir dev -- '${CMake_BUILD_NIGH set(tutorial_build_options -DUSE_MYMATH:BOOL=OFF) endif() add_test(${tutorial_test_name} ${CMAKE_CTEST_COMMAND} + -C "Release" --build-and-test "${CMake_SOURCE_DIR}/Help/guide/tutorial/${step_name}" ${tutorial_build_dir}_Build @@ -1606,11 +1607,11 @@ ${CMake_SOURCE_DIR}/Utilities/Release/push.bash --dir dev -- '${CMake_BUILD_NIGH endfunction() if(NOT CMake_TEST_EXTERNAL_CMAKE) - foreach(STP RANGE 2 11) + foreach(STP RANGE 2 12) add_tutorial_test(Step${STP} TRUE) endforeach() add_tutorial_test(Complete TRUE) - foreach(STP RANGE 3 11) + foreach(STP RANGE 3 12) add_tutorial_test(Step${STP} FALSE) endforeach() add_tutorial_test(Complete FALSE) -- cgit v0.12