[Git][reproducible-builds/reproducible-website][master] rust: add page about Rust specifics

[kpcyrd (@kpcyrd)]

kpcyrd pushed to branch master at Reproducible Builds / reproducible-website


Commits:
3ed014bd by kpcyrd at 2026-03-03T00:38:58+01:00
rust: add page about Rust specifics

- - - - -


2 changed files:

- _data/docs.yml
- + _docs/rust.md


Changes:

=====================================
_data/docs.yml
=====================================
@@ -29,6 +29,7 @@
   - randomness
   - build-path
   - system-images
+  - rust
   - jvm
   - helm
 - title: Define a build environment


=====================================
_docs/rust.md
=====================================
@@ -0,0 +1,89 @@
+---
+title: Rust
+layout: docs
+permalink: /docs/rust/
+---
+
+Rust is a general-purpose programming language with emphasis on performance,
+type safety, concurrency, and [memory safety]. It references build dependencies
+through cryptographic hashes recorded in dependency lockfiles. Programs written
+in Rust are often already reproducible by default, given the original build
+toolchain is version-matched and build paths are normalized, but this page
+documents some common issues you may encounter.
+
+[memory safety]: https://en.wikipedia.org/wiki/Memory_safety
+
+Dependency Lockfiles
+--------------------
+
+Some distributions (like Arch Linux, Alpine and Homebrew) rely on the upstream
+project to commit a dependency lockfile into the repository. In the Rust
+ecosystem, this file is called `Cargo.lock`.
+
+Usually this file is automatically respected by `cargo build` and `cargo build
+--release`, but if it can't satisfy the dependencies in the corresponding
+`Cargo.toml`, cargo may re-resolve the dependency tree using the latest
+semver-compatible versions available, which are going to be different in the
+future.
+
+To disable this behavior and instead insist on an error, use:
+
+```
+cargo build --locked
+```
+
+Not all distributions use the dependency lockfile, the Debian project is using
+their own dependency resolver and [.buildinfo files]({{ "/docs/recording/" |
+relative_url }}).
+
+Diffing the Build Directory
+---------------------------
+
+If you encounter an unreproducible binary, you can usually track down the
+problem to a specific binary by running diffoscope on the `target/`
+directory[^diff-target].
+
+```
+cargo build --release && mv target target.1
+cargo build --release && mv target target.2
+diffoscope --html diff.html --exclude-directory-metadata=yes target.1/ target.2/
+```
+
+You can ignore the file `.rustc_info.json` as well as the files in
+`.fingerprint/`[^fingerprint].
+
+If you see a difference in e.g. `target.1/release/libfoo.rlib` that is a strong
+indicator the problem is in the `foo` crate and you can focus your
+investigation there.
+
+[^diff-target]: [Debugging Reproducibility Issues in Rust
+    Software](https://notes.8pit.net/notes/iqfs.html)
+[^fingerprints]: [Reproducible Builds: Make target/.fingerprint/.../dep-...
+    dep-info files deterministic](https://github.com/rust-lang/cargo/pull/16691)
+
+Embedded Build Time
+-------------------
+
+[`SOURCE_DATE_EPOCH`]({{ "/docs/source-date-epoch/#rust" | relative_url }}).
+
+Build Scripts (`build.rs`)
+--------------------------
+
+See [stable outputs]({{ "/docs/stable-outputs/#rust" | relative_url }})[^docs].
+
+[^docs]: https://doc.rust-lang.org/cargo/reference/build-scripts.html
+
+rust-embed
+----------
+
+The popular crate [`rust-embed`](https://crates.io/crates/rust-embed) contains
+macros to embed additional files into the compiled binary. This is often used
+to bundle web assets. By default, it also records the filesystem metadata of
+those files, including the modification time.
+
+This can be turned off using the `deterministic-timestamps` feature.
+
+```toml
+[dependencies]
+rust-embed = { version = "8.5.0", features = ["deterministic-timestamps"] }
+```



View it on GitLab: https://salsa.debian.org/reproducible-builds/reproducible-website/-/commit/3ed014bd93d1718618822c9dd3829ac93258ee93

-- 
View it on GitLab: https://salsa.debian.org/reproducible-builds/reproducible-website/-/commit/3ed014bd93d1718618822c9dd3829ac93258ee93
You're receiving this email because of your account on salsa.debian.org.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.reproducible-builds.org/pipermail/rb-commits/attachments/20260302/eb417bb7/attachment.htm>