Caution

You’re reading a draft of the Ferrocene Language Specification. Some parts of this document might be missing, incomplete or incorrect. Our aim is to have the specification ready by the end of 2022.

Note

The contents of this page are informational.

1. General

1:1 This document is influenced by the Ada Reference Manual Ada 202x edition, as well as the Rust Language Reference, the Rust Guidebook and the Rustonomicon.

1:2 Parts of these documents have been copied, in whole or in part, in particular but not limited to:

  • 1:3 The outline and structure of the documents;

  • 1:4 The title, outline, organization, and numbering of chapters;

  • 1:5 The structure, formality, wording, and numbering of paragraphs;

  • 1:6 The definitions and uses of terms;

  • 1:7 The categories of syntactic and semantic rules.

1:8 Consult Licenses for the relevant copyright notices and licenses.

1.1. Scope

1.1:1 This document specifies the form and meaning of programs written in the programming language Rust, as implemented by the rustc compiler shipped with Ferrocene. It documents the current understanding for the purposes of compiler validation. As such, given any doubt, it prefers documenting behavior of rustc as included in the associated Ferrocene release over claiming correctness as a specification.

1.1:2 This document is made available for contribution and review as it is useful outside of the Ferrocene effort and can be a place of shared understanding. It is not intended as a discussion ground for language evolution. It is also not intended as a document enabling conformance between compilers.

1.1:3 Contribution and review is managed by the Ferrocene project developers.

1.1.1. Extent

1.1.1:1 This document specifies:

  • 1.1.1:2 The form of a program written in Rust;

  • 1.1.1:3 The effect of translating and executing such a program;

  • 1.1.1:4 The manner in which modules and crates may be combined to form Rust programs;

  • 1.1.1:5 The language-defined libraries that a conforming tool is required to supply;

  • 1.1.1:6 The violations that a conforming tool is required to detect, and the effect of attempting to translate or execute a program containing such violations;

  • 1.1.1:7 The violations that a conforming tool is not required to detect.

1.1.1:8 This document does not specify:

  • 1.1.1:9 The means by which a Rust program is transformed into object code executable by a processor;

  • 1.1.1:10 The means by which translation or execution of Rust programs is invoked and the executing units are controlled;

  • 1.1.1:11 The size or speed of the object code, or the relative execution speed of different language constructs;

  • 1.1.1:12 The form or contents of any listings produced by a tool; in particular, the form or contents of error or warning messages;

  • 1.1.1:13 The effect of undefined behavior;

  • 1.1.1:14 The size of a program or program unit that will exceed the capacity of a conforming tool.

1.1.2. Structure

1.1.2:1 This document contains 21 chapters, 2 appendices, and an index.

1.1.2:2 The specification of the Rust language is separated into:

1.1.2:6 The specification is normative, except for the material in each of the items listed below, which is informative:

  • 1.1.2:7 Text under an Examples heading.

  • 1.1.2:8 Each subchapter whose title starts with the word “Example” or “Examples”.

1.1.2:9 The following appendices are informative:

1.1.2:12 Each chapter is divided into subchapters that have a common structure. Each chapter and subchapter is then organized to include the following segments as is relevant to the topic:

Syntax

1.1.2:13 The syntax representation of a construct.

Legality Rules

1.1.2:14 Compile-time rules and facts for each construct. A construct is legal if it obeys all of the Legality Rules.

1.1.2:15 Legality Rules are verified after macro expansion takes place.

Dynamic Semantics

1.1.2:16 Run-time effects of each construct.

Undefined Behavior

1.1.2:17 Situations that result in unbounded errors.

Implementation Requirements

1.1.2:18 Additional requirements for conforming tools.

Examples

1.1.2:19 Examples illustrating the possible forms of a construct. This material is informative.

1.1.3. Conformity

Implementation Requirements

1.1.3:1 A conforming tool shall:

  • 1.1.3:2 Translate and correctly execute legal programs written in Rust, provided that they are not so large as to exceed the capacity of the tool,

  • 1.1.3:3 Identify all programs or program units that are so large as to exceed the capacity of the tool (or raise an appropriate exception at run time),

  • 1.1.3:4 Identify all programs or program units that contain errors whose detection is required by this document,

  • 1.1.3:5 Supply all language-defined library units required by this document,

  • 1.1.3:6 Contain no variations except those explicitly permitted by this document, or those that are impossible or impractical to avoid given the tool’s execution environment,

  • 1.1.3:7 Specify all such variations in the manner prescribed by this document.

