<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>compiler/rustc_codegen_cranelift/docs/usage.md - fork/rust @ master</title>
<meta name="description" content="compiler/rustc_codegen_cranelift/docs/usage.md in fork/rust at master.">
<meta property="og:title" content="compiler/rustc_codegen_cranelift/docs/usage.md - fork/rust @ master">
<meta property="og:description" content="compiler/rustc_codegen_cranelift/docs/usage.md in fork/rust at master.">
<meta property="og:type" content="website">
<meta property="og:site_name" content="git.julia.blue">
<link rel="stylesheet" href="/css/style.css?v=62">
<script type="module" src="/js/main.js?v=62"></script>
</head>
<body>
<main data-ref="master" data-tip="3bcad65fbf67b6edf87c949531fbc13435882e6b">
<noscript>
  <div class="callout">
    <p>
      hey! this is a static git repo viewer. commit diffs, file history,
      older commits and other revisions won't load without javascript.
    </p>
    <p>
      you are still able to view source files on branch/tag tips,
      but the experience is degraded.
    </p>
  </div>
</noscript>
<header class="repo"><div>
<h1>fork/rust</h1>
</div>
<pre class="clone">git clone https://git.julia.blue/fork/rust</pre>
</header>
<p class="snapshot-commit"><span class="commit-author">bors</span><span class="commit-message" data-commit="3bcad65fbf67b6edf87c949531fbc13435882e6b">Auto merge of #103046 - JanBeh:PR_clarify_cmp_terminology, r=workingjubilee</span><span class="snapshot-sha sha" data-commit="3bcad65fbf67b6edf87c949531fbc13435882e6b">3bcad65fbf6</span><time datetime="2023-10-05T15:24:54+00:00" title="2023-10-05 15:24:54 +0000">2023-10-05</time></p>
<header class="topbar"><details class="switcher"><summary>master</summary><div class="menu"><strong>branches</strong><a class="current" href="/fork/rust/ref/master/">master</a><strong>tags</strong><a href="/fork/rust/ref/1.39.0/">1.39.0</a><a href="/fork/rust/ref/1.40.0/">1.40.0</a><a href="/fork/rust/ref/1.41.0/">1.41.0</a><a href="/fork/rust/ref/1.41.1/">1.41.1</a><a href="/fork/rust/ref/1.42.0/">1.42.0</a><a href="/fork/rust/ref/1.43.0/">1.43.0</a><a href="/fork/rust/ref/1.43.1/">1.43.1</a><a href="/fork/rust/ref/1.44.0/">1.44.0</a><a class="all" href="/fork/rust/refs">all refs →</a></div></details><nav class="crumbs"><a href="/fork/rust/">rust</a> / <a href="/fork/rust/ref/master/tree/compiler/">compiler</a> / <a href="/fork/rust/ref/master/tree/compiler/rustc_codegen_cranelift/">rustc_codegen_cranelift</a> / <a href="/fork/rust/ref/master/tree/compiler/rustc_codegen_cranelift/docs/">docs</a> / <span class="cur">usage.md</span></nav>
<span class="view-stats"><span>1.8 KiB</span><span>67 lines</span></span><span class="actions"><a class="raw" href="/fork/rust/raw/135a51ce392b524b4122546ac8266b649a96d254/compiler/rustc_codegen_cranelift/docs/usage.md">raw</a></span></header>
<div class="markdown-view"><input type="radio" name="markdown-view" id="markdown-rendered" checked><label for="markdown-rendered">rendered</label><input type="radio" name="markdown-view" id="markdown-code"><label for="markdown-code">code</label><section class="readme rendered"><h1>Usage</h1>
<p>rustc_codegen_cranelift can be used as a near-drop-in replacement for <code>cargo build</code> or <code>cargo run</code> for existing projects.</p>
<p>Assuming <code>$cg_clif_dir</code> is the directory you cloned this repo into and you followed the instructions (<code>y.sh prepare</code> and <code>y.sh build</code> or <code>test.sh</code>).</p>
<h2>Cargo</h2>
<p>In the directory with your project (where you can do the usual <code>cargo build</code>), run:</p>
<pre class="language-bash"><a-o>$</a-o><a-f> $cg_clif_dir/dist/cargo-clif</a-f> build</pre>
<p>This will build your project with rustc_codegen_cranelift instead of the usual LLVM backend.</p>
<h2>Rustc</h2>
<blockquote>
<p>You should prefer using the Cargo method.</p>
</blockquote>
<pre class="language-bash"><a-o>$</a-o><a-f> $cg_clif_dir/dist/rustc-clif</a-f> my_crate.rs</pre>
<h2>Jit mode</h2>
<blockquote>
<p>⚠⚠⚠ The JIT mode is highly experimental. It may be slower than AOT compilation due to lack of incremental compilation. It may also be hard to setup if you have cargo dependencies. ⚠⚠⚠</p>
</blockquote>
<p>In jit mode cg_clif will immediately execute your code without creating an executable file.</p>
<blockquote>
<p>This requires all dependencies to be available as dynamic library.
The jit mode will probably need cargo integration to make this possible.</p>
</blockquote>
<pre class="language-bash"><a-o>$</a-o><a-f> $cg_clif_dir/dist/cargo-clif</a-f> jit</pre>
<p>or</p>
<pre class="language-bash"><a-o>$</a-o><a-f> $cg_clif_dir/dist/rustc-clif</a-f> <a-co>-Zunstable-features</a-co> <a-co>-Cllvm-args=mode=jit</a-co> <a-co>-Cprefer-dynamic</a-co> my_crate.rs</pre>
<p>There is also an experimental lazy jit mode. In this mode functions are only compiled once they are
first called.</p>
<pre class="language-bash"><a-o>$</a-o><a-f> $cg_clif_dir/dist/cargo-clif</a-f> lazy-jit</pre>
<h2>Shell</h2>
<p>These are a few functions that allow you to easily run rust code from the shell using cg_clif as jit.</p>
<pre class="language-bash"><a-k>function</a-k> <a-f>jit_naked</a-f>() {
    <a-f>echo</a-f> <a-s>&quot;</a-s><a-o>$</a-o><a-s>@&quot;</a-s> <a-o>|</a-o> <a-o>$</a-o><a-pr>cg_clif_dir</a-pr><a-f>/dist/rustc-clif</a-f> <a-co>-</a-co> <a-co>-Zunstable-options</a-co> <a-co>-Cllvm-args=mode=jit-lazy</a-co> <a-co>-Cprefer-dynamic</a-co>
}

