- rust

- rust Personal Website and Blog of Manuel Bucher. Zola 2025-07-10T00:00:00+00:00 https://manuelbucher.com/tags/rust/atom.xml Integrating a Rust library into Gecko 2025-07-10T00:00:00+00:00 2025-07-10T00:00:00+00:00 Unknown https://manuelbucher.com/blog/rust-gecko/ <p>Integrating a Rust library to Gecko / Firefox is unexpectedly easy, but Rust adoption varies significantly between teams. I started in the Firefox networking Team <a rel="external" href="https://wiki.mozilla.org/Necko">Necko</a>, which has a few Rust components like the HTTP/3 stack <a rel="external" href="https://github.com/mozilla/necko">neqo</a> or the URL implementation. After switching to <a rel="external" href="https://wiki.mozilla.org/Privacy">Privacy / Anti-Tracking team</a> I'm now in a team that has no Rust code at all. The interest for Rust components is there, but usually projects are started in C++ due to all code being in C++.</p> <h2 id="rust-in-gecko">Rust in Gecko</h2> <p><a rel="external" href="https://4e6.github.io/firefox-lang-stats/"><img src="/img/2025-07-08-firefox-lang-stats.png" alt="Pie chart with language usage" /></a></p> <p>Looking at current language stats, we can see that Rust is currently at around 12% of Firefox code with almost 5 million lines of code. This is not neglectable, but falls short behind C / C++ and also JavaScript.</p> <blockquote> <p><strong>Note:</strong> Using tokei with <code>--exclude=third_party</code> suggests Rust has about 8% of the LOC of C++ for code written in mozilla-firefox directly. Not 50% as this diagram might suggest. (feedback after lightning talk)</p> </blockquote> <h2 id="error-categories-rules-out-by-rust">Error categories rules out by Rust</h2> <ul> <li><strong>Use after free bugs</strong>: No more <code>kungFuDeathGrip</code> security fixes to extend the lifetime of an object.</li> <li><strong>Data races</strong>: No more forgetting to question "Do I need to lock a Mutex to access this variable?"</li> <li><strong>Nullptr dereferences</strong>: Call by pointer is very common in C++, especially in idl interfaces. "Can this pointer I’ve got passed be null?" is now answered by the Rust type system.</li> <li><strong>Iterator invalidation</strong>: Another big class of errors. In Gecko this is also <a rel="external" href="https://searchfox.org/mozilla-central/rev/578d9c83f046d8c361ac6b98b297c27990d468fd/xpcom/ds/ArrayIterator.h#40-42">memory safe for nsTArray</a>, but wrong code.</li> <li><strong>Other undefined behavior</strong></li> </ul> <h2 id="other-rusty-reasons">Other Rusty reasons</h2> <p>In my opinion, Rust is just a very well-designed language. It has great documentation infrastructure and awesome compiler errors aiding you in writing safe code.</p> <h2 id="case-study-riir-copy-clean-link">Case Study: RIIR "Copy Clean Link"</h2> <p>The patch for the case study can be found in <a rel="external" href="https://phabricator.services.mozilla.com/D225390">D225390</a>.</p> <p>Almost always you probably want to split up the library into two parts:</p> <p>One crate for functionality and bindings. The functionality crate can be developed out-of-tree. In this example I'm going to have the crate be developed in-tree.</p> <h3 id="add-crate-directories-to-moz-build">Add crate directories to moz.build</h3> <p>Add directory where the crates are located need to be included in the parent moz.build:</p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="python"><span class="giallo-l"><span style="color: #005CC5;">DIRS</span><span style="color: #D73A49;"> +=</span><span> [</span></span> <span class="giallo-l"><span style="color: #032F62;"> "urlstrip"</span><span>,</span></span> <span class="giallo-l"><span style="color: #032F62;"> "urlstrip_glue"</span><span>,</span></span> <span class="giallo-l"><span>]</span></span></code></pre><h3 id="functionality-crate">Functionality crate</h3> <p>The crate implementing the logic with no dependency on xpcom types simply needs to have a single-line (plus license text) <code>moz.build</code> next to the <code>Cargo.toml</code>:</p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="python"><span class="giallo-l"><span style="color: #005CC5;">FINAL_LIBRARY</span><span style="color: #D73A49;"> =</span><span style="color: #032F62;"> "xul"</span></span></code></pre> <blockquote> <p><strong>Note:</strong> To combat build failue you need to regenerate the <code>Cargo.toml</code> by running <code>./mach vendor rust --allow-dirty</code>.</p> </blockquote> <h3 id="cbindgen-xpcom-bindings-crate">cbindgen / XPCOM bindings crate</h3> <p>You need a few more lines for the bindings crate to autogenerate a C++ header with cbindgen.</p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="python"><span class="giallo-l"><span style="color: #005CC5;">FINAL_LIBRARY</span><span style="color: #D73A49;"> =</span><span style="color: #032F62;"> "xul"</span></span> <span class="giallo-l"><span style="color: #005CC5;">EXPORTS</span><span>.mozilla</span><span style="color: #D73A49;"> +=</span><span> [</span></span> <span class="giallo-l"><span style="color: #032F62;"> "UrlStrip.h"</span><span>,</span></span> <span class="giallo-l"><span>]</span></span> <span class="giallo-l"><span style="color: #D73A49;">if</span><span style="color: #005CC5;"> CONFIG</span><span>[</span><span style="color: #032F62;">"COMPILE_ENVIRONMENT"</span><span>]:</span></span> <span class="giallo-l"><span> CbindgenHeader(</span></span> <span class="giallo-l"><span style="color: #032F62;"> "UrlStrip_ffi.h"</span><span>,</span></span> <span class="giallo-l"><span style="color: #E36209;"> inputs</span><span style="color: #D73A49;">=</span><span>[</span><span style="color: #032F62;">"/toolkit/components/antitracking/urlstrip_glue"</span><span>]</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span style="color: #005CC5;"> EXPORTS</span><span>.mozilla</span><span style="color: #D73A49;"> +=</span><span> [</span></span> <span class="giallo-l"><span style="color: #032F62;"> "!UrlStrip_ffi.h"</span><span>,</span></span> <span class="giallo-l"><span> ]</span></span></code></pre> <p>You can depend on <code>nsstring</code> and other <code>xpcom</code> crates. However, you <a rel="external" href="https://firefox-source-docs.mozilla.org/testing-rust-code/index.html#rust-tests:~:text=Rust%20tests%20have%20one%20major%20restriction%3A%20they%20cannot%20link%20against%20Gecko%20symbols%2E%20Therefore%2C%20Rust%20tests%20cannot%20be%20used%20for%20crates%20that%20use%20Gecko%20crates%20like%20nsstring%20and%20xpcom%2E">won't</a> be able to use Rust's native <code>#[test]</code> directive. This is one of the reasons you likely really want to have the separation between the two crate types.</p> <p>To configure cbindgen, get inspired by taking a look at <a rel="external" href="https://searchfox.org/mozilla-central/search?path=&q=cbindgen.toml">other cbindgen.toml files</a>.</p> <p>You also want to have somewhat nicer C++ headers around your autogenerated cbindgen header for C++ <code>UrlStrip.h</code>:</p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="cpp"><span class="giallo-l"><span style="color: #D73A49;">struct</span><span style="color: #6F42C1;"> UrlStrip</span><span> {</span></span> <span class="giallo-l"><span style="color: #D73A49;">public:</span></span> <span class="giallo-l"><span style="color: #D73A49;"> static void</span><span style="color: #6F42C1;"> Create</span><span>(</span><span style="color: #6F42C1;">UrlStrip</span><span style="color: #D73A49;">**</span><span style="color: #E36209;"> pThis</span><span>) {</span><span style="color: #6F42C1;"> urlstrip_new</span><span>(pThis); }</span></span> <span class="giallo-l"><span style="color: #D73A49;"> void</span><span style="color: #6F42C1;"> Delete</span><span>() {</span><span style="color: #6F42C1;"> urlstrip_drop</span><span>(</span><span style="color: #005CC5;">this</span><span>); }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #D73A49;"> void</span><span style="color: #6F42C1;"> Init</span><span>() {</span><span style="color: #6F42C1;"> urlstrip_init</span><span>(</span><span style="color: #005CC5;">this</span><span>); };</span></span> <span class="giallo-l"><span style="color: #D73A49;"> void</span><span style="color: #6F42C1;"> Uninit</span><span>() {</span><span style="color: #6F42C1;"> urlstrip_uninit</span><span>(</span><span style="color: #005CC5;">this</span><span>); };</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #6F42C1;"> nsresult Strip</span><span>(</span><span style="color: #D73A49;">const</span><span style="color: #6F42C1;"> nsACString</span><span style="color: #D73A49;">&</span><span style="color: #E36209;"> aURI</span><span>,</span><span style="color: #6F42C1;"> nsCString</span><span style="color: #D73A49;">*</span><span style="color: #E36209;"> aOutURI</span><span>) {</span></span> <span class="giallo-l"><span style="color: #D73A49;"> return</span><span style="color: #6F42C1;"> urlstrip_strip</span><span>(</span><span style="color: #005CC5;">this</span><span>,</span><span style="color: #D73A49;"> &</span><span>aURI, aOutURI);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span style="color: #D73A49;"> bool</span><span style="color: #6F42C1;"> CanStrip</span><span>(</span><span style="color: #D73A49;">const</span><span style="color: #6F42C1;"> nsACString</span><span style="color: #D73A49;">&</span><span style="color: #E36209;"> aURI</span><span>) {</span></span> <span class="giallo-l"><span style="color: #D73A49;"> return</span><span style="color: #6F42C1;"> urlstrip_canstrip</span><span>(</span><span style="color: #005CC5;">this</span><span>,</span><span style="color: #D73A49;"> &</span><span>aURI);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span style="color: #D73A49;">private:</span></span> <span class="giallo-l"><span style="color: #6F42C1;"> UrlStrip</span><span>()</span><span style="color: #D73A49;"> = delete</span><span>;</span></span> <span class="giallo-l"><span style="color: #6F42C1;"> ~UrlStrip</span><span>()</span><span style="color: #D73A49;"> = delete</span><span>;</span></span> <span class="giallo-l"><span style="color: #6F42C1;"> UrlStrip</span><span>(</span><span style="color: #D73A49;">const</span><span style="color: #6F42C1;"> UrlStrip</span><span style="color: #D73A49;">&</span><span>)</span><span style="color: #D73A49;"> = delete</span><span>;</span></span> <span class="giallo-l"><span style="color: #6F42C1;"> UrlStrip</span><span style="color: #D73A49;">& operator</span><span style="color: #6F42C1;">=</span><span>(</span><span style="color: #D73A49;">const</span><span style="color: #6F42C1;"> UrlStrip</span><span style="color: #D73A49;">&</span><span>)</span><span style="color: #D73A49;"> = delete</span><span>;</span></span> <span class="giallo-l"><span>};</span></span></code></pre> <p>Maybe <a rel="external" href="https://cxx.rs">cxx</a> could ease with this in the future: <a rel="external" href="https://bugzilla.mozilla.org/show_bug.cgi?id=1921139">Bug 1921139 - Allow creating C++ bindings for Rust code with cxx</a>.</p> <h3 id="other-files-to-touch">Other files to touch</h3> <p>To use the Rust library from C++/JS, it must be linked. And for that you need to both add it as a dependency to <code>toolkit/library/rust/shared/Cargo.toml</code>:</p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="rust"><span class="giallo-l"><span>urlstrip</span><span style="color: #D73A49;"> =</span><span> { path</span><span style="color: #D73A49;"> =</span><span style="color: #032F62;"> "../../../components/antitracking/urlstrip"</span><span> }</span></span> <span class="giallo-l"><span>urlstrip_glue</span><span style="color: #D73A49;"> =</span><span> { path</span><span style="color: #D73A49;"> =</span><span style="color: #032F62;"> "../../../components/antitracking/urlstrip_glue"</span><span> }</span></span></code></pre> <p>And also important (due to still using 2015 rust edition) <code>extern crate</code> definitions in <code>toolkit/library/rust/shared/lib.rs</code>:</p> <pre class="giallo" style="color: #24292E; background-color: #FFFFFF;"><code data-lang="rust"><span class="giallo-l"><span style="color: #D73A49;">extern crate</span><span> urlstrip;</span></span> <span class="giallo-l"><span style="color: #D73A49;">extern crate</span><span> urlstrip_glue;</span></span></code></pre><h2 id="done">Done</h2> <p>This is all. Feel free to reach out to me if you have any questions!</p> <h2 id="further-resources">Further Resources</h2> <ul> <li><a rel="external" href="https://firefox-source-docs.mozilla.org/build/buildsystem/rust.html">https://firefox-source-docs.mozilla.org/build/buildsystem/rust.html</a></li> <li><a rel="external" href="https://firefox-source-docs.mozilla.org/writing-rust-code/">https://firefox-source-docs.mozilla.org/writing-rust-code/</a></li> <li><a rel="external" href="https://www.youtube.com/watch?v=ly8eupJOwbE">Blog as Lightning Talk</a></li> <li><a href="/pdf/rust-gecko.pdf">Lightning Talk slides</a></li> </ul> <h2 id="updates">Updates</h2> <ul> <li>2025-07-10: Added note on Rust usage within gecko</li> <li>2025-11-02: note on how to combat build failure after adding rust crate</li> </ul>