39 | {% block body %}{% endblock %}
40 |
41 |
55 |
18 |
57 | {% endblock %}
58 |
59 | {# The blocks below, defined in the basic layout, are effectively removed from
60 | the template as we replace their contents with an empty string. #}
61 | {% block relbar1 %}{% endblock %}
62 | {% block relbar2 %}{% endblock %}
63 | {% block footer %}{% endblock %}
64 |
--------------------------------------------------------------------------------
/src/exceptions-and-errors.rst:
--------------------------------------------------------------------------------
1 | .. SPDX-License-Identifier: MIT OR Apache-2.0
2 | SPDX-FileCopyrightText: The Ferrocene Developers
3 |
4 | .. default-domain:: spec
5 |
6 | .. _fls_dzq9cdz4ibsz:
7 |
8 | Exceptions and Errors
9 | =====================
10 |
11 | .. rubric:: Legality Rules
12 |
13 | :dp:`fls_vsk4vhnuiyyz`
14 | The Rust programming language lacks exceptions and exception handlers. Instead,
15 | the language uses the following tiered error handling scheme:
16 |
17 | * :dp:`fls_ebangxc36t74`
18 | A possibly absent :t:`value` is usually represented using :t:`enum`
19 | :std:`core::option::Option`.
20 |
21 | * :dp:`fls_ckeitwiv326r`
22 | The result of a possibly erroneous computation is usually represented using
23 | :t:`enum` :std:`core::result::Result`.
24 |
25 | * :dp:`fls_eg0orgibg98m`
26 | Erroneous behavior is signaled using :t:`macro` :std:`core::panic`.
27 |
28 | :dp:`fls_ko1x0gp9e7y3`
29 | :t:`Enum` :std:`core::option::Option` indicates whether a :t:`value` is
30 | either present using :std:`core::option::Option::Some` or absent using
31 | :std:`core::option::Option::None`.
32 |
33 | :dp:`fls_gwu4cn4ziabe`
34 | :t:`Enum` :std:`core::result::Result` indicates whether a computation completed
35 | successfully and produced a :t:`value` using :std:`core::result::Result::Ok` or
36 | the computation failed with an error using :std:`core::result::Result::Err`.
37 |
38 | .. _fls_k02nt1m5fq1z:
39 |
40 | Panic
41 | -----
42 |
43 | .. rubric:: Legality Rules
44 |
45 | :dp:`fls_a554v4n0khye`
46 | A :t:`panic` is an abnormal program state caused by invoking :t:`macro`
47 | :std:`core::panic`.
48 |
49 | .. rubric:: Dynamic Semantics
50 |
51 | :dp:`fls_i9njhpte5l0t`
52 | Invoking :t:`macro` :std:`core::panic` has the following runtime effects:
53 |
54 | #. :dp:`fls_n6q7bksyn1m`
55 | Control flow halts the execution of the current thread.
56 |
57 | #. :dp:`fls_xmtt04lw517w`
58 | Control flow of the current thread resumes execution by invoking the
59 | :t:`function` subject to :t:`attribute` :c:`panic_handler`.
60 |
61 | .. rubric:: Examples
62 |
63 | .. code-block:: rust
64 |
65 | panic!("This was a terrible mistake!");
66 |
67 | .. _fls_hi1iz0gbnksi:
68 |
69 | Abort
70 | -----
71 |
72 | .. rubric:: Legality Rules
73 |
74 | :dp:`fls_9a1izu3omkbn`
75 | :t:`Abort` is the immediate termination of a program.
76 |
77 | .. rubric:: Dynamic Semantics
78 |
79 | :dp:`fls_iq6olct3rw4u`
80 | :t:`Abort` has the following runtime effects:
81 |
82 | #. :dp:`fls_wd2q6ft9yzrg`
83 | Control flow halts the execution of all threads.
84 |
85 | #. :dp:`fls_7bnrbjb0pq5n`
86 | The program terminates.
87 |
88 |
--------------------------------------------------------------------------------
/exts/ferrocene_spec_lints/require_paragraph_ids.py:
--------------------------------------------------------------------------------
1 | # SPDX-License-Identifier: MIT OR Apache-2.0
2 | # SPDX-FileCopyrightText: The Ferrocene Developers
3 |
4 | from docutils import nodes
5 | from ferrocene_spec.definitions import DefIdNode
6 |
7 |
8 | def check(app, raise_error):
9 | for document in app.env.found_docs:
10 | doctree = app.env.get_doctree(document)
11 | if document in app.config.lint_no_paragraph_ids:
12 | check_does_not_have_ids(doctree, raise_error)
13 | else:
14 | check_has_ids(doctree, raise_error)
15 |
16 |
17 | def check_has_ids(node, raise_error):
18 | is_paragraph = nodes.paragraph is type(node)
19 |
20 | if is_paragraph and nodes.section is type(node.parent):
21 | should_have_id(node, "paragraph", raise_error)
22 | elif is_paragraph and nodes.list_item is type(node.parent):
23 | should_have_id(node, "list item", raise_error)
24 | elif is_paragraph and nodes.entry is type(node.parent):
25 | if node.parent.parent.index(node.parent) == 0:
26 | should_have_id(node, "first cell of a table row", raise_error)
27 | else:
28 | should_not_have_id(
29 | node,
30 | "second or later cell of a table row",
31 | raise_error,
32 | )
33 | elif nodes.section is type(node):
34 | if not any(name.startswith("fls_") for name in node["names"]):
35 | raise_error("section should have an id", location=node)
36 | else:
37 | should_not_have_id(node, type(node).__name__, raise_error)
38 |
39 | for child in node.children:
40 | check_has_ids(child, raise_error)
41 |
42 |
43 | def check_does_not_have_ids(node, raise_error):
44 | if nodes.section is type(node):
45 | if any(name.startswith("fls_") for name in node["names"]):
46 | raise_error("section should not have an id", location=node)
47 | else:
48 | should_not_have_id(node, type(node).__name__, raise_error)
49 |
50 | for child in node.children:
51 | check_does_not_have_ids(child, raise_error)
52 |
53 |
54 | def should_have_id(node, what, raise_error):
55 | if any(is_definition(child) for child in node.children[1:]):
56 | raise_error(f"id in {what} is not the first element", location=node)
57 | elif not len(node.children) or not is_definition(node.children[0]):
58 | raise_error(f"{what} should have an id", location=node)
59 |
60 |
61 | def should_not_have_id(node, what, raise_error):
62 | if any(is_definition(child) for child in node.children):
63 | raise_error(f"{what} should not have an id", location=node)
64 |
65 |
66 | def is_definition(node):
67 | return (
68 | DefIdNode is type(node)
69 | and node["def_kind"] == "paragraph"
70 | and node["def_id"].startswith("fls_")
71 | )
72 |
--------------------------------------------------------------------------------
/src/background.rst:
--------------------------------------------------------------------------------
1 | .. SPDX-License-Identifier: MIT OR Apache-2.0
2 | SPDX-FileCopyrightText: The Rust Project Contributors
3 |
4 | .. default-domain:: spec
5 |
6 | .. informational-page::
7 |
8 | .. _fls_mLo6B3EWF50J:
9 |
10 | FLS Background
11 | ==============
12 |
13 | :dp:`fls_p7Jiyppmg0FU` The FLS is a document describing aspects of the Rust
14 | language for Rust toolchain qualification purposes.
15 |
16 | :dp:`fls_Uvf5tHsKSV19` It was created by Ferrous Systems, in an original joint
17 | effort with AdaCore, as one of the prerequisites for qualifying `Ferrocene`_, a
18 | Rust toolchain qualified for safety-critical environments. The FLS is compiled
19 | of existing Rust documentation, but presented with a rigorous structure in order
20 | to meet the requirements of qualification.
21 |
22 | :dp:`fls_J7ZI7mBXffzZ` The FLS is not intended to be used as *the* normative
23 | specification of the Rust language (see the `Rust Reference`_), nor is it meant
24 | to replace the decision-making processes of the Rust project. Any difference
25 | between the FLS and the behavior of the Rust compiler is considered an error on
26 | our part and the FLS will be updated accordingly.
27 |
28 | :dp:`fls_ffv8XSbBOMkR` The FLS text is licensed under either the ``MIT`` or
29 | ``Apache-2.0`` licenses, at your option. Individual files might have different
30 | licensing. Licensing metadata is present in each file, and the full licenses
31 | text is present in the ``LICENSES/`` directory.
32 |
33 | .. _Ferrocene: https://ferrocene.dev
34 | .. _Rust Reference: https://doc.rust-lang.org/reference/
35 |
36 | .. _fls_UMsvnuLqzd99:
37 |
38 | Acknowledging Ferrous Systems
39 | -----------------------------
40 |
41 | :dp:`fls_lmlLUAdtfCo5` The Rust Project would like to thank `Ferrous Systems`_
42 | for `donating`_ the FLS (formerly the Ferrocene Language Specification) to the
43 | Rust Project for its continued maintenance and development.
44 |
45 | :dp:`fls_FZRrMT5AYsAQ` As a brief history, the FLS is a description of the Rust
46 | programming language, developed by Ferrous Systems and `AdaCore`_ in July 2022
47 | as part of Ferrocene, a Rust compiler and toolchain designed for safety-critical
48 | and regulated industries. The FLS provides a structured and detailed reference
49 | for Rust's syntax, semantics, and behavior, serving as a foundation for
50 | verification, compliance, and standardization efforts. The FLS represented a
51 | major step toward describing Rust in a way that aligns with industry
52 | requirements, particularly in high-assurance domains. Until its transfer in
53 | April 2025, Ferrous Systems had been the sole steward of the FLS since July
54 | 2023.
55 |
56 | .. _Ferrous Systems: https://ferrous-systems.com
57 | .. _donating: https://rustfoundation.org/media/ferrous-systems-donates-ferrocene-language-specification-to-rust-project/
58 | .. _AdaCore: https://www.adacore.com
--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/change.yml:
--------------------------------------------------------------------------------
1 | # SPDX-License-Identifier: MIT OR Apache-2.0
2 | # SPDX-FileCopyrightText: The Rust Project Developers
3 |
4 | name: Change
5 | description: File a change for the FLS
6 | title: "[Change]: "
7 | labels: ["change intake"]
8 | assignees:
9 | - PLeVasseur
10 | body:
11 | - type: markdown
12 | attributes:
13 | value: |
14 | Thank you for contributing a change!
15 | - type: input
16 | id: title
17 | attributes:
18 | label: Change description
19 | description: Description of what is intended to be changed
20 | placeholder: Fix description of lexing due to xx
21 | validations:
22 | required: true
23 | - type: dropdown
24 | id: area
25 | attributes:
26 | label: Area
27 | description: Which part of the language does this fall under?
28 | options:
29 | - ABI
30 | - async / await
31 | - attributes
32 | - closures
33 | - conditional compilation
34 | - const evaluation
35 | - conventions
36 | - destructors
37 | - diagnostics
38 | - "edition: 2015"
39 | - "edition: 2018"
40 | - "edition: 2021"
41 | - "edition: 2024"
42 | - editions
43 | - generics
44 | - glossary
45 | - grammar
46 | - inline assembly
47 | - linkage
48 | - macros
49 | - method call
50 | - panic
51 | - patterns
52 | - proc macros
53 | - resolution (names, paths, namespaces, preludes, ...)
54 | - types
55 | - type inference
56 | - type layout
57 | - undefined behavior
58 | - N/A
59 | validations:
60 | required: true
61 | - type: dropdown
62 | id: category
63 | attributes:
64 | label: Category
65 | description: What kind of change is this?
66 | options:
67 | - Bug
68 | - Formatting
69 | - Improvement to non-prose section
70 | - Language cleanup
71 | - New content
72 | - Other
73 | validations:
74 | required: true
75 | - type: input
76 | id: fls-id
77 | attributes:
78 | label: FLS Paragraph ID
79 | description: |
80 | The Paragraph ID from the FLS corresponding to what this Guideline covers.
81 | Easiest way to obtain this is to navigate to the
82 | [FLS](https://rust-lang.github.io/fls), right click a section ID
83 | (e.g. `4.2:2`), inspect, and then find it in the pane which opens in
84 | your browser.
85 |
86 | **Note**: New content need not fill this in.
87 | placeholder: fls_deaddeadbeef
88 | validations:
89 | required: false
90 | - type: textarea
91 | id: change-description
92 | attributes:
93 | label: Change description (extended)
94 | description: |
95 | A longer description of the intended change, including background and
96 | details on in what way the FLS is improved by the change.
97 | placeholder: Fix description of lexing due to xx, since under conditions yy it's possible for zz to occur.
98 | validations:
99 | required: true
100 |
--------------------------------------------------------------------------------
/exts/ferrocene_spec/definitions/paragraphs.py:
--------------------------------------------------------------------------------
1 | # SPDX-License-Identifier: MIT OR Apache-2.0
2 | # SPDX-FileCopyrightText: The Ferrocene Developers
3 |
4 | from .. import utils
5 | from collections import defaultdict
6 | from docutils import nodes
7 | import hashlib
8 | import sphinx
9 |
10 |
11 | ROLE = "p"
12 | NAME = "paragraph"
13 | PRETTY_NAME = "paragraph"
14 |
15 |
16 | class Paragraph:
17 | def __init__(self, id, document, section_anchor, section_id, plaintext, sequential):
18 | self.id = id
19 | self.document = document
20 | self.section_anchor = section_anchor
21 | self.section_id = section_id
22 | self.plaintext = plaintext
23 | self.sequential = sequential
24 |
25 | def number(self, env):
26 | section = ".".join(
27 | str(n) for n in env.toc_secnumbers[self.document][self.section_anchor]
28 | )
29 | return f"{section}:{self.sequential}"
30 |
31 | def anchor(self):
32 | return self.id
33 |
34 | def include_in_search(self):
35 | return False
36 |
37 | def display_name(self, env):
38 | return f"{self.number(env)} {self.content_checksum()}"
39 |
40 | def content_checksum(self):
41 | sha256 = hashlib.sha256()
42 | sha256.update(self.plaintext.encode("utf-8"))
43 | return sha256.hexdigest()
44 |
45 |
46 | def collect_items_in_document(app, nodes_to_collect):
47 | ids = defaultdict(lambda: 1)
48 | for node in nodes_to_collect:
49 | section_node = find_parent_of_type(node, nodes.section)
50 | if section_node is None:
51 | raise RuntimeError(f"could not find section for {node!r}")
52 |
53 | try:
54 | section_id, section_anchor = utils.section_id_and_anchor(section_node)
55 | except utils.NoSectionIdError:
56 | logger = sphinx.util.logging.getLogger(__name__)
57 | logger.warn(
58 | "paragraph inside a section that doesn't have an id starting with fls_",
59 | location=node,
60 | )
61 | return
62 |
63 | yield Paragraph(
64 | id=node["def_id"],
65 | document=app.env.docname,
66 | section_anchor=section_anchor,
67 | section_id=section_id,
68 | plaintext=plaintext_paragraph(node),
69 | sequential=ids[section_id],
70 | )
71 | ids[section_id] += 1
72 |
73 |
74 | def replace_id_node(app, node, paragraph):
75 | new = nodes.inline()
76 | new["ids"].append(paragraph.id)
77 | new["classes"].append("spec-paragraph-id")
78 | new += nodes.Text(paragraph.number(app.env))
79 | node.replace_self(new)
80 |
81 |
82 | def create_ref_node(env, text, item):
83 | if item is not None:
84 | return nodes.emphasis("", item.number(env))
85 | else:
86 | return nodes.emphasis("", "Paragraph " + text)
87 |
88 |
89 | def plaintext_paragraph(node):
90 | paragraph = find_parent_of_type(node, nodes.paragraph)
91 | if paragraph is None:
92 | paragraph = node
93 | return paragraph.astext().replace("\n", " ")
94 |
95 |
96 | def find_parent_of_type(node, ty):
97 | cursor = node
98 | while cursor is not None:
99 | if isinstance(cursor, ty):
100 | return cursor
101 | cursor = cursor.parent
102 | return None
103 |
--------------------------------------------------------------------------------
/CONTRIBUTING.rst:
--------------------------------------------------------------------------------
1 | .. SPDX-License-Identifier: MIT OR Apache-2.0
2 | SPDX-FileCopyrightText: The Ferrocene Developers
3 | SPDX-FileCopyrightText: The Rust Project Contributors
4 |
5 | ====================================================
6 | Contributing to the FLS
7 | ====================================================
8 |
9 | The FLS is released publicly under an open source license, specifically MIT and
10 | Apache 2.0.
11 |
12 | The specification is still a work in progress, and while we're open to
13 | contributions, we want to manage your expectations on how much we'll be able to
14 | interact with the community in this repository:
15 |
16 | * Any change made to the specification text causes extra work for us behind the
17 | scenes, as we have other tooling required for qualification that consumes the
18 | specification text.
19 |
20 | * Our resources are limited when it comes to reviewing PRs, especially large
21 | ones.
22 |
23 | We'll try our best to review changes proposed by the community, but we might not
24 | be able to review all of them (or they might be out of date once we get to
25 | them). If there are changes you'd like to make, we recommend opening an issue
26 | beforehand, so that we can provide feedback on whether we'll be able to merge
27 | the changes.
28 |
29 | We've all dealt with those open source projects that feel open in name only, and
30 | have big patches and history-free source drops appearing from behind the walls
31 | of some large organization. We don't like that, and we're not going to do that.
32 | But please bear with us until we have the capacity to accept all external
33 | contributions.
34 |
35 | This introduction was inspired by Oxide Computer Company's `Hubris
36 | contribution guidelines
37 |
19 |
20 |
21 |  }})
22 |
25 |
29 |
36 |
37 |
22 | {{ shorttitle }}
23 | 24 |
38 |
56 |