diff options
Diffstat (limited to 'Help')
242 files changed, 6052 insertions, 327 deletions
diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index dde4dbb..42bf52b 100644 --- a/Help/command/FIND_XXX.txt +++ b/Help/command/FIND_XXX.txt @@ -79,17 +79,19 @@ 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. If called from within a find module loaded by +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. Specifically look in 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, root paths from the parent's find module will be - searched after paths from the current module, - i.e. ``<CurrentPackage>_ROOT``, ``ENV{<CurrentPackage>_ROOT}``, + 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. + 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`. * |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| @@ -97,7 +99,8 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: 2. Search paths specified in cmake-specific cache variables. These are intended to be used on the command line with a ``-DVAR=value``. The values are interpreted as :ref:`semicolon-separated lists <CMake Language Lists>`. - This can be skipped if ``NO_CMAKE_PATH`` is passed. + This can be skipped if ``NO_CMAKE_PATH`` is passed or by setting the + :variable:`CMAKE_FIND_USE_CMAKE_PATH` to ``FALSE``. * |CMAKE_PREFIX_PATH_XXX| * |CMAKE_XXX_PATH| @@ -107,7 +110,8 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: These are intended to be set in the user's shell configuration, and therefore use the host's native path separator (``;`` on Windows and ``:`` on UNIX). - This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed. + This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed or + by setting the :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` to ``FALSE``. * |CMAKE_PREFIX_PATH_XXX| * |CMAKE_XXX_PATH| @@ -119,13 +123,16 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: Hard-coded guesses should be specified with the ``PATHS`` option. 5. Search the standard system environment variables. - This can be skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is an argument. + This can be skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is passed or by + setting the :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH` to ``FALSE``. * |SYSTEM_ENVIRONMENT_PATH_XXX| + * |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| 6. Search cmake variables defined in the Platform files for the current system. This can be skipped if ``NO_CMAKE_SYSTEM_PATH`` - is passed. + is passed or by setting the :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH` + to ``FALSE``. * |CMAKE_SYSTEM_PREFIX_PATH_XXX| * |CMAKE_SYSTEM_XXX_PATH| diff --git a/Help/command/LINK_OPTIONS_LINKER.txt b/Help/command/LINK_OPTIONS_LINKER.txt index a723375..3f66181 100644 --- a/Help/command/LINK_OPTIONS_LINKER.txt +++ b/Help/command/LINK_OPTIONS_LINKER.txt @@ -1,8 +1,8 @@ -To pass options to the linker tool, each compiler driver has is own syntax. -The ``LINKER:`` prefix can be used to specify, in a portable way, options -to pass to the linker tool. The ``LINKER:`` prefix is replaced by the required -driver option and the rest of the option string defines linker arguments using -``,`` as separator. These arguments will be formatted according to the +To pass options to the linker tool, each compiler driver has its own syntax. +The ``LINKER:`` prefix and ``,`` separator can be used to specify, in a portable +way, options to pass to the linker tool. ``LINKER:`` is replaced by the +appropriate driver option and ``,`` by the appropriate driver separator. +The driver prefix and driver separator are given by the values of the :variable:`CMAKE_<LANG>_LINKER_WRAPPER_FLAG` and :variable:`CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP` variables. @@ -12,11 +12,11 @@ For example, ``"LINKER:-z,defs"`` becomes ``-Xlinker -z -Xlinker defs`` for The ``LINKER:`` prefix can be specified as part of a ``SHELL:`` prefix expression. -The ``LINKER:`` prefix supports, as alternate syntax, specification of -arguments using ``SHELL:`` prefix and space as separator. Previous example -becomes ``"LINKER:SHELL:-z defs"``. +The ``LINKER:`` prefix supports, as an alternative syntax, specification of +arguments using the ``SHELL:`` prefix and space as separator. The previous +example then becomes ``"LINKER:SHELL:-z defs"``. .. note:: - Specifying ``SHELL:`` prefix elsewhere than at the beginning of the + Specifying the ``SHELL:`` prefix anywhere other than at the beginning of the ``LINKER:`` prefix is not supported. diff --git a/Help/command/OPTIONS_SHELL.txt b/Help/command/OPTIONS_SHELL.txt index 530c012..0f8ec32 100644 --- a/Help/command/OPTIONS_SHELL.txt +++ b/Help/command/OPTIONS_SHELL.txt @@ -1,9 +1,9 @@ The final set of compile or link options used for a target is constructed by accumulating options from the current target and the usage requirements of -it dependencies. The set of options is de-duplicated to avoid repetition. +its dependencies. The set of options is de-duplicated to avoid repetition. While beneficial for individual options, the de-duplication step can break up option groups. For example, ``-D A -D B`` becomes ``-D A B``. One may specify a group of options using shell-like quoting along with a ``SHELL:`` -prefix. The ``SHELL:`` prefix is dropped and the rest of the option string +prefix. The ``SHELL:`` prefix is dropped, and the rest of the option string is parsed using the :command:`separate_arguments` ``UNIX_COMMAND`` mode. For example, ``"SHELL:-D A" "SHELL:-D B"`` becomes ``-D A -D B``. diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index ed321fc..aba3742 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -68,9 +68,6 @@ The options are: order-only dependencies to ensure the byproducts will be available before their dependents build. - The ``BYPRODUCTS`` option is ignored on non-Ninja generators - except to mark byproducts ``GENERATED``. - ``COMMAND`` Specify the command-line(s) to execute at build time. If more than one ``COMMAND`` is specified they will be executed in order, @@ -82,25 +79,33 @@ The options are: will be ignored. If ``COMMAND`` specifies an executable target name (created by the - :command:`add_executable` command) it will automatically be replaced - by the location of the executable created at build time. If set, the - :prop_tgt:`CROSSCOMPILING_EMULATOR` executable target property will - also be prepended to the command to allow the executable to run on - the host. - (Use the ``TARGET_FILE`` - :manual:`generator expression <cmake-generator-expressions(7)>` to - reference an executable later in the command line.) - Additionally a target-level dependency will be added so that the - executable target will be built before any target using this custom - command. However this does NOT add a file-level dependency that - would cause the custom command to re-run whenever the executable is - recompiled. + :command:`add_executable` command), it will automatically be replaced + by the location of the executable created at build time if either of + the following is true: + + * The target is not being cross-compiled (i.e. the + :variable:`CMAKE_CROSSCOMPILING` variable is not set to true). + * The target is being cross-compiled and an emulator is provided (i.e. + its :prop_tgt:`CROSSCOMPILING_EMULATOR` target property is set). + In this case, the contents of :prop_tgt:`CROSSCOMPILING_EMULATOR` will be + prepended to the command before the location of the target executable. + + If neither of the above conditions are met, it is assumed that the + command name is a program to be found on the ``PATH`` at build time. Arguments to ``COMMAND`` may use :manual:`generator expressions <cmake-generator-expressions(7)>`. - References to target names in generator expressions imply target-level - dependencies, but NOT file-level dependencies. List target names with - the ``DEPENDS`` option to add file-level dependencies. + Use the ``TARGET_FILE`` generator expression to refer to the location of + a target later in the command line (i.e. as a command argument rather + than as the command to execute). + + Whenever a target is used as a command to execute or is mentioned in a + generator expression as a command argument, a target-level dependency + will be added automatically so that the mentioned target will be built + before any target using this custom command. However this does NOT add + a file-level dependency that would cause the custom command to re-run + whenever the executable is recompiled. List target names with + the ``DEPENDS`` option to add such file-level dependencies. ``COMMENT`` Display the given message before the commands are executed at @@ -111,6 +116,9 @@ The options are: an ``OUTPUT`` of another custom command in the same directory (``CMakeLists.txt`` file) CMake automatically brings the other custom command into the target in which this command is built. + A target-level dependency is added if any dependency is listed as + ``BYPRODUCTS`` of a target or any of its build events in the same + directory to ensure the byproducts will be available. If ``DEPENDS`` is not specified the command will run whenever the ``OUTPUT`` is missing; if the command does not actually create the ``OUTPUT`` then the rule will always run. @@ -219,7 +227,8 @@ target is already built, the command will not execute. [BYPRODUCTS [files...]] [WORKING_DIRECTORY dir] [COMMENT comment] - [VERBATIM] [USES_TERMINAL]) + [VERBATIM] [USES_TERMINAL] + [COMMAND_EXPAND_LISTS]) This defines a new command that will be associated with building the specified ``<target>``. The ``<target>`` must be defined in the current diff --git a/Help/command/add_custom_target.rst b/Help/command/add_custom_target.rst index 08b9516..2d5f5f0 100644 --- a/Help/command/add_custom_target.rst +++ b/Help/command/add_custom_target.rst @@ -49,9 +49,6 @@ The options are: order-only dependencies to ensure the byproducts will be available before their dependents build. - The ``BYPRODUCTS`` option is ignored on non-Ninja generators - except to mark byproducts ``GENERATED``. - ``COMMAND`` Specify the command-line(s) to execute at build time. If more than one ``COMMAND`` is specified they will be executed in order, @@ -61,18 +58,30 @@ The options are: a ``COMMAND`` to launch it.) If ``COMMAND`` specifies an executable target name (created by the - :command:`add_executable` command) it will automatically be replaced - by the location of the executable created at build time. If set, the - :prop_tgt:`CROSSCOMPILING_EMULATOR` executable target property will - also be prepended to the command to allow the executable to run on - the host. - Additionally a target-level dependency will be added so that the - executable target will be built before this custom target. + :command:`add_executable` command), it will automatically be replaced + by the location of the executable created at build time if either of + the following is true: + + * The target is not being cross-compiled (i.e. the + :variable:`CMAKE_CROSSCOMPILING` variable is not set to true). + * The target is being cross-compiled and an emulator is provided (i.e. + its :prop_tgt:`CROSSCOMPILING_EMULATOR` target property is set). + In this case, the contents of :prop_tgt:`CROSSCOMPILING_EMULATOR` will be + prepended to the command before the location of the target executable. + + If neither of the above conditions are met, it is assumed that the + command name is a program to be found on the ``PATH`` at build time. Arguments to ``COMMAND`` may use :manual:`generator expressions <cmake-generator-expressions(7)>`. - References to target names in generator expressions imply target-level - dependencies. + Use the ``TARGET_FILE`` generator expression to refer to the location of + a target later in the command line (i.e. as a command argument rather + than as the command to execute). + + Whenever a target is used as a command to execute or is mentioned in a + generator expression as a command argument, a target-level dependency + will be added automatically so that the mentioned target will be built + before this custom target. The command and arguments are optional and if not specified an empty target will be created. @@ -86,6 +95,9 @@ The options are: :command:`add_custom_command` command calls in the same directory (``CMakeLists.txt`` file). They will be brought up to date when the target is built. + A target-level dependency is added if any dependency is a byproduct + of a target or any of its build events in the same directory to ensure + the byproducts will be available before this target is built. Use the :command:`add_dependencies` command to add dependencies on other targets. diff --git a/Help/command/add_test.rst b/Help/command/add_test.rst index 46b9b63..a77ba37 100644 --- a/Help/command/add_test.rst +++ b/Help/command/add_test.rst @@ -7,7 +7,8 @@ Add a test to the project to be run by :manual:`ctest(1)`. add_test(NAME <name> COMMAND <command> [<arg>...] [CONFIGURATIONS <config>...] - [WORKING_DIRECTORY <dir>]) + [WORKING_DIRECTORY <dir>] + [COMMAND_EXPAND_LISTS]) Adds a test called ``<name>``. The test name may not contain spaces, quotes, or other characters special in CMake syntax. The options are: @@ -28,12 +29,18 @@ quotes, or other characters special in CMake syntax. The options are: directory set to the build directory corresponding to the current source directory. +``COMMAND_EXPAND_LISTS`` + 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` or -:prop_test:`FAIL_REGULAR_EXPRESSION` test property is used. +unless the :prop_test:`PASS_REGULAR_EXPRESSION`, +:prop_test:`FAIL_REGULAR_EXPRESSION` or +:prop_test:`SKIP_REGULAR_EXPRESSION` test property is used. The ``COMMAND`` and ``WORKING_DIRECTORY`` options may use "generator expressions" with the syntax ``$<...>``. See the diff --git a/Help/command/ctest_coverage.rst b/Help/command/ctest_coverage.rst index 8d27b9c..d50f634 100644 --- a/Help/command/ctest_coverage.rst +++ b/Help/command/ctest_coverage.rst @@ -8,7 +8,7 @@ Perform the :ref:`CTest Coverage Step` as a :ref:`Dashboard Client`. ctest_coverage([BUILD <build-dir>] [APPEND] [LABELS <label>...] [RETURN_VALUE <result-var>] - [CAPTURE_CMAKE_ERROR <result-var] + [CAPTURE_CMAKE_ERROR <result-var>] [QUIET] ) diff --git a/Help/command/ctest_start.rst b/Help/command/ctest_start.rst index 6db9a48..f0704ac 100644 --- a/Help/command/ctest_start.rst +++ b/Help/command/ctest_start.rst @@ -5,9 +5,9 @@ Starts the testing for a given model :: - ctest_start(<model> [<source> [<binary>]] [TRACK <track>] [QUIET]) + ctest_start(<model> [<source> [<binary>]] [GROUP <group>] [QUIET]) - ctest_start([<model> [<source> [<binary>]]] [TRACK <track>] APPEND [QUIET]) + ctest_start([<model> [<source> [<binary>]]] [GROUP <group>] APPEND [QUIET]) Starts the testing for a given model. The command should be called after the binary directory is initialized. @@ -26,20 +26,21 @@ The parameters are as follows: Set the binary directory. If not specified, the value of :variable:`CTEST_BINARY_DIRECTORY` is used instead. -``TRACK <track>`` - If ``TRACK`` is used, the submissions will go to the specified track on the - CDash server. If no ``TRACK`` is specified, the name of the model is used by - default. +``GROUP <group>`` + If ``GROUP`` is used, the submissions will go to the specified group on the + CDash server. If no ``GROUP`` is specified, the name of the model is used by + default. This replaces the deprecated option ``TRACK``. Despite the name + change its behavior is unchanged. ``APPEND`` If ``APPEND`` is used, the existing ``TAG`` is used rather than creating a new one based on the current time stamp. If you use ``APPEND``, you can omit the - ``<model>`` and ``TRACK <track>`` parameters, because they will be read from + ``<model>`` and ``GROUP <group>`` parameters, because they will be read from the generated ``TAG`` file. For example: .. code-block:: cmake - ctest_start(Experimental TRACK TrackExperimental) + ctest_start(Experimental GROUP GroupExperimental) Later, in another ``ctest -S`` script: @@ -48,11 +49,11 @@ The parameters are as follows: ctest_start(APPEND) When the second script runs ``ctest_start(APPEND)``, it will read the - ``Experimental`` model and ``TrackExperimental`` track from the ``TAG`` file + ``Experimental`` model and ``GroupExperimental`` group from the ``TAG`` file generated by the first ``ctest_start()`` command. Please note that if you - call ``ctest_start(APPEND)`` and specify a different model or track than + call ``ctest_start(APPEND)`` and specify a different model or group than in the first ``ctest_start()`` command, a warning will be issued, and the - new model and track will be used. + new model and group will be used. ``QUIET`` If ``QUIET`` is used, CTest will suppress any non-error messages that it @@ -65,11 +66,11 @@ equivalent: .. code-block:: cmake - ctest_start(Experimental path/to/source path/to/binary TRACK SomeTrack QUIET APPEND) + ctest_start(Experimental path/to/source path/to/binary GROUP SomeGroup QUIET APPEND) - ctest_start(TRACK SomeTrack Experimental QUIET path/to/source APPEND path/to/binary) + ctest_start(GROUP SomeGroup Experimental QUIET path/to/source APPEND path/to/binary) - ctest_start(APPEND QUIET Experimental path/to/source TRACK SomeTrack path/to/binary) + ctest_start(APPEND QUIET Experimental path/to/source GROUP SomeGroup path/to/binary) However, for the sake of readability, it is recommended that you order your parameters in the order listed at the top of this page. diff --git a/Help/command/ctest_test.rst b/Help/command/ctest_test.rst index 4a69491..7a3393b 100644 --- a/Help/command/ctest_test.rst +++ b/Help/command/ctest_test.rst @@ -17,6 +17,7 @@ Perform the :ref:`CTest Test Step` as a :ref:`Dashboard Client`. [EXCLUDE_FIXTURE_SETUP <regex>] [EXCLUDE_FIXTURE_CLEANUP <regex>] [PARALLEL_LEVEL <level>] + [RESOURCE_SPEC_FILE <file>] [TEST_LOAD <threshold>] [SCHEDULE_RANDOM <ON|OFF>] [STOP_TIME <time-of-day>] @@ -82,6 +83,11 @@ The options are: Specify a positive number representing the number of tests to be run in parallel. +``RESOURCE_SPEC_FILE <file>`` + Specify a + :ref:`resource specification file <ctest-resource-specification-file>`. See + :ref:`ctest-resource-allocation` for more information. + ``TEST_LOAD <threshold>`` While running tests in parallel, try not to start tests when they may cause the CPU load to pass above a given threshold. If not diff --git a/Help/command/enable_language.rst b/Help/command/enable_language.rst index fb49b44..fdc44f2 100644 --- a/Help/command/enable_language.rst +++ b/Help/command/enable_language.rst @@ -1,7 +1,6 @@ enable_language --------------- - -Enable a language (CXX/C/Fortran/etc) +Enable a language (CXX/C/OBJC/OBJCXX/Fortran/etc) .. code-block:: cmake @@ -10,7 +9,7 @@ Enable a language (CXX/C/Fortran/etc) Enables support for the named language in CMake. This is the same as the :command:`project` command but does not create any of the extra variables that are created by the project command. Example languages -are ``CXX``, ``C``, ``CUDA``, ``Fortran``, and ``ASM``. +are ``CXX``, ``C``, ``CUDA``, ``OBJC``, ``OBJCXX``, ``Fortran``, and ``ASM``. If enabling ``ASM``, enable it last so that CMake can check whether compilers for other languages like ``C`` work for assembly too. diff --git a/Help/command/file.rst b/Help/command/file.rst index f99021e..b186177 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -13,6 +13,7 @@ Synopsis file(`STRINGS`_ <filename> <out-var> [...]) file(`\<HASH\> <HASH_>`_ <filename> <out-var>) file(`TIMESTAMP`_ <filename> <out-var> [...]) + file(`GET_RUNTIME_DEPENDENCIES`_ [...]) `Writing`_ file({`WRITE`_ | `APPEND`_} <filename> <content>...) @@ -130,6 +131,273 @@ timestamp variable will be set to the empty string (""). See the :command:`string(TIMESTAMP)` command for documentation of the ``<format>`` and ``UTC`` options. +.. _GET_RUNTIME_DEPENDENCIES: + +.. code-block:: cmake + + file(GET_RUNTIME_DEPENDENCIES + [RESOLVED_DEPENDENCIES_VAR <deps_var>] + [UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>] + [CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>] + [EXECUTABLES [<executable_files>...]] + [LIBRARIES [<library_files>...]] + [MODULES [<module_files>...]] + [DIRECTORIES [<directories>...]] + [BUNDLE_EXECUTABLE <bundle_executable_file>] + [PRE_INCLUDE_REGEXES [<regexes>...]] + [PRE_EXCLUDE_REGEXES [<regexes>...]] + [POST_INCLUDE_REGEXES [<regexes>...]] + [POST_EXCLUDE_REGEXES [<regexes>...]] + ) + +Recursively get the list of libraries depended on by the given files. + +Please note that this sub-command is not intended to be used in project mode. +Instead, use it in an :command:`install(CODE)` or :command:`install(SCRIPT)` +block. For example: + +.. code-block:: cmake + + install(CODE [[ + file(GET_RUNTIME_DEPENDENCIES + # ... + ) + ]]) + +The arguments are as follows: + +``RESOLVED_DEPENDENCIES_VAR <deps_var>`` + Name of the variable in which to store the list of resolved dependencies. + +``UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>`` + Name of the variable in which to store the list of unresolved dependencies. + If this variable is not specified, and there are any unresolved dependencies, + an error is issued. + +``CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>`` + Variable prefix in which to store conflicting dependency information. + Dependencies are conflicting if two files with the same name are found in + two different directories. The list of filenames that conflict are stored in + ``<conflicting_deps_prefix>_FILENAMES``. For each filename, the list of paths + that were found for that filename are stored in + ``<conflicting_deps_prefix>_<filename>``. + +``EXECUTABLES <executable_files>`` + List of executable files to read for dependencies. These are executables that + are typically created with :command:`add_executable`, but they do not have to + be created by CMake. On Apple platforms, the paths to these files determine + the value of ``@executable_path`` when recursively resolving the libraries. + Specifying any kind of library (``STATIC``, ``MODULE``, or ``SHARED``) here + will result in undefined behavior. + +``LIBRARIES <library_files>`` + List of library files to read for dependencies. These are libraries that are + typically created with :command:`add_library(SHARED)`, but they do not have + to be created by CMake. Specifying ``STATIC`` libraries, ``MODULE`` + libraries, or executables here will result in undefined behavior. + +``MODULES <module_files>`` + List of loadable module files to read for dependencies. These are modules + that are typically created with :command:`add_library(MODULE)`, but they do + not have to be created by CMake. They are typically used by calling + ``dlopen()`` at runtime rather than linked at link time with ``ld -l``. + Specifying ``STATIC`` libraries, ``SHARED`` libraries, or executables here + will result in undefined behavior. + +``DIRECTORIES <directories>`` + List of additional directories to search for dependencies. On Linux + platforms, these directories are searched if the dependency is not found in + any of the other usual paths. If it is found in such a directory, a warning + is issued, because it means that the file is incomplete (it does not list all + of the directories that contain its dependencies). On Windows platforms, + these directories are searched if the dependency is not found in any of the + other search paths, but no warning is issued, because searching other paths + is a normal part of Windows dependency resolution. On Apple platforms, this + argument has no effect. + +``BUNDLE_EXECUTABLE <bundle_executable_file>`` + Executable to treat as the "bundle executable" when resolving libraries. On + Apple platforms, this argument determines the value of ``@executable_path`` + when recursively resolving libraries for ``LIBRARIES`` and ``MODULES`` files. + It has no effect on ``EXECUTABLES`` files. On other platforms, it has no + effect. This is typically (but not always) one of the executables in the + ``EXECUTABLES`` argument which designates the "main" executable of the + package. + +The following arguments specify filters for including or excluding libraries to +be resolved. See below for a full description of how they work. + +``PRE_INCLUDE_REGEXES <regexes>`` + List of pre-include regexes through which to filter the names of + not-yet-resolved dependencies. + +``PRE_EXCLUDE_REGEXES <regexes>`` + List of pre-exclude regexes through which to filter the names of + not-yet-resolved dependencies. + +``POST_INCLUDE_REGEXES <regexes>`` + List of post-include regexes through which to filter the names of resolved + dependencies. + +``POST_EXCLUDE_REGEXES <regexes>`` + List of post-exclude regexes through which to filter the names of resolved + dependencies. + +These arguments can be used to blacklist unwanted system libraries when +resolving the dependencies, or to whitelist libraries from a specific +directory. The filtering works as follows: + +1. If the not-yet-resolved dependency matches any of the + ``PRE_INCLUDE_REGEXES``, steps 2 and 3 are skipped, and the dependency + resolution proceeds to step 4. +2. If the not-yet-resolved dependency matches any of the + ``PRE_EXCLUDE_REGEXES``, dependency resolution stops for that dependency. +3. Otherwise, dependency resolution proceeds. +4. ``file(GET_RUNTIME_DEPENDENCIES)`` searches for the dependency according to + the linking rules of the platform (see below). +5. If the dependency is found, and its full path matches one of the + ``POST_INCLUDE_REGEXES``, the full path is added to the resolved + dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)`` recursively resolves + that library's own dependencies. Otherwise, resolution proceeds to step 6. +6. If the dependency is found, but its full path matches one of the + ``POST_EXCLUDE_REGEXES``, it is not added to the resolved dependencies, and + dependency resolution stops for that dependency. +7. If the dependency is found, and its full path does not match either + ``POST_INCLUDE_REGEXES`` or ``POST_EXCLUDE_REGEXES``, the full path is added + to the resolved dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)`` + recursively resolves that library's own dependencies. + +Different platforms have different rules for how dependencies are resolved. +These specifics are described here. + +On Linux platforms, library resolution works as follows: + +1. If the depending file does not have any ``RUNPATH`` entries, and the library + exists in one of the depending file's ``RPATH`` entries, or its parents', in + that order, the dependency is resolved to that file. +2. Otherwise, if the depending file has any ``RUNPATH`` entries, and the + library exists in one of those entries, the dependency is resolved to that + file. +3. Otherwise, if the library exists in one of the directories listed by + ``ldconfig``, the dependency is resolved to that file. +4. Otherwise, if the library exists in one of the ``DIRECTORIES`` entries, the + dependency is resolved to that file. In this case, a warning is issued, + because finding a file in one of the ``DIRECTORIES`` means that the + depending file is not complete (it does not list all the directories from + which it pulls dependencies). +5. Otherwise, the dependency is unresolved. + +On Windows platforms, library resolution works as follows: + +1. The dependent DLL name is converted to lowercase. Windows DLL names are + case-insensitive, and some linkers mangle the case of the DLL dependency + names. However, this makes it more difficult for ``PRE_INCLUDE_REGEXES``, + ``PRE_EXCLUDE_REGEXES``, ``POST_INCLUDE_REGEXES``, and + ``POST_EXCLUDE_REGEXES`` to properly filter DLL names - every regex would + have to check for both uppercase and lowercase letters. For example: + + .. code-block:: cmake + + file(GET_RUNTIME_DEPENDENCIES + # ... + PRE_INCLUDE_REGEXES "^[Mm][Yy][Ll][Ii][Bb][Rr][Aa][Rr][Yy]\\.[Dd][Ll][Ll]$" + ) + + Converting the DLL name to lowercase allows the regexes to only match + lowercase names, thus simplifying the regex. For example: + + .. code-block:: cmake + + file(GET_RUNTIME_DEPENDENCIES + # ... + PRE_INCLUDE_REGEXES "^mylibrary\\.dll$" + ) + + This regex will match ``mylibrary.dll`` regardless of how it is cased, + either on disk or in the depending file. (For example, it will match + ``mylibrary.dll``, ``MyLibrary.dll``, and ``MYLIBRARY.DLL``.) + + Please note that the directory portion of any resolved DLLs retains its + casing and is not converted to lowercase. Only the filename portion is + converted. + +2. (**Not yet implemented**) If the depending file is a Windows Store app, and + the dependency is listed as a dependency in the application's package + manifest, the dependency is resolved to that file. +3. Otherwise, if the library exists in the same directory as the depending + file, the dependency is resolved to that file. +4. Otherwise, if the library exists in either the operating system's + ``system32`` directory or the ``Windows`` directory, in that order, the + dependency is resolved to that file. +5. Otherwise, if the library exists in one of the directories specified by + ``DIRECTORIES``, in the order they are listed, the dependency is resolved to + that file. In this case, a warning is not issued, because searching other + directories is a normal part of Windows library resolution. +6. Otherwise, the dependency is unresolved. + +On Apple platforms, library resolution works as follows: + +1. If the dependency starts with ``@executable_path/``, and an ``EXECUTABLES`` + argument is in the process of being resolved, and replacing + ``@executable_path/`` with the directory of the executable yields an + existing file, the dependency is resolved to that file. +2. Otherwise, if the dependency starts with ``@executable_path/``, and there is + a ``BUNDLE_EXECUTABLE`` argument, and replacing ``@executable_path/`` with + the directory of the bundle executable yields an existing file, the + dependency is resolved to that file. +3. Otherwise, if the dependency starts with ``@loader_path/``, and replacing + ``@loader_path/`` with the directory of the depending file yields an + existing file, the dependency is resolved to that file. +4. Otherwise, if the dependency starts with ``@rpath/``, and replacing + ``@rpath/`` with one of the ``RPATH`` entries of the depending file yields + an existing file, the dependency is resolved to that file. Note that + ``RPATH`` entries that start with ``@executable_path/`` or ``@loader_path/`` + also have these items replaced with the appropriate path. +5. Otherwise, if the dependency is an absolute file that exists, the dependency + is resolved to that file. +6. Otherwise, the dependency is unresolved. + +This function accepts several variables that determine which tool is used for +dependency resolution: + +.. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM + + Determines which operating system and executable format the files are built + for. This could be one of several values: + + * ``linux+elf`` + * ``windows+pe`` + * ``macos+macho`` + + If this variable is not specified, it is determined automatically by system + introspection. + +.. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL + + Determines the tool to use for dependency resolution. It could be one of + several values, depending on the value of + :variable:`CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM`: + + ================================================= ============================================= + ``CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM`` ``CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL`` + ================================================= ============================================= + ``linux+elf`` ``objdump`` + ``windows+pe`` ``dumpbin`` + ``windows+pe`` ``objdump`` + ``macos+macho`` ``otool`` + ================================================= ============================================= + + If this variable is not specified, it is determined automatically by system + introspection. + +.. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_COMMAND + + Determines the path to the tool to use for dependency resolution. This is the + actual path to ``objdump``, ``dumpbin``, or ``otool``. + + If this variable is not specified, it is determined automatically by system + introspection. + Writing ^^^^^^^ @@ -235,6 +503,11 @@ regular expressions, but much simpler. If ``RELATIVE`` flag is specified, the results will be returned as relative paths to the given path. The results will be ordered lexicographically. +On Windows and macOS, globbing is case-insensitive even if the underlying +filesystem is case-sensitive (both filenames and globbing expressions are +converted to lowercase before matching). On other platforms, globbing is +case-sensitive. + If the ``CONFIGURE_DEPENDS`` flag is specified, CMake will add logic to the main build system check target to rerun the flagged ``GLOB`` commands at build time. If any of the outputs change, CMake will regenerate the build diff --git a/Help/command/find_file.rst b/Help/command/find_file.rst index 2a14ad7..3f03f37 100644 --- a/Help/command/find_file.rst +++ b/Help/command/find_file.rst @@ -17,11 +17,10 @@ find_file .. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_INCLUDE_PATH` .. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_FRAMEWORK_PATH` -.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in ``INCLUDE``. - On Windows hosts: - ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` - is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|, and the - directories in ``PATH`` itself. +.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``PATH`` and ``INCLUDE``. +.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: On Windows hosts: + ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` + is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|. .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace:: ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` diff --git a/Help/command/find_library.rst b/Help/command/find_library.rst index 0861d67..8a55aca 100644 --- a/Help/command/find_library.rst +++ b/Help/command/find_library.rst @@ -17,11 +17,10 @@ find_library .. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_LIBRARY_PATH` .. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_FRAMEWORK_PATH` -.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in ``LIB``. - On Windows hosts: - ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set, - and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|, - and the directories in ``PATH`` itself. +.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``PATH`` and ``INCLUDE``. +.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: On Windows hosts: + ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` + is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|. .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace:: ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set, diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index e5e5b2c..64a16f3 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -81,6 +81,7 @@ The complete Config mode command signature is find_package(<PackageName> [version] [EXACT] [QUIET] [REQUIRED] [[COMPONENTS] [components...]] + [OPTIONAL_COMPONENTS components...] [CONFIG|NO_MODULE] [NO_POLICY_SCOPE] [NAMES name1 [name2 ...]] @@ -293,13 +294,15 @@ enabled. 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. + 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`. 2. Search paths specified in cmake-specific cache variables. These are intended to be used on the command line with a ``-DVAR=value``. The values are interpreted as :ref:`semicolon-separated lists <CMake Language Lists>`. - This can be skipped if ``NO_CMAKE_PATH`` is passed:: + This can be skipped if ``NO_CMAKE_PATH`` is passed or by setting the + :variable:`CMAKE_FIND_USE_CMAKE_PATH` to ``FALSE``:: CMAKE_PREFIX_PATH CMAKE_FRAMEWORK_PATH @@ -309,7 +312,8 @@ enabled. These are intended to be set in the user's shell configuration, and therefore use the host's native path separator (``;`` on Windows and ``:`` on UNIX). - This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed:: + This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed or by setting + the :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` to ``FALSE``:: <PackageName>_DIR CMAKE_PREFIX_PATH @@ -322,7 +326,8 @@ enabled. be specified with the ``PATHS`` option. 5. Search the standard system environment variables. This can be - skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is passed. Path entries + skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is passed or by setting the + :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH` to ``FALSE``. Path entries ending in ``/bin`` or ``/sbin`` are automatically converted to their parent directories:: @@ -330,14 +335,17 @@ enabled. 6. Search paths stored in the CMake :ref:`User Package Registry`. This can be skipped if ``NO_CMAKE_PACKAGE_REGISTRY`` is passed or by - setting the :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` - to ``TRUE``. + setting the variable :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` + to ``FALSE`` or the deprecated variable + :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` to ``TRUE``. + See the :manual:`cmake-packages(7)` manual for details on the user package registry. 7. Search cmake variables defined in the Platform files for the current system. This can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is - passed:: + passed or by setting the :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH` + to ``FALSE``:: CMAKE_SYSTEM_PREFIX_PATH CMAKE_SYSTEM_FRAMEWORK_PATH @@ -345,8 +353,10 @@ enabled. 8. Search paths stored in the CMake :ref:`System Package Registry`. This can be skipped if ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` is passed - or by setting the + or by setting the :variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY` + variable to ``FALSE`` or the deprecated variable :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` to ``TRUE``. + See the :manual:`cmake-packages(7)` manual for details on the system package registry. diff --git a/Help/command/find_path.rst b/Help/command/find_path.rst index 988a3fa..52ffe3c 100644 --- a/Help/command/find_path.rst +++ b/Help/command/find_path.rst @@ -17,11 +17,10 @@ find_path .. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_INCLUDE_PATH` .. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_FRAMEWORK_PATH` -.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in ``INCLUDE``. - On Windows hosts: - ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` - is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|, and the - directories in ``PATH`` itself. +.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``PATH`` and ``INCLUDE``. +.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: On Windows hosts: + ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` + is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|. .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace:: ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` diff --git a/Help/command/find_program.rst b/Help/command/find_program.rst index 4f00773..e2ff693 100644 --- a/Help/command/find_program.rst +++ b/Help/command/find_program.rst @@ -15,7 +15,8 @@ find_program .. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_PROGRAM_PATH` .. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_APPBUNDLE_PATH` -.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: ``PATH`` +.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``PATH`` itself. +.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: On Windows hosts no extra search paths are included .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace:: |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| diff --git a/Help/command/if.rst b/Help/command/if.rst index d8e3a45..be992df 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst @@ -29,6 +29,8 @@ If used, it must be a verbatim repeat of the argument of the opening ``if`` command. +.. _`Condition Syntax`: + Condition Syntax ^^^^^^^^^^^^^^^^ diff --git a/Help/command/install.rst b/Help/command/install.rst index ab6fef6..5affc5b 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -126,6 +126,8 @@ project. There are several kinds of target files that may be installed: marked with the ``FRAMEWORK`` property on macOS (see ``FRAMEWORK`` below.) For DLL platforms (all Windows-based systems including Cygwin), the DLL import library is treated as an ``ARCHIVE`` target. + On AIX, the linker import file created for executables with + :prop_tgt:`ENABLE_EXPORTS` is treated as an ``ARCHIVE`` target. ``LIBRARY`` Module libraries are always treated as ``LIBRARY`` targets. For non- diff --git a/Help/command/list.rst b/Help/command/list.rst index 39e7e2a..50bf417 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst @@ -180,7 +180,7 @@ Insert elements to the 0th position in the list. list(REMOVE_ITEM <list> <value> [<value> ...]) -Removes the given items from the list. +Removes all instances of the given items from the list. .. _REMOVE_AT: diff --git a/Help/command/load_cache.rst b/Help/command/load_cache.rst index 33625c4..b89eb61 100644 --- a/Help/command/load_cache.rst +++ b/Help/command/load_cache.rst @@ -5,7 +5,7 @@ Load in the values from another project's CMake cache. .. code-block:: cmake - load_cache(pathToCacheFile READ_WITH_PREFIX prefix entry1...) + load_cache(pathToBuildDirectory READ_WITH_PREFIX prefix entry1...) Reads the cache and store the requested entries in variables with their name prefixed with the given prefix. This only reads the values, and @@ -13,7 +13,7 @@ does not create entries in the local project's cache. .. code-block:: cmake - load_cache(pathToCacheFile [EXCLUDE entry1...] + load_cache(pathToBuildDirectory [EXCLUDE entry1...] [INCLUDE_INTERNALS entry1...]) Loads in the values from another cache and store them in the local diff --git a/Help/command/math.rst b/Help/command/math.rst index 3cbe719..ddb1ec6 100644 --- a/Help/command/math.rst +++ b/Help/command/math.rst @@ -8,7 +8,8 @@ Evaluate a mathematical expression. math(EXPR <variable> "<expression>" [OUTPUT_FORMAT <format>]) Evaluates a mathematical ``<expression>`` and sets ``<variable>`` to the -resulting value. +resulting value. The result of the expression must be representable as a +64-bit signed integer. 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/message.rst b/Help/command/message.rst index 5dca6b4..c614286 100644 --- a/Help/command/message.rst +++ b/Help/command/message.rst @@ -57,9 +57,14 @@ are sent to stderr and are not prefixed with hyphens. The :manual:`CMake GUI <cmake-gui(1)>` displays all messages in its log area. The :manual:`curses interface <ccmake(1)>` shows ``STATUS`` to ``TRACE`` messages one at a time on a status line and other messages in an -interactive pop-up box. The ``--loglevel`` command-line option to each of +interactive pop-up box. The ``--log-level`` command-line option to each of these tools can be used to control which messages will be shown. +Messages of log levels ``NOTICE`` and below will also have each line preceded +by the content of the :variable:`CMAKE_MESSAGE_INDENT` variable (converted to +a single string by concatenating its list items). For ``STATUS`` to ``TRACE`` +messages, this indenting content will be inserted after the hyphens. + CMake Warning and Error message text displays using a simple markup language. Non-indented text is formatted in line-wrapped paragraphs delimited by newlines. Indented text is considered pre-formatted. diff --git a/Help/command/project.rst b/Help/command/project.rst index baf18be..3951456 100644 --- a/Help/command/project.rst +++ b/Help/command/project.rst @@ -87,7 +87,8 @@ The options are: Can also be specified without ``LANGUAGES`` keyword per the first, short signature. Selects which programming languages are needed to build the project. - Supported languages include ``C``, ``CXX`` (i.e. C++), ``CUDA``, ``Fortran``, and ``ASM``. + Supported languages include ``C``, ``CXX`` (i.e. C++), ``CUDA``, + ``OBJC`` (i.e. Objective-C), ``OBJCXX``, ``Fortran``, and ``ASM``. By default ``C`` and ``CXX`` are enabled if no language options are given. Specify language ``NONE``, or use the ``LANGUAGES`` keyword and list no languages, to skip enabling any languages. diff --git a/Help/command/string.rst b/Help/command/string.rst index 2e89d7b..81a2061 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -22,8 +22,8 @@ Synopsis string(`PREPEND`_ <string-var> [<input>...]) string(`CONCAT`_ <out-var> [<input>...]) string(`JOIN`_ <glue> <out-var> [<input>...]) - string(`TOLOWER`_ <string1> <out-var>) - string(`TOUPPER`_ <string1> <out-var>) + string(`TOLOWER`_ <string> <out-var>) + string(`TOUPPER`_ <string> <out-var>) string(`LENGTH`_ <string> <out-var>) string(`SUBSTRING`_ <string> <begin> <length> <out-var>) string(`STRIP`_ <string> <out-var>) @@ -38,7 +38,7 @@ Synopsis `Generation`_ string(`ASCII`_ <number>... <out-var>) - string(`CONFIGURE`_ <string1> <out-var> [...]) + string(`CONFIGURE`_ <string> <out-var> [...]) string(`MAKE_C_IDENTIFIER`_ <string> <out-var>) string(`RANDOM`_ [<option>...] <out-var>) string(`TIMESTAMP`_ <out-var> [<format string>] [UTC]) @@ -51,23 +51,28 @@ Search and Replace .. code-block:: cmake - string(FIND <string> <substring> <output variable> [REVERSE]) + string(FIND <string> <substring> <output_variable> [REVERSE]) -Return the position where the given substring was found in -the supplied string. If the ``REVERSE`` flag was used, the command will +Return the position where the given ``<substring>`` was found in +the supplied ``<string>``. If the ``REVERSE`` flag was used, the command will search for the position of the last occurrence of the specified -substring. If the substring is not found, a position of -1 is returned. +``<substring>``. If the ``<substring>`` is not found, a position of -1 is +returned. + +The ``string(FIND)`` subcommand treats all strings as ASCII-only characters. +The index stored in ``<output_variable>`` will also be counted in bytes, +so strings containing multi-byte characters may lead to unexpected results. .. _REPLACE: .. code-block:: cmake string(REPLACE <match_string> - <replace_string> <output variable> + <replace_string> <output_variable> <input> [<input>...]) -Replace all occurrences of ``match_string`` in the input -with ``replace_string`` and store the result in the output. +Replace all occurrences of ``<match_string>`` in the ``<input>`` +with ``<replace_string>`` and store the result in the ``<output_variable>``. Regular Expressions ^^^^^^^^^^^^^^^^^^^ @@ -77,9 +82,10 @@ Regular Expressions .. code-block:: cmake string(REGEX MATCH <regular_expression> - <output variable> <input> [<input>...]) + <output_variable> <input> [<input>...]) -Match the regular expression once and store the match in the output variable. +Match the ``<regular_expression>`` once and store the match in the +``<output_variable>``. All ``<input>`` arguments are concatenated before matching. .. _`REGEX MATCHALL`: @@ -87,10 +93,10 @@ All ``<input>`` arguments are concatenated before matching. .. code-block:: cmake string(REGEX MATCHALL <regular_expression> - <output variable> <input> [<input>...]) + <output_variable> <input> [<input>...]) -Match the regular expression as many times as possible and store the matches -in the output variable as a list. +Match the ``<regular_expression>`` as many times as possible and store the +matches in the ``<output_variable>`` as a list. All ``<input>`` arguments are concatenated before matching. .. _`REGEX REPLACE`: @@ -98,16 +104,17 @@ All ``<input>`` arguments are concatenated before matching. .. code-block:: cmake string(REGEX REPLACE <regular_expression> - <replace_expression> <output variable> + <replacement_expression> <output_variable> <input> [<input>...]) -Match the regular expression as many times as possible and substitute the -replacement expression for the match in the output. +Match the ``<regular_expression>`` as many times as possible and substitute +the ``<replacement_expression>`` for the match in the output. All ``<input>`` arguments are concatenated before matching. -The replace expression may refer to paren-delimited subexpressions of the -match using ``\1``, ``\2``, ..., ``\9``. Note that two backslashes (``\\1``) -are required in CMake code to get a backslash through argument parsing. +The ``<replacement_expression>`` may refer to parenthesis-delimited +subexpressions of the match using ``\1``, ``\2``, ..., ``\9``. Note that +two backslashes (``\\1``) are required in CMake code to get a backslash +through argument parsing. .. _`Regex Specification`: @@ -180,103 +187,109 @@ Manipulation .. code-block:: cmake - string(APPEND <string variable> [<input>...]) + string(APPEND <string_variable> [<input>...]) -Append all the input arguments to the string. +Append all the ``<input>`` arguments to the string. .. _PREPEND: .. code-block:: cmake - string(PREPEND <string variable> [<input>...]) + string(PREPEND <string_variable> [<input>...]) -Prepend all the input arguments to the string. +Prepend all the ``<input>`` arguments to the string. .. _CONCAT: .. code-block:: cmake - string(CONCAT <output variable> [<input>...]) + string(CONCAT <output_variable> [<input>...]) -Concatenate all the input arguments together and store -the result in the named output variable. +Concatenate all the ``<input>`` arguments together and store +the result in the named ``<output_variable>``. .. _JOIN: .. code-block:: cmake - string(JOIN <glue> <output variable> [<input>...]) + string(JOIN <glue> <output_variable> [<input>...]) -Join all the input arguments together using the glue -string and store the result in the named output variable. +Join all the ``<input>`` arguments together using the ``<glue>`` +string and store the result in the named ``<output_variable>``. -To join list's elements, use preferably the ``JOIN`` operator -from :command:`list` command. This allows for the elements to have +To join a list's elements, prefer to use the ``JOIN`` operator +from the :command:`list` command. This allows for the elements to have special characters like ``;`` in them. .. _TOLOWER: .. code-block:: cmake - string(TOLOWER <string1> <output variable>) + string(TOLOWER <string> <output_variable>) -Convert string to lower characters. +Convert ``<string>`` to lower characters. .. _TOUPPER: .. code-block:: cmake - string(TOUPPER <string1> <output variable>) + string(TOUPPER <string> <output_variable>) -Convert string to upper characters. +Convert ``<string>`` to upper characters. .. _LENGTH: .. code-block:: cmake - string(LENGTH <string> <output variable>) + string(LENGTH <string> <output_variable>) -Store in an output variable a given string's length. +Store in an ``<output_variable>`` a given string's length in bytes. +Note that this means if ``<string>`` contains multi-byte characters, the +result stored in ``<output_variable>`` will *not* be the number of characters. .. _SUBSTRING: .. code-block:: cmake - string(SUBSTRING <string> <begin> <length> <output variable>) + string(SUBSTRING <string> <begin> <length> <output_variable>) + +Store in an ``<output_variable>`` a substring of a given ``<string>``. If +``<length>`` is ``-1`` the remainder of the string starting at ``<begin>`` +will be returned. If ``<string>`` is shorter than ``<length>`` then the +end of the string is used instead. -Store in an output variable a substring of a given string. If length is -``-1`` the remainder of the string starting at begin will be returned. -If string is shorter than length then end of string is used instead. +Both ``<begin>`` and ``<length>`` are counted in bytes, so care must +be exercised if ``<string>`` could contain multi-byte characters. .. note:: - CMake 3.1 and below reported an error if length pointed past - the end of string. + CMake 3.1 and below reported an error if ``<length>`` pointed past + the end of ``<string>``. .. _STRIP: .. code-block:: cmake - string(STRIP <string> <output variable>) + string(STRIP <string> <output_variable>) -Store in an output variable a substring of a given string with leading and -trailing spaces removed. +Store in an ``<output_variable>`` a substring of a given ``<string>`` with +leading and trailing spaces removed. .. _GENEX_STRIP: .. code-block:: cmake - string(GENEX_STRIP <input string> <output variable>) + string(GENEX_STRIP <string> <output_variable>) Strip any :manual:`generator expressions <cmake-generator-expressions(7)>` -from the ``input string`` and store the result in the ``output variable``. +from the input ``<string>`` and store the result in the ``<output_variable>``. .. _REPEAT: .. code-block:: cmake - string(REPEAT <input string> <count> <output variable>) + string(REPEAT <string> <count> <output_variable>) -Produce the output string as repetion of ``input string`` ``count`` times. +Produce the output string as the input ``<string>`` repeated ``<count>`` times. Comparison ^^^^^^^^^^ @@ -285,14 +298,14 @@ Comparison .. code-block:: cmake - string(COMPARE LESS <string1> <string2> <output variable>) - string(COMPARE GREATER <string1> <string2> <output variable>) - string(COMPARE EQUAL <string1> <string2> <output variable>) - string(COMPARE NOTEQUAL <string1> <string2> <output variable>) - string(COMPARE LESS_EQUAL <string1> <string2> <output variable>) - string(COMPARE GREATER_EQUAL <string1> <string2> <output variable>) + string(COMPARE LESS <string1> <string2> <output_variable>) + string(COMPARE GREATER <string1> <string2> <output_variable>) + string(COMPARE EQUAL <string1> <string2> <output_variable>) + string(COMPARE NOTEQUAL <string1> <string2> <output_variable>) + string(COMPARE LESS_EQUAL <string1> <string2> <output_variable>) + string(COMPARE GREATER_EQUAL <string1> <string2> <output_variable>) -Compare the strings and store true or false in the output variable. +Compare the strings and store true or false in the ``<output_variable>``. .. _`Supported Hash Algorithms`: @@ -303,9 +316,9 @@ Hashing .. code-block:: cmake - string(<HASH> <output variable> <input>) + string(<HASH> <output_variable> <input>) -Compute a cryptographic hash of the input string. +Compute a cryptographic hash of the ``<input>`` string. The supported ``<HASH>`` algorithm names are: ``MD5`` @@ -336,7 +349,7 @@ Generation .. code-block:: cmake - string(ASCII <number> [<number> ...] <output variable>) + string(ASCII <number> [<number> ...] <output_variable>) Convert all numbers into corresponding ASCII characters. @@ -344,31 +357,31 @@ Convert all numbers into corresponding ASCII characters. .. code-block:: cmake - string(CONFIGURE <string1> <output variable> + string(CONFIGURE <string> <output_variable> [@ONLY] [ESCAPE_QUOTES]) -Transform a string like :command:`configure_file` transforms a file. +Transform a ``<string>`` like :command:`configure_file` transforms a file. .. _MAKE_C_IDENTIFIER: .. code-block:: cmake - string(MAKE_C_IDENTIFIER <input string> <output variable>) + string(MAKE_C_IDENTIFIER <string> <output_variable>) -Convert each non-alphanumeric character in the ``<input string>`` to an -underscore and store the result in the ``<output variable>``. If the first -character of the string is a digit, an underscore will also be prepended to -the result. +Convert each non-alphanumeric character in the input ``<string>`` to an +underscore and store the result in the ``<output_variable>``. If the first +character of the ``<string>`` is a digit, an underscore will also be prepended +to the result. .. _RANDOM: .. code-block:: cmake string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>] - [RANDOM_SEED <seed>] <output variable>) + [RANDOM_SEED <seed>] <output_variable>) -Return a random string of given length consisting of -characters from the given alphabet. Default length is 5 characters +Return a random string of given ``<length>`` consisting of +characters from the given ``<alphabet>``. Default length is 5 characters and default alphabet is all numbers and upper and lower case letters. If an integer ``RANDOM_SEED`` is given, its value will be used to seed the random number generator. @@ -377,18 +390,18 @@ random number generator. .. code-block:: cmake - string(TIMESTAMP <output variable> [<format string>] [UTC]) + string(TIMESTAMP <output_variable> [<format_string>] [UTC]) Write a string representation of the current date -and/or time to the output variable. +and/or time to the ``<output_variable>``. -Should the command be unable to obtain a timestamp the output variable -will be set to the empty string "". +If the command is unable to obtain a timestamp, the ``<output_variable>`` +will be set to the empty string ``""``. The optional ``UTC`` flag requests the current date/time representation to be in Coordinated Universal Time (UTC) rather than local time. -The optional ``<format string>`` may contain the following format +The optional ``<format_string>`` may contain the following format specifiers: :: @@ -415,7 +428,7 @@ specifiers: Unknown format specifiers will be ignored and copied to the output as-is. -If no explicit ``<format string>`` is given it will default to: +If no explicit ``<format_string>`` is given, it will default to: :: @@ -432,7 +445,7 @@ If no explicit ``<format string>`` is given it will default to: .. code-block:: cmake - string(UUID <output variable> NAMESPACE <namespace> NAME <name> + string(UUID <output_variable> NAMESPACE <namespace> NAME <name> TYPE <MD5|SHA1> [UPPER]) Create a universally unique identifier (aka GUID) as per RFC4122 @@ -441,6 +454,6 @@ based on the hash of the combined values of ``<namespace>`` The hash algorithm can be either ``MD5`` (Version 3 UUID) or ``SHA1`` (Version 5 UUID). A UUID has the format ``xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`` -where each `x` represents a lower case hexadecimal character. -Where required an uppercase representation can be requested +where each ``x`` represents a lower case hexadecimal character. +Where required, an uppercase representation can be requested with the optional ``UPPER`` flag. diff --git a/Help/command/target_precompile_headers.rst b/Help/command/target_precompile_headers.rst new file mode 100644 index 0000000..569c7eb --- /dev/null +++ b/Help/command/target_precompile_headers.rst @@ -0,0 +1,124 @@ +target_precompile_headers +------------------------- + +Add a list of header files to precompile. + +Precompiling header files can speed up compilation by creating a partially +processed version of some header files, and then using that version during +compilations rather than repeatedly parsing the original headers. + +Main Form +^^^^^^^^^ + +.. code-block:: cmake + + target_precompile_headers(<target> + <INTERFACE|PUBLIC|PRIVATE> [header1...] + [<INTERFACE|PUBLIC|PRIVATE> [header2...] ...]) + +The command adds header files to the :prop_tgt:`PRECOMPILE_HEADERS` and/or +:prop_tgt:`INTERFACE_PRECOMPILE_HEADERS` target properties of ``<target>``. +The named ``<target>`` must have been created by a command such as +:command:`add_executable` or :command:`add_library` and must not be an +:ref:`ALIAS target <Alias Targets>`. + +The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to +specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC`` +items will populate the :prop_tgt:`PRECOMPILE_HEADERS` property of +``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the +:prop_tgt:`INTERFACE_PRECOMPILE_HEADERS` property of ``<target>`` +(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items). +Repeated calls for the same ``<target>`` will append items in the order called. + +Projects should generally avoid using ``PUBLIC`` or ``INTERFACE`` for targets +that will be :ref:`exported <install(EXPORT)>`, or they should at least use +the ``$<BUILD_INTERFACE:...>`` generator expression to prevent precompile +headers from appearing in an installed exported target. Consumers of a target +should typically be in control of what precompile headers they use, not have +precompile headers forced on them by the targets being consumed (since +precompile headers are not typically usage requirements). A notable exception +to this is where an :ref:`interface library <Interface Libraries>` is created +to define a commonly used set of precompile headers in one place and then other +targets link to that interface library privately. In this case, the interface +library exists specifically to propagate the precompile headers to its +consumers and the consumer is effectively still in control, since it decides +whether to link to the interface library or not. + +The list of header files is used to generate a header file named +``cmake_pch.h|xx`` which is used to generate the precompiled header file +(``.pch``, ``.gch``, ``.pchi``) artifact. The ``cmake_pch.h|xx`` header +file will be force included (``-include`` for GCC, ``/FI`` for MSVC) to +all source files, so sources do not need to have ``#include "pch.h"``. + +Header file names specified with angle brackets (e.g. ``<unordered_map>``) or +explicit double quotes (escaped for the :manual:`cmake-language(7)`, +e.g. ``[["other_header.h"]]``) will be treated as is, and include directories +must be available for the compiler to find them. Other header file names +(e.g. ``project_header.h``) are interpreted as being relative to the current +source directory (e.g. :variable:`CMAKE_CURRENT_SOURCE_DIR`) and will be +included by absolute path. + +Arguments to ``target_precompile_headers()`` may use "generator expressions" +with the syntax ``$<...>``. +See the :manual:`cmake-generator-expressions(7)` manual for available +expressions. See the :manual:`cmake-compile-features(7)` manual for +information on compile features and a list of supported compilers. +The ``$<COMPILE_LANGUAGE:...>`` generator expression is particularly +useful for specifying a language-specific header to precompile for +only one language (e.g. ``CXX`` and not ``C``). For example: + +.. code-block:: cmake + + target_precompile_headers(myTarget + PUBLIC + project_header.h + "$<$<COMPILE_LANGUAGE:CXX>:cxx_only.h>" + PRIVATE + [["other_header.h"]] + <unordered_map> + ) + +When specifying angle brackets inside a :manual:`generator expression +<cmake-generator-expressions(7)>`, be sure to encode the closing ``>`` +as ``$<ANGLE-R>``. For example: + +.. code-block:: cmake + + target_precompile_headers(mylib PRIVATE + "$<$<COMPILE_LANGUAGE:C>:<stddef.h$<ANGLE-R>>" + "$<$<COMPILE_LANGUAGE:CXX>:<cstddef$<ANGLE-R>>" + ) + + +Reusing Precompile Headers +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The command also supports a second signature which can be used to specify that +one target re-uses a precompiled header file artefact from another target +instead of generating its own: + +.. code-block:: cmake + + target_precompile_headers(<target> REUSE_FROM <other_target>) + +This form sets the :prop_tgt:`PRECOMPILE_HEADERS_REUSE_FROM` property to +``<other_target>`` and adds a dependency such that ``<target>`` will depend +on ``<other_target>``. CMake will halt with an error if the +:prop_tgt:`PRECOMPILE_HEADERS` property of ``<target>`` is already set when +the ``REUSE_FROM`` form is used. + +.. note:: + + The ``REUSE_FROM`` form requires the same set of compiler options, + compiler flags and compiler definitions for both ``<target>`` and + ``<other_target>``. Some compilers (e.g. GCC) may issue a warning if the + precompiled header file cannot be used (``-Winvalid-pch``). + +See Also +^^^^^^^^ + +To disable precompile headers for specific targets, see the +:prop_tgt:`DISABLE_PRECOMPILE_HEADERS` target property. + +To prevent precompile headers from being used when compiling a specific +source file, see the :prop_sf:`SKIP_PRECOMPILE_HEADERS` source file property. diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst index 0bc2ca3..edbf92c 100644 --- a/Help/command/try_compile.rst +++ b/Help/command/try_compile.rst @@ -103,15 +103,18 @@ The options are: ``<LANG>_STANDARD <std>`` Specify the :prop_tgt:`C_STANDARD`, :prop_tgt:`CXX_STANDARD`, + :prop_tgt:`OBJC_STANDARD`, :prop_tgt:`OBJCXX_STANDARD`, or :prop_tgt:`CUDA_STANDARD` target property of the generated project. ``<LANG>_STANDARD_REQUIRED <bool>`` Specify the :prop_tgt:`C_STANDARD_REQUIRED`, - :prop_tgt:`CXX_STANDARD_REQUIRED`, or :prop_tgt:`CUDA_STANDARD_REQUIRED` + :prop_tgt:`CXX_STANDARD_REQUIRED`, :prop_tgt:`OBJC_STANDARD_REQUIRED`, + :prop_tgt:`OBJCXX_STANDARD_REQUIRED`,or :prop_tgt:`CUDA_STANDARD_REQUIRED` target property of the generated project. ``<LANG>_EXTENSIONS <bool>`` Specify the :prop_tgt:`C_EXTENSIONS`, :prop_tgt:`CXX_EXTENSIONS`, + :prop_tgt:`OBJC_EXTENSIONS`, :prop_tgt:`OBJCXX_EXTENSIONS`, or :prop_tgt:`CUDA_EXTENSIONS` target property of the generated project. In this version all files in ``<bindir>/CMakeFiles/CMakeTmp`` will be @@ -171,6 +174,12 @@ then the language standard variables are honored: * :variable:`CMAKE_CXX_STANDARD` * :variable:`CMAKE_CXX_STANDARD_REQUIRED` * :variable:`CMAKE_CXX_EXTENSIONS` +* :variable:`CMAKE_OBJC_STANDARD` +* :variable:`CMAKE_OBJC_STANDARD_REQUIRED` +* :variable:`CMAKE_OBJC_EXTENSIONS` +* :variable:`CMAKE_OBJCXX_STANDARD` +* :variable:`CMAKE_OBJCXX_STANDARD_REQUIRED` +* :variable:`CMAKE_OBJCXX_EXTENSIONS` * :variable:`CMAKE_CUDA_STANDARD` * :variable:`CMAKE_CUDA_STANDARD_REQUIRED` * :variable:`CMAKE_CUDA_EXTENSIONS` diff --git a/Help/cpack_gen/archive.rst b/Help/cpack_gen/archive.rst index b288aad..d455f4b 100644 --- a/Help/cpack_gen/archive.rst +++ b/Help/cpack_gen/archive.rst @@ -9,6 +9,7 @@ different formats: - TGZ (.tar.gz) - TXZ (.tar.xz) - TZ (.tar.Z) + - TZST (.tar.zst) - ZIP (.zip) Variables specific to CPack Archive generator diff --git a/Help/cpack_gen/deb.rst b/Help/cpack_gen/deb.rst index 23f0515..db71c87 100644 --- a/Help/cpack_gen/deb.rst +++ b/Help/cpack_gen/deb.rst @@ -179,16 +179,24 @@ List of CPack DEB generator specific variables: * Default : ``CPACK_PACKAGE_CONTACT`` .. variable:: CPACK_DEBIAN_PACKAGE_DESCRIPTION - CPACK_COMPONENT_<COMPONENT>_DESCRIPTION + CPACK_DEBIAN_<COMPONENT>_DESCRIPTION The Debian package description * Mandatory : YES * Default : - - :variable:`CPACK_DEBIAN_PACKAGE_DESCRIPTION` if set or - - :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY` + - :variable:`CPACK_DEBIAN_<COMPONENT>_DESCRIPTION` (component + based installers only) if set, or :variable:`CPACK_DEBIAN_PACKAGE_DESCRIPTION` if set, or + - :variable:`CPACK_COMPONENT_<compName>_DESCRIPTION` (component + based installers only) if set, or :variable:`CPACK_PACKAGE_DESCRIPTION` if set, or + - content of the file specified in :variable:`CPACK_PACKAGE_DESCRIPTION_FILE` if set + If after that description is not set, :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY` going to be + used if set. Otherwise, :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY` will be added as the first + line of description as defined in `Debian Policy Manual`_. + +.. _Debian Policy Manual: https://www.debian.org/doc/debian-policy/ch-controlfields.html#description .. variable:: CPACK_DEBIAN_PACKAGE_SECTION CPACK_DEBIAN_<COMPONENT>_PACKAGE_SECTION diff --git a/Help/cpack_gen/wix.rst b/Help/cpack_gen/wix.rst index dde4943..7fb5a12 100644 --- a/Help/cpack_gen/wix.rst +++ b/Help/cpack_gen/wix.rst @@ -95,6 +95,10 @@ Windows using WiX. If this variable is not set, it will be initialized with CPACK_PACKAGE_NAME + If this variable is set to ``.``, then application shortcuts will be + created directly in the start menu and the uninstaller shortcut will be + omitted. + .. variable:: CPACK_WIX_CULTURES Language(s) of the installer diff --git a/Help/dev/maint.rst b/Help/dev/maint.rst index 1153a09..44e2273 100644 --- a/Help/dev/maint.rst +++ b/Help/dev/maint.rst @@ -92,6 +92,45 @@ Publish both ``master`` and ``release`` simultaneously: .. _`CMake Review Process`: review.rst .. _`CMake CDash Page`: https://open.cdash.org/index.php?project=CMake +Create Release Version +====================== + +When the ``release`` branch is ready to create a new release, follow the +steps in the above `Maintain Current Release`_ section to checkout a local +``release-$ver`` branch, where ``$ver`` is the version number of the +current release in the form ``$major.$minor``. + +Edit ``Source/CMakeVersion.cmake`` to set the full version: + +.. code-block:: cmake + + # CMake version number components. + set(CMake_VERSION_MAJOR $major) + set(CMake_VERSION_MINOR $minor) + set(CMake_VERSION_PATCH $patch) + #set(CMake_VERSION_RC $rc) # uncomment for release candidates + +In the following we use the placeholder ``$fullver`` for the full version +number of the new release with the form ``$major.$minor.$patch[-rc$rc]``. +If the version is not a release candidate, comment out the RC version +component above and leave off the ``-rc$rc`` suffix from ``$fullver``. + +Commit the release version with the **exact** message ``CMake $fullver``: + +.. code-block:: shell + + git commit -m "CMake $fullver" + +Tag the release using an annotated tag with the same message as the +commit and named with the **exact** form ``v$fullver``: + +.. code-block:: shell + + git tag -s -m "CMake $fullver" "v$fullver" + +Follow the steps in the above `Maintain Current Release`_ section to +merge the ``release-$ver`` branch into ``master`` and publish both. + Branch a New Release ==================== @@ -178,7 +217,7 @@ Commit with a message such as:: the CMake Release Notes index page. Update ``Source/CMakeVersion.cmake`` to set the version to -``$major.$minor.0-rc1``: +``$major.$minor.0-rc0``: .. code-block:: cmake @@ -186,7 +225,7 @@ Update ``Source/CMakeVersion.cmake`` to set the version to set(CMake_VERSION_MAJOR $major) set(CMake_VERSION_MINOR $minor) set(CMake_VERSION_PATCH 0) - set(CMake_VERSION_RC 1) + set(CMake_VERSION_RC 0) Update uses of ``DEVEL_CMAKE_VERSION`` in the source tree to mention the actual version number: @@ -197,7 +236,7 @@ actual version number: Commit with a message such as:: - CMake $major.$minor.0-rc1 version update + Begin $ver release versioning Merge the ``release-$ver`` branch to ``master``: @@ -225,7 +264,7 @@ Update ``Source/CMakeVersion.cmake`` to set the version to set(CMake_VERSION_MAJOR $major) set(CMake_VERSION_MINOR $minor) set(CMake_VERSION_PATCH $date) - #set(CMake_VERSION_RC 1) + #set(CMake_VERSION_RC 0) Commit with a message such as:: @@ -240,10 +279,11 @@ Push the update to the ``master`` and ``release`` branches: Announce 'release' Branch ------------------------- -Send email to the ``cmake-developers@cmake.org`` mailing list (perhaps -in reply to a release preparation thread) announcing that post-release -development is open:: +Post a topic to the `CMake Discourse Forum Development Category`_ +announcing that post-release development is open:: - I've branched 'release' for $ver. The repository is now open for - post-$ver development. Please rebase open merge requests on 'master' + I've branched `release` for $ver. The repository is now open for + post-$ver development. Please rebase open merge requests on `master` before staging or merging. + +.. _`CMake Discourse Forum Development Category`: https://discourse.cmake.org/c/development diff --git a/Help/dev/source.rst b/Help/dev/source.rst index 47baff4..0f7488b 100644 --- a/Help/dev/source.rst +++ b/Help/dev/source.rst @@ -74,6 +74,8 @@ The CMake source tree is organized as follows. * ``Utilities/Release/``: Scripts used to package CMake itself for distribution on ``cmake.org``. + See `Utilities/Release/README.rst`_. .. _`CMake Documentation Guide`: documentation.rst .. _`Tests/README.rst`: ../../Tests/README.rst +.. _`Utilities/Release/README.rst`: ../../Utilities/Release/README.rst diff --git a/Help/generator/Ninja.rst b/Help/generator/Ninja.rst index 51ef49b..c75d2c4 100644 --- a/Help/generator/Ninja.rst +++ b/Help/generator/Ninja.rst @@ -3,9 +3,9 @@ Ninja Generates build.ninja files. -A build.ninja file is generated into the build tree. Recent versions -of the ninja program can build the project through the ``all`` target. -An ``install`` target is also provided. +A ``build.ninja`` file is generated into the build tree. Use the ninja +program to build the project through the ``all`` target and install the +project through the ``install`` (or ``install/strip``) target. For each subdirectory ``sub/dir`` of the project, additional targets are generated: @@ -16,6 +16,13 @@ are generated: ``sub/dir/install`` Runs the install step in the subdirectory, if any. +``sub/dir/install/strip`` + Runs the install step in the subdirectory followed by a ``CMAKE_STRIP`` command, + if any. + + The ``CMAKE_STRIP`` variable will contain the platform's ``strip`` utility, which + removes symbols information from generated binaries. + ``sub/dir/test`` Runs the test step in the subdirectory, if any. diff --git a/Help/generator/Unix Makefiles.rst b/Help/generator/Unix Makefiles.rst index 1e65ee1..dfe4ecb 100644 --- a/Help/generator/Unix Makefiles.rst +++ b/Help/generator/Unix Makefiles.rst @@ -3,6 +3,29 @@ Unix Makefiles Generates standard UNIX makefiles. -A hierarchy of UNIX makefiles is generated into the build tree. Any -standard UNIX-style make program can build the project through the -default ``all`` target. An ``install`` target is also provided. +A hierarchy of UNIX makefiles is generated into the build tree. Use +any standard UNIX-style make program to build the project through +the ``all`` target and install the project through the ``install`` +(or ``install/strip``) target. + +For each subdirectory ``sub/dir`` of the project a UNIX makefile will +be created, containing the following targets: + +``all`` + Depends on all targets required by the subdirectory. + +``install`` + Runs the install step in the subdirectory, if any. + +``install/strip`` + Runs the install step in the subdirectory followed by a ``CMAKE_STRIP`` command, + if any. + + The ``CMAKE_STRIP`` variable will contain the platform's ``strip`` utility, which + removes symbols information from generated binaries. + +``test`` + Runs the test step in the subdirectory, if any. + +``package`` + Runs the package step in the subdirectory, if any. diff --git a/Help/guide/tutorial/Complete/CMakeLists.txt b/Help/guide/tutorial/Complete/CMakeLists.txt new file mode 100644 index 0000000..eca79d9 --- /dev/null +++ b/Help/guide/tutorial/Complete/CMakeLists.txt @@ -0,0 +1,120 @@ +cmake_minimum_required(VERSION 3.15) + +# set the project name and version +project(Tutorial VERSION 1.0) + +add_library(tutorial_compiler_flags INTERFACE) +target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11) + +# add compiler warning flags just when building this project via +# the BUILD_INTERFACE genex +set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU>") +set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>") +target_compile_options(tutorial_compiler_flags INTERFACE + "$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>" + "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>" +) + +# control where the static and shared libraries are built so that on windows +# we don't need to tinker with the path to run the executable +set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") +set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") +set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") + +option(BUILD_SHARED_LIBS "Build using shared libraries" ON) + +if(APPLE) + set(CMAKE_INSTALL_RPATH "@executable_path/../lib") +elseif(UNIX) + set(CMAKE_INSTALL_RPATH "$ORIGIN/../lib") +endif() + +# configure a header file to pass the version number only +configure_file(TutorialConfig.h.in TutorialConfig.h) + +# add the MathFunctions library +add_subdirectory(MathFunctions) + +# add the executable +add_executable(Tutorial tutorial.cxx) +target_link_libraries(Tutorial PUBLIC MathFunctions) + +# add the binary tree to the search path for include files +# so that we will find TutorialConfig.h +target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + ) + +# add the install targets +install(TARGETS Tutorial DESTINATION bin) +install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" + DESTINATION include + ) + +# enable testing +enable_testing() + +# does the application run +add_test(NAME Runs COMMAND Tutorial 25) + +# does the usage message work? +add_test(NAME Usage COMMAND Tutorial) +set_tests_properties(Usage + PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number" + ) + +# define a function to simplify adding tests +function(do_test target arg result) + add_test(NAME Comp${arg} COMMAND ${target} ${arg}) + set_tests_properties(Comp${arg} + PROPERTIES PASS_REGULAR_EXPRESSION ${result} + ) +endfunction(do_test) + +# do a bunch of result based tests +do_test(Tutorial 4 "4 is 2") +do_test(Tutorial 9 "9 is 3") +do_test(Tutorial 5 "5 is 2.236") +do_test(Tutorial 7 "7 is 2.645") +do_test(Tutorial 25 "25 is 5") +do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial 0.0001 "0.0001 is 0.01") + +include(InstallRequiredSystemLibraries) +set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt") +set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}") +set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}") +include(CPack) + +# install the configuration targets +install(EXPORT MathFunctionsTargets + FILE MathFunctionsTargets.cmake + DESTINATION lib/cmake/MathFunctions +) + +include(CMakePackageConfigHelpers) +# generate the config file that is includes the exports +configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in + "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake" + INSTALL_DESTINATION "lib/cmake/example" + NO_SET_AND_CHECK_MACRO + NO_CHECK_REQUIRED_COMPONENTS_MACRO + ) +# generate the version file for the config file +write_basic_package_version_file( + "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfigVersion.cmake" + VERSION "${Tutorial_VERSION_MAJOR}.${Tutorial_VERSION_MINOR}" + COMPATIBILITY AnyNewerVersion +) + +# install the configuration file +install(FILES + ${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake + DESTINATION lib/cmake/MathFunctions + ) + +# generate the export targets for the build tree +# needs to be after the install(TARGETS ) command +export(EXPORT MathFunctionsTargets + FILE "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsTargets.cmake" +) diff --git a/Help/guide/tutorial/Complete/CTestConfig.cmake b/Help/guide/tutorial/Complete/CTestConfig.cmake new file mode 100644 index 0000000..73efdb1 --- /dev/null +++ b/Help/guide/tutorial/Complete/CTestConfig.cmake @@ -0,0 +1,7 @@ +set(CTEST_PROJECT_NAME "CMakeTutorial") +set(CTEST_NIGHTLY_START_TIME "00:00:00 EST") + +set(CTEST_DROP_METHOD "http") +set(CTEST_DROP_SITE "my.cdash.org") +set(CTEST_DROP_LOCATION "/submit.php?project=CMakeTutorial") +set(CTEST_DROP_SITE_CDASH TRUE) diff --git a/Help/guide/tutorial/Complete/Config.cmake.in b/Help/guide/tutorial/Complete/Config.cmake.in new file mode 100644 index 0000000..17cbabd --- /dev/null +++ b/Help/guide/tutorial/Complete/Config.cmake.in @@ -0,0 +1,4 @@ + +@PACKAGE_INIT@ + +include ( "${CMAKE_CURRENT_LIST_DIR}/MathFunctionsTargets.cmake" ) diff --git a/Help/guide/tutorial/Complete/License.txt b/Help/guide/tutorial/Complete/License.txt new file mode 100644 index 0000000..c62d00b --- /dev/null +++ b/Help/guide/tutorial/Complete/License.txt @@ -0,0 +1,2 @@ +This is the open source License.txt file introduced in +CMake/Tutorial/Step7... diff --git a/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt new file mode 100644 index 0000000..dfa84c9 --- /dev/null +++ b/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt @@ -0,0 +1,63 @@ +# add the library that runs +add_library(MathFunctions MathFunctions.cxx) + +# state that anybody linking to us needs to include the current source dir +# to find MathFunctions.h, while we don't. +target_include_directories(MathFunctions + INTERFACE + $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}> + $<INSTALL_INTERFACE:include> + ) + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) +if(USE_MYMATH) + + target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") + + # first we add the executable that generates the table + add_executable(MakeTable MakeTable.cxx) + target_link_libraries(MakeTable tutorial_compiler_flags) + + # add the command to generate the source code + add_custom_command( + OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h + COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h + DEPENDS MakeTable + ) + + # library that just does sqrt + add_library(SqrtLibrary STATIC + mysqrt.cxx + ${CMAKE_CURRENT_BINARY_DIR}/Table.h + ) + + # state that we depend on our binary dir to find Table.h + target_include_directories(SqrtLibrary PRIVATE + ${CMAKE_CURRENT_BINARY_DIR} + ) + + # state that SqrtLibrary need PIC when the default is shared libraries + set_target_properties(SqrtLibrary PROPERTIES + POSITION_INDEPENDENT_CODE ${BUILD_SHARED_LIBS} + ) + + target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags) + target_link_libraries(MathFunctions PRIVATE SqrtLibrary) +endif() + +target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) + +# define the symbol stating we are using the declspec(dllexport) when +# building on windows +target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH") + +# setup the version numbering +set_property(TARGET MathFunctions PROPERTY VERSION "1.0.0") +set_property(TARGET MathFunctions PROPERTY SOVERSION "1") + +# install rules +install(TARGETS MathFunctions tutorial_compiler_flags + DESTINATION lib + EXPORT MathFunctionsTargets) +install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Complete/MathFunctions/MakeTable.cxx b/Help/guide/tutorial/Complete/MathFunctions/MakeTable.cxx new file mode 100644 index 0000000..ee58556 --- /dev/null +++ b/Help/guide/tutorial/Complete/MathFunctions/MakeTable.cxx @@ -0,0 +1,25 @@ +// A simple program that builds a sqrt table +#include <cmath> +#include <fstream> +#include <iostream> + +int main(int argc, char* argv[]) +{ + // make sure we have enough arguments + if (argc < 2) { + return 1; + } + + std::ofstream fout(argv[1], std::ios_base::out); + const bool fileOpen = fout.is_open(); + if (fileOpen) { + fout << "double sqrtTable[] = {" << std::endl; + for (int i = 0; i < 10; ++i) { + fout << sqrt(static_cast<double>(i)) << "," << std::endl; + } + // close the table with a zero + fout << "0};" << std::endl; + fout.close(); + } + return fileOpen ? 0 : 1; // return 0 if wrote the file +} diff --git a/Help/guide/tutorial/Complete/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Complete/MathFunctions/MathFunctions.cxx new file mode 100644 index 0000000..0145300 --- /dev/null +++ b/Help/guide/tutorial/Complete/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) +{ +#ifdef USE_MYMATH + return detail::mysqrt(x); +#else + return std::sqrt(x); +#endif +} +} diff --git a/Help/guide/tutorial/Complete/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Complete/MathFunctions/MathFunctions.h new file mode 100644 index 0000000..3fb547b --- /dev/null +++ b/Help/guide/tutorial/Complete/MathFunctions/MathFunctions.h @@ -0,0 +1,14 @@ + +#if defined(_WIN32) +# if defined(EXPORTING_MYMATH) +# define DECLSPEC __declspec(dllexport) +# else +# define DECLSPEC __declspec(dllimport) +# endif +#else // non windows +# define DECLSPEC +#endif + +namespace mathfunctions { +double DECLSPEC sqrt(double x); +} diff --git a/Help/guide/tutorial/Complete/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Complete/MathFunctions/mysqrt.cxx new file mode 100644 index 0000000..8153f18 --- /dev/null +++ b/Help/guide/tutorial/Complete/MathFunctions/mysqrt.cxx @@ -0,0 +1,37 @@ +#include <iostream> + +#include "MathFunctions.h" + +// include the generated table +#include "Table.h" + +namespace mathfunctions { +namespace detail { +// a hack square root calculation using simple operations +double mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + // use the table to help find an initial value + double result = x; + if (x >= 1 && x < 10) { + std::cout << "Use the table to help find an initial value " << std::endl; + result = sqrtTable[static_cast<int>(x)]; + } + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; + } + + return result; +} +} +} diff --git a/Help/guide/tutorial/Complete/MathFunctions/mysqrt.h b/Help/guide/tutorial/Complete/MathFunctions/mysqrt.h new file mode 100644 index 0000000..e1c42ef --- /dev/null +++ b/Help/guide/tutorial/Complete/MathFunctions/mysqrt.h @@ -0,0 +1,6 @@ + +namespace mathfunctions { +namespace detail { +double mysqrt(double x); +} +} diff --git a/Help/guide/tutorial/Complete/TutorialConfig.h.in b/Help/guide/tutorial/Complete/TutorialConfig.h.in new file mode 100644 index 0000000..7e4d7fa --- /dev/null +++ b/Help/guide/tutorial/Complete/TutorialConfig.h.in @@ -0,0 +1,3 @@ +// the configured options and settings for Tutorial +#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ +#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ diff --git a/Help/guide/tutorial/Complete/tutorial.cxx b/Help/guide/tutorial/Complete/tutorial.cxx new file mode 100644 index 0000000..586d183 --- /dev/null +++ b/Help/guide/tutorial/Complete/tutorial.cxx @@ -0,0 +1,26 @@ +// A simple program that computes the square root of a number +#include <iostream> +#include <sstream> +#include <string> + +#include "MathFunctions.h" +#include "TutorialConfig.h" + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." + << Tutorial_VERSION_MINOR << std::endl; + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + const double inputValue = std::stod(argv[1]); + + // calculate square root + const double outputValue = mathfunctions::sqrt(inputValue); + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; + return 0; +} diff --git a/Help/guide/tutorial/Consumer/CMakeLists.txt b/Help/guide/tutorial/Consumer/CMakeLists.txt new file mode 100644 index 0000000..a0e4598 --- /dev/null +++ b/Help/guide/tutorial/Consumer/CMakeLists.txt @@ -0,0 +1,51 @@ +cmake_minimum_required(VERSION 3.10) + +if(NOT DEFINED CMAKE_CXX_STANDARD) + set(CMAKE_CXX_STANDARD 11) + set(CMAKE_CXX_STANDARD_REQUIRED True) +endif() + + +function(find_external_dependency name) + set(${name}_ROOT "" CACHE PATH "Root directory to find ${name}") + mark_as_advanced(${name}_DIR) + find_package(${name} PATHS ${${name}_ROOT} REQUIRED) +endfunction() + + +project(Consumer) + +find_external_dependency(MathFunctions) + +add_library(consumer consumer.cxx) +target_link_libraries(consumer PUBLIC MathFunctions) + +# install the consumer library +install(TARGETS consumer DESTINATION bin EXPORT ConsumerTargets) + +# install the configuration targets +install(EXPORT ConsumerTargets + FILE ConsumerTargets.cmake + DESTINATION lib/cmake/Consumer +) + +include(CMakePackageConfigHelpers) +# generate the config file that is includes the exports +configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in + "${CMAKE_CURRENT_BINARY_DIR}/ConsumerConfig.cmake" + INSTALL_DESTINATION "lib/cmake/example" + NO_SET_AND_CHECK_MACRO + NO_CHECK_REQUIRED_COMPONENTS_MACRO + ) + +# install the configuration file +install(FILES + ${CMAKE_CURRENT_BINARY_DIR}/ConsumerConfig.cmake + DESTINATION lib/cmake/Consumer + ) + +# generate the export targets for the build tree +# needs to be after the install(TARGETS ) command +export(EXPORT ConsumerTargets + FILE "${CMAKE_CURRENT_BINARY_DIR}/ConsumerTargets.cmake" +) diff --git a/Help/guide/tutorial/Consumer/Config.cmake.in b/Help/guide/tutorial/Consumer/Config.cmake.in new file mode 100644 index 0000000..0b3f1e4 --- /dev/null +++ b/Help/guide/tutorial/Consumer/Config.cmake.in @@ -0,0 +1,14 @@ + +@PACKAGE_INIT@ + +include(CMakeFindDependencyMacro) + +function(find_external_dependency name) + set(${name}_ROOT "" CACHE PATH "Root directory to find ${name}") + mark_as_advanced(${name}_DIR) + find_dependency(${name} PATHS ${${name}_ROOT} REQUIRED) +endfunction() + +find_external_dependency(MathFunctions) + +include ( "${CMAKE_CURRENT_LIST_DIR}/ConsumerTargets.cmake" ) diff --git a/Help/guide/tutorial/Consumer/consumer.cxx b/Help/guide/tutorial/Consumer/consumer.cxx new file mode 100644 index 0000000..ae7877b --- /dev/null +++ b/Help/guide/tutorial/Consumer/consumer.cxx @@ -0,0 +1,11 @@ +// A simple function that computes the square root of a number +#include <iostream> +#include <sstream> +#include <string> + +#include "MathFunctions.h" + +double string_square_root(std::string const& value) +{ + return mathfunctions::sqrt(std::stod(value)); +} diff --git a/Help/guide/tutorial/MultiPackage/CMakeLists.txt b/Help/guide/tutorial/MultiPackage/CMakeLists.txt new file mode 100644 index 0000000..01d417a --- /dev/null +++ b/Help/guide/tutorial/MultiPackage/CMakeLists.txt @@ -0,0 +1,112 @@ +cmake_minimum_required(VERSION 3.10) + +# set the project name and version +project(Tutorial VERSION 1.0) + +set(CMAKE_CXX_STANDARD 11) +set(CMAKE_CXX_STANDARD_REQUIRED True) + + +# control where the static and shared libraries are built so that on windows +# we don't need to tinker with the path to run the executable +set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") +set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") +set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") + +option(BUILD_SHARED_LIBS "Build using shared libraries" ON) + +if(APPLE) + set(CMAKE_INSTALL_RPATH "@executable_path/../lib") +elseif(UNIX) + set(CMAKE_INSTALL_RPATH "$ORIGIN/../lib") +endif() + +# configure a header file to pass the version number only +configure_file(TutorialConfig.h.in TutorialConfig.h) + +# add the MathFunctions library +add_subdirectory(MathFunctions) + +# add the executable +add_executable(Tutorial tutorial.cxx) +target_link_libraries(Tutorial PUBLIC MathFunctions) + +# add the binary tree to the search path for include files +# so that we will find TutorialConfig.h +target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + ) + +# add the install targets +install(TARGETS Tutorial DESTINATION bin) +install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" + DESTINATION include + ) + +# enable testing +enable_testing() + +# does the application run +add_test(NAME Runs COMMAND Tutorial 25) + +# does the usage message work? +add_test(NAME Usage COMMAND Tutorial) +set_tests_properties(Usage + PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number" + ) + +# define a function to simplify adding tests +function(do_test target arg result) + add_test(NAME Comp${arg} COMMAND ${target} ${arg}) + set_tests_properties(Comp${arg} + PROPERTIES PASS_REGULAR_EXPRESSION ${result} + ) +endfunction(do_test) + +# do a bunch of result based tests +do_test(Tutorial 4 "4 is 2") +do_test(Tutorial 9 "9 is 3") +do_test(Tutorial 5 "5 is 2.236") +do_test(Tutorial 7 "7 is 2.645") +do_test(Tutorial 25 "25 is 5") +do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial 0.0001 "0.0001 is 0.01") + +include(InstallRequiredSystemLibraries) +set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt") +set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}") +set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}") +include(CPack) + +# install the configuration targets +install(EXPORT MathFunctionsTargets + FILE MathFunctionsTargets.cmake + DESTINATION lib/cmake/MathFunctions +) + +include(CMakePackageConfigHelpers) +# generate the config file that is includes the exports +configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in + "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake" + INSTALL_DESTINATION "lib/cmake/example" + NO_SET_AND_CHECK_MACRO + NO_CHECK_REQUIRED_COMPONENTS_MACRO + ) +# generate the version file for the config file +write_basic_package_version_file( + "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfigVersion.cmake" + VERSION "${Tutorial_VERSION_MAJOR}.${Tutorial_VERSION_MINOR}" + COMPATIBILITY AnyNewerVersion +) + +# install the configuration file +install(FILES + ${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake + DESTINATION lib/cmake/MathFunctions + ) + +# generate the export targets for the build tree +# needs to be after the install(TARGETS ) command +export(EXPORT MathFunctionsTargets + FILE "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsTargets.cmake" +) diff --git a/Help/guide/tutorial/MultiPackage/Config.cmake.in b/Help/guide/tutorial/MultiPackage/Config.cmake.in new file mode 100644 index 0000000..17cbabd --- /dev/null +++ b/Help/guide/tutorial/MultiPackage/Config.cmake.in @@ -0,0 +1,4 @@ + +@PACKAGE_INIT@ + +include ( "${CMAKE_CURRENT_LIST_DIR}/MathFunctionsTargets.cmake" ) diff --git a/Help/guide/tutorial/MultiPackage/License.txt b/Help/guide/tutorial/MultiPackage/License.txt new file mode 100644 index 0000000..c62d00b --- /dev/null +++ b/Help/guide/tutorial/MultiPackage/License.txt @@ -0,0 +1,2 @@ +This is the open source License.txt file introduced in +CMake/Tutorial/Step7... diff --git a/Help/guide/tutorial/MultiPackage/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/MultiPackage/MathFunctions/CMakeLists.txt new file mode 100644 index 0000000..a2df2a7 --- /dev/null +++ b/Help/guide/tutorial/MultiPackage/MathFunctions/CMakeLists.txt @@ -0,0 +1,59 @@ +# add the library that runs +add_library(MathFunctions MathFunctions.cxx) + +# state that anybody linking to us needs to include the current source dir +# to find MathFunctions.h, while we don't. +target_include_directories(MathFunctions + INTERFACE + $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}> + $<INSTALL_INTERFACE:include> + ) + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) +if(USE_MYMATH) + + target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") + + # first we add the executable that generates the table + add_executable(MakeTable MakeTable.cxx) + + # add the command to generate the source code + add_custom_command( + OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h + COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h + DEPENDS MakeTable + ) + + # library that just does sqrt + add_library(SqrtLibrary STATIC + mysqrt.cxx + ${CMAKE_CURRENT_BINARY_DIR}/Table.h + ) + + # state that we depend on our binary dir to find Table.h + target_include_directories(SqrtLibrary PRIVATE + ${CMAKE_CURRENT_BINARY_DIR} + ) + + # state that SqrtLibrary need PIC when the default is shared libraries + set_target_properties(SqrtLibrary PROPERTIES + POSITION_INDEPENDENT_CODE ${BUILD_SHARED_LIBS} + ) + + target_link_libraries(MathFunctions PRIVATE SqrtLibrary) +endif() + +# define the symbol stating we are using the declspec(dllexport) when +# building on windows +target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH") + +# setup the version numbering +set_property(TARGET MathFunctions PROPERTY VERSION "1.0.0") +set_property(TARGET MathFunctions PROPERTY SOVERSION "1") + +# install rules +install(TARGETS MathFunctions + DESTINATION lib + EXPORT MathFunctionsTargets) +install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/MultiPackage/MathFunctions/MakeTable.cxx b/Help/guide/tutorial/MultiPackage/MathFunctions/MakeTable.cxx new file mode 100644 index 0000000..ee58556 --- /dev/null +++ b/Help/guide/tutorial/MultiPackage/MathFunctions/MakeTable.cxx @@ -0,0 +1,25 @@ +// A simple program that builds a sqrt table +#include <cmath> +#include <fstream> +#include <iostream> + +int main(int argc, char* argv[]) +{ + // make sure we have enough arguments + if (argc < 2) { + return 1; + } + + std::ofstream fout(argv[1], std::ios_base::out); + const bool fileOpen = fout.is_open(); + if (fileOpen) { + fout << "double sqrtTable[] = {" << std::endl; + for (int i = 0; i < 10; ++i) { + fout << sqrt(static_cast<double>(i)) << "," << std::endl; + } + // close the table with a zero + fout << "0};" << std::endl; + fout.close(); + } + return fileOpen ? 0 : 1; // return 0 if wrote the file +} diff --git a/Help/guide/tutorial/MultiPackage/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/MultiPackage/MathFunctions/MathFunctions.cxx new file mode 100644 index 0000000..0145300 --- /dev/null +++ b/Help/guide/tutorial/MultiPackage/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) +{ +#ifdef USE_MYMATH + return detail::mysqrt(x); +#else + return std::sqrt(x); +#endif +} +} diff --git a/Help/guide/tutorial/MultiPackage/MathFunctions/MathFunctions.h b/Help/guide/tutorial/MultiPackage/MathFunctions/MathFunctions.h new file mode 100644 index 0000000..3fb547b --- /dev/null +++ b/Help/guide/tutorial/MultiPackage/MathFunctions/MathFunctions.h @@ -0,0 +1,14 @@ + +#if defined(_WIN32) +# if defined(EXPORTING_MYMATH) +# define DECLSPEC __declspec(dllexport) +# else +# define DECLSPEC __declspec(dllimport) +# endif +#else // non windows +# define DECLSPEC +#endif + +namespace mathfunctions { +double DECLSPEC sqrt(double x); +} diff --git a/Help/guide/tutorial/MultiPackage/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/MultiPackage/MathFunctions/mysqrt.cxx new file mode 100644 index 0000000..5e622be --- /dev/null +++ b/Help/guide/tutorial/MultiPackage/MathFunctions/mysqrt.cxx @@ -0,0 +1,38 @@ +#include <iostream> + +#include "MathFunctions.h" + +// include the generated table +#include "Table.h" + +namespace mathfunctions { +namespace detail { +// a hack square root calculation using simple operations +double mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + // use the table to help find an initial value + double result = x; + if (x >= 1 && x < 10) { + result = sqrtTable[static_cast<int>(x)]; + } + + // if we have both log and exp then use them + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; + } + + return result; +} +} +} diff --git a/Help/guide/tutorial/MultiPackage/MathFunctions/mysqrt.h b/Help/guide/tutorial/MultiPackage/MathFunctions/mysqrt.h new file mode 100644 index 0000000..e1c42ef --- /dev/null +++ b/Help/guide/tutorial/MultiPackage/MathFunctions/mysqrt.h @@ -0,0 +1,6 @@ + +namespace mathfunctions { +namespace detail { +double mysqrt(double x); +} +} diff --git a/Help/guide/tutorial/MultiPackage/MultiCPackConfig.cmake b/Help/guide/tutorial/MultiPackage/MultiCPackConfig.cmake new file mode 100644 index 0000000..403b633 --- /dev/null +++ b/Help/guide/tutorial/MultiPackage/MultiCPackConfig.cmake @@ -0,0 +1,7 @@ + +include("release/CPackConfig.cmake") + +set(CPACK_INSTALL_CMAKE_PROJECTS + "debug;Tutorial;ALL;/" + "release;Tutorial;ALL;/" + ) diff --git a/Help/guide/tutorial/MultiPackage/TutorialConfig.h.in b/Help/guide/tutorial/MultiPackage/TutorialConfig.h.in new file mode 100644 index 0000000..8cd2fc9 --- /dev/null +++ b/Help/guide/tutorial/MultiPackage/TutorialConfig.h.in @@ -0,0 +1,3 @@ +// the configured version number +#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ +#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ diff --git a/Help/guide/tutorial/MultiPackage/tutorial.cxx b/Help/guide/tutorial/MultiPackage/tutorial.cxx new file mode 100644 index 0000000..f97805b --- /dev/null +++ b/Help/guide/tutorial/MultiPackage/tutorial.cxx @@ -0,0 +1,25 @@ +// A simple program that computes the square root of a number +#include <iostream> +#include <string> + +#include "MathFunctions.h" +#include "TutorialConfig.h" + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." + << Tutorial_VERSION_MINOR << std::endl; + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + double inputValue = std::stod(argv[1]); + + const double outputValue = mathfunctions::sqrt(inputValue); + + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; + return 0; +} diff --git a/Help/guide/tutorial/Step1/tutorial.cxx b/Help/guide/tutorial/Step1/tutorial.cxx new file mode 100644 index 0000000..08323bf --- /dev/null +++ b/Help/guide/tutorial/Step1/tutorial.cxx @@ -0,0 +1,22 @@ +// A simple program that computes the square root of a number +#include <cmath> +#include <cstdlib> +#include <iostream> +#include <string> + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + const double inputValue = atof(argv[1]); + + // calculate square root + const double outputValue = sqrt(inputValue); + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; + return 0; +} diff --git a/Help/guide/tutorial/Step10/CMakeLists.txt b/Help/guide/tutorial/Step10/CMakeLists.txt new file mode 100644 index 0000000..34ae70c --- /dev/null +++ b/Help/guide/tutorial/Step10/CMakeLists.txt @@ -0,0 +1,73 @@ +cmake_minimum_required(VERSION 3.10) + +# set the project name and version +project(Tutorial VERSION 1.0) + +# specify the C++ standard +set(CMAKE_CXX_STANDARD 11) +set(CMAKE_CXX_STANDARD_REQUIRED True) + +# control where the static and shared libraries are built so that on windows +# we don't need to tinker with the path to run the executable +set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") +set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") +set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") + +option(BUILD_SHARED_LIBS "Build using shared libraries" ON) + +# configure a header file to pass the version number only +configure_file(TutorialConfig.h.in TutorialConfig.h) + +# add the MathFunctions library +add_subdirectory(MathFunctions) + +# add the executable +add_executable(Tutorial tutorial.cxx) +target_link_libraries(Tutorial PUBLIC MathFunctions) + +# add the binary tree to the search path for include files +# so that we will find TutorialConfig.h +target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + ) + +# add the install targets +install(TARGETS Tutorial DESTINATION bin) +install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" + DESTINATION include + ) + +# enable testing +include(CTest) + +# does the application run +add_test(NAME Runs COMMAND Tutorial 25) + +# does the usage message work? +add_test(NAME Usage COMMAND Tutorial) +set_tests_properties(Usage + PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number" + ) + +# define a function to simplify adding tests +function(do_test target arg result) + add_test(NAME Comp${arg} COMMAND ${target} ${arg}) + set_tests_properties(Comp${arg} + PROPERTIES PASS_REGULAR_EXPRESSION ${result} + ) +endfunction(do_test) + +# do a bunch of result based tests +do_test(Tutorial 4 "4 is 2") +do_test(Tutorial 9 "9 is 3") +do_test(Tutorial 5 "5 is 2.236") +do_test(Tutorial 7 "7 is 2.645") +do_test(Tutorial 25 "25 is 5") +do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial 0.0001 "0.0001 is 0.01") + +include(InstallRequiredSystemLibraries) +set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt") +set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}") +set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}") +include(CPack) diff --git a/Help/guide/tutorial/Step10/CTestConfig.cmake b/Help/guide/tutorial/Step10/CTestConfig.cmake new file mode 100644 index 0000000..73efdb1 --- /dev/null +++ b/Help/guide/tutorial/Step10/CTestConfig.cmake @@ -0,0 +1,7 @@ +set(CTEST_PROJECT_NAME "CMakeTutorial") +set(CTEST_NIGHTLY_START_TIME "00:00:00 EST") + +set(CTEST_DROP_METHOD "http") +set(CTEST_DROP_SITE "my.cdash.org") +set(CTEST_DROP_LOCATION "/submit.php?project=CMakeTutorial") +set(CTEST_DROP_SITE_CDASH TRUE) diff --git a/Help/guide/tutorial/Step10/License.txt b/Help/guide/tutorial/Step10/License.txt new file mode 100644 index 0000000..c62d00b --- /dev/null +++ b/Help/guide/tutorial/Step10/License.txt @@ -0,0 +1,2 @@ +This is the open source License.txt file introduced in +CMake/Tutorial/Step7... diff --git a/Help/guide/tutorial/Step10/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step10/MathFunctions/CMakeLists.txt new file mode 100644 index 0000000..e0c0621 --- /dev/null +++ b/Help/guide/tutorial/Step10/MathFunctions/CMakeLists.txt @@ -0,0 +1,51 @@ +# add the library that runs +add_library(MathFunctions MathFunctions.cxx) + +# state that anybody linking to us needs to include the current source dir +# to find MathFunctions.h, while we don't. +target_include_directories(MathFunctions + INTERFACE ${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") + + # first we add the executable that generates the table + add_executable(MakeTable MakeTable.cxx) + + # add the command to generate the source code + add_custom_command( + OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h + COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h + DEPENDS MakeTable + ) + + # library that just does sqrt + add_library(SqrtLibrary STATIC + mysqrt.cxx + ${CMAKE_CURRENT_BINARY_DIR}/Table.h + ) + + # state that we depend on our binary dir to find Table.h + target_include_directories(SqrtLibrary PRIVATE + ${CMAKE_CURRENT_BINARY_DIR} + ) + + # state that SqrtLibrary need PIC when the default is shared libraries + set_target_properties(SqrtLibrary PROPERTIES + POSITION_INDEPENDENT_CODE ${BUILD_SHARED_LIBS} + ) + + target_link_libraries(MathFunctions PRIVATE SqrtLibrary) +endif() + +# define the symbol stating we are using the declspec(dllexport) when +# building on windows +target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH") + +# install rules +install(TARGETS MathFunctions DESTINATION lib) +install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Step10/MathFunctions/MakeTable.cxx b/Help/guide/tutorial/Step10/MathFunctions/MakeTable.cxx new file mode 100644 index 0000000..ee58556 --- /dev/null +++ b/Help/guide/tutorial/Step10/MathFunctions/MakeTable.cxx @@ -0,0 +1,25 @@ +// A simple program that builds a sqrt table +#include <cmath> +#include <fstream> +#include <iostream> + +int main(int argc, char* argv[]) +{ + // make sure we have enough arguments + if (argc < 2) { + return 1; + } + + std::ofstream fout(argv[1], std::ios_base::out); + const bool fileOpen = fout.is_open(); + if (fileOpen) { + fout << "double sqrtTable[] = {" << std::endl; + for (int i = 0; i < 10; ++i) { + fout << sqrt(static_cast<double>(i)) << "," << std::endl; + } + // close the table with a zero + fout << "0};" << std::endl; + fout.close(); + } + return fileOpen ? 0 : 1; // return 0 if wrote the file +} diff --git a/Help/guide/tutorial/Step10/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step10/MathFunctions/MathFunctions.cxx new file mode 100644 index 0000000..0145300 --- /dev/null +++ b/Help/guide/tutorial/Step10/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) +{ +#ifdef USE_MYMATH + return detail::mysqrt(x); +#else + return std::sqrt(x); +#endif +} +} diff --git a/Help/guide/tutorial/Step10/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step10/MathFunctions/MathFunctions.h new file mode 100644 index 0000000..3fb547b --- /dev/null +++ b/Help/guide/tutorial/Step10/MathFunctions/MathFunctions.h @@ -0,0 +1,14 @@ + +#if defined(_WIN32) +# if defined(EXPORTING_MYMATH) +# define DECLSPEC __declspec(dllexport) +# else +# define DECLSPEC __declspec(dllimport) +# endif +#else // non windows +# define DECLSPEC +#endif + +namespace mathfunctions { +double DECLSPEC sqrt(double x); +} diff --git a/Help/guide/tutorial/Step10/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step10/MathFunctions/mysqrt.cxx new file mode 100644 index 0000000..8153f18 --- /dev/null +++ b/Help/guide/tutorial/Step10/MathFunctions/mysqrt.cxx @@ -0,0 +1,37 @@ +#include <iostream> + +#include "MathFunctions.h" + +// include the generated table +#include "Table.h" + +namespace mathfunctions { +namespace detail { +// a hack square root calculation using simple operations +double mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + // use the table to help find an initial value + double result = x; + if (x >= 1 && x < 10) { + std::cout << "Use the table to help find an initial value " << std::endl; + result = sqrtTable[static_cast<int>(x)]; + } + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; + } + + return result; +} +} +} diff --git a/Help/guide/tutorial/Step10/MathFunctions/mysqrt.h b/Help/guide/tutorial/Step10/MathFunctions/mysqrt.h new file mode 100644 index 0000000..e1c42ef --- /dev/null +++ b/Help/guide/tutorial/Step10/MathFunctions/mysqrt.h @@ -0,0 +1,6 @@ + +namespace mathfunctions { +namespace detail { +double mysqrt(double x); +} +} diff --git a/Help/guide/tutorial/Step10/TutorialConfig.h.in b/Help/guide/tutorial/Step10/TutorialConfig.h.in new file mode 100644 index 0000000..7e4d7fa --- /dev/null +++ b/Help/guide/tutorial/Step10/TutorialConfig.h.in @@ -0,0 +1,3 @@ +// the configured options and settings for Tutorial +#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ +#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ diff --git a/Help/guide/tutorial/Step10/tutorial.cxx b/Help/guide/tutorial/Step10/tutorial.cxx new file mode 100644 index 0000000..37a0333 --- /dev/null +++ b/Help/guide/tutorial/Step10/tutorial.cxx @@ -0,0 +1,27 @@ +// A simple program that computes the square root of a number +#include <iostream> +#include <sstream> +#include <string> + +#include "MathFunctions.h" +#include "TutorialConfig.h" + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + // report version + std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." + << Tutorial_VERSION_MINOR << std::endl; + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + const double inputValue = std::stod(argv[1]); + + const double outputValue = mathfunctions::sqrt(inputValue); + + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; + return 0; +} diff --git a/Help/guide/tutorial/Step11/CMakeLists.txt b/Help/guide/tutorial/Step11/CMakeLists.txt new file mode 100644 index 0000000..4763951 --- /dev/null +++ b/Help/guide/tutorial/Step11/CMakeLists.txt @@ -0,0 +1,81 @@ +cmake_minimum_required(VERSION 3.15) + +# set the project name and version +project(Tutorial VERSION 1.0) + +add_library(tutorial_compiler_flags INTERFACE) +target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11) + +# add compiler warning flags just when building this project via +# the BUILD_INTERFACE genex +set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU>") +set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>") +target_compile_options(tutorial_compiler_flags INTERFACE + "$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>" + "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>" +) + +# control where the static and shared libraries are built so that on windows +# we don't need to tinker with the path to run the executable +set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") +set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") +set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") + +option(BUILD_SHARED_LIBS "Build using shared libraries" ON) + +# configure a header file to pass the version number only +configure_file(TutorialConfig.h.in TutorialConfig.h) + +# add the MathFunctions library +add_subdirectory(MathFunctions) + +# add the executable +add_executable(Tutorial tutorial.cxx) +target_link_libraries(Tutorial PUBLIC MathFunctions) + +# add the binary tree to the search path for include files +# so that we will find TutorialConfig.h +target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + ) + +# add the install targets +install(TARGETS Tutorial DESTINATION bin) +install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" + DESTINATION include + ) + +# enable testing +enable_testing() + +# does the application run +add_test(NAME Runs COMMAND Tutorial 25) + +# does the usage message work? +add_test(NAME Usage COMMAND Tutorial) +set_tests_properties(Usage + PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number" + ) + +# define a function to simplify adding tests +function(do_test target arg result) + add_test(NAME Comp${arg} COMMAND ${target} ${arg}) + set_tests_properties(Comp${arg} + PROPERTIES PASS_REGULAR_EXPRESSION ${result} + ) +endfunction(do_test) + +# do a bunch of result based tests +do_test(Tutorial 4 "4 is 2") +do_test(Tutorial 9 "9 is 3") +do_test(Tutorial 5 "5 is 2.236") +do_test(Tutorial 7 "7 is 2.645") +do_test(Tutorial 25 "25 is 5") +do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial 0.0001 "0.0001 is 0.01") + +include(InstallRequiredSystemLibraries) +set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt") +set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}") +set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}") +include(CPack) diff --git a/Help/guide/tutorial/Step11/CTestConfig.cmake b/Help/guide/tutorial/Step11/CTestConfig.cmake new file mode 100644 index 0000000..73efdb1 --- /dev/null +++ b/Help/guide/tutorial/Step11/CTestConfig.cmake @@ -0,0 +1,7 @@ +set(CTEST_PROJECT_NAME "CMakeTutorial") +set(CTEST_NIGHTLY_START_TIME "00:00:00 EST") + +set(CTEST_DROP_METHOD "http") +set(CTEST_DROP_SITE "my.cdash.org") +set(CTEST_DROP_LOCATION "/submit.php?project=CMakeTutorial") +set(CTEST_DROP_SITE_CDASH TRUE) diff --git a/Help/guide/tutorial/Step11/License.txt b/Help/guide/tutorial/Step11/License.txt new file mode 100644 index 0000000..c62d00b --- /dev/null +++ b/Help/guide/tutorial/Step11/License.txt @@ -0,0 +1,2 @@ +This is the open source License.txt file introduced in +CMake/Tutorial/Step7... diff --git a/Help/guide/tutorial/Step11/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step11/MathFunctions/CMakeLists.txt new file mode 100644 index 0000000..e6cb8ba --- /dev/null +++ b/Help/guide/tutorial/Step11/MathFunctions/CMakeLists.txt @@ -0,0 +1,55 @@ +# add the library that runs +add_library(MathFunctions MathFunctions.cxx) + +# state that anybody linking to us needs to include the current source dir +# to find MathFunctions.h, while we don't. +target_include_directories(MathFunctions + INTERFACE ${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") + + # first we add the executable that generates the table + add_executable(MakeTable MakeTable.cxx) + target_link_libraries(MakeTable tutorial_compiler_flags) + + # add the command to generate the source code + add_custom_command( + OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h + COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h + DEPENDS MakeTable + ) + + # library that just does sqrt + add_library(SqrtLibrary STATIC + mysqrt.cxx + ${CMAKE_CURRENT_BINARY_DIR}/Table.h + ) + + # state that we depend on our binary dir to find Table.h + target_include_directories(SqrtLibrary PRIVATE + ${CMAKE_CURRENT_BINARY_DIR} + ) + + # state that SqrtLibrary need PIC when the default is shared libraries + set_target_properties(SqrtLibrary PROPERTIES + POSITION_INDEPENDENT_CODE ${BUILD_SHARED_LIBS} + ) + + target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags) + target_link_libraries(MathFunctions PRIVATE SqrtLibrary) +endif() + +target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) + +# define the symbol stating we are using the declspec(dllexport) when +#building on windows +target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH") + +# install rules +install(TARGETS MathFunctions DESTINATION lib) +install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Step11/MathFunctions/MakeTable.cxx b/Help/guide/tutorial/Step11/MathFunctions/MakeTable.cxx new file mode 100644 index 0000000..ee58556 --- /dev/null +++ b/Help/guide/tutorial/Step11/MathFunctions/MakeTable.cxx @@ -0,0 +1,25 @@ +// A simple program that builds a sqrt table +#include <cmath> +#include <fstream> +#include <iostream> + +int main(int argc, char* argv[]) +{ + // make sure we have enough arguments + if (argc < 2) { + return 1; + } + + std::ofstream fout(argv[1], std::ios_base::out); + const bool fileOpen = fout.is_open(); + if (fileOpen) { + fout << "double sqrtTable[] = {" << std::endl; + for (int i = 0; i < 10; ++i) { + fout << sqrt(static_cast<double>(i)) << "," << std::endl; + } + // close the table with a zero + fout << "0};" << std::endl; + fout.close(); + } + return fileOpen ? 0 : 1; // return 0 if wrote the file +} diff --git a/Help/guide/tutorial/Step11/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step11/MathFunctions/MathFunctions.cxx new file mode 100644 index 0000000..0145300 --- /dev/null +++ b/Help/guide/tutorial/Step11/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) +{ +#ifdef USE_MYMATH + return detail::mysqrt(x); +#else + return std::sqrt(x); +#endif +} +} diff --git a/Help/guide/tutorial/Step11/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step11/MathFunctions/MathFunctions.h new file mode 100644 index 0000000..3fb547b --- /dev/null +++ b/Help/guide/tutorial/Step11/MathFunctions/MathFunctions.h @@ -0,0 +1,14 @@ + +#if defined(_WIN32) +# if defined(EXPORTING_MYMATH) +# define DECLSPEC __declspec(dllexport) +# else +# define DECLSPEC __declspec(dllimport) +# endif +#else // non windows +# define DECLSPEC +#endif + +namespace mathfunctions { +double DECLSPEC sqrt(double x); +} diff --git a/Help/guide/tutorial/Step11/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step11/MathFunctions/mysqrt.cxx new file mode 100644 index 0000000..8153f18 --- /dev/null +++ b/Help/guide/tutorial/Step11/MathFunctions/mysqrt.cxx @@ -0,0 +1,37 @@ +#include <iostream> + +#include "MathFunctions.h" + +// include the generated table +#include "Table.h" + +namespace mathfunctions { +namespace detail { +// a hack square root calculation using simple operations +double mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + // use the table to help find an initial value + double result = x; + if (x >= 1 && x < 10) { + std::cout << "Use the table to help find an initial value " << std::endl; + result = sqrtTable[static_cast<int>(x)]; + } + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; + } + + return result; +} +} +} diff --git a/Help/guide/tutorial/Step11/MathFunctions/mysqrt.h b/Help/guide/tutorial/Step11/MathFunctions/mysqrt.h new file mode 100644 index 0000000..e1c42ef --- /dev/null +++ b/Help/guide/tutorial/Step11/MathFunctions/mysqrt.h @@ -0,0 +1,6 @@ + +namespace mathfunctions { +namespace detail { +double mysqrt(double x); +} +} diff --git a/Help/guide/tutorial/Step11/TutorialConfig.h.in b/Help/guide/tutorial/Step11/TutorialConfig.h.in new file mode 100644 index 0000000..7e4d7fa --- /dev/null +++ b/Help/guide/tutorial/Step11/TutorialConfig.h.in @@ -0,0 +1,3 @@ +// the configured options and settings for Tutorial +#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ +#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ diff --git a/Help/guide/tutorial/Step11/tutorial.cxx b/Help/guide/tutorial/Step11/tutorial.cxx new file mode 100644 index 0000000..a4f44d5 --- /dev/null +++ b/Help/guide/tutorial/Step11/tutorial.cxx @@ -0,0 +1,26 @@ +// A simple program that computes the square root of a number +#include <iostream> +#include <string> + +#include "MathFunctions.h" +#include "TutorialConfig.h" + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + // report version + std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." + << Tutorial_VERSION_MINOR << std::endl; + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + const double inputValue = std::stod(argv[1]); + + const double outputValue = mathfunctions::sqrt(inputValue); + + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; + return 0; +} diff --git a/Help/guide/tutorial/Step2/CMakeLists.txt b/Help/guide/tutorial/Step2/CMakeLists.txt new file mode 100644 index 0000000..7aa59e9 --- /dev/null +++ b/Help/guide/tutorial/Step2/CMakeLists.txt @@ -0,0 +1,21 @@ +cmake_minimum_required(VERSION 3.10) + +# set the project name and version +project(Tutorial VERSION 1.0) + +# specify the C++ standard +set(CMAKE_CXX_STANDARD 11) +set(CMAKE_CXX_STANDARD_REQUIRED True) + +# configure a header file to pass some of the CMake settings +# to the source code +configure_file(TutorialConfig.h.in TutorialConfig.h) + +# add the executable +add_executable(Tutorial tutorial.cxx) + +# add the binary tree to the search path for include files +# so that we will find TutorialConfig.h +target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + ) diff --git a/Help/guide/tutorial/Step2/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step2/MathFunctions/MathFunctions.h new file mode 100644 index 0000000..cd36bcc --- /dev/null +++ b/Help/guide/tutorial/Step2/MathFunctions/MathFunctions.h @@ -0,0 +1 @@ +double mysqrt(double x); diff --git a/Help/guide/tutorial/Step2/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step2/MathFunctions/mysqrt.cxx new file mode 100644 index 0000000..1e4d97a --- /dev/null +++ b/Help/guide/tutorial/Step2/MathFunctions/mysqrt.cxx @@ -0,0 +1,22 @@ +#include <iostream> + +// a hack square root calculation using simple operations +double mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + double result = x; + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; + } + return result; +} diff --git a/Help/guide/tutorial/Step2/TutorialConfig.h.in b/Help/guide/tutorial/Step2/TutorialConfig.h.in new file mode 100644 index 0000000..7e4d7fa --- /dev/null +++ b/Help/guide/tutorial/Step2/TutorialConfig.h.in @@ -0,0 +1,3 @@ +// the configured options and settings for Tutorial +#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ +#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ diff --git a/Help/guide/tutorial/Step2/tutorial.cxx b/Help/guide/tutorial/Step2/tutorial.cxx new file mode 100644 index 0000000..53b0810 --- /dev/null +++ b/Help/guide/tutorial/Step2/tutorial.cxx @@ -0,0 +1,26 @@ +// A simple program that computes the square root of a number +#include <cmath> +#include <iostream> +#include <string> + +#include "TutorialConfig.h" + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + // report version + std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." + << Tutorial_VERSION_MINOR << std::endl; + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + const double inputValue = std::stod(argv[1]); + + // calculate square root + const double outputValue = sqrt(inputValue); + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; + return 0; +} diff --git a/Help/guide/tutorial/Step3/CMakeLists.txt b/Help/guide/tutorial/Step3/CMakeLists.txt new file mode 100644 index 0000000..1c12816 --- /dev/null +++ b/Help/guide/tutorial/Step3/CMakeLists.txt @@ -0,0 +1,34 @@ +cmake_minimum_required(VERSION 3.10) + +# set the project name and version +project(Tutorial VERSION 1.0) + +# specify the C++ standard +set(CMAKE_CXX_STANDARD 11) +set(CMAKE_CXX_STANDARD_REQUIRED True) + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) + +# 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) + list(APPEND EXTRA_INCLUDES "${PROJECT_SOURCE_DIR}/MathFunctions") +endif() + +# add the executable +add_executable(Tutorial tutorial.cxx) + +target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS}) + +# add the binary tree to the search path for include files +# so that we will find TutorialConfig.h +target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + ${EXTRA_INCLUDES} + ) diff --git a/Help/guide/tutorial/Step3/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step3/MathFunctions/CMakeLists.txt new file mode 100644 index 0000000..8b443a6 --- /dev/null +++ b/Help/guide/tutorial/Step3/MathFunctions/CMakeLists.txt @@ -0,0 +1 @@ +add_library(MathFunctions mysqrt.cxx) diff --git a/Help/guide/tutorial/Step3/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step3/MathFunctions/MathFunctions.h new file mode 100644 index 0000000..cd36bcc --- /dev/null +++ b/Help/guide/tutorial/Step3/MathFunctions/MathFunctions.h @@ -0,0 +1 @@ +double mysqrt(double x); diff --git a/Help/guide/tutorial/Step3/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step3/MathFunctions/mysqrt.cxx new file mode 100644 index 0000000..abe767d --- /dev/null +++ b/Help/guide/tutorial/Step3/MathFunctions/mysqrt.cxx @@ -0,0 +1,24 @@ +#include <iostream> + +#include "MathFunctions.h" + +// a hack square root calculation using simple operations +double mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + double result = x; + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; + } + return result; +} diff --git a/Help/guide/tutorial/Step3/TutorialConfig.h.in b/Help/guide/tutorial/Step3/TutorialConfig.h.in new file mode 100644 index 0000000..e23f521 --- /dev/null +++ b/Help/guide/tutorial/Step3/TutorialConfig.h.in @@ -0,0 +1,4 @@ +// 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 new file mode 100644 index 0000000..b3c6a4f --- /dev/null +++ b/Help/guide/tutorial/Step3/tutorial.cxx @@ -0,0 +1,36 @@ +// A simple program that computes the square root of a number +#include <cmath> +#include <iostream> +#include <string> + +#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) { + // report version + std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." + << Tutorial_VERSION_MINOR << std::endl; + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + const double inputValue = std::stod(argv[1]); + + // which square root function should we use? +#ifdef USE_MYMATH + const double outputValue = mysqrt(inputValue); +#else + const double outputValue = sqrt(inputValue); +#endif + + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; + return 0; +} diff --git a/Help/guide/tutorial/Step4/CMakeLists.txt b/Help/guide/tutorial/Step4/CMakeLists.txt new file mode 100644 index 0000000..38e9b1f --- /dev/null +++ b/Help/guide/tutorial/Step4/CMakeLists.txt @@ -0,0 +1,32 @@ +cmake_minimum_required(VERSION 3.10) + +# set the project name and version +project(Tutorial VERSION 1.0) + +# specify the C++ standard +set(CMAKE_CXX_STANDARD 11) +set(CMAKE_CXX_STANDARD_REQUIRED True) + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) + +# 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 the executable +add_executable(Tutorial tutorial.cxx) + +target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS}) + +# add the binary tree to the search path for include files +# so that we will find TutorialConfig.h +target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + ) diff --git a/Help/guide/tutorial/Step4/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step4/MathFunctions/CMakeLists.txt new file mode 100644 index 0000000..0515852 --- /dev/null +++ b/Help/guide/tutorial/Step4/MathFunctions/CMakeLists.txt @@ -0,0 +1,7 @@ +add_library(MathFunctions mysqrt.cxx) + +# state that anybody linking to us needs to include the current source dir +# to find MathFunctions.h, while we don't. +target_include_directories(MathFunctions + INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} + ) diff --git a/Help/guide/tutorial/Step4/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step4/MathFunctions/MathFunctions.h new file mode 100644 index 0000000..cd36bcc --- /dev/null +++ b/Help/guide/tutorial/Step4/MathFunctions/MathFunctions.h @@ -0,0 +1 @@ +double mysqrt(double x); diff --git a/Help/guide/tutorial/Step4/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step4/MathFunctions/mysqrt.cxx new file mode 100644 index 0000000..abe767d --- /dev/null +++ b/Help/guide/tutorial/Step4/MathFunctions/mysqrt.cxx @@ -0,0 +1,24 @@ +#include <iostream> + +#include "MathFunctions.h" + +// a hack square root calculation using simple operations +double mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + double result = x; + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; + } + return result; +} diff --git a/Help/guide/tutorial/Step4/TutorialConfig.h.in b/Help/guide/tutorial/Step4/TutorialConfig.h.in new file mode 100644 index 0000000..e23f521 --- /dev/null +++ b/Help/guide/tutorial/Step4/TutorialConfig.h.in @@ -0,0 +1,4 @@ +// 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 new file mode 100644 index 0000000..b3c6a4f --- /dev/null +++ b/Help/guide/tutorial/Step4/tutorial.cxx @@ -0,0 +1,36 @@ +// A simple program that computes the square root of a number +#include <cmath> +#include <iostream> +#include <string> + +#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) { + // report version + std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." + << Tutorial_VERSION_MINOR << std::endl; + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + const double inputValue = std::stod(argv[1]); + + // which square root function should we use? +#ifdef USE_MYMATH + const double outputValue = mysqrt(inputValue); +#else + const double outputValue = sqrt(inputValue); +#endif + + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; + return 0; +} diff --git a/Help/guide/tutorial/Step5/CMakeLists.txt b/Help/guide/tutorial/Step5/CMakeLists.txt new file mode 100644 index 0000000..c3b375a --- /dev/null +++ b/Help/guide/tutorial/Step5/CMakeLists.txt @@ -0,0 +1,66 @@ +cmake_minimum_required(VERSION 3.10) + +# set the project name and version +project(Tutorial VERSION 1.0) + +# specify the C++ standard +set(CMAKE_CXX_STANDARD 11) +set(CMAKE_CXX_STANDARD_REQUIRED True) + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) + +# 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 the executable +add_executable(Tutorial tutorial.cxx) +target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS}) + +# add the binary tree to the search path for include files +# so that we will find TutorialConfig.h +target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + ) + +# add the install targets +install(TARGETS Tutorial DESTINATION bin) +install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" + DESTINATION include + ) + +# enable testing +enable_testing() + +# does the application run +add_test(NAME Runs COMMAND Tutorial 25) + +# does the usage message work? +add_test(NAME Usage COMMAND Tutorial) +set_tests_properties(Usage + PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number" + ) + +# define a function to simplify adding tests +function(do_test target arg result) + add_test(NAME Comp${arg} COMMAND ${target} ${arg}) + set_tests_properties(Comp${arg} + PROPERTIES PASS_REGULAR_EXPRESSION ${result} + ) +endfunction(do_test) + +# do a bunch of result based tests +do_test(Tutorial 4 "4 is 2") +do_test(Tutorial 9 "9 is 3") +do_test(Tutorial 5 "5 is 2.236") +do_test(Tutorial 7 "7 is 2.645") +do_test(Tutorial 25 "25 is 5") +do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial 0.0001 "0.0001 is 0.01") diff --git a/Help/guide/tutorial/Step5/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step5/MathFunctions/CMakeLists.txt new file mode 100644 index 0000000..b12f27d --- /dev/null +++ b/Help/guide/tutorial/Step5/MathFunctions/CMakeLists.txt @@ -0,0 +1,11 @@ +add_library(MathFunctions mysqrt.cxx) + +# state that anybody linking to us needs to include the current source dir +# to find MathFunctions.h, while we don't. +target_include_directories(MathFunctions + INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} + ) + +# install rules +install(TARGETS MathFunctions DESTINATION lib) +install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Step5/MathFunctions/MakeTable.cxx b/Help/guide/tutorial/Step5/MathFunctions/MakeTable.cxx new file mode 100644 index 0000000..ee58556 --- /dev/null +++ b/Help/guide/tutorial/Step5/MathFunctions/MakeTable.cxx @@ -0,0 +1,25 @@ +// A simple program that builds a sqrt table +#include <cmath> +#include <fstream> +#include <iostream> + +int main(int argc, char* argv[]) +{ + // make sure we have enough arguments + if (argc < 2) { + return 1; + } + + std::ofstream fout(argv[1], std::ios_base::out); + const bool fileOpen = fout.is_open(); + if (fileOpen) { + fout << "double sqrtTable[] = {" << std::endl; + for (int i = 0; i < 10; ++i) { + fout << sqrt(static_cast<double>(i)) << "," << std::endl; + } + // close the table with a zero + fout << "0};" << std::endl; + fout.close(); + } + return fileOpen ? 0 : 1; // return 0 if wrote the file +} diff --git a/Help/guide/tutorial/Step5/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step5/MathFunctions/MathFunctions.h new file mode 100644 index 0000000..cd36bcc --- /dev/null +++ b/Help/guide/tutorial/Step5/MathFunctions/MathFunctions.h @@ -0,0 +1 @@ +double mysqrt(double x); diff --git a/Help/guide/tutorial/Step5/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step5/MathFunctions/mysqrt.cxx new file mode 100644 index 0000000..abe767d --- /dev/null +++ b/Help/guide/tutorial/Step5/MathFunctions/mysqrt.cxx @@ -0,0 +1,24 @@ +#include <iostream> + +#include "MathFunctions.h" + +// a hack square root calculation using simple operations +double mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + double result = x; + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; + } + return result; +} diff --git a/Help/guide/tutorial/Step5/TutorialConfig.h.in b/Help/guide/tutorial/Step5/TutorialConfig.h.in new file mode 100644 index 0000000..e23f521 --- /dev/null +++ b/Help/guide/tutorial/Step5/TutorialConfig.h.in @@ -0,0 +1,4 @@ +// 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 new file mode 100644 index 0000000..b3c6a4f --- /dev/null +++ b/Help/guide/tutorial/Step5/tutorial.cxx @@ -0,0 +1,36 @@ +// A simple program that computes the square root of a number +#include <cmath> +#include <iostream> +#include <string> + +#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) { + // report version + std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." + << Tutorial_VERSION_MINOR << std::endl; + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + const double inputValue = std::stod(argv[1]); + + // which square root function should we use? +#ifdef USE_MYMATH + const double outputValue = mysqrt(inputValue); +#else + const double outputValue = sqrt(inputValue); +#endif + + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; + return 0; +} diff --git a/Help/guide/tutorial/Step6/CMakeLists.txt b/Help/guide/tutorial/Step6/CMakeLists.txt new file mode 100644 index 0000000..c3b375a --- /dev/null +++ b/Help/guide/tutorial/Step6/CMakeLists.txt @@ -0,0 +1,66 @@ +cmake_minimum_required(VERSION 3.10) + +# set the project name and version +project(Tutorial VERSION 1.0) + +# specify the C++ standard +set(CMAKE_CXX_STANDARD 11) +set(CMAKE_CXX_STANDARD_REQUIRED True) + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) + +# 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 the executable +add_executable(Tutorial tutorial.cxx) +target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS}) + +# add the binary tree to the search path for include files +# so that we will find TutorialConfig.h +target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + ) + +# add the install targets +install(TARGETS Tutorial DESTINATION bin) +install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" + DESTINATION include + ) + +# enable testing +enable_testing() + +# does the application run +add_test(NAME Runs COMMAND Tutorial 25) + +# does the usage message work? +add_test(NAME Usage COMMAND Tutorial) +set_tests_properties(Usage + PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number" + ) + +# define a function to simplify adding tests +function(do_test target arg result) + add_test(NAME Comp${arg} COMMAND ${target} ${arg}) + set_tests_properties(Comp${arg} + PROPERTIES PASS_REGULAR_EXPRESSION ${result} + ) +endfunction(do_test) + +# do a bunch of result based tests +do_test(Tutorial 4 "4 is 2") +do_test(Tutorial 9 "9 is 3") +do_test(Tutorial 5 "5 is 2.236") +do_test(Tutorial 7 "7 is 2.645") +do_test(Tutorial 25 "25 is 5") +do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial 0.0001 "0.0001 is 0.01") diff --git a/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt new file mode 100644 index 0000000..4bf6024 --- /dev/null +++ b/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt @@ -0,0 +1,22 @@ +add_library(MathFunctions mysqrt.cxx) + +# state that anybody linking to us needs to include the current source dir +# to find MathFunctions.h, while we don't. +target_include_directories(MathFunctions + INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} + ) + +# does this system provide the log and exp functions? +include(CheckSymbolExists) +set(CMAKE_REQUIRED_LIBRARIES "m") +check_symbol_exists(log "math.h" HAVE_LOG) +check_symbol_exists(exp "math.h" HAVE_EXP) + +if(HAVE_LOG AND HAVE_EXP) + target_compile_definitions(MathFunctions + PRIVATE "HAVE_LOG" "HAVE_EXP") +endif() + +# install rules +install(TARGETS MathFunctions DESTINATION lib) +install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Step6/MathFunctions/MakeTable.cxx b/Help/guide/tutorial/Step6/MathFunctions/MakeTable.cxx new file mode 100644 index 0000000..ee58556 --- /dev/null +++ b/Help/guide/tutorial/Step6/MathFunctions/MakeTable.cxx @@ -0,0 +1,25 @@ +// A simple program that builds a sqrt table +#include <cmath> +#include <fstream> +#include <iostream> + +int main(int argc, char* argv[]) +{ + // make sure we have enough arguments + if (argc < 2) { + return 1; + } + + std::ofstream fout(argv[1], std::ios_base::out); + const bool fileOpen = fout.is_open(); + if (fileOpen) { + fout << "double sqrtTable[] = {" << std::endl; + for (int i = 0; i < 10; ++i) { + fout << sqrt(static_cast<double>(i)) << "," << std::endl; + } + // close the table with a zero + fout << "0};" << std::endl; + fout.close(); + } + return fileOpen ? 0 : 1; // return 0 if wrote the file +} diff --git a/Help/guide/tutorial/Step6/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step6/MathFunctions/MathFunctions.h new file mode 100644 index 0000000..cd36bcc --- /dev/null +++ b/Help/guide/tutorial/Step6/MathFunctions/MathFunctions.h @@ -0,0 +1 @@ +double mysqrt(double x); diff --git a/Help/guide/tutorial/Step6/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step6/MathFunctions/mysqrt.cxx new file mode 100644 index 0000000..0637063 --- /dev/null +++ b/Help/guide/tutorial/Step6/MathFunctions/mysqrt.cxx @@ -0,0 +1,32 @@ +#include <cmath> +#include <iostream> + +#include "MathFunctions.h" + +// a hack square root calculation using simple operations +double mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + // if we have both log and exp then use them +#if defined(HAVE_LOG) && defined(HAVE_EXP) + double result = exp(log(x) * 0.5); + std::cout << "Computing sqrt of " << x << " to be " << result + << " using log and exp" << std::endl; +#else + double result = x; + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; + } +#endif + return result; +} diff --git a/Help/guide/tutorial/Step6/TutorialConfig.h.in b/Help/guide/tutorial/Step6/TutorialConfig.h.in new file mode 100644 index 0000000..e23f521 --- /dev/null +++ b/Help/guide/tutorial/Step6/TutorialConfig.h.in @@ -0,0 +1,4 @@ +// 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 new file mode 100644 index 0000000..b3c6a4f --- /dev/null +++ b/Help/guide/tutorial/Step6/tutorial.cxx @@ -0,0 +1,36 @@ +// A simple program that computes the square root of a number +#include <cmath> +#include <iostream> +#include <string> + +#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) { + // report version + std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." + << Tutorial_VERSION_MINOR << std::endl; + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + const double inputValue = std::stod(argv[1]); + + // which square root function should we use? +#ifdef USE_MYMATH + const double outputValue = mysqrt(inputValue); +#else + const double outputValue = sqrt(inputValue); +#endif + + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; + return 0; +} diff --git a/Help/guide/tutorial/Step7/CMakeLists.txt b/Help/guide/tutorial/Step7/CMakeLists.txt new file mode 100644 index 0000000..c3b375a --- /dev/null +++ b/Help/guide/tutorial/Step7/CMakeLists.txt @@ -0,0 +1,66 @@ +cmake_minimum_required(VERSION 3.10) + +# set the project name and version +project(Tutorial VERSION 1.0) + +# specify the C++ standard +set(CMAKE_CXX_STANDARD 11) +set(CMAKE_CXX_STANDARD_REQUIRED True) + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) + +# 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 the executable +add_executable(Tutorial tutorial.cxx) +target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS}) + +# add the binary tree to the search path for include files +# so that we will find TutorialConfig.h +target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + ) + +# add the install targets +install(TARGETS Tutorial DESTINATION bin) +install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" + DESTINATION include + ) + +# enable testing +enable_testing() + +# does the application run +add_test(NAME Runs COMMAND Tutorial 25) + +# does the usage message work? +add_test(NAME Usage COMMAND Tutorial) +set_tests_properties(Usage + PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number" + ) + +# define a function to simplify adding tests +function(do_test target arg result) + add_test(NAME Comp${arg} COMMAND ${target} ${arg}) + set_tests_properties(Comp${arg} + PROPERTIES PASS_REGULAR_EXPRESSION ${result} + ) +endfunction(do_test) + +# do a bunch of result based tests +do_test(Tutorial 4 "4 is 2") +do_test(Tutorial 9 "9 is 3") +do_test(Tutorial 5 "5 is 2.236") +do_test(Tutorial 7 "7 is 2.645") +do_test(Tutorial 25 "25 is 5") +do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial 0.0001 "0.0001 is 0.01") diff --git a/Help/guide/tutorial/Step7/License.txt b/Help/guide/tutorial/Step7/License.txt new file mode 100644 index 0000000..c62d00b --- /dev/null +++ b/Help/guide/tutorial/Step7/License.txt @@ -0,0 +1,2 @@ +This is the open source License.txt file introduced in +CMake/Tutorial/Step7... diff --git a/Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt new file mode 100644 index 0000000..9ede4b3 --- /dev/null +++ b/Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt @@ -0,0 +1,29 @@ +# 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 + ) + +# 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} + ) + +# install rules +install(TARGETS MathFunctions DESTINATION lib) +install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Step7/MathFunctions/MakeTable.cxx b/Help/guide/tutorial/Step7/MathFunctions/MakeTable.cxx new file mode 100644 index 0000000..ee58556 --- /dev/null +++ b/Help/guide/tutorial/Step7/MathFunctions/MakeTable.cxx @@ -0,0 +1,25 @@ +// A simple program that builds a sqrt table +#include <cmath> +#include <fstream> +#include <iostream> + +int main(int argc, char* argv[]) +{ + // make sure we have enough arguments + if (argc < 2) { + return 1; + } + + std::ofstream fout(argv[1], std::ios_base::out); + const bool fileOpen = fout.is_open(); + if (fileOpen) { + fout << "double sqrtTable[] = {" << std::endl; + for (int i = 0; i < 10; ++i) { + fout << sqrt(static_cast<double>(i)) << "," << std::endl; + } + // close the table with a zero + fout << "0};" << std::endl; + fout.close(); + } + return fileOpen ? 0 : 1; // return 0 if wrote the file +} diff --git a/Help/guide/tutorial/Step7/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step7/MathFunctions/MathFunctions.h new file mode 100644 index 0000000..cd36bcc --- /dev/null +++ b/Help/guide/tutorial/Step7/MathFunctions/MathFunctions.h @@ -0,0 +1 @@ +double mysqrt(double x); diff --git a/Help/guide/tutorial/Step7/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step7/MathFunctions/mysqrt.cxx new file mode 100644 index 0000000..7d80ee9 --- /dev/null +++ b/Help/guide/tutorial/Step7/MathFunctions/mysqrt.cxx @@ -0,0 +1,33 @@ +#include <iostream> + +#include "MathFunctions.h" + +// include the generated table +#include "Table.h" + +// a hack square root calculation using simple operations +double mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + // use the table to help find an initial value + double result = x; + if (x >= 1 && x < 10) { + std::cout << "Use the table to help find an initial value " << std::endl; + result = sqrtTable[static_cast<int>(x)]; + } + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; + } + + return result; +} diff --git a/Help/guide/tutorial/Step7/TutorialConfig.h.in b/Help/guide/tutorial/Step7/TutorialConfig.h.in new file mode 100644 index 0000000..e23f521 --- /dev/null +++ b/Help/guide/tutorial/Step7/TutorialConfig.h.in @@ -0,0 +1,4 @@ +// 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 new file mode 100644 index 0000000..b3c6a4f --- /dev/null +++ b/Help/guide/tutorial/Step7/tutorial.cxx @@ -0,0 +1,36 @@ +// A simple program that computes the square root of a number +#include <cmath> +#include <iostream> +#include <string> + +#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) { + // report version + std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." + << Tutorial_VERSION_MINOR << std::endl; + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + const double inputValue = std::stod(argv[1]); + + // which square root function should we use? +#ifdef USE_MYMATH + const double outputValue = mysqrt(inputValue); +#else + const double outputValue = sqrt(inputValue); +#endif + + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; + return 0; +} diff --git a/Help/guide/tutorial/Step8/CMakeLists.txt b/Help/guide/tutorial/Step8/CMakeLists.txt new file mode 100644 index 0000000..19b9913 --- /dev/null +++ b/Help/guide/tutorial/Step8/CMakeLists.txt @@ -0,0 +1,73 @@ +cmake_minimum_required(VERSION 3.10) + +# set the project name and version +project(Tutorial VERSION 1.0) + +# specify the C++ standard +set(CMAKE_CXX_STANDARD 11) +set(CMAKE_CXX_STANDARD_REQUIRED True) + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) + +# 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 the executable +add_executable(Tutorial tutorial.cxx) +target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS}) + +# add the binary tree to the search path for include files +# so that we will find TutorialConfig.h +target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + ) + +# add the install targets +install(TARGETS Tutorial DESTINATION bin) +install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" + DESTINATION include + ) + +# enable testing +enable_testing() + +# does the application run +add_test(NAME Runs COMMAND Tutorial 25) + +# does the usage message work? +add_test(NAME Usage COMMAND Tutorial) +set_tests_properties(Usage + PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number" + ) + +# define a function to simplify adding tests +function(do_test target arg result) + add_test(NAME Comp${arg} COMMAND ${target} ${arg}) + set_tests_properties(Comp${arg} + PROPERTIES PASS_REGULAR_EXPRESSION ${result} + ) +endfunction(do_test) + +# do a bunch of result based tests +do_test(Tutorial 4 "4 is 2") +do_test(Tutorial 9 "9 is 3") +do_test(Tutorial 5 "5 is 2.236") +do_test(Tutorial 7 "7 is 2.645") +do_test(Tutorial 25 "25 is 5") +do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial 0.0001 "0.0001 is 0.01") + +# setup installer +include(InstallRequiredSystemLibraries) +set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt") +set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}") +set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}") +include(CPack) diff --git a/Help/guide/tutorial/Step8/License.txt b/Help/guide/tutorial/Step8/License.txt new file mode 100644 index 0000000..c62d00b --- /dev/null +++ b/Help/guide/tutorial/Step8/License.txt @@ -0,0 +1,2 @@ +This is the open source License.txt file introduced in +CMake/Tutorial/Step7... diff --git a/Help/guide/tutorial/Step8/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step8/MathFunctions/CMakeLists.txt new file mode 100644 index 0000000..9ede4b3 --- /dev/null +++ b/Help/guide/tutorial/Step8/MathFunctions/CMakeLists.txt @@ -0,0 +1,29 @@ +# 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 + ) + +# 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} + ) + +# install rules +install(TARGETS MathFunctions DESTINATION lib) +install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Step8/MathFunctions/MakeTable.cxx b/Help/guide/tutorial/Step8/MathFunctions/MakeTable.cxx new file mode 100644 index 0000000..ee58556 --- /dev/null +++ b/Help/guide/tutorial/Step8/MathFunctions/MakeTable.cxx @@ -0,0 +1,25 @@ +// A simple program that builds a sqrt table +#include <cmath> +#include <fstream> +#include <iostream> + +int main(int argc, char* argv[]) +{ + // make sure we have enough arguments + if (argc < 2) { + return 1; + } + + std::ofstream fout(argv[1], std::ios_base::out); + const bool fileOpen = fout.is_open(); + if (fileOpen) { + fout << "double sqrtTable[] = {" << std::endl; + for (int i = 0; i < 10; ++i) { + fout << sqrt(static_cast<double>(i)) << "," << std::endl; + } + // close the table with a zero + fout << "0};" << std::endl; + fout.close(); + } + return fileOpen ? 0 : 1; // return 0 if wrote the file +} diff --git a/Help/guide/tutorial/Step8/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step8/MathFunctions/MathFunctions.h new file mode 100644 index 0000000..cd36bcc --- /dev/null +++ b/Help/guide/tutorial/Step8/MathFunctions/MathFunctions.h @@ -0,0 +1 @@ +double mysqrt(double x); diff --git a/Help/guide/tutorial/Step8/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step8/MathFunctions/mysqrt.cxx new file mode 100644 index 0000000..7d80ee9 --- /dev/null +++ b/Help/guide/tutorial/Step8/MathFunctions/mysqrt.cxx @@ -0,0 +1,33 @@ +#include <iostream> + +#include "MathFunctions.h" + +// include the generated table +#include "Table.h" + +// a hack square root calculation using simple operations +double mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + // use the table to help find an initial value + double result = x; + if (x >= 1 && x < 10) { + std::cout << "Use the table to help find an initial value " << std::endl; + result = sqrtTable[static_cast<int>(x)]; + } + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; + } + + return result; +} diff --git a/Help/guide/tutorial/Step8/TutorialConfig.h.in b/Help/guide/tutorial/Step8/TutorialConfig.h.in new file mode 100644 index 0000000..e23f521 --- /dev/null +++ b/Help/guide/tutorial/Step8/TutorialConfig.h.in @@ -0,0 +1,4 @@ +// 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 new file mode 100644 index 0000000..b3c6a4f --- /dev/null +++ b/Help/guide/tutorial/Step8/tutorial.cxx @@ -0,0 +1,36 @@ +// A simple program that computes the square root of a number +#include <cmath> +#include <iostream> +#include <string> + +#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) { + // report version + std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." + << Tutorial_VERSION_MINOR << std::endl; + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + const double inputValue = std::stod(argv[1]); + + // which square root function should we use? +#ifdef USE_MYMATH + const double outputValue = mysqrt(inputValue); +#else + const double outputValue = sqrt(inputValue); +#endif + + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; + return 0; +} diff --git a/Help/guide/tutorial/Step9/CMakeLists.txt b/Help/guide/tutorial/Step9/CMakeLists.txt new file mode 100644 index 0000000..d5f1cc8 --- /dev/null +++ b/Help/guide/tutorial/Step9/CMakeLists.txt @@ -0,0 +1,72 @@ +cmake_minimum_required(VERSION 3.10) + +# set the project name and version +project(Tutorial VERSION 1.0) + +# specify the C++ standard +set(CMAKE_CXX_STANDARD 11) +set(CMAKE_CXX_STANDARD_REQUIRED True) + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) + +# 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 the executable +add_executable(Tutorial tutorial.cxx) +target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS}) + +# add the binary tree to the search path for include files +# so that we will find TutorialConfig.h +target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + ) + +# add the install targets +install(TARGETS Tutorial DESTINATION bin) +install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" + DESTINATION include + ) + +# enable testing +include(CTest) + +# does the application run +add_test(NAME Runs COMMAND Tutorial 25) + +# does the usage message work? +add_test(NAME Usage COMMAND Tutorial) +set_tests_properties(Usage + PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number" + ) + +# define a function to simplify adding tests +function(do_test target arg result) + add_test(NAME Comp${arg} COMMAND ${target} ${arg}) + set_tests_properties(Comp${arg} + PROPERTIES PASS_REGULAR_EXPRESSION ${result} + ) +endfunction(do_test) + +# do a bunch of result based tests +do_test(Tutorial 4 "4 is 2") +do_test(Tutorial 9 "9 is 3") +do_test(Tutorial 5 "5 is 2.236") +do_test(Tutorial 7 "7 is 2.645") +do_test(Tutorial 25 "25 is 5") +do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial 0.0001 "0.0001 is 0.01") + +include(InstallRequiredSystemLibraries) +set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt") +set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}") +set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}") +include(CPack) diff --git a/Help/guide/tutorial/Step9/CTestConfig.cmake b/Help/guide/tutorial/Step9/CTestConfig.cmake new file mode 100644 index 0000000..73efdb1 --- /dev/null +++ b/Help/guide/tutorial/Step9/CTestConfig.cmake @@ -0,0 +1,7 @@ +set(CTEST_PROJECT_NAME "CMakeTutorial") +set(CTEST_NIGHTLY_START_TIME "00:00:00 EST") + +set(CTEST_DROP_METHOD "http") +set(CTEST_DROP_SITE "my.cdash.org") +set(CTEST_DROP_LOCATION "/submit.php?project=CMakeTutorial") +set(CTEST_DROP_SITE_CDASH TRUE) diff --git a/Help/guide/tutorial/Step9/License.txt b/Help/guide/tutorial/Step9/License.txt new file mode 100644 index 0000000..c62d00b --- /dev/null +++ b/Help/guide/tutorial/Step9/License.txt @@ -0,0 +1,2 @@ +This is the open source License.txt file introduced in +CMake/Tutorial/Step7... diff --git a/Help/guide/tutorial/Step9/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step9/MathFunctions/CMakeLists.txt new file mode 100644 index 0000000..50f0701 --- /dev/null +++ b/Help/guide/tutorial/Step9/MathFunctions/CMakeLists.txt @@ -0,0 +1,27 @@ +# 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 + ) + +# 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} + ) + +# install rules +install(TARGETS MathFunctions DESTINATION lib) +install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Step9/MathFunctions/MakeTable.cxx b/Help/guide/tutorial/Step9/MathFunctions/MakeTable.cxx new file mode 100644 index 0000000..ee58556 --- /dev/null +++ b/Help/guide/tutorial/Step9/MathFunctions/MakeTable.cxx @@ -0,0 +1,25 @@ +// A simple program that builds a sqrt table +#include <cmath> +#include <fstream> +#include <iostream> + +int main(int argc, char* argv[]) +{ + // make sure we have enough arguments + if (argc < 2) { + return 1; + } + + std::ofstream fout(argv[1], std::ios_base::out); + const bool fileOpen = fout.is_open(); + if (fileOpen) { + fout << "double sqrtTable[] = {" << std::endl; + for (int i = 0; i < 10; ++i) { + fout << sqrt(static_cast<double>(i)) << "," << std::endl; + } + // close the table with a zero + fout << "0};" << std::endl; + fout.close(); + } + return fileOpen ? 0 : 1; // return 0 if wrote the file +} diff --git a/Help/guide/tutorial/Step9/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step9/MathFunctions/MathFunctions.cxx new file mode 100644 index 0000000..0145300 --- /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) +{ +#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 new file mode 100644 index 0000000..cd36bcc --- /dev/null +++ b/Help/guide/tutorial/Step9/MathFunctions/MathFunctions.h @@ -0,0 +1 @@ +double mysqrt(double x); diff --git a/Help/guide/tutorial/Step9/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step9/MathFunctions/mysqrt.cxx new file mode 100644 index 0000000..7d80ee9 --- /dev/null +++ b/Help/guide/tutorial/Step9/MathFunctions/mysqrt.cxx @@ -0,0 +1,33 @@ +#include <iostream> + +#include "MathFunctions.h" + +// include the generated table +#include "Table.h" + +// a hack square root calculation using simple operations +double mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + // use the table to help find an initial value + double result = x; + if (x >= 1 && x < 10) { + std::cout << "Use the table to help find an initial value " << std::endl; + result = sqrtTable[static_cast<int>(x)]; + } + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; + } + + return result; +} diff --git a/Help/guide/tutorial/Step9/MathFunctions/mysqrt.h b/Help/guide/tutorial/Step9/MathFunctions/mysqrt.h new file mode 100644 index 0000000..e1c42ef --- /dev/null +++ b/Help/guide/tutorial/Step9/MathFunctions/mysqrt.h @@ -0,0 +1,6 @@ + +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 new file mode 100644 index 0000000..e23f521 --- /dev/null +++ b/Help/guide/tutorial/Step9/TutorialConfig.h.in @@ -0,0 +1,4 @@ +// 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 new file mode 100644 index 0000000..b3c6a4f --- /dev/null +++ b/Help/guide/tutorial/Step9/tutorial.cxx @@ -0,0 +1,36 @@ +// A simple program that computes the square root of a number +#include <cmath> +#include <iostream> +#include <string> + +#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) { + // report version + std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." + << Tutorial_VERSION_MINOR << std::endl; + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + const double inputValue = std::stod(argv[1]); + + // which square root function should we use? +#ifdef USE_MYMATH + const double outputValue = mysqrt(inputValue); +#else + const double outputValue = sqrt(inputValue); +#endif + + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; + return 0; +} diff --git a/Help/guide/tutorial/index.rst b/Help/guide/tutorial/index.rst new file mode 100644 index 0000000..d74d160 --- /dev/null +++ b/Help/guide/tutorial/index.rst @@ -0,0 +1,902 @@ +CMake Tutorial +************** + +.. only:: html + + .. contents:: + +The CMake tutorial provides a step-by-step guide that covers common build +system issues that CMake helps address. Seeing how various topics all +work together in an example project can be very helpful. The tutorial +documentation and source code for examples can be found in the +``Help/guide/tutorial`` directory of the CMake source code tree. Each step has +its own subdirectory containing code that may be used as a starting point. The +tutorial examples are progressive so that each step provides the complete +solution for the previous step. + +A Basic Starting Point (Step 1) +=============================== + +The most basic project is an executable built from source code files. +For simple projects, a three line ``CMakeLists.txt`` file is all that is +required. This will be the starting point for our tutorial. Create a +``CMakeLists.txt`` file in the ``Step1`` directory that looks like: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.10) + + # set the project name + project(Tutorial) + + # add the executable + add_executable(Tutorial tutorial.cxx) + + +Note that this example uses lower case commands in the ``CMakeLists.txt`` file. +Upper, lower, and mixed case commands are supported by CMake. The source +code for ``tutorial.cxx`` is provided in the ``Step1`` directory and can be +used to compute the square root of a number. + +Adding a Version Number and Configured Header File +-------------------------------------------------- + +The first feature we will add is to provide our executable and project with a +version number. While we could do this exclusively in the source code, using +``CMakeLists.txt`` provides more flexibility. + +First, modify the ``CMakeLists.txt`` file to set the version number. + +.. literalinclude:: Step2/CMakeLists.txt + :language: cmake + :end-before: # specify the C++ standard + +Then, configure a header file to pass the version number to the source +code: + +.. literalinclude:: Step2/CMakeLists.txt + :language: cmake + :start-after: # to the source code + :end-before: # add the executable + +Since the configured file will be written into the binary tree, we +must add that directory to the list of paths to search for include +files. Add the following lines to the end of the ``CMakeLists.txt`` file: + +.. literalinclude:: Step2/CMakeLists.txt + :language: cmake + :start-after: # so that we will find TutorialConfig.h + +Using your favorite editor, create ``TutorialConfig.h.in`` in the source +directory with the following contents: + +.. literalinclude:: Step2/TutorialConfig.h.in + :language: cmake + +When CMake configures this header file the values for +``@Tutorial_VERSION_MAJOR@`` and ``@Tutorial_VERSION_MINOR@`` will be +replaced. + +Next modify ``tutorial.cxx`` to include the configured header file, +``TutorialConfig.h``. + +Finally, let's print out the version number by updating ``tutorial.cxx`` as +follows: + +.. literalinclude:: Step2/tutorial.cxx + :language: c++ + :start-after: { + :end-before: // convert input to double + +Specify the C++ Standard +------------------------- + +Next let's add some C++11 features to our project by replacing ``atof`` with +``std::stod`` in ``tutorial.cxx``. At the same time, remove +``#include <cstdlib>``. + +.. literalinclude:: Step2/tutorial.cxx + :language: c++ + :start-after: // convert input to double + :end-before: // calculate square root + +We will need to explicitly state in the CMake code that it should use the +correct flags. The easiest way to enable support for a specific C++ standard +in CMake is by using the ``CMAKE_CXX_STANDARD`` variable. For this tutorial, +set the ``CMAKE_CXX_STANDARD`` variable in the ``CMakeLists.txt`` file to 11 +and ``CMAKE_CXX_STANDARD_REQUIRED`` to True: + +.. literalinclude:: Step2/CMakeLists.txt + :language: cmake + :end-before: # configure a header file to pass some of the CMake settings + +Build and Test +-------------- + +Run **cmake** or **cmake-gui** to configure the project and then build it +with your chosen build tool. + +For example, from the command line we could navigate to the +``Help/guide/tutorial`` directory of the CMake source code tree and run the +following commands: + +.. code-block:: console + + mkdir Step1_build + cd Step1_build + cmake ../Step1 + cmake --build . + +Navigate to the directory where Tutorial was built (likely the make directory +or a Debug or Release build configuration subdirectory) and run these commands: + +.. code-block:: console + + Tutorial 4294967296 + Tutorial 10 + Tutorial + +Adding a Library (Step 2) +========================= + +Now we will add a library to our project. This library will contain our own +implementation for computing the square root of a number. The executable can +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``. The source file has one +function called ``mysqrt`` that provides similar functionality to the +compiler's ``sqrt`` function. + +Add the following one line ``CMakeLists.txt`` file to the ``MathFunctions`` +directory: + +.. literalinclude:: Step3/MathFunctions/CMakeLists.txt + :language: cmake + +To make use of the new library we will add an ``add_subdirectory`` call in the +top-level ``CMakeLists.txt`` file so that the library will get built. We add +the new library to the executable, and add ``MathFunctions`` as an include +directory so that the ``mqsqrt.h`` header file can be found. The last few lines +of the top-level ``CMakeLists.txt`` file should now look like: + +.. code-block:: cmake + + # add the MathFunctions library + add_subdirectory(MathFunctions) + + # add the executable + add_executable(Tutorial tutorial.cxx) + + target_link_libraries(Tutorial PUBLIC MathFunctions) + + # add the binary tree to the search path for include files + # so that we will find TutorialConfig.h + target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + "${PROJECT_SOURCE_DIR}/MathFunctions" + ) + +Now let us make the MathFunctions library optional. While for the tutorial +there really isn’t any need to do so, for larger projects this is a common +occurrence. The first step is to add an option to the top-level +``CMakeLists.txt`` file. + +.. literalinclude:: Step3/CMakeLists.txt + :language: cmake + :start-after: # should we use our own math functions + :end-before: # add the MathFunctions library + +This option will be displayed in the CMake GUI and ccmake with a default +value of ON that can be changed by the user. This setting will be stored in +the cache so that the user does not need to set the value each time they run +CMake on a build directory. + +The next change is to make building and linking the MathFunctions library +conditional. To do this we change the end of the top-level ``CMakeLists.txt`` +file to look like the following: + +.. literalinclude:: Step3/CMakeLists.txt + :language: cmake + :start-after: # add the MathFunctions library + +Note the use of the variable ``EXTRA_LIBS`` to collect up any optional +libraries to later be linked into the executable. The variable +``EXTRA_INCLUDES`` is used similarly for optional header files. This is a +classic approach when dealing with many optional components, we will cover +the modern approach in the next step. + +The corresponding changes to the source code are fairly straightforward. First, +in ``tutorial.cxx``, include the ``MathFunctions.h`` header if we need it: + +.. literalinclude:: Step3/tutorial.cxx + :language: c++ + :start-after: // should we include the MathFunctions header + :end-before: int main + +Then, in the same file, make ``USE_MYMATH`` control which square root +function is used: + +.. literalinclude:: Step3/tutorial.cxx + :language: c++ + :start-after: // which square root function should we use? + :end-before: std::cout << "The square root of + +Since the source code now requires ``USE_MYMATH`` we can add it to +``TutorialConfig.h.in`` with the following line: + +.. literalinclude:: Step3/TutorialConfig.h.in + :language: c + :lines: 4 + +**Exercise**: Why is it important that we configure ``TutorialConfig.h.in`` +after the option for ``USE_MYMATH``? What would happen if we inverted the two? + +Run **cmake** or **cmake-gui** to configure the project and then build it +with your chosen build tool. Then run the built Tutorial executable. + +Use ccmake or the CMake GUI to update the value of ``USE_MYMATH``. Rebuild and +run the tutorial again. Which function gives better results, sqrt or mysqrt? + +Adding Usage Requirements for Library (Step 3) +============================================== + +Usage requirements allow for far better control over a library or executable's +link and include line while also giving more control over the transitive +property of targets inside CMake. The primary commands that leverage usage +requirements are: + + - ``target_compile_definitions`` + - ``target_compile_options`` + - ``target_include_directories`` + - ``target_link_libraries`` + +Let's refactor our code from `Adding a Library (Step 2)`_ to use the modern +CMake approach of usage requirements. We first state that anybody linking to +MathFunctions needs to include the current source directory, while +MathFunctions itself doesn't. So this can become an ``INTERFACE`` usage +requirement. + +Remember ``INTERFACE`` means things that consumers require but the producer +doesn't. Add the following lines to the end of ``MathFunctions/CMakeLists.txt``: + +.. literalinclude:: Step4/MathFunctions/CMakeLists.txt + :language: cmake + :start-after: # to find MathFunctions.h + +Now that we've specified usage requirements for MathFunctions we can safely +remove our uses of the ``EXTRA_INCLUDES`` variable from the top-level +``CMakeLists.txt``, here: + +.. literalinclude:: Step4/CMakeLists.txt + :language: cmake + :start-after: # add the MathFunctions library + :end-before: # add the executable + +And here: + +.. literalinclude:: Step4/CMakeLists.txt + :language: cmake + :start-after: # so that we will find TutorialConfig.h + +Once this is done, run **cmake** or **cmake-gui** to configure the project +and then build it with your chosen build tool or by using ``cmake --build .`` +from the build directory. + +Installing and Testing (Step 4) +=============================== + +Now we can start adding install rules and testing support to our project. + +Install Rules +------------- + +The install rules are fairly simple: for MathFunctions we want to install the +library and header file and for the application we want to install the +executable and configured header. + +So to the end of ``MathFunctions/CMakeLists.txt`` we add: + +.. literalinclude:: Step5/MathFunctions/CMakeLists.txt + :language: cmake + :start-after: # install rules + +And to the end of the top-level ``CMakeLists.txt`` we add: + +.. literalinclude:: Step5/CMakeLists.txt + :language: cmake + :start-after: # add the install targets + :end-before: # enable testing + +That is all that is needed to create a basic local install of the tutorial. + +Run **cmake** or **cmake-gui** to configure the project and then build it +with your chosen build tool. Run the install step by typing +``cmake --install .`` (introduced in 3.15, older versions of CMake must use +``make install``) from the command line, or build the ``INSTALL`` target from +an IDE. This will install the appropriate header files, libraries, and +executables. + +The CMake variable ``CMAKE_INSTALL_PREFIX`` is used to determine the root of +where the files will be installed. If using ``cmake --install`` a custom +installation directory can be given via ``--prefix`` argument. For +multi-configuration tools, use the ``--config`` argument to specify the +configuration. + +Verify that the installed Tutorial runs. + +Testing Support +--------------- + +Next let's test our application. At the end of the top-level ``CMakeLists.txt`` +file we can enable testing and then add a number of basic tests to verify that +the application is working correctly. + +.. literalinclude:: Step5/CMakeLists.txt + :language: cmake + :start-after: # enable testing + +The first test simply verifies that the application runs, does not segfault or +otherwise crash, and has a zero return value. This is the basic form of a CTest +test. + +The next test makes use of the ``PASS_REGULAR_EXPRESSION`` test property to +verify that the output of the test contains certain strings. In this case, +verifying that the usage message is printed when an incorrect number of +arguments are provided. + +Lastly, we have a function called ``do_test`` that runs the application and +verifies that the computed square root is correct for given input. For each +invocation of ``do_test``, another test is added to the project with a name, +input, and expected results based on the passed arguments. + +Rebuild the application and then cd to the binary directory and run +``ctest -N`` and ``ctest -VV``. For multi-config generators (e.g. Visual +Studio), the configuration type must be specified. To run tests in Debug mode, +for example, use ``ctest -C Debug -VV`` from the build directory (not the +Debug subdirectory!). Alternatively, build the ``RUN_TESTS`` target from the +IDE. + +Adding System Introspection (Step 5) +==================================== + +Let us consider adding some code to our project that depends on features the +target platform may not have. For this example, we will add some code that +depends on whether or not the target platform has the ``log`` and ``exp`` +functions. Of course almost every platform has these functions but for this +tutorial assume that they are not common. + +If the platform has ``log`` and ``exp`` then we will use them to compute the +square root in the ``mysqrt`` function. We first test for the availability of +these functions using the ``CheckSymbolExists`` module in the top-level +``CMakeLists.txt``. We're going to use the new defines in +``TutorialConfig.h.in``, so be sure to set them before that file is configured. + +.. literalinclude:: Step6/MathFunctions/CMakeLists.txt + :language: cmake + :start-after: # does this system provide the log and exp functions? + :end-before: if(HAVE_LOG AND HAVE_EXP) + +Now let's add these defines to ``TutorialConfig.h.in`` so that we can use them +from ``mysqrt.cxx``: + +.. code-block:: console + + // does the platform provide exp and log functions? + #cmakedefine HAVE_LOG + #cmakedefine HAVE_EXP + +Modify ``mysqrt.cxx`` to include cmath. Next, in that same file in the +``mysqrt`` function we can provide an alternate implementation based on +``log`` and ``exp`` if they are available on the system using the following +code (don't forget the ``#endif`` before returning the result!): + +.. literalinclude:: Step6/MathFunctions/mysqrt.cxx + :language: c++ + :start-after: // if we have both log and exp then use them + :end-before: // do ten iterations + +Run **cmake** or **cmake-gui** to configure the project and then build it +with your chosen build tool and run the Tutorial executable. + +You will notice that we're not using ``log`` and ``exp``, even if we think they +should be available. We should realize quickly that we have forgotten to include +``TutorialConfig.h`` in ``mysqrt.cxx``. + +We will also need to update ``MathFunctions/CMakeLists.txt`` so ``mysqrt.cxx`` +knows where this file is located: + +.. code-block:: cmake + + target_include_directories(MathFunctions + INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} + PRIVATE ${CMAKE_BINARY_DIR} + ) + +After making this update, go ahead and build the project again and run the built +Tutorial executable. If ``log`` and ``exp`` are still not being used, open the +generated ``TutorialConfig.h`` file from the build directory. Maybe they aren't +available on the current system? + +Which function gives better results now, sqrt or mysqrt? + +Specify Compile Definition +-------------------------- + +Is there a better place for us to save the ``HAVE_LOG`` and ``HAVE_EXP`` values +other than in ``TutorialConfig.h``? Let's try to use +``target_compile_definitions``. + +First, remove the defines from ``TutorialConfig.h.in``. We no longer need to +include ``TutorialConfig.h`` from ``mysqrt.cxx`` or the extra include in +``MathFunctions/CMakeLists.txt``. + +Next, we can move the check for ``HAVE_LOG`` and ``HAVE_EXP`` to +``MathFunctions/CMakeLists.txt`` and then specify those values as ``PRIVATE`` +compile definitions. + +.. literalinclude:: Step6/MathFunctions/CMakeLists.txt + :language: cmake + :start-after: # does this system provide the log and exp functions? + :end-before: # install rules + +After making these updates, go ahead and build the project again. Run the +built Tutorial executable and verify that the results are same as earlier in +this step. + +Adding a Custom Command and Generated File (Step 6) +=================================================== + +Suppose, for the purpose of this tutorial, we decide that we never want to use +the platform ``log`` and ``exp`` functions and instead would like to +generate a table of precomputed values to use in the ``mysqrt`` function. +In this section, we will create the table as part of the build process, +and then compile that table into our application. + +First, let's remove the check for the ``log`` and ``exp`` functions in +``MathFunctions/CMakeLists.txt``. Then remove the check for ``HAVE_LOG`` and +``HAVE_EXP`` from ``mysqrt.cxx``. At the same time, we can remove +:code:`#include <cmath>`. + +In the ``MathFunctions`` subdirectory, a new source file named ``MakeTable.cxx`` +has been provided to generate the table. + +After reviewing the file, we can see that the table is produced as valid C++ +code and that the output filename is passed in as an argument. + +The next step is to add the appropriate commands to the +``MathFunctions/CMakeLists.txt`` file to build the MakeTable executable and +then run it as part of the build process. A few commands are needed to +accomplish this. + +First, at the top of ``MathFunctions/CMakeLists.txt``, the executable for +``MakeTable`` is added as any other executable would be added. + +.. literalinclude:: Step7/MathFunctions/CMakeLists.txt + :language: cmake + :start-after: # first we add the executable that generates the table + :end-before: # add the command to generate the source code + +Then we add a custom command that specifies how to produce ``Table.h`` +by running MakeTable. + +.. literalinclude:: Step7/MathFunctions/CMakeLists.txt + :language: cmake + :start-after: # add the command to generate the source code + :end-before: # add the main library + +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 +of sources for the library MathFunctions. + +.. literalinclude:: Step7/MathFunctions/CMakeLists.txt + :language: cmake + :start-after: # add the main library + :end-before: # state that anybody linking + +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``. + +.. literalinclude:: Step7/MathFunctions/CMakeLists.txt + :start-after: # state that we depend on our bin + :end-before: # install rules + +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: + +.. literalinclude:: Step7/MathFunctions/mysqrt.cxx + :language: c++ + :start-after: // a hack square root calculation using simple operations + +Run **cmake** or **cmake-gui** to configure the project and then build it +with your chosen build tool. + +When this project is built it will first build the ``MakeTable`` executable. +It will then run ``MakeTable`` to produce ``Table.h``. Finally, it will +compile ``mysqrt.cxx`` which includes ``Table.h`` to produce the MathFunctions +library. + +Run the Tutorial executable and verify that it is using the table. + +Building an Installer (Step 7) +============================== + +Next suppose that we want to distribute our project to other people so that +they can use it. We want to provide both binary and source distributions on a +variety of platforms. This is a little different from the install we did +previously in `Installing and Testing (Step 4)`_ , where we were +installing the binaries that we had built from the source code. In this +example we will be building installation packages that support binary +installations and package management features. To accomplish this we will use +CPack to create platform specific installers. Specifically we need to add +a few lines to the bottom of our top-level ``CMakeLists.txt`` file. + +.. literalinclude:: Step8/CMakeLists.txt + :language: cmake + :start-after: # setup installer + +That is all there is to it. We start by including +``InstallRequiredSystemLibraries``. This module will include any runtime +libraries that are needed by the project for the current platform. Next we +set some CPack variables to where we have stored the license and version +information for this project. The version information was set earlier in this +tutorial and the ``license.txt`` has been included in the top-level source +directory for this step. + +Finally we include the CPack module which will use these variables and some +other properties of the current system to setup an installer. + +The next step is to build the project in the usual manner and then run +CPack on it. To build a binary distribution, from the binary directory run: + +.. code-block:: console + + cpack + +To specify the generator, use the ``-G`` option. For multi-config builds, use +``-C`` to specify the configuration. For example: + +.. code-block:: console + + cpack -G ZIP -C Debug + +To create a source distribution you would type: + +.. code-block:: console + + cpack --config CPackSourceConfig.cmake + +Alternatively, run ``make package`` or right click the ``Package`` target and +``Build Project`` from an IDE. + +Run the installer found in the binary directory. Then run the +installed executable and verify that it works. + +Adding Support for a Dashboard (Step 8) +======================================= + +Adding support for submitting our test results to a dashboard is very easy. We +already defined a number of tests for our project in `Testing Support`_. Now we +just have to run those tests and submit them to a dashboard. To include support +for dashboards we include the CTest module in our top-level ``CMakeLists.txt``. + +Replace: + +.. code-block:: cmake + + # enable testing + enable_testing() + +With: + +.. code-block:: cmake + + # enable dashboard scripting + include(CTest) + +The CTest module will automatically call ``enable_testing()``, so +we can remove it from our CMake files. + +We will also need to create a ``CTestConfig.cmake`` file in the top-level +directory where we can specify the name of the project and where to submit the +dashboard. + +.. literalinclude:: Step9/CTestConfig.cmake + :language: cmake + +CTest will read in this file when it runs. To create a simple dashboard you can +run **cmake** or **cmake-gui** to configure the project, but do not build it +yet. Instead, change directory to the binary tree, and then run:: + + ctest [-VV] -D Experimental + +Remember, for multi-config generators (e.g. Visual Studio), the configuration +type must be specified:: + + ctest [-VV] -C Debug -D Experimental + +Or, from an IDE, build the ``Experimental`` target. + +``ctest`` will build and test the project and submit the results to the Kitware +public dashboard. The results of your dashboard will be uploaded to Kitware's +public dashboard here: https://my.cdash.org/index.php?project=CMakeTutorial. + +Mixing Static and Shared (Step 9) +================================= + +In this section we will show how by using the ``BUILD_SHARED_LIBS`` variable +we can control the default behavior of ``add_library``, and allow control +over how libraries without an explicit type (``STATIC``, ``SHARED``, ``MODULE`` +or ``OBJECT``) are built. + +To accomplish this we need to add ``BUILD_SHARED_LIBS`` to the top-level +``CMakeLists.txt``. We use the ``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 MathFuctions, 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:: Step10/CMakeLists.txt + :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 when ``USE_MYMATH`` is +enabled. Now, since this is a tutorial, we are going to explicitly require +that SqrtLibrary is built statically. + +The end result is that ``MathFunctions/CMakeLists.txt`` should look like: + +.. literalinclude:: Step10/MathFunctions/CMakeLists.txt + :language: cmake + :lines: 1-36,42- + +Next, update ``MathFunctions/mysqrt.cxx`` to use the ``mathfunctions`` and +``detail`` namespaces: + +.. literalinclude:: Step10/MathFunctions/mysqrt.cxx + :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 + +Finally, update ``MathFunctions/MathFunctions.h`` to use dll export defines: + +.. literalinclude:: Step10/MathFunctions/MathFunctions.h + :language: c++ + +At this point, if you build everything, you will notice that linking fails +as we are combining a static library without position independent code with a +library that has position independent code. The solution to this is to +explicitly set the ``POSITION_INDEPENDENT_CODE`` target property of SqrtLibrary +to be True no matter the build type. + +.. literalinclude:: Step10/MathFunctions/CMakeLists.txt + :language: cmake + :lines: 37-42 + +**Exercise**: We modified ``MathFunctions.h`` to use dll export defines. +Using CMake documentation can you find a helper module to simplify this? + + +Adding Generator Expressions (Step 10) +====================================== + +Generator expressions are evaluated during build system generation to produce +information specific to each build configuration. + +Generator expressions are allowed in the context of many target properties, +such as ``LINK_LIBRARIES``, ``INCLUDE_DIRECTORIES``, ``COMPILE_DEFINITIONS`` +and others. They may also be used when using commands to populate those +properties, such as ``target_link_libraries()``, +``target_include_directories()``, +``target_compile_definitions()`` and others. + +Generator expressions may be used to enable conditional linking, conditional +definitions used when compiling, conditional include directories and more. +The conditions may be based on the build configuration, target properties, +platform information or any other queryable information. + +There are different types of generator expressions including Logical, +Informational, and Output expressions. + +Logical expressions are used to create conditional output. The basic +expressions are the 0 and 1 expressions. A ``$<0:...>`` results in the empty +string, and ``<1:...>`` results in the content of "...". They can also be +nested. + +A common usage of generator expressions is to conditionally add compiler +flags, such as those for language levels or warnings. A nice pattern is +to associate this information to an ``INTERFACE`` target allowing this +information to propagate. Lets start by constructing an ``INTERFACE`` +target and specifying the required C++ standard level of ``11`` instead +of using ``CMAKE_CXX_STANDARD``. + +So the following code: + +.. literalinclude:: Step10/CMakeLists.txt + :language: cmake + :start-after: project(Tutorial VERSION 1.0) + :end-before: # control where the static and shared libraries are built so that on windows + +Would be replaced with: + +.. literalinclude:: Step11/CMakeLists.txt + :language: cmake + :start-after: project(Tutorial VERSION 1.0) + :end-before: # add compiler warning flags just when building this project via + + +Next we add the desired compiler warning flags that we want for our +project. As warning flags vary based on the compiler we use +the ``COMPILE_LANG_AND_ID`` generator expression to control which +flags to apply given a language and a set of compiler ids as seen +below: + +.. literalinclude:: Step11/CMakeLists.txt + :language: cmake + :start-after: # the BUILD_INTERFACE genex + :end-before: # control where the static and shared libraries are built so that on windows + +Looking at this we see that the warning flags are encapsulated inside a +``BUILD_INTERFACE`` condition. This is done so that consumers of our installed +project will not inherit our warning flags. + + +**Exercise**: Modify ``MathFunctions/CMakeLists.txt`` so that +all targets have a ``target_link_libraries()`` call to ``tutorial_compiler_flags``. + + +Adding Export Configuration (Step 11) +===================================== + +During `Installing and Testing (Step 4)`_ of the tutorial we added the ability +for CMake to install the library and headers of the project. During +`Building an Installer (Step 7)`_ we added the ability to package up this +information so it could be distributed to other people. + +The next step is to add the necessary information so that other CMake projects +can use our project, be it from a build directory, a local install or when +packaged. + +The first step is to update our ``install(TARGETS)`` commands to not only +specify a ``DESTINATION`` but also an ``EXPORT``. The ``EXPORT`` keyword +generates and installs a CMake file containing code to import all targets +listed in the install command from the installation tree. So let's go ahead +and explicitly ``EXPORT`` the MathFunctions library by updating the +``install`` command in ``MathFunctions/CMakeLists.txt`` to look like: + +.. literalinclude:: Complete/MathFunctions/CMakeLists.txt + :language: cmake + :start-after: # install rules + +Now that we have MathFunctions being exported, we also need to explicitly +install the generated ``MathFunctionsTargets.cmake`` file. This is done by +adding the following to the bottom of the top-level ``CMakeLists.txt``: + +.. literalinclude:: Complete/CMakeLists.txt + :language: cmake + :start-after: # install the configuration targets + :end-before: include(CMakePackageConfigHelpers) + +At this point you should try and run CMake. If everything is setup properly +you will see that CMake will generate an error that looks like: + +.. code-block:: console + + Target "MathFunctions" INTERFACE_INCLUDE_DIRECTORIES property contains + path: + + "/Users/robert/Documents/CMakeClass/Tutorial/Step11/MathFunctions" + + which is prefixed in the source directory. + +What CMake is trying to say is that during generating the export information +it will export a path that is intrinsically tied to the current machine and +will not be valid on other machines. The solution to this is to update the +MathFunctions ``target_include_directories`` to understand that it needs +different ``INTERFACE`` locations when being used from within the build +directory and from an install / package. This means converting the +``target_include_directories`` call for MathFunctions to look like: + +.. literalinclude:: Complete/MathFunctions/CMakeLists.txt + :language: cmake + :start-after: # to find MathFunctions.h, while we don't. + :end-before: # should we use our own math functions + +Once this has been updated, we can re-run CMake and verify that it doesn't +warn anymore. + +At this point, we have CMake properly packaging the target information that is +required but we will still need to generate a ``MathFunctionsConfig.cmake`` so +that the CMake ``find_package`` command can find our project. So let's go +ahead and add a new file to the top-level of the project called +``Config.cmake.in`` with the following contents: + +.. literalinclude:: Complete/Config.cmake.in + +Then, to properly configure and install that file, add the following to the +bottom of the top-level ``CMakeLists.txt``: + +.. literalinclude:: Complete/CMakeLists.txt + :language: cmake + :start-after: # install the configuration targets + :end-before: # generate the export + +At this point, we have generated a relocatable CMake Configuration for our +project that can be used after the project has been installed or packaged. If +we want our project to also be used from a build directory we only have to add +the following to the bottom of the top level ``CMakeLists.txt``: + +.. literalinclude:: Complete/CMakeLists.txt + :language: cmake + :start-after: # needs to be after the install(TARGETS ) command + +With this export call we now generate a ``Targets.cmake``, allowing the +configured ``MathFunctionsConfig.cmake`` in the build directory to be used by +other projects, without needing it to be installed. + +Import a CMake Project (Consumer) +================================= + +This example shows how a project can find other CMake packages that +generate ``Config.cmake`` files. + +It also shows how to state a project's external dependencies when generating +a ``Config.cmake``. + +Packaging Debug and Release (MultiPackage) +========================================== + +By default CMake's model is that a build directory only contains a single +configuration, be it Debug, Release, MinSizeRel, or RelWithDebInfo. + +But it is possible to setup CPack to bundle multiple build directories at the +same time to build a package that contains multiple configurations of the +same project. + +First we need to construct a directory called ``multi_config``, which +will contain all the builds that we want to package together. + +Second create a ``debug`` and ``release`` directory underneath +``multi_config``. At the end you should have a layout that looks like: + +.. code-block:: none + + ─ multi_config + ├── debug + └── release + +Now we need to setup debug and release builds, which would roughly entail +the following: + +.. code-block:: console + + cd debug + cmake -DCMAKE_BUILD_TYPE=Debug ../../MultiPackage/ + cmake --build . + cd ../release + cmake -DCMAKE_BUILD_TYPE=Release ../../MultiPackage/ + cmake --build . + cd .. + + +Now that both the debug and release builds are complete, we can use +a custom ``MultiCPackConfig.cmake`` file to package both builds into a single +release. + +.. code-block:: console + + cpack --config ../../MultiPackage/MultiCPackConfig.cmake diff --git a/Help/index.rst b/Help/index.rst index a948939..cc6cee6 100644 --- a/Help/index.rst +++ b/Help/index.rst @@ -44,6 +44,16 @@ Reference Manuals /manual/cmake-variables.7 /manual/cpack-generators.7 +.. only:: not man + + Guides + ###### + + .. toctree:: + :maxdepth: 1 + + /guide/tutorial/index + .. only:: html or text Release Notes diff --git a/Help/manual/LINKS.txt b/Help/manual/LINKS.txt index 60a260c..810fa0b 100644 --- a/Help/manual/LINKS.txt +++ b/Help/manual/LINKS.txt @@ -11,11 +11,7 @@ Online Documentation and Community Resources Links to available documentation and community resources may be found on this web page. -Mailing List - https://cmake.org/mailing-lists +Discourse Forum + https://discourse.cmake.org - For help and discussion about using CMake, a mailing list is - provided at cmake@cmake.org. The list is member-post-only but one - may sign up on the CMake web page. Please first read the full - documentation at https://cmake.org before posting questions to - the list. + The Discourse Forum hosts discussion and questions about CMake. diff --git a/Help/manual/OPTIONS_BUILD.txt b/Help/manual/OPTIONS_BUILD.txt index 810aaa9..0947e41 100644 --- a/Help/manual/OPTIONS_BUILD.txt +++ b/Help/manual/OPTIONS_BUILD.txt @@ -18,6 +18,9 @@ containing :command:`set` commands that use the ``CACHE`` option, not a cache-format file. + References to :variable:`CMAKE_SOURCE_DIR` and :variable:`CMAKE_BINARY_DIR` + within the script evaluate to the top-level source and build tree. + ``-D <var>:<type>=<value>, -D <var>=<value>`` Create or update a CMake ``CACHE`` entry. diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index 8cd6e68..d8142a2 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -811,6 +811,10 @@ An *archive* output artifact of a buildsystem target may be: executable target created by the :command:`add_executable` command when its :prop_tgt:`ENABLE_EXPORTS` target property is set. +* On AIX: the linker import file (e.g. ``.imp``) of an executable target + created by the :command:`add_executable` command 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-commands.7.rst b/Help/manual/cmake-commands.7.rst index a3bc465..59ba897 100644 --- a/Help/manual/cmake-commands.7.rst +++ b/Help/manual/cmake-commands.7.rst @@ -112,6 +112,7 @@ These commands are available only in CMake projects. /command/target_link_directories /command/target_link_libraries /command/target_link_options + /command/target_precompile_headers /command/target_sources /command/try_compile /command/try_run diff --git a/Help/manual/cmake-compile-features.7.rst b/Help/manual/cmake-compile-features.7.rst index 658694a..a14e322 100644 --- a/Help/manual/cmake-compile-features.7.rst +++ b/Help/manual/cmake-compile-features.7.rst @@ -28,10 +28,15 @@ CMake knows are known to the compiler, regardless of language standard or compile flags needed to use them. Features known to CMake are named mostly following the same convention -as the Clang feature test macros. The are some exceptions, such as +as the Clang feature test macros. There are some exceptions, such as CMake using ``cxx_final`` and ``cxx_override`` instead of the single ``cxx_override_control`` used by Clang. +Note that there are no separate compile features properties or variables for +the ``OBJC`` or ``OBJCXX`` languages. These are based off ``C`` or ``C++`` +respectively, so the properties and variables for their corresponding base +language should be used instead. + Compile Feature Requirements ============================ @@ -90,21 +95,21 @@ Requiring Language Standards In projects that use a large number of commonly available features from a particular language standard (e.g. C++ 11) one may specify a meta-feature (e.g. ``cxx_std_11``) that requires use of a compiler mode -aware of that standard. This is simpler than specifying all the -features individually, but does not guarantee the existence of any -particular feature. Diagnosis of use of unsupported features will be -delayed until compile time. +that is at minimum aware of that standard, but could be greater. +This is simpler than specifying all the features individually, but does +not guarantee the existence of any particular feature. +Diagnosis of use of unsupported features will be delayed until compile time. For example, if C++ 11 features are used extensively in a project's -header files, then clients must use a compiler mode aware of C++ 11 -or above. This can be requested with the code: +header files, then clients must use a compiler mode that is no less +than C++ 11. This can be requested with the code: .. code-block:: cmake target_compile_features(mylib PUBLIC cxx_std_11) In this example, CMake will ensure the compiler is invoked in a mode -that is aware of C++ 11 (or above), adding flags such as +of at-least C++ 11 (or C++ 14, C++ 17, ...), adding flags such as ``-std=gnu++11`` if necessary. This applies to sources within ``mylib`` as well as any dependents (that may include headers from ``mylib``). @@ -331,12 +336,12 @@ and :prop_gbl:`compile features <CMAKE_CXX_KNOWN_FEATURES>` available from the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the versions specified for each: -* ``AppleClang``: Apple Clang for Xcode versions 4.4 though 9.2. -* ``Clang``: Clang compiler versions 2.9 through 6.0. -* ``GNU``: GNU compiler versions 4.4 through 8.0. -* ``MSVC``: Microsoft Visual Studio versions 2010 through 2017. -* ``SunPro``: Oracle SolarisStudio versions 12.4 through 12.6. -* ``Intel``: Intel compiler versions 12.1 through 17.0. +* ``AppleClang``: Apple Clang for Xcode versions 4.4+. +* ``Clang``: Clang compiler versions 2.9+. +* ``GNU``: GNU compiler versions 4.4+. +* ``MSVC``: Microsoft Visual Studio versions 2010+. +* ``SunPro``: Oracle SolarisStudio versions 12.4+. +* ``Intel``: Intel compiler versions 12.1+. CMake is currently aware of the :prop_tgt:`C standards <C_STANDARD>` and :prop_gbl:`compile features <CMAKE_C_KNOWN_FEATURES>` available from @@ -344,16 +349,16 @@ the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the versions specified for each: * all compilers and versions listed above for C++. -* ``GNU``: GNU compiler versions 3.4 through 8.0. +* ``GNU``: GNU compiler versions 3.4+ CMake is currently aware of the :prop_tgt:`C++ standards <CXX_STANDARD>` and their associated meta-features (e.g. ``cxx_std_11``) available from the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the versions specified for each: -* ``Cray``: Cray Compiler Environment version 8.1 through 8.5.8. -* ``PGI``: PGI version 12.10 through 17.5. -* ``XL``: IBM XL version 10.1 through 13.1.5. +* ``Cray``: Cray Compiler Environment version 8.1+. +* ``PGI``: PGI version 12.10+. +* ``XL``: IBM XL version 10.1+. CMake is currently aware of the :prop_tgt:`C standards <C_STANDARD>` and their associated meta-features (e.g. ``c_std_99``) available from the @@ -367,4 +372,4 @@ CMake is currently aware of the :prop_tgt:`CUDA standards <CUDA_STANDARD>` from the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the versions specified for each: -* ``NVIDIA``: NVIDIA nvcc compiler 7.5 though 9.1. +* ``NVIDIA``: NVIDIA nvcc compiler 7.5+. diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index e970379..75f4bd4 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -47,8 +47,8 @@ Logical Operators ----------------- ``$<BOOL:string>`` - Converts ``string`` to ``0`` or ``1`` according to the rules of the - :command:`if()` command. Evaluates to ``0`` if any of the following is true: + Converts ``string`` to ``0`` or ``1``. Evaluates to ``0`` if any of the + following is true: * ``string`` is empty, * ``string`` is a case-insensitive equal of @@ -130,6 +130,16 @@ Variable Queries ``1`` if the CMake's compiler id of the CUDA compiler matches any one of the entries in ``compiler_ids``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<OBJC_COMPILER_ID:compiler_ids>`` + where ``compiler_ids`` is a comma-separated list. + ``1`` if the CMake's compiler id of the Objective-C compiler matches any one + of the entries in ``compiler_ids``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<OBJCXX_COMPILER_ID:compiler_ids>`` + where ``compiler_ids`` is a comma-separated list. + ``1`` if the CMake's compiler id of the Objective-C++ compiler matches any one + of the entries in ``compiler_ids``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. ``$<Fortran_COMPILER_ID:compiler_ids>`` where ``compiler_ids`` is a comma-separated list. ``1`` if the CMake's compiler id of the Fortran compiler matches any one @@ -144,6 +154,12 @@ Variable Queries ``$<CUDA_COMPILER_VERSION:version>`` ``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<OBJC_COMPILER_VERSION:version>`` + ``1`` if the version of the OBJC compiler matches ``version``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<OBJCXX_COMPILER_VERSION:version>`` + ``1`` if the version of the OBJCXX compiler matches ``version``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. ``$<Fortran_COMPILER_VERSION:version>`` ``1`` if the version of the Fortran compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. @@ -401,6 +417,12 @@ Variable Queries ``$<CUDA_COMPILER_ID>`` The CMake's compiler id of the CUDA compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<OBJC_COMPILER_ID>`` + The CMake's compiler id of the OBJC compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<OBJCXX_COMPILER_ID>`` + The CMake's compiler id of the OBJCXX compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. ``$<Fortran_COMPILER_ID>`` The CMake's compiler id of the Fortran compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. @@ -413,6 +435,12 @@ Variable Queries ``$<CUDA_COMPILER_VERSION>`` The version of the CUDA compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<OBJC_COMPILER_VERSION>`` + The version of the OBJC compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<OBJCXX_COMPILER_VERSION>`` + The version of the OBJCXX compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. ``$<Fortran_COMPILER_VERSION>`` The version of the Fortran compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index fc4bfdc..c60dc40 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -36,6 +36,12 @@ These modules are loaded using the :command:`include` command. /module/CheckIncludeFiles /module/CheckLanguage /module/CheckLibraryExists + /module/CheckOBJCCompilerFlag + /module/CheckOBJCSourceCompiles + /module/CheckOBJCSourceRuns + /module/CheckOBJCXXCompilerFlag + /module/CheckOBJCXXSourceCompiles + /module/CheckOBJCXXSourceRuns /module/CheckPIESupported /module/CheckPrototypeDefinition /module/CheckStructHasMember diff --git a/Help/manual/cmake-packages.7.rst b/Help/manual/cmake-packages.7.rst index f5aa42d..4b2934a 100644 --- a/Help/manual/cmake-packages.7.rst +++ b/Help/manual/cmake-packages.7.rst @@ -654,8 +654,13 @@ allows one to disable them using the following variables: :command:`export(PACKAGE)` populates the user package registry unless the :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` variable explicitly disables it. -* :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` disables the - User Package Registry in all the :command:`find_package` calls. +* :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` disables the + User Package Registry in all the :command:`find_package` calls when + set to ``FALSE``. +* Deprecated :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` disables the + User Package Registry in all the :command:`find_package` calls when set + to ``TRUE``. This variable is ignored when + :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` has been set. * :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` disables the System Package Registry in all the :command:`find_package` calls. diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 1d023cb..44ea1a8 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -51,6 +51,16 @@ 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.16 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0097: ExternalProject_Add with GIT_SUBMODULES "" initializes no submodules. </policy/CMP0097> + CMP0096: project() preserves leading zeros in version components. </policy/CMP0096> + CMP0095: RPATH entries are properly escaped in the intermediary CMake install script. </policy/CMP0095> + Policies Introduced by CMake 3.15 ================================= diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 77b1ae8..e704371 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -134,6 +134,7 @@ Properties on Targets /prop_tgt/AUTOMOC_EXECUTABLE /prop_tgt/AUTOMOC_MACRO_NAMES /prop_tgt/AUTOMOC_MOC_OPTIONS + /prop_tgt/AUTOMOC_PATH_PREFIX /prop_tgt/AUTOMOC /prop_tgt/AUTOUIC /prop_tgt/AUTOUIC_EXECUTABLE @@ -181,6 +182,7 @@ Properties on Targets /prop_tgt/DEFINE_SYMBOL /prop_tgt/DEPLOYMENT_REMOTE_DIRECTORY /prop_tgt/DEPLOYMENT_ADDITIONAL_FILES + /prop_tgt/DISABLE_PRECOMPILE_HEADERS /prop_tgt/DOTNET_TARGET_FRAMEWORK_VERSION /prop_tgt/EchoString /prop_tgt/ENABLE_EXPORTS @@ -228,6 +230,7 @@ Properties on Targets /prop_tgt/IMPORT_SUFFIX /prop_tgt/INCLUDE_DIRECTORIES /prop_tgt/INSTALL_NAME_DIR + /prop_tgt/INSTALL_REMOVE_ENVIRONMENT_RPATH /prop_tgt/INSTALL_RPATH /prop_tgt/INSTALL_RPATH_USE_LINK_PATH /prop_tgt/INTERFACE_AUTOUIC_OPTIONS @@ -239,6 +242,7 @@ Properties on Targets /prop_tgt/INTERFACE_LINK_DIRECTORIES /prop_tgt/INTERFACE_LINK_LIBRARIES /prop_tgt/INTERFACE_LINK_OPTIONS + /prop_tgt/INTERFACE_PRECOMPILE_HEADERS /prop_tgt/INTERFACE_POSITION_INDEPENDENT_CODE /prop_tgt/INTERFACE_SOURCES /prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES @@ -285,6 +289,12 @@ Properties on Targets /prop_tgt/NAME /prop_tgt/NO_SONAME /prop_tgt/NO_SYSTEM_FROM_IMPORTED + /prop_tgt/OBJC_EXTENSIONS + /prop_tgt/OBJC_STANDARD + /prop_tgt/OBJC_STANDARD_REQUIRED + /prop_tgt/OBJCXX_EXTENSIONS + /prop_tgt/OBJCXX_STANDARD + /prop_tgt/OBJCXX_STANDARD_REQUIRED /prop_tgt/OSX_ARCHITECTURES_CONFIG /prop_tgt/OSX_ARCHITECTURES /prop_tgt/OUTPUT_NAME_CONFIG @@ -294,6 +304,8 @@ Properties on Targets /prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG /prop_tgt/PDB_OUTPUT_DIRECTORY /prop_tgt/POSITION_INDEPENDENT_CODE + /prop_tgt/PRECOMPILE_HEADERS + /prop_tgt/PRECOMPILE_HEADERS_REUSE_FROM /prop_tgt/PREFIX /prop_tgt/PRIVATE_HEADER /prop_tgt/PROJECT_LABEL @@ -315,9 +327,14 @@ Properties on Targets /prop_tgt/STATIC_LIBRARY_OPTIONS /prop_tgt/SUFFIX /prop_tgt/Swift_DEPENDENCIES_FILE + /prop_tgt/Swift_LANGUAGE_VERSION /prop_tgt/Swift_MODULE_DIRECTORY /prop_tgt/Swift_MODULE_NAME /prop_tgt/TYPE + /prop_tgt/UNITY_BUILD + /prop_tgt/UNITY_BUILD_BATCH_SIZE + /prop_tgt/UNITY_BUILD_CODE_AFTER_INCLUDE + /prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE /prop_tgt/VERSION /prop_tgt/VISIBILITY_INLINES_HIDDEN /prop_tgt/VS_CONFIGURATION_TYPE @@ -331,6 +348,7 @@ Properties on Targets /prop_tgt/VS_DOTNET_REFERENCES /prop_tgt/VS_DOTNET_REFERENCES_COPY_LOCAL /prop_tgt/VS_DOTNET_TARGET_FRAMEWORK_VERSION + /prop_tgt/VS_DPI_AWARE /prop_tgt/VS_GLOBAL_KEYWORD /prop_tgt/VS_GLOBAL_PROJECT_TYPES /prop_tgt/VS_GLOBAL_ROOTNAMESPACE @@ -363,6 +381,7 @@ Properties on Targets /prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN /prop_tgt/XCODE_SCHEME_ARGUMENTS /prop_tgt/XCODE_SCHEME_DEBUG_AS_ROOT + /prop_tgt/XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING /prop_tgt/XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER /prop_tgt/XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS /prop_tgt/XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE @@ -404,8 +423,10 @@ Properties on Tests /prop_test/PROCESSOR_AFFINITY /prop_test/PROCESSORS /prop_test/REQUIRED_FILES + /prop_test/RESOURCE_GROUPS /prop_test/RESOURCE_LOCK /prop_test/RUN_SERIAL + /prop_test/SKIP_REGULAR_EXPRESSION /prop_test/SKIP_RETURN_CODE /prop_test/TIMEOUT /prop_test/TIMEOUT_AFTER_MATCH @@ -442,6 +463,8 @@ Properties on Source Files /prop_sf/SKIP_AUTOMOC /prop_sf/SKIP_AUTORCC /prop_sf/SKIP_AUTOUIC + /prop_sf/SKIP_PRECOMPILE_HEADERS + /prop_sf/SKIP_UNITY_BUILD_INCLUSION /prop_sf/Swift_DEPENDENCIES_FILE /prop_sf/Swift_DIAGNOSTICS_FILE /prop_sf/SYMBOLIC diff --git a/Help/manual/cmake-toolchains.7.rst b/Help/manual/cmake-toolchains.7.rst index 7435d9a..f233d08 100644 --- a/Help/manual/cmake-toolchains.7.rst +++ b/Help/manual/cmake-toolchains.7.rst @@ -399,8 +399,10 @@ Configure use of an Android NDK with the following variables: be false unless using a NDK that does not provide unified headers. :variable:`CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION` - Set to the version of the NDK toolchain to be selected as the compiler. - If not specified, the default will be the latest available GCC toolchain. + On NDK r19 or above, this variable must be unset or set to ``clang``. + On NDK r18 or below, set this to the version of the NDK toolchain to + be selected as the compiler. If not specified, the default will be + the latest available GCC toolchain. :variable:`CMAKE_ANDROID_STL_TYPE` Set to specify which C++ standard library to use. If not specified, diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index e3c2f9f..53b7f8d 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -62,6 +62,7 @@ Variables that Provide Information /variable/CMAKE_JOB_POOLS /variable/CMAKE_LANG_COMPILER_AR /variable/CMAKE_LANG_COMPILER_RANLIB + /variable/CMAKE_LANG_LINK_LIBRARY_SUFFIX /variable/CMAKE_LINK_LIBRARY_SUFFIX /variable/CMAKE_LINK_SEARCH_END_STATIC /variable/CMAKE_LINK_SEARCH_START_STATIC @@ -69,6 +70,7 @@ Variables that Provide Information /variable/CMAKE_MAKE_PROGRAM /variable/CMAKE_MATCH_COUNT /variable/CMAKE_MATCH_n + /variable/CMAKE_MESSAGE_INDENT /variable/CMAKE_MINIMUM_REQUIRED_VERSION /variable/CMAKE_MINOR_VERSION /variable/CMAKE_NETRC @@ -110,6 +112,7 @@ Variables that Provide Information /variable/CMAKE_VS_PLATFORM_NAME_DEFAULT /variable/CMAKE_VS_PLATFORM_TOOLSET /variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA + /variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR /variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE /variable/CMAKE_VS_PLATFORM_TOOLSET_VERSION /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION @@ -158,6 +161,7 @@ Variables that Change Behavior /variable/CMAKE_ECLIPSE_GENERATE_LINKED_RESOURCES /variable/CMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT /variable/CMAKE_ECLIPSE_MAKE_ARGUMENTS + /variable/CMAKE_ECLIPSE_RESOURCE_ENCODING /variable/CMAKE_ECLIPSE_VERSION /variable/CMAKE_ERROR_DEPRECATED /variable/CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION @@ -181,6 +185,13 @@ Variables that Change Behavior /variable/CMAKE_FIND_ROOT_PATH_MODE_LIBRARY /variable/CMAKE_FIND_ROOT_PATH_MODE_PACKAGE /variable/CMAKE_FIND_ROOT_PATH_MODE_PROGRAM + /variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH + /variable/CMAKE_FIND_USE_CMAKE_PATH + /variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH + /variable/CMAKE_FIND_USE_PACKAGE_REGISTRY + /variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH + /variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH + /variable/CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY /variable/CMAKE_FRAMEWORK_PATH /variable/CMAKE_IGNORE_PATH /variable/CMAKE_INCLUDE_DIRECTORIES_BEFORE @@ -224,6 +235,7 @@ Variables that Change Behavior /variable/CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY /variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER /variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN + /variable/CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING /variable/CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER /variable/CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS /variable/CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE @@ -332,6 +344,7 @@ Variables that Control the Build /variable/CMAKE_AUTOMOC_DEPEND_FILTERS /variable/CMAKE_AUTOMOC_MACRO_NAMES /variable/CMAKE_AUTOMOC_MOC_OPTIONS + /variable/CMAKE_AUTOMOC_PATH_PREFIX /variable/CMAKE_AUTORCC /variable/CMAKE_AUTORCC_OPTIONS /variable/CMAKE_AUTOUIC @@ -345,7 +358,9 @@ Variables that Control the Build /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG /variable/CMAKE_CONFIG_POSTFIX /variable/CMAKE_CUDA_SEPARABLE_COMPILATION + /variable/CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS /variable/CMAKE_DEBUG_POSTFIX + /variable/CMAKE_DISABLE_PRECOMPILE_HEADERS /variable/CMAKE_ENABLE_EXPORTS /variable/CMAKE_EXE_LINKER_FLAGS /variable/CMAKE_EXE_LINKER_FLAGS_CONFIG @@ -364,6 +379,7 @@ Variables that Control the Build /variable/CMAKE_INCLUDE_CURRENT_DIR /variable/CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE /variable/CMAKE_INSTALL_NAME_DIR + /variable/CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH /variable/CMAKE_INSTALL_RPATH /variable/CMAKE_INSTALL_RPATH_USE_LINK_PATH /variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION @@ -374,6 +390,8 @@ Variables that Control the Build /variable/CMAKE_LANG_CPPCHECK /variable/CMAKE_LANG_CPPLINT /variable/CMAKE_LANG_INCLUDE_WHAT_YOU_USE + /variable/CMAKE_LANG_LINK_LIBRARY_FILE_FLAG + /variable/CMAKE_LANG_LINK_LIBRARY_FLAG /variable/CMAKE_LANG_VISIBILITY_PRESET /variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY /variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY_CONFIG @@ -417,6 +435,8 @@ Variables that Control the Build /variable/CMAKE_TRY_COMPILE_CONFIGURATION /variable/CMAKE_TRY_COMPILE_PLATFORM_VARIABLES /variable/CMAKE_TRY_COMPILE_TARGET_TYPE + /variable/CMAKE_UNITY_BUILD + /variable/CMAKE_UNITY_BUILD_BATCH_SIZE /variable/CMAKE_USE_RELATIVE_PATHS /variable/CMAKE_VISIBILITY_INLINES_HIDDEN /variable/CMAKE_VS_GLOBALS @@ -509,6 +529,12 @@ Variables for Languages /variable/CMAKE_LANG_SOURCE_FILE_EXTENSIONS /variable/CMAKE_LANG_STANDARD_INCLUDE_DIRECTORIES /variable/CMAKE_LANG_STANDARD_LIBRARIES + /variable/CMAKE_OBJC_EXTENSIONS + /variable/CMAKE_OBJC_STANDARD + /variable/CMAKE_OBJC_STANDARD_REQUIRED + /variable/CMAKE_OBJCXX_EXTENSIONS + /variable/CMAKE_OBJCXX_STANDARD + /variable/CMAKE_OBJCXX_STANDARD_REQUIRED /variable/CMAKE_Swift_LANGUAGE_VERSION /variable/CMAKE_USER_MAKE_RULES_OVERRIDE_LANG @@ -602,7 +628,6 @@ Variables for CPack /variable/CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION /variable/CPACK_INCLUDE_TOPLEVEL_DIRECTORY /variable/CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS - /variable/CPACK_INSTALL_SCRIPT /variable/CPACK_PACKAGING_INSTALL_PREFIX /variable/CPACK_SET_DESTDIR /variable/CPACK_WARN_ON_ABSOLUTE_INSTALL_DESTINATION diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 7b5399d..4ab55a0 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -200,12 +200,15 @@ Options from the top of a binary tree for a CMake project it will dump additional information such as the cache, log files etc. -``--loglevel=<ERROR|WARNING|NOTICE|STATUS|VERBOSE|DEBUG|TRACE>`` +``--log-level=<ERROR|WARNING|NOTICE|STATUS|VERBOSE|DEBUG|TRACE>`` Set the log level. The :command:`message` command will only output messages of the specified log level or higher. The default log level is ``STATUS``. + For backward compatibility reasons, ``--loglevel`` is also accepted as a + synonym for this option. + ``--debug-trycompile`` Do not delete the :command:`try_compile` build tree. Only useful on one :command:`try_compile` at a time. @@ -238,6 +241,9 @@ Options Multiple options are allowed. +``--trace-redirect=<file>`` + Put cmake in trace mode and redirect trace output to a file instead of stderr. + ``--warn-uninitialized`` Warn about uninitialized values. @@ -459,7 +465,7 @@ Available commands are: but the files or directories it point to. ``copy_directory <dir>... <destination>`` - Copy directories to ``<destination>`` directory. + Copy content of ``<dir>...`` directories to ``<destination>`` directory. If ``<destination>`` directory does not exist it will be created. ``copy_directory`` does follow symlinks. @@ -470,6 +476,12 @@ Available commands are: directory and it must exist. ``copy_if_different`` does follow symlinks. +``create_symlink <old> <new>`` + Create a symbolic link ``<new>`` naming ``<old>``. + + .. note:: + Path to where ``<new>`` symbolic link will be created has to exist beforehand. + ``echo [<string>...]`` Displays arguments as text. @@ -482,6 +494,9 @@ Available commands are: ``environment`` Display the current environment variables. +``false`` + Do nothing, with an exit code of 1. + ``make_directory <dir>...`` Create ``<dir>`` directories. If necessary, create parent directories too. If a directory already exists it will be @@ -533,7 +548,8 @@ Available commands are: ``remove_directory <dir>...`` Remove ``<dir>`` directories and their contents. If a directory does - not exist it will be silently ignored. + not exist it will be silently ignored. If ``<dir>`` is a symlink to + a directory, just the symlink will be removed. ``rename <oldname> <newname>`` Rename a file or directory (on one volume). If file with the ``<newname>`` name @@ -598,11 +614,8 @@ Available commands are: Touch a file if it exists but do not create it. If a file does not exist it will be silently ignored. -``create_symlink <old> <new>`` - Create a symbolic link ``<new>`` naming ``<old>``. - -.. note:: - Path to where ``<new>`` symbolic link will be created has to exist beforehand. +``true`` + Do nothing, with an exit code of 0. Windows-specific Command-Line Tools ----------------------------------- diff --git a/Help/manual/cpack.1.rst b/Help/manual/cpack.1.rst index 10f617e..395cd41 100644 --- a/Help/manual/cpack.1.rst +++ b/Help/manual/cpack.1.rst @@ -48,11 +48,15 @@ Options the :variable:`CPACK_GENERATOR` variable determines the default set of generators that will be used. -``-C <Configuration>`` - Specify the project configuration to be packaged (e.g. ``Debug``, - ``Release``, etc.). When the CMake project uses a multi-configuration +``-C <configs>`` + Specify the project configuration(s) to be packaged (e.g. ``Debug``, + ``Release``, etc.), where ``<configs>`` is a + :ref:`semicolon-separated list <CMake Language Lists>`. + When the CMake project uses a multi-configuration generator such as Xcode or Visual Studio, this option is needed to tell ``cpack`` which built executables to include in the package. + The user is responsible for ensuring that the configuration(s) listed + have already been built before invoking ``cpack``. ``-D <var>=<value>`` Set a CPack variable. This will override any value set for ``<var>`` in the diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index 5773176..e29ebca 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -90,6 +90,15 @@ Options See `Label and Subproject Summary`_. +``--resource-spec-file <file>`` + Run CTest with :ref:`resource allocation <ctest-resource-allocation>` enabled, + using the + :ref:`resource specification file <ctest-resource-specification-file>` + specified in ``<file>``. + + When ``ctest`` is run as a `Dashboard Client`_ this sets the + ``ResourceSpecFile`` option of the `CTest Test Step`_. + ``--test-load <level>`` While running tests in parallel (e.g. with ``-j``), try not to start tests when they may cause the CPU load to pass above a given threshold. @@ -443,7 +452,8 @@ this mode include: Specify the name of the project to build. ``--build-makeprogram`` - Override the make program chosen by CTest with a given one. + Specify the explicit make program to be used by CMake when configuring and + building the project. Only applicable for Make and Ninja based generators. ``--build-noclean`` Skip the make clean step. @@ -481,14 +491,17 @@ a `CDash`_ server. The command-line signature used to submit to `CDash`_ is:: Options for Dashboard Client include: -``--track <track>`` - Specify the track to submit dashboard to +``--group <group>`` + Specify what group you'd like to submit results to - Submit dashboard to specified track instead of default one. By + Submit dashboard to specified group instead of default one. By default, the dashboard is submitted to Nightly, Experimental, or - Continuous track, but by specifying this option, the track can be + Continuous group, but by specifying this option, the group can be arbitrary. + This replaces the deprecated option ``--track``. + Despite the name change its behavior is unchanged. + ``-A <file>, --add-notes <file>`` Add a notes file with submission. @@ -954,6 +967,11 @@ Arguments to the command may specify some of the step settings. Configuration settings include: +``ResourceSpecFile`` + Specify a + :ref:`resource specification file <ctest-resource-specification-file>`. See + :ref:`ctest-resource-allocation` for more information. + ``LabelsForSubprojects`` Specify a semicolon-separated list of labels that will be treated as subprojects. This mapping will be passed on to CDash when configure, test or @@ -1263,6 +1281,248 @@ model is defined as follows: Test properties. Can contain keys for each of the supported test properties. +.. _`ctest-resource-allocation`: + +Resource Allocation +=================== + +CTest provides a mechanism for tests to specify the resources that they need +in a fine-grained way, and for users to specify the resources availiable on +the running machine. This allows CTest to internally keep track of which +resources are in use and which are free, scheduling tests in a way that +prevents them from trying to claim resources that are not available. + +A common use case for this feature is for tests that require the use of a GPU. +Multiple tests can simultaneously allocate memory from a GPU, but if too many +tests try to do this at once, some of them will fail to allocate, resulting in +a failed test, even though the test would have succeeded if it had the memory +it needed. By using the resource allocation feature, each test can specify how +much memory it requires from a GPU, allowing CTest to schedule tests in a way +that running several of these tests at once does not exhaust the GPU's memory +pool. + +Please note that CTest has no concept of what a GPU is or how much memory it +has, nor does it have any way of communicating with a GPU to retrieve this +information or perform any memory management. CTest simply keeps track of a +list of abstract resource types, each of which has a certain number of slots +available for tests to use. Each test specifies the number of slots that it +requires from a certain resource, and CTest then schedules them in a way that +prevents the total number of slots in use from exceeding the listed capacity. +When a test is executed, and slots from a resource are allocated to that test, +tests may assume that they have exclusive use of those slots for the duration +of the test's process. + +The CTest resource allocation feature consists of two inputs: + +* The :ref:`resource specification file <ctest-resource-specification-file>`, + described below, which describes the resources available on the system. +* The :prop_test:`RESOURCE_GROUPS` property of tests, which describes the + resources required by the test. + +When CTest runs a test, the resources allocated to that test are passed in the +form of a set of +:ref:`environment variables <ctest-resource-environment-variables>` as +described below. Using this information to decide which resource to connect to +is left to the test writer. + +The ``RESOURCE_GROUPS`` property tells CTest what resources a test expects +to use grouped in a way meaningful to the test. The test itself must read +the :ref:`environment variables <ctest-resource-environment-variables>` to +determine which resources have been allocated to each group. For example, +each group may correspond to a process the test will spawn when executed. + +Note that even if a test specifies a ``RESOURCE_GROUPS`` property, it is still +possible for that to test to run without any resource allocation (and without +the corresponding +:ref:`environment variables <ctest-resource-environment-variables>`) +if the user does not pass a resource specification file. Passing this file, +either through the ``--resource-spec-file`` command-line argument or the +``RESOURCE_SPEC_FILE`` argument to :command:`ctest_test`, is what activates the +resource allocation feature. Tests should check the +``CTEST_RESOURCE_GROUP_COUNT`` environment variable to find out whether or not +resource allocation is activated. This variable will always (and only) be +defined if resource allocation is activated. If resource allocation is not +activated, then the ``CTEST_RESOURCE_GROUP_COUNT`` variable will not exist, +even if it exists for the parent ``ctest`` process. If a test absolutely must +have resource allocation, then it can return a failing exit code or use the +:prop_test:`SKIP_RETURN_CODE` or :prop_test:`SKIP_REGULAR_EXPRESSION` +properties to indicate a skipped test. + +.. _`ctest-resource-specification-file`: + +Resource Specification File +--------------------------- + +The resource specification file is a JSON file which is passed to CTest, either +on the :manual:`ctest(1)` command line as ``--resource-spec-file``, or as the +``RESOURCE_SPEC_FILE`` argument of :command:`ctest_test`. The resource +specification file must be a JSON object. All examples in this document assume +the following resource specification file: + +.. code-block:: json + + { + "version": { + "major": 1, + "minor": 0 + }, + "local": [ + { + "gpus": [ + { + "id": "0", + "slots": 2 + }, + { + "id": "1", + "slots": 4 + }, + { + "id": "2", + "slots": 2 + }, + { + "id": "3" + } + ], + "crypto_chips": [ + { + "id": "card0", + "slots": 4 + } + ] + } + ] + } + +The members are: + +``version`` + An object containing a ``major`` integer field and a ``minor`` integer field. + Currently, the only supported version is major ``1``, minor ``0``. Any other + value is an error. + +``local`` + A JSON array of resource sets present on the system. Currently, this array + is restricted to being of size 1. + + Each array element is a JSON object with members whose names are equal to the + desired resource types, such as ``gpus``. These names must start with a + lowercase letter or an underscore, and subsequent characters can be a + lowercase letter, a digit, or an underscore. Uppercase letters are not + allowed, because certain platforms have case-insensitive environment + variables. See the `Environment Variables`_ section below for + more information. It is recommended that the resource type name be the plural + of a noun, such as ``gpus`` or ``crypto_chips`` (and not ``gpu`` or + ``crypto_chip``.) + + Please note that the names ``gpus`` and ``crypto_chips`` are just examples, + and CTest does not interpret them in any way. You are free to make up any + resource type you want to meet your own requirements. + + The value for each resource type is a JSON array consisting of JSON objects, + each of which describe a specific instance of the specified resource. These + objects have the following members: + + ``id`` + A string consisting of an identifier for the resource. Each character in + the identifier can be a lowercase letter, a digit, or an underscore. + Uppercase letters are not allowed. + + Identifiers must be unique within a resource type. However, they do not + have to be unique across resource types. For example, it is valid to have a + ``gpus`` resource named ``0`` and a ``crypto_chips`` resource named ``0``, + but not two ``gpus`` resources both named ``0``. + + Please note that the IDs ``0``, ``1``, ``2``, ``3``, and ``card0`` are just + examples, and CTest does not interpret them in any way. You are free to + make up any IDs you want to meet your own requirements. + + ``slots`` + An optional unsigned number specifying the number of slots available on the + resource. For example, this could be megabytes of RAM on a GPU, or + cryptography units available on a cryptography chip. If ``slots`` is not + specified, a default value of ``1`` is assumed. + +In the example file above, there are four GPUs with ID's 0 through 3. GPU 0 has +2 slots, GPU 1 has 4, GPU 2 has 2, and GPU 3 has a default of 1 slot. There is +also one cryptography chip with 4 slots. + +``RESOURCE_GROUPS`` Property +---------------------------- + +See :prop_test:`RESOURCE_GROUPS` for a description of this property. + +.. _`ctest-resource-environment-variables`: + +Environment Variables +--------------------- + +Once CTest has decided which resources to allocate to a test, it passes this +information to the test executable as a series of environment variables. For +each example below, we will assume that the test in question has a +:prop_test:`RESOURCE_GROUPS` property of +``2,gpus:2;gpus:4,gpus:1,crypto_chips:2``. + +The following variables are passed to the test process: + +.. envvar:: CTEST_RESOURCE_GROUP_COUNT + + The total number of groups specified by the :prop_test:`RESOURCE_GROUPS` + property. For example: + + * ``CTEST_RESOURCE_GROUP_COUNT=3`` + + This variable will only be defined if :manual:`ctest(1)` has been given a + ``--resource-spec-file``, or if :command:`ctest_test` has been given a + ``RESOURCE_SPEC_FILE``. If no resource specification file has been given, + this variable will not be defined. + +.. envvar:: CTEST_RESOURCE_GROUP_<num> + + The list of resource types allocated to each group, with each item + separated by a comma. ``<num>`` is a number from zero to + ``CTEST_RESOURCE_GROUP_COUNT`` minus one. ``CTEST_RESOURCE_GROUP_<num>`` + is defined for each ``<num>`` in this range. For example: + + * ``CTEST_RESOURCE_GROUP_0=gpus`` + * ``CTEST_RESOURCE_GROUP_1=gpus`` + * ``CTEST_RESOURCE_GROUP_2=crypto_chips,gpus`` + +.. envvar:: CTEST_RESOURCE_GROUP_<num>_<resource-type> + + The list of resource IDs and number of slots from each ID allocated to each + group for a given resource type. This variable consists of a series of + pairs, each pair separated by a semicolon, and with the two items in the pair + separated by a comma. The first item in each pair is ``id:`` followed by the + ID of a resource of type ``<resource-type>``, and the second item is + ``slots:`` followed by the number of slots from that resource allocated to + the given group. For example: + + * ``CTEST_RESOURCE_GROUP_0_GPUS=id:0,slots:2`` + * ``CTEST_RESOURCE_GROUP_1_GPUS=id:2,slots:2`` + * ``CTEST_RESOURCE_GROUP_2_GPUS=id:1,slots:4;id:3,slots:1`` + * ``CTEST_RESOURCE_GROUP_2_CRYPTO_CHIPS=id:card0,slots:2`` + + In this example, group 0 gets 2 slots from GPU ``0``, group 1 gets 2 slots + from GPU ``2``, and group 2 gets 4 slots from GPU ``1``, 1 slot from GPU + ``3``, and 2 slots from cryptography chip ``card0``. + + ``<num>`` is a number from zero to ``CTEST_RESOURCE_GROUP_COUNT`` minus one. + ``<resource-type>`` is the name of a resource type, converted to uppercase. + ``CTEST_RESOURCE_GROUP_<num>_<resource-type>`` is defined for the product + of each ``<num>`` in the range listed above and each resource type listed in + ``CTEST_RESOURCE_GROUP_<num>``. + + Because some platforms have case-insensitive names for environment variables, + the names of resource types may not clash in a case-insensitive environment. + Because of this, for the sake of simplicity, all resource types must be + listed in all lowercase in the + :ref:`resource specification file <ctest-resource-specification-file>` and + in the :prop_test:`RESOURCE_GROUPS` property, and they are converted to all + uppercase in the ``CTEST_RESOURCE_GROUP_<num>_<resource-type>`` environment + variable. + See Also ======== diff --git a/Help/module/CheckOBJCCompilerFlag.rst b/Help/module/CheckOBJCCompilerFlag.rst new file mode 100644 index 0000000..e4bd6fd --- /dev/null +++ b/Help/module/CheckOBJCCompilerFlag.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckOBJCCompilerFlag.cmake diff --git a/Help/module/CheckOBJCSourceCompiles.rst b/Help/module/CheckOBJCSourceCompiles.rst new file mode 100644 index 0000000..d4a1484 --- /dev/null +++ b/Help/module/CheckOBJCSourceCompiles.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckOBJCSourceCompiles.cmake diff --git a/Help/module/CheckOBJCSourceRuns.rst b/Help/module/CheckOBJCSourceRuns.rst new file mode 100644 index 0000000..c72f0db --- /dev/null +++ b/Help/module/CheckOBJCSourceRuns.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckOBJCSourceRuns.cmake diff --git a/Help/module/CheckOBJCXXCompilerFlag.rst b/Help/module/CheckOBJCXXCompilerFlag.rst new file mode 100644 index 0000000..1518a48 --- /dev/null +++ b/Help/module/CheckOBJCXXCompilerFlag.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckOBJCXXCompilerFlag.cmake diff --git a/Help/module/CheckOBJCXXSourceCompiles.rst b/Help/module/CheckOBJCXXSourceCompiles.rst new file mode 100644 index 0000000..a1c8ae9 --- /dev/null +++ b/Help/module/CheckOBJCXXSourceCompiles.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckOBJCXXSourceCompiles.cmake diff --git a/Help/module/CheckOBJCXXSourceRuns.rst b/Help/module/CheckOBJCXXSourceRuns.rst new file mode 100644 index 0000000..5198e1b --- /dev/null +++ b/Help/module/CheckOBJCXXSourceRuns.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckOBJCXXSourceRuns.cmake diff --git a/Help/policy/CMP0074.rst b/Help/policy/CMP0074.rst index 896936b..63ebf7b 100644 --- a/Help/policy/CMP0074.rst +++ b/Help/policy/CMP0074.rst @@ -7,9 +7,9 @@ In CMake 3.12 and above the :command:`find_package(<PackageName>)` command now searches prefixes specified by the :variable:`<PackageName>_ROOT` CMake variable and the :envvar:`<PackageName>_ROOT` environment variable. Package roots are maintained as a stack so nested calls to all ``find_*`` -commands inside find modules also search the roots as prefixes. This policy -provides compatibility with projects that have not been updated to avoid using -``<PackageName>_ROOT`` variables for other purposes. +commands inside find modules and config packages also search the roots as +prefixes. 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. The ``NEW`` behavior for this policy is to use diff --git a/Help/policy/CMP0095.rst b/Help/policy/CMP0095.rst new file mode 100644 index 0000000..4c56a05 --- /dev/null +++ b/Help/policy/CMP0095.rst @@ -0,0 +1,30 @@ +CMP0095 +------- + +``RPATH`` entries are properly escaped in the intermediary CMake install script. + +In CMake 3.15 and earlier, ``RPATH`` entries set via +:variable:`CMAKE_INSTALL_RPATH` or via :prop_tgt:`INSTALL_RPATH` have not been +escaped before being inserted into the ``cmake_install.cmake`` script. Dynamic +linkers on ELF-based systems (e.g. Linux and FreeBSD) allow certain keywords in +``RPATH`` entries, such as ``${ORIGIN}`` (More details are available in the +``ld.so`` man pages on those systems). The syntax of these keywords can match +CMake's variable syntax. In order to not be substituted (usually to an empty +string) already by the intermediary ``cmake_install.cmake`` script, the user had +to double-escape such ``RPATH`` keywords, e.g. +``set(CMAKE_INSTALL_RPATH "\\\${ORIGIN}/../lib")``. Since the intermediary +``cmake_install.cmake`` script is an implementation detail of CMake, CMake 3.16 +and later will make sure ``RPATH`` entries are inserted literally by escaping +any coincidental CMake syntax. + +The ``OLD`` behavior of this policy is to not escape ``RPATH`` entries in the +intermediary ``cmake_install.cmake`` script. The ``NEW`` behavior is to properly +escape coincidental CMake syntax in ``RPATH`` entries when generating the +intermediary ``cmake_install.cmake`` script. + +This policy was introduced in CMake version 3.16. CMake version |release| warns +when the policy is not set and detected usage of CMake-like syntax 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/CMP0096.rst b/Help/policy/CMP0096.rst new file mode 100644 index 0000000..8eaf0f9 --- /dev/null +++ b/Help/policy/CMP0096.rst @@ -0,0 +1,25 @@ +CMP0096 +------- + +The :command:`project` command preserves leading zeros in version components. + +When a ``VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]`` argument is given +to the :command:`project` command, it stores the version string in the +``PROJECT_VERSION`` variable and stores individual integer version components +in ``PROJECT_VERSION_{MAJOR,MINOR,PATCH,TWEAK}`` variables (see policy +:policy:`CMP0048`). CMake 3.15 and below dropped leading zeros from each +component. CMake 3.16 and higher prefer to preserve leading zeros. This +policy provides compatibility for projects that have not been updated to +expect the new behavior. + +The ``OLD`` behavior of this policy drops leading zeros in all components, +e.g. such that version ``1.07.06`` becomes ``1.7.6``. The ``NEW`` behavior +of this policy preserves the leading zeros in all components, such that +version ``1.07.06`` remains unchanged. + +This policy was introduced in CMake version 3.16. Unlike many policies, CMake +version |release| does *not* warn when this policy is not set and simply uses +the ``OLD`` behavior. Use the :command:`cmake_policy` command to set it to +``OLD`` or ``NEW`` explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0097.rst b/Help/policy/CMP0097.rst new file mode 100644 index 0000000..4840aa6 --- /dev/null +++ b/Help/policy/CMP0097.rst @@ -0,0 +1,23 @@ +CMP0097 +------- + +:command:`ExternalProject_Add` with ``GIT_SUBMODULES ""`` initializes no +submodules. + +The module provides a ``GIT_SUBMODULES`` option which controls what submodules +to initialize and update. Starting with CMake 3.16, explicitly setting +``GIT_SUBMODULES`` to an empty string means no submodules will be initialized +or updated. + +This policy provides compatibility for projects that have not been updated +to expect the new behavior. + +The ``OLD`` behavior for this policy is for ``GIT_SUBMODULES`` when set to +an empty string to initialize and update all git submodules. +The ``NEW`` behavior for this policy is for ``GIT_SUBMODULES`` when set to +an empty string to initialize and update no git submodules. + +This policy was introduced in CMake version 3.16. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +Unlike most policies, CMake version |release| does *not* warn +when this policy is not set and simply uses ``OLD`` behavior. diff --git a/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst index 262a67c..b921c6b 100644 --- a/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst +++ b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst @@ -15,19 +15,19 @@ compile features and a list of supported compilers. The features known to this version of CMake are: ``cxx_std_98`` - Compiler mode is aware of C++ 98. + Compiler mode is at least C++ 98. ``cxx_std_11`` - Compiler mode is aware of C++ 11. + Compiler mode is at least C++ 11. ``cxx_std_14`` - Compiler mode is aware of C++ 14. + Compiler mode is at least C++ 14. ``cxx_std_17`` - Compiler mode is aware of C++ 17. + Compiler mode is at least C++ 17. ``cxx_std_20`` - Compiler mode is aware of C++ 20. + Compiler mode is at least C++ 20. ``cxx_aggregate_default_initializers`` Aggregate default initializers, as defined in N3605_. diff --git a/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst index 3707fef..e5f896e 100644 --- a/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst +++ b/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst @@ -14,13 +14,13 @@ compile features and a list of supported compilers. The features known to this version of CMake are: ``c_std_90`` - Compiler mode is aware of C 90. + Compiler mode is at least C 90. ``c_std_99`` - Compiler mode is aware of C 99. + Compiler mode is at least C 99. ``c_std_11`` - Compiler mode is aware of C 11. + Compiler mode is at least C 11. ``c_function_prototypes`` Function prototypes, as defined in ``ISO/IEC 9899:1990``. diff --git a/Help/prop_sf/SKIP_PRECOMPILE_HEADERS.rst b/Help/prop_sf/SKIP_PRECOMPILE_HEADERS.rst new file mode 100644 index 0000000..5f39f30 --- /dev/null +++ b/Help/prop_sf/SKIP_PRECOMPILE_HEADERS.rst @@ -0,0 +1,13 @@ +SKIP_PRECOMPILE_HEADERS +----------------------- + +Is this source file skipped by :prop_tgt:`PRECOMPILE_HEADERS` feature. + +This property helps with build problems that one would run into +when using the :prop_tgt:`PRECOMPILE_HEADERS` feature. + +One example would be the usage of Objective-C (*.m) files, and +Objective-C++ (*.mm) files, which lead to compilation failure +because they are treated (in case of Ninja / Makefile generator) +as C, and CXX respectively. The precompile headers are not +compatible between languages. diff --git a/Help/prop_sf/SKIP_UNITY_BUILD_INCLUSION.rst b/Help/prop_sf/SKIP_UNITY_BUILD_INCLUSION.rst new file mode 100644 index 0000000..6d1e60d --- /dev/null +++ b/Help/prop_sf/SKIP_UNITY_BUILD_INCLUSION.rst @@ -0,0 +1,11 @@ +SKIP_UNITY_BUILD_INCLUSION +-------------------------- + +Setting this property to true ensures the source file will be skipped by +unity builds when its associated target has its :prop_tgt:`UNITY_BUILD` +property set to true. The source file will instead be compiled on its own +in the same way as it would with unity builds disabled. + +This property helps with "ODR (One definition rule)" problems where combining +a particular source file with others might lead to build errors or other +unintended side effects. diff --git a/Help/prop_test/RESOURCE_GROUPS.rst b/Help/prop_test/RESOURCE_GROUPS.rst new file mode 100644 index 0000000..63c56ce --- /dev/null +++ b/Help/prop_test/RESOURCE_GROUPS.rst @@ -0,0 +1,70 @@ +RESOURCE_GROUPS +--------------- + +Specify resources required by a test, grouped in a way that is meaningful to +the test. See :ref:`resource allocation <ctest-resource-allocation>` +for more information on how this property integrates into the CTest resource +allocation feature. + +The ``RESOURCE_GROUPS`` property is a :ref:`semicolon-separated list <CMake +Language Lists>` of group descriptions. Each entry consists of an optional +number of groups using the description followed by a series of resource +requirements for those groups. These requirements (and the number of groups) +are separated by commas. The resource requirements consist of the name of a +resource type, followed by a colon, followed by an unsigned integer +specifying the number of slots required on one resource of the given type. + +The ``RESOURCE_GROUPS`` property tells CTest what resources a test expects +to use grouped in a way meaningful to the test. The test itself must read +the :ref:`environment variables <ctest-resource-environment-variables>` to +determine which resources have been allocated to each group. For example, +each group may correspond to a process the test will spawn when executed. + +Consider the following example: + +.. code-block:: cmake + + add_test(NAME MyTest COMMAND MyExe) + set_property(TEST MyTest PROPERTY RESOURCE_GROUPS + "2,gpus:2" + "gpus:4,crypto_chips:2") + +In this example, there are two group descriptions (implicitly separated by a +semicolon.) The content of the first description is ``2,gpus:2``. This +description specifies 2 groups, each of which requires 2 slots from a single +GPU. The content of the second description is ``gpus:4,crypto_chips:2``. This +description does not specify a group count, so a default of 1 is assumed. +This single group requires 4 slots from a single GPU and 2 slots from a +single cryptography chip. In total, 3 resource groups are specified for this +test, each with its own unique requirements. + +Note that the number of slots following the resource type specifies slots from +a *single* instance of the resource. If the resource group can tolerate +receiving slots from different instances of the same resource, it can indicate +this by splitting the specification into multiple requirements of one slot. For +example: + +.. code-block:: cmake + + add_test(NAME MyTest COMMAND MyExe) + set_property(TEST MyTest PROPERTY RESOURCE_GROUPS + "gpus:1,gpus:1,gpus:1,gpus:1") + +In this case, the single resource group indicates that it needs four GPU slots, +all of which may come from separate GPUs (though they don't have to; CTest may +still assign slots from the same GPU.) + +When CTest sets the :ref:`environment variables +<ctest-resource-environment-variables>` for a test, it assigns a group number +based on the group description, starting at 0 on the left and the number of +groups minus 1 on the right. For example, in the example above, the two +groups in the first description would have IDs of 0 and 1, and the single +group in the second description would have an ID of 2. + +Both the ``RESOURCE_GROUPS`` and :prop_test:`RESOURCE_LOCK` properties serve +similar purposes, but they are distinct and orthogonal. Resources specified by +``RESOURCE_GROUPS`` do not affect :prop_test:`RESOURCE_LOCK`, and vice versa. +Whereas :prop_test:`RESOURCE_LOCK` is a simpler property that is used for +locking one global resource, ``RESOURCE_GROUPS`` is a more advanced property +that allows multiple tests to simultaneously use multiple resources of the +same type, specifying their requirements in a fine-grained manner. diff --git a/Help/prop_test/RESOURCE_LOCK.rst b/Help/prop_test/RESOURCE_LOCK.rst index 755e0aa..8b13a01 100644 --- a/Help/prop_test/RESOURCE_LOCK.rst +++ b/Help/prop_test/RESOURCE_LOCK.rst @@ -8,3 +8,11 @@ not to run concurrently. See also :prop_test:`FIXTURES_REQUIRED` if the resource requires any setup or cleanup steps. + +Both the :prop_test:`RESOURCE_GROUPS` and ``RESOURCE_LOCK`` properties serve +similar purposes, but they are distinct and orthogonal. Resources specified by +:prop_test:`RESOURCE_GROUPS` do not affect ``RESOURCE_LOCK``, and vice versa. +Whereas ``RESOURCE_LOCK`` is a simpler property that is used for locking one +global resource, :prop_test:`RESOURCE_GROUPS` is a more advanced property +that allows multiple tests to simultaneously use multiple resources of the +same type, specifying their requirements in a fine-grained manner. diff --git a/Help/prop_test/SKIP_REGULAR_EXPRESSION.rst b/Help/prop_test/SKIP_REGULAR_EXPRESSION.rst new file mode 100644 index 0000000..2c6d980 --- /dev/null +++ b/Help/prop_test/SKIP_REGULAR_EXPRESSION.rst @@ -0,0 +1,17 @@ +SKIP_REGULAR_EXPRESSION +----------------------- + +If the output matches this regular expression the test will be marked as skipped. + +If set, if the output matches one of specified regular expressions, +the test will be marked as skipped. Example: + +.. code-block:: cmake + + set_property(TEST mytest PROPERTY + SKIP_REGULAR_EXPRESSION "[^a-z]Skip" "SKIP" "Skipped" + ) + +``SKIP_REGULAR_EXPRESSION`` expects a list of regular expressions. + +See also the :prop_test:`SKIP_RETURN_CODE` property. diff --git a/Help/prop_test/SKIP_RETURN_CODE.rst b/Help/prop_test/SKIP_RETURN_CODE.rst index a05fbf3..23c4c62 100644 --- a/Help/prop_test/SKIP_RETURN_CODE.rst +++ b/Help/prop_test/SKIP_RETURN_CODE.rst @@ -6,4 +6,7 @@ Return code to mark a test as skipped. Sometimes only a test itself can determine if all requirements for the test are met. If such a situation should not be considered a hard failure a return code of the process can be specified that will mark the test as -``Not Run`` if it is encountered. +``Not Run`` if it is encountered. Valid values are in the range of +0 to 255, inclusive. + +See also the :prop_test:`SKIP_REGULAR_EXPRESSION` property. diff --git a/Help/prop_tgt/AUTOMOC_PATH_PREFIX.rst b/Help/prop_tgt/AUTOMOC_PATH_PREFIX.rst new file mode 100644 index 0000000..e2ebb3f --- /dev/null +++ b/Help/prop_tgt/AUTOMOC_PATH_PREFIX.rst @@ -0,0 +1,32 @@ +AUTOMOC_PATH_PREFIX +------------------- + +When this property is ``ON``, CMake will generate the ``-p`` path prefix +option for ``moc`` on :prop_tgt:`AUTOMOC` enabled Qt targets. + +To generate the path prefix, CMake tests if the header compiled by ``moc`` +is in any of the target +:command:`include directories <target_include_directories>`. If so, CMake will +compute the relative path accordingly. If the header is not in the +:command:`include directories <target_include_directories>`, CMake will omit +the ``-p`` path prefix option. ``moc`` usually generates a +relative include path in that case. + +:prop_tgt:`AUTOMOC_PATH_PREFIX` is initialized from the variable +:variable:`CMAKE_AUTOMOC_PATH_PREFIX`, which is ``ON`` by default. + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. + +Reproducible builds +^^^^^^^^^^^^^^^^^^^ + +For reproducible builds is is recommended to keep headers that are ``moc`` +compiled in one of the target +:command:`include directories <target_include_directories>` and set +:prop_tgt:`AUTOMOC_PATH_PREFIX` to ``ON`` (which is the default). This ensures +that + +- ``moc`` output files are identical on different build setups, +- ``moc`` output files will compile correctly when the source and/or + build directory is a symbolic link. diff --git a/Help/prop_tgt/BUILD_RPATH.rst b/Help/prop_tgt/BUILD_RPATH.rst index 13c9c1d..d978b94 100644 --- a/Help/prop_tgt/BUILD_RPATH.rst +++ b/Help/prop_tgt/BUILD_RPATH.rst @@ -8,3 +8,6 @@ tree. See also the :prop_tgt:`INSTALL_RPATH` target property. This property is initialized by the value of the variable :variable:`CMAKE_BUILD_RPATH` if it is set when a target is created. + +This property supports +:manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/prop_tgt/CUDA_RESOLVE_DEVICE_SYMBOLS.rst b/Help/prop_tgt/CUDA_RESOLVE_DEVICE_SYMBOLS.rst index ef74ae2..dae960f 100644 --- a/Help/prop_tgt/CUDA_RESOLVE_DEVICE_SYMBOLS.rst +++ b/Help/prop_tgt/CUDA_RESOLVE_DEVICE_SYMBOLS.rst @@ -1,12 +1,16 @@ CUDA_RESOLVE_DEVICE_SYMBOLS --------------------------- -CUDA only: Enables device linking for the specific library target - -If set this will enable device linking on the library target. Normally -device linking is deferred until a shared library or executable is generated, -allowing for multiple static libraries to resolve device symbols at the same -time when they are used by a shared library or executable. +CUDA only: Enables device linking for the specific library target where +required. + +If set, this will tell the required compilers to enable device linking +on the library target. Device linking is an additional link step +required by some CUDA compilers when :prop_tgt:`CUDA_SEPARABLE_COMPILATION` is +enabled. Normally device linking is deferred until a shared library or +executable is generated, allowing for multiple static libraries to resolve +device symbols at the same time when they are used by a shared library or +executable. By default static library targets have this property is disabled, while shared, module, and executable targets have this property enabled. diff --git a/Help/prop_tgt/DISABLE_PRECOMPILE_HEADERS.rst b/Help/prop_tgt/DISABLE_PRECOMPILE_HEADERS.rst new file mode 100644 index 0000000..4cef023 --- /dev/null +++ b/Help/prop_tgt/DISABLE_PRECOMPILE_HEADERS.rst @@ -0,0 +1,8 @@ +DISABLE_PRECOMPILE_HEADERS +-------------------------- + +Disables the precompilation of header files specified by +:prop_tgt:`PRECOMPILE_HEADERS` property. + +If the property is not set, CMake will use the value provided +by :variable:`CMAKE_DISABLE_PRECOMPILE_HEADERS`. diff --git a/Help/prop_tgt/ENABLE_EXPORTS.rst b/Help/prop_tgt/ENABLE_EXPORTS.rst index 581c2b9..0b1064a 100644 --- a/Help/prop_tgt/ENABLE_EXPORTS.rst +++ b/Help/prop_tgt/ENABLE_EXPORTS.rst @@ -7,16 +7,25 @@ Normally an executable does not export any symbols because it is the final program. It is possible for an executable to export symbols to be used by loadable modules. When this property is set to true CMake will allow other targets to "link" to the executable with the -:command:`TARGET_LINK_LIBRARIES` command. On all platforms a target-level +:command:`target_link_libraries` command. On all platforms a target-level dependency on the executable is created for targets that link to it. -For DLL platforms an import library will be created for the exported -symbols and then used for linking. All Windows-based systems -including Cygwin are DLL platforms. For non-DLL platforms that -require all symbols to be resolved at link time, such as macOS, the -module will "link" to the executable using a flag like -``-bundle_loader``. For other non-DLL platforms the link rule is simply -ignored since the dynamic loader will automatically bind symbols when -the module is loaded. +Handling of the executable on the link lines of the loadable modules +varies by platform: + +* On Windows-based systems (including Cygwin) an "import library" is + created along with the executable to list the exported symbols. + Loadable modules link to the import library to get the symbols. + +* On macOS, loadable modules link to the executable itself using the + ``-bundle_loader`` flag. + +* On AIX, a linker "import file" is created along with the executable + to list the exported symbols for import when linking other targets. + Loadable modules link to the import file to get the symbols. + +* On other platforms, loadable modules are simply linked without + referencing the executable since the dynamic loader will + 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. diff --git a/Help/prop_tgt/IMPORTED_IMPLIB.rst b/Help/prop_tgt/IMPORTED_IMPLIB.rst index 77fb552..c8b6fde 100644 --- a/Help/prop_tgt/IMPORTED_IMPLIB.rst +++ b/Help/prop_tgt/IMPORTED_IMPLIB.rst @@ -3,5 +3,7 @@ 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. Ignored -for non-imported targets. +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. diff --git a/Help/prop_tgt/IMPORTED_LOCATION.rst b/Help/prop_tgt/IMPORTED_LOCATION.rst index a9123cd..f0a1646 100644 --- a/Help/prop_tgt/IMPORTED_LOCATION.rst +++ b/Help/prop_tgt/IMPORTED_LOCATION.rst @@ -26,3 +26,6 @@ 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 +:prop_tgt:`IMPORTED_IMPLIB`. diff --git a/Help/prop_tgt/INSTALL_REMOVE_ENVIRONMENT_RPATH.rst b/Help/prop_tgt/INSTALL_REMOVE_ENVIRONMENT_RPATH.rst new file mode 100644 index 0000000..72dcaa0 --- /dev/null +++ b/Help/prop_tgt/INSTALL_REMOVE_ENVIRONMENT_RPATH.rst @@ -0,0 +1,16 @@ +INSTALL_REMOVE_ENVIRONMENT_RPATH +-------------------------------- + +Controls whether toolchain-defined rpaths should be removed during installation. + +When a target is being installed, CMake may need to rewrite its rpath +information. This occurs when the install rpath (as specified by the +:prop_tgt:`INSTALL_RPATH` target property) has different contents to the rpath +that the target was built with. Some toolchains insert their own rpath +contents into the binary as part of the build. By default, CMake will +preserve those extra inserted contents in the install rpath. For those +scenarios where such toolchain-inserted entries need to be discarded during +install, set the ``INSTALL_REMOVE_ENVIRONMENT_RPATH`` target property to true. + +This property is initialized by the value of +:variable:`CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH` when the target is created. diff --git a/Help/prop_tgt/INSTALL_RPATH.rst b/Help/prop_tgt/INSTALL_RPATH.rst index 6403f4c..93b4488 100644 --- a/Help/prop_tgt/INSTALL_RPATH.rst +++ b/Help/prop_tgt/INSTALL_RPATH.rst @@ -7,3 +7,6 @@ A semicolon-separated list specifying the rpath to use in installed targets (for platforms that support it). This property is initialized by the value of the variable :variable:`CMAKE_INSTALL_RPATH` if it is set when a target is created. + +This property supports +:manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/prop_tgt/INTERFACE_PRECOMPILE_HEADERS.rst b/Help/prop_tgt/INTERFACE_PRECOMPILE_HEADERS.rst new file mode 100644 index 0000000..e285407 --- /dev/null +++ b/Help/prop_tgt/INTERFACE_PRECOMPILE_HEADERS.rst @@ -0,0 +1,16 @@ +INTERFACE_PRECOMPILE_HEADERS +---------------------------- + +List of interface header files to precompile into consuming targets. + +Targets may populate this property to publish the header files +for consuming targets to precompile. The :command:`target_precompile_headers` +command populates this property with values given to the ``PUBLIC`` and +``INTERFACE`` keywords. Projects may also get and set the property directly. +See the discussion in :command:`target_precompile_headers` for guidance on +appropriate use of this property for installed or exported targets. + +Contents of ``INTERFACE_PRECOMPILE_HEADERS`` may use "generator expressions" +with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` +manual for available expressions. See the :manual:`cmake-buildsystem(7)` +manual for more on defining buildsystem properties. diff --git a/Help/prop_tgt/OBJCXX_EXTENSIONS.rst b/Help/prop_tgt/OBJCXX_EXTENSIONS.rst new file mode 100644 index 0000000..9f9d804 --- /dev/null +++ b/Help/prop_tgt/OBJCXX_EXTENSIONS.rst @@ -0,0 +1,20 @@ +OBJCXX_EXTENSIONS +----------------- + +Boolean specifying whether compiler specific extensions are requested. + +This property specifies whether compiler specific extensions should be +used. For some compilers, this results in adding a flag such +as ``-std=gnu++11`` instead of ``-std=c++11`` to the compile line. This +property is ``ON`` by default. The basic ObjC++ standard level is +controlled by the :prop_tgt:`OBJCXX_STANDARD` target property. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. + +If the property is not set, and the project has set the :prop_tgt:`CXX_EXTENSIONS`, +the value of :prop_tgt:`CXX_EXTENSIONS` is set for :prop_tgt:`OBJCXX_EXTENSIONS`. + +This property is initialized by the value of +the :variable:`CMAKE_OBJCXX_EXTENSIONS` variable if it is set when a target +is created. diff --git a/Help/prop_tgt/OBJCXX_STANDARD.rst b/Help/prop_tgt/OBJCXX_STANDARD.rst new file mode 100644 index 0000000..3c925dc --- /dev/null +++ b/Help/prop_tgt/OBJCXX_STANDARD.rst @@ -0,0 +1,35 @@ +OBJCXX_STANDARD +--------------- + +The ObjC++ standard whose features are requested to build this target. + +This property specifies the ObjC++ standard whose features are requested +to build this target. For some compilers, this results in adding a +flag such as ``-std=gnu++11`` to the compile line. + +Supported values are ``98``, ``11``, ``14``, ``17``, and ``20``. + +If the value requested does not result in a compile flag being added for +the compiler in use, a previous standard flag will be added instead. This +means that using: + +.. code-block:: cmake + + set_property(TARGET tgt PROPERTY OBJCXX_STANDARD 11) + +with a compiler which does not support ``-std=gnu++11`` or an equivalent +flag will not result in an error or warning, but will instead add the +``-std=gnu++98`` flag if supported. This "decay" behavior may be controlled +with the :prop_tgt:`OBJCXX_STANDARD_REQUIRED` target property. +Additionally, the :prop_tgt:`OBJCXX_EXTENSIONS` target property may be used to +control whether compiler-specific extensions are enabled on a per-target basis. + +If the property is not set, and the project has set the :prop_tgt:`CXX_STANDARD`, +the value of :prop_tgt:`CXX_STANDARD` is set for :prop_tgt:`OBJCXX_STANDARD`. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. + +This property is initialized by the value of +the :variable:`CMAKE_OBJCXX_STANDARD` variable if it is set when a target +is created. diff --git a/Help/prop_tgt/OBJCXX_STANDARD_REQUIRED.rst b/Help/prop_tgt/OBJCXX_STANDARD_REQUIRED.rst new file mode 100644 index 0000000..c330abf --- /dev/null +++ b/Help/prop_tgt/OBJCXX_STANDARD_REQUIRED.rst @@ -0,0 +1,20 @@ +OBJCXX_STANDARD_REQUIRED +------------------------ + +Boolean describing whether the value of :prop_tgt:`OBJCXX_STANDARD` is a requirement. + +If this property is set to ``ON``, then the value of the +:prop_tgt:`OBJCXX_STANDARD` target property is treated as a requirement. If this +property is ``OFF`` or unset, the :prop_tgt:`OBJCXX_STANDARD` target property is +treated as optional and may "decay" to a previous standard if the requested is +not available. + +If the property is not set, and the project has set the :prop_tgt:`CXX_STANDARD_REQUIRED`, +the value of :prop_tgt:`CXX_STANDARD_REQUIRED` is set for :prop_tgt:`OBJCXX_STANDARD_REQUIRED`. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. + +This property is initialized by the value of +the :variable:`CMAKE_OBJCXX_STANDARD_REQUIRED` variable if it is set when a +target is created. diff --git a/Help/prop_tgt/OBJC_EXTENSIONS.rst b/Help/prop_tgt/OBJC_EXTENSIONS.rst new file mode 100644 index 0000000..2de9e48 --- /dev/null +++ b/Help/prop_tgt/OBJC_EXTENSIONS.rst @@ -0,0 +1,20 @@ +OBJC_EXTENSIONS +--------------- + +Boolean specifying whether compiler specific extensions are requested. + +This property specifies whether compiler specific extensions should be +used. For some compilers, this results in adding a flag such +as ``-std=gnu11`` instead of ``-std=c11`` to the compile line. This +property is ``ON`` by default. The basic OBJC standard level is +controlled by the :prop_tgt:`OBJC_STANDARD` target property. + +If the property is not set, and the project has set the :prop_tgt:`C_EXTENSIONS`, +the value of :prop_tgt:`C_EXTENSIONS` is set for :prop_tgt:`OBJC_EXTENSIONS`. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. + +This property is initialized by the value of +the :variable:`CMAKE_OBJC_EXTENSIONS` variable if it is set when a target +is created. diff --git a/Help/prop_tgt/OBJC_STANDARD.rst b/Help/prop_tgt/OBJC_STANDARD.rst new file mode 100644 index 0000000..d1e1b24 --- /dev/null +++ b/Help/prop_tgt/OBJC_STANDARD.rst @@ -0,0 +1,35 @@ +OBJC_STANDARD +------------- + +The OBJC standard whose features are requested to build this target. + +This property specifies the OBJC standard whose features are requested +to build this target. For some compilers, this results in adding a +flag such as ``-std=gnu11`` to the compile line. + +Supported values are ``90``, ``99`` and ``11``. + +If the value requested does not result in a compile flag being added for +the compiler in use, a previous standard flag will be added instead. This +means that using: + +.. code-block:: cmake + + set_property(TARGET tgt PROPERTY OBJC_STANDARD 11) + +with a compiler which does not support ``-std=gnu11`` or an equivalent +flag will not result in an error or warning, but will instead add the +``-std=gnu99`` or ``-std=gnu90`` flag if supported. This "decay" behavior may +be controlled with the :prop_tgt:`OBJC_STANDARD_REQUIRED` target property. +Additionally, the :prop_tgt:`OBJC_EXTENSIONS` target property may be used to +control whether compiler-specific extensions are enabled on a per-target basis. + +If the property is not set, and the project has set the :prop_tgt:`C_STANDARD`, +the value of :prop_tgt:`C_STANDARD` is set for :prop_tgt:`OBJC_STANDARD`. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. + +This property is initialized by the value of +the :variable:`CMAKE_OBJC_STANDARD` variable if it is set when a target +is created. diff --git a/Help/prop_tgt/OBJC_STANDARD_REQUIRED.rst b/Help/prop_tgt/OBJC_STANDARD_REQUIRED.rst new file mode 100644 index 0000000..8cf377c --- /dev/null +++ b/Help/prop_tgt/OBJC_STANDARD_REQUIRED.rst @@ -0,0 +1,20 @@ +OBJC_STANDARD_REQUIRED +---------------------- + +Boolean describing whether the value of :prop_tgt:`OBJC_STANDARD` is a requirement. + +If this property is set to ``ON``, then the value of the +:prop_tgt:`OBJC_STANDARD` target property is treated as a requirement. If this +property is ``OFF`` or unset, the :prop_tgt:`OBJC_STANDARD` target property is +treated as optional and may "decay" to a previous standard if the requested is +not available. + +If the property is not set, and the project has set the :prop_tgt:`C_STANDARD_REQUIRED`, +the value of :prop_tgt:`C_STANDARD_REQUIRED` is set for :prop_tgt:`OBJC_STANDARD_REQUIRED`. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. + +This property is initialized by the value of +the :variable:`CMAKE_OBJC_STANDARD_REQUIRED` variable if it is set when a +target is created. diff --git a/Help/prop_tgt/PRECOMPILE_HEADERS.rst b/Help/prop_tgt/PRECOMPILE_HEADERS.rst new file mode 100644 index 0000000..9e70b65 --- /dev/null +++ b/Help/prop_tgt/PRECOMPILE_HEADERS.rst @@ -0,0 +1,12 @@ +PRECOMPILE_HEADERS +------------------ + +List of header files to precompile. + +This property holds a :ref:`semicolon-separated list <CMake Language Lists>` +of header files to precompile specified so far for its target. +Use the :command:`target_precompile_headers` command to append more header +files. + +This property supports +:manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/prop_tgt/PRECOMPILE_HEADERS_REUSE_FROM.rst b/Help/prop_tgt/PRECOMPILE_HEADERS_REUSE_FROM.rst new file mode 100644 index 0000000..9c3e7ea --- /dev/null +++ b/Help/prop_tgt/PRECOMPILE_HEADERS_REUSE_FROM.rst @@ -0,0 +1,7 @@ +PRECOMPILE_HEADERS_REUSE_FROM +----------------------------- + +Target from which to reuse the precompiled headers build artifact. + +See the second signature of :command:`target_precompile_headers` command +for more detailed information. diff --git a/Help/prop_tgt/Swift_LANGUAGE_VERSION.rst b/Help/prop_tgt/Swift_LANGUAGE_VERSION.rst new file mode 100644 index 0000000..7579447 --- /dev/null +++ b/Help/prop_tgt/Swift_LANGUAGE_VERSION.rst @@ -0,0 +1,6 @@ +Swift_LANGUAGE_VERSION +---------------------- + +This property sets the language version for the Swift sources in the target. If +one is not specified, it will default to ``<CMAKE_Swift_LANGUAGE_VERSION>`` if +specified, otherwise it is the latest version supported by the compiler. diff --git a/Help/prop_tgt/UNITY_BUILD.rst b/Help/prop_tgt/UNITY_BUILD.rst new file mode 100644 index 0000000..479802e --- /dev/null +++ b/Help/prop_tgt/UNITY_BUILD.rst @@ -0,0 +1,60 @@ +UNITY_BUILD +----------- + +When this property is set to true, the target source files will be combined +into batches for faster compilation. This is done by creating a (set of) +unity sources which ``#include`` the original sources, then compiling these +unity sources instead of the originals. This is known as a *Unity* or *Jumbo* +build. The :prop_tgt:`UNITY_BUILD_BATCH_SIZE` property controls the upper +limit on how many sources can be combined per unity source file. + +Unity builds are not currently supported for all languages. CMake version +|release| supports combining ``C`` and ``CXX`` source files. For targets that +mix source files from more than one language, CMake will separate the languages +such that each generated unity source file only contains sources for a single +language. + +This property is initialized by the value of the :variable:`CMAKE_UNITY_BUILD` +variable when a target is created. + +.. note:: + + Projects should not directly set the ``UNITY_BUILD`` property or its + associated :variable:`CMAKE_UNITY_BUILD` variable to true. Depending + on the capabilities of the build machine and compiler used, it might or + might not be appropriate to enable unity builds. Therefore, this feature + should be under developer control, which would normally be through the + developer choosing whether or not to set the :variable:`CMAKE_UNITY_BUILD` + variable on the :manual:`cmake(1)` command line or some other equivalent + method. However, it IS recommended to set the ``UNITY_BUILD`` target + property to false if it is known that enabling unity builds for the + target can lead to problems. + +ODR (One definition rule) errors +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When multiple source files are included into one source file, as is done +for unity builds, it can potentially lead to ODR errors. CMake provides +a number of measures to help address such problems: + +* Any source file that has a non-empty :prop_sf:`COMPILE_OPTIONS`, + :prop_sf:`COMPILE_DEFINITIONS`, :prop_sf:`COMPILE_FLAGS`, or + :prop_sf:`INCLUDE_DIRECTORIES` source property will not be combined + into a unity source. + +* Projects can prevent an individual source file from being combined into + a unity source by setting its :prop_sf:`SKIP_UNITY_BUILD_INCLUSION` + source property to true. This can be a more effective way to prevent + problems with specific files than disabling unity builds for an entire + target. + +* The :prop_tgt:`UNITY_BUILD_CODE_BEFORE_INCLUDE` and + :prop_tgt:`UNITY_BUILD_CODE_AFTER_INCLUDE` target properties can be used + to inject code into the unity source files before and after every + ``#include`` statement. + +* The order of source files added to the target via commands like + :command:`add_library`, :command:`add_executable` or + :command:`target_sources` will be preserved in the generated unity source + files. This can be used to manually enforce a specific grouping based on + the :prop_tgt:`UNITY_BUILD_BATCH_SIZE` target property. diff --git a/Help/prop_tgt/UNITY_BUILD_BATCH_SIZE.rst b/Help/prop_tgt/UNITY_BUILD_BATCH_SIZE.rst new file mode 100644 index 0000000..44ffe27 --- /dev/null +++ b/Help/prop_tgt/UNITY_BUILD_BATCH_SIZE.rst @@ -0,0 +1,23 @@ +UNITY_BUILD_BATCH_SIZE +---------------------- + +Specifies the maximum number of source files that can be combined into any one +unity source file when unity builds are enabled by the :prop_tgt:`UNITY_BUILD` +target property. The original source files will be distributed across as many +unity source files as necessary to honor this limit. + +The initial value for this property is taken from the +:variable:`CMAKE_UNITY_BUILD_BATCH_SIZE` variable when the target is created. +If that variable has not been set, the initial value will be 8. + +The batch size needs to be selected carefully. If set too high, the size of +the combined source files could result in the compiler using excessive memory +or hitting other similar limits. In extreme cases, this can even result in +build failure. On the other hand, if the batch size is too low, there will be +little gain in build performance. + +Although strongly discouraged, the batch size may be set to a value of 0 to +combine all the sources for the target into a single unity file, regardless of +how many sources are involved. This runs the risk of creating an excessively +large unity source file and negatively impacting the build performance, so +a value of 0 is not generally recommended. diff --git a/Help/prop_tgt/UNITY_BUILD_CODE_AFTER_INCLUDE.rst b/Help/prop_tgt/UNITY_BUILD_CODE_AFTER_INCLUDE.rst new file mode 100644 index 0000000..7231b61 --- /dev/null +++ b/Help/prop_tgt/UNITY_BUILD_CODE_AFTER_INCLUDE.rst @@ -0,0 +1,19 @@ +UNITY_BUILD_CODE_AFTER_INCLUDE +------------------------------ + +Code snippet which is included verbatim by the :prop_tgt:`UNITY_BUILD` +feature just after every ``#include`` statement in the generated unity +source files. For example: + +.. code-block:: cmake + + set(after [[ + #if defined(NOMINMAX) + #undef NOMINMAX + #endif + ]]) + set_target_properties(myTarget PROPERTIES + UNITY_BUILD_CODE_AFTER_INCLUDE "${after}" + ) + +See also :prop_tgt:`UNITY_BUILD_CODE_BEFORE_INCLUDE`. diff --git a/Help/prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE.rst b/Help/prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE.rst new file mode 100644 index 0000000..7ed6fa1 --- /dev/null +++ b/Help/prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE.rst @@ -0,0 +1,19 @@ +UNITY_BUILD_CODE_BEFORE_INCLUDE +------------------------------- + +Code snippet which is included verbatim by the :prop_tgt:`UNITY_BUILD` +feature just before every ``#include`` statement in the generated unity +source files. For example: + +.. code-block:: cmake + + set(before [[ + #if !defined(NOMINMAX) + #define NOMINMAX + #endif + ]]) + set_target_properties(myTarget PROPERTIES + UNITY_BUILD_CODE_BEFORE_INCLUDE "${before}" + ) + +See also :prop_tgt:`UNITY_BUILD_CODE_AFTER_INCLUDE`. diff --git a/Help/prop_tgt/VS_CONFIGURATION_TYPE.rst b/Help/prop_tgt/VS_CONFIGURATION_TYPE.rst index ff987ff..640bed5 100644 --- a/Help/prop_tgt/VS_CONFIGURATION_TYPE.rst +++ b/Help/prop_tgt/VS_CONFIGURATION_TYPE.rst @@ -4,6 +4,8 @@ VS_CONFIGURATION_TYPE Visual Studio project configuration type. Sets the ``ConfigurationType`` attribute for a generated Visual Studio project. +The property value may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. If this property is set, it overrides the default setting that is based on the target type (e.g. ``StaticLibrary``, ``Application``, ...). diff --git a/Help/prop_tgt/VS_DPI_AWARE.rst b/Help/prop_tgt/VS_DPI_AWARE.rst new file mode 100644 index 0000000..82640cc --- /dev/null +++ b/Help/prop_tgt/VS_DPI_AWARE.rst @@ -0,0 +1,14 @@ +VS_DPI_AWARE +------------ + +Set the Manifest Tool -> Input and Output -> DPI Awareness in the Visual Studio +target project properties. + +Valid values are ``PerMonitor``, ``ON``, or ``OFF``. + +For example: + +.. code-block:: cmake + + add_executable(myproject myproject.cpp) + set_property(TARGET myproject PROPERTY VS_DPI_AWARE "PerMonitor") diff --git a/Help/prop_tgt/XCODE_GENERATE_SCHEME.rst b/Help/prop_tgt/XCODE_GENERATE_SCHEME.rst index 0adb5db..0e182cf 100644 --- a/Help/prop_tgt/XCODE_GENERATE_SCHEME.rst +++ b/Help/prop_tgt/XCODE_GENERATE_SCHEME.rst @@ -31,9 +31,10 @@ at target creation time. - :prop_tgt:`XCODE_SCHEME_ZOMBIE_OBJECTS` The following target properties will be applied on the -"Info" and "Arguments" tab: +"Info", "Arguments", and "Options" tab: - :prop_tgt:`XCODE_SCHEME_ARGUMENTS` - :prop_tgt:`XCODE_SCHEME_DEBUG_AS_ROOT` +- :prop_tgt:`XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING` - :prop_tgt:`XCODE_SCHEME_ENVIRONMENT` - :prop_tgt:`XCODE_SCHEME_EXECUTABLE` diff --git a/Help/prop_tgt/XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING.rst b/Help/prop_tgt/XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING.rst new file mode 100644 index 0000000..9afeedd --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING.rst @@ -0,0 +1,13 @@ +XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING +-------------------------------------- + +Whether to enable +``Allow debugging when using document Versions Browser`` +in the Options section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING` +if it is set when a target is created. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/release/3.16.rst b/Help/release/3.16.rst new file mode 100644 index 0000000..0d1cc1e --- /dev/null +++ b/Help/release/3.16.rst @@ -0,0 +1,279 @@ +CMake 3.16 Release Notes +************************ + +.. only:: html + + .. contents:: + +Changes made since CMake 3.15 include the following. + +New Features +============ + +Languages +--------- + +* CMake learned to support the Objective C (``OBJC``) and Objective C++ + (``OBJCXX``) languages. They may be enabled via the :command:`project` + and :command:`enable_language` commands. When ``OBJC`` or ``OBJCXX`` + is enabled, source files with the ``.m`` or ``.mm``, respectively, + will be compiled as Objective C or C++. Otherwise they will be treated + as plain C++ sources as they were before. + +Compilers +--------- + +* The ``Clang`` compiler is now supported on ``Solaris``. + +Platforms +--------- + +* On AIX, executables using the :prop_tgt:`ENABLE_EXPORTS` target property + now produce a linker import file with a ``.imp`` extension in addition + to the executable file. Plugins (created via :command:`add_library` with + the ``MODULE`` option) that use :command:`target_link_libraries` to link + to the executable for its symbols are now linked using the import file. + The :command:`install(TARGETS)` command now installs the import file as + an ``ARCHIVE`` artifact. + +* On AIX, runtime linking is no longer enabled by default. CMake provides + the linker enough information to resolve all symbols up front. + One may manually enable runtime linking for shared libraries and/or + loadable modules by adding ``-Wl,-G`` to their link flags + (e.g. in the :variable:`CMAKE_SHARED_LINKER_FLAGS` or + :variable:`CMAKE_MODULE_LINKER_FLAGS` variable). + One may manually enable runtime linking for executables by adding + ``-Wl,-brtl`` to their link flags (e.g. in the + :variable:`CMAKE_EXE_LINKER_FLAGS` variable). + +Command-Line +------------ + +* :manual:`cmake(1)` ``-E`` now supports ``true`` and ``false`` commands, + which do nothing while returning exit codes of 0 and 1, respectively. + +* :manual:`cmake(1)` gained a ``--trace-redirect=<file>`` command line + option that can be used to redirect ``--trace`` output to a file instead + of ``stderr``. + +* The :manual:`cmake(1)` ``--loglevel`` command line option has been + renamed to ``--log-level`` to make it consistent with the naming of other + command line options. The ``--loglevel`` option is still supported to + preserve backward compatibility. + +Commands +-------- + +* The :command:`add_test` command learned the option ``COMMAND_EXPAND_LISTS`` + which causes lists in the ``COMMAND`` argument to be expanded, including + lists created by generator expressions. + +* The :command:`file` command learned a new sub-command, + ``GET_RUNTIME_DEPENDENCIES``, which allows you to recursively get the list of + libraries linked by an executable or library. This sub-command is intended as + a replacement for :module:`GetPrerequisites`. + +* The :command:`find_file`, :command:`find_library`, :command:`find_path`, + :command:`find_package`, and :command:`find_program` commands have learned to + check the following variables to control the default behavior for groups of + search locations: + + * :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` - Controls the default + behavior of searching the :variable:`<PackageName>_ROOT` variables. + + * :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` - Controls the default + behavior of searching the CMake-specific environment variables. + + * :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH` - Controls the default + behavior of searching the standard system environment variables. + + * :variable:`CMAKE_FIND_USE_CMAKE_PATH` - Controls the default behavior of + searching the CMake-specific cache variables. + + * :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH` - Controls the default + behavior of searching the platform-specific CMake variables. + +* The :command:`find_package` command has learned to check the + :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` variable to control the default + behavior of searching the CMake user package registry and to check the + :variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY` variable to control + the default behavior of searching the CMake system package registry. + +* The :command:`message` command learned indentation control with the new + :variable:`CMAKE_MESSAGE_INDENT` variable. + +* The :command:`target_precompile_headers` command was added to specify + a list of headers to precompile for faster compilation times. + +Variables +--------- + +* The :variable:`CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS` variable has been + introduced to optionally initialize the + :prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` target property. + +* The :variable:`CMAKE_ECLIPSE_RESOURCE_ENCODING` variable was added to + specify the resource encoding for the the :generator:`Eclipse CDT4` extra + generator. + +* The :variable:`CMAKE_UNITY_BUILD` variable was added to initialize the + :prop_tgt:`UNITY_BUILD` target property to tell generators to batch + include source files for faster compilation times. + +Properties +---------- + +* The :prop_tgt:`BUILD_RPATH` and :prop_tgt:`INSTALL_RPATH` target properties + now support :manual:`generator expressions <cmake-generator-expressions(7)>`. + +* The :prop_tgt:`INSTALL_REMOVE_ENVIRONMENT_RPATH` target property was + added to remove compiler-defined ``RPATH`` entries from a target. + This property is initialized by the + :variable:`CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH` variable. + +* The :prop_tgt:`PRECOMPILE_HEADERS` target property was added to specify + a list of headers to precompile for faster compilation times. + Set it using the :command:`target_precompile_headers` command. + +* The :prop_tgt:`UNITY_BUILD` target property was added to tell + generators to batch include source files for faster compilation + times. + +* The :prop_tgt:`VS_CONFIGURATION_TYPE` target property now supports + :manual:`generator expressions <cmake-generator-expressions(7)>`. + +* The :prop_tgt:`VS_DPI_AWARE` target property was added to tell + :ref:`Visual Studio Generators` to set the ``EnableDpiAwareness`` + property in ``.vcxproj`` files. + +* The :prop_tgt:`XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING` target property was + added to tell the :generator:`Xcode` generator to set the value of the + ``Allow debugging when using document Versions Browser`` schema option. + +Modules +------- + +* The :module:`FindDoxygen` module :command:`doxygen_add_docs` command + gained a new ``USE_STAMP_FILE`` option. When this option present, + the custom target created by the command will only re-run Doxygen if + any of the source files have changed since the last successful run. + +* The :module:`FindGnuTLS` module now provides an imported target. + +* The :module:`FindPackageHandleStandardArgs` module + :command:`find_package_handle_standard_args` command gained + a new ``REASON_FAILURE_MESSAGE`` option to specify a message + giving the reason for the failure. + +* The :module:`FindPkgConfig` module :command:`pkg_search_module` macro + now defines a ``<prefix>_MODULE_NAME`` result variable containing the + first matching module name. + +* The :module:`FindPython3` and :module:`FindPython` modules gained + options to control which ``ABIs`` will be searched. + +* The :module:`FindPython3`, :module:`FindPython2`, and :module:`FindPython` + modules now support direct specification of artifacts via cache entries. + +Autogen +------- + +* When using :prop_tgt:`AUTOMOC`, CMake now generates the ``-p`` path prefix + option for ``moc``. This ensures that ``moc`` output files are identical + on different build setups (given, that the headers compiled by ``moc`` are + in an :command:`include directory <target_include_directories>`). + Also it ensures that ``moc`` output files will compile correctly when the + source and/or build directory is a symbolic link. + + The ``moc`` path prefix generation behavior can be configured by setting + the new :variable:`CMAKE_AUTOMOC_PATH_PREFIX` variable and/or + :prop_tgt:`AUTOMOC_PATH_PREFIX` target property. + +CTest +----- + +* :manual:`ctest(1)` now has the ability to schedule tests based on resource + requirements for each test. See :ref:`ctest-resource-allocation` for + details. + +* A new test property, :prop_test:`SKIP_REGULAR_EXPRESSION`, has been added. + This property is similar to :prop_test:`FAIL_REGULAR_EXPRESSION` and + :prop_test:`PASS_REGULAR_EXPRESSION`, but with the same meaning as + :prop_test:`SKIP_RETURN_CODE`. This is useful, for example, in cases where + the user has no control over the return code of the test. For example, in + Catch2, the return value is the number of assertion failed, therefore it is + impossible to use it for :prop_test:`SKIP_RETURN_CODE`. + +CPack +----- + +* :manual:`cpack(1)` learned support for multiple configurations for ``-C`` + option. + +* The :cpack_gen:`CPack DEB Generator` is now able to format generic text + (usually used as the description for multiple CPack generators) according + to the `Debian Policy Manual`_. See the + :variable:`CPACK_PACKAGE_DESCRIPTION_FILE` and + :variable:`CPACK_DEBIAN_<COMPONENT>_DESCRIPTION` variables. + +* The :cpack_gen:`CPack Archive Generator` learned to generate ``.tar.zst`` + packages with Zstandard compression. + +.. _`Debian Policy Manual`: https://www.debian.org/doc/debian-policy/ch-controlfields.html#description + +Deprecated and Removed Features +=============================== + +* An explicit deprecation diagnostic was added for policy ``CMP0067`` + (``CMP0066`` and below were already deprecated). + The :manual:`cmake-policies(7)` manual explains that the OLD behaviors + of all policies are deprecated and that projects should port to the + NEW behaviors. + +* The :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` variable has been + deprecated. Use the :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` variable + instead. + +* The :module:`GetPrerequisites` module has been deprecated, as it has been + superceded by :command:`file(GET_RUNTIME_DEPENDENCIES)`. + +* The ``CPACK_INSTALL_SCRIPT`` variable has been deprecated in favor of the + new, more accurately named :variable:`CPACK_INSTALL_SCRIPTS` variable. + +Other Changes +============= + +* The :manual:`cmake(1)` ``-C <initial-cache>`` option now evaluates the + initial cache script with :variable:`CMAKE_SOURCE_DIR` and + :variable:`CMAKE_BINARY_DIR` set to the top-level source and build trees. + +* The :manual:`cmake(1)` ``-E remove_directory`` command-line tool, + when given the path to a symlink to a directory, now removes just + the symlink. It no longer removes content of the linked directory. + +* The :manual:`ctest(1)` ``--build-makeprogram`` command-line option now + specifies the make program used when configuring a project with the + :generator:`Ninja` generator or the :ref:`Makefile Generators`. + +* The :module:`ExternalProject` module :command:`ExternalProject_Add` command + has been updated so that ``GIT_SUBMODULES ""`` initializes no submodules. + See policy :policy:`CMP0097`. + +* The :module:`FindGTest` module has been updated to recognize + MSVC build trees generated by GTest 1.8.1. + +* The :command:`project` command no longer strips leading zeros in version + components. See policy :policy:`CMP0096`. + +* The Qt Compressed Help file is now named ``CMake.qch``, which no longer + contains the release version in the file name. When CMake is upgraded + in-place, the name and location of this file will remain constant. + Tools such as IDEs, help viewers, etc. should now be able to refer to this + file at a fixed location that remains valid across CMake upgrades. + +* ``RPATH`` entries are properly escaped in the generated CMake scripts + used for installation. See policy :policy:`CMP0095`. + +* When using :variable:`CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS` on Windows the + auto-generated exports are now updated only when the object files + providing the symbols are updated. diff --git a/Help/release/index.rst b/Help/release/index.rst index 35a47aa..0cc3f97 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -13,6 +13,7 @@ Releases .. toctree:: :maxdepth: 1 + 3.16 <3.16> 3.15 <3.15> 3.14 <3.14> 3.13 <3.13> diff --git a/Help/variable/CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION.rst b/Help/variable/CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION.rst index 5ae55d1..22808e3 100644 --- a/Help/variable/CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION.rst +++ b/Help/variable/CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION.rst @@ -3,7 +3,11 @@ CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION When :ref:`Cross Compiling for Android with the NDK`, this variable may be set to specify the version of the toolchain to be used -as the compiler. The variable must be set to one of these forms: +as the compiler. + +On NDK r19 or above, this variable must be unset or set to ``clang``. + +On NDK r18 or below, this variable must be set to one of these forms: * ``<major>.<minor>``: GCC of specified version * ``clang<major>.<minor>``: Clang of specified version diff --git a/Help/variable/CMAKE_AUTOMOC_PATH_PREFIX.rst b/Help/variable/CMAKE_AUTOMOC_PATH_PREFIX.rst new file mode 100644 index 0000000..dca0b06 --- /dev/null +++ b/Help/variable/CMAKE_AUTOMOC_PATH_PREFIX.rst @@ -0,0 +1,11 @@ +CMAKE_AUTOMOC_PATH_PREFIX +------------------------- + +Whether to generate the ``-p`` path prefix option for ``moc`` on +:prop_tgt:`AUTOMOC` enabled Qt targets. + +This variable is used to initialize the :prop_tgt:`AUTOMOC_PATH_PREFIX` +property on all the targets. See that target property for additional +information. + +The default value is ``ON``. diff --git a/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst b/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst index eea2c4f..6d34c5c 100644 --- a/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst +++ b/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst @@ -4,4 +4,5 @@ CMAKE_CUDA_HOST_COMPILER Executable to use when compiling host code when compiling ``CUDA`` language files. Maps to the ``nvcc -ccbin`` option. Will only be used by CMake on the first configuration to determine a valid host compiler for ``CUDA``. After a valid -host compiler has been found, this value is read-only. +host compiler has been found, this value is read-only. This variable takes +priority over the :envvar:`CUDAHOSTCXX` environment variable. diff --git a/Help/variable/CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS.rst b/Help/variable/CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS.rst new file mode 100644 index 0000000..fc835cd --- /dev/null +++ b/Help/variable/CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS.rst @@ -0,0 +1,6 @@ +CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS +--------------------------------- + +Default value for :prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` target +property. This variable is used to initialize the property on each target as +it is created. diff --git a/Help/variable/CMAKE_DISABLE_PRECOMPILE_HEADERS.rst b/Help/variable/CMAKE_DISABLE_PRECOMPILE_HEADERS.rst new file mode 100644 index 0000000..7c30ede --- /dev/null +++ b/Help/variable/CMAKE_DISABLE_PRECOMPILE_HEADERS.rst @@ -0,0 +1,6 @@ +CMAKE_DISABLE_PRECOMPILE_HEADERS +-------------------------------- + +Default value for :prop_tgt:`DISABLE_PRECOMPILE_HEADERS` of targets. + +By default ``CMAKE_DISABLE_PRECOMPILE_HEADERS`` is ``OFF``. diff --git a/Help/variable/CMAKE_ECLIPSE_RESOURCE_ENCODING.rst b/Help/variable/CMAKE_ECLIPSE_RESOURCE_ENCODING.rst new file mode 100644 index 0000000..314efe5 --- /dev/null +++ b/Help/variable/CMAKE_ECLIPSE_RESOURCE_ENCODING.rst @@ -0,0 +1,6 @@ +CMAKE_ECLIPSE_RESOURCE_ENCODING +------------------------------- + +This cache variable tells the :generator:`Eclipse CDT4` project generator +to set the resource encoding to the given value in generated project files. +If no value is given, no encoding will be set. diff --git a/Help/variable/CMAKE_ENABLE_EXPORTS.rst b/Help/variable/CMAKE_ENABLE_EXPORTS.rst index 7ec4d63..8848da1 100644 --- a/Help/variable/CMAKE_ENABLE_EXPORTS.rst +++ b/Help/variable/CMAKE_ENABLE_EXPORTS.rst @@ -1,22 +1,8 @@ CMAKE_ENABLE_EXPORTS -------------------- -Specify whether an executable exports symbols for loadable modules. +Specify whether executables export symbols for loadable modules. -Normally an executable does not export any symbols because it is the -final program. It is possible for an executable to export symbols to -be used by loadable modules. When this property is set to true CMake -will allow other targets to ``link`` to the executable with the -:command:`TARGET_LINK_LIBRARIES` command. On all platforms a target-level -dependency on the executable is created for targets that link to it. -For DLL platforms an import library will be created for the exported -symbols and then used for linking. All Windows-based systems -including Cygwin are DLL platforms. For non-DLL platforms that -require all symbols to be resolved at link time, such as macOS, the -module will ``link`` to the executable using a flag like -``-bundle_loader``. For other non-DLL platforms the link rule is simply -ignored since the dynamic loader will automatically bind symbols when -the module is loaded. - -This variable is used to initialize the target property -:prop_tgt:`ENABLE_EXPORTS` for executable targets. +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. diff --git a/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst b/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst index 8776279..4548abc 100644 --- a/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst +++ b/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst @@ -28,3 +28,7 @@ form. The format of the JSON file looks like: .. note:: This option is implemented only by :ref:`Makefile Generators` and the :generator:`Ninja`. It is ignored on other generators. + + This option currently does not work well in combination with + the :prop_tgt:`UNITY_BUILD` target property or the + :variable:`CMAKE_UNITY_BUILD` variable. diff --git a/Help/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY.rst index 9058471..4ee9d8b 100644 --- a/Help/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY.rst +++ b/Help/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY.rst @@ -1,12 +1,23 @@ CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY -------------------------------------- -Skip :ref:`User Package Registry` in :command:`find_package` calls. +.. deprecated:: 3.16 + + Use the :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` variable instead. + +By default this variable is not set. If neither +:variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` nor +``CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY`` is set, then +:command:`find_package()` will use the :ref:`User Package Registry` +unless the ``NO_CMAKE_PACKAGE_REGISTRY`` option is provided. + +``CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY`` is ignored if +:variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` is set. In some cases, for example to locate only system wide installations, it is not desirable to use the :ref:`User Package Registry` when searching for packages. If the :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` -variable is enabled, all the :command:`find_package` commands will skip +variable is ``TRUE``, all the :command:`find_package` commands will skip the :ref:`User Package Registry` as if they were called with the ``NO_CMAKE_PACKAGE_REGISTRY`` argument. diff --git a/Help/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY.rst index 44588b1..107c183 100644 --- a/Help/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY.rst +++ b/Help/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY.rst @@ -1,12 +1,23 @@ CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY --------------------------------------------- -Skip :ref:`System Package Registry` in :command:`find_package` calls. +.. deprecated:: 3.16 + + Use the :variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY` variable instead. + +By default this variable is not set. If neither +:variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY` nor +``CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY`` is set, then +:command:`find_package()` will use the :ref:`System Package Registry` +unless the ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` option is provided. + +``CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY`` is ignored if +:variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY` is set. In some cases, it is not desirable to use the :ref:`System Package Registry` when searching for packages. If the :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` variable is -enabled, all the :command:`find_package` commands will skip +``TRUE``, all the :command:`find_package` commands will skip the :ref:`System Package Registry` as if they were called with the ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` argument. diff --git a/Help/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.rst b/Help/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.rst new file mode 100644 index 0000000..957e956 --- /dev/null +++ b/Help/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.rst @@ -0,0 +1,24 @@ +CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH +------------------------------------- + +Controls the default behavior of the following commands for whether or not to +search paths provided by cmake-specific environment variables: + +* :command:`find_program` +* :command:`find_library` +* :command:`find_file` +* :command:`find_path` +* :command:`find_package` + +This is useful in cross-compiling environments. + +By default this variable is not set, which is equivalent to it having +a value of ``TRUE``. Explicit options given to the above commands +take precedence over this variable. + +See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`, +:variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`, +and :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` variables. diff --git a/Help/variable/CMAKE_FIND_USE_CMAKE_PATH.rst b/Help/variable/CMAKE_FIND_USE_CMAKE_PATH.rst new file mode 100644 index 0000000..d2bdb09 --- /dev/null +++ b/Help/variable/CMAKE_FIND_USE_CMAKE_PATH.rst @@ -0,0 +1,24 @@ +CMAKE_FIND_USE_CMAKE_PATH +------------------------- + +Controls the default behavior of the following commands for whether or not to +search paths provided by cmake-specific cache variables: + +* :command:`find_program` +* :command:`find_library` +* :command:`find_file` +* :command:`find_path` +* :command:`find_package` + +This is useful in cross-compiling environments. + +By default this variable is not set, which is equivalent to it having +a value of ``TRUE``. Explicit options given to the above commands +take precedence over this variable. + +See also the :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`, +:variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`, +and :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` variables. diff --git a/Help/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.rst b/Help/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.rst new file mode 100644 index 0000000..b99081d --- /dev/null +++ b/Help/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.rst @@ -0,0 +1,24 @@ +CMAKE_FIND_USE_CMAKE_SYSTEM_PATH +-------------------------------- + +Controls the default behavior of the following commands for whether or not to +search paths provided by platform-specific cmake variables: + +* :command:`find_program` +* :command:`find_library` +* :command:`find_file` +* :command:`find_path` +* :command:`find_package` + +This is useful in cross-compiling environments. + +By default this variable is not set, which is equivalent to it having +a value of ``TRUE``. Explicit options given to the above commands +take precedence over this variable. + +See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`, +:variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`, +and :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` variables. diff --git a/Help/variable/CMAKE_FIND_USE_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_FIND_USE_PACKAGE_REGISTRY.rst new file mode 100644 index 0000000..7c7ca36 --- /dev/null +++ b/Help/variable/CMAKE_FIND_USE_PACKAGE_REGISTRY.rst @@ -0,0 +1,30 @@ +CMAKE_FIND_USE_PACKAGE_REGISTRY +------------------------------- + +Controls the default behavior of the :command:`find_package` command for +whether or not to search paths provided by the :ref:`User Package Registry`. + +By default this variable is not set and the behavior will fall back +to that determined by the deprecated +:variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` variable. If that is +also not set, then :command:`find_package` will use the +:ref:`User Package Registry` unless the ``NO_CMAKE_PACKAGE_REGISTRY`` option +is provided. + +This variable takes precedence over +:variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` when both are set. + +In some cases, for example to locate only system wide installations, it +is not desirable to use the :ref:`User Package Registry` when searching +for packages. If the :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` +variable is ``FALSE``, all the :command:`find_package` commands will skip +the :ref:`User Package Registry` as if they were called with the +``NO_CMAKE_PACKAGE_REGISTRY`` argument. + +See also :ref:`Disabling the Package Registry` and the +:variable:`CMAKE_FIND_USE_CMAKE_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`, +and :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` variables. diff --git a/Help/variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH.rst b/Help/variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH.rst new file mode 100644 index 0000000..e7f5b0f --- /dev/null +++ b/Help/variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH.rst @@ -0,0 +1,22 @@ +CMAKE_FIND_USE_PACKAGE_ROOT_PATH +-------------------------------- + +Controls the default behavior of the following commands for whether or not to +search paths provided by :variable:`<PackageName>_ROOT` variables: + +* :command:`find_program` +* :command:`find_library` +* :command:`find_file` +* :command:`find_path` +* :command:`find_package` + +By default this variable is not set, which is equivalent to it having +a value of ``TRUE``. Explicit options given to the above commands +take precedence over this variable. + +See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`, +and :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` variables. diff --git a/Help/variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.rst b/Help/variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.rst new file mode 100644 index 0000000..fbaba5a --- /dev/null +++ b/Help/variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.rst @@ -0,0 +1,24 @@ +CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH +-------------------------------------- + +Controls the default behavior of the following commands for whether or not to +search paths provided by standard system environment variables: + +* :command:`find_program` +* :command:`find_library` +* :command:`find_file` +* :command:`find_path` +* :command:`find_package` + +This is useful in cross-compiling environments. + +By default this variable is not set, which is equivalent to it having +a value of ``TRUE``. Explicit options given to the above commands +take precedence over this variable. + +See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, +:variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`, +:variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH`, +and :variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY` variables. diff --git a/Help/variable/CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY.rst new file mode 100644 index 0000000..cb4eec5 --- /dev/null +++ b/Help/variable/CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY.rst @@ -0,0 +1,31 @@ +CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY +-------------------------------------- + +Controls searching the :ref:`System Package Registry` by the +:command:`find_package` command. + +By default this variable is not set and the behavior will fall back +to that determined by the deprecated +:variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` variable. +If that is also not set, then :command:`find_package()` will use the +:ref:`System Package Registry` unless the ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` +option is provided. + +This variable takes precedence over +:variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` when both are set. + +In some cases, for example to locate only user specific installations, it +is not desirable to use the :ref:`System Package Registry` when searching +for packages. If the ``CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`` +variable is ``FALSE``, all the :command:`find_package` commands will skip +the :ref:`System Package Registry` as if they were called with the +``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` argument. + +See also :ref:`Disabling the Package Registry`. + +See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`, +and :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` variables. diff --git a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst index a01a8b7..222824f 100644 --- a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst +++ b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst @@ -40,10 +40,13 @@ The ``key=value`` pairs form a comma-separated list of options to specify generator-specific details of the toolset selection. Supported pairs are: -``cuda=<version>`` - Specify the CUDA toolkit version to use. Supported by VS 2010 - and above with the CUDA toolkit VS integration installed. - See the :variable:`CMAKE_VS_PLATFORM_TOOLSET_CUDA` variable. +``cuda=<version>|<path>`` + Specify the CUDA toolkit version to use or the path to a + standalone CUDA toolkit directory. Supported by VS 2010 + and above. The version can only be used with the CUDA + toolkit VS integration globally installed. + See the :variable:`CMAKE_VS_PLATFORM_TOOLSET_CUDA` and + :variable:`CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR` variables. ``host=<arch>`` Specify the host tools architecture as ``x64`` or ``x86``. diff --git a/Help/variable/CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH.rst b/Help/variable/CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH.rst new file mode 100644 index 0000000..76ca3da --- /dev/null +++ b/Help/variable/CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH.rst @@ -0,0 +1,9 @@ +CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH +-------------------------------------- + +Sets the default for whether toolchain-defined rpaths should be removed during +installation. + +``CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH`` is a boolean that provides the +default value for the :prop_tgt:`INSTALL_REMOVE_ENVIRONMENT_RPATH` property +of all subsequently created targets. diff --git a/Help/variable/CMAKE_LANG_LINK_LIBRARY_FILE_FLAG.rst b/Help/variable/CMAKE_LANG_LINK_LIBRARY_FILE_FLAG.rst new file mode 100644 index 0000000..d54f080 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_LIBRARY_FILE_FLAG.rst @@ -0,0 +1,8 @@ +CMAKE_<LANG>_LINK_LIBRARY_FILE_FLAG +----------------------------------- + +Language-specific flag to be used to link a library specified by +a path to its file. + +The flag will be used before a library file path is given to the +linker. This is needed only on very few platforms. diff --git a/Help/variable/CMAKE_LANG_LINK_LIBRARY_FLAG.rst b/Help/variable/CMAKE_LANG_LINK_LIBRARY_FLAG.rst new file mode 100644 index 0000000..d7bb0d8 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_LIBRARY_FLAG.rst @@ -0,0 +1,7 @@ +CMAKE_<LANG>_LINK_LIBRARY_FLAG +------------------------------ + +Flag to be used to link a library into a shared library or executable. + +This flag will be used to specify a library to link to a shared library or an +executable for the specific language. On most compilers this is ``-l``. diff --git a/Help/variable/CMAKE_LANG_LINK_LIBRARY_SUFFIX.rst b/Help/variable/CMAKE_LANG_LINK_LIBRARY_SUFFIX.rst new file mode 100644 index 0000000..a378657 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_LIBRARY_SUFFIX.rst @@ -0,0 +1,6 @@ +CMAKE_<LANG>_LINK_LIBRARY_SUFFIX +-------------------------------- + +Language-specific suffix for libraries that you link to. + +The suffix to use for the end of a library filename, ``.lib`` on Windows. diff --git a/Help/variable/CMAKE_MESSAGE_INDENT.rst b/Help/variable/CMAKE_MESSAGE_INDENT.rst new file mode 100644 index 0000000..7e44a4c --- /dev/null +++ b/Help/variable/CMAKE_MESSAGE_INDENT.rst @@ -0,0 +1,32 @@ +CMAKE_MESSAGE_INDENT +-------------------- + +The :command:`message` command joins the strings from this list and for +log levels of ``NOTICE`` and below, it prepends the resultant string to +each line of the message. + +Example: + +.. code-block:: cmake + + list(APPEND listVar one two three) + + message(VERBOSE [[Collected items in the "listVar":]]) + list(APPEND CMAKE_MESSAGE_INDENT " ") + + foreach(item IN LISTS listVar) + message(VERBOSE ${item}) + endforeach() + + list(POP_BACK CMAKE_MESSAGE_INDENT) + message(VERBOSE "No more indent") + +Which results in the following output: + +.. code-block:: none + + -- Collected items in the "listVar": + -- one + -- two + -- three + -- No more indent diff --git a/Help/variable/CMAKE_OBJCXX_EXTENSIONS.rst b/Help/variable/CMAKE_OBJCXX_EXTENSIONS.rst new file mode 100644 index 0000000..8afa6f2 --- /dev/null +++ b/Help/variable/CMAKE_OBJCXX_EXTENSIONS.rst @@ -0,0 +1,11 @@ +CMAKE_OBJCXX_EXTENSIONS +----------------------- + +Default value for :prop_tgt:`OBJCXX_EXTENSIONS` property of targets. + +This variable is used to initialize the :prop_tgt:`OBJCXX_EXTENSIONS` +property on all targets. See that target property for additional +information. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_OBJCXX_STANDARD.rst b/Help/variable/CMAKE_OBJCXX_STANDARD.rst new file mode 100644 index 0000000..4e5016a --- /dev/null +++ b/Help/variable/CMAKE_OBJCXX_STANDARD.rst @@ -0,0 +1,11 @@ +CMAKE_OBJCXX_STANDARD +--------------------- + +Default value for :prop_tgt:`OBJCXX_STANDARD` property of targets. + +This variable is used to initialize the :prop_tgt:`OBJCXX_STANDARD` +property on all targets. See that target property for additional +information. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_OBJCXX_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_OBJCXX_STANDARD_REQUIRED.rst new file mode 100644 index 0000000..3a0602a --- /dev/null +++ b/Help/variable/CMAKE_OBJCXX_STANDARD_REQUIRED.rst @@ -0,0 +1,11 @@ +CMAKE_OBJCXX_STANDARD_REQUIRED +------------------------------ + +Default value for :prop_tgt:`OBJCXX_STANDARD_REQUIRED` property of targets. + +This variable is used to initialize the :prop_tgt:`OBJCXX_STANDARD_REQUIRED` +property on all targets. See that target property for additional +information. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_OBJC_EXTENSIONS.rst b/Help/variable/CMAKE_OBJC_EXTENSIONS.rst new file mode 100644 index 0000000..d9619d8 --- /dev/null +++ b/Help/variable/CMAKE_OBJC_EXTENSIONS.rst @@ -0,0 +1,11 @@ +CMAKE_OBJC_EXTENSIONS +--------------------- + +Default value for :prop_tgt:`OBJC_EXTENSIONS` property of targets. + +This variable is used to initialize the :prop_tgt:`OBJC_EXTENSIONS` +property on all targets. See that target property for additional +information. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_OBJC_STANDARD.rst b/Help/variable/CMAKE_OBJC_STANDARD.rst new file mode 100644 index 0000000..976c441 --- /dev/null +++ b/Help/variable/CMAKE_OBJC_STANDARD.rst @@ -0,0 +1,11 @@ +CMAKE_OBJC_STANDARD +------------------- + +Default value for :prop_tgt:`OBJC_STANDARD` property of targets. + +This variable is used to initialize the :prop_tgt:`OBJC_STANDARD` +property on all targets. See that target property for additional +information. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_OBJC_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_OBJC_STANDARD_REQUIRED.rst new file mode 100644 index 0000000..5c02096 --- /dev/null +++ b/Help/variable/CMAKE_OBJC_STANDARD_REQUIRED.rst @@ -0,0 +1,11 @@ +CMAKE_OBJC_STANDARD_REQUIRED +---------------------------- + +Default value for :prop_tgt:`OBJC_STANDARD_REQUIRED` property of targets. + +This variable is used to initialize the :prop_tgt:`OBJC_STANDARD_REQUIRED` +property on all targets. See that target property for additional +information. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_STATIC_LINKER_FLAGS.rst b/Help/variable/CMAKE_STATIC_LINKER_FLAGS.rst index 9c38673..1a810ce 100644 --- a/Help/variable/CMAKE_STATIC_LINKER_FLAGS.rst +++ b/Help/variable/CMAKE_STATIC_LINKER_FLAGS.rst @@ -1,6 +1,12 @@ CMAKE_STATIC_LINKER_FLAGS ------------------------- -Linker flags to be used to create static libraries. +Flags to be used to create static libraries. These flags will be passed +to the archiver when creating a static library. -These flags will be used by the linker when creating a static library. +See also :variable:`CMAKE_STATIC_LINKER_FLAGS_<CONFIG>`. + +.. note:: + Static libraries do not actually link. They are essentially archives + of object files. The use of the name "linker" in the name of this + variable is kept for compatibility. diff --git a/Help/variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG.rst b/Help/variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG.rst index b9f8003..e561dc6 100644 --- a/Help/variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG.rst +++ b/Help/variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG.rst @@ -1,7 +1,13 @@ CMAKE_STATIC_LINKER_FLAGS_<CONFIG> ---------------------------------- -Flags to be used when linking a static library. +Flags to be used to create static libraries. These flags will be passed +to the archiver when creating a static library in the ``<CONFIG>`` +configuration. -Same as ``CMAKE_C_FLAGS_*`` but used by the linker when creating static -libraries. +See also :variable:`CMAKE_STATIC_LINKER_FLAGS`. + +.. note:: + Static libraries do not actually link. They are essentially archives + of object files. The use of the name "linker" in the name of this + variable is kept for compatibility. diff --git a/Help/variable/CMAKE_UNITY_BUILD.rst b/Help/variable/CMAKE_UNITY_BUILD.rst new file mode 100644 index 0000000..a86cd67 --- /dev/null +++ b/Help/variable/CMAKE_UNITY_BUILD.rst @@ -0,0 +1,20 @@ +CMAKE_UNITY_BUILD +----------------- + +This variable is used to initialize the :prop_tgt:`UNITY_BUILD` +property of targets when they are created. Setting it to true +enables batch compilation of multiple sources within each target. +This feature is known as a *Unity* or *Jumbo* build. + +Projects should not set this variable, it is intended as a developer +control to be set on the :manual:`cmake(1)` command line or other +equivalent methods. The developer must have the ability to enable or +disable unity builds according to the capabilities of their own machine +and compiler. + +By default, this variable is not set, which will result in unity builds +being disabled. + +.. note:: + This option currently does not work well in combination with + the :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` variable. diff --git a/Help/variable/CMAKE_UNITY_BUILD_BATCH_SIZE.rst b/Help/variable/CMAKE_UNITY_BUILD_BATCH_SIZE.rst new file mode 100644 index 0000000..7988d4b --- /dev/null +++ b/Help/variable/CMAKE_UNITY_BUILD_BATCH_SIZE.rst @@ -0,0 +1,7 @@ +CMAKE_UNITY_BUILD_BATCH_SIZE +---------------------------- + +This variable is used to initialize the :prop_tgt:`UNITY_BUILD_BATCH_SIZE` +property of targets when they are created. It specifies the default upper +limit on the number of source files that may be combined in any one unity +source file when unity builds are enabled for a target. diff --git a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA.rst b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA.rst index 1604a76..67b7f74 100644 --- a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA.rst +++ b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA.rst @@ -6,7 +6,9 @@ NVIDIA CUDA Toolkit version whose Visual Studio toolset to use. The :ref:`Visual Studio Generators` for VS 2010 and above support using a CUDA toolset provided by a CUDA Toolkit. The toolset version number may be specified by a field in :variable:`CMAKE_GENERATOR_TOOLSET` of -the form ``cuda=8.0``. If none is specified CMake will choose a default -version. CMake provides the selected CUDA toolset version in this variable. +the form ``cuda=8.0``. Or it is automatically detected if a path to +a standalone CUDA directory is specified in the form ``cuda=C:\path\to\cuda``. +If none is specified CMake will choose a default version. +CMake provides the selected CUDA toolset version in this variable. The value may be empty if no CUDA Toolkit with Visual Studio integration is installed. diff --git a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR.rst b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR.rst new file mode 100644 index 0000000..060648a --- /dev/null +++ b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR.rst @@ -0,0 +1,16 @@ +CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR +----------------------------------------- + +Path to standalone NVIDIA CUDA Toolkit (eg. extracted from installer). + +The :ref:`Visual Studio Generators` for VS 2010 and above support using +a standalone (non-installed) NVIDIA CUDA toolkit. The path +may be specified by a field in :variable:`CMAKE_GENERATOR_TOOLSET` of +the form ``cuda=C:\path\to\cuda``. The given directory must at least +contain a folder ``.\nvcc`` and must provide Visual Studio integration +files in path ``.\CUDAVisualStudioIntegration\extras\ +visual_studio_integration\MSBuildExtensions\``. One can create a standalone +CUDA toolkit directory by either opening a installer with 7zip or +copying the files that are extracted by the running installer. +The value may be empty if no path to a standalone CUDA Toolkit was +specified. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING.rst b/Help/variable/CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING.rst new file mode 100644 index 0000000..a264d36 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING.rst @@ -0,0 +1,13 @@ +CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING +-------------------------------------------- + +Whether to enable +``Allow debugging when using document Versions Browser`` +in the Options section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CPACK_INSTALL_SCRIPT.rst b/Help/variable/CPACK_INSTALL_SCRIPT.rst deleted file mode 100644 index 12a48a4..0000000 --- a/Help/variable/CPACK_INSTALL_SCRIPT.rst +++ /dev/null @@ -1,8 +0,0 @@ -CPACK_INSTALL_SCRIPT --------------------- - -Extra CMake script provided by the user. - -If set this CMake script will be executed by CPack during its local -[CPack-private] installation which is done right before packaging the -files. The script is not called by e.g.: ``make install``. |