diff options
Diffstat (limited to 'Help')
145 files changed, 1551 insertions, 659 deletions
diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index bd55e24..21236fa 100644 --- a/Help/command/FIND_XXX.txt +++ b/Help/command/FIND_XXX.txt @@ -140,21 +140,40 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: |prefix_XXX_SUBDIR| for each ``<prefix>`` in :variable:`CMAKE_SYSTEM_PREFIX_PATH` -1. .. versionadded:: 3.12 - If called from within a find module or any other script loaded by a call to - :command:`find_package(<PackageName>)`, search prefixes unique to the - current package being found. Specifically, look in the - :variable:`<PackageName>_ROOT` CMake variable and the - :envvar:`<PackageName>_ROOT` environment variable. - The package root variables are maintained as a stack, so if called from - nested find modules or config packages, root paths from the parent's find - module or config package will be searched after paths from the current - module or package. In other words, the search order would be - ``<CurrentPackage>_ROOT``, ``ENV{<CurrentPackage>_ROOT}``, - ``<ParentPackage>_ROOT``, ``ENV{<ParentPackage>_ROOT}``, etc. - This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed or by setting - the :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` to ``FALSE``. - See policy :policy:`CMP0074`. +1. If called from within a find module or any other script loaded by a call to + :command:`find_package(<PackageName>)`, search prefixes unique to the + current package being found. See policy :policy:`CMP0074`. + + .. versionadded:: 3.12 + + Specifically, search paths specified by the following variables, in order: + + a. :variable:`<PackageName>_ROOT` CMake variable, + where ``<PackageName>`` is the case-preserved package name. + + b. :variable:`<PACKAGENAME>_ROOT` CMake variable, + where ``<PACKAGENAME>`` is the upper-cased package name. + See policy :policy:`CMP0144`. + + .. versionadded:: 3.27 + + c. :envvar:`<PackageName>_ROOT` environment variable, + where ``<PackageName>`` is the case-preserved package name. + + d. :envvar:`<PACKAGENAME>_ROOT` environment variable, + where ``<PACKAGENAME>`` is the upper-cased package name. + See policy :policy:`CMP0144`. + + .. versionadded:: 3.27 + + The package root variables are maintained as a stack, so if called from + nested find modules or config packages, root paths from the parent's find + module or config package will be searched after paths from the current + module or package. In other words, the search order would be + ``<CurrentPackage>_ROOT``, ``ENV{<CurrentPackage>_ROOT}``, + ``<ParentPackage>_ROOT``, ``ENV{<ParentPackage>_ROOT}``, etc. + This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed or by setting + the :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` to ``FALSE``. * |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index 293d3f0..1ccd434 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -25,7 +25,8 @@ The first signature is for adding a custom command to produce an output: [DEPFILE depfile] [JOB_POOL job_pool] [VERBATIM] [APPEND] [USES_TERMINAL] - [COMMAND_EXPAND_LISTS]) + [COMMAND_EXPAND_LISTS] + [DEPENDS_EXPLICIT_ONLY]) This defines a command to generate specified ``OUTPUT`` file(s). A target created in the same directory (``CMakeLists.txt`` file) @@ -357,6 +358,24 @@ The options are: :ref:`Makefile Generators`, :ref:`Visual Studio Generators`, and the :generator:`Xcode` generator. +``DEPENDS_EXPLICIT_ONLY`` + + .. versionadded:: 3.27 + + Indicate that the command's ``DEPENDS`` argument represents all files + required by the command and implicit dependencies are not required. + + Without this option, if any target uses the output of the custom command, + CMake will consider that target's dependencies as implicit dependencies for + the custom command in case this custom command requires files implicitly + created by those targets. + + This option can be enabled on all custom commands by setting + :variable:`CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY` to ``ON``. + + Only the :ref:`Ninja Generators` actually use this information to remove + unnecessary implicit dependencies. + Examples: Generating Files ^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Help/command/add_test.rst b/Help/command/add_test.rst index 53555a4..02dd3986 100644 --- a/Help/command/add_test.rst +++ b/Help/command/add_test.rst @@ -12,13 +12,24 @@ Add a test to the project to be run by :manual:`ctest(1)`. Adds a test called ``<name>``. The test name may contain arbitrary characters, expressed as a :ref:`Quoted Argument` or :ref:`Bracket Argument` -if necessary. See policy :policy:`CMP0110`. The options are: +if necessary. See policy :policy:`CMP0110`. + +CMake only generates tests if the :command:`enable_testing` command has been +invoked. The :module:`CTest` module invokes ``enable_testing`` automatically +unless ``BUILD_TESTING`` is set to ``OFF``. + +Tests added with the ``add_test(NAME)`` signature support using +:manual:`generator expressions <cmake-generator-expressions(7)>` +in test properties set by :command:`set_property(TEST)` or +:command:`set_tests_properties`. Test properties may only be set in the +directory the test is created in. + +``add_test`` options are: ``COMMAND`` - Specify the test command-line. If ``<command>`` specifies an - executable target (created by :command:`add_executable`) it will - automatically be replaced by the location of the executable created - at build time. + Specify the test command-line. If ``<command>`` specifies an executable + target created by :command:`add_executable`, it will automatically be + replaced by the location of the executable created at build time. The command may be specified using :manual:`generator expressions <cmake-generator-expressions(7)>`. @@ -27,38 +38,29 @@ if necessary. See policy :policy:`CMP0110`. The options are: Restrict execution of the test only to the named configurations. ``WORKING_DIRECTORY`` - Set the :prop_test:`WORKING_DIRECTORY` test property to - specify the working directory in which to execute the test. - If not specified the test will be run with the current working - directory set to the build directory corresponding to the - current source directory. - - The working directory may be specified using - :manual:`generator expressions <cmake-generator-expressions(7)>`. + Set the test property :prop_test:`WORKING_DIRECTORY` in which to execute the + test. If not specified, the test will be run in + :variable:`CMAKE_CURRENT_BINARY_DIR`. The working directory may be specified + using :manual:`generator expressions <cmake-generator-expressions(7)>`. ``COMMAND_EXPAND_LISTS`` .. versionadded:: 3.16 - Lists in ``COMMAND`` arguments will be expanded, including those - created with + Lists in ``COMMAND`` arguments will be expanded, including those created with :manual:`generator expressions <cmake-generator-expressions(7)>`. -The given test command is expected to exit with code ``0`` to pass and -non-zero to fail, or vice-versa if the :prop_test:`WILL_FAIL` test -property is set. Any output written to stdout or stderr will be -captured by :manual:`ctest(1)` but does not affect the pass/fail status -unless the :prop_test:`PASS_REGULAR_EXPRESSION`, -:prop_test:`FAIL_REGULAR_EXPRESSION` or -:prop_test:`SKIP_REGULAR_EXPRESSION` test property is used. +If the test command exits with code ``0`` the test passes. Non-zero exit code +is a "failed" test. The test property :prop_test:`WILL_FAIL` inverts this +logic. Note that system-level test failures such as segmentation faults or +heap errors will still fail the test even if ``WILL_FALL`` is true. Output +written to stdout or stderr is captured by :manual:`ctest(1)` and only +affects the pass/fail status via the :prop_test:`PASS_REGULAR_EXPRESSION`, +:prop_test:`FAIL_REGULAR_EXPRESSION`, or :prop_test:`SKIP_REGULAR_EXPRESSION` +test properties. .. versionadded:: 3.16 Added :prop_test:`SKIP_REGULAR_EXPRESSION` property. -Tests added with the ``add_test(NAME)`` signature support using -:manual:`generator expressions <cmake-generator-expressions(7)>` -in test properties set by :command:`set_property(TEST)` or -:command:`set_tests_properties`. - Example usage: .. code-block:: cmake @@ -71,16 +73,9 @@ This creates a test ``mytest`` whose command runs a ``testDriver`` tool passing the configuration name and the full path to the executable file produced by target ``myexe``. -.. note:: - - CMake will generate tests only if the :command:`enable_testing` - command has been invoked. The :module:`CTest` module invokes the - command automatically unless the ``BUILD_TESTING`` option is turned - ``OFF``. - --------------------------------------------------------------------- -This command also supports a simpler, but less flexible, signature: +The command syntax above is recommended over the older, less flexible form: .. code-block:: cmake diff --git a/Help/command/file.rst b/Help/command/file.rst index df895d0..6ab7421 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -1077,7 +1077,14 @@ Options to both ``DOWNLOAD`` and ``UPLOAD`` are: ``HTTPHEADER <HTTP-header>`` .. versionadded:: 3.7 - HTTP header for operation. Suboption can be repeated several times. + HTTP header for ``DOWNLOAD`` and ``UPLOAD`` operations. ``HTTPHEADER`` can be + repeated for multiple options: + + .. code-block:: cmake + + file(DOWNLOAD <url> + HTTPHEADER "Authorization: Bearer <auth-token>" + HTTPHEADER "UserAgent: Mozilla/5.0") ``NETRC <level>`` .. versionadded:: 3.11 diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index de4cb88..b82088e 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -367,17 +367,37 @@ The set of installation prefixes is constructed using the following steps. If ``NO_DEFAULT_PATH`` is specified all ``NO_*`` options are enabled. -1. .. versionadded:: 3.12 - Search paths specified in the :variable:`<PackageName>_ROOT` CMake - variable and the :envvar:`<PackageName>_ROOT` environment variable, - where ``<PackageName>`` is the package to be found - (the case-preserved first argument to ``find_package``). - The package root variables are maintained as a stack so if - called from within a find module, root paths from the parent's find - module will also be searched after paths for the current package. - This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed or by setting - the :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` to ``FALSE``. - See policy :policy:`CMP0074`. +1. Search prefixes unique to the current ``<PackageName>`` being found. + See policy :policy:`CMP0074`. + + .. versionadded:: 3.12 + + Specifically, search prefixes specified by the following variables, + in order: + + a. :variable:`<PackageName>_ROOT` CMake variable, + where ``<PackageName>`` is the case-preserved package name. + + b. :variable:`<PACKAGENAME>_ROOT` CMake variable, + where ``<PACKAGENAME>`` is the upper-cased package name. + See policy :policy:`CMP0144`. + + .. versionadded:: 3.27 + + c. :envvar:`<PackageName>_ROOT` environment variable, + where ``<PackageName>`` is the case-preserved package name. + + d. :envvar:`<PACKAGENAME>_ROOT` environment variable, + where ``<PACKAGENAME>`` is the upper-cased package name. + See policy :policy:`CMP0144`. + + .. versionadded:: 3.27 + + The package root variables are maintained as a stack so if + called from within a find module, root paths from the parent's find + module will also be searched after paths for the current package. + This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed or by setting + the :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` to ``FALSE``. 2. Search paths specified in cmake-specific cache variables. These are intended to be used on the command line with a :option:`-DVAR=VALUE <cmake -D>`. diff --git a/Help/command/install.rst b/Help/command/install.rst index 126888a..d5092ae 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -158,6 +158,9 @@ that may be installed: ``.lib``, in contrast to the ``.dll`` libraries that go to ``RUNTIME``); * On AIX, the *linker import file* created for executables with :prop_tgt:`ENABLE_EXPORTS` enabled. + * On macOS, the *linker import file* created for shared libraries with + :prop_tgt:`ENABLE_EXPORTS` enabled (except when marked as ``FRAMEWORK``, + see below). ``LIBRARY`` Target artifacts of this kind include: @@ -308,6 +311,11 @@ the following additional arguments: value of ``COMPONENT``. It is an error to use this parameter outside of a ``LIBRARY`` block. + .. versionchanged:: 3.27 + This parameter is also usable for an ``ARCHIVE`` block to manage + the linker import file created, on macOS, for shared libraries with + :prop_tgt:`ENABLE_EXPORTS` enabled. + Consider the following example: .. code-block:: cmake @@ -342,6 +350,11 @@ the following additional arguments: option installs nothing. It is an error to use this parameter outside of a ``LIBRARY`` block. + .. versionchanged:: 3.27 + This parameter is also usable for an ``ARCHIVE`` block to manage + the linker import file created, on macOS, for shared libraries with + :prop_tgt:`ENABLE_EXPORTS` enabled. + When ``NAMELINK_ONLY`` is given, either ``NAMELINK_COMPONENT`` or ``COMPONENT`` may be used to specify the installation component of the namelink, but ``COMPONENT`` should generally be preferred. @@ -355,6 +368,11 @@ the following additional arguments: installs the library. It is an error to use this parameter outside of a ``LIBRARY`` block. + .. versionchanged:: 3.27 + This parameter is also usable for an ``ARCHIVE`` block to manage + the linker import file created, on macOS, for shared libraries with + :prop_tgt:`ENABLE_EXPORTS` enabled. + If ``NAMELINK_SKIP`` is specified, ``NAMELINK_COMPONENT`` has no effect. It is not recommended to use ``NAMELINK_SKIP`` in conjunction with ``NAMELINK_COMPONENT``. diff --git a/Help/command/math.rst b/Help/command/math.rst index 8386aab..6989ebc 100644 --- a/Help/command/math.rst +++ b/Help/command/math.rst @@ -9,7 +9,8 @@ Evaluate a mathematical expression. Evaluates a mathematical ``<expression>`` and sets ``<variable>`` to the resulting value. The result of the expression must be representable as a -64-bit signed integer. +64-bit signed integer. Floating point inputs are invalid e.g. ``1.1 * 10``. +Non-integer results e.g. ``3 / 2`` are truncated. The mathematical expression must be given as a string (i.e. enclosed in double quotation marks). An example is ``"5 * (10 + 13)"``. diff --git a/Help/command/separate_arguments.rst b/Help/command/separate_arguments.rst index f66af35..4f0b25e 100644 --- a/Help/command/separate_arguments.rst +++ b/Help/command/separate_arguments.rst @@ -69,7 +69,7 @@ be one of the following keywords: The contents of ``out`` will be: ``/path/to/cc;-c;main.c`` -.. _`Parsing C Command-Line Arguments`: https://msdn.microsoft.com/library/a1y7w461.aspx +.. _`Parsing C Command-Line Arguments`: https://learn.microsoft.com/en-us/cpp/c-language/parsing-c-command-line-arguments .. code-block:: cmake diff --git a/Help/command/set_property.rst b/Help/command/set_property.rst index d446a2d..8dd4b94 100644 --- a/Help/command/set_property.rst +++ b/Help/command/set_property.rst @@ -82,15 +82,15 @@ It must be one of the following: to the installation prefix. ``TEST`` - Scope may name zero or more existing tests. - See also the :command:`set_tests_properties` command. + Scope is limited to the directory the command is called in. It may name zero + or more existing tests. See also command :command:`set_tests_properties`. Test property values may be specified using :manual:`generator expressions <cmake-generator-expressions(7)>` for tests created by the :command:`add_test(NAME)` signature. ``CACHE`` - Scope must name zero or more cache existing entries. + Scope must name zero or more existing cache entries. The required ``PROPERTY`` option is immediately followed by the name of the property to set. Remaining arguments are used to compose the diff --git a/Help/cpack_gen/nuget.rst b/Help/cpack_gen/nuget.rst index 1f2e762..8ee2816 100644 --- a/Help/cpack_gen/nuget.rst +++ b/Help/cpack_gen/nuget.rst @@ -258,7 +258,7 @@ List of CPack NuGet generator specific variables: .. _nuget.org: https://www.nuget.org .. _version specification: https://learn.microsoft.com/en-us/nuget/concepts/package-versioning#version-ranges -.. _SPDX license identifier: https://spdx.github.io/spdx-spec/SPDX-license-list -.. _SPDX specification: https://spdx.github.io/spdx-spec/SPDX-license-expressions +.. _SPDX license identifier: https://spdx.org/licenses +.. _SPDX specification: https://spdx.github.io/spdx-spec/v2.3/SPDX-license-expressions .. NuGet spec docs https://docs.microsoft.com/en-us/nuget/reference/nuspec diff --git a/Help/cpack_gen/wix.rst b/Help/cpack_gen/wix.rst index c880049..af01252 100644 --- a/Help/cpack_gen/wix.rst +++ b/Help/cpack_gen/wix.rst @@ -111,7 +111,7 @@ Windows using WiX. simply provide the name of the culture. If you specify more than one culture identifier in a comma or semicolon delimited list, the first one that is found will be used. You can find a list of supported languages at: - https://wixtoolset.org//documentation/manual/v3/wixui/wixui_localization.html + https://wixtoolset.org/docs/v3/wixui/wixui_localization/ .. variable:: CPACK_WIX_TEMPLATE @@ -319,7 +319,7 @@ Windows using WiX. for using WiX extensions. Each declaration should be in the form name=url, where name is the plain namespace without the usual xmlns: prefix and url is an unquoted namespace url. A list of commonly known WiX schemata can be found here: - https://wixtoolset.org/documentation/manual/v3/xsd/ + https://wixtoolset.org/docs/v3/xsd/ .. variable:: CPACK_WIX_SKIP_WIX_UI_EXTENSION diff --git a/Help/envvar/PackageName_ROOT.rst b/Help/envvar/PackageName_ROOT.rst index fa8c385..6e9c744 100644 --- a/Help/envvar/PackageName_ROOT.rst +++ b/Help/envvar/PackageName_ROOT.rst @@ -17,3 +17,17 @@ by ``:`` on UNIX or ``;`` on Windows (the same as the ``PATH`` environment variable convention on those platforms). See also the :variable:`<PackageName>_ROOT` CMake variable. + +.. envvar:: <PACKAGENAME>_ROOT + + .. versionadded:: 3.27 + + Calls to :command:`find_package(<PackageName>)` will also search in + prefixes specified by the upper-case ``<PACKAGENAME>_ROOT`` environment + variable. See policy :policy:`CMP0144`. + +.. note:: + + Note that the ``<PackageName>_ROOT`` and ``<PACKAGENAME>_ROOT`` + environment variables are distinct only on platforms that have + case-sensitive environments. diff --git a/Help/generator/CodeBlocks.rst b/Help/generator/CodeBlocks.rst index 85da715..5c48bc9 100644 --- a/Help/generator/CodeBlocks.rst +++ b/Help/generator/CodeBlocks.rst @@ -1,6 +1,12 @@ CodeBlocks ---------- +.. deprecated:: 3.27 + + Support for :ref:`Extra Generators` is deprecated and will be removed from + a future version of CMake. IDEs may use the :manual:`cmake-file-api(7)` + to view CMake-generated project build trees. + Generates CodeBlocks project files. Project files for CodeBlocks will be created in the top directory and diff --git a/Help/generator/CodeLite.rst b/Help/generator/CodeLite.rst index 4f276df..faec9b9 100644 --- a/Help/generator/CodeLite.rst +++ b/Help/generator/CodeLite.rst @@ -1,6 +1,12 @@ CodeLite ---------- +.. deprecated:: 3.27 + + Support for :ref:`Extra Generators` is deprecated and will be removed from + a future version of CMake. IDEs may use the :manual:`cmake-file-api(7)` + to view CMake-generated project build trees. + Generates CodeLite project files. Project files for CodeLite will be created in the top directory and diff --git a/Help/generator/Eclipse CDT4.rst b/Help/generator/Eclipse CDT4.rst index 634e2b6..9c1610d 100644 --- a/Help/generator/Eclipse CDT4.rst +++ b/Help/generator/Eclipse CDT4.rst @@ -1,6 +1,12 @@ Eclipse CDT4 ------------ +.. deprecated:: 3.27 + + Support for :ref:`Extra Generators` is deprecated and will be removed from + a future version of CMake. IDEs may use the :manual:`cmake-file-api(7)` + to view CMake-generated project build trees. + Generates Eclipse CDT 4.0 project files. Project files for Eclipse will be created in the top directory. In diff --git a/Help/generator/Kate.rst b/Help/generator/Kate.rst index 129bf63..11354f2 100644 --- a/Help/generator/Kate.rst +++ b/Help/generator/Kate.rst @@ -1,6 +1,12 @@ Kate ---- +.. deprecated:: 3.27 + + Support for :ref:`Extra Generators` is deprecated and will be removed from + a future version of CMake. IDEs may use the :manual:`cmake-file-api(7)` + to view CMake-generated project build trees. + Generates Kate project files. A project file for Kate will be created in the top directory in the top level @@ -22,5 +28,8 @@ This "extra" generator may be specified as: ``Kate - Ninja`` Generate with :generator:`Ninja`. +``Kate - Ninja Multi-Config`` + Generate with :generator:`Ninja Multi-Config`. + ``Kate - Unix Makefiles`` Generate with :generator:`Unix Makefiles`. diff --git a/Help/generator/Sublime Text 2.rst b/Help/generator/Sublime Text 2.rst index 0a07ea9..a45ab08 100644 --- a/Help/generator/Sublime Text 2.rst +++ b/Help/generator/Sublime Text 2.rst @@ -1,6 +1,12 @@ Sublime Text 2 -------------- +.. deprecated:: 3.27 + + Support for :ref:`Extra Generators` is deprecated and will be removed from + a future version of CMake. IDEs may use the :manual:`cmake-file-api(7)` + to view CMake-generated project build trees. + Generates Sublime Text 2 project files. Project files for Sublime Text 2 will be created in the top directory diff --git a/Help/generator/Visual Studio 9 2008.rst b/Help/generator/Visual Studio 9 2008.rst index 3434956..816969d 100644 --- a/Help/generator/Visual Studio 9 2008.rst +++ b/Help/generator/Visual Studio 9 2008.rst @@ -1,7 +1,15 @@ Visual Studio 9 2008 -------------------- -Generates Visual Studio 9 2008 project files. +Deprecated. Generates Visual Studio 9 2008 project files. + +.. note:: + This generator is deprecated and will be removed in a future version + of CMake. It will still be possible to build with VS 9 2008 tools + using the :generator:`Visual Studio 12 2013` generator (or above, + and with VS 10 2010 also installed) with + :variable:`CMAKE_GENERATOR_TOOLSET` set to ``v90``, + or by using the :generator:`NMake Makefiles` generator. Platform Selection ^^^^^^^^^^^^^^^^^^ diff --git a/Help/guide/ide-integration/index.rst b/Help/guide/ide-integration/index.rst index e198789..3a11a34 100644 --- a/Help/guide/ide-integration/index.rst +++ b/Help/guide/ide-integration/index.rst @@ -145,7 +145,7 @@ The following IDEs support CMake natively: * `VSCode`_ (via a plugin) .. _CLion: https://www.jetbrains.com/clion/ -.. _KDevelop: https://www.kdevelop.org/ +.. _KDevelop: https://kdevelop.org/ .. _QtCreator: https://www.qt.io/product/development-tools .. _Vim: https://www.vim.org/ .. _Visual Studio: https://visualstudio.microsoft.com/ diff --git a/Help/guide/tutorial/A Basic Starting Point.rst b/Help/guide/tutorial/A Basic Starting Point.rst index 3dac68a..37b0668 100644 --- a/Help/guide/tutorial/A Basic Starting Point.rst +++ b/Help/guide/tutorial/A Basic Starting Point.rst @@ -160,7 +160,7 @@ The last command to call for a basic project is :name: CMakeLists.txt-add_executable :language: cmake :start-after: # add the executable - :end-before: # TODO 9: + :end-before: # TODO 3: .. raw:: html @@ -240,7 +240,7 @@ the following: :name: tutorial.cxx-cxx11 :language: c++ :start-after: // convert input to double - :end-before: // TODO 12: + :end-before: // TODO 6: .. raw:: html @@ -265,7 +265,7 @@ add the :variable:`CMAKE_CXX_STANDARD` declarations above the call to :name: CMakeLists.txt-CXX_STANDARD :language: cmake :start-after: # specify the C++ standard - :end-before: # TODO 7: + :end-before: # configure a header file .. raw:: html @@ -375,7 +375,7 @@ specified CMake variables replaced: :name: CMakeLists.txt-configure_file :language: cmake :start-after: # to the source code - :end-before: # TODO 8: + :end-before: # TODO 2: .. raw:: html @@ -420,7 +420,6 @@ be replaced with the corresponding version numbers from the project in :caption: TODO 10: TutorialConfig.h.in :name: TutorialConfig.h.in :language: c++ - :end-before: // TODO 13: .. raw:: html diff --git a/Help/guide/tutorial/Adding Generator Expressions.rst b/Help/guide/tutorial/Adding Generator Expressions.rst index 6f9714e..08f3eea 100644 --- a/Help/guide/tutorial/Adding Generator Expressions.rst +++ b/Help/guide/tutorial/Adding Generator Expressions.rst @@ -299,7 +299,7 @@ condition. The resulting full code looks like the following: :name: CMakeLists.txt-target_compile_options-genex :language: cmake :start-after: set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>") - :end-before: # should we use our own math functions + :end-before: # configure a header file to pass some of the CMake settings .. raw:: html diff --git a/Help/guide/tutorial/Adding System Introspection.rst b/Help/guide/tutorial/Adding System Introspection.rst index b69abd2..b314773 100644 --- a/Help/guide/tutorial/Adding System Introspection.rst +++ b/Help/guide/tutorial/Adding System Introspection.rst @@ -119,7 +119,7 @@ our source code can tell what resources are available. If both ``log`` and :name: MathFunctions/CMakeLists.txt-target_compile_definitions :language: cmake :start-after: # add compile definitions - :end-before: # install libs + :end-before: # state .. raw:: html @@ -136,7 +136,8 @@ Since we may be using ``log`` and ``exp``, we need to modify :caption: TODO 4: MathFunctions/mysqrt.cxx :name: MathFunctions/mysqrt.cxx-include-cmath :language: c++ - :end-before: #include <iostream> + :start-after: #include "mysqrt.h" + :end-before: include <iostream> .. raw:: html diff --git a/Help/guide/tutorial/Adding Usage Requirements for a Library.rst b/Help/guide/tutorial/Adding Usage Requirements for a Library.rst index 4aef050..74b7496 100644 --- a/Help/guide/tutorial/Adding Usage Requirements for a Library.rst +++ b/Help/guide/tutorial/Adding Usage Requirements for a Library.rst @@ -100,7 +100,7 @@ follows: :name: MathFunctions/CMakeLists.txt-target_include_directories-INTERFACE :language: cmake :start-after: # to find MathFunctions.h - :end-before: # TODO 3: Link to + :end-before: option .. raw:: html @@ -119,7 +119,7 @@ safely remove our uses of the ``EXTRA_INCLUDES`` variable from the top-level :name: CMakeLists.txt-remove-EXTRA_INCLUDES :language: cmake :start-after: # add the MathFunctions library - :end-before: # add the executable + :end-before: # TODO 2: Link to tutorial_compiler_flags .. raw:: html diff --git a/Help/guide/tutorial/Adding a Custom Command and Generated File.rst b/Help/guide/tutorial/Adding a Custom Command and Generated File.rst index b1f9840..9e6311e 100644 --- a/Help/guide/tutorial/Adding a Custom Command and Generated File.rst +++ b/Help/guide/tutorial/Adding a Custom Command and Generated File.rst @@ -23,15 +23,25 @@ The next step is to add the appropriate commands to the then run it as part of the build process. A few commands are needed to accomplish this. -First, at the top of ``MathFunctions/CMakeLists.txt``, the executable for -``MakeTable`` is added as any other executable would be added. +First, in the ``USE_MYMATH`` section of ``MathFunctions/CMakeLists.txt``, +we add an executable for ``MakeTable``. .. literalinclude:: Step9/MathFunctions/CMakeLists.txt :caption: MathFunctions/CMakeLists.txt :name: MathFunctions/CMakeLists.txt-add_executable-MakeTable :language: cmake :start-after: # first we add the executable that generates the table - :end-before: # add the command to generate the source code + :end-before: target_link_libraries + +After creating the executable, we add the ``tutorial_compiler_flags`` to our +executable using :command:`target_link_libraries`. + +.. literalinclude:: Step9/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-link-tutorial-compiler-flags + :language: cmake + :start-after: add_executable + :end-before: # add the command to generate Then we add a custom command that specifies how to produce ``Table.h`` by running MakeTable. @@ -41,7 +51,7 @@ by running MakeTable. :name: MathFunctions/CMakeLists.txt-add_custom_command-Table.h :language: cmake :start-after: # add the command to generate the source code - :end-before: # add the main library + :end-before: # library that just does sqrt Next we have to let CMake know that ``mysqrt.cxx`` depends on the generated file ``Table.h``. This is done by adding the generated ``Table.h`` to the list @@ -51,8 +61,8 @@ of sources for the library MathFunctions. :caption: MathFunctions/CMakeLists.txt :name: MathFunctions/CMakeLists.txt-add_library-Table.h :language: cmake - :start-after: # add the main library - :end-before: # state that anybody linking + :start-after: # library that just does sqrt + :end-before: # state that we depend on We also have to add the current binary directory to the list of include directories so that ``Table.h`` can be found and included by ``mysqrt.cxx``. @@ -62,7 +72,19 @@ directories so that ``Table.h`` can be found and included by ``mysqrt.cxx``. :name: MathFunctions/CMakeLists.txt-target_include_directories-Table.h :language: cmake :start-after: # state that we depend on our bin - :end-before: # install libs + :end-before: target_link_libraries + +As the last thing in our ``USE_MYMATH`` section, we need to link the our +flags onto ``SqrtLibrary`` and then link ``SqrtLibrary`` onto +``MathFunctions``. This makes the resulting ``USE_MYMATH`` section look like +the following: + +.. literalinclude:: Step9/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-full_USE_MYMATH-section + :language: cmake + :start-after: if (USE_MYMATH) + :end-before: endif() Now let's use the generated table. First, modify ``mysqrt.cxx`` to include ``Table.h``. Next, we can rewrite the ``mysqrt`` function to use the table: diff --git a/Help/guide/tutorial/Adding a Library.rst b/Help/guide/tutorial/Adding a Library.rst index a56c327..2dd731f 100644 --- a/Help/guide/tutorial/Adding a Library.rst +++ b/Help/guide/tutorial/Adding a Library.rst @@ -51,11 +51,13 @@ 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``. This directory already contains a header file, -``MathFunctions.h``, and a source file ``mysqrt.cxx``. We will not need to -modify either of these files. The source file has one function called +``MathFunctions``. This directory already contains the header files +``MathFunctions.h`` and ``mysqrt.h``. Their respective source files +``MathFunctions.cxx`` and ``mysqrt.cxx`` are also provided. We will not need +to modify any of these files. ``mysqrt.cxx`` has one function called ``mysqrt`` that provides similar functionality to the compiler's ``sqrt`` -function. +function. ``MathFunctions.cxx`` contains one function ``sqrt`` which serves +to hide the implementation details of ``sqrt``. From the ``Help/guide/tutorial/Step2`` directory, start with ``TODO 1`` and complete through ``TODO 6``. @@ -91,10 +93,10 @@ Solution In the ``CMakeLists.txt`` file in the ``MathFunctions`` directory, we create a library target called ``MathFunctions`` with :command:`add_library`. The -source file for the library is passed as an argument to +source files for the library are passed as an argument to :command:`add_library`. This looks like the following line: -.. raw:: html +.. raw:: html/ <details><summary>TODO 1: Click to show/hide answer</summary> @@ -171,36 +173,40 @@ Now let's use our library. In ``tutorial.cxx``, include ``MathFunctions.h``: <details><summary>TODO 5: Click to show/hide answer</summary> -.. code-block:: c++ - :caption: TODO 5 : tutorial.cxx - :name: tutorial.cxx-include_MathFunctions.h - - #include "MathFunctions.h" +.. literalinclude:: Step3/tutorial.cxx + :caption: TODO 5: tutorial.cxx + :name: CMakeLists.txt-include-MathFunctions.h + :language: cmake + :start-after: #include <string> + :end-before: #include "TutorialConfig.h" .. raw:: html </details> -Lastly, replace ``sqrt`` with our library function ``mysqrt``. +Lastly, replace ``sqrt`` with our library function ``mathfunctions::mysqrt``. .. raw:: html <details><summary>TODO 6: Click to show/hide answer</summary> -.. code-block:: c++ - :caption: TODO 6 : tutorial.cxx - :name: tutorial.cxx-call_mysqrt - - const double outputValue = mysqrt(inputValue); +.. literalinclude:: Step3/tutorial.cxx + :caption: TODO 7: tutorial.cxx + :name: CMakeLists.txt-option + :language: cmake + :start-after: const double inputValue = std::stod(argv[1]); + :end-before: std::cout .. raw:: html </details> -Exercise 2 - Making Our Library Optional -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Exercise 2 - Adding an Option +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Now let us make the MathFunctions library optional. While for the tutorial +Now let us add an option in the MathFunctions library to allow developers to +select either the custom square root implementation or the built in standard +implementation. While for the tutorial there really isn't any need to do so, for larger projects this is a common occurrence. @@ -219,28 +225,26 @@ Helpful Resources ----------------- * :command:`if` -* :command:`list` * :command:`option` -* :command:`cmakedefine <configure_file>` +* :command:`target_compile_definitions` Files to Edit ------------- -* ``CMakeLists.txt`` -* ``tutorial.cxx`` -* ``TutorialConfig.h.in`` +* ``MathFunctions/CMakeLists.txt`` +* ``MathFunctions/MathFunctions.cxx`` Getting Started --------------- Start with the resulting files from Exercise 1. Complete ``TODO 7`` through -``TODO 13``. +``TODO 9``. First create a variable ``USE_MYMATH`` using the :command:`option` command -in the top-level ``CMakeLists.txt`` file. In that same file, use that option -to determine whether to build and use the ``MathFunctions`` library. +in ``MathFunctions/CMakeLists.txt``. In that same file, use that option +to pass a compile definition to the ``MathFunctions`` library. -Then, update ``tutorial.cxx`` and ``TutorialConfig.h.in`` to use +Then, update ``MathFunctions.cxx`` to redirect compilation based on ``USE_MYMATH``. Build and Run @@ -279,7 +283,7 @@ or ``mysqrt``? Solution -------- -The first step is to add an option to the top-level ``CMakeLists.txt`` file. +The first step is to add an option to ``MathFunctions/CMakeLists.txt``. This option will be displayed in the :manual:`cmake-gui <cmake-gui(1)>` and :manual:`ccmake <ccmake(1)>` with a default value of ``ON`` that can be changed by the user. @@ -288,172 +292,95 @@ changed by the user. <details><summary>TODO 7: Click to show/hide answer</summary> -.. literalinclude:: Step3/CMakeLists.txt - :caption: TODO 7: CMakeLists.txt - :name: CMakeLists.txt-option +.. literalinclude:: Step3/MathFunctions/CMakeLists.txt + :caption: TODO 7: MathFunctions/CMakeLists.txt + :name: CMakeLists.txt-option-library-level :language: cmake :start-after: # should we use our own math functions - :end-before: # configure a header file to pass some of the CMake settings + :end-before: if (USE_MYMATH) .. raw:: html </details> -Next, make building and linking the ``MathFunctions`` library -conditional. - -Start by creating a :command:`list` of the optional library targets for our -project. At the moment, it is just ``MathFunctions``. Let's name our list -``EXTRA_LIBS``. +Next, make building and linking our library with ``mysqrt`` function +conditional using this new option. -Similarly, we need to make a :command:`list` for the optional includes which -we will call ``EXTRA_INCLUDES``. In this list, we will ``APPEND`` the path of -the header file needed for our library. - -Next, create an :command:`if` statement which checks the value of +Create an :command:`if` statement which checks the value of ``USE_MYMATH``. Inside the :command:`if` block, put the -:command:`add_subdirectory` command from Exercise 1 with the additional -:command:`list` commands. - -When ``USE_MYMATH`` is ``ON``, the lists will be generated and will be added to -our project. When ``USE_MYMATH`` is ``OFF``, the lists stay empty. With this -strategy, we allow users to toggle ``USE_MYMATH`` to manipulate what library is -used in the build. - -The top-level CMakeLists.txt file will now look like the following: +:command:`target_compile_definitions` command with the compile +definition ``USE_MYMATH``. .. raw:: html <details><summary>TODO 8: Click to show/hide answer</summary> -.. literalinclude:: Step3/CMakeLists.txt - :caption: TODO 8: CMakeLists.txt +.. literalinclude:: Step3/MathFunctions/CMakeLists.txt + :caption: TODO 8: MathFunctions/CMakeLists.txt :name: CMakeLists.txt-USE_MYMATH :language: cmake - :start-after: # add the MathFunctions library - :end-before: # add the executable + :start-after: USE_MYMATH "Use tutorial provided math implementation" ON) .. raw:: html </details> -Now that we have these two lists, we need to update -:command:`target_link_libraries` and :command:`target_include_directories` to -use them. Changing them is fairly straightforward. - -For :command:`target_link_libraries`, we replace the written out -library names with ``EXTRA_LIBS``. This looks like the following: +The corresponding changes to the source code are fairly straightforward. +In ``MathFunctions.cxx``, we make ``USE_MYMATH`` control which square root +function is used: .. raw:: html <details><summary>TODO 9: Click to show/hide answer</summary> -.. literalinclude:: Step3/CMakeLists.txt - :caption: TODO 9: CMakeLists.txt - :name: CMakeLists.txt-target_link_libraries-EXTRA_LIBS - :language: cmake - :start-after: add_executable(Tutorial tutorial.cxx) - :end-before: # TODO 3 +.. literalinclude:: Step3/MathFunctions/MathFunctions.cxx + :caption: TODO 9: MathFunctions/MathFunctions.cxx + :name: MathFunctions-USE_MYMATH-if + :language: c++ + :start-after: which square root function should we use? + :end-before: } .. raw:: html </details> -Then, we do the same thing with :command:`target_include_directories` and -``EXTRA_INCLUDES``. +Next, we need to include ``mysqrt.h`` if ``USE_MYMATH`` is defined. .. raw:: html <details><summary>TODO 10: Click to show/hide answer</summary> -.. literalinclude:: Step3/CMakeLists.txt - :caption: TODO 10 : CMakeLists.txt - :name: CMakeLists.txt-target_link_libraries-EXTRA_INCLUDES - :language: cmake - :start-after: # so that we will find TutorialConfig.h - -.. raw:: html - - </details> - -Note that this is a classic approach when dealing with many components. We -will cover the modern approach in the Step 3 of the tutorial. - -The corresponding changes to the source code are fairly straightforward. -First, in ``tutorial.cxx``, we include the ``MathFunctions.h`` header if -``USE_MYMATH`` is defined. - -.. raw:: html - - <details><summary>TODO 11: Click to show/hide answer</summary> - -.. literalinclude:: Step3/tutorial.cxx - :caption: TODO 11 : tutorial.cxx - :name: tutorial.cxx-ifdef-include +.. literalinclude:: Step3/MathFunctions/MathFunctions.cxx + :caption: TODO 10: MathFunctions/MathFunctions.cxx + :name: MathFunctions-USE_MYMATH-if-include :language: c++ - :start-after: // should we include the MathFunctions header - :end-before: int main + :start-after: include <cmath> + :end-before: namespace mathfunctions .. raw:: html </details> -Then, in the same file, we make ``USE_MYMATH`` control which square root -function is used: - -.. raw:: html - - <details><summary>TODO 12: Click to show/hide answer</summary> - -.. literalinclude:: Step3/tutorial.cxx - :caption: TODO 12 : tutorial.cxx - :name: tutorial.cxx-ifdef-const - :language: c++ - :start-after: // which square root function should we use? - :end-before: std::cout << "The square root of +Finally, we need to include ``cmath`` now that we are using ``std::sqrt``. .. raw:: html - </details> - -Since the source code now requires ``USE_MYMATH`` we can add it to -``TutorialConfig.h.in`` with the following line: - -.. raw:: html + <details><summary>TODO 11: Click to show/hide answer</summary> - <details><summary>TODO 13: Click to show/hide answer</summary> +.. code-block:: c++ + :caption: TODO 11 : MathFunctions/MathFunctions.cxx + :name: tutorial.cxx-include_cmath -.. literalinclude:: Step3/TutorialConfig.h.in - :caption: TODO 13 : TutorialConfig.h.in - :name: TutorialConfig.h.in-cmakedefine - :language: c++ - :lines: 4 + #include <cmath> .. raw:: html </details> -With these changes, our library is now completely optional to whoever is -building and using it. - -Bonus Question --------------- - -Why is it important that we configure ``TutorialConfig.h.in`` -after the option for ``USE_MYMATH``? What would happen if we inverted the two? - -Answer ------- +When ``USE_MYMATH`` is ``ON``, the compile definition ``USE_MYMATH`` will +be set. We can then use this compile definition to enable or disable +sections of our source code. With this strategy, we allow users to +toggle ``USE_MYMATH`` to manipulate what library is used in the build. -.. raw:: html - - <details><summary>Click to show/hide answer</summary> - -We configure after because ``TutorialConfig.h.in`` uses the value of -``USE_MYMATH``. If we configure the file before -calling :command:`option`, we won't be using the expected value of -``USE_MYMATH``. - -.. raw:: html - - </details> +With these changes, the ``mysqrt`` function is now completely optional to +whoever is building and using the ``MathFunctions`` library. diff --git a/Help/guide/tutorial/Complete/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Complete/MathFunctions/MathFunctions.cxx index 0145300..c0991b9 100644 --- a/Help/guide/tutorial/Complete/MathFunctions/MathFunctions.cxx +++ b/Help/guide/tutorial/Complete/MathFunctions/MathFunctions.cxx @@ -10,6 +10,7 @@ namespace mathfunctions { double sqrt(double x) { +// which square root function should we use? #ifdef USE_MYMATH return detail::mysqrt(x); #else diff --git a/Help/guide/tutorial/Selecting Static or Shared Libraries.rst b/Help/guide/tutorial/Selecting Static or Shared Libraries.rst index 7befe1d..504e42f 100644 --- a/Help/guide/tutorial/Selecting Static or Shared Libraries.rst +++ b/Help/guide/tutorial/Selecting Static or Shared Libraries.rst @@ -10,49 +10,22 @@ To accomplish this we need to add :variable:`BUILD_SHARED_LIBS` to the top-level ``CMakeLists.txt``. We use the :command:`option` command as it allows users to optionally select if the value should be ``ON`` or ``OFF``. -Next we are going to refactor ``MathFunctions`` to become a real library that -encapsulates using ``mysqrt`` or ``sqrt``, instead of requiring the calling -code to do this logic. This will also mean that ``USE_MYMATH`` will not control -building ``MathFunctions``, but instead will control the behavior of this -library. - -The first step is to update the starting section of the top-level -``CMakeLists.txt`` to look like: - .. literalinclude:: Step11/CMakeLists.txt :caption: CMakeLists.txt :name: CMakeLists.txt-option-BUILD_SHARED_LIBS :language: cmake - :end-before: # add the binary tree - -Now that we have made ``MathFunctions`` always be used, we will need to update -the logic of that library. So, in ``MathFunctions/CMakeLists.txt`` we need to -create a SqrtLibrary that will conditionally be built and installed when -``USE_MYMATH`` is enabled. Now, since this is a tutorial, we are going to -explicitly require that SqrtLibrary is built statically. + :start-after: set(CMAKE_RUNTIME_OUTPUT_DIRECTORY + :end-before: # configure a header file to pass the version number only -The end result is that ``MathFunctions/CMakeLists.txt`` should look like: +Next, we need to specify output directories for our static and shared +libraries. -.. literalinclude:: Step11/MathFunctions/CMakeLists.txt - :caption: MathFunctions/CMakeLists.txt - :name: MathFunctions/CMakeLists.txt-add_library-STATIC +.. literalinclude:: Step11/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-cmake-output-directories :language: cmake - :lines: 1-36,42- - -Next, update ``MathFunctions/mysqrt.cxx`` to use the ``mathfunctions`` and -``detail`` namespaces: - -.. literalinclude:: Step11/MathFunctions/mysqrt.cxx - :caption: MathFunctions/mysqrt.cxx - :name: MathFunctions/mysqrt.cxx-namespace - :language: c++ - -We also need to make some changes in ``tutorial.cxx``, so that it no longer -uses ``USE_MYMATH``: - -#. Always include ``MathFunctions.h`` -#. Always use ``mathfunctions::sqrt`` -#. Don't include ``cmath`` + :start-after: # we don't need to tinker with the path to run the executable + :end-before: # configure a header file to pass the version number only Finally, update ``MathFunctions/MathFunctions.h`` to use dll export defines: diff --git a/Help/guide/tutorial/Step10/CMakeLists.txt b/Help/guide/tutorial/Step10/CMakeLists.txt index 5c661aa..2dd6db5 100644 --- a/Help/guide/tutorial/Step10/CMakeLists.txt +++ b/Help/guide/tutorial/Step10/CMakeLists.txt @@ -16,22 +16,15 @@ target_compile_options(tutorial_compiler_flags INTERFACE "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>" ) -# 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 a header file to pass the version number only configure_file(TutorialConfig.h.in TutorialConfig.h) # add the MathFunctions library -if(USE_MYMATH) - add_subdirectory(MathFunctions) - list(APPEND EXTRA_LIBS MathFunctions) -endif() +add_subdirectory(MathFunctions) # add the executable add_executable(Tutorial tutorial.cxx) -target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS} tutorial_compiler_flags) +target_link_libraries(Tutorial PUBLIC MathFunctions tutorial_compiler_flags) # add the binary tree to the search path for include files # so that we will find TutorialConfig.h diff --git a/Help/guide/tutorial/Step10/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step10/MathFunctions/CMakeLists.txt index fa73321..6f6c430 100644 --- a/Help/guide/tutorial/Step10/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step10/MathFunctions/CMakeLists.txt @@ -1,32 +1,51 @@ -# first we add the executable that generates the table -add_executable(MakeTable MakeTable.cxx) - -# add the command to generate the source code -add_custom_command( - OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h - COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h - DEPENDS MakeTable - ) - -# add the main library -add_library(MathFunctions - mysqrt.cxx - ${CMAKE_CURRENT_BINARY_DIR}/Table.h - ) +# add the library that runs +add_library(MathFunctions MathFunctions.cxx) # state that anybody linking to us needs to include the current source dir # to find MathFunctions.h, while we don't. -# state that we depend on our binary dir to find Table.h target_include_directories(MathFunctions - INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} - PRIVATE ${CMAKE_CURRENT_BINARY_DIR} - ) + INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} + ) -# link our compiler flags interface library -target_link_libraries(MathFunctions tutorial_compiler_flags) +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) +if(USE_MYMATH) + + target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") + + # first we add the executable that generates the table + add_executable(MakeTable MakeTable.cxx) + target_link_libraries(MakeTable PRIVATE tutorial_compiler_flags) + + # add the command to generate the source code + add_custom_command( + OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h + COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h + DEPENDS MakeTable + ) + + # library that just does sqrt + add_library(SqrtLibrary STATIC + mysqrt.cxx + ${CMAKE_CURRENT_BINARY_DIR}/Table.h + ) + + # state that we depend on our binary dir to find Table.h + target_include_directories(SqrtLibrary PRIVATE + ${CMAKE_CURRENT_BINARY_DIR} + ) + + target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags) + target_link_libraries(MathFunctions PRIVATE SqrtLibrary) +endif() + +target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) # install libs set(installable_libs MathFunctions tutorial_compiler_flags) +if(TARGET SqrtLibrary) + list(APPEND installable_libs SqrtLibrary) +endif() install(TARGETS ${installable_libs} DESTINATION lib) # install include headers install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Step10/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step10/MathFunctions/MathFunctions.cxx index 0145300..c0991b9 100644 --- a/Help/guide/tutorial/Step10/MathFunctions/MathFunctions.cxx +++ b/Help/guide/tutorial/Step10/MathFunctions/MathFunctions.cxx @@ -10,6 +10,7 @@ namespace mathfunctions { double sqrt(double x) { +// which square root function should we use? #ifdef USE_MYMATH return detail::mysqrt(x); #else diff --git a/Help/guide/tutorial/Step10/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step10/MathFunctions/MathFunctions.h index cd36bcc..1e916e1 100644 --- a/Help/guide/tutorial/Step10/MathFunctions/MathFunctions.h +++ b/Help/guide/tutorial/Step10/MathFunctions/MathFunctions.h @@ -1 +1,3 @@ -double mysqrt(double x); +namespace mathfunctions { +double sqrt(double x); +} diff --git a/Help/guide/tutorial/Step10/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step10/MathFunctions/mysqrt.cxx index 7d80ee9..8153f18 100644 --- a/Help/guide/tutorial/Step10/MathFunctions/mysqrt.cxx +++ b/Help/guide/tutorial/Step10/MathFunctions/mysqrt.cxx @@ -5,6 +5,8 @@ // include the generated table #include "Table.h" +namespace mathfunctions { +namespace detail { // a hack square root calculation using simple operations double mysqrt(double x) { @@ -31,3 +33,5 @@ double mysqrt(double x) return result; } +} +} diff --git a/Help/guide/tutorial/Step10/TutorialConfig.h.in b/Help/guide/tutorial/Step10/TutorialConfig.h.in index e23f521..7e4d7fa 100644 --- a/Help/guide/tutorial/Step10/TutorialConfig.h.in +++ b/Help/guide/tutorial/Step10/TutorialConfig.h.in @@ -1,4 +1,3 @@ // 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/Step10/tutorial.cxx b/Help/guide/tutorial/Step10/tutorial.cxx index b3c6a4f..37a0333 100644 --- a/Help/guide/tutorial/Step10/tutorial.cxx +++ b/Help/guide/tutorial/Step10/tutorial.cxx @@ -1,15 +1,11 @@ // A simple program that computes the square root of a number -#include <cmath> #include <iostream> +#include <sstream> #include <string> +#include "MathFunctions.h" #include "TutorialConfig.h" -// should we include the MathFunctions header? -#ifdef USE_MYMATH -# include "MathFunctions.h" -#endif - int main(int argc, char* argv[]) { if (argc < 2) { @@ -23,12 +19,7 @@ int main(int argc, char* argv[]) // convert input to double const double inputValue = std::stod(argv[1]); - // which square root function should we use? -#ifdef USE_MYMATH - const double outputValue = mysqrt(inputValue); -#else - const double outputValue = sqrt(inputValue); -#endif + const double outputValue = mathfunctions::sqrt(inputValue); std::cout << "The square root of " << inputValue << " is " << outputValue << std::endl; diff --git a/Help/guide/tutorial/Step11/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step11/MathFunctions/MathFunctions.cxx index 0145300..c0991b9 100644 --- a/Help/guide/tutorial/Step11/MathFunctions/MathFunctions.cxx +++ b/Help/guide/tutorial/Step11/MathFunctions/MathFunctions.cxx @@ -10,6 +10,7 @@ namespace mathfunctions { double sqrt(double x) { +// which square root function should we use? #ifdef USE_MYMATH return detail::mysqrt(x); #else diff --git a/Help/guide/tutorial/Step12/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step12/MathFunctions/MathFunctions.cxx index 0145300..c0991b9 100644 --- a/Help/guide/tutorial/Step12/MathFunctions/MathFunctions.cxx +++ b/Help/guide/tutorial/Step12/MathFunctions/MathFunctions.cxx @@ -10,6 +10,7 @@ namespace mathfunctions { double sqrt(double x) { +// which square root function should we use? #ifdef USE_MYMATH return detail::mysqrt(x); #else diff --git a/Help/guide/tutorial/Step2/CMakeLists.txt b/Help/guide/tutorial/Step2/CMakeLists.txt index 2b96128..0a06ed7 100644 --- a/Help/guide/tutorial/Step2/CMakeLists.txt +++ b/Help/guide/tutorial/Step2/CMakeLists.txt @@ -7,36 +7,20 @@ project(Tutorial VERSION 1.0) set(CMAKE_CXX_STANDARD 11) set(CMAKE_CXX_STANDARD_REQUIRED True) -# TODO 7: Create a variable USE_MYMATH using option and set default to ON - # configure a header file to pass some of the CMake settings # to the source code configure_file(TutorialConfig.h.in TutorialConfig.h) -# TODO 8: Use list() and APPEND to create a list of optional libraries -# called EXTRA_LIBS and a list of optional include directories called -# EXTRA_INCLUDES. Add the MathFunctions library and source directory to -# the appropriate lists. -# -# Only call add_subdirectory and only add MathFunctions specific values -# to EXTRA_LIBS and EXTRA_INCLUDES if USE_MYMATH is true. - # TODO 2: Use add_subdirectory() to add MathFunctions to this project # add the executable add_executable(Tutorial tutorial.cxx) -# TODO 9: Use EXTRA_LIBS instead of the MathFunctions specific values -# in target_link_libraries. - # TODO 3: Use target_link_libraries to link the library to our executable # TODO 4: Add MathFunctions to Tutorial's target_include_directories() # Hint: ${PROJECT_SOURCE_DIR} is a path to the project source. AKA This folder! -# TODO 10: Use EXTRA_INCLUDES instead of the MathFunctions specific values -# in target_include_directories. - # add the binary tree to the search path for include files # so that we will find TutorialConfig.h target_include_directories(Tutorial PUBLIC diff --git a/Help/guide/tutorial/Step2/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step2/MathFunctions/CMakeLists.txt index b7779b7..c468b0e 100644 --- a/Help/guide/tutorial/Step2/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step2/MathFunctions/CMakeLists.txt @@ -1,2 +1,7 @@ # TODO 1: Add a library called MathFunctions # Hint: You will need the add_library command + +# TODO 7: Create a variable USE_MYMATH using option and set default to ON + +# TODO 8: If USE_MYMATH is ON, use target_compile_definitions to pass +# USE_MYMATH as a precompiled definition to our source files diff --git a/Help/guide/tutorial/Step2/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step2/MathFunctions/MathFunctions.cxx new file mode 100644 index 0000000..781d0ec --- /dev/null +++ b/Help/guide/tutorial/Step2/MathFunctions/MathFunctions.cxx @@ -0,0 +1,15 @@ +#include "MathFunctions.h" + +// TODO 11: include cmath + +// TODO 10: Wrap the mysqrt include in a precompiled ifdef based on USE_MYMATH +#include "mysqrt.h" + +namespace mathfunctions { +double sqrt(double x) +{ + // TODO 9: If USE_MYMATH is defined, use detail::mysqrt. + // Otherwise, use std::sqrt. + return detail::mysqrt(x); +} +} diff --git a/Help/guide/tutorial/Step2/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step2/MathFunctions/MathFunctions.h index cd36bcc..d5c2f22 100644 --- a/Help/guide/tutorial/Step2/MathFunctions/MathFunctions.h +++ b/Help/guide/tutorial/Step2/MathFunctions/MathFunctions.h @@ -1 +1,5 @@ -double mysqrt(double x); +#pragma once + +namespace mathfunctions { +double sqrt(double x); +} diff --git a/Help/guide/tutorial/Step2/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step2/MathFunctions/mysqrt.cxx index 1e4d97a..ba0ac64 100644 --- a/Help/guide/tutorial/Step2/MathFunctions/mysqrt.cxx +++ b/Help/guide/tutorial/Step2/MathFunctions/mysqrt.cxx @@ -1,5 +1,9 @@ +#include "mysqrt.h" + #include <iostream> +namespace mathfunctions { +namespace detail { // a hack square root calculation using simple operations double mysqrt(double x) { @@ -20,3 +24,5 @@ double mysqrt(double x) } return result; } +} +} diff --git a/Help/guide/tutorial/Step2/MathFunctions/mysqrt.h b/Help/guide/tutorial/Step2/MathFunctions/mysqrt.h new file mode 100644 index 0000000..593d41e --- /dev/null +++ b/Help/guide/tutorial/Step2/MathFunctions/mysqrt.h @@ -0,0 +1,7 @@ +#pragma once + +namespace mathfunctions { +namespace detail { +double mysqrt(double x); +} +} diff --git a/Help/guide/tutorial/Step2/TutorialConfig.h.in b/Help/guide/tutorial/Step2/TutorialConfig.h.in index 6c09e1a..7e4d7fa 100644 --- a/Help/guide/tutorial/Step2/TutorialConfig.h.in +++ b/Help/guide/tutorial/Step2/TutorialConfig.h.in @@ -1,5 +1,3 @@ // the configured options and settings for Tutorial #define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ #define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ - -// TODO 13: use cmakedefine to define USE_MYMATH diff --git a/Help/guide/tutorial/Step2/tutorial.cxx b/Help/guide/tutorial/Step2/tutorial.cxx index 87f5e0f..7a2a595 100644 --- a/Help/guide/tutorial/Step2/tutorial.cxx +++ b/Help/guide/tutorial/Step2/tutorial.cxx @@ -3,11 +3,8 @@ #include <iostream> #include <string> -#include "TutorialConfig.h" - -// TODO 11: Only include MathFunctions if USE_MYMATH is defined - // TODO 5: Include MathFunctions.h +#include "TutorialConfig.h" int main(int argc, char* argv[]) { @@ -22,9 +19,7 @@ int main(int argc, char* argv[]) // convert input to double const double inputValue = std::stod(argv[1]); - // TODO 12: Use mysqrt if USE_MYMATH is defined and sqrt otherwise - - // TODO 6: Replace sqrt with mysqrt + // TODO 6: Replace sqrt with mathfunctions::sqrt // calculate square root const double outputValue = sqrt(inputValue); diff --git a/Help/guide/tutorial/Step3/CMakeLists.txt b/Help/guide/tutorial/Step3/CMakeLists.txt index 007770a..f051826 100644 --- a/Help/guide/tutorial/Step3/CMakeLists.txt +++ b/Help/guide/tutorial/Step3/CMakeLists.txt @@ -7,9 +7,6 @@ project(Tutorial VERSION 1.0) 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) - # configure a header file to pass some of the CMake settings # to the source code configure_file(TutorialConfig.h.in TutorialConfig.h) @@ -17,16 +14,13 @@ configure_file(TutorialConfig.h.in TutorialConfig.h) # TODO 2: Remove EXTRA_INCLUDES list # add the MathFunctions library -if(USE_MYMATH) - add_subdirectory(MathFunctions) - list(APPEND EXTRA_LIBS MathFunctions) - list(APPEND EXTRA_INCLUDES "${PROJECT_SOURCE_DIR}/MathFunctions") -endif() +add_subdirectory(MathFunctions) +list(APPEND EXTRA_INCLUDES "${PROJECT_SOURCE_DIR}/MathFunctions") # add the executable add_executable(Tutorial tutorial.cxx) -target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS}) +target_link_libraries(Tutorial PUBLIC MathFunctions) # TODO 3: Remove use of EXTRA_INCLUDES diff --git a/Help/guide/tutorial/Step3/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step3/MathFunctions/CMakeLists.txt index 7bf05e0..90d6c24 100644 --- a/Help/guide/tutorial/Step3/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step3/MathFunctions/CMakeLists.txt @@ -1,5 +1,11 @@ -add_library(MathFunctions mysqrt.cxx) +add_library(MathFunctions MathFunctions.cxx mysqrt.cxx) # TODO 1: State that anybody linking to MathFunctions needs to include the # current source directory, while MathFunctions itself doesn't. # Hint: Use target_include_directories with the INTERFACE keyword + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) +if (USE_MYMATH) + target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") +endif() diff --git a/Help/guide/tutorial/Step3/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step3/MathFunctions/MathFunctions.cxx new file mode 100644 index 0000000..dc28b4b --- /dev/null +++ b/Help/guide/tutorial/Step3/MathFunctions/MathFunctions.cxx @@ -0,0 +1,19 @@ +#include "MathFunctions.h" + +#include <cmath> + +#ifdef USE_MYMATH +# include "mysqrt.h" +#endif + +namespace mathfunctions { +double sqrt(double x) +{ +// which square root function should we use? +#ifdef USE_MYMATH + return detail::mysqrt(x); +#else + return std::sqrt(x); +#endif +} +} diff --git a/Help/guide/tutorial/Step3/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step3/MathFunctions/MathFunctions.h index cd36bcc..d5c2f22 100644 --- a/Help/guide/tutorial/Step3/MathFunctions/MathFunctions.h +++ b/Help/guide/tutorial/Step3/MathFunctions/MathFunctions.h @@ -1 +1,5 @@ -double mysqrt(double x); +#pragma once + +namespace mathfunctions { +double sqrt(double x); +} diff --git a/Help/guide/tutorial/Step3/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step3/MathFunctions/mysqrt.cxx index abe767d..ba0ac64 100644 --- a/Help/guide/tutorial/Step3/MathFunctions/mysqrt.cxx +++ b/Help/guide/tutorial/Step3/MathFunctions/mysqrt.cxx @@ -1,7 +1,9 @@ -#include <iostream> +#include "mysqrt.h" -#include "MathFunctions.h" +#include <iostream> +namespace mathfunctions { +namespace detail { // a hack square root calculation using simple operations double mysqrt(double x) { @@ -22,3 +24,5 @@ double mysqrt(double x) } return result; } +} +} diff --git a/Help/guide/tutorial/Step3/MathFunctions/mysqrt.h b/Help/guide/tutorial/Step3/MathFunctions/mysqrt.h new file mode 100644 index 0000000..593d41e --- /dev/null +++ b/Help/guide/tutorial/Step3/MathFunctions/mysqrt.h @@ -0,0 +1,7 @@ +#pragma once + +namespace mathfunctions { +namespace detail { +double mysqrt(double x); +} +} diff --git a/Help/guide/tutorial/Step3/TutorialConfig.h.in b/Help/guide/tutorial/Step3/TutorialConfig.h.in index e23f521..7e4d7fa 100644 --- a/Help/guide/tutorial/Step3/TutorialConfig.h.in +++ b/Help/guide/tutorial/Step3/TutorialConfig.h.in @@ -1,4 +1,3 @@ // 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/Step3/tutorial.cxx b/Help/guide/tutorial/Step3/tutorial.cxx index b3c6a4f..a3a2bdc 100644 --- a/Help/guide/tutorial/Step3/tutorial.cxx +++ b/Help/guide/tutorial/Step3/tutorial.cxx @@ -3,13 +3,9 @@ #include <iostream> #include <string> +#include "MathFunctions.h" #include "TutorialConfig.h" -// should we include the MathFunctions header? -#ifdef USE_MYMATH -# include "MathFunctions.h" -#endif - int main(int argc, char* argv[]) { if (argc < 2) { @@ -23,12 +19,7 @@ int main(int argc, char* argv[]) // convert input to double const double inputValue = std::stod(argv[1]); - // which square root function should we use? -#ifdef USE_MYMATH - const double outputValue = mysqrt(inputValue); -#else - const double outputValue = sqrt(inputValue); -#endif + const double outputValue = mathfunctions::sqrt(inputValue); std::cout << "The square root of " << inputValue << " is " << outputValue << std::endl; diff --git a/Help/guide/tutorial/Step4/CMakeLists.txt b/Help/guide/tutorial/Step4/CMakeLists.txt index fa4aab2..dcda135 100644 --- a/Help/guide/tutorial/Step4/CMakeLists.txt +++ b/Help/guide/tutorial/Step4/CMakeLists.txt @@ -31,25 +31,19 @@ set(CMAKE_CXX_STANDARD_REQUIRED True) # build-tree # Hint: Use BUILD_INTERFACE -# 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(TutorialConfig.h.in TutorialConfig.h) # add the MathFunctions library -if(USE_MYMATH) - add_subdirectory(MathFunctions) - list(APPEND EXTRA_LIBS MathFunctions) -endif() +add_subdirectory(MathFunctions) # add the executable add_executable(Tutorial tutorial.cxx) # TODO 2: Link to tutorial_compiler_flags -target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS}) +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/Step4/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step4/MathFunctions/CMakeLists.txt index 5f7369c..cc71d86 100644 --- a/Help/guide/tutorial/Step4/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step4/MathFunctions/CMakeLists.txt @@ -1,9 +1,15 @@ -add_library(MathFunctions mysqrt.cxx) +add_library(MathFunctions MathFunctions.cxx mysqrt.cxx) # state that anybody linking to us needs to include the current source dir # to find MathFunctions.h, while we don't. target_include_directories(MathFunctions - INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} - ) + INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} + ) + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) +if (USE_MYMATH) + target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") +endif() # TODO 3: Link to tutorial_compiler_flags diff --git a/Help/guide/tutorial/Step4/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step4/MathFunctions/MathFunctions.cxx new file mode 100644 index 0000000..dc28b4b --- /dev/null +++ b/Help/guide/tutorial/Step4/MathFunctions/MathFunctions.cxx @@ -0,0 +1,19 @@ +#include "MathFunctions.h" + +#include <cmath> + +#ifdef USE_MYMATH +# include "mysqrt.h" +#endif + +namespace mathfunctions { +double sqrt(double x) +{ +// which square root function should we use? +#ifdef USE_MYMATH + return detail::mysqrt(x); +#else + return std::sqrt(x); +#endif +} +} diff --git a/Help/guide/tutorial/Step4/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step4/MathFunctions/MathFunctions.h index cd36bcc..d5c2f22 100644 --- a/Help/guide/tutorial/Step4/MathFunctions/MathFunctions.h +++ b/Help/guide/tutorial/Step4/MathFunctions/MathFunctions.h @@ -1 +1,5 @@ -double mysqrt(double x); +#pragma once + +namespace mathfunctions { +double sqrt(double x); +} diff --git a/Help/guide/tutorial/Step4/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step4/MathFunctions/mysqrt.cxx index abe767d..ba0ac64 100644 --- a/Help/guide/tutorial/Step4/MathFunctions/mysqrt.cxx +++ b/Help/guide/tutorial/Step4/MathFunctions/mysqrt.cxx @@ -1,7 +1,9 @@ -#include <iostream> +#include "mysqrt.h" -#include "MathFunctions.h" +#include <iostream> +namespace mathfunctions { +namespace detail { // a hack square root calculation using simple operations double mysqrt(double x) { @@ -22,3 +24,5 @@ double mysqrt(double x) } return result; } +} +} diff --git a/Help/guide/tutorial/Step4/MathFunctions/mysqrt.h b/Help/guide/tutorial/Step4/MathFunctions/mysqrt.h new file mode 100644 index 0000000..593d41e --- /dev/null +++ b/Help/guide/tutorial/Step4/MathFunctions/mysqrt.h @@ -0,0 +1,7 @@ +#pragma once + +namespace mathfunctions { +namespace detail { +double mysqrt(double x); +} +} diff --git a/Help/guide/tutorial/Step4/TutorialConfig.h.in b/Help/guide/tutorial/Step4/TutorialConfig.h.in index e23f521..7e4d7fa 100644 --- a/Help/guide/tutorial/Step4/TutorialConfig.h.in +++ b/Help/guide/tutorial/Step4/TutorialConfig.h.in @@ -1,4 +1,3 @@ // 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/Step4/tutorial.cxx b/Help/guide/tutorial/Step4/tutorial.cxx index b3c6a4f..a3a2bdc 100644 --- a/Help/guide/tutorial/Step4/tutorial.cxx +++ b/Help/guide/tutorial/Step4/tutorial.cxx @@ -3,13 +3,9 @@ #include <iostream> #include <string> +#include "MathFunctions.h" #include "TutorialConfig.h" -// should we include the MathFunctions header? -#ifdef USE_MYMATH -# include "MathFunctions.h" -#endif - int main(int argc, char* argv[]) { if (argc < 2) { @@ -23,12 +19,7 @@ int main(int argc, char* argv[]) // convert input to double const double inputValue = std::stod(argv[1]); - // which square root function should we use? -#ifdef USE_MYMATH - const double outputValue = mysqrt(inputValue); -#else - const double outputValue = sqrt(inputValue); -#endif + const double outputValue = mathfunctions::sqrt(inputValue); std::cout << "The square root of " << inputValue << " is " << outputValue << std::endl; diff --git a/Help/guide/tutorial/Step5/CMakeLists.txt b/Help/guide/tutorial/Step5/CMakeLists.txt index 279ddf9..ad814f6 100644 --- a/Help/guide/tutorial/Step5/CMakeLists.txt +++ b/Help/guide/tutorial/Step5/CMakeLists.txt @@ -16,22 +16,17 @@ target_compile_options(tutorial_compiler_flags INTERFACE "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>" ) -# 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(TutorialConfig.h.in TutorialConfig.h) # add the MathFunctions library -if(USE_MYMATH) - add_subdirectory(MathFunctions) - list(APPEND EXTRA_LIBS MathFunctions) -endif() +add_subdirectory(MathFunctions) # add the executable add_executable(Tutorial tutorial.cxx) -target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS} tutorial_compiler_flags) + +target_link_libraries(Tutorial PUBLIC MathFunctions tutorial_compiler_flags) # add the binary tree to the search path for include files # so that we will find TutorialConfig.h diff --git a/Help/guide/tutorial/Step5/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step5/MathFunctions/CMakeLists.txt index 6cd88d7..000a786 100644 --- a/Help/guide/tutorial/Step5/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step5/MathFunctions/CMakeLists.txt @@ -1,13 +1,19 @@ -add_library(MathFunctions mysqrt.cxx) +add_library(MathFunctions MathFunctions.cxx mysqrt.cxx) # state that anybody linking to us needs to include the current source dir # to find MathFunctions.h, while we don't. target_include_directories(MathFunctions - INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} - ) + INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} + ) + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) +if (USE_MYMATH) + target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") +endif() # link our compiler flags interface library -target_link_libraries(MathFunctions tutorial_compiler_flags) +target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) # TODO 1: Create a variable called installable_libs that is a list of all # libraries we want to install (e.g. MathFunctions and tutorial_compiler_flags) diff --git a/Help/guide/tutorial/Step5/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step5/MathFunctions/MathFunctions.cxx new file mode 100644 index 0000000..dc28b4b --- /dev/null +++ b/Help/guide/tutorial/Step5/MathFunctions/MathFunctions.cxx @@ -0,0 +1,19 @@ +#include "MathFunctions.h" + +#include <cmath> + +#ifdef USE_MYMATH +# include "mysqrt.h" +#endif + +namespace mathfunctions { +double sqrt(double x) +{ +// which square root function should we use? +#ifdef USE_MYMATH + return detail::mysqrt(x); +#else + return std::sqrt(x); +#endif +} +} diff --git a/Help/guide/tutorial/Step5/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step5/MathFunctions/MathFunctions.h index cd36bcc..d5c2f22 100644 --- a/Help/guide/tutorial/Step5/MathFunctions/MathFunctions.h +++ b/Help/guide/tutorial/Step5/MathFunctions/MathFunctions.h @@ -1 +1,5 @@ -double mysqrt(double x); +#pragma once + +namespace mathfunctions { +double sqrt(double x); +} diff --git a/Help/guide/tutorial/Step5/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step5/MathFunctions/mysqrt.cxx index abe767d..ba0ac64 100644 --- a/Help/guide/tutorial/Step5/MathFunctions/mysqrt.cxx +++ b/Help/guide/tutorial/Step5/MathFunctions/mysqrt.cxx @@ -1,7 +1,9 @@ -#include <iostream> +#include "mysqrt.h" -#include "MathFunctions.h" +#include <iostream> +namespace mathfunctions { +namespace detail { // a hack square root calculation using simple operations double mysqrt(double x) { @@ -22,3 +24,5 @@ double mysqrt(double x) } return result; } +} +} diff --git a/Help/guide/tutorial/Step5/MathFunctions/mysqrt.h b/Help/guide/tutorial/Step5/MathFunctions/mysqrt.h new file mode 100644 index 0000000..593d41e --- /dev/null +++ b/Help/guide/tutorial/Step5/MathFunctions/mysqrt.h @@ -0,0 +1,7 @@ +#pragma once + +namespace mathfunctions { +namespace detail { +double mysqrt(double x); +} +} diff --git a/Help/guide/tutorial/Step5/TutorialConfig.h.in b/Help/guide/tutorial/Step5/TutorialConfig.h.in index e23f521..7e4d7fa 100644 --- a/Help/guide/tutorial/Step5/TutorialConfig.h.in +++ b/Help/guide/tutorial/Step5/TutorialConfig.h.in @@ -1,4 +1,3 @@ // 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/Step5/tutorial.cxx b/Help/guide/tutorial/Step5/tutorial.cxx index b3c6a4f..a3a2bdc 100644 --- a/Help/guide/tutorial/Step5/tutorial.cxx +++ b/Help/guide/tutorial/Step5/tutorial.cxx @@ -3,13 +3,9 @@ #include <iostream> #include <string> +#include "MathFunctions.h" #include "TutorialConfig.h" -// should we include the MathFunctions header? -#ifdef USE_MYMATH -# include "MathFunctions.h" -#endif - int main(int argc, char* argv[]) { if (argc < 2) { @@ -23,12 +19,7 @@ int main(int argc, char* argv[]) // convert input to double const double inputValue = std::stod(argv[1]); - // which square root function should we use? -#ifdef USE_MYMATH - const double outputValue = mysqrt(inputValue); -#else - const double outputValue = sqrt(inputValue); -#endif + const double outputValue = mathfunctions::sqrt(inputValue); std::cout << "The square root of " << inputValue << " is " << outputValue << std::endl; diff --git a/Help/guide/tutorial/Step6/CMakeLists.txt b/Help/guide/tutorial/Step6/CMakeLists.txt index c11e307..a86d60a 100644 --- a/Help/guide/tutorial/Step6/CMakeLists.txt +++ b/Help/guide/tutorial/Step6/CMakeLists.txt @@ -16,22 +16,17 @@ target_compile_options(tutorial_compiler_flags INTERFACE "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>" ) -# 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(TutorialConfig.h.in TutorialConfig.h) # add the MathFunctions library -if(USE_MYMATH) - add_subdirectory(MathFunctions) - list(APPEND EXTRA_LIBS MathFunctions) -endif() +add_subdirectory(MathFunctions) # add the executable add_executable(Tutorial tutorial.cxx) -target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS} tutorial_compiler_flags) + +target_link_libraries(Tutorial PUBLIC MathFunctions tutorial_compiler_flags) # add the binary tree to the search path for include files # so that we will find TutorialConfig.h diff --git a/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt index b4724c4..623cb74 100644 --- a/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt @@ -1,13 +1,19 @@ -add_library(MathFunctions mysqrt.cxx) +add_library(MathFunctions MathFunctions.cxx mysqrt.cxx) # state that anybody linking to us needs to include the current source dir # to find MathFunctions.h, while we don't. target_include_directories(MathFunctions - INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} - ) + INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} + ) + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) +if (USE_MYMATH) + target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") +endif() # link our compiler flags interface library -target_link_libraries(MathFunctions tutorial_compiler_flags) +target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) # install libs set(installable_libs MathFunctions tutorial_compiler_flags) diff --git a/Help/guide/tutorial/Step6/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step6/MathFunctions/MathFunctions.cxx new file mode 100644 index 0000000..dc28b4b --- /dev/null +++ b/Help/guide/tutorial/Step6/MathFunctions/MathFunctions.cxx @@ -0,0 +1,19 @@ +#include "MathFunctions.h" + +#include <cmath> + +#ifdef USE_MYMATH +# include "mysqrt.h" +#endif + +namespace mathfunctions { +double sqrt(double x) +{ +// which square root function should we use? +#ifdef USE_MYMATH + return detail::mysqrt(x); +#else + return std::sqrt(x); +#endif +} +} diff --git a/Help/guide/tutorial/Step6/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step6/MathFunctions/MathFunctions.h index cd36bcc..d5c2f22 100644 --- a/Help/guide/tutorial/Step6/MathFunctions/MathFunctions.h +++ b/Help/guide/tutorial/Step6/MathFunctions/MathFunctions.h @@ -1 +1,5 @@ -double mysqrt(double x); +#pragma once + +namespace mathfunctions { +double sqrt(double x); +} diff --git a/Help/guide/tutorial/Step6/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step6/MathFunctions/mysqrt.cxx index abe767d..ba0ac64 100644 --- a/Help/guide/tutorial/Step6/MathFunctions/mysqrt.cxx +++ b/Help/guide/tutorial/Step6/MathFunctions/mysqrt.cxx @@ -1,7 +1,9 @@ -#include <iostream> +#include "mysqrt.h" -#include "MathFunctions.h" +#include <iostream> +namespace mathfunctions { +namespace detail { // a hack square root calculation using simple operations double mysqrt(double x) { @@ -22,3 +24,5 @@ double mysqrt(double x) } return result; } +} +} diff --git a/Help/guide/tutorial/Step6/MathFunctions/mysqrt.h b/Help/guide/tutorial/Step6/MathFunctions/mysqrt.h new file mode 100644 index 0000000..593d41e --- /dev/null +++ b/Help/guide/tutorial/Step6/MathFunctions/mysqrt.h @@ -0,0 +1,7 @@ +#pragma once + +namespace mathfunctions { +namespace detail { +double mysqrt(double x); +} +} diff --git a/Help/guide/tutorial/Step6/TutorialConfig.h.in b/Help/guide/tutorial/Step6/TutorialConfig.h.in index e23f521..7e4d7fa 100644 --- a/Help/guide/tutorial/Step6/TutorialConfig.h.in +++ b/Help/guide/tutorial/Step6/TutorialConfig.h.in @@ -1,4 +1,3 @@ // 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/Step6/tutorial.cxx b/Help/guide/tutorial/Step6/tutorial.cxx index b3c6a4f..a3a2bdc 100644 --- a/Help/guide/tutorial/Step6/tutorial.cxx +++ b/Help/guide/tutorial/Step6/tutorial.cxx @@ -3,13 +3,9 @@ #include <iostream> #include <string> +#include "MathFunctions.h" #include "TutorialConfig.h" -// should we include the MathFunctions header? -#ifdef USE_MYMATH -# include "MathFunctions.h" -#endif - int main(int argc, char* argv[]) { if (argc < 2) { @@ -23,12 +19,7 @@ int main(int argc, char* argv[]) // convert input to double const double inputValue = std::stod(argv[1]); - // which square root function should we use? -#ifdef USE_MYMATH - const double outputValue = mysqrt(inputValue); -#else - const double outputValue = sqrt(inputValue); -#endif + const double outputValue = mathfunctions::sqrt(inputValue); std::cout << "The square root of " << inputValue << " is " << outputValue << std::endl; diff --git a/Help/guide/tutorial/Step7/CMakeLists.txt b/Help/guide/tutorial/Step7/CMakeLists.txt index d26a90c..97ec6aa 100644 --- a/Help/guide/tutorial/Step7/CMakeLists.txt +++ b/Help/guide/tutorial/Step7/CMakeLists.txt @@ -16,22 +16,17 @@ target_compile_options(tutorial_compiler_flags INTERFACE "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>" ) -# 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(TutorialConfig.h.in TutorialConfig.h) # add the MathFunctions library -if(USE_MYMATH) - add_subdirectory(MathFunctions) - list(APPEND EXTRA_LIBS MathFunctions) -endif() +add_subdirectory(MathFunctions) # add the executable add_executable(Tutorial tutorial.cxx) -target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS} tutorial_compiler_flags) + +target_link_libraries(Tutorial PUBLIC MathFunctions tutorial_compiler_flags) # add the binary tree to the search path for include files # so that we will find TutorialConfig.h diff --git a/Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt index e5bdc4d..c0d1e72 100644 --- a/Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt @@ -1,33 +1,39 @@ -add_library(MathFunctions mysqrt.cxx) +add_library(MathFunctions MathFunctions.cxx mysqrt.cxx) # state that anybody linking to us needs to include the current source dir # to find MathFunctions.h, while we don't. target_include_directories(MathFunctions - INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} - ) + INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} + ) -# link our compiler flags interface library -target_link_libraries(MathFunctions tutorial_compiler_flags) +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) +if (USE_MYMATH) + target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") + + # TODO 1: Include CheckCXXSourceCompiles -# TODO 1: Include CheckCXXSourceCompiles + # TODO 2: Use check_cxx_source_compiles with simple C++ code to verify + # availability of: + # * std::log + # * std::exp + # Store the results in HAVE_LOG and HAVE_EXP respectively. -# TODO 2: Use check_cxx_source_compiles with simple C++ code to verify -# availability of: -# * std::log -# * std::exp -# Store the results in HAVE_LOG and HAVE_EXP respectively. + # Hint: Sample C++ code which uses log: + # #include <cmath> + # int main() { + # std::log(1.0); + # return 0; + # } -# Hint: Sample C++ code which uses log: -# #include <cmath> -# int main() { -# std::log(1.0); -# return 0; -# } + # TODO 3: Conditionally on HAVE_LOG and HAVE_EXP, add private compile + # definitions "HAVE_LOG" and "HAVE_EXP" to the MathFunctions target. -# TODO 3: Conditionally on HAVE_LOG and HAVE_EXP, add private compile -# definitions "HAVE_LOG" and "HAVE_EXP" to the MathFunctions target. + # Hint: Use target_compile_definitions() +endif() -#Hint: Use target_compile_definitions() +# link our compiler flags interface library +target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) # install libs set(installable_libs MathFunctions tutorial_compiler_flags) diff --git a/Help/guide/tutorial/Step7/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step7/MathFunctions/MathFunctions.cxx new file mode 100644 index 0000000..dc28b4b --- /dev/null +++ b/Help/guide/tutorial/Step7/MathFunctions/MathFunctions.cxx @@ -0,0 +1,19 @@ +#include "MathFunctions.h" + +#include <cmath> + +#ifdef USE_MYMATH +# include "mysqrt.h" +#endif + +namespace mathfunctions { +double sqrt(double x) +{ +// which square root function should we use? +#ifdef USE_MYMATH + return detail::mysqrt(x); +#else + return std::sqrt(x); +#endif +} +} diff --git a/Help/guide/tutorial/Step7/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step7/MathFunctions/MathFunctions.h index cd36bcc..d5c2f22 100644 --- a/Help/guide/tutorial/Step7/MathFunctions/MathFunctions.h +++ b/Help/guide/tutorial/Step7/MathFunctions/MathFunctions.h @@ -1 +1,5 @@ -double mysqrt(double x); +#pragma once + +namespace mathfunctions { +double sqrt(double x); +} diff --git a/Help/guide/tutorial/Step7/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step7/MathFunctions/mysqrt.cxx index 3d2492a..9963cff 100644 --- a/Help/guide/tutorial/Step7/MathFunctions/mysqrt.cxx +++ b/Help/guide/tutorial/Step7/MathFunctions/mysqrt.cxx @@ -1,8 +1,9 @@ -#include <iostream> +#include "mysqrt.h" -// TODO 4: include cmath -#include "MathFunctions.h" +#include <iostream> +namespace mathfunctions { +namespace detail { // a hack square root calculation using simple operations double mysqrt(double x) { @@ -32,3 +33,5 @@ double mysqrt(double x) return result; } +} +} diff --git a/Help/guide/tutorial/Step7/MathFunctions/mysqrt.h b/Help/guide/tutorial/Step7/MathFunctions/mysqrt.h new file mode 100644 index 0000000..593d41e --- /dev/null +++ b/Help/guide/tutorial/Step7/MathFunctions/mysqrt.h @@ -0,0 +1,7 @@ +#pragma once + +namespace mathfunctions { +namespace detail { +double mysqrt(double x); +} +} diff --git a/Help/guide/tutorial/Step7/TutorialConfig.h.in b/Help/guide/tutorial/Step7/TutorialConfig.h.in index e23f521..7e4d7fa 100644 --- a/Help/guide/tutorial/Step7/TutorialConfig.h.in +++ b/Help/guide/tutorial/Step7/TutorialConfig.h.in @@ -1,4 +1,3 @@ // 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/Step7/tutorial.cxx b/Help/guide/tutorial/Step7/tutorial.cxx index b3c6a4f..a3a2bdc 100644 --- a/Help/guide/tutorial/Step7/tutorial.cxx +++ b/Help/guide/tutorial/Step7/tutorial.cxx @@ -3,13 +3,9 @@ #include <iostream> #include <string> +#include "MathFunctions.h" #include "TutorialConfig.h" -// should we include the MathFunctions header? -#ifdef USE_MYMATH -# include "MathFunctions.h" -#endif - int main(int argc, char* argv[]) { if (argc < 2) { @@ -23,12 +19,7 @@ int main(int argc, char* argv[]) // convert input to double const double inputValue = std::stod(argv[1]); - // which square root function should we use? -#ifdef USE_MYMATH - const double outputValue = mysqrt(inputValue); -#else - const double outputValue = sqrt(inputValue); -#endif + const double outputValue = mathfunctions::sqrt(inputValue); std::cout << "The square root of " << inputValue << " is " << outputValue << std::endl; diff --git a/Help/guide/tutorial/Step8/CMakeLists.txt b/Help/guide/tutorial/Step8/CMakeLists.txt index cb87281..97ec6aa 100644 --- a/Help/guide/tutorial/Step8/CMakeLists.txt +++ b/Help/guide/tutorial/Step8/CMakeLists.txt @@ -16,23 +16,17 @@ target_compile_options(tutorial_compiler_flags INTERFACE "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>" ) - -# 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(TutorialConfig.h.in TutorialConfig.h) # add the MathFunctions library -if(USE_MYMATH) - add_subdirectory(MathFunctions) - list(APPEND EXTRA_LIBS MathFunctions) -endif() +add_subdirectory(MathFunctions) # add the executable add_executable(Tutorial tutorial.cxx) -target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS} tutorial_compiler_flags) + +target_link_libraries(Tutorial PUBLIC MathFunctions tutorial_compiler_flags) # add the binary tree to the search path for include files # so that we will find TutorialConfig.h diff --git a/Help/guide/tutorial/Step8/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step8/MathFunctions/CMakeLists.txt index f81b563..861014d 100644 --- a/Help/guide/tutorial/Step8/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step8/MathFunctions/CMakeLists.txt @@ -1,36 +1,43 @@ -add_library(MathFunctions mysqrt.cxx) +add_library(MathFunctions MathFunctions.cxx mysqrt.cxx) + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) +if (USE_MYMATH) + target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") + + # does this system provide the log and exp functions? + include(CheckCXXSourceCompiles) + check_cxx_source_compiles(" + #include <cmath> + int main() { + std::log(1.0); + return 0; + } + " HAVE_LOG) + check_cxx_source_compiles(" + #include <cmath> + int main() { + std::exp(1.0); + return 0; + } + " HAVE_EXP) + + # add compile definitions + if(HAVE_LOG AND HAVE_EXP) + target_compile_definitions(MathFunctions + PRIVATE "HAVE_LOG" "HAVE_EXP" + ) + endif() +endif() # state that anybody linking to us needs to include the current source dir # to find MathFunctions.h, while we don't. target_include_directories(MathFunctions - INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} - ) + INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} + ) # link our compiler flags interface library -target_link_libraries(MathFunctions tutorial_compiler_flags) - -# does this system provide the log and exp functions? -include(CheckCXXSourceCompiles) -check_cxx_source_compiles(" - #include <cmath> - int main() { - std::log(1.0); - return 0; - } -" HAVE_LOG) -check_cxx_source_compiles(" - #include <cmath> - int main() { - std::exp(1.0); - return 0; - } -" HAVE_EXP) - -# add compile definitions -if(HAVE_LOG AND HAVE_EXP) - target_compile_definitions(MathFunctions - PRIVATE "HAVE_LOG" "HAVE_EXP") -endif() +target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) # install libs set(installable_libs MathFunctions tutorial_compiler_flags) diff --git a/Help/guide/tutorial/Step8/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step8/MathFunctions/MathFunctions.cxx new file mode 100644 index 0000000..dc28b4b --- /dev/null +++ b/Help/guide/tutorial/Step8/MathFunctions/MathFunctions.cxx @@ -0,0 +1,19 @@ +#include "MathFunctions.h" + +#include <cmath> + +#ifdef USE_MYMATH +# include "mysqrt.h" +#endif + +namespace mathfunctions { +double sqrt(double x) +{ +// which square root function should we use? +#ifdef USE_MYMATH + return detail::mysqrt(x); +#else + return std::sqrt(x); +#endif +} +} diff --git a/Help/guide/tutorial/Step8/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step8/MathFunctions/MathFunctions.h index cd36bcc..d5c2f22 100644 --- a/Help/guide/tutorial/Step8/MathFunctions/MathFunctions.h +++ b/Help/guide/tutorial/Step8/MathFunctions/MathFunctions.h @@ -1 +1,5 @@ -double mysqrt(double x); +#pragma once + +namespace mathfunctions { +double sqrt(double x); +} diff --git a/Help/guide/tutorial/Step8/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step8/MathFunctions/mysqrt.cxx index 7eecd26..28ab042 100644 --- a/Help/guide/tutorial/Step8/MathFunctions/mysqrt.cxx +++ b/Help/guide/tutorial/Step8/MathFunctions/mysqrt.cxx @@ -1,8 +1,10 @@ +#include "mysqrt.h" + #include <cmath> #include <iostream> -#include "MathFunctions.h" - +namespace mathfunctions { +namespace detail { // a hack square root calculation using simple operations double mysqrt(double x) { @@ -30,3 +32,5 @@ double mysqrt(double x) #endif return result; } +} +} diff --git a/Help/guide/tutorial/Step8/MathFunctions/mysqrt.h b/Help/guide/tutorial/Step8/MathFunctions/mysqrt.h new file mode 100644 index 0000000..593d41e --- /dev/null +++ b/Help/guide/tutorial/Step8/MathFunctions/mysqrt.h @@ -0,0 +1,7 @@ +#pragma once + +namespace mathfunctions { +namespace detail { +double mysqrt(double x); +} +} diff --git a/Help/guide/tutorial/Step8/TutorialConfig.h.in b/Help/guide/tutorial/Step8/TutorialConfig.h.in index e23f521..7e4d7fa 100644 --- a/Help/guide/tutorial/Step8/TutorialConfig.h.in +++ b/Help/guide/tutorial/Step8/TutorialConfig.h.in @@ -1,4 +1,3 @@ // 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/Step8/tutorial.cxx b/Help/guide/tutorial/Step8/tutorial.cxx index b3c6a4f..a3a2bdc 100644 --- a/Help/guide/tutorial/Step8/tutorial.cxx +++ b/Help/guide/tutorial/Step8/tutorial.cxx @@ -3,13 +3,9 @@ #include <iostream> #include <string> +#include "MathFunctions.h" #include "TutorialConfig.h" -// should we include the MathFunctions header? -#ifdef USE_MYMATH -# include "MathFunctions.h" -#endif - int main(int argc, char* argv[]) { if (argc < 2) { @@ -23,12 +19,7 @@ int main(int argc, char* argv[]) // convert input to double const double inputValue = std::stod(argv[1]); - // which square root function should we use? -#ifdef USE_MYMATH - const double outputValue = mysqrt(inputValue); -#else - const double outputValue = sqrt(inputValue); -#endif + const double outputValue = mathfunctions::sqrt(inputValue); std::cout << "The square root of " << inputValue << " is " << outputValue << std::endl; diff --git a/Help/guide/tutorial/Step9/CMakeLists.txt b/Help/guide/tutorial/Step9/CMakeLists.txt index d26a90c..97ec6aa 100644 --- a/Help/guide/tutorial/Step9/CMakeLists.txt +++ b/Help/guide/tutorial/Step9/CMakeLists.txt @@ -16,22 +16,17 @@ target_compile_options(tutorial_compiler_flags INTERFACE "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>" ) -# 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(TutorialConfig.h.in TutorialConfig.h) # add the MathFunctions library -if(USE_MYMATH) - add_subdirectory(MathFunctions) - list(APPEND EXTRA_LIBS MathFunctions) -endif() +add_subdirectory(MathFunctions) # add the executable add_executable(Tutorial tutorial.cxx) -target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS} tutorial_compiler_flags) + +target_link_libraries(Tutorial PUBLIC MathFunctions tutorial_compiler_flags) # add the binary tree to the search path for include files # so that we will find TutorialConfig.h diff --git a/Help/guide/tutorial/Step9/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step9/MathFunctions/CMakeLists.txt index 8e04f97..05c8616 100644 --- a/Help/guide/tutorial/Step9/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step9/MathFunctions/CMakeLists.txt @@ -1,34 +1,49 @@ -# first we add the executable that generates the table -add_executable(MakeTable MakeTable.cxx) - -# add the command to generate the source code -add_custom_command( - OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h - COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h - DEPENDS MakeTable - ) - -# add the main library -add_library(MathFunctions - mysqrt.cxx - ${CMAKE_CURRENT_BINARY_DIR}/Table.h - ) +add_library(MathFunctions MathFunctions.cxx) # state that anybody linking to us needs to include the current source dir # to find MathFunctions.h, while we don't. -# state that we depend on Tutorial_BINARY_DIR but consumers don't, as the -# TutorialConfig.h include is an implementation detail -# state that we depend on our binary dir to find Table.h target_include_directories(MathFunctions - INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} - PRIVATE ${CMAKE_CURRENT_BINARY_DIR} - ) + INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} + ) -# link our compiler flags interface library -target_link_libraries(MathFunctions tutorial_compiler_flags) +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) +if (USE_MYMATH) + target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") + + # first we add the executable that generates the table + add_executable(MakeTable MakeTable.cxx) + target_link_libraries(MakeTable PRIVATE tutorial_compiler_flags) + + # add the command to generate the source code + add_custom_command( + OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h + COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h + DEPENDS MakeTable + ) + + # library that just does sqrt + add_library(SqrtLibrary STATIC + mysqrt.cxx + ${CMAKE_CURRENT_BINARY_DIR}/Table.h + ) + + # state that we depend on our binary dir to find Table.h + target_include_directories(SqrtLibrary PRIVATE + ${CMAKE_CURRENT_BINARY_DIR} + ) + + target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags) + target_link_libraries(MathFunctions PRIVATE SqrtLibrary) +endif() + +target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) # install libs set(installable_libs MathFunctions tutorial_compiler_flags) +if(TARGET SqrtLibrary) + list(APPEND installable_libs SqrtLibrary) +endif() install(TARGETS ${installable_libs} DESTINATION lib) # install include headers install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Step9/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step9/MathFunctions/MathFunctions.cxx new file mode 100644 index 0000000..dc28b4b --- /dev/null +++ b/Help/guide/tutorial/Step9/MathFunctions/MathFunctions.cxx @@ -0,0 +1,19 @@ +#include "MathFunctions.h" + +#include <cmath> + +#ifdef USE_MYMATH +# include "mysqrt.h" +#endif + +namespace mathfunctions { +double sqrt(double x) +{ +// which square root function should we use? +#ifdef USE_MYMATH + return detail::mysqrt(x); +#else + return std::sqrt(x); +#endif +} +} diff --git a/Help/guide/tutorial/Step9/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step9/MathFunctions/MathFunctions.h index cd36bcc..d5c2f22 100644 --- a/Help/guide/tutorial/Step9/MathFunctions/MathFunctions.h +++ b/Help/guide/tutorial/Step9/MathFunctions/MathFunctions.h @@ -1 +1,5 @@ -double mysqrt(double x); +#pragma once + +namespace mathfunctions { +double sqrt(double x); +} diff --git a/Help/guide/tutorial/Step9/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step9/MathFunctions/mysqrt.cxx index 7d80ee9..477d715 100644 --- a/Help/guide/tutorial/Step9/MathFunctions/mysqrt.cxx +++ b/Help/guide/tutorial/Step9/MathFunctions/mysqrt.cxx @@ -1,10 +1,12 @@ -#include <iostream> +#include "mysqrt.h" -#include "MathFunctions.h" +#include <iostream> // include the generated table #include "Table.h" +namespace mathfunctions { +namespace detail { // a hack square root calculation using simple operations double mysqrt(double x) { @@ -31,3 +33,5 @@ double mysqrt(double x) return result; } +} +} diff --git a/Help/guide/tutorial/Step9/MathFunctions/mysqrt.h b/Help/guide/tutorial/Step9/MathFunctions/mysqrt.h new file mode 100644 index 0000000..593d41e --- /dev/null +++ b/Help/guide/tutorial/Step9/MathFunctions/mysqrt.h @@ -0,0 +1,7 @@ +#pragma once + +namespace mathfunctions { +namespace detail { +double mysqrt(double x); +} +} diff --git a/Help/guide/tutorial/Step9/TutorialConfig.h.in b/Help/guide/tutorial/Step9/TutorialConfig.h.in index e23f521..7e4d7fa 100644 --- a/Help/guide/tutorial/Step9/TutorialConfig.h.in +++ b/Help/guide/tutorial/Step9/TutorialConfig.h.in @@ -1,4 +1,3 @@ // 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 b3c6a4f..a3a2bdc 100644 --- a/Help/guide/tutorial/Step9/tutorial.cxx +++ b/Help/guide/tutorial/Step9/tutorial.cxx @@ -3,13 +3,9 @@ #include <iostream> #include <string> +#include "MathFunctions.h" #include "TutorialConfig.h" -// should we include the MathFunctions header? -#ifdef USE_MYMATH -# include "MathFunctions.h" -#endif - int main(int argc, char* argv[]) { if (argc < 2) { @@ -23,12 +19,7 @@ int main(int argc, char* argv[]) // convert input to double const double inputValue = std::stod(argv[1]); - // which square root function should we use? -#ifdef USE_MYMATH - const double outputValue = mysqrt(inputValue); -#else - const double outputValue = sqrt(inputValue); -#endif + const double outputValue = mathfunctions::sqrt(inputValue); std::cout << "The square root of " << inputValue << " is " << outputValue << std::endl; diff --git a/Help/manual/ccmake.1.rst b/Help/manual/ccmake.1.rst index a09857b..5b118d1 100644 --- a/Help/manual/ccmake.1.rst +++ b/Help/manual/ccmake.1.rst @@ -8,6 +8,7 @@ Synopsis .. parsed-literal:: + ccmake [<options>] -B <path-to-build> [-S <path-to-source>] ccmake [<options>] <path-to-source | path-to-existing-build> Description diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index b9d621b..9fdb26c 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -797,6 +797,10 @@ An *archive* output artifact of a buildsystem target may be: created by the :command:`add_executable` command when its :prop_tgt:`ENABLE_EXPORTS` target property is set. +* On macOS: the linker import file (e.g. ``.tbd``) of a shared library target + created by the :command:`add_library` command with the ``SHARED`` option and + when its :prop_tgt:`ENABLE_EXPORTS` target property is set. + The :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY` and :prop_tgt:`ARCHIVE_OUTPUT_NAME` target properties may be used to control archive output artifact locations and names in the build tree. diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index c3e87d7..a640c13 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -446,16 +446,20 @@ command. All paths are expected to be in cmake-style format. components from a path. See :ref:`Path Structure And Terminology` for the meaning of each path component. + .. versionchanged:: 3.27 + All operations now accept a list of paths as argument. When a list of paths + is specified, the operation will be applied to each path. + :: - $<PATH:GET_ROOT_NAME,path> - $<PATH:GET_ROOT_DIRECTORY,path> - $<PATH:GET_ROOT_PATH,path> - $<PATH:GET_FILENAME,path> - $<PATH:GET_EXTENSION[,LAST_ONLY],path> - $<PATH:GET_STEM[,LAST_ONLY],path> - $<PATH:GET_RELATIVE_PART,path> - $<PATH:GET_PARENT_PATH,path> + $<PATH:GET_ROOT_NAME,path...> + $<PATH:GET_ROOT_DIRECTORY,path...> + $<PATH:GET_ROOT_PATH,path...> + $<PATH:GET_FILENAME,path...> + $<PATH:GET_EXTENSION[,LAST_ONLY],path...> + $<PATH:GET_STEM[,LAST_ONLY],path...> + $<PATH:GET_RELATIVE_PART,path...> + $<PATH:GET_PARENT_PATH,path...> If a requested component is not present in the path, an empty string is returned. @@ -470,9 +474,14 @@ These expressions provide the generation-time capabilities equivalent to the options of the :command:`cmake_path` command. All paths are expected to be in cmake-style format. +.. versionchanged:: 3.27 + All operations now accept a list of paths as argument. When a list of paths + is specified, the operation will be applied to each path. + + .. _GenEx PATH-CMAKE_PATH: -.. genex:: $<PATH:CMAKE_PATH[,NORMALIZE],path> +.. genex:: $<PATH:CMAKE_PATH[,NORMALIZE],path...> .. versionadded:: 3.24 @@ -483,7 +492,7 @@ in cmake-style format. When the ``NORMALIZE`` option is specified, the path is :ref:`normalized <Normalization>` after the conversion. -.. genex:: $<PATH:APPEND,path,input,...> +.. genex:: $<PATH:APPEND,path...,input,...> .. versionadded:: 3.24 @@ -493,7 +502,7 @@ in cmake-style format. See :ref:`cmake_path(APPEND) <APPEND>` for more details. -.. genex:: $<PATH:REMOVE_FILENAME,path> +.. genex:: $<PATH:REMOVE_FILENAME,path...> .. versionadded:: 3.24 @@ -503,7 +512,7 @@ in cmake-style format. See :ref:`cmake_path(REMOVE_FILENAME) <REMOVE_FILENAME>` for more details. -.. genex:: $<PATH:REPLACE_FILENAME,path,input> +.. genex:: $<PATH:REPLACE_FILENAME,path...,input> .. versionadded:: 3.24 @@ -513,7 +522,7 @@ in cmake-style format. See :ref:`cmake_path(REPLACE_FILENAME) <REPLACE_FILENAME>` for more details. -.. genex:: $<PATH:REMOVE_EXTENSION[,LAST_ONLY],path> +.. genex:: $<PATH:REMOVE_EXTENSION[,LAST_ONLY],path...> .. versionadded:: 3.24 @@ -521,7 +530,7 @@ in cmake-style format. See :ref:`cmake_path(REMOVE_EXTENSION) <REMOVE_EXTENSION>` for more details. -.. genex:: $<PATH:REPLACE_EXTENSION[,LAST_ONLY],path,input> +.. genex:: $<PATH:REPLACE_EXTENSION[,LAST_ONLY],path...,input> .. versionadded:: 3.24 @@ -530,14 +539,14 @@ in cmake-style format. See :ref:`cmake_path(REPLACE_EXTENSION) <REPLACE_EXTENSION>` for more details. -.. genex:: $<PATH:NORMAL_PATH,path> +.. genex:: $<PATH:NORMAL_PATH,path...> .. versionadded:: 3.24 Returns ``path`` normalized according to the steps described in :ref:`Normalization`. -.. genex:: $<PATH:RELATIVE_PATH,path,base_directory> +.. genex:: $<PATH:RELATIVE_PATH,path...,base_directory> .. versionadded:: 3.24 @@ -547,7 +556,7 @@ in cmake-style format. See :ref:`cmake_path(RELATIVE_PATH) <cmake_path-RELATIVE_PATH>` for more details. -.. genex:: $<PATH:ABSOLUTE_PATH[,NORMALIZE],path,base_directory> +.. genex:: $<PATH:ABSOLUTE_PATH[,NORMALIZE],path...,base_directory> .. versionadded:: 3.24 @@ -1494,6 +1503,76 @@ In the following, the phrase "the ``tgt`` filename" means the name of the Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on (see policy :policy:`CMP0112`). +.. genex:: $<TARGET_IMPORT_FILE:tgt> + + .. versionadded:: 3.27 + + Full path to the linker import file. On DLL platforms, it would be the + ``.lib`` file. On AIX, for the executables, and on macOS, for the shared + libraries, it could be, respectively, the ``.imp`` or ``.tbd`` import file, + depending of the value of :prop_tgt:`ENABLE_EXPORTS` property. + + An empty string is returned when there is no import file associated with the + target. + +.. genex:: $<TARGET_IMPORT_FILE_BASE_NAME:tgt> + + .. versionadded:: 3.27 + + Base name of file linker import file of the target ``tgt`` without prefix and + suffix. For example, if target file name is ``libbase.tbd``, the base name is + ``base``. + + See also the :prop_tgt:`OUTPUT_NAME` and :prop_tgt:`ARCHIVE_OUTPUT_NAME` + target properties and their configuration specific variants + :prop_tgt:`OUTPUT_NAME_<CONFIG>` and :prop_tgt:`ARCHIVE_OUTPUT_NAME_<CONFIG>`. + + The :prop_tgt:`<CONFIG>_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target + properties can also be considered. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_IMPORT_FILE_PREFIX:tgt> + + .. versionadded:: 3.27 + + Prefix of the import file of the target ``tgt``. + + See also the :prop_tgt:`IMPORT_PREFIX` target property. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_IMPORT_FILE_SUFFIX:tgt> + + .. versionadded:: 3.27 + + Suffix of the import file of the target ``tgt``. + + The suffix corresponds to the file extension (such as ".lib" or ".tbd"). + + See also the :prop_tgt:`IMPORT_SUFFIX` target property. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_IMPORT_FILE_NAME:tgt> + + .. versionadded:: 3.27 + + Name of the import file of the target target ``tgt``. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_IMPORT_FILE_DIR:tgt> + + Directory of the import file of the target ``tgt``. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + .. genex:: $<TARGET_LINKER_FILE:tgt> File used when linking to the ``tgt`` target. This will usually @@ -1501,13 +1580,22 @@ In the following, the phrase "the ``tgt`` filename" means the name of the but for a shared library on DLL platforms, it would be the ``.lib`` import library associated with the DLL. + .. versionadded:: 3.27 + On macOS, it could be the ``.tbd`` import file associated with the shared + library, depending of the value of :prop_tgt:`ENABLE_EXPORTS` property. + + This generator expression is equivalent to + :genex:`$<TARGET_LINKER_LIBRARY_FILE>` or + :genex:`$<TARGET_LINKER_IMPORT_FILE>` generator expressions, depending of the + characteristics of the target and the platform. + .. genex:: $<TARGET_LINKER_FILE_BASE_NAME:tgt> .. versionadded:: 3.15 Base name of file used to link the target ``tgt``, i.e. - ``$<TARGET_LINKER_FILE_NAME:tgt>`` without prefix and suffix. For example, - if target file name is ``libbase.a``, the base name is ``base``. + :genex:`$<TARGET_LINKER_FILE_NAME:tgt>` without prefix and suffix. For + example, if target file name is ``libbase.a``, the base name is ``base``. See also the :prop_tgt:`OUTPUT_NAME`, :prop_tgt:`ARCHIVE_OUTPUT_NAME`, and :prop_tgt:`LIBRARY_OUTPUT_NAME` target properties and their configuration @@ -1561,9 +1649,151 @@ In the following, the phrase "the ``tgt`` filename" means the name of the Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on (see policy :policy:`CMP0112`). +.. genex:: $<TARGET_LINKER_LIBRARY_FILE:tgt> + + .. versionadded:: 3.27 + + File used when linking o the ``tgt`` target is done using directly the + library, and not an import file. This will usually be the library that + ``tgt`` represents (``.a``, ``.so``, ``.dylib``). So, on DLL platforms, it + will be an empty string. + +.. genex:: $<TARGET_LINKER_LIBRARY_FILE_BASE_NAME:tgt> + + .. versionadded:: 3.27 + + Base name of library file used to link the target ``tgt``, i.e. + :genex:`$<TARGET_LINKER_LIBRARY_FILE_NAME:tgt>` without prefix and suffix. + For example, if target file name is ``libbase.a``, the base name is ``base``. + + See also the :prop_tgt:`OUTPUT_NAME`, :prop_tgt:`ARCHIVE_OUTPUT_NAME`, + and :prop_tgt:`LIBRARY_OUTPUT_NAME` target properties and their configuration + specific variants :prop_tgt:`OUTPUT_NAME_<CONFIG>`, + :prop_tgt:`ARCHIVE_OUTPUT_NAME_<CONFIG>` and + :prop_tgt:`LIBRARY_OUTPUT_NAME_<CONFIG>`. + + The :prop_tgt:`<CONFIG>_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target + properties can also be considered. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_LINKER_LIBRARY_FILE_PREFIX:tgt> + + .. versionadded:: 3.27 + + Prefix of the library file used to link target ``tgt``. + + See also the :prop_tgt:`PREFIX` target property. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_LINKER_LIBRARY_FILE_SUFFIX:tgt> + + .. versionadded:: 3.27 + + Suffix of the library file used to link target ``tgt``. + + The suffix corresponds to the file extension (such as ".a" or ".dylib"). + + See also the :prop_tgt:`SUFFIX` target property. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_LINKER_LIBRARY_FILE_NAME:tgt> + + .. versionadded:: 3.27 + + Name of the library file used to link target ``tgt``. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_LINKER_LIBRARY_FILE_DIR:tgt> + + .. versionadded:: 3.27 + + Directory of the library file used to link target ``tgt``. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_LINKER_IMPORT_FILE:tgt> + + .. versionadded:: 3.27 + + File used when linking to the ``tgt`` target is done using an import + file. This will usually be the import file that ``tgt`` represents + (``.lib``, ``.tbd``). So, when no import file is involved in the link step, + an empty string is returned. + +.. genex:: $<TARGET_LINKER_IMPORT_FILE_BASE_NAME:tgt> + + .. versionadded:: 3.27 + + Base name of the import file used to link the target ``tgt``, i.e. + :genex:`$<TARGET_LINKER_IMPORT_FILE_NAME:tgt>` without prefix and suffix. + For example, if target file name is ``libbase.tbd``, the base name is ``base``. + + See also the :prop_tgt:`OUTPUT_NAME` and :prop_tgt:`ARCHIVE_OUTPUT_NAME`, + target properties and their configuration + specific variants :prop_tgt:`OUTPUT_NAME_<CONFIG>` and + :prop_tgt:`ARCHIVE_OUTPUT_NAME_<CONFIG>`. + + The :prop_tgt:`<CONFIG>_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target + properties can also be considered. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_LINKER_IMPORT_FILE_PREFIX:tgt> + + .. versionadded:: 3.27 + + Prefix of the import file used to link target ``tgt``. + + See also the :prop_tgt:`IMPORT_PREFIX` target property. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_LINKER_IMPORT_FILE_SUFFIX:tgt> + + .. versionadded:: 3.27 + + Suffix of the import file used to link target ``tgt``. + + The suffix corresponds to the file extension (such as ".lib" or ".tbd"). + + See also the :prop_tgt:`IMPORT_SUFFIX` target property. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_LINKER_IMPORT_FILE_NAME:tgt> + + .. versionadded:: 3.27 + + Name of the import file used to link target ``tgt``. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_LINKER_IMPORT_FILE_DIR:tgt> + + .. versionadded:: 3.27 + + Directory of the import file used to link target ``tgt``. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + .. genex:: $<TARGET_SONAME_FILE:tgt> File with soname (``.so.3``) where ``tgt`` is the name of a target. + .. genex:: $<TARGET_SONAME_FILE_NAME:tgt> Name of file with soname (``.so.3``). @@ -1573,11 +1803,35 @@ In the following, the phrase "the ``tgt`` filename" means the name of the .. genex:: $<TARGET_SONAME_FILE_DIR:tgt> - Directory of with soname (``.so.3``). + Directory of file with soname (``.so.3``). Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on (see policy :policy:`CMP0112`). +.. genex:: $<TARGET_SONAME_IMPORT_FILE:tgt> + + .. versionadded:: 3.27 + + Import file with soname (``.3.tbd``) where ``tgt`` is the name of a target. + +.. genex:: $<TARGET_SONAME_IMPORT_FILE_NAME:tgt> + + .. versionadded:: 3.27 + + Name of the import file with soname (``.3.tbd``). + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_SONAME_IMPORT_FILE_DIR:tgt> + + .. versionadded:: 3.27 + + Directory of the import file with soname (``.3.tbd``). + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + .. genex:: $<TARGET_PDB_FILE:tgt> .. versionadded:: 3.1 @@ -1668,7 +1922,9 @@ In the following, the phrase "the ``tgt`` filename" means the name of the List of DLLs that the target depends on at runtime. This is determined by the locations of all the ``SHARED`` targets in the target's transitive - dependencies. Using this generator expression on targets other than + dependencies. If only the directories of the DLLs are needed, see the + :genex:`TARGET_RUNTIME_DLL_DIRS` generator expression. + Using this generator expression on targets other than executables, ``SHARED`` libraries, and ``MODULE`` libraries is an error. **On non-DLL platforms, this expression always evaluates to an empty string**. @@ -1700,6 +1956,20 @@ On platforms that support runtime paths (``RPATH``), refer to the :prop_tgt:`INSTALL_RPATH` target property. On Apple platforms, refer to the :prop_tgt:`INSTALL_NAME_DIR` target property. +.. genex:: $<TARGET_RUNTIME_DLL_DIRS:tgt> + + .. versionadded:: 3.27 + + List of the directories which contain the DLLs that the target depends on at + runtime (see :genex:`TARGET_RUNTIME_DLLS`). This is determined by + the locations of all the ``SHARED`` targets in the target's transitive + dependencies. Using this generator expression on targets other than + executables, ``SHARED`` libraries, and ``MODULE`` libraries is an error. + **On non-DLL platforms, this expression always evaluates to an empty string**. + + This generator expression can e.g. be used to create a batch file using + :command:`file(GENERATE)` which sets the PATH environment variable accordingly. + Export And Install Expressions ------------------------------ @@ -1725,8 +1995,10 @@ Export And Install Expressions Content of the install prefix when the target is exported via :command:`install(EXPORT)`, or when evaluated in the - :prop_tgt:`INSTALL_NAME_DIR` property or the ``INSTALL_NAME_DIR`` argument of - :command:`install(RUNTIME_DEPENDENCY_SET)`, and empty otherwise. + :prop_tgt:`INSTALL_NAME_DIR` property, the ``INSTALL_NAME_DIR`` argument of + :command:`install(RUNTIME_DEPENDENCY_SET)`, the code argument of + :command:`install(CODE)`, or the file argument of :command:`install(SCRIPT)`, + and empty otherwise. Multi-level Expression Evaluation --------------------------------- diff --git a/Help/manual/cmake-generators.7.rst b/Help/manual/cmake-generators.7.rst index ed5bbbf..9647f0d 100644 --- a/Help/manual/cmake-generators.7.rst +++ b/Help/manual/cmake-generators.7.rst @@ -107,6 +107,12 @@ Other Generators Extra Generators ================ +.. deprecated:: 3.27 + + Support for "Extra Generators" is deprecated and will be removed from + a future version of CMake. IDEs may use the :manual:`cmake-file-api(7)` + to view CMake-generated project build trees. + Some of the `CMake Generators`_ listed in the :manual:`cmake(1)` command-line tool :option:`--help <cmake --help>` output may have variants that specify an extra generator for an auxiliary IDE tool. diff --git a/Help/manual/cmake-gui.1.rst b/Help/manual/cmake-gui.1.rst index cdb860f..26083ca 100644 --- a/Help/manual/cmake-gui.1.rst +++ b/Help/manual/cmake-gui.1.rst @@ -9,9 +9,9 @@ Synopsis .. parsed-literal:: cmake-gui [<options>] + cmake-gui [<options>] -B <path-to-build> [-S <path-to-source>] cmake-gui [<options>] <path-to-source | path-to-existing-build> - cmake-gui [<options>] -S <path-to-source> -B <path-to-build> - cmake-gui [<options>] --browse-manual + cmake-gui [<options>] --browse-manual [<filename>] Description =========== @@ -46,9 +46,11 @@ Options Name of the preset to use from the project's :manual:`presets <cmake-presets(7)>` files, if it has them. -.. option:: --browse-manual +.. option:: --browse-manual [<filename>] - Open the CMake reference manual in a browser and immediately exit. + Open the CMake reference manual in a browser and immediately exit. If + ``<filename>`` is specified, open that file within the reference manual + instead of ``index.html``. .. include:: OPTIONS_HELP.txt diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 22e9eb2..28272ad 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -51,6 +51,15 @@ The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used to determine whether to report an error on use of deprecated macros or functions. +Policies Introduced by CMake 3.27 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0145: The Dart and FindDart modules are removed. </policy/CMP0145> + CMP0144: find_package uses upper-case PACKAGENAME_ROOT variables. </policy/CMP0144> + Policies Introduced by CMake 3.26 ================================= diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index fb84f5a..01c9ce8 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -202,6 +202,7 @@ Properties on Targets /prop_tgt/DEPLOYMENT_REMOTE_DIRECTORY /prop_tgt/DEPRECATION /prop_tgt/DISABLE_PRECOMPILE_HEADERS + /prop_tgt/DLL_NAME_WITH_SOVERSION /prop_tgt/DOTNET_SDK /prop_tgt/DOTNET_TARGET_FRAMEWORK /prop_tgt/DOTNET_TARGET_FRAMEWORK_VERSION diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 23d8256..99ea564 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -166,6 +166,7 @@ Variables that Change Behavior /variable/BUILD_SHARED_LIBS /variable/CMAKE_ABSOLUTE_DESTINATION_FILES + /variable/CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY /variable/CMAKE_APPBUNDLE_PATH /variable/CMAKE_AUTOMOC_RELAXED_MODE /variable/CMAKE_BACKWARDS_COMPATIBILITY @@ -226,6 +227,8 @@ Variables that Change Behavior /variable/CMAKE_INSTALL_MESSAGE /variable/CMAKE_INSTALL_PREFIX /variable/CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT + /variable/CMAKE_KATE_FILES_MODE + /variable/CMAKE_KATE_MAKE_ARGUMENTS /variable/CMAKE_LIBRARY_PATH /variable/CMAKE_LINK_DIRECTORIES_BEFORE /variable/CMAKE_LINK_LIBRARIES_ONLY_TARGETS @@ -424,7 +427,9 @@ Variables that Control the Build /variable/CMAKE_DEFAULT_CONFIGS /variable/CMAKE_DEPENDS_USE_COMPILER /variable/CMAKE_DISABLE_PRECOMPILE_HEADERS + /variable/CMAKE_DLL_NAME_WITH_SOVERSION /variable/CMAKE_ENABLE_EXPORTS + /variable/CMAKE_EXECUTABLE_ENABLE_EXPORTS /variable/CMAKE_EXE_LINKER_FLAGS /variable/CMAKE_EXE_LINKER_FLAGS_CONFIG /variable/CMAKE_EXE_LINKER_FLAGS_CONFIG_INIT @@ -504,6 +509,7 @@ Variables that Control the Build /variable/CMAKE_POSITION_INDEPENDENT_CODE /variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY /variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY_CONFIG + /variable/CMAKE_SHARED_LIBRARY_ENABLE_EXPORTS /variable/CMAKE_SHARED_LINKER_FLAGS /variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG /variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG_INIT diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index e48ecd9..1ea7626 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -9,8 +9,8 @@ Synopsis .. parsed-literal:: `Generate a Project Buildsystem`_ + cmake [<options>] -B <path-to-build> [-S <path-to-source>] cmake [<options>] <path-to-source | path-to-existing-build> - cmake [<options>] -S <path-to-source> -B <path-to-build> `Build a Project`_ cmake --build <dir> [<options>] [-- <build-tool-options>] @@ -116,6 +116,20 @@ Generate a Project Buildsystem Run CMake with one of the following command signatures to specify the source and build trees and generate a buildsystem: +``cmake [<options>] -B <path-to-build> [-S <path-to-source>]`` + + .. versionadded:: 3.13 + + Uses ``<path-to-build>`` as the build tree and ``<path-to-source>`` + as the source tree. The specified paths may be absolute or relative + to the current working directory. The source tree must contain a + ``CMakeLists.txt`` file. The build tree will be created automatically + if it does not already exist. For example: + + .. code-block:: console + + $ cmake -S src -B build + ``cmake [<options>] <path-to-source>`` Uses the current working directory as the build tree, and ``<path-to-source>`` as the source tree. The specified path may @@ -141,20 +155,6 @@ source and build trees and generate a buildsystem: $ cd build $ cmake . -``cmake [<options>] -S <path-to-source> -B <path-to-build>`` - - .. versionadded:: 3.13 - - Uses ``<path-to-build>`` as the build tree and ``<path-to-source>`` - as the source tree. The specified paths may be absolute or relative - to the current working directory. The source tree must contain a - ``CMakeLists.txt`` file. The build tree will be created automatically - if it does not already exist. For example: - - .. code-block:: console - - $ cmake -S src -B build - In all cases the ``<options>`` may be zero or more of the `Options`_ below. The above styles for specifying the source and build trees may be mixed. @@ -167,14 +167,14 @@ the current working directory (cwd) is used for the other. For example: ============================== ============ =========== Command Line Source Dir Build Dir ============================== ============ =========== + ``cmake -B build`` `cwd` ``build`` + ``cmake -B build src`` ``src`` ``build`` + ``cmake -B build -S src`` ``src`` ``build`` ``cmake src`` ``src`` `cwd` ``cmake build`` (existing) `loaded` ``build`` ``cmake -S src`` ``src`` `cwd` ``cmake -S src build`` ``src`` ``build`` ``cmake -S src -B build`` ``src`` ``build`` - ``cmake -B build`` `cwd` ``build`` - ``cmake -B build src`` ``src`` ``build`` - ``cmake -B build -S src`` ``src`` ``build`` ============================== ============ =========== .. versionchanged:: 3.23 @@ -781,7 +781,7 @@ Available commands are: (:option:`-A ... <cmake -A>`). The value is a list of platforms known to be supported. ``extraGenerators`` - A list of strings with all the extra generators compatible with + A list of strings with all the :ref:`Extra Generators` compatible with the generator. ``fileApi`` @@ -1080,11 +1080,18 @@ Available commands are: situations instead. Use ``--`` to stop interpreting options and treat all remaining arguments as paths, even if they start with ``-``. -.. option:: sleep <number>... +.. option:: sleep <number> .. versionadded:: 3.0 - Sleep for given number of seconds. + Sleep for ``<number>`` seconds. ``<number>`` may be a floating point number. + A practical minimum is about 0.1 seconds due to overhead in starting/stopping + CMake executable. This can be useful in a CMake script to insert a delay: + + .. code-block:: cmake + + # Sleep for about 0.5 seconds + execute_process(COMMAND ${CMAKE_COMMAND} -E sleep 0.5) .. option:: tar [cxt][vf][zjJ] file.tar [<options>] [--] [<pathname>...] @@ -1189,7 +1196,7 @@ Available commands are: .. option:: time <command> [<args>...] - Run command and display elapsed time. + Run ``<command>`` and display elapsed time (including overhead of CMake frontend). .. versionadded:: 3.5 The command now properly passes arguments with spaces or special characters diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index 5e82faa..994ae47 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -11,7 +11,7 @@ Synopsis .. parsed-literal:: `Run Tests`_ - ctest [<options>] + ctest [<options>] [--test-dir <path-to-build>] `Build and Test Mode`_ ctest --build-and-test <path-to-source> <path-to-build> @@ -354,7 +354,8 @@ Run Tests .. option:: --test-dir <dir> - Specify the directory in which to look for tests. + Specify the directory in which to look for tests, typically a CMake project + build directory. If not specified, the current directory is used. .. option:: --test-output-size-passed <size> diff --git a/Help/policy/CMP0144.rst b/Help/policy/CMP0144.rst new file mode 100644 index 0000000..3959d96 --- /dev/null +++ b/Help/policy/CMP0144.rst @@ -0,0 +1,26 @@ +CMP0144 +------- + +.. versionadded:: 3.27 + +:command:`find_package` uses upper-case ``<PACKAGENAME>_ROOT`` variables. + +In CMake 3.27 and above the :command:`find_package(<PackageName>)` command now +searches prefixes specified by the upper-case :variable:`<PACKAGENAME>_ROOT` +CMake variable and the :envvar:`<PACKAGENAME>_ROOT` environment variable +in addition to the case-preserved :variable:`<PackageName>_ROOT` and +:envvar:`<PackageName>_ROOT` variables used since policy :policy:`CMP0074`. +This policy provides compatibility with projects that have not been +updated to avoid using ``<PACKAGENAME>_ROOT`` variables for other purposes. + +The ``OLD`` behavior for this policy is to ignore ``<PACKAGENAME>_ROOT`` +variables if the original ``<PackageName>`` has lower-case characters. +The ``NEW`` behavior for this policy is to use ``<PACKAGENAME>_ROOT`` +variables. + +This policy was introduced in CMake version 3.27. CMake version +|release| warns when the policy is not set and uses ``OLD`` behavior. +Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` +explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0145.rst b/Help/policy/CMP0145.rst new file mode 100644 index 0000000..bb1c02e --- /dev/null +++ b/Help/policy/CMP0145.rst @@ -0,0 +1,30 @@ +CMP0145 +------- + +.. versionadded:: 3.27 + +The :module:`Dart` and :module:`FindDart` modules are removed. + +These modules were added very early in CMake's development to support +driving tests with a "DART" tool, but DART has not been distributed or +maintained for many years. Projects would ``include(Dart)`` to use it, +and the ``Dart`` module would run ``find_package(Dart)`` internally. +Since :manual:`ctest(1)` was created, the ``Dart`` module has just been +a compatibility shim that finds ``Dart`` to support some legacy +functionality and then forwards to the :module:`CTest` module. + +CMake 3.27 and above prefer to not provide the :module:`Dart` or +:module:`FindDart` modules. This policy provides compatibility for +projects that have not been ported away from them. Projects using the +``Dart`` module should be updated to use the :module:`CTest` module directly. + +The ``OLD`` behavior of this policy is for ``include(Dart)`` and +``find_package(Dart)`` to load the deprecated modules. The ``NEW`` +behavior is for uses of the modules to fail as if they do not exist. + +This policy was introduced in CMake version 3.27. CMake version +|release| warns when the policy is not set and uses ``OLD`` behavior. +Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` +explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/prop_test/WILL_FAIL.rst b/Help/prop_test/WILL_FAIL.rst index f1f94a4..4926f40 100644 --- a/Help/prop_test/WILL_FAIL.rst +++ b/Help/prop_test/WILL_FAIL.rst @@ -3,5 +3,6 @@ WILL_FAIL If set to true, this will invert the pass/fail flag of the test. -This property can be used for tests that are expected to fail and -return a non zero return code. +This property can be used for tests that are expected to fail and return a +non-zero return code. Note that system-level test failures such as segmentation +faults or heap errors will still fail the test even if ``WILL_FALL`` is true. diff --git a/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY.rst b/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY.rst index 677e06d..abb627c 100644 --- a/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY.rst +++ b/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY.rst @@ -6,4 +6,7 @@ ARCHIVE_OUTPUT_DIRECTORY .. |CMAKE_XXX_OUTPUT_DIRECTORY| replace:: :variable:`CMAKE_ARCHIVE_OUTPUT_DIRECTORY` .. include:: XXX_OUTPUT_DIRECTORY.txt +.. |IDEM| replace:: in the same directory +.. include:: MACOS_IMPORT_FILES.txt + See also the :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY_<CONFIG>` target property. diff --git a/Help/prop_tgt/ARCHIVE_OUTPUT_NAME.rst b/Help/prop_tgt/ARCHIVE_OUTPUT_NAME.rst index 6150193..1f1c467 100644 --- a/Help/prop_tgt/ARCHIVE_OUTPUT_NAME.rst +++ b/Help/prop_tgt/ARCHIVE_OUTPUT_NAME.rst @@ -5,4 +5,7 @@ ARCHIVE_OUTPUT_NAME .. |xxx| replace:: archive .. include:: XXX_OUTPUT_NAME.txt +.. |IDEM| replace:: with the same name +.. include:: MACOS_IMPORT_FILES.txt + See also the :prop_tgt:`ARCHIVE_OUTPUT_NAME_<CONFIG>` target property. diff --git a/Help/prop_tgt/DLL_NAME_WITH_SOVERSION.rst b/Help/prop_tgt/DLL_NAME_WITH_SOVERSION.rst new file mode 100644 index 0000000..59ef00f --- /dev/null +++ b/Help/prop_tgt/DLL_NAME_WITH_SOVERSION.rst @@ -0,0 +1,17 @@ +DLL_NAME_WITH_SOVERSION +----------------------- + +.. versionadded:: 3.27 + +This property control whether the :prop_tgt:`SOVERSION` target +property are added to the filename of generated DLL filenames +for the Windows platform, which is selected when the +:variable:`WIN32` variable is set. + +The value of the listed property is appended to the +basename of the runtime component of the shared library +target as ``-<SOVERSION>``. + +Please note that setting this property has no effect +if versioned filenames are globally disabled with the +:variable:`CMAKE_PLATFORM_NO_VERSIONED_SONAME` variable. diff --git a/Help/prop_tgt/ENABLE_EXPORTS.rst b/Help/prop_tgt/ENABLE_EXPORTS.rst index 0b1064a..3e9b285 100644 --- a/Help/prop_tgt/ENABLE_EXPORTS.rst +++ b/Help/prop_tgt/ENABLE_EXPORTS.rst @@ -1,7 +1,7 @@ ENABLE_EXPORTS -------------- -Specify whether an executable exports symbols for loadable modules. +Specify whether an executable or a shared library exports symbols. Normally an executable does not export any symbols because it is the final program. It is possible for an executable to export symbols to @@ -28,4 +28,29 @@ varies by platform: automatically bind symbols when the module is loaded. This property is initialized by the value of the variable -:variable:`CMAKE_ENABLE_EXPORTS` if it is set when a target is created. +:variable:`CMAKE_EXECUTABLE_ENABLE_EXPORTS` if it is set when an executable +target is created. + +.. versionadded:: 3.27 + On macOS, to link with a shared library (standard one as well as framework), + a linker import file (e.g. a text-based stubs file, with ``.tbd`` extension) + can be used instead of the shared library itself. + +The generation of these linker import files, as well as the consumption, is +controlled by this property. When this property is set to true, CMake will +generate a ``.tbd`` file for each shared library created by +:command:`add_library` command. This allow other targets to use this ``.tbd`` +file to link to the library with the :command:`target_link_libraries` +command. + +.. note:: + + For compatibility purpose, this property will be ignored if + :prop_tgt:`XCODE_ATTRIBUTE_GENERATE_TEXT_BASED_STUBS <XCODE_ATTRIBUTE_<an-attribute>>` + target property or the + :variable:`CMAKE_XCODE_ATTRIBUTE_GENERATE_TEXT_BASED_STUBS <CMAKE_XCODE_ATTRIBUTE_<an-attribute>>` + variable is set to ``NO``. + +This property is initialized by the value of the variable +:variable:`CMAKE_SHARED_LIBRARY_ENABLE_EXPORTS` if it is set when a shared +library target is created. diff --git a/Help/prop_tgt/IMPORTED_CONFIGURATIONS.rst b/Help/prop_tgt/IMPORTED_CONFIGURATIONS.rst index 6de1baa..8605548 100644 --- a/Help/prop_tgt/IMPORTED_CONFIGURATIONS.rst +++ b/Help/prop_tgt/IMPORTED_CONFIGURATIONS.rst @@ -1,11 +1,20 @@ IMPORTED_CONFIGURATIONS ----------------------- -Configurations provided for an IMPORTED target. - -Set this to the list of configuration names available for an IMPORTED -target. The names correspond to configurations defined in the project -from which the target is imported. If the importing project uses a -different set of configurations the names may be mapped using the -MAP_IMPORTED_CONFIG_<CONFIG> property. Ignored for non-imported -targets. +Configurations provided for an :ref:`imported target <Imported targets>`. + +Set this to the list of configuration names available for an imported +target. For each configuration named, the imported target's artifacts +must be specified in other target properties: + +* :prop_tgt:`IMPORTED_LOCATION_<CONFIG>`, or +* :prop_tgt:`IMPORTED_IMPLIB_<CONFIG>` (on DLL platforms), or +* :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>` (for :ref:`Object Libraries`), or +* :prop_tgt:`IMPORTED_LIBNAME_<CONFIG>` (for :ref:`Interface Libraries`). + +The configuration names correspond to those defined in the project from +which the target is imported. If the importing project uses a different +set of configurations, the names may be mapped using the +:prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` target property. + +The ``IMPORTED_CONFIGURATIONS`` property is ignored for non-imported targets. diff --git a/Help/prop_tgt/IMPORTED_IMPLIB.rst b/Help/prop_tgt/IMPORTED_IMPLIB.rst index c8b6fde..e67acba 100644 --- a/Help/prop_tgt/IMPORTED_IMPLIB.rst +++ b/Help/prop_tgt/IMPORTED_IMPLIB.rst @@ -3,7 +3,22 @@ IMPORTED_IMPLIB Full path to the import library for an ``IMPORTED`` target. -Set this to the location of the ``.lib`` part of a Windows DLL, or on -AIX set it to an import file created for executables that export symbols -(see the :prop_tgt:`ENABLE_EXPORTS` target property). -Ignored for non-imported targets. +This property may be set: + +* On DLL platforms, to the location of the ``.lib`` part of the DLL. +* On AIX, to an import file (e.g. ``.imp``) created for executables that export + symbols (see the :prop_tgt:`ENABLE_EXPORTS` target property). +* On macOS, to an import file (e.g. ``.tbd``) created for shared libraries (see + the :prop_tgt:`ENABLE_EXPORTS` target property). For frameworks this is the + location of the ``.tbd`` file symlink just inside the framework folder. + +The ``IMPORTED_IMPLIB`` target property may be overridden for a +given configuration ``<CONFIG>`` by the configuration-specific +:prop_tgt:`IMPORTED_IMPLIB_<CONFIG>` target property. Furthermore, +the :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` target property may be +used to map between a project's configurations and those of an imported +target. If none of these is set then the name of any other configuration +listed in the :prop_tgt:`IMPORTED_CONFIGURATIONS` target property may be +selected and its :prop_tgt:`IMPORTED_IMPLIB_<CONFIG>` value used. + +This property is ignored for non-imported targets. diff --git a/Help/prop_tgt/IMPORTED_LOCATION.rst b/Help/prop_tgt/IMPORTED_LOCATION.rst index ddd910a..a7207d8 100644 --- a/Help/prop_tgt/IMPORTED_LOCATION.rst +++ b/Help/prop_tgt/IMPORTED_LOCATION.rst @@ -27,5 +27,5 @@ selected and its :prop_tgt:`IMPORTED_LOCATION_<CONFIG>` value used. To get the location of an imported target read one of the :prop_tgt:`LOCATION` or ``LOCATION_<CONFIG>`` properties. -For platforms with import libraries (e.g. Windows) see also +For platforms with import libraries (e.g. Windows, AIX or macOS) see also :prop_tgt:`IMPORTED_IMPLIB`. diff --git a/Help/prop_tgt/LANG_LINKER_LAUNCHER.rst b/Help/prop_tgt/LANG_LINKER_LAUNCHER.rst index f6ca5ad..d39ec20 100644 --- a/Help/prop_tgt/LANG_LINKER_LAUNCHER.rst +++ b/Help/prop_tgt/LANG_LINKER_LAUNCHER.rst @@ -14,3 +14,8 @@ arguments to the tool. This is useful for tools such as static analyzers. This property is initialized by the value of the :variable:`CMAKE_<LANG>_LINKER_LAUNCHER` variable if it is set when a target is created. + +.. versionadded:: 3.27 + + The property value may use + :manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/prop_tgt/MACOS_IMPORT_FILES.txt b/Help/prop_tgt/MACOS_IMPORT_FILES.txt new file mode 100644 index 0000000..3c98fc8 --- /dev/null +++ b/Help/prop_tgt/MACOS_IMPORT_FILES.txt @@ -0,0 +1,12 @@ +.. note:: + + On macOS, this property will be ignored for the linker import files (e.g. + ``.tbd`` files, see :prop_tgt:`ENABLE_EXPORTS` property for details) when: + + * The :prop_tgt:`FRAMEWORK` is set, because the framework layout cannot be + changed. + * The :generator:`Xcode` generator is used, due to the limitations and + constraints of the ``Xcode`` tool. + + In both cases, the linker import files will be generated |IDEM| as the shared + library. diff --git a/Help/release/dev/0-sample-topic.rst b/Help/release/dev/0-sample-topic.rst new file mode 100644 index 0000000..e4cc01e --- /dev/null +++ b/Help/release/dev/0-sample-topic.rst @@ -0,0 +1,7 @@ +0-sample-topic +-------------- + +* This is a sample release note for the change in a topic. + Developers should add similar notes for each topic branch + making a noteworthy change. Each document should be named + and titled to match the topic name to avoid merge conflicts. diff --git a/Help/release/dev/Apple-tbd-files-management.rst b/Help/release/dev/Apple-tbd-files-management.rst new file mode 100644 index 0000000..edcfe55 --- /dev/null +++ b/Help/release/dev/Apple-tbd-files-management.rst @@ -0,0 +1,6 @@ +Apple-tbd-files-management +-------------------------- + +* Support for text-based stubs (i.e. ``.tbd`` files) was added on macOS + platform. This capability is managed through the :prop_tgt:`ENABLE_EXPORTS` + property. diff --git a/Help/release/dev/PATH-genex-support-list.rst b/Help/release/dev/PATH-genex-support-list.rst new file mode 100644 index 0000000..ce87fdd --- /dev/null +++ b/Help/release/dev/PATH-genex-support-list.rst @@ -0,0 +1,5 @@ +PATH-genex-supports-list +------------------------ + +* The :genex:`$<PATH>` generator expression learned to process list of paths + for decomposition and transformation operations. diff --git a/Help/release/dev/deprecate-extra-generators.rst b/Help/release/dev/deprecate-extra-generators.rst new file mode 100644 index 0000000..ceb2f4e --- /dev/null +++ b/Help/release/dev/deprecate-extra-generators.rst @@ -0,0 +1,5 @@ +deprecate-extra-generators +-------------------------- + +* The :ref:`Extra Generators` have been deprecated. IDEs may use the + :manual:`cmake-file-api(7)` to view CMake-generated project build trees. diff --git a/Help/release/dev/deprecate-policy-old.rst b/Help/release/dev/deprecate-policy-old.rst new file mode 100644 index 0000000..9c38866 --- /dev/null +++ b/Help/release/dev/deprecate-policy-old.rst @@ -0,0 +1,7 @@ +deprecate-policy-old +-------------------- + +* Compatibility with versions of CMake older than 3.5 is now deprecated + and will be removed from a future version. Calls to + :command:`cmake_minimum_required` or :command:`cmake_policy` that set + the policy version to an older value now issue a deprecation diagnostic. diff --git a/Help/release/dev/dll-name-soversion.rst b/Help/release/dev/dll-name-soversion.rst new file mode 100644 index 0000000..56d0842 --- /dev/null +++ b/Help/release/dev/dll-name-soversion.rst @@ -0,0 +1,7 @@ +dll-name-soversion +------------------ + +* The :variable:`CMAKE_DLL_NAME_WITH_SOVERSION` variable and associated + :prop_tgt:`DLL_NAME_WITH_SOVERSION` target property were added to + optionally append the :prop_tgt:`SOVERSION` to the filename of the + ``.dll`` part of a shared library on Windows. diff --git a/Help/release/dev/find_package-PACKAGENAME_ROOT.rst b/Help/release/dev/find_package-PACKAGENAME_ROOT.rst new file mode 100644 index 0000000..0388271 --- /dev/null +++ b/Help/release/dev/find_package-PACKAGENAME_ROOT.rst @@ -0,0 +1,7 @@ +find_package-PACKAGENAME_ROOT +----------------------------- + +* The :command:`find_package` command now searches prefixes specified by + upper-case :variable:`<PACKAGENAME>_ROOT` CMake variables and upper-case + :envvar:`<PACKAGENAME>_ROOT` environment variables. + See policy :policy:`CMP0144`. diff --git a/Help/release/dev/install-prefix-genex-install-code-script.rst b/Help/release/dev/install-prefix-genex-install-code-script.rst new file mode 100644 index 0000000..810f448 --- /dev/null +++ b/Help/release/dev/install-prefix-genex-install-code-script.rst @@ -0,0 +1,5 @@ +install-prefix-genex-install-code-script +---------------------------------------- + +* The :command:`install(CODE)` and :command:`install(SCRIPT)` commands + now support the :genex:`$<INSTALL_PREFIX>` generator expression. diff --git a/Help/release/dev/lang-linker-launcher-genex.rst b/Help/release/dev/lang-linker-launcher-genex.rst new file mode 100644 index 0000000..b6494eb --- /dev/null +++ b/Help/release/dev/lang-linker-launcher-genex.rst @@ -0,0 +1,5 @@ +lang-linker-launcher-genex +-------------------------- + +* The :prop_tgt:`<LANG>_LINKER_LAUNCHER` target property now supports + :manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/release/dev/ninja-custom-command-depends.rst b/Help/release/dev/ninja-custom-command-depends.rst new file mode 100644 index 0000000..0b7840c --- /dev/null +++ b/Help/release/dev/ninja-custom-command-depends.rst @@ -0,0 +1,11 @@ +ninja-custom-command-depends +---------------------------- + +* The :command:`add_custom_command` command gained a new + ``DEPENDS_EXPLICIT_ONLY`` option to tell the :ref:`Ninja Generators` + not to add any dependencies implied by the target to which it is + attached. + +* The :variable:`CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY` variable can + be set to enable ``DEPENDS_EXPLICIT_ONLY`` in all uses of + :command:`add_custom_command` command. diff --git a/Help/release/dev/remove-dart-modules.rst b/Help/release/dev/remove-dart-modules.rst new file mode 100644 index 0000000..5da2eda --- /dev/null +++ b/Help/release/dev/remove-dart-modules.rst @@ -0,0 +1,5 @@ +remove-dart-modules +------------------- + +* The :module:`Dart` and :module:`FindDart` modules have been deprecated via + policy :policy:`CMP0145`. Port projects to the :module:`CTest` module. diff --git a/Help/release/dev/vs9-deprecate.rst b/Help/release/dev/vs9-deprecate.rst new file mode 100644 index 0000000..46568f8 --- /dev/null +++ b/Help/release/dev/vs9-deprecate.rst @@ -0,0 +1,5 @@ +vs9-deprecate +------------- + +* The :generator:`Visual Studio 9 2008` generator is now deprecated + and will be removed in a future version of CMake. diff --git a/Help/release/index.rst b/Help/release/index.rst index c82889f..d434a3a 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -7,6 +7,8 @@ CMake Release Notes This file should include the adjacent "dev.txt" file in development versions but not in release versions. +.. include:: dev.txt + Releases ======== diff --git a/Help/variable/CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY.rst b/Help/variable/CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY.rst new file mode 100644 index 0000000..9c9bd2c --- /dev/null +++ b/Help/variable/CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY.rst @@ -0,0 +1,11 @@ +CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY +---------------------------------------------- + +.. versionadded:: 3.27 + +Whether to enable DEPENDS_EXPLICIT_ONLY option by default in +:command:`add_custom_command`. + +This variable affects the default behavior of the :command:`add_custom_command` +command. Setting this variable to ``ON`` is equivalent to using the ``DEPENDS_EXPLICIT_ONLY`` +option in all uses of that command. diff --git a/Help/variable/CMAKE_DLL_NAME_WITH_SOVERSION.rst b/Help/variable/CMAKE_DLL_NAME_WITH_SOVERSION.rst new file mode 100644 index 0000000..5fa49de --- /dev/null +++ b/Help/variable/CMAKE_DLL_NAME_WITH_SOVERSION.rst @@ -0,0 +1,14 @@ +CMAKE_DLL_NAME_WITH_SOVERSION +----------------------------- + +.. versionadded:: 3.27 + +This variable is used to initialize the :prop_tgt:`DLL_NAME_WITH_SOVERSION` +property on shared library targets for the Windows platform, which is selected +when the :variable:`WIN32` variable is set. + +See this target property for additional information. + +Please note that setting this variable has no effect if versioned filenames +are globally disabled with the :variable:`CMAKE_PLATFORM_NO_VERSIONED_SONAME` +variable. diff --git a/Help/variable/CMAKE_EDIT_COMMAND.rst b/Help/variable/CMAKE_EDIT_COMMAND.rst index 2f4ab1f..b21434f 100644 --- a/Help/variable/CMAKE_EDIT_COMMAND.rst +++ b/Help/variable/CMAKE_EDIT_COMMAND.rst @@ -2,7 +2,8 @@ CMAKE_EDIT_COMMAND ------------------ Full path to :manual:`cmake-gui(1)` or :manual:`ccmake(1)`. Defined only for -:ref:`Makefile Generators` when not using an "extra" generator for an IDE. +:ref:`Makefile Generators` and :ref:`Ninja Generators` when not using any +:ref:`Extra Generators`. This is the full path to the CMake executable that can graphically edit the cache. For example, :manual:`cmake-gui(1)` or :manual:`ccmake(1)`. diff --git a/Help/variable/CMAKE_ENABLE_EXPORTS.rst b/Help/variable/CMAKE_ENABLE_EXPORTS.rst index 9f43de3..d2c5ed0 100644 --- a/Help/variable/CMAKE_ENABLE_EXPORTS.rst +++ b/Help/variable/CMAKE_ENABLE_EXPORTS.rst @@ -8,3 +8,7 @@ Specify whether executables export symbols for loadable modules. This variable is used to initialize the :prop_tgt:`ENABLE_EXPORTS` target property for executable targets when they are created by calls to the :command:`add_executable` command. See the property documentation for details. + +This command has been superseded by the +:variable:`CMAKE_EXECUTABLE_ENABLE_EXPORTS` command. It is provided for +compatibility with older CMake code. diff --git a/Help/variable/CMAKE_EXECUTABLE_ENABLE_EXPORTS.rst b/Help/variable/CMAKE_EXECUTABLE_ENABLE_EXPORTS.rst new file mode 100644 index 0000000..aa6dda2 --- /dev/null +++ b/Help/variable/CMAKE_EXECUTABLE_ENABLE_EXPORTS.rst @@ -0,0 +1,12 @@ +CMAKE_EXECUTABLE_ENABLE_EXPORTS +------------------------------- + +.. versionadded:: 3.27 + +Specify whether executables export symbols for loadable modules. + +This variable is used to initialize the :prop_tgt:`ENABLE_EXPORTS` target +property for executable targets when they are created by calls to the +:command:`add_executable` command. See the property documentation for details. + +This variable supersede the :variable:`CMAKE_ENABLE_EXPORTS` variable. diff --git a/Help/variable/CMAKE_EXTRA_GENERATOR.rst b/Help/variable/CMAKE_EXTRA_GENERATOR.rst index 2c92323..0a113a5 100644 --- a/Help/variable/CMAKE_EXTRA_GENERATOR.rst +++ b/Help/variable/CMAKE_EXTRA_GENERATOR.rst @@ -1,6 +1,12 @@ CMAKE_EXTRA_GENERATOR --------------------- +.. deprecated:: 3.27 + + Support for :ref:`Extra Generators` is deprecated and will be removed from + a future version of CMake. IDEs may use the :manual:`cmake-file-api(7)` + to view CMake-generated project build trees. + The extra generator used to build the project. See :manual:`cmake-generators(7)`. diff --git a/Help/variable/CMAKE_KATE_FILES_MODE.rst b/Help/variable/CMAKE_KATE_FILES_MODE.rst new file mode 100644 index 0000000..195c15d --- /dev/null +++ b/Help/variable/CMAKE_KATE_FILES_MODE.rst @@ -0,0 +1,20 @@ +CMAKE_KATE_FILES_MODE +--------------------- + +.. versionadded:: 3.27 + +This cache variable is used by the Kate project generator and controls +to what mode the ``files`` entry in the project file will be set. See +:manual:`cmake-generators(7)`. + +Possible values are ``AUTO``, ``SVN``, ``GIT``, ``HG``, ``FOSSIL`` and ``LIST``. + +When set to ``LIST``, CMake will put the list of source files known to CMake +in the project file. +When set to ``SVN``, ``GIT``, ``HG`` or ``FOSSIL``, CMake will set +the generated project accordingly to Subversion, git, Mercurial +or Fossil, and Kate will then use the respective command line tool to +retrieve the list of files in the project. +When unset or set to ``AUTO``, CMake will try to detect whether the +source directory is part of a git or svn checkout or not, and put the +respective entry into the project file. diff --git a/Help/variable/CMAKE_KATE_MAKE_ARGUMENTS.rst b/Help/variable/CMAKE_KATE_MAKE_ARGUMENTS.rst new file mode 100644 index 0000000..c830332 --- /dev/null +++ b/Help/variable/CMAKE_KATE_MAKE_ARGUMENTS.rst @@ -0,0 +1,11 @@ +CMAKE_KATE_MAKE_ARGUMENTS +------------------------- + +.. versionadded:: 3.0 + +This cache variable is used by the Kate project generator. See +:manual:`cmake-generators(7)`. + +This variable holds arguments which are used when Kate invokes the make +tool. By default it is initialized to hold flags to enable parallel builds +(using -j typically). diff --git a/Help/variable/CMAKE_SHARED_LIBRARY_ENABLE_EXPORTS.rst b/Help/variable/CMAKE_SHARED_LIBRARY_ENABLE_EXPORTS.rst new file mode 100644 index 0000000..3e2c6df --- /dev/null +++ b/Help/variable/CMAKE_SHARED_LIBRARY_ENABLE_EXPORTS.rst @@ -0,0 +1,10 @@ +CMAKE_SHARED_LIBRARY_ENABLE_EXPORTS +----------------------------------- + +.. versionadded:: 3.27 + +Specify whether shared library generates an import file. + +This variable is used to initialize the :prop_tgt:`ENABLE_EXPORTS` target +property for shared library targets when they are created by calls to the +:command:`add_library` command. See the property documentation for details. diff --git a/Help/variable/PackageName_ROOT.rst b/Help/variable/PackageName_ROOT.rst index 6b17be3..8b728ba 100644 --- a/Help/variable/PackageName_ROOT.rst +++ b/Help/variable/PackageName_ROOT.rst @@ -14,3 +14,11 @@ This variable may hold a single prefix or a :ref:`semicolon-separated list <CMake Language Lists>` of multiple prefixes. See also the :envvar:`<PackageName>_ROOT` environment variable. + +.. variable:: <PACKAGENAME>_ROOT + + .. versionadded:: 3.27 + + Calls to :command:`find_package(<PackageName>)` will also search in + prefixes specified by the upper-case ``<PACKAGENAME>_ROOT`` CMake + variable. See policy :policy:`CMP0144`. |