diff options
Diffstat (limited to 'Help')
60 files changed, 1916 insertions, 254 deletions
diff --git a/Help/command/add_compile_options.rst b/Help/command/add_compile_options.rst index fcdcfd4..43805c3 100644 --- a/Help/command/add_compile_options.rst +++ b/Help/command/add_compile_options.rst @@ -7,15 +7,12 @@ Add options to the compilation of source files. add_compile_options(<option> ...) -Adds options to the compiler command line for targets in the current -directory and below that are added after this command is invoked. -See documentation of the :prop_dir:`directory <COMPILE_OPTIONS>` and -:prop_tgt:`target <COMPILE_OPTIONS>` ``COMPILE_OPTIONS`` properties. +Adds options to the :prop_dir:`COMPILE_OPTIONS` directory property. +These options are used when compiling targets from the current +directory and below. -This command can be used to add any options, but alternative commands -exist to add preprocessor definitions (:command:`target_compile_definitions` -and :command:`add_compile_definitions`) or include directories -(:command:`target_include_directories` and :command:`include_directories`). +Arguments +^^^^^^^^^ Arguments to ``add_compile_options`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` @@ -23,3 +20,29 @@ manual for available expressions. See the :manual:`cmake-buildsystem(7)` manual for more on defining buildsystem properties. .. include:: OPTIONS_SHELL.txt + +Example +^^^^^^^ + +Since different compilers support different options, a typical use of +this command is in a compiler-specific conditional clause: + +.. code-block:: cmake + + if (MSVC) + # warning level 4 and all warnings as errors + add_compile_options(/W4 /WX) + else() + # lots of warnings and all warnings as errors + add_compile_options(-Wall -Wextra -pedantic -Werror) + endif() + +See Also +^^^^^^^^ + +This command can be used to add any options. However, for +adding preprocessor definitions and include directories it is recommended +to use the more specific commands :command:`add_compile_definitions` +and :command:`include_directories`. + +The command :command:`target_compile_options` adds target-specific options. diff --git a/Help/command/ctest_build.rst b/Help/command/ctest_build.rst index 55bb4a3..66e1844 100644 --- a/Help/command/ctest_build.rst +++ b/Help/command/ctest_build.rst @@ -50,9 +50,7 @@ The options are: for an example. ``PROJECT_NAME <project-name>`` - Set the name of the project to build. This should correspond - to the top-level call to the :command:`project` command. - If not specified the ``CTEST_PROJECT_NAME`` variable will be checked. + Ignored. This was once used but is no longer needed. ``TARGET <target-name>`` Specify the name of a target to build. If not specified the diff --git a/Help/command/file.rst b/Help/command/file.rst index f5279c0..6e2a6dd 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -25,6 +25,8 @@ Synopsis file({`REMOVE`_ | `REMOVE_RECURSE`_ } [<files>...]) file(`MAKE_DIRECTORY`_ [<dir>...]) file({`COPY`_ | `INSTALL`_} <file>... DESTINATION <dir> [...]) + file(`SIZE`_ <filename> <out-var>) + file(`READ_SYMLINK`_ <filename> <out-var>) `Path Conversion`_ file(`RELATIVE_PATH`_ <out-var> <directory> <file>) @@ -333,6 +335,39 @@ and ``NO_SOURCE_PERMISSIONS`` is default. Installation scripts generated by the :command:`install` command use this signature (with some undocumented options for internal use). +.. _SIZE: + +.. code-block:: cmake + + file(SIZE <filename> <variable>) + +Determine the file size of the ``<filename>`` and put the result in +``<variable>`` variable. Requires that ``<filename>`` is a valid path +pointing to a file and is readable. + +.. _READ_SYMLINK: + +.. code-block:: cmake + + file(READ_SYMLINK <filename> <variable>) + +Read the symlink at ``<filename>`` and put the result in ``<variable>``. +Requires that ``<filename>`` is a valid path pointing to a symlink. If +``<filename>`` does not exist, or is not a symlink, an error is thrown. + +Note that this command returns the raw symlink path and does not resolve +relative symlinks. If you want to resolve the relative symlink yourself, you +could do something like this: + +.. code-block:: cmake + + set(filename "/path/to/foo.sym") + file(READ_SYMLINK "${filename}" result) + if(NOT IS_ABSOLUTE "${result}") + get_filename_component(dir "${filename}" DIRECTORY) + set(result "${dir}/${result}") + endif() + Path Conversion ^^^^^^^^^^^^^^^ diff --git a/Help/command/get_target_property.rst b/Help/command/get_target_property.rst index cbf4721..4327681 100644 --- a/Help/command/get_target_property.rst +++ b/Help/command/get_target_property.rst @@ -23,3 +23,5 @@ target so far created. The targets do not need to be in the current ``CMakeLists.txt`` file. See also the more general :command:`get_property` command. + +See :ref:`Target Properties` for the list of properties known to CMake. diff --git a/Help/command/install.rst b/Help/command/install.rst index 55c8485..a0e8c37 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -547,6 +547,11 @@ example, the code will print a message during installation. +``<file>`` or ``<code>`` may use "generator expressions" with the syntax +``$<...>`` (in the case of ``<file>``, this refers to their use in the file +name, not the file's contents). See the +:manual:`cmake-generator-expressions(7)` manual for available expressions. + Installing Exports ^^^^^^^^^^^^^^^^^^ diff --git a/Help/command/macro.rst b/Help/command/macro.rst index 42a99fc..05e5d79 100644 --- a/Help/command/macro.rst +++ b/Help/command/macro.rst @@ -76,16 +76,16 @@ Macro vs Function The ``macro`` command is very similar to the :command:`function` command. Nonetheless, there are a few important differences. -In a function, ``ARGC``, ``ARGC`` and ``ARGV0``, ``ARGV1``, ... are -true variables in the usual CMake sense. In a macro, they are not. -They are string replacements much like the C preprocessor would do +In a function, ``ARGN``, ``ARGC``, ``ARGV`` and ``ARGV0``, ``ARGV1``, ... +are true variables in the usual CMake sense. In a macro, they are not, +they are string replacements much like the C preprocessor would do with a macro. This has a number of consequences, as explained in the :ref:`Argument Caveats` section below. Another difference between macros and functions is the control flow. -A function is executed by transfering control from the calling +A function is executed by transferring control from the calling statement to the function body. A macro is executed as if the macro -body were pasted in place of the calling statement. This has for +body were pasted in place of the calling statement. This has the consequence that a :command:`return()` in a macro body does not just terminate execution of the macro; rather, control is returned from the scope of the macro call. To avoid confusion, it is recommended @@ -96,7 +96,7 @@ to avoid :command:`return()` in macros altogether. Argument Caveats ^^^^^^^^^^^^^^^^ -Since ``ARGC``, ``ARGC``, ``ARGV0`` etc are not variables, +Since ``ARGN``, ``ARGC``, ``ARGV``, ``ARGV0`` etc. are not variables, you will NOT be able to use commands like .. code-block:: cmake diff --git a/Help/command/target_compile_options.rst b/Help/command/target_compile_options.rst index c26c926..47e7d86 100644 --- a/Help/command/target_compile_options.rst +++ b/Help/command/target_compile_options.rst @@ -9,22 +9,18 @@ Add compile options to a target. <INTERFACE|PUBLIC|PRIVATE> [items1...] [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) -Specifies compile options to use when compiling a given 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>`. +Adds options to the :prop_tgt:`COMPILE_OPTIONS` or +:prop_tgt:`INTERFACE_COMPILE_OPTIONS` target properties. These options +are used when compiling the given ``<target>``, which 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>`. + +Arguments +^^^^^^^^^ If ``BEFORE`` is specified, the content will be prepended to the property instead of being appended. -This command can be used to add any options, but -alternative commands exist to add preprocessor definitions -(:command:`target_compile_definitions` and :command:`add_compile_definitions`) -or include directories (:command:`target_include_directories` and -:command:`include_directories`). See documentation of the -:prop_dir:`directory <COMPILE_OPTIONS>` and -:prop_tgt:`target <COMPILE_OPTIONS>` ``COMPILE_OPTIONS`` properties. - 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:`COMPILE_OPTIONS` property of @@ -40,3 +36,13 @@ manual for available expressions. See the :manual:`cmake-buildsystem(7)` manual for more on defining buildsystem properties. .. include:: OPTIONS_SHELL.txt + +See Also +^^^^^^^^ + +This command can be used to add any options. However, for adding +preprocessor definitions and include directories it is recommended +to use the more specific commands :command:`target_compile_definitions` +and :command:`target_include_directories`. + +For directory-wide settings, there is the command :command:`add_compile_options`. diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst index 28caa7c..cf9e06f 100644 --- a/Help/command/try_compile.rst +++ b/Help/command/try_compile.rst @@ -33,6 +33,7 @@ Try Compiling Source Files try_compile(RESULT_VAR <bindir> <srcfile|SOURCES srcfile...> [CMAKE_FLAGS <flags>...] [COMPILE_DEFINITIONS <defs>...] + [LINK_OPTIONS <options>...] [LINK_LIBRARIES <libs>...] [OUTPUT_VARIABLE <var>] [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]] @@ -55,6 +56,7 @@ the source(s) as an executable that looks something like this: include_directories(${INCLUDE_DIRECTORIES}) link_directories(${LINK_DIRECTORIES}) add_executable(cmTryCompileExec <srcfile>...) + target_link_options(cmTryCompileExec PRIVATE <LINK_OPTIONS from caller>) target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES}) The options are: @@ -67,7 +69,7 @@ The options are: are used. ``COMPILE_DEFINITIONS <defs>...`` - Specify ``-Ddefinition`` arguments to pass to ``add_definitions`` + Specify ``-Ddefinition`` arguments to pass to :command:`add_definitions` in the generated test project. ``COPY_FILE <fileName>`` @@ -85,6 +87,11 @@ The options are: If this option is specified, any ``-DLINK_LIBRARIES=...`` value given to the ``CMAKE_FLAGS`` option will be ignored. +``LINK_OPTIONS <options>...`` + Specify link step options to pass to :command:`target_link_options` or + to :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property in the generated + project, depending of the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable. + ``OUTPUT_VARIABLE <var>`` Store the output from the build process the given variable. @@ -127,7 +134,13 @@ default values: If :policy:`CMP0056` is set to ``NEW``, then :variable:`CMAKE_EXE_LINKER_FLAGS` is passed in as well. -The current setting of :policy:`CMP0065` is set in the generated project. +If :policy:`CMP0083` is set to ``NEW``, then in order to obtain correct +behavior at link time, the ``check_pie_supported()`` command from the +:module:`CheckPIESupported` module must be called before using the +:command:`try_compile` command. + +The current settings of :policy:`CMP0065` and :policy:`CMP0083` are set in the +generated project. Set the :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` variable to choose a build configuration. diff --git a/Help/command/try_run.rst b/Help/command/try_run.rst index dfa0bf9..137402f 100644 --- a/Help/command/try_run.rst +++ b/Help/command/try_run.rst @@ -15,6 +15,7 @@ Try Compiling and Running Source Files try_run(RUN_RESULT_VAR COMPILE_RESULT_VAR bindir srcfile [CMAKE_FLAGS <flags>...] [COMPILE_DEFINITIONS <defs>...] + [LINK_OPTIONS <options>...] [LINK_LIBRARIES <libs>...] [COMPILE_OUTPUT_VARIABLE <var>] [RUN_OUTPUT_VARIABLE <var>] @@ -38,7 +39,7 @@ The options are: are used. ``COMPILE_DEFINITIONS <defs>...`` - Specify ``-Ddefinition`` arguments to pass to ``add_definitions`` + Specify ``-Ddefinition`` arguments to pass to :command:`add_definitions` in the generated test project. ``COMPILE_OUTPUT_VARIABLE <var>`` @@ -52,6 +53,10 @@ The options are: If this option is specified, any ``-DLINK_LIBRARIES=...`` value given to the ``CMAKE_FLAGS`` option will be ignored. +``LINK_OPTIONS <options>...`` + Specify link step options to pass to :command:`target_link_options` in the + generated project. + ``OUTPUT_VARIABLE <var>`` Report the compile build output and the output from running the executable in the given variable. This option exists for legacy reasons. Prefer diff --git a/Help/cpack_gen/deb.rst b/Help/cpack_gen/deb.rst index fdde654..23f0515 100644 --- a/Help/cpack_gen/deb.rst +++ b/Help/cpack_gen/deb.rst @@ -15,9 +15,9 @@ better deb package when Debian specific tools ``dpkg-xxx`` are usable on the build system. The CPack DEB generator has specific features which are controlled by the -specifics :code:`CPACK_DEBIAN_XXX` variables. +specifics ``CPACK_DEBIAN_XXX`` variables. -:code:`CPACK_DEBIAN_<COMPONENT>_XXXX` variables may be used in order to have +``CPACK_DEBIAN_<COMPONENT>_XXXX`` variables may be used in order to have **component** specific values. Note however that ``<COMPONENT>`` refers to the **grouping name** written in upper case. It may be either a component name or a component GROUP name. @@ -133,8 +133,8 @@ List of CPack DEB generator specific variables: The Debian package architecture * Mandatory : YES - * Default : Output of :code:`dpkg --print-architecture` (or :code:`i386` - if :code:`dpkg` is not found) + * Default : Output of ``dpkg --print-architecture`` (or ``i386`` + if ``dpkg`` is not found) .. variable:: CPACK_DEBIAN_PACKAGE_DEPENDS CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS @@ -176,7 +176,7 @@ List of CPack DEB generator specific variables: The Debian package maintainer * Mandatory : YES - * Default : :code:`CPACK_PACKAGE_CONTACT` + * Default : ``CPACK_PACKAGE_CONTACT`` .. variable:: CPACK_DEBIAN_PACKAGE_DESCRIPTION CPACK_COMPONENT_<COMPONENT>_DESCRIPTION @@ -205,18 +205,18 @@ List of CPack DEB generator specific variables: The archive format used for creating the Debian package. * Mandatory : YES - * Default : "paxr" + * Default : "gnutar" - Possible values are: + Possible value is: - - paxr - gnutar .. note:: - Default pax archive format is the most portable format and generates - packages that do not treat sparse files specially. - GNU tar format on the other hand supports longer filenames. + This variable previously defaulted to the ``paxr`` value, but ``dpkg`` + has never supported that tar format. For backwards compatibility the + ``paxr`` value will be mapped to ``gnutar`` and a deprecation message + will be emitted. .. variable:: CPACK_DEBIAN_COMPRESSION_TYPE @@ -260,7 +260,7 @@ List of CPack DEB generator specific variables: .. variable:: CPACK_DEBIAN_PACKAGE_SHLIBDEPS CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS - May be set to ON in order to use :code:`dpkg-shlibdeps` to generate + May be set to ON in order to use ``dpkg-shlibdeps`` to generate better package dependency list. * Mandatory : NO @@ -272,7 +272,7 @@ List of CPack DEB generator specific variables: .. note:: You may need set :variable:`CMAKE_INSTALL_RPATH` to an appropriate value - if you use this feature, because if you don't :code:`dpkg-shlibdeps` + if you use this feature, because if you don't ``dpkg-shlibdeps`` may fail to find your own shared libs. See https://gitlab.kitware.com/cmake/community/wikis/doc/cmake/RPATH-handling @@ -289,7 +289,7 @@ List of CPack DEB generator specific variables: Sets the `Pre-Depends` field of the Debian package. Like :variable:`Depends <CPACK_DEBIAN_PACKAGE_DEPENDS>`, except that it - also forces :code:`dpkg` to complete installation of the packages named + also forces ``dpkg`` to complete installation of the packages named before even starting the installation of the package which declares the pre-dependency. @@ -324,7 +324,7 @@ List of CPack DEB generator specific variables: Sets the `Breaks` field of the Debian package. When a binary package (P) declares that it breaks other packages (B), - :code:`dpkg` will not allow the package (P) which declares `Breaks` be + ``dpkg`` will not allow the package (P) which declares `Breaks` be **unpacked** unless the packages that will be broken (B) are deconfigured first. As long as the package (P) is configured, the previously deconfigured @@ -344,7 +344,7 @@ List of CPack DEB generator specific variables: Sets the `Conflicts` field of the Debian package. When one binary package declares a conflict with another using a `Conflicts` - field, :code:`dpkg` will not allow them to be unpacked on the system at + field, ``dpkg`` will not allow them to be unpacked on the system at the same time. * Mandatory : NO diff --git a/Help/cpack_gen/freebsd.rst b/Help/cpack_gen/freebsd.rst index b22ea9a..a8dd320 100644 --- a/Help/cpack_gen/freebsd.rst +++ b/Help/cpack_gen/freebsd.rst @@ -20,7 +20,7 @@ The CPack FreeBSD generator should work on any host with libpkg installed. The packages it produces are specific to the host architecture and ABI. The CPack FreeBSD generator sets package-metadata through -:code:`CPACK_FREEBSD_XXX` variables. The CPack FreeBSD generator, unlike the +``CPACK_FREEBSD_XXX`` variables. The CPack FreeBSD generator, unlike the CPack Deb generator, does not specially support componentized packages; a single package is created from all the software artifacts created through CMake. diff --git a/Help/cpack_gen/nuget.rst b/Help/cpack_gen/nuget.rst index c8c481f..f8aa626 100644 --- a/Help/cpack_gen/nuget.rst +++ b/Help/cpack_gen/nuget.rst @@ -18,7 +18,7 @@ The CPack NuGet generator may be used to create NuGet packages using it uses the ``CPACK_XXX`` variables used by :module:`CPack`. The CPack NuGet generator has specific features which are controlled by the -specifics :code:`CPACK_NUGET_XXX` variables. In the "one per group" mode +specifics ``CPACK_NUGET_XXX`` variables. In the "one per group" mode (see :variable:`CPACK_COMPONENTS_GROUPING`), ``<compName>`` placeholder in the variables below would contain a group name (uppercased and turned into a "C" identifier). diff --git a/Help/cpack_gen/rpm.rst b/Help/cpack_gen/rpm.rst index 5c543ff..65009db 100644 --- a/Help/cpack_gen/rpm.rst +++ b/Help/cpack_gen/rpm.rst @@ -11,9 +11,9 @@ The CPack RPM generator is a :module:`CPack` generator thus it uses the ``CPACK_XXX`` variables used by :module:`CPack`. The CPack RPM generator has specific features which are controlled by the specifics -:code:`CPACK_RPM_XXX` variables. +``CPACK_RPM_XXX`` variables. -:code:`CPACK_RPM_<COMPONENT>_XXXX` variables may be used in order to have +``CPACK_RPM_<COMPONENT>_XXXX`` variables may be used in order to have **component** specific values. Note however that ``<COMPONENT>`` refers to the **grouping name** written in upper case. It may be either a component name or a component GROUP name. Usually those variables correspond to RPM spec file diff --git a/Help/dev/documentation.rst b/Help/dev/documentation.rst index 1b2c942..c302790 100644 --- a/Help/dev/documentation.rst +++ b/Help/dev/documentation.rst @@ -458,32 +458,22 @@ reStructuredText markup from comment blocks that start in ``.rst:``. At the top of ``Modules/<module-name>.cmake``, begin with the following license notice: -.. code-block:: cmake +:: # Distributed under the OSI-approved BSD 3-Clause License. See accompanying # file Copyright.txt or https://cmake.org/licensing for details. After this notice, add a *BLANK* line. Then, add documentation using -a `Line Comment`_ block of the form: - -.. code-block:: cmake - - #.rst: - # <module-name> - # ------------- - # - # <reStructuredText documentation of module> - -or a `Bracket Comment`_ of the form: +a `Bracket Comment`_ of the form: :: - #[[.rst: - <module-name> - ------------- + #[=======================================================================[.rst: + <module-name> + ------------- - <reStructuredText documentation of module> - #]] + <reStructuredText documentation of module> + #]=======================================================================] Any number of ``=`` may be used in the opening and closing brackets as long as they match. Content on the line containing the closing @@ -496,35 +486,38 @@ For example, a ``Findxxx.cmake`` module may contain: :: - # Distributed under the OSI-approved BSD 3-Clause License. See accompanying - # file Copyright.txt or https://cmake.org/licensing for details. + # Distributed under the OSI-approved BSD 3-Clause License. See accompanying + # file Copyright.txt or https://cmake.org/licensing for details. + + #[=======================================================================[.rst: + FindXxx + ------- + + This is a cool module. + This module does really cool stuff. + It can do even more than you think. + + It even needs two paragraphs to tell you about it. + And it defines the following variables: + + ``VAR_COOL`` + this is great isn't it? + ``VAR_REALLY_COOL`` + cool right? + #]=======================================================================] + + <code> + + #[=======================================================================[.rst: + .. command:: xxx_do_something + + This command does something for Xxx:: - #.rst: - # FindXxx - # ------- - # - # This is a cool module. - # This module does really cool stuff. - # It can do even more than you think. - # - # It even needs two paragraphs to tell you about it. - # And it defines the following variables: - # - # * VAR_COOL: this is great isn't it? - # * VAR_REALLY_COOL: cool right? - - <code> - - #[========================================[.rst: - .. command:: xxx_do_something - - This command does something for Xxx:: - - xxx_do_something(some arguments) - #]========================================] - macro(xxx_do_something) - <code> - endmacro() + xxx_do_something(some arguments) + #]=======================================================================] + macro(xxx_do_something) + <code> + endmacro() Test the documentation formatting by running ``cmake --help-module <module-name>``, and also by enabling the @@ -534,5 +527,4 @@ have a .cmake file in this directory NOT show up in the modules documentation, simply leave out the ``Help/module/<module-name>.rst`` file and the ``Help/manual/cmake-modules.7.rst`` toctree entry. -.. _`Line Comment`: https://cmake.org/cmake/help/latest/manual/cmake-language.7.html#line-comment .. _`Bracket Comment`: https://cmake.org/cmake/help/latest/manual/cmake-language.7.html#bracket-comment diff --git a/Help/dev/review.rst b/Help/dev/review.rst index a524115..0c4eded 100644 --- a/Help/dev/review.rst +++ b/Help/dev/review.rst @@ -323,6 +323,14 @@ branch (e.g. ``master``) branch followed by a sequence of merges each integrating changes from an open MR that has been staged for integration testing. Each time the target integration branch is updated the stage is rebuilt automatically by merging the staged MR topics again. +The branch is stored in the upstream repository by special refs: + +* ``refs/stage/master/head``: The current topic stage branch. + This is used by continuous builds that report to CDash. +* ``refs/stage/master/nightly/latest``: Topic stage as of 1am UTC each night. + This is used by most nightly builds that report to CDash. +* ``refs/stage/master/nightly/<yyyy>/<mm>/<dd>``: Topic stage as of 1am UTC + on the date specified. This is used for historical reference. `CMake GitLab Project Developers`_ may stage a MR for integration testing by adding a comment with a command among the `comment trailing lines`_:: diff --git a/Help/index.rst b/Help/index.rst index fe1b73c..a948939 100644 --- a/Help/index.rst +++ b/Help/index.rst @@ -30,6 +30,7 @@ Reference Manuals /manual/cmake-compile-features.7 /manual/cmake-developer.7 /manual/cmake-env-variables.7 + /manual/cmake-file-api.7 /manual/cmake-generator-expressions.7 /manual/cmake-generators.7 /manual/cmake-language.7 diff --git a/Help/manual/ccmake.1.rst b/Help/manual/ccmake.1.rst index cc3ceec..9548471 100644 --- a/Help/manual/ccmake.1.rst +++ b/Help/manual/ccmake.1.rst @@ -13,7 +13,7 @@ Synopsis Description =========== -The "ccmake" executable is the CMake curses interface. Project +The **ccmake** executable is the CMake curses interface. Project configuration settings may be specified interactively through this GUI. Brief instructions are provided at the bottom of the terminal when the program is running. diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst index b949464..85ed935 100644 --- a/Help/manual/cmake-developer.7.rst +++ b/Help/manual/cmake-developer.7.rst @@ -196,49 +196,78 @@ them. A Sample Find Module -------------------- -We will describe how to create a simple find module for a library -``Foo``. +We will describe how to create a simple find module for a library ``Foo``. -The first thing that is needed is a license notice. +The top of the module should begin with a license notice, followed by +a blank line, and then followed by a :ref:`Bracket Comment`. The comment +should begin with ``.rst:`` to indicate that the rest of its content is +reStructuredText-format documentation. For example: -.. code-block:: cmake +:: - # Distributed under the OSI-approved BSD 3-Clause License. See accompanying - # file Copyright.txt or https://cmake.org/licensing for details. + # Distributed under the OSI-approved BSD 3-Clause License. See accompanying + # file Copyright.txt or https://cmake.org/licensing for details. -Next we need module documentation. CMake's documentation system requires you -to follow the license notice with a blank line and then with a documentation -marker and the name of the module. You should follow this with a simple -statement of what the module does. + #[=======================================================================[.rst: + FindFoo + ------- -.. code-block:: cmake + Finds the Foo library. - #.rst: - # FindFoo - # ------- - # - # Finds the Foo library - # + Imported Targets + ^^^^^^^^^^^^^^^^ -More description may be required for some packages. If there are -caveats or other details users of the module should be aware of, you can -add further paragraphs below this. Then you need to document what -variables and imported targets are set by the module, such as + This module provides the following imported targets, if found: -.. code-block:: cmake + ``Foo::Foo`` + The Foo library + + Result Variables + ^^^^^^^^^^^^^^^^ + + This will define the following variables: + + ``Foo_FOUND`` + True if the system has the Foo library. + ``Foo_VERSION`` + The version of the Foo library which was found. + ``Foo_INCLUDE_DIRS`` + Include directories needed to use Foo. + ``Foo_LIBRARIES`` + Libraries needed to link to Foo. + + Cache Variables + ^^^^^^^^^^^^^^^ + + The following cache variables may also be set: + + ``Foo_INCLUDE_DIR`` + The directory containing ``foo.h``. + ``Foo_LIBRARY`` + The path to the Foo library. + + #]=======================================================================] + +The module documentation consists of: + +* An underlined heading specifying the module name. + +* A simple description of what the module finds. + More description may be required for some packages. If there are + caveats or other details users of the module should be aware of, + specify them here. + +* A section listing imported targets provided by the module, if any. + +* A section listing result variables provided by the module. - # This will define the following variables:: - # - # Foo_FOUND - True if the system has the Foo library - # Foo_VERSION - The version of the Foo library which was found - # - # and the following imported targets:: - # - # Foo::Foo - The Foo library +* Optionally a section listing cache variables used by the module, if any. -If the package provides any macros, they should be listed here, but can -be documented where they are defined. +If the package provides any macros or functions, they should be listed in +an additional section, but can be documented by additional ``.rst:`` +comment blocks immediately above where those macros or functions are defined. +The find module implementation may begin below the documentation block. Now the actual libraries and so on have to be found. The code here will obviously vary from module to module (dealing with that, after all, is the point of find modules), but there tends to be a common pattern for libraries. diff --git a/Help/manual/cmake-file-api.7.rst b/Help/manual/cmake-file-api.7.rst new file mode 100644 index 0000000..f3e0208 --- /dev/null +++ b/Help/manual/cmake-file-api.7.rst @@ -0,0 +1,1111 @@ +.. cmake-manual-description: CMake File-Based API + +cmake-file-api(7) +***************** + +.. only:: html + + .. contents:: + +Introduction +============ + +CMake provides a file-based API that clients may use to get semantic +information about the buildsystems CMake generates. Clients may use +the API by writing query files to a specific location in a build tree +to request zero or more `Object Kinds`_. When CMake generates the +buildsystem in that build tree it will read the query files and write +reply files for the client to read. + +The file-based API uses a ``<build>/.cmake/api/`` directory at the top +of a build tree. The API is versioned to support changes to the layout +of files within the API directory. API file layout versioning is +orthogonal to the versioning of `Object Kinds`_ used in replies. +This version of CMake supports only one API version, `API v1`_. + +API v1 +====== + +API v1 is housed in the ``<build>/.cmake/api/v1/`` directory. +It has the following subdirectories: + +``query/`` + Holds query files written by clients. + These may be `v1 Shared Stateless Query Files`_, + `v1 Client Stateless Query Files`_, or `v1 Client Stateful Query Files`_. + +``reply/`` + Holds reply files written by CMake whenever it runs to generate a build + system. These are indexed by a `v1 Reply Index File`_ file that may + reference additional `v1 Reply Files`_. CMake owns all reply files. + Clients must never remove them. + + Clients may look for and read a reply index file at any time. + Clients may optionally create the ``reply/`` directory at any time + and monitor it for the appearance of a new reply index file. + +v1 Shared Stateless Query Files +------------------------------- + +Shared stateless query files allow clients to share requests for +major versions of the `Object Kinds`_ and get all requested versions +recognized by the CMake that runs. + +Clients may create shared requests by creating empty files in the +``v1/query/`` directory. The form is:: + + <build>/.cmake/api/v1/query/<kind>-v<major> + +where ``<kind>`` is one of the `Object Kinds`_, ``-v`` is literal, +and ``<major>`` is the major version number. + +Files of this form are stateless shared queries not owned by any specific +client. Once created they should not be removed without external client +coordination or human intervention. + +v1 Client Stateless Query Files +------------------------------- + +Client stateless query files allow clients to create owned requests for +major versions of the `Object Kinds`_ and get all requested versions +recognized by the CMake that runs. + +Clients may create owned requests by creating empty files in +client-specific query subdirectories. The form is:: + + <build>/.cmake/api/v1/query/client-<client>/<kind>-v<major> + +where ``client-`` is literal, ``<client>`` is a string uniquely +identifying the client, ``<kind>`` is one of the `Object Kinds`_, +``-v`` is literal, and ``<major>`` is the major version number. +Each client must choose a unique ``<client>`` identifier via its +own means. + +Files of this form are stateless queries owned by the client ``<client>``. +The owning client may remove them at any time. + +v1 Client Stateful Query Files +------------------------------ + +Stateful query files allow clients to request a list of versions of +each of the `Object Kinds`_ and get only the most recent version +recognized by the CMake that runs. + +Clients may create owned stateful queries by creating ``query.json`` +files in client-specific query subdirectories. The form is:: + + <build>/.cmake/api/v1/query/client-<client>/query.json + +where ``client-`` is literal, ``<client>`` is a string uniquely +identifying the client, and ``query.json`` is literal. Each client +must choose a unique ``<client>`` identifier via its own means. + +``query.json`` files are stateful queries owned by the client ``<client>``. +The owning client may update or remove them at any time. When a +given client installation is updated it may then update the stateful +query it writes to build trees to request newer object versions. +This can be used to avoid asking CMake to generate multiple object +versions unnecessarily. + +A ``query.json`` file must contain a JSON object: + +.. code-block:: json + + { + "requests": [ + { "kind": "<kind>" , "version": 1 }, + { "kind": "<kind>" , "version": { "major": 1, "minor": 2 } }, + { "kind": "<kind>" , "version": [2, 1] }, + { "kind": "<kind>" , "version": [2, { "major": 1, "minor": 2 }] }, + { "kind": "<kind>" , "version": 1, "client": {} }, + { "kind": "..." } + ], + "client": {} + } + +The members are: + +``requests`` + A JSON array containing zero or more requests. Each request is + a JSON object with members: + + ``kind`` + Specifies one of the `Object Kinds`_ to be included in the reply. + + ``version`` + Indicates the version(s) of the object kind that the client + understands. Versions have major and minor components following + semantic version conventions. The value must be + + * a JSON integer specifying a (non-negative) major version number, or + * a JSON object containing ``major`` and (optionally) ``minor`` + members specifying non-negative integer version components, or + * a JSON array whose elements are each one of the above. + + ``client`` + Optional member reserved for use by the client. This value is + preserved in the reply written for the client in the + `v1 Reply Index File`_ but is otherwise ignored. Clients may use + this to pass custom information with a request through to its reply. + + For each requested object kind CMake will choose the *first* version + that it recognizes for that kind among those listed in the request. + The response will use the selected *major* version with the highest + *minor* version known to the running CMake for that major version. + Therefore clients should list all supported major versions in + preferred order along with the minimal minor version required + for each major version. + +``client`` + Optional member reserved for use by the client. This value is + preserved in the reply written for the client in the + `v1 Reply Index File`_ but is otherwise ignored. Clients may use + this to pass custom information with a query through to its reply. + +Other ``query.json`` top-level members are reserved for future use. +If present they are ignored for forward compatibility. + +v1 Reply Index File +------------------- + +CMake writes an ``index-*.json`` file to the ``v1/reply/`` directory +whenever it runs to generate a build system. Clients must read the +reply index file first and may read other `v1 Reply Files`_ only by +following references. The form of the reply index file name is:: + + <build>/.cmake/api/v1/reply/index-<unspecified>.json + +where ``index-`` is literal and ``<unspecified>`` is an unspecified +name selected by CMake. Whenever a new index file is generated it +is given a new name and any old one is deleted. During the short +time between these steps there may be multiple index files present; +the one with the largest name in lexicographic order is the current +index file. + +The reply index file contains a JSON object: + +.. code-block:: json + + { + "cmake": { + "version": { + "major": 3, "minor": 14, "patch": 0, "suffix": "", + "string": "3.14.0", "isDirty": false + }, + "paths": { + "cmake": "/prefix/bin/cmake", + "ctest": "/prefix/bin/ctest", + "cpack": "/prefix/bin/cpack", + "root": "/prefix/share/cmake-3.14" + }, + "generator": { + "name": "Unix Makefiles" + } + }, + "objects": [ + { "kind": "<kind>", + "version": { "major": 1, "minor": 0 }, + "jsonFile": "<file>" }, + { "...": "..." } + ], + "reply": { + "<kind>-v<major>": { "kind": "<kind>", + "version": { "major": 1, "minor": 0 }, + "jsonFile": "<file>" }, + "<unknown>": { "error": "unknown query file" }, + "...": {}, + "client-<client>": { + "<kind>-v<major>": { "kind": "<kind>", + "version": { "major": 1, "minor": 0 }, + "jsonFile": "<file>" }, + "<unknown>": { "error": "unknown query file" }, + "...": {}, + "query.json": { + "requests": [ {}, {}, {} ], + "responses": [ + { "kind": "<kind>", + "version": { "major": 1, "minor": 0 }, + "jsonFile": "<file>" }, + { "error": "unknown query file" }, + { "...": {} } + ], + "client": {} + } + } + } + } + +The members are: + +``cmake`` + A JSON object containing information about the instance of CMake that + generated the reply. It contains members: + + ``version`` + A JSON object specifying the version of CMake with members: + + ``major``, ``minor``, ``patch`` + Integer values specifying the major, minor, and patch version components. + ``suffix`` + A string specifying the version suffix, if any, e.g. ``g0abc3``. + ``string`` + A string specifying the full version in the format + ``<major>.<minor>.<patch>[-<suffix>]``. + ``isDirty`` + A boolean indicating whether the version was built from a version + controlled source tree with local modifications. + + ``paths`` + A JSON object specifying paths to things that come with CMake. + It has members for ``cmake``, ``ctest``, and ``cpack`` whose values + are JSON strings specifying the absolute path to each tool, + represented with forward slashes. It also has a ``root`` member for + the absolute path to the directory containing CMake resources like the + ``Modules/`` directory (see :variable:`CMAKE_ROOT`). + + ``generator`` + A JSON object describing the CMake generator used for the build. + It has members: + + ``name`` + A string specifying the name of the generator. + ``platform`` + If the generator supports :variable:`CMAKE_GENERATOR_PLATFORM`, + this is a string specifying the generator platform name. + +``objects`` + A JSON array listing all versions of all `Object Kinds`_ generated + as part of the reply. Each array entry is a + `v1 Reply File Reference`_. + +``reply`` + A JSON object mirroring the content of the ``query/`` directory + that CMake loaded to produce the reply. The members are of the form + + ``<kind>-v<major>`` + A member of this form appears for each of the + `v1 Shared Stateless Query Files`_ that CMake recognized as a + request for object kind ``<kind>`` with major version ``<major>``. + The value is a `v1 Reply File Reference`_ to the corresponding + reply file for that object kind and version. + + ``<unknown>`` + A member of this form appears for each of the + `v1 Shared Stateless Query Files`_ that CMake did not recognize. + The value is a JSON object with a single ``error`` member + containing a string with an error message indicating that the + query file is unknown. + + ``client-<client>`` + A member of this form appears for each client-owned directory + holding `v1 Client Stateless Query Files`_. + The value is a JSON object mirroring the content of the + ``query/client-<client>/`` directory. The members are of the form: + + ``<kind>-v<major>`` + A member of this form appears for each of the + `v1 Client Stateless Query Files`_ that CMake recognized as a + request for object kind ``<kind>`` with major version ``<major>``. + The value is a `v1 Reply File Reference`_ to the corresponding + reply file for that object kind and version. + + ``<unknown>`` + A member of this form appears for each of the + `v1 Client Stateless Query Files`_ that CMake did not recognize. + The value is a JSON object with a single ``error`` member + containing a string with an error message indicating that the + query file is unknown. + + ``query.json`` + This member appears for clients using + `v1 Client Stateful Query Files`_. + If the ``query.json`` file failed to read or parse as a JSON object, + this member is a JSON object with a single ``error`` member + containing a string with an error message. Otherwise, this member + is a JSON object mirroring the content of the ``query.json`` file. + The members are: + + ``client`` + A copy of the ``query.json`` file ``client`` member, if it exists. + + ``requests`` + A copy of the ``query.json`` file ``requests`` member, if it exists. + + ``responses`` + If the ``query.json`` file ``requests`` member is missing or invalid, + this member is a JSON object with a single ``error`` member + containing a string with an error message. Otherwise, this member + contains a JSON array with a response for each entry of the + ``requests`` array, in the same order. Each response is + + * a JSON object with a single ``error`` member containing a string + with an error message, or + * a `v1 Reply File Reference`_ to the corresponding reply file for + the requested object kind and selected version. + +After reading the reply index file, clients may read the other +`v1 Reply Files`_ it references. + +v1 Reply File Reference +^^^^^^^^^^^^^^^^^^^^^^^ + +The reply index file represents each reference to another reply file +using a JSON object with members: + +``kind`` + A string specifying one of the `Object Kinds`_. +``version`` + A JSON object with members ``major`` and ``minor`` specifying + integer version components of the object kind. +``jsonFile`` + A JSON string specifying a path relative to the reply index file + to another JSON file containing the object. + +v1 Reply Files +-------------- + +Reply files containing specific `Object Kinds`_ are written by CMake. +The names of these files are unspecified and must not be interpreted +by clients. Clients must first read the `v1 Reply Index File`_ and +and follow references to the names of the desired response objects. + +Reply files (including the index file) will never be replaced by +files of the same name but different content. This allows a client +to read the files concurrently with a running CMake that may generate +a new reply. However, after generating a new reply CMake will attempt +to remove reply files from previous runs that it did not just write. +If a client attempts to read a reply file referenced by the index but +finds the file missing, that means a concurrent CMake has generated +a new reply. The client may simply start again by reading the new +reply index file. + +Object Kinds +============ + +The CMake file-based API reports semantic information about the build +system using the following kinds of JSON objects. Each kind of object +is versioned independently using semantic versioning with major and +minor components. Every kind of object has the form: + +.. code-block:: json + + { + "kind": "<kind>", + "version": { "major": 1, "minor": 0 }, + "...": {} + } + +The ``kind`` member is a string specifying the object kind name. +The ``version`` member is a JSON object with ``major`` and ``minor`` +members specifying integer components of the object kind's version. +Additional top-level members are specific to each object kind. + +Object Kind "codemodel" +----------------------- + +The ``codemodel`` object kind describes the build system structure as +modeled by CMake. + +There is only one ``codemodel`` object major version, version 2. +Version 1 does not exist to avoid confusion with that from +:manual:`cmake-server(7)` mode. + +"codemodel" version 2 +^^^^^^^^^^^^^^^^^^^^^ + +``codemodel`` object version 2 is a JSON object: + +.. code-block:: json + + { + "kind": "codemodel", + "version": { "major": 2, "minor": 0 }, + "paths": { + "source": "/path/to/top-level-source-dir", + "build": "/path/to/top-level-build-dir" + }, + "configurations": [ + { + "name": "Debug", + "directories": [ + { + "source": ".", + "build": ".", + "childIndexes": [ 1 ], + "projectIndex": 0, + "targetIndexes": [ 0 ], + "hasInstallRule": true, + "minimumCMakeVersion": { + "string": "3.14" + } + }, + { + "source": "sub", + "build": "sub", + "parentIndex": 0, + "projectIndex": 0, + "targetIndexes": [ 1 ], + "minimumCMakeVersion": { + "string": "3.14" + } + } + ], + "projects": [ + { + "name": "MyProject", + "directoryIndexes": [ 0, 1 ], + "targetIndexes": [ 0, 1 ] + } + ], + "targets": [ + { + "name": "MyExecutable", + "directoryIndex": 0, + "projectIndex": 0, + "jsonFile": "<file>" + }, + { + "name": "MyLibrary", + "directoryIndex": 1, + "projectIndex": 0, + "jsonFile": "<file>" + } + ] + } + ] + } + +The members specific to ``codemodel`` objects are: + +``paths`` + A JSON object containing members: + + ``source`` + A string specifying the absolute path to the top-level source directory, + represented with forward slashes. + + ``build`` + A string specifying the absolute path to the top-level build directory, + represented with forward slashes. + +``configurations`` + A JSON array of entries corresponding to available build configurations. + On single-configuration generators there is one entry for the value + of the :variable:`CMAKE_BUILD_TYPE` variable. For multi-configuration + generators there is an entry for each configuration listed in the + :variable:`CMAKE_CONFIGURATION_TYPES` variable. + Each entry is a JSON object containing members: + + ``name`` + A string specifying the name of the configuration, e.g. ``Debug``. + + ``directories`` + A JSON array of entries each corresponding to a build system directory + whose source directory contains a ``CMakeLists.txt`` file. The first + entry corresponds to the top-level directory. Each entry is a + JSON object containing members: + + ``source`` + A string specifying the path to the source directory, represented + with forward slashes. If the directory is inside the top-level + source directory then the path is specified relative to that + directory (with ``.`` for the top-level source directory itself). + Otherwise the path is absolute. + + ``build`` + A string specifying the path to the build directory, represented + with forward slashes. If the directory is inside the top-level + build directory then the path is specified relative to that + directory (with ``.`` for the top-level build directory itself). + Otherwise the path is absolute. + + ``parentIndex`` + Optional member that is present when the directory is not top-level. + The value is an unsigned integer 0-based index of another entry in + the main ``directories`` array that corresponds to the parent + directory that added this directory as a subdirectory. + + ``childIndexes`` + Optional member that is present when the directory has subdirectories. + The value is a JSON array of entries corresponding to child directories + created by the :command:`add_subdirectory` or :command:`subdirs` + command. Each entry is an unsigned integer 0-based index of another + entry in the main ``directories`` array. + + ``projectIndex`` + An unsigned integer 0-based index into the main ``projects`` array + indicating the build system project to which the this directory belongs. + + ``targetIndexes`` + Optional member that is present when the directory itself has targets, + excluding those belonging to subdirectories. The value is a JSON + array of entries corresponding to the targets. Each entry is an + unsigned integer 0-based index into the main ``targets`` array. + + ``minimumCMakeVersion`` + Optional member present when a minimum required version of CMake is + known for the directory. This is the ``<min>`` version given to the + most local call to the :command:`cmake_minimum_required(VERSION)` + command in the directory itself or one of its ancestors. + The value is a JSON object with one member: + + ``string`` + A string specifying the minimum required version in the format:: + + <major>.<minor>[.<patch>[.<tweak>]][<suffix>] + + Each component is an unsigned integer and the suffix may be an + arbitrary string. + + ``hasInstallRule`` + Optional member that is present with boolean value ``true`` when + the directory or one of its subdirectories contains any + :command:`install` rules, i.e. whether a ``make install`` + or equivalent rule is available. + + ``projects`` + A JSON array of entries corresponding to the top-level project + and sub-projects defined in the build system. Each (sub-)project + corresponds to a source directory whose ``CMakeLists.txt`` file + calls the :command:`project` command with a project name different + from its parent directory. The first entry corresponds to the + top-level project. + + Each entry is a JSON object containing members: + + ``name`` + A string specifying the name given to the :command:`project` command. + + ``parentIndex`` + Optional member that is present when the project is not top-level. + The value is an unsigned integer 0-based index of another entry in + the main ``projects`` array that corresponds to the parent project + that added this project as a sub-project. + + ``childIndexes`` + Optional member that is present when the project has sub-projects. + The value is a JSON array of entries corresponding to the sub-projects. + Each entry is an unsigned integer 0-based index of another + entry in the main ``projects`` array. + + ``directoryIndexes`` + A JSON array of entries corresponding to build system directories + that are part of the project. The first entry corresponds to the + top-level directory of the project. Each entry is an unsigned + integer 0-based index into the main ``directories`` array. + + ``targetIndexes`` + Optional member that is present when the project itself has targets, + excluding those belonging to sub-projects. The value is a JSON + array of entries corresponding to the targets. Each entry is an + unsigned integer 0-based index into the main ``targets`` array. + + ``targets`` + A JSON array of entries corresponding to the build system targets. + Such targets are created by calls to :command:`add_executable`, + :command:`add_library`, and :command:`add_custom_target`, excluding + imported targets and interface libraries (which do not generate any + build rules). Each entry is a JSON object containing members: + + ``name`` + A string specifying the target name. + + ``id`` + A string uniquely identifying the target. This matches the ``id`` + field in the file referenced by ``jsonFile``. + + ``directoryIndex`` + An unsigned integer 0-based index into the main ``directories`` array + indicating the build system directory in which the target is defined. + + ``projectIndex`` + An unsigned integer 0-based index into the main ``projects`` array + indicating the build system project in which the target is defined. + + ``jsonFile`` + A JSON string specifying a path relative to the codemodel file + to another JSON file containing a + `"codemodel" version 2 "target" object`_. + +"codemodel" version 2 "target" object +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A codemodel "target" object is referenced by a `"codemodel" version 2`_ +object's ``targets`` array. Each "target" object is a JSON object +with members: + +``name`` + A string specifying the logical name of the target. + +``id`` + A string uniquely identifying the target. The format is unspecified + and should not be interpreted by clients. + +``type`` + A string specifying the type of the target. The value is one of + ``EXECUTABLE``, ``STATIC_LIBRARY``, ``SHARED_LIBRARY``, + ``MODULE_LIBRARY``, ``OBJECT_LIBRARY``, or ``UTILITY``. + +``backtrace`` + Optional member that is present when a CMake language backtrace to + the command in the source code that created the target is available. + The value is an unsigned integer 0-based index into the + ``backtraceGraph`` member's ``nodes`` array. + +``folder`` + Optional member that is present when the :prop_tgt:`FOLDER` target + property is set. The value is a JSON object with one member: + + ``name`` + A string specifying the name of the target folder. + +``paths`` + A JSON object containing members: + + ``source`` + A string specifying the path to the target's source directory, + represented with forward slashes. If the directory is inside the + top-level source directory then the path is specified relative to + that directory (with ``.`` for the top-level source directory itself). + Otherwise the path is absolute. + + ``build`` + A string specifying the path to the target's build directory, + represented with forward slashes. If the directory is inside the + top-level build directory then the path is specified relative to + that directory (with ``.`` for the top-level build directory itself). + Otherwise the path is absolute. + +``nameOnDisk`` + Optional member that is present for executable and library targets + that are linked or archived into a single primary artifact. + The value is a string specifying the file name of that artifact on disk. + +``artifacts`` + Optional member that is present for executable and library targets + that produce artifacts on disk meant for consumption by dependents. + The value is a JSON array of entries corresponding to the artifacts. + Each entry is a JSON object containing one member: + + ``path`` + A string specifying the path to the file on disk, represented with + forward slashes. If the file is inside the top-level build directory + then the path is specified relative to that directory. + Otherwise the path is absolute. + +``isGeneratorProvided`` + Optional member that is present with boolean value ``true`` if the + target is provided by CMake's build system generator rather than by + a command in the source code. + +``install`` + Optional member that is present when the target has an :command:`install` + rule. The value is a JSON object with members: + + ``prefix`` + A JSON object specifying the installation prefix. It has one member: + + ``path`` + A string specifying the value of :variable:`CMAKE_INSTALL_PREFIX`. + + ``destinations`` + A JSON array of entries specifying an install destination path. + Each entry is a JSON object with members: + + ``path`` + A string specifying the install destination path. The path may + be absolute or relative to the install prefix. + + ``backtrace`` + Optional member that is present when a CMake language backtrace to + the :command:`install` command invocation that specified this + destination is available. The value is an unsigned integer 0-based + index into the ``backtraceGraph`` member's ``nodes`` array. + +``link`` + Optional member that is present for executables and shared library + targets that link into a runtime binary. The value is a JSON object + with members describing the link step: + + ``language`` + A string specifying the language (e.g. ``C``, ``CXX``, ``Fortran``) + of the toolchain is used to invoke the linker. + + ``commandFragments`` + Optional member that is present when fragments of the link command + line invocation are available. The value is a JSON array of entries + specifying ordered fragments. Each entry is a JSON object with members: + + ``fragment`` + A string specifying a fragment of the link command line invocation. + The value is encoded in the build system's native shell format. + + ``role`` + A string specifying the role of the fragment's content: + + * ``flags``: link flags. + * ``libraries``: link library file paths or flags. + * ``libraryPath``: library search path flags. + * ``frameworkPath``: macOS framework search path flags. + + ``lto`` + Optional member that is present with boolean value ``true`` + when link-time optimization (a.k.a. interprocedural optimization + or link-time code generation) is enabled. + + ``sysroot`` + Optional member that is present when the :variable:`CMAKE_SYSROOT_LINK` + or :variable:`CMAKE_SYSROOT` variable is defined. The value is a + JSON object with one member: + + ``path`` + A string specifying the absolute path to the sysroot, represented + with forward slashes. + +``archive`` + Optional member that is present for static library targets. The value + is a JSON object with members describing the archive step: + + ``commandFragments`` + Optional member that is present when fragments of the archiver command + line invocation are available. The value is a JSON array of entries + specifying the fragments. Each entry is a JSON object with members: + + ``fragment`` + A string specifying a fragment of the archiver command line invocation. + The value is encoded in the build system's native shell format. + + ``role`` + A string specifying the role of the fragment's content: + + * ``flags``: archiver flags. + + ``lto`` + Optional member that is present with boolean value ``true`` + when link-time optimization (a.k.a. interprocedural optimization + or link-time code generation) is enabled. + +``dependencies`` + Optional member that is present when the target depends on other targets. + The value is a JSON array of entries corresponding to the dependencies. + Each entry is a JSON object with members: + + ``id`` + A string uniquely identifying the target on which this target depends. + This matches the main ``id`` member of the other target. + + ``backtrace`` + Optional member that is present when a CMake language backtrace to + the :command:`add_dependencies`, :command:`target_link_libraries`, + or other command invocation that created this dependency is + available. The value is an unsigned integer 0-based index into + the ``backtraceGraph`` member's ``nodes`` array. + +``sources`` + A JSON array of entries corresponding to the target's source files. + Each entry is a JSON object with members: + + ``path`` + A string specifying the path to the source file on disk, represented + with forward slashes. If the file is inside the top-level source + directory then the path is specified relative to that directory. + Otherwise the path is absolute. + + ``compileGroupIndex`` + Optional member that is present when the source is compiled. + The value is an unsigned integer 0-based index into the + ``compileGroups`` array. + + ``sourceGroupIndex`` + Optional member that is present when the source is part of a source + group either via the :command:`source_group` command or by default. + The value is an unsigned integer 0-based index into the + ``sourceGroups`` array. + + ``isGenerated`` + Optional member that is present with boolean value ``true`` if + the source is :prop_sf:`GENERATED`. + + ``backtrace`` + Optional member that is present when a CMake language backtrace to + the :command:`target_sources`, :command:`add_executable`, + :command:`add_library`, :command:`add_custom_target`, or other + command invocation that added this source to the target is + available. The value is an unsigned integer 0-based index into + the ``backtraceGraph`` member's ``nodes`` array. + +``sourceGroups`` + Optional member that is present when sources are grouped together by + the :command:`source_group` command or by default. The value is a + JSON array of entries corresponding to the groups. Each entry is + a JSON object with members: + + ``name`` + A string specifying the name of the source group. + + ``sourceIndexes`` + A JSON array listing the sources belonging to the group. + Each entry is an unsigned integer 0-based index into the + main ``sources`` array for the target. + +``compileGroups`` + Optional member that is present when the target has sources that compile. + The value is a JSON array of entries corresponding to groups of sources + that all compile with the same settings. Each entry is a JSON object + with members: + + ``sourceIndexes`` + A JSON array listing the sources belonging to the group. + Each entry is an unsigned integer 0-based index into the + main ``sources`` array for the target. + + ``language`` + A string specifying the language (e.g. ``C``, ``CXX``, ``Fortran``) + of the toolchain is used to compile the source file. + + ``compileCommandFragments`` + Optional member that is present when fragments of the compiler command + line invocation are available. The value is a JSON array of entries + specifying ordered fragments. Each entry is a JSON object with + one member: + + ``fragment`` + A string specifying a fragment of the compile command line invocation. + The value is encoded in the build system's native shell format. + + ``includes`` + Optional member that is present when there are include directories. + The value is a JSON array with an entry for each directory. Each + entry is a JSON object with members: + + ``path`` + A string specifying the path to the include directory, + represented with forward slashes. + + ``isSystem`` + Optional member that is present with boolean value ``true`` if + the include directory is marked as a system include directory. + + ``backtrace`` + Optional member that is present when a CMake language backtrace to + the :command:`target_include_directories` or other command invocation + that added this include directory is available. The value is + an unsigned integer 0-based index into the ``backtraceGraph`` + member's ``nodes`` array. + + ``defines`` + Optional member that is present when there are preprocessor definitions. + The value is a JSON array with an entry for each definition. Each + entry is a JSON object with members: + + ``define`` + A string specifying the preprocessor definition in the format + ``<name>[=<value>]``, e.g. ``DEF`` or ``DEF=1``. + + ``backtrace`` + Optional member that is present when a CMake language backtrace to + the :command:`target_compile_definitions` or other command invocation + that added this preprocessor definition is available. The value is + an unsigned integer 0-based index into the ``backtraceGraph`` + member's ``nodes`` array. + + ``sysroot`` + Optional member that is present when the + :variable:`CMAKE_SYSROOT_COMPILE` or :variable:`CMAKE_SYSROOT` + variable is defined. The value is a JSON object with one member: + + ``path`` + A string specifying the absolute path to the sysroot, represented + with forward slashes. + +``backtraceGraph`` + A JSON object describing the graph of backtraces whose nodes are + referenced from ``backtrace`` members elsewhere. The members are: + + ``nodes`` + A JSON array listing nodes in the backtrace graph. Each entry + is a JSON object with members: + + ``file`` + An unsigned integer 0-based index into the backtrace ``files`` array. + + ``line`` + An optional member present when the node represents a line within + the file. The value is an unsigned integer 1-based line number. + + ``command`` + An optional member present when the node represents a command + invocation within the file. The value is an unsigned integer + 0-based index into the backtrace ``commands`` array. + + ``parent`` + An optional member present when the node is not the bottom of + the call stack. The value is an unsigned integer 0-based index + of another entry in the backtrace ``nodes`` array. + + ``commands`` + A JSON array listing command names referenced by backtrace nodes. + Each entry is a string specifying a command name. + + ``files`` + A JSON array listing CMake language files referenced by backtrace nodes. + Each entry is a string specifying the path to a file, represented + with forward slashes. If the file is inside the top-level source + directory then the path is specified relative to that directory. + Otherwise the path is absolute. + +Object Kind "cache" +------------------- + +The ``cache`` object kind lists cache entries. These are the +:ref:`CMake Language Variables` stored in the persistent cache +(``CMakeCache.txt``) for the build tree. + +There is only one ``cache`` object major version, version 2. +Version 1 does not exist to avoid confusion with that from +:manual:`cmake-server(7)` mode. + +"cache" version 2 +^^^^^^^^^^^^^^^^^ + +``cache`` object version 2 is a JSON object: + +.. code-block:: json + + { + "kind": "cache", + "version": { "major": 2, "minor": 0 }, + "entries": [ + { + "name": "BUILD_SHARED_LIBS", + "value": "ON", + "type": "BOOL", + "properties": [ + { + "name": "HELPSTRING", + "value": "Build shared libraries" + } + ] + }, + { + "name": "CMAKE_GENERATOR", + "value": "Unix Makefiles", + "type": "INTERNAL", + "properties": [ + { + "name": "HELPSTRING", + "value": "Name of generator." + } + ] + } + ] + } + +The members specific to ``cache`` objects are: + +``entries`` + A JSON array whose entries are each a JSON object specifying a + cache entry. The members of each entry are: + + ``name`` + A string specifying the name of the entry. + + ``value`` + A string specifying the value of the entry. + + ``type`` + A string specifying the type of the entry used by + :manual:`cmake-gui(1)` to choose a widget for editing. + + ``properties`` + A JSON array of entries specifying associated + :ref:`cache entry properties <Cache Entry Properties>`. + Each entry is a JSON object containing members: + + ``name`` + A string specifying the name of the cache entry property. + + ``value`` + A string specifying the value of the cache entry property. + +Object Kind "cmakeFiles" +------------------------ + +The ``cmakeFiles`` object kind lists files used by CMake while +configuring and generating the build system. These include the +``CMakeLists.txt`` files as well as included ``.cmake`` files. + +There is only one ``cmakeFiles`` object major version, version 1. + +"cmakeFiles" version 1 +^^^^^^^^^^^^^^^^^^^^^^ + +``cmakeFiles`` object version 1 is a JSON object: + +.. code-block:: json + + { + "kind": "cmakeFiles", + "version": { "major": 1, "minor": 0 }, + "paths": { + "build": "/path/to/top-level-build-dir", + "source": "/path/to/top-level-source-dir" + }, + "inputs": [ + { + "path": "CMakeLists.txt" + }, + { + "isGenerated": true, + "path": "/path/to/top-level-build-dir/.../CMakeSystem.cmake" + }, + { + "isExternal": true, + "path": "/path/to/external/third-party/module.cmake" + }, + { + "isCMake": true, + "isExternal": true, + "path": "/path/to/cmake/Modules/CMakeGenericSystem.cmake" + } + ] + } + +The members specific to ``cmakeFiles`` objects are: + +``paths`` + A JSON object containing members: + + ``source`` + A string specifying the absolute path to the top-level source directory, + represented with forward slashes. + + ``build`` + A string specifying the absolute path to the top-level build directory, + represented with forward slashes. + +``inputs`` + A JSON array whose entries are each a JSON object specifying an input + file used by CMake when configuring and generating the build system. + The members of each entry are: + + ``path`` + A string specifying the path to an input file to CMake, represented + with forward slashes. If the file is inside the top-level source + directory then the path is specified relative to that directory. + Otherwise the path is absolute. + + ``isGenerated`` + Optional member that is present with boolean value ``true`` + if the path specifies a file that is under the top-level + build directory and the build is out-of-source. + This member is not available on in-source builds. + + ``isExternal`` + Optional member that is present with boolean value ``true`` + if the path specifies a file that is not under the top-level + source or build directories. + + ``isCMake`` + Optional member that is present with boolean value ``true`` + if the path specifies a file in the CMake installation. diff --git a/Help/manual/cmake-generators.7.rst b/Help/manual/cmake-generators.7.rst index 0287767..1de10c4 100644 --- a/Help/manual/cmake-generators.7.rst +++ b/Help/manual/cmake-generators.7.rst @@ -27,6 +27,8 @@ when creating a new build tree. CMake Generators ================ +.. _`Command-Line Build Tool Generators`: + Command-Line Build Tool Generators ---------------------------------- @@ -58,6 +60,8 @@ Ninja Generator /generator/Ninja +.. _`IDE Build Tool Generators`: + IDE Build Tool Generators ------------------------- diff --git a/Help/manual/cmake-gui.1.rst b/Help/manual/cmake-gui.1.rst index 57a9850..9322e33 100644 --- a/Help/manual/cmake-gui.1.rst +++ b/Help/manual/cmake-gui.1.rst @@ -14,7 +14,7 @@ Synopsis Description =========== -The "cmake-gui" executable is the CMake GUI. Project configuration +The **cmake-gui** executable is the CMake GUI. Project configuration settings may be specified interactively. Brief instructions are provided at the bottom of the window when the program is running. diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index cd5d1a5..940186a 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -35,6 +35,7 @@ These modules are loaded using the :command:`include` command. /module/CheckIncludeFiles /module/CheckLanguage /module/CheckLibraryExists + /module/CheckPIESupported /module/CheckPrototypeDefinition /module/CheckStructHasMember /module/CheckSymbolExists @@ -176,6 +177,7 @@ They are normally called through the :command:`find_package` command. /module/FindMPEG2 /module/FindMPEG /module/FindMPI + /module/FindOctave /module/FindODBC /module/FindOpenACC /module/FindOpenAL diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 7c0fe6d..40ec1ef 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -57,6 +57,9 @@ Policies Introduced by CMake 3.14 .. toctree:: :maxdepth: 1 + CMP0087: install(SCRIPT | CODE) supports generator expressions. </policy/CMP0087> + CMP0086: UseSWIG honors SWIG_MODULE_NAME via -module flag. </policy/CMP0086> + CMP0085: IN_LIST generator expression handles empty list items. </policy/CMP0085> CMP0084: The FindQt module does not exist for find_package(). </policy/CMP0084> CMP0083: Add PIE options when linking executable. </policy/CMP0083> CMP0082: Install rules from add_subdirectory() are interleaved with those in caller. </policy/CMP0082> diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index b11526c..915e0d4 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -8,37 +8,164 @@ Synopsis .. parsed-literal:: - cmake [<options>] {<path-to-source> | <path-to-existing-build>} - cmake [<options>] -S <path-to-source> -B <path-to-build> - cmake [{-D <var>=<value>}...] -P <cmake-script-file> - cmake --build <dir> [<options>...] [-- <build-tool-options>...] - cmake --open <dir> - cmake -E <command> [<options>...] - cmake --find-package <options>... + `Generate a Project Buildsystem`_ + cmake [<options>] <path-to-source> + cmake [<options>] <path-to-existing-build> + cmake [<options>] -S <path-to-source> -B <path-to-build> + + `Build a Project`_ + cmake --build <dir> [<options>] [-- <build-tool-options>] + + `Open a Project`_ + cmake --open <dir> + + `Run a Script`_ + cmake [{-D <var>=<value>}...] -P <cmake-script-file> + + `Run a Command-Line Tool`_ + cmake -E <command> [<options>] + + `Run the Find-Package Tool`_ + cmake --find-package [<options>] + + `View Help`_ + cmake --help[-<topic>] Description =========== -The "cmake" executable is the CMake command-line interface. It may be -used to configure projects in scripts. Project configuration settings -may be specified on the command line with the -D option. +The **cmake** executable is the command-line interface of the cross-platform +buildsystem generator CMake. The above `Synopsis`_ lists various actions +the tool can perform as described in sections below. + +To build a software project with CMake, `Generate a Project Buildsystem`_. +Optionally use **cmake** to `Build a Project`_ or just run the +corresponding build tool (e.g. ``make``) directly. **cmake** can also +be used to `View Help`_. + +The other actions are meant for use by software developers writing +scripts in the :manual:`CMake language <cmake-language(7)>` to support +their builds. + +For graphical user interfaces that may be used in place of **cmake**, +see :manual:`ccmake <ccmake(1)>` and :manual:`cmake-gui <cmake-gui(1)>`. +For command-line interfaces to the CMake testing and packaging facilities, +see :manual:`ctest <ctest(1)>` and :manual:`cpack <cpack(1)>`. + +For more information on CMake at large, `see also`_ the links at the end +of this manual. + + +Introduction to CMake Buildsystems +================================== + +A *buildsystem* describes how to build a project's executables and libraries +from its source code using a *build tool* to automate the process. For +example, a buildsystem may be a ``Makefile`` for use with a command-line +``make`` tool or a project file for an Integrated Development Environment +(IDE). In order to avoid maintaining multiple such buildsystems, a project +may specify its buildsystem abstractly using files written in the +:manual:`CMake language <cmake-language(7)>`. From these files CMake +generates a preferred buildsystem locally for each user through a backend +called a *generator*. + +To generate a buildsystem with CMake, the following must be selected: + +Source Tree + The top-level directory containing source files provided by the project. + The project specifies its buildsystem using files as described in the + :manual:`cmake-language(7)` manual, starting with a top-level file named + ``CMakeLists.txt``. These files specify build targets and their + dependencies as described in the :manual:`cmake-buildsystem(7)` manual. + +Build Tree + The top-level directory in which buildsystem files and build output + artifacts (e.g. executables and libraries) are to be stored. + CMake will write a ``CMakeCache.txt`` file to identify the directory + as a build tree and store persistent information such as buildsystem + configuration options. + + To maintain a pristine source tree, perform an *out-of-source* build + by using a separate dedicated build tree. An *in-source* build in + which the build tree is placed in the same directory as the source + tree is also supported, but discouraged. + +Generator + This chooses the kind of buildsystem to generate. See the + :manual:`cmake-generators(7)` manual for documentation of all generators. + Run ``cmake --help`` to see a list of generators available locally. + Optionally use the ``-G`` option below to specify a generator, or simply + accept the default CMake chooses for the current platform. + + When using one of the :ref:`Command-Line Build Tool Generators` + CMake expects that the environment needed by the compiler toolchain + is already configured in the shell. When using one of the + :ref:`IDE Build Tool Generators`, no particular environment is needed. + + +Generate a Project Buildsystem +============================== + +Run CMake with one of the following command signatures to specify the +source and build trees and generate a buildsystem: + +``cmake [<options>] <path-to-source>`` + Uses the current working directory as the build tree, and + ``<path-to-source>`` as the source tree. The specified path may + be absolute or relative to the current working directory. + The source tree must contain a ``CMakeLists.txt`` file and must + *not* contain a ``CMakeCache.txt`` file because the latter + identifies an existing build tree. For example: + + .. code-block:: console + + $ mkdir build ; cd build + $ cmake ../src + +``cmake [<options>] <path-to-existing-build>`` + Uses ``<path-to-existing-build>`` as the build tree, and loads the + path to the source tree from its ``CMakeCache.txt`` file, which must + have already been generated by a previous run of CMake. The specified + path may be absolute or relative to the current working directory. + For example: + + .. code-block:: console + + $ cd build + $ cmake . + +``cmake [<options>] -S <path-to-source> -B <path-to-build>`` + Uses ``<path-to-build>`` as the build tree and ``<path-to-source>`` + as the source tree. The specified paths may be absolute or relative + to the current working directory. The source tree must contain a + ``CMakeLists.txt`` file. The build tree will be created automatically + if it does not already exist. For example: + + .. code-block:: console + + $ cmake -S src -B build + +In all cases the ``<options>`` may be zero or more of the `Options`_ below. + +After generating a buildsystem one may use the corresponding native +build tool to build the project. For example, after using the +:generator:`Unix Makefiles` generator one may run ``make`` directly: + + .. code-block:: console + + $ make + $ make install -CMake is a cross-platform build system generator. Projects specify -their build process with platform-independent CMake listfiles included -in each directory of a source tree with the name CMakeLists.txt. -Users build a project by using CMake to generate a build system for a -native tool on their platform. +Alternatively, one may use **cmake** to `Build a Project`_ by +automatically choosing and invoking the appropriate native build tool. .. _`CMake Options`: Options -======= +------- .. include:: OPTIONS_BUILD.txt -``-E <command> [<options>...]`` - See `Command-Line Tool Mode`_. - ``-L[A][H]`` List non-advanced cached variables. @@ -50,30 +177,12 @@ Options display also advanced variables. If H is specified, it will also display help for each variable. -``--build <dir>`` - See `Build Tool Mode`_. - -``--open <dir>`` - Open the generated project in the associated application. This is - only supported by some generators. - ``-N`` View mode only. Only load the cache. Do not actually run configure and generate steps. -``-P <file>`` - Process script mode. - - Process the given cmake file as a script written in the CMake - language. No configure or generate step is performed and the cache - is not modified. If variables are defined using -D, this must be - done before the -P argument. - -``--find-package`` - See `Find-Package Tool Mode`_. - ``--graphviz=[file]`` Generate graphviz of dependencies, see :module:`CMakeGraphVizOptions` for more. @@ -142,17 +251,17 @@ Options in CMAKE_SOURCE_DIR and CMAKE_BINARY_DIR. This flag tells CMake to warn about other files as well. -.. include:: OPTIONS_HELP.txt - .. _`Build Tool Mode`: -Build Tool Mode +Build a Project =============== CMake provides a command-line signature to build an already-generated -project binary tree:: +project binary tree: - cmake --build <dir> [<options>...] [-- <build-tool-options>...] +.. code-block:: shell + + cmake --build <dir> [<options>] [-- <build-tool-options>] This abstracts a native build tool's command-line interface with the following options: @@ -185,12 +294,41 @@ following options: Run ``cmake --build`` with no options for quick help. -Command-Line Tool Mode -====================== -CMake provides builtin command-line tools through the signature:: +Open a Project +============== + +.. code-block:: shell + + cmake --open <dir> + +Open the generated project in the associated application. This is only +supported by some generators. + + +.. _`Script Processing Mode`: + +Run a Script +============ + +.. code-block:: shell - cmake -E <command> [<options>...] + cmake [{-D <var>=<value>}...] -P <cmake-script-file> + +Process the given cmake file as a script written in the CMake +language. No configure or generate step is performed and the cache +is not modified. If variables are defined using -D, this must be +done before the -P argument. + + +Run a Command-Line Tool +======================= + +CMake provides builtin command-line tools through the signature + +.. code-block:: shell + + cmake -E <command> [<options>] Run ``cmake -E`` or ``cmake -E help`` for a summary of commands. Available commands are: @@ -326,7 +464,7 @@ Available commands are: ``sleep <number>...`` Sleep for given number of seconds. -``tar [cxt][vf][zjJ] file.tar [<options>...] [--] [<file>...]`` +``tar [cxt][vf][zjJ] file.tar [<options>] [--] [<file>...]`` Create or extract a tar or zip archive. Options are: ``--`` @@ -379,24 +517,40 @@ The following ``cmake -E`` commands are available only on Windows: ``write_regv <key> <value>`` Write Windows registry value. -Find-Package Tool Mode -====================== -CMake provides a helper for Makefile-based projects with the signature:: +Run the Find-Package Tool +========================= - cmake --find-package <options>... +CMake provides a pkg-config like helper for Makefile-based projects: -This runs in a pkg-config like mode. +.. code-block:: shell -Search a package using :command:`find_package()` and print the resulting flags -to stdout. This can be used to use cmake instead of pkg-config to find -installed libraries in plain Makefile-based projects or in autoconf-based -projects (via ``share/aclocal/cmake.m4``). + cmake --find-package [<options>] + +It searches a package using :command:`find_package()` and prints the +resulting flags to stdout. This can be used instead of pkg-config +to find installed libraries in plain Makefile-based projects or in +autoconf-based projects (via ``share/aclocal/cmake.m4``). .. note:: This mode is not well-supported due to some technical limitations. It is kept for compatibility but should not be used in new projects. + +View Help +========= + +To print selected pages from the CMake documentation, use + +.. code-block:: shell + + cmake --help[-<topic>] + +with one of the following options: + +.. include:: OPTIONS_HELP.txt + + See Also ======== diff --git a/Help/manual/cpack.1.rst b/Help/manual/cpack.1.rst index 6159d7b..679c547 100644 --- a/Help/manual/cpack.1.rst +++ b/Help/manual/cpack.1.rst @@ -13,12 +13,29 @@ Synopsis Description =========== -The ``cpack`` executable is the CMake packaging program. -CMake projects use :command:`install` commands to define the contents of -packages which can be generated in various formats by this tool. -The :module:`CPack` module greatly simplifies the creation of the input file -used by ``cpack``, allowing most aspects of the packaging configuration to be -controlled directly from the CMake project's own ``CMakeLists.txt`` files. +The **cpack** executable is the CMake packaging program. It generates +installers and source packages in a variety of formats. + +For each installer or package format, **cpack** has a specific backend, +called "generator". A generator is responsible for generating the required +inputs and invoking the specific package creation tools. These installer +or package generators are not to be confused with the makefile generators +of the :manual:`cmake <cmake(1)>` command. + +All supported generators are specified in the :manual:`cpack-generators +<cpack-generators(7)>` manual. The command ``cpack --help`` prints a +list of generators supported for the target platform. Which of them are +to be used can be selected through the :variable:`CPACK_GENERATOR` variable +or through the command-line option ``-G``. + +The **cpack** program is steered by a configuration file written in the +:manual:`CMake language <cmake-language(7)>`. Unless chosen differently +through the command-line option ``--config``, the file ``CPackConfig.cmake`` +in the current directory is used. + +In the standard CMake workflow, the file ``CPackConfig.cmake`` is generated +by the :manual:`cmake <cmake(1)>` executable, provided the :module:`CPack` +module is included by the project's ``CMakeLists.txt`` file. Options ======= @@ -27,14 +44,9 @@ Options ``<generators>`` is a :ref:`semicolon-separated list <CMake Language Lists>` of generator names. ``cpack`` will iterate through this list and produce package(s) in that generator's format according to the details provided in - the ``CPackConfig.cmake`` configuration file. A generator is responsible for - generating the required inputs for a particular package system and invoking - that system's package creation tools. All supported generators are specified - in the :manual:`Generators <cpack-generators(7)>` section of the manual and - the ``--help`` option lists the generators supported for the target platform. - - If this option is not given, the :variable:`CPACK_GENERATOR` variable - determines the default set of generators that will be used. + the ``CPackConfig.cmake`` configuration file. If this option is not given, + 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``, diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index e24b10d..1ef20ab 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -19,7 +19,7 @@ Synopsis Description =========== -The "ctest" executable is the CMake test driver program. +The **ctest** executable is the CMake test driver program. CMake-generated build trees created for projects that use the ENABLE_TESTING and ADD_TEST commands have testing support. This program will run the tests and report results. @@ -38,7 +38,7 @@ Options ``--progress`` Enable short progress output from tests. - When the output of ``ctest`` is being sent directly to a terminal, the + When the output of **ctest** is being sent directly to a terminal, the progress through the set of tests is reported by updating the same line rather than printing start and end messages for each test on new lines. This can significantly reduce the verbosity of the test output. @@ -313,10 +313,11 @@ See `Build and Test Mode`_. Do not use. ``--timeout <seconds>`` - Set a global timeout on all tests. + Set the default test timeout. - This option will set a global timeout on all tests that do not - already have a timeout set on them. + This option effectively sets a timeout on all tests that do not + already have a timeout set on them via the :prop_test:`TIMEOUT` + property. ``--stop-time <time>`` Set a time at which all tests should stop running. @@ -1069,7 +1070,7 @@ Configuration settings include: * :module:`CTest` module variable: ``BUILDNAME`` ``CDashVersion`` - Specify the version of `CDash`_ on the server. + Legacy option. Not used. * `CTest Script`_ variable: none, detected from server * :module:`CTest` module variable: ``CTEST_CDASH_VERSION`` @@ -1106,17 +1107,14 @@ Configuration settings include: ``DropMethod`` Specify the method by which results should be submitted to the - dashboard server. The value may be ``cp``, ``ftp``, ``http``, - ``https``, ``scp``, or ``xmlrpc`` (if CMake was built with - support for it). + dashboard server. The value may be ``http`` or ``https``. * `CTest Script`_ variable: :variable:`CTEST_DROP_METHOD` * :module:`CTest` module variable: ``DROP_METHOD`` if set, else ``CTEST_DROP_METHOD`` ``DropSite`` - The dashboard server name - (for ``ftp``, ``http``, and ``https``, ``scp``, and ``xmlrpc``). + The dashboard server name. * `CTest Script`_ variable: :variable:`CTEST_DROP_SITE` * :module:`CTest` module variable: ``DROP_SITE`` if set, @@ -1139,14 +1137,13 @@ Configuration settings include: else ``CTEST_DROP_SITE_USER`` ``IsCDash`` - Specify whether the dashboard server is `CDash`_ or an older - dashboard server implementation requiring ``TriggerSite``. + Legacy option. Not used. * `CTest Script`_ variable: :variable:`CTEST_DROP_SITE_CDASH` * :module:`CTest` module variable: ``CTEST_DROP_SITE_CDASH`` ``ScpCommand`` - ``scp`` command-line tool to use when ``DropMethod`` is ``scp``. + Legacy option. Not used. * `CTest Script`_ variable: :variable:`CTEST_SCP_COMMAND` * :module:`CTest` module variable: ``SCPCOMMAND`` @@ -1160,8 +1157,7 @@ Configuration settings include: initialized by the :command:`site_name` command ``TriggerSite`` - Legacy option to support older dashboard server implementations. - Not used when ``IsCDash`` is true. + Legacy option. Not used. * `CTest Script`_ variable: :variable:`CTEST_TRIGGER_SITE` * :module:`CTest` module variable: ``TRIGGER_SITE`` if set, diff --git a/Help/module/CheckPIESupported.rst b/Help/module/CheckPIESupported.rst new file mode 100644 index 0000000..02e7b43 --- /dev/null +++ b/Help/module/CheckPIESupported.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckPIESupported.cmake diff --git a/Help/module/FindOctave.rst b/Help/module/FindOctave.rst new file mode 100644 index 0000000..2dbcec4 --- /dev/null +++ b/Help/module/FindOctave.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindOctave.cmake diff --git a/Help/policy/CMP0078.rst b/Help/policy/CMP0078.rst index 54cdc9c..2e97934 100644 --- a/Help/policy/CMP0078.rst +++ b/Help/policy/CMP0078.rst @@ -1,6 +1,8 @@ CMP0078 ------- +:module:`UseSWIG` generates standard target names. + Starting with CMake 3.13, :module:`UseSWIG` generates now standard target names. This policy provides compatibility with projects that expect the legacy behavior. diff --git a/Help/policy/CMP0083.rst b/Help/policy/CMP0083.rst index 7b467b0..b26d6c8 100644 --- a/Help/policy/CMP0083.rst +++ b/Help/policy/CMP0083.rst @@ -17,8 +17,46 @@ is set: passed to the linker step. For example ``-no-pie`` for ``GCC``. * Not set: no flags are passed to the linker step. +Since a given linker may not support ``PIE`` flags in all environments in +which it is used, it is the project's responsibility to use the +:module:`CheckPIESupported` module to check for support to ensure that the +:prop_tgt:`POSITION_INDEPENDENT_CODE` target property for executables will be +honored at link time. + This policy was introduced in CMake version 3.14. CMake version |release| warns when the policy is not set and uses ``OLD`` behavior. Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. .. include:: DEPRECATED.txt + +Examples +^^^^^^^^ + +Behave like CMake 3.13 and do not apply any ``PIE`` flags at link stage. + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.13) + project(foo) + + # ... + + add_executable(foo ...) + set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE) + +Use the :module:`CheckPIESupported` module to detect whether ``PIE`` is +supported by the current linker and environment. Apply ``PIE`` flags only +if the linker supports them. + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.14) # CMP0083 NEW + project(foo) + + include(CheckPIESupported) + check_pie_supported() + + # ... + + add_executable(foo ...) + set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE) diff --git a/Help/policy/CMP0085.rst b/Help/policy/CMP0085.rst new file mode 100644 index 0000000..d9ec9a2 --- /dev/null +++ b/Help/policy/CMP0085.rst @@ -0,0 +1,21 @@ +CMP0085 +------- + +``$<IN_LIST:...>`` handles empty list items. + +In CMake 3.13 and lower, the ``$<IN_LIST:...>`` generator expression always +returned ``0`` if the first argument was empty, even if the list contained an +empty item. This behavior is inconsistent with the ``IN_LIST`` behavior of +:command:`if`, which this generator expression is meant to emulate. CMake 3.14 +and later handles this case correctly. + +The ``OLD`` behavior of this policy is for ``$<IN_LIST:...>`` to always return +``0`` if the first argument is empty. The ``NEW`` behavior is to return ``1`` +if the first argument is empty and the list contains an empty item. + +This policy was introduced in CMake version 3.14. CMake version +|release| warns when the policy is not set and uses ``OLD`` behavior. +Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` +explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0086.rst b/Help/policy/CMP0086.rst new file mode 100644 index 0000000..4a9e8b8 --- /dev/null +++ b/Help/policy/CMP0086.rst @@ -0,0 +1,20 @@ +CMP0086 +------- + +:module:`UseSWIG` honors ``SWIG_MODULE_NAME`` via ``-module`` flag. + +Starting with CMake 3.14, :module:`UseSWIG` passes option +``-module <module_name>`` to ``SWIG`` compiler if the file property +``SWIG_MODULE_NAME`` is specified. This policy provides compatibility with +projects that expect the legacy behavior. + +The ``OLD`` behavior for this policy is to never pass ``-module`` option. +The ``NEW`` behavior is to pass ``-module`` option to ``SWIG`` compiler if +``SWIG_MODULE_NAME`` is specified. + +This policy was introduced in CMake version 3.14. CMake version +|release| warns when the policy is not set and uses ``OLD`` behavior. +Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` +explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0087.rst b/Help/policy/CMP0087.rst new file mode 100644 index 0000000..4c45b99 --- /dev/null +++ b/Help/policy/CMP0087.rst @@ -0,0 +1,29 @@ +CMP0087 +------- + +:command:`install(CODE)` and :command:`install(SCRIPT)` support generator +expressions. + +In CMake 3.13 and earlier, :command:`install(CODE)` and +:command:`install(SCRIPT)` did not evaluate generator expressions. CMake 3.14 +and later will evaluate generator expressions for :command:`install(CODE)` and +:command:`install(SCRIPT)`. + +The ``OLD`` behavior of this policy is for :command:`install(CODE)` and +:command:`install(SCRIPT)` to not evaluate generator expressions. The ``NEW`` +behavior is to evaluate generator expressions for :command:`install(CODE)` and +:command:`install(SCRIPT)`. + +Note that it is the value of this policy setting at the end of the directory +scope that is important, not its setting at the time of the call to +:command:`install(CODE)` or :command:`install(SCRIPT)`. This has implications +for calling these commands from places that have their own policy scope but not +their own directory scope (e.g. from files brought in via :command:`include()` +rather than :command:`add_subdirectory()`). + +This policy was introduced in CMake version 3.14. CMake version +|release| warns when the policy is not set and uses ``OLD`` behavior. +Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` +explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/prop_tgt/AUTOGEN_ORIGIN_DEPENDS.rst b/Help/prop_tgt/AUTOGEN_ORIGIN_DEPENDS.rst index f61089a..022bab5 100644 --- a/Help/prop_tgt/AUTOGEN_ORIGIN_DEPENDS.rst +++ b/Help/prop_tgt/AUTOGEN_ORIGIN_DEPENDS.rst @@ -5,22 +5,34 @@ Switch for forwarding origin target dependencies to the corresponding ``_autogen`` target. Targets which have their :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC` property -``ON`` have a corresponding ``_autogen`` target which is used to auto generate +``ON`` have a corresponding ``_autogen`` target which generates ``moc`` and ``uic`` files. As this ``_autogen`` target is created at -generate-time, it is not possible to define dependencies of it, -such as to create inputs for the ``moc`` or ``uic`` executable. - -The dependencies of the ``_autogen`` target are composed from - -- the origin target dependencies - (by default enabled via :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS`) -- user defined dependencies from :prop_tgt:`AUTOGEN_TARGET_DEPENDS` - -:prop_tgt:`AUTOGEN_ORIGIN_DEPENDS` decides whether the origin target -dependencies should be forwarded to the ``_autogen`` target or not. +generate-time, it is not possible to define dependencies of it using +e.g. :command:`add_dependencies`. Instead the +:prop_tgt:`AUTOGEN_ORIGIN_DEPENDS` target property decides whether the origin +target dependencies should be forwarded to the ``_autogen`` target or not. By default :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS` is initialized from :variable:`CMAKE_AUTOGEN_ORIGIN_DEPENDS` which is ``ON`` by default. +In total the dependencies of the ``_autogen`` target are composed from + +- forwarded origin target dependencies + (enabled by default via :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS`) +- additional user defined dependencies from :prop_tgt:`AUTOGEN_TARGET_DEPENDS` + See the :manual:`cmake-qt(7)` manual for more information on using CMake with Qt. + +Note +^^^^ + +Disabling :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS` is useful to avoid building of +origin target dependencies when building the ``_autogen`` target only. +This is especially interesting when a +:variable:`global autogen target <CMAKE_GLOBAL_AUTOGEN_TARGET>` is enabled. + +When the ``_autogen`` target doesn't require all the origin target's +dependencies, and :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS` is disabled, it might be +necessary to extend :prop_tgt:`AUTOGEN_TARGET_DEPENDS` to add missing +dependencies. diff --git a/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst b/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst index 84c2bfe..d5c5e14 100644 --- a/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst +++ b/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst @@ -1,23 +1,22 @@ AUTOGEN_TARGET_DEPENDS ---------------------- -Target dependencies of the corresponding ``_autogen`` target. +Additional target dependencies of the corresponding ``_autogen`` target. Targets which have their :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC` property -``ON`` have a corresponding ``_autogen`` target which is used to auto generate +``ON`` have a corresponding ``_autogen`` target which generates ``moc`` and ``uic`` files. As this ``_autogen`` target is created at -generate-time, it is not possible to define dependencies of it, -such as to create inputs for the ``moc`` or ``uic`` executable. +generate-time, it is not possible to define dependencies of it using +e.g. :command:`add_dependencies`. Instead the +:prop_tgt:`AUTOGEN_TARGET_DEPENDS` target property can be set to a +:ref:`;-list <CMake Language Lists>` of additional dependencies for the +``_autogen`` target. Dependencies can be target names or file names. -The dependencies of the ``_autogen`` target are composed from +In total the dependencies of the ``_autogen`` target are composed from -- the origin target dependencies - (by default enabled via :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS`) -- user defined dependencies from :prop_tgt:`AUTOGEN_TARGET_DEPENDS` - -The :prop_tgt:`AUTOGEN_TARGET_DEPENDS` target property can be set to a -list of additional dependencies for the ``_autogen`` target. Dependencies -can be target names or file names. +- forwarded origin target dependencies + (enabled by default via :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS`) +- additional user defined dependencies from :prop_tgt:`AUTOGEN_TARGET_DEPENDS` See the :manual:`cmake-qt(7)` manual for more information on using CMake with Qt. @@ -32,6 +31,6 @@ If :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC` depends on a file that is either - a :prop_sf:`GENERATED` C++ file that isn't recognized by :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` because it's skipped by :prop_sf:`SKIP_AUTOMOC`, :prop_sf:`SKIP_AUTOUIC`, :prop_sf:`SKIP_AUTOGEN` or :policy:`CMP0071` or -- a file that isn't in the target's sources +- a file that isn't in the origin target's sources it must added to :prop_tgt:`AUTOGEN_TARGET_DEPENDS`. diff --git a/Help/prop_tgt/POSITION_INDEPENDENT_CODE.rst b/Help/prop_tgt/POSITION_INDEPENDENT_CODE.rst index 54af8c6..0aaf66b 100644 --- a/Help/prop_tgt/POSITION_INDEPENDENT_CODE.rst +++ b/Help/prop_tgt/POSITION_INDEPENDENT_CODE.rst @@ -9,3 +9,8 @@ property is ``True`` by default for ``SHARED`` and ``MODULE`` library targets and ``False`` otherwise. This property is initialized by the value of the :variable:`CMAKE_POSITION_INDEPENDENT_CODE` variable if it is set when a target is created. + +.. note:: + + For executable targets, the link step is controlled by the :policy:`CMP0083` + policy and the :module:`CheckPIESupported` module. diff --git a/Help/release/3.13.rst b/Help/release/3.13.rst index 9f7e61f..68e05c3 100644 --- a/Help/release/3.13.rst +++ b/Help/release/3.13.rst @@ -239,3 +239,16 @@ Other Changes These internal implementation modules are also no longer available to scripts that may have been incorrectly including them, because they should never have been available in the first place. + +Updates +======= + +Changes made since CMake 3.13.0 include the following. + +3.13.2 +------ + +* CMake 3.13.0 included a change to pass compiler implicit include + directories to the ``moc`` tool for :prop_tgt:`AUTOMOC`. This has + been reverted due to regressing existing builds and will need + further investigation before being re-introduced in a later release. diff --git a/Help/release/dev/FindCURL-components.rst b/Help/release/dev/FindCURL-components.rst new file mode 100644 index 0000000..9c50ede --- /dev/null +++ b/Help/release/dev/FindCURL-components.rst @@ -0,0 +1,5 @@ +FindCURL-components +------------------- + +* The :module:`FindCURL` module gained support for requesting + protocols as package components. diff --git a/Help/release/dev/FindGIF-modernize.rst b/Help/release/dev/FindGIF-modernize.rst new file mode 100644 index 0000000..3bb4821 --- /dev/null +++ b/Help/release/dev/FindGIF-modernize.rst @@ -0,0 +1,4 @@ +FindGIF-modernize +----------------- + +* The :module:`FindGIF` module now provides imported targets. diff --git a/Help/release/dev/FindLibLZMA-target.rst b/Help/release/dev/FindLibLZMA-target.rst new file mode 100644 index 0000000..a13c45f --- /dev/null +++ b/Help/release/dev/FindLibLZMA-target.rst @@ -0,0 +1,4 @@ +FindLibLZMA-target +------------------ + +* The :module:`FindLibLZMA` module now provides an imported target. diff --git a/Help/release/dev/FindOctave.rst b/Help/release/dev/FindOctave.rst new file mode 100644 index 0000000..fe3b242 --- /dev/null +++ b/Help/release/dev/FindOctave.rst @@ -0,0 +1,4 @@ +FindOctave +---------- + +* A :module:`FindOctave` module was added to find GNU octave. diff --git a/Help/release/dev/FindX11-imported-targets.rst b/Help/release/dev/FindX11-imported-targets.rst new file mode 100644 index 0000000..4df753d --- /dev/null +++ b/Help/release/dev/FindX11-imported-targets.rst @@ -0,0 +1,32 @@ +FindX11-imported-targets +------------------------ + +* The :module:`FindX11` had the following variables renamed in order to match + their library names rather than header names. The old variables are provided + for compatibility: + + - ``X11_Xxf86misc_INCLUDE_PATH`` instead of ``X11_xf86misc_INCLUDE_PATH`` + - ``X11_Xxf86misc_LIB`` instead of ``X11_xf86misc_LIB`` + - ``X11_Xxf86misc_FOUND`` instead of ``X11_xf86misc_FOUND`` + - ``X11_Xxf86vm_INCLUDE_PATH`` instead of ``X11_xf86vmode_INCLUDE_PATH`` + - ``X11_Xxf86vm_LIB`` instead of ``X11_xf86vmode_LIB`` + - ``X11_Xxf86vm_FOUND`` instead of ``X11_xf86vmode_FOUND`` + - ``X11_xkbfile_INCLUDE_PATH`` instead of ``X11_Xkbfile_INCLUDE_PATH`` + - ``X11_xkbfile_LIB`` instead of ``X11_Xkbfile_LIB`` + - ``X11_xkbfile_FOUND`` instead of ``X11_Xkbfile_FOUND`` + - ``X11_Xtst_INCLUDE_PATH`` instead of ``X11_XTest_INCLUDE_PATH`` + - ``X11_Xtst_LIB`` instead of ``X11_XTest_LIB`` + - ``X11_Xtst_FOUND`` instead of ``X11_XTest_FOUND`` + - ``X11_Xss_INCLUDE_PATH`` instead of ``X11_Xscreensaver_INCLUDE_PATH`` + - ``X11_Xss_LIB`` instead of ``X11_Xscreensaver_LIB`` + - ``X11_Xss_FOUND`` instead of ``X11_Xscreensaver_FOUND`` + + The following variables are deprecated completely since they were + essentially duplicates: + + - ``X11_Xinput_INCLUDE_PATH`` (use ``X11_Xi_INCLUDE_PATH``) + - ``X11_Xinput_LIB`` (use ``X11_Xi_LIB``) + - ``X11_Xinput_FOUND`` (use ``X11_Xi_FOUND``) + +* The :module:`FindX11` now provides ``X11_Xext_INCLUDE_PATH``. +* The :module:`FindX11` now provides imported targets. diff --git a/Help/release/dev/UseSWIG-CMP0086.rst b/Help/release/dev/UseSWIG-CMP0086.rst new file mode 100644 index 0000000..d6fd0d1 --- /dev/null +++ b/Help/release/dev/UseSWIG-CMP0086.rst @@ -0,0 +1,6 @@ +UseSWIG-CMP0086 +--------------- + +* The :module:`UseSWIG` module passes option ``-module <module_name>`` to + ``SWIG`` compiler if the file property ``SWIG_MODULE_NAME`` is defined. + See policy :policy:`CMP0086`. diff --git a/Help/release/dev/UseSWIG-source-file-ext.rst b/Help/release/dev/UseSWIG-source-file-ext.rst new file mode 100644 index 0000000..5d11dc6 --- /dev/null +++ b/Help/release/dev/UseSWIG-source-file-ext.rst @@ -0,0 +1,5 @@ +UseSWIG-source-file-ext +----------------------- + +* The :module:`UseSWIG` module gains capability to specify + ``SWIG`` source file extensions. diff --git a/Help/release/dev/check-functions-LINK_OPTIONS.rst b/Help/release/dev/check-functions-LINK_OPTIONS.rst new file mode 100644 index 0000000..a6bfed2 --- /dev/null +++ b/Help/release/dev/check-functions-LINK_OPTIONS.rst @@ -0,0 +1,5 @@ +check-functions-LINK_OPTIONS +---------------------------- + +* The family of modules to check capabilities (like + :module:`CheckCSourceCompiles`) gain capability to manage ``LINK_OPTIONS``. diff --git a/Help/release/dev/cpack-deb-tar-format.rst b/Help/release/dev/cpack-deb-tar-format.rst new file mode 100644 index 0000000..9296ec6 --- /dev/null +++ b/Help/release/dev/cpack-deb-tar-format.rst @@ -0,0 +1,7 @@ +cpack-deb-tar-format +-------------------- + +* The :module:`CPack` module no longer defaults to the ``paxr`` value in the + :variable:`CPACK_DEBIAN_ARCHIVE_TYPE` variable, because ``dpkg`` has + never supported the PAX tar format. The ``paxr`` value will be mapped + to ``gnutar`` and a deprecation message emitted. diff --git a/Help/release/dev/file-read_symlink.rst b/Help/release/dev/file-read_symlink.rst new file mode 100644 index 0000000..718802e --- /dev/null +++ b/Help/release/dev/file-read_symlink.rst @@ -0,0 +1,5 @@ +file-read_symlink +----------------- + +* The :command:`file` command learned a new sub-command, ``READ_SYMLINK``, + which can be used to determine the path that a symlink points to. diff --git a/Help/release/dev/file-size.rst b/Help/release/dev/file-size.rst new file mode 100644 index 0000000..4f0e196 --- /dev/null +++ b/Help/release/dev/file-size.rst @@ -0,0 +1,5 @@ +file-size +--------- + +* The :command:`file` command gained a ``SIZE`` mode to get the size + of a file on disk. diff --git a/Help/release/dev/fileapi.rst b/Help/release/dev/fileapi.rst new file mode 100644 index 0000000..c3f03ef --- /dev/null +++ b/Help/release/dev/fileapi.rst @@ -0,0 +1,5 @@ +fileapi +------- + +* A file-based api for clients to get semantic buildsystem information + has been added. See the :manual:`cmake-file-api(7)` manual. diff --git a/Help/release/dev/genex-in_list-empty-args.rst b/Help/release/dev/genex-in_list-empty-args.rst new file mode 100644 index 0000000..ec1c6c0 --- /dev/null +++ b/Help/release/dev/genex-in_list-empty-args.rst @@ -0,0 +1,5 @@ +genex-in_list-empty-args +------------------------ + +* The $<IN_LIST:...> generator expression now correctly handles an empty + argument. See :policy:`CMP0085` for details. diff --git a/Help/release/dev/install-code-script-genex.rst b/Help/release/dev/install-code-script-genex.rst new file mode 100644 index 0000000..a28a466 --- /dev/null +++ b/Help/release/dev/install-code-script-genex.rst @@ -0,0 +1,5 @@ +install-code-script-genex +------------------------- + +* The :command:`install(CODE)` and :command:`install(SCRIPT)` commands + learned to support generator expressions. See policy :policy:`CMP0087`. diff --git a/Help/release/dev/link-option-PIE.rst b/Help/release/dev/link-option-PIE.rst index 824ab2c..872343c 100644 --- a/Help/release/dev/link-option-PIE.rst +++ b/Help/release/dev/link-option-PIE.rst @@ -2,5 +2,8 @@ link-option-PIE --------------- * Required link options to manage Position Independent Executable are now - added when :prop_tgt:`POSITION_INDEPENDENT_CODE` is set. These flags are - controlled by policy :policy:`CMP0083`. + added when :prop_tgt:`POSITION_INDEPENDENT_CODE` is set. The project is + responsible for using the :module:`CheckPIESupported` module to check for + ``PIE`` support to ensure that the :prop_tgt:`POSITION_INDEPENDENT_CODE` + target property will be honored at link time for executables. This behavior + is controlled by policy :policy:`CMP0083`. diff --git a/Help/release/dev/object-library-link.rst b/Help/release/dev/object-library-link.rst new file mode 100644 index 0000000..990d915 --- /dev/null +++ b/Help/release/dev/object-library-link.rst @@ -0,0 +1,5 @@ +object-library-link +------------------- + +* Object library linking has been fixed to propagate transitive link + dependencies of object libraries to consuming targets. diff --git a/Help/release/dev/submit-method.rst b/Help/release/dev/submit-method.rst new file mode 100644 index 0000000..38f0b92 --- /dev/null +++ b/Help/release/dev/submit-method.rst @@ -0,0 +1,6 @@ +submit-method +------------- + +* CTest no longer supports submissions via ``ftp``, ``scp``, ``cp``, and + ``xmlrpc``. CDash is the only maintained testing dashboard for CTest, + and it only supports submissions over ``http`` and ``https``. diff --git a/Help/release/dev/try_compile-LINK_OPTIONS.rst b/Help/release/dev/try_compile-LINK_OPTIONS.rst new file mode 100644 index 0000000..1db485b --- /dev/null +++ b/Help/release/dev/try_compile-LINK_OPTIONS.rst @@ -0,0 +1,5 @@ +try_compile-LINK_OPTIONS +------------------------ + +* The commands :command:`try_compile` and :command:`try_run` gain new + option ``LINK_OPTIONS``. diff --git a/Help/variable/CMAKE_ARGC.rst b/Help/variable/CMAKE_ARGC.rst index aec9711..30db2a2 100644 --- a/Help/variable/CMAKE_ARGC.rst +++ b/Help/variable/CMAKE_ARGC.rst @@ -3,6 +3,6 @@ CMAKE_ARGC Number of command line arguments passed to CMake in script mode. -When run in :ref:`-P <CMake Options>` script mode, CMake sets this variable to -the number of command line arguments. See also :variable:`CMAKE_ARGV0`, -``1``, ``2`` ... +When run in :ref:`-P <Script Processing Mode>` script mode, CMake sets this +variable to the number of command line arguments. See also +:variable:`CMAKE_ARGV0`, ``1``, ``2`` ... diff --git a/Help/variable/CMAKE_ARGV0.rst b/Help/variable/CMAKE_ARGV0.rst index 8b1ecb7..c4d1c21 100644 --- a/Help/variable/CMAKE_ARGV0.rst +++ b/Help/variable/CMAKE_ARGV0.rst @@ -3,7 +3,7 @@ CMAKE_ARGV0 Command line argument passed to CMake in script mode. -When run in :ref:`-P <CMake Options>` script mode, CMake sets this variable to -the first command line argument. It then also sets ``CMAKE_ARGV1``, +When run in :ref:`-P <Script Processing Mode>` script mode, CMake sets this +variable to the first command line argument. It then also sets ``CMAKE_ARGV1``, ``CMAKE_ARGV2``, ... and so on, up to the number of command line arguments given. See also :variable:`CMAKE_ARGC`. diff --git a/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET.rst b/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET.rst index 75903ab..e82867d 100644 --- a/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET.rst +++ b/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET.rst @@ -16,3 +16,11 @@ By default :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET` is unset. See the :manual:`cmake-qt(7)` manual for more information on using CMake with Qt. + +Note +^^^^ + +``<ORIGIN>_autogen`` targets by default inherit their origin target's +dependencies. This might result in unintended dependency target +builds when only ``<ORIGIN>_autogen`` targets are built. A solution is to +disable :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS` on the respective origin targets. diff --git a/Help/variable/CTEST_SCP_COMMAND.rst b/Help/variable/CTEST_SCP_COMMAND.rst index 0f128b1..19ea8b3 100644 --- a/Help/variable/CTEST_SCP_COMMAND.rst +++ b/Help/variable/CTEST_SCP_COMMAND.rst @@ -1,5 +1,4 @@ CTEST_SCP_COMMAND ----------------- -Specify the CTest ``SCPCommand`` setting -in a :manual:`ctest(1)` dashboard client script. +Legacy option. Not used. diff --git a/Help/variable/CTEST_TRIGGER_SITE.rst b/Help/variable/CTEST_TRIGGER_SITE.rst index de92428..a50e405 100644 --- a/Help/variable/CTEST_TRIGGER_SITE.rst +++ b/Help/variable/CTEST_TRIGGER_SITE.rst @@ -1,5 +1,4 @@ CTEST_TRIGGER_SITE ------------------ -Specify the CTest ``TriggerSite`` setting -in a :manual:`ctest(1)` dashboard client script. +Legacy option. Not used. |