<!DOCTYPE html> | |
<html xmlns="http://www.w3.org/1999/xhtml" lang="en"> | |
<head> | |
<meta charset="utf-8" /> | |
<title>cmake_language — CMake 3.23.1 Documentation</title> | |
<link rel="stylesheet" href="../_static/cmake.css" type="text/css" /> | |
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> | |
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script> | |
<script type="text/javascript" src="../_static/jquery.js"></script> | |
<script type="text/javascript" src="../_static/underscore.js"></script> | |
<script type="text/javascript" src="../_static/doctools.js"></script> | |
<script type="text/javascript" src="../_static/language_data.js"></script> | |
<link rel="shortcut icon" href="../_static/cmake-favicon.ico"/> | |
<link rel="index" title="Index" href="../genindex.html" /> | |
<link rel="search" title="Search" href="../search.html" /> | |
<link rel="next" title="cmake_minimum_required" href="cmake_minimum_required.html" /> | |
<link rel="prev" title="cmake_host_system_information" href="cmake_host_system_information.html" /> | |
</head><body> | |
<div class="related" role="navigation" aria-label="related navigation"> | |
<h3>Navigation</h3> | |
<ul> | |
<li class="right" style="margin-right: 10px"> | |
<a href="../genindex.html" title="General Index" | |
accesskey="I">index</a></li> | |
<li class="right" > | |
<a href="cmake_minimum_required.html" title="cmake_minimum_required" | |
accesskey="N">next</a> |</li> | |
<li class="right" > | |
<a href="cmake_host_system_information.html" title="cmake_host_system_information" | |
accesskey="P">previous</a> |</li> | |
<li> | |
<img src="../_static/cmake-logo-16.png" alt="" | |
style="vertical-align: middle; margin-top: -2px" /> | |
</li> | |
<li> | |
<a href="https://cmake.org/">CMake</a> » | |
</li> | |
<li> | |
<a href="../index.html">3.23.1 Documentation</a> » | |
</li> | |
<li class="nav-item nav-item-1"><a href="../manual/cmake-commands.7.html" accesskey="U">cmake-commands(7)</a> »</li> | |
</ul> | |
</div> | |
<div class="document"> | |
<div class="documentwrapper"> | |
<div class="bodywrapper"> | |
<div class="body" role="main"> | |
<div class="section" id="cmake-language"> | |
<span id="command:cmake_language"></span><h1>cmake_language<a class="headerlink" href="#cmake-language" title="Permalink to this headline">¶</a></h1> | |
<div class="versionadded"> | |
<p><span class="versionmodified added">New in version 3.18.</span></p> | |
</div> | |
<p>Call meta-operations on CMake commands.</p> | |
<div class="section" id="synopsis"> | |
<h2>Synopsis<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2> | |
<pre class="literal-block">cmake_language(<a class="reference internal" href="#call">CALL</a> <command> [<arg>...]) | |
cmake_language(<a class="reference internal" href="#eval">EVAL</a> CODE <code>...) | |
cmake_language(<a class="reference internal" href="#defer">DEFER</a> <options>... CALL <command> [<arg>...])</pre> | |
</div> | |
<div class="section" id="introduction"> | |
<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2> | |
<p>This command will call meta-operations on built-in CMake commands or | |
those created via the <span class="target" id="index-0-command:macro"></span><a class="reference internal" href="macro.html#command:macro" title="macro"><code class="xref cmake cmake-command docutils literal notranslate"><span class="pre">macro()</span></code></a> or <span class="target" id="index-0-command:function"></span><a class="reference internal" href="function.html#command:function" title="function"><code class="xref cmake cmake-command docutils literal notranslate"><span class="pre">function()</span></code></a> commands.</p> | |
<p><code class="docutils literal notranslate"><span class="pre">cmake_language</span></code> does not introduce a new variable or policy scope.</p> | |
</div> | |
<div class="section" id="calling-commands"> | |
<h2>Calling Commands<a class="headerlink" href="#calling-commands" title="Permalink to this headline">¶</a></h2> | |
<div class="highlight-cmake notranslate" id="call"><div class="highlight"><pre><span></span><span class="nf">cmake_language(</span><span class="no">CALL</span><span class="w"> </span><span class="nv"><command></span><span class="w"> </span><span class="p">[</span><span class="nv"><arg>...</span><span class="p">]</span><span class="nf">)</span><span class="w"></span> | |
</pre></div> | |
</div> | |
<p>Calls the named <code class="docutils literal notranslate"><span class="pre"><command></span></code> with the given arguments (if any). | |
For example, the code:</p> | |
<div class="highlight-cmake notranslate"><div class="highlight"><pre><span></span><span class="nf">set(</span><span class="nb">message_command</span><span class="w"> </span><span class="s">"message"</span><span class="nf">)</span><span class="w"></span> | |
<span class="nf">cmake_language(</span><span class="no">CALL</span><span class="w"> </span><span class="o">${</span><span class="nt">message_command</span><span class="o">}</span><span class="w"> </span><span class="no">STATUS</span><span class="w"> </span><span class="s">"Hello World!"</span><span class="nf">)</span><span class="w"></span> | |
</pre></div> | |
</div> | |
<p>is equivalent to</p> | |
<div class="highlight-cmake notranslate"><div class="highlight"><pre><span></span><span class="nf">message(</span><span class="no">STATUS</span><span class="w"> </span><span class="s">"Hello World!"</span><span class="nf">)</span><span class="w"></span> | |
</pre></div> | |
</div> | |
<div class="admonition note"> | |
<p class="admonition-title">Note</p> | |
<p>To ensure consistency of the code, the following commands are not allowed:</p> | |
<ul class="simple"> | |
<li><p><code class="docutils literal notranslate"><span class="pre">if</span></code> / <code class="docutils literal notranslate"><span class="pre">elseif</span></code> / <code class="docutils literal notranslate"><span class="pre">else</span></code> / <code class="docutils literal notranslate"><span class="pre">endif</span></code></p></li> | |
<li><p><code class="docutils literal notranslate"><span class="pre">while</span></code> / <code class="docutils literal notranslate"><span class="pre">endwhile</span></code></p></li> | |
<li><p><code class="docutils literal notranslate"><span class="pre">foreach</span></code> / <code class="docutils literal notranslate"><span class="pre">endforeach</span></code></p></li> | |
<li><p><code class="docutils literal notranslate"><span class="pre">function</span></code> / <code class="docutils literal notranslate"><span class="pre">endfunction</span></code></p></li> | |
<li><p><code class="docutils literal notranslate"><span class="pre">macro</span></code> / <code class="docutils literal notranslate"><span class="pre">endmacro</span></code></p></li> | |
</ul> | |
</div> | |
</div> | |
<div class="section" id="evaluating-code"> | |
<h2>Evaluating Code<a class="headerlink" href="#evaluating-code" title="Permalink to this headline">¶</a></h2> | |
<div class="highlight-cmake notranslate" id="eval"><div class="highlight"><pre><span></span><span class="nf">cmake_language(</span><span class="no">EVAL</span><span class="w"> </span><span class="no">CODE</span><span class="w"> </span><span class="nv"><code>...</span><span class="nf">)</span><span class="w"></span> | |
</pre></div> | |
</div> | |
<p>Evaluates the <code class="docutils literal notranslate"><span class="pre"><code>...</span></code> as CMake code.</p> | |
<p>For example, the code:</p> | |
<div class="highlight-cmake notranslate"><div class="highlight"><pre><span></span><span class="nf">set(</span><span class="no">A</span><span class="w"> </span><span class="no">TRUE</span><span class="nf">)</span><span class="w"></span> | |
<span class="nf">set(</span><span class="no">B</span><span class="w"> </span><span class="no">TRUE</span><span class="nf">)</span><span class="w"></span> | |
<span class="nf">set(</span><span class="no">C</span><span class="w"> </span><span class="no">TRUE</span><span class="nf">)</span><span class="w"></span> | |
<span class="nf">set(</span><span class="nb">condition</span><span class="w"> </span><span class="s">"(A AND B) OR C"</span><span class="nf">)</span><span class="w"></span> | |
<span class="nf">cmake_language(</span><span class="no">EVAL</span><span class="w"> </span><span class="no">CODE</span><span class="w"> </span><span class="s">"</span> | |
<span class="s"> if (${condition})</span> | |
<span class="s"> message(STATUS TRUE)</span> | |
<span class="s"> else()</span> | |
<span class="s"> message(STATUS FALSE)</span> | |
<span class="s"> endif()"</span><span class="w"></span> | |
<span class="nf">)</span><span class="w"></span> | |
</pre></div> | |
</div> | |
<p>is equivalent to</p> | |
<div class="highlight-cmake notranslate"><div class="highlight"><pre><span></span><span class="nf">set(</span><span class="no">A</span><span class="w"> </span><span class="no">TRUE</span><span class="nf">)</span><span class="w"></span> | |
<span class="nf">set(</span><span class="no">B</span><span class="w"> </span><span class="no">TRUE</span><span class="nf">)</span><span class="w"></span> | |
<span class="nf">set(</span><span class="no">C</span><span class="w"> </span><span class="no">TRUE</span><span class="nf">)</span><span class="w"></span> | |
<span class="nf">set(</span><span class="nb">condition</span><span class="w"> </span><span class="s">"(A AND B) OR C"</span><span class="nf">)</span><span class="w"></span> | |
<span class="nf">file(</span><span class="no">WRITE</span><span class="w"> </span><span class="o">${</span><span class="nt">CMAKE_CURRENT_BINARY_DIR</span><span class="o">}</span><span class="na">/eval.cmake</span><span class="w"> </span><span class="s">"</span> | |
<span class="s"> if (${condition})</span> | |
<span class="s"> message(STATUS TRUE)</span> | |
<span class="s"> else()</span> | |
<span class="s"> message(STATUS FALSE)</span> | |
<span class="s"> endif()"</span><span class="w"></span> | |
<span class="nf">)</span><span class="w"></span> | |
<span class="nf">include(</span><span class="o">${</span><span class="nt">CMAKE_CURRENT_BINARY_DIR</span><span class="o">}</span><span class="na">/eval.cmake</span><span class="nf">)</span><span class="w"></span> | |
</pre></div> | |
</div> | |
</div> | |
<div class="section" id="deferring-calls"> | |
<h2>Deferring Calls<a class="headerlink" href="#deferring-calls" title="Permalink to this headline">¶</a></h2> | |
<div class="versionadded"> | |
<p><span class="versionmodified added">New in version 3.19.</span></p> | |
</div> | |
<div class="highlight-cmake notranslate" id="defer"><div class="highlight"><pre><span></span><span class="nf">cmake_language(</span><span class="no">DEFER</span><span class="w"> </span><span class="nv"><options>...</span><span class="w"> </span><span class="no">CALL</span><span class="w"> </span><span class="nv"><command></span><span class="w"> </span><span class="p">[</span><span class="nv"><arg>...</span><span class="p">]</span><span class="nf">)</span><span class="w"></span> | |
</pre></div> | |
</div> | |
<p>Schedules a call to the named <code class="docutils literal notranslate"><span class="pre"><command></span></code> with the given arguments (if any) | |
to occur at a later time. By default, deferred calls are executed as if | |
written at the end of the current directory's <code class="docutils literal notranslate"><span class="pre">CMakeLists.txt</span></code> file, | |
except that they run even after a <span class="target" id="index-0-command:return"></span><a class="reference internal" href="return.html#command:return" title="return"><code class="xref cmake cmake-command docutils literal notranslate"><span class="pre">return()</span></code></a> call. Variable | |
references in arguments are evaluated at the time the deferred call is | |
executed.</p> | |
<p>The options are:</p> | |
<dl> | |
<dt><code class="docutils literal notranslate"><span class="pre">DIRECTORY</span> <span class="pre"><dir></span></code></dt><dd><p>Schedule the call for the end of the given directory instead of the | |
current directory. The <code class="docutils literal notranslate"><span class="pre"><dir></span></code> may reference either a source | |
directory or its corresponding binary directory. Relative paths are | |
treated as relative to the current source directory.</p> | |
<p>The given directory must be known to CMake, being either the top-level | |
directory or one added by <span class="target" id="index-0-command:add_subdirectory"></span><a class="reference internal" href="add_subdirectory.html#command:add_subdirectory" title="add_subdirectory"><code class="xref cmake cmake-command docutils literal notranslate"><span class="pre">add_subdirectory()</span></code></a>. Furthermore, | |
the given directory must not yet be finished processing. This means | |
it can be the current directory or one of its ancestors.</p> | |
</dd> | |
<dt><code class="docutils literal notranslate"><span class="pre">ID</span> <span class="pre"><id></span></code></dt><dd><p>Specify an identification for the deferred call. | |
The <code class="docutils literal notranslate"><span class="pre"><id></span></code> may not be empty and may not begin with a capital letter <code class="docutils literal notranslate"><span class="pre">A-Z</span></code>. | |
The <code class="docutils literal notranslate"><span class="pre"><id></span></code> may begin with an underscore (<code class="docutils literal notranslate"><span class="pre">_</span></code>) only if it was generated | |
automatically by an earlier call that used <code class="docutils literal notranslate"><span class="pre">ID_VAR</span></code> to get the id.</p> | |
</dd> | |
<dt><code class="docutils literal notranslate"><span class="pre">ID_VAR</span> <span class="pre"><var></span></code></dt><dd><p>Specify a variable in which to store the identification for the | |
deferred call. If <code class="docutils literal notranslate"><span class="pre">ID</span> <span class="pre"><id></span></code> is not given, a new identification | |
will be generated and the generated id will start with an underscore (<code class="docutils literal notranslate"><span class="pre">_</span></code>).</p> | |
</dd> | |
</dl> | |
<p>The currently scheduled list of deferred calls may be retrieved:</p> | |
<div class="highlight-cmake notranslate"><div class="highlight"><pre><span></span><span class="nf">cmake_language(</span><span class="no">DEFER</span><span class="w"> </span><span class="p">[</span><span class="no">DIRECTORY</span><span class="w"> </span><span class="nv"><dir></span><span class="p">]</span><span class="w"> </span><span class="no">GET_CALL_IDS</span><span class="w"> </span><span class="nv"><var></span><span class="nf">)</span><span class="w"></span> | |
</pre></div> | |
</div> | |
<p>This will store in <code class="docutils literal notranslate"><span class="pre"><var></span></code> a <a class="reference internal" href="../manual/cmake-language.7.html#cmake-language-lists"><span class="std std-ref">semicolon-separated list</span></a> 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 | |
be different to the scope in which they were created. The <code class="docutils literal notranslate"><span class="pre">DIRECTORY</span></code> | |
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 | |
be returned.</p> | |
<p>Details of a specific call may be retrieved from its id:</p> | |
<div class="highlight-cmake notranslate"><div class="highlight"><pre><span></span><span class="nf">cmake_language(</span><span class="no">DEFER</span><span class="w"> </span><span class="p">[</span><span class="no">DIRECTORY</span><span class="w"> </span><span class="nv"><dir></span><span class="p">]</span><span class="w"> </span><span class="no">GET_CALL</span><span class="w"> </span><span class="nv"><id></span><span class="w"> </span><span class="nv"><var></span><span class="nf">)</span><span class="w"></span> | |
</pre></div> | |
</div> | |
<p>This will store in <code class="docutils literal notranslate"><span class="pre"><var></span></code> a <a class="reference internal" href="../manual/cmake-language.7.html#cmake-language-lists"><span class="std std-ref">semicolon-separated list</span></a> in which the first element is the name of the command to be | |
called, and the remaining elements are its unevaluated arguments (any | |
contained <code class="docutils literal notranslate"><span class="pre">;</span></code> characters are included literally and cannot be distinguished | |
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 | |
the specified <code class="docutils literal notranslate"><span class="pre">DIRECTORY</span></code> scope (or the current directory scope if no | |
<code class="docutils literal notranslate"><span class="pre">DIRECTORY</span></code> option is given), this stores an empty string in the variable.</p> | |
<p>Deferred calls may be canceled by their id:</p> | |
<div class="highlight-cmake notranslate"><div class="highlight"><pre><span></span><span class="nf">cmake_language(</span><span class="no">DEFER</span><span class="w"> </span><span class="p">[</span><span class="no">DIRECTORY</span><span class="w"> </span><span class="nv"><dir></span><span class="p">]</span><span class="w"> </span><span class="no">CANCEL_CALL</span><span class="w"> </span><span class="nv"><id>...</span><span class="nf">)</span><span class="w"></span> | |
</pre></div> | |
</div> | |
<p>This cancels all deferred calls matching any of the given ids in the specified | |
<code class="docutils literal notranslate"><span class="pre">DIRECTORY</span></code> scope (or the current directory scope if no <code class="docutils literal notranslate"><span class="pre">DIRECTORY</span></code> option | |
is given). Unknown ids are silently ignored.</p> | |
<div class="section" id="deferred-call-examples"> | |
<h3>Deferred Call Examples<a class="headerlink" href="#deferred-call-examples" title="Permalink to this headline">¶</a></h3> | |
<p>For example, the code:</p> | |
<div class="highlight-cmake notranslate"><div class="highlight"><pre><span></span><span class="nf">cmake_language(</span><span class="no">DEFER</span><span class="w"> </span><span class="no">CALL</span><span class="w"> </span><span class="nb">message</span><span class="w"> </span><span class="s">"${deferred_message}"</span><span class="nf">)</span><span class="w"></span> | |
<span class="nf">cmake_language(</span><span class="no">DEFER</span><span class="w"> </span><span class="no">ID_VAR</span><span class="w"> </span><span class="nb">id</span><span class="w"> </span><span class="no">CALL</span><span class="w"> </span><span class="nb">message</span><span class="w"> </span><span class="s">"Canceled Message"</span><span class="nf">)</span><span class="w"></span> | |
<span class="nf">cmake_language(</span><span class="no">DEFER</span><span class="w"> </span><span class="no">CANCEL_CALL</span><span class="w"> </span><span class="o">${</span><span class="nt">id</span><span class="o">}</span><span class="nf">)</span><span class="w"></span> | |
<span class="nf">message(</span><span class="s">"Immediate Message"</span><span class="nf">)</span><span class="w"></span> | |
<span class="nf">set(</span><span class="nb">deferred_message</span><span class="w"> </span><span class="s">"Deferred Message"</span><span class="nf">)</span><span class="w"></span> | |
</pre></div> | |
</div> | |
<p>prints:</p> | |
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Immediate Message | |
Deferred Message | |
</pre></div> | |
</div> | |
<p>The <code class="docutils literal notranslate"><span class="pre">Cancelled</span> <span class="pre">Message</span></code> is never printed because its command is | |
canceled. The <code class="docutils literal notranslate"><span class="pre">deferred_message</span></code> variable reference is not evaluated | |
until the call site, so it can be set after the deferred call is scheduled.</p> | |
<p>In order to evaluate variable references immediately when scheduling a | |
deferred call, wrap it using <code class="docutils literal notranslate"><span class="pre">cmake_language(EVAL)</span></code>. However, note that | |
arguments will be re-evaluated in the deferred call, though that can be | |
avoided by using bracket arguments. For example:</p> | |
<div class="highlight-cmake notranslate"><div class="highlight"><pre><span></span><span class="nf">set(</span><span class="nb">deferred_message</span><span class="w"> </span><span class="s">"Deferred Message 1"</span><span class="nf">)</span><span class="w"></span> | |
<span class="nf">set(</span><span class="nb">re_evaluated</span><span class="w"> </span><span class="p">[[</span><span class="o">${</span><span class="nt">deferred_message</span><span class="o">}</span><span class="p">]]</span><span class="nf">)</span><span class="w"></span> | |
<span class="nf">cmake_language(</span><span class="no">EVAL</span><span class="w"> </span><span class="no">CODE</span><span class="w"> </span><span class="s">"</span> | |
<span class="s"> cmake_language(DEFER CALL message [[${deferred_message}]])</span> | |
<span class="s"> cmake_language(DEFER CALL message \"${re_evaluated}\")</span> | |
<span class="s">"</span><span class="nf">)</span><span class="w"></span> | |
<span class="nf">message(</span><span class="s">"Immediate Message"</span><span class="nf">)</span><span class="w"></span> | |
<span class="nf">set(</span><span class="nb">deferred_message</span><span class="w"> </span><span class="s">"Deferred Message 2"</span><span class="nf">)</span><span class="w"></span> | |
</pre></div> | |
</div> | |
<p>also prints:</p> | |
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Immediate Message | |
Deferred Message 1 | |
Deferred Message 2 | |
</pre></div> | |
</div> | |
</div> | |
</div> | |
</div> | |
</div> | |
</div> | |
</div> | |
<div class="sphinxsidebar" role="navigation" aria-label="main navigation"> | |
<div class="sphinxsidebarwrapper"> | |
<h3><a href="../index.html">Table of Contents</a></h3> | |
<ul> | |
<li><a class="reference internal" href="#">cmake_language</a><ul> | |
<li><a class="reference internal" href="#synopsis">Synopsis</a></li> | |
<li><a class="reference internal" href="#introduction">Introduction</a></li> | |
<li><a class="reference internal" href="#calling-commands">Calling Commands</a></li> | |
<li><a class="reference internal" href="#evaluating-code">Evaluating Code</a></li> | |
<li><a class="reference internal" href="#deferring-calls">Deferring Calls</a><ul> | |
<li><a class="reference internal" href="#deferred-call-examples">Deferred Call Examples</a></li> | |
</ul> | |
</li> | |
</ul> | |
</li> | |
</ul> | |
<h4>Previous topic</h4> | |
<p class="topless"><a href="cmake_host_system_information.html" | |
title="previous chapter">cmake_host_system_information</a></p> | |
<h4>Next topic</h4> | |
<p class="topless"><a href="cmake_minimum_required.html" | |
title="next chapter">cmake_minimum_required</a></p> | |
<div role="note" aria-label="source link"> | |
<h3>This Page</h3> | |
<ul class="this-page-menu"> | |
<li><a href="../_sources/command/cmake_language.rst.txt" | |
rel="nofollow">Show Source</a></li> | |
</ul> | |
</div> | |
<div id="searchbox" style="display: none" role="search"> | |
<h3 id="searchlabel">Quick search</h3> | |
<div class="searchformwrapper"> | |
<form class="search" action="../search.html" method="get"> | |
<input type="text" name="q" aria-labelledby="searchlabel" /> | |
<input type="submit" value="Go" /> | |
</form> | |
</div> | |
</div> | |
<script type="text/javascript">$('#searchbox').show(0);</script> | |
</div> | |
</div> | |
<div class="clearer"></div> | |
</div> | |
<div class="related" role="navigation" aria-label="related navigation"> | |
<h3>Navigation</h3> | |
<ul> | |
<li class="right" style="margin-right: 10px"> | |
<a href="../genindex.html" title="General Index" | |
>index</a></li> | |
<li class="right" > | |
<a href="cmake_minimum_required.html" title="cmake_minimum_required" | |
>next</a> |</li> | |
<li class="right" > | |
<a href="cmake_host_system_information.html" title="cmake_host_system_information" | |
>previous</a> |</li> | |
<li> | |
<img src="../_static/cmake-logo-16.png" alt="" | |
style="vertical-align: middle; margin-top: -2px" /> | |
</li> | |
<li> | |
<a href="https://cmake.org/">CMake</a> » | |
</li> | |
<li> | |
<a href="../index.html">3.23.1 Documentation</a> » | |
</li> | |
<li class="nav-item nav-item-1"><a href="../manual/cmake-commands.7.html" >cmake-commands(7)</a> »</li> | |
</ul> | |
</div> | |
<div class="footer" role="contentinfo"> | |
© Copyright 2000-2022 Kitware, Inc. and Contributors. | |
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 2.1.2. | |
</div> | |
</body> | |
</html> |