<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>doc_internal/rust-devel.md - fork/fish-shell @ master</title>
<meta name="description" content="doc_internal/rust-devel.md in fork/fish-shell at master.">
<meta property="og:title" content="doc_internal/rust-devel.md - fork/fish-shell @ master">
<meta property="og:description" content="doc_internal/rust-devel.md in fork/fish-shell 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="605c466379a074cf1b5cdb2b62bc8071aab8b47b">
<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/fish-shell</h1>
</div>
<pre class="clone">git clone https://git.julia.blue/fork/fish-shell</pre>
</header>
<p class="snapshot-commit"><span class="commit-author">Daniel Rainer</span><span class="commit-message" data-commit="b62a312cba64103bffdc72cf09ae163e16ad08b3">rename: crate::wchar::prelude -&gt; crate::prelude</span><span class="snapshot-sha sha" data-commit="b62a312cba64103bffdc72cf09ae163e16ad08b3">b62a312cb</span><time datetime="2025-12-18T00:34:41+01:00" title="2025-12-18 00:34:41 +0100">2025-12-18</time></p>
<header class="topbar"><details class="switcher"><summary>master</summary><div class="menu"><strong>branches</strong><a class="current" href="/fork/fish-shell/ref/master/">master</a><a class="all" href="/fork/fish-shell/refs">all refs →</a></div></details><nav class="crumbs"><a href="/fork/fish-shell/">fish-shell</a> / <a href="/fork/fish-shell/ref/master/tree/doc_internal/">doc_internal</a> / <span class="cur">rust-devel.md</span></nav>
<span class="view-stats"><span>9.7 KiB</span><span>192 lines</span></span><span class="actions"><a class="raw" href="/fork/fish-shell/raw/a6a55ded8d4d4f73c106783ad362d44297343870/doc_internal/rust-devel.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>fish-shell Rust Development Guide</h1>
<p>This describes how to get started building fish-shell in its partial Rust state, and how to contribute to the port.</p>
<h2>Overview</h2>
<p>fish is in the process of transitioning from C++ to Rust. The fish project has a Rust crate embedded at path <code>fish-rust</code>. This crate builds a Rust library <code>libfish_rust.a</code> which is linked with the C++ <code>libfish.a</code>. Existing C++ code will be incrementally migrated to this crate; then CMake will be replaced with cargo and other Rust-native tooling.</p>
<p>Important tools used during this transition:</p>
<ol>
<li><a href="https://github.com/corrosion-rs/corrosion">Corrosion</a> to invoke cargo from CMake.</li>
<li><a href="http://cxx.rs">cxx</a> for basic C++ &lt;-&gt; Rust interop.</li>
<li><a href="https://google.github.io/autocxx/">autocxx</a> for using C++ types in Rust.</li>
</ol>
<p>We use forks of the last two - see the <a href="#ffi">FFI section</a> below. No special action is required to obtain these packages. They're downloaded by cargo.</p>
<h2>Building</h2>
<h3>Build Dependencies</h3>
<p>fish-shell currently depends on Rust 1.85 or later. To install Rust, follow https://rustup.rs.</p>
<h3>Build via CMake</h3>
<p>It is recommended to build inside <code>fish-shell/build</code>. This will make it easier for Rust to find the <code>config.h</code> file.</p>
<p>Build via CMake as normal (use any generator, here we use Ninja):</p>
<pre class="language-bash"><a-o>$</a-o><a-f> </a-f><a-pr>cd</a-pr> fish-shell
<a-o>$</a-o><a-f> </a-f><a-pr>mkdir</a-pr> build <a-o>&amp;&amp;</a-o> <a-f>cd</a-f> build
<a-o>$</a-o><a-f> </a-f><a-pr>cmake</a-pr> <a-co>-G</a-co> Ninja ..
<a-o>$</a-o><a-f> </a-f><a-pr>ninja</a-pr></pre>
<p>This will create the usual fish executables.</p>
<h3>Build just libfish_rust.a with Cargo</h3>
<p>The directory <code>fish-rust</code> contains the Rust sources. These require that CMake has been run to produce <code>config.h</code> which is necessary for autocxx to succeed.</p>
<p>Follow the "Build from CMake" steps above, and then:</p>
<pre class="language-bash"><a-o>$</a-o><a-f> </a-f><a-pr>cd</a-pr> fish-shell/fish-rust
<a-o>$</a-o><a-f> </a-f><a-pr>cargo</a-pr> build</pre>
<p>This will build only the library, not a full working fish, but it allows faster iteration for Rust development. That is, after running <code>cmake</code> you can open the <code>fish-rust</code> as the root of a Rust crate, and tools like rust-analyzer will work.</p>
<h2>Development</h2>
<p>The basic development loop for this port:</p>
<ol>
<li>Pick a .cpp (or in some cases .h) file to port, say <code>util.cpp</code>.</li>
<li>Add the corresponding <code>util.rs</code> file to <code>fish-rust/</code>.</li>
<li>Reimplement it in Rust, along with its dependencies as needed. Match the existing C++ code where practical, including propagating any relevant comments.
<ul>
<li>Do this even if it results in less idiomatic Rust, but avoid being super-dogmatic either way.</li>
<li>One technique is to paste the C++ into the Rust code, commented out, and go line by line.</li>
</ul>
</li>
<li>Decide whether any existing C++ callers should invoke the Rust implementation, or whether we should keep the C++ one.
<ul>
<li>Utility functions may have both a Rust and C++ implementation. An example is <code>flog</code> where interop is too hard.</li>
<li>Major components (e.g. builtin implementations) should <em>not</em> be duplicated; instead the Rust should call C++ or vice-versa.</li>
</ul>
</li>
<li>Remember to run <code>cargo fmt</code> and <code>cargo clippy</code> to keep the codebase somewhat clean (otherwise CI will fail). If you use rust-analyzer, you can run clippy automatically by setting <code>rust-analyzer.checkOnSave.command = "clippy"</code>.</li>
</ol>
<p>You will likely run into limitations of <a href="https://google.github.io/autocxx/"><code>autocxx</code></a> and to a lesser extent <a href="https://cxx.rs/"><code>cxx</code></a>. See the <a href="#ffi">FFI sections</a> below.</p>
<h2>Type Mapping</h2>
<h3>Constants &amp; Type Aliases</h3>
<p>The FFI does not support constants (<code>#define</code> or <code>static const</code>) or type aliases (<code>typedef</code>, <code>using</code>). Duplicate them using their Rust equivalent (<code>pub const</code> and <code>type</code>/<code>struct</code>/<code>enum</code>).</p>
<h3>Non-POD types</h3>
<p>Many types cannot currently be passed across the language boundary by value or occur in shared structs. As a workaround, use references, raw pointers or smart pointers (<code>cxx</code> provides <code>SharedPtr</code> and <code>UniquePtr</code>). Try to keep workarounds on the C++ side and the FFI layer of the Rust code. This ensures we will get rid of the workarounds as we peel off the FFI layer.</p>
<h3>Strings</h3>
<p>Fish will mostly <em>not</em> use Rust's <code>String/&amp;str</code> types as these cannot represent non-UTF8 data using the default encoding.</p>
<p>fish's primary string types will come from the <a href="https://docs.rs/widestring"><code>widestring</code> crate</a>. The two main string types are <code>WString</code> and <code>&amp;wstr</code>, which are renamed <a href="https://docs.rs/widestring/latest/widestring/utfstring/struct.Utf32String.html">Utf32String</a> and <a href="https://docs.rs/widestring/latest/widestring/utfstr/struct.Utf32Str.html">Utf32Str</a>. <code>WString</code> is an owned, heap-allocated UTF32 string, <code>&amp;wstr</code> a borrowed UTF32 slice.</p>
<p>In general, follow this mapping when porting from C++:</p>
<ul>
<li><code>wcstring</code> -&gt; <code>WString</code></li>
<li><code>const wcstring &amp;</code> -&gt; <code>&amp;wstr</code></li>
<li><code>const wchar_t *</code> -&gt; <code>&amp;wstr</code></li>
</ul>
<p>None of the Rust string types are nul-terminated. We're taking this opportunity to drop the nul-terminated aspect of wide string handling.</p>
<h4>Creating strings</h4>
<p>One may create a <code>&amp;wstr</code> from a string literal using the <code>wchar::L!</code> macro:</p>
<pre class="language-rust"><a-k>use</a-k> <a-k>crate</a-k><a-p>::</a-p>prelude<a-p>::</a-p><a-o>*</a-o><a-p>;</a-p>
<a-c>// This imports wstr, the L! macro, WString, a ToWString trait that supplies .to_wstring() along with other things</a-c>

<a-k>fn</a-k> <a-f>get_shell_name</a-f><a-p>()</a-p> -&gt; <a-o>&amp;&#39;</a-o><a-l>static</a-l> <a-t>wstr</a-t> <a-p>{</a-p>
    <a-m>L!</a-m><a-p>(</a-p><a-s>&quot;fish&quot;</a-s><a-p>)</a-p>
<a-p>}</a-p></pre>
<p>There is also a <code>widestrs</code> proc-macro which enables L as a <em>suffix</em>, to reduce the noise. This can be applied to any block, including modules and individual functions:</p>
<pre class="language-rust"><a-k>use</a-k> <a-k>crate</a-k><a-p>::</a-p>wchar<a-p>::{</a-p>wstr<a-p>,</a-p> widestrs<a-p>}</a-p>
<a-c>// also imported by the prelude</a-c><a-p>

