diff options
Diffstat (limited to 'Help/manual')
| -rw-r--r-- | Help/manual/cmake-developer.7.rst | 136 | ||||
| -rw-r--r-- | Help/manual/cmake-file-api.7.rst | 157 |
2 files changed, 250 insertions, 43 deletions
diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst index 85ed935..af9a8ab 100644 --- a/Help/manual/cmake-developer.7.rst +++ b/Help/manual/cmake-developer.7.rst @@ -23,15 +23,14 @@ in turn link to developer guides for CMake itself. Find Modules ============ -A "find module" is a ``Find<PackageName>.cmake`` file to be loaded -by the :command:`find_package` command when invoked for ``<PackageName>``. +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 -exists on the system, set the ``<PackageName>_FOUND`` variable to reflect -this and provide any variables, macros and imported targets required to -use the package. A find module is useful in cases where an upstream -library does not provide a -:ref:`config file package <Config File Packages>`. +The primary task of a find module is to determine whether a package is +available, set the ``<PackageName>_FOUND`` variable to reflect this and +provide any variables, macros and imported targets required to use the +package. A find module is useful in cases where an upstream library does +not provide a :ref:`config file package <Config File Packages>`. The traditional approach is to use variables for everything, including libraries and executables: see the `Standard Variable Names`_ section @@ -91,55 +90,92 @@ Standard Variable Names For a ``FindXxx.cmake`` module that takes the approach of setting variables (either instead of or in addition to creating imported targets), the following variable names should be used to keep things -consistent between find modules. Note that all variables start with -``Xxx_`` to make sure they do not interfere with other find modules; the -same consideration applies to macros, functions and imported targets. +consistent between Find modules. Note that all variables start with +``Xxx_``, which (unless otherwise noted) must match exactly the name +of the ``FindXxx.cmake`` file, including upper/lowercase. +This prefix on the variable names ensures that they do not conflict with +variables of other Find modules. The same pattern should also be followed +for any macros, functions and imported targets defined by the Find module. ``Xxx_INCLUDE_DIRS`` The final set of include directories listed in one variable for use by - client code. This should not be a cache entry. + client code. This should not be a cache entry (note that this also means + this variable should not be used as the result variable of a + :command:`find_path` command - see ``Xxx_INCLUDE_DIR`` below for that). ``Xxx_LIBRARIES`` - The libraries to link against to use Xxx. These should include full - paths. This should not be a cache entry. + The libraries to use with the module. These may be CMake targets, full + absolute paths to a library binary or the name of a library that the + linker must find in its search path. This should not be a cache entry + (note that this also means this variable should not be used as the + result variable of a :command:`find_library` command - see + ``Xxx_LIBRARY`` below for that). ``Xxx_DEFINITIONS`` - Definitions to use when compiling code that uses Xxx. This really - shouldn't include options such as ``-DHAS_JPEG`` that a client + The compile definitions to use when compiling code that uses the module. + This really shouldn't include options such as ``-DHAS_JPEG`` that a client source-code file uses to decide whether to ``#include <jpeg.h>`` ``Xxx_EXECUTABLE`` - Where to find the Xxx tool. - -``Xxx_Yyy_EXECUTABLE`` - Where to find the Yyy tool that comes with Xxx. + The full absolute path to an executable. In this case, ``Xxx`` might not + be the name of the module, it might be the name of the tool (usually + converted to all uppercase), assuming that tool has such a well-known name + that it is unlikely that another tool with the same name exists. It would + be appropriate to use this as the result variable of a + :command:`find_program` command. + +``Xxx_YYY_EXECUTABLE`` + Similar to ``Xxx_EXECUTABLE`` except here the ``Xxx`` is always the module + name and ``YYY`` is the tool name (again, usually fully uppercase). + Prefer this form if the tool name is not very widely known or has the + potential to clash with another tool. For greater consistency, also + prefer this form if the module provides more than one executable. ``Xxx_LIBRARY_DIRS`` Optionally, the final set of library directories listed in one - variable for use by client code. This should not be a cache entry. + variable for use by client code. This should not be a cache entry. ``Xxx_ROOT_DIR`` - Where to find the base directory of Xxx. - -``Xxx_VERSION_Yy`` - Expect Version Yy if true. Make sure at most one of these is ever true. - -``Xxx_WRAP_Yy`` - If False, do not try to use the relevant CMake wrapping command. + Where to find the base directory of the module. + +``Xxx_VERSION_VV`` + Variables of this form specify whether the ``Xxx`` module being provided + is version ``VV`` of the module. There should not be more than one + variable of this form set to true for a given module. For example, a + module ``Barry`` might have evolved over many years and gone through a + number of different major versions. Version 3 of the ``Barry`` module + might set the variable ``Barry_VERSION_3`` to true, whereas an older + version of the module might set ``Barry_VERSION_2`` to true instead. + It would be an error for both ``Barry_VERSION_3`` and ``Barry_VERSION_2`` + to both be set to true. + +``Xxx_WRAP_YY`` + When a variable of this form is set to false, it indicates that the + relevant wrapping command should not be used. The wrapping command + depends on the module, it may be implied by the module name or it might + be specified by the ``YY`` part of the variable. ``Xxx_Yy_FOUND`` - If False, optional Yy part of Xxx system is not available. + For variables of this form, ``Yy`` is the name of a component for the + module. It should match exactly one of the valid component names that + may be passed to the :command:`find_package` command for the module. + If a variable of this form is set to false, it means that the ``Yy`` + component of module ``Xxx`` was not found or is not available. + Variables of this form would typically be used for optional components + so that the caller can check whether an optional component is available. ``Xxx_FOUND`` - Set to false, or undefined, if we haven't found, or don't want to use - Xxx. + When the :command:`find_package` command returns to the caller, this + variable will be set to true if the module was deemed to have been found + successfully. ``Xxx_NOT_FOUND_MESSAGE`` Should be set by config-files in the case that it has set ``Xxx_FOUND`` to FALSE. The contained message will be printed by the :command:`find_package` command and by - ``find_package_handle_standard_args()`` to inform the user about the - problem. + :command:`find_package_handle_standard_args` to inform the user about the + problem. Use this instead of calling :command:`message` directly to + report a reason for failing to find the module or package. ``Xxx_RUNTIME_LIBRARY_DIRS`` Optionally, the runtime library search path for use when running an @@ -160,23 +196,36 @@ same consideration applies to macros, functions and imported targets. ``Xxx_VERSION_PATCH`` The patch version of the package found, if any. -The following names should not usually be used in CMakeLists.txt files, but -are typically cache variables for users to edit and control the -behaviour of find modules (like entering the path to a library manually) +The following names should not usually be used in ``CMakeLists.txt`` files. +They are intended for use by Find modules to specify and cache the locations +of specific files or directories. Users are typically able to set and edit +these variables to control the behavior of Find modules (like entering the +path to a library manually): ``Xxx_LIBRARY`` - The path of the Xxx library (as used with :command:`find_library`, for - example). + The path of the library. Use this form only when the module provides a + single library. It is appropriate to use this as the result variable + in a :command:`find_library` command. ``Xxx_Yy_LIBRARY`` - The path of the Yy library that is part of the Xxx system. It may or - may not be required to use Xxx. + The path of library ``Yy`` provided by the module ``Xxx``. Use this form + when the module provides more than one library or where other modules may + also provide a library of the same name. It is also appropriate to use + this form as the result variable in a :command:`find_library` command. ``Xxx_INCLUDE_DIR`` - Where to find headers for using the Xxx library. + When the module provides only a single library, this variable can be used + to specify where to find headers for using the library (or more accurately, + the path that consumers of the library should add to their header search + path). It would be appropriate to use this as the result variable in a + :command:`find_path` command. ``Xxx_Yy_INCLUDE_DIR`` - Where to find headers for using the Yy library of the Xxx system. + If the module provides more than one library or where other modules may + also provide a library of the same name, this form is recommended for + specifying where to find headers for using library ``Yy`` provided by + the module. Again, it would be appropriate to use this as the result + variable in a :command:`find_path` command. To prevent users being overwhelmed with settings to configure, try to keep as many options as possible out of the cache, leaving at least one @@ -185,7 +234,8 @@ not-found library (e.g. ``Xxx_ROOT_DIR``). For the same reason, mark most cache options as advanced. For packages which provide both debug and release binaries, it is common to create cache variables with a ``_LIBRARY_<CONFIG>`` suffix, such as ``Foo_LIBRARY_RELEASE`` and -``Foo_LIBRARY_DEBUG``. +``Foo_LIBRARY_DEBUG``. The :module:`SelectLibraryConfigurations` module +can be helpful for such cases. While these are the standard variable names, you should provide backwards compatibility for any old names that were actually in use. diff --git a/Help/manual/cmake-file-api.7.rst b/Help/manual/cmake-file-api.7.rst index 6876e1c..89739b7 100644 --- a/Help/manual/cmake-file-api.7.rst +++ b/Help/manual/cmake-file-api.7.rst @@ -1154,3 +1154,160 @@ The members specific to ``cmakeFiles`` objects are: ``isCMake`` Optional member that is present with boolean value ``true`` if the path specifies a file in the CMake installation. + +Object Kind "toolchains" +------------------------ + +The ``toolchains`` object kind lists properties of the toolchains used during +the build. These include the language, compiler path, ID, and version. + +There is only one ``toolchains`` object major version, version 1. + +"toolchains" version 1 +^^^^^^^^^^^^^^^^^^^^^^ + +``toolchains`` object version 1 is a JSON object: + +.. code-block:: json + + { + "kind": "toolchains", + "version": { "major": 1, "minor": 0 }, + "toolchains": [ + { + "language": "C", + "compiler": { + "path": "/usr/bin/cc", + "id": "GNU", + "version": "9.3.0", + "implicit": { + "includeDirectories": [ + "/usr/lib/gcc/x86_64-linux-gnu/9/include", + "/usr/local/include", + "/usr/include/x86_64-linux-gnu", + "/usr/include" + ], + "linkDirectories": [ + "/usr/lib/gcc/x86_64-linux-gnu/9", + "/usr/lib/x86_64-linux-gnu", + "/usr/lib", + "/lib/x86_64-linux-gnu", + "/lib" + ], + "linkFrameworkDirectories": [], + "linkLibraries": [ "gcc", "gcc_s", "c", "gcc", "gcc_s" ] + } + }, + "sourceFileExtensions": [ "c", "m" ] + }, + { + "language": "CXX", + "compiler": { + "path": "/usr/bin/c++", + "id": "GNU", + "version": "9.3.0", + "implicit": { + "includeDirectories": [ + "/usr/include/c++/9", + "/usr/include/x86_64-linux-gnu/c++/9", + "/usr/include/c++/9/backward", + "/usr/lib/gcc/x86_64-linux-gnu/9/include", + "/usr/local/include", + "/usr/include/x86_64-linux-gnu", + "/usr/include" + ], + "linkDirectories": [ + "/usr/lib/gcc/x86_64-linux-gnu/9", + "/usr/lib/x86_64-linux-gnu", + "/usr/lib", + "/lib/x86_64-linux-gnu", + "/lib" + ], + "linkFrameworkDirectories": [], + "linkLibraries": [ + "stdc++", "m", "gcc_s", "gcc", "c", "gcc_s", "gcc" + ] + } + }, + "sourceFileExtensions": [ + "C", "M", "c++", "cc", "cpp", "cxx", "mm", "CPP" + ] + } + ] + } + +The members specific to ``toolchains`` objects are: + +``toolchains`` + A JSON array whose entries are each a JSON object specifying a toolchain + associated with a particular language. The members of each entry are: + + ``language`` + A JSON string specifying the toolchain language, like C or CXX. Language + names are the same as langauge names that can be passed to the + :command:`project` command. Because CMake only supports a single toolchain + per language, this field can be used as a key. + + ``compiler`` + A JSON object containing members: + + ``path`` + Optional member that is present when the + :variable:`CMAKE_<LANG>_COMPILER` variable is defined for the current + language. Its value is a JSON string holding the path to the compiler. + + ``id`` + Optional member that is present when the + :variable:`CMAKE_<LANG>_COMPILER_ID` variable is defined for the current + language. Its value is a JSON string holding the ID (GNU, MSVC, etc.) of + the compiler. + + ``version`` + Optional member that is present when the + :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable is defined for the + current language. Its value is a JSON string holding the version of the + compiler. + + ``target`` + Optional member that is present when the + :variable:`CMAKE_<LANG>_COMPILER_TARGET` variable is defined for the + current language. Its value is a JSON string holding the cross-compiling + target of the compiler. + + ``implicit`` + A JSON object containing members: + + ``includeDirectories`` + Optional member that is present when the + :variable:`CMAKE_<LANG>_IMPLICIT_INCLUDE_DIRECTORIES` variable is + defined for the current language. Its value is a JSON array of JSON + strings where each string holds a path to an implicit include + directory for the compiler. + + ``linkDirectories`` + Optional member that is present when the + :variable:`CMAKE_<LANG>_IMPLICIT_LINK_DIRECTORIES` variable is + defined for the current language. Its value is a JSON array of JSON + strings where each string holds a path to an implicit link directory + for the compiler. + + ``linkFrameworkDirectories`` + Optional member that is present when the + :variable:`CMAKE_<LANG>_IMPLICIT_LINK_FRAMEWORK_DIRECTORIES` variable + is defined for the current language. Its value is a JSON array of JSON + strings where each string holds a path to an implicit link framework + directory for the compiler. + + ``linkLibraries`` + Optional member that is present when the + :variable:`CMAKE_<LANG>_IMPLICIT_LINK_LIBRARIES` variable is defined + for the current language. Its value is a JSON array of JSON strings + where each string holds a path to an implicit link library for the + compiler. + + ``sourceFileExtensions`` + Optional member that is present when the + :variable:`CMAKE_<LANG>_SOURCE_FILE_EXTENSIONS` variable is defined for + the current language. Its value is a JSON array of JSON strings where each + each string holds a file extension (without the leading dot) for the + language. |