Rust 1.18 distributes a rewritten explanation of the language

A compiler can enforce a rule without making that rule easy to learn. Rust 1.18 includes the first draft of a rewritten official book, drawing on the experience of teaching the language since its initial stable release. The release treats explanations as part of the practical language environment, alongside implementation and library changes.

The June 8 announcement credits Carol Nichols and Steve Klabnik with the rewrite and notes more than a hundred contributors. Nineteen of twenty chapters have drafts. This is a substantial new account of the language, but it remains an incomplete draft offered for wider feedback, with editing still underway.

The 2017 roadmap makes the context explicit. Lowering the learning curve is a project goal, with a new book and better explanations among the planned work. Rust 1.18 supplies a concrete installment of that effort without claiming that the teaching problem is finished.

I am impressed by the semantics of Rust, but a strict language also needs explanations that let a learner predict what the compiler will accept. Rewriting the book can address misunderstandings that isolated reference additions would leave intact. The value is in a coherent account of the model, not simply more pages.

The draft has a defined status

The announcement describes a rewrite from the ground up. It promises new explanations of core concepts and new projects to build, informed by the preceding two years of teaching. That is different from updating a few examples to match newly stable syntax.

The draft status matters to how readers should use it. Most chapters are present, but the final chapter is not part of this release. The announcement invites feedback while the authors continue editing with the publisher. A reader can evaluate the explanations now without mistaking them for a completed printed edition.

Documentation also needs to distinguish guarantees from observations. The other changes in this release provide unusually concrete examples. Visibility rules define which code may use an item. Default field layout deliberately leaves room for implementation choices. Both require explanations accurate enough that programmers do not infer promises from one successful program.

Visibility gains an internal boundary

Items are private by default, while pub exposes them more broadly. Rust 1.18 adds restricted visibility, including pub(crate) for an item accessible within its crate but not exposed to external users. The announcement says the earlier module system could express such arrangements, but often awkwardly.

A crate-wide helper can now state its intended boundary where it is declared. The following example has an ordinary function body and uses the new restriction directly.

pub(crate) fn default_limit() -> usize {
    16
}

The number is just example data. The important property is that other code in the crate can use the function without making it part of the interface offered outside the crate. This lets internal decomposition proceed without accidentally turning every shared helper into a public commitment.

The announcement also describes path-based restrictions for a specified module hierarchy. That makes visibility a more precise tool for expressing architecture. The syntax identifies the area where an item is usable, while the type and function body continue to describe what the item does.

Field order was never the default guarantee

The release enables automatic reordering for structures, tuple fields, and enum variant fields using the unspecified Rust layout. The announcement illustrates a tuple structure containing u8, u16, and another u8. On x86-64, its previous layout occupied six bytes because of padding, while reordering permits four.

The source declaration has not changed, but the compiler can choose a more compact representation. That is permitted because the default layout was left unspecified. A program that treats the earlier observed order as a guarantee has added an assumption the language did not promise.

This matters particularly to unsafe code. Safe field access uses the declared fields through the language, while code calculating offsets or interpreting bytes may depend on representation details. The announcement says the optimization had previously been rolled back while known unsafe assumptions were repaired, and asks for reports of remaining breakage.

For foreign interfaces, the release points to #[repr(C)], which prevents this reordering and requests C-compatible field layout. It supplies the explicit representation choice when the boundary requires it. A compact default layout and a predictable foreign layout serve different purposes.

I see the book and this implementation change as connected work. A learner needs to know which observations can be relied on when writing systems code. A clearer explanation of the representation contract can prevent an unsafe assumption that a compiler optimization later exposes.

The release also adds an opt-in CommonMark parser for rustdoc through --enable-commonmark. The announcement presents it as a transition mechanism for finding rendering differences before replacing the existing parser. That gives documentation producers a way to check their actual material, just as the book draft gives readers a way to test the new explanations while revision is still possible.