1.1.3:8 The external effect of the execution of a Rust program is defined in terms of its interactions with its external environment. The following are defined as external interactions:

1.1.3:12 A tool that conforms to this document shall produce for the execution of a given Rust program a set of interactions with the external environment whose order and timing are consistent with the definitions and requirements of this document for the semantics of the given program.

1.1.3:13 A tool that conforms to this document shall support each capability required by the language as specified.

1.1.3:14 A tool that conforms to this document may provide additional attributes as long as their names are not the same as the names of built-in attributes.

1.1.4. Method of Description and Syntax Notation

1.1.4:1 The form of a Rust program is described by means of a context-free syntax together with context-dependent requirements expressed by narrative rules.

1.1.4:2 The meaning of a Rust program is described by means of narrative rules defining both the effects of each construct and the composition rules for constructs.

1.1.4:3 The context-free syntax of Rust is described using a simple variant of the Backus-Naur form. In particular:

  • 1.1.4:4 A monospaced font is used to denote Rust syntax.

  • 1.1.4:5 Words in PascalCase font are used to denote a syntactic category, for example:

FloatExponent
  • 1.1.4:6 Words in bold font are used to indicate literal words and keywords, for example:

crate
proc_macro_derive
Self
tt
  • 1.1.4:7 Characters in bold font are used to indicate literal characters and literal punctuation, for example:

1
F
{
&&
>>=
  • 1.1.4:8 A character preceded by \ (bold reverse solidus) is used to denote an escaped character, for example:

\t
\\
  • 1.1.4:9 A prefix followed by ? (question mark) is used to denote an optional prefix, for example:

IntegerSuffix?
  • 1.1.4:10 A prefix followed by * (asterisk) is used to denote zero or more repetitions of the prefix, for example:

OuterAttributeOrDoc*
  • 1.1.4:11 A prefix followed by + (plus sign) is used to denote one or more repetitions of the prefix, for example:

MacroMatch+
  • 1.1.4:12 A prefix followed by L-H is used to denote the number of repetitions of the prefix within the range from L to H, inclusive. For example:

HexadecimalDigit1-6
  • 1.1.4:13 [ ] (square brackets) indicate any character within, for example:

[8 a \r :]
  • 1.1.4:14 ~[ ] (square brackets preceded by tilde) indicate any character except the characters within, for example:

~[8 a \r :]
  • 1.1.4:15 [ - ] indicates any character within the specified range, inclusive. For example:

[a-f]
  • 1.1.4:16 A | (vertical line) separates alternative items, for example:

self | Identifier | _
  • 1.1.4:17 ( ) (parentheses) are used to group items, for example:

(, ConfigurationPredicate)

1.1.4:18 Whenever the run-time semantics define certain actions to happen in an arbitrary order, this means that a tool arranges for these actions to occur in a way that is equivalent to some sequential order, following the rules that result from that sequential order. This can happen, for example, if two parameters of a given call expression have side effects.

1.2. Versioning

1.2:1 Ferrocene is a qualified compiler and this is the accompanying language specification for the qualified version of the compiler. This document will be updated with each qualification to accurately reflect the behavior of the compiler qualified under that version of Ferrocene.

1.3. Definitions

1.3:1 Terms are defined throughout this document, indicated by italic type. Terms explicitly defined in this document are not to be presumed to refer implicitly to similar terms defined elsewhere.

1.3:2 Mathematical terms not defined in this document are to be interpreted according to the CRC Concise Encyclopedia of Mathematics, Second Edition.

1.3:3 Other terms not defined in this document are to be interpreted according to the Webster’s Third New International Dictionary of the English Language.

1.3:4 The definitions of terms are available in Glossary.

1.3:5 A rule is a requirement imposed on the programmer, stated in normative language such as “shall”, “shall not”, “must”, “must not”, except for text under Implementation Requirements heading.

1.3:6 A fact is a requirement imposed on a conforming tool, stated in informative language such as “is”, “is not”, “can”, “cannot”.