diff options
Diffstat (limited to 'Help')
84 files changed, 672 insertions, 532 deletions
diff --git a/Help/command/ctest_coverage.rst b/Help/command/ctest_coverage.rst index 8d27b9c..d50f634 100644 --- a/Help/command/ctest_coverage.rst +++ b/Help/command/ctest_coverage.rst @@ -8,7 +8,7 @@ Perform the :ref:`CTest Coverage Step` as a :ref:`Dashboard Client`. ctest_coverage([BUILD <build-dir>] [APPEND] [LABELS <label>...] [RETURN_VALUE <result-var>] - [CAPTURE_CMAKE_ERROR <result-var] + [CAPTURE_CMAKE_ERROR <result-var>] [QUIET] ) diff --git a/Help/command/ctest_start.rst b/Help/command/ctest_start.rst index 6db9a48..f0704ac 100644 --- a/Help/command/ctest_start.rst +++ b/Help/command/ctest_start.rst @@ -5,9 +5,9 @@ Starts the testing for a given model :: - ctest_start(<model> [<source> [<binary>]] [TRACK <track>] [QUIET]) + ctest_start(<model> [<source> [<binary>]] [GROUP <group>] [QUIET]) - ctest_start([<model> [<source> [<binary>]]] [TRACK <track>] APPEND [QUIET]) + ctest_start([<model> [<source> [<binary>]]] [GROUP <group>] APPEND [QUIET]) Starts the testing for a given model. The command should be called after the binary directory is initialized. @@ -26,20 +26,21 @@ The parameters are as follows: Set the binary directory. If not specified, the value of :variable:`CTEST_BINARY_DIRECTORY` is used instead. -``TRACK <track>`` - If ``TRACK`` is used, the submissions will go to the specified track on the - CDash server. If no ``TRACK`` is specified, the name of the model is used by - default. +``GROUP <group>`` + If ``GROUP`` is used, the submissions will go to the specified group on the + CDash server. If no ``GROUP`` is specified, the name of the model is used by + default. This replaces the deprecated option ``TRACK``. Despite the name + change its behavior is unchanged. ``APPEND`` If ``APPEND`` is used, the existing ``TAG`` is used rather than creating a new one based on the current time stamp. If you use ``APPEND``, you can omit the - ``<model>`` and ``TRACK <track>`` parameters, because they will be read from + ``<model>`` and ``GROUP <group>`` parameters, because they will be read from the generated ``TAG`` file. For example: .. code-block:: cmake - ctest_start(Experimental TRACK TrackExperimental) + ctest_start(Experimental GROUP GroupExperimental) Later, in another ``ctest -S`` script: @@ -48,11 +49,11 @@ The parameters are as follows: ctest_start(APPEND) When the second script runs ``ctest_start(APPEND)``, it will read the - ``Experimental`` model and ``TrackExperimental`` track from the ``TAG`` file + ``Experimental`` model and ``GroupExperimental`` group from the ``TAG`` file generated by the first ``ctest_start()`` command. Please note that if you - call ``ctest_start(APPEND)`` and specify a different model or track than + call ``ctest_start(APPEND)`` and specify a different model or group than in the first ``ctest_start()`` command, a warning will be issued, and the - new model and track will be used. + new model and group will be used. ``QUIET`` If ``QUIET`` is used, CTest will suppress any non-error messages that it @@ -65,11 +66,11 @@ equivalent: .. code-block:: cmake - ctest_start(Experimental path/to/source path/to/binary TRACK SomeTrack QUIET APPEND) + ctest_start(Experimental path/to/source path/to/binary GROUP SomeGroup QUIET APPEND) - ctest_start(TRACK SomeTrack Experimental QUIET path/to/source APPEND path/to/binary) + ctest_start(GROUP SomeGroup Experimental QUIET path/to/source APPEND path/to/binary) - ctest_start(APPEND QUIET Experimental path/to/source TRACK SomeTrack path/to/binary) + ctest_start(APPEND QUIET Experimental path/to/source GROUP SomeGroup path/to/binary) However, for the sake of readability, it is recommended that you order your parameters in the order listed at the top of this page. diff --git a/Help/command/target_precompile_headers.rst b/Help/command/target_precompile_headers.rst new file mode 100644 index 0000000..3e28265 --- /dev/null +++ b/Help/command/target_precompile_headers.rst @@ -0,0 +1,56 @@ +target_precompile_headers +------------------------- + +Add a list of header files to precompile. + +.. code-block:: cmake + + target_precompile_headers(<target> + <INTERFACE|PUBLIC|PRIVATE> [header1...] + [<INTERFACE|PUBLIC|PRIVATE> [header2...] ...]) + +Adds header files to :prop_tgt:`PRECOMPILE_HEADERS` or +:prop_tgt:`INTERFACE_PRECOMPILE_HEADERS` target properties. + +Precompiling header files can speed up compilation by creating a partially +processed version of some header files, and then using that version during +compilations rather than repeatedly parsing the original headers. + +The named ``<target>`` must have been created by a command such as +:command:`add_executable` or :command:`add_library` and must not be an +:ref:`ALIAS target <Alias Targets>`. + +The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to +specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC`` +items will populate the :prop_tgt:`PRECOMPILE_HEADERS` property of +``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the +:prop_tgt:`INTERFACE_PRECOMPILE_HEADERS` property of ``<target>``. +(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items.) +Repeated calls for the same ``<target>`` append items in the order called. + +Arguments to ``target_precompile_headers`` may use "generator expressions" +with the syntax ``$<...>``. +See the :manual:`cmake-generator-expressions(7)` manual for available +expressions. See the :manual:`cmake-compile-features(7)` manual for +information on compile features and a list of supported compilers. + +.. code-block:: cmake + + target_precompile_headers(<target> + PUBLIC + "project_header.h" + PRIVATE + <unordered_map> + ) + +Header files will be double quoted if they are not specified with double +quotes or angle brackets. + +See Also +^^^^^^^^ + +For disabling precompile headers for specific targets there is the +property :prop_tgt:`DISABLE_PRECOMPILE_HEADERS`. + +For skipping certain source files there is the source file property +:prop_sf:`SKIP_PRECOMPILE_HEADERS`. diff --git a/Help/dev/source.rst b/Help/dev/source.rst index 47baff4..0f7488b 100644 --- a/Help/dev/source.rst +++ b/Help/dev/source.rst @@ -74,6 +74,8 @@ The CMake source tree is organized as follows. * ``Utilities/Release/``: Scripts used to package CMake itself for distribution on ``cmake.org``. + See `Utilities/Release/README.rst`_. .. _`CMake Documentation Guide`: documentation.rst .. _`Tests/README.rst`: ../../Tests/README.rst +.. _`Utilities/Release/README.rst`: ../../Utilities/Release/README.rst diff --git a/Help/guide/tutorial/Complete/CMakeLists.txt b/Help/guide/tutorial/Complete/CMakeLists.txt index 4541392..eca79d9 100644 --- a/Help/guide/tutorial/Complete/CMakeLists.txt +++ b/Help/guide/tutorial/Complete/CMakeLists.txt @@ -1,5 +1,7 @@ cmake_minimum_required(VERSION 3.15) -project(Tutorial) + +# 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) @@ -13,10 +15,6 @@ target_compile_options(tutorial_compiler_flags INTERFACE "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>" ) -# set the version number -set(Tutorial_VERSION_MAJOR 1) -set(Tutorial_VERSION_MINOR 0) - # 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}") @@ -32,17 +30,14 @@ elseif(UNIX) endif() # configure a header file to pass the version number only -configure_file( - "${PROJECT_SOURCE_DIR}/TutorialConfig.h.in" - "${PROJECT_BINARY_DIR}/TutorialConfig.h" - ) +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 MathFunctions) +target_link_libraries(Tutorial PUBLIC MathFunctions) # add the binary tree to the search path for include files # so that we will find TutorialConfig.h diff --git a/Help/guide/tutorial/Complete/CTestConfig.cmake b/Help/guide/tutorial/Complete/CTestConfig.cmake new file mode 100644 index 0000000..73efdb1 --- /dev/null +++ b/Help/guide/tutorial/Complete/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/Complete/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt index c12955d..dfa84c9 100644 --- a/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt @@ -13,11 +13,7 @@ target_include_directories(MathFunctions option(USE_MYMATH "Use tutorial provided math implementation" ON) if(USE_MYMATH) - # does this system provide the log and exp functions? - include(CheckSymbolExists) - set(CMAKE_REQUIRED_LIBRARIES "m") - check_symbol_exists(log "math.h" HAVE_LOG) - check_symbol_exists(exp "math.h" HAVE_EXP) + target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") # first we add the executable that generates the table add_executable(MakeTable MakeTable.cxx) @@ -41,18 +37,12 @@ if(USE_MYMATH) ${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_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") - if(HAVE_LOG AND HAVE_EXP) - target_compile_definitions(SqrtLibrary - PRIVATE "HAVE_LOG" "HAVE_EXP") - endif() target_link_libraries(MathFunctions PRIVATE SqrtLibrary) endif() diff --git a/Help/guide/tutorial/Complete/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Complete/MathFunctions/mysqrt.cxx index 96d9421..ff37312 100644 --- a/Help/guide/tutorial/Complete/MathFunctions/mysqrt.cxx +++ b/Help/guide/tutorial/Complete/MathFunctions/mysqrt.cxx @@ -4,8 +4,6 @@ // include the generated table #include "Table.h" -#include <cmath> - namespace mathfunctions { namespace detail { // a hack square root calculation using simple operations @@ -15,20 +13,13 @@ double mysqrt(double x) return 0; } - // if we have both log and exp then use them -#if defined(HAVE_LOG) && defined(HAVE_EXP) - double result = exp(log(x) * 0.5); - std::cout << "Computing sqrt of " << x << " to be " << result << " using log" - << std::endl; -#else // 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)]; } - // if we have both log and exp then use them - // do ten iterations for (int i = 0; i < 10; ++i) { if (result <= 0) { @@ -38,7 +29,7 @@ double mysqrt(double x) result = result + 0.5 * delta / result; std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; } -#endif + return result; } } diff --git a/Help/guide/tutorial/Complete/TutorialConfig.h.in b/Help/guide/tutorial/Complete/TutorialConfig.h.in index 8cd2fc9..7e4d7fa 100644 --- a/Help/guide/tutorial/Complete/TutorialConfig.h.in +++ b/Help/guide/tutorial/Complete/TutorialConfig.h.in @@ -1,3 +1,3 @@ -// the configured version number +// 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/Complete/tutorial.cxx b/Help/guide/tutorial/Complete/tutorial.cxx index 4451cbd..586d183 100644 --- a/Help/guide/tutorial/Complete/tutorial.cxx +++ b/Help/guide/tutorial/Complete/tutorial.cxx @@ -15,10 +15,11 @@ int main(int argc, char* argv[]) return 1; } - double inputValue = std::stod(argv[1]); + // 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/Consumer/CMakeLists.txt b/Help/guide/tutorial/Consumer/CMakeLists.txt index 4033b4d..a0e4598 100644 --- a/Help/guide/tutorial/Consumer/CMakeLists.txt +++ b/Help/guide/tutorial/Consumer/CMakeLists.txt @@ -1,4 +1,4 @@ -cmake_minimum_required(VERSION 3.3) +cmake_minimum_required(VERSION 3.10) if(NOT DEFINED CMAKE_CXX_STANDARD) set(CMAKE_CXX_STANDARD 11) diff --git a/Help/guide/tutorial/MultiPackage/CMakeLists.txt b/Help/guide/tutorial/MultiPackage/CMakeLists.txt index bea611c..01d417a 100644 --- a/Help/guide/tutorial/MultiPackage/CMakeLists.txt +++ b/Help/guide/tutorial/MultiPackage/CMakeLists.txt @@ -1,12 +1,11 @@ -cmake_minimum_required(VERSION 3.3) -project(Tutorial) +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) -# set the version number -set(Tutorial_VERSION_MAJOR 1) -set(Tutorial_VERSION_MINOR 0) # 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 @@ -23,17 +22,14 @@ elseif(UNIX) endif() # configure a header file to pass the version number only -configure_file( - "${PROJECT_SOURCE_DIR}/TutorialConfig.h.in" - "${PROJECT_BINARY_DIR}/TutorialConfig.h" - ) +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 MathFunctions) +target_link_libraries(Tutorial PUBLIC MathFunctions) # add the binary tree to the search path for include files # so that we will find TutorialConfig.h diff --git a/Help/guide/tutorial/MultiPackage/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/MultiPackage/MathFunctions/CMakeLists.txt index 63c0f5f..a2df2a7 100644 --- a/Help/guide/tutorial/MultiPackage/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/MultiPackage/MathFunctions/CMakeLists.txt @@ -13,11 +13,7 @@ target_include_directories(MathFunctions option(USE_MYMATH "Use tutorial provided math implementation" ON) if(USE_MYMATH) - # does this system provide the log and exp functions? - include(CheckSymbolExists) - set(CMAKE_REQUIRED_LIBRARIES "m") - check_symbol_exists(log "math.h" HAVE_LOG) - check_symbol_exists(exp "math.h" HAVE_EXP) + target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") # first we add the executable that generates the table add_executable(MakeTable MakeTable.cxx) @@ -40,19 +36,14 @@ if(USE_MYMATH) ${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_compile_definitions(SqrtLibrary PRIVATE - "$<$<BOOL:${HAVE_LOG}>:HAVE_LOG>" - "$<$<BOOL:${HAVE_EXP}>:HAVE_EXP>" - ) target_link_libraries(MathFunctions PRIVATE SqrtLibrary) endif() -target_compile_definitions(MathFunctions PRIVATE "$<$<BOOL:${USE_MYMATH}>:USE_MYMATH>") - # define the symbol stating we are using the declspec(dllexport) when # building on windows target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH") diff --git a/Help/guide/tutorial/MultiPackage/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/MultiPackage/MathFunctions/mysqrt.cxx index 96d9421..4c212b3 100644 --- a/Help/guide/tutorial/MultiPackage/MathFunctions/mysqrt.cxx +++ b/Help/guide/tutorial/MultiPackage/MathFunctions/mysqrt.cxx @@ -4,8 +4,6 @@ // include the generated table #include "Table.h" -#include <cmath> - namespace mathfunctions { namespace detail { // a hack square root calculation using simple operations @@ -15,12 +13,6 @@ double mysqrt(double x) return 0; } - // if we have both log and exp then use them -#if defined(HAVE_LOG) && defined(HAVE_EXP) - double result = exp(log(x) * 0.5); - std::cout << "Computing sqrt of " << x << " to be " << result << " using log" - << std::endl; -#else // use the table to help find an initial value double result = x; if (x >= 1 && x < 10) { @@ -38,7 +30,7 @@ double mysqrt(double x) result = result + 0.5 * delta / result; std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; } -#endif + return result; } } diff --git a/Help/guide/tutorial/MultiPackage/tutorial.cxx b/Help/guide/tutorial/MultiPackage/tutorial.cxx index 4451cbd..f97805b 100644 --- a/Help/guide/tutorial/MultiPackage/tutorial.cxx +++ b/Help/guide/tutorial/MultiPackage/tutorial.cxx @@ -1,6 +1,5 @@ // A simple program that computes the square root of a number #include <iostream> -#include <sstream> #include <string> #include "MathFunctions.h" @@ -15,6 +14,7 @@ int main(int argc, char* argv[]) return 1; } + // convert input to double double inputValue = std::stod(argv[1]); const double outputValue = mathfunctions::sqrt(inputValue); diff --git a/Help/guide/tutorial/Step1/CMakeLists.txt b/Help/guide/tutorial/Step1/CMakeLists.txt deleted file mode 100644 index 141f0c2..0000000 --- a/Help/guide/tutorial/Step1/CMakeLists.txt +++ /dev/null @@ -1,3 +0,0 @@ -project(Tutorial) - -add_executable(Tutorial tutorial.cxx) diff --git a/Help/guide/tutorial/Step1/TutorialConfig.h.in b/Help/guide/tutorial/Step1/TutorialConfig.h.in deleted file mode 100644 index 7e4d7fa..0000000 --- a/Help/guide/tutorial/Step1/TutorialConfig.h.in +++ /dev/null @@ -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@ diff --git a/Help/guide/tutorial/Step1/tutorial.cxx b/Help/guide/tutorial/Step1/tutorial.cxx index f8dd0c6..08323bf 100644 --- a/Help/guide/tutorial/Step1/tutorial.cxx +++ b/Help/guide/tutorial/Step1/tutorial.cxx @@ -11,9 +11,11 @@ int main(int argc, char* argv[]) return 1; } - double inputValue = atof(argv[1]); + // convert input to double + const double inputValue = atof(argv[1]); - double outputValue = sqrt(inputValue); + // calculate square root + const double outputValue = sqrt(inputValue); std::cout << "The square root of " << inputValue << " is " << outputValue << std::endl; return 0; diff --git a/Help/guide/tutorial/Step10/CMakeLists.txt b/Help/guide/tutorial/Step10/CMakeLists.txt index 25bc0c1..34ae70c 100644 --- a/Help/guide/tutorial/Step10/CMakeLists.txt +++ b/Help/guide/tutorial/Step10/CMakeLists.txt @@ -1,13 +1,12 @@ -cmake_minimum_required(VERSION 3.3) -project(Tutorial) +cmake_minimum_required(VERSION 3.10) +# set the project name and version +project(Tutorial VERSION 1.0) + +# specify the C++ standard set(CMAKE_CXX_STANDARD 11) set(CMAKE_CXX_STANDARD_REQUIRED True) -# Set the version number -set(Tutorial_VERSION_MAJOR 1) -set(Tutorial_VERSION_MINOR 0) - # 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}") @@ -17,17 +16,14 @@ set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") option(BUILD_SHARED_LIBS "Build using shared libraries" ON) # configure a header file to pass the version number only -configure_file( - "${PROJECT_SOURCE_DIR}/TutorialConfig.h.in" - "${PROJECT_BINARY_DIR}/TutorialConfig.h" - ) +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 MathFunctions) +target_link_libraries(Tutorial PUBLIC MathFunctions) # add the binary tree to the search path for include files # so that we will find TutorialConfig.h @@ -42,7 +38,7 @@ install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" ) # enable testing -enable_testing() +include(CTest) # does the application run add_test(NAME Runs COMMAND Tutorial 25) diff --git a/Help/guide/tutorial/Step10/CTestConfig.cmake b/Help/guide/tutorial/Step10/CTestConfig.cmake new file mode 100644 index 0000000..73efdb1 --- /dev/null +++ b/Help/guide/tutorial/Step10/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/Step10/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step10/MathFunctions/CMakeLists.txt index aafd090..e0c0621 100644 --- a/Help/guide/tutorial/Step10/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step10/MathFunctions/CMakeLists.txt @@ -11,11 +11,7 @@ target_include_directories(MathFunctions option(USE_MYMATH "Use tutorial provided math implementation" ON) if(USE_MYMATH) - # does this system provide the log and exp functions? - include(CheckSymbolExists) - set(CMAKE_REQUIRED_LIBRARIES "m") - check_symbol_exists(log "math.h" HAVE_LOG) - check_symbol_exists(exp "math.h" HAVE_EXP) + target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") # first we add the executable that generates the table add_executable(MakeTable MakeTable.cxx) @@ -43,12 +39,6 @@ if(USE_MYMATH) POSITION_INDEPENDENT_CODE ${BUILD_SHARED_LIBS} ) - target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") - if(HAVE_LOG AND HAVE_EXP) - target_compile_definitions(SqrtLibrary - PRIVATE "HAVE_LOG" "HAVE_EXP") - endif() - target_link_libraries(MathFunctions PRIVATE SqrtLibrary) endif() diff --git a/Help/guide/tutorial/Step10/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step10/MathFunctions/mysqrt.cxx index 96d9421..ff37312 100644 --- a/Help/guide/tutorial/Step10/MathFunctions/mysqrt.cxx +++ b/Help/guide/tutorial/Step10/MathFunctions/mysqrt.cxx @@ -4,8 +4,6 @@ // include the generated table #include "Table.h" -#include <cmath> - namespace mathfunctions { namespace detail { // a hack square root calculation using simple operations @@ -15,20 +13,13 @@ double mysqrt(double x) return 0; } - // if we have both log and exp then use them -#if defined(HAVE_LOG) && defined(HAVE_EXP) - double result = exp(log(x) * 0.5); - std::cout << "Computing sqrt of " << x << " to be " << result << " using log" - << std::endl; -#else // 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)]; } - // if we have both log and exp then use them - // do ten iterations for (int i = 0; i < 10; ++i) { if (result <= 0) { @@ -38,7 +29,7 @@ double mysqrt(double x) result = result + 0.5 * delta / result; std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; } -#endif + return result; } } diff --git a/Help/guide/tutorial/Step10/TutorialConfig.h.in b/Help/guide/tutorial/Step10/TutorialConfig.h.in index 8cd2fc9..7e4d7fa 100644 --- a/Help/guide/tutorial/Step10/TutorialConfig.h.in +++ b/Help/guide/tutorial/Step10/TutorialConfig.h.in @@ -1,3 +1,3 @@ -// the configured version number +// 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/Step10/tutorial.cxx b/Help/guide/tutorial/Step10/tutorial.cxx index 42eaab9..37a0333 100644 --- a/Help/guide/tutorial/Step10/tutorial.cxx +++ b/Help/guide/tutorial/Step10/tutorial.cxx @@ -16,7 +16,8 @@ int main(int argc, char* argv[]) return 1; } - double inputValue = std::stod(argv[1]); + // convert input to double + const double inputValue = std::stod(argv[1]); const double outputValue = mathfunctions::sqrt(inputValue); diff --git a/Help/guide/tutorial/Step11/CMakeLists.txt b/Help/guide/tutorial/Step11/CMakeLists.txt index e54bdde..4763951 100644 --- a/Help/guide/tutorial/Step11/CMakeLists.txt +++ b/Help/guide/tutorial/Step11/CMakeLists.txt @@ -1,5 +1,7 @@ cmake_minimum_required(VERSION 3.15) -project(Tutorial) + +# 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) @@ -13,10 +15,6 @@ target_compile_options(tutorial_compiler_flags INTERFACE "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>" ) -# set the version number -set(Tutorial_VERSION_MAJOR 1) -set(Tutorial_VERSION_MINOR 0) - # 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}") @@ -26,17 +24,14 @@ set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") option(BUILD_SHARED_LIBS "Build using shared libraries" ON) # configure a header file to pass the version number only -configure_file( - "${PROJECT_SOURCE_DIR}/TutorialConfig.h.in" - "${PROJECT_BINARY_DIR}/TutorialConfig.h" - ) +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 MathFunctions) +target_link_libraries(Tutorial PUBLIC MathFunctions) # add the binary tree to the search path for include files # so that we will find TutorialConfig.h diff --git a/Help/guide/tutorial/Step11/CTestConfig.cmake b/Help/guide/tutorial/Step11/CTestConfig.cmake new file mode 100644 index 0000000..73efdb1 --- /dev/null +++ b/Help/guide/tutorial/Step11/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/Step11/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step11/MathFunctions/CMakeLists.txt index daaaa55..e6cb8ba 100644 --- a/Help/guide/tutorial/Step11/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step11/MathFunctions/CMakeLists.txt @@ -11,11 +11,7 @@ target_include_directories(MathFunctions option(USE_MYMATH "Use tutorial provided math implementation" ON) if(USE_MYMATH) - # does this system provide the log and exp functions? - include(CheckSymbolExists) - set(CMAKE_REQUIRED_LIBRARIES "m") - check_symbol_exists(log "math.h" HAVE_LOG) - check_symbol_exists(exp "math.h" HAVE_EXP) + target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") # first we add the executable that generates the table add_executable(MakeTable MakeTable.cxx) @@ -39,17 +35,12 @@ if(USE_MYMATH) ${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_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") - if(HAVE_LOG AND HAVE_EXP) - target_compile_definitions(SqrtLibrary - PRIVATE "HAVE_LOG" "HAVE_EXP") - endif() target_link_libraries(MathFunctions PRIVATE SqrtLibrary) endif() diff --git a/Help/guide/tutorial/Step11/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step11/MathFunctions/mysqrt.cxx index 96d9421..ff37312 100644 --- a/Help/guide/tutorial/Step11/MathFunctions/mysqrt.cxx +++ b/Help/guide/tutorial/Step11/MathFunctions/mysqrt.cxx @@ -4,8 +4,6 @@ // include the generated table #include "Table.h" -#include <cmath> - namespace mathfunctions { namespace detail { // a hack square root calculation using simple operations @@ -15,20 +13,13 @@ double mysqrt(double x) return 0; } - // if we have both log and exp then use them -#if defined(HAVE_LOG) && defined(HAVE_EXP) - double result = exp(log(x) * 0.5); - std::cout << "Computing sqrt of " << x << " to be " << result << " using log" - << std::endl; -#else // 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)]; } - // if we have both log and exp then use them - // do ten iterations for (int i = 0; i < 10; ++i) { if (result <= 0) { @@ -38,7 +29,7 @@ double mysqrt(double x) result = result + 0.5 * delta / result; std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; } -#endif + return result; } } diff --git a/Help/guide/tutorial/Step11/TutorialConfig.h.in b/Help/guide/tutorial/Step11/TutorialConfig.h.in index 8cd2fc9..7e4d7fa 100644 --- a/Help/guide/tutorial/Step11/TutorialConfig.h.in +++ b/Help/guide/tutorial/Step11/TutorialConfig.h.in @@ -1,3 +1,3 @@ -// the configured version number +// 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/Step11/tutorial.cxx b/Help/guide/tutorial/Step11/tutorial.cxx index 6acafd2..a4f44d5 100644 --- a/Help/guide/tutorial/Step11/tutorial.cxx +++ b/Help/guide/tutorial/Step11/tutorial.cxx @@ -1,5 +1,4 @@ // A simple program that computes the square root of a number -#include <cmath> #include <iostream> #include <string> @@ -16,7 +15,8 @@ int main(int argc, char* argv[]) return 1; } - double inputValue = std::stod(argv[1]); + // convert input to double + const double inputValue = std::stod(argv[1]); const double outputValue = mathfunctions::sqrt(inputValue); diff --git a/Help/guide/tutorial/Step2/CMakeLists.txt b/Help/guide/tutorial/Step2/CMakeLists.txt index 059b89a..7aa59e9 100644 --- a/Help/guide/tutorial/Step2/CMakeLists.txt +++ b/Help/guide/tutorial/Step2/CMakeLists.txt @@ -1,19 +1,15 @@ -cmake_minimum_required(VERSION 3.3) -project(Tutorial) +cmake_minimum_required(VERSION 3.10) +# set the project name and version +project(Tutorial VERSION 1.0) + +# specify the C++ standard set(CMAKE_CXX_STANDARD 11) set(CMAKE_CXX_STANDARD_REQUIRED True) -# set the version number -set(Tutorial_VERSION_MAJOR 1) -set(Tutorial_VERSION_MINOR 0) - # configure a header file to pass some of the CMake settings # to the source code -configure_file( - "${PROJECT_SOURCE_DIR}/TutorialConfig.h.in" - "${PROJECT_BINARY_DIR}/TutorialConfig.h" - ) +configure_file(TutorialConfig.h.in TutorialConfig.h) # add the executable add_executable(Tutorial tutorial.cxx) diff --git a/Help/guide/tutorial/Step2/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step2/MathFunctions/CMakeLists.txt deleted file mode 100644 index 8b443a6..0000000 --- a/Help/guide/tutorial/Step2/MathFunctions/CMakeLists.txt +++ /dev/null @@ -1 +0,0 @@ -add_library(MathFunctions mysqrt.cxx) diff --git a/Help/guide/tutorial/Step2/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step2/MathFunctions/mysqrt.cxx index 7d9379e..1e4d97a 100644 --- a/Help/guide/tutorial/Step2/MathFunctions/mysqrt.cxx +++ b/Help/guide/tutorial/Step2/MathFunctions/mysqrt.cxx @@ -1,4 +1,3 @@ -#include "MathFunctions.h" #include <iostream> // a hack square root calculation using simple operations diff --git a/Help/guide/tutorial/Step2/tutorial.cxx b/Help/guide/tutorial/Step2/tutorial.cxx index f2ab446..53b0810 100644 --- a/Help/guide/tutorial/Step2/tutorial.cxx +++ b/Help/guide/tutorial/Step2/tutorial.cxx @@ -15,9 +15,11 @@ int main(int argc, char* argv[]) return 1; } - double inputValue = std::stod(argv[1]); + // convert input to double + const double inputValue = std::stod(argv[1]); - double outputValue = sqrt(inputValue); + // calculate square root + const double outputValue = sqrt(inputValue); std::cout << "The square root of " << inputValue << " is " << outputValue << std::endl; return 0; diff --git a/Help/guide/tutorial/Step3/CMakeLists.txt b/Help/guide/tutorial/Step3/CMakeLists.txt index 9804abf..1c12816 100644 --- a/Help/guide/tutorial/Step3/CMakeLists.txt +++ b/Help/guide/tutorial/Step3/CMakeLists.txt @@ -1,34 +1,30 @@ -cmake_minimum_required(VERSION 3.3) -project(Tutorial) +cmake_minimum_required(VERSION 3.10) +# set the project name and version +project(Tutorial VERSION 1.0) + +# specify the C++ standard set(CMAKE_CXX_STANDARD 11) set(CMAKE_CXX_STANDARD_REQUIRED True) # should we use our own math functions option(USE_MYMATH "Use tutorial provided math implementation" ON) -# set the version number -set(Tutorial_VERSION_MAJOR 1) -set(Tutorial_VERSION_MINOR 0) - # configure a header file to pass some of the CMake settings # to the source code -configure_file( - "${PROJECT_SOURCE_DIR}/TutorialConfig.h.in" - "${PROJECT_BINARY_DIR}/TutorialConfig.h" - ) +configure_file(TutorialConfig.h.in TutorialConfig.h) -# add the MathFunctions library? +# add the MathFunctions library if(USE_MYMATH) add_subdirectory(MathFunctions) list(APPEND EXTRA_LIBS MathFunctions) list(APPEND EXTRA_INCLUDES "${PROJECT_SOURCE_DIR}/MathFunctions") -endif(USE_MYMATH) +endif() # add the executable add_executable(Tutorial tutorial.cxx) -target_link_libraries(Tutorial ${EXTRA_LIBS}) +target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS}) # add the binary tree to the search path for include files # so that we will find TutorialConfig.h diff --git a/Help/guide/tutorial/Step3/tutorial.cxx b/Help/guide/tutorial/Step3/tutorial.cxx index 8156a9c..b3c6a4f 100644 --- a/Help/guide/tutorial/Step3/tutorial.cxx +++ b/Help/guide/tutorial/Step3/tutorial.cxx @@ -20,13 +20,14 @@ int main(int argc, char* argv[]) return 1; } - double inputValue = std::stod(argv[1]); + // convert input to double + const double inputValue = std::stod(argv[1]); // which square root function should we use? #ifdef USE_MYMATH - double outputValue = mysqrt(inputValue); + const double outputValue = mysqrt(inputValue); #else - double outputValue = sqrt(inputValue); + const double outputValue = sqrt(inputValue); #endif std::cout << "The square root of " << inputValue << " is " << outputValue diff --git a/Help/guide/tutorial/Step4/CMakeLists.txt b/Help/guide/tutorial/Step4/CMakeLists.txt index 0ae2648..38e9b1f 100644 --- a/Help/guide/tutorial/Step4/CMakeLists.txt +++ b/Help/guide/tutorial/Step4/CMakeLists.txt @@ -1,28 +1,24 @@ -cmake_minimum_required(VERSION 3.3) -project(Tutorial) +cmake_minimum_required(VERSION 3.10) +# set the project name and version +project(Tutorial VERSION 1.0) + +# specify the C++ standard set(CMAKE_CXX_STANDARD 11) set(CMAKE_CXX_STANDARD_REQUIRED True) # should we use our own math functions option(USE_MYMATH "Use tutorial provided math implementation" ON) -# set the version number -set(Tutorial_VERSION_MAJOR 1) -set(Tutorial_VERSION_MINOR 0) - # configure a header file to pass some of the CMake settings # to the source code -configure_file( - "${PROJECT_SOURCE_DIR}/TutorialConfig.h.in" - "${PROJECT_BINARY_DIR}/TutorialConfig.h" - ) +configure_file(TutorialConfig.h.in TutorialConfig.h) -# add the MathFunctions library? +# add the MathFunctions library if(USE_MYMATH) add_subdirectory(MathFunctions) list(APPEND EXTRA_LIBS MathFunctions) -endif(USE_MYMATH) +endif() # add the executable add_executable(Tutorial tutorial.cxx) diff --git a/Help/guide/tutorial/Step4/tutorial.cxx b/Help/guide/tutorial/Step4/tutorial.cxx index 8156a9c..b3c6a4f 100644 --- a/Help/guide/tutorial/Step4/tutorial.cxx +++ b/Help/guide/tutorial/Step4/tutorial.cxx @@ -20,13 +20,14 @@ int main(int argc, char* argv[]) return 1; } - double inputValue = std::stod(argv[1]); + // convert input to double + const double inputValue = std::stod(argv[1]); // which square root function should we use? #ifdef USE_MYMATH - double outputValue = mysqrt(inputValue); + const double outputValue = mysqrt(inputValue); #else - double outputValue = sqrt(inputValue); + const double outputValue = sqrt(inputValue); #endif std::cout << "The square root of " << inputValue << " is " << outputValue diff --git a/Help/guide/tutorial/Step5/CMakeLists.txt b/Help/guide/tutorial/Step5/CMakeLists.txt index dac9b45..c3b375a 100644 --- a/Help/guide/tutorial/Step5/CMakeLists.txt +++ b/Help/guide/tutorial/Step5/CMakeLists.txt @@ -1,24 +1,20 @@ -cmake_minimum_required(VERSION 3.3) -project(Tutorial) +cmake_minimum_required(VERSION 3.10) +# set the project name and version +project(Tutorial VERSION 1.0) + +# specify the C++ standard set(CMAKE_CXX_STANDARD 11) set(CMAKE_CXX_STANDARD_REQUIRED True) # should we use our own math functions option(USE_MYMATH "Use tutorial provided math implementation" ON) -# set the version number -set(Tutorial_VERSION_MAJOR 1) -set(Tutorial_VERSION_MINOR 0) - # configure a header file to pass some of the CMake settings # to the source code -configure_file( - "${PROJECT_SOURCE_DIR}/TutorialConfig.h.in" - "${PROJECT_BINARY_DIR}/TutorialConfig.h" - ) +configure_file(TutorialConfig.h.in TutorialConfig.h) -# add the MathFunctions library? +# add the MathFunctions library if(USE_MYMATH) add_subdirectory(MathFunctions) list(APPEND EXTRA_LIBS MathFunctions) diff --git a/Help/guide/tutorial/Step5/tutorial.cxx b/Help/guide/tutorial/Step5/tutorial.cxx index 8156a9c..b3c6a4f 100644 --- a/Help/guide/tutorial/Step5/tutorial.cxx +++ b/Help/guide/tutorial/Step5/tutorial.cxx @@ -20,13 +20,14 @@ int main(int argc, char* argv[]) return 1; } - double inputValue = std::stod(argv[1]); + // convert input to double + const double inputValue = std::stod(argv[1]); // which square root function should we use? #ifdef USE_MYMATH - double outputValue = mysqrt(inputValue); + const double outputValue = mysqrt(inputValue); #else - double outputValue = sqrt(inputValue); + const double outputValue = sqrt(inputValue); #endif std::cout << "The square root of " << inputValue << " is " << outputValue diff --git a/Help/guide/tutorial/Step6/CMakeLists.txt b/Help/guide/tutorial/Step6/CMakeLists.txt index 1465e46..c3b375a 100644 --- a/Help/guide/tutorial/Step6/CMakeLists.txt +++ b/Help/guide/tutorial/Step6/CMakeLists.txt @@ -1,30 +1,20 @@ -cmake_minimum_required(VERSION 3.3) -project(Tutorial) +cmake_minimum_required(VERSION 3.10) +# set the project name and version +project(Tutorial VERSION 1.0) + +# specify the C++ standard set(CMAKE_CXX_STANDARD 11) set(CMAKE_CXX_STANDARD_REQUIRED True) -# set the version number -set(Tutorial_VERSION_MAJOR 1) -set(Tutorial_VERSION_MINOR 0) - -# does this system provide the log and exp functions? -include(CheckSymbolExists) -set(CMAKE_REQUIRED_LIBRARIES "m") -check_symbol_exists(log "math.h" HAVE_LOG) -check_symbol_exists(exp "math.h" HAVE_EXP) - # should we use our own math functions option(USE_MYMATH "Use tutorial provided math implementation" ON) # configure a header file to pass some of the CMake settings # to the source code -configure_file( - "${PROJECT_SOURCE_DIR}/TutorialConfig.h.in" - "${PROJECT_BINARY_DIR}/TutorialConfig.h" - ) +configure_file(TutorialConfig.h.in TutorialConfig.h) -# add the MathFunctions library? +# add the MathFunctions library if(USE_MYMATH) add_subdirectory(MathFunctions) list(APPEND EXTRA_LIBS MathFunctions) diff --git a/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt index def1140..4bf6024 100644 --- a/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt @@ -2,13 +2,21 @@ add_library(MathFunctions mysqrt.cxx) # state that anybody linking to us needs to include the current source dir # to find MathFunctions.h, while we don't. -# state that we depend on Tutorial_BINARY_DIR but consumers don't, as the -# TutorialConfig.h include is an implementation detail target_include_directories(MathFunctions INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} - PRIVATE ${Tutorial_BINARY_DIR} ) +# does this system provide the log and exp functions? +include(CheckSymbolExists) +set(CMAKE_REQUIRED_LIBRARIES "m") +check_symbol_exists(log "math.h" HAVE_LOG) +check_symbol_exists(exp "math.h" HAVE_EXP) + +if(HAVE_LOG AND HAVE_EXP) + target_compile_definitions(MathFunctions + PRIVATE "HAVE_LOG" "HAVE_EXP") +endif() + # install rules install(TARGETS MathFunctions DESTINATION lib) install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Step6/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step6/MathFunctions/mysqrt.cxx index b9ad20a..3f23245 100644 --- a/Help/guide/tutorial/Step6/MathFunctions/mysqrt.cxx +++ b/Help/guide/tutorial/Step6/MathFunctions/mysqrt.cxx @@ -1,5 +1,4 @@ #include "MathFunctions.h" -#include "TutorialConfig.h" #include <iostream> #include <cmath> @@ -14,8 +13,8 @@ double mysqrt(double x) // if we have both log and exp then use them #if defined(HAVE_LOG) && defined(HAVE_EXP) double result = exp(log(x) * 0.5); - std::cout << "Computing sqrt of " << x << " to be " << result << " using log" - << std::endl; + std::cout << "Computing sqrt of " << x << " to be " << result + << " using log and exp" << std::endl; #else double result = x; diff --git a/Help/guide/tutorial/Step6/TutorialConfig.h.in b/Help/guide/tutorial/Step6/TutorialConfig.h.in index e97ce24..e23f521 100644 --- a/Help/guide/tutorial/Step6/TutorialConfig.h.in +++ b/Help/guide/tutorial/Step6/TutorialConfig.h.in @@ -2,7 +2,3 @@ #define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ #define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ #cmakedefine USE_MYMATH - -// does the platform provide exp and log functions? -#cmakedefine HAVE_LOG -#cmakedefine HAVE_EXP diff --git a/Help/guide/tutorial/Step6/tutorial.cxx b/Help/guide/tutorial/Step6/tutorial.cxx index 8156a9c..b3c6a4f 100644 --- a/Help/guide/tutorial/Step6/tutorial.cxx +++ b/Help/guide/tutorial/Step6/tutorial.cxx @@ -20,13 +20,14 @@ int main(int argc, char* argv[]) return 1; } - double inputValue = std::stod(argv[1]); + // convert input to double + const double inputValue = std::stod(argv[1]); // which square root function should we use? #ifdef USE_MYMATH - double outputValue = mysqrt(inputValue); + const double outputValue = mysqrt(inputValue); #else - double outputValue = sqrt(inputValue); + const double outputValue = sqrt(inputValue); #endif std::cout << "The square root of " << inputValue << " is " << outputValue diff --git a/Help/guide/tutorial/Step7/CMakeLists.txt b/Help/guide/tutorial/Step7/CMakeLists.txt index a1efa77..c3b375a 100644 --- a/Help/guide/tutorial/Step7/CMakeLists.txt +++ b/Help/guide/tutorial/Step7/CMakeLists.txt @@ -1,34 +1,24 @@ -cmake_minimum_required(VERSION 3.3) -project(Tutorial) +cmake_minimum_required(VERSION 3.10) +# set the project name and version +project(Tutorial VERSION 1.0) + +# specify the C++ standard set(CMAKE_CXX_STANDARD 11) set(CMAKE_CXX_STANDARD_REQUIRED True) -# set the version number -set(Tutorial_VERSION_MAJOR 1) -set(Tutorial_VERSION_MINOR 0) - -# does this system provide the log and exp functions? -include(CheckSymbolExists) -set(CMAKE_REQUIRED_LIBRARIES "m") -check_symbol_exists(log "math.h" HAVE_LOG) -check_symbol_exists(exp "math.h" HAVE_EXP) - # should we use our own math functions option(USE_MYMATH "Use tutorial provided math implementation" ON) # configure a header file to pass some of the CMake settings # to the source code -configure_file( - "${PROJECT_SOURCE_DIR}/TutorialConfig.h.in" - "${PROJECT_BINARY_DIR}/TutorialConfig.h" - ) +configure_file(TutorialConfig.h.in TutorialConfig.h) -# add the MathFunctions library? +# add the MathFunctions library if(USE_MYMATH) add_subdirectory(MathFunctions) list(APPEND EXTRA_LIBS MathFunctions) -endif(USE_MYMATH) +endif() # add the executable add_executable(Tutorial tutorial.cxx) @@ -38,7 +28,7 @@ target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS}) # so that we will find TutorialConfig.h target_include_directories(Tutorial PUBLIC "${PROJECT_BINARY_DIR}" - ) + ) # add the install targets install(TARGETS Tutorial DESTINATION bin) diff --git a/Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt index 3c3a816..9ede4b3 100644 --- a/Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt @@ -21,8 +21,7 @@ add_library(MathFunctions # state that we depend on our binary dir to find Table.h target_include_directories(MathFunctions INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} - PRIVATE ${Tutorial_BINARY_DIR} - ${CMAKE_CURRENT_BINARY_DIR} + PRIVATE ${CMAKE_CURRENT_BINARY_DIR} ) # install rules diff --git a/Help/guide/tutorial/Step7/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step7/MathFunctions/mysqrt.cxx index 5272f56..2ae60c6 100644 --- a/Help/guide/tutorial/Step7/MathFunctions/mysqrt.cxx +++ b/Help/guide/tutorial/Step7/MathFunctions/mysqrt.cxx @@ -1,12 +1,9 @@ #include "MathFunctions.h" -#include "TutorialConfig.h" #include <iostream> // include the generated table #include "Table.h" -#include <cmath> - // a hack square root calculation using simple operations double mysqrt(double x) { @@ -17,6 +14,7 @@ double mysqrt(double x) // 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)]; } diff --git a/Help/guide/tutorial/Step7/TutorialConfig.h.in b/Help/guide/tutorial/Step7/TutorialConfig.h.in index e97ce24..e23f521 100644 --- a/Help/guide/tutorial/Step7/TutorialConfig.h.in +++ b/Help/guide/tutorial/Step7/TutorialConfig.h.in @@ -2,7 +2,3 @@ #define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ #define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ #cmakedefine USE_MYMATH - -// does the platform provide exp and log functions? -#cmakedefine HAVE_LOG -#cmakedefine HAVE_EXP diff --git a/Help/guide/tutorial/Step7/tutorial.cxx b/Help/guide/tutorial/Step7/tutorial.cxx index 8156a9c..b3c6a4f 100644 --- a/Help/guide/tutorial/Step7/tutorial.cxx +++ b/Help/guide/tutorial/Step7/tutorial.cxx @@ -20,13 +20,14 @@ int main(int argc, char* argv[]) return 1; } - double inputValue = std::stod(argv[1]); + // convert input to double + const double inputValue = std::stod(argv[1]); // which square root function should we use? #ifdef USE_MYMATH - double outputValue = mysqrt(inputValue); + const double outputValue = mysqrt(inputValue); #else - double outputValue = sqrt(inputValue); + const double outputValue = sqrt(inputValue); #endif std::cout << "The square root of " << inputValue << " is " << outputValue diff --git a/Help/guide/tutorial/Step8/CMakeLists.txt b/Help/guide/tutorial/Step8/CMakeLists.txt index a0316a0..19b9913 100644 --- a/Help/guide/tutorial/Step8/CMakeLists.txt +++ b/Help/guide/tutorial/Step8/CMakeLists.txt @@ -1,34 +1,24 @@ -cmake_minimum_required(VERSION 3.3) -project(Tutorial) +cmake_minimum_required(VERSION 3.10) +# set the project name and version +project(Tutorial VERSION 1.0) + +# specify the C++ standard set(CMAKE_CXX_STANDARD 11) set(CMAKE_CXX_STANDARD_REQUIRED True) -# set the version number -set(Tutorial_VERSION_MAJOR 1) -set(Tutorial_VERSION_MINOR 0) - -# does this system provide the log and exp functions? -include(CheckSymbolExists) -set(CMAKE_REQUIRED_LIBRARIES "m") -check_symbol_exists(log "math.h" HAVE_LOG) -check_symbol_exists(exp "math.h" HAVE_EXP) - # should we use our own math functions option(USE_MYMATH "Use tutorial provided math implementation" ON) # configure a header file to pass some of the CMake settings # to the source code -configure_file( - "${PROJECT_SOURCE_DIR}/TutorialConfig.h.in" - "${PROJECT_BINARY_DIR}/TutorialConfig.h" - ) +configure_file(TutorialConfig.h.in TutorialConfig.h) -# add the MathFunctions library? +# add the MathFunctions library if(USE_MYMATH) add_subdirectory(MathFunctions) list(APPEND EXTRA_LIBS MathFunctions) -endif(USE_MYMATH) +endif() # add the executable add_executable(Tutorial tutorial.cxx) @@ -60,7 +50,7 @@ set_tests_properties(Usage # define a function to simplify adding tests function(do_test target arg result) -add_test(NAME Comp${arg} COMMAND ${target} ${arg}) + add_test(NAME Comp${arg} COMMAND ${target} ${arg}) set_tests_properties(Comp${arg} PROPERTIES PASS_REGULAR_EXPRESSION ${result} ) diff --git a/Help/guide/tutorial/Step8/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step8/MathFunctions/CMakeLists.txt index 3c3a816..9ede4b3 100644 --- a/Help/guide/tutorial/Step8/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step8/MathFunctions/CMakeLists.txt @@ -21,8 +21,7 @@ add_library(MathFunctions # state that we depend on our binary dir to find Table.h target_include_directories(MathFunctions INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} - PRIVATE ${Tutorial_BINARY_DIR} - ${CMAKE_CURRENT_BINARY_DIR} + PRIVATE ${CMAKE_CURRENT_BINARY_DIR} ) # install rules diff --git a/Help/guide/tutorial/Step8/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step8/MathFunctions/mysqrt.cxx index 5b862fb..2ae60c6 100644 --- a/Help/guide/tutorial/Step8/MathFunctions/mysqrt.cxx +++ b/Help/guide/tutorial/Step8/MathFunctions/mysqrt.cxx @@ -1,12 +1,9 @@ #include "MathFunctions.h" -#include "TutorialConfig.h" #include <iostream> // include the generated table #include "Table.h" -#include <cmath> - // a hack square root calculation using simple operations double mysqrt(double x) { @@ -14,20 +11,13 @@ double mysqrt(double x) return 0; } - // if we have both log and exp then use them -#if defined(HAVE_LOG) && defined(HAVE_EXP) - double result = exp(log(x) * 0.5); - std::cout << "Computing sqrt of " << x << " to be " << result << " using log" - << std::endl; -#else // 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)]; } - // if we have both log and exp then use them - // do ten iterations for (int i = 0; i < 10; ++i) { if (result <= 0) { @@ -37,6 +27,6 @@ double mysqrt(double x) result = result + 0.5 * delta / result; std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; } -#endif + return result; } diff --git a/Help/guide/tutorial/Step8/TutorialConfig.h.in b/Help/guide/tutorial/Step8/TutorialConfig.h.in index e97ce24..e23f521 100644 --- a/Help/guide/tutorial/Step8/TutorialConfig.h.in +++ b/Help/guide/tutorial/Step8/TutorialConfig.h.in @@ -2,7 +2,3 @@ #define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ #define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ #cmakedefine USE_MYMATH - -// does the platform provide exp and log functions? -#cmakedefine HAVE_LOG -#cmakedefine HAVE_EXP diff --git a/Help/guide/tutorial/Step8/tutorial.cxx b/Help/guide/tutorial/Step8/tutorial.cxx index 8156a9c..b3c6a4f 100644 --- a/Help/guide/tutorial/Step8/tutorial.cxx +++ b/Help/guide/tutorial/Step8/tutorial.cxx @@ -20,13 +20,14 @@ int main(int argc, char* argv[]) return 1; } - double inputValue = std::stod(argv[1]); + // convert input to double + const double inputValue = std::stod(argv[1]); // which square root function should we use? #ifdef USE_MYMATH - double outputValue = mysqrt(inputValue); + const double outputValue = mysqrt(inputValue); #else - double outputValue = sqrt(inputValue); + const double outputValue = sqrt(inputValue); #endif std::cout << "The square root of " << inputValue << " is " << outputValue diff --git a/Help/guide/tutorial/Step9/CMakeLists.txt b/Help/guide/tutorial/Step9/CMakeLists.txt index e610b99..d5f1cc8 100644 --- a/Help/guide/tutorial/Step9/CMakeLists.txt +++ b/Help/guide/tutorial/Step9/CMakeLists.txt @@ -1,29 +1,20 @@ -cmake_minimum_required(VERSION 3.3) -project(Tutorial) +cmake_minimum_required(VERSION 3.10) +# set the project name and version +project(Tutorial VERSION 1.0) + +# specify the C++ standard set(CMAKE_CXX_STANDARD 11) set(CMAKE_CXX_STANDARD_REQUIRED True) -# set the version number -set(Tutorial_VERSION_MAJOR 1) -set(Tutorial_VERSION_MINOR 0) - -# does this system provide the log and exp functions? -include(CheckSymbolExists) -set(CMAKE_REQUIRED_LIBRARIES "m") -check_symbol_exists(log "math.h" HAVE_LOG) -check_symbol_exists(exp "math.h" HAVE_EXP) - # should we use our own math functions option(USE_MYMATH "Use tutorial provided math implementation" ON) -# configure a header file to pass the version number only -configure_file( - "${PROJECT_SOURCE_DIR}/TutorialConfig.h.in" - "${PROJECT_BINARY_DIR}/TutorialConfig.h" - ) +# configure a header file to pass some of the CMake settings +# to the source code +configure_file(TutorialConfig.h.in TutorialConfig.h) -# add the MathFunctions library? +# add the MathFunctions library if(USE_MYMATH) add_subdirectory(MathFunctions) list(APPEND EXTRA_LIBS MathFunctions) diff --git a/Help/guide/tutorial/Step9/CTestConfig.cmake b/Help/guide/tutorial/Step9/CTestConfig.cmake index 7a927ac..73efdb1 100644 --- a/Help/guide/tutorial/Step9/CTestConfig.cmake +++ b/Help/guide/tutorial/Step9/CTestConfig.cmake @@ -1,11 +1,3 @@ -## This file should be placed in the root directory of your project. -## Then modify the CMakeLists.txt file in the root directory of your -## project to incorporate the testing dashboard. -## -## # The following are required to submit to the CDash dashboard: -## ENABLE_TESTING() -## INCLUDE(CTest) - set(CTEST_PROJECT_NAME "CMakeTutorial") set(CTEST_NIGHTLY_START_TIME "00:00:00 EST") diff --git a/Help/guide/tutorial/Step9/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step9/MathFunctions/CMakeLists.txt index c8cd1dd..50f0701 100644 --- a/Help/guide/tutorial/Step9/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step9/MathFunctions/CMakeLists.txt @@ -22,15 +22,6 @@ target_include_directories(MathFunctions PRIVATE ${CMAKE_CURRENT_BINARY_DIR} ) -# use compile definitions to state if we have enabled USE_MYMATH -# and that anything that links to use will get this define -target_compile_definitions(MathFunctions INTERFACE "USE_MYMATH") - -if(HAVE_LOG AND HAVE_EXP) - target_compile_definitions(MathFunctions - PRIVATE "HAVE_LOG" "HAVE_EXP") -endif() - # install rules install(TARGETS MathFunctions DESTINATION lib) install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Step9/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step9/MathFunctions/mysqrt.cxx index 8b82141..2ae60c6 100644 --- a/Help/guide/tutorial/Step9/MathFunctions/mysqrt.cxx +++ b/Help/guide/tutorial/Step9/MathFunctions/mysqrt.cxx @@ -4,8 +4,6 @@ // include the generated table #include "Table.h" -#include <cmath> - // a hack square root calculation using simple operations double mysqrt(double x) { @@ -13,20 +11,13 @@ double mysqrt(double x) return 0; } - // if we have both log and exp then use them -#if defined(HAVE_LOG) && defined(HAVE_EXP) - double result = exp(log(x) * 0.5); - std::cout << "Computing sqrt of " << x << " to be " << result << " using log" - << std::endl; -#else // 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)]; } - // if we have both log and exp then use them - // do ten iterations for (int i = 0; i < 10; ++i) { if (result <= 0) { @@ -36,6 +27,6 @@ double mysqrt(double x) result = result + 0.5 * delta / result; std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; } -#endif + return result; } diff --git a/Help/guide/tutorial/Step9/TutorialConfig.h.in b/Help/guide/tutorial/Step9/TutorialConfig.h.in index 8cd2fc9..e23f521 100644 --- a/Help/guide/tutorial/Step9/TutorialConfig.h.in +++ b/Help/guide/tutorial/Step9/TutorialConfig.h.in @@ -1,3 +1,4 @@ -// the configured version number +// the configured options and settings for Tutorial #define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ #define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ +#cmakedefine USE_MYMATH diff --git a/Help/guide/tutorial/Step9/tutorial.cxx b/Help/guide/tutorial/Step9/tutorial.cxx index 3286bc8..b3c6a4f 100644 --- a/Help/guide/tutorial/Step9/tutorial.cxx +++ b/Help/guide/tutorial/Step9/tutorial.cxx @@ -1,7 +1,6 @@ // A simple program that computes the square root of a number #include <cmath> #include <iostream> -#include <sstream> #include <string> #include "TutorialConfig.h" @@ -21,13 +20,14 @@ int main(int argc, char* argv[]) return 1; } - double inputValue = std::stod(argv[1]); + // convert input to double + const double inputValue = std::stod(argv[1]); // which square root function should we use? #ifdef USE_MYMATH - double outputValue = mysqrt(inputValue); + const double outputValue = mysqrt(inputValue); #else - double outputValue = sqrt(inputValue); + const double outputValue = sqrt(inputValue); #endif std::cout << "The square root of " << inputValue << " is " << outputValue diff --git a/Help/guide/tutorial/index.rst b/Help/guide/tutorial/index.rst index 068499e..d858c25 100644 --- a/Help/guide/tutorial/index.rst +++ b/Help/guide/tutorial/index.rst @@ -5,33 +5,38 @@ CMake Tutorial .. contents:: -This tutorial provides a step-by-step guide that covers common build +The CMake tutorial provides a step-by-step guide that covers common build system issues that CMake helps address. Seeing how various topics all -work together in an example project can be very helpful. This tutorial -can be found in the ``Help/guide/tutorial`` directory of the CMake -source code tree. Each topic has its own subdirectory containing code -that may be used as a starting point for that step. The tutorial -examples are progressive so that each step provides the complete +work together in an example project can be very helpful. The tutorial +documentation and source code for examples can be found in the +``Help/guide/tutorial`` directory of the CMake source code tree. Each step has +its own subdirectory containing code that may be used as a starting point. The +tutorial examples are progressive so that each step provides the complete solution for the previous step. A Basic Starting Point (Step 1) =============================== The most basic project is an executable built from source code files. -For simple projects, a two line CMakeLists file is all that is required. -This will be the starting point for our tutorial. The CMakeLists file -looks like: +For simple projects, a three line CMakeLists file is all that is required. +This will be the starting point for our tutorial. Create a ``CMakeLists.txt`` +file in the ``Step1`` directory that looks like: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.10) + + # set the project name + project(Tutorial) + + # add the executable + add_executable(Tutorial tutorial.cxx) -.. literalinclude:: Step1/CMakeLists.txt - :language: cmake Note that this example uses lower case commands in the CMakeLists file. Upper, lower, and mixed case commands are supported by CMake. The source -code for ``tutorial.cxx`` will compute the square root of a number and -the first version of it is very simple, as follows: - -.. literalinclude:: Step1/tutorial.cxx - :language: c++ +code for ``tutorial.cxx`` is provided in the ``Step1`` directory and can be +used to compute the square root of a number. Adding a Version Number and Configured Header File -------------------------------------------------- @@ -40,55 +45,70 @@ The first feature we will add is to provide our executable and project with a version number. While we could do this exclusively in the source code, using CMakeLists provides more flexibility. -To add a version number we modify the CMakeLists file as follows: +First, modify the CMakeLists file to set the version number. .. literalinclude:: Step2/CMakeLists.txt :language: cmake - :start-after: # set the version number - :end-before: # configure a header file + :end-before: # specify the C++ standard + +Then, configure a header file to pass the version number to the source +code: + +.. literalinclude:: Step2/CMakeLists.txt + :language: cmake + :start-after: # to the source code + :end-before: # add the executable Since the configured file will be written into the binary tree, we must add that directory to the list of paths to search for include -files. +files. Add the following lines to the end of the CMakeLists file: .. literalinclude:: Step2/CMakeLists.txt :language: cmake :start-after: # so that we will find TutorialConfig.h -We then create a ``TutorialConfig.h.in`` file in the source tree with the -following contents: +Using your favorite editor, create ``TutorialConfig.h.in`` in the source +directory with the following contents: -.. literalinclude:: Step1/TutorialConfig.h.in +.. literalinclude:: Step2/TutorialConfig.h.in :language: cmake When CMake configures this header file the values for ``@Tutorial_VERSION_MAJOR@`` and ``@Tutorial_VERSION_MINOR@`` will be -replaced by the values from the CMakeLists file. Next we modify -``tutorial.cxx`` to include the configured header file and to make use of the -version numbers. The updated source code is listed below. +replaced. + +Next modify ``tutorial.cxx`` to include the configured header file, +``TutorialConfig.h``. + +Finally, let's print out the version number by updating ``tutorial.cxx`` as +follows: .. literalinclude:: Step2/tutorial.cxx :language: c++ - :start-after: // report version - :end-before: return 1; - -The main changes are the inclusion of the ``TutorialConfig.h`` header -file and printing out a version number as part of the usage message. + :start-after: { + :end-before: // convert input to double Specify the C++ Standard ------------------------- -Next let's add some C++11 features to our project. We will need to explicitly -state in the CMake code that it should use the correct flags. The easiest way -to enable C++11 support for CMake is by using the ``CMAKE_CXX_STANDARD`` -variable. +Next let's add some C++11 features to our project by replacing ``atof`` with +``std::stod`` in ``tutorial.cxx``. At the same time, remove +``#include <cstdlib>``. -First, replace ``atof`` with ``std::stod`` in ``tutorial.cxx``. +.. literalinclude:: Step2/tutorial.cxx + :language: c++ + :start-after: // convert input to double + :end-before: // calculate square root -Then, set the ``CMAKE_CXX_STANDARD`` variable in the CMakeLists file. +We will need to explicitly state in the CMake code that it should use the +correct flags. The easiest way to enable support for a specific C++ standard +in CMake is by using the ``CMAKE_CXX_STANDARD`` variable. For this tutorial, +set the ``CMAKE_CXX_STANDARD`` variable in the CMakeLists file to 11 and +``CMAKE_CXX_STANDARD_REQUIRED`` to True: -Which variable can we set in the CMakeLists file to treat the -``CMAKE_CXX_STANDARD`` value as a requirement? +.. literalinclude:: Step2/CMakeLists.txt + :language: cmake + :end-before: # configure a header file to pass some of the CMake settings Build and Test -------------- @@ -96,8 +116,19 @@ Build and Test Run **cmake** or **cmake-gui** to configure the project and then build it with your chosen build tool. -cd to the directory where Tutorial was built (likely the make directory or -a Debug or Release build configuration subdirectory) and run these commands: +For example, from the command line we could navigate to the +``Help/guide/tutorial`` directory of the CMake source code tree and run the +following commands: + +.. code-block:: console + + mkdir Step1_build + cd Step1_build + cmake ../Step1 + cmake --build . + +Navigate to the directory where Tutorial was built (likely the make directory +or a Debug or Release build configuration subdirectory) and run these commands: .. code-block:: console @@ -114,18 +145,22 @@ then use this library instead of the standard square root function provided by the compiler. For this tutorial we will put the library into a subdirectory -called MathFunctions. It will have the following one line CMakeLists file: +called MathFunctions. This directory already contains a header file, +``MathFunctions.h``, and a source file ``mysqrt.cxx``. The source file has one +function called ``mysqrt`` that provides similar functionality to the +compiler's ``sqrt`` function. -.. literalinclude:: Step2/MathFunctions/CMakeLists.txt +Add the following one line ``CMakeLists.txt`` file to the MathFunctions +directory: + +.. literalinclude:: Step3/MathFunctions/CMakeLists.txt :language: cmake -The source file ``mysqrt.cxx`` has one function called ``mysqrt`` that -provides similar functionality to the compiler’s ``sqrt`` function. To make use -of the new library we add an ``add_subdirectory`` call in the top-level -CMakeLists file so that the library will get built. We add the new library to -the executable, and add MathFunctions as an include directory so that the -``mqsqrt.h`` header file can be found. The last few lines of the top-level -CMakeLists file now look like: +To make use of the new library we will add an ``add_subdirectory`` call in the +top-level CMakeLists file so that the library will get built. We add the new +library to the executable, and add MathFunctions as an include directory so +that the ``mqsqrt.h`` header file can be found. The last few lines of the +top-level CMakeLists file should now look like: .. code-block:: cmake @@ -135,7 +170,7 @@ CMakeLists file now look like: # add the executable add_executable(Tutorial tutorial.cxx) - target_link_libraries(Tutorial MathFunctions) + target_link_libraries(Tutorial PUBLIC MathFunctions) # add the binary tree to the search path for include files # so that we will find TutorialConfig.h @@ -152,12 +187,12 @@ file. .. literalinclude:: Step3/CMakeLists.txt :language: cmake :start-after: # should we use our own math functions - :end-before: # set the version number + :end-before: # add the MathFunctions library -This will show up in the CMake GUI and ccmake with a default value of ON -that can be changed by the user. This setting will be stored in the cache so -that the user does not need to set the value each time they run CMake on this -build directory. +This option will be displayed in the CMake GUI and ccmake with a default +value of ON that can be changed by the user. This setting will be stored in +the cache so that the user does not need to set the value each time they run +CMake on a build directory. The next change is to make building and linking the MathFunctions library conditional. To do this we change the end of the top-level CMakeLists file to @@ -165,22 +200,24 @@ look like the following: .. literalinclude:: Step3/CMakeLists.txt :language: cmake - :start-after: # add the MathFunctions library? + :start-after: # add the MathFunctions library -Note the use of the variables ``EXTRA_LIBS`` and ``EXTRA_INCLUDES`` to collect -up any optional libraries to later be linked into the executable. This is a -classic approach when dealing with many optional components, we will cover the -modern approach in the next step. +Note the use of the variable ``EXTRA_LIBS`` to collect up any optional +libraries to later be linked into the executable. The variable +``EXTRA_INCLUDES`` is used similarly for optional header files. This is a +classic approach when dealing with many optional components, we will cover +the modern approach in the next step. The corresponding changes to the source code are fairly straightforward. First, -include the MathFunctions header if we need it: +in ``tutorial.cxx``, include the MathFunctions header if we need it: .. literalinclude:: Step3/tutorial.cxx :language: c++ :start-after: // should we include the MathFunctions header :end-before: int main -Then make which square root function is used dependent on ``USE_MYMATH``: +Then, in the same file, make which square root function is used dependent on +``USE_MYMATH``: .. literalinclude:: Step3/tutorial.cxx :language: c++ @@ -194,10 +231,14 @@ Since the source code now requires ``USE_MYMATH`` we can add it to :language: c :lines: 4 +**Exercise**: Why is it important that we configure ``TutorialConfig.h.in`` +after the option for ``USE_MYMATH``? What would happen if we inverted the two? + Run **cmake** or **cmake-gui** to configure the project and then build it with your chosen build tool. Then run the built Tutorial executable. -Which function gives better results, Step1’s sqrt or Step2’s mysqrt? +Use ccmake or the CMake GUI to update the value of ``USE_MYMATH``. Rebuild and +run the tutorial again. Which function gives better results, sqrt or mysqrt? Adding Usage Requirements for Library (Step 3) ============================================== @@ -212,12 +253,14 @@ requirements are: - ``target_include_directories`` - ``target_link_libraries`` -First up is MathFunctions. We first state that anybody linking to MathFunctions -needs to include the current source directory, while MathFunctions itself -doesn't. So this can become an ``INTERFACE`` usage requirement. +Let's refactor our code from `Adding a Library (Step 2)`_ to use the modern +CMake approach of usage requirements. We first state that anybody linking to +MathFunctions needs to include the current source directory, while +MathFunctions itself doesn't. So this can become an ``INTERFACE`` usage +requirement. Remember ``INTERFACE`` means things that consumers require but the producer -doesn't. Update ``MathFunctions/CMakeLists.txt`` with: +doesn't. Add the following lines to the end of ``MathFunctions/CMakeLists.txt``: .. literalinclude:: Step4/MathFunctions/CMakeLists.txt :language: cmake @@ -225,7 +268,18 @@ doesn't. Update ``MathFunctions/CMakeLists.txt`` with: Now that we've specified usage requirements for MathFunctions we can safely remove our uses of the ``EXTRA_INCLUDES`` variable from the top-level -CMakeLists. +CMakeLists, here: + +.. literalinclude:: Step4/CMakeLists.txt + :language: cmake + :start-after: # add the MathFunctions library + :end-before: # add the executable + +And here: + +.. literalinclude:: Step4/CMakeLists.txt + :language: cmake + :start-after: # so that we will find TutorialConfig.h Once this is done, run **cmake** or **cmake-gui** to configure the project and then build it with your chosen build tool or by using ``cmake --build .`` @@ -239,17 +293,17 @@ Now we can start adding install rules and testing support to our project. Install Rules ------------- -The install rules are fairly simple for MathFunctions we want to install the +The install rules are fairly simple: for MathFunctions we want to install the library and header file and for the application we want to install the executable and configured header. -So to ``MathFunctions/CMakeLists.txt`` we add: +So to the end of ``MathFunctions/CMakeLists.txt`` we add: .. literalinclude:: Step5/MathFunctions/CMakeLists.txt :language: cmake :start-after: # install rules -And the to top-level ``CMakeLists.txt`` we add: +And to the end of the top-level ``CMakeLists.txt`` we add: .. literalinclude:: Step5/CMakeLists.txt :language: cmake @@ -260,21 +314,25 @@ That is all that is needed to create a basic local install of the tutorial. Run **cmake** or **cmake-gui** to configure the project and then build it with your chosen build tool. Run the install step by typing -``cmake --install .`` or from the command line, or build the ``INSTALL`` -target from an IDE. This will install the appropriate header files, libraries, -and executables. +``cmake --install .`` (introduced in 3.15, older versions of CMake must use +``make install``) from the command line, or build the ``INSTALL`` target from +an IDE. This will install the appropriate header files, libraries, and +executables. + +The CMake variable ``CMAKE_INSTALL_PREFIX`` is used to determine the root of +where the files will be installed. If using ``cmake --install`` a custom +installation directory can be given via ``--prefix`` argument. For +multi-configuration tools, use the ``--config`` argument to specify the +configuration. -Verify that the installed Tutorial runs. Note: The CMake variable -``CMAKE_INSTALL_PREFIX`` is used to determine the root of where the files will -be installed. If using ``cmake --install`` a custom installation directory can -be given via ``--prefix`` argument. +Verify that the installed Tutorial runs. Testing Support --------------- Next let's test our application. At the end of the top-level CMakeLists file we -can add a number of basic tests to verify that the application is -working correctly. +can enable testing and then add a number of basic tests to verify that the +application is working correctly. .. literalinclude:: Step5/CMakeLists.txt :language: cmake @@ -285,7 +343,7 @@ otherwise crash, and has a zero return value. This is the basic form of a CTest test. The next test makes use of the ``PASS_REGULAR_EXPRESSION`` test property to -verify that the output of the test contains certain strings, in this case: +verify that the output of the test contains certain strings. In this case, verifying that the the usage message is printed when an incorrect number of arguments are provided. @@ -295,7 +353,11 @@ invocation of ``do_test``, another test is added to the project with a name, input, and expected results based on the passed arguments. Rebuild the application and then cd to the binary directory and run -``ctest -N`` and ``ctest -VV``. +``ctest -N`` and ``ctest -VV``. For multi-config generators (e.g. Visual +Studio), the configuration type must be specified. To run tests in Debug mode, +for example, use ``ctest -C Debug -VV`` from the build directory (not the +Debug subdirectory!). Alternatively, build the ``RUN_TESTS`` target from the +IDE. Adding System Introspection (Step 5) ==================================== @@ -309,72 +371,108 @@ tutorial assume that they are not common. If the platform has ``log`` and ``exp`` then we will use them to compute the square root in the ``mysqrt`` function. We first test for the availability of these functions using the ``CheckSymbolExists.cmake`` macro in the top-level -CMakeLists file as follows: +CMakeLists. We're going to use the new defines in ``TutorialConfig.h.in``, +so be sure to set them before that file is configured. -.. literalinclude:: Step6/CMakeLists.txt +.. literalinclude:: Step6/MathFunctions/CMakeLists.txt :language: cmake :start-after: # does this system provide the log and exp functions? - :end-before: # should we use our own math functions + :end-before: if(HAVE_LOG AND HAVE_EXP) Now let's add these defines to ``TutorialConfig.h.in`` so that we can use them from ``mysqrt.cxx``: -.. literalinclude:: Step6/TutorialConfig.h.in - :language: c - :start-after: // does the platform provide exp and log functions? +.. code-block:: console -Finally, in the ``mysqrt`` function we can provide an alternate implementation -based on ``log`` and ``exp`` if they are available on the system using the -following code: + // does the platform provide exp and log functions? + #cmakedefine HAVE_LOG + #cmakedefine HAVE_EXP + +Modify ``mysqrt.cxx`` to include cmath. Next, in that same file in the +``mysqrt`` function we can provide an alternate implementation based on +``log`` and ``exp`` if they are available on the system using the following +code (don't forget the ``#endif`` before returning the result!): .. literalinclude:: Step6/MathFunctions/mysqrt.cxx :language: c++ :start-after: // if we have both log and exp then use them - :end-before: #else + :end-before: // do ten iterations Run **cmake** or **cmake-gui** to configure the project and then build it -with your chosen build tool. +with your chosen build tool and run the Tutorial executable. -You will notice that even though ``HAVE_LOG`` and ``HAVE_EXP`` are both -defined ``mysqrt`` isn't using them. We should realize quickly that we have -forgotten to include ``TutorialConfig.h`` in ``mysqrt.cxx``. +You will notice that we're not using ``log`` and ``exp``, even if we think they +should be available. We should realize quickly that we have forgotten to include +``TutorialConfig.h`` in ``mysqrt.cxx``. -After making this update, go ahead and build the project again. +We will also need to update MathFunctions/CMakeLists so ``mysqrt.cxx`` knows +where this file is located: -Run the built Tutorial executable. Which function gives better results now, -Step1’s sqrt or Step5’s mysqrt? -**Exercise**: Why is it important that we configure ``TutorialConfig.h.in`` -after the checks for ``HAVE_LOG`` and ``HAVE_EXP``? What would happen if we -inverted the two? +.. code-block:: cmake + + target_include_directories(MathFunctions + INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} + PRIVATE ${CMAKE_BINARY_DIR} + ) + +After making this update, go ahead and build the project again and run the built +Tutorial executable. If ``log`` and ``exp`` are still not being used, open the +generated ``TutorialConfig.h`` file from the build directory. Maybe they aren't +available on the current system? -**Exercise**: Is there a better place for us to save the ``HAVE_LOG`` and -``HAVE_EXP`` values other than in ``TutorialConfig.h``? +Which function gives better results now, sqrt or mysqrt? + +Specify Compile Definition +-------------------------- + +Is there a better place for us to save the ``HAVE_LOG`` and ``HAVE_EXP`` values +other than in ``TutorialConfig.h``? Let's try to use +``target_compile_definitions``. + +First, remove the defines from ``TutorialConfig.h.in``. We no longer need to +include ``TutorialConfig.h`` from ``mysqrt.cxx`` or the extra include in +MathFunctions/CMakeLists. + +Next, we can move the check for ``HAVE_LOG`` and ``HAVE_EXP`` to +MathFunctions/CMakeLists and then add specify those values as ``PRIVATE`` +compile definitions. + +.. literalinclude:: Step6/MathFunctions/CMakeLists.txt + :language: cmake + :start-after: # does this system provide the log and exp functions? + :end-before: # install rules + +After making these updates, go ahead and build the project again. Run the +built Tutorial executable and verify that the results are same as earlier in +this step. Adding a Custom Command and Generated File (Step 6) =================================================== -In this section, we will add a generated source file into the build process -of an application. For this example, we will create a table of precomputed -square roots as part of the build process, and then compile that -table into our application. +Suppose, for the purpose of this tutorial, we decide that we never want to use +the platform ``log`` and ``exp`` functions and instead would like to +generate a table of precomputed values to use in the ``mysqrt`` function. +In this section, we will create the table as part of the build process, +and then compile that table into our application. -To accomplish this, we first need a program that will generate the table. In -the MathFunctions subdirectory a new source file named ``MakeTable.cxx`` will -do just that. +First, let's remove the check for the ``log`` and ``exp`` functions in +MathFunctions/CMakeLists. Then remove the check for ``HAVE_LOG`` and +``HAVE_EXP`` from ``mysqrt.cxx``. At the same time, we can remove +:code:`#include <cmath>`. -.. literalinclude:: Step7/MathFunctions/MakeTable.cxx - :language: c++ +In the MathFunctions subdirectory, a new source file named ``MakeTable.cxx`` +has been provided to generate the table. -Note that the table is produced as valid C++ code and that the output filename -is passed in as an argument. +After reviewing the file, we can see that the table is produced as valid C++ +code and that the output filename is passed in as an argument. -The next step is to add the appropriate commands to MathFunctions' CMakeLists +The next step is to add the appropriate commands to MathFunctions CMakeLists file to build the MakeTable executable and then run it as part of the build process. A few commands are needed to accomplish this. -First, the executable for ``MakeTable`` is added as any other executable would -be added. +First, at the top of MathFunctions/CMakeLists, the executable for ``MakeTable`` +is added as any other executable would be added. .. literalinclude:: Step7/MathFunctions/CMakeLists.txt :language: cmake @@ -413,10 +511,14 @@ Now let's use the generated table. First, modify ``mysqrt.cxx`` to include :start-after: // a hack square root calculation using simple operations Run **cmake** or **cmake-gui** to configure the project and then build it -with your chosen build tool. When this project is built it will first build -the ``MakeTable`` executable. It will then run ``MakeTable`` to produce -``Table.h``. Finally, it will compile ``mysqrt.cxx`` which includes -``Table.h`` to produce the MathFunctions library. +with your chosen build tool. + +When this project is built it will first build the ``MakeTable`` executable. +It will then run ``MakeTable`` to produce ``Table.h``. Finally, it will +compile ``mysqrt.cxx`` which includes ``Table.h`` to produce the MathFunctions +library. + +Run the Tutorial executable and verify that it is using the table. Building an Installer (Step 7) ============================== @@ -439,38 +541,46 @@ That is all there is to it. We start by including ``InstallRequiredSystemLibraries``. This module will include any runtime libraries that are needed by the project for the current platform. Next we set some CPack variables to where we have stored the license and version -information for this project. The version information makes use of the -variables we set earlier in this tutorial. Finally we include the CPack -module which will use these variables and some other properties of the system -you are on to setup an installer. +information for this project. The version information was set earlier in this +tutorial and the ``license.txt`` has been included in the top-level source +directory for this step. + +Finally we include the CPack module which will use these variables and some +other properties of the current system to setup an installer. The next step is to build the project in the usual manner and then run -CPack on it. To build a binary distribution you would run: +CPack on it. To build a binary distribution, from the binary directory run: .. code-block:: console cpack +To specify the generator, use the ``-G`` option. For multi-config builds, use +``-C`` to specify the configuration. For example: + +.. code-block:: console + + cpack -G ZIP -C Debug + To create a source distribution you would type: .. code-block:: console - cpack -C CPackSourceConfig.cmake + cpack --config CPackSourceConfig.cmake Alternatively, run ``make package`` or right click the ``Package`` target and ``Build Project`` from an IDE. -Run the installer executable found in the binary directory. Then run the +Run the installer found in the binary directory. Then run the installed executable and verify that it works. Adding Support for a Dashboard (Step 8) ======================================= Adding support for submitting our test results to a dashboard is very easy. We -already defined a number of tests for our project in the earlier steps of this -tutorial. We just have to run those tests and submit them to a dashboard. To -include support for dashboards we include the CTest module in our top-level -``CMakeLists.txt``. +already defined a number of tests for our project in `Testing Support`_. Now we +just have to run those tests and submit them to a dashboard. To include support +for dashboards we include the CTest module in our top-level ``CMakeLists.txt``. Replace: @@ -489,21 +599,25 @@ With: The CTest module will automatically call ``enable_testing()``, so we can remove it from our CMake files. -We will also need to create a ``CTestConfig.cmake`` file where we can specify -the name of the project and where to submit the dashboard. +We will also need to create a ``CTestConfig.cmake`` file in the top-level +directory where we can specify the name of the project and where to submit the +dashboard. .. literalinclude:: Step9/CTestConfig.cmake :language: cmake CTest will read in this file when it runs. To create a simple dashboard you can run **cmake** or **cmake-gui** to configure the project, but do not build it -yet. Instead, change directory to the binary tree, and then run: +yet. Instead, change directory to the binary tree, and then run:: -.. code-block:: console + ctest [-VV] –D Experimental + +Remember, for multi-config generators (e.g. Visual Studio), the configuration +type must be specified:: - 'ctest [-VV] –D Experimental' + ctest [-VV] -C Debug –D Experimental -On Windows, build the EXPERIMENTAL target. +Or, from an IDE, build the ``Experimental`` target. Ctest will build and test the project and submit the results to the Kitware public dashboard. The results of your dashboard will be uploaded to Kitware's @@ -531,7 +645,6 @@ The first step is to update the starting section of the top-level .. literalinclude:: Step10/CMakeLists.txt :language: cmake - :start-after: set(Tutorial_VERSION_MINOR :end-before: # add the binary tree Now that we have made MathFunctions always be used, we will need to update @@ -544,7 +657,7 @@ The end result is that ``MathFunctions/CMakeLists.txt`` should look like: .. literalinclude:: Step10/MathFunctions/CMakeLists.txt :language: cmake - :lines: 1-40,46- + :lines: 1-36,42- Next, update ``MathFunctions/mysqrt.cxx`` to use the ``mathfunctions`` and ``detail`` namespaces: @@ -557,6 +670,7 @@ uses ``USE_MYMATH``: #. Always include ``MathFunctions.h`` #. Always use ``mathfunctions::sqrt`` +#. Don't include cmath Finally, update ``MathFunctions/MathFunctions.h`` to use dll export defines: @@ -569,9 +683,14 @@ library that has position enabled code. The solution to this is to explicitly set the ``POSITION_INDEPENDENT_CODE`` target property of SqrtLibrary to be True no matter the build type. +.. literalinclude:: Step10/MathFunctions/CMakeLists.txt + :language: cmake + :lines: 37-42 + **Exercise**: We modified ``MathFunctions.h`` to use dll export defines. Using CMake documentation can you find a helper module to simplify this? + Adding Generator Expressions (Step 10) ====================================== @@ -609,14 +728,14 @@ So the following code: .. literalinclude:: Step10/CMakeLists.txt :language: cmake - :start-after: project(Tutorial) - :end-before: # Set the version number + :start-after: project(Tutorial VERSION 1.0) + :end-before: # control where the static and shared libraries are built so that on windows Would be replaced with: .. literalinclude:: Step11/CMakeLists.txt :language: cmake - :start-after: project(Tutorial) + :start-after: project(Tutorial VERSION 1.0) :end-before: # add compiler warning flags just when building this project via @@ -629,7 +748,7 @@ below: .. literalinclude:: Step11/CMakeLists.txt :language: cmake :start-after: # the BUILD_INTERFACE genex - :end-before: # set the version number + :end-before: # control where the static and shared libraries are built so that on windows Looking at this we see that the warning flags are encapsulated inside a ``BUILD_INTERFACE`` condition. This is done so that consumers of our installed diff --git a/Help/index.rst b/Help/index.rst index cf1d2f1..cc6cee6 100644 --- a/Help/index.rst +++ b/Help/index.rst @@ -44,13 +44,15 @@ Reference Manuals /manual/cmake-variables.7 /manual/cpack-generators.7 -Guides -###### +.. only:: not man -.. toctree:: - :maxdepth: 1 + Guides + ###### + + .. toctree:: + :maxdepth: 1 - /guide/tutorial/index + /guide/tutorial/index .. only:: html or text diff --git a/Help/manual/OPTIONS_BUILD.txt b/Help/manual/OPTIONS_BUILD.txt index 810aaa9..0947e41 100644 --- a/Help/manual/OPTIONS_BUILD.txt +++ b/Help/manual/OPTIONS_BUILD.txt @@ -18,6 +18,9 @@ containing :command:`set` commands that use the ``CACHE`` option, not a cache-format file. + References to :variable:`CMAKE_SOURCE_DIR` and :variable:`CMAKE_BINARY_DIR` + within the script evaluate to the top-level source and build tree. + ``-D <var>:<type>=<value>, -D <var>=<value>`` Create or update a CMake ``CACHE`` entry. diff --git a/Help/manual/cmake-commands.7.rst b/Help/manual/cmake-commands.7.rst index a3bc465..59ba897 100644 --- a/Help/manual/cmake-commands.7.rst +++ b/Help/manual/cmake-commands.7.rst @@ -112,6 +112,7 @@ These commands are available only in CMake projects. /command/target_link_directories /command/target_link_libraries /command/target_link_options + /command/target_precompile_headers /command/target_sources /command/try_compile /command/try_run diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 62d23c7..25d6b24 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -181,6 +181,7 @@ Properties on Targets /prop_tgt/DEFINE_SYMBOL /prop_tgt/DEPLOYMENT_REMOTE_DIRECTORY /prop_tgt/DEPLOYMENT_ADDITIONAL_FILES + /prop_tgt/DISABLE_PRECOMPILE_HEADERS /prop_tgt/DOTNET_TARGET_FRAMEWORK_VERSION /prop_tgt/EchoString /prop_tgt/ENABLE_EXPORTS @@ -240,6 +241,7 @@ Properties on Targets /prop_tgt/INTERFACE_LINK_DIRECTORIES /prop_tgt/INTERFACE_LINK_LIBRARIES /prop_tgt/INTERFACE_LINK_OPTIONS + /prop_tgt/INTERFACE_PRECOMPILE_HEADERS /prop_tgt/INTERFACE_POSITION_INDEPENDENT_CODE /prop_tgt/INTERFACE_SOURCES /prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES @@ -295,6 +297,7 @@ Properties on Targets /prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG /prop_tgt/PDB_OUTPUT_DIRECTORY /prop_tgt/POSITION_INDEPENDENT_CODE + /prop_tgt/PRECOMPILE_HEADERS /prop_tgt/PREFIX /prop_tgt/PRIVATE_HEADER /prop_tgt/PROJECT_LABEL @@ -316,6 +319,7 @@ Properties on Targets /prop_tgt/STATIC_LIBRARY_OPTIONS /prop_tgt/SUFFIX /prop_tgt/Swift_DEPENDENCIES_FILE + /prop_tgt/Swift_LANGUAGE_VERSION /prop_tgt/Swift_MODULE_DIRECTORY /prop_tgt/Swift_MODULE_NAME /prop_tgt/TYPE @@ -445,6 +449,7 @@ Properties on Source Files /prop_sf/SKIP_AUTOMOC /prop_sf/SKIP_AUTORCC /prop_sf/SKIP_AUTOUIC + /prop_sf/SKIP_PRECOMPILE_HEADERS /prop_sf/Swift_DEPENDENCIES_FILE /prop_sf/Swift_DIAGNOSTICS_FILE /prop_sf/SYMBOLIC diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 9ad1195..0ae1ebe 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -62,6 +62,7 @@ Variables that Provide Information /variable/CMAKE_JOB_POOLS /variable/CMAKE_LANG_COMPILER_AR /variable/CMAKE_LANG_COMPILER_RANLIB + /variable/CMAKE_LANG_LINK_LIBRARY_SUFFIX /variable/CMAKE_LINK_LIBRARY_SUFFIX /variable/CMAKE_LINK_SEARCH_END_STATIC /variable/CMAKE_LINK_SEARCH_START_STATIC @@ -355,6 +356,7 @@ Variables that Control the Build /variable/CMAKE_CUDA_SEPARABLE_COMPILATION /variable/CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS /variable/CMAKE_DEBUG_POSTFIX + /variable/CMAKE_DISABLE_PRECOMPILE_HEADERS /variable/CMAKE_ENABLE_EXPORTS /variable/CMAKE_EXE_LINKER_FLAGS /variable/CMAKE_EXE_LINKER_FLAGS_CONFIG @@ -384,6 +386,7 @@ Variables that Control the Build /variable/CMAKE_LANG_CPPCHECK /variable/CMAKE_LANG_CPPLINT /variable/CMAKE_LANG_INCLUDE_WHAT_YOU_USE + /variable/CMAKE_LANG_LINK_LIBRARY_FILE_FLAG /variable/CMAKE_LANG_LINK_LIBRARY_FLAG /variable/CMAKE_LANG_VISIBILITY_PRESET /variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 68d88e7..26ef904 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -238,6 +238,9 @@ Options Multiple options are allowed. +``--trace-redirect=<file>`` + Put cmake in trace mode and redirect trace output to a file instead of stderr. + ``--warn-uninitialized`` Warn about uninitialized values. diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index c6b1425..9d93bb8 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -482,14 +482,17 @@ a `CDash`_ server. The command-line signature used to submit to `CDash`_ is:: Options for Dashboard Client include: -``--track <track>`` - Specify the track to submit dashboard to +``--group <group>`` + Specify what group you'd like to submit results to - Submit dashboard to specified track instead of default one. By + Submit dashboard to specified group instead of default one. By default, the dashboard is submitted to Nightly, Experimental, or - Continuous track, but by specifying this option, the track can be + Continuous group, but by specifying this option, the group can be arbitrary. + This replaces the deprecated option ``--track``. + Despite the name change its behavior is unchanged. + ``-A <file>, --add-notes <file>`` Add a notes file with submission. diff --git a/Help/prop_sf/SKIP_PRECOMPILE_HEADERS.rst b/Help/prop_sf/SKIP_PRECOMPILE_HEADERS.rst new file mode 100644 index 0000000..5f39f30 --- /dev/null +++ b/Help/prop_sf/SKIP_PRECOMPILE_HEADERS.rst @@ -0,0 +1,13 @@ +SKIP_PRECOMPILE_HEADERS +----------------------- + +Is this source file skipped by :prop_tgt:`PRECOMPILE_HEADERS` feature. + +This property helps with build problems that one would run into +when using the :prop_tgt:`PRECOMPILE_HEADERS` feature. + +One example would be the usage of Objective-C (*.m) files, and +Objective-C++ (*.mm) files, which lead to compilation failure +because they are treated (in case of Ninja / Makefile generator) +as C, and CXX respectively. The precompile headers are not +compatible between languages. diff --git a/Help/prop_tgt/DISABLE_PRECOMPILE_HEADERS.rst b/Help/prop_tgt/DISABLE_PRECOMPILE_HEADERS.rst new file mode 100644 index 0000000..4cef023 --- /dev/null +++ b/Help/prop_tgt/DISABLE_PRECOMPILE_HEADERS.rst @@ -0,0 +1,8 @@ +DISABLE_PRECOMPILE_HEADERS +-------------------------- + +Disables the precompilation of header files specified by +:prop_tgt:`PRECOMPILE_HEADERS` property. + +If the property is not set, CMake will use the value provided +by :variable:`CMAKE_DISABLE_PRECOMPILE_HEADERS`. diff --git a/Help/prop_tgt/INTERFACE_PRECOMPILE_HEADERS.rst b/Help/prop_tgt/INTERFACE_PRECOMPILE_HEADERS.rst new file mode 100644 index 0000000..8ff7e8b --- /dev/null +++ b/Help/prop_tgt/INTERFACE_PRECOMPILE_HEADERS.rst @@ -0,0 +1,14 @@ +INTERFACE_PRECOMPILE_HEADERS +---------------------------- + +List of interface header files to precompile into consuming targets. + +Targets may populate this property to publish the header files +for consuming targets to precompile. The :command:`target_precompile_headers` +command populates this property with values given to the ``PUBLIC`` and +``INTERFACE`` keywords. Projects may also get and set the property directly. + +Contents of ``INTERFACE_PRECOMPILE_HEADERS`` may use "generator expressions" +with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` +manual for available expressions. See the :manual:`cmake-buildsystem(7)` +manual for more on defining buildsystem properties. diff --git a/Help/prop_tgt/PRECOMPILE_HEADERS.rst b/Help/prop_tgt/PRECOMPILE_HEADERS.rst new file mode 100644 index 0000000..9e70b65 --- /dev/null +++ b/Help/prop_tgt/PRECOMPILE_HEADERS.rst @@ -0,0 +1,12 @@ +PRECOMPILE_HEADERS +------------------ + +List of header files to precompile. + +This property holds a :ref:`semicolon-separated list <CMake Language Lists>` +of header files to precompile specified so far for its target. +Use the :command:`target_precompile_headers` command to append more header +files. + +This property supports +:manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/prop_tgt/Swift_LANGUAGE_VERSION.rst b/Help/prop_tgt/Swift_LANGUAGE_VERSION.rst new file mode 100644 index 0000000..7579447 --- /dev/null +++ b/Help/prop_tgt/Swift_LANGUAGE_VERSION.rst @@ -0,0 +1,6 @@ +Swift_LANGUAGE_VERSION +---------------------- + +This property sets the language version for the Swift sources in the target. If +one is not specified, it will default to ``<CMAKE_Swift_LANGUAGE_VERSION>`` if +specified, otherwise it is the latest version supported by the compiler. diff --git a/Help/prop_tgt/VS_CONFIGURATION_TYPE.rst b/Help/prop_tgt/VS_CONFIGURATION_TYPE.rst index ff987ff..640bed5 100644 --- a/Help/prop_tgt/VS_CONFIGURATION_TYPE.rst +++ b/Help/prop_tgt/VS_CONFIGURATION_TYPE.rst @@ -4,6 +4,8 @@ VS_CONFIGURATION_TYPE Visual Studio project configuration type. Sets the ``ConfigurationType`` attribute for a generated Visual Studio project. +The property value may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. If this property is set, it overrides the default setting that is based on the target type (e.g. ``StaticLibrary``, ``Application``, ...). diff --git a/Help/release/3.15.rst b/Help/release/3.15.rst index b0365ba..48f3aa4 100644 --- a/Help/release/3.15.rst +++ b/Help/release/3.15.rst @@ -369,3 +369,10 @@ Changes made since CMake 3.15.0 include the following. * In CMake 3.15.0 and 3.15.1 the :variable:`CMAKE_FIND_PACKAGE_PREFER_CONFIG` variable caused the :command:`find_package` command to fail on a missing package even without the ``REQUIRED`` option. This has been fixed. + +3.15.3 +------ + +* ``CrayPrgEnv`` compiler wrapper support has been updated for the 19.06 + release of the Cray Programming Environment for which the default linking + mode on XC Cray systems is now dynamic instead of static. diff --git a/Help/release/dev/cmake-initial-cache-dirs.rst b/Help/release/dev/cmake-initial-cache-dirs.rst new file mode 100644 index 0000000..be91902 --- /dev/null +++ b/Help/release/dev/cmake-initial-cache-dirs.rst @@ -0,0 +1,6 @@ +cmake-initial-cache-dirs +------------------------ + +* The :manual:`cmake(1)` ``-C <initial-cache>`` option now evaluates the + initial cache script with :variable:`CMAKE_SOURCE_DIR` and + :variable:`CMAKE_BINARY_DIR` set to the top-level source and build trees. diff --git a/Help/release/dev/per-lang-link-library-flag.rst b/Help/release/dev/per-lang-link-library-flag.rst index ca1181d..4f5966d 100644 --- a/Help/release/dev/per-lang-link-library-flag.rst +++ b/Help/release/dev/per-lang-link-library-flag.rst @@ -1,7 +1,9 @@ per-lang-link-library-flag -------------------------- -* The new :variable:`CMAKE_<LANG>_LINK_LIBRARY_FLAG` flag allows you to now - control the flag used to specify linking to a library on a per-language basis. - This is useful for mixed-language projects where the different drivers may use - different flags. +* New variables :variable:`CMAKE_<LANG>_LINK_LIBRARY_FLAG`, + :variable:`CMAKE_<LANG>_LINK_LIBRARY_FILE_FLAG`, and + :variable:`CMAKE_<LANG>_LINK_LIBRARY_SUFFIX` allow control of the + flag used to specify linking to a library on a per-language basis. + This is useful for mixed-language projects where the different + drivers may use different flags. diff --git a/Help/release/dev/precompile-headers.rst b/Help/release/dev/precompile-headers.rst new file mode 100644 index 0000000..8b62da7 --- /dev/null +++ b/Help/release/dev/precompile-headers.rst @@ -0,0 +1,6 @@ +Precompile Headers +------------------ + +* The :prop_tgt:`PRECOMPILE_HEADERS` target property was added to tell + generators to use a list of precompile headers for faster compilation + times. diff --git a/Help/release/dev/trace-redirect.rst b/Help/release/dev/trace-redirect.rst new file mode 100644 index 0000000..410021e --- /dev/null +++ b/Help/release/dev/trace-redirect.rst @@ -0,0 +1,6 @@ +trace-redirect +-------------- + +* :manual:`cmake(1)` gained a ``--trace-redirect=<file>`` command line option + that can be used to redirect ``--trace`` output to a file instead + of ``stderr``. diff --git a/Help/release/dev/vs-configuration-type-genex.rst b/Help/release/dev/vs-configuration-type-genex.rst new file mode 100644 index 0000000..d930d5b --- /dev/null +++ b/Help/release/dev/vs-configuration-type-genex.rst @@ -0,0 +1,5 @@ +vs-configuration-type-genex +--------------------------- + +* :prop_tgt:`VS_CONFIGURATION_TYPE` now supports + :manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/variable/CMAKE_DISABLE_PRECOMPILE_HEADERS.rst b/Help/variable/CMAKE_DISABLE_PRECOMPILE_HEADERS.rst new file mode 100644 index 0000000..7c30ede --- /dev/null +++ b/Help/variable/CMAKE_DISABLE_PRECOMPILE_HEADERS.rst @@ -0,0 +1,6 @@ +CMAKE_DISABLE_PRECOMPILE_HEADERS +-------------------------------- + +Default value for :prop_tgt:`DISABLE_PRECOMPILE_HEADERS` of targets. + +By default ``CMAKE_DISABLE_PRECOMPILE_HEADERS`` is ``OFF``. diff --git a/Help/variable/CMAKE_LANG_LINK_LIBRARY_FILE_FLAG.rst b/Help/variable/CMAKE_LANG_LINK_LIBRARY_FILE_FLAG.rst new file mode 100644 index 0000000..d54f080 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_LIBRARY_FILE_FLAG.rst @@ -0,0 +1,8 @@ +CMAKE_<LANG>_LINK_LIBRARY_FILE_FLAG +----------------------------------- + +Language-specific flag to be used to link a library specified by +a path to its file. + +The flag will be used before a library file path is given to the +linker. This is needed only on very few platforms. diff --git a/Help/variable/CMAKE_LANG_LINK_LIBRARY_SUFFIX.rst b/Help/variable/CMAKE_LANG_LINK_LIBRARY_SUFFIX.rst new file mode 100644 index 0000000..a378657 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_LIBRARY_SUFFIX.rst @@ -0,0 +1,6 @@ +CMAKE_<LANG>_LINK_LIBRARY_SUFFIX +-------------------------------- + +Language-specific suffix for libraries that you link to. + +The suffix to use for the end of a library filename, ``.lib`` on Windows. |