BD103's BlogTechnical writing on Bevy, Rust, and moreZola2026-06-18T00:00:00+00:00https://bd103.dev/atom.xmlUpdating Stacked Pull Requests with git rebase --onto2026-06-18T00:00:00+00:002026-06-18T00:00:00+00:00
BD103
https://bd103.dev/blog/2026-06-18-git-rebase-onto/<style>
body {
img.dark-only {
display: none;
}
img.light-only {
display: inline;
}
}
body.dark {
img.dark-only {
display: inline;
}
img.light-only {
display: none;
}
}
em {
&.commit-a {
color: var(--callout-warning-color);
}
&.commit-b {
color: var(--callout-tip-color);
}
&.commit-c {
color: var(--callout-important-color);
}
&.commit-e {
color: var(--callout-note-color);
}
}
</style>
<p>Sometimes I find myself in the situation where I have multiple pull requests that build off of each other.</p>
<figure>
<img
src="original.png"
alt="TODO"
>
</figure>
<p>Then, a reviewer asks me to squash <em class="commit-b">commit B</em> into <em class="commit-a">commit A</em>, creating a new <em class="commit-e">commit E</em>. I do so, but now my second pull request is all messed up!</p>
<figure>
<img
src="squashed.png"
alt="TODO"
>
</figure>
<p>When Git created <em class="commit-e">commit E</em>, it didn't tell <em class="commit-b">commit B</em>'s children that their new parent should be <em class="commit-e">commit E</em>. This means that <em class="commit-c">commit C</em> still thinks its parent is <em class="commit-b">commit B</em>!</p>
<figure>
<img class="dark-only" src="commit-c-dark.png" alt="TODO">
<img class="light-only" src="commit-c-light.png" alt="TODO">
</figure>
<p>While this behavior is a sensible default, in this scenario we don't want it. We can tell <em class="commit-c">commit C</em> that its new parent is <em class="commit-e">commit E</em> by rebasing it with the following command:</p>
<pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Make sure we're on the second PR's branch.</span></span>
<span class="giallo-l"><span class="z-entity z-name z-function">git</span><span class="z-string"> switch</span><span class="z-string"> second-pr</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Tell commit C that its new parent is E, not B.</span></span>
<span class="giallo-l"><span class="z-entity z-name z-function">git</span><span class="z-string"> rebase</span><span class="z-string"> -</span><span class="z-string">-onto</span><span class="z-string"> E</span><span class="z-string"> B</span></span></code></pre><figure>
<img
src="rebased.png"
alt="TODO"
>
</figure>
<p>The general form of this command is <code>git rebase --onto <newparent> <oldparent></code>, and it's very useful when updating stacked pull requests where the parent commit has been replaced. You don't need it if the base pull request only had new commits added, though, in which case you would use a normal <code>git rebase</code> without the <code>--onto</code> option. Once you do rebase your second pull request, take a look at the <a rel="external" href="https://git-scm.com/docs/git-push#Documentation/git-push.txt---force-with-lease"><code>--force-with-lease</code></a> option of <code>git push</code> to safely push your changes to the remote.</p>
<figure>
<img class="dark-only" src="commit-f-dark.png" alt="TODO">
<img class="light-only" src="commit-f-light.png" alt="TODO">
</figure>
<p><em>Thank you to <a rel="external" href="https://stackoverflow.com/a/39081674">sEver on Stack Overflow for the answer</a> that inspired this article!</em></p>
Correctly Converting HEIC to PNG2026-06-03T00:00:00+00:002026-06-04T00:00:00+00:00
BD103
https://bd103.dev/blog/2026-06-03-correctly-converting-heic-to-png/<p>iPhones by default store photos in the <a rel="external" href="https://en.wikipedia.org/wiki/High_Efficiency_Image_File_Format">High Efficiency Image File format</a> (HEIF), a lossy format that often uses the <code>.heic</code> extension<sup class="footnote-reference" id="fr-heif-heic-1"><a href="#fn-heif-heic">1</a></sup>. While this file format works well enough within the Apple ecosystem, there is very poor support for it outside of the walled garden.</p>
<p>Windows requires the <a rel="external" href="https://www.microsoft.com/en-us/p/hevc-video-extensions/9nmzlz57r3t7">HEVC Video Extension</a>, which costs $0.99<sup class="footnote-reference" id="fr-windows-hevc-extension-1"><a href="#fn-windows-hevc-extension">2</a></sup>. Android added support in 2019 with Android 10<sup class="footnote-reference" id="fr-android-heic-1"><a href="#fn-android-heic">3</a></sup>. Linux distributions support HEIC if you install <a rel="external" href="https://github.com/strukturag/libheif">libheif</a><sup class="footnote-reference" id="fr-libheif-1"><a href="#fn-libheif">4</a></sup>. Chromium and Firefox do not support HEIC, only Safari does<sup class="footnote-reference" id="fr-web-heic-1"><a href="#fn-web-heic">5</a></sup>, which reflects in popular web apps like Google Docs and Google Slides also not supporting it.</p>
<p>Because of this, I have a habit of converting HEIC files to PNGs before exporting them from my laptop. This process isn't obvious, however, and many solutions mentioned online suggest using an online service or downloading a sketchy program. In this article I will go over 3 different methods for converting HEIC to PNG using built-in tools in MacOS and iOS. No extra software, no online services, just the vanilla programs shipped by Apple.</p>
<blockquote class="callout caution has-title">
<p class="title">
<span class="icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="18" height="18"><path d="M4.00098 20V14C4.00098 9.58172 7.5827 6 12.001 6C16.4193 6 20.001 9.58172 20.001 14V20H21.001V22H3.00098V20H4.00098ZM6.00098 20H18.001V14C18.001 10.6863 15.3147 8 12.001 8C8.68727 8 6.00098 10.6863 6.00098 14V20ZM11.001 2H13.001V5H11.001V2ZM19.7792 4.80761L21.1934 6.22183L19.0721 8.34315L17.6578 6.92893L19.7792 4.80761ZM2.80859 6.22183L4.22281 4.80761L6.34413 6.92893L4.92991 8.34315L2.80859 6.22183ZM7.00098 14C7.00098 11.2386 9.23956 9 12.001 9V11C10.3441 11 9.00098 12.3431 9.00098 14H7.00098Z" fill="currentColor"></path></svg>
</span>
<strong>Caution</strong>
</p>
<div class="content">
<p><strong>Do not upload your photos to online image converters.</strong> As a matter of privacy, you have no idea how long those images are stored and what the website operators may be doing with them. It is easier, faster, and more secure to do the conversion locally on your computer.</p>
</div>
</blockquote>
<h2 id="export-from-photos-macos">Export from Photos (MacOS)<a class="zola-anchor" href="#export-from-photos-macos" aria-label="Anchor link for: export-from-photos-macos" style="visibility: hidden;"></a>
</h2>
<p>If your photos are stored in iCloud or accessible through the Photos app on MacOS, it's really easy to convert them to PNG. Select the image in Photos and export the HEIC using File → Export → Export 1 Photo.</p>
<figure>
<img
src="photos-macos-export-menu.png"
alt="A screenshot of the photo export menu, highlighting the text 'Export 1 Photo'"
>
</figure>
<p>Make sure to set "Photo Kind" to "PNG," "Color Profile" to "Most Compatible," and "Size" to "Full Size" in the export dialogue.</p>
<figure>
<img
src="photos-macos-export-dialogue.png"
alt="A screenshot of the photo export dialogue"
>
</figure>
<p>Once exported, you're good to go!</p>
<figure>
<img
src="photos-macos-image.png"
alt="The final image: a bright sky with clouds and a tree line"
>
</figure>
<h2 id="convert-with-preview-macos">Convert with Preview (MacOS)<a class="zola-anchor" href="#convert-with-preview-macos" aria-label="Anchor link for: convert-with-preview-macos" style="visibility: hidden;"></a>
</h2>
<p>Preview is also able to convert HEIC to PNG, however you need to use ColorSync Utility for the image to turn out correct. First, open the HEIC file in Preview. Then, select File → Duplicate to create a copy.</p>
<figure>
<img
src="preview-duplicate.png"
alt="A screenshot of the file menu, with 'Duplicate' selected"
width="300"
>
</figure>
<p>When you go to save the duplicate, make sure to set "Format" to "PNG". This will tell Preview to convert the image to PNG instead of leaving it as a HEIC.</p>
<figure>
<img
src="preview-save-as.png"
alt="A screenshot of the file export dialogue, asking where to save the image and in what format"
>
</figure>
<p>At this point, it may look like you're done, but don't be fooled! While Preview (and Safari) will show the image as normal...</p>
<figure>
<img
src="preview-uncorrected.png"
alt="A screenshot of Preview displaying the image with everything looking normal"
>
</figure>
<p>...if you open the same image in Firefox or Chromium it will look washed out and gray! Preview created a PNG that only looks correct on certain platforms!</p>
<figure>
<img id="image-washed" src="colorsync-uncorrected-washed.png" alt="A photograph of electricity poles, the sun, and a bird mid-flight, however the image looks much more gray than it should, lacking vibrant blues and greens">
<img id="image-raw" src="colorsync-uncorrected-raw.png" alt="A photograph of electricity poles, the sun, and a bird mid-flight, however on Firefox and Chrome the image looks much more gray than it should, lacking vibrant blues and greens">
<figcaption>
<div>
<input type="radio" id="hidden-image-washed" name="hidden-image" value="image-raw" onchange="updateHiddenImage()" checked>
<label for="hidden-image-washed">What Firefox and Chromium See (Washed)</label>
<br />
<input type="radio" id="hidden-image-raw" name="hidden-image" value="image-washed" onchange="updateHiddenImage()">
<label for="hidden-image-raw">What Your Browser Sees (Original)</label>
</div>
</figcaption>
</figure>
<style id="hidden-image-style"></style>
<script>
function updateHiddenImage() {
const selection = document.querySelector("input[name='hidden-image']:checked").value;
document.getElementById("hidden-image-style").innerText = `#${selection} { display: none }`;
console.info(`Hiding image #${selection}`);
}
updateHiddenImage();
</script>
<p>While I am not positive, I believe this happens because the image has <a rel="external" href="https://en.wikipedia.org/wiki/High_dynamic_range">high dynamic range</a> (HDR). If you inspect the color profile of the original image, you will see <code>Display P3 Primaries; PQ (Adaptive Gain Curve 0974DE20B8237D0E)</code>. This image uses the <a rel="external" href="https://en.wikipedia.org/wiki/DCI-P3">Display P3 color space</a>, which is normal for Apple devices, but the PQ part tells me the image is HDR. PQ stands for <a rel="external" href="https://en.wikipedia.org/wiki/Perceptual_quantizer">perceptual quantizer</a>, and is used when calculating the brightness of HDR images.</p>
<p>The reason I believe this image looks bad on Firefox and Chromium is because PNG <a rel="external" href="https://www.w3.org/TR/png-3/#changes-20031110:~:text=2100%5D-,High%20Dynamic%20Range">only recently added support for HDR</a> in June 2025 as part of the PNG 3.0 specification. If I had to guess, MacOS and Safari have native support for HDR PNGs, but Firefox and Chromium do not yet.</p>
<p>Either way, we need to fix this so the PNG looks correct on all platforms. We're going to convert the HDR image to SDR using MacOS's ColorSync Utility. ColorSync Utility is a strange, oft-ignored application for managing color profiles and converting between color spaces. To begin, first open ColorSync Utility, then select File → Open and select the PNG file.</p>
<figure>
<img
src="colorsync-open-menu.png"
alt="A screenshot of the file menu, with 'Open' highlighted"
width="300"
>
</figure>
<p>In the new window, select "Match to Profile" and select the "sRGB IEC61966-2.1" color profile<sup class="footnote-reference" id="fr-srgb-1"><a href="#fn-srgb">6</a></sup>. Click "Apply," then save the file.</p>
<figure>
<img
src="colorsync-match-profile.png"
alt="A screenshot of the image open in ColorSync Utility, with 'Match to Profile' and 'sRGB IEC61966-2.1' both selected"
>
</figure>
<p>Now, if you open the corrected image in a browser, it will look much much closer to the original.</p>
<figure>
<img
src="colorsync-corrected.png"
alt="A photograph of electricity poles, the sun, and a bird mid-flight"
>
</figure>
<h2 id="export-from-photos-ios">Export from Photos (iOS)<a class="zola-anchor" href="#export-from-photos-ios" aria-label="Anchor link for: export-from-photos-ios" style="visibility: hidden;"></a>
</h2>
<p>The Photos app on iOS is similar to MacOS, except it doesn't give as much control. When you go to export the image, click the "Options" button at the top of the window.</p>
<figure>
<img
src="photos-ios-export.png"
alt="A screenshot of the export image screen in the Photos app"
width="400"
>
</figure>
<p>In the options sheet, make sure to select "Most Compatible" for the format.</p>
<figure>
<img
src="photos-ios-export-options.png"
alt="A screenshot of the options menu, with 'Most Compatible' selected. The format selection box is captioned 'Choose Automatic for the best format for the destination or Current to prevent file format conversions. Photos and videos may convert to JPEG, PNG, and H.264 formats if you choose Most Compatible.'"
width="400"
>
</figure>
<p>The iOS version does not give you control over the file format, and from my experience it exports JPEGs rather than PNGs. Even still, the resulting image appears correct and does not experience the washed-out behavior from Preview.</p>
<figure>
<img
src="photos-ios-image.jpeg"
alt="A photo of a pink cherry blossom tree in bloom with a traditional Japanese building visible in the background"
>
</figure>
<blockquote class="callout tip has-title">
<p class="title">
<span class="icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="18" height="18"><path d="M9.97308 18H11V13H13V18H14.0269C14.1589 16.7984 14.7721 15.8065 15.7676 14.7226C15.8797 14.6006 16.5988 13.8564 16.6841 13.7501C17.5318 12.6931 18 11.385 18 10C18 6.68629 15.3137 4 12 4C8.68629 4 6 6.68629 6 10C6 11.3843 6.46774 12.6917 7.31462 13.7484C7.40004 13.855 8.12081 14.6012 8.23154 14.7218C9.22766 15.8064 9.84103 16.7984 9.97308 18ZM10 20V21H14V20H10ZM5.75395 14.9992C4.65645 13.6297 4 11.8915 4 10C4 5.58172 7.58172 2 12 2C16.4183 2 20 5.58172 20 10C20 11.8925 19.3428 13.6315 18.2443 15.0014C17.624 15.7748 16 17 16 18.5V21C16 22.1046 15.1046 23 14 23H10C8.89543 23 8 22.1046 8 21V18.5C8 17 6.37458 15.7736 5.75395 14.9992Z" fill="currentColor"></path></svg>
</span>
<strong>Tip</strong>
</p>
<div class="content">
<p>If you enjoyed this post, you may be interested Howard Oakley's writing at <a rel="external" href="https://eclecticlight.co/">The Eclectic Light Company</a>. His blog is a treasure-trove of information on the behind-the-scenes of Macs and MacOS, and has proved invaluable to me time and time again!</p>
</div>
</blockquote>
<section class="footnotes">
<ol class="footnotes-list">
<li id="fn-heif-heic">
<p>There's actually a bit more nuance to this. HEIF is an image container format where the image itself can be encoded in a number of formats. When the image is encoded with <a rel="external" href="https://en.wikipedia.org/wiki/High_Efficiency_Video_Coding">HEVC (x265)</a>, it is referred to as a HEIC file. HEIF can be either lossy or lossless, depending on the inner format used. HEVC is usually lossy, but has optional support for lossless encoding. As such, when HEIF uses HEVC, it is called HEIC and is usually lossy. <a href="#fr-heif-heic-1">↩</a></p>
</li>
<li id="fn-windows-hevc-extension">
<p>I wasn't able to verify this myself, as I don't use Windows, so this may be outdated. <a href="#fr-windows-hevc-extension-1">↩</a></p>
</li>
<li id="fn-android-heic">
<p><a rel="external" href="https://source.android.com/docs/core/camera/heif">https://source.android.com/docs/core/camera/heif</a> <a href="#fr-android-heic-1">↩</a></p>
</li>
<li id="fn-libheif">
<p>libheif has been experiencing an uptick in security vulnerability reports recently, <a rel="external" href="https://daniel.haxx.se/blog/2026/04/22/high-quality-chaos/">similar to curl</a>. In the past 2 weeks they published 5 CVEs with a severity of either high or critical, with an additional 10 moderate CVEs. This doesn't mean libheif has poor code quality compared to other projects, rather that it is a much larger target for security researchers who have powerful new tools. <a href="#fr-libheif-1">↩</a></p>
</li>
<li id="fn-web-heic">
<p><a rel="external" href="https://caniuse.com/heif">https://caniuse.com/heif</a> <a href="#fr-web-heic-1">↩</a></p>
</li>
<li id="fn-srgb">
<p><a rel="external" href="https://en.wikipedia.org/wiki/SRGB">sRGB</a> is an SDR color space that is the standard for the web. You can generally assume any device in the last 15 years supports it, which is why I chose it here. <a href="#fr-srgb-1">↩</a></p>
</li>
</ol>
</section>
Stacking Gradients in Typst2026-05-23T00:00:00+00:002026-05-23T00:00:00+00:00
BD103
https://bd103.dev/blog/2026-05-23-stacking-gradients-typst/<p>In March I wrote a <a rel="external" href="https://summerofcode.withgoogle.com">Google Summer of Code</a> proposal for <a rel="external" href="https://stjude.org">St. Jude Children's Research Hospital</a>. My proposal was specifically geared towards <a rel="external" href="https://sprocket.bio/">Sprocket</a>, a bioinformatics workflow engine. While typesetting my document, Sprocket's homepage caught my eye.</p>
<figure>
<img
src="sprocket-homepage.png"
alt="A screenshot of Sprocket's homepage"
width="100%"
>
<figcaption><p>Sprocket's homepage</p>
</figcaption>
</figure>
<p>I really love the gradient in the background of the hero banner. The blend between navy, purple, and blue are iconic, and I wanted to recreate this effect in the title page of my proposal.</p>
<p>Using DevTools, I looked at the CSS for the background and found the following:</p>
<pre class="giallo z-code"><code data-lang="css"><span class="giallo-l"><span class="z-punctuation">.</span><span class="z-entity z-other z-attribute-name z-class z-css">hero__background</span><span class="z-punctuation"> {</span></span>
<span class="giallo-l"><span class="z-support z-type z-property-name z-css"> background</span><span class="z-punctuation z-separator z-key-value">:</span><span class="z-support z-function"> radial-gradient</span><span class="z-punctuation">(</span><span class="z-source">circle</span><span class="z-keyword z-operator"> at</span><span class="z-source"> top</span><span class="z-source"> right</span><span class="z-punctuation">,</span><span class="z-punctuation"> #</span><span class="z-source">7035b4</span><span class="z-constant z-numeric"> 0</span><span class="z-keyword z-other z-unit z-percentage z-css">%</span><span class="z-punctuation">,</span><span class="z-source"> transparent</span><span class="z-constant z-numeric"> 55</span><span class="z-keyword z-other z-unit z-percentage z-css">%</span><span class="z-punctuation">)</span><span class="z-punctuation">,</span><span class="z-support z-function"> radial-gradient</span><span class="z-punctuation">(</span><span class="z-source">circle</span><span class="z-keyword z-operator"> at</span><span class="z-source"> bottom</span><span class="z-source"> right</span><span class="z-punctuation">,</span><span class="z-punctuation"> #</span><span class="z-source">6e89be</span><span class="z-constant z-numeric"> 0</span><span class="z-keyword z-other z-unit z-percentage z-css">%</span><span class="z-punctuation">,</span><span class="z-source"> transparent</span><span class="z-constant z-numeric"> 45</span><span class="z-keyword z-other z-unit z-percentage z-css">%</span><span class="z-punctuation">)</span><span class="z-punctuation">,</span><span class="z-punctuation"> #</span><span class="z-source">070A19</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"><span class="z-punctuation">}</span></span></code></pre>
<p>This CSS takes advantage of a fun quirk of the <a rel="external" href="https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/background"><code>background</code> property</a>:</p>
<blockquote class="quote">
<div class="icon" style="display: none;"><svg fill="currentColor" xmlns="http://www.w3.org/2000/svg" width="10" height="10" viewBox="796 698 200 200">
<g>
<path d="M885.208,749.739v-40.948C836.019,708.791,796,748.81,796,798v89.209h89.208V798h-48.26
C836.948,771.39,858.598,749.739,885.208,749.739z"/>
<path d="M996,749.739v-40.948c-49.19,0-89.209,40.019-89.209,89.209v89.209H996V798h-48.26
C947.74,771.39,969.39,749.739,996,749.739z"/>
</g>
</svg>
</div>
<div class="content"><p>If multiple comma-separated backgrounds are included, they create multiple background layers on top of one another. The first background in the list creates the top layer. If the top layer contains no transparent areas, this is the only layer that will be visible.</p>
<p>The last layer is the bottom layer. The background color is always included in this layer.</p>
</div>
<div class="from">
<p>— <a rel="external" href="https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/background#image_painting_order">MDN on background image painting order</a></p>
</div>
</blockquote>
<p>In sum, the hero background is actually three backgrounds stacked on top of each other!</p>
<div class="gradient-grid">
<div id="gradient-1"></div>
<div id="gradient-2"></div>
<div id="gradient-3"></div>
</div>
<style>
.gradient-grid {
display: grid;
grid-template-columns: 3fr 1fr 3fr 1fr 3fr;
}
.gradient-grid div {
aspect-ratio: 1 / 1;
outline: solid 1.5px var(--primary-color);
}
#gradient-1 {
background: radial-gradient(circle at top right, #7035b4 0%, transparent 55%);
grid-column: 1;
}
#gradient-2 {
background: radial-gradient(circle at bottom right, #6e89be 0%, transparent 45%);
grid-column: 3;
}
#gradient-3 {
background: #070A19;
grid-column: 5;
}
</style>
<p>I created my proposal using <a rel="external" href="https://typst.app/home/">Typst</a>, a typesetting system similar to <a rel="external" href="https://www.latex-project.org/">LaTeX</a>. Typst allows you to set the background of a page using the <a rel="external" href="https://typst.app/docs/reference/layout/page/#parameters-fill"><code>fill</code> parameter</a>, but unfortunately it only supports a single color or gradient.</p>
<pre class="giallo z-code"><code data-lang="typst"><span class="giallo-l"><span class="z-punctuation">#</span><span class="z-entity z-name z-function">page</span><span class="z-punctuation">(</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Purple to black background gradient.</span></span>
<span class="giallo-l"><span class="z-variable z-parameter"> fill</span><span class="z-punctuation">:</span><span class="z-source"> gradient</span><span class="z-source">.</span><span class="z-entity z-name z-function">radial</span><span class="z-punctuation">(</span></span>
<span class="giallo-l"><span class="z-entity z-name z-function"> rgb</span><span class="z-punctuation">(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">#7035b4</span><span class="z-punctuation z-definition z-string">"</span><span class="z-punctuation">)</span><span class="z-punctuation">,</span></span>
<span class="giallo-l"><span class="z-entity z-name z-function"> rgb</span><span class="z-punctuation">(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">#070A19</span><span class="z-punctuation z-definition z-string">"</span><span class="z-punctuation">)</span><span class="z-punctuation">,</span></span>
<span class="giallo-l"><span class="z-variable z-parameter"> center</span><span class="z-punctuation">:</span><span class="z-punctuation"> (</span><span class="z-constant z-numeric">100%</span><span class="z-punctuation">,</span><span class="z-constant z-numeric"> 0%</span><span class="z-punctuation">)</span><span class="z-punctuation">,</span></span>
<span class="giallo-l"><span class="z-variable z-parameter"> radius</span><span class="z-punctuation">:</span><span class="z-constant z-numeric"> 100%</span><span class="z-punctuation">,</span></span>
<span class="giallo-l"><span class="z-punctuation"> )</span></span>
<span class="giallo-l"><span class="z-punctuation">)</span><span class="z-source">[</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-keyword"> #</span><span class="z-keyword">set</span><span class="z-entity z-name z-function"> align</span><span class="z-punctuation">(</span><span class="z-source">center</span><span class="z-keyword z-operator"> +</span><span class="z-source"> horizon</span><span class="z-punctuation">)</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-keyword"> #</span><span class="z-keyword">set</span><span class="z-entity z-name z-function"> text</span><span class="z-punctuation">(</span><span class="z-variable z-parameter">fill</span><span class="z-punctuation">:</span><span class="z-source"> white</span><span class="z-punctuation">)</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-keyword"> #</span><span class="z-keyword">set</span><span class="z-entity z-name z-function"> par</span><span class="z-punctuation">(</span><span class="z-variable z-parameter">spacing</span><span class="z-punctuation">:</span><span class="z-constant z-numeric"> 0.6em</span><span class="z-punctuation">)</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation"> #</span><span class="z-entity z-name z-function">text</span><span class="z-punctuation">(</span><span class="z-constant z-numeric">7em</span><span class="z-punctuation">)</span><span class="z-source">[Title]</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation"> #</span><span class="z-entity z-name z-function">text</span><span class="z-punctuation">(</span><span class="z-constant z-numeric">3em</span><span class="z-punctuation">)</span><span class="z-source">[Subtitle]</span></span>
<span class="giallo-l"><span class="z-source">]</span></span></code></pre><figure>
<img
src="single-gradient.svg"
alt="A page with a centered placeholder title and subtitle and a single gradient background"
width="50%"
>
</figure>
<p>This isn't the end of the world, however, because I found that <a rel="external" href="https://typst.app/docs/reference/layout/block/"><code>block</code></a> also has a <a rel="external" href="https://typst.app/docs/reference/layout/block/#parameters-fill"><code>fill</code> parameter</a>. To make a stacked gradient liked Sprocket's homepage, I simply created a <code>block</code> inside the <code>page</code> with the extra gradient!</p>
<pre class="giallo z-code"><code data-lang="typst"><span class="giallo-l"><span class="z-punctuation">#</span><span class="z-entity z-name z-function">page</span><span class="z-punctuation">(</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Purple to black background gradient.</span></span>
<span class="giallo-l"><span class="z-variable z-parameter"> fill</span><span class="z-punctuation">:</span><span class="z-source"> gradient</span><span class="z-source">.</span><span class="z-entity z-name z-function">radial</span><span class="z-punctuation">(</span></span>
<span class="giallo-l"><span class="z-entity z-name z-function"> rgb</span><span class="z-punctuation">(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">#7035b4</span><span class="z-punctuation z-definition z-string">"</span><span class="z-punctuation">)</span><span class="z-punctuation">,</span></span>
<span class="giallo-l"><span class="z-entity z-name z-function"> rgb</span><span class="z-punctuation">(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">#070A19</span><span class="z-punctuation z-definition z-string">"</span><span class="z-punctuation">)</span><span class="z-punctuation">,</span></span>
<span class="giallo-l"><span class="z-variable z-parameter"> center</span><span class="z-punctuation">:</span><span class="z-punctuation"> (</span><span class="z-constant z-numeric">100%</span><span class="z-punctuation">,</span><span class="z-constant z-numeric"> 0%</span><span class="z-punctuation">)</span><span class="z-punctuation">,</span></span>
<span class="giallo-l"><span class="z-variable z-parameter"> radius</span><span class="z-punctuation">:</span><span class="z-constant z-numeric"> 100%</span><span class="z-punctuation">,</span></span>
<span class="giallo-l"><span class="z-punctuation"> )</span><span class="z-punctuation">,</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> No margin, so inner block fills entire page.</span></span>
<span class="giallo-l"><span class="z-variable z-parameter"> margin</span><span class="z-punctuation">:</span><span class="z-constant z-numeric"> 0in</span><span class="z-punctuation">,</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> The inner block with the extra gradient to be stacked on top of the page</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> background.</span></span>
<span class="giallo-l"><span class="z-entity z-name z-function"> block</span><span class="z-punctuation">(</span></span>
<span class="giallo-l"><span class="z-variable z-parameter"> width</span><span class="z-punctuation">:</span><span class="z-constant z-numeric"> 100%</span><span class="z-punctuation">,</span></span>
<span class="giallo-l"><span class="z-variable z-parameter"> height</span><span class="z-punctuation">:</span><span class="z-constant z-numeric"> 100%</span><span class="z-punctuation">,</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Blue to transparent layer gradient.</span></span>
<span class="giallo-l"><span class="z-variable z-parameter"> fill</span><span class="z-punctuation">:</span><span class="z-source"> gradient</span><span class="z-source">.</span><span class="z-entity z-name z-function">radial</span><span class="z-punctuation">(</span></span>
<span class="giallo-l"><span class="z-entity z-name z-function"> rgb</span><span class="z-punctuation">(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">#6e89be</span><span class="z-punctuation z-definition z-string">"</span><span class="z-punctuation">)</span><span class="z-punctuation">,</span></span>
<span class="giallo-l"><span class="z-entity z-name z-function"> luma</span><span class="z-punctuation">(</span><span class="z-constant z-numeric">0</span><span class="z-punctuation">,</span><span class="z-constant z-numeric"> 0%</span><span class="z-punctuation">)</span><span class="z-punctuation">,</span></span>
<span class="giallo-l"><span class="z-variable z-parameter"> center</span><span class="z-punctuation">:</span><span class="z-punctuation"> (</span><span class="z-constant z-numeric">100%</span><span class="z-punctuation">,</span><span class="z-constant z-numeric"> 100%</span><span class="z-punctuation">)</span><span class="z-punctuation">,</span></span>
<span class="giallo-l"><span class="z-variable z-parameter"> radius</span><span class="z-punctuation">:</span><span class="z-constant z-numeric"> 100%</span><span class="z-punctuation">,</span></span>
<span class="giallo-l"><span class="z-punctuation"> )</span><span class="z-punctuation">,</span></span>
<span class="giallo-l"><span class="z-punctuation"> )</span><span class="z-punctuation">[</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-keyword"> #</span><span class="z-keyword">set</span><span class="z-entity z-name z-function"> align</span><span class="z-punctuation">(</span><span class="z-source">center</span><span class="z-keyword z-operator"> +</span><span class="z-source"> horizon</span><span class="z-punctuation">)</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-keyword"> #</span><span class="z-keyword">set</span><span class="z-entity z-name z-function"> text</span><span class="z-punctuation">(</span><span class="z-variable z-parameter">fill</span><span class="z-punctuation">:</span><span class="z-source"> white</span><span class="z-punctuation">)</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-keyword"> #</span><span class="z-keyword">set</span><span class="z-entity z-name z-function"> par</span><span class="z-punctuation">(</span><span class="z-variable z-parameter">spacing</span><span class="z-punctuation">:</span><span class="z-constant z-numeric"> 0.6em</span><span class="z-punctuation">)</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation"> #</span><span class="z-entity z-name z-function">text</span><span class="z-punctuation">(</span><span class="z-constant z-numeric">7em</span><span class="z-punctuation">)</span><span class="z-source">[Title</span><span class="z-punctuation">]</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-source"> #</span><span class="z-entity z-name z-function">text</span><span class="z-punctuation">(</span><span class="z-constant z-numeric">3em</span><span class="z-punctuation">)</span><span class="z-punctuation">[</span><span class="z-source">Subtitle</span><span class="z-punctuation">]</span></span>
<span class="giallo-l"><span class="z-source"> ]</span></span>
<span class="giallo-l"><span class="z-punctuation">)</span></span></code></pre><figure>
<img
src="stacked-gradient.svg"
alt="A page with a centered placeholder title and subtitle and a stacked gradient background"
width="50%"
>
</figure>
<p>Perfect! In the end, I added a few finishing touches and landed with this as my title page:</p>
<figure>
<img
src="proposal-title-page.svg"
alt="The front page of my GSoC proposal"
width="50%"
>
</figure>
<p>I'm super proud of the final result! It looks professional, with a lot of care put into it. The stacked gradients add a bit of flair that really makes it stand out. This is a great example of the power that Typst affords you, as compared to a word processor like Microsoft Word or Google Docs.</p>
<p>While the title page was definitely not the complete reason, it must have helped somewhat! <a rel="external" href="https://summerofcode.withgoogle.com/programs/2026/projects/BNPmlzOg">My proposal was selected</a> of the 70 applications St. Jude received, so starting next week I will working with their developers to implement Python bindings for Sprocket's WDL crates! Google Summer of Code is a program I've wanted to participate in for a few years now, ever since I read that <a rel="external" href="https://blog.rust-lang.org/2024/02/21/Rust-participates-in-GSoC-2024/">the Rust project was participating back in 2024</a>. I'm really excited to be working with the developers at St. Jude, learning from their experience, making strong relationships, and building something that leaves a positive impact on the world.</p>
<p>Until next time,</p>
<p>- BD103 :)</p>
Rust Hashing Cheat Sheet2025-11-10T00:00:00+00:002025-11-10T00:00:00+00:00
BD103
https://bd103.dev/blog/2025-11-10-rust-hashing-cheat-sheet/<p>Hashing is the process of transforming arbitrary data into a fixed-size number. Several useful programming concepts arise out of hash codes:</p>
<ul>
<li>Hash sets and maps</li>
<li>Data digests</li>
<li>Cheap identifiers / inequality checks</li>
<li>Storing passwords</li>
</ul>
<p>Recently I tried writing a hash set from scratch in <a rel="external" href="https://rust-lang.org/">Rust</a> for educational purposes, but was awfully confused by the collection of traits and types provided by <a rel="external" href="https://doc.rust-lang.org/stable/std/hash/index.html"><code>std::hash</code></a>. In this post I hope to share some common patterns related to hashing in Rust, while explaining <code>std::hash</code> as I go.</p>
<h2 id="hashing-a-single-value">Hashing a Single Value<a class="zola-anchor" href="#hashing-a-single-value" aria-label="Anchor link for: hashing-a-single-value" style="visibility: hidden;"></a>
</h2>
<p>Hashing a value is as simple as creating a <code>Hasher</code>, calling <code>value.hash(&mut hasher)</code>, and then calling <code>hasher.finish()</code>.</p>
<pre class="giallo z-code"><code data-lang="rust"><span class="giallo-l"><span class="z-keyword">use</span><span class="z-entity z-name z-namespace"> std</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-namespace">hash</span><span class="z-keyword z-operator">::</span><span class="z-punctuation">{</span><span class="z-entity z-name z-type">DefaultHasher</span><span class="z-punctuation">,</span><span class="z-entity z-name z-type"> Hash</span><span class="z-punctuation">,</span><span class="z-entity z-name z-type"> Hasher</span><span class="z-punctuation">}</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type z-rust">let</span><span class="z-storage z-modifier"> mut</span><span class="z-source"> hasher</span><span class="z-keyword z-operator"> =</span><span class="z-entity z-name z-type"> DefaultHasher</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-function">new</span><span class="z-punctuation">(</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-string">"</span><span class="z-string">Hello, world!</span><span class="z-punctuation z-definition z-string">"</span><span class="z-keyword z-operator">.</span><span class="z-entity z-name z-function">hash</span><span class="z-punctuation">(</span><span class="z-keyword z-operator">&</span><span class="z-storage z-modifier">mut</span><span class="z-variable z-other z-rust"> hasher</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"><span class="z-storage z-type z-rust">let</span><span class="z-source"> hash</span><span class="z-keyword z-operator">:</span><span class="z-entity z-name z-type z-numeric z-rust"> u64</span><span class="z-keyword z-operator"> =</span><span class="z-source"> hasher</span><span class="z-keyword z-operator">.</span><span class="z-entity z-name z-function">finish</span><span class="z-punctuation">(</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-entity z-name z-function z-macro z-rust">println!</span><span class="z-punctuation">(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">Hash: </span><span class="z-punctuation">{</span><span class="z-string">hash</span><span class="z-punctuation">}</span><span class="z-punctuation z-definition z-string">"</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Hash: 7092736762612737980</span></span></code></pre><h2 id="hashing-several-values-into-one-code">Hashing Several Values into One Code<a class="zola-anchor" href="#hashing-several-values-into-one-code" aria-label="Anchor link for: hashing-several-values-into-one-code" style="visibility: hidden;"></a>
</h2>
<p>You can call <code>value.hash(&mut hasher)</code> several times to create a hash code composed of multiple data sources. This is useful when hashing structs or arrays.</p>
<pre class="giallo z-code"><code data-lang="rust"><span class="giallo-l"><span class="z-keyword">use</span><span class="z-entity z-name z-namespace"> std</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-namespace">hash</span><span class="z-keyword z-operator">::</span><span class="z-punctuation">{</span><span class="z-entity z-name z-type">DefaultHasher</span><span class="z-punctuation">,</span><span class="z-entity z-name z-type"> Hash</span><span class="z-punctuation">,</span><span class="z-entity z-name z-type"> Hasher</span><span class="z-punctuation">}</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type z-rust">let</span><span class="z-storage z-modifier"> mut</span><span class="z-source"> hasher</span><span class="z-keyword z-operator"> =</span><span class="z-entity z-name z-type"> DefaultHasher</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-function">new</span><span class="z-punctuation">(</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-string">"</span><span class="z-string">Hello</span><span class="z-punctuation z-definition z-string">"</span><span class="z-keyword z-operator">.</span><span class="z-entity z-name z-function">hash</span><span class="z-punctuation">(</span><span class="z-keyword z-operator">&</span><span class="z-storage z-modifier">mut</span><span class="z-variable z-other z-rust"> hasher</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"><span class="z-constant z-numeric">13</span><span class="z-entity z-name z-type z-numeric z-rust">u64</span><span class="z-keyword z-operator">.</span><span class="z-entity z-name z-function">hash</span><span class="z-punctuation">(</span><span class="z-keyword z-operator">&</span><span class="z-storage z-modifier">mut</span><span class="z-variable z-other z-rust"> hasher</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"><span class="z-constant z-language">false</span><span class="z-keyword z-operator">.</span><span class="z-entity z-name z-function">hash</span><span class="z-punctuation">(</span><span class="z-keyword z-operator">&</span><span class="z-storage z-modifier">mut</span><span class="z-variable z-other z-rust"> hasher</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type z-rust">let</span><span class="z-source"> hash</span><span class="z-keyword z-operator">:</span><span class="z-entity z-name z-type z-numeric z-rust"> u64</span><span class="z-keyword z-operator"> =</span><span class="z-source"> hasher</span><span class="z-keyword z-operator">.</span><span class="z-entity z-name z-function">finish</span><span class="z-punctuation">(</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-entity z-name z-function z-macro z-rust">println!</span><span class="z-punctuation">(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">Hash: </span><span class="z-punctuation">{</span><span class="z-string">hash</span><span class="z-punctuation">}</span><span class="z-punctuation z-definition z-string">"</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Hash: 3402450879032501501</span></span></code></pre><h2 id="hash-hasher-and-defaulthasher"><code>Hash</code>, <code>Hasher</code>, and <code>DefaultHasher</code><a class="zola-anchor" href="#hash-hasher-and-defaulthasher" aria-label="Anchor link for: hash-hasher-and-defaulthasher" style="visibility: hidden;"></a>
</h2>
<ul>
<li><a rel="external" href="https://doc.rust-lang.org/stable/std/hash/trait.Hash.html"><code>Hash</code></a>: a type that can be hashed (<code>str</code>, <code>u64</code>, <code>bool</code>, etc.)</li>
<li><a rel="external" href="https://doc.rust-lang.org/stable/std/hash/trait.Hasher.html"><code>Hasher</code></a>: a hashing algorithm (<code>DefaultHasher</code>, 3rd-party implementations)</li>
<li><a rel="external" href="https://doc.rust-lang.org/stable/std/hash/struct.DefaultHasher.html"><code>DefaultHasher</code></a>: Rust's default hashing algorithm<sup class="footnote-reference" id="fr-siphash-1"><a href="#fn-siphash">1</a></sup></li>
</ul>
<p><code>Hasher</code>s are never re-used to make several hash codes. If you want to compute a new hash code, you discard the current <code>Hasher</code> and create a new one.</p>
<h2 id="hashing-with-a-random-seed">Hashing with a Random Seed<a class="zola-anchor" href="#hashing-with-a-random-seed" aria-label="Anchor link for: hashing-with-a-random-seed" style="visibility: hidden;"></a>
</h2>
<p>To make a hash resilient to <a rel="external" href="https://en.wikipedia.org/wiki/Collision_attack#Hash_flooding">hash flooding</a>, you can create a <code>Hasher</code> with a random seed using <code>RandomState</code>.</p>
<pre class="giallo z-code"><code data-lang="rust"><span class="giallo-l"><span class="z-keyword">use</span><span class="z-entity z-name z-namespace"> std</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-namespace">hash</span><span class="z-keyword z-operator">::</span><span class="z-punctuation">{</span><span class="z-entity z-name z-type">BuildHasher</span><span class="z-punctuation">,</span><span class="z-entity z-name z-type"> Hash</span><span class="z-punctuation">,</span><span class="z-entity z-name z-type"> Hasher</span><span class="z-punctuation">,</span><span class="z-entity z-name z-type"> RandomState</span><span class="z-punctuation">}</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type z-rust">let</span><span class="z-source"> state</span><span class="z-keyword z-operator"> =</span><span class="z-entity z-name z-type"> RandomState</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-function">new</span><span class="z-punctuation">(</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type z-rust">let</span><span class="z-storage z-modifier"> mut</span><span class="z-source"> hasher</span><span class="z-keyword z-operator"> =</span><span class="z-source"> state</span><span class="z-keyword z-operator">.</span><span class="z-entity z-name z-function">build_hasher</span><span class="z-punctuation">(</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-string">"</span><span class="z-string">Hello, world!</span><span class="z-punctuation z-definition z-string">"</span><span class="z-keyword z-operator">.</span><span class="z-entity z-name z-function">hash</span><span class="z-punctuation">(</span><span class="z-keyword z-operator">&</span><span class="z-storage z-modifier">mut</span><span class="z-variable z-other z-rust"> hasher</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"><span class="z-storage z-type z-rust">let</span><span class="z-source"> hash</span><span class="z-keyword z-operator"> =</span><span class="z-source"> hasher</span><span class="z-keyword z-operator">.</span><span class="z-entity z-name z-function">finish</span><span class="z-punctuation">(</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-entity z-name z-function z-macro z-rust">println!</span><span class="z-punctuation">(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">Hash: </span><span class="z-punctuation">{</span><span class="z-string">hash</span><span class="z-punctuation">}</span><span class="z-punctuation z-definition z-string">"</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Hash: 1905042730872565693</span></span></code></pre>
<p>There's also a shorthand for this pattern using <a rel="external" href="https://doc.rust-lang.org/stable/std/hash/trait.BuildHasher.html#method.hash_one"><code>BuildHasher::hash_one()</code></a>.</p>
<pre class="giallo z-code"><code data-lang="rust"><span class="giallo-l"><span class="z-keyword">use</span><span class="z-entity z-name z-namespace"> std</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-namespace">hash</span><span class="z-keyword z-operator">::</span><span class="z-punctuation">{</span><span class="z-entity z-name z-type">BuildHasher</span><span class="z-punctuation">,</span><span class="z-entity z-name z-type"> RandomState</span><span class="z-punctuation">}</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type z-rust">let</span><span class="z-source"> state</span><span class="z-keyword z-operator"> =</span><span class="z-entity z-name z-type"> RandomState</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-function">new</span><span class="z-punctuation">(</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type z-rust">let</span><span class="z-source"> hash</span><span class="z-keyword z-operator"> =</span><span class="z-source"> state</span><span class="z-keyword z-operator">.</span><span class="z-entity z-name z-function">hash_one</span><span class="z-punctuation">(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">Hello, world!</span><span class="z-punctuation z-definition z-string">"</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-entity z-name z-function z-macro z-rust">println!</span><span class="z-punctuation">(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">Hash: </span><span class="z-punctuation">{</span><span class="z-string">hash</span><span class="z-punctuation">}</span><span class="z-punctuation z-definition z-string">"</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Hash: 11506452463443521132</span></span></code></pre>
<p>Note how the hash codes are different from the two examples, even though they're both hashing <code>"Hello, world!"</code>, because <code>RandomState::new()</code> creates a new random seed each time it is called.</p>
<h2 id="buildhasher-and-randomseed"><code>BuildHasher</code> and <code>RandomSeed</code><a class="zola-anchor" href="#buildhasher-and-randomseed" aria-label="Anchor link for: buildhasher-and-randomseed" style="visibility: hidden;"></a>
</h2>
<ul>
<li><a rel="external" href="https://doc.rust-lang.org/stable/std/hash/trait.BuildHasher.html"><code>BuildHasher</code></a>: a type that can create a new <code>Hasher</code> with a seed</li>
<li><a rel="external" href="https://doc.rust-lang.org/stable/std/hash/struct.RandomState.html"><code>RandomState</code></a>: generates a random seed when constructed, then builds <code>Hasher</code>s using that seed</li>
</ul>
<p>If you want to hash two separate values and compare them for equality, you would typically create one <code>RandomState</code> then use it to build two <code>DefaultHasher</code>s with the same seed.<sup class="footnote-reference" id="fr-default-hasher-new-1"><a href="#fn-default-hasher-new">2</a></sup></p>
<h2 id="deriving-hash">Deriving <code>Hash</code><a class="zola-anchor" href="#deriving-hash" aria-label="Anchor link for: deriving-hash" style="visibility: hidden;"></a>
</h2>
<p>The easiest way to make a custom type hashable is by deriving <code>Hash</code>.</p>
<pre class="giallo z-code"><code data-lang="rust"><span class="giallo-l"><span class="z-keyword">use</span><span class="z-entity z-name z-namespace"> std</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-namespace">hash</span><span class="z-keyword z-operator">::</span><span class="z-punctuation">{</span><span class="z-entity z-name z-type">DefaultHasher</span><span class="z-punctuation">,</span><span class="z-entity z-name z-type"> Hash</span><span class="z-punctuation">,</span><span class="z-entity z-name z-type"> Hasher</span><span class="z-punctuation">}</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-attribute z-rust">#</span><span class="z-punctuation">[</span><span class="z-meta z-attribute z-rust">derive</span><span class="z-punctuation">(</span><span class="z-entity z-name z-type">Hash</span><span class="z-punctuation">)</span><span class="z-punctuation">]</span></span>
<span class="giallo-l"><span class="z-storage z-type z-rust">struct</span><span class="z-entity z-name z-type"> Foo</span><span class="z-punctuation"> {</span></span>
<span class="giallo-l"><span class="z-source"> a</span><span class="z-keyword z-operator">:</span><span class="z-keyword z-operator"> &</span><span class="z-punctuation">'</span><span class="z-entity z-name z-type z-lifetime">static</span><span class="z-entity z-name z-type"> str</span><span class="z-punctuation">,</span></span>
<span class="giallo-l"><span class="z-source"> b</span><span class="z-keyword z-operator">:</span><span class="z-entity z-name z-type z-numeric z-rust"> u64</span><span class="z-punctuation">,</span></span>
<span class="giallo-l"><span class="z-source"> c</span><span class="z-keyword z-operator">:</span><span class="z-entity z-name z-type"> bool</span><span class="z-punctuation">,</span></span>
<span class="giallo-l"><span class="z-punctuation">}</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type z-rust">let</span><span class="z-storage z-modifier"> mut</span><span class="z-source"> hasher</span><span class="z-keyword z-operator"> =</span><span class="z-entity z-name z-type"> DefaultHasher</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-function">new</span><span class="z-punctuation">(</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-entity z-name z-type">Foo</span><span class="z-punctuation"> {</span><span class="z-source"> a</span><span class="z-keyword z-operator">:</span><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">Hello</span><span class="z-punctuation z-definition z-string">"</span><span class="z-punctuation">,</span><span class="z-source"> b</span><span class="z-keyword z-operator">:</span><span class="z-constant z-numeric"> 13</span><span class="z-punctuation">,</span><span class="z-source"> c</span><span class="z-keyword z-operator">:</span><span class="z-constant z-language"> false</span><span class="z-punctuation"> }</span><span class="z-keyword z-operator">.</span><span class="z-entity z-name z-function">hash</span><span class="z-punctuation">(</span><span class="z-keyword z-operator">&</span><span class="z-storage z-modifier">mut</span><span class="z-variable z-other z-rust"> hasher</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type z-rust">let</span><span class="z-source"> hash</span><span class="z-keyword z-operator">:</span><span class="z-entity z-name z-type z-numeric z-rust"> u64</span><span class="z-keyword z-operator"> =</span><span class="z-source"> hasher</span><span class="z-keyword z-operator">.</span><span class="z-entity z-name z-function">finish</span><span class="z-punctuation">(</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-entity z-name z-function z-macro z-rust">println!</span><span class="z-punctuation">(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">Hash: </span><span class="z-punctuation">{</span><span class="z-string">hash</span><span class="z-punctuation">}</span><span class="z-punctuation z-definition z-string">"</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Hash: 3402450879032501501</span></span></code></pre><h2 id="implementing-hash-manually">Implementing <code>Hash</code> Manually<a class="zola-anchor" href="#implementing-hash-manually" aria-label="Anchor link for: implementing-hash-manually" style="visibility: hidden;"></a>
</h2>
<p>If you look closely, you'll notice that the hash codes from <a href="https://bd103.dev/blog/2025-11-10-rust-hashing-cheat-sheet/#hashing-several-values-into-one-code">Hashing Several Values into One Code</a> and <a href="https://bd103.dev/blog/2025-11-10-rust-hashing-cheat-sheet/#deriving-hash">Deriving <code>Hash</code></a> are equal! This is because they're hashing the same data in the same order with the same seed. To prove this, we can expand the <code>Hash</code> derivation:</p>
<pre class="giallo z-code"><code data-lang="rust"><span class="giallo-l"><span class="z-keyword">use</span><span class="z-entity z-name z-namespace"> std</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-namespace">hash</span><span class="z-keyword z-operator">::</span><span class="z-punctuation">{</span><span class="z-entity z-name z-type">Hash</span><span class="z-punctuation">,</span><span class="z-entity z-name z-type"> Hasher</span><span class="z-punctuation">}</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type z-rust">struct</span><span class="z-entity z-name z-type"> Foo</span><span class="z-punctuation"> {</span></span>
<span class="giallo-l"><span class="z-source"> a</span><span class="z-keyword z-operator">:</span><span class="z-keyword z-operator"> &</span><span class="z-punctuation">'</span><span class="z-entity z-name z-type z-lifetime">static</span><span class="z-entity z-name z-type"> str</span><span class="z-punctuation">,</span></span>
<span class="giallo-l"><span class="z-source"> b</span><span class="z-keyword z-operator">:</span><span class="z-entity z-name z-type z-numeric z-rust"> u64</span><span class="z-punctuation">,</span></span>
<span class="giallo-l"><span class="z-source"> c</span><span class="z-keyword z-operator">:</span><span class="z-entity z-name z-type"> bool</span><span class="z-punctuation">,</span></span>
<span class="giallo-l"><span class="z-punctuation">}</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-keyword">impl</span><span class="z-entity z-name z-type"> Hash</span><span class="z-keyword"> for</span><span class="z-entity z-name z-type"> Foo</span><span class="z-punctuation"> {</span></span>
<span class="giallo-l"><span class="z-keyword"> fn</span><span class="z-entity z-name z-function"> hash</span><span class="z-punctuation z-brackets z-angle z-rust"><</span><span class="z-entity z-name z-type">H</span><span class="z-keyword z-operator">:</span><span class="z-entity z-name z-type"> Hasher</span><span class="z-punctuation z-brackets z-angle z-rust">></span><span class="z-punctuation">(</span><span class="z-keyword z-operator">&</span><span class="z-variable z-language z-self z-rust">self</span><span class="z-punctuation">,</span><span class="z-variable z-other z-rust"> state</span><span class="z-keyword z-operator">:</span><span class="z-keyword z-operator"> &</span><span class="z-storage z-modifier">mut</span><span class="z-entity z-name z-type"> H</span><span class="z-punctuation">)</span><span class="z-punctuation"> {</span></span>
<span class="giallo-l"><span class="z-variable z-language z-self z-rust"> self</span><span class="z-keyword z-operator">.</span><span class="z-source">a</span><span class="z-keyword z-operator">.</span><span class="z-entity z-name z-function">hash</span><span class="z-punctuation">(</span><span class="z-variable z-other z-rust">state</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"><span class="z-variable z-language z-self z-rust"> self</span><span class="z-keyword z-operator">.</span><span class="z-source">b</span><span class="z-keyword z-operator">.</span><span class="z-entity z-name z-function">hash</span><span class="z-punctuation">(</span><span class="z-variable z-other z-rust">state</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"><span class="z-variable z-language z-self z-rust"> self</span><span class="z-keyword z-operator">.</span><span class="z-source">c</span><span class="z-keyword z-operator">.</span><span class="z-entity z-name z-function">hash</span><span class="z-punctuation">(</span><span class="z-variable z-other z-rust">state</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"><span class="z-punctuation"> }</span></span>
<span class="giallo-l"><span class="z-punctuation">}</span></span></code></pre><h2 id="conclusion">Conclusion<a class="zola-anchor" href="#conclusion" aria-label="Anchor link for: conclusion" style="visibility: hidden;"></a>
</h2>
<p>I hope these examples help you wrap your head around Rust's hashing support! While I didn't cover it in this article, you may be also interested in <a rel="external" href="https://doc.rust-lang.org/stable/std/hash/trait.Hasher.html"><code>Hasher</code></a>'s methods and how primitives like <a rel="external" href="https://doc.rust-lang.org/stable/std/hash/trait.Hash.html#impl-Hash-for-bool"><code>bool</code></a>, <a rel="external" href="https://doc.rust-lang.org/stable/std/hash/trait.Hash.html#impl-Hash-for-char"><code>char</code></a>, and <a rel="external" href="https://doc.rust-lang.org/stable/std/hash/trait.Hash.html#impl-Hash-for-(T,)">tuples</a> implement <code>Hash</code>. You may also enjoy looking at <a rel="external" href="https://lib.rs/crates/rustc-hash"><code>rustc-hash</code></a> (previous <code>fxhash</code>), <a rel="external" href="https://lib.rs/crates/fnv"><code>fnv</code></a>, <a rel="external" href="https://lib.rs/crates/sha2"><code>sha2</code></a>, and <a rel="external" href="https://lib.rs/crates/blake2"><code>blake2</code></a>.</p>
<p>Happy hacking!</p>
<section class="footnotes">
<ol class="footnotes-list">
<li id="fn-siphash">
<p>In Rust 1.91.0 the default hashing algorithm is <a rel="external" href="https://en.wikipedia.org/wiki/SipHash">SipHash 1-3</a>, but this is an internal detail that may change in the future. <a href="#fr-siphash-1">↩</a></p>
</li>
<li id="fn-default-hasher-new">
<p>Technically, you could just create the two hashers by calling <code>DefaultHasher::new()</code>, which initializes them with a seed of 0. This is vulnerable to <a rel="external" href="https://en.wikipedia.org/wiki/Collision_attack#Hash_flooding">hash flooding</a> attacks, however, so I don't recommend it! <a href="#fr-default-hasher-new-1">↩</a></p>
</li>
</ol>
</section>
Bevy's 5th Birthday: Year of the Linter2025-09-09T00:00:00+00:002025-09-09T00:00:00+00:00
BD103
https://bd103.dev/blog/2025-09-09-bevys-5th-birthday/<p><a rel="external" href="https://bevy.org/">Bevy</a> is an open-source game engine built in Rust. On August 10th, 2025, the project lead Cart <a rel="external" href="https://bevy.org/news/bevys-fifth-birthday/">celebrated Bevy's 5th birthday with a blog post</a>, and I wanted to do the same!</p>
<h2 id="hi-i-m-bd103">Hi, I'm BD103<a class="zola-anchor" href="#hi-i-m-bd103" aria-label="Anchor link for: hi-i-m-bd103" style="visibility: hidden;"></a>
</h2>
<p>For those uninitiated, I'm BD103! I'm a programmer who's been working on Bevy for a little under 2 years, at this point. <a href="https://bd103.dev/blog/2024-08-18-4-years-of-bevy/">Last year</a> I talked about how I got involved with Bevy and how I found my place working on the CI infrastructure. This year, you’re in for a treat, as I took my work in a fun, new direction!</p>
<h2 id="nerd-snipe-of-the-year">Nerd Snipe of the Year<a class="zola-anchor" href="#nerd-snipe-of-the-year" aria-label="Anchor link for: nerd-snipe-of-the-year" style="visibility: hidden;"></a>
</h2>
<p>In late August of 2024, one of the maintainers, <a rel="external" href="https://github.com/alice-i-cecile">Alice</a>, was helping a contributor find larger, independent projects to work on related to Bevy. One of the ideas she mentioned was a Bevy CLI, a command-line tool that would help users setup and manage their Bevy projects.</p>
<p>Now the idea of a Bevy CLI has been around for quite some time, with <a rel="external" href="https://github.com/bevyengine/bevy/issues/436">an issue opened about it in late 2020</a>. When I saw Alice mention a Bevy CLI, I did some digging and found that specific issue. In the issue description it listed several possible commands, but one of which really caught my attention:</p>
<blockquote class="quote">
<div class="icon" style="display: none;"><svg fill="currentColor" xmlns="http://www.w3.org/2000/svg" width="10" height="10" viewBox="796 698 200 200">
<g>
<path d="M885.208,749.739v-40.948C836.019,708.791,796,748.81,796,798v89.209h89.208V798h-48.26
C836.948,771.39,858.598,749.739,885.208,749.739z"/>
<path d="M996,749.739v-40.948c-49.19,0-89.209,40.019-89.209,89.209v89.209H996V798h-48.26
C947.74,771.39,969.39,749.739,996,749.739z"/>
</g>
</svg>
</div>
<div class="content"><ul>
<li><code>bevy lint</code> - possibly checks the project for best practices?</li>
</ul>
</div>
<div class="from">
<p>— <a rel="external" href="https://github.com/bevyengine/bevy/issues/436">bevy cli #436</a></p>
</div>
</blockquote>
<p>So...</p>
<figure>
<img
src="nerd-sniping.png"
alt="A comic panel of a truck running someone over"
>
<figcaption><p>I was thoroughly nerd-sniped, <a rel="external" href="https://xkcd.com/356/">via</a></p>
</figcaption>
</figure>
<h2 id="thankfully-i-did-not-get-run-over-by-a-truck">Thankfully I Did Not Get Run Over by a Truck<sup class="footnote-reference" id="fr-1-1"><a href="#fn-1">1</a></sup><a class="zola-anchor" href="#thankfully-i-did-not-get-run-over-by-a-truck" aria-label="Anchor link for: thankfully-i-did-not-get-run-over-by-a-truck" style="visibility: hidden;"></a>
</h2>
<p>The concept of a Bevy linter led me down a <em>looooong</em> rabbit hole, but I hit the bottom with a skip in my step and a plan of action in my head. I joined the newly-created <a rel="external" href="https://discord.com/channels/691052431525675048/1278871953721262090">Bevy CLI working group</a> and wrote <a rel="external" href="https://hackmd.io/@bevy/ryelRBqiiR">a design document</a> for the linter based on the architecture of <a rel="external" href="https://github.com/rust-lang/rust-clippy">Clippy</a>. Once I got a thumbs-up 👍 from the working group, I got to work contributing my design to the new <a rel="external" href="https://github.com/TheBevyFlock/bevy_cli"><code>TheBevyFlock/bevy_cli</code></a> repository.</p>
<p>From late August to mid-November, I and a few others worked on the linter until we got it to a place where <a rel="external" href="https://github.com/TheBevyFlock/bevy_cli/releases/tag/lint-v0.1.0">it could be released as v0.1.0</a>. That release came with 6 lints, live documentation, and lots of infrastructure set up for future releases.</p>
<h2 id="briefly-being-famous">Briefly Being Famous<a class="zola-anchor" href="#briefly-being-famous" aria-label="Anchor link for: briefly-being-famous" style="visibility: hidden;"></a>
</h2>
<p>4 days after releasing v0.1.0, I went on the <a rel="external" href="https://www.youtube.com/watch?v=Ao2gXd_CgUc">7th Bevy Meetup livestream</a> and presented a talk on the linter. In my talk I went into the architecture behind the linter, and gave examples building up a new linter from scratch using the same method. You can <a rel="external" href="https://github.com/BD103/Bevy-Meetup-7">see the demo code and slides here</a>, if you're curious. It was great working with the host <a rel="external" href="https://github.com/extrawurst">Stephan</a>, and I really enjoyed presenting alongside speakers <a rel="external" href="https://github.com/bushrat011899">Zac</a> and <a rel="external" href="https://github.com/UkoeHB">Koe</a>!</p>
<h2 id="the-next-3-releases">The Next 3 Releases<a class="zola-anchor" href="#the-next-3-releases" aria-label="Anchor link for: the-next-3-releases" style="visibility: hidden;"></a>
</h2>
<p>After the first release, I and a few others in the working group published <a rel="external" href="https://github.com/TheBevyFlock/bevy_cli/releases/tag/lint-v0.2.0">v0.2.0 in March of 2025</a>, <a rel="external" href="https://github.com/TheBevyFlock/bevy_cli/releases/tag/lint-v0.3.0">v0.3.0 in April of 2025</a>, and <a rel="external" href="https://github.com/TheBevyFlock/bevy_cli/releases/tag/lint-v0.4.0">v0.4.0 in August of 2025</a>. While these releases did add several new lints, much of my personal work focused on other aspects of the linter:</p>
<ul>
<li>Upgrading to support new versions of Bevy and Rust</li>
<li>Fixing and improving existing lints, renaming and merging them when it made sense</li>
<li>Writing and refining our external and internal documentation</li>
<li>Adding support for configuring lints in <code>Cargo.toml</code></li>
<li>Assisting with writing <a rel="external" href="https://github.com/rust-lang/rfcs/pull/3808">RFC 3808</a> in order to make it easier to configure lints within code</li>
<li>Improving support for running the linter in Github Actions</li>
<li>Adding the ability to auto-fix warnings with the <code>--fix</code> flag</li>
</ul>
<p>This has been a trend in my work for a while. While I do enjoy writing new features, I tend to spend a lot more time looking over existing code and trying my best to improve it. I would like to write more lints, as I'm not satisfied with <a rel="external" href="https://thebevyflock.github.io/bevy_cli/api/bevy_lint/lints/index.html">our current selection</a>, but that's a project for a later date.</p>
<h2 id="thank-you">Thank You<a class="zola-anchor" href="#thank-you" aria-label="Anchor link for: thank-you" style="visibility: hidden;"></a>
</h2>
<p>The Bevy community is such a kind and welcoming place, and I'd be remiss to not mention my co-maintainers who I've worked with in the Bevy CLI working group for the past year!</p>
<h3 id="tim"><a rel="external" href="https://github.com/TimJentzsch">Tim</a><a class="zola-anchor" href="#tim" aria-label="Anchor link for: tim" style="visibility: hidden;"></a>
</h3>
<p>Tim, you are the driving force behind the CLI since its earliest days in the working group. Many of the largest features, including <a rel="external" href="https://thebevyflock.github.io/bevy_cli/cli/web.html">easy web support</a> and <a rel="external" href="https://github.com/TheBevyFlock/bevy_cli/pull/547">the upcoming <code>getrandom</code> fix</a>, were implemented by of you. You've truly left your mark on the Bevy community<sup class="footnote-reference" id="fr-2-1"><a href="#fn-2">2</a></sup>, and it's been wonderful working alongside you!</p>
<h3 id="david"><a rel="external" href="https://github.com/DaAlbrecht">David</a><a class="zola-anchor" href="#david" aria-label="Anchor link for: david" style="visibility: hidden;"></a>
</h3>
<p>David, you were the first outside contributor to <em>continuously</em> work on the CLI and linter. Although we've had several one-off contributions from others, you both started and stuck with the project. Unlike Tim who specializes in the CLI and myself who specializes in the linter, you've worked on and improved both. You're knowledge of both tools has made you super valuable in the review process, and it's been really fun getting to know you!</p>
<h2 id="in-conclusion">In Conclusion<a class="zola-anchor" href="#in-conclusion" aria-label="Anchor link for: in-conclusion" style="visibility: hidden;"></a>
</h2>
<p>I'm truly grateful to have been given the opportunity to work on Bevy and within its ecosystem. While the project itself is cool<sup class="footnote-reference" id="fr-3-1"><a href="#fn-3">3</a></sup>, <strong>the people are why I stayed</strong>.</p>
<p>If you use Bevy and haven't given it a shot yet, I'd really appreciate it if you <a rel="external" href="https://thebevyflock.github.io/bevy_cli/">tried out the CLI and linter for yourself</a>! They're both unofficial right now, but we're working on upstreaming them into an official product in the near future.</p>
<p>If you'd like to support my work, you can do so indirectly by <a rel="external" href="https://bevy.org/donate/">donating to the Bevy Foundation</a> or by <a rel="external" href="https://merch.bevy.org">purchasing some sweet official merch</a>. I'm not in a position to take donations myself, but <a rel="external" href="https://bevy.org/community/people/">the people working for the foundation</a> are wonderful and highly deserving of any support you can give them.</p>
<p>If you'd like to see more posts by community members on Bevy's 5th Birthday, I've enjoyed reading through these:</p>
<ul>
<li><a rel="external" href="https://bevy.org/news/bevys-fifth-birthday/">Cart's Perspective</a></li>
<li><a rel="external" href="https://www.charlotte.fyi/posts/bevys-fifth-bday">Charlotte's Perspective</a></li>
<li><a rel="external" href="https://rinoxide.substack.com/p/bevys-fifth-birthday-the-editor">Rin's Perspective</a></li>
<li><a rel="external" href="https://jms55.github.io/posts/2025-09-03-bevy-fifth-birthday/">Jasmine's Perspective</a></li>
</ul>
<p>There are also several more <a rel="external" href="https://github.com/bevyengine/bevy-website/issues/2202">in the community submissions issue on Github</a> that I highly recommend checking out!</p>
<p>That's all from me for now! If you'd like to chat, I'm @bd103 <a rel="external" href="https://discord.gg/bevy">on Discord</a> and <a rel="external" href="https://hachyderm.io/@bd103">@bd103@hachyderm.io</a> on Mastodon. Until next time,</p>
<p>- BD103</p>
<section class="footnotes">
<ol class="footnotes-list">
<li id="fn-1">
<p>But any future work I may have done on the engine itself did get run over by the said metaphorical truck. I was officially nerd-sniped. <a href="#fr-1-1">↩</a></p>
</li>
<li id="fn-2">
<p>This is especially true for the jammers who participated in the <a rel="external" href="https://itch.io/jam/bevy-jam-6">6th Bevy Game jam</a>. The CLI combined with <a rel="external" href="https://github.com/TheBevyFlock/bevy_new_2d"><code>bevy_new_2d</code></a> <em>drastically</em> decreased the difficulty of making a new Bevy game from scratch. <a href="#fr-2-1">↩</a></p>
</li>
<li id="fn-3">
<p>Game engines are really fun to build, especially when you want to make one that's both efficient and ergonomic! <a href="#fr-3-1">↩</a></p>
</li>
</ol>
</section>
Be Careful Zero-Copying Strings with serde2025-09-01T00:00:00+00:002025-09-01T00:00:00+00:00
BD103
https://bd103.dev/blog/2025-09-01-zero-copying-strings-serde/<p>When deserializing a string using <a rel="external" href="https://serde.rs/"><code>serde</code></a>, it is possible to use a borrowed <a rel="external" href="https://doc.rust-lang.org/stable/std/primitive.str.html"><code>&str</code></a> instead of an owned <a rel="external" href="https://doc.rust-lang.org/stable/std/string/struct.String.html"><code>String</code></a>:</p>
<pre class="giallo z-code"><code data-lang="rust"><span class="giallo-l"><span class="z-keyword">use</span><span class="z-entity z-name z-namespace"> serde</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-type">Deserialize</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"><span class="z-keyword">use</span><span class="z-source"> serde_json</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-attribute z-rust">#</span><span class="z-punctuation">[</span><span class="z-meta z-attribute z-rust">derive</span><span class="z-punctuation">(</span><span class="z-entity z-name z-type">Deserialize</span><span class="z-punctuation">)</span><span class="z-punctuation">]</span></span>
<span class="giallo-l"><span class="z-storage z-type z-rust">struct</span><span class="z-entity z-name z-type"> Foo</span><span class="z-punctuation z-brackets z-angle z-rust"><</span><span class="z-punctuation">'</span><span class="z-entity z-name z-type z-lifetime">a</span><span class="z-punctuation z-brackets z-angle z-rust">></span><span class="z-punctuation"> {</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> This string is borrowed.</span></span>
<span class="giallo-l"><span class="z-source"> text</span><span class="z-keyword z-operator">:</span><span class="z-keyword z-operator"> &</span><span class="z-punctuation">'</span><span class="z-entity z-name z-type z-lifetime">a</span><span class="z-entity z-name z-type"> str</span><span class="z-punctuation">,</span></span>
<span class="giallo-l"><span class="z-punctuation">}</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-keyword">fn</span><span class="z-entity z-name z-function"> main</span><span class="z-punctuation">(</span><span class="z-punctuation">)</span><span class="z-punctuation"> {</span></span>
<span class="giallo-l"><span class="z-storage z-type z-rust"> let</span><span class="z-source"> json</span><span class="z-keyword z-operator"> =</span><span class="z-string"> r</span><span class="z-punctuation z-definition z-string">#</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">{ "text": "Hello, world!" }</span><span class="z-punctuation z-definition z-string">"</span><span class="z-punctuation z-definition z-string">#</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type z-rust"> let</span><span class="z-source"> foo</span><span class="z-keyword z-operator">:</span><span class="z-entity z-name z-type"> Foo</span><span class="z-keyword z-operator"> =</span><span class="z-entity z-name z-namespace"> serde_json</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-function">from_str</span><span class="z-punctuation">(</span><span class="z-variable z-other z-rust">json</span><span class="z-punctuation">)</span><span class="z-keyword z-operator">.</span><span class="z-entity z-name z-function">unwrap</span><span class="z-punctuation">(</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-entity z-name z-function z-macro z-rust"> println!</span><span class="z-punctuation">(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-punctuation">{</span><span class="z-punctuation">}</span><span class="z-punctuation z-definition z-string">"</span><span class="z-punctuation">,</span><span class="z-source"> foo</span><span class="z-keyword z-operator">.</span><span class="z-source">text</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Hello, world!</span></span>
<span class="giallo-l"><span class="z-punctuation">}</span></span></code></pre>
<p>The borrowed string is a reference to a portion of the original serialized data. In this case, <code>foo.text</code> refers to a slice of the <code>json</code> variable that contains the text <code>Hello, world!</code>.</p>
<p>This process is called zero-copy deserialization, and can be more efficient than allocating a new <code>String</code> and copying the data to it. Be warned, however; <strong>some strings cannot be deserialized into <code>&str</code>, and must be deserialized into a <code>String</code> instead</strong>.</p>
<p>The specific case where I found this out was when I was deserializing text with backslashes in it:</p>
<pre class="giallo z-code"><code data-lang="rust"><span class="giallo-l"><span class="z-storage z-type z-rust">let</span><span class="z-source"> json</span><span class="z-keyword z-operator"> =</span><span class="z-string"> r</span><span class="z-punctuation z-definition z-string">#</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">{ "text": "Go to C:\\Users\\bd\\Desktop" }</span><span class="z-punctuation z-definition z-string">"</span><span class="z-punctuation z-definition z-string">#</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type z-rust">let</span><span class="z-source"> foo</span><span class="z-keyword z-operator">:</span><span class="z-entity z-name z-type"> Foo</span><span class="z-keyword z-operator"> =</span><span class="z-entity z-name z-namespace"> serde_json</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-function">from_str</span><span class="z-punctuation">(</span><span class="z-variable z-other z-rust">json</span><span class="z-punctuation">)</span><span class="z-keyword z-operator">.</span><span class="z-entity z-name z-function">unwrap</span><span class="z-punctuation">(</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-entity z-name z-function z-macro z-rust">println!</span><span class="z-punctuation">(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-punctuation">{</span><span class="z-punctuation">}</span><span class="z-punctuation z-definition z-string">"</span><span class="z-punctuation">,</span><span class="z-source"> foo</span><span class="z-keyword z-operator">.</span><span class="z-source">text</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span></code></pre>
<p>Instead of printing <code>Go to C:\Users\bd\Desktop</code> as I expected, it instead panicked!</p>
<pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>thread 'main' panicked at src/main.rs:12:47:</span></span>
<span class="giallo-l"><span>called `Result::unwrap()` on an `Err` value: Error("invalid type: string \"Go to C:\\\\Users\\\\bd\\\\Desktop\", expected a borrowed string", line: 1, column: 34)</span></span></code></pre>
<p>When deserializing the text, <code>serde_json</code> needs to convert <code>Go to C:\\Users\\bd\\Desktop</code> to <code>Go to C:\Users\bd\Desktop</code>. The only way it can do that is by <em>allocating a new string</em>. <code>serde_json</code> can't do that here, however, because we told it not to by using zero-copy deserialization!</p>
<p>In order to fix this, you need to replace the borrowed <code>&str</code> with an owned <code>String</code>. It can be slower than zero-copy deserialization, but it supports <em>all</em> possible data inputs:</p>
<pre class="giallo z-code"><code data-lang="rust"><span class="giallo-l"><span class="z-keyword">use</span><span class="z-entity z-name z-namespace"> serde</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-type">Deserialize</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"><span class="z-keyword">use</span><span class="z-source"> serde_json</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-attribute z-rust">#</span><span class="z-punctuation">[</span><span class="z-meta z-attribute z-rust">derive</span><span class="z-punctuation">(</span><span class="z-entity z-name z-type">Deserialize</span><span class="z-punctuation">)</span><span class="z-punctuation">]</span></span>
<span class="giallo-l"><span class="z-storage z-type z-rust">struct</span><span class="z-entity z-name z-type"> Foo</span><span class="z-punctuation"> {</span></span>
<span class="giallo-l"><span class="z-source"> text</span><span class="z-keyword z-operator">:</span><span class="z-entity z-name z-type"> String</span><span class="z-punctuation">,</span></span>
<span class="giallo-l"><span class="z-punctuation">}</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-keyword">fn</span><span class="z-entity z-name z-function"> main</span><span class="z-punctuation">(</span><span class="z-punctuation">)</span><span class="z-punctuation"> {</span></span>
<span class="giallo-l"><span class="z-storage z-type z-rust"> let</span><span class="z-source"> json</span><span class="z-keyword z-operator"> =</span><span class="z-string"> r</span><span class="z-punctuation z-definition z-string">#</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">{ "text": "Go to C:\\Users\\bd\\Desktop" }</span><span class="z-punctuation z-definition z-string">"</span><span class="z-punctuation z-definition z-string">#</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type z-rust"> let</span><span class="z-source"> foo</span><span class="z-keyword z-operator">:</span><span class="z-entity z-name z-type"> Foo</span><span class="z-keyword z-operator"> =</span><span class="z-entity z-name z-namespace"> serde_json</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-function">from_str</span><span class="z-punctuation">(</span><span class="z-variable z-other z-rust">json</span><span class="z-punctuation">)</span><span class="z-keyword z-operator">.</span><span class="z-entity z-name z-function">unwrap</span><span class="z-punctuation">(</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-entity z-name z-function z-macro z-rust"> println!</span><span class="z-punctuation">(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-punctuation">{</span><span class="z-punctuation">}</span><span class="z-punctuation z-definition z-string">"</span><span class="z-punctuation">,</span><span class="z-source"> foo</span><span class="z-keyword z-operator">.</span><span class="z-source">text</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Go to C:\Users\bd\Desktop</span></span>
<span class="giallo-l"><span class="z-punctuation">}</span></span></code></pre>
<p>This kind of issue will arise when deserializing other escape codes in JSON, such as <code>\n</code> and <code>\t</code>. It can also occur when using other types that can be zero-copied, such as <a rel="external" href="https://doc.rust-lang.org/stable/std/path/struct.Path.html"><code>&Path</code></a><sup class="footnote-reference" id="fr-1-1"><a href="#fn-1">1</a></sup>. Next time you consider using zero-copy deserialization, be sure you're ok with limiting what data you can support.</p>
<h2 id="further-reading">Further Reading:<a class="zola-anchor" href="#further-reading" aria-label="Anchor link for: further-reading" style="visibility: hidden;"></a>
</h2>
<ul>
<li><a rel="external" href="https://serde.rs/lifetimes.html">Deserializer lifetimes</a></li>
<li><a rel="external" href="https://github.com/serde-rs/serde/issues/1746">JSON string with backslashes does not deserialize into borrowed <code>&str</code></a></li>
</ul>
<h2 id="addendum">Addendum<a class="zola-anchor" href="#addendum" aria-label="Anchor link for: addendum" style="visibility: hidden;"></a>
</h2>
<p>As <a rel="external" href="https://github.com/korrat">@korrat</a> has <a rel="external" href="https://github.com/BD103/bd103.github.io/issues/15">helpfully pointed out</a>, <a rel="external" href="https://doc.rust-lang.org/stable/std/borrow/enum.Cow.html"><code>Cow<str></code></a> can be used as a compromise between <code>&str</code> and <code>String</code>. If you annotate a field with <code>#[serde(borrow)]</code>, it will first try to zero-copy deserialize the string, but will fall back to cloning the data if it needs to be modified.</p>
<p>As a result, <code>Cow<str></code> should be preferred as it offers performance improvements without restricting what data can be deserialized:</p>
<pre class="giallo z-code"><code data-lang="rust"><span class="giallo-l"><span class="z-keyword">use</span><span class="z-entity z-name z-namespace"> serde</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-type">Deserialize</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"><span class="z-keyword">use</span><span class="z-source"> serde_json</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-keyword">use</span><span class="z-entity z-name z-namespace"> std</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-namespace">borrow</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-type">Cow</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-attribute z-rust">#</span><span class="z-punctuation">[</span><span class="z-meta z-attribute z-rust">derive</span><span class="z-punctuation">(</span><span class="z-entity z-name z-type">Deserialize</span><span class="z-punctuation">)</span><span class="z-punctuation">]</span></span>
<span class="giallo-l"><span class="z-storage z-type z-rust">struct</span><span class="z-entity z-name z-type"> Foo</span><span class="z-punctuation z-brackets z-angle z-rust"><</span><span class="z-punctuation">'</span><span class="z-entity z-name z-type z-lifetime">a</span><span class="z-punctuation z-brackets z-angle z-rust">></span><span class="z-punctuation"> {</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Try to borrow the string when possible, but clone it when necessary.</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-attribute z-rust"> #</span><span class="z-punctuation">[</span><span class="z-meta z-attribute z-rust">serde</span><span class="z-punctuation">(</span><span class="z-meta z-attribute z-rust">borrow</span><span class="z-punctuation">)</span><span class="z-punctuation">]</span></span>
<span class="giallo-l"><span class="z-source"> text</span><span class="z-keyword z-operator">:</span><span class="z-entity z-name z-type"> Cow</span><span class="z-punctuation z-brackets z-angle z-rust"><</span><span class="z-punctuation">'</span><span class="z-entity z-name z-type z-lifetime">a</span><span class="z-punctuation">,</span><span class="z-entity z-name z-type"> str</span><span class="z-punctuation z-brackets z-angle z-rust">></span><span class="z-punctuation">,</span></span>
<span class="giallo-l"><span class="z-punctuation">}</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-keyword">fn</span><span class="z-entity z-name z-function"> main</span><span class="z-punctuation">(</span><span class="z-punctuation">)</span><span class="z-punctuation"> {</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> No changes need to be made, the string can be borrowed.</span></span>
<span class="giallo-l"><span class="z-storage z-type z-rust"> let</span><span class="z-source"> json</span><span class="z-keyword z-operator"> =</span><span class="z-string"> r</span><span class="z-punctuation z-definition z-string">#</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">{ "text": "Hello, world!" }</span><span class="z-punctuation z-definition z-string">"</span><span class="z-punctuation z-definition z-string">#</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type z-rust"> let</span><span class="z-source"> foo</span><span class="z-keyword z-operator">:</span><span class="z-entity z-name z-type"> Foo</span><span class="z-keyword z-operator"> =</span><span class="z-entity z-name z-namespace"> serde_json</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-function">from_str</span><span class="z-punctuation">(</span><span class="z-variable z-other z-rust">json</span><span class="z-punctuation">)</span><span class="z-keyword z-operator">.</span><span class="z-entity z-name z-function">unwrap</span><span class="z-punctuation">(</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-entity z-name z-function z-macro z-rust"> assert!</span><span class="z-punctuation">(</span><span class="z-entity z-name z-function z-macro z-rust">matches!</span><span class="z-punctuation">(</span><span class="z-source">foo</span><span class="z-keyword z-operator">.</span><span class="z-source">text</span><span class="z-punctuation">,</span><span class="z-entity z-name z-type"> Cow</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-function">Borrowed</span><span class="z-punctuation">(</span><span class="z-variable z-other z-rust">_</span><span class="z-punctuation">)</span><span class="z-punctuation">)</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Changes need to be made, the string must be owned.</span></span>
<span class="giallo-l"><span class="z-storage z-type z-rust"> let</span><span class="z-source"> json</span><span class="z-keyword z-operator"> =</span><span class="z-string"> r</span><span class="z-punctuation z-definition z-string">#</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">{ "text": "Hello,\nworld!" }</span><span class="z-punctuation z-definition z-string">"</span><span class="z-punctuation z-definition z-string">#</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type z-rust"> let</span><span class="z-source"> foo</span><span class="z-keyword z-operator">:</span><span class="z-entity z-name z-type"> Foo</span><span class="z-keyword z-operator"> =</span><span class="z-entity z-name z-namespace"> serde_json</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-function">from_str</span><span class="z-punctuation">(</span><span class="z-variable z-other z-rust">json</span><span class="z-punctuation">)</span><span class="z-keyword z-operator">.</span><span class="z-entity z-name z-function">unwrap</span><span class="z-punctuation">(</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-entity z-name z-function z-macro z-rust"> assert!</span><span class="z-punctuation">(</span><span class="z-entity z-name z-function z-macro z-rust">matches!</span><span class="z-punctuation">(</span><span class="z-source">foo</span><span class="z-keyword z-operator">.</span><span class="z-source">text</span><span class="z-punctuation">,</span><span class="z-entity z-name z-type"> Cow</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-function">Owned</span><span class="z-punctuation">(</span><span class="z-variable z-other z-rust">_</span><span class="z-punctuation">)</span><span class="z-punctuation">)</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"><span class="z-punctuation">}</span></span></code></pre>
<p>In the initial release of this post, I incorrectly wrote that <code>Cow<str></code> does not support zero-copy deserialization. This isn't the case, you just need to annotate the <code>Cow<str></code> field with <code>#[serde(borrow)]</code>. Don't forget that attribute, or <code>Cow<str></code> will just be equivalent to <code>String</code>! See <a rel="external" href="https://serde.rs/lifetimes.html#borrowing-data-in-a-derived-impl">the <code>serde</code> docs</a> for more information and examples.</p>
<section class="footnotes">
<ol class="footnotes-list">
<li id="fn-1">
<p>Be especially careful about using this type. Since it cannot deserialize backslashes, you're essentially eliminating support for Windows paths. <a href="#fr-1-1">↩</a></p>
</li>
</ol>
</section>
Announcing bevy_lint v0.2.02025-03-19T00:00:00+00:002025-09-28T00:00:00+00:00
BD103
https://bd103.dev/blog/2025-03-19-bevy-lint-v0-2-0/<span>
Hello there, my dear
<select id="adjective">
<option>punctual</option>
<option>splendiforous</option>
<option>bright</option>
<option>questionably loud</option>
</select> reader! I hope your day has been going exceptionally well.
</span>
<p>I have returned from my 6 month<sup class="footnote-reference" id="fr-1-1"><a href="#fn-1">1</a></sup> writing hiatus to give you a very special announcement: today is the official release of <code>bevy_lint</code> v0.2.0! With it comes some very exciting features that I can't wait to talk about!</p>
<p><code>bevy_lint</code> is a custom linter for the <a rel="external" href="https://bevyengine.org">Bevy game engine</a>, similar to <a rel="external" href="https://doc.rust-lang.org/clippy/">Clippy</a>, that can be used to enforce Bevy-specific idioms, catch common mistakes, and help you write better code. In order to avoid repeating myself, I highly recommend you check out <a rel="external" href="https://thebevyflock.github.io/bevy_cli/bevy_lint/index.html">its documentation</a> for an extended description, installation guide, and user guide.</p>
<p><a rel="external" href="https://github.com/TheBevyFlock/bevy_cli/releases/tag/lint-v0.1.0"><code>bevy_lint</code> v0.1.0</a> released mid-November of 2024, so it's been a good 4 months since then. In that time, I and several others have added many new features and improvements (all of which you can view <a rel="external" href="https://github.com/TheBevyFlock/bevy_cli/blob/main/bevy_lint/CHANGELOG.md">in the changelog</a>). Let's take a look at the highlights!</p>
<h2 id="configure-lints-in-cargo-toml">Configure lints in <code>Cargo.toml</code><a class="zola-anchor" href="#configure-lints-in-cargo-toml" aria-label="Anchor link for: configure-lints-in-cargo-toml" style="visibility: hidden;"></a>
</h2>
<p>If you were an early adopter of <code>bevy_lint</code>, the following header may be familiar to you:</p>
<pre class="giallo z-code"><code data-lang="rust"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> Register `bevy` as a tool.</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-attribute z-rust">#</span><span class="z-meta z-attribute z-rust">!</span><span class="z-punctuation">[</span><span class="z-meta z-attribute z-rust">cfg_attr</span><span class="z-punctuation">(</span><span class="z-meta z-attribute z-rust">bevy_lint</span><span class="z-punctuation">,</span><span class="z-meta z-attribute z-rust"> feature</span><span class="z-punctuation">(</span><span class="z-meta z-attribute z-rust">register_tool</span><span class="z-punctuation">)</span><span class="z-punctuation">,</span><span class="z-meta z-attribute z-rust"> register_tool</span><span class="z-punctuation">(</span><span class="z-meta z-attribute z-rust">bevy</span><span class="z-punctuation">)</span><span class="z-punctuation">)</span><span class="z-punctuation">]</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> Enable pedantic lints.</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-attribute z-rust">#</span><span class="z-meta z-attribute z-rust">!</span><span class="z-punctuation">[</span><span class="z-meta z-attribute z-rust">cfg_attr</span><span class="z-punctuation">(</span><span class="z-meta z-attribute z-rust">bevy_lint</span><span class="z-punctuation">,</span><span class="z-meta z-attribute z-rust"> warn</span><span class="z-punctuation">(</span><span class="z-meta z-attribute z-rust">bevy</span><span class="z-keyword z-operator">::</span><span class="z-meta z-attribute z-rust">pedantic</span><span class="z-punctuation">)</span><span class="z-punctuation">)</span><span class="z-punctuation">)</span><span class="z-punctuation">]</span></span></code></pre>
<p>In v0.1.0, the only way to toggle lints was to write the above in your crate root (<code>lib.rs</code> or <code>main.rs</code>). This was clearly a lot of boilerplate, so in <a rel="external" href="https://github.com/TheBevyFlock/bevy_cli/pull/251">#251</a> I added support for configuring lints in <code>Cargo.toml</code>:</p>
<pre class="giallo z-code"><code data-lang="toml"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Much nicer! :)</span></span>
<span class="giallo-l"><span class="z-punctuation">[</span><span class="z-source">package</span><span class="z-source">.</span><span class="z-source">metadata</span><span class="z-source">.</span><span class="z-source">bevy_lint</span><span class="z-punctuation">]</span></span>
<span class="giallo-l"><span class="z-source">pedantic</span><span class="z-punctuation z-separator z-key-value"> =</span><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">warn</span><span class="z-punctuation z-definition z-string">"</span></span></code></pre>
<p>This feature was heavily inspired by Cargo's builtin <a rel="external" href="https://doc.rust-lang.org/cargo/reference/manifest.html#the-lints-section"><code>[lints]</code> section</a>, which lets you configure Rust and Clippy's lints from <code>Cargo.toml</code>. I initially wanted to support this table instead of using <code>[package.metadata]</code>, but Cargo emits a warning that cannot be silenced when you add <code>[lints.bevy]</code> to <code>Cargo.toml</code>:</p>
<pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>warning: /path/to/Cargo.toml: unrecognized lint tool `lints.bevy`, specifying unrecognized tools may break in the future.</span></span>
<span class="giallo-l"><span>supported tools: cargo, clippy, rust, rustdoc</span></span></code></pre>
<p>On the positive side, however, using <code>[package.metadata]</code> means <code>bevy_lint</code> has direct control over how lints are applied. I took advantage of this by adding support for merging workspace-level lints with crate-level lints (a feature that Cargo does not natively support yet):</p>
<pre class="giallo z-code"><code data-lang="toml"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> This will be applied to all crates in the workspace.</span></span>
<span class="giallo-l"><span class="z-punctuation">[</span><span class="z-source">workspace</span><span class="z-source">.</span><span class="z-source">metadata</span><span class="z-source">.</span><span class="z-source">bevy_lint</span><span class="z-punctuation">]</span></span>
<span class="giallo-l"><span class="z-source">pedantic</span><span class="z-punctuation z-separator z-key-value"> =</span><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">warn</span><span class="z-punctuation z-definition z-string">"</span></span>
<span class="giallo-l"><span class="z-source">panicking_methods</span><span class="z-punctuation z-separator z-key-value"> =</span><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">deny</span><span class="z-punctuation z-definition z-string">"</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation">[</span><span class="z-source">package</span><span class="z-source">.</span><span class="z-source">metadata</span><span class="z-source">.</span><span class="z-source">bevy_lint</span><span class="z-punctuation">]</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> This enables an extra lint just for this crate.</span></span>
<span class="giallo-l"><span class="z-source">insert_unit_bundle</span><span class="z-punctuation z-separator z-key-value"> =</span><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">forbid</span><span class="z-punctuation z-definition z-string">"</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> This overrides the workspace lint level.</span></span>
<span class="giallo-l"><span class="z-source">panicking_methods</span><span class="z-punctuation z-separator z-key-value"> =</span><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">allow</span><span class="z-punctuation z-definition z-string">"</span></span></code></pre><h2 id="bevy-0-15-support">Bevy 0.15 Support<a class="zola-anchor" href="#bevy-0-15-support" aria-label="Anchor link for: bevy-0-15-support" style="visibility: hidden;"></a>
</h2>
<p>As of <a rel="external" href="https://github.com/TheBevyFlock/bevy_cli/pull/191">#191</a>, the linter now officially supports <a rel="external" href="https://bevyengine.org/news/bevy-0-15/">Bevy 0.15</a><sup class="footnote-reference" id="fr-2-1"><a href="#fn-2">2</a></sup>. Unfortunately, that also means dropping support for Bevy 0.14. There are plans to eventually <a rel="external" href="https://github.com/TheBevyFlock/bevy_cli/issues/138">support multiple versions</a>, but as of right now we can only support one.</p>
<h2 id="many-new-lints">Many New Lints<a class="zola-anchor" href="#many-new-lints" aria-label="Anchor link for: many-new-lints" style="visibility: hidden;"></a>
</h2>
<p><code>bevy_lint</code> has three new lints! (All of which were implemented by outside contributors. Thank you!)</p>
<h3 id="borrowed-reborrowable"><code>borrowed_reborrowable</code><a class="zola-anchor" href="#borrowed-reborrowable" aria-label="Anchor link for: borrowed-reborrowable" style="visibility: hidden;"></a>
</h3>
<p>First, <code>borrowed_reborrowable</code> warns against creating references to types that themselves are actually references, such as <code>Commands</code> and <code>Mut</code>. Instead, it recommends you use the convenient <code>reborrow()</code> method that many structures provide, which lets you convert <code>&mut T</code> into <code>T</code> for re-borrowable types:</p>
<pre class="giallo z-code"><code data-lang="rust"><span class="giallo-l"><span class="z-keyword">fn</span><span class="z-entity z-name z-function"> system</span><span class="z-punctuation">(</span><span class="z-storage z-modifier">mut</span><span class="z-variable z-other z-rust"> commands</span><span class="z-keyword z-operator">:</span><span class="z-entity z-name z-type"> Commands</span><span class="z-punctuation">)</span><span class="z-punctuation"> {</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> `Commands` internally contains an `&mut T` already, so creating a reference results in</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> `&mut &mut T`:</span></span>
<span class="giallo-l"><span class="z-entity z-name z-function"> helper_function</span><span class="z-punctuation">(</span><span class="z-keyword z-operator">&</span><span class="z-storage z-modifier">mut</span><span class="z-variable z-other z-rust"> commands</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"><span class="z-punctuation">}</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-keyword">fn</span><span class="z-entity z-name z-function"> helper_function</span><span class="z-punctuation">(</span><span class="z-variable z-other z-rust">commands</span><span class="z-keyword z-operator">:</span><span class="z-keyword z-operator"> &</span><span class="z-storage z-modifier">mut</span><span class="z-entity z-name z-type"> Commands</span><span class="z-punctuation">)</span><span class="z-punctuation"> {</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> ...</span></span>
<span class="giallo-l"><span class="z-punctuation">}</span></span></code></pre>
<p>Use instead:</p>
<pre class="giallo z-code"><code data-lang="rust"><span class="giallo-l"><span class="z-keyword">fn</span><span class="z-entity z-name z-function"> system</span><span class="z-punctuation">(</span><span class="z-storage z-modifier">mut</span><span class="z-variable z-other z-rust"> commands</span><span class="z-keyword z-operator">:</span><span class="z-entity z-name z-type"> Commands</span><span class="z-punctuation">)</span><span class="z-punctuation"> {</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Convert `&mut Commands` to `Commands`.</span></span>
<span class="giallo-l"><span class="z-entity z-name z-function"> helper_function</span><span class="z-punctuation">(</span><span class="z-variable z-other z-rust">commands</span><span class="z-keyword z-operator">.</span><span class="z-entity z-name z-function">reborrow</span><span class="z-punctuation">(</span><span class="z-punctuation">)</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"><span class="z-punctuation">}</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-keyword">fn</span><span class="z-entity z-name z-function"> helper_function</span><span class="z-punctuation">(</span><span class="z-storage z-modifier">mut</span><span class="z-variable z-other z-rust"> commands</span><span class="z-keyword z-operator">:</span><span class="z-entity z-name z-type"> Commands</span><span class="z-punctuation">)</span><span class="z-punctuation"> {</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> ...</span></span>
<span class="giallo-l"><span class="z-punctuation">}</span></span></code></pre><h3 id="insert-unit-bundle"><code>insert_unit_bundle</code><a class="zola-anchor" href="#insert-unit-bundle" aria-label="Anchor link for: insert-unit-bundle" style="visibility: hidden;"></a>
</h3>
<p>Second, <code>insert_unit_bundle</code> warns against spawning a <a rel="external" href="https://doc.rust-lang.org/stable/std/primitive.unit.html">unit <code>()</code></a>. Even though <code>()</code> is <a rel="external" href="https://docs.rs/bevy/0.15.3/bevy/ecs/bundle/trait.Bundle.html#impl-Bundle-for-()">technically a bundle</a>, trying to spawn it does nothing. (<code>commands.spawn(())</code> is equivalent to <code>commands.spawn_empty()</code>, although the latter is more efficient.) In practice, this lint catches occurrences where you assume a function returns a component that you can spawn, when in reality it just returns a unit <code>()</code>:</p>
<pre class="giallo z-code"><code data-lang="rust"><span class="giallo-l"><span class="z-keyword">fn</span><span class="z-entity z-name z-function"> spawn</span><span class="z-punctuation">(</span><span class="z-storage z-modifier">mut</span><span class="z-variable z-other z-rust"> commands</span><span class="z-keyword z-operator">:</span><span class="z-entity z-name z-type"> Commands</span><span class="z-punctuation">)</span><span class="z-punctuation"> {</span></span>
<span class="giallo-l"><span class="z-source"> commands</span><span class="z-keyword z-operator">.</span><span class="z-entity z-name z-function">spawn</span><span class="z-punctuation">(</span><span class="z-punctuation">(</span><span class="z-punctuation">)</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-source"> commands</span><span class="z-keyword z-operator">.</span><span class="z-entity z-name z-function">spawn</span><span class="z-punctuation">(</span><span class="z-punctuation">(</span></span>
<span class="giallo-l"><span class="z-entity z-name z-namespace"> Name</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-function">new</span><span class="z-punctuation">(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">Decal</span><span class="z-punctuation z-definition z-string">"</span><span class="z-punctuation">)</span><span class="z-punctuation">,</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> This is likely a mistake! `Transform::rotate_z()` returns a unit `()`, not a</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> `Transform`! As such, no `Transform` will be inserted into the entity.</span></span>
<span class="giallo-l"><span class="z-entity z-name z-namespace"> Transform</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-function">from_translation</span><span class="z-punctuation">(</span><span class="z-entity z-name z-namespace">Vec3</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-function">new</span><span class="z-punctuation">(</span><span class="z-constant z-numeric">0</span><span class="z-punctuation">.</span><span class="z-constant z-numeric">75</span><span class="z-punctuation">,</span><span class="z-constant z-numeric"> 0</span><span class="z-punctuation">.</span><span class="z-constant z-numeric">0</span><span class="z-punctuation">,</span><span class="z-constant z-numeric"> 0</span><span class="z-punctuation">.</span><span class="z-constant z-numeric">0</span><span class="z-punctuation">)</span><span class="z-punctuation">)</span></span>
<span class="giallo-l"><span class="z-keyword z-operator"> .</span><span class="z-entity z-name z-function">rotate_z</span><span class="z-punctuation">(</span><span class="z-constant z-other z-caps z-rust">PI</span><span class="z-keyword z-operator"> /</span><span class="z-constant z-numeric"> 4</span><span class="z-punctuation">.</span><span class="z-constant z-numeric">0</span><span class="z-punctuation">)</span><span class="z-punctuation">,</span></span>
<span class="giallo-l"><span class="z-punctuation"> )</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"><span class="z-punctuation">}</span></span></code></pre>
<p>Use instead:</p>
<pre class="giallo z-code"><code data-lang="rust"><span class="giallo-l"><span class="z-keyword">fn</span><span class="z-entity z-name z-function"> spawn</span><span class="z-punctuation">(</span><span class="z-storage z-modifier">mut</span><span class="z-variable z-other z-rust"> commands</span><span class="z-keyword z-operator">:</span><span class="z-entity z-name z-type"> Commands</span><span class="z-punctuation">)</span><span class="z-punctuation"> {</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> `Commands::spawn_empty()` is preferred if you do not need any components.</span></span>
<span class="giallo-l"><span class="z-source"> commands</span><span class="z-keyword z-operator">.</span><span class="z-entity z-name z-function">spawn_empty</span><span class="z-punctuation">(</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-source"> commands</span><span class="z-keyword z-operator">.</span><span class="z-entity z-name z-function">spawn</span><span class="z-punctuation">(</span><span class="z-punctuation">(</span></span>
<span class="giallo-l"><span class="z-entity z-name z-namespace"> Name</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-function">new</span><span class="z-punctuation">(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">Decal</span><span class="z-punctuation z-definition z-string">"</span><span class="z-punctuation">)</span><span class="z-punctuation">,</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> `Transform::with_rotation()` returns a `Transform`, which was likely the intended</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> behavior.</span></span>
<span class="giallo-l"><span class="z-entity z-name z-namespace"> Transform</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-function">from_translation</span><span class="z-punctuation">(</span><span class="z-entity z-name z-namespace">Vec3</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-function">new</span><span class="z-punctuation">(</span><span class="z-constant z-numeric">0</span><span class="z-punctuation">.</span><span class="z-constant z-numeric">75</span><span class="z-punctuation">,</span><span class="z-constant z-numeric"> 0</span><span class="z-punctuation">.</span><span class="z-constant z-numeric">0</span><span class="z-punctuation">,</span><span class="z-constant z-numeric"> 0</span><span class="z-punctuation">.</span><span class="z-constant z-numeric">0</span><span class="z-punctuation">)</span><span class="z-punctuation">)</span></span>
<span class="giallo-l"><span class="z-keyword z-operator"> .</span><span class="z-entity z-name z-function">with_rotation</span><span class="z-punctuation">(</span><span class="z-entity z-name z-namespace">Quat</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-function">from_rotation_z</span><span class="z-punctuation">(</span><span class="z-constant z-other z-caps z-rust">PI</span><span class="z-keyword z-operator"> /</span><span class="z-constant z-numeric"> 4</span><span class="z-punctuation">.</span><span class="z-constant z-numeric">0</span><span class="z-punctuation">)</span><span class="z-punctuation">)</span><span class="z-punctuation">,</span></span>
<span class="giallo-l"><span class="z-punctuation"> )</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"><span class="z-punctuation">}</span></span></code></pre><h3 id="duplicate-bevy-dependencies"><code>duplicate_bevy_dependencies</code><a class="zola-anchor" href="#duplicate-bevy-dependencies" aria-label="Anchor link for: duplicate-bevy-dependencies" style="visibility: hidden;"></a>
</h3>
<p>Finally, <code>duplicate_bevy_dependencies</code> checks if you're depending on multiple versions of Bevy in the same crate. Since <a rel="external" href="https://doc.rust-lang.org/cargo/reference/resolver.html#semver-compatibility">Cargo lets projects use several major versions of the same crate</a>, it is really easy to accidentally pull in more than one version of <code>bevy</code>. A common example of this is when your project depends on a 3rd-party plugin that uses an older version of Bevy:</p>
<pre class="giallo z-code"><code data-lang="toml"><span class="giallo-l"><span class="z-punctuation">[</span><span class="z-source">dependencies</span><span class="z-punctuation">]</span></span>
<span class="giallo-l"><span class="z-source">bevy</span><span class="z-punctuation z-separator z-key-value"> =</span><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">0.15</span><span class="z-punctuation z-definition z-string">"</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> This version of `leafwing-input-manager` actually requires Bevy 0.14!</span></span>
<span class="giallo-l"><span class="z-source">leafwing-input-manager</span><span class="z-punctuation z-separator z-key-value"> =</span><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">0.15</span><span class="z-punctuation z-definition z-string">"</span></span></code></pre>
<p>While at first using the above dependencies will appear as if nothing is wrong, trying to mix <code>leafwing-input-manager</code>'s types with a newer version of Bevy will result in an error:</p>
<pre class="giallo z-code"><code data-lang="rust"><span class="giallo-l"><span class="z-keyword">use</span><span class="z-entity z-name z-namespace"> bevy</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-namespace">prelude</span><span class="z-keyword z-operator">::</span><span class="z-keyword z-operator">*</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"><span class="z-keyword">use</span><span class="z-entity z-name z-namespace"> leafwing_input_manager</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-namespace">plugin</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-type">AccumulatorPlugin</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-keyword">fn</span><span class="z-entity z-name z-function"> main</span><span class="z-punctuation">(</span><span class="z-punctuation">)</span><span class="z-punctuation"> {</span></span>
<span class="giallo-l"><span class="z-entity z-name z-type"> App</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-function">new</span><span class="z-punctuation">(</span><span class="z-punctuation">)</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Error: `AccumulatorPlugin` does not implement `Plugin`!</span></span>
<span class="giallo-l"><span class="z-keyword z-operator"> .</span><span class="z-entity z-name z-function">add_plugins</span><span class="z-punctuation">(</span><span class="z-entity z-name z-type">AccumulatorPlugin</span><span class="z-punctuation">)</span></span>
<span class="giallo-l"><span class="z-keyword z-operator"> .</span><span class="z-entity z-name z-function">run</span><span class="z-punctuation">(</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"><span class="z-punctuation">}</span></span></code></pre>
<p>Developers who first run into this error likely think: "That doesn't make since! <code>AccumulatorPlugin</code> is definitely a <code>Plugin</code>!" While that may be true, <code>AccumularPlugin</code> only implements Bevy 0.14's <code>Plugin</code> trait, not Bevy 0.15's <code>Plugin</code> trait, which was expected. The Rust compiler treats those two traits as distinct, which is why it raised an error.</p>
<details >
<summary><span>See a real life example of this error...</span></summary>
<pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-entity z-name z-function">$</span><span class="z-string"> cargo</span><span class="z-string"> check</span></span>
<span class="giallo-l"><span class="z-entity z-name z-function">error[E0277]:</span><span class="z-string"> the</span><span class="z-string"> trait</span><span class="z-string"> bound</span><span class="z-punctuation z-definition z-evaluation z-backticks z-shell"> `</span><span class="z-entity z-name z-function">AccumulatorPlugin:</span><span class="z-string"> Plugins</span><span class="z-keyword z-operator"><</span><span class="z-string">_</span><span class="z-keyword z-operator">></span><span class="z-punctuation z-definition z-evaluation z-backticks z-shell">`</span><span class="z-entity z-name z-function"> is</span><span class="z-string"> not</span><span class="z-string"> satisfied</span></span>
<span class="giallo-l"><span class="z-entity z-name z-function"> --</span><span class="z-source">></span><span class="z-string"> src/main.rs:6:22</span></span>
<span class="giallo-l"><span class="z-keyword z-operator"> |</span></span>
<span class="giallo-l"><span class="z-entity z-name z-function">6</span><span class="z-keyword z-operator"> |</span><span class="z-entity z-name z-function"> .add_plugins(AccumulatorPlugin</span><span class="z-source">)</span></span>
<span class="giallo-l"><span class="z-keyword z-operator"> |</span><span class="z-entity z-name z-function"> -----------</span><span class="z-string"> ^^^^^^^^^^^^^^^^^</span><span class="z-string"> the</span><span class="z-string"> trait</span><span class="z-punctuation z-definition z-evaluation z-backticks z-shell"> `</span><span class="z-entity z-name z-function">app::plugin::sealed::Plugins</span><span class="z-string"><_></span><span class="z-punctuation z-definition z-evaluation z-backticks z-shell">`</span><span class="z-entity z-name z-function"> is</span><span class="z-string"> not</span><span class="z-string"> implemented</span><span class="z-string"> for</span><span class="z-punctuation z-definition z-evaluation z-backticks z-shell"> `</span><span class="z-entity z-name z-function">AccumulatorPlugin</span><span class="z-punctuation z-definition z-evaluation z-backticks z-shell">`</span></span>
<span class="giallo-l"><span class="z-keyword z-operator"> |</span><span class="z-keyword z-operator"> |</span></span>
<span class="giallo-l"><span class="z-keyword z-operator"> |</span><span class="z-entity z-name z-function"> required</span><span class="z-string"> by</span><span class="z-string"> a</span><span class="z-string"> bound</span><span class="z-string"> introduced</span><span class="z-string"> by</span><span class="z-string"> this</span><span class="z-string"> call</span></span>
<span class="giallo-l"><span class="z-keyword z-operator"> |</span></span>
<span class="giallo-l"><span class="z-entity z-name z-function">note:</span><span class="z-string"> there</span><span class="z-string"> are</span><span class="z-string"> multiple</span><span class="z-string"> different</span><span class="z-string"> versions</span><span class="z-string"> of</span><span class="z-string"> crate</span><span class="z-punctuation z-definition z-evaluation z-backticks z-shell"> `</span><span class="z-entity z-name z-function">bevy_app</span><span class="z-punctuation z-definition z-evaluation z-backticks z-shell">`</span><span class="z-source"> in the dependency graph</span></span>
<span class="giallo-l"><span class="z-entity z-name z-function"> --</span><span class="z-source">></span><span class="z-string"> ~/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/bevy_app-0.15.3/src/plugin.rs:136:5</span></span>
<span class="giallo-l"><span class="z-keyword z-operator"> |</span></span>
<span class="giallo-l"><span class="z-entity z-name z-function">136</span><span class="z-keyword z-operator"> |</span><span class="z-entity z-name z-function"> pub</span><span class="z-string"> trait</span><span class="z-string"> Plugins</span><span class="z-keyword z-operator"><</span><span class="z-string">Marke</span><span class="z-source">r</span><span class="z-keyword z-operator">></span><span class="z-string"> {</span></span>
<span class="giallo-l"><span class="z-keyword z-operator"> |</span><span class="z-entity z-name z-function"> ^^^^^^^^^^^^^^^^^^^^^^^^^</span><span class="z-string"> this</span><span class="z-string"> is</span><span class="z-string"> the</span><span class="z-string"> required</span><span class="z-string"> trait</span></span>
<span class="giallo-l"><span class="z-keyword z-operator"> |</span></span>
<span class="giallo-l"><span class="z-support z-function z-builtin"> :</span><span class="z-support z-function z-builtin">:</span><span class="z-support z-function z-builtin">:</span><span class="z-string"> src/main.rs:1:5</span></span>
<span class="giallo-l"><span class="z-keyword z-operator"> |</span></span>
<span class="giallo-l"><span class="z-entity z-name z-function">1</span><span class="z-keyword z-operator"> |</span><span class="z-entity z-name z-function"> use</span><span class="z-string"> bevy::prelude::</span><span class="z-variable">*</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"><span class="z-keyword z-operator"> |</span><span class="z-entity z-name z-function"> ----</span><span class="z-string"> one</span><span class="z-string"> version</span><span class="z-string"> of</span><span class="z-string"> crate</span><span class="z-punctuation z-definition z-evaluation z-backticks z-shell"> `</span><span class="z-entity z-name z-function">bevy_app</span><span class="z-punctuation z-definition z-evaluation z-backticks z-shell">`</span><span class="z-entity z-name z-function"> used</span><span class="z-string"> here,</span><span class="z-string"> as</span><span class="z-string"> a</span><span class="z-string"> dependency</span><span class="z-string"> of</span><span class="z-string"> crate</span><span class="z-punctuation z-definition z-evaluation z-backticks z-shell"> `</span><span class="z-entity z-name z-function">bevy_internal</span><span class="z-punctuation z-definition z-evaluation z-backticks z-shell">`</span></span>
<span class="giallo-l"><span class="z-entity z-name z-function">2</span><span class="z-keyword z-operator"> |</span><span class="z-entity z-name z-function"> use</span><span class="z-string"> leafwing_input_manager::plugin::AccumulatorPlugin</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"><span class="z-keyword z-operator"> |</span><span class="z-entity z-name z-function"> ----------------------</span><span class="z-string"> one</span><span class="z-string"> version</span><span class="z-string"> of</span><span class="z-string"> crate</span><span class="z-punctuation z-definition z-evaluation z-backticks z-shell"> `</span><span class="z-entity z-name z-function">bevy_app</span><span class="z-punctuation z-definition z-evaluation z-backticks z-shell">`</span><span class="z-entity z-name z-function"> used</span><span class="z-string"> here,</span><span class="z-string"> as</span><span class="z-string"> a</span><span class="z-string"> dependency</span><span class="z-string"> of</span><span class="z-string"> crate</span><span class="z-punctuation z-definition z-evaluation z-backticks z-shell"> `</span><span class="z-entity z-name z-function">bevy_internal</span><span class="z-punctuation z-definition z-evaluation z-backticks z-shell">`</span></span>
<span class="giallo-l"><span class="z-keyword z-operator"> |</span></span>
<span class="giallo-l"><span class="z-support z-function z-builtin"> :</span><span class="z-support z-function z-builtin">:</span><span class="z-support z-function z-builtin">:</span><span class="z-string"> ~/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/leafwing-input-manager-0.15.1/src/plugin.rs:320:1</span></span>
<span class="giallo-l"><span class="z-keyword z-operator"> |</span></span>
<span class="giallo-l"><span class="z-entity z-name z-function">320</span><span class="z-keyword z-operator"> |</span><span class="z-entity z-name z-function"> pub</span><span class="z-string"> struct</span><span class="z-string"> AccumulatorPlugin</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"><span class="z-keyword z-operator"> |</span><span class="z-entity z-name z-function"> ----------------------------</span><span class="z-string"> this</span><span class="z-string"> type</span><span class="z-string"> doesn</span><span class="z-punctuation z-definition z-string">'</span><span class="z-string">t implement the required trait</span></span>
<span class="giallo-l"><span class="z-string"> |</span></span>
<span class="giallo-l"><span class="z-string"> ::: ~/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/bevy_app-0.14.2/src/app.rs:26:1</span></span>
<span class="giallo-l"><span class="z-string"> |</span></span>
<span class="giallo-l"><span class="z-string">26 | / bevy_ecs::define_label!(</span></span>
<span class="giallo-l"><span class="z-string">27 | | /// A strongly-typed class of labels used to identify an [`App`].</span></span>
<span class="giallo-l"><span class="z-string">28 | | AppLabel,</span></span>
<span class="giallo-l"><span class="z-string">29 | | APP_LABEL_INTERNER</span></span>
<span class="giallo-l"><span class="z-string">30 | | );</span></span>
<span class="giallo-l"><span class="z-string"> | |_- this is the found trait</span></span>
<span class="giallo-l"><span class="z-string"> = help: you can use `cargo tree` to explore your dependency tree</span></span>
<span class="giallo-l"><span class="z-string"> = note: required for `AccumulatorPlugin` to implement `Plugins<_>`</span></span>
<span class="giallo-l"><span class="z-string">note: required by a bound in `bevy::prelude::App::add_plugins`</span></span>
<span class="giallo-l"><span class="z-string"> --> ~/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/bevy_app-0.15.3/src/app.rs:548:52</span></span>
<span class="giallo-l"><span class="z-string"> |</span></span>
<span class="giallo-l"><span class="z-string">548 | pub fn add_plugins<M>(&mut self, plugins: impl Plugins<M>) -> &mut Self {</span></span>
<span class="giallo-l"><span class="z-string"> | ^^^^^^^^^^ required by this bound in `App::add_plugins`</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-string">For more information about this error, try `rustc --explain E0277`.</span></span></code></pre>
</details>
<p>To fix this, you can update your dependencies to all use the same version of Bevy. Many 3rd-party plugins provide a "compatibility table" that makes it easy to reference which plugins versions work with which Bevy versions:</p>
<pre class="giallo z-code"><code data-lang="toml"><span class="giallo-l"><span class="z-punctuation">[</span><span class="z-source">dependencies</span><span class="z-punctuation">]</span></span>
<span class="giallo-l"><span class="z-source">bevy</span><span class="z-punctuation z-separator z-key-value"> =</span><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">0.15</span><span class="z-punctuation z-definition z-string">"</span></span>
<span class="giallo-l"><span class="z-source">leafwing-input-manager</span><span class="z-punctuation z-separator z-key-value"> =</span><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">0.16</span><span class="z-punctuation z-definition z-string">"</span></span></code></pre><h2 id="fixed-bevy-lint-on-windows">Fixed <code>bevy_lint</code> on Windows<a class="zola-anchor" href="#fixed-bevy-lint-on-windows" aria-label="Anchor link for: fixed-bevy-lint-on-windows" style="visibility: hidden;"></a>
</h2>
<p>As you may know, the linter requires <a rel="external" href="https://rustup.rs/">Rustup</a> to be installed in order to function. Internally, <a rel="external" href="https://github.com/TheBevyFlock/bevy_cli/blob/61954e35d2cb56beae53325afaaacd21647b7b55/bevy_lint/src/bin/main.rs#L24-L37">it was calling the following command</a> to make Cargo check over projects with <code>bevy_lint</code>:</p>
<pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-entity z-name z-function">$</span><span class="z-string"> export</span><span class="z-string"> RUSTC_WORKSPACE_WRAPPER=path/to/bevy_lint_driver</span></span>
<span class="giallo-l"><span class="z-entity z-name z-function">$</span><span class="z-string"> rustup</span><span class="z-string"> run</span><span class="z-string"> nightly-2025-02-20</span><span class="z-string"> cargo</span><span class="z-string"> check</span></span></code></pre>
<p><code>rustup run</code> is great because it handles setting the <code>PATH</code> and <code>LD_LIBRARY_PATH</code> variables for us. These environmental variables are crucial in helping <code>bevy_lint_driver</code> discover <code>librustc_driver.so</code>, the dynamic library that the linter uses to interface with the compiler.</p>
<p>As I daily drive both Linux and MacOS, I made sure to test the linter on those platforms to ensure it worked correctly. Unfortunately I didn't test it on Windows, as I just assumed that it would work the same!</p>
<p><em>It did not work the same.</em><sup class="footnote-reference" id="fr-3-1"><a href="#fn-3">3</a></sup></p>
<p>When trying to call <code>bevy_lint</code> v0.1.0 on Windows, it raises the following error:</p>
<pre class="giallo z-code"><code data-lang="powershell"><span class="giallo-l"><span class="z-keyword z-operator">></span><span class="z-source"> bevy_lint</span></span>
<span class="giallo-l"><span class="z-source">error: </span><span class="z-keyword">process</span><span class="z-source"> didn</span><span class="z-punctuation z-definition z-string">'</span><span class="z-string">t exit successfully: `\\?\C:\Users\USER\.cargo\bin\bevy_lint_driver.exe C:\Users\USER\.rustup\toolchains\nightly-2024-11-14-aarch64-pc-windows-msvc\bin\rustc.exe -vV` (exit code: 0xc0000135, STATUS_DLL_NOT_FOUND)</span></span>
<span class="giallo-l"><span class="z-string">Check failed: exit code: 101.</span></span></code></pre>
<p>The error says <code>STATUS_DLL_NOT_FOUND</code>; somehow <code>bevy_lint_driver</code> wasn't able to find <code>rustc_driver.dll</code>. It took quite some time and a bit of digging for me to discover the issue, but I eventually stumbled upon <a rel="external" href="https://internals.rust-lang.org/t/help-test-windows-behavior-between-rustup-and-cargo/20237">this forum post</a>. Turns out <code>rustup run</code> <em>does not</em> modify the <code>PATH</code> variable by default on Windows, since it breaks <a rel="external" href="https://rust-lang.github.io/rustup/concepts/proxies.html">proxies</a>.</p>
<p>Thankfully, there is a quick fix: setting <code>RUSTUP_WINDOWS_PATH_ADD_BIN=1</code> forces Rustup to modify the <code>PATH</code>:</p>
<pre class="giallo z-code"><code data-lang="powershell"><span class="giallo-l"><span class="z-keyword z-operator">></span><span class="z-source"> set RUSTUP_WINDOWS_PATH_ADD_BIN</span><span class="z-keyword z-operator">=</span><span class="z-constant z-numeric">1</span></span>
<span class="giallo-l"><span class="z-keyword z-operator">></span><span class="z-source"> bevy_lint</span></span>
<span class="giallo-l"><span class="z-source"> Finished </span><span class="z-keyword z-operator">`</span><span class="z-source">dev</span><span class="z-keyword z-operator">`</span><span class="z-source"> profile </span><span class="z-punctuation">[</span><span class="z-storage z-type">unoptimized</span><span class="z-keyword z-operator"> +</span><span class="z-storage z-type"> debuginfo</span><span class="z-punctuation">]</span><span class="z-source"> target</span><span class="z-punctuation">(</span><span class="z-source">s</span><span class="z-punctuation">)</span><span class="z-keyword"> in</span><span class="z-constant z-numeric"> 3.</span><span class="z-source">42s</span></span></code></pre>
<p>This is now automatically set in v0.2.0, so Windows should now work without any extra steps. Nice!</p>
<h2 id="conclusion">Conclusion<a class="zola-anchor" href="#conclusion" aria-label="Anchor link for: conclusion" style="visibility: hidden;"></a>
</h2>
<p>There are several other changes that I have not covered, but I highly recommend reading them in <a rel="external" href="https://github.com/TheBevyFlock/bevy_cli/blob/main/bevy_lint/CHANGELOG.md">the changelog</a>. I also recommend looking at <a rel="external" href="https://github.com/TheBevyFlock/bevy_cli/blob/main/bevy_lint/MIGRATION.md">the migration guide</a> if you used to use v0.1.0 and are planning on upgrading.</p>
<p>I would also like to thank several contributors who helped develop the v0.2.0 release of the linter:</p>
<ul>
<li><a rel="external" href="https://github.com/DaAlbrecht">DaAlbrecht</a>, who <a rel="external" href="https://github.com/TheBevyFlock/bevy_cli/pull/210">implemented <code>insert_unit_bundle</code></a>, added support for <a rel="external" href="https://github.com/TheBevyFlock/bevy_cli/pull/253">linting qualified methods</a>, merged <a rel="external" href="https://github.com/TheBevyFlock/bevy_cli/pull/271"><code>panicking_query_methods</code> and <code>panicking_world_methods</code></a>, reviewed several PRs, and helped many on Discord</li>
<li><a rel="external" href="https://github.com/TimJentzsch">TimJentzsch</a>, who has been hard at work building the linter's sibling project, the <a rel="external" href="https://github.com/TheBevyFlock/bevy_cli">Bevy CLI</a>. Tim has provided valuable feedback and is a consistent reviewer of PRs.</li>
<li><a rel="external" href="https://github.com/MrGVSV">MrGVSV</a>, who <a rel="external" href="https://github.com/TheBevyFlock/bevy_cli/pull/164">wrote the <code>borrowed_reborrowable</code></a> lint. (He's also the driving force behind <code>bevy_reflect</code>!)</li>
</ul>
<p>If you would like to try contributing yourself, please check out the <a rel="external" href="https://thebevyflock.github.io/bevy_cli/contribute/linter/index.html">Contributor's Guide</a>! We're super welcome to new contributors, and love any help we can get!</p>
<p>That's all for today. Thank you for your time!</p>
<p>- BD103 :)</p>
<style>
/* Clear the gradient background, make it bright yellow instead, and make the text black. 😎 */
body.bright {
background-color: yellow !important;
color: black !important;
}
/* Make all text fully uppercase. (If you're going to yell at me, I'll yell back!) */
body.loud {
text-transform: uppercase !important;
}
</style>
<script>
document.getElementById("adjective").addEventListener("change", (event) => {
const adjective = event.currentTarget.value;
document.body.classList.toggle("bright", adjective === "bright");
document.body.classList.toggle("loud", adjective === "questionably loud");
});
</script>
<section class="footnotes">
<ol class="footnotes-list">
<li id="fn-1">
<p>Oh wow, has it actually been 6 months? I feel like I just wrote <a href="https://bd103.dev/blog/2024-08-18-4-years-of-bevy/">4 Years of Bevy</a> yesterday! <a href="#fr-1-1">↩</a></p>
</li>
<li id="fn-2">
<p>Which is somewhat funny, since the engine has already published the release candidates for Bevy 0.16! I guess we'll have to release v0.3.0 a bit faster next time, so we don't fall behind the rest of the ecosystem :) <a href="#fr-2-1">↩</a></p>
</li>
<li id="fn-3">
<p>Which, looking back, makes complete sense. Linux and MacOS are much more similar to each other than Windows, so if any of them were going to operate differently, it was going to be Windows. I hoped <code>rustup run</code> would hide any of these details so I wouldn't need to worry about it, but unfortunately that isn't the case. <a href="#fr-3-1">↩</a></p>
</li>
</ol>
</section>
4 Years of Bevy2024-08-18T00:00:00+00:002025-09-28T00:00:00+00:00
BD103
https://bd103.dev/blog/2024-08-18-4-years-of-bevy/<p>It's Bevy's 4th birthday! If you haven't already, read <a rel="external" href="https://bevyengine.org/news/bevys-fourth-birthday/">Cart's post here</a>. As part of this milestone, I would like to reflect on my journey in the Bevy developer community.</p>
<h2 id="wait-bevy">Wait... Bevy?!<a class="zola-anchor" href="#wait-bevy" aria-label="Anchor link for: wait-bevy" style="visibility: hidden;"></a>
</h2>
<p>Yeah! I contribute to <a rel="external" href="https://bevyengine.org">Bevy</a>, an open-source game engine written in <a rel="external" href="https://www.rust-lang.org/">Rust</a>. I'm a relatively new contributor, having started in November of 2023<sup class="footnote-reference" id="fr-0-1"><a href="#fn-0">1</a></sup>, but I've accomplished a lot since then. I was inspired after reading the <a rel="external" href="https://bevyengine.org/news/bevy-0-12/">0.12 announcement post</a>, so I found an issue labeled <code>D-Good-First-Issue</code> and tried my best to complete it!</p>
<p>The change was simple, the review process went well, and it was merged only a day later. I was really excited that I had the chance to contribute to this cool piece of software that I looked up to.</p>
<h2 id="finding-my-place-in-it-all">Finding my place in it all<a class="zola-anchor" href="#finding-my-place-in-it-all" aria-label="Anchor link for: finding-my-place-in-it-all" style="visibility: hidden;"></a>
</h2>
<p>It wasn't until December where I began working on the aspect of Bevy that I now specialize in: Github Actions. I modified the workflow that publishes <a rel="external" href="https://dev-docs.bevyengine.org">https://dev-docs.bevyengine.org</a> to upload an artifact instead of force-pushing to the <code>gh-pages</code> branch. It took a few attempts, but in the end its result was safer and <em>far less cursed</em>.</p>
<blockquote class="callout note has-title">
<p class="title">
<span class="icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="18" height="18"><path d="M12 22C6.47715 22 2 17.5228 2 12C2 6.47715 6.47715 2 12 2C17.5228 2 22 6.47715 22 12C22 17.5228 17.5228 22 12 22ZM12 20C16.4183 20 20 16.4183 20 12C20 7.58172 16.4183 4 12 4C7.58172 4 4 7.58172 4 12C4 16.4183 7.58172 20 12 20ZM11 7H13V9H11V7ZM11 11H13V17H11V11Z" fill="currentColor"></path></svg>
</span>
<strong>Note</strong>
</p>
<div class="content">
<p>Github Actions is a continuous integration platform used primarily to test and lint code. It lets you use Github-hosted runners for free for public projects, which I was all for! I setup a lot of CI for my previous hobby projects, so I was already familiar with it before entering the Bevy scene.</p>
</div>
</blockquote>
<p>The ranks of Bevy contributors are chock-full of ECS enthusiasts and rendering ninjas, but how many CI wizards are there? Not many<sup class="footnote-reference" id="fr-1-1"><a href="#fn-1">2</a></sup>, and so I found my role. I spent a lot of time improve the quality of the CI jobs and their associated <code>ci</code> tool.</p>
<h2 id="what-i-m-proud-of">What I'm proud of<a class="zola-anchor" href="#what-i-m-proud-of" aria-label="Anchor link for: what-i-m-proud-of" style="visibility: hidden;"></a>
</h2>
<p>Then again, I don't just hack around with YAML until <a rel="external" href="https://xkcd.com/722/">the rectangle of lights acts to my liking</a>. Of all the things I've done, I'm most proud of the following:</p>
<h3 id="bevy-bencher"><a rel="external" href="https://github.com/TheBevyFlock/bevy-bencher"><code>bevy-bencher</code></a><a class="zola-anchor" href="#bevy-bencher" aria-label="Anchor link for: bevy-bencher" style="visibility: hidden;"></a>
</h3>
<p>I wrote an automated system on Github Actions and <a rel="external" href="https://bencher.dev">https://bencher.dev</a> that runs daily benchmarks on Bevy's main branch. It can catch performance regressions, file size changes, and more. In the coming months I hope to:</p>
<ul>
<li>Expand on the benchmarks themselves: we aren't tracking enough critical functions!</li>
<li>Benchmark every commit, instead of just benchmarking daily.</li>
<li>Introduce the <a rel="external" href="https://github.com/iai-callgrind/iai-callgrind"><code>iai-callgrind</code></a> harness to track instruction count, not just wall time.<sup class="footnote-reference" id="fr-2-1"><a href="#fn-2">3</a></sup></li>
</ul>
<h3 id="flag-frenzy"><a rel="external" href="https://github.com/TheBevyFlock/flag-frenzy"><code>flag-frenzy</code></a><a class="zola-anchor" href="#flag-frenzy" aria-label="Anchor link for: flag-frenzy" style="visibility: hidden;"></a>
</h3>
<p><code>flag-frenzy</code> is a tool built to test combinations of Bevy's feature flags. Bevy <a rel="external" href="https://github.com/bevyengine/bevy/blob/423285cf1cbd86d85db066dbfe26de4fd68333d9/Cargo.toml#L57-L353">has a <em>lot</em> of features</a>, and it's really easy to write code that doesn't account for a specific combination. Though there are many popular tools that can test the combinatorial features explosions in Cargo projects, <code>flag-frenzy</code> stands out due to its:</p>
<ul>
<li><strong>Memory efficiency</strong>: <code>flag-frenzy</code> lazily computes combinations instead of doing it all at once, avoiding large<sup class="footnote-reference" id="fr-3-1"><a href="#fn-3">4</a></sup> memory requirements!</li>
<li><strong>Expressive feature configuration</strong>: <code>flag-frenzy</code> lets you specify advanced feature requirements using an expressive <a rel="external" href="https://github.com/TheBevyFlock/flag-frenzy/blob/ee347bb795b70494fa03809982d3af9b572b9796/docs/4-rules.md">TOML DSL</a>.</li>
<li><strong>Work chunking</strong>: Inspired by <code>cargo-all-features</code>, <code>flag-frenzy</code> lets you <a rel="external" href="https://github.com/TheBevyFlock/flag-frenzy/blob/ee347bb795b70494fa03809982d3af9b572b9796/docs/2-cli.md#dividing-up-work">split up work into chunks</a> that you can distribute across multiple machines.</li>
<li><strong>Colorful output</strong>: <code>flag-frenzy</code> outputs parsable information using ANSI terminal colors, and it summarizes information in a failure report at the end of the program.</li>
</ul>
<h3 id="0-14-migration-guide"><a rel="external" href="https://bevyengine.org/learn/migration-guides/0-13-to-0-14/">0.14 Migration Guide</a><a class="zola-anchor" href="#0-14-migration-guide" aria-label="Anchor link for: 0-14-migration-guide" style="visibility: hidden;"></a>
</h3>
<p>I wrote the majority of the migration guide for 0.13 to 0.14. I edited <a rel="external" href="https://github.com/bevyengine/bevy-website/tree/main/release-content/0.14/migration-guides">128 different entries</a> over the course of <a rel="external" href="https://github.com/bevyengine/bevy-website/issues/1396">16 pull requests</a>. It was a monumental effort that took over a month, but I am so happy with the final result.</p>
<p>I had a bit of burn-out after this (understandably so!), so I want to thank <a rel="external" href="https://github.com/TrialDragon">Trial</a> for reviewing and merging follow-up changes to the guide after I took a break. I've since recovered, so if you find an issue with the guide then feel free to ping me <a rel="external" href="https://github.com/BD103">on Github</a>!</p>
<h3 id="contributor-s-guide"><a rel="external" href="https://bevy.org/learn/contribute/introduction/">Contributor's Guide</a><a class="zola-anchor" href="#contributor-s-guide" aria-label="Anchor link for: contributor-s-guide" style="visibility: hidden;"></a>
</h3>
<p>I, along with <a rel="external" href="https://github.com/nthtensor">Nth</a> and a few others in the working group, have been writing and editing the (soon to be released) Contributor's Guide. Our hope is to consolidate development resources into a single source, improving the on-boarding experience for new contributors, and going into more depth than the existing resources.</p>
<p>At the time of writing, it's very close to being published! <a rel="external" href="https://github.com/alice-i-cecile">Alice</a> has been taking the reigns in getting the final changes merged, so all that's left is copy-editing and cleanup.</p>
<hr />
<p>I'm really proud of all the work I put into Bevy, even though it doesn't get much of the spotlight. The only time I got on the glorious release notes was to <a rel="external" href="https://bevyengine.org/news/bevy-0-14/#deprecate-dynamic-plugins">deprecate dynamic plugins</a>, but I don't mind. There are plenty of talented and wonderful people who deserve recognition just as much as me!</p>
<h2 id="a-thank-you-letter">A thank you letter<a class="zola-anchor" href="#a-thank-you-letter" aria-label="Anchor link for: a-thank-you-letter" style="visibility: hidden;"></a>
</h2>
<p>The Bevy community is truly a wonderful place to be. So many kind and welcoming people helped me, and I want to take some time to say thank you.</p>
<h3 id="alice"><a rel="external" href="https://github.com/alice-i-cecile">Alice</a><a class="zola-anchor" href="#alice" aria-label="Anchor link for: alice" style="visibility: hidden;"></a>
</h3>
<p>Alice, you are <em>hands down</em> the best maintainer I have ever worked with. You bring enthusiasm to your work every day and are a staple in the Bevy community. Whether it be a quick review, better wording in documentation, or even arcane Bevy lore, I know I can always reach out to you. Your merge train is a fun way to catch up with all the latest changes, and is something I look forward to each week.</p>
<p>Thank you for all that you do!</p>
<h3 id="francois"><a rel="external" href="https://github.com/mockersf">François</a><a class="zola-anchor" href="#francois" aria-label="Anchor link for: francois" style="visibility: hidden;"></a>
</h3>
<p>François, you don't get enough credit for the credit you deserve. Your infrastructure and behind-the-scenes work is inspirational, and is the reason you're the unofficial SME-CI. Pixel Eagle, the screenshot testing platform that you built from scratch, is incredibly useful. Not only does it catch bugs, but you also submit PRs that fix them too!</p>
<p>It's been a pleasure working alongside you.</p>
<h3 id="trial"><a rel="external" href="https://github.com/TrialDragon">Trial</a><a class="zola-anchor" href="#trial" aria-label="Anchor link for: trial" style="visibility: hidden;"></a>
</h3>
<p>Trial, you were one of the first people that I feel like I actually worked with on Bevy. I fondly remember us both working on the website over the span of 2 months, trading reviews and keeping the momentum going. Your expertise with Zola is unmatched, and you have a knowledge of the website's templates and macros that I envy.</p>
<p>Though you may not have realized how much it meant to me as a new contributor, thank you.</p>
<hr />
<p>In the end, 3 thank-you's cannot describe how grateful I am to this community. It takes a true village to keep a project this scale running, so an additional thank you is required to <a rel="external" href="https://github.com/cart">Cart</a>, <a rel="external" href="https://github.com/janhohenheim">Jan</a>, <a rel="external" href="https://github.com/icesentry">IceSentry</a>, <a rel="external" href="https://github.com/brezak">Brezak</a>, <a rel="external" href="https://github.com/Jondolf">Jondolf</a>, <a rel="external" href="https://github.com/viridia">Talin</a>, <a rel="external" href="https://github.com/ChristopherBiscardi">Chris</a>, <a rel="external" href="https://github.com/nisevoid">NiseVoid</a>, <a rel="external" href="https://github.com/tychedelia">Charlotte</a>, <a rel="external" href="https://github.com/pcwalton">pcwalton</a>, <a rel="external" href="https://github.com/MrGVSV">MrGVSV</a>, <a rel="external" href="https://github.com/SkiFire13">SkiFire</a>, <a rel="external" href="https://github.com/JMS55">Jasmine</a>, <a rel="external" href="https://github.com/james7132">James</a>, <a rel="external" href="https://github.com/rparrett">rparret</a>, <a rel="external" href="https://github.com/aevyrie">Aevyrie</a>, <a rel="external" href="https://github.com/maniwani">Joy</a>, <a rel="external" href="https://github.com/nthtensor">Nth</a>, and so many more! You all rock!</p>
<p>If you want to build something awesome with Rust or get into the game development scene, please consider contributing to Bevy! Check out <a rel="external" href="https://github.com/bevyengine/bevy/issues?q=is%3Aopen+is%3Aissue+-label%3AX-Controversial+label%3AD-Trivial%2CD-Straightforward">the issue tracker</a>, specifically issues labeled <code>D-Trivial</code> and <code>D-Straightforward</code>. They're how I and so many others got started, so I highly recommend it!</p>
<p>Bevy has been life-changing. I've met so many wonderful people, worked on so many fun things, and helped so many others to do the same. It's truly an era that I will look back on with joy and pride.</p>
<p>Chat with you on <a rel="external" href="https://discord.gg/bevy">Discord</a>,</p>
<p>~ BD103</p>
<section class="footnotes">
<ol class="footnotes-list">
<li id="fn-0">
<p>This is excluding the one time in September of 2022 where I opened <a rel="external" href="https://github.com/bevyengine/bevy/pull/5022">a PR</a> to Bevy that got closed due to immature plugin dependencies. <a href="#fr-0-1">↩</a></p>
</li>
<li id="fn-1">
<p>But not none! I can think of a few off of the top of my head, the most prominent being <a rel="external" href="https://github.com/mockersf">François</a>. <a href="#fr-1-1">↩</a></p>
</li>
<li id="fn-2">
<p>I used to daily-drive MacOS, which didn't support Valgrind, so I originally couldn't work on this. I've since built a PC that runs Linux, so there's nothing blocking me now! <a href="#fr-2-1">↩</a></p>
</li>
<li id="fn-3">
<p>I believe it is a factorial increase in memory usage, but I haven't done the math. Feel free to prove me wrong and I'll update this! <a href="#fr-3-1">↩</a></p>
</li>
</ol>
</section>
Rust Pointer Metadata2023-08-06T00:00:00+00:002023-08-06T00:00:00+00:00
BD103
https://bd103.dev/blog/2023-08-06-ptr-metadata/<h1 id="rust-pointer-metadata">Rust Pointer Metadata<a class="zola-anchor" href="#rust-pointer-metadata" aria-label="Anchor link for: rust-pointer-metadata" style="visibility: hidden;"></a>
</h1>
<p>Welcome back! In my <a href="https://bd103.dev/blog/2023-06-27-global-allocators/">last blog post</a> I talked about overriding the global allocator. It was reasonably successful, even getting mentioned in <a rel="external" href="https://rust-osdev.com/this-month/2023-06/">This Month in Rust OSDev</a> without me suggesting it! That success has inspired me to write about another really interesting feature in the <a rel="external" href="https://www.rust-lang.org/">Rust</a> programming language called pointer metadata.</p>
<blockquote class="callout caution has-title">
<p class="title">
<span class="icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="18" height="18"><path d="M4.00098 20V14C4.00098 9.58172 7.5827 6 12.001 6C16.4193 6 20.001 9.58172 20.001 14V20H21.001V22H3.00098V20H4.00098ZM6.00098 20H18.001V14C18.001 10.6863 15.3147 8 12.001 8C8.68727 8 6.00098 10.6863 6.00098 14V20ZM11.001 2H13.001V5H11.001V2ZM19.7792 4.80761L21.1934 6.22183L19.0721 8.34315L17.6578 6.92893L19.7792 4.80761ZM2.80859 6.22183L4.22281 4.80761L6.34413 6.92893L4.92991 8.34315L2.80859 6.22183ZM7.00098 14C7.00098 11.2386 9.23956 9 12.001 9V11C10.3441 11 9.00098 12.3431 9.00098 14H7.00098Z" fill="currentColor"></path></svg>
</span>
<strong>Caution</strong>
</p>
<div class="content">
<p>Some examples in this blog post use the unstable feature <a rel="external" href="https://github.com/rust-lang/rust/issues/81513"><code>ptr_metadata</code></a> with Nightly Rust. I have tested all of them with <code>rustc 1.72.0-nightly (101fa903b 2023-06-04)</code>, but it may fail to compile if you use a different version. For more information, please see <a rel="external" href="https://rust-lang.github.io/rustup/concepts/channels.html#working-with-nightly-rust">the Rustup documentation</a>.</p>
</div>
</blockquote>
<h2 id="what-is-a-pointer">What is a pointer?<a class="zola-anchor" href="#what-is-a-pointer" aria-label="Anchor link for: what-is-a-pointer" style="visibility: hidden;"></a>
</h2>
<p>A pointer is simply a number that points to a location in memory. There are two different types in Rust: <a rel="external" href="https://doc.rust-lang.org/std/primitive.reference.html">references</a> and <a rel="external" href="https://doc.rust-lang.org/std/primitive.pointer.html">raw pointers</a>. References uphold certain restrictions that prevent programmers from making common mistakes as seen in the C and C++ languages<sup class="footnote-reference" id="fr-0-1"><a href="#fn-0">1</a></sup>. Raw pointers have none of these restrictions, and thus require <a rel="external" href="https://doc.rust-lang.org/std/keyword.unsafe.html"><code>unsafe</code></a> to access the underlying memory.</p>
<p>After getting compiled, references and raw pointers are semantically equivalent and look the same. They are only treated differently by the compiler. From this point onward when I refer to a "pointer," I will be talking about both references and raw pointers.</p>
<h2 id="data-representation">Data Representation<a class="zola-anchor" href="#data-representation" aria-label="Anchor link for: data-representation" style="visibility: hidden;"></a>
</h2>
<p>All pointers are unsigned integers that represent a location in memory. (I fear the day where someone decides to represent them with floating point numbers.) The amount of bits they use is platform-dependent, but guaranteed to always be the same size as a <a rel="external" href="https://doc.rust-lang.org/std/primitive.usize.html"><code>usize</code></a>.</p>
<blockquote class="quote">
<div class="icon" style="display: none;"><svg fill="currentColor" xmlns="http://www.w3.org/2000/svg" width="10" height="10" viewBox="796 698 200 200">
<g>
<path d="M885.208,749.739v-40.948C836.019,708.791,796,748.81,796,798v89.209h89.208V798h-48.26
C836.948,771.39,858.598,749.739,885.208,749.739z"/>
<path d="M996,749.739v-40.948c-49.19,0-89.209,40.019-89.209,89.209v89.209H996V798h-48.26
C947.74,771.39,969.39,749.739,996,749.739z"/>
</g>
</svg>
</div>
<div class="content"><p>The pointer-sized unsigned integer type.</p>
</div>
<div class="from">
<p>— <a rel="external" href="https://doc.rust-lang.org/std/primitive.usize.html">Rust <code>usize</code> Documentation</a></p>
</div>
</blockquote>
<p>I use an Apple M1 CPU, which has a 64-bit architecture. This means that all <code>usize</code>s compiled on my computer will be 64 bits long. 64-bit pointers are the most common nowadays, but some older computers (specifically Windows ones) may use 32-bit pointers instead.</p>
<p>All that I've said so far about the data representation of pointers is mostly language-independent, but what comes next is Rust specific. Pointers in Rust can either one <code>usize</code> or <strong>two</strong> <code>usize</code>s. This means that any pointer can be twice the normal size, depending on the type of data it points to.</p>
<pre class="giallo z-code"><code data-lang="rust"><span class="giallo-l"><span class="z-keyword">use</span><span class="z-entity z-name z-namespace"> std</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-namespace">mem</span><span class="z-keyword z-operator">::</span><span class="z-source">size_of</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-keyword">fn</span><span class="z-entity z-name z-function"> main</span><span class="z-punctuation">(</span><span class="z-punctuation">)</span><span class="z-punctuation"> {</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> `usize` and pointers are the same size...</span></span>
<span class="giallo-l"><span class="z-entity z-name z-function z-macro z-rust"> assert_eq!</span><span class="z-punctuation">(</span><span class="z-entity z-name z-function">size_of</span><span class="z-keyword z-operator">::</span><span class="z-punctuation z-brackets z-angle z-rust"><</span><span class="z-entity z-name z-type z-numeric z-rust">usize</span><span class="z-punctuation z-brackets z-angle z-rust">></span><span class="z-punctuation">(</span><span class="z-punctuation">)</span><span class="z-punctuation">,</span><span class="z-entity z-name z-function"> size_of</span><span class="z-keyword z-operator">::</span><span class="z-punctuation z-brackets z-angle z-rust"><</span><span class="z-keyword z-operator">&</span><span class="z-entity z-name z-type">bool</span><span class="z-punctuation z-brackets z-angle z-rust">></span><span class="z-punctuation">(</span><span class="z-punctuation">)</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"><span class="z-entity z-name z-function z-macro z-rust"> assert_eq!</span><span class="z-punctuation">(</span><span class="z-entity z-name z-function">size_of</span><span class="z-keyword z-operator">::</span><span class="z-punctuation z-brackets z-angle z-rust"><</span><span class="z-entity z-name z-type z-numeric z-rust">usize</span><span class="z-punctuation z-brackets z-angle z-rust">></span><span class="z-punctuation">(</span><span class="z-punctuation">)</span><span class="z-punctuation">,</span><span class="z-entity z-name z-function"> size_of</span><span class="z-keyword z-operator">::</span><span class="z-punctuation z-brackets z-angle z-rust"><</span><span class="z-keyword z-operator">*</span><span class="z-storage z-modifier z-rust">const</span><span class="z-entity z-name z-type z-numeric z-rust"> u8</span><span class="z-punctuation z-brackets z-angle z-rust">></span><span class="z-punctuation">(</span><span class="z-punctuation">)</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> ...until they're not?!</span></span>
<span class="giallo-l"><span class="z-entity z-name z-function z-macro z-rust"> assert_ne!</span><span class="z-punctuation">(</span><span class="z-entity z-name z-function">size_of</span><span class="z-keyword z-operator">::</span><span class="z-punctuation z-brackets z-angle z-rust"><</span><span class="z-entity z-name z-type z-numeric z-rust">usize</span><span class="z-punctuation z-brackets z-angle z-rust">></span><span class="z-punctuation">(</span><span class="z-punctuation">)</span><span class="z-punctuation">,</span><span class="z-entity z-name z-function"> size_of</span><span class="z-keyword z-operator">::</span><span class="z-punctuation z-brackets z-angle z-rust"><</span><span class="z-keyword z-operator">&</span><span class="z-entity z-name z-type">str</span><span class="z-punctuation z-brackets z-angle z-rust">></span><span class="z-punctuation">(</span><span class="z-punctuation">)</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"><span class="z-punctuation">}</span></span></code></pre>
<p>In the above example, <code>&str</code> is not the size of a <code>usize</code>! On my machine where a <code>usize</code> is 8 bytes<sup class="footnote-reference" id="fr-1-1"><a href="#fn-1">2</a></sup>, the size of <code>&str</code> is 16 bytes. The reason behind this sudden increase is size is because of a special property called <em>pointer metadata</em>.</p>
<h2 id="intro-to-pointer-metadata">Intro to Pointer Metadata<a class="zola-anchor" href="#intro-to-pointer-metadata" aria-label="Anchor link for: intro-to-pointer-metadata" style="visibility: hidden;"></a>
</h2>
<p>Pointer metadata is an optional feature that allows pointers to store additional data about themselves. Where a normal pointer just stores its address, a pointer with metadata stores its address and an extra <code>usize</code> of information.</p>
<p>A brief terminology break: pointers with metadata are called <strong>fat pointers</strong>, while ones without are called <strong>thin pointers</strong>.</p>
<p>Due to their increase in size, Rust only uses fat pointers in places where it cannot infer certain information at compile time. The most popular, and currently only, use of pointer metadata is when combined with <em>dynamically sized types</em>.</p>
<h2 id="dsts">DSTs<a class="zola-anchor" href="#dsts" aria-label="Anchor link for: dsts" style="visibility: hidden;"></a>
</h2>
<p>Dynamically sized types, or DSTs, fit the requirements for pointer metadata perfectly. Their size is unknown to the compiler, so it delegates the size to be calculated and stored at runtime. Here is a list of commonly used DSTs:</p>
<ul>
<li><a rel="external" href="https://doc.rust-lang.org/std/primitive.slice.html">Slices <code>&[T]</code></a></li>
<li><a rel="external" href="https://doc.rust-lang.org/std/primitive.str.html">String slices <code>&str</code></a></li>
<li><a rel="external" href="https://doc.rust-lang.org/std/keyword.dyn.html">Trait objects <code>&dyn Trait</code></a></li>
<li>Structures that wrap the above DSTs<sup class="footnote-reference" id="fr-2-1"><a href="#fn-2">3</a></sup></li>
</ul>
<p>All DSTs are required to be used behind a pointer so that the compiler can embed the metadata necessary to actually use them.</p>
<pre class="giallo z-code"><code data-lang="rust"><span class="giallo-l"><span class="z-keyword">fn</span><span class="z-entity z-name z-function"> main</span><span class="z-punctuation">(</span><span class="z-punctuation">)</span><span class="z-punctuation"> {</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Has a known size to the compiler.</span></span>
<span class="giallo-l"><span class="z-storage z-type z-rust"> let</span><span class="z-source"> source</span><span class="z-keyword z-operator">:</span><span class="z-punctuation"> [</span><span class="z-entity z-name z-type z-numeric z-rust">u8</span><span class="z-punctuation">;</span><span class="z-constant z-numeric"> 5</span><span class="z-punctuation">]</span><span class="z-keyword z-operator"> =</span><span class="z-punctuation"> [</span><span class="z-constant z-numeric">2</span><span class="z-punctuation">,</span><span class="z-constant z-numeric"> 4</span><span class="z-punctuation">,</span><span class="z-constant z-numeric"> 8</span><span class="z-punctuation">,</span><span class="z-constant z-numeric"> 16</span><span class="z-punctuation">,</span><span class="z-constant z-numeric"> 32</span><span class="z-punctuation">]</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Has an unknown size to the compiler.</span></span>
<span class="giallo-l"><span class="z-storage z-type z-rust"> let</span><span class="z-source"> dst</span><span class="z-keyword z-operator">:</span><span class="z-keyword z-operator"> &</span><span class="z-punctuation">[</span><span class="z-entity z-name z-type z-numeric z-rust">u8</span><span class="z-punctuation">]</span><span class="z-keyword z-operator"> =</span><span class="z-keyword z-operator"> &</span><span class="z-source">source</span><span class="z-punctuation">[</span><span class="z-constant z-numeric">0</span><span class="z-keyword z-operator">..</span><span class="z-constant z-numeric">3</span><span class="z-punctuation">]</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> And yet we can somehow still find its size as runtime.</span></span>
<span class="giallo-l"><span class="z-entity z-name z-function z-macro z-rust"> assert_eq!</span><span class="z-punctuation">(</span><span class="z-source">dst</span><span class="z-keyword z-operator">.</span><span class="z-entity z-name z-function">len</span><span class="z-punctuation">(</span><span class="z-punctuation">)</span><span class="z-punctuation">,</span><span class="z-constant z-numeric"> 3</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"><span class="z-punctuation">}</span></span></code></pre>
<blockquote class="callout note has-title">
<p class="title">
<span class="icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="18" height="18"><path d="M12 22C6.47715 22 2 17.5228 2 12C2 6.47715 6.47715 2 12 2C17.5228 2 22 6.47715 22 12C22 17.5228 17.5228 22 12 22ZM12 20C16.4183 20 20 16.4183 20 12C20 7.58172 16.4183 4 12 4C7.58172 4 4 7.58172 4 12C4 16.4183 7.58172 20 12 20ZM11 7H13V9H11V7ZM11 11H13V17H11V11Z" fill="currentColor"></path></svg>
</span>
<strong>Note</strong>
</p>
<div class="content">
<p>You may argue that the compiler could infer that <code>dst</code> is 3 bytes, but imagine scenarios where this wouldn't be possible. A good one that I can think of is taking a <code>&[u8]</code> as a function argument. The function needs to work with any slice, no matter its size.</p>
</div>
</blockquote>
<h2 id="what-metadata-is-stored">What metadata is stored?<a class="zola-anchor" href="#what-metadata-is-stored" aria-label="Anchor link for: what-metadata-is-stored" style="visibility: hidden;"></a>
</h2>
<p>I've evaded this question long enough. What metadata is actually being stored in fat pointers to facilitate DSTs? This is type dependent, so here's a quick list:</p>
<ul>
<li>For slices, the metadata is a number describing the length.</li>
<li>For <code>str</code> slices, the metadata is a number describing the length, specifically in bytes.</li>
<li>For trait objects, the metadata is a pointer to a static VTable used in <a rel="external" href="https://en.wikipedia.org/wiki/Dynamic_dispatch">dynamic dispatch</a>.</li>
<li>For structs that wrap DSTs<sup class="footnote-reference" id="fr-2-2"><a href="#fn-2">3</a></sup>, their metadata is the metadata of the wrapped DST.</li>
</ul>
<p>And that's it! For all slices, the metadata can be thought of as the length. Trait objects are a bit more complex, but I hope to cover them in a later blog post.</p>
<h2 id="reading-metadata">Reading Metadata<a class="zola-anchor" href="#reading-metadata" aria-label="Anchor link for: reading-metadata" style="visibility: hidden;"></a>
</h2>
<p>The unstable <a rel="external" href="https://doc.rust-lang.org/stable/std/ptr/fn.metadata.html"><code>std::ptr::metadata</code></a> function can be used to read the metadata of any pointer.</p>
<pre class="giallo z-code"><code data-lang="rust"><span class="giallo-l"><span class="z-punctuation z-definition z-attribute z-rust">#</span><span class="z-meta z-attribute z-rust">!</span><span class="z-punctuation">[</span><span class="z-meta z-attribute z-rust">feature</span><span class="z-punctuation">(</span><span class="z-meta z-attribute z-rust">ptr_metadata</span><span class="z-punctuation">)</span><span class="z-punctuation">]</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-keyword">use</span><span class="z-entity z-name z-namespace"> std</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-namespace">ptr</span><span class="z-keyword z-operator">::</span><span class="z-source">metadata</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-keyword">fn</span><span class="z-entity z-name z-function"> main</span><span class="z-punctuation">(</span><span class="z-punctuation">)</span><span class="z-punctuation"> {</span></span>
<span class="giallo-l"><span class="z-storage z-type z-rust"> let</span><span class="z-source"> slice</span><span class="z-keyword z-operator">:</span><span class="z-keyword z-operator"> &</span><span class="z-punctuation">[</span><span class="z-entity z-name z-type z-numeric z-rust">u8</span><span class="z-punctuation">]</span><span class="z-keyword z-operator"> =</span><span class="z-keyword z-operator"> &</span><span class="z-punctuation">[</span><span class="z-constant z-numeric">1</span><span class="z-punctuation">,</span><span class="z-constant z-numeric"> 2</span><span class="z-punctuation">,</span><span class="z-constant z-numeric"> 3</span><span class="z-punctuation">]</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"><span class="z-entity z-name z-function z-macro z-rust"> assert_eq!</span><span class="z-punctuation">(</span><span class="z-entity z-name z-function">metadata</span><span class="z-punctuation">(</span><span class="z-variable z-other z-rust">slice</span><span class="z-punctuation">)</span><span class="z-punctuation">,</span><span class="z-constant z-numeric"> 3</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-storage z-type z-rust"> let</span><span class="z-source"> string</span><span class="z-keyword z-operator"> =</span><span class="z-punctuation z-definition z-string"> "</span><span class="z-string">Boo!</span><span class="z-punctuation z-definition z-string">"</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"><span class="z-entity z-name z-function z-macro z-rust"> assert_eq!</span><span class="z-punctuation">(</span><span class="z-entity z-name z-function">metadata</span><span class="z-punctuation">(</span><span class="z-variable z-other z-rust">string</span><span class="z-punctuation">)</span><span class="z-punctuation">,</span><span class="z-constant z-numeric"> 4</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Create a DST wrapper type.</span></span>
<span class="giallo-l"><span class="z-storage z-type z-rust"> struct</span><span class="z-entity z-name z-type"> Wrapper</span><span class="z-punctuation z-brackets z-angle z-rust"><</span><span class="z-entity z-name z-type">T</span><span class="z-keyword z-operator">:</span><span class="z-keyword z-operator"> ?</span><span class="z-entity z-name z-type">Sized</span><span class="z-punctuation z-brackets z-angle z-rust">></span><span class="z-punctuation"> {</span></span>
<span class="giallo-l"><span class="z-source"> foo</span><span class="z-keyword z-operator">:</span><span class="z-entity z-name z-type"> bool</span><span class="z-punctuation">,</span></span>
<span class="giallo-l"><span class="z-source"> bar</span><span class="z-keyword z-operator">:</span><span class="z-entity z-name z-type"> T</span><span class="z-punctuation">,</span></span>
<span class="giallo-l"><span class="z-punctuation"> }</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> The metadata is the size of `bar`.</span></span>
<span class="giallo-l"><span class="z-storage z-type z-rust"> let</span><span class="z-source"> wrapper</span><span class="z-keyword z-operator">:</span><span class="z-keyword z-operator"> &</span><span class="z-entity z-name z-type">Wrapper</span><span class="z-punctuation z-brackets z-angle z-rust"><</span><span class="z-punctuation">[</span><span class="z-entity z-name z-type">bool</span><span class="z-punctuation">]</span><span class="z-punctuation z-brackets z-angle z-rust">></span><span class="z-keyword z-operator"> =</span><span class="z-keyword z-operator"> &</span><span class="z-entity z-name z-type">Wrapper</span><span class="z-punctuation"> {</span></span>
<span class="giallo-l"><span class="z-source"> foo</span><span class="z-keyword z-operator">:</span><span class="z-constant z-language"> true</span><span class="z-punctuation">,</span></span>
<span class="giallo-l"><span class="z-source"> bar</span><span class="z-keyword z-operator">:</span><span class="z-punctuation"> [</span><span class="z-constant z-language">false</span><span class="z-punctuation">,</span><span class="z-constant z-language"> true</span><span class="z-punctuation">]</span><span class="z-punctuation">,</span></span>
<span class="giallo-l"><span class="z-punctuation"> }</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> `bar` has a length of 2.</span></span>
<span class="giallo-l"><span class="z-entity z-name z-function z-macro z-rust"> assert_eq!</span><span class="z-punctuation">(</span><span class="z-entity z-name z-function">metadata</span><span class="z-punctuation">(</span><span class="z-variable z-other z-rust">wrapper</span><span class="z-punctuation">)</span><span class="z-punctuation">,</span><span class="z-constant z-numeric"> 2</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Thin pointers have no metadata, so they're metadata is a unit type.</span></span>
<span class="giallo-l"><span class="z-storage z-type z-rust"> let</span><span class="z-source"> thin</span><span class="z-keyword z-operator">:</span><span class="z-entity z-name z-type z-numeric z-rust"> u8</span><span class="z-keyword z-operator"> =</span><span class="z-constant z-numeric"> 2</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"><span class="z-entity z-name z-function z-macro z-rust"> assert_eq!</span><span class="z-punctuation">(</span><span class="z-entity z-name z-function">metadata</span><span class="z-punctuation">(</span><span class="z-keyword z-operator">&</span><span class="z-variable z-other z-rust">thin</span><span class="z-punctuation">)</span><span class="z-punctuation">,</span><span class="z-punctuation"> (</span><span class="z-punctuation">)</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"><span class="z-punctuation">}</span></span></code></pre>
<p><code>metadata</code> works in combination with the <a rel="external" href="https://doc.rust-lang.org/stable/std/ptr/trait.Pointee.html"><code>Pointee</code></a> trait, which supplies an associated type for the metadata.</p>
<pre class="giallo z-code"><code data-lang="rust"><span class="giallo-l"><span class="z-keyword">pub</span><span class="z-storage z-type z-rust"> trait</span><span class="z-entity z-name z-type"> Pointee</span><span class="z-punctuation"> {</span></span>
<span class="giallo-l"><span class="z-storage z-type z-rust"> type</span><span class="z-entity z-name z-type"> Metadata</span><span class="z-keyword z-operator">:</span><span class="z-entity z-name z-type"> Copy</span><span class="z-keyword z-operator"> +</span><span class="z-entity z-name z-type"> Send</span><span class="z-keyword z-operator"> +</span><span class="z-entity z-name z-type"> Sync</span><span class="z-keyword z-operator"> +</span><span class="z-entity z-name z-type"> Ord</span><span class="z-keyword z-operator"> +</span><span class="z-entity z-name z-type"> Hash</span><span class="z-keyword z-operator"> +</span><span class="z-entity z-name z-type"> Unpin</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"><span class="z-punctuation">}</span></span></code></pre>
<p><code>Pointee</code> is implemented for every type. For most, <code>Metadata</code> will be the <a rel="external" href="https://doc.rust-lang.org/std/primitive.unit.html">unit <code>()</code></a> type. It only differs for dynamically sized types, which range from just the raw <code>usize</code> to the more complicated <a rel="external" href="https://doc.rust-lang.org/stable/std/ptr/struct.DynMetadata.html"><code>DynMetadata<Dyn></code></a> type.</p>
<h2 id="conclusion">Conclusion<a class="zola-anchor" href="#conclusion" aria-label="Anchor link for: conclusion" style="visibility: hidden;"></a>
</h2>
<p>Hey, you made it! Congratulations! I hope you enjoyed reading this article and learned a little more about Rust. I found pointer metadata interesting because it exposes fun implementation details that aren't known to the average Rustacean. As per usual, here are a few more links to dive into related to pointer metadata:</p>
<ul>
<li><a rel="external" href="https://rust-lang.github.io/rfcs/2580-ptr-meta.html">RFC 2580</a></li>
<li><a rel="external" href="https://github.com/rust-lang/rust/issues/81513">Pointer Metadata Tracking Issue</a></li>
<li><a rel="external" href="https://doc.rust-lang.org/std/ptr/fn.metadata.html"><code>metadata<T>(*const T)</code></a></li>
<li><a rel="external" href="https://doc.rust-lang.org/std/ptr/trait.Pointee.html"><code>Pointee</code></a></li>
<li><a rel="external" href="https://doc.rust-lang.org/std/ptr/struct.DynMetadata.html"><code>DynMetadata<Dyn></code></a></li>
<li><a rel="external" href="https://doc.rust-lang.org/1.71.0/src/core/ptr/metadata.rs.html#138-149">Private <code>PtrRepr</code> and <code>PtrComponents</code></a></li>
<li><a rel="external" href="https://doc.rust-lang.org/1.71.0/src/core/slice/mod.rs.html#141-143"><code>slice::len()</code></a></li>
<li><a rel="external" href="https://github.com/BD103/Blog-Examples/blob/main/ptr-metadata/src/bin/04-sneak-peak.rs">👀 A sneak peak at VTables</a></li>
</ul>
<p>If you have any questions, feel free to comment on <a rel="external" href="https://users.rust-lang.org/t/introduction-to-pointer-metadata/98083">my post</a> in the Rust Users' Forum or contact me <a rel="external" href="https://github.com/BD103/BD103/issues">by creating an issue</a> in my Github repository. The source code for all examples in this post can be found <a rel="external" href="https://github.com/BD103/Blog-Examples/tree/main/ptr-metadata">here</a>.</p>
<p>Cheers!</p>
<figure>
<img
src="https://www.rustacean.net/assets/rustacean-flat-happy.svg"
alt="Ferris the crab, Rust's unofficial mascot, smiling"
width="200rem"
>
<figcaption><p><a rel="external" href="https://rustacean.net/">via</a></p>
</figcaption>
</figure>
<section class="footnotes">
<ol class="footnotes-list">
<li id="fn-0">
<p>See <a rel="external" href="https://doc.rust-lang.org/book/ch04-02-references-and-borrowing.html">the Book</a> on the Rust Borrow Checker. I'd hope that the reader would know about Rust ownership rules, but I don't really know who my audience is yet. :P <a href="#fr-0-1">↩</a></p>
</li>
<li id="fn-1">
<p>Or 64 bits, as stated previously. <code>bits = 8 * bytes</code> <a href="#fr-1-1">↩</a></p>
</li>
<li id="fn-2">
<p>See <a rel="external" href="https://doc.rust-lang.org/reference/items/traits.html#object-safety">object safety</a> in the Rust Reference. You can created structures that wrap DSTs as long as it doesn't contain more than one DST (along with a bunch of other restrictions). <a href="#fr-2-1">↩</a> <a href="#fr-2-2">↩2</a></p>
</li>
</ol>
</section>
Intercepting Allocations with the Global Allocator2023-06-27T00:00:00+00:002023-06-27T00:00:00+00:00
BD103
https://bd103.dev/blog/2023-06-27-global-allocators/
<blockquote class="callout important has-title">
<p class="title">
<span class="icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="18" height="18"><path d="M12 22C6.47715 22 2 17.5228 2 12C2 6.47715 6.47715 2 12 2C17.5228 2 22 6.47715 22 12C22 17.5228 17.5228 22 12 22ZM12 20C16.4183 20 20 16.4183 20 12C20 7.58172 16.4183 4 12 4C7.58172 4 4 7.58172 4 12C4 16.4183 7.58172 20 12 20ZM11 15H13V17H11V15ZM11 7H13V13H11V7Z" fill="currentColor"></path></svg>
</span>
<strong>Important</strong>
</p>
<div class="content">
<p>This post is directed towards programmers experienced with the <a rel="external" href="https://www.rust-lang.org">Rust</a> programming language that are interested in manual memory management. I will not explain some concepts like pointers, statics, etc. If you want to learn how to program in Rust, you can find a helpful page <a rel="external" href="https://www.rust-lang.org/learn">here</a>.</p>
</div>
</blockquote>
<p>It is possible to replace the global heap allocator used by <a rel="external" href="https://doc.rust-lang.org/stable/std/boxed/struct.Box.html"><code>Box<T></code></a>, <a rel="external" href="https://doc.rust-lang.org/stable/std/vec/struct.Vec.html"><code>Vec<T></code></a>, and more. This is useful if you want to use a custom allocator like <a rel="external" href="https://jemalloc.net">jemalloc</a> for the features it provides, or if you are working in a <code>#![no_std]</code> context without an OS allocator.</p>
<p>This article is going to cover:</p>
<ul>
<li>The <a rel="external" href="https://doc.rust-lang.org/stable/std/alloc/trait.GlobalAlloc.html"><code>GlobalAlloc</code></a> trait</li>
<li>The <a rel="external" href="https://doc.rust-lang.org/stable/std/alloc/struct.System.html"><code>System</code></a> allocator</li>
<li>Wrapping the <code>System</code> allocator with custom code</li>
<li>The <code>wg-allocators</code>' plans for the future</li>
</ul>
<h2 id="the-globalalloc-trait">The <code>GlobalAlloc</code> Trait<a class="zola-anchor" href="#the-globalalloc-trait" aria-label="Anchor link for: the-globalalloc-trait" style="visibility: hidden;"></a>
</h2>
<p><a rel="external" href="https://doc.rust-lang.org/stable/std/alloc/trait.GlobalAlloc.html"><code>GlobalAlloc</code></a> is a trait that was stabilized in Rust 1.28. It is meant to be implemented to any struct that wishes to replace the default allocator. Here's a simplified version of its definition:</p>
<pre class="giallo z-code"><code data-lang="rust"><span class="giallo-l"><span class="z-keyword">pub</span><span class="z-keyword"> unsafe</span><span class="z-storage z-type z-rust"> trait</span><span class="z-entity z-name z-type"> GlobalAlloc</span><span class="z-punctuation"> {</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Required methods</span></span>
<span class="giallo-l"><span class="z-keyword"> unsafe</span><span class="z-keyword"> fn</span><span class="z-entity z-name z-function"> alloc</span><span class="z-punctuation">(</span><span class="z-keyword z-operator">&</span><span class="z-variable z-language z-self z-rust">self</span><span class="z-punctuation">,</span><span class="z-variable z-other z-rust"> layout</span><span class="z-keyword z-operator">:</span><span class="z-entity z-name z-type"> Layout</span><span class="z-punctuation">)</span><span class="z-keyword z-operator"> -></span><span class="z-keyword z-operator"> *</span><span class="z-storage z-modifier">mut</span><span class="z-entity z-name z-type z-numeric z-rust"> u8</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"><span class="z-keyword"> unsafe</span><span class="z-keyword"> fn</span><span class="z-entity z-name z-function"> dealloc</span><span class="z-punctuation">(</span><span class="z-keyword z-operator">&</span><span class="z-variable z-language z-self z-rust">self</span><span class="z-punctuation">,</span><span class="z-variable z-other z-rust"> ptr</span><span class="z-keyword z-operator">:</span><span class="z-keyword z-operator"> *</span><span class="z-storage z-modifier">mut</span><span class="z-entity z-name z-type z-numeric z-rust"> u8</span><span class="z-punctuation">,</span><span class="z-variable z-other z-rust"> layout</span><span class="z-keyword z-operator">:</span><span class="z-entity z-name z-type"> Layout</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Provided methods (out of scope for this article)</span></span>
<span class="giallo-l"><span class="z-keyword z-operator"> ...</span></span>
<span class="giallo-l"><span class="z-punctuation">}</span></span></code></pre>
<p>Any struct that wants to become a global allocator has to be able to both allocate and deallocate regions of memory. It can approach this in many different ways, but all implementations use a pointer and a size to represent memory.</p>
<p>Take <code>alloc()</code> for example. It takes a <a rel="external" href="https://doc.rust-lang.org/stable/std/alloc/struct.Layout.html"><code>Layout</code></a>, which represents a size and alignment<sup class="footnote-reference" id="fr-0-1"><a href="#fn-0">1</a></sup> for a block of memory. It then returns a pointer to the first byte (<code>u8</code>) of the freshly allocated memory.</p>
<p><code>dealloc()</code> is the inverse of this. It takes the pointer and the layout, then internally deallocates the memory block based on the given information.</p>
<h2 id="the-system-allocator">The <code>System</code> Allocator<a class="zola-anchor" href="#the-system-allocator" aria-label="Anchor link for: the-system-allocator" style="visibility: hidden;"></a>
</h2>
<p>If you are running on a computer that the standard library supports, then you have access to the <a rel="external" href="https://doc.rust-lang.org/stable/std/alloc/struct.System.html"><code>System</code></a> default global allocator. If you don't specify a global allocator, then this will be used instead.</p>
<blockquote class="callout tip has-title">
<p class="title">
<span class="icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="18" height="18"><path d="M9.97308 18H11V13H13V18H14.0269C14.1589 16.7984 14.7721 15.8065 15.7676 14.7226C15.8797 14.6006 16.5988 13.8564 16.6841 13.7501C17.5318 12.6931 18 11.385 18 10C18 6.68629 15.3137 4 12 4C8.68629 4 6 6.68629 6 10C6 11.3843 6.46774 12.6917 7.31462 13.7484C7.40004 13.855 8.12081 14.6012 8.23154 14.7218C9.22766 15.8064 9.84103 16.7984 9.97308 18ZM10 20V21H14V20H10ZM5.75395 14.9992C4.65645 13.6297 4 11.8915 4 10C4 5.58172 7.58172 2 12 2C16.4183 2 20 5.58172 20 10C20 11.8925 19.3428 13.6315 18.2443 15.0014C17.624 15.7748 16 17 16 18.5V21C16 22.1046 15.1046 23 14 23H10C8.89543 23 8 22.1046 8 21V18.5C8 17 6.37458 15.7736 5.75395 14.9992Z" fill="currentColor"></path></svg>
</span>
<strong>Tip</strong>
</p>
<div class="content">
<p><code>System</code> uses libc's <code>malloc</code> and <code>free</code> functions on Unix platforms, while it uses <code>HeapAlloc</code> and associated functions on Windows.</p>
</div>
</blockquote>
<p>Lucky for us, <code>System</code> already implements <code>GlobalAlloc</code>. Without changing anything, here's an overly verbose program that manually registers the <code>System</code> allocator:</p>
<pre class="giallo z-code"><code data-lang="rust"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> Import the System allocator.</span></span>
<span class="giallo-l"><span class="z-keyword">use</span><span class="z-entity z-name z-namespace"> std</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-namespace">alloc</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-type">System</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> This attribute registers the global allocator.</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-attribute z-rust">#</span><span class="z-punctuation">[</span><span class="z-meta z-attribute z-rust">global_allocator</span><span class="z-punctuation">]</span></span>
<span class="giallo-l"><span class="z-storage z-modifier z-rust">static</span><span class="z-entity z-name z-type"> A</span><span class="z-keyword z-operator">:</span><span class="z-entity z-name z-type"> System</span><span class="z-keyword z-operator"> =</span><span class="z-entity z-name z-type"> System</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-keyword">fn</span><span class="z-entity z-name z-function"> main</span><span class="z-punctuation">(</span><span class="z-punctuation">)</span><span class="z-punctuation"> {</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Let's allocate on the heap to prove that it works.</span></span>
<span class="giallo-l"><span class="z-storage z-type z-rust"> let</span><span class="z-source"> _</span><span class="z-keyword z-operator"> =</span><span class="z-entity z-name z-type"> Box</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-function">new</span><span class="z-punctuation">(</span><span class="z-constant z-numeric">103</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"><span class="z-punctuation">}</span></span></code></pre>
<p>To register a global allocator, you initialize it in a <a rel="external" href="https://doc.rust-lang.org/reference/items/static-items.html">static item</a> and annotate it with the <code>#[global_allocator]</code> attribute. There may only be one global allocator in a binary, but there is no restriction on where the static is and what visibility it has.</p>
<blockquote class="callout caution has-title">
<p class="title">
<span class="icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="18" height="18"><path d="M4.00098 20V14C4.00098 9.58172 7.5827 6 12.001 6C16.4193 6 20.001 9.58172 20.001 14V20H21.001V22H3.00098V20H4.00098ZM6.00098 20H18.001V14C18.001 10.6863 15.3147 8 12.001 8C8.68727 8 6.00098 10.6863 6.00098 14V20ZM11.001 2H13.001V5H11.001V2ZM19.7792 4.80761L21.1934 6.22183L19.0721 8.34315L17.6578 6.92893L19.7792 4.80761ZM2.80859 6.22183L4.22281 4.80761L6.34413 6.92893L4.92991 8.34315L2.80859 6.22183ZM7.00098 14C7.00098 11.2386 9.23956 9 12.001 9V11C10.3441 11 9.00098 12.3431 9.00098 14H7.00098Z" fill="currentColor"></path></svg>
</span>
<strong>Caution</strong>
</p>
<div class="content">
<p>It is actually possible for a dependency crate to register a global allocator without the consumer knowing of it. This is <strong>very</strong> bad practice, as the end-user has no control over it. Please don't do this, or at least <a rel="external" href="https://doc.rust-lang.org/cargo/reference/features.html">feature-gate</a> it.</p>
</div>
</blockquote>
<h2 id="wrapping-system">Wrapping <code>System</code><a class="zola-anchor" href="#wrapping-system" aria-label="Anchor link for: wrapping-system" style="visibility: hidden;"></a>
</h2>
<p>Since <code>GlobalAlloc</code> is a public trait, it is very possible to define our own allocator. Instead of going into the nitty-gritty of writing one from scratch, let's instead pass these allocation calls to <code>System</code>. This can let us intercept information, which we will see in the next section. Here's our new code:</p>
<pre class="giallo z-code"><code data-lang="rust"><span class="giallo-l"><span class="z-keyword">use</span><span class="z-entity z-name z-namespace"> std</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-namespace">alloc</span><span class="z-keyword z-operator">::</span><span class="z-punctuation">{</span><span class="z-entity z-name z-type">GlobalAlloc</span><span class="z-punctuation">,</span><span class="z-entity z-name z-type"> Layout</span><span class="z-punctuation">,</span><span class="z-entity z-name z-type"> System</span><span class="z-punctuation">}</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> This is our custom allocator!</span></span>
<span class="giallo-l"><span class="z-keyword">pub</span><span class="z-storage z-type z-rust"> struct</span><span class="z-entity z-name z-type"> MyAlloc</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-keyword">unsafe</span><span class="z-keyword"> impl</span><span class="z-entity z-name z-type"> GlobalAlloc</span><span class="z-keyword"> for</span><span class="z-entity z-name z-type"> MyAlloc</span><span class="z-punctuation"> {</span></span>
<span class="giallo-l"><span class="z-keyword"> unsafe</span><span class="z-keyword"> fn</span><span class="z-entity z-name z-function"> alloc</span><span class="z-punctuation">(</span><span class="z-keyword z-operator">&</span><span class="z-variable z-language z-self z-rust">self</span><span class="z-punctuation">,</span><span class="z-variable z-other z-rust"> layout</span><span class="z-keyword z-operator">:</span><span class="z-entity z-name z-type"> Layout</span><span class="z-punctuation">)</span><span class="z-keyword z-operator"> -></span><span class="z-keyword z-operator"> *</span><span class="z-storage z-modifier">mut</span><span class="z-entity z-name z-type z-numeric z-rust"> u8</span><span class="z-punctuation"> {</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Pass everything to System.</span></span>
<span class="giallo-l"><span class="z-entity z-name z-type"> System</span><span class="z-keyword z-operator">.</span><span class="z-entity z-name z-function">alloc</span><span class="z-punctuation">(</span><span class="z-variable z-other z-rust">layout</span><span class="z-punctuation">)</span></span>
<span class="giallo-l"><span class="z-punctuation"> }</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-keyword"> unsafe</span><span class="z-keyword"> fn</span><span class="z-entity z-name z-function"> dealloc</span><span class="z-punctuation">(</span><span class="z-keyword z-operator">&</span><span class="z-variable z-language z-self z-rust">self</span><span class="z-punctuation">,</span><span class="z-variable z-other z-rust"> ptr</span><span class="z-keyword z-operator">:</span><span class="z-keyword z-operator"> *</span><span class="z-storage z-modifier">mut</span><span class="z-entity z-name z-type z-numeric z-rust"> u8</span><span class="z-punctuation">,</span><span class="z-variable z-other z-rust"> layout</span><span class="z-keyword z-operator">:</span><span class="z-entity z-name z-type"> Layout</span><span class="z-punctuation">)</span><span class="z-punctuation"> {</span></span>
<span class="giallo-l"><span class="z-entity z-name z-type"> System</span><span class="z-keyword z-operator">.</span><span class="z-entity z-name z-function">dealloc</span><span class="z-punctuation">(</span><span class="z-variable z-other z-rust">ptr</span><span class="z-punctuation">,</span><span class="z-variable z-other z-rust"> layout</span><span class="z-punctuation">)</span></span>
<span class="giallo-l"><span class="z-punctuation"> }</span></span>
<span class="giallo-l"><span class="z-punctuation">}</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> Register our custom allocator.</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-attribute z-rust">#</span><span class="z-punctuation">[</span><span class="z-meta z-attribute z-rust">global_allocator</span><span class="z-punctuation">]</span></span>
<span class="giallo-l"><span class="z-storage z-modifier z-rust">static</span><span class="z-entity z-name z-type"> A</span><span class="z-keyword z-operator">:</span><span class="z-entity z-name z-type"> MyAlloc</span><span class="z-keyword z-operator"> =</span><span class="z-entity z-name z-type"> MyAlloc</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-keyword">fn</span><span class="z-entity z-name z-function"> main</span><span class="z-punctuation">(</span><span class="z-punctuation">)</span><span class="z-punctuation"> {</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> String, like Box, also allocates on the heap.</span></span>
<span class="giallo-l"><span class="z-storage z-type z-rust"> let</span><span class="z-source"> _</span><span class="z-keyword z-operator"> =</span><span class="z-entity z-name z-type"> String</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-function">from</span><span class="z-punctuation">(</span><span class="z-punctuation z-definition z-string">"</span><span class="z-string">Boo!</span><span class="z-punctuation z-definition z-string">"</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"><span class="z-punctuation">}</span></span></code></pre>
<p>When running this program, you'll notice that it functions no different than before. We still use <code>System</code>, but we can now run our own code for each allocation. (Which is exactly what we're going to do next!)</p>
<h2 id="counting-allocations">Counting Allocations<a class="zola-anchor" href="#counting-allocations" aria-label="Anchor link for: counting-allocations" style="visibility: hidden;"></a>
</h2>
<p>Say you are profiling some code and want to track how many heap allocations were made. This can easily be implemented with a custom allocator.</p>
<pre class="giallo z-code"><code data-lang="rust"><span class="giallo-l"><span class="z-keyword">use</span><span class="z-entity z-name z-namespace"> std</span><span class="z-keyword z-operator">::</span><span class="z-punctuation">{</span></span>
<span class="giallo-l"><span class="z-entity z-name z-namespace"> alloc</span><span class="z-keyword z-operator">::</span><span class="z-punctuation">{</span><span class="z-entity z-name z-type">GlobalAlloc</span><span class="z-punctuation">,</span><span class="z-entity z-name z-type"> Layout</span><span class="z-punctuation">,</span><span class="z-entity z-name z-type"> System</span><span class="z-punctuation">}</span><span class="z-punctuation">,</span></span>
<span class="giallo-l"><span class="z-entity z-name z-namespace"> sync</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-namespace">atomic</span><span class="z-keyword z-operator">::</span><span class="z-punctuation">{</span><span class="z-entity z-name z-type">AtomicU64</span><span class="z-punctuation">,</span><span class="z-entity z-name z-type"> Ordering</span><span class="z-punctuation">}</span><span class="z-punctuation">,</span></span>
<span class="giallo-l"><span class="z-punctuation">}</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> This is our counting allocator. It wraps a u64 that stores our actual count.</span></span>
<span class="giallo-l"><span class="z-keyword">pub</span><span class="z-storage z-type z-rust"> struct</span><span class="z-entity z-name z-type"> Counter</span><span class="z-punctuation">(</span><span class="z-entity z-name z-type">AtomicU64</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-keyword">impl</span><span class="z-entity z-name z-type"> Counter</span><span class="z-punctuation"> {</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> A const initializer that starts the count at 0.</span></span>
<span class="giallo-l"><span class="z-keyword"> pub</span><span class="z-storage z-modifier z-rust"> const</span><span class="z-keyword"> fn</span><span class="z-entity z-name z-function"> new</span><span class="z-punctuation">(</span><span class="z-punctuation">)</span><span class="z-keyword z-operator"> -></span><span class="z-variable z-language z-self z-rust"> Self</span><span class="z-punctuation"> {</span></span>
<span class="giallo-l"><span class="z-entity z-name z-function"> Counter</span><span class="z-punctuation">(</span><span class="z-entity z-name z-namespace">AtomicU64</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-function">new</span><span class="z-punctuation">(</span><span class="z-constant z-numeric">0</span><span class="z-punctuation">)</span><span class="z-punctuation">)</span></span>
<span class="giallo-l"><span class="z-punctuation"> }</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Returns the current count.</span></span>
<span class="giallo-l"><span class="z-keyword"> pub</span><span class="z-keyword"> fn</span><span class="z-entity z-name z-function"> count</span><span class="z-punctuation">(</span><span class="z-keyword z-operator">&</span><span class="z-variable z-language z-self z-rust">self</span><span class="z-punctuation">)</span><span class="z-keyword z-operator"> -></span><span class="z-entity z-name z-type z-numeric z-rust"> u64</span><span class="z-punctuation"> {</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> We're using Relaxed since there is only 1 synchronization primitive.</span></span>
<span class="giallo-l"><span class="z-variable z-language z-self z-rust"> self</span><span class="z-keyword z-operator">.</span><span class="z-constant z-numeric">0</span><span class="z-punctuation">.</span><span class="z-entity z-name z-function">load</span><span class="z-punctuation">(</span><span class="z-entity z-name z-namespace">Ordering</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-type">Relaxed</span><span class="z-punctuation">)</span></span>
<span class="giallo-l"><span class="z-punctuation"> }</span></span>
<span class="giallo-l"><span class="z-punctuation">}</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-keyword">unsafe</span><span class="z-keyword"> impl</span><span class="z-entity z-name z-type"> GlobalAlloc</span><span class="z-keyword"> for</span><span class="z-entity z-name z-type"> Counter</span><span class="z-punctuation"> {</span></span>
<span class="giallo-l"><span class="z-keyword"> unsafe</span><span class="z-keyword"> fn</span><span class="z-entity z-name z-function"> alloc</span><span class="z-punctuation">(</span><span class="z-keyword z-operator">&</span><span class="z-variable z-language z-self z-rust">self</span><span class="z-punctuation">,</span><span class="z-variable z-other z-rust"> layout</span><span class="z-keyword z-operator">:</span><span class="z-entity z-name z-type"> Layout</span><span class="z-punctuation">)</span><span class="z-keyword z-operator"> -></span><span class="z-keyword z-operator"> *</span><span class="z-storage z-modifier">mut</span><span class="z-entity z-name z-type z-numeric z-rust"> u8</span><span class="z-punctuation"> {</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Increment our counter by 1. See other comment on Ordering.</span></span>
<span class="giallo-l"><span class="z-variable z-language z-self z-rust"> self</span><span class="z-keyword z-operator">.</span><span class="z-constant z-numeric">0</span><span class="z-punctuation">.</span><span class="z-entity z-name z-function">fetch_add</span><span class="z-punctuation">(</span><span class="z-constant z-numeric">1</span><span class="z-punctuation">,</span><span class="z-entity z-name z-namespace"> Ordering</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-type">Relaxed</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"><span class="z-entity z-name z-type"> System</span><span class="z-keyword z-operator">.</span><span class="z-entity z-name z-function">alloc</span><span class="z-punctuation">(</span><span class="z-variable z-other z-rust">layout</span><span class="z-punctuation">)</span></span>
<span class="giallo-l"><span class="z-punctuation"> }</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-keyword"> unsafe</span><span class="z-keyword"> fn</span><span class="z-entity z-name z-function"> dealloc</span><span class="z-punctuation">(</span><span class="z-keyword z-operator">&</span><span class="z-variable z-language z-self z-rust">self</span><span class="z-punctuation">,</span><span class="z-variable z-other z-rust"> ptr</span><span class="z-keyword z-operator">:</span><span class="z-keyword z-operator"> *</span><span class="z-storage z-modifier">mut</span><span class="z-entity z-name z-type z-numeric z-rust"> u8</span><span class="z-punctuation">,</span><span class="z-variable z-other z-rust"> layout</span><span class="z-keyword z-operator">:</span><span class="z-entity z-name z-type"> Layout</span><span class="z-punctuation">)</span><span class="z-punctuation"> {</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> No modifications here! :)</span></span>
<span class="giallo-l"><span class="z-entity z-name z-type"> System</span><span class="z-keyword z-operator">.</span><span class="z-entity z-name z-function">dealloc</span><span class="z-punctuation">(</span><span class="z-variable z-other z-rust">ptr</span><span class="z-punctuation">,</span><span class="z-variable z-other z-rust"> layout</span><span class="z-punctuation">)</span></span>
<span class="giallo-l"><span class="z-punctuation"> }</span></span>
<span class="giallo-l"><span class="z-punctuation">}</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-attribute z-rust">#</span><span class="z-punctuation">[</span><span class="z-meta z-attribute z-rust">global_allocator</span><span class="z-punctuation">]</span></span>
<span class="giallo-l"><span class="z-storage z-modifier z-rust">static</span><span class="z-entity z-name z-type"> A</span><span class="z-keyword z-operator">:</span><span class="z-entity z-name z-type"> Counter</span><span class="z-keyword z-operator"> =</span><span class="z-entity z-name z-type"> Counter</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-function">new</span><span class="z-punctuation">(</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-keyword">fn</span><span class="z-entity z-name z-function"> main</span><span class="z-punctuation">(</span><span class="z-punctuation">)</span><span class="z-punctuation"> {</span></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Track initial count and count after allocating once.</span></span>
<span class="giallo-l"><span class="z-storage z-type z-rust"> let</span><span class="z-source"> count</span><span class="z-keyword z-operator"> =</span><span class="z-entity z-name z-type"> A</span><span class="z-keyword z-operator">.</span><span class="z-entity z-name z-function">count</span><span class="z-punctuation">(</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"><span class="z-storage z-type z-rust"> let</span><span class="z-source"> _</span><span class="z-keyword z-operator"> =</span><span class="z-entity z-name z-type"> Box</span><span class="z-keyword z-operator">::</span><span class="z-entity z-name z-function">new</span><span class="z-punctuation">(</span><span class="z-constant z-numeric">1</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"><span class="z-storage z-type z-rust"> let</span><span class="z-source"> new_count</span><span class="z-keyword z-operator"> =</span><span class="z-entity z-name z-type"> A</span><span class="z-keyword z-operator">.</span><span class="z-entity z-name z-function">count</span><span class="z-punctuation">(</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> count = 3, new_count = 4.</span></span>
<span class="giallo-l"><span class="z-entity z-name z-function z-macro z-rust"> dbg!</span><span class="z-punctuation">(</span><span class="z-source">count</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"><span class="z-entity z-name z-function z-macro z-rust"> dbg!</span><span class="z-punctuation">(</span><span class="z-source">new_count</span><span class="z-punctuation">)</span><span class="z-punctuation">;</span></span>
<span class="giallo-l"><span class="z-punctuation">}</span></span></code></pre>
<p>Wait, wait! Don't go! I know it uses atomics, but we can work through this together.</p>
<p>This allocator keeps a bit of internal state, a <code>u64</code> number to be exact. This number starts at 0 and increments by 1 every time <code>alloc()</code> is called. In order <code>main()</code> function, we track how many allocations were made before and after a <code>Box</code> was constructed. We know our allocator works because <code>new_count</code> is greater by 1 than <code>count</code>.</p>
<p>Realistically that is all the knowledge you need to understand this allocator. You may have spotted the <code>AtomicU64</code> though with its <code>load()</code> and <code>fetch_add()</code> calls. This is an advanced synchronization primitive that prevents data races in concurrency. Since the global allocator is used by the entire program, it is perfectly possible for it to be used by multiple threads. Our <code>AtomicU64</code> ensures that every allocation is counted, no matter where it was called from.</p>
<p>As much as I would love to talk about them, threads and data races are out of the scope of this article. (It's getting long enough as it is!) If you want to learn more about this fascinating subject, please see the <a rel="external" href="https://doc.rust-lang.org/stable/std/thread/index.html"><code>std::thread</code></a> module and <a rel="external" href="https://marabos.nl/atomics/">Mara Bos's fantastic book</a>.</p>
<blockquote class="callout caution has-title">
<p class="title">
<span class="icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="18" height="18"><path d="M4.00098 20V14C4.00098 9.58172 7.5827 6 12.001 6C16.4193 6 20.001 9.58172 20.001 14V20H21.001V22H3.00098V20H4.00098ZM6.00098 20H18.001V14C18.001 10.6863 15.3147 8 12.001 8C8.68727 8 6.00098 10.6863 6.00098 14V20ZM11.001 2H13.001V5H11.001V2ZM19.7792 4.80761L21.1934 6.22183L19.0721 8.34315L17.6578 6.92893L19.7792 4.80761ZM2.80859 6.22183L4.22281 4.80761L6.34413 6.92893L4.92991 8.34315L2.80859 6.22183ZM7.00098 14C7.00098 11.2386 9.23956 9 12.001 9V11C10.3441 11 9.00098 12.3431 9.00098 14H7.00098Z" fill="currentColor"></path></svg>
</span>
<strong>Caution</strong>
</p>
<div class="content">
<p>If we wanted to follow best practices, the <code>AtomicU64</code> would be stored in a separate static and <code>Counter</code> would remain a zero-sized-type (ZST). I felt that the example provided would be easier for a beginner to understand, even if it is not perfect.</p>
</div>
</blockquote>
<h2 id="towards-the-future">Towards the Future<a class="zola-anchor" href="#towards-the-future" aria-label="Anchor link for: towards-the-future" style="visibility: hidden;"></a>
</h2>
<p>And that's it! Thank you for reading this article, I hope you found it interesting. Global allocators can be a handy tool, though they do cover a relatively niche surface of Rust programming. There is a lot of work being put in by the <code>wg-allocators</code> working group to streamline this process and other related parts. Here are a few links that you may find interesting:</p>
<ul>
<li>The <a rel="external" href="https://doc.rust-lang.org/stable/std/alloc/trait.Allocator.html"><code>Allocator</code></a> trait, for non-global allocators
<ul>
<li><a rel="external" href="https://github.com/rust-lang/wg-allocators/issues/7">Structs that support the <code>Allocator</code> API</a></li>
</ul>
</li>
<li>The <a rel="external" href="https://doc.rust-lang.org/stable/std/alloc/struct.Global.html"><code>Global</code></a> struct, which redirects all allocation calls to the registered global allocator</li>
<li><a rel="external" href="https://internals.rust-lang.org/t/pre-rfc-storage-api/18822?u=bd103">Pre-RFC: Storage API</a></li>
<li><a rel="external" href="https://github.com/rust-lang/wg-allocators/issues/48">The <code>wg-allocators</code> Roadmap</a></li>
<li><a rel="external" href="https://github.com/zakarumych/allocator-api2"><code>allocator_api2</code></a>, for using the allocator API in stable Rust</li>
</ul>
<p>If you have any questions, feel free to comment on <a rel="external" href="https://users.rust-lang.org/t/intercepting-allocations-with-the-global-allocator/96277?u=bd103">my post</a> in the Rust Users' Forum or <a rel="external" href="https://github.com/BD103/BD103/issues">create a new issue</a> in my Github repository. The source code for all examples is available <a rel="external" href="https://github.com/BD103/Blog-Examples/tree/main/global-allocator">here</a>.</p>
<p>Have a great day!</p>
<section class="footnotes">
<ol class="footnotes-list">
<li id="fn-0">
<p>Alignment is used for structure packing. While it can be useful for implementing an allocator from scratch, that is out of scope for this article. For more information, you may find this <a rel="external" href="https://en.wikipedia.org/wiki/Data_structure_alignment">Wikipedia article</a> interesting. <a href="#fr-0-1">↩</a></p>
</li>
</ol>
</section>