</a-p><a-at>#</a-at><a-p>[</a-p><a-at>widestrs</a-at><a-p>]</a-p><a-p>
</a-p><a-k>fn</a-k><a-p> </a-p><a-f>get_shell_name</a-f><a-p>()</a-p><a-p> -&gt; </a-p><a-o>&amp;&#39;</a-o><a-l>static</a-l><a-p> </a-p><a-t>wstr</a-t><a-p> </a-p><a-p>{</a-p><a-p>
    </a-p><a-s>&quot;fish&quot;</a-s><a-cr>L</a-cr><a-p> </a-p><a-c>// equivalent to L!(&quot;fish&quot;)</a-c><a-p>
</a-p><a-p>}</a-p></pre>
<h4>The wchar prelude</h4>
<p>We have a prelude to make working with these string types a whole lot more ergonomic. In particular <code>WExt</code> supplies the null-terminated-compatible <code>.char_at(usize)</code>,
and a whole lot more methods that makes porting C++ code easier. It is also preferred to use char-based-methods like <code>.char_count()</code> and <code>.slice_{from,to}()</code>
of the <code>WExt</code> trait over directly calling <code>.len()</code> and <code>[usize..]/[..usize]</code>, as that makes the code compatible with a potential future change to UTF8-strings.</p>
<pre class="language-rust"><a-k>pub</a-k><a-p>(</a-p><a-k>crate</a-k><a-p>)</a-p> <a-k>mod</a-k> prelude <a-p>{</a-p>
    <a-k>pub</a-k><a-p>(</a-p><a-k>crate</a-k><a-p>)</a-p> <a-k>use</a-k> <a-k>crate</a-k><a-p>::{</a-p>
        wchar<a-p>::{</a-p>wstr<a-p>,</a-p> <a-cr>IntoCharIter</a-cr><a-p>,</a-p> <a-cr>WString</a-cr><a-p>,</a-p> <a-cr>L</a-cr><a-p>},</a-p>
        wchar_ext<a-p>::{</a-p><a-cr>ToWString</a-cr><a-p>,</a-p> <a-cr>WExt</a-cr><a-p>},</a-p>
        wutil<a-p>::{</a-p>sprintf<a-p>,</a-p> wgettext<a-p>,</a-p> wgettext_fmt<a-p>,</a-p> wgettext_str<a-p>},</a-p>
    <a-p>};</a-p>
    <a-k>pub</a-k><a-p>(</a-p><a-k>crate</a-k><a-p>)</a-p> <a-k>use</a-k> widestring_suffix<a-p>::</a-p>widestrs<a-p>;</a-p>
<a-p>}</a-p></pre>
<h3>Strings for FFI</h3>
<p><code>WString</code> and <code>&amp;wstr</code> are the common strings used by Rust components. At the FII boundary there are some additional strings for interop. <em>All of these are temporary for the duration of the port.</em></p>
<ul>
<li><code>CxxWString</code> is the Rust binding of <code>std::wstring</code>. It is the wide-string analog to <a href="https://cxx.rs/binding/cxxstring.html"><code>CxxString</code></a> and is <a href="https://github.com/ridiculousfish/cxx/blob/fish/src/cxx_wstring.rs">added in our fork of cxx</a>. This is useful for functions which return e.g. <code>const wcstring &amp;</code>.</li>
<li><code>W0String</code> is renamed <a href="https://docs.rs/widestring/latest/widestring/ucstring/struct.U32CString.html">U32CString</a>. This is basically <code>WString</code> except it <em>is</em> nul-terminated. This is useful for getting a nul-terminated <code>const wchar_t *</code> to pass to C++ implementations.</li>
<li><code>wcharz_t</code> is an annoying C++ struct which merely wraps a <code>const wchar_t *</code>, used for passing these pointers from C++ to Rust. We would prefer to use <code>const wchar_t *</code> directly but <code>autocxx</code> refuses to generate bindings for types such as <code>std::vector&lt;const wchar_t *&gt;</code> so we wrap it in this silly struct.</li>
</ul>
<p>Note C++ <code>wchar_t</code>, Rust <code>char</code>, and <code>u32</code> are effectively interchangeable: you can cast pointers to them back and forth (except we check upon u32-&gt;char conversion). However be aware of which types are nul-terminated.</p>
<p>These types should be confined to the FFI modules, in particular <code>wchar_ffi</code>. They should not "leak" into other modules. See the <code>wchar_ffi</code> module.</p>
<h3>Format strings</h3>
<p>Rust's builtin <code>std::fmt</code> modules do not accept runtime-provided format strings, so we mostly won't use them, except perhaps for flog / other non-translated text.</p>
<p>Instead we'll continue to use printf-style strings, with a Rust printf implementation.</p>
<h3>Vectors</h3>
<p>See <a href="https://cxx.rs/binding/vec.html"><code>Vec</code></a> and <a href="https://cxx.rs/binding/cxxvector.html"><code>CxxVector</code></a>.</p>
<p>In many cases, <code>autocxx</code> refuses to allow vectors of certain types. For example, autocxx supports <code>std::vector</code> and <code>std::shared_ptr</code> but NOT <code>std::vector&lt;std::shared_ptr&lt;...&gt;&gt;</code>. To work around this one can create a helper (pointer, length) struct. Example:</p>
<pre class="language-cpp"><a-k>struct</a-k> <a-t>RustFFIJobList</a-t> {
    std::<a-t>shared_ptr</a-t><a-o>&lt;</a-o><a-t>job_t</a-t><a-o>&gt;</a-o> <a-o>*</a-o><a-pr>jobs</a-pr>;
    <a-t>size_t</a-t> <a-pr>count</a-pr>;
};</pre>
<p>This is just a POD (plain old data) so autocxx can generate bindings for it. Then it is trivial to convert it to a Rust slice:</p>
<pre>pub fn get_jobs(ffi_jobs: &amp;ffi::RustFFIJobList) -&gt; &amp;[SharedPtr&lt;job_t&gt;] {
    unsafe { slice::from_raw_parts(ffi_jobs.jobs, ffi_jobs.count) }
}
</pre>
<p>Another workaround is to define a struct that contains the shared pointer, and create a vector of that struct.</p>
<h2>Development Tooling</h2>
<p>The <a href="https://google.github.io/autocxx/workflow.html#how-can-i-see-what-bindings-autocxx-has-generated">autocxx guidance</a> is helpful:</p>
<ol>
<li>Install cargo expand (<code>cargo install cargo-expand</code>). Then you can use <code>cargo expand</code> to see the generated Rust bindings for C++. In particular this is useful for seeing failed expansions for C++ types that autocxx cannot handle.</li>
<li>In rust-analyzer, enable Proc Macro and Proc Macro Attributes.</li>
</ol>
<h2>FFI</h2>
<p>The boundary between Rust and C++ is referred to as the Foreign Function Interface, or FFI.</p>
<p><code>autocxx</code> and <code>cxx</code> both are designed for long-term interop: C++ and Rust coexisting for years. To this end, both emphasize safety: requiring lots of <code>unsafe</code>, <code>Pin</code>, etc.</p>
<p>fish plans to use them only temporarily, with a focus on getting things working. To this end, both cxx and autocxx have been forked to support fish:</p>
<ol>
<li>Relax the requirement that all functions taking pointers are <code>unsafe</code> (this just added noise).</li>
<li>Add support for <code>wchar_t</code> as a recognized type, and <code>CxxWString</code> analogous to <code>CxxString</code>.</li>
</ol>
<p>See the <code>Cargo.toml</code> file for the locations of the forks.</p>
</section><div class="code-panel"><pre class="code src language-markdown"><span class="code-line"><a class="ln" id="L1" href="#L1">1</a><span class="code-text"><a-p>#</a-p> <a-tt>fish-shell Rust Development Guide</a-tt></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">This describes how to get started building fish-shell in its partial Rust state, and how to contribute to the port.</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"><a-p>##</a-p> <a-tt>Overview</a-tt></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">fish is in the process of transitioning from C++ to Rust. The fish project has a Rust crate embedded at path `fish-rust`. This crate builds a Rust library `libfish_rust.a` which is linked with the C++ `libfish.a`. Existing C++ code will be incrementally migrated to this crate; then CMake will be replaced with cargo and other Rust-native tooling.</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">Important tools used during this transition:</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"><a-p>1. </a-p>[Corrosion](https://github.com/corrosion-rs/corrosion) to invoke cargo from CMake.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L12" href="#L12">12</a><span class="code-text"><a-p>2. </a-p>[cxx](http://cxx.rs) for basic C++ &lt;-&gt; Rust interop.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L13" href="#L13">13</a><span class="code-text"><a-p>3. </a-p>[autocxx](https://google.github.io/autocxx/) for using C++ types in Rust.</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"><a-p>We use forks of the last two - see the [FFI section](#ffi) below. No special action is required to obtain these packages. They&#39;re downloaded by cargo.</a-p></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"><a-p>## </a-p><a-tt>Building</a-tt></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"><a-p>### </a-p><a-tt>Build Dependencies</a-tt></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"><a-p>fish-shell currently depends on Rust 1.85 or later. To install Rust, follow https://rustup.rs.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L22" href="#L22">22</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L23" href="#L23">23</a><span class="code-text"><a-p>### </a-p><a-tt>Build via CMake</a-tt></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"><a-p>It is recommended to build inside `fish-shell/build`. This will make it easier for Rust to find the `config.h` file.</a-p></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"><a-p>Build via CMake as normal (use any generator, here we use Ninja):</a-p></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"><a-p>```</a-p><a-tl>shell</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L30" href="#L30">30</a><span class="code-text"><a-p>$ cd fish-shell</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L31" href="#L31">31</a><span class="code-text"><a-p>$ mkdir build &amp;&amp; cd build</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L32" href="#L32">32</a><span class="code-text"><a-p>$ cmake -G Ninja ..</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L33" href="#L33">33</a><span class="code-text"><a-p>$ ninja</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L34" href="#L34">34</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L35" href="#L35">35</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L36" href="#L36">36</a><span class="code-text"><a-p>This will create the usual fish executables.</a-p></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"><a-p>### </a-p><a-tt>Build just libfish_rust.a with Cargo</a-tt></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"><a-p>The directory `fish-rust` contains the Rust sources. These require that CMake has been run to produce `config.h` which is necessary for autocxx to succeed.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L41" href="#L41">41</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L42" href="#L42">42</a><span class="code-text"><a-p>Follow the &quot;Build from CMake&quot; steps above, and then:</a-p></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"><a-p>```</a-p><a-tl>shell</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L45" href="#L45">45</a><span class="code-text"><a-p>$ cd fish-shell/fish-rust</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L46" href="#L46">46</a><span class="code-text"><a-p>$ cargo build</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L47" href="#L47">47</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L48" href="#L48">48</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L49" href="#L49">49</a><span class="code-text"><a-p>This will build only the library, not a full working fish, but it allows faster iteration for Rust development. That is, after running `cmake` you can open the `fish-rust` as the root of a Rust crate, and tools like rust-analyzer will work.</a-p></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"><a-p>## </a-p><a-tt>Development</a-tt></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"><a-p>The basic development loop for this port:</a-p></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"><a-p>1. Pick a .cpp (or in some cases .h) file to port, say `util.cpp`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L56" href="#L56">56</a><span class="code-text"><a-p>2. Add the corresponding `util.rs` file to `fish-rust/`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L57" href="#L57">57</a><span class="code-text"><a-p>3. Reimplement it in Rust, along with its dependencies as needed. Match the existing C++ code where practical, including propagating any relevant comments.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L58" href="#L58">58</a><span class="code-text"><a-p>   - Do this even if it results in less idiomatic Rust, but avoid being super-dogmatic either way.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L59" href="#L59">59</a><span class="code-text"><a-p>   - One technique is to paste the C++ into the Rust code, commented out, and go line by line.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L60" href="#L60">60</a><span class="code-text"><a-p>4. Decide whether any existing C++ callers should invoke the Rust implementation, or whether we should keep the C++ one.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L61" href="#L61">61</a><span class="code-text"><a-p>   - Utility functions may have both a Rust and C++ implementation. An example is `flog` where interop is too hard.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L62" href="#L62">62</a><span class="code-text"><a-p>   - Major components (e.g. builtin implementations) should _not_ be duplicated; instead the Rust should call C++ or vice-versa.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L63" href="#L63">63</a><span class="code-text"><a-p>5. Remember to run `cargo fmt` and `cargo clippy` to keep the codebase somewhat clean (otherwise CI will fail). If you use rust-analyzer, you can run clippy automatically by setting `rust-analyzer.checkOnSave.command = &quot;clippy&quot;`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L64" href="#L64">64</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L65" href="#L65">65</a><span class="code-text"><a-p>You will likely run into limitations of [`autocxx`](https://google.github.io/autocxx/) and to a lesser extent [`cxx`](https://cxx.rs/). See the [FFI sections](#ffi) below.</a-p></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"><a-p>## </a-p><a-tt>Type Mapping</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L68" href="#L68">68</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L69" href="#L69">69</a><span class="code-text"><a-p>### </a-p><a-tt>Constants &amp; Type Aliases</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L70" href="#L70">70</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L71" href="#L71">71</a><span class="code-text"><a-p>The FFI does not support constants (`#define` or `static const`) or type aliases (`typedef`, `using`). Duplicate them using their Rust equivalent (`pub const` and `type`/`struct`/`enum`).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L72" href="#L72">72</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L73" href="#L73">73</a><span class="code-text"><a-p>### </a-p><a-tt>Non-POD types</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L74" href="#L74">74</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L75" href="#L75">75</a><span class="code-text"><a-p>Many types cannot currently be passed across the language boundary by value or occur in shared structs. As a workaround, use references, raw pointers or smart pointers (`cxx` provides `SharedPtr` and `UniquePtr`). Try to keep workarounds on the C++ side and the FFI layer of the Rust code. This ensures we will get rid of the workarounds as we peel off the FFI layer.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L76" href="#L76">76</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L77" href="#L77">77</a><span class="code-text"><a-p>### </a-p><a-tt>Strings</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L78" href="#L78">78</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L79" href="#L79">79</a><span class="code-text"><a-p>Fish will mostly _not_ use Rust&#39;s `String/&amp;str` types as these cannot represent non-UTF8 data using the default encoding.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L80" href="#L80">80</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L81" href="#L81">81</a><span class="code-text"><a-p>fish&#39;s primary string types will come from the [`widestring` crate](https://docs.rs/widestring). The two main string types are `WString` and `&amp;wstr`, which are renamed [Utf32String](https://docs.rs/widestring/latest/widestring/utfstring/struct.Utf32String.html) and [Utf32Str](https://docs.rs/widestring/latest/widestring/utfstr/struct.Utf32Str.html). `WString` is an owned, heap-allocated UTF32 string, `&amp;wstr` a borrowed UTF32 slice.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L82" href="#L82">82</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L83" href="#L83">83</a><span class="code-text"><a-p>In general, follow this mapping when porting from C++:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L84" href="#L84">84</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L85" href="#L85">85</a><span class="code-text"><a-p>- `wcstring` -&gt; `WString`</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L86" href="#L86">86</a><span class="code-text"><a-p>- `const wcstring &amp;` -&gt; `&amp;wstr`</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L87" href="#L87">87</a><span class="code-text"><a-p>- `const wchar_t *` -&gt; `&amp;wstr`</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L88" href="#L88">88</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L89" href="#L89">89</a><span class="code-text"><a-p>None of the Rust string types are nul-terminated. We&#39;re taking this opportunity to drop the nul-terminated aspect of wide string handling.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L90" href="#L90">90</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L91" href="#L91">91</a><span class="code-text"><a-p>#### </a-p><a-tt>Creating strings</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L92" href="#L92">92</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L93" href="#L93">93</a><span class="code-text"><a-p>One may create a `&amp;wstr` from a string literal using the `wchar::L!` macro:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L94" href="#L94">94</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L95" href="#L95">95</a><span class="code-text"><a-p>```</a-p><a-tl>rust</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L96" href="#L96">96</a><span class="code-text"><a-p>use </a-p><a-k>crate</a-k><a-p>::prelude::</a-p><a-o>*</a-o><a-p>;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L97" href="#L97">97</a><span class="code-text"><a-p>// This imports wstr, the L! macro, WString, a ToWString trait that supplies .to_wstring() along with other things</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L98" href="#L98">98</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L99" href="#L99">99</a><span class="code-text"><a-p>fn </a-p><a-f>get_shell_name</a-f><a-p>() -&gt; </a-p><a-o>&amp;&#39;</a-o><a-l>static</a-l><a-p> </a-p><a-t>wstr</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L100" href="#L100">100</a><span class="code-text"><a-p>    </a-p><a-m>L!</a-m><a-p>(</a-p><a-s>&quot;fish&quot;</a-s><a-p>)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L101" href="#L101">101</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L102" href="#L102">102</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L103" href="#L103">103</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L104" href="#L104">104</a><span class="code-text"><a-p>There is also a `widestrs` proc-macro which enables L as a _suffix_, to reduce the noise. This can be applied to any block, including modules and individual functions:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L105" href="#L105">105</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L106" href="#L106">106</a><span class="code-text"><a-p>```</a-p><a-tl>rust</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L107" href="#L107">107</a><span class="code-text"><a-p>use </a-p><a-k>crate</a-k><a-p>::wchar::{wstr, widestrs}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L108" href="#L108">108</a><span class="code-text"><a-p>// also imported by the prelude</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L109" href="#L109">109</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L110" href="#L110">110</a><span class="code-text"><a-p>#[widestrs]</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L111" href="#L111">111</a><span class="code-text"><a-p>fn </a-p><a-f>get_shell_name</a-f><a-p>() -&gt; </a-p><a-o>&amp;&#39;</a-o><a-l>static</a-l><a-p> </a-p><a-t>wstr</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L112" href="#L112">112</a><span class="code-text"><a-p>    </a-p><a-s>&quot;fish&quot;</a-s><a-cr>L</a-cr><a-p> </a-p><a-c>// equivalent to L!(&quot;fish&quot;)</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L113" href="#L113">113</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L114" href="#L114">114</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L115" href="#L115">115</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L116" href="#L116">116</a><span class="code-text"><a-p>#### </a-p><a-tt>The wchar prelude</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L117" href="#L117">117</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L118" href="#L118">118</a><span class="code-text"><a-p>We have a prelude to make working with these string types a whole lot more ergonomic. In particular `WExt` supplies the null-terminated-compatible `.char_at(usize)`,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L119" href="#L119">119</a><span class="code-text"><a-p>and a whole lot more methods that makes porting C++ code easier. It is also preferred to use char-based-methods like `.char_count()` and `.slice_{from,to}()`</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L120" href="#L120">120</a><span class="code-text"><a-p>of the `WExt` trait over directly calling `.len()` and `[usize..]/[..usize]`, as that makes the code compatible with a potential future change to UTF8-strings.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L121" href="#L121">121</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L122" href="#L122">122</a><span class="code-text"><a-p>```</a-p><a-tl>rust</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L123" href="#L123">123</a><span class="code-text"><a-p>pub(</a-p><a-k>crate</a-k><a-p>) </a-p><a-k>mod</a-k><a-p> prelude {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L124" href="#L124">124</a><span class="code-text"><a-p>    </a-p><a-k>pub</a-k><a-p>(</a-p><a-k>crate</a-k><a-p>) </a-p><a-k>use</a-k><a-p> </a-p><a-k>crate</a-k><a-p>::{</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L125" href="#L125">125</a><span class="code-text"><a-p>        wchar::{wstr, </a-p><a-cr>IntoCharIter</a-cr><a-p>, </a-p><a-cr>WString</a-cr><a-p>, </a-p><a-cr>L</a-cr><a-p>},</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L126" href="#L126">126</a><span class="code-text"><a-p>        wchar_ext::{</a-p><a-cr>ToWString</a-cr><a-p>, </a-p><a-cr>WExt</a-cr><a-p>},</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L127" href="#L127">127</a><span class="code-text"><a-p>        wutil::{sprintf, wgettext, wgettext_fmt, wgettext_str},</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L128" href="#L128">128</a><span class="code-text"><a-p>    };</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L129" href="#L129">129</a><span class="code-text"><a-p>    </a-p><a-k>pub</a-k><a-p>(</a-p><a-k>crate</a-k><a-p>) </a-p><a-k>use</a-k><a-p> widestring_suffix::widestrs;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L130" href="#L130">130</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L131" href="#L131">131</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L132" href="#L132">132</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L133" href="#L133">133</a><span class="code-text"><a-p>### </a-p><a-tt>Strings for FFI</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L134" href="#L134">134</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L135" href="#L135">135</a><span class="code-text"><a-p>`WString` and `&amp;wstr` are the common strings used by Rust components. At the FII boundary there are some additional strings for interop. _All of these are temporary for the duration of the port._</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L136" href="#L136">136</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L137" href="#L137">137</a><span class="code-text"><a-p>- `CxxWString` is the Rust binding of `std::wstring`. It is the wide-string analog to [`CxxString`](https://cxx.rs/binding/cxxstring.html) and is [added in our fork of cxx](https://github.com/ridiculousfish/cxx/blob/fish/src/cxx_wstring.rs). This is useful for functions which return e.g. `const wcstring &amp;`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L138" href="#L138">138</a><span class="code-text"><a-p>- `W0String` is renamed [U32CString](https://docs.rs/widestring/latest/widestring/ucstring/struct.U32CString.html). This is basically `WString` except it _is_ nul-terminated. This is useful for getting a nul-terminated `const wchar_t *` to pass to C++ implementations.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L139" href="#L139">139</a><span class="code-text"><a-p>- `wcharz_t` is an annoying C++ struct which merely wraps a `const wchar_t *`, used for passing these pointers from C++ to Rust. We would prefer to use `const wchar_t *` directly but `autocxx` refuses to generate bindings for types such as `std::vector&lt;const wchar_t *&gt;` so we wrap it in this silly struct.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L140" href="#L140">140</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L141" href="#L141">141</a><span class="code-text"><a-p>Note C++ `wchar_t`, Rust `char`, and `u32` are effectively interchangeable: you can cast pointers to them back and forth (except we check upon u32-&gt;char conversion). However be aware of which types are nul-terminated.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L142" href="#L142">142</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L143" href="#L143">143</a><span class="code-text"><a-p>These types should be confined to the FFI modules, in particular `wchar_ffi`. They should not &quot;leak&quot; into other modules. See the `wchar_ffi` module.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L144" href="#L144">144</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L145" href="#L145">145</a><span class="code-text"><a-p>### </a-p><a-tt>Format strings</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L146" href="#L146">146</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L147" href="#L147">147</a><span class="code-text"><a-p>Rust&#39;s builtin `std::fmt` modules do not accept runtime-provided format strings, so we mostly won&#39;t use them, except perhaps for flog / other non-translated text.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L148" href="#L148">148</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L149" href="#L149">149</a><span class="code-text"><a-p>Instead we&#39;ll continue to use printf-style strings, with a Rust printf implementation.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L150" href="#L150">150</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L151" href="#L151">151</a><span class="code-text"><a-p>### </a-p><a-tt>Vectors</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L152" href="#L152">152</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L153" href="#L153">153</a><span class="code-text"><a-p>See [`Vec`](https://cxx.rs/binding/vec.html) and [`CxxVector`](https://cxx.rs/binding/cxxvector.html).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L154" href="#L154">154</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L155" href="#L155">155</a><span class="code-text"><a-p>In many cases, `autocxx` refuses to allow vectors of certain types. For example, autocxx supports `std::vector` and `std::shared_ptr` but NOT `std::vector&lt;std::shared_ptr&lt;...&gt;&gt;`. To work around this one can create a helper (pointer, length) struct. Example:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L156" href="#L156">156</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L157" href="#L157">157</a><span class="code-text"><a-p>```</a-p><a-tl>cpp</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L158" href="#L158">158</a><span class="code-text"><a-p>struct </a-p><a-t>RustFFIJobList</a-t><a-p> {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L159" href="#L159">159</a><span class="code-text"><a-p>    std::</a-p><a-t>shared_ptr</a-t><a-o>&lt;</a-o><a-t>job_t</a-t><a-o>&gt;</a-o><a-p> </a-p><a-o>*</a-o><a-pr>jobs</a-pr><a-p>;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L160" href="#L160">160</a><span class="code-text"><a-p>    </a-p><a-t>size_t</a-t><a-p> </a-p><a-pr>count</a-pr><a-p>;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L161" href="#L161">161</a><span class="code-text"><a-p>};</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L162" href="#L162">162</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L163" href="#L163">163</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L164" href="#L164">164</a><span class="code-text"><a-p>This is just a POD (plain old data) so autocxx can generate bindings for it. Then it is trivial to convert it to a Rust slice:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L165" href="#L165">165</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L166" href="#L166">166</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L167" href="#L167">167</a><span class="code-text"><a-p>pub fn get_jobs(ffi_jobs: &amp;ffi::RustFFIJobList) -&gt; &amp;[SharedPtr&lt;job_t&gt;] {</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L168" href="#L168">168</a><span class="code-text"><a-p>    unsafe { slice::from_raw_parts(ffi_jobs.jobs, ffi_jobs.count) }</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L169" href="#L169">169</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L170" href="#L170">170</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L171" href="#L171">171</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L172" href="#L172">172</a><span class="code-text"><a-p>Another workaround is to define a struct that contains the shared pointer, and create a vector of that struct.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L173" href="#L173">173</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L174" href="#L174">174</a><span class="code-text"><a-p>## </a-p><a-tt>Development Tooling</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L175" href="#L175">175</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L176" href="#L176">176</a><span class="code-text"><a-p>The [autocxx guidance](https://google.github.io/autocxx/workflow.html#how-can-i-see-what-bindings-autocxx-has-generated) is helpful:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L177" href="#L177">177</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L178" href="#L178">178</a><span class="code-text"><a-p>1. Install cargo expand (`cargo install cargo-expand`). Then you can use `cargo expand` to see the generated Rust bindings for C++. In particular this is useful for seeing failed expansions for C++ types that autocxx cannot handle.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L179" href="#L179">179</a><span class="code-text"><a-p>2. In rust-analyzer, enable Proc Macro and Proc Macro Attributes.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L180" href="#L180">180</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L181" href="#L181">181</a><span class="code-text"><a-p>## </a-p><a-tt>FFI</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L182" href="#L182">182</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L183" href="#L183">183</a><span class="code-text"><a-p>The boundary between Rust and C++ is referred to as the Foreign Function Interface, or FFI.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L184" href="#L184">184</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L185" href="#L185">185</a><span class="code-text"><a-p>`autocxx` and `cxx` both are designed for long-term interop: C++ and Rust coexisting for years. To this end, both emphasize safety: requiring lots of `unsafe`, `Pin`, etc.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L186" href="#L186">186</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L187" href="#L187">187</a><span class="code-text"><a-p>fish plans to use them only temporarily, with a focus on getting things working. To this end, both cxx and autocxx have been forked to support fish:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L188" href="#L188">188</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L189" href="#L189">189</a><span class="code-text"><a-p>1. Relax the requirement that all functions taking pointers are `unsafe` (this just added noise).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L190" href="#L190">190</a><span class="code-text"><a-p>2. Add support for `wchar_t` as a recognized type, and `CxxWString` analogous to `CxxString`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L191" href="#L191">191</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L192" href="#L192">192</a><span class="code-text">See the `Cargo.toml` file for the locations of the forks.</span></span></pre></div></div>
</main>
</body>
</html>
