mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-01-06 21:59:54 -06:00
Code Issues Packages Projects Releases Wiki Activity

Help: Use signature directive for cmake_language command

Browse Source
This commit is contained in:
Matthew Woehlke
2023-02-27 11:08:32 -05:00
committed by Brad King
parent 74e3c1d313
commit cd33f461a6
1 changed files with 146 additions and 159 deletions
Download Patch File Download Diff File Expand all files Collapse all files

305
Help/command/cmake_language.rst
View File

@@ -27,163 +27,155 @@ those created via the :command:`macro` or :command:`function` commands.
Calling Commands Calling Commands
^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^
.. _CALL: .. signature::
.. code-block:: cmake
cmake_language(CALL <command> [<arg>...]) cmake_language(CALL <command> [<arg>...])
Calls the named ``<command>`` with the given arguments (if any). Calls the named ``<command>`` with the given arguments (if any).
For example, the code: For example, the code:
.. code-block:: cmake .. code-block:: cmake
set(message_command "message") set(message_command "message")
cmake_language(CALL ${message_command} STATUS "Hello World!") cmake_language(CALL ${message_command} STATUS "Hello World!")
is equivalent to is equivalent to
.. code-block:: cmake .. code-block:: cmake
message(STATUS "Hello World!") message(STATUS "Hello World!")
.. note:: .. note::
To ensure consistency of the code, the following commands are not allowed: To ensure consistency of the code, the following commands are not allowed:
* ``if`` / ``elseif`` / ``else`` / ``endif`` * ``if`` / ``elseif`` / ``else`` / ``endif``
* ``block`` / ``endblock`` * ``block`` / ``endblock``
* ``while`` / ``endwhile`` * ``while`` / ``endwhile``
* ``foreach`` / ``endforeach`` * ``foreach`` / ``endforeach``
* ``function`` / ``endfunction`` * ``function`` / ``endfunction``
* ``macro`` / ``endmacro`` * ``macro`` / ``endmacro``
Evaluating Code Evaluating Code
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
.. _EVAL: .. signature::
.. code-block:: cmake
cmake_language(EVAL CODE <code>...) cmake_language(EVAL CODE <code>...)
:target: EVAL
Evaluates the ``<code>...`` as CMake code. Evaluates the ``<code>...`` as CMake code.
For example, the code: For example, the code:
.. code-block:: cmake .. code-block:: cmake
set(A TRUE) set(A TRUE)
set(B TRUE) set(B TRUE)
set(C TRUE) set(C TRUE)
set(condition "(A AND B) OR C") set(condition "(A AND B) OR C")
cmake_language(EVAL CODE " cmake_language(EVAL CODE "
if (${condition}) if (${condition})
message(STATUS TRUE) message(STATUS TRUE)
else() else()
message(STATUS FALSE) message(STATUS FALSE)
endif()" endif()"
) )
is equivalent to is equivalent to
.. code-block:: cmake .. code-block:: cmake
set(A TRUE) set(A TRUE)
set(B TRUE) set(B TRUE)
set(C TRUE) set(C TRUE)
set(condition "(A AND B) OR C") set(condition "(A AND B) OR C")
file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/eval.cmake " file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/eval.cmake "
if (${condition}) if (${condition})
message(STATUS TRUE) message(STATUS TRUE)
else() else()
message(STATUS FALSE) message(STATUS FALSE)
endif()" endif()"
) )
include(${CMAKE_CURRENT_BINARY_DIR}/eval.cmake) include(${CMAKE_CURRENT_BINARY_DIR}/eval.cmake)
Deferring Calls Deferring Calls
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
.. versionadded:: 3.19 .. versionadded:: 3.19
.. _DEFER: .. signature::
.. code-block:: cmake
cmake_language(DEFER <options>... CALL <command> [<arg>...]) cmake_language(DEFER <options>... CALL <command> [<arg>...])
Schedules a call to the named ``<command>`` with the given arguments (if any) Schedules a call to the named ``<command>`` with the given arguments (if any)
to occur at a later time. By default, deferred calls are executed as if to occur at a later time. By default, deferred calls are executed as if
written at the end of the current directory's ``CMakeLists.txt`` file, written at the end of the current directory's ``CMakeLists.txt`` file,
except that they run even after a :command:`return` call. Variable except that they run even after a :command:`return` call. Variable
references in arguments are evaluated at the time the deferred call is references in arguments are evaluated at the time the deferred call is
executed. executed.
The options are: The options are:
``DIRECTORY <dir>`` ``DIRECTORY <dir>``
Schedule the call for the end of the given directory instead of the Schedule the call for the end of the given directory instead of the
current directory. The ``<dir>`` may reference either a source current directory. The ``<dir>`` may reference either a source
directory or its corresponding binary directory. Relative paths are directory or its corresponding binary directory. Relative paths are
treated as relative to the current source directory. treated as relative to the current source directory.
The given directory must be known to CMake, being either the top-level The given directory must be known to CMake, being either the top-level
directory or one added by :command:`add_subdirectory`. Furthermore, directory or one added by :command:`add_subdirectory`. Furthermore,
the given directory must not yet be finished processing. This means the given directory must not yet be finished processing. This means
it can be the current directory or one of its ancestors. it can be the current directory or one of its ancestors.
``ID <id>`` ``ID <id>``
Specify an identification for the deferred call. Specify an identification for the deferred call.
The ``<id>`` may not be empty and may not begin with a capital letter ``A-Z``. The ``<id>`` may not be empty and may not begin with a capital letter ``A-Z``.
The ``<id>`` may begin with an underscore (``_``) only if it was generated The ``<id>`` may begin with an underscore (``_``) only if it was generated
automatically by an earlier call that used ``ID_VAR`` to get the id. automatically by an earlier call that used ``ID_VAR`` to get the id.
``ID_VAR <var>`` ``ID_VAR <var>``
Specify a variable in which to store the identification for the Specify a variable in which to store the identification for the
deferred call. If ``ID <id>`` is not given, a new identification deferred call. If ``ID <id>`` is not given, a new identification
will be generated and the generated id will start with an underscore (``_``). will be generated and the generated id will start with an underscore (``_``).
The currently scheduled list of deferred calls may be retrieved: The currently scheduled list of deferred calls may be retrieved:
.. code-block:: cmake .. code-block:: cmake
cmake_language(DEFER [DIRECTORY <dir>] GET_CALL_IDS <var>) cmake_language(DEFER [DIRECTORY <dir>] GET_CALL_IDS <var>)
This will store in ``<var>`` a :ref:`semicolon-separated list <CMake Language This will store in ``<var>`` a :ref:`semicolon-separated list <CMake Language
Lists>` of deferred call ids. The ids are for the directory scope in which Lists>` of deferred call ids. The ids are for the directory scope in which
the calls have been deferred to (i.e. where they will be executed), which can the calls have been deferred to (i.e. where they will be executed), which can
be different to the scope in which they were created. The ``DIRECTORY`` be different to the scope in which they were created. The ``DIRECTORY``
option can be used to specify the scope for which to retrieve the call ids. option can be used to specify the scope for which to retrieve the call ids.
If that option is not given, the call ids for the current directory scope will If that option is not given, the call ids for the current directory scope
be returned. will be returned.
Details of a specific call may be retrieved from its id: Details of a specific call may be retrieved from its id:
.. code-block:: cmake .. code-block:: cmake
cmake_language(DEFER [DIRECTORY <dir>] GET_CALL <id> <var>) cmake_language(DEFER [DIRECTORY <dir>] GET_CALL <id> <var>)
This will store in ``<var>`` a :ref:`semicolon-separated list <CMake Language This will store in ``<var>`` a :ref:`semicolon-separated list <CMake Language
Lists>` in which the first element is the name of the command to be Lists>` in which the first element is the name of the command to be
called, and the remaining elements are its unevaluated arguments (any called, and the remaining elements are its unevaluated arguments (any
contained ``;`` characters are included literally and cannot be distinguished contained ``;`` characters are included literally and cannot be distinguished
from multiple arguments). If multiple calls are scheduled with the same id, from multiple arguments). If multiple calls are scheduled with the same id,
this retrieves the first one. If no call is scheduled with the given id in this retrieves the first one. If no call is scheduled with the given id in
the specified ``DIRECTORY`` scope (or the current directory scope if no the specified ``DIRECTORY`` scope (or the current directory scope if no
``DIRECTORY`` option is given), this stores an empty string in the variable. ``DIRECTORY`` option is given), this stores an empty string in the variable.
Deferred calls may be canceled by their id: Deferred calls may be canceled by their id:
.. code-block:: cmake .. code-block:: cmake
cmake_language(DEFER [DIRECTORY <dir>] CANCEL_CALL <id>...) cmake_language(DEFER [DIRECTORY <dir>] CANCEL_CALL <id>...)
This cancels all deferred calls matching any of the given ids in the specified This cancels all deferred calls matching any of the given ids in the specified
``DIRECTORY`` scope (or the current directory scope if no ``DIRECTORY`` option ``DIRECTORY`` scope (or the current directory scope if no ``DIRECTORY`` option
is given). Unknown ids are silently ignored. is given). Unknown ids are silently ignored.
Deferred Call Examples Deferred Call Examples
"""""""""""""""""""""" """"""""""""""""""""""
@@ -229,8 +221,6 @@ also prints::
Deferred Message 1 Deferred Message 1
Deferred Message 2 Deferred Message 2
.. _SET_DEPENDENCY_PROVIDER:
.. _dependency_providers: .. _dependency_providers:
Dependency Providers Dependency Providers
@@ -241,51 +231,50 @@ Dependency Providers
.. note:: A high-level introduction to this feature can be found in the .. note:: A high-level introduction to this feature can be found in the
:ref:`Using Dependencies Guide <dependency_providers_overview>`. :ref:`Using Dependencies Guide <dependency_providers_overview>`.
.. code-block:: cmake .. signature::
cmake_language(SET_DEPENDENCY_PROVIDER <command> cmake_language(SET_DEPENDENCY_PROVIDER <command>
SUPPORTED_METHODS <methods>...) SUPPORTED_METHODS <methods>...)
When a call is made to :command:`find_package` or When a call is made to :command:`find_package` or
:command:`FetchContent_MakeAvailable`, the call may be forwarded to a :command:`FetchContent_MakeAvailable`, the call may be forwarded to a
dependency provider which then has the opportunity to fulfill the request. dependency provider which then has the opportunity to fulfill the request.
If the request is for one of the ``<methods>`` specified when the provider If the request is for one of the ``<methods>`` specified when the provider
was set, CMake calls the provider's ``<command>`` with a set of was set, CMake calls the provider's ``<command>`` with a set of
method-specific arguments. If the provider does not fulfill the request, method-specific arguments. If the provider does not fulfill the request,
or if the provider doesn't support the request's method, or no provider or if the provider doesn't support the request's method, or no provider
is set, the built-in :command:`find_package` or is set, the built-in :command:`find_package` or
:command:`FetchContent_MakeAvailable` implementation is used to fulfill :command:`FetchContent_MakeAvailable` implementation is used to fulfill
the request in the usual way. the request in the usual way.
One or more of the following values can be specified for the ``<methods>`` One or more of the following values can be specified for the ``<methods>``
when setting the provider: when setting the provider:
``FIND_PACKAGE`` ``FIND_PACKAGE``
The provider command accepts :command:`find_package` requests. The provider command accepts :command:`find_package` requests.
``FETCHCONTENT_MAKEAVAILABLE_SERIAL`` ``FETCHCONTENT_MAKEAVAILABLE_SERIAL``
The provider command accepts :command:`FetchContent_MakeAvailable` The provider command accepts :command:`FetchContent_MakeAvailable`
requests. It expects each dependency to be fed to the provider command requests. It expects each dependency to be fed to the provider command
one at a time, not the whole list in one go. one at a time, not the whole list in one go.
Only one provider can be set at any point in time. If a provider is already Only one provider can be set at any point in time. If a provider is already
set when ``cmake_language(SET_DEPENDENCY_PROVIDER)`` is called, the new set when ``cmake_language(SET_DEPENDENCY_PROVIDER)`` is called, the new
provider replaces the previously set one. The specified ``<command>`` must provider replaces the previously set one. The specified ``<command>`` must
already exist when ``cmake_language(SET_DEPENDENCY_PROVIDER)`` is called. already exist when ``cmake_language(SET_DEPENDENCY_PROVIDER)`` is called.
As a special case, providing an empty string for the ``<command>`` and no As a special case, providing an empty string for the ``<command>`` and no
``<methods>`` will discard any previously set provider. ``<methods>`` will discard any previously set provider.
The dependency provider can only be set while processing one of the files The dependency provider can only be set while processing one of the files
specified by the :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable. specified by the :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable.
Thus, dependency providers can only be set as part of the first call to Thus, dependency providers can only be set as part of the first call to
:command:`project`. Calling ``cmake_language(SET_DEPENDENCY_PROVIDER)`` :command:`project`. Calling ``cmake_language(SET_DEPENDENCY_PROVIDER)``
outside of that context will result in an error. outside of that context will result in an error.
.. note:: .. note::
The choice of dependency provider should always be under the user's control. The choice of dependency provider should always be under the user's control.
As a convenience, a project may choose to provide a file that users can As a convenience, a project may choose to provide a file that users can
list in their :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable, but list in their :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable, but
the use of such a file should always be the user's choice. the use of such a file should always be the user's choice.
Provider commands Provider commands
""""""""""""""""" """""""""""""""""
@@ -499,23 +488,21 @@ Getting current message log level
.. versionadded:: 3.25 .. versionadded:: 3.25
.. _GET_MESSAGE_LOG_LEVEL:
.. _query_message_log_level: .. _query_message_log_level:
.. code-block:: cmake .. signature::
cmake_language(GET_MESSAGE_LOG_LEVEL <output_variable>) cmake_language(GET_MESSAGE_LOG_LEVEL <output_variable>)
Writes the current :command:`message` logging level Writes the current :command:`message` logging level
into the given ``<output_variable>``. into the given ``<output_variable>``.
See :command:`message` for the possible logging levels. See :command:`message` for the possible logging levels.
The current message logging level can be set either using the The current message logging level can be set either using the
:option:`--log-level <cmake --log-level>` :option:`--log-level <cmake --log-level>`
command line option of the :manual:`cmake(1)` program or using command line option of the :manual:`cmake(1)` program or using
the :variable:`CMAKE_MESSAGE_LOG_LEVEL` variable. the :variable:`CMAKE_MESSAGE_LOG_LEVEL` variable.
If both the command line option and the variable are set, the command line If both the command line option and the variable are set, the command line
option takes precedence. If neither are set, the default logging level option takes precedence. If neither are set, the default logging level
is returned. is returned.