blob: 8fa374d7c7849285ea2e7b2b14d720665f2becf2 [file] [log] [blame]
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
<head>
<meta charset="utf-8" />
<title>cmake_language &mdash; 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> &#187;
</li>
<li>
<a href="../index.html">3.23.1 Documentation</a> &#187;
</li>
<li class="nav-item nav-item-1"><a href="../manual/cmake-commands.7.html" accesskey="U">cmake-commands(7)</a> &#187;</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> &lt;command&gt; [&lt;arg&gt;...])
cmake_language(<a class="reference internal" href="#eval">EVAL</a> CODE &lt;code&gt;...)
cmake_language(<a class="reference internal" href="#defer">DEFER</a> &lt;options&gt;... CALL &lt;command&gt; [&lt;arg&gt;...])</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">&lt;command&gt;</span><span class="w"> </span><span class="p">[</span><span class="nv">&lt;arg&gt;...</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">&lt;command&gt;</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">&quot;message&quot;</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">&quot;Hello World!&quot;</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">&quot;Hello World!&quot;</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">&lt;code&gt;...</span><span class="nf">)</span><span class="w"></span>
</pre></div>
</div>
<p>Evaluates the <code class="docutils literal notranslate"><span class="pre">&lt;code&gt;...</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">&quot;(A AND B) OR C&quot;</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">&quot;</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()&quot;</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">&quot;(A AND B) OR C&quot;</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">&quot;</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()&quot;</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">&lt;options&gt;...</span><span class="w"> </span><span class="no">CALL</span><span class="w"> </span><span class="nv">&lt;command&gt;</span><span class="w"> </span><span class="p">[</span><span class="nv">&lt;arg&gt;...</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">&lt;command&gt;</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">&lt;dir&gt;</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">&lt;dir&gt;</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">&lt;id&gt;</span></code></dt><dd><p>Specify an identification for the deferred call.
The <code class="docutils literal notranslate"><span class="pre">&lt;id&gt;</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">&lt;id&gt;</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">&lt;var&gt;</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">&lt;id&gt;</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">&lt;dir&gt;</span><span class="p">]</span><span class="w"> </span><span class="no">GET_CALL_IDS</span><span class="w"> </span><span class="nv">&lt;var&gt;</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">&lt;var&gt;</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">&lt;dir&gt;</span><span class="p">]</span><span class="w"> </span><span class="no">GET_CALL</span><span class="w"> </span><span class="nv">&lt;id&gt;</span><span class="w"> </span><span class="nv">&lt;var&gt;</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">&lt;var&gt;</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">&lt;dir&gt;</span><span class="p">]</span><span class="w"> </span><span class="no">CANCEL_CALL</span><span class="w"> </span><span class="nv">&lt;id&gt;...</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">&quot;${deferred_message}&quot;</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">&quot;Canceled Message&quot;</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">&quot;Immediate Message&quot;</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">&quot;Deferred Message&quot;</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">&quot;Deferred Message 1&quot;</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">&quot;</span>
<span class="s"> cmake_language(DEFER CALL message [[${deferred_message}]])</span>
<span class="s"> cmake_language(DEFER CALL message \&quot;${re_evaluated}\&quot;)</span>
<span class="s">&quot;</span><span class="nf">)</span><span class="w"></span>
<span class="nf">message(</span><span class="s">&quot;Immediate Message&quot;</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">&quot;Deferred Message 2&quot;</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> &#187;
</li>
<li>
<a href="../index.html">3.23.1 Documentation</a> &#187;
</li>
<li class="nav-item nav-item-1"><a href="../manual/cmake-commands.7.html" >cmake-commands(7)</a> &#187;</li>
</ul>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2000-2022 Kitware, Inc. and Contributors.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 2.1.2.
</div>
</body>
</html>