diff options
Diffstat (limited to 'Help/manual')
| -rw-r--r-- | Help/manual/ccmake.1.rst | 2 | ||||
| -rw-r--r-- | Help/manual/cmake-buildsystem.7.rst | 1 | ||||
| -rw-r--r-- | Help/manual/cmake-commands.7.rst | 14 | ||||
| -rw-r--r-- | Help/manual/cmake-developer.7.rst | 676 | ||||
| -rw-r--r-- | Help/manual/cmake-env-variables.7.rst | 10 | ||||
| -rw-r--r-- | Help/manual/cmake-file-api.7.rst | 1111 | ||||
| -rw-r--r-- | Help/manual/cmake-generator-expressions.7.rst | 422 | ||||
| -rw-r--r-- | Help/manual/cmake-generators.7.rst | 5 | ||||
| -rw-r--r-- | Help/manual/cmake-gui.1.rst | 11 | ||||
| -rw-r--r-- | Help/manual/cmake-language.7.rst | 81 | ||||
| -rw-r--r-- | Help/manual/cmake-modules.7.rst | 106 | ||||
| -rw-r--r-- | Help/manual/cmake-policies.7.rst | 14 | ||||
| -rw-r--r-- | Help/manual/cmake-properties.7.rst | 31 | ||||
| -rw-r--r-- | Help/manual/cmake-qt.7.rst | 39 | ||||
| -rw-r--r-- | Help/manual/cmake-toolchains.7.rst | 129 | ||||
| -rw-r--r-- | Help/manual/cmake-variables.7.rst | 82 | ||||
| -rw-r--r-- | Help/manual/cmake.1.rst | 279 | ||||
| -rw-r--r-- | Help/manual/cpack.1.rst | 40 | ||||
| -rw-r--r-- | Help/manual/ctest.1.rst | 131 |
19 files changed, 2219 insertions, 965 deletions
diff --git a/Help/manual/ccmake.1.rst b/Help/manual/ccmake.1.rst index cc3ceec1b..954847150 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-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index 4fc484b2d..a1328f230 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -978,6 +978,7 @@ are: * Built-in properties matching ``COMPATIBLE_INTERFACE_*`` * ``EXPORT_NAME`` * ``IMPORTED`` +* ``MANUALLY_ADDED_DEPENDENCIES`` * ``NAME`` * Properties matching ``IMPORTED_LIBNAME_*`` * Properties matching ``MAP_IMPORTED_CONFIG_*`` diff --git a/Help/manual/cmake-commands.7.rst b/Help/manual/cmake-commands.7.rst index 0cc5fca83..a3bc46519 100644 --- a/Help/manual/cmake-commands.7.rst +++ b/Help/manual/cmake-commands.7.rst @@ -22,8 +22,8 @@ These commands are always available. /command/cmake_policy /command/configure_file /command/continue - /command/elseif /command/else + /command/elseif /command/endforeach /command/endfunction /command/endif @@ -53,9 +53,9 @@ These commands are always available. /command/option /command/return /command/separate_arguments + /command/set /command/set_directory_properties /command/set_property - /command/set /command/site_name /command/string /command/unset @@ -100,8 +100,6 @@ These commands are available only in CMake projects. /command/link_libraries /command/load_cache /command/project - /command/qt_wrap_cpp - /command/qt_wrap_ui /command/remove_definitions /command/set_source_files_properties /command/set_target_properties @@ -145,8 +143,10 @@ These commands are available only in CTest scripts. Deprecated Commands =================== -These commands are available only for compatibility with older -versions of CMake. Do not use them in new code. +These commands are deprecated and are only made available to maintain +backward compatibility. The documentation of each command states the +CMake version in which it was deprecated. Do not use these commands +in new code. .. toctree:: :maxdepth: 1 @@ -160,6 +160,8 @@ versions of CMake. Do not use them in new code. /command/load_command /command/make_directory /command/output_required_files + /command/qt_wrap_cpp + /command/qt_wrap_ui /command/remove /command/subdir_depends /command/subdirs diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst index f05c4b129..85ed935e6 100644 --- a/Help/manual/cmake-developer.7.rst +++ b/Help/manual/cmake-developer.7.rst @@ -10,576 +10,20 @@ cmake-developer(7) Introduction ============ -This manual is intended for reference by developers modifying the CMake -source tree itself, and by those authoring externally-maintained modules. - -Adding Compile Features -======================= - -CMake reports an error if a compiler whose features are known does not report -support for a particular requested feature. A compiler is considered to have -known features if it reports support for at least one feature. - -When adding a new compile feature to CMake, it is therefore necessary to list -support for the feature for all CompilerIds which already have one or more -feature supported, if the new feature is available for any version of the -compiler. - -When adding the first supported feature to a particular CompilerId, it is -necessary to list support for all features known to cmake (See -:variable:`CMAKE_C_COMPILE_FEATURES` and -:variable:`CMAKE_CXX_COMPILE_FEATURES` as appropriate), where available for -the compiler. Ensure that the ``CMAKE_<LANG>_STANDARD_DEFAULT`` is set to -the computed internal variable ``CMAKE_<LANG>_STANDARD_COMPUTED_DEFAULT`` -for compiler versions which should be supported. - -It is sensible to record the features for the most recent version of a -particular CompilerId first, and then work backwards. It is sensible to -try to create a continuous range of versions of feature releases of the -compiler. Gaps in the range indicate incorrect features recorded for -intermediate releases. - -Generally, features are made available for a particular version if the -compiler vendor documents availability of the feature with that -version. Note that sometimes partially implemented features appear to -be functional in previous releases (such as ``cxx_constexpr`` in GNU 4.6, -though availability is documented in GNU 4.7), and sometimes compiler vendors -document availability of features, though supporting infrastructure is -not available (such as ``__has_feature(cxx_generic_lambdas)`` indicating -non-availability in Clang 3.4, though it is documented as available, and -fixed in Clang 3.5). Similar cases for other compilers and versions -need to be investigated when extending CMake to support them. - -When a vendor releases a new version of a known compiler which supports -a previously unsupported feature, and there are already known features for -that compiler, the feature should be listed as supported in CMake for -that version of the compiler as soon as reasonably possible. - -Standard-specific/compiler-specific variables such -``CMAKE_CXX98_COMPILE_FEATURES`` are deliberately not documented. They -only exist for the compiler-specific implementation of adding the ``-std`` -compile flag for compilers which need that. - -Help -==== - -The ``Help`` directory contains CMake help manual source files. -They are written using the `reStructuredText`_ markup syntax and -processed by `Sphinx`_ to generate the CMake help manuals. - -.. _`reStructuredText`: http://docutils.sourceforge.net/docs/ref/rst/introduction.html -.. _`Sphinx`: http://sphinx-doc.org - -Markup Constructs ------------------ - -In addition to using Sphinx to generate the CMake help manuals, we -also use a C++-implemented document processor to print documents for -the ``--help-*`` command-line help options. It supports a subset of -reStructuredText markup. When authoring or modifying documents, -please verify that the command-line help looks good in addition to the -Sphinx-generated html and man pages. - -The command-line help processor supports the following constructs -defined by reStructuredText, Sphinx, and a CMake extension to Sphinx. - -.. - Note: This list must be kept consistent with the cmRST implementation. - -CMake Domain directives - Directives defined in the `CMake Domain`_ for defining CMake - documentation objects are printed in command-line help output as - if the lines were normal paragraph text with interpretation. - -CMake Domain interpreted text roles - Interpreted text roles defined in the `CMake Domain`_ for - cross-referencing CMake documentation objects are replaced by their - link text in command-line help output. Other roles are printed - literally and not processed. - -``code-block`` directive - Add a literal code block without interpretation. The command-line - help processor prints the block content without the leading directive - line and with common indentation replaced by one space. - -``include`` directive - Include another document source file. The command-line help - processor prints the included document inline with the referencing - document. - -literal block after ``::`` - A paragraph ending in ``::`` followed by a blank line treats - the following indented block as literal text without interpretation. - The command-line help processor prints the ``::`` literally and - prints the block content with common indentation replaced by one - space. - -``note`` directive - Call out a side note. The command-line help processor prints the - block content as if the lines were normal paragraph text with - interpretation. - -``parsed-literal`` directive - Add a literal block with markup interpretation. The command-line - help processor prints the block content without the leading - directive line and with common indentation replaced by one space. - -``productionlist`` directive - Render context-free grammar productions. The command-line help - processor prints the block content as if the lines were normal - paragraph text with interpretation. - -``replace`` directive - Define a ``|substitution|`` replacement. - The command-line help processor requires a substitution replacement - to be defined before it is referenced. - -``|substitution|`` reference - Reference a substitution replacement previously defined by - the ``replace`` directive. The command-line help processor - performs the substitution and replaces all newlines in the - replacement text with spaces. - -``toctree`` directive - Include other document sources in the Table-of-Contents - document tree. The command-line help processor prints - the referenced documents inline as part of the referencing - document. - -Inline markup constructs not listed above are printed literally in the -command-line help output. We prefer to use inline markup constructs that -look correct in source form, so avoid use of \\-escapes in favor of inline -literals when possible. - -Explicit markup blocks not matching directives listed above are removed from -command-line help output. Do not use them, except for plain ``..`` comments -that are removed by Sphinx too. +This manual is intended for reference by developers working with +:manual:`cmake-language(7)` code, whether writing their own modules, +authoring their own build systems, or working on CMake itself. -Note that nested indentation of blocks is not recognized by the -command-line help processor. Therefore: - -* Explicit markup blocks are recognized only when not indented - inside other blocks. - -* Literal blocks after paragraphs ending in ``::`` but not - at the top indentation level may consume all indented lines - following them. - -Try to avoid these cases in practice. - -CMake Domain ------------- - -CMake adds a `Sphinx Domain`_ called ``cmake``, also called the -"CMake Domain". It defines several "object" types for CMake -documentation: - -``command`` - A CMake language command. - -``generator`` - A CMake native build system generator. - See the :manual:`cmake(1)` command-line tool's ``-G`` option. - -``manual`` - A CMake manual page, like this :manual:`cmake-developer(7)` manual. - -``module`` - A CMake module. - See the :manual:`cmake-modules(7)` manual - and the :command:`include` command. - -``policy`` - A CMake policy. - See the :manual:`cmake-policies(7)` manual - and the :command:`cmake_policy` command. - -``prop_cache, prop_dir, prop_gbl, prop_sf, prop_inst, prop_test, prop_tgt`` - A CMake cache, directory, global, source file, installed file, test, - or target property, respectively. See the :manual:`cmake-properties(7)` - manual and the :command:`set_property` command. - -``variable`` - A CMake language variable. - See the :manual:`cmake-variables(7)` manual - and the :command:`set` command. - -Documentation objects in the CMake Domain come from two sources. -First, the CMake extension to Sphinx transforms every document named -with the form ``Help/<type>/<file-name>.rst`` to a domain object with -type ``<type>``. The object name is extracted from the document title, -which is expected to be of the form:: - - <object-name> - ------------- - -and to appear at or near the top of the ``.rst`` file before any other -lines starting in a letter, digit, or ``<``. If no such title appears -literally in the ``.rst`` file, the object name is the ``<file-name>``. -If a title does appear, it is expected that ``<file-name>`` is equal -to ``<object-name>`` with any ``<`` and ``>`` characters removed. - -Second, the CMake Domain provides directives to define objects inside -other documents: - -.. code-block:: rst - - .. command:: <command-name> - - This indented block documents <command-name>. - - .. variable:: <variable-name> - - This indented block documents <variable-name>. - -Object types for which no directive is available must be defined using -the first approach above. - -.. _`Sphinx Domain`: http://sphinx-doc.org/domains.html - -Cross-References ----------------- - -Sphinx uses reStructuredText interpreted text roles to provide -cross-reference syntax. The `CMake Domain`_ provides for each -domain object type a role of the same name to cross-reference it. -CMake Domain roles are inline markup of the forms:: - - :type:`name` - :type:`text <name>` - -where ``type`` is the domain object type and ``name`` is the -domain object name. In the first form the link text will be -``name`` (or ``name()`` if the type is ``command``) and in -the second form the link text will be the explicit ``text``. -For example, the code: - -.. code-block:: rst - - * The :command:`list` command. - * The :command:`list(APPEND)` sub-command. - * The :command:`list() command <list>`. - * The :command:`list(APPEND) sub-command <list>`. - * The :variable:`CMAKE_VERSION` variable. - * The :prop_tgt:`OUTPUT_NAME_<CONFIG>` target property. - -produces: - -* The :command:`list` command. -* The :command:`list(APPEND)` sub-command. -* The :command:`list() command <list>`. -* The :command:`list(APPEND) sub-command <list>`. -* The :variable:`CMAKE_VERSION` variable. -* The :prop_tgt:`OUTPUT_NAME_<CONFIG>` target property. - -Note that CMake Domain roles differ from Sphinx and reStructuredText -convention in that the form ``a<b>``, without a space preceding ``<``, -is interpreted as a name instead of link text with an explicit target. -This is necessary because we use ``<placeholders>`` frequently in -object names like ``OUTPUT_NAME_<CONFIG>``. The form ``a <b>``, -with a space preceding ``<``, is still interpreted as a link text -with an explicit target. - -Style ------ - -Style: Section Headers -^^^^^^^^^^^^^^^^^^^^^^ - -When marking section titles, make the section decoration line as long as -the title text. Use only a line below the title, not above. For -example: - -.. code-block:: rst - - Title Text - ---------- - -Capitalize the first letter of each non-minor word in the title. - -The section header underline character hierarchy is - -* ``#``: Manual group (part) in the master document -* ``*``: Manual (chapter) title -* ``=``: Section within a manual -* ``-``: Subsection or `CMake Domain`_ object document title -* ``^``: Subsubsection or `CMake Domain`_ object document section -* ``"``: Paragraph or `CMake Domain`_ object document subsection - -Style: Whitespace -^^^^^^^^^^^^^^^^^ - -Use two spaces for indentation. Use two spaces between sentences in -prose. - -Style: Line Length -^^^^^^^^^^^^^^^^^^ - -Prefer to restrict the width of lines to 75-80 columns. This is not a -hard restriction, but writing new paragraphs wrapped at 75 columns -allows space for adding minor content without significant re-wrapping of -content. - -Style: Prose -^^^^^^^^^^^^ - -Use American English spellings in prose. - -Style: Starting Literal Blocks -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Prefer to mark the start of literal blocks with ``::`` at the end of -the preceding paragraph. In cases where the following block gets -a ``code-block`` marker, put a single ``:`` at the end of the preceding -paragraph. - -Style: CMake Command Signatures -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Command signatures should be marked up as plain literal blocks, not as -cmake ``code-blocks``. - -Signatures are separated from preceding content by a section header. -That is, use: - -.. code-block:: rst - - ... preceding paragraph. - - Normal Libraries - ^^^^^^^^^^^^^^^^ - - :: - - add_library(<lib> ...) - - This signature is used for ... - -Signatures of commands should wrap optional parts with square brackets, -and should mark list of optional arguments with an ellipsis (``...``). -Elements of the signature which are specified by the user should be -specified with angle brackets, and may be referred to in prose using -``inline-literal`` syntax. - -Style: Boolean Constants -^^^^^^^^^^^^^^^^^^^^^^^^ - -Use "``OFF``" and "``ON``" for boolean values which can be modified by -the user, such as :prop_tgt:`POSITION_INDEPENDENT_CODE`. Such properties -may be "enabled" and "disabled". Use "``True``" and "``False``" for -inherent values which can't be modified after being set, such as the -:prop_tgt:`IMPORTED` property of a build target. - -Style: Inline Literals -^^^^^^^^^^^^^^^^^^^^^^ - -Mark up references to keywords in signatures, file names, and other -technical terms with ``inline-literal`` syntax, for example: - -.. code-block:: rst - - If ``WIN32`` is used with :command:`add_executable`, the - :prop_tgt:`WIN32_EXECUTABLE` target property is enabled. That command - creates the file ``<name>.exe`` on Windows. - -Style: Cross-References -^^^^^^^^^^^^^^^^^^^^^^^ - -Mark up linkable references as links, including repeats. -An alternative, which is used by wikipedia -(`<http://en.wikipedia.org/wiki/WP:REPEATLINK>`_), -is to link to a reference only once per article. That style is not used -in CMake documentation. - -Style: Referencing CMake Concepts -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If referring to a concept which corresponds to a property, and that -concept is described in a high-level manual, prefer to link to the -manual section instead of the property. For example: - -.. code-block:: rst - - This command creates an :ref:`Imported Target <Imported Targets>`. - -instead of: - -.. code-block:: rst - - This command creates an :prop_tgt:`IMPORTED` target. - -The latter should be used only when referring specifically to the -property. - -References to manual sections are not automatically created by creating -a section, but code such as: - -.. code-block:: rst - - .. _`Imported Targets`: - -creates a suitable anchor. Use an anchor name which matches the name -of the corresponding section. Refer to the anchor using a -cross-reference with specified text. - -Imported Targets need the ``IMPORTED`` term marked up with care in -particular because the term may refer to a command keyword -(``IMPORTED``), a target property (:prop_tgt:`IMPORTED`), or a -concept (:ref:`Imported Targets`). - -Where a property, command or variable is related conceptually to others, -by for example, being related to the buildsystem description, generator -expressions or Qt, each relevant property, command or variable should -link to the primary manual, which provides high-level information. Only -particular information relating to the command should be in the -documentation of the command. - -Style: Referencing CMake Domain Objects -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -When referring to `CMake Domain`_ objects such as properties, variables, -commands etc, prefer to link to the target object and follow that with -the type of object it is. For example: - -.. code-block:: rst - - Set the :prop_tgt:`AUTOMOC` target property to ``ON``. - -Instead of - -.. code-block:: rst - - Set the target property :prop_tgt:`AUTOMOC` to ``ON``. - -The ``policy`` directive is an exception, and the type us usually -referred to before the link: - -.. code-block:: rst - - If policy :prop_tgt:`CMP0022` is set to ``NEW`` the behavior is ... - -However, markup self-references with ``inline-literal`` syntax. -For example, within the :command:`add_executable` command -documentation, use - -.. code-block:: rst - - ``add_executable`` - -not - -.. code-block:: rst - - :command:`add_executable` - -which is used elsewhere. - -Modules -======= - -The ``Modules`` directory contains CMake-language ``.cmake`` module files. - -Module Documentation --------------------- - -To document CMake module ``Modules/<module-name>.cmake``, modify -``Help/manual/cmake-modules.7.rst`` to reference the module in the -``toctree`` directive, in sorted order, as:: - - /module/<module-name> - -Then add the module document file ``Help/module/<module-name>.rst`` -containing just the line:: - - .. cmake-module:: ../../Modules/<module-name>.cmake - -The ``cmake-module`` directive will scan the module file to extract -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 :ref:`Line Comment` block of the form: - -.. code-block:: cmake - - #.rst: - # <module-name> - # ------------- - # - # <reStructuredText documentation of module> - -or a :ref:`Bracket Comment` of the form: - -:: - - #[[.rst: - <module-name> - ------------- - - <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 -bracket is excluded if and only if the line starts in ``#``. - -Additional such ``.rst:`` comments may appear anywhere in the module file. -All such comments must start with ``#`` in the first column. - -For example, a ``Modules/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. - - #.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() - -Test the documentation formatting by running -``cmake --help-module <module-name>``, and also by enabling the -``SPHINX_HTML`` and ``SPHINX_MAN`` options to build the documentation. -Edit the comments until generated documentation looks satisfactory. To -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. +See https://cmake.org/get-involved/ to get involved in development of +CMake upstream. It includes links to contribution instructions, which +in turn link to developer guides for CMake itself. .. _`Find Modules`: Find Modules ------------- +============ -A "find module" is a ``Modules/Find<PackageName>.cmake`` file to be loaded +A "find module" is a ``Find<PackageName>.cmake`` file to be loaded by the :command:`find_package` command when invoked for ``<PackageName>``. The primary task of a find module is to determine whether a package @@ -638,16 +82,11 @@ and required is up to the find module, but should be documented. For internal implementation, it is a generally accepted convention that variables starting with underscore are for temporary use only. -Like all modules, find modules should be properly documented. To add a -module to the CMake documentation, follow the steps in the `Module -Documentation`_ section above. - - .. _`CMake Developer Standard Variable Names`: Standard Variable Names -^^^^^^^^^^^^^^^^^^^^^^^ +----------------------- For a ``FindXxx.cmake`` module that takes the approach of setting variables (either instead of or in addition to creating imported @@ -754,54 +193,81 @@ Make sure you comment them as deprecated, so that no-one starts using 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. See the `Module -Documentation`_ section above for more details. +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-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst index 31aa723fe..c43341276 100644 --- a/Help/manual/cmake-env-variables.7.rst +++ b/Help/manual/cmake-env-variables.7.rst @@ -7,6 +7,14 @@ cmake-env-variables(7) .. contents:: +This page lists environment variables that have special +meaning to CMake. + +For general information on environment variables, see the +:ref:`Environment Variables <CMake Language Environment Variables>` +section in the cmake-language manual. + + Environment Variables that Control the Build ============================================ @@ -16,11 +24,13 @@ Environment Variables that Control the Build /envvar/CMAKE_BUILD_PARALLEL_LEVEL /envvar/CMAKE_CONFIG_TYPE /envvar/CMAKE_MSVCIDE_RUN_PATH + /envvar/CMAKE_NO_VERBOSE /envvar/CMAKE_OSX_ARCHITECTURES /envvar/DESTDIR /envvar/LDFLAGS /envvar/MACOSX_DEPLOYMENT_TARGET /envvar/PackageName_ROOT + /envvar/VERBOSE Environment Variables for Languages =================================== diff --git a/Help/manual/cmake-file-api.7.rst b/Help/manual/cmake-file-api.7.rst new file mode 100644 index 000000000..f3e02088a --- /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-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 76fd3d9ed..7f484a42a 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -20,61 +20,74 @@ commands to populate those properties, such as :command:`target_link_libraries`, :command:`target_include_directories`, :command:`target_compile_definitions` and others. -This means that they enable conditional linking, conditional -definitions used when compiling, and conditional include directories and -more. The conditions may be based on the build configuration, target -properties, platform information or any other queryable information. +They enable conditional linking, conditional definitions used when compiling, +conditional include directories, and more. The conditions may be based on +the build configuration, target properties, platform information or any other +queryable information. -Logical Expressions -=================== +Generator expressions have the form ``$<...>``. To avoid confusion, this page +deviates from most of the CMake documentation in that it omits angular brackets +``<...>`` around placeholders like ``condition``, ``string``, ``target``, +among others. -Logical expressions are used to create conditional output. The basic -expressions are the ``0`` and ``1`` expressions. Because other logical -expressions evaluate to either ``0`` or ``1``, they can be composed to -create conditional output:: +Generator expressions can be nested, as shown in most of the examples below. - $<$<CONFIG:Debug>:DEBUG_MODE> +.. _`Boolean Generator Expressions`: -expands to ``DEBUG_MODE`` when the ``Debug`` configuration is used, and -otherwise expands to nothing. - -Available logical expressions are: - -``$<BOOL:...>`` - ``1`` if the ``...`` is true, else ``0`` -``$<AND:?[,?]...>`` - ``1`` if all ``?`` are ``1``, else ``0`` - - The ``?`` must always be either ``0`` or ``1`` in boolean expressions. - -``$<OR:?[,?]...>`` - ``0`` if all ``?`` are ``0``, else ``1`` -``$<NOT:?>`` - ``0`` if ``?`` is ``1``, else ``1`` -``$<IF:?,true-value...,false-value...>`` - ``true-value...`` if ``?`` is ``1``, ``false-value...`` if ``?`` is ``0`` -``$<STREQUAL:a,b>`` - ``1`` if ``a`` is STREQUAL ``b``, else ``0`` -``$<EQUAL:a,b>`` - ``1`` if ``a`` is EQUAL ``b`` in a numeric comparison, else ``0`` -``$<IN_LIST:a,b>`` - ``1`` if ``a`` is IN_LIST ``b``, else ``0`` -``$<TARGET_EXISTS:tgt>`` - ``1`` if ``tgt`` is an existed target name, else ``0``. -``$<CONFIG:cfg>`` - ``1`` if config is ``cfg``, else ``0``. This is a case-insensitive comparison. - The mapping in :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` is also considered by - this expression when it is evaluated on a property on an :prop_tgt:`IMPORTED` - target. -``$<PLATFORM_ID:comp>`` - ``1`` if the CMake-id of the platform matches ``comp``, otherwise ``0``. - See also the :variable:`CMAKE_SYSTEM_NAME` variable. -``$<C_COMPILER_ID:comp>`` - ``1`` if the CMake-id of the C compiler matches ``comp``, otherwise ``0``. - See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. -``$<CXX_COMPILER_ID:comp>`` - ``1`` if the CMake-id of the CXX compiler matches ``comp``, otherwise ``0``. - See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +Boolean Generator Expressions +============================= + +Boolean expressions evaluate to either ``0`` or ``1``. +They are typically used to construct the condition in a :ref:`conditional +generator expression<Conditional Generator Expressions>`. + +Available boolean expressions are: + +Logical Operators +----------------- + +``$<BOOL:string>`` + Converts ``string`` to ``0`` or ``1`` according to the rules of the + :command:`if()` command. Evaluates to ``0`` if any of the following is true: + + * ``string`` is empty, + * ``string`` is a case-insensitive equal of + ``0``, ``FALSE``, ``OFF``, ``N``, ``NO``, ``IGNORE``, or ``NOTFOUND``, or + * ``string`` ends in the suffix ``-NOTFOUND`` (case-sensitive). + + Otherwise evaluates to ``1``. + +``$<AND:conditions>`` + where ``conditions`` is a comma-separated list of boolean expressions. + Evaluates to ``1`` if all conditions are ``1``. + Otherwise evaluates to ``0``. + +``$<OR:conditions>`` + where ``conditions`` is a comma-separated list of boolean expressions. + Evaluates to ``1`` if at least one of the conditions is ``1``. + Otherwise evaluates to ``0``. + +``$<NOT:condition>`` + ``0`` if ``condition`` is ``1``, else ``1``. + +String Comparisons +------------------ + +``$<STREQUAL:string1,string2>`` + ``1`` if ``string1`` and ``string2`` are equal, else ``0``. + The comparison is case-sensitive. For a case-insensitive comparison, + combine with a :ref:`string transforming generator expression + <String Transforming Generator Expressions>`, + + .. code-block:: cmake + + $<STREQUAL:$<UPPER_CASE:${foo}>,"BAR"> # "1" if ${foo} is any of "BAR", "Bar", "bar", ... + +``$<EQUAL:value1,value2>`` + ``1`` if ``value1`` and ``value2`` are numerically equal, else ``0``. +``$<IN_LIST:string,list>`` + ``1`` if ``string`` is member of the comma-separated ``list``, else ``0``. + Uses case-sensitive comparisons. ``$<VERSION_LESS:v1,v2>`` ``1`` if ``v1`` is a version less than ``v2``, else ``0``. ``$<VERSION_GREATER:v1,v2>`` @@ -85,27 +98,62 @@ Available logical expressions are: ``1`` if ``v1`` is a version less than or equal to ``v2``, else ``0``. ``$<VERSION_GREATER_EQUAL:v1,v2>`` ``1`` if ``v1`` is a version greater than or equal to ``v2``, else ``0``. -``$<C_COMPILER_VERSION:ver>`` - ``1`` if the version of the C compiler matches ``ver``, otherwise ``0``. + + +Variable Queries +---------------- + +``$<TARGET_EXISTS:target>`` + ``1`` if ``target`` exists, else ``0``. +``$<CONFIG:cfg>`` + ``1`` if config is ``cfg``, else ``0``. This is a case-insensitive comparison. + The mapping in :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` is also considered by + this expression when it is evaluated on a property on an :prop_tgt:`IMPORTED` + target. +``$<PLATFORM_ID:platform_id>`` + ``1`` if the CMake-id of the platform matches ``platform_id`` + otherwise ``0``. + See also the :variable:`CMAKE_SYSTEM_NAME` variable. +``$<C_COMPILER_ID:compiler_id>`` + ``1`` if the CMake-id of the C compiler matches ``compiler_id``, + otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<CXX_COMPILER_ID:compiler_id>`` + ``1`` if the CMake-id of the CXX compiler matches ``compiler_id``, + otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<Fortran_COMPILER_ID:compiler_id>`` + ``1`` if the CMake-id of the Fortran compiler matches ``compiler_id``, + otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<C_COMPILER_VERSION:version>`` + ``1`` if the version of the C compiler matches ``version``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<CXX_COMPILER_VERSION:version>`` + ``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. -``$<CXX_COMPILER_VERSION:ver>`` - ``1`` if the version of the CXX compiler matches ``ver``, otherwise ``0``. +``$<Fortran_COMPILER_VERSION:version>`` + ``1`` if the version of the Fortran compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. -``$<TARGET_POLICY:pol>`` - ``1`` if the policy ``pol`` was NEW when the 'head' target was created, - else ``0``. If the policy was not set, the warning message for the policy +``$<TARGET_POLICY:policy>`` + ``1`` if the ``policy`` was NEW when the 'head' target was created, + else ``0``. If the ``policy`` was not set, the warning message for the policy will be emitted. This generator expression only works for a subset of policies. -``$<COMPILE_FEATURES:feature[,feature]...>`` - ``1`` if all of the ``feature`` features are available for the 'head' +``$<COMPILE_FEATURES:features>`` + where ``features`` is a comma-spearated list. + Evaluates to ``1`` if all of the ``features`` are available for the 'head' target, and ``0`` otherwise. If this expression is used while evaluating the link implementation of a target and if any dependency transitively increases the required :prop_tgt:`C_STANDARD` or :prop_tgt:`CXX_STANDARD` for the 'head' target, an error is reported. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. -``$<COMPILE_LANGUAGE:lang>`` - ``1`` when the language used for compilation unit matches ``lang``, + +.. _`Boolean COMPILE_LANGUAGE Generator Expression`: + +``$<COMPILE_LANGUAGE:language>`` + ``1`` when the language used for compilation unit matches ``language``, otherwise ``0``. This expression may be used to specify compile options, compile definitions, and include directories for source files of a particular language in a target. For example: @@ -147,18 +195,24 @@ Available logical expressions are: add_executable(myapp main.cpp) target_link_libraries(myapp myapp_c myapp_cxx) -Informational Expressions -========================= +String-Valued Generator Expressions +=================================== + +These expressions expand to some string. +For example, -These expressions expand to some information. The information may be used -directly, eg:: +.. code-block:: cmake include_directories(/usr/include/$<CXX_COMPILER_ID>/) expands to ``/usr/include/GNU/`` or ``/usr/include/Clang/`` etc, depending on -the Id of the compiler. +the compiler identifier. -These expressions may also may be combined with logical expressions:: +String-valued expressions may also be combined with other expressions. +Here an example for a string-valued expression within a boolean expressions +within a conditional expression: + +.. code-block:: cmake $<$<VERSION_LESS:$<CXX_COMPILER_VERSION>,4.2.0>:OLD_COMPILER> @@ -166,12 +220,123 @@ expands to ``OLD_COMPILER`` if the :variable:`CMAKE_CXX_COMPILER_VERSION <CMAKE_<LANG>_COMPILER_VERSION>` is less than 4.2.0. -Available informational expressions are: +And here two nested string-valued expressions: + +.. code-block:: cmake + + -I$<JOIN:$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>, -I> + +generates a string of the entries in the :prop_tgt:`INCLUDE_DIRECTORIES` target +property with each entry preceded by ``-I``. + +Expanding on the previous example, if one first wants to check if the +``INCLUDE_DIRECTORIES`` property is non-empty, then it is advisable to +introduce a helper variable to keep the code readable: + +.. code-block:: cmake + + set(prop "$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>") # helper variable + $<$<BOOL:${prop}>:-I$<JOIN:${prop}, -I>> + +The following string-valued generator expressions are available: + +Escaped Characters +------------------ + +String literals to escape the special meaning a character would otherwise have: + +``$<ANGLE-R>`` + A literal ``>``. Used for example to compare strings that contain a ``>``. +``$<COMMA>`` + A literal ``,``. Used for example to compare strings which contain a ``,``. +``$<SEMICOLON>`` + A literal ``;``. Used to prevent list expansion on an argument with ``;``. + +.. _`Conditional Generator Expressions`: + +Conditional Expressions +----------------------- + +Conditional generator expressions depend on a boolean condition +that must be ``0`` or ``1``. + +``$<condition:true_string>`` + Evaluates to ``true_string`` if ``condition`` is ``1``. + Otherwise evaluates to the empty string. + +``$<IF:condition,true_string,false_string>`` + Evaluates to ``true_string`` if ``condition`` is ``1``. + Otherwise evaluates to ``false_string``. + +Typically, the ``condition`` is a :ref:`boolean generator expression +<Boolean Generator Expressions>`. For instance, + +.. code-block:: cmake + + $<$<CONFIG:Debug>:DEBUG_MODE> + +expands to ``DEBUG_MODE`` when the ``Debug`` configuration is used, and +otherwise expands to the empty string. + +.. _`String Transforming Generator Expressions`: + +String Transformations +---------------------- + +``$<JOIN:list,string>`` + Joins the list with the content of ``string``. +``$<LOWER_CASE:string>`` + Content of ``string`` converted to lower case. +``$<UPPER_CASE:string>`` + Content of ``string`` converted to upper case. + +``$<GENEX_EVAL:expr>`` + Content of ``expr`` evaluated as a generator expression in the current + context. This enables consumption of generator expressions whose + evaluation results itself in generator expressions. +``$<TARGET_GENEX_EVAL:tgt,expr>`` + Content of ``expr`` evaluated as a generator expression in the context of + ``tgt`` target. This enables consumption of custom target properties that + themselves contain generator expressions. + + Having the capability to evaluate generator expressions is very useful when + you want to manage custom properties supporting generator expressions. + For example: + + .. code-block:: cmake + + add_library(foo ...) + + set_property(TARGET foo PROPERTY + CUSTOM_KEYS $<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS> + ) + + add_custom_target(printFooKeys + COMMAND ${CMAKE_COMMAND} -E echo $<TARGET_PROPERTY:foo,CUSTOM_KEYS> + ) + + This naive implementation of the ``printFooKeys`` custom command is wrong + because ``CUSTOM_KEYS`` target property is not evaluated and the content + is passed as is (i.e. ``$<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS>``). + + To have the expected result (i.e. ``FOO_EXTRA_THINGS`` if config is + ``Debug``), it is required to evaluate the output of + ``$<TARGET_PROPERTY:foo,CUSTOM_KEYS>``: + + .. code-block:: cmake + + add_custom_target(printFooKeys + COMMAND ${CMAKE_COMMAND} -E + echo $<TARGET_GENEX_EVAL:foo,$<TARGET_PROPERTY:foo,CUSTOM_KEYS>> + ) + +Variable Queries +---------------- -``$<CONFIGURATION>`` - Configuration name. Deprecated. Use ``CONFIG`` instead. ``$<CONFIG>`` - Configuration name + Configuration name. +``$<CONFIGURATION>`` + Configuration name. Deprecated since CMake 3.0. Use ``CONFIG`` instead. ``$<PLATFORM_ID>`` The CMake-id of the platform. See also the :variable:`CMAKE_SYSTEM_NAME` variable. @@ -181,12 +346,31 @@ Available informational expressions are: ``$<CXX_COMPILER_ID>`` The CMake-id of the CXX compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<Fortran_COMPILER_ID>`` + The CMake-id of the Fortran compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. ``$<C_COMPILER_VERSION>`` The version of the C compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. ``$<CXX_COMPILER_VERSION>`` The version of the CXX compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<Fortran_COMPILER_VERSION>`` + The version of the Fortran compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<COMPILE_LANGUAGE>`` + The compile language of source files when evaluating compile options. + See :ref:`the related boolean expression + <Boolean COMPILE_LANGUAGE Generator Expression>` + ``$<COMPILE_LANGUAGE:language>`` + for notes about the portability of this generator expression. + +Target-Dependent Queries +------------------------ + +``$<TARGET_NAME_IF_EXISTS:tgt>`` + Expands to the ``tgt`` if the given target exists, an empty string + otherwise. ``$<TARGET_FILE:tgt>`` Full path to main file (.exe, .so.1.2, .a) where ``tgt`` is the name of a target. ``$<TARGET_FILE_NAME:tgt>`` @@ -232,56 +416,21 @@ Available informational expressions are: expression is evaluated on. ``$<TARGET_PROPERTY:prop>`` Value of the property ``prop`` on the target on which the generator - expression is evaluated. + expression is evaluated. Note that for generator expressions in + :ref:`Target Usage Requirements` this is the value of the property + on the consuming target rather than the target specifying the + requirement. ``$<INSTALL_PREFIX>`` Content of the install prefix when the target is exported via :command:`install(EXPORT)` and empty otherwise. -``$<COMPILE_LANGUAGE>`` - The compile language of source files when evaluating compile options. See - the unary version for notes about portability of this generator - expression. - -Output Expressions -================== -These expressions generate output, in some cases depending on an input. These -expressions may be combined with other expressions for information or logical -comparison:: +Output-Related Expressions +-------------------------- - -I$<JOIN:$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>, -I> - -generates a string of the entries in the :prop_tgt:`INCLUDE_DIRECTORIES` target -property with each entry preceded by ``-I``. Note that a more-complete use -in this situation would require first checking if the INCLUDE_DIRECTORIES -property is non-empty:: - - $<$<BOOL:${prop}>:-I$<JOIN:${prop}, -I>> - -where ``${prop}`` refers to a helper variable:: - - set(prop "$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>") - -Available output expressions are: - -``$<0:...>`` - Empty string (ignores ``...``) -``$<1:...>`` - Content of ``...`` -``$<JOIN:list,...>`` - Joins the list with the content of ``...`` -``$<ANGLE-R>`` - A literal ``>``. Used to compare strings which contain a ``>`` for example. -``$<COMMA>`` - A literal ``,``. Used to compare strings which contain a ``,`` for example. -``$<SEMICOLON>`` - A literal ``;``. Used to prevent list expansion on an argument with ``;``. ``$<TARGET_NAME:...>`` Marks ``...`` as being the name of a target. This is required if exporting targets to multiple dependent export sets. The ``...`` must be a literal name of a target- it may not contain generator expressions. -``$<TARGET_NAME_IF_EXISTS:...>`` - Expands to the ``...`` if the given target exists, an empty string - otherwise. ``$<LINK_ONLY:...>`` Content of ``...`` except when evaluated in a link interface while propagating :ref:`Target Usage Requirements`, in which case it is the @@ -296,10 +445,6 @@ Available output expressions are: Content of ``...`` when the property is exported using :command:`export`, or when the target is used by another target in the same buildsystem. Expands to the empty string otherwise. -``$<LOWER_CASE:...>`` - Content of ``...`` converted to lower case. -``$<UPPER_CASE:...>`` - Content of ``...`` converted to upper case. ``$<MAKE_C_IDENTIFIER:...>`` Content of ``...`` converted to a C identifier. The conversion follows the same behavior as :command:`string(MAKE_C_IDENTIFIER)`. @@ -310,42 +455,25 @@ Available output expressions are: Content of ``...`` converted to shell path style. For example, slashes are converted to backslashes in Windows shells and drive letters are converted to posix paths in MSYS shells. The ``...`` must be an absolute path. -``$<GENEX_EVAL:...>`` - Content of ``...`` evaluated as a generator expression in the current - context. This enables consumption of generator expressions - whose evaluation results itself in generator expressions. -``$<TARGET_GENEX_EVAL:tgt,...>`` - Content of ``...`` evaluated as a generator expression in the context of - ``tgt`` target. This enables consumption of custom target properties that - themselves contain generator expressions. - Having the capability to evaluate generator expressions is very useful when - you want to manage custom properties supporting generator expressions. - For example: +Debugging +========= - .. code-block:: cmake +Since generator expressions are evaluated during generation of the buildsystem, +and not during processing of ``CMakeLists.txt`` files, it is not possible to +inspect their result with the :command:`message()` command. - add_library(foo ...) +One possible way to generate debug messages is to add a custom target, - set_property(TARGET foo PROPERTY - CUSTOM_KEYS $<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS> - ) +.. code-block:: cmake - add_custom_target(printFooKeys - COMMAND ${CMAKE_COMMAND} -E echo $<TARGET_PROPERTY:foo,CUSTOM_KEYS> - ) + add_custom_target(genexdebug COMMAND ${CMAKE_COMMAND} -E echo "$<...>") - This naive implementation of the ``printFooKeys`` custom command is wrong - because ``CUSTOM_KEYS`` target property is not evaluated and the content - is passed as is (i.e. ``$<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS>``). +The shell command ``make genexdebug`` (invoked after execution of ``cmake``) +would then print the result of ``$<...>``. - To have the expected result (i.e. ``FOO_EXTRA_THINGS`` if config is - ``Debug``), it is required to evaluate the output of - ``$<TARGET_PROPERTY:foo,CUSTOM_KEYS>``: +Another way is to write debug messages to a file: - .. code-block:: cmake +.. code-block:: cmake - add_custom_target(printFooKeys - COMMAND ${CMAKE_COMMAND} -E - echo $<TARGET_GENEX_EVAL:foo,$<TARGET_PROPERTY:foo,CUSTOM_KEYS>> - ) + file(GENERATE OUTPUT filename CONTENT "$<...>") diff --git a/Help/manual/cmake-generators.7.rst b/Help/manual/cmake-generators.7.rst index 028776750..41f765220 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 ------------------------- @@ -83,6 +87,7 @@ Visual Studio Generators /generator/Visual Studio 12 2013 /generator/Visual Studio 14 2015 /generator/Visual Studio 15 2017 + /generator/Visual Studio 16 2019 Other Generators ^^^^^^^^^^^^^^^^ diff --git a/Help/manual/cmake-gui.1.rst b/Help/manual/cmake-gui.1.rst index 57a98503b..856aa2fba 100644 --- a/Help/manual/cmake-gui.1.rst +++ b/Help/manual/cmake-gui.1.rst @@ -10,11 +10,12 @@ Synopsis cmake-gui [<options>] cmake-gui [<options>] {<path-to-source> | <path-to-existing-build>} + cmake-gui [<options>] -S <path-to-source> -B <path-to-build> 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. @@ -27,6 +28,14 @@ native tool on their platform. Options ======= +``-S <path-to-source>`` + Path to root directory of the CMake project to build. + +``-B <path-to-build>`` + Path to directory which CMake will use as the root of build directory. + + If the directory doesn't already exist CMake will make it. + .. include:: OPTIONS_HELP.txt See Also diff --git a/Help/manual/cmake-language.7.rst b/Help/manual/cmake-language.7.rst index 71649ba3e..5e5cffffd 100644 --- a/Help/manual/cmake-language.7.rst +++ b/Help/manual/cmake-language.7.rst @@ -206,9 +206,10 @@ enclosed content, such as `Escape Sequences`_ or `Variable References`_, is performed. A bracket argument is always given to the command invocation as exactly one argument. -For example: +.. No code-block syntax highlighting in the following example + (long string literal not supported by our cmake.py) -.. code-block:: cmake +For example:: message([=[ This is the first line in a bracket argument with bracket length 1. @@ -253,16 +254,22 @@ closing quotes. Both `Escape Sequences`_ and `Variable References`_ are evaluated. A quoted argument is always given to the command invocation as exactly one argument. +.. No code-block syntax highlighting in the following example + (escape \" not supported by our cmake.py) + For example: -:: +.. code-block:: cmake - message("This is a quoted argument containing multiple lines. - This is always one argument even though it contains a ; character. - Both \\-escape sequences and ${variable} references are evaluated. - The text does not end on an escaped double-quote like \". - It does end in an unescaped double quote. - ") + message("This is a quoted argument containing multiple lines. + This is always one argument even though it contains a ; character. + Both \\-escape sequences and ${variable} references are evaluated. + The text does not end on an escaped double-quote like \". + It does end in an unescaped double quote. + ") + +.. No code-block syntax highlighting in the following example + (for conformity with the two above examples) The final ``\`` on any line ending in an odd number of backslashes is treated as a line continuation and ignored along with the @@ -270,11 +277,11 @@ immediately following newline character. For example: .. code-block:: cmake - message("\ - This is the first line of a quoted argument. \ - In fact it is the only line but since it is long \ - the source code uses line continuation.\ - ") + message("\ + This is the first line of a quoted argument. \ + In fact it is the only line but since it is long \ + the source code uses line continuation.\ + ") .. note:: CMake versions prior to 3.0 do not support continuation with ``\``. @@ -382,7 +389,7 @@ historical considerations.) Variable References ------------------- -A *variable reference* has the form ``${variable_name}`` and is +A *variable reference* has the form ``${<variable>}`` and is evaluated inside a `Quoted Argument`_ or an `Unquoted Argument`_. A variable reference is replaced by the value of the variable, or by the empty string if the variable is not set. @@ -398,14 +405,18 @@ the ``$`` is also technically permitted but is discouraged. The `Variables`_ section documents the scope of variable names and how their values are set. -An *environment variable reference* has the form ``$ENV{VAR}`` and -is evaluated in the same contexts as a normal variable reference. -See :variable:`ENV` for more information. +An *environment variable reference* has the form ``$ENV{<variable>}``. +See the `Environment Variables`_ section for more information. -A *cache variable reference* has the form ``$CACHE{VAR}`` and -is evaluated in the same contexts as a normal variable reference. +A *cache variable reference* has the form ``$CACHE{<variable>}``. See :variable:`CACHE` for more information. +The :command:`if` command has a special condition syntax that +allows for variable references in the short form ``<variable>`` +instead of ``${<variable>}``. +However, environment and cache variables always need to be +referenced as ``$ENV{<variable>}`` or ``$CACHE{<variable>}``. + Comments -------- @@ -552,10 +563,38 @@ Otherwise, the variable reference evaluates to an empty string. The ``$CACHE{VAR}`` syntax can be used to do direct cache entry lookups. -The :manual:`cmake-variables(7)` manual documents many variables +The :manual:`cmake-variables(7)` manual documents the many variables that are provided by CMake or have meaning to CMake when set by project code. +.. _`CMake Language Environment Variables`: + +Environment Variables +===================== + +Environment Variables are like ordinary `Variables`_, with the +following differences: + +Scope + Environment variables have global scope in a CMake process. + They are never cached. + +References + `Variable References`_ have the form ``$ENV{<variable>}``. + +Initialization + Initial values of the CMake environment variables are those of + the calling process. + Values can be changed using the :command:`set` and :command:`unset` + commands. + These commands only affect the running CMake process, + not the system environment at large. + Changed values are not written back to the calling process, + and they are not seen by subsequent build or test processes. + +The :manual:`cmake-env-variables(7)` manual documents environment +variables that have special meaning to CMake. + .. _`CMake Language Lists`: Lists diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index b7276b657..d9b939f3b 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -3,12 +3,14 @@ cmake-modules(7) **************** -.. only:: html +The modules listed here are part of the CMake distribution. +Projects may provide further modules; their location(s) +can be specified in the :variable:`CMAKE_MODULE_PATH` variable. - .. contents:: +Utility Modules +^^^^^^^^^^^^^^^ -All Modules -=========== +These modules are loaded using the :command:`include` command. .. toctree:: :maxdepth: 1 @@ -26,6 +28,7 @@ All Modules /module/CheckFortranCompilerFlag /module/CheckFortranFunctionExists /module/CheckFortranSourceCompiles + /module/CheckFortranSourceRuns /module/CheckFunctionExists /module/CheckIPOSupported /module/CheckIncludeFileCXX @@ -33,6 +36,7 @@ All Modules /module/CheckIncludeFiles /module/CheckLanguage /module/CheckLibraryExists + /module/CheckPIESupported /module/CheckPrototypeDefinition /module/CheckStructHasMember /module/CheckSymbolExists @@ -41,15 +45,11 @@ All Modules /module/CMakeAddFortranSubdirectory /module/CMakeBackwardCompatibilityCXX /module/CMakeDependentOption - /module/CMakeDetermineVSServicePack - /module/CMakeExpandImportedTargets /module/CMakeFindDependencyMacro /module/CMakeFindFrameworks /module/CMakeFindPackageMode - /module/CMakeForceCompiler /module/CMakeGraphVizOptions /module/CMakePackageConfigHelpers - /module/CMakeParseArguments /module/CMakePrintHelpers /module/CMakePrintSystemInformation /module/CMakePushCheckState @@ -70,6 +70,39 @@ All Modules /module/ExternalProject /module/FeatureSummary /module/FetchContent + /module/FindPackageHandleStandardArgs + /module/FindPackageMessage + /module/FortranCInterface + /module/GenerateExportHeader + /module/GetPrerequisites + /module/GNUInstallDirs + /module/GoogleTest + /module/InstallRequiredSystemLibraries + /module/ProcessorCount + /module/SelectLibraryConfigurations + /module/SquishTestScript + /module/TestBigEndian + /module/TestForANSIForScope + /module/TestForANSIStreamHeaders + /module/TestForSSTREAM + /module/TestForSTDNamespace + /module/UseEcos + /module/UseJavaClassFilelist + /module/UseJava + /module/UseJavaSymlinks + /module/UseSWIG + /module/UsewxWidgets + /module/WriteCompilerDetectionHeader + +Find Modules +^^^^^^^^^^^^ + +These modules search for third-party software. +They are normally called through the :command:`find_package` command. + +.. toctree:: + :maxdepth: 1 + /module/FindALSA /module/FindArmadillo /module/FindASPELL @@ -82,7 +115,6 @@ All Modules /module/FindBZip2 /module/FindCABLE /module/FindCoin3D - /module/FindCUDA /module/FindCups /module/FindCURL /module/FindCurses @@ -97,6 +129,7 @@ All Modules /module/FindFLEX /module/FindFLTK2 /module/FindFLTK + /module/FindFontconfig /module/FindFreetype /module/FindGCCXML /module/FindGDAL @@ -131,6 +164,7 @@ All Modules /module/FindLAPACK /module/FindLATEX /module/FindLibArchive + /module/FindLibinput /module/FindLibLZMA /module/FindLibXml2 /module/FindLibXslt @@ -173,8 +207,6 @@ All Modules /module/FindosgViewer /module/FindosgVolume /module/FindosgWidget - /module/FindPackageHandleStandardArgs - /module/FindPackageMessage /module/FindPatch /module/FindPerlLibs /module/FindPerl @@ -189,11 +221,8 @@ All Modules /module/FindPython /module/FindPython2 /module/FindPython3 - /module/FindPythonInterp - /module/FindPythonLibs /module/FindQt3 /module/FindQt4 - /module/FindQt /module/FindQuickTime /module/FindRTI /module/FindRuby @@ -205,6 +234,7 @@ All Modules /module/FindSDL_ttf /module/FindSelfPackers /module/FindSquish + /module/FindSQLite3 /module/FindSubversion /module/FindSWIG /module/FindTCL @@ -218,39 +248,43 @@ All Modules /module/FindWget /module/FindWish /module/FindwxWidgets - /module/FindwxWindows /module/FindXCTest /module/FindXalanC /module/FindXercesC /module/FindX11 /module/FindXMLRPC /module/FindZLIB - /module/FortranCInterface - /module/GenerateExportHeader - /module/GetPrerequisites - /module/GNUInstallDirs - /module/GoogleTest - /module/InstallRequiredSystemLibraries + +Deprecated Modules +^^^^^^^^^^^^^^^^^^^ + +Deprecated Utility Modules +========================== + +.. toctree:: + :maxdepth: 1 + + /module/CMakeDetermineVSServicePack + /module/CMakeExpandImportedTargets + /module/CMakeForceCompiler + /module/CMakeParseArguments /module/MacroAddFileDependencies - /module/ProcessorCount - /module/SelectLibraryConfigurations - /module/SquishTestScript - /module/TestBigEndian /module/TestCXXAcceptsFlag - /module/TestForANSIForScope - /module/TestForANSIStreamHeaders - /module/TestForSSTREAM - /module/TestForSTDNamespace - /module/UseEcos - /module/UseJavaClassFilelist - /module/UseJava - /module/UseJavaSymlinks /module/UsePkgConfig - /module/UseSWIG - /module/UsewxWidgets /module/Use_wxWindows /module/WriteBasicConfigVersionFile - /module/WriteCompilerDetectionHeader + +Deprecated Find Modules +======================= + +.. toctree:: + :maxdepth: 1 + + /module/FindCUDA + /module/FindPythonInterp + /module/FindPythonLibs + /module/FindQt + /module/FindwxWindows Legacy CPack Modules ==================== diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 2cc52fe1a..409b5b1c7 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -51,6 +51,20 @@ The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used to determine whether to report an error on use of deprecated macros or functions. +Policies Introduced by CMake 3.14 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0088: FindBISON runs bison in CMAKE_CURRENT_BINARY_DIR when executing. </policy/CMP0088> + 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> + Policies Introduced by CMake 3.13 ================================= diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 5c3eb81fc..ef864129b 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -23,6 +23,7 @@ Properties of Global Scope /prop_gbl/AUTORCC_SOURCE_GROUP /prop_gbl/CMAKE_C_KNOWN_FEATURES /prop_gbl/CMAKE_CXX_KNOWN_FEATURES + /prop_gbl/CMAKE_ROLE /prop_gbl/DEBUG_CONFIGURATIONS /prop_gbl/DISABLED_FEATURES /prop_gbl/ENABLED_FEATURES @@ -124,20 +125,25 @@ Properties on Targets /prop_tgt/ARCHIVE_OUTPUT_NAME_CONFIG /prop_tgt/ARCHIVE_OUTPUT_NAME /prop_tgt/AUTOGEN_BUILD_DIR + /prop_tgt/AUTOGEN_ORIGIN_DEPENDS /prop_tgt/AUTOGEN_PARALLEL /prop_tgt/AUTOGEN_TARGET_DEPENDS /prop_tgt/AUTOMOC_COMPILER_PREDEFINES /prop_tgt/AUTOMOC_DEPEND_FILTERS + /prop_tgt/AUTOMOC_EXECUTABLE /prop_tgt/AUTOMOC_MACRO_NAMES /prop_tgt/AUTOMOC_MOC_OPTIONS /prop_tgt/AUTOMOC /prop_tgt/AUTOUIC + /prop_tgt/AUTOUIC_EXECUTABLE /prop_tgt/AUTOUIC_OPTIONS /prop_tgt/AUTOUIC_SEARCH_PATHS /prop_tgt/AUTORCC + /prop_tgt/AUTORCC_EXECUTABLE /prop_tgt/AUTORCC_OPTIONS /prop_tgt/BINARY_DIR /prop_tgt/BUILD_RPATH + /prop_tgt/BUILD_RPATH_USE_ORIGIN /prop_tgt/BUILD_WITH_INSTALL_NAME_DIR /prop_tgt/BUILD_WITH_INSTALL_RPATH /prop_tgt/BUNDLE_EXTENSION @@ -188,6 +194,8 @@ Properties on Targets /prop_tgt/FRAMEWORK /prop_tgt/FRAMEWORK_VERSION /prop_tgt/GENERATOR_FILE_NAME + /prop_tgt/GHS_INTEGRITY_APP + /prop_tgt/GHS_NO_SOURCE_GROUP_FILE /prop_tgt/GNUtoMS /prop_tgt/HAS_CXX /prop_tgt/IMPLICIT_DEPENDS_INCLUDE_TRANSFORM @@ -199,7 +207,6 @@ Properties on Targets /prop_tgt/IMPORTED_LIBNAME_CONFIG /prop_tgt/IMPORTED_LIBNAME /prop_tgt/IMPORTED_LINK_DEPENDENT_LIBRARIES_CONFIG - /prop_tgt/IMPORTED_LINK_DEPENDENT_LIBRARIES_CONFIG /prop_tgt/IMPORTED_LINK_DEPENDENT_LIBRARIES /prop_tgt/IMPORTED_LINK_INTERFACE_LANGUAGES_CONFIG /prop_tgt/IMPORTED_LINK_INTERFACE_LANGUAGES @@ -344,22 +351,22 @@ Properties on Targets /prop_tgt/XCODE_PRODUCT_TYPE /prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER /prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN + /prop_tgt/XCODE_SCHEME_ARGUMENTS + /prop_tgt/XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER + /prop_tgt/XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS + /prop_tgt/XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE + /prop_tgt/XCODE_SCHEME_ENVIRONMENT + /prop_tgt/XCODE_SCHEME_EXECUTABLE + /prop_tgt/XCODE_SCHEME_GUARD_MALLOC + /prop_tgt/XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP + /prop_tgt/XCODE_SCHEME_MALLOC_GUARD_EDGES + /prop_tgt/XCODE_SCHEME_MALLOC_SCRIBBLE + /prop_tgt/XCODE_SCHEME_MALLOC_STACK /prop_tgt/XCODE_SCHEME_THREAD_SANITIZER /prop_tgt/XCODE_SCHEME_THREAD_SANITIZER_STOP /prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER /prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP - /prop_tgt/XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER - /prop_tgt/XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP - /prop_tgt/XCODE_SCHEME_MALLOC_SCRIBBLE - /prop_tgt/XCODE_SCHEME_MALLOC_GUARD_EDGES - /prop_tgt/XCODE_SCHEME_GUARD_MALLOC /prop_tgt/XCODE_SCHEME_ZOMBIE_OBJECTS - /prop_tgt/XCODE_SCHEME_MALLOC_STACK - /prop_tgt/XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE - /prop_tgt/XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS - /prop_tgt/XCODE_SCHEME_EXECUTABLE - /prop_tgt/XCODE_SCHEME_ARGUMENTS - /prop_tgt/XCODE_SCHEME_ENVIRONMENT /prop_tgt/XCTEST .. _`Test Properties`: diff --git a/Help/manual/cmake-qt.7.rst b/Help/manual/cmake-qt.7.rst index 724d8ec2a..d8d61729e 100644 --- a/Help/manual/cmake-qt.7.rst +++ b/Help/manual/cmake-qt.7.rst @@ -44,14 +44,10 @@ Qt Build Tools Qt relies on some bundled tools for code generation, such as ``moc`` for meta-object code generation, ``uic`` for widget layout and population, -and ``rcc`` for virtual filesystem content generation. These tools may be +and ``rcc`` for virtual file system content generation. These tools may be automatically invoked by :manual:`cmake(1)` if the appropriate conditions are met. The automatic tool invocation may be used with both Qt 4 and Qt 5. -The tools are executed as part of a synthesized custom target generated by -CMake. Target dependencies may be added to that custom target by adding them -to the :prop_tgt:`AUTOGEN_TARGET_DEPENDS` target property. - AUTOMOC ^^^^^^^ @@ -214,20 +210,33 @@ overrides options from the :prop_tgt:`AUTORCC_OPTIONS` target property. Source files can be excluded from :prop_tgt:`AUTORCC` processing by enabling :prop_sf:`SKIP_AUTORCC` or the broader :prop_sf:`SKIP_AUTOGEN`. +The ``<ORIGIN>_autogen`` target +=============================== + +The ``moc`` and ``uic`` tools are executed as part of a synthesized +``<ORIGIN>_autogen`` :command:`custom target <add_custom_target>` generated by +CMake. By default that ``<ORIGIN>_autogen`` target inherits the dependencies +of the ``<ORIGIN>`` target (see :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS`). +Target dependencies may be added to the ``<ORIGIN>_autogen`` target by adding +them to the :prop_tgt:`AUTOGEN_TARGET_DEPENDS` target property. + Visual Studio Generators ======================== -When using the :manual:`Visual Studio generators <cmake-generators(7)>`, -CMake uses a ``PRE_BUILD`` :command:`custom command <add_custom_command>` for -:prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`. -If the :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` processing depends on files, -a :command:`custom target <add_custom_target>` is used instead. -This happens when - -- The origin target depends on :prop_sf:`GENERATED` files which aren't excluded - from :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` by :prop_sf:`SKIP_AUTOMOC`, - :prop_sf:`SKIP_AUTOUIC`, :prop_sf:`SKIP_AUTOGEN` or :policy:`CMP0071` +When using the :manual:`Visual Studio generators <cmake-generators(7)>`, CMake +generates a ``PRE_BUILD`` :command:`custom command <add_custom_command>` +instead of the ``<ORIGIN>_autogen`` :command:`custom target <add_custom_target>` +(for :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`). +This isn't always possible though and +an ``<ORIGIN>_autogen`` :command:`custom target <add_custom_target>` is used, +when either + +- the ``<ORIGIN>`` target depends on :prop_sf:`GENERATED` files which aren't + excluded from :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` by + :prop_sf:`SKIP_AUTOMOC`, :prop_sf:`SKIP_AUTOUIC`, :prop_sf:`SKIP_AUTOGEN` + or :policy:`CMP0071` - :prop_tgt:`AUTOGEN_TARGET_DEPENDS` lists a source file +- :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET` is enabled qtmain.lib on Windows ===================== diff --git a/Help/manual/cmake-toolchains.7.rst b/Help/manual/cmake-toolchains.7.rst index 8554e87f9..ba44b7f21 100644 --- a/Help/manual/cmake-toolchains.7.rst +++ b/Help/manual/cmake-toolchains.7.rst @@ -522,3 +522,132 @@ See also target properties: * :prop_tgt:`ANDROID_SECURE_PROPS_PATH` * :prop_tgt:`ANDROID_SKIP_ANT_STEP` * :prop_tgt:`ANDROID_STL_TYPE` + +.. _`Cross Compiling for iOS, tvOS, or watchOS`: + +Cross Compiling for iOS, tvOS, or watchOS +----------------------------------------- + +For cross-compiling to iOS, tvOS, or watchOS, the :generator:`Xcode` +generator is recommended. The :generator:`Unix Makefiles` or +:generator:`Ninja` generators can also be used, but they require the +project to handle more areas like target CPU selection and code signing. + +Any of the three systems can be targetted by setting the +:variable:`CMAKE_SYSTEM_NAME` variable to a value from the table below. +By default, the latest Device SDK is chosen. As for all Apple platforms, +a different SDK (e.g. a simulator) can be selected by setting the +:variable:`CMAKE_OSX_SYSROOT` variable, although this should rarely be +necessary (see :ref:`Switching Between Device and Simulator` below). +A list of available SDKs can be obtained by running ``xcodebuild -showsdks``. + +======= ================= ==================== ================ +OS CMAKE_SYSTEM_NAME Device SDK (default) Simulator SDK +======= ================= ==================== ================ +iOS iOS iphoneos iphonesimulator +tvOS tvOS appletvos appletvsimulator +watchOS watchOS watchos watchsimulator +======= ================= ==================== ================ + +For example, to create a CMake configuration for iOS, the following +command is sufficient: + +.. code-block:: console + + cmake .. -GXcode -DCMAKE_SYSTEM_NAME=iOS + +Variable :variable:`CMAKE_OSX_ARCHITECTURES` can be used to set architectures +for both device and simulator. Variable :variable:`CMAKE_OSX_DEPLOYMENT_TARGET` +can be used to set an iOS/tvOS/watchOS deployment target. + +Next configuration will install fat 5 architectures iOS library +and add the ``-miphoneos-version-min=9.3``/``-mios-simulator-version-min=9.3`` +flags to the compiler: + +.. code-block:: console + + $ cmake -S. -B_builds -GXcode \ + -DCMAKE_SYSTEM_NAME=iOS \ + "-DCMAKE_OSX_ARCHITECTURES=armv7;armv7s;arm64;i386;x86_64" \ + -DCMAKE_OSX_DEPLOYMENT_TARGET=9.3 \ + -DCMAKE_INSTALL_PREFIX=`pwd`/_install \ + -DCMAKE_XCODE_ATTRIBUTE_ONLY_ACTIVE_ARCH=NO \ + -DCMAKE_IOS_INSTALL_COMBINED=YES + +Example: + +.. code-block:: cmake + + # CMakeLists.txt + cmake_minimum_required(VERSION 3.14) + project(foo) + add_library(foo foo.cpp) + install(TARGETS foo DESTINATION lib) + +Install: + +.. code-block:: console + + $ cmake --build _builds --config Release --target install + +Check library: + +.. code-block:: console + + $ lipo -info _install/lib/libfoo.a + Architectures in the fat file: _install/lib/libfoo.a are: i386 armv7 armv7s x86_64 arm64 + +.. code-block:: console + + $ otool -l _install/lib/libfoo.a | grep -A2 LC_VERSION_MIN_IPHONEOS + cmd LC_VERSION_MIN_IPHONEOS + cmdsize 16 + version 9.3 + +Code Signing +^^^^^^^^^^^^ + +Some build artifacts for the embedded Apple platforms require mandatory +code signing. If the :generator:`Xcode` generator is being used and +code signing is required or desired, the developmemt team ID can be +specified via the ``CMAKE_XCODE_ATTRIBUTE_DEVELOPMENT_TEAM`` CMake variable. +This team ID will then be included in the generated Xcode project. +By default, CMake avoids the need for code signing during the internal +configuration phase (i.e compiler ID and feature detection). + +.. _`Switching Between Device and Simulator`: + +Switching Between Device and Simulator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When configuring for any of the embedded platforms, one can target either +real devices or the simulator. Both have their own separate SDK, but CMake +only supports specifying a single SDK for the configuration phase. This +means the developer must select one or the other at configuration time. +When using the :generator:`Xcode` generator, this is less of a limitation +because Xcode still allows you to build for either a device or a simulator, +even though configuration was only performed for one of the two. From +within the Xcode IDE, builds are performed for the selected "destination" +platform. When building from the command line, the desired sdk can be +specified directly by passing a ``-sdk`` option to the underlying build +tool (``xcodebuild``). For example: + +.. code-block:: console + + $ cmake --build ... -- -sdk iphonesimulator + +Please note that checks made during configuration were performed against +the configure-time SDK and might not hold true for other SDKs. Commands +like :command:`find_package`, :command:`find_library`, etc. store and use +details only for the configured SDK/platform, so they can be problematic +if wanting to switch between device and simulator builds. You can follow +the next rules to make device + simulator configuration work: + +- Use explicit ``-l`` linker flag, + e.g. ``target_link_libraries(foo PUBLIC "-lz")`` + +- Use explicit ``-framework`` linker flag, + e.g. ``target_link_libraries(foo PUBLIC "-framework CoreFoundation")`` + +- Use :command:`find_package` only for libraries installed with + :variable:`CMAKE_IOS_INSTALL_COMBINED` feature diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 9dd36ede4..6bb30cba3 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -7,6 +7,14 @@ cmake-variables(7) .. contents:: +This page documents variables that are provided by CMake +or have meaning to CMake when set by project code. + +For general information on variables, see the +:ref:`Variables <CMake Language Variables>` +section in the cmake-language manual. + + Variables that Provide Information ================================== @@ -47,7 +55,6 @@ Variables that Provide Information /variable/CMAKE_GENERATOR_INSTANCE /variable/CMAKE_GENERATOR_PLATFORM /variable/CMAKE_GENERATOR_TOOLSET - /variable/CMAKE_HOME_DIRECTORY /variable/CMAKE_IMPORT_LIBRARY_PREFIX /variable/CMAKE_IMPORT_LIBRARY_SUFFIX /variable/CMAKE_JOB_POOL_COMPILE @@ -95,7 +102,6 @@ Variables that Provide Information /variable/CMAKE_VERBOSE_MAKEFILE /variable/CMAKE_VERSION /variable/CMAKE_VS_DEVENV_COMMAND - /variable/CMAKE_VS_INTEL_Fortran_PROJECT_VERSION /variable/CMAKE_VS_MSBUILD_COMMAND /variable/CMAKE_VS_NsightTegra_VERSION /variable/CMAKE_VS_PLATFORM_NAME @@ -162,6 +168,7 @@ Variables that Change Behavior /variable/CMAKE_FIND_NO_INSTALL_PREFIX /variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY /variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY + /variable/CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS /variable/CMAKE_FIND_PACKAGE_WARN_NO_MODULE /variable/CMAKE_FIND_ROOT_PATH /variable/CMAKE_FIND_ROOT_PATH_MODE_INCLUDE @@ -181,8 +188,8 @@ Variables that Change Behavior /variable/CMAKE_LIBRARY_PATH /variable/CMAKE_LINK_DIRECTORIES_BEFORE /variable/CMAKE_MFC_FLAG + /variable/CMAKE_MAXIMUM_RECURSION_DEPTH /variable/CMAKE_MODULE_PATH - /variable/CMAKE_NOT_USING_CONFIG_FLAGS /variable/CMAKE_POLICY_DEFAULT_CMPNNNN /variable/CMAKE_POLICY_WARNING_CMPNNNN /variable/CMAKE_PREFIX_PATH @@ -209,19 +216,19 @@ Variables that Change Behavior /variable/CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY /variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER /variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN + /variable/CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER + /variable/CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS + /variable/CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE + /variable/CMAKE_XCODE_SCHEME_GUARD_MALLOC + /variable/CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP + /variable/CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES + /variable/CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE + /variable/CMAKE_XCODE_SCHEME_MALLOC_STACK /variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER /variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP /variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER /variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP - /variable/CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER - /variable/CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP - /variable/CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE - /variable/CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES - /variable/CMAKE_XCODE_SCHEME_GUARD_MALLOC /variable/CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS - /variable/CMAKE_XCODE_SCHEME_MALLOC_STACK - /variable/CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE - /variable/CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS /variable/PackageName_ROOT Variables that Describe the System @@ -233,7 +240,6 @@ Variables that Describe the System /variable/ANDROID /variable/APPLE /variable/BORLAND - /variable/CACHE /variable/CMAKE_CL_64 /variable/CMAKE_COMPILER_2005 /variable/CMAKE_HOST_APPLE @@ -252,8 +258,8 @@ Variables that Describe the System /variable/CMAKE_SYSTEM_PROCESSOR /variable/CMAKE_SYSTEM_VERSION /variable/CYGWIN - /variable/ENV /variable/GHS-MULTI + /variable/IOS /variable/MINGW /variable/MSVC /variable/MSVC10 @@ -268,6 +274,7 @@ Variables that Describe the System /variable/MSVC_IDE /variable/MSVC_TOOLSET_VERSION /variable/MSVC_VERSION + /variable/MSYS /variable/UNIX /variable/WIN32 /variable/WINCE @@ -309,6 +316,7 @@ Variables that Control the Build /variable/CMAKE_ANDROID_STL_TYPE /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG + /variable/CMAKE_AUTOGEN_ORIGIN_DEPENDS /variable/CMAKE_AUTOGEN_PARALLEL /variable/CMAKE_AUTOGEN_VERBOSE /variable/CMAKE_AUTOMOC @@ -322,6 +330,7 @@ Variables that Control the Build /variable/CMAKE_AUTOUIC_OPTIONS /variable/CMAKE_AUTOUIC_SEARCH_PATHS /variable/CMAKE_BUILD_RPATH + /variable/CMAKE_BUILD_RPATH_USE_ORIGIN /variable/CMAKE_BUILD_WITH_INSTALL_NAME_DIR /variable/CMAKE_BUILD_WITH_INSTALL_RPATH /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY @@ -337,6 +346,11 @@ Variables that Control the Build /variable/CMAKE_FOLDER /variable/CMAKE_Fortran_FORMAT /variable/CMAKE_Fortran_MODULE_DIRECTORY + /variable/CMAKE_GHS_NO_SOURCE_GROUP_FILE + /variable/CMAKE_GLOBAL_AUTOGEN_TARGET + /variable/CMAKE_GLOBAL_AUTOGEN_TARGET_NAME + /variable/CMAKE_GLOBAL_AUTORCC_TARGET + /variable/CMAKE_GLOBAL_AUTORCC_TARGET_NAME /variable/CMAKE_GNUtoMS /variable/CMAKE_INCLUDE_CURRENT_DIR /variable/CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE @@ -437,7 +451,6 @@ Variables for Languages /variable/CMAKE_Fortran_MODDIR_DEFAULT /variable/CMAKE_Fortran_MODDIR_FLAG /variable/CMAKE_Fortran_MODOUT_FLAG - /variable/CMAKE_INTERNAL_PLATFORM_ABI /variable/CMAKE_LANG_ANDROID_TOOLCHAIN_MACHINE /variable/CMAKE_LANG_ANDROID_TOOLCHAIN_PREFIX /variable/CMAKE_LANG_ANDROID_TOOLCHAIN_SUFFIX @@ -445,15 +458,12 @@ Variables for Languages /variable/CMAKE_LANG_ARCHIVE_CREATE /variable/CMAKE_LANG_ARCHIVE_FINISH /variable/CMAKE_LANG_COMPILER - /variable/CMAKE_LANG_COMPILER_ABI - /variable/CMAKE_LANG_COMPILER_ARCHITECTURE_ID /variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN /variable/CMAKE_LANG_COMPILER_ID /variable/CMAKE_LANG_COMPILER_LOADED /variable/CMAKE_LANG_COMPILER_PREDEFINES_COMMAND /variable/CMAKE_LANG_COMPILER_TARGET /variable/CMAKE_LANG_COMPILER_VERSION - /variable/CMAKE_LANG_COMPILER_VERSION_INTERNAL /variable/CMAKE_LANG_COMPILE_OBJECT /variable/CMAKE_LANG_CREATE_SHARED_LIBRARY /variable/CMAKE_LANG_CREATE_SHARED_MODULE @@ -470,11 +480,6 @@ Variables for Languages /variable/CMAKE_LANG_FLAGS_RELEASE_INIT /variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO /variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT - /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_CONFIG - /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_DEBUG - /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_MINSIZEREL - /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELEASE - /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELWITHDEBINFO /variable/CMAKE_LANG_IGNORE_EXTENSIONS /variable/CMAKE_LANG_IMPLICIT_INCLUDE_DIRECTORIES /variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES @@ -487,7 +492,6 @@ Variables for Languages /variable/CMAKE_LANG_LINKER_WRAPPER_FLAG_SEP /variable/CMAKE_LANG_LINK_EXECUTABLE /variable/CMAKE_LANG_OUTPUT_EXTENSION - /variable/CMAKE_LANG_PLATFORM_ID /variable/CMAKE_LANG_SIMULATE_ID /variable/CMAKE_LANG_SIMULATE_VERSION /variable/CMAKE_LANG_SIZEOF_DATA_PTR @@ -529,7 +533,7 @@ Variables for CTest /variable/CTEST_CUSTOM_POST_TEST /variable/CTEST_CUSTOM_PRE_MEMCHECK /variable/CTEST_CUSTOM_PRE_TEST - /variable/CTEST_CUSTOM_TEST_IGNORE + /variable/CTEST_CUSTOM_TESTS_IGNORE /variable/CTEST_CUSTOM_WARNING_EXCEPTION /variable/CTEST_CUSTOM_WARNING_MATCH /variable/CTEST_CVS_CHECKOUT @@ -562,6 +566,7 @@ Variables for CTest /variable/CTEST_RUN_CURRENT_SCRIPT /variable/CTEST_SCP_COMMAND /variable/CTEST_SITE + /variable/CTEST_SUBMIT_URL /variable/CTEST_SOURCE_DIRECTORY /variable/CTEST_SVN_COMMAND /variable/CTEST_SVN_OPTIONS @@ -589,3 +594,32 @@ Variables for CPack /variable/CPACK_PACKAGING_INSTALL_PREFIX /variable/CPACK_SET_DESTDIR /variable/CPACK_WARN_ON_ABSOLUTE_INSTALL_DESTINATION + +Variable Expansion Operators +============================ + +.. toctree:: + :maxdepth: 1 + + /variable/CACHE + /variable/ENV + +Internal Variables +================== + +CMake has many internal variables. Most of them are undocumented. +Some of them, however, were at some point described as normal +variables, and therefore may be encountered in legacy code. They +are subject to change, and not recommended for use in project code. + +.. toctree:: + :maxdepth: 1 + + /variable/CMAKE_HOME_DIRECTORY + /variable/CMAKE_INTERNAL_PLATFORM_ABI + /variable/CMAKE_LANG_COMPILER_ABI + /variable/CMAKE_LANG_COMPILER_ARCHITECTURE_ID + /variable/CMAKE_LANG_COMPILER_VERSION_INTERNAL + /variable/CMAKE_LANG_PLATFORM_ID + /variable/CMAKE_NOT_USING_CONFIG_FLAGS + /variable/CMAKE_VS_INTEL_Fortran_PROJECT_VERSION diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index b11526c43..f3b81ecb6 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. + -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. +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 + +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: @@ -180,17 +289,54 @@ following options: ``--use-stderr`` Ignored. Behavior is default in CMake >= 3.0. +``-v, --verbose`` + Enable verbose output - if supported - including the build commands to be + executed. + + This option can be omitted if :envvar:`VERBOSE` environment variable or + :variable:`CMAKE_VERBOSE_MAKEFILE` cached variable is set. + + ``--`` Pass remaining options to the native tool. 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 +============ - cmake -E <command> [<options>...] +.. code-block:: shell + + 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: @@ -235,9 +381,10 @@ Available commands are: ``chdir <dir> <cmd> [<arg>...]`` Change the current working directory and run a command. -``compare_files <file1> <file2>`` +``compare_files [--ignore-eol] <file1> <file2>`` Check if ``<file1>`` is same as ``<file2>``. If files are the same, - then returns 0, if not it returns 1. + then returns 0, if not it returns 1. The ``--ignore-eol`` option + implies line-wise comparison and ignores LF/CRLF differences. ``copy <file>... <destination>`` Copy files to ``<destination>`` (either file or directory). @@ -326,7 +473,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 +526,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 6159d7bee..679c5478e 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 e24b10daf..d1bd69b66 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -11,15 +11,16 @@ Synopsis .. parsed-literal:: ctest [<options>] - ctest <path-to-source> <path-to-build> --build-generator <generator> - [<options>...] [-- <build-options>...] [--test-command <test>] + ctest --build-and-test <path-to-source> <path-to-build> + --build-generator <generator> [<options>...] + [--build-options <opts>...] [--test-command <command> [<args>...]] ctest {-D <dashboard> | -M <model> -T <action> | -S <script> | -SP <script>} [-- <dashboard-options>...] 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 +39,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. @@ -109,13 +110,23 @@ Options This option tells CTest to write all its output to a log file. -``-N,--show-only`` +``-N,--show-only[=<format>]`` Disable actual execution of tests. This option tells CTest to list the tests that would be run but not actually run them. Useful in conjunction with the ``-R`` and ``-E`` options. + ``<format>`` can be one of the following values. + + ``human`` + Human-friendly output. This is not guaranteed to be stable. + This is the default. + + ``json-v1`` + Dump the test information in JSON format. + See `Show as JSON Object Model`_. + ``-L <regex>, --label-regex <regex>`` Run tests with labels matching regular expression. @@ -313,10 +324,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 +1081,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`` @@ -1098,55 +1110,58 @@ Configuration settings include: * :module:`CTest` module variable: ``CTEST_CURL_OPTIONS`` ``DropLocation`` - The path on the dashboard server to send the submission. + Legacy option. When ``SubmitURL`` is not set, it is constructed from + ``DropMethod``, ``DropSiteUser``, ``DropSitePassword``, ``DropSite``, and + ``DropLocation``. * `CTest Script`_ variable: :variable:`CTEST_DROP_LOCATION` * :module:`CTest` module variable: ``DROP_LOCATION`` if set, else ``CTEST_DROP_LOCATION`` ``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). + Legacy option. When ``SubmitURL`` is not set, it is constructed from + ``DropMethod``, ``DropSiteUser``, ``DropSitePassword``, ``DropSite``, and + ``DropLocation``. * `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``). + Legacy option. When ``SubmitURL`` is not set, it is constructed from + ``DropMethod``, ``DropSiteUser``, ``DropSitePassword``, ``DropSite``, and + ``DropLocation``. * `CTest Script`_ variable: :variable:`CTEST_DROP_SITE` * :module:`CTest` module variable: ``DROP_SITE`` if set, else ``CTEST_DROP_SITE`` ``DropSitePassword`` - The dashboard server login password, if any - (for ``ftp``, ``http``, and ``https``). + Legacy option. When ``SubmitURL`` is not set, it is constructed from + ``DropMethod``, ``DropSiteUser``, ``DropSitePassword``, ``DropSite``, and + ``DropLocation``. * `CTest Script`_ variable: :variable:`CTEST_DROP_SITE_PASSWORD` * :module:`CTest` module variable: ``DROP_SITE_PASSWORD`` if set, else ``CTEST_DROP_SITE_PASWORD`` ``DropSiteUser`` - The dashboard server login user name, if any - (for ``ftp``, ``http``, and ``https``). + Legacy option. When ``SubmitURL`` is not set, it is constructed from + ``DropMethod``, ``DropSiteUser``, ``DropSitePassword``, ``DropSite``, and + ``DropLocation``. * `CTest Script`_ variable: :variable:`CTEST_DROP_SITE_USER` * :module:`CTest` module variable: ``DROP_SITE_USER`` if set, 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`` @@ -1159,14 +1174,80 @@ Configuration settings include: * :module:`CTest` module variable: ``SITE``, initialized by the :command:`site_name` command +``SubmitURL`` + The ``http`` or ``https`` URL of the dashboard server to send the submission + to. + + * `CTest Script`_ variable: :variable:`CTEST_SUBMIT_URL` + * :module:`CTest` module variable: ``SUBMIT_URL`` if set, + else ``CTEST_SUBMIT_URL`` + ``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, else ``CTEST_TRIGGER_SITE`` +.. _`Show as JSON Object Model`: + +Show as JSON Object Model +========================= + +When the ``--show-only=json-v1`` command line option is given, the test +information is output in JSON format. Version 1.0 of the JSON object +model is defined as follows: + +``kind`` + The string "ctestInfo". + +``version`` + A JSON object specifying the version components. Its members are + + ``major`` + A non-negative integer specifying the major version component. + ``minor`` + A non-negative integer specifying the minor version component. + +``backtraceGraph`` + JSON object representing backtrace information with the + following members: + + ``commands`` + List of command names. + ``files`` + List of file names. + ``nodes`` + List of node JSON objects with members: + + ``command`` + Index into the ``commands`` member of the ``backtraceGraph``. + ``file`` + Index into the ``files`` member of the ``backtraceGraph``. + ``line`` + Line number in the file where the backtrace was added. + ``parent`` + Index into the ``nodes`` member of the ``backtraceGraph`` + representing the parent in the graph. + +``tests`` + A JSON array listing information about each test. Each entry + is a JSON object with members: + + ``name`` + Test name. + ``config`` + Configuration that the test can run on. + Empty string means any config. + ``command`` + List where the first element is the test command and the + remaining elements are the command arguments. + ``backtrace`` + Index into the ``nodes`` member of the ``backtraceGraph``. + ``properties`` + Test properties. + Can contain keys for each of the supported test properties. + See Also ======== |