Meeting proposal: Rust Specification

Summary

Let’s talk about creating an official Rust specification.

Background reading

https://blog.m-ou.se/rust-standard/

Current situation

Languages like C and C++ are standardized. Rust is not. Standardization comes down to, basically:

1. Having an accurate specification (a document)
2. An (open?) process for evolution of the language
3. Stability

Rust currently already has 2 and 3, but not 1.

For 1, we currently have:

• The (incomplete) Rust Reference
• The Standard Library Reference Documentation
• The Rust Nomicon
• The Unsafe Code Guidelines Project
• Miri
• The collection of accepted RFCs
• An early draft of the Ferrocene Language Specification
• Lots context and decisions spread over tons of GitHub issues
• MiniRust
• The source code
• (And probably a few more things.)

These are currently all incomplete, and/or not a good source to rely on.

Things to discuss

It’d be wonderful if we had an official Rust specification, which is kept up to date and distributed together with each new release. (I suppose this would effectively mean completing/upgrading the Rust Reference.)

Questions to discuss:

• Do we want this at all?
• What are the goals we aim to meet? (Audience and purpose.)
• How do we want to do this?
  • Writing a specification involves a lot of tedious work, so it’s unlikely to happen entirely from volunteer contributions, unlike many other parts of the Rust project.
  • We could ask the foundation to fund the work. E.g. by hiring a technical writer/editor who will collect the information and write it down in a draft that the team(s) can approve or give feedback on.
• What form/structure should the spec have?
  • We could take the Ferrocene spec as a starting point, or we could take the current Rust reference as starting point, or we could come up with something else.
• What should the scope of the spec be?
  • Should it include the standard library? (Just core, or also alloc and std?)
  • Should it cover all editions and all versions? Or only the latest ones? (Or only the latest version+edition accurately, but with notes everywhere that say in which edition or version a feature was introduced as useful (but not necessarily accurate/complete) context.)
  • Should it cover things like rustc flags and details about cargo (and build.rs)?
  • How about proc macros? (And the proc_macro crate?)
  • Should it include our (still nonexistent (?)) memory model?
  • Should it also document our stability guarantees?
  • Should it specify exactly which programs are accepted and rejected? Or should it focus on specifying the behavior of accepted programs? (And leave it to “cargo check” which programs are accepted. That’d allow us to skip specifying the exact details of the borrow checker for example, while still specifying the behaviour of any compiled Rust program.)
• How should it tie in to our existing language evolution processes?
  • Do we expect RFCs to include a diff/patch for the spec? (I think no.)
  • Should it be required for the spec to be updated to include a new feature when it is stabilized? (I think yes.)

About this issue

This issue corresponds to a lang-team design meeting proposal. It corresponds to a possible topic of discussion that may be scheduled for deeper discussion during one of our design meetings.

[m-ou-se]

one thing i very much want Rust to avoid is ending up like ISO C++ where the standard’s text is behind a paywall.

No worries, nobody wants that.

I assume you are all aware of the Ferrocene project and its effort to produce a reasonable language reference/specification?

Yes, it’s already mentioned and linked in the meeting proposal above.

[nikomatsakis]

Question I would want to start with:

What are the goals we aim to meet? (for which audience, and for which purpose)