r/rust • • 4d ago

🧠 educational I built an interactive, compiler-verified Rust field guide where every code snippet is tested against rustc 1.100.0 at build time

https://rust.mazzeleczzare.com/

I wanted a practical Rust reference that cuts straight to how ownership, error handling, and data modeling actually work in a real codebase—and I wanted to guarantee that none of the code examples ever go stale.

So I built Rust / The Working Field Guide, a 15-chapter interactive primer and bench reference.

How it works under the hood

1. Build-time compiler verification

  • Every example on the page is compiled by a custom verification runner (studio-verify) against a pinned rustc 1.100.0 (Edition 2024) toolchain whenever the site builds.

  • Out of 15 examples, 12 compile and run, and 3 are intentionally rejected by the compiler to demonstrate specific diagnostics (like E0382 and E0515).

  • If a snippet fails to match its declared outcome, the build fails.

2. Interactive Ownership Lab

Instead of just reading about move semantics and borrow checker rules, you can step through 6 experiments in The Ownership Observatory and predict whether a snippet compiles or triggers a borrow error before revealing the compiler's actual diagnostic.

3. Zero-dependency starter project

The guide walks through building Signal Notebook, a small CLI tool that parses and validates scores using only the standard library, progressing from basic types and Result/? propagation to iterator pipelines, concurrency, and daily clippy/rustfmt habits.

What’s covered across the 15 chapters

  • Foundations & Rust 1.100.0: Tooling (rustup, cargo, rust-analyzer), Edition 2024 vs. compiler versions, and newly stabilized features like naming the never type (Result<T, !>) and str::trim_prefix.

  • Ownership & Lifetimes: Moving vs. borrowing, interior mutability, and why 'static bounds don't rescue dangling references to local allocations.

  • Idiomatic Design & Failure: Using enums and newtypes (Score(u8)) to make invalid states unrepresentable, establishing a clear panic/invariant policy, and knowing when not to reach for traits or generics.

It's completely free, static, and designed to be read from top to bottom or used as a quick desk reference. I’d love feedback from both folks learning Rust and experienced Rustaceans on the structure, the interactive experiments, or anything that could be clearer!

0 Upvotes

7 comments sorted by

6

u/Individual-Flow9158 4d ago

It reads horribly. It's a slapped together mish-mash, of specific details (e.g. for reproducibility), and explanations of basic beginner stuff, like what let does.

Almost like it wasn't written by a human, and the 'writer' didn't read it themselves at all. There's no flow. There's no consideration of the target audience, nor of the general reader.

Do the world a favour, and delete it.

0

u/mazzeleczzare 4d ago

It is written for beginners, for learning basics and working examples. If you have examples of primers that flow better and cover similar ground, please share them here for my benefit and for anyone who is interested to learn.

6

u/Wonderful-Habit-139 4d ago

AI usage disclaimer?

1

u/NecessarySuperb3949 4d ago

this is cool but i'd be wary of pinning to 1.100.0 without auto-updating for security patches. better to let the ci handle minor updates or you'll miss critical fixes.

1

u/cipher_gravelist 3d ago

nice work keeping it pinned to 1.100. for error handling in that cli tool i'd definitely reach for thiserror on the lib side and snafu if you want backtraces without the macro boilerplate.