| |
| <!DOCTYPE html> |
| |
| <html lang="en"> |
| <head> |
| <meta charset="utf-8" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0" /> |
| <title>cmake_language — CMake 3.23.1 Documentation</title> |
| |
| <link rel="stylesheet" type="text/css" href="../_static/pygments.css" /> |
| <link rel="stylesheet" type="text/css" href="../_static/cmake.css" /> |
| |
| <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script> |
| <script src="../_static/jquery.js"></script> |
| <script src="../_static/underscore.js"></script> |
| <script src="../_static/doctools.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> |
| <li class="nav-item nav-item-this"><a href="">cmake_language</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 class="clearer"></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" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/> |
| <input type="submit" value="Go" /> |
| </form> |
| </div> |
| </div> |
| <script>$('#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> |
| <li class="nav-item nav-item-this"><a href="">cmake_language</a></li> |
| </ul> |
| </div> |
| |
| <div class="footer" role="contentinfo"> |
| © Copyright 2000-2022 Kitware, Inc. and Contributors. |
| Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.1.2. |
| </div> |
| </body> |
| </html> |