<a-k>function</a-k> <a-f>jit</a-f>() {
    <a-f>jit_naked</a-f> <a-s>&quot;fn main() { </a-s><a-o>$</a-o><a-s>@ }&quot;</a-s>
}

<a-k>function</a-k> <a-f>jit_calc</a-f>() {
    <a-f>jit</a-f> <a-s>&#39;println!(&quot;0x{:x}&quot;, &#39;</a-s> <a-o>$</a-o>@ <a-s>&#39;);&#39;</a-s>;
}</pre>
</section><div class="code-panel"><pre class="code src" data-hl="compiler/rustc_codegen_cranelift/docs/usage.md"><span class="code-line"><a class="ln" id="L1" href="#L1">1</a><span class="code-text"># Usage</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2" href="#L2">2</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L3" href="#L3">3</a><span class="code-text">rustc_codegen_cranelift can be used as a near-drop-in replacement for `cargo build` or `cargo run` for existing projects.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L4" href="#L4">4</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L5" href="#L5">5</a><span class="code-text">Assuming `$cg_clif_dir` is the directory you cloned this repo into and you followed the instructions (`y.sh prepare` and `y.sh build` or `test.sh`).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L6" href="#L6">6</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L7" href="#L7">7</a><span class="code-text">## Cargo</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L8" href="#L8">8</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L9" href="#L9">9</a><span class="code-text">In the directory with your project (where you can do the usual `cargo build`), run:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L10" href="#L10">10</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L11" href="#L11">11</a><span class="code-text">```bash</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L12" href="#L12">12</a><span class="code-text">$ $cg_clif_dir/dist/cargo-clif build</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L13" href="#L13">13</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L14" href="#L14">14</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L15" href="#L15">15</a><span class="code-text">This will build your project with rustc_codegen_cranelift instead of the usual LLVM backend.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L16" href="#L16">16</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L17" href="#L17">17</a><span class="code-text">## Rustc</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L18" href="#L18">18</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L19" href="#L19">19</a><span class="code-text">&gt; You should prefer using the Cargo method.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L20" href="#L20">20</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L21" href="#L21">21</a><span class="code-text">```bash</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L22" href="#L22">22</a><span class="code-text">$ $cg_clif_dir/dist/rustc-clif my_crate.rs</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L23" href="#L23">23</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L24" href="#L24">24</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L25" href="#L25">25</a><span class="code-text">## Jit mode</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L26" href="#L26">26</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L27" href="#L27">27</a><span class="code-text">&gt; ⚠⚠⚠ The JIT mode is highly experimental. It may be slower than AOT compilation due to lack of incremental compilation. It may also be hard to setup if you have cargo dependencies. ⚠⚠⚠</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L28" href="#L28">28</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L29" href="#L29">29</a><span class="code-text">In jit mode cg_clif will immediately execute your code without creating an executable file.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L30" href="#L30">30</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L31" href="#L31">31</a><span class="code-text">&gt; This requires all dependencies to be available as dynamic library.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L32" href="#L32">32</a><span class="code-text">&gt; The jit mode will probably need cargo integration to make this possible.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L33" href="#L33">33</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L34" href="#L34">34</a><span class="code-text">```bash</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L35" href="#L35">35</a><span class="code-text">$ $cg_clif_dir/dist/cargo-clif jit</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L36" href="#L36">36</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L37" href="#L37">37</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L38" href="#L38">38</a><span class="code-text">or</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L39" href="#L39">39</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L40" href="#L40">40</a><span class="code-text">```bash</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L41" href="#L41">41</a><span class="code-text">$ $cg_clif_dir/dist/rustc-clif -Zunstable-features -Cllvm-args=mode=jit -Cprefer-dynamic my_crate.rs</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L42" href="#L42">42</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L43" href="#L43">43</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L44" href="#L44">44</a><span class="code-text">There is also an experimental lazy jit mode. In this mode functions are only compiled once they are</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L45" href="#L45">45</a><span class="code-text">first called.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L46" href="#L46">46</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L47" href="#L47">47</a><span class="code-text">```bash</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L48" href="#L48">48</a><span class="code-text">$ $cg_clif_dir/dist/cargo-clif lazy-jit</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L49" href="#L49">49</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L50" href="#L50">50</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L51" href="#L51">51</a><span class="code-text">## Shell</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L52" href="#L52">52</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L53" href="#L53">53</a><span class="code-text">These are a few functions that allow you to easily run rust code from the shell using cg_clif as jit.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L54" href="#L54">54</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L55" href="#L55">55</a><span class="code-text">```bash</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L56" href="#L56">56</a><span class="code-text">function jit_naked() {</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L57" href="#L57">57</a><span class="code-text">    echo &quot;$@&quot; | $cg_clif_dir/dist/rustc-clif - -Zunstable-options -Cllvm-args=mode=jit-lazy -Cprefer-dynamic</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L58" href="#L58">58</a><span class="code-text">}</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L59" href="#L59">59</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L60" href="#L60">60</a><span class="code-text">function jit() {</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L61" href="#L61">61</a><span class="code-text">    jit_naked &quot;fn main() { $@ }&quot;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L62" href="#L62">62</a><span class="code-text">}</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L63" href="#L63">63</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L64" href="#L64">64</a><span class="code-text">function jit_calc() {</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L65" href="#L65">65</a><span class="code-text">    jit 'println!(&quot;0x{:x}&quot;, ' $@ ');';</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L66" href="#L66">66</a><span class="code-text">}</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L67" href="#L67">67</a><span class="code-text">```</span></span></pre></div></div>
</main>
</body>
</html>
